@dudousxd/nestjs-agent-dashboard 0.9.0 → 0.10.0

package/README.md

@@ -42,7 +42,7 @@ AgentDashboardModule.forRoot({
   basePath?: string;             // where the SPA is served. Default '/ai-gateway'
   apiBasePath?: string;          // where the JSON/SSE API is mounted. Default '<basePath>/api'
   guards?: Type<CanActivate>[];  // bring-your-own auth — see "Console auth" below
-  dashboardAuth?: DashboardAuthOptions; // built-in login screen — see "Console auth" below
+  dashboardAuth?: DashboardAuthOptions; // signed-cookie gate (Mode A session / Mode B login) — see "Console auth" below
   imports?: DynamicModule['imports'];
   approvalActorRef?: (req) => string | undefined;
 });
@@ -56,7 +56,7 @@ The console has no auth of its own by default — pick one of three postures, or
 | ------- | ----------- | ----- |
 | **Open** (default) | Local dev only. Never mount this way in production. | Omit both `guards` and `dashboardAuth`. |
 | **`guards`** | You already have auth the console can reuse — an existing cookie-session guard, an SSO/OIDC session, a header your reverse proxy injects. | Pass guard classes; see below. |
-| **`dashboardAuth`** | You have no ready-made guard for the console — e.g. your app authenticates with a header-only Bearer token a browser navigation can't attach — and want the simplest path to a protected console with zero SSO setup. | Pass `{ secret, login }`; see below. |
+| **`dashboardAuth`** | You have no ready-made guard for the console — e.g. your app authenticates with a header-only Bearer token a browser navigation can't attach — and want a protected console without building a whole `CanActivate`. Two modes: `session` (host mints the cookie from its own auth) or `login` (built-in login screen). | Pass `{ secret, session }` and/or `{ secret, login }`; see below. |
 
 Both `guards` and `dashboardAuth` can be set together — **AND semantics**: a request must pass BOTH. `dashboardAuth`'s own gate runs first; a denied request never reaches your `guards`.
 
@@ -90,9 +90,31 @@ class ConsoleSessionGuard implements CanActivate {
 export class AppModule {}
 ```
 
-### Option B — `dashboardAuth` (built-in login screen)
+### Option B — `dashboardAuth` (signed session cookie)
 
-Gates the console behind a stateless, signed session cookie (HMAC-SHA256, `node:crypto` only — no JWT dependency, no session store, mirrors `@dudousxd/nestjs-telescope`'s `dashboardAuth`). An unauthenticated page visit is redirected (302) to a built-in login form at `<basePath>/auth/login`; an unauthenticated API call gets `401`.
+Gates the console behind a stateless, signed session cookie (HMAC-SHA256, `node:crypto` only — no JWT dependency, no session store, mirrors `@dudousxd/nestjs-telescope`'s `dashboardAuth`). Two ways to mint that cookie — **Mode A** (`session`) and **Mode B** (`login`). At least one is required, or `forRoot`/`forRootAsync` throws at boot (an un-mintable gate is a boot error, not a silently-open console); you can also configure both together (e.g. Mode A for normal use, Mode B as a break-glass fallback). An unauthenticated API call always gets `401`, regardless of mode.
+
+#### Mode A — `session` (the host mints the cookie)
+
+Your host app already has its own auth (SSO/OIDC/whatever) — no need to teach this library a second credential. The host frontend, carrying that auth, `POST`s to `<basePath>/auth/session`; your `session` hook validates the raw request and returns the session user, or `null` to deny (`401`). No credential this library understands ever exists.
+
+```ts
+AgentDashboardModule.forRoot({
+  dashboardAuth: {
+    secret: process.env.AI_GATEWAY_AUTH_SECRET, // REQUIRED — 32+ bytes recommended. Missing => boot error.
+    session: async (request) => {
+      const user = await sessions.verifyFromCookie(request); // read YOUR app's own session
+      return user ? { id: user.id, name: user.name, roles: user.roles } : null; // null => 401
+    },
+  },
+});
+```
+
+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.
+
+#### 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`.
 
 ```ts
 AgentDashboardModule.forRoot({
@@ -107,7 +129,9 @@ AgentDashboardModule.forRoot({
 });
 ```
 
-Open `/ai-gateway`, enter the credentials, and you're in. Bad credentials get a **uniform** redirect back to the login page — the response is identical for an unknown user and a wrong password, so the endpoint never reveals which one was wrong. `POST <basePath>/auth/logout` clears the cookie.
+Open `/ai-gateway`, enter the credentials, and you're in. Bad credentials get a **uniform** redirect back to the login page — the response is identical for an unknown user and a wrong password, so the endpoint never reveals which one was wrong. `POST <basePath>/auth/logout` clears the cookie (redirecting back to the login form, or — Mode-A-only — to the `session-required` instruction page above).
+
+Only `username` is required (non-empty) — the password is passed through to `login` verbatim, including empty, so a host that authenticates by username/email alone (password deliberately ignored) can use the built-in screen unmodified; the hook owns whether an empty password is accepted or rejected.
 
 Need the `login` hook to reach a DB (e.g. an `EntityManager`)? Use `forRootAsync` — `basePath`/`apiBasePath`/`guards` stay static (needed at module-build time for routing), only the auth config is resolved through DI:
 
@@ -127,6 +151,20 @@ AgentDashboardModule.forRootAsync({
 });
 ```
 
+#### Session lifetime: `ttl`, sliding renewal, and `revalidate`
+
+Any request carrying a valid cookie past 50% of its `ttl` gets a freshly re-signed one, so an active tab never expires mid-use. `revalidate?: (session) => boolean | Promise<boolean>` hooks into that same sliding-renewal path — a chance to re-check a *live* session (e.g. "is this user still active?") before the fresh cookie ships, so a deactivated or demoted operator loses access instead of riding a self-renewing cookie for as long as the tab stays open. Return `false` (or throw) to revoke: the cookie is cleared and the request denied, the same treatment as an absent cookie. It runs at most once per `ttl/2` per cookie generation, per in-flight request — concurrent requests still carrying the same not-yet-renewed cookie each invoke it (a page load firing several parallel API calls can trigger several calls before the refreshed cookie lands), so size it for occasional concurrent invocations, not a strict once-per-session cap. `revalidate` alone can't mint a session — it doesn't count toward the `session`/`login` "at least one" requirement.
+
+```ts
+AgentDashboardModule.forRoot({
+  dashboardAuth: {
+    secret: process.env.AI_GATEWAY_AUTH_SECRET,
+    session: async (request) => /* ... */,
+    revalidate: async (session) => (await users.findActive(session.id)) !== null,
+  },
+});
+```
+
 ## JSON + SSE API
 
 Mounted at `apiBasePath`:

package/dist/server/index.cjs

@@ -303,6 +303,39 @@ function clearSessionCookie(context) {
   appendSetCookie(context.response, cookie);
 }
 __name(clearSessionCookie, "clearSessionCookie");
+async function maybeRenewSession(auth, session, request, response, now = Date.now()) {
+  if (now - session.iat <= auth.ttlMs / 2) return true;
+  const user = {
+    id: session.sub,
+    ...session.name !== void 0 ? {
+      name: session.name
+    } : {},
+    roles: session.roles
+  };
+  if (auth.revalidate) {
+    let allowed;
+    try {
+      allowed = await auth.revalidate(user);
+    } catch {
+      allowed = false;
+    }
+    if (!allowed) {
+      clearSessionCookie({
+        request,
+        response
+      });
+      return false;
+    }
+  }
+  issueSessionCookie(user, {
+    auth,
+    request,
+    response,
+    now
+  });
+  return true;
+}
+__name(maybeRenewSession, "maybeRenewSession");
 
 // src/server/auth/dashboard-auth.guard.ts
 function _ts_decorate(decorators, target, key, desc) {
@@ -330,14 +363,16 @@ var DashboardAuthGuard = class {
   constructor(auth) {
     this.auth = auth;
   }
-  canActivate(context) {
+  async canActivate(context) {
     if (!this.auth) return true;
     const http = context.switchToHttp();
     const request = http.getRequest();
     const session = this.verifyRequestSession(request);
     if (!session) throw new import_common.UnauthorizedException();
     attachSession(request, session);
-    this.maybeRenew(http.getResponse(), request, session);
+    if (!await maybeRenewSession(this.auth, session, request, http.getResponse())) {
+      throw new import_common.UnauthorizedException();
+    }
     return true;
   }
   verifyRequestSession(request) {
@@ -349,28 +384,6 @@ var DashboardAuthGuard = class {
       secret: auth.secret
     });
   }
-  /**
-  * Sliding renewal: a valid cookie past 50% of its TTL is transparently re-issued on the
-  * response, so an active user never gets logged out mid-session.
-  */
-  maybeRenew(response, request, session) {
-    const auth = this.auth;
-    if (!auth) return;
-    const now = Date.now();
-    if (now - session.iat <= auth.ttlMs / 2) return;
-    issueSessionCookie({
-      id: session.sub,
-      ...session.name !== void 0 ? {
-        name: session.name
-      } : {},
-      roles: session.roles
-    }, {
-      auth,
-      request,
-      response,
-      now
-    });
-  }
 };
 DashboardAuthGuard = _ts_decorate([
   (0, import_common.Injectable)(),
@@ -1166,17 +1179,14 @@ function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
 __name(escapeHtml, "escapeHtml");
-function renderLoginPage(options) {
-  const action = escapeHtml(options.actionUrl);
-  const returnTo = escapeHtml(options.returnTo);
-  const errorBanner = options.error === true ? '<p role="alert" class="error">Invalid username or password.</p>' : "";
+function pageShell(content, title) {
   return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <meta name="robots" content="noindex, nofollow" />
-<title>Sign in \u2014 AI Gateway</title>
+<title>${title}</title>
 <style>
   :root { color-scheme: dark; }
   * { box-sizing: border-box; }
@@ -1207,6 +1217,13 @@ function renderLoginPage(options) {
     font-weight: 600;
     color: #34d399;
   }
+  h1 {
+    margin: 0 0 12px;
+    font-size: 16px;
+    font-weight: 600;
+    color: #f4f4f5;
+  }
+  p { margin: 0 0 16px; color: #a1a1aa; }
   form { display: flex; flex-direction: column; gap: 16px; }
   label { display: flex; flex-direction: column; gap: 6px; }
   .field-label {
@@ -1245,7 +1262,17 @@ function renderLoginPage(options) {
 </head>
 <body>
   <div class="card">
-    <p class="brand">AI Gateway</p>
+    ${content}
+  </div>
+</body>
+</html>`;
+}
+__name(pageShell, "pageShell");
+function renderLoginPage(options) {
+  const action = escapeHtml(options.actionUrl);
+  const returnTo = escapeHtml(options.returnTo);
+  const errorBanner = options.error === true ? '<p role="alert" class="error">Invalid username or password.</p>' : "";
+  return pageShell(`<p class="brand">AI Gateway</p>
     <form method="post" action="${action}">
       <input type="hidden" name="returnTo" value="${returnTo}" />
       <label>
@@ -1258,12 +1285,15 @@ function renderLoginPage(options) {
       </label>
       ${errorBanner}
       <button type="submit">Sign in</button>
-    </form>
-  </div>
-</body>
-</html>`;
+    </form>`, "Sign in \u2014 AI Gateway");
 }
 __name(renderLoginPage, "renderLoginPage");
+function renderSessionRequiredPage() {
+  return pageShell(`<p class="brand">AI Gateway</p>
+    <h1>Open this console from your application</h1>
+    <p>Your session is minted by the host app. Use its console launcher to sign in, then reload.</p>`, "Sign in \u2014 AI Gateway");
+}
+__name(renderSessionRequiredPage, "renderSessionRequiredPage");
 
 // src/server/auth/sanitize-return-to.ts
 function sanitizeReturnTo(basePath, returnTo) {
@@ -1295,9 +1325,13 @@ function _ts_param4(paramIndex, decorator) {
 }
 __name(_ts_param4, "_ts_param");
 function isNonEmptyString(value) {
-  return typeof value === "string" && value !== "";
+  return typeof value === "string" && value.trim() !== "";
 }
 __name(isNonEmptyString, "isNonEmptyString");
+function isString(value) {
+  return typeof value === "string";
+}
+__name(isString, "isString");
 var AgentDashboardAuthController = class _AgentDashboardAuthController {
   static {
     __name(this, "AgentDashboardAuthController");
@@ -1305,14 +1339,15 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   auth;
   basePath;
   logger = new import_common7.Logger(_AgentDashboardAuthController.name);
-  /** Warn once (not per request) so a broken hook can't be used to flood the logs. */
-  warnedLoginHookThrow = false;
+  /** Warn once PER HOOK KIND (not per request) so a broken hook can't be used to flood the logs. */
+  warnedHooks = /* @__PURE__ */ new Set();
   constructor(auth, basePath) {
     this.auth = auth;
     this.basePath = basePath;
   }
   loginPage(req, res, returnToQuery, error) {
-    this.requireAuth();
+    const auth = this.requireAuth();
+    if (!auth.login) throw new import_common7.NotFoundException();
     const returnTo = sanitizeReturnTo(this.basePath, returnToQuery);
     if (this.currentSession(req)) {
       res.status(302);
@@ -1327,14 +1362,15 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
   }
   async login(body, req, res) {
     const auth = this.requireAuth();
+    if (!auth.login) throw new import_common7.NotFoundException();
     const returnTo = sanitizeReturnTo(this.basePath, body?.returnTo);
     const username = body?.username;
     const password = body?.password;
-    if (!isNonEmptyString(username) || !isNonEmptyString(password)) {
+    if (!isNonEmptyString(username) || password !== void 0 && !isString(password)) {
       this.redirectToLoginError(res, returnTo);
       return "";
     }
-    const user = await this.runLoginHook(auth, username, password);
+    const user = await this.runHook("login", () => auth.login?.(username.trim(), isString(password) ? password : "") ?? null);
     if (!user) {
       this.redirectToLoginError(res, returnTo);
       return "";
@@ -1354,9 +1390,30 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
       response: res
     });
     res.status(302);
-    res.setHeader("Location", `${this.basePath}/auth/login`);
+    res.setHeader("Location", this.auth && !this.auth.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();
+    const user = await this.runHook("session", () => auth.session?.(request) ?? null);
+    if (!user) throw new import_common7.UnauthorizedException();
+    issueSessionCookie(user, {
+      auth,
+      request,
+      response
+    });
+  }
+  // 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() {
+    const auth = this.requireAuth();
+    if (auth.login) throw new import_common7.NotFoundException();
+    return renderSessionRequiredPage();
+  }
   /** Uniform failure: same redirect (generic error flag) whether the user is unknown or the password is wrong. */
   redirectToLoginError(res, returnTo) {
     res.status(303);
@@ -1372,17 +1429,17 @@ var AgentDashboardAuthController = class _AgentDashboardAuthController {
     }) !== null;
   }
   /**
-  * 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.
   */
-  async runLoginHook(auth, username, password) {
+  async runHook(kind, run) {
     try {
-      return await auth.login(username, password) ?? null;
+      return await run() ?? null;
     } catch (error) {
-      if (!this.warnedLoginHookThrow) {
-        this.warnedLoginHookThrow = true;
-        this.logger.warn(`AgentDashboardModule dashboardAuth login hook threw; treating as denial. ${error instanceof Error ? error.message : String(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)}`);
       }
       return null;
     }
@@ -1439,6 +1496,28 @@ _ts_decorate4([
   ]),
   _ts_metadata4("design:returntype", String)
 ], AgentDashboardAuthController.prototype, "logout", null);
+_ts_decorate4([
+  (0, import_common7.Post)("session"),
+  (0, import_common7.HttpCode)(204),
+  _ts_param4(0, (0, import_common7.Req)()),
+  _ts_param4(1, (0, import_common7.Res)({
+    passthrough: true
+  })),
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", [
+    Object,
+    Object
+  ]),
+  _ts_metadata4("design:returntype", Promise)
+], 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_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", []),
+  _ts_metadata4("design:returntype", String)
+], AgentDashboardAuthController.prototype, "sessionRequiredPage", null);
 AgentDashboardAuthController = _ts_decorate4([
   (0, import_common7.Controller)("auth"),
   _ts_param4(0, (0, import_common7.Optional)()),
@@ -1551,19 +1630,39 @@ var DashboardAuthPageGuard = class {
     this.auth = auth;
     this.basePath = basePath;
   }
-  canActivate(context) {
+  async canActivate(context) {
     if (!this.auth) return true;
+    const auth = this.auth;
     const http = context.switchToHttp();
     const request = http.getRequest();
     const session = this.verifyRequestSession(request);
-    if (!session) {
-      const returnTo = readOriginalUrl(request);
-      throw new DashboardAuthRedirect(`${this.basePath}/auth/login?returnTo=${encodeURIComponent(returnTo)}`);
-    }
+    if (!session) this.deny(auth, request);
     attachSession(request, session);
-    this.maybeRenew(http.getResponse(), request, session);
+    if (!await maybeRenewSession(auth, session, request, http.getResponse())) {
+      this.deny(auth, request);
+    }
     return true;
   }
+  /**
+  * No valid session: bounce the browser navigation onward. Under Mode B (`login` configured)
+  * that's the built-in login screen, carrying `returnTo` back to the page that was requested.
+  * Under Mode-A-only there is no login screen to redirect to — the host mints the session
+  * itself — so this instead serves the instruction page rather than redirecting into a 404.
+  * Pulled out of `canActivate` so both the "no session at all" and the "revalidate revoked a
+  * renewable session" paths reuse the exact same mode-aware deny logic.
+  *
+  * Takes `auth` explicitly rather than reading `this.auth`: `canActivate`'s `!this.auth` early
+  * return narrows the field within that method only — TS doesn't carry it across a method call —
+  * so the caller passes the already-narrowed value instead of this method re-deriving (or
+  * asserting away) the nullability.
+  */
+  deny(auth, request) {
+    if (!auth.login) {
+      throw new DashboardAuthRedirect(`${this.basePath}/auth/session-required`);
+    }
+    const returnTo = readOriginalUrl(request);
+    throw new DashboardAuthRedirect(`${this.basePath}/auth/login?returnTo=${encodeURIComponent(returnTo)}`);
+  }
   verifyRequestSession(request) {
     const auth = this.auth;
     if (!auth) return null;
@@ -1573,28 +1672,6 @@ var DashboardAuthPageGuard = class {
       secret: auth.secret
     });
   }
-  /**
-  * Sliding renewal: a valid cookie past 50% of its TTL is transparently re-issued on the
-  * response, so an active user never gets logged out mid-session.
-  */
-  maybeRenew(response, request, session) {
-    const auth = this.auth;
-    if (!auth) return;
-    const now = Date.now();
-    if (now - session.iat <= auth.ttlMs / 2) return;
-    issueSessionCookie({
-      id: session.sub,
-      ...session.name !== void 0 ? {
-        name: session.name
-      } : {},
-      roles: session.roles
-    }, {
-      auth,
-      request,
-      response,
-      now
-    });
-  }
 };
 DashboardAuthPageGuard = _ts_decorate6([
   (0, import_common9.Injectable)(),
@@ -1753,13 +1830,38 @@ function resolveDashboardAuth(options) {
   if (typeof options.secret !== "string" || options.secret === "") {
     throw new Error("AgentDashboardModule dashboardAuth: `secret` is required and must be a non-empty string (HMAC-SHA256 signing key, 32+ bytes recommended). Failing closed.");
   }
-  if (typeof options.login !== "function") {
-    throw new Error("AgentDashboardModule dashboardAuth: `login` is required (validates submitted credentials for the built-in login screen). Failing closed.");
+  const modes = [];
+  if (options.session !== void 0) {
+    if (typeof options.session !== "function") {
+      throw new Error("AgentDashboardModule dashboardAuth: `session` must be a function.");
+    }
+    modes.push("session");
+  }
+  if (options.login !== void 0) {
+    if (typeof options.login !== "function") {
+      throw new Error("AgentDashboardModule dashboardAuth: `login` must be a function.");
+    }
+    modes.push("login");
+  }
+  if (options.revalidate !== void 0 && typeof options.revalidate !== "function") {
+    throw new Error("AgentDashboardModule dashboardAuth: `revalidate` 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.");
   }
   return {
     secret: options.secret,
     ttlMs: durationToMs(options.ttl ?? DEFAULT_TTL),
-    login: options.login
+    modes,
+    ...options.session !== void 0 ? {
+      session: options.session
+    } : {},
+    ...options.login !== void 0 ? {
+      login: options.login
+    } : {},
+    ...options.revalidate !== void 0 ? {
+      revalidate: options.revalidate
+    } : {}
   };
 }
 __name(resolveDashboardAuth, "resolveDashboardAuth");