@oxy.so/core 1.0.0

package/src/utils/__tests__/languageUtils.test.ts

@@ -0,0 +1,219 @@
+import {
+  SUPPORTED_LANGUAGES,
+  getBaseLanguage,
+  normalizeLocale,
+  isSupportedLocale,
+  getLanguageMetadata,
+  getLanguageName,
+  getNativeLanguageName,
+  isRTLLocale,
+  getUserLanguages,
+  getPrimaryLanguage,
+} from '../languageUtils';
+
+describe('getBaseLanguage', () => {
+  it('extracts the base subtag from a full locale, lowercased', () => {
+    expect(getBaseLanguage('es-ES')).toBe('es');
+    expect(getBaseLanguage('EN-us')).toBe('en');
+  });
+
+  it('is tolerant of a bare base subtag', () => {
+    expect(getBaseLanguage('es')).toBe('es');
+    expect(getBaseLanguage('ES')).toBe('es');
+  });
+
+  it('ignores script/variant subtags', () => {
+    expect(getBaseLanguage('zh-Hant-TW')).toBe('zh');
+  });
+
+  it('trims surrounding whitespace and handles empty input', () => {
+    expect(getBaseLanguage('  fr-FR ')).toBe('fr');
+    expect(getBaseLanguage('')).toBe('');
+  });
+});
+
+describe('normalizeLocale', () => {
+  it('canonicalizes case: lowercase base, uppercase region', () => {
+    expect(normalizeLocale('es-es')).toBe('es-ES');
+    expect(normalizeLocale('EN-us')).toBe('en-US');
+    expect(normalizeLocale('PT-br')).toBe('pt-BR');
+  });
+
+  it('returns already-canonical supported locales unchanged', () => {
+    expect(normalizeLocale('es-MX')).toBe('es-MX');
+    expect(normalizeLocale('zh-TW')).toBe('zh-TW');
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(normalizeLocale('  fr-CA  ')).toBe('fr-CA');
+  });
+
+  it('collapses extra subtags to language-REGION', () => {
+    expect(normalizeLocale('zh-Hant-TW')).toBe('zh-TW');
+  });
+
+  it('returns undefined for a bare base subtag (no region)', () => {
+    expect(normalizeLocale('es')).toBeUndefined();
+    expect(normalizeLocale('en')).toBeUndefined();
+  });
+
+  it('returns undefined for unsupported locales', () => {
+    expect(normalizeLocale('xx-ZZ')).toBeUndefined();
+    expect(normalizeLocale('es-ZZ')).toBeUndefined();
+  });
+
+  it('returns undefined for empty or whitespace input', () => {
+    expect(normalizeLocale('')).toBeUndefined();
+    expect(normalizeLocale('   ')).toBeUndefined();
+  });
+});
+
+describe('isSupportedLocale', () => {
+  it('is true for supported locales in any case', () => {
+    expect(isSupportedLocale('es-ES')).toBe(true);
+    expect(isSupportedLocale('es-es')).toBe(true);
+  });
+
+  it('is false for bare subtags and unknown locales', () => {
+    expect(isSupportedLocale('es')).toBe(false);
+    expect(isSupportedLocale('xx-ZZ')).toBe(false);
+    expect(isSupportedLocale('')).toBe(false);
+  });
+});
+
+describe('getLanguageMetadata', () => {
+  it('resolves a supported locale to its catalog entry', () => {
+    const entry = getLanguageMetadata('es-mx');
+    expect(entry).not.toBeNull();
+    expect(entry?.code).toBe('es-MX');
+    expect(entry?.language).toBe('es');
+    expect(entry?.region).toBe('MX');
+  });
+
+  it('returns null for bare, unknown, or empty codes', () => {
+    expect(getLanguageMetadata('es')).toBeNull();
+    expect(getLanguageMetadata('xx-ZZ')).toBeNull();
+    expect(getLanguageMetadata('')).toBeNull();
+    expect(getLanguageMetadata(null)).toBeNull();
+    expect(getLanguageMetadata(undefined)).toBeNull();
+  });
+});
+
+describe('getLanguageName / getNativeLanguageName', () => {
+  it('returns the English and native display names for a supported locale', () => {
+    expect(getLanguageName('es-ES')).toBe('Spanish (Spain)');
+    expect(getNativeLanguageName('es-ES')).toBe('Español (España)');
+  });
+
+  it('falls back to the input tag for unsupported locales', () => {
+    expect(getLanguageName('xx-ZZ')).toBe('xx-ZZ');
+    expect(getNativeLanguageName('xx-ZZ')).toBe('xx-ZZ');
+  });
+
+  it('falls back to the fallback locale for empty input', () => {
+    expect(getLanguageName('')).toBe('en-US');
+    expect(getNativeLanguageName(null)).toBe('en-US');
+  });
+});
+
+describe('isRTLLocale', () => {
+  it('is true for right-to-left locales and their base subtags', () => {
+    expect(isRTLLocale('ar-SA')).toBe(true);
+    expect(isRTLLocale('he-IL')).toBe(true);
+    expect(isRTLLocale('fa')).toBe(true);
+    expect(isRTLLocale('ur-PK')).toBe(true);
+  });
+
+  it('is false for left-to-right locales and empty input', () => {
+    expect(isRTLLocale('en-US')).toBe(false);
+    expect(isRTLLocale('es-ES')).toBe(false);
+    expect(isRTLLocale(null)).toBe(false);
+    expect(isRTLLocale(undefined)).toBe(false);
+  });
+});
+
+describe('getUserLanguages', () => {
+  it('normalizes and validates the plural array, preserving order', () => {
+    expect(getUserLanguages({ languages: ['es-es', 'EN-us', 'pt-BR'] })).toEqual([
+      'es-ES',
+      'en-US',
+      'pt-BR',
+    ]);
+  });
+
+  it('drops unsupported locales and bare subtags', () => {
+    expect(getUserLanguages({ languages: ['es-ES', 'xx-ZZ', 'en'] })).toEqual(['es-ES']);
+  });
+
+  it('de-duplicates after normalization, keeping first-seen order', () => {
+    expect(getUserLanguages({ languages: ['es-ES', 'es-es', 'en-US', 'ES-es'] })).toEqual([
+      'es-ES',
+      'en-US',
+    ]);
+  });
+
+  it('ignores non-string junk entries without throwing', () => {
+    const languages = ['es-ES', 42, null, undefined, {}, 'en-US'] as unknown as string[];
+    expect(getUserLanguages({ languages })).toEqual(['es-ES', 'en-US']);
+  });
+
+  it('returns an empty array when languages is absent, empty, or non-array', () => {
+    expect(getUserLanguages({})).toEqual([]);
+    expect(getUserLanguages({ languages: [] })).toEqual([]);
+    expect(getUserLanguages({ languages: undefined })).toEqual([]);
+    expect(getUserLanguages(null)).toEqual([]);
+    expect(getUserLanguages(undefined)).toEqual([]);
+  });
+
+  it('ignores any stray singular language field (removed from User)', () => {
+    const strayLanguage: { language: string; languages?: string[] } = { language: 'es-ES' };
+    expect(getUserLanguages(strayLanguage)).toEqual([]);
+  });
+});
+
+describe('getPrimaryLanguage', () => {
+  it('returns the first normalized locale from the plural array', () => {
+    expect(getPrimaryLanguage({ languages: ['es-es', 'en-US'] })).toBe('es-ES');
+  });
+
+  it('skips leading unsupported entries', () => {
+    expect(getPrimaryLanguage({ languages: ['xx-ZZ', 'pt-br'] })).toBe('pt-BR');
+  });
+
+  it('returns undefined when the user has no supported locale', () => {
+    expect(getPrimaryLanguage({})).toBeUndefined();
+    expect(getPrimaryLanguage({ languages: ['xx-ZZ'] })).toBeUndefined();
+    expect(getPrimaryLanguage(null)).toBeUndefined();
+  });
+});
+
+describe('SUPPORTED_LANGUAGES catalog integrity', () => {
+  it('is non-empty', () => {
+    expect(SUPPORTED_LANGUAGES.length).toBeGreaterThan(0);
+  });
+
+  it('has no duplicate codes', () => {
+    const codes = SUPPORTED_LANGUAGES.map((entry) => entry.code);
+    expect(new Set(codes).size).toBe(codes.length);
+  });
+
+  it('every entry is internally consistent', () => {
+    for (const entry of SUPPORTED_LANGUAGES) {
+      // code is canonical language-REGION derived from its subtags
+      expect(entry.code).toBe(`${entry.language}-${entry.region}`);
+      // base subtag is lowercase, region is uppercase
+      expect(entry.language).toBe(entry.language.toLowerCase());
+      expect(entry.region).toBe(entry.region.toUpperCase());
+      // parsing the code recovers the subtags
+      expect(getBaseLanguage(entry.code)).toBe(entry.language);
+      // the code round-trips through normalization
+      expect(normalizeLocale(entry.code)).toBe(entry.code);
+      expect(isSupportedLocale(entry.code)).toBe(true);
+      // display names are present
+      expect(entry.name.length).toBeGreaterThan(0);
+      expect(entry.nativeName.length).toBeGreaterThan(0);
+      // rtl flag agrees with the RTL detector
+      expect(isRTLLocale(entry.code)).toBe(entry.rtl === true);
+    }
+  });
+});

package/src/utils/__tests__/oauthPkce.test.ts

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import {
+  buildOAuthAuthorizeUrl,
+  canonicalizeOAuthRedirectUri,
+  computeCodeChallenge,
+  DEFAULT_OAUTH_SCOPE,
+  generateOAuthState,
+  generatePkcePair,
+  OXY_AUTHORIZE_URL,
+  OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
+  OXY_OAUTH_RETURN_PATH_STORAGE_KEY,
+  clearOAuthHandshake,
+  consumeOAuthReturnPath,
+  persistOAuthHandshake,
+  persistOAuthReturnPath,
+  readOAuthHandshake,
+} from '../oauthPkce';
+
+/** RFC 7636 unreserved subset produced by base64url (no `+`, `/`, `=`). */
+const BASE64URL_RE = /^[A-Za-z0-9\-_]+$/;
+
+/** Independent base64url(SHA-256(input)) via Node crypto for cross-checking. */
+function nodeCodeChallenge(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+describe('computeCodeChallenge', () => {
+  it('matches the RFC 7636 Appendix B known-answer vector', async () => {
+    // From RFC 7636 §Appendix B: verifier -> S256 challenge.
+    const verifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
+    const expected = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
+    await expect(computeCodeChallenge(verifier)).resolves.toBe(expected);
+  });
+
+  it('produces unpadded base64url (no +, /, or = characters)', async () => {
+    const challenge = await computeCodeChallenge('some-arbitrary-code-verifier-value-123');
+    expect(challenge).toMatch(BASE64URL_RE);
+    expect(challenge).not.toContain('=');
+  });
+
+  it('agrees with an independent Node crypto implementation', async () => {
+    const verifier = 'another_verifier-value.with~allowed_chars-0123456789';
+    await expect(computeCodeChallenge(verifier)).resolves.toBe(nodeCodeChallenge(verifier));
+  });
+
+  it('encodes the full 32-byte SHA-256 digest as 43 base64url chars', async () => {
+    const challenge = await computeCodeChallenge('x');
+    expect(challenge).toHaveLength(43);
+  });
+});
+
+describe('generatePkcePair', () => {
+  it('returns a verifier, challenge, and S256 method', async () => {
+    const pair = await generatePkcePair();
+    expect(pair.method).toBe('S256');
+    expect(typeof pair.codeVerifier).toBe('string');
+    expect(typeof pair.codeChallenge).toBe('string');
+  });
+
+  it('produces a verifier in the RFC 7636 length range with only unreserved chars', async () => {
+    const { codeVerifier } = await generatePkcePair();
+    expect(codeVerifier).toMatch(BASE64URL_RE);
+    expect(codeVerifier.length).toBeGreaterThanOrEqual(43);
+    expect(codeVerifier.length).toBeLessThanOrEqual(128);
+  });
+
+  it('derives the challenge as base64url(SHA-256(verifier))', async () => {
+    const { codeVerifier, codeChallenge } = await generatePkcePair();
+    await expect(computeCodeChallenge(codeVerifier)).resolves.toBe(codeChallenge);
+    expect(codeChallenge).toBe(nodeCodeChallenge(codeVerifier));
+  });
+
+  it('generates a fresh, unpredictable verifier on each call', async () => {
+    const [a, b] = await Promise.all([generatePkcePair(), generatePkcePair()]);
+    expect(a.codeVerifier).not.toBe(b.codeVerifier);
+    expect(a.codeChallenge).not.toBe(b.codeChallenge);
+  });
+});
+
+describe('generateOAuthState', () => {
+  it('returns an unreserved base64url token of 32 random bytes (43 chars)', async () => {
+    const state = await generateOAuthState();
+    expect(state).toMatch(BASE64URL_RE);
+    expect(state).toHaveLength(43);
+  });
+
+  it('is unique across calls', async () => {
+    const [a, b] = await Promise.all([generateOAuthState(), generateOAuthState()]);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('buildOAuthAuthorizeUrl', () => {
+  const base = {
+    clientId: 'oxy_dk_example',
+    redirectUri: 'https://merchant.co/auth/callback',
+    state: 'csrf-state-token',
+    codeChallenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM',
+  };
+
+  it('defaults to the Oxy authorize endpoint', () => {
+    const url = buildOAuthAuthorizeUrl(base);
+    expect(url.startsWith(`${OXY_AUTHORIZE_URL}?`)).toBe(true);
+    expect(OXY_AUTHORIZE_URL).toBe('https://auth.oxy.so/authorize');
+  });
+
+  it('includes every required OAuth authorization-code + PKCE parameter', () => {
+    const params = new URL(buildOAuthAuthorizeUrl(base)).searchParams;
+    expect(params.get('client_id')).toBe(base.clientId);
+    expect(params.get('redirect_uri')).toBe(base.redirectUri);
+    expect(params.get('response_type')).toBe('code');
+    expect(params.get('state')).toBe(base.state);
+    expect(params.get('scope')).toBe(DEFAULT_OAUTH_SCOPE);
+    expect(params.get('code_challenge')).toBe(base.codeChallenge);
+    expect(params.get('code_challenge_method')).toBe('S256');
+  });
+
+  it('defaults the scope to "openid profile"', () => {
+    const params = new URL(buildOAuthAuthorizeUrl(base)).searchParams;
+    expect(params.get('scope')).toBe('openid profile');
+  });
+
+  it('honors a custom scope', () => {
+    const params = new URL(
+      buildOAuthAuthorizeUrl({ ...base, scope: 'openid profile email wallet' }),
+    ).searchParams;
+    expect(params.get('scope')).toBe('openid profile email wallet');
+  });
+
+  it('honors an authorizeBaseUrl override', () => {
+    const url = buildOAuthAuthorizeUrl({
+      ...base,
+      authorizeBaseUrl: 'https://auth.merchant.co/authorize',
+    });
+    expect(url.startsWith('https://auth.merchant.co/authorize?')).toBe(true);
+    expect(new URL(url).searchParams.get('client_id')).toBe(base.clientId);
+  });
+
+  it('preserves a query string already present on authorizeBaseUrl', () => {
+    const params = new URL(
+      buildOAuthAuthorizeUrl({
+        ...base,
+        authorizeBaseUrl: 'https://auth.merchant.co/authorize?foo=bar&tenant=acme',
+      }),
+    ).searchParams;
+    // Pre-existing params survive alongside the OAuth params.
+    expect(params.get('foo')).toBe('bar');
+    expect(params.get('tenant')).toBe('acme');
+    expect(params.get('client_id')).toBe(base.clientId);
+    expect(params.get('code_challenge_method')).toBe('S256');
+  });
+
+  it('URL-encodes a redirect_uri that carries a query string and special chars', () => {
+    const redirectUri = 'https://merchant.co/auth/callback?next=/dashboard&lang=es';
+    const url = buildOAuthAuthorizeUrl({ ...base, redirectUri });
+    // The raw string must be percent-encoded (its own & must not leak as a delimiter).
+    expect(url).toContain('redirect_uri=https%3A%2F%2Fmerchant.co%2Fauth%2Fcallback');
+    expect(url).not.toContain('redirect_uri=https://merchant.co');
+    // Round-trips back to the exact original when parsed.
+    expect(new URL(url).searchParams.get('redirect_uri')).toBe(redirectUri);
+  });
+});
+
+describe('canonicalizeOAuthRedirectUri', () => {
+  it('collapses apex URLs to origin only', () => {
+    expect(canonicalizeOAuthRedirectUri('https://app.example/')).toBe('https://app.example');
+    expect(canonicalizeOAuthRedirectUri('https://app.example')).toBe('https://app.example');
+  });
+
+  it('preserves path-qualified redirect URIs', () => {
+    const uri = 'https://app.example/oauth/callback';
+    expect(canonicalizeOAuthRedirectUri(uri)).toBe(uri);
+  });
+});
+
+describe('OAuth handshake persistence', () => {
+  function installSessionStorage(): Map<string, string> {
+    const map = new Map<string, string>();
+    (globalThis as { sessionStorage?: Storage }).sessionStorage = {
+      getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: (k: string, v: string) => void map.set(k, v),
+      removeItem: (k: string) => void map.delete(k),
+      clear: () => map.clear(),
+      key: (i: number) => [...map.keys()][i] ?? null,
+      get length() {
+        return map.size;
+      },
+    } as unknown as Storage;
+    return map;
+  }
+
+  afterEach(() => {
+    delete (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  });
+
+  it('round-trips redirect_uri through persist/read/clear', () => {
+    const store = installSessionStorage();
+    const redirectUri = 'https://app.example/oauth/callback';
+    expect(persistOAuthHandshake('state-1', 'verifier-1', redirectUri)).toBe(true);
+    expect(readOAuthHandshake()).toEqual({
+      state: 'state-1',
+      codeVerifier: 'verifier-1',
+      redirectUri,
+    });
+    clearOAuthHandshake();
+    expect(store.get(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY)).toBeUndefined();
+    expect(readOAuthHandshake()).toBeNull();
+  });
+});
+
+describe('OAuth return path', () => {
+  /** Minimal sessionStorage stand-in — jsdom is not assumed by this suite. */
+  function installSessionStorage(): Map<string, string> {
+    const map = new Map<string, string>();
+    (globalThis as { sessionStorage?: Storage }).sessionStorage = {
+      getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: (k: string, v: string) => void map.set(k, v),
+      removeItem: (k: string) => void map.delete(k),
+      clear: () => map.clear(),
+      key: (i: number) => [...map.keys()][i] ?? null,
+      get length() {
+        return map.size;
+      },
+    } as unknown as Storage;
+    return map;
+  }
+
+  afterEach(() => {
+    delete (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  });
+
+  it('round-trips a deep path through persist/consume', () => {
+    installSessionStorage();
+    persistOAuthReturnPath('/company/team?tab=eng#lead');
+    expect(consumeOAuthReturnPath()).toBe('/company/team?tab=eng#lead');
+  });
+
+  it('is single-use, so a stale value cannot redirect a later navigation', () => {
+    installSessionStorage();
+    persistOAuthReturnPath('/pricing');
+    expect(consumeOAuthReturnPath()).toBe('/pricing');
+    expect(consumeOAuthReturnPath()).toBeNull();
+  });
+
+  it('rejects protocol-relative and absolute values (open-redirect guard)', () => {
+    const store = installSessionStorage();
+    for (const hostile of ['//evil.com', '/\\evil.com', 'https://evil.com/x', 'evil.com']) {
+      persistOAuthReturnPath(hostile);
+      expect(store.get(OXY_OAUTH_RETURN_PATH_STORAGE_KEY)).toBeUndefined();
+    }
+  });
+
+  it('rejects a hostile value written directly into storage', () => {
+    const store = installSessionStorage();
+    store.set(OXY_OAUTH_RETURN_PATH_STORAGE_KEY, '//evil.com');
+    expect(consumeOAuthReturnPath()).toBeNull();
+    // Consumed even when rejected, so it cannot be retried.
+    expect(store.get(OXY_OAUTH_RETURN_PATH_STORAGE_KEY)).toBeUndefined();
+  });
+
+  it('is cleared with the handshake it belongs to', () => {
+    const store = installSessionStorage();
+    persistOAuthReturnPath('/newsroom');
+    clearOAuthHandshake();
+    expect(store.get(OXY_OAUTH_RETURN_PATH_STORAGE_KEY)).toBeUndefined();
+  });
+
+  it('no-ops without sessionStorage instead of throwing', () => {
+    expect(() => persistOAuthReturnPath('/pricing')).not.toThrow();
+    expect(consumeOAuthReturnPath()).toBeNull();
+  });
+});

package/src/utils/__tests__/officialOrigins.test.ts

@@ -0,0 +1,31 @@
+import {
+  isAllowedDeviceJoinOrigin,
+  isLoopbackOrigin,
+  isOfficialWebOrigin,
+} from '../officialOrigins';
+
+describe('officialOrigins', () => {
+  it('allows official first-party origins', () => {
+    expect(isOfficialWebOrigin('https://inbox.oxy.so')).toBe(true);
+    expect(isOfficialWebOrigin('https://mention.earth')).toBe(true);
+    expect(isOfficialWebOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('flags loopback / local-dev origins on any port', () => {
+    expect(isLoopbackOrigin('http://localhost:3000')).toBe(true);
+    expect(isLoopbackOrigin('http://127.0.0.1:8081')).toBe(true);
+    expect(isLoopbackOrigin('http://[::1]:19006')).toBe(true);
+    expect(isLoopbackOrigin('https://localhost')).toBe(true);
+    expect(isLoopbackOrigin('https://accounts.oxy.so')).toBe(false);
+    expect(isLoopbackOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('treats loopback as an official origin (loopback dev is trusted)', () => {
+    expect(isOfficialWebOrigin('http://localhost:3000')).toBe(true);
+  });
+
+  it('keeps the deprecated alias in sync with isOfficialWebOrigin', () => {
+    expect(isAllowedDeviceJoinOrigin('https://accounts.oxy.so')).toBe(true);
+    expect(isAllowedDeviceJoinOrigin('https://evil.example')).toBe(false);
+  });
+});

package/src/utils/__tests__/oxyServiceEnvironment.test.ts

@@ -0,0 +1,7 @@
+import { OXY_SERVICE_ENVIRONMENTS } from '../oxyServiceEnvironment';
+
+describe('OXY_SERVICE_ENVIRONMENTS', () => {
+  it('lists exactly development, staging, production, in that order', () => {
+    expect(OXY_SERVICE_ENVIRONMENTS).toEqual(['development', 'staging', 'production']);
+  });
+});