
One core, a thin adapter per framework.
How adapters work
The@glinr/theauth package has zero framework dependencies. It operates entirely on the Web platform Request/Response API. Adapter packages wrap the core and expose framework-idiomatic handlers for authentication, authorization, and MCP OAuth routes.
Because the core uses only Web platform APIs, theAuth runs on edge runtimes without modification: Next.js Edge Runtime, Cloudflare Workers, Deno Deploy, Vercel Edge Functions, and Bun. The Hono and SvelteKit adapters are fully edge-compatible out of the box. The Next.js adapter works on edge when you use export const runtime = 'edge' in your route file.
Each adapter follows the same pattern: accept a theauth instance, optionally accept a config object, and return something your framework knows how to mount.
mcp to the adapter to enable the MCP OAuth 2.1 endpoints under the same mount path. createMcpModule comes from @glinr/theauth/mcp and takes a config object plus storage callbacks, see MCP.
Authenticate the management routes
The agent, delegation, audit and dashboard routes (/agents, /delegations, /audit, /dashboard, and POST /authorize) manage your whole agent fleet, so every adapter requires an authenticated caller. /authorize/token (agent bearer token), the MCP endpoints, password reset, email verification and plugin routes are not affected; they carry their own checks.
Pass an authenticate function. It receives the standard Request and returns { id } for an allowed caller or null to reject with 401:
theauth.auth.resolveUser only consults the auth.adapter you configured. If you rely on auth.session alone, skip authenticate (see next paragraph) or validate the token yourself with theauth.auth.session.validate(token).
If you leave authenticate out and auth.session is configured on createTheAuth, the adapter accepts any valid session (cookie or Authorization: Bearer <session token>). That admits every signed-in user, but each one only sees and acts on their own agents, delegations and audit rows. Write your own resolver when admins or service tokens need to reach everything; whatever a custom resolver accepts is unrestricted. If neither is configured, the adapter throws when you create it:
allowUnauthenticated: true. A warning is logged on startup. Do not ship it.
Rate limiting and cross-site writes
Every adapter refuses abusive traffic before authentication runs.- Rate limits are per client, in three tiers: token, registration and authorize routes (30 per minute), other writes (120 per minute) and reads (300 per minute). Exceeding one returns
429withRetry-After. - Cookie sessions cannot be used for cross-site writes. A
POST,PUT,PATCHorDELETEthat carries a cookie and noAuthorizationheader must come from the adapter’s own origin or one listed intrustedOrigins. Bearer callers are not affected.
skip leaves a request out of rate limiting (health checks, your own network) and key replaces the client key, for example to count per tenant:
trustedProxy so limits apply per client IP. Without it the IP is unknown and callers are split by their credential instead. Counts are kept in the rateLimit secondary storage. With the default in-process store each instance counts alone; configure secondaryStorage: "database" or a Redis style store and one limit holds across instances. If the store errors, the request is let through so an outage there does not take sign-in down. Use rateLimit: false or csrf: false to switch either check off.
Upgrading
Earlier versions mounted these routes with no authentication. After upgrading, passauthenticate (or configure auth.session) to each adapter call, or add allowUnauthenticated: true while you work on it locally.
Available adapters
Headers and CORS
Every response isCache-Control: no-store by default. Security headers (securityHeaders) and an exact-origin CORS allowlist (cors) are opt-in. See Routes.
Endpoints registered
All adapters register the same set of REST routes underbasePath (default /api/theauth):
When
mcp is passed, additional endpoints are registered:
Using without an adapter
If your framework is not listed, call the module methods directly from any server that handles standardRequest objects. The mcp module from createMcpModule does not route URLs for you: you map paths to its methods yourself.
/mcp/register, /mcp/authorize, and /mcp/token to mcp.registerClient(body), mcp.authorize(request), and mcp.token(request), which return a Result you turn into a Response. The adapters in this table already do that, and the agent REST routes are only available through an adapter.
Choose your framework
Hono
Lightweight, fast, runs everywhere.
Express
The most widely used Node.js framework.
Next.js
App Router with catch-all route handler.
Fastify
High-performance with plugin architecture.
Nuxt
Vue-based with H3 server routes.
SvelteKit
Svelte with +server.ts handlers.
Astro
Content-focused with API routes.
Related
MCP
OAuth 2.1 authorization server, works with any adapter.
REST API
Full endpoint reference for all routes the adapters mount.
Configuration
Core theAuth instance options passed to every adapter.
Agent identity
Creating and managing agents via the mounted REST endpoints.