@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

package/src/local-services.mjs

@@ -0,0 +1,156 @@
+// 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 { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+export function serviceSettings(input) {
+  if (
+    !input ||
+    Object.keys(input).some(
+      (k) =>
+        !["version", "runtimeUrl", "settlementUrl", "startupChoice"].includes(
+          k,
+        ),
+    ) ||
+    input.version !== 1
+  )
+    throw Error("Invalid local service settings.");
+  if (
+    input.startupChoice !== undefined &&
+    !["enabled", "disabled"].includes(input.startupChoice)
+  )
+    throw Error("Invalid startup preference.");
+  const runtime = new URL(input.runtimeUrl),
+    settlement = new URL(input.settlementUrl);
+  if (
+    runtime.protocol !== "http:" ||
+    runtime.hostname !== "127.0.0.1" ||
+    !runtime.port ||
+    runtime.pathname !== "/" ||
+    runtime.search ||
+    runtime.hash ||
+    runtime.username ||
+    runtime.password
+  )
+    throw Error("Runtime needs a loopback HTTP origin with an explicit port.");
+  if (
+    settlement.username ||
+    settlement.password ||
+    settlement.search ||
+    settlement.hash ||
+    !(
+      settlement.protocol === "https:" ||
+      (settlement.protocol === "http:" &&
+        ["127.0.0.1", "localhost", "[::1]"].includes(settlement.hostname))
+    )
+  )
+    throw Error("Settlement needs HTTPS or a local rehearsal URL.");
+  return {
+    version: 1,
+    runtimeUrl: runtime.origin,
+    settlementUrl: settlement.href.replace(/\/+$/, ""),
+    ...(input.startupChoice ? { startupChoice: input.startupChoice } : {}),
+  };
+}
+function owned(info) {
+  return (
+    info.uid === process.getuid() &&
+    (info.mode & 0o077) === 0 &&
+    !info.isSymbolicLink()
+  );
+}
+export async function checkServiceDirectory(dataDir) {
+  for (const dir of [
+    dataDir,
+    join(dataDir, "wallet"),
+    join(dataDir, "runtime"),
+  ]) {
+    const info = await lstat(dir);
+    if (!info.isDirectory() || !owned(info))
+      throw Error(
+        "Local service directories must be private and owned by you.",
+      );
+  }
+}
+export async function saveServiceSettings({
+  dataDir,
+  runtimeUrl,
+  settlementUrl,
+  startupChoice,
+}) {
+  await checkServiceDirectory(dataDir);
+  let previous;
+  try {
+    previous = await readServiceSettings(dataDir);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  const choice = startupChoice ?? previous?.startupChoice;
+  const settings = serviceSettings({
+    version: 1,
+    runtimeUrl,
+    settlementUrl,
+    ...(choice ? { startupChoice: choice } : {}),
+  });
+  const temp = join(dataDir, "runtime", `services-${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open(temp, "wx", 0o600);
+    await handle.writeFile(JSON.stringify(settings) + "\n");
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temp, join(dataDir, "runtime", "local-services.json"));
+  } finally {
+    await handle?.close();
+    await unlink(temp).catch(() => {});
+  }
+}
+export async function readServiceSettings(dataDir) {
+  await checkServiceDirectory(dataDir);
+  const file = await open(
+    join(dataDir, "runtime", "local-services.json"),
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  );
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || !owned(info) || info.size > 4096)
+      throw Error("Invalid local service settings file.");
+    return serviceSettings(JSON.parse(await file.readFile("utf8")));
+  } finally {
+    await file.close();
+  }
+}
+export function runtimeEnvironment(dataDir, settings) {
+  return {
+    AGENTPAY_USER_HOST: "127.0.0.1",
+    AGENTPAY_USER_PORT: new URL(settings.runtimeUrl).port,
+    AGENTPAY_WALLET_SOCKET: join(dataDir, "wallet", "wallet.sock"),
+    AGENTPAY_WALLET_AGENT_TOKEN_FILE: join(dataDir, "wallet", "agent.token"),
+    AGENTPAY_USER_CALLER_TOKEN_FILE: join(dataDir, "runtime", "caller.token"),
+    AGENTPAY_USER_STATE_FILE: join(dataDir, "runtime", "invocations.json"),
+    AGENTPAY_SETTLEMENT_URL: settings.settlementUrl,
+  };
+}
+export function listenerPresent(address) {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(address);
+    socket.setTimeout(2000);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", (e) => {
+      socket.destroy();
+      if (["ENOENT", "ECONNREFUSED"].includes(e.code)) resolve(false);
+      else reject(Error("Could not safely check the existing listener."));
+    });
+    socket.once("timeout", () => {
+      socket.destroy();
+      reject(Error("Existing listener check timed out."));
+    });
+  });
+}

package/src/local-time.mjs

@@ -0,0 +1,36 @@
+// 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 {
+  assertUnixMilliseconds,
+  parseLegacyIsoMilliseconds,
+  unixSecondsToMilliseconds,
+} from "@c4roa0/agentpay-protocol";
+export const currentTimeMs = () => assertUnixMilliseconds(Date.now());
+// Explicit migration adapter for known local fields only; never inspect signed payloads.
+export function localTimeMs(entry, key) {
+  if (Object.hasOwn(entry, key + "Ms")) {
+    const ms = assertUnixMilliseconds(entry[key + "Ms"]);
+    if (
+      Object.hasOwn(entry, key) &&
+      parseLegacyIsoMilliseconds(entry[key]) !== ms
+    )
+      throw Error("LOCAL_TIME_CONFLICT");
+    return ms;
+  }
+  return parseLegacyIsoMilliseconds(entry[key]);
+}
+export function displayTime(ms) {
+  assertUnixMilliseconds(ms);
+  const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return (
+    new Intl.DateTimeFormat(undefined, {
+      dateStyle: "medium",
+      timeStyle: "long",
+      timeZone: zone,
+    }).format(ms) + ` (${zone})`
+  );
+}
+export function displaySeconds(seconds) {
+  return displayTime(unixSecondsToMilliseconds(seconds));
+}

package/src/local-update.mjs

@@ -0,0 +1,316 @@
+import { requireRunningSoftware } from "./software-versions.mjs";
+import { walletPackage } from "./wallet-package.mjs";
+// Apply installed packages. Preserve identity/history and startup preferences;
+// preparation failure must not enable a mismatched Wallet/Runtime pair.
+// 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 { ensureRuntimeConnection } from "./runtime-connection-settings.mjs";
+import { prepareOfficialTestUpdate } from "./official-test-update.mjs";
+import { readFile, open, lstat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+import {
+  installedUserDir,
+  resolveUserDataDir,
+} from "./local-data-directory.mjs";
+import {
+  checkServiceDirectory,
+  readServiceSettings,
+} from "./local-services.mjs";
+import { createInterface } from "node:readline/promises";
+import { createHash } from "node:crypto";
+import { runInstall, fingerprint } from "./install-user.mjs";
+import { localWalletAdmin } from "./local-wallet-ipc.mjs";
+import { readRuntimeStatus } from "./runtime-status.mjs";
+
+async function json(path) {
+  const info = await lstat(path);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 65536)
+    throw Error("Update metadata must be a regular file.");
+  return JSON.parse(await readFile(path, "utf8"));
+}
+// The v1 metadata field typesDependency now pins the public npm Protocol package.
+// Keep exact pair checks until the separate compatibility-range design is implemented.
+export async function checkUpdatePair(userDir) {
+  const { directory: walletDir } = walletPackage(userDir);
+  const [pair, user, wallet] = await Promise.all([
+    json(join(userDir, "update-pair.json")),
+    json(join(userDir, "package.json")),
+    json(join(walletDir, "package.json")),
+  ]);
+  if (
+    pair.format !== "agentpay.local-update-pair.v1" ||
+    !/^\d+\.\d+\.\d+$/.test(pair.userVersion) ||
+    !/^\d+\.\d+\.\d+$/.test(pair.walletVersion) ||
+    typeof pair.typesDependency !== "string" ||
+    !pair.typesDependency ||
+    user.name !== "@c4roa0/agentpay-user" ||
+    wallet.name !== "@c4roa0/agentpay-wallet" ||
+    user.version !== pair.userVersion ||
+    wallet.version !== pair.walletVersion ||
+    user.dependencies?.["@c4roa0/agentpay-protocol"] !== pair.typesDependency ||
+    wallet.dependencies?.["@c4roa0/agentpay-protocol"] !== pair.typesDependency
+  ) {
+    throw Error(
+      "User and Wallet do not match the downloaded update. Reinstall the reviewed User package version, then retry agentpay repair.",
+    );
+  }
+  return pair;
+}
+export async function updateSnapshot(userDir) {
+  const { directory: walletDir } = walletPackage(userDir);
+  const inputs = createHash("sha256")
+    .update(
+      JSON.stringify([
+        userDir,
+        process.execPath,
+        process.versions.node,
+        await fingerprint(userDir, [
+          "package.json",
+          "update-pair.json",
+          "src",
+          "scripts",
+        ]),
+        await fingerprint(walletDir, [
+          "package.json",
+          "lib",
+          "bin",
+        ]),
+      ]),
+    )
+    .digest("hex");
+  let outputs = null;
+  try {
+    outputs = await fingerprint(walletDir, ["lib", "bin"]);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  return { inputs, outputs };
+}
+async function askUpdate(prompt) {
+  if (!process.stdin.isTTY)
+    throw Error(
+      "Run agentpay repair in a terminal to confirm, or use agentpay repair -f to skip confirmation.",
+    );
+  const terminal = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return await terminal.question(prompt + "\n> ");
+  } finally {
+    terminal.close();
+  }
+}
+async function manage(action, { userDir, dataDir, logPath }) {
+  const file = await open(logPath, "a", 0o600);
+  try {
+    await new Promise((done, reject) => {
+      const child = spawn(
+        process.execPath,
+        [join(userDir, "scripts/autostart.mjs"), action],
+        {
+          shell: false,
+          env: { ...process.env, AGENTPAY_USER_DATA_DIR: dataDir },
+          stdio: ["ignore", file.fd, file.fd],
+        },
+      );
+      child.once("error", reject);
+      child.once("exit", (code) =>
+        code === 0
+          ? done()
+          : reject(Error("Background service operation failed.")),
+      );
+    });
+  } finally {
+    await file.close();
+  }
+}
+export async function applyLocalUpdate({
+  userDir = installedUserDir,
+  dataDir,
+  write = console.log,
+  platform = process.platform,
+  force = false,
+  ask = askUpdate,
+  snapshot = updateSnapshot,
+  officialTest = prepareOfficialTestUpdate,
+  resolveDirectory = resolveUserDataDir,
+  pairCheck = checkUpdatePair,
+  checkDirectory = checkServiceDirectory,
+  settings = readServiceSettings,
+  connection = ensureRuntimeConnection,
+  prepare = runInstall,
+  service = manage,
+  wallet = localWalletAdmin,
+  runtime = readRuntimeStatus,
+  pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  let phase = "preflight",
+    logPath,
+    selected;
+  try {
+    write(
+      "\n------------------------------------------------------------\n> Repair User and Wallet\n------------------------------------------------------------",
+    );
+    write(
+      "Checks the installed User and Wallet packages, refreshes service paths and checks the official test Skill.",
+    );
+    if (platform !== "linux")
+      throw Error(
+        "This repair command currently supports Linux user services. macOS startup support is not ready.",
+      );
+    dataDir ??= await resolveDirectory({ userDir });
+    const pair = await pairCheck(userDir);
+    await checkDirectory(dataDir);
+    await settings(dataDir);
+    write(
+      `1/3 Check local files · User ${pair.userVersion} / Wallet ${pair.walletVersion}`,
+    );
+    const result = await prepare({
+      userDir,
+      dataDir,
+      prepareOnly: true,
+
+      write: () => {},
+      beforePrepare: async (context) => {
+        logPath = context.logPath;
+        // Recheck after taking the shared installer lock, before stopping anything.
+        await pairCheck(userDir);
+        selected = await snapshot(userDir);
+        const applied = context.state.localUpdate;
+        if (
+          context.initial.ok &&
+          applied?.status === "complete" &&
+          applied.inputs === selected.inputs &&
+          applied.outputs === selected.outputs
+        ) {
+          let runningMatches = false;
+          try {
+            requireRunningSoftware(await wallet(dataDir, "status"), await runtime(dataDir), { ...pair, protocolVersion: pair.typesDependency });
+            runningMatches = true;
+          } catch { /* Keep repair available for old, stopped or unreported processes. */ }
+          if (runningMatches) {
+            await connection({ dataDir, write });
+            phase = "unchanged";
+            write("Local installation and running versions are up to date. Background services were not changed.");
+            return false;
+          }
+          write("Running versions need verification. Repair will restart the paired services.");
+        }
+        write(
+          applied?.status === "pending"
+            ? "A previous repair did not finish. Retry preparation."
+            : "Installed program changes need to be applied.",
+        );
+        write(
+          "Wallet and Runtime will pause, verify installed files and restart. Wallet will need unlocking afterwards.",
+        );
+        if (!force) {
+          while (true) {
+            const answer = (
+              await ask("Type 'confirm' to repair, or 'q' to cancel")
+            )
+              .trim()
+              .toLowerCase();
+            if (answer === "q") {
+              phase = "cancelled";
+              write("Repair cancelled. Background services were not changed.");
+              return false;
+            }
+            if (answer === "confirm") break;
+            write("Enter 'confirm' or 'q'.");
+          }
+        }
+        const confirmed = await snapshot(userDir);
+        if (JSON.stringify(confirmed) !== JSON.stringify(selected))
+          throw Error(
+            "Local files changed during confirmation. Run agentpay repair again.",
+          );
+        await connection({ dataDir, write, refreshClientModule: true, checkOnly: true });
+        context.state.localUpdate = {
+          status: "pending",
+          inputs: selected.inputs,
+        };
+        await context.saveState();
+        await service("prepare-repair", { userDir, dataDir, logPath });
+        phase = "stopping";
+        write(
+          "2/3 Pause background services and check installed packages. This may take a few minutes.",
+        );
+        await service("stop", { userDir, dataDir, logPath });
+        phase = "building";
+      },
+      afterPrepare: async (context) => {
+        logPath = context.logPath;
+        const built = await snapshot(userDir);
+        if (built.inputs !== selected.inputs)
+          throw Error("Installed files changed during repair.");
+        await connection({ dataDir, write, refreshClientModule: true });
+        phase = "starting";
+        write("3/3 Start Wallet and Runtime.");
+        await service("start", { userDir, dataDir, logPath });
+        let ready = false;
+        const deadline = Date.now() + 15000;
+        for (
+          let attempt = 0;
+          attempt < 20 && Date.now() < deadline;
+          attempt++
+        ) {
+          try {
+            const [w, r] = await Promise.all([
+              wallet(dataDir, "status"),
+              runtime(dataDir),
+            ]);
+            if (typeof w.locked === "boolean" && r.role === "user-runtime") {
+              requireRunningSoftware(w, r, { ...pair, protocolVersion: pair.typesDependency });
+              ready = true;
+              break;
+            }
+          } catch (error) {
+            if (error.code === "RUNNING_VERSION_UNVERIFIED") throw error;
+            /* Startup can take a moment; final failure is reported below. */
+          }
+          await pause(500);
+        }
+        if (!ready) throw Error("Service readiness could not be confirmed.");
+        context.state.localUpdate = { status: "complete", ...built };
+        await context.saveState();
+        phase = "ready";
+      },
+    });
+    if (result?.skipped && phase === "cancelled") return 0;
+    if (result?.skipped && phase === "unchanged") {
+      await officialTest({ userDir, dataDir, write });
+      return 0;
+    }
+    if (!result?.completed || phase !== "ready")
+      throw Error("Repair did not finish.");
+    write(
+      "\nRepair complete. Wallet and Runtime are running in the background.",
+    );
+    write(
+      "Keys, spending permission and Order records were kept. Login startup preference is unchanged.",
+    );
+    await officialTest({ userDir, dataDir, write });
+    write("Next: agentpay wallet unlock\nThen: agentpay status");
+    return 0;
+  } catch (error) {
+    if (phase === "preflight")
+      write("Repair stopped before pausing services. " + error.message);
+    else if (phase === "building")
+      write(
+        "Repair could not finish. Wallet and Runtime remain stopped; your local data was kept.",
+      );
+    else
+      write(
+        "Service changes could not be confirmed. Check agentpay status and agentpay service logs runtime before retrying.",
+      );
+    if (error.code === "RUNNING_VERSION_UNVERIFIED") write(error.message);
+    const log = error.logPath || logPath;
+    if (log) write("Details: " + log);
+    write("After resolving the problem, run agentpay repair again.");
+    return 1;
+  }
+}

package/src/local-wallet-ipc.mjs

@@ -0,0 +1,93 @@
+// 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 { checkServiceDirectory } from "./local-services.mjs";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+export async function localWalletAdmin(dataDir, method, params = {}) {
+  await checkServiceDirectory(dataDir);
+  const h = await open(
+    join(dataDir, "wallet/admin.token"),
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  );
+  let token;
+  try {
+    const s = await h.stat();
+    if (
+      !s.isFile() ||
+      s.uid !== process.getuid() ||
+      s.mode & 0o077 ||
+      s.size > 4096
+    )
+      throw Error("Local Wallet access file is unsafe.");
+    token = (await h.readFile("utf8")).trim();
+  } finally {
+    await h.close();
+  }
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(join(dataDir, "wallet/wallet.sock"));
+    let text = "",
+      done = false;
+    const finish = (e, value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      socket.destroy();
+      e ? reject(e) : resolve(value);
+    };
+    const timer = setTimeout(
+      () => finish(Error("Wallet did not respond. Run agentpay status.")),
+      30000,
+    );
+    socket.setEncoding("utf8");
+    socket.once("error", (e) =>
+      finish(
+        Object.assign(
+          Error(
+            "Start Wallet with agentpay service start, then run agentpay wallet unlock.",
+          ),
+          {
+            code: ["ENOENT", "ECONNREFUSED"].includes(e.code)
+              ? "WALLET_NOT_RUNNING"
+              : "WALLET_CONNECTION_FAILED",
+          },
+        ),
+      ),
+    );
+    socket.once("connect", () =>
+      socket.write(
+        JSON.stringify({
+          id: randomBytes(8).toString("hex"),
+          token,
+          method,
+          params,
+        }) + "\n",
+      ),
+    );
+    socket.on("data", (part) => {
+      text += part;
+      if (Buffer.byteLength(text) > 65536)
+        finish(Error("Wallet response was too large."));
+    });
+    socket.once("close", () => {
+      if (!done)
+        finish(Error("Wallet closed the connection. Check agentpay status."));
+    });
+    socket.once("end", () => {
+      try {
+        const r = JSON.parse(text);
+        if (!r.ok)
+          throw Object.assign(
+            Error(r.error?.message || "Wallet rejected the connection."),
+            { code: r.error?.code },
+          );
+        finish(null, r.result);
+      } catch (e) {
+        finish(e);
+      }
+    });
+  });
+}

package/src/login-reminder.mjs

@@ -0,0 +1,28 @@
+// 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/.
+export async function remindLockedWallet({
+  env = process.env,
+  status,
+  notify,
+  pause = (ms) => new Promise((r) => setTimeout(r, ms)),
+}) {
+  if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return "headless";
+  // The graphical-session oneshot stays active until logout, independently of service restarts.
+  for (let i = 0; i < 15; i++) {
+    try {
+      const state = await status();
+      if (state?.locked === false) return "unlocked";
+      if (state?.locked === true) {
+        try {
+          await notify();
+          return "notified";
+        } catch {
+          return "unavailable";
+        }
+      }
+    } catch {}
+    if (i < 14) await pause(2000);
+  }
+  return "wallet_unavailable";
+}

package/src/market-download-url.mjs

@@ -0,0 +1,21 @@
+// 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/.
+// Preserve the approved metadata URL's ingress prefix; metadata cannot select a host.
+export function marketDownloadUrl(metadataUrl, serviceId) {
+  const url = new URL(metadataUrl);
+  const suffix = `/skills/bundles/${encodeURIComponent(serviceId)}/metadata`;
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !url.pathname.endsWith(suffix)
+  )
+    throw Error("MARKET_METADATA_PATH_MISMATCH");
+  const prefix = url.pathname.slice(0, -suffix.length);
+  if (!["", "/market"].includes(prefix))
+    throw Error("MARKET_METADATA_PREFIX_INVALID");
+  url.pathname = prefix + suffix.replace(/\/metadata$/, "/download");
+  return url;
+}

package/src/node-version.mjs

@@ -0,0 +1,12 @@
+// 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/.
+export const NODE_REQUIREMENT = "Node 22.22.3 or newer";
+export function supportedNodeVersion(version) {
+  if (typeof version !== "string" || !/^[0-9]+\.[0-9]+\.[0-9]+$/.test(version))
+    return false;
+  const [major, minor, patch] = version.split(".").map(Number);
+  return (
+    major > 22 || (major === 22 && (minor > 22 || (minor === 22 && patch >= 3)))
+  );
+}