@private.me/xbind 1.2.0

package/dist-standalone/cjs/retry-transport.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryTransportAdapter = void 0;
+/* ── Implementation ── */
+/**
+ * Decorator that adds exponential backoff retry logic to any transport adapter.
+ *
+ * Retry delays follow exponential backoff with jitter:
+ * - Formula: 2^attempt * baseDelay + jitter
+ * - Jitter: Math.random() * maxJitter * 2 - maxJitter
+ * - Default delays: 1s, 2s, 4s (with ±200ms jitter)
+ *
+ * Use case: Push notification delivery failures requiring automatic retry.
+ *
+ * @example
+ * ```typescript
+ * const transport = new RetryTransportAdapter(baseTransport, {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
+ *   maxJitterMs: 200
+ * });
+ * ```
+ */
+class RetryTransportAdapter {
+    inner;
+    maxRetries;
+    baseDelayMs;
+    maxJitterMs;
+    /**
+     * Create a new RetryTransportAdapter wrapping an existing transport.
+     *
+     * @param inner - The transport adapter to wrap with retry logic
+     * @param options - Retry configuration options
+     */
+    constructor(inner, options = {}) {
+        this.inner = inner;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.baseDelayMs = options.baseDelayMs ?? 1000;
+        this.maxJitterMs = options.maxJitterMs ?? 200;
+    }
+    /**
+     * Send an envelope with exponential backoff retry logic.
+     *
+     * Retries on all error types (SEND_FAILED, NETWORK_ERROR, RECIPIENT_UNREACHABLE, TIMEOUT).
+     * Throws error after all retries are exhausted.
+     *
+     * @param envelope - The envelope to send
+     * @param recipientDid - The recipient's DID
+     * @returns Result with void on success, or TransportError on failure
+     * @throws Error if all retry attempts are exhausted
+     */
+    async send(envelope, recipientDid) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const result = await this.inner.send(envelope, recipientDid);
+            // Success - return immediately
+            if (result.ok) {
+                return result;
+            }
+            // Store error for final throw
+            lastError = result.error;
+            // Don't delay after final attempt
+            if (attempt < this.maxRetries) {
+                // Exponential backoff: 2^attempt * baseDelay + jitter
+                const delay = Math.pow(2, attempt) * this.baseDelayMs;
+                // SAFETY: Using crypto.getRandomValues for OWASP-compliant secure random jitter
+                const jitterArray = new Uint32Array(1);
+                crypto.getRandomValues(jitterArray);
+                const jitter = (jitterArray[0] / 0xffffffff) * this.maxJitterMs * 2 -
+                    this.maxJitterMs;
+                await this.sleep(delay + jitter);
+            }
+        }
+        // All retries exhausted - throw error with clear message
+        throw new Error(`Failed after ${this.maxRetries} retries: ${lastError ?? 'unknown error'}`);
+    }
+    /**
+     * Register a handler for incoming envelopes.
+     * Delegates directly to the inner transport.
+     *
+     * @param handler - The envelope handler function
+     */
+    onReceive(handler) {
+        this.inner.onReceive(handler);
+    }
+    /**
+     * Shut down the transport.
+     * Delegates directly to the inner transport.
+     */
+    dispose() {
+        this.inner.dispose();
+    }
+    /**
+     * Sleep for a specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.RetryTransportAdapter = RetryTransportAdapter;

package/dist-standalone/cjs/security-policy.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Security policy interface for automatic risk-based Xorida activation.
+ *
+ * Determines when to apply information-theoretic security (XorIDA split-channel)
+ * vs standard encrypted transport based on action semantics and parameters.
+ *
+ * Design principle: Security should be invisible to users. The policy classifies
+ * risk automatically so developers don't need to understand threshold cryptography.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultSecurityPolicy = void 0;
+exports.describeSecurityMode = describeSecurityMode;
+exports.describeSecurityModeStructured = describeSecurityModeStructured;
+/**
+ * Default security policy for basic XBind.
+ *
+ * Rules:
+ * - Transfers over $100,000: High security (3 shares, 2-of-3 threshold)
+ * - Cross-entity communication: High security (3 shares, 2-of-3 threshold)
+ * - Explicit 'high' override: High security (3 shares, 2-of-3 threshold)
+ * - Explicit 'critical' override: Critical security (5 shares, 3-of-5 threshold)
+ * - Everything else: Standard encrypted transport (V3 hybrid PQ)
+ *
+ * Enterprise and Government variants extend this with custom rules.
+ */
+class DefaultSecurityPolicy {
+    options;
+    /**
+     * Create a default security policy.
+     *
+     * @param options - Optional configuration
+     * @param options.highValueThreshold - Amount threshold for high security (default: 100000)
+     * @param options.enableXchange - Allow Xchange mode for performance (default: false)
+     */
+    constructor(options = {}) {
+        this.options = options;
+    }
+    classify(context) {
+        const { action, params, securityOverride } = context;
+        const threshold = this.options.highValueThreshold ?? 100_000;
+        // Explicit override: critical
+        if (securityOverride === 'critical') {
+            return {
+                mode: { type: 'split', shares: 5, threshold: 3 },
+                reason: 'User requested critical security level (5 shares, 3-of-5 threshold)',
+                wasOverridden: true,
+            };
+        }
+        // Explicit override: high
+        if (securityOverride === 'high') {
+            return {
+                mode: { type: 'split', shares: 3, threshold: 2 },
+                reason: 'User requested high security level (3 shares, 2-of-3 threshold)',
+                wasOverridden: true,
+            };
+        }
+        // Explicit override: standard
+        if (securityOverride === 'standard') {
+            return {
+                mode: { type: 'standard' },
+                reason: 'User requested standard security level (encrypted transport)',
+                wasOverridden: true,
+            };
+        }
+        // Auto-detection: High-value transfer
+        if ((action === 'transfer' || action === 'execute') &&
+            typeof params.amount === 'number' &&
+            params.amount > threshold) {
+            return {
+                mode: { type: 'split', shares: 3, threshold: 2 },
+                reason: `High-value transfer ($${params.amount.toLocaleString()}) requires multi-party approval (2 of 3)`,
+                wasOverridden: false,
+            };
+        }
+        // Auto-detection: Cross-entity communication
+        if (params.crossEntity === true) {
+            return {
+                mode: { type: 'split', shares: 3, threshold: 2 },
+                reason: 'Cross-organization communication requires multi-party approval (2 of 3)',
+                wasOverridden: false,
+            };
+        }
+        // Auto-detection: Sensitive scopes
+        if (context.scope.includes('admin') ||
+            context.scope.includes('custody') ||
+            context.scope.includes('settlement')) {
+            return {
+                mode: { type: 'split', shares: 3, threshold: 2 },
+                reason: `Sensitive scope "${context.scope}" requires multi-party approval (2 of 3)`,
+                wasOverridden: false,
+            };
+        }
+        // Xchange mode: opt-in performance mode (if enabled)
+        if (this.options.enableXchange && params.xchange === true) {
+            return {
+                mode: { type: 'xchange' },
+                reason: 'Xchange mode enabled for performance (~180x faster)',
+                wasOverridden: false,
+            };
+        }
+        // Default: Standard encrypted transport
+        return {
+            mode: { type: 'standard' },
+            reason: 'Standard encrypted transport (hybrid post-quantum)',
+            wasOverridden: false,
+        };
+    }
+}
+exports.DefaultSecurityPolicy = DefaultSecurityPolicy;
+/**
+ * Get a human-readable security mode description.
+ *
+ * Used for logging and user feedback.
+ *
+ * @param mode - Security mode
+ * @returns User-friendly description
+ *
+ * @deprecated Use describeSecurityModeStructured() for new code. This function remains for backward compatibility.
+ */
+function describeSecurityMode(mode) {
+    switch (mode.type) {
+        case 'standard':
+            return 'Standard (encrypted)';
+        case 'split':
+            return `Multi-party approval (${mode.threshold} of ${mode.shares})`;
+        case 'xchange':
+            return 'Xchange (fast mode)';
+    }
+}
+/**
+ * Get a structured security mode description with multiple formats.
+ *
+ * Returns an object with the security classification and formatted descriptions
+ * optimized for different use cases (display, logging, APIs, docs).
+ *
+ * @param mode - Security mode
+ * @returns Security mode description with formats
+ *
+ * @example
+ * ```typescript
+ * const mode: SecurityMode = { type: 'split', shares: 3, threshold: 2 };
+ * const description = describeSecurityModeStructured(mode);
+ *
+ * console.log(description.formats.singleline);
+ * // "high | split | 2-of-3"
+ *
+ * console.log(description.formats.multiline);
+ * // "Security Level: High
+ * //  Mode: Split-channel (XorIDA)
+ * //  Shares: 3 total, 2 required"
+ *
+ * console.log(description.shares);
+ * // { total: 3, threshold: 2 }
+ * ```
+ */
+function describeSecurityModeStructured(mode) {
+    let level;
+    let multiline;
+    let singleline;
+    let markdown;
+    let shares;
+    switch (mode.type) {
+        case 'standard':
+            level = 'standard';
+            multiline = 'Security Level: Standard\nMode: Encrypted transport (hybrid post-quantum)';
+            singleline = 'standard | encrypted';
+            markdown = '**Security Level:** Standard\n\n**Mode:** Encrypted transport (hybrid post-quantum)';
+            break;
+        case 'split':
+            // Classify split mode as high or critical based on threshold
+            level = mode.shares >= 5 ? 'critical' : 'high';
+            shares = { total: mode.shares, threshold: mode.threshold };
+            multiline = `Security Level: ${level === 'critical' ? 'Critical' : 'High'}\nMode: Split-channel (XorIDA)\nShares: ${mode.shares} total, ${mode.threshold} required`;
+            singleline = `${level} | split | ${mode.threshold}-of-${mode.shares}`;
+            markdown = `**Security Level:** ${level === 'critical' ? 'Critical' : 'High'}\n\n**Mode:** Split-channel (XorIDA)\n\n**Shares:** ${mode.shares} total, ${mode.threshold} required`;
+            break;
+        case 'xchange':
+            level = 'performance';
+            multiline = 'Security Level: Performance\nMode: Xchange (single IT layer, ~180x faster)';
+            singleline = 'performance | xchange';
+            markdown = '**Security Level:** Performance\n\n**Mode:** Xchange (single IT layer, ~180x faster)';
+            break;
+    }
+    const jsonObj = {
+        type: mode.type,
+        level,
+    };
+    if (shares) {
+        jsonObj.shares = shares;
+    }
+    const json = JSON.stringify(jsonObj);
+    return {
+        type: mode.type,
+        level,
+        shares,
+        formats: {
+            multiline,
+            singleline,
+            json,
+            markdown,
+        },
+    };
+}

package/dist-standalone/cjs/split-channel.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * XorIDA split-channel bridge for @private.me/xbind.
+ *
+ * Bridges @private.me/crypto threshold sharing with the agent-sdk
+ * TransportEnvelope format. Splits plaintext into n shares with HMAC
+ * integrity, each share wrapped in its own envelope for independent routing.
+ *
+ * Pipeline:
+ *   split:  pad -> HMAC -> XorIDA split -> share Uint8Arrays with metadata
+ *   reconstruct: collect k shares -> XorIDA reconstruct -> HMAC verify -> unpad
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SPLIT_CONFIG = void 0;
+exports.splitForChannel = splitForChannel;
+exports.splitForChannelWithGroupId = splitForChannelWithGroupId;
+exports.reconstructFromChannel = reconstructFromChannel;
+const shared_1 = require("../_deps/shared/index.js");
+const crypto_1 = require("../_deps/crypto/index.js");
+/** Default split-channel configuration: 3 shares, threshold 2. */
+exports.DEFAULT_SPLIT_CONFIG = {
+    totalShares: 3,
+    threshold: 2,
+};
+/* ── Split ── */
+/**
+ * Split plaintext into n shares via XorIDA with HMAC integrity.
+ *
+ * Pipeline: pad(PKCS#7) -> HMAC(padded) -> XorIDA split -> ChannelShare[]
+ *
+ * @param plaintext - Raw plaintext bytes to split
+ * @param config - Split configuration (totalShares, threshold)
+ * @returns Array of n ChannelShare objects ready for envelope wrapping
+ */
+async function splitForChannel(plaintext, config = exports.DEFAULT_SPLIT_CONFIG) {
+    const { totalShares: n, threshold: k } = config;
+    if (n < 2 || k < 2 || k > n) {
+        return (0, shared_1.err)('SPLIT_FAILED:INVALID_PARAMS');
+    }
+    const groupId = (0, crypto_1.generateUUID)();
+    return splitForChannelWithGroupId(plaintext, config, groupId);
+}
+/**
+ * Split plaintext with a specific groupId (for testability).
+ *
+ * @param plaintext - Raw plaintext bytes
+ * @param config - Split configuration
+ * @param groupId - UUID to use for the share group
+ * @returns Array of ChannelShare objects
+ */
+async function splitForChannelWithGroupId(plaintext, config, groupId) {
+    const { totalShares: n, threshold: k } = config;
+    if (n < 2 || k < 2 || k > n) {
+        return (0, shared_1.err)('SPLIT_FAILED:INVALID_PARAMS');
+    }
+    const p = (0, crypto_1.nextOddPrime)(n);
+    const blockSize = p - 1;
+    const padded = (0, crypto_1.pkcs7Pad)(plaintext, blockSize);
+    const { key: hmacKey, signature: hmacSig } = await (0, crypto_1.generateHMAC)(padded);
+    let shareArrays;
+    try {
+        shareArrays = (0, crypto_1.splitXorIDA)(padded, n, k);
+    }
+    catch {
+        return (0, shared_1.err)('SPLIT_FAILED');
+    }
+    const hmacKeyB64 = (0, crypto_1.toBase64)(hmacKey);
+    const hmacSigB64 = (0, crypto_1.toBase64)(hmacSig);
+    const shares = shareArrays.map((data, index) => ({
+        data: (0, crypto_1.formatShareHeader)((0, crypto_1.toBase64)(data)),
+        index,
+        total: n,
+        threshold: k,
+        groupId,
+        hmacKey: hmacKeyB64,
+        hmacSig: hmacSigB64,
+    }));
+    return (0, shared_1.ok)(shares);
+}
+/* ── Reconstruct ── */
+/**
+ * Reconstruct plaintext from k-of-n shares.
+ *
+ * Pipeline: validate -> XorIDA reconstruct -> HMAC verify -> unpad -> plaintext
+ * HMAC verification happens BEFORE the data is trusted.
+ *
+ * @param shares - Array of at least k ChannelShare objects
+ * @returns Reconstructed plaintext bytes
+ */
+async function reconstructFromChannel(shares) {
+    const validationResult = validateShares(shares);
+    if (!validationResult.ok)
+        return validationResult;
+    const { k, n } = validationResult.value;
+    const usedShares = shares.slice(0, k);
+    return reconstructValidated(usedShares, n, k);
+}
+/**
+ * Validate share consistency before reconstruction.
+ *
+ * @param shares - Shares to validate
+ * @returns Validated parameters or error
+ */
+function validateShares(shares) {
+    if (shares.length === 0) {
+        return (0, shared_1.err)('INSUFFICIENT_SHARES');
+    }
+    const first = shares[0];
+    const k = first.threshold;
+    const n = first.total;
+    if (shares.length < k) {
+        return (0, shared_1.err)('INSUFFICIENT_SHARES');
+    }
+    const indexSet = new Set();
+    for (const share of shares) {
+        if (share.groupId !== first.groupId) {
+            return (0, shared_1.err)('INCONSISTENT_SHARES');
+        }
+        if (share.total !== n || share.threshold !== k) {
+            return (0, shared_1.err)('INCONSISTENT_SHARES');
+        }
+        if (share.index < 0 || share.index >= n) {
+            return (0, shared_1.err)('INVALID_SHARE_DATA');
+        }
+        if (indexSet.has(share.index)) {
+            return (0, shared_1.err)('INVALID_SHARE_DATA');
+        }
+        indexSet.add(share.index);
+    }
+    return (0, shared_1.ok)({ k, n, groupId: first.groupId });
+}
+/**
+ * Perform XorIDA reconstruction and HMAC verification.
+ *
+ * @param usedShares - Exactly k validated shares
+ * @param n - Total shares
+ * @param k - Threshold
+ * @returns Reconstructed plaintext
+ */
+async function reconstructValidated(usedShares, n, k) {
+    let shareData;
+    try {
+        shareData = usedShares.map((s) => (0, crypto_1.fromBase64)((0, crypto_1.parseShareHeader)(s.data)));
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SHARE_DATA:BASE64');
+    }
+    const indices = usedShares.map((s) => s.index);
+    let padded;
+    try {
+        padded = (0, crypto_1.reconstructXorIDA)(shareData, indices, n, k);
+    }
+    catch {
+        return (0, shared_1.err)('SPLIT_FAILED:RECONSTRUCT');
+    }
+    const first = usedShares[0];
+    let hmacKey;
+    let hmacSig;
+    try {
+        hmacKey = (0, crypto_1.fromBase64)(first.hmacKey);
+        hmacSig = (0, crypto_1.fromBase64)(first.hmacSig);
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SHARE_DATA:HMAC_DECODE');
+    }
+    const hmacValid = await (0, crypto_1.verifyHMAC)(hmacKey, padded, hmacSig);
+    if (!hmacValid) {
+        return (0, shared_1.err)('HMAC_VERIFICATION_FAILED');
+    }
+    const p = (0, crypto_1.nextOddPrime)(n);
+    const blockSize = p - 1;
+    const unpadResult = (0, crypto_1.pkcs7Unpad)(padded, blockSize);
+    if (!unpadResult.ok) {
+        return (0, shared_1.err)('UNPAD_FAILED');
+    }
+    return (0, shared_1.ok)(unpadResult.value);
+}