@plane31/blind-relay 0.1.3 → 0.2.0

package/src/testing/fakeHost.ts

@@ -8,19 +8,22 @@ import { equalBytes, fromHex, toHex } from "../bytes.js";
 import {
   DocumentType,
   buildResetReceipt,
+  buildSuccession,
   expectType,
   parseDocument,
   parseVaultHeader,
   verifyDocument,
   type AccountDevice,
+  type AccountSuccession,
   type CircleSnapshot,
   type EncryptedRecord,
   type EpochManifest,
   type RecordKind
 } from "../codec.js";
-import { bodyHash, identityId, streamId as deriveStreamId, type SigningKeypair } from "../crypto.js";
+import { bodyHash, identityId, randomBytes, streamId as deriveStreamId, type SigningKeypair } from "../crypto.js";
 import type {
   AppendOutcome,
+  CircleListing,
   Directory,
   EpochBundle,
   JoinRequest,
@@ -28,13 +31,21 @@ import type {
   ReadRecordsResult,
   Relay,
   ResolvedAccount,
+  SuccessionLink,
   Transport
 } from "../transport.js";
 
 interface Account {
   accountName: string;
   accountKey: Uint8Array;
+  /** The identity of the current key. */
   identityId: string;
+  /** The account id: the root of the succession chain; what circles, manifests and streams name. */
+  accountId: string;
+  /** The chain from the root, oldest first; empty until a succession. */
+  successions: SuccessionLink[];
+  /** The certificate the first succession replaced: a certificate under the root key. */
+  rootCertificate: Uint8Array | undefined;
   certificate: Uint8Array;
   certificateHash: string;
   generation: bigint;
@@ -89,6 +100,22 @@ export class FakeHost {
   readonly streams = new Map<string, StreamState>();
   readonly notifications: Notification[] = [];
   readonly receipts = new Map<string, Uint8Array>();
+  /** Successions by succession id: the committed document and the certificate hash it bound, for idempotent commits. */
+  readonly successionLog = new Map<string, { accountName: string; certificateHash: string; wire: Uint8Array }>();
+  /** Replacement authorizations the product's fresh authentication issued (`authorizeReplacement`), single use. */
+  readonly authorizations = new Map<string, { accountName: string; successionId: string; expectedCertificateHash: string; certificateHash: string; expiresAt: bigint; used: boolean }>();
+  /** Sharing preferences per (account id, circle id), with the revision that orders them. */
+  readonly preferences = new Map<string, { enabled: boolean; revision: bigint }>();
+  authorizationTtlMs = 300_000n;
+  successionPageSize = 8;
+  circlePageSize = 50;
+  /** Re-attest a link under the current operational key when its original signer is no longer it (section 7). */
+  reattest = true;
+  /** Test switch: the n-th call to listCircles (1-based) fails with a transport error, once. */
+  failCircleListAt: number | undefined;
+  circleListCalls = 0;
+  /** Every getSuccessions call, for tests that check where a peer resumes a chain. */
+  readonly successionCalls: { accountId: string; afterGeneration: bigint; limit: number }[] = [];
   resetKeyList: Uint8Array | undefined;
   resetSigner: { key: SigningKeypair; keyId: Uint8Array } | undefined;
   /** Test switches. */
@@ -106,6 +133,58 @@ export class FakeHost {
     return [...this.accounts.values()].find((a) => a.identityId === iid);
   }
 
+  /** The account an id names today: its account id, its current identity, or an identity it retired. */
+  accountByAnyId(id: string): Account | undefined {
+    return [...this.accounts.values()].find((a) => a.accountId === id || a.identityId === id || a.previousIdentities.has(id));
+  }
+
+  /**
+   * The product's fresh authentication, as a test hook: an authorization bound to the proposal
+   * (account, succession id, expected certificate, the certificate's hash), single use, expiring.
+   */
+  authorizeReplacement(input: { accountName: string; successionId: Uint8Array; expectedCertificateHash: Uint8Array; certificate: Uint8Array }): Uint8Array {
+    const doc = expectType<AccountDevice>(verifyDocument(input.certificate), DocumentType.AccountDevice);
+    const token = randomBytes(32);
+    this.authorizations.set(toHex(token), { accountName: input.accountName, successionId: toHex(input.successionId), expectedCertificateHash: toHex(input.expectedCertificateHash), certificateHash: toHex(doc.bodyHash), expiresAt: this.now() + this.authorizationTtlMs, used: false });
+    return token;
+  }
+
+  private resolvedOf(a: Account): ResolvedAccount {
+    const r: ResolvedAccount = { accountName: a.accountName, accountKey: a.accountKey, certificate: a.certificate };
+    const page = this.successionPage(a, 0n, this.successionPageSize);
+    return {
+      ...r,
+      ...(a.resetReceipt ? { resetReceipt: a.resetReceipt } : {}),
+      ...(page.successions.length ? { successions: page.successions } : {}),
+      ...(page.nextGeneration !== undefined ? { successionsNext: page.nextGeneration } : {}),
+      ...(page.rootCertificate ? { rootCertificate: page.rootCertificate } : {})
+    };
+  }
+
+  private successionPage(a: Account, afterGeneration: bigint, limit: number): { successions: SuccessionLink[]; nextGeneration?: bigint; rootCertificate?: Uint8Array } {
+    const gen = (l: SuccessionLink): bigint => expectType<AccountDevice>(parseDocument(l.certificate), DocumentType.AccountDevice).generation;
+    const rest = a.successions.filter((l) => gen(l) > afterGeneration).map((l) => this.served(l));
+    const page = rest.slice(0, Math.max(1, limit));
+    const last = page.at(-1);
+    const root = afterGeneration === 0n && page.length && a.rootCertificate ? { rootCertificate: a.rootCertificate } : {};
+    return rest.length > page.length && last ? { successions: page, nextGeneration: gen(last), ...root } : { successions: page, ...root };
+  }
+
+  /** A link as served: re-attested under the current operational key when its signer changed and re-attestation is on. */
+  private served(l: SuccessionLink): SuccessionLink {
+    const signer = this.resetSigner;
+    if (!this.reattest || !signer) return l;
+    const doc = expectType<AccountSuccession>(parseDocument(l.wire), DocumentType.AccountSuccession);
+    if (equalBytes(doc.authorityKeyId, signer.keyId)) return l;
+    const fields = { accountName: doc.accountName, accountId: doc.accountId, previousIdentityId: doc.previousIdentityId, newIdentityId: doc.newIdentityId, previousGeneration: doc.previousGeneration, newGeneration: doc.newGeneration, newCertificateHash: doc.newCertificateHash, successionId: doc.successionId };
+    return { wire: buildSuccession({ ...fields, issuedAt: this.now(), authorityKeyId: signer.keyId }, signer.key.secretKey), certificate: l.certificate };
+  }
+
+  /** The circle fence: is this certificate the account's current device? A retired device is refused reads too. */
+  private isCurrentDevice(accountName: string, certificateHash: string): boolean {
+    return this.accounts.get(accountName)?.certificateHash === certificateHash;
+  }
+
   private stream(streamHex: string, authorIdentityId: string, accountName: string): StreamState {
     let s = this.streams.get(streamHex);
     if (!s) {
@@ -181,17 +260,13 @@ export class FakeHost {
       async resolveAccounts(names): Promise<ResolvedAccount[]> {
         return names.flatMap((n) => {
           const a = host.accounts.get(n);
-          if (!a) return [];
-          const r: ResolvedAccount = { accountName: n, accountKey: a.accountKey, certificate: a.certificate };
-          return [a.resetReceipt ? { ...r, resetReceipt: a.resetReceipt } : r];
+          return a ? [host.resolvedOf(a)] : [];
         });
       },
       async resolveIdentities(identityIds): Promise<ResolvedAccount[]> {
         return identityIds.flatMap((iid) => {
-          const a = host.accountByIdentity(toHex(iid)) ?? [...host.accounts.values()].find((x) => x.previousIdentities.has(toHex(iid)));
-          if (!a) return [];
-          const r: ResolvedAccount = { accountName: a.accountName, accountKey: a.accountKey, certificate: a.certificate };
-          return [a.resetReceipt ? { ...r, resetReceipt: a.resetReceipt } : r];
+          const a = host.accountByAnyId(toHex(iid));
+          return a ? [host.resolvedOf(a)] : [];
         });
       },
       async getCertificate(hash) {
@@ -201,18 +276,21 @@ export class FakeHost {
         const doc = expectType<AccountDevice>(verifyDocument(certificate), DocumentType.AccountDevice);
         const taken = host.accounts.get(doc.accountName);
         if (taken) return equalBytes(taken.certificate, certificate) ? { status: "ALREADY_COMMITTED" } : { status: "CONFLICT" };
-        const vh = parseVaultHeader(vault);
+        const vh = vault ? parseVaultHeader(vault) : undefined;
         const iid = toHex(identityId(doc.accountName, doc.accountKey));
         host.accounts.set(doc.accountName, {
           accountName: doc.accountName,
           accountKey: doc.accountKey,
           identityId: iid,
+          accountId: iid,
+          successions: [],
+          rootCertificate: undefined,
           certificate,
           certificateHash: toHex(doc.bodyHash),
           generation: doc.generation,
           deviceIds: new Set([toHex(doc.deviceId)]),
           retiredCertificates: new Set(),
-          vault: { wire: vault, revision: vh.vaultRevision, hash: toHex(vh.hash) },
+          vault: vault && vh ? { wire: vault, revision: vh.vaultRevision, hash: toHex(vh.hash) } : undefined,
           retiredIdentity: false,
           previousIdentities: new Set(),
           resetReceipt: undefined
@@ -237,7 +315,7 @@ export class FakeHost {
         a.deviceIds.add(toHex(doc.deviceId));
         a.vault = { wire: input.newVault, revision: vh.vaultRevision, hash: toHex(vh.hash) };
         host.certificates.set(a.certificateHash, input.newCertificate);
-        host.stream(toHex(deriveStreamId(fromHex(a.identityId), doc.deviceId)), a.identityId, a.accountName);
+        host.stream(toHex(deriveStreamId(fromHex(a.identityId), doc.deviceId)), a.accountId, a.accountName);
         return { status: "COMMITTED" };
       },
       async getVault(name) {
@@ -264,7 +342,7 @@ export class FakeHost {
         const a = caller();
         if (!current()) return { status: "UNAUTHORIZED" };
         const doc = expectType<CircleSnapshot>(verifyDocument(newSnapshot, a.accountKey), DocumentType.CircleSnapshot);
-        if (toHex(doc.ownerIdentityId) !== a.identityId || !equalBytes(doc.circleId, circleId)) return { status: "UNAUTHORIZED" };
+        if (toHex(doc.ownerIdentityId) !== a.accountId || !equalBytes(doc.circleId, circleId)) return { status: "UNAUTHORIZED" };
         const key = toHex(circleId);
         const existing = host.circles.get(key);
         if (existing) {
@@ -273,10 +351,10 @@ export class FakeHost {
             return { status: "CONFLICT", current: existing.snapshot, currentRevision: existing.revision };
           }
         } else if (expectedRevision !== 0n || doc.revision !== 1n) return { status: "CONFLICT" };
-        host.circles.set(key, { snapshot: newSnapshot, revision: doc.revision, hash: toHex(doc.bodyHash), ownerIdentityId: a.identityId, closed: false });
+        host.circles.set(key, { snapshot: newSnapshot, revision: doc.revision, hash: toHex(doc.bodyHash), ownerIdentityId: a.accountId, closed: false });
         // Requests for accounts now admitted are cleared.
         const members = new Set(doc.members.map(toHex));
-        host.requests.set(key, (host.requests.get(key) ?? []).filter((r) => !members.has(host.accounts.get(r.accountName)?.identityId ?? "")));
+        host.requests.set(key, (host.requests.get(key) ?? []).filter((r) => !members.has(host.accounts.get(r.accountName)?.accountId ?? "")));
         return { status: "COMMITTED" };
       },
       async requestJoin(circleId): Promise<MutationOutcome> {
@@ -289,7 +367,7 @@ export class FakeHost {
         list.push({ circleId, accountName: a.accountName, action: "join", requestedAt: host.now() });
         host.requests.set(toHex(circleId), list);
         if (!hadLive) {
-          const owner = host.accountByIdentity(c.ownerIdentityId);
+          const owner = host.accountByAnyId(c.ownerIdentityId);
           if (owner) host.notifications.push({ kind: "joinRequest", to: owner.accountName, from: a.accountName, circleId: toHex(circleId) });
         }
         return { status: "COMMITTED" };
@@ -301,14 +379,14 @@ export class FakeHost {
         const list = host.requests.get(toHex(circleId)) ?? [];
         list.push({ circleId, accountName: a.accountName, action: "leave", requestedAt: host.now() });
         host.requests.set(toHex(circleId), list);
-        const owner = host.accountByIdentity(c.ownerIdentityId);
+        const owner = host.accountByAnyId(c.ownerIdentityId);
         if (owner) host.notifications.push({ kind: "leaveRequest", to: owner.accountName, from: a.accountName, circleId: toHex(circleId) });
         return { status: "COMMITTED" };
       },
       async readRequests(circleId) {
         const a = caller();
         const c = host.circles.get(toHex(circleId));
-        if (!c || c.ownerIdentityId !== a.identityId) return [];
+        if (!c || c.ownerIdentityId !== a.accountId) return [];
         const cutoff = host.now() - 7n * 86_400_000n;
         return (host.requests.get(toHex(circleId)) ?? []).filter((r) => r.requestedAt > cutoff);
       },
@@ -332,9 +410,14 @@ export class FakeHost {
           host.resetSigner.key.secretKey
         );
         host.receipts.set(toHex(input.resetId), receipt);
-        for (const c of host.circles.values()) if (c.ownerIdentityId === a.identityId) c.closed = true;
-        const vh = parseVaultHeader(input.newVault);
+        for (const c of host.circles.values()) if (c.ownerIdentityId === a.accountId) c.closed = true;
+        const vh = input.newVault ? parseVaultHeader(input.newVault) : undefined;
+        // The whole chain is retired; the reset starts a new account root with an empty chain.
         a.previousIdentities.add(a.identityId);
+        a.previousIdentities.add(a.accountId);
+        for (const l of a.successions) a.previousIdentities.add(toHex(expectType<AccountSuccession>(parseDocument(l.wire), DocumentType.AccountSuccession).previousIdentityId));
+        a.successions = [];
+        a.rootCertificate = undefined;
         a.resetReceipt = receipt;
         a.retiredCertificates.add(a.certificateHash);
         a.accountKey = doc.accountKey;
@@ -343,10 +426,101 @@ export class FakeHost {
         a.certificateHash = toHex(doc.bodyHash);
         a.generation = doc.generation;
         a.deviceIds.add(toHex(doc.deviceId));
-        a.vault = { wire: input.newVault, revision: vh.vaultRevision, hash: toHex(vh.hash) };
+        a.accountId = toHex(newIid);
+        a.vault = input.newVault && vh ? { wire: input.newVault, revision: vh.vaultRevision, hash: toHex(vh.hash) } : undefined;
         host.certificates.set(a.certificateHash, input.newCertificate);
-        host.stream(toHex(deriveStreamId(newIid, doc.deviceId)), a.identityId, a.accountName);
+        host.stream(toHex(deriveStreamId(newIid, doc.deviceId)), a.accountId, a.accountName);
         return { status: "COMMITTED" as const, receipt };
+      },
+      async succeedAccount(input) {
+        // The succession id answers first: a device retrying after a lost response finds its
+        // proposal committed and its token spent, and must get the document, not UNAUTHORIZED.
+        const doc = expectType<AccountDevice>(verifyDocument(input.newCertificate), DocumentType.AccountDevice);
+        const certHash = toHex(doc.bodyHash);
+        const known = host.successionLog.get(toHex(input.successionId));
+        if (known) return known.certificateHash === certHash && known.accountName === input.accountName ? { status: "ALREADY_COMMITTED" as const, succession: known.wire } : { status: "UNAUTHORIZED" as const };
+        const a = host.accounts.get(input.accountName);
+        if (!a || doc.accountName !== a.accountName) return { status: "UNAUTHORIZED" as const };
+        // The authorization: issued for this proposal, unspent, unexpired.
+        const auth = host.authorizations.get(toHex(input.authorization));
+        if (!auth || auth.used || auth.expiresAt < host.now() || auth.accountName !== a.accountName || auth.successionId !== toHex(input.successionId) || auth.expectedCertificateHash !== toHex(input.expectedCertificateHash) || auth.certificateHash !== certHash) {
+          return { status: "UNAUTHORIZED" as const };
+        }
+        if (a.certificateHash !== toHex(input.expectedCertificateHash)) return { status: "CONFLICT" as const, current: a.certificate };
+        if (equalBytes(doc.accountKey, a.accountKey) || doc.generation !== a.generation + 1n || a.deviceIds.has(toHex(doc.deviceId))) return { status: "UNAUTHORIZED" as const };
+        if (!host.resetSigner) return { status: "PERMANENT_FAILURE" as const };
+        const newIid = identityId(doc.accountName, doc.accountKey);
+        const wire = buildSuccession(
+          {
+            accountName: a.accountName,
+            accountId: fromHex(a.accountId),
+            previousIdentityId: fromHex(a.identityId),
+            newIdentityId: newIid,
+            previousGeneration: a.generation,
+            newGeneration: doc.generation,
+            newCertificateHash: doc.bodyHash,
+            successionId: input.successionId,
+            issuedAt: host.now(),
+            authorityKeyId: host.resetSigner.keyId
+          },
+          host.resetSigner.key.secretKey
+        );
+        auth.used = true;
+        host.successionLog.set(toHex(input.successionId), { accountName: a.accountName, certificateHash: certHash, wire });
+        if (a.successions.length === 0) a.rootCertificate = a.certificate;
+        a.successions.push({ wire, certificate: input.newCertificate });
+        a.previousIdentities.add(a.identityId);
+        a.retiredCertificates.add(a.certificateHash);
+        a.accountKey = doc.accountKey;
+        a.identityId = toHex(newIid);
+        a.certificate = input.newCertificate;
+        a.certificateHash = certHash;
+        a.generation = doc.generation;
+        a.deviceIds.add(toHex(doc.deviceId));
+        if (input.newVault) {
+          const vh = parseVaultHeader(input.newVault);
+          a.vault = { wire: input.newVault, revision: vh.vaultRevision, hash: toHex(vh.hash) };
+        }
+        host.certificates.set(certHash, input.newCertificate);
+        host.stream(toHex(deriveStreamId(newIid, doc.deviceId)), a.accountId, a.accountName);
+        return { status: "COMMITTED" as const, succession: wire };
+      },
+      async getSuccessions(accountId, afterGeneration, limit) {
+        host.successionCalls.push({ accountId: toHex(accountId), afterGeneration, limit });
+        const a = host.accountByAnyId(toHex(accountId));
+        if (!a || a.accountId !== toHex(accountId)) return { successions: [] };
+        return host.successionPage(a, afterGeneration, limit);
+      },
+      async listCircles(cursor) {
+        const a = caller();
+        if (host.failCircleListAt !== undefined && ++host.circleListCalls === host.failCircleListAt) {
+          host.failCircleListAt = undefined;
+          throw new Error("transport down");
+        }
+        if (!current()) return { circles: [] };
+        const mine: CircleListing[] = [];
+        for (const [key, c] of [...host.circles].sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0))) {
+          if (cursor !== undefined && key <= cursor) continue;
+          const snap = expectType<CircleSnapshot>(parseDocument(c.snapshot), DocumentType.CircleSnapshot);
+          const pending = (host.requests.get(key) ?? []).some((r) => r.accountName === a.accountName && r.action === "join");
+          const role = c.ownerIdentityId === a.accountId ? "owner" : snap.members.some((m) => toHex(m) === a.accountId) ? "member" : pending ? "pending" : undefined;
+          if (!role) continue;
+          const pref = host.preferences.get(`${a.accountId}:${key}`);
+          mine.push({ circleId: fromHex(key), ownerAccountId: fromHex(c.ownerIdentityId), role, snapshot: c.closed ? undefined : c.snapshot, enabled: pref?.enabled, preferenceRevision: pref?.revision ?? 0n });
+        }
+        const page = mine.slice(0, Math.max(1, host.circlePageSize));
+        const last = page.at(-1);
+        return mine.length > page.length && last ? { circles: page, cursor: toHex(last.circleId) } : { circles: page };
+      },
+      async setSharingPreference(circleId, enabled, expectedRevision) {
+        const a = caller();
+        if (!current()) return { status: "UNAUTHORIZED" as const, revision: 0n };
+        const key = `${a.accountId}:${toHex(circleId)}`;
+        const cur = host.preferences.get(key) ?? { enabled: false, revision: 0n };
+        if (cur.revision !== expectedRevision) return { status: "CONFLICT" as const, revision: cur.revision, enabled: cur.enabled };
+        const next = { enabled, revision: cur.revision + 1n };
+        host.preferences.set(key, next);
+        return { status: "COMMITTED" as const, revision: next.revision };
       }
     };
 
@@ -361,12 +535,12 @@ export class FakeHost {
         const s = host.streams.get(toHex(streamId));
         const e = s?.epochs.get(epoch);
         if (!e) return undefined;
-        return { manifest: e.manifest, wrap: e.wraps.get(caller().identityId) };
+        return { manifest: e.manifest, wrap: e.wraps.get(caller().accountId) };
       },
       async publishEpoch({ streamId, expectedEpoch, manifest, wraps }) {
         const a = caller();
         const s = host.streams.get(toHex(streamId));
-        if (!s || s.authorIdentityId !== a.identityId) return { status: "UNAUTHORIZED" as const };
+        if (!s || s.authorIdentityId !== a.accountId) return { status: "UNAUTHORIZED" as const };
         if (!current()) return { status: "UNAUTHORIZED" as const };
         const doc = expectType<EpochManifest>(parseDocument(manifest), DocumentType.EpochManifest);
         const cur = s.epochs.get(s.currentEpoch);
@@ -379,7 +553,7 @@ export class FakeHost {
         s.currentEpoch = doc.epoch;
         s.currentManifestHash = toHex(doc.bodyHash);
         for (const r of rows) {
-          if (r.identityId === a.identityId) continue;
+          if (r.identityId === a.accountId) continue;
           if (!s.subscriptions.has(r.certificateHash)) s.subscriptions.set(r.certificateHash, { identityId: r.identityId, cursor: s.tail, startSeq: s.tail });
         }
         host.purgeEpochs(s);
@@ -392,7 +566,7 @@ export class FakeHost {
           const a = caller();
           const rec = expectType<EncryptedRecord>(parseDocument(wire), DocumentType.EncryptedRecord);
           const s = host.streams.get(toHex(rec.streamId));
-          if (!s || s.authorIdentityId !== a.identityId) return { status: "UNAUTHORIZED" };
+          if (!s || s.authorIdentityId !== a.accountId) return { status: "UNAUTHORIZED" };
           if (!current()) return { status: "SUPERSEDED_DEVICE" };
           const id = toHex(recordId);
           const hash = toHex(bodyHash(wire)); // exact bytes, signature included
@@ -410,14 +584,14 @@ export class FakeHost {
           const seq = ++s.tail;
           const acceptedAt = host.now() > s.lastAcceptedAt ? host.now() : s.lastAcceptedAt;
           s.lastAcceptedAt = acceptedAt;
-          const required = new Set(epoch.rows.filter((r) => r.identityId !== a.identityId).map((r) => r.certificateHash));
+          const required = new Set(epoch.rows.filter((r) => r.identityId !== a.accountId).map((r) => r.certificateHash));
           s.records.set(seq, { recordId: id, wire, acceptedAt, epoch: rec.epoch, counter: rec.counter, kind: rec.headerClass, required });
           s.highWater = { epoch: rec.epoch, counter: rec.counter };
           const outcome: AppendOutcome = { status: "ACCEPTED", deliverySeq: seq };
           s.lastAppend = { recordId: id, hash, seq, at: acceptedAt, outcome };
           for (const r of epoch.rows) {
-            if (r.identityId === a.identityId) continue;
-            const to = host.accountByIdentity(r.identityId)?.accountName ?? r.identityId;
+            if (r.identityId === a.accountId) continue;
+            const to = host.accountByAnyId(r.identityId)?.accountName ?? r.identityId;
             // By header class, as the test profile declares them: 1 is a visible notification, 2 is
             // silent and needs no wake-up, anything else is a wake-up. The host never sees the kind.
             if (rec.headerClass !== 2) host.notifications.push({ kind: rec.headerClass === 1 ? "visible" : "wake", to, from: a.accountName });
@@ -437,6 +611,8 @@ export class FakeHost {
       },
       async readRecords(streamId, afterSeq, limit): Promise<ReadRecordsResult> {
         const s = host.streams.get(toHex(streamId));
+        // The fence: a retired device reads nothing more (amendment A1, host rules).
+        if (!host.isCurrentDevice(accountName, callerCert)) throw new Error("SUPERSEDED_DEVICE");
         if (!s) return { records: [], nextSeq: afterSeq, tail: 0n, expiredThrough: 0n, committedCursor: 0n };
         if (afterSeq > s.tail) throw new Error("CURSOR_OUT_OF_RANGE");
         const sub = s.subscriptions.get(callerCert);

package/src/testing/faults.ts

@@ -8,7 +8,8 @@
 import { equalBytes, toHex } from "../bytes.js";
 import { KavachError } from "../errors.js";
 import { invokeSync, type Store, type Tx } from "../store.js";
-import type { AppendOutcome, Directory, EpochBundle, MutationOutcome, ReadRecordsResult, Relay, Transport } from "../transport.js";
+import type {
+  ResolvedAccount, AppendOutcome, Directory, EpochBundle, MutationOutcome, ReadRecordsResult, Relay, Transport } from "../transport.js";
 
 // Crashes ------------------------------------------------------------------------------------------
 
@@ -99,9 +100,9 @@ export class FaultyStore implements Store {
 
 // The malicious transport ----------------------------------------------------------------------------
 
-export type MutationName = "registerAccount" | "activateDevice" | "publishVault" | "publishOwnedCircle" | "requestJoin" | "requestLeave" | "resetAccount" | "publishEpoch" | "appendRecord" | "ackThrough";
+export type MutationName = "registerAccount" | "activateDevice" | "publishVault" | "publishOwnedCircle" | "requestJoin" | "requestLeave" | "resetAccount" | "succeedAccount" | "setSharingPreference" | "publishEpoch" | "appendRecord" | "ackThrough";
 
-export type ServedKind = "certificate" | "snapshot" | "vault" | "manifest" | "wrap" | "record" | "keyList" | "receipt";
+export type ServedKind = "certificate" | "snapshot" | "vault" | "manifest" | "wrap" | "record" | "keyList" | "receipt" | "succession";
 
 export interface MaliciousKnobs {
   /** Mutations whose next response is lost after the host committed it (each name is consumed once). */
@@ -111,7 +112,7 @@ export interface MaliciousKnobs {
   /** Mutations whose next response waits for the given promise after the host committed (consumed once). */
   readonly hold: Map<MutationName, Promise<void>>;
   /** Reads that answer "nothing" while present. */
-  readonly withhold: Set<"snapshots" | "epochs" | "records" | "requests" | "currentEpoch" | "keyList" | "certificates">;
+  readonly withhold: Set<"snapshots" | "epochs" | "records" | "requests" | "currentEpoch" | "keyList" | "certificates" | "successions" | "circleList">;
   /** Older documents served instead of the current ones. */
   readonly replay: {
     vault?: Uint8Array;
@@ -197,6 +198,13 @@ export class MaliciousTransport implements Transport {
     return result;
   }
 
+  /** A resolved account as served: a forked or tampered certificate, and a tampered chain, where the knobs say so. */
+  private servedAccount(r: ResolvedAccount): ResolvedAccount {
+    const certificate = this.knobs.fork.certificates.get(r.accountName) ?? this.serve("certificate", r.certificate) ?? r.certificate;
+    const successions = r.successions?.map((l) => ({ ...l, wire: this.serve("succession", l.wire) ?? l.wire }));
+    return { ...r, certificate, ...(successions ? { successions } : {}) };
+  }
+
   private wrapDirectory(): Directory {
     // The inner transport may rebind itself per call (a device's certificate changes at
     // activation), so it is read on every call, never captured.
@@ -207,13 +215,13 @@ export class MaliciousTransport implements Transport {
         this.calls.push("resolveAccounts");
         if (k.withhold.has("certificates")) return [];
         const rs = await d().resolveAccounts(names);
-        return rs.map((r) => ({ ...r, certificate: k.fork.certificates.get(r.accountName) ?? this.serve("certificate", r.certificate) ?? r.certificate }));
+        return rs.map((r) => this.servedAccount(r));
       },
       resolveIdentities: async (ids) => {
         this.calls.push("resolveIdentities");
         if (k.withhold.has("certificates")) return [];
         const rs = await d().resolveIdentities(ids);
-        return rs.map((r) => ({ ...r, certificate: k.fork.certificates.get(r.accountName) ?? this.serve("certificate", r.certificate) ?? r.certificate }));
+        return rs.map((r) => this.servedAccount(r));
       },
       getCertificate: async (hash) => {
         this.calls.push("getCertificate");
@@ -248,7 +256,20 @@ export class MaliciousTransport implements Transport {
         this.calls.push("getResetReceipt");
         return this.serve("receipt", await d().getResetReceipt(id));
       },
-      resetAccount: (input) => this.mutate("resetAccount", () => d().resetAccount(input))
+      resetAccount: (input) => this.mutate("resetAccount", () => d().resetAccount(input)),
+      succeedAccount: (input) => this.mutate("succeedAccount", () => d().succeedAccount(input)),
+      getSuccessions: async (accountId, after, limit) => {
+        this.calls.push("getSuccessions");
+        if (k.withhold.has("successions")) return { successions: [] };
+        const page = await d().getSuccessions(accountId, after, limit);
+        return { ...page, successions: page.successions.map((l) => ({ ...l, wire: this.serve("succession", l.wire) ?? l.wire })) };
+      },
+      listCircles: async (cursor) => {
+        this.calls.push("listCircles");
+        if (k.withhold.has("circleList")) throw new KavachError("NETWORK", "transport", "network unreachable");
+        return d().listCircles(cursor);
+      },
+      setSharingPreference: (circleId, enabled, expected) => this.mutate("setSharingPreference", () => d().setSharingPreference(circleId, enabled, expected))
     };
   }
 

package/src/transactions.ts

@@ -3,7 +3,7 @@
  * live with the outbox and the inbox. Each function takes an open `Tx` so callers can compose
  * them; nothing here opens the network.
  */
-import { equalBytes, toHex } from "./bytes.js";
+import { equalBytes, fromHex, toHex } from "./bytes.js";
 import { applyAudienceEvent, initialRevisionState, type AudienceEvent } from "./audience.js";
 import { DocumentType, expectType, parseDocument, type AccountDevice } from "./codec.js";
 import { identityId } from "./crypto.js";
@@ -25,7 +25,9 @@ export const VAULT = "vault";
 export type OpenedState =
   | { readonly kind: "fresh" }
   | { readonly kind: "initializing"; readonly account: OwnAccount }
-  | { readonly kind: StoreState; readonly meta: MetaRow; readonly account: OwnAccount };
+  | { readonly kind: StoreState; readonly meta: MetaRow; readonly account: OwnAccount }
+  /** A device retired by a succession erased its account seed (amendment A1, section 4): the header stays, the key is gone. */
+  | { readonly kind: "RETIRED"; readonly meta: MetaRow; readonly account: undefined };
 
 /**
  * Bind the secret store to the local store. A mismatch between the two is `RECOVERY_REQUIRED`
@@ -36,10 +38,11 @@ export async function openStore(store: Store, secrets: SecretStore, accountName:
   const [accountSeed, instanceId] = await Promise.all([secrets.get("accountSeed"), secrets.get("instanceId")]);
   const meta = await store.read((tx) => tx.get("meta", META));
   if (!accountSeed || !instanceId) {
+    if (meta?.state === "RETIRED") return { kind: "RETIRED", meta, account: undefined };
     if (meta) throw new KavachError("RECOVERY_REQUIRED", stage, "store present but secrets missing");
     return { kind: "fresh" };
   }
-  const account = openAccount(accountName, accountSeed);
+  const account = openAccount(accountName, accountSeed, meta?.accountId ? fromHex(meta.accountId) : undefined);
   if (!meta) return { kind: "initializing", account };
   if (meta.instanceId !== toHex(instanceId) || meta.identityId !== toHex(account.identityId) || meta.accountName !== accountName || meta.schema !== 1) {
     throw new KavachError("RECOVERY_REQUIRED", stage, "store header does not match the secret store");
@@ -61,7 +64,7 @@ export async function t1Secrets(secrets: SecretStore, roots: { accountSeed: Uint
 /** T1b: the store header with the INITIALIZING marker, the own pin and the stream state. */
 export function t1Header(tx: Tx, input: { account: OwnAccount; device: DeviceKeys; certificate: Uint8Array; instanceId: Uint8Array; generation: bigint }): void {
   const doc = expectType<AccountDevice>(parseDocument(input.certificate), DocumentType.AccountDevice, "t1");
-  const pin = pinFromCertificate(doc);
+  const pin = pinFromCertificate(doc, undefined, input.account.accountId);
   if (!equalBytes(pin.identityId, input.account.identityId)) throw new KavachError("MALFORMED", "t1", "certificate is not for this account");
   tx.put("meta", META, {
     schema: 1,
@@ -70,6 +73,7 @@ export function t1Header(tx: Tx, input: { account: OwnAccount; device: DeviceKey
     instanceId: toHex(input.instanceId),
     accountName: input.account.accountName,
     identityId: toHex(input.account.identityId),
+    accountId: toHex(input.account.accountId),
     certificateHash: toHex(pin.certificateHash),
     state: "INITIALIZING"
   });
@@ -80,9 +84,12 @@ export function t1Header(tx: Tx, input: { account: OwnAccount; device: DeviceKey
     certificateHash: toHex(pin.certificateHash),
     streamId: toHex(pin.streamId)
   });
-  tx.put("pins", toHex(pin.identityId), pinToRow(pin));
+  tx.put("pins", toHex(pin.accountId), pinToRow(pin));
+  if (!tx.get("identities", toHex(pin.identityId))) {
+    tx.put("identities", toHex(pin.identityId), { accountId: toHex(pin.accountId), accountName: pin.accountName, accountKey: toHex(pin.accountKey), sinceGeneration: big(input.generation), retired: false });
+  }
   tx.put("certificates", toHex(pin.certificateHash), {
-    identityId: toHex(pin.identityId),
+    identityId: toHex(pin.accountId),
     certificateHash: toHex(pin.certificateHash),
     signingKey: toHex(pin.signingKey),
     boxKey: toHex(pin.boxKey),

package/src/transport.ts

@@ -19,6 +19,52 @@ export interface ResolvedAccount {
   readonly certificate: Uint8Array;
   /** When the account's key changed through a reset: the receipt that proves it. */
   readonly resetReceipt?: Uint8Array | undefined;
+  /** When the account's key changed through successions (revision 9): the first page of the chain from the root, each link with the successor's certificate, oldest first. */
+  readonly successions?: readonly SuccessionLink[] | undefined;
+  /** Set when `successions` is not the whole chain: the generation to continue from with `getSuccessions`. */
+  readonly successionsNext?: bigint | undefined;
+  /** With a non-empty chain: a certificate under the root key (the one the first succession replaced), so a peer can verify what that key signed. */
+  readonly rootCertificate?: Uint8Array | undefined;
+}
+
+/** One link of an account's succession chain: the type 9 document and the certificate it binds. */
+export interface SuccessionLink {
+  readonly wire: Uint8Array;
+  readonly certificate: Uint8Array;
+}
+
+export interface SuccessionPage {
+  readonly successions: readonly SuccessionLink[];
+  /** On the first page of a non-empty chain: a certificate under the root key. */
+  readonly rootCertificate?: Uint8Array | undefined;
+  /** The generation to ask after for the next page; absent when the chain ends here. */
+  readonly nextGeneration?: bigint | undefined;
+}
+
+/** One circle of the authenticated account as the host lists it for bootstrap (amendment A1, section 5). Host-trusted. */
+export interface CircleListing {
+  readonly circleId: Uint8Array;
+  readonly ownerAccountId: Uint8Array;
+  readonly role: "owner" | "member" | "pending";
+  /** The current snapshot; absent for a closed circle. */
+  readonly snapshot: Uint8Array | undefined;
+  /** The account's sharing preference the host holds; absent when none was ever set (disabled). */
+  readonly enabled: boolean | undefined;
+  readonly preferenceRevision: bigint;
+}
+
+export interface CirclePage {
+  readonly circles: readonly CircleListing[];
+  /** The cursor for the next page; absent on the last page. */
+  readonly cursor?: string | undefined;
+}
+
+export interface PreferenceOutcome {
+  readonly status: "COMMITTED" | "ALREADY_COMMITTED" | "CONFLICT" | "UNAUTHORIZED" | "RETRYABLE";
+  /** The revision the host now holds (the new one on success, the current one on conflict). */
+  readonly revision: bigint;
+  /** On CONFLICT: the value the host holds at that revision. */
+  readonly enabled?: boolean | undefined;
 }
 
 export interface JoinRequest {
@@ -41,7 +87,8 @@ export interface Directory {
     newCertificate: Uint8Array;
     newVault: Uint8Array;
   }): Promise<MutationOutcome>;
-  registerAccount(input: { certificate: Uint8Array; vault: Uint8Array }): Promise<MutationOutcome>;
+  /** `vault` is absent for an account on a recovery-only profile without a recovery provider. */
+  registerAccount(input: { certificate: Uint8Array; vault: Uint8Array | undefined }): Promise<MutationOutcome>;
   getVault(accountName: string): Promise<Uint8Array | undefined>;
   publishVault(input: { expectedRevision: bigint; expectedHash: Uint8Array | undefined; newVault: Uint8Array }): Promise<MutationOutcome>;
   getCircle(circleId: Uint8Array): Promise<Uint8Array | undefined>;
@@ -55,10 +102,30 @@ export interface Directory {
     accountName: string;
     expectedOldIdentityId: Uint8Array;
     newCertificate: Uint8Array;
-    newVault: Uint8Array;
+    newVault: Uint8Array | undefined;
     resetId: Uint8Array;
     reauthProof: Uint8Array;
   }): Promise<MutationOutcome & { receipt?: Uint8Array | undefined }>;
+  /**
+   * Account recovery (amendment A1): commit a prepared replacement. `ALREADY_COMMITTED` with the
+   * original document for a repeated `successionId` with identical bytes is answered before any
+   * authorization check; `CONFLICT` carries the current certificate; `UNAUTHORIZED` covers a
+   * missing, expired or mismatched authorization and a known id with different bytes.
+   */
+  succeedAccount(input: {
+    accountName: string;
+    expectedCertificateHash: Uint8Array;
+    newCertificate: Uint8Array;
+    newVault: Uint8Array | undefined;
+    successionId: Uint8Array;
+    authorization: Uint8Array;
+  }): Promise<MutationOutcome & { succession?: Uint8Array | undefined }>;
+  /** One page of an account's succession chain, in generation order, links whose new generation exceeds `afterGeneration`. */
+  getSuccessions(accountId: Uint8Array, afterGeneration: bigint, limit: number): Promise<SuccessionPage>;
+  /** One page of the authenticated account's circles, for bootstrap without a vault. */
+  listCircles(cursor: string | undefined): Promise<CirclePage>;
+  /** Compare-and-swap on the per-circle preference revision the host keeps for the authenticated account. */
+  setSharingPreference(circleId: Uint8Array, enabled: boolean, expectedRevision: bigint): Promise<PreferenceOutcome>;
 }
 
 export interface EpochBundle {