@dudousxd/nestjs-agent-dashboard 0.10.1 → 0.11.0

package/README.md

@@ -112,6 +112,30 @@ AgentDashboardModule.forRoot({
 
 Have your host frontend call `POST <basePath>/auth/session` once it knows the visitor is signed in — no body this library reads. Success is `204` with the `Set-Cookie`; a denial is `401` and no cookie is set. An unauthenticated PAGE navigation under Mode-A-only has nowhere to redirect to (there's no login form) — it's served a small, static instruction page at `<basePath>/auth/session-required` instead, telling the visitor to sign in through the host app and reload.
 
+##### `unauthenticatedPage` — render that instruction page yourself
+
+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 your launcher, link to it, or look like the rest of your product. Pass `unauthenticatedPage` and the whole response is yours:
+
+```ts
+AgentDashboardModule.forRoot({
+  dashboardAuth: {
+    secret: process.env.AGENT_DASHBOARD_SECRET,
+    session: (request) => resolveAdmin(request),
+    unauthenticatedPage: ({ request, response, basePath }) => {
+      // `request`/`response` are your platform's own objects (Express here). Render however you
+      // already render — a template engine, @dudousxd/nestjs-inertia, a plain string.
+      (response as Response).status(401).render('console-locked', { returnTo: basePath });
+    },
+  },
+});
+```
+
+The hook **owns** the response: it must write AND end it. It replaces what `<basePath>/auth/session-required` *contains*, not the flow that reaches it — a denied navigation is still redirected there.
+
+It cannot open the console: it only ever runs on a request that has already been denied. If it throws, or returns without writing, the library logs one warning and falls back to the built-in page, so a broken page can't hang the request or turn a denial into a `500`. It is also not a mode — `unauthenticatedPage` alone still fails boot on the "at least one of `session` or `login`" check.
+
+Under Mode B this route stays `404`: there is no session-required page to customise, because a denied navigation goes to the login form instead. To ship your own **login** UI, combine Mode A with this hook and `POST <basePath>/auth/session` from your page — that mint endpoint is the supported primitive for it.
+
 #### Mode B — `login` (built-in login screen)
 
 No host frontend/IdP to lean on — the console serves its own small, dependency-free, server-rendered login page. An unauthenticated page visit is redirected (302) to a built-in login form at `<basePath>/auth/login`.

package/dist/server/index.cjs

@@ -189,6 +189,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;
@@ -1426,10 +1440,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 import_common7.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) {
@@ -1454,13 +1489,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 import_common7.NotFoundException();
     return this.auth;
@@ -1529,11 +1570,14 @@ _ts_decorate4([
 ], AgentDashboardAuthController.prototype, "session", null);
 _ts_decorate4([
   (0, import_common7.Get)("session-required"),
-  (0, import_common7.Header)("Content-Type", "text/html; charset=utf-8"),
-  (0, import_common7.Header)("Cache-Control", "no-store, must-revalidate"),
+  _ts_param4(0, (0, import_common7.Req)()),
+  _ts_param4(1, (0, import_common7.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([
   (0, import_common7.Controller)("auth"),
@@ -1863,6 +1907,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.");
   }
@@ -1878,6 +1925,9 @@ function resolveDashboardAuth(options) {
     } : {},
     ...options.revalidate !== void 0 ? {
       revalidate: options.revalidate
+    } : {},
+    ...options.unauthenticatedPage !== void 0 ? {
+      unauthenticatedPage: options.unauthenticatedPage
     } : {}
   };
 }