@plane31/blind-relay 0.0.0-stage → 0.1.2

package/src/outbox.ts

@@ -0,0 +1,385 @@
+/**
+ * The outbox and the sender (protocol section 10, publishing; transactions T6 and T6h).
+ */
+import { fromHex, toHex } from "./bytes.js";
+import { rotationReason, MAX_COUNTER } from "./epoch.js";
+import { bodyHash } from "./crypto.js";
+import { KavachError } from "./errors.js";
+import { indexHistory } from "./historyIndex.js";
+import { kindOf, type RetentionPolicy } from "./policy.js";
+import { clampEventTime, takeSlot } from "./slots.js";
+import { sealRecord } from "./record.js";
+import { big, unbig } from "./rows.js";
+import type { HistoryRow, OutboxRow, Store, Tx } from "./store.js";
+import { META, REVISION, STREAM, currentRevision, t3ApplyChange } from "./transactions.js";
+import type { AppendOutcome, Relay } from "./transport.js";
+import { recordWireBytes, type RecordKind } from "./codec.js";
+
+export interface OutboxEvents {
+  queued?(recordId: Uint8Array, kind: RecordKind): void;
+  accepted?(recordId: Uint8Array): void;
+  cancelled?(recordId: Uint8Array, reason: string): void;
+  /** A record of a kind with a newest slot was cancelled or is in doubt: the app may resend its current state of that kind. */
+  refresh?(reason: string): void;
+  securityError?(code: string, detail: string): void;
+}
+
+export interface OutboxDeps {
+  readonly store: Store;
+  readonly relay: Relay;
+  readonly policy: RetentionPolicy;
+  readonly now: () => bigint;
+  readonly author: () => { streamId: Uint8Array; signingSecretKey: Uint8Array; generation: bigint; identityId: Uint8Array };
+  readonly events?: OutboxEvents;
+}
+
+function requireReady(tx: Pick<Tx, "get">): void {
+  const meta = tx.get("meta", META);
+  if (!meta) throw new KavachError("RECOVERY_REQUIRED", "enqueue", "no header");
+  if (meta.state === "RETIRED") throw new KavachError("SUPERSEDED_DEVICE", "enqueue", "this device is retired");
+  if (meta.state !== "ACTIVE") throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", "enqueue", `store is ${meta.state}`);
+}
+
+export interface EnqueueOptions {
+  /**
+   * A caller-chosen key for this hand-over, derived from the sample itself (its fix time and
+   * source, say). The guarantee: a keyed enqueue that returns has committed its record and the
+   * key in one transaction; a second enqueue under the same key, from a retry after a crash or
+   * from another runtime on the same store, returns that record with `duplicate: true` and seals
+   * nothing, concurrent calls included, since the store's writer lock orders them; a refused
+   * enqueue stores no key, so its retry is checked again. The key is kept for the delivery
+   * window and covers the hand-over, not delivery: the record it names can still be cancelled by
+   * a rotation, which the `cancelled` event reports as for any record. Up to 128 characters.
+   */
+  readonly idempotencyKey?: string;
+  /**
+   * The event time of what the record describes (a fix time, say), carried in the encrypted
+   * envelope. A reader orders the kind's newest slot by it, clamped to the send time. Absent for a
+   * kind with no natural event time; the slot then orders by send time. Zero means absent: the
+   * envelope has no other way to say "none", and the sender's own slot follows the same reading.
+   */
+  readonly eventTime?: bigint;
+}
+
+export interface Enqueued {
+  recordId: Uint8Array;
+  counter: number;
+  epoch: number;
+  /** True when the idempotency key matched an earlier enqueue and this call made no record. */
+  duplicate: boolean;
+  /** True when this record took the sender's own newest slot for its kind. */
+  own: boolean;
+}
+
+export const MAX_IDEMPOTENCY_KEY = 128;
+
+/**
+ * T6: require a usable active epoch under the current desired revision, enforce the queue limits,
+ * seal once, write the outbox row and the own history row, and advance the counter. The record
+ * id is returned only after commit. A kind declared latestWins cancels a queued record of the same
+ * kind when a newer one is enqueued, never a sent one; a slot-only kind writes no history row. An
+ * idempotency key is answered before any check: its record is already durable, whatever has
+ * happened to the queue since.
+ */
+export async function enqueue(deps: OutboxDeps, kind: RecordKind, payload: Uint8Array, options: EnqueueOptions = {}): Promise<Enqueued> {
+  const stage = "enqueue";
+  const declared = kindOf(deps.policy, kind);
+  if (!declared) throw new KavachError("MALFORMED", stage, `kind ${kind} is not declared in the retention policy`);
+  const key = options.idempotencyKey;
+  if (key !== undefined && (key.length === 0 || key.length > MAX_IDEMPOTENCY_KEY)) throw new KavachError("MALFORMED", stage, "idempotency key must be 1 to 128 characters");
+  // One reading of the event time for the envelope, the own slot and the history row: zero is none.
+  const eventTime = options.eventTime === undefined || options.eventTime === 0n ? undefined : options.eventTime;
+  if (eventTime !== undefined && eventTime < 0n) throw new KavachError("MALFORMED", stage, "event time before the epoch");
+  const superseded: Uint8Array[] = [];
+  const result = await deps.store.transaction((tx) => {
+    requireReady(tx);
+    if (key !== undefined) {
+      const seen = tx.get("enqueueKeys", key);
+      if (seen) return { recordId: fromHex(seen.recordId), counter: seen.counter, epoch: seen.epoch, duplicate: true, own: false } as const;
+    }
+    const revision = tx.get("revision", REVISION);
+    if (revision?.paused === "metadata") throw new KavachError("METADATA_REQUIRED", stage);
+    if (revision?.paused === "limit") throw new KavachError("RECIPIENT_LIMIT", stage);
+    const stream = tx.get("stream", STREAM);
+    if (!stream || stream.activeEpoch === undefined || revision?.paused === "rotation") throw new KavachError("ROTATION_REQUIRED", stage, "no active epoch");
+    const epoch = tx.get("epochs", String(stream.activeEpoch));
+    if (!epoch || epoch.status !== "active") throw new KavachError("ROTATION_REQUIRED", stage, "epoch not active");
+    const now = deps.now();
+    const reason = rotationReason({ createdAt: unbig(epoch.createdAt), nextCounter: epoch.nextCounter, lastSentAt: epoch.lastSentAt === undefined ? undefined : unbig(epoch.lastSentAt) }, now, deps.policy.hygieneRotationMs);
+    if (reason) {
+      // Commit the invalidation (T3) and report the rotation after the transaction, so the
+      // burned counters and cancelled rows are durable even though nothing was enqueued.
+      t3ApplyChange(tx, { kind: reason });
+      return { rotate: reason } as const;
+    }
+    let count = 0;
+    let bytes = 0;
+    for (const [key, row] of tx.list("outbox")) {
+      if (declared.queue === "latestWins" && row.kind === kind && row.status === "queued") {
+        tx.put("outbox", key, terminal(row, "cancelled", "superseded"));
+        superseded.push(fromHex(row.recordId));
+        continue;
+      }
+      if (row.status === "queued" || row.status === "inflight") {
+        count++;
+        bytes += row.wire.length / 2;
+      }
+    }
+    if (count >= deps.policy.maxOutboxRecords || bytes + recordWireBytes(payload.length) > deps.policy.maxOutboxBytes) throw new KavachError("QUEUE_FULL", stage);
+    const a = deps.author();
+    const sealed = sealRecord({
+      streamId: a.streamId,
+      epoch: epoch.epoch,
+      nextCounter: epoch.nextCounter,
+      kind,
+      eventTime,
+      headerClass: declared.headerClass,
+      payload,
+      sentAt: now,
+      epochKey: fromHex(epoch.epochKey),
+      signingSecretKey: a.signingSecretKey
+    });
+    const id = toHex(sealed.recordId);
+    tx.put("outbox", id, {
+      recordId: id,
+      wire: toHex(sealed.wire),
+      epoch: epoch.epoch,
+      counter: sealed.counter,
+      kind,
+      sentAt: big(now),
+      desiredRevision: big(currentRevision(tx)),
+      status: "queued",
+      attempts: 0,
+      reason: undefined
+    });
+    if (key !== undefined) tx.put("enqueueKeys", key, { recordId: id, epoch: epoch.epoch, counter: sealed.counter, sentAt: big(now) });
+    // The sender's own row, under the rules a reader applies (section 10): history when the kind
+    // keeps it, and the own newest slot when the kind has one, so `newest` answers for self.
+    const self = toHex(a.identityId);
+    const hash = toHex(bodyHash(sealed.wire.subarray(0, sealed.wire.length - 64)));
+    const own = declared.newest ? takeSlot(tx, self, kind, { generation: a.generation, eventTime: clampEventTime(eventTime, now), epoch: epoch.epoch, counter: sealed.counter, recordId: id, bodyHash: hash, sentAt: now, receivedAt: now, payload }, toHex) : false;
+    if (declared.history) {
+      const ownRow: HistoryRow = {
+        recordId: id,
+        authorIdentityId: toHex(a.identityId),
+        streamId: toHex(a.streamId),
+        generation: big(a.generation),
+        epoch: epoch.epoch,
+        counter: sealed.counter,
+        kind,
+        sentAt: big(now),
+        receivedAt: big(now),
+        plaintext: toHex(payload),
+        superseded: false,
+        own: true,
+        ...(eventTime === undefined ? {} : { eventTime: big(eventTime) })
+      };
+      tx.put("history", id, ownRow);
+      indexHistory(tx, ownRow);
+    }
+    const nextCounter = epoch.nextCounter + 1;
+    tx.put("epochs", String(epoch.epoch), { ...epoch, nextCounter, lastSentAt: big(now) });
+    if (nextCounter > MAX_COUNTER) {
+      // The final counter was just used: the next enqueue rotates.
+    }
+    return { recordId: sealed.recordId, counter: sealed.counter, epoch: epoch.epoch, duplicate: false, own } as const;
+  });
+  if ("rotate" in result) {
+    throw new KavachError(result.rotate === "counterExhausted" ? "COUNTER_EXHAUSTED" : "ROTATION_REQUIRED", stage, result.rotate);
+  }
+  if (result.duplicate) return result;
+  for (const id of superseded) deps.events?.cancelled?.(id, "superseded");
+  deps.events?.queued?.(result.recordId, kind);
+  return result;
+}
+
+export interface DrainSummary {
+  sent: number;
+  accepted: number;
+  cancelled: number;
+  unknown: number;
+  retry: number;
+}
+
+/** "none": nothing to send, the drain ends. "skipped": a row was cancelled, the next one is tried. */
+type HandoffStep = { kind: "none" } | { kind: "skipped" } | { kind: "sent"; key: string; row: OutboxRow; outcome: Promise<AppendOutcome> };
+
+/**
+ * The single serialised sender: one record in flight per stream, drained in (epoch, counter)
+ * order. Each handoff is T6h: re-check eligibility, mark in flight, start the send inside the
+ * transaction, commit; the response is awaited outside and recorded in a new transaction that
+ * 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 };
+  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++;
+    let outcome: AppendOutcome | undefined;
+    try {
+      outcome = await step.outcome;
+    } catch {
+      outcome = undefined; // lost response
+    }
+    const final = await recordOutcome(deps, step.key, outcome);
+    if (final === "accepted") summary.accepted++;
+    else if (final === "cancelled") summary.cancelled++;
+    else if (final === "unknown") summary.unknown++;
+    else {
+      summary.retry++;
+      break; // a retryable failure ends this drain; the next sync re-enters T6h
+    }
+  }
+  return summary;
+}
+
+/** Dead rows cancelled per handoff transaction; a larger backlog is finished over the next handoffs. */
+const CANCEL_BATCH = 500;
+
+/** A row that will not be sent again keeps its summary and sheds the ciphertext. */
+function terminal(row: OutboxRow, status: "cancelled" | "unknown", reason: string): OutboxRow {
+  return { ...row, wire: "", status, reason };
+}
+
+async function handoffNext(deps: OutboxDeps, summary: DrainSummary): Promise<HandoffStep> {
+  // Application events fire after the commit, never from inside it: a subscriber cannot roll a
+  // transition back, and never sees state the store has not kept yet.
+  const after: (() => void)[] = [];
+  const step = await deps.store.transaction((tx): HandoffStep => {
+    const meta = tx.get("meta", META);
+    if (!meta || meta.state !== "ACTIVE") return { kind: "none" };
+    const now = deps.now();
+    const revision = currentRevision(tx);
+    // One pass: every row that is no longer sendable (its revision moved on, or its window has
+    // passed) is cancelled here, in bounded batches, and the first sendable row goes out in the
+    // same transaction. A backlog of dead rows costs one scan, not one transaction per row.
+    const live: [string, OutboxRow][] = [];
+    let cancelled = 0;
+    let refresh = false;
+    for (const [key, row] of [...tx.list("outbox")].sort(([, a], [, b]) => a.epoch - b.epoch || a.counter - b.counter)) {
+      if (row.status !== "queued" && row.status !== "inflight") continue;
+      const reason = cancelled >= CANCEL_BATCH ? undefined : unbig(row.desiredRevision) !== revision ? "rotation" : unbig(row.sentAt) + deps.policy.deliveryWindowMs <= now ? "expired" : undefined;
+      if (!reason) {
+        live.push([key, row]);
+        continue;
+      }
+      tx.put("outbox", key, terminal(row, "cancelled", reason));
+      cancelled++;
+      after.push(() => deps.events?.cancelled?.(fromHex(row.recordId), reason));
+      if (reason === "rotation" && kindOf(deps.policy, row.kind)?.newest) refresh = true;
+    }
+    summary.cancelled += cancelled;
+    if (refresh) after.push(() => deps.events?.refresh?.("rotation"));
+    // A full batch means unchecked rows remain: finish them in the next handoff before sending.
+    if (cancelled >= CANCEL_BATCH) return { kind: "skipped" };
+    const next = live.find(([, r]) => r.status === "inflight") ?? live[0];
+    if (!next) return { kind: "none" };
+    const [key, row] = next;
+    const marked: OutboxRow = { ...row, status: "inflight", attempts: row.attempts + 1 };
+    tx.put("outbox", key, marked);
+    let outcome: Promise<AppendOutcome>;
+    try {
+      outcome = tx.handoff(() => deps.relay.appendRecord(fromHex(row.recordId), fromHex(row.wire)));
+    } catch {
+      // A synchronous transport failure: roll the in-flight mark back and stop this drain.
+      tx.put("outbox", key, { ...row, attempts: row.attempts + 1 });
+      summary.retry++;
+      return { kind: "none" };
+    }
+    return { kind: "sent", key, row: marked, outcome };
+  });
+  for (const fire of after) fire();
+  return step;
+}
+
+type Final = "accepted" | "cancelled" | "unknown" | "retry";
+
+export async function recordOutcome(deps: OutboxDeps, key: string, outcome: AppendOutcome | undefined): Promise<Final> {
+  const after: (() => void)[] = [];
+  const final = await deps.store.transaction((tx): Final => {
+    const row = tx.get("outbox", key);
+    if (!row || row.status !== "inflight") return "retry";
+    const id = fromHex(row.recordId);
+    const requeue = (): void => tx.put("outbox", key, { ...row, status: "queued", reason: undefined });
+    const cancel = (reason: string): void => tx.put("outbox", key, terminal(row, "cancelled", reason));
+    if (!outcome) {
+      requeue(); // lost response: retry the identical bytes; the relay answers from its checkpoint
+      return "retry";
+    }
+    switch (outcome.status) {
+      case "ACCEPTED":
+      case "ALREADY_ACCEPTED":
+        tx.delete("outbox", key);
+        after.push(() => deps.events?.accepted?.(id));
+        return "accepted";
+      case "RETRYABLE":
+        requeue();
+        return "retry";
+      case "STALE_APPEND":
+        tx.put("outbox", key, terminal(row, "unknown", "STALE_APPEND"));
+        after.push(() => deps.events?.cancelled?.(id, "acceptanceUnknown"));
+        if (kindOf(deps.policy, row.kind)?.newest) after.push(() => deps.events?.refresh?.("acceptanceUnknown"));
+        return "unknown";
+      case "EQUIVOCATION":
+        cancel("EQUIVOCATION");
+        after.push(() => deps.events?.securityError?.("EQUIVOCATION", "the relay holds a different record under this id"));
+        return "cancelled";
+      case "EPOCH_FENCED":
+      case "SUPERSEDED_DEVICE":
+      case "UNAUTHORIZED":
+        cancel(outcome.status);
+        after.push(() => deps.events?.cancelled?.(id, outcome.status));
+        if (kindOf(deps.policy, row.kind)?.newest) after.push(() => deps.events?.refresh?.(outcome.status));
+        return "cancelled";
+    }
+  });
+  for (const fire of after) fire();
+  return final;
+}
+
+/** Retention for rows that will not be sent again: they go once the delivery window has passed. */
+export async function purgeOutbox(store: Store, policy: RetentionPolicy, now: bigint): Promise<number> {
+  return store.transaction((tx) => {
+    let purged = 0;
+    for (const [key, row] of tx.list("outbox")) {
+      if ((row.status === "cancelled" || row.status === "unknown") && unbig(row.sentAt) + policy.deliveryWindowMs <= now) {
+        tx.delete("outbox", key);
+        purged++;
+      }
+    }
+    // Idempotency keys outlive the delivery window by nothing: a replay later is a new record.
+    for (const [key, row] of tx.list("enqueueKeys")) if (unbig(row.sentAt) + policy.deliveryWindowMs <= now) tx.delete("enqueueKeys", key);
+    return purged;
+  });
+}
+
+export interface OutboxCounts {
+  readonly queued: number;
+  readonly inflight: number;
+  readonly cancelled: number;
+  readonly unknown: number;
+  /** Age of the oldest row still to send, when there is one. */
+  readonly oldestPendingAgeMs: bigint | undefined;
+}
+
+/** Rows by state, for diagnostics. */
+export function outboxCounts(tx: Pick<Tx, "list">, now: bigint): OutboxCounts {
+  const counts = { queued: 0, inflight: 0, cancelled: 0, unknown: 0 };
+  let oldest: bigint | undefined;
+  for (const [, r] of tx.list("outbox")) {
+    if (r.status === "accepted") continue;
+    counts[r.status]++;
+    if (r.status === "queued" || r.status === "inflight") {
+      const sentAt = unbig(r.sentAt);
+      if (oldest === undefined || sentAt < oldest) oldest = sentAt;
+    }
+  }
+  return { ...counts, oldestPendingAgeMs: oldest === undefined ? undefined : now - oldest };
+}
+
+/** Rows still waiting, for state reporting. */
+export async function outboxCount(store: Store): Promise<number> {
+  return store.read((tx) => tx.list("outbox").filter(([, r]) => r.status === "queued" || r.status === "inflight").length);
+}

package/src/policy.ts

@@ -0,0 +1,88 @@
+/**
+ * The versioned retention policy a profile passes to `open()` (protocol section 13): the global
+ * windows, and one declaration per record kind the product uses. The SDK treats a kind as an
+ * opaque small integer whose behaviour is what the declaration says. No defaults.
+ */
+import { KavachError } from "./errors.js";
+
+/** How the SDK treats one record kind; what the kind means is the product's. */
+export interface KindDeclaration {
+  /** The kind number carried by the record. Until revision 8 the wire carries 0, 1 or 2. */
+  readonly kind: number;
+  /** How long a reader keeps records and the newest slot's payload, from `sentAt`. */
+  readonly retentionMs: bigint;
+  /** `keepAll`: every queued record is sent. `latestWins`: a newer queued record of this kind cancels the older one (`superseded`). */
+  readonly queue: "keepAll" | "latestWins";
+  /** Whether records are kept in indexed, pageable history. */
+  readonly history: boolean;
+  /** Whether one newest-per-author slot is kept, from the author's current device, ordered by event time. */
+  readonly newest: boolean;
+  /** The two header bits the relay may see for this kind (0 to 3, 0 when absent), for routing and notifications without content. */
+  readonly headerClass: 0 | 1 | 2 | 3;
+}
+
+export interface RetentionPolicy {
+  readonly version: number;
+  readonly deliveryWindowMs: bigint;
+  readonly appendRetryWindowMs: bigint;
+  readonly hygieneRotationMs: bigint;
+  readonly maxOutboxRecords: number;
+  readonly maxOutboxBytes: number;
+  readonly kinds: readonly KindDeclaration[];
+}
+
+/** The largest kind the envelope carries. */
+export const MAX_WIRE_KIND = 255;
+
+const FIELDS: readonly (keyof RetentionPolicy)[] = ["version", "deliveryWindowMs", "appendRetryWindowMs", "hygieneRotationMs", "maxOutboxRecords", "maxOutboxBytes", "kinds"];
+
+/** A missing or malformed policy is rejected; the SDK never substitutes defaults. */
+export function validatePolicy(policy: unknown): RetentionPolicy {
+  const stage = "policy";
+  if (typeof policy !== "object" || policy === null) throw new KavachError("MALFORMED", stage, "retention policy missing");
+  const p = policy as Record<string, unknown>;
+  for (const f of FIELDS) if (!(f in p)) throw new KavachError("MALFORMED", stage, `retention policy lacks ${f}`);
+  const big = (f: string, v: unknown): bigint => {
+    if (typeof v !== "bigint" || v <= 0n) throw new KavachError("MALFORMED", stage, `${f} must be a positive bigint`);
+    return v;
+  };
+  const int = (f: string, v: unknown): number => {
+    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) throw new KavachError("MALFORMED", stage, `${f} must be a positive integer`);
+    return v;
+  };
+  if (!Array.isArray(p.kinds) || p.kinds.length === 0) throw new KavachError("MALFORMED", stage, "kinds must declare at least one kind");
+  const seen = new Set<number>();
+  const kinds: KindDeclaration[] = p.kinds.map((raw: unknown, i: number) => {
+    if (typeof raw !== "object" || raw === null) throw new KavachError("MALFORMED", stage, `kinds[${i}] must be an object`);
+    const k = raw as Record<string, unknown>;
+    const kind = k.kind;
+    if (typeof kind !== "number" || !Number.isInteger(kind) || kind < 0 || kind > MAX_WIRE_KIND) throw new KavachError("MALFORMED", stage, `kinds[${i}].kind must be an integer from 0 to ${MAX_WIRE_KIND}`);
+    if (seen.has(kind)) throw new KavachError("MALFORMED", stage, `kind ${kind} declared twice`);
+    seen.add(kind);
+    if (k.queue !== "keepAll" && k.queue !== "latestWins") throw new KavachError("MALFORMED", stage, `kinds[${i}].queue must be keepAll or latestWins`);
+    if (typeof k.history !== "boolean" || typeof k.newest !== "boolean") throw new KavachError("MALFORMED", stage, `kinds[${i}].history and .newest must be booleans`);
+    if (!k.history && !k.newest) throw new KavachError("MALFORMED", stage, `kinds[${i}] keeps nothing: declare history or newest`);
+    const headerClass = k.headerClass ?? 0;
+    if (headerClass !== 0 && headerClass !== 1 && headerClass !== 2 && headerClass !== 3) throw new KavachError("MALFORMED", stage, `kinds[${i}].headerClass must be 0 to 3`);
+    return { kind, retentionMs: big(`kinds[${i}].retentionMs`, k.retentionMs), queue: k.queue, history: k.history, newest: k.newest, headerClass };
+  });
+  return {
+    version: int("version", p.version),
+    deliveryWindowMs: big("deliveryWindowMs", p.deliveryWindowMs),
+    appendRetryWindowMs: big("appendRetryWindowMs", p.appendRetryWindowMs),
+    hygieneRotationMs: big("hygieneRotationMs", p.hygieneRotationMs),
+    maxOutboxRecords: int("maxOutboxRecords", p.maxOutboxRecords),
+    maxOutboxBytes: int("maxOutboxBytes", p.maxOutboxBytes),
+    kinds
+  };
+}
+
+/** The declaration of a kind, or `undefined` for one the product did not declare. */
+export function kindOf(policy: RetentionPolicy, kind: number): KindDeclaration | undefined {
+  return policy.kinds.find((k) => k.kind === kind);
+}
+
+/** The kinds kept in history, in declaration order. */
+export function historyKinds(policy: RetentionPolicy): readonly number[] {
+  return policy.kinds.filter((k) => k.history).map((k) => k.kind);
+}

package/src/record.ts

@@ -0,0 +1,106 @@
+/**
+ * Records: sealing with the active epoch, opening with certificate and manifest resolution
+ * (protocol section 9).
+ */
+import { equalBytes, toHex } from "./bytes.js";
+import {
+  DocumentType,
+  buildRecordWire,
+  decodeEnvelope,
+  expectType,
+  openRecord as openRecordBody,
+  parseDocument,
+  verifyDocument,
+  type EncryptedRecord,
+  type HeaderClass,
+  type Parsed,
+  type RecordKind
+} from "./codec.js";
+import { NONCE_BYTES, randomBytes, recordId } from "./crypto.js";
+import type { AuthorView } from "./epoch.js";
+import { MAX_COUNTER } from "./epoch.js";
+import { KavachError } from "./errors.js";
+
+export interface SealedRecord {
+  readonly wire: Uint8Array;
+  readonly recordId: Uint8Array;
+  readonly counter: number;
+  readonly kind: RecordKind;
+}
+
+/** Seal one record under the active epoch. The caller persists the result and the next counter (T6). */
+export function sealRecord(input: {
+  readonly streamId: Uint8Array;
+  readonly epoch: number;
+  readonly nextCounter: number;
+  readonly kind: RecordKind;
+  /** The product's event time for the record, carried in the envelope; absent when the kind has none. */
+  readonly eventTime?: bigint | undefined;
+  /** The declared header class of the kind, the one thing the relay sees of it. */
+  readonly headerClass: HeaderClass;
+  readonly payload: Uint8Array;
+  readonly sentAt: bigint;
+  readonly epochKey: Uint8Array;
+  readonly signingSecretKey: Uint8Array;
+  readonly nonce?: Uint8Array;
+}): SealedRecord {
+  if (input.nextCounter > MAX_COUNTER) throw new KavachError("COUNTER_EXHAUSTED", "sealRecord");
+  const nonce = input.nonce ?? randomBytes(NONCE_BYTES);
+  const wire = buildRecordWire(
+    { streamId: input.streamId, epoch: input.epoch, counter: input.nextCounter, sentAt: input.sentAt, headerClass: input.headerClass, kind: input.kind, eventTime: input.eventTime },
+    input.payload,
+    input.epochKey,
+    nonce,
+    input.signingSecretKey
+  );
+  return { wire, recordId: recordId(input.streamId, input.epoch, input.nextCounter), counter: input.nextCounter, kind: input.kind };
+}
+
+export interface OpenedRecord {
+  readonly record: Parsed<EncryptedRecord>;
+  readonly recordId: Uint8Array;
+  /** From the envelope: the kind, the event time if the sender gave one, and the payload. */
+  readonly kind: RecordKind;
+  readonly eventTime: bigint | undefined;
+  readonly payload: Uint8Array;
+  /** The record comes from a device of the author that is no longer current: history only. */
+  readonly superseded: boolean;
+}
+
+/**
+ * Verify and open a record. The author view supplies the certificate for the record's stream
+ * (the current one, or an archived one for history); `epochKeyFor` returns the stored key for
+ * (stream, epoch) or `undefined`, which is `KEY_PENDING`.
+ */
+export function openRecordWire(
+  wire: Uint8Array,
+  author: AuthorView,
+  epochKeyFor: (streamId: Uint8Array, epoch: number) => Uint8Array | undefined
+): OpenedRecord {
+  const stage = "openRecord";
+  const parsed = expectType<EncryptedRecord>(parseDocument(wire), DocumentType.EncryptedRecord, stage);
+  const cert = [...author.certificates.values()].find((c) => equalBytes(c.streamId, parsed.streamId));
+  if (!cert) throw new KavachError("NOT_AUTHORIZED", stage, "record stream belongs to no known device of the author");
+  const record = expectType<EncryptedRecord>(verifyDocument(wire, cert.signingKey), DocumentType.EncryptedRecord, stage);
+  const key = epochKeyFor(record.streamId, record.epoch);
+  if (!key) throw new KavachError("KEY_PENDING", stage, `no key for epoch ${record.epoch}`);
+  const envelope = decodeEnvelope(openRecordBody(record, key));
+  return { record, recordId: recordId(record.streamId, record.epoch, record.counter), kind: envelope.kind, eventTime: envelope.eventTime, payload: envelope.payload, superseded: !cert.current };
+}
+
+/** (generation, epoch, counter) ordering for the live pin. */
+export interface PinSlot {
+  readonly generation: bigint;
+  readonly epoch: number;
+  readonly counter: number;
+}
+
+export function compareSlots(a: PinSlot, b: PinSlot): number {
+  if (a.generation !== b.generation) return a.generation < b.generation ? -1 : 1;
+  if (a.epoch !== b.epoch) return a.epoch - b.epoch;
+  return a.counter - b.counter;
+}
+
+export function slotKey(streamId: Uint8Array, epoch: number, counter: number): string {
+  return `${toHex(streamId)}:${epoch}:${counter}`;
+}