@plane31/blind-relay 0.3.0 → 0.5.0

package/src/crypto/sodiumLike.ts

@@ -0,0 +1,169 @@
+/**
+ * A libsodium backend over any object with libsodium's JavaScript API: `libsodium-wrappers-sumo`
+ * on Node (wasm), or a native binding on a phone (`react-native-libsodium` over JSI), where it
+ * replaces the portable backend's pure-JavaScript Ed25519 and X25519 with the C implementation.
+ *
+ * Bindings differ from libsodium's reference API in small ways (react-native-libsodium 1.7 has
+ * no `crypto_scalarmult`, no `memzero`, no `crypto_core_ed25519_is_valid_point`, and its AEAD
+ * takes only string associated data, while the protocol's is binary). So the backend is built per
+ * function: each one the binding provides is checked once against the portable implementation
+ * on known inputs, and a function the binding lacks or gets wrong on a type it does not support
+ * falls back to the portable one, while a function that answers differently on the same input is
+ * refused outright, since silently wrong bytes would be worse than slow ones. The caller awaits
+ * `sodium.ready` before building. Both backends pass the same vectors.
+ */
+import { KavachError } from "../errors.js";
+import type { BoxKeypair, CryptoBackend, SignKeypair } from "./backend.js";
+import { nobleBackend } from "./noble.js";
+
+/** The subset of libsodium's API the backend can use; everything but signing, boxing and hashing may be absent. */
+export interface SodiumLike {
+  crypto_generichash(outLen: number, data: Uint8Array, key?: Uint8Array | null): Uint8Array;
+  randombytes_buf(length: number): Uint8Array;
+  crypto_sign_seed_keypair(seed: Uint8Array): { publicKey: Uint8Array; privateKey: Uint8Array };
+  crypto_sign_detached(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+  crypto_sign_verify_detached(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+  crypto_core_ed25519_is_valid_point?(point: Uint8Array): boolean;
+  crypto_box_seed_keypair(seed: Uint8Array): { publicKey: Uint8Array; privateKey: Uint8Array };
+  crypto_box_keypair(): { publicKey: Uint8Array; privateKey: Uint8Array };
+  crypto_scalarmult?(secretKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+  crypto_box_easy(message: Uint8Array, nonce: Uint8Array, publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
+  crypto_box_open_easy(box: Uint8Array, nonce: Uint8Array, publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
+  crypto_aead_xchacha20poly1305_ietf_encrypt?(message: Uint8Array, aad: Uint8Array | null, secretNonce: Uint8Array | null, nonce: Uint8Array, key: Uint8Array): Uint8Array;
+  crypto_aead_xchacha20poly1305_ietf_decrypt?(secretNonce: Uint8Array | null, ciphertext: Uint8Array, aad: Uint8Array | null, nonce: Uint8Array, key: Uint8Array): Uint8Array;
+  memzero?(bytes: Uint8Array): void;
+}
+
+/** Which of the backend's operations run on the binding and which on the portable implementation, after the build-time check. */
+export interface SodiumBackendReport {
+  readonly native: readonly string[];
+  readonly portable: readonly string[];
+}
+
+const same = (a: Uint8Array, b: Uint8Array): boolean => a.length === b.length && a.every((x, i) => x === b[i]);
+/** The X25519 base point, for deriving a public key from a secret scalar on the portable implementation. */
+const X25519_BASE = Uint8Array.from([9, ...new Array<number>(31).fill(0)]);
+
+/** Build the backend; see the module comment for how each function is checked. */
+export function sodiumBackend(sodium: SodiumLike): CryptoBackend {
+  return buildSodiumBackend(sodium).backend;
+}
+
+/** One build per binding object: the checks run once in a JavaScript context, however often the same binding is installed. */
+const built = new WeakMap<SodiumLike, { backend: CryptoBackend; report: SodiumBackendReport }>();
+
+export function buildSodiumBackend(sodium: SodiumLike): { backend: CryptoBackend; report: SodiumBackendReport } {
+  const cached = built.get(sodium);
+  if (cached) return cached;
+  const result = checkAndBuild(sodium);
+  built.set(sodium, result);
+  return result;
+}
+
+function checkAndBuild(sodium: SodiumLike): { backend: CryptoBackend; report: SodiumBackendReport } {
+  const stage = "sodiumBackend";
+  const native: string[] = [];
+  const portable: string[] = [];
+  const n = nobleBackend;
+  // Known inputs: deterministic, so the check is the same on every device.
+  const seed = Uint8Array.from({ length: 32 }, (_, i) => (i * 37 + 11) & 0xff);
+  const message = Uint8Array.from({ length: 70 }, (_, i) => (i * 29 + 3) & 0xff);
+  const nonce24 = Uint8Array.from({ length: 24 }, (_, i) => (i * 13 + 5) & 0xff);
+  const key32 = Uint8Array.from({ length: 32 }, (_, i) => (255 - i * 7) & 0xff);
+  const aad = Uint8Array.from([0, 1, 2, 250, 251, 252]);
+
+  /** A required function: present and agreeing with the portable implementation, or the binding is refused. */
+  const required = (name: string, check: () => boolean): void => {
+    let ok = false;
+    try {
+      ok = check();
+    } catch {
+      ok = false;
+    }
+    if (!ok) throw new KavachError("INVALID_KEY", stage, `${name} is missing or disagrees with the portable implementation; the binding cannot be used`);
+    native.push(name);
+  };
+  /** An optional function: used when present and agreeing on the protocol's input types, portable otherwise. */
+  const optional = (name: string, present: boolean, check: () => boolean): boolean => {
+    let ok = false;
+    if (present) {
+      try {
+        ok = check();
+      } catch {
+        ok = false;
+      }
+    }
+    (ok ? native : portable).push(name);
+    return ok;
+  };
+
+  const nSign = n.signKeypairFromSeed(seed);
+  required("signKeypairFromSeed", () => {
+    const kp = sodium.crypto_sign_seed_keypair(seed);
+    return same(kp.publicKey, nSign.publicKey) && same(kp.privateKey, nSign.secretKey);
+  });
+  required("signDetached", () => same(sodium.crypto_sign_detached(message, nSign.secretKey), n.signDetached(message, nSign.secretKey)));
+  required("verifyDetached", () => sodium.crypto_sign_verify_detached(n.signDetached(message, nSign.secretKey), message, nSign.publicKey) === true && sodium.crypto_sign_verify_detached(n.signDetached(message, nSign.secretKey), nonce24, nSign.publicKey) === false);
+  required("blake2b", () => same(sodium.crypto_generichash(32, message, null), n.blake2b(message, 32)) && same(sodium.crypto_generichash(64, message, key32), n.blake2b(message, 64, key32)));
+  const nBox = n.boxKeypairFromSeed(seed);
+  required("boxKeypairFromSeed", () => {
+    const kp = sodium.crypto_box_seed_keypair(seed);
+    return same(kp.publicKey, nBox.publicKey) && same(kp.privateKey, nBox.secretKey);
+  });
+  required("boxKeypair", () => {
+    // A fresh keypair cannot be compared with a known one; its public key must be the one its secret derives.
+    const kp = sodium.crypto_box_keypair();
+    return kp.publicKey.length === 32 && kp.privateKey.length === 32 && same(kp.publicKey, n.scalarMult(kp.privateKey, X25519_BASE));
+  });
+  const other = n.boxKeypairFromSeed(key32);
+  required("boxEasy", () => same(sodium.crypto_box_easy(message, nonce24, other.publicKey, nBox.secretKey), n.boxEasy(message, nonce24, other.publicKey, nBox.secretKey)));
+  required("boxOpenEasy", () => same(sodium.crypto_box_open_easy(n.boxEasy(message, nonce24, other.publicKey, nBox.secretKey), nonce24, nBox.publicKey, other.secretKey), message));
+  required("randomBytes", () => sodium.randombytes_buf(16).length === 16);
+  const scalarMultNative = optional("scalarMult", typeof sodium.crypto_scalarmult === "function", () => same(sodium.crypto_scalarmult?.(nBox.secretKey, other.publicKey) ?? new Uint8Array(), n.scalarMult(nBox.secretKey, other.publicKey)));
+  const aeadNative = optional("aead", typeof sodium.crypto_aead_xchacha20poly1305_ietf_encrypt === "function" && typeof sodium.crypto_aead_xchacha20poly1305_ietf_decrypt === "function", () => {
+    // The protocol's associated data is binary; a binding that takes only strings throws here and falls back.
+    const sealed = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt?.(message, aad, null, nonce24, key32) ?? new Uint8Array();
+    const opened = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt?.(null, n.aeadEncrypt(message, aad, nonce24, key32), aad, nonce24, key32) ?? new Uint8Array();
+    return same(sealed, n.aeadEncrypt(message, aad, nonce24, key32)) && same(opened, message);
+  });
+  const validPointNative = optional("isValidSignPoint", typeof sodium.crypto_core_ed25519_is_valid_point === "function", () => sodium.crypto_core_ed25519_is_valid_point?.(nSign.publicKey) === true && sodium.crypto_core_ed25519_is_valid_point?.(new Uint8Array(32)) === false);
+  const memzeroNative = optional("memzero", typeof sodium.memzero === "function", () => {
+    const probe = Uint8Array.from([1, 2, 3]);
+    sodium.memzero?.(probe);
+    return probe.every((b) => b === 0);
+  });
+
+  const backend: CryptoBackend = {
+    name: "sodium",
+    blake2b: (data, outLen, key) => sodium.crypto_generichash(outLen, data, key ?? null),
+    randomBytes: (length) => sodium.randombytes_buf(length),
+    signKeypairFromSeed(s): SignKeypair {
+      const kp = sodium.crypto_sign_seed_keypair(s);
+      return { publicKey: kp.publicKey, secretKey: kp.privateKey };
+    },
+    signDetached: (m, secretKey) => sodium.crypto_sign_detached(m, secretKey),
+    verifyDetached(signature, m, publicKey) {
+      try {
+        return sodium.crypto_sign_verify_detached(signature, m, publicKey);
+      } catch {
+        return false;
+      }
+    },
+    isValidSignPoint: validPointNative ? (publicKey) => publicKey.length === 32 && sodium.crypto_core_ed25519_is_valid_point?.(publicKey) === true : (publicKey) => n.isValidSignPoint(publicKey),
+    boxKeypairFromSeed(s): BoxKeypair {
+      const kp = sodium.crypto_box_seed_keypair(s);
+      return { publicKey: kp.publicKey, secretKey: kp.privateKey };
+    },
+    boxKeypair(): BoxKeypair {
+      const kp = sodium.crypto_box_keypair();
+      return { publicKey: kp.publicKey, secretKey: kp.privateKey };
+    },
+    scalarMult: scalarMultNative ? (secretKey, publicKey) => sodium.crypto_scalarmult?.(secretKey, publicKey) ?? n.scalarMult(secretKey, publicKey) : (secretKey, publicKey) => n.scalarMult(secretKey, publicKey),
+    boxEasy: (m, nonce, publicKey, secretKey) => sodium.crypto_box_easy(m, nonce, publicKey, secretKey),
+    boxOpenEasy: (box, nonce, publicKey, secretKey) => sodium.crypto_box_open_easy(box, nonce, publicKey, secretKey),
+    aeadEncrypt: aeadNative ? (plaintext, a, nonce, key) => sodium.crypto_aead_xchacha20poly1305_ietf_encrypt?.(plaintext, a, null, nonce, key) ?? n.aeadEncrypt(plaintext, a, nonce, key) : (plaintext, a, nonce, key) => n.aeadEncrypt(plaintext, a, nonce, key),
+    aeadDecrypt: aeadNative ? (c, a, nonce, key) => sodium.crypto_aead_xchacha20poly1305_ietf_decrypt?.(null, c, a, nonce, key) ?? n.aeadDecrypt(c, a, nonce, key) : (c, a, nonce, key) => n.aeadDecrypt(c, a, nonce, key),
+    memzero: memzeroNative ? (bytes) => sodium.memzero?.(bytes) : (bytes) => bytes.fill(0)
+  };
+  return { backend, report: { native, portable } };
+}

package/src/errors.ts

@@ -52,6 +52,7 @@ export type ErrorCode =
   | "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";
 
@@ -63,6 +64,7 @@ const RETRYABLE: ReadonlySet<ErrorCode> = new Set<ErrorCode>([
   "LOCKED",
   "STORAGE_FAILURE",
   "NETWORK",
+  "RATE_LIMITED",
   "SUCCESSION_PENDING"
 ]);
 
@@ -75,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

@@ -36,7 +36,8 @@ export {
   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/testing/faults.ts

@@ -113,6 +113,10 @@ export interface MaliciousKnobs {
   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" | "subscriptions">;
   /** Older documents served instead of the current ones. */
@@ -142,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() },
@@ -298,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");
@@ -308,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 };