wayleave 0.3.0 → 0.4.1

package/README.md

@@ -4,9 +4,9 @@
 [![npm](https://img.shields.io/npm/v/wayleave.svg)](https://www.npmjs.com/package/wayleave)
 [![install size](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/wayleave)
 
-**Charge AI agents for passage across your app.**
+**Observe agent traffic. Control access. Charge payment-ready agents.**
 
-A *wayleave* is the fee paid for the right of passage across private land — utility companies have paid them for 150 years to run cables through property. AI agents are about to cross your app millions of times for free. Charge them a wayleave.
+Wayleave is open-source middleware for request classification, signed-agent verification, route-level policies and pricing. The [hosted Meter](https://meter.wayleave.dev) records traffic and settlement activity.
 
 Zero dependencies. Node's native crypto only. TypeScript declarations included.
 
@@ -14,7 +14,7 @@ Zero dependencies. Node's native crypto only. TypeScript declarations included.
 
 Every request gets classified into a lane:
 
-- **verified_agent** — valid Ed25519 signature (Web Bot Auth profile, RFC 9421) against a key directory you trust
+- **verified_agent** — valid Ed25519 HTTP Message Signature (RFC 9421, compatible with emerging Web Bot Auth) 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, which means *nothing gave it away*, not that a person is there
@@ -23,7 +23,40 @@ Then policy runs per lane: allow, deny, rate-limit — and on routes you price,
 
 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
+## Quickstart: observe first
+
+```sh
+npm install wayleave
+```
+
+[Create a Meter account](https://meter.wayleave.dev/account.html), issue an API key,
+and set `WAYLEAVE_METER_KEY` in your server environment. Signing in does not
+start billing. The optional hosted Meter trial requires a card and becomes
+$49/month after 3 days unless canceled; see your account for current terms.
+
+In your existing Express app:
+
+```js
+import Wayleave from 'wayleave';
+
+if (!process.env.WAYLEAVE_METER_KEY) {
+  throw new Error('Set WAYLEAVE_METER_KEY before starting the app');
+}
+const gate = new Wayleave({
+  meter: { apiKey: process.env.WAYLEAVE_METER_KEY },
+});
+app.use(gate.express()); // before the routes you want to observe
+```
+
+Send a request to your app, allow the buffer to flush, then open the
+[Meter dashboard](https://meter.wayleave.dev/app.html). No pricing, blocking,
+or rate limits are configured in this example. Drain `gate.sink.close()`
+during your application's graceful shutdown. Keep the key server-side.
+
+The middleware also works without an account: omit `meter` and use `onEvent`
+to send events to your own backend. See [integration docs](https://meter.wayleave.dev/docs.html).
+
+## Add access rules and payments
 
 ```js
 import Wayleave from 'wayleave';
@@ -58,8 +91,9 @@ 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.
+- A signature is single-use only when the signer sends a nonce. `signRequest(..., nonce)` will issue one (`true` for random, or supply your own) and the gate then refuses a repeat. Without a nonce there is nothing to remember a request by, and a captured signature stays usable until it expires — on any path of the host, since the Web Bot Auth profile covers only `@authority`. Opt in when you sign per attempt; leave it off if your client retries by resending the same headers.
 - 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.
+- Local verification is benchmarked by the tests; latency depends on your hardware and configuration. Payment-provider network calls add latency.
 - The metering hook can throw, crash, or hang your billing backend — serving continues. Your uptime never depends on ours.
 - 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.
@@ -85,8 +119,8 @@ Pay-at-the-door, not IOUs. On a route you price:
 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.
+4. Access can be released after payment verification. Your verifier must
+   check the payment with the configured provider before returning success.
 
 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
@@ -94,9 +128,9 @@ 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.
+The [hosted Meter](https://meter.wayleave.dev) records crossings and confirmed
+settlement activity. The 402 challenge is built in; payment verification is
+a function you configure. A Meter account does not configure a payment rail.
 
 **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

package/cdp-auth.js

@@ -0,0 +1,35 @@
+import { createPrivateKey, randomBytes, sign } from 'node:crypto';
+
+/** Short-lived, request-bound CDP bearer token. The secret never leaves this process.
+ * https://docs.cdp.coinbase.com/api-reference/v2/authentication
+ */
+export function cdpBearerToken({ apiKeyId, apiKeySecret, url, now = Math.floor(Date.now() / 1000) }) {
+  if (!apiKeyId || !apiKeySecret) throw new Error('CDP credentials are required');
+  const target = new URL(url);
+  if (target.protocol !== 'https:' || target.username || target.password || target.hash)
+    throw new Error('CDP endpoint must be an HTTPS URL without credentials or fragment');
+  let key;
+  try {
+    if (apiKeySecret.includes('-----BEGIN')) {
+      key = createPrivateKey(apiKeySecret.replaceAll('\\n', '\n'));
+    } else {
+      const raw = Buffer.from(apiKeySecret, 'base64');
+      if (raw.length !== 64) throw new Error('Invalid length');
+      key = createPrivateKey({ key: Buffer.concat([
+        Buffer.from('302e020100300506032b657004220420', 'hex'), raw.subarray(0, 32),
+      ]), format: 'der', type: 'pkcs8' });
+    }
+  } catch {
+    throw new Error('Invalid CDP signing key; use the Secret API Key, not a client or wallet key');
+  }
+  const ed = key.asymmetricKeyType === 'ed25519';
+  if (!ed && !(key.asymmetricKeyType === 'ec' && key.asymmetricKeyDetails?.namedCurve === 'prime256v1'))
+    throw new Error('CDP signing key must be Ed25519 or P-256');
+  const encode = value => Buffer.from(JSON.stringify(value)).toString('base64url');
+  const header = encode({ alg: ed ? 'EdDSA' : 'ES256', typ: 'JWT', kid: apiKeyId, nonce: randomBytes(16).toString('hex') });
+  const claims = encode({ sub: apiKeyId, iss: 'cdp', aud: ['cdp_service'], nbf: now, exp: now + 120,
+    uri: `POST ${target.host}${target.pathname}` });
+  const input = `${header}.${claims}`;
+  const signature = sign(ed ? null : 'sha256', Buffer.from(input), ed ? key : { key, dsaEncoding: 'ieee-p1363' });
+  return `${input}.${signature.toString('base64url')}`;
+}

package/index.d.ts

@@ -328,7 +328,9 @@ export interface WayleaveOptions {
 export function buildParams(
   keyid: string,
   created: number,
-  expires: number
+  expires: number,
+  /** Appended as `;nonce="..."` when present. */
+  nonce?: string | null
 ): string;
 
 /**
@@ -342,7 +344,13 @@ export function signRequest(
   keyid: string,
   directoryUrl: string,
   created?: number,
-  expires?: number
+  expires?: number,
+  /**
+   * Opt in to a single-use signature. `true` generates 16 random bytes; a
+   * string is used verbatim. Omit it if your client retries by resending the
+   * same headers — a nonce turns that retry into a rejected replay.
+   */
+  nonce?: string | boolean | null
 ): Record<string, string>;
 
 /** Verify a presented signature against your configured directories. */

package/index.js

@@ -18,7 +18,7 @@
  */
 
 import { createPublicKey, verify as edVerify, sign as edSign,
-         createHash, randomUUID } from 'node:crypto';
+         createHash, randomUUID, randomBytes } 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';
@@ -91,18 +91,38 @@ function sigBase(components, ctx, paramsRaw) {
   return Buffer.from(lines.join('\n'));
 }
 
-export function buildParams(keyid, created, expires) {
+export function buildParams(keyid, created, expires, nonce = null) {
   return `("@authority" "signature-agent");created=${created};` +
-         `keyid="${keyid}";alg="ed25519";expires=${expires};tag="web-bot-auth"`;
+         `keyid="${keyid}";alg="ed25519";expires=${expires};tag="web-bot-auth"` +
+         (nonce ? `;nonce="${nonce}"` : '');
 }
 
-/** What a legitimate agent operator's SDK does before sending. */
+/**
+ * What a legitimate agent operator's SDK does before sending.
+ *
+ * `nonce` is opt-in, and opting in is what makes a signature single-use.
+ * Without one, `verifySignature` has nothing to remember a request by, and
+ * `replayProtection` on the verifying side is inert however it is configured
+ * — the Web Bot Auth profile covers only `@authority`, so the same signature
+ * is valid for every path on the host until it expires.
+ *
+ * It is not the default because it changes what a retry means. An agent that
+ * signs once and resends those exact headers after a socket error is doing
+ * something reasonable, and a nonce turns that retry into a rejected replay.
+ * Callers that re-sign per attempt should pass `true`; callers that retry with
+ * held headers should not.
+ *
+ * Pass a string to supply your own, or `true` for 16 random bytes.
+ */
 export function signRequest(headers, authority, privateKey, keyid, directoryUrl,
                             created = Math.floor(Date.now() / 1000),
-                            expires = created + 300) {
+                            expires = created + 300,
+                            nonce = null) {
   // Structured-field string: the value is sent quoted.
   headers['signature-agent'] = `"${directoryUrl}"`;
-  const params = buildParams(keyid, created, expires);
+  const n = nonce === true ? randomBytes(16).toString('base64url')
+          : (typeof nonce === 'string' && nonce ? nonce : null);
+  const params = buildParams(keyid, created, expires, n);
   const base = sigBase(['@authority', 'signature-agent'],
                        { authority, headers }, params);
   const sig = edSign(null, base, privateKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",
@@ -27,7 +27,8 @@
     "meter.d.ts",
     "meter.js",
     "x402.d.ts",
-    "x402.js"
+    "x402.js",
+    "cdp-auth.js"
   ],
   "scripts": {
     "test": "node --test *.test.js"
@@ -49,6 +50,7 @@
     "ed25519"
   ],
   "license": "MIT",
+  "author": "Gibran Corbin (https://github.com/gibrancorbin11-hub)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gibrancorbin11-hub/wayleave.git"
@@ -56,5 +58,5 @@
   "bugs": {
     "url": "https://github.com/gibrancorbin11-hub/wayleave/issues"
   },
-  "homepage": "https://github.com/gibrancorbin11-hub/wayleave#readme"
+  "homepage": "https://wayleave.dev"
 }

package/x402.d.ts

@@ -16,9 +16,16 @@ export interface CoinbaseFacilitatorOptions {
   asset?: string;
   /** Asset decimals. 6 for USDC. */
   decimals?: number;
+  /**
+   * The EIP-712 domain the payer signed against, as the token contract
+   * reports it. Defaults are known for `base` and `base-sepolia`; supply it
+   * for any other network. Required by the facilitator — without it a payment
+   * is read, the payer identified, and the signature never checked.
+   */
+  extra?: { name: string; version: string };
   /**
    * true (default) submits the payment on-chain. false only verifies it,
-   * which is useful for a dry run but pays nobody.
+   * which is useful for a dry run but pays nobody and never grants access.
    */
   settle?: boolean;
   baseUrl?: string;

package/x402.js

@@ -1,3 +1,4 @@
+import { cdpBearerToken } from './cdp-auth.js';
 /**
  * wayleave/x402 — a ready-made `verifyPayment` for the Coinbase x402 rail.
  *
@@ -55,6 +56,37 @@ export function toAtomicUnits(usd, decimals = DEFAULT_DECIMALS) {
   return (whole + frac.padEnd(decimals, '0')).replace(/^0+(?=\d)/, '');
 }
 
+/**
+ * The settlement asset per network, and the EIP-712 domain its contract
+ * enforces.
+ *
+ * Both are REQUIRED by the facilitator and neither can be guessed:
+ *
+ *   - Omit `asset` and CDP rejects the call outright ("x402V1PaymentRequirements
+ *     requires 'asset'"). Until 0.4.1 this module omitted it whenever the
+ *     caller did not pass one, which was the default. No default configuration
+ *     could settle a payment.
+ *   - Omit `extra` and CDP identifies the payer and then refuses with "missing
+ *     EIP-712 domain parameters". The agent signs an EIP-3009 authorization
+ *     against the token's own domain, and the facilitator has to be told which
+ *     domain to check the signature against.
+ *
+ * The name genuinely differs per deployment -- Base mainnet USDC calls itself
+ * "USD Coin", the Sepolia test token calls itself "USDC" -- so one hardcoded
+ * value is wrong on the other chain. These were read from each contract and
+ * checked against its own DOMAIN_SEPARATOR.
+ */
+const KNOWN_ASSETS = {
+  'base': {
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    extra: { name: 'USD Coin', version: '2' }, decimals: 6,
+  },
+  'base-sepolia': {
+    asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    extra: { name: 'USDC', version: '2' }, decimals: 6,
+  },
+};
+
 /**
  * Build a `verifyPayment(proof, ctx)` for the Coinbase x402 facilitator.
  *
@@ -73,7 +105,7 @@ export function toAtomicUnits(usd, decimals = DEFAULT_DECIMALS) {
  */
 export function coinbaseFacilitator({
   apiKeyId, apiKeySecret, receivingAddress,
-  network = 'base', asset = null, decimals = DEFAULT_DECIMALS,
+  network = 'base', asset = null, decimals = null, extra = null,
   settle = true, baseUrl = DEFAULT_BASE, onError = () => {}, fetch: f = fetch,
 } = {}) {
   if (!apiKeyId || !apiKeySecret)
@@ -81,6 +113,24 @@ export function coinbaseFacilitator({
   if (!receivingAddress)
     throw new Error('coinbaseFacilitator requires receivingAddress — the address YOU get paid at');
 
+  const known = KNOWN_ASSETS[network];
+  const resolvedAsset = asset ?? known?.asset ?? null;
+  const resolvedExtra = extra ?? known?.extra ?? null;
+  const resolvedDecimals = decimals ?? known?.decimals ?? DEFAULT_DECIMALS;
+
+  // Fail here rather than on the first payment. A facilitator that cannot
+  // possibly settle should not be constructible: the alternative is a service
+  // that looks configured, passes its own tests, and denies every real payment
+  // with a 400 from someone else's API.
+  if (!resolvedAsset)
+    throw new Error(
+      `coinbaseFacilitator: no settlement asset known for network "${network}" — ` +
+      'pass asset: "0x..." (the token contract payment settles in)');
+  if (!resolvedExtra?.name || !resolvedExtra?.version)
+    throw new Error(
+      `coinbaseFacilitator: no EIP-712 domain known for network "${network}" — ` +
+      'pass extra: { name, version } as the token contract reports them');
+
   const base = baseUrl.replace(/\/$/, '');
 
   return async function verifyPayment(proof, ctx) {
@@ -103,13 +153,16 @@ export function coinbaseFacilitator({
         // 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),
+        maxAmountRequired: toAtomicUnits(ctx.price, resolvedDecimals),
         resource: ctx.resource ?? ctx.path ?? '',
         description: '',
         mimeType: 'application/json',
         payTo: receivingAddress,
         maxTimeoutSeconds: 60,
-        ...(asset ? { asset } : {}),
+        asset: resolvedAsset,
+        // The domain the payer signed against. Without it the facilitator can
+        // read the payload and still not check the signature.
+        extra: resolvedExtra,
       };
     } catch (err) {
       return deny(`cannot build payment requirements: ${err.message}`);
@@ -148,7 +201,9 @@ export function coinbaseFacilitator({
 
     if (d.isValid !== true)
       return deny(`payment not valid: ${d.invalidReason ?? 'no reason given'}`);
-    return { ok: true, ref: d.payer ? `payer:${d.payer}` : null };
+    // A valid authorization is not settled money. Do not release a priced
+    // resource or record billed revenue from a verification-only dry run.
+    return { ok: false, reason: 'Payment verified only; settlement is disabled' };
   };
 }
 
@@ -160,8 +215,7 @@ async function post(f, url, body, keyId, keySecret) {
       method: 'POST',
       headers: {
         'content-type': 'application/json',
-        'cb-access-key': keyId,
-        'cb-access-secret': keySecret,
+        authorization: `Bearer ${cdpBearerToken({ apiKeyId: keyId, apiKeySecret: keySecret, url })}`,
       },
       body: JSON.stringify(body),
       signal: ctrl.signal,