@dudousxd/nestjs-agent-dashboard 0.10.1 → 0.12.0

package/dist/server/index.d.cts

@@ -214,6 +214,44 @@ type LoginHook = (username: string, password: string) => Promise<DashboardSessio
  * 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';
 /**
@@ -245,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 {
@@ -254,6 +295,7 @@ interface ResolvedDashboardAuth {
     session?: SessionHook;
     login?: LoginHook;
     revalidate?: RevalidateHook;
+    unauthenticatedPage?: UnauthenticatedPageHook;
 }
 /**
  * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
@@ -306,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;
@@ -316,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;
 }
 
@@ -589,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

@@ -214,6 +214,44 @@ type LoginHook = (username: string, password: string) => Promise<DashboardSessio
  * 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';
 /**
@@ -245,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 {
@@ -254,6 +295,7 @@ interface ResolvedDashboardAuth {
     session?: SessionHook;
     login?: LoginHook;
     revalidate?: RevalidateHook;
+    unauthenticatedPage?: UnauthenticatedPageHook;
 }
 /**
  * Validate + resolve `dashboardAuth`. Returns `null` when unconfigured (behavior unchanged — the
@@ -306,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;
@@ -316,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;
 }
 
@@ -589,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;
@@ -1384,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.modes.includes("login")) throw new NotFoundException();
-    return renderSessionRequiredPage();
+    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) {
@@ -1412,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;
@@ -1487,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"),
@@ -1821,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.");
   }
@@ -1836,6 +1883,9 @@ function resolveDashboardAuth(options) {
     } : {},
     ...options.revalidate !== void 0 ? {
       revalidate: options.revalidate
+    } : {},
+    ...options.unauthenticatedPage !== void 0 ? {
+      unauthenticatedPage: options.unauthenticatedPage
     } : {}
   };
 }