@data-club/ai-hub-server 0.0.1

package/src/routes/admin/settings.ts

@@ -0,0 +1,463 @@
+/**
+ * `/admin/settings/*` — super_admin-only deployment-wide configuration.
+ *
+ * Five endpoints:
+ *
+ * - `GET    /admin/settings` — Letta connection (api key **masked**), theme,
+ *   metrics + signing-key rotation timestamps. Encrypted Letta API key
+ *   surfaces only as `letta_api_key_masked` (`••••••••<last4>`); plaintext
+ *   never leaves the server outside the `Reveal once` flow (Step 12).
+ * - `PATCH  /admin/settings` — body `{ letta_base_url?, letta_ade_url?, letta_api_key?, theme?: { default?, switcher_enabled? } }`.
+ *   API key, when supplied, is encrypted under `AI_HUB_ENCRYPTION_KEY`. Theme
+ *   fields live as **separate columns**, not in `feature_toggles`.
+ * - `GET    /admin/settings/feature-toggles` — flat JSON blob from §8.4.
+ * - `PATCH  /admin/settings/feature-toggles` — merge-patch the same blob.
+ *   Unknown keys are accepted (forward-compat for future toggles).
+ * - `POST   /admin/settings/rotate-signing-key` — replace
+ *   `service_token_signing_key` with random 64 bytes; bump
+ *   `signing_key_rotated_at`. Returns nothing — the key never leaves the
+ *   server. After rotation every outstanding JWT fails signature
+ *   verification (no grace period in v1; the calling super-admin is logged
+ *   out alongside everyone else).
+ * - `POST   /admin/settings/rotate-metrics-token` — generate a new 32-byte
+ *   hex token, bump `metrics_scrape_token_rotated_at`, return
+ *   `{ token: "<new>" }` exactly once in the response. Same one-time-reveal
+ *   pattern as user password reset; subsequent `GET /admin/settings` calls
+ *   do not echo it back.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — settings endpoints
+ * @see SPECIFICATIONS.md §6.7 — signing key rotation
+ * @see SPECIFICATIONS.md §6.10 — metrics token rotation
+ * @see ui-sketches/08-admin-settings.md
+ */
+
+import { randomBytes } from "node:crypto";
+
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { encryptString } from "../../auth/encryption.js";
+import { protectedRoute } from "../../auth/middleware.js";
+import { adminSetting } from "../../db/schema.js";
+import type { AdminSettingRow } from "../../db/schema.js";
+import {
+  internalError,
+  jsonResponse,
+  validationError,
+} from "../../handlers/responses.js";
+import type { RouteHandler } from "../../handlers/types.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Helpers                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** ISO-8601 timestamp with millisecond precision. */
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Computes a privacy-preserving display of the encrypted Letta API key.
+ *
+ * Per [08-admin-settings.md], the UI shows `••••••••` while the value is in
+ * the field — operators reveal-once if they need to copy. The server's
+ * `GET /admin/settings` never returns plaintext.
+ *
+ * @param row - the admin_setting row.
+ * @returns a masked string, or `null` when no key is stored.
+ */
+function maskLettaApiKey(row: AdminSettingRow): string | null {
+  if (!row.lettaApiKeyEncrypted) return null;
+  // We can't decrypt without the key, and decrypting just to show "<last 4>"
+  // would defeat the purpose of encrypting at rest. Use a constant placeholder
+  // so the UI knows a key is configured without revealing length / contents.
+  return "••••••••";
+}
+
+/** Possible sources for the effective Letta API key at runtime. */
+type LettaApiKeySource = "db" | "env" | "none";
+
+/**
+ * Determines the *effective* source of the Letta API key at this moment.
+ * Mirrors `letta/client.ts:resolveApiKey` (DB → env → throw) so the admin
+ * UI can show the truth about which source the runtime will use, not just
+ * what's stored in the DB.
+ *
+ * Returning the SOURCE — not the value — keeps plaintext off the wire.
+ *
+ * @param row - the admin_setting row (may be missing).
+ * @param envSource - env-var record from the server context. Lets tests
+ *   exercise the source-resolution without touching the real `process.env`.
+ * @returns `"db"` when DB column has a non-empty value (the runtime will
+ *   use it); `"env"` when DB is empty AND `LETTA_API_KEY` in `envSource`
+ *   is set and non-empty; `"none"` otherwise.
+ */
+function resolveApiKeySource(
+  row: AdminSettingRow | null,
+  envSource: Record<string, string | undefined>,
+): LettaApiKeySource {
+  // We deliberately can't tell here whether the DB-encrypted bytes decrypt
+  // to a non-whitespace string without doing the decrypt — but the rule is
+  // "non-empty bytes ⇒ candidate." The runtime resolver does the actual
+  // whitespace check; the UI source is just "is there a DB value worth
+  // showing?" The mismatch (DB has whitespace-only after decrypt) is rare
+  // enough that we don't pay the cost of decrypting here just to detect
+  // it; `letta_api_key_set` aligned with `lettaApiKeyEncrypted IS NOT NULL`
+  // matches the existing PATCH semantics (we never write whitespace).
+  if (row?.lettaApiKeyEncrypted) return "db";
+  const envKey = envSource.LETTA_API_KEY;
+  if (envKey && envKey.trim().length > 0) return "env";
+  return "none";
+}
+
+/**
+ * Reads the singleton admin-settings row. Throws if the row hasn't been
+ * seeded — should not happen after first-boot.
+ *
+ * @param ctx - minimal server-context slice carrying the Drizzle client.
+ * @param ctx.db - the Drizzle client used for the read.
+ * @returns the row, or `null` if absent.
+ */
+function readSettings(ctx: {
+  db: import("../../db/connection.js").DrizzleDB;
+}): AdminSettingRow | null {
+  return ctx.db.select().from(adminSetting).where(eq(adminSetting.id, 1)).get() ?? null;
+}
+
+/**
+ * Wire-format view of the settings row for `GET /admin/settings`.
+ *
+ * @param row - the admin_setting row.
+ * @returns the JSON-safe response shape.
+ */
+function settingsView(
+  row: AdminSettingRow,
+  envSource: Record<string, string | undefined>,
+): Record<string, unknown> {
+  const source = resolveApiKeySource(row, envSource);
+  return {
+    letta_base_url: row.lettaBaseUrl ?? null,
+    letta_ade_url: row.lettaAdeUrl ?? null,
+    letta_api_key_masked: maskLettaApiKey(row),
+    // True when EITHER the DB column is populated OR env.LETTA_API_KEY is
+    // set — matches the runtime resolver's "is the chat path going to
+    // work?" answer. The admin UI uses this to decide whether to render a
+    // "configured" badge vs. a "missing" warning, regardless of which
+    // source supplies the value.
+    letta_api_key_set: source !== "none",
+    // Source the runtime is *currently* using (per resolveApiKey precedence
+    // in letta/client.ts). Drives the admin UI's source-indicator text —
+    // "(from env)" vs "(from admin panel)" vs "(not configured)" — so
+    // operators don't get confused when the DB row is empty but chat
+    // still works (env fallback) or vice versa.
+    letta_api_key_source: source,
+    theme: {
+      default: row.themeDefault,
+      switcher_enabled: row.themeSwitcherEnabled,
+    },
+    feature_toggles: row.featureToggles,
+    signing_key_rotated_at: row.signingKeyRotatedAt ?? null,
+    metrics_scrape_token_rotated_at: row.metricsScrapeTokenRotatedAt ?? null,
+    updated_at: row.updatedAt,
+    // `metrics_scrape_token` and `service_token_signing_key` are deliberately
+    // omitted — see file-level comment.
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /admin/settings                                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /admin/settings` — super_admin-only deployment configuration.
+ *
+ * Encrypted Letta API key surfaces only as the masked placeholder
+ * (`letta_api_key_masked: "••••••••"`) + the boolean `letta_api_key_set`;
+ * plaintext never leaves the server through this endpoint. Step 12 wires the
+ * `Reveal once` flow as a separate UI affordance.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see ui-sketches/08-admin-settings.md
+ */
+export const handleGetSettings: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (_req, ctx) => {
+    const row = readSettings(ctx);
+    if (!row) return internalError("Admin settings row is missing — server misconfigured.");
+    return jsonResponse(200, settingsView(row, ctx.envSource));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /admin/settings                                                     */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Body for `PATCH /admin/settings`. Every field optional; empty body is a no-op. */
+const patchSettingsSchema = z
+  .object({
+    letta_base_url: z.string().url().nullable().optional(),
+    letta_ade_url: z.string().url().nullable().optional(),
+    // The API key accepts:
+    //   - a non-empty string → encrypt + store; runtime will use this DB
+    //     value over env on the next request.
+    //   - an empty/whitespace string → clear the DB column to NULL; the
+    //     runtime then falls back to env.LETTA_API_KEY (the operator-spec'd
+    //     "if admin panel is empty, use env" precedence).
+    //   - omitted → no change.
+    letta_api_key: z.string().max(2048).optional(),
+    theme: z
+      .object({
+        default: z.enum(["light", "dark"]).optional(),
+        switcher_enabled: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /admin/settings` — partial update of deployment configuration.
+ *
+ * The Letta API key, when supplied, is encrypted under
+ * `AI_HUB_ENCRYPTION_KEY` (env-only) before write. Theme fields live as
+ * separate columns (`theme_default`, `theme_switcher_enabled`) per §8.4.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see SPECIFICATIONS.md §8.4 — theme settings are explicit columns
+ */
+export const handlePatchSettings: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = patchSettingsSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    const update: Partial<typeof adminSetting.$inferInsert> = { updatedAt: nowIso() };
+    if (body.letta_base_url !== undefined) update.lettaBaseUrl = body.letta_base_url;
+    if (body.letta_ade_url !== undefined) update.lettaAdeUrl = body.letta_ade_url;
+    if (body.letta_api_key !== undefined) {
+      // Empty / whitespace-only string clears the DB column to NULL. The
+      // runtime then falls back to env.LETTA_API_KEY (see
+      // letta/client.ts:resolveApiKey). Non-empty values are encrypted +
+      // stored as the operator's override of env.
+      const trimmed = body.letta_api_key.trim();
+      update.lettaApiKeyEncrypted =
+        trimmed.length === 0 ? null : encryptString(ctx.encryptionKey, body.letta_api_key);
+    }
+    if (body.theme?.default !== undefined) update.themeDefault = body.theme.default;
+    if (body.theme?.switcher_enabled !== undefined)
+      update.themeSwitcherEnabled = body.theme.switcher_enabled;
+
+    if (Object.keys(update).length > 1) {
+      // More than just `updatedAt` — write.
+      ctx.db.update(adminSetting).set(update).where(eq(adminSetting.id, 1)).run();
+      ctx.logger.info(
+        {
+          actor_id: auth.user.id,
+          patch_keys: Object.keys(body),
+          event: "admin_settings_patched",
+        },
+        "Admin updated deployment settings.",
+      );
+    }
+
+    const fresh = readSettings(ctx);
+    if (!fresh) return internalError();
+    return jsonResponse(200, settingsView(fresh, ctx.envSource));
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  GET /admin/settings/feature-toggles                                       */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `GET /admin/settings/feature-toggles` — the §8.4 flat JSON blob.
+ *
+ * Missing keys fall back to the React side's built-in defaults at render
+ * time; the server doesn't merge defaults in here (so the admin UI can show
+ * "default" vs. "explicitly set").
+ *
+ * @see SPECIFICATIONS.md §8.4
+ */
+export const handleGetFeatureToggles: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (_req, ctx) => {
+    const row = readSettings(ctx);
+    if (!row) return internalError();
+    return jsonResponse(200, { feature_toggles: row.featureToggles ?? {} });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  PATCH /admin/settings/feature-toggles                                     */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `PATCH /admin/settings/feature-toggles` body. Strict — only known toggles
+ * are accepted. **Adding a new toggle requires bumping this schema** so
+ * accidental typos in the UI surface as 400s instead of silently being saved
+ * into the blob.
+ */
+const featureTogglesSchema = z
+  .object({
+    sessions_panel_enabled: z.boolean().optional(),
+    sessions_panel_resizable: z.boolean().optional(),
+    sessions_panel_collapsible: z.boolean().optional(),
+    create_session_button_enabled: z.boolean().optional(),
+    user_input_enabled: z.boolean().optional(),
+    stop_button_enabled: z.boolean().optional(),
+    tool_calls_visible: z.boolean().optional(),
+    reasoning_visible: z.boolean().optional(),
+    system_messages_visible: z.boolean().optional(),
+    tpm_notice_visible: z.boolean().optional(),
+    effort_control_visible: z.boolean().optional(),
+    scroll_to_present_visible: z.boolean().optional(),
+    turn_status_visible: z.boolean().optional(),
+  })
+  .strict();
+
+/**
+ * `PATCH /admin/settings/feature-toggles` — merge-patch the §8.4 blob.
+ *
+ * Unknown keys → 400. Each successful PATCH replaces the entire stored blob
+ * with the merge of (old state) + (incoming patch). Setting a key to `false`
+ * makes it explicit-false; omitting a key leaves the current value.
+ *
+ * @see SPECIFICATIONS.md §8.4
+ */
+export const handlePatchFeatureToggles: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (req, ctx, auth) => {
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch {
+      return validationError("Request body must be valid JSON.");
+    }
+    const parsed = featureTogglesSchema.safeParse(raw);
+    if (!parsed.success) {
+      return validationError(parsed.error.issues[0]?.message ?? "Invalid request body.");
+    }
+    const body = parsed.data;
+
+    const row = readSettings(ctx);
+    if (!row) return internalError();
+    const current = (row.featureToggles ?? {}) as Record<string, unknown>;
+    const next = { ...current };
+    for (const [k, v] of Object.entries(body)) {
+      if (v !== undefined) next[k] = v;
+    }
+
+    ctx.db
+      .update(adminSetting)
+      .set({ featureToggles: next, updatedAt: nowIso() })
+      .where(eq(adminSetting.id, 1))
+      .run();
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        patch_keys: Object.keys(body),
+        event: "admin_feature_toggles_patched",
+      },
+      "Admin updated feature toggles.",
+    );
+
+    return jsonResponse(200, { feature_toggles: next });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/settings/rotate-signing-key                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /admin/settings/rotate-signing-key` — replace the JWT signing key.
+ *
+ * Generates 64 new random bytes (matches seed bytes), writes to
+ * `admin_setting.service_token_signing_key`, bumps `signing_key_rotated_at`.
+ * Returns 204 No Content — the key never leaves the server.
+ *
+ * **Every outstanding JWT fails signature verification immediately after this
+ * call** (no grace period in v1). The calling super-admin's own token is
+ * invalidated alongside everyone else's; the React UI handles the 401 on the
+ * next request by routing back to login.
+ *
+ * @see SPECIFICATIONS.md §6.7 — signing key
+ * @see ui-sketches/08-admin-settings.md
+ */
+export const handleRotateSigningKey: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (_req, ctx, auth) => {
+    const newKey = randomBytes(64);
+    ctx.db
+      .update(adminSetting)
+      .set({
+        serviceTokenSigningKey: newKey,
+        signingKeyRotatedAt: nowIso(),
+        updatedAt: nowIso(),
+      })
+      .where(eq(adminSetting.id, 1))
+      .run();
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        event: "admin_signing_key_rotated",
+      },
+      "Admin rotated the JWT signing key. All outstanding tokens are now invalid.",
+    );
+    return new Response(null, { status: 204 });
+  },
+);
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  POST /admin/settings/rotate-metrics-token                                 */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * `POST /admin/settings/rotate-metrics-token` — replace the `/metrics` bearer
+ * token.
+ *
+ * Generates a fresh 32-byte hex token, writes it, bumps
+ * `metrics_scrape_token_rotated_at`, and returns `{ token: "<new>" }` exactly
+ * once. The plaintext never appears in subsequent `GET /admin/settings`
+ * responses (same one-time-reveal pattern as user password resets).
+ *
+ * Rotating does **not** invalidate the calling super-admin's JWT — only the
+ * metrics-scraper bearer changes. Operators paste the new value into their
+ * Prometheus / Alloy config; old scrapers start failing immediately.
+ *
+ * @see SPECIFICATIONS.md §6.10
+ * @see ui-sketches/08-admin-settings.md
+ */
+export const handleRotateMetricsToken: RouteHandler = protectedRoute(
+  { requiredRole: "super_admin" },
+  async (_req, ctx, auth) => {
+    const newToken = randomBytes(32).toString("hex");
+    ctx.db
+      .update(adminSetting)
+      .set({
+        metricsScrapeToken: newToken,
+        metricsScrapeTokenRotatedAt: nowIso(),
+        updatedAt: nowIso(),
+      })
+      .where(eq(adminSetting.id, 1))
+      .run();
+    ctx.logger.info(
+      {
+        actor_id: auth.user.id,
+        event: "admin_metrics_token_rotated",
+      },
+      "Admin rotated the /metrics scrape token.",
+    );
+    return jsonResponse(200, { token: newToken });
+  },
+);