@private.me/xbind 1.2.0 → 1.2.2

package/dist-standalone/agent.d.ts

@@ -282,13 +282,18 @@ export declare class Agent {
      * Create an Agent from a deterministic 32-byte seed.
      *
      * Uses HKDF-SHA256 to derive Ed25519 + X25519 keys from the seed.
-     * The same seed always produces the same DID and keys. Skips registry
-     * registration — the caller is responsible for registering externally.
+     * The same seed always produces the same DID and keys.
      *
-     * Ideal for IoT: factory burns seed → field deploys → boot derives identity.
+     * **Just-in-Time Registration (JITR):** Automatically registers identity
+     * with the trust registry on first use. Follows industry standards (AWS IoT
+     * JITR, OAuth DCR, MCP 2025 spec) for zero-config onboarding. Idempotent:
+     * safe to call multiple times (ignores ALREADY_REGISTERED errors).
+     *
+     * Ideal for IoT, servers, AI agents: zero-config deployment with automatic
+     * registration on first connection.
      *
      * @param seed - Exactly 32 bytes of high-entropy key material.
-     * @param opts - Agent options (registry, transport, etc.).
+     * @param opts - Agent options (registry, transport, scopes, etc.).
      * @returns Agent instance or error.
      */
     static fromSeed(seed: Uint8Array, opts: Omit<AgentCreateOptions, 'name'> & {

package/dist-standalone/agent.js

@@ -197,19 +197,35 @@ export class Agent {
      * Create an Agent from a deterministic 32-byte seed.
      *
      * Uses HKDF-SHA256 to derive Ed25519 + X25519 keys from the seed.
-     * The same seed always produces the same DID and keys. Skips registry
-     * registration — the caller is responsible for registering externally.
+     * The same seed always produces the same DID and keys.
      *
-     * Ideal for IoT: factory burns seed → field deploys → boot derives identity.
+     * **Just-in-Time Registration (JITR):** Automatically registers identity
+     * with the trust registry on first use. Follows industry standards (AWS IoT
+     * JITR, OAuth DCR, MCP 2025 spec) for zero-config onboarding. Idempotent:
+     * safe to call multiple times (ignores ALREADY_REGISTERED errors).
+     *
+     * Ideal for IoT, servers, AI agents: zero-config deployment with automatic
+     * registration on first connection.
      *
      * @param seed - Exactly 32 bytes of high-entropy key material.
-     * @param opts - Agent options (registry, transport, etc.).
+     * @param opts - Agent options (registry, transport, scopes, etc.).
      * @returns Agent instance or error.
      */
     static async fromSeed(seed, opts) {
         const idResult = await identityFromSeed(seed, { postQuantumSig: opts.postQuantumSig });
         if (!idResult.ok)
             return err('IDENTITY_FAILED:KEYGEN');
+        // JITR: Auto-register with trust registry (zero-config onboarding)
+        // Includes all keys: Ed25519 (signing), X25519 (encryption), ML-KEM, ML-DSA
+        const regResult = await opts.registry.register(idResult.value.did, idResult.value.rawPublicKey, opts.name ?? idResult.value.did, opts.scopes, idResult.value.rawX25519PublicKey, idResult.value.mlKemPublicKey, idResult.value.mlDsaPublicKey, opts.xchange ?? false);
+        // Idempotent: Ignore ALREADY_REGISTERED (agent may have registered before)
+        // Fail on other errors (network issues, invalid data, etc.)
+        if (!regResult.ok && regResult.error !== 'ALREADY_REGISTERED') {
+            const sub = regResult.error === 'NETWORK_ERROR'
+                ? 'REGISTRATION_FAILED:NETWORK_ERROR'
+                : 'REGISTRATION_FAILED';
+            return err(sub);
+        }
         const nonceStore = opts.nonceStore ?? new MemoryNonceStore();
         const timestampWindowMs = opts.timestampWindowMs ?? TIMESTAMP_WINDOW_MS;
         const transports = Array.isArray(opts.transport) ? opts.transport : [opts.transport];

package/dist-standalone/cjs/agent.js

@@ -235,19 +235,35 @@ class Agent {
      * Create an Agent from a deterministic 32-byte seed.
      *
      * Uses HKDF-SHA256 to derive Ed25519 + X25519 keys from the seed.
-     * The same seed always produces the same DID and keys. Skips registry
-     * registration — the caller is responsible for registering externally.
+     * The same seed always produces the same DID and keys.
      *
-     * Ideal for IoT: factory burns seed → field deploys → boot derives identity.
+     * **Just-in-Time Registration (JITR):** Automatically registers identity
+     * with the trust registry on first use. Follows industry standards (AWS IoT
+     * JITR, OAuth DCR, MCP 2025 spec) for zero-config onboarding. Idempotent:
+     * safe to call multiple times (ignores ALREADY_REGISTERED errors).
+     *
+     * Ideal for IoT, servers, AI agents: zero-config deployment with automatic
+     * registration on first connection.
      *
      * @param seed - Exactly 32 bytes of high-entropy key material.
-     * @param opts - Agent options (registry, transport, etc.).
+     * @param opts - Agent options (registry, transport, scopes, etc.).
      * @returns Agent instance or error.
      */
     static async fromSeed(seed, opts) {
         const idResult = await (0, identity_js_1.identityFromSeed)(seed, { postQuantumSig: opts.postQuantumSig });
         if (!idResult.ok)
             return (0, shared_1.err)('IDENTITY_FAILED:KEYGEN');
+        // JITR: Auto-register with trust registry (zero-config onboarding)
+        // Includes all keys: Ed25519 (signing), X25519 (encryption), ML-KEM, ML-DSA
+        const regResult = await opts.registry.register(idResult.value.did, idResult.value.rawPublicKey, opts.name ?? idResult.value.did, opts.scopes, idResult.value.rawX25519PublicKey, idResult.value.mlKemPublicKey, idResult.value.mlDsaPublicKey, opts.xchange ?? false);
+        // Idempotent: Ignore ALREADY_REGISTERED (agent may have registered before)
+        // Fail on other errors (network issues, invalid data, etc.)
+        if (!regResult.ok && regResult.error !== 'ALREADY_REGISTERED') {
+            const sub = regResult.error === 'NETWORK_ERROR'
+                ? 'REGISTRATION_FAILED:NETWORK_ERROR'
+                : 'REGISTRATION_FAILED';
+            return (0, shared_1.err)(sub);
+        }
         const nonceStore = opts.nonceStore ?? new nonce_store_js_1.MemoryNonceStore();
         const timestampWindowMs = opts.timestampWindowMs ?? TIMESTAMP_WINDOW_MS;
         const transports = Array.isArray(opts.transport) ? opts.transport : [opts.transport];

package/dist-standalone/cjs/correlation-id.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * @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');
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORRELATION_ID_ALIASES = exports.CORRELATION_ID_HEADER = void 0;
+exports.generateCorrelationId = generateCorrelationId;
+exports.validateCorrelationId = validateCorrelationId;
+exports.parseCorrelationId = parseCorrelationId;
+exports.attachCorrelationId = attachCorrelationId;
+exports.extractCorrelationId = extractCorrelationId;
+exports.getOrCreateCorrelationId = getOrCreateCorrelationId;
+exports.createCorrelationIdFromTimestamp = createCorrelationIdFromTimestamp;
+exports.getCorrelationIdAge = getCorrelationIdAge;
+exports.isCorrelationIdExpired = isCorrelationIdExpired;
+exports.correlationIdMiddleware = correlationIdMiddleware;
+/**
+ * Standard header name for correlation ID
+ */
+exports.CORRELATION_ID_HEADER = 'X-Correlation-ID';
+/**
+ * Alternative header names for compatibility
+ */
+exports.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"
+ * ```
+ */
+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)
+ * ```
+ */
+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' }
+ * ```
+ */
+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);
+ * ```
+ */
+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(exports.CORRELATION_ID_HEADER, correlationId);
+    }
+    else {
+        headers[exports.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'
+ * ```
+ */
+function extractCorrelationId(headers) {
+    // Check primary header
+    const primary = headers instanceof Headers
+        ? headers.get(exports.CORRELATION_ID_HEADER)
+        : headers[exports.CORRELATION_ID_HEADER];
+    if (primary && validateCorrelationId(primary)) {
+        return primary;
+    }
+    // Check aliases
+    for (const alias of exports.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
+ * ```
+ */
+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'
+ * ```
+ */
+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);
+ * ```
+ */
+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');
+ * }
+ * ```
+ */
+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());
+ * ```
+ */
+function correlationIdMiddleware() {
+    return (req, res, next) => {
+        const id = getOrCreateCorrelationId(req.headers);
+        req.correlationId = id;
+        res.setHeader(exports.CORRELATION_ID_HEADER, id);
+        if (typeof next === 'function')
+            next();
+    };
+}