cloudflare-next-intl 0.6.13 → 0.6.15

package/dist/src/config/init_config.d.ts

@@ -2,9 +2,14 @@ import type { LocalePrefixMode, Locales, RoutingConfig } from '../types/types';
 /**
  * Defines and type-checks your app's i18n routing config.
  *
- * Identity function at runtime — it exists purely so TypeScript infers
- * `AppLocales`/`AppLocalePrefixMode` from the literal config object you pass
- * in, giving you autocomplete/type errors on `locale` params elsewhere.
+ * Mostly an identity function at runtime — it exists primarily so
+ * TypeScript infers `AppLocales`/`AppLocalePrefixMode` from the literal
+ * config object you pass in, giving you autocomplete/type errors on
+ * `locale` params elsewhere. The one runtime behavior: if `firebaseAuth` is
+ * set, `redirectAuthPath`/`homePath`/`verifyEmailPath` are auto-corrected to
+ * start with `/` (with a console warning) if you forgot it — see
+ * `normalizeFirebaseAuthPaths` above for why that specific typo is worth
+ * guarding against.
  *
  * Export the result from the file referenced by `@intl-config` (see your
  * `next.config`), e.g.:

package/dist/src/config/init_config.js

@@ -1,9 +1,45 @@
+// Every path this package compares against `request.nextUrl.pathname`
+// (always `/`-prefixed) must itself start with `/` — a missing leading
+// slash means `path === fa.verifyEmailPath` (and the same check for
+// `redirectAuthPath`/`homePath`) never matches, silently disabling that
+// redirect/exemption entirely (e.g. an infinite redirect loop on
+// `verifyEmailPath` because the page is never recognized as itself).
+// Auto-prepending `/` here fixes the common typo (`'login'` instead of
+// `'/login'`) at the source, for every consumer, instead of requiring each
+// one to notice and fix it themselves.
+const FIREBASE_AUTH_PATH_FIELDS = ['redirectAuthPath', 'homePath', 'verifyEmailPath'];
+function normalizeFirebaseAuthPaths(config) {
+    const fa = config.firebaseAuth;
+    if (!fa)
+        return config;
+    let changed = false;
+    const normalizedFa = { ...fa };
+    for (const field of FIREBASE_AUTH_PATH_FIELDS) {
+        const value = normalizedFa[field];
+        if (typeof value === 'string' && value !== '' && !value.startsWith('/')) {
+            console.warn(`[cloudflare-next-intl] firebaseAuth.${field} ("${value}") is missing its leading "/" — ` +
+                `auto-corrected to "/${value}". Paths are compared against the URL pathname (always ` +
+                `"/"-prefixed), so without this fix the check would never match and silently disable the ` +
+                `redirect/exemption for this path. Fix your config to avoid this warning.`);
+            normalizedFa[field] = `/${value}`;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return config;
+    return { ...config, firebaseAuth: normalizedFa };
+}
 /**
  * Defines and type-checks your app's i18n routing config.
  *
- * Identity function at runtime — it exists purely so TypeScript infers
- * `AppLocales`/`AppLocalePrefixMode` from the literal config object you pass
- * in, giving you autocomplete/type errors on `locale` params elsewhere.
+ * Mostly an identity function at runtime — it exists primarily so
+ * TypeScript infers `AppLocales`/`AppLocalePrefixMode` from the literal
+ * config object you pass in, giving you autocomplete/type errors on
+ * `locale` params elsewhere. The one runtime behavior: if `firebaseAuth` is
+ * set, `redirectAuthPath`/`homePath`/`verifyEmailPath` are auto-corrected to
+ * start with `/` (with a console warning) if you forgot it — see
+ * `normalizeFirebaseAuthPaths` above for why that specific typo is worth
+ * guarding against.
  *
  * Export the result from the file referenced by `@intl-config` (see your
  * `next.config`), e.g.:
@@ -15,5 +51,5 @@
  * ```
  */
 export function setIntlConfig(config) {
-    return config;
+    return normalizeFirebaseAuthPaths(config);
 }

package/dist/src/firebase_auth/client/auth_user_provider.js

@@ -108,6 +108,19 @@ export default function AuthUserProvider({ initialUser = null, children }) {
     // login-then-bounce-home flash whenever the two disagreed.
     const consecutiveNulls = useRef(0);
     const [confirmedSignedOut, setConfirmedSignedOut] = useState(initialUser === null);
+    // Whether `onSignIn`/`onSignOut` have already fired for the CURRENT
+    // signed-in/signed-out state — both seeded from `initialUser` so a
+    // callback observing the SAME state `initialUser` already established
+    // (server-resolved, not a fresh client-side transition) does not refire
+    // it. Reset on the opposite transition so the next real occurrence of
+    // this state fires again.
+    const signInCallbackFired = useRef(initialUser !== null);
+    const signOutCallbackFired = useRef(initialUser === null);
+    // Tracks the last-observed `emailVerified` value so `onEmailVerified`
+    // fires exactly once on the false→true edge, not on every later
+    // observation of an already-verified user (both `onIdTokenChanged` and
+    // `reloadUser` can be the first to observe the transition).
+    const emailVerifiedRef = useRef(initialUser?.emailVerified ?? false);
     useEffect(() => {
         const { user, loading } = state;
         if (loading || isWhiteListed)
@@ -168,11 +181,42 @@ export default function AuthUserProvider({ initialUser = null, children }) {
                 if (user) {
                     consecutiveNulls.current = 0;
                     setConfirmedSignedOut(false);
+                    signOutCallbackFired.current = false;
+                    if (!signInCallbackFired.current) {
+                        signInCallbackFired.current = true;
+                        try {
+                            await fa.onSignIn?.(user);
+                        }
+                        catch (e) {
+                            console.error('AuthUserProvider: onSignIn callback failed', e);
+                        }
+                    }
+                    if (!emailVerifiedRef.current && user.emailVerified) {
+                        emailVerifiedRef.current = true;
+                        try {
+                            await fa.onEmailVerified?.(user);
+                        }
+                        catch (e) {
+                            console.error('AuthUserProvider: onEmailVerified callback failed', e);
+                        }
+                    }
+                    else {
+                        emailVerifiedRef.current = user.emailVerified;
+                    }
                 }
                 else {
                     consecutiveNulls.current += 1;
-                    if (consecutiveNulls.current >= 2)
+                    signInCallbackFired.current = false;
+                    if (consecutiveNulls.current >= 2 && !signOutCallbackFired.current) {
                         setConfirmedSignedOut(true);
+                        signOutCallbackFired.current = true;
+                        try {
+                            await fa.onSignOut?.();
+                        }
+                        catch (e) {
+                            console.error('AuthUserProvider: onSignOut callback failed', e);
+                        }
+                    }
                 }
                 const flipped = previous !== undefined && previous !== isSignedIn;
                 const contradictsPage = previous === undefined && isSignedIn === isAuthPage;
@@ -221,6 +265,18 @@ export default function AuthUserProvider({ initialUser = null, children }) {
                 }
             }
             await writeSession(user, sessionCookieName, maxAge, refreshTokenCookieName, refreshTokenMaxAge, emailVerifiedHintCookieName, confirmedToken);
+            if (!emailVerifiedRef.current && user.emailVerified) {
+                emailVerifiedRef.current = true;
+                try {
+                    await fa.onEmailVerified?.(user);
+                }
+                catch (e) {
+                    console.error('AuthUserProvider: onEmailVerified callback failed', e);
+                }
+            }
+            else {
+                emailVerifiedRef.current = user.emailVerified;
+            }
             setAuthUserCache(user);
             setState({ user, loading: false });
         }

package/dist/src/server/components/server_provider.d.ts

@@ -13,6 +13,64 @@ import type { TranslationObject } from "../../types/types";
  *   otherwise.
  * @param messages Optional pre-loaded messages for `language`. If omitted,
  *   they're loaded via `getMessage(language)`.
+ * @param staticSafe Marks THIS RENDER of `IntlProvider` as one that's safe
+ *   to serve from static rendering / ISR — i.e. the caller already knows
+ *   the current route never needs a server-resolved auth user (a public
+ *   page: marketing, privacy policy, docs, etc). Concretely, setting this
+ *   to `true` skips the internal `resolveAuthUserAndRedirect()` call.
+ *
+ *   ── Why this call is normally made, and why skipping it is safe ──
+ *   When `firebaseAuth` is configured, `IntlProvider` by default calls
+ *   `resolveAuthUserAndRedirect()`, which:
+ *     1. Reads the session cookie via `cookies()` and verifies it against
+ *        Firebase (server-side, authoritative check for "who is this?").
+ *     2. Reads the current pathname via `headers()` (`x-pathname`, set by
+ *        `intlMiddleware`) to redirect guest → `redirectAuthPath` or
+ *        signed-in → `homePath` on an auth page.
+ *     3. Returns the resolved user so the client `AuthUserProvider` can
+ *        render the correct signed-in/signed-out UI on the FIRST paint,
+ *        with zero flash.
+ *   Both `cookies()` and `headers()` are request-scoped APIs — calling
+ *   either one forces Next.js to render the ENTIRE subtree dynamically on
+ *   every request. No static HTML, no ISR, no caching — for that route
+ *   AND every route nested under this same `IntlProvider` call, whether
+ *   or not that specific route actually needs auth. A page in
+ *   `firebaseAuth.whiteListPaths` (meant to be public) is NOT exempt from
+ *   this cost today: the whitelist check happens only AFTER `cookies()`/
+ *   `headers()` are already read, so it's just as dynamic as a protected
+ *   page.
+ *
+ *   The redirect part of step 2 is redundant on any project using the
+ *   default middleware wiring (`firebaseAuth.middlewareEnabled !== false`,
+ *   the default): `intlMiddleware`'s `update_session` step already
+ *   validates the session JWT (refreshing it via Firebase's token API if
+ *   expired) and performs the exact same guest/auth-page redirects —
+ *   authoritatively, on every request, BEFORE this component ever runs.
+ *   So `staticSafe: true` does not weaken auth enforcement — the
+ *   middleware gate still applies unchanged. The only thing you give up
+ *   is step 3: `initialAuthUser` is not seeded server-side, so the client
+ *   `AuthUserProvider` resolves it itself after mount instead. In
+ *   practice this means a signed-in user MAY see this route's
+ *   logged-out-state UI (e.g. a nav avatar placeholder) for one client
+ *   render before the real user data appears — never wrong/protected
+ *   content, since middleware already gated that; just a delayed value.
+ *
+ *   ── When to use it ──
+ *   Set `staticSafe: true` only on `IntlProvider` calls that wrap routes
+ *   you know are always public and don't render auth-dependent UI above
+ *   the fold (or can tolerate that UI appearing a moment late). Leave the
+ *   default (`false`) for any `IntlProvider` call that also wraps
+ *   protected routes or routes where the auth-state flash would be
+ *   visually jarring (dashboards, account pages, anything showing
+ *   `initialAuthUser`-derived content immediately). If you need
+ *   different behavior for public vs protected routes within the SAME
+ *   app, render `IntlProvider` twice — once per layout/route-group, each
+ *   with its own `staticSafe` value — rather than picking one value for
+ *   the whole app. If `firebaseAuth.middlewareEnabled` is explicitly
+ *   `false` (middleware auth disabled), do NOT set `staticSafe: true` —
+ *   this component becomes the ONLY place performing the auth redirect,
+ *   so skipping it there really does remove the security check, not just
+ *   the flash.
  *
  * @example
  * ```tsx
@@ -28,8 +86,9 @@ import type { TranslationObject } from "../../types/types";
  * }
  * ```
  */
-export default function LocationzationProvider({ language, messages, children }: {
+export default function LocationzationProvider({ language, messages, staticSafe, children }: {
     language: string;
     messages?: TranslationObject;
+    staticSafe?: boolean;
     children: React.ReactNode;
 }): Promise<Component>;

package/dist/src/server/components/server_provider.js

@@ -23,6 +23,64 @@ let authUserServerProviderModule;
  *   otherwise.
  * @param messages Optional pre-loaded messages for `language`. If omitted,
  *   they're loaded via `getMessage(language)`.
+ * @param staticSafe Marks THIS RENDER of `IntlProvider` as one that's safe
+ *   to serve from static rendering / ISR — i.e. the caller already knows
+ *   the current route never needs a server-resolved auth user (a public
+ *   page: marketing, privacy policy, docs, etc). Concretely, setting this
+ *   to `true` skips the internal `resolveAuthUserAndRedirect()` call.
+ *
+ *   ── Why this call is normally made, and why skipping it is safe ──
+ *   When `firebaseAuth` is configured, `IntlProvider` by default calls
+ *   `resolveAuthUserAndRedirect()`, which:
+ *     1. Reads the session cookie via `cookies()` and verifies it against
+ *        Firebase (server-side, authoritative check for "who is this?").
+ *     2. Reads the current pathname via `headers()` (`x-pathname`, set by
+ *        `intlMiddleware`) to redirect guest → `redirectAuthPath` or
+ *        signed-in → `homePath` on an auth page.
+ *     3. Returns the resolved user so the client `AuthUserProvider` can
+ *        render the correct signed-in/signed-out UI on the FIRST paint,
+ *        with zero flash.
+ *   Both `cookies()` and `headers()` are request-scoped APIs — calling
+ *   either one forces Next.js to render the ENTIRE subtree dynamically on
+ *   every request. No static HTML, no ISR, no caching — for that route
+ *   AND every route nested under this same `IntlProvider` call, whether
+ *   or not that specific route actually needs auth. A page in
+ *   `firebaseAuth.whiteListPaths` (meant to be public) is NOT exempt from
+ *   this cost today: the whitelist check happens only AFTER `cookies()`/
+ *   `headers()` are already read, so it's just as dynamic as a protected
+ *   page.
+ *
+ *   The redirect part of step 2 is redundant on any project using the
+ *   default middleware wiring (`firebaseAuth.middlewareEnabled !== false`,
+ *   the default): `intlMiddleware`'s `update_session` step already
+ *   validates the session JWT (refreshing it via Firebase's token API if
+ *   expired) and performs the exact same guest/auth-page redirects —
+ *   authoritatively, on every request, BEFORE this component ever runs.
+ *   So `staticSafe: true` does not weaken auth enforcement — the
+ *   middleware gate still applies unchanged. The only thing you give up
+ *   is step 3: `initialAuthUser` is not seeded server-side, so the client
+ *   `AuthUserProvider` resolves it itself after mount instead. In
+ *   practice this means a signed-in user MAY see this route's
+ *   logged-out-state UI (e.g. a nav avatar placeholder) for one client
+ *   render before the real user data appears — never wrong/protected
+ *   content, since middleware already gated that; just a delayed value.
+ *
+ *   ── When to use it ──
+ *   Set `staticSafe: true` only on `IntlProvider` calls that wrap routes
+ *   you know are always public and don't render auth-dependent UI above
+ *   the fold (or can tolerate that UI appearing a moment late). Leave the
+ *   default (`false`) for any `IntlProvider` call that also wraps
+ *   protected routes or routes where the auth-state flash would be
+ *   visually jarring (dashboards, account pages, anything showing
+ *   `initialAuthUser`-derived content immediately). If you need
+ *   different behavior for public vs protected routes within the SAME
+ *   app, render `IntlProvider` twice — once per layout/route-group, each
+ *   with its own `staticSafe` value — rather than picking one value for
+ *   the whole app. If `firebaseAuth.middlewareEnabled` is explicitly
+ *   `false` (middleware auth disabled), do NOT set `staticSafe: true` —
+ *   this component becomes the ONLY place performing the auth redirect,
+ *   so skipping it there really does remove the security check, not just
+ *   the flash.
  *
  * @example
  * ```tsx
@@ -38,7 +96,7 @@ let authUserServerProviderModule;
  * }
  * ```
  */
-export default async function LocationzationProvider({ language, messages, children }) {
+export default async function LocationzationProvider({ language, messages, staticSafe = false, children }) {
     if (!localesSet.has(language)) {
         const { notFound } = await import("next/navigation");
         notFound();
@@ -54,10 +112,25 @@ export default async function LocationzationProvider({ language, messages, child
     let initialAuthUser = null;
     const autoWireClientProvider = config.firebaseAuth?.autoWireClientProvider !== false;
     if (config.firebaseAuth && autoWireClientProvider) {
-        if (!authUserServerProviderModule) {
-            authUserServerProviderModule = await import("../../firebase_auth/server/auth_user_server_provider");
+        // `staticSafe: true` with middleware auth disabled would silently
+        // drop the ONLY auth redirect this app has — not just the flash-
+        // prevention seed. Warn loudly rather than let that combination
+        // slip through unnoticed; still honor the caller's choice, since a
+        // hard throw here would be a worse failure mode than a console
+        // warning for what is, after all, a caller-controlled flag.
+        if (staticSafe && config.firebaseAuth.middlewareEnabled === false) {
+            console.warn('[cloudflare-next-intl] IntlProvider was called with `staticSafe: true` while ' +
+                '`firebaseAuth.middlewareEnabled` is `false`. With middleware auth disabled, ' +
+                'this component is the ONLY place performing the auth redirect — skipping it ' +
+                'here removes that protection entirely, it does not just remove a render flash. ' +
+                'Set `staticSafe: false` (or enable middleware auth) for this route.');
+        }
+        if (!staticSafe) {
+            if (!authUserServerProviderModule) {
+                authUserServerProviderModule = await import("../../firebase_auth/server/auth_user_server_provider");
+            }
+            initialAuthUser = await authUserServerProviderModule.resolveAuthUserAndRedirect();
         }
-        initialAuthUser = await authUserServerProviderModule.resolveAuthUserAndRedirect();
     }
     let analyticsConfig;
     let requiresConsent = true;

package/dist/src/types/types.d.ts

@@ -4,6 +4,7 @@ import type { Videos } from 'next/dist/lib/metadata/types/metadata-types';
 import type { CookieConsentDialogProps } from '../cookie_consent/client/components/cookie_consent_dialog';
 import type { PrivacyPolicyUpdateDialogProps } from '../cookie_consent/client/components/privacy_policy_update_dialog';
 import type { ConsentValue } from '../cookie_consent/types';
+import type { User } from 'firebase/auth';
 /**
  * Custom middleware hook, run by `intlMiddleware` for your own logic
  * (e.g. auth, feature flags, A/B tests) — on top of the library's own
@@ -439,11 +440,11 @@ export interface FirebaseAuthRoutingConfig {
     appId: string;
     /** Firebase Analytics measurement ID. */
     measurementId?: string;
-    /** Path to redirect signed-out users to, e.g. "/login". */
+    /** Path to redirect signed-out users to, e.g. "/login". Must start with "/" — `setIntlConfig` auto-corrects a missing leading slash with a warning. */
     redirectAuthPath: string;
-    /** Path to redirect signed-in users away from auth pages to, e.g. "/". */
+    /** Path to redirect signed-in users away from auth pages to, e.g. "/". Must start with "/" — `setIntlConfig` auto-corrects a missing leading slash with a warning. */
     homePath: string;
-    /** Path to redirect unverified-email users to. Omit to skip email-verification redirects. */
+    /** Path to redirect unverified-email users to. Omit to skip email-verification redirects. Must start with "/" — `setIntlConfig` auto-corrects a missing leading slash with a warning. */
     verifyEmailPath?: string;
     /** Returns true if the given (locale-stripped) path is an auth page (login/signup/etc). */
     isAuthPath: (path: string) => boolean;
@@ -459,6 +460,34 @@ export interface FirebaseAuthRoutingConfig {
     refreshTokenCookieName?: string;
     /** Email-verified hint cookie name. Defaults to `'__fa_email_verified_hint__'`. Client-written, non-httpOnly; lets the middleware avoid an unnecessary token refresh when its view already matches the client's. */
     emailVerifiedHintCookieName?: string;
+    /**
+     * Called once, the moment `AuthUserProvider` observes a real sign-in
+     * (a `null → user` transition) — never on a plain token refresh of an
+     * already-signed-in user. Runs after the session/refresh-token/
+     * email-verified-hint cookies have already been written for this
+     * user, so cookie state is in sync when this fires. A throw/rejection
+     * is caught and logged via `console.error`; it never blocks cookie
+     * sync or navigation.
+     */
+    onSignIn?: (user: User) => void | Promise<void>;
+    /**
+     * Called once, on the `false → true` transition of `user.emailVerified`
+     * — never on a later observation of an already-verified user. Checked
+     * from both `AuthUserProvider`'s `onIdTokenChanged` listener and its
+     * `reloadUser()`, since either can be the first to observe the
+     * transition. A throw/rejection is caught and logged via
+     * `console.error`.
+     */
+    onEmailVerified?: (user: User) => void | Promise<void>;
+    /**
+     * Called once, when sign-out is confirmed — after `AuthUserProvider`'s
+     * existing debounce for transient SDK null-callbacks (two consecutive
+     * `onIdTokenChanged(null)` calls), not on the first, possibly
+     * transient, null. Runs after the session/refresh-token cookies have
+     * already been cleared. A throw/rejection is caught and logged via
+     * `console.error`.
+     */
+    onSignOut?: () => void | Promise<void>;
 }
 export interface CookieAttributes {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",