@plane31/blind-relay 0.0.0-stage → 0.1.2

package/src/testing/faults.ts

@@ -0,0 +1,321 @@
+/**
+ * The fault harness of build step 16: a store wrapper that crashes the process at a chosen
+ * transaction boundary, a transport wrapper that loses responses after the host committed,
+ * duplicates and reorders deliveries, withholds, replays, forks and tampers with documents,
+ * and a sweep that runs one scenario once per boundary and checks the durable-state outcomes
+ * of protocol section 11 after a restart. Exported under `@plane31/blind-relay/testing` only.
+ */
+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";
+
+// Crashes ------------------------------------------------------------------------------------------
+
+export type CrashPhase = "beforeCommit" | "afterCommit";
+
+export interface CrashPlan {
+  /** The 1-based index of the transaction (counted across every handle of the process) to crash at. */
+  readonly at: number;
+  /** Before commit: the transaction rolls back. After commit: it is durable but no caller sees the result. */
+  readonly phase: CrashPhase;
+}
+
+/** The process died here. Every later store call from the same process fails. */
+export class SimulatedCrash extends Error {
+  constructor(
+    readonly at: number,
+    readonly phase: CrashPhase
+  ) {
+    super(`simulated crash ${phase} transaction ${at}`);
+    this.name = "SimulatedCrash";
+  }
+}
+
+interface ProcessState {
+  transactions: number;
+  crashed: SimulatedCrash | undefined;
+  readonly plan: CrashPlan | undefined;
+}
+
+/**
+ * A store handle that belongs to one simulated process. All handles made with `fork()` share
+ * the transaction counter and die together. A read-only probe that must survive the crash reads
+ * the inner store directly.
+ */
+export class FaultyStore implements Store {
+  private readonly process: ProcessState;
+
+  constructor(
+    readonly inner: Store,
+    plan?: CrashPlan,
+    private readonly forkInner?: () => Store,
+    process?: ProcessState
+  ) {
+    this.process = process ?? { transactions: 0, crashed: undefined, plan };
+  }
+
+  get crashed(): SimulatedCrash | undefined {
+    return this.process.crashed;
+  }
+
+  get transactions(): number {
+    return this.process.transactions;
+  }
+
+  async transaction<R>(fn: (tx: Tx) => R): Promise<R> {
+    this.alive();
+    const n = ++this.process.transactions;
+    const plan = this.process.plan;
+    const result = await this.inner.transaction((tx) => {
+      const r = invokeSync(fn, tx);
+      if (plan && plan.phase === "beforeCommit" && plan.at === n) throw this.die(n, "beforeCommit");
+      return r;
+    });
+    if (plan && plan.phase === "afterCommit" && plan.at === n) throw this.die(n, "afterCommit");
+    return result;
+  }
+
+  async read<R>(fn: (tx: Omit<Tx, "put" | "delete" | "handoff">) => R): Promise<R> {
+    this.alive();
+    return this.inner.read(fn);
+  }
+
+  /** Another execution context of the same process. */
+  fork(): FaultyStore {
+    if (!this.forkInner) throw new Error("this store cannot fork");
+    return new FaultyStore(this.forkInner(), undefined, this.forkInner, this.process);
+  }
+
+  private die(at: number, phase: CrashPhase): SimulatedCrash {
+    this.process.crashed = new SimulatedCrash(at, phase);
+    return this.process.crashed;
+  }
+
+  private alive(): void {
+    if (this.process.crashed) throw new KavachError("STORAGE_FAILURE", "faultyStore", "the process has crashed");
+  }
+}
+
+// The malicious transport ----------------------------------------------------------------------------
+
+export type MutationName = "registerAccount" | "activateDevice" | "publishVault" | "publishOwnedCircle" | "requestJoin" | "requestLeave" | "resetAccount" | "publishEpoch" | "appendRecord" | "ackThrough";
+
+export type ServedKind = "certificate" | "snapshot" | "vault" | "manifest" | "wrap" | "record" | "keyList" | "receipt";
+
+export interface MaliciousKnobs {
+  /** Mutations whose next response is lost after the host committed it (each name is consumed once). */
+  readonly loseResponseOf: Set<MutationName>;
+  /** Mutations whose next call fails before reaching the host (each name is consumed once). */
+  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>>;
+  /** Reads that answer "nothing" while present. */
+  readonly withhold: Set<"snapshots" | "epochs" | "records" | "requests" | "currentEpoch" | "keyList" | "certificates">;
+  /** Older documents served instead of the current ones. */
+  readonly replay: {
+    vault?: Uint8Array;
+    snapshots: Map<string, Uint8Array>;
+    keyList?: Uint8Array;
+    currentEpoch?: { epoch: number; manifestHash: Uint8Array };
+  };
+  /** Served documents to substitute: forks of the host's log. Keys are hex (circle id, stream id, record id). */
+  readonly fork: {
+    snapshots: Map<string, Uint8Array>;
+    manifests: Map<string, Uint8Array>;
+    records: Map<string, Uint8Array>;
+    certificates: Map<string, Uint8Array>;
+  };
+  /** Every record page is served twice over, and each record appears twice inside a page. */
+  duplicate: boolean;
+  /** Records inside a page are served newest first. */
+  reorder: boolean;
+  /** Flip a byte in every served document of these kinds. */
+  readonly tamper: Set<ServedKind>;
+}
+
+export function emptyKnobs(): MaliciousKnobs {
+  return {
+    loseResponseOf: new Set(),
+    refuse: new Set(),
+    hold: new Map(),
+    withhold: new Set(),
+    replay: { snapshots: new Map() },
+    fork: { snapshots: new Map(), manifests: new Map(), records: new Map(), certificates: new Map() },
+    duplicate: false,
+    reorder: false,
+    tamper: new Set()
+  };
+}
+
+function flipByte(bytes: Uint8Array): Uint8Array {
+  const out = Uint8Array.from(bytes);
+  const i = out.length - 1; // inside the signature for every signed type; inside the tag for a wrap
+  out[i] = (out[i] ?? 0) ^ 0x01;
+  return out;
+}
+
+/**
+ * Wraps a transport. Everything not switched on passes through unchanged, so a scenario can be
+ * driven to a point and then attacked. `calls` records every method name in order.
+ */
+export class MaliciousTransport implements Transport {
+  readonly knobs: MaliciousKnobs = emptyKnobs();
+  readonly calls: string[] = [];
+  /** The mutations whose response this transport has lost so far. */
+  readonly losses: MutationName[] = [];
+  readonly directory: Directory;
+  readonly relay: Relay;
+
+  constructor(private readonly inner: Transport) {
+    this.directory = this.wrapDirectory();
+    this.relay = this.wrapRelay();
+  }
+
+  private serve(kind: ServedKind, bytes: Uint8Array | undefined): Uint8Array | undefined {
+    if (!bytes) return bytes;
+    return this.knobs.tamper.has(kind) ? flipByte(bytes) : bytes;
+  }
+
+  private async mutate<O extends MutationOutcome | AppendOutcome | { status: string }>(name: MutationName, call: () => Promise<O>): Promise<O> {
+    this.calls.push(name);
+    if (this.knobs.refuse.has(name)) {
+      this.knobs.refuse.delete(name);
+      throw new KavachError("NETWORK", "transport", "network unreachable");
+    }
+    const result = await call();
+    const gate = this.knobs.hold.get(name);
+    if (gate) {
+      this.knobs.hold.delete(name);
+      await gate;
+    }
+    if (this.knobs.loseResponseOf.has(name)) {
+      this.knobs.loseResponseOf.delete(name);
+      this.losses.push(name);
+      throw new KavachError("NETWORK", "transport", "response lost");
+    }
+    return result;
+  }
+
+  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.
+    const d = (): Directory => this.inner.directory;
+    const k = this.knobs;
+    return {
+      resolveAccounts: async (names) => {
+        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 }));
+      },
+      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 }));
+      },
+      getCertificate: async (hash) => {
+        this.calls.push("getCertificate");
+        return this.serve("certificate", await d().getCertificate(hash));
+      },
+      activateDevice: (input) => this.mutate("activateDevice", () => d().activateDevice(input)),
+      registerAccount: (input) => this.mutate("registerAccount", () => d().registerAccount(input)),
+      getVault: async (name) => {
+        this.calls.push("getVault");
+        return this.serve("vault", k.replay.vault ?? (await d().getVault(name)));
+      },
+      publishVault: (input) => this.mutate("publishVault", () => d().publishVault(input)),
+      getCircle: async (circleId) => {
+        this.calls.push("getCircle");
+        if (k.withhold.has("snapshots")) return undefined;
+        const key = toHex(circleId);
+        return this.serve("snapshot", k.fork.snapshots.get(key) ?? k.replay.snapshots.get(key) ?? (await d().getCircle(circleId)));
+      },
+      publishOwnedCircle: (input) => this.mutate("publishOwnedCircle", () => d().publishOwnedCircle(input)),
+      requestJoin: (circleId) => this.mutate("requestJoin", () => d().requestJoin(circleId)),
+      requestLeave: (circleId) => this.mutate("requestLeave", () => d().requestLeave(circleId)),
+      readRequests: async (circleId) => {
+        this.calls.push("readRequests");
+        return k.withhold.has("requests") ? [] : d().readRequests(circleId);
+      },
+      getResetKeyList: async () => {
+        this.calls.push("getResetKeyList");
+        if (k.withhold.has("keyList")) return undefined;
+        return this.serve("keyList", k.replay.keyList ?? (await d().getResetKeyList()));
+      },
+      getResetReceipt: async (id) => {
+        this.calls.push("getResetReceipt");
+        return this.serve("receipt", await d().getResetReceipt(id));
+      },
+      resetAccount: (input) => this.mutate("resetAccount", () => d().resetAccount(input))
+    };
+  }
+
+  private wrapRelay(): Relay {
+    const r = (): Relay => this.inner.relay;
+    const k = this.knobs;
+    const pagesServed = new Map<string, number>();
+    return {
+      getCurrentEpoch: async (streamId) => {
+        this.calls.push("getCurrentEpoch");
+        if (k.withhold.has("currentEpoch")) return undefined;
+        return k.replay.currentEpoch ?? r().getCurrentEpoch(streamId);
+      },
+      getEpoch: async (streamId, epoch): Promise<EpochBundle | undefined> => {
+        this.calls.push("getEpoch");
+        if (k.withhold.has("epochs")) return undefined;
+        const b = await r().getEpoch(streamId, epoch);
+        if (!b) return b;
+        const manifest = k.fork.manifests.get(`${toHex(streamId)}:${epoch}`) ?? this.serve("manifest", b.manifest) ?? b.manifest;
+        return { manifest, wrap: this.serve("wrap", b.wrap) };
+      },
+      publishEpoch: (input) => this.mutate("publishEpoch", () => r().publishEpoch(input)),
+      appendRecord: (recordId, wire) => {
+        // Must stay synchronous up to the inner call (T6h).
+        this.calls.push("appendRecord");
+        const p = r().appendRecord(recordId, wire);
+        if (!k.loseResponseOf.has("appendRecord")) return p;
+        k.loseResponseOf.delete("appendRecord");
+        this.losses.push("appendRecord");
+        return p.then(() => {
+          throw new KavachError("NETWORK", "transport", "response lost");
+        });
+      },
+      readRecords: async (streamId, afterSeq, limit): Promise<ReadRecordsResult> => {
+        this.calls.push("readRecords");
+        if (k.withhold.has("records")) {
+          const probe = await r().readRecords(streamId, afterSeq, limit);
+          return { ...probe, records: [], nextSeq: afterSeq };
+        }
+        const page = await r().readRecords(streamId, afterSeq, limit);
+        let records = page.records.map((x) => {
+          const forked = k.fork.records.get(`${toHex(streamId)}:${x.deliverySeq}`);
+          return { deliverySeq: x.deliverySeq, wire: forked ?? this.serve("record", x.wire) ?? x.wire };
+        });
+        if (k.reorder) records = [...records].reverse();
+        if (k.duplicate) {
+          records = records.flatMap((x) => [x, x]);
+          const key = `${toHex(streamId)}:${afterSeq}`;
+          const n = (pagesServed.get(key) ?? 0) + 1;
+          pagesServed.set(key, n);
+          // The first time a page is asked for, claim no progress so the reader asks again.
+          if (n === 1 && records.length > 0) return { ...page, records, nextSeq: afterSeq };
+        }
+        return { ...page, records };
+      },
+      ackThrough: (streamId, cursor) => this.mutate("ackThrough", () => r().ackThrough(streamId, cursor)),
+      listSubscriptions: async () => {
+        this.calls.push("listSubscriptions");
+        return r().listSubscriptions();
+      }
+    };
+  }
+}
+
+// Helpers shared by the sweeps ----------------------------------------------------------------------
+
+/** Whether two byte strings are equal, for assertions on exact-bytes outcomes. */
+export function sameBytes(a: Uint8Array | undefined, b: Uint8Array | undefined): boolean {
+  return a !== undefined && b !== undefined && equalBytes(a, b);
+}

package/src/testing/fixtures.ts

@@ -0,0 +1,35 @@
+/**
+ * Protocol state a test builds by hand where an application would let the client build it:
+ * accounts, devices and certificates for store tests, and a signed reset key list for a fake
+ * or real host. Call `ready()` first.
+ */
+import { buildResetKeyList } from "../codec.js";
+import { C, H, signingKeypairFromSeed, type SigningKeypair } from "../crypto.js";
+
+export { accountKeypair, identityId } from "../crypto.js";
+export { certify, deviceFromSeed, newDevice, openAccount, type DeviceKeys, type OwnAccount } from "../identity.js";
+
+export interface TestResetKeys {
+  /** The deployment's management keypair, derived from a fixed seed. */
+  readonly management: SigningKeypair;
+  /** The operational keypair that signs reset receipts, derived from a fixed seed. */
+  readonly operational: SigningKeypair;
+  readonly operationalKeyId: Uint8Array;
+}
+
+/** Deterministic management and operational keys: management seed H(C("identity")), operational seed H(C("stream")), key id 07x16. */
+export function testResetKeys(): TestResetKeys {
+  return {
+    management: signingKeypairFromSeed(H(C("identity"))),
+    operational: signingKeypairFromSeed(H(C("stream"))),
+    operationalKeyId: new Uint8Array(16).fill(7)
+  };
+}
+
+/** A key list of version 1, issued at `now` and valid for thirty days, signed by the management key. */
+export function testResetKeyList(keys: TestResetKeys, now: bigint): Uint8Array {
+  return buildResetKeyList(
+    { version: 1n, issuedAt: now, expiresAt: now + 2_592_000_000n, keys: [{ keyId: keys.operationalKeyId, publicKey: keys.operational.publicKey }] },
+    keys.management.secretKey
+  );
+}

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+export { FakeHost, type Notification } from "./fakeHost.js";
+export { testPolicy, TestClock } from "./clock.js";
+export { FaultyStore, MaliciousTransport, SimulatedCrash, emptyKnobs, sameBytes, type CrashPhase, type CrashPlan, type MaliciousKnobs, type MutationName, type ServedKind } from "./faults.js";
+export { MemoryPlatformProvider } from "./providers.js";
+export { countBoundaries, crashSweep, hostTransport, lostResponseSweep, type DeviceName, type LostResponseRun, type SweepOptions, type SweepResult, type SweepRun, type SweepStores } from "./sweep.js";
+export { accountKeypair, certify, deviceFromSeed, identityId, newDevice, openAccount, testResetKeyList, testResetKeys, type DeviceKeys, type OwnAccount, type TestResetKeys } from "./fixtures.js";

package/src/testing/providers.ts

@@ -0,0 +1,39 @@
+import { toHex } from "../bytes.js";
+import type { ProviderLoadResult, ProviderSaveResult, ProviderStatus, ProviderStatusResult, RecoveryProvider } from "../vault.js";
+
+/** A platform recovery provider shared by every device signed into one platform account. */
+export class MemoryPlatformProvider implements RecoveryProvider {
+  status_: ProviderStatus = "available";
+  items: Map<string, Uint8Array> = new Map();
+
+  constructor(private readonly platformAccount: string) {}
+
+  private key(accountName: string, identityId: Uint8Array): string {
+    return `${this.platformAccount}:${accountName}:${toHex(identityId)}`;
+  }
+
+  async load(accountName: string, identityId: Uint8Array): Promise<ProviderLoadResult> {
+    if (this.status_ !== "available") return { status: this.status_ };
+    const k = this.items.get(this.key(accountName, identityId));
+    return k ? { status: "available", recoveryKey: k } : { status: "unavailable", reason: "no item" };
+  }
+
+  async save(accountName: string, identityId: Uint8Array, recoveryKey: Uint8Array): Promise<ProviderSaveResult> {
+    if (this.status_ !== "available") return { status: this.status_, backupState: "unavailable" };
+    this.items.set(this.key(accountName, identityId), recoveryKey);
+    return { status: "available", backupState: "pending" };
+  }
+
+  async status(): Promise<ProviderStatusResult> {
+    return { status: this.status_, backupState: this.status_ === "available" ? "pending" : "unavailable" };
+  }
+
+  async eraseLocalAccess(): Promise<void> {}
+
+  /** Another phone on the same platform account sees the same items. */
+  twin(): MemoryPlatformProvider {
+    const p = new MemoryPlatformProvider(this.platformAccount);
+    p.items = this.items;
+    return p;
+  }
+}