catence 0.2.1-beta.2 → 0.2.1-beta.21

package/dist/interfaces/http/cli-options.js

@@ -1,3 +1,6 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { readMcpOauthSettings } from '../../runtime/index.js';
 export const SERVE_USAGE = `Usage: catence serve [options]
 
 Run Catence as a local Streamable HTTP MCP server.
@@ -7,7 +10,155 @@ Options:
   --host <host>              Listener host. Defaults to 127.0.0.1.
   --port <port>              Listener port. Defaults to 8787.
   --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.
+  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;
+                             generate/inspect it with 'catence-data mcp enable|token'.
+                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.
+  --mcp-keys-file <path>     Per-account MCP key registry for the HTTP gate. Any active key in it
+                             switches authentication on; manage keys with 'catence-data mcp key'.
+                             Defaults to CATENCE_MCP_KEYS_FILE or <catalog-home>/mcp-keys.json.
+  --oauth                    Run the OAuth 2.1 authorization server (issuer = --public-url) so
+                             ChatGPT/Codex-style MCP clients connect with a per-account consent
+                             login. Requires --public-url. Defaults to CATENCE_OAUTH_ENABLED=1/true.
+                             The Console settings file overrides this at runtime.
+  --public-url <url>         Public https URL of this server (no query string or fragment), e.g.
+                             the tunnel URL. Required when --oauth is enabled.
+                             Defaults to CATENCE_PUBLIC_URL.
+  --oauth-settings-file <path>
+                             Console-managed OAuth settings that override --oauth/--public-url
+                             at runtime. Defaults to CATENCE_OAUTH_SETTINGS_FILE or
+                             <catalog-home>/oauth/settings.json.
   -h, --help                 Show this help text.`;
+/** The canonical token location inside a catalog home. */
+export function defaultBearerTokenPath(catalogRoot) {
+    return `${catalogRoot.replace(/[/\\]+$/, '')}/mcp-token`;
+}
+/** The canonical per-account MCP key registry location inside a catalog home. */
+export function defaultMcpKeysPath(catalogRoot) {
+    return `${catalogRoot.replace(/[/\\]+$/, '')}/mcp-keys.json`;
+}
+/** The canonical Console-managed OAuth settings location inside a catalog home. */
+export function defaultOauthSettingsPath(catalogRoot) {
+    return `${catalogRoot.replace(/[/\\]+$/, '')}/oauth/settings.json`;
+}
+/** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
+export function loadBearerToken(filePath) {
+    let token;
+    try {
+        token = readFileSync(filePath, 'utf8').trim();
+    }
+    catch (error) {
+        throw new Error(`Cannot read the auth token file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!token)
+        throw new Error(`The auth token file ${filePath} is empty.`);
+    return token;
+}
+/**
+ * The bearer token for the server: the stored one, or a freshly generated
+ * token written to the file (mode 0600) when it does not exist yet. Users
+ * never hand-craft tokens; they enable auth and read the result with
+ * `catence-data mcp-token`.
+ */
+export function ensureBearerToken(filePath) {
+    if (existsSync(filePath))
+        return loadBearerToken(filePath);
+    const token = randomBytes(32).toString('hex');
+    writeFileSync(filePath, token, { mode: 0o600 });
+    return token;
+}
+export function disableBearerToken(filePath) {
+    if (existsSync(filePath))
+        rmSync(filePath);
+}
+/** The bearer token when exposure is enabled, or null when no token file exists. */
+export function readBearerToken(filePath) {
+    return existsSync(filePath) ? loadBearerToken(filePath) : null;
+}
+const tokenCache = new Map();
+/**
+ * The currently active bearer token for the HTTP gate, cached by the token
+ * file's mtime so enabling or disabling is picked up without a restart. A
+ * missing file disables the gate; an existing but unreadable or empty file
+ * fails closed (the gate rejects everything except health probes).
+ */
+export function activeBearerToken(filePath) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(filePath).mtimeMs;
+    }
+    catch {
+        tokenCache.set(filePath, { mtimeMs: 0, token: null });
+        return null;
+    }
+    const cached = tokenCache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+        return cached.token === null ? 'invalid' : cached.token;
+    }
+    try {
+        const token = loadBearerToken(filePath);
+        tokenCache.set(filePath, { mtimeMs, token });
+        return token;
+    }
+    catch {
+        tokenCache.set(filePath, { mtimeMs, token: null });
+        return 'invalid';
+    }
+}
+export function mcpExposureStatus(filePath, endpointBase, oauth) {
+    const token = readBearerToken(filePath);
+    const base = endpointBase.replace(/\/+$/, '');
+    return {
+        enabled: token !== null,
+        tokenFile: filePath,
+        endpoint: `${base}/mcp`,
+        healthEndpoint: `${base}/health`,
+        ...(token !== null ? { token } : {}),
+        ...(oauth !== undefined ? { oauth } : {}),
+    };
+}
+/** True when CATENCE_OAUTH_ENABLED is 1/true. */
+export function oauthEnabledFromEnv(env = process.env) {
+    const value = env.CATENCE_OAUTH_ENABLED;
+    return value === '1' || value === 'true';
+}
+/** The OAuth exposure reported by `catence-data mcp status`, read from the environment. */
+export function oauthStatusFromEnv(env = process.env) {
+    const publicUrl = env.CATENCE_PUBLIC_URL || undefined;
+    return { enabled: oauthEnabledFromEnv(env), ...(publicUrl !== undefined ? { publicUrl } : {}) };
+}
+/**
+ * The effective OAuth exposure: the Console settings file when a valid one
+ * exists (a malformed one fails closed to disabled), else the environment.
+ * `source` records where the effective values come from.
+ */
+export function oauthStatusFromSettings(settingsFile, env = process.env) {
+    const { state, settings } = readMcpOauthSettings(settingsFile);
+    if (state === 'ok' && settings !== null) {
+        return { enabled: settings.enabled, ...(settings.publicUrl ? { publicUrl: settings.publicUrl } : {}), source: 'console' };
+    }
+    if (state === 'invalid')
+        return { enabled: false, source: 'disabled' };
+    const fromEnv = oauthStatusFromEnv(env);
+    return { ...fromEnv, source: fromEnv.enabled ? 'environment' : 'disabled' };
+}
+/**
+ * Validate the public URL: an absolute https URL with no query string or
+ * fragment (it becomes the advertised OAuth issuer), trailing slashes stripped.
+ */
+function parsePublicUrl(value, option) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${option} must be a valid absolute URL.`);
+    }
+    if (url.protocol !== 'https:')
+        throw new Error(`${option} must use https: the OAuth issuer is advertised publicly.`);
+    if (url.search || url.hash)
+        throw new Error(`${option} must not contain a query string or fragment.`);
+    return value.replace(/\/+$/, '');
+}
 function requiredValue(arguments_, index, option) {
     const value = arguments_[index + 1];
     if (!value || value.startsWith('-'))
@@ -27,10 +178,16 @@ export function parseServeCliOptions(arguments_) {
     let host = process.env.CATENCE_HTTP_HOST ?? '127.0.0.1';
     let port = process.env.CATENCE_HTTP_PORT ? parsePort(process.env.CATENCE_HTTP_PORT) : 8787;
     const allowedOrigins = [];
+    let authTokenFile = process.env.CATENCE_MCP_TOKEN_FILE || undefined;
+    let mcpKeysFile = process.env.CATENCE_MCP_KEYS_FILE || undefined;
+    let oauthSettingsFile = process.env.CATENCE_OAUTH_SETTINGS_FILE || undefined;
+    let oauth = oauthEnabledFromEnv();
+    let publicUrl = process.env.CATENCE_PUBLIC_URL || undefined;
+    let publicUrlSource = 'CATENCE_PUBLIC_URL';
     for (let index = 0; index < arguments_.length; index++) {
         const argument = arguments_[index];
         if (argument === '-h' || argument === '--help')
-            return { home, host, port, allowedOrigins, help: true };
+            return { home, host, port, allowedOrigins, authTokenFile, mcpKeysFile, oauthSettingsFile, oauth, publicUrl, help: true };
         if (argument === '--home') {
             home = requiredValue(arguments_, index, '--home');
             index++;
@@ -42,6 +199,39 @@ export function parseServeCliOptions(arguments_) {
                 throw new Error('--home requires a value.');
             continue;
         }
+        if (argument === '--auth-token-file') {
+            authTokenFile = requiredValue(arguments_, index, '--auth-token-file');
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--auth-token-file=')) {
+            authTokenFile = argument.slice('--auth-token-file='.length);
+            if (!authTokenFile)
+                throw new Error('--auth-token-file requires a value.');
+            continue;
+        }
+        if (argument === '--mcp-keys-file') {
+            mcpKeysFile = requiredValue(arguments_, index, '--mcp-keys-file');
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--mcp-keys-file=')) {
+            mcpKeysFile = argument.slice('--mcp-keys-file='.length);
+            if (!mcpKeysFile)
+                throw new Error('--mcp-keys-file requires a value.');
+            continue;
+        }
+        if (argument === '--oauth-settings-file') {
+            oauthSettingsFile = requiredValue(arguments_, index, '--oauth-settings-file');
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--oauth-settings-file=')) {
+            oauthSettingsFile = argument.slice('--oauth-settings-file='.length);
+            if (!oauthSettingsFile)
+                throw new Error('--oauth-settings-file requires a value.');
+            continue;
+        }
         if (argument === '--host') {
             host = requiredValue(arguments_, index, '--host');
             index++;
@@ -74,8 +264,30 @@ export function parseServeCliOptions(arguments_) {
             allowedOrigins.push(origin);
             continue;
         }
+        if (argument === '--oauth') {
+            oauth = true;
+            continue;
+        }
+        if (argument === '--public-url') {
+            publicUrl = requiredValue(arguments_, index, '--public-url');
+            publicUrlSource = '--public-url';
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--public-url=')) {
+            publicUrl = argument.slice('--public-url='.length);
+            if (!publicUrl)
+                throw new Error('--public-url requires a value.');
+            publicUrlSource = '--public-url';
+            continue;
+        }
         throw new Error(`Unknown option: ${argument}`);
     }
-    return { home, host, port, allowedOrigins, help: false };
+    if (publicUrl !== undefined)
+        publicUrl = parsePublicUrl(publicUrl, publicUrlSource);
+    if (oauth && publicUrl === undefined) {
+        throw new Error('--oauth requires --public-url (or CATENCE_PUBLIC_URL): the OAuth issuer is the public URL of this server.');
+    }
+    return { home, host, port, allowedOrigins, authTokenFile, mcpKeysFile, oauthSettingsFile, oauth, publicUrl, help: false };
 }
 //# sourceMappingURL=cli-options.js.map

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

@@ -0,0 +1,16 @@
+import { type Express } from 'express';
+/** What the HTTP gate needs from the lazily built OAuth sub-app. */
+export type OAuthAppHandle = {
+    /** The Express app; mounted by path delegation for /.well-known/oauth-* and /oauth/*. */
+    app: Express;
+    /** Verify a bearer access token; null when unknown, expired, or revoked. */
+    verifyAccessToken: (token: string) => Promise<{
+        userId?: string;
+    } | null>;
+    /** The RFC 9728 metadata URL advertised in the 401 WWW-Authenticate challenge. */
+    protectedResourceMetadataUrl: string;
+};
+export declare function createOAuthApp(options: {
+    catalogRoot: string;
+    publicUrl: string;
+}): Promise<OAuthAppHandle>;

package/dist/interfaces/http/oauth.js

@@ -0,0 +1,228 @@
+import path from 'node:path';
+import express from 'express';
+import { authenticateHandler, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl, mcpAuthRouter, OAuthServer, redirectUriMatches, } from 'mcp-oauth-server';
+import { asPublicClientMetadata, createFileOAuthServerModel, declaresPrivateKeyJwt, resolveCatalogPaths, verifyAccountPassword } from '../../runtime/index.js';
+/**
+ * The OAuth 2.1 authorization server for `catence serve --oauth`, built on the
+ * mcp-oauth-server package over the file-backed model in core/runtime/oauth.
+ *
+ * Layout of the public surface (issuer = publicUrl, resource = publicUrl/mcp):
+ *
+ *   GET  /.well-known/oauth-authorization-server   RFC 8414 AS metadata
+ *   GET  /.well-known/oauth-protected-resource[/mcp]  RFC 9728 PRM metadata
+ *   *    /oauth/authorize, /oauth/token, /oauth/register, /oauth/revoke
+ *        (mcpAuthRouter mounted at the root with baseUrl = publicUrl + /oauth)
+ *   GET  /oauth/consent    login + consent form (round-trips the authorize params)
+ *   POST /oauth/confirm    authenticateHandler: bcrypt login, then issues the code
+ *   POST /oauth/deny       redirects to the client with error=access_denied
+ *
+ * The consent round-trip is the lib's contract: the authorize handler 302s to
+ * authorizationUrl with the full authorize request as query params, and
+ * authenticateHandler re-validates those same params from the confirm POST
+ * body — so the consent form echoes them as hidden fields next to the
+ * username/password inputs. Credentials and tokens are never logged.
+ */
+/**
+ * Fetch wrapper for client ID metadata documents (CIMD): clients such as
+ * OpenAI's connector declare `token_endpoint_auth_method: "private_key_jwt"`
+ * in their document. The server cannot verify a client JWT assertion, so the
+ * declaration is downgraded to a public client ("none") before the library
+ * validates and caches the document — PKCE still protects the flow. The
+ * rewritten body drops content-length; the library's size guard reads the
+ * actual stream anyway.
+ *
+ * Parsing happens on a clone: every passthrough path must hand the library a
+ * response whose body is still readable, and a consumed stream would surface
+ * as an opaque 500 instead of the library's proper OAuth error.
+ */
+function sanitizingMetadataFetch(fetchImpl) {
+    return async (input, init) => {
+        const response = await fetchImpl(input, init);
+        if (!response.ok)
+            return response;
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!contentType.includes('application/json'))
+            return response;
+        let document;
+        try {
+            document = JSON.parse(await response.clone().text());
+        }
+        catch {
+            return response;
+        }
+        if (!declaresPrivateKeyJwt(document))
+            return response;
+        const rewritten = JSON.stringify(asPublicClientMetadata(document));
+        const headers = new Headers(response.headers);
+        headers.delete('content-length');
+        return new Response(rewritten, { status: response.status, statusText: response.statusText, headers });
+    };
+}
+/**
+ * DCR body sanitizer for POST /oauth/register. Mounted ahead of the library's
+ * router: it parses the JSON body and downgrades private_key_jwt to "none";
+ * the library's own express.json() then skips the already-consumed stream
+ * (body-parser returns early once the request is finished) and validates the
+ * sanitized metadata, issuing no client secret for the downgraded client.
+ */
+function sanitizeRegisterBody(request, _response, next) {
+    if (declaresPrivateKeyJwt(request.body)) {
+        request.body = asPublicClientMetadata(request.body);
+    }
+    next();
+}
+export async function createOAuthApp(options) {
+    const publicUrl = options.publicUrl.replace(/\/+$/, '');
+    const issuerUrl = new URL(publicUrl);
+    const resourceServerUrl = new URL(`${publicUrl}/mcp`);
+    const oauthBaseUrl = new URL(`${publicUrl}/oauth`);
+    const accountPaths = resolveCatalogPaths(options.catalogRoot);
+    const provider = new OAuthServer({
+        issuerUrl,
+        authorizationUrl: new URL(`${publicUrl}/oauth/consent`),
+        resourceServerUrl,
+        scopesSupported: ['mcp:tools'],
+        clientIdMetadataDocuments: { fetch: sanitizingMetadataFetch(fetch) },
+        model: createFileOAuthServerModel(path.join(options.catalogRoot, 'oauth')),
+    });
+    const oauthMetadata = createOAuthMetadata({ provider, baseUrl: oauthBaseUrl });
+    const protectedResourceMetadata = {
+        resource: resourceServerUrl.href,
+        authorization_servers: [issuerUrl.href],
+        scopes_supported: ['mcp:tools'],
+        bearer_methods_supported: ['header'],
+    };
+    const protectedResourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceServerUrl);
+    // Behind the tunnel the peer is the tunnel itself, so X-Forwarded-For is
+    // always set; express-rate-limit v8 refuses to run with it while
+    // `trust proxy` is false. Key the limiters on the socket address instead.
+    const rateLimitValidate = { xForwardedForHeader: false, forwardedHeader: false };
+    const app = express();
+    app.disable('x-powered-by');
+    // The issuer carries no path, so the canonical RFC 8414/RFC 9728 locations
+    // are the bare well-known paths; the lib's router serves the same documents
+    // at the /oauth-suffixed variants. These routes shadow nothing the lib needs.
+    const serveMetadata = (document) => (_request, response) => {
+        response.setHeader('Cache-Control', 'no-store');
+        response.status(200).json(document);
+    };
+    app.get('/.well-known/oauth-authorization-server', serveMetadata(oauthMetadata));
+    app.get('/.well-known/oauth-protected-resource', serveMetadata(protectedResourceMetadata));
+    app.get('/.well-known/oauth-protected-resource/mcp', serveMetadata(protectedResourceMetadata));
+    // DCR runs through the library's router, whose own express.json() would
+    // re-parse (and reject) an already-consumed stream; parsing here first
+    // leaves the sanitized body in place for it.
+    app.use('/oauth/register', express.json(), sanitizeRegisterBody);
+    app.use(mcpAuthRouter({
+        provider,
+        baseUrl: oauthBaseUrl,
+        resourceServerUrl,
+        authorizationOptions: { rateLimit: { validate: rateLimitValidate } },
+        tokenOptions: { rateLimit: { validate: rateLimitValidate } },
+        clientRegistrationOptions: { rateLimit: { validate: rateLimitValidate } },
+        revocationOptions: { rateLimit: { validate: rateLimitValidate } },
+    }));
+    app.get('/oauth/consent', async (request, response) => {
+        response.setHeader('Cache-Control', 'no-store');
+        const clientId = typeof request.query.client_id === 'string' ? request.query.client_id : '';
+        const client = clientId ? await provider.getClient(clientId).catch(() => undefined) : undefined;
+        if (!client) {
+            response.status(400).json({ error: 'invalid_request', error_description: 'Unknown client_id.' });
+            return;
+        }
+        response.status(200).type('html').send(renderConsentPage(request.query, client.client_name ?? client.client_id));
+    });
+    // authenticateHandler returns an Express Router: it must be mounted with
+    // app.use so the mount path is stripped before the router matches its
+    // internal POST / route (app.post(path, router) leaves req.url intact and
+    // the router 404s).
+    app.use('/oauth/confirm', authenticateHandler({
+        provider,
+        rateLimit: { windowMs: 15 * 60 * 1000, max: 20, validate: rateLimitValidate },
+        getUser: async (request) => {
+            const username = typeof request.body?.username === 'string' ? request.body.username : '';
+            const password = typeof request.body?.password === 'string' ? request.body.password : '';
+            if (!username || !password)
+                return null;
+            const valid = await verifyAccountPassword(accountPaths, username, password);
+            return valid ? username : null;
+        },
+    }));
+    app.post('/oauth/deny', express.urlencoded({ extended: false }), async (request, response) => {
+        response.setHeader('Cache-Control', 'no-store');
+        const body = (request.body ?? {});
+        const clientId = typeof body.client_id === 'string' ? body.client_id : '';
+        const redirectUri = typeof body.redirect_uri === 'string' ? body.redirect_uri : '';
+        const state = typeof body.state === 'string' ? body.state : undefined;
+        const client = clientId ? await provider.getClient(clientId).catch(() => undefined) : undefined;
+        const redirectRegistered = client !== undefined && redirectUri !== '' && client.redirect_uris.some((registered) => redirectUriMatches(redirectUri, registered));
+        if (!client || !redirectRegistered) {
+            response.status(400).json({ error: 'invalid_request', error_description: 'Unknown client_id or unregistered redirect_uri.' });
+            return;
+        }
+        const target = new URL(redirectUri);
+        target.searchParams.set('error', 'access_denied');
+        if (state)
+            target.searchParams.set('state', state);
+        target.searchParams.set('iss', issuerUrl.href);
+        response.redirect(302, target.toString());
+    });
+    const verifyAccessToken = async (token) => {
+        try {
+            const authInfo = await provider.verifyAccessToken(token);
+            return { userId: authInfo.userId };
+        }
+        catch {
+            // Unknown, expired, or revoked tokens all fail closed to null.
+            return null;
+        }
+    };
+    return { app, verifyAccessToken, protectedResourceMetadataUrl };
+}
+/** The authorize request parameters the consent form must echo back. */
+const CONSENT_PARAMETERS = ['client_id', 'redirect_uri', 'response_type', 'code_challenge', 'code_challenge_method', 'state', 'scope', 'resource'];
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function renderConsentPage(query, clientName) {
+    const hiddenInputs = CONSENT_PARAMETERS
+        .filter((name) => typeof query[name] === 'string' && query[name] !== '')
+        .map((name) => `      <input type="hidden" name="${name}" value="${escapeHtml(query[name])}">`)
+        .join('\n');
+    const redirectUri = typeof query.redirect_uri === 'string' ? query.redirect_uri : '';
+    let redirectHost = redirectUri;
+    try {
+        redirectHost = new URL(redirectUri).host;
+    }
+    catch {
+        // Display the raw value when it does not parse; the confirm step rejects it.
+    }
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Catence — authorize ${escapeHtml(clientName)}</title>
+  </head>
+  <body>
+    <h1>Authorize ${escapeHtml(clientName)}</h1>
+    <p><strong>${escapeHtml(clientName)}</strong> is asking to access your Catence data${redirectHost ? ` (redirecting to ${escapeHtml(redirectHost)})` : ''}.</p>
+    <form method="post">
+${hiddenInputs}
+      <p><label>Username <input type="text" name="username" autocomplete="username" required></label></p>
+      <p><label>Password <input type="password" name="password" autocomplete="current-password" required></label></p>
+      <p>
+        <button type="submit" formaction="/oauth/confirm">Approve</button>
+        <button type="submit" formaction="/oauth/deny">Deny</button>
+      </p>
+    </form>
+  </body>
+</html>
+`;
+}
+//# sourceMappingURL=oauth.js.map

package/dist/interfaces/http/server.d.ts

@@ -1,11 +1,63 @@
 import { type Server } from 'node:http';
-import { type DetachedSyncSpawner, mergeOpenCodeGoConsoleProfiles, startDetachedSync, type CatalogPaths, type CatencePaths } from '../../runtime/index.js';
+import { type DetachedSyncSpawner, mergeOpenCodeGoConsoleProfiles, startDetachedSync, type CatalogPaths, type CatencePaths, type ConsoleAccountRole } from '../../runtime/index.js';
 export type CatenceHttpServerOptions = {
     /** A shared catalog for public servers. All data APIs then require athleteId. */
     catalogPaths?: CatalogPaths;
     /** Internal compatibility hook for tests and embedded single-store callers. */
     paths?: CatencePaths;
     allowedOrigins?: readonly string[];
+    /**
+     * Static bearer token for the gate (tests and embedded single-store callers).
+     * Mutually exclusive with bearerTokenFile.
+     */
+    bearerToken?: string;
+    /**
+     * Token file whose presence switches the gate on: every request except the
+     * health endpoints and CORS preflights must present
+     * `Authorization: Bearer <token>`. The file is re-read on mtime change, so
+     * `catence-data mcp enable|disable` (and the /api/v1/mcp-exposure route)
+     * take effect without a restart. The MCP server has no other
+     * authentication; this gates it (and the JSON APIs) for non-loopback
+     * exposure such as a Cloudflare Tunnel to an MCP client.
+     */
+    bearerTokenFile?: string;
+    /**
+     * Per-account MCP key registry for the gate. Any active key in it arms
+     * authentication and resolves to that account's athlete scope; keys are
+     * managed with `catence-data mcp key` and the /api/v1/mcp-keys routes.
+     */
+    mcpKeysFile?: string;
+    /**
+     * OAuth bearer-token verifier (Task B plugs in the MCP OAuth server). Its
+     * presence arms the gate when oauthEnabled() is unset or true; verified
+     * usernames resolve through the same Console accounts as MCP keys.
+     */
+    oauthVerifier?: (token: string) => Promise<{
+        username: string;
+    } | null>;
+    /**
+     * Live check whether the OAuth 2.1 server is effectively enabled. Wired by
+     * the server itself when OAuth is configurable (the `oauth` startup option
+     * or an oauthSettingsFile); its truth arms the gate together with the
+     * oauthVerifier.
+     */
+    oauthEnabled?: () => boolean;
+    /**
+     * Run the OAuth 2.1 authorization server (issuer = publicUrl) for
+     * ChatGPT/Codex-style clients. The Express sub-app is built lazily on first
+     * effective use and serves /.well-known/oauth-* and /oauth/* ahead of the
+     * gate; its verifyAccessToken is wired in as the oauthVerifier. The
+     * oauthSettingsFile overrides this at runtime.
+     */
+    oauth?: {
+        publicUrl: string;
+    };
+    /**
+     * Console-managed OAuth settings file for the gate and the
+     * /api/v1/mcp-oauth-settings routes. A valid file overrides the `oauth`
+     * startup option at runtime; a malformed one fails closed to disabled.
+     */
+    oauthSettingsFile?: string;
     /** Internal compatibility hook for tests: override the detached sync spawner. */
     startSync?: typeof startDetachedSync;
     /** Internal compatibility hook for tests: passed into the default startDetachedSync. */
@@ -13,6 +65,13 @@ export type CatenceHttpServerOptions = {
     /** Internal compatibility hook for tests: override OpenCode Go model discovery. */
     mergeModels?: typeof mergeOpenCodeGoConsoleProfiles;
 };
+/** The authenticated identity behind one request and the athletes it may touch. */
+export type CatencePrincipal = {
+    kind: 'admin-token' | 'key' | 'oauth';
+    username?: string;
+    role: ConsoleAccountRole;
+    athleteIds: string[] | 'all';
+};
 /**
  * Create Catence's local Streamable HTTP server.
  *