@vfarcic/dot-ai 1.5.0 → 1.6.0

package/dist/interfaces/oauth/middleware.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Dual-mode authentication middleware for PRD #380.
+ *
+ * Validates Bearer tokens in two modes:
+ * 1. JWT (HMAC-SHA256) — returns UserIdentity when valid
+ * 2. Legacy DOT_AI_AUTH_TOKEN — constant-time comparison fallback
+ *
+ * All existing tests continue to pass because the legacy path is preserved.
+ */
+import { IncomingMessage } from 'node:http';
+import type { AuthResult } from './types';
+/**
+ * Check Bearer token authentication (dual-mode: JWT + legacy token).
+ *
+ * Order: JWT verification first, legacy DOT_AI_AUTH_TOKEN fallback second.
+ * When neither auth method is configured, authentication is disabled (backward compatible).
+ *
+ * @param req - The incoming HTTP request
+ * @returns AuthResult with optional UserIdentity when JWT auth succeeds
+ */
+export declare function checkBearerAuth(req: IncomingMessage): AuthResult;
+/**
+ * Check if authentication is enabled.
+ * True when either legacy token or JWT secret is configured.
+ */
+export declare function isAuthEnabled(): boolean;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/interfaces/oauth/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/interfaces/oauth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG1C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,CAyFhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}

package/dist/interfaces/oauth/middleware.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Dual-mode authentication middleware for PRD #380.
+ *
+ * Validates Bearer tokens in two modes:
+ * 1. JWT (HMAC-SHA256) — returns UserIdentity when valid
+ * 2. Legacy DOT_AI_AUTH_TOKEN — constant-time comparison fallback
+ *
+ * All existing tests continue to pass because the legacy path is preserved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkBearerAuth = checkBearerAuth;
+exports.isAuthEnabled = isAuthEnabled;
+const node_crypto_1 = require("node:crypto");
+const jwt_1 = require("./jwt");
+/**
+ * Check Bearer token authentication (dual-mode: JWT + legacy token).
+ *
+ * Order: JWT verification first, legacy DOT_AI_AUTH_TOKEN fallback second.
+ * When neither auth method is configured, authentication is disabled (backward compatible).
+ *
+ * @param req - The incoming HTTP request
+ * @returns AuthResult with optional UserIdentity when JWT auth succeeds
+ */
+function checkBearerAuth(req) {
+    const legacyToken = process.env.DOT_AI_AUTH_TOKEN;
+    const jwtSecret = process.env.DOT_AI_JWT_SECRET;
+    // If no auth is configured, reject — DOT_AI_AUTH_TOKEN is required
+    if (!legacyToken && !jwtSecret) {
+        return {
+            authorized: false,
+            message: 'Authentication is not configured. Set DOT_AI_AUTH_TOKEN in your deployment.',
+        };
+    }
+    // Extract Authorization header
+    const rawAuthHeader = req.headers['authorization'];
+    if (!rawAuthHeader) {
+        return {
+            authorized: false,
+            message: 'Authentication required. Provide Authorization: Bearer <token> header.',
+        };
+    }
+    // Normalize header to string (handle array case)
+    const authHeader = Array.isArray(rawAuthHeader)
+        ? (rawAuthHeader[0] ?? '')
+        : rawAuthHeader;
+    // Parse Bearer token (ReDoS-safe: indexOf instead of regex)
+    const trimmedHeader = authHeader.trim();
+    const spaceIndex = trimmedHeader.indexOf(' ');
+    if (spaceIndex === -1) {
+        return {
+            authorized: false,
+            message: 'Invalid authorization format. Expected: Bearer <token>',
+        };
+    }
+    const scheme = trimmedHeader.slice(0, spaceIndex);
+    const providedToken = trimmedHeader.slice(spaceIndex + 1).trim();
+    // Validate Bearer scheme (case-insensitive per RFC 7235)
+    if (scheme.toLowerCase() !== 'bearer') {
+        return {
+            authorized: false,
+            message: 'Invalid authorization format. Expected: Bearer <token>',
+        };
+    }
+    if (!providedToken) {
+        return { authorized: false, message: 'Bearer token is empty.' };
+    }
+    // Mode 1: Try JWT verification
+    const secret = jwtSecret || (0, jwt_1.getJwtSecret)();
+    const claims = (0, jwt_1.verifyJwt)(providedToken, secret);
+    if (claims) {
+        return {
+            authorized: true,
+            identity: {
+                userId: claims.sub,
+                email: claims.email,
+                groups: claims.groups ?? [],
+                source: 'oauth',
+            },
+        };
+    }
+    // Mode 2: Fall back to legacy DOT_AI_AUTH_TOKEN comparison
+    if (legacyToken) {
+        const configuredBuffer = Buffer.from(legacyToken, 'utf8');
+        const providedBuffer = Buffer.from(providedToken, 'utf8');
+        if (configuredBuffer.length !== providedBuffer.length) {
+            // Dummy comparison to maintain constant time
+            (0, node_crypto_1.timingSafeEqual)(configuredBuffer, configuredBuffer);
+            return { authorized: false, message: 'Invalid authentication token.' };
+        }
+        if ((0, node_crypto_1.timingSafeEqual)(configuredBuffer, providedBuffer)) {
+            return {
+                authorized: true,
+                identity: { userId: 'anonymous', groups: [], source: 'token' },
+            };
+        }
+    }
+    return { authorized: false, message: 'Invalid authentication token.' };
+}
+/**
+ * Check if authentication is enabled.
+ * True when either legacy token or JWT secret is configured.
+ */
+function isAuthEnabled() {
+    return !!process.env.DOT_AI_AUTH_TOKEN || !!process.env.DOT_AI_JWT_SECRET;
+}

package/dist/interfaces/oauth/provider.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MCP SDK OAuth Server Provider for PRD #380.
+ *
+ * Implements the SDK's OAuthServerProvider interface with:
+ * - In-memory client store (clients re-register on restart per MCP spec)
+ * - Dual-mode token verification (JWT + legacy DOT_AI_AUTH_TOKEN)
+ * - Dex OIDC integration for authorize/callback/token flow (Task 2.3)
+ */
+import type { Request, Response } from 'express';
+import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
+import type { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+/**
+ * In-memory client store for OAuth registered clients.
+ * Clients re-register on server restart per the MCP Authorization spec.
+ */
+export declare class DotAIClientsStore implements OAuthRegisteredClientsStore {
+    private clients;
+    getClient(clientId: string): OAuthClientInformationFull | undefined;
+    registerClient(client: Omit<OAuthClientInformationFull, 'client_id' | 'client_id_issued_at'>): OAuthClientInformationFull;
+    /** Clear all registered clients. For testing only. @internal */
+    _clearClients(): void;
+}
+/**
+ * OAuth Server Provider for dot-ai.
+ *
+ * Acts as the OAuth Authorization Server for MCP clients. On authorize,
+ * redirects the browser to Dex for authentication, then exchanges the
+ * Dex code for an ID token and issues a dot-ai JWT.
+ *
+ * Token verification supports dual-mode: JWT first, legacy token fallback.
+ */
+export declare class DotAIOAuthProvider implements OAuthServerProvider {
+    readonly clientsStore: DotAIClientsStore;
+    private pendingRequests;
+    private authCodes;
+    private dexConfig;
+    private dotAiExternalUrl;
+    private pruneTimer;
+    constructor();
+    /**
+     * Periodically remove expired entries from pendingRequests and authCodes
+     * to prevent unbounded memory growth from abandoned OAuth flows.
+     */
+    private startPruning;
+    /** Remove expired pending requests and authorization codes. */
+    private pruneExpired;
+    /** Stop the pruning timer. For testing only. @internal */
+    _stopPruning(): void;
+    private loadDexConfig;
+    /**
+     * Start the authorization flow by redirecting the browser to Dex.
+     *
+     * Stores the pending auth request (PKCE challenge, redirect URI, state)
+     * keyed by a random session ID, then encodes sessionId|originalState
+     * in the Dex state param so the callback can recover the pending request.
+     */
+    authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    /**
+     * Return the PKCE code challenge for a given authorization code.
+     *
+     * Called by the SDK's tokenHandler BEFORE exchangeAuthorizationCode.
+     * Do NOT delete the code here — it is consumed in exchangeAuthorizationCode.
+     */
+    challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
+    /**
+     * Exchange a dot-ai authorization code for a JWT access token.
+     *
+     * Called by the SDK's tokenHandler AFTER PKCE verification passes.
+     * Consumes the authorization code (one-time use) and signs a JWT
+     * containing the user's identity from the Dex ID token.
+     */
+    exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string, _resource?: URL): Promise<OAuthTokens>;
+    exchangeRefreshToken(_client: OAuthClientInformationFull, _refreshToken: string, _scopes?: string[], _resource?: URL): Promise<OAuthTokens>;
+    /**
+     * Handle the Dex OIDC callback after user authenticates.
+     *
+     * Receives the redirect from Dex with ?code=DEX_CODE&state=sessionId|originalState.
+     * Exchanges the Dex code for an ID token, extracts user identity,
+     * creates a dot-ai authorization code, and redirects to the MCP client.
+     */
+    handleCallback(req: Request, res: Response): Promise<void>;
+    /**
+     * Verify an access token (dual-mode: JWT + legacy token).
+     *
+     * 1. If no auth configured → anonymous access (backward compatible)
+     * 2. Try JWT verification → returns AuthInfo with identity in `extra`
+     * 3. Fall back to legacy DOT_AI_AUTH_TOKEN → returns AuthInfo without identity
+     * 4. Throw InvalidTokenError on failure
+     */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/interfaces/oauth/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/interfaces/oauth/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kDAAkD,CAAC;AACpG,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAM/E,OAAO,KAAK,EACV,0BAA0B,EAC1B,WAAW,EACZ,MAAM,0CAA0C,CAAC;AAelD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,2BAA2B;IACnE,OAAO,CAAC,OAAO,CAAiD;IAEhE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,0BAA0B,GAAG,SAAS;IAInE,cAAc,CACZ,MAAM,EAAE,IAAI,CAAC,0BAA0B,EAAE,WAAW,GAAG,qBAAqB,CAAC,GAC5E,0BAA0B;IAQ7B,gEAAgE;IAChE,aAAa,IAAI,IAAI;CAGtB;AAWD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAA+C;;IASjE;;;OAGG;IACH,OAAO,CAAC,YAAY;IAMpB,+DAA+D;IAC/D,OAAO,CAAC,YAAY;IAcpB,0DAA0D;IAC1D,YAAY,IAAI,IAAI;IAOpB,OAAO,CAAC,aAAa;IAYrB;;;;;;OAMG;IACG,SAAS,CACb,MAAM,EAAE,0BAA0B,EAClC,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,IAAI,CAAC;IAgChB;;;;;OAKG;IACG,6BAA6B,CACjC,MAAM,EAAE,0BAA0B,EAClC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,CAAC;IAoBlB;;;;;;OAMG;IACG,yBAAyB,CAC7B,MAAM,EAAE,0BAA0B,EAClC,iBAAiB,EAAE,MAAM,EACzB,aAAa,CAAC,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,GAAG,GACd,OAAO,CAAC,WAAW,CAAC;IA6CjB,oBAAoB,CACxB,OAAO,EAAE,0BAA0B,EACnC,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,SAAS,CAAC,EAAE,GAAG,GACd,OAAO,CAAC,WAAW,CAAC;IAIvB;;;;;;OAMG;IACG,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6FhE;;;;;;;OAOG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CA2D1D"}

package/dist/interfaces/oauth/provider.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * MCP SDK OAuth Server Provider for PRD #380.
+ *
+ * Implements the SDK's OAuthServerProvider interface with:
+ * - In-memory client store (clients re-register on restart per MCP spec)
+ * - Dual-mode token verification (JWT + legacy DOT_AI_AUTH_TOKEN)
+ * - Dex OIDC integration for authorize/callback/token flow (Task 2.3)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DotAIOAuthProvider = exports.DotAIClientsStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("@modelcontextprotocol/sdk/server/auth/errors.js");
+const jwt_1 = require("./jwt");
+const dex_client_1 = require("./dex-client");
+/**
+ * Safely extract a single string from an Express query parameter.
+ * Query params can be string, string[], or undefined when tampered.
+ */
+function extractQueryParam(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && typeof value[0] === 'string')
+        return value[0];
+    return undefined;
+}
+/**
+ * In-memory client store for OAuth registered clients.
+ * Clients re-register on server restart per the MCP Authorization spec.
+ */
+class DotAIClientsStore {
+    clients = new Map();
+    getClient(clientId) {
+        return this.clients.get(clientId);
+    }
+    registerClient(client) {
+        // SDK pre-populates client_id, client_secret, timestamps before calling this.
+        // The Omit type is the interface contract, but the actual object has all fields.
+        const fullClient = client;
+        this.clients.set(fullClient.client_id, fullClient);
+        return fullClient;
+    }
+    /** Clear all registered clients. For testing only. @internal */
+    _clearClients() {
+        this.clients.clear();
+    }
+}
+exports.DotAIClientsStore = DotAIClientsStore;
+/** Max age for pending auth requests (10 minutes). */
+const PENDING_REQUEST_TTL_MS = 10 * 60 * 1000;
+/** Max age for authorization codes (5 minutes). */
+const AUTH_CODE_TTL_MS = 5 * 60 * 1000;
+/** Separator between session ID and original state in the Dex state param. */
+const STATE_SEPARATOR = '|';
+/**
+ * OAuth Server Provider for dot-ai.
+ *
+ * Acts as the OAuth Authorization Server for MCP clients. On authorize,
+ * redirects the browser to Dex for authentication, then exchanges the
+ * Dex code for an ID token and issues a dot-ai JWT.
+ *
+ * Token verification supports dual-mode: JWT first, legacy token fallback.
+ */
+class DotAIOAuthProvider {
+    clientsStore;
+    pendingRequests = new Map();
+    authCodes = new Map();
+    dexConfig;
+    dotAiExternalUrl;
+    pruneTimer = null;
+    constructor() {
+        this.clientsStore = new DotAIClientsStore();
+        this.dexConfig = this.loadDexConfig();
+        this.dotAiExternalUrl = (process.env.DOT_AI_EXTERNAL_URL || '').replace(/\/$/, '');
+        this.startPruning();
+    }
+    /**
+     * Periodically remove expired entries from pendingRequests and authCodes
+     * to prevent unbounded memory growth from abandoned OAuth flows.
+     */
+    startPruning() {
+        // Run every 60 seconds — lightweight scan of small maps
+        this.pruneTimer = setInterval(() => this.pruneExpired(), 60_000);
+        this.pruneTimer.unref(); // Don't prevent Node.js from exiting
+    }
+    /** Remove expired pending requests and authorization codes. */
+    pruneExpired() {
+        const now = Date.now();
+        for (const [key, req] of this.pendingRequests) {
+            if (now - req.createdAt > PENDING_REQUEST_TTL_MS) {
+                this.pendingRequests.delete(key);
+            }
+        }
+        for (const [key, code] of this.authCodes) {
+            if (now > code.expiresAt) {
+                this.authCodes.delete(key);
+            }
+        }
+    }
+    /** Stop the pruning timer. For testing only. @internal */
+    _stopPruning() {
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+    }
+    loadDexConfig() {
+        const issuerUrl = process.env.DEX_ISSUER_URL;
+        const clientId = process.env.DEX_CLIENT_ID;
+        const clientSecret = process.env.DEX_CLIENT_SECRET;
+        if (!issuerUrl || !clientId || !clientSecret) {
+            return null;
+        }
+        const tokenEndpoint = process.env.DEX_TOKEN_ENDPOINT
+            || `${issuerUrl.replace(/\/$/, '')}/token`;
+        return { issuerUrl, tokenEndpoint, clientId, clientSecret };
+    }
+    /**
+     * Start the authorization flow by redirecting the browser to Dex.
+     *
+     * Stores the pending auth request (PKCE challenge, redirect URI, state)
+     * keyed by a random session ID, then encodes sessionId|originalState
+     * in the Dex state param so the callback can recover the pending request.
+     */
+    async authorize(client, params, res) {
+        if (!this.dexConfig) {
+            throw new errors_js_1.ServerError('Dex not configured (set DEX_ISSUER_URL, DEX_CLIENT_ID, DEX_CLIENT_SECRET)');
+        }
+        if (!this.dotAiExternalUrl) {
+            throw new errors_js_1.ServerError('DOT_AI_EXTERNAL_URL is required for OAuth. Set it to the external URL of the dot-ai server.');
+        }
+        const sessionId = (0, node_crypto_1.randomBytes)(16).toString('hex');
+        const pending = {
+            clientId: client.client_id,
+            redirectUri: params.redirectUri,
+            codeChallenge: params.codeChallenge,
+            codeChallengeMethod: 'S256',
+            state: params.state ?? '',
+            createdAt: Date.now(),
+        };
+        this.pendingRequests.set(sessionId, pending);
+        const dexState = `${sessionId}${STATE_SEPARATOR}${params.state ?? ''}`;
+        const callbackUrl = `${this.dotAiExternalUrl}/callback`;
+        const dexAuthUrl = (0, dex_client_1.buildAuthorizeUrl)(this.dexConfig, {
+            redirectUri: callbackUrl,
+            state: dexState,
+        });
+        res.redirect(302, dexAuthUrl);
+    }
+    /**
+     * Return the PKCE code challenge for a given authorization code.
+     *
+     * Called by the SDK's tokenHandler BEFORE exchangeAuthorizationCode.
+     * Do NOT delete the code here — it is consumed in exchangeAuthorizationCode.
+     */
+    async challengeForAuthorizationCode(client, authorizationCode) {
+        const record = this.authCodes.get(authorizationCode);
+        if (!record) {
+            throw new errors_js_1.InvalidGrantError('Authorization code not found or expired');
+        }
+        if (Date.now() > record.expiresAt) {
+            this.authCodes.delete(authorizationCode);
+            throw new errors_js_1.InvalidGrantError('Authorization code expired');
+        }
+        // Verify the code was issued to the requesting client (RFC 6749 §4.1.3)
+        if (record.clientId !== client.client_id) {
+            this.authCodes.delete(authorizationCode);
+            throw new errors_js_1.InvalidGrantError('Authorization code was not issued to this client');
+        }
+        return record.codeChallenge;
+    }
+    /**
+     * Exchange a dot-ai authorization code for a JWT access token.
+     *
+     * Called by the SDK's tokenHandler AFTER PKCE verification passes.
+     * Consumes the authorization code (one-time use) and signs a JWT
+     * containing the user's identity from the Dex ID token.
+     */
+    async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri, _resource) {
+        const record = this.authCodes.get(authorizationCode);
+        if (!record) {
+            throw new errors_js_1.InvalidGrantError('Authorization code not found or expired');
+        }
+        if (Date.now() > record.expiresAt) {
+            this.authCodes.delete(authorizationCode);
+            throw new errors_js_1.InvalidGrantError('Authorization code expired');
+        }
+        // Verify client_id matches (RFC 6749 §4.1.3)
+        if (record.clientId !== client.client_id) {
+            this.authCodes.delete(authorizationCode);
+            throw new errors_js_1.InvalidGrantError('Authorization code was not issued to this client');
+        }
+        // Verify redirect_uri matches the original request (RFC 6749 §4.1.3)
+        if (redirectUri && redirectUri !== record.redirectUri) {
+            this.authCodes.delete(authorizationCode);
+            throw new errors_js_1.InvalidGrantError('redirect_uri does not match the original authorization request');
+        }
+        // Consume the authorization code (one-time use)
+        this.authCodes.delete(authorizationCode);
+        const now = Math.floor(Date.now() / 1000);
+        const expiresIn = 3600; // 1 hour
+        const secret = (0, jwt_1.getJwtSecret)();
+        const accessToken = (0, jwt_1.signJwt)({
+            sub: record.userIdentity.userId,
+            email: record.userIdentity.email,
+            groups: record.userIdentity.groups,
+            iat: now,
+            exp: now + expiresIn,
+        }, secret);
+        return {
+            access_token: accessToken,
+            token_type: 'bearer',
+            expires_in: expiresIn,
+        };
+    }
+    async exchangeRefreshToken(_client, _refreshToken, _scopes, _resource) {
+        throw new errors_js_1.ServerError('Refresh tokens not supported');
+    }
+    /**
+     * Handle the Dex OIDC callback after user authenticates.
+     *
+     * Receives the redirect from Dex with ?code=DEX_CODE&state=sessionId|originalState.
+     * Exchanges the Dex code for an ID token, extracts user identity,
+     * creates a dot-ai authorization code, and redirects to the MCP client.
+     */
+    async handleCallback(req, res) {
+        const dexCode = extractQueryParam(req.query.code);
+        const encodedState = extractQueryParam(req.query.state);
+        const error = extractQueryParam(req.query.error);
+        if (error) {
+            const sessionId = encodedState?.split(STATE_SEPARATOR)[0];
+            const pending = sessionId ? this.pendingRequests.get(sessionId) : undefined;
+            if (pending) {
+                this.pendingRequests.delete(sessionId);
+                const errUrl = new URL(pending.redirectUri);
+                errUrl.searchParams.set('error', 'access_denied');
+                errUrl.searchParams.set('error_description', extractQueryParam(req.query.error_description) ?? 'Authentication failed');
+                if (pending.state)
+                    errUrl.searchParams.set('state', pending.state);
+                res.redirect(302, errUrl.toString());
+            }
+            else {
+                res.status(400).send('Authentication failed and no pending session found');
+            }
+            return;
+        }
+        if (!dexCode || !encodedState) {
+            res.status(400).send('Missing code or state parameter');
+            return;
+        }
+        const separatorIndex = encodedState.indexOf(STATE_SEPARATOR);
+        if (separatorIndex === -1) {
+            res.status(400).send('Invalid state parameter');
+            return;
+        }
+        const sessionId = encodedState.slice(0, separatorIndex);
+        const originalState = encodedState.slice(separatorIndex + 1);
+        const pending = this.pendingRequests.get(sessionId);
+        if (!pending) {
+            res.status(400).send('No pending auth request for this session (expired or invalid)');
+            return;
+        }
+        if (Date.now() - pending.createdAt > PENDING_REQUEST_TTL_MS) {
+            this.pendingRequests.delete(sessionId);
+            res.status(400).send('Auth request expired');
+            return;
+        }
+        this.pendingRequests.delete(sessionId);
+        if (!this.dexConfig) {
+            res.status(500).send('Dex not configured');
+            return;
+        }
+        try {
+            const callbackUrl = `${this.dotAiExternalUrl}/callback`;
+            const { idToken } = await (0, dex_client_1.exchangeDexCode)(this.dexConfig, dexCode, callbackUrl);
+            const claims = (0, dex_client_1.parseIdToken)(idToken);
+            const userIdentity = {
+                userId: claims.sub,
+                email: claims.email,
+                groups: claims.groups ?? [],
+                source: 'oauth',
+            };
+            const dotAiCode = (0, node_crypto_1.randomBytes)(32).toString('hex');
+            const authCode = {
+                code: dotAiCode,
+                clientId: pending.clientId,
+                redirectUri: pending.redirectUri,
+                codeChallenge: pending.codeChallenge,
+                codeChallengeMethod: 'S256',
+                userIdentity,
+                createdAt: Date.now(),
+                expiresAt: Date.now() + AUTH_CODE_TTL_MS,
+            };
+            this.authCodes.set(dotAiCode, authCode);
+            const redirectUrl = new URL(pending.redirectUri);
+            redirectUrl.searchParams.set('code', dotAiCode);
+            if (originalState)
+                redirectUrl.searchParams.set('state', originalState);
+            res.redirect(302, redirectUrl.toString());
+        }
+        catch {
+            const errUrl = new URL(pending.redirectUri);
+            errUrl.searchParams.set('error', 'server_error');
+            errUrl.searchParams.set('error_description', 'Failed to exchange code with identity provider');
+            if (originalState)
+                errUrl.searchParams.set('state', originalState);
+            res.redirect(302, errUrl.toString());
+        }
+    }
+    /**
+     * Verify an access token (dual-mode: JWT + legacy token).
+     *
+     * 1. If no auth configured → anonymous access (backward compatible)
+     * 2. Try JWT verification → returns AuthInfo with identity in `extra`
+     * 3. Fall back to legacy DOT_AI_AUTH_TOKEN → returns AuthInfo without identity
+     * 4. Throw InvalidTokenError on failure
+     */
+    async verifyAccessToken(token) {
+        const legacyToken = process.env.DOT_AI_AUTH_TOKEN;
+        const jwtSecretEnv = process.env.DOT_AI_JWT_SECRET;
+        // No auth configured → allow all (backward compatible)
+        if (!legacyToken && !jwtSecretEnv) {
+            return {
+                token,
+                clientId: 'anonymous',
+                scopes: [],
+                expiresAt: Math.floor(Date.now() / 1000) + 3600,
+            };
+        }
+        // Mode 1: JWT verification
+        const secret = jwtSecretEnv || (0, jwt_1.getJwtSecret)();
+        const claims = (0, jwt_1.verifyJwt)(token, secret);
+        if (claims) {
+            return {
+                token,
+                clientId: claims.sub,
+                scopes: [],
+                expiresAt: claims.exp,
+                extra: {
+                    identity: {
+                        userId: claims.sub,
+                        email: claims.email,
+                        groups: claims.groups ?? [],
+                        source: 'oauth',
+                    },
+                },
+            };
+        }
+        // Mode 2: Legacy DOT_AI_AUTH_TOKEN comparison
+        if (legacyToken) {
+            const configuredBuffer = Buffer.from(legacyToken, 'utf8');
+            const providedBuffer = Buffer.from(token, 'utf8');
+            let isMatch = false;
+            if (configuredBuffer.length === providedBuffer.length) {
+                isMatch = (0, node_crypto_1.timingSafeEqual)(configuredBuffer, providedBuffer);
+            }
+            else {
+                // Dummy comparison to maintain constant time
+                (0, node_crypto_1.timingSafeEqual)(configuredBuffer, configuredBuffer);
+            }
+            if (isMatch) {
+                return {
+                    token,
+                    clientId: 'legacy',
+                    scopes: [],
+                    expiresAt: Math.floor(Date.now() / 1000) + 3600,
+                };
+            }
+        }
+        throw new errors_js_1.InvalidTokenError('Invalid authentication token.');
+    }
+}
+exports.DotAIOAuthProvider = DotAIOAuthProvider;