@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/progress-callbacks.d.ts

@@ -0,0 +1,394 @@
+/**
+ * @module progress-callbacks
+ * Enhanced progress tracking for xBind operations
+ *
+ * Provides domain-specific progress callbacks for long-running operations:
+ * - Upload/download progress with bandwidth estimation
+ * - Share distribution progress (XorIDA multi-channel delivery)
+ * - Encryption/decryption progress
+ * - Multi-stage operation tracking
+ *
+ * @example
+ * ```typescript
+ * const tracker = new OperationProgressTracker(onProgress);
+ * tracker.startStage('encryption', 40); // 40% of total operation
+ * // ... encryption work
+ * tracker.updateStageProgress(50); // 50% of encryption stage
+ * tracker.completeStage();
+ * ```
+ */
+import type { ProgressCallback } from '@private.me/ux-helpers';
+/**
+ * Enhanced progress event with operation-specific metadata.
+ */
+export interface EnhancedProgressEvent {
+    /** Current stage/operation name */
+    readonly stage: string;
+    /** Overall progress percentage (0-100) */
+    readonly progress: number;
+    /** Stage-specific progress percentage (0-100) */
+    readonly stageProgress: number;
+    /** Human-readable status message */
+    readonly status: string;
+    /** Operation-specific metadata */
+    readonly metadata?: ProgressMetadata;
+}
+/**
+ * Progress metadata for different operation types.
+ */
+export interface ProgressMetadata {
+    /** Bytes transferred (for upload/download) */
+    readonly bytesTransferred?: number;
+    /** Total bytes (for upload/download) */
+    readonly totalBytes?: number;
+    /** Transfer rate in bytes/second */
+    readonly bytesPerSecond?: number;
+    /** Estimated time remaining in milliseconds */
+    readonly estimatedTimeRemaining?: number;
+    /** Number of shares distributed (for XorIDA operations) */
+    readonly sharesDistributed?: number;
+    /** Total shares to distribute */
+    readonly totalShares?: number;
+    /** Current encryption/decryption operation */
+    readonly cryptoOperation?: 'encrypt' | 'decrypt' | 'sign' | 'verify';
+    /** Number of items processed */
+    readonly itemsProcessed?: number;
+    /** Total items to process */
+    readonly totalItems?: number;
+}
+/**
+ * Enhanced progress callback with metadata.
+ */
+export type EnhancedProgressCallback = (event: EnhancedProgressEvent) => void;
+/**
+ * Stage definition for multi-stage operations.
+ */
+export interface OperationStage {
+    /** Stage identifier */
+    readonly name: string;
+    /** Weight of this stage (percentage of total operation, 0-100) */
+    readonly weight: number;
+    /** Human-readable description */
+    readonly description: string;
+}
+/**
+ * Options for operation progress tracking.
+ */
+export interface OperationProgressOptions {
+    /** Progress callback */
+    readonly onProgress?: ProgressCallback | EnhancedProgressCallback;
+    /** Enable bandwidth estimation for transfers */
+    readonly estimateBandwidth?: boolean;
+    /** Minimum interval between progress updates (ms) */
+    readonly throttleMs?: number;
+}
+/**
+ * Multi-stage operation progress tracker.
+ *
+ * Manages progress across multiple stages with weighted contributions
+ * to overall progress. Useful for complex operations like:
+ * - Message send: resolve DID (10%) → encrypt (30%) → split shares (20%) → distribute (40%)
+ * - File transfer: prepare (5%) → encrypt (25%) → upload (70%)
+ *
+ * @example
+ * ```typescript
+ * const tracker = new OperationProgressTracker(onProgress);
+ *
+ * tracker.startStage('preparation', 10);
+ * // ... prep work
+ * tracker.completeStage();
+ *
+ * tracker.startStage('encryption', 40);
+ * tracker.updateStageProgress(50); // Halfway through encryption
+ * tracker.completeStage();
+ *
+ * tracker.startStage('distribution', 50);
+ * // ... distribution work
+ * tracker.complete();
+ * ```
+ */
+export declare class OperationProgressTracker {
+    private readonly callback?;
+    private readonly throttleMs;
+    private lastUpdateTime;
+    private currentStage;
+    private currentStageWeight;
+    private currentStageProgress;
+    private completedWeight;
+    private metadata;
+    /**
+     * Create a new operation progress tracker.
+     *
+     * @param onProgress Progress callback (standard or enhanced)
+     * @param options Tracking options
+     */
+    constructor(onProgress?: ProgressCallback | EnhancedProgressCallback, options?: Omit<OperationProgressOptions, 'onProgress'>);
+    /**
+     * Start a new stage.
+     *
+     * @param name Stage identifier
+     * @param weight Weight of this stage (percentage of total, 0-100)
+     * @param description Human-readable description
+     */
+    startStage(name: string, weight: number, description?: string): void;
+    /**
+     * Update progress within the current stage.
+     *
+     * @param stagePercent Progress percentage within current stage (0-100)
+     * @param status Optional status message
+     * @param metadata Optional progress metadata
+     */
+    updateStageProgress(stagePercent: number, status?: string, metadata?: Partial<ProgressMetadata>): void;
+    /**
+     * Complete the current stage and advance overall progress.
+     */
+    completeStage(): void;
+    /**
+     * Mark the entire operation as complete.
+     */
+    complete(): void;
+    /**
+     * Get current overall progress percentage.
+     *
+     * @returns Progress percentage (0-100)
+     */
+    getProgress(): number;
+    /**
+     * Update metadata without changing progress.
+     *
+     * @param metadata Metadata to merge
+     */
+    updateMetadata(metadata: Partial<ProgressMetadata>): void;
+    /**
+     * Report progress to callback (with throttling).
+     *
+     * @param status Status message
+     */
+    private reportProgress;
+    /**
+     * Check if callback expects enhanced events.
+     *
+     * @param callback Callback to check
+     * @returns True if enhanced callback
+     */
+    private isEnhancedCallback;
+}
+/**
+ * Transfer progress tracker with bandwidth estimation.
+ *
+ * Tracks upload/download progress with automatic bandwidth calculation
+ * and estimated time remaining.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new TransferProgressTracker(totalBytes, onProgress);
+ *
+ * for (const chunk of chunks) {
+ *   await uploadChunk(chunk);
+ *   tracker.addTransferred(chunk.length);
+ * }
+ *
+ * tracker.complete();
+ * ```
+ */
+export declare class TransferProgressTracker {
+    private readonly totalBytes;
+    private readonly callback?;
+    private readonly reporter;
+    private readonly throttleMs;
+    private bytesTransferred;
+    private startTime;
+    private lastUpdateTime;
+    private samples;
+    private readonly maxSamples;
+    /**
+     * Create a new transfer progress tracker.
+     *
+     * @param totalBytes Total bytes to transfer
+     * @param onProgress Progress callback
+     * @param throttleMs Minimum interval between updates (default: 100ms)
+     */
+    constructor(totalBytes: number, onProgress?: ProgressCallback | EnhancedProgressCallback, throttleMs?: number);
+    /**
+     * Add transferred bytes and update progress.
+     *
+     * @param bytes Number of bytes transferred
+     */
+    addTransferred(bytes: number): void;
+    /**
+     * Mark transfer as complete.
+     */
+    complete(): void;
+    /**
+     * Get current progress percentage.
+     *
+     * @returns Progress percentage (0-100)
+     */
+    getProgress(): number;
+    /**
+     * Calculate current transfer rate.
+     *
+     * @returns Bytes per second
+     */
+    private calculateBytesPerSecond;
+    /**
+     * Estimate time remaining.
+     *
+     * @returns Estimated milliseconds remaining
+     */
+    private estimateTimeRemaining;
+    /**
+     * Report progress to callback.
+     */
+    private reportProgress;
+    /**
+     * Format status message with transfer details.
+     *
+     * @param progress Progress percentage
+     * @param bytesPerSecond Transfer rate
+     * @param estimatedTimeRemaining Time remaining in ms
+     * @returns Formatted status string
+     */
+    private formatStatus;
+    /**
+     * Format bytes for display.
+     *
+     * @param bytes Number of bytes
+     * @returns Formatted string (e.g., "1.5 MB")
+     */
+    private formatBytes;
+    /**
+     * Format time for display.
+     *
+     * @param ms Milliseconds
+     * @returns Formatted string (e.g., "2m 30s")
+     */
+    private formatTime;
+    /**
+     * Check if callback expects enhanced events.
+     *
+     * @param callback Callback to check
+     * @returns True if enhanced callback
+     */
+    private isEnhancedCallback;
+}
+/**
+ * Share distribution progress tracker for XorIDA operations.
+ *
+ * Tracks progress of distributing shares across multiple channels.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ShareDistributionTracker(3, onProgress);
+ *
+ * await distributeShare(0);
+ * tracker.markShareDistributed(0);
+ *
+ * await distributeShare(1);
+ * tracker.markShareDistributed(1);
+ *
+ * await distributeShare(2);
+ * tracker.markShareDistributed(2);
+ *
+ * tracker.complete();
+ * ```
+ */
+export declare class ShareDistributionTracker {
+    private readonly totalShares;
+    private readonly callback?;
+    private readonly reporter;
+    private distributedShares;
+    /**
+     * Create a new share distribution tracker.
+     *
+     * @param totalShares Total number of shares to distribute
+     * @param onProgress Progress callback
+     */
+    constructor(totalShares: number, onProgress?: ProgressCallback | EnhancedProgressCallback);
+    /**
+     * Mark a share as successfully distributed.
+     *
+     * @param shareIndex Zero-based share index
+     */
+    markShareDistributed(shareIndex: number): void;
+    /**
+     * Mark all shares as distributed and complete.
+     */
+    complete(): void;
+    /**
+     * Get current progress percentage.
+     *
+     * @returns Progress percentage (0-100)
+     */
+    getProgress(): number;
+    /**
+     * Report progress to callback.
+     */
+    private reportProgress;
+    /**
+     * Check if callback expects enhanced events.
+     *
+     * @param callback Callback to check
+     * @returns True if enhanced callback
+     */
+    private isEnhancedCallback;
+}
+/**
+ * Encryption progress tracker.
+ *
+ * Tracks progress of encryption/decryption operations on large data.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new EncryptionProgressTracker('encrypt', totalChunks, onProgress);
+ *
+ * for (const chunk of chunks) {
+ *   await encryptChunk(chunk);
+ *   tracker.incrementProcessed();
+ * }
+ *
+ * tracker.complete();
+ * ```
+ */
+export declare class EncryptionProgressTracker {
+    private readonly operation;
+    private readonly totalItems;
+    private readonly callback?;
+    private readonly reporter;
+    private itemsProcessed;
+    /**
+     * Create a new encryption progress tracker.
+     *
+     * @param operation Cryptographic operation type
+     * @param totalItems Total number of items to process
+     * @param onProgress Progress callback
+     */
+    constructor(operation: 'encrypt' | 'decrypt' | 'sign' | 'verify', totalItems: number, onProgress?: ProgressCallback | EnhancedProgressCallback);
+    /**
+     * Increment the number of processed items.
+     *
+     * @param count Number of items to add (default: 1)
+     */
+    incrementProcessed(count?: number): void;
+    /**
+     * Mark operation as complete.
+     */
+    complete(): void;
+    /**
+     * Get current progress percentage.
+     *
+     * @returns Progress percentage (0-100)
+     */
+    getProgress(): number;
+    /**
+     * Report progress to callback.
+     */
+    private reportProgress;
+    /**
+     * Check if callback expects enhanced events.
+     *
+     * @param callback Callback to check
+     * @returns True if enhanced callback
+     */
+    private isEnhancedCallback;
+}

package/dist-standalone/progress-callbacks.js

@@ -0,0 +1 @@
+import{ProgressReporter}from"./_deps/ux-helpers/index.js";export class OperationProgressTracker{callback;throttleMs;lastUpdateTime=0;currentStage="";currentStageWeight=0;currentStageProgress=0;completedWeight=0;metadata={};constructor(t,e){this.callback=t,this.throttleMs=e?.throttleMs??100}startStage(t,e,s){this.currentStage=t,this.currentStageWeight=Math.max(0,Math.min(100,e)),this.currentStageProgress=0,this.reportProgress(s??`Starting ${t}...`)}updateStageProgress(t,e,s){this.currentStageProgress=Math.max(0,Math.min(100,t)),s&&(this.metadata={...this.metadata,...s});const r=e??`${this.currentStage} (${Math.round(t)}%)`;this.reportProgress(r)}completeStage(){this.currentStageProgress=100,this.completedWeight+=this.currentStageWeight,this.reportProgress(`${this.currentStage} complete`),this.currentStage="",this.currentStageWeight=0,this.currentStageProgress=0}complete(){this.completedWeight=100,this.currentStageProgress=100,this.reportProgress("Complete")}getProgress(){const t=this.currentStageWeight*this.currentStageProgress/100;return Math.min(100,this.completedWeight+t)}updateMetadata(t){this.metadata={...this.metadata,...t}}reportProgress(t){if(!this.callback)return;const e=Date.now();if(e-this.lastUpdateTime<this.throttleMs){if(this.getProgress()<100)return}this.lastUpdateTime=e;const s=this.getProgress();if(this.isEnhancedCallback(this.callback)){const e={stage:this.currentStage,progress:s,stageProgress:this.currentStageProgress,status:t,metadata:Object.keys(this.metadata).length>0?this.metadata:void 0};this.callback(e)}else this.callback(t,s)}isEnhancedCallback(t){return 1===t.length}}export class TransferProgressTracker{totalBytes;callback;reporter;throttleMs;bytesTransferred=0;startTime=Date.now();lastUpdateTime=0;samples=[];maxSamples=10;constructor(t,e,s=100){this.totalBytes=t,this.callback=e,this.throttleMs=s,this.reporter=new ProgressReporter("function"==typeof e&&2===e.length?e:void 0)}addTransferred(t){this.bytesTransferred+=t;const e=Date.now();this.samples.push({time:e,bytes:this.bytesTransferred}),this.samples.length>this.maxSamples&&this.samples.shift(),e-this.lastUpdateTime<this.throttleMs||(this.lastUpdateTime=e,this.reportProgress())}complete(){this.bytesTransferred=this.totalBytes,this.reportProgress()}getProgress(){return 0===this.totalBytes?100:Math.min(100,this.bytesTransferred/this.totalBytes*100)}calculateBytesPerSecond(){if(this.samples.length<2){const t=(Date.now()-this.startTime)/1e3;return t>0?this.bytesTransferred/t:0}const t=this.samples[0],e=this.samples[this.samples.length-1];if(!t||!e)return 0;const s=(e.time-t.time)/1e3,r=e.bytes-t.bytes;return s>0?r/s:0}estimateTimeRemaining(){const t=this.calculateBytesPerSecond();if(0===t)return 0;return(this.totalBytes-this.bytesTransferred)/t*1e3}reportProgress(){if(!this.callback)return;const t=this.getProgress(),e=this.calculateBytesPerSecond(),s=this.estimateTimeRemaining(),r=this.formatStatus(t,e,s);if(this.isEnhancedCallback(this.callback)){const a={stage:"transfer",progress:t,stageProgress:t,status:r,metadata:{bytesTransferred:this.bytesTransferred,totalBytes:this.totalBytes,bytesPerSecond:e,estimatedTimeRemaining:s}};this.callback(a)}else this.reporter.report(r,t)}formatStatus(t,e,s){const r=this.formatBytes(this.bytesTransferred),a=this.formatBytes(this.totalBytes),i=this.formatBytes(e),o=this.formatTime(s);return`Transferring ${r} / ${a} (${Math.round(t)}%) - ${i}/s - ${o} remaining`}formatBytes(t){const e=["B","KB","MB","GB","TB"];let s=t,r=0;for(;s>=1024&&r<e.length-1;)s/=1024,r++;return`${s.toFixed(1)} ${e[r]}`}formatTime(t){const e=Math.floor(t/1e3);if(e<60)return`${e}s`;const s=Math.floor(e/60);if(s<60)return`${s}m ${e%60}s`;return`${Math.floor(s/60)}h ${s%60}m`}isEnhancedCallback(t){return 1===t.length}}export class ShareDistributionTracker{totalShares;callback;reporter;distributedShares=new Set;constructor(t,e){this.totalShares=t,this.callback=e,this.reporter=new ProgressReporter("function"==typeof e&&2===e.length?e:void 0)}markShareDistributed(t){this.distributedShares.add(t),this.reportProgress()}complete(){for(let t=0;t<this.totalShares;t++)this.distributedShares.add(t);this.reportProgress()}getProgress(){return 0===this.totalShares?100:this.distributedShares.size/this.totalShares*100}reportProgress(){if(!this.callback)return;const t=this.getProgress(),e=`Distributed ${this.distributedShares.size} / ${this.totalShares} shares`;if(this.isEnhancedCallback(this.callback)){const s={stage:"distribution",progress:t,stageProgress:t,status:e,metadata:{sharesDistributed:this.distributedShares.size,totalShares:this.totalShares}};this.callback(s)}else this.reporter.report(e,t)}isEnhancedCallback(t){return 1===t.length}}export class EncryptionProgressTracker{operation;totalItems;callback;reporter;itemsProcessed=0;constructor(t,e,s){this.operation=t,this.totalItems=e,this.callback=s,this.reporter=new ProgressReporter("function"==typeof s&&2===s.length?s:void 0)}incrementProcessed(t=1){this.itemsProcessed+=t,this.reportProgress()}complete(){this.itemsProcessed=this.totalItems,this.reportProgress()}getProgress(){return 0===this.totalItems?100:Math.min(100,this.itemsProcessed/this.totalItems*100)}reportProgress(){if(!this.callback)return;const t=this.getProgress(),e=`${this.operation.charAt(0).toUpperCase()+this.operation.slice(1)}ing: ${this.itemsProcessed} / ${this.totalItems} items`;if(this.isEnhancedCallback(this.callback)){const s={stage:this.operation,progress:t,stageProgress:t,status:e,metadata:{cryptoOperation:this.operation,itemsProcessed:this.itemsProcessed,totalItems:this.totalItems}};this.callback(s)}else this.reporter.report(e,t)}isEnhancedCallback(t){return 1===t.length}}

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

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

package/dist-standalone/registry-middleware.js

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