@private.me/xbind 1.2.0

package/dist-standalone/redis-nonce-store.d.ts

@@ -0,0 +1,93 @@
+import type { NonceStore } from './nonce-store.js';
+/**
+ * Minimal Redis client interface.
+ *
+ * Users implement this with their Redis library of choice (ioredis, node-redis, etc.).
+ * This keeps @private.me/xbind free of concrete Redis dependencies.
+ */
+export interface RedisClient {
+    /**
+     * SET key value EX seconds NX -- atomic set-if-not-exists with TTL.
+     * @param key - The key to set.
+     * @param value - The value to store.
+     * @param ttlSeconds - Time-to-live in seconds.
+     * @returns 'OK' if the key was set (new), null if the key already exists (duplicate).
+     */
+    setNX(key: string, value: string, ttlSeconds: number): Promise<string | null>;
+    /**
+     * DEL key -- delete a key from Redis.
+     * @param key - The key to delete.
+     * @returns The number of keys removed.
+     */
+    del(key: string): Promise<number>;
+    /**
+     * QUIT -- disconnect from Redis gracefully.
+     */
+    quit(): Promise<void>;
+}
+/**
+ * Configuration options for RedisNonceStore.
+ */
+export interface RedisNonceStoreOptions {
+    /** The Redis client instance to use for nonce storage. */
+    readonly client: RedisClient;
+    /** TTL in seconds for nonce entries. Default: 600 (10 minutes). */
+    readonly ttlSeconds?: number;
+    /** Key prefix for all nonce entries in Redis. Default: 'nonce:'. */
+    readonly keyPrefix?: string;
+}
+/**
+ * Redis-backed nonce store for multi-node deployments.
+ *
+ * Uses Redis SET NX with TTL for atomic, distributed nonce deduplication.
+ * Nonce expiry is handled by Redis TTL -- no manual cleanup needed.
+ * Zero npm dependencies: users provide their own RedisClient implementation.
+ *
+ * @example
+ * ```typescript
+ * import { RedisNonceStore } from '@private.me/xbind';
+ * import Redis from 'ioredis';
+ *
+ * const redis = new Redis();
+ * const store = new RedisNonceStore({
+ *   client: {
+ *     setNX: (key, value, ttl) =>
+ *       redis.set(key, value, 'EX', ttl, 'NX'),
+ *     del: (key) => redis.del(key),
+ *     quit: () => redis.quit(),
+ *   },
+ * });
+ * ```
+ */
+export declare class RedisNonceStore implements NonceStore {
+    private readonly client;
+    private readonly ttlSeconds;
+    private readonly keyPrefix;
+    constructor(opts: RedisNonceStoreOptions);
+    /**
+     * Check if a nonce is fresh and record it atomically via Redis SET NX.
+     *
+     * Uses Redis SET with NX (set-if-not-exists) and EX (TTL in seconds)
+     * for atomic, distributed deduplication. If the key already exists in
+     * any Redis-connected node, the nonce is rejected as a duplicate.
+     *
+     * @param nonce - The nonce string to check.
+     * @param senderDid - The DID of the sender.
+     * @returns true if the nonce is new (accepted), false if duplicate (rejected).
+     */
+    check(nonce: string, senderDid: string): Promise<boolean>;
+    /**
+     * No-op for Redis store -- TTL-based expiry is handled automatically.
+     *
+     * This method exists to satisfy the NonceStore interface. Redis keys
+     * expire based on the TTL set during setNX, so no manual cleanup is needed.
+     */
+    cleanup(): void;
+    /**
+     * Disconnect from Redis gracefully.
+     *
+     * Calls the underlying RedisClient quit() method to close the connection.
+     * After calling dispose(), the store should not be used.
+     */
+    dispose(): void;
+}

package/dist-standalone/redis-nonce-store.js

@@ -0,0 +1,72 @@
+/* -- RedisNonceStore -- Cross-Node Replay Prevention -- */
+/** Default TTL for nonce entries: 600 seconds (10 minutes). */
+const DEFAULT_TTL_SECONDS = 600;
+/** Default key prefix for Redis nonce keys. */
+const DEFAULT_KEY_PREFIX = 'nonce:';
+/**
+ * Redis-backed nonce store for multi-node deployments.
+ *
+ * Uses Redis SET NX with TTL for atomic, distributed nonce deduplication.
+ * Nonce expiry is handled by Redis TTL -- no manual cleanup needed.
+ * Zero npm dependencies: users provide their own RedisClient implementation.
+ *
+ * @example
+ * ```typescript
+ * import { RedisNonceStore } from '@private.me/xbind';
+ * import Redis from 'ioredis';
+ *
+ * const redis = new Redis();
+ * const store = new RedisNonceStore({
+ *   client: {
+ *     setNX: (key, value, ttl) =>
+ *       redis.set(key, value, 'EX', ttl, 'NX'),
+ *     del: (key) => redis.del(key),
+ *     quit: () => redis.quit(),
+ *   },
+ * });
+ * ```
+ */
+export class RedisNonceStore {
+    client;
+    ttlSeconds;
+    keyPrefix;
+    constructor(opts) {
+        this.client = opts.client;
+        this.ttlSeconds = opts.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        this.keyPrefix = opts.keyPrefix ?? DEFAULT_KEY_PREFIX;
+    }
+    /**
+     * Check if a nonce is fresh and record it atomically via Redis SET NX.
+     *
+     * Uses Redis SET with NX (set-if-not-exists) and EX (TTL in seconds)
+     * for atomic, distributed deduplication. If the key already exists in
+     * any Redis-connected node, the nonce is rejected as a duplicate.
+     *
+     * @param nonce - The nonce string to check.
+     * @param senderDid - The DID of the sender.
+     * @returns true if the nonce is new (accepted), false if duplicate (rejected).
+     */
+    async check(nonce, senderDid) {
+        const key = `${this.keyPrefix}${senderDid}:${nonce}`;
+        const result = await this.client.setNX(key, '1', this.ttlSeconds);
+        return result === 'OK';
+    }
+    /**
+     * No-op for Redis store -- TTL-based expiry is handled automatically.
+     *
+     * This method exists to satisfy the NonceStore interface. Redis keys
+     * expire based on the TTL set during setNX, so no manual cleanup is needed.
+     */
+    cleanup() {
+        // No-op: Redis TTL handles expiry automatically
+    }
+    /**
+     * Disconnect from Redis gracefully.
+     *
+     * Calls the underlying RedisClient quit() method to close the connection.
+     * After calling dispose(), the store should not be used.
+     */
+    dispose() {
+        void this.client.quit();
+    }
+}

package/dist-standalone/registry-middleware.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Express middleware for protecting trust registry endpoints with bearer auth.
+ *
+ * GET/HEAD requests pass through (public reads). POST/PUT/DELETE require
+ * a valid Bearer token matching the configured admin token.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createRegistryAuthMiddleware } from '@private.me/xbind';
+ *
+ * const app = express();
+ * app.use('/registry', createRegistryAuthMiddleware(process.env.REGISTRY_ADMIN_TOKEN!));
+ * ```
+ */
+/** Express-compatible request with method and headers. */
+interface MiddlewareRequest {
+    readonly method: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+}
+/** Express-compatible response with status and json. */
+interface MiddlewareResponse {
+    status: (code: number) => {
+        json: (data: unknown) => void;
+    };
+}
+/**
+ * Create an Express-compatible middleware that protects write operations
+ * on registry endpoints with bearer token authentication.
+ *
+ * GET and HEAD requests pass through without authentication.
+ * POST, PUT, and DELETE require `Authorization: Bearer <token>`.
+ *
+ * @param token - The admin token to validate against.
+ * @returns Express middleware function.
+ */
+export declare function createRegistryAuthMiddleware(token: string): (req: MiddlewareRequest, res: MiddlewareResponse, next: (err?: unknown) => void) => void;
+export {};

package/dist-standalone/registry-middleware.js

@@ -0,0 +1,47 @@
+/**
+ * Express middleware for protecting trust registry endpoints with bearer auth.
+ *
+ * GET/HEAD requests pass through (public reads). POST/PUT/DELETE require
+ * a valid Bearer token matching the configured admin token.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createRegistryAuthMiddleware } from '@private.me/xbind';
+ *
+ * const app = express();
+ * app.use('/registry', createRegistryAuthMiddleware(process.env.REGISTRY_ADMIN_TOKEN!));
+ * ```
+ */
+/**
+ * Create an Express-compatible middleware that protects write operations
+ * on registry endpoints with bearer token authentication.
+ *
+ * GET and HEAD requests pass through without authentication.
+ * POST, PUT, and DELETE require `Authorization: Bearer <token>`.
+ *
+ * @param token - The admin token to validate against.
+ * @returns Express middleware function.
+ */
+export function createRegistryAuthMiddleware(token) {
+    return (req, res, next) => {
+        const method = req.method.toUpperCase();
+        if (method === 'GET' || method === 'HEAD') {
+            next();
+            return;
+        }
+        const authHeader = typeof req.headers['authorization'] === 'string'
+            ? req.headers['authorization']
+            : undefined;
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            res.status(401).json({ error: 'UNAUTHORIZED' });
+            return;
+        }
+        const provided = authHeader.slice('Bearer '.length);
+        if (provided !== token) {
+            res.status(401).json({ error: 'UNAUTHORIZED' });
+            return;
+        }
+        next();
+    };
+}

package/dist-standalone/retry-transport.d.ts

@@ -0,0 +1,76 @@
+import type { Result } from '@private.me/shared';
+import type { XailTransportAdapter, TransportError, EnvelopeHandler } from './transport.js';
+import type { AnyTransportEnvelope } from './envelope.js';
+/**
+ * Configuration options for exponential backoff retry logic.
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts. Default: 3. */
+    maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff. Default: 1000. */
+    baseDelayMs?: number;
+    /** Maximum jitter in milliseconds for randomization. Default: 200. */
+    maxJitterMs?: number;
+}
+/**
+ * Decorator that adds exponential backoff retry logic to any transport adapter.
+ *
+ * Retry delays follow exponential backoff with jitter:
+ * - Formula: 2^attempt * baseDelay + jitter
+ * - Jitter: Math.random() * maxJitter * 2 - maxJitter
+ * - Default delays: 1s, 2s, 4s (with ±200ms jitter)
+ *
+ * Use case: Push notification delivery failures requiring automatic retry.
+ *
+ * @example
+ * ```typescript
+ * const transport = new RetryTransportAdapter(baseTransport, {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
+ *   maxJitterMs: 200
+ * });
+ * ```
+ */
+export declare class RetryTransportAdapter implements XailTransportAdapter {
+    private readonly inner;
+    private readonly maxRetries;
+    private readonly baseDelayMs;
+    private readonly maxJitterMs;
+    /**
+     * Create a new RetryTransportAdapter wrapping an existing transport.
+     *
+     * @param inner - The transport adapter to wrap with retry logic
+     * @param options - Retry configuration options
+     */
+    constructor(inner: XailTransportAdapter, options?: RetryOptions);
+    /**
+     * Send an envelope with exponential backoff retry logic.
+     *
+     * Retries on all error types (SEND_FAILED, NETWORK_ERROR, RECIPIENT_UNREACHABLE, TIMEOUT).
+     * Throws error after all retries are exhausted.
+     *
+     * @param envelope - The envelope to send
+     * @param recipientDid - The recipient's DID
+     * @returns Result with void on success, or TransportError on failure
+     * @throws Error if all retry attempts are exhausted
+     */
+    send(envelope: AnyTransportEnvelope, recipientDid: string): Promise<Result<void, TransportError>>;
+    /**
+     * Register a handler for incoming envelopes.
+     * Delegates directly to the inner transport.
+     *
+     * @param handler - The envelope handler function
+     */
+    onReceive(handler: EnvelopeHandler): void;
+    /**
+     * Shut down the transport.
+     * Delegates directly to the inner transport.
+     */
+    dispose(): void;
+    /**
+     * Sleep for a specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     */
+    private sleep;
+}

package/dist-standalone/retry-transport.js

@@ -0,0 +1,98 @@
+/* ── Implementation ── */
+/**
+ * Decorator that adds exponential backoff retry logic to any transport adapter.
+ *
+ * Retry delays follow exponential backoff with jitter:
+ * - Formula: 2^attempt * baseDelay + jitter
+ * - Jitter: Math.random() * maxJitter * 2 - maxJitter
+ * - Default delays: 1s, 2s, 4s (with ±200ms jitter)
+ *
+ * Use case: Push notification delivery failures requiring automatic retry.
+ *
+ * @example
+ * ```typescript
+ * const transport = new RetryTransportAdapter(baseTransport, {
+ *   maxRetries: 3,
+ *   baseDelayMs: 1000,
+ *   maxJitterMs: 200
+ * });
+ * ```
+ */
+export class RetryTransportAdapter {
+    inner;
+    maxRetries;
+    baseDelayMs;
+    maxJitterMs;
+    /**
+     * Create a new RetryTransportAdapter wrapping an existing transport.
+     *
+     * @param inner - The transport adapter to wrap with retry logic
+     * @param options - Retry configuration options
+     */
+    constructor(inner, options = {}) {
+        this.inner = inner;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.baseDelayMs = options.baseDelayMs ?? 1000;
+        this.maxJitterMs = options.maxJitterMs ?? 200;
+    }
+    /**
+     * Send an envelope with exponential backoff retry logic.
+     *
+     * Retries on all error types (SEND_FAILED, NETWORK_ERROR, RECIPIENT_UNREACHABLE, TIMEOUT).
+     * Throws error after all retries are exhausted.
+     *
+     * @param envelope - The envelope to send
+     * @param recipientDid - The recipient's DID
+     * @returns Result with void on success, or TransportError on failure
+     * @throws Error if all retry attempts are exhausted
+     */
+    async send(envelope, recipientDid) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const result = await this.inner.send(envelope, recipientDid);
+            // Success - return immediately
+            if (result.ok) {
+                return result;
+            }
+            // Store error for final throw
+            lastError = result.error;
+            // Don't delay after final attempt
+            if (attempt < this.maxRetries) {
+                // Exponential backoff: 2^attempt * baseDelay + jitter
+                const delay = Math.pow(2, attempt) * this.baseDelayMs;
+                // SAFETY: Using crypto.getRandomValues for OWASP-compliant secure random jitter
+                const jitterArray = new Uint32Array(1);
+                crypto.getRandomValues(jitterArray);
+                const jitter = (jitterArray[0] / 0xffffffff) * this.maxJitterMs * 2 -
+                    this.maxJitterMs;
+                await this.sleep(delay + jitter);
+            }
+        }
+        // All retries exhausted - throw error with clear message
+        throw new Error(`Failed after ${this.maxRetries} retries: ${lastError ?? 'unknown error'}`);
+    }
+    /**
+     * Register a handler for incoming envelopes.
+     * Delegates directly to the inner transport.
+     *
+     * @param handler - The envelope handler function
+     */
+    onReceive(handler) {
+        this.inner.onReceive(handler);
+    }
+    /**
+     * Shut down the transport.
+     * Delegates directly to the inner transport.
+     */
+    dispose() {
+        this.inner.dispose();
+    }
+    /**
+     * Sleep for a specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist-standalone/security-policy.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Security policy interface for automatic risk-based Xorida activation.
+ *
+ * Determines when to apply information-theoretic security (XorIDA split-channel)
+ * vs standard encrypted transport based on action semantics and parameters.
+ *
+ * Design principle: Security should be invisible to users. The policy classifies
+ * risk automatically so developers don't need to understand threshold cryptography.
+ */
+/** Security mode selected by policy. */
+export type SecurityMode = {
+    readonly type: 'standard';
+} | {
+    readonly type: 'split';
+    readonly shares: number;
+    readonly threshold: number;
+} | {
+    readonly type: 'xchange';
+};
+/** Explicit security level override (user-facing). */
+export type SecurityLevel = 'auto' | 'standard' | 'high' | 'critical';
+/** Context for security classification. */
+export interface SecurityContext {
+    /** Action being performed (e.g., 'transfer', 'execute', 'send'). */
+    readonly action: string;
+    /** Action parameters (amount, recipient, scope, etc.). */
+    readonly params: Record<string, unknown>;
+    /** Sender DID. */
+    readonly sender: string;
+    /** Recipient DID. */
+    readonly recipient: string;
+    /** Permission scope. */
+    readonly scope: string;
+    /** Explicit security level override (if provided by user). */
+    readonly securityOverride?: SecurityLevel;
+}
+/** Reason why a particular security mode was selected. */
+export interface SecurityDecision {
+    /** Selected security mode. */
+    readonly mode: SecurityMode;
+    /** Human-readable reason for this decision. */
+    readonly reason: string;
+    /** Whether this was an auto-decision or explicit override. */
+    readonly wasOverridden: boolean;
+}
+/**
+ * Security policy interface.
+ *
+ * Implementations classify actions into security modes based on risk.
+ * Used by Agent.send() to automatically apply Xorida when needed.
+ */
+export interface SecurityPolicy {
+    /**
+     * Classify an action into a security mode.
+     *
+     * @param context - Action context (action, params, sender, recipient, scope)
+     * @returns Security decision with mode and reason
+     */
+    classify(context: SecurityContext): SecurityDecision;
+}
+/**
+ * Default security policy for basic XBind.
+ *
+ * Rules:
+ * - Transfers over $100,000: High security (3 shares, 2-of-3 threshold)
+ * - Cross-entity communication: High security (3 shares, 2-of-3 threshold)
+ * - Explicit 'high' override: High security (3 shares, 2-of-3 threshold)
+ * - Explicit 'critical' override: Critical security (5 shares, 3-of-5 threshold)
+ * - Everything else: Standard encrypted transport (V3 hybrid PQ)
+ *
+ * Enterprise and Government variants extend this with custom rules.
+ */
+export declare class DefaultSecurityPolicy implements SecurityPolicy {
+    private readonly options;
+    /**
+     * Create a default security policy.
+     *
+     * @param options - Optional configuration
+     * @param options.highValueThreshold - Amount threshold for high security (default: 100000)
+     * @param options.enableXchange - Allow Xchange mode for performance (default: false)
+     */
+    constructor(options?: {
+        readonly highValueThreshold?: number;
+        readonly enableXchange?: boolean;
+    });
+    classify(context: SecurityContext): SecurityDecision;
+}
+/**
+ * Security mode description with multiple format representations.
+ */
+export interface SecurityModeDescription {
+    /** Security mode type. */
+    readonly type: 'standard' | 'split' | 'xchange';
+    /** Security level classification. */
+    readonly level: 'standard' | 'high' | 'critical' | 'performance';
+    /** Share configuration (only for split mode). */
+    readonly shares?: {
+        readonly total: number;
+        readonly threshold: number;
+    };
+    /** Multiple format representations. */
+    readonly formats: {
+        readonly multiline: string;
+        readonly singleline: string;
+        readonly json: string;
+        readonly markdown: string;
+    };
+}
+/**
+ * Get a human-readable security mode description.
+ *
+ * Used for logging and user feedback.
+ *
+ * @param mode - Security mode
+ * @returns User-friendly description
+ *
+ * @deprecated Use describeSecurityModeStructured() for new code. This function remains for backward compatibility.
+ */
+export declare function describeSecurityMode(mode: SecurityMode): string;
+/**
+ * Get a structured security mode description with multiple formats.
+ *
+ * Returns an object with the security classification and formatted descriptions
+ * optimized for different use cases (display, logging, APIs, docs).
+ *
+ * @param mode - Security mode
+ * @returns Security mode description with formats
+ *
+ * @example
+ * ```typescript
+ * const mode: SecurityMode = { type: 'split', shares: 3, threshold: 2 };
+ * const description = describeSecurityModeStructured(mode);
+ *
+ * console.log(description.formats.singleline);
+ * // "high | split | 2-of-3"
+ *
+ * console.log(description.formats.multiline);
+ * // "Security Level: High
+ * //  Mode: Split-channel (XorIDA)
+ * //  Shares: 3 total, 2 required"
+ *
+ * console.log(description.shares);
+ * // { total: 3, threshold: 2 }
+ * ```
+ */
+export declare function describeSecurityModeStructured(mode: SecurityMode): SecurityModeDescription;