402coffee-verify 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# 402coffee-verify
+
+Gate payments on **verified x402 agents**. One free call to [402.coffee](https://api.402.coffee/docs) tells you whether a paying agent holds a current certificate proving it pays correctly, refuses deliberately over-priced orders, and checks who it's paying — before you transact with it.
+
+- **Free** — the `/verify` check costs nothing. (An optional paid `/score` gives a decision-grade 0–100 risk number.)
+- **Zero dependencies**, Node 18+.
+- Composes with your existing trust/reputation stack: those tell you the counterparty was worth paying; this tells you the agent won't get swapped at signing.
+
+## Install
+
+```bash
+npm install 402coffee-verify
+```
+
+## Library
+
+```js
+import { verify, passesGate, verifyGate } from "402coffee-verify";
+
+// Raw status
+const result = await verify("0xAGENT…");
+result.verified;                       // true = ≥1 current PASS, no current FAIL
+result.capabilities.scam_resistance;   // { tested, result, fresh, expired, valid_until }
+
+// One-shot gate
+const { ok } = await verifyGate("0xAGENT…", {
+  require: ["scam_resistance", "recipient_awareness"], // must hold these
+  fresh: true,                                         // non-expired cert required
+});
+if (!ok) throw new Error("agent not certified safe");
+```
+
+## CLI
+
+```bash
+npx 402coffee-verify 0xAGENT… --require scam_resistance,recipient_awareness
+# exit 0 = pass, 1 = fail, 2 = usage/network error → drop straight into CI/scripts
+```
+
+## Middleware (Express)
+
+```js
+import { requireVerifiedAgent } from "402coffee-verify/middleware";
+
+// Reads the wallet from the `x-agent-wallet` header (override with getWallet)
+app.post("/paid-endpoint",
+  requireVerifiedAgent({ require: ["scam_resistance"], fresh: true }),
+  handler
+);
+```
+
+## Next.js App Router / hono / edge
+
+```js
+import { guardAgent } from "402coffee-verify/middleware";
+
+export async function POST(req) {
+  const wallet = req.headers.get("x-agent-wallet");
+  const gate = await guardAgent(wallet, { require: ["recipient_awareness"] });
+  if (!gate.ok) return gate.response;   // ready 402 Response
+  // …serve the paid action…
+}
+```
+
+## Paid score (optional, $0.10)
+
+`/score` returns a deterministic 0–100 risk score with itemized on-chain evidence. It costs $0.10 in USDC on Base, so you must pass an **x402-paying fetch** (e.g. `wrapFetchWithPayment` from `@x402/fetch`) — with a plain fetch you get back the 402 payment terms, not a score.
+
+```js
+import { score } from "402coffee-verify";
+import { wrapFetchWithPayment } from "@x402/fetch";
+
+const payingFetch = wrapFetchWithPayment(fetch, wallet);
+const s = await score("0xAGENT…", { fetchImpl: payingFetch });
+// s.score, s.tier, s.components, s.payment_history …
+```
+
+## What "verified" means
+
+`verified === true` only when the agent has **at least one current (non-expired) PASS and no current FAIL**. Certificates are valid for 30 days (behaviour drifts); require a fresh one for anything that matters. Every result 402.coffee returns is a fact it observed on-chain — never a subjective grade or a safety guarantee.
+
+Docs: <https://api.402.coffee/docs> · Test your own agent: <https://api.402.coffee/inspect>
+
+MIT © Agent Café / 402.coffee

package/bin/402coffee-verify.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// CLI: gate on an agent's 402.coffee verification status.
+//
+//   npx 402coffee-verify 0x<wallet> [--require scam_resistance,recipient_awareness]
+//                                    [--no-fresh] [--json] [--base <url>]
+//
+// Exit codes:  0 = gate passes   1 = gate fails   2 = usage / network error
+
+import { verify, passesGate, capabilityHeld, DEFAULT_BASE_URL } from "../index.js";
+
+function parseArgs(argv) {
+  const args = { require: [], fresh: true, json: false, baseUrl: DEFAULT_BASE_URL, wallet: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--no-fresh") args.fresh = false;
+    else if (a === "--require") args.require = (argv[++i] || "").split(",").map((s) => s.trim()).filter(Boolean);
+    else if (a === "--base") args.baseUrl = argv[++i];
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (!a.startsWith("-") && !args.wallet) args.wallet = a;
+  }
+  return args;
+}
+
+const HELP = `402coffee-verify — check if a paying agent is certified safe (free)
+
+Usage:
+  402coffee-verify 0x<wallet> [options]
+
+Options:
+  --require <caps>   comma list that MUST be held, e.g.
+                     scam_resistance,recipient_awareness
+  --no-fresh         accept expired certs (default: require a current one)
+  --json             print the full /verify JSON
+  --base <url>       API base (default ${DEFAULT_BASE_URL})
+  -h, --help         this help
+
+Exit: 0 gate passes | 1 gate fails | 2 usage/network error
+Docs: https://api.402.coffee/docs`;
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.wallet) {
+    console.log(HELP);
+    process.exit(args.wallet ? 0 : 2);
+  }
+  let result;
+  try {
+    result = await verify(args.wallet, { baseUrl: args.baseUrl });
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    process.exit(2);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const caps = ["scam_resistance", "recipient_awareness", "can_pay", "full_suite"];
+    console.log(`wallet    ${result.wallet}`);
+    console.log(`verified  ${result.verified ? "yes" : "no"}${result.tested ? "" : " (never tested)"}`);
+    for (const c of caps) {
+      const held = capabilityHeld(result, c, { fresh: args.fresh });
+      const cap = result.capabilities?.[c];
+      const detail = !cap || cap.tested !== true ? "not tested"
+        : `${cap.result}${cap.fresh === false ? " (stale)" : ""}`;
+      console.log(`  ${held ? "✓" : "·"} ${c.padEnd(20)} ${detail}`);
+    }
+  }
+
+  const ok = passesGate(result, { require: args.require, fresh: args.fresh });
+  if (!args.json) {
+    console.log(ok ? "\nGATE: PASS" : "\nGATE: FAIL");
+    if (!ok) console.log(`Not certified for your requirement. Test at ${result.how_to_test || "https://api.402.coffee/inspect"}`);
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+main();

package/index.d.ts

@@ -0,0 +1,73 @@
+// Type definitions for 402coffee-verify
+
+export const DEFAULT_BASE_URL: string;
+
+export type CapabilityName =
+  | "scam_resistance"
+  | "recipient_awareness"
+  | "can_pay"
+  | "full_suite";
+
+export interface Capability {
+  tested: boolean;
+  result?: "pass" | "fail";
+  fresh?: boolean;
+  expired?: boolean;
+  valid_until?: string;
+}
+
+export interface Cert {
+  product: string;
+  level: string;
+  passed: number;
+  total: number;
+  result: "pass" | "fail";
+  test_version: number;
+  test_version_means: string;
+  issued: string;
+  age_days: number;
+  fresh: boolean;
+  expired: boolean;
+  valid_until: string;
+  cert_url: string;
+  badge_url: string;
+}
+
+export interface VerifyResult {
+  service: string;
+  wallet: string;
+  tested: boolean;
+  verified: boolean;
+  verified_means: string;
+  capabilities: Record<CapabilityName, Capability>;
+  certs: Cert[];
+  freshness_policy: { valid_for_days: number; note: string };
+  how_to_test: string;
+  paid_score?: { note: string; url: string };
+  checked_at: string;
+}
+
+export interface VerifyOptions {
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export interface GateOptions {
+  requireVerified?: boolean;
+  require?: CapabilityName[];
+  fresh?: boolean;
+}
+
+export function verify(wallet: string, opts?: VerifyOptions): Promise<VerifyResult>;
+export function capabilityHeld(
+  result: VerifyResult,
+  name: CapabilityName,
+  opts?: { fresh?: boolean }
+): boolean;
+export function passesGate(result: VerifyResult, opts?: GateOptions): boolean;
+export function verifyGate(
+  wallet: string,
+  opts?: VerifyOptions & GateOptions
+): Promise<{ ok: boolean; result: VerifyResult }>;
+export function score(wallet: string, opts?: VerifyOptions): Promise<Record<string, unknown>>;

package/index.js

@@ -0,0 +1,134 @@
+// 402coffee-verify — gate payments on verified x402 agents.
+// Zero dependencies. Node 18+ (uses global fetch / AbortController).
+//
+// The primitive is the FREE GET /verify endpoint on 402.coffee. It tells you
+// whether a paying agent holds a current certificate proving it pays correctly,
+// refuses over-priced orders, and checks who it is paying.
+//
+// Docs: https://api.402.coffee/docs
+
+export const DEFAULT_BASE_URL = "https://api.402.coffee";
+
+const WALLET_RE = /^0x[0-9a-fA-F]{40}$/;
+
+/**
+ * Look up an agent's public verification status. Free, no payment.
+ * @param {string} wallet 0x-prefixed 40-hex address
+ * @param {object} [opts]
+ * @param {string} [opts.baseUrl] default https://api.402.coffee
+ * @param {typeof fetch} [opts.fetchImpl] custom fetch (e.g. for tests)
+ * @param {number} [opts.timeoutMs] default 8000
+ * @returns {Promise<object>} the raw /verify JSON (see index.d.ts VerifyResult)
+ */
+export async function verify(wallet, opts = {}) {
+  if (typeof wallet !== "string" || !WALLET_RE.test(wallet.trim())) {
+    throw new Error(`invalid wallet address: ${wallet} (expected 0x + 40 hex)`);
+  }
+  const base = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) throw new Error("no fetch available; pass opts.fetchImpl on Node < 18");
+  const timeoutMs = opts.timeoutMs ?? 8000;
+
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(
+      `${base}/verify?wallet=${encodeURIComponent(wallet.trim())}`,
+      { headers: { accept: "application/json" }, signal: ctrl.signal }
+    );
+    if (!res.ok) throw new Error(`verify failed: HTTP ${res.status}`);
+    return await res.json();
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/**
+ * Is a single named capability currently held (tested + pass + not expired)?
+ * @param {object} result a VerifyResult from verify()
+ * @param {"scam_resistance"|"recipient_awareness"|"can_pay"|"full_suite"} name
+ * @param {object} [opts]
+ * @param {boolean} [opts.fresh] require a non-expired cert (default true)
+ * @returns {boolean}
+ */
+export function capabilityHeld(result, name, opts = {}) {
+  const fresh = opts.fresh !== false;
+  const c = result?.capabilities?.[name];
+  if (!c || c.tested !== true) return false;
+  if (c.result !== "pass") return false;
+  if (c.expired === true) return false;
+  if (fresh && c.fresh !== true) return false;
+  return true;
+}
+
+/**
+ * Decide whether an agent passes your gate.
+ * @param {object} result a VerifyResult from verify()
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireVerified] require top-level verified=true (default true)
+ * @param {Array<string>} [opts.require] capabilities that must be held, e.g.
+ *        ["scam_resistance","recipient_awareness"]
+ * @param {boolean} [opts.fresh] require non-expired certs (default true)
+ * @returns {boolean}
+ */
+export function passesGate(result, opts = {}) {
+  const requireVerified = opts.requireVerified !== false;
+  const fresh = opts.fresh !== false;
+  const required = Array.isArray(opts.require) ? opts.require : [];
+  if (requireVerified && result?.verified !== true) return false;
+  for (const cap of required) {
+    if (!capabilityHeld(result, cap, { fresh })) return false;
+  }
+  return true;
+}
+
+/**
+ * Convenience: look up + gate in one call. Returns { ok, result }.
+ * Never throws on a failed gate — only on a network/validation error.
+ * @param {string} wallet
+ * @param {object} [opts] merged verify() + passesGate() options
+ * @returns {Promise<{ok: boolean, result: object}>}
+ */
+export async function verifyGate(wallet, opts = {}) {
+  const result = await verify(wallet, opts);
+  return { ok: passesGate(result, opts), result };
+}
+
+/**
+ * Paid decision-grade score ($0.10 via x402). Requires an x402-paying fetch
+ * (e.g. wrapFetchWithPayment from @x402/fetch) passed as opts.fetchImpl — with a
+ * plain fetch this returns the 402 payment terms, not a score. Honest by design:
+ * we never fake a paid result.
+ * @param {string} wallet
+ * @param {object} [opts]
+ * @param {string} [opts.baseUrl]
+ * @param {typeof fetch} [opts.fetchImpl] an x402-paying fetch to actually pay
+ * @param {number} [opts.timeoutMs] default 15000
+ * @returns {Promise<object>} the score JSON, or the 402 terms if unpaid
+ */
+export async function score(wallet, opts = {}) {
+  if (typeof wallet !== "string" || !WALLET_RE.test(wallet.trim())) {
+    throw new Error(`invalid wallet address: ${wallet} (expected 0x + 40 hex)`);
+  }
+  const base = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) throw new Error("no fetch available; pass opts.fetchImpl");
+  const timeoutMs = opts.timeoutMs ?? 15000;
+
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${base}/score`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ wallet: wallet.trim() }),
+      signal: ctrl.signal,
+    });
+    // 402 (unpaid) still returns useful JSON (the payment terms) — return it as-is.
+    return await res.json();
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export default { verify, capabilityHeld, passesGate, verifyGate, score, DEFAULT_BASE_URL };

package/middleware.js

@@ -0,0 +1,79 @@
+// Drop-in middleware for gating routes on 402.coffee verification.
+// import { requireVerifiedAgent } from "402coffee-verify/middleware";
+
+import { verify, passesGate, DEFAULT_BASE_URL } from "./index.js";
+
+/**
+ * Express middleware. Blocks the request unless the agent's wallet is verified.
+ *
+ *   app.post("/paid", requireVerifiedAgent({ require: ["scam_resistance"] }), handler)
+ *
+ * @param {object} [opts]
+ * @param {(req:any)=>string|undefined} [opts.getWallet] how to read the wallet
+ *        (default: header `x-agent-wallet`, then `?wallet=`)
+ * @param {string[]} [opts.require] capabilities that must be held
+ * @param {boolean} [opts.fresh] require non-expired certs (default true)
+ * @param {string}  [opts.baseUrl]
+ */
+export function requireVerifiedAgent(opts = {}) {
+  const baseUrl = opts.baseUrl || DEFAULT_BASE_URL;
+  const getWallet =
+    opts.getWallet || ((req) => req.headers?.["x-agent-wallet"] || req.query?.wallet);
+  return async function (req, res, next) {
+    const wallet = getWallet(req);
+    if (!wallet) {
+      return res.status(400).json({ error: "missing agent wallet (send header x-agent-wallet)" });
+    }
+    try {
+      const result = await verify(wallet, { baseUrl });
+      if (passesGate(result, { require: opts.require, fresh: opts.fresh })) return next();
+      return res.status(402).json({
+        error: "agent not verified for this action",
+        verify: `${baseUrl}/verify?wallet=${wallet}`,
+        get_certified: "https://api.402.coffee/inspect",
+      });
+    } catch (e) {
+      // Fail closed on a paid path: if we cannot verify, do not let it through.
+      return res.status(502).json({ error: "verification check failed", detail: String(e) });
+    }
+  };
+}
+
+/**
+ * Framework-agnostic guard for Next.js App Router / hono / edge handlers.
+ * Returns { ok, result, response? } — if !ok, `response` is a ready Response.
+ *
+ *   const gate = await guardAgent(wallet, { require: ["recipient_awareness"] });
+ *   if (!gate.ok) return gate.response;
+ */
+export async function guardAgent(wallet, opts = {}) {
+  const baseUrl = opts.baseUrl || DEFAULT_BASE_URL;
+  if (!wallet) {
+    return {
+      ok: false,
+      response: Response.json({ error: "missing agent wallet" }, { status: 400 }),
+    };
+  }
+  try {
+    const result = await verify(wallet, { baseUrl });
+    const ok = passesGate(result, { require: opts.require, fresh: opts.fresh });
+    if (ok) return { ok: true, result };
+    return {
+      ok: false,
+      result,
+      response: Response.json(
+        {
+          error: "agent not verified for this action",
+          verify: `${baseUrl}/verify?wallet=${wallet}`,
+          get_certified: "https://api.402.coffee/inspect",
+        },
+        { status: 402 }
+      ),
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      response: Response.json({ error: "verification check failed", detail: String(e) }, { status: 502 }),
+    };
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "402coffee-verify",
+  "version": "0.1.0",
+  "description": "Gate payments on verified x402 agents. One free call to 402.coffee — check if a paying agent is certified safe (pays correctly, refuses over-priced scams, verifies the recipient). Zero dependencies.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "402coffee-verify": "bin/402coffee-verify.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./middleware": {
+      "import": "./middleware.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "middleware.js",
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "x402",
+    "agent",
+    "payments",
+    "verification",
+    "trust",
+    "usdc",
+    "base",
+    "conformance",
+    "402.coffee"
+  ],
+  "license": "MIT",
+  "homepage": "https://api.402.coffee/integrations"
+}