@plane31/blind-relay 0.0.0-stage → 0.1.2

package/src/errors.ts

@@ -0,0 +1,78 @@
+/** Error codes of Kavach v1, protocol section 14. The set is closed: new codes are a protocol change. */
+export type ErrorCode =
+  // Parsing
+  | "SIZE_LIMIT"
+  | "MALFORMED"
+  | "UNSUPPORTED_VERSION"
+  | "UNSUPPORTED_TYPE"
+  | "BAD_PAYLOAD"
+  // Authentication
+  | "INVALID_KEY"
+  | "BAD_SIGNATURE"
+  | "DECRYPT_FAILED"
+  | "WRAP_HASH_MISMATCH"
+  | "KEY_COMMITMENT_MISMATCH"
+  // Trust and state
+  | "ACCOUNT_KEY_CHANGED"
+  | "ACCOUNT_RECOVERY_REQUIRED"
+  | "DEVICE_ROLLBACK"
+  | "DEVICE_ID_REUSED"
+  | "SUPERSEDED_DEVICE"
+  | "VAULT_BINDING"
+  | "RESET_BINDING"
+  | "RESET_KEYS_REQUIRED"
+  | "RESET_KEY_REVOKED"
+  | "RESET_CLOCK_UNTRUSTED"
+  | "ROLLBACK"
+  | "EQUIVOCATION"
+  | "METADATA_REQUIRED"
+  | "KEY_PENDING"
+  | "NOT_AUTHORIZED"
+  | "ROTATION_REQUIRED"
+  | "COUNTER_EXHAUSTED"
+  | "RECIPIENT_LIMIT"
+  // Delivery
+  | "CLOCK_SKEW"
+  | "EXPIRED"
+  | "QUEUE_FULL"
+  | "CURSOR_OUT_OF_RANGE"
+  | "STALE_APPEND"
+  // Storage and transport
+  | "LOCKED"
+  | "RECOVERY_REQUIRED"
+  | "STORAGE_FAILURE"
+  /** 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";
+
+const RETRYABLE: ReadonlySet<ErrorCode> = new Set<ErrorCode>([
+  "KEY_PENDING",
+  "METADATA_REQUIRED",
+  "RESET_KEYS_REQUIRED",
+  "ROTATION_REQUIRED",
+  "LOCKED",
+  "STORAGE_FAILURE",
+  "NETWORK"
+]);
+
+/**
+ * Every failure the SDK reports. `code` is one of the protocol's codes, `stage` is a safe
+ * stage name for logs (never a secret, a payload or an identifier), `retryable` says whether
+ * the same call may succeed later without any change of state.
+ */
+export class KavachError extends Error {
+  readonly code: ErrorCode;
+  readonly stage: string;
+  readonly retryable: boolean;
+
+  constructor(code: ErrorCode, stage = "unknown", message?: string) {
+    super(message ?? `${code} at ${stage}`);
+    this.name = "KavachError";
+    this.code = code;
+    this.stage = stage;
+    this.retryable = RETRYABLE.has(code);
+  }
+}
+
+export function isKavachError(value: unknown, code?: ErrorCode): value is KavachError {
+  return value instanceof KavachError && (code === undefined || value.code === code);
+}

package/src/historyIndex.ts

@@ -0,0 +1,61 @@
+/**
+ * The history index: two time-ordered keys per history row, so a history query, a cursor and
+ * the retention purge read a bounded slice of the store instead of the whole history table.
+ *
+ * Keys sort by time and are unique: the tuple is the zero-padded `sentAt`, epoch and counter
+ * followed by the record id. `t:<kind>:<tuple>` is the timeline of one kind; `a:<author>:<kind>:
+ * <tuple>` is one author's. A query without a kind merges the two kinds that reach history
+ * declared with history; a slot-only kind is never history. The tuple doubles as the page cursor:
+ * it names a position that no later write moves.
+ */
+import { unbig } from "./rows.js";
+import type { HistoryRow, Store, Tx } from "./store.js";
+
+const META = "meta";
+
+/** A u64 as twenty decimal digits, so that string order is numeric order. */
+export function padTime(ms: bigint): string {
+  return (ms < 0n ? 0n : ms).toString().padStart(20, "0");
+}
+
+export function historyTuple(r: Pick<HistoryRow, "sentAt" | "epoch" | "counter" | "recordId">): string {
+  return `${padTime(unbig(r.sentAt))}:${r.epoch.toString().padStart(10, "0")}:${r.counter.toString().padStart(10, "0")}:${r.recordId}`;
+}
+
+export function timelinePrefix(kind: number): string {
+  return `t:${kind}:`;
+}
+
+export function authorPrefix(authorIdentityId: string, kind: number): string {
+  return `a:${authorIdentityId}:${kind}:`;
+}
+
+function keysOf(r: HistoryRow): string[] {
+  const tuple = historyTuple(r);
+  return [timelinePrefix(r.kind) + tuple, authorPrefix(r.authorIdentityId, r.kind) + tuple];
+}
+
+/** Index a history row; written in the same transaction as the row (T6, T7). */
+export function indexHistory(tx: Tx, r: HistoryRow): void {
+  for (const k of keysOf(r)) tx.put("historyIndex", k, { recordId: r.recordId });
+}
+
+export function unindexHistory(tx: Tx, r: HistoryRow): void {
+  for (const k of keysOf(r)) tx.delete("historyIndex", k);
+}
+
+/**
+ * Build the index once for a store written before it existed: every history row is indexed and
+ * the header records it. A fresh store is marked at T1 and never runs this. Idempotent.
+ */
+export async function ensureHistoryIndex(store: Store): Promise<boolean> {
+  const built = await store.read((tx) => tx.get("meta", META)?.historyIndex === 1);
+  if (built) return false;
+  return store.transaction((tx) => {
+    const meta = tx.get("meta", META);
+    if (!meta || meta.historyIndex === 1) return false;
+    for (const [, r] of tx.list("history")) indexHistory(tx, r);
+    tx.put("meta", META, { ...meta, historyIndex: 1 });
+    return true;
+  });
+}

package/src/identity.ts

@@ -0,0 +1,158 @@
+/**
+ * Accounts, devices, certificates and generation rules (protocol section 4).
+ *
+ * The pin is the local trust state for one account: (`accountName`, `AK`) at first contact, then
+ * the greatest accepted device generation with its certificate hash and device keys. Everything
+ * here is a pure decision over a pin and a candidate certificate; persistence is the store's job.
+ */
+import { concat, equalBytes, toHex } from "./bytes.js";
+import {
+  DocumentType,
+  buildAccountDevice,
+  expectType,
+  verifyDocument,
+  type AccountDevice,
+  type Parsed
+} from "./codec.js";
+import {
+  DEVICE_ID_BYTES,
+  SEED_BYTES,
+  accountKeypair,
+  deviceBoxKeypair,
+  deviceSigningKeypair,
+  identityId,
+  randomBytes,
+  streamId,
+  type BoxKeypair,
+  type SigningKeypair
+} from "./crypto.js";
+import { KavachError } from "./errors.js";
+
+/** What the SDK persists per known account. */
+export interface AccountPin {
+  readonly accountName: string;
+  readonly accountKey: Uint8Array;
+  readonly identityId: Uint8Array;
+  readonly generation: bigint;
+  readonly certificateHash: Uint8Array;
+  readonly certificate: Uint8Array;
+  readonly deviceId: Uint8Array;
+  readonly signingKey: Uint8Array;
+  readonly boxKey: Uint8Array;
+  readonly streamId: Uint8Array;
+  /** Every device id this account has used, including the current one. */
+  readonly deviceIds: readonly Uint8Array[];
+}
+
+export type CertificateOutcome =
+  | { readonly outcome: "ACCEPTED"; readonly pin: AccountPin; readonly rotate: boolean; readonly previous: AccountPin | undefined }
+  | { readonly outcome: "DUPLICATE"; readonly pin: AccountPin };
+
+export function pinFromCertificate(doc: Parsed<AccountDevice>, previous?: AccountPin): AccountPin {
+  const iid = identityId(doc.accountName, doc.accountKey);
+  const ids = previous ? [...previous.deviceIds] : [];
+  if (!ids.some((d) => equalBytes(d, doc.deviceId))) ids.push(doc.deviceId);
+  return {
+    accountName: doc.accountName,
+    accountKey: doc.accountKey,
+    identityId: iid,
+    generation: doc.generation,
+    certificateHash: doc.bodyHash,
+    certificate: concat(doc.body, doc.signature),
+    deviceId: doc.deviceId,
+    signingKey: doc.signingKey,
+    boxKey: doc.boxKey,
+    streamId: streamId(iid, doc.deviceId),
+    deviceIds: ids
+  };
+}
+
+/**
+ * Accept or reject a certificate against the local pin for its account.
+ *
+ * - No pin yet: first contact. If `expected` names the account the directory resolved, the
+ *   certificate must carry that name and key; the pin is created and nothing rotates.
+ * - A pinned account: a different `AK` is `ACCOUNT_KEY_CHANGED` and the caller quarantines
+ *   (never closing or re-admitting anything); a lower generation is `DEVICE_ROLLBACK`; the same
+ *   generation is a duplicate or `EQUIVOCATION`; a higher one with a reused device id is
+ *   `DEVICE_ID_REUSED`; otherwise it is accepted and the audience must rotate.
+ */
+export function acceptCertificate(
+  current: AccountPin | undefined,
+  wire: Uint8Array,
+  expected?: { readonly accountName: string; readonly accountKey: Uint8Array }
+): CertificateOutcome {
+  const stage = "acceptCertificate";
+  const doc = expectType<AccountDevice>(verifyDocument(wire), DocumentType.AccountDevice, stage);
+  const anchor = current ?? expected;
+  if (anchor && (anchor.accountName !== doc.accountName || !equalBytes(anchor.accountKey, doc.accountKey))) {
+    throw new KavachError("ACCOUNT_KEY_CHANGED", stage, `certificate for ${doc.accountName} carries a different account key`);
+  }
+  if (!current) return { outcome: "ACCEPTED", pin: pinFromCertificate(doc), rotate: false, previous: undefined };
+  if (doc.generation < current.generation) throw new KavachError("DEVICE_ROLLBACK", stage);
+  if (doc.generation === current.generation) {
+    if (equalBytes(doc.bodyHash, current.certificateHash)) return { outcome: "DUPLICATE", pin: current };
+    throw new KavachError("EQUIVOCATION", stage, "two certificates at one generation");
+  }
+  if (current.deviceIds.some((d) => equalBytes(d, doc.deviceId))) throw new KavachError("DEVICE_ID_REUSED", stage);
+  return { outcome: "ACCEPTED", pin: pinFromCertificate(doc, current), rotate: true, previous: current };
+}
+
+// Own account and device ---------------------------------------------------------------------
+
+export interface DeviceKeys {
+  readonly deviceSeed: Uint8Array;
+  readonly deviceId: Uint8Array;
+  readonly signing: SigningKeypair;
+  readonly box: BoxKeypair;
+}
+
+export interface OwnAccount {
+  readonly accountName: string;
+  readonly accountSeed: Uint8Array;
+  readonly account: SigningKeypair;
+  readonly identityId: Uint8Array;
+}
+
+export function openAccount(accountName: string, accountSeed: Uint8Array): OwnAccount {
+  if (accountSeed.length !== SEED_BYTES) throw new KavachError("INVALID_KEY", "openAccount");
+  const account = accountKeypair(accountSeed);
+  return { accountName, accountSeed, account, identityId: identityId(accountName, account.publicKey) };
+}
+
+export function newAccountSeed(): Uint8Array {
+  return randomBytes(SEED_BYTES);
+}
+
+/** A fresh installation: new device seed and a random nonzero device id. Never backed up. */
+export function newDevice(): DeviceKeys {
+  const deviceSeed = randomBytes(SEED_BYTES);
+  let deviceId = randomBytes(DEVICE_ID_BYTES);
+  while (deviceId.every((b) => b === 0)) deviceId = randomBytes(DEVICE_ID_BYTES);
+  return deviceFromSeed(deviceSeed, deviceId);
+}
+
+export function deviceFromSeed(deviceSeed: Uint8Array, deviceId: Uint8Array): DeviceKeys {
+  if (deviceId.length !== DEVICE_ID_BYTES || deviceId.every((b) => b === 0)) throw new KavachError("MALFORMED", "device", "device id");
+  return { deviceSeed, deviceId, signing: deviceSigningKeypair(deviceSeed), box: deviceBoxKeypair(deviceSeed) };
+}
+
+/** Build and sign this account's certificate for a device at a generation. */
+export function certify(account: OwnAccount, device: DeviceKeys, generation: bigint): Uint8Array {
+  if (generation < 1n) throw new KavachError("MALFORMED", "certify", "generation");
+  return buildAccountDevice(
+    {
+      accountName: account.accountName,
+      accountKey: account.account.publicKey,
+      generation,
+      deviceId: device.deviceId,
+      signingKey: device.signing.publicKey,
+      boxKey: device.box.publicKey
+    },
+    account.account.secretKey
+  );
+}
+
+export function pinKey(identity: Uint8Array): string {
+  return toHex(identity);
+}