wayleave 0.5.7 → 0.6.0

package/README.md

@@ -240,6 +240,49 @@ confirmation is yours to supply and denies by default. If you shipped 0.1.4 or e
 route, upgrade.
 
 **0.1.6** addressed the other half: payment could be faked, and so could being human.
+### Charge by lane
+
+A route can cost different amounts depending on who is asking.
+
+```js
+pricedPaths: {
+  '/api/v1/properties/search': 0.001,          // flat: every lane pays this
+
+  '/api/v1/properties/valuation-history': {    // or per lane
+    verified_agent: 0.01,                      // proved who it is
+    declared_agent: 0.05,                      // said who it is
+    suspected_bot:  0.15,                      // neither
+    method: 'GET',
+    description: 'Historical comps, tax and owner records',
+  },
+}
+```
+
+The reason to bother is not price discrimination. Signing a request under Web
+Bot Auth currently earns an operator nothing — it is pure cost, which is the
+honest explanation for how few agents do it. A lower price for a proved
+identity turns adoption into a bill that goes down, and it is the only lever
+on that an origin actually controls.
+
+Three rules, each of which exists because the alternative is worse:
+
+- **The manifest publishes the dearest lane.** A discovery document is read
+  before anyone knows who is asking, so the only safe direction for the real
+  quote to move is downward. Advertise $0.01 and bill a suspected bot $0.15
+  and you have surprised them upward; advertise $0.15 and every other lane is
+  a discount.
+- **An unlisted lane pays the list price, never free.** Set `default` to
+  choose otherwise. A lane nobody configured is a case nobody considered, and
+  giving the route away is the one outcome they certainly did not intend.
+- **The `human` lane cannot be priced.** It is a fall-through, so that is
+  where an ordinary visitor lands. A `human:` key warns at startup and is
+  unreachable in the pricing path — including under `strictPricedPaths`,
+  where an unconfirmed human *does* reach it. To charge everything that is
+  not a proven person, use `strictPricedPaths: true`, not a human price.
+
+The 402 names the lane it priced, so a caller asking why it was charged more
+than someone else has an answer.
+
 `strictPricedPaths` lets a priced route demand positive evidence rather than accepting the absence of
 a bot signal as one.
 

package/index.js

@@ -507,6 +507,8 @@ export class Wayleave {
    *   rateLimits: { [lane]: perWindow }, rateWindow: 60,
    *   pricedPaths: { pathPrefix: priceUsd },
    *   pricedPaths: { pathPrefix: { price, method, description } },
+   *   pricedPaths: { pathPrefix: { verified_agent, declared_agent,
+   *                                suspected_bot, default } },
    *   verifyPayment: (proof, ctx) => boolean | { ok, ref },
    *   strictPricedPaths: false,
    *   confirmHuman: (req) => boolean,
@@ -573,6 +575,27 @@ export class Wayleave {
       : opts.strictPricedPaths === true;
     const priced = Object.keys(this.pricedPaths).length > 0;
     const warn = this._onWarn = opts.onWarn || console.warn;
+    /* A price on the human lane would charge people.
+     *
+     * The lane is a fall-through: a request reaches it by tripping none of
+     * the automation tells, which is how an ordinary visitor arrives. Every
+     * other guarantee here is hedged somewhere in the README; "humans are
+     * never charged" is not, and a per-lane table is the first place someone
+     * could break it by typing one extra key.
+     *
+     * Ignored rather than thrown -- an app that boots is easier to fix than
+     * one that does not -- but said once, loudly, naming the route. */
+    for (const [prefix, cfg] of Object.entries(this.pricedPaths)) {
+      if (cfg === null || typeof cfg !== 'object') continue;
+      for (const k of ['human', 'unclassified', 'unknown']) {
+        if (typeof cfg[k] === 'number')
+          warn(`[wayleave] pricedPaths["${prefix}"] sets a price for the ` +
+               `"${k}" lane. That lane is where people land, and it is not ` +
+               `charged. The price is ignored. To charge anything that is ` +
+               `not a proven person, set strictPricedPaths: true instead.`);
+      }
+    }
+
     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 ' +
@@ -806,9 +829,14 @@ export class Wayleave {
           /* Through routeSpec, so a route configured with a method and a
              description still charges its price and not the object holding
              it. The manifest reads the same function, so the document and
-             this challenge cannot disagree about what a route costs. */
-          const { price } = routeSpec(configured);
-          const challenge = { scheme: 'x402', price_usd: price, resource: prefix };
+             this challenge cannot disagree about what a route costs.
+
+             The lane is passed in because a route may be priced per lane.
+             Here we know who is asking, so the quote is exact; the manifest
+             has no lane and publishes the dearest, which is why the two can
+             differ without either being wrong. */
+          const { price } = routeSpec(configured, lane);
+          const challenge = { scheme: 'x402', price_usd: price, resource: prefix, lane };
           if (!paymentProof) {
             const why = this.strictPricedPaths && lane === LANES.HUMAN
               ? 'payment required: no signature and no confirmed human'

package/manifest.js

@@ -59,11 +59,70 @@ const DEFAULT_TIMEOUT_SECONDS = 60;
  *   pricedPaths: { '/api/x': { price: 0.05, method: 'POST',
  *                              description: 'Score one transaction' } }
  */
-export function routeSpec(value) {
+/**
+ * The agent lanes a route may be priced for, dearest first.
+ *
+ * `human` is deliberately absent and cannot be priced. It is a fall-through
+ * lane -- reached by tripping none of the automation tells -- so a real
+ * person lands there, and charging it would charge people. That is the one
+ * promise this library makes without qualification.
+ */
+export const PRICED_LANES = Object.freeze(
+  ['suspected_bot', 'declared_agent', 'verified_agent']);
+
+/** Is this object a per-lane price table rather than a rich single price? */
+function isLaneTable(v) {
+  return v !== null && typeof v === 'object' &&
+         PRICED_LANES.some((l) => typeof v[l] === 'number');
+}
+
+/**
+ * One priced route, normalised.
+ *
+ * Called with a lane it answers what that lane pays. Called without one -- as
+ * the manifest does, because a document has no lane -- it answers the LIST
+ * price, which is the dearest of the configured lanes.
+ *
+ * List price is the maximum on purpose. The manifest is an advertisement read
+ * before anyone knows who is asking, so the only safe direction for the real
+ * quote to differ is downward. Publish the cheapest and a suspected bot that
+ * discovered the route at $0.01 gets billed $0.15, which is a surprise in the
+ * worst direction. Publish the dearest and every other lane is a discount.
+ *
+ * A lane with no entry falls back to `default`, and failing that to the list
+ * price. Not to free: an unlisted lane is an operator who did not think about
+ * that case, and money fails closed.
+ */
+export function routeSpec(value, lane) {
   const rich = value !== null && typeof value === 'object';
-  const price = rich ? value.price : value;
+  const lanes = isLaneTable(value) ? value : null;
+
+  let price;
+  if (!lanes) {
+    price = rich ? value.price : value;
+  } else if (lane && PRICED_LANES.includes(lane) && typeof lanes[lane] === 'number') {
+    /* PRICED_LANES.includes() is load-bearing, not a tidy-up.
+     *
+     * Without it a `human: 0.99` key is reachable: under strictPricedPaths an
+     * unconfirmed human DOES reach the pricing loop -- that is the whole
+     * point of strict mode -- and would be quoted its own entry. The
+     * constructor warns about such a key, but a warning is advice and this is
+     * the code path that takes money. Reading the lane through the allowed
+     * list means the price cannot be quoted even if the warning is ignored. */
+    price = lanes[lane];
+  } else if (typeof lanes.default === 'number') {
+    price = lanes.default;
+  } else {
+    price = Math.max(...PRICED_LANES
+      .map((l) => lanes[l]).filter((n) => typeof n === 'number'));
+  }
+
   return {
     price,
+    lanes: lanes
+      ? Object.fromEntries(PRICED_LANES
+          .filter((l) => typeof lanes[l] === 'number').map((l) => [l, lanes[l]]))
+      : null,
     method: String((rich && value.method) || 'GET').toUpperCase(),
     description: (rich && value.description) || 'x402-priced route',
     mimeType: (rich && value.mimeType) || 'application/json',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wayleave",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "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",