@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/connection-pool.d.ts

@@ -0,0 +1,251 @@
+/**
+ * @module connection-pool
+ * HTTP connection pooling for xBind registry/gateway requests
+ *
+ * Provides connection reuse, keep-alive support, and automatic cleanup
+ * to enhance performance for applications making frequent requests.
+ *
+ * @example
+ * ```typescript
+ * const pool = new ConnectionPool({
+ *   maxConnections: 50,
+ *   keepAliveTimeout: 30000,
+ * });
+ *
+ * const response = await pool.fetch('https://api.example.com/data');
+ * const data = await response.json();
+ * ```
+ */
+/**
+ * Connection pool configuration options
+ */
+export interface ConnectionPoolOptions {
+    /**
+     * Maximum number of connections per origin
+     * @default 10
+     */
+    maxConnections?: number;
+    /**
+     * Minimum number of idle connections to maintain
+     * @default 2
+     */
+    minConnections?: number;
+    /**
+     * Keep-alive timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    keepAliveTimeout?: number;
+    /**
+     * Maximum time a connection can be idle before cleanup
+     * @default 60000 (60 seconds)
+     */
+    idleTimeout?: number;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    requestTimeout?: number;
+    /**
+     * Enable connection pooling metrics
+     * @default true
+     */
+    enableMetrics?: boolean;
+    /**
+     * Retry failed connections
+     * @default true
+     */
+    retryOnFailure?: boolean;
+    /**
+     * Maximum retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+}
+/**
+ * Connection pool metrics
+ */
+export interface ConnectionPoolMetrics {
+    /** Total number of connections */
+    totalConnections: number;
+    /** Number of active connections */
+    activeConnections: number;
+    /** Number of idle connections */
+    idleConnections: number;
+    /** Total requests served */
+    totalRequests: number;
+    /** Number of connection reuses */
+    reuseCount: number;
+    /** Number of failed requests */
+    failedRequests: number;
+    /** Average request duration in milliseconds */
+    avgRequestDuration: number;
+    /** Connection pool hit rate (0-1) */
+    hitRate: number;
+    /** Metrics by origin */
+    byOrigin: Map<string, {
+        connections: number;
+        requests: number;
+        avgDuration: number;
+    }>;
+}
+/**
+ * Connection pool for HTTP requests
+ *
+ * Manages connection lifecycle, keep-alive, and automatic cleanup
+ * to optimize performance for frequent requests to the same origins.
+ */
+export declare class ConnectionPool {
+    private options;
+    private connections;
+    private metrics;
+    private cleanupInterval;
+    /**
+     * Create a new connection pool
+     *
+     * @param options - Pool configuration options
+     */
+    constructor(options?: ConnectionPoolOptions);
+    /**
+     * Make an HTTP request using the connection pool
+     *
+     * @param url - Target URL
+     * @param init - Fetch options
+     * @returns Response promise
+     *
+     * @example
+     * ```typescript
+     * const response = await pool.fetch('https://api.example.com/data', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ key: 'value' }),
+     * });
+     * ```
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Retry a failed request with exponential backoff
+     */
+    private retryRequest;
+    /**
+     * Acquire a connection from the pool or create a new one
+     */
+    private acquireConnection;
+    /**
+     * Wait for a connection to become available
+     */
+    private waitForConnection;
+    /**
+     * Create a new connection
+     */
+    private createConnection;
+    /**
+     * Get origin from URL
+     */
+    private getOrigin;
+    /**
+     * Record request metrics
+     */
+    private recordMetrics;
+    /**
+     * Get connection pool metrics
+     *
+     * @returns Current metrics snapshot
+     *
+     * @example
+     * ```typescript
+     * const metrics = pool.getMetrics();
+     * console.log(`Hit rate: ${(metrics.hitRate * 100).toFixed(1)}%`);
+     * console.log(`Avg duration: ${metrics.avgRequestDuration}ms`);
+     * ```
+     */
+    getMetrics(): ConnectionPoolMetrics;
+    /**
+     * Reset metrics counters
+     *
+     * @example
+     * ```typescript
+     * pool.resetMetrics();
+     * // Start fresh measurements
+     * ```
+     */
+    resetMetrics(): void;
+    /**
+     * Start automatic connection cleanup
+     */
+    private startCleanup;
+    /**
+     * Clean up idle and expired connections
+     */
+    private cleanup;
+    /**
+     * Manually trigger connection cleanup
+     *
+     * @example
+     * ```typescript
+     * // Force cleanup of idle connections
+     * pool.cleanupNow();
+     * ```
+     */
+    cleanupNow(): void;
+    /**
+     * Close all connections and shutdown the pool
+     *
+     * @example
+     * ```typescript
+     * // Cleanup on application shutdown
+     * await pool.close();
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Get the number of connections for a specific origin
+     *
+     * @param origin - Target origin (e.g., "https://api.example.com")
+     * @returns Number of connections
+     *
+     * @example
+     * ```typescript
+     * const count = pool.getConnectionCount('https://api.example.com');
+     * console.log(`Active connections: ${count}`);
+     * ```
+     */
+    getConnectionCount(origin: string): number;
+    /**
+     * Get all origins with active connections
+     *
+     * @returns Array of origins
+     *
+     * @example
+     * ```typescript
+     * const origins = pool.getOrigins();
+     * console.log(`Connected to ${origins.length} origins`);
+     * ```
+     */
+    getOrigins(): string[];
+    /**
+     * Check if the pool is healthy
+     *
+     * @returns True if pool is operating normally
+     *
+     * @example
+     * ```typescript
+     * if (!pool.isHealthy()) {
+     *   console.warn('Connection pool degraded');
+     * }
+     * ```
+     */
+    isHealthy(): boolean;
+}
+export declare function getGlobalPool(options?: ConnectionPoolOptions): ConnectionPool;
+/**
+ * Reset the global connection pool
+ *
+ * Closes the current pool and allows a new one to be created.
+ *
+ * @example
+ * ```typescript
+ * await resetGlobalPool();
+ * // Next getGlobalPool() call will create a fresh instance
+ * ```
+ */
+export declare function resetGlobalPool(): Promise<void>;

package/dist-standalone/connection-pool.js

@@ -0,0 +1 @@
+export class ConnectionPool{options;connections=new Map;metrics;cleanupInterval=null;constructor(t={}){this.options={maxConnections:t.maxConnections??10,minConnections:t.minConnections??2,keepAliveTimeout:t.keepAliveTimeout??3e4,idleTimeout:t.idleTimeout??6e4,requestTimeout:t.requestTimeout??3e4,enableMetrics:t.enableMetrics??!0,retryOnFailure:t.retryOnFailure??!0,maxRetries:t.maxRetries??3},this.metrics={totalRequests:0,reuseCount:0,failedRequests:0,requestDurations:[],byOrigin:new Map},this.startCleanup()}async fetch(t,e){const s=Date.now(),n=this.getOrigin(t);try{const o=await this.acquireConnection(n);this.options.enableMetrics&&(this.metrics.totalRequests++,o.requestCount>0&&this.metrics.reuseCount++);const i={...e,signal:e?.signal??o.controller.signal,keepalive:!0},r=await fetch(t,i);if(o.requestCount++,o.lastUsedAt=Date.now(),o.state="idle",this.options.enableMetrics){const t=Date.now()-s;this.recordMetrics(n,t)}return r}catch(s){if(this.options.enableMetrics&&this.metrics.failedRequests++,this.options.retryOnFailure&&!0!==e?.signal?.aborted)return this.retryRequest(t,e,1);throw s}}async retryRequest(t,e,s){if(s>this.options.maxRetries)throw new Error(`Request failed after ${this.options.maxRetries} retries: ${t}`);const n=100*Math.pow(2,s-1);await new Promise(t=>setTimeout(t,n));const o=this.getOrigin(t);try{const s=await this.acquireConnection(o),n={...e,signal:e?.signal??s.controller.signal,keepalive:!0},i=await fetch(t,n);return s.requestCount++,s.lastUsedAt=Date.now(),s.state="idle",i}catch(n){if(s>=this.options.maxRetries)throw new Error(`Request failed after ${this.options.maxRetries} retries: ${t}`);return this.retryRequest(t,e,s+1)}}async acquireConnection(t){let e=this.connections.get(t);e||(e=[],this.connections.set(t,e));const s=e.find(t=>"idle"===t.state);if(s)return s.state="active",s;if(e.length<this.options.maxConnections){const s=this.createConnection(t);return e.push(s),s}return this.waitForConnection(t)}async waitForConnection(t){const e=Date.now(),s=this.options.requestTimeout;for(;Date.now()-e<s;){const e=this.connections.get(t);if(!e)throw new Error(`Connection pool for ${t} disappeared`);const s=e.find(t=>"idle"===t.state);if(s)return s.state="active",s;await new Promise(t=>setTimeout(t,10))}throw new Error(`Timeout waiting for connection to ${t} after ${s}ms`)}createConnection(t){const e=new Uint8Array(8);crypto.getRandomValues(e);return{id:`conn_${Array.from(e).map(t=>t.toString(16).padStart(2,"0")).join("")}`,origin:t,createdAt:Date.now(),lastUsedAt:Date.now(),requestCount:0,state:"active",controller:new AbortController}}getOrigin(t){try{const e=new URL(t);return`${e.protocol}//${e.host}`}catch(e){throw new Error(`Invalid URL: ${t}`)}}recordMetrics(t,e){this.metrics.requestDurations.push(e),this.metrics.requestDurations.length>1e3&&this.metrics.requestDurations.shift();let s=this.metrics.byOrigin.get(t);s||(s={requests:0,durations:[]},this.metrics.byOrigin.set(t,s)),s.requests++,s.durations.push(e),s.durations.length>100&&s.durations.shift()}getMetrics(){let t=0,e=0,s=0;const n=new Map;for(const[o,i]of this.connections.entries()){t+=i.length,e+=i.filter(t=>"active"===t.state).length,s+=i.filter(t=>"idle"===t.state).length;const r=this.metrics.byOrigin.get(o);if(r){const t=r.durations.length>0?r.durations.reduce((t,e)=>t+e,0)/r.durations.length:0;n.set(o,{connections:i.length,requests:r.requests,avgDuration:Math.round(t)})}}const o=this.metrics.requestDurations.length>0?Math.round(this.metrics.requestDurations.reduce((t,e)=>t+e,0)/this.metrics.requestDurations.length):0,i=this.metrics.totalRequests>0?this.metrics.reuseCount/this.metrics.totalRequests:0;return{totalConnections:t,activeConnections:e,idleConnections:s,totalRequests:this.metrics.totalRequests,reuseCount:this.metrics.reuseCount,failedRequests:this.metrics.failedRequests,avgRequestDuration:o,hitRate:i,byOrigin:n}}resetMetrics(){this.metrics={totalRequests:0,reuseCount:0,failedRequests:0,requestDurations:[],byOrigin:new Map}}startCleanup(){this.cleanupInterval=setInterval(()=>{this.cleanup()},1e4)}cleanup(){const t=Date.now();for(const[e,s]of this.connections.entries()){const n=s.filter(e=>t-e.lastUsedAt>this.options.idleTimeout&&"idle"===e.state?(e.controller.abort(),e.state="closed",!1):"closed"!==e.state);for(;n.length<this.options.minConnections&&n.length<this.options.maxConnections;){const t=this.createConnection(e);t.state="idle",n.push(t)}n.length>0?this.connections.set(e,n):this.connections.delete(e)}}cleanupNow(){this.cleanup()}async close(){this.cleanupInterval&&(clearInterval(this.cleanupInterval),this.cleanupInterval=null);for(const[t,e]of this.connections.entries())for(const t of e)t.controller.abort(),t.state="closed";this.connections.clear()}getConnectionCount(t){const e=this.connections.get(t);return e?e.length:0}getOrigins(){return Array.from(this.connections.keys())}isHealthy(){const t=this.getMetrics();return!((t.totalRequests>0?t.failedRequests/t.totalRequests:0)>.1)&&!(t.avgRequestDuration>5e3)}}let globalPool=null;export function getGlobalPool(t){return globalPool||(globalPool=new ConnectionPool(t)),globalPool}export async function resetGlobalPool(){globalPool&&(await globalPool.close(),globalPool=null)}

package/dist-standalone/correlation-id.js

@@ -1,326 +1 @@
-/**
- * @module correlation-id
- * Client-side correlation ID utilities for request tracking
- *
- * Correlation IDs enable distributed tracing across xBind agent operations,
- * making it easier to debug issues, track requests across microservices,
- * and correlate logs between client and server.
- *
- * Format: `req_{timestamp}_{random}`
- * Example: `req_1716234567890_a3f5c9d2`
- *
- * Usage:
- * ```typescript
- * import { generateCorrelationId, attachCorrelationId } from '@private.me/xbind';
- *
- * // Generate a new correlation ID
- * const id = generateCorrelationId();
- *
- * // Attach to request headers
- * const headers = attachCorrelationId(new Headers(), id);
- *
- * // Validate format
- * if (validateCorrelationId(id)) {
- *   console.log('Valid correlation ID');
- * }
- * ```
- */
-/**
- * Standard header name for correlation ID
- */
-export const CORRELATION_ID_HEADER = 'X-Correlation-ID';
-/**
- * Alternative header names for compatibility
- */
-export const CORRELATION_ID_ALIASES = [
-    'X-Request-ID',
-    'X-Trace-ID',
-    'X-Transaction-ID',
-];
-/**
- * Regular expression for validating correlation ID format
- */
-const CORRELATION_ID_PATTERN = /^req_\d{13}_[a-f0-9]{8}$/;
-/**
- * Generate a new correlation ID
- *
- * Format: `req_{timestamp}_{random}`
- * - `req`: Static prefix for identification
- * - `timestamp`: Unix timestamp in milliseconds (13 digits)
- * - `random`: 8-character hex string for uniqueness
- *
- * @returns New correlation ID string
- *
- * @example
- * ```typescript
- * const id = generateCorrelationId();
- * // => "req_1716234567890_a3f5c9d2"
- * ```
- */
-export function generateCorrelationId() {
-    const timestamp = Date.now();
-    const random = generateRandomHex(8);
-    return `req_${timestamp}_${random}`;
-}
-/**
- * Validate correlation ID format
- *
- * Checks if the provided string matches the expected correlation ID format.
- *
- * @param id - String to validate
- * @returns True if valid, false otherwise
- *
- * @example
- * ```typescript
- * validateCorrelationId('req_1716234567890_a3f5c9d2'); // => true
- * validateCorrelationId('invalid'); // => false
- * validateCorrelationId('req_123_abc'); // => false (wrong lengths)
- * ```
- */
-export function validateCorrelationId(id) {
-    if (typeof id !== 'string')
-        return false;
-    return CORRELATION_ID_PATTERN.test(id);
-}
-/**
- * Parse correlation ID into components
- *
- * Extracts the timestamp and random components from a correlation ID.
- *
- * @param id - Correlation ID to parse
- * @returns Parsed components or null if invalid
- *
- * @example
- * ```typescript
- * const spec = parseCorrelationId('req_1716234567890_a3f5c9d2');
- * // => { prefix: 'req', timestamp: 1716234567890, random: 'a3f5c9d2' }
- * ```
- */
-export function parseCorrelationId(id) {
-    if (!validateCorrelationId(id))
-        return null;
-    const parts = id.split('_');
-    return {
-        prefix: parts[0] ?? 'req',
-        timestamp: parseInt(parts[1] ?? '0', 10),
-        random: parts[2] ?? '',
-    };
-}
-/**
- * Attach correlation ID to request headers
- *
- * Adds the correlation ID to the X-Correlation-ID header.
- * If no ID is provided, generates a new one.
- * Compatible with both Headers API and plain objects.
- *
- * @param headers - Headers object or plain object
- * @param id - Correlation ID (generates new if not provided)
- * @returns Updated headers object
- *
- * @example
- * ```typescript
- * // With Headers API
- * const headers = new Headers();
- * attachCorrelationId(headers);
- *
- * // With plain object
- * const headers = { 'Content-Type': 'application/json' };
- * attachCorrelationId(headers, 'req_1716234567890_a3f5c9d2');
- *
- * // With existing correlation ID
- * const id = generateCorrelationId();
- * attachCorrelationId(headers, id);
- * ```
- */
-export function attachCorrelationId(headers, id) {
-    const correlationId = id ?? generateCorrelationId();
-    if (!validateCorrelationId(correlationId)) {
-        throw new Error(`Invalid correlation ID format: ${correlationId}. Expected format: req_{timestamp}_{random}`);
-    }
-    if (headers instanceof Headers) {
-        headers.set(CORRELATION_ID_HEADER, correlationId);
-    }
-    else {
-        headers[CORRELATION_ID_HEADER] = correlationId;
-    }
-    return headers;
-}
-/**
- * Extract correlation ID from request headers
- *
- * Checks the standard header and common aliases.
- *
- * @param headers - Headers object or plain object
- * @returns Correlation ID if found, undefined otherwise
- *
- * @example
- * ```typescript
- * const headers = new Headers({
- *   'X-Correlation-ID': 'req_1716234567890_a3f5c9d2'
- * });
- * const id = extractCorrelationId(headers);
- * // => 'req_1716234567890_a3f5c9d2'
- * ```
- */
-export function extractCorrelationId(headers) {
-    // Check primary header
-    const primary = headers instanceof Headers
-        ? headers.get(CORRELATION_ID_HEADER)
-        : headers[CORRELATION_ID_HEADER];
-    if (primary && validateCorrelationId(primary)) {
-        return primary;
-    }
-    // Check aliases
-    for (const alias of CORRELATION_ID_ALIASES) {
-        const value = headers instanceof Headers ? headers.get(alias) : headers[alias];
-        if (value && validateCorrelationId(value)) {
-            return value;
-        }
-    }
-    return undefined;
-}
-/**
- * Get or create correlation ID from headers
- *
- * Returns existing correlation ID from headers, or generates a new one if not found.
- * Does NOT modify the input headers.
- *
- * @param headers - Headers to check
- * @returns Existing or new correlation ID
- *
- * @example
- * ```typescript
- * const headers = new Headers();
- * const id = getOrCreateCorrelationId(headers);
- * // => Generates new ID if not found in headers
- * ```
- */
-export function getOrCreateCorrelationId(headers) {
-    if (!headers)
-        return generateCorrelationId();
-    const existing = extractCorrelationId(headers);
-    return existing ?? generateCorrelationId();
-}
-/**
- * Create a correlation ID from a timestamp
- *
- * Useful for testing or when you need deterministic IDs.
- *
- * @param timestamp - Unix timestamp in milliseconds
- * @param random - Optional random component (generates if not provided)
- * @returns Correlation ID
- *
- * @example
- * ```typescript
- * const id = createCorrelationIdFromTimestamp(1716234567890);
- * // => 'req_1716234567890_a3f5c9d2'
- *
- * const deterministicId = createCorrelationIdFromTimestamp(1716234567890, 'aaaaaaaa');
- * // => 'req_1716234567890_aaaaaaaa'
- * ```
- */
-export function createCorrelationIdFromTimestamp(timestamp, random) {
-    const randomComponent = random ?? generateRandomHex(8);
-    if (!/^[a-f0-9]{8}$/.test(randomComponent)) {
-        throw new Error(`Invalid random component: ${randomComponent}. Expected 8 hex characters`);
-    }
-    return `req_${timestamp}_${randomComponent}`;
-}
-/**
- * Calculate age of correlation ID in milliseconds
- *
- * @param id - Correlation ID
- * @returns Age in milliseconds, or null if invalid
- *
- * @example
- * ```typescript
- * const id = generateCorrelationId();
- * setTimeout(() => {
- *   const age = getCorrelationIdAge(id);
- *   console.log(`Request age: ${age}ms`);
- * }, 1000);
- * ```
- */
-export function getCorrelationIdAge(id) {
-    const spec = parseCorrelationId(id);
-    if (!spec)
-        return null;
-    const now = Date.now();
-    return now - spec.timestamp;
-}
-/**
- * Check if correlation ID is expired
- *
- * @param id - Correlation ID
- * @param maxAgeMs - Maximum age in milliseconds (default: 5 minutes)
- * @returns True if expired, false otherwise
- *
- * @example
- * ```typescript
- * const id = generateCorrelationId();
- * if (isCorrelationIdExpired(id, 60000)) {
- *   console.log('Request older than 1 minute');
- * }
- * ```
- */
-export function isCorrelationIdExpired(id, maxAgeMs = 5 * 60 * 1000) {
-    const age = getCorrelationIdAge(id);
-    return age !== null && age > maxAgeMs;
-}
-/**
- * Generate random hex string
- *
- * Uses Web Crypto API in browser, Node.js crypto in Node.
- * Falls back to Math.random() if neither available (NOT cryptographically secure).
- *
- * @param length - Number of hex characters to generate
- * @returns Random hex string
- *
- * @internal
- */
-function generateRandomHex(length) {
-    const bytes = Math.ceil(length / 2);
-    // Try Web Crypto API (browser)
-    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-        const buffer = new Uint8Array(bytes);
-        crypto.getRandomValues(buffer);
-        return Array.from(buffer)
-            .map((b) => b.toString(16).padStart(2, '0'))
-            .join('')
-            .substring(0, length);
-    }
-    // Try Node.js crypto
-    try {
-        const nodeCrypto = require('node:crypto');
-        return nodeCrypto.randomBytes(bytes).toString('hex').substring(0, length);
-    }
-    catch {
-        // SECURITY: Never fall back to Math.random() in production (OWASP violation)
-        // Correlation IDs must be cryptographically random to prevent enumeration attacks
-        throw new Error('Cryptographic random generation unavailable. ' +
-            'Install crypto polyfill or use environment with crypto support.');
-    }
-}
-/**
- * Middleware helper for Express/Koa-style frameworks
- *
- * Automatically attaches correlation ID to incoming requests.
- *
- * @example
- * ```typescript
- * import express from 'express';
- * import { correlationIdMiddleware } from '@private.me/xbind';
- *
- * const app = express();
- * app.use(correlationIdMiddleware());
- * ```
- */
-export function correlationIdMiddleware() {
-    return (req, res, next) => {
-        const id = getOrCreateCorrelationId(req.headers);
-        req.correlationId = id;
-        res.setHeader(CORRELATION_ID_HEADER, id);
-        if (typeof next === 'function')
-            next();
-    };
-}
+export const CORRELATION_ID_HEADER="X-Correlation-ID";export const CORRELATION_ID_ALIASES=["X-Request-ID","X-Trace-ID","X-Transaction-ID"];const CORRELATION_ID_PATTERN=/^req_\d{13}_[a-f0-9]{8}$/;export function generateCorrelationId(){return`req_${Date.now()}_${generateRandomHex(8)}`}export function validateCorrelationId(r){return"string"==typeof r&&CORRELATION_ID_PATTERN.test(r)}export function parseCorrelationId(r){if(!validateCorrelationId(r))return null;const e=r.split("_");return{prefix:e[0]??"req",timestamp:parseInt(e[1]??"0",10),random:e[2]??""}}export function attachCorrelationId(r,e){const t=e??generateCorrelationId();if(!validateCorrelationId(t))throw new Error(`Invalid correlation ID format: ${t}. Expected format: req_{timestamp}_{random}`);return r instanceof Headers?r.set("X-Correlation-ID",t):r["X-Correlation-ID"]=t,r}export function extractCorrelationId(r){const e=r instanceof Headers?r.get("X-Correlation-ID"):r["X-Correlation-ID"];if(e&&validateCorrelationId(e))return e;for(const e of CORRELATION_ID_ALIASES){const t=r instanceof Headers?r.get(e):r[e];if(t&&validateCorrelationId(t))return t}}export function getOrCreateCorrelationId(r){if(!r)return generateCorrelationId();return extractCorrelationId(r)??generateCorrelationId()}export function createCorrelationIdFromTimestamp(r,e){const t=e??generateRandomHex(8);if(!/^[a-f0-9]{8}$/.test(t))throw new Error(`Invalid random component: ${t}. Expected 8 hex characters`);return`req_${r}_${t}`}export function getCorrelationIdAge(r){const e=parseCorrelationId(r);if(!e)return null;return Date.now()-e.timestamp}export function isCorrelationIdExpired(r,e=3e5){const t=getCorrelationIdAge(r);return null!==t&&t>e}function generateRandomHex(r){const e=Math.ceil(r/2);if("undefined"!=typeof crypto&&crypto.getRandomValues){const t=new Uint8Array(e);return crypto.getRandomValues(t),Array.from(t).map(r=>r.toString(16).padStart(2,"0")).join("").substring(0,r)}try{return require("node:crypto").randomBytes(e).toString("hex").substring(0,r)}catch{throw new Error("Cryptographic random generation unavailable. Install crypto polyfill or use environment with crypto support.")}}export function correlationIdMiddleware(){return(r,e,t)=>{const o=getOrCreateCorrelationId(r.headers);r.correlationId=o,e.setHeader("X-Correlation-ID",o),"function"==typeof t&&t()}}

package/dist-standalone/crypto-utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module crypto-utils
+ * Local crypto utilities (non-IP, safe for npm distribution).
+ *
+ * These are NOT proprietary - just standard Web Crypto API wrappers.
+ * The proprietary XorIDA algorithm is vault-gated via vault-store-loader.ts.
+ */
+/** Convert Uint8Array to Base64 string */
+export declare function toBase64(data: Uint8Array): string;
+/** Convert Base64 string to Uint8Array */
+export declare function fromBase64(base64: string): Uint8Array;
+/** Convert Uint8Array to Base64URL string (URL-safe) */
+export declare function toBase64Url(data: Uint8Array): string;
+/** Convert Base64URL string to Uint8Array */
+export declare function fromBase64Url(base64url: string): Uint8Array;
+/** Generate a UUID v4 (random) */
+export declare function generateUUID(): string;
+/**
+ * Wrap share data with branded IDA5 copyright header.
+ * @param data - Base64-encoded share data
+ * @returns Branded string with copyright header
+ */
+export declare function formatShareHeader(data: string): string;
+/**
+ * Extract share data from branded IDA5 header.
+ * @param input - Branded share string or legacy raw data
+ * @returns Extracted share data
+ */
+export declare function parseShareHeader(input: string): string;
+/** Check if string has branded IDA5 share header */
+export declare function hasShareHeader(input: string): boolean;
+/**
+ * Vault-gated XorIDA functions (loaded dynamically from payment-gated Vault Store).
+ * These are re-exported from vault-store-loader for convenience.
+ */
+import { getCrypto, loadCryptoPackage, isCryptoLoaded } from './vault-store-loader.js';
+/** Split data using XorIDA (vault-gated, requires payment) */
+export declare function splitXorIDA(data: Uint8Array, totalShares: number, requiredShares: number): Uint8Array[];
+/** Reconstruct data from XorIDA shares (vault-gated, requires payment) */
+export declare function reconstructXorIDA(shares: Uint8Array[], indices: number[], requiredShares: number, totalShares: number): Uint8Array;
+/** Get next odd prime >= n (vault-gated utility) */
+export declare function nextOddPrime(n: number): number;
+/** PKCS7 padding (vault-gated utility) */
+export declare function pkcs7Pad(data: Uint8Array, blockSize: number): Uint8Array;
+/** PKCS7 unpadding (vault-gated utility) */
+export declare function pkcs7Unpad(data: Uint8Array, blockSize: number): {
+    ok: true;
+    value: Uint8Array;
+} | {
+    ok: false;
+    error: unknown;
+};
+/** Generate HMAC-SHA256 (vault-gated utility) */
+export declare function generateHMAC(data: Uint8Array): Promise<{
+    key: Uint8Array;
+    signature: Uint8Array;
+}>;
+/** Verify HMAC-SHA256 (vault-gated utility) */
+export declare function verifyHMAC(key: Uint8Array, data: Uint8Array, expectedHmac: Uint8Array): Promise<boolean>;
+export { loadCryptoPackage, getCrypto, isCryptoLoaded };

package/dist-standalone/crypto-utils.js

@@ -0,0 +1 @@
+export function toBase64(r){if("undefined"!=typeof Buffer)return Buffer.from(r).toString("base64");const t=String.fromCharCode(...r);return btoa(t)}export function fromBase64(r){if("undefined"!=typeof Buffer)return new Uint8Array(Buffer.from(r,"base64"));const t=atob(r),e=new Uint8Array(t.length);for(let r=0;r<t.length;r++)e[r]=t.charCodeAt(r);return e}export function toBase64Url(r){return toBase64(r).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}export function fromBase64Url(r){let t=r.replace(/-/g,"+").replace(/_/g,"/");for(;t.length%4;)t+="=";return fromBase64(t)}export function generateUUID(){if("undefined"!=typeof crypto&&crypto.randomUUID)return crypto.randomUUID();const r=new Uint8Array(16);crypto.getRandomValues(r),r[6]=15&r[6]|64,r[8]=63&r[8]|128;const t=Array.from(r).map(r=>r.toString(16).padStart(2,"0")).join("");return`${t.substring(0,8)}-${t.substring(8,12)}-${t.substring(12,16)}-${t.substring(16,20)}-${t.substring(20)}`}const START_MARKER="Encrypted://",END_MARKER="=> Generated by Xecret (TM)",BRAND_PREFIX="Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> ";export function formatShareHeader(r){return`${BRAND_PREFIX}${START_MARKER} ${r} ${END_MARKER}`}export function parseShareHeader(r){const t=r.indexOf(START_MARKER);if(t<0)return r.trim();const e=t+12,o=r.indexOf(END_MARKER,e);return o<0?r.trim():r.substring(e,o).trim()}export function hasShareHeader(r){return r.includes(START_MARKER)&&r.includes(END_MARKER)}import{getCrypto,loadCryptoPackage,isCryptoLoaded}from"./vault-store-loader.js";export function splitXorIDA(r,t,e){const o=getCrypto();if(!o)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return o.splitXorIDA(r,t,e)}export function reconstructXorIDA(r,t,e,o){const n=getCrypto();if(!n)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return n.reconstructXorIDA(r,t,e,o)}export function nextOddPrime(r){const t=getCrypto();if(!t)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return t.nextOddPrime(r)}export function pkcs7Pad(r,t){const e=getCrypto();if(!e)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return e.pkcs7Pad(r,t)}export function pkcs7Unpad(r,t){const e=getCrypto();if(!e)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return e.pkcs7Unpad(r,t)}export async function generateHMAC(r){const t=getCrypto();if(!t)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return t.generateHMAC(r)}export async function verifyHMAC(r,t,e){const o=getCrypto();if(!o)throw new Error("Crypto package not loaded. Call loadCryptoPackage() first.");return o.verifyHMAC(r,t,e)}export{loadCryptoPackage,getCrypto,isCryptoLoaded};