Overview

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.

import { createTheAuth } from '@glinr/theauth';
import { createMcpModule } from '@glinr/theauth/mcp';
import { mcpStore } from './mcp-store.js'; // storage callbacks, see the MCP page

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  baseUrl: 'https://auth.yourapp.com',
});

// optional, enables MCP OAuth endpoints
const mcp = createMcpModule({
  config: {
    enabled: true,
    issuer: 'https://auth.yourapp.com',
    baseUrl: 'https://auth.yourapp.com/api/theauth', // origin plus the mount path
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

Pass 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:

const authenticate = async (request: Request) => {
  const user = await theauth.auth.resolveUser(request);
  return user?.id === process.env.ADMIN_USER_ID ? { id: user.id } : null;
};

app.route('/api/theauth', theAuthHono(theauth, { authenticate }));

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:

[theauth] theAuthHono: the management routes (/agents, /delegations, /audit, /dashboard, /authorize) require authentication, but none is configured.

For a local demo you can opt out with allowUnauthenticated: true. A warning is logged on startup. Do not ship it.

Upgrading

Earlier versions mounted these routes with no authentication. After upgrading, pass authenticate (or configure auth.session) to each adapter call, or add allowUnauthenticated: true while you work on it locally.

Available adapters

Package	Framework	Mount pattern
`@glinr/theauth-hono`	Hono	`app.route('/api/theauth', theAuthHono(theauth))`
`@glinr/theauth-express`	Express	`app.use('/api/theauth', theAuthExpress(theauth))`
`@glinr/theauth-nextjs`	Next.js App Router	catch-all route `app/api/theauth/[...theauth]/route.ts`
`@glinr/theauth-fastify`	Fastify	`app.register(theAuthFastify(theauth), { prefix: '/api/theauth' })`
`@glinr/theauth-nuxt`	Nuxt (H3)	catch-all file `server/api/theauth/[...].ts`
`@glinr/theauth-sveltekit`	SvelteKit	catch-all route `src/routes/api/theauth/[...path]/+server.ts`
`@glinr/theauth-astro`	Astro	catch-all page `src/pages/api/theauth/[...path].ts`
`@glinr/theauth-nestjs`	NestJS	`AuthModule.forRoot({ theauth, mcp })`
`@glinr/theauth-solidstart`	SolidStart	catch-all route `src/routes/api/theauth/[...theauth].ts`
`@glinr/theauth-tanstack`	TanStack Start	catch-all route `app/routes/api/theauth.$.ts`

Endpoints registered

All adapters register the same set of REST routes under basePath (default /api/theauth):

Path	Methods	Description
`/agents`	`GET`, `POST`	List and create agents
`/agents/:id`	`GET`, `PATCH`, `DELETE`	Get, update, revoke an agent
`/agents/:id/rotate`	`POST`	Rotate an agent’s token
`/authorize`	`POST`	Authorize an action by agent ID
`/authorize/token`	`POST`	Authorize an action by bearer token
`/delegations`	`POST`	Create a delegation chain
`/delegations/:id`	`DELETE`	Revoke a delegation
`/delegations/:agentId`	`GET`	List delegation chains for an agent
`/audit`	`GET`	Query audit logs
`/audit/export`	`GET`	Export audit logs as JSON or CSV

When mcp is passed, additional endpoints are registered:

Path	Methods	Description
`/.well-known/oauth-authorization-server`	`GET`	OAuth 2.1 server metadata (RFC 8414)
`/.well-known/oauth-protected-resource`	`GET`	Protected resource metadata (RFC 9728)
`/mcp/register`	`POST`	Dynamic client registration (RFC 7591)
`/mcp/authorize`	`GET`	Authorization endpoint (PKCE + S256)
`/mcp/token`	`POST`	Token endpoint

These paths are relative to the mount point, but MCP clients look for the /.well-known/* documents at the root of your origin. When you mount the adapter under a prefix such as /api/theauth, also serve mcp.getMetadata() and mcp.getProtectedResourceMetadata() from root-level /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource routes. See MCP.

Using without an adapter

If your framework is not listed, call the module methods directly from any server that handles standard Request objects. The mcp module from createMcpModule does not route URLs for you: you map paths to its methods yourself.

import { mcp } from './lib/theauth.js';

async function handler(request: Request): Promise<Response> {
  const url = new URL(request.url);

  if (url.pathname === '/.well-known/oauth-authorization-server') {
    return Response.json(mcp.getMetadata());
  }
  if (url.pathname === '/.well-known/oauth-protected-resource') {
    return Response.json(mcp.getProtectedResourceMetadata());
  }

  // Protect everything else: 401 or 403 responses are built for you
  const check = await mcp.requireScopes(request, ['mcp:read']);
  if (!check.authorized) return check.response;

  return Response.json({ tools: [] });
}

You would also route /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.

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.

MCP and gateway

Framework adapters

Client SDKs

Infra

How adapters work

Authenticate the management routes

Upgrading

Available adapters

Endpoints registered

Using without an adapter

Choose your framework

Hono

Express

Next.js

Fastify

Nuxt

SvelteKit

Astro

MCP

REST API

Configuration

Agent identity

​How adapters work

​Authenticate the management routes

​Upgrading

​Available adapters

​Endpoints registered

​Using without an adapter

​Choose your framework

Hono

Express

Next.js

Fastify

Nuxt

SvelteKit

Astro

​Related

MCP

REST API

Configuration

Agent identity

How adapters work

Authenticate the management routes

Upgrading

Available adapters

Endpoints registered

Using without an adapter

Choose your framework

Related