hazo_auth 10.4.9 → 10.4.10

package/cli-src/cli/validate.ts

@@ -305,6 +305,113 @@ function check_env_vars(): CheckResult[] {
   return results;
 }
 
+// Canonical values live in src/lib/oauth_routes.ts; inlined here because the CLI
+// 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";
+
+function read_oauth_origin(): { origin: string; resolved: boolean } {
+  const nextauth_url = process.env.NEXTAUTH_URL;
+  if (nextauth_url && nextauth_url.trim().length > 0) {
+    return { origin: nextauth_url.trim().replace(/\/+$/, ""), resolved: true };
+  }
+  const port = process.env.PORT ?? "3000";
+  return { origin: `http://localhost:${port}`, resolved: false };
+}
+
+function check_oauth(project_root: string): CheckResult[] {
+  const results: CheckResult[] = [];
+
+  const hazo_config_path = path.join(project_root, "config", "hazo_auth_config.ini");
+  const hazo_config = read_ini_file(hazo_config_path);
+  const oauth_section = hazo_config?.["hazo_auth__oauth"] ?? {};
+  const enable_google = (oauth_section["enable_google"] ?? "").toLowerCase() === "true";
+  const enable_facebook = (oauth_section["enable_facebook_oauth"] ?? "").toLowerCase() === "true";
+
+  if (!enable_google && !enable_facebook) {
+    results.push({
+      name: "OAuth providers",
+      status: "pass",
+      message: "No OAuth providers enabled (email/password only)",
+    });
+    return results;
+  }
+
+  const { origin, resolved } = read_oauth_origin();
+
+  // NEXTAUTH_URL — source of the redirect URI.
+  results.push(
+    resolved
+      ? { name: "NEXTAUTH_URL", status: "pass", message: origin }
+      : {
+          name: "NEXTAUTH_URL",
+          status: "fail",
+          message: `Not set. The redirect URI below is a guess from PORT. Set NEXTAUTH_URL=${origin}`,
+        }
+  );
+
+  // NEXTAUTH_SECRET — required for OAuth state/session signing.
+  const secret = process.env.NEXTAUTH_SECRET;
+  if (!secret || secret.length === 0) {
+    results.push({
+      name: "NEXTAUTH_SECRET",
+      status: "fail",
+      message: "Not set. Generate: openssl rand -base64 32",
+    });
+  } else if (secret.length < 32) {
+    results.push({
+      name: "NEXTAUTH_SECRET",
+      status: "warn",
+      message: `Only ${secret.length} chars; use at least 32. Generate: openssl rand -base64 32`,
+    });
+  } else {
+    results.push({ name: "NEXTAUTH_SECRET", status: "pass", message: "Set" });
+  }
+
+  if (enable_google) {
+    const id = process.env.HAZO_AUTH_GOOGLE_CLIENT_ID;
+    const cs = process.env.HAZO_AUTH_GOOGLE_CLIENT_SECRET;
+    const missing = [
+      !id ? "HAZO_AUTH_GOOGLE_CLIENT_ID" : null,
+      !cs ? "HAZO_AUTH_GOOGLE_CLIENT_SECRET" : null,
+    ].filter(Boolean);
+    results.push(
+      missing.length === 0
+        ? { name: "Google OAuth credentials", status: "pass", message: "Set" }
+        : {
+            name: "Google OAuth credentials",
+            status: "fail",
+            message: `enable_google=true but missing: ${missing.join(", ")}`,
+          }
+    );
+  }
+
+  return results;
+}
+
+/**
+ * Returns the exact redirect URIs to register, per enabled provider. Printed as
+ * a copy-pasteable box so the dev never guesses the port/path — the single thing
+ * that prevents redirect_uri_mismatch.
+ */
+function get_oauth_redirect_lines(project_root: string): string[] {
+  const hazo_config = read_ini_file(path.join(project_root, "config", "hazo_auth_config.ini"));
+  const oauth_section = hazo_config?.["hazo_auth__oauth"] ?? {};
+  const enable_google = (oauth_section["enable_google"] ?? "").toLowerCase() === "true";
+  const enable_facebook = (oauth_section["enable_facebook_oauth"] ?? "").toLowerCase() === "true";
+  if (!enable_google && !enable_facebook) return [];
+
+  const { origin, resolved } = read_oauth_origin();
+  const lines: string[] = [];
+  if (enable_google) lines.push(`  google   → ${origin}${GOOGLE_NEXTAUTH_CALLBACK_PATH}`);
+  if (enable_facebook) lines.push(`  facebook → ${origin}${FACEBOOK_NEXTAUTH_CALLBACK_PATH}`);
+  if (!resolved) {
+    lines.push("");
+    lines.push("  ⚠ NEXTAUTH_URL not set — above is a guess from PORT. Set it and re-register.");
+  }
+  return lines;
+}
+
 function check_api_routes(project_root: string): CheckResult[] {
   const results: CheckResult[] = [];
 
@@ -743,6 +850,17 @@ export function run_validation(): ValidationSummary {
   all_results.push(...env_results);
   console.log();
 
+  console.log("\x1b[1m🔑 OAuth Providers\x1b[0m");
+  const oauth_results = check_oauth(project_root);
+  oauth_results.forEach(print_result);
+  all_results.push(...oauth_results);
+  const redirect_lines = get_oauth_redirect_lines(project_root);
+  if (redirect_lines.length > 0) {
+    console.log("\n  Register these redirect URIs in the provider console (must match exactly):");
+    redirect_lines.forEach(line => console.log(line));
+  }
+  console.log();
+
   console.log("\x1b[1m🗄️  Database\x1b[0m");
   const db_results = check_database(project_root);
   db_results.forEach(print_result);

package/cli-src/lib/auth/auth_error_help.ts

@@ -0,0 +1,67 @@
+// file_description: client-safe decoder mapping NextAuth/hazo_auth `?error=` codes
+// to human-readable guidance. Use on a login/error page to replace opaque codes.
+
+export type AuthErrorHelp = {
+  /** The raw error code from the `?error=` query param. */
+  code: string;
+  /** Short, user-facing summary. */
+  title: string;
+  /** Developer-facing detail and remediation. */
+  detail: string;
+};
+
+const KNOWN: Record<string, Omit<AuthErrorHelp, "code">> = {
+  Configuration: {
+    title: "Sign-in is misconfigured.",
+    detail:
+      "The server's OAuth/NextAuth config is incomplete. Check NEXTAUTH_SECRET, NEXTAUTH_URL, and provider credentials. Run `npx hazo_auth validate`.",
+  },
+  AccessDenied: {
+    title: "Access denied.",
+    detail: "You don't have permission to sign in, or you cancelled the consent screen.",
+  },
+  Verification: {
+    title: "This sign-in link has expired.",
+    detail: "The link was already used or timed out. Request a new one.",
+  },
+  OAuthSignin: {
+    title: "Couldn't start sign-in.",
+    detail: "Error constructing the provider authorization URL. Check provider credentials.",
+  },
+  OAuthCallback: {
+    title: "Sign-in callback failed.",
+    detail:
+      "The provider rejected the callback. Most often the registered redirect URI doesn't match. Confirm the provider console lists the exact URI hazo_auth prints at boot.",
+  },
+  OAuthAccountNotLinked: {
+    title: "This email is already linked to a different sign-in method.",
+    detail: "Sign in with the original method, then link the new provider from account settings.",
+  },
+  GoogleTokenStorageUnconfigured: {
+    title: "Signed in, but offline Google access is unavailable.",
+    detail:
+      "Refresh-token storage needs HAZO_AUTH_OAUTH_KEY_CURRENT and HAZO_AUTH_OAUTH_KEY_<ID>. Login still works; set these only if you need offline Google API calls.",
+  },
+  redirect_uri_mismatch: {
+    title: "Sign-in blocked: redirect URI mismatch.",
+    detail:
+      "The redirect URI sent to the provider isn't registered. Register the exact URI hazo_auth prints at boot (origin = NEXTAUTH_URL + /api/auth/callback/<provider>). Note: providers usually show this on their own page, before returning to the app.",
+  },
+};
+
+/**
+ * Resolves a NextAuth/hazo_auth error code to friendly guidance. Unknown codes
+ * get a generic fallback so callers can always render something useful.
+ */
+export function describeAuthError(code: string | null | undefined): AuthErrorHelp {
+  const key = (code ?? "").trim();
+  const hit = key ? KNOWN[key] : undefined;
+  if (hit) return { code: key, ...hit };
+  return {
+    code: key || "Unknown",
+    title: "Sign-in failed.",
+    detail: key
+      ? `Unrecognised error code "${key}". Check the server logs for details.`
+      : "No error code provided. Check the server logs for details.",
+  };
+}

package/cli-src/lib/auth/nextauth_config.ts

@@ -13,6 +13,7 @@ import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { create_app_logger } from "../app_logger.js";
 import { store_google_oauth_token, GoogleTokenStorageUnconfigured } from "../services/google_token_service.js";
 import { GOOGLE_OAUTH_CALLBACK_PATH, FACEBOOK_OAUTH_CALLBACK_PATH } from "../oauth_routes.js";
+import { logOAuthPreflight } from "../oauth_preflight.server.js";
 
 // section: types
 export type NextAuthCallbackUser = {
@@ -48,6 +49,10 @@ export type NextAuthCallbackProfile = {
  * @returns NextAuth configuration object
  */
 export function get_nextauth_config(): AuthOptions {
+  // Print enabled-provider redirect URIs + flag missing env once per process.
+  // No-op after the first call; safe to run on every config build.
+  logOAuthPreflight();
+
   const oauth_config = get_oauth_config();
   const providers = [];
 

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

@@ -0,0 +1,188 @@
+// file_description: server-only OAuth preflight — validates env and prints the exact
+// 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 { googleRedirectUri, facebookRedirectUri } from "./oauth_routes.js";
+import { create_app_logger } from "./app_logger.js";
+
+// section: types
+export type PreflightStatus = "pass" | "warn" | "fail";
+
+export type PreflightCheck = {
+  name: string;
+  status: PreflightStatus;
+  message: string;
+};
+
+export type OAuthPreflightReport = {
+  /** Origin used to derive redirect URIs (NEXTAUTH_URL, or a fallback). */
+  origin: string;
+  /** True when NEXTAUTH_URL was actually set (vs. a guessed fallback). */
+  originResolved: boolean;
+  /** Absolute redirect URIs to paste into the provider console, per enabled provider. */
+  redirectUris: { provider: "google" | "facebook"; uri: string }[];
+  checks: PreflightCheck[];
+};
+
+// section: helpers
+const MIN_SECRET_LEN = 32;
+
+function resolve_origin(): { origin: string; resolved: boolean } {
+  const nextauth_url = process.env.NEXTAUTH_URL;
+  if (nextauth_url && nextauth_url.trim().length > 0) {
+    return { origin: nextauth_url.trim().replace(/\/+$/, ""), resolved: true };
+  }
+  // Fallback so we can still print a best-guess URI to register.
+  const port = process.env.PORT ?? "3000";
+  return { origin: `http://localhost:${port}`, resolved: false };
+}
+
+/**
+ * Builds a structured OAuth config report without printing. Safe to call
+ * anywhere server-side (CLI, route, instrumentation). Pure config inspection —
+ * no DB or network access.
+ */
+export function getOAuthPreflightReport(): OAuthPreflightReport {
+  const checks: PreflightCheck[] = [];
+  const { origin, resolved } = resolve_origin();
+  const oauth = get_oauth_config();
+  const redirectUris: OAuthPreflightReport["redirectUris"] = [];
+
+  // NEXTAUTH_URL — the source of the redirect URI.
+  if (resolved) {
+    checks.push({ name: "NEXTAUTH_URL", status: "pass", message: origin });
+  } else {
+    checks.push({
+      name: "NEXTAUTH_URL",
+      status: "fail",
+      message: `Not set. NextAuth derives the OAuth redirect URI from it. Set NEXTAUTH_URL=${origin} (matching the port you serve on).`,
+    });
+  }
+
+  // NEXTAUTH_URL port vs. the port the app is told to listen on.
+  const declared_port = process.env.PORT;
+  if (resolved && declared_port) {
+    let url_port: string | null = null;
+    try {
+      const u = new URL(origin);
+      url_port = u.port || (u.protocol === "https:" ? "443" : "80");
+    } catch {
+      url_port = null;
+    }
+    if (url_port && url_port !== declared_port) {
+      checks.push({
+        name: "Port match",
+        status: "warn",
+        message: `NEXTAUTH_URL port (${url_port}) differs from PORT (${declared_port}). The redirect URI uses ${url_port}; if you serve on ${declared_port}, OAuth will fail with redirect_uri_mismatch.`,
+      });
+    }
+  }
+
+  // NEXTAUTH_SECRET — required for OAuth session/state signing.
+  const secret = process.env.NEXTAUTH_SECRET;
+  if (!secret || secret.length === 0) {
+    checks.push({
+      name: "NEXTAUTH_SECRET",
+      status: "fail",
+      message: "Not set. Generate one: openssl rand -base64 32",
+    });
+  } else if (secret.length < MIN_SECRET_LEN) {
+    checks.push({
+      name: "NEXTAUTH_SECRET",
+      status: "warn",
+      message: `Only ${secret.length} chars; use at least ${MIN_SECRET_LEN}. Generate: openssl rand -base64 32`,
+    });
+  } else {
+    checks.push({ name: "NEXTAUTH_SECRET", status: "pass", message: "Set" });
+  }
+
+  // Google provider.
+  if (oauth.enable_google) {
+    const id = process.env.HAZO_AUTH_GOOGLE_CLIENT_ID;
+    const secretG = process.env.HAZO_AUTH_GOOGLE_CLIENT_SECRET;
+    if (!id || !secretG) {
+      const missing = [
+        !id ? "HAZO_AUTH_GOOGLE_CLIENT_ID" : null,
+        !secretG ? "HAZO_AUTH_GOOGLE_CLIENT_SECRET" : null,
+      ].filter(Boolean);
+      checks.push({
+        name: "Google OAuth credentials",
+        status: "fail",
+        message: `enable_google=true but missing: ${missing.join(", ")} (from Google Cloud Console).`,
+      });
+    } else {
+      checks.push({ name: "Google OAuth credentials", status: "pass", message: "Set" });
+    }
+    redirectUris.push({ provider: "google", uri: googleRedirectUri(origin) });
+  }
+
+  // Facebook provider.
+  if (oauth.enable_facebook_oauth) {
+    const appId = oauth.facebook_app_id || process.env.HAZO_AUTH_FACEBOOK_APP_ID;
+    const appSecret = oauth.facebook_app_secret || process.env.HAZO_AUTH_FACEBOOK_APP_SECRET;
+    if (!appId || !appSecret) {
+      checks.push({
+        name: "Facebook OAuth credentials",
+        status: "fail",
+        message: "enable_facebook_oauth=true but app_id/app_secret missing.",
+      });
+    } else {
+      checks.push({ name: "Facebook OAuth credentials", status: "pass", message: "Set" });
+    }
+    redirectUris.push({ provider: "facebook", uri: facebookRedirectUri(origin) });
+  }
+
+  return { origin, originResolved: resolved, redirectUris, checks };
+}
+
+// section: boot logger
+let _logged_once = false;
+
+/**
+ * Logs the OAuth preflight report once per process. Call from a Next.js
+ * `instrumentation.ts` `register()` hook to surface config problems — and the
+ * exact redirect URI to register — the moment the server boots, before anyone
+ * hits a broken sign-in.
+ *
+ * Idempotent: subsequent calls in the same process are no-ops.
+ */
+export function logOAuthPreflight(): OAuthPreflightReport | null {
+  if (_logged_once) return null;
+  _logged_once = true;
+
+  const report = getOAuthPreflightReport();
+  if (report.redirectUris.length === 0) return report; // No OAuth providers enabled.
+
+  const logger = create_app_logger();
+
+  for (const check of report.checks) {
+    if (check.status === "fail") {
+      logger.error("oauth_preflight_check_failed", { check: check.name, detail: check.message });
+    } else if (check.status === "warn") {
+      logger.warn("oauth_preflight_check_warning", { check: check.name, detail: check.message });
+    }
+  }
+
+  // Highlighted, copy-pasteable block — the single thing that prevents
+  // redirect_uri_mismatch. console (not logger) so it renders verbatim.
+  const lines: string[] = [
+    "",
+    "──────────────────────────────────────────────────────────────",
+    " hazo_auth · OAuth redirect URIs to register in the provider console",
+    "──────────────────────────────────────────────────────────────",
+  ];
+  for (const { provider, uri } of report.redirectUris) {
+    lines.push(`   ${provider.padEnd(9)} → ${uri}`);
+  }
+  if (!report.originResolved) {
+    lines.push("");
+    lines.push("   ⚠ NEXTAUTH_URL not set — above is a guess from PORT.");
+    lines.push("     Set NEXTAUTH_URL to your real origin and re-register.");
+  }
+  lines.push("──────────────────────────────────────────────────────────────");
+  lines.push("");
+  console.log(lines.join("\n"));
+
+  return report;
+}

package/cli-src/lib/oauth_routes.ts

@@ -11,3 +11,24 @@ export const FACEBOOK_NEXTAUTH_CALLBACK_PATH = "/api/auth/callback/facebook" as
 
 /** hazo_auth's custom post-auth handler — creates the hazo_auth session after Facebook sign-in. */
 export const FACEBOOK_OAUTH_CALLBACK_PATH = "/api/hazo_auth/oauth/facebook/callback" as const;
+
+/**
+ * Builds the absolute Google redirect URI to register in Google Cloud Console.
+ * This is exactly the value NextAuth sends as `redirect_uri`; registering
+ * anything else (wrong port, https vs http, trailing slash) causes the
+ * `redirect_uri_mismatch` 400. Derive it from your origin (= NEXTAUTH_URL) so
+ * the two can never drift.
+ */
+export function googleRedirectUri(origin: string): string {
+  return joinOrigin(origin, GOOGLE_NEXTAUTH_CALLBACK_PATH);
+}
+
+/** Builds the absolute Facebook redirect URI to register in the Facebook Developer Console. */
+export function facebookRedirectUri(origin: string): string {
+  return joinOrigin(origin, FACEBOOK_NEXTAUTH_CALLBACK_PATH);
+}
+
+function joinOrigin(origin: string, pathname: string): string {
+  // Tolerate a trailing slash on the origin; never emit a double slash.
+  return `${origin.replace(/\/+$/, "")}${pathname}`;
+}

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;AA2rBF,wBAAgB,cAAc,IAAI,iBAAiB,CA2ElD"}
+{"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"}

package/dist/cli/validate.js

@@ -268,6 +268,105 @@ function check_env_vars() {
     }
     return results;
 }
+// Canonical values live in src/lib/oauth_routes.ts; inlined here because the CLI
+// 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";
+function read_oauth_origin() {
+    var _a;
+    const nextauth_url = process.env.NEXTAUTH_URL;
+    if (nextauth_url && nextauth_url.trim().length > 0) {
+        return { origin: nextauth_url.trim().replace(/\/+$/, ""), resolved: true };
+    }
+    const port = (_a = process.env.PORT) !== null && _a !== void 0 ? _a : "3000";
+    return { origin: `http://localhost:${port}`, resolved: false };
+}
+function check_oauth(project_root) {
+    var _a, _b, _c;
+    const results = [];
+    const hazo_config_path = path.join(project_root, "config", "hazo_auth_config.ini");
+    const hazo_config = read_ini_file(hazo_config_path);
+    const oauth_section = (_a = hazo_config === null || hazo_config === void 0 ? void 0 : hazo_config["hazo_auth__oauth"]) !== null && _a !== void 0 ? _a : {};
+    const enable_google = ((_b = oauth_section["enable_google"]) !== null && _b !== void 0 ? _b : "").toLowerCase() === "true";
+    const enable_facebook = ((_c = oauth_section["enable_facebook_oauth"]) !== null && _c !== void 0 ? _c : "").toLowerCase() === "true";
+    if (!enable_google && !enable_facebook) {
+        results.push({
+            name: "OAuth providers",
+            status: "pass",
+            message: "No OAuth providers enabled (email/password only)",
+        });
+        return results;
+    }
+    const { origin, resolved } = read_oauth_origin();
+    // NEXTAUTH_URL — source of the redirect URI.
+    results.push(resolved
+        ? { name: "NEXTAUTH_URL", status: "pass", message: origin }
+        : {
+            name: "NEXTAUTH_URL",
+            status: "fail",
+            message: `Not set. The redirect URI below is a guess from PORT. Set NEXTAUTH_URL=${origin}`,
+        });
+    // NEXTAUTH_SECRET — required for OAuth state/session signing.
+    const secret = process.env.NEXTAUTH_SECRET;
+    if (!secret || secret.length === 0) {
+        results.push({
+            name: "NEXTAUTH_SECRET",
+            status: "fail",
+            message: "Not set. Generate: openssl rand -base64 32",
+        });
+    }
+    else if (secret.length < 32) {
+        results.push({
+            name: "NEXTAUTH_SECRET",
+            status: "warn",
+            message: `Only ${secret.length} chars; use at least 32. Generate: openssl rand -base64 32`,
+        });
+    }
+    else {
+        results.push({ name: "NEXTAUTH_SECRET", status: "pass", message: "Set" });
+    }
+    if (enable_google) {
+        const id = process.env.HAZO_AUTH_GOOGLE_CLIENT_ID;
+        const cs = process.env.HAZO_AUTH_GOOGLE_CLIENT_SECRET;
+        const missing = [
+            !id ? "HAZO_AUTH_GOOGLE_CLIENT_ID" : null,
+            !cs ? "HAZO_AUTH_GOOGLE_CLIENT_SECRET" : null,
+        ].filter(Boolean);
+        results.push(missing.length === 0
+            ? { name: "Google OAuth credentials", status: "pass", message: "Set" }
+            : {
+                name: "Google OAuth credentials",
+                status: "fail",
+                message: `enable_google=true but missing: ${missing.join(", ")}`,
+            });
+    }
+    return results;
+}
+/**
+ * Returns the exact redirect URIs to register, per enabled provider. Printed as
+ * a copy-pasteable box so the dev never guesses the port/path — the single thing
+ * that prevents redirect_uri_mismatch.
+ */
+function get_oauth_redirect_lines(project_root) {
+    var _a, _b, _c;
+    const hazo_config = read_ini_file(path.join(project_root, "config", "hazo_auth_config.ini"));
+    const oauth_section = (_a = hazo_config === null || hazo_config === void 0 ? void 0 : hazo_config["hazo_auth__oauth"]) !== null && _a !== void 0 ? _a : {};
+    const enable_google = ((_b = oauth_section["enable_google"]) !== null && _b !== void 0 ? _b : "").toLowerCase() === "true";
+    const enable_facebook = ((_c = oauth_section["enable_facebook_oauth"]) !== null && _c !== void 0 ? _c : "").toLowerCase() === "true";
+    if (!enable_google && !enable_facebook)
+        return [];
+    const { origin, resolved } = read_oauth_origin();
+    const lines = [];
+    if (enable_google)
+        lines.push(`  google   → ${origin}${GOOGLE_NEXTAUTH_CALLBACK_PATH}`);
+    if (enable_facebook)
+        lines.push(`  facebook → ${origin}${FACEBOOK_NEXTAUTH_CALLBACK_PATH}`);
+    if (!resolved) {
+        lines.push("");
+        lines.push("  ⚠ NEXTAUTH_URL not set — above is a guess from PORT. Set it and re-register.");
+    }
+    return lines;
+}
 function check_api_routes(project_root) {
     const results = [];
     const possible_app_dirs = [
@@ -682,6 +781,16 @@ export function run_validation() {
     env_results.forEach(print_result);
     all_results.push(...env_results);
     console.log();
+    console.log("\x1b[1m🔑 OAuth Providers\x1b[0m");
+    const oauth_results = check_oauth(project_root);
+    oauth_results.forEach(print_result);
+    all_results.push(...oauth_results);
+    const redirect_lines = get_oauth_redirect_lines(project_root);
+    if (redirect_lines.length > 0) {
+        console.log("\n  Register these redirect URIs in the provider console (must match exactly):");
+        redirect_lines.forEach(line => console.log(line));
+    }
+    console.log();
     console.log("\x1b[1m🗄️  Database\x1b[0m");
     const db_results = check_database(project_root);
     db_results.forEach(print_result);

package/dist/index.d.ts

@@ -8,4 +8,7 @@ export { cn, merge_class_names } from "./lib/utils.js";
 export { HAZO_AUTH_PERMISSIONS, ALL_ADMIN_PERMISSIONS, GLOBAL_ADMIN_PERMISSION } from "./lib/constants.js";
 export { GOOGLE_NEXTAUTH_CALLBACK_PATH, GOOGLE_OAUTH_CALLBACK_PATH, FACEBOOK_NEXTAUTH_CALLBACK_PATH, FACEBOOK_OAUTH_CALLBACK_PATH, } from "./lib/oauth_routes.js";
 export { requestGoogleScopes } from "./lib/auth/request_google_scopes.js";
+export { describeAuthError } from "./lib/auth/auth_error_help.js";
+export type { AuthErrorHelp } from "./lib/auth/auth_error_help";
+export { googleRedirectUri, facebookRedirectUri } from "./lib/oauth_routes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAG5C,cAAc,oBAAoB,CAAC;AAGnC,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,QAAQ,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGxG,OAAO,EAAE,EAAE,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAG5C,cAAc,oBAAoB,CAAC;AAGnC,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,QAAQ,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGxG,OAAO,EAAE,EAAE,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -17,3 +17,7 @@ export { HAZO_AUTH_PERMISSIONS, ALL_ADMIN_PERMISSIONS, GLOBAL_ADMIN_PERMISSION }
 export { GOOGLE_NEXTAUTH_CALLBACK_PATH, GOOGLE_OAUTH_CALLBACK_PATH, FACEBOOK_NEXTAUTH_CALLBACK_PATH, FACEBOOK_OAUTH_CALLBACK_PATH, } from "./lib/oauth_routes.js";
 // section: google_oauth_exports
 export { requestGoogleScopes } from "./lib/auth/request_google_scopes.js";
+// section: auth_error_help_exports (client-safe)
+export { describeAuthError } from "./lib/auth/auth_error_help.js";
+// section: oauth_route_helper_exports (client-safe — pure string builders)
+export { googleRedirectUri, facebookRedirectUri } from "./lib/oauth_routes.js";

package/dist/lib/auth/auth_error_help.d.ts

@@ -0,0 +1,14 @@
+export type AuthErrorHelp = {
+    /** The raw error code from the `?error=` query param. */
+    code: string;
+    /** Short, user-facing summary. */
+    title: string;
+    /** Developer-facing detail and remediation. */
+    detail: string;
+};
+/**
+ * Resolves a NextAuth/hazo_auth error code to friendly guidance. Unknown codes
+ * get a generic fallback so callers can always render something useful.
+ */
+export declare function describeAuthError(code: string | null | undefined): AuthErrorHelp;
+//# sourceMappingURL=auth_error_help.d.ts.map

package/dist/lib/auth/auth_error_help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth_error_help.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_error_help.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAyCF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAWhF"}

package/dist/lib/auth/auth_error_help.js

@@ -0,0 +1,53 @@
+// file_description: client-safe decoder mapping NextAuth/hazo_auth `?error=` codes
+// to human-readable guidance. Use on a login/error page to replace opaque codes.
+const KNOWN = {
+    Configuration: {
+        title: "Sign-in is misconfigured.",
+        detail: "The server's OAuth/NextAuth config is incomplete. Check NEXTAUTH_SECRET, NEXTAUTH_URL, and provider credentials. Run `npx hazo_auth validate`.",
+    },
+    AccessDenied: {
+        title: "Access denied.",
+        detail: "You don't have permission to sign in, or you cancelled the consent screen.",
+    },
+    Verification: {
+        title: "This sign-in link has expired.",
+        detail: "The link was already used or timed out. Request a new one.",
+    },
+    OAuthSignin: {
+        title: "Couldn't start sign-in.",
+        detail: "Error constructing the provider authorization URL. Check provider credentials.",
+    },
+    OAuthCallback: {
+        title: "Sign-in callback failed.",
+        detail: "The provider rejected the callback. Most often the registered redirect URI doesn't match. Confirm the provider console lists the exact URI hazo_auth prints at boot.",
+    },
+    OAuthAccountNotLinked: {
+        title: "This email is already linked to a different sign-in method.",
+        detail: "Sign in with the original method, then link the new provider from account settings.",
+    },
+    GoogleTokenStorageUnconfigured: {
+        title: "Signed in, but offline Google access is unavailable.",
+        detail: "Refresh-token storage needs HAZO_AUTH_OAUTH_KEY_CURRENT and HAZO_AUTH_OAUTH_KEY_<ID>. Login still works; set these only if you need offline Google API calls.",
+    },
+    redirect_uri_mismatch: {
+        title: "Sign-in blocked: redirect URI mismatch.",
+        detail: "The redirect URI sent to the provider isn't registered. Register the exact URI hazo_auth prints at boot (origin = NEXTAUTH_URL + /api/auth/callback/<provider>). Note: providers usually show this on their own page, before returning to the app.",
+    },
+};
+/**
+ * Resolves a NextAuth/hazo_auth error code to friendly guidance. Unknown codes
+ * get a generic fallback so callers can always render something useful.
+ */
+export function describeAuthError(code) {
+    const key = (code !== null && code !== void 0 ? code : "").trim();
+    const hit = key ? KNOWN[key] : undefined;
+    if (hit)
+        return Object.assign({ code: key }, hit);
+    return {
+        code: key || "Unknown",
+        title: "Sign-in failed.",
+        detail: key
+            ? `Unrecognised error code "${key}". Check the server logs for details.`
+            : "No error code provided. Check the server logs for details.",
+    };
+}

package/dist/lib/auth/nextauth_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nextauth_config.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/nextauth_config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,WAAW,CAAC;AAetD,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAGF;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,CA2RjD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAW7C"}
+{"version":3,"file":"nextauth_config.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/nextauth_config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,WAAW,CAAC;AAgBtD,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAGF;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,CA+RjD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAW7C"}

package/dist/lib/auth/nextauth_config.js

@@ -9,6 +9,7 @@ import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { create_app_logger } from "../app_logger.js";
 import { store_google_oauth_token, GoogleTokenStorageUnconfigured } from "../services/google_token_service.js";
 import { GOOGLE_OAUTH_CALLBACK_PATH, FACEBOOK_OAUTH_CALLBACK_PATH } from "../oauth_routes.js";
+import { logOAuthPreflight } from "../oauth_preflight.server.js";
 // section: config
 /**
  * Gets NextAuth.js configuration with enabled OAuth providers
@@ -16,6 +17,9 @@ import { GOOGLE_OAUTH_CALLBACK_PATH, FACEBOOK_OAUTH_CALLBACK_PATH } from "../oau
  * @returns NextAuth configuration object
  */
 export function get_nextauth_config() {
+    // Print enabled-provider redirect URIs + flag missing env once per process.
+    // No-op after the first call; safe to run on every config build.
+    logOAuthPreflight();
     const oauth_config = get_oauth_config();
     const providers = [];
     // Add Google provider if enabled

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

@@ -0,0 +1,35 @@
+import "server-only";
+export type PreflightStatus = "pass" | "warn" | "fail";
+export type PreflightCheck = {
+    name: string;
+    status: PreflightStatus;
+    message: string;
+};
+export type OAuthPreflightReport = {
+    /** Origin used to derive redirect URIs (NEXTAUTH_URL, or a fallback). */
+    origin: string;
+    /** True when NEXTAUTH_URL was actually set (vs. a guessed fallback). */
+    originResolved: boolean;
+    /** Absolute redirect URIs to paste into the provider console, per enabled provider. */
+    redirectUris: {
+        provider: "google" | "facebook";
+        uri: string;
+    }[];
+    checks: PreflightCheck[];
+};
+/**
+ * Builds a structured OAuth config report without printing. Safe to call
+ * anywhere server-side (CLI, route, instrumentation). Pure config inspection —
+ * no DB or network access.
+ */
+export declare function getOAuthPreflightReport(): OAuthPreflightReport;
+/**
+ * Logs the OAuth preflight report once per process. Call from a Next.js
+ * `instrumentation.ts` `register()` hook to surface config problems — and the
+ * exact redirect URI to register — the moment the server boots, before anyone
+ * hits a broken sign-in.
+ *
+ * Idempotent: subsequent calls in the same process are no-ops.
+ */
+export declare function logOAuthPreflight(): OAuthPreflightReport | null;
+//# sourceMappingURL=oauth_preflight.server.d.ts.map

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

@@ -0,0 +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"}

package/dist/lib/oauth_preflight.server.js

@@ -0,0 +1,162 @@
+// file_description: server-only OAuth preflight — validates env and prints the exact
+// 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 { googleRedirectUri, facebookRedirectUri } from "./oauth_routes.js";
+import { create_app_logger } from "./app_logger.js";
+// section: helpers
+const MIN_SECRET_LEN = 32;
+function resolve_origin() {
+    var _a;
+    const nextauth_url = process.env.NEXTAUTH_URL;
+    if (nextauth_url && nextauth_url.trim().length > 0) {
+        return { origin: nextauth_url.trim().replace(/\/+$/, ""), resolved: true };
+    }
+    // Fallback so we can still print a best-guess URI to register.
+    const port = (_a = process.env.PORT) !== null && _a !== void 0 ? _a : "3000";
+    return { origin: `http://localhost:${port}`, resolved: false };
+}
+/**
+ * Builds a structured OAuth config report without printing. Safe to call
+ * anywhere server-side (CLI, route, instrumentation). Pure config inspection —
+ * no DB or network access.
+ */
+export function getOAuthPreflightReport() {
+    const checks = [];
+    const { origin, resolved } = resolve_origin();
+    const oauth = get_oauth_config();
+    const redirectUris = [];
+    // NEXTAUTH_URL — the source of the redirect URI.
+    if (resolved) {
+        checks.push({ name: "NEXTAUTH_URL", status: "pass", message: origin });
+    }
+    else {
+        checks.push({
+            name: "NEXTAUTH_URL",
+            status: "fail",
+            message: `Not set. NextAuth derives the OAuth redirect URI from it. Set NEXTAUTH_URL=${origin} (matching the port you serve on).`,
+        });
+    }
+    // NEXTAUTH_URL port vs. the port the app is told to listen on.
+    const declared_port = process.env.PORT;
+    if (resolved && declared_port) {
+        let url_port = null;
+        try {
+            const u = new URL(origin);
+            url_port = u.port || (u.protocol === "https:" ? "443" : "80");
+        }
+        catch (_a) {
+            url_port = null;
+        }
+        if (url_port && url_port !== declared_port) {
+            checks.push({
+                name: "Port match",
+                status: "warn",
+                message: `NEXTAUTH_URL port (${url_port}) differs from PORT (${declared_port}). The redirect URI uses ${url_port}; if you serve on ${declared_port}, OAuth will fail with redirect_uri_mismatch.`,
+            });
+        }
+    }
+    // NEXTAUTH_SECRET — required for OAuth session/state signing.
+    const secret = process.env.NEXTAUTH_SECRET;
+    if (!secret || secret.length === 0) {
+        checks.push({
+            name: "NEXTAUTH_SECRET",
+            status: "fail",
+            message: "Not set. Generate one: openssl rand -base64 32",
+        });
+    }
+    else if (secret.length < MIN_SECRET_LEN) {
+        checks.push({
+            name: "NEXTAUTH_SECRET",
+            status: "warn",
+            message: `Only ${secret.length} chars; use at least ${MIN_SECRET_LEN}. Generate: openssl rand -base64 32`,
+        });
+    }
+    else {
+        checks.push({ name: "NEXTAUTH_SECRET", status: "pass", message: "Set" });
+    }
+    // Google provider.
+    if (oauth.enable_google) {
+        const id = process.env.HAZO_AUTH_GOOGLE_CLIENT_ID;
+        const secretG = process.env.HAZO_AUTH_GOOGLE_CLIENT_SECRET;
+        if (!id || !secretG) {
+            const missing = [
+                !id ? "HAZO_AUTH_GOOGLE_CLIENT_ID" : null,
+                !secretG ? "HAZO_AUTH_GOOGLE_CLIENT_SECRET" : null,
+            ].filter(Boolean);
+            checks.push({
+                name: "Google OAuth credentials",
+                status: "fail",
+                message: `enable_google=true but missing: ${missing.join(", ")} (from Google Cloud Console).`,
+            });
+        }
+        else {
+            checks.push({ name: "Google OAuth credentials", status: "pass", message: "Set" });
+        }
+        redirectUris.push({ provider: "google", uri: googleRedirectUri(origin) });
+    }
+    // Facebook provider.
+    if (oauth.enable_facebook_oauth) {
+        const appId = oauth.facebook_app_id || process.env.HAZO_AUTH_FACEBOOK_APP_ID;
+        const appSecret = oauth.facebook_app_secret || process.env.HAZO_AUTH_FACEBOOK_APP_SECRET;
+        if (!appId || !appSecret) {
+            checks.push({
+                name: "Facebook OAuth credentials",
+                status: "fail",
+                message: "enable_facebook_oauth=true but app_id/app_secret missing.",
+            });
+        }
+        else {
+            checks.push({ name: "Facebook OAuth credentials", status: "pass", message: "Set" });
+        }
+        redirectUris.push({ provider: "facebook", uri: facebookRedirectUri(origin) });
+    }
+    return { origin, originResolved: resolved, redirectUris, checks };
+}
+// section: boot logger
+let _logged_once = false;
+/**
+ * Logs the OAuth preflight report once per process. Call from a Next.js
+ * `instrumentation.ts` `register()` hook to surface config problems — and the
+ * exact redirect URI to register — the moment the server boots, before anyone
+ * hits a broken sign-in.
+ *
+ * Idempotent: subsequent calls in the same process are no-ops.
+ */
+export function logOAuthPreflight() {
+    if (_logged_once)
+        return null;
+    _logged_once = true;
+    const report = getOAuthPreflightReport();
+    if (report.redirectUris.length === 0)
+        return report; // No OAuth providers enabled.
+    const logger = create_app_logger();
+    for (const check of report.checks) {
+        if (check.status === "fail") {
+            logger.error("oauth_preflight_check_failed", { check: check.name, detail: check.message });
+        }
+        else if (check.status === "warn") {
+            logger.warn("oauth_preflight_check_warning", { check: check.name, detail: check.message });
+        }
+    }
+    // Highlighted, copy-pasteable block — the single thing that prevents
+    // redirect_uri_mismatch. console (not logger) so it renders verbatim.
+    const lines = [
+        "",
+        "──────────────────────────────────────────────────────────────",
+        " hazo_auth · OAuth redirect URIs to register in the provider console",
+        "──────────────────────────────────────────────────────────────",
+    ];
+    for (const { provider, uri } of report.redirectUris) {
+        lines.push(`   ${provider.padEnd(9)} → ${uri}`);
+    }
+    if (!report.originResolved) {
+        lines.push("");
+        lines.push("   ⚠ NEXTAUTH_URL not set — above is a guess from PORT.");
+        lines.push("     Set NEXTAUTH_URL to your real origin and re-register.");
+    }
+    lines.push("──────────────────────────────────────────────────────────────");
+    lines.push("");
+    console.log(lines.join("\n"));
+    return report;
+}

package/dist/lib/oauth_routes.d.ts

@@ -6,4 +6,14 @@ export declare const GOOGLE_OAUTH_CALLBACK_PATH: "/api/hazo_auth/oauth/google/ca
 export declare const FACEBOOK_NEXTAUTH_CALLBACK_PATH: "/api/auth/callback/facebook";
 /** hazo_auth's custom post-auth handler — creates the hazo_auth session after Facebook sign-in. */
 export declare const FACEBOOK_OAUTH_CALLBACK_PATH: "/api/hazo_auth/oauth/facebook/callback";
+/**
+ * Builds the absolute Google redirect URI to register in Google Cloud Console.
+ * This is exactly the value NextAuth sends as `redirect_uri`; registering
+ * anything else (wrong port, https vs http, trailing slash) causes the
+ * `redirect_uri_mismatch` 400. Derive it from your origin (= NEXTAUTH_URL) so
+ * the two can never drift.
+ */
+export declare function googleRedirectUri(origin: string): string;
+/** Builds the absolute Facebook redirect URI to register in the Facebook Developer Console. */
+export declare function facebookRedirectUri(origin: string): string;
 //# sourceMappingURL=oauth_routes.d.ts.map

package/dist/lib/oauth_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth_routes.d.ts","sourceRoot":"","sources":["../../src/lib/oauth_routes.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,eAAO,MAAM,6BAA6B,EAAG,2BAAoC,CAAC;AAElF,iGAAiG;AACjG,eAAO,MAAM,0BAA0B,EAAG,sCAA+C,CAAC;AAE1F,4FAA4F;AAC5F,eAAO,MAAM,+BAA+B,EAAG,6BAAsC,CAAC;AAEtF,mGAAmG;AACnG,eAAO,MAAM,4BAA4B,EAAG,wCAAiD,CAAC"}
+{"version":3,"file":"oauth_routes.d.ts","sourceRoot":"","sources":["../../src/lib/oauth_routes.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,eAAO,MAAM,6BAA6B,EAAG,2BAAoC,CAAC;AAElF,iGAAiG;AACjG,eAAO,MAAM,0BAA0B,EAAG,sCAA+C,CAAC;AAE1F,4FAA4F;AAC5F,eAAO,MAAM,+BAA+B,EAAG,6BAAsC,CAAC;AAEtF,mGAAmG;AACnG,eAAO,MAAM,4BAA4B,EAAG,wCAAiD,CAAC;AAE9F;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/lib/oauth_routes.js

@@ -7,3 +7,21 @@ export const GOOGLE_OAUTH_CALLBACK_PATH = "/api/hazo_auth/oauth/google/callback"
 export const FACEBOOK_NEXTAUTH_CALLBACK_PATH = "/api/auth/callback/facebook";
 /** hazo_auth's custom post-auth handler — creates the hazo_auth session after Facebook sign-in. */
 export const FACEBOOK_OAUTH_CALLBACK_PATH = "/api/hazo_auth/oauth/facebook/callback";
+/**
+ * Builds the absolute Google redirect URI to register in Google Cloud Console.
+ * This is exactly the value NextAuth sends as `redirect_uri`; registering
+ * anything else (wrong port, https vs http, trailing slash) causes the
+ * `redirect_uri_mismatch` 400. Derive it from your origin (= NEXTAUTH_URL) so
+ * the two can never drift.
+ */
+export function googleRedirectUri(origin) {
+    return joinOrigin(origin, GOOGLE_NEXTAUTH_CALLBACK_PATH);
+}
+/** Builds the absolute Facebook redirect URI to register in the Facebook Developer Console. */
+export function facebookRedirectUri(origin) {
+    return joinOrigin(origin, FACEBOOK_NEXTAUTH_CALLBACK_PATH);
+}
+function joinOrigin(origin, pathname) {
+    // Tolerate a trailing slash on the origin; never emit a double slash.
+    return `${origin.replace(/\/+$/, "")}${pathname}`;
+}

package/dist/server-lib.d.ts

@@ -38,4 +38,6 @@ export { wireAdminIssueCapture } from "./admin-issues/wire.server.js";
 export type { WireAdminIssueCaptureOptions } from "./admin-issues/wire.server";
 export { denyPermission } from "./lib/auth/deny_permission.server.js";
 export type { DenyPermissionInput } from "./lib/auth/deny_permission.server";
+export { logOAuthPreflight, getOAuthPreflightReport } from "./lib/oauth_preflight.server.js";
+export type { OAuthPreflightReport, PreflightCheck, PreflightStatus, } from "./lib/oauth_preflight.server";
 //# sourceMappingURL=server-lib.d.ts.map

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"}
+{"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"}

package/dist/server-lib.js

@@ -53,3 +53,7 @@ export { authIssueTypeDef, registerAuthIssuePlugin } from "./admin-issues/plugin
 export { wireAdminIssueCapture } from "./admin-issues/wire.server.js";
 // deny_permission helper
 export { denyPermission } from "./lib/auth/deny_permission.server.js";
+// section: oauth_preflight_exports
+// Call logOAuthPreflight() from a Next.js instrumentation.ts register() hook to
+// print the exact redirect URIs to register and flag missing OAuth env at boot.
+export { logOAuthPreflight, getOAuthPreflightReport } from "./lib/oauth_preflight.server.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "10.4.9",
+  "version": "10.4.10",
   "description": "Zero-config authentication UI components for Next.js with RBAC, OAuth, scope-based multi-tenancy, and invitations",
   "keywords": [
     "authentication",