keysearch.py
psychiatry/keysearch.py · 126 line(s) · py
#!/usr/bin/env python3
"""keysearch.py -- ping GitHub to check whether the local Secret.key matches
the one published in the repository.
Invoked from the SLeeLa terminal as:
$> SLeeLa keysearch
It performs a **read-only HTTPS GET** of the repository's Secret.key and compares
it to the local copy. To avoid ever transmitting or logging the key material, the
comparison is done by **SHA-256 digest**, not by sending the raw key anywhere:
* the local key is hashed locally;
* the remote key is fetched and hashed;
* only the two 64-hex-char digests are compared and (optionally) shown.
Result:
MATCH local and remote keys are byte-identical (same SHA-256)
MISMATCH both present but differ
NOT FOUND the remote key could not be fetched (missing/offline/HTTP error)
ERROR the local key is missing or unreadable
Safety stance (matches the bonding collar / OS-floor reporter):
* GET only -- it never uploads or POSTs the secret anywhere.
* Digest comparison -- the raw key never leaves the machine and is never logged.
* Fail closed -- any network/HTTP problem yields NOT FOUND, never a false MATCH.
Configuration:
SLEELA_KEY_URL override the remote URL (default: the repo's main branch raw URL)
SLEELA_KEY_PATH override the local key path (default: alongside this script)
"""
from __future__ import annotations
import hashlib
import os
import sys
from pathlib import Path
from typing import Callable, Optional, Tuple
DEFAULT_URL = "https://raw.githubusercontent.com/mearvk/SLeeLa/master/psychiatry/Secret.key"
DEFAULT_LOCAL = Path(__file__).resolve().parent / "Secret.key"
# Transport is injectable so tests can run without real network access.
# Signature: fetch(url) -> (status_int, body_bytes). Raise on transport failure.
Fetch = Callable[[str], Tuple[int, bytes]]
def _urllib_fetch(url: str) -> Tuple[int, bytes]:
import urllib.request
import urllib.error
req = urllib.request.Request(url, method="GET",
headers={"User-Agent": "sleela-keysearch"})
try:
with urllib.request.urlopen(req, timeout=3) as resp:
return (resp.status, resp.read())
except urllib.error.HTTPError as e:
return (e.code, b"")
def _sha256_hex(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def _normalize(raw: bytes) -> bytes:
# Compare on the key's hex content, ignoring a trailing newline / surrounding
# whitespace so a stored "...\n" matches a fetched "..." of the same digits.
return raw.strip()
def keysearch(url: Optional[str] = None,
local_path: Optional[Path] = None,
*,
fetch: Optional[Fetch] = None) -> Tuple[str, str]:
"""Return (result, detail). result in {MATCH, MISMATCH, NOT FOUND, ERROR}."""
url = url or os.environ.get("SLEELA_KEY_URL", DEFAULT_URL)
local_path = Path(local_path or os.environ.get("SLEELA_KEY_PATH", DEFAULT_LOCAL))
# Local key
try:
local = _normalize(local_path.read_bytes())
except OSError as e:
return ("ERROR", f"local key unreadable: {e}")
if not local:
return ("ERROR", f"local key is empty: {local_path}")
local_digest = _sha256_hex(local)
# Remote key (GET only; fail closed on any problem)
send = fetch or _urllib_fetch
try:
status, body = send(url)
except Exception as e: # noqa: BLE001 -- fail closed on any transport error
return ("NOT FOUND", f"fetch failed: {e}")
if status < 200 or status >= 300 or not body:
return ("NOT FOUND", f"remote unavailable (HTTP {status})")
remote_digest = _sha256_hex(_normalize(body))
if local_digest == remote_digest:
return ("MATCH", f"sha256={local_digest} ({len(local)} hex digits)")
return ("MISMATCH", f"local={local_digest} remote={remote_digest}")
def main(argv=None) -> int:
argv = list(sys.argv[1:] if argv is None else argv)
startup = "--startup" in argv
argv = [a for a in argv if a != "--startup"]
url = argv[0] if argv else None
result, detail = keysearch(url=url)
if startup:
# Startup mode is deliberately quiet on a match and non-fatal for all
# other states. Only a small status note is emitted when the check cannot
# verify the local key against the published master copy.
if result == "MISMATCH":
print("SLeeLa: Secret.key startup check mismatch", file=sys.stderr)
elif result in ("NOT FOUND", "ERROR"):
print("SLeeLa: Secret.key startup check unavailable", file=sys.stderr)
return 0
print(f"SLeeLa keysearch: {result}")
print(f" {detail}")
# Exit code: 0 match, 1 mismatch, 2 not found, 3 error (scriptable).
return {"MATCH": 0, "MISMATCH": 1, "NOT FOUND": 2, "ERROR": 3}.get(result, 3)
if __name__ == "__main__":
raise SystemExit(main())