@debros/network-ts-sdk 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debros/network-ts-sdk",
-  "version": "0.6.1",
+  "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/core/interfaces/IWebSocketClient.ts

@@ -41,12 +41,12 @@ export interface IWebSocketClient {
   /**
    * Register close handler
    */
-  onClose(handler: () => void): void;
+  onClose(handler: (code: number, reason: string) => void): void;
 
   /**
    * Unregister close handler
    */
-  offClose(handler: () => void): void;
+  offClose(handler: (code: number, reason: string) => void): void;
 
   /**
    * Check if WebSocket is connected

package/src/core/ws.ts

@@ -16,7 +16,7 @@ export interface WSClientConfig {
 
 export type WSMessageHandler = (data: string) => void;
 export type WSErrorHandler = (error: Error) => void;
-export type WSCloseHandler = () => void;
+export type WSCloseHandler = (code: number, reason: string) => void;
 export type WSOpenHandler = () => void;
 
 /**
@@ -102,7 +102,12 @@ export class WSClient {
         this.ws.addEventListener("error", (event: Event) => {
           console.error("[WSClient] WebSocket error:", event);
           clearTimeout(timeout);
-          const error = new SDKError("WebSocket error", 500, "WS_ERROR", event);
+          // Extract useful details from the event — raw Event objects don't serialize
+          const details: Record<string, any> = { type: event.type };
+          if ("message" in event) {
+            details.message = (event as ErrorEvent).message;
+          }
+          const error = new SDKError("WebSocket error", 0, "WS_ERROR", details);
 
           // Call the network error callback if configured
           if (this.onNetworkError) {
@@ -118,10 +123,13 @@ export class WSClient {
           reject(error);
         });
 
-        this.ws.addEventListener("close", () => {
+        this.ws.addEventListener("close", (event: Event) => {
           clearTimeout(timeout);
-          console.log("[WSClient] Connection closed");
-          this.closeHandlers.forEach((handler) => handler());
+          const closeEvent = event as CloseEvent;
+          const code = closeEvent.code ?? 1006;
+          const reason = closeEvent.reason ?? "";
+          console.log(`[WSClient] Connection closed (code: ${code}, reason: ${reason || "none"})`);
+          this.closeHandlers.forEach((handler) => handler(code, reason));
         });
       } catch (error) {
         reject(error);
@@ -206,7 +214,7 @@ export class WSClient {
    */
   send(data: string): void {
     if (this.ws?.readyState !== WebSocket.OPEN) {
-      throw new SDKError("WebSocket is not connected", 500, "WS_NOT_CONNECTED");
+      throw new SDKError("WebSocket is not connected", 0, "WS_NOT_CONNECTED");
     }
     this.ws.send(data);
   }

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/pubsub/client.ts

@@ -176,7 +176,7 @@ export class Subscription {
   private isClosed = false;
   private wsMessageHandler: ((data: string) => void) | null = null;
   private wsErrorHandler: ((error: Error) => void) | null = null;
-  private wsCloseHandler: (() => void) | null = null;
+  private wsCloseHandler: ((code: number, reason: string) => void) | null = null;
   private getPresenceFn: () => Promise<PresenceResponse>;
 
   constructor(
@@ -271,8 +271,8 @@ export class Subscription {
     this.wsClient.onError(this.wsErrorHandler);
 
     // Register close handler
-    this.wsCloseHandler = () => {
-      this.closeHandlers.forEach((handler) => handler());
+    this.wsCloseHandler = (code: number, reason: string) => {
+      this.closeHandlers.forEach((handler) => handler(code, reason));
     };
     this.wsClient.onClose(this.wsCloseHandler);
   }

package/src/pubsub/types.ts

@@ -42,5 +42,5 @@ export interface SubscribeOptions {
 
 export type MessageHandler = (message: PubSubMessage) => void;
 export type ErrorHandler = (error: Error) => void;
-export type CloseHandler = () => void;
+export type CloseHandler = (code: number, reason: string) => void;
 

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