@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/scripts/test-package.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MPL-2.0
+// Verify the archive consumers receive, without a sibling repository or local Wallet build.
+import {execFileSync} from 'node:child_process';
+import {mkdtemp,mkdir,readFile,copyFile,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {dirname,join,resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+const source=fileURLToPath(new URL('..',import.meta.url));
+const output=resolve(process.argv[2] || 'artifacts/npm');
+await mkdir(output,{recursive:true});
+const root=await mkdtemp(join(tmpdir(),'agentpay-user-package-'));
+const env={...process.env,HOME:join(root,'home'),XDG_STATE_HOME:join(root,'state'),PATH:dirname(process.execPath)+':'+process.env.PATH};
+for(const name of Object.keys(env)) if(name.startsWith('AGENTPAY_') || ['NODE_OPTIONS','NODE_PATH'].includes(name)) delete env[name];
+const run=(file,args,cwd)=>execFileSync(file,args,{cwd,env,encoding:'utf8',timeout:180000,maxBuffer:8*1024*1024});
+try {
+ await mkdir(env.HOME,{mode:0o700});
+ const packed=JSON.parse(run('npm',['pack','--ignore-scripts','--json','--pack-destination',output],source))[0];
+ const paths=packed.files.map(x=>x.path);
+ for(const name of ['LICENSE','NOTICE.md','SECURITY.md','scripts/agentpay-cli.mjs','scripts/update.mjs','src/index.mjs'])
+  if(!paths.includes(name))throw Error('Missing package file: '+name);
+ if(paths.some(x=>x.startsWith('test/') || x.startsWith('node_modules/') || /(?:^|\/)\.env(?:\.|$)|\.keystore\.json$|\.token$|\.log$/.test(x)))throw Error('Unexpected private/test material in archive');
+ const archive=join(output,packed.filename),consumer=join(root,'consumer');
+ await mkdir(consumer);
+ run('npm',['install','--ignore-scripts','--no-audit','--no-fund',archive],consumer);
+ const installed=join(consumer,'node_modules/@c4roa0/agentpay-user');
+ const help=run(join(consumer,'node_modules/.bin/agentpay'),['help'],consumer);
+ if(!help.includes('update [-f]') || !help.includes('policy help'))throw Error('Installed command unavailable');
+ await mkdir(join(installed,'test'));
+ await copyFile(join(source,'test/local-services-process.test.mjs'),join(installed,'test/local-services-process.test.mjs'));
+ console.log(run(process.execPath,['--test','test/local-services-process.test.mjs'],installed));
+ console.log('Verified archive: '+archive);
+ console.log('SHA256: '+createHash('sha256').update(await readFile(archive)).digest('hex'));
+} finally {await rm(root,{recursive:true,force:true});}

package/scripts/unlock.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { controlWallet } from "../src/wallet-control.mjs";
+try {
+  process.exitCode = await controlWallet("unlock");
+} catch {
+  console.error(
+    "Could not start Wallet unlock. Check your local installation.",
+  );
+  process.exitCode = 1;
+}

package/scripts/update.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MPL-2.0
+import { updateFromNpm } from '../src/npm-update.mjs';
+const args=process.argv.slice(2);
+if(args.length > 1 || (args.length === 1 && args[0] !== '-f')) {
+  console.error('Usage: agentpay update [-f]'); process.exitCode=2;
+} else process.exitCode=await updateFromNpm({force:args[0] === '-f'});

package/scripts/user-setup.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import {
+  confirmDemoUnlockSecret,
+  readHiddenTerminal,
+} from "../src/demo-unlock-secret.mjs";
+import { createInterface } from "node:readline/promises";
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { checkLocalInstallation } from "../src/install-preflight.mjs";
+import {
+  inspectLocalUserSetup,
+  runUserSetupGuide,
+} from "../src/user-setup-guide.mjs";
+try {
+  const args = process.argv.slice(2),
+    demo = args[0] === "--demo";
+  if (args[0] === "--guided") {
+    if (args.length > 2 || (args[1] && !isAbsolute(args[1])))
+      throw Error("Usage: user-setup.mjs --guided [ABSOLUTE_PRIVATE_DATA_DIR]");
+    if (!process.stdin.isTTY)
+      throw Error("Run the setup guide in an interactive terminal.");
+    const { resolveUserDataDir } = await import(
+      "../src/local-data-directory.mjs"
+    );
+    const { runGuidedEntry } = await import("../src/guided-setup.mjs");
+    process.exit(
+      await runGuidedEntry({
+        userDir: fileURLToPath(new URL("..", import.meta.url)),
+        dataDir: await resolveUserDataDir({ argument: args[1] }),
+      }),
+    );
+  }
+
+  if (["--config", "--anvil"].includes(args[0])) {
+    if (args.length !== 3 || !isAbsolute(args[1]) || !isAbsolute(args[2]))
+      throw Error(
+        "Usage: user-setup.mjs --config ABSOLUTE_PRIVATE_DATA_DIR ABSOLUTE_CONFIG_JSON",
+      );
+    if (!process.stdin.isTTY)
+      throw Error("Run the setup guide in an interactive terminal.");
+    const preflight = await checkLocalInstallation({
+      userDir: fileURLToPath(new URL("..", import.meta.url)),
+      dataDir: args[1],
+    });
+    if (!preflight.ok) {
+      for (const item of preflight.checks.filter(
+        (item) => item.status === "failed",
+      ))
+        console.error(`${item.message}. ${item.fix || ""}`);
+      process.exitCode = 1;
+    } else {
+      const { runAnvilOnboarding } = await import(
+        "../src/anvil-onboarding.mjs"
+      );
+      const ask = async (prompt) => {
+        const terminal = createInterface({
+          input: process.stdin,
+          output: process.stderr,
+        });
+        try {
+          return await terminal.question(prompt);
+        } finally {
+          terminal.close();
+        }
+      };
+      const config = JSON.parse(await readFile(args[2], "utf8"));
+      if (
+        args[0] === "--anvil" &&
+        (config.mode !== "private-anvil" || config.chainId !== 31337)
+      )
+        throw Error("PRIVATE_ANVIL_CONFIG_REQUIRED");
+      const result = await runAnvilOnboarding({
+        dataDir: args[1],
+        config,
+        ask,
+        write: (value) => process.stdout.write(`${value}\n`),
+      });
+      process.exit(
+        result?.completed === false && result.stage !== "quit" ? 1 : 0,
+      );
+    }
+    if (!preflight.ok) process.exit(1);
+  }
+  if (
+    demo
+      ? args.length !== 1
+      : !args[0] || !isAbsolute(args[0]) || args.length > 2
+  )
+    throw Error(
+      "Usage: user-setup.mjs --demo | ABSOLUTE_PRIVATE_DATA_DIR [PUBLIC_DEPLOYMENT_JSON]",
+    );
+  if (!process.stdin.isTTY)
+    throw Error("Run the setup guide in an interactive terminal.");
+  const ask = async (prompt) => {
+    const terminal = createInterface({
+      input: process.stdin,
+      output: process.stderr,
+    });
+    try {
+      return await terminal.question(prompt);
+    } finally {
+      terminal.close();
+    }
+  };
+  const write = (text) => process.stdout.write(`${text}\n`);
+  let demoInitialized = false;
+  await runUserSetupGuide({
+    demo,
+    ask,
+    write,
+    check: () =>
+      demo
+        ? { ok: true }
+        : checkLocalInstallation({
+            userDir: fileURLToPath(new URL("..", import.meta.url)),
+            dataDir: args[0],
+          }),
+    state: () =>
+      demo
+        ? {
+            stage: demoInitialized ? "initialized" : "not_initialized",
+            delegate: demoInitialized ? `0x${"5".repeat(40)}` : null,
+            policyStatus: "not_configured",
+            runtimeStatus: "not_checked",
+          }
+        : inspectLocalUserSetup(args[0]),
+    initialize: async () => {
+      if (demo) {
+        write(
+          "\n------------------------------------------------------------\nSet your Wallet unlock secret\n------------------------------------------------------------",
+        );
+        await confirmDemoUnlockSecret({
+          readHidden: readHiddenTerminal,
+          write,
+        });
+        write(
+          "\n------------------------------------------------------------\nPrepare local runtime access\n------------------------------------------------------------\n  Real setup saves a local access credential automatically.\n  Demo: skipped; no credential or file is created.",
+        );
+        demoInitialized = true;
+        return;
+      }
+      const child = spawn(
+        process.execPath,
+        [
+          fileURLToPath(new URL("./setup-local.mjs", import.meta.url)),
+          "install",
+          args[0],
+        ],
+        { stdio: "inherit" },
+      );
+      const code = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", resolve);
+      });
+      if (code !== 0)
+        throw Error(
+          "Initialization did not finish. Existing state was preserved; inspect and resume.",
+        );
+    },
+    preview: async (delegate, options = {}) => {
+      if (!demo && !args[1]) {
+        write(
+          "Provide a trusted public deployment JSON as the second argument to preview authorization. No Policy was changed.",
+        );
+        return;
+      }
+      const { runPolicyTerminalGuide } = await import(
+        "../src/policy-terminal-guide.mjs"
+      );
+      const deployment = demo
+        ? {
+            chainId: 31337,
+            rpcUrl: "http://127.0.0.1:8545",
+            module: `0x${"1".repeat(40)}`,
+            token: `0x${"2".repeat(40)}`,
+            factory: `0x${"3".repeat(40)}`,
+            registry: `0x${"4".repeat(40)}`,
+            tokenDecimals: 6,
+            source: "Demo data, not an actual deployment",
+          }
+        : JSON.parse(await readFile(args[1], "utf8"));
+      return await runPolicyTerminalGuide({
+        deployment,
+        delegate,
+        demo,
+        ask,
+        write,
+        ...options,
+        inspect: async (plan) => {
+          const { JsonRpcProvider } = await import("ethers");
+          const { inspectSafePolicy } = await import(
+            "../src/safe-policy-plan.mjs"
+          );
+          const rpc = new JsonRpcProvider(plan.rpcUrl);
+          let timer;
+          try {
+            return await Promise.race([
+              inspectSafePolicy(rpc, plan),
+              new Promise((_, reject) => {
+                timer = setTimeout(() => reject(Error("timeout")), 10000);
+              }),
+            ]);
+          } finally {
+            clearTimeout(timer);
+            rpc.destroy();
+          }
+        },
+      });
+    },
+  });
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/verify-npm-release.mjs

@@ -0,0 +1,32 @@
+// Check public registry data only. Never retries publication after an uncertain result.
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const [archive, version] = process.argv.slice(2);
+if (!archive || !/^\d+\.\d+\.\d+$/.test(version ?? '')) {
+  throw new Error('Usage: node scripts/verify-npm-release.mjs ARCHIVE VERSION');
+}
+const integrity = 'sha512-' + createHash('sha512')
+  .update(await readFile(archive)).digest('base64');
+const url = `https://registry.npmjs.org/@c4roa0%2fagentpay-user/${version}`;
+for (let attempt = 1; attempt <= 10; attempt++) {
+  let metadata;
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(15000) });
+    if (response.ok) metadata = await response.json();
+    else console.log(`Registry check ${attempt}/10: HTTP ${response.status}`);
+  } catch {
+    console.log(`Registry check ${attempt}/10: request unavailable`);
+  }
+  if (metadata) {
+    if (metadata.name !== '@c4roa0/agentpay-user' || metadata.version !== version ||
+        metadata.dist?.integrity !== integrity) {
+      throw new Error('Public package identity or integrity differs from the built archive.');
+    }
+    console.log(`Verified public package @c4roa0/agentpay-user@${version}.`);
+    process.exit(0);
+  }
+  if (attempt < 10) await delay(Math.min(5000 * 2 ** (attempt - 1), 60000));
+}
+throw new Error('Publication may already be accepted. Registry verification is pending; do not republish.');

package/src/active-skill.mjs

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import {
+  readFile,
+  lstat,
+  realpath,
+  writeFile,
+  rename,
+  unlink,
+} from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  parseSkillBundle,
+  bundleDigest,
+  skillArchiveLimits,
+} from "./skill-bundle.mjs";
+import { parseServicePackage } from "./skill-package.mjs";
+async function privateFile(path, maxBytes = 262144) {
+  const st = await lstat(path);
+  if (
+    !st.isFile() ||
+    st.isSymbolicLink() ||
+    st.uid !== process.getuid() ||
+    st.mode & 0o077
+  )
+    throw new Error("SKILL_FILE_PERMISSIONS_INVALID");
+  if (st.size > maxBytes) throw new Error("SKILL_FILE_TOO_LARGE");
+  return readFile(path);
+}
+export async function inspectInstalledBundle(directory) {
+  const dir = resolve(directory);
+  if ((await realpath(dir)) !== dir)
+    throw new Error("SKILL_SYMLINK_PATH_INVALID");
+  const original = parseSkillBundle(
+    await privateFile(
+      join(dir, "publisher.zip"),
+      skillArchiveLimits.compressed,
+    ),
+  );
+  const receipt = JSON.parse(await privateFile(join(dir, "installation.json")));
+  if (
+    receipt.format !== "agentpay.skill-installation.v1" ||
+    receipt.sha256 !== original.sha256
+  )
+    throw new Error("SKILL_INSTALLATION_RECEIPT_MISMATCH");
+  const files = {};
+  const hashes = {};
+  let locallyModified = false;
+  for (const name of Object.keys(original.files)) {
+    const path = join(dir, name);
+    if ((await realpath(path)) !== path)
+      throw new Error("SKILL_SYMLINK_PATH_INVALID");
+    files[name] = await privateFile(path, skillArchiveLimits.file);
+    hashes[name] = bundleDigest(files[name]);
+    if (!files[name].equals(original.files[name])) locallyModified = true;
+  }
+  const manifest = JSON.parse(files[original.root + "agentpay.json"]);
+  if (JSON.stringify(manifest) !== JSON.stringify(original.manifest))
+    throw Error("SKILL_MANIFEST_INVALID");
+  const reference = original.services.main;
+  if (!reference) throw Error("TEST_SERVICE_REFERENCE_REQUIRED");
+  const service = parseServicePackage(Buffer.from(JSON.stringify(reference)));
+  return {
+    directory: dir,
+    sha256: original.sha256,
+    locallyModified,
+    hashes,
+    service,
+    publication: receipt.publication ?? null,
+  };
+}
+export async function loadActiveSkill(path) {
+  const selected = JSON.parse(await privateFile(path));
+  if (
+    selected.version !== "agentpay.active-skill.v1" ||
+    typeof selected.directory !== "string"
+  )
+    throw new Error("SKILL_SELECTION_INVALID");
+  const current = await inspectInstalledBundle(selected.directory);
+  if (
+    current.sha256 !== selected.sha256 ||
+    JSON.stringify(current.hashes) !== JSON.stringify(selected.hashes)
+  )
+    throw new Error("SKILL_CHANGED_RESELECT_REQUIRED");
+  return {
+    ...current.service,
+    bundle: {
+      directory: current.directory,
+      sha256: current.sha256,
+      filesHash: bundleDigest(Buffer.from(JSON.stringify(current.hashes))),
+      locallyModified: current.locallyModified,
+    },
+  };
+}
+export async function selectInstalledBundle(
+  dataDir,
+  directory,
+  expectedHashes = null,
+) {
+  const runtime = join(resolve(dataDir), "runtime");
+  const dir = resolve(directory);
+  if (dirname(dir) !== join(runtime, "skill-bundles"))
+    throw new Error("SKILL_NOT_IN_USER_INSTALL_DIRECTORY");
+  const info = await lstat(runtime);
+  if (
+    !info.isDirectory() ||
+    info.isSymbolicLink() ||
+    info.uid !== process.getuid() ||
+    info.mode & 0o077
+  )
+    throw new Error("PRIVATE_RUNTIME_REQUIRED");
+  const current = await inspectInstalledBundle(dir);
+  if (
+    expectedHashes &&
+    JSON.stringify(expectedHashes) !== JSON.stringify(current.hashes)
+  )
+    throw new Error("SKILL_CHANGED_DURING_CONFIRMATION");
+  const selected = {
+    version: "agentpay.active-skill.v1",
+    directory: dir,
+    sha256: current.sha256,
+    hashes: current.hashes,
+  };
+  const path = join(runtime, "active-skill.json");
+  let existing = null;
+  try {
+    existing = JSON.parse(await privateFile(path));
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  if (JSON.stringify(existing) === JSON.stringify(selected))
+    return { changed: false, path, ...current };
+  // This file selects only the official test material. Runtime binds each call
+  // independently. Never replace material while a test checkpoint still refers to it.
+  try {
+    await lstat(join(runtime, "model-ack-smoke.json"));
+    throw Error("TEST_SELECTION_REQUIRES_CHECKPOINT_REVIEW");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, JSON.stringify(selected) + "\n", {
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temp, path);
+  } finally {
+    await unlink(temp).catch((e) => {
+      if (e.code !== "ENOENT") throw e;
+    });
+  }
+  return { changed: true, path, ...current };
+}
+// Retained checkpoint filename selects official test material only.
+export async function installedSkillPath(dataDir) {
+  return join(dataDir, "runtime", "active-skill.json");
+}

package/src/anvil-onboarding-state.mjs

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MPL-2.0
+// This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+// If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
+import { createHash } from "node:crypto";
+import { hashPrivateRequest } from "@c4roa0/agentpay-protocol";
+
+// These are local guide checks, not a new Policy or payment authority.
+export function sameWalletPolicy(actual, expected) {
+  if (!actual || !expected) return false;
+  const keys = Object.keys(expected);
+  return (
+    Object.keys(actual).length === keys.length &&
+    keys.every((key) => {
+      if (key === "registryRpcUrl")
+        return new URL(actual[key]).href === new URL(expected[key]).href;
+      if (typeof expected[key] === "string" && expected[key].startsWith("0x")) {
+        return (
+          typeof actual[key] === "string" &&
+          actual[key].toLowerCase() === expected[key].toLowerCase()
+        );
+      }
+      return actual[key] === expected[key];
+    })
+  );
+}
+export function validateGuideTestCheckpoint(checkpoint, history, skill) {
+  if (!checkpoint) return null;
+  const b32 = (value) => /^0x[0-9a-f]{64}$/.test(value || "");
+  if (
+    checkpoint.version !== "agentpay.model-ack-smoke.v1" ||
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(
+      checkpoint.key || "",
+    ) ||
+    typeof checkpoint.confirmed !== "boolean" ||
+    !(checkpoint.orderId === null || b32(checkpoint.orderId)) ||
+    !(checkpoint.outputHash === null || b32(checkpoint.outputHash)) ||
+    (checkpoint.confirmed &&
+      (!b32(checkpoint.orderId) || !b32(checkpoint.outputHash)))
+  ) {
+    throw Error("GUIDE_TEST_CHECKPOINT_INVALID");
+  }
+  if (!skill) throw Error("GUIDE_TEST_SKILL_REQUIRED");
+  if (
+    !skill.reference ||
+    skill.reference.skillId !== skill.skillId ||
+    skill.reference.profileHash !== skill.profileHash
+  )
+    throw Error("GUIDE_TEST_SKILL_HISTORY_MISMATCH");
+  if (checkpoint.routingVersion !== "agentpay.runtime-call.v1")
+    throw Error("GUIDE_LEGACY_TEST_REVIEW_REQUIRED");
+  const id = `0x${createHash("sha256").update(`agentpay.user-invocation.v1:${checkpoint.key}`).digest("hex")}`;
+  if (
+    history &&
+    (history.version !== "agentpay.user-invocations.v1" ||
+      !history.invocations ||
+      typeof history.invocations !== "object" ||
+      Array.isArray(history.invocations))
+  )
+    throw Error("GUIDE_INVOCATION_HISTORY_INVALID");
+  const entry = history?.invocations?.[id];
+  if (checkpoint.orderId && (!entry || entry.orderId !== checkpoint.orderId))
+    throw Error("GUIDE_TEST_ORDER_HISTORY_MISMATCH");
+  if (entry) {
+    const binding = JSON.stringify({
+      version: "agentpay.runtime-service.v1",
+      reference: skill.reference,
+      requestedMaxUsageUnits: "1",
+    });
+    if (
+      entry.invocationId !== id ||
+      entry.requestHash !== hashPrivateRequest({ min: 10, max: 99 }) ||
+      entry.serviceBinding !== binding
+    )
+      throw Error("GUIDE_TEST_SKILL_HISTORY_MISMATCH");
+  }
+  return { ...checkpoint, hasOrder: Boolean(entry?.orderId) };
+}
+export function guideNextAction({
+  initialized,
+  plan,
+  chain,
+  bound,
+  installed,
+  liveWallet,
+  liveRuntime,
+  checked,
+  test,
+}) {
+  if (!initialized) return "initialize";
+  if (!plan) return "limits";
+  if (!chain?.moduleEnabled || !chain?.policyMatches) return "approve";
+  if (!bound) return "bind";
+  if (!liveWallet || liveWallet.locked || !liveRuntime) return "start";
+  if (!installed) return "install";
+  return checked || test ? "test" : "check";
+}