wayleave 0.5.3 → 0.5.5

package/README.md

@@ -25,7 +25,7 @@ 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.
 
-## Two ways to use it
+## Three ways to use it
 
 **1. The hosted Identity API — no install, any language.** Post a request's
 signature headers and get back who signed it and which lane it belongs in.
@@ -54,6 +54,25 @@ way to know which to believe.
 you do not send. This is the path if you want to price routes, enforce access
 rules, or stay in-process. Start below.
 
+**3. A platform adapter — if your code does not run on Node.** This package is
+Express middleware and Node's crypto; it cannot run on a Worker or a Deno
+edge function. These can, share one policy engine with it, and are configured
+the same way:
+
+| Where you run | Install |
+|---|---|
+| Cloudflare Workers | [`@wayleave/cloudflare`](https://www.npmjs.com/package/@wayleave/cloudflare) |
+| Vercel middleware | [`@wayleave/vercel`](https://www.npmjs.com/package/@wayleave/vercel) |
+| Supabase Edge Functions | [`@wayleave/supabase`](https://www.npmjs.com/package/@wayleave/supabase) |
+| Netlify Edge Functions | [`@wayleave/netlify`](https://www.npmjs.com/package/@wayleave/netlify) |
+| An MCP server | [`@wayleave/mcp`](https://www.npmjs.com/package/@wayleave/mcp) |
+
+All four HTTP adapters default to observe mode and fail open, exactly as this
+one does. The MCP guard is the odd one: an MCP server has no HTTP request to
+inspect and MCP clients carry no signatures, so it does not classify lanes at
+all — it bounds tool calls by rate, budget and repetition instead, and says
+`classification: "unknown"` rather than guessing.
+
 ## Quickstart: observe first
 
 ```sh

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';
 
@@ -344,7 +344,18 @@ export function classify(req, directories, now, opts = {}) {
   if (h['signature'] || h['signature-input'])
     return { lane: LANES.SUSPECT, agentId: null,
              evidence: [`crypto: ${v.reason}`, 'presented invalid signature'] };
-  if (AGENT_UA.some(p => p.test(ua))) {
+  /* WHICH pattern matched, not merely that one did.
+     
+     This used to be `.some(...)`, and the evidence then quoted the first 40
+     characters of the user-agent. Almost every bot UA opens with a Mozilla
+     compatibility preamble and names itself at the END, so the quote cut off
+     exactly where the identifying part began: 486 crossings on one site all
+     recorded as `mozilla/5.0 applewebkit/537.36 (khtml, l`, indistinguishable
+     from each other and from a browser.
+     
+     The matched pattern is the name. It was in hand and discarded. */
+  const agentMatch = AGENT_UA.map(p => (p.exec(ua) || [])[0]).find(Boolean);
+  if (agentMatch) {
     // A UA naming a known operator is a claim, and claims are checkable when
     // the operator publishes its addresses. Claiming to be GPTBot from an
     // address OpenAI does not own is a stronger fraud signal than saying
@@ -356,10 +367,10 @@ export function classify(req, directories, now, opts = {}) {
       : null;
     if (ipOk === false)
       return { lane: LANES.SUSPECT, agentId: null,
-               evidence: [`UA claims "${ua.slice(0, 40)}"`,
+               evidence: [`UA claims "${agentMatch}"`,
                           `but ${opts.ip || 'the client'} is not a published address for it`] };
     return { lane: LANES.DECLARED, agentId: null,
-             evidence: [`self-identified in UA: "${ua.slice(0, 40)}"`,
+             evidence: [`self-identified as "${agentMatch}"`,
                         ipOk === true ? 'source address matches published range'
                                       : 'no signature presented'] };
   }
@@ -611,16 +622,6 @@ export class Wayleave {
 
   /** req: { method, path, authority, headers, ip } → decision */
   handle(req, now = Math.floor(Date.now() / 1000), paymentProof = '') {
-    /* 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,
@@ -628,7 +629,11 @@ export class Wayleave {
     const { lane, agentId, evidence } = c;
     const ident = agentId || `${lane}:${this._client(r)}`;
     const proof = paymentProof || headerValue(req.headers, 'x-payment-proof');
-    const d = this._decide(r, 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.
@@ -690,6 +695,10 @@ export class Wayleave {
                     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 };
   }
@@ -887,24 +896,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.3",
+  "version": "0.5.5",
   "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() {