Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 30 additions & 9 deletions docs/prism-id.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
12 changes: 8 additions & 4 deletions product/contracts.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

53 changes: 41 additions & 12 deletions src/prism-id.js
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
54 changes: 54 additions & 0 deletions tests/prism-guardian.test.js
Original file line number Diff line number Diff line change
@@ -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/);
});
Loading