@elizaos/plugin-x402 2.0.0-alpha.6 → 2.0.0-beta.1

package/src/x402-replay-durable.ts

@@ -0,0 +1,320 @@
+import { createHash, randomUUID } from "node:crypto";
+import { type AgentRuntime, logger } from "@elizaos/core";
+import { sql } from "drizzle-orm";
+
+function sha256Utf8(s: string): string {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+
+/** Stored in the runtime cache while verification owns a durable reservation. */
+export type X402ReplayInflightPayload = {
+  state: "inflight";
+  owner: string;
+  reservedAt: number;
+  expiresAt: number;
+};
+
+/** Stored in the runtime cache after a successful payment verification. */
+export type X402ReplayConsumedPayload = {
+  state: "consumed";
+  consumedAt: number;
+};
+
+export type X402ReplayPayload =
+  | X402ReplayInflightPayload
+  | X402ReplayConsumedPayload;
+
+export type DurableReplayReservation =
+  | { ok: true; owner: string; atomic: boolean }
+  | { ok: false };
+
+type QueryableDb = {
+  execute: (query: unknown) => Promise<unknown>;
+};
+
+/**
+ * Stable cache key for a replay credential, scoped by agent so two agents never
+ * share the same cache row.
+ */
+export function durableReplayCacheKey(
+  agentId: string | undefined,
+  replayKey: string,
+): string {
+  const agent = agentId && agentId.trim().length > 0 ? agentId.trim() : "_";
+  return `x402:replay:v1:${sha256Utf8(`${agent}::${replayKey}`)}`;
+}
+
+function replayReservationTtlMs(): number {
+  const raw = process.env.X402_REPLAY_RESERVATION_TTL_MS;
+  const n = Number.parseInt(raw ?? "120000", 10);
+  return Number.isFinite(n) && n > 0 ? n : 120_000;
+}
+
+function resultHadRows(result: unknown): boolean {
+  if (Array.isArray(result)) return result.length > 0;
+  if (typeof result === "object" && result !== null) {
+    const rows = (result as { rows?: unknown }).rows;
+    if (Array.isArray(rows)) return rows.length > 0;
+    const rowCount = (result as { rowCount?: unknown }).rowCount;
+    if (typeof rowCount === "number") return rowCount > 0;
+  }
+  return false;
+}
+
+async function getSqlDb(runtime: AgentRuntime): Promise<QueryableDb | null> {
+  const db = await runtime.adapter?.getConnection?.();
+  if (
+    db &&
+    typeof db === "object" &&
+    typeof (db as { execute?: unknown }).execute === "function"
+  ) {
+    return db as QueryableDb;
+  }
+  return null;
+}
+
+async function insertInflightReservation(
+  db: QueryableDb,
+  agentId: string,
+  cacheKey: string,
+  payload: X402ReplayInflightPayload,
+): Promise<boolean> {
+  const result = await db.execute(sql`
+    INSERT INTO cache (key, agent_id, value)
+    VALUES (${cacheKey}, ${agentId}, ${JSON.stringify(payload)}::jsonb)
+    ON CONFLICT (key, agent_id) DO NOTHING
+    RETURNING key
+  `);
+  return resultHadRows(result);
+}
+
+async function stealExpiredInflightReservation(
+  db: QueryableDb,
+  agentId: string,
+  cacheKey: string,
+  payload: X402ReplayInflightPayload,
+  now: number,
+): Promise<boolean> {
+  const result = await db.execute(sql`
+    UPDATE cache
+    SET value = ${JSON.stringify(payload)}::jsonb
+    WHERE key = ${cacheKey}
+      AND agent_id = ${agentId}
+      AND value->>'state' = 'inflight'
+      AND COALESCE((value->>'expiresAt')::bigint, 0) <= ${now}
+    RETURNING key
+  `);
+  return resultHadRows(result);
+}
+
+async function releaseSqlReservations(
+  db: QueryableDb,
+  agentId: string,
+  cacheKeys: string[],
+  owner: string,
+): Promise<void> {
+  for (const cacheKey of cacheKeys) {
+    await db.execute(sql`
+      DELETE FROM cache
+      WHERE key = ${cacheKey}
+        AND agent_id = ${agentId}
+        AND value->>'state' = 'inflight'
+        AND value->>'owner' = ${owner}
+    `);
+  }
+}
+
+async function commitSqlReservations(
+  db: QueryableDb,
+  agentId: string,
+  cacheKeys: string[],
+  owner: string,
+): Promise<void> {
+  const payload: X402ReplayConsumedPayload = {
+    state: "consumed",
+    consumedAt: Date.now(),
+  };
+  for (const cacheKey of cacheKeys) {
+    const result = await db.execute(sql`
+      UPDATE cache
+      SET value = ${JSON.stringify(payload)}::jsonb
+      WHERE key = ${cacheKey}
+        AND agent_id = ${agentId}
+        AND value->>'state' = 'inflight'
+        AND value->>'owner' = ${owner}
+      RETURNING key
+    `);
+    if (!resultHadRows(result)) {
+      logger.error(
+        `[x402] durable replay: failed to commit reserved replay key ${cacheKey}`,
+      );
+    }
+  }
+}
+
+function isConsumed(value: X402ReplayPayload | undefined): boolean {
+  if (!value) return false;
+  return value.state === "consumed" || "consumedAt" in value;
+}
+
+export async function durableReplayTryReserve(
+  runtime: AgentRuntime,
+  agentId: string | undefined,
+  keys: string[],
+): Promise<DurableReplayReservation> {
+  if (keys.length === 0) return { ok: true, owner: randomUUID(), atomic: true };
+
+  const db = await getSqlDb(runtime);
+  const resolvedAgentId =
+    agentId && agentId.trim().length > 0
+      ? agentId.trim()
+      : runtime.agentId
+        ? String(runtime.agentId)
+        : undefined;
+
+  if (db && resolvedAgentId) {
+    const owner = randomUUID();
+    const now = Date.now();
+    const payload: X402ReplayInflightPayload = {
+      state: "inflight",
+      owner,
+      reservedAt: now,
+      expiresAt: now + replayReservationTtlMs(),
+    };
+    const acquired: string[] = [];
+    try {
+      for (const replayKey of keys) {
+        const cacheKey = durableReplayCacheKey(resolvedAgentId, replayKey);
+        if (
+          (await insertInflightReservation(
+            db,
+            resolvedAgentId,
+            cacheKey,
+            payload,
+          )) ||
+          (await stealExpiredInflightReservation(
+            db,
+            resolvedAgentId,
+            cacheKey,
+            payload,
+            now,
+          ))
+        ) {
+          acquired.push(cacheKey);
+          continue;
+        }
+
+        await releaseSqlReservations(db, resolvedAgentId, acquired, owner);
+        return { ok: false };
+      }
+      return { ok: true, owner, atomic: true };
+    } catch (err) {
+      await releaseSqlReservations(db, resolvedAgentId, acquired, owner).catch(
+        () => {},
+      );
+      logger.error(
+        `[x402] durable replay: atomic reservation failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      return { ok: false };
+    }
+  }
+
+  const owner = randomUUID();
+  for (const replayKey of keys) {
+    const cacheKey = durableReplayCacheKey(agentId, replayKey);
+    const v = await runtime.getCache<X402ReplayPayload>(cacheKey);
+    if (isConsumed(v)) return { ok: false };
+    if (v?.state === "inflight" && v.expiresAt > Date.now()) {
+      return { ok: false };
+    }
+  }
+  const now = Date.now();
+  const payload: X402ReplayInflightPayload = {
+    state: "inflight",
+    owner,
+    reservedAt: now,
+    expiresAt: now + replayReservationTtlMs(),
+  };
+  for (const replayKey of keys) {
+    await runtime.setCache(durableReplayCacheKey(agentId, replayKey), payload);
+  }
+  return { ok: true, owner, atomic: false };
+}
+
+export async function durableReplayAbortReservation(
+  runtime: AgentRuntime,
+  agentId: string | undefined,
+  keys: string[],
+  owner?: string,
+): Promise<void> {
+  if (!owner || keys.length === 0) return;
+  const db = await getSqlDb(runtime);
+  const resolvedAgentId =
+    agentId && agentId.trim().length > 0
+      ? agentId.trim()
+      : runtime.agentId
+        ? String(runtime.agentId)
+        : undefined;
+  if (db && resolvedAgentId) {
+    await releaseSqlReservations(
+      db,
+      resolvedAgentId,
+      keys.map((k) => durableReplayCacheKey(resolvedAgentId, k)),
+      owner,
+    );
+    return;
+  }
+  for (const replayKey of keys) {
+    const cacheKey = durableReplayCacheKey(agentId, replayKey);
+    const v = await runtime.getCache<X402ReplayPayload>(cacheKey);
+    if (v?.state === "inflight" && v.owner === owner) {
+      await runtime.deleteCache(cacheKey);
+    }
+  }
+}
+
+export async function durableReplayCommitReservation(
+  runtime: AgentRuntime,
+  agentId: string | undefined,
+  keys: string[],
+  owner?: string,
+): Promise<void> {
+  if (keys.length === 0) return;
+  const db = await getSqlDb(runtime);
+  const resolvedAgentId =
+    agentId && agentId.trim().length > 0
+      ? agentId.trim()
+      : runtime.agentId
+        ? String(runtime.agentId)
+        : undefined;
+  if (db && resolvedAgentId && owner) {
+    await commitSqlReservations(
+      db,
+      resolvedAgentId,
+      keys.map((k) => durableReplayCacheKey(resolvedAgentId, k)),
+      owner,
+    );
+    return;
+  }
+
+  const payload: X402ReplayConsumedPayload = {
+    state: "consumed",
+    consumedAt: Date.now(),
+  };
+  for (const replayKey of keys) {
+    const ok = await runtime.setCache(
+      durableReplayCacheKey(agentId, replayKey),
+      payload,
+    );
+    if (!ok) {
+      logger.error(
+        `[x402] durable replay: setCache failed for replay key ${replayKey.slice(
+          0,
+          80,
+        )} (payment may be retryable if this persists)`,
+      );
+    }
+  }
+}

package/src/x402-replay-guard.ts

@@ -0,0 +1,165 @@
+/**
+ * Replay + in-flight guard for x402 verification.
+ *
+ * - **In-flight (`inflight`)**: in-memory only; prevents concurrent duplicate
+ *   verification in the same process (TOCTOU between check and verify).
+ * - **Consumed**: when `X402_REPLAY_DURABLE` is not disabled and `runtime` is
+ *   passed, credentials are recorded via `runtime.setCache` / `getCache` so they
+ *   survive restarts and work across multiple server processes sharing the DB.
+ *   Entries do not expire (same tx hash / payment id must not unlock paid routes twice).
+ * - **Fallback**: set `X402_REPLAY_DURABLE=0` (or `false` / `off`) to use only an
+ *   in-memory TTL map (`X402_REPLAY_WINDOW_MS` / `X402_REPLAY_TTL_MS`, default 10m).
+ *   If `runtime` is omitted (e.g. isolated unit tests), that same in-memory path is used.
+ */
+
+import { type AgentRuntime, logger } from "@elizaos/core";
+
+import {
+  durableReplayAbortReservation,
+  durableReplayCommitReservation,
+  durableReplayTryReserve,
+} from "./x402-replay-durable.js";
+
+const inflight = new Set<string>();
+const consumedMemory = new Map<string, number>();
+const durableReservationOwners = new Map<string, string>();
+
+function replayWindowMs(): number {
+  const raw =
+    process.env.X402_REPLAY_WINDOW_MS ?? process.env.X402_REPLAY_TTL_MS;
+  const n = Number.parseInt(raw ?? "600000", 10);
+  return Number.isFinite(n) && n > 0 ? n : 600_000;
+}
+
+function pruneConsumedMemory(now: number): void {
+  for (const [k, exp] of consumedMemory) {
+    if (exp <= now) consumedMemory.delete(k);
+  }
+}
+
+/** When true (default), use runtime cache for consumed credentials. */
+export function isDurableReplayEnabled(): boolean {
+  const v = process.env.X402_REPLAY_DURABLE?.trim().toLowerCase();
+  if (v === "0" || v === "false" || v === "off") return false;
+  return true;
+}
+
+/**
+ * Reserve canonical replay keys for the duration of verification.
+ * Returns false if any key is already consumed, or already in-flight in this process.
+ */
+export async function replayGuardTryBegin(
+  keys: string[],
+  runtime?: AgentRuntime,
+  agentId?: string,
+): Promise<boolean> {
+  if (keys.length === 0) return true;
+  const now = Date.now();
+  const useDurable = isDurableReplayEnabled() && runtime != null;
+
+  try {
+    let durableOwner: string | null = null;
+    if (useDurable) {
+      const reservation = await durableReplayTryReserve(runtime, agentId, keys);
+      if (!reservation.ok) return false;
+      durableOwner = reservation.owner;
+    } else {
+      pruneConsumedMemory(now);
+      for (const k of keys) {
+        const exp = consumedMemory.get(k);
+        if (exp != null && exp > now) return false;
+      }
+    }
+
+    for (const k of keys) {
+      if (inflight.has(k)) {
+        // Already in-flight in this process — release the durable reservation
+        // we just took so it does not linger until TTL expiry and block
+        // subsequent legitimate attempts for the same credential.
+        if (durableOwner && runtime) {
+          await durableReplayAbortReservation(
+            runtime,
+            agentId,
+            keys,
+            durableOwner,
+          );
+        }
+        return false;
+      }
+    }
+    if (durableOwner) {
+      for (const k of keys) durableReservationOwners.set(k, durableOwner);
+    }
+    for (const k of keys) inflight.add(k);
+    return true;
+  } catch (err) {
+    logger.error(
+      `[x402] replayGuardTryBegin failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return false;
+  }
+}
+
+/** Release reservation after a failed or abandoned verification attempt. */
+export function replayGuardAbort(keys: string[]): void {
+  for (const k of keys) {
+    inflight.delete(k);
+    durableReservationOwners.delete(k);
+  }
+}
+
+/** Release a durable reservation after a failed or abandoned verification attempt. */
+export async function replayGuardAbortAsync(
+  keys: string[],
+  runtime?: AgentRuntime,
+  agentId?: string,
+): Promise<void> {
+  const owner = keys
+    .map((k) => durableReservationOwners.get(k))
+    .find((x): x is string => typeof x === "string");
+  replayGuardAbort(keys);
+  if (owner && runtime) {
+    await durableReplayAbortReservation(runtime, agentId, keys, owner);
+  }
+}
+
+/** Mark keys consumed after a successful verification (clears in-flight). */
+export async function replayGuardCommit(
+  keys: string[],
+  runtime?: AgentRuntime,
+  agentId?: string,
+): Promise<void> {
+  const useDurable = isDurableReplayEnabled() && runtime != null;
+  const exp = Date.now() + replayWindowMs();
+  // Require all keys to map to the same owner. If owners diverge, the
+  // in-process map raced with another request — drop the owner so the durable
+  // layer can no-op the owner-bound path instead of recording wrong lineage.
+  let owner: string | undefined;
+  let ownerConsistent = true;
+  for (const k of keys) {
+    const o = durableReservationOwners.get(k);
+    if (typeof o !== "string") continue;
+    if (owner === undefined) {
+      owner = o;
+    } else if (owner !== o) {
+      ownerConsistent = false;
+      break;
+    }
+  }
+  for (const k of keys) {
+    inflight.delete(k);
+    durableReservationOwners.delete(k);
+  }
+  if (useDurable && keys.length > 0 && runtime) {
+    await durableReplayCommitReservation(
+      runtime,
+      agentId,
+      keys,
+      ownerConsistent ? owner : undefined,
+    );
+  } else if (!useDurable) {
+    for (const k of keys) consumedMemory.set(k, exp);
+  }
+}

package/src/x402-replay-keys.ts

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+
+function sha256Utf8(s: string): string {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+
+/**
+ * Replay key for facilitator payment IDs (sanitized id → stable hash).
+ */
+export function paymentIdReplayKey(paymentId: string): string | null {
+  const cleaned = paymentId.trim();
+  if (!/^[a-zA-Z0-9_-]+$/.test(cleaned) || cleaned.length > 128) return null;
+  return `fac:${sha256Utf8(cleaned)}`;
+}
+
+function looksMostlyPrintableAscii(s: string): boolean {
+  if (!s || s.length > 100_000) return false;
+  let ok = 0;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (
+      code === 9 ||
+      code === 10 ||
+      code === 13 ||
+      (code >= 32 && code < 127)
+    ) {
+      ok++;
+    }
+  }
+  return ok / s.length > 0.85;
+}
+
+function tryBase64Utf8(proof: string): string | null {
+  const t = proof.trim();
+  if (t.length < 8 || !/^[A-Za-z0-9+/=_-]+$/.test(t.replace(/\s/g, ""))) {
+    return null;
+  }
+  const buf = Buffer.from(t, "base64");
+  if (buf.length === 0) return null;
+  const decoded = buf.toString("utf8");
+  if (!decoded || decoded.includes("\0")) return null;
+  if (!looksMostlyPrintableAscii(decoded)) return null;
+  return decoded;
+}
+
+/**
+ * For route handlers: only treat the proof as base64-wrapped UTF-8 when it passes
+ * the same heuristics as replay-key extraction. Raw `0x…` tx hashes and colon proofs
+ * stay intact (unlike unconditional `Buffer.from(s, "base64")`).
+ */
+export function decodePaymentProofForParsing(proof: string): string {
+  return tryBase64Utf8(proof) ?? proof;
+}
+
+function addEvmTxHashes(s: string, into: Set<string>): void {
+  const matches = s.match(/0x[a-fA-F0-9]{64}/g);
+  if (!matches) return;
+  for (const h of matches) into.add(`evm-tx:${h.toLowerCase()}`);
+}
+
+function addSolanaTxSignatures(s: string, into: Set<string>): void {
+  const parts = s.split(":");
+  if (parts.length >= 3 && parts[0]?.toUpperCase() === "SOLANA") {
+    const sig = parts[2]?.trim();
+    if (sig && /^[1-9A-HJ-NP-Za-km-z]{87,88}$/.test(sig)) {
+      into.add(`sol-tx:${sig}`);
+    }
+  }
+  const trimmed = s.trim().split(/\s+/)[0] ?? "";
+  if (/^[1-9A-HJ-NP-Za-km-z]{87,88}$/.test(trimmed)) {
+    into.add(`sol-tx:${trimmed}`);
+  }
+}
+
+function addEip712StableKey(s: string, into: Set<string>): void {
+  let obj: unknown;
+  try {
+    obj = JSON.parse(s);
+  } catch {
+    return;
+  }
+  if (typeof obj !== "object" || obj === null) return;
+  const root = obj as Record<string, unknown>;
+  const payload = root.payload as Record<string, unknown> | undefined;
+  const auth = (payload?.authorization ?? root.authorization) as
+    | Record<string, unknown>
+    | undefined;
+  if (!auth || typeof auth !== "object") return;
+  const domain = (payload?.domain ?? root.domain) as
+    | Record<string, unknown>
+    | undefined;
+  if (
+    typeof auth.from !== "string" ||
+    typeof auth.to !== "string" ||
+    typeof auth.value !== "string" ||
+    typeof auth.nonce !== "string"
+  ) {
+    return;
+  }
+  const contract =
+    domain && typeof domain.verifyingContract === "string"
+      ? domain.verifyingContract.toLowerCase()
+      : "";
+  const chainId =
+    domain && typeof domain.chainId === "number" ? domain.chainId : -1;
+  const stable = JSON.stringify({
+    c: contract,
+    ch: chainId,
+    f: auth.from.toLowerCase(),
+    t: auth.to.toLowerCase(),
+    v: auth.value,
+    n: auth.nonce,
+  });
+  into.add(`eip712:${sha256Utf8(stable)}`);
+}
+
+/**
+ * Canonical replay keys derivable from a payment proof string (raw or base64-wrapped).
+ * Same on-chain tx / Solana signature / EIP-712 intent maps to the same key regardless
+ * of outer encoding (e.g. base64 vs plain).
+ */
+export function replayKeysFromProofString(proof: string): string[] {
+  const keys = new Set<string>();
+  const variants = new Set<string>([proof]);
+  const decoded = tryBase64Utf8(proof);
+  if (decoded) variants.add(decoded);
+  for (const v of variants) {
+    addEvmTxHashes(v, keys);
+    addSolanaTxSignatures(v, keys);
+    addEip712StableKey(v, keys);
+  }
+  return [...keys];
+}
+
+/**
+ * All replay keys to consult before verification and to mark after a successful one.
+ */
+export function collectReplayKeysToCheck(
+  paymentProof?: string,
+  paymentId?: string,
+): string[] {
+  const keys = new Set<string>();
+  if (paymentId) {
+    const pk = paymentIdReplayKey(paymentId);
+    if (pk) keys.add(pk);
+  }
+  if (paymentProof) {
+    for (const k of replayKeysFromProofString(paymentProof)) keys.add(k);
+  }
+  return [...keys];
+}

package/src/x402-resolve.ts

@@ -0,0 +1,43 @@
+import type {
+  AgentRuntime,
+  Character,
+  CharacterX402Settings,
+  PaymentEnabledRoute,
+  X402Config,
+} from "@elizaos/core";
+
+export const X402_EVENT_PAYMENT_VERIFIED = "PAYMENT_VERIFIED";
+export const X402_EVENT_PAYMENT_REQUIRED = "PAYMENT_REQUIRED";
+
+function readCharacterX402(
+  settings: Character["settings"] | undefined,
+): CharacterX402Settings | undefined {
+  if (!settings || typeof settings !== "object") return undefined;
+  const raw = (settings as Record<string, unknown>).x402;
+  if (!raw || typeof raw !== "object") return undefined;
+  return raw as CharacterX402Settings;
+}
+
+/** Resolves `x402: true` / partial route config using `character.settings.x402`. */
+export function resolveEffectiveX402(
+  route: PaymentEnabledRoute,
+  runtime: AgentRuntime,
+): X402Config | null {
+  const cx = readCharacterX402(runtime.character?.settings);
+  const raw = route.x402;
+  if (raw === true) {
+    if (cx?.defaultPriceInCents == null || !cx.defaultPaymentConfigs?.length)
+      return null;
+    return {
+      priceInCents: cx.defaultPriceInCents,
+      paymentConfigs: [...cx.defaultPaymentConfigs],
+    };
+  }
+  if (raw && typeof raw === "object") {
+    const price = raw.priceInCents ?? cx?.defaultPriceInCents;
+    const configs = raw.paymentConfigs ?? cx?.defaultPaymentConfigs;
+    if (price == null || !configs?.length) return null;
+    return { priceInCents: price, paymentConfigs: [...configs] };
+  }
+  return null;
+}