wayleave 0.5.4 → 0.5.7

package/README.md

@@ -25,7 +25,7 @@ Then policy runs per lane: allow, deny, rate-limit — and on routes you price,
 
 Only the first lane is cryptographic. The other three are read off what the client says about itself, so a bot willing to lie reaches the human lane — see [Guarantees](#guarantees-honestly-stated), and set `strictPricedPaths` on anything you charge for.
 
-## Two ways to use it
+## Three ways to use it
 
 **1. The hosted Identity API — no install, any language.** Post a request's
 signature headers and get back who signed it and which lane it belongs in.
@@ -54,6 +54,25 @@ way to know which to believe.
 you do not send. This is the path if you want to price routes, enforce access
 rules, or stay in-process. Start below.
 
+**3. A platform adapter — if your code does not run on Node.** This package is
+Express middleware and Node's crypto; it cannot run on a Worker or a Deno
+edge function. These can, share one policy engine with it, and are configured
+the same way:
+
+| Where you run | Install |
+|---|---|
+| Cloudflare Workers | [`@wayleave/cloudflare`](https://www.npmjs.com/package/@wayleave/cloudflare) |
+| Vercel middleware | [`@wayleave/vercel`](https://www.npmjs.com/package/@wayleave/vercel) |
+| Supabase Edge Functions | [`@wayleave/supabase`](https://www.npmjs.com/package/@wayleave/supabase) |
+| Netlify Edge Functions | [`@wayleave/netlify`](https://www.npmjs.com/package/@wayleave/netlify) |
+| An MCP server | [`@wayleave/mcp`](https://www.npmjs.com/package/@wayleave/mcp) |
+
+All four HTTP adapters default to observe mode and fail open, exactly as this
+one does. The MCP guard is the odd one: an MCP server has no HTTP request to
+inspect and MCP clients carry no signatures, so it does not classify lanes at
+all — it bounds tool calls by rate, budget and repetition instead, and says
+`classification: "unknown"` rather than guessing.
+
 ## Quickstart: observe first
 
 ```sh

package/index.d.ts

@@ -264,7 +264,16 @@ export interface WayleaveOptions {
   /** Window length in seconds. Default 60. */
   rateWindow?: number;
   /** Path prefix -> price in USD. Non-human lanes get 402 here. */
-  pricedPaths?: Record<string, number>;
+  /** A price, or a price with the method and description to publish.
+   *  A bare number keeps the old behaviour: GET, generic description. */
+  pricedPaths?: Record<string, number | {
+    price: number | string;
+    /** The HTTP method this route actually serves. Default GET.
+     *  Publishing GET for a POST API advertises a call that cannot work. */
+    method?: string;
+    description?: string;
+    mimeType?: string;
+  }>;
   /**
    * Confirms a payment actually settled. **Without this, every priced route
    * stays 402 forever** — deny is the only safe default, since the proof is a

package/index.js

@@ -25,7 +25,7 @@ import { MeterSink } from './meter.js';
 import { RemotePolicy } from './policy.js';
 import { evaluatePolicy, evaluatePolicySync } from './policy-engine.js';
 import { Registry } from './registry.js';
-import { ManifestServer, MANIFEST_PATHS, originFor, paymentRequirementsFor } from './manifest.js';
+import { ManifestServer, MANIFEST_PATHS, originFor, paymentRequirementsFor, routeSpec } from './manifest.js';
 
 export const LANES = Object.freeze({
   VERIFIED: 'verified_agent',
@@ -81,6 +81,30 @@ function headerValue(headers, name) {
   return Array.isArray(v) ? v.join(', ') : (v == null ? '' : String(v));
 }
 
+/**
+ * The payment header, read under both names.
+ *
+ * x402 calls this `X-PAYMENT`. This gate shipped reading only
+ * `x-payment-proof`, a name of its own invention, and nothing read the
+ * standard one. So an agent that did everything right — fetched
+ * /.well-known/x402, read the `accepts` block this gate itself publishes,
+ * and paid exactly as the protocol specifies — had its payment ignored and
+ * received a second 402. The gate advertised x402 and could not be paid by
+ * x402, which is the one thing it exists to do.
+ *
+ * `X-PAYMENT` wins because it is what the protocol mandates and what a
+ * stranger's agent sends without being told. `x-payment-proof` is still read
+ * so anything already deployed against it keeps working; this is strictly a
+ * superset.
+ *
+ * The value is passed through untouched. This gate does not parse payments —
+ * `verifyPayment` does, and it is yours — so this is a transport fix, not a
+ * protocol implementation.
+ */
+function paymentHeader(headers) {
+  return headerValue(headers, 'x-payment') || headerValue(headers, 'x-payment-proof');
+}
+
 /**
  * Build the signature base from the components the signer actually declared,
  * not from a fixed list. An agent covering only ("@authority") is valid.
@@ -344,7 +368,18 @@ export function classify(req, directories, now, opts = {}) {
   if (h['signature'] || h['signature-input'])
     return { lane: LANES.SUSPECT, agentId: null,
              evidence: [`crypto: ${v.reason}`, 'presented invalid signature'] };
-  if (AGENT_UA.some(p => p.test(ua))) {
+  /* WHICH pattern matched, not merely that one did.
+     
+     This used to be `.some(...)`, and the evidence then quoted the first 40
+     characters of the user-agent. Almost every bot UA opens with a Mozilla
+     compatibility preamble and names itself at the END, so the quote cut off
+     exactly where the identifying part began: 486 crossings on one site all
+     recorded as `mozilla/5.0 applewebkit/537.36 (khtml, l`, indistinguishable
+     from each other and from a browser.
+     
+     The matched pattern is the name. It was in hand and discarded. */
+  const agentMatch = AGENT_UA.map(p => (p.exec(ua) || [])[0]).find(Boolean);
+  if (agentMatch) {
     // A UA naming a known operator is a claim, and claims are checkable when
     // the operator publishes its addresses. Claiming to be GPTBot from an
     // address OpenAI does not own is a stronger fraud signal than saying
@@ -356,10 +391,10 @@ export function classify(req, directories, now, opts = {}) {
       : null;
     if (ipOk === false)
       return { lane: LANES.SUSPECT, agentId: null,
-               evidence: [`UA claims "${ua.slice(0, 40)}"`,
+               evidence: [`UA claims "${agentMatch}"`,
                           `but ${opts.ip || 'the client'} is not a published address for it`] };
     return { lane: LANES.DECLARED, agentId: null,
-             evidence: [`self-identified in UA: "${ua.slice(0, 40)}"`,
+             evidence: [`self-identified as "${agentMatch}"`,
                         ipOk === true ? 'source address matches published range'
                                       : 'no signature presented'] };
   }
@@ -471,6 +506,7 @@ export class Wayleave {
    *   rules: { [lane]: [ [pathPrefix, allow], ... ] },
    *   rateLimits: { [lane]: perWindow }, rateWindow: 60,
    *   pricedPaths: { pathPrefix: priceUsd },
+   *   pricedPaths: { pathPrefix: { price, method, description } },
    *   verifyPayment: (proof, ctx) => boolean | { ok, ref },
    *   strictPricedPaths: false,
    *   confirmHuman: (req) => boolean,
@@ -617,7 +653,7 @@ export class Wayleave {
                        { verifyAgentIP: this.verifyAgentIP, ip: this._client(r) });
     const { lane, agentId, evidence } = c;
     const ident = agentId || `${lane}:${this._client(r)}`;
-    const proof = paymentProof || headerValue(req.headers, 'x-payment-proof');
+    const proof = paymentProof || paymentHeader(req.headers);
     /* The same policy the async path enforces, evaluated here for every rule
        that needs no I/O. Before this, `handle()` skipped policy entirely and
        one document behaved as two: enforced through express(), ignored here. */
@@ -676,7 +712,7 @@ export class Wayleave {
                        { verifyAgentIP: this.verifyAgentIP, ip: this._client(r) });
     const { lane, agentId, evidence } = c;
     const ident = agentId || `${lane}:${this._client(r)}`;
-    const proof = paymentProof || headerValue(req.headers, 'x-payment-proof');
+    const proof = paymentProof || paymentHeader(req.headers);
     const fromPolicy = await this._policyDecision(r, lane, ident, c);
     const d = fromPolicy || await this._decideAsync(r, lane, ident, now, proof, c);
     const entry = { v: 1, idempotencyKey: `${this._instance}:${this._seq++}`,
@@ -765,8 +801,13 @@ export class Wayleave {
       ? this._confirmedHuman(req)
       : lane === LANES.HUMAN;
     if (!freeOnPriced) {
-      for (const [prefix, price] of Object.entries(this.pricedPaths)) {
+      for (const [prefix, configured] of Object.entries(this.pricedPaths)) {
         if (pathUnder(req.path, prefix)) {
+          /* Through routeSpec, so a route configured with a method and a
+             description still charges its price and not the object holding
+             it. The manifest reads the same function, so the document and
+             this challenge cannot disagree about what a route costs. */
+          const { price } = routeSpec(configured);
           const challenge = { scheme: 'x402', price_usd: price, resource: prefix };
           if (!paymentProof) {
             const why = this.strictPricedPaths && lane === LANES.HUMAN
@@ -999,7 +1040,7 @@ export class Wayleave {
         // none of which survive the projection above. Classification still
         // reads only the fields it declares; this is for your callback.
         raw: req,
-      }, undefined, req.headers['x-payment-proof'] || '');
+      }, undefined, paymentHeader(req.headers));
       req.wayleave = r;
       if (r.status === 200) return next();
       if (r.status === 402) {

package/manifest.js

@@ -41,6 +41,35 @@ const KNOWN_ASSETS = {
 
 const DEFAULT_TIMEOUT_SECONDS = 60;
 
+/**
+ * One priced route, however it was configured.
+ *
+ * `pricedPaths` was `{ path: priceUsd }`, and the manifest hardcoded
+ * `method: 'GET'` and the description "x402-priced route" for every entry.
+ * For a POST API — which is most paid APIs — that published a call that
+ * cannot work, and by this module's own standard an entry an index cannot
+ * act on is "indistinguishable from not publishing at all".
+ *
+ * A value may now be the price as before, or an object carrying the method
+ * and a real description. Both consumers of a priced path go through here —
+ * the manifest and the gate's own 402 — so the document and the challenge
+ * cannot describe the route differently.
+ *
+ *   pricedPaths: { '/api/x': 0.05 }
+ *   pricedPaths: { '/api/x': { price: 0.05, method: 'POST',
+ *                              description: 'Score one transaction' } }
+ */
+export function routeSpec(value) {
+  const rich = value !== null && typeof value === 'object';
+  const price = rich ? value.price : value;
+  return {
+    price,
+    method: String((rich && value.method) || 'GET').toUpperCase(),
+    description: (rich && value.description) || 'x402-priced route',
+    mimeType: (rich && value.mimeType) || 'application/json',
+  };
+}
+
 /**
  * Build the manifest from configuration. A pure function of `pricedPaths` and
  * `payment`: there is no separate document to author, and therefore none to
@@ -68,19 +97,20 @@ export function buildManifest({ pricedPaths = {}, payment = {}, origin,
   // a wrong address is worse than a missing one.
   const priceable = Boolean(asset && payTo && Number.isInteger(decimals));
 
-  const resources = routes.map(([path, priceUsd]) => {
+  const resources = routes.map(([path, value]) => {
+    const spec = routeSpec(value);
     const url = origin.replace(/\/+$/, '') + path;
-    const entry = { url, method: 'GET', description: 'x402-priced route' };
+    const entry = { url, method: spec.method, description: spec.description };
     if (priceable) {
       entry.accepts = [{
         scheme: 'exact',
         network,
-        maxAmountRequired: toAtomicUnits(String(priceUsd), decimals),
+        maxAmountRequired: toAtomicUnits(String(spec.price), decimals),
         asset,
         payTo,
         resource: url,
-        description: 'x402-priced route',
-        mimeType: 'application/json',
+        description: spec.description,
+        mimeType: spec.mimeType,
         maxTimeoutSeconds: payment.maxTimeoutSeconds || DEFAULT_TIMEOUT_SECONDS,
       }];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.5.4",
+  "version": "0.5.7",
   "description": "Know which AI agents cross your API \u2014 verified by signature, not guessed from an IP. Sorts every request into four lanes, prices the non-human ones with HTTP 402, and never charges a human. Zero dependencies.",
   "type": "module",
   "main": "index.js",

package/x402.js

@@ -87,6 +87,19 @@ const KNOWN_ASSETS = {
   },
 };
 
+/** JSON, or base64 of JSON. Returns null when it is neither. */
+function parsePayload(raw) {
+  const text = String(raw).trim();
+  if (!text) return null;
+  try { const v = JSON.parse(text); if (v && typeof v === 'object') return v; } catch {}
+  try {
+    const decoded = Buffer.from(text, 'base64').toString('utf8');
+    const v = JSON.parse(decoded);
+    if (v && typeof v === 'object') return v;
+  } catch {}
+  return null;
+}
+
 /**
  * Build a `verifyPayment(proof, ctx)` for the Coinbase x402 facilitator.
  *
@@ -138,8 +151,21 @@ export function coinbaseFacilitator({
     // payload as JSON. Accept either so a customer does not have to care.
     let paymentPayload = proof;
     if (typeof proof === 'string') {
-      try { paymentPayload = JSON.parse(proof); }
-      catch { return deny('payment proof is not a valid x402 payload'); }
+      /* Raw JSON or base64 JSON.
+       *
+       * x402 defines the X-PAYMENT header as the base64 encoding of the
+       * payload, so that is what a spec-compliant agent sends. This accepted
+       * only raw JSON, which meant the agent cleared the header fix and then
+       * failed here with "payment proof is not a valid x402 payload" — an
+       * error that reads like the agent sent something malformed when what it
+       * sent was exactly what the protocol prescribes.
+       *
+       * Both are taken, which is the stated intent of this block anyway.
+       * JSON first: a payload is unambiguous JSON and never also valid
+       * base64 of different JSON, so trying it first cannot mis-read one as
+       * the other. */
+      paymentPayload = parsePayload(proof);
+      if (!paymentPayload) return deny('payment proof is not a valid x402 payload');
     }
     if (!paymentPayload || typeof paymentPayload !== 'object')
       return deny('no payment payload supplied');