@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/correlation-id.js

@@ -1 +1,326 @@
-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()}}
+/**
+ * @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();
+    };
+}

package/dist-standalone/crypto-utils.js

@@ -1 +1,157 @@
-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};
+/**
+ * @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 function toBase64(data) {
+    if (typeof Buffer !== 'undefined') {
+        // Node.js
+        return Buffer.from(data).toString('base64');
+    }
+    // Browser
+    const binary = String.fromCharCode(...data);
+    return btoa(binary);
+}
+/** Convert Base64 string to Uint8Array */
+export function fromBase64(base64) {
+    if (typeof Buffer !== 'undefined') {
+        // Node.js
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    }
+    // Browser
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/** Convert Uint8Array to Base64URL string (URL-safe) */
+export function toBase64Url(data) {
+    return toBase64(data).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+/** Convert Base64URL string to Uint8Array */
+export function fromBase64Url(base64url) {
+    // Add back padding
+    let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4) {
+        base64 += '=';
+    }
+    return fromBase64(base64);
+}
+/** Generate a UUID v4 (random) */
+export function generateUUID() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback implementation
+    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.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+}
+/**
+ * Branded share header — IDA5 copyright layer.
+ * Wraps XorIDA share output with patent-locked branded string.
+ *
+ * Format: Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> Encrypted:// [data] => Generated by Xecret (TM)
+ */
+const START_MARKER = 'Encrypted://';
+const END_MARKER = '=> Generated by Xecret (TM)';
+const BRAND_PREFIX = 'Xecret (TM) -> PRIVATE .ME (R) -> IDA5 -> ';
+/**
+ * Wrap share data with branded IDA5 copyright header.
+ * @param data - Base64-encoded share data
+ * @returns Branded string with copyright header
+ */
+export function formatShareHeader(data) {
+    return `${BRAND_PREFIX}${START_MARKER} ${data} ${END_MARKER}`;
+}
+/**
+ * Extract share data from branded IDA5 header.
+ * @param input - Branded share string or legacy raw data
+ * @returns Extracted share data
+ */
+export function parseShareHeader(input) {
+    const startIdx = input.indexOf(START_MARKER);
+    if (startIdx < 0)
+        return input.trim();
+    const dataStart = startIdx + START_MARKER.length;
+    const endIdx = input.indexOf(END_MARKER, dataStart);
+    if (endIdx < 0)
+        return input.trim();
+    return input.substring(dataStart, endIdx).trim();
+}
+/** Check if string has branded IDA5 share header */
+export function hasShareHeader(input) {
+    return input.includes(START_MARKER) && input.includes(END_MARKER);
+}
+/**
+ * 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 function splitXorIDA(data, totalShares, requiredShares) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.splitXorIDA(data, totalShares, requiredShares);
+}
+/** Reconstruct data from XorIDA shares (vault-gated, requires payment) */
+export function reconstructXorIDA(shares, indices, requiredShares, totalShares) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.reconstructXorIDA(shares, indices, requiredShares, totalShares);
+}
+/** Get next odd prime >= n (vault-gated utility) */
+export function nextOddPrime(n) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.nextOddPrime(n);
+}
+/** PKCS7 padding (vault-gated utility) */
+export function pkcs7Pad(data, blockSize) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.pkcs7Pad(data, blockSize);
+}
+/** PKCS7 unpadding (vault-gated utility) */
+export function pkcs7Unpad(data, blockSize) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.pkcs7Unpad(data, blockSize);
+}
+/** Generate HMAC-SHA256 (vault-gated utility) */
+export async function generateHMAC(data) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.generateHMAC(data);
+}
+/** Verify HMAC-SHA256 (vault-gated utility) */
+export async function verifyHMAC(key, data, expectedHmac) {
+    const crypto = getCrypto();
+    if (!crypto) {
+        throw new Error('Crypto package not loaded. Call loadCryptoPackage() first.');
+    }
+    return crypto.verifyHMAC(key, data, expectedHmac);
+}
+// Re-export vault loader functions for convenience
+export { loadCryptoPackage, getCrypto, isCryptoLoaded };