@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/approval.js

@@ -1 +1,193 @@
-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)}}
+/**
+ * @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);
+    }
+}

package/dist-standalone/async-iterators.js

@@ -1 +1,382 @@
-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)})}
+/**
+ * @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
+ */
+/**
+ * Async iterable message stream.
+ *
+ * Implements AsyncIterableIterator for use with `for await...of` syntax.
+ * Handles backpressure, cancellation, and error propagation.
+ */
+export class MessageStream {
+    agent;
+    options;
+    state;
+    constructor(agent, options = {}) {
+        this.agent = agent;
+        this.options = {
+            from: options.from,
+            scope: options.scope,
+            bufferSize: options.bufferSize ?? 100,
+            signal: options.signal,
+            allowCleartext: options.allowCleartext ?? false,
+        };
+        this.state = {
+            buffer: [],
+            pending: [],
+            done: false,
+        };
+        // Setup abort signal handler
+        if (this.options.signal) {
+            this.options.signal.addEventListener('abort', () => {
+                this.close(new Error('Stream aborted'));
+            });
+        }
+        // Register envelope handler
+        const handler = (envelope) => {
+            void this.handleEnvelope(envelope);
+        };
+        // Get first transport adapter and register handler
+        const transports = this.agent.getTransports();
+        const transport = transports[0];
+        if (transport) {
+            transport.onReceive(handler);
+            this.state.cleanup = () => {
+                // Remove handler by creating new transport without this handler
+                // (Transport interface doesn't support handler removal)
+            };
+        }
+    }
+    /**
+     * Handle incoming envelope from transport.
+     * @internal
+     */
+    async handleEnvelope(envelope) {
+        if (this.state.done)
+            return;
+        // Verify and decrypt the envelope
+        const result = await this.agent.receive(envelope, {
+            allowCleartext: this.options.allowCleartext,
+        });
+        if (!result.ok) {
+            // Ignore verification errors (not all envelopes are for this stream)
+            return;
+        }
+        const message = result.value;
+        // Apply filters
+        if (this.options.from && message.sender !== this.options.from) {
+            return;
+        }
+        if (this.options.scope && message.scope !== this.options.scope) {
+            return;
+        }
+        // Deliver message
+        if (this.state.pending.length > 0) {
+            // Consumer is waiting - deliver immediately
+            const resolve = this.state.pending.shift();
+            resolve({ value: message, done: false });
+        }
+        else if (this.state.buffer.length < this.options.bufferSize) {
+            // Buffer has space - enqueue
+            this.state.buffer.push(message);
+        }
+        // else: buffer full - drop message (backpressure)
+    }
+    /**
+     * Close the stream with optional error.
+     * @internal
+     */
+    close(error) {
+        if (this.state.done)
+            return;
+        this.state.done = true;
+        this.state.error = error;
+        // Resolve all pending next() calls
+        for (const resolve of this.state.pending) {
+            if (error) {
+                resolve({ value: undefined, done: true });
+            }
+            else {
+                resolve({ value: undefined, done: true });
+            }
+        }
+        this.state.pending = [];
+        // Cleanup resources
+        if (this.state.cleanup) {
+            this.state.cleanup();
+        }
+    }
+    /**
+     * 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
+     */
+    async next() {
+        // Stream already done
+        if (this.state.done) {
+            return { value: undefined, done: true };
+        }
+        // Check abort signal
+        if (this.options.signal?.aborted) {
+            this.close(new Error('Stream aborted'));
+            return { value: undefined, done: true };
+        }
+        // Message available in buffer
+        if (this.state.buffer.length > 0) {
+            const message = this.state.buffer.shift();
+            return { value: message, done: false };
+        }
+        // Wait for next message
+        return new Promise((resolve) => {
+            this.state.pending.push(resolve);
+        });
+    }
+    /**
+     * Return method for iterator protocol.
+     * Closes the stream and completes iteration.
+     *
+     * @param value - Optional value (ignored)
+     * @returns Promise resolving to done result
+     */
+    async return(value) {
+        this.close();
+        return { value: undefined, done: true };
+    }
+    /**
+     * Throw method for iterator protocol.
+     * Closes the stream with error.
+     *
+     * @param error - Error to propagate
+     * @returns Promise resolving to done result
+     */
+    async throw(error) {
+        this.close(error instanceof Error ? error : new Error(String(error)));
+        return { value: undefined, done: true };
+    }
+    /**
+     * Make this object async iterable.
+     * Enables `for await...of` syntax.
+     *
+     * @returns This stream instance
+     */
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    /**
+     * Get number of buffered messages.
+     * Useful for monitoring backpressure.
+     */
+    get bufferedCount() {
+        return this.state.buffer.length;
+    }
+    /**
+     * Check if stream is closed.
+     */
+    get closed() {
+        return this.state.done;
+    }
+    /**
+     * Get stream error if any.
+     */
+    get error() {
+        return this.state.error;
+    }
+}
+/**
+ * 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 async function collectMessages(agent, options = {}) {
+    const messages = [];
+    const stream = new MessageStream(agent, options);
+    // Setup timeout if specified
+    let timeoutId;
+    if (options.timeout) {
+        timeoutId = setTimeout(() => {
+            void stream.return();
+        }, options.timeout);
+    }
+    try {
+        for await (const message of stream) {
+            messages.push(message);
+            if (options.limit && messages.length >= options.limit) {
+                break;
+            }
+        }
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        if (!stream.closed) {
+            await stream.return();
+        }
+    }
+    return messages;
+}
+/**
+ * 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 async function* mapStream(stream, fn) {
+    for await (const value of stream) {
+        yield await fn(value);
+    }
+}
+/**
+ * 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 async function* filterStream(stream, predicate) {
+    for await (const value of stream) {
+        if (await predicate(value)) {
+            yield value;
+        }
+    }
+}
+/**
+ * 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 async function* takeStream(stream, count) {
+    let taken = 0;
+    for await (const value of stream) {
+        if (taken >= count)
+            break;
+        yield value;
+        taken++;
+    }
+}
+/**
+ * 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 async function* mergeStreams(streams) {
+    const iterators = streams.map((s) => s[Symbol.asyncIterator]());
+    const pending = new Map();
+    // Start all iterators
+    for (let i = 0; i < iterators.length; i++) {
+        pending.set(i, iterators[i].next());
+    }
+    while (pending.size > 0) {
+        // Race all pending next() calls
+        const entries = Array.from(pending.entries());
+        const winner = await Promise.race(entries.map(async ([idx, promise]) => ({ idx, result: await promise })));
+        pending.delete(winner.idx);
+        if (!winner.result.done) {
+            yield winner.result.value;
+            // Start next iteration for this stream
+            pending.set(winner.idx, iterators[winner.idx].next());
+        }
+    }
+}
+/**
+ * Add subscribe method to Agent prototype.
+ * @internal
+ */
+export function installAsyncIterators(AgentClass) {
+    if ('subscribe' in AgentClass.prototype) {
+        return; // Already installed
+    }
+    AgentClass.prototype.subscribe = function (options) {
+        return new MessageStream(this, options);
+    };
+}