@shellui/core 0.2.0 → 0.3.0-beta.0

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

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { getPreferredBackendProvider } from './getPreferredBackendProvider';
+
+describe('getPreferredBackendProvider', () => {
+  it('maps frontend aliases to backend provider ids', () => {
+    expect(getPreferredBackendProvider('x')).toBe('twitter');
+    expect(getPreferredBackendProvider('meta')).toBe('facebook');
+    expect(getPreferredBackendProvider('linkedin')).toBe('linkedin_oidc');
+  });
+
+  it('returns normalized provider for regular providers', () => {
+    expect(getPreferredBackendProvider('github')).toBe('github');
+    expect(getPreferredBackendProvider('Google')).toBe('google');
+  });
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Maps UI provider keys to the preferred backend provider identifier.
+ */
+export const getPreferredBackendProvider = (provider: string): string => {
+  const normalized = provider.toLowerCase();
+  if (normalized === 'x') return 'twitter';
+  if (normalized === 'meta') return 'facebook';
+  if (normalized === 'linkedin') return 'linkedin_oidc';
+  return normalized;
+};

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

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { getProviderVisual } from './getProviderVisual';
+
+describe('getProviderVisual', () => {
+  it('returns branded icon metadata for known providers', () => {
+    const apple = getProviderVisual('apple');
+    expect(apple.Icon).toBeTypeOf('function');
+    expect(apple.iconClassName).toContain('dark:text-white');
+    expect(apple.badgeClassName).toContain('bg-muted');
+
+    const github = getProviderVisual('github');
+    expect(github.Icon).toBeTypeOf('function');
+    expect(github.iconClassName).toContain('text-[#24292F]');
+
+    const linkedIn = getProviderVisual('linkedin_oidc');
+    expect(linkedIn.Icon).toBeTypeOf('function');
+    expect(linkedIn.iconClassName).toContain('text-[#0A66C2]');
+
+    const ethereum = getProviderVisual('ethereum');
+    expect(ethereum.Icon).toBeTypeOf('function');
+    expect(ethereum.iconClassName).toContain('text-[#627EEA]');
+  });
+
+  it('returns fallback visual for unknown providers', () => {
+    const fallback = getProviderVisual('custom');
+    expect(fallback.Icon).toBeTypeOf('function');
+    expect(fallback.iconClassName).toContain('text-primary');
+    expect(fallback.badgeClassName).toContain('bg-primary/10');
+  });
+});

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

@@ -0,0 +1,83 @@
+import type { IconType } from 'react-icons';
+import {
+  FaApple,
+  FaFacebook,
+  FaGithub,
+  FaGoogle,
+  FaLinkedinIn,
+  FaMicrosoft,
+  FaQuestion,
+  FaEthereum,
+  FaXTwitter,
+} from 'react-icons/fa6';
+
+export type ProviderVisual = {
+  Icon: IconType;
+  iconClassName: string;
+  badgeClassName: string;
+};
+
+/**
+ * Returns lightweight visual metadata used to style provider buttons.
+ */
+export const getProviderVisual = (provider: string): ProviderVisual => {
+  switch (provider.toLowerCase()) {
+    case 'apple':
+      return {
+        Icon: FaApple,
+        iconClassName: 'text-black dark:text-white',
+        badgeClassName: 'bg-muted',
+      };
+    case 'google':
+      return {
+        Icon: FaGoogle,
+        iconClassName: 'text-[#DB4437] dark:text-[#F28B82]',
+        badgeClassName: 'bg-[#DB4437]/10 dark:bg-[#DB4437]/20',
+      };
+    case 'github':
+      return {
+        Icon: FaGithub,
+        iconClassName: 'text-[#24292F] dark:text-white',
+        badgeClassName: 'bg-muted',
+      };
+    case 'microsoft':
+      return {
+        Icon: FaMicrosoft,
+        iconClassName: 'text-[#0078D4] dark:text-[#5BB8FF]',
+        badgeClassName: 'bg-[#0078D4]/10 dark:bg-[#0078D4]/20',
+      };
+    case 'meta':
+    case 'facebook':
+      return {
+        Icon: FaFacebook,
+        iconClassName: 'text-[#1877F2] dark:text-[#60A5FA]',
+        badgeClassName: 'bg-[#1877F2]/10 dark:bg-[#1877F2]/20',
+      };
+    case 'x':
+    case 'twitter':
+      return {
+        Icon: FaXTwitter,
+        iconClassName: 'text-black dark:text-white',
+        badgeClassName: 'bg-muted',
+      };
+    case 'linkedin':
+    case 'linkedin_oidc':
+      return {
+        Icon: FaLinkedinIn,
+        iconClassName: 'text-[#0A66C2] dark:text-[#60A5FA]',
+        badgeClassName: 'bg-[#0A66C2]/10 dark:bg-[#0A66C2]/20',
+      };
+    case 'ethereum':
+      return {
+        Icon: FaEthereum,
+        iconClassName: 'text-[#627EEA] dark:text-[#A5B4FC]',
+        badgeClassName: 'bg-[#627EEA]/10 dark:bg-[#627EEA]/20',
+      };
+    default:
+      return {
+        Icon: FaQuestion,
+        iconClassName: 'text-primary',
+        badgeClassName: 'bg-primary/10 dark:bg-primary/20',
+      };
+  }
+};

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

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@shellui/sdk', () => ({
+  shellui: {
+    initialSettings: null,
+  },
+}));
+
+import { shellui } from '@shellui/sdk';
+import { getAccessTokenFromSdkSettings, getUserFromSdkSettings } from './getUserFromSdkSettings';
+
+describe('getUserFromSdkSettings', () => {
+  it('returns null when sdk has no user', () => {
+    (shellui as { initialSettings: unknown }).initialSettings = null;
+    expect(getUserFromSdkSettings()).toBeNull();
+  });
+
+  it('returns user from sdk initial settings', () => {
+    (shellui as { initialSettings: unknown }).initialSettings = {
+      user: {
+        id: 'u1',
+        email: 'u1@example.com',
+      },
+      accessToken: 'jwt.from.initial.settings',
+    };
+    expect(getUserFromSdkSettings()).toEqual({
+      id: 'u1',
+      email: 'u1@example.com',
+    });
+    expect(getAccessTokenFromSdkSettings()).toBe('jwt.from.initial.settings');
+  });
+});

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

@@ -0,0 +1,13 @@
+import { shellui, type Settings, type SettingsUser } from '@shellui/sdk';
+
+// Retrieves the current user from ShellUI initial settings when available.
+export const getUserFromSdkSettings = (): SettingsUser | null => {
+  const initialSettings = shellui.initialSettings as Settings | null;
+  return initialSettings?.user ?? null;
+};
+
+// Retrieves the current access token from ShellUI initial settings when available.
+export const getAccessTokenFromSdkSettings = (): string | null => {
+  const initialSettings = shellui.initialSettings as Settings | null;
+  return initialSettings?.accessToken ?? null;
+};

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

@@ -0,0 +1,21 @@
+export {
+  getShellUILoginClientTimezone,
+  getShellUILoginCompanyId,
+  getShellUILoginDeviceId,
+} from './clientLoginContext';
+export { buildSessionFromParams } from './buildSessionFromParams';
+export { clearStoredAuthSession } from './clearStoredAuthSession';
+export { decodeJwtPayload } from './decodeJwtPayload';
+export { formatProviderLabel } from './formatProviderLabel';
+export { getAccessTokenFromSdkSettings, getUserFromSdkSettings } from './getUserFromSdkSettings';
+export { getOAuthProviderCandidates } from './getOAuthProviderCandidates';
+export { getPreferredBackendProvider } from './getPreferredBackendProvider';
+export { getProviderVisual } from './getProviderVisual';
+export { isLoginMethod } from './isLoginMethod';
+export { isSessionExpired } from './isSessionExpired';
+export { normalizeAuthSettings } from './normalizeAuthSettings';
+export { normalizeNextPath } from './normalizeNextPath';
+export { normalizeRedirectPath } from './normalizeRedirectPath';
+export { persistAuthSession } from './persistAuthSession';
+export { readStoredAuthSession } from './readStoredAuthSession';
+export { toAuthSessionFromSettingsUser } from './toAuthSessionFromSettingsUser';

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

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { isLoginMethod } from './isLoginMethod';
+
+describe('isLoginMethod', () => {
+  it('returns true for supported auth methods', () => {
+    expect(isLoginMethod('password')).toBe(true);
+    expect(isLoginMethod('oauth')).toBe(true);
+    expect(isLoginMethod('magic_link')).toBe(true);
+    expect(isLoginMethod('web3')).toBe(true);
+  });
+
+  it('returns false for unsupported values', () => {
+    expect(isLoginMethod('sms')).toBe(false);
+    expect(isLoginMethod(null)).toBe(false);
+    expect(isLoginMethod(undefined)).toBe(false);
+    expect(isLoginMethod(123)).toBe(false);
+  });
+});

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

@@ -0,0 +1,5 @@
+import type { LoginMethod } from '../types';
+
+// Checks whether a value is a supported auth login method.
+export const isLoginMethod = (value: unknown): value is LoginMethod =>
+  value === 'password' || value === 'oauth' || value === 'magic_link' || value === 'web3';

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

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+import { isSessionExpired } from './isSessionExpired';
+import type { AuthSession } from '../types';
+
+describe('isSessionExpired', () => {
+  it('returns false when session expires well in the future', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+    const now = Math.floor(Date.now() / 1000);
+    const session = { expiresAt: now + 120 } as AuthSession;
+    expect(isSessionExpired(session)).toBe(false);
+    vi.useRealTimers();
+  });
+
+  it('returns true when session is already expired or in grace window', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+    const now = Math.floor(Date.now() / 1000);
+    const nearExpirySession = { expiresAt: now + 20 } as AuthSession;
+    expect(isSessionExpired(nearExpirySession)).toBe(true);
+    vi.useRealTimers();
+  });
+});

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

@@ -0,0 +1,5 @@
+import type { AuthSession } from '../types';
+
+// Returns true when a session is already expired or about to expire.
+export const isSessionExpired = (session: AuthSession) =>
+  session.expiresAt <= Math.floor(Date.now() / 1000) + 30;

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeAuthSettings } from './normalizeAuthSettings';
+
+describe('normalizeAuthSettings', () => {
+  it('normalizes settings payload to supported methods and oauth providers', () => {
+    const payload = {
+      methods: ['password', 'oauth', 'unknown'],
+      external: {
+        github: true,
+        google: true,
+        email: true,
+      },
+      enable_magic_link: true,
+    };
+
+    const result = normalizeAuthSettings(payload);
+    expect(result.methods).toEqual(expect.arrayContaining(['password', 'oauth', 'magic_link']));
+    expect(result.oauthProviders).toEqual(expect.arrayContaining(['github', 'google']));
+    expect(result.oauthProviders).not.toContain('email');
+    expect(result.oauthClients).toEqual([]);
+  });
+
+  it('supports array payloads and handles invalid values', () => {
+    expect(normalizeAuthSettings([])).toEqual({
+      methods: [],
+      oauthProviders: [],
+      oauthClients: [],
+    });
+
+    const result = normalizeAuthSettings([{ loginMethod: 'both', oauth_provider: 'GitLab' }]);
+    expect(result.methods).toEqual(expect.arrayContaining(['password', 'oauth']));
+    expect(result.oauthProviders).toEqual(['gitlab']);
+  });
+
+  it('detects web3-enabled providers in settings payload', () => {
+    const payload = {
+      external: {
+        ethereum: true,
+      },
+    };
+    const result = normalizeAuthSettings(payload);
+    expect(result.methods).toEqual(expect.arrayContaining(['web3']));
+  });
+
+  it('parses oauthClients and unions provider list', () => {
+    const payload = {
+      methods: ['oauth'],
+      oauthClients: [
+        { id: 12, provider: 'GitHub', label: 'Production' },
+        { id: 14, provider: 'google', label: 'Staging' },
+      ],
+    };
+    const result = normalizeAuthSettings(payload);
+    expect(result.oauthClients).toEqual([
+      { id: 12, provider: 'github', label: 'Production' },
+      { id: 14, provider: 'google', label: 'Staging' },
+    ]);
+    expect(result.oauthProviders).toEqual(expect.arrayContaining(['github', 'google']));
+  });
+});

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

@@ -0,0 +1,71 @@
+import type { AuthSettings, LoginMethod } from '../types';
+import { isLoginMethod } from './isLoginMethod';
+
+const NON_OAUTH_EXTERNAL_PROVIDERS = new Set(['email', 'phone', 'sms']);
+const WEB3_EXTERNAL_PROVIDERS = new Set(['ethereum', 'solana', 'web3_ethereum', 'web3_solana']);
+
+// Normalizes auth settings payloads into supported login methods and providers.
+export const normalizeAuthSettings = (payload: unknown): AuthSettings => {
+  const record = Array.isArray(payload) ? payload[0] : payload;
+  if (!record || typeof record !== 'object') {
+    return { methods: [], oauthProviders: [], oauthClients: [] };
+  }
+
+  const obj = record as Record<string, unknown>;
+  const methodsFromArray = Array.isArray(obj.methods) ? obj.methods.filter(isLoginMethod) : [];
+  const methods = new Set<LoginMethod>(methodsFromArray);
+  const oauthProvidersSet = new Set<string>();
+  const oauthClients: AuthSettings['oauthClients'] = [];
+
+  if (isLoginMethod(obj.loginMethod)) methods.add(obj.loginMethod);
+  if (obj.loginMethod === 'both') {
+    methods.add('password');
+    methods.add('oauth');
+  }
+  if (obj.enable_password === true) methods.add('password');
+  if (obj.enable_oauth === true) methods.add('oauth');
+  if (obj.enable_magic_link === true) methods.add('magic_link');
+  if (obj.enable_web3 === true) methods.add('web3');
+
+  if (obj.external && typeof obj.external === 'object') {
+    const external = obj.external as Record<string, unknown>;
+    const enabledProviders = Object.entries(external)
+      .filter(([, enabled]) => enabled === true)
+      .map(([provider]) => provider);
+    if (enabledProviders.length > 0) methods.add('oauth');
+    enabledProviders
+      .filter((provider) => !NON_OAUTH_EXTERNAL_PROVIDERS.has(provider.toLowerCase()))
+      .forEach((provider) => oauthProvidersSet.add(provider.toLowerCase()));
+    if (enabledProviders.some((provider) => WEB3_EXTERNAL_PROVIDERS.has(provider.toLowerCase()))) {
+      methods.add('web3');
+    }
+    if (external.email === true || obj.disable_signup === false) methods.add('magic_link');
+  }
+
+  if (Array.isArray(obj.oauthProviders)) {
+    obj.oauthProviders
+      .filter((provider): provider is string => typeof provider === 'string')
+      .forEach((provider) => oauthProvidersSet.add(provider.toLowerCase()));
+  }
+  if (typeof obj.oauth_provider === 'string') {
+    oauthProvidersSet.add(obj.oauth_provider.toLowerCase());
+  }
+  if (Array.isArray(obj.oauthClients)) {
+    obj.oauthClients.forEach((row) => {
+      if (!row || typeof row !== 'object') return;
+      const item = row as Record<string, unknown>;
+      const id = Number(item.id);
+      const provider = typeof item.provider === 'string' ? item.provider.toLowerCase().trim() : '';
+      const label = typeof item.label === 'string' ? item.label.trim() : '';
+      if (!Number.isInteger(id) || id <= 0 || !provider || !label) return;
+      oauthClients.push({ id, provider, label });
+      oauthProvidersSet.add(provider);
+    });
+  }
+
+  return {
+    methods: Array.from(methods),
+    oauthProviders: Array.from(oauthProvidersSet),
+    oauthClients,
+  };
+};

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import urls from '../../../constants/urls';
+import { normalizeNextPath } from './normalizeNextPath';
+
+describe('normalizeNextPath', () => {
+  it('keeps valid absolute paths', () => {
+    expect(normalizeNextPath('/')).toBe('/');
+    expect(normalizeNextPath('/dashboard')).toBe('/dashboard');
+  });
+
+  it('rejects invalid or unsafe next paths', () => {
+    expect(normalizeNextPath(null)).toBeNull();
+    expect(normalizeNextPath('dashboard')).toBeNull();
+    expect(normalizeNextPath('//evil.example.com')).toBeNull();
+  });
+
+  it('rejects login route loops', () => {
+    expect(normalizeNextPath(urls.login)).toBeNull();
+    expect(normalizeNextPath(`${urls.login}?next=%2Fhome`)).toBeNull();
+  });
+});

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

@@ -0,0 +1,12 @@
+import urls from '../../../constants/urls';
+
+/**
+ * Sanitizes "next" redirect paths to prevent invalid or unsafe redirects.
+ */
+export const normalizeNextPath = (value: string | null): string | null => {
+  if (!value) return null;
+  if (!value.startsWith('/')) return null;
+  if (value.startsWith('//')) return null;
+  if (value === urls.login || value.startsWith(`${urls.login}?`)) return null;
+  return value;
+};

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

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeRedirectPath } from './normalizeRedirectPath';
+
+describe('normalizeRedirectPath', () => {
+  it('keeps absolute paths unchanged', () => {
+    expect(normalizeRedirectPath('/login')).toBe('/login');
+  });
+
+  it('prefixes relative paths with slash', () => {
+    expect(normalizeRedirectPath('login')).toBe('/login');
+  });
+});

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

@@ -0,0 +1,3 @@
+// Ensures auth redirect paths are absolute and start with a slash.
+export const normalizeRedirectPath = (redirectPath: string) =>
+  redirectPath.startsWith('/') ? redirectPath : `/${redirectPath}`;

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

@@ -0,0 +1,35 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { persistAuthSession } from './persistAuthSession';
+import type { AuthSession } from '../types';
+
+const createStorageMock = () => {
+  const data = new Map<string, string>();
+  return {
+    getItem: vi.fn((key: string) => data.get(key) ?? null),
+    setItem: vi.fn((key: string, value: string) => data.set(key, value)),
+    removeItem: vi.fn((key: string) => data.delete(key)),
+    clear: vi.fn(() => data.clear()),
+    key: vi.fn(() => null),
+    get length() {
+      return data.size;
+    },
+  } as unknown as Storage;
+};
+
+describe('persistAuthSession', () => {
+  beforeEach(() => {
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: createStorageMock(),
+    });
+  });
+
+  it('stores session under auth storage key', () => {
+    const session = { userId: '1' } as AuthSession;
+    persistAuthSession(session);
+    expect(localStorage.setItem).toHaveBeenCalledWith(
+      'shellui.auth.session',
+      JSON.stringify(session),
+    );
+  });
+});

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

@@ -0,0 +1,12 @@
+import type { AuthSession } from '../types';
+
+const AUTH_SESSION_STORAGE_KEY = 'shellui.auth.session';
+
+// Persists the current auth session to local storage for browser reload recovery.
+export const persistAuthSession = (session: AuthSession) => {
+  try {
+    localStorage.setItem(AUTH_SESSION_STORAGE_KEY, JSON.stringify(session));
+  } catch {
+    // Ignore storage errors (e.g. private mode); user can still continue in-memory.
+  }
+};

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

@@ -0,0 +1,34 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { readStoredAuthSession } from './readStoredAuthSession';
+
+const createStorageMock = (value: string | null) =>
+  ({
+    getItem: vi.fn(() => value),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+    clear: vi.fn(),
+    key: vi.fn(() => null),
+    length: 0,
+  }) as unknown as Storage;
+
+describe('readStoredAuthSession', () => {
+  beforeEach(() => {
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: createStorageMock(null),
+    });
+  });
+
+  it('returns null when there is no stored session', () => {
+    expect(readStoredAuthSession()).toBeNull();
+  });
+
+  it('parses and returns stored session data', () => {
+    const stored = JSON.stringify({ userId: 'u1', expiresAt: 123 });
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: createStorageMock(stored),
+    });
+    expect(readStoredAuthSession()).toEqual({ userId: 'u1', expiresAt: 123 });
+  });
+});

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

@@ -0,0 +1,14 @@
+import type { AuthSession } from '../types';
+
+const AUTH_SESSION_STORAGE_KEY = 'shellui.auth.session';
+
+// Reads a previously persisted auth session from local storage.
+export const readStoredAuthSession = (): AuthSession | null => {
+  try {
+    const raw = localStorage.getItem(AUTH_SESSION_STORAGE_KEY);
+    if (!raw) return null;
+    return JSON.parse(raw) as AuthSession;
+  } catch {
+    return null;
+  }
+};

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

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest';
+import { toAuthSessionFromSettingsUser } from './toAuthSessionFromSettingsUser';
+import type { SettingsUser } from '@shellui/sdk';
+
+const toBase64Url = (value: string): string => Buffer.from(value, 'utf8').toString('base64url');
+
+const shelluiJwtWithGroups = () => {
+  const payload = {
+    user_metadata: {
+      is_staff: true,
+      is_company_owner: true,
+      groups: ['team-a', 'team-b'],
+    },
+  };
+  return `header.${toBase64Url(JSON.stringify(payload))}.signature`;
+};
+
+describe('toAuthSessionFromSettingsUser', () => {
+  it('maps settings user fields into an auth session', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+
+    const settingsUser = {
+      id: 'user-1',
+      email: 'user@example.com',
+      name: 'Demo User',
+      profilePicture: 'https://example.com/avatar.png',
+      authProvider: 'google',
+    } as SettingsUser;
+
+    const session = toAuthSessionFromSettingsUser(settingsUser, 'jwt.example.token');
+    expect(session.userId).toBe('user-1');
+    expect(session.userEmail).toBe('user@example.com');
+    expect(session.userName).toBe('Demo User');
+    expect(session.userAvatarUrl).toBe('https://example.com/avatar.png');
+    expect(session.userIsStaff).toBe(false);
+    expect(session.userIsCompanyOwner).toBe(false);
+    expect(session.userGroups).toEqual([]);
+    expect(session.provider).toBe('google');
+    expect(session.tokenType).toBe('bearer');
+    expect(session.accessToken).toBe('jwt.example.token');
+    expect(session.refreshToken).toBe('');
+    expect(session.expiresAt).toBeGreaterThan(Math.floor(Date.now() / 1000));
+
+    vi.useRealTimers();
+  });
+
+  it('reads groups and staff from ShellUI JWT user_metadata when present', () => {
+    const settingsUser = {
+      id: 'user-1',
+      email: 'user@example.com',
+      name: 'Demo User',
+      profilePicture: null,
+      authProvider: 'github',
+    } as SettingsUser;
+
+    const session = toAuthSessionFromSettingsUser(settingsUser, shelluiJwtWithGroups());
+    expect(session.userIsStaff).toBe(true);
+    expect(session.userIsCompanyOwner).toBe(true);
+    expect(session.userGroups).toEqual(['team-a', 'team-b']);
+  });
+
+  it('prefers explicit settings user groups over JWT when both are set', () => {
+    const settingsUser = {
+      id: 'user-1',
+      email: 'user@example.com',
+      name: 'Demo User',
+      profilePicture: null,
+      authProvider: 'github',
+      groups: ['from-settings', 'alpha'],
+    } as SettingsUser;
+
+    const session = toAuthSessionFromSettingsUser(settingsUser, shelluiJwtWithGroups());
+    expect(session.userGroups).toEqual(['alpha', 'from-settings']);
+  });
+});