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

package/dist/core/runtime/oauth/model.js

@@ -0,0 +1,341 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+/**
+ * File-backed OAuthServerModel for the mcp-oauth-server package.
+ *
+ * Layout under <catalogHome>/oauth/ (directory 0700, files 0600, atomic
+ * tmp+rename writes, mirroring mcp-keys.ts):
+ *
+ *   clients/<clientId>.json          registered client (clientId is a UUID)
+ *   codes/<sha256(code)>.json        authorization code (raw code never at rest)
+ *   access/<sha256(token)>.json      access token (raw token never at rest)
+ *   refresh/<sha256(token)>.json     refresh token (raw token never at rest)
+ *   cimd/<sha256(clientIdUrl)>.json  cached client id metadata document
+ *
+ * Every path component is either a validated UUID or a SHA-256 hex digest, so
+ * no record id reaches the filesystem unvalidated. Records are immutable once
+ * written; consume operations claim a record with an atomic rename before
+ * deleting it, so exactly one concurrent caller wins. Expired records are
+ * swept on read; malformed records fail closed (undefined) and are removed.
+ */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const uuidSchema = z.string().regex(UUID_PATTERN, 'must be a UUID');
+const isoTimestampSchema = z.string().datetime();
+// The RFC 7591 metadata fields the lib persists on a client. Registered
+// clients key them by a UUID client_id; a cached Client ID Metadata Document
+// keys them by the document URL instead (see cimdClientRecordSchema).
+const clientMetadataFields = {
+    redirect_uris: z.array(z.string()),
+    token_endpoint_auth_method: z.string().optional(),
+    grant_types: z.array(z.string()).optional(),
+    response_types: z.array(z.string()).optional(),
+    application_type: z.string().optional(),
+    client_name: z.string().optional(),
+    client_uri: z.string().optional(),
+    logo_uri: z.string().optional(),
+    scope: z.string().optional(),
+    contacts: z.array(z.string()).optional(),
+    tos_uri: z.string().optional(),
+    policy_uri: z.string().optional(),
+    jwks_uri: z.string().optional(),
+    jwks: z.any().optional(),
+    software_id: z.string().optional(),
+    software_version: z.string().optional(),
+    // The lib's OAuthClientMetadataSchema passes software_statement through to
+    // the stored client; the strict record schema must accept it too.
+    software_statement: z.string().optional(),
+};
+const clientRecordSchema = z.object({
+    ...clientMetadataFields,
+    client_id: uuidSchema,
+    client_secret: z.string().optional(),
+    client_id_issued_at: z.number().optional(),
+    client_secret_expires_at: z.number().optional(),
+}).strict();
+// A cached CIMD document's client_id is the document URL, not a UUID. The
+// record is keyed by the hash of that URL, never by the id itself.
+const cimdClientRecordSchema = z.object({
+    ...clientMetadataFields,
+    client_id: z.string().min(1),
+    client_secret: z.string().optional(),
+    client_id_issued_at: z.number().optional(),
+    client_secret_expires_at: z.number().optional(),
+}).strict();
+const authorizationCodeRecordSchema = z.object({
+    clientId: uuidSchema,
+    userId: z.string(),
+    expiresAt: isoTimestampSchema,
+    scopes: z.array(z.string()),
+    resource: z.string().optional(),
+    codeChallenge: z.string(),
+    redirectUri: z.string(),
+    state: z.string().optional(),
+    grantId: uuidSchema.optional(),
+}).strict();
+const tokenRecordSchema = z.object({
+    clientId: uuidSchema,
+    userId: z.string().optional(),
+    expiresAt: isoTimestampSchema,
+    scopes: z.array(z.string()),
+    resource: z.string().optional(),
+    grantId: uuidSchema.optional(),
+}).strict();
+const clientIdMetadataDocumentRecordSchema = z.object({
+    client: cimdClientRecordSchema,
+    expiresAt: isoTimestampSchema,
+}).strict();
+function hashSecret(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function isExpired(expiresAtIso) {
+    return new Date(expiresAtIso).getTime() <= Date.now();
+}
+async function writeRecord(filePath, record) {
+    await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, filePath);
+}
+/**
+ * Read one record file. A missing file is undefined; a malformed file fails
+ * closed (undefined) and is swept so it cannot linger. Read errors other than
+ * ENOENT propagate: the caller's fail-closed wrapper turns them into a
+ * rejection, never into an anonymous success.
+ */
+async function readRecord(filePath, schema) {
+    let contents;
+    try {
+        contents = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        return schema.parse(JSON.parse(contents));
+    }
+    catch {
+        await unlink(filePath).catch(() => { });
+        return undefined;
+    }
+}
+async function removeRecord(filePath) {
+    await unlink(filePath).catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+    });
+}
+export class FileOAuthServerModel {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    clientFile(clientId) {
+        return path.join(this.root, 'clients', `${clientId}.json`);
+    }
+    codeFile(authorizationCode) {
+        return path.join(this.root, 'codes', `${hashSecret(authorizationCode)}.json`);
+    }
+    accessTokenFile(accessToken) {
+        return path.join(this.root, 'access', `${hashSecret(accessToken)}.json`);
+    }
+    refreshTokenFile(refreshToken) {
+        return path.join(this.root, 'refresh', `${hashSecret(refreshToken)}.json`);
+    }
+    cimdFile(clientId) {
+        return path.join(this.root, 'cimd', `${hashSecret(clientId)}.json`);
+    }
+    async getClient(clientId) {
+        // Validate before any filesystem use: client ids become path components.
+        if (!UUID_PATTERN.test(clientId))
+            return undefined;
+        const record = await readRecord(this.clientFile(clientId), clientRecordSchema);
+        return record;
+    }
+    async registerClient(client) {
+        if (!UUID_PATTERN.test(client.client_id))
+            throw new Error(`Invalid OAuth client id: ${client.client_id}`);
+        await writeRecord(this.clientFile(client.client_id), clientRecordSchema.parse(client));
+        return client;
+    }
+    async saveAuthorizationCode(code, _client) {
+        const record = {
+            clientId: code.clientId,
+            userId: code.userId,
+            expiresAt: code.expiresAt.toISOString(),
+            scopes: code.scopes ?? [],
+            codeChallenge: code.codeChallenge,
+            redirectUri: code.redirectUri,
+            ...(code.resource !== undefined ? { resource: code.resource } : {}),
+            ...(code.state !== undefined ? { state: code.state } : {}),
+            ...(code.grantId !== undefined ? { grantId: code.grantId } : {}),
+        };
+        await writeRecord(this.codeFile(code.authorizationCode), record);
+    }
+    /**
+     * Read + invalidate in one operation, scoped to the client. The rename is
+     * the atomic claim: when several requests present the same code only one
+     * rename succeeds, and the losers see ENOENT and return undefined. A request
+     * from the wrong client consumes nothing.
+     */
+    async consumeAuthorizationCode(authorizationCode, clientId) {
+        const record = await this.consumeRecord(this.codeFile(authorizationCode), clientId, authorizationCodeRecordSchema);
+        if (!record)
+            return undefined;
+        return {
+            authorizationCode,
+            clientId: record.clientId,
+            userId: record.userId,
+            expiresAt: new Date(record.expiresAt),
+            scopes: record.scopes,
+            codeChallenge: record.codeChallenge,
+            redirectUri: record.redirectUri,
+            ...(record.resource !== undefined ? { resource: record.resource } : {}),
+            ...(record.state !== undefined ? { state: record.state } : {}),
+            ...(record.grantId !== undefined ? { grantId: record.grantId } : {}),
+        };
+    }
+    async revokeAuthorizationCode(authorizationCode) {
+        await removeRecord(this.codeFile(authorizationCode));
+    }
+    async saveAccessToken(token, _client) {
+        await writeRecord(this.accessTokenFile(token.token), FileOAuthServerModel.tokenRecord(token));
+    }
+    async getAccessToken(accessToken) {
+        const record = await readRecord(this.accessTokenFile(accessToken), tokenRecordSchema);
+        if (!record)
+            return undefined;
+        if (isExpired(record.expiresAt)) {
+            await removeRecord(this.accessTokenFile(accessToken));
+            return undefined;
+        }
+        return FileOAuthServerModel.accessToken(record, accessToken);
+    }
+    /**
+     * Revoke only when the token was issued to the requesting client; never
+     * throw when nothing matches (RFC 7009 §2.2 answers 200 either way).
+     */
+    async revokeAccessToken(accessToken, clientId) {
+        return this.revokeTokenRecord(this.accessTokenFile(accessToken), accessToken, clientId);
+    }
+    async saveRefreshToken(token, _client) {
+        await writeRecord(this.refreshTokenFile(token.token), FileOAuthServerModel.tokenRecord(token));
+    }
+    async revokeRefreshToken(refreshToken, clientId) {
+        return this.revokeTokenRecord(this.refreshTokenFile(refreshToken), refreshToken, clientId);
+    }
+    /** Refresh tokens rotate on every use, so consume is atomic + client-scoped like the code consume. */
+    async consumeRefreshToken(refreshToken, clientId) {
+        const record = await this.consumeRecord(this.refreshTokenFile(refreshToken), clientId, tokenRecordSchema);
+        if (!record)
+            return undefined;
+        return FileOAuthServerModel.refreshToken(record, refreshToken);
+    }
+    /** Sweep every access and refresh token belonging to one authorization grant. */
+    async revokeGrant(grantId) {
+        if (!grantId)
+            return;
+        for (const directory of ['access', 'refresh']) {
+            const directoryPath = path.join(this.root, directory);
+            let entries;
+            try {
+                entries = await readdir(directoryPath);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            for (const entry of entries) {
+                if (!entry.endsWith('.json'))
+                    continue;
+                const filePath = path.join(directoryPath, entry);
+                const record = await readRecord(filePath, tokenRecordSchema);
+                if (record?.grantId === grantId)
+                    await removeRecord(filePath);
+            }
+        }
+    }
+    async saveClientIdMetadataDocument(document) {
+        // The cache key is a client-supplied URL: hash it so it never becomes a
+        // path component.
+        const record = {
+            client: cimdClientRecordSchema.parse(document.client),
+            expiresAt: document.expiresAt.toISOString(),
+        };
+        await writeRecord(this.cimdFile(document.client.client_id), record);
+    }
+    async getClientIdMetadataDocument(clientId) {
+        const record = await readRecord(this.cimdFile(clientId), clientIdMetadataDocumentRecordSchema);
+        if (!record)
+            return undefined;
+        if (isExpired(record.expiresAt)) {
+            await removeRecord(this.cimdFile(clientId));
+            return undefined;
+        }
+        return { client: record.client, expiresAt: new Date(record.expiresAt) };
+    }
+    static tokenRecord(token) {
+        return {
+            clientId: token.clientId,
+            expiresAt: token.expiresAt.toISOString(),
+            scopes: token.scopes,
+            ...(token.userId !== undefined ? { userId: token.userId } : {}),
+            ...(token.resource !== undefined ? { resource: token.resource } : {}),
+            ...(token.grantId !== undefined ? { grantId: token.grantId } : {}),
+        };
+    }
+    static accessToken(record, token) {
+        return {
+            token,
+            clientId: record.clientId,
+            expiresAt: new Date(record.expiresAt),
+            scopes: record.scopes,
+            ...(record.userId !== undefined ? { userId: record.userId } : {}),
+            ...(record.resource !== undefined ? { resource: record.resource } : {}),
+            ...(record.grantId !== undefined ? { grantId: record.grantId } : {}),
+        };
+    }
+    static refreshToken(record, token) {
+        return FileOAuthServerModel.accessToken(record, token);
+    }
+    async consumeRecord(filePath, clientId, schema) {
+        const record = await readRecord(filePath, schema);
+        if (!record)
+            return undefined;
+        if (record.clientId !== clientId)
+            return undefined;
+        if (isExpired(record.expiresAt)) {
+            await removeRecord(filePath);
+            return undefined;
+        }
+        // Claim the record atomically before deleting it: the rename succeeds for
+        // exactly one caller even when several requests race the same credential.
+        const claimed = `${filePath}.consumed-${randomBytes(6).toString('hex')}`;
+        try {
+            await rename(filePath, claimed);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        await removeRecord(claimed);
+        return record;
+    }
+    async revokeTokenRecord(filePath, token, clientId) {
+        const record = await readRecord(filePath, tokenRecordSchema);
+        if (!record || record.clientId !== clientId)
+            return undefined;
+        await removeRecord(filePath);
+        return FileOAuthServerModel.accessToken(record, token);
+    }
+}
+/** The file-backed OAuth server model rooted at <catalogHome>/oauth. */
+export function createFileOAuthServerModel(oauthRoot) {
+    return new FileOAuthServerModel(oauthRoot);
+}
+//# sourceMappingURL=model.js.map

package/dist/core/runtime/oauth/settings.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+declare const settingsSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    enabled: z.ZodBoolean;
+    publicUrl: z.ZodString;
+}, z.core.$strict>;
+export type McpOauthSettings = z.infer<typeof settingsSchema>;
+export type McpOauthSettingsState = 'ok' | 'missing' | 'invalid';
+export type McpOauthSettingsRead = {
+    state: McpOauthSettingsState;
+    settings: McpOauthSettings | null;
+};
+export type McpOauthSettingsInput = {
+    enabled: boolean;
+    publicUrl?: string;
+};
+/**
+ * Validate the public URL: an absolute https URL with no query string or
+ * fragment (it becomes the advertised OAuth issuer), trailing slashes stripped.
+ * Mirrors the CLI's --public-url rule (cli-options.ts) at the write boundary.
+ */
+export declare function validateOauthPublicUrl(value: string): string;
+/** Validate and normalize a settings write; throws on invalid input (fail loud). */
+export declare function normalizeMcpOauthSettings(input: McpOauthSettingsInput): McpOauthSettings;
+/**
+ * The settings read for resolution, cached by file mtime so Console writes are
+ * picked up without a restart. A missing file is 'missing'; an unreadable or
+ * malformed one is 'invalid' and fails closed downstream.
+ */
+export declare function readMcpOauthSettings(settingsFile: string): McpOauthSettingsRead;
+/** Atomically write validated settings; the write is the only mutation. */
+export declare function writeMcpOauthSettings(settingsFile: string, input: McpOauthSettingsInput): Promise<McpOauthSettings>;
+export {};

package/dist/core/runtime/oauth/settings.js

@@ -0,0 +1,96 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+/**
+ * Console-managed OAuth 2.1 exposure settings, stored at
+ * <catalogHome>/oauth/settings.json (directory 0700, file 0600, atomic
+ * tmp+rename writes, mirroring mcp-keys.ts).
+ *
+ * The file is the runtime override for the startup --oauth/--public-url
+ * (CATENCE_OAUTH_ENABLED/CATENCE_PUBLIC_URL) values: once a valid file exists
+ * it alone decides whether the OAuth 2.1 authorization server is enabled, so
+ * the Console can switch OAuth on and off without a restart. A malformed file
+ * fails closed (disabled) until the Console writes a valid one.
+ */
+const MCP_OAUTH_SETTINGS_FORMAT_VERSION = 1;
+const settingsSchema = z.object({
+    formatVersion: z.literal(MCP_OAUTH_SETTINGS_FORMAT_VERSION),
+    enabled: z.boolean(),
+    // Normalized at write time: absolute https URL, no query/fragment, trailing
+    // slashes stripped; empty when never set.
+    publicUrl: z.string().max(2048),
+}).strict()
+    // An enabled record without a public URL is semantically invalid (the URL is
+    // the advertised issuer); the read fails closed for it like any malformed file.
+    .refine((value) => !value.enabled || value.publicUrl.length > 0, { message: 'enabled requires a publicUrl' });
+/**
+ * Validate the public URL: an absolute https URL with no query string or
+ * fragment (it becomes the advertised OAuth issuer), trailing slashes stripped.
+ * Mirrors the CLI's --public-url rule (cli-options.ts) at the write boundary.
+ */
+export function validateOauthPublicUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('publicUrl must be a valid absolute URL.');
+    }
+    if (url.protocol !== 'https:')
+        throw new Error('publicUrl must use https: the OAuth issuer is advertised publicly.');
+    if (url.search || url.hash)
+        throw new Error('publicUrl must not contain a query string or fragment.');
+    return value.replace(/\/+$/, '');
+}
+/** Validate and normalize a settings write; throws on invalid input (fail loud). */
+export function normalizeMcpOauthSettings(input) {
+    const publicUrl = (input.publicUrl ?? '').trim();
+    if (input.enabled && !publicUrl) {
+        throw new Error('publicUrl is required when OAuth is enabled: the OAuth issuer is the public URL of this server.');
+    }
+    return {
+        formatVersion: MCP_OAUTH_SETTINGS_FORMAT_VERSION,
+        enabled: input.enabled,
+        publicUrl: publicUrl ? validateOauthPublicUrl(publicUrl) : '',
+    };
+}
+const settingsCache = new Map();
+/**
+ * The settings read for resolution, cached by file mtime so Console writes are
+ * picked up without a restart. A missing file is 'missing'; an unreadable or
+ * malformed one is 'invalid' and fails closed downstream.
+ */
+export function readMcpOauthSettings(settingsFile) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(settingsFile).mtimeMs;
+    }
+    catch {
+        const read = { state: 'missing', settings: null };
+        settingsCache.set(settingsFile, { mtimeMs: 0, read });
+        return read;
+    }
+    const cached = settingsCache.get(settingsFile);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.read;
+    let read;
+    try {
+        read = { state: 'ok', settings: settingsSchema.parse(JSON.parse(readFileSync(settingsFile, 'utf8'))) };
+    }
+    catch {
+        read = { state: 'invalid', settings: null };
+    }
+    settingsCache.set(settingsFile, { mtimeMs, read });
+    return read;
+}
+/** Atomically write validated settings; the write is the only mutation. */
+export async function writeMcpOauthSettings(settingsFile, input) {
+    const settings = normalizeMcpOauthSettings(input);
+    await mkdir(path.dirname(settingsFile), { recursive: true, mode: 0o700 });
+    const temporary = `${settingsFile}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, settingsFile);
+    return settings;
+}
+//# sourceMappingURL=settings.js.map

package/dist/elt/ingestion/importer.js

@@ -103,6 +103,10 @@ export async function importJsonl(database, runId, filePath, log) {
             await database.run('ROLLBACK');
         throw error;
     }
+    if (inTransaction) {
+        await database.run('COMMIT');
+        inTransaction = false;
+    }
     const qualityStartedAt = Date.now();
     for (const activityId of pass.deferredQualityActivityIds) {
         await refreshActivityQuality(database, activityId);

package/dist/interfaces/cli/commands.js

@@ -2,8 +2,8 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { defaultBearerTokenPath, disableBearerToken, ensureBearerToken, mcpExposureStatus, readBearerToken, } from '../http/cli-options.js';
-import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, deleteAthleteSecret, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, parseAutoSyncInterval, planSelfUpdate, readAutoSyncSchedule, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, updateAutoSyncSchedule, } from '../../runtime/index.js';
+import { defaultBearerTokenPath, defaultMcpKeysPath, defaultOauthSettingsPath, disableBearerToken, ensureBearerToken, mcpExposureStatus, oauthStatusFromSettings, readBearerToken, } from '../http/cli-options.js';
+import { addAthlete, addMcpKey, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, deleteAthleteSecret, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, listMcpKeys, loadCatalog, npmGlobalPrefix, parseAutoSyncInterval, planSelfUpdate, readAutoSyncSchedule, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, revokeMcpKey, rollMcpKey, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, updateAutoSyncSchedule, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -38,14 +38,26 @@ async function stdinSecret() {
         throw new Error('--value-stdin received an empty secret.');
     return value;
 }
-const mcpCommand = program.command('mcp').description('Manage Streamable HTTP MCP exposure: the bearer-token gate, its token, and endpoint URLs.');
+const mcpCommand = program.command('mcp').description('Manage Streamable HTTP MCP exposure: the bearer-token gate, its token, per-account keys, and endpoint URLs.');
 const mcpLocalEndpoint = () => `http://127.0.0.1:${process.env.CATENCE_HTTP_PORT ?? '8787'}`;
+// The keys registry resolves like the serve option: --file, then the
+// environment, then the catalog home default.
+const mcpKeysFile = (file) => file ?? process.env.CATENCE_MCP_KEYS_FILE ?? defaultMcpKeysPath(currentCatalog().root);
+// The OAuth settings file resolves like the serve option: the environment,
+// then the catalog home default.
+const mcpOauthSettingsFile = () => process.env.CATENCE_OAUTH_SETTINGS_FILE ?? defaultOauthSettingsPath(currentCatalog().root);
 mcpCommand.command('status')
-    .description('Report whether the bearer-token gate is enabled, the token, and the endpoint URLs.')
+    .description('Report whether the bearer-token gate is enabled, the token, the per-account key counts, and the endpoint URLs.')
     .option('--file <path>', 'non-default token file path')
     .action(async (options) => {
     const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
-    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+    const keys = await listMcpKeys(mcpKeysFile());
+    const status = {
+        ...mcpExposureStatus(tokenFile, mcpLocalEndpoint()),
+        keys: { total: keys.length, active: keys.filter((key) => key.revokedAt === undefined).length },
+        oauth: oauthStatusFromSettings(mcpOauthSettingsFile()),
+    };
+    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
 });
 mcpCommand.command('enable')
     .description('Enable the bearer-token gate: generate the token file (mode 0600) if it does not exist.')
@@ -73,6 +85,38 @@ mcpCommand.command('token')
         throw new Error(`MCP exposure is not enabled; run 'catence-data mcp enable' first.`);
     process.stdout.write(`${token}\n`);
 });
+const mcpKeyCommand = mcpCommand.command('key').description('Manage per-account MCP bearer keys; raw tokens are printed exactly once and stored only as hashes.');
+mcpKeyCommand.command('add')
+    .description('Create a per-account MCP key and print its raw token exactly once.')
+    .requiredOption('--account <username>', 'Console account username the key acts for')
+    .option('--label <label>', 'human-readable key label')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (options) => {
+    const { record, token } = await addMcpKey(mcpKeysFile(options.file), { account: options.account, label: options.label });
+    process.stdout.write(`${JSON.stringify({ id: record.id, label: record.label, account: record.account, createdAt: record.createdAt, token }, null, 2)}\n`);
+});
+mcpKeyCommand.command('list')
+    .description('List MCP keys without their token hashes.')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (options) => {
+    process.stdout.write(`${JSON.stringify({ keys: await listMcpKeys(mcpKeysFile(options.file)) }, null, 2)}\n`);
+});
+mcpKeyCommand.command('revoke')
+    .description('Revoke an MCP key by id; its token stops working immediately.')
+    .argument('<id>', 'key id')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (id, options) => {
+    await revokeMcpKey(mcpKeysFile(options.file), id);
+    process.stdout.write(`${JSON.stringify({ revoked: id }, null, 2)}\n`);
+});
+mcpKeyCommand.command('roll')
+    .description('Replace an MCP key’s token and print the new raw token exactly once.')
+    .argument('<id>', 'key id')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (id, options) => {
+    const { record, token } = await rollMcpKey(mcpKeysFile(options.file), id);
+    process.stdout.write(`${JSON.stringify({ id: record.id, label: record.label, account: record.account, createdAt: record.createdAt, token }, null, 2)}\n`);
+});
 program.command('setup')
     .description('Create a home catalog and its first athlete store. Existing 0.1 stores must be re-synced.')
     .option('--athlete <id>', 'first athlete ID')

package/dist/interfaces/http/cli-options.d.ts

@@ -4,11 +4,19 @@ export type ServeCliOptions = {
     port: number;
     allowedOrigins: string[];
     authTokenFile?: string;
+    mcpKeysFile?: string;
+    oauthSettingsFile?: string;
+    oauth: boolean;
+    publicUrl?: string;
     help: boolean;
 };
-export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;\n                             generate/inspect it with 'catence-data mcp enable|token'.\n                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.\n  -h, --help                 Show this help text.";
+export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;\n                             generate/inspect it with 'catence-data mcp enable|token'.\n                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.\n  --mcp-keys-file <path>     Per-account MCP key registry for the HTTP gate. Any active key in it\n                             switches authentication on; manage keys with 'catence-data mcp key'.\n                             Defaults to CATENCE_MCP_KEYS_FILE or <catalog-home>/mcp-keys.json.\n  --oauth                    Run the OAuth 2.1 authorization server (issuer = --public-url) so\n                             ChatGPT/Codex-style MCP clients connect with a per-account consent\n                             login. Requires --public-url. Defaults to CATENCE_OAUTH_ENABLED=1/true.\n                             The Console settings file overrides this at runtime.\n  --public-url <url>         Public https URL of this server (no query string or fragment), e.g.\n                             the tunnel URL. Required when --oauth is enabled.\n                             Defaults to CATENCE_PUBLIC_URL.\n  --oauth-settings-file <path>\n                             Console-managed OAuth settings that override --oauth/--public-url\n                             at runtime. Defaults to CATENCE_OAUTH_SETTINGS_FILE or\n                             <catalog-home>/oauth/settings.json.\n  -h, --help                 Show this help text.";
 /** The canonical token location inside a catalog home. */
 export declare function defaultBearerTokenPath(catalogRoot: string): string;
+/** The canonical per-account MCP key registry location inside a catalog home. */
+export declare function defaultMcpKeysPath(catalogRoot: string): string;
+/** The canonical Console-managed OAuth settings location inside a catalog home. */
+export declare function defaultOauthSettingsPath(catalogRoot: string): string;
 /** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
 export declare function loadBearerToken(filePath: string): string;
 /**
@@ -34,6 +42,31 @@ export type McpExposureStatus = {
     endpoint: string;
     healthEndpoint: string;
     token?: string;
+    oauth?: {
+        enabled: boolean;
+        publicUrl?: string;
+    };
+};
+export declare function mcpExposureStatus(filePath: string, endpointBase: string, oauth?: {
+    enabled: boolean;
+    publicUrl?: string;
+}): McpExposureStatus;
+/** True when CATENCE_OAUTH_ENABLED is 1/true. */
+export declare function oauthEnabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/** The OAuth exposure reported by `catence-data mcp status`, read from the environment. */
+export declare function oauthStatusFromEnv(env?: NodeJS.ProcessEnv): {
+    enabled: boolean;
+    publicUrl?: string;
+};
+export type McpOauthStatusSource = 'console' | 'environment' | 'disabled';
+/**
+ * The effective OAuth exposure: the Console settings file when a valid one
+ * exists (a malformed one fails closed to disabled), else the environment.
+ * `source` records where the effective values come from.
+ */
+export declare function oauthStatusFromSettings(settingsFile: string, env?: NodeJS.ProcessEnv): {
+    enabled: boolean;
+    publicUrl?: string;
+    source: McpOauthStatusSource;
 };
-export declare function mcpExposureStatus(filePath: string, endpointBase: string): McpExposureStatus;
 export declare function parseServeCliOptions(arguments_: readonly string[]): ServeCliOptions;