wayleave 0.5.1 → 0.5.3

package/README.md

@@ -62,8 +62,10 @@ 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.
+start billing. The optional hosted plans require a card and start after a
+3-day trial unless canceled — current plans and prices are at
+[wayleave.dev/pricing](https://wayleave.dev/pricing/), which is the one place
+they are kept up to date.
 
 In your existing Express app:
 

package/index.d.ts

@@ -377,6 +377,18 @@ export function classify(
   }
 ): Classification;
 
+/**
+ * The path a request is for, whichever property the framework used.
+ *
+ * Express sets `req.path`; Node's own server and most other frameworks set
+ * `req.url` with the query still attached. Query and fragment are removed,
+ * so "/api?x=1" and "/api" are the same route.
+ */
+export function requestPath(req: { path?: string; url?: string } | null | undefined): string;
+
+/** True when `path` is `prefix` or lies beneath its boundary. Query-insensitive. */
+export function pathUnder(path: string, prefix: string): boolean;
+
 export class Wayleave {
   constructor(opts?: WayleaveOptions);
   /**

package/index.js

@@ -95,6 +95,57 @@ function sigBase(components, ctx, paramsRaw) {
   return Buffer.from(lines.join('\n'));
 }
 
+/**
+ * Does `path` fall under `prefix`?
+ *
+ * Not `startsWith`. A raw prefix test makes "/api" match "/apiv2" and
+ * "/api-internal", which is wrong in both directions and dangerous in one:
+ *
+ *   pricedPaths { "/api": 0.05 }     charges for /apiv2, which the operator
+ *                                    never priced
+ *   rules { bot: [["/public", true]] }  ALLOWS /public-admin, which the
+ *                                    operator never opened
+ *
+ * The second is the one that matters. An over-matching deny is merely
+ * annoying; an over-matching allow is a hole.
+ *
+ * A prefix matches the path itself or anything beneath its boundary, and a
+ * trailing slash on the prefix changes nothing — "/api" and "/api/" mean the
+ * same thing, because operators write both and neither should surprise them.
+ */
+/**
+ * The path to decide about, whatever shape the caller's request object has.
+ *
+ * Express puts a query-free path on `req.path`. Node's own http server -- and
+ * every framework that hands you its raw request -- puts "/api/x?y=1" on
+ * `req.url` and nothing on `req.path`. `handle()` read `req.path` alone, so a
+ * caller outside Express passed `undefined` into the matcher, matched no
+ * priced prefix and no rule, and was allowed through. Silently: a 200 on a
+ * route the operator had priced, with a receipt recording no path at all.
+ *
+ * The query and fragment come off here for the same reason they come off in
+ * pathUnder: "/api?x=1" must not be a different route from "/api", and a
+ * query string recorded in a receipt is user data we never asked for.
+ */
+export function requestPath(req) {
+  const raw = (req && (req.path ?? req.url)) ?? '';
+  return String(raw).split('#')[0].split('?')[0] || '/';
+}
+
+export function pathUnder(path, prefix) {
+  if (typeof path !== 'string' || typeof prefix !== 'string') return false;
+  /* Strip the query before comparing. `handle()` takes whatever the caller
+     passes, and callers pass `req.url` as often as `req.path` — so "/api?x=1"
+     arrived here as a literal and matched no prefix at all. In 0.5.2 that
+     meant appending "?x=1" walked straight past a priced route: the boundary
+     fix was bypassable by anyone who noticed. Also cut the fragment, which a
+     server should never see but a hand-built request can carry. */
+  path = path.split('#')[0].split('?')[0];
+  if (prefix === '' || prefix === '/') return true;
+  const base = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  return path === base || path.startsWith(base + '/');
+}
+
 export function buildParams(keyid, created, expires, nonce = null) {
   return `("@authority" "signature-agent");created=${created};` +
          `keyid="${keyid}";alg="ed25519";expires=${expires};tag="web-bot-auth"` +
@@ -239,10 +290,25 @@ export function verifySignature(h, authority, directories,
 
 // ── classification ──────────────────────────────────────────────────────
 
-const AGENT_UA = [
+/* Named agents, not the word "agent".
+ *
+ * `/agent/` matched "MyAgencyCRM" and "UserAgent/1.0" — ordinary software with
+ * an unlucky name, sorted into the lane that gets charged. Guessing from a
+ * substring is the opposite of what this library is for: identity comes from
+ * signature math, and the UA list is only a declared-intent hint for the
+ * crawlers that announce themselves honestly.
+ *
+ * Exported so an operator can add the one their traffic actually shows. */
+export const AGENT_UA = [
   /gptbot/, /oai-searchbot/, /chatgpt-user/, /claude(?:bot|-user|-searchbot)?/,
-  /perplexitybot/, /google-extended/, /bingbot/, /anthropic/, /openai/,
-  /agent/, /autonomous/, /\bbot\b/,
+  /perplexitybot/, /google-extended/, /bingbot/, /duckassistbot/, /applebot-extended/,
+  /meta-externalagent/, /amazonbot/, /youbot/, /ccbot/, /cohere-ai/, /diffbot/,
+  /anthropic/, /openai/, /autonomous[- ]agent/,
+  /* `bot` ending a word, not `\bbot\b`. Agents name themselves by suffix —
+     GPTBot, ClaudeBot, PerplexityBot, ShopBot — and a leading word boundary
+     misses every one of them. A trailing boundary still refuses `bottle`,
+     because the `t` that follows is a word character. */
+  /bot\b/, /crawler\b/, /spider\b/,
 ];
 const AUTOMATION_TELLS = [
   ['headlesschrome', 'headless browser UA'],
@@ -457,7 +523,36 @@ export class Wayleave {
     // 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;
+    /* Item 3. The human lane means "nothing tripped", not "verified person":
+       a User-Agent and an Accept-Language are enough to reach it, and both are
+       one line in any scraper. With strict mode off, every priced route was
+       free to anything that looked like a browser — which is the whole product
+       leaking.
+
+       So it now defaults ON wherever there is something to protect. Turning it
+       off stays possible and says so once at startup, because an operator who
+       chooses it should know what they chose. */
+    this.strictPricedPaths = opts.strictPricedPaths === undefined
+      ? Object.keys(this.pricedPaths).length > 0
+      : opts.strictPricedPaths === true;
+    const priced = Object.keys(this.pricedPaths).length > 0;
+    const warn = this._onWarn = opts.onWarn || console.warn;
+    if (opts.strictPricedPaths === false && priced)
+      warn('[wayleave] strictPricedPaths is off: priced routes are reachable free ' +
+           'by any client that looks like a browser. Pass confirmHuman() to charge ' +
+           'agents while letting your signed-in people through.');
+    /* The other half of item 3, and the one that can hurt a real person.
+       
+       Strict mode says the human lane is not enough on a priced route. If the
+       operator has not also said how to recognise their own people, then
+       nobody qualifies — and a customer reading an article gets a 402. The law
+       this library is built on is that people never pay and never get blocked,
+       so the combination that breaks it does not pass silently. */
+    if (this.strictPricedPaths && priced && typeof opts.confirmHuman !== 'function')
+      warn('[wayleave] priced routes are strict but no confirmHuman() was given, ' +
+           'so signed-in people will be asked to pay like agents. Pass ' +
+           'confirmHuman: (req) => Boolean(yourSession(req)), or set ' +
+           'strictPricedPaths: false if these routes have no human visitors.');
     this.confirmHuman = opts.confirmHuman || null;
 
     // x-forwarded-for is written by the client unless a proxy you control
@@ -516,17 +611,29 @@ export class Wayleave {
 
   /** req: { method, path, authority, headers, ip } → decision */
   handle(req, now = Math.floor(Date.now() / 1000), paymentProof = '') {
-    const c = classify(req, this.directories, now,
-                       { verifyAgentIP: this.verifyAgentIP, ip: this._client(req) });
+    /* A remote policy is a signed document fetched over the network, so a
+       synchronous call cannot evaluate one. Silence here would mean an
+       operator's rules quietly not applying; say it once, loudly, rather than
+       let them believe a policy is in force that is not. */
+    if (this.policy && !this._warnedSyncPolicy) {
+      this._warnedSyncPolicy = true;
+      this._onWarn('[wayleave] handle() cannot evaluate a remote policy — verifying a ' +
+                   'signed document is asynchronous, so your policy rules are NOT being ' +
+                   'applied here. Use handleAsync(); gate.express() already does.');
+    }
+    const path = requestPath(req);
+    const r = this._withPath(req, path);
+    const c = classify(r, this.directories, now,
+                       { verifyAgentIP: this.verifyAgentIP, ip: this._client(r) });
     const { lane, agentId, evidence } = c;
-    const ident = agentId || `${lane}:${this._client(req)}`;
+    const ident = agentId || `${lane}:${this._client(r)}`;
     const proof = paymentProof || headerValue(req.headers, 'x-payment-proof');
-    const d = this._decide(req, lane, ident, now, proof, c);
+    const d = this._decide(r, lane, ident, now, proof, c);
     // 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,
+                    t: now, path, lane, identity: ident,
                     status: d.status, why: d.why, evidence,
                     billedUsd: d.billed || 0 };
     if (d.paymentRef) entry.paymentRef = d.paymentRef;
@@ -569,15 +676,17 @@ export class Wayleave {
   }
 
   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 path = requestPath(req);
+    const r = this._withPath(req, path);
+    const c = classify(r, this.directories, now,
+                       { verifyAgentIP: this.verifyAgentIP, ip: this._client(r) });
     const { lane, agentId, evidence } = c;
-    const ident = agentId || `${lane}:${this._client(req)}`;
+    const ident = agentId || `${lane}:${this._client(r)}`;
     const proof = paymentProof || headerValue(req.headers, 'x-payment-proof');
-    const fromPolicy = await this._policyDecision(req, lane, ident, c);
-    const d = fromPolicy || await this._decideAsync(req, lane, ident, now, proof, c);
+    const fromPolicy = await this._policyDecision(r, lane, ident, c);
+    const d = fromPolicy || await this._decideAsync(r, lane, ident, now, proof, c);
     const entry = { v: 1, idempotencyKey: `${this._instance}:${this._seq++}`,
-                    t: now, path: req.path, lane, identity: ident,
+                    t: now, path, lane, identity: ident,
                     status: d.status, why: d.why, evidence,
                     billedUsd: d.billed || 0 };
     if (d.paymentRef) entry.paymentRef = d.paymentRef;
@@ -631,7 +740,7 @@ export class Wayleave {
    */
   _preDecide(req, lane, ident, now, paymentProof, c) {
     for (const [prefix, allow] of this.rules[lane] || []) {
-      if (req.path.startsWith(prefix)) {
+      if (pathUnder(req.path, prefix)) {
         if (!allow) return { status: 403, why: `${lane} denied on ${prefix}` };
         break;
       }
@@ -659,7 +768,7 @@ export class Wayleave {
       : lane === LANES.HUMAN;
     if (!freeOnPriced) {
       for (const [prefix, price] of Object.entries(this.pricedPaths)) {
-        if (req.path.startsWith(prefix)) {
+        if (pathUnder(req.path, prefix)) {
           const challenge = { scheme: 'x402', price_usd: price, resource: prefix };
           if (!paymentProof) {
             const why = this.strictPricedPaths && lane === LANES.HUMAN
@@ -752,6 +861,21 @@ export class Wayleave {
   /** Stop polling. Safe to call when no remote policy is configured. */
   close() { this.policy?.stop(); this.registry?.stop(); }
 
+  /**
+   * The caller's request, seen with a `path` on it.
+   *
+   * Built with Object.create so the original is never mutated and never
+   * copied: a framework's request object owns sockets, streams and getters,
+   * and cloning one is a good way to break something far from here. Reads
+   * fall through to the real request; only `path` is ours.
+   */
+  _withPath(req, path) {
+    if (!req || typeof req !== 'object' || req.path === path) return req;
+    try {
+      return Object.create(req, { path: { value: path, enumerable: true, configurable: true } });
+    } catch { return req; }
+  }
+
   /**
    * Evaluate the fetched policy for one request.
    *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wayleave",
-  "version": "0.5.1",
-  "description": "Know which AI agents cross your API — verified by signature, not guessed from an IP. Sorts every request into four lanes, prices the non-human ones with HTTP 402, and never charges a human. Zero dependencies.",
+  "version": "0.5.3",
+  "description": "Know which AI agents cross your API \u2014 verified by signature, not guessed from an IP. Sorts every request into four lanes, prices the non-human ones with HTTP 402, and never charges a human. Zero dependencies.",
   "type": "module",
   "main": "index.js",
   "types": "./index.d.ts",

package/policy.js

@@ -114,9 +114,33 @@ export class RemotePolicy {
    * @param {(e:object)=>void} [o.onEvent] observability; never throws into us
    */
   constructor({ apiKey = null, url = null, publicKey = null, endpoint = DEFAULT_ENDPOINT,
-                refreshMs = DEFAULT_REFRESH_MS, graceMs = 0,
+                refreshMs = DEFAULT_REFRESH_MS, graceMs = 0, allowUnsigned = false,
                 cachePath = null, onEvent = null, onChange = null, fetchImpl = null } = {}) {
     if (!apiKey && !url) throw new Error('RemotePolicy requires a policy url (or the meter apiKey)');
+    /* A policy document decides who is allowed through and what they are
+       charged. Applying one nobody signed means whoever can answer that URL
+       — a hijacked CDN, a DNS answer, anyone on the path — writes your access
+       rules. Until 0.5.2 a missing publicKey silently skipped the check.
+
+       The requirement applies to a bare `url` only. With `apiKey` the document
+       comes from the customer's own meter over TLS with their key, which is an
+       authenticated channel; the signature is defence in depth there, not the
+       only defence. A public policy URL has no such channel — being publicly
+       cacheable is the point of it — so the signature IS the authentication.
+
+       Refusing at construction rather than at fetch time is deliberate: the
+       failure belongs at startup, where someone is watching, not on a poll at
+       three in the morning. `allowUnsigned: true` remains for a URL you trust
+       end to end, and it has to be written down. */
+    if (url && !apiKey && !publicKey && !allowUnsigned)
+      throw new Error(
+        'RemotePolicy requires publicKey: an unsigned policy document is an ' +
+        'unauthenticated one, and it decides access and pricing. Pass the ' +
+        'signing key, or allowUnsigned: true if you genuinely trust this URL.');
+    this.allowUnsigned = allowUnsigned;
+    // True only for a bare public URL, where the signature is the only
+    // thing authenticating the document.
+    this._needsSignature = Boolean(url) && !apiKey;
     this.apiKey = apiKey;
     this.publicKey = publicKey;
     this.graceMs = graceMs;
@@ -186,6 +210,11 @@ export class RemotePolicy {
         const v = verifyEnvelope(raw, this.publicKey, { graceMs: this.graceMs });
         if (!v.ok) { this._emit('policy.rejected', { why: v.reason }); return this.document; }
         doc = v.policy;
+      } else if (this._needsSignature && !this.allowUnsigned) {
+        // Unreachable via the constructor, which refuses this combination.
+        // Kept because the field is public and a caller may clear it.
+        this._emit('policy.rejected', { why: 'no signing key configured' });
+        return this.document;
       }
       if (!isUsable(doc)) { this._emit('policy.rejected', { why: 'document not usable' }); return this.document; }