@plane31/blind-relay 0.1.1 → 0.1.2

package/src/transport.ts

@@ -0,0 +1,106 @@
+/**
+ * The transport the host implements (protocol section 13): a directory and a relay. The SDK
+ * passes opaque bytes through unchanged; no plaintext payload ever enters this interface.
+ */
+
+export type MutationStatus = "COMMITTED" | "ALREADY_COMMITTED" | "CONFLICT" | "IGNORED_OLDER" | "RETRYABLE" | "UNAUTHORIZED" | "PERMANENT_FAILURE";
+
+export interface MutationOutcome {
+  readonly status: MutationStatus;
+  /** On CONFLICT: the bytes the host currently holds, when it can return them. */
+  readonly current?: Uint8Array | undefined;
+  readonly currentRevision?: bigint | undefined;
+}
+
+export interface ResolvedAccount {
+  readonly accountName: string;
+  readonly accountKey: Uint8Array;
+  /** The current certificate wire. */
+  readonly certificate: Uint8Array;
+  /** When the account's key changed through a reset: the receipt that proves it. */
+  readonly resetReceipt?: Uint8Array | undefined;
+}
+
+export interface JoinRequest {
+  readonly circleId: Uint8Array;
+  readonly accountName: string;
+  readonly action: "join" | "leave";
+  readonly requestedAt: bigint;
+}
+
+export interface Directory {
+  resolveAccounts(names: readonly string[]): Promise<readonly ResolvedAccount[]>;
+  /** Snapshots name identities; the directory maps them back to accounts (host-trusted, like first contact). */
+  resolveIdentities(identityIds: readonly Uint8Array[]): Promise<readonly ResolvedAccount[]>;
+  getCertificate(hash: Uint8Array): Promise<Uint8Array | undefined>;
+  activateDevice(input: {
+    accountName: string;
+    expectedCertificateHash: Uint8Array;
+    expectedVaultRevision: bigint;
+    expectedVaultHash: Uint8Array;
+    newCertificate: Uint8Array;
+    newVault: Uint8Array;
+  }): Promise<MutationOutcome>;
+  registerAccount(input: { certificate: Uint8Array; vault: Uint8Array }): Promise<MutationOutcome>;
+  getVault(accountName: string): Promise<Uint8Array | undefined>;
+  publishVault(input: { expectedRevision: bigint; expectedHash: Uint8Array | undefined; newVault: Uint8Array }): Promise<MutationOutcome>;
+  getCircle(circleId: Uint8Array): Promise<Uint8Array | undefined>;
+  publishOwnedCircle(input: { circleId: Uint8Array; expectedRevision: bigint; expectedHash: Uint8Array | undefined; newSnapshot: Uint8Array }): Promise<MutationOutcome>;
+  requestJoin(circleId: Uint8Array): Promise<MutationOutcome>;
+  requestLeave(circleId: Uint8Array): Promise<MutationOutcome>;
+  readRequests(circleId: Uint8Array): Promise<readonly JoinRequest[]>;
+  getResetKeyList(): Promise<Uint8Array | undefined>;
+  getResetReceipt(resetId: Uint8Array): Promise<Uint8Array | undefined>;
+  resetAccount(input: {
+    accountName: string;
+    expectedOldIdentityId: Uint8Array;
+    newCertificate: Uint8Array;
+    newVault: Uint8Array;
+    resetId: Uint8Array;
+    reauthProof: Uint8Array;
+  }): Promise<MutationOutcome & { receipt?: Uint8Array | undefined }>;
+}
+
+export interface EpochBundle {
+  readonly manifest: Uint8Array;
+  /** The caller's own wrap. */
+  readonly wrap: Uint8Array | undefined;
+}
+
+export type AppendStatus = "ACCEPTED" | "ALREADY_ACCEPTED" | "EQUIVOCATION" | "STALE_APPEND" | "RETRYABLE" | "UNAUTHORIZED" | "SUPERSEDED_DEVICE" | "EPOCH_FENCED";
+
+export interface AppendOutcome {
+  readonly status: AppendStatus;
+  readonly deliverySeq?: bigint;
+}
+
+export interface ReadRecordsResult {
+  readonly records: readonly { readonly deliverySeq: bigint; readonly wire: Uint8Array }[];
+  readonly nextSeq: bigint;
+  readonly tail: bigint;
+  readonly expiredThrough: bigint;
+  readonly committedCursor: bigint;
+}
+
+export interface Relay {
+  getCurrentEpoch(streamId: Uint8Array): Promise<{ epoch: number; manifestHash: Uint8Array } | undefined>;
+  getEpoch(streamId: Uint8Array, epoch: number): Promise<EpochBundle | undefined>;
+  publishEpoch(input: {
+    streamId: Uint8Array;
+    expectedEpoch: number;
+    expectedHash: Uint8Array | undefined;
+    manifest: Uint8Array;
+    wraps: ReadonlyMap<string, Uint8Array>;
+  }): Promise<MutationOutcome & { currentEpoch?: number | undefined; currentManifest?: Uint8Array | undefined }>;
+  /** MUST be callable from inside T6h without awaiting: it queues the bytes synchronously and returns a promise. */
+  appendRecord(recordId: Uint8Array, wire: Uint8Array): Promise<AppendOutcome>;
+  readRecords(streamId: Uint8Array, afterSeq: bigint, limit: number): Promise<ReadRecordsResult>;
+  ackThrough(streamId: Uint8Array, cursor: bigint): Promise<{ status: "COMMITTED" | "CURSOR_OUT_OF_RANGE" | "RETRYABLE" | "UNAUTHORIZED"; committedCursor?: bigint }>;
+  /** The streams this reader is subscribed to (the host creates subscriptions). */
+  listSubscriptions(): Promise<readonly { streamId: Uint8Array; authorIdentityId: Uint8Array }[]>;
+}
+
+export interface Transport {
+  readonly directory: Directory;
+  readonly relay: Relay;
+}

package/src/vault.ts

@@ -0,0 +1,126 @@
+/**
+ * The account vault and the recovery order (protocol section 5).
+ *
+ * The vault carries the account seed, the last device checkpoint and the circle pins with their
+ * sharing preference. It never carries a key that decrypts a record. Recovery tries the platform
+ * provider, then a saved code, and otherwise reports `ACCOUNT_RECOVERY_REQUIRED`; it never
+ * manufactures identity keys.
+ */
+import { compareBytes, equalBytes } from "./bytes.js";
+import {
+  decodeRecoveryCode,
+  encodeRecoveryCode,
+  openVault,
+  sealVault,
+  type OpenedVault,
+  type VaultContents,
+  type VaultEntry,
+  type VaultHeader
+} from "./codec.js";
+import { KEY_BYTES, NONCE_BYTES, bodyHash, randomBytes } from "./crypto.js";
+import { KavachError, isKavachError } from "./errors.js";
+
+export { encodeRecoveryCode, decodeRecoveryCode, openVault, sealVault };
+export type { OpenedVault, VaultContents, VaultEntry, VaultHeader };
+
+export type ProviderStatus = "available" | "unavailable" | "locked" | "unsupported" | "error";
+export type BackupState = "unknown" | "pending" | "unavailable";
+
+export interface ProviderLoadResult {
+  readonly status: ProviderStatus;
+  readonly reason?: string;
+  readonly recoveryKey?: Uint8Array;
+}
+
+export interface ProviderSaveResult {
+  readonly status: ProviderStatus;
+  readonly reason?: string;
+  /** A successful local write is never reported as a completed cloud backup. */
+  readonly backupState: BackupState;
+}
+
+export interface ProviderStatusResult {
+  readonly status: ProviderStatus;
+  readonly backupState: BackupState;
+  readonly reason?: string;
+}
+
+/** The platform recovery provider the host supplies (synced Keychain, Block Store, ...). */
+export interface RecoveryProvider {
+  load(accountName: string, identityId: Uint8Array): Promise<ProviderLoadResult>;
+  save(accountName: string, identityId: Uint8Array, recoveryKey: Uint8Array): Promise<ProviderSaveResult>;
+  status(): Promise<ProviderStatusResult>;
+  /** Logout or retirement: forget local access without deleting the shared item. */
+  eraseLocalAccess(): Promise<void>;
+}
+
+export function newRecoveryKey(): Uint8Array {
+  return randomBytes(KEY_BYTES);
+}
+
+/** Seal a vault at a revision with a fresh nonce. Returns the exact bytes and their hash. */
+export function buildVault(header: VaultHeader, contents: VaultContents, recoveryKey: Uint8Array): { wire: Uint8Array; hash: Uint8Array } {
+  const wire = sealVault(header, contents, recoveryKey, randomBytes(NONCE_BYTES));
+  return { wire, hash: bodyHash(wire) };
+}
+
+/** Pure edits to the entry list, keeping it sorted and unique by circle id. */
+export function upsertEntry(entries: readonly VaultEntry[], entry: VaultEntry): VaultEntry[] {
+  const rest = entries.filter((e) => !equalBytes(e.circleId, entry.circleId));
+  return [...rest, entry].sort((a, b) => compareBytes(a.circleId, b.circleId));
+}
+
+export function removeEntry(entries: readonly VaultEntry[], circleId: Uint8Array): VaultEntry[] {
+  return entries.filter((e) => !equalBytes(e.circleId, circleId));
+}
+
+export type RecoverySource = "provider" | "code";
+
+export interface RecoveryOutcome {
+  readonly vault: OpenedVault;
+  readonly recoveryKey: Uint8Array;
+  readonly source: RecoverySource;
+  readonly providerStatus: ProviderStatus;
+}
+
+/**
+ * The recovery order. The provider is asked first; a saved code second; when neither opens the
+ * vault the result is `ACCOUNT_RECOVERY_REQUIRED` and the caller preserves what it cannot use.
+ * A wrong key is an authentication failure and never a reason to reset.
+ */
+export async function recoverAccount(input: {
+  readonly accountName: string;
+  readonly identityId: Uint8Array;
+  readonly accountKey: Uint8Array;
+  readonly vaultWire: Uint8Array;
+  readonly provider: RecoveryProvider;
+  readonly recoveryCode?: string;
+}): Promise<RecoveryOutcome> {
+  const stage = "recoverAccount";
+  const tryOpen = (key: Uint8Array): OpenedVault | undefined => {
+    try {
+      return openVault(input.vaultWire, key, input.accountName, input.accountKey);
+    } catch (e) {
+      if (isKavachError(e, "DECRYPT_FAILED")) return undefined;
+      throw e;
+    }
+  };
+  let providerStatus: ProviderStatus = "error";
+  try {
+    const loaded = await input.provider.load(input.accountName, input.identityId);
+    providerStatus = loaded.status;
+    if (loaded.status === "available" && loaded.recoveryKey) {
+      const vault = tryOpen(loaded.recoveryKey);
+      if (vault) return { vault, recoveryKey: loaded.recoveryKey, source: "provider", providerStatus };
+    }
+  } catch {
+    providerStatus = "error";
+  }
+  if (input.recoveryCode !== undefined) {
+    const key = decodeRecoveryCode(input.recoveryCode);
+    const vault = tryOpen(key);
+    if (vault) return { vault, recoveryKey: key, source: "code", providerStatus };
+    throw new KavachError("DECRYPT_FAILED", stage, "recovery code does not open the vault");
+  }
+  throw new KavachError("ACCOUNT_RECOVERY_REQUIRED", stage, `provider ${providerStatus}, no code`);
+}