@tollbase/middleware 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tollbase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @tollbase/middleware
+
+Let AI agents become paying customers of your API or MCP server: verified agent
+identity, human-approved spending caps, scoped keys, per-call metering, and
+billing through your own Stripe account.
+
+This is the vendor middleware. It mounts inside your existing server, serves
+your agent-facing manifest, verifies agent tokens locally (your latency and
+uptime never depend on the Tollbase control plane), enforces spending caps, and
+streams idempotency-keyed usage for exact billing.
+
+## Install
+
+```bash
+npm install @tollbase/middleware
+```
+
+## Integrate (Express)
+
+```ts
+import { Tollbase } from "@tollbase/middleware";
+import { tollbaseRouter, protect } from "@tollbase/middleware/express";
+
+const tb = new Tollbase({ serviceSlug, serviceKey, controlPlaneUrl });
+await tb.init();
+
+app.use(tollbaseRouter(tb)); // the agent front door
+app.post("/v1/enrich", protect(tb, "enrich", "enrich:read"), (req, res) => res.json(doWork(req.body)));
+```
+
+High-value routes can opt into a synchronous ledger check:
+`protect(tb, "bulk", "enrich:read", { strict: true, costCents: 30 })`.
+
+## MCP servers
+
+```ts
+import { paidTool } from "@tollbase/middleware/mcp";
+server.registerTool("enrich", schema, paidTool(tb, "enrich", "enrich:read", handler));
+```
+
+## How it behaves
+
+- Local JWT verification against a cached JWKS; no network on the hot path.
+- Optimistic cap enforcement from token claims, reconciled at every key refresh;
+  overspend bounded to one 15-minute token window by design.
+- Usage streams asynchronously with client idempotency keys; at-least-once
+  delivery cannot double-bill.
+- Revocation propagates through a pulled feed; in-flight tokens die within one
+  poll interval.
+
+A Python SDK with identical behavior is available: `pip install tollbase`.
+
+MIT.

package/dist/express.d.ts

@@ -0,0 +1,37 @@
+import { Router, type Request, type Response, type NextFunction } from "express";
+import type { Tollbase, VerifiedAgent } from "./index.js";
+declare global {
+    namespace Express {
+        interface Request {
+            tollbase?: {
+                agent: VerifiedAgent;
+                meter: (tool: string, units?: number, costCents?: number) => void;
+            };
+        }
+    }
+}
+/**
+ * Mounts the agent-facing front door on the vendor's app:
+ *   GET  /.well-known/agent.json     discovery manifest
+ *   POST /agent/register             proxied to the control plane
+ *   POST /agent/keys                 proxied (mint/refresh; carries agent_secret or refresh_token)
+ *   POST /agent/topup-request        proxied
+ *   GET  /agent/accounts/:id/status  proxied
+ * Agents interact with ONE origin (the vendor); Tollbase stays behind it.
+ */
+export declare function tollbaseRouter(dm: Tollbase): Router;
+export interface ProtectOptions {
+    /**
+     * strict: one synchronous cap check per call against the control plane —
+     * for high-value routes where exactness beats latency. Default false
+     * (optimistic local enforcement, bounded by one token TTL window).
+     */
+    strict?: boolean;
+    /** Override the per-call price; defaults to the plan's unit_cents. */
+    costCents?: number;
+}
+/**
+ * Protect a paid route: verify locally, check scope, gate against the cap,
+ * and auto-meter one unit. `requiredScope` maps the route to a plan scope.
+ */
+export declare function protect(dm: Tollbase, tool: string, requiredScope: string, opts?: ProtectOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;

package/dist/express.js

@@ -0,0 +1,68 @@
+import { Router } from "express";
+import express from "express";
+/**
+ * Mounts the agent-facing front door on the vendor's app:
+ *   GET  /.well-known/agent.json     discovery manifest
+ *   POST /agent/register             proxied to the control plane
+ *   POST /agent/keys                 proxied (mint/refresh; carries agent_secret or refresh_token)
+ *   POST /agent/topup-request        proxied
+ *   GET  /agent/accounts/:id/status  proxied
+ * Agents interact with ONE origin (the vendor); Tollbase stays behind it.
+ */
+export function tollbaseRouter(dm) {
+    const r = Router();
+    r.use(express.json());
+    const cp = dm.cfg.controlPlaneUrl;
+    const proxy = (method, target) => async (req, res) => {
+        const headers = { "content-type": "application/json" };
+        const sig = req.header("signature-agent");
+        if (sig)
+            headers["signature-agent"] = sig; // forward Web Bot Auth identity
+        const upstream = await fetch(target(req), {
+            method,
+            headers,
+            body: method === "GET" ? undefined : JSON.stringify(req.body ?? {}),
+        });
+        res.status(upstream.status).json(await upstream.json());
+    };
+    r.get("/.well-known/agent.json", (_req, res) => {
+        if (!dm.manifest)
+            return res.status(503).json({ error: "manifest_not_loaded" });
+        res.json(dm.manifest);
+    });
+    r.post("/agent/register", proxy("POST", () => `${cp}/services/${dm.cfg.serviceSlug}/register`));
+    r.post("/agent/keys", proxy("POST", (req) => `${cp}/accounts/${req.body?.account_id}/keys`));
+    r.post("/agent/topup-request", proxy("POST", (req) => `${cp}/accounts/${req.body?.account_id}/topup-request`));
+    r.get("/agent/accounts/:id/status", proxy("GET", (req) => `${cp}/accounts/${req.params.id}/status`));
+    return r;
+}
+/**
+ * Protect a paid route: verify locally, check scope, gate against the cap,
+ * and auto-meter one unit. `requiredScope` maps the route to a plan scope.
+ */
+export function protect(dm, tool, requiredScope, opts = {}) {
+    return async (req, res, next) => {
+        const agent = await dm.verify(req.header("authorization"));
+        if (!agent) {
+            return res
+                .status(401)
+                .json({ error: "missing_or_invalid_bearer_token", hint: "see /.well-known/agent.json" });
+        }
+        if (!agent.scopes.includes(requiredScope)) {
+            return res.status(403).json({ error: "insufficient_scope", required: requiredScope });
+        }
+        const cost = opts.costCents ?? dm.unitCents();
+        const gate = opts.strict ? await dm.gateStrict(agent, tool, cost) : dm.gate(agent, tool, cost);
+        if (!gate.ok)
+            return res.status(402).json(gate.body);
+        req.tollbase = {
+            agent,
+            meter: (t, units = 1, costCents = dm.unitCents()) => {
+                // Additional units beyond the auto-metered one (e.g. per-row pricing).
+                for (let i = 0; i < units; i++)
+                    dm.gate(agent, t, costCents);
+            },
+        };
+        next();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { err402, type Err402Body, type Manifest } from "@tollbase/core/types";
+export interface TollbaseConfig {
+    serviceSlug: string;
+    serviceKey: string;
+    controlPlaneUrl: string;
+    /** Flush interval for the usage queue (ms). Default 2000. */
+    flushMs?: number;
+    /** Poll interval for the revocation feed (ms). Default 30000. 0 disables. */
+    revocationPollMs?: number;
+    /** Refresh interval for the service manifest (ms), so dashboard price
+     * edits reach running vendors without a restart. Default 60000. 0 disables. */
+    manifestRefreshMs?: number;
+}
+export interface VerifiedAgent {
+    accountId: string;
+    scopes: string[];
+    capCents: number;
+    iat: number;
+    jti: string;
+}
+/**
+ * Framework-agnostic middleware core. Design principle P1: the vendor's hot
+ * path never synchronously depends on the control plane.
+ *   - Token verification is local (jose caches the JWKS).
+ *   - Spend caps enforce optimistically from the `cap` claim minus local
+ *     spend since mint; the control plane reconciles at every key refresh,
+ *     bounding overspend to one 15-minute TTL window by design.
+ *   - Revocation is a pull feed: an in-TTL token dies within one poll
+ *     interval, still without a hot-path network call.
+ *   - Usage streams asynchronously with client idempotency keys, so
+ *     at-least-once delivery cannot double-bill.
+ */
+export declare class Tollbase {
+    readonly cfg: TollbaseConfig;
+    private jwks;
+    manifest: Manifest | null;
+    private localSpend;
+    private queue;
+    private flushTimer;
+    private revokedJtis;
+    private revocationCursor;
+    private revocationTimer;
+    private manifestTimer;
+    constructor(cfg: TollbaseConfig);
+    /** Load the service manifest and start background loops. Call once at boot. */
+    init(): Promise<void>;
+    /** Fetch the current manifest; keep the previous one on transient failure. */
+    private refreshManifest;
+    unitCents(): number;
+    /** Local JWT verification; no network on the hot path. */
+    verify(authHeader: string | undefined): Promise<VerifiedAgent | null>;
+    /**
+     * Gate and meter one paid call (optimistic mode). Enforces the cap claim
+     * minus local spend since mint.
+     */
+    gate(agent: VerifiedAgent, tool: string, costCents?: number): {
+        ok: true;
+    } | {
+        ok: false;
+        body: Err402Body;
+    };
+    /**
+     * Strict-mode gate for high-value routes: one synchronous cap check against
+     * the control plane before allowing the call. Trades ~one round trip for
+     * exactness; falls CLOSED on control-plane failure (a strict route would
+     * rather refuse than overspend).
+     */
+    gateStrict(agent: VerifiedAgent, tool: string, costCents?: number): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        body: Err402Body;
+    }>;
+    challenge(accountId: string, reason: Parameters<typeof err402>[0]): Err402Body;
+    private enqueue;
+    /** At-least-once delivery; server-side idempotency makes redelivery safe. */
+    flush(): Promise<void>;
+    private pollRevocations;
+    stop(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,200 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { randomUUID } from "node:crypto";
+import { err402 } from "@tollbase/core/types";
+/**
+ * Framework-agnostic middleware core. Design principle P1: the vendor's hot
+ * path never synchronously depends on the control plane.
+ *   - Token verification is local (jose caches the JWKS).
+ *   - Spend caps enforce optimistically from the `cap` claim minus local
+ *     spend since mint; the control plane reconciles at every key refresh,
+ *     bounding overspend to one 15-minute TTL window by design.
+ *   - Revocation is a pull feed: an in-TTL token dies within one poll
+ *     interval, still without a hot-path network call.
+ *   - Usage streams asynchronously with client idempotency keys, so
+ *     at-least-once delivery cannot double-bill.
+ */
+export class Tollbase {
+    cfg;
+    jwks;
+    manifest = null;
+    localSpend = new Map(); // token jti -> cents spent since mint
+    queue = [];
+    flushTimer = null;
+    revokedJtis = new Set();
+    revocationCursor = "1970-01-01";
+    revocationTimer = null;
+    manifestTimer = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.jwks = createRemoteJWKSet(new URL(`${cfg.controlPlaneUrl}/jwks.json`));
+    }
+    /** Load the service manifest and start background loops. Call once at boot. */
+    async init() {
+        await this.refreshManifest();
+        if (!this.manifest)
+            throw new Error(`tollbase: cannot load manifest for ${this.cfg.serviceSlug}`);
+        this.flushTimer = setInterval(() => void this.flush(), this.cfg.flushMs ?? 2000);
+        this.flushTimer.unref?.();
+        const mrMs = this.cfg.manifestRefreshMs ?? 60_000;
+        if (mrMs > 0) {
+            this.manifestTimer = setInterval(() => void this.refreshManifest(), mrMs);
+            this.manifestTimer.unref?.();
+        }
+        const pollMs = this.cfg.revocationPollMs ?? 30_000;
+        if (pollMs > 0) {
+            this.revocationTimer = setInterval(() => void this.pollRevocations(), pollMs);
+            this.revocationTimer.unref?.();
+            await this.pollRevocations(); // pick up pre-existing revocations at boot
+        }
+    }
+    /** Fetch the current manifest; keep the previous one on transient failure. */
+    async refreshManifest() {
+        try {
+            const r = await fetch(`${this.cfg.controlPlaneUrl}/services/${this.cfg.serviceSlug}/manifest`);
+            if (r.ok)
+                this.manifest = (await r.json());
+        }
+        catch {
+            // Control plane unreachable: the cached manifest keeps serving (P1).
+        }
+    }
+    unitCents() {
+        return this.manifest?.plans[0]?.unit_cents ?? 0;
+    }
+    /** Local JWT verification; no network on the hot path. */
+    async verify(authHeader) {
+        if (!authHeader?.startsWith("Bearer "))
+            return null;
+        try {
+            const { payload } = await jwtVerify(authHeader.slice(7), this.jwks, {
+                issuer: "tollbase",
+                algorithms: ["ES256"],
+            });
+            if (payload.svc !== this.cfg.serviceSlug)
+                return null;
+            const jti = String(payload.jti ?? "");
+            if (this.revokedJtis.has(jti))
+                return null;
+            return {
+                accountId: payload.sub,
+                scopes: (typeof payload.scope === "string" ? payload.scope : "").split(" ").filter(Boolean),
+                capCents: Number(payload.cap ?? 0),
+                iat: Number(payload.iat),
+                jti,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Gate and meter one paid call (optimistic mode). Enforces the cap claim
+     * minus local spend since mint.
+     */
+    gate(agent, tool, costCents = this.unitCents()) {
+        // Keyed by jti: each minted token carries its own cap claim and its own
+        // local ledger (iat has one-second resolution and can collide on rotation).
+        const key = agent.jti;
+        const spent = this.localSpend.get(key) ?? 0;
+        if (spent + costCents > agent.capCents) {
+            return { ok: false, body: this.challenge(agent.accountId, "cap_exceeded") };
+        }
+        this.localSpend.set(key, spent + costCents);
+        this.enqueue(agent.accountId, tool, 1, costCents);
+        return { ok: true };
+    }
+    /**
+     * Strict-mode gate for high-value routes: one synchronous cap check against
+     * the control plane before allowing the call. Trades ~one round trip for
+     * exactness; falls CLOSED on control-plane failure (a strict route would
+     * rather refuse than overspend).
+     */
+    async gateStrict(agent, tool, costCents = this.unitCents()) {
+        // Drain this instance's own metering queue first so the ledger the
+        // control plane consults reflects everything we already allowed.
+        await this.flush();
+        try {
+            const r = await fetch(`${this.cfg.controlPlaneUrl}/internal/cap-check`, {
+                method: "POST",
+                headers: { "content-type": "application/json", "x-tollbase-service-key": this.cfg.serviceKey },
+                body: JSON.stringify({ account_id: agent.accountId, cost_cents: costCents }),
+            });
+            const body = (await r.json());
+            if (!r.ok || !body.allowed)
+                return { ok: false, body: this.challenge(agent.accountId, "cap_exceeded") };
+        }
+        catch {
+            return { ok: false, body: this.challenge(agent.accountId, "cap_exceeded") };
+        }
+        // Record the spend locally as well, so optimistic gates on the same
+        // token account for what strict routes consumed.
+        const key = agent.jti;
+        this.localSpend.set(key, (this.localSpend.get(key) ?? 0) + costCents);
+        this.enqueue(agent.accountId, tool, 1, costCents);
+        return { ok: true };
+    }
+    challenge(accountId, reason) {
+        return err402(reason, {
+            accountId,
+            topupUrl: "/agent/topup-request", // vendor-origin proxy path; agents keep one origin
+            plans: this.manifest?.plans ?? [],
+        });
+    }
+    enqueue(accountId, tool, units, costCents) {
+        this.queue.push({
+            idempotency_key: randomUUID(),
+            account_id: accountId,
+            tool,
+            units,
+            cost_cents: costCents,
+            occurred_at: new Date().toISOString(),
+        });
+        if (this.queue.length >= 20)
+            void this.flush();
+    }
+    /** At-least-once delivery; server-side idempotency makes redelivery safe. */
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0, this.queue.length);
+        try {
+            const r = await fetch(`${this.cfg.controlPlaneUrl}/usage`, {
+                method: "POST",
+                headers: { "content-type": "application/json", "x-tollbase-service-key": this.cfg.serviceKey },
+                body: JSON.stringify({ events: batch }),
+            });
+            if (!r.ok)
+                throw new Error(`usage ingest ${r.status}`);
+        }
+        catch {
+            this.queue.unshift(...batch); // retry on the next tick; dedup on the server
+        }
+    }
+    async pollRevocations() {
+        try {
+            const r = await fetch(`${this.cfg.controlPlaneUrl}/revocations?since=${encodeURIComponent(this.revocationCursor)}`, { headers: { "x-tollbase-service-key": this.cfg.serviceKey } });
+            if (!r.ok)
+                return;
+            const body = (await r.json());
+            for (const rec of body.revocations)
+                this.revokedJtis.add(rec.jti);
+            if (body.revocations.length) {
+                const last = body.revocations[body.revocations.length - 1];
+                if (last)
+                    this.revocationCursor = last.revoked_at;
+            }
+        }
+        catch {
+            // Transient failure: keep the previous cursor; the next poll catches up.
+        }
+    }
+    async stop() {
+        if (this.flushTimer)
+            clearInterval(this.flushTimer);
+        if (this.revocationTimer)
+            clearInterval(this.revocationTimer);
+        if (this.manifestTimer)
+            clearInterval(this.manifestTimer);
+        await this.flush();
+    }
+}

package/dist/mcp.d.ts

@@ -0,0 +1,28 @@
+import type { Tollbase } from "./index.js";
+/**
+ * MCP integration without a hard dependency on any MCP SDK version.
+ *
+ * MCP servers speak JSON-RPC over a transport that carries HTTP headers
+ * (Streamable HTTP). This wrapper factors the Tollbase concerns — verify,
+ * scope, gate, meter — into a single function the vendor applies to each
+ * paid tool handler, whatever SDK they use:
+ *
+ *   server.registerTool("enrich", schema,
+ *     paidTool(dm, "enrich", "enrich:read", async (args) => doEnrich(args)));
+ *
+ * The bearer token is read from the request's Authorization header (exposed
+ * by MCP SDKs via the per-request extra/context object; pass an accessor if
+ * yours differs). On a cap violation the tool returns an MCP tool error
+ * whose text is the machine-readable 402 JSON, so agent frameworks can parse
+ * the same payload they would receive over plain HTTP.
+ */
+export interface McpToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export declare function paidTool<Args>(dm: Tollbase, tool: string, requiredScope: string, handler: (args: Args) => Promise<McpToolResult | {
+    [k: string]: unknown;
+}>, getAuthHeader?: (extra: unknown) => string | undefined): (args: Args, extra?: unknown) => Promise<McpToolResult>;

package/dist/mcp.js

@@ -0,0 +1,38 @@
+import { err402 } from "@tollbase/core/types";
+export function paidTool(dm, tool, requiredScope, handler, getAuthHeader = defaultAuthAccessor) {
+    return async (args, extra) => {
+        const agent = await dm.verify(getAuthHeader(extra));
+        if (!agent) {
+            return mcpError({
+                ...err402("not_claimed", { plans: dm.manifest?.plans ?? [] }),
+                message: "Missing or invalid bearer token. Register via the service manifest.",
+            });
+        }
+        if (!agent.scopes.includes(requiredScope)) {
+            return mcpError({
+                ...dm.challenge(agent.accountId, "no_plan"),
+                message: `Scope ${requiredScope} not granted.`,
+            });
+        }
+        const gate = dm.gate(agent, tool);
+        if (!gate.ok)
+            return mcpError(gate.body);
+        const out = await handler(args);
+        // Pass through well-formed MCP results; wrap plain objects as text.
+        if (out && typeof out === "object" && "content" in out)
+            return out;
+        return { content: [{ type: "text", text: JSON.stringify(out) }] };
+    };
+}
+function mcpError(body) {
+    return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+}
+/**
+ * Default accessor for the Authorization header across common MCP SDK shapes
+ * ({requestInfo:{headers}} in the TypeScript SDK's Streamable HTTP transport).
+ */
+function defaultAuthAccessor(extra) {
+    const e = extra;
+    const h = e?.requestInfo?.headers?.authorization ?? e?.requestInfo?.headers?.Authorization;
+    return Array.isArray(h) ? h[0] : h;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@tollbase/middleware",
+  "version": "0.3.0",
+  "description": "Tollbase vendor middleware: let AI agents become paying customers of your API or MCP server.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./express": {
+      "source": "./src/express.ts",
+      "types": "./dist/express.d.ts",
+      "default": "./dist/express.js"
+    },
+    "./mcp": {
+      "source": "./src/mcp.ts",
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    }
+  },
+  "dependencies": {
+    "@tollbase/core": "0.3.0",
+    "jose": "^5.9.2"
+  },
+  "peerDependencies": {
+    "express": "^4.19.2"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tollbase/tollbase.git"
+  },
+  "homepage": "https://tollbase.dev",
+  "keywords": [
+    "ai-agents",
+    "agents",
+    "billing",
+    "metering",
+    "mcp",
+    "payments",
+    "402",
+    "usage-based"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}