@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/src/invocation-store.mjs

@@ -0,0 +1,385 @@
+// Durable purchase identity and checkpoint store. Conflicts must preserve the original
+// request; losing an acknowledgement is not permission to issue a new paid attempt.
+// 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 { currentTimeMs, localTimeMs } from "./local-time.mjs";
+import { constants } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, rename, open, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const B32 = /^0x[0-9a-f]{64}$/;
+
+export function createInvocationStore(path, serviceBinding = null) {
+  if (!String(path || "").trim())
+    throw new Error("AGENTPAY_USER_STATE_FILE is required");
+  let tail = Promise.resolve();
+
+  async function locked(operation) {
+    const previous = tail;
+    let release;
+    tail = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+
+  async function load() {
+    try {
+      const handle = await open(
+        path,
+        constants.O_RDONLY | constants.O_NOFOLLOW,
+      );
+      let parsed;
+      try {
+        const info = await handle.stat();
+        if (
+          !info.isFile() ||
+          info.uid !== process.getuid() ||
+          info.mode & 0o077 ||
+          info.size > 32 * 1048576
+        )
+          throw coded(
+            "INVOCATION_STATE_INVALID",
+            "Invocation history must be a private regular file within the size limit",
+          );
+        parsed = JSON.parse(await handle.readFile("utf8"));
+      } finally {
+        await handle.close();
+      }
+      if (
+        parsed?.version !== "agentpay.user-invocations.v1" ||
+        !parsed.invocations ||
+        typeof parsed.invocations !== "object" ||
+        Array.isArray(parsed.invocations) ||
+        Object.entries(parsed.invocations).some(
+          ([id, entry]) =>
+            !B32.test(id) ||
+            !entry ||
+            typeof entry !== "object" ||
+            Array.isArray(entry) ||
+            entry.invocationId !== id ||
+            !B32.test(entry.requestHash) ||
+            !B32.test(entry.orderRequestId) ||
+            !B32.test(entry.commitmentNonce) ||
+            (entry.orderId !== null && !B32.test(entry.orderId)) ||
+            typeof entry.paymentSubmitted !== "boolean" ||
+            (entry.paymentPayload !== null &&
+              typeof entry.paymentPayload !== "object"),
+        )
+      ) {
+        throw coded(
+          "INVOCATION_STATE_INVALID",
+          "User invocation state is incompatible or damaged; preserve the file and recover it manually",
+        );
+      }
+      for (const entry of Object.values(parsed.invocations))
+        if (
+          entry.routingVersion !== undefined &&
+          (entry.routingVersion !== "agentpay.runtime-call.v1" ||
+            typeof entry.serviceBinding !== "string")
+        )
+          throw coded(
+            "INVOCATION_STATE_INVALID",
+            "Invalid per-service routing state",
+          );
+      if (
+        parsed.timeEncoding !== undefined &&
+        parsed.timeEncoding !== "unix-ms"
+      )
+        throw coded(
+          "INVOCATION_STATE_INVALID",
+          "Unsupported invocation timestamp encoding; preserve the file",
+        );
+      for (const entry of Object.values(parsed.invocations)) {
+        try {
+          for (const key of ["createdAt", "updatedAt"]) {
+            if (
+              parsed.timeEncoding === "unix-ms" &&
+              !Object.hasOwn(entry, key + "Ms")
+            )
+              throw Error("Missing invocation epoch");
+            const ms = localTimeMs(entry, key);
+            entry[key + "Ms"] = ms;
+            entry[key] = new Date(ms).toISOString();
+          }
+        } catch {
+          throw coded(
+            "INVOCATION_STATE_INVALID",
+            "Invocation timestamp is invalid; preserve the file and recover it manually",
+          );
+        }
+      }
+      return parsed;
+    } catch (error) {
+      if (error?.code === "ENOENT")
+        return { version: "agentpay.user-invocations.v1", invocations: {} };
+      if (error instanceof SyntaxError)
+        throw coded(
+          "INVOCATION_STATE_INVALID",
+          "User invocation state is invalid JSON; preserve the file and recover it manually",
+        );
+      throw error;
+    }
+  }
+
+  async function save(document) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    const stored = {
+      ...document,
+      timeEncoding: "unix-ms",
+      invocations: Object.fromEntries(
+        Object.entries(document.invocations).map(([id, entry]) => {
+          const data = { ...entry };
+          for (const key of ["createdAt", "updatedAt"]) {
+            data[key + "Ms"] = localTimeMs(entry, key);
+            delete data[key];
+          }
+          return [id, data];
+        }),
+      ),
+    };
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+      try {
+        await handle.writeFile(`${JSON.stringify(stored, null, 2)}\n`);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, path);
+      const directory = await open(dirname(path), "r");
+      try {
+        await directory.sync();
+      } finally {
+        await directory.close();
+      }
+    } finally {
+      await unlink(temporary).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+  }
+
+  function checkBinding(entry, expected = serviceBinding, routing = null) {
+    if (
+      (entry.routingVersion ?? null) !== routing ||
+      (expected !== null && entry.serviceBinding !== expected) ||
+      (expected === null && entry.serviceBinding != null)
+    ) {
+      throw coded(
+        "INVOCATION_SERVICE_BINDING_MISMATCH",
+        "Preserve invocation history and restore its selected Skill before retrying",
+      );
+    }
+  }
+  return Object.freeze({
+    async inventory() {
+      const document = await load();
+      return structuredClone(document.invocations);
+    },
+    async verifyServiceBinding() {
+      const document = await load();
+      for (const entry of Object.values(document.invocations)) {
+        if (
+          entry.routingVersion === "agentpay.runtime-call.v1" &&
+          typeof entry.serviceBinding === "string"
+        )
+          continue;
+        checkBinding(entry);
+      }
+    },
+    async lookup({
+      invocationKey,
+      requestHash,
+      binding = serviceBinding,
+      routingVersion = null,
+    }) {
+      return locked(async () => {
+        const existing = (await load()).invocations[
+          hashInvocationKey(invocationKey)
+        ];
+        if (!existing)
+          throw coded(
+            "ORIGINAL_REQUEST_NOT_FOUND",
+            "Original Runtime history is missing. Do not create a replacement purchase.",
+          );
+        checkBinding(existing, binding, routingVersion);
+        if (existing.requestHash !== requestHash)
+          throw coded("INVOCATION_CONFLICT", "Original request input differs.");
+        return structuredClone(existing);
+      });
+    },
+    async begin({
+      invocationKey,
+      requestHash,
+      binding = serviceBinding,
+      routingVersion = null,
+      recoveryScope = null,
+      readRecoveryScope = null,
+      originalOrderRequestId = null,
+    }) {
+      if (
+        routingVersion !== null &&
+        routingVersion !== "agentpay.runtime-call.v1"
+      )
+        throw coded(
+          "INVOCATION_STATE_INVALID",
+          "Unsupported invocation routing version",
+        );
+      return locked(async () => {
+        const document = await load();
+        const invocationId = hashInvocationKey(invocationKey);
+        const existing = document.invocations[invocationId];
+        if (
+          originalOrderRequestId !== null &&
+          (!B32.test(originalOrderRequestId) ||
+            !existing ||
+            existing.orderRequestId !== originalOrderRequestId)
+        )
+          throw coded(
+            "ORIGINAL_REQUEST_NOT_FOUND",
+            "The original Runtime record changed or disappeared. No replacement purchase was created.",
+          );
+        if (existing) {
+          checkBinding(existing, binding, routingVersion);
+          if (existing.requestHash !== requestHash)
+            throw coded(
+              "INVOCATION_CONFLICT",
+              "Idempotency-Key was already used with a different request",
+            );
+          return structuredClone(existing);
+        }
+        if (readRecoveryScope) {
+          recoveryScope = await readRecoveryScope();
+          if (
+            !recoveryScope ||
+            Object.keys(recoveryScope).sort().join(",") !==
+              "module,network,policyId,safe" ||
+            !/^eip155:[1-9][0-9]*$/.test(recoveryScope.network) ||
+            ![recoveryScope.safe, recoveryScope.module].every((v) =>
+              /^0x[0-9a-f]{40}$/i.test(v),
+            ) ||
+            !B32.test(String(recoveryScope.policyId).toLowerCase())
+          )
+            throw coded(
+              "RUNTIME_RECOVERY_REQUIRED",
+              "Wallet authorization is unavailable. Complete or update Wallet setup before starting a new request.",
+            );
+        }
+        const atMs = currentTimeMs();
+        const at = new Date(atMs).toISOString();
+        const created = {
+          invocationId,
+          requestHash,
+          orderRequestId: randomB32(),
+          commitmentNonce: randomB32(),
+          orderId: null,
+          paymentPayload: null,
+          paymentSubmitted: false,
+          ...(recoveryScope ? { recoveryScope } : {}),
+          ...(binding !== null ? { serviceBinding: binding } : {}),
+          ...(routingVersion
+            ? { routingVersion, quoteAcceptanceRequired: true }
+            : {}),
+          createdAt: at,
+          updatedAt: at,
+          createdAtMs: atMs,
+          updatedAtMs: atMs,
+        };
+        document.invocations[invocationId] = created;
+        await save(document);
+        return structuredClone(created);
+      });
+    },
+    async attachRecoveredOrder(expected, orderId, recoveryScope) {
+      if (!B32.test(orderId))
+        throw coded("ORDER_IDENTITY_MISMATCH", "Invalid recovered Order");
+      return locked(async () => {
+        const document = await load(),
+          existing = document.invocations[expected.invocationId];
+        if (
+          !existing ||
+          existing.orderId ||
+          JSON.stringify(existing) !== JSON.stringify(expected)
+        )
+          return false;
+        document.invocations[expected.invocationId] = {
+          ...existing,
+          orderId,
+          ...(recoveryScope ? { recoveryScope } : {}),
+          updatedAtMs: currentTimeMs(),
+        };
+        document.invocations[expected.invocationId].updatedAt = new Date(
+          document.invocations[expected.invocationId].updatedAtMs,
+        ).toISOString();
+        await save(document);
+        return true;
+      });
+    },
+    async update(invocationId, expectedRequestHash, changes) {
+      return locked(async () => {
+        const document = await load();
+        const existing = document.invocations[invocationId];
+        if (!existing || existing.requestHash !== expectedRequestHash)
+          throw coded(
+            "INVOCATION_NOT_FOUND",
+            "durable invocation checkpoint was not found",
+          );
+        if (
+          existing.recoveryScope &&
+          changes.recoveryScope &&
+          JSON.stringify(existing.recoveryScope) !==
+            JSON.stringify(changes.recoveryScope)
+        )
+          throw coded(
+            "ORDER_IDENTITY_MISMATCH",
+            "Original authorization cannot be replaced",
+          );
+        const atMs = currentTimeMs();
+        const updated = {
+          ...existing,
+          ...changes,
+          invocationId: existing.invocationId,
+          requestHash: existing.requestHash,
+          orderRequestId: existing.orderRequestId,
+          ...(existing.serviceBinding !== undefined
+            ? { serviceBinding: existing.serviceBinding }
+            : {}),
+          ...(existing.routingVersion !== undefined
+            ? { routingVersion: existing.routingVersion }
+            : {}),
+          updatedAt: new Date(atMs).toISOString(),
+          updatedAtMs: atMs,
+        };
+        document.invocations[invocationId] = updated;
+        await save(document);
+        return structuredClone(updated);
+      });
+    },
+  });
+}
+
+function hashInvocationKey(value) {
+  const normalized = String(value || "").trim();
+  if (!/^[A-Za-z0-9._:-]{8,128}$/.test(normalized))
+    throw coded(
+      "INVALID_IDEMPOTENCY_KEY",
+      "Idempotency-Key must contain 8-128 safe characters",
+    );
+  return `0x${createHash("sha256").update(`agentpay.user-invocation.v1:${normalized}`).digest("hex")}`;
+}
+
+function randomB32() {
+  return `0x${randomBytes(32).toString("hex")}`;
+}
+function coded(code, message) {
+  return Object.assign(new Error(message), { code });
+}

package/src/local-data-directory.mjs

@@ -0,0 +1,117 @@
+import { installationDirectory, legacyInstallationDirectory } from "./installation-paths.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 { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+export const installedUserDir = fileURLToPath(new URL("..", import.meta.url));
+const stateDirectory = installationDirectory;
+function privateInfo(info) {
+  return (
+    info.uid === process.getuid() &&
+    (info.mode & 0o077) === 0 &&
+    !info.isSymbolicLink()
+  );
+}
+async function readState(userDir, directory = stateDirectory(userDir)) {
+  try {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || !privateInfo(info))
+      throw Error(
+        "Installation record directory must be private and owned by you.",
+      );
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if (directory === stateDirectory(userDir)) return readState(userDir, legacyInstallationDirectory(userDir));
+      return {};
+    }
+    throw error;
+  }
+  let file;
+  try {
+    file = await open(
+      join(directory, "state.json"),
+      constants.O_RDONLY | constants.O_NOFOLLOW,
+    );
+    const info = await file.stat();
+    if (!info.isFile() || !privateInfo(info) || info.size > 65536)
+      throw Error("Installation record is not a private regular file.");
+    const state = JSON.parse(await file.readFile("utf8"));
+    if (
+      state.version !== 1 ||
+      (state.dataDir !== undefined &&
+        (typeof state.dataDir !== "string" ||
+          !isAbsolute(state.dataDir) ||
+          state.dataDir.includes("\0")))
+    )
+      throw Error("Installation record is invalid.");
+    return state;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if (directory === stateDirectory(userDir)) return readState(userDir, legacyInstallationDirectory(userDir));
+      return {};
+    }
+    throw error;
+  } finally {
+    await file?.close();
+  }
+}
+export async function resolveUserDataDir({
+  argument,
+  env = process.env,
+  userDir = installedUserDir,
+} = {}) {
+  if (argument || env.AGENTPAY_USER_DATA_DIR)
+    return resolve(argument || env.AGENTPAY_USER_DATA_DIR);
+  const state = await readState(userDir);
+  return state.dataDir || join(homedir(), ".local/share/agentpay/user");
+}
+// Uses the existing installer lock and preserves dependency/build checkpoints.
+export async function rememberUserDataDir({
+  userDir = installedUserDir,
+  dataDir,
+}) {
+  const directory = stateDirectory(userDir);
+  await mkdir(directory, { recursive:true, mode: 0o700 }).catch((e) => {
+    if (e.code !== "EEXIST") throw e;
+  });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || !privateInfo(info))
+    throw Error(
+      "Installation record directory must be private and owned by you.",
+    );
+  const lockPath = join(directory, "install.lock");
+  let lock;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw Error(
+        "Another installation may be running. Retry after it finishes.",
+      );
+    throw error;
+  }
+  const temp = join(directory, `location-${randomUUID()}.tmp`);
+  let file;
+  try {
+    const state = await readState(userDir);
+    file = await open(temp, "wx", 0o600);
+    await file.writeFile(
+      JSON.stringify({ ...state, version: 1, dataDir: resolve(dataDir) }) +
+        "\n",
+    );
+    await file.sync();
+    await file.close();
+    file = null;
+    await rename(temp, join(directory, "state.json"));
+  } finally {
+    await file?.close();
+    await unlink(temp).catch(() => {});
+    await lock.close();
+    await unlink(lockPath);
+  }
+}

package/src/local-info.mjs

@@ -0,0 +1,181 @@
+// 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 { open, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveUserDataDir } from "./local-data-directory.mjs";
+
+const address = (value) =>
+  typeof value === "string" && /^0x[0-9a-f]{40}$/i.test(value)
+    ? value
+    : "Not recorded";
+const policyId = (value) =>
+  typeof value === "string" && /^0x[0-9a-f]{64}$/i.test(value)
+    ? value
+    : "Not recorded";
+const text = (value) =>
+  typeof value === "string"
+    ? value.replace(/[\x00-\x1f\x7f-\x9f]/g, "").slice(0, 160)
+    : "Not recorded";
+function endpoint(value) {
+  try {
+    const u = new URL(value);
+    if (
+      !["http:", "https:"].includes(u.protocol) ||
+      u.username ||
+      u.password ||
+      u.search ||
+      u.hash
+    )
+      return "Not shown (inspect local settings)";
+    return u.origin + u.pathname;
+  } catch {
+    return "Not recorded";
+  }
+}
+async function privateJson(dataDir, relative) {
+  for (const directory of [
+    dataDir,
+    ...(relative.includes("/") ? [join(dataDir, relative.split("/")[0])] : []),
+  ]) {
+    try {
+      const st = await lstat(directory);
+      if (
+        !st.isDirectory() ||
+        st.isSymbolicLink() ||
+        st.uid !== process.getuid() ||
+        st.mode & 0o077
+      )
+        throw Error("unsafe");
+    } catch (e) {
+      if (e.code === "ENOENT") return null;
+      throw e;
+    }
+  }
+  let h;
+  try {
+    h = await open(
+      join(dataDir, relative),
+      constants.O_RDONLY | constants.O_NOFOLLOW,
+    );
+    const st = await h.stat();
+    if (
+      !st.isFile() ||
+      st.uid !== process.getuid() ||
+      st.mode & 0o077 ||
+      st.size > 65536
+    )
+      throw Error("unsafe");
+    return JSON.parse(await h.readFile("utf8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  } finally {
+    await h?.close();
+  }
+}
+// Display only selected public fields. Never dump files or query/unlock Wallet.
+export async function showLocalInfo({
+  resolveDirectory = resolveUserDataDir,
+  write = console.log,
+} = {}) {
+  let dataDir;
+  try {
+    dataDir = await resolveDirectory();
+  } catch {
+    write(
+      "Could not read your saved User directory. Check the installation record.",
+    );
+    return 1;
+  }
+  let incomplete = false;
+  const read = async (name) => {
+    try {
+      return await privateJson(dataDir, name);
+    } catch {
+      incomplete = true;
+      write(
+        `Could not safely read ${name}. Check its ownership, permissions and format.`,
+      );
+      return null;
+    }
+  };
+  const key = await read("wallet/session.keystore.json"),
+    policy = await read("wallet/policy.json"),
+    services = await read("runtime/local-services.json"),
+    connection = await read("runtime/connection.json"),
+    market = await read("market-connection.json");
+  const keyAddress = typeof key?.address === "string" ? key.address : "";
+  const delegate = address(
+    keyAddress.startsWith("0x") ? keyAddress : `0x${keyAddress}`,
+  );
+  const divider =
+    "------------------------------------------------------------";
+  const section = (title) => ["", divider, `> ${title}`, divider];
+  const field = (label, value) => [`  ${label}`, `    ${value}`];
+  const lines = [
+    divider,
+    "> Wallet information",
+    divider,
+    "Saved settings · live status: agentpay status",
+    ...section("Wallet & authorization"),
+    `  Network: ${Number.isSafeInteger(policy?.chainId) && policy.chainId > 0 ? `eip155:${policy.chainId}` : "Not recorded"}`,
+    ...field("Safe account", address(policy?.safe)),
+    ...field("Policy ID", policyId(policy?.policyId)),
+    ...field("Wallet execution address", delegate),
+    ...field("AgentPay Module", address(policy?.module)),
+  ];
+  if (
+    policy &&
+    delegate !== "Not recorded" &&
+    delegate.toLowerCase() !== String(policy.delegate).toLowerCase()
+  ) {
+    incomplete = true;
+    lines.push(
+      "  [!] Saved Policy delegate differs from this key. Review before using it.",
+    );
+  }
+  lines.push(
+    ...section("Local files"),
+    ...field("Data folder", dataDir),
+    "  Files inside this folder:",
+    "    wallet/session.keystore.json   Encrypted Session Key",
+    "    wallet/policy.json             Policy binding",
+    "    runtime/local-services.json    Startup settings",
+    "    runtime/invocations.json       Order history",
+    "    runtime/invocations.json.results/  Verified result records",
+    "    runtime/invocations.json.pending-results/  Results awaiting verification",
+    "    runtime/invocations.json.files/  Saved file copies · agentpay orders files ORDER_ID",
+    ...section("Service connections"),
+    ...field(
+      "Local Runtime · Skills connect here",
+      endpoint(services?.runtimeUrl || connection?.runtimeUrl),
+    ),
+    ...field(
+      "Settlement · Platform order service",
+      endpoint(services?.settlementUrl),
+    ),
+    ...section("Market"),
+  );
+  if (market)
+    lines.push(
+      ...field("Saved website", endpoint(market.marketOrigin)),
+      `  Wallet nickname: ${text(market.connection?.label)}`,
+      ...field("Saved connection ID", text(market.connection?.id)),
+      "  Current connection status is shown on the website.",
+    );
+  else lines.push("  No saved connection. To connect: agentpay market connect");
+  lines.push(
+    ...section("Backup"),
+    "  Keep a private backup of this data folder and your unlock password.",
+    "  This includes your key, Order records, private results and download links. Do not share it.",
+  );
+  if (!key)
+    lines.push(
+      "",
+      "No readable Session Key found. Check your data directory before creating a new Wallet.",
+    );
+  write(lines.join("\n"));
+  return incomplete ? 1 : 0;
+}