@private.me/xbind 1.2.0

package/dist-standalone/approval.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @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 type { Result } from '@private.me/shared';
+import type { PolicyConstraints } from './agent-call.js';
+/**
+ * Approval request options
+ */
+export interface ApprovalOptions {
+    /** Agent DID requesting approval */
+    readonly agentDid: string;
+    /** Scopes being requested (e.g., ["payments:createCharge", "invoices:create"]) */
+    readonly scopes: string[];
+    /** Policy limits to enforce */
+    readonly limits: PolicyConstraints['limits'];
+    /** Duration of approval (ISO 8601 duration or ms) */
+    readonly duration: string | number;
+    /** Human-readable description of what the agent will do */
+    readonly description?: string;
+    /** Metadata for audit logging */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Approval token (returned after user consent)
+ */
+export interface ApprovalToken {
+    /** Unique approval ID */
+    readonly id: string;
+    /** Agent DID this approval is for */
+    readonly agentDid: string;
+    /** Granted scopes */
+    readonly scopes: string[];
+    /** Granted limits */
+    readonly limits: PolicyConstraints['limits'];
+    /** Expiration timestamp (ms since epoch) */
+    readonly expiresAt: number;
+    /** When this approval was created */
+    readonly createdAt: number;
+    /** Whether this approval is still valid */
+    readonly valid: boolean;
+    /** JWT-style signature (Ed25519) */
+    readonly signature: string;
+}
+/**
+ * Approval result
+ */
+export interface ApprovalResult {
+    /** Whether user approved */
+    readonly approved: boolean;
+    /** Approval token (if approved) */
+    readonly token?: ApprovalToken;
+    /** Reason for denial (if not approved) */
+    readonly reason?: string;
+}
+/**
+ * Approval error codes
+ */
+export declare enum ApprovalErrorCode {
+    USER_DENIED = "APPROVAL_USER_DENIED",
+    TIMEOUT = "APPROVAL_TIMEOUT",
+    INVALID_DURATION = "APPROVAL_INVALID_DURATION",
+    SIGNATURE_FAILED = "APPROVAL_SIGNATURE_FAILED",
+    TOKEN_EXPIRED = "APPROVAL_TOKEN_EXPIRED",
+    TOKEN_REVOKED = "APPROVAL_TOKEN_REVOKED",
+    INVALID_TOKEN = "APPROVAL_INVALID_TOKEN"
+}
+/**
+ * Approval error
+ */
+export declare class ApprovalError extends Error {
+    readonly code: ApprovalErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: ApprovalErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Approval presenter (UI abstraction)
+ *
+ * Implementations display consent screen to user and return their decision.
+ * This allows different UIs (CLI, web, mobile) to plug in.
+ */
+export interface ApprovalPresenter {
+    /**
+     * Present approval request to user
+     *
+     * @param options - Approval options
+     * @returns User's decision
+     */
+    present(options: ApprovalOptions): Promise<Result<ApprovalResult, ApprovalError>>;
+}
+/**
+ * CLI approval presenter (prints to console, reads stdin)
+ * This is a legitimate CLI interface - console output is intentional
+ */
+export declare class CLIApprovalPresenter implements ApprovalPresenter {
+    present(options: ApprovalOptions): Promise<Result<ApprovalResult, ApprovalError>>;
+}
+/**
+ * Approval flow coordinator
+ *
+ * Orchestrates the consent flow: present to user → sign token → track expiry
+ */
+export declare class ApprovalFlow {
+    private readonly presenter;
+    private readonly tokens;
+    constructor(options?: {
+        readonly presenter?: ApprovalPresenter;
+    });
+    /**
+     * Request approval from user
+     *
+     * @param options - Approval request options
+     * @returns Approval result with token (if approved)
+     */
+    requestApproval(options: ApprovalOptions): Promise<Result<ApprovalResult, ApprovalError>>;
+    /**
+     * Verify an approval token
+     *
+     * @param tokenId - Token ID to verify
+     * @returns Token if valid, error otherwise
+     */
+    verifyToken(tokenId: string): Result<ApprovalToken, ApprovalError>;
+    /**
+     * Revoke an approval token
+     *
+     * @param tokenId - Token ID to revoke
+     */
+    revokeToken(tokenId: string): void;
+    /**
+     * Parse duration string to milliseconds
+     */
+    private parseDuration;
+    /**
+     * Generate a unique token ID
+     */
+    private generateTokenId;
+    /**
+     * Sign an approval token (stub - production would use Ed25519)
+     */
+    private signToken;
+}

package/dist-standalone/approval.js

@@ -0,0 +1,193 @@
+/**
+ * @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/auth.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Xlock auth challenge module for Agent SDK.
+ *
+ * Provides requestAuth(), respondToChallenge(), and onChallenge()
+ * functions that work with an Agent instance and the XBind gateway.
+ *
+ * These functions are also re-exported as thin methods on the Agent class.
+ */
+import type { Result, AuthRequest, AuthResult, IncomingAuthChallenge, AuthChallengeErrorCode } from '@private.me/shared';
+import type { Agent } from './agent.js';
+/** Options for the gateway connection used by auth functions. */
+export interface AuthGatewayOptions {
+    /** Gateway base URL (e.g. 'https://api.xail.io'). */
+    readonly gatewayUrl: string;
+    /** Bearer token for status polling (HMAC-SHA256 of sender DID). */
+    readonly accessToken: string;
+}
+/**
+ * Create an auth challenge and poll until the user responds.
+ *
+ * Sends a challenge via the XBind gateway, then polls the status
+ * endpoint until the challenge is approved, denied, or expires.
+ *
+ * @param agent - The Agent requesting authorization.
+ * @param request - Auth request details (recipient DID, action, metadata).
+ * @param gateway - Gateway connection options.
+ * @returns Auth result (approved/denied) or error.
+ */
+export declare function requestAuth(agent: Agent, request: AuthRequest, gateway: AuthGatewayOptions): Promise<Result<AuthResult, AuthChallengeErrorCode>>;
+/**
+ * Respond to an incoming auth challenge (approve or deny).
+ *
+ * Sends a signed response envelope to the gateway.
+ *
+ * @param agent - The Agent responding to the challenge.
+ * @param challengeId - The challenge ID to respond to.
+ * @param approved - Whether the user approved the challenge.
+ * @param gateway - Gateway connection options.
+ * @returns Success or error.
+ */
+export declare function respondToChallenge(agent: Agent, challengeId: string, approved: boolean, gateway: AuthGatewayOptions): Promise<Result<void, AuthChallengeErrorCode>>;
+/**
+ * Register a callback for incoming auth challenges via WebSocket.
+ *
+ * The callback fires when an `auth:challenge` message arrives
+ * over the gateway WebSocket connection.
+ *
+ * @param ws - The WebSocket connection to the gateway.
+ * @param callback - Handler for incoming challenges.
+ * @returns Cleanup function to unregister the listener.
+ */
+export declare function onChallenge(ws: {
+    addEventListener: (type: string, handler: (event: {
+        data: string;
+    }) => void) => void;
+    removeEventListener: (type: string, handler: (event: {
+        data: string;
+    }) => void) => void;
+}, callback: (challenge: IncomingAuthChallenge) => void): () => void;
+/**
+ * Generate a registration QR code URI for TOTP migration.
+ *
+ * Creates a `xlock://register` URI that replaces `otpauth://` for
+ * asymmetric DID-based registration.
+ *
+ * @param options - Registration options.
+ * @returns The registration URI string.
+ */
+export declare function generateRegistrationQR(options: {
+    readonly appName: string;
+    readonly appDid: string;
+    readonly registryUrl: string;
+    readonly callbackUrl: string;
+    readonly appIcon?: string;
+}): string;

package/dist-standalone/auth.js

@@ -0,0 +1,219 @@
+/**
+ * Xlock auth challenge module for Agent SDK.
+ *
+ * Provides requestAuth(), respondToChallenge(), and onChallenge()
+ * functions that work with an Agent instance and the XBind gateway.
+ *
+ * These functions are also re-exported as thin methods on the Agent class.
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { createSignedEnvelope } from './envelope.js';
+/** Default poll interval for challenge status. */
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+/** Default TTL for challenges (5 minutes). */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** Max poll iterations (TTL / pollInterval + safety margin). */
+const MAX_POLL_ITERATIONS = 200;
+/**
+ * Create an auth challenge and poll until the user responds.
+ *
+ * Sends a challenge via the XBind gateway, then polls the status
+ * endpoint until the challenge is approved, denied, or expires.
+ *
+ * @param agent - The Agent requesting authorization.
+ * @param request - Auth request details (recipient DID, action, metadata).
+ * @param gateway - Gateway connection options.
+ * @returns Auth result (approved/denied) or error.
+ */
+export async function requestAuth(agent, request, gateway) {
+    const ttlMs = request.ttlMs ?? DEFAULT_TTL_MS;
+    const pollIntervalMs = request.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    // Build the challenge payload
+    const payload = {
+        recipientDid: request.to,
+        action: request.action,
+        metadata: request.metadata ?? {},
+        ttlMs,
+    };
+    // Create a signed envelope wrapping the challenge request
+    const envelopeResult = await createSignedEnvelope({
+        senderDid: agent.did,
+        recipientDid: request.to,
+        scope: 'xlock:challenge',
+        plaintext: new TextEncoder().encode(JSON.stringify(payload)),
+        privateKey: agent.identity.privateKey,
+    });
+    if (!envelopeResult.ok) {
+        return err('INVALID_REQUEST');
+    }
+    // POST to gateway
+    let challengeId;
+    let expiresAt;
+    try {
+        const response = await fetch(`${gateway.gatewayUrl}/gateway/auth/challenge`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(envelopeResult.value),
+        });
+        if (response.status === 429)
+            return err('RATE_LIMITED');
+        if (!response.ok) {
+            const body = await response.json().catch(() => null);
+            const code = body
+                ?.error?.code;
+            return err(code ?? 'INVALID_REQUEST');
+        }
+        const data = await response.json();
+        challengeId = data.challengeId;
+        expiresAt = data.expiresAt;
+    }
+    catch {
+        return err('INVALID_REQUEST');
+    }
+    // Poll for status
+    return pollChallengeStatus(challengeId, expiresAt, pollIntervalMs, gateway);
+}
+/**
+ * Respond to an incoming auth challenge (approve or deny).
+ *
+ * Sends a signed response envelope to the gateway.
+ *
+ * @param agent - The Agent responding to the challenge.
+ * @param challengeId - The challenge ID to respond to.
+ * @param approved - Whether the user approved the challenge.
+ * @param gateway - Gateway connection options.
+ * @returns Success or error.
+ */
+export async function respondToChallenge(agent, challengeId, approved, gateway) {
+    const payload = {
+        challengeId,
+        approved,
+        timestamp: Date.now(),
+    };
+    // Create a signed envelope for the response
+    const envelopeResult = await createSignedEnvelope({
+        senderDid: agent.did,
+        recipientDid: agent.did, // Self-addressed (gateway verifies recipient match)
+        scope: 'xlock:respond',
+        plaintext: new TextEncoder().encode(JSON.stringify(payload)),
+        privateKey: agent.identity.privateKey,
+    });
+    if (!envelopeResult.ok) {
+        return err('INVALID_REQUEST');
+    }
+    try {
+        const response = await fetch(`${gateway.gatewayUrl}/gateway/auth/respond`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                ...envelopeResult.value,
+                // Include response fields at top level for the server
+                challengeId,
+                approved,
+                responseEnvelope: envelopeResult.value,
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => null);
+            const code = body
+                ?.error?.code;
+            return err(code ?? 'INVALID_REQUEST');
+        }
+        return ok(undefined);
+    }
+    catch {
+        return err('INVALID_REQUEST');
+    }
+}
+/**
+ * Register a callback for incoming auth challenges via WebSocket.
+ *
+ * The callback fires when an `auth:challenge` message arrives
+ * over the gateway WebSocket connection.
+ *
+ * @param ws - The WebSocket connection to the gateway.
+ * @param callback - Handler for incoming challenges.
+ * @returns Cleanup function to unregister the listener.
+ */
+export function onChallenge(ws, callback) {
+    const handler = (event) => {
+        try {
+            const msg = JSON.parse(event.data);
+            if (msg.type === 'auth:challenge' && msg.data) {
+                callback(msg.data);
+            }
+        }
+        catch {
+            // Skip non-JSON messages
+        }
+    };
+    ws.addEventListener('message', handler);
+    return () => ws.removeEventListener('message', handler);
+}
+/**
+ * Generate a registration QR code URI for TOTP migration.
+ *
+ * Creates a `xlock://register` URI that replaces `otpauth://` for
+ * asymmetric DID-based registration.
+ *
+ * @param options - Registration options.
+ * @returns The registration URI string.
+ */
+export function generateRegistrationQR(options) {
+    const params = new URLSearchParams({
+        app: options.appName,
+        did: options.appDid,
+        registry: options.registryUrl,
+        callback: options.callbackUrl,
+    });
+    if (options.appIcon)
+        params.set('icon', options.appIcon);
+    return `xlock://register?${params.toString()}`;
+}
+/** Poll the gateway for challenge status until resolved or expired. */
+async function pollChallengeStatus(challengeId, expiresAt, pollIntervalMs, gateway) {
+    for (let i = 0; i < MAX_POLL_ITERATIONS; i++) {
+        if (Date.now() > expiresAt) {
+            return err('CHALLENGE_EXPIRED');
+        }
+        await sleep(pollIntervalMs);
+        try {
+            const response = await fetch(`${gateway.gatewayUrl}/gateway/auth/status/${challengeId}`, {
+                headers: { Authorization: `Bearer ${gateway.accessToken}` },
+            });
+            if (!response.ok) {
+                if (response.status === 404)
+                    return err('CHALLENGE_NOT_FOUND');
+                continue; // Retry on transient errors
+            }
+            const data = await response.json();
+            if (data.status === 'approved') {
+                return ok({
+                    challengeId: data.challengeId,
+                    approved: true,
+                    respondedAt: data.respondedAt,
+                    envelope: data.envelope,
+                });
+            }
+            if (data.status === 'denied') {
+                return ok({
+                    challengeId: data.challengeId,
+                    approved: false,
+                    respondedAt: data.respondedAt,
+                });
+            }
+            if (data.status === 'expired') {
+                return err('CHALLENGE_EXPIRED');
+            }
+            // Still pending — continue polling
+        }
+        catch {
+            // Network error — continue polling
+        }
+    }
+    return err('CHALLENGE_TIMEOUT');
+}
+/** Promise-based sleep. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}