From 6cfd318dff1b9b2e0064b4f1cff233087f32a916 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 20:17:24 +0000 Subject: [PATCH 1/2] docs(prism-id): state the replayed paper kit residual exactly The Open item said a replayed old recovery kit could only deny the id at hosts. That holds only where the recovery that used the kit is heard: a verifier that hears only the replay, because nothing retains the recovery any more, takes it for a recovery. The item now says so, and gives why no stitch element closes it for a kit of paper shares alone: a recovery after losing every device leaves nothing but the kit that knows it happened, so a later holder of a copy holds everything the person held and only the order of the two uses differs. Guardians are that witness already (they confirm the person out of band before releaseShare); a paper-only kit has none. The Recovery paragraph's "the replay never acts as the person" is scoped to where the recovery is heard. product/contracts.json regenerated. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3NdLCxdzL1iQw9rg5T --- docs/prism-id.md | 29 ++++++++++++++++++++--------- product/contracts.json | 4 ++-- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/prism-id.md b/docs/prism-id.md index 633597e..30a78c0 100644 --- a/docs/prism-id.md +++ b/docs/prism-id.md @@ -131,7 +131,7 @@ replay's records. A replay that also signs a second retirement of the old recovery device, keeping its own records, is a fork. A recovery device is retired once, so a log holding two retirements that keep different records does not resolve (`fork`): a host that hears both acts for neither side, and -the replay never acts as the person. Devices never hold a fork: +the replay never acts as the person where the recovery is heard. Devices never hold a fork: `receiveSync`, and `heardLog(..., { own: true })` for a device checking its own log, admit records through `admitRecords`, which refuses a retirement of a recovery device the held log already retires. Recovering again with the @@ -233,14 +233,25 @@ These belong in the threat model's residuals (section 10) and designs (section 12) when its next revision is attested; they are kept here so that change does not invalidate the retained proof evidence. -- **A replayed old recovery, forked.** A replayed old kit binds and revokes - nothing (see Recovery), but whoever holds it can still sign a second - retirement and publish it on the public log topic. Hosts that hear it then - act for neither side until the person stops using that prism id: the old - kit cannot take the id over, but it can deny it at hosts. Set union has no - order, so only an outside witness tells the two retirements apart; ordering - by the witnessed time of threat-model D4 closes it, and keeping an old kit - as secret as the current one keeps it from arising. +- **A replayed old paper kit.** A replayed old kit binds and revokes + nothing where the recovery that used it is heard (see Recovery), but + whoever holds it can still sign a second retirement and publish it on the + public log topic. Hosts that hear both then act for neither side, and a host + that hears only the replay, because nothing retains the recovery any more, + takes it for a recovery. So an old kit is denial wherever the recovery is + heard, and as strong as the current kit wherever it is not. + No element of stitch can close this for a kit that is only paper shares: + a recovery after losing every device leaves nothing that knows it happened + except the kit itself, so whoever later holds a copy of the kit holds + everything the person held, and only the order of the two uses tells them + apart. That order needs a witness that outlasts the devices. Guardians + already are one: a guardian confirms the person out of band before + `releaseShare`, and refuses whoever replays later. A kit of paper shares + alone has none, so it is to be kept as secret after use as before. The + person's own devices are never denied: they hold their log and admit what + they hear through `admitRecords`. + The witnessed time of threat-model D4 would close it for paper kits too, + but needs witnesses that run somewhere, which stitch does not add. - **Retention when every member is offline.** The refresh cadence keeps a recent sync and public log on the warm relay while a member is online. After every member has been offline longer than the relay keeps messages, log-free diff --git a/product/contracts.json b/product/contracts.json index e596ad4..1777cb9 100644 --- a/product/contracts.json +++ b/product/contracts.json @@ -2842,7 +2842,7 @@ }, { "path": "docs/prism-id.md", - "sha256": "b1076262092ea2416b282aa81541614cc68c2490de1ac2fd3bbddd9690e86a81" + "sha256": "5a273e45f745544ccae8d625f79b7a7f3c7919cc5c216f93d43ec1f6314babb1" }, { "path": "docs/prism-model.md", @@ -3205,5 +3205,5 @@ "sha256": "02263c2d4bf1a1913a673466554c19593b5a6c39b22a2da32ce4375675868347" } ], - "sourceDigest": "sha256:6df26232d612c8f74579999e58483c020829afb29253e6174c54cf348a07b92c" + "sourceDigest": "sha256:c349f917274f78d0d8f16f8a68dd4f68113fef3e4b65d15cf0554d8f687c3408" } From 764522ff2f10f46187c22f57395a0ca3fc22d48c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 20:20:57 +0000 Subject: [PATCH 2/2] feat(prism-id): replaceRecovery adds a guardian to a paper kit A kit of one paper share has no witness of its use, so a copy of it replays. Guardians are that witness: each confirms the person out of band before releaseShare, and one that released its share has none left to give a replay. replaceRecovery(session, shares, { threshold, guardians }) lets a member, holding the current recovery device's shares, move the prism to a new recovery device with fresh shares: the old recovery device (combined from the shares, never kept by the member) binds the new one through createRecovery and retires itself through revokeDevice, keeping what it signed. Nothing else in the log changes; the member's keyring takes up the rotation. With threshold 2 over a paper share and a guardian, the paper alone no longer recovers. The share combination recoverPrism did inline moves to recoverySecret, which both use; recoverPrism's behaviour is unchanged. No model predicate is added: thresholdMet, mayAdminister, bindAllowed, recoveryBindAllowed and revocationCounts decide every step as before. tests/prism-guardian.test.js: a guardian joins a paper kit and the old recovery device is retired; the paper share alone is refused below the threshold; with the guardian's released share recovery succeeds, and the released share opens only on the device it was released to; a share is refused to a guardian it was not made for. docs/prism-id.md describes replaceRecovery and the residual it closes. product/contracts.json regenerated. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013Asa3NdLCxdzL1iQw9rg5T --- docs/prism-id.md | 14 ++++++++-- product/contracts.json | 12 +++++--- src/prism-id.js | 53 +++++++++++++++++++++++++++-------- tests/prism-guardian.test.js | 54 ++++++++++++++++++++++++++++++++++++ 4 files changed, 115 insertions(+), 18 deletions(-) create mode 100644 tests/prism-guardian.test.js diff --git a/docs/prism-id.md b/docs/prism-id.md index 30a78c0..7d57198 100644 --- a/docs/prism-id.md +++ b/docs/prism-id.md @@ -137,6 +137,14 @@ own log, admit records through `admitRecords`, which refuses a retirement of a recovery device the held log already retires. Recovering again with the newer kit leaves the retired recovery device as it is. +`replaceRecovery(session, shares, { threshold, guardians })` replaces the +recovery device while a member is at hand: the current recovery device, +combined from its shares, binds a new one with fresh shares and retires +itself. No member holds the recovery secret on the way. A kit of one paper +share gains a guardian this way: two of two over a paper share and a +guardian's, so the paper alone no longer recovers, and a guardian that keeps +its share until it releases it once has nothing to release to a replay. + Recovery needs no copy of the log. Given `bus` instead of `records`, it reads the sync messages the substrate retained (`bus.retained(topic)`), opening them with the keyring snapshot in the recovery secret. Every rotation wraps the next @@ -246,8 +254,10 @@ change does not invalidate the retained proof evidence. everything the person held, and only the order of the two uses tells them apart. That order needs a witness that outlasts the devices. Guardians already are one: a guardian confirms the person out of band before - `releaseShare`, and refuses whoever replays later. A kit of paper shares - alone has none, so it is to be kept as secret after use as before. The + `releaseShare`, and refuses whoever replays later. `replaceRecovery` adds + one to a paper kit. A kit of paper shares alone has none, so it is to be + kept as secret after use as before, and a paper kit that never left the + device it was made on, replaced before it was saved, was never exposed. The person's own devices are never denied: they hold their log and admit what they hear through `admitRecords`. The witnessed time of threat-model D4 would close it for paper kits too, diff --git a/product/contracts.json b/product/contracts.json index 1777cb9..2eaa8b8 100644 --- a/product/contracts.json +++ b/product/contracts.json @@ -1372,8 +1372,8 @@ "origin": "Project-owned source checkout", "licenseStatus": "Project declares MIT; audit applies", "redistributionCleared": true, - "bytes": 98032, - "sha256": "5ae9114fbc7d34c50b2736ed4813d6ab52b678435c1342c97874ab57762fe87f" + "bytes": 99640, + "sha256": "9b32ec3e3d98e959887b2092f370d97b970eb75928b636faf96527e6d9b79a48" }, { "declaration": "assetProductExperience", @@ -2842,7 +2842,7 @@ }, { "path": "docs/prism-id.md", - "sha256": "5a273e45f745544ccae8d625f79b7a7f3c7919cc5c216f93d43ec1f6314babb1" + "sha256": "b37ca11b5124cd34cf38a5038c077b9ee6c77d5197caac1911e1a419df6af20b" }, { "path": "docs/prism-model.md", @@ -3128,6 +3128,10 @@ "path": "tests/prism-bus.test.js", "sha256": "37d02bfcf831de90c9651f84f95a6fa745a3605bbb449ec242a27530a0c50dde" }, + { + "path": "tests/prism-guardian.test.js", + "sha256": "c6d12d98cb4a4d3d3ef956b618bd9230054fa26d23a8b20d7fbbc092930dd0c6" + }, { "path": "tests/prism-id.test.js", "sha256": "ade2eb4cfca393f21034c974a315c560e4bc7b2f87e4cafa9c37dc0280556aa9" @@ -3205,5 +3209,5 @@ "sha256": "02263c2d4bf1a1913a673466554c19593b5a6c39b22a2da32ce4375675868347" } ], - "sourceDigest": "sha256:c349f917274f78d0d8f16f8a68dd4f68113fef3e4b65d15cf0554d8f687c3408" + "sourceDigest": "sha256:1de8da497644d607610fb331cfa7d3056c8b8846886889e85cc6b3916b4587ff" } diff --git a/src/prism-id.js b/src/prism-id.js index 070d593..ef30240 100644 --- a/src/prism-id.js +++ b/src/prism-id.js @@ -1123,19 +1123,10 @@ export async function recoveryCode(prism, newDeviceRecord) { } /** - * Recover a prism on a new device from `threshold` shares. Refuses below the - * threshold (Stitch.PrismId.thresholdMet). The recovered recovery device binds - * the new device as a member and revokes every other device, which also stops - * any revocations a thief made from counting. Pass `rotateRecovery` with new - * guardians so the recovered secret is retired at once. Personas are carried - * over when their host-held logs are supplied. + * Combine `threshold` shares of one recovery device into its secret + * (Stitch.PrismId.thresholdMet). `device` opens shares a guardian released to it. */ -export async function recoverPrism({ prism, records, bus, shares, device, personas = {}, rotateRecovery }) { - let log = records === undefined ? null : await logFromRecords(records); - let state = log ? await resolvePrism(prism, log) : null; - if (!log && typeof bus?.retained !== 'function') refuse('recovery', 'give the prism log, or a bus that retains sync messages'); - const recoveryId = state ? state.recovery : shares.find(s => s?.kind === KIND.recoveryShare && s.prism === prism)?.recovery; - if (!recoveryId) refuse('recovery', 'this prism has no active recovery device'); +async function recoverySecret(prism, recoveryId, shares, device) { const parts = []; for (const s of shares) { if (s.kind !== KIND.recoveryShare || s.prism !== prism || s.recovery !== recoveryId) continue; @@ -1152,6 +1143,44 @@ export async function recoverPrism({ prism, records, bus, shares, device, person secretBytes.fill(0); if (secret.kind !== KIND.recoverySecret || secret.prism !== prism || await kappa(secret.device) !== recoveryId) refuse('recovery', 'the shares belong to another recovery device'); const recovery = await importDeviceSecret(secret.device, secret.keys); + return { secret, recovery }; +} + +/** + * Replace the recovery device while a member is at hand, with the shares of + * the current one: the old recovery device binds a new one with fresh + * `threshold`-of-n shares for `guardians` and retires itself, keeping what it + * signed. Nothing else changes, and no member ever holds the recovery secret. + * A kit of paper shares gains a guardian this way: with `threshold: 2` over a + * paper share and a guardian, the paper alone no longer recovers, and a + * guardian who released its share once has none to release to a replay. + */ +export async function replaceRecovery(session, shares, { threshold, guardians }) { + const state = await mayAdminister(session); + if (!state.recovery) refuse('recovery', 'this prism has no active recovery device'); + const { recovery } = await recoverySecret(session.prism, state.recovery, shares, session.device); + const made = await createRecovery({ ...session, device: recovery }, { threshold, guardians }); + const retired = await revokeDevice({ ...made.session, device: recovery }, recovery.id); + const next = { ...session, log: retired.log }; + next.keyring = await absorbRekeys(next, await resolvePrism(session.prism, retired.log)); + return { session: next, recovery: made.recovery, shares: made.shares }; +} + +/** + * Recover a prism on a new device from `threshold` shares. Refuses below the + * threshold (Stitch.PrismId.thresholdMet). The recovered recovery device binds + * the new device as a member and revokes every other device, which also stops + * any revocations a thief made from counting. Pass `rotateRecovery` with new + * guardians so the recovered secret is retired at once. Personas are carried + * over when their host-held logs are supplied. + */ +export async function recoverPrism({ prism, records, bus, shares, device, personas = {}, rotateRecovery }) { + let log = records === undefined ? null : await logFromRecords(records); + let state = log ? await resolvePrism(prism, log) : null; + if (!log && typeof bus?.retained !== 'function') refuse('recovery', 'give the prism log, or a bus that retains sync messages'); + const recoveryId = state ? state.recovery : shares.find(s => s?.kind === KIND.recoveryShare && s.prism === prism)?.recovery; + if (!recoveryId) refuse('recovery', 'this prism has no active recovery device'); + const { secret, recovery } = await recoverySecret(prism, recoveryId, shares, device); const snapshot = new Map(); for (const [id, raw] of Object.entries(secret.keyring)) snapshot.set(id, await boundaryFromRaw(fromBase64Url(raw), true)); let carried = personas; diff --git a/tests/prism-guardian.test.js b/tests/prism-guardian.test.js new file mode 100644 index 0000000..ba71994 --- /dev/null +++ b/tests/prism-guardian.test.js @@ -0,0 +1,54 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + createPrism, createDevice, resolvePrism, canSign, createRecovery, replaceRecovery, releaseShare, recoverPrism, recoveryCode +} from '../src/prism-id.js'; + +const PAPER = { threshold: 1, guardians: [{ paper: true }] }; + +/** The frame's id: one device, a kit of one paper share. A guardian is a device of another person's prism. */ +async function guarded() { + const made = await createRecovery(await createPrism(), PAPER); + const guardian = (await createPrism()).device; + const replaced = await replaceRecovery(made.session, [made.shares[0]], { threshold: 2, guardians: [{ paper: true }, guardian.record] }); + return { made, guardian, replaced, prism: made.session.prism }; +} + +test('R4: a guardian joins a paper kit without a recovery, and the member never holds the recovery secret', async () => { + const { made, guardian, replaced, prism } = await guarded(); + const state = await resolvePrism(prism, replaced.session.log); + assert.deepEqual(state.active, [made.session.device.id, replaced.recovery].sort()); + assert.deepEqual(state.retired, [made.shares[0].recovery]); + assert.equal(state.recovery, replaced.recovery); + const [paper, held] = replaced.shares; + assert.equal(paper.guardian, 'paper'); + assert.equal(held.guardian, guardian.id); + assert.equal(paper.threshold, 2); + assert.ok(!('share' in held), 'the guardian share is wrapped to the guardian only'); + assert.equal(await canSign(prism, replaced.session.log, made.session.device.id), true); + // The member's keyring took up the rotation the old recovery device made when it retired. + assert.ok(replaced.session.keyring.has(state.boundary.keyId)); +}); + +test('R4: the paper share alone no longer recovers; with the share a guardian released, it does', async () => { + const { replaced, guardian, prism } = await guarded(); + const [paper, held] = replaced.shares; + const records = [...replaced.session.log.values()]; + await assert.rejects(recoverPrism({ prism, records, shares: [paper], device: await createDevice() }), /not enough shares/); + const fresh = await createDevice(); + assert.match(await recoveryCode(prism, fresh.record), /^\d{6}$/); + const released = await releaseShare(guardian, held, fresh.record); + const recovered = await recoverPrism({ prism, records, shares: [paper, released], device: fresh, rotateRecovery: PAPER }); + const state = await resolvePrism(prism, recovered.session.log); + assert.deepEqual(state.active, [fresh.id, recovered.shares[0].recovery].sort()); + // The guardian's share opens only on the device it was released to. + await assert.rejects(recoverPrism({ prism, records, shares: [paper, released], device: await createDevice() })); +}); + +test('R4: a guardian share is refused to a guardian it was not made for, and the old paper kit is retired', async () => { + const { made, replaced, prism } = await guarded(); + const stranger = (await createPrism()).device; + await assert.rejects(releaseShare(stranger, replaced.shares[1], (await createDevice()).record), /not held by this guardian/); + const records = [...replaced.session.log.values()]; + await assert.rejects(recoverPrism({ prism, records, shares: [made.shares[0]], device: await createDevice() }), /not enough shares/); +});