@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/src/user-setup-guide.mjs

@@ -0,0 +1,193 @@
+// 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 { runSetupDemo } from "./setup-demo.mjs";
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function inspectLocalUserSetup(dataDir) {
+  async function file(name) {
+    try {
+      const info = await lstat(join(dataDir, name));
+      if (
+        !info.isFile() ||
+        info.isSymbolicLink() ||
+        info.uid !== process.getuid() ||
+        info.mode & 0o077
+      )
+        throw Error("unsafe file");
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw Error(`Unsafe or unreadable local file: ${name}`);
+    }
+  }
+  const walletPresent = await file("wallet/session.keystore.json");
+  const callerPresent = await file("runtime/caller.token");
+  const policyPresent = await file("wallet/policy.json");
+  if (
+    callerPresent &&
+    !/^[0-9a-f]{64}$/.test(
+      (await readFile(join(dataDir, "runtime/caller.token"), "utf8")).trim(),
+    )
+  )
+    throw Error(
+      "Existing caller credential is invalid; inspect it without regenerating Wallet identity",
+    );
+  let delegate = null;
+  if (walletPresent) {
+    const keystore = JSON.parse(
+      await readFile(join(dataDir, "wallet/session.keystore.json"), "utf8"),
+    );
+    const address = String(keystore.address || "").replace(/^0x/, "");
+    if (!/^[0-9a-fA-F]{40}$/.test(address))
+      throw Error(
+        "Wallet public address is invalid; restore or inspect the existing keystore",
+      );
+    delegate = `0x${address}`;
+  }
+  return {
+    walletPresent,
+    callerPresent,
+    policyPresent,
+    delegate,
+    stage: !walletPresent
+      ? "not_initialized"
+      : !callerPresent
+        ? "partial_setup"
+        : "initialized",
+    policyStatus: policyPresent
+      ? "local_record_present_not_chain_verified"
+      : "not_configured",
+    runtimeStatus: "not_checked",
+    readyToPurchase: false,
+  };
+}
+
+// Legacy preview entry: local initialization and read-only authorization preview.
+// The public agentpay setup command uses runGuidedEntry for the complete flow,
+// with explicit external-owner or guarded Anvil signer selection.
+export async function runUserSetupGuide({
+  ask,
+  write,
+  check,
+  state,
+  initialize,
+  preview,
+  demo = false,
+}) {
+  if (demo)
+    return runSetupDemo({ ask, write, check, state, initialize, preview });
+  write(
+    "AgentPay · Local Wallet setup and authorization preview. Real setup needs an owner wallet and a Safe on the intended network.",
+  );
+  let previewed = false;
+  while (true) {
+    const report = await check();
+    if (!report.ok) {
+      for (const item of report.checks.filter(
+        (item) => item.status === "failed",
+      ))
+        write(`${item.message}. ${item.fix || ""}`);
+      return;
+    }
+    const local = await state();
+    const initialized = local.stage === "initialized";
+    const recommended = !initialized
+      ? "initialize"
+      : previewed || local.policyPresent
+        ? null
+        : "authorization";
+    write(
+      `\nYour progress\n  Wallet: ${initialized ? "Initialized" : "Not initialized"}\n  Authorization: ${previewed ? "Preview completed; actual authorization pending" : local.policyPresent ? "Saved locally; chain validity not checked" : "Not configured"}`,
+    );
+    write(
+      `\n------------------------------------------------------------\n> Choose an action\n------------------------------------------------------------\n${[
+        [
+          "initialize",
+          initialized ? "Already completed" : "Create local Wallet",
+        ],
+        [
+          "authorization",
+          previewed ? "Review preview again" : "Preview Safe and limits",
+        ],
+        ["status", "Inspect local state"],
+        ["reset", "Credential options"],
+        ["update", "Update information"],
+        ["uninstall", "Uninstall information"],
+        ["q", "Quit"],
+      ]
+        .map(
+          ([name, label]) =>
+            `  ${recommended === name ? "*" : " "} '${name}' ${label}${recommended === name ? " ← next step" : ""}`,
+        )
+        .join("\n")}`,
+    );
+    const action = (await ask("> ")).trim().toLowerCase();
+    if (action === "q") return;
+    if (action === "status") {
+      write(JSON.stringify(local, null, 2));
+      continue;
+    }
+    if (action === "update") {
+      write("Guided updates are not implemented yet.");
+      continue;
+    }
+    if (action === "uninstall") {
+      write(
+        "To uninstall, quit this guide and run agentpay uninstall. It requires confirmation before deleting local keys and history; Safe permissions remain unchanged.",
+      );
+      continue;
+    }
+    if (action === "reset") {
+      while (true) {
+        write(
+          "Reset options: 'change-password', 'rotate-session-key', 'rotate-caller-token', 'back', 'q'.",
+        );
+        const option = (await ask("> ")).trim().toLowerCase();
+        if (option === "q") return;
+        if (option === "back") break;
+        const explanations = {
+          "change-password":
+            "Changes encryption; preserves the Session Key and Policy.",
+          "rotate-session-key":
+            "Replacing the key requires explicit revocation and new owner authorization.",
+          "rotate-caller-token":
+            "Caller configuration must be updated; the Policy is unchanged.",
+        };
+        if (explanations[option])
+          write(
+            `${explanations[option]} Not implemented yet. No key, password, credential or Policy was changed.`,
+          );
+      }
+      continue;
+    }
+    if (action === "initialize") {
+      if (initialized) {
+        write("Wallet is already initialized; the existing key is preserved.");
+        continue;
+      }
+      await initialize();
+      write("Local initialization complete.");
+      continue;
+    }
+    if (action === "authorization") {
+      if (!initialized) {
+        write("Choose 'initialize' first.");
+        continue;
+      }
+      try {
+        const result = await preview(local.delegate);
+        if (result?.mode === "read_only" || result?.mode === "demo") {
+          previewed = true;
+          write(
+            "Owner signing is not implemented in this entry. This preview does not grant permission.",
+          );
+        }
+      } catch (error) {
+        if (error.code === "CANCELLED") write("Preview cancelled.");
+        else throw error;
+      }
+    }
+  }
+}

package/src/wallet-control.mjs

@@ -0,0 +1,182 @@
+import { walletCliPath } from "./wallet-package.mjs";
+// 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 { listenerPresent } from "./local-services.mjs";
+import { resolveUserDataDir } from "./local-data-directory.mjs";
+import { spawn } from "node:child_process";
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export async function controlWallet(
+  action,
+  {
+    args = process.argv.slice(2),
+    env = process.env,
+    terminal = Boolean(process.stdin.isTTY && process.stderr.isTTY),
+    spawnWallet = spawn,
+    inspect = lstat,
+    probe = listenerPresent,
+    resolveDirectory = resolveUserDataDir,
+    write = (m) => process.stderr.write(m + "\n"),
+    prompt = (m) => process.stderr.write(m),
+  } = {},
+) {
+  if (!["unlock", "lock", "status"].includes(action))
+    throw Error("Unsupported Wallet action");
+  if (args.length > 1 || args[0]?.startsWith("-")) {
+    write(`Usage: agentpay ${action} [User data directory]`);
+    return args.length === 1 && args[0] === "--help" ? 0 : 2;
+  }
+  if (action === "unlock" && !terminal) {
+    write(
+      "Open a terminal to unlock Wallet. Do not pass your password as an argument.",
+    );
+    return 1;
+  }
+  let dataDir;
+  try {
+    dataDir = await resolveDirectory({ argument: args[0], env });
+  } catch {
+    write(
+      "Your saved installation directory could not be read. Check the installation record or explicitly select your existing User data directory.",
+    );
+    return 1;
+  }
+  const walletDir = join(dataDir, "wallet"),
+    walletCli = walletCliPath();
+  try {
+    if (!(await inspect(walletCli)).isFile()) throw Error();
+  } catch {
+    write(
+      "Wallet executable could not be found or read. Complete agentpay install --market YOUR_MARKET_URL first.",
+    );
+    return 1;
+  }
+  const privateEntry = (info) =>
+    info.uid === process.getuid() &&
+    (info.mode & 0o077) === 0 &&
+    !info.isSymbolicLink();
+  try {
+    const dir = await inspect(walletDir);
+    if (!dir.isDirectory() || !privateEntry(dir)) throw Error();
+    const token = await inspect(
+      join(walletDir, action === "status" ? "agent.token" : "admin.token"),
+    );
+    if (!token.isFile() || !privateEntry(token)) throw Error();
+  } catch (error) {
+    write(
+      error.code === "ENOENT"
+        ? `Wallet setup files are missing in: ${walletDir}`
+        : `Cannot safely read Wallet setup in: ${walletDir}`,
+    );
+    write(
+      `If you selected the wrong installation: agentpay ${action} '/your/existing/User data directory'`,
+    );
+    return 1;
+  }
+  try {
+    const sock = await inspect(join(walletDir, "wallet.sock"));
+    if (!sock.isSocket() || !privateEntry(sock)) throw Error();
+  } catch (error) {
+    write(
+      error.code === "ENOENT"
+        ? "No Wallet socket was found for this installation. Run agentpay service start, then agentpay status."
+        : "The Wallet socket could not be safely inspected. Check the selected data directory and socket ownership.",
+    );
+    return 1;
+  }
+  try {
+    if (!(await probe(join(walletDir, "wallet.sock")))) {
+      write(
+        "No Wallet is listening on the saved socket (stale socket). Run agentpay service start, then agentpay status.",
+      );
+      return 1;
+    }
+  } catch {
+    write(
+      "Could not check the Wallet connection. Run agentpay status; inspect agentpay service logs wallet if it remains unavailable.",
+    );
+    return 1;
+  }
+  // stdin belongs directly to Wallet. Only public CLI output is captured; no password
+  // arguments, shell, Runtime call, secret capture, or persistent output file.
+  let output = "",
+    errors = "",
+    overflow = false,
+    prompted = false;
+  const code = await new Promise((done) => {
+    const child = spawnWallet(
+      process.execPath,
+      [walletCli, action, walletDir],
+      { stdio: ["inherit", "pipe", "pipe"], shell: false },
+    );
+    const collect = (part, isError) => {
+      if (overflow) return;
+      const text = part.toString();
+      if (output.length + errors.length + text.length > 16384) {
+        overflow = true;
+        child.kill();
+        return;
+      }
+      if (isError) {
+        errors += text;
+        if (errors.startsWith("Unlock secret: ")) {
+          prompt("Wallet password (input hidden): ");
+          prompted = true;
+          errors = errors.slice("Unlock secret: ".length);
+        }
+      } else output += text;
+    };
+    child.stdout.on("data", (part) => collect(part, false));
+    child.stderr.on("data", (part) => collect(part, true));
+    child.once("error", () => done(1));
+    child.once("close", (code) => done(code ?? 1));
+  });
+  if (prompted) prompt("\n");
+  let result, error;
+  try {
+    result = JSON.parse(output.trim());
+  } catch {}
+  for (const line of errors.split("\n")) {
+    try {
+      const value = JSON.parse(line);
+      if (value?.ok === false) error = value.error;
+    } catch {}
+  }
+  const success =
+    action === "status"
+      ? typeof result?.locked === "boolean"
+      : action === "lock"
+        ? result?.locked === true
+        : typeof result?.address === "string";
+  if (code === 0 && !overflow && !error && success) {
+    write(
+      action === "status"
+        ? `Wallet: running (${result.locked ? "locked" : "unlocked"}).`
+        : action === "lock"
+          ? "Wallet locked. Your on-chain spending permission is unchanged."
+          : "Wallet unlocked. Order checks will continue. Use agentpay status before resuming your original Skill request.",
+    );
+    return 0;
+  }
+  const messages = {
+    UNLOCK_FAILED:
+      "Could not unlock Wallet. Check your password and try again.",
+    CANCELLED: "Unlock cancelled. Wallet was not unlocked.",
+    UNAUTHORIZED:
+      "Local Wallet access was rejected. Check that you selected the correct User data directory.",
+    LOCKED: "Wallet is still locked.",
+    TTY_REQUIRED: "Run unlock in an interactive terminal.",
+  };
+  write(
+    messages[error?.code] ||
+      `Wallet did not confirm ${action}. Run agentpay status, then agentpay service logs wallet for the cause.`,
+  );
+  if (error?.code && !messages[error.code])
+    write(
+      `Error code: ${/^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : "UNKNOWN_ERROR"}`,
+    );
+  return code || 1;
+}

package/src/wallet-ipc-error.mjs

@@ -0,0 +1,16 @@
+// 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/.
+const CODE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+
+export function walletIpcError(payload) {
+  const error = payload?.error;
+  const settlementCode =
+    typeof error?.settlementCode === "string" && CODE.test(error.settlementCode)
+      ? error.settlementCode
+      : null;
+  return Object.assign(new Error(error?.message || "Wallet request failed"), {
+    code: error?.code || "WALLET_FAILED",
+    ...(settlementCode ? { settlementCode } : {}),
+  });
+}

package/src/wallet-package.mjs

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MPL-2.0
+// Resolve public Wallet entries from this User installation, never a sibling checkout.
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const userPackageDirectory = fileURLToPath(new URL('..', import.meta.url));
+export function walletPackage(userDir = userPackageDirectory) {
+  const require = createRequire(join(userDir, 'package.json'));
+  const manifestPath = require.resolve('@c4roa0/agentpay-wallet/package.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const user = JSON.parse(readFileSync(join(userDir, 'package.json'), 'utf8'));
+  if (manifest.name !== '@c4roa0/agentpay-wallet' ||
+      !/^\d+\.\d+\.\d+$/.test(user.dependencies?.[manifest.name] || '') ||
+      manifest.version !== user.dependencies[manifest.name] ||
+      manifest.dependencies?.['@c4roa0/agentpay-protocol'] !== user.dependencies?.['@c4roa0/agentpay-protocol']) {
+    throw Error('Installed Wallet does not match this User version. Reinstall the reviewed User version, then run agentpay repair. Your private data is unchanged.');
+  }
+  return { directory: dirname(manifestPath), manifest, cli: require.resolve('@c4roa0/agentpay-wallet/cli') };
+}
+export function walletCliPath(userDir) { return walletPackage(userDir).cli; }

package/update-pair.json

@@ -0,0 +1,6 @@
+{
+  "format": "agentpay.local-update-pair.v1",
+  "userVersion": "0.3.0",
+  "walletVersion": "0.3.0",
+  "typesDependency": "0.14.3"
+}