diff --git a/docs/prism-id.md b/docs/prism-id.md index 633597e..7d57198 100644 --- a/docs/prism-id.md +++ b/docs/prism-id.md @@ -131,12 +131,20 @@ 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 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 @@ -233,14 +241,27 @@ 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. `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, + 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..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": "b1076262092ea2416b282aa81541614cc68c2490de1ac2fd3bbddd9690e86a81" + "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:6df26232d612c8f74579999e58483c020829afb29253e6174c54cf348a07b92c" + "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/); +});