wayleave 0.2.0 → 0.3.0

package/README.md

@@ -27,6 +27,7 @@ Only the first lane is cryptographic. The other three are read off what the clie
 
 ```js
 import Wayleave from 'wayleave';
+import { coinbaseFacilitator } from 'wayleave/x402';
 
 const gate = new Wayleave({
   directories: {
@@ -38,14 +39,22 @@ 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
+  verifyPayment: coinbaseFacilitator({                   // REQUIRED to sell
+    apiKeyId: process.env.CDP_API_KEY_ID,
+    apiKeySecret: process.env.CDP_API_KEY_SECRET,
+    receivingAddress: process.env.WAYLEAVE_RECEIVING_ADDRESS,
+  }),
   onEvent: e => queueForBilling(e),        // metering hook; never blocks serving
 });
 
-app.use(gate.express());
+app.use(gate.express());   // async: it awaits your verifier
 ```
 
+**If you sell anything, use `gate.express()` or `gate.handleAsync()`.**
+Confirming settlement is a network call, so a real `verifyPayment` returns a
+Promise. The synchronous `handle()` cannot await one and will tell you so
+rather than quietly denying every payment.
+
 ## Guarantees, honestly stated
 
 - Signature verification is real Ed25519 over an RFC 9421 signature base — forged keys, tampered requests, expired signatures, and replay-farming windows are all rejected. Tested adversarially, and against other implementations' wire formats rather than only its own.
@@ -59,13 +68,13 @@ app.use(gate.express());
 
 ## Status
 
-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.
+v0.3.0 — verification, lanes, policy, pricing, and the metering hook, all under test (101 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).
+0.2.1 ships `wayleave/meter`, a buffering and retrying sink for the hosted meter. 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
 
@@ -159,6 +168,28 @@ new Wayleave({
 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.
 
+A buffering, retrying sink ships in the box:
+
+```js
+import Wayleave from 'wayleave';
+import { MeterSink } from 'wayleave/meter';
+
+const sink = new MeterSink({
+  endpoint: 'https://meter.wayleave.dev',
+  apiKey: process.env.WAYLEAVE_METER_KEY,
+  onError: (err, info) => log.warn({ err, info }, 'meter'),
+});
+
+const gate = new Wayleave({ pricedPaths: { '/api/premium': 0.05 }, sink });
+process.on('SIGTERM', () => sink.close());   // drain, or lose what is buffered
+```
+
+`emit` is synchronous, non-throwing, and does no I/O — a billing backend
+having a bad day must not become your customers having one. Retries are safe
+because of the idempotency key: sending a batch twice costs a round trip, not
+a double-billed customer. The buffer is bounded, and anything shed is counted
+and reported rather than dropped quietly.
+
 `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

package/index.d.ts

@@ -116,7 +116,8 @@ export interface PaymentContext {
 export type PaymentVerifier = (
   proof: string,
   ctx: PaymentContext
-) => boolean | { ok: boolean; ref?: string; reason?: string };
+) => boolean | { ok: boolean; ref?: string; reason?: string }
+  | Promise<boolean | { ok: boolean; ref?: string; reason?: string }>;
 
 /** x402-shaped payment challenge returned with a 402. */
 export interface PaymentChallenge {
@@ -315,6 +316,12 @@ export interface WayleaveOptions {
    * billing must never break serving.
    */
   onEvent?: (event: MeterEvent) => void;
+  /**
+   * Shorthand for wiring a `MeterSink` yourself: `meter: { apiKey }` builds
+   * one pointed at meter.wayleave.dev. Pass `sink` directly for full control;
+   * an explicit `sink` always wins.
+   */
+  meter?: { apiKey: string; endpoint?: string; [k: string]: unknown };
 }
 
 /** Build the `@signature-params` value for the Web Bot Auth profile. */
@@ -364,6 +371,12 @@ export function classify(
 
 export class Wayleave {
   constructor(opts?: WayleaveOptions);
+  /**
+   * Async twin of `handle`. Required if `verifyPayment` returns a Promise —
+   * which any real facilitator does, since confirming settlement is a network
+   * call. `express()` uses this.
+   */
+  handleAsync(req: WayleaveRequest, now?: number, paymentProof?: string): Promise<Decision>;
   /** Classify, apply policy, price, and emit the metering event. */
   handle(
     req: WayleaveRequest,

package/index.js

@@ -19,6 +19,9 @@
 
 import { createPublicKey, verify as edVerify, sign as edSign,
          createHash, randomUUID } from 'node:crypto';
+// Same package, zero dependencies, ~9KB. Importing it unconditionally costs
+// nothing measurable and makes `meter: { apiKey }` work without ceremony.
+import { MeterSink } from './meter.js';
 
 export const LANES = Object.freeze({
   VERIFIED: 'verified_agent',
@@ -351,6 +354,24 @@ export class DirectSink {
   }
 }
 
+/**
+ * Turn whatever a verifier returned into a verdict.
+ *
+ * A Promise reaching here means an async verifier was used on the synchronous
+ * path. Reading `.ok` off a Promise yields undefined and denies silently —
+ * which is precisely how the documented facilitator example failed from 0.1.5
+ * to 0.2.1. It now says so instead.
+ */
+function normalizeVerdict(r) {
+  if (r && typeof r.then === 'function')
+    return { ok: false, reason:
+      'verifyPayment returned a Promise — use gate.handleAsync() or gate.express(), ' +
+      'which await it. The synchronous handle() cannot.' };
+  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' };
+}
+
 // ── the gate ────────────────────────────────────────────────────────────
 
 export class Wayleave {
@@ -408,7 +429,19 @@ export class Wayleave {
     // 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);
+
+    // `meter: { apiKey }` is shorthand for wiring a MeterSink yourself. It
+    // exists because the two-line version of this was the most common thing
+    // people got wrong: forgetting to drain on shutdown, or handing the sink
+    // a callback that throws. Pass `sink` directly if you want control.
+    this.sink = opts.sink
+      || (opts.meter?.apiKey
+            ? new MeterSink({
+                endpoint: 'https://meter.wayleave.dev',
+                ...opts.meter,
+              })
+            : null)
+      || 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
@@ -437,6 +470,28 @@ export class Wayleave {
     return { lane, identity: ident, ...d, evidence };
   }
 
+  /**
+   * Async twin of handle(), for verifiers that talk to a network.
+   *
+   * Identical in every respect except that it can await your verifyPayment.
+   * Use this whenever you actually sell something; the Express adapter does.
+   */
+  async handleAsync(req, now = Math.floor(Date.now() / 1000), paymentProof = '') {
+    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 = await this._decideAsync(req, lane, ident, now, proof, c);
+    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;
+    this.sink.emit(entry);
+    return { lane, identity: ident, ...d, evidence };
+  }
+
   /**
    * Who to rate-limit. A cryptographic identity is authoritative; a network
    * address is at least expensive to rotate. A header is neither.
@@ -449,6 +504,7 @@ 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.
@@ -470,7 +526,17 @@ export class Wayleave {
     return this.store.hit(ident, this.rateWindow, now);
   }
 
-  _decide(req, lane, ident, now, paymentProof, c) {
+  /**
+   * Everything up to the payment question.
+   *
+   * Split out so the sync and async paths share one copy of the policy,
+   * replay, and rate-limit logic. Two copies of this would drift, and the
+   * half that drifted would be the one nobody tested.
+   *
+   * Returns either a final decision, or a marker saying a priced route was
+   * matched and a payment verdict is needed.
+   */
+  _preDecide(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}` };
@@ -508,12 +574,10 @@ export class Wayleave {
               : '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)
-            return { status: 200, billed: price, paymentRef: v.ref,
-                     why: `settled $${price}` };
-          return { status: 402, why: `payment proof rejected: ${v.reason}`, challenge };
+          // Hand back to the caller, which knows whether it can await.
+          return { needsPayment: true, challenge, price,
+                   ctx: { price, resource: prefix, identity: ident,
+                          path: req.path, now } };
         }
       }
     }
@@ -522,6 +586,28 @@ export class Wayleave {
     return { status: 200, why: `${lane} allowed` };
   }
 
+  /** Turn a payment verdict into the final decision. Shared by both paths. */
+  _settleDecision(v, pre) {
+    if (v.ok)
+      return { status: 200, billed: pre.price, paymentRef: v.ref,
+               why: `settled $${pre.price}` };
+    return { status: 402, why: `payment proof rejected: ${v.reason}`,
+             challenge: pre.challenge };
+  }
+
+  _decide(req, lane, ident, now, paymentProof, c) {
+    const pre = this._preDecide(req, lane, ident, now, paymentProof, c);
+    if (!pre.needsPayment) return pre;
+    return this._settleDecision(this._checkPayment(paymentProof, pre.ctx), pre);
+  }
+
+  async _decideAsync(req, lane, ident, now, paymentProof, c) {
+    const pre = this._preDecide(req, lane, ident, now, paymentProof, c);
+    if (!pre.needsPayment) return pre;
+    return this._settleDecision(
+      await this._checkPaymentAsync(paymentProof, pre.ctx), pre);
+  }
+
   /**
    * Settlement is somebody else's job — a facilitator that actually moved the
    * money. This asks yours and believes nothing else. A verifier that throws
@@ -533,15 +619,32 @@ export class Wayleave {
     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' };
+    return normalizeVerdict(r);
+  }
+
+  /**
+   * The async twin of _checkPayment.
+   *
+   * Every real facilitator is a network call, so a useful verifier returns a
+   * Promise. The synchronous path cannot await one and refuses it loudly
+   * rather than reading `.ok` off a Promise and silently denying — which is
+   * what shipped from 0.1.5 to 0.2.1, and meant the documented way to sell
+   * anything never worked.
+   */
+  async _checkPaymentAsync(proof, ctx) {
+    if (!this.verifyPayment)
+      return { ok: false, reason: 'no verifyPayment configured' };
+    try {
+      return normalizeVerdict(await this.verifyPayment(proof, ctx));
+    } catch (e) {
+      return { ok: false, reason: `verifier threw: ${e.message}` };
+    }
   }
 
   /** Express/Connect adapter: app.use(wayleave.express()) */
   express() {
-    return (req, res, next) => {
-      const r = this.handle({
+    return async (req, res, next) => {
+      const r = await this.handleAsync({
         method: req.method, path: req.path || req.url,
         authority: req.headers.host || '',
         headers: req.headers,

package/meter.d.ts

@@ -0,0 +1,74 @@
+import type { MeterEvent, Sink } from './index.js';
+
+export interface MeterSinkOptions {
+  /** Base URL of your meter, e.g. "https://meter.wayleave.dev". */
+  endpoint: string;
+  /** API key issued by the meter. Sent as a bearer token. */
+  apiKey: string;
+  /** Drain interval in ms. Default 5000. */
+  flushMs?: number;
+  /** Events per request. Default 500; the meter caps batches at 1000. */
+  maxBatch?: number;
+  /**
+   * Hard ceiling on buffered events. Default 10000. Past this the oldest are
+   * shed — counted in `stats.dropped` and reported through `onError`, never
+   * dropped silently.
+   */
+  maxBuffer?: number;
+  /** Retries per batch, exponential backoff with jitter. Default 5. */
+  maxRetries?: number;
+  /** Per-request timeout in ms. Default 10000. */
+  timeoutMs?: number;
+  /**
+   * Observability hook for drops, permanent rejections, and unreachable
+   * meters. Anything it throws is swallowed — a broken error handler must not
+   * reach the request path either.
+   */
+  onError?: (err: Error, info: Record<string, unknown>) => void;
+  /** Injectable for tests. Defaults to global fetch. */
+  fetch?: typeof fetch;
+}
+
+export interface MeterSinkStats {
+  queued: number;
+  sent: number;
+  /** Shed from a full buffer, or permanently rejected by the meter. */
+  dropped: number;
+  failedBatches: number;
+  /** Reported by the meter as already-seen. Retries are supposed to produce these. */
+  duplicates: number;
+}
+
+/**
+ * A `Sink` that buffers, batches, and retries against a wayleave meter.
+ *
+ * Retrying is safe because every event carries an `idempotencyKey` and the
+ * meter deduplicates on it: sending a batch twice costs a round trip, not a
+ * double-billed customer.
+ *
+ * ```js
+ * import Wayleave from 'wayleave';
+ * import { MeterSink } from 'wayleave/meter';
+ *
+ * const sink = new MeterSink({
+ *   endpoint: 'https://meter.wayleave.dev',
+ *   apiKey: process.env.WAYLEAVE_METER_KEY,
+ *   onError: (err, info) => log.warn({ err, info }, 'meter'),
+ * });
+ *
+ * const gate = new Wayleave({ pricedPaths: { '/api/premium': 0.05 }, sink });
+ * process.on('SIGTERM', () => sink.close());
+ * ```
+ */
+export class MeterSink implements Sink {
+  constructor(opts: MeterSinkOptions);
+  readonly stats: MeterSinkStats;
+  /** Synchronous, non-throwing, no I/O. Safe on the request path. */
+  emit(event: MeterEvent): void;
+  /** Drain the buffer. Never rejects; concurrent calls collapse into one. */
+  flush(): Promise<void>;
+  /** Stop accepting events and make a final drain. Call on SIGTERM. */
+  close(): Promise<MeterSinkStats>;
+}
+
+export default MeterSink;

package/meter.js

@@ -0,0 +1,230 @@
+/**
+ * MeterSink — ships metering events to a wayleave meter.
+ *
+ * This is the concrete `sink` that 0.2.0's interface was shaped for. The
+ * default DirectSink hands each event straight to `onEvent` and swallows what
+ * it throws: correct for uptime, lossy for revenue. This one buffers, batches,
+ * and retries, so a meter that is briefly unreachable costs you nothing.
+ *
+ * Three rules govern every line in this file, in this order:
+ *
+ *   1. NEVER throw into the request path. A billing backend having a bad day
+ *      must not become your customers having a bad day. `emit` cannot throw,
+ *      cannot await, and cannot block.
+ *
+ *   2. NEVER lose an event silently. Dropping is sometimes unavoidable — a
+ *      buffer that grows forever is an outage, not a feature — but a drop is
+ *      always counted and always reported.
+ *
+ *   3. Retry freely. Every event carries an `idempotencyKey`, and the meter
+ *      deduplicates on it. Sending the same batch twice costs a round trip,
+ *      not a double-billed customer. This is the entire reason that field was
+ *      added before there was anything to receive it.
+ *
+ * Zero dependencies: `fetch` is global from Node 18.
+ */
+
+const DEFAULTS = {
+  flushMs: 5000,
+  maxBatch: 500,
+  maxBuffer: 10000,
+  maxRetries: 5,
+  timeoutMs: 10000,
+};
+
+export class MeterSink {
+  /**
+   * opts = {
+   *   endpoint: 'https://meter.wayleave.dev',   // required
+   *   apiKey:   'wm_live_...',                  // required
+   *   flushMs:   5000,   // how often to drain the buffer
+   *   maxBatch:  500,    // events per request; the meter caps at 1000
+   *   maxBuffer: 10000,  // hard ceiling before shedding
+   *   maxRetries: 5,     // per batch, exponential backoff
+   *   timeoutMs: 10000,
+   *   onError: (err, info) => {}   // observability hook; never called with
+   *                                // anything that should crash your process
+   * }
+   */
+  constructor(opts = {}) {
+    if (!opts.endpoint) throw new Error('MeterSink requires an endpoint');
+    if (!opts.apiKey) throw new Error('MeterSink requires an apiKey');
+
+    this.endpoint = String(opts.endpoint).replace(/\/$/, '');
+    this.apiKey = opts.apiKey;
+    this.flushMs = opts.flushMs ?? DEFAULTS.flushMs;
+    this.maxBatch = opts.maxBatch ?? DEFAULTS.maxBatch;
+    this.maxBuffer = opts.maxBuffer ?? DEFAULTS.maxBuffer;
+    this.maxRetries = opts.maxRetries ?? DEFAULTS.maxRetries;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULTS.timeoutMs;
+    this.onError = typeof opts.onError === 'function' ? opts.onError : () => {};
+    this._fetch = opts.fetch || globalThis.fetch;
+
+    this._buffer = [];
+    this._inFlight = false;
+    this._closed = false;
+
+    /** Counters worth exposing: a silent drop is a billing hole. */
+    this.stats = { queued: 0, sent: 0, dropped: 0, failedBatches: 0, duplicates: 0 };
+
+    this._timer = setInterval(() => { this.flush(); }, this.flushMs);
+    // Do not hold the process open just to run a billing timer.
+    if (typeof this._timer.unref === 'function') this._timer.unref();
+  }
+
+  /**
+   * Called by the gate, once per request, on the hot path.
+   *
+   * Synchronous, non-throwing, and does no I/O. The only work here is a push
+   * and possibly scheduling a flush on a later tick.
+   */
+  emit(event) {
+    if (this._closed) return;
+    try {
+      if (this._buffer.length >= this.maxBuffer) {
+        // Shed the oldest. They have been failing longest and are the most
+        // likely to be stale; the newest are the most likely to succeed on
+        // the next attempt. Either choice loses billing data, which is why
+        // this is counted and surfaced rather than quietly absorbed.
+        const shed = this._buffer.shift();
+        this.stats.dropped++;
+        this.onError(new Error('meter buffer full, dropped oldest event'), {
+          dropped: this.stats.dropped, idempotencyKey: shed?.idempotencyKey,
+        });
+      }
+      this._buffer.push(event);
+      this.stats.queued++;
+
+      // Schedule rather than await: emit must return to the request handler
+      // immediately.
+      if (this._buffer.length >= this.maxBatch && !this._inFlight)
+        queueMicrotask(() => this.flush());
+    } catch (err) {
+      // Even the buffering path must not throw into serving.
+      try { this.onError(err, { phase: 'emit' }); } catch { /* nothing left to do */ }
+    }
+  }
+
+  /**
+   * Drain the buffer. Safe to call at any time; concurrent calls collapse
+   * into the one already running.
+   *
+   * Never rejects. Failures are reported through `onError` and the events go
+   * back on the buffer for the next attempt.
+   */
+  async flush() {
+    if (this._inFlight || this._buffer.length === 0) return;
+    this._inFlight = true;
+    try {
+      while (this._buffer.length > 0) {
+        const batch = this._buffer.splice(0, this.maxBatch);
+        const ok = await this._sendWithRetry(batch);
+        if (!ok) {
+          // Put them back at the FRONT so ordering is preserved, and stop —
+          // hammering a meter that is down helps nobody.
+          this._buffer.unshift(...batch.slice(0, Math.max(0, this.maxBuffer - this._buffer.length)));
+          break;
+        }
+      }
+    } catch (err) {
+      try { this.onError(err, { phase: 'flush' }); } catch { /* ignore */ }
+    } finally {
+      this._inFlight = false;
+    }
+  }
+
+  async _sendWithRetry(batch) {
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const r = await this._send(batch);
+
+      if (r.ok) {
+        this.stats.sent += r.accepted ?? batch.length;
+        this.stats.duplicates += r.duplicates ?? 0;
+        if (r.rejected?.length) {
+          // The meter refused specific events permanently — a schema mismatch,
+          // usually. Retrying cannot fix them and would wedge everything
+          // queued behind. Report and move on.
+          this.onError(new Error(`meter rejected ${r.rejected.length} event(s)`), {
+            phase: 'send', rejected: r.rejected,
+          });
+        }
+        return true;
+      }
+
+      // 4xx other than 429 is our bug, not a blip. Retrying a malformed or
+      // unauthorised request forever is how a buffer becomes a memory leak.
+      if (r.status && r.status >= 400 && r.status < 500 && r.status !== 429) {
+        this.stats.failedBatches++;
+        this.stats.dropped += batch.length;
+        this.onError(new Error(`meter rejected batch: ${r.status} ${r.error ?? ''}`.trim()), {
+          phase: 'send', status: r.status, dropped: batch.length, permanent: true,
+        });
+        return true; // consumed: do not requeue something that can never succeed
+      }
+
+      if (attempt < this.maxRetries) {
+        // Exponential backoff with jitter, so a fleet of instances coming back
+        // after an outage does not stampede the meter in lockstep.
+        const base = Math.min(30000, 500 * 2 ** attempt);
+        await sleep(base / 2 + Math.random() * base / 2);
+      }
+    }
+
+    this.stats.failedBatches++;
+    this.onError(new Error('meter unreachable after retries; events requeued'), {
+      phase: 'send', batch: batch.length,
+    });
+    return false;
+  }
+
+  async _send(batch) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this._fetch(`${this.endpoint}/v1/events`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({ events: batch }),
+        signal: ctrl.signal,
+      });
+      let body = null;
+      try { body = await res.json(); } catch { /* non-JSON body stays null */ }
+      if (!res.ok) return { ok: false, status: res.status, error: body?.error };
+      return { ok: true, ...body };
+    } catch (err) {
+      return { ok: false, status: 0, error: err.message };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Stop accepting events and make a final attempt to drain.
+   *
+   * Call this on SIGTERM. Without it, whatever is buffered at shutdown is
+   * revenue you never billed for. With it, a rolling deploy costs nothing.
+   */
+  async close() {
+    this._closed = true;
+    clearInterval(this._timer);
+    await this.flush();
+    return this.stats;
+  }
+}
+
+/**
+ * Deliberately NOT unref'd, unlike the flush interval.
+ *
+ * The interval is a heartbeat and must not hold a process open. A backoff is
+ * an operation already in flight: unref'ing it lets the event loop drain
+ * mid-retry, which abandons events that were about to be delivered — during
+ * exactly the shutdown where `close()` is trying to save them.
+ */
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+export default MeterSink;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -9,16 +9,28 @@
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
+    },
+    "./meter": {
+      "types": "./meter.d.ts",
+      "default": "./meter.js"
+    },
+    "./x402": {
+      "types": "./x402.d.ts",
+      "default": "./x402.js"
     }
   },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "LICENSE",
     "README.md",
-    "LICENSE"
+    "index.d.ts",
+    "index.js",
+    "meter.d.ts",
+    "meter.js",
+    "x402.d.ts",
+    "x402.js"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test *.test.js"
   },
   "engines": {
     "node": ">=18"

package/x402.d.ts

@@ -0,0 +1,41 @@
+import type { PaymentVerifier } from './index.js';
+
+export interface CoinbaseFacilitatorOptions {
+  /** CDP API key id. Yours. */
+  apiKeyId: string;
+  /** CDP API key secret. Yours. */
+  apiKeySecret: string;
+  /**
+   * The address YOU get paid at. Money moves agent → facilitator → here.
+   * Wayleave is never a hop and holds nothing.
+   */
+  receivingAddress: string;
+  /** Default 'base'. */
+  network?: string;
+  /** Token contract address; omit for the network default (USDC). */
+  asset?: string;
+  /** Asset decimals. 6 for USDC. */
+  decimals?: number;
+  /**
+   * true (default) submits the payment on-chain. false only verifies it,
+   * which is useful for a dry run but pays nobody.
+   */
+  settle?: boolean;
+  baseUrl?: string;
+  onError?: (err: Error, info: Record<string, unknown>) => void;
+  fetch?: typeof fetch;
+}
+
+/**
+ * A ready-made `verifyPayment` for the Coinbase x402 rail.
+ *
+ * Returns a Promise, so use it with `gate.express()` or `gate.handleAsync()`.
+ * The synchronous `handle()` cannot await it and will say so rather than
+ * silently deny.
+ */
+export function coinbaseFacilitator(opts: CoinbaseFacilitatorOptions): PaymentVerifier;
+
+/** Dollars → atomic units as a decimal string. Throws on excess precision. */
+export function toAtomicUnits(usd: number | string, decimals?: number): string;
+
+export default coinbaseFacilitator;

package/x402.js

@@ -0,0 +1,181 @@
+/**
+ * wayleave/x402 — a ready-made `verifyPayment` for the Coinbase x402 rail.
+ *
+ * Before this existed, selling anything meant writing your own integration
+ * against the facilitator API: two endpoints, a request body shaped
+ * { x402Version, paymentPayload, paymentRequirements }, atomic-unit
+ * conversion, and a response that returns HTTP 200 even when the payment is
+ * bad. That is a lot of surface to get subtly wrong in the one place where
+ * being wrong means giving away data for free or billing for money that never
+ * moved.
+ *
+ * So it lives here instead, tested, and you configure it:
+ *
+ *   import Wayleave from 'wayleave';
+ *   import { coinbaseFacilitator } from 'wayleave/x402';
+ *
+ *   const gate = new Wayleave({
+ *     pricedPaths: { '/api/premium': 0.05 },
+ *     strictPricedPaths: true,
+ *     confirmHuman: req => Boolean(req.session?.userId),
+ *     verifyPayment: coinbaseFacilitator({
+ *       apiKeyId: process.env.CDP_API_KEY_ID,
+ *       apiKeySecret: process.env.CDP_API_KEY_SECRET,
+ *       receivingAddress: process.env.WAYLEAVE_RECEIVING_ADDRESS,
+ *     }),
+ *   });
+ *
+ * YOUR credentials, YOUR receiving address. Money moves agent -> facilitator
+ * -> you. Wayleave is not a hop, does not hold funds, and this module has no
+ * method that moves value — there is a test asserting that, because the day it
+ * gains one this stops being metering and becomes money transmission.
+ *
+ * Zero dependencies: fetch is global from Node 18.
+ */
+
+const DEFAULT_BASE = 'https://api.cdp.coinbase.com/platform';
+const X402_VERSION = 1;
+const DEFAULT_DECIMALS = 6;      // USDC and most stablecoins
+const TIMEOUT_MS = 10000;
+
+/**
+ * Dollars -> atomic units, as a decimal string.
+ *
+ * String arithmetic, not `usd * 10 ** decimals`, because floating point
+ * mangles money: 0.07 * 1e6 is 70000.00000000001 in JavaScript, and rounding
+ * that is how a ledger acquires a cent of drift per transaction.
+ */
+export function toAtomicUnits(usd, decimals = DEFAULT_DECIMALS) {
+  const s = String(usd);
+  if (!/^\d+(\.\d+)?$/.test(s))
+    throw new Error(`amount must be a non-negative decimal, got "${usd}"`);
+  const [whole, frac = ''] = s.split('.');
+  if (frac.length > decimals)
+    throw new Error(`amount ${usd} is finer than the asset's ${decimals} decimals`);
+  return (whole + frac.padEnd(decimals, '0')).replace(/^0+(?=\d)/, '');
+}
+
+/**
+ * Build a `verifyPayment(proof, ctx)` for the Coinbase x402 facilitator.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiKeyId          CDP API key id
+ * @param {string} opts.apiKeySecret      CDP API key secret
+ * @param {string} opts.receivingAddress  YOUR address. Never ours.
+ * @param {string} [opts.network]         'base' (default) | 'base-sepolia' | ...
+ * @param {string} [opts.asset]           token contract; omit for the network default
+ * @param {number} [opts.decimals]        asset decimals, 6 for USDC
+ * @param {boolean} [opts.settle]         true (default) submits on-chain.
+ *                                        false only verifies — useful for a
+ *                                        dry run, but nobody gets paid.
+ * @param {(err:Error, info:object)=>void} [opts.onError]
+ * @returns {(proof:string, ctx:object)=> Promise<{ok:boolean, ref?:string, reason?:string}>}
+ */
+export function coinbaseFacilitator({
+  apiKeyId, apiKeySecret, receivingAddress,
+  network = 'base', asset = null, decimals = DEFAULT_DECIMALS,
+  settle = true, baseUrl = DEFAULT_BASE, onError = () => {}, fetch: f = fetch,
+} = {}) {
+  if (!apiKeyId || !apiKeySecret)
+    throw new Error('coinbaseFacilitator requires apiKeyId and apiKeySecret');
+  if (!receivingAddress)
+    throw new Error('coinbaseFacilitator requires receivingAddress — the address YOU get paid at');
+
+  const base = baseUrl.replace(/\/$/, '');
+
+  return async function verifyPayment(proof, ctx) {
+    // The middleware hands us the proof as a string; agents send the signed
+    // 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'); }
+    }
+    if (!paymentPayload || typeof paymentPayload !== 'object')
+      return deny('no payment payload supplied');
+
+    let requirements;
+    try {
+      requirements = {
+        scheme: 'exact',
+        network,
+        // We assert what was required; the facilitator checks the payment
+        // matches. Under the exact scheme the transfer MUST equal this and
+        // MUST land at payTo, so a wrong amount or wrong address cannot come
+        // back valid. That is stronger than trusting a number the payer sent.
+        maxAmountRequired: toAtomicUnits(ctx.price, decimals),
+        resource: ctx.resource ?? ctx.path ?? '',
+        description: '',
+        mimeType: 'application/json',
+        payTo: receivingAddress,
+        maxTimeoutSeconds: 60,
+        ...(asset ? { asset } : {}),
+      };
+    } catch (err) {
+      return deny(`cannot build payment requirements: ${err.message}`);
+    }
+
+    const body = { x402Version: X402_VERSION, paymentPayload, paymentRequirements: requirements };
+    const path = settle ? '/v2/x402/settle' : '/v2/x402/verify';
+
+    let res;
+    try {
+      res = await post(f, `${base}${path}`, body, apiKeyId, apiKeySecret);
+    } catch (err) {
+      // Unreachable facilitator denies. An outage must degrade into unpaid,
+      // never into free passage recorded as revenue.
+      onError(err, { phase: 'facilitator', path });
+      return deny(`facilitator unreachable: ${err.message}`);
+    }
+
+    if (!res.ok) {
+      onError(new Error(`facilitator ${res.status}`), { phase: 'facilitator', path });
+      return deny(`facilitator returned ${res.status}`);
+    }
+
+    const d = res.data ?? {};
+
+    // CRITICAL: the facilitator answers HTTP 200 even when the payment is
+    // bad. Reading the status code alone books every rejected payment as
+    // revenue — which is exactly the bug 0.1.5 fixed, one layer down.
+    if (settle) {
+      if (d.success !== true)
+        return deny(`settlement failed: ${d.errorReason ?? 'no reason given'}`);
+      if (!d.transaction)
+        return deny('settlement reported success with nothing to reference');
+      return { ok: true, ref: String(d.transaction) };
+    }
+
+    if (d.isValid !== true)
+      return deny(`payment not valid: ${d.invalidReason ?? 'no reason given'}`);
+    return { ok: true, ref: d.payer ? `payer:${d.payer}` : null };
+  };
+}
+
+async function post(f, url, body, keyId, keySecret) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    const r = await f(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'cb-access-key': keyId,
+        'cb-access-secret': keySecret,
+      },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    let data = null;
+    try { data = await r.json(); } catch { /* non-JSON body stays null */ }
+    return { ok: r.ok, status: r.status, data };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function deny(reason) {
+  return { ok: false, reason };
+}
+
+export default coinbaseFacilitator;