@envarai/envarpay 0.2.0-alpha.17 → 0.2.0-alpha.18

package/dist/commerce/external-runtime.js

@@ -0,0 +1,244 @@
+import { ExternalAgentOAuth } from "./external-oauth.js";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { join, dirname, resolve } from "node:path";
+import { readFileSync, lstatSync, chmodSync, mkdirSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { CommerceStore } from "./store.js";
+import { CommerceServer, bearerAuthenticator } from "./server.js";
+import { loadCommerceConfig } from "./config.js";
+import { ExternalAgentExecutor } from "./external-agent.js";
+import { ExternalAgentEvents, publicWebhook, } from "./external-events.js";
+import { ExternalAgentMcp, externalAgentSkill } from "./external-mcp.js";
+import { CredentialVault } from "./vault.js";
+import { CommerceError } from "./types.js";
+export function setupExternalAgent(directory, origin) {
+    directory = resolve(directory);
+    const u = new URL(origin);
+    if (u.protocol !== "https:" || u.origin !== origin)
+        throw new CommerceError("external_origin", "Provide the exact public HTTPS origin");
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const config = {
+        configVersion: 1,
+        agent: { id: "external-agent", name: "External Agent" },
+        paymentProfiles: {},
+        services: [
+            {
+                id: "text-answer",
+                name: "Bounded text answer",
+                revision: 1,
+                execution: { type: "a2a", cardUrl: origin + "/agent-card.json" },
+                contract: {
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            request: { type: "string", minLength: 1, maxLength: 2000 },
+                        },
+                        required: ["request"],
+                        additionalProperties: false,
+                    },
+                    deliverables: ["external-agent-result.txt"],
+                    targetDurationSeconds: 600,
+                    includedRevisions: 0,
+                },
+                offers: [
+                    {
+                        id: "free",
+                        pricing: { kind: "free" },
+                        collection: { kind: "none" },
+                    },
+                ],
+            },
+        ],
+    };
+    loadCommerceConfig(config);
+    const agentToken = randomBytes(32).toString("base64url"), buyerToken = randomBytes(32).toString("base64url");
+    const credentials = {
+        principal: "external-agent",
+        services: ["text-answer"],
+        agentTokens: { [agentToken]: "external-agent" },
+        callers: { [buyerToken]: "owner" },
+        vaultKeyFile: join(directory, "events.key"),
+    };
+    for (const [name, value] of Object.entries({
+        "seller.json": JSON.stringify(config, null, 2),
+        "credentials.json": JSON.stringify(credentials, null, 2),
+        "events.key": randomBytes(32),
+        "agent.token": agentToken,
+        "pairing.key": randomBytes(32).toString("base64url"),
+        "buyer.token": buyerToken,
+        "SKILL.md": externalAgentSkill,
+        "connection.json": JSON.stringify({
+            url: origin + "/services/text-answer/v1/offers/free/agent-card.json",
+            authToken: buyerToken,
+            mcpUrl: origin + "/mcp",
+        }),
+    }))
+        writeFileSync(join(directory, name), value, { mode: 0o600, flag: "wx" });
+    return {
+        directory,
+        cardUrl: origin + "/services/text-answer/v1/offers/free/agent-card.json",
+        mcpUrl: origin + "/mcp",
+        credentialsFile: join(directory, "credentials.json"),
+        paymentsEnabled: false,
+    };
+}
+export function serveExternalAgent(options) {
+    const privateBytes = (path) => {
+        const s = lstatSync(path);
+        if (!s.isFile() || s.isSymbolicLink() || s.mode & 0o077 || s.size > 65536)
+            throw new CommerceError("external_private_file", "Use private regular config/credential files");
+        return readFileSync(path);
+    };
+    const privateJson = (path) => JSON.parse(privateBytes(path).toString("utf8"));
+    const config = loadCommerceConfig(privateJson(options.configFile)), secret = privateJson(options.credentialsFile);
+    if (config.services.some((s) => s.execution.type !== "a2a" ||
+        s.offers.some((o) => o.pricing.kind !== "free")) ||
+        Object.keys(config.paymentProfiles).length)
+        throw new CommerceError("external_free_only", "External setup currently supports explicit free task acceptance only");
+    if (Object.keys(secret.agentTokens).some((token) => Object.hasOwn(secret.callers, token)))
+        throw new CommerceError("external_token_scope", "External Agent tokens must differ from buyer credentials");
+    const store = new CommerceStore(options.stateFile), executor = new ExternalAgentExecutor(store, secret.principal, secret.services), vault = new CredentialVault(join(dirname(options.stateFile), "event-secrets"), privateBytes(secret.vaultKeyFile));
+    const pairingFile = join(dirname(options.credentialsFile), "pairing.key"), oauth = new ExternalAgentOAuth(options.stateFile + ".oauth.sqlite3", options.origin, secret.principal, privateBytes(pairingFile).toString("utf8").trim());
+    const agentAuth = bearerAuthenticator(secret.agentTokens);
+    const eventsPath = options.stateFile + ".events.sqlite3", events = new ExternalAgentEvents(eventsPath, executor, vault, (url, body, headers) => publicWebhook(url, body, headers, options.callbackLookup));
+    chmodSync(eventsPath, 0o600);
+    const mcp = new ExternalAgentMcp(executor, events, async (r) => oauth.authenticate(r) ?? (await agentAuth(r)));
+    const server = new CommerceServer({
+        config,
+        store,
+        origin: options.origin,
+        authenticate: bearerAuthenticator(secret.callers),
+        execute: executor.execute,
+    });
+    const expected = new URL(options.origin).host;
+    async function externalA2a(request) {
+        const path = new URL(request.url).pathname;
+        let normalized = request;
+        if (request.method === "POST" && path.endsWith("/a2a")) {
+            const rawText = await request.text();
+            if (Buffer.byteLength(rawText) > 65536)
+                return Response.json({ error: "request_too_large" }, { status: 413 });
+            let raw;
+            try {
+                raw = JSON.parse(rawText);
+            }
+            catch {
+                return Response.json({ error: "invalid_json" }, { status: 400 });
+            }
+            if (raw.method === "SendMessage") {
+                const message = raw.params?.message;
+                if (message?.parts?.length === 1 &&
+                    typeof message.parts[0]?.text === "string" &&
+                    Object.keys(message.parts[0]).every((k) => ["text", "mediaType"].includes(k))) {
+                    const text = message.parts[0].text;
+                    // This opt-in external service advertises a bounded plain-text request.
+                    // A JSON-text request with exactly that schema is also accepted.
+                    let input = { request: text };
+                    try {
+                        const parsed = JSON.parse(text);
+                        if (parsed &&
+                            !Array.isArray(parsed) &&
+                            Object.keys(parsed).length === 1 &&
+                            typeof parsed.request === "string")
+                            input = parsed;
+                    }
+                    catch { }
+                    message.parts = [{ data: input }];
+                }
+                raw.params.configuration = {
+                    ...raw.params.configuration,
+                    returnImmediately: true,
+                };
+            }
+            normalized = new Request(request.url, {
+                method: "POST",
+                headers: request.headers,
+                body: JSON.stringify(raw),
+            });
+        }
+        const response = await server.handle(normalized);
+        if (response.status !== 200)
+            return response;
+        const value = await response.json();
+        if (request.method === "GET" && path.endsWith("/agent-card.json")) {
+            value.defaultInputModes = ["application/json", "text/plain"];
+        }
+        // Internally the completed dispatch queue waits for an external claim.
+        // A2A buyers see WORKING and can poll until this original Task completes.
+        for (const task of [value.result?.task, value.result]) {
+            if (task?.status?.state === "TASK_STATE_INPUT_REQUIRED" &&
+                task.metadata?.externalAgent) {
+                task.status.state = "TASK_STATE_WORKING";
+                delete task.status.message;
+            }
+        }
+        return Response.json(value, {
+            status: response.status,
+            headers: response.headers,
+        });
+    }
+    const http = createServer(async (req, res) => {
+        try {
+            if (req.headers.host !== expected) {
+                res.writeHead(421);
+                res.end();
+                return;
+            }
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers))
+                if (v !== undefined)
+                    headers.set(k, Array.isArray(v) ? v.join(",") : v);
+            const request = new Request(new URL(req.url ?? "/", options.origin), {
+                method: req.method,
+                headers,
+                ...(!["GET", "HEAD"].includes(req.method ?? "GET")
+                    ? { body: Readable.toWeb(req), duplex: "half" }
+                    : {}),
+            });
+            let response = await oauth.handle(request);
+            if (!response)
+                response =
+                    new URL(request.url).pathname === "/mcp"
+                        ? await mcp.handle(request)
+                        : await externalA2a(request);
+            if (response.status === 401 && new URL(request.url).pathname === "/mcp")
+                response = new Response(response.body, {
+                    status: 401,
+                    headers: {
+                        ...Object.fromEntries(response.headers),
+                        "WWW-Authenticate": oauth.challenge(),
+                    },
+                });
+            res.writeHead(response.status, Object.fromEntries(response.headers));
+            if (response.body)
+                Readable.fromWeb(response.body).pipe(res);
+            else
+                res.end();
+        }
+        catch {
+            if (!res.headersSent)
+                res.writeHead(500);
+            res.end('{"error":"request_failed"}');
+        }
+    });
+    http.requestTimeout = 30000;
+    http.headersTimeout = 15000;
+    http.listen(options.port, options.host);
+    events.start();
+    return {
+        http,
+        store,
+        events,
+        server,
+        close: async () => {
+            oauth.close();
+            await events.close();
+            server.stop();
+            await new Promise((resolve) => http.close(() => resolve()));
+            while (server.isRunning)
+                await new Promise((r) => setTimeout(r, 10));
+            store.close();
+        },
+    };
+}

package/dist/commerce/runtime.d.ts

@@ -8,3 +8,4 @@ export * from './http.js';
 export * from './x402.js';
 export * from './vault.js';
 export * from './chain.js';
+export * from './external-agent.js';

package/dist/commerce/runtime.js

@@ -8,3 +8,4 @@ export * from './http.js';
 export * from './x402.js';
 export * from './vault.js';
 export * from './chain.js';
+export * from './external-agent.js';

package/dist/commerce/store.d.ts

@@ -80,8 +80,18 @@ export declare class CommerceStore implements TaskStore {
     hasUnresolvedContinuation(orderId: string): boolean;
     acknowledgeRecoveredContinuations(orderId: string, task: Task): void;
     recoverInterruptedDispatches(): number;
+    prepareExternalTask(orderId: string, principal: string): void;
+    externalTasks(principal: string, services: readonly string[]): {
+        order: OrderRecord;
+        claimId: string;
+    }[];
+    claimExternalTask(taskId: string, principal: string, services: readonly string[]): {
+        order: OrderRecord;
+        claimId: string;
+    };
+    externalClaim(taskId: string, principal: string, claimId: string, services: readonly string[]): OrderRecord;
     private scope;
-    save(task: Task, context: ServerCallContext): Promise<void>;
+    save(task: Task, context: ServerCallContext, expectedOriginal?: Task): Promise<void>;
     load(taskId: string, context: ServerCallContext): Promise<Task | undefined>;
     list(params: ListTasksRequest, context: ServerCallContext): Promise<ListTasksResponse>;
     fingerprint(order: OrderRecord): string;

package/dist/commerce/store.js

@@ -97,7 +97,11 @@ export class CommerceStore {
       state TEXT NOT NULL CHECK(state IN ('ready','dispatching','done','unknown')), UNIQUE(order_id,message_id)
     );
     CREATE INDEX IF NOT EXISTS commerce_tasks_owner_tenant_updated ON commerce_tasks(owner,tenant,updated_at DESC,id);
-    CREATE INDEX IF NOT EXISTS commerce_continuations_order_state ON commerce_continuations(order_id,state);`);
+    CREATE INDEX IF NOT EXISTS commerce_continuations_order_state ON commerce_continuations(order_id,state);
+    CREATE TABLE IF NOT EXISTS commerce_external_claims(
+      order_id TEXT PRIMARY KEY REFERENCES commerce_orders(id),
+      principal TEXT NOT NULL, claim_id TEXT NOT NULL DEFAULT ''
+    );`);
     }
     migrateV1() {
         // Rebuild only the state constraint. Preserve original IDs, credentials and every payment row.
@@ -394,17 +398,47 @@ export class CommerceStore {
             return pending.length;
         });
     }
+    prepareExternalTask(orderId, principal) {
+        const order = this.order(this.db.prepare('SELECT * FROM commerce_orders WHERE id=?').get(orderId));
+        if (!order || !['confirmed', 'not_required'].includes(order.paymentState) || order.executionState !== 'dispatching')
+            throw new CommerceError('external_payment_required', 'Only a dispatched and payment-approved original order can be delegated');
+        const existing = this.db.prepare('SELECT principal FROM commerce_external_claims WHERE order_id=?').get(orderId);
+        if (existing && existing.principal !== principal)
+            throw new CommerceError('external_owner', 'Original execution belongs to another external agent');
+        this.db.prepare('INSERT OR IGNORE INTO commerce_external_claims(order_id,principal) VALUES (?,?)').run(orderId, principal);
+    }
+    externalTasks(principal, services) {
+        return this.db.prepare("SELECT o.*,c.claim_id FROM commerce_orders o JOIN commerce_external_claims c ON c.order_id=o.id WHERE c.principal=? AND o.payment_state IN ('confirmed','not_required') AND o.execution_state IN ('input_required','working') ORDER BY o.rowid LIMIT 100").all(principal).filter(r => services.includes(String(r.service_revision).split(':')[0])).map(r => ({ order: this.order(r), claimId: String(r.claim_id) }));
+    }
+    claimExternalTask(taskId, principal, services) {
+        return this.transaction(() => {
+            const row = this.db.prepare("SELECT o.*,c.claim_id FROM commerce_orders o JOIN commerce_external_claims c ON c.order_id=o.id WHERE o.task_id=? AND c.principal=? AND o.payment_state IN ('confirmed','not_required') AND o.execution_state IN ('input_required','working','completed','failed')").get(taskId, principal);
+            if (!row || !services.includes(String(row.service_revision).split(':')[0]))
+                throw new CommerceError('external_task', 'Original Task is outside this external agent scope');
+            const claimId = String(row.claim_id) || randomUUID();
+            this.db.prepare('UPDATE commerce_external_claims SET claim_id=? WHERE order_id=?').run(claimId, String(row.id));
+            return { order: this.order(row), claimId };
+        });
+    }
+    externalClaim(taskId, principal, claimId, services) {
+        const row = this.db.prepare("SELECT o.* FROM commerce_orders o JOIN commerce_external_claims c ON c.order_id=o.id WHERE o.task_id=? AND c.principal=? AND c.claim_id=? AND c.claim_id!='' AND o.payment_state IN ('confirmed','not_required')").get(taskId, principal, claimId);
+        if (!row || !services.includes(String(row.service_revision).split(':')[0]))
+            throw new CommerceError('external_claim', 'Claim does not identify an authorized original Task');
+        return this.order(row);
+    }
     scope(context) {
         if (!context.user?.isAuthenticated || !context.user.userName)
             throw new CommerceError('authentication_required', 'Authenticated task owner required');
         return { owner: context.user.userName, tenant: context.tenant ?? '' };
     }
-    async save(task, context) {
+    async save(task, context, expectedOriginal) {
         const scope = this.scope(context);
         this.transaction(() => {
             const current = this.db.prepare('SELECT owner,tenant,task_json FROM commerce_tasks WHERE id=?').get(task.id);
             if (current && (current.owner !== scope.owner || current.tenant !== scope.tenant))
                 throw new CommerceError('task_owner_conflict', 'Cannot replace another owner task');
+            if (expectedOriginal && current?.task_json !== JSON.stringify(Task.toJSON(expectedOriginal)))
+                throw new CommerceError('external_result_conflict', 'Original Task changed while preparing this result; read and recover it before retrying');
             const order = this.db.prepare('SELECT payment_state FROM commerce_orders WHERE task_id=?').get(task.id);
             if (order && !['confirmed', 'not_required'].includes(String(order.payment_state)))
                 throw new CommerceError('payment_required', 'Cannot publish task execution before payment');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/envarpay",
-  "version": "0.2.0-alpha.17",
+  "version": "0.2.0-alpha.18",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",
@@ -69,7 +69,8 @@
     "canonicalize": "2.1.0",
     "mppx": "0.13.1",
     "viem": "2.57.1",
-    "yaml": "2.8.2"
+    "yaml": "2.8.2",
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",