@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/http-status-map.js

@@ -1 +1,561 @@
-export const HTTP_STATUS_MAP={KEYGEN_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Identity",rationale:"Server crypto initialization failure - client should retry"},SIGN_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!1,errorType:"Server",category:"Identity",rationale:"Server key corruption - requires admin intervention"},VERIFY_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Identity",rationale:"Invalid signature - authentication failure"},INVALID_DID:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Identity",rationale:"Malformed DID format - client validation error"},INVALID_KEY_LENGTH:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Identity",rationale:"Invalid key material size - client validation error"},EXPORT_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Identity",rationale:"Crypto API failure - transient server issue"},IMPORT_FAILED:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Identity",rationale:"Invalid PKCS8 format - client validation error"},INVALID_VERSION:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Envelope",rationale:"Unsupported protocol version - client must upgrade"},INVALID_ALG:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Envelope",rationale:"Unsupported algorithm - client must use AES-256-GCM"},INVALID_NONCE:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Envelope",rationale:"Missing or invalid nonce - client validation error"},INVALID_FIELDS:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Envelope",rationale:"Missing required envelope fields - client validation error"},ENCRYPT_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Envelope",rationale:"Server encryption failure - transient issue"},DECRYPT_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Envelope",rationale:"Decryption failed - wrong key or corrupted data"},PARSE_FAILED:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Envelope",rationale:"Malformed JSON envelope - client validation error"},SEND_FAILED:{statusCode:503,statusText:"Service Unavailable",retryable:!0,errorType:"Server",category:"Transport",rationale:"Network send failure - retry with backoff"},NETWORK_ERROR:{statusCode:503,statusText:"Service Unavailable",retryable:!0,errorType:"Server",category:"Transport",rationale:"Network connectivity issue - retry with backoff"},RECIPIENT_UNREACHABLE:{statusCode:503,statusText:"Service Unavailable",retryable:!0,errorType:"Server",category:"Transport",rationale:"Recipient offline or unreachable - retry later"},TIMEOUT:{statusCode:504,statusText:"Gateway Timeout",retryable:!0,errorType:"Server",category:"Transport",rationale:"Request timed out - increase timeout and retry"},NOT_FOUND:{statusCode:404,statusText:"Not Found",retryable:!1,errorType:"Client",category:"Registry",rationale:"Agent not in registry - recipient must register first"},ALREADY_REGISTERED:{statusCode:409,statusText:"Conflict",retryable:!1,errorType:"Client",category:"Registry",rationale:"DID already exists - use updateAgent instead"},REVOKED:{statusCode:403,statusText:"Forbidden",retryable:!1,errorType:"Client",category:"Registry",rationale:"Agent revoked - contact admin for re-registration"},DERIVE_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Key Agreement",rationale:"ECDH derivation failure - transient crypto issue"},KEM_ENCAPSULATE_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Key Agreement",rationale:"ML-KEM encapsulation failure - transient crypto issue"},KEM_DECAPSULATE_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Key Agreement",rationale:"ML-KEM decapsulation failed - wrong ciphertext"},HKDF_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Key Agreement",rationale:"HKDF derivation failure - transient crypto issue"},MLKEM_NOT_AVAILABLE:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Key Agreement",rationale:"Post-quantum not enabled - client must configure"},PQ_SIGN_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Key Agreement",rationale:"ML-DSA signing failure - transient crypto issue"},PQ_VERIFY_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Key Agreement",rationale:"ML-DSA verification failed - invalid signature"},SPLIT_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Split Channel",rationale:"XorIDA split failure - transient issue"},INSUFFICIENT_SHARES:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Split Channel",rationale:"Not enough shares - client must collect more"},INCONSISTENT_SHARES:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Split Channel",rationale:"Mismatched shares - client validation error"},HMAC_VERIFICATION_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Split Channel",rationale:"Share tampered with - security violation"},UNPAD_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!1,errorType:"Server",category:"Split Channel",rationale:"Padding removal error - data corruption"},INVALID_SHARE_DATA:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Split Channel",rationale:"Malformed share format - client validation error"},XCHANGE_KEYGEN_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Xchange",rationale:"Key generation failure - transient crypto issue"},XCHANGE_ENCRYPT_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Xchange",rationale:"Bundle encryption failure - transient crypto issue"},XCHANGE_DECRYPT_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Xchange",rationale:"Bundle decryption failed - wrong key"},INVALID_BUNDLE:{statusCode:400,statusText:"Bad Request",retryable:!1,errorType:"Client",category:"Xchange",rationale:"Malformed bundle format - client validation error"},IDENTITY_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Agent",rationale:"Agent identity creation failed - transient issue"},REGISTRATION_FAILED:{statusCode:503,statusText:"Service Unavailable",retryable:!0,errorType:"Server",category:"Agent",rationale:"Registry unavailable - retry with backoff"},RECIPIENT_NOT_FOUND:{statusCode:404,statusText:"Not Found",retryable:!1,errorType:"Client",category:"Agent",rationale:"Recipient not in registry - recipient must register"},RECIPIENT_REVOKED:{statusCode:403,statusText:"Forbidden",retryable:!1,errorType:"Client",category:"Agent",rationale:"Recipient revoked - contact admin"},KEY_AGREEMENT_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Agent",rationale:"Key agreement failure - transient crypto issue"},ENVELOPE_FAILED:{statusCode:500,statusText:"Internal Server Error",retryable:!0,errorType:"Server",category:"Agent",rationale:"Envelope creation failed - transient issue"},VERIFICATION_FAILED:{statusCode:401,statusText:"Unauthorized",retryable:!1,errorType:"Client",category:"Agent",rationale:"Envelope verification failed - authentication error"},REPLAY_DETECTED:{statusCode:403,statusText:"Forbidden",retryable:!1,errorType:"Client",category:"Agent",rationale:"Replay attack detected - security violation"},SCOPE_DENIED:{statusCode:403,statusText:"Forbidden",retryable:!1,errorType:"Client",category:"Agent",rationale:"Sender lacks scope permission - authorization failure"},RECEIVER_SCOPE_DENIED:{statusCode:403,statusText:"Forbidden",retryable:!1,errorType:"Client",category:"Agent",rationale:"Recipient rejects scope - authorization failure"},TIMESTAMP_EXPIRED:{statusCode:400,statusText:"Bad Request",retryable:!0,errorType:"Client",category:"Agent",rationale:"Timestamp outside window - clock sync issue (retryable)"}};export function getHttpStatus(e){const t=e.split(":")[0]??e,r=HTTP_STATUS_MAP[t];return r?.statusCode??500}export function getStatusText(e){const t=e.split(":")[0]??e,r=HTTP_STATUS_MAP[t];return r?.statusText??"Internal Server Error"}export function isRetryable(e){const t=e.split(":")[0]??e,r=HTTP_STATUS_MAP[t];return r?.retryable??!1}export function getMapping(e){const t=e.split(":")[0]??e;return HTTP_STATUS_MAP[t]??null}export function getErrorCodesByCategory(e){return Object.entries(HTTP_STATUS_MAP).filter(([t,r])=>r.category===e).map(([e])=>e)}export function getRetryableErrorCodes(){return Object.entries(HTTP_STATUS_MAP).filter(([e,t])=>t.retryable).map(([e])=>e)}export function validateCoverage(e){return e.filter(e=>!HTTP_STATUS_MAP[e])}
+/**
+ * @module http-status-map
+ * Maps xBind error codes to HTTP status codes for REST API responses.
+ *
+ * This mapping provides:
+ * - Consistent HTTP status codes for all 52 xBind error codes
+ * - Retryability information for client retry logic
+ * - Error categorization (client vs server errors)
+ * - Human-readable status text
+ *
+ * Based on RFC 9110 HTTP Semantics and REST API best practices.
+ *
+ * @example
+ * ```typescript
+ * import { getHttpStatus, isRetryable } from '@private.me/xbind/http-status-map';
+ *
+ * const status = getHttpStatus('VERIFY_FAILED'); // 401
+ * const canRetry = isRetryable('NETWORK_ERROR');  // true
+ * ```
+ */
+/**
+ * Complete mapping of xBind error codes to HTTP status codes.
+ * All 52 error codes are mapped for 100% coverage.
+ */
+export const HTTP_STATUS_MAP = {
+    // ============================================================================
+    // IDENTITY (8 error codes)
+    // ============================================================================
+    KEYGEN_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Identity',
+        rationale: 'Server crypto initialization failure - client should retry',
+    },
+    SIGN_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: false,
+        errorType: 'Server',
+        category: 'Identity',
+        rationale: 'Server key corruption - requires admin intervention',
+    },
+    VERIFY_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Identity',
+        rationale: 'Invalid signature - authentication failure',
+    },
+    INVALID_DID: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Identity',
+        rationale: 'Malformed DID format - client validation error',
+    },
+    INVALID_KEY_LENGTH: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Identity',
+        rationale: 'Invalid key material size - client validation error',
+    },
+    EXPORT_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Identity',
+        rationale: 'Crypto API failure - transient server issue',
+    },
+    IMPORT_FAILED: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Identity',
+        rationale: 'Invalid PKCS8 format - client validation error',
+    },
+    // ============================================================================
+    // ENVELOPE (7 error codes)
+    // ============================================================================
+    INVALID_VERSION: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Envelope',
+        rationale: 'Unsupported protocol version - client must upgrade',
+    },
+    INVALID_ALG: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Envelope',
+        rationale: 'Unsupported algorithm - client must use AES-256-GCM',
+    },
+    INVALID_NONCE: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Envelope',
+        rationale: 'Missing or invalid nonce - client validation error',
+    },
+    INVALID_FIELDS: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Envelope',
+        rationale: 'Missing required envelope fields - client validation error',
+    },
+    ENCRYPT_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Envelope',
+        rationale: 'Server encryption failure - transient issue',
+    },
+    DECRYPT_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Envelope',
+        rationale: 'Decryption failed - wrong key or corrupted data',
+    },
+    PARSE_FAILED: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Envelope',
+        rationale: 'Malformed JSON envelope - client validation error',
+    },
+    // ============================================================================
+    // TRANSPORT (4 error codes)
+    // ============================================================================
+    SEND_FAILED: {
+        statusCode: 503,
+        statusText: 'Service Unavailable',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Transport',
+        rationale: 'Network send failure - retry with backoff',
+    },
+    NETWORK_ERROR: {
+        statusCode: 503,
+        statusText: 'Service Unavailable',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Transport',
+        rationale: 'Network connectivity issue - retry with backoff',
+    },
+    RECIPIENT_UNREACHABLE: {
+        statusCode: 503,
+        statusText: 'Service Unavailable',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Transport',
+        rationale: 'Recipient offline or unreachable - retry later',
+    },
+    TIMEOUT: {
+        statusCode: 504,
+        statusText: 'Gateway Timeout',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Transport',
+        rationale: 'Request timed out - increase timeout and retry',
+    },
+    // ============================================================================
+    // REGISTRY (3 error codes)
+    // ============================================================================
+    NOT_FOUND: {
+        statusCode: 404,
+        statusText: 'Not Found',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Registry',
+        rationale: 'Agent not in registry - recipient must register first',
+    },
+    ALREADY_REGISTERED: {
+        statusCode: 409,
+        statusText: 'Conflict',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Registry',
+        rationale: 'DID already exists - use updateAgent instead',
+    },
+    REVOKED: {
+        statusCode: 403,
+        statusText: 'Forbidden',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Registry',
+        rationale: 'Agent revoked - contact admin for re-registration',
+    },
+    // ============================================================================
+    // KEY AGREEMENT (8 error codes)
+    // ============================================================================
+    DERIVE_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Key Agreement',
+        rationale: 'ECDH derivation failure - transient crypto issue',
+    },
+    KEM_ENCAPSULATE_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Key Agreement',
+        rationale: 'ML-KEM encapsulation failure - transient crypto issue',
+    },
+    KEM_DECAPSULATE_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Key Agreement',
+        rationale: 'ML-KEM decapsulation failed - wrong ciphertext',
+    },
+    HKDF_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Key Agreement',
+        rationale: 'HKDF derivation failure - transient crypto issue',
+    },
+    MLKEM_NOT_AVAILABLE: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Key Agreement',
+        rationale: 'Post-quantum not enabled - client must configure',
+    },
+    PQ_SIGN_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Key Agreement',
+        rationale: 'ML-DSA signing failure - transient crypto issue',
+    },
+    PQ_VERIFY_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Key Agreement',
+        rationale: 'ML-DSA verification failed - invalid signature',
+    },
+    // ============================================================================
+    // SPLIT CHANNEL (6 error codes)
+    // ============================================================================
+    SPLIT_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Split Channel',
+        rationale: 'XorIDA split failure - transient issue',
+    },
+    INSUFFICIENT_SHARES: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Split Channel',
+        rationale: 'Not enough shares - client must collect more',
+    },
+    INCONSISTENT_SHARES: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Split Channel',
+        rationale: 'Mismatched shares - client validation error',
+    },
+    HMAC_VERIFICATION_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Split Channel',
+        rationale: 'Share tampered with - security violation',
+    },
+    UNPAD_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: false,
+        errorType: 'Server',
+        category: 'Split Channel',
+        rationale: 'Padding removal error - data corruption',
+    },
+    INVALID_SHARE_DATA: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Split Channel',
+        rationale: 'Malformed share format - client validation error',
+    },
+    // ============================================================================
+    // XCHANGE (4 error codes)
+    // ============================================================================
+    XCHANGE_KEYGEN_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Xchange',
+        rationale: 'Key generation failure - transient crypto issue',
+    },
+    XCHANGE_ENCRYPT_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Xchange',
+        rationale: 'Bundle encryption failure - transient crypto issue',
+    },
+    XCHANGE_DECRYPT_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Xchange',
+        rationale: 'Bundle decryption failed - wrong key',
+    },
+    INVALID_BUNDLE: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Xchange',
+        rationale: 'Malformed bundle format - client validation error',
+    },
+    // ============================================================================
+    // AGENT (12 error codes)
+    // ============================================================================
+    IDENTITY_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Agent',
+        rationale: 'Agent identity creation failed - transient issue',
+    },
+    REGISTRATION_FAILED: {
+        statusCode: 503,
+        statusText: 'Service Unavailable',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Agent',
+        rationale: 'Registry unavailable - retry with backoff',
+    },
+    RECIPIENT_NOT_FOUND: {
+        statusCode: 404,
+        statusText: 'Not Found',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Recipient not in registry - recipient must register',
+    },
+    RECIPIENT_REVOKED: {
+        statusCode: 403,
+        statusText: 'Forbidden',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Recipient revoked - contact admin',
+    },
+    KEY_AGREEMENT_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Agent',
+        rationale: 'Key agreement failure - transient crypto issue',
+    },
+    ENVELOPE_FAILED: {
+        statusCode: 500,
+        statusText: 'Internal Server Error',
+        retryable: true,
+        errorType: 'Server',
+        category: 'Agent',
+        rationale: 'Envelope creation failed - transient issue',
+    },
+    VERIFICATION_FAILED: {
+        statusCode: 401,
+        statusText: 'Unauthorized',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Envelope verification failed - authentication error',
+    },
+    REPLAY_DETECTED: {
+        statusCode: 403,
+        statusText: 'Forbidden',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Replay attack detected - security violation',
+    },
+    SCOPE_DENIED: {
+        statusCode: 403,
+        statusText: 'Forbidden',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Sender lacks scope permission - authorization failure',
+    },
+    RECEIVER_SCOPE_DENIED: {
+        statusCode: 403,
+        statusText: 'Forbidden',
+        retryable: false,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Recipient rejects scope - authorization failure',
+    },
+    TIMESTAMP_EXPIRED: {
+        statusCode: 400,
+        statusText: 'Bad Request',
+        retryable: true,
+        errorType: 'Client',
+        category: 'Agent',
+        rationale: 'Timestamp outside window - clock sync issue (retryable)',
+    },
+};
+/**
+ * Get HTTP status code for a given xBind error code.
+ * Handles colon-separated sub-codes (e.g., 'DECRYPT_FAILED:KEY_AGREEMENT').
+ *
+ * @param errorCode - xBind error code (e.g., 'VERIFY_FAILED')
+ * @returns HTTP status code (e.g., 401) or 500 if unknown
+ *
+ * @example
+ * ```typescript
+ * getHttpStatus('VERIFY_FAILED')           // 401
+ * getHttpStatus('DECRYPT_FAILED:NETWORK')  // 401 (ignores sub-code)
+ * getHttpStatus('UNKNOWN_ERROR')           // 500 (fallback)
+ * ```
+ */
+export function getHttpStatus(errorCode) {
+    const baseCode = errorCode.split(':')[0] ?? errorCode;
+    const mapping = HTTP_STATUS_MAP[baseCode];
+    return mapping?.statusCode ?? 500; // Default to 500 for unknown errors
+}
+/**
+ * Get HTTP status text for a given xBind error code.
+ *
+ * @param errorCode - xBind error code (e.g., 'VERIFY_FAILED')
+ * @returns HTTP status text (e.g., 'Unauthorized') or 'Internal Server Error' if unknown
+ *
+ * @example
+ * ```typescript
+ * getStatusText('VERIFY_FAILED')  // 'Unauthorized'
+ * getStatusText('NOT_FOUND')      // 'Not Found'
+ * ```
+ */
+export function getStatusText(errorCode) {
+    const baseCode = errorCode.split(':')[0] ?? errorCode;
+    const mapping = HTTP_STATUS_MAP[baseCode];
+    return mapping?.statusText ?? 'Internal Server Error';
+}
+/**
+ * Check if an error is retryable by the client.
+ *
+ * @param errorCode - xBind error code (e.g., 'NETWORK_ERROR')
+ * @returns True if the client should retry the operation
+ *
+ * @example
+ * ```typescript
+ * isRetryable('NETWORK_ERROR')    // true  (503 - retry with backoff)
+ * isRetryable('VERIFY_FAILED')    // false (401 - authentication failure)
+ * isRetryable('KEYGEN_FAILED')    // true  (500 - transient server issue)
+ * ```
+ */
+export function isRetryable(errorCode) {
+    const baseCode = errorCode.split(':')[0] ?? errorCode;
+    const mapping = HTTP_STATUS_MAP[baseCode];
+    return mapping?.retryable ?? false; // Default to non-retryable for unknown errors
+}
+/**
+ * Get complete mapping information for an error code.
+ *
+ * @param errorCode - xBind error code (e.g., 'VERIFY_FAILED')
+ * @returns Complete mapping information or null if not found
+ *
+ * @example
+ * ```typescript
+ * const mapping = getMapping('VERIFY_FAILED');
+ * if (mapping) {
+ *   console.log(`${mapping.statusCode} ${mapping.statusText}`);
+ *   console.log(`Retryable: ${mapping.retryable}`);
+ *   console.log(`Rationale: ${mapping.rationale}`);
+ * }
+ * ```
+ */
+export function getMapping(errorCode) {
+    const baseCode = errorCode.split(':')[0] ?? errorCode;
+    return HTTP_STATUS_MAP[baseCode] ?? null;
+}
+/**
+ * Get all error codes in a specific category.
+ *
+ * @param category - Error category (e.g., 'Identity', 'Transport')
+ * @returns Array of error codes in that category
+ *
+ * @example
+ * ```typescript
+ * const identityErrors = getErrorCodesByCategory('Identity');
+ * // ['KEYGEN_FAILED', 'SIGN_FAILED', 'VERIFY_FAILED', ...]
+ * ```
+ */
+export function getErrorCodesByCategory(category) {
+    return Object.entries(HTTP_STATUS_MAP)
+        .filter(([_, mapping]) => mapping.category === category)
+        .map(([code]) => code);
+}
+/**
+ * Get all retryable error codes.
+ *
+ * @returns Array of error codes that are retryable
+ *
+ * @example
+ * ```typescript
+ * const retryableErrors = getRetryableErrorCodes();
+ * // ['KEYGEN_FAILED', 'EXPORT_FAILED', 'ENCRYPT_FAILED', ...]
+ * ```
+ */
+export function getRetryableErrorCodes() {
+    return Object.entries(HTTP_STATUS_MAP)
+        .filter(([_, mapping]) => mapping.retryable)
+        .map(([code]) => code);
+}
+/**
+ * Validate that all error codes from the CSV are mapped.
+ * This function is used for testing purposes to ensure 100% coverage.
+ *
+ * @param csvErrorCodes - Array of error codes from the CSV file
+ * @returns Array of missing error codes (empty if all mapped)
+ *
+ * @internal
+ */
+export function validateCoverage(csvErrorCodes) {
+    return csvErrorCodes.filter((code) => !HTTP_STATUS_MAP[code]);
+}