@private.me/xbind 3.0.0 → 3.0.1

package/README.md

@@ -1,7 +1,7 @@
 # @private.me/xbind
 
 ![npm version](https://img.shields.io/npm/v/@private.me/xbind)
-![version](https://img.shields.io/badge/version-3.0.0-blue)
+![version](https://img.shields.io/badge/version-3.0.1-blue)
 ![tests](https://img.shields.io/badge/tests-2762%20passing-brightgreen)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)
 ![license](https://img.shields.io/badge/license-Proprietary-blue)
@@ -12,7 +12,14 @@ Build AI agents that communicate securely using ML-DSA-65 DID identity, ML-KEM-7
 
 Part of the **Private.Me** platform—where APIs have keys, but ACIs have identity.
 
-**Version 3.0.0** — **Major Features:** Full Control IP Protection (PLAN-13) - Vault Store architecture with payment-gated algorithm delivery. Store Front (npm) contains Share 1 only, Vault Store (EC2) contains Share 2 (payment-gated). Runtime crypto loading, 4-layer security (DID auth + usage quotas + rate limiting + audit logging). Usage-based model: Free tier 100K ops/month (includes vault access), Pro tier unlimited. Previous v1.4.2: Runtime compatibility, API enhancements. Previous v1.3.5: ML-KEM deterministic key generation fix.
+**Version 3.0.1** — **Major Features:** Full Control IP Protection (PLAN-13) - Vault Store architecture with payment-gated algorithm delivery. Store Front (npm) contains Share 1 only, Vault Store (EC2) contains Share 2 (payment-gated). Runtime crypto loading, 4-layer security (DID auth + usage quotas + rate limiting + audit logging). Usage-based model: Free tier 100K ops/month (includes vault access), Pro tier unlimited. Previous v1.4.2: Runtime compatibility, API enhancements. Previous v1.3.5: ML-KEM deterministic key generation fix.
+
+## Pricing
+
+**Free tier:** 100,000 operations/month (includes Vault Store access)
+**Pro tier:** Unlimited operations
+
+See [pricing](https://private.me/pricing) for current rates and purchase flow.
 
 ## Install
 

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 @@
+import{ok}from"../_deps/shared/index.js";export var LogLevel;!function(e){e.DEBUG="debug",e.INFO="info",e.WARN="warn",e.ERROR="error"}(LogLevel||(LogLevel={}));export class LoggingPlugin{name="logging";version="1.0.0";description="Captures message processing events for debugging and audit trails";priority=10;options;logs=[];constructor(e={}){this.options={level:e.level??LogLevel.INFO,includeSize:e.includeSize??!0,includeMetadata:e.includeMetadata??!1,logHandler:e.logHandler??(e=>console.log(JSON.stringify(e))),filter:e.filter??(()=>!0)}}onInit(){return this.log({timestamp:(new Date).toISOString(),level:LogLevel.INFO,event:"send",agent:"system",metadata:{message:"Logging plugin initialized"}}),ok(void 0)}onDestroy(){return this.log({timestamp:(new Date).toISOString(),level:LogLevel.INFO,event:"send",agent:"system",metadata:{message:"Logging plugin destroyed",totalLogs:this.logs.length}}),this.logs=[],ok(void 0)}onSend(e,t){const i=this.options.includeSize?this.estimateSize(e):void 0;return this.log({timestamp:(new Date).toISOString(),level:LogLevel.INFO,event:"send",agent:t.agent.did,recipient:t.recipient,scope:t.scope,payloadSize:i,metadata:this.options.includeMetadata?t.metadata:void 0}),ok({payload:e})}onReceive(e,t){const i=this.options.includeSize?this.estimateSize(e):void 0;return this.log({timestamp:(new Date).toISOString(),level:LogLevel.INFO,event:"receive",agent:t.agent.did,recipient:e.sender,scope:t.scope,payloadSize:i,metadata:this.options.includeMetadata?t.metadata:void 0}),ok({payload:e})}onEncrypt(e,t){return this.log({timestamp:(new Date).toISOString(),level:LogLevel.DEBUG,event:"encrypt",agent:t.agent.did,recipient:t.recipient,scope:t.scope,payloadSize:this.options.includeSize?e.length:void 0,metadata:this.options.includeMetadata?t.metadata:void 0}),ok({payload:e})}onDecrypt(e,t){return this.log({timestamp:(new Date).toISOString(),level:LogLevel.DEBUG,event:"decrypt",agent:t.agent.did,scope:t.scope,payloadSize:this.options.includeSize?e.length:void 0,metadata:this.options.includeMetadata?t.metadata:void 0}),ok({payload:e})}getLogs(){return[...this.logs]}clearLogs(){this.logs=[]}getFilteredLogs(e){return this.logs.filter(e)}log(e){this.shouldLog(e.level)&&this.options.filter(e)&&(this.logs.push(e),this.options.logHandler(e))}shouldLog(e){const t=[LogLevel.DEBUG,LogLevel.INFO,LogLevel.WARN,LogLevel.ERROR],i=t.indexOf(this.options.level);return t.indexOf(e)>=i}estimateSize(e){if(e instanceof Uint8Array)return e.length;try{return JSON.stringify(e).length}catch{return 0}}}export function createLoggingPlugin(e){return new LoggingPlugin(e)}

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;

package/dist-standalone/plugins/metrics.js

@@ -0,0 +1 @@
+import{ok}from"../_deps/shared/index.js";export class MetricsPlugin{name="metrics";version="1.0.0";description="Tracks performance metrics, message counts, and error rates";priority=20;options;metrics=[];startTime=Date.now();exportTimer;constructor(t={}){this.options={highResolution:t.highResolution??!0,maxMetrics:t.maxMetrics??1e4,onExport:t.onExport??(()=>{}),exportInterval:t.exportInterval??6e4}}onInit(){return this.startTime=Date.now(),this.options.exportInterval>0&&(this.exportTimer=setInterval(()=>{this.export()},this.options.exportInterval)),ok(void 0)}onDestroy(){return this.exportTimer&&(clearInterval(this.exportTimer),this.exportTimer=void 0),this.export(),this.metrics=[],ok(void 0)}onSend(t,e){const r=this.now(),i=this.now();return this.record({timestamp:Date.now(),event:"send",duration:i-r,success:!0}),ok({payload:t})}onReceive(t,e){const r=this.now(),i=this.now();return this.record({timestamp:Date.now(),event:"receive",duration:i-r,success:!0}),ok({payload:t})}onEncrypt(t,e){const r=this.now(),i=this.now();return this.record({timestamp:Date.now(),event:"encrypt",duration:i-r,success:!0}),ok({payload:t})}onDecrypt(t,e){const r=this.now(),i=this.now();return this.record({timestamp:Date.now(),event:"decrypt",duration:i-r,success:!0}),ok({payload:t})}getMetrics(){return[...this.metrics]}getAggregatedMetrics(){const t=this.metrics.filter(t=>"send"===t.event),e=this.metrics.filter(t=>"receive"===t.event),r=this.metrics.filter(t=>"encrypt"===t.event),i=this.metrics.filter(t=>"decrypt"===t.event),s=this.metrics.filter(t=>!t.success),n=t=>0===t.length?0:t.reduce((t,e)=>t+e.duration,0)/t.length,o=this.metrics.length;return{totalSends:t.length,totalReceives:e.length,totalEncrypts:r.length,totalDecrypts:i.length,avgSendDuration:n(t),avgReceiveDuration:n(e),avgEncryptDuration:n(r),avgDecryptDuration:n(i),totalErrors:s.length,errorRate:o>0?s.length/o:0,uptime:Date.now()-this.startTime}}clearMetrics(){this.metrics=[],this.startTime=Date.now()}export(){this.metrics.length>0&&this.options.onExport([...this.metrics])}getMetricsInRange(t,e){return this.metrics.filter(r=>r.timestamp>=t&&r.timestamp<=e)}getMetricsByEvent(t){return this.metrics.filter(e=>e.event===t)}record(t){this.metrics.push(t),this.metrics.length>this.options.maxMetrics&&this.metrics.shift()}now(){return this.options.highResolution&&"undefined"!=typeof performance?performance.now():Date.now()}}export function createMetricsPlugin(t){return new MetricsPlugin(t)}

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 @@
+import{ok,err}from"../_deps/shared/index.js";export class ValidationPlugin{name="validation";version="1.0.0";description="Validates payloads and envelopes before processing";priority=5;options;validationErrors=[];constructor(e={}){this.options={maxPayloadSize:e.maxPayloadSize??10485760,maxEnvelopeSize:e.maxEnvelopeSize??15728640,allowedScopes:e.allowedScopes??[],customRules:e.customRules??[],strictMode:e.strictMode??!1,validateSchema:e.validateSchema??!1}}onInit(){return ok(void 0)}onDestroy(){return this.validationErrors=[],ok(void 0)}onSend(e,r){const t=this.validatePayloadSize(e);if(!1===t.ok)return this.recordError("payload_size",t.error),err(t.error);if(r.scope){const e=this.validateScope(r.scope);if(!1===e.ok)return this.recordError("scope",e.error),err(e.error)}const o=this.validatePayloadStructure(e);if(!1===o.ok)return this.recordError("payload_structure",o.error),err(o.error);for(const t of this.options.customRules)if(!t.appliesTo||t.appliesTo.includes("send")){const o=t.validate(e,r);if(o)return this.recordError(t.name,o),err(`VALIDATION_FAILED:${t.name}:${o}`)}return ok({payload:e})}onReceive(e,r){const t=this.validateEnvelopeSize(e);if(!1===t.ok)return this.recordError("envelope_size",t.error),err(t.error);const o=this.validateEnvelopeStructure(e);if(!1===o.ok)return this.recordError("envelope_structure",o.error),err(o.error);for(const t of this.options.customRules)if(!t.appliesTo||t.appliesTo.includes("receive")){const o=t.validate(e,r);if(o)return this.recordError(t.name,o),err(`VALIDATION_FAILED:${t.name}:${o}`)}return ok({payload:e})}onEncrypt(e,r){if(0===e.length)return this.recordError("plaintext_empty","Plaintext cannot be empty"),err("VALIDATION_FAILED:PLAINTEXT_EMPTY");if(e.length>this.options.maxPayloadSize)return this.recordError("plaintext_size",`Plaintext exceeds max size: ${e.length} bytes`),err(`VALIDATION_FAILED:PLAINTEXT_TOO_LARGE:${e.length}`);for(const t of this.options.customRules)if(!t.appliesTo||t.appliesTo.includes("encrypt")){const o=t.validate(e,r);if(o)return this.recordError(t.name,o),err(`VALIDATION_FAILED:${t.name}:${o}`)}return ok({payload:e})}onDecrypt(e,r){if(0===e.length)return this.recordError("plaintext_empty","Decrypted plaintext is empty"),err("VALIDATION_FAILED:DECRYPTED_EMPTY");for(const t of this.options.customRules)if(!t.appliesTo||t.appliesTo.includes("decrypt")){const o=t.validate(e,r);if(o)return this.recordError(t.name,o),err(`VALIDATION_FAILED:${t.name}:${o}`)}return ok({payload:e})}getValidationErrors(){return[...this.validationErrors]}clearErrors(){this.validationErrors=[]}addRule(e){this.options.customRules.push(e)}removeRule(e){const r=this.options.customRules.findIndex(r=>r.name===e);return-1!==r&&(this.options.customRules.splice(r,1),!0)}validatePayloadSize(e){const r=this.estimateSize(e);return r>this.options.maxPayloadSize?err(`VALIDATION_FAILED:PAYLOAD_TOO_LARGE:${r}>${this.options.maxPayloadSize}`):ok(void 0)}validateEnvelopeSize(e){const r=this.estimateSize(e);return r>this.options.maxEnvelopeSize?err(`VALIDATION_FAILED:ENVELOPE_TOO_LARGE:${r}>${this.options.maxEnvelopeSize}`):ok(void 0)}validateScope(e){return this.options.allowedScopes.length>0&&!this.options.allowedScopes.includes(e)?err(`VALIDATION_FAILED:SCOPE_NOT_ALLOWED:${e}`):ok(void 0)}validatePayloadStructure(e){if(null==e)return err("VALIDATION_FAILED:PAYLOAD_NULL_OR_UNDEFINED");try{JSON.stringify(e)}catch(e){return err(`VALIDATION_FAILED:PAYLOAD_NOT_SERIALIZABLE:${String(e)}`)}return ok(void 0)}validateEnvelopeStructure(e){return"v"in e||"version"in e?e.sender?e.recipient?"payload"in e||"ciphertext"in e?ok(void 0):err("VALIDATION_FAILED:ENVELOPE_MISSING_CIPHERTEXT"):err("VALIDATION_FAILED:ENVELOPE_MISSING_RECIPIENT"):err("VALIDATION_FAILED:ENVELOPE_MISSING_SENDER"):err("VALIDATION_FAILED:ENVELOPE_MISSING_VERSION")}estimateSize(e){if(e instanceof Uint8Array)return e.length;try{return JSON.stringify(e).length}catch{return 0}}recordError(e,r){this.validationErrors.push({timestamp:Date.now(),rule:e,error:r}),this.validationErrors.length>1e3&&this.validationErrors.shift()}}export function createValidationPlugin(e){return new ValidationPlugin(e)}export const CommonRules={requireFields:e=>({name:"require_fields",appliesTo:["send"],validate:r=>{if("object"!=typeof r||null===r)return"Payload must be an object";const t=r,o=e.filter(e=>!(e in t));return o.length>0?`Missing required fields: ${o.join(", ")}`:null}}),validateDIDFormat:()=>({name:"did_format",appliesTo:["send","receive"],validate:(e,r)=>r.recipient&&!r.recipient.startsWith("did:")?`Invalid DID format: ${r.recipient}`:null}),validateTimestamp:(e=3e5)=>({name:"timestamp_freshness",appliesTo:["receive"],validate:(r,t)=>{const o=Date.now()-t.timestamp;return o>e?`Timestamp too old: ${o}ms > ${e}ms`:null}})};

package/dist-standalone/runtime/browser.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Browser Runtime Compatibility Layer
+ *
+ * Provides polyfills and runtime detection for browser environments.
+ * Ensures xBind works seamlessly in Chrome, Firefox, Safari, and service workers.
+ *
+ * @module runtime/browser
+ * @packageDocumentation
+ */
+import type { Result } from '@private.me/shared';
+/**
+ * Runtime environment type.
+ */
+export type RuntimeEnvironment = 'browser' | 'node' | 'service-worker' | 'web-worker' | 'unknown';
+/**
+ * Detect the current runtime environment.
+ *
+ * @returns The detected runtime environment type
+ *
+ * @example
+ * ```typescript
+ * import { detectRuntime } from '@private.me/xbind/runtime/browser';
+ *
+ * const runtime = detectRuntime();
+ * console.log('Running in:', runtime);
+ * // => 'browser' | 'node' | 'service-worker' | 'web-worker' | 'unknown'
+ * ```
+ */
+export declare function detectRuntime(): RuntimeEnvironment;
+/**
+ * Check if running in a browser environment.
+ *
+ * @returns True if running in browser, service worker, or web worker
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Check if running in Node.js environment.
+ *
+ * @returns True if running in Node.js
+ */
+export declare function isNode(): boolean;
+/**
+ * Check if running in a service worker.
+ *
+ * @returns True if running in service worker context
+ */
+export declare function isServiceWorker(): boolean;
+/**
+ * Browser-compatible random bytes generator.
+ * Uses Web Crypto API's getRandomValues.
+ *
+ * @param length - Number of random bytes to generate
+ * @returns Uint8Array of cryptographically secure random bytes
+ *
+ * @throws {Error} If Web Crypto API is not available
+ *
+ * @example
+ * ```typescript
+ * import { getRandomBytes } from '@private.me/xbind/runtime/browser';
+ *
+ * const nonce = getRandomBytes(16);
+ * console.log('Random nonce:', nonce);
+ * ```
+ */
+export declare function getRandomBytes(length: number): Uint8Array;
+/**
+ * Generate a cryptographically secure random UUID.
+ * Uses Web Crypto API's randomUUID if available, falls back to manual generation.
+ *
+ * @returns UUID v4 string (e.g., "550e8400-e29b-41d4-a716-446655440000")
+ *
+ * @example
+ * ```typescript
+ * import { generateUUID } from '@private.me/xbind/runtime/browser';
+ *
+ * const id = generateUUID();
+ * console.log('Generated UUID:', id);
+ * ```
+ */
+export declare function generateUUID(): string;
+/**
+ * Browser storage interface for persisting agent identity and state.
+ */
+export interface BrowserStorage {
+    /**
+     * Store a value.
+     * @param key - Storage key
+     * @param value - Value to store (will be JSON serialized)
+     */
+    setItem(key: string, value: unknown): Promise<void>;
+    /**
+     * Retrieve a value.
+     * @param key - Storage key
+     * @returns Stored value or null if not found
+     */
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Remove a value.
+     * @param key - Storage key
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * LocalStorage-based implementation of BrowserStorage.
+ * Suitable for browser environments with persistent storage needs.
+ */
+export declare class LocalStorageAdapter implements BrowserStorage {
+    private prefix;
+    /**
+     * Create a new LocalStorage adapter.
+     *
+     * @param prefix - Key prefix to avoid collisions (default: 'xbind:')
+     */
+    constructor(prefix?: string);
+    setItem(key: string, value: unknown): Promise<void>;
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * IndexedDB-based implementation of BrowserStorage.
+ * Suitable for larger datasets and service workers.
+ */
+export declare class IndexedDBAdapter implements BrowserStorage {
+    private dbName;
+    private storeName;
+    private version;
+    private db;
+    /**
+     * Create a new IndexedDB adapter.
+     *
+     * @param dbName - Database name (default: 'xbind-storage')
+     * @param storeName - Object store name (default: 'keyval')
+     * @param version - Database version (default: 1)
+     */
+    constructor(dbName?: string, storeName?: string, version?: number);
+    /**
+     * Initialize the database connection.
+     * Called automatically by storage operations.
+     */
+    private ensureDB;
+    setItem(key: string, value: unknown): Promise<void>;
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Close the database connection.
+     * Should be called when storage is no longer needed.
+     */
+    close(): void;
+}
+/**
+ * In-memory storage implementation for testing and ephemeral use cases.
+ */
+export declare class MemoryStorageAdapter implements BrowserStorage {
+    private store;
+    setItem(key: string, value: unknown): Promise<void>;
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Error codes for WASM operations.
+ */
+export type WasmError = 'WASM_NOT_SUPPORTED' | 'WASM_LOAD_FAILED' | 'WASM_INIT_FAILED';
+/**
+ * Check if WebAssembly is supported in the current environment.
+ *
+ * @returns True if WebAssembly is supported
+ *
+ * @example
+ * ```typescript
+ * import { isWasmSupported } from '@private.me/xbind/runtime/browser';
+ *
+ * if (isWasmSupported()) {
+ *   console.log('WASM is supported - using post-quantum crypto');
+ * } else {
+ *   console.log('WASM not supported - falling back to classical crypto');
+ * }
+ * ```
+ */
+export declare function isWasmSupported(): boolean;
+/**
+ * Load and instantiate a WebAssembly module from a URL.
+ *
+ * @param url - URL to WASM module
+ * @param importObject - Optional imports for WASM module
+ * @returns Result containing the WASM instance or error
+ *
+ * @example
+ * ```typescript
+ * import { loadWasmModule } from '@private.me/xbind/runtime/browser';
+ *
+ * const result = await loadWasmModule('/mldsa.wasm');
+ * if (!result.ok) {
+ *   console.error('Failed to load WASM:', result.error);
+ *   return;
+ * }
+ *
+ * const instance = result.value;
+ * // Use WASM exports...
+ * ```
+ */
+export declare function loadWasmModule(url: string, importObject?: WebAssembly.Imports): Promise<Result<WebAssembly.Instance, WasmError>>;
+/**
+ * Browser capabilities and feature support.
+ */
+export interface BrowserCapabilities {
+    /** WebCrypto API available */
+    webCrypto: boolean;
+    /** SubtleCrypto API available */
+    subtleCrypto: boolean;
+    /** Ed25519 support in WebCrypto */
+    ed25519: boolean;
+    /** X25519 support in WebCrypto */
+    x25519: boolean;
+    /** WebAssembly support */
+    wasm: boolean;
+    /** IndexedDB support */
+    indexedDB: boolean;
+    /** LocalStorage support */
+    localStorage: boolean;
+    /** Service Worker support */
+    serviceWorker: boolean;
+    /** Web Worker support */
+    webWorker: boolean;
+    /** Fetch API support */
+    fetch: boolean;
+    /** TextEncoder/TextDecoder support */
+    textEncoding: boolean;
+}
+/**
+ * Detect browser capabilities and feature support.
+ *
+ * @returns Object describing available browser features
+ *
+ * @example
+ * ```typescript
+ * import { detectCapabilities } from '@private.me/xbind/runtime/browser';
+ *
+ * const caps = await detectCapabilities();
+ *
+ * if (!caps.webCrypto) {
+ *   throw new Error('WebCrypto required for xBind');
+ * }
+ *
+ * if (!caps.ed25519) {
+ *   console.warn('Ed25519 not supported - using polyfill');
+ * }
+ *
+ * if (caps.serviceWorker) {
+ *   console.log('Service workers supported - can run in background');
+ * }
+ * ```
+ */
+export declare function detectCapabilities(): Promise<BrowserCapabilities>;
+/**
+ * Install Node.js compatibility shims for browser environments.
+ * Only installs missing APIs - does not override existing implementations.
+ *
+ * @example
+ * ```typescript
+ * import { installNodePolyfills } from '@private.me/xbind/runtime/browser';
+ *
+ * // Install polyfills at application startup
+ * installNodePolyfills();
+ *
+ * // Now Node.js-style code works in browser
+ * import { randomBytes } from 'crypto'; // Works!
+ * ```
+ */
+export declare function installNodePolyfills(): void;
+/**
+ * Configuration for service worker compatibility mode.
+ */
+export interface ServiceWorkerConfig {
+    /** Cache strategy for WASM modules */
+    wasmCacheStrategy: 'cache-first' | 'network-first' | 'no-cache';
+    /** Maximum age for cached WASM modules (milliseconds) */
+    wasmCacheMaxAge: number;
+    /** Enable background sync for pending messages */
+    enableBackgroundSync: boolean;
+}
+/**
+ * Default service worker configuration.
+ */
+export declare const DEFAULT_SERVICE_WORKER_CONFIG: ServiceWorkerConfig;
+/**
+ * Initialize xBind for service worker environment.
+ * Sets up caching strategies and background sync handlers.
+ *
+ * @param config - Service worker configuration
+ *
+ * @example
+ * ```typescript
+ * // In your service worker (sw.js):
+ * import { initServiceWorker } from '@private.me/xbind/runtime/browser';
+ *
+ * initServiceWorker({
+ *   wasmCacheStrategy: 'cache-first',
+ *   wasmCacheMaxAge: 24 * 60 * 60 * 1000,
+ *   enableBackgroundSync: true,
+ * });
+ * ```
+ */
+export declare function initServiceWorker(config?: Partial<ServiceWorkerConfig>): void;
+export type { Result, };

package/dist-standalone/runtime/browser.js

@@ -0,0 +1 @@
+import{ok,err}from"../_deps/shared/index.js";export function detectRuntime(){return"undefined"!=typeof self&&"ServiceWorkerGlobalScope"in self?"service-worker":"undefined"!=typeof self&&"WorkerGlobalScope"in self&&"importScripts"in self?"web-worker":"undefined"!=typeof window&&"undefined"!=typeof document?"browser":"undefined"!=typeof process&&process.versions&&process.versions.node?"node":"unknown"}export function isBrowser(){const e=detectRuntime();return"browser"===e||"service-worker"===e||"web-worker"===e}export function isNode(){return"node"===detectRuntime()}export function isServiceWorker(){return"service-worker"===detectRuntime()}export function getRandomBytes(e){if("undefined"==typeof crypto||!crypto.getRandomValues)throw new Error("Web Crypto API not available - secure random generation impossible");const t=new Uint8Array(e);return crypto.getRandomValues(t),t}export function generateUUID(){if("undefined"!=typeof crypto&&crypto.randomUUID)return crypto.randomUUID();const e=getRandomBytes(16),t=e[6],r=e[8];void 0!==t&&(e[6]=15&t|64),void 0!==r&&(e[8]=63&r|128);const o=Array.from(e).map(e=>e.toString(16).padStart(2,"0")).join("");return[o.slice(0,8),o.slice(8,12),o.slice(12,16),o.slice(16,20),o.slice(20,32)].join("-")}export class LocalStorageAdapter{prefix;constructor(e="xbind:"){if(this.prefix=e,"undefined"==typeof localStorage)throw new Error("localStorage not available in this environment")}async setItem(e,t){const r=this.prefix+e,o=JSON.stringify(t);localStorage.setItem(r,o)}async getItem(e){const t=this.prefix+e,r=localStorage.getItem(t);if(null===r)return null;try{return JSON.parse(r)}catch{return null}}async removeItem(e){const t=this.prefix+e;localStorage.removeItem(t)}async clear(){Object.keys(localStorage).filter(e=>e.startsWith(this.prefix)).forEach(e=>localStorage.removeItem(e))}}export class IndexedDBAdapter{dbName;storeName;version;db=null;constructor(e="xbind-storage",t="keyval",r=1){this.dbName=e,this.storeName=t,this.version=r}async ensureDB(){return this.db?this.db:new Promise((e,t)=>{const r=indexedDB.open(this.dbName,this.version);r.onerror=()=>t(r.error),r.onsuccess=()=>{this.db=r.result,e(r.result)},r.onupgradeneeded=e=>{const t=e.target.result;t.objectStoreNames.contains(this.storeName)||t.createObjectStore(this.storeName)}})}async setItem(e,t){const r=(await this.ensureDB()).transaction(this.storeName,"readwrite").objectStore(this.storeName);return new Promise((o,n)=>{const s=r.put(t,e);s.onerror=()=>n(s.error),s.onsuccess=()=>o()})}async getItem(e){const t=(await this.ensureDB()).transaction(this.storeName,"readonly").objectStore(this.storeName);return new Promise((r,o)=>{const n=t.get(e);n.onerror=()=>o(n.error),n.onsuccess=()=>{const e=n.result;r(void 0===e?null:e)}})}async removeItem(e){const t=(await this.ensureDB()).transaction(this.storeName,"readwrite").objectStore(this.storeName);return new Promise((r,o)=>{const n=t.delete(e);n.onerror=()=>o(n.error),n.onsuccess=()=>r()})}async clear(){const e=(await this.ensureDB()).transaction(this.storeName,"readwrite").objectStore(this.storeName);return new Promise((t,r)=>{const o=e.clear();o.onerror=()=>r(o.error),o.onsuccess=()=>t()})}close(){this.db&&(this.db.close(),this.db=null)}}export class MemoryStorageAdapter{store=new Map;async setItem(e,t){this.store.set(e,t)}async getItem(e){const t=this.store.get(e);return void 0===t?null:t}async removeItem(e){this.store.delete(e)}async clear(){this.store.clear()}}export function isWasmSupported(){try{if("undefined"==typeof WebAssembly)return!1;const e=new WebAssembly.Module(new Uint8Array([0,97,115,109,1,0,0,0]));if(!(e instanceof WebAssembly.Module))return!1;return new WebAssembly.Instance(e)instanceof WebAssembly.Instance}catch{return!1}}export async function loadWasmModule(e,t){if(!isWasmSupported())return err("WASM_NOT_SUPPORTED");try{if(void 0!==WebAssembly.instantiateStreaming){const r=await fetch(e),o=await WebAssembly.instantiateStreaming(r,t);return ok(o.instance)}const r=await fetch(e),o=await r.arrayBuffer(),n=await WebAssembly.instantiate(o,t);return ok(n.instance)}catch(e){return console.error("WASM load failed:",e),err("WASM_LOAD_FAILED")}}export async function detectCapabilities(){const e={webCrypto:"undefined"!=typeof crypto&&!!crypto.subtle,subtleCrypto:"undefined"!=typeof crypto&&!!crypto.subtle,ed25519:!1,x25519:!1,wasm:isWasmSupported(),indexedDB:"undefined"!=typeof indexedDB,localStorage:"undefined"!=typeof localStorage,serviceWorker:"undefined"!=typeof navigator&&"serviceWorker"in navigator,webWorker:"undefined"!=typeof Worker,fetch:"undefined"!=typeof fetch,textEncoding:"undefined"!=typeof TextEncoder&&"undefined"!=typeof TextDecoder};if(e.subtleCrypto)try{await crypto.subtle.generateKey({name:"Ed25519"},!0,["sign","verify"]),e.ed25519=!0}catch{e.ed25519=!1}if(e.subtleCrypto)try{await crypto.subtle.generateKey({name:"X25519"},!0,["deriveBits"]),e.x25519=!0}catch{e.x25519=!1}return e}export function installNodePolyfills(){isBrowser()&&(void 0===globalThis.process&&(globalThis.process={env:{},versions:{},nextTick:e=>Promise.resolve().then(e)}),void 0===globalThis.Buffer&&(globalThis.Buffer={from:(e,t)=>{if(e instanceof Uint8Array)return e;if("base64"===t){const t=atob(e);return new Uint8Array(t.split("").map(e=>e.charCodeAt(0)))}return(new TextEncoder).encode(e)},alloc:e=>new Uint8Array(e)}),void 0===globalThis.global&&(globalThis.global=globalThis))}export const DEFAULT_SERVICE_WORKER_CONFIG={wasmCacheStrategy:"cache-first",wasmCacheMaxAge:864e5,enableBackgroundSync:!0};export function initServiceWorker(e={}){const t={...DEFAULT_SERVICE_WORKER_CONFIG,...e};if(!isServiceWorker())throw new Error("initServiceWorker() must be called from service worker context");self.__xbind_sw_config=t,console.log("[xBind] Service worker initialized with config:",t)}