@valentinkolb/cloud 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/cloud",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "MIT",
   "repository": {
@@ -19,39 +19,49 @@
   "exports": {
     ".": "./src/index.ts",
     "./ui": "./src/ui/index.ts",
+    "./ui/styles.css": "./src/styles/global.css",
+    "./desktop": "./src/desktop/index.ts",
+    "./desktop/solid": "./src/desktop/solid.tsx",
     "./server": "./src/server/index.ts",
     "./browser": "./src/server/api-client.ts",
     "./shared": "./src/shared/index.ts",
     "./services": "./src/services/index.ts",
+    "./services/ipa/service-account": null,
     "./services/*": "./src/services/*",
     "./ssr": "./src/ssr/index.ts",
     "./ssr/islands": "./src/ssr/islands/index.ts",
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
     "./contracts": "./src/contracts/index.ts",
+    "./api": "./src/api/index.ts",
+    "./clients/core": "./src/clients/core.ts",
     "./styles/global.css": "./src/styles/global.css"
   },
   "scripts": {
+    "test": "bun test",
     "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.typecheck.json --noEmit --pretty false 2>&1 | grep -v node_modules | (! grep -q 'error TS')"
   },
   "dependencies": {
-    "@fontsource-variable/jetbrains-mono": "^5.2.8",
-    "@scalar/hono-api-reference": "^0.10.9",
-    "@scalar/openapi-to-markdown": "^0.5.6",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "@fontsource/ibm-plex-sans": "^5.2.8",
+    "@fontsource/ibm-plex-sans-condensed": "^5.2.8",
+    "@simplewebauthn/server": "^13.3.1",
     "@tabler/icons-webfont": "^3.36.1",
     "@tailwindcss/typography": "^0.5.19",
-    "@valentinkolb/ssr": "0.9.0",
-    "@valentinkolb/stdlib": "0.3.0",
+    "@valentinkolb/ssr": "0.10.0",
+    "@valentinkolb/stdlib": "0.12.0",
     "@valentinkolb/sync": "^5.0.0",
     "bun-plugin-tailwind": "^0.1.2",
     "hono": "^4.11.1",
     "hono-openapi": "^1.1.2",
+    "jose": "^6.1.3",
     "katex": "^0.16.28",
     "marked": "^17.0.1",
     "mermaid": "^11.12.2",
     "mustache": "^4.2.0",
-    "nodemailer": "^7.0.12",
-    "sanitize-html": "^2.17.0",
+    "nodemailer": "^8.0.10",
+    "sanitize-html": "^2.17.4",
+    "seroval": "^1.5.4",
     "solid-js": "^1.9.10",
     "tailwindcss": "^4.1.18",
     "zod": "^4.3.4"

package/scripts/preload.ts

@@ -7,10 +7,11 @@
  * uses /app as projectRoot → auto-detect scans all packages → all classes generated.
  * No @source directives needed in CSS files.
  */
-import tailwind from "bun-plugin-tailwind";
+import { existsSync, watch } from "node:fs";
 import { cp, mkdir } from "node:fs/promises";
-import { resolve, dirname } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import tailwind from "bun-plugin-tailwind";
 
 const appId = process.env.APP_ID ?? "core";
 const { plugin } = await import(`../../${appId}/src/config`);
@@ -21,8 +22,7 @@ const workspaceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..
 const publicDir = resolve(workspaceRoot, "public");
 await mkdir(publicDir, { recursive: true });
 
-// global.css + branding are only served by core (Traefik routes them there)
-if (appId === "core") {
+const buildGlobalCss = async () => {
   // Use styles.css at workspace root as entrypoint so the oxide scanner
   // walks up to /app/package.json and scans ALL packages for utility classes.
   // (If the CSS file is inside packages/lib/, it only scans packages/lib/.)
@@ -32,24 +32,74 @@ if (appId === "core") {
     naming: "global.css",
     plugins: [tailwind],
   });
+};
+
+const buildAppCss = async () => {
+  // `naming: "app.css"` is essential — without it, Bun.build with `root: workspaceRoot`
+  // preserves the directory structure (packages/<id>/src/styles/app.css) inside outdir,
+  // so Layout's `<link href="/public/<id>/app.css">` 404s and only global.css's classes
+  // reach the browser. That's why responsive grid utilities went missing on dashboard.
+  await Bun.build({
+    entrypoints: [resolve(workspaceRoot, `packages/${appId}/src/styles/app.css`)],
+    outdir: resolve(publicDir, appId),
+    naming: "app.css",
+    root: workspaceRoot, // same: auto-detect from /app
+    plugins: [tailwind],
+  });
+};
+
+const watchDevCss = (label: string, paths: string[], build: () => Promise<void>) => {
+  if (process.env.NODE_ENV !== "development") return;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let running = false;
+  let queued = false;
+
+  const rebuild = () => {
+    if (running) {
+      queued = true;
+      return;
+    }
+
+    running = true;
+    void build()
+      .then(() => console.log(`[preload] rebuilt ${label}`))
+      .catch((error) => console.error(`[preload] failed to rebuild ${label}`, error))
+      .finally(() => {
+        running = false;
+        if (queued) {
+          queued = false;
+          rebuild();
+        }
+      });
+  };
+
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(rebuild, 75);
+  };
+
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    watch(path, { persistent: true }, schedule);
+  }
+};
+
+// global.css + branding are only served by core (Traefik routes them there)
+if (appId === "core") {
+  await buildGlobalCss();
 
   // Default branding asset: copy the tracked logo.svg into the runtime
   // public dir so serveBranding can fall back to it when no admin-uploaded
   // logo (data URI) is configured. User uploads are stored as base64 data
   // URIs in settings — no image processing (sharp etc.) needed.
-  await cp(
-    resolve(workspaceRoot, "packages/cloud/public/logo.svg"),
-    resolve(publicDir, "logo.svg"),
-  );
+  await cp(resolve(workspaceRoot, "packages/cloud/public/logo.svg"), resolve(publicDir, "logo.svg"));
 }
 
 // katex.css is only needed by notebooks (served by core via Traefik /public/katex.css)
 if (appId === "notebooks") {
   try {
-    await cp(
-      resolve(workspaceRoot, "node_modules/katex/dist/katex.min.css"),
-      resolve(publicDir, "katex.css"),
-    );
+    await cp(resolve(workspaceRoot, "node_modules/katex/dist/katex.min.css"), resolve(publicDir, "katex.css"));
   } catch {
     console.warn("[preload] katex.css not found, skipping");
   }
@@ -60,14 +110,19 @@ const appCssPath = resolve(workspaceRoot, `packages/${appId}/src/styles/app.css`
 const appPublicDir = resolve(publicDir, appId);
 await mkdir(appPublicDir, { recursive: true });
 
-// `naming: "app.css"` is essential — without it, Bun.build with `root: workspaceRoot`
-// preserves the directory structure (packages/<id>/src/styles/app.css) inside outdir,
-// so Layout's `<link href="/public/<id>/app.css">` 404s and only global.css's classes
-// reach the browser. That's why responsive grid utilities went missing on dashboard.
-await Bun.build({
-  entrypoints: [appCssPath],
-  outdir: appPublicDir,
-  naming: "app.css",
-  root: workspaceRoot, // same: auto-detect from /app
-  plugins: [tailwind],
-});
+await buildAppCss();
+
+watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
+if (appId === "core") {
+  watchDevCss("global.css", [resolve(workspaceRoot, "styles.css"), resolve(workspaceRoot, "packages/cloud/src/styles")], buildGlobalCss);
+}
+
+// Optional app-owned dev assets. Production builds already have
+// scripts/build-extras.ts; this mirrors that hook for watch mode without
+// forcing app-specific asset logic into the framework preload.
+const devExtras = resolve(workspaceRoot, `packages/${appId}/scripts/dev-extras.ts`);
+if (existsSync(devExtras)) {
+  process.env.WORKSPACE_ROOT = workspaceRoot;
+  process.env.PUBLIC_DIR = publicDir;
+  await import(devExtras);
+}

package/src/_internal/define-app.ts

@@ -4,26 +4,23 @@
  * Merges SSR config, app meta, and server bootstrap into one call.
  * Returns `{ ssr, plugin, config, meta, start }`.
  */
+
+import type { SsrConfig } from "@valentinkolb/ssr";
 import { createConfig as createSsrConfig } from "@valentinkolb/ssr";
 import { createSSRHandler, routes } from "@valentinkolb/ssr/hono";
 import { Hono } from "hono";
 import { serveStatic } from "hono/bun";
-import type { SsrConfig } from "@valentinkolb/ssr";
-import type {
-  AppMeta,
-  AppLifecycle,
-  AppCapabilities,
-  AppSearchContext,
-  CloudContext,
-} from "../contracts/app";
+import { generateSpecs } from "hono-openapi";
+import type { AppCapabilities, AppLifecycle, AppMeta, AppSearchContext, CloudContext } from "../contracts/app";
 import type { AppRegistryEntry } from "../contracts/registry";
-import type { Role } from "../contracts/shared";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
-import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
-import { registerSettings, type SettingDef } from "../services/settings/defaults";
+import type { Role } from "../contracts/shared";
+import { themeBootstrapScript } from "../shared/theme";
 import { auth } from "../server/middleware/auth";
 import { logger } from "../services/logging";
-import { get, set, loadCache as loadSettingsCache } from "../services/settings";
+import { get, loadCache as loadSettingsCache, set } from "../services/settings";
+import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
+import { registerSettings, type SettingDef } from "../services/settings/defaults";
 import { createHeartbeat } from "./heartbeat";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 
@@ -80,7 +77,7 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
   /**
    * Legal/info links contributed by this app — aggregated app-wide via
    * `listLegalLinks()` and rendered in login footer, app Footer, rail more
-   * dropdown. Each app contributes its own (e.g. settings owns
+   * dropdown. Each app contributes its own (e.g. core owns
    * Imprint/Privacy/Terms; faq owns FAQ). KISS: no `external` flag, links
    * always open in a new tab from the login footer.
    */
@@ -101,12 +98,29 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
    *   `/admin/<id>`   — admin SSR pages
    *   `/public/<id>`  — built CSS and other static assets
    *
-   * Apps with non-standard URLs (core's `/auth`, `/me`; oauth's `/oauth`,
-   * `/.well-known/...`; settings' `/legal/*`, `/impressum`) list whatever
+   * Apps with non-standard URLs (core's `/auth`, `/me`, `/legal/*`, `/impressum`;
+   * oauth's `/oauth`, `/.well-known/...`) list whatever
    * top-level paths they own. The gateway is dumb — it just builds a
    * prefix-trie from these strings.
    */
   routes: readonly string[];
+  /**
+   * Gateway-relative URL at which this app's OpenAPI 3.x JSON spec is
+   * served, e.g. `"/api/notebooks/openapi.json"`. Opt-in: only set this
+   * for apps whose api router is documented with `middleware.openapi()`
+   * (i.e. `describeRoute()`) and worth surfacing in the api-docs aggregator.
+   *
+   * Pair this with `app.start({ openapi: <api router> })` — `defineApp`
+   * generates the spec from that router at boot, mounts it on the
+   * framework server (before the user's fetch, so it bypasses any
+   * auth/rate-limit middleware), and advertises the URL via the registry
+   * so `app-api-docs` picks it up automatically.
+   *
+   * The path must be reachable through the gateway — usually that means
+   * the standard form `"/api/<id>/openapi.json"` (covered by the
+   * `/api/<id>` entry in `routes`).
+   */
+  openapi?: string;
   /**
    * Project root used by the SSR plugin to discover island/client files.
    * Defaults to `process.cwd()`. Override only if you run the entrypoint
@@ -133,7 +147,19 @@ export type StartOptions = {
    * before this fetch — they take precedence over any catch-all the app
    * might register.
    */
-  fetch: (req: Request) => Response | Promise<Response>;
+  fetch: (req: Request, env?: unknown) => Response | Promise<Response>;
+  /**
+   * Hono router to scan for OpenAPI route metadata. When set together with
+   * `defineApp({ openapi: "..." })`, the framework generates an OpenAPI
+   * spec from this router and mounts it at the configured URL on the
+   * framework server (before the user's fetch, so the spec stays public).
+   *
+   * Pass the BARE api router — the one with `describeRoute()` annotations.
+   * `generateSpecs` walks the route tree without executing middleware, so
+   * the inner auth/rate-limit `.use(...)` calls don't matter for spec
+   * generation; they only run if the router is hit by an actual request.
+   */
+  openapi?: Hono<any>;
   lifecycle?: AppLifecycle;
   capabilities?: AppCapabilities;
   port?: number;
@@ -142,6 +168,7 @@ export type StartOptions = {
 
 export type StartResult = {
   port: number;
+  development: boolean;
   fetch: Hono["fetch"];
 };
 
@@ -174,6 +201,8 @@ export type AppDefinition<S extends AppSettingsMap = {}> = {
 // ── Implementation ──────────────────────────────────────────────────────────
 
 export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<S>): AppDefinition<S> => {
+  const isDevelopment = process.env.NODE_ENV === "development";
+
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
   // (writeKey checks SETTINGS_MAP.get(key)) and for snapshot.ts (allKnownKeys
@@ -207,7 +236,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
 
   // ── 1. SSR config ─────────────────────────────────────────────────────
   const { config, plugin, html } = createSsrConfig<PageOptions>({
-    dev: process.env.NODE_ENV !== "production",
+    dev: isDevelopment,
     verbose: true,
     rootDir: opts.appRoot ?? process.cwd(),
     basePath: opts.basePath,
@@ -222,17 +251,10 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     <meta name="theme-color" content="#09090b">
     <meta name="mobile-web-app-capable" content="yes">
     <link rel="icon" href="/branding/favicon">
-    <link rel="stylesheet" href="/public/global.css?v=${v}">
+    <style data-cloud-css-layers>@layer theme, base, components, utilities;</style>
     <link rel="stylesheet" href="/public/${opts.id}/app.css?v=${v}">
-    <script>
-      (function() {
-        var el = document.documentElement;
-        if (!el.hasAttribute('data-theme-fixed')) {
-          var theme = document.cookie.match(/theme=([^;]+)/)?.[1] || 'light';
-          el.classList.add(theme);
-        }
-      })();
-    </script>
+    <link rel="stylesheet" href="/public/global.css?v=${v}">
+    <script>${themeBootstrapScript}</script>
   </head>
   <body>
     ${body}
@@ -258,6 +280,8 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
+    settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
+    openapi: opts.openapi,
   };
 
   // ── 3. start() — builds and boots the Hono server ────────────────────
@@ -266,6 +290,11 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     const baseUrl = opts.baseUrl;
     const log = logger("app");
 
+    // OpenAPI advertised in the registry only when there's a router to
+    // derive the spec from. The mount block lower down uses the same
+    // flag so the registry never points at a URL that 404s.
+    const advertiseOpenapi = !!(opts.openapi && startOpts.openapi);
+
     // Registry entry
     const entry: AppRegistryEntry = {
       id: meta.id,
@@ -274,16 +303,17 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       description: meta.description,
       baseUrl,
       routes: [...meta.routes],
-      nav: (meta.nav || meta.adminHref)
-        ? {
-            href: meta.nav?.href ?? "",
-            match: meta.nav?.match,
-            section: meta.nav?.section ?? "hidden",
-            requiresAuth: meta.nav?.requiresAuth,
-            requiresRoles: meta.nav?.requiresRoles,
-            adminHref: meta.adminHref,
-          }
-        : undefined,
+      nav:
+        meta.nav || meta.adminHref
+          ? {
+              href: meta.nav?.href ?? "",
+              match: meta.nav?.match,
+              section: meta.nav?.section ?? "hidden",
+              requiresAuth: meta.nav?.requiresAuth,
+              requiresRoles: meta.nav?.requiresRoles,
+              adminHref: meta.adminHref,
+            }
+          : undefined,
       search: startOpts.capabilities?.search
         ? {
             tags: [...(startOpts.capabilities.search.tags ?? [])],
@@ -294,6 +324,8 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
         : undefined,
       legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
       widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+      settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
+      openapi: advertiseOpenapi ? opts.openapi : undefined,
     };
 
     // Heartbeat
@@ -306,21 +338,26 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     // watcher is a module-level singleton, only one runs per process.
     await ensureRuntimeWatcher();
 
-    // Build Hono server. Framework owns three mounts (registered first so
+    // Build Hono server. Framework owns these mounts (registered first so
     // they take precedence over any catch-all in the user's fetch):
     //   /_ssr/*                 island chunks (SSR adapter)
     //   /public/*               serveStatic + terminal 404
     //   /api/_internal/search   only when capabilities.search is declared
+    //   <opts.openapi>          OpenAPI JSON spec, when both opts.openapi
+    //                            and startOpts.openapi are set
     const ssrMountPath = config.basePath ? `${config.basePath}/_ssr` : "/_ssr";
 
     const server = new Hono()
       .route(ssrMountPath, routes(config))
-      .use("/public/*", serveStatic({
-        root: "./",
-        onFound: (_path, c) => {
-          c.header("Cache-Control", "public, max-age=31536000, immutable");
-        },
-      }))
+      .use(
+        "/public/*",
+        serveStatic({
+          root: "./",
+          onFound: (_path, c) => {
+            c.header("Cache-Control", isDevelopment ? "no-store" : "public, max-age=31536000, immutable");
+          },
+        }),
+      )
       // serveStatic calls next() on miss — terminate /public/* here so a
       // missing asset is a clean 404 instead of falling through to the app
       // fetch (which might render an HTML page for the missing path).
@@ -329,6 +366,9 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     if (startOpts.capabilities?.search) {
       const searchRun = startOpts.capabilities.search.run;
       server.post("/api/_internal/search", auth.requireRole("authenticated"), async (c) => {
+        if (!c.get("user")) {
+          return c.json({ message: "Search providers require a user-backed actor", code: "FORBIDDEN" }, 403);
+        }
         const body = await c.req.json<{ query: string; tags: string[]; limit: number }>();
         const ctx: AppSearchContext = { get: (key) => c.get(key) as never };
         const results = await searchRun({ query: body.query, tags: body.tags, limit: body.limit, ctx });
@@ -336,10 +376,40 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       });
     }
 
+    // OpenAPI spec mount. Registered on the framework server (before the
+    // user-fetch catch-all below) so it bypasses any auth / rate-limit
+    // middleware on the api router — the spec must stay reachable without
+    // a session for `app-api-docs` to render it.
+    //
+    // The `servers` override is load-bearing: hono-openapi walks the
+    // BARE api router and emits paths relative to its own root (e.g.
+    // `/{id}`, `/{id}/notes`), without the `/api/<id>` prefix it ends
+    // up under in the user's outer router. We derive that prefix from
+    // `opts.openapi` (everything before the trailing `/openapi.json`)
+    // so combined Scalar URLs resolve to the real public paths.
+    if (advertiseOpenapi) {
+      const apiPrefix = opts.openapi!.replace(/\/openapi\.json$/, "") || "/";
+      const spec = await generateSpecs(startOpts.openapi!, {
+        documentation: {
+          info: {
+            title: meta.name,
+            version: "0.0.1",
+            description: meta.description,
+          },
+          servers: [{ url: apiPrefix }],
+        },
+      });
+      server.get(opts.openapi!, (c) => c.json(spec));
+    }
+
     // User's fetch handles everything else. The framework doesn't inject any
     // context vars here — the user's router is expected to register the
     // middlewares it needs (middleware.runtime, middleware.settings, …).
-    server.all("*", (c) => Promise.resolve(startOpts.fetch(c.req.raw)));
+    //
+    // env is threaded through so Bun-specific helpers inside the user's
+    // router still work — most importantly `upgradeWebSocket` from hono/bun,
+    // which reads the Bun server off `c.env`.
+    server.all("*", (c) => Promise.resolve(startOpts.fetch(c.req.raw, c.env)));
 
     // Lifecycle
     const cloudCtx: CloudContext = {
@@ -366,7 +436,9 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       if (stopping) return;
       stopping = true;
       log.info(`Stopping: ${meta.id}`);
-      try { if (startOpts.lifecycle?.stop) await startOpts.lifecycle.stop(cloudCtx); } catch {}
+      try {
+        if (startOpts.lifecycle?.stop) await startOpts.lifecycle.stop(cloudCtx);
+      } catch {}
       await stopRuntimeWatcher();
       await heartbeat.stop();
     };
@@ -374,7 +446,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
     process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
 
-    return { port, fetch: server.fetch };
+    return { port, development: isDevelopment, fetch: server.fetch };
   };
 
   return {

package/src/_internal/runtime-context.ts

@@ -33,6 +33,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[]): CloudRunt
       searchHelp: e.search?.help,
       searchTagHelp: e.search?.tagHelp,
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
+      openapi: e.openapi,
     }),
   ),
 });

package/src/api/accounts-entities.ts

@@ -32,6 +32,7 @@ const QuerySchema = z
     profile: UserProfileSchema.optional(),
     exclude_user_ids: z.string().optional(),
     exclude_group_ids: z.string().optional(),
+    exclude_service_account_ids: z.string().optional(),
     user_member_of_group_ids: z.string().optional(),
     member_of_group_id: z.uuid().optional(),
     manager_of_group_id: z.uuid().optional(),
@@ -102,6 +103,8 @@ const app = new Hono()
       if (!excludeUserIds.ok) return respond(c, fail(err.badInput(excludeUserIds.message)));
       const excludeGroupIds = parseUuidList(query.exclude_group_ids, "exclude_group_ids");
       if (!excludeGroupIds.ok) return respond(c, fail(err.badInput(excludeGroupIds.message)));
+      const excludeServiceAccountIds = parseUuidList(query.exclude_service_account_ids, "exclude_service_account_ids");
+      if (!excludeServiceAccountIds.ok) return respond(c, fail(err.badInput(excludeServiceAccountIds.message)));
       const userMemberOfGroupIds = parseUuidList(query.user_member_of_group_ids, "user_member_of_group_ids");
       if (!userMemberOfGroupIds.ok) return respond(c, fail(err.badInput(userMemberOfGroupIds.message)));
 
@@ -113,6 +116,7 @@ const app = new Hono()
         profile: query.profile,
         excludeUserIds: excludeUserIds.value,
         excludeGroupIds: excludeGroupIds.value,
+        excludeServiceAccountIds: excludeServiceAccountIds.value,
         userMemberOfGroupIds: userMemberOfGroupIds.value,
         memberOfGroupId: query.member_of_group_id,
         managerOfGroupId: query.manager_of_group_id,

package/src/api/admin-core-settings.ts

@@ -0,0 +1,98 @@
+/**
+ * Admin API for platform-wide runtime settings.
+ *
+ * This route lives in cloud-lib because `/admin/settings` is a platform page
+ * and needs a typed client without depending on the core app package. The
+ * core app mounts it under `/api/admin/core/settings`.
+ */
+import { sql } from "bun";
+import { Hono } from "hono";
+import { z } from "zod";
+import { listApps } from "../_internal/registry";
+import { auth, v, type AuthContext } from "../server";
+import { settingsDeleteLegacyKeys, settingsListLegacyKeys } from "../services";
+import * as settings from "../services/settings";
+import { SETTINGS_MAP } from "../services/settings/defaults";
+
+const BulkUpdateSchema = z.record(z.string(), z.unknown());
+
+type FieldErrors = Record<string, string>;
+
+const isKnownSetting = (key: string): boolean => SETTINGS_MAP.has(key);
+const liveSettingKeys = async () => (await listApps()).flatMap((app) => [...(app.settingKeys ?? [])]);
+
+const app = new Hono<AuthContext>()
+  .get("/legacy", auth.requireRole("admin"), async (c) => {
+    return c.json(await settingsListLegacyKeys(await liveSettingKeys()));
+  })
+  .delete("/legacy", auth.requireRole("admin"), async (c) => {
+    return c.json(await settingsDeleteLegacyKeys(await liveSettingKeys()));
+  })
+  .put(
+    "/",
+    auth.requireRole("admin"),
+    v("json", BulkUpdateSchema),
+    async (c) => {
+      const updates = c.req.valid("json");
+      const keys = Object.keys(updates);
+
+      if (keys.length === 0) {
+        return c.body(null, 204);
+      }
+
+      const ownership: FieldErrors = {};
+      for (const key of keys) {
+        if (!isKnownSetting(key)) {
+          ownership[key] = `Unknown setting "${key}"`;
+        }
+      }
+      if (Object.keys(ownership).length > 0) {
+        return c.json({ message: "Invalid keys", errors: ownership }, 400);
+      }
+
+      const fieldErrors: FieldErrors = {};
+      try {
+        await sql.begin(async () => {
+          for (const [key, value] of Object.entries(updates)) {
+            try {
+              await settings.set(key, value);
+            } catch (error) {
+              fieldErrors[key] = error instanceof Error ? error.message : `Failed to update ${key}`;
+              throw error;
+            }
+          }
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Save failed";
+        return c.json(
+          {
+            message,
+            errors: Object.keys(fieldErrors).length > 0 ? fieldErrors : { _form: message },
+          },
+          400,
+        );
+      }
+
+      return c.body(null, 204);
+    },
+  )
+  .delete(
+    "/:key{.+}",
+    auth.requireRole("admin"),
+    async (c) => {
+      const key = c.req.param("key");
+      if (!isKnownSetting(key)) {
+        return c.json({ message: `Unknown setting "${key}"` }, 400);
+      }
+      try {
+        await settings.remove(key);
+        return c.body(null, 204);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Reset failed";
+        return c.json({ message }, 500);
+      }
+    },
+  );
+
+export default app;
+export type ApiType = typeof app;