@private.me/xbind 1.3.5 → 3.0.0

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

@@ -1,561 +1 @@
-/**
- * @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]);
-}
+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])}

package/dist-standalone/identity.d.ts

@@ -1,4 +1,13 @@
 import type { Result } from '@private.me/shared';
+/** Rotated key material (preserved for decryption of old messages). */
+export interface RotatedKeys {
+    /** Timestamp when keys were rotated (milliseconds since epoch). */
+    readonly rotatedAt: number;
+    /** Previous X25519 private key for decrypting messages encrypted with old key. */
+    readonly x25519PrivateKey: CryptoKey;
+    /** Previous ML-KEM-768 secret key for hybrid decryption. */
+    readonly mlKemSecretKey?: Uint8Array;
+}
 /** Agent cryptographic identity backed by Ed25519 keypair. */
 export interface AgentIdentity {
     /** Decentralized identifier: did:key:z6Mk... */
@@ -23,12 +32,37 @@ export interface AgentIdentity {
     readonly mlDsaPublicKey?: Uint8Array;
     /** ML-DSA-65 secret key (4032 bytes) for hybrid post-quantum signatures. */
     readonly mlDsaSecretKey?: Uint8Array;
+    /** Previous rotated keys (for backward-compatible decryption). */
+    readonly rotatedKeys?: RotatedKeys[];
 }
 /** Error codes for identity operations. */
-export type IdentityError = 'KEYGEN_FAILED' | 'SIGN_FAILED' | 'VERIFY_FAILED' | 'INVALID_DID' | 'INVALID_KEY_LENGTH' | 'EXPORT_FAILED' | 'IMPORT_FAILED';
+export type IdentityError = 'KEYGEN_FAILED' | 'SIGN_FAILED' | 'VERIFY_FAILED' | 'INVALID_DID' | 'INVALID_KEY_LENGTH' | 'EXPORT_FAILED' | 'IMPORT_FAILED' | 'ROTATION_FAILED';
 /**
  * Generate a new Ed25519 agent identity.
  * Creates keypair via Web Crypto API, derives did:key DID.
+ *
+ * @param opts - Optional configuration
+ * @param opts.postQuantumSig - Enable ML-DSA-65 post-quantum signatures (default: false)
+ * @returns Result containing the agent identity or error
+ *
+ * @example
+ * ```typescript
+ * import { generateIdentity } from '@private.me/xbind';
+ *
+ * // Generate identity with classical cryptography only
+ * const identity = await generateIdentity();
+ * if (!identity.ok) {
+ *   throw new Error(`Failed to generate identity: ${identity.error}`);
+ * }
+ * console.log('DID:', identity.value.did);
+ *
+ * // Generate identity with post-quantum signatures
+ * const pqIdentity = await generateIdentity({ postQuantumSig: true });
+ * if (pqIdentity.ok) {
+ *   console.log('Post-quantum DID:', pqIdentity.value.did);
+ *   console.log('Has ML-DSA key:', !!pqIdentity.value.mlDsaPublicKey);
+ * }
+ * ```
  */
 export declare function generateIdentity(opts?: {
     postQuantumSig?: boolean;
@@ -174,3 +208,32 @@ export declare function extractRawEd25519(pkcs8: Uint8Array): Result<Uint8Array,
  * @returns 32-byte raw private key or error.
  */
 export declare function extractRawX25519(pkcs8: Uint8Array): Result<Uint8Array, IdentityError>;
+/**
+ * Rotate ML-KEM + X25519 keys while preserving old keys for decryption.
+ *
+ * Generates new X25519 and ML-KEM-768 keypairs. Saves the old keys
+ * in rotatedKeys array (with timestamp) for backward-compatible decryption
+ * of messages encrypted with the old keys. Ed25519 keys (for signing) are
+ * NOT rotated — they remain constant for persistent identity.
+ *
+ * After rotation:
+ * - New messages use the new X25519 + ML-KEM keys
+ * - Old messages decrypt using preserved rotatedKeys
+ * - DID remains unchanged (anchored to Ed25519 public key)
+ * - Registry must be updated with new X25519 + ML-KEM public keys
+ *
+ * @param identity - Current identity with keys to rotate
+ * @returns Updated identity with new keys + old keys in rotatedKeys array, or error
+ *
+ * @example
+ * ```ts
+ * const rotated = await identity.rotateKeys();
+ * if (rotated.ok) {
+ *   // New keys are active; old keys preserved for decryption
+ *   console.log('Rotated at:', rotated.value.rotatedKeys?.[0]?.rotatedAt);
+ *   // Update registry with new X25519 + ML-KEM public keys
+ *   await registry.updateKeys(rotated.value.did, rotated.value.rawX25519PublicKey, rotated.value.mlKemPublicKey);
+ * }
+ * ```
+ */
+export declare function rotateKeys(identity: AgentIdentity): Promise<Result<AgentIdentity, IdentityError>>;