wayleave 0.1.5 → 0.2.0

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
@@ -50,15 +52,21 @@ app.use(gate.express());
 - Signature parameters are parsed as an RFC 9421 dictionary: order-independent, `alg` enforced as Ed25519, any signature label, and the signature base is built from whatever components the signer declared. Requests signed in Cloudflare's documented format verify.
 - 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.
+- Key rotation has a seam but no implementation. `directories` accepts a resolver function you can point at a cache, but there is no JWKS fetcher in the box and the resolver must not block. Wiring that cache is still your job.
+- **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 and no challenge here; that work belongs at your edge or CDN, and pretending otherwise would be the dishonest version of this list. (`verifyAgentIP` checks a *declared* operator against its published ranges — it does nothing about a request claiming to be a browser, which is this bypass.) `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.2.0 — verification, lanes, policy, pricing, and the metering hook, all under test (70 scenarios, including forgery, tampering, replay, guessed payment proofs, spoofed rate-limit identities, spoofed browser headers, spoofed operator identity, 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.
+
+0.2.0 turns three hardcoded strategies into seams — state, metering, and key lookup — so shared storage, durable billing, and key rotation become configuration rather than a rewrite. Defaults are unchanged; see [Extending it](#extending-it).
+
 ## How payment actually works
 
 Pay-at-the-door, not IOUs. On a route you price:
@@ -93,6 +101,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,
@@ -105,9 +132,40 @@ nothing but a confirmed settlement is ever written to the ledger as billed.
   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.
+- **State is per-process by default.** Rate limits and replay memory do not
+  survive a restart and do not span instances. Pass a `store` implementing
+  `hit` / `hasNonce` / `rememberNonce` to share them. Keep it synchronous —
+  it runs on every request — so back a distributed store with a local view
+  that replicates asynchronously. Note the two uses differ in how much they
+  mind lag: fixed-window rate limiting tolerates approximate counts, replay
+  does not, because a nonce that has not replicated yet can be spent twice.
+- **Key rotation is possible but not built in.** `directories` accepts a
+  resolver function, so point it at a cache you refresh from a JWKS endpoint
+  on a timer. There is no fetcher in the box, and the resolver must not block.
+
+## Extending it
+
+Three seams, each defaulting to the behaviour above. Nothing here is required.
+
+```js
+new Wayleave({
+  store: myRedisBackedStore,        // shared rate limits + replay across instances
+  sink: myBufferedSink,             // emit() with batching, retry, dedup
+  directories: url => keyCache[url],// rotatable keys, refreshed out of band
+  verifyAgentIP: (ip, ua) => isPublishedRange(ip, ua),
+});
+```
+
+Every metering event carries `v` (schema version) and `idempotencyKey`, so a
+sink that retries can be deduplicated at the far end rather than double-billing.
+
+`verifyAgentIP` is the one that changes a lane. A `user-agent` naming a known
+operator is a claim; when that operator publishes its ranges the claim is
+checkable. Returning `false` moves the request to `suspected_bot` — a false
+claim of identity is a stronger signal than no claim, which is the same
+reasoning that puts an invalid signature there. Return `null` for operators you
+cannot check; that leaves the request `declared_agent`, because unknown is not
+guilty. Throwing is treated as `null` for the same reason.
 
 ## License
 

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 {
@@ -138,6 +144,17 @@ export interface Decision {
 
 /** What the metering hook receives. It may throw; serving continues. */
 export interface MeterEvent {
+  /**
+   * Event schema version. Present so a meter that outlives one release can
+   * tell which shape it is reading. Currently always 1.
+   */
+  v: number;
+  /**
+   * Unique per crossing and stable across retries of the same event, so a
+   * sink that resends after a failure can be deduplicated at the far end.
+   * Namespaced per process — two instances never collide.
+   */
+  idempotencyKey: string;
   /** Unix seconds. */
   t: number;
   path: string;
@@ -155,8 +172,90 @@ export interface MeterEvent {
 /** `[pathPrefix, allow]` — first matching prefix wins. */
 export type PolicyRule = [prefix: string, allow: boolean];
 
+/**
+ * Rate-limit counters and consumed nonces. Implement this against Redis or
+ * Postgres and pass it as `store` to share state across instances.
+ *
+ * Must be synchronous — it is called on every request, and an awaited round
+ * trip per crossing costs more than the crossing earns. Put a distributed
+ * backend behind a local view that replicates asynchronously.
+ *
+ * Note the two uses differ in how much they mind approximation: fixed-window
+ * rate limiting tolerates it, replay does not. A nonce that has not yet
+ * replicated is a nonce that can be spent twice.
+ */
+export interface Store {
+  /** Requests by this identity in the current window. Returns the new count. */
+  hit(identity: string, windowSeconds: number, now: number): number;
+  hasNonce(nonce: string): boolean;
+  rememberNonce(nonce: string, expiresAt: number): void;
+}
+
+/** The default `Store`: bounded, in this process's memory, lost on restart. */
+export class MemoryStore implements Store {
+  constructor(opts?: { maxTracked?: number });
+  maxTracked: number;
+  hit(identity: string, windowSeconds: number, now: number): number;
+  hasNonce(nonce: string): boolean;
+  rememberNonce(nonce: string, expiresAt: number): void;
+}
+
+/**
+ * Where metering events go. Implement `emit` to buffer, batch, retry, and
+ * dedup on `idempotencyKey`. It must never throw into the request path.
+ */
+export interface Sink {
+  emit(event: MeterEvent): void;
+}
+
+/** The default `Sink`: calls `onEvent` and swallows whatever it throws. */
+export class DirectSink implements Sink {
+  constructor(onEvent?: (event: MeterEvent) => void);
+  emit(event: MeterEvent): void;
+}
+
+/**
+ * Key lookup. The function form is what makes rotation possible: point it at
+ * a cache your app refreshes from a JWKS endpoint on a timer. Synchronous by
+ * design — do not fetch here.
+ */
+export type KeyResolver = (directoryUrl: string) =>
+  Record<string, PublicKeyLike> | undefined;
+
+/**
+ * Checks whether a request claiming to be a known operator actually came from
+ * that operator's published addresses.
+ *
+ * Return `true` to confirm, `false` to accuse — a false claim is a stronger
+ * fraud signal than silence, so it lands in `suspected_bot` alongside an
+ * invalid signature. Return `null`/`undefined` for "cannot check", which
+ * leaves the request merely `declared_agent`: unknown is not guilty. A throw
+ * is treated as "cannot check" too, so a DNS blip never demotes real agents.
+ */
+export type AgentIPVerifier = (
+  ip: string | undefined,
+  userAgent: string
+) => boolean | null | undefined;
+
 export interface WayleaveOptions {
-  directories?: KeyDirectories;
+  /** Config object, or a resolver function for rotatable keys. */
+  directories?: KeyDirectories | KeyResolver;
+  /**
+   * Verify that a self-declared operator is on its published addresses.
+   * Without it, `declared_agent` is a claim taken at face value.
+   */
+  verifyAgentIP?: AgentIPVerifier;
+  /**
+   * Rate-limit and replay state. Defaults to a bounded `MemoryStore`, which
+   * is per-process: two instances mean two independent limiters. Supply a
+   * shared implementation to fix that without touching anything else.
+   */
+  store?: Store;
+  /**
+   * Where metering events go. Defaults to a `DirectSink` wrapping `onEvent`.
+   * Replace it with a buffering, retrying sink when losing events costs money.
+   */
+  sink?: Sink;
   /** Per-lane allow/deny rules, evaluated in order. */
   rules?: Partial<Record<Lane, PolicyRule[]>>;
   /** Max requests per identity per window, per lane. */
@@ -172,6 +271,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
@@ -220,7 +342,7 @@ export function signRequest(
 export function verifySignature(
   headers: Record<string, string | string[] | undefined>,
   authority: string,
-  directories: KeyDirectories,
+  directories: KeyDirectories | KeyResolver,
   now?: number
 ): VerifyResult;
 
@@ -230,8 +352,14 @@ export function verifySignature(
  */
 export function classify(
   req: WayleaveRequest,
-  directories: KeyDirectories,
-  now?: number
+  directories: KeyDirectories | KeyResolver,
+  now?: number,
+  opts?: {
+    /** Confirms a declared operator is on its published addresses. */
+    verifyAgentIP?: AgentIPVerifier;
+    /** Source address handed to `verifyAgentIP`. */
+    ip?: string;
+  }
 ): Classification;
 
 export class Wayleave {

package/index.js

@@ -18,7 +18,7 @@
  */
 
 import { createPublicKey, verify as edVerify, sign as edSign,
-         createHash } from 'node:crypto';
+         createHash, randomUUID } from 'node:crypto';
 
 export const LANES = Object.freeze({
   VERIFIED: 'verified_agent',
@@ -108,8 +108,28 @@ export function signRequest(headers, authority, privateKey, keyid, directoryUrl,
   return headers;
 }
 
+/**
+ * Key lookup, as a seam rather than an object read.
+ *
+ * `directories` may be the config object it has always been, or a function
+ * `(directoryUrl) => { keyid: key }`. The function form is what makes rotation
+ * possible without touching this file: point it at a cache your app refreshes
+ * from a JWKS endpoint on a timer.
+ *
+ * It MUST be synchronous. This runs on every signed request, and awaiting a
+ * network fetch per crossing would cost far more than the crossing earns —
+ * the sub-millisecond claim in the README is a real constraint, not a boast.
+ * Fetch on a schedule, resolve from memory.
+ */
+function asResolver(directories) {
+  if (typeof directories === 'function') return directories;
+  const d = directories || {};
+  return (directoryUrl) => d[directoryUrl];
+}
+
 /**
  * directories: { [directoryUrl]: { [keyid]: publicKey (KeyObject|PEM|raw b64) } }
+ *              or (directoryUrl) => { [keyid]: publicKey }
  * Returns { ok, agentId, reason, nonce, expires }
  *
  * `nonce` is set only when the signer supplied RFC 9421's `nonce` parameter,
@@ -157,7 +177,7 @@ export function verifySignature(h, authority, directories,
   if (expires - created > 3600)
     return { ok: false, agentId: null, reason: 'validity window too long (replay risk)' };
 
-  const dir = directories[directory];
+  const dir = asResolver(directories)(directory);
   if (!dir) return { ok: false, agentId: null, reason: `unknown key directory ${directory}` };
   let key = dir[keyid];
   if (!key) return { ok: false, agentId: null, reason: `keyid "${keyid}" not in directory` };
@@ -209,7 +229,20 @@ const AUTOMATION_TELLS = [
   ['wget', 'wget UA'],
 ];
 
-export function classify(req, directories, now) {
+/**
+ * A verifier that throws must not decide the lane. Treat the failure as
+ * "could not check" rather than "is a forger" — a DNS timeout is not evidence
+ * of fraud, and demoting real agents to the fraud lane because a lookup blipped
+ * would be a self-inflicted outage on the traffic we most want to bill.
+ */
+function tryVerifyIP(verify, ip, ua) {
+  try {
+    const r = verify(ip, ua);
+    return r === true ? true : r === false ? false : null;
+  } catch { return null; }
+}
+
+export function classify(req, directories, now, opts = {}) {
   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,
@@ -218,10 +251,25 @@ export function classify(req, directories, now) {
   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)))
+  if (AGENT_UA.some(p => p.test(ua))) {
+    // 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
+    // nothing at all — so it lands in the fraud lane, exactly like a
+    // signature that fails to verify. An unrecognised operator returns
+    // null/undefined and stays merely declared: unknown is not guilty.
+    const ipOk = opts.verifyAgentIP
+      ? tryVerifyIP(opts.verifyAgentIP, opts.ip, ua)
+      : null;
+    if (ipOk === false)
+      return { lane: LANES.SUSPECT, agentId: null,
+               evidence: [`UA claims "${ua.slice(0, 40)}"`,
+                          `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)}"`,
-                        'no signature presented'] };
+                        ipOk === true ? 'source address matches published range'
+                                      : 'no signature presented'] };
+  }
   for (const [tell, why] of AUTOMATION_TELLS)
     if (ua.includes(tell))
       return { lane: LANES.SUSPECT, agentId: null, evidence: [why] };
@@ -232,6 +280,77 @@ export function classify(req, directories, now) {
   return { lane: LANES.HUMAN, agentId: null, evidence: ['browser-shaped request'] };
 }
 
+// ── state ───────────────────────────────────────────────────────────────
+
+/**
+ * Rate-limit counters and consumed nonces, in this process's memory.
+ *
+ * This is the seam that a shared backend replaces. Implement the same four
+ * methods against Redis or Postgres and pass it as `store` — the gate does not
+ * know the difference. Two properties any replacement must preserve:
+ *
+ *   Synchronous. Called on every request. An awaited round trip per crossing
+ *   is a worse tax than the crossing is worth; a distributed store belongs
+ *   behind a local view that replicates asynchronously.
+ *
+ *   Bounded. `maxTracked` exists because an attacker who can mint identities
+ *   can otherwise mint memory. Evicting the oldest keeps recent arrivals
+ *   counted, which is the useful half.
+ *
+ * A distributed store trades exactness for reach, and the two uses differ in
+ * how much they mind. Fixed-window rate limiting tolerates approximate counts.
+ * Replay does NOT: a nonce that has not replicated yet is a nonce that can be
+ * spent twice. Say which you chose in your deployment notes.
+ */
+export class MemoryStore {
+  constructor({ maxTracked = 10000 } = {}) {
+    this.maxTracked = maxTracked;
+    this._hits = new Map();
+    this._window = -1;
+    this._seen = new Map();
+  }
+
+  /** Count this identity's requests in the current fixed window. */
+  hit(identity, windowSeconds, now) {
+    const w = Math.floor(now / windowSeconds);
+    if (w !== this._window) {
+      this._window = w;
+      this._hits.clear();
+      for (const [n, exp] of this._seen) if (exp <= now) this._seen.delete(n);
+    }
+    if (this._hits.size >= this.maxTracked && !this._hits.has(identity))
+      this._hits.delete(this._hits.keys().next().value);
+    const n = (this._hits.get(identity) || 0) + 1;
+    this._hits.set(identity, n);
+    return n;
+  }
+
+  hasNonce(nonce) { return this._seen.has(nonce); }
+
+  rememberNonce(nonce, expiresAt) {
+    if (this._seen.size >= this.maxTracked)
+      this._seen.delete(this._seen.keys().next().value);
+    this._seen.set(nonce, expiresAt);
+  }
+}
+
+/**
+ * Where metering events go. The default hands each one straight to `onEvent`
+ * and swallows anything it throws, because serving must not depend on billing.
+ *
+ * That swallow is correct for uptime and lossy for revenue, which is the
+ * trade a durable sink is meant to change: buffer locally, flush in batches,
+ * retry on failure, and dedup on `idempotencyKey` at the far end. Implement
+ * `emit(event)` and pass it as `sink`. Whatever you build, it must not throw
+ * into the request path — this class is the last line that guarantees that.
+ */
+export class DirectSink {
+  constructor(onEvent) { this.onEvent = onEvent || (() => {}); }
+  emit(event) {
+    try { this.onEvent(event); } catch { /* metering must never break serving */ }
+  }
+}
+
 // ── the gate ────────────────────────────────────────────────────────────
 
 export class Wayleave {
@@ -242,6 +361,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 +383,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.
@@ -270,23 +400,40 @@ export class Wayleave {
     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
+    // Verifies that a UA claiming to be a known operator comes from that
+    // operator's published addresses. Absent, a declared agent is taken at
+    // its word — which is all "declared" ever meant.
+    this.verifyAgentIP = opts.verifyAgentIP || null;
+
+    // State and metering are interfaces, not implementations. Swap either for
+    // a shared or durable one without the gate noticing. See MemoryStore.
+    this.store = opts.store || new MemoryStore({ maxTracked: this.maxTracked });
+    this.sink = opts.sink || new DirectSink(this.onEvent);
+
+    // Identifies events from this process so a retrying sink can dedup. A
+    // counter alone would collide across instances; a timestamp alone would
+    // collide within a millisecond.
+    this._instance = randomUUID();
+    this._seq = 0;
   }
 
   /** req: { method, path, authority, headers, ip } → decision */
   handle(req, now = Math.floor(Date.now() / 1000), paymentProof = '') {
-    const c = classify(req, this.directories, now);
+    const c = classify(req, this.directories, now,
+                       { verifyAgentIP: this.verifyAgentIP, ip: this._client(req) });
     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,
+    // v is the event schema version. A meter that outlives one release has to
+    // know which shape it is reading; adding this after receipts exist in the
+    // wild would mean reconciling two formats forever.
+    const entry = { v: 1, idempotencyKey: `${this._instance}:${this._seq++}`,
+                    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 */ }
+    this.sink.emit(entry);
     return { lane, identity: ident, ...d, evidence };
   }
 
@@ -303,25 +450,24 @@ export class Wayleave {
   }
 
   /**
-   * 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.
+   * 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, delegated to whichever store is configured. */
   _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;
+    return this.store.hit(ident, this.rateWindow, now);
   }
 
   _decide(req, lane, ident, now, paymentProof, c) {
@@ -336,23 +482,32 @@ export class Wayleave {
     // 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))
+      if (this.store.hasNonce(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);
+      this.store.rememberNonce(c.nonce, c.sigExpires || now + this.rateWindow);
     }
     const limit = this.rateLimits[lane];
     if (limit) {
       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 +548,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.2.0",
   "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",