catence 0.2.1-beta.17 → 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.17";
+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.17';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.19';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/runtime/console-accounts.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { CatalogPaths } from './catalog.js';
+declare const accountSchema: z.ZodObject<{
+    username: z.ZodString;
+    passwordHash: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>;
+    athletes: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export type ConsoleAccount = z.infer<typeof accountSchema>;
+export type ConsoleAccountRole = ConsoleAccount['role'];
+export type ConsoleAccountScope = {
+    role: ConsoleAccountRole;
+    athleteIds: string[] | 'all';
+};
+export declare function consoleAccountsPath(paths: CatalogPaths): string;
+/**
+ * Read and strictly validate the Console accounts store. A missing file is an
+ * empty store; any other read or validation problem throws so callers fail
+ * closed instead of silently dropping accounts.
+ */
+export declare function loadConsoleAccounts(paths: CatalogPaths): ConsoleAccount[];
+/**
+ * The athlete scope one account may act for, or null when the username is not
+ * stored. An admin holding a grant list instead of "all" keeps the list (fail
+ * safe); any account holding "all" sees every athlete.
+ */
+export declare function resolveAccountScope(paths: CatalogPaths, username: string): ConsoleAccountScope | null;
+/** True when the scope grants this athlete: "all", or the id is listed. */
+export declare function scopeAllowsAthlete(athleteIds: string[] | 'all', athleteId: string): boolean;
+/**
+ * Verify a Console account password against its stored bcrypt hash (the
+ * OAuth consent login). Fail closed: a missing account, a malformed store, or
+ * a malformed hash all return false. bcryptjs is imported lazily so the stdio
+ * path never loads it. The password is verified, never logged or stored.
+ */
+export declare function verifyAccountPassword(paths: CatalogPaths, username: string, password: string): Promise<boolean>;
+/**
+ * Narrow an athlete roster to a scope, mirroring the Console's filter_roster:
+ * "all" returns the roster unchanged; otherwise only granted athletes remain
+ * and the default moves to the first visible athlete (or "" when none).
+ */
+export declare function filterRosterToScope<Athlete extends {
+    id: string;
+}>(athletes: Athlete[], defaultAthleteId: string, athleteIds: string[] | 'all'): {
+    athletes: Athlete[];
+    defaultAthleteId: string;
+};
+export {};

package/dist/core/runtime/console-accounts.js

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+const usernameSchema = z.string().regex(/^[A-Za-z0-9._-]{1,64}$/, 'must be 1-64 characters of letters, digits, dots, underscores, or hyphens');
+const athleteIdSchema = z.string().regex(/^[a-z][a-z0-9-]{0,62}$/, 'must use lowercase letters, digits, and hyphens, starting with a letter');
+const accountSchema = z.object({
+    username: usernameSchema,
+    passwordHash: z.string().startsWith('$2', "must be a bcrypt hash starting with '$2'"),
+    role: z.enum(['admin', 'member']),
+    athletes: z.union([z.literal('all'), z.array(athleteIdSchema)]),
+    createdAt: z.string().min(1).refine((value) => !Number.isNaN(Date.parse(value)), 'must be an ISO timestamp'),
+}).strict();
+const accountsSchema = z.object({
+    formatVersion: z.literal(1),
+    accounts: z.array(accountSchema),
+}).strict().superRefine((store, context) => {
+    const usernames = store.accounts.map((account) => account.username);
+    if (new Set(usernames).size !== usernames.length)
+        context.addIssue({ code: 'custom', path: ['accounts'], message: 'account usernames must be unique' });
+});
+export function consoleAccountsPath(paths) {
+    return path.join(paths.console, 'accounts.json');
+}
+/**
+ * Read and strictly validate the Console accounts store. A missing file is an
+ * empty store; any other read or validation problem throws so callers fail
+ * closed instead of silently dropping accounts.
+ */
+export function loadConsoleAccounts(paths) {
+    const filePath = consoleAccountsPath(paths);
+    let contents;
+    try {
+        contents = readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new Error(`Cannot read Console accounts at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return accountsSchema.parse(JSON.parse(contents)).accounts;
+    }
+    catch (error) {
+        throw new Error(`Invalid Console accounts at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * The athlete scope one account may act for, or null when the username is not
+ * stored. An admin holding a grant list instead of "all" keeps the list (fail
+ * safe); any account holding "all" sees every athlete.
+ */
+export function resolveAccountScope(paths, username) {
+    const account = loadConsoleAccounts(paths).find((entry) => entry.username === username);
+    if (!account)
+        return null;
+    return { role: account.role, athleteIds: account.athletes === 'all' ? 'all' : account.athletes };
+}
+/** True when the scope grants this athlete: "all", or the id is listed. */
+export function scopeAllowsAthlete(athleteIds, athleteId) {
+    return athleteIds === 'all' || athleteIds.includes(athleteId);
+}
+/**
+ * Verify a Console account password against its stored bcrypt hash (the
+ * OAuth consent login). Fail closed: a missing account, a malformed store, or
+ * a malformed hash all return false. bcryptjs is imported lazily so the stdio
+ * path never loads it. The password is verified, never logged or stored.
+ */
+export async function verifyAccountPassword(paths, username, password) {
+    if (!username || !password)
+        return false;
+    let account;
+    try {
+        account = loadConsoleAccounts(paths).find((entry) => entry.username === username);
+    }
+    catch {
+        return false;
+    }
+    if (!account)
+        return false;
+    const { default: bcrypt } = await import('bcryptjs');
+    try {
+        return await bcrypt.compare(password, account.passwordHash);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Narrow an athlete roster to a scope, mirroring the Console's filter_roster:
+ * "all" returns the roster unchanged; otherwise only granted athletes remain
+ * and the default moves to the first visible athlete (or "" when none).
+ */
+export function filterRosterToScope(athletes, defaultAthleteId, athleteIds) {
+    if (athleteIds === 'all')
+        return { athletes, defaultAthleteId };
+    const visible = athletes.filter((athlete) => athleteIds.includes(athlete.id));
+    const visibleIds = visible.map((athlete) => athlete.id);
+    return {
+        athletes: visible,
+        defaultAthleteId: visibleIds.includes(defaultAthleteId) ? defaultAthleteId : (visibleIds[0] ?? ''),
+    };
+}
+//# sourceMappingURL=console-accounts.js.map

package/dist/core/runtime/mcp-keys.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import type { ConsoleAccountScope } from './console-accounts.js';
+declare const keySchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    account: z.ZodString;
+    tokenHash: z.ZodString;
+    createdAt: z.ZodString;
+    revokedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const registrySchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    keys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        account: z.ZodString;
+        tokenHash: z.ZodString;
+        createdAt: z.ZodString;
+        revokedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The stored key record; tokenHash is the SHA-256 hex digest of the raw token. */
+export type McpKeyRecord = z.infer<typeof keySchema>;
+/** The public key view: the stored record without the token hash. */
+export type McpKeySummary = Omit<McpKeyRecord, 'tokenHash'>;
+export type McpKeyRegistry = z.infer<typeof registrySchema>;
+export type McpKeyPrincipal = ConsoleAccountScope & {
+    account: string;
+};
+export declare class McpKeyNotFoundError extends Error {
+}
+type AccountScopeResolver = (username: string) => ConsoleAccountScope | null;
+/** The number of non-revoked keys; a missing or malformed registry counts zero. */
+export declare function countActiveMcpKeys(keysFile: string): number;
+/**
+ * Create a per-account key. The raw token is generated here, stored only as a
+ * SHA-256 hex digest, and returned exactly once.
+ */
+export declare function addMcpKey(keysFile: string, input: {
+    account: string;
+    label?: string;
+}): Promise<{
+    record: McpKeyRecord;
+    token: string;
+}>;
+/** All keys without their token hashes; a missing registry lists as empty. */
+export declare function listMcpKeys(keysFile: string): Promise<McpKeySummary[]>;
+/** Revoke a key by id. Revoking an already-revoked key is a no-op. */
+export declare function revokeMcpKey(keysFile: string, id: string): Promise<McpKeyRecord>;
+/**
+ * Replace a key's token: same id, account, and label, revokedAt cleared, and a
+ * new raw token returned exactly once. The previous token stops resolving.
+ */
+export declare function rollMcpKey(keysFile: string, id: string): Promise<{
+    record: McpKeyRecord;
+    token: string;
+}>;
+/**
+ * Resolve a raw bearer token to the key's account principal, or null when the
+ * token matches nothing. Comparison is timing-safe over the fixed-length
+ * SHA-256 hex digests. Fail closed: an unreadable or malformed registry, a
+ * revoked key, or a key whose account no longer exists all resolve to null.
+ */
+export declare function resolveKeyPrincipal(keysFile: string, rawToken: string, resolveAccount: AccountScopeResolver): McpKeyPrincipal | null;
+export {};

package/dist/core/runtime/mcp-keys.js

@@ -0,0 +1,171 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+const MCP_KEYS_FORMAT_VERSION = 1;
+const accountSchema = z.string().regex(/^[A-Za-z0-9._-]{1,64}$/, 'must be 1-64 characters of letters, digits, dots, underscores, or hyphens');
+const keySchema = z.object({
+    id: z.string().regex(/^[0-9a-f]{32}$/, 'must be a 32-character hex id'),
+    label: z.string().trim().min(1).max(120),
+    account: accountSchema,
+    tokenHash: z.string().regex(/^[0-9a-f]{64}$/, 'must be a SHA-256 hex digest'),
+    createdAt: z.string().datetime(),
+    revokedAt: z.string().datetime().optional(),
+}).strict();
+const registrySchema = z.object({
+    formatVersion: z.literal(MCP_KEYS_FORMAT_VERSION),
+    keys: z.array(keySchema),
+}).strict();
+export class McpKeyNotFoundError extends Error {
+}
+function hashToken(rawToken) {
+    return createHash('sha256').update(rawToken, 'utf8').digest('hex');
+}
+function newToken() {
+    return randomBytes(32).toString('hex');
+}
+function newKeyId() {
+    return randomBytes(16).toString('hex');
+}
+function emptyRegistry() {
+    return { formatVersion: MCP_KEYS_FORMAT_VERSION, keys: [] };
+}
+/** Strict registry read for mutations and listings: malformed fails loudly. */
+async function loadRegistry(keysFile) {
+    const contents = await readFile(keysFile, 'utf8').catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return null;
+    });
+    if (contents === null)
+        return emptyRegistry();
+    try {
+        return registrySchema.parse(JSON.parse(contents));
+    }
+    catch (error) {
+        throw new Error(`Invalid MCP key registry at ${keysFile}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function writeRegistry(keysFile, registry) {
+    await mkdir(path.dirname(keysFile), { recursive: true, mode: 0o700 });
+    const temporary = `${keysFile}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(registry, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, keysFile);
+}
+const registryCache = new Map();
+/**
+ * The parsed registry for resolution, cached by file mtime so revocations and
+ * rollovers are picked up without a restart. A missing file is an empty
+ * registry; an unreadable or malformed one resolves to null (fail closed).
+ */
+function readRegistryCached(keysFile) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(keysFile).mtimeMs;
+    }
+    catch {
+        registryCache.set(keysFile, { mtimeMs: 0, registry: emptyRegistry() });
+        return emptyRegistry();
+    }
+    const cached = registryCache.get(keysFile);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.registry;
+    let registry = null;
+    try {
+        registry = registrySchema.parse(JSON.parse(readFileSync(keysFile, 'utf8')));
+    }
+    catch {
+        registry = null;
+    }
+    registryCache.set(keysFile, { mtimeMs, registry });
+    return registry;
+}
+/** The number of non-revoked keys; a missing or malformed registry counts zero. */
+export function countActiveMcpKeys(keysFile) {
+    const registry = readRegistryCached(keysFile);
+    if (!registry)
+        return 0;
+    return registry.keys.filter((key) => key.revokedAt === undefined).length;
+}
+function findKey(registry, id) {
+    const key = registry.keys.find((entry) => entry.id === id);
+    if (!key)
+        throw new McpKeyNotFoundError(`Unknown MCP key ${id}.`);
+    return key;
+}
+/**
+ * Create a per-account key. The raw token is generated here, stored only as a
+ * SHA-256 hex digest, and returned exactly once.
+ */
+export async function addMcpKey(keysFile, input) {
+    const account = accountSchema.parse(input.account);
+    const label = (input.label ?? `${account} key`).trim();
+    if (!label)
+        throw new Error('Key label is required.');
+    if (label.length > 120)
+        throw new Error('Key label must be at most 120 characters.');
+    const registry = await loadRegistry(keysFile);
+    const id = newKeyId();
+    if (registry.keys.some((key) => key.id === id))
+        throw new Error(`MCP key id ${id} already exists.`);
+    const token = newToken();
+    const record = { id, label, account, tokenHash: hashToken(token), createdAt: new Date().toISOString() };
+    await writeRegistry(keysFile, { ...registry, keys: [...registry.keys, record] });
+    return { record, token };
+}
+/** All keys without their token hashes; a missing registry lists as empty. */
+export async function listMcpKeys(keysFile) {
+    const registry = await loadRegistry(keysFile);
+    return registry.keys.map(({ tokenHash: _tokenHash, ...summary }) => summary);
+}
+/** Revoke a key by id. Revoking an already-revoked key is a no-op. */
+export async function revokeMcpKey(keysFile, id) {
+    const registry = await loadRegistry(keysFile);
+    const key = findKey(registry, id);
+    if (key.revokedAt !== undefined)
+        return key;
+    const revoked = { ...key, revokedAt: new Date().toISOString() };
+    await writeRegistry(keysFile, { ...registry, keys: registry.keys.map((entry) => (entry.id === id ? revoked : entry)) });
+    return revoked;
+}
+/**
+ * Replace a key's token: same id, account, and label, revokedAt cleared, and a
+ * new raw token returned exactly once. The previous token stops resolving.
+ */
+export async function rollMcpKey(keysFile, id) {
+    const registry = await loadRegistry(keysFile);
+    const key = findKey(registry, id);
+    const token = newToken();
+    const rolled = { ...key, tokenHash: hashToken(token), revokedAt: undefined };
+    await writeRegistry(keysFile, { ...registry, keys: registry.keys.map((entry) => (entry.id === id ? rolled : entry)) });
+    return { record: rolled, token };
+}
+/**
+ * Resolve a raw bearer token to the key's account principal, or null when the
+ * token matches nothing. Comparison is timing-safe over the fixed-length
+ * SHA-256 hex digests. Fail closed: an unreadable or malformed registry, a
+ * revoked key, or a key whose account no longer exists all resolve to null.
+ */
+export function resolveKeyPrincipal(keysFile, rawToken, resolveAccount) {
+    if (!rawToken)
+        return null;
+    const registry = readRegistryCached(keysFile);
+    if (!registry)
+        return null;
+    const received = Buffer.from(hashToken(rawToken), 'utf8');
+    for (const key of registry.keys) {
+        if (key.revokedAt !== undefined)
+            continue;
+        const expected = Buffer.from(key.tokenHash, 'utf8');
+        // timingSafeEqual throws on length mismatch, so compare sizes first.
+        if (received.length !== expected.length || !timingSafeEqual(received, expected))
+            continue;
+        const scope = resolveAccount(key.account);
+        if (!scope)
+            return null;
+        return { account: key.account, role: scope.role, athleteIds: scope.athleteIds };
+    }
+    return null;
+}
+//# sourceMappingURL=mcp-keys.js.map

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

@@ -0,0 +1,44 @@
+import type { AccessToken, AuthorizationCode, ClientIdMetadataDocument, GrantId, OAuthServerModel, RefreshToken } from 'mcp-oauth-server';
+import type { OAuthClientInformationFull } from 'mcp-oauth-server';
+export declare class FileOAuthServerModel implements OAuthServerModel {
+    private readonly root;
+    constructor(root: string);
+    private clientFile;
+    private codeFile;
+    private accessTokenFile;
+    private refreshTokenFile;
+    private cimdFile;
+    getClient(clientId: string): Promise<OAuthClientInformationFull | undefined>;
+    registerClient(client: OAuthClientInformationFull): Promise<OAuthClientInformationFull>;
+    saveAuthorizationCode(code: AuthorizationCode, _client: OAuthClientInformationFull): Promise<void>;
+    /**
+     * 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.
+     */
+    consumeAuthorizationCode(authorizationCode: string, clientId: string): Promise<AuthorizationCode | undefined>;
+    revokeAuthorizationCode(authorizationCode: string): Promise<void>;
+    saveAccessToken(token: AccessToken, _client: OAuthClientInformationFull): Promise<void>;
+    getAccessToken(accessToken: string): Promise<AccessToken | undefined>;
+    /**
+     * Revoke only when the token was issued to the requesting client; never
+     * throw when nothing matches (RFC 7009 §2.2 answers 200 either way).
+     */
+    revokeAccessToken(accessToken: string, clientId: string): Promise<AccessToken | undefined>;
+    saveRefreshToken(token: RefreshToken, _client: OAuthClientInformationFull): Promise<void>;
+    revokeRefreshToken(refreshToken: string, clientId: string): Promise<RefreshToken | undefined>;
+    /** Refresh tokens rotate on every use, so consume is atomic + client-scoped like the code consume. */
+    consumeRefreshToken(refreshToken: string, clientId: string): Promise<RefreshToken | undefined>;
+    /** Sweep every access and refresh token belonging to one authorization grant. */
+    revokeGrant(grantId: GrantId): Promise<void>;
+    saveClientIdMetadataDocument(document: ClientIdMetadataDocument): Promise<void>;
+    getClientIdMetadataDocument(clientId: string): Promise<ClientIdMetadataDocument | undefined>;
+    private static tokenRecord;
+    private static accessToken;
+    private static refreshToken;
+    private consumeRecord;
+    private revokeTokenRecord;
+}
+/** The file-backed OAuth server model rooted at <catalogHome>/oauth. */
+export declare function createFileOAuthServerModel(oauthRoot: string): OAuthServerModel;