@data-club/ai-hub-server 0.0.1

package/dist/routes/admin/settings.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `/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 type { RouteHandler } from "../../handlers/types.js";
+/**
+ * `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 declare const handleGetSettings: RouteHandler;
+/**
+ * `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 declare const handlePatchSettings: RouteHandler;
+/**
+ * `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 declare const handleGetFeatureToggles: RouteHandler;
+/**
+ * `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 declare const handlePatchFeatureToggles: RouteHandler;
+/**
+ * `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 declare const handleRotateSigningKey: RouteHandler;
+/**
+ * `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 declare const handleRotateMetricsToken: RouteHandler;
+//# sourceMappingURL=settings.d.ts.map

package/dist/routes/admin/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/routes/admin/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAgBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AA2H5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAO/B,CAAC;AA6BF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAgDjC,CAAC;AAMF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,YAOrC,CAAC;AA8BF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,YAuCvC,CAAC;AAMF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,EAAE,YAsBpC,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,EAAE,YAsBtC,CAAC"}

package/dist/routes/admin/settings.js

@@ -0,0 +1,401 @@
+/**
+ * `/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 { internalError, jsonResponse, validationError, } from "../../handlers/responses.js";
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Helpers                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+/** ISO-8601 timestamp with millisecond precision. */
+function nowIso() {
+    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) {
+    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 "••••••••";
+}
+/**
+ * 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, envSource) {
+    // 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) {
+    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, envSource) {
+    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 = 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 = protectedRoute({ requiredRole: "super_admin" }, async (req, ctx, auth) => {
+    let raw;
+    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 = { 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 = 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 = protectedRoute({ requiredRole: "super_admin" }, async (req, ctx, auth) => {
+    let raw;
+    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 ?? {});
+    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 = 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 = 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 });
+});
+//# sourceMappingURL=settings.js.map

package/dist/routes/admin/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../../src/routes/admin/settings.ts"],"names":[],"mappings":"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"}

package/dist/routes/admin/users.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `/admin/users/*` — admin + super_admin user management.
+ *
+ * Five endpoints:
+ *
+ * - `GET    /admin/users` — list every user in the deployment.
+ * - `POST   /admin/users` — create a user; the server generates a 16-char
+ *   alphanumeric password, hashes it, and returns the **plaintext exactly
+ *   once** in the response. The caller delivers it to the user out-of-band.
+ *   Sets `is_initial_password = true` so the user is forced to change on
+ *   first login (§8.5).
+ * - `PATCH  /admin/users/:id/role` — change a user's role. Uses
+ *   `applyUserRoleChangeInTx` so the shield + min-count rules are enforced
+ *   inside the transaction (no race possible).
+ * - `POST   /admin/users/:id/reset-password` — regenerate a 16-char password
+ *   for an existing user. Same return-once semantics; sets the initial-
+ *   password flag back to true. Uses `assertPasswordResetInTx` to validate
+ *   the shield + min-count rules, then performs the async Argon2 hash + write
+ *   outside the transaction (better-sqlite3 transactions are synchronous so
+ *   an Argon2 hash cannot live inside one). The narrow window between assert
+ *   and write is documented in the helper's JSDoc and is acceptable in v1.
+ * - `DELETE /admin/users/:id` — hard-delete the user. Uses
+ *   `applyUserDeletionInTx`; cascades to `session` via the FK.
+ *
+ * **Admin shield + min-count rules** are enforced by the helpers in
+ * `auth/roleRules.ts`; the handlers here just translate the helper's
+ * `TxResult` into a Response.
+ *
+ * **Admin cannot create / promote to `super_admin`.** The role enum on the
+ * POST body is filtered by caller role (admins see user / power_user /
+ * admin; super_admin sees all four). This mirrors the [05-admin-users.md]
+ * sketch's "Create User" modal.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin users endpoints
+ * @see SPECIFICATIONS.md §8.1 — shield + min-count rules
+ * @see SPECIFICATIONS.md §8.5 — password reset semantics
+ * @see ui-sketches/05-admin-users.md
+ */
+import type { RouteHandler } from "../../handlers/types.js";
+/**
+ * `GET /admin/users` — list every user in the deployment.
+ *
+ * `admin` and `super_admin` only; gated by `protectedRoute({ requiredRole: "admin" })`.
+ * Sorted alphabetically by username for stable rendering in the admin table.
+ *
+ * @see SPECIFICATIONS.md §6.3.4
+ * @see ui-sketches/05-admin-users.md
+ */
+export declare const handleListUsers: RouteHandler;
+/**
+ * `POST /admin/users` — create a new user with a server-generated password.
+ *
+ * The 16-char alphanumeric plaintext is returned **exactly once** in the
+ * response (`{ user, generated_password }`); the caller (admin) is expected
+ * to deliver it out-of-band per §8.5. The plaintext never appears in logs
+ * (pino's redaction policy plus we never log the field).
+ *
+ * Caller-role gates:
+ *
+ * - `admin` can create role `user` / `power_user` / `admin`.
+ * - `super_admin` can additionally create `super_admin`.
+ *
+ * On username collision returns 409 `username_taken` (not 400) — the request
+ * itself was well-formed; the conflict is with existing data.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.5
+ * @see ui-sketches/05-admin-users.md
+ */
+export declare const handleCreateUser: RouteHandler;
+/**
+ * `PATCH /admin/users/:id/role` — change a user's role.
+ *
+ * Delegates the shield + min-count check to `applyUserRoleChangeInTx`, which
+ * re-reads the target row + super-admin count inside one transaction so a
+ * concurrent demote cannot bypass the invariants.
+ *
+ * Additional caller-role gate on top of the helper: an `admin` cannot grant
+ * the `super_admin` role on a target they could otherwise mutate (e.g.
+ * promoting a `power_user → super_admin`) — only super-admins can.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.1
+ */
+export declare const handlePatchUserRole: RouteHandler;
+/**
+ * `POST /admin/users/:id/reset-password` — regenerate the user's password.
+ *
+ * Uses `assertPasswordResetInTx` to validate shield + min-count inside a
+ * transaction, then performs the async Argon2 hash + UPDATE *outside* the
+ * transaction (better-sqlite3 transactions are synchronous). The narrow
+ * window between assertion and write is acceptable in v1 — a concurrent
+ * role-mutation could in theory bypass the rule, but the worst-case is a
+ * single password reset on a user the admin shouldn't have been able to
+ * touch; the admin already had to authenticate and the new password is
+ * displayed only to them. Mitigation if this ever bites: re-verify the
+ * caller's role hasn't dropped between assertion and write.
+ *
+ * Returns `{ generated_password }` exactly once. Sets `is_initial_password =
+ * true` so the user is forced to change on their next login.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.5
+ * @see ui-sketches/05-admin-users.md
+ */
+export declare const handleResetUserPassword: RouteHandler;
+/**
+ * `DELETE /admin/users/:id` — hard-delete the user.
+ *
+ * Uses `applyUserDeletionInTx`; the FK on `session.user_id` cascades, so
+ * deleting a user removes all their sessions atomically. The shield + min-
+ * count invariants apply (an admin cannot delete another admin or super
+ * admin; nobody can delete the only super admin).
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.1
+ */
+export declare const handleDeleteUser: RouteHandler;
+//# sourceMappingURL=users.d.ts.map

package/dist/routes/admin/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/routes/admin/users.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA0BH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAgF5D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,YAQ7B,CAAC;AAiBF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAyE9B,CAAC;AAaF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,EAAE,YA4CjC,CAAC;AAMF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,EAAE,YA6CrC,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,YA6B9B,CAAC"}