@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/types/error-response.js

@@ -1 +1,52 @@
-export function isErrorResponse(t){if(!t||"object"!=typeof t)return!1;const e=t;return"string"==typeof e.code&&"number"==typeof e.httpStatus&&"string"==typeof e.message}export function createErrorResponse(t){return{...t,timestamp:t.timestamp??Date.now()}}
+/**
+ * Error Response Types
+ *
+ * Dual-code error response system supporting both AWS standard codes
+ * and legacy xBind codes for backward compatibility.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Type guard to check if a value is an ErrorResponse
+ *
+ * @param value - Value to check
+ * @returns True if value is an ErrorResponse
+ *
+ * @example
+ * ```typescript
+ * if (isErrorResponse(result)) {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export function isErrorResponse(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const err = value;
+    return (typeof err.code === 'string' &&
+        typeof err.httpStatus === 'number' &&
+        typeof err.message === 'string');
+}
+/**
+ * Create a standardized error response
+ *
+ * @param params - Error response parameters
+ * @returns Standardized ErrorResponse object
+ *
+ * @example
+ * ```typescript
+ * const error = createErrorResponse({
+ *   code: 'UnauthorizedException',
+ *   legacyCode: 'XBIND_AUTH_FAILED',
+ *   httpStatus: 401,
+ *   message: 'Invalid signature'
+ * });
+ * ```
+ */
+export function createErrorResponse(params) {
+    return {
+        ...params,
+        timestamp: params.timestamp ?? Date.now()
+    };
+}

package/dist-standalone/vault-auth.js

@@ -1 +1,174 @@
-import{ok,err}from"./_deps/shared/index.js";import{toBase64}from"./crypto-utils.js";export async function signVaultRequest(t,e,n){const r=Date.now(),a=generateNonce(),o=JSON.stringify(n),c=`POST\n${e}\n${r}\n${a}\n${await hashString(o)}`;let i;try{const e=(new TextEncoder).encode(c);i=await crypto.subtle.sign({name:"Ed25519"},t.privateKey,e)}catch{return err("SIGN_FAILED")}return ok({signature:toBase64(new Uint8Array(i)),timestamp:r,nonce:a})}function generateNonce(){if("undefined"!=typeof crypto&&crypto.randomUUID)return crypto.randomUUID();const t=new Uint8Array(16);crypto.getRandomValues(t),t[6]=15&t[6]|64,t[8]=63&t[8]|128;const e=Array.from(t).map(t=>t.toString(16).padStart(2,"0")).join("");return[e.slice(0,8),e.slice(8,12),e.slice(12,16),e.slice(16,20),e.slice(20,32)].join("-")}async function hashString(t){const e=(new TextEncoder).encode(t),n=await crypto.subtle.digest("SHA-256",e);return toBase64(new Uint8Array(n))}export async function verifyVaultRequest(t,e,n,r,a,o,c){const i=Date.now();if(Math.abs(i-o)>3e5)return!1;const s=`POST\n${n}\n${o}\n${c}\n${await hashString(r)}`;let y;try{const t=new ArrayBuffer(e.byteLength);new Uint8Array(t).set(e),y=await crypto.subtle.importKey("raw",t,{name:"Ed25519"},!1,["verify"])}catch{return!1}try{const t=(new TextEncoder).encode(s),e=Uint8Array.from(atob(a),t=>t.charCodeAt(0));return await crypto.subtle.verify({name:"Ed25519"},y,e,t)}catch{return!1}}
+/**
+ * @module vault-auth
+ * DID-based authentication for Vault Store API requests.
+ *
+ * Implements Ed25519 signature over canonical request representation with:
+ * - Timestamp (prevents replay attacks >5min old)
+ * - Nonce (prevents duplicate requests)
+ * - Request body hash (ensures integrity)
+ *
+ * Server verifies signature + timestamp + nonce before serving vault content.
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { toBase64 } from './crypto-utils.js';
+/**
+ * Sign a vault store API request with agent's DID identity.
+ *
+ * Creates canonical request representation:
+ * ```
+ * {method}\n{endpoint}\n{timestamp}\n{nonce}\n{bodyHash}
+ * ```
+ *
+ * Server verifies:
+ * 1. Signature matches DID public key
+ * 2. Timestamp within ±5min (prevents replay)
+ * 3. Nonce not seen before (prevents duplicate)
+ * 4. Body hash matches (ensures integrity)
+ *
+ * @param identity - Agent identity (contains signing key)
+ * @param endpoint - API endpoint (e.g., "/api/vault-store/crypto")
+ * @param body - Request body (JSON-serializable)
+ * @returns Signed request metadata or error
+ *
+ * @example
+ * ```typescript
+ * const sigResult = await signVaultRequest(agent.identity, '/api/vault-store/crypto', {
+ *   requestedVersion: 'latest',
+ *   clientVersion: '1.5.0',
+ * });
+ *
+ * if (!sigResult.ok) {
+ *   throw new Error('Failed to sign vault request');
+ * }
+ *
+ * const { signature, timestamp, nonce } = sigResult.value;
+ *
+ * const response = await fetch('https://private.me/api/vault-store/crypto', {
+ *   method: 'POST',
+ *   headers: {
+ *     'X-DID': agent.did,
+ *     'X-Signature': signature,
+ *     'X-Timestamp': timestamp.toString(),
+ *     'X-Nonce': nonce,
+ *   },
+ *   body: JSON.stringify(body),
+ * });
+ * ```
+ */
+export async function signVaultRequest(identity, endpoint, body) {
+    const timestamp = Date.now();
+    const nonce = generateNonce();
+    // Canonical request representation
+    const method = 'POST';
+    const bodyJson = JSON.stringify(body);
+    const bodyHash = await hashString(bodyJson);
+    const canonical = `${method}\n${endpoint}\n${timestamp}\n${nonce}\n${bodyHash}`;
+    // Sign with Ed25519
+    let signatureBuffer;
+    try {
+        const encoder = new TextEncoder();
+        const message = encoder.encode(canonical);
+        signatureBuffer = await crypto.subtle.sign({ name: 'Ed25519' }, identity.privateKey, message);
+    }
+    catch {
+        return err('SIGN_FAILED');
+    }
+    return ok({
+        signature: toBase64(new Uint8Array(signatureBuffer)),
+        timestamp,
+        nonce,
+    });
+}
+/**
+ * Generate cryptographically secure nonce (UUID v4 format).
+ *
+ * @returns Random UUID string
+ */
+function generateNonce() {
+    // Use crypto.randomUUID if available (Node.js 16+, modern browsers)
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback: manual UUID v4 generation
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    // Set version (4) and variant (RFC 4122)
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join('-');
+}
+/**
+ * Hash string with SHA-256 (for request body integrity).
+ *
+ * @param data - String to hash
+ * @returns Base64-encoded hash
+ */
+async function hashString(data) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(data);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
+    return toBase64(new Uint8Array(hashBuffer));
+}
+/**
+ * Verify vault request signature (server-side only).
+ *
+ * Validates:
+ * 1. Signature matches DID public key
+ * 2. Timestamp within ±5min window
+ * 3. Body hash matches
+ *
+ * Note: Nonce verification requires server-side nonce store (not implemented here).
+ *
+ * @param did - Sender DID
+ * @param publicKeyBytes - Ed25519 public key (32 bytes)
+ * @param endpoint - API endpoint
+ * @param body - Request body (JSON string)
+ * @param signature - Base64-encoded signature
+ * @param timestamp - Request timestamp (Unix ms)
+ * @param nonce - Request nonce
+ * @returns True if signature is valid
+ *
+ * @internal Server-side verification only
+ */
+export async function verifyVaultRequest(did, publicKeyBytes, endpoint, body, signature, timestamp, nonce) {
+    // Timestamp verification (±5min window)
+    const now = Date.now();
+    const maxAge = 5 * 60 * 1000; // 5 minutes
+    if (Math.abs(now - timestamp) > maxAge) {
+        return false;
+    }
+    // Reconstruct canonical request
+    const method = 'POST';
+    const bodyHash = await hashString(body);
+    const canonical = `${method}\n${endpoint}\n${timestamp}\n${nonce}\n${bodyHash}`;
+    // Import public key
+    let publicKey;
+    try {
+        // Copy to new ArrayBuffer to avoid SharedArrayBuffer issues
+        const keyBuffer = new ArrayBuffer(publicKeyBytes.byteLength);
+        new Uint8Array(keyBuffer).set(publicKeyBytes);
+        publicKey = await crypto.subtle.importKey('raw', keyBuffer, { name: 'Ed25519' }, false, ['verify']);
+    }
+    catch {
+        return false;
+    }
+    // Verify signature
+    try {
+        const encoder = new TextEncoder();
+        const message = encoder.encode(canonical);
+        const signatureBytes = Uint8Array.from(atob(signature), (c) => c.charCodeAt(0));
+        return await crypto.subtle.verify({ name: 'Ed25519' }, publicKey, signatureBytes, message);
+    }
+    catch {
+        return false;
+    }
+}

package/dist-standalone/vault-store-loader.js

@@ -1 +1,187 @@
-import{ok,err}from"./_deps/shared/index.js";import{signVaultRequest}from"./vault-auth.js";const VAULT_STORE_URL=process.env.VAULT_STORE_URL||"https://private.me/api/vault-store",CACHE_TTL_MS=6048e5;let cryptoCache=null;export async function loadCryptoPackage(identity){if(cryptoCache&&Date.now()<cryptoCache.expiresAt)return ok(cryptoCache.module);const signatureResult=await signVaultRequest(identity,"/api/vault-store/crypto",{requestedVersion:"latest",clientVersion:"1.5.0"});if(!signatureResult.ok)return err("VAULT_AUTH_FAILED");const{signature:signature,timestamp:timestamp,nonce:nonce}=signatureResult.value;let response,vaultData,cryptoModule;try{response=await fetch(`${VAULT_STORE_URL}/crypto`,{method:"POST",headers:{"Content-Type":"application/json","X-DID":identity.did,"X-Signature":signature,"X-Timestamp":timestamp.toString(),"X-Nonce":nonce},body:JSON.stringify({requestedVersion:"latest",clientVersion:"1.5.0"})})}catch(t){return err("VAULT_FETCH_FAILED")}if(!response.ok)return 402===response.status?err("VAULT_QUOTA_EXCEEDED"):401===response.status||403===response.status?err("VAULT_AUTH_FAILED"):451===response.status?err("VAULT_PAYMENT_REQUIRED"):err("VAULT_FETCH_FAILED");try{vaultData=await response.json()}catch{return err("VAULT_INVALID_RESPONSE")}if(!vaultData.cryptoBundle||!vaultData.version)return err("VAULT_INVALID_RESPONSE");try{const bundleCode=atob(vaultData.cryptoBundle),moduleExports=eval(`(function() {\n      const exports = {};\n      ${bundleCode}\n      return exports;\n    })()`);if(cryptoModule=moduleExports,"function"!=typeof cryptoModule.splitXorIDA||"function"!=typeof cryptoModule.reconstructXorIDA)return err("VAULT_LOAD_FAILED")}catch{return err("VAULT_LOAD_FAILED")}const ttlMs=vaultData.cacheTtl?1e3*vaultData.cacheTtl:CACHE_TTL_MS;return cryptoCache={module:cryptoModule,expiresAt:Date.now()+ttlMs,version:vaultData.version},ok(cryptoModule)}export function getCrypto(){return cryptoCache&&Date.now()<cryptoCache.expiresAt?cryptoCache.module:null}export function isCryptoLoaded(){return null!==cryptoCache&&Date.now()<cryptoCache.expiresAt}export function clearCryptoCache(){cryptoCache=null}export function getCacheStatus(){if(!cryptoCache)return{loaded:!1};const t=Date.now();return{loaded:t<cryptoCache.expiresAt,version:cryptoCache.version,expiresAt:cryptoCache.expiresAt,ttlRemaining:Math.max(0,cryptoCache.expiresAt-t)}}
+/**
+ * @module vault-store-loader
+ * Runtime loader for payment-gated crypto packages (Full Control IP protection).
+ *
+ * Fetches XorIDA algorithm from EC2 Vault Store with:
+ * - DID-based authentication (Ed25519 signatures)
+ * - Usage quota verification (Free: 100K/month, Pro: unlimited)
+ * - Memory caching (7-day TTL, session-only)
+ * - Automatic re-fetch on expiration
+ *
+ * Security: Crypto package NEVER bundled in npm. Always fetched at runtime
+ * with payment gate enforcement. Share 2 (Vault Store) completes algorithm.
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { signVaultRequest } from './vault-auth.js';
+/** Vault Store API endpoint (EC2) */
+const VAULT_STORE_URL = process.env.VAULT_STORE_URL || 'https://private.me/api/vault-store';
+/** Cache TTL: 7 days (in milliseconds) */
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** In-memory cache (cleared on process restart) */
+let cryptoCache = null;
+/**
+ * Load crypto package from Vault Store with authentication and caching.
+ *
+ * Flow:
+ * 1. Check cache (if valid, return cached)
+ * 2. Sign vault request with DID
+ * 3. POST to /api/vault-store/crypto
+ * 4. Server verifies: signature + quota + payment
+ * 5. Receive crypto bundle + share2
+ * 6. Evaluate bundle (dynamic import)
+ * 7. Cache for 7 days
+ *
+ * @param identity - Agent identity (for DID signature)
+ * @returns Crypto package exports or error
+ *
+ * @example
+ * ```typescript
+ * const cryptoResult = await loadCryptoPackage(agent.identity);
+ * if (!cryptoResult.ok) {
+ *   if (cryptoResult.error === 'VAULT_QUOTA_EXCEEDED') {
+ *     console.error('Free tier quota exceeded. Upgrade to Pro for unlimited access.');
+ *   }
+ *   throw new Error(cryptoResult.error);
+ * }
+ * const { splitXorIDA, reconstructXorIDA } = cryptoResult.value;
+ * ```
+ */
+export async function loadCryptoPackage(identity) {
+    // Check cache first
+    if (cryptoCache && Date.now() < cryptoCache.expiresAt) {
+        return ok(cryptoCache.module);
+    }
+    // Sign vault request
+    const signatureResult = await signVaultRequest(identity, '/api/vault-store/crypto', {
+        requestedVersion: 'latest',
+        clientVersion: '1.5.0',
+    });
+    if (!signatureResult.ok) {
+        return err('VAULT_AUTH_FAILED');
+    }
+    const { signature, timestamp, nonce } = signatureResult.value;
+    // Fetch from vault store
+    let response;
+    try {
+        response = await fetch(`${VAULT_STORE_URL}/crypto`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-DID': identity.did,
+                'X-Signature': signature,
+                'X-Timestamp': timestamp.toString(),
+                'X-Nonce': nonce,
+            },
+            body: JSON.stringify({
+                requestedVersion: 'latest',
+                clientVersion: '1.5.0',
+            }),
+        });
+    }
+    catch (fetchError) {
+        return err('VAULT_FETCH_FAILED');
+    }
+    // Handle error responses
+    if (!response.ok) {
+        if (response.status === 402) {
+            // Payment Required - quota exceeded
+            return err('VAULT_QUOTA_EXCEEDED');
+        }
+        else if (response.status === 401 || response.status === 403) {
+            // Unauthorized / Forbidden
+            return err('VAULT_AUTH_FAILED');
+        }
+        else if (response.status === 451) {
+            // Unavailable For Legal Reasons - payment required
+            return err('VAULT_PAYMENT_REQUIRED');
+        }
+        return err('VAULT_FETCH_FAILED');
+    }
+    // Parse response
+    let vaultData;
+    try {
+        vaultData = (await response.json());
+    }
+    catch {
+        return err('VAULT_INVALID_RESPONSE');
+    }
+    if (!vaultData.cryptoBundle || !vaultData.version) {
+        return err('VAULT_INVALID_RESPONSE');
+    }
+    // Decode and evaluate bundle
+    let cryptoModule;
+    try {
+        const bundleCode = atob(vaultData.cryptoBundle);
+        // Dynamic evaluation (isolated scope)
+        // eslint-disable-next-line no-eval
+        const moduleExports = eval(`(function() {
+      const exports = {};
+      ${bundleCode}
+      return exports;
+    })()`);
+        cryptoModule = moduleExports;
+        // Validate required exports
+        if (typeof cryptoModule.splitXorIDA !== 'function' ||
+            typeof cryptoModule.reconstructXorIDA !== 'function') {
+            return err('VAULT_LOAD_FAILED');
+        }
+    }
+    catch {
+        return err('VAULT_LOAD_FAILED');
+    }
+    // Cache for 7 days (or server-provided TTL)
+    const ttlMs = vaultData.cacheTtl ? vaultData.cacheTtl * 1000 : CACHE_TTL_MS;
+    cryptoCache = {
+        module: cryptoModule,
+        expiresAt: Date.now() + ttlMs,
+        version: vaultData.version,
+    };
+    return ok(cryptoModule);
+}
+/**
+ * Get cached crypto package without fetching.
+ *
+ * Returns null if cache is empty or expired.
+ * Use loadCryptoPackage() to fetch and cache.
+ *
+ * @returns Cached crypto package or null
+ */
+export function getCrypto() {
+    if (cryptoCache && Date.now() < cryptoCache.expiresAt) {
+        return cryptoCache.module;
+    }
+    return null;
+}
+/**
+ * Check if crypto package is loaded and valid.
+ *
+ * @returns True if crypto is cached and not expired
+ */
+export function isCryptoLoaded() {
+    return cryptoCache !== null && Date.now() < cryptoCache.expiresAt;
+}
+/**
+ * Clear crypto cache (force re-fetch on next load).
+ *
+ * Useful for testing or forcing quota re-verification.
+ */
+export function clearCryptoCache() {
+    cryptoCache = null;
+}
+/**
+ * Get cache status (for debugging).
+ *
+ * @returns Cache metadata or null if empty
+ */
+export function getCacheStatus() {
+    if (!cryptoCache) {
+        return { loaded: false };
+    }
+    const now = Date.now();
+    return {
+        loaded: now < cryptoCache.expiresAt,
+        version: cryptoCache.version,
+        expiresAt: cryptoCache.expiresAt,
+        ttlRemaining: Math.max(0, cryptoCache.expiresAt - now),
+    };
+}

package/dist-standalone/verify.js

@@ -1 +1,16 @@
-export{verify,importPublicKey,didToPublicKeyBytes}from"./identity.js";export{validateEnvelope,deserializeEnvelope,openSignedEnvelope}from"./envelope.js";
+/**
+ * @module verify
+ * Lightweight sub-path export for verification-only use cases.
+ *
+ * Import as `@private.me/xbind/verify` for tree-shaking on edge/serverless:
+ * ```ts
+ * import { verify, importPublicKey, validateEnvelope } from '@private.me/xbind/verify';
+ * ```
+ *
+ * This module re-exports only the functions needed to verify signatures
+ * and validate envelopes — no key generation, no encryption, no transport.
+ */
+// Identity — verify + key import only
+export { verify, importPublicKey, didToPublicKeyBytes } from './identity.js';
+// Envelope — validation + signed envelope verification
+export { validateEnvelope, deserializeEnvelope, openSignedEnvelope, } from './envelope.js';