@dudousxd/nestjs-durable-dashboard 0.54.0 → 0.55.0

package/dist/server/index.d.cts

@@ -5,104 +5,7 @@ import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
 import { FilterRunner } from '@dudousxd/nestjs-filter';
-import { CanActivate, ExecutionContext, Provider, Logger, DynamicModule, Type, InjectionToken, OptionalFactoryDependency, 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 for Mode A — validates the host's own auth on the raw request. */
-type SessionHook = (request: unknown) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
-/** Host hook for Mode B — validates submitted credentials from the built-in login page. */
-type LoginHook = (username: string, password: string) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
-/**
- * Re-checks a LIVE session when the cookie is slid forward. Runs at most once per `ttl/2` per
- * session, so a DB round-trip here is cheap — this holds even under concurrent traffic: N parallel
- * requests carrying the same past-half-life cookie share ONE call (see `revalidateOnce` in
- * `session-cookie-io.ts`), not N. Return `false` to revoke (the cookie is cleared and the request
- * denied). Distinct from `session`: that hook reads the host's auth off a fresh request, which a
- * console XHR does not carry — this one receives the already-minted session.
- */
-type RevalidateHook = (session: DashboardSessionUser) => Promise<boolean> | boolean;
-/** What `unauthenticatedPage` receives. An object (not positional args) so fields can be added later. */
-interface UnauthenticatedPageContext {
-    /**
-     * The platform-native request — Express' `Request`, Fastify's `FastifyRequest`. Typed `unknown`
-     * for the same reason `SessionHook`'s is: this package refuses to depend on either platform.
-     * Cast it to whatever your app actually runs on.
-     */
-    request: unknown;
-    /**
-     * The platform-native response. The hook OWNS it: it must write AND end it (`res.render(...)`,
-     * `res.status(401).send(...)`, an Inertia render, ...). If the hook returns without writing, the
-     * library falls back to its own built-in page rather than leaving the request hanging.
-     */
-    response: unknown;
-    /** Where this console is mounted (e.g. `/durable`) — useful for a "back to the console" link. */
-    basePath: string;
-}
-/**
- * Host-owned page for an unauthenticated full-page navigation to the console.
- *
- * The built-in page cannot know who hosts the console, so it can only say "open this console from
- * your application" in the abstract — it can't name the launcher, link to it, or look like the rest
- * of the host's product. This hook hands the whole response to the host instead: render through
- * your own template engine, your own Inertia page, whatever. The page is served AT the console's
- * own URL, so `/durable` stays `/durable`.
- *
- * Deliberately NOT a replacement for Mode B's built-in login form. A host that wants its own login
- * UI uses Mode A plus this hook, and posts to `<basePath>/session` from its own page — the mint
- * endpoint is the supported primitive for that.
- *
- * Fail-closed by construction: it only ever runs on a request that has ALREADY been denied. A hook
- * that throws, or that returns without writing, falls back to the built-in page — it cannot let
- * anyone in.
- */
-type UnauthenticatedPageHook = (context: UnauthenticatedPageContext) => void | Promise<void>;
-type AuthMode = 'session' | 'login';
-/**
- * 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). Two ways to
- * mint that cookie: Mode A (`session`) — the host frontend, already carrying its own auth, POSTs
- * to `<basePath>/session` and the host hook decides; or Mode B (`login`) — the built-in,
- * dependency-free server-rendered login page (`GET <basePath>/login`). At least one of the two is
- * required so an un-mintable gate is a boot error, not a silently-open (or silently-stuck) console.
- */
-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;
-    /** Mode A: validates the host's own auth on the raw request POSTed to `<basePath>/session`;
-     *  return the session user, or `null` to deny. Thrown errors are treated as a denial (logged
-     *  once, never surfaced to the client). */
-    session?: SessionHook;
-    /** Mode B: validates submitted username/password from the built-in login page; return the
-     *  session user, or `null` to deny. Thrown errors are treated as a denial (logged once, never
-     *  surfaced to the client). */
-    login?: LoginHook;
-    /** Re-checks a live session on sliding renewal; see `RevalidateHook`. Not a mode — it cannot
-     *  mint a session, only revoke one already minted by `session`/`login`. */
-    revalidate?: RevalidateHook;
-    /** Renders the host's own page for an unauthenticated navigation, in place of the built-in
-     *  "open this console from your application" card; see `UnauthenticatedPageHook`. */
-    unauthenticatedPage?: UnauthenticatedPageHook;
-}
-/** Resolved, validated `dashboardAuth` config shared by the guards, auth controller, and login page. */
-interface ResolvedDashboardAuth {
-    secret: string;
-    ttlMs: number;
-    modes: AuthMode[];
-    session?: SessionHook;
-    login?: LoginHook;
-    revalidate?: RevalidateHook;
-    unauthenticatedPage?: UnauthenticatedPageHook;
-}
+import { DynamicModule, StreamableFile } from '@nestjs/common';
 
 /**
  * Read-model and actions backing the control-plane UI. Run-facing ops (list/detail/retry/cancel/
@@ -286,14 +189,20 @@ declare class RunQueryDraft {
 }
 
 /**
- * JSON API consumed by the control-plane SPA. Mounted at `apiBasePath` (set by RouterModule).
+ * JSON API consumed by the control-plane SPA. The mounted {@link DurableApiController} sits at
+ * `apiBasePath` (set by RouterModule).
+ *
+ * This base is what a host EXTENDS to serve the API from a controller of its own (with
+ * `forRoot({ routes: false, apiBasePath })`): `@Controller('<apiBasePath>') class MyConsoleApi
+ * extends DurableApiControllerBase {}`. It carries no guards and no `@nestjs/authorization` mark,
+ * so a subclass is protected only by what the host puts on it.
  *
  * The filter interceptor (what resolves `@ApplyFilter` into a query) is bound HERE rather than as
  * the app-wide `APP_INTERCEPTOR` that `FilterModule.forRoot()` registers: a library must not add a
  * global interceptor to its host, and on an app that already has one this would be the second copy,
  * running every filter in the app twice.
  */
-declare class DurableApiController {
+declare class DurableApiControllerBase {
     private readonly dashboard;
     private readonly runner;
     constructor(dashboard: DashboardService, runner: FilterRunner);
@@ -426,103 +335,13 @@ declare class DurableApiController {
     /** Deliver a validated `ctx.onUpdate` to a run; the body is the update argument. */
     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 per hook kind so a throwing hook doesn't spam logs on every failed attempt. */
-    private readonly warnedHooks;
-    constructor(auth: ResolvedDashboardAuth | null, basePath: string);
-    loginPage(): string;
-    login(body: LoginBody, request: unknown, response: unknown): Promise<{
-        redirectTo: string;
-    }>;
-    session(request: unknown, response: unknown): Promise<void>;
-    logout(request: unknown, response: unknown): void;
-    private requireAuth;
-    /**
-     * Run a host hook (`login` or `session`) defensively: a throw is treated as a denial (uniform
-     * failure) and warn-logged once PER KIND, so a buggy hook never 500s the endpoint into a
-     * stack-trace leak nor floods the logs on repeated bad attempts.
-     */
-    private runHook;
-}
-
-/** The env var the token gate reads when no `token` option is given. */
-declare const DURABLE_DASHBOARD_TOKEN_ENV = "DURABLE_DASHBOARD_TOKEN";
-/** DI token carrying the resolved {@link DashboardGate} (one per dashboard mount). */
-declare const DASHBOARD_GATE: unique symbol;
-/**
- * What the module knows about how the console is protected, captured at `forRoot`/`forRootAsync`
- * time. Everything that can change between module definition and boot (env vars, the async
- * `dashboardAuth` factory) is read later, in {@link resolveDashboardGate}.
- */
-interface DashboardGateOptions {
-    /** Host `guards` were passed (non-empty). */
-    hasGuards: boolean;
-    /** `allowUnauthenticated` as passed. */
-    allowUnauthenticated?: boolean;
-    /** `token` as passed (else `DURABLE_DASHBOARD_TOKEN` is read at boot). */
-    token?: string;
-}
-/**
- * How the gate treats every console request:
- *
- * - `delegated`: `guards` or `dashboardAuth` protect the console; the gate passes everything.
- * - `open`: `allowUnauthenticated: true`; the gate passes everything (warned at boot).
- * - `token`: a request must carry the token (`Authorization: Bearer`, `x-durable-token`, or
- *   `?token=` on GET/HEAD).
- * - `unconfigured`: nothing was configured outside production; the gate passes everything
- *   (warned at boot, because production will deny).
- * - `deny`: nothing was configured and `NODE_ENV=production`; every request is refused.
- */
-type DashboardGateMode = 'delegated' | 'open' | 'token' | 'unconfigured' | 'deny';
-interface DashboardGate {
-    mode: DashboardGateMode;
-    /** Set only when `mode === 'token'`. */
-    token?: string;
-}
-/**
- * Decide the gate mode. Precedence: `guards`/`dashboardAuth` (they are the gate) > a token > the
- * `allowUnauthenticated` opt-out > the environment default. A token beats `allowUnauthenticated`
- * because a configured secret is never silently ignored.
- */
-declare function resolveDashboardGate(options: DashboardGateOptions, auth: ResolvedDashboardAuth | null): DashboardGate;
-/** Log the one boot line the resolved gate calls for (nothing for a properly configured console). */
-declare function reportDashboardGate(gate: DashboardGate, options: DashboardGateOptions, logger?: Pick<Logger, 'warn' | 'error'>): void;
-/** The `DASHBOARD_GATE` provider: resolves once, after `DASHBOARD_AUTH`, and logs once. */
-declare function dashboardGateProvider(options: DashboardGateOptions): Provider;
 /**
- * Read the token from `Authorization: Bearer <token>`, `x-durable-token`, or (GET/HEAD only) a
- * `token` query param. The query channel is read-only on purpose: a `?token=` URL ends up in access
- * logs, `Referer` headers and browser history, and must never authorize a mutation.
+ * The JSON API controller `DurableDashboardModule.forRoot(...)` mounts at `apiBasePath`. The module
+ * puts the `@nestjs/authorization` open mark on THIS class (and `decorators` on a per-registration
+ * subclass of it), never on {@link DurableApiControllerBase}, so a host's own subclass of the base
+ * inherits none of them.
  */
-declare function readDashboardToken(request: unknown): string | undefined;
-/**
- * The fail-closed default gate, stamped on `DurableUiController` and `DurableApiController` (after
- * the built-in session guard, before host `guards`) whenever the module can't prove at definition
- * time that something else protects the console. It never gates `DurableAuthController`, so the
- * login/session/logout routes stay reachable. See {@link DashboardGateMode} for what each mode does.
- */
-declare class DurableDashboardGateGuard implements CanActivate {
-    private readonly gate;
-    constructor(gate: DashboardGate);
-    canActivate(context: ExecutionContext): boolean;
+declare class DurableApiController extends DurableApiControllerBase {
 }
 
 interface DurableDashboardOptions {
@@ -538,150 +357,76 @@ interface DurableDashboardOptions {
      */
     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. A non-empty `guards` counts as the
-     * console's authentication, so the fail-closed default gate steps aside (see
-     * {@link allowUnauthenticated}). If the host fronts the routes another way (a global guard,
-     * reverse-proxy auth), say so with `allowUnauthenticated: true` instead.
-     *
-     * 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]`.
+     * Extra `imports` merged into the dashboard's dynamic module: the DI resolution path for a guard
+     * passed through {@link decorators} (`UseGuards(...)`), whose dependencies resolve from the module
+     * that hosts the controller. Typically the host's own auth module, unless it is global.
      */
     imports?: DynamicModule['imports'];
     /**
-     * Gate the console (the SPA at `basePath` AND its JSON API at `apiBasePath`) behind a built-in,
-     * signed session cookie — no infra required. Two ways to mint it:
-     *
-     * - **Mode A (`session`, recommended)**: your host app already has its own auth (SSO/OIDC/
-     *   whatever) — the host frontend, carrying that auth, POSTs to `<basePath>/session`, your
-     *   `session` hook validates the raw request and returns the session user, and this library mints
-     *   its cookie from that. No credential this library understands ever exists; you keep your own
-     *   identity provider as the source of truth. A page-level request with no valid session (and only
-     *   Mode A configured) gets a small server-rendered instruction page telling the visitor to sign in
-     *   through your host app, since there is no login page to redirect to.
-     * - **Mode B (`login`, standalone fallback)**: no host frontend/IdP to lean on — the durable
-     *   dashboard serves its own small, dependency-free, server-rendered login page (`GET
-     *   <basePath>/login`, handled by `DurableAuthController`) and your `login` hook validates
-     *   submitted username/password. A missing/invalid/expired session redirects a page-level request
-     *   to that login page with `?returnTo=<original url>`.
-     *
-     * Either mode can be used alone, or both together (e.g. Mode A for normal use, Mode B as a
-     * break-glass fallback) — at least one is required, or `forRoot`/`forRootAsync` throws at boot
-     * (an un-mintable gate is a boot error, not a silently-open or silently-stuck console). An API
-     * request (`apiBasePath`, fetched by the SPA's own JS) always gets a plain `401` on a missing
-     * session, regardless of mode — the caller reads the status code, not HTML.
+     * Class decorators applied to BOTH controllers this module mounts (the SPA and its JSON API), the
+     * way `@nestjs/mcp`'s own `decorators` option works. Use it to hand the console to the official NestJS tooling, e.g.
+     * `[UseGuards(AuthenticationGuard), Can(ConsolePolicy, 'view')]` with `@nestjs/authentication`
+     * and `@nestjs/authorization`.
      *
-     * A third, optional hook — **`revalidate`** — re-checks an already-minted session rather than
-     * minting one: once a session cookie is past 50% of its TTL, the guard slides it forward with a
-     * fresh one, and if `revalidate` is set it's consulted first, so a deactivated or demoted
-     * operator loses access instead of riding a self-renewing cookie indefinitely. It only runs on
-     * that renewal path, not on every request, so revocation has **latency, not immediacy**: an
-     * operator revoked right after a renewal keeps their existing cookie — and therefore console
-     * access — for up to `ttl/2` (4 hours at the default 8h TTL) before the next renewal check catches
-     * it. Do not rely on `revalidate` for a same-second cutoff; front the mount with your own guard
-     * (see {@link guards}) if you need that.
+     * Each registration gets fresh subclasses of the controllers, so decorators never leak into
+     * another registration or onto the exported classes. A guard named in `UseGuards(...)` resolves
+     * its dependencies from {@link imports} (or a global module).
      *
-     * 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.
+     * A non-empty `decorators` is how a mounted console states its protection. With
+     * `NODE_ENV=production`, a mounted console with no (or an empty) `decorators` fails the boot; see
+     * {@link DurableDashboardModule}. The module cannot tell a `Can(...)` from a decorator that
+     * protects nothing, so passing one is your statement that the console is protected.
      *
-     * 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. Setting it
-     * counts as the console's authentication (the fail-closed default gate steps aside). Omit it and
-     * configure `guards`, a {@link token}, or {@link allowUnauthenticated} instead.
-     *
-     * See {@link DashboardAuthOptions} for the `secret`/`ttl`/`session`/`login`/`revalidate` shape,
-     * and `forRootAsync` / {@link DurableDashboardAsyncOptions.useDashboardAuth} when a hook needs DI
-     * (e.g. an `EntityManager` to look up an admin user).
+     * Default: none. Outside production the console is then served open, and the controllers are
+     * marked `Can.Anyone()` for `@nestjs/authorization`, whose global guard otherwise refuses every
+     * route that declares no `@Can()`. A `@Can()` passed here is still enforced.
      */
-    dashboardAuth?: DashboardAuthOptions;
+    decorators?: ClassDecorator[];
     /**
-     * Explicitly serve the console with NO authentication from this module. Use it only when
-     * something outside the module already protects it: a global guard, a reverse proxy / SSO in
-     * front of the mount, a private network. Logs a boot warning.
+     * `false` mounts NO controllers: the SPA and its JSON API are not registered,
+     * while every provider still is (the run read/action service, the run filter, the SPA's base
+     * paths). Serve the console from controllers of your own instead, protected with ordinary Nest
+     * decorators, by extending {@link DurableUiControllerBase} and {@link DurableApiControllerBase}:
      *
-     * Without it, an unconfigured console (no `guards`, no `dashboardAuth`, no token) is DENIED when
-     * `NODE_ENV=production` (every UI and API request answers `403`, and one boot error explains how
-     * to configure it). Outside production it is still served open, with a boot warning. Ignored when
-     * `guards`, `dashboardAuth` or a token is configured.
-     */
-    allowUnauthenticated?: boolean;
-    /**
-     * Bearer-token gate for the console. Defaults to `process.env.DURABLE_DASHBOARD_TOKEN` (read at
-     * boot). Only applies when neither `guards` nor `dashboardAuth` is configured: every UI and API
-     * request must then carry it as `Authorization: Bearer <token>`, an `x-durable-token` header, or
-     * (GET/HEAD only) a `?token=` query param, compared in constant time; anything else gets `401`.
+     * ```ts
+     * @Controller('ops/durable') @UseGuards(AuthenticationGuard) @Can(ConsolePolicy, 'view')
+     * class ConsoleUi extends DurableUiControllerBase {}
+     * @Controller('ops/durable/api') @UseGuards(AuthenticationGuard) @Can(ConsolePolicy, 'view')
+     * class ConsoleApi extends DurableApiControllerBase {}
+     * // in the module that declares them:
+     * imports: [DurableDashboardModule.forRoot({ routes: false, basePath: '/ops/durable', apiBasePath: '/ops/durable/api' })]
+     * ```
+     *
+     * `basePath`/`apiBasePath` still matter here: they are where you mounted the two controllers, and
+     * the SPA is told to load its assets from `basePath` and fetch from `apiBasePath`.
+     *
+     * The production rule does not apply: this module mounts nothing, and the routes are yours,
+     * protected by what you put on them like any other route you write. The `*Base` classes carry no
+     * guards and no `Can.Anyone()` mark, so under `@nestjs/authorization`'s global guard a subclass
+     * without a `@Can()` is denied. `decorators` throws when combined with `routes: false` rather than
+     * being silently ignored.
      *
-     * Meant for scripts and reverse proxies that inject the header: the bundled SPA does not attach
-     * the token to its own asset and API requests. Browser operators want `dashboardAuth` or `guards`.
+     * Default `true`. Named `routes` rather than `path: false` because `basePath`/`apiBasePath` are
+     * strings that keep their meaning (where the console lives) whether or not this module mounts it.
      */
-    token?: string;
-}
-/**
- * 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 `session`/`login` hooks
- * can reach your DB/services — e.g. Mode A's `session` hook calling out to the same auth service
- * your host app already uses to validate the raw request. Returning `undefined` from
- * `useDashboardAuth` is exactly like omitting `dashboardAuth` from `forRoot`: the console then
- * falls back to `guards` / the token / `allowUnauthenticated`, and is DENIED in production when
- * none of those is configured.
- */
-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` for no session auth). */
-    useDashboardAuth: (...deps: any[]) => DashboardAuthOptions | undefined | Promise<DashboardAuthOptions | undefined>;
-    /** See {@link DurableDashboardOptions.allowUnauthenticated}. */
-    allowUnauthenticated?: boolean;
-    /** See {@link DurableDashboardOptions.token}. */
-    token?: string;
+    routes?: boolean;
 }
+/** DI token of the boot-time check that refuses an unprotected console in production. */
+declare const DASHBOARD_PROTECTION_CHECK: unique symbol;
+/** The boot error for a mounted console with no `decorators` under `NODE_ENV=production`. */
+declare const UNPROTECTED_CONSOLE_IN_PRODUCTION: string;
 /**
- * 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`).
+ * Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. Its own
+ * dynamic module because enhancers (a guard from `decorators`) DI-instantiate from their
+ * controller's host module, so this module, not the outer wrapper, must carry the host's `imports`.
  */
 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;
-        /** What the fail-closed gate needs; resolved into `DASHBOARD_GATE` at boot (logged once). */
-        gate: DashboardGateOptions;
-        /** Whether `DurableDashboardGateGuard` is stamped (false when guards/dashboardAuth are static). */
-        stampGate: boolean;
+        /** `false`: register the providers only, no controller (see `routes`). */
+        routes?: boolean;
+        /** See {@link DurableDashboardOptions.decorators}. */
+        decorators?: ClassDecorator[];
     }): DynamicModule;
 }
 /**
@@ -691,66 +436,28 @@ declare class DurableApiModule {
  * 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.
- * With none of those (and no `token` / `allowUnauthenticated`), the console fails closed when
- * `NODE_ENV=production` — see {@link DurableDashboardOptions.allowUnauthenticated}.
+ * With none of those (and no `decorators` / `token` / `allowUnauthenticated`), the console fails
+ * closed when `NODE_ENV=production` — see {@link DurableDashboardOptions.allowUnauthenticated}.
+ * `routes: false` mounts nothing and leaves serving the console to the host's own controllers — see
+ * {@link DurableDashboardOptions.routes}.
  */
-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,
- * when Mode B (`login`) is configured, gets 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`). When only Mode A (`session`) is
- * configured there is no login page to redirect to — the host mints the session itself — so it
- * instead throws `DashboardSessionRequiredException`, rendering a small instruction page.
+ * 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.
  *
- * 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): Promise<boolean>;
-    /**
-     * A revoked session (the host's `revalidate` hook says no) is denied exactly like an absent
-     * one — by design, there is nothing left to distinguish "never had a session" from "had one,
-     * then lost it" once the cookie is cleared, so both get the same Mode-aware treatment.
-     *
-     * Takes `auth` explicitly rather than reading `this.auth`: `canActivate`'s `!this.auth` early
-     * return narrows the field within that method only — TS doesn't carry it across a method call
-     * — so callers pass the already-narrowed value instead of this method re-deriving (or
-     * asserting away) the nullability.
-     */
-    private denyUnauthenticated;
-}
-/**
- * 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).
+ * Protect the console with the first-party NestJS tools (`@nestjs/authentication`,
+ * `@nestjs/authorization`), one of two ways:
+ *
+ * 1. `decorators` on the mounted controllers (see {@link DurableDashboardOptions.decorators});
+ * 2. `routes: false`, and mount it yourself by extending `DurableUiControllerBase` /
+ *    `DurableApiControllerBase` (see {@link DurableDashboardOptions.routes}).
  *
- * Mount-level and role-agnostic, same as `DurableUiSessionGuard` above.
+ * With `NODE_ENV=production`, a mounted console with no `decorators` fails the boot with
+ * {@link UNPROTECTED_CONSOLE_IN_PRODUCTION}. Outside production it is served open, with a warning.
  */
-declare class DurableApiSessionGuard implements CanActivate {
-    private readonly auth;
-    constructor(auth: ResolvedDashboardAuth | null);
-    canActivate(context: ExecutionContext): Promise<boolean>;
-    /**
-     * A bare 401 body carrying `{ auth: { modes } }` — mirrors `@dudousxd/nestjs-telescope`'s
-     * dashboardAuth 401. The API is fetched (never navigated), so this is the ONLY way the console
-     * SPA (`durable-client.ts`) learns which auth surface to send the operator to on a mid-session
-     * 401; `DurableUiSessionGuard`'s redirect/session-required exceptions above don't reach it.
-     */
-    private unauthorized;
+declare class DurableDashboardModule {
+    static forRoot(options?: DurableDashboardOptions): DynamicModule;
 }
 
 /** DI token carrying the UI mount base (e.g. `/durable`). */
@@ -759,18 +466,16 @@ declare const DASHBOARD_BASE_PATH: unique symbol;
 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.
+ * The controller routes are relative: the mounted {@link DurableUiController} gets its path from
+ * `RouterModule` (set by `DurableDashboardModule.forRoot({ basePath })`).
  *
- * `@UseFilters(DashboardLoginRedirectFilter, DashboardSessionRequiredFilter)` is permanent (present
- * regardless of whether `dashboardAuth` is configured): each only ever activates for its own
- * exception type, which `DurableUiSessionGuard` only throws when it is ALSO stamped on this
- * controller (see `DurableDashboardModule.forRoot`) — so leaving them decorated here is inert, not
- * a behavior change, when `dashboardAuth` is absent. The guard picks between the two exceptions
- * based on which mode is configured (Mode B => redirect to the login page; Mode A only => render
- * the session-required instruction page in place, since there is no login page to redirect to).
+ * This base is what a host EXTENDS to serve the console from a controller of its own (with
+ * `forRoot({ routes: false, basePath })`): `@Controller('<basePath>') class MyConsole extends
+ * DurableUiControllerBase {}`, protected with the host's own decorators. It carries no guards and
+ * no `@nestjs/authorization` mark, so a subclass is protected only by what the host puts on it (and,
+ * under `AuthorizationModule`'s global guard, is denied until it declares a `@Can()`).
  */
-declare class DurableUiController {
+declare class DurableUiControllerBase {
     private readonly basePath;
     private readonly apiBasePath;
     private readonly dir;
@@ -778,5 +483,13 @@ declare class DurableUiController {
     index(): string;
     asset(file: string): StreamableFile;
 }
+/**
+ * The SPA controller `DurableDashboardModule.forRoot(...)` mounts at `basePath`. The module puts
+ * the `@nestjs/authorization` open mark on THIS class (and `decorators` on a per-registration
+ * subclass of it), never on {@link DurableUiControllerBase}, so a host's own subclass of the base
+ * inherits none of them.
+ */
+declare class DurableUiController extends DurableUiControllerBase {
+}
 
-export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DASHBOARD_GATE, DURABLE_DASHBOARD_TOKEN_ENV, type DashboardAuthOptions, type DashboardGate, type DashboardGateMode, type DashboardGateOptions, DashboardService, type DashboardSessionUser, DurableApiController, DurableApiModule, DurableApiSessionGuard, DurableAuthController, type DurableDashboardAsyncOptions, DurableDashboardGateGuard, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiSessionGuard, type UnauthenticatedPageContext, type UnauthenticatedPageHook, type WorkflowLifecyclePage, dashboardGateProvider, readDashboardToken, reportDashboardGate, resolveDashboardGate };
+export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DASHBOARD_PROTECTION_CHECK, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UNPROTECTED_CONSOLE_IN_PRODUCTION, type WorkflowLifecyclePage };