@dudousxd/nestjs-durable-dashboard 0.36.0 → 0.37.1

package/dist/server/index.d.cts

@@ -12,32 +12,55 @@ interface DashboardSessionUser {
     roles?: string[];
 }
 
-/** Host hook validating submitted credentials from the built-in login page. */
+/** 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;
+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). 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.
+ * `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;
-    /** 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;
+    /** 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;
 }
 /** Resolved, validated `dashboardAuth` config shared by the guards, auth controller, and login page. */
 interface ResolvedDashboardAuth {
     secret: string;
     ttlMs: number;
-    login: LoginHook;
+    modes: AuthMode[];
+    session?: SessionHook;
+    login?: LoginHook;
+    revalidate?: RevalidateHook;
 }
 
 /**
@@ -195,21 +218,22 @@ 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;
+    /** 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 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.
+     * 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 runLoginHook;
+    private runHook;
 }
 
 interface DurableDashboardOptions {
@@ -253,13 +277,36 @@ interface DurableDashboardOptions {
     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.
+     * 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.
+     *
+     * 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.
      *
      * 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
@@ -271,18 +318,19 @@ interface DurableDashboardOptions {
      * 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).
+     * 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).
      */
     dashboardAuth?: DashboardAuthOptions;
 }
 /**
  * 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`.
+ * 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` leaves the console open, exactly like omitting `dashboardAuth` from `forRoot`.
  */
 interface DurableDashboardAsyncOptions {
     basePath?: string;
@@ -332,10 +380,12 @@ declare class DurableDashboardModule {
 /**
  * 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`).
+ * — 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.
  *
  * 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
@@ -345,7 +395,18 @@ declare class DurableUiSessionGuard implements CanActivate {
     private readonly auth;
     private readonly basePath;
     constructor(auth: ResolvedDashboardAuth | null, basePath: string);
-    canActivate(context: ExecutionContext): boolean;
+    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
@@ -358,7 +419,14 @@ declare class DurableUiSessionGuard implements CanActivate {
 declare class DurableApiSessionGuard implements CanActivate {
     private readonly auth;
     constructor(auth: ResolvedDashboardAuth | null);
-    canActivate(context: ExecutionContext): boolean;
+    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;
 }
 
 /** DI token carrying the UI mount base (e.g. `/durable`). */
@@ -370,11 +438,13 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * 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.
+ * `@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).
  */
 declare class DurableUiController {
     private readonly basePath;

package/dist/server/index.d.ts

@@ -12,32 +12,55 @@ interface DashboardSessionUser {
     roles?: string[];
 }
 
-/** Host hook validating submitted credentials from the built-in login page. */
+/** 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;
+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). 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.
+ * `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;
-    /** 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;
+    /** 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;
 }
 /** Resolved, validated `dashboardAuth` config shared by the guards, auth controller, and login page. */
 interface ResolvedDashboardAuth {
     secret: string;
     ttlMs: number;
-    login: LoginHook;
+    modes: AuthMode[];
+    session?: SessionHook;
+    login?: LoginHook;
+    revalidate?: RevalidateHook;
 }
 
 /**
@@ -195,21 +218,22 @@ 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;
+    /** 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 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.
+     * 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 runLoginHook;
+    private runHook;
 }
 
 interface DurableDashboardOptions {
@@ -253,13 +277,36 @@ interface DurableDashboardOptions {
     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.
+     * 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.
+     *
+     * 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.
      *
      * 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
@@ -271,18 +318,19 @@ interface DurableDashboardOptions {
      * 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).
+     * 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).
      */
     dashboardAuth?: DashboardAuthOptions;
 }
 /**
  * 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`.
+ * 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` leaves the console open, exactly like omitting `dashboardAuth` from `forRoot`.
  */
 interface DurableDashboardAsyncOptions {
     basePath?: string;
@@ -332,10 +380,12 @@ declare class DurableDashboardModule {
 /**
  * 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`).
+ * — 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.
  *
  * 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
@@ -345,7 +395,18 @@ declare class DurableUiSessionGuard implements CanActivate {
     private readonly auth;
     private readonly basePath;
     constructor(auth: ResolvedDashboardAuth | null, basePath: string);
-    canActivate(context: ExecutionContext): boolean;
+    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
@@ -358,7 +419,14 @@ declare class DurableUiSessionGuard implements CanActivate {
 declare class DurableApiSessionGuard implements CanActivate {
     private readonly auth;
     constructor(auth: ResolvedDashboardAuth | null);
-    canActivate(context: ExecutionContext): boolean;
+    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;
 }
 
 /** DI token carrying the UI mount base (e.g. `/durable`). */
@@ -370,11 +438,13 @@ declare const DASHBOARD_API_PATH: unique symbol;
  * 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.
+ * `@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).
  */
 declare class DurableUiController {
     private readonly basePath;