@debros/orama 0.122.4-nightly

package/src/vault/index.ts

@@ -0,0 +1,65 @@
+// High-level vault client
+export { VaultClient } from './client';
+export { adaptiveThreshold, writeQuorum } from './quorum';
+export type {
+  VaultConfig,
+  SecretMeta,
+  StoreResult,
+  RetrieveResult,
+  ListResult,
+  DeleteResult,
+  GuardianResult,
+} from './types';
+
+// Vault auth (renamed to avoid collision with top-level AuthClient)
+export { AuthClient as VaultAuthClient } from './auth';
+
+// Transport (guardian communication)
+export { GuardianClient, GuardianError } from './transport';
+export { fanOut, fanOutIndexed, withTimeout, withRetry } from './transport';
+export type {
+  GuardianEndpoint,
+  GuardianErrorCode,
+  GuardianInfo,
+  HealthResponse as GuardianHealthResponse,
+  StatusResponse as GuardianStatusResponse,
+  PushResponse,
+  PullResponse,
+  StoreSecretResponse,
+  GetSecretResponse,
+  DeleteSecretResponse,
+  ListSecretsResponse,
+  SecretEntry,
+  ChallengeResponse as GuardianChallengeResponse,
+  SessionResponse as GuardianSessionResponse,
+  FanOutResult,
+} from './transport';
+
+// Crypto primitives
+export {
+  encrypt,
+  decrypt,
+  encryptString,
+  decryptString,
+  serialize as serializeEncrypted,
+  deserialize as deserializeEncrypted,
+  encryptAndSerialize,
+  deserializeAndDecrypt,
+  toHex as encryptedToHex,
+  fromHex as encryptedFromHex,
+  toBase64 as encryptedToBase64,
+  fromBase64 as encryptedFromBase64,
+  generateKey,
+  generateNonce,
+  clearKey,
+  isValidEncryptedData,
+  KEY_SIZE,
+  NONCE_SIZE,
+  TAG_SIZE,
+} from './crypto';
+export type { EncryptedData, SerializedEncryptedData } from './crypto';
+
+export { deriveKeyHKDF } from './crypto';
+
+export { shamirSplit, shamirCombine } from './crypto';
+export type { ShamirShare } from './crypto';

package/src/vault/quorum.ts

@@ -0,0 +1,16 @@
+/**
+ * Quorum calculations for distributed vault operations.
+ * Must match orama-vault (Zig side).
+ */
+
+/** Adaptive Shamir threshold: max(3, floor(N/3)). */
+export function adaptiveThreshold(n: number): number {
+  return Math.max(3, Math.floor(n / 3));
+}
+
+/** Write quorum: ceil(2N/3). Requires majority for consistency. */
+export function writeQuorum(n: number): number {
+  if (n === 0) return 0;
+  if (n <= 2) return n;
+  return Math.ceil((2 * n) / 3);
+}

package/src/vault/transport/fanout.ts

@@ -0,0 +1,94 @@
+import { GuardianClient, GuardianError } from './guardian';
+import type { GuardianEndpoint, GuardianErrorCode, FanOutResult } from './types';
+
+/**
+ * Fan out an operation to multiple guardians in parallel.
+ * Returns results from all guardians (both successes and failures).
+ */
+export async function fanOut<T>(
+  guardians: GuardianEndpoint[],
+  operation: (client: GuardianClient) => Promise<T>,
+): Promise<FanOutResult<T>[]> {
+  const results = await Promise.allSettled(
+    guardians.map(async (endpoint) => {
+      const client = new GuardianClient(endpoint);
+      const result = await operation(client);
+      return { endpoint, result, error: null } as FanOutResult<T>;
+    }),
+  );
+
+  return results.map((r, i) => {
+    if (r.status === 'fulfilled') return r.value;
+    const reason = r.reason as Error;
+    const errorCode: GuardianErrorCode | undefined = reason instanceof GuardianError ? reason.code : undefined;
+    return {
+      endpoint: guardians[i]!,
+      result: null,
+      error: reason.message,
+      errorCode,
+    };
+  });
+}
+
+/**
+ * Fan out an indexed operation to multiple guardians in parallel.
+ * The operation receives the index so each guardian can get a different share.
+ */
+export async function fanOutIndexed<T>(
+  guardians: GuardianEndpoint[],
+  operation: (client: GuardianClient, index: number) => Promise<T>,
+): Promise<FanOutResult<T>[]> {
+  const results = await Promise.allSettled(
+    guardians.map(async (endpoint, i) => {
+      const client = new GuardianClient(endpoint);
+      const result = await operation(client, i);
+      return { endpoint, result, error: null } as FanOutResult<T>;
+    }),
+  );
+
+  return results.map((r, i) => {
+    if (r.status === 'fulfilled') return r.value;
+    const reason = r.reason as Error;
+    const errorCode: GuardianErrorCode | undefined = reason instanceof GuardianError ? reason.code : undefined;
+    return {
+      endpoint: guardians[i]!,
+      result: null,
+      error: reason.message,
+      errorCode,
+    };
+  });
+}
+
+/**
+ * Race a promise against a timeout.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms),
+    ),
+  ]);
+}
+
+/**
+ * Retry a function with exponential backoff.
+ * Does not retry auth or not-found errors.
+ */
+export async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
+  let lastError: Error | undefined;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err as Error;
+      if (err instanceof GuardianError && (err.code === 'AUTH' || err.code === 'NOT_FOUND')) {
+        throw err;
+      }
+      if (i < attempts - 1) {
+        await new Promise((r) => setTimeout(r, 200 * Math.pow(2, i)));
+      }
+    }
+  }
+  throw lastError!;
+}

package/src/vault/transport/guardian.ts

@@ -0,0 +1,285 @@
+import type {
+  GuardianEndpoint,
+  GuardianErrorCode,
+  GuardianErrorBody,
+  HealthResponse,
+  StatusResponse,
+  GuardianInfo,
+  PushResponse,
+  PullResponse,
+  StoreSecretResponse,
+  GetSecretResponse,
+  DeleteSecretResponse,
+  ListSecretsResponse,
+  ChallengeResponse,
+  SessionResponse,
+} from './types';
+
+export class GuardianError extends Error {
+  constructor(public readonly code: GuardianErrorCode, message: string) {
+    super(message);
+    this.name = 'GuardianError';
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * HTTP client for a single orama-vault guardian node.
+ * Supports V1 (push/pull) and V2 (CRUD secrets) endpoints.
+ */
+export class GuardianClient {
+  private baseUrl: string;
+  private timeoutMs: number;
+  private sessionToken: string | null = null;
+
+  constructor(endpoint: GuardianEndpoint, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.baseUrl = `http://${endpoint.address}:${endpoint.port}`;
+    this.timeoutMs = timeoutMs;
+  }
+
+  /** Set a session token for authenticated V2 requests. */
+  setSessionToken(token: string): void {
+    this.sessionToken = token;
+  }
+
+  /** Get the current session token. */
+  getSessionToken(): string | null {
+    return this.sessionToken;
+  }
+
+  /** Clear the session token. */
+  clearSessionToken(): void {
+    this.sessionToken = null;
+  }
+
+  // ── V1 endpoints ────────────────────────────────────────────────────
+
+  /** GET /v1/vault/health */
+  async health(): Promise<HealthResponse> {
+    return this.get<HealthResponse>('/v1/vault/health');
+  }
+
+  /** GET /v1/vault/status */
+  async status(): Promise<StatusResponse> {
+    return this.get<StatusResponse>('/v1/vault/status');
+  }
+
+  /** GET /v1/vault/guardians */
+  async guardians(): Promise<GuardianInfo> {
+    return this.get<GuardianInfo>('/v1/vault/guardians');
+  }
+
+  /** POST /v1/vault/push — store a share (V1). */
+  async push(identity: string, share: Uint8Array): Promise<PushResponse> {
+    return this.post<PushResponse>('/v1/vault/push', {
+      identity,
+      share: uint8ToBase64(share),
+    });
+  }
+
+  /** POST /v1/vault/pull — retrieve a share (V1). */
+  async pull(identity: string): Promise<Uint8Array> {
+    const resp = await this.post<PullResponse>('/v1/vault/pull', { identity });
+    return base64ToUint8(resp.share);
+  }
+
+  /** Check if this guardian is reachable. */
+  async isReachable(): Promise<boolean> {
+    try {
+      await this.health();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── V2 auth endpoints ───────────────────────────────────────────────
+
+  /** POST /v2/vault/auth/challenge — request an auth challenge. */
+  async requestChallenge(identity: string): Promise<ChallengeResponse> {
+    return this.post<ChallengeResponse>('/v2/vault/auth/challenge', { identity });
+  }
+
+  /** POST /v2/vault/auth/session — exchange challenge for session token. */
+  async createSession(identity: string, nonce: string, created_ns: number, tag: string): Promise<SessionResponse> {
+    return this.post<SessionResponse>('/v2/vault/auth/session', {
+      identity,
+      nonce,
+      created_ns,
+      tag,
+    });
+  }
+
+  // ── V2 secrets CRUD ─────────────────────────────────────────────────
+
+  /** PUT /v2/vault/secrets/{name} — store a secret. Requires session token. */
+  async putSecret(name: string, share: Uint8Array, version: number): Promise<StoreSecretResponse> {
+    return this.authedRequest<StoreSecretResponse>('PUT', `/v2/vault/secrets/${encodeURIComponent(name)}`, {
+      share: uint8ToBase64(share),
+      version,
+    });
+  }
+
+  /** GET /v2/vault/secrets/{name} — retrieve a secret. Requires session token. */
+  async getSecret(name: string): Promise<{ share: Uint8Array; name: string; version: number; created_ns: number; updated_ns: number }> {
+    const resp = await this.authedRequest<GetSecretResponse>('GET', `/v2/vault/secrets/${encodeURIComponent(name)}`);
+    return {
+      share: base64ToUint8(resp.share),
+      name: resp.name,
+      version: resp.version,
+      created_ns: resp.created_ns,
+      updated_ns: resp.updated_ns,
+    };
+  }
+
+  /** DELETE /v2/vault/secrets/{name} — delete a secret. Requires session token. */
+  async deleteSecret(name: string): Promise<DeleteSecretResponse> {
+    return this.authedRequest<DeleteSecretResponse>('DELETE', `/v2/vault/secrets/${encodeURIComponent(name)}`);
+  }
+
+  /** GET /v2/vault/secrets — list all secrets. Requires session token. */
+  async listSecrets(): Promise<ListSecretsResponse> {
+    return this.authedRequest<ListSecretsResponse>('GET', '/v2/vault/secrets');
+  }
+
+  // ── Internal HTTP methods ───────────────────────────────────────────
+
+  private async authedRequest<T>(method: string, path: string, body?: unknown): Promise<T> {
+    if (!this.sessionToken) {
+      throw new GuardianError('AUTH', 'No session token set. Call authenticate() first.');
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const headers: Record<string, string> = {
+        'X-Session-Token': this.sessionToken,
+      };
+      const init: RequestInit = {
+        method,
+        headers,
+        signal: controller.signal,
+      };
+
+      if (body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        init.body = JSON.stringify(body);
+      }
+
+      const resp = await fetch(`${this.baseUrl}${path}`, init);
+
+      if (!resp.ok) {
+        const errBody = (await resp.json().catch(() => ({}))) as GuardianErrorBody;
+        const msg = errBody.error || `HTTP ${resp.status}`;
+        throw new GuardianError(classifyHttpStatus(resp.status), msg);
+      }
+
+      return (await resp.json()) as T;
+    } catch (err) {
+      throw classifyError(err);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async get<T>(path: string): Promise<T> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const resp = await fetch(`${this.baseUrl}${path}`, {
+        method: 'GET',
+        signal: controller.signal,
+      });
+
+      if (!resp.ok) {
+        const body = (await resp.json().catch(() => ({}))) as GuardianErrorBody;
+        const msg = body.error || `HTTP ${resp.status}`;
+        throw new GuardianError(classifyHttpStatus(resp.status), msg);
+      }
+
+      return (await resp.json()) as T;
+    } catch (err) {
+      throw classifyError(err);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const resp = await fetch(`${this.baseUrl}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!resp.ok) {
+        const errBody = (await resp.json().catch(() => ({}))) as GuardianErrorBody;
+        const msg = errBody.error || `HTTP ${resp.status}`;
+        throw new GuardianError(classifyHttpStatus(resp.status), msg);
+      }
+
+      return (await resp.json()) as T;
+    } catch (err) {
+      throw classifyError(err);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+// ── Error classification ──────────────────────────────────────────────────
+
+function classifyHttpStatus(status: number): GuardianErrorCode {
+  if (status === 404) return 'NOT_FOUND';
+  if (status === 401 || status === 403) return 'AUTH';
+  if (status === 409) return 'CONFLICT';
+  if (status >= 500) return 'SERVER_ERROR';
+  return 'NETWORK';
+}
+
+function classifyError(err: unknown): GuardianError {
+  if (err instanceof GuardianError) return err;
+  if (err instanceof Error) {
+    if (err.name === 'AbortError') {
+      return new GuardianError('TIMEOUT', `Request timed out: ${err.message}`);
+    }
+    if (err.name === 'TypeError' || err.message.includes('fetch')) {
+      return new GuardianError('NETWORK', `Network error: ${err.message}`);
+    }
+    return new GuardianError('NETWORK', err.message);
+  }
+  return new GuardianError('NETWORK', String(err));
+}
+
+// ── Base64 helpers ────────────────────────────────────────────────────────
+
+function uint8ToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+function base64ToUint8(b64: string): Uint8Array {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+  }
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/vault/transport/index.ts

@@ -0,0 +1,19 @@
+export { GuardianClient, GuardianError } from './guardian';
+export { fanOut, fanOutIndexed, withTimeout, withRetry } from './fanout';
+export type {
+  GuardianEndpoint,
+  GuardianErrorCode,
+  GuardianInfo,
+  HealthResponse,
+  StatusResponse,
+  PushResponse,
+  PullResponse,
+  StoreSecretResponse,
+  GetSecretResponse,
+  DeleteSecretResponse,
+  ListSecretsResponse,
+  SecretEntry,
+  ChallengeResponse,
+  SessionResponse,
+  FanOutResult,
+} from './types';

package/src/vault/transport/types.ts

@@ -0,0 +1,101 @@
+/** A guardian node endpoint. */
+export interface GuardianEndpoint {
+  address: string;
+  port: number;
+}
+
+/** V1 push response. */
+export interface PushResponse {
+  status: string;
+}
+
+/** V1 pull response. */
+export interface PullResponse {
+  share: string; // base64
+}
+
+/** V2 store response. */
+export interface StoreSecretResponse {
+  status: string;
+  name: string;
+  version: number;
+}
+
+/** V2 get response. */
+export interface GetSecretResponse {
+  share: string; // base64
+  name: string;
+  version: number;
+  created_ns: number;
+  updated_ns: number;
+}
+
+/** V2 delete response. */
+export interface DeleteSecretResponse {
+  status: string;
+  name: string;
+}
+
+/** V2 list response. */
+export interface ListSecretsResponse {
+  secrets: SecretEntry[];
+}
+
+/** An entry in the list secrets response. */
+export interface SecretEntry {
+  name: string;
+  version: number;
+  size: number;
+}
+
+/** Health check response. */
+export interface HealthResponse {
+  status: string;
+  version: string;
+}
+
+/** Status response. */
+export interface StatusResponse {
+  status: string;
+  version: string;
+  data_dir: string;
+  client_port: number;
+  peer_port: number;
+}
+
+/** Guardian info response. */
+export interface GuardianInfo {
+  guardians: Array<{ address: string; port: number }>;
+  threshold: number;
+  total: number;
+}
+
+/** Challenge response from auth endpoint. */
+export interface ChallengeResponse {
+  nonce: string;
+  created_ns: number;
+  tag: string;
+}
+
+/** Session token response from auth endpoint. */
+export interface SessionResponse {
+  identity: string;
+  expiry_ns: number;
+  tag: string;
+}
+
+/** Error body from guardian. */
+export interface GuardianErrorBody {
+  error: string;
+}
+
+/** Error classification codes. */
+export type GuardianErrorCode = 'TIMEOUT' | 'NOT_FOUND' | 'AUTH' | 'SERVER_ERROR' | 'NETWORK' | 'CONFLICT';
+
+/** Fan-out result for a single guardian. */
+export interface FanOutResult<T> {
+  endpoint: GuardianEndpoint;
+  result: T | null;
+  error: string | null;
+  errorCode?: GuardianErrorCode;
+}

package/src/vault/types.ts

@@ -0,0 +1,62 @@
+import type { GuardianEndpoint } from './transport/types';
+
+/** Configuration for VaultClient. */
+export interface VaultConfig {
+  /** Guardian endpoints to connect to. */
+  guardians: GuardianEndpoint[];
+  /** HMAC key for authentication (derived from user's secret). */
+  hmacKey: Uint8Array;
+  /** Identity hash (hex string, 64 chars). */
+  identityHex: string;
+  /** Request timeout in ms (default: 10000). */
+  timeoutMs?: number;
+}
+
+/** Metadata for a stored secret. */
+export interface SecretMeta {
+  name: string;
+  version: number;
+  size: number;
+}
+
+/** Result of a store operation. */
+export interface StoreResult {
+  /** Number of guardians that acknowledged. */
+  ackCount: number;
+  /** Total guardians contacted. */
+  totalContacted: number;
+  /** Number of failures. */
+  failCount: number;
+  /** Whether write quorum was met. */
+  quorumMet: boolean;
+  /** Per-guardian results. */
+  guardianResults: GuardianResult[];
+}
+
+/** Result of a retrieve operation. */
+export interface RetrieveResult {
+  /** The reconstructed secret data. */
+  data: Uint8Array;
+  /** Number of shares collected. */
+  sharesCollected: number;
+}
+
+/** Result of a list operation. */
+export interface ListResult {
+  secrets: SecretMeta[];
+}
+
+/** Result of a delete operation. */
+export interface DeleteResult {
+  /** Number of guardians that acknowledged. */
+  ackCount: number;
+  totalContacted: number;
+  quorumMet: boolean;
+}
+
+/** Per-guardian operation result. */
+export interface GuardianResult {
+  endpoint: string;
+  success: boolean;
+  error?: string;
+}