catence 0.2.1-beta.16 → 0.2.1-beta.18

package/dist/interfaces/mcp/main.js

@@ -2,7 +2,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync } from 'node:fs';
 import { addAthlete, athleteStorePaths, CatenceDatabase, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths, startAutoSyncScheduler } from '../../runtime/index.js';
-import { defaultBearerTokenPath, parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
+import { defaultBearerTokenPath, defaultMcpKeysPath, defaultOauthSettingsPath, oauthStatusFromSettings, parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
 import { createCatenceHttpServer } from '../http/server.js';
 import { MCP_USAGE, parseMcpCliOptions } from './cli-options.js';
 import { createCatenceMcpServer } from './server.js';
@@ -47,12 +47,24 @@ async function run() {
         }
         await migrateCatalogStores(options.home);
         const catalogPaths = resolveCatalogPaths(options.home);
+        const mcpKeysFile = options.mcpKeysFile ?? defaultMcpKeysPath(catalogPaths.root);
+        const oauthSettingsFile = options.oauthSettingsFile ?? defaultOauthSettingsPath(catalogPaths.root);
         const httpServer = createCatenceHttpServer({
             catalogPaths,
             allowedOrigins: options.allowedOrigins,
             // The token file's presence switches authentication on; enable it with
             // `catence-data mcp enable` (or the Console Settings / exposure API).
             bearerTokenFile: options.authTokenFile ?? defaultBearerTokenPath(catalogPaths.root),
+            // Any active per-account key in the registry arms the gate too; manage
+            // keys with `catence-data mcp key`.
+            mcpKeysFile,
+            // The Console-managed settings file overrides the startup --oauth flag at
+            // runtime; the Express sub-app builds lazily on first effective use.
+            oauthSettingsFile,
+            // The OAuth authorization server (express is loaded lazily inside the
+            // server) serves /.well-known/oauth-* and /oauth/* and verifies tokens
+            // at the gate; requires the https --public-url validated at parse time.
+            ...(options.oauth && options.publicUrl ? { oauth: { publicUrl: options.publicUrl } } : {}),
         });
         await new Promise((resolve, reject) => {
             httpServer.once('error', reject);
@@ -63,6 +75,14 @@ async function run() {
         });
         console.error(`Catence Streamable HTTP server is listening at http://${options.host}:${options.port}/mcp`);
         console.error(`Bearer-token authentication is armed at ${options.authTokenFile ?? defaultBearerTokenPath(catalogPaths.root)}; enable it with 'catence-data mcp enable'. Health endpoints stay open for readiness probes.`);
+        console.error(`Per-account MCP keys are read from ${mcpKeysFile}; manage them with 'catence-data mcp key'.`);
+        const oauthStatus = oauthStatusFromSettings(oauthSettingsFile);
+        if (oauthStatus.enabled && oauthStatus.publicUrl) {
+            console.error(`OAuth 2.1 authorization server is enabled (${oauthStatus.source}); issuer ${oauthStatus.publicUrl}, consent at ${oauthStatus.publicUrl}/oauth/consent.`);
+        }
+        else {
+            console.error('OAuth 2.1 authorization server is disabled; enable it from the Console (Settings, MCP exposure tab) or with CATENCE_OAUTH_ENABLED=1 and CATENCE_PUBLIC_URL.');
+        }
         // Auto-sync runs while the server is up: each athlete's autosync.json
         // (default: enabled, every 2 hours) triggers a detached sync. The
         // detached child and the single-writer DuckDB lock stay the only

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

@@ -5,5 +5,16 @@ type McpDependencies = {
     hydrateStravaActivity?: StravaActivityHydrator;
     startDetachedSync?: typeof startDetachedSync;
 };
-export declare function createCatenceMcpServer(paths?: CatencePaths | CatalogPaths, dependencies?: McpDependencies): McpServer;
+export type CatenceMcpServerOptions = {
+    /**
+     * Athlete scope enforced on every tool that selects an athlete, and applied
+     * to the list_athletes tool and the catence://athletes resource. "all" (or no
+     * scope at all, as on the stdio path) means the caller may reach every
+     * athlete.
+     */
+    scope?: {
+        athleteIds: string[] | 'all';
+    };
+};
+export declare function createCatenceMcpServer(paths?: CatencePaths | CatalogPaths, dependencies?: McpDependencies, options?: CatenceMcpServerOptions): McpServer;
 export {};

package/dist/interfaces/mcp/server.js

@@ -1,7 +1,7 @@
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
-import { ActivityDiscoveryService, AnalyticsService, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, loadCatalog, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, DetachedSyncBusyError, EventsService, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, listAthleteFileRevisions, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, readAthleteFile, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, searchContext, SlidingWindowLimiter, startDetachedSync, StravaEnrichmentError, StravaRateLimitError, SwimmingService, updateAthleteFile, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
+import { ActivityDiscoveryService, AnalyticsService, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, loadCatalog, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, DetachedSyncBusyError, EventsService, filterRosterToScope, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, listAthleteFileRevisions, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, readAthleteFile, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, scopeAllowsAthlete, searchContext, SlidingWindowLimiter, startDetachedSync, StravaEnrichmentError, StravaRateLimitError, SwimmingService, updateAthleteFile, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
 const filterSchema = z.object({
     column: z.string().min(1),
     op: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'between', 'contains']),
@@ -137,12 +137,13 @@ async function activitySegments(repository, activityId, hydratedStravaActivityId
     LIMIT $limit
   `, values);
 }
-export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependencies = {}) {
+export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependencies = {}, options = {}) {
     const server = new McpServer({ name: 'catence', version: '0.1.0' }, { instructions: MCP_INSTRUCTIONS });
     const hydrateActivity = dependencies.hydrateStravaActivity ?? hydrateStravaActivity;
     const startSync = dependencies.startDetachedSync ?? startDetachedSync;
     const catalogPaths = isCatalogPaths(paths) ? paths : null;
     const staticPaths = isCatalogPaths(paths) ? null : paths;
+    const athleteScope = options.scope?.athleteIds;
     const scope = new AsyncLocalStorage();
     const activePaths = () => scope.getStore()?.paths ?? staticPaths ?? (() => { throw new Error('athleteId is required. Call list_athletes to inspect the configured catalog.'); })();
     const activeAthlete = () => scope.getStore()?.athlete;
@@ -177,7 +178,9 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         }, async () => {
             try {
                 const catalog = await loadCatalog(catalogPaths);
-                return textResult({ data: { defaultAthleteId: catalog.defaultAthleteId, athletes: catalog.athletes } });
+                // The roster is narrowed to the caller's athlete scope, if any.
+                const roster = filterRosterToScope(catalog.athletes, catalog.defaultAthleteId, athleteScope ?? 'all');
+                return textResult({ data: { defaultAthleteId: roster.defaultAthleteId, athletes: roster.athletes } });
             }
             catch (error) {
                 return errorResult(error);
@@ -217,6 +220,15 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             const selected = catalogPaths
                 ? await resolveAthlete(catalogPaths, rawInput.athleteId ?? '')
                 : null;
+            // A scoped caller may only reach athletes inside its scope; the HTTP gate
+            // applies the same rule to its JSON APIs.
+            if (selected && athleteScope !== undefined && !scopeAllowsAthlete(athleteScope, selected.athlete.id)) {
+                const message = `This credential is not allowed to access athlete ${selected.athlete.id}.`;
+                return {
+                    ...textResult({ data: null, provenance: {}, query: { athleteId: selected.athlete.id }, caveats: [message], error: { code: 'athlete_forbidden', message } }),
+                    isError: true,
+                };
+            }
             const run = async () => {
                 const currentPaths = activePaths();
                 const config = await loadCatenceConfig(currentPaths);
@@ -731,7 +743,9 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         server.registerResource('athletes', 'catence://athletes', { title: 'Configured athlete roster', mimeType: 'application/json' }, async (uri) => {
             try {
                 const catalog = await loadCatalog(catalogPaths);
-                return resource(uri, { defaultAthleteId: catalog.defaultAthleteId, athletes: catalog.athletes });
+                // The roster is narrowed to the caller's athlete scope, if any.
+                const roster = filterRosterToScope(catalog.athletes, catalog.defaultAthleteId, athleteScope ?? 'all');
+                return resource(uri, { defaultAthleteId: roster.defaultAthleteId, athletes: roster.athletes });
             }
             catch (error) {
                 return resource(uri, { error: errorResult(error).content[0].text });

package/dist/runtime/index.d.ts

@@ -13,6 +13,13 @@ export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
 export type { Athlete, CatalogPaths, CatenceCatalog } from '../core/runtime/catalog.js';
+export { addMcpKey, countActiveMcpKeys, listMcpKeys, McpKeyNotFoundError, resolveKeyPrincipal, revokeMcpKey, rollMcpKey, } from '../core/runtime/mcp-keys.js';
+export type { McpKeyPrincipal, McpKeyRecord, McpKeySummary } from '../core/runtime/mcp-keys.js';
+export { consoleAccountsPath, filterRosterToScope, loadConsoleAccounts, resolveAccountScope, scopeAllowsAthlete, verifyAccountPassword, } from '../core/runtime/console-accounts.js';
+export type { ConsoleAccount, ConsoleAccountRole, ConsoleAccountScope } from '../core/runtime/console-accounts.js';
+export { createFileOAuthServerModel, FileOAuthServerModel } from '../core/runtime/oauth/model.js';
+export { normalizeMcpOauthSettings, readMcpOauthSettings, validateOauthPublicUrl, writeMcpOauthSettings, } from '../core/runtime/oauth/settings.js';
+export type { McpOauthSettings, McpOauthSettingsInput, McpOauthSettingsRead, McpOauthSettingsState, } from '../core/runtime/oauth/settings.js';
 export { athleteProviderEnvironment, deleteAthleteSecret, describeAthleteSecrets, providerSecretPath, readAthleteSecrets, secretProviderLabels, setAthleteSecret } from '../core/runtime/secrets.js';
 export type { AthleteSecrets, SecretFieldDescription, SecretProvider, SecretProviderDescription } from '../core/runtime/secrets.js';
 export { ATHLETE_FILE_MAX_CHARACTERS, ATHLETE_FILE_TEMPLATE, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, hashAthleteFileContent, listAthleteFileRevisions, readAthleteFile, readAthleteFileRevision, updateAthleteFile, } from '../core/runtime/athlete-file.js';

package/dist/runtime/index.js

@@ -2,6 +2,10 @@ export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiR
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
+export { addMcpKey, countActiveMcpKeys, listMcpKeys, McpKeyNotFoundError, resolveKeyPrincipal, revokeMcpKey, rollMcpKey, } from '../core/runtime/mcp-keys.js';
+export { consoleAccountsPath, filterRosterToScope, loadConsoleAccounts, resolveAccountScope, scopeAllowsAthlete, verifyAccountPassword, } from '../core/runtime/console-accounts.js';
+export { createFileOAuthServerModel, FileOAuthServerModel } from '../core/runtime/oauth/model.js';
+export { normalizeMcpOauthSettings, readMcpOauthSettings, validateOauthPublicUrl, writeMcpOauthSettings, } from '../core/runtime/oauth/settings.js';
 export { athleteProviderEnvironment, deleteAthleteSecret, describeAthleteSecrets, providerSecretPath, readAthleteSecrets, secretProviderLabels, setAthleteSecret } from '../core/runtime/secrets.js';
 export { ATHLETE_FILE_MAX_CHARACTERS, ATHLETE_FILE_TEMPLATE, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, hashAthleteFileContent, listAthleteFileRevisions, readAthleteFile, readAthleteFileRevision, updateAthleteFile, } from '../core/runtime/athlete-file.js';
 export { SlidingWindowLimiter } from '../core/runtime/limiter.js';

package/docs/deployment/docker.md

@@ -27,6 +27,7 @@ explained in the [beta release notes](../../README.md#beta-releases).
 | API keys | process environment only | `.env` |
 | Chat history + preferences | data home | `console/chat-history.sqlite3` |
 | Console logins + athlete grants | data home (mode 0600, bcrypt hashes) | `console/accounts.json` |
+| Per-account MCP keys + OAuth state | data home (registry 0600; `oauth/` dir 0700) | `mcp-keys.json`, `oauth/` |
 
 Credentials never land in `config.json`; profiles reference environment
 variable *names* (`apiKeyEnv`, `apiBaseEnv`, `apiVersionEnv`). See
@@ -165,9 +166,10 @@ to scope a chat to. The environment pair is a never-persisted break-glass
 admin: it keeps working when the accounts file is lost or the last admin is
 locked out, and unsetting the two variables revokes it.
 
-Accounts gate the Console only. The MCP server keeps its own contract — no
-authentication, the caller's `athleteId` is trusted — so port 8787 still needs
-loopback or network-layer restriction (see
+Accounts gate the Console only. The MCP server has no authentication by
+default — the caller's `athleteId` is trusted — so port 8787 still needs
+loopback or network-layer restriction unless you switch on the bearer gate,
+per-account keys, or OAuth (see
 [Connecting to the Docker-based MCP from outside](#connecting-to-the-docker-based-mcp-from-outside)).
 
 The accounts file is the only copy of your stored logins: keep it in backups
@@ -468,11 +470,12 @@ CATENCE_MCP_BIND=0.0.0.0 ./scripts/deploy-console.sh beta
 After deployment, the MCP server is available at
 `http://<tailscale-ip>:8787/mcp` from any device on your tailnet.
 
-**Security note:** The MCP server has **no authentication** — it trusts the
-caller's `athleteId` parameter. When exposing on `0.0.0.0`, you **must**
-restrict access at the network layer (Tailscale ACLs, firewall rules, etc.).
-The Console UI remains on loopback (`127.0.0.1:8000`) and should still be
-fronted by Cloudflare Tunnel or a reverse proxy.
+**Security note:** Without the bearer gate, per-account keys, or OAuth, the MCP
+server has **no authentication** — it trusts the caller's `athleteId`
+parameter. When exposing on `0.0.0.0`, you **must** restrict access at the
+network layer (Tailscale ACLs, firewall rules, etc.). The Console UI remains
+on loopback (`127.0.0.1:8000`) and should still be fronted by Cloudflare
+Tunnel or a reverse proxy.
 
 **Examples: common MCP clients**
 
@@ -498,8 +501,8 @@ claude mcp add --transport http catence -- http://<tailscale-ip>:8787/mcp
 
 ### Why not expose port 8787 directly?
 
-- The MCP server has **no authentication** — it trusts the caller's
-  `athleteId` parameter.
+- Without the bearer gate, per-account keys, or OAuth, the MCP server has
+  **no authentication** — it trusts the caller's `athleteId` parameter.
 - Exposing it would allow any network caller to read all athlete data in the
   catalog.
 - The Console proxies dashboard requests through its **authenticated**
@@ -547,6 +550,41 @@ A custom host-side token file is still possible: set
 read-only at the same path, so it must already exist on the host — enabling
 from the Console cannot create it.
 
+#### Per-account MCP keys and OAuth 2.1 (Docker)
+
+The runtime reads three more environment variables. The deploy script passes
+them into the container, writes them into `catence-deploy/.env`, and validates
+them before rendering the compose file:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `CATENCE_OAUTH_ENABLED` | empty (disabled) | `1` or `true` runs the OAuth 2.1 authorization server so ChatGPT/Codex connect with their OAuth flow. Startup default — the Console (Settings → MCP Exposure → OAuth 2.1 sign-in) overrides it at runtime. Requires `CATENCE_PUBLIC_URL` when enabled. |
+| `CATENCE_PUBLIC_URL` | empty | Public `https` URL of this server (the tunnel URL; no query string or fragment). It becomes the advertised OAuth issuer. Startup default — overridable in the Console. |
+| `CATENCE_MCP_KEYS_FILE` | `/data/mcp-keys.json` | Per-account MCP key registry, a container path — no host mount needed. Managed with `catence-data mcp key` or the Console (Settings → MCP Exposure → API keys). |
+
+```sh
+# Per-account key for a Console account (the raw token is printed exactly once):
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp key add --account coach
+
+# OAuth for ChatGPT/Codex — preferred: enable in the Console
+#   (Settings → MCP Exposure → OAuth 2.1 sign-in; applies without a restart).
+# Startup defaults, set in catence-deploy/.env and re-run the script:
+#   CATENCE_OAUTH_ENABLED=1
+#   CATENCE_PUBLIC_URL=https://catence-mcp.example.com
+./scripts/deploy-console.sh beta
+```
+
+The script refuses to deploy when `CATENCE_OAUTH_ENABLED` is set without a
+valid https `CATENCE_PUBLIC_URL`. Once a valid Console settings file exists
+(`<catalog-home>/oauth/settings.json`, inside the data volume), it overrides
+these startup values at runtime. The checked-in dev compose
+(`docker-compose.beta.yml`) accepts `CATENCE_OAUTH_ENABLED` and
+`CATENCE_PUBLIC_URL` the same way (empty default = disabled). See
+[local-mcp.md](local-mcp.md#per-account-api-keys) and
+[local-mcp.md](local-mcp.md#oauth-21-chatgptcodex) for the full semantics and
+the client matrix.
+
 ## Exposing the Console safely
 
 Keep the Console port bound to `127.0.0.1` (the default) and front it with a

package/docs/deployment/local-mcp.md

@@ -90,8 +90,10 @@ implicitly; the MCP server does not authenticate callers — it trusts the
 Catence serves several athlete stores from one server. Each store has its own
 DuckDB, raw data, and tokens; a call acts on the single store it names and
 never merges athletes implicitly. That is a tool contract, not an access
-boundary: the MCP server does not authenticate callers and trusts the
-`athleteId` they pass — see [MCP clients and HTTP](#streamable-http-server).
+boundary: the stdio server does not authenticate callers and trusts the
+`athleteId` they pass — over Streamable HTTP the bearer gate, per-account
+keys, or OAuth authenticate and scope callers; see
+[MCP clients and HTTP](#streamable-http-server).
 
 ### MCP behavior
 
@@ -310,7 +312,10 @@ Mistral Work), switch on the bearer-token gate. The gate is armed at a token
 file — `<catalog-home>/mcp-token` by default, or the path given by
 `--auth-token-file` (environment equivalent: `CATENCE_MCP_TOKEN_FILE`) — and
 the **file's presence is the switch**: create it to enable, remove it to
-disable, no restart needed.
+disable, no restart needed. The gate is also armed when the per-account key
+registry holds at least one active key or when OAuth is enabled (see the next
+sections); only with no token file, no keys, and no OAuth configured is the
+server open.
 
 Catence generates the token itself; never hand-craft one:
 
@@ -325,7 +330,9 @@ catence-data mcp disable   # remove the file; remote access is refused again
   probes) answers `401` without an exact `Authorization: Bearer <token>`
   header while the gate is on. The `401` deliberately carries no
   `WWW-Authenticate`, so MCP clients with auth auto-detection (Mistral Work)
-  classify the server as bearer-auth rather than OAuth.
+  classify the server as bearer-auth rather than OAuth. With OAuth enabled the
+  `401` instead gains a `WWW-Authenticate: Bearer resource_metadata="<public-url>/.well-known/oauth-protected-resource/mcp"`
+  challenge — see [OAuth 2.1 (ChatGPT/Codex)](#oauth-21-chatgptcodex).
 - CORS preflights (`OPTIONS`) pass through without a token.
 - An existing but unreadable or empty token file fails closed: the gate
   rejects everything except the health probes until the file is fixed or
@@ -369,7 +376,108 @@ catence-data mcp disable   # remove the file; remote access is refused again
   packaged Console instead proxies the dashboard through its authenticated
   same-origin route.
 
-Connect HTTP-based clients to `http://127.0.0.1:8787/mcp`. There is **no
-authentication on the MCP server itself** — it trusts the caller's `athleteId`
-parameter — so keep it on loopback or restrict it at the network layer. For
-remote access over SSH: `ssh -L 8787:127.0.0.1:8787 server`.
+#### Per-account API keys
+
+The shared bearer token is a single admin credential. For per-account access,
+create API keys bound to Console accounts (`console/accounts.json`). A key acts
+as its account: an admin account's key sees every athlete, a member account's
+key sees only that account's granted athletes.
+
+The key registry lives at `<catalog-home>/mcp-keys.json` — override with
+`--mcp-keys-file` or `CATENCE_MCP_KEYS_FILE`. In the Docker deployment the
+default is `/data/mcp-keys.json` inside the data volume: runtime-managed, no
+host mount needed. The file is written atomically with mode 0600 and stores
+only SHA-256 token hashes. Any active key in the registry arms the gate,
+exactly like the token file's presence does.
+
+```sh
+catence-data mcp status                                    # gate, token, key counts, OAuth state
+catence-data mcp key add --account coach --label "vibe"   # prints the raw token exactly once
+catence-data mcp key list                                  # ids, labels, accounts — never hashes
+catence-data mcp key roll <id>                             # new raw token, printed exactly once
+catence-data mcp key revoke <id>                           # stops working immediately
+```
+
+All four accept `--file <path>` for a non-default registry. Admins manage the
+same registry in the Console under Settings → MCP Exposure → API keys (create
+with an account picker and a label — the raw token is shown once — and revoke
+by id), backed by the admin-only HTTP API `GET`/`POST`/`DELETE
+/api/v1/mcp-keys` and `POST /api/v1/mcp-keys/roll`.
+
+Scope semantics:
+
+- A key is bound to a Console account; its athlete scope is the account's
+  grant list, resolved live from `console/accounts.json` on every request.
+- Scope is enforced in the runtime for both MCP tools and the HTTP APIs: an
+  out-of-scope `athleteId` is refused with `403 athlete_forbidden` over HTTP
+  (`athlete_forbidden` tool error over MCP), and `list_athletes`,
+  `catence://athletes`, and `GET /api/v1/athletes` are filtered to the scope.
+- Admin-only APIs (`POST /api/v1/athletes`, `/api/v1/mcp-exposure`,
+  `/api/v1/mcp-keys`, `/api/v1/models/discover`) require an admin principal:
+  the legacy token is always admin, an account key is admin only when its
+  account is.
+- Fail closed: a revoked key, a deleted account, or an unreadable registry or
+  accounts file rejects the request (`401`) — never an anonymous fallback.
+- The raw token is shown exactly once (on `add` and `roll`); only its hash is
+  stored. Keep it in a password manager, out of `.env`, `config.json`, shell
+  history, and repositories.
+- `mcp disable` only closes the shared-token path: while keys or OAuth are
+  configured, exposure stays armed through them.
+
+#### OAuth 2.1 (ChatGPT/Codex)
+
+`catence serve --oauth --public-url <url>` runs an OAuth 2.1 authorization
+server inside the runtime so ChatGPT and Codex can connect with their native
+OAuth flow. The environment equivalents are `CATENCE_OAUTH_ENABLED=1|true` and
+`CATENCE_PUBLIC_URL=<url>`.
+
+From the Console, open Settings → MCP exposure → **OAuth 2.1 sign-in**: set the
+public URL and flip the switch. The Console writes
+`<catalog-home>/oauth/settings.json`, which the runtime reads on every request —
+the change applies immediately, without a restart. Once a valid settings file
+exists it alone decides whether OAuth is enabled and overrides the
+`CATENCE_OAUTH_ENABLED`/`CATENCE_PUBLIC_URL` (or `--oauth`/`--public-url`)
+startup values; a malformed file fails closed to disabled until the Console
+saves a valid one. `catence-data mcp status` reports the effective state and
+its `source` (`console`, `environment`, or `disabled`).
+
+- The issuer is the public URL: it must be an absolute `https` URL with no
+  query string or fragment (typically the tunnel URL), and it is required when
+  OAuth is enabled — the server refuses to start without it (startup values)
+  and the Console write rejects it (settings values).
+- Clients discover the server through RFC 8414/RFC 9728 metadata served at
+  `/.well-known/oauth-authorization-server` and
+  `/.well-known/oauth-protected-resource[/mcp]`. Dynamic client registration
+  (`POST /oauth/register`, RFC 7591) and client ID metadata documents (CIMD)
+  are enabled; PKCE with S256 is enforced.
+- The browser consent page lives at `<public-url>/oauth/consent`: it logs in
+  with a Console account (username + password, verified against
+  `console/accounts.json`) and asks to approve or deny the client. The access
+  token carries the account username, and the athlete scope is that account's
+  live grants — scoped exactly like an account key.
+- While OAuth is enabled, the `401` for a missing or invalid bearer token
+  gains an RFC 9728 challenge —
+  `WWW-Authenticate: Bearer resource_metadata="<public-url>/.well-known/oauth-protected-resource/mcp"`
+  — so OAuth clients can discover the authorization server. Without `--oauth`
+  the `401` stays plain on purpose (Mistral connector auto-detection).
+- Authorization-server state (registered clients, authorization codes, tokens)
+  lives in `<catalog-home>/oauth/` (directory mode 0700, files 0600).
+
+Note: the added `WWW-Authenticate` challenge can flip a client with auth
+auto-detection (Mistral Work) from bearer to OAuth — smoke-test the Mistral
+connector after enabling OAuth.
+
+#### Client matrix
+
+| Client | Setup | Credential |
+| --- | --- | --- |
+| Mistral Vibe (Work custom connector) | Connectors → Add Connector → Custom MCP Connector, URL `https://<host>/mcp` | Bearer credential (the shared token) — unchanged |
+| Claude (custom connector) | Authentication: "No sign in"; Request headers: `Authorization: Bearer <key>` | Per-account API key |
+| Claude Code (CLI) | `claude mcp add --transport http --header "Authorization: Bearer <key>" <url>` | Per-account API key |
+| ChatGPT / Codex | Connector OAuth connect flow | OAuth 2.1 (Console: MCP exposure → OAuth 2.1 sign-in, or `--oauth`) |
+
+Connect HTTP-based clients to `http://127.0.0.1:8787/mcp`. Without the bearer
+gate, per-account keys, or OAuth there is **no authentication on the MCP
+server itself** — it trusts the caller's `athleteId` parameter — so keep it on
+loopback or restrict it at the network layer. For remote access over SSH:
+`ssh -L 8787:127.0.0.1:8787 server`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.1-beta.16",
+  "version": "0.2.1-beta.18",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -71,12 +71,18 @@
   "dependencies": {
     "@duckdb/node-api": "^1.4.4-r.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "bcryptjs": "3.0.3",
     "commander": "^14.0.0",
     "dotenv": "^17.2.2",
+    "express": "5.3.0",
+    "express-rate-limit": "8.7.1",
     "intervals-icu": "^2.2.0",
+    "mcp-oauth-server": "1.0.1",
     "zod": "^4.1.5"
   },
   "devDependencies": {
+    "@types/bcryptjs": "2.4.6",
+    "@types/express": "5.0.6",
     "@types/node": "^24.3.0",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",