@lenne.tech/nest-server 11.31.2 → 11.31.3

package/src/core/modules/hub/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,64 @@
+# Hub Integration Checklist
+
+The Hub is **config-only** — no files need to be created in the consuming project. It is auto-registered
+by `CoreModule.forRoot()` when `hub` is present in the config.
+
+## Reference Implementation
+
+- Local: `node_modules/@lenne.tech/nest-server/src/core/modules/hub/`
+- The framework's own e2e config (`src/config.env.ts`) enables it in `local`/`development`/`e2e`/`ci`.
+
+## Quick Setup
+
+### 1. Enable per environment
+
+**Edit:** `src/config.env.ts`
+
+```typescript
+// development / local
+hub: {
+  collectors: { queries: true },   // opt-in query profiler
+  mailbox: { mode: 'capture' },    // capture outgoing mail locally (Mailpit replacement)
+},
+
+// production — usually omit `hub` entirely, or (if you want it, still ADMIN-gated):
+// hub: { collectors: { queries: false }, mailbox: false },
+```
+
+That's it. Sign in as a user with `RoleEnum.ADMIN` and open `/hub`.
+
+## Optional Enhancements
+
+| Want                        | Do                                                                                                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Cron panel populated**    | Import `ScheduleModule.forRoot()` in your ServerModule (usually already present).                                                                                              |
+| **Query profiler**          | Set `hub.collectors.queries: true` (opts the driver into `monitorCommands`).                                                                                                   |
+| **Migrations run/rollback** | Set `hub.migrations.dir` to your migrations directory (default `./migrations`). In compiled deployments point it at the built JS. Use `lockCollectionName` for cluster safety. |
+| **Custom look / behavior**  | Pass `overrides.hub.{controller,actionsController,service,htmlService,actionsService}` to `CoreModule.forRoot()`.                                                              |
+
+## Verification Checklist
+
+- [ ] `pnpm run build` succeeds
+- [ ] Sign in as ADMIN → `GET /hub` returns the dashboard HTML
+- [ ] A non-admin user gets `403`; an anonymous request gets `401`
+- [ ] `GET /hub/dashboard.json` returns build/memory/features
+- [ ] `GET /hub/config.json` shows `***` for secrets (never the real values)
+- [ ] Mutating actions without `X-Hub-Request: 1` return `403`
+
+## Common Mistakes
+
+| Mistake                                          | Symptom                                                        | Fix                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hub` not set in the target environment          | `/hub` → 404                                                   | Add `hub: true` (or an options object) to that env's config block                                                                                                                                                                                                                                  |
+| `mailbox.mode: 'capture'` in production          | Startup error                                                  | Use `mode: 'copy'` or disable the mailbox in production — capture suppresses all mail                                                                                                                                                                                                              |
+| Query panel empty                                | queries collector off (default)                                | `hub.collectors.queries: true`                                                                                                                                                                                                                                                                     |
+| Cron panel empty                                 | `ScheduleModule.forRoot()` not imported                        | Import it in your ServerModule                                                                                                                                                                                                                                                                     |
+| Hub path collides with a project route           | 404 / wrong page                                               | Set a distinct `hub.path` (e.g. `admin/hub`)                                                                                                                                                                                                                                                       |
+| No roles guard registered (auth system disabled) | Every `/hub` sidecar/action returns 200 for anonymous requests | The Hub relies on the framework's `RolesGuard`/`BetterAuthRolesGuard` (registered by the auth/BetterAuth module) to enforce `@Roles(RoleEnum.ADMIN)`. If you disable BetterAuth AND legacy auth, no guard runs and the ADMIN gate is inert. Keep an auth module enabled, or do not expose the Hub. |
+
+> **Auth dependency (why):** the Hub does not register its own guard — it assigns `@Roles(hub.roles)`
+> (default `ADMIN`) as metadata and depends on the app-wide `RolesGuard` / `BetterAuthRolesGuard` to
+> read it. That guard ships with the auth/BetterAuth modules. In a normal project one of them is
+> active, so the gate works out of the box; but an app that runs with _no_ auth system has no guard
+> to enforce the roles, and the sidecars/actions would be reachable unauthenticated. Either keep an
+> auth module enabled or leave the Hub disabled in such a setup.

package/src/core/modules/hub/README.md

@@ -0,0 +1,159 @@
+# Hub — Admin Area (Operator Cockpit)
+
+A build-free, ADMIN-gated dashboard of runtime information and admin tools, served directly by the
+framework. Inspired by the sister project [nest-base](https://github.com/lenneTech/nest-base)'s Hub,
+but adapted to this stack (NestJS + GraphQL + Mongoose) and shipped as **dependency-free server-side
+HTML + a vanilla-JS SPA** (no React, no build step) so it works identically in npm- and vendor-mode.
+
+## Enable it
+
+The Hub is **never enabled implicitly** — switch it on per environment:
+
+```typescript
+// config.env.ts
+{
+  hub: true,                          // enabled at /hub, admin-only, default collectors
+  // or, with options:
+  hub: {
+    path: 'hub',                      // default 'hub'
+    collectors: { queries: true },    // query profiler is opt-in (enables driver command monitoring)
+    mailbox: { mode: 'capture' },     // built-in Mailpit-style mail capture (dev/test)
+  },
+}
+```
+
+Do NOT set `hub` in the `production` block unless you intend the cockpit to be reachable there
+(it stays ADMIN-gated). See `IHubConfig` in `interfaces/hub-config.interface.ts` for every option.
+
+## Panels
+
+| Panel                | Route                 | Source                                                          |
+| -------------------- | --------------------- | --------------------------------------------------------------- |
+| Dashboard            | `/hub`                | health, build info, memory, feature matrix, links               |
+| Diagnostics          | `/hub/diagnostics`    | heap/rss, node/platform, collector buffer levels                |
+| Logs                 | `/hub/logs`           | in-memory log ring buffer (redacted)                            |
+| Request Traces       | `/hub/traces`         | HTTP timing middleware                                          |
+| Query Performance    | `/hub/queries`        | MongoDB driver command monitoring (opt-in)                      |
+| Cron Jobs            | `/hub/cron`           | `@nestjs/schedule` `SchedulerRegistry` (optional)               |
+| Database             | `/hub/db`             | dbStats / per-collection collStats                              |
+| Models / ERD         | `/hub/models`         | Mongoose schemas → Mermaid ER diagram                           |
+| Migrations           | `/hub/migrations`     | `MigrationRunner` status + run/rollback                         |
+| Files                | `/hub/files`          | GridFS listing + delete                                         |
+| Config               | `/hub/config`         | full config, secrets masked                                     |
+| Auth Migration       | `/hub/auth-migration` | Legacy → IAM progress (BetterAuth, optional)                    |
+| Routes / Permissions | `/hub/routes`         | route + role + `@Restricted` map (Permissions module, optional) |
+| Error Codes          | `/hub/error-codes`    | de/en catalog (ErrorCode module, optional)                      |
+| Email Preview        | `/hub/emails`         | EJS templates rendered with sample data                         |
+| Mailbox              | `/hub/mailbox`        | captured outgoing mail (Mailpit replacement)                    |
+| AI                   | `/hub/ai`             | AI usage summary (AI module, optional)                          |
+
+Each panel has a `*.json` sidecar (the stable data contract) that the client polls. Optional sources
+degrade to an "unavailable" state instead of erroring.
+
+## Actions (mutating)
+
+Enabled by default (`actions: true`). Every mutating request requires the `X-Hub-Request: 1` header
+(CSRF defense) and destructive ones a server-validated `confirm` keyword:
+
+| Action                  | Endpoint                                   | Confirm      |
+| ----------------------- | ------------------------------------------ | ------------ |
+| Run pending migrations  | `POST /hub/actions/migrations/run`         | `RUN`        |
+| Rollback last migration | `POST /hub/actions/migrations/down`        | `DOWN`       |
+| Delete GridFS file      | `DELETE /hub/actions/files/:id`            | the filename |
+| Cron start/stop/trigger | `POST /hub/actions/cron/:name/:action`     | the job name |
+| Clear collector buffer  | `POST /hub/actions/collectors/:name/clear` | `CLEAR`      |
+| Send test mail          | `POST /hub/actions/email/test`             | —            |
+
+Every action writes an audit line: `[HUB-ACTION] <action> by user <id>`.
+
+## Security
+
+- **Auth**: the DATA sidecars (`*.json`) and all actions are `@Roles(RoleEnum.ADMIN)` (configurable
+  via `hub.roles`; `false` = public — dangerous). The **shell** (page routes) is public chrome only —
+  it shows a **login form** when the data is 401, so the Hub is self-sufficient: an admin can sign in
+  directly at the API (email/password → `loginEndpoint`, default `/iam/sign-in/email` → session cookie)
+  without the frontend, with a token-paste fallback for cookie-less setups. In fullstack, a
+  cross-subdomain session cookie from the app login already authenticates `/hub` — no separate login.
+  A **"Sign out"** button in the topbar POSTs to `hub.logoutEndpoint` (default `/iam/sign-out`),
+  clears the session cookie + any pasted token, and returns to the login gate. The logout endpoint is
+  delivered only in the ADMIN-gated `session.json` payload, never in the public shell.
+  - **Public-shell trade-off (by design):** because the shell must render before authentication, its
+    HTML source reveals the panel structure, the environment name (shown on the login card) and any
+    configured external links (`hub.links.*`) to an unauthenticated request. This is intentional — the
+    panel structure is already discoverable via the public `hub.js` — and carries no data: every
+    `*.json` sidecar and every action stays ADMIN-gated. Do not place secrets in `hub.links.*` (e.g.
+    an internal Mailpit URL) if the shell's origin is reachable by untrusted clients.
+- **Action errors**: mutating actions return plain admin-facing messages (not `ErrorCode` catalog
+  entries) by design — the `ErrorCode` i18n module is optional and the Hub cannot hard-depend on it.
+  The messages are centralized in `hub-action-messages.ts` (`HubActionMessage`) so the wording stays
+  consistent and reviewable in one place.
+- **CSP**: strict per-request nonce; no `unsafe-inline`; `X-Frame-Options: DENY`; `no-store`.
+- **Secrets**: the config viewer deep-clones and masks by key pattern + `security.secretFields`.
+- **Interceptor safety**: sidecars return pre-serialized JSON strings, so the global response
+  interceptors never walk/mutate live config.
+- **Mailbox guard**: `mode: 'capture'` throws at startup in any **reachable** environment (anything
+  whose `env` is not `local`/`development`/`test`/`ci`/`e2e`) — it suppresses outgoing mail.
+- **Public-access guard**: `roles: false` (no auth check — public config viewer, logs and destructive
+  actions) throws at startup in any **reachable** environment unless `hub.allowPublicAccessInProduction:
+true` is set explicitly. This closes the single most dangerous Hub misconfiguration (a `roles: false`
+  copied from a local config into a reachable environment). The reachable check is fail-safe: it treats
+  every env name except the known local/test set as reachable, so a custom name (`prod`, `preprod`,
+  `staging-2`, …) cannot bypass it. Only acknowledge public access behind a fully-controlled network
+  boundary (VPN / IP allow-list / authenticating reverse proxy).
+- **No-guard warning**: the Hub registers no guard of its own — its ADMIN gate is enforced by the
+  app-wide roles guard from BetterAuth (IAM) or the legacy Auth module. If the Hub is enabled and
+  gated but neither is active (and you have not registered your own `APP_GUARD`), `CoreModule` logs a
+  loud startup warning, because nothing would then enforce the gate.
+- **CSRF**: mutating actions require the `X-Hub-Request` custom header, which forces a CORS preflight
+  that a restrictive allowlist rejects for foreign origins — **that header** (not the type-to-confirm
+  keyword, which is public UX safety, not a token) is the CSRF barrier. It holds with the default
+  `SameSite=Lax` session cookie or Bearer-token auth. Do NOT combine `cors.allowAll: true` with a
+  `SameSite=None` cookie (cross-subdomain fullstack): that lets any origin pass the preflight — pin
+  `cors` to your `appUrl` instead.
+- **Redaction is best-effort (ADMIN-only surfaces)**: the config viewer masks by key pattern +
+  `security.secretFields` (a secret under an unusual key can slip); the logs/queries collectors and
+  the copy-mode mailbox redact patterned secrets (JWT / Bearer / `key=value` / cookie / reset-link
+  path tokens) but cannot catch an arbitrary value logged without a recognizable shape. All are
+  ADMIN-gated — treat Hub access as equivalent to config/log read access.
+
+### Routes / Permissions panel vs. the standalone `/permissions` endpoint
+
+The **Routes / Permissions** panel renders the same data as the standalone permissions module — the
+full security map (every route + its required roles + `@Restricted` field rules) — but _inside_ the
+Hub, so it inherits the Hub's ADMIN gate, per-environment opt-in and strict CSP. It reuses the
+permissions **scanner** (`CorePermissionsService`), so it needs the `permissions` module enabled
+(`config.permissions`); otherwise the panel degrades to an "unavailable" state.
+
+The two surfaces are **independent** and answer the common "how do I reach it?" questions:
+
+| Situation                                       | How to reach the report                                                                                                                                                                                                                                                    |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hub **on**, `permissions` **on**                | Hub → **Routes / Permissions** panel (ADMIN, login-gated by the Hub). The standalone `/permissions` also works per its own `role` (default ADMIN).                                                                                                                         |
+| Hub **off**, `permissions` **on** (ADMIN)       | The standalone `/permissions` is ADMIN-gated but has **no login page** — reach it with an ADMIN **session cookie** (be logged in via the app) or a **bearer token** (`Authorization: Bearer <jwt>` from `POST /iam/sign-in/email`), exactly like any other ADMIN endpoint. |
+| Hub **off**, want frictionless **local** access | Set `permissions: { role: false }` — public, no auth. Legitimate **only** on a local, non-network-reachable machine, as a conscious opt-in. Never ship it to a reachable environment: the report is a reconnaissance goldmine.                                             |
+| `permissions` **off**                           | No report anywhere: `/permissions` is not registered (404) and the Hub panel shows "unavailable".                                                                                                                                                                          |
+
+**Security note:** the permissions report exposes your entire authorization model. Keep it ADMIN
+(the default) everywhere it could be reachable; use `role: false` only behind a network boundary you
+fully control. In production the framework's own config does not register the permissions module at all.
+
+## Collectors
+
+Three in-memory ring buffers (fixed capacity, no timers, per-app-instance — parallel-test-safe):
+
+- **Logs** — installs a chaining `Logger.overrideLogger()` delegate (no main.ts change), restored on shutdown.
+- **Traces** — an Express middleware registered only when enabled (zero cost otherwise).
+- **Queries** — MongoDB driver command monitoring; records value-free query SHAPES (N+1 templates), never values.
+  Enabling it opts the driver into `monitorCommands` from `core.module.ts`.
+
+## Overrides
+
+```typescript
+CoreModule.forRoot(envConfig, {
+  hub: { service: MyHubService, htmlService: MyHubHtmlService },
+});
+```
+
+Fields: `controller`, `actionsController`, `service`, `htmlService`, `actionsService`.
+
+See [INTEGRATION-CHECKLIST.md](./INTEGRATION-CHECKLIST.md) for setup in a consumer project.

package/src/core/modules/hub/core-hub-actions.controller.ts

@@ -0,0 +1,137 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  ForbiddenException,
+  Headers,
+  Param,
+  Post,
+} from '@nestjs/common';
+
+import { HubActionMessage } from './hub-action-messages';
+import { CoreHubActionsService } from './services/core-hub-actions.service';
+
+/** Body shape shared by the confirm-guarded actions. */
+interface ConfirmBody {
+  confirm?: string;
+}
+
+/**
+ * The Hub's mutating actions (migrations, file delete, cron control, buffer clears, test mail).
+ *
+ * Registered as a SEPARATE controller only when `hub.actions !== false`, so disabling actions simply
+ * removes the routes (404). Path + roles metadata are assigned at runtime in `CoreHubModule.forRoot()`
+ * exactly like the read controller.
+ *
+ * Every mutating request must carry the `X-Hub-Request: 1` header (CSRF defense in depth: a custom
+ * header makes the request non-simple, so a cross-origin attempt triggers a CORS preflight the
+ * framework will not approve). Destructive actions additionally require a server-validated `confirm`
+ * keyword that the UI makes the operator type.
+ *
+ * Overridable via `overrides.hub.actionsController`.
+ */
+@Controller()
+export class CoreHubActionsController {
+  constructor(protected readonly actions: CoreHubActionsService) {}
+
+  @Post('actions/collectors/:name/clear')
+  async clearCollector(
+    @Param('name') name: string,
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    this.requireConfirm(body, 'CLEAR');
+    if (!['logs', 'mailbox', 'queries', 'traces'].includes(name)) {
+      throw new BadRequestException(HubActionMessage.unknownCollector);
+    }
+    return this.wrap(() =>
+      Promise.resolve(this.actions.clearBuffer(name as 'logs' | 'mailbox' | 'queries' | 'traces')),
+    );
+  }
+
+  @Post('actions/cron/:name/:action')
+  async cron(
+    @Param('name') name: string,
+    @Param('action') action: string,
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    if (!['start', 'stop', 'trigger'].includes(action)) {
+      throw new BadRequestException(HubActionMessage.unknownCronAction);
+    }
+    this.requireConfirm(body, name);
+    return this.wrap(() => Promise.resolve(this.actions.controlCron(name, action as 'start' | 'stop' | 'trigger')));
+  }
+
+  @Delete('actions/files/:id')
+  async deleteFile(
+    @Param('id') id: string,
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    if (!body?.confirm) {
+      throw new BadRequestException(HubActionMessage.confirmationFilenameRequired);
+    }
+    return this.wrap(() => this.actions.deleteFile(id, body.confirm as string));
+  }
+
+  @Post('actions/email/test')
+  async emailTest(
+    @Body() body: { locale?: string; template?: string; to?: string },
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    if (!body?.to) {
+      throw new BadRequestException(HubActionMessage.recipientRequired);
+    }
+    return this.wrap(() => this.actions.sendTestEmail(body.to as string, body.template, body.locale));
+  }
+
+  @Post('actions/migrations/down')
+  async migrationsDown(
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    this.requireConfirm(body, 'DOWN');
+    return this.wrap(() => this.actions.rollbackMigration());
+  }
+
+  @Post('actions/migrations/run')
+  async migrationsRun(
+    @Body() body: ConfirmBody,
+    @Headers('x-hub-request') hubHeader: string | undefined,
+  ): Promise<unknown> {
+    this.requireHubRequest(hubHeader);
+    this.requireConfirm(body, 'RUN');
+    return this.wrap(() => this.actions.runMigrations());
+  }
+
+  /** Validate the server-side confirmation keyword. */
+  protected requireConfirm(body: ConfirmBody, expected: string): void {
+    if (body?.confirm !== expected) {
+      throw new BadRequestException(HubActionMessage.confirmationKeywordMismatch(expected));
+    }
+  }
+
+  /** CSRF defense: mutating requests must carry the X-Hub-Request header. */
+  protected requireHubRequest(header: string | undefined): void {
+    if (!header) {
+      throw new ForbiddenException(HubActionMessage.missingHubRequestHeader);
+    }
+  }
+
+  /** Run an action, mapping domain errors to 400 (admin-facing plain message). */
+  protected async wrap(fn: () => Promise<unknown>): Promise<unknown> {
+    try {
+      const result = await fn();
+      return { ok: true, timestamp: new Date().toISOString(), ...(result as object) };
+    } catch (error) {
+      throw new BadRequestException(error instanceof Error ? error.message : HubActionMessage.actionFailed);
+    }
+  }
+}

package/src/core/modules/hub/core-hub-html.service.ts

@@ -0,0 +1,135 @@
+import { Inject, Injectable } from '@nestjs/common';
+
+import { HUB_CONFIG } from './hub.constants';
+
+/**
+ * Per-process cache-bust token for the client bundle (`hub.js?v=<token>`). It changes on every server
+ * start, so the browser refetches the script after a restart/redeploy (a dev code change is never
+ * masked by the immutable cache), while a single boot keeps the long-lived cache. The app version is
+ * deliberately NOT part of this public URL — it would leak the version to unauthenticated requests
+ * (the version is shown only in the ADMIN-gated, client-built topbar from session.json).
+ */
+const HUB_ASSET_TOKEN = Date.now().toString(36);
+import { getHubClientJs } from './helpers/hub-client-js.helper';
+import { escapeHtml, escapeJsString, HUB_NONCE_PLACEHOLDER } from './helpers/hub-shell.helper';
+import { ResolvedHubConfig } from './interfaces/hub-config.interface';
+
+/**
+ * Builds the Hub's single, self-contained HTML shell. Every page route serves the same shell (the
+ * client router picks the active panel from the URL), so this is stateless apart from the injected
+ * config. All server-provided values are escaped; the auth token (when present) is embedded as a JS
+ * string so sidecar fetches carry it in cookie-less setups.
+ *
+ * Overridable: a project may replace it via `overrides.hub.htmlService` to re-skin the cockpit.
+ */
+@Injectable()
+export class CoreHubHtmlService {
+  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {}
+
+  /** The shared client runtime script — served verbatim from `GET /{hub}/hub.js`. */
+  buildClientScript(): string {
+    return getHubClientJs();
+  }
+
+  /**
+   * Build the full shell HTML with `__CSP_NONCE__` placeholders. The controller replaces the
+   * placeholders per request via `injectNonce()`.
+   *
+   * @param authHeader - the incoming `Authorization` header, embedded so client fetches can replay it
+   */
+  buildShell(authHeader?: string): string {
+    const base = '/' + this.config.path;
+
+    const bootstrap = [
+      `window.__HUB_BASE__='${escapeJsString(base)}';`,
+      `window.__HUB_POLL_MS__=${Number(this.config.pollIntervalMs) || 5000};`,
+      `window.__HUB_LOGIN__='${escapeJsString(this.config.loginEndpoint)}';`,
+      authHeader ? `window.__HUB_TOKEN__='${escapeJsString(authHeader)}';` : '',
+    ].join('');
+
+    // SECURITY (self-sufficient login): the shell is PUBLIC because it must render the login form
+    // before authentication. It therefore carries NO cockpit chrome — no navigation, no environment
+    // badge, no version, no external links. The client builds all of that ONLY after a successful
+    // ADMIN auth check, from the ADMIN-gated `session.json` payload. So an unauthenticated request to
+    // any /hub page reveals nothing of the Hub's structure; #hub-app stays empty until login.
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Hub · nest-server</title>
+  <style nonce="${HUB_NONCE_PLACEHOLDER}">${this.css()}</style>
+</head>
+<body class="hub-locked">
+  <div id="hub-gate" class="hub-gate"></div>
+  <div id="hub-app"></div>
+  <dialog id="hub-confirm" class="hub-dialog"></dialog>
+  <script nonce="${HUB_NONCE_PLACEHOLDER}">${bootstrap}</script>
+  <script nonce="${HUB_NONCE_PLACEHOLDER}" src="${escapeHtml(base)}/hub.js?v=${HUB_ASSET_TOKEN}"></script>
+</body>
+</html>`;
+  }
+
+  protected css(): string {
+    return `
+:root{--bg:#0b0d12;--panel:#141821;--panel2:#1b212d;--border:#242c3a;--text:#e6ebf2;--muted:#8b97a8;--accent:#4f8cff;--ok:#3fb950;--warn:#d29922;--err:#f85149}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--text);font:14px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif}
+.hub-layout{display:flex;min-height:100vh}
+.hub-nav{width:230px;flex:0 0 230px;background:var(--panel);border-right:1px solid var(--border);padding:16px 10px;overflow-y:auto}
+.hub-brand{font-weight:700;font-size:18px;padding:4px 10px 14px;display:flex;align-items:center;gap:8px}
+.hub-env{font-size:10px;text-transform:uppercase;letter-spacing:.05em;padding:2px 6px;border-radius:4px;background:var(--panel2);color:var(--muted)}
+.hub-env-production{background:#3d1418;color:#ff7b72}
+.hub-nav h3{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);margin:16px 10px 4px}
+.hub-nav a{display:block;padding:6px 10px;border-radius:6px;color:var(--text);text-decoration:none;font-size:13px}
+.hub-nav a:hover{background:var(--panel2)}
+.hub-nav a.active{background:var(--accent);color:#fff}
+.hub-nav a.hub-nav-disabled{opacity:.38;cursor:not-allowed}
+.hub-nav a.hub-nav-disabled:hover{background:none}
+.hub-nav a.hub-ext::after{content:' ↗';color:var(--muted)}
+.hub-main{flex:1;min-width:0;display:flex;flex-direction:column}
+.hub-topbar{display:flex;align-items:center;justify-content:space-between;padding:14px 22px;border-bottom:1px solid var(--border)}
+.hub-topbar h1{font-size:18px;margin:0}
+.hub-meta{color:var(--muted);font-size:12px;display:flex;align-items:center;gap:8px}
+.hub-dot{width:9px;height:9px;border-radius:50%;display:inline-block;background:var(--muted)}
+.hub-dot-ok{background:var(--ok)}.hub-dot-err{background:var(--err)}
+.hub-content{padding:22px;overflow:auto}
+.hub-tiles{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:12px;margin-bottom:20px}
+.hub-tile{background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:14px}
+.hub-tile-label{color:var(--muted);font-size:12px}
+.hub-tile-value{font-size:22px;font-weight:600;margin-top:4px}
+.hub-tile-value.ok{color:var(--ok)}.hub-tile-value.warn{color:var(--warn)}.hub-tile-value.err{color:var(--err)}
+.hub-tile-sub{color:var(--muted);font-size:11px;margin-top:4px}
+.hub-table{width:100%;border-collapse:collapse;background:var(--panel);border:1px solid var(--border);border-radius:8px;overflow:hidden}
+.hub-table th{text-align:left;padding:8px 12px;background:var(--panel2);color:var(--muted);font-size:12px;font-weight:600;cursor:pointer}
+.hub-table td{padding:8px 12px;border-top:1px solid var(--border);font-size:13px}
+.hub-table tr:hover td{background:var(--panel2)}
+.hub-json{background:var(--panel);border:1px solid var(--border);border-radius:8px;padding:14px;overflow:auto;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre;max-width:100%}
+.hub-empty{color:var(--muted);padding:40px;text-align:center;border:1px dashed var(--border);border-radius:8px}
+.hub-btn{background:var(--panel2);color:var(--text);border:1px solid var(--border);border-radius:6px;padding:6px 12px;font-size:13px;cursor:pointer}
+.hub-btn:hover{border-color:var(--accent)}
+.hub-btn:disabled{opacity:.5;cursor:not-allowed}
+.hub-btn-primary{background:var(--accent);border-color:var(--accent);color:#fff}
+.hub-btn-danger{background:var(--err);border-color:var(--err);color:#fff}
+.hub-signout{padding:4px 10px;font-size:12px;margin-left:4px}
+.hub-input{width:100%;background:var(--bg);border:1px solid var(--border);border-radius:6px;padding:8px;color:var(--text);margin:8px 0;font-size:13px}
+.hub-dialog{background:var(--panel);color:var(--text);border:1px solid var(--border);border-radius:12px;padding:20px;max-width:440px;width:90%}
+.hub-dialog::backdrop{background:rgba(0,0,0,.6)}
+.hub-dialog h3{margin:0 0 8px}
+.hub-dialog-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:12px}
+.hub-hint{color:var(--muted);font-size:12px}
+.hub-chip{display:inline-block;padding:1px 7px;border-radius:10px;font-size:11px;background:var(--panel2);color:var(--muted)}
+.hub-chip-ok{background:#132d1c;color:var(--ok)}.hub-chip-warn{background:#2d2611;color:var(--warn)}.hub-chip-err{background:#3d1418;color:var(--err)}
+.hub-toast{position:fixed;bottom:20px;right:20px;background:var(--panel2);border:1px solid var(--accent);color:var(--text);padding:12px 16px;border-radius:8px;font-size:13px;z-index:9999;box-shadow:0 6px 20px rgba(0,0,0,.4)}
+.hub-toast-err{border-color:var(--err)}
+/* Auth gate: nothing of the app is visible until authenticated. The client builds the layout into
+   #hub-app only after a successful auth check, so body.hub-locked just hides the (empty) app root. */
+.hub-gate{display:none;position:fixed;inset:0;background:var(--bg);z-index:100;align-items:center;justify-content:center;padding:20px}
+.hub-locked .hub-gate{display:flex}
+.hub-locked #hub-app{display:none}
+.hub-gate-card{background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:28px;width:360px;max-width:100%}
+.hub-gate-card h2{margin:0 0 4px}
+.hub-gate-brand{font-weight:700;font-size:20px;margin-bottom:18px;display:flex;align-items:center;gap:8px}
+`;
+  }
+}