@debros/network-ts-sdk 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debros/network-ts-sdk",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "TypeScript SDK for DeBros Network Gateway - Database, PubSub, Cache, Storage, and more",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,12 @@
     "wasm",
     "serverless",
     "distributed",
-    "gateway"
+    "gateway",
+    "vault",
+    "secrets",
+    "shamir",
+    "encryption",
+    "guardian"
   ],
   "repository": {
     "type": "git",
@@ -53,6 +58,8 @@
     "release:gh": "npm publish --registry=https://npm.pkg.github.com"
   },
   "dependencies": {
+    "@noble/ciphers": "^0.5.3",
+    "@noble/hashes": "^1.4.0",
     "isomorphic-ws": "^5.0.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -6,12 +6,14 @@ import { NetworkClient } from "./network/client";
 import { CacheClient } from "./cache/client";
 import { StorageClient } from "./storage/client";
 import { FunctionsClient, FunctionsClientConfig } from "./functions/client";
+import { VaultClient } from "./vault/client";
 import { WSClientConfig } from "./core/ws";
 import {
   StorageAdapter,
   MemoryStorage,
   LocalStorageAdapter,
 } from "./auth/types";
+import type { VaultConfig } from "./vault/types";
 
 export interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
   apiKey?: string;
@@ -25,6 +27,8 @@ export interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
    * Use this to trigger gateway failover at the application layer.
    */
   onNetworkError?: NetworkErrorCallback;
+  /** Configuration for the vault (distributed secrets store). */
+  vaultConfig?: VaultConfig;
 }
 
 export interface Client {
@@ -35,6 +39,7 @@ export interface Client {
   cache: CacheClient;
   storage: StorageClient;
   functions: FunctionsClient;
+  vault: VaultClient | null;
 }
 
 export function createClient(config: ClientConfig): Client {
@@ -68,6 +73,9 @@ export function createClient(config: ClientConfig): Client {
   const cache = new CacheClient(httpClient);
   const storage = new StorageClient(httpClient);
   const functions = new FunctionsClient(httpClient, config.functionsConfig);
+  const vault = config.vaultConfig
+    ? new VaultClient(config.vaultConfig)
+    : null;
 
   return {
     auth,
@@ -77,6 +85,7 @@ export function createClient(config: ClientConfig): Client {
     cache,
     storage,
     functions,
+    vault,
   };
 }
 
@@ -133,3 +142,60 @@ export type {
 } from "./storage/client";
 export type { FunctionsClientConfig } from "./functions/client";
 export type * from "./functions/types";
+// Vault module
+export { VaultClient } from "./vault/client";
+export { AuthClient as VaultAuthClient } from "./vault/auth";
+export { GuardianClient, GuardianError } from "./vault/transport";
+export { fanOut, fanOutIndexed, withTimeout, withRetry } from "./vault/transport";
+export { adaptiveThreshold, writeQuorum } from "./vault/quorum";
+export {
+  encrypt,
+  decrypt,
+  encryptString,
+  decryptString,
+  serializeEncrypted,
+  deserializeEncrypted,
+  encryptAndSerialize,
+  deserializeAndDecrypt,
+  encryptedToHex,
+  encryptedFromHex,
+  encryptedToBase64,
+  encryptedFromBase64,
+  generateKey,
+  generateNonce,
+  clearKey,
+  isValidEncryptedData,
+  KEY_SIZE,
+  NONCE_SIZE,
+  TAG_SIZE,
+  deriveKeyHKDF,
+  shamirSplit,
+  shamirCombine,
+} from "./vault";
+export type {
+  VaultConfig,
+  SecretMeta,
+  StoreResult,
+  RetrieveResult,
+  ListResult,
+  DeleteResult,
+  GuardianResult as VaultGuardianResult,
+  EncryptedData,
+  SerializedEncryptedData,
+  ShamirShare,
+  GuardianEndpoint,
+  GuardianErrorCode,
+  GuardianInfo,
+  GuardianHealthResponse,
+  GuardianStatusResponse,
+  PushResponse,
+  PullResponse,
+  StoreSecretResponse,
+  GetSecretResponse,
+  DeleteSecretResponse,
+  ListSecretsResponse,
+  SecretEntry,
+  GuardianChallengeResponse,
+  GuardianSessionResponse,
+  FanOutResult,
+} from "./vault";

package/src/vault/auth.ts

@@ -0,0 +1,98 @@
+import { GuardianClient } from './transport/guardian';
+import type { GuardianEndpoint } from './transport/types';
+
+/**
+ * Handles challenge-response authentication with guardian nodes.
+ * Caches session tokens per guardian endpoint.
+ *
+ * Auth flow:
+ * 1. POST /v2/vault/auth/challenge with identity → get {nonce, created_ns, tag}
+ * 2. POST /v2/vault/auth/session with identity + challenge fields → get session token
+ * 3. Use session token as X-Session-Token header for V2 requests
+ *
+ * The session token format is: `<identity_hex>:<expiry_ns>:<tag_hex>`
+ */
+export class AuthClient {
+  private sessions = new Map<string, { token: string; expiryNs: number }>();
+  private identityHex: string;
+  private timeoutMs: number;
+
+  constructor(identityHex: string, timeoutMs = 10_000) {
+    this.identityHex = identityHex;
+    this.timeoutMs = timeoutMs;
+  }
+
+  /**
+   * Authenticate with a guardian and cache the session token.
+   * Returns a GuardianClient with the session token set.
+   */
+  async authenticate(endpoint: GuardianEndpoint): Promise<GuardianClient> {
+    const key = `${endpoint.address}:${endpoint.port}`;
+    const cached = this.sessions.get(key);
+
+    // Check if we have a valid cached session (with 30s safety margin)
+    if (cached) {
+      const nowNs = Date.now() * 1_000_000;
+      if (cached.expiryNs > nowNs + 30_000_000_000) {
+        const client = new GuardianClient(endpoint, this.timeoutMs);
+        client.setSessionToken(cached.token);
+        return client;
+      }
+      // Expired, remove
+      this.sessions.delete(key);
+    }
+
+    const client = new GuardianClient(endpoint, this.timeoutMs);
+
+    // Step 1: Request challenge
+    const challenge = await client.requestChallenge(this.identityHex);
+
+    // Step 2: Exchange for session
+    const session = await client.createSession(
+      this.identityHex,
+      challenge.nonce,
+      challenge.created_ns,
+      challenge.tag,
+    );
+
+    // Build token string: identity:expiry_ns:tag
+    const token = `${session.identity}:${session.expiry_ns}:${session.tag}`;
+    client.setSessionToken(token);
+
+    // Cache
+    this.sessions.set(key, { token, expiryNs: session.expiry_ns });
+
+    return client;
+  }
+
+  /**
+   * Authenticate with multiple guardians in parallel.
+   * Returns authenticated GuardianClients for all that succeed.
+   */
+  async authenticateAll(endpoints: GuardianEndpoint[]): Promise<{ client: GuardianClient; endpoint: GuardianEndpoint }[]> {
+    const results = await Promise.allSettled(
+      endpoints.map(async (ep) => {
+        const client = await this.authenticate(ep);
+        return { client, endpoint: ep };
+      }),
+    );
+
+    const authenticated: { client: GuardianClient; endpoint: GuardianEndpoint }[] = [];
+    for (const r of results) {
+      if (r.status === 'fulfilled') {
+        authenticated.push(r.value);
+      }
+    }
+    return authenticated;
+  }
+
+  /** Clear all cached sessions. */
+  clearSessions(): void {
+    this.sessions.clear();
+  }
+
+  /** Get the identity hex string. */
+  getIdentityHex(): string {
+    return this.identityHex;
+  }
+}

package/src/vault/client.ts

@@ -0,0 +1,197 @@
+import { AuthClient } from './auth';
+import type { GuardianClient } from './transport/guardian';
+import { withTimeout, withRetry } from './transport/fanout';
+import { split, combine } from './crypto/shamir';
+import type { Share } from './crypto/shamir';
+import { adaptiveThreshold, writeQuorum } from './quorum';
+import type {
+  VaultConfig,
+  StoreResult,
+  RetrieveResult,
+  ListResult,
+  DeleteResult,
+  GuardianResult,
+} from './types';
+
+const PULL_TIMEOUT_MS = 10_000;
+
+/**
+ * High-level client for the orama-vault distributed secrets store.
+ *
+ * Handles:
+ * - Authentication with guardian nodes
+ * - Shamir split/combine for data distribution
+ * - Quorum-based writes and reads
+ * - V2 CRUD operations (store, retrieve, list, delete)
+ */
+export class VaultClient {
+  private config: VaultConfig;
+  private auth: AuthClient;
+
+  constructor(config: VaultConfig) {
+    this.config = config;
+    this.auth = new AuthClient(config.identityHex, config.timeoutMs);
+  }
+
+  /**
+   * Store a secret across guardian nodes using Shamir splitting.
+   *
+   * @param name - Secret name (alphanumeric, _, -, max 128 chars)
+   * @param data - Secret data to store
+   * @param version - Monotonic version number (must be > previous)
+   */
+  async store(name: string, data: Uint8Array, version: number): Promise<StoreResult> {
+    const guardians = this.config.guardians;
+    const n = guardians.length;
+    const k = adaptiveThreshold(n);
+
+    // Shamir split the data
+    const shares = split(data, n, k);
+
+    // Authenticate and push to all guardians
+    const authed = await this.auth.authenticateAll(guardians);
+
+    const results = await Promise.allSettled(
+      authed.map(async ({ client, endpoint }, _i) => {
+        // Find the share for this guardian's index
+        const guardianIdx = guardians.indexOf(endpoint);
+        const share = shares[guardianIdx];
+        if (!share) throw new Error('share index out of bounds');
+
+        // Encode share as [x:1byte][y:rest]
+        const shareBytes = new Uint8Array(1 + share.y.length);
+        shareBytes[0] = share.x;
+        shareBytes.set(share.y, 1);
+
+        return withRetry(() => client.putSecret(name, shareBytes, version));
+      }),
+    );
+
+    // Wipe shares
+    for (const share of shares) {
+      share.y.fill(0);
+    }
+
+    const guardianResults: GuardianResult[] = authed.map(({ endpoint }, i) => {
+      const ep = `${endpoint.address}:${endpoint.port}`;
+      const r = results[i]!;
+      if (r.status === 'fulfilled') {
+        return { endpoint: ep, success: true };
+      }
+      return { endpoint: ep, success: false, error: (r.reason as Error).message };
+    });
+
+    const ackCount = results.filter((r) => r.status === 'fulfilled').length;
+    const failCount = results.filter((r) => r.status === 'rejected').length;
+    const w = writeQuorum(n);
+
+    return {
+      ackCount,
+      totalContacted: authed.length,
+      failCount,
+      quorumMet: ackCount >= w,
+      guardianResults,
+    };
+  }
+
+  /**
+   * Retrieve and reconstruct a secret from guardian nodes.
+   *
+   * @param name - Secret name
+   */
+  async retrieve(name: string): Promise<RetrieveResult> {
+    const guardians = this.config.guardians;
+    const n = guardians.length;
+    const k = adaptiveThreshold(n);
+
+    // Authenticate and pull from all guardians
+    const authed = await this.auth.authenticateAll(guardians);
+
+    const pullResults = await Promise.allSettled(
+      authed.map(async ({ client }) => {
+        const resp = await withTimeout(client.getSecret(name), PULL_TIMEOUT_MS);
+        const shareBytes = resp.share;
+        if (shareBytes.length < 2) throw new Error('Share too short');
+        return {
+          x: shareBytes[0]!,
+          y: shareBytes.slice(1),
+        } as Share;
+      }),
+    );
+
+    const shares: Share[] = [];
+    for (const r of pullResults) {
+      if (r.status === 'fulfilled') {
+        shares.push(r.value);
+      }
+    }
+
+    if (shares.length < k) {
+      throw new Error(
+        `Not enough shares: collected ${shares.length} of ${k} required (contacted ${authed.length} guardians)`,
+      );
+    }
+
+    // Reconstruct
+    const data = combine(shares);
+
+    // Wipe collected shares
+    for (const share of shares) {
+      share.y.fill(0);
+    }
+
+    return {
+      data,
+      sharesCollected: shares.length,
+    };
+  }
+
+  /**
+   * List all secrets for this identity.
+   * Queries the first reachable guardian (metadata is replicated).
+   */
+  async list(): Promise<ListResult> {
+    const guardians = this.config.guardians;
+    const authed = await this.auth.authenticateAll(guardians);
+
+    if (authed.length === 0) {
+      throw new Error('No guardians reachable');
+    }
+
+    // Query first authenticated guardian
+    const resp = await authed[0]!.client.listSecrets();
+    return { secrets: resp.secrets };
+  }
+
+  /**
+   * Delete a secret from all guardian nodes.
+   *
+   * @param name - Secret name to delete
+   */
+  async delete(name: string): Promise<DeleteResult> {
+    const guardians = this.config.guardians;
+    const n = guardians.length;
+
+    const authed = await this.auth.authenticateAll(guardians);
+
+    const results = await Promise.allSettled(
+      authed.map(async ({ client }) => {
+        return withRetry(() => client.deleteSecret(name));
+      }),
+    );
+
+    const ackCount = results.filter((r) => r.status === 'fulfilled').length;
+    const w = writeQuorum(n);
+
+    return {
+      ackCount,
+      totalContacted: authed.length,
+      quorumMet: ackCount >= w,
+    };
+  }
+
+  /** Clear all cached auth sessions. */
+  clearSessions(): void {
+    this.auth.clearSessions();
+  }
+}

package/src/vault/crypto/aes.ts

@@ -0,0 +1,271 @@
+/**
+ * AES-256-GCM Encryption
+ *
+ * Implements authenticated encryption using AES-256 in Galois/Counter Mode.
+ * Uses @noble/ciphers for platform-agnostic, audited cryptographic operations.
+ *
+ * Features:
+ * - Authenticated encryption (confidentiality + integrity)
+ * - 256-bit keys for strong security
+ * - 96-bit nonces (randomly generated)
+ * - 128-bit authentication tags
+ *
+ * Security considerations:
+ * - Never reuse a nonce with the same key
+ * - Nonces are randomly generated and prepended to ciphertext
+ * - Authentication tags are verified before decryption
+ */
+
+import { gcm } from '@noble/ciphers/aes';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { bytesToHex, hexToBytes, concatBytes } from '@noble/hashes/utils';
+
+/**
+ * Size constants
+ */
+export const KEY_SIZE = 32; // 256 bits
+export const NONCE_SIZE = 12; // 96 bits (recommended for GCM)
+export const TAG_SIZE = 16; // 128 bits
+
+/**
+ * Encrypted data structure
+ */
+export interface EncryptedData {
+  /** Ciphertext including authentication tag */
+  ciphertext: Uint8Array;
+  /** Nonce used for encryption */
+  nonce: Uint8Array;
+  /** Additional authenticated data (optional) */
+  aad?: Uint8Array;
+}
+
+/**
+ * Serialized encrypted data (nonce prepended to ciphertext)
+ */
+export interface SerializedEncryptedData {
+  /** Combined nonce + ciphertext + tag */
+  data: Uint8Array;
+  /** Additional authenticated data (optional) */
+  aad?: Uint8Array;
+}
+
+/**
+ * Encrypts data using AES-256-GCM
+ */
+export function encrypt(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  aad?: Uint8Array
+): EncryptedData {
+  validateKey(key);
+
+  const nonce = randomBytes(NONCE_SIZE);
+  const cipher = gcm(key, nonce, aad);
+  const ciphertext = cipher.encrypt(plaintext);
+
+  return {
+    ciphertext,
+    nonce,
+    aad,
+  };
+}
+
+/**
+ * Decrypts data using AES-256-GCM
+ */
+export function decrypt(encryptedData: EncryptedData, key: Uint8Array): Uint8Array {
+  validateKey(key);
+  validateNonce(encryptedData.nonce);
+
+  const cipher = gcm(key, encryptedData.nonce, encryptedData.aad);
+
+  try {
+    return cipher.decrypt(encryptedData.ciphertext);
+  } catch (error) {
+    throw new Error('Decryption failed: invalid ciphertext or authentication tag');
+  }
+}
+
+/**
+ * Encrypts a string message
+ */
+export function encryptString(
+  message: string,
+  key: Uint8Array,
+  aad?: Uint8Array
+): EncryptedData {
+  const plaintext = new TextEncoder().encode(message);
+  try {
+    return encrypt(plaintext, key, aad);
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+/**
+ * Decrypts to a string message
+ */
+export function decryptString(encryptedData: EncryptedData, key: Uint8Array): string {
+  const plaintext = decrypt(encryptedData, key);
+  try {
+    return new TextDecoder().decode(plaintext);
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+/**
+ * Serializes encrypted data (prepends nonce to ciphertext)
+ */
+export function serialize(encryptedData: EncryptedData): SerializedEncryptedData {
+  const data = concatBytes(encryptedData.nonce, encryptedData.ciphertext);
+
+  return {
+    data,
+    aad: encryptedData.aad,
+  };
+}
+
+/**
+ * Deserializes encrypted data
+ */
+export function deserialize(serialized: SerializedEncryptedData): EncryptedData {
+  if (serialized.data.length < NONCE_SIZE + TAG_SIZE) {
+    throw new Error('Invalid serialized data: too short');
+  }
+
+  const nonce = serialized.data.slice(0, NONCE_SIZE);
+  const ciphertext = serialized.data.slice(NONCE_SIZE);
+
+  return {
+    ciphertext,
+    nonce,
+    aad: serialized.aad,
+  };
+}
+
+/**
+ * Encrypts and serializes data in one step
+ */
+export function encryptAndSerialize(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  aad?: Uint8Array
+): SerializedEncryptedData {
+  const encrypted = encrypt(plaintext, key, aad);
+  return serialize(encrypted);
+}
+
+/**
+ * Deserializes and decrypts data in one step
+ */
+export function deserializeAndDecrypt(
+  serialized: SerializedEncryptedData,
+  key: Uint8Array
+): Uint8Array {
+  const encrypted = deserialize(serialized);
+  return decrypt(encrypted, key);
+}
+
+/**
+ * Converts encrypted data to hex string
+ */
+export function toHex(encryptedData: EncryptedData): string {
+  const serialized = serialize(encryptedData);
+  return bytesToHex(serialized.data);
+}
+
+/**
+ * Parses encrypted data from hex string
+ */
+export function fromHex(hex: string, aad?: Uint8Array): EncryptedData {
+  const normalized = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const data = hexToBytes(normalized);
+
+  return deserialize({ data, aad });
+}
+
+/**
+ * Converts encrypted data to base64 string
+ */
+export function toBase64(encryptedData: EncryptedData): string {
+  const serialized = serialize(encryptedData);
+
+  if (typeof btoa === 'function') {
+    return btoa(String.fromCharCode(...serialized.data));
+  } else {
+    return Buffer.from(serialized.data).toString('base64');
+  }
+}
+
+/**
+ * Parses encrypted data from base64 string
+ */
+export function fromBase64(base64: string, aad?: Uint8Array): EncryptedData {
+  let data: Uint8Array;
+
+  if (typeof atob === 'function') {
+    const binary = atob(base64);
+    data = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      data[i] = binary.charCodeAt(i);
+    }
+  } else {
+    data = new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+
+  return deserialize({ data, aad });
+}
+
+function validateKey(key: Uint8Array): void {
+  if (!(key instanceof Uint8Array)) {
+    throw new Error('Key must be a Uint8Array');
+  }
+
+  if (key.length !== KEY_SIZE) {
+    throw new Error(`Invalid key length: expected ${KEY_SIZE}, got ${key.length}`);
+  }
+}
+
+function validateNonce(nonce: Uint8Array): void {
+  if (!(nonce instanceof Uint8Array)) {
+    throw new Error('Nonce must be a Uint8Array');
+  }
+
+  if (nonce.length !== NONCE_SIZE) {
+    throw new Error(`Invalid nonce length: expected ${NONCE_SIZE}, got ${nonce.length}`);
+  }
+}
+
+/**
+ * Generates a random encryption key
+ */
+export function generateKey(): Uint8Array {
+  return randomBytes(KEY_SIZE);
+}
+
+/**
+ * Generates a random nonce
+ */
+export function generateNonce(): Uint8Array {
+  return randomBytes(NONCE_SIZE);
+}
+
+/**
+ * Securely clears a key from memory
+ */
+export function clearKey(key: Uint8Array): void {
+  key.fill(0);
+}
+
+/**
+ * Checks if encrypted data appears valid (basic structure check)
+ */
+export function isValidEncryptedData(data: EncryptedData): boolean {
+  return (
+    data.nonce instanceof Uint8Array &&
+    data.nonce.length === NONCE_SIZE &&
+    data.ciphertext instanceof Uint8Array &&
+    data.ciphertext.length >= TAG_SIZE
+  );
+}