@jskit-ai/auth-provider-supabase-core 0.1.4

package/src/server/lib/service.js

@@ -0,0 +1,868 @@
+import { createClient } from "@supabase/supabase-js";
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import {
+  AUTH_METHOD_PASSWORD_ID,
+  AUTH_METHOD_PASSWORD_PROVIDER,
+  buildOAuthMethodId
+} from "@jskit-ai/auth-core/shared/authMethods";
+import { normalizeEmail } from "@jskit-ai/auth-core/server/utils";
+import { validators } from "@jskit-ai/auth-core/server/validators";
+import {
+  isTransientAuthMessage,
+  isTransientSupabaseError,
+  mapAuthError,
+  validationError,
+  isUserNotFoundLikeAuthError,
+  mapRecoveryError,
+  mapPasswordUpdateError,
+  mapOtpVerifyError,
+  mapProfileUpdateError,
+  mapCurrentPasswordError
+} from "./authErrorMappers.js";
+import { displayNameFromEmail, resolveDisplayName, resolveDisplayNameFromClaims } from "./authProfileNames.js";
+import {
+  normalizeOAuthProviderInput as normalizeOAuthProviderInputFromCatalog,
+  validatePasswordRecoveryPayload,
+  parseOAuthCompletePayload as parseOAuthCompletePayloadFromCatalog,
+  parseOtpLoginVerifyPayload,
+  mapOAuthCallbackError
+} from "./authInputParsers.js";
+import {
+  parseHttpUrl,
+  buildPasswordResetRedirectUrl,
+  buildOtpLoginRedirectUrl,
+  normalizeOAuthIntent,
+  normalizeReturnToPath,
+  buildOAuthRedirectUrl,
+  buildOAuthLoginRedirectUrl,
+  buildOAuthLinkRedirectUrl
+} from "./authRedirectUrls.js";
+import {
+  normalizeIdentityProviderId,
+  collectProviderIdsFromSupabaseUser,
+  buildAuthMethodsStatusFromProviderIds,
+  buildAuthMethodsStatusFromSupabaseUser,
+  buildSecurityStatusFromAuthMethodsStatus,
+  findAuthMethodById,
+  findLinkedIdentityByProvider
+} from "./authMethodStatus.js";
+import { safeRequestCookies, cookieOptions } from "./authCookies.js";
+import { loadJose, isExpiredJwtError, classifyJwtVerifyError } from "./authJwt.js";
+import { buildDisabledPasswordSecret } from "./authSecrets.js";
+import { createAccountFlows } from "./accountFlows.js";
+import { createOauthFlows } from "./oauthFlows.js";
+import { createPasswordSecurityFlows } from "./passwordSecurityFlows.js";
+import { USER_PROFILE_EMAIL_CONFLICT_CODE } from "./standaloneProfileSyncService.js";
+import {
+  buildOAuthProviderCatalogResponse,
+  resolveOAuthProviderQueryParams,
+  resolveSupabaseOAuthProviderCatalog
+} from "./oauthProviderCatalog.js";
+
+const ACCESS_TOKEN_COOKIE = "sb_access_token";
+const REFRESH_TOKEN_COOKIE = "sb_refresh_token";
+const DEFAULT_AUDIENCE = "authenticated";
+const DEFAULT_AUTH_PROVIDER_ID = "supabase";
+const AUTH_PROVIDER_ID_PATTERN = /^[a-z][a-z0-9_-]{1,63}$/;
+const PERSISTENT_SESSION_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 400;
+
+function normalizeAuthProviderId(value, { fallback = DEFAULT_AUTH_PROVIDER_ID } = {}) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (AUTH_PROVIDER_ID_PATTERN.test(normalized)) {
+    return normalized;
+  }
+
+  const fallbackNormalized = String(fallback || "")
+    .trim()
+    .toLowerCase();
+  if (AUTH_PROVIDER_ID_PATTERN.test(fallbackNormalized)) {
+    return fallbackNormalized;
+  }
+
+  return DEFAULT_AUTH_PROVIDER_ID;
+}
+
+function normalizeProviderUserId(value) {
+  return String(value || "").trim();
+}
+
+function createService(options) {
+  const authProvider = options.authProvider && typeof options.authProvider === "object" ? options.authProvider : null;
+  if (!authProvider) {
+    throw new Error("authProvider is required.");
+  }
+
+  const authProviderId = normalizeAuthProviderId(authProvider.id);
+  if (authProviderId !== DEFAULT_AUTH_PROVIDER_ID) {
+    throw new Error(`Unsupported auth provider "${authProviderId}".`);
+  }
+
+  const supabaseUrl = String(authProvider.supabaseUrl || "").trim();
+  const supabasePublishableKey = String(authProvider.supabasePublishableKey || "").trim();
+  const userSettingsRepository = options.userSettingsRepository || null;
+  const userProfileSyncService = options.userProfileSyncService;
+  if (
+    !userProfileSyncService ||
+    typeof userProfileSyncService.syncIdentityProfile !== "function" ||
+    typeof userProfileSyncService.findByIdentity !== "function"
+  ) {
+    throw new Error("userProfileSyncService with syncIdentityProfile() and findByIdentity() is required.");
+  }
+  const isProduction = options.nodeEnv === "production";
+  const jwtAudience = String(authProvider.jwtAudience || DEFAULT_AUDIENCE).trim();
+  const settingsProfileAuthInfo = Object.freeze({
+    emailManagedBy: normalizeAuthProviderId(authProvider.emailManagedBy || authProviderId, { fallback: authProviderId }),
+    emailChangeFlow: normalizeAuthProviderId(authProvider.emailChangeFlow || authProviderId, { fallback: authProviderId })
+  });
+  const passwordResetRedirectUrl = buildPasswordResetRedirectUrl({
+    appPublicUrl: options.appPublicUrl
+  });
+  const otpLoginRedirectUrl = buildOtpLoginRedirectUrl({
+    appPublicUrl: options.appPublicUrl
+  });
+  const appPublicUrl = String(options.appPublicUrl || "");
+  const authAllowedReturnToOrigins = Array.isArray(options.authAllowedReturnToOrigins)
+    ? options.authAllowedReturnToOrigins
+    : [];
+  const authOAuthCatalog = resolveSupabaseOAuthProviderCatalog({
+    oauthProviderCatalog: authProvider.oauthProviderCatalog || options.authOAuthProviderCatalog,
+    oauthProviders: authProvider.oauthProviders ?? options.authOAuthProviders,
+    oauthDefaultProvider: authProvider.oauthDefaultProvider ?? options.authOAuthDefaultProvider,
+    oauthProviderLabels: authProvider.oauthProviderLabels || options.authOAuthProviderLabels,
+    oauthProviderQueryParams: authProvider.oauthProviderQueryParams || options.authOAuthProviderQueryParams
+  });
+  const authOAuthProviders = authOAuthCatalog.providers;
+  const authOAuthProviderIds = authOAuthCatalog.providerIds;
+  const authOAuthDefaultProvider = authOAuthCatalog.defaultProvider;
+  const authOAuthCatalogResponse = Object.freeze(buildOAuthProviderCatalogResponse(authOAuthCatalog));
+
+  function normalizeOAuthProviderInput(value) {
+    return normalizeOAuthProviderInputFromCatalog(value, {
+      providerIds: authOAuthProviderIds,
+      defaultProvider: authOAuthDefaultProvider
+    });
+  }
+
+  function parseOAuthCompletePayload(payload) {
+    return parseOAuthCompletePayloadFromCatalog(payload, {
+      providerIds: authOAuthProviderIds,
+      defaultProvider: authOAuthDefaultProvider
+    });
+  }
+
+  function buildOAuthLoginRedirectUrlWithCatalog(payload) {
+    return buildOAuthLoginRedirectUrl({
+      ...payload,
+      providerIds: authOAuthProviderIds
+    });
+  }
+
+  function buildOAuthLinkRedirectUrlWithCatalog(payload) {
+    return buildOAuthLinkRedirectUrl({
+      ...payload,
+      providerIds: authOAuthProviderIds
+    });
+  }
+
+  function resolveOAuthProviderQueryParamsForProvider(providerId) {
+    return resolveOAuthProviderQueryParams(providerId, {
+      providerQueryParamsById: authOAuthCatalog.providerQueryParamsById
+    });
+  }
+
+  function normalizeAuthReturnToTarget(value, { fallback = "/" } = {}) {
+    return normalizeReturnToPath(value, {
+      fallback,
+      allowedOrigins: authAllowedReturnToOrigins
+    });
+  }
+
+  const issuerUrl = supabaseUrl ? new URL("/auth/v1", supabaseUrl).toString().replace(/\/$/, "") : "";
+  const jwksUrl = issuerUrl ? `${issuerUrl}/.well-known/jwks.json` : "";
+
+  let jwksResolver = null;
+
+  function ensureConfigured() {
+    if (!supabaseUrl || !supabasePublishableKey) {
+      throw new AppError(500, "Auth provider is not configured.");
+    }
+  }
+
+  function createSupabaseClient() {
+    ensureConfigured();
+    return createClient(supabaseUrl, supabasePublishableKey, {
+      auth: {
+        autoRefreshToken: false,
+        persistSession: false
+      }
+    });
+  }
+
+  function getSupabaseClient() {
+    return createSupabaseClient();
+  }
+
+  function createStatelessSupabaseClient() {
+    return createSupabaseClient();
+  }
+
+  async function getJwksResolver() {
+    if (jwksResolver) {
+      return jwksResolver;
+    }
+
+    const jose = await loadJose();
+    jwksResolver = jose.createRemoteJWKSet(new URL(jwksUrl));
+    return jwksResolver;
+  }
+
+  async function verifyAccessToken(accessToken) {
+    const jose = await loadJose();
+    const jwks = await getJwksResolver();
+
+    try {
+      const { payload } = await jose.jwtVerify(accessToken, jwks, {
+        issuer: issuerUrl,
+        audience: jwtAudience,
+        clockTolerance: 5
+      });
+
+      return {
+        status: "valid",
+        payload
+      };
+    } catch (error) {
+      return {
+        status: classifyJwtVerifyError(error)
+      };
+    }
+  }
+
+  async function verifyAccessTokenViaSupabase(accessToken) {
+    const supabase = getSupabaseClient();
+
+    try {
+      const response = await supabase.auth.getUser(accessToken);
+      if (response.error) {
+        if (isTransientSupabaseError(response.error)) {
+          return { status: "transient" };
+        }
+
+        return { status: "invalid" };
+      }
+
+      if (!response.data?.user) {
+        return { status: "invalid" };
+      }
+
+      const profile = await syncProfileFromSupabaseUser(response.data.user, response.data.user.email);
+      return {
+        status: "valid",
+        profile
+      };
+    } catch (error) {
+      if (isTransientSupabaseError(error)) {
+        return { status: "transient" };
+      }
+
+      return { status: "invalid" };
+    }
+  }
+
+  async function setSessionFromRequestCookies(request, options = {}) {
+    const cookies = safeRequestCookies(request);
+    const accessToken = String(cookies[ACCESS_TOKEN_COOKIE] || "").trim();
+    const refreshToken = String(cookies[REFRESH_TOKEN_COOKIE] || "").trim();
+
+    if (!accessToken || !refreshToken) {
+      throw new AppError(401, "Authentication required.");
+    }
+
+    const supabase = options.supabaseClient || getSupabaseClient();
+    let sessionResponse;
+    try {
+      sessionResponse = await supabase.auth.setSession({
+        access_token: accessToken,
+        refresh_token: refreshToken
+      });
+    } catch (error) {
+      throw mapRecoveryError(error);
+    }
+
+    const session = sessionResponse.data?.session || null;
+    const user = sessionResponse.data?.user || null;
+
+    if (sessionResponse.error || !session || !user) {
+      throw mapRecoveryError(sessionResponse.error);
+    }
+
+    return {
+      ...sessionResponse,
+      data: {
+        ...sessionResponse.data,
+        session,
+        user
+      }
+    };
+  }
+
+  async function resolveCurrentSupabaseUser(request, options = {}) {
+    const supabase = options.supabaseClient || getSupabaseClient();
+    const cookies = safeRequestCookies(request);
+    const accessToken = String(cookies[ACCESS_TOKEN_COOKIE] || "").trim();
+    let user = null;
+    let session = null;
+
+    async function getUserByAccessToken(token) {
+      if (!token) {
+        return null;
+      }
+
+      try {
+        const userResponse = await supabase.auth.getUser(token);
+        if (!userResponse.error && userResponse.data?.user) {
+          return userResponse.data.user;
+        }
+
+        if (userResponse.error && isTransientSupabaseError(userResponse.error)) {
+          throw mapAuthError(userResponse.error, 503);
+        }
+      } catch (error) {
+        if (isTransientSupabaseError(error)) {
+          throw mapAuthError(error, 503);
+        }
+      }
+
+      return null;
+    }
+
+    if (accessToken) {
+      user = await getUserByAccessToken(accessToken);
+    }
+
+    if (!user) {
+      const sessionResponse = await setSessionFromRequestCookies(request, {
+        supabaseClient: supabase
+      });
+      user = sessionResponse.data.user || null;
+      session = sessionResponse.data.session || null;
+    }
+
+    const currentAccessToken = String(session?.access_token || accessToken || "").trim();
+    const explicitUser = await getUserByAccessToken(currentAccessToken);
+    if (explicitUser) {
+      user = explicitUser;
+    }
+
+    if (!user) {
+      throw new AppError(401, "Authentication required.");
+    }
+
+    return {
+      session,
+      user
+    };
+  }
+
+  function writeSessionCookies(reply, session) {
+    const accessToken = String(session?.access_token || "");
+    const refreshToken = String(session?.refresh_token || "");
+    if (!accessToken || !refreshToken) {
+      return;
+    }
+
+    const sessionAccessMaxAge = Number.isFinite(Number(session?.expires_in)) ? Number(session.expires_in) : 3600;
+    const persistentCookieMaxAge = Math.max(Math.floor(sessionAccessMaxAge), PERSISTENT_SESSION_COOKIE_MAX_AGE_SECONDS);
+
+    reply.setCookie(ACCESS_TOKEN_COOKIE, accessToken, cookieOptions(isProduction, persistentCookieMaxAge));
+    reply.setCookie(REFRESH_TOKEN_COOKIE, refreshToken, cookieOptions(isProduction, persistentCookieMaxAge));
+  }
+
+  function clearSessionCookies(reply) {
+    const clearOptions = cookieOptions(isProduction, 0);
+    reply.clearCookie(ACCESS_TOKEN_COOKIE, clearOptions);
+    reply.clearCookie(REFRESH_TOKEN_COOKIE, clearOptions);
+  }
+
+  function requireSynchronizedProfile(profile) {
+    if (profile && Number.isFinite(Number(profile.id)) && String(profile.displayName || "").trim()) {
+      return profile;
+    }
+
+    throw new AppError(500, "Authentication profile synchronization failed. Please retry.");
+  }
+
+  function buildNormalizedIdentityKey(identityLike) {
+    const source = identityLike && typeof identityLike === "object" ? identityLike : {};
+    const authProvider = normalizeAuthProviderId(source.authProvider || authProviderId, {
+      fallback: authProviderId
+    });
+    const authProviderUserId = normalizeProviderUserId(source.authProviderUserId);
+
+    if (!authProviderUserId) {
+      throw new TypeError("Profile identity is missing required fields.");
+    }
+
+    return {
+      authProvider,
+      authProviderUserId
+    };
+  }
+
+  function buildNormalizedIdentityProfile(profileLike) {
+    const source = profileLike && typeof profileLike === "object" ? profileLike : {};
+    const identity = buildNormalizedIdentityKey(source);
+    const email = normalizeEmail(source.email || "");
+    const displayName = String(source.displayName || "").trim();
+
+    if (!email || !displayName) {
+      throw new TypeError("Profile identity is missing required fields.");
+    }
+
+    return {
+      authProvider: identity.authProvider,
+      authProviderUserId: identity.authProviderUserId,
+      email,
+      displayName
+    };
+  }
+
+  async function findProfileByIdentity(identityProfile, options = {}) {
+    const normalized = buildNormalizedIdentityKey(identityProfile);
+    return userProfileSyncService.findByIdentity(
+      {
+        authProvider: normalized.authProvider,
+        authProviderUserId: normalized.authProviderUserId
+      },
+      options
+    );
+  }
+
+  function getSettingsProfileAuthInfo() {
+    return {
+      emailManagedBy: settingsProfileAuthInfo.emailManagedBy,
+      emailChangeFlow: settingsProfileAuthInfo.emailChangeFlow
+    };
+  }
+
+  async function syncProfileMirror(nextProfile) {
+    try {
+      const normalized = buildNormalizedIdentityProfile(nextProfile);
+      const synchronizedProfile = await userProfileSyncService.syncIdentityProfile(normalized);
+      return requireSynchronizedProfile(synchronizedProfile);
+    } catch (error) {
+      if (String(error?.code || "") === USER_PROFILE_EMAIL_CONFLICT_CODE) {
+        throw new AppError(
+          409,
+          "This email is already registered with another sign-in method. Sign in with that method, then link this provider in Settings > Security."
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  async function syncProfileFromSupabaseUser(supabaseUser, fallbackEmail) {
+    const supabaseUserId = normalizeProviderUserId(supabaseUser?.id);
+    const email = normalizeEmail(supabaseUser?.email || fallbackEmail);
+
+    if (!supabaseUserId || !email) {
+      throw new AppError(500, "Auth provider user payload is missing required fields.");
+    }
+
+    return syncProfileMirror({
+      authProvider: authProviderId,
+      authProviderUserId: supabaseUserId,
+      email,
+      displayName: resolveDisplayName(supabaseUser, email)
+    });
+  }
+
+  async function syncProfileFromJwtClaims(claims) {
+    const supabaseUserId = normalizeProviderUserId(claims?.sub);
+    if (!supabaseUserId) {
+      throw new AppError(401, "Token is missing subject claim.");
+    }
+
+    const existing = await findProfileByIdentity({
+      authProvider: authProviderId,
+      authProviderUserId: supabaseUserId
+    });
+    const emailFromToken = normalizeEmail(claims?.email || "");
+
+    if (!emailFromToken) {
+      if (existing) {
+        return existing;
+      }
+      throw new AppError(401, "Token is missing email claim.");
+    }
+
+    return syncProfileMirror({
+      authProvider: authProviderId,
+      authProviderUserId: supabaseUserId,
+      email: emailFromToken,
+      displayName: resolveDisplayNameFromClaims(claims, emailFromToken)
+    });
+  }
+
+  async function resolvePasswordSignInPolicyForUserId(userId) {
+    if (!userSettingsRepository || typeof userSettingsRepository.ensureForUserId !== "function") {
+      return {
+        passwordSignInEnabled: true,
+        passwordSetupRequired: false
+      };
+    }
+
+    const settings = await userSettingsRepository.ensureForUserId(userId);
+    return {
+      passwordSignInEnabled: settings?.passwordSignInEnabled !== false,
+      passwordSetupRequired: settings?.passwordSetupRequired === true
+    };
+  }
+
+  async function setPasswordSignInEnabledForUserId(userId, enabled, options = {}) {
+    if (!userSettingsRepository || typeof userSettingsRepository.updatePasswordSignInEnabled !== "function") {
+      throw new AppError(500, "Password sign-in settings repository is not configured.");
+    }
+
+    const updated = await userSettingsRepository.updatePasswordSignInEnabled(userId, enabled, options);
+    return {
+      passwordSignInEnabled: updated.passwordSignInEnabled !== false,
+      passwordSetupRequired: updated.passwordSetupRequired === true
+    };
+  }
+
+  async function setPasswordSetupRequiredForUserId(userId, required) {
+    if (!userSettingsRepository || typeof userSettingsRepository.updatePasswordSetupRequired !== "function") {
+      return;
+    }
+
+    await userSettingsRepository.updatePasswordSetupRequired(userId, required);
+  }
+
+  async function resolveCurrentAuthContext(request, options = {}) {
+    const current = await resolveCurrentSupabaseUser(request, options);
+    const profile = await syncProfileFromSupabaseUser(current.user, current.user?.email || "");
+    const passwordSignInPolicy = await resolvePasswordSignInPolicyForUserId(profile.id);
+    const authMethodsStatus = buildAuthMethodsStatusFromSupabaseUser(current.user, {
+      ...passwordSignInPolicy,
+      oauthProviders: authOAuthProviders
+    });
+
+    return {
+      ...current,
+      profile,
+      passwordSignInEnabled: passwordSignInPolicy.passwordSignInEnabled,
+      passwordSetupRequired: passwordSignInPolicy.passwordSetupRequired,
+      authMethodsStatus
+    };
+  }
+
+  const { register, login, requestOtpLogin, verifyOtpLogin, updateDisplayName } = createAccountFlows({
+    ensureConfigured,
+    validators,
+    validationError,
+    getSupabaseClient,
+    displayNameFromEmail,
+    mapAuthError,
+    syncProfileFromSupabaseUser,
+    resolvePasswordSignInPolicyForUserId,
+    otpLoginRedirectUrl,
+    buildOtpLoginRedirectUrl,
+    appPublicUrl,
+    isTransientSupabaseError,
+    isUserNotFoundLikeAuthError,
+    parseOtpLoginVerifyPayload,
+    mapOtpVerifyError,
+    setSessionFromRequestCookies,
+    mapProfileUpdateError,
+    normalizeReturnToPath: normalizeAuthReturnToTarget
+  });
+
+  const { oauthStart, startProviderLink, oauthComplete, unlinkProvider } = createOauthFlows({
+    ensureConfigured,
+    normalizeOAuthProviderInput,
+    normalizeReturnToPath: normalizeAuthReturnToTarget,
+    buildOAuthLoginRedirectUrl: buildOAuthLoginRedirectUrlWithCatalog,
+    appPublicUrl,
+    authOAuthDefaultProvider,
+    resolveOAuthProviderQueryParams: resolveOAuthProviderQueryParamsForProvider,
+    getSupabaseClient,
+    mapAuthError,
+    setSessionFromRequestCookies,
+    buildOAuthLinkRedirectUrl: buildOAuthLinkRedirectUrlWithCatalog,
+    parseOAuthCompletePayload,
+    validationError,
+    mapOAuthCallbackError,
+    mapRecoveryError,
+    syncProfileFromSupabaseUser,
+    resolveCurrentAuthContext,
+    buildOAuthMethodId,
+    findAuthMethodById,
+    findLinkedIdentityByProvider,
+    buildSecurityStatusFromAuthMethodsStatus
+  });
+
+  const {
+    requestPasswordReset,
+    completePasswordRecovery,
+    resetPassword,
+    changePassword,
+    setPasswordSignInEnabled,
+    signOutOtherSessions,
+    getSecurityStatus
+  } = createPasswordSecurityFlows({
+    ensureConfigured,
+    validators,
+    validationError,
+    getSupabaseClient,
+    passwordResetRedirectUrl,
+    mapAuthError,
+    validatePasswordRecoveryPayload,
+    mapRecoveryError,
+    syncProfileFromSupabaseUser,
+    setSessionFromRequestCookies,
+    resolvePasswordSignInPolicyForUserId,
+    mapPasswordUpdateError,
+    setPasswordSetupRequiredForUserId,
+    normalizeEmail,
+    createStatelessSupabaseClient,
+    mapCurrentPasswordError,
+    resolveCurrentAuthContext,
+    findAuthMethodById,
+    authMethodPasswordId: AUTH_METHOD_PASSWORD_ID,
+    buildDisabledPasswordSecret,
+    setPasswordSignInEnabledForUserId,
+    buildAuthMethodsStatusFromSupabaseUser: (user, statusOptions = {}) =>
+      buildAuthMethodsStatusFromSupabaseUser(user, {
+        ...statusOptions,
+        oauthProviders: authOAuthProviders
+      }),
+    buildSecurityStatusFromAuthMethodsStatus,
+    authMethodPasswordProvider: AUTH_METHOD_PASSWORD_PROVIDER,
+    buildAuthMethodsStatusFromProviderIds: (providerIds, statusOptions = {}) =>
+      buildAuthMethodsStatusFromProviderIds(providerIds, {
+        ...statusOptions,
+        oauthProviders: authOAuthProviders
+      })
+  });
+
+  async function authenticateRequest(request) {
+    ensureConfigured();
+
+    const cookies = safeRequestCookies(request);
+    const accessToken = String(cookies[ACCESS_TOKEN_COOKIE] || "");
+    const refreshToken = String(cookies[REFRESH_TOKEN_COOKIE] || "");
+
+    if (!accessToken && !refreshToken) {
+      return {
+        authenticated: false,
+        clearSession: false,
+        session: null,
+        transientFailure: false
+      };
+    }
+
+    if (accessToken) {
+      const verification = await verifyAccessToken(accessToken);
+
+      if (verification.status === "valid") {
+        const profile = await syncProfileFromJwtClaims(verification.payload);
+        return {
+          authenticated: true,
+          profile,
+          clearSession: false,
+          session: null,
+          transientFailure: false
+        };
+      }
+
+      if (verification.status === "transient") {
+        return {
+          authenticated: false,
+          clearSession: false,
+          session: null,
+          transientFailure: true
+        };
+      }
+
+      if (verification.status === "invalid") {
+        const supabaseVerification = await verifyAccessTokenViaSupabase(accessToken);
+        if (supabaseVerification.status === "valid") {
+          return {
+            authenticated: true,
+            profile: supabaseVerification.profile,
+            clearSession: false,
+            session: null,
+            transientFailure: false
+          };
+        }
+
+        if (supabaseVerification.status === "transient") {
+          return {
+            authenticated: false,
+            clearSession: false,
+            session: null,
+            transientFailure: true
+          };
+        }
+      }
+    }
+
+    if (!refreshToken) {
+      return {
+        authenticated: false,
+        clearSession: true,
+        session: null,
+        transientFailure: false
+      };
+    }
+
+    const supabase = getSupabaseClient();
+    let refreshResponse;
+    try {
+      refreshResponse = await supabase.auth.refreshSession({ refresh_token: refreshToken });
+      /* c8 ignore next 17 -- defensive: refreshSession usually resolves with { error } for auth/transport issues. */
+    } catch (error) {
+      if (isTransientSupabaseError(error)) {
+        return {
+          authenticated: false,
+          clearSession: false,
+          session: null,
+          transientFailure: true
+        };
+      }
+
+      return {
+        authenticated: false,
+        clearSession: true,
+        session: null,
+        transientFailure: false
+      };
+    }
+
+    if (refreshResponse.error) {
+      if (isTransientSupabaseError(refreshResponse.error)) {
+        return {
+          authenticated: false,
+          clearSession: false,
+          session: null,
+          transientFailure: true
+        };
+      }
+
+      return {
+        authenticated: false,
+        clearSession: true,
+        session: null,
+        transientFailure: false
+      };
+    }
+
+    if (!refreshResponse.data?.session || !refreshResponse.data?.user) {
+      return {
+        authenticated: false,
+        clearSession: true,
+        session: null,
+        transientFailure: false
+      };
+    }
+
+    const profile = await syncProfileFromSupabaseUser(refreshResponse.data.user, refreshResponse.data.user.email);
+
+    return {
+      authenticated: true,
+      profile,
+      clearSession: false,
+      session: refreshResponse.data.session,
+      transientFailure: false
+    };
+  }
+
+  function hasAccessTokenCookie(request) {
+    const cookies = safeRequestCookies(request);
+    return Boolean(cookies[ACCESS_TOKEN_COOKIE]);
+  }
+
+  function hasSessionCookie(request) {
+    const cookies = safeRequestCookies(request);
+    return Boolean(cookies[ACCESS_TOKEN_COOKIE] || cookies[REFRESH_TOKEN_COOKIE]);
+  }
+
+  function getOAuthProviderCatalog() {
+    return authOAuthCatalogResponse;
+  }
+
+  return {
+    register,
+    login,
+    requestOtpLogin,
+    verifyOtpLogin,
+    oauthStart,
+    oauthComplete,
+    startProviderLink,
+    requestPasswordReset,
+    completePasswordRecovery,
+    resetPassword,
+    updateDisplayName,
+    changePassword,
+    setPasswordSignInEnabled,
+    unlinkProvider,
+    signOutOtherSessions,
+    getSecurityStatus,
+    getSettingsProfileAuthInfo,
+    getOAuthProviderCatalog,
+    authenticateRequest,
+    hasAccessTokenCookie,
+    hasSessionCookie,
+    writeSessionCookies,
+    clearSessionCookies
+  };
+}
+
+const __testables = {
+  validatePasswordRecoveryPayload,
+  displayNameFromEmail,
+  resolveDisplayName,
+  resolveDisplayNameFromClaims,
+  isTransientAuthMessage,
+  isTransientSupabaseError,
+  mapAuthError,
+  validationError,
+  isUserNotFoundLikeAuthError,
+  mapRecoveryError,
+  mapPasswordUpdateError,
+  mapOtpVerifyError,
+  mapProfileUpdateError,
+  mapCurrentPasswordError,
+  parseHttpUrl,
+  buildPasswordResetRedirectUrl,
+  buildOtpLoginRedirectUrl,
+  normalizeOAuthIntent,
+  normalizeReturnToPath,
+  buildOAuthRedirectUrl,
+  buildOAuthLoginRedirectUrl,
+  buildOAuthLinkRedirectUrl,
+  normalizeOAuthProviderInput: normalizeOAuthProviderInputFromCatalog,
+  parseOAuthCompletePayload: parseOAuthCompletePayloadFromCatalog,
+  parseOtpLoginVerifyPayload,
+  mapOAuthCallbackError,
+  resolveSupabaseOAuthProviderCatalog,
+  resolveOAuthProviderQueryParams,
+  buildOAuthProviderCatalogResponse,
+  normalizeIdentityProviderId,
+  collectProviderIdsFromSupabaseUser,
+  buildAuthMethodsStatusFromProviderIds,
+  buildAuthMethodsStatusFromSupabaseUser,
+  buildSecurityStatusFromAuthMethodsStatus,
+  findAuthMethodById,
+  findLinkedIdentityByProvider,
+  safeRequestCookies,
+  cookieOptions,
+  isExpiredJwtError,
+  classifyJwtVerifyError
+};
+
+export { createService, __testables };