@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

package/src/safe-owner-anvil.mjs

@@ -0,0 +1,115 @@
+// 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 { Contract, JsonRpcProvider, getAddress } from "ethers";
+import { safeEthSignSignature } from "./safe-policy-plan.mjs";
+
+// Rehearsal adapter only. Production sends the exported calls through the User's
+// external owner wallet / Safe approval workflow, then uses the same chain checks.
+export async function executeAnvilOwnerCall(plan, ownerInput, call) {
+  const url = new URL(plan.source.registryRpcUrl);
+  if (
+    plan.source.chainId !== 31337 ||
+    url.protocol !== "http:" ||
+    !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)
+  )
+    throw new Error("ANVIL_OWNER_SIGNING_TEST_ONLY");
+  const owner = getAddress(ownerInput);
+  const rpc = new JsonRpcProvider(url.toString(), undefined, {
+    batchMaxCount: 1,
+  });
+  try {
+    if (BigInt(await rpc.send("eth_chainId", [])) !== 31337n)
+      throw new Error("CHAIN_ID_MISMATCH");
+    const safe = new Contract(
+      plan.source.safe,
+      [
+        "function getOwners() view returns (address[])",
+        "function getThreshold() view returns (uint256)",
+        "function nonce() view returns (uint256)",
+        "function getTransactionHash(address,uint256,bytes,uint8,uint256,uint256,uint256,address,address,uint256) view returns (bytes32)",
+        "function execTransaction(address,uint256,bytes,uint8,uint256,uint256,uint256,address,address,bytes) returns (bool)",
+        "event ExecutionSuccess(bytes32 indexed txHash,uint256 payment)",
+        "event ExecutionFailure(bytes32 indexed txHash,uint256 payment)",
+      ],
+      await rpc.getSigner(owner),
+    );
+    if (
+      (await safe.getThreshold()) !== 1n ||
+      !(await safe.getOwners()).includes(owner)
+    )
+      throw new Error("ANVIL_OWNER_THRESHOLD_UNSUPPORTED");
+    const zero = "0x0000000000000000000000000000000000000000";
+    const nonce = await safe.nonce();
+    const hash = await safe.getTransactionHash(
+      call.to,
+      0,
+      call.data,
+      0,
+      0,
+      0,
+      0,
+      zero,
+      zero,
+      nonce,
+    );
+    const signature = safeEthSignSignature(
+      hash,
+      await rpc.send("eth_sign", [owner, hash]),
+      owner,
+    );
+    const tx = await safe.execTransaction(
+      call.to,
+      0,
+      call.data,
+      0,
+      0,
+      0,
+      0,
+      zero,
+      zero,
+      signature,
+    );
+    process.stdout.write(
+      `${JSON.stringify({ safeCall: call.purpose, transactionHash: tx.hash, state: "submitted" })}\n`,
+    );
+    const receipt = await tx.wait(1, 60_000);
+    const events =
+      receipt?.logs.map((log) => {
+        try {
+          return safe.interface.parseLog(log);
+        } catch {
+          return null;
+        }
+      }) ?? [];
+    if (
+      receipt?.status !== 1 ||
+      !events.some((e) => e?.name === "ExecutionSuccess") ||
+      events.some((e) => e?.name === "ExecutionFailure")
+    )
+      throw new Error("SAFE_OWNER_CALL_FAILED");
+    return {
+      safeCall: call.purpose,
+      transactionHash: tx.hash,
+      safeNonce: nonce.toString(),
+      confirmed: true,
+    };
+  } catch (error) {
+    // RPC/ethers errors may contain raw signed Safe calldata. Do not place that
+    // payload in terminal logs; the submitted hash above and chain status suffice
+    // for recovery after an ambiguous send or receipt timeout.
+    const publicCodes = new Set([
+      "CHAIN_ID_MISMATCH",
+      "ANVIL_OWNER_THRESHOLD_UNSUPPORTED",
+      "ANVIL_OWNER_SIGNATURE_MISMATCH",
+      "SAFE_OWNER_CALL_FAILED",
+    ]);
+    throw new Error(
+      publicCodes.has(error?.message)
+        ? error.message
+        : "SAFE_OWNER_CALL_UNCONFIRMED_RECHECK_CHAIN",
+    );
+  } finally {
+    rpc.destroy();
+  }
+}

package/src/safe-policy-plan.mjs

@@ -0,0 +1,195 @@
+// 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 {
+  Contract,
+  getBytes,
+  hashMessage,
+  Interface,
+  getAddress,
+  isHexString,
+  recoverAddress,
+  Signature,
+} from "ethers";
+
+const ZERO = "0x0000000000000000000000000000000000000000";
+const moduleAbi = [
+  "function createPolicy(bytes32 policyId,address delegate,address token,address factory,address registry,uint256 maxPerPayment,uint256 totalBudget,uint64 validAfter,uint64 validUntil)",
+  "function policies(address safe,bytes32 policyId) view returns (address delegate,address token,address factory,address registry,uint256 maxPerPayment,uint256 totalBudget,uint256 spent,uint64 validAfter,uint64 validUntil,bool revoked)",
+];
+const safeAbi = [
+  "function getOwners() view returns (address[])",
+  "function getThreshold() view returns (uint256)",
+  "function isModuleEnabled(address) view returns (bool)",
+];
+const enableInterface = new Interface([
+  "function enableModule(address module)",
+]);
+const policyInterface = new Interface(moduleAbi);
+
+export function safeEthSignSignature(hash, signedMessage, ownerAddress) {
+  if (
+    !isHexString(hash, 32) ||
+    recoverAddress(hashMessage(getBytes(hash)), signedMessage) !==
+      getAddress(ownerAddress)
+  ) {
+    throw new Error("ANVIL_OWNER_SIGNATURE_MISMATCH");
+  }
+  // Safe v1.4.x interprets v=31/32 as an EIP-191 eth_sign signature.
+  const parsed = Signature.from(signedMessage);
+  return `${signedMessage.slice(0, -2)}${(parsed.v + 4).toString(16).padStart(2, "0")}`;
+}
+
+function positive(value, name) {
+  if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value))
+    throw new Error(`${name} must be a positive atomic integer string`);
+  return BigInt(value);
+}
+function address(value, name) {
+  try {
+    return getAddress(value);
+  } catch {
+    throw new Error(`${name} must be an address`);
+  }
+}
+export function buildSafePolicyPlan(config, delegate) {
+  if (!config || typeof config !== "object" || Array.isArray(config))
+    throw new Error("POLICY_CONFIG_INVALID");
+  const chainId = Number(config.chainId);
+  if (!Number.isSafeInteger(chainId) || chainId < 1)
+    throw new Error("CHAIN_ID_INVALID");
+  const rpcUrl = new URL(config.rpcUrl);
+  if (
+    !(
+      rpcUrl.protocol === "https:" ||
+      (rpcUrl.protocol === "http:" &&
+        ["127.0.0.1", "localhost", "[::1]"].includes(rpcUrl.hostname))
+    )
+  )
+    throw new Error("RPC_URL_UNSAFE");
+  if (!isHexString(config.policyId, 32) || /^0x0{64}$/i.test(config.policyId))
+    throw new Error("POLICY_ID_INVALID");
+  const safe = address(config.safe, "safe");
+  const module = address(config.module, "module");
+  const token = address(config.token, "token");
+  const factory = address(config.factory, "factory");
+  const registry = address(config.registry, "registry");
+  const sessionDelegate = address(delegate, "delegate");
+  const maxPerPayment = positive(config.maxPerPayment, "maxPerPayment");
+  const totalBudget = positive(config.totalBudget, "totalBudget");
+  if (totalBudget < maxPerPayment)
+    throw new Error("BUDGET_BELOW_PER_PAYMENT_LIMIT");
+  const validAfter = Number(config.validAfter);
+  const validUntil = Number(config.validUntil);
+  if (
+    ![validAfter, validUntil].every(Number.isSafeInteger) ||
+    validAfter < 0 ||
+    validUntil <= validAfter ||
+    validUntil <= Math.floor(Date.now() / 1000)
+  )
+    throw new Error("POLICY_VALIDITY_INVALID");
+  const policyId = config.policyId.toLowerCase();
+  const enableData = enableInterface.encodeFunctionData("enableModule", [
+    module,
+  ]);
+  const createData = policyInterface.encodeFunctionData("createPolicy", [
+    policyId,
+    sessionDelegate,
+    token,
+    factory,
+    registry,
+    maxPerPayment,
+    totalBudget,
+    validAfter,
+    validUntil,
+  ]);
+  return Object.freeze({
+    chainId,
+    rpcUrl: rpcUrl.toString(),
+    safe,
+    module,
+    token,
+    factory,
+    registry,
+    delegate: sessionDelegate,
+    policyId,
+    maxPerPayment,
+    totalBudget,
+    validAfter,
+    validUntil,
+    calls: [
+      {
+        purpose: "enable AgentPay Module",
+        to: safe,
+        value: "0",
+        operation: 0,
+        data: enableData,
+      },
+      {
+        purpose: "create bounded Spending Policy",
+        to: module,
+        value: "0",
+        operation: 0,
+        data: createData,
+      },
+    ],
+    walletPolicy: {
+      version: "agentpay.safe-module.v1",
+      chainId,
+      module,
+      safe,
+      delegate: sessionDelegate,
+      policyId,
+      factory,
+      registry,
+      registryRpcUrl: rpcUrl.toString(),
+      token,
+      maxAmount: maxPerPayment.toString(),
+      validUntil,
+    },
+  });
+}
+
+export async function inspectSafePolicy(provider, plan) {
+  const chain = await provider.getNetwork();
+  if (Number(chain.chainId) !== plan.chainId)
+    throw new Error("CHAIN_ID_MISMATCH");
+  for (const [name, at] of [
+    ["safe", plan.safe],
+    ["module", plan.module],
+    ["token", plan.token],
+    ["factory", plan.factory],
+    ["registry", plan.registry],
+  ]) {
+    if ((await provider.getCode(at)) === "0x")
+      throw new Error(`${name.toUpperCase()}_CODE_MISSING`);
+  }
+  const safe = new Contract(plan.safe, safeAbi, provider);
+  const module = new Contract(plan.module, moduleAbi, provider);
+  const [owners, threshold, moduleEnabled, policy] = await Promise.all([
+    safe.getOwners(),
+    safe.getThreshold(),
+    safe.isModuleEnabled(plan.module),
+    module.policies(plan.safe, plan.policyId),
+  ]);
+  const existing = policy.delegate !== ZERO;
+  const policyMatches =
+    existing &&
+    policy.delegate === plan.delegate &&
+    policy.token === plan.token &&
+    policy.factory === plan.factory &&
+    policy.registry === plan.registry &&
+    policy.maxPerPayment === plan.maxPerPayment &&
+    policy.totalBudget === plan.totalBudget &&
+    Number(policy.validAfter) === plan.validAfter &&
+    Number(policy.validUntil) === plan.validUntil &&
+    !policy.revoked;
+  return {
+    owners,
+    threshold: Number(threshold),
+    moduleEnabled,
+    policyExists: existing,
+    policyMatches,
+    policySpent: existing ? policy.spent.toString() : null,
+  };
+}

package/src/service-reference.mjs

@@ -0,0 +1,233 @@
+// 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 {
+  normalizeServiceReference,
+  canonicalizeServiceJson,
+  normalizeServiceResult,
+  AGENTPAY_SERVICE_INVOCATION_VERSION,
+} from "@c4roa0/agentpay-protocol";
+export const SERVICE_REFERENCE_VERSION = "agentpay.service-reference.v1";
+export function parseServiceReference(value) {
+  try {
+    return normalizeServiceReference(value);
+  } catch {
+    throw coded(
+      "SERVICE_REFERENCE_INVALID",
+      "Service reference or registered profile hash is invalid.",
+    );
+  }
+}
+export function serviceRequest(value) {
+  try {
+    return JSON.parse(canonicalizeServiceJson(value));
+  } catch {
+    throw coded(
+      "INVALID_INPUT",
+      "Request must be bounded JSON with no more than 32 levels.",
+    );
+  }
+}
+export function usageCap(value = "1") {
+  if (typeof value !== "string" || !/^[1-9][0-9]{0,76}$/.test(value))
+    throw coded(
+      "INVALID_USAGE_CAP",
+      "Maximum usage must be a positive integer string.",
+    );
+  return value;
+}
+export function serviceContext(body, localUsageCap = "1000000") {
+  if (
+    !body ||
+    Object.keys(body)
+      .filter((k) => k !== "acceptedTerms")
+      .sort()
+      .join(",") !== "request,requestedMaxUsageUnits,service,version" ||
+    body.version !== "agentpay.runtime-call.v1"
+  )
+    throw coded(
+      "INVALID_INPUT",
+      "Use the versioned Runtime call with service, request and maximum usage.",
+    );
+  const reference = parseServiceReference(body.service),
+    requestedMaxUsageUnits = usageCap(body.requestedMaxUsageUnits);
+  if (BigInt(requestedMaxUsageUnits) > BigInt(usageCap(localUsageCap)))
+    throw coded(
+      "INVALID_USAGE_CAP",
+      "Requested usage exceeds the local Runtime cap.",
+    );
+  const request = serviceRequest(body.request);
+  return {
+    reference,
+    skillId: reference.skillId,
+    profileHash: reference.profileHash,
+    endpointUrl: reference.profile.paymentEndpoint,
+    adapter: reference.adapter,
+    requestedMaxUsageUnits,
+    request,
+    ...(body.acceptedTerms === undefined
+      ? {}
+      : { acceptedTerms: normalizeAcceptedTerms(body.acceptedTerms) }),
+    binding: JSON.stringify({
+      version: "agentpay.runtime-service.v1",
+      reference,
+      requestedMaxUsageUnits,
+    }),
+  };
+}
+export function assertPreparedService(result, context, requestHash) {
+  const order = result?.order,
+    profile = context.reference.profile;
+  if (
+    !order ||
+    order.skillId !== context.skillId ||
+    order.profileHash !== context.profileHash ||
+    order.requestHash !== requestHash ||
+    order.providerId !== profile.providerId ||
+    String(order.assetAddress).toLowerCase() !== profile.asset ||
+    `eip155:${order.chainId}` !== profile.network ||
+    String(result.commitmentContext?.seller).toLowerCase() !== profile.seller ||
+    BigInt(order.maxUsageUnits) > BigInt(context.requestedMaxUsageUnits)
+  )
+    throw coded(
+      "SETTLEMENT_SERVICE_MISMATCH",
+      "Prepared Order does not match the registered service reference.",
+    );
+}
+export function providerRequest(context, orderId, requestHash, request) {
+  return {
+    version: AGENTPAY_SERVICE_INVOCATION_VERSION,
+    orderId,
+    requestHash,
+    request,
+  };
+}
+export function providerOutput(payload, context, input, orderId, requestHash) {
+  let result;
+  try {
+    result = normalizeServiceResult(payload?.result);
+    if (
+      result.orderId !== orderId ||
+      result.requestHash !== requestHash ||
+      !/^(0|[1-9][0-9]{0,76})$/.test(result.usageUnits || "") ||
+      BigInt(result.usageUnits) > BigInt(context.requestedMaxUsageUnits)
+    )
+      throw Error();
+  } catch {
+    throw coded(
+      "PROVIDER_RESPONSE_INVALID",
+      "Provider output, hash, usage or request identity does not match this invocation.",
+    );
+  }
+  return result;
+}
+function coded(code, message) {
+  return Object.assign(Error(message), { code });
+}
+
+export function normalizeRuntimeResult(
+  value,
+  context,
+  requestHash,
+  orderId = null,
+) {
+  try {
+    if (
+      value?.version !== "agentpay.runtime-result.v1" ||
+      value.service?.skillId !== context.skillId ||
+      value.service?.profileHash !== context.profileHash ||
+      value.requestHash !== requestHash ||
+      !/^0x[0-9a-f]{64}$/.test(value.orderId || "") ||
+      (orderId && value.orderId !== orderId) ||
+      value.deliveryEvidenceVerified !== true
+    )
+      throw Error();
+    const delivery = normalizeServiceResult({
+      version: "agentpay.service-result.v1",
+      orderId: value.orderId,
+      requestHash,
+      output: value.output,
+      outputHash: value.outputHash,
+      usageUnits: value.usageUnits,
+    });
+    if (BigInt(delivery.usageUnits) > BigInt(context.requestedMaxUsageUnits))
+      throw Error();
+    return {
+      version: "agentpay.runtime-result.v1",
+      orderId: value.orderId,
+      requestHash,
+      service: { skillId: context.skillId, profileHash: context.profileHash },
+      output: delivery.output,
+      outputHash: delivery.outputHash,
+      usageUnits: delivery.usageUnits,
+      deliveryEvidenceVerified: true,
+      confirmationRequired: false,
+      finalization: value.finalization,
+      deadlines: value.deadlines,
+    };
+  } catch {
+    throw coded(
+      "RUNTIME_RESPONSE_INVALID",
+      "Runtime result does not match the bound service, input or usage cap.",
+    );
+  }
+}
+
+export function normalizeAcceptedTerms(value) {
+  if (
+    !value ||
+    Object.keys(value).sort().join(",") !==
+      "baseAmountAtomic,serviceWindowSeconds,unitPriceAtomic" ||
+    typeof value.baseAmountAtomic !== "string" ||
+    typeof value.unitPriceAtomic !== "string" ||
+    !/^(0|[1-9][0-9]*)$/.test(value.baseAmountAtomic) ||
+    !/^(0|[1-9][0-9]*)$/.test(value.unitPriceAtomic) ||
+    !Number.isSafeInteger(value.serviceWindowSeconds) ||
+    value.serviceWindowSeconds < 1 ||
+    value.serviceWindowSeconds > 31536000
+  )
+    throw coded(
+      "QUOTE_TERMS_INVALID",
+      "Review the price and maximum delivery duration.",
+    );
+  return {
+    baseAmountAtomic: value.baseAmountAtomic,
+    unitPriceAtomic: value.unitPriceAtomic,
+    serviceWindowSeconds: value.serviceWindowSeconds,
+  };
+}
+
+// Check again before signing, including when an older Wallet transport omitted
+// the accepted conditions. A mismatch keeps the original Order, never reaccepts it.
+export function assertPreparedCommercialTerms(result, accepted) {
+  if (!accepted) return;
+  const fail = () => {
+    throw coded(
+      "ORDER_TERMS_MISMATCH",
+      "Prepared Order differs from the accepted price or delivery time. Preserve this Order; no payment was authorized.",
+    );
+  };
+  const order = result?.order,
+    due = result?.deadlines?.deliveryDueAtMs;
+  if (
+    !order ||
+    order.basePriceAtomic !== accepted.baseAmountAtomic ||
+    order.unitPriceAtomic !== accepted.unitPriceAtomic ||
+    !Number.isSafeInteger(order.createdAtMs) ||
+    due - order.createdAtMs !== accepted.serviceWindowSeconds * 1000
+  )
+    fail();
+  try {
+    const amount =
+      BigInt(accepted.baseAmountAtomic) +
+      BigInt(accepted.unitPriceAtomic) * BigInt(order.maxUsageUnits);
+    if (
+      amount !== BigInt(order.prepaidAmountAtomic) ||
+      (result.paymentRequired &&
+        BigInt(result.paymentRequired.amount) !== amount)
+    )
+      fail();
+  } catch {
+    fail();
+  }
+}

package/src/service-url.mjs

@@ -0,0 +1,52 @@
+// 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/.
+// A deployment base may include an ingress prefix. Local control stays separate.
+export function serviceBase(value, label = "Service URL") {
+  if (
+    typeof value !== "string" ||
+    value !== value.trim() ||
+    value.includes("\\")
+  )
+    throw Error(`Invalid ${label}`);
+  const rawPath = /^[a-z]+:\/\/[^/?#]+([^?#]*)/.exec(value)?.[1];
+  if (
+    rawPath === undefined ||
+    !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]*$/.test(rawPath || "/")
+  )
+    throw Error(`Invalid ${label} path`);
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !(
+      url.protocol === "https:" ||
+      (url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+    )
+  )
+    throw Error(`${label} must use HTTPS or loopback HTTP`);
+  return url.origin + url.pathname.replace(/\/+$/, "");
+}
+export function serviceUrl(base, path) {
+  if (
+    typeof path !== "string" ||
+    !path.startsWith("/") ||
+    path.startsWith("//") ||
+    path.includes("#") ||
+    path.includes("\\")
+  )
+    throw Error("Invalid service endpoint");
+  const normalized = serviceBase(String(base));
+  const url = new URL(path.slice(1), normalized + "/");
+  if (
+    url.origin !== new URL(normalized).origin ||
+    !url.pathname.startsWith(
+      new URL(normalized).pathname.replace(/\/$/, "") + "/",
+    )
+  )
+    throw Error("Endpoint escapes service base");
+  return url;
+}

package/src/settlement-response.mjs

@@ -0,0 +1,69 @@
+// 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 {
+  normalizeParticipantOrder,
+  normalizeFinalizationDisclosure,
+  normalizeOrderDeadlines,
+  normalizeServiceAuthorization,
+  AGENTPAY_SERVICE_AUTHORIZATION_V2,
+  normalizeDeliveryResult,
+  validateOrderWaiting,
+  validateOrderClosure,
+  AGENTPAY_DELIVERY_RESULT_V2,
+} from "@c4roa0/agentpay-protocol";
+
+// Keep integer timestamps inside Runtime; v1 is an explicit ingress adapter.
+export function readSettlementResult(value) {
+  const fail = () => {
+    throw Object.assign(
+      new Error("Settlement response has invalid fields or timestamps"),
+      { code: "SETTLEMENT_RESPONSE_INVALID" },
+    );
+  };
+  if (
+    value?.ok !== true ||
+    !value.result ||
+    typeof value.result !== "object" ||
+    Array.isArray(value.result)
+  )
+    fail();
+  try {
+    let result = { ...value.result };
+    if (
+      result.version === AGENTPAY_SERVICE_AUTHORIZATION_V2 ||
+      (Object.hasOwn(result, "authorizationId") &&
+        (Object.hasOwn(result, "expiresAt") ||
+          Object.hasOwn(result, "expiresAtMs") ||
+          Object.hasOwn(result, "state") ||
+          Object.hasOwn(result, "authorization")))
+    )
+      result = normalizeServiceAuthorization(result);
+    if (
+      result.version === AGENTPAY_DELIVERY_RESULT_V2 ||
+      Object.hasOwn(result, "confirmedAt") ||
+      Object.hasOwn(result, "confirmedAtMs") ||
+      (Object.hasOwn(result, "receiptId") && Object.hasOwn(result, "billing"))
+    )
+      result = normalizeDeliveryResult(result);
+    if (Object.hasOwn(result, "order")) {
+      result.order = normalizeParticipantOrder(result.order);
+      if (result.order.role !== "buyer") fail();
+    }
+    if (result.waiting != null)
+      result.waiting = validateOrderWaiting(result.waiting);
+    if (result.closure != null) {
+      result.closure = validateOrderClosure(result.closure);
+      if (result.paymentRequired != null) fail();
+    }
+    if (result.deadlines != null)
+      result.deadlines = normalizeOrderDeadlines(result.deadlines);
+    if (result.finalization != null)
+      result.finalization = normalizeFinalizationDisclosure(
+        result.finalization,
+      );
+    return result;
+  } catch {
+    fail();
+  }
+}