@debros/network-ts-sdk 0.6.2 → 0.7.0

package/src/vault/crypto/hkdf.ts

@@ -0,0 +1,42 @@
+/**
+ * HKDF Key Derivation
+ *
+ * Derives deterministic sub-keys from a master secret using HKDF-SHA256 (RFC 5869).
+ */
+
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+
+/** Default output length in bytes (256 bits) */
+const DEFAULT_KEY_LENGTH = 32;
+
+/** Maximum allowed output length (255 * SHA-256 output = 8160 bytes) */
+const MAX_KEY_LENGTH = 255 * 32;
+
+/**
+ * Derives a sub-key from input key material using HKDF-SHA256.
+ *
+ * @param ikm - Input key material (e.g., wallet private key). MUST be high-entropy.
+ * @param salt - Domain separation salt. Can be a string or bytes.
+ * @param info - Context-specific info. Can be a string or bytes.
+ * @param length - Output key length in bytes (default: 32).
+ * @returns Derived key as Uint8Array. Caller MUST zero this after use.
+ */
+export function deriveKeyHKDF(
+  ikm: Uint8Array,
+  salt: string | Uint8Array,
+  info: string | Uint8Array,
+  length: number = DEFAULT_KEY_LENGTH,
+): Uint8Array {
+  if (!ikm || ikm.length === 0) {
+    throw new Error('HKDF: input key material must not be empty');
+  }
+  if (length <= 0 || length > MAX_KEY_LENGTH) {
+    throw new Error(`HKDF: output length must be between 1 and ${MAX_KEY_LENGTH}`);
+  }
+
+  const saltBytes = typeof salt === 'string' ? new TextEncoder().encode(salt) : salt;
+  const infoBytes = typeof info === 'string' ? new TextEncoder().encode(info) : info;
+
+  return hkdf(sha256, ikm, saltBytes, infoBytes, length);
+}

package/src/vault/crypto/index.ts

@@ -0,0 +1,27 @@
+export {
+  encrypt,
+  decrypt,
+  encryptString,
+  decryptString,
+  serialize,
+  deserialize,
+  encryptAndSerialize,
+  deserializeAndDecrypt,
+  toHex,
+  fromHex,
+  toBase64,
+  fromBase64,
+  generateKey,
+  generateNonce,
+  clearKey,
+  isValidEncryptedData,
+  KEY_SIZE,
+  NONCE_SIZE,
+  TAG_SIZE,
+} from './aes';
+export type { EncryptedData, SerializedEncryptedData } from './aes';
+
+export { deriveKeyHKDF } from './hkdf';
+
+export { split as shamirSplit, combine as shamirCombine } from './shamir';
+export type { Share as ShamirShare } from './shamir';

package/src/vault/crypto/shamir.ts

@@ -0,0 +1,173 @@
+/**
+ * Shamir's Secret Sharing over GF(2^8)
+ *
+ * Information-theoretic secret splitting: any K shares reconstruct the secret,
+ * K-1 shares reveal zero information.
+ *
+ * Uses GF(2^8) with irreducible polynomial x^8 + x^4 + x^3 + x + 1 (0x11B),
+ * same as AES. This is the standard choice for byte-level SSS.
+ */
+
+import { randomBytes } from '@noble/ciphers/webcrypto';
+
+// ── GF(2^8) Arithmetic ─────────────────────────────────────────────────────
+
+const IRREDUCIBLE = 0x11b;
+
+/** Exponential table: exp[log[a] + log[b]] = a * b */
+const EXP_TABLE = new Uint8Array(512);
+
+/** Logarithm table: log[a] for a in 1..255 (log[0] is undefined) */
+const LOG_TABLE = new Uint8Array(256);
+
+// Build log/exp tables using generator 3
+(function buildTables() {
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    EXP_TABLE[i] = x;
+    LOG_TABLE[x] = i;
+    x = x ^ (x << 1); // multiply by generator (3 is primitive in this field)
+    if (x >= 256) x ^= IRREDUCIBLE;
+  }
+  // Extend exp table for easy modular arithmetic (avoid mod 255)
+  for (let i = 255; i < 512; i++) {
+    EXP_TABLE[i] = EXP_TABLE[i - 255]!;
+  }
+})();
+
+/** GF(2^8) addition: XOR */
+function gfAdd(a: number, b: number): number {
+  return a ^ b;
+}
+
+/** GF(2^8) multiplication via log/exp tables */
+function gfMul(a: number, b: number): number {
+  if (a === 0 || b === 0) return 0;
+  return EXP_TABLE[LOG_TABLE[a]! + LOG_TABLE[b]!]!;
+}
+
+/** GF(2^8) multiplicative inverse */
+function gfInv(a: number): number {
+  if (a === 0) throw new Error('GF(2^8): division by zero');
+  return EXP_TABLE[255 - LOG_TABLE[a]!]!;
+}
+
+/** GF(2^8) division: a / b */
+function gfDiv(a: number, b: number): number {
+  if (b === 0) throw new Error('GF(2^8): division by zero');
+  if (a === 0) return 0;
+  return EXP_TABLE[(LOG_TABLE[a]! - LOG_TABLE[b]! + 255) % 255]!;
+}
+
+// ── Share Type ──────────────────────────────────────────────────────────────
+
+/** A single Shamir share */
+export interface Share {
+  /** Share index (1..N, never 0) */
+  x: number;
+  /** Share data (same length as secret) */
+  y: Uint8Array;
+}
+
+// ── Split ───────────────────────────────────────────────────────────────────
+
+/**
+ * Splits a secret into N shares with threshold K.
+ *
+ * @param secret - Secret bytes to split (any length)
+ * @param n - Total number of shares to create (2..255)
+ * @param k - Minimum shares needed for reconstruction (2..n)
+ * @returns Array of N shares
+ */
+export function split(secret: Uint8Array, n: number, k: number): Share[] {
+  if (k < 2) throw new Error('Threshold K must be at least 2');
+  if (n < k) throw new Error('Share count N must be >= threshold K');
+  if (n > 255) throw new Error('Maximum 255 shares (GF(2^8) limit)');
+  if (secret.length === 0) throw new Error('Secret must not be empty');
+
+  const coefficients = new Array<Uint8Array>(secret.length);
+  for (let i = 0; i < secret.length; i++) {
+    const poly = new Uint8Array(k);
+    poly[0] = secret[i]!;
+    const rand = randomBytes(k - 1);
+    poly.set(rand, 1);
+    coefficients[i] = poly;
+  }
+
+  const shares: Share[] = [];
+  for (let xi = 1; xi <= n; xi++) {
+    const y = new Uint8Array(secret.length);
+    for (let byteIdx = 0; byteIdx < secret.length; byteIdx++) {
+      y[byteIdx] = evaluatePolynomial(coefficients[byteIdx]!, xi);
+    }
+    shares.push({ x: xi, y });
+  }
+
+  for (const poly of coefficients) {
+    poly.fill(0);
+  }
+
+  return shares;
+}
+
+function evaluatePolynomial(coeffs: Uint8Array, x: number): number {
+  let result = 0;
+  for (let i = coeffs.length - 1; i >= 0; i--) {
+    result = gfAdd(gfMul(result, x), coeffs[i]!);
+  }
+  return result;
+}
+
+// ── Combine ─────────────────────────────────────────────────────────────────
+
+/**
+ * Reconstructs a secret from K or more shares using Lagrange interpolation.
+ *
+ * @param shares - Array of K or more shares (must all have same y.length)
+ * @returns Reconstructed secret
+ */
+export function combine(shares: Share[]): Uint8Array {
+  if (shares.length < 2) throw new Error('Need at least 2 shares');
+
+  const secretLength = shares[0]!.y.length;
+  for (const share of shares) {
+    if (share.y.length !== secretLength) {
+      throw new Error('All shares must have the same data length');
+    }
+    if (share.x === 0) {
+      throw new Error('Share index must not be 0');
+    }
+  }
+
+  const xValues = new Set(shares.map(s => s.x));
+  if (xValues.size !== shares.length) {
+    throw new Error('Duplicate share indices');
+  }
+
+  const secret = new Uint8Array(secretLength);
+
+  for (let byteIdx = 0; byteIdx < secretLength; byteIdx++) {
+    let value = 0;
+
+    for (let i = 0; i < shares.length; i++) {
+      const xi = shares[i]!.x;
+      const yi = shares[i]!.y[byteIdx]!;
+
+      let basis = 1;
+      for (let j = 0; j < shares.length; j++) {
+        if (i === j) continue;
+        const xj = shares[j]!.x;
+        basis = gfMul(basis, gfDiv(xj, gfAdd(xi, xj)));
+      }
+
+      value = gfAdd(value, gfMul(yi, basis));
+    }
+
+    secret[byteIdx] = value;
+  }
+
+  return secret;
+}
+
+/** @internal Exported for cross-platform test vector validation */
+export const _gf = { add: gfAdd, mul: gfMul, inv: gfInv, div: gfDiv, EXP_TABLE, LOG_TABLE } as const;

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;
+}