@dudousxd/nestjs-durable-dashboard 0.30.0 → 0.32.0

package/dist/server/index.d.ts

@@ -3,7 +3,42 @@ import { RunGateway, StateStore, WorkflowEngine, RunQuery, RunListItem, DurableT
 export { RunDetail } from '@dudousxd/nestjs-durable-core';
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
-import { DynamicModule, StreamableFile } from '@nestjs/common';
+import { DynamicModule, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, ExecutionContext, StreamableFile } from '@nestjs/common';
+
+/** The session user the host `login` hook returns to mint a cookie. */
+interface DashboardSessionUser {
+    id: string;
+    name?: string;
+    roles?: string[];
+}
+
+/** Host hook validating submitted credentials from the built-in login page. */
+type LoginHook = (username: string, password: string) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/**
+ * Author-facing `dashboardAuth` option on `DurableDashboardModule.forRoot`/`forRootAsync`. Gates
+ * BOTH the SPA (a full-page navigation redirected to a server-rendered login page) and the JSON
+ * API (a plain `401`) behind a signed session cookie, mirroring `@dudousxd/nestjs-telescope`'s
+ * `dashboardAuth` mechanism (same HMAC-SHA256 cookie, same fail-closed validation). Unlike
+ * Telescope's dashboard — a client-rendered SPA that can grow its own login screen — the durable
+ * dashboard's bundled React app stays untouched: the login screen here is a small, dependency-free
+ * server-rendered HTML page (`GET <basePath>/login`), so gating the SPA shell itself with a real
+ * redirect doesn't require rebuilding or extending the Vite bundle.
+ */
+interface DashboardAuthOptions {
+    /** REQUIRED HMAC-SHA256 signing key. Missing/empty => boot error (fail closed). */
+    secret: string;
+    /** Cookie TTL as a duration string (`'8h'`, `'30m'`, `'7d'`). Default `'8h'`. */
+    ttl?: string;
+    /** Validates submitted username/password; return the session user, or `null` to deny. Thrown
+     *  errors are treated as a denial (logged once, never surfaced to the client). */
+    login: LoginHook;
+}
+/** Resolved, validated `dashboardAuth` config shared by the guards, auth controller, and login page. */
+interface ResolvedDashboardAuth {
+    secret: string;
+    ttlMs: number;
+    login: LoginHook;
+}
 
 /**
  * Read-model and actions backing the control-plane UI. Run-facing ops (list/detail/retry/cancel/
@@ -142,6 +177,41 @@ declare class DurableApiController {
     update(id: string, name: string, body: unknown): Promise<_dudousxd_nestjs_durable_core.UpdateResult>;
 }
 
+interface LoginBody {
+    username?: unknown;
+    password?: unknown;
+    returnTo?: unknown;
+}
+/**
+ * Mints/clears the `dashboardAuth` session cookie and serves the built-in login page. Mounted
+ * under `basePath` alongside `DurableUiController` (see `DurableDashboardModule.forRoot`), but on
+ * a SEPARATE controller so it is never itself behind `DurableUiSessionGuard` — these endpoints
+ * CREATE the session that guard checks for. `@Optional()` on both injections: this controller is
+ * only registered when `dashboardAuth` might be configured (a static `forRoot({ dashboardAuth })`
+ * or any `forRootAsync`), but the resolved value can still be `null` at runtime for the async case
+ * — every handler below re-checks it and 404s rather than assuming it is set.
+ */
+declare class DurableAuthController {
+    private readonly auth;
+    private readonly basePath;
+    private readonly logger;
+    /** Warn once so a throwing `login` hook doesn't spam logs on every failed attempt. */
+    private warnedOnHookThrow;
+    constructor(auth: ResolvedDashboardAuth | null, basePath: string);
+    loginPage(): string;
+    login(body: LoginBody, request: unknown, response: unknown): Promise<{
+        redirectTo: string;
+    }>;
+    logout(request: unknown, response: unknown): void;
+    private requireAuth;
+    /**
+     * Run the host's `login` hook defensively: a throw is treated as a denial (uniform failure) and
+     * warn-logged once, so a buggy hook never 500s the endpoint into a stack-trace leak nor floods
+     * the logs on repeated bad attempts.
+     */
+    private runLoginHook;
+}
+
 interface DurableDashboardOptions {
     /**
      * Where the SPA (UI) is served. Default `/durable`. This is a page route — keep it out of an
@@ -154,17 +224,141 @@ interface DurableDashboardOptions {
      * while the UI stays at `basePath`.
      */
     apiBasePath?: string;
+    /**
+     * Guard classes fronting BOTH dashboard controllers (the SPA at `basePath` and its JSON API at
+     * `apiBasePath`). Stamped onto each controller via `@nestjs/common`'s own `@UseGuards` metadata key
+     * — REPLACE semantics, so a second `forRoot(...)` call overwrites (not appends to) whatever a prior
+     * call stamped, same as re-applying `@UseGuards` by hand. Omit to leave the routes unguarded (the
+     * host fronts them another way, e.g. a global guard or reverse-proxy auth).
+     *
+     * A guard's own DEPENDENCIES resolve from this module's `imports` (see {@link imports}) — the
+     * dashboard module has no application context of its own to pull them from otherwise.
+     *
+     * Auth reality for the two mount points: `apiBasePath` is fetched by the SPA's own JS (an XHR/fetch
+     * from the same origin), so a guard reading a bearer/`Authorization` header there works exactly like
+     * any other API route. `basePath` (the UI shell, `DurableUiController.index()`) is a full-page
+     * navigation — the BROWSER issues that GET directly (typing the URL, a bookmark, a link click), so
+     * there is no custom header to read: only whatever ambient credential the browser sends by default
+     * (a cookie, or nothing) reaches the guard there. A guard that only checks an `Authorization` header
+     * will 403 the page shell while the API calls it makes right after would have passed — put session
+     * auth behind a cookie (or front the UI mount with your reverse proxy / SSO instead) if you need the
+     * shell itself gated.
+     */
+    guards?: Type<CanActivate>[];
+    /**
+     * Extra `imports` merged into the dashboard's dynamic module — the DI resolution path for a class
+     * passed to {@link guards} (or any other provider the controllers need reachable). Typically the
+     * host's own auth module, e.g. `imports: [AuthModule]` alongside `guards: [JwtAuthGuard]`.
+     */
+    imports?: DynamicModule['imports'];
+    /**
+     * Gate the console (the SPA at `basePath` AND its JSON API at `apiBasePath`) behind a built-in,
+     * cookie-session login — no infra, no changes to the bundled React SPA. Unlike
+     * `@dudousxd/nestjs-telescope`'s `dashboardAuth` (a client-rendered login screen inside its SPA),
+     * the durable dashboard's login page is small, dependency-free, server-rendered HTML served
+     * directly by `DurableAuthController` at `GET <basePath>/login` — the SPA bundle itself never
+     * changes. A missing/invalid/expired session redirects a page-level request (a full-page
+     * navigation to `basePath`) to that login page with `?returnTo=<original url>`; an API request
+     * (`apiBasePath`, fetched by the SPA's own JS) gets a plain `401` instead.
+     *
+     * Auth here is mount-level and role-agnostic: this option (and the guards/controller it wires up)
+     * has no notion of control-plane vs tenant role (see the durable dashboard's topology note in
+     * `dashboard.service.ts`) — nothing role-specific changes based on who logs in.
+     *
+     * Composes with {@link guards}: when both are set, a request must pass the built-in session check
+     * AND every guard in `guards` — the SAME logical-AND semantics `@UseGuards` already gives multiple
+     * guards, since the built-in guard is simply prepended to whatever `guards` you pass. Omit to leave
+     * the console open (today's behavior, unchanged byte-for-byte) — front it with `guards`, a global
+     * guard, or a reverse proxy instead.
+     *
+     * See {@link DashboardAuthOptions} for the `secret`/`ttl`/`login` shape, and `forRootAsync` /
+     * {@link DurableDashboardAsyncOptions.useDashboardAuth} when the `login` hook needs DI (e.g. an
+     * `EntityManager` to look up an admin user).
+     */
+    dashboardAuth?: DashboardAuthOptions;
 }
-/** Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. */
+/**
+ * Async variant of {@link DurableDashboardOptions}. The mount paths and `guards` stay static (the
+ * router and guard metadata are bound at module-DEFINITION time — the same constraint `forRoot`
+ * already has), but `dashboardAuth` is built by an injected factory, so its `login` hook can reach
+ * your DB/services. Returning `undefined` from `useDashboardAuth` leaves the console open, exactly
+ * like omitting `dashboardAuth` from `forRoot`.
+ */
+interface DurableDashboardAsyncOptions {
+    basePath?: string;
+    apiBasePath?: string;
+    guards?: Type<CanActivate>[];
+    imports?: DynamicModule['imports'];
+    /** Providers injected into `useDashboardAuth`, in order. Shared with a `guards` class's own deps. */
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    /** Build the `dashboardAuth` config from injected deps (or `undefined` to leave the console open). */
+    useDashboardAuth: (...deps: any[]) => DashboardAuthOptions | undefined | Promise<DashboardAuthOptions | undefined>;
+}
+/**
+ * Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. Dynamic:
+ * guards are DI-instantiated by the CONTROLLER's host module, so this module — not the outer wrapper
+ * — must carry the guard classes as providers plus the host's `imports` that resolve their
+ * dependencies. A static module here made `guards: [SomeGuardWithDeps]` fail at boot with "Nest can't
+ * resolve dependencies ... in the DurableApiModule context" even when the host passed the right
+ * `imports` to `forRoot` (mirrors `@dudousxd/nestjs-agent-dashboard`'s `AgentApiModule`).
+ */
 declare class DurableApiModule {
+    static register(options: {
+        imports?: DynamicModule['imports'];
+        guards?: Type<CanActivate>[];
+        /** Provider for `DASHBOARD_AUTH` — a `useValue` (`forRoot`) or a `useFactory` (`forRootAsync`). */
+        authProvider: Provider;
+        /** Whether the built-in `DurableApiSessionGuard` should be stamped on `DurableApiController`
+         *  (true whenever `dashboardAuth` was set, or unconditionally for `forRootAsync`, where it's
+         *  resolved at runtime and is a no-op if it ends up unconfigured). */
+        authMayBeConfigured: boolean;
+    }): DynamicModule;
 }
 /**
  * Mounts the control plane: the bundled React SPA at `basePath` and its JSON API at `apiBasePath`
- * (default `<basePath>/api`). Import via `DurableDashboardModule.forRoot(...)` alongside
- * `DurableModule` (global), so it resolves the engine and store. Front the routes with a guard.
+ * (default `<basePath>/api`). Import via `DurableDashboardModule.forRoot(...)` (or `forRootAsync`
+ * when `dashboardAuth`'s `login` hook needs injected services) alongside `DurableModule` (global),
+ * so it resolves the engine and store. Front the routes with the first-class `guards` option
+ * (plus `imports` for the guards' own dependencies) — see {@link DurableDashboardOptions.guards} —
+ * or with the built-in `dashboardAuth` cookie login, or both.
  */
 declare class DurableDashboardModule {
     static forRoot(options?: DurableDashboardOptions): DynamicModule;
+    static forRootAsync(options: DurableDashboardAsyncOptions): DynamicModule;
+    /** Shared wiring: static routing + the API module, with `dashboardAuth` supplied by `authProvider`. */
+    private static build;
+}
+
+/**
+ * Gates `DurableUiController` (the SPA shell + assets, a full-page browser navigation) on a valid
+ * `dashboardAuth` session cookie. A no-op (always `true`) when `dashboardAuth` was not configured
+ * — see `DurableDashboardModule.forRoot`'s `dashboardAuth` doc. Missing/invalid/expired session =>
+ * a `302` to the built-in login page carrying `?returnTo=<original url>`, via
+ * `DashboardLoginRedirectException` (see that file for why a guard can't just call
+ * `response.redirect()` and return `false`).
+ *
+ * Auth is mount-level and role-agnostic: this guard has no notion of control-plane vs tenant
+ * (see the durable dashboard's topology note in `dashboard.service.ts`) — it only ever answers
+ * "is there a valid dashboard session", nothing role-specific changes here.
+ */
+declare class DurableUiSessionGuard implements CanActivate {
+    private readonly auth;
+    private readonly basePath;
+    constructor(auth: ResolvedDashboardAuth | null, basePath: string);
+    canActivate(context: ExecutionContext): boolean;
+}
+/**
+ * Gates `DurableApiController` (the JSON API the SPA fetches) on a valid `dashboardAuth` session
+ * cookie. A no-op (always `true`) when `dashboardAuth` was not configured. Missing/invalid/expired
+ * session => a plain `401` (the API is called via `fetch`, never a browser navigation, so a
+ * redirect would just fail the request anyway — the caller reads the status code, not HTML).
+ *
+ * Mount-level and role-agnostic, same as `DurableUiSessionGuard` above.
+ */
+declare class DurableApiSessionGuard implements CanActivate {
+    private readonly auth;
+    constructor(auth: ResolvedDashboardAuth | null);
+    canActivate(context: ExecutionContext): boolean;
 }
 
 /** DI token carrying the UI mount base (e.g. `/durable`). */
@@ -175,6 +369,12 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * Serves the bundled control-plane SPA at the configured base (+ hashed assets at `<base>/assets`).
  * The path comes from `RouterModule` (set by `DurableDashboardModule.forRoot({ basePath })`), so the
  * controller routes are relative.
+ *
+ * `@UseFilters(DashboardLoginRedirectFilter)` is permanent (present regardless of whether
+ * `dashboardAuth` is configured): it only ever activates for a `DashboardLoginRedirectException`,
+ * which `DurableUiSessionGuard` only throws when it is ALSO stamped on this controller (see
+ * `DurableDashboardModule.forRoot`) — so leaving it decorated here is inert, not a behavior change,
+ * when `dashboardAuth` is absent.
  */
 declare class DurableUiController {
     private readonly basePath;
@@ -185,4 +385,4 @@ declare class DurableUiController {
     asset(file: string): StreamableFile;
 }
 
-export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DashboardService, DurableApiController, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController };
+export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type DashboardSessionUser, DurableApiController, DurableApiModule, DurableApiSessionGuard, DurableAuthController, type DurableDashboardAsyncOptions, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiSessionGuard };