@dudousxd/nestjs-agent-dashboard 0.10.0 → 0.11.0

package/dist/server/index.d.cts

@@ -203,16 +203,55 @@ type SessionHook = (request: unknown) => Promise<DashboardSessionUser | null> |
 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, per in-flight request — the gate is on the inbound cookie's `iat`, so every
- * request still carrying a not-yet-renewed cookie invokes this hook, not just the first: a page
- * load that fires N parallel API calls can trigger up to N calls before the refreshed cookie lands
- * on the client. Bounded and cheap for typical console traffic, but not a per-session-lifetime
- * cap — a slow or expensive check should debounce/cache 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.
+ * 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;
+/** 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. `/ai-gateway`) — useful for a "back to the console" link. */
+    basePath: string;
+}
+/**
+ * Host-owned page for an unauthenticated 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.
+ *
+ * Served at `<basePath>/auth/session-required`, which is where `DashboardAuthPageGuard` already
+ * redirects a denied Mode-A navigation today — this hook changes what that page CONTAINS, not the
+ * flow that reaches it.
+ *
+ * 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>/auth/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>;
 /** Which `dashboardAuth` hook(s) a resolved config was given — see `resolveDashboardAuth`. */
 type AuthMode = 'session' | 'login';
 /**
@@ -244,6 +283,9 @@ interface DashboardAuthOptions {
     /** 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 used by the guards/controller. */
 interface ResolvedDashboardAuth {
@@ -253,6 +295,7 @@ interface ResolvedDashboardAuth {
     session?: SessionHook;
     login?: LoginHook;
     revalidate?: RevalidateHook;
+    unauthenticatedPage?: UnauthenticatedPageHook;
 }
 /**
  * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
@@ -289,9 +332,10 @@ interface LoginFormBody {
  * 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 configured (`auth.session`/`auth.login` absent), and
- * every route 404s outright when `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to
- * `null`) — no dangling login page when the feature is off.
+ * 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;
@@ -304,7 +348,7 @@ declare class AgentDashboardAuthController {
     login(body: LoginFormBody, req: unknown, res: AuthPageResponse): Promise<string>;
     logout(req: unknown, res: AuthPageResponse): string;
     session(request: unknown, response: unknown): Promise<void>;
-    sessionRequiredPage(): string;
+    sessionRequiredPage(req: AuthPageRequest, res: unknown): Promise<void>;
     /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
     private redirectToLoginError;
     private currentSession;
@@ -314,6 +358,11 @@ declare class AgentDashboardAuthController {
      * endpoint into a stack-trace leak nor floods the logs on repeated bad attempts.
      */
     private runHook;
+    /**
+     * Warn once per hook kind for the life of the process, not once per request: a broken hook fires
+     * on every denied navigation and would otherwise flood the logs.
+     */
+    private warnHookOnce;
     private requireAuth;
 }
 
@@ -587,4 +636,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, 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 };
+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 UnauthenticatedPageContext, type UnauthenticatedPageHook, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };

package/dist/server/index.d.ts

@@ -203,16 +203,55 @@ type SessionHook = (request: unknown) => Promise<DashboardSessionUser | null> |
 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, per in-flight request — the gate is on the inbound cookie's `iat`, so every
- * request still carrying a not-yet-renewed cookie invokes this hook, not just the first: a page
- * load that fires N parallel API calls can trigger up to N calls before the refreshed cookie lands
- * on the client. Bounded and cheap for typical console traffic, but not a per-session-lifetime
- * cap — a slow or expensive check should debounce/cache 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.
+ * 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;
+/** 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. `/ai-gateway`) — useful for a "back to the console" link. */
+    basePath: string;
+}
+/**
+ * Host-owned page for an unauthenticated 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.
+ *
+ * Served at `<basePath>/auth/session-required`, which is where `DashboardAuthPageGuard` already
+ * redirects a denied Mode-A navigation today — this hook changes what that page CONTAINS, not the
+ * flow that reaches it.
+ *
+ * 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>/auth/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>;
 /** Which `dashboardAuth` hook(s) a resolved config was given — see `resolveDashboardAuth`. */
 type AuthMode = 'session' | 'login';
 /**
@@ -244,6 +283,9 @@ interface DashboardAuthOptions {
     /** 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 used by the guards/controller. */
 interface ResolvedDashboardAuth {
@@ -253,6 +295,7 @@ interface ResolvedDashboardAuth {
     session?: SessionHook;
     login?: LoginHook;
     revalidate?: RevalidateHook;
+    unauthenticatedPage?: UnauthenticatedPageHook;
 }
 /**
  * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
@@ -289,9 +332,10 @@ interface LoginFormBody {
  * 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 configured (`auth.session`/`auth.login` absent), and
- * every route 404s outright when `dashboardAuth` is unconfigured (`DASHBOARD_AUTH` resolves to
- * `null`) — no dangling login page when the feature is off.
+ * 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;
@@ -304,7 +348,7 @@ declare class AgentDashboardAuthController {
     login(body: LoginFormBody, req: unknown, res: AuthPageResponse): Promise<string>;
     logout(req: unknown, res: AuthPageResponse): string;
     session(request: unknown, response: unknown): Promise<void>;
-    sessionRequiredPage(): string;
+    sessionRequiredPage(req: AuthPageRequest, res: unknown): Promise<void>;
     /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
     private redirectToLoginError;
     private currentSession;
@@ -314,6 +358,11 @@ declare class AgentDashboardAuthController {
      * endpoint into a stack-trace leak nor floods the logs on repeated bad attempts.
      */
     private runHook;
+    /**
+     * Warn once per hook kind for the life of the process, not once per request: a broken hook fires
+     * on every denied navigation and would otherwise flood the logs.
+     */
+    private warnHookOnce;
     private requireAuth;
 }
 
@@ -587,4 +636,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, 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 };
+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 UnauthenticatedPageContext, type UnauthenticatedPageHook, type WithActorLabel, agentDashboardMountPaths, parsePriceInput, resolveDashboardAuth };

package/dist/server/index.js

@@ -147,6 +147,20 @@ function resolveRawResponse(response) {
   return null;
 }
 __name(resolveRawResponse, "resolveRawResponse");
+function responseAlreadyWritten(response) {
+  const raw = resolveRawResponse(response);
+  return raw?.headersSent === true;
+}
+__name(responseAlreadyWritten, "responseAlreadyWritten");
+function sendHtml(response, status, html) {
+  const raw = resolveRawResponse(response);
+  if (!raw) return;
+  raw.statusCode = status;
+  raw.setHeader("content-type", "text/html; charset=utf-8");
+  raw.setHeader("cache-control", "no-store, must-revalidate");
+  raw.end(html);
+}
+__name(sendHtml, "sendHtml");
 function sendRedirect(response, status, location) {
   const raw = resolveRawResponse(response);
   if (!raw) return;
@@ -261,6 +275,30 @@ function clearSessionCookie(context) {
   appendSetCookie(context.response, cookie);
 }
 __name(clearSessionCookie, "clearSessionCookie");
+var inFlightRevalidations = /* @__PURE__ */ new Map();
+function revalidationKey(session) {
+  return `${session.sub}:${session.iat}`;
+}
+__name(revalidationKey, "revalidationKey");
+function getOrStartRevalidation(auth, session, user) {
+  const hook = auth.revalidate;
+  if (!hook) return Promise.resolve(true);
+  const key = revalidationKey(session);
+  const inFlight = inFlightRevalidations.get(key);
+  if (inFlight) return inFlight;
+  const outcome = (async () => {
+    try {
+      return await hook(user);
+    } catch {
+      return false;
+    }
+  })().finally(() => {
+    inFlightRevalidations.delete(key);
+  });
+  inFlightRevalidations.set(key, outcome);
+  return outcome;
+}
+__name(getOrStartRevalidation, "getOrStartRevalidation");
 async function maybeRenewSession(auth, session, request, response, now = Date.now()) {
   if (now - session.iat <= auth.ttlMs / 2) return true;
   const user = {
@@ -270,20 +308,13 @@ async function maybeRenewSession(auth, session, request, response, now = Date.no
     } : {},
     roles: session.roles
   };
-  if (auth.revalidate) {
-    let allowed;
-    try {
-      allowed = await auth.revalidate(user);
-    } catch {
-      allowed = false;
-    }
-    if (!allowed) {
-      clearSessionCookie({
-        request,
-        response
-      });
-      return false;
-    }
+  const allowed = await getOrStartRevalidation(auth, session, user);
+  if (!allowed) {
+    clearSessionCookie({
+      request,
+      response
+    });
+    return false;
   }
   issueSessionCookie(user, {
     auth,
@@ -1305,7 +1336,7 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   }
   loginPage(req, res, returnToQuery, error) {
     const auth = this.requireAuth();
-    if (!auth.login) throw new NotFoundException();
+    if (!auth.modes.includes("login")) throw new NotFoundException();
     const returnTo = sanitizeReturnTo(this.basePath, returnToQuery);
     if (this.currentSession(req)) {
       res.status(302);
@@ -1320,7 +1351,7 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   }
   async login(body, req, res) {
     const auth = this.requireAuth();
-    if (!auth.login) throw new NotFoundException();
+    if (!auth.modes.includes("login")) throw new NotFoundException();
     const returnTo = sanitizeReturnTo(this.basePath, body?.returnTo);
     const username = body?.username;
     const password = body?.password;
@@ -1348,14 +1379,14 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
       response: res
     });
     res.status(302);
-    res.setHeader("Location", this.auth && !this.auth.login ? `${this.basePath}/auth/session-required` : `${this.basePath}/auth/login`);
+    res.setHeader("Location", this.auth && !this.auth.modes.includes("login") ? `${this.basePath}/auth/session-required` : `${this.basePath}/auth/login`);
     return "";
   }
   // Mode A: the host frontend (carrying its own auth) POSTs here; the host hook validates the raw
   // request and returns the session user, or `null` to deny. No credential reaches this library.
   async session(request, response) {
     const auth = this.requireAuth();
-    if (!auth.session) throw new NotFoundException();
+    if (!auth.modes.includes("session")) throw new NotFoundException();
     const user = await this.runHook("session", () => auth.session?.(request) ?? null);
     if (!user) throw new UnauthorizedException2();
     issueSessionCookie(user, {
@@ -1367,10 +1398,31 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   // Mode-A-only landing: the host mints the session, so there is nothing to submit here. Serves
   // as the redirect target `DashboardAuthPageGuard` bounces to instead of `/auth/login`, which
   // 404s under Mode A (see `loginPage` above).
-  sessionRequiredPage() {
+  //
+  // Non-passthrough `@Res()` (unlike its sibling routes) because `dashboardAuth.unauthenticatedPage`
+  // hands the response to the HOST, which writes and ends it itself — there is no return value for
+  // Nest to send, and letting Nest also send one would double-write. The `Content-Type` /
+  // `Cache-Control` this route used to carry as decorators move into `sendHtml` for the built-in
+  // path; the host owns its own headers on the hook path.
+  async sessionRequiredPage(req, res) {
     const auth = this.requireAuth();
-    if (auth.login) throw new NotFoundException();
-    return renderSessionRequiredPage();
+    if (auth.modes.includes("login")) throw new NotFoundException();
+    const hook = auth.unauthenticatedPage;
+    if (hook) {
+      try {
+        await hook({
+          request: req,
+          response: res,
+          basePath: this.basePath
+        });
+        if (responseAlreadyWritten(res)) return;
+        this.warnHookOnce("unauthenticatedPage", "dashboardAuth.unauthenticatedPage returned without writing a response; falling back to the built-in page. The hook must write AND end the response it is given.");
+      } catch (error) {
+        this.warnHookOnce("unauthenticatedPage", `dashboardAuth.unauthenticatedPage threw; falling back to the built-in page. ${String(error)}`);
+        if (responseAlreadyWritten(res)) return;
+      }
+    }
+    sendHtml(res, 200, renderSessionRequiredPage());
   }
   /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
   redirectToLoginError(res, returnTo) {
@@ -1395,13 +1447,19 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
     try {
       return await run() ?? null;
     } catch (error) {
-      if (!this.warnedHooks.has(kind)) {
-        this.warnedHooks.add(kind);
-        this.logger.warn(`AgentDashboardModule dashboardAuth ${kind} hook threw; treating as denial. ${error instanceof Error ? error.message : String(error)}`);
-      }
+      this.warnHookOnce(kind, `AgentDashboardModule dashboardAuth ${kind} hook threw; treating as denial. ${error instanceof Error ? error.message : String(error)}`);
       return null;
     }
   }
+  /**
+  * Warn once per hook kind for the life of the process, not once per request: a broken hook fires
+  * on every denied navigation and would otherwise flood the logs.
+  */
+  warnHookOnce(kind, message) {
+    if (this.warnedHooks.has(kind)) return;
+    this.warnedHooks.add(kind);
+    this.logger.warn(message);
+  }
   requireAuth() {
     if (!this.auth) throw new NotFoundException();
     return this.auth;
@@ -1470,11 +1528,14 @@ _ts_decorate4([
 ], AgentDashboardAuthController.prototype, "session", null);
 _ts_decorate4([
   Get2("session-required"),
-  Header("Content-Type", "text/html; charset=utf-8"),
-  Header("Cache-Control", "no-store, must-revalidate"),
+  _ts_param4(0, Req2()),
+  _ts_param4(1, Res()),
   _ts_metadata4("design:type", Function),
-  _ts_metadata4("design:paramtypes", []),
-  _ts_metadata4("design:returntype", String)
+  _ts_metadata4("design:paramtypes", [
+    typeof AuthPageRequest === "undefined" ? Object : AuthPageRequest,
+    Object
+  ]),
+  _ts_metadata4("design:returntype", Promise)
 ], AgentDashboardAuthController.prototype, "sessionRequiredPage", null);
 AgentDashboardAuthController = _ts_decorate4([
   Controller2("auth"),
@@ -1615,7 +1676,7 @@ var DashboardAuthPageGuard = class {
   * asserting away) the nullability.
   */
   deny(auth, request) {
-    if (!auth.login) {
+    if (!auth.modes.includes("login")) {
       throw new DashboardAuthRedirect(`${this.basePath}/auth/session-required`);
     }
     const returnTo = readOriginalUrl(request);
@@ -1804,6 +1865,9 @@ function resolveDashboardAuth(options) {
   if (options.revalidate !== void 0 && typeof options.revalidate !== "function") {
     throw new Error("AgentDashboardModule dashboardAuth: `revalidate` must be a function.");
   }
+  if (options.unauthenticatedPage !== void 0 && typeof options.unauthenticatedPage !== "function") {
+    throw new Error("AgentDashboardModule dashboardAuth: `unauthenticatedPage` must be a function.");
+  }
   if (modes.length === 0) {
     throw new Error("AgentDashboardModule dashboardAuth: at least one of `session` (the host mints the session from its own auth) or `login` (the built-in login screen) is required \u2014 otherwise the cookie can never be minted. Failing closed.");
   }
@@ -1819,6 +1883,9 @@ function resolveDashboardAuth(options) {
     } : {},
     ...options.revalidate !== void 0 ? {
       revalidate: options.revalidate
+    } : {},
+    ...options.unauthenticatedPage !== void 0 ? {
+      unauthenticatedPage: options.unauthenticatedPage
     } : {}
   };
 }