@katrinalaszlo/agentkey-clerk 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# agentkey-clerk
+
+Spend caps for [Clerk](https://clerk.com) M2M tokens. Clerk authenticates your agent; agentkey-clerk caps what it can spend, scopes what it can do, and sets when its access ends.
+
+## Why
+
+Clerk's [machine-to-machine (M2M) tokens](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens) authenticate your agents: which machine is calling, and which machines it may talk to. What they don't do is cap how much a machine can spend, meter its usage, or scope what it can do. So once your agent has a valid M2M token, nothing stops it from burning through a month of budget in twenty minutes.
+
+This package adds that layer. The agent keeps carrying its Clerk M2M token. You add one middleware, and every request is checked against a per-machine budget, scope, and expiry before it runs.
+
+| Layer | What it controls | Who covers it |
+|---|---|---|
+| Identity | Which machine is calling | **Clerk M2M** |
+| Budget | How much this machine can spend | **agentkey** |
+| Scope | What this machine can do | **agentkey** |
+| Expiry | When access ends | **agentkey** |
+
+Built on [`@katrinalaszlo/agentkey`](https://github.com/katrinalaszlo/agentkey).
+
+## Install
+
+```bash
+npm install @katrinalaszlo/agentkey-clerk @katrinalaszlo/agentkey
+```
+
+You bring your own Clerk client (`@clerk/backend` or `@clerk/express`) and a Postgres pool — this package doesn't wrap either.
+
+## Quick start
+
+```typescript
+import express from "express";
+import pg from "pg";
+import { createClerkClient } from "@clerk/backend";
+import { AgentKey } from "@katrinalaszlo/agentkey";
+import { clerkAgentKeyMiddleware, trackByM2M } from "@katrinalaszlo/agentkey-clerk";
+
+const pool = new pg.Pool();
+const ak = new AgentKey({ pool });
+await ak.migrate(); // adds the columns agentkey needs to your keys table
+
+const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY });
+
+const app = express();
+
+app.use(
+  "/api/agent",
+  clerkAgentKeyMiddleware({
+    clerkClient,
+    ak,
+    // Applied the first time each machine is seen.
+    defaults: { scopes: ["proxy.chat"], budgetCents: 5000, budgetPeriod: "month" },
+    scope: "proxy.chat", // optional: required capability for this route
+  }),
+);
+
+// Inside a handler, after the agent's billable work:
+app.post("/api/agent/chat", async (req, res) => {
+  const cost = await callTheModel(req.body);
+  await trackByM2M(ak, req.m2m!.subject, cost.cents);
+  res.json(cost.result);
+});
+```
+
+The agent calls your API with its Clerk M2M token in `Authorization: Bearer <token>`. The middleware:
+
+1. verifies the token with Clerk (`clerkClient.m2m.verify`),
+2. provisions a budget row for the machine on first sight (from `onFirstSeen` or `defaults`),
+3. enforces budget, scope, and expiry,
+4. attaches `req.m2m` (the verified token) and `req.agentKey` (the budget state).
+
+## Responses
+
+| Condition | Status |
+|---|---|
+| Valid, in budget, has scope | `next()` |
+| Missing `Bearer` token | `401 Missing M2M token` |
+| Revoked or expired Clerk token | `401 invalid_token` |
+| Over budget | `429 budget_exceeded` |
+| Missing required scope | `403 insufficient_scope` |
+| Clerk or DB fault | `500 auth_unavailable` (fails closed) |
+
+## Per-machine budgets
+
+Pass `onFirstSeen` to set budget/scope from the verified token instead of a flat default:
+
+```typescript
+clerkAgentKeyMiddleware({
+  clerkClient,
+  ak,
+  onFirstSeen: (token) => ({
+    accountId: (token.claims?.org_id as string) ?? token.subject,
+    scopes: ["proxy.chat"],
+    budgetCents: 2000,
+    budgetPeriod: "day",
+    expiresIn: "30d",
+  }),
+});
+```
+
+`accountId` defaults to the machine subject if you don't set it.
+
+## A note on scope
+
+agentkey's `scopes` (what the agent may *do* — `proxy.chat`, `usage.read`) are not the same as Clerk's machine scopes (which machines may *talk to* which). This package enforces the agentkey kind. Set them in `defaults`/`onFirstSeen`.
+
+## What it doesn't do
+
+This is the per-machine spend layer only. It does not do hierarchical org > team > agent budget composition, and it does not put a human's Clerk session on the agent's request path (the agent carries its own M2M token — that's the point). For non-Clerk apps, use [`@katrinalaszlo/agentkey`](https://github.com/katrinalaszlo/agentkey) directly with its own `ak_` keys.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { Request, Response, NextFunction } from "express";
+import type { AgentKey, ValidateResult, EnsureSubjectOptions } from "@katrinalaszlo/agentkey";
+export interface VerifiedM2MToken {
+    id: string;
+    subject: string;
+    scopes?: string[];
+    claims?: Record<string, unknown> | null;
+    revoked?: boolean;
+    expired?: boolean;
+    expiration?: number | null;
+}
+export interface ClerkM2MClient {
+    m2m: {
+        verify(params: {
+            token: string;
+        }): Promise<VerifiedM2MToken>;
+    };
+}
+export interface ClerkAgentKeyOptions {
+    clerkClient: ClerkM2MClient;
+    ak: AgentKey;
+    defaults?: EnsureSubjectOptions;
+    onFirstSeen?: (token: VerifiedM2MToken) => EnsureSubjectOptions;
+    scope?: string;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            m2m?: VerifiedM2MToken;
+            agentKey?: ValidateResult;
+        }
+    }
+}
+export declare function clerkAgentKeyMiddleware(opts: ClerkAgentKeyOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
+export declare function trackByM2M(ak: AgentKey, subject: string, costCents: number): Promise<import("@katrinalaszlo/agentkey").TrackUsageResult>;

package/dist/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clerkAgentKeyMiddleware = clerkAgentKeyMiddleware;
+exports.trackByM2M = trackByM2M;
+// Express middleware: verify the incoming Clerk M2M token, then enforce
+// agentkey's budget/scope/expiry on the machine behind it. Clerk says *who* the
+// machine is; agentkey says *how much it may spend and do*. On first sight of a
+// machine, its budget row is provisioned from `onFirstSeen`/`defaults`.
+function clerkAgentKeyMiddleware(opts) {
+    const { clerkClient, ak, defaults, onFirstSeen, scope } = opts;
+    return async (req, res, next) => {
+        try {
+            const authHeader = req.headers.authorization;
+            if (!authHeader?.startsWith("Bearer ")) {
+                return res.status(401).json({ error: "Missing M2M token" });
+            }
+            const token = authHeader.slice(7);
+            const verified = await clerkClient.m2m.verify({ token });
+            // Clerk already computed these; don't re-derive them.
+            if (verified.revoked || verified.expired) {
+                return res.status(401).json({ error: "invalid_token" });
+            }
+            const subject = verified.subject;
+            let result = await ak.validateBySubject(subject);
+            // First time we've seen this machine: provision its budget row, then
+            // re-validate. ensureSubject is idempotent, so a concurrent first request
+            // racing on the same machine is safe.
+            if (!result.valid && result.reason === "invalid") {
+                await ak.ensureSubject(subject, onFirstSeen?.(verified) ?? defaults ?? {});
+                result = await ak.validateBySubject(subject);
+            }
+            if (!result.valid) {
+                const status = result.reason === "budget_exceeded" ? 429 : 401;
+                return res.status(status).json({ error: result.reason });
+            }
+            if (scope && !ak.hasScope(result, scope)) {
+                return res.status(403).json({
+                    error: "insufficient_scope",
+                    required: scope,
+                    available: result.scopes,
+                });
+            }
+            req.m2m = verified;
+            req.agentKey = result;
+            next();
+        }
+        catch (err) {
+            // clerkClient.m2m.verify() and the agentkey DB lookups reject on routine
+            // faults (network, pool exhaustion, statement timeout). Express 4 does not
+            // forward a rejected promise from async middleware, so without this the
+            // request hangs. Fail closed with a 500.
+            console.error("clerkAgentKeyMiddleware error:", err);
+            return res.status(500).json({ error: "auth_unavailable" });
+        }
+    };
+}
+// Charge a machine's budget after its billable work (e.g. after an LLM call).
+// Thin wrapper over agentkey's subject-keyed usage tracking.
+function trackByM2M(ak, subject, costCents) {
+    return ak.trackUsageBySubject(subject, { costCents });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@katrinalaszlo/agentkey-clerk",
+  "version": "0.1.0",
+  "description": "Spend caps for Clerk M2M tokens — budget, scope, and expiry on top of Clerk machine auth",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "clerk",
+    "m2m",
+    "machine-to-machine",
+    "agent",
+    "budget",
+    "spend",
+    "scoped-keys",
+    "api-key",
+    "agentkey",
+    "agent-experience"
+  ],
+  "author": "Katrina Laszlo <katrina.j.laszlo@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/katrinalaszlo/agentkey-clerk.git"
+  },
+  "peerDependencies": {
+    "@katrinalaszlo/agentkey": ">=0.2.0",
+    "express": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@katrinalaszlo/agentkey": "file:../agentkey",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0",
+    "express": "^4.0.0",
+    "@types/express": "^4.0.0"
+  }
+}