wayleave 0.4.1 → 0.5.1

package/README.md

@@ -4,9 +4,11 @@
 [![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)
 
-**Observe agent traffic. Control access. Charge payment-ready agents.**
+**Know which AI agents cross your API — verified by signature, not guessed from an IP.**
 
-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.
+Wayleave is open-source middleware that classifies every request, verifies signed agents against a key
+directory, applies the access rules you set, and prices the non-human traffic with HTTP 402. Humans are
+never charged. The [hosted Meter](https://meter.wayleave.dev) records what crossed and what settled.
 
 Zero dependencies. Node's native crypto only. TypeScript declarations included.
 
@@ -23,6 +25,35 @@ 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
+
+**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.
+Nothing is stored, and your traffic never routes through us.
+
+```sh
+curl -X POST https://api.wayleave.dev/v1/identify \
+  -H "Authorization: Bearer $WAYLEAVE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"method":"GET","url":"https://api.yourapp.com/v1/data",
+       "headers":{"user-agent":"...","signature":"...","signature-input":"..."},
+       "client_ip":"203.0.113.7"}'
+```
+
+```json
+{ "lane": "verified_agent", "verified": true,
+  "identity": { "keyid": "k1", "operator": "Example Labs" },
+  "signature": { "present": true, "valid": true, "reason": null } }
+```
+
+The same evaluator answers here and in the middleware, and a test asserts they
+agree — if the two front doors disagreed about one request you would have no
+way to know which to believe.
+
+**2. The middleware — in your own process.** Nothing leaves your server that
+you do not send. This is the path if you want to price routes, enforce access
+rules, or stay in-process. Start below.
+
 ## Quickstart: observe first
 
 ```sh
@@ -88,6 +119,61 @@ 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.
 
+## Enforce rules you set elsewhere
+
+> Requires 0.5.0 or later, which is what `npm install wayleave` now gives you.
+
+A policy the gate fetches, rather than configuration compiled into your app:
+
+```js
+const gate = new Wayleave({
+  policy: { url: 'https://meter.wayleave.dev/v1/policy/public/<id>.json',
+            publicKey: WAYLEAVE_ROOT_KEY },
+});
+await gate.ready();
+app.use(gate.express());
+```
+
+Fetched on a timer and evaluated from memory — never a network call inside a request. A denial
+returns `403` with `x-wayleave-rule: <ruleId>`; a quota denial returns `429` with `Retry-After`.
+
+The document is signed, which is the only reason the URL can be public. A CDN, or anyone on the
+path, can serve whatever it likes and the gate refuses the bytes.
+
+**If we are unreachable, your traffic is unaffected.** Last cached policy; with no cache, the gate
+behaves exactly as if no policy were configured. That is tested five ways, and the cold-start case is
+asserted by comparing against a gate constructed with no policy at all.
+
+## Be found by the agents that can pay
+
+A priced route nothing can discover earns nothing. Every install with `pricedPaths` serves a
+manifest derived from your own configuration:
+
+```js
+new Wayleave({
+  pricedPaths: { '/api/premium': 0.05 },
+  payment: { payTo: '0xYourAddress', network: 'base' },
+  publicOrigin: 'https://api.example.com',
+});
+```
+
+```sh
+curl https://api.example.com/.well-known/x402
+```
+
+No priced routes, or `manifest: false`, returns 404 — an empty manifest tells an index there is
+nothing to buy here, which is a claim.
+
+Use `gate.paymentRequirements(req)` to build your 402 body. It returns the same spec-shaped entry the
+manifest advertises, so the two cannot disagree about the price.
+
+Three details that decide whether an index reads you at all, all verified against the spec rather
+than assumed: the path is `/.well-known/x402` (not `.json`), `asset` is the **token contract
+address** rather than a symbol, and `maxTimeoutSeconds` is required. Note that the merged x402
+specification has no well-known discovery document — this is a
+[proposed extension](https://datatracker.ietf.org/doc/html/draft-hawkins-x402-dns-discovery-01)
+that tooling in the wild does fetch.
+
 ## 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.
@@ -95,20 +181,46 @@ rather than quietly denying every payment.
 - 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.
 - 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.
+- Key rotation has an implementation now: `directories: 'wayleave:default'` fetches a signed directory on a timer and resolves from memory, and you can still pass your own resolver function instead. The resolver must not block; that constraint has not moved. The bundled registry currently lists no operators — an empty directory resolves nothing rather than everything, so it changes no decision until it has entries.
 - **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.
 - Wayleave prices **disclosure**; it does not detect **concealment**. It is a tollbooth, not a wall — it works on operators who want to be identifiable, which today is most of the ones worth billing.
 - This is a **screening and pricing layer, not a guarantee**. Every decision returns its evidence and is loggable.
 
 ## Status
 
-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.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).
+v0.5.0 — 155 tests, zero dependencies. Published on npm.
+
+**0.5.0** does three things. Rules you set are now *enforced*: `policy: { url, publicKey }` fetches a
+signed policy, verifies it, caches it, and evaluates per request — denials carry the rule id in
+`x-wayleave-rule`, and a quota denial is 429 with `Retry-After`. `directories: 'wayleave:default'`
+resolves agent keys from a signed directory. And every install with a priced route now serves
+`/.well-known/x402`, so discovery indexes can find it.
+
+The property worth testing for yourself: **a Wayleave outage cannot break your API.** Unreachable,
+500, unparseable, wrong signature — each keeps the last good policy, and with no cache at all the
+gate behaves exactly as if no policy were configured. Money is the opposite law and fails closed: an
+unreachable rail is a 402, never free passage on a priced route.
+
+That claim is not only unit-tested. `acceptance-policy.test.js` drives the real meter over a socket
+and this gate fetching over HTTP with a real Ed25519 signature: a rule is set and enforced, changed
+and re-enforced, a forged document is refused, and the service is then killed while traffic keeps
+flowing. The same run against production on 2026-09-22 found a bug no local test had — the public
+policy URL advertised an ETag and ignored `if-none-match`, so every poll re-sent and re-signed the
+whole document. Fixed and covered.
+
+**0.4.1** fixed a rail that could never settle. Two required fields were missing from every request
+the x402 module made — `asset`, and the EIP-712 domain in `extra` — so the documented configuration
+would have failed for anyone who tried it. Found by settling a real payment, not by reading the code.
+If you were running the Coinbase rail before 0.4.1 and saw nothing settle, that is why.
+
+**0.1.5** closed a hole worth naming: a priced route accepted a payment proof any agent could derive
+from the 402 challenge it had just been sent — free passage, recorded as revenue. Settlement
+confirmation is yours to supply and denies by default. If you shipped 0.1.4 or earlier on a priced
+route, upgrade.
+
+**0.1.6** addressed the other half: payment could be faked, and so could being human.
+`strictPricedPaths` lets a priced route demand positive evidence rather than accepting the absence of
+a bot signal as one.
 
 ## How payment actually works
 

package/index.js

@@ -22,6 +22,10 @@ import { createPublicKey, verify as edVerify, sign as edSign,
 // Same package, zero dependencies, ~9KB. Importing it unconditionally costs
 // 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 { Registry } from './registry.js';
+import { ManifestServer, MANIFEST_PATHS, originFor, paymentRequirementsFor } from './manifest.js';
 
 export const LANES = Object.freeze({
   VERIFIED: 'verified_agent',
@@ -411,11 +415,34 @@ export class Wayleave {
    * }
    */
   constructor(opts = {}) {
-    this.directories = opts.directories || {};
+    // `directories: 'wayleave:default'` resolves to the signed public registry.
+    // The verification path below does not change: asResolver() already accepts
+    // a function, and this supplies one backed by a document fetched on a timer
+    // and resolved from memory.
+    if (opts.directories === 'wayleave:default' || opts.registry) {
+      this.registry = new Registry({
+        onEvent: opts.onEvent,
+        ...(typeof opts.registry === 'object' ? opts.registry : {}),
+      });
+      this.directories = this.registry.resolver();
+    } else {
+      this.registry = null;
+      this.directories = opts.directories || {};
+    }
     this.rules = opts.rules || {};
     this.rateLimits = opts.rateLimits || {};
     this.rateWindow = opts.rateWindow || 60;
     this.pricedPaths = opts.pricedPaths || {};
+
+    // Discovery. Default on when there is something to discover, because a
+    // priced route nothing can find earns nothing.
+    this.publicOrigin = opts.publicOrigin || null;
+    this.manifestEnabled = opts.manifest !== false && Object.keys(this.pricedPaths).length > 0;
+    this.manifests = this.manifestEnabled
+      ? new ManifestServer({ pricedPaths: this.pricedPaths, payment: opts.payment || {},
+                             name: opts.name, description: opts.description,
+                             docs: opts.docs, contact: opts.contact })
+      : null;
     this.onEvent = opts.onEvent || (() => {});
 
     // No payment verifier configured means no agent can ever buy passage.
@@ -466,6 +493,23 @@ export class Wayleave {
     // Identifies events from this process so a retrying sink can dedup. A
     // counter alone would collide across instances; a timestamp alone would
     // collide within a millisecond.
+    // What the developer configured here is the floor and never moves. A
+    // policy fetched from the meter is layered ON TOP, so if our service is
+    // unreachable -- or returns nothing at all -- the gate still enforces
+    // exactly what this constructor was given.
+    this._localRules = this.rules;
+    this._localRateLimits = this.rateLimits;
+    this._localPricedPaths = this.pricedPaths;
+
+    this.quotaStore = opts.quotaStore || null;
+    this.policy = opts.policy
+      ? new RemotePolicy({
+          ...opts.policy,
+          onEvent: this.onEvent,
+          onChange: compiled => this._applyPolicy(compiled),
+        })
+      : null;
+
     this._instance = randomUUID();
     this._seq = 0;
   }
@@ -486,6 +530,7 @@ export class Wayleave {
                     status: d.status, why: d.why, evidence,
                     billedUsd: d.billed || 0 };
     if (d.paymentRef) entry.paymentRef = d.paymentRef;
+    if (d.ruleId) entry.ruleId = d.ruleId;
     this.sink.emit(entry);
     return { lane, identity: ident, ...d, evidence };
   }
@@ -496,13 +541,41 @@ export class Wayleave {
    * Identical in every respect except that it can await your verifyPayment.
    * Use this whenever you actually sell something; the Express adapter does.
    */
+  /**
+   * The discovery document, if this request is asking for it.
+   *
+   * Checked before classification so it is never metered, never rate-limited
+   * and never priced. A paywalled discovery document cannot be discovered.
+   */
+  /**
+   * Spec-shaped payment requirements for a priced path, or null.
+   *
+   * Use this to build a 402 body. The alternative is every application
+   * inventing its own translation of the internal challenge, and getting it
+   * wrong the same way once each.
+   */
+  paymentRequirements(req) {
+    if (!this.manifests) return null;
+    const origin = originFor(req, this.publicOrigin);
+    return origin ? paymentRequirementsFor(this.manifests.forOrigin(origin), req.path) : null;
+  }
+
+  manifestFor(req) {
+    if (!this.manifests || !MANIFEST_PATHS.includes(req.path)) return null;
+    const origin = originFor(req, this.publicOrigin);
+    if (!origin) return null;
+    const body = this.manifests.forOrigin(origin);
+    return body ? { status: 200, body, headers: { 'content-type': 'application/json' } } : null;
+  }
+
   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 fromPolicy = await this._policyDecision(req, lane, ident, c);
+    const d = fromPolicy || 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,
@@ -662,8 +735,87 @@ export class Wayleave {
   }
 
   /** Express/Connect adapter: app.use(wayleave.express()) */
+  /**
+   * Start polling for a remote policy. Awaiting this is optional: skip it and
+   * the gate enforces its local configuration until the first refresh lands.
+   * It never rejects, because a gate that will not boot when our service is
+   * down is worse than one that enforces nothing.
+   */
+  async ready() {
+    // Neither rejects. A gate that will not boot because our service is down
+    // is worse than one that enforces nothing.
+    if (this.registry) await this.registry.start();
+    if (this.policy) await this.policy.start();
+    return this;
+  }
+
+  /** Stop polling. Safe to call when no remote policy is configured. */
+  close() { this.policy?.stop(); this.registry?.stop(); }
+
+  /**
+   * Evaluate the fetched policy for one request.
+   *
+   * The context is built from the gate's OWN verification result. Nothing here
+   * comes from a header or body the caller controls: the engine only honours
+   * subject and operator selectors when identity.verified is true, and passing
+   * a caller's claims through would defeat exactly that check.
+   *
+   * 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) {
+    const policy = this.policy?.document;
+    if (!policy) return null;
+    const identity = c?.agentId && c.lane === 'verified_agent'
+      ? { verified: true, subject: c.agentId, operator: c.operator || undefined }
+      : { verified: false };
+    let d;
+    try {
+      d = await evaluatePolicy(policy, {
+        tenant: this.policy.tenant || 'self',
+        path: req.path, method: req.method, lane,
+        identity, 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;
+    }
+    if (d.action === 'allow') return null;
+    if (d.action === 'deny')
+      return { status: 403, why: d.reason || `denied by rule ${d.ruleId || 'default'}`,
+               ruleId: d.ruleId, headers: { 'x-wayleave-rule': String(d.ruleId || 'default') },
+               ...(d.reason === 'Quota exceeded'
+                    ? { status: 429, headers: { 'x-wayleave-rule': String(d.ruleId),
+                                                'retry-after': String(this.rateWindow) } }
+                    : {}) };
+    if (d.action === 'pay')
+      return { status: 402, why: `payment required by rule ${d.ruleId}`, ruleId: d.ruleId,
+               headers: { 'x-wayleave-rule': String(d.ruleId) },
+               challenge: { scheme: d.rail || 'x402', price_usd: d.priceMicros / 1e6,
+                            resource: req.path } };
+    return null;
+  }
+
+  /** Local configuration, untouched by any fetched policy. */
+  _applyPolicy() { /* policy is evaluated per request; nothing to compile */ }
+
   express() {
     return async (req, res, next) => {
+      /* The discovery document is answered first: before classification,
+         before rate limiting, before pricing. A manifest an agent must pay
+         to read cannot be discovered, and one that is classified as bot
+         traffic gets a 402 instead of the price list.
+
+         This lived only on manifestFor() until 0.5.1, so `app.use(gate.express())`
+         -- the integration the Quickstart shows -- served no manifest at all
+         while the README said every install with a priced route does. */
+      const manifest = this.manifestFor({
+        path: req.path || (req.url || '').split('?')[0],
+        headers: req.headers,
+      });
+      if (manifest) return res.status(manifest.status).set(manifest.headers).json(manifest.body);
+
       const r = await this.handleAsync({
         method: req.method, path: req.path || req.url,
         authority: req.headers.host || '',
@@ -678,10 +830,25 @@ export class Wayleave {
       }, undefined, req.headers['x-payment-proof'] || '');
       req.wayleave = r;
       if (r.status === 200) return next();
-      if (r.status === 402)
+      if (r.status === 402) {
+        /* The 402 body and the manifest must come from one source, or an
+           index quotes a price the origin does not honour. `accepts` is
+           built by the same call the manifest is, so they cannot drift.
+
+           Without a payment config there is nothing spec-shaped to say --
+           no payee, no network, no asset -- so the internal challenge is
+           all that is sent, and `accepts` is absent rather than empty.
+           An empty accepts array would read as "priced at nothing". */
+        const body = { error: r.why, challenge: r.challenge };
+        const requirements = this.paymentRequirements({
+          path: req.path || (req.url || '').split('?')[0],
+          headers: req.headers,
+        });
+        if (requirements) { body.x402Version = 1; body.accepts = [requirements]; }
         return res.status(402)
                   .set('x-payment-challenge', JSON.stringify(r.challenge))
-                  .json({ error: r.why, challenge: r.challenge });
+                  .json(body);
+      }
       return res.status(r.status).json({ error: r.why });
     };
   }

package/manifest.js

@@ -0,0 +1,163 @@
+/**
+ * Discovery manifest — E-1.
+ *
+ * The problem it solves: a developer installs the gate, prices a route, and
+ * nothing finds it. Agent discovery indexes register resources they can read a
+ * price for, so an unadvertised priced route is invisible to the exact agents
+ * that could pay it.
+ *
+ * ── WHAT THE SPEC ACTUALLY SAYS, as of 2026-09-18 ──────────────────────────
+ *
+ * The merged x402 specification has NO well-known discovery document. Its
+ * mechanism is the `bazaar` extension carried inside 402 responses, which a
+ * facilitator catalogs as it sees them (specs/extensions/bazaar.md).
+ *
+ * The well-known manifest is a PROPOSED extension: draft-hawkins-x402-dns-
+ * discovery-01, plus an open PR against the foundation repo. It is widely used
+ * in the wild — validators and index tooling fetch it — so it is worth serving,
+ * but it is a convention, not a ratified standard, and this comment is here so
+ * nobody later mistakes it for one.
+ *
+ * The path is `/.well-known/x402`. NOT `.json`: tooling that looks for the
+ * manifest requests the extensionless path, and a document served only at
+ * `.json` is a document nobody fetches. We answer both, because answering the
+ * alias costs nothing and a 404 costs a listing.
+ *
+ * Field names below were read from the draft and from
+ * specs/x402-specification-v1.md, not from memory. Two traps in particular:
+ *   - `asset` is the TOKEN CONTRACT ADDRESS, not a symbol like "usdc".
+ *   - `maxTimeoutSeconds` is REQUIRED in PaymentRequirements.
+ * An entry that gets either wrong is an entry an index silently skips, which
+ * is indistinguishable from not publishing at all.
+ */
+
+import { toAtomicUnits } from './x402.js';
+
+/** Networks whose USDC contract we have actually verified. See x402.js. */
+const KNOWN_ASSETS = {
+  'base': { asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', decimals: 6 },
+  'base-sepolia': { asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', decimals: 6 },
+};
+
+const DEFAULT_TIMEOUT_SECONDS = 60;
+
+/**
+ * Build the manifest from configuration. A pure function of `pricedPaths` and
+ * `payment`: there is no separate document to author, and therefore none to
+ * drift out of step with what the gate actually charges.
+ *
+ * Returns null when there is nothing honest to publish. An empty manifest is
+ * worse than no manifest — it tells an index there is nothing to buy here,
+ * which is a claim, and a false one.
+ */
+export function buildManifest({ pricedPaths = {}, payment = {}, origin,
+                                name, description, docs, contact,
+                                now = () => new Date() } = {}) {
+  const routes = Object.entries(pricedPaths);
+  if (!routes.length || !origin) return null;
+
+  const network = payment.network || 'base';
+  const known = KNOWN_ASSETS[network];
+  // An address we were given wins over our table; a symbol never does.
+  const asset = isAddress(payment.asset) ? payment.asset : known?.asset;
+  const decimals = Number.isInteger(payment.decimals) ? payment.decimals : known?.decimals;
+  const payTo = payment.payTo;
+
+  // Priceable only when we can name a real contract and a real payee. Without
+  // both, publish the resource without `accepts` rather than inventing fields:
+  // a wrong address is worse than a missing one.
+  const priceable = Boolean(asset && payTo && Number.isInteger(decimals));
+
+  const resources = routes.map(([path, priceUsd]) => {
+    const url = origin.replace(/\/+$/, '') + path;
+    const entry = { url, method: 'GET', description: 'x402-priced route' };
+    if (priceable) {
+      entry.accepts = [{
+        scheme: 'exact',
+        network,
+        maxAmountRequired: toAtomicUnits(String(priceUsd), decimals),
+        asset,
+        payTo,
+        resource: url,
+        description: 'x402-priced route',
+        mimeType: 'application/json',
+        maxTimeoutSeconds: payment.maxTimeoutSeconds || DEFAULT_TIMEOUT_SECONDS,
+      }];
+    }
+    return entry;
+  });
+
+  const manifest = {
+    // What we actually speak. The draft's example shows 2; advertising a
+    // version we do not implement would be a lie an index acts on.
+    x402Version: 1,
+    kind: 'resource-server',
+    name: name || hostOf(origin),
+    description: description || 'Paid routes served behind Wayleave.',
+    resources,
+    attestation: { type: 'none' },
+    updated: now().toISOString(),
+  };
+  if (docs) manifest.docs = docs;
+  if (contact) manifest.contact = contact;
+  return manifest;
+}
+
+const isAddress = v => typeof v === 'string' && /^0x[0-9a-fA-F]{40}$/.test(v);
+const hostOf = origin => { try { return new URL(origin).host; } catch { return 'wayleave resource server'; } };
+
+/**
+ * The x402 PaymentRequirements for one priced path.
+ *
+ * The gate's own `challenge` is an internal shape — `{scheme:'x402',
+ * price_usd, resource}` — which is fine for an application that speaks it and
+ * wrong for anything that validates against the x402 schema. An index reading
+ * that body skips the endpoint, silently, which is the same as never having
+ * published. Applications returning a 402 body should use this, so the 402 and
+ * the manifest cannot describe different prices.
+ */
+export function paymentRequirementsFor(manifest, path) {
+  if (!manifest) return null;
+  const entry = manifest.resources?.find(r => { try { return new URL(r.url).pathname === path; } catch { return false; } })
+    || manifest.resources?.find(r => r.url.endsWith(path));
+  return entry?.accepts?.[0] ?? null;
+}
+
+/** The canonical path and the alias we also answer. */
+export const MANIFEST_PATHS = ['/.well-known/x402', '/.well-known/x402.json'];
+
+/**
+ * Serve the manifest, computed once per origin and held.
+ *
+ * No I/O in the handler, and never priced: a discovery document behind a
+ * paywall cannot be discovered, which defeats its only purpose.
+ */
+export class ManifestServer {
+  #cache = new Map();
+  constructor(config) { this.config = config; }
+
+  /** Cached per origin, since the same install may answer on several hosts. */
+  forOrigin(origin) {
+    if (!this.#cache.has(origin))
+      this.#cache.set(origin, buildManifest({ ...this.config, origin }));
+    return this.#cache.get(origin);
+  }
+
+  /** Invalidate when configuration changes underneath us. */
+  reset(config) { if (config) this.config = config; this.#cache.clear(); }
+}
+
+/** Origin from the request, unless the app configured one explicitly. */
+export function originFor(req, publicOrigin) {
+  if (publicOrigin) return publicOrigin.replace(/\/+$/, '');
+  const host = headerish(req, 'x-forwarded-host') || headerish(req, 'host');
+  if (!host) return null;
+  const proto = headerish(req, 'x-forwarded-proto') || 'https';
+  return `${proto}://${host}`;
+}
+
+function headerish(req, name) {
+  const h = req?.headers || {};
+  const v = h[name] ?? h[name.toLowerCase()];
+  return Array.isArray(v) ? v[0] : (typeof v === 'string' ? v.split(',')[0].trim() : null);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wayleave",
-  "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.",
+  "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.",
   "type": "module",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -17,18 +17,33 @@
     "./x402": {
       "types": "./x402.d.ts",
       "default": "./x402.js"
+    },
+    "./policy": {
+      "types": "./policy.d.ts",
+      "default": "./policy.js"
+    },
+    "./registry": {
+      "default": "./registry.js"
+    },
+    "./manifest": {
+      "default": "./manifest.js"
     }
   },
   "files": [
     "LICENSE",
     "README.md",
+    "cdp-auth.js",
     "index.d.ts",
     "index.js",
+    "manifest.js",
     "meter.d.ts",
     "meter.js",
+    "policy-engine.js",
+    "policy.d.ts",
+    "policy.js",
+    "registry.js",
     "x402.d.ts",
-    "x402.js",
-    "cdp-auth.js"
+    "x402.js"
   ],
   "scripts": {
     "test": "node --test *.test.js"
@@ -38,16 +53,26 @@
   },
   "keywords": [
     "ai-agents",
+    "agent-identity",
+    "agent-traffic",
+    "bot-detection",
     "web-bot-auth",
     "rfc9421",
+    "http-message-signatures",
+    "ed25519",
     "402",
+    "http-402",
     "x402",
     "agent-payments",
-    "bot-detection",
+    "micropayments",
     "middleware",
     "express",
+    "connect",
+    "api-monetization",
     "monetization",
-    "ed25519"
+    "rate-limiting",
+    "access-control",
+    "zero-dependencies"
   ],
   "license": "MIT",
   "author": "Gibran Corbin (https://github.com/gibrancorbin11-hub)",

package/policy-engine.js

@@ -0,0 +1,81 @@
+/**
+ * The policy evaluator, evaluated IN THE GATE.
+ *
+ * ── THIS FILE IS A COPY ────────────────────────────────────────────────
+ * It must stay byte-identical in behaviour to src/policy-engine.js in the
+ * meter. The meter validates what it stores; the gate evaluates what it
+ * fetched. If the two ever disagree, a customer sees a rule accepted by the
+ * dashboard and ignored at their origin, which is the worst kind of wrong:
+ * it looks like it is working.
+ *
+ * The copy exists because the gate has zero dependencies and cannot import
+ * from the meter. policy-engine.parity.test.js asserts the two files match.
+ * ───────────────────────────────────────────────────────────────────────
+ */
+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');
+  const ids = new Set();
+  for (const r of policy.rules) {
+    if (!r || typeof r.id !== 'string' || !r.id || ids.has(r.id)) throw new Error('Unique rule IDs required');
+    ids.add(r.id);
+    const supported = ['id','route','method','tool','lane','subject','operator','verified','action','priceMicros','rail','quota'];
+    if (Object.keys(r).some(k => !supported.includes(k))) throw new Error('Unknown rule property');
+    if (!['allow','deny','pay','quota','allowance'].includes(r.action)) throw new Error('Unsupported action');
+    if (r.route !== undefined && (typeof r.route !== 'string' || !r.route.startsWith('/') || /[?#\\]/.test(r.route))) throw new Error('Invalid route prefix');
+    for (const k of ['method','tool','subject','operator']) if (r[k] !== undefined && (typeof r[k] !== 'string' || !r[k])) throw new Error('Invalid selector');
+    // The lane is the gate's own classification of the request. It is not an
+    // identity: suspected_bot means nothing was proven, so a rule written
+    // against it is a rule about absence of evidence, which is what a site
+    // owner actually wants to act on.
+    if (r.lane !== undefined && !['verified_agent','declared_agent','suspected_bot','human'].includes(r.lane)) throw new Error('Unknown lane');
+    if (r.verified !== undefined && typeof r.verified !== 'boolean') throw new Error('Invalid verified selector');
+    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');
+  }
+  return policy;
+}
+export async function evaluatePolicy(policy, context, { quotaStore } = {}) {
+  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 =>
+    (r.route === undefined || context.path === r.route || context.path.startsWith(r.route.endsWith('/') ? r.route : r.route+'/')) &&
+    (r.method === undefined || r.method === context.method) &&
+    (r.lane === undefined || r.lane === context.lane) &&
+    (r.tool === undefined || r.tool === context.tool) &&
+    (r.verified === undefined || r.verified === !!identity) &&
+    (r.subject === undefined || r.subject === identity?.subject) &&
+    (r.operator === undefined || r.operator === identity?.operator);
+  // 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;
+  for (const r of policy.rules) {
+    if (!matches(r)) continue;
+    const base = { policyVersion: policy.version, ruleId: r.id, ...(spent ? { reason: spent } : {}) };
+    if (r.action === 'quota' || r.action === 'allowance') {
+      const subject = identity?.subject || context.anonymousBucket;
+      if (!subject || !quotaStore) {
+        if (r.action === 'quota') return { ...base, action: 'deny', reason: 'Quota store or identity bucket unavailable' };
+        spent = 'Free allowance could not be verified'; continue;
+      }
+      const key = JSON.stringify([context.tenant, policy.version, r.id, subject]);
+      let allowed;
+      try { allowed = await quotaStore.consume({ key, limit: r.quota.limit, windowSeconds: r.quota.windowSeconds }); }
+      catch {
+        if (r.action === 'quota') return { ...base, action: 'deny', reason: 'Quota store unavailable' };
+        // Unknown consumption must not spend the allowance on the operator's
+        // behalf. Step aside so the priced rule behind this one applies.
+        spent = 'Free allowance could not be verified'; continue;
+      }
+      if (r.action === 'quota')
+        return { ...base, action: allowed === true ? 'allow' : 'deny', reason: allowed === true ? 'Within quota' : 'Quota exceeded' };
+      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 };
+  }
+  // A route the operator metered never falls back to a permissive default.
+  if (spent) return { policyVersion: policy.version, ruleId: null, action: 'deny', reason: spent };
+  return { policyVersion: policy.version, ruleId: null, action: policy.default };
+}

package/policy.d.ts

@@ -0,0 +1,57 @@
+/** Remote policy: fetched out of band, cached on disk, fail-open by construction. */
+export interface PolicyRule {
+  id: string;
+  route?: string;
+  method?: string;
+  tool?: string;
+  lane?: 'verified_agent' | 'declared_agent' | 'suspected_bot' | 'human';
+  subject?: string;
+  operator?: string;
+  verified?: boolean;
+  action: 'allow' | 'deny' | 'pay' | 'quota';
+  priceMicros?: number;
+  rail?: string;
+  quota?: { limit: number; windowSeconds: number };
+}
+
+export interface PolicyDocument {
+  version: string;
+  default: 'allow' | 'deny';
+  rules: PolicyRule[];
+  fetched?: string;
+  onUnreachable?: string;
+}
+
+export interface CompiledPolicy {
+  rules: Record<string, [string, boolean][]>;
+  rateLimits: Record<string, number>;
+  pricedPaths: Record<string, number>;
+  /** Rule ids the gate can enforce at this layer. */
+  applied: string[];
+  /** Rules deliberately not applied, with the reason. Never silently widened. */
+  skipped: { id: string; why: string }[];
+}
+
+export function compilePolicy(doc: PolicyDocument | null): CompiledPolicy;
+
+export interface RemotePolicyOptions {
+  apiKey: string;
+  endpoint?: string;
+  refreshMs?: number;
+  cachePath?: string;
+  onEvent?: (event: { type: string; [k: string]: unknown }) => void;
+  onChange?: (compiled: CompiledPolicy) => void;
+  fetchImpl?: typeof fetch;
+}
+
+export class RemotePolicy {
+  constructor(options: RemotePolicyOptions);
+  document: PolicyDocument | null;
+  etag: string | null;
+  fetchedAt: number | null;
+  compiled(): CompiledPolicy;
+  /** Never rejects. A gate must boot even when the meter is unreachable. */
+  start(): Promise<this>;
+  refresh(): Promise<PolicyDocument | null>;
+  stop(): void;
+}

package/policy.js

@@ -0,0 +1,243 @@
+/**
+ * Remote policy for an installed gate.
+ *
+ * THE LAW THIS FILE EXISTS TO OBEY: traffic fails open.
+ *
+ * Wayleave sits in front of somebody else's site. If our service is slow,
+ * unreachable, misconfigured or returning nonsense, their users must not
+ * notice. Nothing here is awaited in a request path, nothing here can throw
+ * into one, and every failure mode ends in "enforce what we last knew, and if
+ * we never knew anything, enforce nothing."
+ *
+ *   boot      -> disk cache, then network, then nothing
+ *   every 5m  -> conditional GET, swap in memory on success
+ *   decide    -> pure memory read, no I/O, no await
+ *
+ * Money is the opposite law and fails closed; that lives in x402.js.
+ */
+
+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';
+
+const DEFAULT_ENDPOINT = 'https://meter.wayleave.dev';
+const DEFAULT_REFRESH_MS = 5 * 60_000;
+const FETCH_TIMEOUT_MS = 5_000;
+const LANES = ['verified_agent', 'declared_agent', 'suspected_bot', 'human'];
+
+/** Deterministic JSON. Must match the meter's canonical() exactly, or every
+ *  signature verifies where it was made and nowhere else. */
+export function canonical(value) {
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort()
+      .filter(k => value[k] !== undefined)
+      .map(k => JSON.stringify(k) + ':' + canonical(value[k]))
+      .join(',') + '}';
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}
+
+/**
+ * Verify the signed envelope. Returns rather than throws: a gate's only
+ * correct response to a bad document is to keep serving from its last good
+ * copy, never to fail a request.
+ */
+export function verifyEnvelope(envelope, publicKey, { now = Date.now(), graceMs = 0 } = {}) {
+  if (!envelope || typeof envelope !== 'object') return { ok: false, reason: 'not an object' };
+  if (envelope.v !== 1) return { ok: false, reason: 'unsupported envelope version' };
+  if (typeof envelope.sig !== 'string' || !envelope.sig) return { ok: false, reason: 'missing signature' };
+  const { sig, ...body } = envelope;
+  try {
+    const key = typeof publicKey === 'string' ? createPublicKey(publicKey) : publicKey;
+    if (!edVerify(null, Buffer.from(canonical(body), 'utf8'), key, Buffer.from(sig, 'base64')))
+      return { ok: false, reason: 'signature does not match' };
+  } catch (err) { return { ok: false, reason: 'signature check failed: ' + err.message }; }
+  // After the signature, so a forged expiry cannot decide whether we check it.
+  const expires = Date.parse(envelope.expires);
+  if (!Number.isFinite(expires)) return { ok: false, reason: 'unreadable expiry' };
+  if (now > expires + graceMs) return { ok: false, reason: 'expired past grace' };
+  return { ok: true, policy: envelope.policy };
+}
+
+/**
+ * The meter's policy document, translated into the shapes the gate already
+ * enforces. Anything unrecognised is dropped rather than guessed at: a rule we
+ * cannot express is a rule we must not pretend to apply.
+ */
+export function compilePolicy(doc) {
+  const rules = {}, rateLimits = {}, pricedPaths = {};
+  const applied = [], skipped = [];
+  if (!doc || !Array.isArray(doc.rules)) return { rules, rateLimits, pricedPaths, applied, skipped };
+
+  for (const r of doc.rules) {
+    const lanes = r.lane ? [r.lane] : LANES;
+    const prefix = typeof r.route === 'string' && r.route.startsWith('/') ? r.route : '/';
+
+    if (r.action === 'allow' || r.action === 'deny') {
+      // Selectors the gate cannot evaluate at this layer. Applying such a rule
+      // as if it matched everything would deny traffic the customer meant to
+      // allow, which is exactly the outage this file exists to prevent.
+      if (r.subject || r.operator || r.tool || r.method || r.verified !== undefined) {
+        skipped.push({ id: r.id, why: 'selector not enforceable by the gate' });
+        continue;
+      }
+      for (const lane of lanes) (rules[lane] ||= []).push([prefix, r.action === 'allow']);
+      applied.push(r.id);
+    } else if (r.action === 'quota') {
+      // The gate's limiter is per-lane and per-window, not per-route, so a
+      // route-scoped quota is not something it can honour faithfully.
+      if (r.route) { skipped.push({ id: r.id, why: 'route-scoped quota needs the shared store' }); continue; }
+      for (const lane of lanes) rateLimits[lane] = r.quota.limit;
+      applied.push(r.id);
+    } else if (r.action === 'pay') {
+      if (!r.route) { skipped.push({ id: r.id, why: 'priced rule needs a route' }); continue; }
+      // Integer micro-USD is the wire format; pricedPaths is decimal USD. The
+      // division is exact for any price a person would write.
+      pricedPaths[r.route] = r.priceMicros / 1_000_000;
+      applied.push(r.id);
+    } else {
+      skipped.push({ id: r.id, why: `unsupported action ${r.action}` });
+    }
+  }
+  return { rules, rateLimits, pricedPaths, applied, skipped };
+}
+
+export class RemotePolicy {
+  /**
+   * @param {object} o
+   * @param {string} o.apiKey      the meter API key for this tenant
+   * @param {string} [o.endpoint]  meter base URL
+   * @param {number} [o.refreshMs] poll interval
+   * @param {string} [o.cachePath] where the last good document is kept
+   * @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,
+                cachePath = null, onEvent = null, onChange = null, fetchImpl = null } = {}) {
+    if (!apiKey && !url) throw new Error('RemotePolicy requires a policy url (or the meter apiKey)');
+    this.apiKey = apiKey;
+    this.publicKey = publicKey;
+    this.graceMs = graceMs;
+    this.url = url || endpoint.replace(/\/+$/, '') + '/v1/policy';
+    this.refreshMs = refreshMs;
+    this.cachePath = cachePath || defaultCachePath();
+    this.onEvent = onEvent || (() => {});
+    this._onChange = onChange || (() => {});
+    this._fetch = fetchImpl || globalThis.fetch;
+    this.document = null;   // last good policy, or null meaning enforce nothing
+    this.etag = null;
+    this.fetchedAt = null;
+    this._timer = null;
+  }
+
+  /** Compiled form of whatever we currently know. Pure memory. */
+  compiled() { return compilePolicy(this.document); }
+
+  /**
+   * Load whatever is on disk, then try the network once. Never rejects: a gate
+   * that cannot start because our service is down is the failure this whole
+   * design refuses.
+   */
+  async start() {
+    await this._loadCache();
+    await this.refresh();
+    if (this.refreshMs > 0) {
+      this._timer = setInterval(() => { this.refresh(); }, this.refreshMs);
+      this._timer.unref?.();
+    }
+    return this;
+  }
+
+  stop() { if (this._timer) clearInterval(this._timer); this._timer = null; }
+
+  /** One conditional GET. Swallows everything; reports through onEvent. */
+  async refresh() {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await this._fetch(this.url, {
+        signal: ac.signal,
+        headers: {
+          authorization: `Bearer ${this.apiKey}`,
+          ...(this.etag ? { 'if-none-match': this.etag } : {}),
+        },
+      });
+
+      if (res.status === 304) { this._emit('policy.unchanged'); return this.document; }
+
+      // 404 is "this tenant has set no policy", which is a real answer and
+      // means enforce nothing -- not an error, and not a reason to keep
+      // enforcing something the customer has since deleted.
+      if (res.status === 404) {
+        if (this.document) { this.document = null; this.etag = null; await this._writeCache(null); }
+        this._emit('policy.none');
+        this._changed();
+        return null;
+      }
+
+      if (!res.ok) { this._emit('policy.error', { status: res.status }); return this.document; }
+
+      const raw = await res.json();
+      // A signed URL that is served unverified is an unauthenticated URL.
+      let doc = raw;
+      if (this.publicKey) {
+        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;
+      }
+      if (!isUsable(doc)) { this._emit('policy.rejected', { why: 'document not usable' }); return this.document; }
+
+      this.document = doc;
+      this.etag = res.headers.get?.('etag') ?? null;
+      this.fetchedAt = Date.now();
+      await this._writeCache(doc);
+      const { applied, skipped } = compilePolicy(doc);
+      this._emit('policy.applied', { version: doc.version, applied, skipped });
+      this._changed();
+      return doc;
+    } catch (err) {
+      // Unreachable, timed out, DNS gone, TLS wrong, body not JSON: all the
+      // same answer. Keep the last good copy and say nothing to the request path.
+      this._emit('policy.unreachable', { error: err?.message });
+      return this.document;
+    } finally { clearTimeout(timer); }
+  }
+
+  async _loadCache() {
+    try {
+      const raw = JSON.parse(await readFile(this.cachePath, 'utf8'));
+      if (raw?.url === this.url && isUsable(raw.document)) {
+        this.document = raw.document;
+        this.etag = null;   // revalidate against the server, not against disk
+        this._emit('policy.cache.loaded', { version: raw.document.version });
+        this._changed();
+      }
+    } catch { /* no cache is the normal first-run state */ }
+  }
+
+  async _writeCache(document) {
+    try {
+      await mkdir(dirname(this.cachePath), { recursive: true });
+      await writeFile(this.cachePath, JSON.stringify({ url: this.url, document, at: Date.now() }));
+    } catch (err) { this._emit('policy.cache.unwritable', { error: err?.message }); }
+  }
+
+  _changed() { try { this._onChange(this.compiled()); } catch { /* never breaks a refresh */ } }
+
+  _emit(type, data = {}) { try { this.onEvent({ type, ...data }); } catch { /* never our problem */ } }
+}
+
+/** 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');
+}
+
+function defaultCachePath() {
+  // Beside the install when that is writable, /tmp when it is not. A read-only
+  // node_modules is normal in a container and must not cost us the cache.
+  try { return join(process.cwd(), 'node_modules', '.cache', 'wayleave', 'policy.json'); }
+  catch { return join(tmpdir(), 'wayleave-policy.json'); }
+}

package/registry.js

@@ -0,0 +1,187 @@
+/**
+ * The Wayleave registry: a signed, cached, fail-open directory of agent keys.
+ *
+ * Why this exists rather than more verification code: verification is
+ * commoditizable — an edge provider could clone the gate in a quarter. A
+ * directory that every install consults, whose value grows on both sides, can
+ * only be accumulated. It is also the one position an edge provider
+ * structurally cannot take, because a directory owned by one network is not a
+ * neutral directory.
+ *
+ * WHAT v1 IS: a signed list of operators' public keys, each traced to the
+ * endpoint that operator published it at.
+ *
+ * WHAT v1 IS NOT: reputation, scores, ranking, paid placement. Those are
+ * separate decisions with their own specs, and each is only safe after
+ * NEUTRALITY.md has held under pressure.
+ *
+ * THE FAIL-OPEN LAW, restated because it is the whole design:
+ *   unreachable, expired past grace, or bad signature -> last cached copy
+ *   no cache -> behave exactly as if no directory were configured
+ * Unknown agents stay unknown. They do not become suspected, and nothing
+ * about a customer's traffic changes because our CDN had a bad day.
+ */
+
+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 { canonical } from './policy.js';
+
+export const DEFAULT_REGISTRY_URL = 'https://registry.wayleave.dev/v1/agents.json';
+const DEFAULT_REFRESH_MS = 6 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5_000;
+
+/**
+ * Root keys this package accepts, newest first.
+ *
+ * Shipping the public half INSIDE the package is what makes a CDN compromise
+ * useless: a tampered document fails here, not at a server we also have to
+ * trust. A key fetched from the same origin as the document proves nothing.
+ *
+ * Rotation is never a flag day. Publish a release that accepts both the new
+ * and old key, then drop the old one a version later.
+ *
+ * EMPTY UNTIL A ROOT KEY EXISTS. With no key pinned, `wayleave:default`
+ * verifies nothing and therefore resolves nothing — which is the correct
+ * inert state, not a bypass. It must never be made to "accept anything when
+ * unconfigured"; that would turn the registry into an open door.
+ */
+export const WAYLEAVE_ROOT_KEYS = [];
+
+/** Verify the signed envelope. Returns rather than throws; see the header. */
+export function verifyRegistry(envelope, rootKeys, { now = Date.now(), graceMs = 0 } = {}) {
+  if (!envelope || typeof envelope !== 'object') return { ok: false, reason: 'not an object' };
+  if (envelope.v !== 1) return { ok: false, reason: 'unsupported registry version' };
+  if (!Array.isArray(envelope.agents)) return { ok: false, reason: 'no agents array' };
+  if (typeof envelope.sig !== 'string' || !envelope.sig) return { ok: false, reason: 'missing signature' };
+  if (!rootKeys?.length) return { ok: false, reason: 'no root key pinned in this build' };
+
+  const { sig, ...body } = envelope;
+  const bytes = Buffer.from(canonical(body), 'utf8');
+  const signature = Buffer.from(sig, 'base64');
+  const matched = rootKeys.some(k => {
+    try { return edVerify(null, bytes, typeof k === 'string' ? createPublicKey(k) : k, signature); }
+    catch { return false; }
+  });
+  if (!matched) return { ok: false, reason: 'signature does not match any pinned root key' };
+
+  // After the signature, so a forged expiry cannot decide whether we check it.
+  const expires = Date.parse(envelope.expires);
+  if (!Number.isFinite(expires)) return { ok: false, reason: 'unreadable expiry' };
+  if (now > expires + graceMs) return { ok: false, reason: 'expired past grace' };
+
+  return { ok: true, agents: envelope.agents };
+}
+
+/**
+ * Build the synchronous resolver verifySignature() expects.
+ *
+ * Keys are indexed by the operator's OWN published endpoint, because that is
+ * what an agent's signature names. An entry with no `source` is dropped: a key
+ * we cannot trace back to where the operator published it is a key we guessed,
+ * and guessing is the one thing this list must never do.
+ */
+export function buildIndex(agents) {
+  const byDirectory = new Map();
+  for (const a of agents || []) {
+    if (!a || typeof a.source !== 'string' || !a.source) continue;
+    if (a.status && a.status !== 'listed') continue;
+    const keys = byDirectory.get(a.source) || {};
+    for (const k of a.keys || []) {
+      if (!k || k.scheme !== 'ed25519' || k.status === 'revoked') continue;
+      if (typeof k.keyid !== 'string' || typeof k.pubkey !== 'string') continue;
+      keys[k.keyid] = k.pubkey;
+    }
+    if (Object.keys(keys).length) byDirectory.set(a.source, keys);
+  }
+  return byDirectory;
+}
+
+export class Registry {
+  constructor({ url = DEFAULT_REGISTRY_URL, rootKeys = WAYLEAVE_ROOT_KEYS,
+                refreshMs = DEFAULT_REFRESH_MS, graceMs = 0, cachePath = null,
+                onEvent = null, fetchImpl = null } = {}) {
+    this.url = url;
+    this.rootKeys = rootKeys;
+    this.refreshMs = refreshMs;
+    this.graceMs = graceMs;
+    this.cachePath = cachePath || defaultCachePath();
+    this.onEvent = onEvent || (() => {});
+    this._fetch = fetchImpl || globalThis.fetch;
+    this.agents = null;
+    this.index = new Map();
+    this._timer = null;
+  }
+
+  /** Synchronous, memory-only. This runs on every signed request. */
+  resolver() {
+    return directoryUrl => this.index.get(directoryUrl);
+  }
+
+  /** How many operators and keys are live. For a dashboard, not a decision. */
+  stats() {
+    let keys = 0;
+    for (const m of this.index.values()) keys += Object.keys(m).length;
+    return { directories: this.index.size, keys, listed: this.agents?.length ?? 0 };
+  }
+
+  async start() {
+    await this._loadCache();
+    await this.refresh();
+    if (this.refreshMs > 0) {
+      this._timer = setInterval(() => { this.refresh(); }, this.refreshMs);
+      this._timer.unref?.();
+    }
+    return this;
+  }
+
+  stop() { if (this._timer) clearInterval(this._timer); this._timer = null; }
+
+  async refresh() {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await this._fetch(this.url, { signal: ac.signal });
+      if (!res.ok) { this._emit('registry.error', { status: res.status }); return this.agents; }
+      const envelope = await res.json();
+      const v = verifyRegistry(envelope, this.rootKeys, { graceMs: this.graceMs });
+      if (!v.ok) { this._emit('registry.rejected', { why: v.reason }); return this.agents; }
+      this._adopt(v.agents);
+      await this._writeCache(envelope);
+      this._emit('registry.applied', this.stats());
+      return this.agents;
+    } catch (err) {
+      this._emit('registry.unreachable', { error: err?.message });
+      return this.agents;
+    } finally { clearTimeout(timer); }
+  }
+
+  _adopt(agents) { this.agents = agents; this.index = buildIndex(agents); }
+
+  async _loadCache() {
+    try {
+      const raw = JSON.parse(await readFile(this.cachePath, 'utf8'));
+      if (raw?.url !== this.url) return;
+      // The cache is re-verified, not trusted. A file on disk is not evidence.
+      const v = verifyRegistry(raw.envelope, this.rootKeys, { graceMs: this.graceMs });
+      if (!v.ok) { this._emit('registry.cache.rejected', { why: v.reason }); return; }
+      this._adopt(v.agents);
+      this._emit('registry.cache.loaded', this.stats());
+    } catch { /* no cache is the normal first run */ }
+  }
+
+  async _writeCache(envelope) {
+    try {
+      await mkdir(dirname(this.cachePath), { recursive: true });
+      await writeFile(this.cachePath, JSON.stringify({ url: this.url, envelope, at: Date.now() }));
+    } catch (err) { this._emit('registry.cache.unwritable', { error: err?.message }); }
+  }
+
+  _emit(type, data = {}) { try { this.onEvent({ type, ...data }); } catch { /* never our problem */ } }
+}
+
+function defaultCachePath() {
+  try { return join(process.cwd(), 'node_modules', '.cache', 'wayleave', 'registry.json'); }
+  catch { return join(tmpdir(), 'wayleave-registry.json'); }
+}