id: design: issuer key rotation and compromise recovery for currency issuers (from #2041)

From the #2041 investigation (token issuance in the ID graph)

The landed investigation doc for #2041 (doc/2026-10-30T19-18-00Z_investigation_token_issuance_id_graph/, §10 case 7) identifies issuer key compromise as the catastrophic case for any issuer system: an attacker mints/converts as the issuer until the compromise is noticed. The model names the mitigations — supply caps bound mint damage, registries/views can pin issuer key generations — but the rotation mechanics were explicitly not designed. This issue designs them, so the #2043 synthesis adopts a designed answer instead of an afterthought.

Design to produce

Signed rotation object: format and chain semantics for an issuer key rotation (old key names successor), as an ID-graph object consistent with the signed-event envelope in pkgs/id/src/chain.rs; what happens to currency definitions issued pre-rotation (investigation position: they keep their identity — verify or amend).
Counting-view pinning: how counting views (id: investigate: trust/visibility model — servers accept all signed objects; views count only allowed writers #2030) and wallets pin which issuer key generation(s) they count for a currency, and how a view learns of a rotation/compromise.
Anchored path handling: registry/gateway treatment of rotation and of a declared compromise — minter-set updates via signed registry writes (id: design: currency control plane — registry, account factory, gateway #2062 §2.5), in-flight issuance/conversion treatment, and the compromise-declaration flow (who can declare, what freezes, what stays valid).
Graph-native path handling: the same questions where there is no gateway to enforce anything.

Acceptance criteria

Design recorded in a doc under doc/ (or in pkgs/id/doc/ if the id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251 spec has set that convention by then) and linked from this issue
Rotation object + pinning rules specified precisely enough for id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251's wire-format spec and the id: design: currency control plane — registry, account factory, gateway #2062 gateway follow-ups to implement against
Compromise walkthrough: attacker mints with a stolen issuer key — what is bounded by caps, what the rotation/compromise declaration stops, what remains exposed
Anything buildable that falls out is filed as its own issue(s)

Program: ID platform expansion, epic #2056. Parent investigation: #2041. Related: #2251 (object-format spec), #2062 (control plane), #2030 (counting views), #2043 (currencies v1 synthesis — consumes the outcome).

Intake review

Related: from the id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041 token-issuance investigation (doc §10 case 7); synthesis consumer id: design: ID currencies v1 #2043; counting views id: investigate: trust/visibility model — servers accept all signed objects; views count only allowed writers #2030.
Notes: The body already contains an acceptance-criteria discussion, so no body edit in this pass — labels only (priority/effort/kind/status were missing) plus this comment. Still live: rotation mechanics are explicitly undesigned, and key compromise is the catastrophic case for issuers, so this design should not drift.
Risks: A rotation design that invalidates pre-rotation currency definitions would break the identity guarantee the investigation recorded; the verify-or-amend point in the body is the crux.
Suggested approach: Design the signed rotation object against pkgs/id/src/chain.rs envelope semantics first, then counting-view pinning; record the adoption decision on id: design: ID currencies v1 #2043.

agent-note:v1 — task 5743 design triage record (lane A shift, 2026-11-01). Decision-ready record for issuer key rotation + compromise recovery, from the #2041 investigation (doc doc/2026-10-30T19-18-00Z_investigation_token_issuance_id_graph/, §10 case 7, §11 hand-off). Consumer: the #2043 currencies v1 synthesis (OPEN, gated on this outcome among its inputs).

Grounding (verified today, main `51919e9`)

No issuer or currency implementation exists in pkgs/id/src yet — this is a design-first topic; nothing shipped constrains the mechanics.
The signed-event envelope the rotation object must use exists: pkgs/id/src/chain.rs — Event (:262) and sign() (:282).
The investigation position (§10 case 7), adopted unless amended below: supply caps bound mint damage even with a stolen key; rotation is a signed object (old key names successor); definitions issued pre-rotation keep their identity; registries/views pin which issuer key generation they count.

The decision

The exact format/chain semantics of the rotation object, the pinning rules counting views apply, and the compromise-declaration flow — for both the anchored path (registry/gateway, #2062) and the graph-native path (no enforcer).

Recommendation — the v1 design in one pass

Rotation object = one chain Event, dual-signed. Signed by the OLD key, naming: issuer identity, currency scope (one currency or all-of-issuer — per-currency is the default), successor public key, generation = previous + 1, and the effective frontier (the event position from which the successor is authoritative). Countersigned by the SUCCESSOR key (proof the successor is live and controlled). A rotation missing the countersignature is invalid, not advisory.
Generations are linear; a fork is a compromise signal. Two valid-looking rotations from the same generation cannot both be counted: a view counts the first in its frontier order and flags the conflict as a suspected compromise of that generation. No silent tie-breaking by timestamp (self-authored times prove nothing — the same honesty limit as the id: design: match attestation + audit v1 #2039 frontier rule).
Definitions keep their identity (investigation position: VERIFIED, adopted). A currency definition references the issuer identity, never a key generation. Historical issuance is judged against the generation that was authoritative at its own frontier — rotation alone never invalidates history.
Counting-view pinning. A view pins, per currency: the set of generations it counts (default: all non-compromised generations) plus the compromise frontier per compromised generation. Issuance under a generation BEFORE its compromise frontier counts; issuance AFTER it does not. A compromise declaration may assert an earlier compromise start; that earlier window becomes DISPUTED in the view (excluded from settled counts, visible as disputed) — never silently counted, never silently erased.
Compromise declaration needs a key the thief does not have. This is the crux, stated plainly: a declaration signed by the compromised key itself proves nothing (the thief holds it too). The design therefore has issuers pre-commit a recovery key hash in the currency definition (cold key, never used for minting). A compromise declaration is authoritative only when signed by the recovery key (which simultaneously names the successor generation, i.e. compromise recovery IS a recovery-key-signed rotation). A declaration signed by the current minting key alone is advisory: views and gateways MAY freeze on it, and must label the freeze as unproven.
Anchored path. The registry records the rotation via a signed registry write updating the minter set (id: design: currency control plane — registry, account factory, gateway #2062 §2.5 pattern), referencing the rotation event id. From the rotation frontier the gateway rejects mint/convert signatures from the old generation; conversions signed before the frontier settle; conversions signed after it are rejected, not queued. A compromise declaration (recovery-key-signed) freezes mint/convert for the compromised generation at the gateway immediately on receipt; pre-frontier history stays valid per rule 4.
Graph-native path. No enforcer exists, so nothing "stops" — the same objects are published to the graph and every view/wallet applies rules 2–5 locally. Wallet UX must surface generation status (current / rotated / compromised-disputed) wherever a balance is shown; a view that has not seen a rotation yet is simply behind, and its counts must name the frontier they were computed at.

Compromise walkthrough (acceptance scenario)

Attacker mints with a stolen issuer key. Bounded immediately by: the currency supply cap (mint damage ceiling even with the key — investigation §10 case 7). The issuer publishes a recovery-key-signed compromise rotation (rule 5): anchored gateways freeze the stolen generation on receipt (rule 6); counting views stop counting post-frontier issuance from it and mark the asserted-compromise window disputed (rule 4). Remains exposed, honestly: issuance between the actual theft and the declaration counts unless the declaration asserts the earlier start (then it is disputed, and counterparties decide) — no design without a trusted clock does better; conversion attempts with the stolen key after the frontier fail at gateways and do not count in pinned views.

Invariants

Rotation never rewrites history; generation forks are signals, not ties; no authoritative compromise state from the compromised key alone; every count names its frontier; caps are load-bearing and stay mandatory for issuers.

Phasing

task (below) — the full design doc under doc/ expanding this record to id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251-implementable precision (wire format via id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251, registry-write shape via id: design: currency control plane — registry, account factory, gateway #2062 §2.5), including the walkthrough as a worked example. That doc is this issue's own acceptance deliverable.
Everything buildable is downstream of currencies existing at all (id: design: ID currencies v1 #2043 synthesis + id: design: currency control plane — registry, account factory, gateway #2062 follow-ups own that build list); filing code packets now would packet ahead of the gated synthesis — stated explicitly rather than filed speculatively.

Question for Drew (explicit, non-blocking)

Recovery-key pre-commitment (rule 5): mandate it for registry-anchored currencies (recommended — without it, compromise recovery has no authoritative signer, and anchored issuance is exactly where real value concentrates), or make it optional everywhere (more graph-native in spirit; anchored issuers who skip it get advisory-only recovery)? Default until ruled: the recommendation — mandatory on the anchored path, optional graph-native. Ruling goes on this issue; the doc packet proceeds either way and records the ruling.

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-k
Session / ID: task 7983
Found via: queue claim
Task: Triage issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 (id: design: issuer key rotation and compromise recovery for currency issuers) — execution lane assigned to opencode; handed off to the laptop claimant (opencode-claimant), which launches the bound session that drives task 7983 to its terminal state.
Expectation: effort l; done = issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 triaged at current main with evidence, fix/design path scoped or closed with evidence.
Links: task 7983 · issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-h
Session / ID: task 7983
Found via: queue claim
Task: Triage issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 at current main — handed off to the opencode execution lane; the laptop claimant launches the bound opencode session, which drives task 7983 to its terminal state. Claim labels were already in sync on pickup (queue/claimed, work/assigned, status/in-progress).
Expectation: effort l; done = triaged at current main with evidence, fix/design path scoped or closed with evidence. Note: task 7983 is at attempt 5 of 6 — the claimant should complete it on this pass.
Links: queue task 7983 (repo-health-code-pilot)

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-f
Session / ID: task 7983
Found via: queue claim
Task: Handed off to the opencode execution lane; the laptop claimant launches the bound opencode session, which drives task 7983 to its terminal state. Resumed from checkpoint stage handed_off (prior handoff lease expired, where applicable). Fresh revalidation: issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 is OPEN, no hard-stop labels (held / user/owned / do-not-merge / do-not-auto-edit absent).
Expectation: effort l; done = worked per the task packet for issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 at current main, verified terminal state.
Links: issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane K (code-k)
Session / ID: task 7983
Found via: queue claim
Task: Handoff of task 7983 for issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 to the opencode claimant; fresh check confirms issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 OPEN, hard-stop labels: none, labels in claim set (work/assigned, queue/claimed, status/in-progress).
Expectation: claimant launches bound opencode session and drives task 7983 to terminal state
Links: issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane K (code-k)
Session / ID: task 7983
Found via: queue claim
Task: Handoff of task 7983 for issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 to the opencode claimant; fresh check confirms issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 OPEN, hard-stop labels: none, labels in claim set.
Expectation: claimant launches bound opencode session and drives task 7983 to terminal state
Links: issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-a
Session / ID: task 7983
Found via: queue claim
Task: task 7983 for issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 (triage) — execution lane assigned opencode; handed off to the laptop claimant (opencode-claimant), which launches the bound session that drives task 7983 to its terminal state.
Expectation: done = worked per the task packet at current main, verified terminal state.
Links: task 7983 · issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-j
Session / ID: task 7983 (triage)
Found via: queue claim (execution lane: opencode)
Task: Triage issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 — id design: issuer key rotation and compromise recovery for currency issuers (from id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041)
Expectation: handed off to the opencode claimant; it launches the bound session that drives task 7983 to a terminal state.
Findings (verified fresh 2026-11-04): issue id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804 is OPEN with no hard-stop labels; labels already show queue/claimed + status/in-progress + work/assigned. Attempt 13/24; the previous claim also handed off with session_id null.
Resume: claimant launches the bound opencode session for task 7983; if the lease lapses unlaunched, the task returns to the queue.

fix(id): carry the rotation in the signed extension; recovery resolve…

feat(id): issuer key rotation and compromise recovery — protocol core (…

🤖 Agent note · handed off

Agent: fleet monitor
Session / ID: task 7983 (repo-fleet-monitor run 2026-11-05T15:45:48Z)
Found via: monitor reconciliation (Duty 1 claim/label divergence repair)
Task: Claim evaporated: task 7983 is queued and unclaimed in repo-health-code-pilot, but this issue still carried claimed labels. Labels reset to the truth (queue/queued + status/needs-triage). Checkpoint stage at evaporation: handed_off.
Expectation: The next lane claim picks task 7983 up from the queued state and posts a fresh pickup note.

Navigation Menu

Repository navigation

id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

From the #2041 investigation (token issuance in the ID graph)

Design to produce

Acceptance criteria

Intake review

Grounding (verified today, main `51919e9`)

The decision

Recommendation — the v1 design in one pass

Compromise walkthrough (acceptance scenario)

Invariants

Phasing

Question for Drew (explicit, non-blocking)

80 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

id: design: issuer key rotation and compromise recovery for currency issuers (from #2041) #2804

Description

From the #2041 investigation (token issuance in the ID graph)

Design to produce

Acceptance criteria

Activity

dezren39 commented on Oct 31, 2026

Intake review

dezren39 commented on Nov 1, 2026

Grounding (verified today, main 51919e9)

The decision

Recommendation — the v1 design in one pass

Compromise walkthrough (acceptance scenario)

Invariants

Phasing

Question for Drew (explicit, non-blocking)

80 remaining items

dezren39 commented on Nov 3, 2026

dezren39 commented on Nov 3, 2026

dezren39 commented on Nov 3, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Grounding (verified today, main `51919e9`)