@agent-id/express 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-id
+
+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,106 @@
+# @agent-id/express
+
+Express.js middleware that automatically detects AI-agent traffic and requires a valid [AgentID](https://agentpass.vercel.app) JWT. Human browser traffic always passes through untouched.
+
+## Install
+
+```bash
+npm install @agent-id/express
+```
+
+Requires `express >= 4` and `node >= 18`.
+
+## Setup — 2 steps
+
+### 1. Add the middleware
+
+```ts
+import express from 'express';
+import { agentID } from '@agent-id/express';
+
+const app = express();
+
+app.use(agentID());
+
+app.listen(3000);
+```
+
+That's it. The middleware now:
+- Lets all human browser traffic through unchanged
+- Requires a valid AgentID JWT from any AI agent / bot
+- Returns `403 AGENT_UNAUTHORIZED` when the JWT is missing or invalid
+
+### 2. Read the verified identity in your route handlers (optional)
+
+```ts
+app.get('/api/data', (req, res) => {
+  const agent = req.agentId;
+
+  if (agent?.verified) {
+    // Verified AI agent — claims are fully typed
+    console.log(agent.claims.sub);          // pseudonymous stable user ID
+    console.log(agent.claims.auth_method);  // "bankid"
+    return res.json({ ok: true, sub: agent.claims.sub });
+  }
+
+  // Human traffic: agent.reason === 'not_agent'
+  return res.json({ ok: true });
+});
+```
+
+`req.agentId` is typed automatically — no extra TypeScript configuration needed.
+
+## How agents authenticate
+
+Agents add one header to every request:
+
+```
+Authorization: Bearer <agentid-jwt>
+```
+
+The JWT is obtained by completing a BankID flow at [agentpass.vercel.app](https://agentpass.vercel.app). Tokens are valid for 1 hour.
+
+## Options
+
+All options are optional — `agentID()` with no arguments works out of the box.
+
+```ts
+app.use(agentID({
+  // Return 403 when an agent has no valid token (default: true).
+  // Set to false to let unverified agents through (useful for logging / gradual rollout).
+  blockUnauthorizedAgents: true,
+
+  // Override the JWKS endpoint — only needed if you self-host AgentID.
+  jwksUrl: 'https://your-agentid.example.com/api/jwks',
+
+  // Clock skew tolerance in seconds (default: 30).
+  clockTolerance: 30,
+
+  // Fully custom response when an agent is rejected.
+  onUnauthorizedAgent: (req, res, next, reason) => {
+    res.status(403).json({ error: 'No AgentID token', reason });
+  },
+}));
+```
+
+## What gets verified
+
+Verification is **fully offline** after the first request. The public key is fetched once from the AgentID JWKS endpoint and cached for 1 hour — no per-request network call.
+
+| Check | Requirement |
+|---|---|
+| Signature | RS256 — `alg:none` and HS256 are explicitly rejected |
+| Issuer (`iss`) | Must equal `"agentid"` |
+| Expiry (`exp`) | Must be in the future |
+| `auth_method` | Must equal `"bankid"` |
+
+## JWT claims
+
+| Field | Description |
+|---|---|
+| `sub` | Pseudonymous stable user ID (HMAC-SHA256 of BankID personal number — non-reversible, same person always gets the same ID) |
+| `auth_method` | Always `"bankid"` |
+| `iss` | `"agentid"` |
+| `exp` | Unix timestamp — 1 hour from issue |
+| `iat` | Unix timestamp — when issued |
+| `jti` | Unique token ID |

package/dist/index.d.mts

@@ -0,0 +1,152 @@
+import { Request, Response, NextFunction } from 'express';
+import { IncomingHttpHeaders } from 'node:http';
+
+/**
+ * JWT claims present in every AgentID token.
+ *
+ * The `sub` field is a pseudonymous identifier derived via HMAC-SHA256 of the
+ * user's BankID personal number. It is stable per person but non-reversible —
+ * organisations cannot extract the personal number from it.
+ */
+interface AgentIDClaims {
+    /** Pseudonymous, stable per-user identifier (HMAC-SHA256 of personal number). */
+    sub: string;
+    /** Issuer — always "agentid". */
+    iss: string;
+    /** Issued-at Unix timestamp. */
+    iat: number;
+    /** Expiry Unix timestamp (1 hour after iat). */
+    exp: number;
+    /** Unique JWT ID — enables token logging / replay detection on your side. */
+    jti: string;
+    /** Authentication method — always "bankid" in this version. */
+    auth_method: "bankid";
+}
+interface AgentIDVerified {
+    verified: true;
+    claims: AgentIDClaims;
+}
+interface AgentIDUnverified {
+    verified: false;
+    /** Why verification was skipped or failed. */
+    reason: "not_agent" | "no_token" | "invalid_token";
+}
+/** Result attached to every request processed by the AgentID middleware. */
+type AgentIDResult = AgentIDVerified | AgentIDUnverified;
+interface VerifierOptions {
+    /**
+     * URL of the AgentID JWKS endpoint.
+     * Must use HTTPS (except `localhost` / `127.0.0.1` in development).
+     *
+     * @default 'https://agentpass.vercel.app/api/jwks'
+     */
+    jwksUrl?: string;
+    /**
+     * Block agent requests that carry no valid AgentID token.
+     * When `false` the middleware still runs but sets an unverified result
+     * on the request instead of returning 403.
+     *
+     * @default true
+     */
+    blockUnauthorizedAgents?: boolean;
+    /**
+     * Allowed clock skew in seconds when verifying JWT expiry.
+     * Protects against minor clock drift between issuer and verifier.
+     *
+     * @default 30
+     */
+    clockTolerance?: number;
+}
+
+declare global {
+    namespace Express {
+        interface Request {
+            /** AgentID verification result set by the agentID() middleware. */
+            agentId?: AgentIDResult;
+        }
+    }
+}
+type AgentIDMiddlewareOptions = VerifierOptions & {
+    /**
+     * Custom handler invoked when an agent is detected but has no valid token.
+     * Call `next()` to pass through, or `res.status(403).json(...)` to block.
+     * If omitted, the default behaviour is controlled by `blockUnauthorizedAgents`.
+     */
+    onUnauthorizedAgent?: (req: Request, res: Response, next: NextFunction, reason: string) => void;
+};
+/**
+ * Express middleware that detects AI-agent traffic and enforces AgentID
+ * JWT authentication.
+ *
+ * Sets `req.agentId` on every request:
+ *  - `{ verified: false, reason: 'not_agent' }` — human traffic (always passes through)
+ *  - `{ verified: true, claims }` — agent with valid JWT
+ *  - `{ verified: false, reason: 'no_token' | 'invalid_token' }` — blocked agent
+ *    (returns 403 when `blockUnauthorizedAgents: true`)
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { agentID } from '@agent-id/express';
+ *
+ * const app = express();
+ * app.use(agentID({ blockUnauthorizedAgents: true }));
+ *
+ * app.get('/api/data', (req, res) => {
+ *   if (req.agentId?.verified) {
+ *     res.json({ sub: req.agentId.claims.sub });
+ *   } else {
+ *     res.status(403).json({ error: 'Unauthorized' });
+ *   }
+ * });
+ * ```
+ */
+declare function agentID(options?: AgentIDMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+interface VerifyTokenOptions {
+    jwksUrl?: string;
+    clockTolerance?: number;
+}
+/**
+ * Verify an AgentID JWT and return its decoded claims.
+ *
+ * Security guarantees
+ * ───────────────────
+ * • Signature   — RS256, verified against the live JWKS public key.
+ * • Algorithm   — strict allowlist `['RS256']`; alg:none and HS256 are
+ *                 rejected before signature verification even begins.
+ * • Issuer      — must be exactly "agentid".
+ * • Expiry      — enforced; configurable clock tolerance (default 30 s).
+ * • kid         — jose matches the JWT `kid` header to the JWKS automatically.
+ * • auth_method — validated at runtime; must equal "bankid".
+ *
+ * @throws if the token is invalid, expired, or fails any check.
+ */
+declare function verifyAgentIDToken(token: string, options?: VerifyTokenOptions): Promise<AgentIDClaims>;
+
+/**
+ * Bot / AI-agent detection for Express.js (Node.js).
+ *
+ * Mirrors the logic in @agent-id/nextjs but uses `IncomingHttpHeaders`
+ * from Node's `http` module instead of the Web `Headers` API.
+ */
+
+/**
+ * Returns `true` if the request appears to originate from an automated
+ * agent or bot rather than a human browser.
+ *
+ * @param headers - `req.headers` from an Express `Request`
+ */
+declare function isAgentRequest(headers: IncomingHttpHeaders): boolean;
+/**
+ * Extract the AgentID JWT from request headers.
+ *
+ * Checks:
+ *  1. `Authorization: Bearer <token>` (preferred)
+ *  2. `X-AgentID-Token` (fallback)
+ *
+ * @returns Raw JWT string or `null`.
+ */
+declare function extractToken(headers: IncomingHttpHeaders): string | null;
+
+export { type AgentIDClaims, type AgentIDMiddlewareOptions, type AgentIDResult, type AgentIDUnverified, type AgentIDVerified, type VerifierOptions, type VerifyTokenOptions, agentID, extractToken, isAgentRequest, verifyAgentIDToken };

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+import { Request, Response, NextFunction } from 'express';
+import { IncomingHttpHeaders } from 'node:http';
+
+/**
+ * JWT claims present in every AgentID token.
+ *
+ * The `sub` field is a pseudonymous identifier derived via HMAC-SHA256 of the
+ * user's BankID personal number. It is stable per person but non-reversible —
+ * organisations cannot extract the personal number from it.
+ */
+interface AgentIDClaims {
+    /** Pseudonymous, stable per-user identifier (HMAC-SHA256 of personal number). */
+    sub: string;
+    /** Issuer — always "agentid". */
+    iss: string;
+    /** Issued-at Unix timestamp. */
+    iat: number;
+    /** Expiry Unix timestamp (1 hour after iat). */
+    exp: number;
+    /** Unique JWT ID — enables token logging / replay detection on your side. */
+    jti: string;
+    /** Authentication method — always "bankid" in this version. */
+    auth_method: "bankid";
+}
+interface AgentIDVerified {
+    verified: true;
+    claims: AgentIDClaims;
+}
+interface AgentIDUnverified {
+    verified: false;
+    /** Why verification was skipped or failed. */
+    reason: "not_agent" | "no_token" | "invalid_token";
+}
+/** Result attached to every request processed by the AgentID middleware. */
+type AgentIDResult = AgentIDVerified | AgentIDUnverified;
+interface VerifierOptions {
+    /**
+     * URL of the AgentID JWKS endpoint.
+     * Must use HTTPS (except `localhost` / `127.0.0.1` in development).
+     *
+     * @default 'https://agentpass.vercel.app/api/jwks'
+     */
+    jwksUrl?: string;
+    /**
+     * Block agent requests that carry no valid AgentID token.
+     * When `false` the middleware still runs but sets an unverified result
+     * on the request instead of returning 403.
+     *
+     * @default true
+     */
+    blockUnauthorizedAgents?: boolean;
+    /**
+     * Allowed clock skew in seconds when verifying JWT expiry.
+     * Protects against minor clock drift between issuer and verifier.
+     *
+     * @default 30
+     */
+    clockTolerance?: number;
+}
+
+declare global {
+    namespace Express {
+        interface Request {
+            /** AgentID verification result set by the agentID() middleware. */
+            agentId?: AgentIDResult;
+        }
+    }
+}
+type AgentIDMiddlewareOptions = VerifierOptions & {
+    /**
+     * Custom handler invoked when an agent is detected but has no valid token.
+     * Call `next()` to pass through, or `res.status(403).json(...)` to block.
+     * If omitted, the default behaviour is controlled by `blockUnauthorizedAgents`.
+     */
+    onUnauthorizedAgent?: (req: Request, res: Response, next: NextFunction, reason: string) => void;
+};
+/**
+ * Express middleware that detects AI-agent traffic and enforces AgentID
+ * JWT authentication.
+ *
+ * Sets `req.agentId` on every request:
+ *  - `{ verified: false, reason: 'not_agent' }` — human traffic (always passes through)
+ *  - `{ verified: true, claims }` — agent with valid JWT
+ *  - `{ verified: false, reason: 'no_token' | 'invalid_token' }` — blocked agent
+ *    (returns 403 when `blockUnauthorizedAgents: true`)
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { agentID } from '@agent-id/express';
+ *
+ * const app = express();
+ * app.use(agentID({ blockUnauthorizedAgents: true }));
+ *
+ * app.get('/api/data', (req, res) => {
+ *   if (req.agentId?.verified) {
+ *     res.json({ sub: req.agentId.claims.sub });
+ *   } else {
+ *     res.status(403).json({ error: 'Unauthorized' });
+ *   }
+ * });
+ * ```
+ */
+declare function agentID(options?: AgentIDMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+interface VerifyTokenOptions {
+    jwksUrl?: string;
+    clockTolerance?: number;
+}
+/**
+ * Verify an AgentID JWT and return its decoded claims.
+ *
+ * Security guarantees
+ * ───────────────────
+ * • Signature   — RS256, verified against the live JWKS public key.
+ * • Algorithm   — strict allowlist `['RS256']`; alg:none and HS256 are
+ *                 rejected before signature verification even begins.
+ * • Issuer      — must be exactly "agentid".
+ * • Expiry      — enforced; configurable clock tolerance (default 30 s).
+ * • kid         — jose matches the JWT `kid` header to the JWKS automatically.
+ * • auth_method — validated at runtime; must equal "bankid".
+ *
+ * @throws if the token is invalid, expired, or fails any check.
+ */
+declare function verifyAgentIDToken(token: string, options?: VerifyTokenOptions): Promise<AgentIDClaims>;
+
+/**
+ * Bot / AI-agent detection for Express.js (Node.js).
+ *
+ * Mirrors the logic in @agent-id/nextjs but uses `IncomingHttpHeaders`
+ * from Node's `http` module instead of the Web `Headers` API.
+ */
+
+/**
+ * Returns `true` if the request appears to originate from an automated
+ * agent or bot rather than a human browser.
+ *
+ * @param headers - `req.headers` from an Express `Request`
+ */
+declare function isAgentRequest(headers: IncomingHttpHeaders): boolean;
+/**
+ * Extract the AgentID JWT from request headers.
+ *
+ * Checks:
+ *  1. `Authorization: Bearer <token>` (preferred)
+ *  2. `X-AgentID-Token` (fallback)
+ *
+ * @returns Raw JWT string or `null`.
+ */
+declare function extractToken(headers: IncomingHttpHeaders): string | null;
+
+export { type AgentIDClaims, type AgentIDMiddlewareOptions, type AgentIDResult, type AgentIDUnverified, type AgentIDVerified, type VerifierOptions, type VerifyTokenOptions, agentID, extractToken, isAgentRequest, verifyAgentIDToken };

package/dist/index.js

@@ -0,0 +1,222 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  agentID: () => agentID,
+  extractToken: () => extractToken,
+  isAgentRequest: () => isAgentRequest,
+  verifyAgentIDToken: () => verifyAgentIDToken
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/detect.ts
+var BOT_UA_PATTERNS = [
+  // OpenAI
+  /GPTBot/i,
+  /ChatGPT-User/i,
+  /OAI-SearchBot/i,
+  // Anthropic / Claude
+  /ClaudeBot/i,
+  /Claude-Web/i,
+  /anthropic-ai/i,
+  /Claude-User/i,
+  // Google
+  /Googlebot/i,
+  /Google-Extended/i,
+  /AdsBot-Google/i,
+  // Microsoft / Bing
+  /bingbot/i,
+  /msnbot/i,
+  // AI search engines
+  /PerplexityBot/i,
+  /YouBot/i,
+  // Common HTTP automation libraries
+  /python-requests/i,
+  /node-fetch/i,
+  /\baxios\b/i,
+  /\bgot\b\//i,
+  /\bundici\b/i,
+  /\bcurl\b/i,
+  /\bwget\b/i,
+  /\bhttpie\b/i,
+  // Generic crawler signals
+  /\bbot\b/i,
+  /\bcrawler\b/i,
+  /\bspider\b/i,
+  /\bscraper\b/i,
+  /\bfetcher\b/i,
+  // MCP / AgentID clients
+  /mcp-client/i,
+  /agentid-client/i
+];
+var BROWSER_UA_RE = /Mozilla\/5\.0/i;
+function single(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+function isAgentRequest(headers) {
+  const ua = single(headers["user-agent"]) ?? "";
+  if (!ua) return true;
+  if (BOT_UA_PATTERNS.some((p) => p.test(ua))) return true;
+  const cfRaw = single(headers["cf-bot-management"]);
+  if (cfRaw) {
+    try {
+      const parsed = JSON.parse(cfRaw);
+      if (typeof parsed.score === "number" && parsed.score < 30) return true;
+    } catch {
+    }
+  }
+  if (!BROWSER_UA_RE.test(ua) && !headers["accept-language"]) return true;
+  return false;
+}
+function extractToken(headers) {
+  const auth = single(headers["authorization"]) ?? "";
+  if (auth.startsWith("Bearer ")) {
+    const token = auth.slice(7).trim();
+    if (token) return token;
+  }
+  const custom = single(headers["x-agentid-token"])?.trim();
+  if (custom) return custom;
+  return null;
+}
+
+// src/verify.ts
+var import_jose = require("jose");
+var DEFAULT_JWKS_URL = "https://agentpass.vercel.app/api/jwks";
+var jwksSets = /* @__PURE__ */ new Map();
+function getJwks(rawUrl) {
+  if (!jwksSets.has(rawUrl)) {
+    const url = new URL(rawUrl);
+    const isLocal = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (url.protocol !== "https:" && !isLocal) {
+      throw new Error(
+        `[agent-id] jwksUrl must use HTTPS, received: ${rawUrl}`
+      );
+    }
+    jwksSets.set(
+      rawUrl,
+      (0, import_jose.createRemoteJWKSet)(url, {
+        cacheMaxAge: 60 * 60 * 1e3
+        // 1 hour in ms
+      })
+    );
+  }
+  return jwksSets.get(rawUrl);
+}
+async function verifyAgentIDToken(token, options = {}) {
+  const jwksUrl = options.jwksUrl ?? DEFAULT_JWKS_URL;
+  const JWKS = getJwks(jwksUrl);
+  const { payload } = await (0, import_jose.jwtVerify)(token, JWKS, {
+    issuer: "agentid",
+    // ↓ Critical — explicit allowlist prevents algorithm-confusion attacks.
+    //   Any token claiming alg:"none", alg:"HS256", or anything else is
+    //   rejected before signature verification.
+    algorithms: ["RS256"],
+    clockTolerance: options.clockTolerance ?? 30
+  });
+  if (payload.auth_method !== "bankid") {
+    throw new Error(
+      `[agent-id] JWT has invalid auth_method: expected "bankid", got "${payload.auth_method ?? "undefined"}"`
+    );
+  }
+  if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+    throw new Error("[agent-id] JWT is missing the sub claim");
+  }
+  return payload;
+}
+
+// src/middleware.ts
+var MANAGED_HEADERS = [
+  "x-agentid-verified",
+  "x-agentid-sub",
+  "x-agentid-claims"
+];
+function agentID(options = {}) {
+  const {
+    jwksUrl,
+    blockUnauthorizedAgents = true,
+    clockTolerance = 30,
+    onUnauthorizedAgent
+  } = options;
+  return async function agentIDMiddleware(req, res, next) {
+    for (const header of MANAGED_HEADERS) {
+      delete req.headers[header];
+    }
+    if (!isAgentRequest(req.headers)) {
+      req.agentId = { verified: false, reason: "not_agent" };
+      return next();
+    }
+    const token = extractToken(req.headers);
+    if (!token) {
+      return handleUnauthorized(
+        req,
+        res,
+        next,
+        "no_token",
+        'Agent request missing AgentID token. Provide "Authorization: Bearer <token>".',
+        blockUnauthorizedAgents,
+        onUnauthorizedAgent
+      );
+    }
+    let claims;
+    try {
+      claims = await verifyAgentIDToken(token, {
+        ...jwksUrl !== void 0 && { jwksUrl },
+        clockTolerance
+      });
+    } catch (err) {
+      console.warn(
+        "[agent-id] Token verification failed:",
+        err instanceof Error ? err.message : String(err)
+      );
+      return handleUnauthorized(
+        req,
+        res,
+        next,
+        "invalid_token",
+        "Invalid or expired AgentID token.",
+        blockUnauthorizedAgents,
+        onUnauthorizedAgent
+      );
+    }
+    req.agentId = { verified: true, claims };
+    return next();
+  };
+}
+function handleUnauthorized(req, res, next, reason, message, block, onUnauthorized) {
+  req.agentId = { verified: false, reason };
+  if (onUnauthorized) {
+    onUnauthorized(req, res, next, message);
+    return;
+  }
+  if (block) {
+    res.status(403).json({ error: "AGENT_UNAUTHORIZED", message });
+    return;
+  }
+  next();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  agentID,
+  extractToken,
+  isAgentRequest,
+  verifyAgentIDToken
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/detect.ts","../src/verify.ts","../src/middleware.ts"],"sourcesContent":["export { agentID } from \"./middleware.js\";\nexport type { AgentIDMiddlewareOptions } from \"./middleware.js\";\n\nexport { verifyAgentIDToken } from \"./verify.js\";\nexport type { VerifyTokenOptions } from \"./verify.js\";\n\nexport { isAgentRequest, extractToken } from \"./detect.js\";\n\nexport type {\n  AgentIDClaims,\n  AgentIDResult,\n  AgentIDVerified,\n  AgentIDUnverified,\n  VerifierOptions,\n} from \"./types.js\";\n","/**\n * Bot / AI-agent detection for Express.js (Node.js).\n *\n * Mirrors the logic in @agent-id/nextjs but uses `IncomingHttpHeaders`\n * from Node's `http` module instead of the Web `Headers` API.\n */\nimport type { IncomingHttpHeaders } from \"node:http\";\n\nconst BOT_UA_PATTERNS: RegExp[] = [\n  // OpenAI\n  /GPTBot/i,\n  /ChatGPT-User/i,\n  /OAI-SearchBot/i,\n  // Anthropic / Claude\n  /ClaudeBot/i,\n  /Claude-Web/i,\n  /anthropic-ai/i,\n  /Claude-User/i,\n  // Google\n  /Googlebot/i,\n  /Google-Extended/i,\n  /AdsBot-Google/i,\n  // Microsoft / Bing\n  /bingbot/i,\n  /msnbot/i,\n  // AI search engines\n  /PerplexityBot/i,\n  /YouBot/i,\n  // Common HTTP automation libraries\n  /python-requests/i,\n  /node-fetch/i,\n  /\\baxios\\b/i,\n  /\\bgot\\b\\//i,\n  /\\bundici\\b/i,\n  /\\bcurl\\b/i,\n  /\\bwget\\b/i,\n  /\\bhttpie\\b/i,\n  // Generic crawler signals\n  /\\bbot\\b/i,\n  /\\bcrawler\\b/i,\n  /\\bspider\\b/i,\n  /\\bscraper\\b/i,\n  /\\bfetcher\\b/i,\n  // MCP / AgentID clients\n  /mcp-client/i,\n  /agentid-client/i,\n];\n\nconst BROWSER_UA_RE = /Mozilla\\/5\\.0/i;\n\n/** Normalise a potentially multi-value header to a single string. */\nfunction single(\n  value: string | string[] | undefined\n): string | undefined {\n  return Array.isArray(value) ? value[0] : value;\n}\n\n/**\n * Returns `true` if the request appears to originate from an automated\n * agent or bot rather than a human browser.\n *\n * @param headers - `req.headers` from an Express `Request`\n */\nexport function isAgentRequest(headers: IncomingHttpHeaders): boolean {\n  const ua = single(headers[\"user-agent\"]) ?? \"\";\n\n  if (!ua) return true;\n\n  if (BOT_UA_PATTERNS.some((p) => p.test(ua))) return true;\n\n  // Cloudflare Bot Management score\n  const cfRaw = single(headers[\"cf-bot-management\"]);\n  if (cfRaw) {\n    try {\n      const parsed = JSON.parse(cfRaw) as { score?: unknown };\n      if (typeof parsed.score === \"number\" && parsed.score < 30) return true;\n    } catch {\n      // Malformed header — fail open\n    }\n  }\n\n  // Non-browser UA + no Accept-Language → likely automated\n  if (!BROWSER_UA_RE.test(ua) && !headers[\"accept-language\"]) return true;\n\n  return false;\n}\n\n/**\n * Extract the AgentID JWT from request headers.\n *\n * Checks:\n *  1. `Authorization: Bearer <token>` (preferred)\n *  2. `X-AgentID-Token` (fallback)\n *\n * @returns Raw JWT string or `null`.\n */\nexport function extractToken(headers: IncomingHttpHeaders): string | null {\n  const auth = single(headers[\"authorization\"]) ?? \"\";\n  if (auth.startsWith(\"Bearer \")) {\n    const token = auth.slice(7).trim();\n    if (token) return token;\n  }\n\n  const custom = single(headers[\"x-agentid-token\"])?.trim();\n  if (custom) return custom;\n\n  return null;\n}\n","import { createRemoteJWKSet, jwtVerify } from \"jose\";\nimport type { AgentIDClaims } from \"./types.js\";\n\nconst DEFAULT_JWKS_URL = \"https://agentpass.vercel.app/api/jwks\";\n\n/**\n * Module-level JWKS cache — one RemoteJWKSet instance per unique URL.\n * jose caches the fetched key material internally; re-fetches when the\n * cache TTL (1 h) expires or a new `kid` is seen.\n */\nconst jwksSets = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction getJwks(rawUrl: string): ReturnType<typeof createRemoteJWKSet> {\n  if (!jwksSets.has(rawUrl)) {\n    const url = new URL(rawUrl); // throws on malformed URL\n\n    // Security: HTTPS is mandatory to prevent MITM on the public-key fetch.\n    // Localhost is whitelisted for local development / CI.\n    const isLocal =\n      url.hostname === \"localhost\" ||\n      url.hostname === \"127.0.0.1\" ||\n      url.hostname === \"::1\";\n\n    if (url.protocol !== \"https:\" && !isLocal) {\n      throw new Error(\n        `[agent-id] jwksUrl must use HTTPS, received: ${rawUrl}`\n      );\n    }\n\n    jwksSets.set(\n      rawUrl,\n      createRemoteJWKSet(url, {\n        cacheMaxAge: 60 * 60 * 1_000, // 1 hour in ms\n      })\n    );\n  }\n\n  return jwksSets.get(rawUrl)!;\n}\n\nexport interface VerifyTokenOptions {\n  jwksUrl?: string;\n  clockTolerance?: number;\n}\n\n/**\n * Verify an AgentID JWT and return its decoded claims.\n *\n * Security guarantees\n * ───────────────────\n * • Signature   — RS256, verified against the live JWKS public key.\n * • Algorithm   — strict allowlist `['RS256']`; alg:none and HS256 are\n *                 rejected before signature verification even begins.\n * • Issuer      — must be exactly \"agentid\".\n * • Expiry      — enforced; configurable clock tolerance (default 30 s).\n * • kid         — jose matches the JWT `kid` header to the JWKS automatically.\n * • auth_method — validated at runtime; must equal \"bankid\".\n *\n * @throws if the token is invalid, expired, or fails any check.\n */\nexport async function verifyAgentIDToken(\n  token: string,\n  options: VerifyTokenOptions = {}\n): Promise<AgentIDClaims> {\n  const jwksUrl = options.jwksUrl ?? DEFAULT_JWKS_URL;\n  const JWKS = getJwks(jwksUrl);\n\n  const { payload } = await jwtVerify(token, JWKS, {\n    issuer: \"agentid\",\n    // ↓ Critical — explicit allowlist prevents algorithm-confusion attacks.\n    //   Any token claiming alg:\"none\", alg:\"HS256\", or anything else is\n    //   rejected before signature verification.\n    algorithms: [\"RS256\"],\n    clockTolerance: options.clockTolerance ?? 30,\n  });\n\n  // Runtime validation of AgentID-specific claims.\n  if (payload.auth_method !== \"bankid\") {\n    throw new Error(\n      `[agent-id] JWT has invalid auth_method: expected \"bankid\", got \"${\n        payload.auth_method ?? \"undefined\"\n      }\"`\n    );\n  }\n  if (typeof payload.sub !== \"string\" || payload.sub.length === 0) {\n    throw new Error(\"[agent-id] JWT is missing the sub claim\");\n  }\n\n  return payload as unknown as AgentIDClaims;\n}\n","import type { Request, Response, NextFunction } from \"express\";\nimport { isAgentRequest, extractToken } from \"./detect.js\";\nimport { verifyAgentIDToken } from \"./verify.js\";\nimport type { VerifierOptions, AgentIDResult, AgentIDClaims } from \"./types.js\";\n\n// ── TypeScript augmentation ──────────────────────────────────────────────────\n// Adds `req.agentId` to Express's Request interface.\n// Consumers get full type-safety without any extra setup.\ndeclare global {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace Express {\n    interface Request {\n      /** AgentID verification result set by the agentID() middleware. */\n      agentId?: AgentIDResult;\n    }\n  }\n}\n\nexport type AgentIDMiddlewareOptions = VerifierOptions & {\n  /**\n   * Custom handler invoked when an agent is detected but has no valid token.\n   * Call `next()` to pass through, or `res.status(403).json(...)` to block.\n   * If omitted, the default behaviour is controlled by `blockUnauthorizedAgents`.\n   */\n  onUnauthorizedAgent?: (\n    req: Request,\n    res: Response,\n    next: NextFunction,\n    reason: string\n  ) => void;\n};\n\n/** Headers managed by this middleware — stripped from incoming requests. */\nconst MANAGED_HEADERS = [\n  \"x-agentid-verified\",\n  \"x-agentid-sub\",\n  \"x-agentid-claims\",\n] as const;\n\n/**\n * Express middleware that detects AI-agent traffic and enforces AgentID\n * JWT authentication.\n *\n * Sets `req.agentId` on every request:\n *  - `{ verified: false, reason: 'not_agent' }` — human traffic (always passes through)\n *  - `{ verified: true, claims }` — agent with valid JWT\n *  - `{ verified: false, reason: 'no_token' | 'invalid_token' }` — blocked agent\n *    (returns 403 when `blockUnauthorizedAgents: true`)\n *\n * @example\n * ```ts\n * import express from 'express';\n * import { agentID } from '@agent-id/express';\n *\n * const app = express();\n * app.use(agentID({ blockUnauthorizedAgents: true }));\n *\n * app.get('/api/data', (req, res) => {\n *   if (req.agentId?.verified) {\n *     res.json({ sub: req.agentId.claims.sub });\n *   } else {\n *     res.status(403).json({ error: 'Unauthorized' });\n *   }\n * });\n * ```\n */\nexport function agentID(options: AgentIDMiddlewareOptions = {}) {\n  const {\n    jwksUrl,\n    blockUnauthorizedAgents = true,\n    clockTolerance = 30,\n    onUnauthorizedAgent,\n  } = options;\n\n  return async function agentIDMiddleware(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    // ── Security: strip client-supplied AgentID headers ──────────────────\n    // Prevents a malicious client from pre-setting x-agentid-verified: true\n    // to fool any downstream code that checks the header directly.\n    for (const header of MANAGED_HEADERS) {\n      delete req.headers[header];\n    }\n\n    // ── Non-agent traffic ──────────────────────────────────────────────────\n    if (!isAgentRequest(req.headers)) {\n      req.agentId = { verified: false, reason: \"not_agent\" };\n      return next();\n    }\n\n    // ── Agent detected — require a valid JWT ───────────────────────────────\n    const token = extractToken(req.headers);\n\n    if (!token) {\n      return handleUnauthorized(\n        req,\n        res,\n        next,\n        \"no_token\",\n        'Agent request missing AgentID token. Provide \"Authorization: Bearer <token>\".',\n        blockUnauthorizedAgents,\n        onUnauthorizedAgent\n      );\n    }\n\n    // ── Verify the JWT ─────────────────────────────────────────────────────\n    let claims: AgentIDClaims;\n    try {\n      claims = await verifyAgentIDToken(token, {\n        ...(jwksUrl !== undefined && { jwksUrl }),\n        clockTolerance,\n      });\n    } catch (err) {\n      console.warn(\n        \"[agent-id] Token verification failed:\",\n        err instanceof Error ? err.message : String(err)\n      );\n      return handleUnauthorized(\n        req,\n        res,\n        next,\n        \"invalid_token\",\n        \"Invalid or expired AgentID token.\",\n        blockUnauthorizedAgents,\n        onUnauthorizedAgent\n      );\n    }\n\n    // ── Verified ───────────────────────────────────────────────────────────\n    req.agentId = { verified: true, claims };\n    return next();\n  };\n}\n\n// ── Internal helper ──────────────────────────────────────────────────────────\n\nfunction handleUnauthorized(\n  req: Request,\n  res: Response,\n  next: NextFunction,\n  reason: \"no_token\" | \"invalid_token\",\n  message: string,\n  block: boolean,\n  onUnauthorized: AgentIDMiddlewareOptions[\"onUnauthorizedAgent\"]\n): void {\n  req.agentId = { verified: false, reason };\n\n  if (onUnauthorized) {\n    onUnauthorized(req, res, next, message);\n    return;\n  }\n\n  if (block) {\n    res.status(403).json({ error: \"AGENT_UNAUTHORIZED\", message });\n    return;\n  }\n\n  next();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACQA,IAAM,kBAA4B;AAAA;AAAA,EAEhC;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AACF;AAEA,IAAM,gBAAgB;AAGtB,SAAS,OACP,OACoB;AACpB,SAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,CAAC,IAAI;AAC3C;AAQO,SAAS,eAAe,SAAuC;AACpE,QAAM,KAAK,OAAO,QAAQ,YAAY,CAAC,KAAK;AAE5C,MAAI,CAAC,GAAI,QAAO;AAEhB,MAAI,gBAAgB,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAG,QAAO;AAGpD,QAAM,QAAQ,OAAO,QAAQ,mBAAmB,CAAC;AACjD,MAAI,OAAO;AACT,QAAI;AACF,YAAM,SAAS,KAAK,MAAM,KAAK;AAC/B,UAAI,OAAO,OAAO,UAAU,YAAY,OAAO,QAAQ,GAAI,QAAO;AAAA,IACpE,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,MAAI,CAAC,cAAc,KAAK,EAAE,KAAK,CAAC,QAAQ,iBAAiB,EAAG,QAAO;AAEnE,SAAO;AACT;AAWO,SAAS,aAAa,SAA6C;AACxE,QAAM,OAAO,OAAO,QAAQ,eAAe,CAAC,KAAK;AACjD,MAAI,KAAK,WAAW,SAAS,GAAG;AAC9B,UAAM,QAAQ,KAAK,MAAM,CAAC,EAAE,KAAK;AACjC,QAAI,MAAO,QAAO;AAAA,EACpB;AAEA,QAAM,SAAS,OAAO,QAAQ,iBAAiB,CAAC,GAAG,KAAK;AACxD,MAAI,OAAQ,QAAO;AAEnB,SAAO;AACT;;;AC3GA,kBAA8C;AAG9C,IAAM,mBAAmB;AAOzB,IAAM,WAAW,oBAAI,IAAmD;AAExE,SAAS,QAAQ,QAAuD;AACtE,MAAI,CAAC,SAAS,IAAI,MAAM,GAAG;AACzB,UAAM,MAAM,IAAI,IAAI,MAAM;AAI1B,UAAM,UACJ,IAAI,aAAa,eACjB,IAAI,aAAa,eACjB,IAAI,aAAa;AAEnB,QAAI,IAAI,aAAa,YAAY,CAAC,SAAS;AACzC,YAAM,IAAI;AAAA,QACR,gDAAgD,MAAM;AAAA,MACxD;AAAA,IACF;AAEA,aAAS;AAAA,MACP;AAAA,UACA,gCAAmB,KAAK;AAAA,QACtB,aAAa,KAAK,KAAK;AAAA;AAAA,MACzB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO,SAAS,IAAI,MAAM;AAC5B;AAsBA,eAAsB,mBACpB,OACA,UAA8B,CAAC,GACP;AACxB,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,OAAO,QAAQ,OAAO;AAE5B,QAAM,EAAE,QAAQ,IAAI,UAAM,uBAAU,OAAO,MAAM;AAAA,IAC/C,QAAQ;AAAA;AAAA;AAAA;AAAA,IAIR,YAAY,CAAC,OAAO;AAAA,IACpB,gBAAgB,QAAQ,kBAAkB;AAAA,EAC5C,CAAC;AAGD,MAAI,QAAQ,gBAAgB,UAAU;AACpC,UAAM,IAAI;AAAA,MACR,mEACE,QAAQ,eAAe,WACzB;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,QAAQ,QAAQ,YAAY,QAAQ,IAAI,WAAW,GAAG;AAC/D,UAAM,IAAI,MAAM,yCAAyC;AAAA,EAC3D;AAEA,SAAO;AACT;;;ACxDA,IAAM,kBAAkB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AACF;AA6BO,SAAS,QAAQ,UAAoC,CAAC,GAAG;AAC9D,QAAM;AAAA,IACJ;AAAA,IACA,0BAA0B;AAAA,IAC1B,iBAAiB;AAAA,IACjB;AAAA,EACF,IAAI;AAEJ,SAAO,eAAe,kBACpB,KACA,KACA,MACe;AAIf,eAAW,UAAU,iBAAiB;AACpC,aAAO,IAAI,QAAQ,MAAM;AAAA,IAC3B;AAGA,QAAI,CAAC,eAAe,IAAI,OAAO,GAAG;AAChC,UAAI,UAAU,EAAE,UAAU,OAAO,QAAQ,YAAY;AACrD,aAAO,KAAK;AAAA,IACd;AAGA,UAAM,QAAQ,aAAa,IAAI,OAAO;AAEtC,QAAI,CAAC,OAAO;AACV,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI;AACJ,QAAI;AACF,eAAS,MAAM,mBAAmB,OAAO;AAAA,QACvC,GAAI,YAAY,UAAa,EAAE,QAAQ;AAAA,QACvC;AAAA,MACF,CAAC;AAAA,IACH,SAAS,KAAK;AACZ,cAAQ;AAAA,QACN;AAAA,QACA,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MACjD;AACA,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,UAAU,EAAE,UAAU,MAAM,OAAO;AACvC,WAAO,KAAK;AAAA,EACd;AACF;AAIA,SAAS,mBACP,KACA,KACA,MACA,QACA,SACA,OACA,gBACM;AACN,MAAI,UAAU,EAAE,UAAU,OAAO,OAAO;AAExC,MAAI,gBAAgB;AAClB,mBAAe,KAAK,KAAK,MAAM,OAAO;AACtC;AAAA,EACF;AAEA,MAAI,OAAO;AACT,QAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,sBAAsB,QAAQ,CAAC;AAC7D;AAAA,EACF;AAEA,OAAK;AACP;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,192 @@
+// src/detect.ts
+var BOT_UA_PATTERNS = [
+  // OpenAI
+  /GPTBot/i,
+  /ChatGPT-User/i,
+  /OAI-SearchBot/i,
+  // Anthropic / Claude
+  /ClaudeBot/i,
+  /Claude-Web/i,
+  /anthropic-ai/i,
+  /Claude-User/i,
+  // Google
+  /Googlebot/i,
+  /Google-Extended/i,
+  /AdsBot-Google/i,
+  // Microsoft / Bing
+  /bingbot/i,
+  /msnbot/i,
+  // AI search engines
+  /PerplexityBot/i,
+  /YouBot/i,
+  // Common HTTP automation libraries
+  /python-requests/i,
+  /node-fetch/i,
+  /\baxios\b/i,
+  /\bgot\b\//i,
+  /\bundici\b/i,
+  /\bcurl\b/i,
+  /\bwget\b/i,
+  /\bhttpie\b/i,
+  // Generic crawler signals
+  /\bbot\b/i,
+  /\bcrawler\b/i,
+  /\bspider\b/i,
+  /\bscraper\b/i,
+  /\bfetcher\b/i,
+  // MCP / AgentID clients
+  /mcp-client/i,
+  /agentid-client/i
+];
+var BROWSER_UA_RE = /Mozilla\/5\.0/i;
+function single(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+function isAgentRequest(headers) {
+  const ua = single(headers["user-agent"]) ?? "";
+  if (!ua) return true;
+  if (BOT_UA_PATTERNS.some((p) => p.test(ua))) return true;
+  const cfRaw = single(headers["cf-bot-management"]);
+  if (cfRaw) {
+    try {
+      const parsed = JSON.parse(cfRaw);
+      if (typeof parsed.score === "number" && parsed.score < 30) return true;
+    } catch {
+    }
+  }
+  if (!BROWSER_UA_RE.test(ua) && !headers["accept-language"]) return true;
+  return false;
+}
+function extractToken(headers) {
+  const auth = single(headers["authorization"]) ?? "";
+  if (auth.startsWith("Bearer ")) {
+    const token = auth.slice(7).trim();
+    if (token) return token;
+  }
+  const custom = single(headers["x-agentid-token"])?.trim();
+  if (custom) return custom;
+  return null;
+}
+
+// src/verify.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+var DEFAULT_JWKS_URL = "https://agentpass.vercel.app/api/jwks";
+var jwksSets = /* @__PURE__ */ new Map();
+function getJwks(rawUrl) {
+  if (!jwksSets.has(rawUrl)) {
+    const url = new URL(rawUrl);
+    const isLocal = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (url.protocol !== "https:" && !isLocal) {
+      throw new Error(
+        `[agent-id] jwksUrl must use HTTPS, received: ${rawUrl}`
+      );
+    }
+    jwksSets.set(
+      rawUrl,
+      createRemoteJWKSet(url, {
+        cacheMaxAge: 60 * 60 * 1e3
+        // 1 hour in ms
+      })
+    );
+  }
+  return jwksSets.get(rawUrl);
+}
+async function verifyAgentIDToken(token, options = {}) {
+  const jwksUrl = options.jwksUrl ?? DEFAULT_JWKS_URL;
+  const JWKS = getJwks(jwksUrl);
+  const { payload } = await jwtVerify(token, JWKS, {
+    issuer: "agentid",
+    // ↓ Critical — explicit allowlist prevents algorithm-confusion attacks.
+    //   Any token claiming alg:"none", alg:"HS256", or anything else is
+    //   rejected before signature verification.
+    algorithms: ["RS256"],
+    clockTolerance: options.clockTolerance ?? 30
+  });
+  if (payload.auth_method !== "bankid") {
+    throw new Error(
+      `[agent-id] JWT has invalid auth_method: expected "bankid", got "${payload.auth_method ?? "undefined"}"`
+    );
+  }
+  if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+    throw new Error("[agent-id] JWT is missing the sub claim");
+  }
+  return payload;
+}
+
+// src/middleware.ts
+var MANAGED_HEADERS = [
+  "x-agentid-verified",
+  "x-agentid-sub",
+  "x-agentid-claims"
+];
+function agentID(options = {}) {
+  const {
+    jwksUrl,
+    blockUnauthorizedAgents = true,
+    clockTolerance = 30,
+    onUnauthorizedAgent
+  } = options;
+  return async function agentIDMiddleware(req, res, next) {
+    for (const header of MANAGED_HEADERS) {
+      delete req.headers[header];
+    }
+    if (!isAgentRequest(req.headers)) {
+      req.agentId = { verified: false, reason: "not_agent" };
+      return next();
+    }
+    const token = extractToken(req.headers);
+    if (!token) {
+      return handleUnauthorized(
+        req,
+        res,
+        next,
+        "no_token",
+        'Agent request missing AgentID token. Provide "Authorization: Bearer <token>".',
+        blockUnauthorizedAgents,
+        onUnauthorizedAgent
+      );
+    }
+    let claims;
+    try {
+      claims = await verifyAgentIDToken(token, {
+        ...jwksUrl !== void 0 && { jwksUrl },
+        clockTolerance
+      });
+    } catch (err) {
+      console.warn(
+        "[agent-id] Token verification failed:",
+        err instanceof Error ? err.message : String(err)
+      );
+      return handleUnauthorized(
+        req,
+        res,
+        next,
+        "invalid_token",
+        "Invalid or expired AgentID token.",
+        blockUnauthorizedAgents,
+        onUnauthorizedAgent
+      );
+    }
+    req.agentId = { verified: true, claims };
+    return next();
+  };
+}
+function handleUnauthorized(req, res, next, reason, message, block, onUnauthorized) {
+  req.agentId = { verified: false, reason };
+  if (onUnauthorized) {
+    onUnauthorized(req, res, next, message);
+    return;
+  }
+  if (block) {
+    res.status(403).json({ error: "AGENT_UNAUTHORIZED", message });
+    return;
+  }
+  next();
+}
+export {
+  agentID,
+  extractToken,
+  isAgentRequest,
+  verifyAgentIDToken
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/detect.ts","../src/verify.ts","../src/middleware.ts"],"sourcesContent":["/**\n * Bot / AI-agent detection for Express.js (Node.js).\n *\n * Mirrors the logic in @agent-id/nextjs but uses `IncomingHttpHeaders`\n * from Node's `http` module instead of the Web `Headers` API.\n */\nimport type { IncomingHttpHeaders } from \"node:http\";\n\nconst BOT_UA_PATTERNS: RegExp[] = [\n  // OpenAI\n  /GPTBot/i,\n  /ChatGPT-User/i,\n  /OAI-SearchBot/i,\n  // Anthropic / Claude\n  /ClaudeBot/i,\n  /Claude-Web/i,\n  /anthropic-ai/i,\n  /Claude-User/i,\n  // Google\n  /Googlebot/i,\n  /Google-Extended/i,\n  /AdsBot-Google/i,\n  // Microsoft / Bing\n  /bingbot/i,\n  /msnbot/i,\n  // AI search engines\n  /PerplexityBot/i,\n  /YouBot/i,\n  // Common HTTP automation libraries\n  /python-requests/i,\n  /node-fetch/i,\n  /\\baxios\\b/i,\n  /\\bgot\\b\\//i,\n  /\\bundici\\b/i,\n  /\\bcurl\\b/i,\n  /\\bwget\\b/i,\n  /\\bhttpie\\b/i,\n  // Generic crawler signals\n  /\\bbot\\b/i,\n  /\\bcrawler\\b/i,\n  /\\bspider\\b/i,\n  /\\bscraper\\b/i,\n  /\\bfetcher\\b/i,\n  // MCP / AgentID clients\n  /mcp-client/i,\n  /agentid-client/i,\n];\n\nconst BROWSER_UA_RE = /Mozilla\\/5\\.0/i;\n\n/** Normalise a potentially multi-value header to a single string. */\nfunction single(\n  value: string | string[] | undefined\n): string | undefined {\n  return Array.isArray(value) ? value[0] : value;\n}\n\n/**\n * Returns `true` if the request appears to originate from an automated\n * agent or bot rather than a human browser.\n *\n * @param headers - `req.headers` from an Express `Request`\n */\nexport function isAgentRequest(headers: IncomingHttpHeaders): boolean {\n  const ua = single(headers[\"user-agent\"]) ?? \"\";\n\n  if (!ua) return true;\n\n  if (BOT_UA_PATTERNS.some((p) => p.test(ua))) return true;\n\n  // Cloudflare Bot Management score\n  const cfRaw = single(headers[\"cf-bot-management\"]);\n  if (cfRaw) {\n    try {\n      const parsed = JSON.parse(cfRaw) as { score?: unknown };\n      if (typeof parsed.score === \"number\" && parsed.score < 30) return true;\n    } catch {\n      // Malformed header — fail open\n    }\n  }\n\n  // Non-browser UA + no Accept-Language → likely automated\n  if (!BROWSER_UA_RE.test(ua) && !headers[\"accept-language\"]) return true;\n\n  return false;\n}\n\n/**\n * Extract the AgentID JWT from request headers.\n *\n * Checks:\n *  1. `Authorization: Bearer <token>` (preferred)\n *  2. `X-AgentID-Token` (fallback)\n *\n * @returns Raw JWT string or `null`.\n */\nexport function extractToken(headers: IncomingHttpHeaders): string | null {\n  const auth = single(headers[\"authorization\"]) ?? \"\";\n  if (auth.startsWith(\"Bearer \")) {\n    const token = auth.slice(7).trim();\n    if (token) return token;\n  }\n\n  const custom = single(headers[\"x-agentid-token\"])?.trim();\n  if (custom) return custom;\n\n  return null;\n}\n","import { createRemoteJWKSet, jwtVerify } from \"jose\";\nimport type { AgentIDClaims } from \"./types.js\";\n\nconst DEFAULT_JWKS_URL = \"https://agentpass.vercel.app/api/jwks\";\n\n/**\n * Module-level JWKS cache — one RemoteJWKSet instance per unique URL.\n * jose caches the fetched key material internally; re-fetches when the\n * cache TTL (1 h) expires or a new `kid` is seen.\n */\nconst jwksSets = new Map<string, ReturnType<typeof createRemoteJWKSet>>();\n\nfunction getJwks(rawUrl: string): ReturnType<typeof createRemoteJWKSet> {\n  if (!jwksSets.has(rawUrl)) {\n    const url = new URL(rawUrl); // throws on malformed URL\n\n    // Security: HTTPS is mandatory to prevent MITM on the public-key fetch.\n    // Localhost is whitelisted for local development / CI.\n    const isLocal =\n      url.hostname === \"localhost\" ||\n      url.hostname === \"127.0.0.1\" ||\n      url.hostname === \"::1\";\n\n    if (url.protocol !== \"https:\" && !isLocal) {\n      throw new Error(\n        `[agent-id] jwksUrl must use HTTPS, received: ${rawUrl}`\n      );\n    }\n\n    jwksSets.set(\n      rawUrl,\n      createRemoteJWKSet(url, {\n        cacheMaxAge: 60 * 60 * 1_000, // 1 hour in ms\n      })\n    );\n  }\n\n  return jwksSets.get(rawUrl)!;\n}\n\nexport interface VerifyTokenOptions {\n  jwksUrl?: string;\n  clockTolerance?: number;\n}\n\n/**\n * Verify an AgentID JWT and return its decoded claims.\n *\n * Security guarantees\n * ───────────────────\n * • Signature   — RS256, verified against the live JWKS public key.\n * • Algorithm   — strict allowlist `['RS256']`; alg:none and HS256 are\n *                 rejected before signature verification even begins.\n * • Issuer      — must be exactly \"agentid\".\n * • Expiry      — enforced; configurable clock tolerance (default 30 s).\n * • kid         — jose matches the JWT `kid` header to the JWKS automatically.\n * • auth_method — validated at runtime; must equal \"bankid\".\n *\n * @throws if the token is invalid, expired, or fails any check.\n */\nexport async function verifyAgentIDToken(\n  token: string,\n  options: VerifyTokenOptions = {}\n): Promise<AgentIDClaims> {\n  const jwksUrl = options.jwksUrl ?? DEFAULT_JWKS_URL;\n  const JWKS = getJwks(jwksUrl);\n\n  const { payload } = await jwtVerify(token, JWKS, {\n    issuer: \"agentid\",\n    // ↓ Critical — explicit allowlist prevents algorithm-confusion attacks.\n    //   Any token claiming alg:\"none\", alg:\"HS256\", or anything else is\n    //   rejected before signature verification.\n    algorithms: [\"RS256\"],\n    clockTolerance: options.clockTolerance ?? 30,\n  });\n\n  // Runtime validation of AgentID-specific claims.\n  if (payload.auth_method !== \"bankid\") {\n    throw new Error(\n      `[agent-id] JWT has invalid auth_method: expected \"bankid\", got \"${\n        payload.auth_method ?? \"undefined\"\n      }\"`\n    );\n  }\n  if (typeof payload.sub !== \"string\" || payload.sub.length === 0) {\n    throw new Error(\"[agent-id] JWT is missing the sub claim\");\n  }\n\n  return payload as unknown as AgentIDClaims;\n}\n","import type { Request, Response, NextFunction } from \"express\";\nimport { isAgentRequest, extractToken } from \"./detect.js\";\nimport { verifyAgentIDToken } from \"./verify.js\";\nimport type { VerifierOptions, AgentIDResult, AgentIDClaims } from \"./types.js\";\n\n// ── TypeScript augmentation ──────────────────────────────────────────────────\n// Adds `req.agentId` to Express's Request interface.\n// Consumers get full type-safety without any extra setup.\ndeclare global {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace Express {\n    interface Request {\n      /** AgentID verification result set by the agentID() middleware. */\n      agentId?: AgentIDResult;\n    }\n  }\n}\n\nexport type AgentIDMiddlewareOptions = VerifierOptions & {\n  /**\n   * Custom handler invoked when an agent is detected but has no valid token.\n   * Call `next()` to pass through, or `res.status(403).json(...)` to block.\n   * If omitted, the default behaviour is controlled by `blockUnauthorizedAgents`.\n   */\n  onUnauthorizedAgent?: (\n    req: Request,\n    res: Response,\n    next: NextFunction,\n    reason: string\n  ) => void;\n};\n\n/** Headers managed by this middleware — stripped from incoming requests. */\nconst MANAGED_HEADERS = [\n  \"x-agentid-verified\",\n  \"x-agentid-sub\",\n  \"x-agentid-claims\",\n] as const;\n\n/**\n * Express middleware that detects AI-agent traffic and enforces AgentID\n * JWT authentication.\n *\n * Sets `req.agentId` on every request:\n *  - `{ verified: false, reason: 'not_agent' }` — human traffic (always passes through)\n *  - `{ verified: true, claims }` — agent with valid JWT\n *  - `{ verified: false, reason: 'no_token' | 'invalid_token' }` — blocked agent\n *    (returns 403 when `blockUnauthorizedAgents: true`)\n *\n * @example\n * ```ts\n * import express from 'express';\n * import { agentID } from '@agent-id/express';\n *\n * const app = express();\n * app.use(agentID({ blockUnauthorizedAgents: true }));\n *\n * app.get('/api/data', (req, res) => {\n *   if (req.agentId?.verified) {\n *     res.json({ sub: req.agentId.claims.sub });\n *   } else {\n *     res.status(403).json({ error: 'Unauthorized' });\n *   }\n * });\n * ```\n */\nexport function agentID(options: AgentIDMiddlewareOptions = {}) {\n  const {\n    jwksUrl,\n    blockUnauthorizedAgents = true,\n    clockTolerance = 30,\n    onUnauthorizedAgent,\n  } = options;\n\n  return async function agentIDMiddleware(\n    req: Request,\n    res: Response,\n    next: NextFunction\n  ): Promise<void> {\n    // ── Security: strip client-supplied AgentID headers ──────────────────\n    // Prevents a malicious client from pre-setting x-agentid-verified: true\n    // to fool any downstream code that checks the header directly.\n    for (const header of MANAGED_HEADERS) {\n      delete req.headers[header];\n    }\n\n    // ── Non-agent traffic ──────────────────────────────────────────────────\n    if (!isAgentRequest(req.headers)) {\n      req.agentId = { verified: false, reason: \"not_agent\" };\n      return next();\n    }\n\n    // ── Agent detected — require a valid JWT ───────────────────────────────\n    const token = extractToken(req.headers);\n\n    if (!token) {\n      return handleUnauthorized(\n        req,\n        res,\n        next,\n        \"no_token\",\n        'Agent request missing AgentID token. Provide \"Authorization: Bearer <token>\".',\n        blockUnauthorizedAgents,\n        onUnauthorizedAgent\n      );\n    }\n\n    // ── Verify the JWT ─────────────────────────────────────────────────────\n    let claims: AgentIDClaims;\n    try {\n      claims = await verifyAgentIDToken(token, {\n        ...(jwksUrl !== undefined && { jwksUrl }),\n        clockTolerance,\n      });\n    } catch (err) {\n      console.warn(\n        \"[agent-id] Token verification failed:\",\n        err instanceof Error ? err.message : String(err)\n      );\n      return handleUnauthorized(\n        req,\n        res,\n        next,\n        \"invalid_token\",\n        \"Invalid or expired AgentID token.\",\n        blockUnauthorizedAgents,\n        onUnauthorizedAgent\n      );\n    }\n\n    // ── Verified ───────────────────────────────────────────────────────────\n    req.agentId = { verified: true, claims };\n    return next();\n  };\n}\n\n// ── Internal helper ──────────────────────────────────────────────────────────\n\nfunction handleUnauthorized(\n  req: Request,\n  res: Response,\n  next: NextFunction,\n  reason: \"no_token\" | \"invalid_token\",\n  message: string,\n  block: boolean,\n  onUnauthorized: AgentIDMiddlewareOptions[\"onUnauthorizedAgent\"]\n): void {\n  req.agentId = { verified: false, reason };\n\n  if (onUnauthorized) {\n    onUnauthorized(req, res, next, message);\n    return;\n  }\n\n  if (block) {\n    res.status(403).json({ error: \"AGENT_UNAUTHORIZED\", message });\n    return;\n  }\n\n  next();\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@agent-id/express",
+  "version": "0.1.0",
+  "description": "Agent-ID verifier middleware for Express.js — blocks unauthorized AI agents from your API routes",
+  "keywords": ["agent-id", "agentpass", "bankid", "jwt", "express", "middleware", "ai-agent", "mcp", "bot-detection"],
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "jose": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "express": "^4.21.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/agentpass"
+  }
+}