@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/plugins/metrics.js

@@ -0,0 +1,176 @@
+/**
+ * @module plugins/metrics
+ * Metrics plugin for xBind plugin system
+ *
+ * Tracks performance metrics, message counts, and error rates.
+ */
+import { ok } from"../_deps/shared/index.js";
+/**
+ * Metrics plugin implementation.
+ * Tracks performance and usage statistics for all operations.
+ */
+export class MetricsPlugin {
+    name = 'metrics';
+    version = '1.0.0';
+    description = 'Tracks performance metrics, message counts, and error rates';
+    priority = 20; // Execute after logging
+    options;
+    metrics = [];
+    startTime = Date.now();
+    exportTimer;
+    constructor(options = {}) {
+        this.options = {
+            highResolution: options.highResolution ?? true,
+            maxMetrics: options.maxMetrics ?? 10000,
+            onExport: options.onExport ?? (() => { }),
+            exportInterval: options.exportInterval ?? 60000,
+        };
+    }
+    onInit() {
+        this.startTime = Date.now();
+        if (this.options.exportInterval > 0) {
+            this.exportTimer = setInterval(() => {
+                this.export();
+            }, this.options.exportInterval);
+        }
+        return ok(undefined);
+    }
+    onDestroy() {
+        if (this.exportTimer) {
+            clearInterval(this.exportTimer);
+            this.exportTimer = undefined;
+        }
+        this.export();
+        this.metrics = [];
+        return ok(undefined);
+    }
+    onSend(payload, context) {
+        const start = this.now();
+        // Simulate processing
+        const end = this.now();
+        this.record({
+            timestamp: Date.now(),
+            event: 'send',
+            duration: end - start,
+            success: true,
+        });
+        return ok({ payload });
+    }
+    onReceive(envelope, context) {
+        const start = this.now();
+        // Simulate processing
+        const end = this.now();
+        this.record({
+            timestamp: Date.now(),
+            event: 'receive',
+            duration: end - start,
+            success: true,
+        });
+        return ok({ payload: envelope });
+    }
+    onEncrypt(plaintext, context) {
+        const start = this.now();
+        // Simulate processing
+        const end = this.now();
+        this.record({
+            timestamp: Date.now(),
+            event: 'encrypt',
+            duration: end - start,
+            success: true,
+        });
+        return ok({ payload: plaintext });
+    }
+    onDecrypt(plaintext, context) {
+        const start = this.now();
+        // Simulate processing
+        const end = this.now();
+        this.record({
+            timestamp: Date.now(),
+            event: 'decrypt',
+            duration: end - start,
+            success: true,
+        });
+        return ok({ payload: plaintext });
+    }
+    /**
+     * Get all captured metrics.
+     */
+    getMetrics() {
+        return [...this.metrics];
+    }
+    /**
+     * Get aggregated metrics summary.
+     */
+    getAggregatedMetrics() {
+        const sends = this.metrics.filter((m) => m.event === 'send');
+        const receives = this.metrics.filter((m) => m.event === 'receive');
+        const encrypts = this.metrics.filter((m) => m.event === 'encrypt');
+        const decrypts = this.metrics.filter((m) => m.event === 'decrypt');
+        const errors = this.metrics.filter((m) => !m.success);
+        const avgDuration = (items) => {
+            if (items.length === 0)
+                return 0;
+            return items.reduce((sum, m) => sum + m.duration, 0) / items.length;
+        };
+        const total = this.metrics.length;
+        return {
+            totalSends: sends.length,
+            totalReceives: receives.length,
+            totalEncrypts: encrypts.length,
+            totalDecrypts: decrypts.length,
+            avgSendDuration: avgDuration(sends),
+            avgReceiveDuration: avgDuration(receives),
+            avgEncryptDuration: avgDuration(encrypts),
+            avgDecryptDuration: avgDuration(decrypts),
+            totalErrors: errors.length,
+            errorRate: total > 0 ? errors.length / total : 0,
+            uptime: Date.now() - this.startTime,
+        };
+    }
+    /**
+     * Clear all metrics.
+     */
+    clearMetrics() {
+        this.metrics = [];
+        this.startTime = Date.now();
+    }
+    /**
+     * Export metrics using the configured callback.
+     */
+    export() {
+        if (this.metrics.length > 0) {
+            this.options.onExport([...this.metrics]);
+        }
+    }
+    /**
+     * Get metrics for a specific time range.
+     */
+    getMetricsInRange(startTime, endTime) {
+        return this.metrics.filter((m) => m.timestamp >= startTime && m.timestamp <= endTime);
+    }
+    /**
+     * Get metrics for a specific event type.
+     */
+    getMetricsByEvent(event) {
+        return this.metrics.filter((m) => m.event === event);
+    }
+    record(entry) {
+        this.metrics.push(entry);
+        // Enforce max metrics limit
+        if (this.metrics.length > this.options.maxMetrics) {
+            this.metrics.shift(); // Remove oldest
+        }
+    }
+    now() {
+        if (this.options.highResolution && typeof performance !== 'undefined') {
+            return performance.now();
+        }
+        return Date.now();
+    }
+}
+/**
+ * Create a metrics plugin with options.
+ */
+export function createMetricsPlugin(options) {
+    return new MetricsPlugin(options);
+}

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

@@ -0,0 +1,104 @@
+/**
+ * @module plugins/validation
+ * Validation plugin for xBind plugin system
+ *
+ * Validates payloads, envelopes, and ensures data integrity before processing.
+ */
+import type { Result } from '@private.me/shared';
+import type { Plugin, PluginContext, HookResult } from '../plugin-system.js';
+import type { AnyTransportEnvelope } from '../envelope.js';
+/**
+ * Validation rule.
+ */
+export interface ValidationRule {
+    /** Rule name */
+    name: string;
+    /** Validate function - returns error message on failure, null on success */
+    validate: (value: unknown, context: PluginContext) => string | null;
+    /** Apply to send operations */
+    appliesTo?: ('send' | 'receive' | 'encrypt' | 'decrypt')[];
+}
+/**
+ * Validation plugin options.
+ */
+export interface ValidationPluginOptions {
+    /** Maximum payload size in bytes (default: 10MB) */
+    maxPayloadSize?: number;
+    /** Maximum envelope size in bytes (default: 15MB) */
+    maxEnvelopeSize?: number;
+    /** Allowed scopes (empty = all allowed) */
+    allowedScopes?: string[];
+    /** Custom validation rules */
+    customRules?: ValidationRule[];
+    /** Strict mode - reject any validation warning (default: false) */
+    strictMode?: boolean;
+    /** Enable payload schema validation (default: false) */
+    validateSchema?: boolean;
+}
+/**
+ * Validation plugin implementation.
+ * Validates all data before processing to ensure integrity and compliance.
+ */
+export declare class ValidationPlugin implements Plugin {
+    readonly name = "validation";
+    readonly version = "1.0.0";
+    readonly description = "Validates payloads and envelopes before processing";
+    readonly priority = 5;
+    private options;
+    private validationErrors;
+    constructor(options?: ValidationPluginOptions);
+    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 validation errors.
+     */
+    getValidationErrors(): ReadonlyArray<{
+        timestamp: number;
+        rule: string;
+        error: string;
+    }>;
+    /**
+     * Clear validation errors.
+     */
+    clearErrors(): void;
+    /**
+     * Add a custom validation rule.
+     */
+    addRule(rule: ValidationRule): void;
+    /**
+     * Remove a custom validation rule by name.
+     */
+    removeRule(name: string): boolean;
+    private validatePayloadSize;
+    private validateEnvelopeSize;
+    private validateScope;
+    private validatePayloadStructure;
+    private validateEnvelopeStructure;
+    private estimateSize;
+    private recordError;
+}
+/**
+ * Create a validation plugin with options.
+ */
+export declare function createValidationPlugin(options?: ValidationPluginOptions): ValidationPlugin;
+/**
+ * Common validation rules.
+ */
+export declare const CommonRules: {
+    /**
+     * Validate payload contains required fields.
+     */
+    requireFields(fields: string[]): ValidationRule;
+    /**
+     * Validate DID format.
+     */
+    validateDIDFormat(): ValidationRule;
+    /**
+     * Validate timestamp is recent.
+     */
+    validateTimestamp(maxAgeMs?: number): ValidationRule;
+};

package/dist-standalone/plugins/validation.js

@@ -0,0 +1,297 @@
+/**
+ * @module plugins/validation
+ * Validation plugin for xBind plugin system
+ *
+ * Validates payloads, envelopes, and ensures data integrity before processing.
+ */
+import { ok, err } from"../_deps/shared/index.js";
+/**
+ * Validation plugin implementation.
+ * Validates all data before processing to ensure integrity and compliance.
+ */
+export class ValidationPlugin {
+    name = 'validation';
+    version = '1.0.0';
+    description = 'Validates payloads and envelopes before processing';
+    priority = 5; // Execute very early
+    options;
+    validationErrors = [];
+    constructor(options = {}) {
+        this.options = {
+            maxPayloadSize: options.maxPayloadSize ?? 10 * 1024 * 1024, // 10MB
+            maxEnvelopeSize: options.maxEnvelopeSize ?? 15 * 1024 * 1024, // 15MB
+            allowedScopes: options.allowedScopes ?? [],
+            customRules: options.customRules ?? [],
+            strictMode: options.strictMode ?? false,
+            validateSchema: options.validateSchema ?? false,
+        };
+    }
+    onInit() {
+        return ok(undefined);
+    }
+    onDestroy() {
+        this.validationErrors = [];
+        return ok(undefined);
+    }
+    onSend(payload, context) {
+        // Validate payload size
+        const sizeResult = this.validatePayloadSize(payload);
+        if (sizeResult.ok === false) {
+            this.recordError('payload_size', sizeResult.error);
+            return err(sizeResult.error);
+        }
+        // Validate scope
+        if (context.scope) {
+            const scopeResult = this.validateScope(context.scope);
+            if (scopeResult.ok === false) {
+                this.recordError('scope', scopeResult.error);
+                return err(scopeResult.error);
+            }
+        }
+        // Validate payload structure
+        const structureResult = this.validatePayloadStructure(payload);
+        if (structureResult.ok === false) {
+            this.recordError('payload_structure', structureResult.error);
+            return err(structureResult.error);
+        }
+        // Apply custom rules
+        for (const rule of this.options.customRules) {
+            if (!rule.appliesTo || rule.appliesTo.includes('send')) {
+                const error = rule.validate(payload, context);
+                if (error) {
+                    this.recordError(rule.name, error);
+                    return err(`VALIDATION_FAILED:${rule.name}:${error}`);
+                }
+            }
+        }
+        return ok({ payload });
+    }
+    onReceive(envelope, context) {
+        // Validate envelope size
+        const sizeResult = this.validateEnvelopeSize(envelope);
+        if (sizeResult.ok === false) {
+            this.recordError('envelope_size', sizeResult.error);
+            return err(sizeResult.error);
+        }
+        // Validate envelope structure
+        const structureResult = this.validateEnvelopeStructure(envelope);
+        if (structureResult.ok === false) {
+            this.recordError('envelope_structure', structureResult.error);
+            return err(structureResult.error);
+        }
+        // Apply custom rules
+        for (const rule of this.options.customRules) {
+            if (!rule.appliesTo || rule.appliesTo.includes('receive')) {
+                const error = rule.validate(envelope, context);
+                if (error) {
+                    this.recordError(rule.name, error);
+                    return err(`VALIDATION_FAILED:${rule.name}:${error}`);
+                }
+            }
+        }
+        return ok({ payload: envelope });
+    }
+    onEncrypt(plaintext, context) {
+        // Validate plaintext is not empty
+        if (plaintext.length === 0) {
+            this.recordError('plaintext_empty', 'Plaintext cannot be empty');
+            return err('VALIDATION_FAILED:PLAINTEXT_EMPTY');
+        }
+        // Validate plaintext size
+        if (plaintext.length > this.options.maxPayloadSize) {
+            this.recordError('plaintext_size', `Plaintext exceeds max size: ${plaintext.length} bytes`);
+            return err(`VALIDATION_FAILED:PLAINTEXT_TOO_LARGE:${plaintext.length}`);
+        }
+        // Apply custom rules
+        for (const rule of this.options.customRules) {
+            if (!rule.appliesTo || rule.appliesTo.includes('encrypt')) {
+                const error = rule.validate(plaintext, context);
+                if (error) {
+                    this.recordError(rule.name, error);
+                    return err(`VALIDATION_FAILED:${rule.name}:${error}`);
+                }
+            }
+        }
+        return ok({ payload: plaintext });
+    }
+    onDecrypt(plaintext, context) {
+        // Validate plaintext is not empty
+        if (plaintext.length === 0) {
+            this.recordError('plaintext_empty', 'Decrypted plaintext is empty');
+            return err('VALIDATION_FAILED:DECRYPTED_EMPTY');
+        }
+        // Apply custom rules
+        for (const rule of this.options.customRules) {
+            if (!rule.appliesTo || rule.appliesTo.includes('decrypt')) {
+                const error = rule.validate(plaintext, context);
+                if (error) {
+                    this.recordError(rule.name, error);
+                    return err(`VALIDATION_FAILED:${rule.name}:${error}`);
+                }
+            }
+        }
+        return ok({ payload: plaintext });
+    }
+    /**
+     * Get all validation errors.
+     */
+    getValidationErrors() {
+        return [...this.validationErrors];
+    }
+    /**
+     * Clear validation errors.
+     */
+    clearErrors() {
+        this.validationErrors = [];
+    }
+    /**
+     * Add a custom validation rule.
+     */
+    addRule(rule) {
+        this.options.customRules.push(rule);
+    }
+    /**
+     * Remove a custom validation rule by name.
+     */
+    removeRule(name) {
+        const index = this.options.customRules.findIndex((r) => r.name === name);
+        if (index === -1) {
+            return false;
+        }
+        this.options.customRules.splice(index, 1);
+        return true;
+    }
+    validatePayloadSize(payload) {
+        const size = this.estimateSize(payload);
+        if (size > this.options.maxPayloadSize) {
+            return err(`VALIDATION_FAILED:PAYLOAD_TOO_LARGE:${size}>${this.options.maxPayloadSize}`);
+        }
+        return ok(undefined);
+    }
+    validateEnvelopeSize(envelope) {
+        const size = this.estimateSize(envelope);
+        if (size > this.options.maxEnvelopeSize) {
+            return err(`VALIDATION_FAILED:ENVELOPE_TOO_LARGE:${size}>${this.options.maxEnvelopeSize}`);
+        }
+        return ok(undefined);
+    }
+    validateScope(scope) {
+        if (this.options.allowedScopes.length > 0 && !this.options.allowedScopes.includes(scope)) {
+            return err(`VALIDATION_FAILED:SCOPE_NOT_ALLOWED:${scope}`);
+        }
+        return ok(undefined);
+    }
+    validatePayloadStructure(payload) {
+        if (payload === null || payload === undefined) {
+            return err('VALIDATION_FAILED:PAYLOAD_NULL_OR_UNDEFINED');
+        }
+        // Validate can be serialized to JSON
+        try {
+            JSON.stringify(payload);
+        }
+        catch (error) {
+            return err(`VALIDATION_FAILED:PAYLOAD_NOT_SERIALIZABLE:${String(error)}`);
+        }
+        return ok(undefined);
+    }
+    validateEnvelopeStructure(envelope) {
+        // Validate required fields
+        if (!('v' in envelope) && !('version' in envelope)) {
+            return err('VALIDATION_FAILED:ENVELOPE_MISSING_VERSION');
+        }
+        if (!envelope.sender) {
+            return err('VALIDATION_FAILED:ENVELOPE_MISSING_SENDER');
+        }
+        if (!envelope.recipient) {
+            return err('VALIDATION_FAILED:ENVELOPE_MISSING_RECIPIENT');
+        }
+        if (!('payload' in envelope) && !('ciphertext' in envelope)) {
+            return err('VALIDATION_FAILED:ENVELOPE_MISSING_CIPHERTEXT');
+        }
+        return ok(undefined);
+    }
+    estimateSize(value) {
+        if (value instanceof Uint8Array) {
+            return value.length;
+        }
+        try {
+            return JSON.stringify(value).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    recordError(rule, error) {
+        this.validationErrors.push({
+            timestamp: Date.now(),
+            rule,
+            error,
+        });
+        // Keep only last 1000 errors
+        if (this.validationErrors.length > 1000) {
+            this.validationErrors.shift();
+        }
+    }
+}
+/**
+ * Create a validation plugin with options.
+ */
+export function createValidationPlugin(options) {
+    return new ValidationPlugin(options);
+}
+/**
+ * Common validation rules.
+ */
+export const CommonRules = {
+    /**
+     * Validate payload contains required fields.
+     */
+    requireFields(fields) {
+        return {
+            name: 'require_fields',
+            appliesTo: ['send'],
+            validate: (value) => {
+                if (typeof value !== 'object' || value === null) {
+                    return 'Payload must be an object';
+                }
+                const obj = value;
+                const missing = fields.filter((field) => !(field in obj));
+                if (missing.length > 0) {
+                    return `Missing required fields: ${missing.join(', ')}`;
+                }
+                return null;
+            },
+        };
+    },
+    /**
+     * Validate DID format.
+     */
+    validateDIDFormat() {
+        return {
+            name: 'did_format',
+            appliesTo: ['send', 'receive'],
+            validate: (value, context) => {
+                if (context.recipient && !context.recipient.startsWith('did:')) {
+                    return `Invalid DID format: ${context.recipient}`;
+                }
+                return null;
+            },
+        };
+    },
+    /**
+     * Validate timestamp is recent.
+     */
+    validateTimestamp(maxAgeMs = 300000) {
+        return {
+            name: 'timestamp_freshness',
+            appliesTo: ['receive'],
+            validate: (value, context) => {
+                const age = Date.now() - context.timestamp;
+                if (age > maxAgeMs) {
+                    return `Timestamp too old: ${age}ms > ${maxAgeMs}ms`;
+                }
+                return null;
+            },
+        };
+    },
+};