@private.me/xbind 1.2.0 → 1.2.1

package/dist-standalone/correlation-id.d.ts

@@ -0,0 +1,222 @@
+/**
+ * @module correlation-id
+ * Client-side correlation ID utilities for request tracking
+ *
+ * Correlation IDs enable distributed tracing across xBind agent operations,
+ * making it easier to debug issues, track requests across microservices,
+ * and correlate logs between client and server.
+ *
+ * Format: `req_{timestamp}_{random}`
+ * Example: `req_1716234567890_a3f5c9d2`
+ *
+ * Usage:
+ * ```typescript
+ * import { generateCorrelationId, attachCorrelationId } from '@private.me/xbind';
+ *
+ * // Generate a new correlation ID
+ * const id = generateCorrelationId();
+ *
+ * // Attach to request headers
+ * const headers = attachCorrelationId(new Headers(), id);
+ *
+ * // Validate format
+ * if (validateCorrelationId(id)) {
+ *   console.log('Valid correlation ID');
+ * }
+ * ```
+ */
+/**
+ * Correlation ID format specification
+ */
+export interface CorrelationIdSpec {
+    /** Prefix (always 'req') */
+    prefix: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Random hex string (8 characters) */
+    random: string;
+}
+/**
+ * Standard header name for correlation ID
+ */
+export declare const CORRELATION_ID_HEADER = "X-Correlation-ID";
+/**
+ * Alternative header names for compatibility
+ */
+export declare const CORRELATION_ID_ALIASES: readonly ["X-Request-ID", "X-Trace-ID", "X-Transaction-ID"];
+/**
+ * Generate a new correlation ID
+ *
+ * Format: `req_{timestamp}_{random}`
+ * - `req`: Static prefix for identification
+ * - `timestamp`: Unix timestamp in milliseconds (13 digits)
+ * - `random`: 8-character hex string for uniqueness
+ *
+ * @returns New correlation ID string
+ *
+ * @example
+ * ```typescript
+ * const id = generateCorrelationId();
+ * // => "req_1716234567890_a3f5c9d2"
+ * ```
+ */
+export declare function generateCorrelationId(): string;
+/**
+ * Validate correlation ID format
+ *
+ * Checks if the provided string matches the expected correlation ID format.
+ *
+ * @param id - String to validate
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validateCorrelationId('req_1716234567890_a3f5c9d2'); // => true
+ * validateCorrelationId('invalid'); // => false
+ * validateCorrelationId('req_123_abc'); // => false (wrong lengths)
+ * ```
+ */
+export declare function validateCorrelationId(id: unknown): id is string;
+/**
+ * Parse correlation ID into components
+ *
+ * Extracts the timestamp and random components from a correlation ID.
+ *
+ * @param id - Correlation ID to parse
+ * @returns Parsed components or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const spec = parseCorrelationId('req_1716234567890_a3f5c9d2');
+ * // => { prefix: 'req', timestamp: 1716234567890, random: 'a3f5c9d2' }
+ * ```
+ */
+export declare function parseCorrelationId(id: string): CorrelationIdSpec | null;
+/**
+ * Attach correlation ID to request headers
+ *
+ * Adds the correlation ID to the X-Correlation-ID header.
+ * If no ID is provided, generates a new one.
+ * Compatible with both Headers API and plain objects.
+ *
+ * @param headers - Headers object or plain object
+ * @param id - Correlation ID (generates new if not provided)
+ * @returns Updated headers object
+ *
+ * @example
+ * ```typescript
+ * // With Headers API
+ * const headers = new Headers();
+ * attachCorrelationId(headers);
+ *
+ * // With plain object
+ * const headers = { 'Content-Type': 'application/json' };
+ * attachCorrelationId(headers, 'req_1716234567890_a3f5c9d2');
+ *
+ * // With existing correlation ID
+ * const id = generateCorrelationId();
+ * attachCorrelationId(headers, id);
+ * ```
+ */
+export declare function attachCorrelationId<T extends Headers | Record<string, string>>(headers: T, id?: string): T;
+/**
+ * Extract correlation ID from request headers
+ *
+ * Checks the standard header and common aliases.
+ *
+ * @param headers - Headers object or plain object
+ * @returns Correlation ID if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const headers = new Headers({
+ *   'X-Correlation-ID': 'req_1716234567890_a3f5c9d2'
+ * });
+ * const id = extractCorrelationId(headers);
+ * // => 'req_1716234567890_a3f5c9d2'
+ * ```
+ */
+export declare function extractCorrelationId(headers: Headers | Record<string, string>): string | undefined;
+/**
+ * Get or create correlation ID from headers
+ *
+ * Returns existing correlation ID from headers, or generates a new one if not found.
+ * Does NOT modify the input headers.
+ *
+ * @param headers - Headers to check
+ * @returns Existing or new correlation ID
+ *
+ * @example
+ * ```typescript
+ * const headers = new Headers();
+ * const id = getOrCreateCorrelationId(headers);
+ * // => Generates new ID if not found in headers
+ * ```
+ */
+export declare function getOrCreateCorrelationId(headers?: Headers | Record<string, string>): string;
+/**
+ * Create a correlation ID from a timestamp
+ *
+ * Useful for testing or when you need deterministic IDs.
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @param random - Optional random component (generates if not provided)
+ * @returns Correlation ID
+ *
+ * @example
+ * ```typescript
+ * const id = createCorrelationIdFromTimestamp(1716234567890);
+ * // => 'req_1716234567890_a3f5c9d2'
+ *
+ * const deterministicId = createCorrelationIdFromTimestamp(1716234567890, 'aaaaaaaa');
+ * // => 'req_1716234567890_aaaaaaaa'
+ * ```
+ */
+export declare function createCorrelationIdFromTimestamp(timestamp: number, random?: string): string;
+/**
+ * Calculate age of correlation ID in milliseconds
+ *
+ * @param id - Correlation ID
+ * @returns Age in milliseconds, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const id = generateCorrelationId();
+ * setTimeout(() => {
+ *   const age = getCorrelationIdAge(id);
+ *   console.log(`Request age: ${age}ms`);
+ * }, 1000);
+ * ```
+ */
+export declare function getCorrelationIdAge(id: string): number | null;
+/**
+ * Check if correlation ID is expired
+ *
+ * @param id - Correlation ID
+ * @param maxAgeMs - Maximum age in milliseconds (default: 5 minutes)
+ * @returns True if expired, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const id = generateCorrelationId();
+ * if (isCorrelationIdExpired(id, 60000)) {
+ *   console.log('Request older than 1 minute');
+ * }
+ * ```
+ */
+export declare function isCorrelationIdExpired(id: string, maxAgeMs?: number): boolean;
+/**
+ * Middleware helper for Express/Koa-style frameworks
+ *
+ * Automatically attaches correlation ID to incoming requests.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { correlationIdMiddleware } from '@private.me/xbind';
+ *
+ * const app = express();
+ * app.use(correlationIdMiddleware());
+ * ```
+ */
+export declare function correlationIdMiddleware(): (req: any, res: any, next: any) => void;

package/dist-standalone/correlation-id.js

@@ -0,0 +1,326 @@
+/**
+ * @module correlation-id
+ * Client-side correlation ID utilities for request tracking
+ *
+ * Correlation IDs enable distributed tracing across xBind agent operations,
+ * making it easier to debug issues, track requests across microservices,
+ * and correlate logs between client and server.
+ *
+ * Format: `req_{timestamp}_{random}`
+ * Example: `req_1716234567890_a3f5c9d2`
+ *
+ * Usage:
+ * ```typescript
+ * import { generateCorrelationId, attachCorrelationId } from '@private.me/xbind';
+ *
+ * // Generate a new correlation ID
+ * const id = generateCorrelationId();
+ *
+ * // Attach to request headers
+ * const headers = attachCorrelationId(new Headers(), id);
+ *
+ * // Validate format
+ * if (validateCorrelationId(id)) {
+ *   console.log('Valid correlation ID');
+ * }
+ * ```
+ */
+/**
+ * Standard header name for correlation ID
+ */
+export const CORRELATION_ID_HEADER = 'X-Correlation-ID';
+/**
+ * Alternative header names for compatibility
+ */
+export const CORRELATION_ID_ALIASES = [
+    'X-Request-ID',
+    'X-Trace-ID',
+    'X-Transaction-ID',
+];
+/**
+ * Regular expression for validating correlation ID format
+ */
+const CORRELATION_ID_PATTERN = /^req_\d{13}_[a-f0-9]{8}$/;
+/**
+ * Generate a new correlation ID
+ *
+ * Format: `req_{timestamp}_{random}`
+ * - `req`: Static prefix for identification
+ * - `timestamp`: Unix timestamp in milliseconds (13 digits)
+ * - `random`: 8-character hex string for uniqueness
+ *
+ * @returns New correlation ID string
+ *
+ * @example
+ * ```typescript
+ * const id = generateCorrelationId();
+ * // => "req_1716234567890_a3f5c9d2"
+ * ```
+ */
+export function generateCorrelationId() {
+    const timestamp = Date.now();
+    const random = generateRandomHex(8);
+    return `req_${timestamp}_${random}`;
+}
+/**
+ * Validate correlation ID format
+ *
+ * Checks if the provided string matches the expected correlation ID format.
+ *
+ * @param id - String to validate
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validateCorrelationId('req_1716234567890_a3f5c9d2'); // => true
+ * validateCorrelationId('invalid'); // => false
+ * validateCorrelationId('req_123_abc'); // => false (wrong lengths)
+ * ```
+ */
+export function validateCorrelationId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return CORRELATION_ID_PATTERN.test(id);
+}
+/**
+ * Parse correlation ID into components
+ *
+ * Extracts the timestamp and random components from a correlation ID.
+ *
+ * @param id - Correlation ID to parse
+ * @returns Parsed components or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const spec = parseCorrelationId('req_1716234567890_a3f5c9d2');
+ * // => { prefix: 'req', timestamp: 1716234567890, random: 'a3f5c9d2' }
+ * ```
+ */
+export function parseCorrelationId(id) {
+    if (!validateCorrelationId(id))
+        return null;
+    const parts = id.split('_');
+    return {
+        prefix: parts[0] ?? 'req',
+        timestamp: parseInt(parts[1] ?? '0', 10),
+        random: parts[2] ?? '',
+    };
+}
+/**
+ * Attach correlation ID to request headers
+ *
+ * Adds the correlation ID to the X-Correlation-ID header.
+ * If no ID is provided, generates a new one.
+ * Compatible with both Headers API and plain objects.
+ *
+ * @param headers - Headers object or plain object
+ * @param id - Correlation ID (generates new if not provided)
+ * @returns Updated headers object
+ *
+ * @example
+ * ```typescript
+ * // With Headers API
+ * const headers = new Headers();
+ * attachCorrelationId(headers);
+ *
+ * // With plain object
+ * const headers = { 'Content-Type': 'application/json' };
+ * attachCorrelationId(headers, 'req_1716234567890_a3f5c9d2');
+ *
+ * // With existing correlation ID
+ * const id = generateCorrelationId();
+ * attachCorrelationId(headers, id);
+ * ```
+ */
+export function attachCorrelationId(headers, id) {
+    const correlationId = id ?? generateCorrelationId();
+    if (!validateCorrelationId(correlationId)) {
+        throw new Error(`Invalid correlation ID format: ${correlationId}. Expected format: req_{timestamp}_{random}`);
+    }
+    if (headers instanceof Headers) {
+        headers.set(CORRELATION_ID_HEADER, correlationId);
+    }
+    else {
+        headers[CORRELATION_ID_HEADER] = correlationId;
+    }
+    return headers;
+}
+/**
+ * Extract correlation ID from request headers
+ *
+ * Checks the standard header and common aliases.
+ *
+ * @param headers - Headers object or plain object
+ * @returns Correlation ID if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const headers = new Headers({
+ *   'X-Correlation-ID': 'req_1716234567890_a3f5c9d2'
+ * });
+ * const id = extractCorrelationId(headers);
+ * // => 'req_1716234567890_a3f5c9d2'
+ * ```
+ */
+export function extractCorrelationId(headers) {
+    // Check primary header
+    const primary = headers instanceof Headers
+        ? headers.get(CORRELATION_ID_HEADER)
+        : headers[CORRELATION_ID_HEADER];
+    if (primary && validateCorrelationId(primary)) {
+        return primary;
+    }
+    // Check aliases
+    for (const alias of CORRELATION_ID_ALIASES) {
+        const value = headers instanceof Headers ? headers.get(alias) : headers[alias];
+        if (value && validateCorrelationId(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get or create correlation ID from headers
+ *
+ * Returns existing correlation ID from headers, or generates a new one if not found.
+ * Does NOT modify the input headers.
+ *
+ * @param headers - Headers to check
+ * @returns Existing or new correlation ID
+ *
+ * @example
+ * ```typescript
+ * const headers = new Headers();
+ * const id = getOrCreateCorrelationId(headers);
+ * // => Generates new ID if not found in headers
+ * ```
+ */
+export function getOrCreateCorrelationId(headers) {
+    if (!headers)
+        return generateCorrelationId();
+    const existing = extractCorrelationId(headers);
+    return existing ?? generateCorrelationId();
+}
+/**
+ * Create a correlation ID from a timestamp
+ *
+ * Useful for testing or when you need deterministic IDs.
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @param random - Optional random component (generates if not provided)
+ * @returns Correlation ID
+ *
+ * @example
+ * ```typescript
+ * const id = createCorrelationIdFromTimestamp(1716234567890);
+ * // => 'req_1716234567890_a3f5c9d2'
+ *
+ * const deterministicId = createCorrelationIdFromTimestamp(1716234567890, 'aaaaaaaa');
+ * // => 'req_1716234567890_aaaaaaaa'
+ * ```
+ */
+export function createCorrelationIdFromTimestamp(timestamp, random) {
+    const randomComponent = random ?? generateRandomHex(8);
+    if (!/^[a-f0-9]{8}$/.test(randomComponent)) {
+        throw new Error(`Invalid random component: ${randomComponent}. Expected 8 hex characters`);
+    }
+    return `req_${timestamp}_${randomComponent}`;
+}
+/**
+ * Calculate age of correlation ID in milliseconds
+ *
+ * @param id - Correlation ID
+ * @returns Age in milliseconds, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const id = generateCorrelationId();
+ * setTimeout(() => {
+ *   const age = getCorrelationIdAge(id);
+ *   console.log(`Request age: ${age}ms`);
+ * }, 1000);
+ * ```
+ */
+export function getCorrelationIdAge(id) {
+    const spec = parseCorrelationId(id);
+    if (!spec)
+        return null;
+    const now = Date.now();
+    return now - spec.timestamp;
+}
+/**
+ * Check if correlation ID is expired
+ *
+ * @param id - Correlation ID
+ * @param maxAgeMs - Maximum age in milliseconds (default: 5 minutes)
+ * @returns True if expired, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const id = generateCorrelationId();
+ * if (isCorrelationIdExpired(id, 60000)) {
+ *   console.log('Request older than 1 minute');
+ * }
+ * ```
+ */
+export function isCorrelationIdExpired(id, maxAgeMs = 5 * 60 * 1000) {
+    const age = getCorrelationIdAge(id);
+    return age !== null && age > maxAgeMs;
+}
+/**
+ * Generate random hex string
+ *
+ * Uses Web Crypto API in browser, Node.js crypto in Node.
+ * Falls back to Math.random() if neither available (NOT cryptographically secure).
+ *
+ * @param length - Number of hex characters to generate
+ * @returns Random hex string
+ *
+ * @internal
+ */
+function generateRandomHex(length) {
+    const bytes = Math.ceil(length / 2);
+    // Try Web Crypto API (browser)
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        const buffer = new Uint8Array(bytes);
+        crypto.getRandomValues(buffer);
+        return Array.from(buffer)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('')
+            .substring(0, length);
+    }
+    // Try Node.js crypto
+    try {
+        const nodeCrypto = require('node:crypto');
+        return nodeCrypto.randomBytes(bytes).toString('hex').substring(0, length);
+    }
+    catch {
+        // SECURITY: Never fall back to Math.random() in production (OWASP violation)
+        // Correlation IDs must be cryptographically random to prevent enumeration attacks
+        throw new Error('Cryptographic random generation unavailable. ' +
+            'Install crypto polyfill or use environment with crypto support.');
+    }
+}
+/**
+ * Middleware helper for Express/Koa-style frameworks
+ *
+ * Automatically attaches correlation ID to incoming requests.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { correlationIdMiddleware } from '@private.me/xbind';
+ *
+ * const app = express();
+ * app.use(correlationIdMiddleware());
+ * ```
+ */
+export function correlationIdMiddleware() {
+    return (req, res, next) => {
+        const id = getOrCreateCorrelationId(req.headers);
+        req.correlationId = id;
+        res.setHeader(CORRELATION_ID_HEADER, id);
+        if (typeof next === 'function')
+            next();
+    };
+}

package/dist-standalone/http-status-map.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @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
+ * ```
+ */
+/**
+ * HTTP status mapping entry with metadata.
+ */
+export interface HttpStatusMapping {
+    /** HTTP status code (e.g., 400, 401, 500) */
+    readonly statusCode: number;
+    /** HTTP status text (e.g., 'Bad Request', 'Unauthorized') */
+    readonly statusText: string;
+    /** Whether the operation should be retried by the client */
+    readonly retryable: boolean;
+    /** Error type classification */
+    readonly errorType: 'Client' | 'Server';
+    /** Error category for grouping related errors */
+    readonly category: 'Identity' | 'Envelope' | 'Transport' | 'Registry' | 'Key Agreement' | 'Split Channel' | 'Xchange' | 'Agent';
+    /** Rationale for the HTTP status code choice */
+    readonly rationale: string;
+}
+/**
+ * Complete mapping of xBind error codes to HTTP status codes.
+ * All 52 error codes are mapped for 100% coverage.
+ */
+export declare const HTTP_STATUS_MAP: Record<string, HttpStatusMapping>;
+/**
+ * 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 declare function getHttpStatus(errorCode: string): number;
+/**
+ * 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 declare function getStatusText(errorCode: string): string;
+/**
+ * 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 declare function isRetryable(errorCode: string): boolean;
+/**
+ * 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 declare function getMapping(errorCode: string): HttpStatusMapping | 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 declare function getErrorCodesByCategory(category: HttpStatusMapping['category']): string[];
+/**
+ * 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 declare function getRetryableErrorCodes(): string[];
+/**
+ * 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 declare function validateCoverage(csvErrorCodes: string[]): string[];