@private.me/xbind 1.2.0

package/dist-standalone/security-policy.js

@@ -0,0 +1,198 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export 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,
+        };
+    }
+}
+/**
+ * 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.
+ */
+export 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 }
+ * ```
+ */
+export 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/split-channel.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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
+ */
+import type { Result } from '@private.me/shared';
+/** Configuration for split-channel delivery. */
+export interface SplitChannelConfig {
+    /** Total number of shares to produce. Default: 3. */
+    readonly totalShares: number;
+    /** Minimum shares needed for reconstruction. Default: 2. */
+    readonly threshold: number;
+}
+/** Serialized share with metadata for transport. */
+export interface ChannelShare {
+    /** Base64-encoded share data. */
+    readonly data: string;
+    /** Share index (0-based). */
+    readonly index: number;
+    /** Total shares produced. */
+    readonly total: number;
+    /** Threshold for reconstruction. */
+    readonly threshold: number;
+    /** UUID linking all shares of this message. */
+    readonly groupId: string;
+    /** Base64-encoded HMAC key (needed for verification on reconstruct). */
+    readonly hmacKey: string;
+    /** Base64-encoded HMAC signature over the padded plaintext. */
+    readonly hmacSig: string;
+}
+/** Error codes for split-channel operations. Sub-codes give context. */
+export type SplitChannelError = 'SPLIT_FAILED' | 'SPLIT_FAILED:INVALID_PARAMS' | 'SPLIT_FAILED:RECONSTRUCT' | 'INSUFFICIENT_SHARES' | 'INCONSISTENT_SHARES' | 'HMAC_VERIFICATION_FAILED' | 'UNPAD_FAILED' | 'INVALID_SHARE_DATA' | 'INVALID_SHARE_DATA:BASE64' | 'INVALID_SHARE_DATA:HMAC_DECODE';
+/** Default split-channel configuration: 3 shares, threshold 2. */
+export declare const DEFAULT_SPLIT_CONFIG: SplitChannelConfig;
+/**
+ * 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
+ */
+export declare function splitForChannel(plaintext: Uint8Array, config?: SplitChannelConfig): Promise<Result<ChannelShare[], SplitChannelError>>;
+/**
+ * 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
+ */
+export declare function splitForChannelWithGroupId(plaintext: Uint8Array, config: SplitChannelConfig, groupId: string): Promise<Result<ChannelShare[], SplitChannelError>>;
+/**
+ * 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
+ */
+export declare function reconstructFromChannel(shares: readonly ChannelShare[]): Promise<Result<Uint8Array, SplitChannelError>>;

package/dist-standalone/split-channel.js

@@ -0,0 +1,171 @@
+/**
+ * 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
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { splitXorIDA, reconstructXorIDA, nextOddPrime, pkcs7Pad, pkcs7Unpad, generateHMAC, verifyHMAC, toBase64, fromBase64, generateUUID, formatShareHeader, parseShareHeader, } from"./_deps/crypto/index.js";
+/** Default split-channel configuration: 3 shares, threshold 2. */
+export const 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
+ */
+export async function splitForChannel(plaintext, config = DEFAULT_SPLIT_CONFIG) {
+    const { totalShares: n, threshold: k } = config;
+    if (n < 2 || k < 2 || k > n) {
+        return err('SPLIT_FAILED:INVALID_PARAMS');
+    }
+    const groupId = 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
+ */
+export async function splitForChannelWithGroupId(plaintext, config, groupId) {
+    const { totalShares: n, threshold: k } = config;
+    if (n < 2 || k < 2 || k > n) {
+        return err('SPLIT_FAILED:INVALID_PARAMS');
+    }
+    const p = nextOddPrime(n);
+    const blockSize = p - 1;
+    const padded = pkcs7Pad(plaintext, blockSize);
+    const { key: hmacKey, signature: hmacSig } = await generateHMAC(padded);
+    let shareArrays;
+    try {
+        shareArrays = splitXorIDA(padded, n, k);
+    }
+    catch {
+        return err('SPLIT_FAILED');
+    }
+    const hmacKeyB64 = toBase64(hmacKey);
+    const hmacSigB64 = toBase64(hmacSig);
+    const shares = shareArrays.map((data, index) => ({
+        data: formatShareHeader(toBase64(data)),
+        index,
+        total: n,
+        threshold: k,
+        groupId,
+        hmacKey: hmacKeyB64,
+        hmacSig: hmacSigB64,
+    }));
+    return 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
+ */
+export 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 err('INSUFFICIENT_SHARES');
+    }
+    const first = shares[0];
+    const k = first.threshold;
+    const n = first.total;
+    if (shares.length < k) {
+        return err('INSUFFICIENT_SHARES');
+    }
+    const indexSet = new Set();
+    for (const share of shares) {
+        if (share.groupId !== first.groupId) {
+            return err('INCONSISTENT_SHARES');
+        }
+        if (share.total !== n || share.threshold !== k) {
+            return err('INCONSISTENT_SHARES');
+        }
+        if (share.index < 0 || share.index >= n) {
+            return err('INVALID_SHARE_DATA');
+        }
+        if (indexSet.has(share.index)) {
+            return err('INVALID_SHARE_DATA');
+        }
+        indexSet.add(share.index);
+    }
+    return 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) => fromBase64(parseShareHeader(s.data)));
+    }
+    catch {
+        return err('INVALID_SHARE_DATA:BASE64');
+    }
+    const indices = usedShares.map((s) => s.index);
+    let padded;
+    try {
+        padded = reconstructXorIDA(shareData, indices, n, k);
+    }
+    catch {
+        return err('SPLIT_FAILED:RECONSTRUCT');
+    }
+    const first = usedShares[0];
+    let hmacKey;
+    let hmacSig;
+    try {
+        hmacKey = fromBase64(first.hmacKey);
+        hmacSig = fromBase64(first.hmacSig);
+    }
+    catch {
+        return err('INVALID_SHARE_DATA:HMAC_DECODE');
+    }
+    const hmacValid = await verifyHMAC(hmacKey, padded, hmacSig);
+    if (!hmacValid) {
+        return err('HMAC_VERIFICATION_FAILED');
+    }
+    const p = nextOddPrime(n);
+    const blockSize = p - 1;
+    const unpadResult = pkcs7Unpad(padded, blockSize);
+    if (!unpadResult.ok) {
+        return err('UNPAD_FAILED');
+    }
+    return ok(unpadResult.value);
+}

package/dist-standalone/subscription-proof.d.ts

@@ -0,0 +1,103 @@
+import type { Result } from '@private.me/shared';
+/** Error codes for subscription proof operations. */
+export type ProofError = 'INVALID_PROOF' | 'EXPIRED' | 'SIGNATURE_VERIFICATION_FAILED' | 'HASH_FAILED' | 'NETWORK_ERROR' | 'INVALID_DID';
+/**
+ * Subscription proof format (peer-signed).
+ *
+ * Enables gateway portability: clients can resume subscriptions on a new
+ * gateway by presenting a proof that they previously subscribed to a bloom
+ * filter covering specific DIDs.
+ */
+export interface SubscriptionProof {
+    /** Proof type identifier. */
+    readonly type: 'SubscriptionProof';
+    /** Proof format version. */
+    readonly version: '1.0';
+    /** Subscriber's DID (did:key:z6Mk... or did:privateme:...). */
+    readonly peer_did: string;
+    /** SHA-256 hash of the bloom filter (hex string). */
+    readonly bloom_filter_hash: string;
+    /** Unix timestamp (ms) when proof was created. */
+    readonly asserted_at: number;
+    /** Unix timestamp (ms) when proof expires. */
+    readonly expires_at: number;
+    /** Signature algorithm used. */
+    readonly peer_signature_algorithm: 'ML-DSA-65';
+    /** Base64-encoded ML-DSA-65 signature (3309 bytes). */
+    readonly peer_signature: string;
+}
+/**
+ * Create a subscription proof (client-side).
+ *
+ * Signs a bloom filter hash with the peer's ML-DSA-65 private key, creating
+ * a portable proof that can be used to resume subscriptions on a new gateway.
+ *
+ * @param peerDid - Subscriber's DID (must match the private key).
+ * @param bloomFilterHash - SHA-256 hash of the bloom filter (hex string).
+ * @param privateKey - 32-byte ML-DSA-65 secret key seed.
+ * @param expiresAt - Optional expiration timestamp (ms). Default: 30 days from now.
+ * @returns Subscription proof with ML-DSA-65 signature.
+ *
+ * @example
+ * ```typescript
+ * const proof = await createSubscriptionProof(
+ *   'did:key:z6Mk...',
+ *   'a1b2c3...',
+ *   mlDsaPrivateKey,
+ *   Date.now() + 30 * 24 * 60 * 60 * 1000
+ * );
+ * ```
+ */
+export declare function createSubscriptionProof(peerDid: string, bloomFilterHash: string, privateKey: Uint8Array, expiresAt?: number): Promise<Result<SubscriptionProof, ProofError>>;
+/**
+ * Verify a subscription proof (gateway-side).
+ *
+ * Validates the ML-DSA-65 signature and checks expiration.
+ *
+ * @param proof - Subscription proof to verify.
+ * @param peerPublicKey - 1952-byte ML-DSA-65 public key of the subscriber.
+ * @returns true if valid, false if invalid or expired.
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifySubscriptionProof(proof, mlDsaPublicKey);
+ * if (isValid.ok && isValid.value) {
+ *   // Resume subscription
+ * }
+ * ```
+ */
+export declare function verifySubscriptionProof(proof: SubscriptionProof, peerPublicKey: Uint8Array): Promise<Result<boolean, ProofError>>;
+/**
+ * Resume subscription on a new gateway using a proof.
+ *
+ * Presents the subscription proof to the new gateway, allowing the client
+ * to resume receiving trust events without re-subscribing.
+ *
+ * @param proof - Valid subscription proof.
+ * @param newGatewayUrl - Base URL of the new gateway (e.g., https://atelier2.xail.io).
+ * @returns Success or network error.
+ *
+ * @example
+ * ```typescript
+ * const result = await resumeSubscription(proof, 'https://atelier2.xail.io');
+ * if (result.ok) {
+ *   console.log('Subscription resumed on new gateway');
+ * }
+ * ```
+ */
+export declare function resumeSubscription(proof: SubscriptionProof, newGatewayUrl: string): Promise<Result<void, ProofError>>;
+/**
+ * Compute SHA-256 hash of a bloom filter for proof creation.
+ *
+ * @param bloomFilter - Bloom filter bytes.
+ * @returns Hex-encoded SHA-256 hash.
+ *
+ * @example
+ * ```typescript
+ * const hash = await hashBloomFilter(bloomFilterBytes);
+ * if (hash.ok) {
+ *   const proof = await createSubscriptionProof(did, hash.value, privateKey);
+ * }
+ * ```
+ */
+export declare function hashBloomFilter(bloomFilter: Uint8Array): Promise<Result<string, ProofError>>;