@plane31/blind-relay 0.2.0 → 0.4.0

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,8 +49,10 @@ export type ErrorCode =
   | "STALE_APPEND"
   // Storage and transport
   | "LOCKED"
+  | "CLOSED"
   | "RECOVERY_REQUIRED"
   | "STORAGE_FAILURE"
+  | "RATE_LIMITED"
   /** 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. */
   | "NETWORK";
 
@@ -62,6 +64,7 @@ const RETRYABLE: ReadonlySet<ErrorCode> = new Set<ErrorCode>([
   "LOCKED",
   "STORAGE_FAILURE",
   "NETWORK",
+  "RATE_LIMITED",
   "SUCCESSION_PENDING"
 ]);
 
@@ -74,13 +77,16 @@ export class KavachError extends Error {
   readonly code: ErrorCode;
   readonly stage: string;
   readonly retryable: boolean;
+  /** On `RATE_LIMITED`: how long the host asked the client to wait, when it said. */
+  readonly retryAfterMs: number | undefined;
 
-  constructor(code: ErrorCode, stage = "unknown", message?: string) {
+  constructor(code: ErrorCode, stage = "unknown", message?: string, options: { retryAfterMs?: number } = {}) {
     super(message ?? `${code} at ${stage}`);
     this.name = "KavachError";
     this.code = code;
     this.stage = stage;
     this.retryable = RETRYABLE.has(code);
+    this.retryAfterMs = options.retryAfterMs;
   }
 }
 

package/src/inbox.ts

@@ -191,6 +191,10 @@ export interface StreamSyncSummary {
   acked: bigint | undefined;
   /** The relay holds more records past the last page read; the budget stopped the catch-up. */
   hasMore: boolean;
+  /** Record bytes read from the relay. */
+  bytes: number;
+  /** Set when a read failed after the pages counted above: the caller reports it, with what landed. */
+  failure?: unknown;
 }
 
 function subscription(tx: Pick<Tx, "get">, streamId: Uint8Array, authorIdentityId: Uint8Array): SubscriptionRow {
@@ -236,23 +240,29 @@ export interface ReadBudget {
  * records past the last page when the budget stopped the loop.
  */
 export async function syncStream(deps: InboxDeps, streamId: Uint8Array, authorIdentityId: Uint8Array, budget: ReadBudget = { remainingRecords: READ_BATCH, deadline: deps.now() }): Promise<StreamSyncSummary> {
-  const summary: StreamSyncSummary = { read: 0, stored: 0, duplicate: 0, keyPending: 0, invalid: 0, expired: 0, acked: undefined, hasMore: false };
+  const summary: StreamSyncSummary = { read: 0, stored: 0, duplicate: 0, keyPending: 0, invalid: 0, expired: 0, acked: undefined, hasMore: false, bytes: 0 };
   const sub = await deps.store.read((tx) => subscription(tx, streamId, authorIdentityId));
   const unresolved = await deps.store.read((tx) => tx.list("unresolved", toHex(streamId) + ":"));
   let from = unresolved.length > 0 ? unbig(sub.ackPrefix) : unbig(sub.scanPos);
-  for (;;) {
-    // A failed read is the caller's to report: the sync names the stream in its report and goes
-    // on to the next one, rather than counting a stream it never read as synced.
-    const page = await deps.relay.readRecords(streamId, from, READ_BATCH);
-    await processPage(deps, streamId, authorIdentityId, page, summary);
-    budget.remainingRecords -= page.records.length;
-    const caughtUp = page.nextSeq >= page.tail || page.nextSeq <= from;
-    if (caughtUp) break;
-    if (budget.remainingRecords <= 0 || deps.now() >= budget.deadline) {
-      summary.hasMore = true;
-      break;
+  try {
+    for (;;) {
+      // A failed read is the caller's to report: the sync names the stream in its report and goes
+      // on to the next one, rather than counting a stream it never read as synced.
+      const page = await deps.relay.readRecords(streamId, from, READ_BATCH);
+      await processPage(deps, streamId, authorIdentityId, page, summary);
+      budget.remainingRecords -= page.records.length;
+      const caughtUp = page.nextSeq >= page.tail || page.nextSeq <= from;
+      if (caughtUp) break;
+      if (budget.remainingRecords <= 0 || deps.now() >= budget.deadline) {
+        summary.hasMore = true;
+        break;
+      }
+      from = page.nextSeq;
     }
-    from = page.nextSeq;
+  } catch (e) {
+    // The pages that landed before the failure are real work: the summary keeps them and carries
+    // the failure beside them, untouched, for the caller to report.
+    summary.failure = e;
   }
   return summary;
 }
@@ -269,6 +279,7 @@ async function processPage(deps: InboxDeps, streamId: Uint8Array, authorIdentity
   }
   for (const item of page.records) {
     summary.read++;
+    summary.bytes += item.wire.length;
     if (item.deliverySeq <= page.expiredThrough) {
       summary.expired++;
       continue;

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,10 +31,13 @@ export {
   type OpenOptions,
   type PauseReason,
   type ReceiveResult,
+  type ReplaceDeviceOptions,
+  type ReplaceDeviceResult,
   type ReplacementProposal,
   type SyncError,
   type SyncOptions,
-  type SyncReport
+  type SyncReport,
+  type SyncTimings
 } from "./client.js";
 
 // Errors -------------------------------------------------------------------------------------------

package/src/outbox.ts

@@ -199,6 +199,10 @@ export interface DrainSummary {
   cancelled: number;
   unknown: number;
   retry: number;
+  /** Record bytes handed to the relay by this drain. */
+  bytes: number;
+  /** The error that ended the drain early, when a send failed before or without an answer (NETWORK, RATE_LIMITED); its record stays queued. */
+  blocked?: KavachError;
 }
 
 /** "none": nothing to send, the drain ends. "skipped": a row was cancelled, the next one is tried. */
@@ -211,17 +215,19 @@ type HandoffStep = { kind: "none" } | { kind: "skipped" } | { kind: "sent"; key:
  * revalidates first.
  */
 export async function drain(deps: OutboxDeps, maxRecords = 1000): Promise<DrainSummary> {
-  const summary: DrainSummary = { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0 };
+  const summary: DrainSummary = { sent: 0, accepted: 0, cancelled: 0, unknown: 0, retry: 0, bytes: 0 };
   for (let i = 0; i < maxRecords; i++) {
     const step = await handoffNext(deps, summary);
     if (step.kind === "none") break;
     if (step.kind === "skipped") continue; // a cancelled row counts against the limit, never ends the drain
     summary.sent++;
+    summary.bytes += step.row.wire.length / 2;
     let outcome: AppendOutcome | undefined;
     try {
       outcome = await step.outcome;
-    } catch {
-      outcome = undefined; // lost response
+    } catch (e) {
+      outcome = undefined; // no answer: the identical bytes are retried, the relay answers from its checkpoint
+      if (e instanceof KavachError) summary.blocked ??= e; // and the reason reaches the report
     }
     const final = await recordOutcome(deps, step.key, outcome);
     if (final === "accepted") summary.accepted++;

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,14 @@ 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;
+  /** Mutations whose next call fails with exactly this error before reaching the host (consumed once). */
+  readonly failWith: Map<MutationName, KavachError>;
+  /** Record reads fail once with NETWORK after this many pages have been served. */
+  failReadsAfter?: number | undefined;
   /** 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;
@@ -140,6 +146,7 @@ export function emptyKnobs(): MaliciousKnobs {
     loseResponseOf: new Set(),
     refuse: new Set(),
     hold: new Map(),
+    failWith: new Map(),
     withhold: new Set(),
     replay: { snapshots: new Map() },
     fork: { snapshots: new Map(), manifests: new Map(), records: new Map(), certificates: new Map() },
@@ -188,6 +195,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)) {
@@ -295,6 +303,11 @@ export class MaliciousTransport implements Transport {
       appendRecord: (recordId, wire) => {
         // Must stay synchronous up to the inner call (T6h).
         this.calls.push("appendRecord");
+        const fail = k.failWith.get("appendRecord");
+        if (fail) {
+          k.failWith.delete("appendRecord");
+          return Promise.reject(fail);
+        }
         const p = r().appendRecord(recordId, wire);
         if (!k.loseResponseOf.has("appendRecord")) return p;
         k.loseResponseOf.delete("appendRecord");
@@ -305,6 +318,13 @@ export class MaliciousTransport implements Transport {
       },
       readRecords: async (streamId, afterSeq, limit): Promise<ReadRecordsResult> => {
         this.calls.push("readRecords");
+        if (k.failReadsAfter !== undefined) {
+          if (k.failReadsAfter <= 0) {
+            k.failReadsAfter = undefined;
+            throw Object.freeze(new KavachError("NETWORK", "transport", "network unreachable")); // frozen, as a transport may hand it over
+          }
+          k.failReadsAfter--;
+        }
         if (k.withhold.has("records")) {
           const probe = await r().readRecords(streamId, afterSeq, limit);
           return { ...probe, records: [], nextSeq: afterSeq };
@@ -328,6 +348,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();
       }
     };