@private.me/xbind 1.2.0

package/dist-standalone/cjs/gateway-transport.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Gateway transport adapter for delivering envelopes to Xail inbox users.
+ *
+ * Sends envelopes via POST /gateway/deliver on the hosted gateway API.
+ * For agent-to-agent (M2M), use HttpsTransportAdapter with direct URLs.
+ * Optionally polls for incoming messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayTransport = void 0;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Transport adapter for the Xail Gateway.
+ *
+ * Sends envelopes via POST /gateway/deliver with API key auth.
+ * Optionally polls GET /gateway/messages/:did for incoming messages.
+ */
+class GatewayTransport {
+    apiKey;
+    gateway;
+    timeoutMs;
+    fetchFn;
+    pollIntervalMs;
+    handlers = [];
+    pollTimer = null;
+    senderDid = null;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.gateway = opts.gateway.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 15_000;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.pollIntervalMs = opts.pollIntervalMs ?? 0;
+    }
+    /**
+     * Send a signed envelope to a recipient via the gateway.
+     * @param envelope - The signed transport envelope.
+     * @param _recipientDid - Recipient DID (already in envelope.recipient).
+     * @returns Success or transport error.
+     */
+    async send(envelope, _recipientDid) {
+        const url = `${this.gateway}/gateway/deliver`;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            const response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!response.ok) {
+                return (0, shared_1.err)(response.status === 404
+                    ? 'RECIPIENT_UNREACHABLE'
+                    : 'SEND_FAILED');
+            }
+            return (0, shared_1.ok)(undefined);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === 'AbortError') {
+                return (0, shared_1.err)('TIMEOUT');
+            }
+            return (0, shared_1.err)('NETWORK_ERROR');
+        }
+    }
+    /** Register a handler for incoming envelopes. */
+    onReceive(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Start polling for incoming messages.
+     * Must be called after Agent.create() sets the sender DID.
+     * @param did - The agent's own DID for polling.
+     */
+    startPolling(did) {
+        this.senderDid = did;
+        if (this.pollIntervalMs > 0 && !this.pollTimer) {
+            this.pollTimer = setInterval(() => void this.poll(), this.pollIntervalMs);
+        }
+    }
+    /** Shut down the transport (stop polling, clear handlers). */
+    dispose() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.handlers = [];
+    }
+    /** Poll for incoming messages and dispatch to handlers. */
+    async poll() {
+        if (!this.senderDid)
+            return;
+        try {
+            const url = `${this.gateway}/gateway/messages/${encodeURIComponent(this.senderDid)}`;
+            const res = await this.fetchFn(url, {
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+            });
+            if (!res.ok)
+                return;
+            const data = (await res.json());
+            for (const msg of data.messages) {
+                for (const handler of this.handlers) {
+                    handler(msg.envelope);
+                }
+                // Ack delivery
+                await this.fetchFn(`${this.gateway}/gateway/ack/${msg.id}`, {
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${this.apiKey}` },
+                });
+            }
+        }
+        catch {
+            // Silent failure — polling errors are non-fatal
+        }
+    }
+}
+exports.GatewayTransport = GatewayTransport;

package/dist-standalone/cjs/guardrails.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * @module guardrails
+ * Enhanced error messages with actionable suggestions for policy violations
+ *
+ * When policies deny requests, guardrails provide specific, actionable
+ * guidance on how to fix the issue or what to request from admins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Guardrails = exports.PolicyDenied = void 0;
+exports.extractSuggestion = extractSuggestion;
+exports.toPolicyDenied = toPolicyDenied;
+/**
+ * Policy violation error with actionable suggestions
+ */
+class PolicyDenied extends Error {
+    rule;
+    allowed;
+    requested;
+    suggestion;
+    details;
+    constructor(
+    /** Which policy rule was violated */
+    rule, 
+    /** What the policy allows */
+    allowed, 
+    /** What was requested */
+    requested, 
+    /** Actionable suggestion for how to fix */
+    suggestion, 
+    /** Full policy violation details */
+    details) {
+        super(`Policy violation: ${rule}`);
+        this.rule = rule;
+        this.allowed = allowed;
+        this.requested = requested;
+        this.suggestion = suggestion;
+        this.details = details;
+        this.name = 'PolicyDenied';
+    }
+    /**
+     * Format error for AI agent consumption
+     *
+     * Structured format optimized for LLM parsing
+     */
+    toAgentFormat() {
+        return [
+            `POLICY_VIOLATION: ${this.rule}`,
+            `REQUESTED: ${JSON.stringify(this.requested)}`,
+            `ALLOWED: ${JSON.stringify(this.allowed)}`,
+            `SUGGESTION: ${this.suggestion}`,
+        ].join('\n');
+    }
+    /**
+     * Format error for human consumption
+     *
+     * User-friendly format with clear next steps
+     */
+    toUserFormat() {
+        return [
+            `❌ Policy Violation: ${this.rule}`,
+            '',
+            `You requested: ${this.formatValue(this.requested)}`,
+            `Policy allows: ${this.formatValue(this.allowed)}`,
+            '',
+            `💡 Suggestion: ${this.suggestion}`,
+        ].join('\n');
+    }
+    /**
+     * Format error for logs (structured JSON)
+     */
+    toLogFormat() {
+        return {
+            error: 'PolicyDenied',
+            rule: this.rule,
+            allowed: this.allowed,
+            requested: this.requested,
+            suggestion: this.suggestion,
+            details: this.details,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    formatValue(value) {
+        if (typeof value === 'number') {
+            // Format currency if it looks like money
+            if (this.rule.includes('amount') || this.rule.includes('Amount')) {
+                return `$${value.toLocaleString()}`;
+            }
+            return value.toLocaleString();
+        }
+        if (Array.isArray(value)) {
+            return value.map((v) => `"${String(v)}"`).join(', ');
+        }
+        return JSON.stringify(value);
+    }
+}
+exports.PolicyDenied = PolicyDenied;
+/**
+ * Guardrail builder - fluent API for creating policy errors with suggestions
+ *
+ * @example
+ * ```typescript
+ * const error = Guardrails.amountExceeded({
+ *   requested: 5000,
+ *   limit: 1000,
+ *   type: 'per-transaction'
+ * });
+ *
+ * throw error;
+ * // ❌ Policy Violation: maxAmount
+ * // You requested: $5,000
+ * // Policy allows: $1,000
+ * // 💡 Suggestion: Reduce amount to $1,000 or request policy update from admin
+ * ```
+ */
+class Guardrails {
+    /**
+     * Amount exceeded (per-transaction limit)
+     */
+    static amountExceeded(options) {
+        let rule;
+        let suggestion;
+        switch (options.type) {
+            case 'per-transaction':
+                rule = 'maxAmount';
+                suggestion = `Reduce amount to $${options.limit.toLocaleString()} or request policy update from admin`;
+                break;
+            case 'daily':
+                rule = 'dailyAmount';
+                suggestion = `Reduce amount to stay within daily limit of $${options.limit.toLocaleString()}, or wait until tomorrow`;
+                break;
+            case 'monthly':
+                rule = 'monthlyAmount';
+                suggestion = `Reduce amount to stay within monthly limit of $${options.limit.toLocaleString()}, or wait until next month`;
+                break;
+        }
+        return new PolicyDenied(rule, options.limit, options.requested, suggestion);
+    }
+    /**
+     * Rate limit exceeded
+     */
+    static rateLimitExceeded(options) {
+        const windowSec = options.windowMs / 1000;
+        const suggestion = windowSec >= 60
+            ? `Wait ${Math.ceil(windowSec / 60)} minutes before making additional calls`
+            : `Wait ${windowSec} seconds before making additional calls`;
+        return new PolicyDenied('callsPerMinute', options.limit, options.current + 1, suggestion);
+    }
+    /**
+     * Tool not allowed
+     */
+    static toolDenied(options) {
+        const [service] = options.tool.split(':');
+        const suggestion = options.allowed.length === 0
+            ? `No tools are currently allowed. Request approval from admin to enable "${options.tool}"`
+            : `Request approval from admin to add "${options.tool}" or "${service}:*" to allowed tools`;
+        return new PolicyDenied('allowedTools', options.allowed, options.tool, suggestion);
+    }
+    /**
+     * Scope not allowed
+     */
+    static scopeDenied(options) {
+        const suggestion = options.allowed.length === 0
+            ? `No scopes are currently allowed. Request approval from admin to enable "${options.scope}"`
+            : `Request approval from admin to add "${options.scope}" to allowed scopes`;
+        return new PolicyDenied('allowedScopes', options.allowed, options.scope, suggestion);
+    }
+    /**
+     * Field filter denied (data access restriction)
+     */
+    static fieldDenied(options) {
+        const suggestion = `Field "${options.field}" is restricted. Contact admin to update policy.fieldFilters for "${options.tool}"`;
+        return new PolicyDenied('fieldFilters', options.allowed, options.field, suggestion);
+    }
+    /**
+     * Time window restriction
+     */
+    static timeWindowDenied(options) {
+        const suggestion = `Actions are only allowed between ${options.allowedStart} and ${options.allowedEnd}. Current time is ${options.current.toTimeString()}`;
+        return new PolicyDenied('timeWindow', `${options.allowedStart} - ${options.allowedEnd}`, options.current.toTimeString(), suggestion);
+    }
+    /**
+     * Generic policy violation
+     */
+    static custom(options) {
+        return new PolicyDenied(options.rule, options.allowed, options.requested, options.suggestion);
+    }
+}
+exports.Guardrails = Guardrails;
+/**
+ * Helper: Extract actionable suggestion from AgentError details
+ *
+ * Used by agent.call() to convert PolicyViolationDetails into PolicyDenied
+ */
+function extractSuggestion(details) {
+    return details.fix ?? 'Contact administrator to update policy';
+}
+/**
+ * Helper: Convert PolicyViolationDetails to PolicyDenied
+ */
+function toPolicyDenied(details) {
+    let rule;
+    switch (details.constraint) {
+        case 'amountPerTxn':
+            rule = 'maxAmount';
+            break;
+        case 'dailyAmount':
+            rule = 'dailyAmount';
+            break;
+        case 'callsPerMinute':
+            rule = 'callsPerMinute';
+            break;
+        case 'scope':
+            rule = 'allowedScopes';
+            break;
+        case 'tool':
+            rule = 'allowedTools';
+            break;
+        default:
+            rule = String(details.constraint);
+    }
+    return new PolicyDenied(rule, details.allowed, details.requested, details.fix, details);
+}

package/dist-standalone/cjs/http-compat.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * @module http-compat
+ * HTTP client compatibility adapters for xBind auto-upgrade
+ *
+ * Provides drop-in replacements for popular HTTP clients (fetch, axios, got)
+ * that transparently upgrade to xBind when both parties support it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAxiosCompat = createAxiosCompat;
+exports.createGotCompat = createGotCompat;
+exports.wrapFetch = wrapFetch;
+const xfetch_js_1 = require("./xfetch.js");
+/**
+ * Create axios-compatible HTTP client with xBind auto-upgrade
+ *
+ * Drop-in replacement for axios that transparently upgrades to xBind.
+ *
+ * @returns Axios-compatible client
+ *
+ * @example
+ * ```typescript
+ * import { createAxiosCompat } from '@private.me/xbind/http-compat';
+ *
+ * const axios = createAxiosCompat();
+ *
+ * // Auto-upgrades to xBind if supported
+ * const response = await axios.get('https://api.example.com/data');
+ * console.log('Used xBind?', response.xbind?.used);
+ * console.log('Data:', response.data);
+ * ```
+ */
+function createAxiosCompat() {
+    async function request(config) {
+        // Normalize config
+        const cfg = typeof config === 'string' ? { url: config } : config;
+        const method = cfg.method?.toUpperCase() ?? 'GET';
+        const url = cfg.baseURL
+            ? new URL(cfg.url ?? '', cfg.baseURL).toString()
+            : cfg.url ?? '';
+        // Build headers
+        const headers = { ...cfg.headers };
+        // Build URL with query params
+        let finalUrl = url;
+        if (cfg.params) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(cfg.params)) {
+                params.append(key, String(value));
+            }
+            finalUrl = `${url}?${params.toString()}`;
+        }
+        // Build request body
+        let body;
+        if (cfg.data) {
+            if (typeof cfg.data === 'string') {
+                body = cfg.data;
+            }
+            else {
+                body = JSON.stringify(cfg.data);
+                headers['Content-Type'] = 'application/json';
+            }
+        }
+        // Convert to xfetch options
+        const xfetchOpts = {
+            method,
+            headers,
+            body,
+            timeout: cfg.timeout,
+            forceXBind: cfg.forceXBind,
+            disableXBind: cfg.disableXBind,
+        };
+        // Make request via xfetch
+        const response = await (0, xfetch_js_1.xfetch)(finalUrl, xfetchOpts);
+        // Parse response body based on responseType
+        let data;
+        const responseType = cfg.responseType ?? 'json';
+        switch (responseType) {
+            case 'json':
+                data = (await response.json());
+                break;
+            case 'text':
+                data = (await response.text());
+                break;
+            case 'blob':
+                data = (await response.blob());
+                break;
+            case 'arraybuffer':
+                data = (await response.arrayBuffer());
+                break;
+            default:
+                data = (await response.json());
+        }
+        // Validate status if custom validator provided
+        if (cfg.validateStatus && !cfg.validateStatus(response.status)) {
+            throw new Error(`Request failed with status ${response.status}`);
+        }
+        // Convert headers to object
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            data,
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+            config: cfg,
+            xbind: {
+                used: response.usedXBind,
+                protocol: response.transport.protocol,
+                latency: response.transport.latency,
+                peerDID: response.transport.peerDID,
+            },
+        };
+    }
+    // Convenience methods
+    async function get(url, config) {
+        return request({ ...config, url, method: 'GET' });
+    }
+    async function post(url, data, config) {
+        return request({ ...config, url, method: 'POST', data });
+    }
+    async function put(url, data, config) {
+        return request({ ...config, url, method: 'PUT', data });
+    }
+    async function patch(url, data, config) {
+        return request({ ...config, url, method: 'PATCH', data });
+    }
+    async function del(url, config) {
+        return request({ ...config, url, method: 'DELETE' });
+    }
+    return {
+        request,
+        get,
+        post,
+        put,
+        patch,
+        delete: del,
+    };
+}
+/**
+ * Create got-compatible HTTP client with xBind auto-upgrade
+ *
+ * Drop-in replacement for got that transparently upgrades to xBind.
+ *
+ * @returns Got-compatible client
+ *
+ * @example
+ * ```typescript
+ * import { createGotCompat } from '@private.me/xbind/http-compat';
+ *
+ * const got = createGotCompat();
+ *
+ * // Auto-upgrades to xBind if supported
+ * const response = await got('https://api.example.com/data', {
+ *   responseType: 'json',
+ * });
+ * console.log('Used xBind?', response.xbind?.used);
+ * console.log('Body:', response.body);
+ * ```
+ */
+function createGotCompat() {
+    async function got(url, options) {
+        // Normalize options
+        const opts = typeof url === 'string' ? { ...options, url } : url;
+        const method = opts.method?.toUpperCase() ?? 'GET';
+        const finalUrl = opts.url ?? '';
+        // Build headers
+        const headers = { ...opts.headers };
+        // Build URL with search params
+        let urlWithParams = finalUrl;
+        if (opts.searchParams) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(opts.searchParams)) {
+                params.append(key, String(value));
+            }
+            urlWithParams = `${finalUrl}?${params.toString()}`;
+        }
+        // Build request body
+        let body;
+        if (opts.json) {
+            body = JSON.stringify(opts.json);
+            headers['Content-Type'] = 'application/json';
+        }
+        else if (opts.body) {
+            // Convert Buffer to string for compatibility with xfetch
+            // SAFETY: After instanceof check, both branches produce string type
+            body = (opts.body instanceof Buffer ? opts.body.toString() : opts.body);
+        }
+        // Extract timeout
+        const timeout = typeof opts.timeout === 'number'
+            ? opts.timeout
+            : opts.timeout?.request;
+        // Convert to xfetch options
+        const xfetchOpts = {
+            method,
+            headers,
+            body,
+            timeout,
+            forceXBind: opts.forceXBind,
+            disableXBind: opts.disableXBind,
+        };
+        // Make request via xfetch
+        const response = await (0, xfetch_js_1.xfetch)(urlWithParams, xfetchOpts);
+        // Parse response body based on responseType
+        let responseBody;
+        const responseType = opts.responseType ?? 'text';
+        switch (responseType) {
+            case 'json':
+                responseBody = (await response.json());
+                break;
+            case 'text':
+                responseBody = (await response.text());
+                break;
+            case 'buffer':
+                const arrayBuffer = await response.arrayBuffer();
+                responseBody = Buffer.from(arrayBuffer);
+                break;
+            default:
+                responseBody = (await response.text());
+        }
+        // Convert headers to object
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            body: responseBody,
+            statusCode: response.status,
+            headers: responseHeaders,
+            url: response.url,
+            requestUrl: urlWithParams,
+            xbind: {
+                used: response.usedXBind,
+                protocol: response.transport.protocol,
+                latency: response.transport.latency,
+                peerDID: response.transport.peerDID,
+            },
+        };
+    }
+    // Convenience methods
+    got.get = (url, options) => got(url, { ...options, method: 'GET' });
+    got.post = (url, options) => got(url, { ...options, method: 'POST' });
+    got.put = (url, options) => got(url, { ...options, method: 'PUT' });
+    got.patch = (url, options) => got(url, { ...options, method: 'PATCH' });
+    got.delete = (url, options) => got(url, { ...options, method: 'DELETE' });
+    return got;
+}
+/**
+ * Wrap existing fetch implementation with xBind auto-upgrade
+ *
+ * Use this to upgrade an existing fetch instance (like node-fetch, cross-fetch, etc.)
+ *
+ * @param fetchImpl - Fetch implementation to wrap
+ * @returns Wrapped fetch with xBind support
+ *
+ * @example
+ * ```typescript
+ * import { wrapFetch } from '@private.me/xbind/http-compat';
+ * import nodeFetch from 'node-fetch';
+ *
+ * const fetch = wrapFetch(nodeFetch);
+ *
+ * // Uses xBind if supported, falls back to node-fetch
+ * const response = await fetch('https://api.example.com/data');
+ * ```
+ */
+function wrapFetch(fetchImpl) {
+    // Return xfetch (which already handles auto-upgrade and fallback)
+    // The original fetchImpl is not used because xfetch uses global fetch
+    return xfetch_js_1.xfetch;
+}