wayleave 0.1.4 → 0.1.5

package/README.md

@@ -36,6 +36,8 @@ const gate = new Wayleave({
   },
   rateLimits: { declared_agent: 10 },
   pricedPaths: { '/api/premium': 0.05 },   // agents pay 5¢/call, humans free
+  verifyPayment: (proof, { price, resource }) =>
+    facilitator.confirmSettled(proof, price, resource),  // REQUIRED to sell
   onEvent: e => queueForBilling(e),        // metering hook; never blocks serving
 });
 
@@ -53,7 +55,59 @@ app.use(gate.express());
 
 ## Status
 
-v0.1 — verification, lanes, policy, pricing, and the metering hook, all under test (29 scenarios, including forgery, tampering, replay, and cross-implementation wire formats). Payment settlement network integration is in progress; today the 402 challenge and payment-proof check are pluggable.
+v0.1.5 — verification, lanes, policy, pricing, and the metering hook, all under test (44 scenarios, including forgery, tampering, replay, guessed payment proofs, spoofed rate-limit identities, and cross-implementation wire formats). Payment settlement network integration is in progress; the 402 challenge is built in and settlement confirmation is a function you supply.
+
+0.1.5 closes a hole worth naming: before it, a priced route accepted a payment proof that any agent could derive from the 402 challenge it had just been sent — free passage, recorded as revenue. Settlement confirmation is now yours to supply and denies by default. If you shipped 0.1.4 or earlier on a priced route, upgrade.
+
+## How payment actually works
+
+Pay-at-the-door, not IOUs. On a route you price:
+
+1. An agent requests the route → Wayleave answers `402 Payment Required`
+   with an x402-shaped challenge: the price and *your* receiving address.
+2. A wallet-carrying agent signs payment and retries with proof attached.
+3. The proof is verified and settlement executes on a licensed rail
+   (x402 facilitator) — money moves to your account.
+4. Only then: `200`. No settled payment, no passage. Data never moves
+   on a promise.
+
+Agents without wallets (most crawlers today) are simply turned away on
+priced routes — you aren't paid by them, but you also never serve them
+free. The ledger shows exactly how much turned-away demand is standing
+at your gate.
+
+Wayleave never holds funds. Agent money flows agent → facilitator → you.
+The hosted meter (not built yet — see the waitlist) is what wires this
+end-to-end; today the 402 challenge is built in and step 3 is a function
+you supply.
+
+**Step 3 is yours, and it defaults to no.** `verifyPayment(proof, ctx)` is
+the only thing that can turn a 402 into a 200. Configure nothing and every
+priced route stays 402 forever — deliberately. A payment proof is a string
+written by the party who owes you money, so there is nothing this library
+can check about it on its own that the payer could not have fabricated.
+Point it at a facilitator that confirms settlement, and never at a
+comparison against the challenge you just issued. A verifier that returns
+anything but `true`/`{ok:true}` — or that throws — denies passage, and
+nothing but a confirmed settlement is ever written to the ledger as billed.
+
+## Security posture
+
+- **Rate limits key on the connection address, not `x-forwarded-for`.**
+  The header is client-written unless a proxy you own overwrites it; believing
+  it by default hands an attacker unlimited fresh buckets. Behind a real proxy,
+  set `trustProxy: true`. Pass `req.ip` (the Express adapter does).
+- **In-memory state is bounded** by `maxTracked` (default 10,000) and cleared
+  each rate window, so a flood of distinct clients cannot exhaust memory.
+- **Replay: single-use is enforced only for signers that send RFC 9421's
+  `nonce`.** Signature bytes are not a usable substitute — Ed25519 is
+  deterministic and the Web Bot Auth profile covers only `@authority`, so one
+  agent hitting two paths in the same second produces byte-identical
+  signatures. Rejecting those would break real traffic. Without a signer
+  nonce, replay is bounded by the expiry window and nothing tighter.
+- **State is per-process.** Rate limits and replay memory do not survive a
+  restart and do not span instances — two instances mean two independent
+  limiters. Shared state is the next real gap, alongside key rotation.
 
 ## License
 

package/index.d.ts

@@ -53,6 +53,13 @@ export interface WayleaveRequest {
   /** Host authority the signature was computed over, e.g. "example.com". */
   authority: string;
   headers: Record<string, string | string[] | undefined>;
+  /**
+   * The connection's source address, e.g. `req.socket.remoteAddress`. Used to
+   * key rate limits for unsigned traffic. Supply it: without it every
+   * anonymous client shares one bucket. Never taken from a header unless
+   * `trustProxy` is on.
+   */
+  ip?: string;
 }
 
 export interface VerifyResult {
@@ -61,6 +68,15 @@ export interface VerifyResult {
   agentId: string | null;
   /** Human-readable reason, safe to log. */
   reason: string;
+  /**
+   * Single-use token, set only when the signer supplied RFC 9421's `nonce`
+   * parameter. Null otherwise — a signature hash is NOT a safe substitute,
+   * because deterministic Ed25519 over `@authority` alone makes two
+   * legitimate same-second requests byte-identical.
+   */
+  nonce?: string | null;
+  /** Unix seconds the signature stops being valid. */
+  expires?: number;
 }
 
 export interface Classification {
@@ -68,8 +84,34 @@ export interface Classification {
   agentId: string | null;
   /** Why this lane was chosen. Loggable. */
   evidence: string[];
+  /** Present only for verified agents whose signer sent a nonce. */
+  nonce?: string | null;
+  sigExpires?: number;
+}
+
+/** What `verifyPayment` is told about the crossing it is confirming. */
+export interface PaymentContext {
+  /** Price in USD for the matched resource. */
+  price: number;
+  /** The priced path prefix that matched. */
+  resource: string;
+  /** Cryptographic agent identity when verified, else lane:address. */
+  identity: string;
+  path: string;
+  /** Unix seconds. */
+  now: number;
 }
 
+/**
+ * Your answer to "did this actually settle?". Return `true`, or an object
+ * carrying the settlement reference so it reaches the ledger. Anything else
+ * — including a throw — denies passage.
+ */
+export type PaymentVerifier = (
+  proof: string,
+  ctx: PaymentContext
+) => boolean | { ok: boolean; ref?: string; reason?: string };
+
 /** x402-shaped payment challenge returned with a 402. */
 export interface PaymentChallenge {
   scheme: 'x402';
@@ -88,8 +130,10 @@ export interface Decision {
   evidence: string[];
   /** Present only on 402. */
   challenge?: PaymentChallenge;
-  /** Present only when a priced request was paid. */
+  /** Present only when `verifyPayment` confirmed settlement. */
   billed?: number;
+  /** Settlement reference returned by your verifier, if any. */
+  paymentRef?: string | null;
 }
 
 /** What the metering hook receives. It may throw; serving continues. */
@@ -102,7 +146,10 @@ export interface MeterEvent {
   status: number;
   why: string;
   evidence: string[];
+  /** Zero unless settlement was confirmed. Never records an unpaid crossing. */
   billedUsd: number;
+  /** Settlement reference from your verifier, when it supplied one. */
+  paymentRef?: string;
 }
 
 /** `[pathPrefix, allow]` — first matching prefix wins. */
@@ -118,6 +165,29 @@ export interface WayleaveOptions {
   rateWindow?: number;
   /** Path prefix -> price in USD. Non-human lanes get 402 here. */
   pricedPaths?: Record<string, number>;
+  /**
+   * Confirms a payment actually settled. **Without this, every priced route
+   * stays 402 forever** — deny is the only safe default, since the proof is a
+   * string the payer wrote. Wire it to your facilitator, not to a comparison
+   * against the challenge you just issued.
+   */
+  verifyPayment?: PaymentVerifier;
+  /**
+   * Believe `x-forwarded-for` for the client address. Default false. Turn on
+   * ONLY behind a proxy you control that overwrites the header — otherwise
+   * clients mint themselves unlimited rate-limit buckets.
+   */
+  trustProxy?: boolean;
+  /**
+   * Reject a second use of a signature whose signer supplied a nonce.
+   * Default true. In-process only: it does not span instances or restarts.
+   */
+  replayProtection?: boolean;
+  /**
+   * Ceiling on in-memory identities and nonces. Default 10000. Bounds memory
+   * under a flood of distinct clients; oldest entries are evicted.
+   */
+  maxTracked?: number;
   /**
    * Metering hook, called once per request. Exceptions are swallowed —
    * billing must never break serving.

package/index.js

@@ -17,7 +17,8 @@
  * Zero dependencies. Node's native crypto only.
  */
 
-import { createPublicKey, verify as edVerify, sign as edSign } from 'node:crypto';
+import { createPublicKey, verify as edVerify, sign as edSign,
+         createHash } from 'node:crypto';
 
 export const LANES = Object.freeze({
   VERIFIED: 'verified_agent',
@@ -109,7 +110,15 @@ export function signRequest(headers, authority, privateKey, keyid, directoryUrl,
 
 /**
  * directories: { [directoryUrl]: { [keyid]: publicKey (KeyObject|PEM|raw b64) } }
- * Returns { ok, agentId, reason }
+ * Returns { ok, agentId, reason, nonce, expires }
+ *
+ * `nonce` is set only when the signer supplied RFC 9421's `nonce` parameter,
+ * and it is what makes a signature single-use. Do NOT substitute a hash of
+ * the signature itself: Ed25519 is deterministic and the Web Bot Auth profile
+ * covers only `@authority`, so one agent hitting two different paths in the
+ * same second legitimately produces the SAME signature bytes. Treating that
+ * as a replay would reject real traffic. Without a signer-supplied nonce,
+ * replay is bounded by the expiry window and nothing tighter — see README.
  */
 export function verifySignature(h, authority, directories,
                                 now = Math.floor(Date.now() / 1000)) {
@@ -173,7 +182,12 @@ export function verifySignature(h, authority, directories,
   if (!valid)
     return { ok: false, agentId: null,
              reason: 'signature verification FAILED (forged or tampered)' };
-  return { ok: true, agentId: `${directory}#${keyid}`, reason: 'valid signature' };
+  return { ok: true, agentId: `${directory}#${keyid}`, reason: 'valid signature',
+           nonce: params.nonce
+             ? createHash('sha256')
+                 .update(`${directory}#${keyid}#${params.nonce}`).digest('base64')
+             : null,
+           expires };
 }
 
 // ── classification ──────────────────────────────────────────────────────
@@ -199,7 +213,8 @@ export function classify(req, directories, now) {
   const h = req.headers, ua = (h['user-agent'] || '').toLowerCase();
   const v = verifySignature(h, req.authority, directories, now);
   if (v.ok) return { lane: LANES.VERIFIED, agentId: v.agentId,
-                     evidence: [`crypto: ${v.reason}`] };
+                     evidence: [`crypto: ${v.reason}`],
+                     nonce: v.nonce, sigExpires: v.expires };
   if (h['signature'] || h['signature-input'])
     return { lane: LANES.SUSPECT, agentId: null,
              evidence: [`crypto: ${v.reason}`, 'presented invalid signature'] };
@@ -226,6 +241,10 @@ export class Wayleave {
    *   rules: { [lane]: [ [pathPrefix, allow], ... ] },
    *   rateLimits: { [lane]: perWindow }, rateWindow: 60,
    *   pricedPaths: { pathPrefix: priceUsd },
+   *   verifyPayment: (proof, ctx) => boolean | { ok, ref },
+   *   trustProxy: false,
+   *   replayProtection: true,
+   *   maxTracked: 10000,
    *   onEvent: (logEntry) => {}   // metering/billing hook, async-safe
    * }
    */
@@ -236,43 +255,110 @@ export class Wayleave {
     this.rateWindow = opts.rateWindow || 60;
     this.pricedPaths = opts.pricedPaths || {};
     this.onEvent = opts.onEvent || (() => {});
-    this._hits = new Map();
+
+    // No payment verifier configured means no agent can ever buy passage.
+    // Deny is the only safe default: a proof is a string the PAYER wrote, and
+    // anything this library could check about it without a settlement network
+    // is something the payer could equally have made up.
+    this.verifyPayment = opts.verifyPayment || null;
+
+    // x-forwarded-for is written by the client unless a proxy you control
+    // overwrites it. Trusting it by default hands every attacker an unlimited
+    // supply of fresh rate-limit buckets. Opt in only behind a real proxy.
+    this.trustProxy = opts.trustProxy === true;
+
+    this.replayProtection = opts.replayProtection !== false;
+    this.maxTracked = opts.maxTracked || 10000;
+
+    this._hits = new Map();     // identity -> count, cleared each window
+    this._window = -1;
+    this._seen = new Map();     // signature nonce -> expiry, pruned on rollover
   }
 
-  /** req: { method, path, authority, headers } → decision */
+  /** req: { method, path, authority, headers, ip } → decision */
   handle(req, now = Math.floor(Date.now() / 1000), paymentProof = '') {
-    const { lane, agentId, evidence } = classify(req, this.directories, now);
-    const ident = agentId ||
-      `${lane}:${req.headers['x-forwarded-for'] || 'unknown'}`;
-    const d = this._decide(req, lane, ident, now, paymentProof);
+    const c = classify(req, this.directories, now);
+    const { lane, agentId, evidence } = c;
+    const ident = agentId || `${lane}:${this._client(req)}`;
+    const proof = paymentProof || headerValue(req.headers, 'x-payment-proof');
+    const d = this._decide(req, lane, ident, now, proof, c);
     const entry = { t: now, path: req.path, lane, identity: ident,
                     status: d.status, why: d.why, evidence,
                     billedUsd: d.billed || 0 };
+    if (d.paymentRef) entry.paymentRef = d.paymentRef;
     try { this.onEvent(entry); } catch { /* metering must never break serving */ }
     return { lane, identity: ident, ...d, evidence };
   }
 
-  _decide(req, lane, ident, now, paymentProof) {
+  /**
+   * Who to rate-limit. A cryptographic identity is authoritative; a network
+   * address is at least expensive to rotate. A header is neither.
+   */
+  _client(req) {
+    if (this.trustProxy) {
+      const xff = headerValue(req.headers, 'x-forwarded-for');
+      if (xff) return xff.split(',')[0].trim();
+    }
+    return req.ip || 'unknown';
+  }
+
+  /**
+   * Fixed-window counting. On rollover the whole table is dropped — last
+   * window's counts are meaningless anyway, and it keeps memory bounded to
+   * one window's worth of identities instead of growing forever.
+   */
+  _bump(ident, now) {
+    const w = Math.floor(now / this.rateWindow);
+    if (w !== this._window) {
+      this._window = w;
+      this._hits.clear();
+      for (const [n, exp] of this._seen) if (exp <= now) this._seen.delete(n);
+    }
+    // Hard ceiling so a flood of distinct identities inside a single window
+    // cannot exhaust memory. Evicting the oldest keeps the newest arrivals
+    // counted; the durable fix is shared state, not a bigger Map.
+    if (this._hits.size >= this.maxTracked && !this._hits.has(ident))
+      this._hits.delete(this._hits.keys().next().value);
+    const n = (this._hits.get(ident) || 0) + 1;
+    this._hits.set(ident, n);
+    return n;
+  }
+
+  _decide(req, lane, ident, now, paymentProof, c) {
     for (const [prefix, allow] of this.rules[lane] || []) {
       if (req.path.startsWith(prefix)) {
         if (!allow) return { status: 403, why: `${lane} denied on ${prefix}` };
         break;
       }
     }
+    // A valid signature replayed is still a replay. Checked before rate
+    // limiting so a captured request cannot be farmed into N billed crossings.
+    // Only signers that send a nonce can be held to single use; see
+    // verifySignature for why a signature hash is not a safe substitute.
+    if (this.replayProtection && c && c.nonce) {
+      if (this._seen.has(c.nonce))
+        return { status: 403, why: 'signature already used (replay)' };
+      if (this._seen.size >= this.maxTracked)
+        this._seen.delete(this._seen.keys().next().value);
+      this._seen.set(c.nonce, c.sigExpires || now + this.rateWindow);
+    }
     const limit = this.rateLimits[lane];
     if (limit) {
-      const k = `${ident}|${Math.floor(now / this.rateWindow)}`;
-      const n = (this._hits.get(k) || 0) + 1;
-      this._hits.set(k, n);
+      const n = this._bump(ident, now);
       if (n > limit) return { status: 429, why: `${n} req in window, limit ${limit}` };
     }
     if (lane !== LANES.HUMAN) {
       for (const [prefix, price] of Object.entries(this.pricedPaths)) {
         if (req.path.startsWith(prefix)) {
-          if (paymentProof === `paid:${prefix}:${price}`)
-            return { status: 200, billed: price, why: `paid access $${price}` };
-          return { status: 402, why: 'payment required for agent access',
-                   challenge: { scheme: 'x402', price_usd: price, resource: prefix } };
+          const challenge = { scheme: 'x402', price_usd: price, resource: prefix };
+          if (!paymentProof)
+            return { status: 402, why: 'payment required for agent access', challenge };
+          const v = this._checkPayment(paymentProof, {
+            price, resource: prefix, identity: ident, path: req.path, now });
+          if (v.ok)
+            return { status: 200, billed: price, paymentRef: v.ref,
+                     why: `settled $${price}` };
+          return { status: 402, why: `payment proof rejected: ${v.reason}`, challenge };
         }
       }
     }
@@ -281,6 +367,22 @@ export class Wayleave {
     return { status: 200, why: `${lane} allowed` };
   }
 
+  /**
+   * Settlement is somebody else's job — a facilitator that actually moved the
+   * money. This asks yours and believes nothing else. A verifier that throws
+   * is a verifier that did not say yes, so the answer is no.
+   */
+  _checkPayment(proof, ctx) {
+    if (!this.verifyPayment)
+      return { ok: false, reason: 'no verifyPayment configured' };
+    let r;
+    try { r = this.verifyPayment(proof, ctx); }
+    catch (e) { return { ok: false, reason: `verifier threw: ${e.message}` }; }
+    if (r === true) return { ok: true, ref: null };
+    if (r && r.ok === true) return { ok: true, ref: r.ref || null };
+    return { ok: false, reason: (r && r.reason) || 'not settled' };
+  }
+
   /** Express/Connect adapter: app.use(wayleave.express()) */
   express() {
     return (req, res, next) => {
@@ -288,6 +390,9 @@ export class Wayleave {
         method: req.method, path: req.path || req.url,
         authority: req.headers.host || '',
         headers: req.headers,
+        // The socket address, not a header. Express only populates req.ip
+        // from x-forwarded-for when ITS trust proxy setting says to.
+        ip: req.socket?.remoteAddress || req.connection?.remoteAddress,
       }, undefined, req.headers['x-payment-proof'] || '');
       req.wayleave = r;
       if (r.status === 200) return next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Charge AI agents for passage across your app. Verify agent signatures (Web Bot Auth / Ed25519), classify every request, and return 402 with a price on routes you choose. Humans browse free.",
   "type": "module",
   "main": "index.js",