chain-of-custody

name

chain-of-custody

description

Use when changing anything in loopctl's trust model — role requirements, the auth pipeline, story lifecycle transitions (report / review-complete / verify), capability tokens, dispatch lineage, WebAuthn/human-anchor gates, or the audit chain. Covers who may do what, why the self-* 409s are correct, and the capability/dispatch mechanics. Triggers on: chain of custody, self_report_blocked, self_review_blocked, self_verify_blocked, RequireRole, role hierarchy, capability token, dispatch, lineage, WebAuthn, human anchor, custody halt, superadmin, orchestrator, agent role, verify_story, report_story.

Chain of Custody & Trust Model

loopctl's core product guarantee: nobody marks their own work as done. An agent implements, an independently-lineaged verifier confirms. Weakening any custody gate is the single most dangerous change class here. Full spec: docs/chain-of-custody-v2.md (Epic 26). This skill is the code map + invariants — read the cited code and the spec before touching auth/custody.

Role hierarchy — superadmin (4) > user (3) > orchestrator (2) > agent (1)

Ranks (@role_levels, :12) and role_at_least?/2 (:34) live in lib/loopctl/auth/role.ex; enforcement is the LoopctlWeb.Plugs.RequireRole plug (lib/loopctl_web/plugs/require_role.ex).

Hierarchy inheritance applies ONLY to role: gates. The plug has a second mode, exact_role: (a single atom or a list), which does NO hierarchy — a HIGHER role is 403'd like any other non-member (require_role.ex:37-70). Every chain-of-custody endpoint is exact-role gated, so escalating to a bigger key never clears a 403 there:

Endpoint	Gate
verify / reject / force_unclaim / verify_all	exact_role: :orchestrator (story_verification_controller.ex:28-29) — a superadmin key CANNOT verify
contract / report	exact_role: [:agent, :orchestrator] (story_status_controller.ex:26-30) — a human user key CANNOT report
claim / start / request-review / unclaim	exact_role: :agent (story_status_controller.ex:32-33)
review-complete	exact_role: [:orchestrator, :user] (review_record_controller.ex:22-23) — an agent key never reaches the controller

Anti-pattern: never "normalize" an exact_role custody gate to role:. That is exactly what would let one high-privilege key both implement and report/verify.

Human-rooted operations additionally pass RequireHumanAnchor (lib/loopctl_web/plugs/require_human_anchor.ex), which gates on the TENANT's trust_tier and is deliberately orthogonal to role (:4, :9). Three branches, in order:

1. current_tenant: nil — a superadmin key that is NOT impersonating — passes unconditionally, no tier evaluated (:44-49). Impersonate reassigns current_tenant before controller plugs run, so an impersonated agent-rooted tenant IS still gated.
2. trust_tier: :human_anchored passes (:51).
3. Everything else — a catch-all, which covers :agent_rooted AND a missing current_tenant assign — halts with 403 custody_tier_required (:55, :61).

It is not a per-request WebAuthn check — WebAuthn is how a tenant EARNS :human_anchored. Keying on tier rather than role is what closes the self-minted-key bypass. The plug is in NO router pipeline — it is opt-in per controller (e.g. story_verification_controller.ex:35, dispatch_controller.ex:16, artifact_report_controller.ex:30), so a new human-rooted endpoint gets NO trust-tier gate unless you add the plug line yourself.

Where the line sits (CLAUDE.md "Security & Trust Model" checklist — the authority):

• role: :user (or WebAuthn): anything IRREVERSIBLE or that is itself a custody gate — tenant/:work-project delete, budget/token corrections, cost-anomaly resolution, audit-key rotation, break-glass. On the KB surface the :user set is single-article unpublish plus ALL the set-based bulk ops — bulk_publish, bulk_unpublish and the ENTIRE bulk_delete action, soft path included (article_workflow_controller.ex:37-39). Two criteria hold that line: set-based blast radius (one call mutates an unbounded set) AND irreversibility (bulk_delete carries a hard-delete path). Neither criterion alone is the rule — do not drop reversibility when reasoning about a new op.
• role: :orchestrator: constructive/metadata work-breakdown (create/update epics, stories, deps, imports, backfills) so an autonomous orchestrator composes projects without a human. Also KB drafts / single-article publish (article_workflow_controller.ex:33).
• role: :agent: read work-breakdown only; KB-content curation is the carve-out — create/update/ soft-archive/resolve-conflict are agent-role because each is reversible + audited (see knowledge-wiki).
• role: :agent, human-anchor-EXEMPT: :kb-kind project scopes — create_kb_scope, archive_kb_scope, restore_kb_scope (project_controller.ex:25-35), deliberately outside RequireHumanAnchor (project_controller.ex:37-41) because a :kb scope carries no chain-of-custody surface (RequireWorkProject bars work attachment). Extends owner decision #331. An existing agent-role kb-scope archive is NOT a custody violation. :work projects stay :orchestrator/:user + anchored.

Rule of thumb before lowering any role: does this let one session both implement AND verify/report? If yes, the change is wrong.

The self-* gates — the 409s are the system working

Enforced in lib/loopctl/progress.ex. The three gates are NOT one implementation, but ALL THREE now compare dispatch lineage and all three fail closed on a story with no custody provenance. The caller's lineage is always resolved SERVER-SIDE from the authenticating key (Dispatches.lineage_for_api_key/2, dispatches.ex:518-528) — never read from the request body.

• verify — validate_not_self_verify/2 progress.ex:1743-1776. nil orchestrator identity is untrusted (progress.ex:1743); a custody-orphaned story fails closed with :missing_assigned_agent (progress.ex:1758-1760, "nil is never permissive"); the lineage clause runs when BOTH implementer_dispatch_id and verifier_dispatch_id are set (progress.ex:1763-1767), decided by verify_lineage_separated/4 (progress.ex:1786-1806). An EMPTY lineage on either side (what an unloadable dispatch yields, get_dispatch_lineage/2 progress.ex:1808-1813) fails CLOSED, and the assigned_agent_id equality check runs IN ADDITION to the lineage comparison rather than being short-circuited by it. verifier_dispatch_id is written only by the assign-verifier flow (assign_rotating_verifier/3, progress.ex:363-396); that write is result-checked, and a failure flags verifier_needed plus a verifier_not_assigned audit event (flag_verifier_needed/5, progress.ex:401-425) instead of silently leaving the field nil. With no verifier dispatch the gate is agent-id equality.
• report — validate_not_self_report/3 progress.ex:2268-2294. nil caller blocked (progress.ex:2268); a story with nil assigned_agent_id AND nil implementer_dispatch_id is custody-unattributed and fails closed with :missing_assigned_agent + a custody_orphaned_blocked log (custody_unattributed?/1, progress.ex:2307-2310) — it used to pass vacuously; then the reporter's lineage vs the implementer's (lineage_status/2, progress.ex:2339-2357) — tri-state :ok | :conflict | :unresolvable, where an unresolvable implementer dispatch fails CLOSED with unresolvable_dispatch_lineage (LCP-1 §7.5); then plain assigned_agent_id equality.
• review-complete — validate_not_self_review/3 progress.ex:2359-2389. Custody-orphan backstop first (progress.ex:2366-2368), then a nil reviewer is deliberately PERMITTED (progress.ex:2375-2376) because nil means a human operator on a user-role key; then the reviewer's lineage; then plain equality. That nil permit has THREE parts, all of which must change together: (a) the exact_role: [:orchestrator, :user] plug (review_record_controller.ex:22-23), which 403s an agent key before the controller runs — so the :agent branch of the controller cond is unreachable today; (b) LoopctlWeb.ReviewRecordController.create/2 (lib/loopctl_web/controllers/review_record_controller.ex:92-116), which rejects an orchestrator key with no agent_id and passes a literal nil (there is NO sentinel) for a user key; (c) the Progress permit itself.

Custody-orphan predicates are the ONLY guard for the never-dispatched case. The DB CHECK stories_reported_done_requires_agent is satisfied whenever implementer_dispatch_id IS NULL, which is exactly the orphaned shape — do not delete custody_orphaned?/1 or custody_unattributed?/1 as redundant with the constraint.

The MCP server must NEVER hold both an implementer and a reviewer key in one process — the 409s are correct behavior; do not add a workaround.

Capability tokens (L1) — signed, scoped, single-use

lib/loopctl/capabilities.ex:

• mint/4 (capabilities.ex:32-57) — per-(typ, story_id, lineage) token (start_cap / report_cap / verify_cap / review_complete_cap), signed, nonce'd, bounded TTL.
• verify/2 (capabilities.ex:67-84), decided by validate_cap/6 (capabilities.ex:125-135) — type match + story match + lineage exact match + not-expired + not-consumed + a valid ed25519 signature over the token fields, checked against the tenant's audit_signing_public_key (verify_signature/2, capabilities.ex:137-164, which returns false — fails CLOSED — when the tenant has no pubkey). There is NO "nonce exists" check; the nonce is an input to the signed message. The signature is the ONLY cryptographic check — never remove it as ceremony.
• consume/1 (capabilities.ex:91-104) — atomic update_all ... where consumed_at IS NULL; the {0, _} branch returns :replay. This is the TOCTOU-safe single-use guard — never replace it with a read-then-write.

Enforcement is conditional — this is the deprecation seam. Progress.maybe_consume_cap/6 (progress.ex:323-346) is what actually gates the custody ops: a nil cap_id is rejected with :missing_capability only for tenants that have an audit key (tenant_has_audit_key?/1, progress.ex:425-431); a pre-v2 (keyless) tenant returns {:ok, :pre_v2_tenant} and the operation proceeds with NO capability at all. So L1 strength is per-tenant. That branch now emits a pre_v2_custody_bypass warning plus a [:loopctl, :custody, :pre_v2_bypass] telemetry event, so the degraded tenants are observable — alert on the count. Do not "simplify" the clause: removing the audit-key condition either breaks pre-v2 tenants or silently widens the bypass.

Dispatch lineage (L4) — structural verifier separation

lib/loopctl/dispatches.ex: each dispatch carries a lineage_path (root → self). lineage_shares_prefix?/2 (dispatches.ex:587-591) is the primitive the self-* checks use — note it compares lineage ROOTS (element 0) only, not arbitrary prefixes, and an empty list on either side is never a match. select_verifier/3 (dispatches.ex:613-650) picks a verifier whose lineage does NOT share the implementer's root — rejected in SQL (reject_same_root/2, dispatches.ex:658-664) and again in Elixir — from a pool capped at @verifier_pool_limit, seeded deterministically by sha256(tenant audit pubkey || story_id) so the orchestrator cannot predict the pick.

Empty-lineage caveat, in BOTH directions. When the implementer dispatch cannot be loaded, assign_rotating_verifier/3 passes [] (progress.ex:363-367), and with [] the rejection is inert — selection can then pick a same-lineage (even the implementer's own) dispatch. The verify-time comparison is fail-closed on an empty lineage, so this is caught at verify rather than at selection; do not "simplify" either half.

Ephemeral per-dispatch keys (minted via POST /api/v1/dispatches, MCP dispatch tool) replace long-lived env-var keys.

Anti-patterns

• Lowering a role on a destructive/custody endpoint "for convenience" — re-check the CLAUDE.md checklist.
• "Fixing" a self_*_blocked 409 by sharing keys or collapsing lineage — that defeats the product.
• A capability consume that isn't the atomic conditional update — reintroduces replay.
• New table in the audit/custody path without the hash-chain / DB CHECK backstops (audit_chain/).
• Adding a new human-rooted endpoint WITHOUT an explicit plug RequireHumanAnchor line — the plug is per-controller opt-in, not pipeline-wide, so the gate is silently absent.
• Using a dispatched sub-agent to report or review-complete its PARENT's work — all three gates now compare lineage, so this is blocked; do not "route around" it by minting a key outside the lineage.
• Taking the caller's lineage from request params instead of Dispatches.lineage_for_api_key/2 — a client-supplied lineage is self-attested and defeats the gate.
• Trusting a nil identity as permissive where the code blocks it — verify (progress.ex:1743) and report (progress.ex:2268) fail closed on nil caller identity. The one documented exception is review-complete (progress.ex:2375-2376, nil = human operator, paired with the exact_role plug and the controller check). Do not "fix" it without reading its comment.

Related

• tenancy-rls — custody writes/consume run on AdminRepo (BYPASSRLS: an explicit tenant_id predicate is the ONLY isolation). Custody READS fetch by (id, tenant_id); Capabilities.consume/1 (capabilities.ex:91-104) is id-only — its update_all filters on c.id alone (:97-98) and inherits its tenant scoping from the verify/2 that fetched the row. Never call it on a row you did not fetch tenant-scoped.
• knowledge-wiki — the KB-content carve-out (#331) is the one agent-role exception to archive/delete⇒:user.
• Security review of a custody change: dispatch the global security-adversary agent.