@leanmcp/auth 0.3.1 → 0.4.0

package/dist/server/index.d.mts

@@ -0,0 +1,496 @@
+import { Router } from 'express';
+
+/**
+ * JWT Utilities for Stateless OAuth
+ *
+ * Provides cryptographic functions for:
+ * - JWT signing and verification (HS256)
+ * - Upstream token encryption/decryption (AES-256-GCM)
+ */
+/**
+ * Encrypted token structure for upstream credentials
+ */
+interface EncryptedToken {
+    ciphertext: string;
+    iv: string;
+    tag: string;
+}
+/**
+ * JWT payload structure (RFC 7519 + custom claims)
+ */
+interface JWTPayload {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    jti?: string;
+    scope?: string;
+    client_id?: string;
+    name?: string;
+    email?: string;
+    picture?: string;
+    upstream_provider?: string;
+    upstream_token?: EncryptedToken;
+    upstream_refresh_token?: EncryptedToken;
+}
+
+/**
+ * Server-side OAuth types for MCP Authorization
+ *
+ * Types for Authorization Server, Dynamic Client Registration,
+ * and Token Verification per MCP spec.
+ */
+/**
+ * Client registration request (RFC 7591 Section 2)
+ */
+interface ClientRegistrationRequest {
+    /** Array of redirect URIs */
+    redirect_uris?: string[];
+    /** OAuth 2.0 grant types */
+    grant_types?: ('authorization_code' | 'refresh_token' | 'client_credentials')[];
+    /** OAuth 2.0 response types */
+    response_types?: ('code' | 'token')[];
+    /** Client name */
+    client_name?: string;
+    /** Client URI */
+    client_uri?: string;
+    /** Logo URI */
+    logo_uri?: string;
+    /** Token endpoint auth method */
+    token_endpoint_auth_method?: 'none' | 'client_secret_post' | 'client_secret_basic';
+    /** Scope */
+    scope?: string;
+    /** Contacts */
+    contacts?: string[];
+    /** Software ID */
+    software_id?: string;
+    /** Software version */
+    software_version?: string;
+}
+/**
+ * Client registration response (RFC 7591 Section 3.2.1)
+ */
+interface ClientRegistrationResponse {
+    /** Issued client ID */
+    client_id: string;
+    /** Issued client secret (for confidential clients) */
+    client_secret?: string;
+    /** Timestamp when client_id was issued */
+    client_id_issued_at?: number;
+    /** Timestamp when client_secret expires (0 = never) */
+    client_secret_expires_at?: number;
+    /** All registration request fields echoed back */
+    redirect_uris?: string[];
+    grant_types?: string[];
+    response_types?: string[];
+    client_name?: string;
+    token_endpoint_auth_method?: string;
+}
+/**
+ * Registered client stored in memory/storage
+ */
+interface RegisteredClient {
+    client_id: string;
+    client_secret?: string;
+    redirect_uris: string[];
+    grant_types: string[];
+    response_types: string[];
+    client_name?: string;
+    token_endpoint_auth_method: string;
+    created_at: number;
+    expires_at?: number;
+}
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414)
+ */
+interface AuthorizationServerMetadata {
+    /** Authorization server's issuer identifier URL */
+    issuer: string;
+    /** URL of the authorization endpoint */
+    authorization_endpoint: string;
+    /** URL of the token endpoint */
+    token_endpoint: string;
+    /** URL of the dynamic client registration endpoint */
+    registration_endpoint?: string;
+    /** URL of the JWKS endpoint */
+    jwks_uri?: string;
+    /** Supported scopes */
+    scopes_supported?: string[];
+    /** Supported response types */
+    response_types_supported: string[];
+    /** Supported grant types */
+    grant_types_supported?: string[];
+    /** Supported PKCE code challenge methods */
+    code_challenge_methods_supported?: string[];
+    /** Supported token endpoint auth methods */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Service documentation URL */
+    service_documentation?: string;
+}
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728)
+ */
+interface ProtectedResourceMetadata {
+    /** Canonical resource identifier */
+    resource: string;
+    /** Authorization servers that can authorize access */
+    authorization_servers: string[];
+    /** Scopes supported by this resource */
+    scopes_supported?: string[];
+    /** Resource documentation URL */
+    resource_documentation?: string;
+    /** Token endpoint auth methods supported */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Introspection endpoint */
+    introspection_endpoint?: string;
+}
+/**
+ * Token claims extracted from access token
+ */
+interface TokenClaims {
+    /** Subject (user ID) */
+    sub: string;
+    /** Issuer */
+    iss: string;
+    /** Audience (resource server) */
+    aud: string | string[];
+    /** Expiration timestamp */
+    exp: number;
+    /** Issued at timestamp */
+    iat: number;
+    /** Scopes (space-separated or array) */
+    scope?: string | string[];
+    /** Client ID */
+    client_id?: string;
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Token verification result
+ */
+interface TokenVerificationResult {
+    /** Whether token is valid */
+    valid: boolean;
+    /** Extracted claims (if valid) */
+    claims?: JWTPayload;
+    /** Decrypted upstream token (if present and valid) */
+    upstreamToken?: string;
+    /** Error message (if invalid) */
+    error?: string;
+    /** Error code */
+    errorCode?: 'invalid_token' | 'expired_token' | 'insufficient_scope';
+}
+
+interface OAuthAuthorizationServerOptions {
+    /** Issuer URL (e.g., https://auth.example.com) */
+    issuer: string;
+    /** Session secret for signing state parameters */
+    sessionSecret: string;
+    /** JWT signing secret (for HS256) */
+    jwtSigningSecret?: string;
+    /** JWT encryption secret (32 bytes for AES-256) */
+    jwtEncryptionSecret?: Buffer;
+    /** Upstream OAuth provider configuration (e.g., GitHub, Google) */
+    upstreamProvider?: {
+        id: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        clientId: string;
+        clientSecret: string;
+        scopes?: string[];
+        userInfoEndpoint?: string;
+    };
+    /** Scopes to advertise */
+    scopesSupported?: string[];
+    /** Enable dynamic client registration */
+    enableDCR?: boolean;
+    /** Token TTL in seconds (default: 3600) */
+    tokenTTL?: number;
+    /** Refresh token TTL in seconds (default: 2592000 = 30 days) */
+    refreshTokenTTL?: number;
+    /** Custom token mapper */
+    tokenMapper?: (upstreamTokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+    }, userInfo: Record<string, unknown>) => Promise<{
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+    }>;
+}
+/**
+ * DCR options
+ */
+interface DynamicClientRegistrationOptions {
+    /** Client ID prefix */
+    clientIdPrefix?: string;
+    /** Client secret length in bytes */
+    clientSecretLength?: number;
+    /** Client TTL in seconds (0 = never expires) */
+    clientTTL?: number;
+}
+/**
+ * Token verifier options
+ */
+interface TokenVerifierOptions {
+    /** Expected audience (resource server URL) */
+    audience: string;
+    /** Expected issuer */
+    issuer: string;
+    /** JWKS URI for RS256/ES256 signature verification */
+    jwksUri?: string;
+    /** Symmetric secret for HS256 tokens */
+    secret?: string;
+    /** Encryption secret for decrypting upstream tokens (32 bytes) */
+    encryptionSecret?: Buffer;
+    /** Clock tolerance in seconds for exp/nbf checks */
+    clockTolerance?: number;
+}
+
+/**
+ * OAuth Authorization Server
+ *
+ * MCP-compliant OAuth 2.1 authorization server that can proxy to
+ * external providers like GitHub, Google, etc.
+ *
+ * Implements:
+ * - RFC 8414: Authorization Server Metadata
+ * - RFC 7591: Dynamic Client Registration
+ * - RFC 8707: Resource Indicators
+ * - OAuth 2.1 with PKCE
+ */
+
+/**
+ * OAuth Authorization Server for MCP
+ *
+ * Creates Express routes for a complete OAuth 2.1 authorization server
+ * that can proxy authentication to external providers.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { OAuthAuthorizationServer } from '@leanmcp/auth/server';
+ *
+ * const app = express();
+ *
+ * const authServer = new OAuthAuthorizationServer({
+ *   issuer: 'https://mcp.example.com',
+ *   sessionSecret: process.env.SESSION_SECRET!,
+ *   upstreamProvider: {
+ *     id: 'github',
+ *     authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+ *     tokenEndpoint: 'https://github.com/login/oauth/access_token',
+ *     clientId: process.env.GITHUB_CLIENT_ID!,
+ *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     scopes: ['read:user', 'repo'],
+ *     userInfoEndpoint: 'https://api.github.com/user',
+ *   },
+ *   scopesSupported: ['read:user', 'repo'],
+ * });
+ *
+ * app.use(authServer.getRouter());
+ * ```
+ */
+declare class OAuthAuthorizationServer {
+    private options;
+    private dcr;
+    constructor(options: OAuthAuthorizationServerOptions);
+    /**
+     * Generate state parameter with HMAC signature
+     */
+    private generateState;
+    /**
+     * Verify state parameter signature
+     */
+    private verifyState;
+    /**
+     * Generate an authorization code
+     */
+    private generateAuthCode;
+    /**
+     * Generate JWT access token with encrypted upstream credentials
+     */
+    private generateAccessToken;
+    /**
+     * Get authorization server metadata (RFC 8414)
+     */
+    getMetadata(): AuthorizationServerMetadata;
+    /**
+     * Get Express router with all OAuth endpoints
+     */
+    getRouter(): Router;
+    /**
+     * Handle authorization request
+     */
+    private handleAuthorize;
+    /**
+     * Handle callback from upstream provider
+     */
+    private handleCallback;
+    /**
+     * Handle token request
+     */
+    private handleToken;
+    /**
+     * Handle authorization code grant
+     */
+    private handleAuthCodeGrant;
+}
+
+/**
+ * Dynamic Client Registration (RFC 7591) - Stateless Implementation
+ *
+ * Uses signed JWTs as client credentials for serverless compatibility.
+ * No storage required - all client data is encoded in the credentials.
+ */
+
+/**
+ * Dynamic Client Registration handler (Stateless)
+ *
+ * Client credentials are JWTs signed by the server:
+ * - client_id: JWT containing client metadata
+ * - client_secret: HMAC signature derived from client_id
+ *
+ * This eliminates the need for storage while maintaining security.
+ *
+ * @example
+ * ```typescript
+ * const dcr = new DynamicClientRegistration({
+ *   signingSecret: process.env.DCR_SIGNING_SECRET,
+ *   clientIdPrefix: 'chatgpt_',
+ *   clientTTL: 0, // Never expires
+ * });
+ *
+ * // Register a client
+ * const { client_id, client_secret } = dcr.register({
+ *   redirect_uris: ['https://chatgpt.com/callback'],
+ *   grant_types: ['authorization_code'],
+ * });
+ *
+ * // Validate credentials (no storage lookup needed)
+ * if (dcr.validate(client_id, client_secret)) {
+ *   // Valid client
+ * }
+ * ```
+ */
+declare class DynamicClientRegistration {
+    private options;
+    constructor(options: DynamicClientRegistrationOptions & {
+        signingSecret: string;
+    });
+    /**
+     * Register a new OAuth client (stateless)
+     *
+     * @param request - Client registration request per RFC 7591
+     * @returns Client registration response with JWT credentials
+     */
+    register(request: ClientRegistrationRequest): ClientRegistrationResponse;
+    /**
+     * Validate client credentials (stateless)
+     *
+     * @param clientId - Client ID (JWT with prefix)
+     * @param clientSecret - Client secret (optional for public clients)
+     * @returns Whether credentials are valid
+     */
+    validate(clientId: string, clientSecret?: string): boolean;
+    /**
+     * Get a registered client by ID (stateless)
+     */
+    getClient(clientId: string): RegisteredClient | undefined;
+    /**
+     * Validate redirect URI for a client
+     */
+    validateRedirectUri(clientId: string, redirectUri: string): boolean;
+    /**
+     * Delete a client (no-op in stateless mode)
+     *
+     * In stateless mode, clients cannot be truly "deleted" because
+     * their credentials are self-contained. They will expire naturally
+     * or when the signing secret is rotated.
+     */
+    delete(clientId: string): boolean;
+    /**
+     * List all registered clients (not supported in stateless mode)
+     */
+    listClients(): RegisteredClient[];
+    /**
+     * Clear all clients (no-op in stateless mode)
+     */
+    clearAll(): void;
+    /**
+     * Extract JWT from prefixed client_id
+     */
+    private extractJWT;
+    /**
+     * Derive client secret from client_id JWT
+     *
+     * Uses HMAC to create a deterministic secret that can be
+     * validated without storage.
+     */
+    private deriveClientSecret;
+}
+
+/**
+ * Token Verifier
+ *
+ * Verifies JWT access tokens on the resource server side.
+ */
+
+/**
+ * Token Verifier for resource servers
+ *
+ * @example
+ * ```typescript
+ * const verifier = new TokenVerifier({
+ *   audience: 'https://mcp.example.com',
+ *   issuer: 'https://auth.example.com',
+ *   secret: process.env.JWT_SIGNING_SECRET,
+ *   encryptionSecret: Buffer.from(process.env.JWT_ENCRYPTION_SECRET, 'hex'),
+ * });
+ *
+ * const result = await verifier.verify(accessToken);
+ * if (result.valid) {
+ *   console.log('User:', result.claims.sub);
+ *   console.log('Upstream token:', result.upstreamToken);
+ * } else {
+ *   console.error('Invalid token:', result.error);
+ * }
+ * ```
+ */
+declare class TokenVerifier {
+    private options;
+    constructor(options: TokenVerifierOptions & {
+        encryptionSecret?: Buffer;
+    });
+    /**
+     * Verify a JWT access token
+     *
+     * @param token - The JWT access token to verify
+     * @returns Verification result with claims and decrypted upstream token if valid
+     */
+    verify(token: string): Promise<TokenVerificationResult & {
+        upstreamToken?: string;
+    }>;
+    /**
+     * Generate WWW-Authenticate header for 401 responses
+     *
+     * Per RFC 9728, this should include the resource_metadata URL
+     *
+     * @param options - Header options
+     * @returns WWW-Authenticate header value
+     */
+    static getWWWAuthenticateHeader(options: {
+        resourceMetadataUrl: string;
+        error?: string;
+        errorDescription?: string;
+        scope?: string;
+    }): string;
+    /**
+     * Check if token has required scopes
+     */
+    hasScopes(claims: JWTPayload, requiredScopes: string[]): boolean;
+}
+
+export { type AuthorizationServerMetadata, type ClientRegistrationRequest, type ClientRegistrationResponse, DynamicClientRegistration, type DynamicClientRegistrationOptions, OAuthAuthorizationServer, type OAuthAuthorizationServerOptions, type ProtectedResourceMetadata, type RegisteredClient, type TokenClaims, type TokenVerificationResult, TokenVerifier, type TokenVerifierOptions };