@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

package/src/authorization-question-checkpoint.mjs

@@ -0,0 +1,114 @@
+// 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/.
+// Only public authorization fields are persisted; never Wallet unlock input.
+export function authorizationFields({
+  context,
+  checkpoint,
+  ask,
+  save,
+  write,
+  details,
+}) {
+  const allowed = ["safe", "policyChoice", "budget", "perPayment", "days"];
+  if (
+    checkpoint &&
+    (checkpoint.version !== 2 ||
+      checkpoint.context !== context ||
+      !checkpoint.fields ||
+      typeof checkpoint.fields !== "object" ||
+      Array.isArray(checkpoint.fields) ||
+      Object.entries(checkpoint.fields).some(
+        ([key, value]) =>
+          !allowed.includes(key) ||
+          typeof value !== "string" ||
+          value.length > 256,
+      ))
+  ) {
+    throw Error("AUTHORIZATION_INPUT_CHECKPOINT_MISMATCH");
+  }
+  let state = checkpoint || { version: 2, context, fields: {} };
+  if (Object.keys(state.fields).length)
+    write("Continuing saved Safe and spending limits.");
+  const visited = [];
+  return async (key, prompt, validate, providedValue) => {
+    const previous = visited.at(-1);
+    if (providedValue === undefined) visited.push(key);
+    if (!allowed.includes(key)) throw Error("AUTHORIZATION_FIELD_INVALID");
+    if (Object.hasOwn(state.fields, key)) {
+      try {
+        validate(state.fields[key]);
+      } catch {
+        throw Error(`SAVED_AUTHORIZATION_FIELD_INVALID: ${key}`);
+      }
+      if (
+        providedValue !== undefined &&
+        validate(state.fields[key]) !== validate(providedValue)
+      )
+        throw Error(
+          `SAVED_AUTHORIZATION_FIELD_MISMATCH: ${key}. Saved settings and authorization inputs differ; review before continuing.`,
+        );
+      return state.fields[key];
+    }
+    if (providedValue !== undefined) {
+      const normalized = validate(providedValue);
+      const next = {
+        ...state,
+        fields: { ...state.fields, [key]: String(normalized) },
+      };
+      await save(next);
+      state = next;
+      return state.fields[key];
+    }
+    while (true) {
+      const value = (
+        await ask(
+          `${prompt}\n('back' for previous, 'details' for information, 'q' to return)\n> `,
+        )
+      ).trim();
+      if (value.toLowerCase() === "back") {
+        if (!previous) {
+          write("This is the first editable item.");
+          continue;
+        }
+        const start = allowed.indexOf(previous);
+        const next = {
+          ...state,
+          fields: Object.fromEntries(
+            Object.entries(state.fields).filter(
+              ([name]) => allowed.indexOf(name) < start,
+            ),
+          ),
+        };
+        await save(next);
+        throw Object.assign(Error("Return to previous item"), {
+          code: "AUTHORIZATION_BACK",
+          checkpoint: next,
+        });
+      }
+      if (value.toLowerCase() === "q")
+        throw Object.assign(Error("Setup paused; saved inputs are retained."), {
+          code: "CANCELLED",
+        });
+      if (value.toLowerCase() === "details") {
+        write(JSON.stringify(details, null, 2));
+        continue;
+      }
+      let normalized;
+      try {
+        if (value.length > 256) throw Error();
+        normalized = validate(value) ?? value;
+      } catch (error) {
+        write(error.message || "Check this value and try again.");
+        continue;
+      }
+      const next = {
+        ...state,
+        fields: { ...state.fields, [key]: String(normalized) },
+      };
+      await save(next);
+      state = next;
+      return state.fields[key];
+    }
+  };
+}

package/src/autostart-files.mjs

@@ -0,0 +1,50 @@
+// 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 { isAbsolute, join } from "node:path";
+function checked(value) {
+  if (
+    typeof value !== "string" ||
+    !isAbsolute(value) ||
+    /[\x00-\x1f\x7f]/.test(value)
+  )
+    throw Error("Autostart paths must be absolute without control characters.");
+  return value;
+}
+const unitArg = (value) =>
+  '"' +
+  checked(value)
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("%", "%%")
+    .replaceAll("$", () => "$$") +
+  '"';
+export const runtimeUnits = [
+  "agentpay-local-wallet.service",
+  "agentpay-local-runtime.service",
+];
+export const reminderUnit = "agentpay-wallet-reminder.service";
+export const units = [...runtimeUnits, reminderUnit];
+export function autostartFiles({ node, userDir, dataDir }) {
+  const entries = {};
+  for (const role of ["wallet", "runtime"])
+    entries[`agentpay-local-${role}.service`] =
+      `# Managed by AgentPay User\n[Unit]\nDescription=AgentPay local ${role}\n${role === "runtime" ? "Wants=agentpay-local-wallet.service\nAfter=agentpay-local-wallet.service\n" : ""}StartLimitIntervalSec=60\nStartLimitBurst=3\n\n[Service]\nType=simple\nExecStart=${[node, join(userDir, "scripts/local-service.mjs")].map(unitArg).join(" ")} ${role} ${unitArg(dataDir)}\nRestart=on-failure\nRestartSec=10\nUMask=0077\nKillMode=control-group\nTimeoutStopSec=30\n\n[Install]\nWantedBy=default.target\n`;
+  entries[reminderUnit] =
+    `# Managed by AgentPay User\n[Unit]\nDescription=AgentPay Wallet login reminder\nPartOf=graphical-session.target\nAfter=graphical-session-pre.target agentpay-local-wallet.service\n\n[Service]\nType=oneshot\nExecStart=${[node, join(userDir, "scripts/login-notify.mjs"), dataDir].map(unitArg).join(" ")}\nRemainAfterExit=yes\nTimeoutStartSec=90\nUMask=0077\n\n[Install]\nWantedBy=graphical-session.target\n`;
+  return entries;
+}
+
+// Accept only an exact previously generated unit for this same private directory.
+// This lets repair relocate program/Node paths without accepting custom unit bodies.
+export function isManagedUnit(body, name, dataDir) {
+  try {
+    const line = body.split('\n').find(line => line.startsWith('ExecStart='));
+    const quoted = [...line.matchAll(/"(?:\\.|[^"\\])*"/g)].map(([text]) => JSON.parse(text).replaceAll('%%','%').replaceAll('$$','$'));
+    const [node, script] = quoted;
+    const suffix = name === reminderUnit ? '/scripts/login-notify.mjs' : '/scripts/local-service.mjs';
+    if (!script.endsWith(suffix)) return false;
+    const userDir = script.slice(0, -suffix.length);
+    return autostartFiles({node, userDir, dataDir})[name] === body;
+  } catch { return false; }
+}

package/src/cache-management-cli.mjs

@@ -0,0 +1,302 @@
+// 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, unlink, realpath } from "node:fs/promises";
+import { join, resolve, dirname, sep, extname } from "node:path";
+import { createHash } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { resolveUserDataDir } from "./local-data-directory.mjs";
+import { loadRuntimeConnection, cacheManagement } from "./runtime-client.mjs";
+import { createFileCache } from "./file-cache.mjs";
+import { readCacheLimits } from "./file-cache-settings.mjs";
+import { manageCache } from "./cache-management.mjs";
+import { withResultCacheView } from "./result-cache-view.mjs";
+const safe = (v) => String(v ?? "").replace(/[\x00-\x1f\x7f-\x9f]/g, "");
+const size = (n) =>
+  n < 1024
+    ? `${n} B`
+    : n < 1048576
+      ? `${(n / 1024).toFixed(1)} KiB`
+      : `${(n / 1048576).toFixed(1)} MiB`;
+const contentSize = (row) => {
+  if (row.kind === "result")
+    return `Text (JSON) · content ${Number.isSafeInteger(row.contentBytes) ? size(row.contentBytes) : "unknown"} · cached ${size(row.storageBytes ?? row.bytes)}`;
+  const extension = extname(row.filename || "")
+    .slice(1)
+    .toUpperCase();
+  const type = /^[A-Z0-9]{1,12}$/.test(extension)
+    ? `File (.${extension.toLowerCase()})`
+    : "File";
+  return `${type} · ${row.purpose === "input" ? "input" : "output"} · cached ${size(row.bytes)}`;
+};
+const prompt = async (message) => {
+  const r = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await r.question(message + "\n> ");
+  } finally {
+    r.close();
+  }
+};
+export async function exportCacheFile(row, target) {
+  const destination = resolve(target),
+    parent = await realpath(dirname(destination)),
+    cacheDir = await realpath(dirname(row.localPath));
+  if (parent === cacheDir || parent.startsWith(cacheDir + sep))
+    throw Error("Choose an export location outside the managed cache.");
+  let input,
+    output,
+    created = false;
+  try {
+    input = await open(
+      row.localPath,
+      constants.O_RDONLY | (constants.O_NOFOLLOW || 0),
+    );
+    const st = await input.stat();
+    if (
+      !st.isFile() ||
+      st.nlink !== 1 ||
+      st.size !== row.bytes ||
+      (typeof process.getuid === "function" &&
+        (st.uid !== process.getuid() || st.mode & 0o077))
+    )
+      throw Error("Saved file is unavailable or changed.");
+    output = await open(destination, "wx", 0o600);
+    created = true;
+    const hash = createHash("sha256");
+    let bytes = 0;
+    for await (const chunk of input.createReadStream({ autoClose: false })) {
+      bytes += chunk.length;
+      if (bytes > row.bytes) throw Error("Saved file changed during export.");
+      hash.update(chunk);
+      await output.writeFile(chunk);
+    }
+    if (bytes !== row.bytes || hash.digest("hex") !== row.sha256)
+      throw Error("Saved file failed verification.");
+    await output.sync();
+    await output.close();
+    output = null;
+    const h = await open(parent, "r");
+    try {
+      await h.sync();
+    } finally {
+      await h.close();
+    }
+    return destination;
+  } catch (e) {
+    await output?.close();
+    output = null;
+    if (created) await unlink(destination).catch(() => {});
+    if (e.code === "EEXIST")
+      throw Error("Export destination already exists. Choose a new filename.");
+    throw e;
+  } finally {
+    await input?.close();
+    await output?.close();
+  }
+}
+export async function runCacheManagement(
+  args,
+  { write = console.log, ask = prompt, operate, dataDir } = {},
+) {
+  const values = [...args],
+    offline = values.includes("--offline");
+  if (offline) values.splice(values.indexOf("--offline"), 1);
+  const [action = "summary", ...rest] = values;
+  const filters = {};
+  let invalidFilter = false;
+  if (action === "list")
+    for (let i = 0; i < rest.length; ) {
+      const fields = {
+        "--state": "state",
+        "--request": "requestId",
+        "--order": "orderId",
+      };
+      if (Object.hasOwn(fields, rest[i])) {
+        const key = fields[rest[i]];
+        if (
+          filters[key] !== undefined ||
+          !rest[i + 1] ||
+          rest[i + 1].startsWith("--")
+        ) {
+          invalidFilter = true;
+          break;
+        }
+        filters[key] = rest[i + 1];
+        rest.splice(i, 2);
+      } else i++;
+    }
+  const usage =
+    "Usage: agentpay cache [info | list [PAGE] [input|output] [--state STATE] [--request ID | --order ID] | details ID | export ID PATH | clean | settings [KEY VALUE]]\nAdd --offline only when managing stopped Runtime storage. Wallet unlock is not required.";
+  if (
+    invalidFilter ||
+    !["summary", "list", "details", "export", "clean", "settings"].includes(
+      action,
+    ) ||
+    (["summary", "clean"].includes(action) && rest.length) ||
+    (action === "details" && rest.length !== 1) ||
+    (action === "export" && rest.length !== 2) ||
+    (action === "settings" && ![0, 2].includes(rest.length)) ||
+    (action === "list" &&
+      (rest.length > 2 ||
+        (rest[0] !== undefined && !/^[1-9][0-9]{0,5}$/.test(rest[0])) ||
+        (rest[1] !== undefined && !["input", "output"].includes(rest[1]))))
+  ) {
+    write(usage);
+    return 2;
+  }
+  try {
+    if (!operate) {
+      dataDir ??= await resolveUserDataDir();
+      if (offline) {
+        const state = join(dataDir, "runtime/invocations.json"),
+          cache = createFileCache(state, {
+            limits: await readCacheLimits(state),
+          });
+        operate = (body) => manageCache(cache, body);
+      } else {
+        const connection = await loadRuntimeConnection({ dataDir });
+        operate = (body) => cacheManagement(connection, body);
+      }
+    }
+    if (dataDir)
+      operate = withResultCacheView(
+        operate,
+        dataDir,
+        process.env.AGENTPAY_USER_STATE_FILE
+          ? { statePath: resolve(process.env.AGENTPAY_USER_STATE_FILE) }
+          : {},
+      );
+    write(
+      "\n------------------------------------------------------------\n> Local cache\n------------------------------------------------------------",
+    );
+    if (action === "summary") {
+      const r = await operate({ action });
+      write(
+        `\n> Saved locally\n  Text  ${r.resultRecords || 0} · ${size(r.resultBytes || 0)}\n  Files         ${r.records} · ${size(r.bytes)}\n\n> Attachment storage\n  ${size(r.bytes)} / ${size(r.limits.totalBytes)}${r.overLimit ? " · LIMIT EXCEEDED" : ""}`,
+      );
+      if (r.reservedBytes)
+        write(`  Transfers in progress: ${size(r.reservedBytes)}`);
+      if (r.unknownBytes)
+        write(
+          `[!] ${size(r.unknownBytes)} needs inspection; cleanup will keep it.`,
+        );
+      write("\n> Next\n  agentpay cache list");
+    } else if (action === "list") {
+      const page = Number(rest[0] || 1),
+        r = await operate({
+          action: "list",
+          offset: (page - 1) * 20,
+          limit: 20,
+          ...filters,
+          ...(rest[1] ? { purpose: rest[1] } : {}),
+        });
+      write(
+        `\n${r.total} entries · page ${page}\nDetails: agentpay cache details <Cache ID>`,
+      );
+      if (!r.items.length)
+        write("No saved results or attachments match this view.");
+      for (const [index, row] of r.items.entries()) {
+        const label = safe(
+          row.skillName ||
+            row.providerId ||
+            (row.skillId ? "Service " + row.skillId : "Source not recorded"),
+        );
+        const identity = row.orderId || row.requestId || "";
+        write(
+          `\n────────────────────────────────────────────────────────────\n${(page - 1) * 20 + index + 1}. ${label}\n   ${contentSize(row)}\n   ${new Date(row.updatedAtMs).toLocaleString()}${row.kind === "result" ? "" : " · " + safe(row.state)}${row.kind === "result" ? "" : "\n   " + safe(row.filename)}\n   ${row.orderId ? "Order" : "Request"}: ${safe(identity)}\n   Cache ID: ${row.id}`,
+        );
+      }
+      if (page * 20 < r.total)
+        write(
+          `\nNext page: agentpay cache list ${page + 1}${rest[1] ? " " + rest[1] : ""}${Object.entries(
+            filters,
+          )
+            .map(
+              ([k, v]) =>
+                " --" +
+                { state: "state", requestId: "request", orderId: "order" }[k] +
+                " " +
+                v,
+            )
+            .join("")}`,
+        );
+    } else if (action === "details") {
+      const r = await operate({ action, id: rest[0] });
+      write(
+        `${safe(r.filename)}\n  ${contentSize(r)} · ${r.state}\n  ${r.requestId ? "Request" : "Order"}: ${safe(r.requestId || r.orderId)}\n  File key: ${safe(r.fileKey)}\n  SHA-256: ${r.sha256 || "Not available"}\n  Updated: ${new Date(r.updatedAtMs).toLocaleString()}`,
+      );
+      if (r.protected)
+        write(
+          r.kind === "result"
+            ? "Saved result retained for recovery. Cleanup will not remove it."
+            : "Kept for original-request recovery. Cleanup will not remove this input.",
+        );
+      if (r.error) write("Issue: " + safe(r.error));
+      if (r.state === "available")
+        write(
+          `Export a copy: agentpay cache export ${r.id} /your/destination/filename`,
+        );
+    } else if (action === "export") {
+      const row = await operate({ action: "verified", id: rest[0] });
+      write("Exported: " + safe(await exportCacheFile(row, rest[1])));
+    } else if (action === "settings") {
+      if (rest.length && !/^[0-9]+$/.test(rest[1]))
+        throw Error("Use a positive integer value. Byte limits are in bytes.");
+      const r = await operate({
+        action,
+        ...(rest.length ? { overrides: { [rest[0]]: Number(rest[1]) } } : {}),
+      });
+      for (const [k, v] of Object.entries(r))
+        write(
+          `  ${k}: ${k.endsWith("Bytes") ? size(v) + " (" + v + " bytes)" : v}`,
+        );
+      write(
+        rest.length
+          ? "Limits saved and applied. Existing copies are kept."
+          : "Change a limit: agentpay cache settings totalBytes 1073741824\nfilesPerResult applies per input request or output Order.",
+      );
+    } else if (action === "clean") {
+      const items = await operate({ action: "preview" });
+      if (!items.length) {
+        write(
+          "No eligible file copies to clean. Protected inputs and history are kept.",
+        );
+        return 0;
+      }
+      write(
+        `${items.length} file copies · ${size(items.reduce((n, r) => n + r.bytes, 0))}\n` +
+          items
+            .map((r) => "  " + safe(r.filename) + " · " + size(r.bytes))
+            .join("\n"),
+      );
+      if (
+        (
+          await ask(
+            "These local copies will be deleted. Original download links may no longer work.\nPayments, Order history and protected inputs are unchanged.\nType confirm to clean, or q to return.",
+          )
+        ).trim() !== "confirm"
+      ) {
+        write("Cleanup cancelled.");
+        return 0;
+      }
+      const r = await operate({
+        action: "clean",
+        items: items.map(({ id, generation }) => ({ id, generation })),
+        confirmed: true,
+      });
+      write(
+        `${r.removed} local copies removed. History kept. Run clean again to review any remaining copies.`,
+      );
+    }
+    return 0;
+  } catch (error) {
+    write("Cache operation stopped: " + safe(error.message));
+    write(
+      offline
+        ? "If another Runtime owns this cache, use the command without --offline. Do not delete its lock file."
+        : "Check agentpay status. When Runtime is stopped, add --offline. No automatic offline fallback or payment was made.",
+    );
+    return 1;
+  }
+}

package/src/cache-management.mjs

@@ -0,0 +1,47 @@
+// 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 { fileError } from "./file-download.mjs";
+// Shared by the authenticated local route and the explicit offline CLI. No
+// import/download/financial operation is exposed through this management surface.
+export async function manageCache(cache, body) {
+  const fields = {
+    summary: [],
+    list: ["purpose", "state", "orderId", "requestId", "offset", "limit"],
+    details: ["id"],
+    verified: ["id"],
+    preview: [],
+    clean: ["items", "confirmed"],
+    settings: ["overrides"],
+  };
+  if (
+    !body ||
+    typeof body !== "object" ||
+    Array.isArray(body) ||
+    !Object.hasOwn(fields, body.action) ||
+    Object.keys(body).some(
+      (k) => k !== "action" && !fields[body.action].includes(k),
+    )
+  )
+    throw fileError(
+      "FILE_INPUT_INVALID",
+      "Choose a supported cache operation.",
+    );
+  const { action, ...args } = body;
+  switch (action) {
+    case "summary":
+      return cache.summary();
+    case "list":
+      return cache.listAll(args);
+    case "details":
+      return cache.details(args.id);
+    case "verified":
+      return cache.verified(args.id);
+    case "preview":
+      return cache.cleanPreview();
+    case "clean":
+      return cache.clean(args);
+    case "settings":
+      return cache.settings(args.overrides);
+  }
+}

package/src/caller-auth.mjs

@@ -0,0 +1,58 @@
+// 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 { randomBytes, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, open } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const TOKEN_PATTERN = /^[0-9a-f]{64}$/;
+
+export async function readCallerToken(path) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let token;
+  try {
+    const info = await handle.stat();
+    if (
+      !info.isFile() ||
+      info.uid !== process.getuid() ||
+      info.mode & 0o077 ||
+      info.size > 1024
+    )
+      throw Error(
+        "User Runtime caller credential must be a private regular file",
+      );
+    token = (await handle.readFile("utf8")).trim();
+  } finally {
+    await handle.close();
+  }
+  if (!TOKEN_PATTERN.test(token))
+    throw new Error("User Runtime caller credential file is invalid");
+  return token;
+}
+
+export function authorizeCaller(header, expectedToken) {
+  const prefix = "Bearer ";
+  const value =
+    typeof header === "string" && header.startsWith(prefix)
+      ? header.slice(prefix.length)
+      : "";
+  const actual = Buffer.from(value, "utf8");
+  const expected = Buffer.from(expectedToken, "utf8");
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+export async function initializeCallerCredential(path) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  let handle;
+  try {
+    handle = await open(path, "wx", 0o600);
+    await handle.writeFile(`${randomBytes(32).toString("hex")}\n`, "utf8");
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+  } finally {
+    await handle?.close();
+  }
+  await chmod(path, 0o600);
+  return readCallerToken(path);
+}

package/src/client-request-lock.mjs

@@ -0,0 +1,44 @@
+// 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 { open } from "node:fs/promises";
+import { constants } from "node:fs";
+const queues = new Map();
+// Same portable OS lock primitive as the file store, but scoped to a client call.
+// No PID files or stale-lock deletion: process exit releases the descriptor lock.
+export async function withClientRequestLock(path, operation) {
+  const previous = queues.get(path) || Promise.resolve();
+  let release;
+  const current = new Promise((r) => (release = r));
+  queues.set(path, current);
+  await previous;
+  let handle;
+  try {
+    const { tryLock } = await import("fs-native-extensions");
+    handle = await open(
+      path,
+      constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW,
+      0o600,
+    );
+    const s = await handle.stat();
+    if (
+      !s.isFile() ||
+      s.nlink !== 1 ||
+      s.uid !== process.getuid() ||
+      s.mode & 0o077
+    )
+      throw Error("Unsafe request lock");
+    if (!tryLock(handle.fd))
+      throw Object.assign(
+        Error(
+          "This original request is already running. Retry the same request shortly.",
+        ),
+        { code: "REQUEST_BUSY" },
+      );
+    return await operation();
+  } finally {
+    await handle?.close();
+    release();
+    if (queues.get(path) === current) queues.delete(path);
+  }
+}