@plane31/blind-relay 0.1.1 → 0.1.3

package/src/reset.ts

@@ -0,0 +1,176 @@
+/**
+ * Last-resort account reset and the reset keys (protocol section 12).
+ *
+ * `ResetTrust` is the acceptance model for management-signed key lists (type 8) and reset
+ * receipts (type 7): version rules, the 30-day lifetime, the trusted-clock rules with a durable
+ * time high-water mark, revocation by list, and immutable reset bindings. It is pure state with
+ * row conversions; the client persists it in T9. Nothing here pauses sharing.
+ */
+import { equalBytes, fromHex, toHex } from "./bytes.js";
+import {
+  DocumentType,
+  expectType,
+  parseDocument,
+  verifyDocument,
+  type AccountDevice,
+  type AccountResetReceipt,
+  type Parsed,
+  type ResetKeyList
+} from "./codec.js";
+import { H, identityId } from "./crypto.js";
+import { KavachError } from "./errors.js";
+import { big, unbig } from "./rows.js";
+
+export interface ResetTrustConfig {
+  /** The deployment's pinned management public key. */
+  readonly managementKey: Uint8Array;
+  /** The packaged minimum list version. */
+  readonly minimumVersion: bigint;
+}
+
+export interface ResetBinding {
+  readonly accountName: string;
+  readonly oldIdentityId: string;
+  readonly newIdentityId: string;
+}
+
+export interface ResetTrustState {
+  readonly current: { wire: Uint8Array; list: Parsed<ResetKeyList> } | undefined;
+  /** The greatest trusted time seen: a durable high-water mark. */
+  readonly timeHighWater: bigint;
+  readonly acceptedReceipts: ReadonlySet<string>;
+  readonly events: ReadonlyMap<string, ResetBinding>;
+  readonly retired: ReadonlySet<string>;
+}
+
+export const emptyResetTrust: ResetTrustState = { current: undefined, timeHighWater: 0n, acceptedReceipts: new Set(), events: new Map(), retired: new Set() };
+
+export type InstallOutcome = "INSTALLED" | "DUPLICATE";
+export type ApplyOutcome = "ACCOUNT_KEY_CHANGED" | "DUPLICATE";
+
+/** A peer's view of an accepted reset: who to stop sharing with, and whose circles close. */
+export interface ResetEffect {
+  readonly outcome: ApplyOutcome;
+  readonly oldIdentityId: Uint8Array;
+  readonly newIdentityId: Uint8Array;
+  readonly receipt: Parsed<AccountResetReceipt>;
+}
+
+export class ResetTrust {
+  constructor(
+    readonly config: ResetTrustConfig,
+    public state: ResetTrustState = emptyResetTrust
+  ) {}
+
+  /** The platform clock under the accurate-clock assumption, checked against the high-water mark. */
+  private clock(now: bigint | undefined, stage: string): bigint {
+    if (now === undefined || now < this.state.timeHighWater) throw new KavachError("RESET_CLOCK_UNTRUSTED", stage);
+    return now;
+  }
+
+  /** Is the current list usable at `now`? */
+  fresh(now: bigint): boolean {
+    const c = this.state.current;
+    return !!c && c.list.issuedAt <= now && now < c.list.expiresAt;
+  }
+
+  /**
+   * Install a key list: verified under the pinned management key, version at least the packaged
+   * minimum and the durable highest, equal version only with an equal body, fresh at `now`.
+   */
+  install(wire: Uint8Array, now: bigint | undefined): InstallOutcome {
+    const stage = "resetKeyList";
+    const list = expectType<ResetKeyList>(verifyDocument(wire, this.config.managementKey), DocumentType.ResetKeyList, stage);
+    if (list.keys.some((k) => equalBytes(k.publicKey, this.config.managementKey))) {
+      throw new KavachError("INVALID_KEY", stage, "the management key cannot be an operational key");
+    }
+    const current = this.state.current;
+    if (list.version < this.config.minimumVersion || (current && list.version < current.list.version)) throw new KavachError("ROLLBACK", stage);
+    if (current && list.version === current.list.version && !equalBytes(list.bodyHash, current.list.bodyHash)) {
+      throw new KavachError("EQUIVOCATION", stage, "two key lists at one version");
+    }
+    const t = this.clock(now, stage);
+    if (!(list.issuedAt <= t && t < list.expiresAt)) throw new KavachError("RESET_KEYS_REQUIRED", stage, "list not fresh");
+    const outcome: InstallOutcome = current && list.version === current.list.version ? "DUPLICATE" : "INSTALLED";
+    this.state = { ...this.state, current: { wire, list }, timeHighWater: t };
+    return outcome;
+  }
+
+  /**
+   * Apply a reset receipt for an account whose current pinned identity is `currentIdentityId`.
+   * Requires a fresh list, an allowed signer, a verified new certificate and consistent bindings.
+   */
+  apply(receiptWire: Uint8Array, newCertificate: Uint8Array, accountName: string, currentIdentityId: Uint8Array, now: bigint | undefined): ResetEffect {
+    const stage = "resetReceipt";
+    const parsed = expectType<AccountResetReceipt>(parseDocument(receiptWire), DocumentType.AccountResetReceipt, stage);
+    const receiptHash = toHex(H(receiptWire));
+    if (this.state.acceptedReceipts.has(receiptHash)) {
+      return { outcome: "DUPLICATE", oldIdentityId: parsed.oldIdentityId, newIdentityId: parsed.newIdentityId, receipt: parsed };
+    }
+    const t = this.clock(now, stage);
+    if (!this.fresh(t)) throw new KavachError("RESET_KEYS_REQUIRED", stage, "no fresh key list");
+    const current = this.state.current;
+    if (!current) throw new KavachError("RESET_KEYS_REQUIRED", stage);
+    const signer = current.list.keys.find((k) => equalBytes(k.keyId, parsed.authorityKeyId));
+    if (!signer) throw new KavachError("RESET_KEY_REVOKED", stage, "the signing key is not in the current list");
+    const receipt = expectType<AccountResetReceipt>(verifyDocument(receiptWire, signer.publicKey), DocumentType.AccountResetReceipt, stage);
+    const cert = expectType<AccountDevice>(verifyDocument(newCertificate), DocumentType.AccountDevice, stage);
+    const binding: ResetBinding = { accountName: receipt.accountName, oldIdentityId: toHex(receipt.oldIdentityId), newIdentityId: toHex(receipt.newIdentityId) };
+    if (receipt.accountName !== accountName || cert.accountName !== accountName || !equalBytes(identityId(accountName, cert.accountKey), receipt.newIdentityId)) {
+      throw new KavachError("RESET_BINDING", stage, "receipt, account and certificate do not bind");
+    }
+    const resetId = toHex(receipt.resetId);
+    const known = this.state.events.get(resetId);
+    let outcome: ApplyOutcome;
+    if (known) {
+      if (known.accountName !== binding.accountName || known.oldIdentityId !== binding.oldIdentityId || known.newIdentityId !== binding.newIdentityId) {
+        throw new KavachError("RESET_BINDING", stage, "a conflicting binding for a known reset id");
+      }
+      outcome = "DUPLICATE";
+    } else {
+      if (!equalBytes(receipt.oldIdentityId, currentIdentityId) || this.state.retired.has(binding.newIdentityId)) {
+        throw new KavachError("RESET_BINDING", stage, "old identity is not the current pin, or the new one is retired");
+      }
+      outcome = "ACCOUNT_KEY_CHANGED";
+    }
+    const accepted = new Set(this.state.acceptedReceipts);
+    accepted.add(receiptHash);
+    const events = new Map(this.state.events);
+    events.set(resetId, binding);
+    const retired = new Set(this.state.retired);
+    retired.add(binding.oldIdentityId);
+    this.state = { ...this.state, acceptedReceipts: accepted, events, retired, timeHighWater: t };
+    return { outcome, oldIdentityId: receipt.oldIdentityId, newIdentityId: receipt.newIdentityId, receipt };
+  }
+
+  // Persistence ----------------------------------------------------------------------------------
+
+  toRows(): ResetTrustRows {
+    return {
+      list: this.state.current ? { wire: toHex(this.state.current.wire), version: big(this.state.current.list.version), hash: toHex(this.state.current.list.bodyHash), checkedAt: big(this.state.timeHighWater) } : undefined,
+      clock: { highWater: big(this.state.timeHighWater) },
+      accepted: [...this.state.acceptedReceipts],
+      events: [...this.state.events.entries()].map(([resetId, b]) => ({ resetId, ...b })),
+      retired: [...this.state.retired]
+    };
+  }
+
+  static fromRows(config: ResetTrustConfig, rows: ResetTrustRows): ResetTrust {
+    const current = rows.list ? { wire: fromHex(rows.list.wire), list: expectType<ResetKeyList>(parseDocument(fromHex(rows.list.wire)), DocumentType.ResetKeyList) } : undefined;
+    return new ResetTrust(config, {
+      current,
+      timeHighWater: unbig(rows.clock.highWater),
+      acceptedReceipts: new Set(rows.accepted),
+      events: new Map(rows.events.map((e) => [e.resetId, { accountName: e.accountName, oldIdentityId: e.oldIdentityId, newIdentityId: e.newIdentityId }])),
+      retired: new Set(rows.retired)
+    });
+  }
+}
+
+export interface ResetTrustRows {
+  list: { wire: string; version: string; hash: string; checkedAt: string } | undefined;
+  clock: { highWater: string };
+  accepted: string[];
+  events: { resetId: string; accountName: string; oldIdentityId: string; newIdentityId: string }[];
+  retired: string[];
+}

package/src/rows.ts

@@ -0,0 +1,116 @@
+/** Conversions between domain objects and the JSON-safe rows of the store. */
+import { fromHex, toHex } from "./bytes.js";
+import type { CircleState } from "./circle.js";
+import type { AccountPin } from "./identity.js";
+import type { RevisionState } from "./audience.js";
+import type { PreparedEpoch } from "./epoch.js";
+import type { CircleRow, EpochRow, PinRow, RevisionRow } from "./store.js";
+
+export const big = (v: bigint): string => v.toString();
+export const unbig = (v: string): bigint => BigInt(v);
+
+export function pinToRow(p: AccountPin): PinRow {
+  return {
+    accountName: p.accountName,
+    accountKey: toHex(p.accountKey),
+    identityId: toHex(p.identityId),
+    generation: big(p.generation),
+    certificateHash: toHex(p.certificateHash),
+    certificate: toHex(p.certificate),
+    deviceId: toHex(p.deviceId),
+    signingKey: toHex(p.signingKey),
+    boxKey: toHex(p.boxKey),
+    streamId: toHex(p.streamId),
+    deviceIds: p.deviceIds.map(toHex)
+  };
+}
+
+export function rowToPin(r: PinRow): AccountPin {
+  return {
+    accountName: r.accountName,
+    accountKey: fromHex(r.accountKey),
+    identityId: fromHex(r.identityId),
+    generation: unbig(r.generation),
+    certificateHash: fromHex(r.certificateHash),
+    certificate: fromHex(r.certificate),
+    deviceId: fromHex(r.deviceId),
+    signingKey: fromHex(r.signingKey),
+    boxKey: fromHex(r.boxKey),
+    streamId: fromHex(r.streamId),
+    deviceIds: r.deviceIds.map(fromHex)
+  };
+}
+
+export function circleToRow(c: CircleState): CircleRow {
+  return {
+    circleId: toHex(c.circleId),
+    ownerIdentityId: toHex(c.ownerIdentityId),
+    revision: big(c.revision),
+    bodyHash: c.bodyHash ? toHex(c.bodyHash) : undefined,
+    snapshot: c.snapshot ? toHex(c.snapshot) : undefined,
+    members: c.members.map(toHex),
+    enabled: c.enabled,
+    status: c.status,
+    verifiedAt: big(c.verifiedAt)
+  };
+}
+
+export function rowToCircle(r: CircleRow): CircleState {
+  return {
+    circleId: fromHex(r.circleId),
+    ownerIdentityId: fromHex(r.ownerIdentityId),
+    revision: unbig(r.revision),
+    bodyHash: r.bodyHash ? fromHex(r.bodyHash) : undefined,
+    snapshot: r.snapshot ? fromHex(r.snapshot) : undefined,
+    members: r.members.map(fromHex),
+    enabled: r.enabled,
+    status: r.status,
+    verifiedAt: unbig(r.verifiedAt)
+  };
+}
+
+export function revisionToRow(s: RevisionState, paused: RevisionRow["paused"]): RevisionRow {
+  return {
+    desiredRevision: big(s.desiredRevision),
+    seenSnapshots: Object.fromEntries([...s.seenSnapshots].map(([k, v]) => [k, big(v)])),
+    seenCertificates: Object.fromEntries([...s.seenCertificates]),
+    paused
+  };
+}
+
+export function rowToRevision(r: RevisionRow): RevisionState {
+  return {
+    desiredRevision: unbig(r.desiredRevision),
+    seenSnapshots: new Map(Object.entries(r.seenSnapshots).map(([k, v]) => [k, unbig(v)])),
+    seenCertificates: new Map(Object.entries(r.seenCertificates))
+  };
+}
+
+export function preparedToRow(p: PreparedEpoch): EpochRow {
+  return {
+    epoch: p.epoch,
+    status: "prepared",
+    manifest: toHex(p.manifest),
+    manifestHash: toHex(p.manifestHash),
+    wraps: Object.fromEntries([...p.wraps].map(([k, v]) => [k, toHex(v)])),
+    epochKey: toHex(p.epochKey),
+    capturedRevision: big(p.capturedRevision),
+    audienceKey: p.audienceKey,
+    createdAt: big(p.createdAt),
+    nextCounter: 0,
+    lastSentAt: undefined
+  };
+}
+
+export function rowToPrepared(r: EpochRow): PreparedEpoch {
+  return {
+    epoch: r.epoch,
+    manifest: fromHex(r.manifest),
+    manifestHash: fromHex(r.manifestHash),
+    wraps: new Map(Object.entries(r.wraps).map(([k, v]) => [k, fromHex(v)])),
+    epochKey: fromHex(r.epochKey),
+    capturedRevision: unbig(r.capturedRevision),
+    audienceKey: r.audienceKey,
+    createdAt: unbig(r.createdAt)
+  };
+}

package/src/slots.ts

@@ -0,0 +1,55 @@
+/**
+ * The newest slot (protocol section 10): for every kind declared `newest`, one row per author
+ * holding the newest record from the author's current device, shared by the receiver (T7) and
+ * the sender's own row (T6). Order: a newer device generation first; within one generation the
+ * later event time, clamped to the record's `sentAt` so a clock set ahead cannot hold the slot;
+ * equal event times by (epoch, counter). The slot outlives its payload: expiry drops the payload
+ * and keeps the order, so an older record replayed later cannot become current.
+ */
+import { compareSlots } from "./record.js";
+import { big, unbig } from "./rows.js";
+import type { NewestRow, Tx } from "./store.js";
+
+export interface SlotOrder {
+  readonly generation: bigint;
+  readonly eventTime: bigint;
+  readonly epoch: number;
+  readonly counter: number;
+}
+
+export function compareSlotOrder(a: SlotOrder, b: SlotOrder): number {
+  if (a.generation !== b.generation) return a.generation < b.generation ? -1 : 1;
+  if (a.eventTime !== b.eventTime) return a.eventTime < b.eventTime ? -1 : 1;
+  return compareSlots(a, b);
+}
+
+/** The event time a slot orders by: the envelope's, never later than `sentAt`; `sentAt` when the sender gave none. */
+export function clampEventTime(eventTime: bigint | undefined, sentAt: bigint): bigint {
+  return eventTime === undefined || eventTime > sentAt ? sentAt : eventTime;
+}
+
+export function slotKey(authorIdentityId: string, kind: number): string {
+  return `${authorIdentityId}:${kind}`;
+}
+
+export function slotOrderOf(row: NewestRow): SlotOrder {
+  return { generation: unbig(row.generation), eventTime: unbig(row.eventTime), epoch: row.epoch, counter: row.counter };
+}
+
+export interface SlotCandidate extends SlotOrder {
+  readonly recordId: string;
+  readonly bodyHash: string;
+  readonly sentAt: bigint;
+  readonly receivedAt: bigint;
+  readonly payload: Uint8Array;
+}
+
+/** Take the slot if the candidate orders after its current holder (or there is none); true when it did. */
+export function takeSlot(tx: Tx, authorIdentityId: string, kind: number, c: SlotCandidate, toHex: (b: Uint8Array) => string): boolean {
+  const key = slotKey(authorIdentityId, kind);
+  const current = tx.get("newest", key);
+  if (current && compareSlotOrder(c, slotOrderOf(current)) <= 0) return false;
+  const next: NewestRow = { recordId: c.recordId, bodyHash: c.bodyHash, generation: big(c.generation), epoch: c.epoch, counter: c.counter, sentAt: big(c.sentAt), receivedAt: big(c.receivedAt), eventTime: big(c.eventTime), payload: toHex(c.payload) };
+  tx.put("newest", key, next);
+  return true;
+}