@plane31/blind-relay 0.1.1 → 0.1.2

package/dist/crypto/sodium.d.ts

@@ -1,7 +1,9 @@
+import type { CryptoBackend } from "./backend.js";
 /**
- * The libsodium backend (wasm). Loaded only when asked for, so the default bundle never carries
- * the wasm; use it on Node, where it is faster than the portable backend, and to cross-check it.
+ * Node only. The wrapper is loaded through its `require` condition, the CommonJS build, which is
+ * self-contained; its ESM build has shipped broken (0.7.16 imports a sibling file the package does
+ * not contain), and a consumer's plain `import` would hit that. The release smoke test loads this
+ * entry from the packed tarball in a clean Node to keep it so.
  */
-import type { CryptoBackend } from "./backend.js";
 export declare function loadSodiumBackend(): Promise<CryptoBackend>;
 //# sourceMappingURL=sodium.d.ts.map

package/dist/crypto/sodium.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sodium.d.ts","sourceRoot":"","sources":["../../src/crypto/sodium.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAc,aAAa,EAAe,MAAM,cAAc,CAAC;AAI3E,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,CAoChE"}
+{"version":3,"file":"sodium.d.ts","sourceRoot":"","sources":["../../src/crypto/sodium.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAc,aAAa,EAAe,MAAM,cAAc,CAAC;AAI3E;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,CAqChE"}

package/dist/crypto/sodium.js

@@ -1,5 +1,17 @@
+/**
+ * The libsodium backend (wasm). Loaded only when asked for, so the default bundle never carries
+ * the wasm; use it on Node, where it is faster than the portable backend, and to cross-check it.
+ */
+import { createRequire } from "node:module";
+/**
+ * Node only. The wrapper is loaded through its `require` condition, the CommonJS build, which is
+ * self-contained; its ESM build has shipped broken (0.7.16 imports a sibling file the package does
+ * not contain), and a consumer's plain `import` would hit that. The release smoke test loads this
+ * entry from the packed tarball in a clean Node to keep it so.
+ */
 export async function loadSodiumBackend() {
-    const mod = (await import("libsodium-wrappers-sumo"));
+    const require = createRequire(import.meta.url);
+    const mod = require("libsodium-wrappers-sumo");
     const sodium = mod.default ?? mod;
     await sodium.ready;
     return {

package/dist/crypto/sodium.js.map

@@ -1 +1 @@
-{"version":3,"file":"sodium.js","sourceRoot":"","sources":["../../src/crypto/sodium.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sodium.js","sourceRoot":"","sources":["../../src/crypto/sodium.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,yBAAyB,CAAkC,CAAC;IAChF,MAAM,MAAM,GAAW,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;IAC1C,MAAM,MAAM,CAAC,KAAK,CAAC;IACnB,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC;QACpF,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC;QACvD,mBAAmB,CAAC,IAAI;YACtB,MAAM,EAAE,GAAG,MAAM,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;YACjD,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC;QAC/D,CAAC;QACD,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,SAAS,CAAC;QACrF,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS;YAC1C,IAAI,CAAC;gBACH,OAAO,MAAM,CAAC,2BAA2B,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YAC3E,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,gBAAgB,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,EAAE,IAAI,MAAM,CAAC,kCAAkC,CAAC,SAAS,CAAC;QAChH,kBAAkB,CAAC,IAAI;YACrB,MAAM,EAAE,GAAG,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;YAChD,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC;QAC/D,CAAC;QACD,UAAU;YACR,MAAM,EAAE,GAAG,MAAM,CAAC,kBAAkB,EAAE,CAAC;YACvC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC;QAC/D,CAAC;QACD,UAAU,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,SAAS,CAAC;QACpF,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC;QAC/G,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC;QAChH,WAAW,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,0CAA0C,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC;QAChI,WAAW,EAAE,CAAC,gBAAgB,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,0CAA0C,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC;QAC9I,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;KAC1C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plane31/blind-relay",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Kavach v1 protocol: documents, cryptography, state machine. Pure TypeScript, no platform imports.",
   "license": "Apache-2.0",
   "repository": {
@@ -46,7 +46,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "sideEffects": false,
   "dependencies": {

package/src/adapters/index.ts

@@ -0,0 +1,102 @@
+/**
+ * @plane31/blind-relay/adapters: the contracts an adapter or host author implements, and what their
+ * tests need to drive them. Applications import `@plane31/blind-relay` instead.
+ *
+ * A `Store` and `SecretStore` adapter implements the row tables and the transaction interface;
+ * a `Transport` adapter implements the directory and relay calls; a `RecoveryProvider` keeps
+ * the recovery key with the platform; a host parses and verifies the signed documents the
+ * transport carries. The in-memory implementations are the behavioural reference.
+ */
+
+// Bytes --------------------------------------------------------------------------------------------
+export { Reader, Writer, compareBytes, concat, equalBytes, fromHex, toHex, u16, u32, u64 } from "../bytes.js";
+
+// Cipher suite: readiness, randomness and the identifiers a host derives --------------------------
+export { bodyHash, identityId, randomBytes, ready, recordId, signingKeypairFromSeed, streamId, type SigningKeypair } from "../crypto.js";
+
+// Errors -------------------------------------------------------------------------------------------
+export { KavachError, isKavachError, type ErrorCode } from "../errors.js";
+
+// Signed documents, as a host or transport sees them ----------------------------------------------
+export {
+  DocumentType,
+  buildResetKeyList,
+  buildResetReceipt,
+  expectType,
+  parseDocument,
+  parseVaultHeader,
+  verifyDocument,
+  type AccountDevice,
+  type AccountResetReceipt,
+  type CircleSnapshot,
+  type EncryptedRecord,
+  type EpochManifest,
+  type Parsed,
+  type ResetKeyEntry,
+  type ResetKeyList,
+  type SignedDocument,
+  type VaultHeader
+} from "../codec.js";
+
+// Store --------------------------------------------------------------------------------------------
+export {
+  MemorySecretStore,
+  MemoryStore,
+  invokeSync,
+  type ActivationRow,
+  type CertificateRow,
+  type CircleRow,
+  type ClockRow,
+  type EpochRow,
+  type EpochStatus,
+  type HistoryRow,
+  type NewestRow,
+  type MemoryStoreOptions,
+  type MetaRow,
+  type OutboxRow,
+  type OutboxStatus,
+  type EnqueueKeyRow,
+  type HistoryIndexRow,
+  type KeyRange,
+  inKeyRange,
+  type PendingResetRow,
+  type PinRow,
+  type QuarantineRow,
+  type ReaderEpochRow,
+  type ResetListRow,
+  type ResetReceiptRow,
+  type RevisionRow,
+  type SecretName,
+  type SecretStore,
+  type SelfRow,
+  type Store,
+  type StoreState,
+  type StreamRow,
+  type SubscriptionRow,
+  type TableName,
+  type Tables,
+  type Tx,
+  type UnresolvedRow,
+  type VaultRow
+} from "../store.js";
+
+// Transport ----------------------------------------------------------------------------------------
+export type {
+  AppendOutcome,
+  AppendStatus,
+  Directory,
+  EpochBundle,
+  JoinRequest,
+  MutationOutcome,
+  MutationStatus,
+  ReadRecordsResult,
+  Relay,
+  ResolvedAccount,
+  Transport
+} from "../transport.js";
+
+// Recovery provider --------------------------------------------------------------------------------
+export type { BackupState, ProviderLoadResult, ProviderSaveResult, ProviderStatus, ProviderStatusResult, RecoveryProvider } from "../vault.js";
+
+// The transactions an adapter test drives against a store -----------------------------------------
+export { openStore, t1Activate, t1Header, t1Secrets, t3ApplyChange, type ChangeResult, type OpenedState } from "../transactions.js";

package/src/audience.ts

@@ -0,0 +1,123 @@
+/**
+ * Audience resolution and the desired revision (protocol section 7).
+ */
+import { compareBytes, equalBytes, toHex } from "./bytes.js";
+import type { CircleState } from "./circle.js";
+import { KavachError } from "./errors.js";
+import type { AccountPin } from "./identity.js";
+
+export const MAX_AUDIENCE = 100;
+
+export interface AudienceEntry {
+  readonly identityId: Uint8Array;
+  readonly certificateHash: Uint8Array;
+  readonly boxKey: Uint8Array;
+}
+
+export interface ResolvedAudience {
+  /** Sorted by identity id, self included. */
+  readonly rows: readonly AudienceEntry[];
+  /** Rows other than self. */
+  readonly recipientCount: number;
+  /** A digest-friendly description of the exact certificate-bound audience. */
+  readonly key: string;
+}
+
+export function isEligible(circle: CircleState, selfIdentityId: Uint8Array): boolean {
+  return (
+    circle.status === "member" &&
+    circle.enabled &&
+    circle.revision > 0n &&
+    circle.members.some((m) => equalBytes(m, selfIdentityId))
+  );
+}
+
+/**
+ * Self plus every member of every eligible circle, each at its current certificate. Anything
+ * missing is `METADATA_REQUIRED`; more than 100 distinct accounts is `RECIPIENT_LIMIT`. The
+ * author never guesses, omits a recipient or reuses an obsolete key.
+ */
+export function resolveAudience(self: AccountPin, circles: readonly CircleState[], pins: ReadonlyMap<string, AccountPin>, retired: ReadonlySet<string> = new Set()): ResolvedAudience {
+  const stage = "resolveAudience";
+  const wanted = new Map<string, Uint8Array>();
+  wanted.set(toHex(self.identityId), self.identityId);
+  for (const c of circles) {
+    if (!isEligible(c, self.identityId)) continue;
+    // An identity retired by a validated reset receipt is no longer a recipient.
+    for (const m of c.members) if (!retired.has(toHex(m))) wanted.set(toHex(m), m);
+  }
+  if (wanted.size > MAX_AUDIENCE) throw new KavachError("RECIPIENT_LIMIT", stage, `${wanted.size} accounts`);
+  const rows: AudienceEntry[] = [];
+  for (const [hex, iid] of wanted) {
+    const pin = hex === toHex(self.identityId) ? self : pins.get(hex);
+    if (!pin) throw new KavachError("METADATA_REQUIRED", stage, "no certificate for a member");
+    rows.push({ identityId: iid, certificateHash: pin.certificateHash, boxKey: pin.boxKey });
+  }
+  rows.sort((a, b) => compareBytes(a.identityId, b.identityId));
+  return { rows, recipientCount: rows.length - 1, key: rows.map((r) => toHex(r.identityId) + ":" + toHex(r.certificateHash)).join(",") };
+}
+
+// Desired revision -----------------------------------------------------------------------------
+
+export type AudienceEvent =
+  | { readonly kind: "snapshot"; readonly circleId: Uint8Array; readonly revision: bigint }
+  | { readonly kind: "deviceChanged"; readonly identityId: Uint8Array; readonly certificateHash: Uint8Array }
+  | { readonly kind: "ownActivation" }
+  | { readonly kind: "join"; readonly circleId: Uint8Array }
+  | { readonly kind: "leave"; readonly circleId: Uint8Array }
+  | { readonly kind: "enable"; readonly circleId: Uint8Array }
+  | { readonly kind: "disable"; readonly circleId: Uint8Array }
+  | { readonly kind: "counterExhausted" }
+  | { readonly kind: "hygiene" }
+  | { readonly kind: "clockReversal" };
+
+export interface RevisionState {
+  readonly desiredRevision: bigint;
+  /** Highest snapshot revision processed per circle, so reprocessing does not increment. */
+  readonly seenSnapshots: ReadonlyMap<string, bigint>;
+  /** Certificate hash last accepted per recipient, so a replayed certificate does not increment. */
+  readonly seenCertificates: ReadonlyMap<string, string>;
+}
+
+export const initialRevisionState: RevisionState = { desiredRevision: 1n, seenSnapshots: new Map(), seenCertificates: new Map() };
+
+export interface Invalidation {
+  /** The active epoch is no longer usable; allocated counters are burned. */
+  readonly clearActiveEpoch: true;
+  /** Outbox rows sealed under the obsolete revision and not yet handed off are cancelled. */
+  readonly cancelObsoleteOutbox: true;
+  readonly paused: "rotation";
+}
+
+export const INVALIDATION: Invalidation = { clearActiveEpoch: true, cancelObsoleteOutbox: true, paused: "rotation" };
+
+/**
+ * Apply one event. Returns the new state and whether the desired revision moved. Every move
+ * is a rotation: the caller performs the invalidation in the same transaction (T3).
+ */
+export function applyAudienceEvent(state: RevisionState, event: AudienceEvent): { state: RevisionState; changed: boolean } {
+  const bump = (extra?: Partial<RevisionState>): { state: RevisionState; changed: true } => ({
+    state: { ...state, ...extra, desiredRevision: state.desiredRevision + 1n },
+    changed: true
+  });
+  switch (event.kind) {
+    case "snapshot": {
+      const key = toHex(event.circleId);
+      const seen = state.seenSnapshots.get(key) ?? 0n;
+      if (event.revision <= seen) return { state, changed: false };
+      const seenSnapshots = new Map(state.seenSnapshots);
+      seenSnapshots.set(key, event.revision);
+      return bump({ seenSnapshots });
+    }
+    case "deviceChanged": {
+      const key = toHex(event.identityId);
+      const hash = toHex(event.certificateHash);
+      if (state.seenCertificates.get(key) === hash) return { state, changed: false };
+      const seenCertificates = new Map(state.seenCertificates);
+      seenCertificates.set(key, hash);
+      return bump({ seenCertificates });
+    }
+    default:
+      return bump();
+  }
+}

package/src/bytes.ts

@@ -0,0 +1,209 @@
+/**
+ * Fixed-width big-endian encoding, protocol section 3.
+ * u64 values are BigInt end to end; nothing is ever rounded through a double.
+ */
+import { KavachError } from "./errors.js";
+
+export const MAX_DOCUMENT_BYTES = 16_384;
+export const MAX_PAYLOAD_BYTES = 4_096;
+const U32_MAX = 0xffff_ffff;
+const U64_MAX = (1n << 64n) - 1n;
+const NAME_RULE = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function concat(...parts: readonly Uint8Array[]): Uint8Array {
+  let length = 0;
+  for (const part of parts) length += part.length;
+  const out = new Uint8Array(length);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+
+export function u8(value: number): Uint8Array {
+  if (!Number.isInteger(value) || value < 0 || value > 0xff) throw new RangeError("u8 out of range");
+  return Uint8Array.of(value);
+}
+
+export function u16(value: number): Uint8Array {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) throw new RangeError("u16 out of range");
+  return Uint8Array.of(value >>> 8, value & 0xff);
+}
+
+export function u32(value: number): Uint8Array {
+  if (!Number.isInteger(value) || value < 0 || value > U32_MAX) throw new RangeError("u32 out of range");
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, value, false);
+  return out;
+}
+
+export function u64(value: bigint): Uint8Array {
+  if (typeof value !== "bigint" || value < 0n || value > U64_MAX) throw new RangeError("u64 out of range");
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, value, false);
+  return out;
+}
+
+export function i32(value: number): Uint8Array {
+  if (!Number.isInteger(value) || value < -0x8000_0000 || value > 0x7fff_ffff) throw new RangeError("i32 out of range");
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setInt32(0, value, false);
+  return out;
+}
+
+/** The `accountName` rule: 1 to 64 ASCII letters, digits, underscore or hyphen, case-sensitive. */
+export function isValidName(name: string): boolean {
+  return NAME_RULE.test(name);
+}
+
+/** `B(name)`: u8 byte length followed by the ASCII bytes. */
+export function encodeName(name: string): Uint8Array {
+  if (!isValidName(name)) throw new KavachError("MALFORMED", "encodeName", "account name violates the name rule");
+  const bytes = new Uint8Array(name.length);
+  for (let i = 0; i < name.length; i++) bytes[i] = name.charCodeAt(i);
+  return concat(u8(bytes.length), bytes);
+}
+
+export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  return diff === 0;
+}
+
+export function isAllZero(bytes: Uint8Array): boolean {
+  let acc = 0;
+  for (const b of bytes) acc |= b;
+  return acc === 0;
+}
+
+const HEX = /^[0-9a-f]*$/i;
+
+export function toHex(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+
+export function fromHex(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0 || !HEX.test(hex)) throw new RangeError("bad hex");
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = Number.parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+  return out;
+}
+
+/** Compare two byte strings lexicographically, as the strict sort orders in section 3 require. */
+export function compareBytes(a: Uint8Array, b: Uint8Array): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return a.length - b.length;
+}
+
+/**
+ * A bounded reader. Every take is checked against the end; `end()` refuses trailing bytes.
+ * All failures are `MALFORMED`, which is what the codec reports before any cryptography.
+ */
+export class Reader {
+  private offset = 0;
+
+  constructor(
+    private readonly data: Uint8Array,
+    private readonly stage = "parse"
+  ) {}
+
+  get position(): number {
+    return this.offset;
+  }
+
+  get remaining(): number {
+    return this.data.length - this.offset;
+  }
+
+  take(n: number): Uint8Array {
+    if (!Number.isInteger(n) || n < 0 || this.offset + n > this.data.length) {
+      throw new KavachError("MALFORMED", this.stage, "truncated");
+    }
+    const out = this.data.slice(this.offset, this.offset + n);
+    this.offset += n;
+    return out;
+  }
+
+  u8(): number {
+    return this.take(1)[0] ?? 0;
+  }
+
+  u16(): number {
+    const b = this.take(2);
+    return ((b[0] ?? 0) << 8) | (b[1] ?? 0);
+  }
+
+  u32(): number {
+    const b = this.take(4);
+    return new DataView(b.buffer, b.byteOffset, 4).getUint32(0, false);
+  }
+
+  u64(): bigint {
+    const b = this.take(8);
+    return new DataView(b.buffer, b.byteOffset, 8).getBigUint64(0, false);
+  }
+
+  i32(): number {
+    const b = this.take(4);
+    return new DataView(b.buffer, b.byteOffset, 4).getInt32(0, false);
+  }
+
+  /** `B(name)`, enforcing the name rule. */
+  name(): string {
+    const n = this.u8();
+    const bytes = this.take(n);
+    let text = "";
+    for (const b of bytes) text += String.fromCharCode(b);
+    if (!isValidName(text)) throw new KavachError("MALFORMED", this.stage, "bad account name");
+    return text;
+  }
+
+  /** The bytes consumed so far, for AAD and body hashing. */
+  consumed(): Uint8Array {
+    return this.data.slice(0, this.offset);
+  }
+
+  end(): void {
+    if (this.offset !== this.data.length) throw new KavachError("MALFORMED", this.stage, "trailing bytes");
+  }
+}
+
+/** An append-only writer for building bodies. */
+export class Writer {
+  private readonly parts: Uint8Array[] = [];
+
+  bytes(value: Uint8Array): this {
+    this.parts.push(value);
+    return this;
+  }
+  u8(value: number): this {
+    return this.bytes(u8(value));
+  }
+  u16(value: number): this {
+    return this.bytes(u16(value));
+  }
+  u32(value: number): this {
+    return this.bytes(u32(value));
+  }
+  u64(value: bigint): this {
+    return this.bytes(u64(value));
+  }
+  i32(value: number): this {
+    return this.bytes(i32(value));
+  }
+  name(value: string): this {
+    return this.bytes(encodeName(value));
+  }
+  finish(): Uint8Array {
+    return concat(...this.parts);
+  }
+}

package/src/circle.ts

@@ -0,0 +1,127 @@
+/**
+ * Circle membership and owner approval (protocol section 6).
+ *
+ * Membership is one owner-signed snapshot. Join and leave requests are host state with no
+ * signature; the owner builds every successor from trusted local state plus one change.
+ */
+import { compareBytes, equalBytes, toHex } from "./bytes.js";
+import { DocumentType, buildCircleSnapshot, expectType, verifyDocument, type CircleSnapshot, type Parsed } from "./codec.js";
+import { randomBytes } from "./crypto.js";
+import { KavachError } from "./errors.js";
+
+export type CircleStatus = "requested" | "member" | "left" | "quarantined" | "closed";
+
+/** What the SDK persists per circle it has pinned. */
+export interface CircleState {
+  readonly circleId: Uint8Array;
+  readonly ownerIdentityId: Uint8Array;
+  /** 0n until the first verified snapshot. */
+  readonly revision: bigint;
+  readonly bodyHash: Uint8Array | undefined;
+  readonly snapshot: Uint8Array | undefined;
+  readonly members: readonly Uint8Array[];
+  readonly enabled: boolean;
+  readonly status: CircleStatus;
+  /** When the current snapshot was verified, for showing its age. */
+  readonly verifiedAt: bigint;
+}
+
+export type SnapshotOutcome =
+  | { readonly outcome: "ACCEPTED"; readonly state: CircleState; readonly snapshot: Parsed<CircleSnapshot> }
+  | { readonly outcome: "DUPLICATE"; readonly state: CircleState };
+
+export function newCircleId(): Uint8Array {
+  return randomBytes(16);
+}
+
+export function pinCircle(circleId: Uint8Array, ownerIdentityId: Uint8Array, enabled: boolean, status: CircleStatus = "requested"): CircleState {
+  return { circleId, ownerIdentityId, revision: 0n, bodyHash: undefined, snapshot: undefined, members: [], enabled, status, verifiedAt: 0n };
+}
+
+/**
+ * Accept a snapshot for a pinned circle under the pinned owner's account key.
+ * A lower revision is `ROLLBACK`; the same revision with the same body is a duplicate and with a
+ * different valid body is `EQUIVOCATION`, which quarantines the circle. Membership status comes
+ * from the snapshot: the account is a member when it is listed and waiting when it is not.
+ */
+export function acceptSnapshot(state: CircleState, wire: Uint8Array, ownerAccountKey: Uint8Array, selfIdentityId: Uint8Array, now: bigint): SnapshotOutcome {
+  const stage = "acceptSnapshot";
+  const doc = expectType<CircleSnapshot>(verifyDocument(wire, ownerAccountKey), DocumentType.CircleSnapshot, stage);
+  if (!equalBytes(doc.circleId, state.circleId) || !equalBytes(doc.ownerIdentityId, state.ownerIdentityId)) {
+    throw new KavachError("MALFORMED", stage, "snapshot is for another circle or owner");
+  }
+  if (doc.revision < state.revision) throw new KavachError("ROLLBACK", stage);
+  if (doc.revision === state.revision) {
+    if (state.bodyHash && equalBytes(doc.bodyHash, state.bodyHash)) return { outcome: "DUPLICATE", state };
+    throw new KavachError("EQUIVOCATION", stage, "two snapshots at one revision");
+  }
+  // A member that is no longer listed has been removed, whether by a removal or a closure; the
+  // two are indistinguishable to a member and mean the same thing locally. Only the owner's own
+  // explicit close sets "closed".
+  const listed = doc.members.some((m) => equalBytes(m, selfIdentityId));
+  let status: CircleStatus = state.status;
+  if (state.status === "quarantined") status = "quarantined";
+  else if (listed) status = "member";
+  else if (state.status === "member") status = "left";
+  return {
+    outcome: "ACCEPTED",
+    snapshot: doc,
+    state: { ...state, revision: doc.revision, bodyHash: doc.bodyHash, snapshot: wire, members: doc.members, status, verifiedAt: now }
+  };
+}
+
+/** Two different account keys for one account name among resolved members is a forgery attempt. */
+export function checkMemberResolution(resolved: ReadonlyMap<string, { accountName: string; accountKey: Uint8Array }>): void {
+  const byName = new Map<string, string>();
+  for (const [iid, r] of resolved) {
+    const seen = byName.get(r.accountName);
+    if (seen !== undefined && seen !== toHex(r.accountKey)) {
+      throw new KavachError("EQUIVOCATION", "resolveMembers", `two keys for ${r.accountName}`);
+    }
+    byName.set(r.accountName, toHex(r.accountKey));
+    void iid;
+  }
+}
+
+// Owner side -----------------------------------------------------------------------------------
+
+export interface OwnerKeys {
+  readonly identityId: Uint8Array;
+  readonly accountSecretKey: Uint8Array;
+}
+
+/** Revision 1 with the owner as sole member. */
+export function createCircleSnapshot(owner: OwnerKeys, circleId: Uint8Array): Uint8Array {
+  return buildCircleSnapshot({ circleId, ownerIdentityId: owner.identityId, revision: 1n, members: [owner.identityId] }, owner.accountSecretKey);
+}
+
+export type MembershipChange = { readonly admit: Uint8Array } | { readonly remove: Uint8Array } | { readonly close: true };
+
+/**
+ * The successor snapshot from trusted local state plus one change. Returns `undefined` when the
+ * change is already reflected (approval of an admitted account is idempotent).
+ */
+export function successorSnapshot(state: CircleState, change: MembershipChange, owner: OwnerKeys): Uint8Array | undefined {
+  if (!equalBytes(state.ownerIdentityId, owner.identityId)) throw new KavachError("NOT_AUTHORIZED", "successorSnapshot", "not the owner");
+  if (state.status === "closed") throw new KavachError("NOT_AUTHORIZED", "successorSnapshot", "circle closed");
+  let members: Uint8Array[];
+  if ("admit" in change) {
+    if (state.members.some((m) => equalBytes(m, change.admit))) return undefined;
+    members = [...state.members, change.admit];
+    if (members.length > 100) throw new KavachError("RECIPIENT_LIMIT", "successorSnapshot");
+  } else if ("remove" in change) {
+    if (equalBytes(change.remove, owner.identityId)) throw new KavachError("NOT_AUTHORIZED", "successorSnapshot", "the owner cannot leave without closing");
+    if (!state.members.some((m) => equalBytes(m, change.remove))) return undefined;
+    members = state.members.filter((m) => !equalBytes(m, change.remove));
+  } else {
+    members = [owner.identityId];
+    if (state.members.length === 1) return undefined;
+  }
+  members.sort(compareBytes);
+  return buildCircleSnapshot({ circleId: state.circleId, ownerIdentityId: owner.identityId, revision: state.revision + 1n, members }, owner.accountSecretKey);
+}
+
+/** The owner's restored device signs revision plus one over the current snapshot; the revision never resets. */
+export function isOwner(state: CircleState, selfIdentityId: Uint8Array): boolean {
+  return equalBytes(state.ownerIdentityId, selfIdentityId);
+}