underwrit 0.3.0__py3-none-any.whl

underwrit/cedar.py

@@ -0,0 +1,150 @@
+"""A Cedar subset, imported into Underwrit's policy document. Honest about what it covers.
+
+Underwrit's decision engine is not a general authorisation language: it holds or denies *tool calls*
+based on provenance, consequence, ceilings and allowlists. Teams that write Cedar can bring the
+parts of their policy that map onto those knobs:
+
+    forbid (principal, action == Action::"send_email", resource);
+        → deniedTools += send_email
+    forbid (principal, action in [Action::"a", Action::"b"], resource);
+        → deniedTools += a, b
+    permit (principal, action == Action::"send_email", resource)
+        when { resource.to like "*@acme.com" };
+        → allowlist.to += "*@acme.com"      (== "x" is the exact pattern "x")
+    forbid (principal, action == Action::"transfer", resource)
+        when { resource.amount > 10000 };
+        → ceilings.amount = 10000            (>= N becomes N - 1 for integers)
+
+Everything else — principals other than the wildcard, `unless`, `context.*`, entity hierarchies,
+`has`, `&&` chains — is refused with the line it sits on. The importer never guesses: an
+unsupported policy fails the whole import rather than producing a document that silently
+drops a rule. What is imported is the *conservative* projection: a permit can only add an
+allowlist pattern (narrowing what passes), and a forbid can only deny or cap.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import math
+import re
+
+ACTION_ONE = re.compile(r'action\s*==\s*Action::"([^"]+)"')
+ACTION_MANY = re.compile(r'action\s+in\s*\[([^\]]*)\]')
+ACTION_ITEM = re.compile(r'Action::"([^"]+)"')
+HEAD = re.compile(r'^(permit|forbid)\s*\(\s*principal\s*,\s*(.+?)\s*,\s*resource\s*\)\s*(.*?)\s*;\s*$', re.S)
+WHEN = re.compile(r'^when\s*\{\s*(.+?)\s*\}$', re.S)
+LIKE = re.compile(r'^resource\.([A-Za-z_][A-Za-z0-9_]*)\s*(like|==)\s*"([^"]*)"$')
+CEIL = re.compile(r'^resource\.([A-Za-z_][A-Za-z0-9_]*)\s*(>=|>)\s*(-?\d+(?:\.\d+)?)$')
+
+
+class CedarError(ValueError):
+    pass
+
+
+def _strip_comment(raw: str) -> str:
+    """Drop a `//` comment, but not a `//` inside a string ("https://…")."""
+    in_str = False
+    i = 0
+    while i < len(raw):
+        ch = raw[i]
+        if ch == '"' and (i == 0 or raw[i - 1] != "\\"):
+            in_str = not in_str
+        elif not in_str and raw.startswith("//", i):
+            return raw[:i]
+        i += 1
+    return raw
+
+
+def _statements(text: str) -> list[tuple[int, str]]:
+    """(line number, statement) pairs, comments stripped, split on `;`."""
+    out, buf, start = [], [], None
+    for n, raw in enumerate(text.splitlines(), 1):
+        line = _strip_comment(raw)
+        if not line.strip():
+            continue
+        if start is None:
+            start = n
+        buf.append(line.strip())
+        if line.rstrip().endswith(";"):
+            out.append((start, " ".join(buf)))
+            buf, start = [], None
+    if buf:
+        raise CedarError(f"line {start}: statement does not end with ';'")
+    return out
+
+
+def _actions(scope: str, line: int) -> list[str]:
+    m = ACTION_ONE.fullmatch(scope.strip())
+    if m:
+        return [m.group(1)]
+    m = ACTION_MANY.fullmatch(scope.strip())
+    if m:
+        items = ACTION_ITEM.findall(m.group(1))
+        if not items:
+            raise CedarError(f"line {line}: empty action list")
+        return items
+    raise CedarError(f"line {line}: only `action == Action::\"x\"` and `action in [...]` are supported "
+                     f"(got {scope.strip()!r})")
+
+
+def to_policy(text: str) -> dict:
+    """The policy-document fragment a Cedar text maps to: deniedTools, allowlist, ceilings."""
+    denied: list[str] = []
+    allowlist: dict[str, list[str]] = {}
+    ceilings: dict[str, float] = {}
+    for line, stmt in _statements(text):
+        m = HEAD.match(stmt)
+        if not m:
+            raise CedarError(f"line {line}: expected `permit|forbid (principal, action ..., resource) [when {{...}}];`")
+        effect, scope, tail = m.groups()
+        actions = _actions(scope, line)
+        if not tail:
+            if effect == "forbid":
+                denied.extend(a for a in actions if a not in denied)
+                continue
+            raise CedarError(f"line {line}: an unconditional permit does not narrow anything Underwrit enforces; "
+                             f"Underwrit allows by default and records — remove it or add a `when` on a resource field")
+        w = WHEN.match(tail)
+        if not w:
+            raise CedarError(f"line {line}: only a single `when {{ ... }}` clause is supported (no `unless`)")
+        cond = w.group(1).strip()
+        if effect == "permit":
+            c = LIKE.match(cond)
+            if not c:
+                raise CedarError(f"line {line}: a permit's condition must be `resource.<field> like|== \"pattern\"`")
+            fld, op, pat = c.groups()
+            # Cedar `like` is a glob; Underwrit's allowlist speaks literals and anchored `re:` patterns.
+            # Translate rather than store verbatim, or the rule would never match anything.
+            rule = f"re:{fnmatch.translate(pat)}" if op == "like" and any(ch in pat for ch in "*?[") else pat
+            allowlist.setdefault(fld, [])
+            if rule not in allowlist[fld]:
+                allowlist[fld].append(rule)
+        else:
+            c = CEIL.match(cond)
+            if not c:
+                raise CedarError(f"line {line}: a forbid's condition must be `resource.<field> > N` or `>= N`")
+            fld, op, num = c.groups()
+            val = float(num)
+            if op == ">=":
+                # Underwrit holds strictly above a ceiling; "forbid >= N" means N itself is forbidden.
+                val = val - 1 if val == int(val) else math.nextafter(val, -math.inf)
+            ceilings[fld] = min(val, ceilings[fld]) if fld in ceilings else val
+    return {"deniedTools": denied, "allowlist": allowlist, "ceilings": ceilings,
+            "note": "Cedar subset: forbid→deniedTools, permit-when-like→allowlist, forbid-when-greater→ceilings. "
+                    "Principals, contexts, unless-clauses and entity hierarchies are not imported."}
+
+
+def merge(current: dict, fragment: dict) -> dict:
+    """The current policy document with the fragment folded in (lists union, ceilings tightest)."""
+    out = dict(current)
+    out["deniedTools"] = sorted(set(current.get("deniedTools") or []) | set(fragment["deniedTools"]))
+    al = {k: list(v) for k, v in (current.get("allowlist") or {}).items()}
+    for k, pats in fragment["allowlist"].items():
+        al.setdefault(k, [])
+        al[k] += [p for p in pats if p not in al[k]]
+    out["allowlist"] = al
+    ce = dict(current.get("ceilings") or {})
+    for k, v in fragment["ceilings"].items():
+        ce[k] = min(v, ce[k]) if k in ce else v
+    out["ceilings"] = ce
+    return out

underwrit/chain.py

@@ -0,0 +1,519 @@
+"""The audit log: what happened, who caused it, and whether the record has been altered since.
+
+Separate from the run log. A run log is an operator's view of one execution and is written for
+debugging; this is evidence, written for someone reconstructing events afterwards who does not trust
+the system that produced them. The two have different readers and different retention, so they are
+different tables.
+
+**Append-only, and tamper-evident.** Every entry stores the hash of the entry before it, so the log
+is a chain: altering or deleting any row breaks every hash after it, and `verify_chain` finds the
+first break. This does not make the log immutable — anyone with the database file can rewrite it —
+but it makes a rewrite *detectable*, which is the achievable property for a log that lives beside
+the application. Genuine immutability means shipping these entries to somewhere the application
+cannot reach, and `export_jsonl` exists for exactly that.
+
+What is deliberately not recorded: request bodies, tokens, credentials, or anything from a
+`secretRef`. An audit log is a high-value target precisely because it is trusted and retained, and a
+log that accumulates secrets is a breach waiting for a reader.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import json
+import pathlib
+import sqlite3
+import threading
+
+from . import db
+import time
+
+GENESIS = "0" * 64
+
+
+def entry_hash(previous: str, payload: dict) -> str:
+    """Hash one entry together with its predecessor.
+
+    `sort_keys` matters: the same entry must hash identically on every machine and every Python
+    version, or verification fails on a log nobody touched. Separators are pinned for the same
+    reason — json.dumps' default spacing has changed before.
+    """
+    body = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(f"{previous}{body}".encode()).hexdigest()
+
+
+def init(conn) -> None:
+    conn.execute(
+        db.ddl("""
+        CREATE TABLE IF NOT EXISTS audit_log (
+            seq INTEGER PRIMARY KEY AUTOINCREMENT,
+            at REAL NOT NULL,
+            actor TEXT NOT NULL DEFAULT '',
+            actor_id TEXT NOT NULL DEFAULT '',
+            action TEXT NOT NULL,
+            environment TEXT NOT NULL DEFAULT '',
+            target TEXT NOT NULL DEFAULT '',
+            outcome TEXT NOT NULL DEFAULT '',
+            reason TEXT NOT NULL DEFAULT '',
+            detail TEXT NOT NULL DEFAULT '{}',
+            source_ip TEXT NOT NULL DEFAULT '',
+            prev_hash TEXT NOT NULL DEFAULT '',
+            hash TEXT NOT NULL DEFAULT ''
+        );
+        """)
+    )
+    # Added after the table shipped. A redacted entry keeps its row and its hash — see `redact`.
+    if "redacted_at" not in db.table_columns(conn, "audit_log"):
+        conn.execute(db.ddl("ALTER TABLE audit_log ADD COLUMN redacted_at REAL"))
+    # Created here rather than by `seal()`, which is where it used to appear the first time a chain
+    # was sealed. A lazily-created table means two installs of the same version have different
+    # schemas, and that is not theoretical: restoring a backup taken from a *sealed* database into
+    # a fresh one failed on "no such table: audit_log_archive" — so the sealed chain, the hardest
+    # evidence here to reconstruct, was the one thing that could not be recovered. An empty archive
+    # table costs nothing and makes the schema the same everywhere.
+    conn.execute(db.ddl("""
+        CREATE TABLE IF NOT EXISTS audit_log_archive (
+            seq INTEGER,
+            at REAL,
+            actor TEXT,
+            actor_id TEXT,
+            action TEXT,
+            environment TEXT,
+            target TEXT,
+            outcome TEXT,
+            reason TEXT,
+            detail TEXT,
+            source_ip TEXT,
+            prev_hash TEXT,
+            hash TEXT,
+            sealed_at REAL
+        );
+        """))
+    conn.execute("CREATE INDEX IF NOT EXISTS audit_at ON audit_log(at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS audit_actor ON audit_log(actor)")
+
+    # "No two entries claim the same predecessor" *is* the no-fork invariant, so a unique index on
+    # prev_hash states it to the database rather than trusting every writer to be careful. Where it
+    # applies, a second process racing the first gets an integrity error instead of a silent fork,
+    # and `record` retries against the fresh tail.
+    #
+    # It cannot be created over a log that already forked, and rewriting that history to make room
+    # is exactly the tampering the chain exists to detect. So the failure is reported rather than
+    # swallowed: a guarantee that quietly did not apply is the "looks configured, does nothing"
+    # failure this codebase keeps finding.
+    conn.commit()  # what came before must survive the rollback below on a forked log
+    try:
+        conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS audit_prev_unique ON audit_log(prev_hash)")
+    except Exception as exc:  # noqa: BLE001 — any engine's integrity error means pre-existing forks
+        conn.rollback()
+        print(
+            "Audit: could not add the unique index on prev_hash — this log already contains forked "
+            f"entries, so cross-process protection is not active ({type(exc).__name__}). Appends are "
+            "still serialised within this process. Run audit.verify_chain to see where it forked.",
+            flush=True,
+        )
+
+
+def record(
+    conn,
+    *,
+    actor: str,
+    actor_id: str = "",
+    action: str,
+    outcome: str,
+    environment: str = "",
+    target: str = "",
+    reason: str = "",
+    detail: dict | None = None,
+    source_ip: str = "",
+    at: float | None = None,
+) -> dict:
+    """Append one entry. Never raises for a caller — an audit failure must not break the request.
+
+    `outcome` is `allowed`, `denied`, `succeeded` or `failed`. Denials are recorded as carefully as
+    successes: a log containing only what worked cannot show someone probing for what does not.
+    """
+    # Bounded, not `with _APPEND_LOCK:`. The lock serialises appends so two threads cannot read
+    # the same chain tail; held forever by a thread stuck on a dead database socket, it wedged
+    # *every* audit write — and since signing in writes one, nobody could authenticate while
+    # `/api/health` answered normally, because health touches no database. A lock that can only be
+    # waited on indefinitely turns one stuck query into a total outage with no error anywhere.
+    if not _APPEND_LOCK.acquire(timeout=_APPEND_LOCK_TIMEOUT):
+        raise TimeoutError(
+            f"audit append lock held for more than {_APPEND_LOCK_TIMEOUT}s — a previous write is stuck"
+        )
+    try:
+        last = None
+        for _ in range(_MAX_APPEND_RETRIES):
+            try:
+                return _append(conn, actor=actor, actor_id=actor_id, action=action, outcome=outcome,
+                               environment=environment, target=target, reason=reason,
+                               detail=detail, source_ip=source_ip, at=at)
+            except Exception as exc:  # noqa: BLE001 — engines raise different integrity errors
+                # Another process appended between this one's read and write. The unique index on
+                # prev_hash turned what would have been a silent fork into this error, so re-read
+                # the tail and try again rather than writing a second claim on the same predecessor.
+                last = exc
+                conn.rollback()
+        raise last  # type: ignore[misc]
+    finally:
+        _APPEND_LOCK.release()
+
+
+# Appending is serialised. Reading the tail and writing the next entry is a read-modify-write, and
+# `server.py` is a ThreadingHTTPServer, so without this two requests read the same tail and both
+# write claiming the same predecessor. That is not a hypothetical: a real log reached 13 forks
+# across 614 entries, the first pair 0.4ms apart, and `verify_chain` reported the result exactly as
+# it reports tampering. A control that cannot tell a burst of traffic from a rewrite is worse than
+# no control, because it is still believed.
+#
+# The lock spans the commit, not just the insert. Releasing it after the INSERT and before the
+# COMMIT would fix nothing: the next thread's SELECT runs on its own connection and cannot see an
+# uncommitted row, so it would read the same tail again and fork anyway.
+#
+# **This serialises one process.** The server is single-process today, so the chain is correct as
+# deployed — but a second replica appends on its own lock and the two do not see each other. The
+# structural guarantee is the unique index in `init()`; see the note there for when it applies.
+_APPEND_LOCK = threading.Lock()
+# Seconds to wait for the append lock. Long enough that ordinary contention never trips it, short
+# enough that a stuck writer surfaces as an error rather than as authentication hanging forever.
+_APPEND_LOCK_TIMEOUT = float(os.environ.get("AUDIT_LOCK_TIMEOUT", "15") or 15)
+
+
+def _append(conn, *, actor, actor_id, action, outcome, environment, target, reason, detail, source_ip, at=None):
+    row = conn.execute("SELECT hash FROM audit_log ORDER BY seq DESC LIMIT 1").fetchone()
+    previous = (row[0] if row else "") or GENESIS
+    payload = {
+        "at": float(time.time() if at is None else at),
+        "actor": str(actor or ""),
+        # Coerced to the type the COLUMN holds, before hashing. The hash is computed over the values
+        # going in and re-computed over the values coming back out, so any coercion the database
+        # performs between those two moments breaks verification permanently.
+        #
+        # `actor_id` is TEXT. A caller passing the integer 7 hashed `7` and stored `"7"`, and the
+        # entry could never verify afterwards — indistinguishable from a row somebody edited, which
+        # is the single worst way for this to fail. Found by an int slipping into a test.
+        #
+        # Safe to apply to an existing chain: for a caller that already passed a string this is the
+        # identity, so no entry that verifies today changes. It can only turn entries that were
+        # already unverifiable into correct ones.
+        "actor_id": str(actor_id or ""),
+        "action": str(action or ""),
+        "environment": str(environment or ""),
+        "target": str(target or ""),
+        "outcome": str(outcome or ""),
+        "reason": str(reason or ""),
+        "detail": detail or {},
+        "source_ip": str(source_ip or ""),
+    }
+    digest = entry_hash(previous, payload)
+    cur = conn.execute(
+        "INSERT INTO audit_log (at, actor, actor_id, action, environment, target, outcome, reason, detail, "
+        "source_ip, prev_hash, hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
+        + (" RETURNING seq" if db.is_postgres() else ""),
+        # Every value comes from `payload` — the same object that was hashed. Passing the raw
+        # parameters here instead let the stored form drift from the hashed form, which is the
+        # defect above: coercing one without the other only moves where the mismatch happens.
+        (
+            payload["at"], payload["actor"], payload["actor_id"], payload["action"],
+            payload["environment"], payload["target"], payload["outcome"], payload["reason"],
+            json.dumps(payload["detail"], sort_keys=True), payload["source_ip"], previous, digest,
+        ),
+    )
+    # Committed inside the lock so the next appender's SELECT sees this row. The one caller opens a
+    # connection solely for this write, so nothing else is committed by it.
+    seq = cur.fetchone()["seq"] if db.is_postgres() else getattr(cur, "lastrowid", None)
+    conn.commit()
+    return {**payload, "hash": digest, "prevHash": previous, "seq": seq}
+
+
+# How many times an append will re-read the tail and try again. Only reachable when another
+# *process* appended between this one's read and write, which the unique index turns into an error
+# rather than a fork. One retry covers the race; a persistent failure is a real problem and should
+# surface rather than spin.
+_MAX_APPEND_RETRIES = 3
+
+
+def _payload_of(row) -> dict:
+    return {
+        "at": row["at"],
+        "actor": row["actor"],
+        "actor_id": row["actor_id"],
+        "action": row["action"],
+        "environment": row["environment"],
+        "target": row["target"],
+        "outcome": row["outcome"],
+        "reason": row["reason"],
+        "detail": json.loads(row["detail"] or "{}"),
+        "source_ip": row["source_ip"],
+    }
+
+
+def explained_redactions(conn) -> set:
+    """Sequence numbers that have a matching `audit.redact` entry in the chain.
+
+    The check that makes redaction safe. `verify_rows` accepts a redacted row's recorded hash
+    without recomputing it, so on its own a redaction flag is a way to make an edited row verify
+    clean — set `redacted_at` in the database and the content check is skipped. What an attacker
+    cannot do is append the corresponding `audit.redact` entry without it being in the chain,
+    hashed, and visible. So a redaction with no explanation is reported, and it is a stronger
+    signal than a broken hash: a broken hash means somebody edited a row, this means somebody
+    edited a row and tried to make it look authorised.
+    """
+    return {int(r["target"]) for r in conn.execute(
+        "SELECT target FROM audit_log WHERE action = ? AND target != ?", ("audit.redact", ""))
+        if str(r["target"]).isdigit()}
+
+
+def verify_chain(conn) -> dict:
+    """Recompute every hash and report the first entry that does not match.
+
+    Returns {"ok", "checked", "brokenAt", "detail"}. `brokenAt` is the sequence number of the first
+    entry whose recorded hash disagrees with its contents — everything before it is intact, which is
+    what makes this useful rather than merely alarming.
+    """
+    result = verify_rows(conn.execute("SELECT * FROM audit_log ORDER BY seq ASC"))
+    if not result.get("redacted"):
+        return result
+    explained = explained_redactions(conn)
+    unexplained = sorted(
+        r["seq"] for r in conn.execute("SELECT seq FROM audit_log WHERE redacted_at IS NOT NULL")
+        if r["seq"] not in explained)
+    if unexplained:
+        return {**result, "ok": False, "brokenAt": unexplained[0], "unexplained": unexplained,
+                "detail": f"{len(unexplained)} entr"
+                          f"{'y is' if len(unexplained) == 1 else 'ies are'} marked redacted with "
+                          "no `audit.redact` entry authorising it. A redaction skips the content "
+                          "check, so an unexplained one is how an edited row would be made to "
+                          f"verify clean. First: {unexplained[0]}."}
+    return {**result, "unexplained": []}
+
+
+def verify_rows(rows) -> dict:
+    """The verification itself, over anything that yields entries in sequence order.
+
+    Split out so a *backup* is checked by the same definition as the live table (`backup.verify`
+    reads the dumped rows through here). Two implementations of "does this chain hold" is two
+    answers waiting to disagree, on the one question where disagreement is the whole point. Rows
+    may be sqlite3.Row, psycopg rows or plain dicts — all three index by column name.
+    """
+    previous = GENESIS
+    checked = 0
+    redacted = 0
+    for row in rows:
+        if row["prev_hash"] != previous:
+            return {"ok": False, "checked": checked, "redacted": redacted, "brokenAt": row["seq"],
+                    "detail": "entry does not follow the one before it — a row was removed or reordered"}
+        if is_redacted(row):
+            # A redacted entry's *content* is gone, so its hash cannot be recomputed — and that is
+            # the honest report, not a silent pass. What survives is the property that matters:
+            # every later entry's hash covers this row's recorded hash, so the value accepted here
+            # cannot be changed without breaking the whole remainder of the chain. The entry is
+            # still proof that something happened at this position; it is no longer proof of what.
+            #
+            # This is why `redact()` writes its own audit entry. Redaction would otherwise be a way
+            # to make tampering verify clean: the erasure is itself in the chain, naming who did it
+            # and why, so a redaction used to hide something leaves the record of the hiding.
+            redacted += 1
+        elif entry_hash(previous, _payload_of(row)) != row["hash"]:
+            return {"ok": False, "checked": checked, "redacted": redacted, "brokenAt": row["seq"],
+                    "detail": "entry contents do not match its hash — a row was edited"}
+        previous = row["hash"]
+        checked += 1
+    return {"ok": True, "checked": checked, "redacted": redacted, "brokenAt": None,
+            "detail": "" if not redacted else
+                      f"{redacted} of {checked} entries are redacted: the chain is intact and each "
+                      "redaction is itself recorded in it, but the content of those entries cannot "
+                      "be verified because it no longer exists."}
+
+
+# Fields blanked by `redact`. `at`, `action`, `outcome` and `environment` deliberately survive:
+# erasure must remove what identifies a person, not the fact that an action occurred — a log that
+# forgets an apply happened is not a retention policy, it is a gap in the record.
+REDACTED_FIELDS = ("actor", "actor_id", "target", "reason", "detail", "source_ip")
+REDACTION_MARK = "[redacted]"
+
+
+def is_redacted(row) -> bool:
+    keys = row.keys() if hasattr(row, "keys") else row
+    return "redacted_at" in keys and bool(row["redacted_at"])
+
+
+def redact(conn, seq: int, *, actor: str, reason: str) -> dict:
+    """Erase one entry's identifying content, keeping its place in the chain.
+
+    Used for a right-to-erasure request. It is not deletion: the row stays, so `prev_hash` still
+    links its neighbours and nothing about the sequence changes. See `verify_rows` for what
+    survives and what does not.
+
+    A reason is required, and the redaction is appended to the log as its own entry before the
+    content goes — if that append fails, nothing is erased.
+    """
+    row = conn.execute("SELECT * FROM audit_log WHERE seq = ?", (seq,)).fetchone()
+    if row is None:
+        return {"ok": False, "detail": f"no audit entry {seq}"}
+    if is_redacted(row):
+        return {"ok": False, "detail": f"entry {seq} is already redacted"}
+    if not reason:
+        return {"ok": False, "detail": "a redaction must say why — an unexplained erasure in an "
+                                       "audit log is indistinguishable from tampering"}
+    record(conn, actor=actor, action="audit.redact", outcome="succeeded", target=str(seq),
+           reason=reason, detail={"originalAction": row["action"], "at": row["at"]})
+    conn.execute(
+        "UPDATE audit_log SET actor = ?, actor_id = ?, target = ?, reason = ?, detail = ?, "
+        "source_ip = ?, redacted_at = ? WHERE seq = ?",
+        (REDACTION_MARK, "", REDACTION_MARK, REDACTION_MARK, "{}", "", time.time(), seq),
+    )
+    conn.commit()
+    return {"ok": True, "seq": seq,
+            "detail": f"entry {seq} redacted; its hash remains bound into every later entry"}
+
+
+def verify_segment(entries) -> dict:
+    """Verify a *subset* of the log — each entry against its own recorded predecessor hash.
+
+    Different from `verify_rows`, and the difference is not a detail. `verify_rows` walks from
+    GENESIS and requires each entry to follow the last, which is the right check for a whole chain
+    and is *guaranteed to fail* on a subset: a run's entries are interleaved with everyone else's,
+    so the first one's `prev_hash` is some other actor's entry, not the genesis. Used on a segment
+    it reports "broken" for every honest bundle, which is worse than no check — it would teach
+    people that the verdict means nothing.
+
+    What is checkable about a subset: each entry's hash is the SHA-256 of its recorded predecessor
+    hash plus its own contents, so any edit to any field breaks that entry. What is *not* checkable
+    is completeness — nothing here can show an entry was removed, because the neighbours that would
+    have revealed the gap are not in the subset. The bundle says so rather than implying otherwise.
+    """
+    broken = []
+    for row in entries:
+        if entry_hash(row["prev_hash"] or GENESIS, _payload_of(row)) != row["hash"]:
+            broken.append(row["seq"])
+    return {
+        "ok": not broken,
+        "checked": len(entries),
+        "brokenAt": broken[0] if broken else None,
+        "detail": "" if not broken else
+                  f"{len(broken)} entr{'y' if len(broken) == 1 else 'ies'} do not match their hash: "
+                  + ", ".join(str(s) for s in broken[:5]),
+    }
+
+
+def read(conn, limit: int = 200, actor: str = "", action: str = "") -> list[dict]:
+    sql = "SELECT * FROM audit_log WHERE 1=1"
+    params: list[object] = []
+    if actor:
+        sql += " AND actor = ?"
+        params.append(actor)
+    if action:
+        sql += " AND action LIKE ?"
+        params.append(f"{action}%")
+    sql += " ORDER BY seq DESC LIMIT ?"
+    params.append(max(1, min(limit, 1000)))
+    return [{**_payload_of(r), "seq": r["seq"], "hash": r["hash"]} for r in conn.execute(sql, params)]
+
+
+def read_for_target(conn, target: str, environment: str = "", limit: int = 100) -> list[dict]:
+    """Audit entries about one thing — a workflow, an incident, an account.
+
+    Separate from `read()` because the question is different: `read()` answers "what has been
+    happening", filtered by who or what kind; this answers "what has happened *to this*", which is
+    what an activity timeline is. An entry recorded before the environment column carried a value
+    keeps showing, the same tolerance `list_runs` already has for runs that predate it.
+    """
+    sql = "SELECT * FROM audit_log WHERE target = ?"
+    params: list[object] = [target]
+    if environment:
+        sql += " AND (environment = ? OR environment = '' OR environment IS NULL)"
+        params.append(environment)
+    sql += " ORDER BY seq DESC LIMIT ?"
+    params.append(max(1, min(limit, 500)))
+    return [{**_payload_of(r), "seq": r["seq"]} for r in conn.execute(sql, params)]
+
+
+def seal(conn, archive_dir="audit-archive") -> dict:
+    """Close the current chain, preserve it, and start a clean one.
+
+    Needed because a chain that has already forked cannot be repaired. Rewriting the broken segment
+    to make it verify is precisely the tampering the chain exists to detect, so the only honest
+    moves are to leave it broken or to draw a line and start again. In production the first is not
+    a choice: an audit log that permanently answers "ok: false" fails its own check, and nobody can
+    tell a historical concurrency bug from a live intrusion by looking at it.
+
+    So: export everything, move it to `audit_log_archive`, and begin a new chain whose first entry
+    records the seal — including the verdict at the moment of sealing, so the break is on the record
+    rather than quietly disappearing. Nothing is deleted.
+
+    Returns the manifest. The archive file is the evidence; `export_jsonl` already writes the format
+    a SIEM or WORM store wants, and getting entries out of reach of the process that writes them is
+    the only thing that makes them truly immutable.
+    """
+    before = verify_chain(conn)
+    rows = conn.execute("SELECT count(*) AS n FROM audit_log").fetchone()
+    total = rows["n"] if rows else 0
+
+    directory = pathlib.Path(archive_dir)
+    directory.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
+    path = directory / f"audit-{stamp}.jsonl"
+    body = export_jsonl(conn)
+    path.write_text(body + ("\n" if body else ""))
+
+    manifest = {
+        "sealedAt": time.time(),
+        "entries": total,
+        "archive": str(path),
+        "archiveSha256": hashlib.sha256(body.encode()).hexdigest(),
+        "verdictAtSeal": {k: before.get(k) for k in ("ok", "checked", "brokenAt", "detail")},
+    }
+    (directory / f"audit-{stamp}.manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
+
+    conn.execute(
+        "INSERT INTO audit_log_archive (seq, at, actor, actor_id, action, environment, target, outcome, "
+        "reason, detail, source_ip, prev_hash, hash, sealed_at) "
+        "SELECT seq, at, actor, actor_id, action, environment, target, outcome, reason, detail, "
+        f"source_ip, prev_hash, hash, {manifest['sealedAt']} FROM audit_log"
+    )
+    conn.execute("DELETE FROM audit_log")
+    conn.commit()
+
+    # Only now can the invariant be stated to the database: the table is empty, so there is nothing
+    # left for a unique index on prev_hash to collide with.
+    try:
+        conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS audit_prev_unique ON audit_log(prev_hash)")
+        conn.commit()
+        manifest["uniqueIndex"] = True
+    except Exception as exc:  # noqa: BLE001
+        conn.rollback()
+        manifest["uniqueIndex"] = False
+        manifest["uniqueIndexError"] = type(exc).__name__
+
+    # The new chain's first entry says why it starts here. A log that simply began one day, with no
+    # explanation, is the shape a cover-up takes.
+    record(
+        conn,
+        actor="system",
+        action="audit.seal",
+        outcome="succeeded",
+        reason="previous chain archived and a new one started",
+        detail={
+            "archivedEntries": total,
+            "archive": str(path),
+            "archiveSha256": manifest["archiveSha256"],
+            "verdictAtSeal": manifest["verdictAtSeal"],
+        },
+    )
+    return manifest
+
+
+def export_jsonl(conn) -> str:
+    """The whole chain as JSON Lines, for shipping somewhere the application cannot rewrite.
+
+    Tamper-evidence proves a local log was altered; it cannot stop it. Getting entries out of reach
+    of the process that writes them is the only thing that does, and this is the seam for that —
+    a SIEM, an append-only bucket, a WORM store.
+    """
+    return "\n".join(
+        json.dumps({**_payload_of(r), "seq": r["seq"], "prev_hash": r["prev_hash"], "hash": r["hash"]}, sort_keys=True)
+        for r in conn.execute("SELECT * FROM audit_log ORDER BY seq ASC")
+    )