@glinr/theauth 0.4.2

package/dist/mcp/index.d.ts

@@ -0,0 +1,274 @@
+import { M as McpAuthContext, R as Result, a as McpAuthorizeResult, A as ApproveConsentParams, b as McpServerMetadata, c as McpProtectedResourceMetadata, d as McpClientRegistrationResponse, e as McpSession, f as McpConfig, g as McpAuthModule, h as McpTokenResponse } from '../types-BiUe9e8u.js';
+export { K as KavachError, i as McpAccessToken, j as McpAuthorizationCode, k as McpAuthorizeRequest, l as McpAuthorizeRequestSchema, m as McpClient, n as McpClientRegistrationRequest, o as McpClientRegistrationSchema, p as McpTokenPayload, q as McpTokenRequest, r as McpTokenRequestParsed, s as McpTokenRequestSchema } from '../types-BiUe9e8u.js';
+import 'zod';
+
+/**
+ * Handle the OAuth 2.1 authorization endpoint.
+ *
+ * GET /mcp/authorize
+ *
+ * Validates the request parameters, checks the client, enforces PKCE S256,
+ * validates Resource Indicators (RFC 8707), and issues an authorization code.
+ *
+ * The caller is responsible for authenticating the user before calling this
+ * function.  The `ctx.resolveUserId(request)` hook must return a non-null
+ * user ID for the currently authenticated user.
+ */
+declare function handleAuthorize(ctx: McpAuthContext, request: Request): Promise<Result<McpAuthorizeResult>>;
+
+/**
+ * Issue an authorization code after a user has explicitly approved consent.
+ *
+ * Call this from your consent page handler after the user clicks "Allow".
+ * The params should match what was passed to the consent page as query params
+ * by `handleAuthorize`.
+ */
+declare function approveConsent(ctx: McpAuthContext, params: ApproveConsentParams): Promise<Result<{
+    redirectUri: string;
+}>>;
+
+/**
+ * Build OAuth 2.0 Authorization Server Metadata (RFC 8414).
+ *
+ * Returned at: GET /.well-known/oauth-authorization-server
+ */
+declare function getAuthorizationServerMetadata(ctx: McpAuthContext): McpServerMetadata;
+/**
+ * Build Protected Resource Metadata (RFC 9728).
+ *
+ * Returned at: GET /.well-known/oauth-protected-resource
+ *
+ * An MCP resource server (tool server) publishes this so clients can
+ * discover which authorization server to use.
+ */
+declare function getProtectedResourceMetadata(ctx: McpAuthContext): McpProtectedResourceMetadata;
+
+/**
+ * Dynamic Client Registration (RFC 7591).
+ *
+ * Endpoint logic for: POST /mcp/register
+ *
+ * Validates the registration request, generates client credentials,
+ * persists the client via the context store, and returns the
+ * RFC 7591-compliant registration response.
+ */
+declare function registerClient(ctx: McpAuthContext, body: unknown): Promise<Result<McpClientRegistrationResponse>>;
+
+/**
+ * Validate the Bearer token on a request and assert that it carries all of
+ * the `requiredScopes`.
+ *
+ * Encapsulates the three-branch decision MCP resource servers need to make:
+ *
+ *  1. No token (or malformed token)  → 401 Unauthorized
+ *  2. Valid token, missing scopes    → 403 with step-up challenge
+ *  3. Valid token, all scopes present → session returned to the caller
+ *
+ * Usage:
+ * ```typescript
+ * const check = await requireScopes(ctx, request, ['mcp:write']);
+ * if (!check.authorized) return check.response;
+ * // check.session is available here
+ * ```
+ */
+declare function requireScopes(ctx: McpAuthContext, request: Request, requiredScopes: string[]): Promise<{
+    authorized: true;
+    session: McpSession;
+} | {
+    authorized: false;
+    response: Response;
+}>;
+
+/**
+ * Create the MCP authorization server module.
+ *
+ * This is the main factory that wires up all MCP OAuth 2.1 endpoints
+ * into a single module.  The caller provides storage callbacks (how to
+ * persist clients, codes, and tokens) and user resolution (how to identify
+ * the currently authenticated user).
+ *
+ * @example
+ * ```typescript
+ * const mcp = createMcpModule({
+ *   config: {
+ *     enabled: true,
+ *     issuer: 'https://auth.example.com',
+ *     baseUrl: 'https://auth.example.com/api/auth',
+ *     signingSecret: process.env.MCP_SIGNING_SECRET,
+ *   },
+ *   storeClient: async (client) => { await db.insert(mcpClients).values(client); },
+ *   findClient: async (id) => { return db.query.mcpClients.findFirst({ where: eq(mcpClients.clientId, id) }); },
+ *   storeAuthorizationCode: async (code) => { await db.insert(mcpCodes).values(code); },
+ *   consumeAuthorizationCode: async (code) => {
+ *     const found = await db.query.mcpCodes.findFirst({ where: eq(mcpCodes.code, code) });
+ *     if (found) await db.delete(mcpCodes).where(eq(mcpCodes.code, code));
+ *     return found ?? null;
+ *   },
+ *   storeToken: async (token) => { await db.insert(mcpTokens).values(token); },
+ *   findTokenByRefreshToken: async (rt) => { ... },
+ *   revokeToken: async (at) => { ... },
+ *   resolveUserId: async (request) => {
+ *     const session = await getSession(request);
+ *     return session?.userId ?? null;
+ *   },
+ * });
+ *
+ * // Use in a framework adapter:
+ * app.get('/.well-known/oauth-authorization-server', () => mcp.getMetadata());
+ * app.get('/.well-known/oauth-protected-resource', () => mcp.getProtectedResourceMetadata());
+ * app.post('/mcp/register', (req) => mcp.registerClient(req.body));
+ * app.get('/mcp/authorize', (req) => mcp.authorize(req));
+ * app.post('/mcp/token', (req) => mcp.token(req));
+ * ```
+ */
+declare function createMcpModule(params: {
+    config: McpConfig;
+    storeClient: McpAuthContext["storeClient"];
+    findClient: McpAuthContext["findClient"];
+    storeAuthorizationCode: McpAuthContext["storeAuthorizationCode"];
+    consumeAuthorizationCode: McpAuthContext["consumeAuthorizationCode"];
+    storeToken: McpAuthContext["storeToken"];
+    findTokenByRefreshToken: McpAuthContext["findTokenByRefreshToken"];
+    revokeToken: McpAuthContext["revokeToken"];
+    resolveUserId: McpAuthContext["resolveUserId"];
+}): McpAuthModule;
+/**
+ * Create HTTP Response helpers for framework adapters.
+ *
+ * These take Result types and produce standard Response objects
+ * with proper status codes, cache-control headers, and CORS.
+ */
+declare function createMcpResponseHelpers(ctx: McpAuthContext): {
+    /** Metadata endpoints: 200 with JSON */
+    metadataResponse: (data: unknown) => Response;
+    /** Registration: 201 with Cache-Control: no-store */
+    registrationResponse: (result: Result<unknown>) => Response;
+    /** Authorization: 302 redirect or error */
+    authorizeResponse: (result: Result<{
+        redirectUri: string;
+    }>) => Response;
+    /** Token: 200 with Cache-Control: no-store or error */
+    tokenResponse: (result: Result<unknown>) => Response;
+    /** Auth failure in JSON-RPC format for MCP resource servers */
+    unauthorizedResponse: (error: {
+        code: string;
+        message: string;
+    }) => Response;
+};
+
+/**
+ * Build a step-up challenge response (403) indicating required scopes.
+ *
+ * When a token has valid scopes but lacks a specific scope needed for an
+ * operation, return this response so the client knows it must re-authorize
+ * with the additional scopes.
+ *
+ * Per RFC 6750 §3.1 the WWW-Authenticate header uses the
+ * `error="insufficient_scope"` challenge to signal the exact upgrade path.
+ */
+declare function buildStepUpResponse(ctx: McpAuthContext, options: {
+    currentScopes: string[];
+    requiredScopes: string[];
+    resource?: string;
+}): Response;
+
+/**
+ * Handle the OAuth 2.1 token endpoint.
+ *
+ * POST /mcp/token
+ *
+ * Supports two grant types:
+ * 1. authorization_code - Exchange auth code + PKCE verifier for tokens
+ * 2. refresh_token - Refresh an expired access token
+ */
+declare function handleTokenExchange(ctx: McpAuthContext, request: Request): Promise<Result<McpTokenResponse>>;
+
+/**
+ * Generate a cryptographically secure random token string.
+ *
+ * Uses `crypto.getRandomValues()` (Web Crypto API compatible) to produce
+ * a URL-safe base64 string of the requested byte length.
+ */
+declare function generateSecureToken(byteLength: number): string;
+/**
+ * Compute the S256 code challenge from a code verifier.
+ *
+ * S256: BASE64URL(SHA256(ASCII(code_verifier)))
+ *
+ * Uses Web Crypto (SubtleCrypto) for cross-runtime compatibility.
+ */
+declare function computeS256Challenge(codeVerifier: string): Promise<string>;
+/**
+ * Verify a PKCE S256 code_verifier against a stored code_challenge.
+ */
+declare function verifyS256(codeVerifier: string, codeChallenge: string): Promise<boolean>;
+/**
+ * Parse a URL search params or form body into a plain object.
+ *
+ * Handles both `application/x-www-form-urlencoded` and `application/json`
+ * content types, as required by OAuth 2.1 token endpoint.
+ */
+declare function parseRequestBody(request: Request): Promise<Record<string, string>>;
+/**
+ * Extract client credentials from the Authorization header (Basic auth).
+ *
+ * Returns [client_id, client_secret] or null if not present.
+ */
+declare function extractBasicAuth(request: Request): [string, string] | null;
+/**
+ * Extract a Bearer token from the Authorization header.
+ */
+declare function extractBearerToken(request: Request): string | null;
+
+/**
+ * Validate an MCP access token (JWT).
+ *
+ * Performs:
+ * 1. JWT signature verification (HS256)
+ * 2. Expiry check
+ * 3. Issuer validation
+ * 4. Audience validation (token must be bound to the expected resource)
+ * 5. Scope validation (optional - checks all required scopes are present)
+ *
+ * Target: < 5ms with cached keys (per CLAUDE.md performance rule).
+ */
+declare function validateAccessToken(ctx: McpAuthContext, token: string, options?: {
+    requiredScopes?: string[];
+    expectedAudience?: string;
+}): Promise<Result<McpSession>>;
+/**
+ * MCP auth middleware.
+ *
+ * Extracts the Bearer token from the Authorization header, validates it,
+ * and returns the session.  This is the primary entry point for protecting
+ * MCP resource server endpoints.
+ *
+ * Pattern inspired by better-auth's `withMcpAuth()`, adapted to TheAuth's
+ * functional Result-based API.
+ *
+ * Usage:
+ * ```typescript
+ * const result = await withMcpAuth(ctx, request, { requiredScopes: ['read'] });
+ * if (!result.success) {
+ *   return new Response(JSON.stringify(result.error), { status: 401 });
+ * }
+ * const session = result.data;
+ * ```
+ */
+declare function withMcpAuth(ctx: McpAuthContext, request: Request, options?: {
+    requiredScopes?: string[];
+    expectedAudience?: string;
+}): Promise<Result<McpSession>>;
+/**
+ * Build a 401 Unauthorized response in the JSON-RPC format expected
+ * by MCP clients.
+ *
+ * Includes the WWW-Authenticate header pointing to the protected
+ * resource metadata document, as required by the MCP spec.
+ */
+declare function buildUnauthorizedResponse(ctx: McpAuthContext, error: {
+    code: string;
+    message: string;
+}): Response;
+
+export { ApproveConsentParams, McpAuthContext, McpAuthModule, McpAuthorizeResult, McpClientRegistrationResponse, McpConfig, McpProtectedResourceMetadata, McpServerMetadata, McpSession, McpTokenResponse, Result, approveConsent, buildStepUpResponse, buildUnauthorizedResponse, computeS256Challenge, createMcpModule, createMcpResponseHelpers, extractBasicAuth, extractBearerToken, generateSecureToken, getAuthorizationServerMetadata, getProtectedResourceMetadata, handleAuthorize, handleTokenExchange, parseRequestBody, registerClient, requireScopes, validateAccessToken, verifyS256, withMcpAuth };