wayleave 0.5.2 → 0.5.4

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

@@ -23,7 +23,7 @@ import { createPublicKey, verify as edVerify, sign as edSign,
 // nothing measurable and makes `meter: { apiKey }` work without ceremony.
 import { MeterSink } from './meter.js';
 import { RemotePolicy } from './policy.js';
-import { evaluatePolicy } from './policy-engine.js';
+import { evaluatePolicy, evaluatePolicySync } from './policy-engine.js';
 import { Registry } from './registry.js';
 import { ManifestServer, MANIFEST_PATHS, originFor, paymentRequirementsFor } from './manifest.js';
 
@@ -113,8 +113,34 @@ function sigBase(components, ctx, paramsRaw) {
  * 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 + '/');
@@ -264,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'],
@@ -482,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
@@ -541,17 +611,23 @@ 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) });
+    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);
+    /* The same policy the async path enforces, evaluated here for every rule
+       that needs no I/O. Before this, `handle()` skipped policy entirely and
+       one document behaved as two: enforced through express(), ignored here. */
+    const fromPolicy = this._policyDecisionSync(r, lane, ident, c);
+    const d = fromPolicy || 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;
@@ -594,18 +670,24 @@ 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;
+    // The sync path recorded this and the async path did not, so a policy
+    // denial arrived at the meter with no rule on it — unanswerable when the
+    // operator asks which rule refused a request.
+    if (d.ruleId) entry.ruleId = d.ruleId;
     this.sink.emit(entry);
     return { lane, identity: ident, ...d, evidence };
   }
@@ -777,6 +859,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.
    *
@@ -788,24 +885,74 @@ export class Wayleave {
    * Returns null when there is no policy, or when it says allow -- in both
    * cases the gate's local configuration decides, as it always did.
    */
-  async _policyDecision(req, lane, ident, c) {
+  /**
+   * The policy decision that needs no network.
+   *
+   * Everything the async path does, minus quota — consuming from a quota
+   * store is I/O and cannot happen inside a synchronous call. A quota rule
+   * reached here is NOT passed over: passing it would let through exactly the
+   * traffic the operator metered, which is worse than refusing. It answers
+   * the way the async path answers when the store cannot be consulted, and
+   * says which call to use instead.
+   */
+  _policyDecisionSync(req, lane, ident, c) {
     const policy = this.policy?.document;
     if (!policy) return null;
-    const identity = c?.agentId && c.lane === 'verified_agent'
+    let d;
+    try {
+      d = evaluatePolicySync(policy, {
+        tenant: this.policy.tenant || 'self',
+        path: req.path, method: req.method, lane,
+        identity: this._policyIdentity(c), anonymousBucket: ident,
+      });
+    } catch (err) {
+      this.onEvent({ type: 'policy.evaluate.failed', error: err?.message });
+      return null;                                    // traffic fails open
+    }
+    if (d.action === 'needs-async') {
+      if (!this._warnedSyncQuota) {
+        this._warnedSyncQuota = true;
+        this._onWarn('[wayleave] a quota rule was reached through handle(), which cannot ' +
+                     'consult a quota store. The request was refused rather than passed. ' +
+                     'Use handleAsync(); gate.express() already does.');
+      }
+      return { status: 403, why: 'quota rule requires handleAsync', ruleId: d.ruleId,
+               headers: { 'x-wayleave-rule': String(d.ruleId) } };
+    }
+    return this._fromPolicyAction(d, req);
+  }
+
+  /** The identity shape the engine expects, from a classification. */
+  _policyIdentity(c) {
+    return c?.agentId && c.lane === 'verified_agent'
       ? { verified: true, subject: c.agentId, operator: c.operator || undefined }
       : { verified: false };
+  }
+
+  async _policyDecision(req, lane, ident, c) {
+    const policy = this.policy?.document;
+    if (!policy) return null;
     let d;
     try {
       d = await evaluatePolicy(policy, {
         tenant: this.policy.tenant || 'self',
         path: req.path, method: req.method, lane,
-        identity, anonymousBucket: ident,
+        identity: this._policyIdentity(c), anonymousBucket: ident,
       }, { quotaStore: this.quotaStore });
     } catch (err) {
       // A policy we cannot evaluate must not break the request. Traffic fails open.
       this.onEvent({ type: 'policy.evaluate.failed', error: err?.message });
       return null;
     }
+    return this._fromPolicyAction(d, req);
+  }
+
+  /**
+   * One translation from an engine action to a gate decision, used by both
+   * paths. Two copies of this is how a deny becomes a 403 on one path and a
+   * 429 on the other for the same rule.
+   */
+  _fromPolicyAction(d, req) {
     if (d.action === 'allow') return null;
     if (d.action === 'deny')
       return { status: 403, why: d.reason || `denied by rule ${d.ruleId || 'default'}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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",
@@ -27,6 +27,9 @@
     },
     "./manifest": {
       "default": "./manifest.js"
+    },
+    "./policy-engine": {
+      "default": "./policy-engine.js"
     }
   },
   "files": [

package/policy-engine.js

@@ -12,6 +12,20 @@
  * from the meter. policy-engine.parity.test.js asserts the two files match.
  * ───────────────────────────────────────────────────────────────────────
  */
+/* Documents that have already been through validatePolicy.
+   
+   A WeakSet, so remembering a document cannot keep it alive: entries vanish
+   when the policy is replaced by the next fetch. The point is that a policy
+   is validated once, when it arrives, and not again on every request that
+   consults it -- a hot path doing full schema validation per crossing is
+   work nobody asked for, repeated forever. */
+const VALIDATED = new WeakSet();
+
+/** True when this exact object has already been validated. */
+export function isValidated(policy) {
+  return typeof policy === 'object' && policy !== null && VALIDATED.has(policy);
+}
+
 export function validatePolicy(policy) {
   if (!policy || typeof policy.version !== 'string' || !policy.version || !Array.isArray(policy.rules) || policy.rules.length > 100) throw new Error('Version and at most 100 rules required');
   if (!['allow','deny'].includes(policy.default)) throw new Error('Explicit default required');
@@ -33,10 +47,25 @@ export function validatePolicy(policy) {
     if (r.action === 'pay' && (!Number.isSafeInteger(r.priceMicros) || r.priceMicros <= 0 || typeof r.rail !== 'string' || !r.rail)) throw new Error('Payment requires positive integer USD micros and rail');
     if ((r.action === 'quota' || r.action === 'allowance') && (!r.quota || !Number.isSafeInteger(r.quota.limit) || r.quota.limit < 1 || !Number.isSafeInteger(r.quota.windowSeconds) || r.quota.windowSeconds < 1)) throw new Error('Invalid quota');
   }
+  VALIDATED.add(policy);
   return policy;
 }
-export async function evaluatePolicy(policy, context, { quotaStore } = {}) {
-  validatePolicy(policy);
+/**
+ * Everything both evaluators need before either can decide anything.
+ *
+ * Extracted so the matching rules exist once. Two copies of "does this rule
+ * apply" is how a sync path and an async path quietly begin enforcing
+ * different policies from the same document — which is the bug this file
+ * already had between the gate and the meter, and is not worth reproducing
+ * inside a single file.
+ */
+function prepare(policy, context) {
+  /* Validated once, when the document arrived — not again here. A caller
+     handing over a document nobody has checked still gets it checked, because
+     evaluating an unvalidated policy is how a malformed rule becomes a wrong
+     decision. But the normal path, where the fetcher validated it before it
+     became the live document, does no schema work per request at all. */
+  if (!isValidated(policy)) validatePolicy(policy);
   if (typeof context.tenant !== 'string' || !context.tenant || typeof context.path !== 'string') throw new Error('Trusted tenant and path required');
   const identity = context.identity?.verified === true ? context.identity : null;
   const matches = r =>
@@ -47,6 +76,44 @@ export async function evaluatePolicy(policy, context, { quotaStore } = {}) {
     (r.verified === undefined || r.verified === !!identity) &&
     (r.subject === undefined || r.subject === identity?.subject) &&
     (r.operator === undefined || r.operator === identity?.operator);
+  return { identity, matches };
+}
+
+/** A rule that needs no I/O to answer. Shared by both evaluators. */
+function plainDecision(r, base) {
+  return r.action === 'pay'
+    ? { ...base, action: 'pay', priceMicros: r.priceMicros, currency: 'USD', rail: r.rail }
+    : { ...base, action: r.action };
+}
+
+/**
+ * Evaluate without touching the quota store.
+ *
+ * `handle()` is synchronous, so it could not evaluate a policy at all — and
+ * simply did not. The same document enforced through `express()` and was
+ * ignored through `handle()`, which is one policy behaving as two.
+ *
+ * Everything needing no I/O is decided here: allow, deny, pay, and the
+ * default. A quota or allowance rule cannot be, because consuming from the
+ * store is a network or database call. Rather than skip such a rule — which
+ * would silently pass exactly the traffic the operator metered — it stops and
+ * says so, and the caller can use handleAsync() or treat the answer as the
+ * refusal it is.
+ */
+export function evaluatePolicySync(policy, context) {
+  const { matches } = prepare(policy, context);
+  for (const r of policy.rules) {
+    if (!matches(r)) continue;
+    const base = { policyVersion: policy.version, ruleId: r.id };
+    if (r.action === 'quota' || r.action === 'allowance')
+      return { ...base, action: 'needs-async', reason: 'quota rule requires handleAsync' };
+    return plainDecision(r, base);
+  }
+  return { policyVersion: policy.version, ruleId: null, action: policy.default };
+}
+
+export async function evaluatePolicy(policy, context, { quotaStore } = {}) {
+  const { identity, matches } = prepare(policy, context);
   // An exhausted allowance does not answer the request; it steps aside for the
   // rule behind it. Carried so the eventual answer can say why it was reached.
   let spent = null;
@@ -73,7 +140,7 @@ export async function evaluatePolicy(policy, context, { quotaStore } = {}) {
       if (allowed === true) return { ...base, action: 'allow', reason: 'Within free allowance' };
       spent = 'Free allowance exhausted'; continue;
     }
-    return r.action === 'pay' ? { ...base, action: 'pay', priceMicros: r.priceMicros, currency: 'USD', rail: r.rail } : { ...base, action: r.action };
+    return plainDecision(r, base);
   }
   // A route the operator metered never falls back to a permissive default.
   if (spent) return { policyVersion: policy.version, ruleId: null, action: 'deny', reason: spent };

package/policy.js

@@ -20,6 +20,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { verify as edVerify, createPublicKey } from 'node:crypto';
+import { validatePolicy } from './policy-engine.js';
 
 const DEFAULT_ENDPOINT = 'https://meter.wayleave.dev';
 const DEFAULT_REFRESH_MS = 5 * 60_000;
@@ -216,7 +217,13 @@ export class RemotePolicy {
         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; }
+      const check = usable(doc);
+      if (!check.ok) {
+        // The last good policy stays in force. A bad publish must not
+        // silently disarm a gate that was working a second ago.
+        this._emit('policy.rejected', { why: check.why, version: doc?.version ?? null });
+        return this.document;
+      }
 
       this.document = doc;
       this.etag = res.headers.get?.('etag') ?? null;
@@ -237,7 +244,12 @@ export class RemotePolicy {
   async _loadCache() {
     try {
       const raw = JSON.parse(await readFile(this.cachePath, 'utf8'));
-      if (raw?.url === this.url && isUsable(raw.document)) {
+      /* The cache is a file on disk, which means it is a file somebody or
+         something else can edit. It gets the same full validation a freshly
+         fetched document gets -- and it has to, because this is the copy that
+         enforces on the very first request after a restart, before any fetch
+         has completed. */
+      if (raw?.url === this.url && usable(raw.document).ok) {
         this.document = raw.document;
         this.etag = null;   // revalidate against the server, not against disk
         this._emit('policy.cache.loaded', { version: raw.document.version });
@@ -259,9 +271,26 @@ export class RemotePolicy {
 }
 
 /** A document we can act on: right shape, explicit default, sane rule count. */
-function isUsable(doc) {
-  return !!doc && Array.isArray(doc.rules) && doc.rules.length <= 100
-      && (doc.default === 'allow' || doc.default === 'deny');
+/**
+ * Whether a fetched document may become the live policy.
+ *
+ * Full schema validation, here, once — not the shallow shape check this used
+ * to be. Two things follow from doing it at the door rather than per request:
+ * a document with a malformed rule never becomes live at all (the last good
+ * copy stays, which is the whole point of caching one), and the evaluator
+ * does no validation work on the hot path because the document it is handed
+ * has already passed.
+ *
+ * Returns a reason rather than a boolean, because "document not usable" told
+ * an operator nothing about which rule was wrong.
+ */
+function usable(doc) {
+  try {
+    validatePolicy(doc);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, why: err.message };
+  }
 }
 
 function defaultCachePath() {