wayleave 0.1.5 → 0.1.6

package/README.md

@@ -17,10 +17,12 @@ Every request gets classified into a lane:
 - **verified_agent** — valid Ed25519 signature (Web Bot Auth profile, RFC 9421) against a key directory you trust
 - **declared_agent** — identifies as a bot, no valid signature
 - **suspected_bot** — automation fingerprints without disclosure (an *invalid* signature lands here too — faking verification is the strongest fraud signal there is)
-- **human** — browser-shaped traffic
+- **human** — browser-shaped traffic, which means *nothing gave it away*, not that a person is there
 
 Then policy runs per lane: allow, deny, rate-limit — and on routes you price, agents get **402 Payment Required** with an x402-shaped challenge. Your human users never see a paywall.
 
+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.
+
 ## Quickstart
 
 ```js
@@ -51,14 +53,18 @@ app.use(gate.express());
 - Sub-millisecond per request. Your latency budget won't notice.
 - The metering hook can throw, crash, or hang your billing backend — serving continues. Your uptime never depends on ours.
 - Key directories still load from config rather than a live JWKS fetch, so key rotation is not handled. That is the next real gap.
+- **A bot that sends a browser `user-agent` and an `accept-language` header is classified `human` and crosses priced routes free.** Those two headers are the entire bypass. The `human` lane is a fall-through — it is reached by tripping none of the automation tells, which is absence of evidence, not evidence of a person. There is no TLS fingerprinting, no IP verification, and no challenge here; that work belongs at your edge or CDN, and pretending otherwise would be the dishonest version of this list. `strictPricedPaths: true` inverts the burden on priced routes so that only a verified signature or your own `confirmHuman(req)` crosses. Recommended wherever there is a price.
+- Wayleave prices **disclosure**; it does not detect **concealment**. It is a tollbooth, not a wall — it works on operators who want to be identifiable, which today is most of the ones worth billing.
 - This is a **screening and pricing layer, not a guarantee**. Every decision returns its evidence and is loggable.
 
 ## Status
 
-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.
+v0.1.6 — verification, lanes, policy, pricing, and the metering hook, all under test (55 scenarios, including forgery, tampering, replay, guessed payment proofs, spoofed rate-limit identities, spoofed browser headers, 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.
 
+0.1.6 addresses the other half of the same question. Payment could be faked; so could being human. `strictPricedPaths` lets a priced route demand positive evidence instead of accepting the absence of a bot signal as one.
+
 ## How payment actually works
 
 Pay-at-the-door, not IOUs. On a route you price:
@@ -93,6 +99,25 @@ nothing but a confirmed settlement is ever written to the ledger as billed.
 
 ## Security posture
 
+- **`strictPricedPaths: true` is the recommended setting on any priced route.**
+  Without it the free lane is whatever fails to look automated, so the cheapest
+  strategy against a paywall is to look like a browser. With it, a priced route
+  admits exactly two things: a verified signature that pays, and a request your
+  own `confirmHuman(req)` vouches for. That callback fails closed — absent,
+  throwing, or returning anything but `true` all mean pay or leave.
+
+  ```js
+  const gate = new Wayleave({
+    pricedPaths: { '/api/premium': 0.05 },
+    strictPricedPaths: true,
+    confirmHuman: req => Boolean(req.session?.userId),   // your session, not a header
+    verifyPayment: (proof, ctx) => facilitator.confirmSettled(proof, ctx),
+  });
+  ```
+
+  Never infer humanity from headers inside this callback. Every header a
+  browser sends, a bot can send too — that is the property strict mode exists
+  to close, and re-deriving it from `user-agent` reopens it.
 - **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,

package/index.d.ts

@@ -60,6 +60,12 @@ export interface WayleaveRequest {
    * `trustProxy` is on.
    */
   ip?: string;
+  /**
+   * Your framework's own request, when an adapter supplied one. Never read
+   * for classification — it exists so `confirmHuman` can reach the session and
+   * cookies that the projection into this shape leaves behind.
+   */
+  raw?: unknown;
 }
 
 export interface VerifyResult {
@@ -172,6 +178,29 @@ export interface WayleaveOptions {
    * against the challenge you just issued.
    */
   verifyPayment?: PaymentVerifier;
+  /**
+   * Price priced routes for everything except an application-confirmed human.
+   * Default false.
+   *
+   * Off, the `human` lane crosses priced routes free — and that lane is a
+   * fall-through meaning "no automation tell was found", so a bot sending a
+   * browser `user-agent` and an `accept-language` header reaches it. On,
+   * absence of evidence stops being a free pass: only a verified signature
+   * (which pays) or `confirmHuman` returning true (which browses) crosses.
+   * Recommended wherever a route has a price on it.
+   */
+  strictPricedPaths?: boolean;
+  /**
+   * Positive proof a person is present — your session, your cookie, your
+   * challenge. Only consulted under `strictPricedPaths`. Fails closed: absent,
+   * throwing, or non-`true` all mean "pay or leave" on a priced route.
+   *
+   * Receives your framework's request under an adapter (the Express `req`,
+   * session and cookies intact), otherwise whatever you passed to `handle`.
+   * Do not infer humanity from headers here — a bot sends those too, which is
+   * the whole reason this callback exists.
+   */
+  confirmHuman?: (req: any) => boolean;
   /**
    * Believe `x-forwarded-for` for the client address. Default false. Turn on
    * ONLY behind a proxy you control that overwrites the header — otherwise

package/index.js

@@ -242,6 +242,8 @@ export class Wayleave {
    *   rateLimits: { [lane]: perWindow }, rateWindow: 60,
    *   pricedPaths: { pathPrefix: priceUsd },
    *   verifyPayment: (proof, ctx) => boolean | { ok, ref },
+   *   strictPricedPaths: false,
+   *   confirmHuman: (req) => boolean,
    *   trustProxy: false,
    *   replayProtection: true,
    *   maxTracked: 10000,
@@ -262,6 +264,15 @@ export class Wayleave {
     // is something the payer could equally have made up.
     this.verifyPayment = opts.verifyPayment || null;
 
+    // The human lane is a fall-through: it means no automation tell was found,
+    // not that a person is present. Since humans are never priced, that
+    // asymmetry pays the spoofer — a browser User-Agent plus an
+    // accept-language header is the whole bypass. Strict mode inverts the
+    // burden on priced routes only: nothing crosses free without positive
+    // evidence, which is a verified signature or confirmHuman saying yes.
+    this.strictPricedPaths = opts.strictPricedPaths === true;
+    this.confirmHuman = opts.confirmHuman || 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.
@@ -302,6 +313,22 @@ export class Wayleave {
     return req.ip || 'unknown';
   }
 
+  /**
+   * Positive evidence that a person is present, which only your application
+   * holds — a signed-in session, a cookie you set, a challenge you passed.
+   * Consulted only under strictPricedPaths, and fails closed: no callback, a
+   * throw, or anything other than true means no free crossing of a priced
+   * route. Deliberately not inferred from headers; every header a browser
+   * sends, a bot can send too.
+   */
+  _confirmedHuman(req) {
+    if (!this.confirmHuman) return false;
+    // Hand back the framework's own request when an adapter supplied one, so
+    // req.session and req.cookies are there to be checked.
+    try { return this.confirmHuman(req.raw || req) === true; }
+    catch { return false; }
+  }
+
   /**
    * Fixed-window counting. On rollover the whole table is dropped — last
    * window's counts are meaningless anyway, and it keeps memory bounded to
@@ -347,12 +374,23 @@ export class Wayleave {
       const n = this._bump(ident, now);
       if (n > limit) return { status: 429, why: `${n} req in window, limit ${limit}` };
     }
-    if (lane !== LANES.HUMAN) {
+    // Who crosses a priced route without paying. Normally the human lane —
+    // which anything browser-shaped reaches. Under strictPricedPaths only an
+    // application-confirmed human does, so an unsigned request that merely
+    // looks like a browser is asked to pay like the automation it may be.
+    const freeOnPriced = this.strictPricedPaths
+      ? this._confirmedHuman(req)
+      : lane === LANES.HUMAN;
+    if (!freeOnPriced) {
       for (const [prefix, price] of Object.entries(this.pricedPaths)) {
         if (req.path.startsWith(prefix)) {
           const challenge = { scheme: 'x402', price_usd: price, resource: prefix };
-          if (!paymentProof)
-            return { status: 402, why: 'payment required for agent access', challenge };
+          if (!paymentProof) {
+            const why = this.strictPricedPaths && lane === LANES.HUMAN
+              ? 'payment required: no signature and no confirmed human'
+              : 'payment required for agent access';
+            return { status: 402, why, challenge };
+          }
           const v = this._checkPayment(paymentProof, {
             price, resource: prefix, identity: ident, path: req.path, now });
           if (v.ok)
@@ -393,6 +431,10 @@ export class Wayleave {
         // 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,
+        // confirmHuman needs the session and cookies your framework parsed,
+        // 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'] || '');
       req.wayleave = r;
       if (r.status === 200) return next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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",