@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/shared/mcp-contract/types.ts

@@ -55,9 +55,13 @@ export type McpControlCaller = {
 // --------------------------- the authorization vocabulary ---------------------------
 
 /**
- * The complete vocabulary of scopes a personal access token may be issued with,
- * per mcp-gateway-SPEC. `cloudcli:admin` is deliberately absent: it is reserved
- * and cannot be minted.
+ * The CANONICAL scope names: the stable internal vocabulary every stored grant,
+ * tool `requiredScope` and principal comparison uses. Since 3.0 it is no longer
+ * the wire vocabulary — a client issues `cloudpit:*` (see
+ * {@link CLOUDPIT_ACCESS_TOKEN_SCOPES} and {@link ACCEPTED_ACCESS_TOKEN_SCOPES})
+ * and {@link canonicalScope} maps it onto this table.
+ *
+ * `cloudcli:admin` is deliberately absent: it is reserved and cannot be minted.
  *
  * Re-homed verbatim from `server/modules/oauth/access-tokens.service.ts`
  * (proposal `docs/proposals/mcp-gateway-tool-architecture.md` stage 1) so a
@@ -99,10 +103,13 @@ export const ACCESS_TOKEN_SCOPES = [
 ] as const;
 
 /**
- * The Cloudpit spellings of the same eight scopes. Nothing migrates stored tokens:
- * both vocabularies are accepted on issue, and every comparison goes through
- * {@link canonicalScope} so an old `requiredScopes` literal keeps matching a new
- * `cloudpit:*` token (and vice versa).
+ * The Cloudpit spellings of the same eight scopes: the wire vocabulary a client
+ * asks for, the AS metadata advertises and the consent screen offers.
+ *
+ * Stored tokens are NOT migrated: an old token carries the canonical
+ * `cloudcli:*` strings in its row and still verifies, which is the 3.0 policy
+ * stated in the release notes. Only the INPUT vocabulary narrowed — a request
+ * naming a legacy spelling is refused.
  */
 export const CLOUDPIT_SCOPE_PREFIX = 'cloudpit:';
 const CLOUDCLI_SCOPE_PREFIX = 'cloudcli:';
@@ -111,16 +118,14 @@ export const CLOUDPIT_ACCESS_TOKEN_SCOPES: readonly string[] = ACCESS_TOKEN_SCOP
   (scope) => `${CLOUDPIT_SCOPE_PREFIX}${scope.slice(CLOUDCLI_SCOPE_PREFIX.length)}`,
 );
 
-/** Every accepted spelling: the eight legacy names followed by the eight Cloudpit names. */
-export const ACCEPTED_ACCESS_TOKEN_SCOPES: readonly string[] = [
-  ...ACCESS_TOKEN_SCOPES,
-  ...CLOUDPIT_ACCESS_TOKEN_SCOPES,
-];
+/** The one accepted spelling at issue time: the eight Cloudpit names. */
+export const ACCEPTED_ACCESS_TOKEN_SCOPES: readonly string[] = [...CLOUDPIT_ACCESS_TOKEN_SCOPES];
 
 /**
- * Maps either spelling onto the legacy canonical one. The stored/compared value stays
- * `cloudcli:*` because it is the key existing grants, tool `requiredScopes` and the
- * observation/DB rows already use; only the accepted INPUT vocabulary widened.
+ * Maps the wire spelling onto the canonical one. The stored/compared value
+ * stays `cloudcli:*` because it is the key existing grants, tool `requiredScopes`
+ * and the observation/DB rows already use. A canonical value passes through
+ * unchanged, so an old token still matches a required scope.
  */
 export function canonicalScope(scope: string): string {
   return scope.startsWith(CLOUDPIT_SCOPE_PREFIX)

package/server/shared/ports/codex-provider-registry.port.ts

@@ -0,0 +1,133 @@
+/**
+ * The neutral accessor for the project-owned Codex upstream-provider registry.
+ *
+ * WHY THIS FILE EXISTS. `provider-models.service.ts` must refuse a custom Codex
+ * model entry whose `codexProviderId` names no provider the project actually
+ * defines. Naming the settings module directly from the providers module would
+ * close the `providers -> settings -> mcp-gateway -> providers` directory cycle
+ * AC-394 pins (the settings barrel evaluates `settings.module.ts`, which imports
+ * the MCP gateway, which imports the providers barrel). The registry reading is
+ * needed when a model is written, not while either module evaluates, so it is
+ * installed rather than imported: the shared layer imports no feature module,
+ * and the composition root wires the two ends together.
+ *
+ * WHAT THE PORT ANSWERS. `read()` returns the ids the project registry defines
+ * plus the ids Codex itself reserves for its built-ins. Both are data, not
+ * vocabulary this file re-states: the settings source owns the reserved list
+ * (`RESERVED_CODEX_PROVIDER_IDS`) and the provider entries, so a change there
+ * reaches every caller without a second copy drifting.
+ *
+ * A MISSING INSTALL IS NOT AN ERROR. A focused criterion that drives the models
+ * service over an injected fake never installs this port; the service treats an
+ * absent install as "no provider is known" and refuses a declared binding with
+ * a readable error. In production `settings.module.ts` installs the real source
+ * at boot, and `read()` re-reads the settings file on every call, so a provider
+ * added or removed through the settings API is seen by the next model write.
+ *
+ * Consumers: `modules/providers/services/provider-models.service.ts` (the
+ * `codexProviderId` reference check), `modules/providers/list/codex/` (the
+ * per-run spawn-time `resolve`), and `modules/settings/settings.module.ts`
+ * (installs the production reading and resolution).
+ */
+
+/** One provider id the project registry defines; the model entry binds by id only. */
+export type CodexProviderIdEntry = { id: string };
+
+/**
+ * The registry reading a model-entry validation needs: the project providers and
+ * the built-in ids Codex always accepts.
+ */
+export type CodexProviderRegistryReading = {
+  /** Provider ids the project settings file defines, as the registry read them. */
+  providers: CodexProviderIdEntry[];
+  /** Ids Codex reserves for its built-in providers; a project entry may never replace one. */
+  reservedIds: readonly string[];
+};
+
+/**
+ * One provider resolved for a spawn-time injection: the endpoint fields Codex's
+ * `model_providers.<id>` config needs plus the secret read from its token file.
+ *
+ * The secret is handed to the caller in memory, under the provider's `envKey`;
+ * it never appears in a config document or on a command line.
+ */
+export type ResolvedCodexUpstreamProvider = {
+  id: string;
+  name: string;
+  baseUrl: string;
+  envKey: string;
+  wireApi: 'responses';
+  secret: string;
+  /** Codex `[model_providers.<id>]` connection settings, when the entry declares them. */
+  httpHeaders?: Record<string, string>;
+  envHttpHeaders?: Record<string, string>;
+  queryParams?: Record<string, string>;
+  requestMaxRetries?: number;
+  streamMaxRetries?: number;
+  streamIdleTimeoutMs?: number;
+  modelCatalogUrl?: string;
+  /** Top-level Codex `model_context_window` / auto-compact overrides for this provider. */
+  modelContextWindow?: number;
+  modelAutoCompactTokenLimit?: number;
+};
+
+/**
+ * A spawn-time lookup. A false `ok` always carries the readable line a run
+ * reports instead of silently dialling Codex's default endpoint.
+ */
+export type CodexUpstreamProviderResolution =
+  | { ok: true; provider: ResolvedCodexUpstreamProvider }
+  | { ok: false; problem: string };
+
+/**
+ * The registry surface the providers module reads.
+ *
+ * `read()` answers the model-write reference check; `resolve()` is the
+ * per-run/resident spawn-time lookup. `resolve` is optional so an install that
+ * only answers reference checks keeps working; a Codex run that needs an
+ * injection treats its absence as "the registry cannot resolve providers".
+ */
+export type CodexProviderRegistryPort = {
+  read(): CodexProviderRegistryReading;
+  resolve?(id: string): CodexUpstreamProviderResolution;
+};
+
+/**
+ * The installed port behind a lifecycle owner rather than a module-scope `let`.
+ *
+ * It holds one reference with one write path (`install`) and one read path, so
+ * the process-wide wiring is explicit and the architecture ratchet sees no
+ * module-level mutable binding.
+ */
+class CodexProviderRegistrySlot {
+  #installed: CodexProviderRegistryPort | null = null;
+
+  install(port: CodexProviderRegistryPort): void {
+    this.#installed = port;
+  }
+
+  read(): CodexProviderRegistryPort | null {
+    return this.#installed;
+  }
+}
+
+const codexProviderRegistrySlot = new CodexProviderRegistrySlot();
+
+/**
+ * Installs the process's Codex provider registry reading.
+ *
+ * Called once by `settings.module.ts` at boot. Re-installing replaces the port,
+ * which is what a criterion driving a fake relies on; production installs once.
+ */
+export function installCodexProviderRegistryPort(port: CodexProviderRegistryPort): void {
+  codexProviderRegistrySlot.install(port);
+}
+
+/**
+ * Reads the installed registry, or null when the composition root has not wired
+ * one yet. Callers treat null as "no provider is known" rather than throwing, so
+ * merely evaluating the models service never depends on settings-module order.
+ */
+export function readCodexProviderRegistryPort(): CodexProviderRegistryPort | null {
+  return codexProviderRegistrySlot.read();
+}

package/server/shared/ports/session-blocked-events.port.ts

@@ -36,7 +36,7 @@ export type SessionBlockedReason = 'approval' | 'failed' | 'interrupted';
 /**
  * One blocked session.
  *
- * `session` is the CloudCLI application session id. `blockId` is `<sessionId>:<requestId|turnId>`
+ * `session` is the Cloudpit application session id. `blockId` is `<sessionId>:<requestId|turnId>`
  * and is the identity a later `session.blocked.resolved` names. The approval arm carries
  * `requestId`/`toolName` (plus `question` when the protocol states one); the turn arm carries
  * `turnId` (plus `errorMessage` on `failed` only).

package/server/shared/ports/session-run-events.port.ts

@@ -31,7 +31,7 @@ export type SessionRunOutcome = 'completed' | 'aborted' | 'failed';
 /** One completed run: which session, which run, how it ended, and when. */
 export type SessionRunEndedEvent = {
   kind: 'session.run.ended';
-  /** The CloudCLI application session id. */
+  /** The Cloudpit application session id. */
   session: string;
   /** The run id the shared registry minted for this turn. */
   runId: string;
@@ -51,7 +51,7 @@ export type SessionRunEndedEvent = {
  */
 export type SessionClosedEvent = {
   kind: 'session.closed';
-  /** The CloudCLI application session id. */
+  /** The Cloudpit application session id. */
   session: string;
   /** Why the session is closed; see above. */
   reason: string;

package/server/shared/settings-file.ts

@@ -16,18 +16,29 @@
  * THE READING IS NEVER FATAL. A missing default file is the ordinary "feature
  * off" state; a missing explicitly named file, a malformed document or a
  * malformed block field is named in `problems` and the caller's shipped defaults
- * are used. Nothing here throws, because a bad knob must never stop the server.
+ * are used. The readers never throw, because a bad knob must never stop the
+ * server. `readExpectedVersion` is the deliberate exception: it validates a
+ * WRITE's precondition and reports a caller mistake as a 400 `AppError`.
  *
  * Consumers: `modules/quay/counter-voice-settings.ts`,
  * `modules/observation/session-digest-llm-settings.ts`,
  * `modules/reply-suggestions/reply-suggestions-settings.ts` and
  * `modules/architecture/refresh-settings.ts`.
  */
-import { readFileSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { errorMessage, isRecord } from '@/shared/utils.js';
+import { AppError, errorMessage, isRecord } from '@/shared/utils.js';
 
 // ---------------------------- SHARED SHAPES ----------------------------
 
@@ -112,9 +123,11 @@ export function defaultServerSettingsPath(homeDir: string): string {
 }
 
 /**
- * The pre-flip settings location. It is only ever READ (the boot loader falls
- * back to it when the Cloudpit default does not exist yet); a save always
- * targets {@link defaultServerSettingsPath}.
+ * The pre-flip settings location. In v3.0 it is only a ONE-TIME MIGRATION SOURCE:
+ * {@link migrateLegacyServerSettingsFile} copies it to
+ * {@link defaultServerSettingsPath} when the Cloudpit file does not exist yet, and
+ * every reader then reads only the Cloudpit file. A runtime read fallback to this
+ * path was retired with the rest of the 2.x compatibility layer.
  */
 export function legacyServerSettingsPath(homeDir: string): string {
   return path.join(homeDir, '.config', 'claudecodeui', 'server.settings.json');
@@ -366,6 +379,154 @@ export function resolveApiKey(
   return (firstMatch ? unquote(firstMatch[2] ?? '') : unquote(firstLine)).trim();
 }
 
+/**
+ * Write one settings file by replacing it atomically.
+ *
+ * The bytes go to a sibling temp file (same directory, so the rename cannot cross a filesystem)
+ * and are renamed over the target, so a reader never observes a half-written document. Without
+ * an explicit `mode`, an existing file keeps its current permissions and a new file is created
+ * `0600` — settings files can carry operator credentials. Callers that own a secret-bearing file
+ * pass `mode: 0o600` to widen-proof it even when the file already existed.
+ *
+ * Throws the filesystem error unchanged: each caller wraps it in its own domain `AppError`, so
+ * this shared helper does not invent a settings-specific error code.
+ *
+ * Consumers: `settings/server-settings-file.ts` (the cockpit session-start writer) and
+ * `settings/codex-model-providers.store.ts` (the Codex provider settings and secret files).
+ */
+export function writeSettingsFileAtomically(
+  filePath: string,
+  contents: string,
+  options: { mode?: number } = {},
+): void {
+  const directory = path.dirname(filePath);
+  const temporary = path.join(
+    directory,
+    `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  try {
+    mkdirSync(directory, { recursive: true });
+    const mode = options.mode ?? (existsSync(filePath) ? statSync(filePath).mode & 0o777 : 0o600);
+    writeFileSync(temporary, contents, { encoding: 'utf8', mode });
+    renameSync(temporary, filePath);
+  } finally {
+    // The rename consumed the temp name on success; this removes it only after a failed write.
+    try {
+      rmSync(temporary, { force: true });
+    } catch {
+      // A leftover temp file is not a reason to hide the write's own error.
+    }
+  }
+}
+
+// ---------------------------- ONE-TIME MIGRATION ----------------------------
+
+/** What one legacy-settings copy attempt decided. */
+export type LegacyServerSettingsMigration = {
+  /** True only when this call created the Cloudpit file from the legacy one. */
+  migrated: boolean;
+  /**
+   * `copied` — the Cloudpit file was created from the legacy copy;
+   * `target-exists` — the Cloudpit file is already there (idempotent second run);
+   * `no-legacy` — there is no legacy file to copy;
+   * `copy-failed` — the read or write threw; `error` carries the reason.
+   */
+  reason: 'copied' | 'target-exists' | 'no-legacy' | 'copy-failed';
+  /** The failure message for `copy-failed`; never set for the other reasons. */
+  error?: string;
+};
+
+/**
+ * Copy the legacy `~/.config/claudecodeui/server.settings.json` to the Cloudpit
+ * default exactly once.
+ *
+ * v3.0 REPLACEMENT FOR THE READ FALLBACK. Up to 2.x the boot loader read the
+ * legacy file whenever the Cloudpit file was missing, so an upgrade kept its
+ * effective configuration. The runtime fallback is gone; this one-time copy keeps
+ * the upgrade working and then leaves only the Cloudpit file to be read.
+ *
+ * IDEMPOTENT BY CONSTRUCTION. The copy never overwrites: an existing Cloudpit
+ * file is the user's current settings (`target-exists`), so a second run is a
+ * no-op and a save made after the first run is never clobbered. The legacy file
+ * stays on disk untouched.
+ *
+ * The copy goes through {@link writeSettingsFileAtomically} so the new file is
+ * created `0600` and a reader never observes a half-written document. Every
+ * outcome is returned, never thrown: a failed copy must not stop the server.
+ *
+ * Consumers: `modules/settings/server-settings-file.ts`'s target resolver (the
+ * boot path) and the settings criteria.
+ */
+export function migrateLegacyServerSettingsFile(options: {
+  /** The pre-flip file (`~/.config/claudecodeui/server.settings.json`). */
+  legacyPath: string;
+  /** The Cloudpit file (`~/.config/cloudpit/server.settings.json`). */
+  targetPath: string;
+  /** Existence seam; defaults to `node:fs`. */
+  exists?: (filePath: string) => boolean;
+  /** Read seam; defaults to `node:fs` UTF-8. */
+  readFile?: (filePath: string) => string;
+  /** Write seam; defaults to {@link writeSettingsFileAtomically} with mode 0600. */
+  writeTarget?: (filePath: string, contents: string) => void;
+}): LegacyServerSettingsMigration {
+  const exists = options.exists ?? existsSync;
+  if (exists(options.targetPath)) return { migrated: false, reason: 'target-exists' };
+  if (!exists(options.legacyPath)) return { migrated: false, reason: 'no-legacy' };
+
+  try {
+    const readFile = options.readFile ?? ((filePath: string) => readFileSync(filePath, 'utf8'));
+    const writeTarget = options.writeTarget
+      ?? ((filePath: string, contents: string) =>
+        writeSettingsFileAtomically(filePath, contents, { mode: 0o600 }));
+    writeTarget(options.targetPath, readFile(options.legacyPath));
+    return { migrated: true, reason: 'copied' };
+  } catch (failure) {
+    return {
+      migrated: false,
+      reason: 'copy-failed',
+      error: errorMessage(failure),
+    };
+  }
+}
+
+// ---------------------------- SAVE PRECONDITIONS ----------------------------
+
+/**
+ * The version a settings write was based on: the body's `expectedVersion`, else
+ * the `If-Match` header value.
+ *
+ * A save without a version, or with a non-string one, is a caller mistake and is
+ * refused as a 400 `AppError` (`VERSION_REQUIRED` / `INVALID_VERSION`) so a
+ * stale write can never silently overwrite another editor's save. This validates
+ * a REQUEST, not a settings document, so it deliberately throws where the
+ * readers above never do.
+ *
+ * Consumers: `modules/settings/settings.service.ts` (the cockpit session-start
+ * save) and `modules/settings/codex-model-providers.service.ts` (the Codex
+ * upstream provider registry save) — both save contracts require this same
+ * proof before touching their file.
+ */
+export function readExpectedVersion(
+  body: Record<string, unknown>,
+  headerVersion: string | undefined,
+): string {
+  if (body.expectedVersion !== undefined && typeof body.expectedVersion !== 'string') {
+    throw new AppError('expectedVersion must be a string', {
+      code: 'INVALID_VERSION',
+      statusCode: 400,
+    });
+  }
+  const fromBody = typeof body.expectedVersion === 'string' ? body.expectedVersion.trim() : '';
+  const version = fromBody || (headerVersion ?? '').trim();
+  if (!version) {
+    throw new AppError('expectedVersion is required to save', {
+      code: 'VERSION_REQUIRED',
+      statusCode: 400,
+    });
+  }
+  return version;
+}
+
 /**
  * Build a stateful reader over one JSON settings file.
  *