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

package/dist/interfaces/http/server.js

@@ -1,10 +1,105 @@
+import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { catenceRuntimeHealth, DashboardSnapshotService, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, } from '../../runtime/index.js';
-import { createCatenceMcpServer } from '../mcp/server.js';
+import { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/sdk/types.js';
+import { addAthlete, addMcpKey, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, catenceRuntimeHealth, countActiveMcpKeys, DashboardSnapshotService, deleteAthleteSecret, describeAthleteSecrets, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, filterRosterToScope, jsonSafe, listAthleteFileRevisions, listMcpKeys, loadCatalog, McpKeyNotFoundError, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, parseAutoSyncInterval, readAutoSyncSchedule, readAthleteFile, readAthleteFileRevision, readMcpOauthSettings, resolveAccountScope, resolveAthlete, resolveCatalogPaths, resolveKeyPrincipal, revokeMcpKey, rollMcpKey, scopeAllowsAthlete, setAthleteSecret, startDetachedSync, syncProgress, updateAthleteFile, updateAutoSyncSchedule, writeMcpOauthSettings, } from '../../runtime/index.js';
+import { activeBearerToken, ensureBearerToken, disableBearerToken, mcpExposureStatus } from './cli-options.js';
+import { CATENCE_MCP_SERVER_INFO, createCatenceMcpServer, MCP_INSTRUCTIONS } from '../mcp/server.js';
 import { generationStatus } from './generation-status.js';
 const MAX_REQUEST_BYTES = 1_000_000;
+/** Endpoints that stay open when bearer authentication is enabled: they carry
+ * no personal data and must answer unauthenticated readiness probes. */
+const UNAUTHENTICATED_PATHS = new Set(['/health', '/api/v1/health']);
+/** Thrown when a principal resolves an athlete outside its scope; routes map it to 403 athlete_forbidden. */
+class AthleteForbiddenError extends Error {
+}
+/** Full-access principal: unarmed loopback dev mode and the legacy shared token both mean "local admin". */
+const FULL_ACCESS_PRINCIPAL = { kind: 'admin-token', role: 'admin', athleteIds: 'all' };
+function bearerTokenFrom(request) {
+    const header = request.headers.authorization;
+    if (typeof header !== 'string' || !header.startsWith('Bearer '))
+        return null;
+    return header.slice('Bearer '.length);
+}
+function matchesLegacyToken(rawToken, expected) {
+    const received = Buffer.from(rawToken);
+    const expectedBuffer = Buffer.from(expected);
+    // timingSafeEqual throws on length mismatch, so compare sizes first.
+    return received.length === expectedBuffer.length && timingSafeEqual(received, expectedBuffer);
+}
+function scopeAllows(principal, athleteId) {
+    return scopeAllowsAthlete(principal.athleteIds, athleteId);
+}
+function requireAdmin(principal, response) {
+    if (principal.role === 'admin')
+        return true;
+    json(response, 403, { error: { code: 'admin_required', message: 'An admin account is required for this action.' } });
+    return false;
+}
+/**
+ * True when the principal may manage API keys bound to `account`: admins manage
+ * every account's keys; a key or OAuth principal manages only its own
+ * account's keys (self-service from the Console's account settings).
+ */
+function canManageKeysFor(principal, account) {
+    return principal.role === 'admin' || principal.username === account;
+}
+function requireKeyManagementFor(principal, account, response) {
+    if (canManageKeysFor(principal, account))
+        return true;
+    json(response, 403, { error: { code: 'admin_required', message: 'An admin account is required to manage API keys for another account.' } });
+    return false;
+}
+/**
+ * Resolve the request's principal: the legacy shared token first, then a
+ * per-account MCP key, then an OAuth bearer token. The gate is armed when the
+ * legacy token is active, the key registry holds at least one active key, or
+ * the OAuth 2.1 server is effectively enabled; an unarmed server stays open
+ * for loopback dev. Resolution fails closed: a malformed registry or accounts
+ * store, a revoked key, or an unknown account never yields a principal.
+ */
+async function resolvePrincipal(request, options, accountPaths) {
+    const legacyToken = options.bearerToken !== undefined ? options.bearerToken : options.bearerTokenFile !== undefined ? activeBearerToken(options.bearerTokenFile) : undefined;
+    const keysArmed = options.mcpKeysFile !== undefined && countActiveMcpKeys(options.mcpKeysFile) > 0;
+    const oauthArmed = options.oauthVerifier !== undefined && (options.oauthEnabled === undefined || options.oauthEnabled());
+    const armed = (legacyToken !== undefined && legacyToken !== null) || keysArmed || oauthArmed;
+    if (!armed)
+        return FULL_ACCESS_PRINCIPAL;
+    const rawToken = bearerTokenFrom(request);
+    if (rawToken === null)
+        return null;
+    if (typeof legacyToken === 'string' && matchesLegacyToken(rawToken, legacyToken))
+        return FULL_ACCESS_PRINCIPAL;
+    if (options.mcpKeysFile !== undefined) {
+        // A malformed accounts store fails closed: the key resolves to no principal.
+        const keyPrincipal = resolveKeyPrincipal(options.mcpKeysFile, rawToken, (username) => {
+            try {
+                return resolveAccountScope(accountPaths, username);
+            }
+            catch {
+                return null;
+            }
+        });
+        if (keyPrincipal)
+            return { kind: 'key', username: keyPrincipal.account, role: keyPrincipal.role, athleteIds: keyPrincipal.athleteIds };
+    }
+    if (options.oauthVerifier !== undefined) {
+        const verified = await options.oauthVerifier(rawToken).catch(() => null);
+        if (verified) {
+            let scope = null;
+            try {
+                scope = resolveAccountScope(accountPaths, verified.username);
+            }
+            catch {
+                scope = null;
+            }
+            if (scope)
+                return { kind: 'oauth', username: verified.username, role: scope.role, athleteIds: scope.athleteIds };
+        }
+    }
+    return null;
+}
 function json(response, statusCode, value) {
     const body = JSON.stringify(jsonSafe(value));
     response.writeHead(statusCode, { 'content-type': 'application/json; charset=utf-8' });
@@ -18,8 +113,8 @@ function addCorsHeaders(request, response, allowedOrigins) {
         return false;
     response.setHeader('access-control-allow-origin', origin);
     response.setHeader('vary', 'Origin');
-    response.setHeader('access-control-allow-methods', 'GET, POST, DELETE, OPTIONS');
-    response.setHeader('access-control-allow-headers', 'content-type, mcp-session-id');
+    response.setHeader('access-control-allow-methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    response.setHeader('access-control-allow-headers', 'content-type, if-match, mcp-session-id');
     return true;
 }
 async function readJsonBody(request) {
@@ -76,17 +171,88 @@ async function dashboardSnapshot(paths, url) {
         await repository.close();
     }
 }
-async function dashboardPaths(catalogPaths, staticPaths, url) {
+function parseMcpKeyCreateBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['account', 'label'].includes(key))
+            throw new Error(`Unknown MCP key field: ${key}.`);
+    }
+    if (typeof raw.account !== 'string' || !raw.account.trim())
+        throw new Error('account is required.');
+    if (raw.label !== undefined && (typeof raw.label !== 'string' || raw.label.trim().length > 120)) {
+        throw new Error('label must be a string of at most 120 characters.');
+    }
+    return { account: raw.account.trim(), label: raw.label };
+}
+function parseMcpKeyRollBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (key !== 'id')
+            throw new Error(`Unknown MCP key field: ${key}.`);
+    }
+    if (typeof raw.id !== 'string' || !raw.id.trim())
+        throw new Error('id is required.');
+    return { id: raw.id.trim() };
+}
+function parseMcpOauthSettingsBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['enabled', 'publicUrl'].includes(key))
+            throw new Error(`Unknown OAuth settings field: ${key}.`);
+    }
+    if (typeof raw.enabled !== 'boolean')
+        throw new Error('enabled is required and must be a boolean.');
+    if (raw.publicUrl !== undefined && typeof raw.publicUrl !== 'string')
+        throw new Error('publicUrl must be a string.');
+    return { enabled: raw.enabled, publicUrl: raw.publicUrl };
+}
+async function dashboardPaths(catalogPaths, staticPaths, url, principal) {
     if (catalogPaths) {
         const athleteId = url.searchParams.get('athleteId');
         if (!athleteId)
             throw new Error('athleteId is required. Call /api/v1/athletes to inspect the configured catalog.');
+        if (!scopeAllows(principal, athleteId))
+            throw new AthleteForbiddenError(`This credential is not allowed to access athlete ${athleteId}.`);
         return (await resolveAthlete(catalogPaths, athleteId)).paths;
     }
     if (staticPaths)
         return staticPaths;
     throw new Error('No Catence data store is configured.');
 }
+function parseSyncScheduleBody(body) {
+    if (body === undefined)
+        return {};
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['athleteId', 'enabled', 'intervalMinutes'].includes(key)) {
+            throw new Error(`Unknown auto-sync field: ${key}.`);
+        }
+    }
+    if (raw.athleteId !== undefined && typeof raw.athleteId !== 'string')
+        throw new Error('athleteId must be a string.');
+    if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean')
+        throw new Error('enabled must be a boolean.');
+    if (raw.intervalMinutes !== undefined) {
+        if (typeof raw.intervalMinutes === 'string') {
+            raw.intervalMinutes = parseAutoSyncInterval(raw.intervalMinutes);
+        }
+        else if (typeof raw.intervalMinutes !== 'number') {
+            throw new Error('intervalMinutes must be a number or a label like 15m, 2h, 24h.');
+        }
+    }
+    if (raw.enabled === undefined && raw.intervalMinutes === undefined) {
+        throw new Error('Provide enabled, intervalMinutes, or both.');
+    }
+    return raw;
+}
 function parseSyncBody(body) {
     if (body === undefined)
         return {};
@@ -94,7 +260,7 @@ function parseSyncBody(body) {
         throw new Error('Request body must be a JSON object.');
     const raw = body;
     for (const key of Object.keys(raw)) {
-        if (!['athleteId', 'provider', 'from', 'refresh', 'refreshModels'].includes(key)) {
+        if (!['athleteId', 'provider', 'from', 'refresh', 'refreshModels', 'backfill'].includes(key)) {
             throw new Error(`Unknown sync field: ${key}.`);
         }
     }
@@ -106,16 +272,100 @@ function parseSyncBody(body) {
     if (raw.from !== undefined && (typeof raw.from !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw.from))) {
         throw new Error('from must use YYYY-MM-DD.');
     }
-    for (const flag of ['refresh', 'refreshModels']) {
+    for (const flag of ['refresh', 'refreshModels', 'backfill']) {
         if (raw[flag] !== undefined && typeof raw[flag] !== 'boolean')
             throw new Error(`${flag} must be a boolean.`);
     }
+    // A backfill extends history backwards from an explicit date; the CLI's
+    // backfill subcommand requires --from, so the API does the same.
+    if (raw.backfill === true && raw.from === undefined) {
+        throw new Error('from is required for a backfill.');
+    }
     return raw;
 }
-async function resolveSyncPaths(catalogPaths, staticPaths, body) {
+function parseAthleteCreateBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['id', 'label', 'setDefault'].includes(key))
+            throw new Error(`Unknown athlete field: ${key}.`);
+    }
+    if (typeof raw.id !== 'string' || !raw.id.trim())
+        throw new Error('id is required.');
+    if (typeof raw.label !== 'string' || !raw.label.trim())
+        throw new Error('label is required.');
+    if (raw.setDefault !== undefined && typeof raw.setDefault !== 'boolean')
+        throw new Error('setDefault must be a boolean.');
+    return { id: raw.id.trim(), label: raw.label.trim(), setDefault: raw.setDefault === true };
+}
+function parseAthleteFileBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['operation', 'section', 'content', 'expectedHash'].includes(key))
+            throw new Error(`Unknown athlete-file field: ${key}.`);
+    }
+    if (typeof raw.content !== 'string')
+        throw new Error('content must be a string.');
+    const operation = raw.operation ?? 'replace';
+    if (operation !== 'replace' && operation !== 'append' && operation !== 'replace_section') {
+        throw new Error('operation must be replace, append, or replace_section.');
+    }
+    if (raw.section !== undefined && typeof raw.section !== 'string')
+        throw new Error('section must be a string.');
+    if (raw.expectedHash !== undefined && raw.expectedHash !== null && typeof raw.expectedHash !== 'string') {
+        throw new Error('expectedHash must be a string or null.');
+    }
+    return {
+        operation,
+        section: raw.section,
+        content: raw.content,
+        hasExpectedHash: Object.prototype.hasOwnProperty.call(raw, 'expectedHash'),
+        expectedHash: (raw.expectedHash ?? null),
+    };
+}
+function parseAthleteSecretBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['athleteId', 'provider', 'field', 'value'].includes(key))
+            throw new Error(`Unknown athlete-secret field: ${key}.`);
+    }
+    if (raw.athleteId !== undefined && typeof raw.athleteId !== 'string')
+        throw new Error('athleteId must be a string.');
+    if (typeof raw.provider !== 'string' || !raw.provider.trim())
+        throw new Error('provider is required.');
+    if (typeof raw.field !== 'string' || !raw.field.trim())
+        throw new Error('field is required.');
+    if (typeof raw.value !== 'string' || !raw.value.trim())
+        throw new Error('value is required.');
+    return { athleteId: raw.athleteId, provider: raw.provider.trim(), field: raw.field.trim(), value: raw.value };
+}
+function parseAthleteSecretRemovalBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['athleteId', 'provider', 'field'].includes(key))
+            throw new Error(`Unknown athlete-secret field: ${key}.`);
+    }
+    if (raw.athleteId !== undefined && typeof raw.athleteId !== 'string')
+        throw new Error('athleteId must be a string.');
+    if (typeof raw.provider !== 'string' || !raw.provider.trim())
+        throw new Error('provider is required.');
+    if (typeof raw.field !== 'string' || !raw.field.trim())
+        throw new Error('field is required.');
+    return { athleteId: raw.athleteId, provider: raw.provider.trim(), field: raw.field.trim() };
+}
+async function resolveSyncPaths(catalogPaths, staticPaths, body, principal) {
     if (catalogPaths) {
         if (!body.athleteId)
             throw new Error('athleteId is required. Call /api/v1/athletes to inspect the configured catalog.');
+        if (!scopeAllows(principal, body.athleteId))
+            throw new AthleteForbiddenError(`This credential is not allowed to access athlete ${body.athleteId}.`);
         return (await resolveAthlete(catalogPaths, body.athleteId)).paths;
     }
     if (staticPaths)
@@ -165,11 +415,46 @@ async function lastSyncSummary(paths) {
         return null;
     }
 }
-async function handleMcpRequest(request, response, paths) {
+/**
+ * The MCP revision ChatGPT's hosted connector speaks during setup. The bundled
+ * SDK predates it, but the request shapes the revision uses — server/discover,
+ * then stateless tools/list and tools/call without initialize — are already
+ * handled. Only the protocol header value is rejected, so it is bridged down
+ * and server/discover is answered from the same descriptor initialize reports.
+ */
+const MODERN_MCP_PROTOCOL_VERSION = '2026-07-28';
+/** A single JSON-RPC request (batches are left to the transport). */
+function singleJsonRpcRequest(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return null;
+    const method = body.method;
+    return typeof method === 'string' ? body : null;
+}
+/**
+ * Server capabilities exactly as the SDK's initialize response reports them.
+ * getCapabilities() is the runtime accessor that builds that response; the
+ * typings mark it private.
+ */
+function mcpServerCapabilities(server) {
+    return server.server.getCapabilities();
+}
+async function handleMcpRequest(request, response, paths, principal) {
     if (request.method !== 'POST') {
         methodNotAllowed(response);
         return;
     }
+    // ChatGPT's discovery probe and the requests that follow it carry the
+    // 2026-07-28 revision; the transport understands only the older list. The
+    // Node adapter rebuilds the web-standard headers from rawHeaders (not the
+    // parsed headers object), so both views are rewritten.
+    if (request.headers['mcp-protocol-version'] === MODERN_MCP_PROTOCOL_VERSION) {
+        request.headers['mcp-protocol-version'] = LATEST_PROTOCOL_VERSION;
+        const rawHeaders = request.rawHeaders;
+        for (let index = 0; index < rawHeaders.length; index += 2) {
+            if (rawHeaders[index]?.toLowerCase() === 'mcp-protocol-version')
+                rawHeaders[index + 1] = LATEST_PROTOCOL_VERSION;
+        }
+    }
     let body;
     try {
         body = await readJsonBody(request);
@@ -182,7 +467,34 @@ async function handleMcpRequest(request, response, paths) {
         });
         return;
     }
-    const server = createCatenceMcpServer(paths);
+    const jsonRpc = singleJsonRpcRequest(body);
+    if (jsonRpc?.method === 'server/discover') {
+        // Modern clients probe discovery before anything else; answer from the
+        // same descriptor the initialize response reports so the two never drift.
+        const server = createCatenceMcpServer(paths, {}, { scope: { athleteIds: principal.athleteIds } });
+        try {
+            json(response, 200, {
+                jsonrpc: '2.0',
+                id: jsonRpc.id ?? null,
+                result: {
+                    resultType: 'complete',
+                    supportedVersions: [MODERN_MCP_PROTOCOL_VERSION, ...SUPPORTED_PROTOCOL_VERSIONS],
+                    capabilities: mcpServerCapabilities(server),
+                    _meta: { 'io.modelcontextprotocol/serverInfo': CATENCE_MCP_SERVER_INFO },
+                    instructions: MCP_INSTRUCTIONS,
+                    ttlMs: 3_600_000,
+                    cacheScope: 'public',
+                },
+            });
+        }
+        finally {
+            await server.close();
+        }
+        return;
+    }
+    // The HTTP gate has already authenticated this request; the MCP server
+    // re-enforces the principal's athlete scope on every tool and roster.
+    const server = createCatenceMcpServer(paths, {}, { scope: { athleteIds: principal.athleteIds } });
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
     let cleanedUp = false;
     const cleanup = async () => {
@@ -222,20 +534,120 @@ async function handleMcpRequest(request, response, paths) {
 export function createCatenceHttpServer(options = {}) {
     const catalogPaths = options.catalogPaths ?? (options.paths ? null : resolveCatalogPaths());
     const staticPaths = options.paths ?? null;
+    // Key and OAuth principals resolve their athlete scope through the Console
+    // accounts that live next to the catalog.
+    const accountPaths = catalogPaths ?? resolveCatalogPaths();
     const allowedOrigins = options.allowedOrigins ?? [];
     const startSync = options.startSync ?? startDetachedSync;
     const mergeModels = options.mergeModels ?? mergeOpenCodeGoConsoleProfiles;
+    // OAuth 2.1 is configured by a Console-managed settings file
+    // (--oauth-settings-file / <catalog-home>/oauth/settings.json), which
+    // overrides the startup `oauth` option (env/flags) at runtime; a malformed
+    // file fails closed to disabled. The Express sub-app (express,
+    // mcp-oauth-server) builds lazily on first effective use, keyed by the
+    // public URL (the issuer), so the stdio path and a never-enabled serve never
+    // import express. Its verifier is wired into the gate as oauthVerifier;
+    // resolvePrincipal then maps the verified username to the live account scope.
+    const oauthSettingsFile = options.oauthSettingsFile;
+    const bootstrapOauth = options.oauth !== undefined ? { publicUrl: options.oauth.publicUrl.replace(/\/+$/, '') } : null;
+    const oauthConfigurable = options.oauth !== undefined || oauthSettingsFile !== undefined;
+    const effectiveOauth = () => {
+        if (oauthSettingsFile !== undefined) {
+            const { state, settings } = readMcpOauthSettings(oauthSettingsFile);
+            if (state === 'ok' && settings !== null) {
+                return { enabled: settings.enabled, ...(settings.publicUrl ? { publicUrl: settings.publicUrl } : {}), source: 'console', settingsState: state };
+            }
+            if (state === 'invalid')
+                return { enabled: false, source: 'disabled', settingsState: state };
+        }
+        if (bootstrapOauth !== null)
+            return { enabled: true, publicUrl: bootstrapOauth.publicUrl, source: 'environment', settingsState: 'missing' };
+        return { enabled: false, source: 'disabled', settingsState: 'missing' };
+    };
+    let oauthApp = null;
+    const getOauthApp = (publicUrl) => {
+        if (oauthApp === null || oauthApp.publicUrl !== publicUrl) {
+            const ready = import('./oauth.js').then(({ createOAuthApp }) => createOAuthApp({ catalogRoot: accountPaths.root, publicUrl }));
+            // Surface a build failure per request (the outer catch answers 500); this
+            // no-op branch only marks the rejection handled when no request ever comes.
+            void ready.catch(() => { });
+            oauthApp = { publicUrl, ready };
+        }
+        return oauthApp.ready;
+    };
+    let effectiveOptions = options;
+    if (oauthConfigurable) {
+        const verifier = async (token) => {
+            const config = effectiveOauth();
+            if (!config.enabled || config.publicUrl === undefined)
+                return null;
+            const verified = await (await getOauthApp(config.publicUrl)).verifyAccessToken(token);
+            if (!verified?.userId)
+                return null;
+            return { username: verified.userId };
+        };
+        effectiveOptions = { ...options, oauthVerifier: verifier, oauthEnabled: () => effectiveOauth().enabled };
+    }
+    // The status shape mcpExposureStatus reports; present whenever OAuth is
+    // configurable so the Console can read and change it.
+    const oauthStatus = () => {
+        if (!oauthConfigurable)
+            return undefined;
+        const config = effectiveOauth();
+        return { enabled: config.enabled, ...(config.publicUrl ? { publicUrl: config.publicUrl } : {}) };
+    };
     return createServer((request, response) => {
         void (async () => {
+            const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
+            // The OAuth endpoints are the auth surface itself: they bypass the gate
+            // and CORS entirely and are delegated to the Express sub-app. When OAuth
+            // is effectively disabled they answer 404 — no metadata is advertised.
+            if (pathname.startsWith('/.well-known/oauth-') || pathname.startsWith('/oauth/')) {
+                const config = effectiveOauth();
+                if (config.enabled && config.publicUrl !== undefined) {
+                    const handle = await getOauthApp(config.publicUrl);
+                    handle.app(request, response);
+                    return;
+                }
+                json(response, 404, { error: { code: 'not_found', message: 'No Catence endpoint matches this request.' } });
+                return;
+            }
             if (!addCorsHeaders(request, response, allowedOrigins)) {
                 json(response, 403, { error: { code: 'origin_not_allowed', message: 'This browser origin is not allowed to access Catence.' } });
                 return;
             }
-            const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
             if (request.method === 'OPTIONS') {
                 response.writeHead(204).end();
                 return;
             }
+            // Health probes stay open even when the gate is armed; they resolve no
+            // principal because nothing downstream consumes one.
+            const principal = UNAUTHENTICATED_PATHS.has(pathname)
+                ? FULL_ACCESS_PRINCIPAL
+                : await resolvePrincipal(request, effectiveOptions, accountPaths);
+            if (principal === null) {
+                // A presented-but-rejected token is a bearer problem, not an OAuth
+                // discovery problem: answer RFC 6750 invalid_token without
+                // resource_metadata, so static-key clients get a clear "your token is
+                // wrong" instead of being steered into the OAuth flow. With no token,
+                // RFC 9728 points OAuth clients at the protected-resource metadata so
+                // they discover the authorization server; without OAuth the 401 stays
+                // plain on purpose: MCP connector auto-detection treats it as a
+                // bearer gate rather than an OAuth server.
+                if (bearerTokenFrom(request) !== null) {
+                    response.setHeader('www-authenticate', 'Bearer error="invalid_token", error_description="The access token is invalid or expired."');
+                }
+                else {
+                    const config = effectiveOauth();
+                    if (config.enabled && config.publicUrl !== undefined) {
+                        const handle = await getOauthApp(config.publicUrl).catch(() => null);
+                        if (handle !== null)
+                            response.setHeader('www-authenticate', `Bearer resource_metadata="${handle.protectedResourceMetadataUrl}"`);
+                    }
+                }
+                json(response, 401, { error: { code: 'unauthorized', message: 'A valid Authorization: Bearer token is required.' } });
+                return;
+            }
             if (pathname === '/health' && request.method === 'GET') {
                 json(response, 200, catenceRuntimeHealth());
                 return;
@@ -251,28 +663,195 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 try {
                     const catalog = await loadCatalog(catalogPaths);
-                    json(response, 200, { defaultAthleteId: catalog.defaultAthleteId, athletes: catalog.athletes });
+                    // The roster is narrowed to the principal's athlete scope.
+                    const roster = filterRosterToScope(catalog.athletes, catalog.defaultAthleteId, principal.athleteIds);
+                    json(response, 200, { defaultAthleteId: roster.defaultAthleteId, athletes: roster.athletes });
                 }
                 catch (error) {
                     json(response, 400, { error: { code: 'catalog_unavailable', message: error instanceof Error ? error.message : String(error) } });
                 }
                 return;
             }
+            if (pathname === '/api/v1/athletes' && request.method === 'POST') {
+                if (!requireAdmin(principal, response))
+                    return;
+                if (!catalogPaths) {
+                    json(response, 400, {
+                        error: {
+                            code: 'catalog_required',
+                            message: 'Adding athletes requires a Catence catalog; this server uses a single legacy data store.',
+                        },
+                    });
+                    return;
+                }
+                try {
+                    const body = parseAthleteCreateBody(await readJsonBody(request));
+                    const catalog = await loadCatalog(catalogPaths);
+                    if (catalog.athletes.some((athlete) => athlete.id === body.id)) {
+                        json(response, 409, { error: { code: 'athlete_exists', message: `Athlete ${body.id} already exists.` } });
+                        return;
+                    }
+                    const updated = await addAthlete(catalogPaths, body);
+                    json(response, 201, { defaultAthleteId: updated.defaultAthleteId, athletes: updated.athletes });
+                }
+                catch (error) {
+                    json(response, 400, {
+                        error: { code: 'athlete_create_failed', message: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+                return;
+            }
             if (pathname === '/api/v1/dashboard' && request.method === 'GET') {
                 try {
                     const url = new URL(request.url ?? '/', 'http://localhost');
-                    json(response, 200, await dashboardSnapshot(await dashboardPaths(catalogPaths, staticPaths, url), url));
+                    json(response, 200, await dashboardSnapshot(await dashboardPaths(catalogPaths, staticPaths, url, principal), url));
                 }
                 catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
                     json(response, 400, { error: { code: 'dashboard_unavailable', message: error instanceof Error ? error.message : String(error) } });
                 }
                 return;
             }
+            if (pathname === '/api/v1/athlete-file' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
+                    const revisionId = url.searchParams.get('revision');
+                    if (revisionId) {
+                        let content;
+                        try {
+                            content = await readAthleteFileRevision(paths, revisionId);
+                        }
+                        catch (error) {
+                            if (!(error instanceof AthleteFileValidationError))
+                                throw error;
+                            content = null;
+                        }
+                        if (content === null) {
+                            json(response, 404, { error: { code: 'athlete_file_revision_not_found', message: 'No athlete-file revision matches this identifier.' } });
+                            return;
+                        }
+                        json(response, 200, { revisionId, content });
+                        return;
+                    }
+                    const snapshot = await readAthleteFile(paths);
+                    json(response, 200, { ...snapshot, revisions: await listAthleteFileRevisions(paths) });
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    json(response, 400, { error: { code: 'athlete_file_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/athlete-file' && request.method === 'PUT') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
+                    const parsed = parseAthleteFileBody(await readJsonBody(request));
+                    const header = request.headers['if-match'];
+                    const headerHash = typeof header === 'string' && header.trim() ? header.trim() : undefined;
+                    if (!headerHash && !parsed.hasExpectedHash) {
+                        throw new AthleteFileValidationError('expectedHash is required: send the If-Match header or the expectedHash body field (null to create the file).');
+                    }
+                    const snapshot = await updateAthleteFile(paths, {
+                        operation: parsed.operation,
+                        section: parsed.section,
+                        content: parsed.content,
+                        expectedHash: headerHash ?? parsed.expectedHash,
+                    });
+                    json(response, 200, snapshot);
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    if (error instanceof AthleteFileConflictError) {
+                        json(response, 409, {
+                            error: {
+                                code: 'athlete_file_conflict',
+                                message: error.message,
+                                currentHash: error.currentHash,
+                                currentContent: error.currentContent,
+                            },
+                        });
+                    }
+                    else if (error instanceof AthleteFileTooLargeError || error instanceof AthleteFileValidationError) {
+                        json(response, 400, { error: { code: 'invalid_request', message: error.message } });
+                    }
+                    else {
+                        json(response, 400, { error: { code: 'athlete_file_write_failed', message: error instanceof Error ? error.message : String(error) } });
+                    }
+                }
+                return;
+            }
+            if (pathname === '/api/v1/athlete-secrets' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
+                    json(response, 200, { athleteId: url.searchParams.get('athleteId') ?? 'local', providers: await describeAthleteSecrets(paths) });
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    json(response, 400, { error: { code: 'athlete_secrets_unavailable', message } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/athlete-secrets' && request.method === 'PUT') {
+                try {
+                    const parsed = parseAthleteSecretBody(await readJsonBody(request));
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    if (!url.searchParams.get('athleteId') && parsed.athleteId)
+                        url.searchParams.set('athleteId', parsed.athleteId);
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
+                    await setAthleteSecret(paths, parsed.provider, parsed.field, parsed.value);
+                    json(response, 200, { athleteId: url.searchParams.get('athleteId') ?? 'local', providers: await describeAthleteSecrets(paths) });
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    json(response, 400, { error: { code: 'athlete_secret_write_failed', message } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/athlete-secrets/remove' && request.method === 'POST') {
+                try {
+                    const parsed = parseAthleteSecretRemovalBody(await readJsonBody(request));
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    if (!url.searchParams.get('athleteId') && parsed.athleteId)
+                        url.searchParams.set('athleteId', parsed.athleteId);
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
+                    await deleteAthleteSecret(paths, parsed.provider, parsed.field);
+                    json(response, 200, { athleteId: url.searchParams.get('athleteId') ?? 'local', providers: await describeAthleteSecrets(paths) });
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    json(response, 400, { error: { code: 'athlete_secret_remove_failed', message } });
+                }
+                return;
+            }
             if (pathname === '/api/v1/sync' && request.method === 'POST') {
                 let body;
                 try {
                     body = parseSyncBody(await readJsonBody(request));
-                    const paths = await resolveSyncPaths(catalogPaths, staticPaths, body);
+                    const paths = await resolveSyncPaths(catalogPaths, staticPaths, body, principal);
                     // Optional model self-discovery runs before the data sync so new
                     // OpenCode Go models appear without a manual script run. Failure is
                     // non-fatal: it must never block or fail a data sync. The Console
@@ -294,6 +873,7 @@ export function createCatenceHttpServer(options = {}) {
                         provider: body.provider,
                         from: body.from,
                         refresh: body.refresh,
+                        backfill: body.backfill,
                         // The child resolves the athlete within the catalog, not within
                         // the athlete store this route resolved for locks and logs.
                         cliHome: catalogPaths ? catalogPaths.root : undefined,
@@ -301,6 +881,10 @@ export function createCatenceHttpServer(options = {}) {
                     json(response, 202, { ...handle, ...(discoveryWarning ? { warning: discoveryWarning } : {}), progressEndpoint: '/api/v1/sync/status' });
                 }
                 catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
                     json(response, error instanceof DetachedSyncBusyError ? 409 : 400, {
                         error: {
                             code: error instanceof DetachedSyncBusyError ? 'sync_in_progress' : 'sync_start_failed',
@@ -310,7 +894,45 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/sync/schedule' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
+                    const athleteId = catalogPaths ? (url.searchParams.get('athleteId') ?? '') : 'local';
+                    json(response, 200, await readAutoSyncSchedule(paths, athleteId));
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    json(response, 400, { error: { code: 'schedule_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/sync/schedule' && request.method === 'PUT') {
+                try {
+                    const body = parseSyncScheduleBody(await readJsonBody(request));
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await resolveSyncPaths(catalogPaths, staticPaths, { athleteId: body.athleteId }, principal);
+                    const athleteId = catalogPaths ? (body.athleteId ?? '') : 'local';
+                    json(response, 200, await updateAutoSyncSchedule(paths, athleteId, {
+                        enabled: body.enabled,
+                        ...(body.intervalMinutes === undefined ? {} : { intervalMinutes: parseAutoSyncInterval(String(body.intervalMinutes)) }),
+                    }));
+                }
+                catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
+                    json(response, 400, { error: { code: 'schedule_update_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
             if (pathname === '/api/v1/models/discover' && request.method === 'POST') {
+                if (!requireAdmin(principal, response))
+                    return;
                 // Refresh the OpenCode Go profiles without starting a data sync. The
                 // Console's Models page calls this behind its authenticated proxy.
                 try {
@@ -331,11 +953,15 @@ export function createCatenceHttpServer(options = {}) {
             if (pathname === '/api/v1/sync/status' && request.method === 'GET') {
                 try {
                     const url = new URL(request.url ?? '/', 'http://localhost');
-                    const paths = await dashboardPaths(catalogPaths, staticPaths, url);
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url, principal);
                     const athleteId = catalogPaths ? (await resolveAthlete(catalogPaths, url.searchParams.get('athleteId') ?? '')).athlete.id : 'local';
                     json(response, 200, { athleteId, progress: await syncProgress(paths), lastSync: await lastSyncSummary(paths) });
                 }
                 catch (error) {
+                    if (error instanceof AthleteForbiddenError) {
+                        json(response, 403, { error: { code: 'athlete_forbidden', message: error.message } });
+                        return;
+                    }
                     json(response, 400, { error: { code: 'sync_status_unavailable', message: error instanceof Error ? error.message : String(error) } });
                 }
                 return;
@@ -365,8 +991,176 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/mcp-exposure' && request.method === 'GET') {
+                if (!requireAdmin(principal, response))
+                    return;
+                if (!options.bearerTokenFile) {
+                    json(response, 400, { error: { code: 'exposure_not_configured', message: 'This server was started without a bearer-token file; restart it with --auth-token-file to manage MCP exposure.' } });
+                    return;
+                }
+                json(response, 200, mcpExposureStatus(options.bearerTokenFile, `http://${request.headers.host ?? '127.0.0.1:8787'}`, oauthStatus()));
+                return;
+            }
+            if (pathname === '/api/v1/mcp-exposure' && request.method === 'POST') {
+                if (!requireAdmin(principal, response))
+                    return;
+                if (!options.bearerTokenFile) {
+                    json(response, 400, { error: { code: 'exposure_not_configured', message: 'This server was started without a bearer-token file; restart it with --auth-token-file to manage MCP exposure.' } });
+                    return;
+                }
+                try {
+                    const body = await readJsonBody(request);
+                    if (typeof body !== 'object' || body === null || Array.isArray(body) || !('enabled' in body) || typeof body.enabled !== 'boolean') {
+                        throw new Error('Request body must be a JSON object with a boolean "enabled" field.');
+                    }
+                    if (body.enabled)
+                        ensureBearerToken(options.bearerTokenFile);
+                    else
+                        disableBearerToken(options.bearerTokenFile);
+                    json(response, 200, mcpExposureStatus(options.bearerTokenFile, `http://${request.headers.host ?? '127.0.0.1:8787'}`, oauthStatus()));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'exposure_update_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/mcp-keys' && request.method === 'GET') {
+                if (!options.mcpKeysFile) {
+                    json(response, 400, { error: { code: 'mcp_keys_not_configured', message: 'This server was started without an MCP keys file; restart it with --mcp-keys-file to manage per-account keys.' } });
+                    return;
+                }
+                try {
+                    // Listing never exposes token hashes. Admins see the whole registry;
+                    // a key or OAuth principal sees only its own account's keys.
+                    const keys = await listMcpKeys(options.mcpKeysFile);
+                    json(response, 200, { keys: principal.role === 'admin' ? keys : keys.filter((key) => key.account === principal.username) });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'mcp_keys_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/mcp-keys' && request.method === 'POST') {
+                if (!options.mcpKeysFile) {
+                    json(response, 400, { error: { code: 'mcp_keys_not_configured', message: 'This server was started without an MCP keys file; restart it with --mcp-keys-file to manage per-account keys.' } });
+                    return;
+                }
+                try {
+                    const body = parseMcpKeyCreateBody(await readJsonBody(request));
+                    // Admins may key any account; a key or OAuth principal only its own.
+                    if (!requireKeyManagementFor(principal, body.account, response))
+                        return;
+                    const { record, token } = await addMcpKey(options.mcpKeysFile, body);
+                    // The raw token is returned exactly once; only its hash is stored.
+                    json(response, 201, { id: record.id, label: record.label, account: record.account, createdAt: record.createdAt, token });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'mcp_key_create_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/mcp-keys' && request.method === 'DELETE') {
+                if (!options.mcpKeysFile) {
+                    json(response, 400, { error: { code: 'mcp_keys_not_configured', message: 'This server was started without an MCP keys file; restart it with --mcp-keys-file to manage per-account keys.' } });
+                    return;
+                }
+                const id = new URL(request.url ?? '/', 'http://localhost').searchParams.get('id');
+                if (!id) {
+                    json(response, 400, { error: { code: 'invalid_request', message: 'id is required.' } });
+                    return;
+                }
+                try {
+                    // Admins may revoke any key; a key or OAuth principal only its own.
+                    // An unknown id falls through to the same 404 as the admin path.
+                    if (principal.role !== 'admin') {
+                        const keys = await listMcpKeys(options.mcpKeysFile);
+                        const target = keys.find((key) => key.id === id);
+                        if (target && !requireKeyManagementFor(principal, target.account, response))
+                            return;
+                    }
+                    await revokeMcpKey(options.mcpKeysFile, id);
+                    json(response, 200, { revoked: id });
+                }
+                catch (error) {
+                    if (error instanceof McpKeyNotFoundError) {
+                        json(response, 404, { error: { code: 'mcp_key_not_found', message: error.message } });
+                        return;
+                    }
+                    json(response, 400, { error: { code: 'mcp_key_revoke_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/mcp-keys/roll' && request.method === 'POST') {
+                if (!options.mcpKeysFile) {
+                    json(response, 400, { error: { code: 'mcp_keys_not_configured', message: 'This server was started without an MCP keys file; restart it with --mcp-keys-file to manage per-account keys.' } });
+                    return;
+                }
+                try {
+                    const body = parseMcpKeyRollBody(await readJsonBody(request));
+                    // Admins may roll any key; a key or OAuth principal only its own.
+                    // An unknown id falls through to the same 404 as the admin path.
+                    if (principal.role !== 'admin') {
+                        const keys = await listMcpKeys(options.mcpKeysFile);
+                        const target = keys.find((key) => key.id === body.id);
+                        if (target && !requireKeyManagementFor(principal, target.account, response))
+                            return;
+                    }
+                    const { record, token } = await rollMcpKey(options.mcpKeysFile, body.id);
+                    // The new raw token is returned exactly once; only its hash is stored.
+                    json(response, 200, { id: record.id, label: record.label, account: record.account, createdAt: record.createdAt, token });
+                }
+                catch (error) {
+                    if (error instanceof McpKeyNotFoundError) {
+                        json(response, 404, { error: { code: 'mcp_key_not_found', message: error.message } });
+                        return;
+                    }
+                    json(response, 400, { error: { code: 'mcp_key_roll_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/mcp-oauth-settings' && request.method === 'GET') {
+                if (!requireAdmin(principal, response))
+                    return;
+                if (!oauthSettingsFile) {
+                    json(response, 400, { error: { code: 'mcp_oauth_not_configured', message: 'This server was started without an OAuth settings file; restart it with --oauth-settings-file to manage OAuth from the Console.' } });
+                    return;
+                }
+                const status = effectiveOauth();
+                json(response, 200, {
+                    enabled: status.enabled,
+                    publicUrl: status.publicUrl ?? null,
+                    source: status.source,
+                    settingsFile: oauthSettingsFile,
+                    settingsState: status.settingsState,
+                });
+                return;
+            }
+            if (pathname === '/api/v1/mcp-oauth-settings' && request.method === 'POST') {
+                if (!requireAdmin(principal, response))
+                    return;
+                if (!oauthSettingsFile) {
+                    json(response, 400, { error: { code: 'mcp_oauth_not_configured', message: 'This server was started without an OAuth settings file; restart it with --oauth-settings-file to manage OAuth from the Console.' } });
+                    return;
+                }
+                try {
+                    const body = parseMcpOauthSettingsBody(await readJsonBody(request));
+                    await writeMcpOauthSettings(oauthSettingsFile, body);
+                    const status = effectiveOauth();
+                    json(response, 200, {
+                        enabled: status.enabled,
+                        publicUrl: status.publicUrl ?? null,
+                        source: status.source,
+                        settingsFile: oauthSettingsFile,
+                        settingsState: status.settingsState,
+                    });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'mcp_oauth_settings_update_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
             if (pathname === '/mcp') {
-                await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
+                await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths(), principal);
                 return;
             }
             json(response, 404, { error: { code: 'not_found', message: 'No Catence endpoint matches this request.' } });