@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/approval.js

@@ -1,193 +1 @@
-/**
- * @module approval
- * OAuth-style approval flow for agents
- *
- * Enterprise agents require explicit user consent before performing
- * sensitive operations. This module implements OAuth-style consent
- * screens and approval tokens.
- */
-import { ok, err } from"./_deps/shared/index.js";
-/**
- * Approval error codes
- */
-export var ApprovalErrorCode;
-(function (ApprovalErrorCode) {
-    ApprovalErrorCode["USER_DENIED"] = "APPROVAL_USER_DENIED";
-    ApprovalErrorCode["TIMEOUT"] = "APPROVAL_TIMEOUT";
-    ApprovalErrorCode["INVALID_DURATION"] = "APPROVAL_INVALID_DURATION";
-    ApprovalErrorCode["SIGNATURE_FAILED"] = "APPROVAL_SIGNATURE_FAILED";
-    ApprovalErrorCode["TOKEN_EXPIRED"] = "APPROVAL_TOKEN_EXPIRED";
-    ApprovalErrorCode["TOKEN_REVOKED"] = "APPROVAL_TOKEN_REVOKED";
-    ApprovalErrorCode["INVALID_TOKEN"] = "APPROVAL_INVALID_TOKEN";
-})(ApprovalErrorCode || (ApprovalErrorCode = {}));
-/**
- * Approval error
- */
-export class ApprovalError extends Error {
-    code;
-    details;
-    constructor(code, message, details) {
-        super(message);
-        this.code = code;
-        this.details = details;
-        this.name = 'ApprovalError';
-    }
-}
-/**
- * CLI approval presenter (prints to console, reads stdin)
- * This is a legitimate CLI interface - console output is intentional
- */
-export class CLIApprovalPresenter {
-    /* eslint-disable no-console */
-    async present(options) {
-        console.log('\n=== AGENT APPROVAL REQUEST ===');
-        console.log(`Agent: ${options.agentDid}`);
-        console.log(`Duration: ${options.duration}`);
-        console.log('\nRequested Scopes:');
-        for (const scope of options.scopes) {
-            console.log(`  - ${scope}`);
-        }
-        if (options.limits) {
-            console.log('\nPolicy Limits:');
-            if (options.limits.amountPerTxn) {
-                console.log(`  - Max per transaction: $${options.limits.amountPerTxn.toLocaleString()}`);
-            }
-            if (options.limits.dailyAmount) {
-                console.log(`  - Daily limit: $${options.limits.dailyAmount.toLocaleString()}`);
-            }
-            if (options.limits.callsPerMinute) {
-                console.log(`  - Rate limit: ${options.limits.callsPerMinute} calls/minute`);
-            }
-        }
-        if (options.description) {
-            console.log(`\nDescription: ${options.description}`);
-        }
-        console.log('\n[This is a mock presenter - auto-approving for development]');
-        console.log('In production, this would prompt for user input.\n');
-        // Auto-approve for development (production would prompt for y/n)
-        return ok({
-            approved: true,
-        });
-    }
-}
-/**
- * Approval flow coordinator
- *
- * Orchestrates the consent flow: present to user → sign token → track expiry
- */
-export class ApprovalFlow {
-    presenter;
-    tokens = new Map();
-    constructor(options = {}) {
-        this.presenter = options.presenter ?? new CLIApprovalPresenter();
-    }
-    /**
-     * Request approval from user
-     *
-     * @param options - Approval request options
-     * @returns Approval result with token (if approved)
-     */
-    async requestApproval(options) {
-        // Validate duration
-        const durationMs = this.parseDuration(options.duration);
-        if (durationMs <= 0) {
-            return err(new ApprovalError(ApprovalErrorCode.INVALID_DURATION, `Invalid duration: ${options.duration}`));
-        }
-        // Present to user
-        const result = await this.presenter.present(options);
-        if (!result.ok)
-            return result;
-        if (!result.value.approved) {
-            return ok({
-                approved: false,
-                reason: result.value.reason ?? 'User denied approval',
-            });
-        }
-        // Generate approval token
-        const now = Date.now();
-        const token = {
-            id: this.generateTokenId(),
-            agentDid: options.agentDid,
-            scopes: options.scopes,
-            limits: options.limits,
-            expiresAt: now + durationMs,
-            createdAt: now,
-            valid: true,
-            signature: await this.signToken(options.agentDid, options.scopes, now + durationMs),
-        };
-        // Store token
-        this.tokens.set(token.id, token);
-        return ok({
-            approved: true,
-            token,
-        });
-    }
-    /**
-     * Verify an approval token
-     *
-     * @param tokenId - Token ID to verify
-     * @returns Token if valid, error otherwise
-     */
-    verifyToken(tokenId) {
-        const token = this.tokens.get(tokenId);
-        if (!token) {
-            return err(new ApprovalError(ApprovalErrorCode.INVALID_TOKEN, `Token ${tokenId} not found`));
-        }
-        if (!token.valid) {
-            return err(new ApprovalError(ApprovalErrorCode.TOKEN_REVOKED, `Token ${tokenId} has been revoked`));
-        }
-        if (Date.now() > token.expiresAt) {
-            return err(new ApprovalError(ApprovalErrorCode.TOKEN_EXPIRED, `Token ${tokenId} expired at ${new Date(token.expiresAt).toISOString()}`));
-        }
-        return ok(token);
-    }
-    /**
-     * Revoke an approval token
-     *
-     * @param tokenId - Token ID to revoke
-     */
-    revokeToken(tokenId) {
-        const token = this.tokens.get(tokenId);
-        if (token) {
-            this.tokens.set(tokenId, { ...token, valid: false });
-        }
-    }
-    /**
-     * Parse duration string to milliseconds
-     */
-    parseDuration(duration) {
-        if (typeof duration === 'number')
-            return duration;
-        // Parse ISO 8601 duration or simple format
-        const matches = duration.match(/^(\d+)([smhd])$/);
-        if (!matches)
-            return -1;
-        const value = parseInt(matches[1] ?? '0', 10);
-        const unit = matches[2];
-        switch (unit) {
-            case 's': return value * 1000;
-            case 'm': return value * 60 * 1000;
-            case 'h': return value * 60 * 60 * 1000;
-            case 'd': return value * 24 * 60 * 60 * 1000;
-            default: return -1;
-        }
-    }
-    /**
-     * Generate a unique token ID
-     */
-    generateTokenId() {
-        const randomBytes = new Uint8Array(12);
-        crypto.getRandomValues(randomBytes);
-        const randomString = Array.from(randomBytes, b => b.toString(16).padStart(2, '0')).join('');
-        return `appr_${Date.now()}_${randomString}`;
-    }
-    /**
-     * Sign an approval token (stub - production would use Ed25519)
-     */
-    async signToken(agentDid, scopes, expiresAt) {
-        // Production would use Ed25519 signature over JSON.stringify({ agentDid, scopes, expiresAt })
-        // For now, return a mock signature
-        const payload = JSON.stringify({ agentDid, scopes, expiresAt });
-        return btoa(payload).substring(0, 32);
-    }
-}
+import{ok,err}from"./_deps/shared/index.js";export var ApprovalErrorCode;!function(e){e.USER_DENIED="APPROVAL_USER_DENIED",e.TIMEOUT="APPROVAL_TIMEOUT",e.INVALID_DURATION="APPROVAL_INVALID_DURATION",e.SIGNATURE_FAILED="APPROVAL_SIGNATURE_FAILED",e.TOKEN_EXPIRED="APPROVAL_TOKEN_EXPIRED",e.TOKEN_REVOKED="APPROVAL_TOKEN_REVOKED",e.INVALID_TOKEN="APPROVAL_INVALID_TOKEN"}(ApprovalErrorCode||(ApprovalErrorCode={}));export class ApprovalError extends Error{code;details;constructor(e,r,o){super(r),this.code=e,this.details=o,this.name="ApprovalError"}}export class CLIApprovalPresenter{async present(e){console.log("\n=== AGENT APPROVAL REQUEST ==="),console.log(`Agent: ${e.agentDid}`),console.log(`Duration: ${e.duration}`),console.log("\nRequested Scopes:");for(const r of e.scopes)console.log(`  - ${r}`);return e.limits&&(console.log("\nPolicy Limits:"),e.limits.amountPerTxn&&console.log(`  - Max per transaction: $${e.limits.amountPerTxn.toLocaleString()}`),e.limits.dailyAmount&&console.log(`  - Daily limit: $${e.limits.dailyAmount.toLocaleString()}`),e.limits.callsPerMinute&&console.log(`  - Rate limit: ${e.limits.callsPerMinute} calls/minute`)),e.description&&console.log(`\nDescription: ${e.description}`),console.log("\n[This is a mock presenter - auto-approving for development]"),console.log("In production, this would prompt for user input.\n"),ok({approved:!0})}}export class ApprovalFlow{presenter;tokens=new Map;constructor(e={}){this.presenter=e.presenter??new CLIApprovalPresenter}async requestApproval(e){const r=this.parseDuration(e.duration);if(r<=0)return err(new ApprovalError(ApprovalErrorCode.INVALID_DURATION,`Invalid duration: ${e.duration}`));const o=await this.presenter.present(e);if(!o.ok)return o;if(!o.value.approved)return ok({approved:!1,reason:o.value.reason??"User denied approval"});const t=Date.now(),n={id:this.generateTokenId(),agentDid:e.agentDid,scopes:e.scopes,limits:e.limits,expiresAt:t+r,createdAt:t,valid:!0,signature:await this.signToken(e.agentDid,e.scopes,t+r)};return this.tokens.set(n.id,n),ok({approved:!0,token:n})}verifyToken(e){const r=this.tokens.get(e);return r?r.valid?Date.now()>r.expiresAt?err(new ApprovalError(ApprovalErrorCode.TOKEN_EXPIRED,`Token ${e} expired at ${new Date(r.expiresAt).toISOString()}`)):ok(r):err(new ApprovalError(ApprovalErrorCode.TOKEN_REVOKED,`Token ${e} has been revoked`)):err(new ApprovalError(ApprovalErrorCode.INVALID_TOKEN,`Token ${e} not found`))}revokeToken(e){const r=this.tokens.get(e);r&&this.tokens.set(e,{...r,valid:!1})}parseDuration(e){if("number"==typeof e)return e;const r=e.match(/^(\d+)([smhd])$/);if(!r)return-1;const o=parseInt(r[1]??"0",10);switch(r[2]){case"s":return 1e3*o;case"m":return 60*o*1e3;case"h":return 60*o*60*1e3;case"d":return 24*o*60*60*1e3;default:return-1}}generateTokenId(){const e=new Uint8Array(12);crypto.getRandomValues(e);const r=Array.from(e,e=>e.toString(16).padStart(2,"0")).join("");return`appr_${Date.now()}_${r}`}async signToken(e,r,o){const t=JSON.stringify({agentDid:e,scopes:r,expiresAt:o});return btoa(t).substring(0,32)}}

package/dist-standalone/async-iterators.d.ts

@@ -0,0 +1,275 @@
+/**
+ * @fileoverview Async iterator API for xBind message streams.
+ *
+ * Provides modern async iteration patterns for consuming message streams
+ * with backpressure handling, stream cancellation, and error propagation.
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to messages with async iteration
+ * for await (const message of agent.subscribe({ from: 'did:key:alice' })) {
+ *   console.log('Received:', message.payload);
+ * }
+ * ```
+ *
+ * @module async-iterators
+ */
+import type { Agent, AgentMessage } from './agent.js';
+/**
+ * Options for message stream subscription.
+ */
+export interface MessageStreamOptions {
+    /**
+     * Filter messages by sender DID.
+     * If undefined, accepts messages from all senders.
+     */
+    readonly from?: string;
+    /**
+     * Filter messages by scope.
+     * If undefined, accepts messages with any scope.
+     */
+    readonly scope?: string;
+    /**
+     * Maximum number of buffered messages before backpressure.
+     * When buffer is full, new messages are dropped until consumed.
+     * Default: 100
+     */
+    readonly bufferSize?: number;
+    /**
+     * Signal to abort the stream.
+     * When aborted, the iterator completes and cleans up resources.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Allow cleartext messages (signed but not encrypted).
+     * Default: false
+     */
+    readonly allowCleartext?: boolean;
+}
+/**
+ * Async iterable message stream.
+ *
+ * Implements AsyncIterableIterator for use with `for await...of` syntax.
+ * Handles backpressure, cancellation, and error propagation.
+ */
+export declare class MessageStream implements AsyncIterableIterator<AgentMessage> {
+    private readonly agent;
+    private readonly options;
+    private readonly state;
+    constructor(agent: Agent, options?: MessageStreamOptions);
+    /**
+     * Handle incoming envelope from transport.
+     * @internal
+     */
+    private handleEnvelope;
+    /**
+     * Close the stream with optional error.
+     * @internal
+     */
+    private close;
+    /**
+     * Get next message from the stream.
+     *
+     * Returns a promise that resolves when:
+     * - A message is available in the buffer
+     * - A new message arrives from the transport
+     * - The stream is closed
+     *
+     * @returns Promise resolving to iterator result
+     */
+    next(): Promise<IteratorResult<AgentMessage>>;
+    /**
+     * Return method for iterator protocol.
+     * Closes the stream and completes iteration.
+     *
+     * @param value - Optional value (ignored)
+     * @returns Promise resolving to done result
+     */
+    return(value?: any): Promise<IteratorResult<AgentMessage>>;
+    /**
+     * Throw method for iterator protocol.
+     * Closes the stream with error.
+     *
+     * @param error - Error to propagate
+     * @returns Promise resolving to done result
+     */
+    throw(error?: any): Promise<IteratorResult<AgentMessage>>;
+    /**
+     * Make this object async iterable.
+     * Enables `for await...of` syntax.
+     *
+     * @returns This stream instance
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<AgentMessage>;
+    /**
+     * Get number of buffered messages.
+     * Useful for monitoring backpressure.
+     */
+    get bufferedCount(): number;
+    /**
+     * Check if stream is closed.
+     */
+    get closed(): boolean;
+    /**
+     * Get stream error if any.
+     */
+    get error(): Error | undefined;
+}
+/**
+ * Options for batch message collection.
+ */
+export interface CollectOptions extends MessageStreamOptions {
+    /**
+     * Maximum number of messages to collect.
+     * Stream completes after collecting this many messages.
+     * If undefined, collects indefinitely until stream ends.
+     */
+    readonly limit?: number;
+    /**
+     * Timeout in milliseconds.
+     * Stream completes after this duration regardless of message count.
+     * If undefined, no timeout (waits indefinitely).
+     */
+    readonly timeout?: number;
+}
+/**
+ * Collect messages from a stream into an array.
+ *
+ * Useful for batch processing or testing. Stream completes when:
+ * - Limit is reached
+ * - Timeout expires
+ * - Stream is aborted via signal
+ *
+ * @param agent - Agent instance to collect messages from
+ * @param options - Collection options
+ * @returns Promise resolving to array of messages
+ *
+ * @example
+ * ```typescript
+ * // Collect up to 10 messages with 5 second timeout
+ * const messages = await collectMessages(agent, {
+ *   from: 'did:key:alice',
+ *   limit: 10,
+ *   timeout: 5000
+ * });
+ * ```
+ */
+export declare function collectMessages(agent: Agent, options?: CollectOptions): Promise<AgentMessage[]>;
+/**
+ * Transform message stream with async mapping function.
+ *
+ * Enables functional-style stream processing with backpressure preservation.
+ *
+ * @param stream - Source message stream
+ * @param fn - Async transform function
+ * @returns Async iterable of transformed values
+ *
+ * @example
+ * ```typescript
+ * const stream = agent.subscribe({ from: 'did:key:alice' });
+ * const payloads = mapStream(stream, async (msg) => msg.payload);
+ *
+ * for await (const payload of payloads) {
+ *   console.log('Payload:', payload);
+ * }
+ * ```
+ */
+export declare function mapStream<T, U>(stream: AsyncIterable<T>, fn: (value: T) => Promise<U> | U): AsyncIterableIterator<U>;
+/**
+ * Filter message stream with async predicate.
+ *
+ * Only yields messages that satisfy the predicate.
+ *
+ * @param stream - Source message stream
+ * @param predicate - Async filter predicate
+ * @returns Async iterable of filtered messages
+ *
+ * @example
+ * ```typescript
+ * const stream = agent.subscribe({ scope: 'notifications' });
+ * const urgent = filterStream(stream, async (msg) =>
+ *   msg.payload.priority === 'high'
+ * );
+ *
+ * for await (const message of urgent) {
+ *   await handleUrgent(message);
+ * }
+ * ```
+ */
+export declare function filterStream<T>(stream: AsyncIterable<T>, predicate: (value: T) => Promise<boolean> | boolean): AsyncIterableIterator<T>;
+/**
+ * Take first N messages from stream.
+ *
+ * Stream completes after yielding N messages.
+ *
+ * @param stream - Source message stream
+ * @param count - Maximum messages to take
+ * @returns Async iterable with at most count messages
+ *
+ * @example
+ * ```typescript
+ * const stream = agent.subscribe();
+ * const first5 = takeStream(stream, 5);
+ *
+ * for await (const message of first5) {
+ *   console.log('Message:', message);
+ * }
+ * ```
+ */
+export declare function takeStream<T>(stream: AsyncIterable<T>, count: number): AsyncIterableIterator<T>;
+/**
+ * Merge multiple message streams into one.
+ *
+ * Yields messages from all streams as they arrive.
+ * Completes when all source streams complete.
+ *
+ * @param streams - Array of source streams
+ * @returns Async iterable of merged messages
+ *
+ * @example
+ * ```typescript
+ * const stream1 = agent.subscribe({ from: 'did:key:alice' });
+ * const stream2 = agent.subscribe({ from: 'did:key:bob' });
+ * const merged = mergeStreams([stream1, stream2]);
+ *
+ * for await (const message of merged) {
+ *   console.log('From:', message.sender);
+ * }
+ * ```
+ */
+export declare function mergeStreams<T>(streams: AsyncIterable<T>[]): AsyncIterableIterator<T>;
+declare module './agent.js' {
+    interface Agent {
+        /**
+         * Subscribe to incoming messages as an async iterable stream.
+         *
+         * Enables modern async iteration patterns with `for await...of` syntax.
+         * Handles backpressure, cancellation, and error propagation.
+         *
+         * @param options - Stream subscription options
+         * @returns Async iterable message stream
+         *
+         * @example
+         * ```typescript
+         * // Subscribe to all messages from Alice
+         * for await (const message of agent.subscribe({ from: 'did:key:alice' })) {
+         *   console.log('Received:', message.payload);
+         * }
+         *
+         * // With abort signal
+         * const controller = new AbortController();
+         * setTimeout(() => controller.abort(), 5000); // 5 second timeout
+         *
+         * for await (const message of agent.subscribe({ signal: controller.signal })) {
+         *   console.log('Message:', message);
+         * }
+         * ```
+         */
+        subscribe(options?: MessageStreamOptions): MessageStream;
+    }
+}
+/**
+ * Add subscribe method to Agent prototype.
+ * @internal
+ */
+export declare function installAsyncIterators(AgentClass: typeof Agent): void;

package/dist-standalone/async-iterators.js

@@ -0,0 +1 @@
+export class MessageStream{agent;options;state;constructor(t,e={}){this.agent=t,this.options={from:e.from,scope:e.scope,bufferSize:e.bufferSize??100,signal:e.signal,allowCleartext:e.allowCleartext??!1},this.state={buffer:[],pending:[],done:!1},this.options.signal&&this.options.signal.addEventListener("abort",()=>{this.close(new Error("Stream aborted"))});const s=t=>{this.handleEnvelope(t)},n=this.agent.getTransports()[0];n&&(n.onReceive(s),this.state.cleanup=()=>{})}async handleEnvelope(t){if(this.state.done)return;const e=await this.agent.receive(t,{allowCleartext:this.options.allowCleartext});if(!e.ok)return;const s=e.value;if(!(this.options.from&&s.sender!==this.options.from||this.options.scope&&s.scope!==this.options.scope))if(this.state.pending.length>0){this.state.pending.shift()({value:s,done:!1})}else this.state.buffer.length<this.options.bufferSize&&this.state.buffer.push(s)}close(t){if(!this.state.done){this.state.done=!0,this.state.error=t;for(const t of this.state.pending)t({value:void 0,done:!0});this.state.pending=[],this.state.cleanup&&this.state.cleanup()}}async next(){if(this.state.done)return{value:void 0,done:!0};if(this.options.signal?.aborted)return this.close(new Error("Stream aborted")),{value:void 0,done:!0};if(this.state.buffer.length>0){return{value:this.state.buffer.shift(),done:!1}}return new Promise(t=>{this.state.pending.push(t)})}async return(t){return this.close(),{value:void 0,done:!0}}async throw(t){return this.close(t instanceof Error?t:new Error(String(t))),{value:void 0,done:!0}}[Symbol.asyncIterator](){return this}get bufferedCount(){return this.state.buffer.length}get closed(){return this.state.done}get error(){return this.state.error}}export async function collectMessages(t,e={}){const s=[],n=new MessageStream(t,e);let o;e.timeout&&(o=setTimeout(()=>{n.return()},e.timeout));try{for await(const t of n)if(s.push(t),e.limit&&s.length>=e.limit)break}finally{o&&clearTimeout(o),n.closed||await n.return()}return s}export async function*mapStream(t,e){for await(const s of t)yield await e(s)}export async function*filterStream(t,e){for await(const s of t)await e(s)&&(yield s)}export async function*takeStream(t,e){let s=0;for await(const n of t){if(s>=e)break;yield n,s++}}export async function*mergeStreams(t){const e=t.map(t=>t[Symbol.asyncIterator]()),s=new Map;for(let t=0;t<e.length;t++)s.set(t,e[t].next());for(;s.size>0;){const t=Array.from(s.entries()),n=await Promise.race(t.map(async([t,e])=>({idx:t,result:await e})));s.delete(n.idx),n.result.done||(yield n.result.value,s.set(n.idx,e[n.idx].next()))}}export function installAsyncIterators(t){"subscribe"in t.prototype||(t.prototype.subscribe=function(t){return new MessageStream(this,t)})}