najm-auth 2.0.1 → 2.0.3

package/dist/{NajmAuthClient-D08--i69.d.ts → NajmAuthClient-B9dGk9MH.d.ts}

@@ -77,6 +77,11 @@ interface AuthClientConfig {
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
+type OAuthProvider = 'google';
+interface OAuthLoginOptions {
+    /** Same-origin frontend path after OAuth completes. */
+    returnTo?: string;
+}
 /**
  * Auth event types
  */
@@ -182,6 +187,11 @@ declare class NajmAuthClient {
         password: string;
     }): Promise<AuthUser>;
     register(data: Record<string, unknown>): Promise<AuthUser>;
+    getOAuthLoginUrl(provider: OAuthProvider, options?: OAuthLoginOptions): string;
+    loginWithOAuth(provider: OAuthProvider, options?: OAuthLoginOptions): void;
+    loginWithGoogle(options?: OAuthLoginOptions): void;
+    linkOAuthAccount(provider: OAuthProvider, options?: OAuthLoginOptions): Promise<void>;
+    completeOAuthLogin(): Promise<AuthUser>;
     logout(): Promise<void>;
     refresh(): Promise<void>;
     fetchUser(): Promise<AuthUser | null>;
@@ -230,10 +240,11 @@ declare class NajmAuthClient {
     private handleTabMessage;
     private notify;
     private emit;
+    private validateReturnTo;
 }
 /**
  * Factory function to create an auth client.
  */
 declare function createAuthClient(config: AuthClientConfig): NajmAuthClient;
 
-export { AuthError as A, type DecodedToken as D, FetchClient as F, type HydrateSession as H, NajmAuthClient as N, type RetryConfig as R, type SyncPayload as S, type TabSyncMessage as T, type AuthClientConfig as a, type AuthEventMap as b, createAuthClient as c, type AuthState as d, type AuthUser as e, type AuthEvent as f, type AuthEventHandler as g, type ServerResponse as h, type TokenPair as i, type RequestOptions as j };
+export { AuthError as A, type DecodedToken as D, FetchClient as F, type HydrateSession as H, NajmAuthClient as N, type OAuthProvider as O, type RetryConfig as R, type SyncPayload as S, type TabSyncMessage as T, type AuthClientConfig as a, type AuthEventMap as b, createAuthClient as c, type AuthState as d, type AuthUser as e, type AuthEvent as f, type AuthEventHandler as g, type ServerResponse as h, type TokenPair as i, type RequestOptions as j, type OAuthLoginOptions as k };

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
-import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../NajmAuthClient-D08--i69.js';
-export { a as AuthClientConfig, A as AuthError, f as AuthEvent, g as AuthEventHandler, b as AuthEventMap, d as AuthState, e as AuthUser, F as FetchClient, H as HydrateSession, N as NajmAuthClient, j as RequestOptions, R as RetryConfig, h as ServerResponse, i as TokenPair, c as createAuthClient } from '../NajmAuthClient-D08--i69.js';
+import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../NajmAuthClient-B9dGk9MH.js';
+export { a as AuthClientConfig, A as AuthError, f as AuthEvent, g as AuthEventHandler, b as AuthEventMap, d as AuthState, e as AuthUser, F as FetchClient, H as HydrateSession, N as NajmAuthClient, k as OAuthLoginOptions, O as OAuthProvider, j as RequestOptions, R as RetryConfig, h as ServerResponse, i as TokenPair, c as createAuthClient } from '../NajmAuthClient-B9dGk9MH.js';
 
 /**
  * Decode a JWT token payload without verification.

package/dist/client/index.js

@@ -264,6 +264,43 @@ var NajmAuthClient = class _NajmAuthClient {
     );
     return res.data;
   }
+  getOAuthLoginUrl(provider, options = {}) {
+    const baseURL = this.config.baseURL.replace(/\/$/, "");
+    const authPrefix = this.prefix.startsWith("/") ? this.prefix : `/${this.prefix}`;
+    const raw = `${baseURL}${authPrefix}/oauth/${provider}/start`;
+    const absolute = /^[a-z][a-z\d+.-]*:\/\//i.test(raw);
+    const url = new URL(raw, absolute ? void 0 : "https://najm.invalid");
+    if (options.returnTo) {
+      url.searchParams.set("returnTo", this.validateReturnTo(options.returnTo));
+    }
+    return absolute ? url.toString() : `${url.pathname}${url.search}`;
+  }
+  loginWithOAuth(provider, options) {
+    if (typeof window === "undefined") {
+      throw new Error("OAuth login requires a browser environment");
+    }
+    window.location.assign(this.getOAuthLoginUrl(provider, options));
+  }
+  loginWithGoogle(options) {
+    this.loginWithOAuth("google", options);
+  }
+  async linkOAuthAccount(provider, options = {}) {
+    const query = options.returnTo ? `?${new URLSearchParams({ returnTo: this.validateReturnTo(options.returnTo) })}` : "";
+    const res = await this.api.post(
+      `${this.prefix}/oauth/${provider}/link${query}`
+    );
+    if (!res.data?.authorizationUrl) throw new Error("OAuth provider did not return an authorization URL");
+    if (typeof window === "undefined") throw new Error("OAuth linking requires a browser environment");
+    window.location.assign(res.data.authorizationUrl);
+  }
+  async completeOAuthLogin() {
+    await this.refresh();
+    const user = await this.fetchUser();
+    if (!user) throw new Error("OAuth session could not be completed");
+    this.tabSync?.broadcastSync(this.getSyncPayload());
+    this.emit("login", user);
+    return user;
+  }
   async logout() {
     this.resetState();
     this.tabSync?.broadcastLogout();
@@ -555,6 +592,18 @@ var NajmAuthClient = class _NajmAuthClient {
       this.eventListeners.get("stateChange")?.forEach((h) => h(this.state));
     }
   }
+  validateReturnTo(value) {
+    const candidate = value.trim();
+    if (!candidate.startsWith("/") || candidate.startsWith("//") || candidate.includes("\\")) {
+      throw new Error("returnTo must be a same-origin path");
+    }
+    const base = new URL("https://najm.invalid");
+    const parsed = new URL(candidate, base);
+    if (parsed.origin !== base.origin || parsed.username || parsed.password) {
+      throw new Error("returnTo must be a same-origin path");
+    }
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  }
 };
 function createAuthClient(config) {
   return new NajmAuthClient(config);

package/dist/client/react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, ReactElement } from 'react';
-import { N as NajmAuthClient, H as HydrateSession, d as AuthState, e as AuthUser, A as AuthError, f as AuthEvent, b as AuthEventMap } from '../../NajmAuthClient-D08--i69.js';
+import { N as NajmAuthClient, H as HydrateSession, d as AuthState, e as AuthUser, A as AuthError, k as OAuthLoginOptions, f as AuthEvent, b as AuthEventMap } from '../../NajmAuthClient-B9dGk9MH.js';
 
 interface AuthProviderProps {
     client: NajmAuthClient;
@@ -162,6 +162,27 @@ interface UseChangePasswordReturn {
 }
 declare function useChangePassword(opts?: UseChangePasswordOptions): UseChangePasswordReturn;
 
+interface UseGoogleLoginOptions {
+    onError?: (error: AuthError | Error) => void;
+}
+interface UseGoogleLoginReturn {
+    loginWithGoogle: (options?: OAuthLoginOptions) => void;
+    linkGoogle: (options?: OAuthLoginOptions) => Promise<void>;
+    isRedirecting: boolean;
+    error: AuthError | Error | null;
+}
+declare function useGoogleLogin(options?: UseGoogleLoginOptions): UseGoogleLoginReturn;
+
+interface UseOAuthCallbackOptions {
+    onSuccess?: (user: AuthUser) => void;
+    onError?: (error: AuthError | Error) => void;
+}
+declare function useOAuthCallback(options?: UseOAuthCallbackOptions): {
+    complete: () => Promise<AuthUser>;
+    isLoading: boolean;
+    error: AuthError | Error;
+};
+
 /**
  * Subscribe to a specific auth event. Cleans up on unmount.
  * Uses a stable ref for the handler to avoid re-subscribing on every render.
@@ -537,4 +558,22 @@ interface RedirectToLoginProps {
  */
 declare function RedirectToLogin({ to, preserveFrom }: RedirectToLoginProps): any;
 
-export { AuthBoundary, type AuthEventEntry, AuthGate, AuthLoading, AuthProvider, Can, IfAuth, LoginButton, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useLogin, useLogout, usePermissions, useRegister, useResetPassword, useSession, useUser };
+interface GoogleLoginButtonProps extends OAuthLoginOptions {
+    children: ReactNode;
+    onError?: (error: Error) => void;
+}
+declare function GoogleLoginButton({ children, returnTo, onError }: GoogleLoginButtonProps): ReactElement<{
+    onClick?: (event: unknown) => void;
+    disabled?: boolean;
+}, string | react.JSXElementConstructor<any>>;
+
+interface OAuthCallbackProps {
+    fallback?: ReactNode;
+    errorFallback?: ReactNode | ((props: {
+        error: Error;
+    }) => ReactNode);
+    defaultRedirect?: string;
+}
+declare function OAuthCallback({ fallback, errorFallback, defaultRedirect, }: OAuthCallbackProps): react_jsx_runtime.JSX.Element;
+
+export { AuthBoundary, type AuthEventEntry, AuthGate, AuthLoading, AuthProvider, Can, GoogleLoginButton, IfAuth, LoginButton, OAuthCallback, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useGoogleLogin, useLogin, useLogout, useOAuthCallback, usePermissions, useRegister, useResetPassword, useSession, useUser };

package/dist/client/react/index.js

@@ -310,11 +310,74 @@ function useChangePassword(opts) {
 }
 __name(useChangePassword, "useChangePassword");
 
+// src/client/react/useGoogleLogin.ts
+import { useCallback as useCallback7, useState as useState8 } from "react";
+function useGoogleLogin(options) {
+  const client = useAuthClient();
+  const [isRedirecting, setIsRedirecting] = useState8(false);
+  const [error, setError] = useState8(null);
+  const fail = useCallback7((value) => {
+    const next = value instanceof Error ? value : new Error(String(value));
+    setIsRedirecting(false);
+    setError(next);
+    options?.onError?.(next);
+  }, [options?.onError]);
+  const loginWithGoogle = useCallback7((loginOptions) => {
+    setError(null);
+    setIsRedirecting(true);
+    try {
+      client.loginWithGoogle(loginOptions);
+    } catch (value) {
+      fail(value);
+    }
+  }, [client, fail]);
+  const linkGoogle = useCallback7(async (loginOptions) => {
+    setError(null);
+    setIsRedirecting(true);
+    try {
+      await client.linkOAuthAccount("google", loginOptions);
+    } catch (value) {
+      fail(value);
+    }
+  }, [client, fail]);
+  return { loginWithGoogle, linkGoogle, isRedirecting, error };
+}
+__name(useGoogleLogin, "useGoogleLogin");
+
+// src/client/react/useOAuthCallback.ts
+import { useCallback as useCallback8, useRef as useRef3, useState as useState9 } from "react";
+function useOAuthCallback(options) {
+  const client = useAuthClient();
+  const promise = useRef3(null);
+  const [isLoading, setIsLoading] = useState9(false);
+  const [error, setError] = useState9(null);
+  const complete = useCallback8(async () => {
+    if (promise.current) return promise.current;
+    setIsLoading(true);
+    setError(null);
+    promise.current = client.completeOAuthLogin();
+    try {
+      const user = await promise.current;
+      options?.onSuccess?.(user);
+      return user;
+    } catch (value) {
+      const next = value instanceof Error ? value : new Error(String(value));
+      setError(next);
+      options?.onError?.(next);
+      throw next;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client, options?.onSuccess, options?.onError]);
+  return { complete, isLoading, error };
+}
+__name(useOAuthCallback, "useOAuthCallback");
+
 // src/client/react/useAuthEvent.ts
-import { useEffect as useEffect3, useRef as useRef3 } from "react";
+import { useEffect as useEffect3, useRef as useRef4 } from "react";
 function useAuthEvent(event, handler) {
   const client = useAuthClient();
-  const handlerRef = useRef3(handler);
+  const handlerRef = useRef4(handler);
   handlerRef.current = handler;
   useEffect3(() => {
     const listener = /* @__PURE__ */ __name((data) => handlerRef.current(data), "listener");
@@ -325,7 +388,7 @@ function useAuthEvent(event, handler) {
 __name(useAuthEvent, "useAuthEvent");
 
 // src/client/react/useAuthEvents.ts
-import { useEffect as useEffect4, useRef as useRef4, useState as useState8 } from "react";
+import { useEffect as useEffect4, useRef as useRef5, useState as useState10 } from "react";
 var ALL_EVENTS = [
   "login",
   "logout",
@@ -338,8 +401,8 @@ var ALL_EVENTS = [
 function useAuthEvents(opts) {
   const client = useAuthClient();
   const max = opts?.maxEntries ?? 100;
-  const [entries, setEntries] = useState8([]);
-  const maxRef = useRef4(max);
+  const [entries, setEntries] = useState10([]);
+  const maxRef = useRef5(max);
   maxRef.current = max;
   useEffect4(() => {
     const cleanups = [];
@@ -619,14 +682,73 @@ function RedirectToLogin({ to = "/login", preserveFrom = true }) {
   return null;
 }
 __name(RedirectToLogin, "RedirectToLogin");
+
+// src/client/react/GoogleLoginButton.tsx
+import { Children as Children3, cloneElement as cloneElement3, isValidElement as isValidElement3 } from "react";
+function GoogleLoginButton({ children, returnTo, onError }) {
+  const { loginWithGoogle, isRedirecting } = useGoogleLogin({ onError });
+  const child = Children3.only(children);
+  if (!isValidElement3(child)) {
+    throw new Error("<GoogleLoginButton> expects a single React element as its child");
+  }
+  const element = child;
+  return cloneElement3(element, {
+    onClick: /* @__PURE__ */ __name((event) => {
+      element.props.onClick?.(event);
+      if (!event?.defaultPrevented) {
+        loginWithGoogle({ returnTo });
+      }
+    }, "onClick"),
+    disabled: Boolean(element.props.disabled || isRedirecting)
+  });
+}
+__name(GoogleLoginButton, "GoogleLoginButton");
+
+// src/client/react/OAuthCallback.tsx
+import { useEffect as useEffect7 } from "react";
+import { Fragment as Fragment14, jsx as jsx16 } from "react/jsx-runtime";
+var safeReturnTo = /* @__PURE__ */ __name((value, fallback) => {
+  const safeFallback = fallback.startsWith("/") && !fallback.startsWith("//") && !fallback.includes("\\") ? fallback : "/";
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.includes("\\")) return safeFallback;
+  try {
+    const base = new URL("https://najm.invalid");
+    const parsed = new URL(value, base);
+    if (parsed.origin !== base.origin) return safeFallback;
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  } catch {
+    return safeFallback;
+  }
+}, "safeReturnTo");
+function OAuthCallback({
+  fallback = null,
+  errorFallback = null,
+  defaultRedirect = "/"
+}) {
+  const { complete, error } = useOAuthCallback();
+  useEffect7(() => {
+    complete().then(() => {
+      if (typeof window === "undefined") return;
+      const params = new URLSearchParams(window.location.search);
+      window.location.replace(safeReturnTo(params.get("returnTo"), defaultRedirect));
+    }).catch(() => {
+    });
+  }, [complete, defaultRedirect]);
+  if (error) {
+    return /* @__PURE__ */ jsx16(Fragment14, { children: typeof errorFallback === "function" ? errorFallback({ error }) : errorFallback });
+  }
+  return /* @__PURE__ */ jsx16(Fragment14, { children: fallback });
+}
+__name(OAuthCallback, "OAuthCallback");
 export {
   AuthBoundary,
   AuthGate,
   AuthLoading,
   AuthProvider,
   Can,
+  GoogleLoginButton,
   IfAuth,
   LoginButton,
+  OAuthCallback,
   PermissionList,
   Protected,
   RedirectToLogin,
@@ -644,8 +766,10 @@ export {
   useAuthEvents,
   useChangePassword,
   useForgotPassword,
+  useGoogleLogin,
   useLogin,
   useLogout,
+  useOAuthCallback,
   usePermissions,
   useRegister,
   useResetPassword,

package/dist/client/server/index.d.ts

@@ -1,4 +1,4 @@
-import { e as AuthUser, F as FetchClient, R as RetryConfig, N as NajmAuthClient } from '../../NajmAuthClient-D08--i69.js';
+import { e as AuthUser, F as FetchClient, R as RetryConfig, N as NajmAuthClient } from '../../NajmAuthClient-B9dGk9MH.js';
 export { withAuthMiddleware } from '../edge.js';
 import 'next/server';
 

package/dist/client/server/index.js

@@ -588,6 +588,43 @@ var NajmAuthClient = class _NajmAuthClient {
     );
     return res.data;
   }
+  getOAuthLoginUrl(provider, options = {}) {
+    const baseURL = this.config.baseURL.replace(/\/$/, "");
+    const authPrefix = this.prefix.startsWith("/") ? this.prefix : `/${this.prefix}`;
+    const raw = `${baseURL}${authPrefix}/oauth/${provider}/start`;
+    const absolute = /^[a-z][a-z\d+.-]*:\/\//i.test(raw);
+    const url = new URL(raw, absolute ? void 0 : "https://najm.invalid");
+    if (options.returnTo) {
+      url.searchParams.set("returnTo", this.validateReturnTo(options.returnTo));
+    }
+    return absolute ? url.toString() : `${url.pathname}${url.search}`;
+  }
+  loginWithOAuth(provider, options) {
+    if (typeof window === "undefined") {
+      throw new Error("OAuth login requires a browser environment");
+    }
+    window.location.assign(this.getOAuthLoginUrl(provider, options));
+  }
+  loginWithGoogle(options) {
+    this.loginWithOAuth("google", options);
+  }
+  async linkOAuthAccount(provider, options = {}) {
+    const query = options.returnTo ? `?${new URLSearchParams({ returnTo: this.validateReturnTo(options.returnTo) })}` : "";
+    const res = await this.api.post(
+      `${this.prefix}/oauth/${provider}/link${query}`
+    );
+    if (!res.data?.authorizationUrl) throw new Error("OAuth provider did not return an authorization URL");
+    if (typeof window === "undefined") throw new Error("OAuth linking requires a browser environment");
+    window.location.assign(res.data.authorizationUrl);
+  }
+  async completeOAuthLogin() {
+    await this.refresh();
+    const user = await this.fetchUser();
+    if (!user) throw new Error("OAuth session could not be completed");
+    this.tabSync?.broadcastSync(this.getSyncPayload());
+    this.emit("login", user);
+    return user;
+  }
   async logout() {
     this.resetState();
     this.tabSync?.broadcastLogout();
@@ -879,6 +916,18 @@ var NajmAuthClient = class _NajmAuthClient {
       this.eventListeners.get("stateChange")?.forEach((h) => h(this.state));
     }
   }
+  validateReturnTo(value) {
+    const candidate = value.trim();
+    if (!candidate.startsWith("/") || candidate.startsWith("//") || candidate.includes("\\")) {
+      throw new Error("returnTo must be a same-origin path");
+    }
+    const base = new URL("https://najm.invalid");
+    const parsed = new URL(candidate, base);
+    if (parsed.origin !== base.origin || parsed.username || parsed.password) {
+      throw new Error("returnTo must be a same-origin path");
+    }
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  }
 };
 function createAuthClient(config) {
   return new NajmAuthClient(config);

package/dist/index.d.ts

@@ -2,11 +2,11 @@ import * as najm_core from 'najm-core';
 import { Container } from 'najm-core';
 import { ValidationPluginConfig } from 'najm-validation';
 import { RateLimitPluginConfig } from 'najm-rate';
+import { EmailPluginConfig, EmailService } from 'najm-email';
 import { I18nService } from 'najm-i18n';
-import { EmailService } from 'najm-email';
 import { TDb, SeedEntry } from 'najm-database';
 import { User, NewUser, RoleEntity, NewRoleEntity, Permission, NewPermission, RolePermission } from './schema/pg.js';
-export { NewRolePermission, NewToken, Token, authSchema, baseFields, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
+export { NewOAuthAccount, NewRolePermission, NewToken, OAuthAccount, Token, authSchema, baseFields, oauthAccountsTable, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
 import { CacheService } from 'najm-cache';
 import { z } from 'zod';
 import { GuardResult } from 'najm-guard';
@@ -45,6 +45,48 @@ interface SessionCookieConfig {
     /** Secret used to HMAC-sign the cookie. Defaults to jwt.accessSecret. */
     secret?: string;
 }
+type OAuthProvider = 'google';
+interface GoogleOAuthConfig {
+    /** Google OAuth web client ID. Falls back to GOOGLE_CLIENT_ID. */
+    clientId?: string;
+    /** Google OAuth web client secret. Falls back to GOOGLE_CLIENT_SECRET. */
+    clientSecret?: string;
+    /**
+     * Absolute backend callback URL registered in Google Cloud. Falls back to
+     * GOOGLE_CALLBACK_URL, then `${frontendUrl}/api/auth/oauth/google/callback`.
+     */
+    callbackUrl?: string;
+    /** Frontend route that completes the Najm client session. */
+    frontendCallbackPath?: string;
+    /** Frontend route that receives stable OAuth errors. */
+    errorRedirectPath?: string;
+    /** Create a Najm user for a new Google identity (default: true). */
+    allowSignup?: boolean;
+    /** Link an existing user by verified email (default: false). */
+    autoLinkVerifiedEmail?: boolean;
+    /** Optional Google Workspace hosted-domain allowlist. */
+    allowedHostedDomains?: string[];
+}
+interface OAuthConfig {
+    /**
+     * Enable Google with environment defaults (`google: true`), or override
+     * individual settings for split-origin deployments and policy changes.
+     */
+    google?: true | GoogleOAuthConfig;
+}
+interface ResolvedGoogleOAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    frontendCallbackPath: string;
+    errorRedirectPath: string;
+    allowSignup: boolean;
+    autoLinkVerifiedEmail: boolean;
+    allowedHostedDomains: string[];
+}
+interface ResolvedOAuthConfig {
+    google?: ResolvedGoogleOAuthConfig;
+}
 /**
  * Complete auth plugin configuration (internal)
  */
@@ -73,6 +115,8 @@ interface AuthConfig {
     bcryptRounds: number;
     /** Session cookie cache settings */
     session: SessionCookieConfig;
+    /** Resolved external identity-provider configuration. */
+    oauth?: ResolvedOAuthConfig;
 }
 /**
  * Auth plugin configuration options
@@ -88,6 +132,8 @@ interface AuthSchema {
     roles: any;
     permissions: any;
     rolePermissions: any;
+    /** Required when an OAuth provider is enabled. */
+    oauthAccounts?: any;
 }
 type AuthPluginConfig = {
     /**
@@ -130,8 +176,12 @@ type AuthPluginConfig = {
     validation?: ValidationPluginConfig;
     /** Optional config forwarded to rateLimit() dependency */
     rateLimit?: RateLimitPluginConfig;
+    /** Email transport used by password reset and verification flows. */
+    email?: EmailPluginConfig;
     /** AES-256-GCM key for reversible encryption (e.g. API keys). Falls back to NAJM_ENCRYPTION_KEY env var. */
     encryptionKey?: string;
+    /** External identity providers. */
+    oauth?: OAuthConfig;
 };
 /**
  * JWT payload structure
@@ -208,7 +258,17 @@ var auth = {
 		sessionExpired: "Session has expired",
 		accountLocked: "Account is temporarily locked. Please try again later.",
 		accountInactive: "Account is inactive. Please contact support.",
-		emailNotVerified: "Please verify your email address before signing in."
+		emailNotVerified: "Please verify your email address before signing in.",
+		oauthProviderDisabled: "Google sign-in is not configured.",
+		oauthStateInvalid: "The Google sign-in attempt is invalid or expired.",
+		oauthAccessDenied: "Google sign-in was cancelled.",
+		oauthProviderError: "Google sign-in could not be completed.",
+		oauthVerifiedEmailRequired: "Google must provide a verified email address.",
+		oauthAccountLinkRequired: "Sign in with your password and link Google from your account.",
+		oauthProviderAccountLinked: "This Google account is already linked.",
+		oauthSignupDisabled: "Registration with Google is disabled.",
+		oauthHostedDomainDenied: "This Google Workspace domain is not allowed.",
+		oauthLinkSessionExpired: "Your session changed before Google could be linked. Please try again."
 	},
 	success: {
 		login: "Login successful",
@@ -218,7 +278,9 @@ var auth = {
 		passwordResetSent: "If that email exists, a reset link has been sent",
 		passwordReset: "Password has been reset successfully",
 		accountInviteSent: "Invitation sent successfully",
-		tokenRefreshed: "Token refreshed successfully"
+		tokenRefreshed: "Token refreshed successfully",
+		oauthLogin: "Google sign-in successful",
+		oauthLinked: "Google account linked successfully"
 	},
 	emails: {
 		passwordReset: {
@@ -314,6 +376,16 @@ declare const AUTH_LOCALES: {
                 accountLocked: string;
                 accountInactive: string;
                 emailNotVerified: string;
+                oauthProviderDisabled: string;
+                oauthStateInvalid: string;
+                oauthAccessDenied: string;
+                oauthProviderError: string;
+                oauthVerifiedEmailRequired: string;
+                oauthAccountLinkRequired: string;
+                oauthProviderAccountLinked: string;
+                oauthSignupDisabled: string;
+                oauthHostedDomainDenied: string;
+                oauthLinkSessionExpired: string;
             };
             success: {
                 login: string;
@@ -324,6 +396,8 @@ declare const AUTH_LOCALES: {
                 passwordReset: string;
                 accountInviteSent: string;
                 tokenRefreshed: string;
+                oauthLogin: string;
+                oauthLinked: string;
             };
             emails: {
                 passwordReset: {
@@ -478,6 +552,9 @@ declare class UserRepository {
     getByEmail(email: string): Promise<(User & {
         role?: string | null;
     }) | undefined>;
+    getByEmailInsensitive(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
     create(data: NewUser): Promise<User>;
     update(id: string, data: Partial<NewUser>): Promise<User | undefined>;
     updateLastLogin(id: string): Promise<User>;
@@ -737,6 +814,9 @@ declare class UserService {
     findByEmail(email: string): Promise<(User & {
         role?: string | null;
     }) | undefined>;
+    findByEmailInsensitive(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
     getAuthRecordById(id: string): Promise<User | undefined>;
     create(data: Record<string, any>): Promise<SanitizedUser>;
     update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
@@ -1093,6 +1173,16 @@ type UserIdInParam = z.infer<typeof userIdInParam>;
 type AssignRoleParams = z.infer<typeof assignRoleParams>;
 type UserListQuery = z.infer<typeof userListQuery>;
 
+declare class AuthSessionService {
+    private tokenService;
+    private userService;
+    private cookieManager;
+    constructor(tokenService: TokenService, userService: UserService, cookieManager: CookieManager);
+    establish(user: SanitizedUser): Promise<TokenPair & {
+        user: SanitizedUser;
+    }>;
+}
+
 /**
  * Identity fields for creating a user behind a person record (parent, student,
  * teacher, staff…). Role can be given by name (`role`) or id (`roleId`).
@@ -1114,11 +1204,12 @@ declare class AuthService {
     private cookieManager;
     private i18nService;
     private emailService;
+    private authSessionService?;
     private config;
     private t;
     private logger;
     private dummyHash?;
-    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService);
+    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService, authSessionService?: AuthSessionService);
     private isLockoutActive;
     private nextLockoutUntil;
     private getDummyHash;
@@ -1306,7 +1397,7 @@ interface RunAsUser {
 }
 declare function runAsUser<T>(container: Container, user: RunAsUser, fn: () => Promise<T> | T): Promise<T>;
 
-declare const AUTH_MODULE: readonly [typeof AuthService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController, typeof AuthResolver];
+declare const AUTH_MODULE: readonly [typeof AuthService, typeof AuthSessionService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController, typeof AuthResolver];
 
 declare class PermissionRepository {
     db: TDb;
@@ -2197,4 +2288,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type DefineRolesOptions, type EmailParam, EncryptionService, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, type ResetPasswordDto, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type DefineRolesOptions, type EmailParam, EncryptionService, type GoogleOAuthConfig, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, type ResetPasswordDto, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };