hazo_auth 10.4.10 → 10.4.13

package/README.md

@@ -2,6 +2,10 @@
 
 A reusable authentication UI component package powered by Next.js, TailwindCSS, and shadcn. It integrates `hazo_config` for configuration management and `hazo_connect` for data access, enabling future components to stay aligned with platform conventions.
 
+### What's New in v10.4.13
+
+- **`validate_session_secret_config()`** exported from `hazo_auth/server-lib` — hard startup validator that throws `HazoConfigError` (code `HAZO_AUTH_CONFIG`) when `JWT_SECRET` is unset or shorter than 32 chars. Call it from a Next.js `instrumentation.ts` `register()` hook to fail boot loudly instead of hitting the silent split-brain a bad/missing secret otherwise causes (edge proxy bounces to `/login` while server-side auth falls back to unsigned cookies and still considers the user authenticated).
+
 ### What's New in v10.4.5
 
 - **Pre-fill login credentials** — `LoginPage`, `LoginClientWrapper`, and `LoginLayout` now accept a `default_values` / `defaultValues` prop (`{ email?: string; password?: string }`) to pre-populate the login form. Useful for demo and test environments (gate with `process.env.DEMO_EMAIL` etc.).

package/SETUP_CHECKLIST.md

@@ -424,9 +424,10 @@ from_name = Your App Name
 **Checklist:**
 - [ ] `.env.local` file created
 - [ ] `HAZO_AUTH_COOKIE_PREFIX` set (REQUIRED - must match config file)
-- [ ] `JWT_SECRET` set (required for JWT session tokens)
+- [ ] `JWT_SECRET` set (required for JWT session tokens, >= 32 chars)
 - [ ] `ZEPTOMAIL_API_KEY` set (or email will not work)
 - [ ] `from_email` configured in `hazo_notify_config.ini`
+- [ ] Call `validate_session_secret_config()` (from `hazo_auth/server-lib`) in your `instrumentation.ts` `register()` hook — hard-fails boot with a descriptive banner if `JWT_SECRET` is missing or too short, instead of the silent split-brain (logged-in on `/login` but bounced on every protected route) that a bad secret otherwise causes.
 
 ---
 

package/cli-src/cli/generate.ts

@@ -64,6 +64,10 @@ const ROUTES: RouteDefinition[] = [
   { name: "nextauth_post", path: "api/auth/[...nextauth]", method: "POST", export_name: "nextauthPOST" },
   { name: "oauth_google_callback", path: "api/hazo_auth/oauth/google/callback", method: "GET", export_name: "oauthGoogleCallbackGET" },
   { name: "set_password", path: "api/hazo_auth/set_password", method: "POST", export_name: "setPasswordPOST" },
+  // Static assets (default auth-page images served from the package's dist/assets/images).
+  // Without this route the default image_src (/api/hazo_auth/assets/login_default.jpg) 404s
+  // and login/register/etc. render with an empty image panel.
+  { name: "assets", path: "api/hazo_auth/assets/[name]", method: "GET", export_name: "assetGET" },
 ];
 
 const PAGES: PageDefinition[] = [

package/cli-src/cli/validate.ts

@@ -310,6 +310,43 @@ function check_env_vars(): CheckResult[] {
 const GOOGLE_NEXTAUTH_CALLBACK_PATH = "/api/auth/callback/google";
 const FACEBOOK_NEXTAUTH_CALLBACK_PATH = "/api/auth/callback/facebook";
 
+/**
+ * The edge proxy (Edge Runtime, no filesystem) reads the cookie prefix from the
+ * HAZO_AUTH_COOKIE_PREFIX env var, while the server reads cookie_prefix from the
+ * ini. If they differ — or the env var is unset — the edge gate can't find the
+ * session cookie and silently bounces authenticated users back to /login. This
+ * check catches that split before it wastes an afternoon.
+ */
+function check_cookie_prefix(project_root: string): CheckResult[] {
+  const hazo_config = read_ini_file(path.join(project_root, "config", "hazo_auth_config.ini"));
+  const ini_prefix = (hazo_config?.["hazo_auth__cookies"]?.["cookie_prefix"] ?? "").trim();
+  const env_prefix = (process.env.HAZO_AUTH_COOKIE_PREFIX ?? "").trim();
+
+  if (!ini_prefix) {
+    // Already reported as a fail by check_config_values; nothing to compare.
+    return [];
+  }
+  if (!env_prefix) {
+    return [
+      {
+        name: "Cookie prefix (env ↔ ini)",
+        status: "fail",
+        message: `HAZO_AUTH_COOKIE_PREFIX env var not set. The edge proxy throws without it and bounces authenticated users to /login. Set HAZO_AUTH_COOKIE_PREFIX=${ini_prefix} to match cookie_prefix in hazo_auth_config.ini.`,
+      },
+    ];
+  }
+  if (env_prefix !== ini_prefix) {
+    return [
+      {
+        name: "Cookie prefix (env ↔ ini)",
+        status: "fail",
+        message: `Mismatch: HAZO_AUTH_COOKIE_PREFIX="${env_prefix}" but ini cookie_prefix="${ini_prefix}". They must be identical or the edge gate can't find the session cookie. Make them equal.`,
+      },
+    ];
+  }
+  return [{ name: "Cookie prefix (env ↔ ini)", status: "pass", message: `"${env_prefix}" (matches)` }];
+}
+
 function read_oauth_origin(): { origin: string; resolved: boolean } {
   const nextauth_url = process.env.NEXTAUTH_URL;
   if (nextauth_url && nextauth_url.trim().length > 0) {
@@ -850,6 +887,14 @@ export function run_validation(): ValidationSummary {
   all_results.push(...env_results);
   console.log();
 
+  const cookie_prefix_results = check_cookie_prefix(project_root);
+  if (cookie_prefix_results.length > 0) {
+    console.log("\x1b[1m🍪 Cookie Prefix\x1b[0m");
+    cookie_prefix_results.forEach(print_result);
+    all_results.push(...cookie_prefix_results);
+    console.log();
+  }
+
   console.log("\x1b[1m🔑 OAuth Providers\x1b[0m");
   const oauth_results = check_oauth(project_root);
   oauth_results.forEach(print_result);

package/cli-src/lib/oauth_preflight.server.ts

@@ -3,6 +3,7 @@
 import "server-only";
 
 import { get_oauth_config } from "./oauth_config.server.js";
+import { get_cookies_config } from "./cookies_config.server.js";
 import { googleRedirectUri, facebookRedirectUri } from "./oauth_routes.js";
 import { create_app_logger } from "./app_logger.js";
 
@@ -49,6 +50,30 @@ export function getOAuthPreflightReport(): OAuthPreflightReport {
   const oauth = get_oauth_config();
   const redirectUris: OAuthPreflightReport["redirectUris"] = [];
 
+  // Cookie prefix: env (read by the edge proxy) must match the ini (read by the
+  // server). A mismatch — or an unset env var — makes the edge gate throw and
+  // silently bounce authenticated users to /login.
+  try {
+    const ini_prefix = (get_cookies_config().cookie_prefix ?? "").trim();
+    const env_prefix = (process.env.HAZO_AUTH_COOKIE_PREFIX ?? "").trim();
+    if (ini_prefix && !env_prefix) {
+      checks.push({
+        name: "Cookie prefix",
+        status: "fail",
+        message: `HAZO_AUTH_COOKIE_PREFIX env var not set. The edge proxy throws without it and bounces authenticated users to /login. Set HAZO_AUTH_COOKIE_PREFIX=${ini_prefix} (matching cookie_prefix in hazo_auth_config.ini).`,
+      });
+    } else if (ini_prefix && env_prefix && env_prefix !== ini_prefix) {
+      checks.push({
+        name: "Cookie prefix",
+        status: "fail",
+        message: `Mismatch: HAZO_AUTH_COOKIE_PREFIX="${env_prefix}" vs ini cookie_prefix="${ini_prefix}". They must be identical or the edge gate can't find the session cookie.`,
+      });
+    }
+  } catch {
+    // get_cookies_config throws when cookie_prefix is absent from the ini; that
+    // missing-config case is reported elsewhere (validate CLI / server boot).
+  }
+
   // NEXTAUTH_URL — the source of the redirect URI.
   if (resolved) {
     checks.push({ name: "NEXTAUTH_URL", status: "pass", message: origin });
@@ -152,10 +177,10 @@ export function logOAuthPreflight(): OAuthPreflightReport | null {
   _logged_once = true;
 
   const report = getOAuthPreflightReport();
-  if (report.redirectUris.length === 0) return report; // No OAuth providers enabled.
-
   const logger = create_app_logger();
 
+  // Always surface failing/warning checks (e.g. cookie-prefix mismatch), even
+  // when no OAuth provider is enabled and there are no redirect URIs to print.
   for (const check of report.checks) {
     if (check.status === "fail") {
       logger.error("oauth_preflight_check_failed", { check: check.name, detail: check.message });
@@ -164,6 +189,8 @@ export function logOAuthPreflight(): OAuthPreflightReport | null {
     }
   }
 
+  if (report.redirectUris.length === 0) return report; // No OAuth providers — nothing to register.
+
   // Highlighted, copy-pasteable block — the single thing that prevents
   // redirect_uri_mismatch. console (not logger) so it renders verbatim.
   const lines: string[] = [

package/cli-src/lib/validate_session_secret.server.ts

@@ -0,0 +1,83 @@
+// file_description: startup validator for the JWT session signing secret — hard-fails boot with a descriptive banner if JWT_SECRET is missing or too short
+// section: server-only-guard
+import "server-only";
+
+// section: imports
+import { HazoConfigError } from "hazo_core";
+
+// section: constants
+/**
+ * Minimum acceptable length for JWT_SECRET. jose/HS256 accepts shorter keys,
+ * but anything under 32 chars is trivially brute-forceable for a session
+ * signing secret. Matches the threshold the validate CLI enforces.
+ */
+const MIN_JWT_SECRET_LEN = 32;
+
+// section: validate
+/**
+ * Validates the JWT session signing secret at startup.
+ *
+ * Throws HazoConfigError with a descriptive banner if JWT_SECRET is unset or
+ * shorter than 32 chars. Call this in your instrumentation `register()` hook to
+ * hard-fail boot instead of the silent failure mode it otherwise causes:
+ *
+ *   - The edge proxy validator (`validate_session_cookie`) returns
+ *     `{ valid: false }` when JWT_SECRET is missing → logged-in users get
+ *     bounced to /login.
+ *   - The server resolver (`hazo_get_auth`) falls back to unsigned simple
+ *     cookies and considers the same user authenticated.
+ *
+ * The two disagree, so the app looks "logged in" on the login page yet bounces
+ * on every protected route. Failing at boot turns that silent split-brain into
+ * an obvious, actionable error.
+ */
+export function validate_session_secret_config(): void {
+  const jwt_secret = process.env.JWT_SECRET;
+
+  if (!jwt_secret || jwt_secret.trim().length === 0) {
+    console.error("=".repeat(60));
+    console.error("FATAL: JWT_SECRET is not set");
+    console.error("=".repeat(60));
+    console.error("hazo_auth signs session cookies with JWT_SECRET. Without it:");
+    console.error("  - the edge proxy rejects every session and bounces");
+    console.error("    logged-in users to /login;");
+    console.error("  - server-side auth silently falls back to unsigned");
+    console.error("    cookies, so the app looks logged in but every");
+    console.error("    protected route bounces.");
+    console.error("");
+    console.error("Fix — add to .env.local:");
+    console.error("  JWT_SECRET=<random string, at least 32 chars>");
+    console.error("Generate one:");
+    console.error("  node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
+    console.error("=".repeat(60));
+
+    throw new HazoConfigError({
+      code: "HAZO_AUTH_CONFIG",
+      pkg: "hazo_auth",
+      message:
+        "JWT_SECRET environment variable is required to sign session cookies. " +
+        "Without it the edge proxy bounces authenticated users to /login while " +
+        "server-side auth falls back to unsigned cookies. Set JWT_SECRET (>= 32 chars) in .env.local.",
+    });
+  }
+
+  if (jwt_secret.trim().length < MIN_JWT_SECRET_LEN) {
+    console.error("=".repeat(60));
+    console.error("FATAL: JWT_SECRET is too short");
+    console.error("=".repeat(60));
+    console.error(
+      `JWT_SECRET is ${jwt_secret.trim().length} chars; at least ${MIN_JWT_SECRET_LEN} are required.`,
+    );
+    console.error("Generate a strong one:");
+    console.error("  node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
+    console.error("=".repeat(60));
+
+    throw new HazoConfigError({
+      code: "HAZO_AUTH_CONFIG",
+      pkg: "hazo_auth",
+      message:
+        `JWT_SECRET is too short (${jwt_secret.trim().length} chars). ` +
+        `Use at least ${MIN_JWT_SECRET_LEN} characters for the session signing secret.`,
+    });
+  }
+}

package/dist/cli/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAiMF,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI,CA8DnE"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAqMF,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI,CA8DnE"}

package/dist/cli/generate.js

@@ -41,6 +41,10 @@ const ROUTES = [
     { name: "nextauth_post", path: "api/auth/[...nextauth]", method: "POST", export_name: "nextauthPOST" },
     { name: "oauth_google_callback", path: "api/hazo_auth/oauth/google/callback", method: "GET", export_name: "oauthGoogleCallbackGET" },
     { name: "set_password", path: "api/hazo_auth/set_password", method: "POST", export_name: "setPasswordPOST" },
+    // Static assets (default auth-page images served from the package's dist/assets/images).
+    // Without this route the default image_src (/api/hazo_auth/assets/login_default.jpg) 404s
+    // and login/register/etc. render with an empty image panel.
+    { name: "assets", path: "api/hazo_auth/assets/[name]", method: "GET", export_name: "assetGET" },
 ];
 const PAGES = [
     { name: "login", path: "hazo_auth/login", component_name: "LoginPage", import_path: "hazo_auth/pages/login" },

package/dist/cli/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/cli/validate.ts"],"names":[],"mappings":"AAOA,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB,CAAC;AAsyBF,wBAAgB,cAAc,IAAI,iBAAiB,CAsFlD"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/cli/validate.ts"],"names":[],"mappings":"AAOA,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB,CAAC;AA20BF,wBAAgB,cAAc,IAAI,iBAAiB,CA8FlD"}

package/dist/cli/validate.js

@@ -272,6 +272,42 @@ function check_env_vars() {
 // compiles as an isolated tree and must not import the server-only lib.
 const GOOGLE_NEXTAUTH_CALLBACK_PATH = "/api/auth/callback/google";
 const FACEBOOK_NEXTAUTH_CALLBACK_PATH = "/api/auth/callback/facebook";
+/**
+ * The edge proxy (Edge Runtime, no filesystem) reads the cookie prefix from the
+ * HAZO_AUTH_COOKIE_PREFIX env var, while the server reads cookie_prefix from the
+ * ini. If they differ — or the env var is unset — the edge gate can't find the
+ * session cookie and silently bounces authenticated users back to /login. This
+ * check catches that split before it wastes an afternoon.
+ */
+function check_cookie_prefix(project_root) {
+    var _a, _b, _c;
+    const hazo_config = read_ini_file(path.join(project_root, "config", "hazo_auth_config.ini"));
+    const ini_prefix = ((_b = (_a = hazo_config === null || hazo_config === void 0 ? void 0 : hazo_config["hazo_auth__cookies"]) === null || _a === void 0 ? void 0 : _a["cookie_prefix"]) !== null && _b !== void 0 ? _b : "").trim();
+    const env_prefix = ((_c = process.env.HAZO_AUTH_COOKIE_PREFIX) !== null && _c !== void 0 ? _c : "").trim();
+    if (!ini_prefix) {
+        // Already reported as a fail by check_config_values; nothing to compare.
+        return [];
+    }
+    if (!env_prefix) {
+        return [
+            {
+                name: "Cookie prefix (env ↔ ini)",
+                status: "fail",
+                message: `HAZO_AUTH_COOKIE_PREFIX env var not set. The edge proxy throws without it and bounces authenticated users to /login. Set HAZO_AUTH_COOKIE_PREFIX=${ini_prefix} to match cookie_prefix in hazo_auth_config.ini.`,
+            },
+        ];
+    }
+    if (env_prefix !== ini_prefix) {
+        return [
+            {
+                name: "Cookie prefix (env ↔ ini)",
+                status: "fail",
+                message: `Mismatch: HAZO_AUTH_COOKIE_PREFIX="${env_prefix}" but ini cookie_prefix="${ini_prefix}". They must be identical or the edge gate can't find the session cookie. Make them equal.`,
+            },
+        ];
+    }
+    return [{ name: "Cookie prefix (env ↔ ini)", status: "pass", message: `"${env_prefix}" (matches)` }];
+}
 function read_oauth_origin() {
     var _a;
     const nextauth_url = process.env.NEXTAUTH_URL;
@@ -781,6 +817,13 @@ export function run_validation() {
     env_results.forEach(print_result);
     all_results.push(...env_results);
     console.log();
+    const cookie_prefix_results = check_cookie_prefix(project_root);
+    if (cookie_prefix_results.length > 0) {
+        console.log("\x1b[1m🍪 Cookie Prefix\x1b[0m");
+        cookie_prefix_results.forEach(print_result);
+        all_results.push(...cookie_prefix_results);
+        console.log();
+    }
     console.log("\x1b[1m🔑 OAuth Providers\x1b[0m");
     const oauth_results = check_oauth(project_root);
     oauth_results.forEach(print_result);

package/dist/lib/oauth_preflight.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth_preflight.server.d.ts","sourceRoot":"","sources":["../../src/lib/oauth_preflight.server.ts"],"names":[],"mappings":"AAEA,OAAO,aAAa,CAAC;AAOrB,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,cAAc,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,YAAY,EAAE;QAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjE,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B,CAAC;AAeF;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CA2F9D;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,oBAAoB,GAAG,IAAI,CAsC/D"}
+{"version":3,"file":"oauth_preflight.server.d.ts","sourceRoot":"","sources":["../../src/lib/oauth_preflight.server.ts"],"names":[],"mappings":"AAEA,OAAO,aAAa,CAAC;AAQrB,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,cAAc,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,YAAY,EAAE;QAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjE,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B,CAAC;AAeF;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAmH9D;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,oBAAoB,GAAG,IAAI,CAwC/D"}

package/dist/lib/oauth_preflight.server.js

@@ -2,6 +2,7 @@
 // redirect URIs to register, killing the recurring `redirect_uri_mismatch` for new apps.
 import "server-only";
 import { get_oauth_config } from "./oauth_config.server.js";
+import { get_cookies_config } from "./cookies_config.server.js";
 import { googleRedirectUri, facebookRedirectUri } from "./oauth_routes.js";
 import { create_app_logger } from "./app_logger.js";
 // section: helpers
@@ -22,10 +23,36 @@ function resolve_origin() {
  * no DB or network access.
  */
 export function getOAuthPreflightReport() {
+    var _a, _b;
     const checks = [];
     const { origin, resolved } = resolve_origin();
     const oauth = get_oauth_config();
     const redirectUris = [];
+    // Cookie prefix: env (read by the edge proxy) must match the ini (read by the
+    // server). A mismatch — or an unset env var — makes the edge gate throw and
+    // silently bounce authenticated users to /login.
+    try {
+        const ini_prefix = ((_a = get_cookies_config().cookie_prefix) !== null && _a !== void 0 ? _a : "").trim();
+        const env_prefix = ((_b = process.env.HAZO_AUTH_COOKIE_PREFIX) !== null && _b !== void 0 ? _b : "").trim();
+        if (ini_prefix && !env_prefix) {
+            checks.push({
+                name: "Cookie prefix",
+                status: "fail",
+                message: `HAZO_AUTH_COOKIE_PREFIX env var not set. The edge proxy throws without it and bounces authenticated users to /login. Set HAZO_AUTH_COOKIE_PREFIX=${ini_prefix} (matching cookie_prefix in hazo_auth_config.ini).`,
+            });
+        }
+        else if (ini_prefix && env_prefix && env_prefix !== ini_prefix) {
+            checks.push({
+                name: "Cookie prefix",
+                status: "fail",
+                message: `Mismatch: HAZO_AUTH_COOKIE_PREFIX="${env_prefix}" vs ini cookie_prefix="${ini_prefix}". They must be identical or the edge gate can't find the session cookie.`,
+            });
+        }
+    }
+    catch (_c) {
+        // get_cookies_config throws when cookie_prefix is absent from the ini; that
+        // missing-config case is reported elsewhere (validate CLI / server boot).
+    }
     // NEXTAUTH_URL — the source of the redirect URI.
     if (resolved) {
         checks.push({ name: "NEXTAUTH_URL", status: "pass", message: origin });
@@ -45,7 +72,7 @@ export function getOAuthPreflightReport() {
             const u = new URL(origin);
             url_port = u.port || (u.protocol === "https:" ? "443" : "80");
         }
-        catch (_a) {
+        catch (_d) {
             url_port = null;
         }
         if (url_port && url_port !== declared_port) {
@@ -128,9 +155,9 @@ export function logOAuthPreflight() {
         return null;
     _logged_once = true;
     const report = getOAuthPreflightReport();
-    if (report.redirectUris.length === 0)
-        return report; // No OAuth providers enabled.
     const logger = create_app_logger();
+    // Always surface failing/warning checks (e.g. cookie-prefix mismatch), even
+    // when no OAuth provider is enabled and there are no redirect URIs to print.
     for (const check of report.checks) {
         if (check.status === "fail") {
             logger.error("oauth_preflight_check_failed", { check: check.name, detail: check.message });
@@ -139,6 +166,8 @@ export function logOAuthPreflight() {
             logger.warn("oauth_preflight_check_warning", { check: check.name, detail: check.message });
         }
     }
+    if (report.redirectUris.length === 0)
+        return report; // No OAuth providers — nothing to register.
     // Highlighted, copy-pasteable block — the single thing that prevents
     // redirect_uri_mismatch. console (not logger) so it renders verbatim.
     const lines = [

package/dist/lib/validate_session_secret.server.d.ts

@@ -0,0 +1,20 @@
+import "server-only";
+/**
+ * Validates the JWT session signing secret at startup.
+ *
+ * Throws HazoConfigError with a descriptive banner if JWT_SECRET is unset or
+ * shorter than 32 chars. Call this in your instrumentation `register()` hook to
+ * hard-fail boot instead of the silent failure mode it otherwise causes:
+ *
+ *   - The edge proxy validator (`validate_session_cookie`) returns
+ *     `{ valid: false }` when JWT_SECRET is missing → logged-in users get
+ *     bounced to /login.
+ *   - The server resolver (`hazo_get_auth`) falls back to unsigned simple
+ *     cookies and considers the same user authenticated.
+ *
+ * The two disagree, so the app looks "logged in" on the login page yet bounces
+ * on every protected route. Failing at boot turns that silent split-brain into
+ * an obvious, actionable error.
+ */
+export declare function validate_session_secret_config(): void;
+//# sourceMappingURL=validate_session_secret.server.d.ts.map

package/dist/lib/validate_session_secret.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate_session_secret.server.d.ts","sourceRoot":"","sources":["../../src/lib/validate_session_secret.server.ts"],"names":[],"mappings":"AAEA,OAAO,aAAa,CAAC;AAcrB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAiDrD"}

package/dist/lib/validate_session_secret.server.js

@@ -0,0 +1,72 @@
+// file_description: startup validator for the JWT session signing secret — hard-fails boot with a descriptive banner if JWT_SECRET is missing or too short
+// section: server-only-guard
+import "server-only";
+// section: imports
+import { HazoConfigError } from "hazo_core";
+// section: constants
+/**
+ * Minimum acceptable length for JWT_SECRET. jose/HS256 accepts shorter keys,
+ * but anything under 32 chars is trivially brute-forceable for a session
+ * signing secret. Matches the threshold the validate CLI enforces.
+ */
+const MIN_JWT_SECRET_LEN = 32;
+// section: validate
+/**
+ * Validates the JWT session signing secret at startup.
+ *
+ * Throws HazoConfigError with a descriptive banner if JWT_SECRET is unset or
+ * shorter than 32 chars. Call this in your instrumentation `register()` hook to
+ * hard-fail boot instead of the silent failure mode it otherwise causes:
+ *
+ *   - The edge proxy validator (`validate_session_cookie`) returns
+ *     `{ valid: false }` when JWT_SECRET is missing → logged-in users get
+ *     bounced to /login.
+ *   - The server resolver (`hazo_get_auth`) falls back to unsigned simple
+ *     cookies and considers the same user authenticated.
+ *
+ * The two disagree, so the app looks "logged in" on the login page yet bounces
+ * on every protected route. Failing at boot turns that silent split-brain into
+ * an obvious, actionable error.
+ */
+export function validate_session_secret_config() {
+    const jwt_secret = process.env.JWT_SECRET;
+    if (!jwt_secret || jwt_secret.trim().length === 0) {
+        console.error("=".repeat(60));
+        console.error("FATAL: JWT_SECRET is not set");
+        console.error("=".repeat(60));
+        console.error("hazo_auth signs session cookies with JWT_SECRET. Without it:");
+        console.error("  - the edge proxy rejects every session and bounces");
+        console.error("    logged-in users to /login;");
+        console.error("  - server-side auth silently falls back to unsigned");
+        console.error("    cookies, so the app looks logged in but every");
+        console.error("    protected route bounces.");
+        console.error("");
+        console.error("Fix — add to .env.local:");
+        console.error("  JWT_SECRET=<random string, at least 32 chars>");
+        console.error("Generate one:");
+        console.error("  node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
+        console.error("=".repeat(60));
+        throw new HazoConfigError({
+            code: "HAZO_AUTH_CONFIG",
+            pkg: "hazo_auth",
+            message: "JWT_SECRET environment variable is required to sign session cookies. " +
+                "Without it the edge proxy bounces authenticated users to /login while " +
+                "server-side auth falls back to unsigned cookies. Set JWT_SECRET (>= 32 chars) in .env.local.",
+        });
+    }
+    if (jwt_secret.trim().length < MIN_JWT_SECRET_LEN) {
+        console.error("=".repeat(60));
+        console.error("FATAL: JWT_SECRET is too short");
+        console.error("=".repeat(60));
+        console.error(`JWT_SECRET is ${jwt_secret.trim().length} chars; at least ${MIN_JWT_SECRET_LEN} are required.`);
+        console.error("Generate a strong one:");
+        console.error("  node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
+        console.error("=".repeat(60));
+        throw new HazoConfigError({
+            code: "HAZO_AUTH_CONFIG",
+            pkg: "hazo_auth",
+            message: `JWT_SECRET is too short (${jwt_secret.trim().length} chars). ` +
+                `Use at least ${MIN_JWT_SECRET_LEN} characters for the session signing secret.`,
+        });
+    }
+}

package/dist/server/routes/user_management_users.d.ts

@@ -26,7 +26,7 @@ export declare function GET(request: NextRequest): Promise<NextResponse<{
         profile_source: {} | null;
         user_type: string | null;
         app_user_data: Record<string, unknown> | null;
-        legal_acceptance_status: "current" | "none" | "outdated";
+        legal_acceptance_status: "current" | "outdated" | "none";
     }[];
 }>>;
 /**

package/dist/server-lib.d.ts

@@ -26,6 +26,7 @@ export { get_branding_config, is_branding_enabled, is_allowed_logo_format, get_m
 export type { FirmBrandingConfig } from "./lib/branding_config.server";
 export { create_sqlite_hazo_connect } from "./lib/hazo_connect_setup.js";
 export { validate_hazo_connect_config } from "./lib/validate_hazo_connect_config.server.js";
+export { validate_session_secret_config } from "./lib/validate_session_secret.server.js";
 export { get_hazo_connect_instance, set_hazo_connect_instance, reset_hazo_connect_instance, } from "./lib/hazo_connect_instance.server.js";
 export { create_app_logger } from "./lib/app_logger.js";
 export { sanitize_error_for_user } from "./lib/utils/error_sanitizer.js";

package/dist/server-lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-lib.d.ts","sourceRoot":"","sources":["../src/server-lib.ts"],"names":[],"mappings":"AAYA,OAAO,aAAa,CAAC;AAGrB,cAAc,kBAAkB,CAAC;AAGjC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAGrF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,gCAAgC,EAAE,MAAM,2CAA2C,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2CAA2C,CAAC;AACzF,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,YAAY,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,cAAc,+BAA+B,CAAC;AAG9C,OAAO,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACvF,YAAY,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAGpF,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,YAAY,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAG/E,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAK7E,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,GAChB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"server-lib.d.ts","sourceRoot":"","sources":["../src/server-lib.ts"],"names":[],"mappings":"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"}

package/dist/server-lib.js

@@ -40,6 +40,7 @@ export { get_branding_config, is_branding_enabled, is_allowed_logo_format, get_m
 // section: hazo_connect_exports
 export { create_sqlite_hazo_connect } from "./lib/hazo_connect_setup.js";
 export { validate_hazo_connect_config } from "./lib/validate_hazo_connect_config.server.js";
+export { validate_session_secret_config } from "./lib/validate_session_secret.server.js";
 export { get_hazo_connect_instance, set_hazo_connect_instance, reset_hazo_connect_instance, } from "./lib/hazo_connect_instance.server.js";
 // section: logger_exports
 export { create_app_logger } from "./lib/app_logger.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "10.4.10",
+  "version": "10.4.13",
   "description": "Zero-config authentication UI components for Next.js with RBAC, OAuth, scope-based multi-tenancy, and invitations",
   "keywords": [
     "authentication",
@@ -408,7 +408,7 @@
     "hazo_core": "^1.2.1",
     "hazo_logs": "^2.1.1",
     "hazo_notify": "^6.1.4",
-    "hazo_ui": "^4.6.2",
+    "hazo_ui": "^4.7.0",
     "input-otp": "^1.4.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.0.0",