#742 batch B: holder-aware key ledger, and file content sealing follows the cluster key decision #1178

Closed
opened 2026-11-15 12:33:46 +00:00 by Cordy · 2 comments
Owner

Follow-up from #742 batch A (decided 2026-11-15; research .superpowers/sdd/2026-11-14-b9v07/research-742a-ledger.md option (d), and research-742a-rotation.md / review-n25 S4).

1. Holder-aware ledger. In batch A the shared key-drain ledger does not record which members held a retiring key. So after a rotation back-out on one member, an unchanged member on plain hosts must get the new key as recoveryIdentityLegacy before it restarts (batch A ships option (b+): records only make Cairn stricter). A ledger that records holders per key would let such restarts proceed safely without a config change. It must not trust unauthenticated records in external mode to remove protection.

2. Content follows the decision. File content and unfinished uploads are sealed with each member's own configured recipients, not the cluster-decided ones. During a rolling rotation in deployment custody, a member not yet updated cannot open files written through an updated one. These are read errors, not loss; batch A documents it in R9. Make content sealing follow keys.decision like state values do.

Research and decide via the playbook before building.

Follow-up from #742 batch A (decided 2026-11-15; research `.superpowers/sdd/2026-11-14-b9v07/research-742a-ledger.md` option (d), and `research-742a-rotation.md` / review-n25 S4). **1. Holder-aware ledger.** In batch A the shared key-drain ledger does not record which members held a retiring key. So after a rotation back-out on one member, an unchanged member on plain hosts must get the new key as `recoveryIdentityLegacy` before it restarts (batch A ships option (b+): records only make Cairn stricter). A ledger that records holders per key would let such restarts proceed safely without a config change. It must not trust unauthenticated records in external mode to *remove* protection. **2. Content follows the decision.** File content and unfinished uploads are sealed with each member's own configured recipients, not the cluster-decided ones. During a rolling rotation in deployment custody, a member not yet updated cannot open files written through an updated one. These are read errors, not loss; batch A documents it in R9. Make content sealing follow `keys.decision` like state values do. Research and decide via the playbook before building.
Author
Owner

Research: research-b10-r5-keys.md. It found a loss path: a member that wrote files with a new identity, then was backed out with that identity removed instead of kept as legacy, starts with no refusal. The ledger only learns keys in a legacy slot.

Decided for batch 10 (v0.6.411):

  • Holder-aware ledger. Holders are kept in the sealed ledger only. A member is refused only if it held the key and dropped it, or if no holder is left.
  • New command. cairnd cluster forget <name>, with an audit verb.
  • Content follows the cluster decision. All content paths follow it: files, link secrets, upload spool, drain fallback. The content drain answers 409 until the cluster seals with this member's keys.
  • Remote crypto role. Refused in coordination mode, with an issue for a later version.
  • "Activated" mark. Recorded now, used for wording only; the rule for never-activated keys is decided in v0.8.
  • instanceSeed. The docs say every member needs the same seed, and the key record publishes the derived fingerprint.
  • Audit verbs. key-drain-forced and key-drained.
  • Back-out warning. A WARN at start.

Rotation progress on the Overview (P5) goes to batch 11.

Research: `research-b10-r5-keys.md`. It found a loss path: a member that wrote files with a new identity, then was backed out with that identity removed instead of kept as legacy, starts with no refusal. The ledger only learns keys in a legacy slot. Decided for batch 10 (v0.6.411): - **Holder-aware ledger.** Holders are kept in the sealed ledger only. A member is refused only if it held the key and dropped it, or if no holder is left. - **New command.** `cairnd cluster forget <name>`, with an audit verb. - **Content follows the cluster decision.** All content paths follow it: files, link secrets, upload spool, drain fallback. The content drain answers 409 until the cluster seals with this member's keys. - **Remote crypto role.** Refused in coordination mode, with an issue for a later version. - **"Activated" mark.** Recorded now, used for wording only; the rule for never-activated keys is decided in v0.8. - **instanceSeed.** The docs say every member needs the same seed, and the key record publishes the derived fingerprint. - **Audit verbs.** `key-drain-forced` and `key-drained`. - **Back-out warning.** A WARN at start. Rotation progress on the Overview (P5) goes to batch 11.
Author
Owner

Shipped in v0.6.411 (PR #1186); live on both dogfoods.

  • Holder-aware ledger: the ledger records which members hold each key. A member is refused only if it held the key and dropped it, or no holder is left; a forced start in a cluster never drops an entry whose holders are unknown.
  • New commands and verbs: cairnd cluster forget, key-drain-forced and key-drained, and a back-out WARN.
  • Content follows the decision: file content, link secrets, upload pieces and the drain fallback seal with the cluster's decided keys. The drain answers 409 keys-not-decided until the cluster converges.
  • Refusals: the remote crypto role is refused with several instances (follow-up #1187), and a mismatched instanceSeed is refused in either order.

This closes the back-out loss path found in the research. Rotation progress on the Overview (P5) is in batch 11 under #742.

Shipped in v0.6.411 (PR #1186); live on both dogfoods. - **Holder-aware ledger:** the ledger records which members hold each key. A member is refused only if it held the key and dropped it, or no holder is left; a forced start in a cluster never drops an entry whose holders are unknown. - **New commands and verbs:** `cairnd cluster forget`, `key-drain-forced` and `key-drained`, and a back-out WARN. - **Content follows the decision:** file content, link secrets, upload pieces and the drain fallback seal with the cluster's decided keys. The drain answers 409 `keys-not-decided` until the cluster converges. - **Refusals:** the remote crypto role is refused with several instances (follow-up #1187), and a mismatched `instanceSeed` is refused in either order. This closes the back-out loss path found in the research. Rotation progress on the Overview (P5) is in batch 11 under #742.
Cordy closed this issue 2026-11-19 21:01:58 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#1178
No description provided.