@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

package/scripts/autostart.mjs

@@ -0,0 +1,186 @@
+#!/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 { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { lstat, mkdir, readFile, writeFile, unlink, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import {
+  resolveUserDataDir,
+  installedUserDir,
+} from "../src/local-data-directory.mjs";
+import {
+  autostartFiles,
+  isManagedUnit,
+  units,
+  runtimeUnits,
+} from "../src/autostart-files.mjs";
+import {
+  readServiceSettings,
+  saveServiceSettings,
+} from "../src/local-services.mjs";
+import { ensureLocalServices } from "../src/prepare-local-services.mjs";
+const ctl = (...args) =>
+  execFileSync("systemctl", ["--user", ...args], {
+    stdio: "inherit",
+    timeout: 30000,
+  });
+try {
+  const [action, ...args] = process.argv.slice(2);
+  if (
+    ![
+      "prepare",
+      "prepare-repair",
+      "enable",
+      "disable",
+      "remove",
+      "start",
+      "restart",
+      "stop",
+      "status",
+      "configure",
+    ].includes(action) ||
+    args.length !== (action === "configure" ? 2 : 0)
+  )
+    throw Error(
+      "Usage: node scripts/autostart.mjs <prepare|enable|disable|remove|start|restart|stop|status> or configure RUNTIME_URL SETTLEMENT_URL",
+    );
+  if (process.platform !== "linux")
+    throw Error(
+      "Automatic startup currently supports Linux with systemd user services. macOS support is pending.",
+    );
+  const dataDir = await resolveUserDataDir();
+  if (action === "configure") {
+    await saveServiceSettings({
+      dataDir,
+      runtimeUrl: args[0],
+      settlementUrl: args[1],
+    });
+    console.log("Local startup settings saved. No service was started.");
+  } else {
+    const files = autostartFiles({
+      node: process.execPath,
+      userDir: installedUserDir,
+      dataDir,
+    });
+    const config = join(homedir(), ".config"),
+      unitDir = join(config, "systemd/user");
+    for (const directory of [config, join(config, "systemd"), unitDir]) {
+      if (["enable", "prepare", "prepare-repair"].includes(action))
+        await mkdir(directory, { mode: 0o700 }).catch((e) => {
+          if (e.code !== "EEXIST") throw e;
+        });
+      const info = await lstat(directory);
+      if (
+        !info.isDirectory() ||
+        info.isSymbolicLink() ||
+        info.uid !== process.getuid() ||
+        info.mode & 0o022
+      )
+        throw Error(
+          `User configuration directory is not safely owned: ${directory}`,
+        );
+    }
+    const paths = Object.entries(files).map(([name, body]) => ({
+      name,
+      path: join(unitDir, name),
+      body,
+    }));
+    for (const { path, body, name } of paths) {
+      try {
+        const info = await lstat(path);
+        if (
+          !info.isFile() ||
+          info.isSymbolicLink() ||
+          info.uid !== process.getuid() ||
+          info.mode & 0o022 ||
+          !isManagedUnit(await readFile(path, "utf8"), name, dataDir)
+        )
+          throw Error(
+            "An existing startup file belongs to another configuration. Preserve it and review before switching.",
+          );
+      } catch (e) {
+        if (e.code !== "ENOENT") throw e;
+      }
+    }
+    if (action === "status") {
+      ctl("status", "--no-pager", ...runtimeUnits);
+      console.log(
+        "The login reminder runs once per graphical session; it can be inactive outside a desktop login.",
+      );
+    } else if (["start", "restart", "stop"].includes(action)) {
+      if (action !== "stop") await readServiceSettings(dataDir);
+      for (const { path } of paths) await lstat(path);
+      ctl(action, ...(action !== "stop" ? runtimeUnits : units));
+      console.log(
+        action !== "stop"
+          ? `${action === "restart" ? "Restart" : "Start"} requested through systemd. This does not confirm readiness.\nNext: agentpay status`
+          : "Stop requested through systemd. Login startup and saved Wallet data are unchanged.\nNext: agentpay status",
+      );
+    } else if (["enable", "prepare", "prepare-repair"].includes(action)) {
+      await ensureLocalServices({ dataDir, connectionOptions: action === "prepare-repair" ? { refreshClientModule: true, checkOnly: true } : {} });
+      // No --now: avoid replacing a Wallet currently owned by terminal setup/system services.
+      for (const { path, body } of paths)
+        try {
+          await writeFile(path, body, { flag: "wx", mode: 0o600 });
+        } catch (e) {
+          if (e.code !== "EEXIST") throw e;
+          const temporary = path + '.' + randomUUID();
+          try {
+            await writeFile(temporary, body, {flag:'wx',mode:0o600});
+            await rename(temporary,path);
+          } finally { await unlink(temporary).catch(e => { if(e.code !== 'ENOENT') throw e; }); }
+        }
+      ctl("daemon-reload");
+      if (action === "enable") {
+        ctl("enable", ...units);
+        await saveServiceSettings({
+          dataDir,
+          ...(await readServiceSettings(dataDir)),
+          startupChoice: "enabled",
+        });
+        console.log(
+          "Login startup enabled for Wallet and Runtime. Current processes were not changed.\nTo start now: agentpay service start",
+        );
+      } else
+        console.log(
+          "Local service files prepared. Automatic startup was not changed.",
+        );
+    } else if (action === "disable") {
+      await readServiceSettings(dataDir);
+      ctl("disable", ...units);
+      await saveServiceSettings({
+        dataDir,
+        ...(await readServiceSettings(dataDir)),
+        startupChoice: "disabled",
+      });
+      console.log(
+        "Login startup disabled for Wallet and Runtime. Current processes were not stopped.\nTo stop now: agentpay service stop",
+      );
+    } else {
+      await saveServiceSettings({
+        dataDir,
+        ...(await readServiceSettings(dataDir)),
+        startupChoice: "disabled",
+      });
+      ctl("disable", "--now", ...units);
+      for (const { path } of paths)
+        await unlink(path).catch((e) => {
+          if (e.code !== "ENOENT") throw e;
+        });
+      ctl("daemon-reload");
+      console.log(
+        "Automatic startup and its reminder removed. Wallet data, Policy and request history are kept.",
+      );
+    }
+  }
+} catch (error) {
+  console.error(
+    error.status === undefined
+      ? error.message
+      : "The systemd command failed; some service changes may already have applied. Wallet keys and request history were kept. Run agentpay status before retrying.",
+  );
+  process.exitCode = 1;
+}

package/scripts/cancel-order.mjs

@@ -0,0 +1,76 @@
+#!/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 {
+  cancelOrder,
+  cancellationStatus,
+  cancellationOrderForRequest,
+} from "../src/order-cancellation.mjs";
+const args = process.argv.slice(2),
+  [dataDir, settlementUrl] = args;
+let orderId, flag;
+try {
+  if (!dataDir || !settlementUrl)
+    throw Object.assign(Error(), { code: "INVALID_ARGUMENTS" });
+  if (args[2] === "--request") {
+    if (!args[3] || args.length > 5)
+      throw Object.assign(Error(), { code: "INVALID_ARGUMENTS" });
+    orderId = await cancellationOrderForRequest({
+      dataDir,
+      requestId: args[3],
+    });
+    flag = args[4];
+  } else {
+    orderId = args[2];
+    flag = args[3];
+    if (args.length > 4)
+      throw Object.assign(Error(), { code: "INVALID_ARGUMENTS" });
+  }
+  if (
+    !dataDir ||
+    !settlementUrl ||
+    !orderId ||
+    (flag !== undefined && flag !== "--status")
+  )
+    throw Object.assign(Error(), { code: "INVALID_ARGUMENTS" });
+  const result = await (flag === "--status" ? cancellationStatus : cancelOrder)(
+    { dataDir, settlementUrl, orderId },
+  );
+  console.log(JSON.stringify({ ok: true, result }, null, 2));
+} catch (error) {
+  const code = /^[A-Z][A-Z0-9_]{0,95}$/.test(error?.code || "")
+    ? error.code
+    : "ORDER_CANCEL_FAILED";
+  const messages = {
+    INVALID_ARGUMENTS:
+      "Usage: node scripts/cancel-order.mjs <user-data-dir> <settlement-url> <order-id | --request request-id> [--status]",
+    ORDER_NOT_CREATED:
+      "This request has no saved Order yet. Retry its status later; no cancellation or payment was submitted.",
+    INVOCATION_NOT_FOUND:
+      "The original request was not found. Preserve its history; do not create another payment.",
+    ORDER_ALREADY_ACCEPTED:
+      "Provider already accepted this Order. Its existing delivery and timeout rules still apply.",
+    ORDER_CANCEL_FORBIDDEN: "Wallet does not own this Order and Policy.",
+    LOCKED:
+      "Wallet is locked. Unlock it before querying or cancelling this Order.",
+    CANCELLATION_STATE_CONFLICT:
+      "Saved cancellation belongs to a different Policy or endpoint. Preserve it for recovery review.",
+  };
+  console.log(
+    JSON.stringify({
+      ok: false,
+      error: {
+        code,
+        message:
+          messages[code] ||
+          "Cancellation could not be confirmed. Check the same Order again; do not create a replacement payment.",
+        ...(typeof error?.settlementCode === "string" &&
+        /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(error.settlementCode)
+          ? { settlementCode: error.settlementCode }
+          : {}),
+      },
+    }),
+  );
+  process.exitCode = 1;
+}

package/scripts/check-installation.mjs

@@ -0,0 +1,26 @@
+#!/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 { fileURLToPath } from "node:url";
+import { checkLocalInstallation } from "../src/install-preflight.mjs";
+try {
+  if (process.argv.length !== 3)
+    throw new Error(
+      "Usage: node scripts/check-installation.mjs ABSOLUTE_PRIVATE_DATA_DIR",
+    );
+  const { isAbsolute } = await import("node:path");
+  if (!isAbsolute(process.argv[2]))
+    throw new Error("Private data directory must be an absolute path");
+  const result = await checkLocalInstallation({
+    userDir: fileURLToPath(new URL("..", import.meta.url)),
+    dataDir: process.argv[2],
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exitCode = result.ok ? 0 : 1;
+} catch (error) {
+  process.stderr.write(
+    `${JSON.stringify({ ok: false, error: { message: error.message } })}\n`,
+  );
+  process.exitCode = 1;
+}

package/scripts/check-official-test-package.mjs

@@ -0,0 +1,35 @@
+#!/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/.
+// Release check only: never execute the package or accept a new hash automatically.
+import { readFile, stat } from "node:fs/promises";
+import {
+  OFFICIAL_TEST_PACKAGE,
+  verifyOfficialTestBytes,
+} from "../src/official-test-package.mjs";
+import { parseSkillBundle, skillArchiveLimits } from "../src/skill-bundle.mjs";
+try {
+  if (process.argv.length !== 3)
+    throw Error(
+      "Usage: node scripts/check-official-test-package.mjs PATH_TO_REVIEWED_ZIP",
+    );
+  const path = process.argv[2];
+  const info = await stat(path);
+  if (!info.isFile() || info.size > skillArchiveLimits.compressed)
+    throw Error("Invalid package file or size.");
+  const bytes = await readFile(path);
+  verifyOfficialTestBytes(bytes);
+  const bundle = parseSkillBundle(bytes);
+  if (
+    bundle.manifest.packageName !== OFFICIAL_TEST_PACKAGE.name ||
+    bundle.manifest.packageVersion !== OFFICIAL_TEST_PACKAGE.version
+  )
+    throw Error("Pinned package name/version differ from the release record.");
+  console.log(
+    `Official test package verified: ${OFFICIAL_TEST_PACKAGE.name} ${OFFICIAL_TEST_PACKAGE.version}\nSHA-256: ${OFFICIAL_TEST_PACKAGE.sha256}\nNo package scripts were executed.`,
+  );
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/check-purchase-readiness.mjs

@@ -0,0 +1,275 @@
+#!/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 { parseServiceReference } from "../src/service-reference.mjs";
+import { serviceUrl } from "../src/service-url.mjs";
+// Read-only business readiness: no Order preparation, signature, nonce or funds.
+import { readFile, lstat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { Contract, JsonRpcProvider } from "ethers";
+import { Phase0Wallet } from "@c4roa0/agentpay-wallet/local";
+import { callWallet } from "@c4roa0/agentpay-wallet";
+import {
+  buildSafePolicyPlan,
+  inspectSafePolicy,
+} from "../src/safe-policy-plan.mjs";
+import { installedSkillPath } from "../src/active-skill.mjs";
+import { loadInstalledServiceReference } from "../src/skill-package.mjs";
+import { settlementProfileBlocker } from "../src/readiness-profile.mjs";
+
+const [dataArg, configArg, settlementArg, runtimeArg, unitsArg] =
+  process.argv.slice(2);
+if (
+  !dataArg ||
+  !configArg ||
+  !settlementArg ||
+  !runtimeArg ||
+  !/^[1-9][0-9]*$/.test(unitsArg || "") ||
+  process.argv.length !== 7
+)
+  throw new Error(
+    "usage: check-purchase-readiness.mjs <private-user-data-dir> <public-policy-config.json> <settlement-url> <user-runtime-url> <requested-max-usage-units>",
+  );
+const dataDir = resolve(dataArg);
+const config = JSON.parse(await readFile(resolve(configArg), "utf8"));
+const settlement = localOrHttps(settlementArg);
+const runtime = localOrHttps(runtimeArg);
+const blockers = [];
+const facts = {};
+const check = async (code, work) => {
+  try {
+    return await work();
+  } catch {
+    blockers.push(code);
+    return null;
+  }
+};
+const walletDir = join(dataDir, "wallet");
+const wallet = await check("WALLET_NOT_INSTALLED", () =>
+  Phase0Wallet.open(walletDir),
+);
+const delegate = wallet
+  ? await check("WALLET_ADDRESS_UNAVAILABLE", () => wallet.address())
+  : null;
+// This command checks a specific purchase, not global Runtime health.
+const referenceArg = process.env.AGENTPAY_CHECK_SERVICE_REFERENCE_FILE;
+const skill = await check("SERVICE_REFERENCE_REQUIRED", async () =>
+  referenceArg
+    ? readFile(referenceArg, "utf8")
+        .then(JSON.parse)
+        .then(parseServiceReference)
+        .then((reference) => ({
+          ...reference,
+          reference,
+          providerId: reference.profile.providerId,
+          endpointUrl: reference.profile.paymentEndpoint,
+        }))
+    : loadInstalledServiceReference(await installedSkillPath(dataDir)),
+);
+await check("USER_CALLER_CREDENTIAL_MISSING", async () => {
+  const path = join(dataDir, "runtime", "caller.token");
+  const info = await lstat(path);
+  if (
+    !info.isFile() ||
+    info.isSymbolicLink() ||
+    info.uid !== process.getuid() ||
+    info.mode & 0o077 ||
+    !/^[0-9a-f]{64}$/.test((await readFile(path, "utf8")).trim())
+  )
+    throw new Error("caller credential invalid");
+  return true;
+});
+if (skill)
+  facts.skill = {
+    providerId: skill.providerId,
+    skillId: skill.skillId,
+    profileHash: skill.profileHash,
+  };
+let plan = null;
+let chain = null;
+if (wallet && delegate) {
+  plan = await check("POLICY_CONFIG_INVALID", () =>
+    buildSafePolicyPlan(config, delegate),
+  );
+  if (!wallet.policy) blockers.push("WALLET_POLICY_UNBOUND");
+  else if (
+    plan &&
+    JSON.stringify(wallet.policy) !== JSON.stringify(plan.walletPolicy)
+  )
+    blockers.push("WALLET_POLICY_MISMATCH");
+}
+if (plan) {
+  chain = new JsonRpcProvider(plan.rpcUrl, plan.chainId, {
+    staticNetwork: true,
+  });
+  try {
+    const state = await check("CHAIN_POLICY_UNAVAILABLE", () =>
+      inspectSafePolicy(chain, plan),
+    );
+    if (state) {
+      if (!state.moduleEnabled) blockers.push("MODULE_NOT_ENABLED");
+      if (!state.policyMatches) blockers.push("CHAIN_POLICY_MISMATCH");
+      if (plan.validAfter > Math.floor(Date.now() / 1000))
+        blockers.push("POLICY_NOT_YET_ACTIVE");
+      facts.policy = {
+        safe: plan.safe,
+        delegate: plan.delegate,
+        maxPerPaymentAtomic: plan.maxPerPayment.toString(),
+        totalBudgetAtomic: plan.totalBudget.toString(),
+        spentAtomic: state.policySpent,
+        validUntil: plan.validUntil,
+        moduleEnabled: state.moduleEnabled,
+      };
+    }
+  } finally {
+    chain.destroy();
+    chain = null;
+  }
+}
+if (wallet) {
+  const status = await check("WALLET_PROCESS_UNAVAILABLE", async () => {
+    const tokenPath = join(walletDir, "agent.token");
+    const info = await lstat(tokenPath);
+    if (
+      !info.isFile() ||
+      info.isSymbolicLink() ||
+      info.uid !== process.getuid() ||
+      info.mode & 0o077
+    )
+      throw new Error("capability file unsafe");
+    const token = (await readFile(tokenPath, "utf8")).trim();
+    return callWallet(join(walletDir, "wallet.sock"), token, "status");
+  });
+  if (status?.locked) blockers.push("WALLET_LOCKED");
+  if (status?.policyMigrationPending) blockers.push("POLICY_MIGRATION_PENDING");
+  if (status && !status.bound) blockers.push("WALLET_POLICY_UNBOUND_LIVE");
+  if (status?.bound && plan && status.policyId !== plan.policyId)
+    blockers.push("WALLET_LIVE_POLICY_MISMATCH");
+}
+const runtimeState = await check("USER_RUNTIME_UNAVAILABLE", async () => {
+  const response = await fetch(new URL("/health", runtime), {
+    redirect: "error",
+    signal: AbortSignal.timeout(2000),
+  });
+  const body = await response.json();
+  if (!response.ok || body?.result?.role !== "user-runtime")
+    throw new Error("runtime health invalid");
+  return body.result;
+});
+if (
+  runtimeState &&
+  !runtimeState.capabilities?.includes("agentpay.runtime-call.v1")
+)
+  blockers.push("USER_RUNTIME_UPGRADE_REQUIRED");
+let quote = null;
+if (skill) {
+  const commercial = await check(
+    "SETTLEMENT_READINESS_UNAVAILABLE",
+    async () => {
+      const url = serviceUrl(settlement, "/agentpay/purchase-readiness");
+      url.searchParams.set("skillId", skill.skillId);
+      url.searchParams.set("profileHash", skill.profileHash);
+      const response = await fetch(url, {
+        redirect: "error",
+        signal: AbortSignal.timeout(3500),
+      });
+      const body = await response.json();
+      if (!response.ok || body?.ok !== true)
+        throw new Error("commercial readiness unavailable");
+      return body.result;
+    },
+  );
+  if (commercial) {
+    if (plan) {
+      const profileBlocker = settlementProfileBlocker(
+        plan,
+        commercial.settlementProfile,
+      );
+      if (profileBlocker) blockers.push(profileBlocker);
+    }
+    facts.finalizationPolicy = commercial.finalizationPolicy || null;
+    facts.orderDeadlinePolicy = commercial.orderDeadlinePolicy || null;
+    if (!commercial.finalizationPolicy)
+      blockers.push("FINALIZATION_POLICY_UNAVAILABLE");
+    blockers.push(...commercial.blockers);
+    quote = commercial.quote;
+    if (quote && quote.providerId !== skill.providerId)
+      blockers.push("PROVIDER_ID_MISMATCH");
+  }
+}
+if (plan && quote) {
+  const provider = new JsonRpcProvider(plan.rpcUrl, plan.chainId, {
+    staticNetwork: true,
+  });
+  try {
+    const qualified = await check("REGISTRY_UNAVAILABLE", async () => {
+      const registry = new Contract(
+        plan.registry,
+        ["function isQualified(bytes32,bytes32,address) view returns(bool)"],
+        provider,
+      );
+      return registry.isQualified(
+        skill.skillId,
+        skill.profileHash,
+        quote.seller,
+      );
+    });
+    if (qualified === false) blockers.push("SKILL_NOT_QUALIFIED");
+    if (quote.asset.toLowerCase() !== plan.token.toLowerCase())
+      blockers.push("POLICY_ASSET_MISMATCH");
+    const units = BigInt(unitsArg);
+    if (units > BigInt(quote.maxUsageUnits))
+      blockers.push("USAGE_EXCEEDS_QUOTE");
+    const maximum =
+      BigInt(quote.baseAmountAtomic) + BigInt(quote.unitPriceAtomic) * units;
+    const remaining =
+      facts.policy?.spentAtomic == null
+        ? 0n
+        : plan.totalBudget - BigInt(facts.policy.spentAtomic);
+    if (maximum > plan.maxPerPayment)
+      blockers.push("PER_PAYMENT_LIMIT_EXCEEDED");
+    if (maximum > remaining) blockers.push("POLICY_BUDGET_EXCEEDED");
+    const balance = await check("SAFE_BALANCE_UNAVAILABLE", async () => {
+      const token = new Contract(
+        plan.token,
+        ["function balanceOf(address) view returns(uint256)"],
+        provider,
+      );
+      return token.balanceOf(plan.safe);
+    });
+    if (balance != null && balance < maximum)
+      blockers.push("SAFE_TOKEN_BALANCE_LOW");
+    facts.estimatedPrepaidMaximumAtomic = maximum.toString();
+    facts.safeTokenBalanceAtomic = balance?.toString() ?? null;
+    facts.quoteId = quote.quoteId;
+  } finally {
+    provider.destroy();
+  }
+}
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      ok: true,
+      readyToPurchase: blockers.length === 0,
+      blockers: [...new Set(blockers)],
+      facts,
+      note: "Snapshot only; Order creation rechecks all limits and current Quote",
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+function localOrHttps(input) {
+  const url = new URL(input);
+  if (
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw new Error("HTTPS_OR_LOOPBACK_REQUIRED");
+  return url;
+}

package/scripts/configure-runtime-client.mjs

@@ -0,0 +1,16 @@
+#!/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 { saveRuntimeConnection } from "../src/runtime-client.mjs";
+if (process.argv.length !== 4)
+  throw Error(
+    "Usage: node scripts/configure-runtime-client.mjs <User data directory> <loopback Runtime URL>",
+  );
+await saveRuntimeConnection({
+  dataDir: process.argv[2],
+  runtimeUrl: process.argv[3],
+});
+console.log(
+  "Local Runtime client connection saved. No authorization or purchase was made.",
+);

package/scripts/guide-policy.mjs

@@ -0,0 +1,64 @@
+#!/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 { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { JsonRpcProvider } from "ethers";
+import { inspectSafePolicy } from "../src/safe-policy-plan.mjs";
+import { runPolicyTerminalGuide } from "../src/policy-terminal-guide.mjs";
+let terminal;
+try {
+  const args = process.argv.slice(2),
+    demo = args[0] === "--demo";
+  if (demo ? args.length !== 1 : args.length !== 2)
+    throw Error(
+      "Usage: guide-policy.mjs --demo | PUBLIC_DEPLOYMENT_JSON WALLET_DELEGATE",
+    );
+  if (!process.stdin.isTTY)
+    throw Error(
+      "Run this guide in an interactive terminal; piped authorization input is not accepted.",
+    );
+  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[0], "utf8"));
+  terminal = createInterface({ input: process.stdin, output: process.stderr });
+  await runPolicyTerminalGuide({
+    deployment,
+    delegate: demo ? `0x${"5".repeat(40)}` : args[1],
+    demo,
+    ask: (prompt) => terminal.question(prompt),
+    write: (message) => process.stdout.write(`${message}\n`),
+    inspect: async (plan) => {
+      const rpc = new JsonRpcProvider(plan.rpcUrl, undefined, {
+        staticNetwork: false,
+      });
+      let timeout;
+      try {
+        return await Promise.race([
+          inspectSafePolicy(rpc, plan),
+          new Promise((_, reject) => {
+            timeout = setTimeout(() => reject(Error("timeout")), 10000);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timeout);
+        rpc.destroy();
+      }
+    },
+  });
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = error.code === "CANCELLED" ? 0 : 1;
+} finally {
+  terminal?.close();
+}

package/scripts/initialize-caller-credential.mjs

@@ -0,0 +1,11 @@
+// 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 { initializeCallerCredential } from "../src/caller-auth.mjs";
+
+const path = String(process.argv[2] || "").trim();
+if (!path) throw new Error("caller credential path is required");
+await initializeCallerCredential(path);
+process.stdout.write(
+  `${JSON.stringify({ ok: true, callerCredential: "ready" })}\n`,
+);