@private.me/xbind 1.2.0

package/dist-standalone/errors.js

@@ -0,0 +1,548 @@
+/**
+ * @module errors
+ * Named error class hierarchy for xBind agent-sdk.
+ *
+ * These classes are supplementary — existing `Result<T, E>` string codes are
+ * unchanged. Use `toXBindError()` to convert a string error code into a
+ * class-based error for try/catch consumers.
+ */
+import { createDetailedError } from"./_deps/ux-helpers/index.js";
+const DOC_BASE = 'https://private.me/docs/xbind';
+/** Base error class for all XBind errors. */
+export class XBindError extends Error {
+    /** Machine-readable error code matching the Result<T,E> string unions. */
+    code;
+    /** Sub-code parsed from colon-separated codes (e.g. 'DECRYPTION' from 'DECRYPT_FAILED:DECRYPTION'). */
+    subCode;
+    /** URL to relevant documentation for this error. */
+    docUrl;
+    constructor(code, message, docUrl) {
+        super(message);
+        this.name = 'XBindError';
+        const parts = code.split(':');
+        this.code = parts[0] ?? code;
+        this.subCode = parts.length > 1 ? parts.slice(1).join(':') : undefined;
+        this.docUrl = docUrl;
+    }
+}
+/** Ed25519/X25519 identity errors (keygen, sign, verify, DID, import/export). */
+export class XBindIdentityError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#identity`);
+        this.name = 'XBindIdentityError';
+    }
+}
+/** Envelope creation, encryption, decryption, and parsing errors. */
+export class XBindEnvelopeError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#envelope`);
+        this.name = 'XBindEnvelopeError';
+    }
+}
+/** Transport-layer errors (send failures, network, timeouts). */
+export class XBindTransportError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#transport`);
+        this.name = 'XBindTransportError';
+    }
+}
+/** Trust registry errors (lookup, registration, revocation). */
+export class XBindRegistryError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#registry`);
+        this.name = 'XBindRegistryError';
+    }
+}
+/** X25519 ECDH key agreement errors. */
+export class XBindKeyAgreementError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#key-agreement`);
+        this.name = 'XBindKeyAgreementError';
+    }
+}
+/** XorIDA split-channel errors (split, reconstruct, HMAC, shares). */
+export class XBindSplitChannelError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#split-channel`);
+        this.name = 'XBindSplitChannelError';
+    }
+}
+/** High-level Agent errors (wraps subsystem errors with context). */
+export class XBindAgentError extends XBindError {
+    constructor(code, message) {
+        super(code, message, `${DOC_BASE}#agent`);
+        this.name = 'XBindAgentError';
+    }
+}
+/**
+ * Create detailed error information for a given error code.
+ *
+ * @param code - Error code (e.g., 'INVALID_DID')
+ * @param additionalContext - Optional context (field name, custom hint)
+ * @returns ACIErrorDetail with code, message, hint, field, and docs
+ */
+export function createXBindErrorDetail(code, additionalContext) {
+    const baseCode = code.split(':')[0] ?? code;
+    const entry = ERROR_DETAILS[baseCode];
+    if (entry) {
+        return createDetailedError(code, entry.message, {
+            hint: additionalContext?.hint ?? entry.hint,
+            field: additionalContext?.field ?? entry.field,
+            docs: entry.docs,
+        });
+    }
+    // Fallback for unknown codes
+    return createDetailedError(code, `XBind error: ${code}`, {
+        docs: DOC_BASE,
+    });
+}
+/** Detailed error information for each error code. */
+const ERROR_DETAILS = {
+    // Identity
+    KEYGEN_FAILED: {
+        message: 'Key generation failed',
+        hint: 'Actions: (1) Verify Web Crypto API available (browser/Node.js 15+), (2) Check security context (HTTPS or localhost), (3) Retry operation',
+        suggested_action: 'Verify runtime environment supports Web Crypto API and retry key generation',
+        severity: 'critical',
+        docs: `${DOC_BASE}#identity`,
+    },
+    SIGN_FAILED: {
+        message: 'Signing failed',
+        hint: 'Actions: (1) Verify private key is valid and not corrupted, (2) Check key format (must be PKCS8), (3) Ensure key was properly imported',
+        suggested_action: 'Verify private key is valid and properly imported with extractable flag',
+        severity: 'high',
+        docs: `${DOC_BASE}#identity`,
+    },
+    VERIFY_FAILED: {
+        message: 'Signature verification failed',
+        hint: 'Actions: (1) Verify public key matches sender, (2) Check message integrity (not truncated/modified), (3) Confirm signature format is valid base64',
+        suggested_action: 'Verify sender public key and message integrity before retrying',
+        severity: 'critical',
+        docs: `${DOC_BASE}#identity`,
+    },
+    INVALID_DID: {
+        message: 'DID format is invalid',
+        hint: 'Actions: (1) Verify DID starts with "did:" prefix, (2) Check method is valid (e.g., did:key:z6Mk...), (3) Use validateDID() helper before processing',
+        field: 'did',
+        suggested_action: 'Use validateDID() helper to verify format before processing',
+        severity: 'high',
+        docs: `${DOC_BASE}#identity`,
+    },
+    INVALID_KEY_LENGTH: {
+        message: 'Key material has incorrect length',
+        hint: 'Actions: (1) Verify X25519 key is exactly 32 bytes, (2) Check base64 decoding result, (3) Log key.length to confirm size mismatch',
+        suggested_action: 'Verify key is exactly 32 bytes and properly base64-decoded',
+        severity: 'high',
+        docs: `${DOC_BASE}#key-agreement`,
+    },
+    EXPORT_FAILED: {
+        message: 'PKCS8 export failed',
+        hint: 'Actions: (1) Verify key was created with extractable:true, (2) Check browser/Node.js supports PKCS8 export, (3) Use Web Crypto API docs: https://mdn.io/SubtleCrypto.exportKey',
+        suggested_action: 'Create key with extractable:true flag and verify Web Crypto API support',
+        severity: 'medium',
+        docs: `${DOC_BASE}#identity`,
+    },
+    IMPORT_FAILED: {
+        message: 'PKCS8 import failed',
+        hint: 'Actions: (1) Validate PKCS8 format (PEM or raw bytes), (2) Decode base64 if needed, (3) Check algorithm matches (Ed25519/X25519), (4) Verify key data is not corrupted',
+        suggested_action: 'Validate PKCS8 format and verify key data is not corrupted',
+        severity: 'high',
+        docs: `${DOC_BASE}#identity`,
+    },
+    // Envelope
+    INVALID_VERSION: {
+        message: 'Unsupported envelope version',
+        hint: 'Actions: (1) Check envelope.version field, (2) Verify sender uses compatible version (v1-v4 supported), (3) Update SDK or request sender upgrade',
+        field: 'version',
+        suggested_action: 'Update SDK or request sender to use compatible version (v1-v4)',
+        severity: 'high',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    INVALID_ALG: {
+        message: 'Unknown encryption algorithm',
+        hint: 'Actions: (1) Verify envelope.alg === "AES-256-GCM", (2) Check sender uses correct algorithm, (3) Log algorithm value to confirm mismatch',
+        field: 'alg',
+        suggested_action: 'Verify sender uses AES-256-GCM algorithm',
+        severity: 'high',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    INVALID_NONCE: {
+        message: 'Nonce is missing or invalid',
+        hint: 'Actions: (1) Verify nonce exists and is 12 bytes, (2) Check base64 decoding, (3) Ensure nonce is unique per envelope (check replay buffer)',
+        field: 'nonce',
+        suggested_action: 'Verify nonce is 12 bytes and properly base64-encoded',
+        severity: 'critical',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    INVALID_FIELDS: {
+        message: 'Required envelope fields are missing',
+        hint: 'Actions: (1) Verify sender/recipient DIDs present, (2) Check payload is not empty, (3) Validate envelope has: version, alg, nonce, ciphertext, tag',
+        suggested_action: 'Validate all required envelope fields are present',
+        severity: 'high',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    ENCRYPT_FAILED: {
+        message: 'AES-256-GCM encryption failed',
+        hint: 'Actions: (1) Verify shared key is exactly 32 bytes, (2) Check plaintext is valid UTF-8, (3) Ensure nonce is 12 bytes, (4) Review Web Crypto error details',
+        suggested_action: 'Verify key is 32 bytes and nonce is 12 bytes before encryption',
+        severity: 'high',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    DECRYPT_FAILED: {
+        message: 'Decryption failed',
+        hint: 'Actions: (1) Verify correct key is being used, (2) Check ciphertext integrity (not truncated), (3) Confirm authentication tag is valid, (4) Verify sender used same algorithm',
+        suggested_action: 'Verify correct key and check ciphertext integrity',
+        severity: 'critical',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    PARSE_FAILED: {
+        message: 'Envelope deserialization failed',
+        hint: 'Actions: (1) Validate JSON structure, (2) Check for truncation or corruption in data, (3) Verify base64 encoding of nested fields, (4) Use JSON.parse() to identify syntax error',
+        suggested_action: 'Validate JSON structure and check for data corruption',
+        severity: 'high',
+        docs: `${DOC_BASE}#envelope`,
+    },
+    // Transport
+    SEND_FAILED: {
+        message: 'Message send failed',
+        hint: 'Actions: (1) Check network connectivity (ping registry), (2) Verify recipient email is valid, (3) Confirm recipient is registered in trust registry, (4) Retry with exponential backoff',
+        suggested_action: 'Check network connectivity and retry with exponential backoff',
+        severity: 'high',
+        docs: `${DOC_BASE}#transport`,
+    },
+    NETWORK_ERROR: {
+        message: 'Network request failed',
+        hint: 'Actions: (1) Verify internet connection, (2) Check DNS resolution, (3) Try pinging registry endpoint, (4) Implement retry with exponential backoff (2s, 4s, 8s)',
+        suggested_action: 'Verify internet connection and implement exponential backoff retry',
+        severity: 'high',
+        docs: `${DOC_BASE}#transport`,
+    },
+    RECIPIENT_UNREACHABLE: {
+        message: 'Recipient is unreachable',
+        hint: 'Actions: (1) Verify recipient email address is spelled correctly, (2) Check if recipient is registered with xBind, (3) Confirm recipient is online, (4) Ask recipient to check their registration status',
+        field: 'to',
+        suggested_action: 'Verify recipient is registered with xBind and online',
+        severity: 'medium',
+        docs: `${DOC_BASE}#transport`,
+    },
+    TIMEOUT: {
+        message: 'Transport operation timed out',
+        hint: 'Actions: (1) Increase timeout threshold (default: 30s), (2) Check network latency (ping registry), (3) Retry operation, (4) Verify registry is responsive',
+        suggested_action: 'Increase timeout threshold and check network latency',
+        severity: 'medium',
+        docs: `${DOC_BASE}#transport`,
+    },
+    // Registry
+    NOT_FOUND: {
+        message: 'Agent not found in trust registry',
+        hint: 'Actions: (1) Ask recipient to join XBind and register, (2) Verify recipient email is correct, (3) Query registry with recipient DID/email, (4) Check registration timestamp on recipient side',
+        field: 'to',
+        suggested_action: 'Ask recipient to register with xBind',
+        severity: 'medium',
+        docs: `${DOC_BASE}#registry`,
+    },
+    ALREADY_REGISTERED: {
+        message: 'Agent is already registered',
+        hint: 'Actions: (1) Use updateAgent() instead of registerAgent(), (2) Provide new public keys or metadata, (3) Verify DID matches existing registration, (4) Check for duplicate registrations',
+        suggested_action: 'Use updateAgent() instead of registerAgent()',
+        severity: 'low',
+        docs: `${DOC_BASE}#registry`,
+    },
+    REVOKED: {
+        message: 'Agent has been revoked from the registry',
+        hint: 'Actions: (1) Contact registry administrator, (2) Check revocation timestamp and reason, (3) Request re-registration if revocation was accidental, (4) Verify agent identity with admin',
+        suggested_action: 'Contact registry administrator to resolve revocation',
+        severity: 'high',
+        docs: `${DOC_BASE}#registry`,
+    },
+    // Key agreement
+    DERIVE_FAILED: {
+        message: 'ECDH key derivation failed',
+        hint: 'Actions: (1) Verify peer public key is valid X25519 (32 bytes), (2) Check key is not corrupted, (3) Confirm algorithm is X25519 ECDH, (4) Review Web Crypto error details',
+        suggested_action: 'Verify peer public key is valid X25519 and not corrupted',
+        severity: 'high',
+        docs: `${DOC_BASE}#key-agreement`,
+    },
+    KEM_ENCAPSULATE_FAILED: {
+        message: 'ML-KEM-768 encapsulation failed',
+        hint: 'Actions: (1) Verify recipient public key is valid ML-KEM-768, (2) Check key encoding (must be valid format), (3) Confirm post-quantum support enabled, (4) Validate key length and structure',
+        suggested_action: 'Verify recipient ML-KEM-768 public key and post-quantum support',
+        severity: 'high',
+        docs: `${DOC_BASE}#key-agreement`,
+    },
+    KEM_DECAPSULATE_FAILED: {
+        message: 'ML-KEM-768 decapsulation failed',
+        hint: 'Actions: (1) Verify ciphertext integrity (not truncated), (2) Check secret key is valid, (3) Confirm ciphertext matches secret key, (4) Verify ML-KEM library is initialized',
+        suggested_action: 'Verify ciphertext integrity and ML-KEM secret key',
+        severity: 'high',
+        docs: `${DOC_BASE}#key-agreement`,
+    },
+    HKDF_FAILED: {
+        message: 'HKDF key derivation failed',
+        hint: 'Actions: (1) Verify both ECDH and KEM shared secrets are valid, (2) Check HKDF input size, (3) Ensure hash algorithm (SHA-256) is available, (4) Review Web Crypto HKDF implementation',
+        suggested_action: 'Verify shared secrets are valid and SHA-256 is available',
+        severity: 'high',
+        docs: `${DOC_BASE}#key-agreement`,
+    },
+    MLKEM_NOT_AVAILABLE: {
+        message: 'ML-KEM-768 key not available',
+        hint: 'Actions: (1) Enable post-quantum: Agent.create({postQuantum: true}), (2) Check runtime supports ML-KEM-768, (3) Verify agent was initialized with PQ keys, (4) Regenerate identity with PQ enabled',
+        suggested_action: 'Create agent with postQuantum: true',
+        severity: 'medium',
+        docs: `${DOC_BASE}#key-agreement`,
+    },
+    PQ_SIGN_FAILED: {
+        message: 'ML-DSA-65 signing failed',
+        hint: 'Actions: (1) Verify ML-DSA-65 secret key is valid and not corrupted, (2) Check post-quantum support is enabled, (3) Ensure message to sign is not empty, (4) Review ML-DSA library logs',
+        suggested_action: 'Verify ML-DSA-65 secret key and post-quantum support',
+        severity: 'high',
+        docs: `${DOC_BASE}#identity`,
+    },
+    PQ_VERIFY_FAILED: {
+        message: 'ML-DSA-65 verification failed',
+        hint: 'Actions: (1) Verify public key matches signer, (2) Check signature format and encoding, (3) Confirm message matches what was signed, (4) Ensure post-quantum keys are synchronized',
+        suggested_action: 'Verify signer public key and signature format',
+        severity: 'high',
+        docs: `${DOC_BASE}#identity`,
+    },
+    // Split-channel
+    SPLIT_FAILED: {
+        message: 'XorIDA split failed',
+        hint: 'Actions: (1) Verify threshold <= shareCount, (2) Check threshold >= 2, (3) Validate payload size < 1MB, (4) Ensure sufficient memory for split operation',
+        suggested_action: 'Verify threshold parameters and payload size',
+        severity: 'high',
+        docs: `${DOC_BASE}#split-channel`,
+    },
+    INSUFFICIENT_SHARES: {
+        message: 'Not enough shares to reconstruct',
+        hint: 'Actions: (1) Log number of shares collected, (2) Check threshold requirement, (3) Collect more shares from recipients, (4) Verify shares are from same split (group ID match)',
+        suggested_action: 'Collect more shares to meet threshold requirement',
+        severity: 'high',
+        docs: `${DOC_BASE}#split-channel`,
+    },
+    INCONSISTENT_SHARES: {
+        message: 'Shares have mismatched group IDs or lengths',
+        hint: 'Actions: (1) Verify all shares are from same split, (2) Check group IDs match, (3) Ensure shares have same length, (4) Discard mismatched shares and request correct ones',
+        suggested_action: 'Verify all shares are from the same split operation',
+        severity: 'high',
+        docs: `${DOC_BASE}#split-channel`,
+    },
+    HMAC_VERIFICATION_FAILED: {
+        message: 'Share HMAC check failed',
+        hint: 'Actions: (1) Check share data is not corrupted in transit, (2) Verify share was not tampered with, (3) Confirm sender used correct HMAC key, (4) Request fresh share from sender',
+        suggested_action: 'Request fresh share from sender',
+        severity: 'critical',
+        docs: `${DOC_BASE}#split-channel`,
+    },
+    UNPAD_FAILED: {
+        message: 'Padding removal failed after reconstruction',
+        hint: 'Actions: (1) Verify reconstruction succeeded before unpadding, (2) Check reconstructed data is valid UTF-8, (3) Confirm padding algorithm matches (PKCS7), (4) Inspect raw reconstructed bytes',
+        suggested_action: 'Verify reconstruction succeeded and data is valid UTF-8',
+        severity: 'high',
+        docs: `${DOC_BASE}#split-channel`,
+    },
+    INVALID_SHARE_DATA: {
+        message: 'Share data is malformed',
+        hint: 'Actions: (1) Verify share is valid base64, (2) Check share structure (TLV format if applicable), (3) Log raw share bytes to inspect, (4) Request correctly-formatted share from sender',
+        suggested_action: 'Verify share is valid base64 and request correctly-formatted share',
+        severity: 'high',
+        docs: `${DOC_BASE}#split-channel`,
+    },
+    // Xchange
+    XCHANGE_KEYGEN_FAILED: {
+        message: 'Xchange key generation failed',
+        hint: 'Actions: (1) Verify Web Crypto API available (HTTPS/localhost), (2) Check runtime supports key generation, (3) Ensure sufficient entropy, (4) Retry with fresh context',
+        suggested_action: 'Verify Web Crypto API available and retry',
+        severity: 'high',
+        docs: `${DOC_BASE}#xchange`,
+    },
+    XCHANGE_ENCRYPT_FAILED: {
+        message: 'Xchange bundle encryption failed',
+        hint: 'Actions: (1) Check payload size < 64KB, (2) Verify encryption key is 32 bytes, (3) Ensure bundle structure is valid, (4) Review payload for null bytes',
+        suggested_action: 'Verify payload size and encryption key length',
+        severity: 'high',
+        docs: `${DOC_BASE}#xchange`,
+    },
+    XCHANGE_DECRYPT_FAILED: {
+        message: 'Xchange bundle decryption failed',
+        hint: 'Actions: (1) Verify reconstruction completed before decryption, (2) Check decryption key matches encryption key, (3) Confirm bundle integrity (auth tag valid), (4) Inspect bundle format',
+        suggested_action: 'Verify reconstruction completed and decryption key is correct',
+        severity: 'high',
+        docs: `${DOC_BASE}#xchange`,
+    },
+    INVALID_BUNDLE: {
+        message: 'Xchange bundle is malformed',
+        hint: 'Actions: (1) Verify bundle size >= 60 bytes (32B key + 12B IV + 16B tag), (2) Check bundle structure, (3) Decode and inspect bundle contents, (4) Request correctly-formed bundle',
+        suggested_action: 'Verify bundle size and request correctly-formed bundle',
+        severity: 'high',
+        docs: `${DOC_BASE}#xchange`,
+    },
+    // Agent (high-level)
+    IDENTITY_FAILED: {
+        message: 'Agent identity creation failed',
+        hint: 'Actions: (1) Verify Web Crypto API available, (2) Check HTTPS or localhost context, (3) Ensure runtime is Node.js 15+ or modern browser, (4) Retry agent initialization',
+        suggested_action: 'Verify Web Crypto API available and retry agent initialization',
+        severity: 'critical',
+        docs: `${DOC_BASE}#agent`,
+    },
+    REGISTRATION_FAILED: {
+        message: 'Agent registration with trust registry failed',
+        hint: 'Actions: (1) Verify registry URL is correct and reachable, (2) Check auth token is valid and not expired, (3) Confirm registry is online (status page), (4) Retry with exponential backoff',
+        suggested_action: 'Verify registry URL and auth token, then retry with exponential backoff',
+        severity: 'high',
+        docs: `${DOC_BASE}#agent`,
+    },
+    RECIPIENT_NOT_FOUND: {
+        message: 'Recipient agent not found in registry',
+        hint: 'Actions: (1) Verify recipient email/DID is correct, (2) Ask recipient to register with XBind first, (3) Check registration on recipient side (inspect registry), (4) Wait for registration to propagate',
+        field: 'to',
+        suggested_action: 'Ask recipient to register with xBind',
+        severity: 'medium',
+        docs: `${DOC_BASE}#agent`,
+    },
+    RECIPIENT_REVOKED: {
+        message: 'Recipient agent has been revoked',
+        hint: 'Actions: (1) Inform recipient to contact registry admin, (2) Verify revocation reason, (3) Request re-registration if accidental, (4) Confirm revocation status via registry lookup',
+        field: 'to',
+        suggested_action: 'Inform recipient to contact registry administrator',
+        severity: 'high',
+        docs: `${DOC_BASE}#agent`,
+    },
+    KEY_AGREEMENT_FAILED: {
+        message: 'ECDH key agreement with recipient failed',
+        hint: 'Actions: (1) Verify recipient public key is valid, (2) Check key format (X25519, 32 bytes), (3) Confirm keys from same algorithm family, (4) Request fresh key from recipient',
+        suggested_action: 'Request fresh key from recipient',
+        severity: 'high',
+        docs: `${DOC_BASE}#agent`,
+    },
+    ENVELOPE_FAILED: {
+        message: 'Envelope creation failed',
+        hint: 'Actions: (1) Check payload size < 10MB, (2) Verify recipient DID is valid, (3) Confirm sender identity is set, (4) Validate all required fields present',
+        suggested_action: 'Verify payload size and recipient DID',
+        severity: 'high',
+        docs: `${DOC_BASE}#agent`,
+    },
+    VERIFICATION_FAILED: {
+        message: 'Incoming envelope verification failed',
+        hint: 'Actions: (1) Check sender DID is in trust registry, (2) Verify sender signature is valid, (3) Confirm sender is not revoked, (4) Review trust policy settings',
+        suggested_action: 'Verify sender is in trust registry and not revoked',
+        severity: 'critical',
+        docs: `${DOC_BASE}#agent`,
+    },
+    REPLAY_DETECTED: {
+        message: 'Duplicate nonce detected — possible replay attack',
+        hint: 'Actions: (1) DISCARD MESSAGE for security, (2) Log nonce and sender DID, (3) Alert user to potential attack, (4) Check for compromised sender account',
+        suggested_action: 'DISCARD MESSAGE and alert user to potential replay attack',
+        severity: 'critical',
+        docs: `${DOC_BASE}#agent`,
+    },
+    SCOPE_DENIED: {
+        message: 'Sender does not have permission for the requested scope',
+        hint: 'Actions: (1) Check sender scope permissions in registry, (2) Verify scope value is correct, (3) Contact registry admin to grant permission, (4) Confirm sender registered with requested scope',
+        field: 'scope',
+        suggested_action: 'Contact registry admin to grant permission',
+        severity: 'medium',
+        docs: `${DOC_BASE}#agent`,
+    },
+    RECEIVER_SCOPE_DENIED: {
+        message: 'Recipient does not accept messages with this scope',
+        hint: 'Actions: (1) Check recipient receive scope settings, (2) Verify scope matches recipient policy, (3) Ask recipient to enable scope in settings, (4) Confirm recipient registry entry',
+        field: 'scope',
+        suggested_action: 'Ask recipient to enable scope in settings',
+        severity: 'medium',
+        docs: `${DOC_BASE}#agent`,
+    },
+    TIMESTAMP_EXPIRED: {
+        message: 'Envelope timestamp is outside the allowed window',
+        hint: 'Actions: (1) Synchronize system clocks (NTP), (2) Check time difference between sender and receiver, (3) Increase timestamp window (if configurable), (4) Verify no system time drift',
+        suggested_action: 'Synchronize system clocks using NTP',
+        severity: 'medium',
+        docs: `${DOC_BASE}#agent`,
+    },
+};
+/** Error messages keyed by code. Includes what happened and what to do next. */
+const ERROR_MESSAGES = {
+    // Identity
+    KEYGEN_FAILED: [XBindIdentityError, 'Key generation failed. Actions: (1) Verify Web Crypto API is available in HTTPS or localhost, (2) Check runtime is Node.js 15+ or modern browser, (3) Retry initialization.'],
+    SIGN_FAILED: [XBindIdentityError, 'Signing failed. Actions: (1) Verify private key is valid and not corrupted, (2) Check key was properly imported, (3) Ensure key is extractable.'],
+    VERIFY_FAILED: [XBindIdentityError, 'Signature verification failed. Actions: (1) Confirm public key matches signer, (2) Check message integrity, (3) Verify signature format is valid base64.'],
+    INVALID_DID: [XBindIdentityError, 'The DID string is malformed. Actions: (1) Verify format: did:key:z6Mk..., (2) Check no extra whitespace, (3) Use validateDID() helper.'],
+    INVALID_KEY_LENGTH: [XBindKeyAgreementError, 'Key material is the wrong length. Actions: (1) Verify X25519 key is exactly 32 bytes, (2) Check base64 decoding, (3) Log key.length to confirm.'],
+    EXPORT_FAILED: [XBindIdentityError, 'PKCS8 export failed. Actions: (1) Create key with extractable:true, (2) Check Web Crypto support, (3) See: https://mdn.io/SubtleCrypto.exportKey.'],
+    IMPORT_FAILED: [XBindIdentityError, 'PKCS8 import failed. Actions: (1) Validate PKCS8 format (PEM or bytes), (2) Decode base64 if needed, (3) Check algorithm (Ed25519/X25519).'],
+    // Envelope
+    INVALID_VERSION: [XBindEnvelopeError, 'Unsupported envelope version. Actions: (1) Check envelope.version field, (2) Verify sender uses v1-v4, (3) Request sender SDK update.'],
+    INVALID_ALG: [XBindEnvelopeError, 'Unknown encryption algorithm. Actions: (1) Verify envelope.alg === "AES-256-GCM", (2) Log alg value to debug, (3) Check sender SDK version.'],
+    INVALID_NONCE: [XBindEnvelopeError, 'Nonce is missing or invalid. Actions: (1) Verify nonce exists and is 12 bytes, (2) Check base64 decoding, (3) Inspect replay buffer.'],
+    INVALID_FIELDS: [XBindEnvelopeError, 'Required envelope fields are missing. Actions: (1) Verify sender/recipient DIDs, (2) Check payload exists, (3) Validate: version, alg, nonce, ciphertext, tag.'],
+    ENCRYPT_FAILED: [XBindEnvelopeError, 'AES-256-GCM encryption failed. Actions: (1) Verify key is exactly 32 bytes, (2) Check plaintext is valid, (3) Ensure nonce is 12 bytes.'],
+    DECRYPT_FAILED: [XBindEnvelopeError, 'Decryption failed. Actions: (1) Verify correct key is being used, (2) Check ciphertext integrity, (3) Confirm auth tag is valid.'],
+    PARSE_FAILED: [XBindEnvelopeError, 'Envelope deserialization failed. Actions: (1) Validate JSON structure, (2) Check for truncation, (3) Verify base64 encoding of fields.'],
+    // Transport
+    SEND_FAILED: [XBindTransportError, 'Message send failed. Actions: (1) Check network connectivity (ping registry), (2) Verify recipient address, (3) Confirm recipient registered, (4) Retry with backoff.'],
+    NETWORK_ERROR: [XBindTransportError, 'Network request failed. Actions: (1) Verify internet connection, (2) Check DNS resolution, (3) Ping registry endpoint, (4) Implement exponential backoff (2s, 4s, 8s).'],
+    RECIPIENT_UNREACHABLE: [XBindTransportError, 'Recipient is unreachable. Actions: (1) Verify recipient email is correct, (2) Check if recipient is registered, (3) Confirm recipient is online, (4) Provide human follow-up.'],
+    TIMEOUT: [XBindTransportError, 'Transport operation timed out. Actions: (1) Increase timeout threshold, (2) Check network latency, (3) Verify registry responsiveness, (4) Retry operation.'],
+    // Registry
+    NOT_FOUND: [XBindRegistryError, 'Agent not found in trust registry. Actions: (1) Ask recipient to register with xBind, (2) Verify recipient email/DID, (3) Check registration status, (4) Retry after propagation.'],
+    ALREADY_REGISTERED: [XBindRegistryError, 'Agent is already registered. Actions: (1) Use updateAgent() instead, (2) Provide new keys or metadata, (3) Verify DID matches existing entry.'],
+    REVOKED: [XBindRegistryError, 'Agent has been revoked from the registry. Actions: (1) Contact registry admin, (2) Check revocation reason, (3) Request re-registration if accidental.'],
+    // Key agreement
+    DERIVE_FAILED: [XBindKeyAgreementError, 'ECDH key derivation failed. Actions: (1) Verify peer public key is valid X25519 (32 bytes), (2) Check key is not corrupted, (3) Confirm X25519 ECDH support.'],
+    KEM_ENCAPSULATE_FAILED: [XBindKeyAgreementError, 'ML-KEM-768 encapsulation failed. Actions: (1) Verify recipient key is valid ML-KEM-768, (2) Check key format, (3) Confirm post-quantum support enabled.'],
+    KEM_DECAPSULATE_FAILED: [XBindKeyAgreementError, 'ML-KEM-768 decapsulation failed. Actions: (1) Verify ciphertext integrity, (2) Check secret key is valid, (3) Confirm ciphertext matches key.'],
+    HKDF_FAILED: [XBindKeyAgreementError, 'HKDF key derivation failed. Actions: (1) Verify both shared secrets are valid, (2) Check HKDF input size, (3) Ensure SHA-256 support.'],
+    MLKEM_NOT_AVAILABLE: [XBindKeyAgreementError, 'ML-KEM-768 key not available. Actions: (1) Create agent with postQuantum: true, (2) Check runtime supports ML-KEM-768, (3) Regenerate identity with PQ enabled.'],
+    PQ_SIGN_FAILED: [XBindIdentityError, 'ML-DSA-65 signing failed. Actions: (1) Verify secret key is valid, (2) Check post-quantum support enabled, (3) Ensure message is not empty.'],
+    PQ_VERIFY_FAILED: [XBindIdentityError, 'ML-DSA-65 verification failed. Actions: (1) Verify public key matches signer, (2) Check signature format, (3) Confirm message integrity.'],
+    // Split-channel
+    SPLIT_FAILED: [XBindSplitChannelError, 'XorIDA split failed. Actions: (1) Verify threshold <= shareCount, (2) Check threshold >= 2, (3) Validate payload < 1MB.'],
+    INSUFFICIENT_SHARES: [XBindSplitChannelError, 'Not enough shares to reconstruct. Actions: (1) Log number of shares collected, (2) Check threshold requirement, (3) Collect more shares.'],
+    INCONSISTENT_SHARES: [XBindSplitChannelError, 'Shares have mismatched group IDs or lengths. Actions: (1) Verify all from same split, (2) Check group IDs match, (3) Discard mismatched shares.'],
+    HMAC_VERIFICATION_FAILED: [XBindSplitChannelError, 'Share HMAC check failed. Actions: (1) Check share integrity in transit, (2) Verify not tampered with, (3) Request fresh share.'],
+    UNPAD_FAILED: [XBindSplitChannelError, 'Padding removal failed after reconstruction. Actions: (1) Verify reconstruction succeeded, (2) Check data is valid UTF-8, (3) Inspect raw bytes.'],
+    INVALID_SHARE_DATA: [XBindSplitChannelError, 'Share data is malformed. Actions: (1) Verify share is valid base64, (2) Check TLV structure, (3) Log raw bytes to inspect.'],
+    // Xchange (XorIDA key transport)
+    XCHANGE_KEYGEN_FAILED: [XBindKeyAgreementError, 'Xchange key generation failed. Actions: (1) Verify Web Crypto available (HTTPS/localhost), (2) Check runtime support, (3) Ensure entropy.'],
+    XCHANGE_ENCRYPT_FAILED: [XBindEnvelopeError, 'Xchange bundle encryption failed. Actions: (1) Check payload < 64KB, (2) Verify key is 32 bytes, (3) Validate bundle structure.'],
+    XCHANGE_DECRYPT_FAILED: [XBindEnvelopeError, 'Xchange bundle decryption failed. Actions: (1) Verify reconstruction succeeded, (2) Check key matches encryption key, (3) Confirm bundle integrity.'],
+    INVALID_BUNDLE: [XBindSplitChannelError, 'Xchange bundle is malformed. Actions: (1) Verify size >= 60 bytes (32B + 12B + 16B), (2) Check structure, (3) Decode to inspect.'],
+    // Agent (high-level)
+    IDENTITY_FAILED: [XBindAgentError, 'Agent identity creation failed. Actions: (1) Verify Web Crypto available, (2) Check HTTPS/localhost, (3) Ensure Node.js 15+ or modern browser.'],
+    REGISTRATION_FAILED: [XBindAgentError, 'Agent registration with trust registry failed. Actions: (1) Verify registry URL is correct, (2) Check auth token valid/not expired, (3) Confirm registry online.'],
+    RECIPIENT_NOT_FOUND: [XBindAgentError, 'Recipient agent not found in registry. Actions: (1) Verify recipient email/DID, (2) Ask recipient to register first, (3) Wait for propagation.'],
+    RECIPIENT_REVOKED: [XBindAgentError, 'Recipient agent has been revoked. Actions: (1) Inform recipient to contact admin, (2) Verify revocation reason, (3) Request re-registration.'],
+    KEY_AGREEMENT_FAILED: [XBindAgentError, 'ECDH key agreement with recipient failed. Actions: (1) Verify recipient key valid, (2) Check key format (X25519, 32B), (3) Request fresh key.'],
+    ENVELOPE_FAILED: [XBindAgentError, 'Envelope creation failed. Actions: (1) Check payload < 10MB, (2) Verify recipient DID valid, (3) Confirm sender identity set.'],
+    VERIFICATION_FAILED: [XBindAgentError, 'Incoming envelope verification failed. Actions: (1) Check sender in registry, (2) Verify signature valid, (3) Confirm sender not revoked.'],
+    REPLAY_DETECTED: [XBindAgentError, 'Duplicate nonce detected — possible replay attack. Actions: (1) DISCARD message, (2) Log nonce/sender, (3) Alert user to potential attack.'],
+    SCOPE_DENIED: [XBindAgentError, 'Sender does not have permission for the requested scope. Actions: (1) Check sender scope in registry, (2) Contact admin to grant, (3) Verify scope value.'],
+    RECEIVER_SCOPE_DENIED: [XBindAgentError, 'Recipient does not accept messages with this scope. Actions: (1) Check recipient receive scope settings, (2) Ask to enable scope, (3) Verify registry entry.'],
+    TIMESTAMP_EXPIRED: [XBindAgentError, 'Envelope timestamp is outside the allowed window. Actions: (1) Synchronize system clocks (NTP), (2) Check time difference, (3) Verify no time drift.'],
+};
+/**
+ * Convert a string error code to a typed XBindError instance.
+ * Handles colon-separated sub-codes (e.g. 'DECRYPT_FAILED:KEY_AGREEMENT').
+ * Falls back to base XBindError for unknown codes.
+ *
+ * @param code - Error code string from Result<T,E> (e.g. 'REPLAY_DETECTED')
+ * @returns Typed XBindError subclass instance
+ */
+export function toXBindError(code) {
+    const baseCode = code.split(':')[0] ?? code;
+    const entry = ERROR_MESSAGES[baseCode];
+    if (entry) {
+        const [ErrorClass, message] = entry;
+        return new ErrorClass(code, message);
+    }
+    return new XBindError(code, `XBind error: ${code}`);
+}
+/**
+ * Type guard for XBindError instances.
+ *
+ * @param err - Unknown value to check
+ * @returns True if err is a XBindError instance
+ */
+export function isXBindError(err) {
+    return err instanceof XBindError;
+}

package/dist-standalone/gateway-state.d.ts

@@ -0,0 +1,32 @@
+type AnyWebSocket = any;
+/**
+ * Gateway connection state manager.
+ *
+ * Online-only model: State evaporates immediately on disconnect.
+ * No 12-hour windows, no persistent state.
+ *
+ * Note: WebSocket type is runtime-dependent (browser WebSocket or 'ws' package).
+ */
+export declare class GatewayConnectionState {
+    private connections;
+    /**
+     * Register agent connection.
+     *
+     * @param did - DID of the connecting agent
+     * @param socket - WebSocket connection (browser or Node.js 'ws' package)
+     */
+    connect(did: string, socket: AnyWebSocket): void;
+    /**
+     * Check if agent is currently online.
+     */
+    isOnline(did: string): boolean;
+    /**
+     * Get WebSocket for online agent (or null if offline).
+     */
+    getSocket(did: string): AnyWebSocket | null;
+    /**
+     * Get all online DIDs.
+     */
+    getOnlineDids(): string[];
+}
+export {};

package/dist-standalone/gateway-state.js

@@ -0,0 +1,51 @@
+/**
+ * Gateway connection state manager.
+ *
+ * Online-only model: State evaporates immediately on disconnect.
+ * No 12-hour windows, no persistent state.
+ *
+ * Note: WebSocket type is runtime-dependent (browser WebSocket or 'ws' package).
+ */
+export class GatewayConnectionState {
+    connections = new Map(); // did → socket
+    /**
+     * Register agent connection.
+     *
+     * @param did - DID of the connecting agent
+     * @param socket - WebSocket connection (browser or Node.js 'ws' package)
+     */
+    connect(did, socket) {
+        this.connections.set(did, socket);
+        // Handle close event (works for both browser and Node.js ws)
+        if (typeof socket.on === 'function') {
+            // Node.js 'ws' package style
+            socket.on('close', () => {
+                this.connections.delete(did); // Immediate evaporation
+            });
+        }
+        else if (socket.addEventListener) {
+            // Browser WebSocket style
+            socket.addEventListener('close', () => {
+                this.connections.delete(did);
+            });
+        }
+    }
+    /**
+     * Check if agent is currently online.
+     */
+    isOnline(did) {
+        return this.connections.has(did);
+    }
+    /**
+     * Get WebSocket for online agent (or null if offline).
+     */
+    getSocket(did) {
+        return this.connections.get(did) ?? null;
+    }
+    /**
+     * Get all online DIDs.
+     */
+    getOnlineDids() {
+        return Array.from(this.connections.keys());
+    }
+}