@envarai/envarpay 0.2.0-alpha.11 → 0.2.0-alpha.12

package/dist/commerce/agent-setup.d.ts

@@ -0,0 +1,18 @@
+interface Invitation {
+    version: 1;
+    agentId: string;
+    platformOrigin: string;
+    setupToken: string;
+}
+export declare function invitation(value: any): Invitation;
+export declare function agentSetup(options: {
+    file: string;
+    directory?: string;
+    python?: string;
+    home?: string;
+    container?: string;
+    origin?: string;
+    port?: number;
+    checkOnly?: boolean;
+}): Promise<void>;
+export {};

package/dist/commerce/agent-setup.js

@@ -0,0 +1,189 @@
+/** Agent-driven installation. Secrets stay in local files; receipts come from Envar. */
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { setupHermes, parseSetupBundle } from './setup.js';
+import { CommerceError } from './types.js';
+function privateJson(file) {
+    const s = lstatSync(file);
+    if (!s.isFile() || s.isSymbolicLink() || s.size > 16384 || (s.mode & 0o077))
+        throw new CommerceError('setup_private_file', 'Save the setup invitation in an owner-only file (chmod600).');
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+export function invitation(value) {
+    if (value?.version !== 1 || !/^[0-9a-f-]{36}$/.test(value.agentId) || !/^envar_setup_[A-Za-z0-9_-]{43}$/.test(value.setupToken))
+        throw new CommerceError('setup_invitation', 'Copy a fresh setup prompt.');
+    const url = new URL(value.platformOrigin);
+    if (url.protocol !== 'https:' || url.origin !== value.platformOrigin || url.username || url.password)
+        throw new CommerceError('setup_origin', 'Use the exact Envar HTTPS origin.');
+    return value;
+}
+async function request(invite, path, data) {
+    const r = await fetch(invite.platformOrigin + '/api/v1/agent-setup/' + path, { method: 'POST', redirect: 'error', headers: { Authorization: 'Bearer ' + invite.setupToken, 'Content-Type': 'application/json' }, body: JSON.stringify(data), signal: AbortSignal.timeout(45000) });
+    if (!r.ok)
+        throw new CommerceError('setup_' + path, `Envar ${path} returned ${r.status}. Check connection or copy a fresh prompt; do not report success.`);
+    const text = await r.text();
+    if (text.length > 65536)
+        throw new CommerceError('setup_response', 'Envar returned an oversized response.');
+    return JSON.parse(text);
+}
+async function freePort() {
+    const socket = createServer();
+    await new Promise((resolve, reject) => { socket.once('error', reject); socket.listen(0, '127.0.0.1', resolve); });
+    const port = socket.address().port;
+    await new Promise(resolve => socket.close(() => resolve()));
+    return port;
+}
+function save(file, data) { writeFileSync(file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600, flag: 'wx' }); }
+async function publicOrigin(root, port, agentId, supplied) {
+    if (supplied) {
+        const u = new URL(supplied);
+        if (u.protocol !== 'https:' || u.origin !== supplied)
+            throw Error('Use a public HTTPS origin');
+        return supplied;
+    }
+    // Use an available existing tunnel session, without deleting or rebinding any endpoint.
+    for (const apiPort of [4040, 4041, 4042, 4043]) {
+        try {
+            const api = `http://127.0.0.1:${apiPort}`;
+            const r = await fetch(api + '/api/tunnels', { signal: AbortSignal.timeout(1000) });
+            if (!r.ok)
+                continue;
+            const list = (await r.json());
+            const name = 'envarpay-' + agentId, addr = `http://127.0.0.1:${port}`;
+            const prior = list.tunnels?.find((t) => t.name === name);
+            if (prior) {
+                if (prior.config.addr !== addr)
+                    continue;
+                return prior.public_url;
+            }
+            if (list.tunnels?.length >= 3)
+                continue;
+            const created = await fetch(api + '/api/tunnels', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name, proto: 'http', addr, schemes: ['https'], inspect: false }), signal: AbortSignal.timeout(12000) });
+            if (created.ok)
+                return (await created.json()).public_url;
+        }
+        catch { }
+    }
+    // Outbound HTTPS works inside Docker too; never requires a Docker socket or host port mapping.
+    const log = join(root, 'tunnel.log');
+    if (existsSync(log))
+        privateLog(log);
+    const offset = existsSync(log) ? readFileSync(log, 'utf8').length : 0, fd = openSync(log, 'a', 0o600);
+    const tunnel = spawn('cloudflared', ['tunnel', '--url', `http://127.0.0.1:${port}`, '--no-autoupdate'], { detached: true, stdio: ['ignore', fd, fd] });
+    closeSync(fd);
+    let failed = false;
+    tunnel.on('error', () => { failed = true; });
+    tunnel.unref();
+    for (let i = 0; i < 45; i++) {
+        if (failed)
+            break;
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        const url = readFileSync(log, 'utf8').slice(offset).match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com\b/)?.[0];
+        if (url) {
+            writeFileSync(join(root, 'tunnel-process.json'), JSON.stringify({ pid: tunnel.pid, origin: url, temporary: true }), { mode: 0o600 });
+            return url;
+        }
+    }
+    if (tunnel.pid)
+        try {
+            tunnel.kill();
+        }
+        catch { }
+    throw new CommerceError('setup_https', 'Install cloudflared from its official distribution, or supply --origin with an existing HTTPS forwarder. Preserve other tunnels.');
+}
+function privateLog(file) { const s = lstatSync(file); if (!s.isFile() || s.isSymbolicLink() || (s.mode & 0o077))
+    throw new CommerceError('setup_private_file', 'Runtime log must be an owner-only regular file.'); }
+export async function agentSetup(options) {
+    const invite = invitation(privateJson(resolve(options.file)));
+    const profile = resolve(options.directory ?? join(homedir(), '.envarpay', invite.agentId));
+    const root = profile + '.onboarding';
+    if (options.checkOnly) {
+        const result = await request(invite, 'status', {});
+        if (result.agent_id !== invite.agentId)
+            throw new CommerceError('setup_identity', 'Receipt belongs to another Agent.');
+        console.log(JSON.stringify(result, null, 2));
+        if (result.status !== 'connected')
+            process.exitCode = 1;
+        return;
+    }
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    if (lstatSync(root).isSymbolicLink() || (lstatSync(root).mode & 0o077))
+        throw new CommerceError('setup_directory', 'Use a private directory owned by this user.');
+    const manifest = join(root, 'setup.json');
+    if (existsSync(manifest) && privateJson(manifest).agentId !== invite.agentId)
+        throw new CommerceError('setup_identity', 'This directory belongs to another Agent.');
+    const bundle = parseSetupBundle(await request(invite, 'claim', {}));
+    if (bundle.agentId !== invite.agentId || bundle.platformOrigin !== invite.platformOrigin)
+        throw new CommerceError('setup_identity', 'Envar returned another Agent identity.');
+    const bundleFile = join(root, 'bundle.json');
+    if (existsSync(bundleFile))
+        privateJson(bundleFile);
+    writeFileSync(bundleFile, JSON.stringify(bundle), { mode: 0o600 });
+    if (!existsSync(profile)) {
+        let settings = existsSync(manifest) ? privateJson(manifest) : undefined;
+        if (!settings) {
+            const port = options.port ?? await freePort();
+            const origin = await publicOrigin(root, port, invite.agentId, options.origin);
+            settings = { agentId: invite.agentId, port, origin };
+            save(manifest, settings);
+        }
+        await setupHermes({ file: bundleFile, directory: profile, python: options.python, home: options.home, container: options.container, automatic: settings });
+    }
+    if (lstatSync(profile).isSymbolicLink() || (lstatSync(profile).mode & 0o077))
+        throw new CommerceError('setup_directory', 'The runtime must be a private directory.');
+    const connection = privateJson(join(profile, 'connection.json'));
+    privateLog(join(profile, 'envar.token'));
+    const launcher = lstatSync(join(profile, 'start.mjs'));
+    if (!launcher.isFile() || launcher.isSymbolicLink() || (launcher.mode & 0o077))
+        throw new CommerceError('setup_private_file', 'Use the original private runtime launcher.');
+    if (connection.agentId !== invite.agentId)
+        throw new CommerceError('setup_identity', 'Existing runtime belongs to another Agent.');
+    const policy = privateJson(join(profile, 'envar.json')).policy;
+    if (policy.agentId !== invite.agentId || policy.platformOrigin !== invite.platformOrigin)
+        throw new CommerceError('setup_identity', 'Existing integration belongs to another Agent.');
+    const running = join(root, 'process.json');
+    let started = false;
+    if (existsSync(running))
+        try {
+            process.kill(privateJson(running).pid, 0);
+            started = true;
+        }
+        catch { }
+    if (started && readFileSync(join(profile, 'envar.token'), 'utf8') !== bundle.token)
+        throw new CommerceError('setup_running', 'Existing runtime uses an earlier credential. Stop its recorded process, keep its ledger, then retry this invitation.');
+    if (!started) {
+        privateLog(join(profile, 'envar.token'));
+        writeFileSync(join(profile, 'envar.token'), bundle.token, { mode: 0o600 });
+        const log = join(root, 'runtime.log');
+        if (existsSync(log))
+            privateLog(log);
+        const fd = openSync(log, 'a', 0o600), child = spawn(process.execPath, [join(profile, 'start.mjs')], { detached: true, stdio: ['ignore', fd, fd] });
+        closeSync(fd);
+        child.unref();
+        writeFileSync(running, JSON.stringify({ pid: child.pid }), { mode: 0o600 });
+    }
+    let result;
+    for (let attempt = 0; attempt < 12; attempt++) {
+        try {
+            result = await request(invite, 'connect', { agentId: invite.agentId, url: connection.url, authToken: connection.authToken });
+            if (result.status === 'connected')
+                break;
+        }
+        catch (e) {
+            if (attempt === 11)
+                throw e;
+        }
+        await new Promise(resolve => setTimeout(resolve, 3000));
+    }
+    result = await request(invite, 'status', {});
+    if (result.status !== 'connected' || result.agent_id !== invite.agentId || !result.verified_at)
+        throw new CommerceError('setup_unverified', 'Platform did not verify this setup. Keep files and report the blocker.');
+    const output = { ...result, local_directory: profile, receipt_file: join(root, 'receipt.json'), scope: 'connected; not published; no payment', restart: `node ${JSON.stringify(join(profile, 'start.mjs'))}`, temporary_tunnel: !options.origin, automatic_restart: false };
+    if (existsSync(join(root, 'receipt.json')))
+        privateJson(join(root, 'receipt.json'));
+    writeFileSync(join(root, 'receipt.json'), JSON.stringify(output, null, 2) + '\n', { mode: 0o600 });
+    console.log(JSON.stringify(output, null, 2));
+}

package/dist/commerce/cli.js

@@ -24,14 +24,15 @@ import { inspectLedger, inspectLocalAlerts } from './operations.js';
 import { setupHermes } from './setup.js';
 import { SkillDiscovery } from './discovery.js';
 import { upgradeDiscovery, configurePayments } from './configure.js';
+import { agentSetup } from './agent-setup.js';
 const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         config: { type: 'string' }, service: { type: 'string' }, offer: { type: 'string' }, origin: { type: 'string' },
         version: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, state: { type: 'string' }, credentials: { type: 'string' }, host: { type: 'string' },
         port: { type: 'string' }, directory: { type: 'string' }, 'envar-config': { type: 'string' }, 'envar-credentials': { type: 'string' },
         after: { type: 'string' }, limit: { type: 'string' }, 'refund-review': { type: 'boolean' }, alerts: { type: 'boolean' }, 'fail-on-alert': { type: 'boolean' }, 'integration-state': { type: 'string' }, 'no-integration': { type: 'boolean' },
-        file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' },
+        file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' }, check: { type: 'boolean' },
     } });
-const usage = 'envarpay upgrade --directory DIR [--hermes-home PATH] | payments --directory DIR --file receiving.json\nenvarpay setup --file envar-setup.json [--docker-container NAME | --python PATH] [--hermes-home PATH] [--directory DIR]\ninit --directory DIR | inspect --state DB [--after ROW --limit 100 --refund-review] [--alerts --config buyer-policy.json --integration-state DB/--no-integration --fail-on-alert] | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
+const usage = 'envarpay onboard --file invitation.json [--check] [--python PATH] [--docker-container NAME] [--hermes-home PATH] [--origin HTTPS_ORIGIN]\nenvarpay upgrade --directory DIR [--hermes-home PATH] | payments --directory DIR --file receiving.json\nenvarpay setup --file envar-setup.json [--docker-container NAME | --python PATH] [--hermes-home PATH] [--directory DIR]\ninit --directory DIR | inspect --state DB [--after ROW --limit 100 --refund-review] [--alerts --config buyer-policy.json --integration-state DB/--no-integration --fail-on-alert] | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
 const closers = [];
 function privateFile(path) {
     const stat = lstatSync(path);
@@ -91,6 +92,12 @@ async function run() {
         return;
     }
     const command = positionals[0];
+    if (command === 'onboard') {
+        if (!values.file)
+            throw new CommerceError('setup_file', 'Save the private invitation and pass --file PATH.');
+        await agentSetup({ file: values.file, directory: values.directory, python: values.python, home: values['hermes-home'], container: values['docker-container'], origin: values.origin, port: values.port ? port(4020) : undefined, checkOnly: values.check });
+        return;
+    }
     if (command === 'upgrade' && values.directory) {
         upgradeDiscovery(values.directory, values['hermes-home']);
         return;

package/dist/commerce/setup.d.ts

@@ -15,4 +15,8 @@ export declare function setupHermes(options: {
     container?: string;
     python?: string;
     home?: string;
+    automatic?: {
+        port: number;
+        origin: string;
+    };
 }): Promise<void>;

package/dist/commerce/setup.js

@@ -69,18 +69,16 @@ export async function setupHermes(options) {
     const bundle = parseSetupBundle(JSON.parse(readFileSync(file, "utf8")));
     if (options.container && !CONTAINER.test(options.container))
         throw new CommerceError("setup_container", "Use a Docker container name");
-    if (!process.stdin.isTTY)
+    if (!process.stdin.isTTY && !options.automatic)
         throw new CommerceError("setup_terminal", "Run setup in an interactive terminal to select skills");
     chmodSync(file, 0o600);
-    const prompt = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
+    const prompt = options.automatic ? undefined : createInterface({ input: process.stdin, output: process.stdout });
+    const output = options.automatic ? (..._args) => { } : console.log;
     const ask = async (label, fallback = "") => (await prompt.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim() || fallback;
     let staging;
     try {
-        console.log(`\nConnect ${bundle.agentName} to ${bundle.platformOrigin}\nModel credentials and tasks remain on this machine. Start with free services; no wallet is created.\n`);
-        if ((await ask("Continue? (yes/no)", "no")).toLowerCase() !== "yes")
+        output(`\nConnect ${bundle.agentName} to ${bundle.platformOrigin}\nModel credentials and tasks remain on this machine. Start with free services; no wallet is created.\n`);
+        if (!options.automatic && (await ask("Continue? (yes/no)", "no")).toLowerCase() !== "yes")
             return;
         const directory = resolve(options.directory ?? join(homedir(), ".envarpay", bundle.agentId));
         if (existsSync(directory))
@@ -105,6 +103,18 @@ export async function setupHermes(options) {
             if (!python)
                 throw new CommerceError("setup_runtime", "No compatible Hermes interpreter found in this container. Update Hermes or pass --python PATH.");
         }
+        if (!python && options.automatic) {
+            for (const candidate of [process.env.VIRTUAL_ENV && join(process.env.VIRTUAL_ENV, "bin/python"), "/opt/hermes-latest/bin/python", "/opt/hermes/.venv/bin/python", join(homedir(), "hermes-agent/.venv/bin/python"), "python3"].filter(Boolean)) {
+                try {
+                    execFileSync(candidate, ["-c", compatibility], { stdio: "pipe", timeout: 30000 });
+                    python = candidate;
+                    break;
+                }
+                catch { }
+            }
+            if (!python)
+                throw new CommerceError("setup_runtime", "No compatible Hermes Python found. Pass its executable using --python.");
+        }
         python ??= await ask("Hermes Python executable", join(homedir(), "hermes-agent", ".venv", "bin", "python"));
         const probeSource = readFileSync(new URL("../../examples/hermes-setup-probe.py", import.meta.url), "utf8");
         let probe;
@@ -134,25 +144,25 @@ export async function setupHermes(options) {
             throw new CommerceError("setup_model", "Could not read Hermes. Check the container/Python path and configure an OpenAI-compatible model in Hermes first.");
         }
         const candidates = probe.skills.filter((s) => s.textPackage && ID.test(s.name));
-        console.log(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
-        candidates.forEach((skill, i) => console.log(`${i + 1}. ${skill.name} — ${skill.description.replace(/[\r\n\x1b]/g, " ").slice(0, 160)}`));
-        console.log('Newly installed Skills will be discovered privately. Enable each one from the Envar service page after reviewing text-only compatibility.');
-        const selected = (await ask("Optional: enable existing text Skills now (comma separated, Enter to skip)"))
+        output(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
+        candidates.forEach((skill, i) => output(`${i + 1}. ${skill.name} — ${skill.description.replace(/[\r\n\x1b]/g, " ").slice(0, 160)}`));
+        output('Newly installed Skills will be discovered privately. Enable each one from the Envar service page after reviewing text-only compatibility.');
+        const selected = (options.automatic ? "" : await ask("Optional: enable existing text Skills now (comma separated, Enter to skip)"))
             .split(",")
             .map((s) => s.trim()).filter(Boolean);
         if (selected.length > 32 ||
             new Set(selected).size !== selected.length ||
             selected.some((name) => !candidates.some((s) => s.name === name)))
             throw new CommerceError("setup_skills", "Choose installed skill names from the list");
-        console.log("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Hermes skills are preserved; a service copy is created.");
+        output("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Hermes skills are preserved; a service copy is created.");
         if (selected.length &&
             (await ask("Do these selected skills work with text input and text output only? (yes/no)", "no")).toLowerCase() !== "yes")
             return;
-        const port = Number(await ask("Local service port", "4020"));
+        const port = options.automatic?.port ?? Number(await ask("Local service port", "4020"));
         if (!Number.isInteger(port) || port < 1024 || port > 65535)
             throw new CommerceError("setup_port", "Choose a local port from 1024 to 65535");
         let origin;
-        const tunnelMode = await ask("Public HTTPS: use an existing ngrok session or your own reverse proxy? (ngrok/url)", "ngrok");
+        const tunnelMode = options.automatic ? "url" : await ask("Public HTTPS: use an existing ngrok session or your own reverse proxy? (ngrok/url)", "ngrok");
         if (tunnelMode === "ngrok") {
             const api = new URL(await ask("Local ngrok API", "http://127.0.0.1:4040"));
             if (api.protocol !== "http:" ||
@@ -192,7 +202,7 @@ export async function setupHermes(options) {
             }
         }
         else if (tunnelMode === "url") {
-            origin = await ask(`Public HTTPS origin (forward to http://127.0.0.1:${port})`);
+            origin = options.automatic?.origin ?? await ask(`Public HTTPS origin (forward to http://127.0.0.1:${port})`);
         }
         else
             throw new CommerceError("setup_tunnel", "Choose ngrok or url");
@@ -334,10 +344,10 @@ export async function setupHermes(options) {
         writeFileSync(join(staging, "README.md"), `# ${bundle.agentName}\n\nStart: node ${JSON.stringify(start)}\n\nKeep the terminal, Hermes, and HTTPS tunnel running. Import connection.json in the Envar setup page, then check the connection. Choose a skill and save a free service. Request publication; this process applies the selected service automatically. Return to Envar and check/publish.\n\nOnly free service updates are authorized. Receiving and payment setup is separate. Platform token expires ${bundle.expiresAt}. Keep the original files and ledger when restarting.\n`, { mode: 0o600, flag: "wx" });
         renameSync(staging, directory);
         staging = undefined;
-        console.log(`\nReady. Start the local service:\n${process.execPath} ${JSON.stringify(start)}\n\nThen import this connection file in Envar:\n${join(directory, "connection.json")}\n\nKeep the service and HTTPS tunnel online. No task or payment was performed.`);
+        output(`\nReady. Start the local service:\n${process.execPath} ${JSON.stringify(start)}\n\nThen import this connection file in Envar:\n${join(directory, "connection.json")}\n\nKeep the service and HTTPS tunnel online. No task or payment was performed.`);
     }
     finally {
-        prompt.close();
+        prompt?.close();
         if (staging)
             rmSync(staging, { recursive: true, force: true });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/envarpay",
-  "version": "0.2.0-alpha.11",
+  "version": "0.2.0-alpha.12",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",