@plane31/blind-relay 0.2.0 → 0.3.0

package/src/client.ts

@@ -167,6 +167,22 @@ export interface Client {
   completeReplacement(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }>;
   /** The key changes this device accepted for its contacts, newest first, bounded. */
   keyChanges(options?: { accountId?: Uint8Array; limit?: number }): Promise<KeyChangeEntry[]>;
+  /**
+   * Account recovery as one call over `prepareReplacement` and `completeReplacement`, with the
+   * protocol's retry rules: an earlier proposal is settled through the chain first; the same
+   * proposal is kept through an unknown outcome and a refused authorization; a new proposal is
+   * made only after a definitive conflict, and then only by the next call. The product supplies
+   * `authorize`, which obtains the host's token for a proposal after its own fresh sign-in, or
+   * answers `"reauthenticate"` when it cannot. Attempts are bounded; `pending` means call again.
+   */
+  replaceDevice(options: ReplaceDeviceOptions): Promise<ReplaceDeviceResult>;
+  /**
+   * Synchronise in rounds until nothing is left that this device can do now: the relay has no
+   * more records within the budget, bootstrap is complete, or progress needs someone else (an
+   * authorization, another person, metadata the host does not serve). Bounded by rounds and by
+   * time; the result says why it stopped and what remains.
+   */
+  syncUntilDrained(options?: DrainOptions): Promise<DrainReport>;
   /** A durable outbound record of a declared kind; the payload is the product's bytes, never read by the SDK. */
   enqueue(kind: RecordKind, payload: Uint8Array, options?: EnqueueOptions): Promise<EnqueueResult>;
   /** One synchronisation; `options.catchUp` bounds how much of a backlog this call reads (`SyncReport.inbox.hasMore` says when to call again). */
@@ -192,9 +208,70 @@ export interface Client {
     list(): Promise<readonly CircleSummary[]>;
   };
   resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }>;
+  /**
+   * Stop: no new operation is accepted (`CLOSED`), the operations in flight finish their current
+   * transaction and a running sync stops at its next phase boundary, then listeners are cleared
+   * so nothing is emitted afterwards. Closes nothing it did not open: the store and the secret
+   * store are the caller's. Idempotent.
+   */
   close(): Promise<void>;
 }
 
+export interface ReplaceDeviceOptions {
+  /** Obtain the host's authorization for this proposal after the product's fresh sign-in, or say that a sign-in is needed first. */
+  readonly authorize: (proposal: ReplacementProposal) => Promise<Uint8Array | "reauthenticate">;
+  /** Commit attempts per call, over unknown outcomes and refused authorizations. Default 3. */
+  readonly maxAttempts?: number;
+}
+
+export type ReplaceDeviceResult =
+  | { readonly status: "activated"; readonly identityId: Uint8Array; readonly generation: bigint }
+  /** The outcome is still unknown or the attempts are spent: the proposal is kept; call again. */
+  | { readonly status: "pending"; readonly proposal: ReplacementProposal }
+  /** The account moved under the proposal, which is discarded; the next call prepares a new one after a fresh sign-in. */
+  | { readonly status: "conflict"; readonly currentGeneration: bigint | undefined }
+  /** The product's `authorize` asked for a fresh sign-in; the proposal is kept for the next call. */
+  | { readonly status: "reauthenticate"; readonly proposal: ReplacementProposal };
+
+export interface DrainOptions {
+  readonly catchUp?: SyncOptions["catchUp"];
+  /** Rounds at most. Default 10. */
+  readonly maxRounds?: number;
+  /** A soft bound in milliseconds across every round: no round starts past it and each round's reading budget is the time left, but a transport call already in flight ends on its own timeout. Default 30,000. */
+  readonly maxMs?: number;
+}
+
+export type DrainStop =
+  /** Nothing is left that this device can do now. */
+  | "drained"
+  | "maxRounds"
+  | "maxMs"
+  /** A round changed nothing and reported the same errors as the one before. */
+  | "noProgress"
+  /** Progress needs metadata the host does not serve yet (a chain, a certificate, the key list). */
+  | "metadata"
+  /** Progress needs an authorization or a sign-in (a prepared replacement, an account to recover). */
+  | "authentication"
+  /** Nothing more is reported, but a round could not read its inbox fully (discovery or a stream failed), so emptiness is not established. */
+  | "incomplete"
+  | "closed";
+
+/** The merged report of every round, with why the loop stopped and what remains. */
+export interface DrainReport extends SyncReport {
+  readonly rounds: number;
+  readonly stoppedBecause: DrainStop;
+  readonly remaining: {
+    /** The relay still holds records this device has not read; `"unknown"` when the last round could not read its inbox fully. */
+    readonly inboxHasMore: boolean | "unknown";
+    /** Bootstrap after account recovery has circles left to adopt. */
+    readonly bootstrapIncomplete: boolean;
+    /** Contacts whose succession chain this device has verified only partly; the next rounds continue them. */
+    readonly chainsIncomplete: number;
+    /** Authors whose current epoch has not reached this device: nothing to do but wait for them. */
+    readonly waitingFor: number;
+  };
+}
+
 export interface SyncOptions {
   /**
    * The inbox budget of this sync, shared by every stream: at most this many records
@@ -292,6 +369,9 @@ class ClientImpl implements Client {
   private selfPin: AccountPin | undefined;
   private trust: ResetTrust;
   private syncing: Promise<SyncReport> | undefined;
+  private closed = false;
+  /** Every public operation in flight, so `close()` can wait for them. */
+  private readonly running = new Set<Promise<unknown>>();
   /** The current sync's reading budget: records, and the links of a succession chain, count against it. */
   private syncBudget: ReadBudget | undefined;
   private backupChecked = false;
@@ -309,17 +389,56 @@ class ClientImpl implements Client {
     this.now = options.now ?? ((): bigint => BigInt(Date.now()));
     this.trust = new ResetTrust(options.resetTrust);
     this.circles = {
-      create: () => this.createCircle(),
-      requestJoin: (c, o, opts) => this.requestJoin(c, o, opts?.shareOnApproval ?? true),
-      approve: (c, n) => this.approve(c, n),
-      remove: (c, m) => this.changeMembership(c, { remove: m }),
-      leave: (c) => this.leave(c),
-      setEnabled: (c, e) => this.setEnabled(c, e),
-      closeCircle: (c) => this.closeCircle(c),
+      create: () => this.track("createCircle", () => this.createCircle()),
+      requestJoin: (c, o, opts) => this.track("requestJoin", () => this.requestJoin(c, o, opts?.shareOnApproval ?? true)),
+      approve: (c, n) => this.track("approve", () => this.approve(c, n)),
+      remove: (c, m) => this.track("changeMembership", () => this.changeMembership(c, { remove: m })),
+      leave: (c) => this.track("leave", () => this.leave(c)),
+      setEnabled: (c, e) => this.track("setEnabled", () => this.setEnabled(c, e)),
+      closeCircle: (c) => this.track("closeCircle", () => this.closeCircle(c)),
       list: () => this.listCircles()
     };
   }
 
+  // Every public operation that writes enters through `track`, explicitly and typed, so `close()`
+  // refuses new ones and waits for those in flight. Reads stay untracked.
+
+  initializeAccount(): Promise<{ identityId: Uint8Array }> {
+    return this.track("initializeAccount", () => this.initializeAccountNow());
+  }
+
+  restoreAccount(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }> {
+    return this.track("restoreAccount", () => this.restoreAccountNow(recoveryCode));
+  }
+
+  enqueue(kind: RecordKind, payload: Uint8Array, options: EnqueueOptions = {}): Promise<EnqueueResult> {
+    return this.track("enqueue", () => this.enqueueNow(kind, payload, options));
+  }
+
+  receive(wire: Uint8Array): Promise<ReceiveResult> {
+    return this.track("receive", () => receiveRecord(this.inboxDeps(), wire));
+  }
+
+  prepareReplacement(): Promise<ReplacementProposal> {
+    return this.track("prepareReplacement", () => this.prepareReplacementNow());
+  }
+
+  completeReplacement(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }> {
+    return this.track("completeReplacement", () => this.completeReplacementNow(input));
+  }
+
+  resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
+    return this.track("resetAccount", () => this.resetAccountNow(options));
+  }
+
+  replaceDevice(options: ReplaceDeviceOptions): Promise<ReplaceDeviceResult> {
+    return this.track("replaceDevice", () => this.replaceDeviceNow(options));
+  }
+
+  syncUntilDrained(options: DrainOptions = {}): Promise<DrainReport> {
+    return this.track("syncUntilDrained", () => this.drainNow(options));
+  }
+
   // Loading ---------------------------------------------------------------------------------------
 
   async load(): Promise<void> {
@@ -354,8 +473,18 @@ class ClientImpl implements Client {
     });
   }
 
-  /** Each listener on its own: a throwing subscriber affects neither the other listeners nor the protocol. */
+  /** Refuse after `close()`, and keep the operation's promise until it settles. */
+  private track<T>(stage: string, fn: () => Promise<T>): Promise<T> {
+    if (this.closed) return Promise.reject(new KavachError("CLOSED", stage, "the client is closed"));
+    const p = fn();
+    this.running.add(p);
+    void p.finally(() => this.running.delete(p)).catch(() => undefined);
+    return p;
+  }
+
+  /** Each listener on its own: a throwing subscriber affects neither the other listeners nor the protocol. Nothing after `close()`. */
   private emit(event: ClientEvent): void {
+    if (this.closed) return;
     for (const l of this.listeners) {
       try {
         l(event);
@@ -489,7 +618,7 @@ class ClientImpl implements Client {
 
   // Enrollment ------------------------------------------------------------------------------------
 
-  async initializeAccount(): Promise<{ identityId: Uint8Array }> {
+  private async initializeAccountNow(): Promise<{ identityId: Uint8Array }> {
     const stage = "initializeAccount";
     const opened = await openStore(this.store, this.secrets, this.accountName);
     if (opened.kind !== "fresh" && opened.kind !== "initializing") throw new KavachError("MALFORMED", stage, "an account already exists on this device");
@@ -551,7 +680,7 @@ class ClientImpl implements Client {
     return encodeRecoveryCode(key);
   }
 
-  async restoreAccount(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }> {
+  private async restoreAccountNow(recoveryCode?: string): Promise<{ identityId: Uint8Array; generation: bigint }> {
     const stage = "restoreAccount";
     const opened = await openStore(this.store, this.secrets, this.accountName);
     if (opened.kind === "ACTIVE" || opened.kind === "RETIRED") throw new KavachError("MALFORMED", stage, "an account already exists on this device");
@@ -720,7 +849,7 @@ class ClientImpl implements Client {
 
   // Sending ---------------------------------------------------------------------------------------
 
-  async enqueue(kind: RecordKind, payload: Uint8Array, options: EnqueueOptions = {}): Promise<EnqueueResult> {
+  private async enqueueNow(kind: RecordKind, payload: Uint8Array, options: EnqueueOptions): Promise<EnqueueResult> {
     const deps = this.outboxDeps();
     // A key answered before anything that may need the network: the record it names is already
     // durable, so a retry offline, or with a rotation due, returns it. The outbox checks the key
@@ -839,12 +968,107 @@ class ClientImpl implements Client {
 
   async sync(options: SyncOptions = {}): Promise<SyncReport> {
     if (this.syncing) return this.syncing;
-    this.syncing = this.runSync(options).finally(() => {
+    if (this.closed) throw new KavachError("CLOSED", "sync", "the client is closed");
+    this.syncing = this.track("sync", () => this.runSync(options)).finally(() => {
       this.syncing = undefined;
     });
     return this.syncing;
   }
 
+  private async drainNow(options: DrainOptions): Promise<DrainReport> {
+    const maxRounds = Math.max(1, Math.floor(options.maxRounds ?? 10));
+    const maxMs = Math.max(0, Math.floor(options.maxMs ?? 30_000));
+    const deadline = this.now() + BigInt(maxMs);
+    const merged: SyncReport = {
+      metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 },
+      epoch: "unchanged",
+      outbox: { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 },
+      inbox: { streams: 0, stored: 0, keyPending: 0, invalid: 0, acked: 0, hasMore: false },
+      purged: 0,
+      errors: []
+    };
+    let rounds = 0;
+    let previousErrors: string | undefined;
+    let stop: DrainStop = "drained";
+    let last: SyncReport | undefined;
+    // An inbox this device could not fully read this round: discovery or a stream failed, or metadata it
+    // depends on did. Such a round never establishes that the inbox is empty.
+    const inboxUncertain = (r: SyncReport): boolean => r.errors.some((e) => e.operation === "listSubscriptions" || e.operation === "inbox" || e.operation === "metadata");
+    // Chains verified only partly: remaining work, and their cursors moving is progress.
+    const chains = (): Promise<Map<string, string>> => this.store.read((tx) => new Map(tx.list("chainProgress").filter(([, c]) => !c.complete).map(([k, c]) => [k, c.nextGeneration])));
+    let previousChains = await chains();
+    for (;;) {
+      if (this.closed) {
+        stop = "closed";
+        break;
+      }
+      // The time left is this round's reading budget too, so a round never starts work the deadline
+      // does not cover; a transport call already in flight ends on its own timeout.
+      const remainingMs = Number(deadline - this.now());
+      if (rounds > 0 && remainingMs <= 0) {
+        stop = "maxMs";
+        break;
+      }
+      const roundMs = Math.max(0, Math.min(remainingMs, options.catchUp?.maxMs ?? DEFAULT_CATCH_UP.maxMs));
+      const r = await this.sync({ catchUp: { maxMs: roundMs, ...(options.catchUp?.maxRecords !== undefined ? { maxRecords: options.catchUp.maxRecords } : {}) } });
+      rounds++;
+      last = r;
+      // The round's work counts whether or not it was the last: what it accepted, stored and failed
+      // is merged first, and only then is a close that landed meanwhile reported.
+      for (const k of Object.keys(merged.metadata) as (keyof SyncReport["metadata"])[]) merged.metadata[k] += r.metadata[k];
+      for (const k of Object.keys(merged.outbox) as (keyof SyncReport["outbox"])[]) merged.outbox[k] += r.outbox[k];
+      merged.inbox.streams += r.inbox.streams;
+      merged.inbox.stored += r.inbox.stored;
+      merged.inbox.keyPending += r.inbox.keyPending;
+      merged.inbox.invalid += r.inbox.invalid;
+      merged.inbox.acked += r.inbox.acked;
+      merged.purged += r.purged;
+      merged.epoch = r.epoch;
+      merged.errors.push(...r.errors);
+      if (r.bootstrap) merged.bootstrap = r.bootstrap;
+      if (this.closed) {
+        // The round may have stopped at a boundary before its inbox: nothing it reports is complete.
+        stop = "closed";
+        break;
+      }
+      const bootstrapIncomplete = (await this.inspect()).bootstrap?.complete === false;
+      const currentChains = await chains();
+      const more = r.inbox.hasMore || bootstrapIncomplete || currentChains.size > 0;
+      const status = (await this.getState()).status;
+      if (status === "replacementPrepared" || status === "accountRecoveryRequired") {
+        stop = "authentication";
+        break;
+      }
+      if (!more) {
+        stop = inboxUncertain(r) ? "incomplete" : "drained";
+        break;
+      }
+      const signature = r.errors.map((e) => `${e.operation}:${e.code}`).sort().join(",");
+      const chainsAdvanced = [...currentChains].some(([k, next]) => previousChains.get(k) !== next) || [...previousChains.keys()].some((k) => !currentChains.has(k));
+      previousChains = currentChains;
+      const changed = chainsAdvanced || r.inbox.stored + r.metadata.certificates + r.metadata.snapshots + r.metadata.successions + (r.bootstrap?.circles ?? 0) + (r.bootstrap?.pending ?? 0) > 0;
+      if (!changed && signature !== "" && signature === previousErrors) {
+        stop = r.errors.some((e) => e.code === "METADATA_REQUIRED" || e.code === "RESET_KEYS_REQUIRED" || e.code === "RESET_CLOCK_UNTRUSTED") ? "metadata" : "noProgress";
+        break;
+      }
+      previousErrors = signature;
+      if (rounds >= maxRounds) {
+        stop = "maxRounds";
+        break;
+      }
+      if (this.now() >= deadline) {
+        stop = "maxMs";
+        break;
+      }
+    }
+    merged.inbox.hasMore = last?.inbox.hasMore ?? false;
+    const bootstrapIncomplete = this.closed ? false : (await this.inspect()).bootstrap?.complete === false;
+    const chainsIncomplete = this.closed ? previousChains.size : (await chains()).size;
+    const waitingFor = this.closed ? 0 : (await this.getState()).waitingFor.length;
+    const inboxHasMore = !last || inboxUncertain(last) || stop === "closed" ? "unknown" : merged.inbox.hasMore;
+    return { ...merged, rounds, stoppedBecause: stop, remaining: { inboxHasMore, bootstrapIncomplete, chainsIncomplete, waitingFor } };
+  }
+
   private async runSync(options: SyncOptions): Promise<SyncReport> {
     const report: SyncReport = {
       metadata: { certificates: 0, snapshots: 0, rotations: 0, quarantined: 0, resets: 0, successions: 0 },
@@ -914,17 +1138,19 @@ class ClientImpl implements Client {
       report.errors.push(syncError("preference", e));
     }
     const after = await this.store.read((tx) => tx.get("meta", META));
-    if (after?.state === "RETIRED") return report;
+    if (after?.state === "RETIRED" || this.closed) return report;
     try {
       report.epoch = await this.ensureEpoch();
     } catch (e) {
       report.errors.push(syncError("epoch", e));
     }
+    if (this.closed) return report;
     try {
       report.outbox = await drain(this.outboxDeps());
     } catch (e) {
       report.errors.push(syncError("outbox", e));
     }
+    if (this.closed) return report;
     let subs: Awaited<ReturnType<Relay["listSubscriptions"]>> = [];
     try {
       subs = await this.transport.relay.listSubscriptions();
@@ -937,6 +1163,7 @@ class ClientImpl implements Client {
     const budget: ReadBudget = this.syncBudget;
     if (budget.remainingRecords < 1) budget.remainingRecords = 1; // every stream reads at least one page
     for (const s of subs) {
+      if (this.closed) return report;
       try {
         const known = await this.store.read((tx) => tx.list("certificates").some(([, c]) => c.streamId === toHex(s.streamId)));
         if (!known) continue;
@@ -1480,10 +1707,6 @@ class ClientImpl implements Client {
 
   // Receiving and reads ---------------------------------------------------------------------------
 
-  receive(wire: Uint8Array): Promise<ReceiveResult> {
-    return receiveRecord(this.inboxDeps(), wire);
-  }
-
   history(query?: HistoryQuery): Promise<HistoryEntry[]> {
     return history(this.store, this.policy, query);
   }
@@ -1848,7 +2071,7 @@ class ClientImpl implements Client {
 
   // Account recovery (amendment A1) ---------------------------------------------------------------
 
-  async prepareReplacement(): Promise<ReplacementProposal> {
+  private async prepareReplacementNow(): Promise<ReplacementProposal> {
     const stage = "prepareReplacement";
     if (!acceptsSuccession(this.policy)) throw new KavachError("NOT_AUTHORIZED", stage, "this deployment does not use account recovery");
     const opened = await openStore(this.store, this.secrets, this.accountName);
@@ -1893,7 +2116,7 @@ class ClientImpl implements Client {
     return proposalOf(row);
   }
 
-  async completeReplacement(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }> {
+  private async completeReplacementNow(input: { successionId: Uint8Array; authorization: Uint8Array }): Promise<{ identityId: Uint8Array; generation: bigint }> {
     const stage = "completeReplacement";
     // Already activated (by an earlier call, or by a sync that found the commit on the chain): idempotent.
     if (this.selfPin && this.account && !this.retired) return { identityId: this.selfPin.identityId, generation: this.selfPin.generation };
@@ -2143,7 +2366,7 @@ class ClientImpl implements Client {
 
   // Reset -----------------------------------------------------------------------------------------
 
-  async resetAccount(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
+  private async resetAccountNow(options: { confirmed: true; reauthProof?: Uint8Array }): Promise<{ identityId: Uint8Array }> {
     const stage = "resetAccount";
     if (!options.confirmed) throw new KavachError("NOT_AUTHORIZED", stage, "reset requires confirmation");
     const { pin } = this.requireAccount(stage);
@@ -2227,7 +2450,50 @@ class ClientImpl implements Client {
   }
 
   async close(): Promise<void> {
+    this.closed = true;
+    // Everything in flight finishes its current transaction; a sync stops at its next boundary.
+    while (this.running.size > 0) await Promise.allSettled([...this.running]);
     this.listeners.clear();
   }
+
+  // The replacement helper ------------------------------------------------------------------------
+
+  private async replaceDeviceNow(options: ReplaceDeviceOptions): Promise<ReplaceDeviceResult> {
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
+    const activated = (): ReplaceDeviceResult | undefined => (this.selfPin && this.account && !this.retired ? { status: "activated", identityId: this.selfPin.identityId, generation: this.selfPin.generation } : undefined);
+    const done = activated();
+    if (done) return done;
+    // A proposal left by an earlier run may have committed: the chain settles it before anything else.
+    const existing = await this.store.read((tx) => tx.get("replacement", "pending"));
+    if (existing && !existing.stale) {
+      await this.sync();
+      const settled = activated();
+      if (settled) return settled;
+    }
+    const proposal = await this.prepareReplacementNow();
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const authorization = await options.authorize(proposal);
+      if (authorization === "reauthenticate") return { status: "reauthenticate", proposal };
+      for (;;) {
+        try {
+          const r = await this.completeReplacementNow({ successionId: proposal.successionId, authorization });
+          return { status: "activated", identityId: r.identityId, generation: r.generation };
+        } catch (e) {
+          if (isKavachError(e, "SUCCESSION_PENDING")) {
+            // The same call again with the same bytes; the host answers a committed id first.
+            if (++attempt >= maxAttempts) return { status: "pending", proposal };
+            continue;
+          }
+          if (isKavachError(e, "AUTHORIZATION_REQUIRED")) break; // a fresh token for the same proposal
+          if (isKavachError(e, "REPLACEMENT_CONFLICT")) {
+            const conflict = (await this.inspect()).replacement;
+            return { status: "conflict", currentGeneration: conflict?.conflictGeneration };
+          }
+          throw e;
+        }
+      }
+    }
+    return { status: "pending", proposal };
+  }
 }
 

package/src/crypto/noble.ts

@@ -4,7 +4,24 @@ import { hsalsa, xsalsa20poly1305 } from "@noble/ciphers/salsa";
 import { ed25519, x25519 } from "@noble/curves/ed25519";
 import { blake2b } from "@noble/hashes/blake2b";
 import { sha512 } from "@noble/hashes/sha512";
-import { randomBytes } from "@noble/hashes/utils";
+import { KavachError } from "../errors.js";
+
+/**
+ * Randomness from the Web Crypto global, read at every call. `@noble/hashes` captures
+ * `globalThis.crypto` once when it is imported, which on Hermes is before the app has installed
+ * a source (the Expo helper installs expo-crypto's inside `openKavach`), so noble's own
+ * `randomBytes` would throw for the life of the process. Reading the global here, when the bytes
+ * are needed, sees whatever is installed by then.
+ */
+function randomBytes(length: number): Uint8Array {
+  const g = globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => Uint8Array } };
+  const get = g.crypto?.getRandomValues;
+  if (typeof get !== "function") throw new KavachError("INVALID_KEY", "randomBytes", "no crypto.getRandomValues: install a secure random source before opening Kavach");
+  const out = new Uint8Array(length);
+  // Web Crypto caps one call at 65,536 bytes; nothing here is near it, but the rule is kept.
+  for (let offset = 0; offset < length; offset += 65_536) get.call(g.crypto, out.subarray(offset, Math.min(length, offset + 65_536)));
+  return out;
+}
 import type { BoxKeypair, CryptoBackend, SignKeypair } from "./backend.js";
 
 // "expand 32-byte k" as little-endian u32 words: the Salsa constant.

package/src/errors.ts

@@ -49,6 +49,7 @@ export type ErrorCode =
   | "STALE_APPEND"
   // Storage and transport
   | "LOCKED"
+  | "CLOSED"
   | "RECOVERY_REQUIRED"
   | "STORAGE_FAILURE"
   /** The host could not be reached or did not answer in time; the same call may succeed later. A transport raises it, never a plain error. */

package/src/index.ts

@@ -14,6 +14,9 @@ export {
   open,
   type CircleSummary,
   type Client,
+  type DrainOptions,
+  type DrainReport,
+  type DrainStop,
   type ClientEvent,
   type ClientState,
   type ClientStatus,
@@ -28,6 +31,8 @@ export {
   type OpenOptions,
   type PauseReason,
   type ReceiveResult,
+  type ReplaceDeviceOptions,
+  type ReplaceDeviceResult,
   type ReplacementProposal,
   type SyncError,
   type SyncOptions,

package/src/store.ts

@@ -19,6 +19,9 @@ export interface SecretStore {
 
 export type SecretName = "accountSeed" | "deviceSeed" | "recoveryKey" | "storageKey" | "instanceId" | "pendingReset" | "pendingReplacement";
 
+/** Every secret the SDK keeps for an account, in the order an erasure deletes them: the account's roots first, the storage key last, so an interrupted erasure leaves a store that refuses to open rather than one that re-enrolls under old roots. */
+export const SECRET_NAMES: readonly SecretName[] = ["accountSeed", "deviceSeed", "recoveryKey", "instanceId", "pendingReset", "pendingReplacement", "storageKey"];
+
 // Logical tables. Rows are JSON-safe: bytes as hex strings, u64 as decimal strings.
 
 export type StoreState = "INITIALIZING" | "ACTIVE" | "ACTIVATION_PENDING" | "RETIRED";

package/src/testing/faults.ts

@@ -111,8 +111,10 @@ export interface MaliciousKnobs {
   readonly refuse: Set<MutationName>;
   /** Mutations whose next response waits for the given promise after the host committed (consumed once). */
   readonly hold: Map<MutationName, Promise<void>>;
+  /** Called when a held mutation has reached its gate (the host has answered; the response is being held), so a test can act at exactly that point. */
+  onHeld?: (name: MutationName) => void;
   /** Reads that answer "nothing" while present. */
-  readonly withhold: Set<"snapshots" | "epochs" | "records" | "requests" | "currentEpoch" | "keyList" | "certificates" | "successions" | "circleList">;
+  readonly withhold: Set<"snapshots" | "epochs" | "records" | "requests" | "currentEpoch" | "keyList" | "certificates" | "successions" | "circleList" | "subscriptions">;
   /** Older documents served instead of the current ones. */
   readonly replay: {
     vault?: Uint8Array;
@@ -188,6 +190,7 @@ export class MaliciousTransport implements Transport {
     const gate = this.knobs.hold.get(name);
     if (gate) {
       this.knobs.hold.delete(name);
+      this.knobs.onHeld?.(name);
       await gate;
     }
     if (this.knobs.loseResponseOf.has(name)) {
@@ -328,6 +331,7 @@ export class MaliciousTransport implements Transport {
       ackThrough: (streamId, cursor) => this.mutate("ackThrough", () => r().ackThrough(streamId, cursor)),
       listSubscriptions: async () => {
         this.calls.push("listSubscriptions");
+        if (k.withhold.has("subscriptions")) throw new KavachError("NETWORK", "transport", "network unreachable");
         return r().listSubscriptions();
       }
     };