@dudousxd/nestjs-agent-dashboard 0.9.1 → 0.10.1

package/dist/server/index.d.cts

@@ -194,12 +194,36 @@ interface DashboardSessionUser {
     roles?: string[];
 }
 
-/** Host hook: validates submitted credentials for the built-in login screen. */
+/**
+ * Host hook for Mode A: validates the host's own auth on the raw request POSTed to
+ * `<basePath>/auth/session`. Return the session user to grant access, or `null` to deny.
+ */
+type SessionHook = (request: unknown) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/** Host hook for Mode B: validates submitted credentials for the built-in login screen. */
 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
+ * COOKIE GENERATION — the gate is on the inbound cookie's `iat`, so every request still carrying a
+ * not-yet-renewed cookie would, on its own, invoke this hook again; `maybeRenewSession` de-dupes
+ * concurrent calls for the same session (`sub` + `iat`) into a single in-flight call, so a page
+ * load that fires N parallel API calls still costs exactly ONE host round-trip, not N. Still not a
+ * per-session-lifetime cap — this can run again every `ttl/2` as the session keeps sliding, so a
+ * slow or expensive check should still debounce/cache across renewal windows on its own. 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;
+/** Which `dashboardAuth` hook(s) a resolved config was given — see `resolveDashboardAuth`. */
+type AuthMode = 'session' | 'login';
 /**
  * Author-facing `dashboardAuth` option (see `AgentDashboardOptions.dashboardAuth`). Gates the
- * console (SPA + API) behind a built-in cookie-session login screen — no host frontend changes,
- * no SSO required. Mirrors `@dudousxd/nestjs-telescope`'s `dashboardAuth` Mode B (`login`).
+ * console (SPA + API) behind a signed session cookie. Two ways to mint that cookie: Mode A
+ * (`session`) — the host frontend, already carrying its own auth, POSTs to
+ * `<basePath>/auth/session` and the host hook decides — or Mode B (`login`) — the built-in,
+ * dependency-free server-rendered login screen. Mirrors `@dudousxd/nestjs-telescope`'s
+ * `dashboardAuth` two-mode shape. 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 (32+ bytes recommended). Missing/empty => boot error (fail closed). */
@@ -207,23 +231,36 @@ interface DashboardAuthOptions {
     /** Cookie TTL (duration string `'<n><ms|s|m|h|d>'`, e.g. `'30m'`, `'7d'`). Default `'8h'`. */
     ttl?: string;
     /**
-     * Validates submitted username/password. Return the session user to grant access, or `null` to
-     * deny — the login endpoint responds identically (generic failure) for an unknown user and a
-     * wrong password, so it never reveals which one was wrong.
+     * Mode A: validates the host's own auth on the raw request POSTed to `<basePath>/auth/session`.
+     * Return the session user to grant access, or `null` to deny. No credential reaches this
+     * library — the host decides from whatever it already has (a header, an SSO cookie, ...).
      */
-    login: LoginHook;
+    session?: SessionHook;
+    /**
+     * Mode B: validates submitted username/password. Return the session user to grant access, or
+     * `null` to deny — the login endpoint responds identically (generic failure) for an unknown user
+     * and a wrong password, so it never reveals which one was wrong.
+     */
+    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 used by the guards/controller. */
 interface ResolvedDashboardAuth {
     secret: string;
     ttlMs: number;
-    login: LoginHook;
+    modes: AuthMode[];
+    session?: SessionHook;
+    login?: LoginHook;
+    revalidate?: RevalidateHook;
 }
 /**
  * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
  * console stays open, front it with your own `guards`). Throws at boot (fail closed) when
- * configured but missing a secret or a `login` hook — the host learns immediately rather than
- * shipping an open or un-mintable console.
+ * configured but missing a secret, when neither `session` nor `login` is given, or when a given
+ * hook isn't a function — the host learns immediately rather than shipping an open, stuck, or
+ * un-mintable console.
  */
 declare function resolveDashboardAuth(options: DashboardAuthOptions | undefined): ResolvedDashboardAuth | null;
 
@@ -248,32 +285,37 @@ interface LoginFormBody {
  * built-in gates check for, so they can never be made to require the very auth they grant. Mirrors
  * `@dudousxd/nestjs-telescope`'s own auth controller staying outside its `stampGuards` call.
  *
- * A dependency-free, server-rendered login form (GET/POST) rather than a JSON API + client-side
- * screen — the bundled React SPA in this package is a built Vite artifact with no auth-aware UI of
- * its own, so gating the actual page navigation needs a self-contained flow that doesn't touch it.
- *
- * 404s every route when `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to `null`) — no
- * dangling login page when the feature is off.
+ * Two ways to mint that cookie, matching `resolveDashboardAuth`'s modes: Mode A (`session`) — the
+ * host frontend, already carrying its own auth, POSTs to `<basePath>/auth/session` and the host
+ * hook decides — or Mode B (`login`), a dependency-free, server-rendered login form (GET/POST) —
+ * the bundled React SPA in this package is a built Vite artifact with no auth-aware UI of its own,
+ * so gating the actual page navigation needs a self-contained flow that doesn't touch it. Each
+ * mode's routes 404 when that mode isn't listed in `auth.modes` — the single source of truth for
+ * which mode(s) are configured, not hook-presence truthiness — and every route 404s outright when
+ * `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to `null`) — no dangling login page
+ * when the feature is off.
  */
 declare class AgentDashboardAuthController {
     private readonly auth;
     private readonly basePath;
     private readonly logger;
-    /** Warn once (not per request) so a broken hook can't be used to flood the logs. */
-    private warnedLoginHookThrow;
+    /** Warn once PER HOOK KIND (not per request) so a broken hook can't be used to flood the logs. */
+    private readonly warnedHooks;
     constructor(auth: ResolvedDashboardAuth | null, basePath: string);
     loginPage(req: AuthPageRequest, res: AuthPageResponse, returnToQuery?: string, error?: string): string;
     login(body: LoginFormBody, req: unknown, res: AuthPageResponse): Promise<string>;
     logout(req: unknown, res: AuthPageResponse): string;
+    session(request: unknown, response: unknown): Promise<void>;
+    sessionRequiredPage(): string;
     /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
     private redirectToLoginError;
     private currentSession;
     /**
-     * Run the host's `login` hook defensively: a throw (sync or async) is treated as a denial
-     * (`null`) and warn-logged ONCE, so a buggy/unreachable hook never 500s the endpoint into a
-     * stack-trace leak nor floods the logs.
+     * Run a host hook (`login` or `session`) defensively: a throw (sync or async) is treated as a
+     * denial (`null`) and warn-logged ONCE PER KIND, so a buggy/unreachable hook never 500s the
+     * endpoint into a stack-trace leak nor floods the logs on repeated bad attempts.
      */
-    private runLoginHook;
+    private runHook;
     private requireAuth;
 }
 
@@ -355,21 +397,36 @@ interface AgentDashboardOptions<TReq = unknown> {
      */
     approvalActorRef?: (req: TReq) => string | undefined;
     /**
-     * Gate the console (SPA + API) behind a BUILT-IN cookie-session login screen — the simplest way
-     * to protect `basePath` when the host has no ready-made guard (e.g. header-only auth that a
-     * browser navigation can't attach). Omit to leave the console open, or fronted only by
-     * {@link guards}. When set, an unauthenticated page navigation is redirected (302) to
-     * `<basePath>/auth/login`; an unauthenticated API call gets a `401`. Composes with `guards` —
-     * BOTH gates must pass. See `DashboardAuthOptions` for the `secret`/`ttl`/`login` shape.
+     * Gate the console (SPA + API) behind a built-in, signed session cookie. 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>/auth/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 console
+     *   serves its own small, dependency-free, server-rendered login page (`GET
+     *   <basePath>/auth/login`) 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
+     * unauthenticated API call always gets a plain `401`, regardless of mode — the caller reads the
+     * status code, not HTML. Composes with `guards` — BOTH gates must pass. See
+     * `DashboardAuthOptions` for the `secret`/`ttl`/`session`/`login` shape.
      */
     dashboardAuth?: DashboardAuthOptions;
 }
 /**
- * Async variant of {@link AgentDashboardOptions}, for a `login` hook that needs injected services
- * (e.g. an EntityManager to check credentials against a DB). Everything else stays static/sync —
- * `basePath`/`apiBasePath`/`guards` are needed at module-build time (the same constraint
- * `@dudousxd/nestjs-telescope`'s and `@dudousxd/nestjs-media`'s own `forRootAsync`s document), so
- * only the auth piece itself is resolved through DI.
+ * Async variant of {@link AgentDashboardOptions}, for a `session`/`login` hook that needs injected
+ * services (e.g. an EntityManager to check credentials against a DB). Everything else stays
+ * static/sync — `basePath`/`apiBasePath`/`guards` are needed at module-build time (the same
+ * constraint `@dudousxd/nestjs-telescope`'s and `@dudousxd/nestjs-media`'s own `forRootAsync`s
+ * document), so only the auth piece itself is resolved through DI.
  */
 interface AgentDashboardAsyncOptions<TReq = unknown> {
     basePath?: string;
@@ -404,13 +461,15 @@ declare class AgentApiModule {
 }
 /**
  * Mounts the AI-gateway governance console: the bundled React SPA at `basePath` and its JSON + SSE
- * API at `apiBasePath` (default `<basePath>/api`), plus the built-in login screen's routes at
- * `<basePath>/auth/*` when {@link AgentDashboardOptions.dashboardAuth} is set.
+ * API at `apiBasePath` (default `<basePath>/api`), plus the built-in `dashboardAuth` routes at
+ * `<basePath>/auth/*` when {@link AgentDashboardOptions.dashboardAuth} is set — `POST
+ * <basePath>/auth/session` for Mode A (the host mints the session from its own auth) and/or `GET`/
+ * `POST <basePath>/auth/login` for Mode B (the built-in login screen).
  *
  * Import via `AgentDashboardModule.forRoot(...)` alongside your `@dudousxd/nestjs-agent` module
  * (global), which must provide `AGENT_GOVERNANCE_QUERIES` (bound by a store adapter). Front the
  * routes with the first-class `guards` option (plus `imports` for the guards' own dependencies) —
- * see {@link AgentDashboardOptions.guards} — and/or the built-in `dashboardAuth` cookie login.
+ * see {@link AgentDashboardOptions.guards} — and/or the built-in `dashboardAuth` session cookie.
  *
  * Inertia hosts: the console is a full-page app, not an Inertia page. An in-app `<Link>` visit to
  * `basePath` (an XHR carrying `X-Inertia`) is bounced with the protocol's own external-redirect
@@ -530,4 +589,4 @@ declare const DASHBOARD_APPROVAL_ACTOR_REF: unique symbol;
  */
 declare const DASHBOARD_AUTH: unique symbol;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, type AgentDashboardAsyncOptions, AgentDashboardAuthController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_AUTH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type LiveAgentEvent, type LoginHook, type ReliabilityOverview, type ResolvedDashboardAuth, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, type AgentDashboardAsyncOptions, AgentDashboardAuthController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, type AuthMode, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_AUTH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type LiveAgentEvent, type LoginHook, type ReliabilityOverview, type ResolvedDashboardAuth, type RevalidateHook, type SessionHook, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };

package/dist/server/index.d.ts

@@ -194,12 +194,36 @@ interface DashboardSessionUser {
     roles?: string[];
 }
 
-/** Host hook: validates submitted credentials for the built-in login screen. */
+/**
+ * Host hook for Mode A: validates the host's own auth on the raw request POSTed to
+ * `<basePath>/auth/session`. Return the session user to grant access, or `null` to deny.
+ */
+type SessionHook = (request: unknown) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/** Host hook for Mode B: validates submitted credentials for the built-in login screen. */
 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
+ * COOKIE GENERATION — the gate is on the inbound cookie's `iat`, so every request still carrying a
+ * not-yet-renewed cookie would, on its own, invoke this hook again; `maybeRenewSession` de-dupes
+ * concurrent calls for the same session (`sub` + `iat`) into a single in-flight call, so a page
+ * load that fires N parallel API calls still costs exactly ONE host round-trip, not N. Still not a
+ * per-session-lifetime cap — this can run again every `ttl/2` as the session keeps sliding, so a
+ * slow or expensive check should still debounce/cache across renewal windows on its own. 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;
+/** Which `dashboardAuth` hook(s) a resolved config was given — see `resolveDashboardAuth`. */
+type AuthMode = 'session' | 'login';
 /**
  * Author-facing `dashboardAuth` option (see `AgentDashboardOptions.dashboardAuth`). Gates the
- * console (SPA + API) behind a built-in cookie-session login screen — no host frontend changes,
- * no SSO required. Mirrors `@dudousxd/nestjs-telescope`'s `dashboardAuth` Mode B (`login`).
+ * console (SPA + API) behind a signed session cookie. Two ways to mint that cookie: Mode A
+ * (`session`) — the host frontend, already carrying its own auth, POSTs to
+ * `<basePath>/auth/session` and the host hook decides — or Mode B (`login`) — the built-in,
+ * dependency-free server-rendered login screen. Mirrors `@dudousxd/nestjs-telescope`'s
+ * `dashboardAuth` two-mode shape. 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 (32+ bytes recommended). Missing/empty => boot error (fail closed). */
@@ -207,23 +231,36 @@ interface DashboardAuthOptions {
     /** Cookie TTL (duration string `'<n><ms|s|m|h|d>'`, e.g. `'30m'`, `'7d'`). Default `'8h'`. */
     ttl?: string;
     /**
-     * Validates submitted username/password. Return the session user to grant access, or `null` to
-     * deny — the login endpoint responds identically (generic failure) for an unknown user and a
-     * wrong password, so it never reveals which one was wrong.
+     * Mode A: validates the host's own auth on the raw request POSTed to `<basePath>/auth/session`.
+     * Return the session user to grant access, or `null` to deny. No credential reaches this
+     * library — the host decides from whatever it already has (a header, an SSO cookie, ...).
      */
-    login: LoginHook;
+    session?: SessionHook;
+    /**
+     * Mode B: validates submitted username/password. Return the session user to grant access, or
+     * `null` to deny — the login endpoint responds identically (generic failure) for an unknown user
+     * and a wrong password, so it never reveals which one was wrong.
+     */
+    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 used by the guards/controller. */
 interface ResolvedDashboardAuth {
     secret: string;
     ttlMs: number;
-    login: LoginHook;
+    modes: AuthMode[];
+    session?: SessionHook;
+    login?: LoginHook;
+    revalidate?: RevalidateHook;
 }
 /**
  * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
  * console stays open, front it with your own `guards`). Throws at boot (fail closed) when
- * configured but missing a secret or a `login` hook — the host learns immediately rather than
- * shipping an open or un-mintable console.
+ * configured but missing a secret, when neither `session` nor `login` is given, or when a given
+ * hook isn't a function — the host learns immediately rather than shipping an open, stuck, or
+ * un-mintable console.
  */
 declare function resolveDashboardAuth(options: DashboardAuthOptions | undefined): ResolvedDashboardAuth | null;
 
@@ -248,32 +285,37 @@ interface LoginFormBody {
  * built-in gates check for, so they can never be made to require the very auth they grant. Mirrors
  * `@dudousxd/nestjs-telescope`'s own auth controller staying outside its `stampGuards` call.
  *
- * A dependency-free, server-rendered login form (GET/POST) rather than a JSON API + client-side
- * screen — the bundled React SPA in this package is a built Vite artifact with no auth-aware UI of
- * its own, so gating the actual page navigation needs a self-contained flow that doesn't touch it.
- *
- * 404s every route when `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to `null`) — no
- * dangling login page when the feature is off.
+ * Two ways to mint that cookie, matching `resolveDashboardAuth`'s modes: Mode A (`session`) — the
+ * host frontend, already carrying its own auth, POSTs to `<basePath>/auth/session` and the host
+ * hook decides — or Mode B (`login`), a dependency-free, server-rendered login form (GET/POST) —
+ * the bundled React SPA in this package is a built Vite artifact with no auth-aware UI of its own,
+ * so gating the actual page navigation needs a self-contained flow that doesn't touch it. Each
+ * mode's routes 404 when that mode isn't listed in `auth.modes` — the single source of truth for
+ * which mode(s) are configured, not hook-presence truthiness — and every route 404s outright when
+ * `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to `null`) — no dangling login page
+ * when the feature is off.
  */
 declare class AgentDashboardAuthController {
     private readonly auth;
     private readonly basePath;
     private readonly logger;
-    /** Warn once (not per request) so a broken hook can't be used to flood the logs. */
-    private warnedLoginHookThrow;
+    /** Warn once PER HOOK KIND (not per request) so a broken hook can't be used to flood the logs. */
+    private readonly warnedHooks;
     constructor(auth: ResolvedDashboardAuth | null, basePath: string);
     loginPage(req: AuthPageRequest, res: AuthPageResponse, returnToQuery?: string, error?: string): string;
     login(body: LoginFormBody, req: unknown, res: AuthPageResponse): Promise<string>;
     logout(req: unknown, res: AuthPageResponse): string;
+    session(request: unknown, response: unknown): Promise<void>;
+    sessionRequiredPage(): string;
     /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
     private redirectToLoginError;
     private currentSession;
     /**
-     * Run the host's `login` hook defensively: a throw (sync or async) is treated as a denial
-     * (`null`) and warn-logged ONCE, so a buggy/unreachable hook never 500s the endpoint into a
-     * stack-trace leak nor floods the logs.
+     * Run a host hook (`login` or `session`) defensively: a throw (sync or async) is treated as a
+     * denial (`null`) and warn-logged ONCE PER KIND, so a buggy/unreachable hook never 500s the
+     * endpoint into a stack-trace leak nor floods the logs on repeated bad attempts.
      */
-    private runLoginHook;
+    private runHook;
     private requireAuth;
 }
 
@@ -355,21 +397,36 @@ interface AgentDashboardOptions<TReq = unknown> {
      */
     approvalActorRef?: (req: TReq) => string | undefined;
     /**
-     * Gate the console (SPA + API) behind a BUILT-IN cookie-session login screen — the simplest way
-     * to protect `basePath` when the host has no ready-made guard (e.g. header-only auth that a
-     * browser navigation can't attach). Omit to leave the console open, or fronted only by
-     * {@link guards}. When set, an unauthenticated page navigation is redirected (302) to
-     * `<basePath>/auth/login`; an unauthenticated API call gets a `401`. Composes with `guards` —
-     * BOTH gates must pass. See `DashboardAuthOptions` for the `secret`/`ttl`/`login` shape.
+     * Gate the console (SPA + API) behind a built-in, signed session cookie. 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>/auth/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 console
+     *   serves its own small, dependency-free, server-rendered login page (`GET
+     *   <basePath>/auth/login`) 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
+     * unauthenticated API call always gets a plain `401`, regardless of mode — the caller reads the
+     * status code, not HTML. Composes with `guards` — BOTH gates must pass. See
+     * `DashboardAuthOptions` for the `secret`/`ttl`/`session`/`login` shape.
      */
     dashboardAuth?: DashboardAuthOptions;
 }
 /**
- * Async variant of {@link AgentDashboardOptions}, for a `login` hook that needs injected services
- * (e.g. an EntityManager to check credentials against a DB). Everything else stays static/sync —
- * `basePath`/`apiBasePath`/`guards` are needed at module-build time (the same constraint
- * `@dudousxd/nestjs-telescope`'s and `@dudousxd/nestjs-media`'s own `forRootAsync`s document), so
- * only the auth piece itself is resolved through DI.
+ * Async variant of {@link AgentDashboardOptions}, for a `session`/`login` hook that needs injected
+ * services (e.g. an EntityManager to check credentials against a DB). Everything else stays
+ * static/sync — `basePath`/`apiBasePath`/`guards` are needed at module-build time (the same
+ * constraint `@dudousxd/nestjs-telescope`'s and `@dudousxd/nestjs-media`'s own `forRootAsync`s
+ * document), so only the auth piece itself is resolved through DI.
  */
 interface AgentDashboardAsyncOptions<TReq = unknown> {
     basePath?: string;
@@ -404,13 +461,15 @@ declare class AgentApiModule {
 }
 /**
  * Mounts the AI-gateway governance console: the bundled React SPA at `basePath` and its JSON + SSE
- * API at `apiBasePath` (default `<basePath>/api`), plus the built-in login screen's routes at
- * `<basePath>/auth/*` when {@link AgentDashboardOptions.dashboardAuth} is set.
+ * API at `apiBasePath` (default `<basePath>/api`), plus the built-in `dashboardAuth` routes at
+ * `<basePath>/auth/*` when {@link AgentDashboardOptions.dashboardAuth} is set — `POST
+ * <basePath>/auth/session` for Mode A (the host mints the session from its own auth) and/or `GET`/
+ * `POST <basePath>/auth/login` for Mode B (the built-in login screen).
  *
  * Import via `AgentDashboardModule.forRoot(...)` alongside your `@dudousxd/nestjs-agent` module
  * (global), which must provide `AGENT_GOVERNANCE_QUERIES` (bound by a store adapter). Front the
  * routes with the first-class `guards` option (plus `imports` for the guards' own dependencies) —
- * see {@link AgentDashboardOptions.guards} — and/or the built-in `dashboardAuth` cookie login.
+ * see {@link AgentDashboardOptions.guards} — and/or the built-in `dashboardAuth` session cookie.
  *
  * Inertia hosts: the console is a full-page app, not an Inertia page. An in-app `<Link>` visit to
  * `basePath` (an XHR carrying `X-Inertia`) is bounced with the protocol's own external-redirect
@@ -530,4 +589,4 @@ declare const DASHBOARD_APPROVAL_ACTOR_REF: unique symbol;
  */
 declare const DASHBOARD_AUTH: unique symbol;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, type AgentDashboardAsyncOptions, AgentDashboardAuthController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_AUTH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type LiveAgentEvent, type LoginHook, type ReliabilityOverview, type ResolvedDashboardAuth, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, type ActorSpendRowWithLabel, AgentApiController, AgentApiModule, type AgentDashboardAsyncOptions, AgentDashboardAuthController, AgentDashboardModule, type AgentDashboardMountPathsOptions, type AgentDashboardOptions, AgentUiController, type AuthMode, DASHBOARD_API_PATH, DASHBOARD_APPROVAL_ACTOR_REF, DASHBOARD_AUTH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type LiveAgentEvent, type LoginHook, type ReliabilityOverview, type ResolvedDashboardAuth, type RevalidateHook, type SessionHook, type SpendOverview, type ThreadActivityRowWithLabel, type ThreadSpendRowWithLabel, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };