wayleave 0.5.5 → 0.6.0

package/README.md

@@ -240,6 +240,49 @@ confirmation is yours to supply and denies by default. If you shipped 0.1.4 or e
 route, upgrade.
 
 **0.1.6** addressed the other half: payment could be faked, and so could being human.
+### Charge by lane
+
+A route can cost different amounts depending on who is asking.
+
+```js
+pricedPaths: {
+  '/api/v1/properties/search': 0.001,          // flat: every lane pays this
+
+  '/api/v1/properties/valuation-history': {    // or per lane
+    verified_agent: 0.01,                      // proved who it is
+    declared_agent: 0.05,                      // said who it is
+    suspected_bot:  0.15,                      // neither
+    method: 'GET',
+    description: 'Historical comps, tax and owner records',
+  },
+}
+```
+
+The reason to bother is not price discrimination. Signing a request under Web
+Bot Auth currently earns an operator nothing — it is pure cost, which is the
+honest explanation for how few agents do it. A lower price for a proved
+identity turns adoption into a bill that goes down, and it is the only lever
+on that an origin actually controls.
+
+Three rules, each of which exists because the alternative is worse:
+
+- **The manifest publishes the dearest lane.** A discovery document is read
+  before anyone knows who is asking, so the only safe direction for the real
+  quote to move is downward. Advertise $0.01 and bill a suspected bot $0.15
+  and you have surprised them upward; advertise $0.15 and every other lane is
+  a discount.
+- **An unlisted lane pays the list price, never free.** Set `default` to
+  choose otherwise. A lane nobody configured is a case nobody considered, and
+  giving the route away is the one outcome they certainly did not intend.
+- **The `human` lane cannot be priced.** It is a fall-through, so that is
+  where an ordinary visitor lands. A `human:` key warns at startup and is
+  unreachable in the pricing path — including under `strictPricedPaths`,
+  where an unconfirmed human *does* reach it. To charge everything that is
+  not a proven person, use `strictPricedPaths: true`, not a human price.
+
+The 402 names the lane it priced, so a caller asking why it was charged more
+than someone else has an answer.
+
 `strictPricedPaths` lets a priced route demand positive evidence rather than accepting the absence of
 a bot signal as one.
 

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.
@@ -482,6 +506,9 @@ export class Wayleave {
    *   rules: { [lane]: [ [pathPrefix, allow], ... ] },
    *   rateLimits: { [lane]: perWindow }, rateWindow: 60,
    *   pricedPaths: { pathPrefix: priceUsd },
+   *   pricedPaths: { pathPrefix: { price, method, description } },
+   *   pricedPaths: { pathPrefix: { verified_agent, declared_agent,
+   *                                suspected_bot, default } },
    *   verifyPayment: (proof, ctx) => boolean | { ok, ref },
    *   strictPricedPaths: false,
    *   confirmHuman: (req) => boolean,
@@ -548,6 +575,27 @@ export class Wayleave {
       : opts.strictPricedPaths === true;
     const priced = Object.keys(this.pricedPaths).length > 0;
     const warn = this._onWarn = opts.onWarn || console.warn;
+    /* A price on the human lane would charge people.
+     *
+     * The lane is a fall-through: a request reaches it by tripping none of
+     * the automation tells, which is how an ordinary visitor arrives. Every
+     * other guarantee here is hedged somewhere in the README; "humans are
+     * never charged" is not, and a per-lane table is the first place someone
+     * could break it by typing one extra key.
+     *
+     * Ignored rather than thrown -- an app that boots is easier to fix than
+     * one that does not -- but said once, loudly, naming the route. */
+    for (const [prefix, cfg] of Object.entries(this.pricedPaths)) {
+      if (cfg === null || typeof cfg !== 'object') continue;
+      for (const k of ['human', 'unclassified', 'unknown']) {
+        if (typeof cfg[k] === 'number')
+          warn(`[wayleave] pricedPaths["${prefix}"] sets a price for the ` +
+               `"${k}" lane. That lane is where people land, and it is not ` +
+               `charged. The price is ignored. To charge anything that is ` +
+               `not a proven person, set strictPricedPaths: true instead.`);
+      }
+    }
+
     if (opts.strictPricedPaths === false && priced)
       warn('[wayleave] strictPricedPaths is off: priced routes are reachable free ' +
            'by any client that looks like a browser. Pass confirmHuman() to charge ' +
@@ -628,7 +676,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. */
@@ -687,7 +735,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++}`,
@@ -776,9 +824,19 @@ 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)) {
-          const challenge = { scheme: 'x402', price_usd: price, resource: 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.
+
+             The lane is passed in because a route may be priced per lane.
+             Here we know who is asking, so the quote is exact; the manifest
+             has no lane and publishes the dearest, which is why the two can
+             differ without either being wrong. */
+          const { price } = routeSpec(configured, lane);
+          const challenge = { scheme: 'x402', price_usd: price, resource: prefix, lane };
           if (!paymentProof) {
             const why = this.strictPricedPaths && lane === LANES.HUMAN
               ? 'payment required: no signature and no confirmed human'
@@ -1010,7 +1068,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,94 @@ 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' } }
+ */
+/**
+ * The agent lanes a route may be priced for, dearest first.
+ *
+ * `human` is deliberately absent and cannot be priced. It is a fall-through
+ * lane -- reached by tripping none of the automation tells -- so a real
+ * person lands there, and charging it would charge people. That is the one
+ * promise this library makes without qualification.
+ */
+export const PRICED_LANES = Object.freeze(
+  ['suspected_bot', 'declared_agent', 'verified_agent']);
+
+/** Is this object a per-lane price table rather than a rich single price? */
+function isLaneTable(v) {
+  return v !== null && typeof v === 'object' &&
+         PRICED_LANES.some((l) => typeof v[l] === 'number');
+}
+
+/**
+ * One priced route, normalised.
+ *
+ * Called with a lane it answers what that lane pays. Called without one -- as
+ * the manifest does, because a document has no lane -- it answers the LIST
+ * price, which is the dearest of the configured lanes.
+ *
+ * List price is the maximum on purpose. The manifest is an advertisement read
+ * before anyone knows who is asking, so the only safe direction for the real
+ * quote to differ is downward. Publish the cheapest and a suspected bot that
+ * discovered the route at $0.01 gets billed $0.15, which is a surprise in the
+ * worst direction. Publish the dearest and every other lane is a discount.
+ *
+ * A lane with no entry falls back to `default`, and failing that to the list
+ * price. Not to free: an unlisted lane is an operator who did not think about
+ * that case, and money fails closed.
+ */
+export function routeSpec(value, lane) {
+  const rich = value !== null && typeof value === 'object';
+  const lanes = isLaneTable(value) ? value : null;
+
+  let price;
+  if (!lanes) {
+    price = rich ? value.price : value;
+  } else if (lane && PRICED_LANES.includes(lane) && typeof lanes[lane] === 'number') {
+    /* PRICED_LANES.includes() is load-bearing, not a tidy-up.
+     *
+     * Without it a `human: 0.99` key is reachable: under strictPricedPaths an
+     * unconfirmed human DOES reach the pricing loop -- that is the whole
+     * point of strict mode -- and would be quoted its own entry. The
+     * constructor warns about such a key, but a warning is advice and this is
+     * the code path that takes money. Reading the lane through the allowed
+     * list means the price cannot be quoted even if the warning is ignored. */
+    price = lanes[lane];
+  } else if (typeof lanes.default === 'number') {
+    price = lanes.default;
+  } else {
+    price = Math.max(...PRICED_LANES
+      .map((l) => lanes[l]).filter((n) => typeof n === 'number'));
+  }
+
+  return {
+    price,
+    lanes: lanes
+      ? Object.fromEntries(PRICED_LANES
+          .filter((l) => typeof lanes[l] === 'number').map((l) => [l, lanes[l]]))
+      : null,
+    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 +156,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.5",
+  "version": "0.6.0",
   "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');