@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/security-policy.js

@@ -1,239 +1 @@
-/**
- * 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:
- * - Explicit risk tags: low → 2-of-2, medium → 2-of-3, high/critical → 3-of-5
- * - Fiat transfers: USD/EUR/GBP >$100k → 2-of-3, >$1M → 3-of-5
- * - Crypto transfers: Require explicit risk tag (no numeric auto-detection)
- * - Sensitive scopes: custody/admin/settlement → 2-of-3
- * - Cross-entity communication: 2-of-3
- * - Explicit 'high' override: 2-of-3, 'critical' override: 3-of-5
- * - 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.criticalValueThreshold - Amount threshold for critical security (default: 1000000)
-     * @param options.enableXchange - Allow Xchange mode for performance (default: false)
-     */
-    constructor(options = {}) {
-        this.options = options;
-    }
-    classify(context) {
-        const { action, params, securityOverride } = context;
-        const highThreshold = this.options.highValueThreshold ?? 100_000;
-        const criticalThreshold = this.options.criticalValueThreshold ?? 1_000_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,
-            };
-        }
-        // Risk tag detection (preferred for crypto: BTC, ETH, etc.)
-        const riskTag = typeof params.risk === 'string' ? params.risk.toLowerCase() : undefined;
-        if (riskTag) {
-            if (riskTag === 'critical' || riskTag === 'high') {
-                return {
-                    mode: { type: 'split', shares: 5, threshold: 3 },
-                    reason: `Explicit risk tag "${riskTag}" requires 3-of-5 threshold`,
-                    wasOverridden: false,
-                };
-            }
-            else if (riskTag === 'medium') {
-                return {
-                    mode: { type: 'split', shares: 3, threshold: 2 },
-                    reason: `Explicit risk tag "medium" requires 2-of-3 threshold`,
-                    wasOverridden: false,
-                };
-            }
-            else if (riskTag === 'low') {
-                return {
-                    mode: { type: 'split', shares: 2, threshold: 2 },
-                    reason: `Explicit risk tag "low" requires 2-of-2 threshold`,
-                    wasOverridden: false,
-                };
-            }
-        }
-        // Numeric thresholds ONLY for fiat currencies (USD, EUR, GBP)
-        // Crypto (BTC, ETH) should use risk tags instead
-        if ((action === 'transfer' || action === 'execute') && typeof params.amount === 'number') {
-            const currency = typeof params.currency === 'string' ? params.currency.toUpperCase() : 'USD';
-            const isFiat = ['USD', 'EUR', 'GBP'].includes(currency);
-            if (isFiat) {
-                if (params.amount >= criticalThreshold) {
-                    return {
-                        mode: { type: 'split', shares: 5, threshold: 3 },
-                        reason: `Critical-value transfer (${currency} ${params.amount.toLocaleString()}) requires 3-of-5 threshold`,
-                        wasOverridden: false,
-                    };
-                }
-                else if (params.amount >= highThreshold) {
-                    return {
-                        mode: { type: 'split', shares: 3, threshold: 2 },
-                        reason: `High-value transfer (${currency} ${params.amount.toLocaleString()}) requires 2-of-3 threshold`,
-                        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,
-        },
-    };
-}
+export class DefaultSecurityPolicy{options;constructor(e={}){this.options=e}classify(e){const{action:r,params:t,securityOverride:s}=e,a=this.options.highValueThreshold??1e5,i=this.options.criticalValueThreshold??1e6;if("critical"===s)return{mode:{type:"split",shares:5,threshold:3},reason:"User requested critical security level (5 shares, 3-of-5 threshold)",wasOverridden:!0};if("high"===s)return{mode:{type:"split",shares:3,threshold:2},reason:"User requested high security level (3 shares, 2-of-3 threshold)",wasOverridden:!0};if("standard"===s)return{mode:{type:"standard"},reason:"User requested standard security level (encrypted transport)",wasOverridden:!0};const o="string"==typeof t.risk?t.risk.toLowerCase():void 0;if(o){if("critical"===o||"high"===o)return{mode:{type:"split",shares:5,threshold:3},reason:`Explicit risk tag "${o}" requires 3-of-5 threshold`,wasOverridden:!1};if("medium"===o)return{mode:{type:"split",shares:3,threshold:2},reason:'Explicit risk tag "medium" requires 2-of-3 threshold',wasOverridden:!1};if("low"===o)return{mode:{type:"split",shares:2,threshold:2},reason:'Explicit risk tag "low" requires 2-of-2 threshold',wasOverridden:!1}}if(("transfer"===r||"execute"===r)&&"number"==typeof t.amount){const e="string"==typeof t.currency?t.currency.toUpperCase():"USD";if(["USD","EUR","GBP"].includes(e)){if(t.amount>=i)return{mode:{type:"split",shares:5,threshold:3},reason:`Critical-value transfer (${e} ${t.amount.toLocaleString()}) requires 3-of-5 threshold`,wasOverridden:!1};if(t.amount>=a)return{mode:{type:"split",shares:3,threshold:2},reason:`High-value transfer (${e} ${t.amount.toLocaleString()}) requires 2-of-3 threshold`,wasOverridden:!1}}}return!0===t.crossEntity?{mode:{type:"split",shares:3,threshold:2},reason:"Cross-organization communication requires multi-party approval (2 of 3)",wasOverridden:!1}:e.scope.includes("admin")||e.scope.includes("custody")||e.scope.includes("settlement")?{mode:{type:"split",shares:3,threshold:2},reason:`Sensitive scope "${e.scope}" requires multi-party approval (2 of 3)`,wasOverridden:!1}:this.options.enableXchange&&!0===t.xchange?{mode:{type:"xchange"},reason:"Xchange mode enabled for performance (~180x faster)",wasOverridden:!1}:{mode:{type:"standard"},reason:"Standard encrypted transport (hybrid post-quantum)",wasOverridden:!1}}}export function describeSecurityMode(e){switch(e.type){case"standard":return"Standard (encrypted)";case"split":return`Multi-party approval (${e.threshold} of ${e.shares})`;case"xchange":return"Xchange (fast mode)"}}export function describeSecurityModeStructured(e){let r,t,s,a,i;switch(e.type){case"standard":r="standard",t="Security Level: Standard\nMode: Encrypted transport (hybrid post-quantum)",s="standard | encrypted",a="**Security Level:** Standard\n\n**Mode:** Encrypted transport (hybrid post-quantum)";break;case"split":r=e.shares>=5?"critical":"high",i={total:e.shares,threshold:e.threshold},t=`Security Level: ${"critical"===r?"Critical":"High"}\nMode: Split-channel (XorIDA)\nShares: ${e.shares} total, ${e.threshold} required`,s=`${r} | split | ${e.threshold}-of-${e.shares}`,a=`**Security Level:** ${"critical"===r?"Critical":"High"}\n\n**Mode:** Split-channel (XorIDA)\n\n**Shares:** ${e.shares} total, ${e.threshold} required`;break;case"xchange":r="performance",t="Security Level: Performance\nMode: Xchange (single IT layer, ~180x faster)",s="performance | xchange",a="**Security Level:** Performance\n\n**Mode:** Xchange (single IT layer, ~180x faster)"}const o={type:e.type,level:r};i&&(o.shares=i);const n=JSON.stringify(o);return{type:e.type,level:r,shares:i,formats:{multiline:t,singleline:s,json:n,markdown:a}}}

package/dist-standalone/serialization.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Alternative Serialization Formats (API-14)
+ *
+ * Pluggable serialization system supporting JSON, MessagePack, and CBOR.
+ * Provides format negotiation, backward compatibility, and performance benchmarks.
+ *
+ * @module serialization
+ */
+import type { Result } from '@private.me/shared';
+/**
+ * Supported serialization formats.
+ */
+export type SerializationFormat = 'json' | 'msgpack' | 'cbor';
+/**
+ * Serialization options for format negotiation.
+ */
+export interface SerializationOptions {
+    /**
+     * Preferred format for serialization.
+     * @default 'json'
+     */
+    format?: SerializationFormat;
+    /**
+     * List of acceptable formats for deserialization (in preference order).
+     * Used for format negotiation with peers.
+     * @default ['json', 'msgpack', 'cbor']
+     */
+    acceptFormats?: SerializationFormat[];
+    /**
+     * Enable pretty-printing for JSON format (debugging only).
+     * @default false
+     */
+    pretty?: boolean;
+    /**
+     * Enable performance metrics collection.
+     * @default false
+     */
+    collectMetrics?: boolean;
+}
+/**
+ * Serialization result with format metadata.
+ */
+export interface SerializedData {
+    /** Serialized bytes */
+    readonly data: Uint8Array;
+    /** Format used for serialization */
+    readonly format: SerializationFormat;
+    /** Size in bytes */
+    readonly size: number;
+    /** Content-Type header value */
+    readonly contentType: string;
+    /** Performance metrics (if collectMetrics enabled) */
+    readonly metrics?: SerializationMetrics;
+}
+/**
+ * Performance metrics for serialization operations.
+ */
+export interface SerializationMetrics {
+    /** Serialization duration in milliseconds */
+    readonly serializeDuration: number;
+    /** Size in bytes */
+    readonly size: number;
+    /** Format used */
+    readonly format: SerializationFormat;
+    /** Timestamp */
+    readonly timestamp: number;
+}
+/**
+ * Deserialization result with format detection.
+ */
+export interface DeserializedData<T = unknown> {
+    /** Deserialized value */
+    readonly value: T;
+    /** Detected format */
+    readonly format: SerializationFormat;
+    /** Performance metrics (if collectMetrics enabled) */
+    readonly metrics?: SerializationMetrics;
+}
+/**
+ * Error types for serialization operations.
+ */
+export type SerializationError = {
+    code: 'UNSUPPORTED_FORMAT';
+    format: string;
+} | {
+    code: 'SERIALIZATION_FAILED';
+    reason: string;
+    format: SerializationFormat;
+} | {
+    code: 'DESERIALIZATION_FAILED';
+    reason: string;
+} | {
+    code: 'FORMAT_DETECTION_FAILED';
+    reason: string;
+} | {
+    code: 'INVALID_DATA';
+    reason: string;
+};
+/**
+ * Serializer interface for pluggable format implementations.
+ */
+export interface Serializer {
+    /** Format identifier */
+    readonly format: SerializationFormat;
+    /** Content-Type header value */
+    readonly contentType: string;
+    /** Serialize value to bytes */
+    serialize(value: unknown, options?: SerializationOptions): Result<Uint8Array, SerializationError>;
+    /** Deserialize bytes to value */
+    deserialize<T = unknown>(data: Uint8Array): Result<T, SerializationError>;
+    /** Detect if data is in this format */
+    detect(data: Uint8Array): boolean;
+}
+/**
+ * Serialize a value using the specified format.
+ *
+ * @param value - Value to serialize
+ * @param options - Serialization options
+ * @returns Serialized data with metadata
+ *
+ * @example
+ * ```typescript
+ * const data = { message: 'Hello', timestamp: Date.now() };
+ *
+ * // JSON (default, human-readable)
+ * const json = serialize(data);
+ *
+ * // MessagePack (compact binary)
+ * const msgpack = serialize(data, { format: 'msgpack' });
+ *
+ * // CBOR (standard binary)
+ * const cbor = serialize(data, { format: 'cbor' });
+ *
+ * console.log('JSON:', json.value.size, 'bytes');
+ * console.log('MessagePack:', msgpack.value.size, 'bytes');
+ * console.log('CBOR:', cbor.value.size, 'bytes');
+ * ```
+ */
+export declare function serialize(value: unknown, options?: SerializationOptions): Result<SerializedData, SerializationError>;
+/**
+ * Deserialize bytes using format auto-detection or explicit format.
+ *
+ * @param data - Serialized bytes
+ * @param options - Deserialization options
+ * @returns Deserialized value with format metadata
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect format
+ * const result = deserialize(bytes);
+ * if (result.ok) {
+ *   console.log('Format:', result.value.format);
+ *   console.log('Data:', result.value.value);
+ * }
+ *
+ * // Explicit format (faster, skips detection)
+ * const json = deserialize(bytes, { format: 'json' });
+ * ```
+ */
+export declare function deserialize<T = unknown>(data: Uint8Array, options?: SerializationOptions): Result<DeserializedData<T>, SerializationError>;
+/**
+ * Detect serialization format from bytes.
+ *
+ * @param data - Serialized bytes
+ * @returns Detected format
+ *
+ * @example
+ * ```typescript
+ * const format = detectFormat(bytes);
+ * if (format.ok) {
+ *   console.log('Detected format:', format.value); // 'json' | 'msgpack' | 'cbor'
+ * }
+ * ```
+ */
+export declare function detectFormat(data: Uint8Array): Result<SerializationFormat, SerializationError>;
+/**
+ * Negotiate format between client and server.
+ *
+ * @param clientFormats - Formats accepted by client (in preference order)
+ * @param serverFormats - Formats supported by server
+ * @returns Best matching format
+ *
+ * @example
+ * ```typescript
+ * const client = ['msgpack', 'cbor', 'json'];
+ * const server = ['json', 'cbor'];
+ * const format = negotiateFormat(client, server);
+ * console.log(format.value); // 'cbor' (first match)
+ * ```
+ */
+export declare function negotiateFormat(clientFormats: SerializationFormat[], serverFormats: SerializationFormat[]): Result<SerializationFormat, SerializationError>;
+/**
+ * Compare serialization performance across formats.
+ *
+ * @param value - Value to benchmark
+ * @param formats - Formats to compare
+ * @returns Performance comparison
+ *
+ * @example
+ * ```typescript
+ * const data = { message: 'Hello', items: [1, 2, 3, 4, 5] };
+ * const comparison = compareFormats(data);
+ *
+ * if (comparison.ok) {
+ *   for (const result of comparison.value) {
+ *     console.log(`${result.format}: ${result.size} bytes, ${result.duration}ms`);
+ *   }
+ * }
+ * ```
+ */
+export declare function compareFormats(value: unknown, formats?: SerializationFormat[]): Result<Array<{
+    format: SerializationFormat;
+    size: number;
+    duration: number;
+}>, SerializationError>;
+/**
+ * Get Content-Type header for a serialization format.
+ *
+ * @param format - Serialization format
+ * @returns Content-Type header value
+ *
+ * @example
+ * ```typescript
+ * const contentType = getContentType('msgpack');
+ * console.log(contentType); // 'application/msgpack'
+ * ```
+ */
+export declare function getContentType(format: SerializationFormat): string;
+/**
+ * Parse Content-Type header to serialization format.
+ *
+ * @param contentType - Content-Type header value
+ * @returns Serialization format or undefined
+ *
+ * @example
+ * ```typescript
+ * const format = parseContentType('application/json');
+ * console.log(format); // 'json'
+ *
+ * const format2 = parseContentType('application/msgpack');
+ * console.log(format2); // 'msgpack'
+ * ```
+ */
+export declare function parseContentType(contentType: string): SerializationFormat | undefined;

package/dist-standalone/serialization.js

@@ -0,0 +1 @@
+import{ok,err}from"./_deps/shared/index.js";class JSONSerializer{format="json";contentType="application/json";serialize(e,t){try{const r=t?.pretty?JSON.stringify(e,null,2):JSON.stringify(e);return ok((new TextEncoder).encode(r))}catch(e){return err({code:"SERIALIZATION_FAILED",reason:e instanceof Error?e.message:String(e),format:"json"})}}deserialize(e){try{const t=(new TextDecoder).decode(e);return ok(JSON.parse(t))}catch(e){return err({code:"DESERIALIZATION_FAILED",reason:e instanceof Error?e.message:String(e)})}}detect(e){if(0===e.length)return!1;const t=e[0];if(void 0===t)return!1;if(123===t||91===t||34===t)return!0;if(32===t||9===t||10===t||13===t)for(let t=1;t<Math.min(e.length,10);t++){const r=e[t];if(void 0===r)return!1;if(123===r||91===r||34===r)return!0;if(32!==r&&9!==r&&10!==r&&13!==r)return!1}return!1}}class MessagePackSerializer{format="msgpack";contentType="application/msgpack";serialize(e,t){try{return ok(this.encode(e))}catch(e){return err({code:"SERIALIZATION_FAILED",reason:e instanceof Error?e.message:String(e),format:"msgpack"})}}deserialize(e){try{return ok(this.decode(e))}catch(e){return err({code:"DESERIALIZATION_FAILED",reason:e instanceof Error?e.message:String(e)})}}detect(e){if(0===e.length)return!1;const t=e[0];if(void 0===t)return!1;if(t>=224&&t<=255&&e.length<2)return!1;try{const t={offset:0};return this.decodeValue(e,t),!0}catch{return!1}}encode(e){const t=[];this.encodeValue(e,t);const r=t.reduce((e,t)=>e+t.length,0),n=new Uint8Array(r);let s=0;for(const e of t)n.set(e,s),s+=e.length;return n}encodeValue(e,t){if(null==e)t.push(new Uint8Array([192]));else if("boolean"==typeof e)t.push(new Uint8Array([e?195:194]));else if("number"==typeof e)this.encodeNumber(e,t);else if("string"==typeof e)this.encodeString(e,t);else if(e instanceof Uint8Array)this.encodeBinary(e,t);else if(Array.isArray(e))this.encodeArray(e,t);else{if("object"!=typeof e)throw new Error("Unsupported type: "+typeof e);this.encodeObject(e,t)}}encodeNumber(e,t){if(Number.isInteger(e))if(e>=0&&e<=127)t.push(new Uint8Array([e]));else if(e>=-32&&e<0)t.push(new Uint8Array([224|31&e]));else if(e>=0&&e<=255)t.push(new Uint8Array([204,e]));else if(e>=0&&e<=65535)t.push(new Uint8Array([205,e>>8,255&e]));else if(e>=0&&e<=4294967295){const r=new Uint8Array(5);r[0]=206,new DataView(r.buffer).setUint32(1,e,!1),t.push(r)}else{const r=new Uint8Array(9);r[0]=203,new DataView(r.buffer).setFloat64(1,e,!1),t.push(r)}else{const r=new Uint8Array(9);r[0]=203,new DataView(r.buffer).setFloat64(1,e,!1),t.push(r)}}encodeString(e,t){const r=(new TextEncoder).encode(e),n=r.length;if(n<=31)t.push(new Uint8Array([160|n]));else if(n<=255)t.push(new Uint8Array([217,n]));else if(n<=65535)t.push(new Uint8Array([218,n>>8,255&n]));else{const e=new Uint8Array(5);e[0]=219,new DataView(e.buffer).setUint32(1,n,!1),t.push(e)}t.push(r)}encodeBinary(e,t){const r=e.length;if(r<=255)t.push(new Uint8Array([196,r]));else if(r<=65535)t.push(new Uint8Array([197,r>>8,255&r]));else{const e=new Uint8Array(5);e[0]=198,new DataView(e.buffer).setUint32(1,r,!1),t.push(e)}t.push(e)}encodeArray(e,t){const r=e.length;if(r<=15)t.push(new Uint8Array([144|r]));else if(r<=65535)t.push(new Uint8Array([220,r>>8,255&r]));else{const e=new Uint8Array(5);e[0]=221,new DataView(e.buffer).setUint32(1,r,!1),t.push(e)}for(const r of e)this.encodeValue(r,t)}encodeObject(e,t){const r=Object.keys(e),n=r.length;if(n<=15)t.push(new Uint8Array([128|n]));else if(n<=65535)t.push(new Uint8Array([222,n>>8,255&n]));else{const e=new Uint8Array(5);e[0]=223,new DataView(e.buffer).setUint32(1,n,!1),t.push(e)}for(const n of r)this.encodeValue(n,t),this.encodeValue(e[n],t)}decode(e){return this.decodeValue(e,{offset:0})}decodeValue(e,t){if(t.offset>=e.length)throw new Error("Unexpected end of data");const r=e[t.offset++];if(void 0===r)throw new Error("Unexpected end of data");if(r<=127)return r;if(r>=128&&r<=143){const n=15&r;return this.decodeMap(e,t,n)}if(r>=144&&r<=159){const n=15&r;return this.decodeArray(e,t,n)}if(r>=160&&r<=191){const n=31&r;return this.decodeString(e,t,n)}if(r>=224)return(31&r)-32;switch(r){case 192:return null;case 194:return!1;case 195:return!0;case 196:{const r=e[t.offset++];if(void 0===r)throw new Error("Unexpected end of data");return this.decodeBinary(e,t,r)}case 197:return this.decodeBinary(e,t,this.readUint16(e,t));case 198:return this.decodeBinary(e,t,this.readUint32(e,t));case 202:return this.readFloat32(e,t);case 203:return this.readFloat64(e,t);case 204:{const r=e[t.offset++];if(void 0===r)throw new Error("Unexpected end of data");return r}case 205:return this.readUint16(e,t);case 206:return this.readUint32(e,t);case 208:return this.readInt8(e,t);case 209:return this.readInt16(e,t);case 210:return this.readInt32(e,t);case 217:{const r=e[t.offset++];if(void 0===r)throw new Error("Unexpected end of data");return this.decodeString(e,t,r)}case 218:return this.decodeString(e,t,this.readUint16(e,t));case 219:return this.decodeString(e,t,this.readUint32(e,t));case 220:return this.decodeArray(e,t,this.readUint16(e,t));case 221:return this.decodeArray(e,t,this.readUint32(e,t));case 222:return this.decodeMap(e,t,this.readUint16(e,t));case 223:return this.decodeMap(e,t,this.readUint32(e,t));default:throw new Error(`Unknown MessagePack type: 0x${r.toString(16)}`)}}decodeString(e,t,r){const n=e.slice(t.offset,t.offset+r);return t.offset+=r,(new TextDecoder).decode(n)}decodeBinary(e,t,r){const n=e.slice(t.offset,t.offset+r);return t.offset+=r,n}decodeArray(e,t,r){const n=[];for(let s=0;s<r;s++)n.push(this.decodeValue(e,t));return n}decodeMap(e,t,r){const n={};for(let s=0;s<r;s++){const r=this.decodeValue(e,t),s=this.decodeValue(e,t);n[String(r)]=s}return n}readUint16(e,t){const r=new DataView(e.buffer,e.byteOffset).getUint16(t.offset,!1);return t.offset+=2,r}readUint32(e,t){const r=new DataView(e.buffer,e.byteOffset).getUint32(t.offset,!1);return t.offset+=4,r}readInt8(e,t){if(t.offset>=e.length)throw new Error("Unexpected end of data");const r=new DataView(e.buffer,e.byteOffset).getInt8(t.offset);return t.offset+=1,r}readInt16(e,t){const r=new DataView(e.buffer,e.byteOffset).getInt16(t.offset,!1);return t.offset+=2,r}readInt32(e,t){const r=new DataView(e.buffer,e.byteOffset).getInt32(t.offset,!1);return t.offset+=4,r}readFloat32(e,t){const r=new DataView(e.buffer,e.byteOffset).getFloat32(t.offset,!1);return t.offset+=4,r}readFloat64(e,t){const r=new DataView(e.buffer,e.byteOffset).getFloat64(t.offset,!1);return t.offset+=8,r}}class CBORSerializer{format="cbor";contentType="application/cbor";serialize(e,t){try{return ok(this.encode(e))}catch(e){return err({code:"SERIALIZATION_FAILED",reason:e instanceof Error?e.message:String(e),format:"cbor"})}}deserialize(e){try{return ok(this.decode(e))}catch(e){return err({code:"DESERIALIZATION_FAILED",reason:e instanceof Error?e.message:String(e)})}}detect(e){if(0===e.length)return!1;e[0];try{const t={offset:0};return this.decodeValue(e,t),!0}catch{return!1}}encode(e){const t=[];this.encodeValue(e,t);const r=t.reduce((e,t)=>e+t.length,0),n=new Uint8Array(r);let s=0;for(const e of t)n.set(e,s),s+=e.length;return n}encodeValue(e,t){if(null==e)t.push(new Uint8Array([246]));else if("boolean"==typeof e)t.push(new Uint8Array([e?245:244]));else if("number"==typeof e)this.encodeNumber(e,t);else if("string"==typeof e)this.encodeString(e,t);else if(e instanceof Uint8Array)this.encodeBinary(e,t);else if(Array.isArray(e))this.encodeArray(e,t);else{if("object"!=typeof e)throw new Error("Unsupported type: "+typeof e);this.encodeObject(e,t)}}encodeNumber(e,t){if(Number.isInteger(e))if(e>=0)if(e<=23)t.push(new Uint8Array([e]));else if(e<=255)t.push(new Uint8Array([24,e]));else if(e<=65535)t.push(new Uint8Array([25,e>>8,255&e]));else if(e<=4294967295){const r=new Uint8Array(5);r[0]=26,new DataView(r.buffer).setUint32(1,e,!1),t.push(r)}else{const r=new Uint8Array(9);r[0]=251,new DataView(r.buffer).setFloat64(1,e,!1),t.push(r)}else{const r=-1-e;if(r<=23)t.push(new Uint8Array([32|r]));else if(r<=255)t.push(new Uint8Array([56,r]));else if(r<=65535)t.push(new Uint8Array([57,r>>8,255&r]));else{const e=new Uint8Array(5);e[0]=58,new DataView(e.buffer).setUint32(1,r,!1),t.push(e)}}else{const r=new Uint8Array(9);r[0]=251,new DataView(r.buffer).setFloat64(1,e,!1),t.push(r)}}encodeString(e,t){const r=(new TextEncoder).encode(e),n=r.length;if(n<=23)t.push(new Uint8Array([96|n]));else if(n<=255)t.push(new Uint8Array([120,n]));else if(n<=65535)t.push(new Uint8Array([121,n>>8,255&n]));else{const e=new Uint8Array(5);e[0]=122,new DataView(e.buffer).setUint32(1,n,!1),t.push(e)}t.push(r)}encodeBinary(e,t){const r=e.length;if(r<=23)t.push(new Uint8Array([64|r]));else if(r<=255)t.push(new Uint8Array([88,r]));else if(r<=65535)t.push(new Uint8Array([89,r>>8,255&r]));else{const e=new Uint8Array(5);e[0]=90,new DataView(e.buffer).setUint32(1,r,!1),t.push(e)}t.push(e)}encodeArray(e,t){const r=e.length;if(r<=23)t.push(new Uint8Array([128|r]));else if(r<=255)t.push(new Uint8Array([152,r]));else if(r<=65535)t.push(new Uint8Array([153,r>>8,255&r]));else{const e=new Uint8Array(5);e[0]=154,new DataView(e.buffer).setUint32(1,r,!1),t.push(e)}for(const r of e)this.encodeValue(r,t)}encodeObject(e,t){const r=Object.keys(e),n=r.length;if(n<=23)t.push(new Uint8Array([160|n]));else if(n<=255)t.push(new Uint8Array([184,n]));else if(n<=65535)t.push(new Uint8Array([185,n>>8,255&n]));else{const e=new Uint8Array(5);e[0]=186,new DataView(e.buffer).setUint32(1,n,!1),t.push(e)}for(const n of r)this.encodeValue(n,t),this.encodeValue(e[n],t)}decode(e){return this.decodeValue(e,{offset:0})}decodeValue(e,t){if(t.offset>=e.length)throw new Error("Unexpected end of data");const r=e[t.offset++];if(void 0===r)throw new Error("Unexpected end of data");const n=r>>5&7,s=31&r;switch(n){case 0:return this.decodeInteger(e,t,s);case 1:return-1-this.decodeInteger(e,t,s);case 2:return this.decodeBinary(e,t,s);case 3:return this.decodeString(e,t,s);case 4:return this.decodeArray(e,t,s);case 5:return this.decodeMap(e,t,s);case 7:return this.decodeSpecial(e,t,s);default:throw new Error(`Unsupported CBOR major type: ${n}`)}}decodeInteger(e,t,r){if(r<=23)return r;if(24===r){const r=e[t.offset++];if(void 0===r)throw new Error("Unexpected end of data");return r}if(25===r)return this.readUint16(e,t);if(26===r)return this.readUint32(e,t);throw new Error("Unsupported integer size")}decodeString(e,t,r){let n;n=r<=23?r:this.decodeInteger(e,t,r);const s=e.slice(t.offset,t.offset+n);return t.offset+=n,(new TextDecoder).decode(s)}decodeBinary(e,t,r){let n;n=r<=23?r:this.decodeInteger(e,t,r);const s=e.slice(t.offset,t.offset+n);return t.offset+=n,s}decodeArray(e,t,r){let n;n=r<=23?r:this.decodeInteger(e,t,r);const s=[];for(let r=0;r<n;r++)s.push(this.decodeValue(e,t));return s}decodeMap(e,t,r){let n;n=r<=23?r:this.decodeInteger(e,t,r);const s={};for(let r=0;r<n;r++){const r=this.decodeValue(e,t),n=this.decodeValue(e,t);s[String(r)]=n}return s}decodeSpecial(e,t,r){switch(r){case 20:return!1;case 21:return!0;case 22:return null;case 23:return;case 27:return this.readFloat64(e,t);default:throw new Error(`Unsupported CBOR special: ${r}`)}}readUint16(e,t){const r=new DataView(e.buffer,e.byteOffset).getUint16(t.offset,!1);return t.offset+=2,r}readUint32(e,t){const r=new DataView(e.buffer,e.byteOffset).getUint32(t.offset,!1);return t.offset+=4,r}readFloat64(e,t){const r=new DataView(e.buffer,e.byteOffset).getFloat64(t.offset,!1);return t.offset+=8,r}}const serializers=new Map([["json",new JSONSerializer],["cbor",new CBORSerializer],["msgpack",new MessagePackSerializer]]);export function serialize(e,t={}){const r=t.format??"json",n=serializers.get(r);if(!n)return err({code:"UNSUPPORTED_FORMAT",format:r});const s=t.collectMetrics?performance.now():0,o=n.serialize(e,t);if(!o.ok)return o;const i=t.collectMetrics?{serializeDuration:performance.now()-s,size:o.value.length,format:r,timestamp:Date.now()}:void 0;return ok({data:o.value,format:r,size:o.value.length,contentType:n.contentType,metrics:i})}export function deserialize(e,t={}){const r=t.collectMetrics?performance.now():0;let n,s;if(t.format){if(n=t.format,s=serializers.get(n),!s)return err({code:"UNSUPPORTED_FORMAT",format:n})}else{const t=detectFormat(e);if(!t.ok)return t;if(n=t.value,s=serializers.get(n),!s)return err({code:"UNSUPPORTED_FORMAT",format:n})}const o=s.deserialize(e);if(!o.ok)return o;const i=t.collectMetrics?{serializeDuration:performance.now()-r,size:e.length,format:n,timestamp:Date.now()}:void 0;return ok({value:o.value,format:n,metrics:i})}export function detectFormat(e){const t=serializers.get("json");if(t?.detect(e))return ok("json");if(0===e.length)return err({code:"FORMAT_DETECTION_FAILED",reason:"Empty data"});const r=serializers.get("cbor");if(r?.detect(e))return ok("cbor");const n=serializers.get("msgpack");return n?.detect(e)?ok("msgpack"):err({code:"FORMAT_DETECTION_FAILED",reason:"No serializer recognized the data format"})}export function negotiateFormat(e,t){for(const r of e)if(t.includes(r))return ok(r);return err({code:"UNSUPPORTED_FORMAT",format:`No common format (client: ${e.join(",")}, server: ${t.join(",")})`})}export function compareFormats(e,t=["json","msgpack","cbor"]){const r=[];for(const n of t){const t=serialize(e,{format:n,collectMetrics:!0});if(!t.ok)return t;r.push({format:n,size:t.value.size,duration:t.value.metrics?.serializeDuration??0})}return ok(r)}export function getContentType(e){const t=serializers.get(e);return t?.contentType??"application/octet-stream"}export function parseContentType(e){const t=e.toLowerCase().split(";")[0]?.trim()??"";for(const e of serializers.values())if(e.contentType===t)return e.format}

package/dist-standalone/split-channel.d.ts

@@ -43,9 +43,35 @@ export declare const DEFAULT_SPLIT_CONFIG: SplitChannelConfig;
  *
  * Pipeline: pad(PKCS#7) -> HMAC(padded) -> XorIDA split -> ChannelShare[]
  *
+ * Information-theoretic security: Any k shares can reconstruct the plaintext,
+ * but k-1 shares reveal ZERO information (proven secure).
+ *
  * @param plaintext - Raw plaintext bytes to split
  * @param config - Split configuration (totalShares, threshold)
  * @returns Array of n ChannelShare objects ready for envelope wrapping
+ *
+ * @example
+ * ```typescript
+ * import { splitForChannel, DEFAULT_SPLIT_CONFIG } from '@private.me/xbind';
+ *
+ * const plaintext = new TextEncoder().encode('Sensitive data');
+ *
+ * // Default: 3 shares, need 2 to reconstruct
+ * const shares = await splitForChannel(plaintext);
+ * if (!shares.ok) throw new Error(shares.error);
+ *
+ * console.log('Created shares:', shares.value.length);
+ * // Send each share through different channels (email, SMS, push)
+ * shares.value.forEach((share, i) => {
+ *   console.log(`Share ${i}: ${share.groupId}`);
+ * });
+ *
+ * // Custom configuration: 5 shares, need 3
+ * const customShares = await splitForChannel(plaintext, {
+ *   totalShares: 5,
+ *   threshold: 3
+ * });
+ * ```
  */
 export declare function splitForChannel(plaintext: Uint8Array, config?: SplitChannelConfig): Promise<Result<ChannelShare[], SplitChannelError>>;
 /**
@@ -63,7 +89,29 @@ export declare function splitForChannelWithGroupId(plaintext: Uint8Array, config
  * 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
+ * @param shares - Array of at least k ChannelShare objects (must have same groupId)
  * @returns Reconstructed plaintext bytes
+ *
+ * @example
+ * ```typescript
+ * import { reconstructFromChannel, type ChannelShare } from '@private.me/xbind';
+ *
+ * // Collect shares from different channels
+ * const receivedShares: ChannelShare[] = [
+ *   emailShare,   // Received via email
+ *   smsShare,     // Received via SMS
+ *   // Only need 2 shares (threshold = 2)
+ * ];
+ *
+ * // Reconstruct original message
+ * const plaintext = await reconstructFromChannel(receivedShares);
+ * if (!plaintext.ok) {
+ *   console.error('Reconstruction failed:', plaintext.error);
+ *   return;
+ * }
+ *
+ * const message = new TextDecoder().decode(plaintext.value);
+ * console.log('Reconstructed message:', message);
+ * ```
  */
 export declare function reconstructFromChannel(shares: readonly ChannelShare[]): Promise<Result<Uint8Array, SplitChannelError>>;