@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/nonce-store.js

@@ -1,62 +1 @@
-/* ── NonceStore — Replay Prevention ── */
-/** Default TTL for nonce entries: 10 minutes. */
-const DEFAULT_TTL_MS = 10 * 60 * 1000;
-/** Default cleanup interval: 60 seconds. */
-const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 1000;
-/**
- * In-memory nonce store for development and single-process deployments.
- *
- * Stores nonces in a Map keyed by "senderDid:nonce" with expiry timestamps.
- * Periodic cleanup removes expired entries to prevent unbounded growth.
- */
-export class MemoryNonceStore {
-    seen = new Map();
-    ttlMs;
-    cleanupIntervalMs;
-    timer = null;
-    constructor(opts) {
-        this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
-        this.cleanupIntervalMs = opts?.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
-        // Timer starts lazily on first check() to avoid blocking process exit in tests
-    }
-    /** Start cleanup timer on first use. */
-    ensureTimer() {
-        if (this.timer !== null)
-            return;
-        const t = setInterval(() => this.cleanup(), this.cleanupIntervalMs);
-        // Unref so the timer doesn't block Node.js process exit
-        if (typeof t === 'object' && 'unref' in t) {
-            t.unref(); // SAFETY: runtime check guards access
-        }
-        this.timer = t;
-    }
-    async check(nonce, senderDid) {
-        this.ensureTimer();
-        const key = `${senderDid}:${nonce}`;
-        const existing = this.seen.get(key);
-        const now = Date.now();
-        if (existing !== undefined && existing > now) {
-            return false;
-        }
-        this.seen.set(key, now + this.ttlMs);
-        return true;
-    }
-    cleanup() {
-        const now = Date.now();
-        for (const [key, expiry] of this.seen) {
-            if (expiry <= now)
-                this.seen.delete(key);
-        }
-    }
-    dispose() {
-        if (this.timer !== null) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-        this.seen.clear();
-    }
-    /** Number of active (non-expired) entries. Useful for testing. */
-    get size() {
-        return this.seen.size;
-    }
-}
+const DEFAULT_TTL_MS=6e5,DEFAULT_CLEANUP_INTERVAL_MS=6e4;export class MemoryNonceStore{seen=new Map;ttlMs;cleanupIntervalMs;timer=null;constructor(e){this.ttlMs=e?.ttlMs??6e5,this.cleanupIntervalMs=e?.cleanupIntervalMs??6e4}ensureTimer(){if(null!==this.timer)return;const e=setInterval(()=>this.cleanup(),this.cleanupIntervalMs);"object"==typeof e&&"unref"in e&&e.unref(),this.timer=e}buildKey(e,t,s){if(null==s)return`${t}:${e}`;return`${t}:${e}:${"string"==typeof s.shareGroupId?s.shareGroupId:""}:${"number"==typeof s.shareIndex?String(s.shareIndex):""}`}async check(e,t,s){this.ensureTimer();const n=this.buildKey(e,t,s),r=this.seen.get(n),i=Date.now();return!(void 0!==r&&r>i)&&(this.seen.set(n,i+this.ttlMs),!0)}cleanup(){const e=Date.now(),t=Array.from(this.seen.keys());for(const s of t){const t=this.seen.get(s);void 0!==t&&t<=e&&this.seen.delete(s)}}dispose(){null!==this.timer&&(clearInterval(this.timer),this.timer=null),this.seen.clear()}get size(){return this.seen.size}}

package/dist-standalone/package.json

@@ -2,7 +2,6 @@
   "type": "module",
   "imports": {
     "@private.me/shared": "./_deps/shared/index.js",
-    "@private.me/crypto": "./_deps/crypto/index.js",
     "@private.me/xchange": "./_deps/xchange/index.js",
     "@private.me/ux-helpers": "./_deps/ux-helpers/index.js",
     "@private.me/xregistry": "./_deps/xregistry/index.js",

package/dist-standalone/pairing-manager.js

@@ -1,219 +1 @@
-/**
- * @module pairing-manager
- * Security validation for peer-to-peer device pairing via mDNS.
- *
- * Security properties:
- * - 16-byte cryptographically secure nonce (prevents replay attacks)
- * - 60-second timeout (limits attack window)
- * - User confirmation required on BOTH devices
- * - Nonce echo in response (prevents MITM substitution)
- * - Trust registry integration (stores paired DIDs with scopes)
- * - Gold Standard compliant (GS-CONNECT requirement #26, GS-SEC-RNG compliant)
- */
-import { ok, err } from"./_deps/shared/index.js";
-/**
- * Pairing manager for secure peer-to-peer device pairing.
- *
- * Implements challenge-response protocol with user confirmation.
- * Integrates with trust registry for persistent pairing storage.
- */
-export class PairingManager {
-    pendingNonces = new Map(); // nonce → timestamp
-    registry;
-    deviceDid;
-    /**
-     * Create pairing manager.
-     *
-     * @param deviceDid - DID of this device
-     * @param registry - Trust registry instance
-     */
-    constructor(deviceDid, registry) {
-        this.deviceDid = deviceDid;
-        this.registry = registry;
-        // Clean up expired nonces every 10 seconds
-        setInterval(() => {
-            const now = Date.now();
-            for (const [nonce, timestamp] of this.pendingNonces.entries()) {
-                if (now - timestamp > 60_000) {
-                    this.pendingNonces.delete(nonce);
-                }
-            }
-        }, 10_000);
-    }
-    /**
-     * Create pairing request.
-     *
-     * Generates cryptographically secure nonce and stores it for validation.
-     * Device A calls this before sending request to Device B.
-     *
-     * @returns Pairing request to send to remote device
-     *
-     * @example
-     * ```typescript
-     * const manager = new PairingManager('did:key:z6MkA...', registry);
-     * const request = manager.createRequest();
-     * // Send request to Device B via HTTP POST
-     * const response = await fetch(`${deviceB.endpoint}/pair`, {
-     *   method: 'POST',
-     *   body: JSON.stringify(request),
-     * });
-     * ```
-     */
-    createRequest() {
-        // Generate cryptographically secure nonce (GS-SEC-RNG: NEVER use Math.random)
-        const nonceBytes = new Uint8Array(16);
-        if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
-            globalThis.crypto.getRandomValues(nonceBytes);
-        }
-        else {
-            // Node.js environment
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            const crypto = require('node:crypto');
-            crypto.getRandomValues(nonceBytes);
-        }
-        const nonce = Array.from(nonceBytes)
-            .map((b) => b.toString(16).padStart(2, '0'))
-            .join('');
-        const timestamp = Date.now();
-        // Store nonce for validation (60-second TTL)
-        this.pendingNonces.set(nonce, timestamp);
-        return {
-            device_a_did: this.deviceDid,
-            nonce,
-            timestamp,
-        };
-    }
-    /**
-     * Validate pairing request.
-     *
-     * Checks timeout and nonce uniqueness.
-     * Device B calls this when receiving request from Device A.
-     *
-     * @param request - Pairing request from remote device
-     * @returns Ok if valid, Err with reason if invalid
-     *
-     * @example
-     * ```typescript
-     * // Device B receives request
-     * const validation = manager.validateRequest(request);
-     * if (!validation.ok) {
-     *   return res.status(400).json({ error: validation.error });
-     * }
-     * ```
-     */
-    validateRequest(request) {
-        // Check timeout (60-second window)
-        const age = Date.now() - request.timestamp;
-        if (age > 60_000) {
-            return err(`Request expired (${Math.floor(age / 1000)}s old, max 60s)`);
-        }
-        if (age < 0) {
-            return err('Request timestamp in the future (clock skew detected)');
-        }
-        // Check required fields
-        if (!request.device_a_did || !request.nonce || !request.timestamp) {
-            return err('Missing required fields (device_a_did, nonce, timestamp)');
-        }
-        return ok(undefined);
-    }
-    /**
-     * Accept pairing request.
-     *
-     * Shows UI prompt for user confirmation, then stores in trust registry.
-     * Device B calls this after validating request.
-     *
-     * @param request - Validated pairing request
-     * @param promptCallback - Async function to show UI prompt (returns true if accepted)
-     * @returns Pairing response to send back to Device A
-     *
-     * @example
-     * ```typescript
-     * const response = await manager.acceptPairing(request, async () => {
-     *   // Show modal: "Device {name} wants to pair. Accept?"
-     *   return await showConfirmationDialog({
-     *     title: 'Pair with Device?',
-     *     message: `DID: ${request.device_a_did.slice(0, 20)}...`,
-     *   });
-     * });
-     *
-     * if (response.ok && response.value.accepted) {
-     *   // Send response back to Device A
-     * }
-     * ```
-     */
-    async acceptPairing(request, promptCallback) {
-        // Validate request first
-        const validation = this.validateRequest(request);
-        if (!validation.ok) {
-            return err(validation.error);
-        }
-        // Prompt user for confirmation
-        const accepted = await promptCallback();
-        if (accepted) {
-            // Store in trust registry (Device A → Device B)
-            const registerResult = await this.registry.register(request.device_a_did, new Uint8Array(32), 'Paired Device', ['pairing']);
-            if (!registerResult.ok) {
-                const errorMsg = typeof registerResult.error === 'string'
-                    ? registerResult.error
-                    : 'Unknown error';
-                return err(`Failed to register pairing: ${errorMsg}`);
-            }
-        }
-        // Return response (echo nonce to prevent MITM)
-        return ok({
-            device_b_did: this.deviceDid,
-            accepted,
-            nonce: request.nonce,
-        });
-    }
-    /**
-     * Finalize pairing.
-     *
-     * Verifies response nonce and stores remote DID in trust registry.
-     * Device A calls this after receiving response from Device B.
-     *
-     * @param response - Pairing response from Device B
-     * @param expectedNonce - Nonce from original request (for verification)
-     * @returns Ok if successful, Err if nonce mismatch or storage failed
-     *
-     * @example
-     * ```typescript
-     * const request = manager.createRequest();
-     * const response = await sendPairingRequest(deviceB.endpoint, request);
-     *
-     * const result = await manager.finalizePairing(response, request.nonce);
-     * if (result.ok) {
-     *   console.log('Pairing successful!');
-     * } else {
-     *   console.error('Pairing failed:', result.error);
-     * }
-     * ```
-     */
-    async finalizePairing(response, expectedNonce) {
-        // Verify nonce echo (prevents MITM substitution)
-        if (response.nonce !== expectedNonce) {
-            return err('Nonce mismatch (possible MITM attack)');
-        }
-        // Check if pairing was accepted
-        if (!response.accepted) {
-            return err('Pairing rejected by remote device');
-        }
-        // Remove nonce from pending set
-        this.pendingNonces.delete(expectedNonce);
-        // Store in trust registry (Device B → Device A)
-        const registerResult = await this.registry.register(response.device_b_did, new Uint8Array(32), 'Paired Device', ['pairing']);
-        if (!registerResult.ok) {
-            const errorMsg = typeof registerResult.error === 'string'
-                ? registerResult.error
-                : 'Unknown error';
-            return err(`Failed to register pairing: ${errorMsg}`);
-        }
-        return ok(undefined);
-    }
-    /**
-     * Get pending nonce count (for debugging/monitoring).
-     */
-    getPendingNonceCount() {
-        return this.pendingNonces.size;
-    }
-}
+import{ok,err}from"./_deps/shared/index.js";export class PairingManager{pendingNonces=new Map;registry;deviceDid;constructor(e,r){this.deviceDid=e,this.registry=r,setInterval(()=>{const e=Date.now();for(const[r,i]of this.pendingNonces.entries())e-i>6e4&&this.pendingNonces.delete(r)},1e4)}createRequest(){const e=new Uint8Array(16);if(void 0!==globalThis.crypto&&globalThis.crypto.getRandomValues)globalThis.crypto.getRandomValues(e);else{require("node:crypto").getRandomValues(e)}const r=Array.from(e).map(e=>e.toString(16).padStart(2,"0")).join(""),i=Date.now();return this.pendingNonces.set(r,i),{device_a_did:this.deviceDid,nonce:r,timestamp:i}}validateRequest(e){const r=Date.now()-e.timestamp;return r>6e4?err(`Request expired (${Math.floor(r/1e3)}s old, max 60s)`):r<0?err("Request timestamp in the future (clock skew detected)"):e.device_a_did&&e.nonce&&e.timestamp?ok(void 0):err("Missing required fields (device_a_did, nonce, timestamp)")}async acceptPairing(e,r){const i=this.validateRequest(e);if(!i.ok)return err(i.error);const t=await r();if(t){const r=await this.registry.register(e.device_a_did,new Uint8Array(32),"Paired Device",["pairing"]);if(!r.ok){const e="string"==typeof r.error?r.error:"Unknown error";return err(`Failed to register pairing: ${e}`)}}return ok({device_b_did:this.deviceDid,accepted:t,nonce:e.nonce})}async finalizePairing(e,r){if(e.nonce!==r)return err("Nonce mismatch (possible MITM attack)");if(!e.accepted)return err("Pairing rejected by remote device");this.pendingNonces.delete(r);const i=await this.registry.register(e.device_b_did,new Uint8Array(32),"Paired Device",["pairing"]);if(!i.ok){const e="string"==typeof i.error?i.error:"Unknown error";return err(`Failed to register pairing: ${e}`)}return ok(void 0)}getPendingNonceCount(){return this.pendingNonces.size}}

package/dist-standalone/plugin-system.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @module plugin-system
+ * Extensible plugin and middleware architecture for xBind
+ *
+ * Provides hooks for message processing, encryption, decryption, and custom logic.
+ * Supports both synchronous and asynchronous plugin execution.
+ */
+import type { Result } from '@private.me/shared';
+import type { AnyTransportEnvelope } from './envelope.js';
+import type { AgentIdentity } from './identity.js';
+/**
+ * Plugin execution context provided to all hooks.
+ * Contains agent identity, message metadata, and shared state.
+ */
+export interface PluginContext {
+    /** Agent identity making the call */
+    readonly agent: AgentIdentity;
+    /** Recipient DID (if applicable) */
+    readonly recipient?: string;
+    /** Message scope */
+    readonly scope?: string;
+    /** Message timestamp */
+    readonly timestamp: number;
+    /** Shared state across plugins in the chain */
+    readonly state: Map<string, unknown>;
+    /** Plugin metadata */
+    readonly metadata: Record<string, unknown>;
+}
+/**
+ * Hook execution result.
+ * Plugins can modify the payload, add metadata, or abort execution.
+ */
+export interface HookResult<T> {
+    /** Modified payload (or original if unchanged) */
+    readonly payload: T;
+    /** Metadata to attach to context */
+    readonly metadata?: Record<string, unknown>;
+    /** Abort flag - if true, stops further processing */
+    readonly abort?: boolean;
+    /** Abort reason (if abort === true) */
+    readonly reason?: string;
+}
+/**
+ * Plugin interface.
+ * All plugins must implement this interface.
+ */
+export interface Plugin {
+    /** Plugin name (must be unique) */
+    readonly name: string;
+    /** Plugin version */
+    readonly version: string;
+    /** Plugin description */
+    readonly description?: string;
+    /** Plugin priority (lower = earlier execution, default: 100) */
+    readonly priority?: number;
+    /** Called before sending a message */
+    onSend?(payload: unknown, context: PluginContext): Promise<Result<HookResult<unknown>, string>> | Result<HookResult<unknown>, string>;
+    /** Called after receiving a message */
+    onReceive?(envelope: AnyTransportEnvelope, context: PluginContext): Promise<Result<HookResult<AnyTransportEnvelope>, string>> | Result<HookResult<AnyTransportEnvelope>, string>;
+    /** Called before encryption */
+    onEncrypt?(plaintext: Uint8Array, context: PluginContext): Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>;
+    /** Called after decryption */
+    onDecrypt?(plaintext: Uint8Array, context: PluginContext): Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>;
+    /** Called on plugin initialization */
+    onInit?(): Promise<Result<void, string>> | Result<void, string>;
+    /** Called on plugin cleanup */
+    onDestroy?(): Promise<Result<void, string>> | Result<void, string>;
+}
+/**
+ * Middleware chain executor.
+ * Runs plugins in priority order and handles errors.
+ */
+export declare class MiddlewareChain {
+    private plugins;
+    private initialized;
+    constructor(plugins?: Plugin[]);
+    /**
+     * Register a plugin.
+     * Plugins are automatically sorted by priority after registration.
+     */
+    register(plugin: Plugin): Result<void, string>;
+    /**
+     * Unregister a plugin by name.
+     */
+    unregister(name: string): Result<void, string>;
+    /**
+     * Get all registered plugins.
+     */
+    getPlugins(): readonly Plugin[];
+    /**
+     * Initialize all plugins.
+     * Must be called before executing hooks.
+     */
+    initialize(): Promise<Result<void, string>>;
+    /**
+     * Destroy all plugins and cleanup resources.
+     */
+    destroy(): Promise<Result<void, string>>;
+    /**
+     * Execute onSend hooks.
+     */
+    executeSend(payload: unknown, context: PluginContext): Promise<Result<unknown, string>>;
+    /**
+     * Execute onReceive hooks.
+     */
+    executeReceive(envelope: AnyTransportEnvelope, context: PluginContext): Promise<Result<AnyTransportEnvelope, string>>;
+    /**
+     * Execute onEncrypt hooks.
+     */
+    executeEncrypt(plaintext: Uint8Array, context: PluginContext): Promise<Result<Uint8Array, string>>;
+    /**
+     * Execute onDecrypt hooks.
+     */
+    executeDecrypt(plaintext: Uint8Array, context: PluginContext): Promise<Result<Uint8Array, string>>;
+}
+/**
+ * Create a plugin context.
+ */
+export declare function createPluginContext(agent: AgentIdentity, options?: {
+    recipient?: string;
+    scope?: string;
+    timestamp?: number;
+    state?: Map<string, unknown>;
+    metadata?: Record<string, unknown>;
+}): PluginContext;
+/**
+ * Plugin builder for creating plugins with a fluent API.
+ */
+export declare class PluginBuilder {
+    private plugin;
+    constructor(name: string, version: string);
+    description(desc: string): this;
+    priority(p: number): this;
+    onSend(hook: (payload: unknown, context: PluginContext) => Promise<Result<HookResult<unknown>, string>> | Result<HookResult<unknown>, string>): this;
+    onReceive(hook: (envelope: AnyTransportEnvelope, context: PluginContext) => Promise<Result<HookResult<AnyTransportEnvelope>, string>> | Result<HookResult<AnyTransportEnvelope>, string>): this;
+    onEncrypt(hook: (plaintext: Uint8Array, context: PluginContext) => Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>): this;
+    onDecrypt(hook: (plaintext: Uint8Array, context: PluginContext) => Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>): this;
+    onInit(hook: () => Promise<Result<void, string>> | Result<void, string>): this;
+    onDestroy(hook: () => Promise<Result<void, string>> | Result<void, string>): this;
+    build(): Plugin;
+}
+/**
+ * Create a plugin builder.
+ */
+export declare function createPlugin(name: string, version: string): PluginBuilder;

package/dist-standalone/plugin-system.js

@@ -0,0 +1 @@
+import{ok,err}from"./_deps/shared/index.js";export class MiddlewareChain{plugins=[];initialized=!1;constructor(t=[]){this.plugins=[...t].sort((t,e)=>(t.priority??100)-(e.priority??100))}register(t){return this.plugins.some(e=>e.name===t.name)?err(`PLUGIN_ALREADY_REGISTERED:${t.name}`):(this.plugins.push(t),this.plugins.sort((t,e)=>(t.priority??100)-(e.priority??100)),ok(void 0))}unregister(t){const e=this.plugins.findIndex(e=>e.name===t);return-1===e?err(`PLUGIN_NOT_FOUND:${t}`):(this.plugins.splice(e,1),ok(void 0))}getPlugins(){return[...this.plugins]}async initialize(){if(this.initialized)return ok(void 0);for(const t of this.plugins)if(t.onInit){const e=await t.onInit();if(!1===e.ok)return err(`PLUGIN_INIT_FAILED:${t.name}:${e.error}`)}return this.initialized=!0,ok(void 0)}async destroy(){const t=[];for(const e of this.plugins)if(e.onDestroy){const r=await e.onDestroy();!1===r.ok&&t.push(`${e.name}:${r.error}`)}return this.initialized=!1,t.length>0?err(`PLUGIN_DESTROY_FAILED:${t.join(",")}`):ok(void 0)}async executeSend(t,e){if(!this.initialized)return err("MIDDLEWARE_NOT_INITIALIZED");let r=t;for(const t of this.plugins)if(t.onSend){const n=await t.onSend(r,e);if(!1===n.ok)return err(`PLUGIN_HOOK_FAILED:${t.name}:${n.error}`);const i=n.value;if(i.abort)return err(`PLUGIN_ABORTED:${t.name}:${i.reason??"no reason"}`);r=i.payload,i.metadata&&Object.assign(e.metadata,i.metadata)}return ok(r)}async executeReceive(t,e){if(!this.initialized)return err("MIDDLEWARE_NOT_INITIALIZED");let r=t;for(const t of this.plugins)if(t.onReceive){const n=await t.onReceive(r,e);if(!1===n.ok)return err(`PLUGIN_HOOK_FAILED:${t.name}:${n.error}`);const i=n.value;if(i.abort)return err(`PLUGIN_ABORTED:${t.name}:${i.reason??"no reason"}`);r=i.payload,i.metadata&&Object.assign(e.metadata,i.metadata)}return ok(r)}async executeEncrypt(t,e){if(!this.initialized)return err("MIDDLEWARE_NOT_INITIALIZED");let r=t;for(const t of this.plugins)if(t.onEncrypt){const n=await t.onEncrypt(r,e);if(!1===n.ok)return err(`PLUGIN_HOOK_FAILED:${t.name}:${n.error}`);const i=n.value;if(i.abort)return err(`PLUGIN_ABORTED:${t.name}:${i.reason??"no reason"}`);r=i.payload,i.metadata&&Object.assign(e.metadata,i.metadata)}return ok(r)}async executeDecrypt(t,e){if(!this.initialized)return err("MIDDLEWARE_NOT_INITIALIZED");let r=t;for(const t of this.plugins)if(t.onDecrypt){const n=await t.onDecrypt(r,e);if(!1===n.ok)return err(`PLUGIN_HOOK_FAILED:${t.name}:${n.error}`);const i=n.value;if(i.abort)return err(`PLUGIN_ABORTED:${t.name}:${i.reason??"no reason"}`);r=i.payload,i.metadata&&Object.assign(e.metadata,i.metadata)}return ok(r)}}export function createPluginContext(t,e={}){return{agent:t,recipient:e.recipient,scope:e.scope,timestamp:e.timestamp??Date.now(),state:e.state??new Map,metadata:e.metadata??{}}}export class PluginBuilder{plugin={};constructor(t,e){this.plugin.name=t,this.plugin.version=e}description(t){return this.plugin.description=t,this}priority(t){return this.plugin.priority=t,this}onSend(t){return this.plugin.onSend=t,this}onReceive(t){return this.plugin.onReceive=t,this}onEncrypt(t){return this.plugin.onEncrypt=t,this}onDecrypt(t){return this.plugin.onDecrypt=t,this}onInit(t){return this.plugin.onInit=t,this}onDestroy(t){return this.plugin.onDestroy=t,this}build(){if(!this.plugin.name||!this.plugin.version)throw new Error("Plugin name and version are required");return this.plugin}}export function createPlugin(t,e){return new PluginBuilder(t,e)}