primarypath-server 1.0.0__py3-none-any.whl

app/costgov.py

@@ -0,0 +1,345 @@
+"""Cost governance (F23): event-sourced budgets/quotas, live spend
+enforcement on the same seam as policy, and eval/gate decisions as chained
+evidence. The governance of the governance is audited: loosening a spend
+cap or overriding a failed gate leaves a provable record.
+
+Budgets are a fold of `budget_set` events into a rebuildable `budget_view`
+projection (same discipline as policy_view). Spend is NEVER stored — it is
+folded live from `run_event` usage, so there is no cached counter that can
+drift. Eval profiles and gate decisions are ingested (not re-scored) as
+`eval_recorded` / `gate_decision` events; the latest gate verdict folds
+into `gate_view` for CI.
+
+The F21 safety gate stays independent and fail-safe: cost can only add a
+spend control on top of a safety decision, never weaken one.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import json
+import time
+
+from .ledger.store import DEFAULT_TENANT, Ledger
+from .traces import parse_prices
+
+WINDOWS = ("per_run", "daily", "monthly")
+ON_EXCEED = ("gate", "deny")
+SCOPES = ("tenant", "action")
+COST_REVIEWER = "system:cost"
+
+
+class GateAlreadyDecided(Exception):
+    """A gate_decision already exists for this (agent, version); only an
+    admin override may supersede it (F23)."""
+
+    def __init__(self, verdict: dict):
+        self.verdict = verdict
+        super().__init__(
+            f"gate for {verdict['agent']}@{verdict['version']} is already "
+            f"decided (passed={verdict['passed']})")
+
+
+def window_start_ms(window: str, now: float | None = None) -> int | None:
+    """Epoch-ms at which the active window began. per_run has no time window
+    (it is enforced per single run, not a rolling total)."""
+    now = now if now is not None else time.time()
+    d = dt.datetime.fromtimestamp(now, tz=dt.UTC)
+    if window == "daily":
+        start = d.replace(hour=0, minute=0, second=0, microsecond=0)
+    elif window == "monthly":
+        start = d.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    else:
+        return None
+    return int(start.timestamp() * 1000)
+
+
+# 'window' is a reserved SQL keyword, so the column is window_kind; the API
+# and folded dicts keep 'window' as the key.
+BUDGET_SELECT = ("scope, key, max_usd, max_tokens, window_kind, on_exceed, "
+                 "updated_by, reason, updated_ts_ms")
+_BUDGET_KEYS = ("scope", "key", "max_usd", "max_tokens", "window", "on_exceed",
+                "updated_by", "reason", "updated_ts_ms")
+
+
+HISTORY_MAX_LIMIT = 1000
+
+
+def _row_to_budget(row: tuple) -> dict:
+    return dict(zip(_BUDGET_KEYS, row))
+
+
+class CostStore:
+    def __init__(self, pool, ledger: Ledger, settings):
+        self.pool = pool
+        self.ledger = ledger
+        self.settings = settings
+        self.prices = parse_prices(settings.model_prices)
+
+    # -- budgets: fold (read) ------------------------------------------------
+
+    async def current_budgets(self, tenant: str = DEFAULT_TENANT) -> list[dict]:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                f"SELECT {BUDGET_SELECT} FROM budget_view WHERE tenant_id = %s "
+                f"ORDER BY scope, key", (tenant,))
+            return [_row_to_budget(r) for r in await cur.fetchall()]
+
+    async def budget_for(self, scope: str, key: str,
+                         tenant: str = DEFAULT_TENANT) -> dict | None:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                f"SELECT {BUDGET_SELECT} FROM budget_view "
+                f"WHERE tenant_id = %s AND scope = %s AND key = %s",
+                (tenant, scope, key))
+            row = await cur.fetchone()
+        return _row_to_budget(row) if row else None
+
+    # -- budgets: write ------------------------------------------------------
+
+    async def set_budget(self, scope: str, key: str, *, window: str,
+                         on_exceed: str, by: str, reason: str = "",
+                         max_usd: float | None = None,
+                         max_tokens: int | None = None,
+                         tenant: str = DEFAULT_TENANT) -> dict:
+        if scope not in SCOPES:
+            raise ValueError(f"scope must be one of {SCOPES}")
+        if window not in WINDOWS:
+            raise ValueError(f"window must be one of {WINDOWS}")
+        if on_exceed not in ON_EXCEED:
+            raise ValueError(f"on_exceed must be one of {ON_EXCEED}")
+        await self.ledger.append("budget_set", {
+            "scope": scope, "key": key, "window": window,
+            "on_exceed": on_exceed, "max_usd": max_usd,
+            "max_tokens": max_tokens, "by": by, "reason": reason},
+            tenant=tenant)
+        budget = await self.budget_for(scope, key, tenant)
+        assert budget is not None  # just appended
+        return budget
+
+    # -- spend: live fold from run_event usage -------------------------------
+
+    async def spend(self, scope: str, key: str, window: str,
+                    tenant: str = DEFAULT_TENANT,
+                    now: float | None = None,
+                    run_id: str | None = None) -> dict:
+        """Fold run_event model_decision usage into {usd, tokens} for the
+        scope over the active window.
+
+        - daily/monthly: usage since the window start (calendar-aligned, UTC).
+        - per_run: usage of a SINGLE run (`run_id`). At request time the run
+          has already spent on prior decisions, so a per_run cap bounds a
+          run's accumulated spend and gates the next gated action once it is
+          crossed. Without a run_id (e.g. the aggregate spend report), per_run
+          has no single run to total, so it returns zero — it is enforced
+          live on the seam, not aggregated across runs.
+
+        For an action scope, a decision counts if it calls the budgeted action
+        as ANY of its tool calls (not just the first), and the decision's full
+        usage is charged to it. Charging in full is conservative — a decision
+        proposing the budgeted action errs toward the cap, never past it.
+        """
+        q = ("SELECT model, sum(input_tokens), sum(output_tokens) "
+             "FROM usage_view WHERE tenant_id = %s")
+        params: list = [tenant]
+        if window == "per_run":
+            if run_id is None:
+                return {"usd": 0.0, "tokens": 0}
+            q += " AND run_id = %s"
+            params.append(run_id)
+        else:
+            since = window_start_ms(window, now)
+            if since is not None:
+                q += " AND ts_ms >= %s"
+                params.append(since)
+        if scope == "action":
+            q += " AND %s = ANY(tools)"
+            params.append(key)
+        q += " GROUP BY model"
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(q, params)
+            rows = await cur.fetchall()
+        return self._totals(rows)
+
+    def _totals(self, rows) -> dict:
+        """{usd, tokens} from (model, input_tokens, output_tokens) rows:
+        the aggregate is SQL's; only the per-model price lookup is ours."""
+        usd = 0.0
+        tokens = 0
+        for model, inp, out in rows:
+            inp, out = int(inp or 0), int(out or 0)
+            tokens += inp + out
+            rate = self.prices.get(model)
+            if rate:
+                usd += (inp * rate[0] + out * rate[1]) / 1_000_000
+        return {"usd": round(usd, 6), "tokens": tokens}
+
+    # -- enforcement: consulted on the approval seam -------------------------
+
+    async def check(self, action: str, tenant: str = DEFAULT_TENANT,
+                    now: float | None = None,
+                    run_id: str | None = None) -> dict:
+        """Does this request's action breach a budget? Returns
+        {exceeded, on_exceed, scope, key, spent, limit} — a decision the seam
+        turns into a gate or a deny.
+
+        BOTH the action budget and the tenant `*` cap are evaluated (not just
+        the most specific), so a tenant-wide backstop holds even when the
+        action has its own sub-budget. If either is exceeded, the strictest
+        wins: deny beats gate. The no-budget posture is the client's choice
+        (cost_default_posture)."""
+        verdicts = []
+        any_rule = False
+        for scope, key in (("action", action), ("tenant", "*")):
+            rule = await self.budget_for(scope, key, tenant)
+            if rule is None:
+                continue
+            any_rule = True
+            spent = await self.spend(scope, key, rule["window"], tenant, now,
+                                     run_id)
+            verdicts.append({
+                "exceeded": self._over(rule, spent),
+                "on_exceed": rule["on_exceed"], "scope": scope, "key": key,
+                "window": rule["window"], "spent": spent,
+                "limit": {"usd": rule["max_usd"],
+                          "tokens": rule["max_tokens"]}})
+
+        exceeded = [v for v in verdicts if v["exceeded"]]
+        if exceeded:
+            # deny beats gate; among same on_exceed, the most specific reports
+            deny = [v for v in exceeded if v["on_exceed"] == "deny"]
+            return deny[0] if deny else exceeded[0]
+        if any_rule:
+            return verdicts[0]  # rules exist, all under budget: passes
+        # no budget covers this action: the client posture decides
+        if self.settings.cost_default_posture == "closed":
+            return {"exceeded": True, "on_exceed":
+                    self.settings.cost_default_on_exceed, "scope": "default",
+                    "key": action, "window": None, "spent": None,
+                    "limit": None}
+        return {"exceeded": False, "on_exceed": None, "scope": "none",
+                "key": action, "window": None, "spent": None, "limit": None}
+
+    @staticmethod
+    def _over(rule: dict, spent: dict) -> bool:
+        if rule.get("max_usd") is not None and spent["usd"] >= rule["max_usd"]:
+            return True
+        if (rule.get("max_tokens") is not None
+                and spent["tokens"] >= rule["max_tokens"]):
+            return True
+        return False
+
+    # -- spend report (console) ----------------------------------------------
+
+    async def spend_report(self, tenant: str = DEFAULT_TENANT,
+                           now: float | None = None) -> dict:
+        """Spend vs budget per scope, plus the routing mix (which model ran).
+        A read/fold, no cached counters."""
+        budgets = await self.current_budgets(tenant)
+        lines = []
+        for b in budgets:
+            spent = await self.spend(b["scope"], b["key"], b["window"],
+                                     tenant, now)
+            lines.append({**b, "spent": spent,
+                          "over": self._over(b, spent)})
+
+        # routing mix across the tenant's ingested decisions: one GROUP BY
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT model, count(*), sum(input_tokens), sum(output_tokens) "
+                "FROM usage_view WHERE tenant_id = %s GROUP BY model",
+                (tenant,))
+            rows = await cur.fetchall()
+        mix: dict[str, dict] = {}
+        for model, n, inp, out in rows:
+            t = self._totals([(model, inp, out)])
+            mix[model] = {"decisions": int(n), "tokens": t["tokens"],
+                          "usd": t["usd"]}
+        return {"budgets": lines, "routing_mix": mix}
+
+    # -- evals & gate decisions: ingest (not re-score) -----------------------
+
+    async def record_eval(self, agent: str, version: str, *, profile: dict,
+                          scenarios, by: str,
+                          tenant: str = DEFAULT_TENANT) -> None:
+        await self.ledger.append("eval_recorded", {
+            "agent": agent, "version": version, "profile": profile,
+            "scenarios": scenarios, "by": by}, tenant=tenant)
+
+    async def record_gate(self, agent: str, version: str, *, passed: bool,
+                          baseline_version: str | None, blocks,
+                          by: str, reason: str = "", override: bool = False,
+                          tenant: str = DEFAULT_TENANT) -> dict:
+        """Append a gate decision. Immutability is decided INSIDE the append
+        transaction, under the governance chain's advisory lock: a
+        check-then-append across two transactions would let two racing CI
+        jobs both see "undecided" and the second (last-write-wins in
+        gate_view) silently flip the first — the exact bypass the admin
+        override exists to prevent. Raises GateAlreadyDecided unless
+        `override` (the admin path, itself audited)."""
+        from .ledger.store import APPEND_LOCK, GOVERNANCE_CHAIN
+
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                await conn.execute(
+                    "SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
+                    (APPEND_LOCK, f"{tenant}:{GOVERNANCE_CHAIN}"))
+                if not override:
+                    existing = await self._gate_verdict_conn(
+                        conn, agent, version, tenant)
+                    if existing is not None:
+                        raise GateAlreadyDecided(existing)
+                await self.ledger._append_in_tx(conn, "gate_decision", {
+                    "agent": agent, "version": version, "passed": bool(passed),
+                    "baseline_version": baseline_version,
+                    "blocks": blocks or [], "override": bool(override),
+                    "by": by, "reason": reason}, tenant=tenant)
+        verdict = await self.gate_verdict(agent, version, tenant)
+        assert verdict is not None  # just appended
+        return verdict
+
+    async def _gate_verdict_conn(self, conn, agent: str, version: str,
+                                 tenant: str) -> dict | None:
+        cur = await conn.execute(
+            "SELECT passed, baseline_version, blocks, override, "
+            "decided_by, reason, decided_ts_ms FROM gate_view "
+            "WHERE tenant_id = %s AND agent = %s AND version = %s",
+            (tenant, agent, version))
+        row = await cur.fetchone()
+        if row is None:
+            return None
+        return {"agent": agent, "version": version, "passed": row[0],
+                "baseline_version": row[1], "blocks": row[2],
+                "override": row[3], "decided_by": row[4], "reason": row[5],
+                "decided_ts_ms": row[6]}
+
+    async def gate_verdict(self, agent: str, version: str,
+                           tenant: str = DEFAULT_TENANT) -> dict | None:
+        async with self.pool.connection() as conn:
+            return await self._gate_verdict_conn(conn, agent, version, tenant)
+
+    async def history(self, agent: str | None = None,
+                      version: str | None = None,
+                      tenant: str = DEFAULT_TENANT, limit: int = 500,
+                      before: int | None = None) -> list[dict]:
+        """Newest first, cursor-paged: pass the last row's `id` as `before`
+        for the next page. A page, never a silent cap on the whole."""
+        q = ("SELECT kind, agent, version, detail, ts_ms, id FROM eval_history "
+             "WHERE tenant_id = %s")
+        params: list = [tenant]
+        if agent:
+            q += " AND agent = %s"
+            params.append(agent)
+        if version:
+            q += " AND version = %s"
+            params.append(version)
+        if before is not None:
+            q += " AND id < %s"
+            params.append(before)
+        q += " ORDER BY id DESC LIMIT %s"
+        params.append(max(1, min(limit, HISTORY_MAX_LIMIT)))
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(q, params)
+            rows = await cur.fetchall()
+        return [{"id": r[5], "kind": r[0], "agent": r[1], "version": r[2],
+                 "detail": r[3] if isinstance(r[3], dict) else json.loads(r[3]),
+                 "ts_ms": r[4]} for r in rows]

app/db.py

@@ -0,0 +1,56 @@
+"""Async Postgres pool and migrations runner."""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from psycopg_pool import AsyncConnectionPool
+
+from .config import Settings
+
+# the migrations ship INSIDE the package (app/migrations, app/alembic.ini),
+# so an installed wheel migrates exactly like a source checkout
+PKG_DIR = Path(__file__).resolve().parent
+MIGRATIONS_DIR = PKG_DIR / "migrations"
+
+
+def _alembic_config(url: str | None = None):
+    from alembic.config import Config
+
+    cfg = Config(str(PKG_DIR / "alembic.ini"))
+    cfg.set_main_option("script_location", str(MIGRATIONS_DIR))
+    if url is not None:
+        cfg.set_main_option("sqlalchemy.url", url)
+    return cfg
+
+
+def _upgrade_sync(settings: Settings) -> None:
+    from alembic import command
+
+    command.upgrade(_alembic_config(settings.alembic_url), "head")
+
+
+def migrate_main() -> None:
+    """`primarypath-migrate`: alembic upgrade head from PRIMARYPATH_* settings
+    (the Helm pre-install/pre-upgrade Job, or an operator's shell)."""
+    from .config import get_settings
+
+    settings = get_settings()
+    _upgrade_sync(settings)
+    print(f"migrated to {head_revision()}")
+
+
+async def run_migrations(settings: Settings) -> None:
+    """Idempotent: alembic upgrade head, run off the event loop."""
+    await asyncio.to_thread(_upgrade_sync, settings)
+
+
+def head_revision() -> str | None:
+    """The newest migration in the tree (what /readyz requires the DB to be at)."""
+    from alembic.script import ScriptDirectory
+
+    return ScriptDirectory.from_config(_alembic_config()).get_current_head()
+
+
+def make_pool(settings: Settings) -> AsyncConnectionPool:
+    return AsyncConnectionPool(settings.database_url, min_size=1, max_size=10, open=False)

app/faults.py

@@ -0,0 +1,26 @@
+"""Test-only crash injection for the F12 hardening harness.
+
+When PRIMARYPATH_FAULT names a fault point, reaching that point hard-crashes the
+process (os._exit: no cleanup, no flushing — the closest thing to a power
+cut we can do deterministically). A production deployment never sets
+PRIMARYPATH_FAULT, making every hook a no-op comparison against None.
+
+Fault points wired into the service:
+- after_event_insert_before_commit   inside the append tx, after INSERT
+- before_projection_update           inside the append tx, before the view write
+- after_append_commit_before_http    create committed, response never sent
+- after_decision_commit_before_reflect  decision committed, Slack/webhook not told
+- after_write_commit_before_http     an annotate / incident / cancel / redeem /
+                                     ingest committed, response never sent (the
+                                     Idempotency-Key replay tests)
+"""
+from __future__ import annotations
+
+import os
+
+_ACTIVE = os.environ.get("PRIMARYPATH_FAULT")
+
+
+def fault_point(name: str) -> None:
+    if _ACTIVE is not None and _ACTIVE == name:
+        os._exit(1)

app/grants.py

@@ -0,0 +1,122 @@
+"""Signed execution grants: the approve→execute seam.
+
+The chain proves that an approval happened for a digest-bound action. A
+grant lets the EXECUTOR — the MCP gateway or a tool proxy that holds the
+tool credentials, never the agent — prove that the action it is about to
+run is the one that was approved, and run it exactly once:
+
+- minted inside the granting transaction and stamped into the
+  `approval_granted` payload, so the chain carries the grant itself;
+- Ed25519-signed by the audit signer (the same key ring auditors pin
+  from `/api/audit/keys`), so an executor verifies it OFFLINE;
+- bound to approval_id + tenant + agent + tool + action_digest + issue
+  and expiry time + a random nonce;
+- redeemed ONLINE exactly once: `POST /api/approvals/{id}/redeem` under
+  the chain lock appends `grant_redeemed`; a second redemption, an
+  expired grant, or a nonce that does not match is refused.
+
+The signed record is the RFC 8785 (JCS) form of SIGNED_FIELDS; `key_id`
+and `signature` ride alongside. The SDKs (Python `verify_grant`, TypeScript
+`verifyGrant`) recompute the record and the action digest from the
+arguments the executor is about to dispatch, so a substituted argument
+fails before any tool runs.
+"""
+from __future__ import annotations
+
+import base64
+import secrets
+import time
+
+from .jcs import jcs
+from .ledger.store import action_digest
+
+GRANT_VERSION = 1
+
+# the fields the signature commits to, in the order they are documented
+SIGNED_FIELDS = ("v", "approval_id", "tenant", "agent_id", "tool",
+                 "action_digest", "issued_ms", "expires_ms", "nonce")
+
+
+def grant_message(grant: dict) -> bytes:
+    """The exact bytes that were (or must be) signed."""
+    return jcs({k: grant[k] for k in SIGNED_FIELDS}).encode("utf-8")
+
+
+def digest_of(approval: dict) -> str:
+    """The approval's action digest: the one stamped in the chain, or —
+    for approvals requested before the stamp existed — recomputed from
+    the same immutable fields, so a grant always binds a digest."""
+    return approval.get("action_digest") or action_digest(
+        approval["tool"], approval.get("arguments"), approval.get("reasoning"),
+        approval.get("framework"), approval.get("callback_url"))
+
+
+class GrantMinter:
+    """Mints grants with the deployment's audit signer. `ttl_s` is how
+    long an executor has to redeem after the decision: short, because a
+    grant is a bearer capability for one consequential action."""
+
+    def __init__(self, signer, ttl_s: int):
+        self.signer = signer
+        self.ttl_s = ttl_s
+
+    def mint(self, approval: dict, tenant: str,
+             now_ms: int | None = None) -> dict:
+        now_ms = int(time.time() * 1000) if now_ms is None else now_ms
+        grant = {
+            "v": GRANT_VERSION,
+            "approval_id": approval["approval_id"],
+            "tenant": tenant,
+            "agent_id": approval.get("agent_id") or "default",
+            "tool": approval["tool"],
+            "action_digest": digest_of(approval),
+            "issued_ms": now_ms,
+            "expires_ms": now_ms + self.ttl_s * 1000,
+            "nonce": secrets.token_hex(16),
+        }
+        sig = self.signer.backend.sign(grant_message(grant))
+        grant["key_id"] = self.signer.key_id
+        grant["signature"] = base64.b64encode(sig).decode()
+        return grant
+
+
+class GrantInvalid(Exception):
+    """A grant that must not be honored, and why."""
+
+
+def verify_grant(grant: dict, keys: dict[str, str], *,
+                 now_ms: int | None = None,
+                 approval_id: str | None = None,
+                 tool: str | None = None,
+                 expected_digest: str | None = None) -> None:
+    """Offline verification against a public-key ring (`key_id` ->
+    base64 raw Ed25519 public key). Raises GrantInvalid. The server uses
+    it only as a self-check; the SDKs carry the executor-side twin."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric import ed25519
+
+    if not isinstance(grant, dict) or grant.get("v") != GRANT_VERSION:
+        raise GrantInvalid("unsupported grant version")
+    missing = [k for k in SIGNED_FIELDS + ("key_id", "signature")
+               if k not in grant]
+    if missing:
+        raise GrantInvalid(f"grant is missing {', '.join(missing)}")
+    pub = keys.get(grant["key_id"])
+    if pub is None:
+        raise GrantInvalid(f"unknown signing key {grant['key_id']}")
+    try:
+        ed25519.Ed25519PublicKey.from_public_bytes(
+            base64.b64decode(pub)).verify(
+            base64.b64decode(grant["signature"]), grant_message(grant))
+    except (InvalidSignature, ValueError):
+        raise GrantInvalid("signature does not verify") from None
+    now_ms = int(time.time() * 1000) if now_ms is None else now_ms
+    if now_ms > int(grant["expires_ms"]):
+        raise GrantInvalid("grant has expired")
+    if approval_id is not None and grant["approval_id"] != approval_id:
+        raise GrantInvalid("grant is for a different approval")
+    if tool is not None and grant["tool"] != tool:
+        raise GrantInvalid(f"grant is for tool {grant['tool']}, not {tool}")
+    if expected_digest is not None and grant["action_digest"] != expected_digest:
+        raise GrantInvalid("grant binds a different action digest than the "
+                           "one about to execute")

app/idempotency.py

@@ -0,0 +1,58 @@
+"""Operation idempotency keys: retry any write safely.
+
+A client that may lose a response (an agent pausing for days behind a
+flaky network) sends `Idempotency-Key: <its own unique key>` on a
+mutating request and REPEATS the same key on every retry of that one
+logical operation. The server records the key inside the transaction
+that appends the operation's events, together with a fingerprint of
+who asked for what, and the result it returned. A retry with the same
+key and the same fingerprint gets the recorded result back — the same
+annotation, the same decision, the same redeemed grant — and writes
+nothing; the same key with a different fingerprint is refused, because
+a key names one operation.
+
+Approval creation is idempotent by its own id and needs no key; every
+other write accepts one. The SDKs generate a key per call.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+from fastapi import HTTPException, Request
+
+from .auth import credential_id, resolve_tenant
+from .jcs import jcs
+
+HEADER = "Idempotency-Key"
+KEY_MAX = 200
+
+
+class IdempotencyMismatch(Exception):
+    """The key was already used for a different request."""
+
+
+@dataclass(frozen=True)
+class Idem:
+    key: str
+    fingerprint: str
+
+
+async def idempotency_of(request: Request, body) -> Idem | None:
+    """The request's Idem, or None when it carries no key. The
+    fingerprint binds the key to tenant, credential, method, path and the
+    canonical body, so a key cannot be replayed across any of them."""
+    key = request.headers.get(HEADER)
+    if key is None:
+        return None
+    key = key.strip()
+    if not key or len(key) > KEY_MAX:
+        raise HTTPException(400, f"{HEADER} must be 1-{KEY_MAX} characters")
+    record = {
+        "tenant": await resolve_tenant(request),
+        "credential": await credential_id(request),
+        "method": request.method,
+        "path": request.url.path,
+        "body": body,
+    }
+    return Idem(key, hashlib.sha256(jcs(record).encode("utf-8")).hexdigest())