@shellui/core 0.2.0 → 0.3.0-beta.0

package/src/features/auth/components/OAuthCallbackView.tsx

@@ -0,0 +1,119 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+import urls from '../../../constants/urls';
+import { normalizeNextPath } from '../utils';
+import { useAuth } from '../hooks/useAuth';
+
+const toPositiveInt = (raw: string | null): number | undefined => {
+  if (!raw) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.trunc(n);
+};
+
+export const OAuthCallbackView = () => {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const { completeOAuthCallback, isAuthenticated } = useAuth();
+  const [localError, setLocalError] = useState<string | null>(null);
+  const [isWorking, setIsWorking] = useState(true);
+  const hasStartedRef = useRef(false);
+  const nextPath = useMemo(() => {
+    const params = new URLSearchParams(location.search);
+    return normalizeNextPath(params.get('next')) ?? '/';
+  }, [location.search]);
+
+  useEffect(() => {
+    if (!isAuthenticated) return;
+    navigate(nextPath, { replace: true });
+  }, [isAuthenticated, navigate, nextPath]);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (hasStartedRef.current || isAuthenticated) {
+      return () => {
+        cancelled = true;
+      };
+    }
+    hasStartedRef.current = true;
+    const run = async () => {
+      const params = new URLSearchParams(location.search);
+      const oauthError = params.get('error');
+      if (oauthError) {
+        if (!cancelled) {
+          setLocalError(oauthError);
+          setIsWorking(false);
+        }
+        return;
+      }
+      const code = params.get('code');
+      const provider = params.get('provider');
+      if (!code || !provider) {
+        if (!cancelled) {
+          setLocalError('Missing OAuth callback parameters.');
+          setIsWorking(false);
+        }
+        return;
+      }
+      const redirectUri = `${window.location.origin}${location.pathname}${location.search}`;
+      const ok = await completeOAuthCallback({
+        provider,
+        code,
+        redirectUri,
+        oauthClientId: toPositiveInt(params.get('company_oauth_client_id')),
+      });
+      if (cancelled) return;
+      if (!ok) {
+        setIsWorking(false);
+        return;
+      }
+      navigate(nextPath, { replace: true });
+    };
+    void run();
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    completeOAuthCallback,
+    isAuthenticated,
+    location.pathname,
+    location.search,
+    navigate,
+    nextPath,
+  ]);
+
+  const displayError = localError;
+  if (displayError) {
+    return (
+      <main className="flex min-h-full items-center justify-center px-6 py-10">
+        <div className="w-full max-w-lg space-y-3">
+          <h1 className="text-xl font-semibold tracking-tight text-foreground">
+            OAuth sign-in failed
+          </h1>
+          <p className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive">
+            {displayError}
+          </p>
+          <button
+            type="button"
+            className="text-sm text-primary underline-offset-4 hover:underline"
+            onClick={() =>
+              navigate(`${urls.login}?next=${encodeURIComponent(nextPath)}`, { replace: true })
+            }
+          >
+            Return to login
+          </button>
+        </div>
+      </main>
+    );
+  }
+
+  if (isWorking) {
+    return (
+      <main className="flex min-h-full items-center justify-center px-6 py-10">
+        <p className="text-sm text-muted-foreground">Completing sign-in...</p>
+      </main>
+    );
+  }
+
+  return null;
+};

package/src/features/auth/hooks/useAuth.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react';
+import type { AuthEvent, AuthSession, AuthSettings, AuthUser, UserPreferences } from '../types';
+
+export type { AuthSession, AuthUser } from '../types';
+
+export interface AuthContextValue {
+  session: AuthSession | null;
+  user: AuthUser | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  error: string | null;
+  authEvent: AuthEvent;
+  clearAuthEvent: () => void;
+  completeOAuthCallback: (params: {
+    provider: string;
+    code: string;
+    redirectUri: string;
+    oauthClientId?: number;
+  }) => Promise<boolean>;
+  startOAuth: (provider: string, redirectPath?: string, oauthClientId?: number) => boolean;
+  startWeb3Ethereum: () => Promise<boolean>;
+  getAuthSettings: () => Promise<AuthSettings>;
+  sendMagicLink: (email: string, redirectPath?: string) => Promise<void>;
+  syncUserPreferences: (preferences: UserPreferences) => Promise<void>;
+  loadUserPreferences: () => Promise<UserPreferences | null>;
+  logout: () => Promise<void>;
+}
+
+export const AuthContext = createContext<AuthContextValue | null>(null);
+
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within an AuthProvider.');
+  }
+  return context;
+};

package/src/features/auth/types.ts

@@ -0,0 +1,51 @@
+export interface AuthSession {
+  accessToken: string;
+  refreshToken: string;
+  tokenType: string;
+  expiresAt: number;
+  provider: string | null;
+  userId: string | null;
+  userEmail: string | null;
+  userName: string | null;
+  userAvatarUrl: string | null;
+  userIsStaff: boolean;
+  /** True when JWT `user_metadata.is_company_owner` is set for the active company (ShellUI auth). */
+  userIsCompanyOwner: boolean;
+  /** Sorted unique group names from JWT `user_metadata.groups` (ShellUI auth). */
+  userGroups: string[];
+  userPreferences?: UserPreferences | null;
+}
+
+export interface AuthUser {
+  id: string | null;
+  email: string | null;
+  name: string | null;
+  profilePicture: string | null;
+  isStaff: boolean;
+  /** Company owner for the JWT tenant (`user_metadata.is_company_owner`, ShellUI auth). */
+  isCompanyOwner: boolean;
+  authProvider: string | null;
+  /** Group names from the access token; empty if none or not a ShellUI JWT. */
+  groups: string[];
+}
+
+export type AuthEvent = 'oauth_callback' | null;
+
+export type LoginMethod = 'password' | 'oauth' | 'magic_link' | 'web3';
+
+export interface AuthSettings {
+  methods: LoginMethod[];
+  oauthProviders: string[];
+  oauthClients: Array<{
+    id: number;
+    provider: string;
+    label: string;
+  }>;
+}
+
+export type UserPreferences = {
+  themeName?: string;
+  language?: string;
+  region?: string;
+  colorScheme?: 'light' | 'dark' | 'system';
+};

package/src/features/auth/utils/buildSessionFromParams.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { buildSessionFromParams } from './buildSessionFromParams';
+
+const toBase64Url = (value: string): string => Buffer.from(value, 'utf8').toString('base64url');
+
+const createToken = () => {
+  const payload = {
+    sub: 'user-id',
+    email: 'user@example.com',
+    app_metadata: { provider: 'github' },
+    user_metadata: {
+      name: 'Jane',
+      avatar_url: 'https://example.com/avatar.png',
+      is_staff: true,
+      is_company_owner: true,
+      groups: ['editors', 'admin'],
+      shelluiPreferences: {
+        themeName: 'default',
+        language: 'fr',
+        region: 'Europe/Paris',
+        colorScheme: 'dark',
+      },
+    },
+  };
+  return `header.${toBase64Url(JSON.stringify(payload))}.signature`;
+};
+
+describe('buildSessionFromParams', () => {
+  it('returns session data when required params exist', () => {
+    const params = new URLSearchParams({
+      access_token: createToken(),
+      refresh_token: 'refresh-token',
+      expires_in: '3600',
+      token_type: 'bearer',
+    });
+
+    const session = buildSessionFromParams(params, 1_000);
+    expect(session).not.toBeNull();
+    expect(session?.refreshToken).toBe('refresh-token');
+    expect(session?.provider).toBe('github');
+    expect(session?.userId).toBe('user-id');
+    expect(session?.userEmail).toBe('user@example.com');
+    expect(session?.userName).toBe('Jane');
+    expect(session?.userAvatarUrl).toBe('https://example.com/avatar.png');
+    expect(session?.userIsStaff).toBe(true);
+    expect(session?.userIsCompanyOwner).toBe(true);
+    expect(session?.userPreferences).toEqual({
+      themeName: 'default',
+      language: 'fr',
+      region: 'Europe/Paris',
+      colorScheme: 'dark',
+    });
+    expect(session?.userGroups).toEqual(['admin', 'editors']);
+    expect(session?.expiresAt).toBe(4_600);
+  });
+
+  it('returns null when access or refresh token is missing', () => {
+    const params = new URLSearchParams({ access_token: 'a' });
+    expect(buildSessionFromParams(params, 1_000)).toBeNull();
+  });
+});

package/src/features/auth/utils/buildSessionFromParams.ts

@@ -0,0 +1,79 @@
+import type { AuthSession, UserPreferences } from '../types';
+import { decodeJwtPayload, normalizeJwtUserGroups } from './decodeJwtPayload';
+
+// Builds an AuthSession from callback or refresh URL parameters.
+export const buildSessionFromParams = (
+  params: URLSearchParams,
+  nowSeconds: number,
+): AuthSession | null => {
+  const accessToken = params.get('access_token');
+  const refreshToken = params.get('refresh_token');
+  if (!accessToken || !refreshToken) return null;
+
+  const expiresAtFromParam = Number(params.get('expires_at'));
+  const expiresInFromParam = Number(params.get('expires_in'));
+  const expiresAt =
+    Number.isFinite(expiresAtFromParam) && expiresAtFromParam > 0
+      ? expiresAtFromParam
+      : Number.isFinite(expiresInFromParam) && expiresInFromParam > 0
+        ? nowSeconds + expiresInFromParam
+        : nowSeconds + 3600;
+
+  const tokenType = params.get('token_type') ?? 'bearer';
+  const payload = decodeJwtPayload(accessToken);
+  const appMetadata =
+    payload?.app_metadata && typeof payload.app_metadata === 'object'
+      ? (payload.app_metadata as Record<string, unknown>)
+      : null;
+  const userMetadata =
+    payload?.user_metadata && typeof payload.user_metadata === 'object'
+      ? (payload.user_metadata as Record<string, unknown>)
+      : null;
+  const rawPreferences =
+    userMetadata?.shelluiPreferences && typeof userMetadata.shelluiPreferences === 'object'
+      ? (userMetadata.shelluiPreferences as Record<string, unknown>)
+      : null;
+  const preferences: UserPreferences | null = rawPreferences
+    ? {
+        ...(typeof rawPreferences.themeName === 'string'
+          ? { themeName: rawPreferences.themeName }
+          : {}),
+        ...(rawPreferences.language === 'en' || rawPreferences.language === 'fr'
+          ? { language: rawPreferences.language as 'en' | 'fr' }
+          : {}),
+        ...(typeof rawPreferences.region === 'string' ? { region: rawPreferences.region } : {}),
+        ...(rawPreferences.colorScheme === 'light' ||
+        rawPreferences.colorScheme === 'dark' ||
+        rawPreferences.colorScheme === 'system'
+          ? { colorScheme: rawPreferences.colorScheme as 'light' | 'dark' | 'system' }
+          : {}),
+      }
+    : null;
+  const userId =
+    typeof payload?.sub === 'string'
+      ? payload.sub
+      : typeof payload?.user_id === 'string'
+        ? payload.user_id
+        : null;
+
+  return {
+    accessToken,
+    refreshToken,
+    tokenType,
+    expiresAt,
+    provider: typeof appMetadata?.provider === 'string' ? appMetadata.provider : null,
+    userId,
+    userEmail: typeof payload?.email === 'string' ? payload.email : null,
+    userName:
+      typeof userMetadata?.full_name === 'string'
+        ? userMetadata.full_name
+        : typeof userMetadata?.name === 'string'
+          ? userMetadata.name
+          : null,
+    userAvatarUrl: typeof userMetadata?.avatar_url === 'string' ? userMetadata.avatar_url : null,
+    userIsStaff: userMetadata?.is_staff === true,
+    userIsCompanyOwner: userMetadata?.is_company_owner === true,
+    userPreferences: preferences,
+    userGroups: normalizeJwtUserGroups(userMetadata?.groups),
+  };
+};

package/src/features/auth/utils/clearStoredAuthSession.spec.ts

@@ -0,0 +1,23 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { clearStoredAuthSession } from './clearStoredAuthSession';
+
+describe('clearStoredAuthSession', () => {
+  beforeEach(() => {
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: {
+        getItem: vi.fn(),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+        key: vi.fn(() => null),
+        length: 0,
+      } as unknown as Storage,
+    });
+  });
+
+  it('removes auth session from storage', () => {
+    clearStoredAuthSession();
+    expect(localStorage.removeItem).toHaveBeenCalledWith('shellui.auth.session');
+  });
+});

package/src/features/auth/utils/clearStoredAuthSession.ts

@@ -0,0 +1,10 @@
+const AUTH_SESSION_STORAGE_KEY = 'shellui.auth.session';
+
+// Removes the persisted auth session from local storage.
+export const clearStoredAuthSession = () => {
+  try {
+    localStorage.removeItem(AUTH_SESSION_STORAGE_KEY);
+  } catch {
+    // Ignore storage errors.
+  }
+};

package/src/features/auth/utils/clientLoginContext.spec.ts

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getShellUILoginClientTimezone, getShellUILoginDeviceId } from './clientLoginContext';
+
+const createStorageMock = (store: Record<string, string>) =>
+  ({
+    getItem: vi.fn((k: string) => store[k] ?? null),
+    setItem: vi.fn((k: string, v: string) => {
+      store[k] = v;
+    }),
+    removeItem: vi.fn((k: string) => {
+      delete store[k];
+    }),
+    clear: vi.fn(() => {
+      for (const k of Object.keys(store)) delete store[k];
+    }),
+    key: vi.fn(() => null),
+    length: 0,
+  }) as unknown as Storage;
+
+describe('getShellUILoginClientTimezone', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('returns empty string on invalid or unknown timezone', () => {
+    vi.stubGlobal('window', {});
+    vi.spyOn(Intl, 'DateTimeFormat').mockImplementation(
+      () =>
+        ({
+          resolvedOptions: () => ({ timeZone: 'not a/valid zone!' }),
+        }) as Intl.DateTimeFormat,
+    );
+    expect(getShellUILoginClientTimezone()).toBe('');
+  });
+
+  it('returns normalized IANA id when valid', () => {
+    vi.stubGlobal('window', {});
+    vi.spyOn(Intl, 'DateTimeFormat').mockImplementation(
+      () =>
+        ({
+          resolvedOptions: () => ({ timeZone: 'Europe/Paris' }),
+        }) as Intl.DateTimeFormat,
+    );
+    expect(getShellUILoginClientTimezone()).toBe('Europe/Paris');
+  });
+});
+
+describe('getShellUILoginDeviceId', () => {
+  const originalCrypto = globalThis.crypto;
+
+  beforeEach(() => {
+    Object.defineProperty(globalThis, 'crypto', {
+      configurable: true,
+      value: { randomUUID: () => '11111111-2222-3333-4444-555555555555' },
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'crypto', {
+      configurable: true,
+      value: originalCrypto,
+    });
+    vi.unstubAllGlobals();
+  });
+
+  it('persists and returns a new id when missing', () => {
+    const store: Record<string, string> = {};
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('localStorage', createStorageMock(store));
+    expect(getShellUILoginDeviceId()).toBe('11111111-2222-3333-4444-555555555555');
+    expect(store.shellui_auth_client_device_id).toBe('11111111-2222-3333-4444-555555555555');
+  });
+
+  it('reuses stored id when present', () => {
+    const store: Record<string, string> = {
+      shellui_auth_client_device_id: 'existing-id',
+    };
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('localStorage', createStorageMock(store));
+    expect(getShellUILoginDeviceId()).toBe('existing-id');
+  });
+});

package/src/features/auth/utils/clientLoginContext.ts

@@ -0,0 +1,89 @@
+/**
+ * Client hints for shellui-auth login audit (`/api/v1/authorize` query params).
+ * Must stay aligned with shellui-auth `normalize_client_timezone` / device id limits.
+ */
+
+const DEVICE_ID_STORAGE_KEY = 'shellui_auth_client_device_id';
+const COMPANY_ID_STORAGE_KEY = 'shellui_auth_company_id';
+
+const IANA_TZ_RE = /^[A-Za-z0-9_+/\-]{1,64}$/;
+
+/**
+ * IANA timezone from the browser (coarse hint only), or '' when unavailable/invalid.
+ */
+export function getShellUILoginClientTimezone(): string {
+  if (typeof window === 'undefined') {
+    return '';
+  }
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (!tz || typeof tz !== 'string') {
+      return '';
+    }
+    const s = tz.trim();
+    if (!s || s.length > 64 || !IANA_TZ_RE.test(s)) {
+      return '';
+    }
+    return s;
+  } catch {
+    return '';
+  }
+}
+
+function newDeviceId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 18)}`;
+}
+
+/**
+ * Stable first-party id (UUID) in localStorage, max 128 chars, or '' when unavailable.
+ */
+export function getShellUILoginDeviceId(): string {
+  if (typeof window === 'undefined') {
+    return '';
+  }
+  try {
+    const existing = localStorage.getItem(DEVICE_ID_STORAGE_KEY);
+    if (existing) {
+      const trimmed = existing.trim();
+      if (trimmed && trimmed.length <= 128) {
+        return trimmed;
+      }
+    }
+    let created = newDeviceId();
+    if (created.length > 128) {
+      created = created.slice(0, 128);
+    }
+    localStorage.setItem(DEVICE_ID_STORAGE_KEY, created);
+    return created;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Preferred company id for tenant-scoped auth calls.
+ * Uses localStorage value first; if missing, persists and returns the configured fallback.
+ */
+export function getShellUILoginCompanyId(fallbackCompanyId?: string | number): string {
+  const fallback = `${fallbackCompanyId ?? ''}`.trim();
+  const validFallback = fallback && /^\d+$/.test(fallback) ? fallback : '';
+  if (typeof window === 'undefined') {
+    return validFallback;
+  }
+  try {
+    const stored = localStorage.getItem(COMPANY_ID_STORAGE_KEY)?.trim() ?? '';
+    if (stored && /^\d+$/.test(stored)) {
+      return stored;
+    }
+    if (validFallback) {
+      localStorage.setItem(COMPANY_ID_STORAGE_KEY, validFallback);
+      return validFallback;
+    }
+  } catch {
+    return validFallback;
+  }
+  return '';
+}

package/src/features/auth/utils/decodeJwtPayload.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { decodeJwtPayload } from './decodeJwtPayload';
+
+const toBase64Url = (value: string): string => Buffer.from(value, 'utf8').toString('base64url');
+
+describe('decodeJwtPayload', () => {
+  it('decodes payload from a valid JWT token', () => {
+    const payload = { sub: 'user-1', email: 'demo@example.com' };
+    const token = `header.${toBase64Url(JSON.stringify(payload))}.signature`;
+    expect(decodeJwtPayload(token)).toEqual(payload);
+  });
+
+  it('returns null for invalid tokens', () => {
+    expect(decodeJwtPayload('invalid-token')).toBeNull();
+    expect(decodeJwtPayload('header.badpayload.signature')).toBeNull();
+  });
+});

package/src/features/auth/utils/decodeJwtPayload.ts

@@ -0,0 +1,24 @@
+// Decodes a JWT payload section into a plain object.
+export const decodeJwtPayload = (token: string): Record<string, unknown> | null => {
+  try {
+    const payloadPart = token.split('.')[1];
+    if (!payloadPart) return null;
+    const base64 = payloadPart.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    const json = new TextDecoder('utf-8').decode(bytes);
+    return JSON.parse(json) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+};
+
+/** Normalizes `user_metadata.groups` from a ShellUI auth JWT to sorted unique names. */
+export const normalizeJwtUserGroups = (raw: unknown): string[] => {
+  if (!Array.isArray(raw)) return [];
+  const names = raw
+    .filter((item): item is string => typeof item === 'string' && item.trim().length > 0)
+    .map((n) => n.trim());
+  return [...new Set(names)].sort((a, b) => a.localeCompare(b));
+};

package/src/features/auth/utils/formatProviderLabel.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { formatProviderLabel } from './formatProviderLabel';
+
+describe('formatProviderLabel', () => {
+  it('formats known provider aliases', () => {
+    expect(formatProviderLabel('github')).toBe('GitHub');
+    expect(formatProviderLabel('twitter')).toBe('X');
+    expect(formatProviderLabel('x')).toBe('X');
+    expect(formatProviderLabel('facebook')).toBe('Meta');
+    expect(formatProviderLabel('meta')).toBe('Meta');
+    expect(formatProviderLabel('linkedin')).toBe('LinkedIn');
+    expect(formatProviderLabel('linkedin_oidc')).toBe('LinkedIn');
+  });
+
+  it('capitalizes unknown providers', () => {
+    expect(formatProviderLabel('google')).toBe('Google');
+    expect(formatProviderLabel('apple')).toBe('Apple');
+  });
+});

package/src/features/auth/utils/formatProviderLabel.ts

@@ -0,0 +1,11 @@
+/**
+ * Converts an OAuth provider key into a user-facing display label.
+ */
+export const formatProviderLabel = (provider: string): string => {
+  const key = provider.toLowerCase();
+  if (key === 'github') return 'GitHub';
+  if (key === 'x' || key === 'twitter') return 'X';
+  if (key === 'meta' || key === 'facebook') return 'Meta';
+  if (key === 'linkedin' || key === 'linkedin_oidc') return 'LinkedIn';
+  return provider.charAt(0).toUpperCase() + provider.slice(1);
+};

package/src/features/auth/utils/getOAuthProviderCandidates.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { getOAuthProviderCandidates } from './getOAuthProviderCandidates';
+
+describe('getOAuthProviderCandidates', () => {
+  it('returns aliases for supported provider families', () => {
+    expect(getOAuthProviderCandidates('x')).toEqual(['x', 'twitter']);
+    expect(getOAuthProviderCandidates('twitter')).toEqual(['twitter', 'x']);
+    expect(getOAuthProviderCandidates('meta')).toEqual(['meta', 'facebook']);
+    expect(getOAuthProviderCandidates('linkedin')).toEqual(['linkedin', 'linkedin_oidc']);
+  });
+
+  it('returns a normalized single candidate for unknown providers', () => {
+    expect(getOAuthProviderCandidates('GitHub')).toEqual(['github']);
+    expect(getOAuthProviderCandidates('google')).toEqual(['google']);
+  });
+});

package/src/features/auth/utils/getOAuthProviderCandidates.ts

@@ -0,0 +1,15 @@
+/**
+ * Expands a provider key into canonical aliases accepted by different backends.
+ */
+export const getOAuthProviderCandidates = (provider: string): string[] => {
+  const normalized = provider.toLowerCase();
+  const aliases: Record<string, string[]> = {
+    x: ['x', 'twitter'],
+    twitter: ['twitter', 'x'],
+    meta: ['meta', 'facebook'],
+    facebook: ['facebook', 'meta'],
+    linkedin: ['linkedin', 'linkedin_oidc'],
+    linkedin_oidc: ['linkedin_oidc', 'linkedin'],
+  };
+  return aliases[normalized] ?? [normalized];
+};