wayleave 0.1.2 → 0.1.4

package/README.md

@@ -1,10 +1,14 @@
 # wayleave
 
+[![Tests](https://github.com/gibrancorbin11-hub/wayleave/actions/workflows/test.yml/badge.svg)](https://github.com/gibrancorbin11-hub/wayleave/actions/workflows/test.yml)
+[![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)
+
 **Charge AI agents for passage across your app.**
 
 A *wayleave* is the fee paid for the right of passage across private land — utility companies have paid them for 150 years to run cables through property. AI agents are about to cross your app millions of times for free. Charge them a wayleave.
 
-Zero dependencies. Node's native crypto only.
+Zero dependencies. Node's native crypto only. TypeScript declarations included.
 
 ## What it does
 
@@ -40,14 +44,16 @@ app.use(gate.express());
 
 ## Guarantees, honestly stated
 
-- Signature verification is real Ed25519 over an RFC 9421 signature base (`@authority`, `signature-agent`) — forged keys, tampered requests, expired signatures, and replay-farming windows are all rejected. Tested adversarially.
+- 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.
+- 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.
 - Sub-millisecond per request. Your latency budget won't notice.
 - The metering hook can throw, crash, or hang your billing backend — serving continues. Your uptime never depends on ours.
+- Key directories still load from config rather than a live JWKS fetch, so key rotation is not handled. That is the next real gap.
 - This is a **screening and pricing layer, not a guarantee**. Every decision returns its evidence and is loggable.
 
 ## Status
 
-v0.1 — verification, lanes, policy, pricing, and the metering hook, all under test (22 scenarios, including forgery, tampering, and replay). Payment settlement network integration is in progress; today the 402 challenge and payment-proof check are pluggable.
+v0.1 — verification, lanes, policy, pricing, and the metering hook, all under test (29 scenarios, including forgery, tampering, replay, and cross-implementation wire formats). Payment settlement network integration is in progress; today the 402 challenge and payment-proof check are pluggable.
 
 ## License
 

package/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * wayleave — charge AI agents for passage across your app.
+ *
+ * Verifies Web Bot Auth signatures (RFC 9421 profile, Ed25519), classifies
+ * every request into a lane, applies per-lane policy, and returns 402 with an
+ * x402-shaped challenge on routes you price. Humans browse free.
+ */
+
+/**
+ * A Node `KeyObject` from `node:crypto`. Typed structurally rather than
+ * imported so this declaration file needs no @types/node — the package has
+ * zero dependencies and the types shouldn't reintroduce one. A real
+ * KeyObject satisfies this.
+ */
+export interface KeyObjectLike {
+  readonly type: string;
+  readonly asymmetricKeyType?: string;
+}
+
+/** The four lanes every request is sorted into. */
+export type Lane =
+  | 'verified_agent'
+  | 'declared_agent'
+  | 'suspected_bot'
+  | 'human';
+
+export const LANES: Readonly<{
+  VERIFIED: 'verified_agent';
+  DECLARED: 'declared_agent';
+  SUSPECT: 'suspected_bot';
+  HUMAN: 'human';
+}>;
+
+/**
+ * A public key for a signature agent. Accepts a KeyObject, a PEM string, or a
+ * bare base64 raw Ed25519 public key (32 bytes, SPKI prefix added for you).
+ * Strings are converted to a KeyObject and cached on first use.
+ */
+export type PublicKeyLike = KeyObjectLike | string;
+
+/**
+ * Key directories you trust, keyed by the URL an agent presents in its
+ * `signature-agent` header, then by keyid.
+ *
+ * Note: these are read from config, not fetched. Rotation is not handled.
+ */
+export type KeyDirectories = Record<string, Record<string, PublicKeyLike>>;
+
+/** Incoming request, normalised. Framework-agnostic on purpose. */
+export interface WayleaveRequest {
+  method: string;
+  path: string;
+  /** Host authority the signature was computed over, e.g. "example.com". */
+  authority: string;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  /** `${directoryUrl}#${keyid}` when ok, otherwise null. */
+  agentId: string | null;
+  /** Human-readable reason, safe to log. */
+  reason: string;
+}
+
+export interface Classification {
+  lane: Lane;
+  agentId: string | null;
+  /** Why this lane was chosen. Loggable. */
+  evidence: string[];
+}
+
+/** x402-shaped payment challenge returned with a 402. */
+export interface PaymentChallenge {
+  scheme: 'x402';
+  price_usd: number;
+  /** The priced path prefix that matched. */
+  resource: string;
+}
+
+export interface Decision {
+  lane: Lane;
+  /** agentId when verified, else `${lane}:${xff ?? 'unknown'}`. */
+  identity: string;
+  status: 200 | 402 | 403 | 429;
+  /** Why this status was returned. */
+  why: string;
+  evidence: string[];
+  /** Present only on 402. */
+  challenge?: PaymentChallenge;
+  /** Present only when a priced request was paid. */
+  billed?: number;
+}
+
+/** What the metering hook receives. It may throw; serving continues. */
+export interface MeterEvent {
+  /** Unix seconds. */
+  t: number;
+  path: string;
+  lane: Lane;
+  identity: string;
+  status: number;
+  why: string;
+  evidence: string[];
+  billedUsd: number;
+}
+
+/** `[pathPrefix, allow]` — first matching prefix wins. */
+export type PolicyRule = [prefix: string, allow: boolean];
+
+export interface WayleaveOptions {
+  directories?: KeyDirectories;
+  /** Per-lane allow/deny rules, evaluated in order. */
+  rules?: Partial<Record<Lane, PolicyRule[]>>;
+  /** Max requests per identity per window, per lane. */
+  rateLimits?: Partial<Record<Lane, number>>;
+  /** Window length in seconds. Default 60. */
+  rateWindow?: number;
+  /** Path prefix -> price in USD. Non-human lanes get 402 here. */
+  pricedPaths?: Record<string, number>;
+  /**
+   * Metering hook, called once per request. Exceptions are swallowed —
+   * billing must never break serving.
+   */
+  onEvent?: (event: MeterEvent) => void;
+}
+
+/** Build the `@signature-params` value for the Web Bot Auth profile. */
+export function buildParams(
+  keyid: string,
+  created: number,
+  expires: number
+): string;
+
+/**
+ * Sign a request the way a legitimate agent operator's SDK would.
+ * Mutates and returns `headers`.
+ */
+export function signRequest(
+  headers: Record<string, string>,
+  authority: string,
+  privateKey: KeyObjectLike,
+  keyid: string,
+  directoryUrl: string,
+  created?: number,
+  expires?: number
+): Record<string, string>;
+
+/** Verify a presented signature against your configured directories. */
+export function verifySignature(
+  headers: Record<string, string | string[] | undefined>,
+  authority: string,
+  directories: KeyDirectories,
+  now?: number
+): VerifyResult;
+
+/**
+ * Sort a request into a lane. A signature that FAILS verification lands in
+ * `suspected_bot`, not `human` — forging identity is the loudest signal there is.
+ */
+export function classify(
+  req: WayleaveRequest,
+  directories: KeyDirectories,
+  now?: number
+): Classification;
+
+export class Wayleave {
+  constructor(opts?: WayleaveOptions);
+  /** Classify, apply policy, price, and emit the metering event. */
+  handle(
+    req: WayleaveRequest,
+    now?: number,
+    paymentProof?: string
+  ): Decision;
+  /** Express/Connect adapter. Sets `req.wayleave` to the Decision. */
+  express(): (req: any, res: any, next: (err?: any) => void) => void;
+}
+
+export default Wayleave;

package/index.js

@@ -28,28 +28,80 @@ export const LANES = Object.freeze({
 
 // ── RFC 9421 profile (Web Bot Auth usage) ───────────────────────────────
 
-const PARAMS_RE = /created=(\d+);expires=(\d+);keyid="([^"]+)";tag="([^"]+)"/;
+/**
+ * Parse an RFC 9421 `signature-input` value: `label=("a" "b");k=v;k2="v2"`.
+ *
+ * Parameters form a dictionary — order is NOT significant, and no
+ * implementation is obliged to emit them in any particular sequence. The
+ * label is arbitrary too (Cloudflare uses `sig2`, we emit `sig1`). Anything
+ * that hardcodes either will reject legitimately signed traffic.
+ *
+ * Returns { label, components, params, paramsRaw } or null.
+ * `paramsRaw` is preserved verbatim — the signature base must reproduce it
+ * byte for byte or verification fails.
+ */
+function parseSignatureInput(raw) {
+  const eq = raw.indexOf('=');
+  if (eq < 1) return null;
+  const label = raw.slice(0, eq).trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(label)) return null;
+
+  const paramsRaw = raw.slice(eq + 1);
+  const close = paramsRaw.indexOf(')');
+  if (!paramsRaw.startsWith('(') || close < 0) return null;
+
+  const components = (paramsRaw.slice(1, close).match(/"[^"]*"/g) || [])
+    .map(s => s.slice(1, -1).toLowerCase());
+
+  const params = {};
+  const re = /;\s*([A-Za-z0-9_.-]+)=("[^"]*"|[^;]+)/g;
+  let m;
+  while ((m = re.exec(paramsRaw.slice(close + 1))) !== null) {
+    const v = m[2].trim();
+    params[m[1]] = v.startsWith('"') ? v.slice(1, -1) : v;
+  }
+  return { label, components, params, paramsRaw };
+}
+
+/** Structured-field strings arrive quoted; the directory URL itself is not. */
+function unquote(s) {
+  return s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1) : s;
+}
+
+function headerValue(headers, name) {
+  const v = headers[name];
+  return Array.isArray(v) ? v.join(', ') : (v == null ? '' : String(v));
+}
 
-function sigBase(authority, signatureAgent, params) {
-  return Buffer.from(
-    `"@authority": ${authority}\n` +
-    `"signature-agent": ${signatureAgent}\n` +
-    `"@signature-params": ${params}`
+/**
+ * Build the signature base from the components the signer actually declared,
+ * not from a fixed list. An agent covering only ("@authority") is valid.
+ */
+function sigBase(components, ctx, paramsRaw) {
+  const lines = components.map(c =>
+    c === '@authority'
+      ? `"@authority": ${ctx.authority}`
+      : `"${c}": ${headerValue(ctx.headers, c)}`
   );
+  lines.push(`"@signature-params": ${paramsRaw}`);
+  return Buffer.from(lines.join('\n'));
 }
 
 export function buildParams(keyid, created, expires) {
   return `("@authority" "signature-agent");created=${created};` +
-         `expires=${expires};keyid="${keyid}";tag="web-bot-auth"`;
+         `keyid="${keyid}";alg="ed25519";expires=${expires};tag="web-bot-auth"`;
 }
 
 /** What a legitimate agent operator's SDK does before sending. */
 export function signRequest(headers, authority, privateKey, keyid, directoryUrl,
                             created = Math.floor(Date.now() / 1000),
                             expires = created + 300) {
-  headers['signature-agent'] = directoryUrl;
+  // Structured-field string: the value is sent quoted.
+  headers['signature-agent'] = `"${directoryUrl}"`;
   const params = buildParams(keyid, created, expires);
-  const sig = edSign(null, sigBase(authority, directoryUrl, params), privateKey);
+  const base = sigBase(['@authority', 'signature-agent'],
+                       { authority, headers }, params);
+  const sig = edSign(null, base, privateKey);
   headers['signature-input'] = `sig1=${params}`;
   headers['signature'] = `sig1=:${sig.toString('base64')}:`;
   return headers;
@@ -61,18 +113,32 @@ export function signRequest(headers, authority, privateKey, keyid, directoryUrl,
  */
 export function verifySignature(h, authority, directories,
                                 now = Math.floor(Date.now() / 1000)) {
-  const sigInput = h['signature-input'] || '';
-  const sigHeader = h['signature'] || '';
-  const directory = h['signature-agent'] || '';
+  const sigInput = headerValue(h, 'signature-input');
+  const sigHeader = headerValue(h, 'signature');
+  const rawAgent = headerValue(h, 'signature-agent');
 
-  if (!sigInput || !sigHeader || !directory)
+  if (!sigInput || !sigHeader || !rawAgent)
     return { ok: false, agentId: null, reason: 'no signature presented' };
 
-  const m = PARAMS_RE.exec(sigInput);
-  if (!m) return { ok: false, agentId: null, reason: 'malformed signature-input' };
-  const [, createdS, expiresS, keyid, tag] = m;
-  const created = +createdS, expires = +expiresS;
+  const parsed = parseSignatureInput(sigInput);
+  if (!parsed) return { ok: false, agentId: null, reason: 'malformed signature-input' };
+  const { label, components, params, paramsRaw } = parsed;
+
+  const directory = unquote(rawAgent);
+  const keyid = params.keyid;
+  const tag = params.tag;
+  const created = Number(params.created);
+  const expires = Number(params.expires);
 
+  if (!keyid) return { ok: false, agentId: null, reason: 'signature-input missing keyid' };
+  if (!Number.isFinite(created) || !Number.isFinite(expires))
+    return { ok: false, agentId: null, reason: 'signature-input missing created/expires' };
+  if (!components.includes('@authority'))
+    return { ok: false, agentId: null, reason: '@authority not covered by signature' };
+  // alg is mandatory in the Web Bot Auth profile; tolerate its absence for
+  // signers that omit it, but reject anything that is not Ed25519.
+  if (params.alg && params.alg.toLowerCase() !== 'ed25519')
+    return { ok: false, agentId: null, reason: `unsupported alg "${params.alg}"` };
   if (tag !== 'web-bot-auth')
     return { ok: false, agentId: null, reason: `unexpected tag "${tag}"` };
   if (now < created - 30)
@@ -96,11 +162,13 @@ export function verifySignature(h, authority, directories,
     dir[keyid] = key; // cache the KeyObject
   }
 
-  const sm = /sig1=:([A-Za-z0-9+/=]+):/.exec(sigHeader);
+  // Match the signature by the label the signer used, not a hardcoded "sig1".
+  const sm = new RegExp(
+    `(?:^|,)\\s*${label.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')}=:([A-Za-z0-9+/=]+):`
+  ).exec(sigHeader);
   if (!sm) return { ok: false, agentId: null, reason: 'malformed signature header' };
 
-  const params = sigInput.slice(sigInput.indexOf('sig1=') + 5);
-  const valid = edVerify(null, sigBase(authority, directory, params),
+  const valid = edVerify(null, sigBase(components, { authority, headers: h }, paramsRaw),
                          key, Buffer.from(sm[1], 'base64'));
   if (!valid)
     return { ok: false, agentId: null,

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "wayleave",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.",
   "type": "module",
   "main": "index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -40,4 +45,4 @@
     "url": "https://github.com/gibrancorbin11-hub/wayleave/issues"
   },
   "homepage": "https://github.com/gibrancorbin11-hub/wayleave#readme"
-}
+}