@katrinalaszlo/agentkey-clerk 0.1.0 → 0.2.0

package/README.md

@@ -1,18 +1,20 @@
 # 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.
+Spend caps for the [Clerk](https://clerk.com) API keys your users create. Your customers make API keys with Clerk; agentkey-clerk caps what each one 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.
+When you give your customers [API keys](https://clerk.com/docs/guides/development/machine-auth/api-keys) through Clerk, each key calls your API on that customer's behalf. Clerk issues, verifies, and revokes the key. What it doesn't do is cap how much a customer's key can spend against your paid API, so one customer's runaway script can burn through usage that affects everyone else.
 
-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.
+agentkey-clerk adds that layer. The customer keeps using their Clerk-issued key. You add one middleware, and every request is checked against a per-customer budget, scope, and expiry before it runs. It caps **dollars** (not just request counts) and blocks the call the moment a key crosses its budget.
+
+> agentkey-clerk is an independent, open-source companion to Clerk. It is not affiliated with Clerk.
 
 | 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** |
+| Identity | Which customer's key is calling | **Clerk API Keys** |
+| Budget | How much this key can spend (in dollars) | **agentkey** |
+| Scope | What this key can do | **agentkey** |
 | Expiry | When access ends | **agentkey** |
 
 Built on [`@katrinalaszlo/agentkey`](https://github.com/katrinalaszlo/agentkey).
@@ -32,7 +34,7 @@ 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";
+import { clerkApiKeyMiddleware, trackByApiKey } from "@katrinalaszlo/agentkey-clerk";
 
 const pool = new pg.Pool();
 const ak = new AgentKey({ pool });
@@ -43,69 +45,72 @@ const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY
 const app = express();
 
 app.use(
-  "/api/agent",
-  clerkAgentKeyMiddleware({
+  "/api",
+  clerkApiKeyMiddleware({
     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
+    // Applied the first time each customer's key is seen.
+    defaults: { budgetCents: 5000, budgetPeriod: "month" },
   }),
 );
 
-// Inside a handler, after the agent's billable work:
-app.post("/api/agent/chat", async (req, res) => {
+// Inside a handler, after the customer's billable work:
+app.post("/api/chat", async (req, res) => {
   const cost = await callTheModel(req.body);
-  await trackByM2M(ak, req.m2m!.subject, cost.cents);
+  await trackByApiKey(ak, req.clerkApiKey!.subject, cost.cents);
   res.json(cost.result);
 });
 ```
 
-The agent calls your API with its Clerk M2M token in `Authorization: Bearer <token>`. The middleware:
+The customer calls your API with their Clerk API key in `Authorization: Bearer <key>`. 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`),
+1. verifies the key with Clerk (`clerkClient.apiKeys.verify`),
+2. provisions a budget row for the customer — the key's `subject`, a `user_` or `org_` id — on first sight,
 3. enforces budget, scope, and expiry,
-4. attaches `req.m2m` (the verified token) and `req.agentKey` (the budget state).
+4. attaches `req.clerkApiKey` (the verified key) 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` |
+| Missing `Bearer` key | `401 Missing API key` |
+| Invalid / revoked / expired key | `401 invalid_key` |
 | Over budget | `429 budget_exceeded` |
 | Missing required scope | `403 insufficient_scope` |
-| Clerk or DB fault | `500 auth_unavailable` (fails closed) |
+| DB fault | `500 auth_unavailable` (fails closed) |
 
-## Per-machine budgets
+## Per-customer budgets
 
-Pass `onFirstSeen` to set budget/scope from the verified token instead of a flat default:
+Pass `onFirstSeen` to set budget/scope from the verified key — for example, read a plan tier off the key's `claims`:
 
 ```typescript
-clerkAgentKeyMiddleware({
+clerkApiKeyMiddleware({
   clerkClient,
   ak,
-  onFirstSeen: (token) => ({
-    accountId: (token.claims?.org_id as string) ?? token.subject,
+  onFirstSeen: (apiKey) => ({
+    accountId: apiKey.subject, // user_xxx or org_xxx
     scopes: ["proxy.chat"],
-    budgetCents: 2000,
-    budgetPeriod: "day",
+    budgetCents: apiKey.claims?.tier === "pro" ? 20000 : 2000,
+    budgetPeriod: "month",
     expiresIn: "30d",
   }),
 });
 ```
 
-`accountId` defaults to the machine subject if you don't set it.
+`accountId` defaults to the key's `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`.
+agentkey's `scopes` (what a key may *do* — `proxy.chat`, `usage.read`) are enforced by this package against the budget row. They're separate from Clerk's own API-key scopes. Set them in `defaults`/`onFirstSeen`.
+
+## Also: internal services (Clerk M2M)
+
+If you also want to cap your *own* backend services (microservices, workers) that authenticate with [Clerk M2M tokens](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens) — which are distinct from customer API keys — use `clerkAgentKeyMiddleware` + `trackByM2M`. Same shape, keyed on the M2M machine subject. That's internal cost control rather than customer spend caps.
 
 ## 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.
+Per-key dollar spend caps only. No hierarchical org > team > key budget composition. For non-Clerk apps, use [`@katrinalaszlo/agentkey`](https://github.com/katrinalaszlo/agentkey) directly with its own `ak_` keys.
 
 ## License
 

package/dist/index.d.ts

@@ -27,9 +27,35 @@ declare global {
     namespace Express {
         interface Request {
             m2m?: VerifiedM2MToken;
+            clerkApiKey?: VerifiedApiKey;
             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>;
+export interface VerifiedApiKey {
+    id: string;
+    name?: string;
+    description?: string | null;
+    subject: string;
+    scopes?: string[];
+    claims?: Record<string, unknown> | null;
+    revoked?: boolean;
+    expired?: boolean;
+    expiration?: number | null;
+}
+export interface ClerkApiKeyClient {
+    apiKeys: {
+        verify(secret: string): Promise<VerifiedApiKey>;
+    };
+}
+export interface ClerkApiKeyOptions {
+    clerkClient: ClerkApiKeyClient;
+    ak: AgentKey;
+    defaults?: EnsureSubjectOptions;
+    onFirstSeen?: (apiKey: VerifiedApiKey) => EnsureSubjectOptions;
+    scope?: string;
+}
+export declare function clerkApiKeyMiddleware(opts: ClerkApiKeyOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;
+export declare function trackByApiKey(ak: AgentKey, subject: string, costCents: number): Promise<import("@katrinalaszlo/agentkey").TrackUsageResult>;

package/dist/index.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clerkAgentKeyMiddleware = clerkAgentKeyMiddleware;
 exports.trackByM2M = trackByM2M;
+exports.clerkApiKeyMiddleware = clerkApiKeyMiddleware;
+exports.trackByApiKey = trackByApiKey;
 // 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
@@ -59,3 +61,69 @@ function clerkAgentKeyMiddleware(opts) {
 function trackByM2M(ak, subject, costCents) {
     return ak.trackUsageBySubject(subject, { costCents });
 }
+// Express middleware: verify the incoming Clerk API key, then enforce agentkey's
+// budget/scope/expiry on the customer behind it. The customer keeps using their
+// Clerk-issued key; agentkey caps what that key can spend.
+function clerkApiKeyMiddleware(opts) {
+    const { clerkClient, ak, defaults, onFirstSeen, scope } = opts;
+    return async (req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader?.startsWith("Bearer ")) {
+            return res.status(401).json({ error: "Missing API key" });
+        }
+        const secret = authHeader.slice(7);
+        let verified;
+        try {
+            // Clerk's verify throws on an invalid, revoked, or expired key. Treat any
+            // verify failure as a denied key (401). Failing closed is the safe default
+            // even if the cause was a transient Clerk fault — access is denied, not
+            // granted. (Same posture as the M2M middleware's 401 on a bad token.)
+            verified = await clerkClient.apiKeys.verify(secret);
+        }
+        catch {
+            return res.status(401).json({ error: "invalid_key" });
+        }
+        // Defensive: the SDK throws on these, but honor the flags if a future verify
+        // path returns them instead.
+        if (verified.revoked || verified.expired) {
+            return res.status(401).json({ error: "invalid_key" });
+        }
+        try {
+            const subject = verified.subject;
+            let result = await ak.validateBySubject(subject);
+            // First time we've seen this customer's key: provision its budget row,
+            // then re-validate. ensureSubject is idempotent, so concurrent first
+            // requests are 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.clerkApiKey = verified;
+            req.agentKey = result;
+            next();
+        }
+        catch (err) {
+            // agentkey DB lookups reject on routine faults (pool exhaustion, timeout).
+            // Express 4 doesn't forward a rejected async-middleware promise, so fail
+            // closed with a 500.
+            console.error("clerkApiKeyMiddleware error:", err);
+            return res.status(500).json({ error: "auth_unavailable" });
+        }
+    };
+}
+// Charge a customer's budget after their billable work. Pass the verified key's
+// subject (req.clerkApiKey.subject).
+function trackByApiKey(ak, subject, costCents) {
+    return ak.trackUsageBySubject(subject, { costCents });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.2.0",
+  "description": "Dollar spend caps for the Clerk API keys your users create: per-customer budget, scope, and expiry (also supports Clerk M2M)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [