@dudousxd/nestjs-agent-dashboard 0.10.0 → 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;
@@ -303,6 +317,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 = {
@@ -312,20 +350,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,
@@ -1347,7 +1378,7 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   }
   loginPage(req, res, returnToQuery, error) {
     const auth = this.requireAuth();
-    if (!auth.login) throw new import_common7.NotFoundException();
+    if (!auth.modes.includes("login")) throw new import_common7.NotFoundException();
     const returnTo = sanitizeReturnTo(this.basePath, returnToQuery);
     if (this.currentSession(req)) {
       res.status(302);
@@ -1362,7 +1393,7 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   }
   async login(body, req, res) {
     const auth = this.requireAuth();
-    if (!auth.login) throw new import_common7.NotFoundException();
+    if (!auth.modes.includes("login")) throw new import_common7.NotFoundException();
     const returnTo = sanitizeReturnTo(this.basePath, body?.returnTo);
     const username = body?.username;
     const password = body?.password;
@@ -1390,14 +1421,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 import_common7.NotFoundException();
+    if (!auth.modes.includes("session")) throw new import_common7.NotFoundException();
     const user = await this.runHook("session", () => auth.session?.(request) ?? null);
     if (!user) throw new import_common7.UnauthorizedException();
     issueSessionCookie(user, {
@@ -1409,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.login) throw new import_common7.NotFoundException();
-    return renderSessionRequiredPage();
+    if (auth.modes.includes("login")) throw new import_common7.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) {
@@ -1437,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;
@@ -1512,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"),
@@ -1657,7 +1718,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);
@@ -1846,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.");
   }
@@ -1861,6 +1925,9 @@ function resolveDashboardAuth(options) {
     } : {},
     ...options.revalidate !== void 0 ? {
       revalidate: options.revalidate
+    } : {},
+    ...options.unauthenticatedPage !== void 0 ? {
+      unauthenticatedPage: options.unauthenticatedPage
     } : {}
   };
 }