@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/plugin-system.js

@@ -1 +1,257 @@
-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)}
+/**
+ * @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 { ok, err } from"./_deps/shared/index.js";
+/**
+ * Middleware chain executor.
+ * Runs plugins in priority order and handles errors.
+ */
+export class MiddlewareChain {
+    plugins = [];
+    initialized = false;
+    constructor(plugins = []) {
+        this.plugins = [...plugins].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    }
+    /**
+     * Register a plugin.
+     * Plugins are automatically sorted by priority after registration.
+     */
+    register(plugin) {
+        if (this.plugins.some((p) => p.name === plugin.name)) {
+            return err(`PLUGIN_ALREADY_REGISTERED:${plugin.name}`);
+        }
+        this.plugins.push(plugin);
+        this.plugins.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+        return ok(undefined);
+    }
+    /**
+     * Unregister a plugin by name.
+     */
+    unregister(name) {
+        const index = this.plugins.findIndex((p) => p.name === name);
+        if (index === -1) {
+            return err(`PLUGIN_NOT_FOUND:${name}`);
+        }
+        this.plugins.splice(index, 1);
+        return ok(undefined);
+    }
+    /**
+     * Get all registered plugins.
+     */
+    getPlugins() {
+        return [...this.plugins];
+    }
+    /**
+     * Initialize all plugins.
+     * Must be called before executing hooks.
+     */
+    async initialize() {
+        if (this.initialized) {
+            return ok(undefined);
+        }
+        for (const plugin of this.plugins) {
+            if (plugin.onInit) {
+                const result = await plugin.onInit();
+                if (result.ok === false) {
+                    return err(`PLUGIN_INIT_FAILED:${plugin.name}:${result.error}`);
+                }
+            }
+        }
+        this.initialized = true;
+        return ok(undefined);
+    }
+    /**
+     * Destroy all plugins and cleanup resources.
+     */
+    async destroy() {
+        const errors = [];
+        for (const plugin of this.plugins) {
+            if (plugin.onDestroy) {
+                const result = await plugin.onDestroy();
+                if (result.ok === false) {
+                    errors.push(`${plugin.name}:${result.error}`);
+                }
+            }
+        }
+        this.initialized = false;
+        if (errors.length > 0) {
+            return err(`PLUGIN_DESTROY_FAILED:${errors.join(',')}`);
+        }
+        return ok(undefined);
+    }
+    /**
+     * Execute onSend hooks.
+     */
+    async executeSend(payload, context) {
+        if (!this.initialized) {
+            return err('MIDDLEWARE_NOT_INITIALIZED');
+        }
+        let currentPayload = payload;
+        for (const plugin of this.plugins) {
+            if (plugin.onSend) {
+                const result = await plugin.onSend(currentPayload, context);
+                if (result.ok === false) {
+                    return err(`PLUGIN_HOOK_FAILED:${plugin.name}:${result.error}`);
+                }
+                const hookResult = result.value;
+                if (hookResult.abort) {
+                    return err(`PLUGIN_ABORTED:${plugin.name}:${hookResult.reason ?? 'no reason'}`);
+                }
+                currentPayload = hookResult.payload;
+                if (hookResult.metadata) {
+                    Object.assign(context.metadata, hookResult.metadata);
+                }
+            }
+        }
+        return ok(currentPayload);
+    }
+    /**
+     * Execute onReceive hooks.
+     */
+    async executeReceive(envelope, context) {
+        if (!this.initialized) {
+            return err('MIDDLEWARE_NOT_INITIALIZED');
+        }
+        let currentEnvelope = envelope;
+        for (const plugin of this.plugins) {
+            if (plugin.onReceive) {
+                const result = await plugin.onReceive(currentEnvelope, context);
+                if (result.ok === false) {
+                    return err(`PLUGIN_HOOK_FAILED:${plugin.name}:${result.error}`);
+                }
+                const hookResult = result.value;
+                if (hookResult.abort) {
+                    return err(`PLUGIN_ABORTED:${plugin.name}:${hookResult.reason ?? 'no reason'}`);
+                }
+                currentEnvelope = hookResult.payload;
+                if (hookResult.metadata) {
+                    Object.assign(context.metadata, hookResult.metadata);
+                }
+            }
+        }
+        return ok(currentEnvelope);
+    }
+    /**
+     * Execute onEncrypt hooks.
+     */
+    async executeEncrypt(plaintext, context) {
+        if (!this.initialized) {
+            return err('MIDDLEWARE_NOT_INITIALIZED');
+        }
+        let currentPlaintext = plaintext;
+        for (const plugin of this.plugins) {
+            if (plugin.onEncrypt) {
+                const result = await plugin.onEncrypt(currentPlaintext, context);
+                if (result.ok === false) {
+                    return err(`PLUGIN_HOOK_FAILED:${plugin.name}:${result.error}`);
+                }
+                const hookResult = result.value;
+                if (hookResult.abort) {
+                    return err(`PLUGIN_ABORTED:${plugin.name}:${hookResult.reason ?? 'no reason'}`);
+                }
+                currentPlaintext = hookResult.payload;
+                if (hookResult.metadata) {
+                    Object.assign(context.metadata, hookResult.metadata);
+                }
+            }
+        }
+        return ok(currentPlaintext);
+    }
+    /**
+     * Execute onDecrypt hooks.
+     */
+    async executeDecrypt(plaintext, context) {
+        if (!this.initialized) {
+            return err('MIDDLEWARE_NOT_INITIALIZED');
+        }
+        let currentPlaintext = plaintext;
+        for (const plugin of this.plugins) {
+            if (plugin.onDecrypt) {
+                const result = await plugin.onDecrypt(currentPlaintext, context);
+                if (result.ok === false) {
+                    return err(`PLUGIN_HOOK_FAILED:${plugin.name}:${result.error}`);
+                }
+                const hookResult = result.value;
+                if (hookResult.abort) {
+                    return err(`PLUGIN_ABORTED:${plugin.name}:${hookResult.reason ?? 'no reason'}`);
+                }
+                currentPlaintext = hookResult.payload;
+                if (hookResult.metadata) {
+                    Object.assign(context.metadata, hookResult.metadata);
+                }
+            }
+        }
+        return ok(currentPlaintext);
+    }
+}
+/**
+ * Create a plugin context.
+ */
+export function createPluginContext(agent, options = {}) {
+    return {
+        agent,
+        recipient: options.recipient,
+        scope: options.scope,
+        timestamp: options.timestamp ?? Date.now(),
+        state: options.state ?? new Map(),
+        metadata: options.metadata ?? {},
+    };
+}
+/**
+ * Plugin builder for creating plugins with a fluent API.
+ */
+export class PluginBuilder {
+    plugin = {};
+    constructor(name, version) {
+        this.plugin.name = name;
+        this.plugin.version = version;
+    }
+    description(desc) {
+        this.plugin.description = desc;
+        return this;
+    }
+    priority(p) {
+        this.plugin.priority = p;
+        return this;
+    }
+    onSend(hook) {
+        this.plugin.onSend = hook;
+        return this;
+    }
+    onReceive(hook) {
+        this.plugin.onReceive = hook;
+        return this;
+    }
+    onEncrypt(hook) {
+        this.plugin.onEncrypt = hook;
+        return this;
+    }
+    onDecrypt(hook) {
+        this.plugin.onDecrypt = hook;
+        return this;
+    }
+    onInit(hook) {
+        this.plugin.onInit = hook;
+        return this;
+    }
+    onDestroy(hook) {
+        this.plugin.onDestroy = hook;
+        return this;
+    }
+    build() {
+        if (!this.plugin.name || !this.plugin.version) {
+            throw new Error('Plugin name and version are required');
+        }
+        return this.plugin;
+    }
+}
+/**
+ * Create a plugin builder.
+ */
+export function createPlugin(name, version) {
+    return new PluginBuilder(name, version);
+}

package/dist-standalone/plugins/logging.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @module plugins/logging
+ * Logging plugin for xBind plugin system
+ *
+ * Captures send, receive, encrypt, and decrypt events for debugging and audit trails.
+ */
+import type { Result } from '@private.me/shared';
+import type { Plugin, PluginContext, HookResult } from '../plugin-system.js';
+import type { AnyTransportEnvelope } from '../envelope.js';
+/**
+ * Log level enum.
+ */
+export declare enum LogLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error"
+}
+/**
+ * Log entry structure.
+ */
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    event: 'send' | 'receive' | 'encrypt' | 'decrypt';
+    agent: string;
+    recipient?: string;
+    scope?: string;
+    payloadSize?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Logging plugin options.
+ */
+export interface LoggingPluginOptions {
+    /** Log level threshold (default: INFO) */
+    level?: LogLevel;
+    /** Include payload sizes in logs (default: true) */
+    includeSize?: boolean;
+    /** Include metadata in logs (default: false) */
+    includeMetadata?: boolean;
+    /** Custom log handler (default: console.log) */
+    logHandler?: (entry: LogEntry) => void;
+    /** Filter function to exclude certain logs */
+    filter?: (entry: LogEntry) => boolean;
+}
+/**
+ * Logging plugin implementation.
+ * Captures all message processing events and outputs structured logs.
+ */
+export declare class LoggingPlugin implements Plugin {
+    readonly name = "logging";
+    readonly version = "1.0.0";
+    readonly description = "Captures message processing events for debugging and audit trails";
+    readonly priority = 10;
+    private options;
+    private logs;
+    constructor(options?: LoggingPluginOptions);
+    onInit(): Result<void, string>;
+    onDestroy(): Result<void, string>;
+    onSend(payload: unknown, context: PluginContext): Result<HookResult<unknown>, string>;
+    onReceive(envelope: AnyTransportEnvelope, context: PluginContext): Result<HookResult<AnyTransportEnvelope>, string>;
+    onEncrypt(plaintext: Uint8Array, context: PluginContext): Result<HookResult<Uint8Array>, string>;
+    onDecrypt(plaintext: Uint8Array, context: PluginContext): Result<HookResult<Uint8Array>, string>;
+    /**
+     * Get all captured logs.
+     */
+    getLogs(): readonly LogEntry[];
+    /**
+     * Clear all logs.
+     */
+    clearLogs(): void;
+    /**
+     * Get logs filtered by criteria.
+     */
+    getFilteredLogs(filter: (entry: LogEntry) => boolean): LogEntry[];
+    private log;
+    private shouldLog;
+    private estimateSize;
+}
+/**
+ * Create a logging plugin with options.
+ */
+export declare function createLoggingPlugin(options?: LoggingPluginOptions): LoggingPlugin;

package/dist-standalone/plugins/logging.js

@@ -0,0 +1,163 @@
+/**
+ * @module plugins/logging
+ * Logging plugin for xBind plugin system
+ *
+ * Captures send, receive, encrypt, and decrypt events for debugging and audit trails.
+ */
+import { ok } from"../_deps/shared/index.js";
+/**
+ * Log level enum.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "debug";
+    LogLevel["INFO"] = "info";
+    LogLevel["WARN"] = "warn";
+    LogLevel["ERROR"] = "error";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Logging plugin implementation.
+ * Captures all message processing events and outputs structured logs.
+ */
+export class LoggingPlugin {
+    name = 'logging';
+    version = '1.0.0';
+    description = 'Captures message processing events for debugging and audit trails';
+    priority = 10; // Execute early
+    options;
+    logs = [];
+    constructor(options = {}) {
+        this.options = {
+            level: options.level ?? LogLevel.INFO,
+            includeSize: options.includeSize ?? true,
+            includeMetadata: options.includeMetadata ?? false,
+            logHandler: options.logHandler ?? ((entry) => console.log(JSON.stringify(entry))),
+            filter: options.filter ?? (() => true),
+        };
+    }
+    onInit() {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.INFO,
+            event: 'send',
+            agent: 'system',
+            metadata: { message: 'Logging plugin initialized' },
+        });
+        return ok(undefined);
+    }
+    onDestroy() {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.INFO,
+            event: 'send',
+            agent: 'system',
+            metadata: { message: 'Logging plugin destroyed', totalLogs: this.logs.length },
+        });
+        this.logs = [];
+        return ok(undefined);
+    }
+    onSend(payload, context) {
+        const size = this.options.includeSize ? this.estimateSize(payload) : undefined;
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.INFO,
+            event: 'send',
+            agent: context.agent.did,
+            recipient: context.recipient,
+            scope: context.scope,
+            payloadSize: size,
+            metadata: this.options.includeMetadata ? context.metadata : undefined,
+        });
+        return ok({ payload });
+    }
+    onReceive(envelope, context) {
+        const size = this.options.includeSize ? this.estimateSize(envelope) : undefined;
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.INFO,
+            event: 'receive',
+            agent: context.agent.did,
+            recipient: envelope.sender,
+            scope: context.scope,
+            payloadSize: size,
+            metadata: this.options.includeMetadata ? context.metadata : undefined,
+        });
+        return ok({ payload: envelope });
+    }
+    onEncrypt(plaintext, context) {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.DEBUG,
+            event: 'encrypt',
+            agent: context.agent.did,
+            recipient: context.recipient,
+            scope: context.scope,
+            payloadSize: this.options.includeSize ? plaintext.length : undefined,
+            metadata: this.options.includeMetadata ? context.metadata : undefined,
+        });
+        return ok({ payload: plaintext });
+    }
+    onDecrypt(plaintext, context) {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.DEBUG,
+            event: 'decrypt',
+            agent: context.agent.did,
+            scope: context.scope,
+            payloadSize: this.options.includeSize ? plaintext.length : undefined,
+            metadata: this.options.includeMetadata ? context.metadata : undefined,
+        });
+        return ok({ payload: plaintext });
+    }
+    /**
+     * Get all captured logs.
+     */
+    getLogs() {
+        return [...this.logs];
+    }
+    /**
+     * Clear all logs.
+     */
+    clearLogs() {
+        this.logs = [];
+    }
+    /**
+     * Get logs filtered by criteria.
+     */
+    getFilteredLogs(filter) {
+        return this.logs.filter(filter);
+    }
+    log(entry) {
+        if (!this.shouldLog(entry.level)) {
+            return;
+        }
+        if (!this.options.filter(entry)) {
+            return;
+        }
+        this.logs.push(entry);
+        this.options.logHandler(entry);
+    }
+    shouldLog(level) {
+        const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+        const thresholdIndex = levels.indexOf(this.options.level);
+        const currentIndex = levels.indexOf(level);
+        return currentIndex >= thresholdIndex;
+    }
+    estimateSize(value) {
+        if (value instanceof Uint8Array) {
+            return value.length;
+        }
+        try {
+            return JSON.stringify(value).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+/**
+ * Create a logging plugin with options.
+ */
+export function createLoggingPlugin(options) {
+    return new LoggingPlugin(options);
+}

package/dist-standalone/plugins/metrics.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @module plugins/metrics
+ * Metrics plugin for xBind plugin system
+ *
+ * Tracks performance metrics, message counts, and error rates.
+ */
+import type { Result } from '@private.me/shared';
+import type { Plugin, PluginContext, HookResult } from '../plugin-system.js';
+import type { AnyTransportEnvelope } from '../envelope.js';
+/**
+ * Metric entry structure.
+ */
+export interface MetricEntry {
+    timestamp: number;
+    event: 'send' | 'receive' | 'encrypt' | 'decrypt';
+    duration: number;
+    success: boolean;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Aggregated metrics.
+ */
+export interface AggregatedMetrics {
+    /** Total number of send operations */
+    totalSends: number;
+    /** Total number of receive operations */
+    totalReceives: number;
+    /** Total number of encrypt operations */
+    totalEncrypts: number;
+    /** Total number of decrypt operations */
+    totalDecrypts: number;
+    /** Average send duration (ms) */
+    avgSendDuration: number;
+    /** Average receive duration (ms) */
+    avgReceiveDuration: number;
+    /** Average encrypt duration (ms) */
+    avgEncryptDuration: number;
+    /** Average decrypt duration (ms) */
+    avgDecryptDuration: number;
+    /** Total errors */
+    totalErrors: number;
+    /** Error rate (0-1) */
+    errorRate: number;
+    /** Uptime (ms) */
+    uptime: number;
+}
+/**
+ * Metrics plugin options.
+ */
+export interface MetricsPluginOptions {
+    /** Enable high-resolution timing (default: true) */
+    highResolution?: boolean;
+    /** Maximum metrics to store in memory (default: 10000) */
+    maxMetrics?: number;
+    /** Metrics export callback */
+    onExport?: (metrics: MetricEntry[]) => void;
+    /** Export interval in milliseconds (default: 60000 - 1 minute) */
+    exportInterval?: number;
+}
+/**
+ * Metrics plugin implementation.
+ * Tracks performance and usage statistics for all operations.
+ */
+export declare class MetricsPlugin implements Plugin {
+    readonly name = "metrics";
+    readonly version = "1.0.0";
+    readonly description = "Tracks performance metrics, message counts, and error rates";
+    readonly priority = 20;
+    private options;
+    private metrics;
+    private startTime;
+    private exportTimer?;
+    constructor(options?: MetricsPluginOptions);
+    onInit(): Result<void, string>;
+    onDestroy(): Result<void, string>;
+    onSend(payload: unknown, context: PluginContext): Result<HookResult<unknown>, string>;
+    onReceive(envelope: AnyTransportEnvelope, context: PluginContext): Result<HookResult<AnyTransportEnvelope>, string>;
+    onEncrypt(plaintext: Uint8Array, context: PluginContext): Result<HookResult<Uint8Array>, string>;
+    onDecrypt(plaintext: Uint8Array, context: PluginContext): Result<HookResult<Uint8Array>, string>;
+    /**
+     * Get all captured metrics.
+     */
+    getMetrics(): readonly MetricEntry[];
+    /**
+     * Get aggregated metrics summary.
+     */
+    getAggregatedMetrics(): AggregatedMetrics;
+    /**
+     * Clear all metrics.
+     */
+    clearMetrics(): void;
+    /**
+     * Export metrics using the configured callback.
+     */
+    export(): void;
+    /**
+     * Get metrics for a specific time range.
+     */
+    getMetricsInRange(startTime: number, endTime: number): MetricEntry[];
+    /**
+     * Get metrics for a specific event type.
+     */
+    getMetricsByEvent(event: 'send' | 'receive' | 'encrypt' | 'decrypt'): MetricEntry[];
+    private record;
+    private now;
+}
+/**
+ * Create a metrics plugin with options.
+ */
+export declare function createMetricsPlugin(options?: MetricsPluginOptions): MetricsPlugin;