hakodesh 0.1.0__py3-none-any.whl

hakodesh/__init__.py

@@ -0,0 +1,27 @@
+"""hakodesh — empty book, mint as you go."""
+
+from .akashic import inscribe, verify_chain
+from .catalog import catalog as list_catalog
+from .catalog import route
+from .combo import cast as combo_cast
+from .combo import seal as combo_seal
+from .enchant import bind, lift
+from .events import make_event, validate_event
+from .grimoire import seal as grimoire_seal
+from .ward import unlock
+
+__version__ = "0.1.0"
+__all__ = [
+    "list_catalog",
+    "route",
+    "make_event",
+    "validate_event",
+    "inscribe",
+    "verify_chain",
+    "grimoire_seal",
+    "bind",
+    "lift",
+    "unlock",
+    "combo_seal",
+    "combo_cast",
+]

hakodesh/__main__.py

@@ -0,0 +1,4 @@
+from hakodesh.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hakodesh/akashic.py

@@ -0,0 +1,449 @@
+"""Akashic HMAC chain under HAKODESH_HOME/akashic."""
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import hmac
+import json
+import os
+import re
+import uuid
+from pathlib import Path
+
+from . import events, home as paths, keys
+
+SCHEMA = "1.0.0"
+CHAIN_ALG = "hmac-sha256"
+_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+_SENSITIVE_RECEIPT_KEY = re.compile(
+    r"(?:^|_)(?:token|secret|password|authorization|api_?key|private_?key|"
+    r"webhook_?url|credential)(?:$|_)",
+    re.IGNORECASE,
+)
+_SENSITIVE_RECEIPT_VALUE = (
+    re.compile(r"https://(?:canary\.)?discord(?:app)?\.com/api/webhooks/", re.I),
+    re.compile(r"\bBearer\s+[A-Za-z0-9._~+/=-]{12,}", re.I),
+    re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),
+    re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
+    re.compile(r"\b[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY)\s*="),
+)
+
+
+def _safe(name: str) -> str:
+    return _SAFE.sub("-", str(name))
+
+
+def events_path(root: Path | None = None) -> Path:
+    return paths.akashic_dir(root) / "events.jsonl"
+
+
+def events_head_path(root: Path | None = None) -> Path:
+    return paths.akashic_dir(root) / "events_head.json"
+
+
+def record_path(root: Path | None = None) -> Path:
+    return paths.akashic_dir(root) / "akashic_record.json"
+
+
+def receipt_dir(name: str, root: Path | None = None) -> Path:
+    return paths.receipts_dir(root) / _safe(name)
+
+
+def now_iso() -> str:
+    import time
+
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def new_run_id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def key_fp(key: bytes) -> str:
+    return hashlib.sha256(key).hexdigest()[:16]
+
+
+def redact_sensitive(value, key=None, depth=0):
+    if key and _SENSITIVE_RECEIPT_KEY.search(str(key)):
+        return "[REDACTED]"
+    if depth > 12:
+        return "[REDACTED:DEPTH]"
+    if isinstance(value, dict):
+        return {
+            str(item_key): redact_sensitive(item, key=str(item_key), depth=depth + 1)
+            for item_key, item in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [redact_sensitive(item, depth=depth + 1) for item in value]
+    if isinstance(value, str):
+        if any(pattern.search(value) for pattern in _SENSITIVE_RECEIPT_VALUE):
+            return "[REDACTED]"
+        return value
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    return str(value)
+
+
+def _event_body(line: dict) -> str:
+    return json.dumps(
+        {k: v for k, v in line.items() if k != "chain"},
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+    )
+
+
+def event_hash(prev: str, line: dict) -> str:
+    return hashlib.sha256((prev + _event_body(line)).encode()).hexdigest()
+
+
+def event_sig(prev: str, line: dict, key: bytes) -> str:
+    return hmac.new(key, (prev + _event_body(line)).encode(), hashlib.sha256).hexdigest()
+
+
+def _head_mac(pid, lines, tail_self, key):
+    return hmac.new(key, f"{pid}:{lines}:{tail_self}".encode(), hashlib.sha256).hexdigest()
+
+
+def _head_mac2(pid, lines, tail_self, key_fp_, seal_offset, legacy_anchor, signed_hwm, key):
+    msg = f"{pid}:{lines}:{tail_self}:{key_fp_}:{seal_offset}:{legacy_anchor}:{signed_hwm}"
+    return hmac.new(key, msg.encode(), hashlib.sha256).hexdigest()
+
+
+def _atomic_write(path: Path, obj) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name("%s.tmp.%d.%s" % (path.name, os.getpid(), uuid.uuid4().hex[:8]))
+    try:
+        tmp.write_text(json.dumps(obj, indent=2, default=str))
+        os.replace(str(tmp), str(path))
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+
+
+def _read_head(root: Path | None = None):
+    hp = events_head_path(root)
+    if not hp.is_file():
+        return None
+    try:
+        head = json.loads(hp.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    return head if isinstance(head, dict) else None
+
+
+def _write_head(lines, tail_self, key, seal_offset, legacy_anchor, signed_hwm, root=None):
+    pid = "shared"
+    fp = key_fp(key)
+    doc = {
+        "partition": pid,
+        "lines": lines,
+        "self": tail_self,
+        "seal_offset": seal_offset,
+        "legacy_anchor": legacy_anchor,
+        "key_fp": fp,
+        "signed_hwm": signed_hwm,
+        "alg": CHAIN_ALG,
+        "mac": _head_mac(pid, lines, tail_self, key),
+        "mac2": _head_mac2(pid, lines, tail_self, fp, seal_offset, legacy_anchor, signed_hwm, key),
+    }
+    _atomic_write(events_head_path(root), doc)
+
+
+def _tail_line(path: Path):
+    try:
+        with open(path, "rb") as handle:
+            handle.seek(0, os.SEEK_END)
+            end = handle.tell()
+            if end == 0:
+                return None
+            size = min(end, 65536)
+            handle.seek(end - size)
+            block = handle.read(size)
+        for raw in reversed(block.split(b"\n")):
+            if raw.strip():
+                return raw.decode("utf-8", "replace")
+        return None
+    except OSError:
+        return None
+
+
+def _seal_offset_and_anchor(path: Path):
+    off = 0
+    digest = hashlib.sha256()
+    try:
+        with open(path, "rb") as handle:
+            for raw in handle:
+                stripped = raw.strip()
+                if not stripped:
+                    continue
+                try:
+                    obj = json.loads(stripped)
+                except ValueError:
+                    break
+                if isinstance(obj, dict) and isinstance(obj.get("chain"), dict):
+                    break
+                off += 1
+                digest.update(raw)
+    except OSError:
+        return 0, ""
+    return off, (digest.hexdigest() if off else "")
+
+
+def _seal_context(ep: Path, root: Path | None = None):
+    tail = _tail_line(ep)
+    tail_chain = None
+    if tail:
+        try:
+            parsed = json.loads(tail)
+            if isinstance(parsed, dict) and isinstance(parsed.get("chain"), dict):
+                tail_chain = parsed["chain"]
+        except ValueError:
+            tail_chain = None
+    if root is None:
+        root = ep.parent.parent
+    head = _read_head(root)
+    if tail_chain and isinstance(tail_chain.get("self"), str):
+        prev = tail_chain["self"]
+        if head:
+            return (
+                prev,
+                int(head.get("seal_offset") or 0),
+                str(head.get("legacy_anchor") or ""),
+                int(head.get("signed_hwm") or 0),
+                int(head.get("lines") or 0),
+            )
+        off, anchor = _seal_offset_and_anchor(ep)
+        n = sum(1 for _ in open(ep)) if ep.is_file() else off
+        return prev, off, anchor, 0, n
+    off, anchor = _seal_offset_and_anchor(ep)
+    prev = anchor if off else "genesis"
+    return prev, off, anchor, 0, off
+
+
+def _acquire_lock(root: Path | None = None):
+    fd = None
+    try:
+        lp = paths.akashic_dir(root) / ".akashic.lock"
+        lp.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(str(lp), os.O_CREAT | os.O_RDWR, 0o600)
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        return fd, None
+    except OSError as exc:
+        if fd is not None:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        return None, str(exc)
+
+
+def _release_lock(fd):
+    if fd is None:
+        return
+    try:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+    except OSError:
+        pass
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+
+
+def append_event(event: dict, root: Path | None = None) -> dict:
+    """Validate, HMAC-chain, append. Returns the stored line plus chain."""
+    validated = events.validate_event({k: v for k, v in event.items() if k != "chain"})
+    paths.ensure_layout(root)
+    ep = events_path(root)
+    fd, err = _acquire_lock(root)
+    out = {"ok": True, "event_id": validated["event_id"], "errors": []}
+    if err:
+        out["ok"] = False
+        out["errors"].append(err)
+        return out
+    try:
+        prev, seal_offset, legacy_anchor, prev_hwm, base_lines = _seal_context(ep, root)
+        line = dict(validated)
+        self_ = event_hash(prev, line)
+        chain = {"prev": prev, "self": self_}
+        key = keys.chain_key(create=True, root=root)
+        if key:
+            chain["alg"] = CHAIN_ALG
+            chain["sig"] = event_sig(prev, line, key)
+        else:
+            out["errors"].append("chain: keystore unusable — event appended UNSIGNED")
+        line["chain"] = chain
+        ep.parent.mkdir(parents=True, exist_ok=True)
+        with open(ep, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(line, separators=(",", ":"), default=str) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        if key:
+            signed = base_lines - seal_offset + 1
+            _write_head(
+                base_lines + 1,
+                self_,
+                key,
+                seal_offset,
+                legacy_anchor,
+                max(prev_hwm, signed),
+                root=root,
+            )
+        out["chain"] = chain
+        out["event"] = line
+        return out
+    finally:
+        _release_lock(fd)
+
+
+def write_receipt(name: str, receipt: dict, root: Path | None = None) -> Path:
+    folder = receipt_dir(name, root)
+    folder.mkdir(parents=True, exist_ok=True)
+    run_id = receipt.get("run_id") or new_run_id()
+    path = folder / ("%s__%s.json" % (now_iso().replace(":", ""), run_id))
+    path.write_text(json.dumps(redact_sensitive(receipt), indent=2, default=str))
+    return path
+
+
+def inscribe(name: str, receipt: dict, *, event: dict | None = None, root: Path | None = None) -> dict:
+    receipt = dict(receipt)
+    run_id = receipt.get("run_id") or new_run_id()
+    receipt["run_id"] = run_id
+    path = write_receipt(name, receipt, root)
+    out = {"ok": True, "receipt": str(path), "run_id": run_id}
+    if event:
+        actor = events.default_actor(spell=name)
+        built = events.make_event(
+            actor=actor,
+            kind=event.get("kind") or "spell.cast.completed",
+            subject={"product": "hakodesh", "spell": name},
+            state=event.get("state") or ("completed" if receipt.get("ok", True) else "failed"),
+            summary=event.get("summary") or ("cast %s" % name),
+            idempotency_key=event.get("idempotency_key") or ("cast:%s:%s" % (name, run_id)),
+            provenance=event.get("provenance") or {"surface": "hakodesh"},
+            notification_policy="none",
+            run_id=run_id,
+        )
+        chained = append_event(built, root)
+        out["event_id"] = chained.get("event_id")
+        out["chain"] = chained.get("chain")
+        out["event_ok"] = chained.get("ok")
+        if chained.get("errors"):
+            out["errors"] = chained["errors"]
+    return out
+
+
+def verify_chain(strict=False, root: Path | None = None) -> dict:
+    ep = events_path(root)
+    out = {
+        "ok": True,
+        "partition": "shared",
+        "events": str(ep),
+        "lines": 0,
+        "legacy": 0,
+        "signed": 0,
+        "sealed": True,
+        "head_anchor": "absent",
+        "problems": [],
+    }
+    try:
+        raw = [line for line in ep.read_text().splitlines() if line.strip()] if ep.is_file() else []
+    except OSError as exc:
+        out["ok"] = False
+        out["problems"].append("spine unreadable: %s" % exc)
+        return out
+    lines = []
+    for i, line in enumerate(raw):
+        try:
+            lines.append(json.loads(line))
+        except ValueError:
+            out["ok"] = False
+            out["problems"].append("line %d: unparseable" % i)
+            return out
+    out["lines"] = len(lines)
+    key = keys.chain_key(create=False, root=root)
+    head = _read_head(root)
+    off, anchor = _seal_offset_and_anchor(ep)
+    out["legacy"] = off
+    if head and key is not None and head.get("key_fp") and head.get("key_fp") != key_fp(key):
+        out["ok"] = False
+        out["problems"].append("chain key rotated")
+        return out
+    if off == len(lines):
+        out["sealed"] = False
+        if strict:
+            out["ok"] = False
+            out["problems"].append("spine is entirely unsealed")
+        return out
+    prev = anchor if off else "genesis"
+    signed = 0
+    for idx in range(off, len(lines)):
+        entry = lines[idx]
+        chain = entry.get("chain")
+        if not isinstance(chain, dict) or not isinstance(chain.get("self"), str) or not isinstance(chain.get("prev"), str):
+            out["ok"] = False
+            out["problems"].append("line %d: missing chain" % idx)
+            return out
+        if chain["prev"] != prev or chain["self"] != event_hash(prev, entry):
+            out["ok"] = False
+            out["problems"].append("line %d: hash linkage broken" % idx)
+            return out
+        sig = chain.get("sig")
+        if sig:
+            signed += 1
+            if key is None:
+                out["ok"] = False
+                out["problems"].append("line %d: signed but chain key unavailable" % idx)
+                return out
+            if not hmac.compare_digest(sig, event_sig(prev, entry, key)):
+                out["ok"] = False
+                out["problems"].append("line %d: keyed MAC mismatch" % idx)
+                return out
+        prev = chain["self"]
+    out["signed"] = signed
+    hp = events_head_path(root)
+    if hp.is_file():
+        pid = "shared"
+        tail_self = lines[-1].get("chain", {}).get("self")
+        if head is None or key is None:
+            out["ok"] = False
+            out["problems"].append("head anchor unreadable or chain key unavailable")
+        elif not hmac.compare_digest(
+            _head_mac(pid, head.get("lines"), head.get("self") or "", key),
+            head.get("mac") or "",
+        ):
+            out["ok"] = False
+            out["problems"].append("head MAC invalid")
+        elif head.get("lines") != len(lines) or head.get("self") != tail_self:
+            out["ok"] = False
+            out["problems"].append("spine does not match the head anchor")
+        else:
+            out["head_anchor"] = "verified"
+    elif signed or strict:
+        out["ok"] = False
+        out["problems"].append("events_head.json missing")
+    out["tamper_evidence"] = (
+        "keyed (HMAC-SHA256)" if out["ok"] and signed else "FAILED" if not out["ok"] else "hash-linkage only"
+    )
+    return out
+
+
+def tail_events(n=20, root: Path | None = None):
+    ep = events_path(root)
+    try:
+        with open(ep) as handle:
+            lines = handle.readlines()[-int(n) :]
+        out = []
+        for line in lines:
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return out
+    except OSError:
+        return []

hakodesh/catalog.py

@@ -0,0 +1,103 @@
+"""Discover user-book artifacts. Kernel commands are not catalog entries."""
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+from . import home as paths
+
+KERNEL = (
+    "mint",
+    "catalog",
+    "route",
+    "invoke",
+    "akashic",
+    "grimoire",
+    "grimoire-seal",
+    "enchant",
+    "ward",
+    "combo",
+)
+
+
+def _load_spell(path: Path):
+    spec = importlib.util.spec_from_file_location("hakodesh_book_%s" % path.stem, path)
+    if spec is None or spec.loader is None:
+        return None
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    desc = getattr(mod, "SPELL", None)
+    run = getattr(mod, "run", None)
+    if not (isinstance(desc, dict) and callable(run)):
+        return None
+    name = desc.get("name") or path.stem.replace("_", "-")
+    return {"name": name, "kind": "spell", "path": str(path), "descriptor": desc, "run": run}
+
+
+def _load_json(path: Path, kind: str):
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    name = data.get("name") or path.stem
+    return {"name": name, "kind": kind, "path": str(path), "descriptor": data, "run": None}
+
+
+def user_artifacts(root: Path | None = None):
+    root = paths.ensure_layout(root)
+    items = []
+    for path in sorted(paths.book_dir("spell", root).glob("*.py")):
+        loaded = _load_spell(path)
+        if loaded:
+            items.append(loaded)
+    for kind in ("enchantment", "ward", "combo"):
+        for path in sorted(paths.book_dir(kind, root).glob("*.json")):
+            loaded = _load_json(path, kind)
+            if loaded:
+                items.append(loaded)
+    return items
+
+
+def catalog(root: Path | None = None):
+    items = user_artifacts(root)
+    return {
+        "ok": True,
+        "count": len(items),
+        "artifacts": [
+            {
+                "name": item["name"],
+                "kind": item["kind"],
+                "path": item["path"],
+                "purpose": (item.get("descriptor") or {}).get("purpose", ""),
+            }
+            for item in items
+        ],
+        "kernel": list(KERNEL),
+    }
+
+
+def registry(root: Path | None = None):
+    return {item["name"]: item for item in user_artifacts(root)}
+
+
+def route(intent: str, root: Path | None = None):
+    intent = (intent or "").lower()
+    scored = []
+    haystacks = [(name, "kernel command %s" % name, "kernel") for name in KERNEL]
+    for item in user_artifacts(root):
+        desc = item.get("descriptor") or {}
+        hay = "%s %s %s" % (item["name"], desc.get("purpose", ""), " ".join(desc.get("tags") or []))
+        haystacks.append((item["name"], hay, item["kind"]))
+    for name, hay, kind in haystacks:
+        score = sum(1 for word in intent.split() if word and word in hay.lower())
+        if score:
+            scored.append((score, name, kind))
+    scored.sort(reverse=True)
+    return {
+        "ok": True,
+        "intent": intent,
+        "matches": [{"name": name, "score": score, "kind": kind} for score, name, kind in scored[:8]],
+    }