@agentic-passport/next 0.3.0

package/dist/stores.js

@@ -0,0 +1,175 @@
+/**
+ * State store implementations.
+ *   - inMemoryStore() — default; per-instance Map-backed; fine for tests + single-isolate dev
+ *   - kvStore(kv)     — Cloudflare Workers KV-backed; works across isolates
+ */
+import { publicKeyFromJwk } from '@agentic-passport/core';
+// ---------- in-memory ----------
+export function inMemoryStore() {
+    const keys = new Map();
+    const revoked = new Set();
+    const nonces = new Map(); // key|nonce -> expiresAt
+    const mandateJtis = new Map();
+    const dpopJtis = new Map();
+    const agents = new Map();
+    const rateLimitTimestamps = new Map();
+    const NONCE_TTL_MS = 300_000;
+    const sweep = (m) => {
+        const now = Date.now();
+        for (const [k, v] of m)
+            if (v <= now)
+                m.delete(k);
+    };
+    return {
+        async registerKey(keyId, jwk) {
+            keys.set(keyId, publicKeyFromJwk(jwk));
+        },
+        async resolveKey(keyId) {
+            return keys.get(keyId) ?? null;
+        },
+        async isKeyRevoked(keyId) {
+            return revoked.has(keyId);
+        },
+        async revokeKey(keyId) {
+            revoked.add(keyId);
+        },
+        async putAgent(agentId, value) {
+            agents.set(agentId, value);
+        },
+        async getAgent(agentId) {
+            return agents.get(agentId) ?? null;
+        },
+        async isNonceSeen(keyId, nonce) {
+            sweep(nonces);
+            return nonces.has(`${keyId}\x00${nonce}`);
+        },
+        async rememberNonce(keyId, nonce) {
+            nonces.set(`${keyId}\x00${nonce}`, Date.now() + NONCE_TTL_MS);
+        },
+        async isMandateJtiUsed(jti) {
+            sweep(mandateJtis);
+            return mandateJtis.has(jti);
+        },
+        async rememberMandateJti(jti, expSec) {
+            mandateJtis.set(jti, expSec * 1000);
+        },
+        async isDpopJtiSeen(jti) {
+            sweep(dpopJtis);
+            return dpopJtis.has(jti);
+        },
+        async rememberDpopJti(jti, expSec) {
+            dpopJtis.set(jti, expSec * 1000);
+        },
+        async recordRegisterAttempt(keyId) {
+            const cutoff = Date.now() - 60_000;
+            const arr = (rateLimitTimestamps.get(keyId) ?? []).filter((t) => t > cutoff);
+            arr.push(Date.now());
+            rateLimitTimestamps.set(keyId, arr);
+            return arr.length;
+        },
+    };
+}
+const KEY_PREFIX = 'k:'; // agent public JWK by keyId
+const REVOKED_PREFIX = 'r:'; // revocation list
+const AGENT_PREFIX = 'a:'; // agent record by agent_id
+const NONCE_PREFIX = 'n:'; // seen nonces
+const MJTI_PREFIX = 'm:'; // consumed mandate jtis
+const DJTI_PREFIX = 'd:'; // seen dpop jtis
+const RL_PREFIX = 'rl:'; // rate-limit counters
+const NONCE_TTL_SEC = 300;
+/**
+ * KV-backed state store. Use on Cloudflare Workers / Pages.
+ *
+ * Two namespaces are recommended:
+ *   - state: persistent (keys, agents, revocation)
+ *   - cache: ephemeral (nonces, jtis, rate-limit) — falls back to `state` if omitted
+ *
+ * Limits to be aware of:
+ *   - KV writes are eventually consistent (≤60s globally). v0 demo: same-region requests
+ *     usually see fresh writes within ~1s. For multi-region production, consider Durable Objects.
+ *   - Each operation = 1 KV op = real cost / rate limit.
+ */
+export function kvStore(opts) {
+    const state = opts.state;
+    const cache = opts.cache ?? opts.state;
+    return {
+        async registerKey(keyId, jwk) {
+            await state.put(`${KEY_PREFIX}${keyId}`, JSON.stringify(jwk));
+        },
+        async resolveKey(keyId) {
+            const raw = await state.get(`${KEY_PREFIX}${keyId}`);
+            if (!raw)
+                return null;
+            try {
+                return publicKeyFromJwk(JSON.parse(raw));
+            }
+            catch {
+                return null;
+            }
+        },
+        async isKeyRevoked(keyId) {
+            const raw = await state.get(`${REVOKED_PREFIX}${keyId}`);
+            return raw === '1';
+        },
+        async revokeKey(keyId) {
+            await state.put(`${REVOKED_PREFIX}${keyId}`, '1');
+        },
+        async putAgent(agentId, value) {
+            await state.put(`${AGENT_PREFIX}${agentId}`, JSON.stringify(value));
+        },
+        async getAgent(agentId) {
+            const raw = await state.get(`${AGENT_PREFIX}${agentId}`);
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        },
+        async isNonceSeen(keyId, nonce) {
+            const v = await cache.get(`${NONCE_PREFIX}${keyId}:${nonce}`);
+            return v !== null;
+        },
+        async rememberNonce(keyId, nonce) {
+            await cache.put(`${NONCE_PREFIX}${keyId}:${nonce}`, '1', { expirationTtl: NONCE_TTL_SEC });
+        },
+        async isMandateJtiUsed(jti) {
+            const v = await cache.get(`${MJTI_PREFIX}${jti}`);
+            return v !== null;
+        },
+        async rememberMandateJti(jti, expSec) {
+            const ttl = Math.max(60, expSec - Math.floor(Date.now() / 1000));
+            await cache.put(`${MJTI_PREFIX}${jti}`, '1', { expirationTtl: ttl });
+        },
+        async isDpopJtiSeen(jti) {
+            const v = await cache.get(`${DJTI_PREFIX}${jti}`);
+            return v !== null;
+        },
+        async rememberDpopJti(jti, expSec) {
+            const ttl = Math.max(60, expSec - Math.floor(Date.now() / 1000));
+            await cache.put(`${DJTI_PREFIX}${jti}`, '1', { expirationTtl: ttl });
+        },
+        async recordRegisterAttempt(keyId) {
+            // KV doesn't support atomic increments. Read-modify-write here is best-effort:
+            // multiple concurrent calls may under-count. For v0 + per-key rate limits that's
+            // acceptable; for production, use Durable Objects or Workers Rate Limiting API.
+            const raw = (await cache.get(`${RL_PREFIX}${keyId}`)) ?? '[]';
+            let arr;
+            try {
+                arr = JSON.parse(raw);
+            }
+            catch {
+                arr = [];
+            }
+            const cutoff = Date.now() - 60_000;
+            const filtered = arr.filter((t) => t > cutoff);
+            filtered.push(Date.now());
+            await cache.put(`${RL_PREFIX}${keyId}`, JSON.stringify(filtered), { expirationTtl: 120 });
+            return filtered.length;
+        },
+    };
+    void null;
+}
+//# sourceMappingURL=stores.js.map

package/dist/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,159 @@
+import type { JSONWebKeySet, JWK } from 'jose';
+import type { KeyObject } from 'node:crypto';
+import type { ErrorCode, MandateClaims } from '@agentic-passport/protocol';
+export type AgentSignupContext = {
+    agentId: string;
+    mandate: MandateClaims;
+    request: {
+        method: string;
+        url: string;
+        headers: Readonly<Record<string, string | undefined>>;
+    };
+};
+export type AgentSignupResult = {
+    allow: boolean;
+    principal?: {
+        userId: string;
+        grantedScopes: string[];
+    };
+    reason?: string;
+};
+/**
+ * Context passed to onAgentSessionMint. Includes the verified agent record
+ * (after AgentPassport signature + mandate checks have passed) and the user
+ * the vendor mapped them to in onAgentSignup. The vendor uses `userId` to
+ * mint a session in their own auth system.
+ */
+export type AgentSessionMintContext = {
+    agentId: string;
+    userId: string;
+    scopes: readonly string[];
+    mandateJti: string;
+    actor?: string;
+};
+/**
+ * Browser-handoff result. The agent's browser navigates to `bootstrap_url`;
+ * the vendor's auth provider mints its session cookie in that browser
+ * context. From that point on, the browser is signed in to the vendor
+ * exactly as a human would be after going through the equivalent flow.
+ *
+ * `bootstrap_url` should be one-time-use and short-lived (≤5 min). Vendor
+ * is responsible for revoking unused tokens.
+ *
+ * Optional `final_url` lets the vendor tell the agent where to land
+ * after the bootstrap completes — defaults to the vendor origin.
+ */
+export type AgentSessionMintResult = {
+    bootstrap_url: string;
+    final_url?: string;
+};
+export type PaymentChallenge = {
+    rail: 'free';
+};
+/**
+ * Storage backend for cross-request gate state.
+ *
+ * v0 default: inMemoryStore() — fine for single-instance dev / tests.
+ * Production / serverless: provide a KV-backed implementation. Each isolate
+ * sees the same state via the store, eliminating module-scope state issues.
+ */
+export interface AgentStateStore {
+    registerKey(keyId: string, jwk: JWK): Promise<void>;
+    resolveKey(keyId: string): Promise<KeyObject | null>;
+    isKeyRevoked(keyId: string): Promise<boolean>;
+    revokeKey(keyId: string): Promise<void>;
+    putAgent(agentId: string, value: AgentRecord): Promise<void>;
+    getAgent(agentId: string): Promise<AgentRecord | null>;
+    isNonceSeen(keyId: string, nonce: string): Promise<boolean>;
+    rememberNonce(keyId: string, nonce: string): Promise<void>;
+    isMandateJtiUsed(jti: string): Promise<boolean>;
+    rememberMandateJti(jti: string, exp: number): Promise<void>;
+    isDpopJtiSeen(jti: string): Promise<boolean>;
+    rememberDpopJti(jti: string, exp: number): Promise<void>;
+    recordRegisterAttempt(keyId: string): Promise<number>;
+}
+export type AgentRecord = {
+    granted_scopes: string[];
+    mandate_jti: string;
+    user_id: string;
+    actor?: string;
+};
+export type AgentPassportConfig = {
+    /** Vendor's origin (used as JWT aud, signature URL canonicalisation). */
+    vendorOrigin: string;
+    /** Issuer URLs whose mandate signatures we trust. SDK fetches their JWKS automatically. */
+    trustedIssuers: string[];
+    /** Scope vocabulary the vendor exposes (advertised in discovery doc). */
+    scopes: string[];
+    /** Optional human-readable vendor name (discovery doc). */
+    vendorName?: string;
+    /**
+     * Pre-loaded JWKS by issuer URL. Optional — if omitted, the SDK fetches
+     * each issuer's `/.well-known/jwks.json` on first use and caches it.
+     * Provide explicitly for air-gapped deployments or when you want to
+     * pin a JWKS snapshot.
+     */
+    jwksByIssuer?: Map<string, JSONWebKeySet>;
+    /** Hooks the vendor implements (the "agent UX" surface). */
+    hooks: {
+        onAgentSignup: (ctx: AgentSignupContext) => Promise<AgentSignupResult>;
+        /**
+         * Browser-handoff: produce a one-time URL that, when navigated to by
+         * a real browser context (Playwright, Puppeteer), causes the vendor's
+         * auth provider to mint its own session in that browser. After
+         * navigation, the browser has a legitimate provider session — same
+         * mechanism a human would acquire via their own sign-in flow.
+         *
+         * Why a URL and not a cookie value: auth providers (Clerk, Auth.js,
+         * WorkOS, Auth0) mint session cookies only as the result of a
+         * sign-in event in *their* frontend. They expose this surface via a
+         * one-time sign-in token + redirect URL — designed for password-
+         * reset, magic-link, and impersonation flows. We use exactly that
+         * primitive: the agent's browser visits the URL, the provider
+         * recognises the token, mints the session cookie, and lands the
+         * browser on the requested destination.
+         *
+         * This hook is ONLY meaningful for browser-based agents (run via
+         * @agentic-passport/agent-browser). HTTP-only agents ignore it and use the
+         * vendor's getSession()-aware API routes directly.
+         *
+         * For Clerk:
+         *
+         *   onAgentSessionMint: async ({ userId }) => {
+         *     const client = await clerkClient();
+         *     const t = await client.signInTokens.createSignInToken({ userId, expiresInSeconds: 300 });
+         *     return { bootstrap_url: t.url };
+         *   }
+         */
+        onAgentSessionMint?: (ctx: AgentSessionMintContext) => Promise<AgentSessionMintResult>;
+        onPaymentRequired?: () => PaymentChallenge;
+    };
+    /**
+     * Optional pre-built state store. Defaults to inMemoryStore().
+     * Provide kvStore(env) when running on Cloudflare Workers.
+     */
+    store?: AgentStateStore;
+    /**
+     * Optional PKCS8 PEM (or base64-encoded PKCS8 PEM) for the gate's token
+     * signing key. If omitted, a fresh keypair is generated per agentPassport()
+     * call — which is fine for tests but BROKEN on multi-isolate deployments
+     * because each isolate would sign with a different key.
+     */
+    tokenSigningKeyPem?: string;
+};
+export type AgentPrincipal = {
+    type: 'agent';
+    agentId: string;
+    scopes: readonly string[];
+    mandateJti: string;
+};
+export type HumanPrincipal = {
+    type: 'human';
+    userId: string;
+    scopes?: readonly string[];
+};
+export type Session = AgentPrincipal | HumanPrincipal;
+export type { ErrorCode };
+/** @deprecated Use {@link AgentPassportConfig}. */
+export type AgentGateConfig = AgentPassportConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@agentic-passport/next",
+  "version": "0.3.0",
+  "description": "AgentAuth adapter for Next.js — sidecar middleware + route handler factories.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./edge": {
+      "types": "./dist/is-agent-request.d.ts",
+      "import": "./dist/is-agent-request.js"
+    },
+    "./clerk": {
+      "types": "./dist/clerk.d.ts",
+      "import": "./dist/clerk.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "edge": [
+        "dist/is-agent-request.d.ts"
+      ],
+      "clerk": [
+        "dist/clerk.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "next": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "jose": "^6.2.3",
+    "@agentic-passport/protocol": "0.3.0",
+    "@agentic-passport/core": "0.3.0"
+  },
+  "devDependencies": {
+    "next": "^16.2.6",
+    "react": "^19.2.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}