ftown 0.21.0 → 0.24.0

package/dist/security/ledger/ledger.js

@@ -5,6 +5,7 @@ const messages = {
     ledger_other_account: 'Account ledger entry belongs to a different account.',
     ledger_revoked: 'Account ledger entry refers to a revoked key.',
     ledger_limit: 'Account ledger reached its supported capacity.',
+    resolution_incomplete: 'Account ledger resolution must first carry the other history\'s removals and passkeys.',
 };
 /** No untrusted text, key material or underlying crypto error enters this error. */
 export class LedgerError extends Error {
@@ -166,6 +167,13 @@ function parseOperation(value) {
             const fields = exact(record, ['type', 'authority', 'consent']);
             return { type: 'add_authority', authority: parseAuthority(fields.authority), consent: parseSignature(fields.consent) };
         }
+        case 'resolve_fork': {
+            const fields = exact(record, ['type', 'forkHead', 'discardedFirst', 'discardedHead', 'discardedRevision']);
+            return {
+                type: 'resolve_fork', forkHead: fingerprint(fields.forkHead), discardedFirst: fingerprint(fields.discardedFirst),
+                discardedHead: fingerprint(fields.discardedHead), discardedRevision: count(fields.discardedRevision, 1),
+            };
+        }
         default: return fail();
     }
 }
@@ -291,19 +299,25 @@ function apply(current, operation, issuedAt) {
             next.bridges.push(added);
             break;
         }
+        // A revoked id is a permanent tombstone. Revoking an id that is not a member only tombstones it, so it can never be added later: that is
+        // how a resolution carries a removal made on the other history. A device revocation never names a bridge member's endpoint.
         case 'revoke_device': {
+            if (next.revokedDeviceIds.indexOf(operation.endpointId) !== -1)
+                fail('ledger_revoked');
+            if (next.bridges.some(item => item.endpoint.id === operation.endpointId))
+                fail();
             const index = next.devices.findIndex(item => item.endpoint.id === operation.endpointId);
-            if (index === -1)
-                fail(next.revokedDeviceIds.indexOf(operation.endpointId) !== -1 ? 'ledger_revoked' : 'invalid_ledger');
-            next.devices.splice(index, 1);
+            if (index !== -1)
+                next.devices.splice(index, 1);
             next.revokedDeviceIds.push(operation.endpointId);
             break;
         }
         case 'revoke_bridge': {
+            if (next.revokedBridgeIds.indexOf(operation.bridgeId) !== -1)
+                fail('ledger_revoked');
             const index = next.bridges.findIndex(item => item.bridgeId === operation.bridgeId);
-            if (index === -1)
-                fail(next.revokedBridgeIds.indexOf(operation.bridgeId) !== -1 ? 'ledger_revoked' : 'invalid_ledger');
-            next.bridges.splice(index, 1);
+            if (index !== -1)
+                next.bridges.splice(index, 1);
             next.revokedBridgeIds.push(operation.bridgeId);
             break;
         }
@@ -318,10 +332,108 @@ function apply(current, operation, issuedAt) {
             next.authorities.push(added);
             break;
         }
+        case 'resolve_fork': {
+            // Membership is unchanged. Only the rules that need no history are here; settle() checks the heads against the chain itself.
+            const own = [operation.forkHead, next.head, next.accountId];
+            if (own.indexOf(operation.discardedFirst) !== -1 || own.indexOf(operation.discardedHead) !== -1)
+                fail();
+            break;
+        }
         default: return fail();
     }
     return next;
 }
+function joinedAt(trail, credentialId) {
+    for (const item of trail.joined)
+        if (item.credentialId === credentialId)
+            return item.revision;
+    return -1;
+}
+/** History rules of resolve_fork, against the chain before the record: forkHead is one of its heads and the signer was an authority at it;
+ *  the discarded branch (discardedFirst ... discardedHead at discardedRevision) starts after it and is no part of this chain; its first record
+ *  is its tip exactly when it is one record long. */
+function settle(trail, operation, credentialId) {
+    if (operation.type !== 'resolve_fork')
+        return;
+    const fork = trail.heads.indexOf(operation.forkHead);
+    if (fork === -1 || operation.discardedRevision <= fork)
+        fail();
+    if (trail.heads.indexOf(operation.discardedFirst) !== -1 || trail.heads.indexOf(operation.discardedHead) !== -1)
+        fail();
+    if ((operation.discardedRevision === fork + 1) !== (operation.discardedHead === operation.discardedFirst))
+        fail();
+    const joined = joinedAt(trail, credentialId);
+    if (joined === -1 || joined > fork)
+        fail();
+}
+/** Revoked ids and authorities of a chain from its payloads alone; equals its checkpoint's for a chain already verified or vouched for. */
+function holdings(ledger) {
+    const held = { revokedDeviceIds: [], revokedBridgeIds: [], authorities: [ledger.genesis.payload.authority] };
+    for (const record of ledger.transitions) {
+        const operation = record.payload.operation;
+        if (operation.type === 'revoke_device')
+            held.revokedDeviceIds.push(operation.endpointId);
+        else if (operation.type === 'revoke_bridge')
+            held.revokedBridgeIds.push(operation.bridgeId);
+        else if (operation.type === 'add_authority')
+            held.authorities.push(operation.authority);
+    }
+    return held;
+}
+/** The security-relevant operations of `branch` that `held` lacks, in branch order: one revocation per id `held` has not revoked, and one
+ *  add_authority (the original authority and consent) per authority `held` does not hold with the same credentialId and key. */
+function missing(branch, held) {
+    const devices = held.revokedDeviceIds.slice();
+    const bridges = held.revokedBridgeIds.slice();
+    const authorities = held.authorities.slice();
+    const carry = [];
+    for (const record of branch) {
+        const operation = record.payload.operation;
+        if (operation.type === 'revoke_device' && devices.indexOf(operation.endpointId) === -1) {
+            devices.push(operation.endpointId);
+            carry.push({ type: 'revoke_device', endpointId: operation.endpointId });
+        }
+        else if (operation.type === 'revoke_bridge' && bridges.indexOf(operation.bridgeId) === -1) {
+            bridges.push(operation.bridgeId);
+            carry.push({ type: 'revoke_bridge', bridgeId: operation.bridgeId });
+        }
+        else if (operation.type === 'add_authority') {
+            const added = operation.authority;
+            if (authorities.some(item => item.credentialId === added.credentialId && item.publicKey === added.publicKey))
+                continue;
+            authorities.push(added);
+            carry.push({ type: 'add_authority', authority: { ...added }, consent: { ...operation.consent } });
+        }
+    }
+    return carry;
+}
+function note(trail, payload, head) {
+    trail.heads.push(head);
+    if (payload.operation.type === 'add_authority')
+        trail.joined.push({ credentialId: payload.operation.authority.credentialId, revision: payload.revision });
+}
+function initialState(root, accountId) {
+    return { version: 2, accountId, revision: 0, head: accountId, authorities: [root.authority], devices: [], bridges: [], revokedDeviceIds: [], revokedBridgeIds: [] };
+}
+function initialTrail(root, accountId) {
+    return { heads: [accountId], joined: [{ credentialId: root.authority.credentialId, revision: 0 }] };
+}
+/** The trail of the first `length` records of a chain already verified or vouched for; no signature work. */
+function trailOf(chain, length) {
+    const trail = initialTrail(chain.ledger.genesis.payload, chain.accountId);
+    for (let index = 0; index < length; index += 1)
+        note(trail, chain.ledger.transitions[index].payload, chain.heads[index + 1]);
+    return trail;
+}
+/** The checkpoint after the first `length` records of a chain already verified or vouched for: the verifier's state rules, no signature work. */
+function replay(chain, length) {
+    let state = initialState(chain.ledger.genesis.payload, chain.accountId);
+    for (let index = 0; index < length; index += 1) {
+        const payload = chain.ledger.transitions[index].payload;
+        state = { ...apply(state, payload.operation, payload.issuedAt), revision: payload.revision, head: chain.heads[index + 1] };
+    }
+    return state;
+}
 function copyOf(state) {
     return {
         version: 2, accountId: state.accountId, revision: state.revision, head: state.head,
@@ -335,8 +447,9 @@ async function consented(operation, accountId, root) {
     if (!await verifyPasskeyAssertion({ rpId: root.rpId, origins: root.origins, publicKey: operation.authority.publicKey, challenge, signature: operation.consent }))
         fail();
 }
-/** Verifies `records` in order on top of a verified `state` whose last record was issued at `previousTime`. */
-async function extend(state, root, previousTime, records, at) {
+/** Verifies `records` in order on top of a verified `state` whose last record was issued at `previousTime`; `trail` describes the chain up
+ *  to `state` and is extended in place. */
+async function extend(state, root, previousTime, records, at, trail) {
     let current = state;
     let lastTime = previousTime;
     for (const record of records) {
@@ -350,13 +463,16 @@ async function extend(state, root, previousTime, records, at) {
         if (payload.issuedAt < lastTime || payload.issuedAt > at + LEDGER_LIMITS.maxFutureSkewMs)
             fail();
         const signer = signerOf(current, payload.credentialId);
+        settle(trail, payload.operation, signer.credentialId);
         const challenge = await ledgerChallenge(payload);
         if (!await verifyPasskeyAssertion({ rpId: root.rpId, origins: root.origins, publicKey: signer.publicKey, challenge, signature: record.signature }))
             fail();
         await keyMaterial(payload.operation);
         if (payload.operation.type === 'add_authority')
             await consented(payload.operation, current.accountId, root);
-        current = { ...apply(current, payload.operation, payload.issuedAt), revision: payload.revision, head: b64url(challenge) };
+        const head = b64url(challenge);
+        current = { ...apply(current, payload.operation, payload.issuedAt), revision: payload.revision, head };
+        note(trail, payload, head);
         lastTime = payload.issuedAt;
     }
     return current;
@@ -370,10 +486,7 @@ async function verifyAll(ledger, at) {
     if (!await verifyPasskeyAssertion({ rpId: root.rpId, origins: root.origins, publicKey: root.authority.publicKey, challenge, signature: ledger.genesis.signature }))
         fail();
     const accountId = b64url(challenge);
-    const initial = {
-        version: 2, accountId, revision: 0, head: accountId, authorities: [root.authority], devices: [], bridges: [], revokedDeviceIds: [], revokedBridgeIds: [],
-    };
-    return extend(initial, root, root.createdAt, ledger.transitions, at);
+    return extend(initialState(root, accountId), root, root.createdAt, ledger.transitions, at, initialTrail(root, accountId));
 }
 /** Unexpected (non-ledger) failures become invalid_ledger. */
 async function guarded(run) {
@@ -388,11 +501,10 @@ async function guarded(run) {
 }
 async function indexed(value) {
     const ledger = parseLedger(value);
-    const accountId = await ledgerHead(ledger.genesis.payload);
-    const heads = [];
+    const heads = [await ledgerHead(ledger.genesis.payload)];
     for (const record of ledger.transitions)
         heads.push(await ledgerHead(record.payload));
-    return { ledger, accountId, heads, head: heads.length ? heads[heads.length - 1] : accountId };
+    return { ledger, accountId: heads[0], heads };
 }
 /** The cache vouches for `chain` only if it names the chain's last head and the chain is hash-linked up to it. */
 function vouched(chain, cache) {
@@ -401,12 +513,13 @@ function vouched(chain, cache) {
     try {
         const record = object(cache);
         const checkpoint = parseCheckpoint(record.checkpoint);
-        if (record.head !== chain.head || checkpoint.head !== chain.head || checkpoint.accountId !== chain.accountId
-            || checkpoint.revision !== chain.heads.length)
+        const head = chain.heads[chain.heads.length - 1];
+        if (record.head !== head || checkpoint.head !== head || checkpoint.accountId !== chain.accountId
+            || checkpoint.revision !== chain.heads.length - 1)
             return null;
-        for (let index = 0; index < chain.heads.length; index += 1) {
+        for (let index = 0; index < chain.ledger.transitions.length; index += 1) {
             const payload = chain.ledger.transitions[index].payload;
-            if (payload.revision !== index + 1 || payload.previousHead !== (index === 0 ? chain.accountId : chain.heads[index - 1]))
+            if (payload.revision !== index + 1 || payload.previousHead !== chain.heads[index])
                 return null;
         }
         return checkpoint;
@@ -415,39 +528,110 @@ function vouched(chain, cache) {
         return null;
     }
 }
-function sameSignature(left, right) {
-    return left.authenticatorData === right.authenticatorData && left.clientDataJSON === right.clientDataJSON && left.signature === right.signature;
+/** Index of the first revision whose heads differ, or the shorter length when one list is a prefix of the other. String compares only. */
+function firstDifference(local, candidate) {
+    const length = Math.min(local.length, candidate.length);
+    let index = 0;
+    while (index < length && local[index] === candidate[index])
+        index += 1;
+    return index;
+}
+/** null when even the genesis differs (another account). */
+function classify(local, candidate) {
+    const index = firstDifference(local, candidate);
+    if (index === 0)
+        return null;
+    if (index < local.length && index < candidate.length)
+        return 'diverged';
+    if (local.length === candidate.length)
+        return 'same';
+    return candidate.length > local.length ? 'ahead' : 'behind';
+}
+function headList(value) {
+    if (!Array.isArray(value))
+        return fail();
+    const heads = value;
+    if (heads.length < 1 || heads.length > LEDGER_LIMITS.maxTransitions + 1 || heads.some(item => typeof item !== 'string'))
+        return fail();
+    return value;
 }
-/** True iff the genesis and the first `length` records carry byte-identical signatures, so the candidate's prefix is the verified local one. */
-function sameRecords(local, candidate, length) {
-    if (!sameSignature(local.genesis.signature, candidate.genesis.signature))
+/** The fork revision of two diverged chains; ledger_other_account for another account, invalid_ledger for any other relation. */
+function divergence(mine, theirs) {
+    const relation = classify(mine.heads, theirs.heads);
+    if (relation === null)
+        fail('ledger_other_account');
+    if (relation !== 'diverged')
+        fail();
+    return firstDifference(mine.heads, theirs.heads) - 1;
+}
+/**
+ * True iff the verified diverged candidate (checkpoint `adopted`) may replace local's branch, i.e. local's records after `fork`:
+ * - the candidate already holds every revocation and every authority that local's branch makes (nothing security-relevant is discarded), and
+ * - it carries, after the fork point, a resolve_fork R with
+ *   1. R.forkHead = the fork point and R.discardedFirst = local's first record after it (so a lagging or sibling replica of that branch matches);
+ *   2. if local's branch holds any resolve_fork (whatever it targets), R.discardedHead = local's OWN record at R.discardedRevision, at or after
+ *      the latest one: R's payload hashes over it, so its signer saw that choice. A revision number alone is not proof (a signer who saw a
+ *      sibling branch at a higher revision never saw it). Each adoption thus moves to a resolution that hashes over the one held before, and
+ *      as hashes cannot form a cycle, no replica ever adopts its way back to a chain it held;
+ *   3. no record of local's branch is newer than R: issuedAt <= R.issuedAt + maxFutureSkewMs (the module's clock allowance).
+ */
+function resolves(mine, theirs, fork, adopted) {
+    const branch = mine.ledger.transitions.slice(fork);
+    if (missing(branch, adopted).length)
         return false;
-    for (let index = 0; index < length; index += 1) {
-        if (!sameSignature(local.transitions[index].signature, candidate.transitions[index].signature))
-            return false;
+    let seen = 0;
+    let newest = 0;
+    for (const record of branch) {
+        if (record.payload.operation.type === 'resolve_fork')
+            seen = record.payload.revision;
+        newest = Math.max(newest, record.payload.issuedAt);
     }
-    return true;
-}
-function revocationCount(ledger) {
-    let total = 0;
-    for (const record of ledger.transitions) {
-        const type = record.payload.operation.type;
-        if (type === 'revoke_device' || type === 'revoke_bridge')
-            total += 1;
+    for (const record of theirs.ledger.transitions.slice(fork)) {
+        const operation = record.payload.operation;
+        if (operation.type !== 'resolve_fork' || operation.forkHead !== mine.heads[fork] || operation.discardedFirst !== mine.heads[fork + 1])
+            continue;
+        if (seen > 0 && (operation.discardedRevision < seen || mine.heads[operation.discardedRevision] !== operation.discardedHead))
+            continue;
+        if (newest > record.payload.issuedAt + LEDGER_LIMITS.maxFutureSkewMs)
+            continue;
+        return true;
     }
-    return total;
+    return false;
 }
-/** The fork order, strict and total on distinct chains of one account: longer, then more revocations in the whole chain, then the smaller head. */
-function outranks(candidate, local) {
-    if (candidate.heads.length !== local.heads.length)
-        return candidate.heads.length > local.heads.length;
-    const revocations = revocationCount(candidate.ledger) - revocationCount(local.ledger);
-    if (revocations !== 0)
-        return revocations > 0;
-    return candidate.head < local.head;
+/** Local's records after the fork, and the revocations among them that the adopted chain lacks. */
+function discardedBy(mine, fork, adopted) {
+    const records = mine.ledger.transitions.slice(fork);
+    const deviceIds = [];
+    const bridgeIds = [];
+    for (const record of records) {
+        const operation = record.payload.operation;
+        if (operation.type === 'revoke_device' && adopted.revokedDeviceIds.indexOf(operation.endpointId) === -1)
+            deviceIds.push(operation.endpointId);
+        if (operation.type === 'revoke_bridge' && adopted.revokedBridgeIds.indexOf(operation.bridgeId) === -1)
+            bridgeIds.push(operation.bridgeId);
+    }
+    return { records, deviceIds, bridgeIds };
+}
+/** LedgerSeen of a VERIFIED diverged candidate: revocations after `fork` signed by an authority of the shared prefix (joined at or before `fork`). */
+function seenIn(mine, theirs, fork) {
+    const authorities = trailOf(mine, fork).joined.map(item => item.credentialId);
+    const seen = { deviceIds: [], bridgeIds: [] };
+    for (const record of theirs.ledger.transitions.slice(fork)) {
+        const { operation, credentialId } = record.payload;
+        if (authorities.indexOf(credentialId) === -1)
+            continue;
+        if (operation.type === 'revoke_device' && seen.deviceIds.indexOf(operation.endpointId) === -1)
+            seen.deviceIds.push(operation.endpointId);
+        if (operation.type === 'revoke_bridge' && seen.bridgeIds.indexOf(operation.bridgeId) === -1)
+            seen.bridgeIds.push(operation.bridgeId);
+    }
+    return seen;
 }
-function choice(decision, checkpoint, discarded) {
-    return { decision, checkpoint: copyOf(checkpoint), discarded };
+function choice(decision, relation, checkpoint, ledger, discarded, seen) {
+    return {
+        decision, relation, checkpoint: copyOf(checkpoint), discarded: discarded ?? { records: [], deviceIds: [], bridgeIds: [] }, ledger,
+        seen: seen ?? { deviceIds: [], bridgeIds: [] },
+    };
 }
 /** SHA-256(UTF-8(LEDGER_DOMAIN + canonical(payload))): the WebAuthn challenge, and the record's head. */
 export async function ledgerChallenge(payload) {
@@ -477,8 +661,8 @@ export function ledgerLastIssuedAt(ledger) {
     const last = ledger.transitions[ledger.transitions.length - 1];
     return time(last === undefined ? ledger.genesis.payload.createdAt : last.payload.issuedAt);
 }
-/** Every device endpoint id and bridgeId revoked anywhere in the chain, in chain order. Only for chains that verified (or that
- *  chooseLedger did not reject): replicas keep the union over all of them and never trust those ids again. Throws on a malformed shape. */
+/** Every device endpoint id and bridgeId revoked anywhere in the chain, in chain order. Only for chains that verified: replicas keep the
+ *  union over the chains they held (plus chooseLedger's `discarded` ids) and never trust those ids again. Throws on a malformed shape. */
 export function ledgerRevocations(ledger) {
     const deviceIds = [];
     const bridgeIds = [];
@@ -527,17 +711,61 @@ export async function verifyLedger(ledger, now = Date.now()) {
     const at = time(now);
     return copyOf(await guarded(() => verifyAll(parseLedger(ledger), at)));
 }
-/** Fork choice, a pure total order on valid chains of one account: longer wins, then more revoke_device/revoke_bridge records in the
- *  whole chain, then the lexicographically smaller head.
- *  - different genesis or invalid candidate -> 'reject'; equal chain or a prefix of local -> 'keep' (decided from record heads alone)
- *  - otherwise the order decides; when a fork wins, `discarded` lists the local records after the common prefix.
- *  `cache` is the checkpoint of the already-verified local chain; when it vouches for `local`, local signatures and timestamps are not
- *  re-checked, and an extension only has its new records verified. Throws only when `local` is invalid (and not vouched for), or when
- *  `local` is null and the candidate is invalid. */
+/** The head of every record, index = revision: [accountId, head of revision 1, ..., head of the tip]. O(n) SHA-256 over the parsed chain and no
+ *  signature work; compute it once per chain and keep it for relate/forkPoint/relateHead. Throws like parseLedger. */
+export async function ledgerHeads(ledger) {
+    return (await guarded(() => indexed(ledger))).heads;
+}
+/** How `candidate` relates to `local` (both ledgerHeads lists of chains of ONE account): 'same' (identical heads), 'ahead' (candidate strictly
+ *  extends local), 'behind' (local strictly extends candidate), 'diverged' (they differ at some revision both have). Pure, O(min(n, m)) string
+ *  compares, no hashing. Another account is not a relation: throws ledger_other_account (genesis heads differ); a malformed list throws
+ *  invalid_ledger. Every head of the shorter list is compared, so a list whose tip matches but whose middle differs is 'diverged'. */
+export function relate(local, candidate) {
+    const relation = classify(headList(local), headList(candidate));
+    return relation === null ? fail('ledger_other_account') : relation;
+}
+/** The last record `local` and `candidate` (ledgerHeads lists) share, or null when even the genesis differs. Same cost as relate. */
+export function forkPoint(local, candidate) {
+    const mine = headList(local);
+    const index = firstDifference(mine, headList(candidate));
+    return index === 0 ? null : { revision: index - 1, head: mine[index - 1] };
+}
+/** What another replica's bare `{ revision, head }` (an RPC answer or head announcement; other fields ignored) says relative to `local`
+ *  (a ledgerHeads list): 'same', 'behind' (local holds that head at that revision and more), or 'unknown' (ahead, diverged or another
+ *  account: fetch its chain and run chooseLedger). O(1). Throws invalid_ledger on a malformed head or revision. */
+export function relateHead(local, other) {
+    const mine = headList(local);
+    const record = object(other);
+    const revision = count(record.revision, 0);
+    const head = fingerprint(record.head);
+    if (revision >= mine.length || mine[revision] !== head)
+        return 'unknown';
+    return revision === mine.length - 1 ? 'same' : 'behind';
+}
+/**
+ * The append-only acceptance rule, the same on every replica (server, browser, bridge). The candidate's relation decides:
+ * - no local chain (first bind): verified from genesis and adopted, relation null; an invalid candidate throws.
+ * - malformed or another account: 'reject', relation null.
+ * - 'same' / 'behind': 'keep', decided from record heads alone (no candidate signature is checked).
+ * - 'ahead': only the records after local's head are verified, on top of local's state -> 'adopt', or 'reject' if any is invalid.
+ * - 'diverged': the candidate's records after the fork point are verified on top of the shared prefix -> 'reject' if invalid. It is
+ *   'adopt'ed only under the owner-signed resolve_fork rule of resolves(); `discarded.records` then lists local's records after the fork.
+ *   Otherwise 'keep': a valid different history is never adopted, whatever its length or content; `seen` lists its removals to enforce locally.
+ * The candidate's copy of the shared prefix is never verified and never stored: its heads equal local's, so its payloads and state do, and
+ * only the candidate's records after the fork point (after local's tip when 'ahead') are checked. Store `choice.ledger`, which keeps local's
+ * prefix records byte-for-byte; re-encoded prefix signatures therefore cost nothing and are dropped. `cache` is the checkpoint of the
+ * already-verified local chain: when it vouches for `local` (same last head, hash-linked) local is not re-verified, else local is verified
+ * from genesis. Throws only when `local` is invalid (and not vouched for), or when `local` is null and the candidate is invalid.
+ */
 export async function chooseLedger(local, candidate, now = Date.now(), cache) {
     const at = time(now);
-    if (local === null)
-        return choice('adopt', await guarded(() => verifyAll(parseLedger(candidate), at)), []);
+    if (local === null) {
+        const first = await guarded(async () => {
+            const ledger = parseLedger(candidate);
+            return { ledger, checkpoint: await verifyAll(ledger, at) };
+        });
+        return choice('adopt', null, first.checkpoint, first.ledger);
+    }
     const mine = await guarded(() => indexed(local));
     const base = vouched(mine, cache) ?? await guarded(() => verifyAll(mine.ledger, at));
     let theirs;
@@ -545,38 +773,91 @@ export async function chooseLedger(local, candidate, now = Date.now(), cache) {
         theirs = await indexed(candidate);
     }
     catch {
-        return choice('reject', base, []);
-    }
-    if (theirs.accountId !== mine.accountId)
-        return choice('reject', base, []);
-    const localLength = mine.heads.length;
-    const candidateLength = theirs.heads.length;
-    let common = 0;
-    while (common < localLength && common < candidateLength && mine.heads[common] === theirs.heads[common])
-        common += 1;
-    if (common === candidateLength)
-        return choice('keep', base, []);
-    if (common === localLength && sameRecords(mine.ledger, theirs.ledger, localLength)) {
-        try {
-            const fresh = theirs.ledger.transitions.slice(localLength);
-            return choice('adopt', await extend(base, mine.ledger.genesis.payload, ledgerLastIssuedAt(mine.ledger), fresh, at), []);
-        }
-        catch {
-            return choice('reject', base, []);
-        }
+        return choice('reject', null, base, mine.ledger);
     }
-    let winner;
+    const relation = classify(mine.heads, theirs.heads);
+    if (relation === null)
+        return choice('reject', null, base, mine.ledger);
+    if (relation === 'same' || relation === 'behind')
+        return choice('keep', relation, base, mine.ledger);
+    // Revision of the last shared record: local's tip when 'ahead'.
+    const fork = firstDifference(mine.heads, theirs.heads) - 1;
+    // Local is verified or vouched for, so replaying its prefix can only fail on corrupt local state, which throws like an invalid local.
+    const start = relation === 'ahead' ? base : await guarded(async () => replay(mine, fork));
+    const suffix = theirs.ledger.transitions.slice(fork);
+    let verified;
     try {
-        winner = await verifyAll(theirs.ledger, at);
+        const root = mine.ledger.genesis.payload;
+        const previousTime = fork === 0 ? root.createdAt : mine.ledger.transitions[fork - 1].payload.issuedAt;
+        verified = await extend(start, root, previousTime, suffix, at, trailOf(mine, fork));
     }
     catch {
-        return choice('reject', base, []);
+        return choice('reject', relation, base, mine.ledger);
     }
-    return outranks(theirs, mine) ? choice('adopt', winner, mine.ledger.transitions.slice(common)) : choice('keep', base, []);
+    const adopted = { genesis: mine.ledger.genesis, transitions: mine.ledger.transitions.slice(0, fork).concat(suffix) };
+    if (relation === 'ahead')
+        return choice('adopt', relation, verified, adopted);
+    return resolves(mine, theirs, fork, verified)
+        ? choice('adopt', relation, verified, adopted, discardedBy(mine, fork, verified))
+        : choice('keep', relation, base, mine.ledger, undefined, seenIn(mine, theirs, fork));
+}
+/** describeFork(local, other): where the two chains part and each side's payloads after that point, for showing two histories side by side.
+ *  Works for any relation of one account (for 'same' both lists are empty). Throws ledger_other_account for another account, else like parseLedger.
+ *  Neither chain is verified: pass only a local chain and one that chooseLedger classified as 'keep' + 'diverged'. */
+export async function describeFork(local, other) {
+    const mine = await guarded(() => indexed(local));
+    const theirs = await guarded(() => indexed(other));
+    const relation = classify(mine.heads, theirs.heads);
+    if (relation === null)
+        return fail('ledger_other_account');
+    const revision = firstDifference(mine.heads, theirs.heads) - 1;
+    return {
+        relation, fork: { revision, head: mine.heads[revision] },
+        mine: mine.ledger.transitions.slice(revision).map(record => record.payload),
+        theirs: theirs.ledger.transitions.slice(revision).map(record => record.payload),
+    };
+}
+/** What keeping `chosen` over `other` requires first: their fork point, and `carry`, the operations to append to `chosen` (each signed as an
+ *  ordinary record, in this order) before resolveForkTransition. In `other`'s chain order: one revoke_device / revoke_bridge per id revoked on
+ *  other's branch after the fork and not revoked in `chosen` (an id that is not a member of `chosen` is tombstoned, so it can never be added
+ *  there), and one add_authority, with the ORIGINAL authority and consent (a consent binds only accountId, credentialId and key), per authority
+ *  added on other's branch and absent from `chosen` with the same credentialId and key. Building a carried record can still throw (for example
+ *  ledger_limit, or invalid_ledger when `chosen` holds that credentialId or key under another authority): then `chosen` cannot be kept.
+ *  Throws ledger_other_account for another account and invalid_ledger unless the chains diverge. Neither chain is verified: pass only a
+ *  verified local chain and one that chooseLedger classified as 'keep' + 'diverged'. */
+export async function resolutionPlan(chosen, other) {
+    const mine = await guarded(() => indexed(chosen));
+    const theirs = await guarded(() => indexed(other));
+    const fork = divergence(mine, theirs);
+    return { fork: { revision: fork, head: mine.heads[fork] }, carry: missing(theirs.ledger.transitions.slice(fork), holdings(mine.ledger)) };
+}
+/** The unsigned resolve_fork that keeps `chosen` and discards `other` from their fork point: appended to `chosen`, forkHead = the last shared
+ *  record, discardedFirst = other's first record after it, discardedHead/discardedRevision = other's tip. Verifies `chosen` (skipped when
+ *  `cache` vouches for it, as in chooseLedger) and throws invalid_ledger when the chains do not diverge or `credentialId` was not an authority
+ *  at the fork point (one added on chosen's own branch cannot discard the other); resolution_incomplete while resolutionPlan(chosen, other)
+ *  still has operations to carry; ledger_other_account for another account; else nextTransition's errors. `other` is not verified: pass only
+ *  a chain that chooseLedger classified as 'keep' + 'diverged'. */
+export async function resolveForkTransition(chosen, other, credentialId, now = Date.now(), cache) {
+    const at = time(now);
+    const mine = await guarded(() => indexed(chosen));
+    const theirs = await guarded(() => indexed(other));
+    const fork = divergence(mine, theirs);
+    const checkpoint = vouched(mine, cache) ?? await guarded(() => verifyAll(mine.ledger, at));
+    const signer = credential(credentialId);
+    if (joinedAt(trailOf(mine, fork), signer) === -1)
+        fail();
+    if (missing(theirs.ledger.transitions.slice(fork), checkpoint).length)
+        fail('resolution_incomplete');
+    const operation = {
+        type: 'resolve_fork', forkHead: mine.heads[fork], discardedFirst: theirs.heads[fork + 1],
+        discardedHead: theirs.heads[theirs.heads.length - 1], discardedRevision: theirs.heads.length - 1,
+    };
+    return nextTransition(checkpoint, signer, operation, at, ledgerLastIssuedAt(mine.ledger));
 }
 /** Pure next-payload builder for the signer. Applies the operation to a copy of the checkpoint with the verifier's rules and throws the
- *  same errors. Not checked here (they need async crypto): endpoint id = SHA-256(point), points on the curve, and the add_authority
- *  consent signature (only its shape is checked); verifyLedger enforces all three.
+ *  same errors. Not checked here (they need async crypto or the chain): endpoint id = SHA-256(point), points on the curve, the add_authority
+ *  consent signature (only its shape is checked) and resolve_fork's forkHead and signer rules (build it with resolveForkTransition);
+ *  verifyLedger enforces all of them.
  *  `lastIssuedAt` is the issuedAt of the ledger's last record (see ledgerLastIssuedAt); the result's issuedAt is max(now, lastIssuedAt). */
 export function nextTransition(checkpoint, credentialId, operation, now = Date.now(), lastIssuedAt) {
     const current = parseCheckpoint(checkpoint);