SourceIndex 0.1.0__py3-none-any.whl

sourceindex/cli/install.py

@@ -0,0 +1,378 @@
+"""Init-time scaffolding installed into the user's repo.
+
+Four artifacts share this module — all are templates + writers for files
+that ``sourceindex init`` drops into the working repo:
+
+- ``.gitignore`` entry for ``.sourceindex/``.
+- ``.githooks/post-commit`` running ``sourceindex update``.
+- ``.claude/agents/sourceindex-agent.md`` (subagent mode) or ``.mcp.json``
+  (MCP mode).
+- A "Codebase Search" / "Workflow" section appended to ``CLAUDE.md``.
+"""
+
+import json
+import stat
+import subprocess
+from pathlib import Path
+
+from ..lib.log import get_logger
+
+_log = get_logger(__name__)
+
+
+GITIGNORE_ENTRY = ".sourceindex/"
+
+
+UPDATE_SCRIPT = """#!/usr/bin/env bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+sourceindex update --repo-root "$REPO_ROOT" &
+"""
+
+# Git hooks that should trigger an index refresh. All are symlinks to the
+# shared _update.sh, so adding a new hook is a one-line append here.
+HOOKS = ("post-commit", "post-checkout", "post-merge")
+
+# MCP mode is currently broken — DO NOT USE. The MCP detour (ToolSearch +
+# search_index roundtrip) invalidates the prompt cache on turn 2, which negates
+# the cache_input_tokens savings that the agent path relies on. Kept here for
+# now as a reference / for future debugging; use --mode agent (the default).
+MCP_CONFIG = {
+    "mcpServers": {
+        "sourceindex-server": {
+            "type": "stdio",
+            "command": "sourceindex",
+            "args": ["serve"],
+        }
+    }
+}
+
+
+CLAUDE_MD_SECTION_MCP = """## Workflow
+Before implementing any feature or making code changes, always use the
+sourceindex-server MCP tool to get the implementation guide. Follow the
+exact file paths and patterns it returns.
+"""
+
+CLAUDE_MD_MARKER_MCP = "sourceindex-server MCP tool"
+
+
+CLAUDE_MD_SECTION_AGENT = """## Codebase Search
+- The `sourceindex` subagent handles all codebase exploration — for implementation, debugging, planning, inventories, design suggestions, or any "where/how/what" question about this codebase, the first action is `Agent(subagent_type="sourceindex", ...)`.
+- When calling the subagent, set its `prompt` to the user's request lightly polished — fix grammar or replace pronouns if needed, but do not restructure, expand into bullet lists, or wrap with "I need:..." prefaces. The Pass-1a/1b search performs best on the user's original phrasing.
+- Never call `Agent(subagent_type="Explore")` for codebase questions in this repo — the SourceIndex roadmap supersedes Explore here. Same goes for `general-purpose` agents tasked with codebase research.
+- Never use Read/Grep/Glob directly before running the sourceindex subagent first.
+- Trust the search results — implement based on the patterns it returns.
+"""
+
+CLAUDE_MD_MARKER_AGENT = "`sourceindex` subagent handles all codebase exploration"
+
+
+CLAUDE_MD_HEADER = """# CLAUDE.md
+
+This file provides guidance to Claude Code when working in this repository.
+
+"""
+
+
+SUBAGENT_FILENAME = "sourceindex-agent.md"
+
+SUBAGENT_CONFIG = """---
+name: sourceindex
+description: MUST BE USED for ANY question that requires understanding this codebase — implementing features, fixing bugs, refactoring, planning, design suggestions, inventories ("map every command", "list all callers"), "how does X work" questions, or any answer that needs to cite specific files/functions. Prefer this over the built-in Explore subagent and over direct Read/Grep/Glob; the SourceIndex roadmap is the single entry point for codebase exploration in this repo. This agent is responsible for searching the codebase using the sourceindex tool and reporting the results.
+tools: Bash
+---
+You are a codebase search agent. When invoked:
+1. You will receive a query about the task that you are working on. Pass the query to the sourceindex tool executable directly.
+2. Run immediately:
+
+```bash
+sourceindex search --query "<your query here>" --repo-root .
+```
+
+3. **Return the bash command's stdout verbatim — do NOT summarize, paraphrase, or analyze it.** The parent agent needs the full `=== CODEBASE ROADMAP …` block (including line ranges and import hints) in its prompt cache; any synthesis on top breaks the downstream savings telemetry and loses fidelity. Wrap the output in a fenced code block and stop.
+
+If `sourceindex search` errors out, report the error verbatim with file names and line numbers. Do not fix anything — just report.
+"""
+
+
+RESTRICT_HOOK_FILENAME = "restrict-sourceindex-bash.sh"
+
+# Resolved by Claude Code at hook-exec time. ${CLAUDE_PROJECT_DIR} expands to
+# the project root (where .claude/ lives), so the registration stays portable
+# across clones/machines — do NOT bake in an absolute path here.
+RESTRICT_HOOK_COMMAND = "${CLAUDE_PROJECT_DIR}/.claude/hooks/" + RESTRICT_HOOK_FILENAME
+
+# A PreToolUse gate that keeps the `sourceindex` subagent single-shot. Embedded
+# verbatim (raw string preserves the inner triple-quotes and "\n" literals) so
+# init is self-contained — no external file to drift or go missing.
+RESTRICT_HOOK_SCRIPT = r'''#!/usr/bin/env python3
+"""PreToolUse hook that keeps the `sourceindex` subagent single-shot.
+
+The subagent's only job is to run `sourceindex search ...` once and return its
+output. This hook hard-restricts it to exactly that: a single `Bash` call whose
+program is `sourceindex search` (optionally prefixed with `VAR=value` env
+assignments). Any other tool, any other program, or shell chaining/redirection
+appended after the search is blocked.
+
+Why a hook and not the frontmatter `tools:` allowlist: in bypassPermissions
+sessions (`claude --dangerously-skip-permissions`) the subagent `tools:` field
+is not enforced, and even in default mode it does not scope Bash to a single
+command. PreToolUse hooks fire and can block in every mode, so this is the
+reliable backstop — without it the subagent can wander off and run the whole
+task by hand via Bash (read files, edit source, pip install, run tests),
+inflating cost and corrupting the workspace.
+
+Scoping: registered with matcher ".*" so it fires for every tool call;
+`agent_type` (the calling subagent's frontmatter `name`, absent for main-agent
+calls) gates it to the sourceindex subagent — the main agent and all other
+subagents pass through untouched.
+
+Validation is shlex-token based, not raw-string: queries are passed verbatim as
+the quoted `--query` value and routinely contain shell metacharacters (`;`,
+`|`, backticks, `<`, `>`). Inside the quotes those stay within one token and
+are allowed; genuine chaining operators appear as standalone tokens and are
+blocked.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import sys
+
+ENV_ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+SHELL_OPERATORS = {
+    ";", "|", "||", "&", "&&", ">", ">>", ">|",
+    "<", "<<", "<<<", "&>", "&>>", ">&", "|&",
+}
+
+
+def violation(tool_name: str, command: str) -> str | None:
+    """Return a deny reason, or None if the call is allowed."""
+    if tool_name != "Bash":
+        return "only Bash running `sourceindex search ...` is permitted"
+    try:
+        tokens = shlex.split(command)
+    except ValueError as exc:
+        return f"unparseable command: {exc}"
+
+    i = 0
+    while i < len(tokens) and ENV_ASSIGN.match(tokens[i]):
+        i += 1  # allow a leading `VAR=value ...` env prefix
+
+    if i + 1 >= len(tokens) or tokens[i] != "sourceindex" or tokens[i + 1] != "search":
+        return "only `[VAR=value ...] sourceindex search ...` is allowed"
+
+    for tok in tokens[i + 2:]:
+        if tok in SHELL_OPERATORS:
+            return f"shell operator {tok!r} not permitted (no chaining/redirection)"
+    return None
+
+
+def main() -> int:
+    payload = json.load(sys.stdin)
+
+    # Scope to the sourceindex subagent only; main-agent calls carry no
+    # agent_type and pass straight through.
+    if payload.get("agent_type") != "sourceindex":
+        return 0
+
+    tool_name = payload.get("tool_name", "")
+    command = payload.get("tool_input", {}).get("command", "")
+
+    reason = violation(tool_name, command)
+    if reason is None:
+        return 0
+
+    msg = [
+        "BLOCKED by sourceindex subagent restriction.",
+        f"  tool: {tool_name}",
+        f"  reason: {reason}",
+        "  You may run ONLY a single `sourceindex search ...` Bash call.",
+        "  If you have already run that search, you are DONE: stop now and return",
+        "  its stdout to the caller verbatim. Do NOT run any other command",
+        "  (find/ls/grep/cat/...) — retrying is futile, every one will be blocked.",
+    ]
+    if command:
+        msg.append(f"  attempted: {command}")
+    sys.stderr.write("\n".join(msg) + "\n")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+'''
+
+
+def _ensure_gitignored(repo_root: Path) -> None:
+    gitignore = repo_root / ".gitignore"
+    existing = gitignore.read_text() if gitignore.exists() else ""
+    lines = {l.strip() for l in existing.splitlines()}
+    if GITIGNORE_ENTRY in lines or GITIGNORE_ENTRY.rstrip("/") in lines:
+        return
+    sep = "" if not existing or existing.endswith("\n") else "\n"
+    gitignore.write_text(existing + sep + GITIGNORE_ENTRY + "\n")
+    _log.info(f"Added {GITIGNORE_ENTRY} to {gitignore}")
+
+
+def _install_hooks(repo_root: Path) -> None:
+    """Install ``_update.sh`` + a symlink per entry in :data:`HOOKS`.
+
+    Idempotent: re-running rewrites the script when its content drifts and
+    replaces non-symlink leftovers (e.g. an older single-file ``post-commit``)
+    with fresh symlinks pointing at ``_update.sh``. Also sets the per-clone
+    ``core.hooksPath`` config so git actually invokes them.
+    """
+    hooks_dir = repo_root / ".githooks"
+    hooks_dir.mkdir(exist_ok=True)
+
+    script = hooks_dir / "_update.sh"
+    if not script.exists() or script.read_text() != UPDATE_SCRIPT:
+        script.write_text(UPDATE_SCRIPT)
+    script.chmod(script.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    for name in HOOKS:
+        link = hooks_dir / name
+        if link.is_symlink() or link.exists():
+            link.unlink()
+        link.symlink_to("_update.sh")
+
+    if (repo_root / ".git").exists():
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "config", "--get", "core.hooksPath"],
+            capture_output=True, text=True,
+        )
+        if not (result.returncode == 0 and result.stdout.strip() == ".githooks"):
+            subprocess.run(
+                ["git", "-C", str(repo_root), "config", "core.hooksPath", ".githooks"],
+                check=True,
+            )
+        _log.info(f"Installed hooks {list(HOOKS)} at {hooks_dir}")
+    else:
+        _log.warning(
+            f"{repo_root} is not a git repo; hooks written but core.hooksPath not set",
+            extra={"event": "install.no_git", "repo_root": str(repo_root)},
+        )
+
+
+def _append_claude_md(repo_root: Path, section: str, marker: str) -> None:
+    claude_md = repo_root / "CLAUDE.md"
+    if not claude_md.exists():
+        claude_md.write_text(CLAUDE_MD_HEADER + section)
+        _log.info(f"Created {claude_md} with sourceindex workflow section")
+        return
+    existing = claude_md.read_text()
+    if marker in existing:
+        _log.info(f"{claude_md} already contains the sourceindex workflow section, skipping")
+        return
+    claude_md.write_text(existing.rstrip("\n") + "\n\n" + section)
+    _log.info(f"Appended sourceindex workflow section to {claude_md}")
+
+
+def _write_subagent_config(repo_root: Path) -> None:
+    agents_dir = repo_root / ".claude" / "agents"
+    agent_path = agents_dir / SUBAGENT_FILENAME
+
+    if agent_path.exists() and agent_path.read_text() == SUBAGENT_CONFIG:
+        _log.info(f"Subagent config already present at {agent_path}, skipping")
+        return
+
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    agent_path.write_text(SUBAGENT_CONFIG)
+    _log.info(f"Wrote subagent config to {agent_path}")
+
+
+def _write_restrict_hook(repo_root: Path) -> None:
+    """Write the PreToolUse gate that keeps the subagent single-shot.
+
+    Idempotent: rewrites only when the content drifts; always (re)sets the
+    executable bit so Claude Code can invoke it.
+    """
+    hooks_dir = repo_root / ".claude" / "hooks"
+    hook_path = hooks_dir / RESTRICT_HOOK_FILENAME
+
+    if hook_path.exists() and hook_path.read_text() == RESTRICT_HOOK_SCRIPT:
+        _log.info(f"Subagent gate hook already present at {hook_path}, skipping")
+    else:
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+        hook_path.write_text(RESTRICT_HOOK_SCRIPT)
+        _log.info(f"Wrote subagent gate hook to {hook_path}")
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _register_pretooluse_hook(repo_root: Path) -> None:
+    """Register the gate hook in ``.claude/settings.json`` (shared, committed).
+
+    Merges into any existing settings/hooks rather than overwriting, and is
+    idempotent — re-running init never adds a duplicate PreToolUse entry. Pairs
+    with :func:`_write_restrict_hook`; without the registration the script on
+    disk never fires.
+    """
+    settings_path = repo_root / ".claude" / "settings.json"
+
+    settings: dict = {}
+    if settings_path.exists():
+        try:
+            loaded = json.loads(settings_path.read_text())
+            settings = loaded if isinstance(loaded, dict) else {}
+        except json.JSONDecodeError as e:
+            _log.warning(
+                f"{settings_path} is not valid JSON; rewriting with a fresh config.",
+                extra={
+                    "event": "settings.decode_failed",
+                    "path": str(settings_path),
+                    "error": str(e),
+                },
+            )
+            settings = {}
+
+    if not isinstance(settings.get("hooks"), dict):
+        settings["hooks"] = {}
+    hooks = settings["hooks"]
+    if not isinstance(hooks.get("PreToolUse"), list):
+        hooks["PreToolUse"] = []
+    pre_hooks = hooks["PreToolUse"]
+
+    for group in pre_hooks:
+        if not isinstance(group, dict):
+            continue
+        for entry in group.get("hooks", []):
+            if isinstance(entry, dict) and entry.get("command") == RESTRICT_HOOK_COMMAND:
+                _log.info(f"Subagent gate already registered in {settings_path}, skipping")
+                return
+
+    pre_hooks.append({
+        "matcher": ".*",
+        "hooks": [{"type": "command", "command": RESTRICT_HOOK_COMMAND}],
+    })
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+    _log.info(f"Registered subagent gate (PreToolUse) in {settings_path}")
+
+
+def _write_mcp_config(repo_root: Path) -> None:
+    mcp_path = repo_root / ".mcp.json"
+    if mcp_path.exists():
+        try:
+            existing = json.loads(mcp_path.read_text())
+        except json.JSONDecodeError as e:
+            _log.warning(
+                f"{mcp_path} is not valid JSON; replacing with a fresh config.",
+                extra={
+                    "event": "mcp_config.decode_failed",
+                    "path": str(mcp_path),
+                    "error": str(e),
+                },
+            )
+            existing = None
+        if isinstance(existing, dict) and "sourceindex-server" in existing.get("mcpServers", {}):
+            _log.info(f"{mcp_path} already configures sourceindex-server, skipping")
+            return
+        if isinstance(existing, dict):
+            servers = existing.setdefault("mcpServers", {})
+            servers["sourceindex-server"] = MCP_CONFIG["mcpServers"]["sourceindex-server"]
+            mcp_path.write_text(json.dumps(existing, indent=2) + "\n")
+            _log.info(f"Added sourceindex-server to {mcp_path}")
+            return
+    mcp_path.write_text(json.dumps(MCP_CONFIG, indent=2) + "\n")
+    _log.info(f"Wrote {mcp_path}")

sourceindex/daemon/__init__.py

@@ -0,0 +1,83 @@
+"""Privilege-separated daemon + encrypted-at-rest index store."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from .client import AdminSocketUnavailable, Client
+from .server import run_daemon
+from .store import EncryptedStore, PlaintextStore
+
+
+_log = logging.getLogger(__name__)
+
+INDEX_DIR_NAME = ".sourceindex"
+
+
+@dataclass(frozen=True)
+class IndexDir:
+    path: Path
+    repo_hash: str
+
+    @classmethod
+    def for_repo(cls, repo_root: Path, override: str | None = None) -> "IndexDir":
+        from ..lib.git import resolve_main_worktree
+        from .lifecycle import repo_hash_for
+
+        repo_root = Path(repo_root).resolve()
+        if override:
+            return cls(path=Path(override).resolve(), repo_hash=repo_hash_for(repo_root))
+        main = resolve_main_worktree(repo_root)
+        if main != repo_root:
+            _log.info(
+                "Linked worktree detected; using %s/%s for the shared index",
+                main, INDEX_DIR_NAME,
+                extra={
+                    "event": "repo_root.worktree_redirect",
+                    "worktree": str(repo_root),
+                    "main_worktree": str(main),
+                },
+            )
+        return cls(path=main / INDEX_DIR_NAME, repo_hash=repo_hash_for(main))
+
+    def is_encrypted_layout(self) -> bool:
+        from .store import ENC_SUFFIX, MANIFEST_FILENAME, TIER1_FILENAME
+        if (self.path / (MANIFEST_FILENAME + ENC_SUFFIX)).is_file():
+            return True
+        # Legacy per-file encrypted layout still routes through EncryptedStore.
+        return (self.path / (TIER1_FILENAME + ENC_SUFFIX)).is_file()
+
+    def has_plaintext_index(self) -> bool:
+        from .store import TIER1_FILENAME
+        return (self.path / TIER1_FILENAME).is_file()
+
+
+def open_store_for(index_dir: "IndexDir | Path") -> "EncryptedStore | PlaintextStore":
+    if isinstance(index_dir, IndexDir):
+        idx = index_dir
+    else:
+        idx = IndexDir(path=Path(index_dir), repo_hash="")
+    if idx.is_encrypted_layout():
+        from .keyring_store import load_or_create_key
+        if not idx.repo_hash:
+            raise RuntimeError(
+                f"{idx.path} is an encrypted store but --index-dir was "
+                "supplied without a repo context; encrypted stores can only "
+                "be read through the daemon."
+            )
+        key = load_or_create_key(idx.repo_hash)
+        return EncryptedStore(idx.path, key, idx.repo_hash)
+    return PlaintextStore(idx.path)
+
+
+__all__ = [
+    "IndexDir",
+    "Client",
+    "AdminSocketUnavailable",
+    "EncryptedStore",
+    "PlaintextStore",
+    "open_store_for",
+    "run_daemon",
+]

sourceindex/daemon/client.py

@@ -0,0 +1,141 @@
+"""Synchronous client for the daemon's UDS RPC."""
+
+from __future__ import annotations
+
+import socket
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from . import lifecycle
+from .protocol import E_SERVER, RpcError, encode_frame, make_request, read_frame_sync
+
+
+def _drop_none(**kwargs: Any) -> dict[str, Any]:
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+class AdminSocketUnavailable(RuntimeError):
+    pass
+
+
+class Client:
+    def __init__(
+        self,
+        repo_root: Path,
+        *,
+        admin: bool = False,
+        auto_spawn: bool = True,
+        allow_dump_on_spawn: bool = False,
+    ) -> None:
+        self.repo_root = Path(repo_root).resolve()
+        self.admin = admin
+        self.auto_spawn = auto_spawn
+        self.allow_dump_on_spawn = allow_dump_on_spawn
+        self.repo_hash = lifecycle.repo_hash_for(self._main_worktree())
+        self._next_id = 1
+
+    def _main_worktree(self) -> Path:
+        from ..lib.git import resolve_main_worktree
+        return resolve_main_worktree(self.repo_root)
+
+    def _socket_path(self) -> Path:
+        return (
+            lifecycle.admin_socket(self.repo_hash)
+            if self.admin
+            else lifecycle.user_socket(self.repo_hash)
+        )
+
+    def _ensure_running(self) -> None:
+        if lifecycle.is_daemon_running(self.repo_root):
+            return
+        if not self.auto_spawn:
+            raise FileNotFoundError(
+                f"daemon for {self.repo_root} is not running; run "
+                "`sourceindex daemon --repo-root .`"
+            )
+        lifecycle.spawn_daemon(self.repo_root, allow_dump=self.allow_dump_on_spawn)
+
+    def _call(self, method: str, params: dict | None = None) -> Any:
+        self._ensure_running()
+        path = self._socket_path()
+        if self.admin and not path.exists():
+            raise AdminSocketUnavailable(
+                f"admin socket {path} not found; the daemon for {self.repo_root} "
+                "was not started with --allow-dump."
+            )
+        sock = lifecycle.connect_blocking(path)
+        try:
+            req_id = self._next_id
+            self._next_id += 1
+            sock.sendall(encode_frame(make_request(method, params, id_=req_id)))
+            resp = read_frame_sync(sock)
+        finally:
+            sock.close()
+        if "error" in resp and resp["error"] is not None:
+            err = resp["error"]
+            raise RpcError(
+                int(err.get("code", E_SERVER)),
+                str(err.get("message", "unknown error")),
+                err.get("data"),
+            )
+        return resp.get("result")
+
+    def ping(self) -> dict:
+        return self._call("ping")
+
+    def search(self, query: str, *, model: str | None = None, api_key: str | None = None) -> dict:
+        return self._call("search", _drop_none(query=query, model=model, api_key=api_key))
+
+    def init(
+        self,
+        *,
+        api_key: str,
+        model: str | None = None,
+        languages: list[str] | None = None,
+        workers: int | None = None,
+    ) -> dict:
+        return self._call("init", _drop_none(
+            api_key=api_key, model=model, languages=languages, workers=workers,
+        ))
+
+    def update(
+        self,
+        *,
+        api_key: str,
+        model: str | None = None,
+        languages: list[str] | None = None,
+        changed_files: list[str] | None = None,
+        workers: int | None = None,
+    ) -> dict:
+        return self._call("update", _drop_none(
+            api_key=api_key, model=model, languages=languages,
+            changed_files=changed_files, workers=workers,
+        ))
+
+    def install_hooks(self) -> dict:
+        return self._call("install_hooks")
+
+    def usage(self) -> dict:
+        return self._call("usage")
+
+    def dump_all(self, out_dir: Path) -> dict:
+        return self._call("dump_all", {"out_dir": str(Path(out_dir).resolve())})
+
+    def read_index_md(self) -> str:
+        return self._call("read_index_md")["text"]
+
+    def read_detail(self, rel_path: str) -> str:
+        return self._call("read_detail", {"rel_path": rel_path})["text"]
+
+    def read_env(self) -> dict[str, str]:
+        return self._call("read_env")["vars"]
+
+    def shutdown(self) -> dict:
+        try:
+            return self._call("shutdown")
+        except ConnectionError:
+            # Daemon may close the socket before we read the response;
+            # the request itself was delivered.
+            return {"ok": True}

sourceindex/daemon/crypto.py

@@ -0,0 +1,48 @@
+"""AES-256-GCM blob format. Layout: MAGIC(4) || nonce(12) || ciphertext || tag(16)."""
+
+from __future__ import annotations
+
+import os
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+MAGIC = b"SI01"
+NONCE_LEN = 12
+KEY_LEN = 32
+
+
+class InvalidBlob(ValueError):
+    pass
+
+
+def generate_key() -> bytes:
+    return os.urandom(KEY_LEN)
+
+
+def encrypt(plaintext: bytes, key: bytes) -> bytes:
+    if len(key) != KEY_LEN:
+        raise ValueError(f"key must be {KEY_LEN} bytes, got {len(key)}")
+    nonce = os.urandom(NONCE_LEN)
+    ct = AESGCM(key).encrypt(nonce, plaintext, None)
+    return MAGIC + nonce + ct
+
+
+def decrypt(blob: bytes, key: bytes) -> bytes:
+    if len(key) != KEY_LEN:
+        raise ValueError(f"key must be {KEY_LEN} bytes, got {len(key)}")
+    if len(blob) < len(MAGIC) + NONCE_LEN + 16:
+        raise InvalidBlob("blob too short")
+    if blob[: len(MAGIC)] != MAGIC:
+        raise InvalidBlob(f"bad magic: {blob[: len(MAGIC)]!r}")
+    nonce = blob[len(MAGIC) : len(MAGIC) + NONCE_LEN]
+    ct = blob[len(MAGIC) + NONCE_LEN :]
+    try:
+        return AESGCM(key).decrypt(nonce, ct, None)
+    except InvalidTag as e:
+        raise InvalidBlob("authentication failed (wrong key or tampered blob)") from e
+
+
+def looks_encrypted(head: bytes) -> bool:
+    return head.startswith(MAGIC)