catence 0.2.1-beta.18 → 0.2.1-beta.19

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.18";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.19";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.18';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.19';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/runtime/oauth/public-client.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public-client normalization for OAuth client metadata.
+ *
+ * Some OAuth clients — OpenAI's ChatGPT/Codex connector is the known case —
+ * register (RFC 7591 DCR) or publish a client ID metadata document (CIMD)
+ * with `token_endpoint_auth_method: "private_key_jwt"`. Catence has no JWKS
+ * trust for client assertions, so it cannot honor that method; mcp-oauth-server
+ * rejects any method other than "none"/"client_secret_post" outright, which
+ * breaks those clients at registration or authorization time with
+ * `invalid_client: Unsupported token_endpoint_auth_method`.
+ *
+ * The fix is to treat such clients as what they are: public clients. No client
+ * secret is issued, redirect URIs are validated exactly as before, and PKCE
+ * with S256 stays enforced at the authorization and token endpoints — the same
+ * protection a public client gets with `"none"`. A `client_assertion` the
+ * client later sends at the token endpoint is ignored by the server's
+ * client-authentication step, which only reads `client_id`/`client_secret`.
+ */
+export declare const PRIVATE_KEY_JWT = "private_key_jwt";
+/**
+ * True when the metadata declares private_key_jwt client authentication.
+ */
+export declare function declaresPrivateKeyJwt(value: unknown): boolean;
+/**
+ * Return the metadata with private_key_jwt downgraded to "none" (public
+ * client). Anything else passes through unchanged.
+ */
+export declare function asPublicClientMetadata<T>(value: T): T;

package/dist/core/runtime/oauth/public-client.js

@@ -0,0 +1,35 @@
+/**
+ * Public-client normalization for OAuth client metadata.
+ *
+ * Some OAuth clients — OpenAI's ChatGPT/Codex connector is the known case —
+ * register (RFC 7591 DCR) or publish a client ID metadata document (CIMD)
+ * with `token_endpoint_auth_method: "private_key_jwt"`. Catence has no JWKS
+ * trust for client assertions, so it cannot honor that method; mcp-oauth-server
+ * rejects any method other than "none"/"client_secret_post" outright, which
+ * breaks those clients at registration or authorization time with
+ * `invalid_client: Unsupported token_endpoint_auth_method`.
+ *
+ * The fix is to treat such clients as what they are: public clients. No client
+ * secret is issued, redirect URIs are validated exactly as before, and PKCE
+ * with S256 stays enforced at the authorization and token endpoints — the same
+ * protection a public client gets with `"none"`. A `client_assertion` the
+ * client later sends at the token endpoint is ignored by the server's
+ * client-authentication step, which only reads `client_id`/`client_secret`.
+ */
+export const PRIVATE_KEY_JWT = 'private_key_jwt';
+/**
+ * True when the metadata declares private_key_jwt client authentication.
+ */
+export function declaresPrivateKeyJwt(value) {
+    return typeof value === 'object' && value !== null && value.token_endpoint_auth_method === PRIVATE_KEY_JWT;
+}
+/**
+ * Return the metadata with private_key_jwt downgraded to "none" (public
+ * client). Anything else passes through unchanged.
+ */
+export function asPublicClientMetadata(value) {
+    if (!declaresPrivateKeyJwt(value))
+        return value;
+    return { ...value, token_endpoint_auth_method: 'none' };
+}
+//# sourceMappingURL=public-client.js.map

package/dist/elt/application/detached-sync.d.ts

@@ -8,6 +8,11 @@ export type DetachedSyncRequest = {
     provider?: DetachedSyncProvider;
     from?: string;
     refresh?: boolean;
+    /**
+     * Run `catence-data backfill` instead of `sync`: extend history backwards
+     * from `from` without advancing the incremental cursors. Requires `from`.
+     */
+    backfill?: boolean;
     /**
      * The `--home` value the detached `catence-data` child must receive.
      *
@@ -35,8 +40,8 @@ export type DetachedSyncSpawner = (command: string, arguments_: readonly string[
     unref(): void;
 };
 /**
- * Spawn one detached `catence-data sync` process for an athlete store and
- * return immediately.
+ * Spawn one detached `catence-data sync` (or `backfill`, when requested)
+ * process for an athlete store and return immediately.
  *
  * The child outlives this process (SSH deaths, Console restarts), logs to a
  * file under the catalog home, and is guarded by the same live-progress

package/dist/elt/application/detached-sync.js

@@ -46,10 +46,15 @@ function assertValidRequest(request) {
     if (request.from !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(request.from)) {
         throw new Error('from must use YYYY-MM-DD.');
     }
+    // The CLI's backfill subcommand requires --from; enforce it here so the
+    // child never spawns into a usage error.
+    if (request.backfill && !request.from) {
+        throw new Error('from is required for a backfill.');
+    }
 }
 /**
- * Spawn one detached `catence-data sync` process for an athlete store and
- * return immediately.
+ * Spawn one detached `catence-data sync` (or `backfill`, when requested)
+ * process for an athlete store and return immediately.
  *
  * The child outlives this process (SSH deaths, Console restarts), logs to a
  * file under the catalog home, and is guarded by the same live-progress
@@ -73,8 +78,9 @@ export async function startDetachedSync(request, dependencies = {}) {
     const stamp = (dependencies.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, '-');
     const logFile = path.join(request.paths.root, 'logs', `sync-${request.athleteId}-${stamp}.log`);
     await mkdir(path.dirname(logFile), { recursive: true });
-    await writeFile(logFile, `[${new Date().toISOString()}] catence-data --athlete ${request.athleteId} sync --provider ${provider}${request.from ? ` --from ${request.from}` : ''}${request.refresh ? ' --refresh' : ''}\n`, 'utf8');
-    const arguments_ = [cliInvocation().entry, '--home', request.cliHome ?? request.paths.root, '--athlete', request.athleteId, 'sync', '--provider', provider];
+    const subcommand = request.backfill ? 'backfill' : 'sync';
+    await writeFile(logFile, `[${new Date().toISOString()}] catence-data --athlete ${request.athleteId} ${subcommand} --provider ${provider}${request.from ? ` --from ${request.from}` : ''}${request.refresh ? ' --refresh' : ''}\n`, 'utf8');
+    const arguments_ = [cliInvocation().entry, '--home', request.cliHome ?? request.paths.root, '--athlete', request.athleteId, subcommand, '--provider', provider];
     if (request.from)
         arguments_.push('--from', request.from);
     if (request.refresh)

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

@@ -10,26 +10,6 @@ export type OAuthAppHandle = {
     /** The RFC 9728 metadata URL advertised in the 401 WWW-Authenticate challenge. */
     protectedResourceMetadataUrl: string;
 };
-/**
- * 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.
- */
 export declare function createOAuthApp(options: {
     catalogRoot: string;
     publicUrl: string;

package/dist/interfaces/http/oauth.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import express from 'express';
 import { authenticateHandler, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl, mcpAuthRouter, OAuthServer, redirectUriMatches, } from 'mcp-oauth-server';
-import { createFileOAuthServerModel, resolveCatalogPaths, verifyAccountPassword } from '../../runtime/index.js';
+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.
@@ -22,6 +22,51 @@ import { createFileOAuthServerModel, resolveCatalogPaths, verifyAccountPassword
  * 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.
+ */
+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.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);
@@ -33,7 +78,7 @@ export async function createOAuthApp(options) {
         authorizationUrl: new URL(`${publicUrl}/oauth/consent`),
         resourceServerUrl,
         scopesSupported: ['mcp:tools'],
-        clientIdMetadataDocuments: true,
+        clientIdMetadataDocuments: { fetch: sanitizingMetadataFetch(fetch) },
         model: createFileOAuthServerModel(path.join(options.catalogRoot, 'oauth')),
     });
     const oauthMetadata = createOAuthMetadata({ provider, baseUrl: oauthBaseUrl });
@@ -60,6 +105,10 @@ export async function createOAuthApp(options) {
     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,

package/dist/interfaces/http/server.js

@@ -36,6 +36,20 @@ function requireAdmin(principal, response) {
     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
@@ -245,7 +259,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}.`);
         }
     }
@@ -257,10 +271,15 @@ 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;
 }
 function parseAthleteCreateBody(body) {
@@ -546,15 +565,24 @@ export function createCatenceHttpServer(options = {}) {
                 ? FULL_ACCESS_PRINCIPAL
                 : await resolvePrincipal(request, effectiveOptions, accountPaths);
             if (principal === null) {
-                // RFC 9728: point 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.
-                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}"`);
+                // 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;
@@ -784,6 +812,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,
@@ -935,15 +964,15 @@ export function createCatenceHttpServer(options = {}) {
                 return;
             }
             if (pathname === '/api/v1/mcp-keys' && request.method === 'GET') {
-                if (!requireAdmin(principal, response))
-                    return;
                 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.
-                    json(response, 200, { keys: await listMcpKeys(options.mcpKeysFile) });
+                    // 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) } });
@@ -951,14 +980,15 @@ export function createCatenceHttpServer(options = {}) {
                 return;
             }
             if (pathname === '/api/v1/mcp-keys' && request.method === 'POST') {
-                if (!requireAdmin(principal, response))
-                    return;
                 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 });
@@ -969,8 +999,6 @@ export function createCatenceHttpServer(options = {}) {
                 return;
             }
             if (pathname === '/api/v1/mcp-keys' && request.method === 'DELETE') {
-                if (!requireAdmin(principal, response))
-                    return;
                 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;
@@ -981,6 +1009,14 @@ export function createCatenceHttpServer(options = {}) {
                     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 });
                 }
@@ -994,14 +1030,20 @@ export function createCatenceHttpServer(options = {}) {
                 return;
             }
             if (pathname === '/api/v1/mcp-keys/roll' && request.method === 'POST') {
-                if (!requireAdmin(principal, response))
-                    return;
                 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 });

package/dist/interfaces/mcp/server.js

@@ -315,11 +315,12 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     }))));
     registerTool('start_detached_sync', {
         title: 'Start a detached data sync',
-        description: 'Write-only sync trigger, named like the other explicit lock-guarded write tools. Spawns one detached catence-data sync process for this athlete and returns immediately with the run handle and log file; it refuses while another sync run is active. Track the run with catence_sync_progress; this tool never waits for completion.',
+        description: 'Write-only sync trigger, named like the other explicit lock-guarded write tools. Spawns one detached catence-data sync process for this athlete and returns immediately with the run handle and log file; it refuses while another sync run is active. Track the run with catence_sync_progress; this tool never waits for completion. Pass backfill with a from date to extend history backwards without advancing the incremental cursors (from is required when backfill is set).',
         inputSchema: {
             provider: z.enum(['intervals', 'garmin', 'strava', 'all']).optional(),
             from: z.string().date().optional(),
             refresh: z.boolean().optional(),
+            backfill: z.boolean().optional(),
         },
     }, tool('start_detached_sync', async (input) => {
         const paths = activePaths();
@@ -330,6 +331,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             provider: input.provider,
             from: input.from,
             refresh: input.refresh,
+            backfill: input.backfill,
             // The child resolves the athlete within the catalog, not within the
             // athlete store this tool resolved for locks and logs: passing the
             // store itself trips the legacy-store guard in catalog deployments.

package/dist/runtime/index.d.ts

@@ -18,6 +18,7 @@ export type { McpKeyPrincipal, McpKeyRecord, McpKeySummary } from '../core/runti
 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 { asPublicClientMetadata, declaresPrivateKeyJwt, PRIVATE_KEY_JWT } from '../core/runtime/oauth/public-client.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';

package/dist/runtime/index.js

@@ -5,6 +5,7 @@ export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, init
 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 { asPublicClientMetadata, declaresPrivateKeyJwt, PRIVATE_KEY_JWT } from '../core/runtime/oauth/public-client.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';

package/docs/deployment/local-mcp.md

@@ -109,7 +109,9 @@ keys, or OAuth authenticate and scope callers; see
   Strava hydration tools: it spawns a detached `catence-data sync` child for
   the selected athlete and returns immediately with the run handle and log
   file. It refuses to start while another sync run is active (`sync_in_progress`);
-  follow the run with `catence_sync_progress`.
+  follow the run with `catence_sync_progress`. Pass `backfill: true` with a
+  `from` date to spawn `catence-data backfill` instead — history is re-imported
+  backwards from that date without advancing the incremental sync cursors.
 
 ### Adding another athlete
 
@@ -328,11 +330,16 @@ catence-data mcp disable   # remove the file; remote access is refused again
 
 - Every endpoint except `/health` and `/api/v1/health` (kept open for readiness
   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. 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).
+  header while the gate is on. A request with no token gets no
+  `WWW-Authenticate` at all, so MCP clients with auth auto-detection (Mistral
+  Work) classify the server as bearer-auth rather than OAuth; with OAuth
+  enabled a token-less `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). A request
+  that presents a wrong or expired token gets
+  `WWW-Authenticate: Bearer error="invalid_token", error_description="The access token is invalid or expired."`
+  with no `resource_metadata`: the client already holds a credential, so it is
+  told the token is bad instead of being steered into the OAuth flow.
 - 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
@@ -362,7 +369,11 @@ catence-data mcp disable   # remove the file; remote access is refused again
   returns `202` with the run handle immediately; an already-active run is
   refused with `409 sync_in_progress`. Pass `"refreshModels": true` to also
   refresh OpenCode Go model profiles first (failure is a non-fatal warning in
-  the response).
+  the response). Pass `"backfill": true` with a required `"from"` date
+  (`YYYY-MM-DD`) to run `catence-data backfill` instead: history is re-imported
+  backwards from that date without advancing the incremental cursors. The
+  Console's Status tab exposes the same control (date picker + "Backfill
+  history").
 - `GET /api/v1/sync/status?athleteId=alex` reports live progress heartbeats,
   recent runs, and best-effort last-completion timestamps per provider. It
   keeps working while a sync holds the write lock (`lastSync` becomes `null`
@@ -398,11 +409,15 @@ catence-data mcp key roll <id>                             # new raw token, prin
 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`.
+All four accept `--file <path>` for a non-default registry. Every Console
+account manages its own keys in Settings → API keys (create with a label — the
+raw token is shown once — plus roll and revoke); admins additionally see the
+whole registry in Settings → MCP Exposure → API keys with an account picker.
+The HTTP API `GET`/`POST`/`DELETE /api/v1/mcp-keys` and `POST
+/api/v1/mcp-keys/roll` enforce the same boundary for direct callers and for
+key- or OAuth-authenticated sessions: an admin principal may manage any
+account's keys, any other principal only its own (`403 admin_required`
+otherwise), and a non-admin's list shows only its own account's keys.
 
 Scope semantics:
 
@@ -413,9 +428,10 @@ Scope semantics:
   (`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.
+  `/api/v1/models/discover`) require an admin principal: the legacy token is
+  always admin, an account key is admin only when its account is. The key
+  registry APIs are account-scoped instead of admin-only — admins manage every
+  account's keys, any other principal only its own (see above).
 - 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
@@ -455,23 +471,32 @@ its `source` (`console`, `environment`, or `disabled`).
   `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 —
+- While OAuth is enabled, the `401` for a request with no 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).
+  — so OAuth clients can discover the authorization server. A presented but
+  invalid token gets `invalid_token` without the challenge instead. Without
+  `--oauth` the `401` stays plain on purpose (Mistral connector
+  auto-detection).
+- Clients that register (DCR) or publish a client ID metadata document with
+  `token_endpoint_auth_method: "private_key_jwt"` — OpenAI's ChatGPT/Codex
+  connector does — are accepted as public clients: the declaration is
+  downgraded to `"none"`, no client secret is issued, and PKCE with S256
+  still protects the flow. Catence cannot verify client JWT assertions, so
+  the method is never honored as such.
 - 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.
+Note: the `resource_metadata` challenge on token-less `401`s can flip a client
+with auth auto-detection (Mistral Work) from bearer to OAuth — smoke-test the
+Mistral connector after enabling OAuth. A client that already sends a key
+never sees the challenge; it only gets `invalid_token` when the key is wrong.
 
 #### 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 |
+| Mistral Vibe (Work custom connector) | Connectors → Add Connector → Custom MCP Connector, URL `https://<host>/mcp` | Bearer credential (the shared token or a per-account API key) |
 | 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`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.1-beta.18",
+  "version": "0.2.1-beta.19",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {