@dudousxd/nestjs-durable-dashboard 0.30.0 → 0.32.0

package/dist/server/index.js

@@ -523,15 +523,469 @@ DurableApiController = _ts_decorate2([
   ])
 ], DurableApiController);
 
-// src/server/durable-dashboard.module.ts
-import { Module } from "@nestjs/common";
-import { RouterModule } from "@nestjs/core";
+// src/server/durable-auth.controller.ts
+import { BadRequestException, Body as Body2, Controller as Controller3, Get as Get3, Header as Header3, HttpCode, Inject as Inject3, Logger, NotFoundException as NotFoundException3, Optional as Optional2, Post as Post2, Req, Res, UnauthorizedException } from "@nestjs/common";
+
+// src/server/auth/dashboard-auth-config.ts
+var DASHBOARD_AUTH = Symbol("DASHBOARD_AUTH");
+var DEFAULT_TTL = "8h";
+var DEFAULT_TTL_MS = 8 * 60 * 60 * 1e3;
+var DURATION_UNITS = {
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
+};
+function durationToMs(ttl) {
+  const match = /^(\d+)([smhd])$/.exec(ttl.trim());
+  if (!match) return DEFAULT_TTL_MS;
+  const unit = DURATION_UNITS[match[2] ?? ""];
+  if (unit === void 0) return DEFAULT_TTL_MS;
+  return Number(match[1]) * unit;
+}
+__name(durationToMs, "durationToMs");
+function resolveDashboardAuth(options) {
+  if (options === void 0) return null;
+  if (typeof options.secret !== "string" || options.secret === "") {
+    throw new Error("DurableDashboardModule: 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("DurableDashboardModule: dashboardAuth.login is required (a login hook).");
+  }
+  return {
+    secret: options.secret,
+    ttlMs: durationToMs(options.ttl ?? DEFAULT_TTL),
+    login: options.login
+  };
+}
+__name(resolveDashboardAuth, "resolveDashboardAuth");
+
+// src/server/auth/login-page.ts
+function renderLoginPage(basePath) {
+  const loginAction = `${basePath}/login`;
+  const defaultReturnTo = basePath;
+  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 Durable</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+    background: #0b0f14;
+    color: #e5e7eb;
+  }
+  main {
+    width: 100%;
+    max-width: 360px;
+    padding: 32px;
+  }
+  h1 {
+    font-size: 18px;
+    font-weight: 600;
+    margin: 0 0 4px;
+  }
+  p.subtitle {
+    margin: 0 0 24px;
+    color: #9ca3af;
+    font-size: 13px;
+  }
+  label {
+    display: block;
+    font-size: 12px;
+    font-weight: 500;
+    margin-bottom: 6px;
+    color: #cbd5e1;
+  }
+  input {
+    width: 100%;
+    padding: 8px 10px;
+    margin-bottom: 16px;
+    border-radius: 6px;
+    border: 1px solid #374151;
+    background: #111827;
+    color: #e5e7eb;
+    font-size: 14px;
+  }
+  input:focus { outline: 2px solid #3b82f6; outline-offset: 1px; }
+  button {
+    width: 100%;
+    padding: 9px 10px;
+    border-radius: 6px;
+    border: none;
+    background: #3b82f6;
+    color: white;
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  button:disabled { opacity: 0.6; cursor: default; }
+  button:hover:not(:disabled) { background: #2563eb; }
+  #error {
+    display: none;
+    margin-bottom: 16px;
+    padding: 8px 10px;
+    border-radius: 6px;
+    background: #7f1d1d;
+    color: #fecaca;
+    font-size: 13px;
+  }
+</style>
+</head>
+<body>
+<main>
+  <h1>Durable control plane</h1>
+  <p class="subtitle">Sign in to continue.</p>
+  <div id="error" role="alert">Invalid username or password.</div>
+  <form id="login-form" autocomplete="on">
+    <label for="username">Username</label>
+    <input id="username" name="username" type="text" autocomplete="username" required autofocus />
+    <label for="password">Password</label>
+    <input id="password" name="password" type="password" autocomplete="current-password" required />
+    <button id="submit" type="submit">Sign in</button>
+  </form>
+</main>
+<script>
+(function () {
+  var LOGIN_ACTION = ${JSON.stringify(loginAction)};
+  var DEFAULT_RETURN_TO = ${JSON.stringify(defaultReturnTo)};
+  var params = new URLSearchParams(window.location.search);
+  var errorBox = document.getElementById('error');
+  if (params.get('error')) errorBox.style.display = 'block';
+
+  function sameOriginReturnTo(value) {
+    if (typeof value !== 'string' || value === '') return DEFAULT_RETURN_TO;
+    if (value.charAt(0) !== '/' || value.charAt(1) === '/' || value.indexOf('://') !== -1) {
+      return DEFAULT_RETURN_TO;
+    }
+    return value;
+  }
+
+  var form = document.getElementById('login-form');
+  var submitButton = document.getElementById('submit');
+  form.addEventListener('submit', function (event) {
+    event.preventDefault();
+    submitButton.disabled = true;
+    errorBox.style.display = 'none';
+    var returnTo = sameOriginReturnTo(params.get('returnTo'));
+    fetch(LOGIN_ACTION, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      credentials: 'same-origin',
+      body: JSON.stringify({
+        username: document.getElementById('username').value,
+        password: document.getElementById('password').value,
+        returnTo: returnTo,
+      }),
+    })
+      .then(function (response) {
+        if (!response.ok) throw new Error('unauthorized');
+        return response.json();
+      })
+      .then(function (data) {
+        window.location.href = data.redirectTo || DEFAULT_RETURN_TO;
+      })
+      .catch(function () {
+        errorBox.style.display = 'block';
+        submitButton.disabled = false;
+      });
+  });
+})();
+</script>
+</body>
+</html>`;
+}
+__name(renderLoginPage, "renderLoginPage");
+
+// src/server/auth/request.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isRecord, "isRecord");
+function readHeaders(request) {
+  if (!isRecord(request)) return {};
+  const headers = request.headers;
+  return isRecord(headers) ? headers : {};
+}
+__name(readHeaders, "readHeaders");
+function headerToString(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((part) => typeof part === "string")) {
+    return value.join(",");
+  }
+  return void 0;
+}
+__name(headerToString, "headerToString");
+function readCookieHeader(request) {
+  return headerToString(readHeaders(request).cookie);
+}
+__name(readCookieHeader, "readCookieHeader");
+function isHttpsRequest(request) {
+  if (isRecord(request) && request.protocol === "https") return true;
+  const forwarded = headerToString(readHeaders(request)["x-forwarded-proto"]);
+  if (forwarded === void 0) return false;
+  return forwarded.split(",").map((proto) => proto.trim().toLowerCase()).includes("https");
+}
+__name(isHttpsRequest, "isHttpsRequest");
+function originalRequestUrl(request) {
+  if (!isRecord(request)) return "/";
+  if (typeof request.originalUrl === "string" && request.originalUrl !== "") {
+    return request.originalUrl;
+  }
+  if (typeof request.url === "string" && request.url !== "") return request.url;
+  return "/";
+}
+__name(originalRequestUrl, "originalRequestUrl");
+function sanitizeReturnTo(candidate, fallback) {
+  if (typeof candidate !== "string") return fallback;
+  if (!candidate.startsWith("/")) return fallback;
+  if (candidate.startsWith("//")) return fallback;
+  if (candidate.includes("://")) return fallback;
+  return candidate;
+}
+__name(sanitizeReturnTo, "sanitizeReturnTo");
+
+// src/server/auth/response.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isRecord2, "isRecord");
+function isRawCookieResponse(value) {
+  return isRecord2(value) && typeof value.getHeader === "function" && typeof value.setHeader === "function";
+}
+__name(isRawCookieResponse, "isRawCookieResponse");
+function resolveCookieResponse(response) {
+  if (isRawCookieResponse(response)) return response;
+  if (isRecord2(response) && isRawCookieResponse(response.raw)) return response.raw;
+  return null;
+}
+__name(resolveCookieResponse, "resolveCookieResponse");
+function existingSetCookies(response) {
+  const current = response.getHeader("set-cookie");
+  if (Array.isArray(current)) return current;
+  if (typeof current === "string") return [
+    current
+  ];
+  return [];
+}
+__name(existingSetCookies, "existingSetCookies");
+function appendSetCookie(response, cookie) {
+  const raw = resolveCookieResponse(response);
+  if (!raw) return;
+  raw.setHeader("set-cookie", [
+    ...existingSetCookies(raw),
+    cookie
+  ]);
+}
+__name(appendSetCookie, "appendSetCookie");
+function isRawRedirectResponse(value) {
+  return isRecord2(value) && typeof value.getHeader === "function" && typeof value.setHeader === "function" && typeof value.end === "function";
+}
+__name(isRawRedirectResponse, "isRawRedirectResponse");
+function resolveRedirectResponse(response) {
+  if (isRawRedirectResponse(response)) return response;
+  if (isRecord2(response) && isRawRedirectResponse(response.raw)) return response.raw;
+  return null;
+}
+__name(resolveRedirectResponse, "resolveRedirectResponse");
+function redirectRaw(response, location, status = 302) {
+  const raw = resolveRedirectResponse(response);
+  if (!raw) return;
+  raw.statusCode = status;
+  raw.setHeader("location", location);
+  raw.end();
+}
+__name(redirectRaw, "redirectRaw");
+
+// src/server/auth/cookie-header.ts
+function parseCookieHeader(header) {
+  const cookies = {};
+  if (typeof header !== "string" || header === "") return cookies;
+  for (const segment of header.split(";")) {
+    const eq = segment.indexOf("=");
+    if (eq <= 0) continue;
+    const name = segment.slice(0, eq).trim();
+    if (name === "") continue;
+    let rawValue = segment.slice(eq + 1).trim();
+    if (rawValue.length >= 2 && rawValue.startsWith('"') && rawValue.endsWith('"')) {
+      rawValue = rawValue.slice(1, -1);
+    }
+    if (name in cookies) continue;
+    try {
+      cookies[name] = decodeURIComponent(rawValue);
+    } catch {
+      cookies[name] = rawValue;
+    }
+  }
+  return cookies;
+}
+__name(parseCookieHeader, "parseCookieHeader");
+function serializeSetCookie(name, value, options) {
+  const parts = [
+    `${name}=${options.clear ? "" : encodeURIComponent(value)}`
+  ];
+  parts.push(`Path=${options.path}`);
+  parts.push("HttpOnly");
+  parts.push("SameSite=Lax");
+  if (options.secure) parts.push("Secure");
+  if (options.clear) {
+    parts.push("Max-Age=0");
+    parts.push("Expires=Thu, 01 Jan 1970 00:00:00 GMT");
+  } else {
+    parts.push(`Max-Age=${options.maxAgeSeconds}`);
+  }
+  return parts.join("; ");
+}
+__name(serializeSetCookie, "serializeSetCookie");
+
+// src/server/auth/session-cookie.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+var EXP_GRACE_MS = 3e4;
+function base64urlEncode(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+__name(base64urlEncode, "base64urlEncode");
+function base64urlDecode(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+__name(base64urlDecode, "base64urlDecode");
+function hmac(secret, payload) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+__name(hmac, "hmac");
+function signSessionCookie(user, options) {
+  const issuedAt = options.now ?? Date.now();
+  const session = {
+    sub: user.id,
+    ...user.name !== void 0 ? {
+      name: user.name
+    } : {},
+    roles: user.roles ?? [],
+    iat: issuedAt,
+    exp: issuedAt + options.ttlMs
+  };
+  const encodedPayload = base64urlEncode(JSON.stringify(session));
+  const signature = hmac(options.secret, encodedPayload);
+  return `${encodedPayload}.${signature}`;
+}
+__name(signSessionCookie, "signSessionCookie");
+function isSessionPayload(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = {
+    ...value
+  };
+  if (typeof record.sub !== "string") return false;
+  if (record.name !== void 0 && typeof record.name !== "string") return false;
+  if (!Array.isArray(record.roles)) return false;
+  if (!record.roles.every((role) => typeof role === "string")) return false;
+  if (typeof record.iat !== "number" || !Number.isFinite(record.iat)) return false;
+  if (typeof record.exp !== "number" || !Number.isFinite(record.exp)) return false;
+  return true;
+}
+__name(isSessionPayload, "isSessionPayload");
+function verifySessionCookie(value, options) {
+  try {
+    const dot = value.indexOf(".");
+    if (dot <= 0 || dot === value.length - 1) return null;
+    const encodedPayload = value.slice(0, dot);
+    const providedSignature = value.slice(dot + 1);
+    const expectedSignature = hmac(options.secret, encodedPayload);
+    const provided = Buffer.from(providedSignature, "base64url");
+    const expected = Buffer.from(expectedSignature, "base64url");
+    if (provided.length !== expected.length) return null;
+    if (!timingSafeEqual(provided, expected)) return null;
+    const decoded = JSON.parse(base64urlDecode(encodedPayload));
+    if (!isSessionPayload(decoded)) return null;
+    const now = options.now ?? Date.now();
+    if (now > decoded.exp + EXP_GRACE_MS) return null;
+    const session = {
+      sub: decoded.sub,
+      ...decoded.name !== void 0 ? {
+        name: decoded.name
+      } : {},
+      roles: decoded.roles,
+      iat: decoded.iat,
+      exp: decoded.exp
+    };
+    return session;
+  } catch {
+    return null;
+  }
+}
+__name(verifySessionCookie, "verifySessionCookie");
+
+// src/server/auth/session-cookie-io.ts
+var SESSION_COOKIE_NAME = "durable_dashboard_session";
+var COOKIE_PATH = "/";
+function issueSessionCookie(user, context) {
+  const value = signSessionCookie(user, {
+    secret: context.auth.secret,
+    ttlMs: context.auth.ttlMs,
+    ...context.now !== void 0 ? {
+      now: context.now
+    } : {}
+  });
+  const cookie = serializeSetCookie(SESSION_COOKIE_NAME, value, {
+    path: COOKIE_PATH,
+    maxAgeSeconds: Math.floor(context.auth.ttlMs / 1e3),
+    secure: isHttpsRequest(context.request)
+  });
+  appendSetCookie(context.response, cookie);
+}
+__name(issueSessionCookie, "issueSessionCookie");
+function clearSessionCookie(context) {
+  const cookie = serializeSetCookie(SESSION_COOKIE_NAME, "", {
+    path: COOKIE_PATH,
+    maxAgeSeconds: 0,
+    secure: isHttpsRequest(context.request),
+    clear: true
+  });
+  appendSetCookie(context.response, cookie);
+}
+__name(clearSessionCookie, "clearSessionCookie");
+function readSessionFromRequest(auth, request) {
+  const cookieValue = parseCookieHeader(readCookieHeader(request))[SESSION_COOKIE_NAME];
+  if (cookieValue === void 0) return null;
+  return verifySessionCookie(cookieValue, {
+    secret: auth.secret
+  });
+}
+__name(readSessionFromRequest, "readSessionFromRequest");
+function maybeRenewSession(auth, session, request, response) {
+  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
+  });
+}
+__name(maybeRenewSession, "maybeRenewSession");
 
 // src/server/durable-ui.controller.ts
 import { existsSync, readFileSync } from "node:fs";
 import { basename, extname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Controller as Controller2, Get as Get2, Header as Header2, Inject as Inject2, NotFoundException as NotFoundException2, Param as Param2, StreamableFile } from "@nestjs/common";
+import { Controller as Controller2, Get as Get2, Header as Header2, Inject as Inject2, NotFoundException as NotFoundException2, Param as Param2, StreamableFile, UseFilters } from "@nestjs/common";
+
+// src/server/auth/login-redirect.exception.ts
+import { Catch, HttpException, HttpStatus } from "@nestjs/common";
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -539,6 +993,38 @@ function _ts_decorate3(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate3, "_ts_decorate");
+var DashboardLoginRedirectException = class extends HttpException {
+  static {
+    __name(this, "DashboardLoginRedirectException");
+  }
+  location;
+  constructor(location) {
+    super({
+      location
+    }, HttpStatus.FOUND), this.location = location;
+  }
+};
+var DashboardLoginRedirectFilter = class {
+  static {
+    __name(this, "DashboardLoginRedirectFilter");
+  }
+  catch(exception, host) {
+    const response = host.switchToHttp().getResponse();
+    redirectRaw(response, exception.location);
+  }
+};
+DashboardLoginRedirectFilter = _ts_decorate3([
+  Catch(DashboardLoginRedirectException)
+], DashboardLoginRedirectFilter);
+
+// src/server/durable-ui.controller.ts
+function _ts_decorate4(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate4, "_ts_decorate");
 function _ts_metadata3(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
@@ -601,7 +1087,7 @@ var DurableUiController = class {
     });
   }
 };
-_ts_decorate3([
+_ts_decorate4([
   Get2(),
   Header2("Content-Type", "text/html; charset=utf-8"),
   Header2("Cache-Control", "no-store, must-revalidate"),
@@ -609,7 +1095,7 @@ _ts_decorate3([
   _ts_metadata3("design:paramtypes", []),
   _ts_metadata3("design:returntype", String)
 ], DurableUiController.prototype, "index", null);
-_ts_decorate3([
+_ts_decorate4([
   Get2("assets/:file"),
   Header2("Cache-Control", "public, max-age=31536000, immutable"),
   _ts_param3(0, Param2("file")),
@@ -619,7 +1105,8 @@ _ts_decorate3([
   ]),
   _ts_metadata3("design:returntype", typeof StreamableFile === "undefined" ? Object : StreamableFile)
 ], DurableUiController.prototype, "asset", null);
-DurableUiController = _ts_decorate3([
+DurableUiController = _ts_decorate4([
+  UseFilters(DashboardLoginRedirectFilter),
   Controller2(),
   _ts_param3(0, Inject2(DASHBOARD_BASE_PATH)),
   _ts_param3(1, Inject2(DASHBOARD_API_PATH)),
@@ -630,47 +1117,326 @@ DurableUiController = _ts_decorate3([
   ])
 ], DurableUiController);
 
+// src/server/durable-auth.controller.ts
+function _ts_decorate5(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate5, "_ts_decorate");
+function _ts_metadata4(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata4, "_ts_metadata");
+function _ts_param4(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param4, "_ts_param");
+function isString(value) {
+  return typeof value === "string";
+}
+__name(isString, "isString");
+var DurableAuthController = class _DurableAuthController {
+  static {
+    __name(this, "DurableAuthController");
+  }
+  auth;
+  basePath;
+  logger = new Logger(_DurableAuthController.name);
+  /** Warn once so a throwing `login` hook doesn't spam logs on every failed attempt. */
+  warnedOnHookThrow = false;
+  constructor(auth, basePath) {
+    this.auth = auth;
+    this.basePath = basePath;
+  }
+  // The login page reads `returnTo`/`error` from `location.search` client-side (see
+  // `login-page.ts`), so this response never varies per request and needs no templating beyond
+  // the developer-controlled `basePath`.
+  loginPage() {
+    if (!this.auth) throw new NotFoundException3();
+    return renderLoginPage(this.basePath);
+  }
+  // Called by the login page's own fetch (JSON, not a classic form POST — see `login-page.ts` for
+  // why: it keeps the login page working with no host-configured body parser beyond the
+  // JSON one Nest wires in by default on both Express and Fastify). Uniform `401` on any failure
+  // (unknown user, wrong password, throwing hook) — no user-enumeration.
+  async login(body, request, response) {
+    const auth = this.requireAuth();
+    if (!isString(body?.username) || !isString(body?.password)) {
+      throw new BadRequestException("Body must include string `username` and `password`.");
+    }
+    const user = await this.runLoginHook(auth, body.username, body.password);
+    if (!user) throw new UnauthorizedException({
+      message: "Invalid username or password."
+    });
+    issueSessionCookie(user, {
+      auth,
+      request,
+      response
+    });
+    return {
+      redirectTo: sanitizeReturnTo(body.returnTo, this.basePath)
+    };
+  }
+  // Plain `GET` (not `POST`): logging out only ever destroys the CALLER's own session, so it's
+  // safe/idempotent from the caller's perspective — a simple `<a href>` (no JS, no CSRF token)
+  // works. Non-passthrough `@Res()`: this handler owns the response outright (clears the cookie,
+  // then redirects), so Nest must not also try to send a return value afterwards.
+  logout(request, response) {
+    clearSessionCookie({
+      request,
+      response
+    });
+    redirectRaw(response, `${this.basePath}/login`);
+  }
+  requireAuth() {
+    if (!this.auth) throw new NotFoundException3();
+    return this.auth;
+  }
+  /**
+  * Run the host's `login` hook defensively: a throw is treated as a denial (uniform failure) and
+  * warn-logged once, so a buggy hook never 500s the endpoint into a stack-trace leak nor floods
+  * the logs on repeated bad attempts.
+  */
+  async runLoginHook(auth, username, password) {
+    try {
+      return await auth.login(username, password) ?? null;
+    } catch (error) {
+      if (!this.warnedOnHookThrow) {
+        this.warnedOnHookThrow = true;
+        this.logger.warn(`dashboardAuth login hook threw; treating as denial. ${error instanceof Error ? error.message : String(error)}`);
+      }
+      return null;
+    }
+  }
+};
+_ts_decorate5([
+  Get3("login"),
+  Header3("Content-Type", "text/html; charset=utf-8"),
+  Header3("Cache-Control", "no-store, must-revalidate"),
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", []),
+  _ts_metadata4("design:returntype", String)
+], DurableAuthController.prototype, "loginPage", null);
+_ts_decorate5([
+  Post2("login"),
+  HttpCode(200),
+  _ts_param4(0, Body2()),
+  _ts_param4(1, Req()),
+  _ts_param4(2, Res({
+    passthrough: true
+  })),
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", [
+    typeof LoginBody === "undefined" ? Object : LoginBody,
+    Object,
+    Object
+  ]),
+  _ts_metadata4("design:returntype", Promise)
+], DurableAuthController.prototype, "login", null);
+_ts_decorate5([
+  Get3("logout"),
+  _ts_param4(0, Req()),
+  _ts_param4(1, Res()),
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", [
+    Object,
+    Object
+  ]),
+  _ts_metadata4("design:returntype", void 0)
+], DurableAuthController.prototype, "logout", null);
+DurableAuthController = _ts_decorate5([
+  Controller3(),
+  _ts_param4(0, Optional2()),
+  _ts_param4(0, Inject3(DASHBOARD_AUTH)),
+  _ts_param4(1, Inject3(DASHBOARD_BASE_PATH)),
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", [
+    Object,
+    String
+  ])
+], DurableAuthController);
+
 // src/server/durable-dashboard.module.ts
-function _ts_decorate4(decorators, target, key, desc) {
+import "reflect-metadata";
+import { Module } from "@nestjs/common";
+import { RouterModule } from "@nestjs/core";
+
+// src/server/durable-session.guard.ts
+import { Inject as Inject4, Injectable as Injectable2, UnauthorizedException as UnauthorizedException2 } from "@nestjs/common";
+function _ts_decorate6(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate4, "_ts_decorate");
+__name(_ts_decorate6, "_ts_decorate");
+function _ts_metadata5(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata5, "_ts_metadata");
+function _ts_param5(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param5, "_ts_param");
+var DurableUiSessionGuard = class {
+  static {
+    __name(this, "DurableUiSessionGuard");
+  }
+  auth;
+  basePath;
+  constructor(auth, basePath) {
+    this.auth = auth;
+    this.basePath = basePath;
+  }
+  canActivate(context) {
+    if (!this.auth) return true;
+    const http = context.switchToHttp();
+    const request = http.getRequest();
+    const session = readSessionFromRequest(this.auth, request);
+    if (!session) {
+      const returnTo = encodeURIComponent(originalRequestUrl(request));
+      throw new DashboardLoginRedirectException(`${this.basePath}/login?returnTo=${returnTo}`);
+    }
+    maybeRenewSession(this.auth, session, request, http.getResponse());
+    return true;
+  }
+};
+DurableUiSessionGuard = _ts_decorate6([
+  Injectable2(),
+  _ts_param5(0, Inject4(DASHBOARD_AUTH)),
+  _ts_param5(1, Inject4(DASHBOARD_BASE_PATH)),
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
+    Object,
+    String
+  ])
+], DurableUiSessionGuard);
+var DurableApiSessionGuard = class {
+  static {
+    __name(this, "DurableApiSessionGuard");
+  }
+  auth;
+  constructor(auth) {
+    this.auth = auth;
+  }
+  canActivate(context) {
+    if (!this.auth) return true;
+    const http = context.switchToHttp();
+    const request = http.getRequest();
+    const session = readSessionFromRequest(this.auth, request);
+    if (!session) throw new UnauthorizedException2();
+    maybeRenewSession(this.auth, session, request, http.getResponse());
+    return true;
+  }
+};
+DurableApiSessionGuard = _ts_decorate6([
+  Injectable2(),
+  _ts_param5(0, Inject4(DASHBOARD_AUTH)),
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
+    Object
+  ])
+], DurableApiSessionGuard);
+
+// src/server/durable-dashboard.module.ts
+function _ts_decorate7(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate7, "_ts_decorate");
+var GUARDS_METADATA = "__guards__";
 function normalize(path) {
   return `/${path.replace(/^\/+|\/+$/g, "")}`;
 }
 __name(normalize, "normalize");
-var DurableApiModule = class {
+function stampGuards(hostGuards, builtIn, controller) {
+  const merged = [
+    ...builtIn ? [
+      builtIn
+    ] : [],
+    ...hostGuards ?? []
+  ];
+  Reflect.defineMetadata(GUARDS_METADATA, merged, controller);
+}
+__name(stampGuards, "stampGuards");
+var DurableApiModule = class _DurableApiModule {
   static {
     __name(this, "DurableApiModule");
   }
+  static register(options) {
+    stampGuards(options.guards, options.authMayBeConfigured ? DurableApiSessionGuard : void 0, DurableApiController);
+    return {
+      module: _DurableApiModule,
+      imports: [
+        ...options.imports ?? []
+      ],
+      controllers: [
+        DurableApiController
+      ],
+      providers: [
+        DashboardService,
+        options.authProvider,
+        DurableApiSessionGuard,
+        ...options.guards ?? []
+      ],
+      exports: [
+        DashboardService
+      ]
+    };
+  }
 };
-DurableApiModule = _ts_decorate4([
-  Module({
-    controllers: [
-      DurableApiController
-    ],
-    providers: [
-      DashboardService
-    ],
-    exports: [
-      DashboardService
-    ]
-  })
+DurableApiModule = _ts_decorate7([
+  Module({})
 ], DurableApiModule);
 var DurableDashboardModule = class _DurableDashboardModule {
   static {
     __name(this, "DurableDashboardModule");
   }
   static forRoot(options = {}) {
+    const authProvider = {
+      provide: DASHBOARD_AUTH,
+      useValue: resolveDashboardAuth(options.dashboardAuth)
+    };
+    return _DurableDashboardModule.build(options, authProvider, options.dashboardAuth !== void 0);
+  }
+  static forRootAsync(options) {
+    const authProvider = {
+      provide: DASHBOARD_AUTH,
+      inject: options.inject ?? [],
+      useFactory: /* @__PURE__ */ __name(async (...deps) => resolveDashboardAuth(await options.useDashboardAuth(...deps)), "useFactory")
+    };
+    return _DurableDashboardModule.build(options, authProvider, true);
+  }
+  /** Shared wiring: static routing + the API module, with `dashboardAuth` supplied by `authProvider`. */
+  static build(options, authProvider, authMayBeConfigured) {
     const basePath = normalize(options.basePath ?? "/durable");
     const apiBasePath = normalize(options.apiBasePath ?? `${basePath}/api`);
+    stampGuards(options.guards, authMayBeConfigured ? DurableUiSessionGuard : void 0, DurableUiController);
     return {
       module: _DurableDashboardModule,
       imports: [
-        DurableApiModule,
+        ...options.imports ?? [],
+        // Guards + host imports must reach the API controller's HOST module — enhancers resolve
+        // from their controller's own module, never from a parent (see DurableApiModule.register).
+        // Spread-only-when-set: exactOptionalPropertyTypes rejects an explicit `undefined`.
+        DurableApiModule.register({
+          ...options.imports ? {
+            imports: options.imports
+          } : {},
+          ...options.guards ? {
+            guards: options.guards
+          } : {},
+          authProvider,
+          authMayBeConfigured
+        }),
         RouterModule.register([
           {
             path: basePath,
@@ -683,7 +1449,13 @@ var DurableDashboardModule = class _DurableDashboardModule {
         ])
       ],
       controllers: [
-        DurableUiController
+        DurableUiController,
+        // The auth controller (login page + logout) only exists when dashboardAuth might be
+        // configured — mounting it unconditionally would add a new `/login` route even for hosts
+        // that never set `dashboardAuth`, breaking "absent -> today's behavior byte-for-byte".
+        ...authMayBeConfigured ? [
+          DurableAuthController
+        ] : []
       ],
       providers: [
         {
@@ -693,7 +1465,12 @@ var DurableDashboardModule = class _DurableDashboardModule {
         {
           provide: DASHBOARD_API_PATH,
           useValue: apiBasePath
-        }
+        },
+        authProvider,
+        DurableUiSessionGuard,
+        // DurableUiController (and DurableAuthController, when present) are hosted HERE, so their
+        // guards DI-instantiate from this module.
+        ...options.guards ?? []
       ],
       // Re-export the API module so its DashboardService reaches importers (e.g. flip's own controllers).
       exports: [
@@ -702,7 +1479,7 @@ var DurableDashboardModule = class _DurableDashboardModule {
     };
   }
 };
-DurableDashboardModule = _ts_decorate4([
+DurableDashboardModule = _ts_decorate7([
   Module({})
 ], DurableDashboardModule);
 export {
@@ -711,7 +1488,10 @@ export {
   DashboardService,
   DurableApiController,
   DurableApiModule,
+  DurableApiSessionGuard,
+  DurableAuthController,
   DurableDashboardModule,
-  DurableUiController
+  DurableUiController,
+  DurableUiSessionGuard
 };
 //# sourceMappingURL=index.js.map