@elizaos/plugin-x402 2.0.0-beta.1 → 2.0.3-beta.5

package/dist/payment-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payment-wrapper.d.ts","sourceRoot":"","sources":["../src/payment-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,mBAAmB,EACnB,KAAK,EAIN,MAAM,eAAe,CAAC;AAsEvB;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAEtC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAquCD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,GACzB,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CA0Q/B;AAqTD,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,KAAK,EAAE,CAkCT"}
+{"version":3,"file":"payment-wrapper.d.ts","sourceRoot":"","sources":["../src/payment-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,mBAAmB,EACnB,KAAK,EAIN,MAAM,eAAe,CAAC;AAsEvB;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAEtC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAquCD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,GACzB,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CA4Q/B;AAqTD,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,KAAK,EAAE,CAsCT"}

package/dist/startup-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup-validator.d.ts","sourceRoot":"","sources":["../src/startup-validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EAGT,KAAK,EACN,MAAM,eAAe,CAAC;AAUvB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAiQD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,uBAAuB,CAoCzB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,IAAI,CAUN"}
+{"version":3,"file":"startup-validator.d.ts","sourceRoot":"","sources":["../src/startup-validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EAGT,KAAK,EACN,MAAM,eAAe,CAAC;AAUvB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAmQD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,uBAAuB,CAoCzB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,IAAI,CAUN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-x402",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.5",
   "description": "x402 micropayment middleware for elizaOS plugin HTTP routes",
   "type": "module",
   "main": "dist/index.js",
@@ -17,8 +17,24 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
@@ -44,22 +60,25 @@
   "scripts": {
     "build": "bun run build.ts",
     "build:ts": "bun run build.ts",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit",
-    "lint": "echo \"Lint skipped\"",
-    "lint:check": "bun run lint"
+    "clean": "node ../../packages/scripts/rm-path-recursive.mjs dist",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit",
+    "lint": "bun run typecheck",
+    "lint:check": "bun run typecheck"
   },
   "dependencies": {
-    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/core": "2.0.3-beta.5",
+    "@solana/web3.js": "1.98.4",
     "drizzle-orm": "0.45.2",
     "viem": "^2.48.8"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-beta.1"
+    "@elizaos/core": "2.0.3-beta.5"
   },
   "publishConfig": {
     "access": "public"
@@ -67,5 +86,6 @@
   "agentConfig": {
     "pluginType": "elizaos:plugin:1.0.0",
     "pluginParameters": {}
-  }
+  },
+  "gitHead": "ff6157011c9459670021cc28a6797592a78b8817"
 }

package/src/__tests__/core-test-mock.ts

@@ -0,0 +1,10 @@
+import { vi } from "vitest";
+
+vi.mock("@elizaos/core", () => ({
+  logger: {
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  },
+}));

package/src/index.ts

@@ -66,16 +66,16 @@ export {
   isRoutePaymentWrapped,
   X402_ROUTE_PAYMENT_WRAPPED,
 } from "./payment-wrapper.js";
-export {
-  resolveEffectiveX402,
-  X402_EVENT_PAYMENT_REQUIRED,
-  X402_EVENT_PAYMENT_VERIFIED,
-} from "./x402-resolve.js";
 export {
   type StartupValidationResult,
   validateAndThrowIfInvalid,
   validateX402Startup,
 } from "./startup-validator.js";
+export {
+  resolveEffectiveX402,
+  X402_EVENT_PAYMENT_REQUIRED,
+  X402_EVENT_PAYMENT_VERIFIED,
+} from "./x402-resolve.js";
 
 export {
   type Accepts,
@@ -107,6 +107,8 @@ const x402Plugin: Plugin = {
   providers: [],
   evaluators: [],
   services: [],
+  // Middleware-only plugin — no service instances or persistent resources to dispose.
+  dispose: async (_runtime) => {},
 };
 
 export default x402Plugin;

package/src/payment-wrapper.test.ts

@@ -0,0 +1,234 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  applyPaymentProtection,
+  isRoutePaymentWrapped,
+} from "./payment-wrapper.js";
+
+function makeResponse() {
+  const res = {
+    headersSent: false,
+    statusCode: 200,
+    headers: new Map<string, string>(),
+    setHeader: vi.fn((name: string, value: string) => {
+      res.headers.set(name, value);
+      return res;
+    }),
+    status: vi.fn((code: number) => {
+      res.statusCode = code;
+      return res;
+    }),
+    json: vi.fn((body: unknown) => body),
+  };
+  return res;
+}
+
+function decodePaymentRequiredHeader(res: ReturnType<typeof makeResponse>) {
+  const encoded = res.headers.get("PAYMENT-REQUIRED");
+  expect(encoded).toEqual(expect.any(String));
+  return JSON.parse(Buffer.from(String(encoded), "base64").toString("utf8")) as
+    | Record<string, unknown>
+    | undefined;
+}
+
+describe("applyPaymentProtection", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("rejects non-array route input", () => {
+    expect(() => applyPaymentProtection({} as never)).toThrow(
+      "routes must be an array",
+    );
+  });
+
+  it("leaves unprotected routes unchanged", () => {
+    const route = { path: "/free", type: "GET", handler: vi.fn() } as never;
+
+    const [result] = applyPaymentProtection([route]);
+
+    expect(result).toBe(route);
+    expect(isRoutePaymentWrapped(result)).toBe(false);
+  });
+
+  it("wraps protected routes and returns payment-required responses", async () => {
+    const handler = vi.fn();
+    const route = {
+      path: "/paid",
+      type: "GET",
+      handler,
+      x402: { priceInCents: 25, paymentConfigs: ["base_usdc"] },
+    } as never;
+    const runtime = { agentId: "agent-1", emitEvent: vi.fn() };
+    const res = makeResponse();
+
+    const [wrapped] = applyPaymentProtection([route], {
+      agentId: "agent-1",
+    });
+
+    expect(wrapped).not.toBe(route);
+    expect(isRoutePaymentWrapped(wrapped)).toBe(true);
+
+    await wrapped.handler?.(
+      { method: "GET", headers: {}, query: {} } as never,
+      res as never,
+      runtime as never,
+    );
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(402);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ x402Version: 1 }),
+    );
+    expect(runtime.emitEvent).toHaveBeenCalledWith(
+      "PAYMENT_REQUIRED",
+      expect.objectContaining({
+        path: "/paid",
+        reason: "payment_required",
+      }),
+    );
+    expect(res.headers.get("Access-Control-Expose-Headers")).toContain(
+      "PAYMENT-REQUIRED",
+    );
+    expect(decodePaymentRequiredHeader(res)).toEqual(
+      expect.objectContaining({
+        error: "Payment Required",
+      }),
+    );
+  });
+
+  it("handles route requests with missing optional headers and query", async () => {
+    const handler = vi.fn();
+    const route = {
+      path: "/paid",
+      type: "POST",
+      handler,
+      x402: { priceInCents: 10, paymentConfigs: ["base_usdc"] },
+    } as never;
+    const runtime = { agentId: "agent-1", emitEvent: vi.fn() };
+    const res = makeResponse();
+    const [wrapped] = applyPaymentProtection([route], {
+      agentId: "agent-1",
+    });
+
+    await wrapped.handler?.({ method: "POST" } as never, res as never, runtime as never);
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(402);
+    expect(runtime.emitEvent).toHaveBeenCalledWith(
+      "PAYMENT_REQUIRED",
+      expect.objectContaining({ reason: "payment_required" }),
+    );
+  });
+
+  it("returns payment-required responses when validators fail before proof checks", async () => {
+    const handler = vi.fn();
+    const route = {
+      path: "/paid",
+      type: "GET",
+      handler,
+      validator: vi.fn(async () => ({
+        valid: false,
+        error: {
+          message: "bad request",
+          details: { field: "amount" },
+        },
+      })),
+      x402: { priceInCents: 10, paymentConfigs: ["base_usdc"] },
+    } as never;
+    const runtime = { agentId: "agent-1", emitEvent: vi.fn() };
+    const res = makeResponse();
+    const [wrapped] = applyPaymentProtection([route], {
+      agentId: "agent-1",
+    });
+
+    await wrapped.handler?.(
+      {
+        method: "GET",
+        headers: { "x-payment-id": "valid-looking-id" },
+        query: {},
+      } as never,
+      res as never,
+      runtime as never,
+    );
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(route.validator).toHaveBeenCalledTimes(1);
+    expect(res.status).toHaveBeenCalledWith(402);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: 'bad request: {"field":"amount"}',
+      }),
+    );
+    expect(runtime.emitEvent).toHaveBeenCalledWith(
+      "PAYMENT_REQUIRED",
+      expect.objectContaining({ reason: "validator_failed" }),
+    );
+    expect(decodePaymentRequiredHeader(res)).toEqual(
+      expect.objectContaining({
+        error: 'bad request: {"field":"amount"}',
+      }),
+    );
+  });
+
+  it("rejects hostile payment ids before facilitator fetch", async () => {
+    const handler = vi.fn();
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const route = {
+      path: "/paid",
+      type: "GET",
+      handler,
+      x402: { priceInCents: 10, paymentConfigs: ["base_usdc"] },
+    } as never;
+    const runtime = {
+      agentId: "agent-1",
+      emitEvent: vi.fn(),
+      getSetting: vi.fn(() => "https://facilitator.test"),
+    };
+    const res = makeResponse();
+    const [wrapped] = applyPaymentProtection([route], {
+      agentId: "agent-1",
+    });
+
+    await wrapped.handler?.(
+      {
+        method: "GET",
+        headers: { "x-payment-id": "../paid\n" },
+        query: {},
+      } as never,
+      res as never,
+      runtime as never,
+    );
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(handler).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(402);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error: "Payment verification failed",
+      }),
+    );
+    expect(runtime.emitEvent).toHaveBeenCalledWith(
+      "PAYMENT_REQUIRED",
+      expect.objectContaining({ reason: "verification_failed" }),
+    );
+  });
+
+  it("does not wrap routes that are already marked as wrapped", () => {
+    const route = {
+      path: "/paid",
+      type: "GET",
+      handler: vi.fn(),
+      x402: { priceInCents: 25, paymentConfigs: ["base_usdc"] },
+    } as never;
+
+    const [wrapped] = applyPaymentProtection([route]);
+    const firstHandler = wrapped.handler;
+    const [again] = applyPaymentProtection([wrapped]);
+
+    expect(again).toBe(wrapped);
+    expect(again.handler).toBe(firstHandler);
+    expect(isRoutePaymentWrapped(again)).toBe(true);
+  });
+});

package/src/payment-wrapper.ts

@@ -1473,24 +1473,26 @@ export function createPaymentAwareHandler(
       }
     }
 
-    log("Headers:", JSON.stringify(typedReq.headers, null, 2));
-    log("Query:", JSON.stringify(typedReq.query, null, 2));
+    const requestHeaders = typedReq.headers ?? {};
+    const requestQuery = typedReq.query ?? {};
+
+    log("Headers:", JSON.stringify(requestHeaders, null, 2));
+    log("Query:", JSON.stringify(requestQuery, null, 2));
     if (typedReq.method === "POST" && typedReq.body) {
       log("Body:", JSON.stringify(typedReq.body, null, 2));
     }
 
     const paymentProof =
-      typedReq.headers["x-payment-proof"] ||
-      typedReq.headers["x-payment"] ||
-      typedReq.headers["payment-signature"] ||
-      typedReq.query?.paymentProof;
-    const paymentId =
-      typedReq.headers["x-payment-id"] || typedReq.query?.paymentId;
+      requestHeaders["x-payment-proof"] ||
+      requestHeaders["x-payment"] ||
+      requestHeaders["payment-signature"] ||
+      requestQuery.paymentProof;
+    const paymentId = requestHeaders["x-payment-id"] || requestQuery.paymentId;
 
     log("Payment credentials:", {
-      "x-payment-proof": !!typedReq.headers["x-payment-proof"],
-      "x-payment": !!typedReq.headers["x-payment"],
-      "payment-signature": !!typedReq.headers["payment-signature"],
+      "x-payment-proof": !!requestHeaders["x-payment-proof"],
+      "x-payment": !!requestHeaders["x-payment"],
+      "payment-signature": !!requestHeaders["payment-signature"],
       "x-payment-id": !!paymentId,
       found: !!(paymentProof || paymentId),
     });
@@ -1974,6 +1976,10 @@ export function applyPaymentProtection(
   return routes.map((route) => {
     const x402Route = route as PaymentEnabledRoute;
     if (x402Route.x402 != null) {
+      if (isRoutePaymentWrapped(route)) {
+        return route;
+      }
+
       logger.debug(
         { path: x402Route.path, x402: x402Route.x402 },
         "[x402] payment protection enabled",

package/src/startup-validator.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { validateX402Startup } from "./startup-validator.js";
+
+const originalEnv = { ...process.env };
+
+function paidRoute(x402: unknown, overrides: Record<string, unknown> = {}) {
+  return {
+    path: "/paid",
+    type: "GET",
+    handler: vi.fn(),
+    x402,
+    ...overrides,
+  } as never;
+}
+
+describe("validateX402Startup", () => {
+  beforeEach(() => {
+    process.env = { ...originalEnv, NODE_ENV: "test" };
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("rejects x402 true when character defaults are missing", () => {
+    const result = validateX402Startup([paidRoute(true)]);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("defaultPriceInCents"),
+        expect.stringContaining("defaultPaymentConfigs"),
+      ]),
+    );
+  });
+
+  it("uses character defaults for partial route configuration", () => {
+    const result = validateX402Startup(
+      [paidRoute({ priceInCents: 25 })],
+      {
+        settings: {
+          x402: {
+            defaultPriceInCents: 10,
+            defaultPaymentConfigs: ["base_usdc"],
+          },
+        },
+      } as never,
+    );
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it("rejects unknown payment config names", () => {
+    const result = validateX402Startup([
+      paidRoute({ priceInCents: 25, paymentConfigs: ["missing_config"] }),
+    ]);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual([
+      expect.stringContaining("unknown payment config 'missing_config'"),
+    ]);
+  });
+
+  it("rejects primitive x402 values", () => {
+    const result = validateX402Startup([paidRoute("yes")]);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual([
+      expect.stringContaining("x402 must be true or a configuration object"),
+    ]);
+  });
+
+  it("rejects protected routes without handlers", () => {
+    const result = validateX402Startup([
+      paidRoute({ priceInCents: 25, paymentConfigs: ["base_usdc"] }, {
+        handler: undefined,
+      }),
+    ]);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual([
+      expect.stringContaining("route has x402 protection but no handler"),
+    ]);
+  });
+});

package/src/startup-validator.ts

@@ -175,7 +175,7 @@ function validateX402Route(
         `${routePath}: x402: true requires character.settings.x402.defaultPaymentConfigs (non-empty array)`,
       );
     }
-  } else if (typeof raw === "object") {
+  } else if (typeof raw === "object" && !Array.isArray(raw)) {
     priceInCents = raw.priceInCents ?? cx?.defaultPriceInCents;
     paymentConfigs = (raw.paymentConfigs ?? cx?.defaultPaymentConfigs) as
       | string[]
@@ -190,6 +190,8 @@ function validateX402Route(
         `${routePath}: x402.paymentConfigs is required (or set character.settings.x402.defaultPaymentConfigs)`,
       );
     }
+  } else {
+    errors.push(`${routePath}: x402 must be true or a configuration object`);
   }
 
   if (priceInCents !== undefined && priceInCents !== null) {

package/src/x402-replay-guard.ts

@@ -135,7 +135,7 @@ export async function replayGuardCommit(
   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.
+  // layer skips the owner-bound path instead of recording wrong lineage.
   let owner: string | undefined;
   let ownerConsistent = true;
   for (const k of keys) {