@oxyhq/core 3.10.1 → 3.12.0

package/src/mixins/__tests__/serviceAuth.test.ts

@@ -312,6 +312,25 @@ describe('H1: getServiceToken per-credential cache + secret verification', () =>
     );
   });
 
+  it('does not poison the cache when initial token fetch fails for an apiKey', async () => {
+    makeRequestSpy
+      .mockRejectedValueOnce(new Error('invalid service credentials'))
+      .mockResolvedValueOnce({
+        token: 'token-A',
+        expiresIn: 3600,
+        appName: 'tenant-A',
+      });
+
+    await expect(oxy.getServiceToken('key-A', 'attacker-secret')).rejects.toThrow(
+      'invalid service credentials',
+    );
+
+    const token = await oxy.getServiceToken('key-A', 'secret-A');
+
+    expect(token).toBe('token-A');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
+  });
+
   it('refreshes the cached token when it expires (using the correct stored secret)', async () => {
     // First token already past its buffer window.
     makeRequestSpy.mockResolvedValueOnce({

package/src/mixins/__tests__/sso.test.ts

@@ -11,6 +11,7 @@
 
 import { OxyServices } from '../../OxyServices';
 import { generateSsoState } from '../OxyServices.sso';
+import { ssoStateKey } from '../../utils/ssoBounce';
 
 interface FetchCall {
   url: string;
@@ -118,6 +119,36 @@ describe('OxyServices.exchangeSsoCode', () => {
     expect(calls).toHaveLength(0);
   });
 
+  it('rejects a browser SSO exchange when stored state is not echoed', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { calls } = mockFetchOnce(VALID_BODY);
+    const storage = new Map([[ssoStateKey('https://rp.example'), 'expected-state']]);
+    const previousWindow = (globalThis as unknown as { window?: unknown }).window;
+
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      value: {
+        location: { origin: 'https://rp.example' },
+        sessionStorage: {
+          getItem: (key: string) => storage.get(key) ?? null,
+        },
+      },
+    });
+
+    try {
+      await expect(oxy.exchangeSsoCode('opaque-code-123', 'attacker-state')).rejects.toThrow(
+        'SSO exchange state mismatch',
+      );
+      expect(calls).toHaveLength(0);
+      expect(oxy.hasValidToken()).toBe(false);
+    } finally {
+      Object.defineProperty(globalThis, 'window', {
+        configurable: true,
+        value: previousWindow,
+      });
+    }
+  });
+
   it('throws and does not plant a token on a non-2xx response', async () => {
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
     mockFetchOnce({ error: 'invalid_code' }, false, 400);

package/src/mixins/index.ts

@@ -12,6 +12,7 @@ import { OxyServicesSilentAuthMixin } from './OxyServices.silent';
 import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
 import { OxyServicesSsoMixin } from './OxyServices.sso';
 import { OxyServicesUserMixin } from './OxyServices.user';
+import { OxyServicesIdentityMixin } from './OxyServices.identity';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
 import { OxyServicesLanguageMixin } from './OxyServices.language';
 import { OxyServicesPaymentMixin } from './OxyServices.payment';
@@ -29,6 +30,7 @@ import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
+import { OxyServicesCivicMixin } from './OxyServices.civic';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -46,6 +48,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>>
@@ -62,6 +65,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -108,6 +112,8 @@ const MIXIN_PIPELINE: MixinFunction[] = [
 
     // User management (requires auth)
     OxyServicesUserMixin,
+    // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
+    OxyServicesIdentityMixin,
     OxyServicesPrivacyMixin,
 
     // Feature mixins
@@ -126,6 +132,8 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesManagedAccountsMixin,
     OxyServicesContactsMixin,
     OxyServicesAppDataMixin,
+    // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
+    OxyServicesCivicMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,

package/src/models/interfaces.ts

@@ -113,6 +113,9 @@ export interface User {
    */
   name: UserNameResponse;
   bio?: string;
+  phone?: string;
+  address?: string;
+  birthday?: string;
   location?: string;
   website?: string;
   createdAt?: string;

package/src/server/__tests__/cors.test.ts

@@ -34,7 +34,7 @@ function makeNext(): NextFunction & jest.Mock {
 }
 
 describe('@oxyhq/core/server createOxyCors', () => {
-  it('allows the Oxy apex family (apex + any subdomain) and echoes the exact origin', () => {
+  it('allows the HTTPS Oxy apex family (apex + one-level subdomains) and echoes the exact origin', () => {
     const mw = createOxyCors();
     for (const origin of [
       'https://oxy.so',
@@ -74,6 +74,10 @@ describe('@oxyhq/core/server createOxyCors', () => {
       'https://oxy.so.evil.com', // suffix attack
       'https://notoxy.so', // different apex
       'https://example.com',
+      'http://oxy.so',
+      'http://auth.oxy.so',
+      'https://deep.attacker-controlled.oxy.so',
+      'https://api.oxy.so:8443',
     ]) {
       const req = makeRequest('GET', origin);
       const res = makeResponse();

package/src/server/__tests__/rateLimit.test.ts

@@ -0,0 +1,116 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import type { OxyServices } from '../../OxyServices';
+
+const rateLimitMock = jest.fn();
+
+jest.mock('express-rate-limit', () => ({
+  __esModule: true,
+  default: (...args: unknown[]) => rateLimitMock(...args),
+}));
+
+import { createOxyRateLimit } from '../rateLimit';
+
+interface CapturedRateLimitOptions {
+  max: (req: Request) => number;
+  keyGenerator: (req: Request) => string;
+  skip: (req: Request) => boolean;
+}
+
+interface RateLimitTestRequest extends Request {
+  userId?: string | null;
+  user?: { id?: string; _id?: string } | null;
+  sessionId?: string | null;
+  serviceApp?: { appId?: string } | null;
+  serviceActingAs?: { userId?: string } | null;
+  observedMax?: number;
+  observedKey?: string;
+}
+
+function makeOxy(authHandler: RequestHandler): OxyServices {
+  return {
+    auth: jest.fn(() => authHandler),
+  } as unknown as OxyServices;
+}
+
+function makeRequest(overrides: Partial<RateLimitTestRequest> = {}): RateLimitTestRequest {
+  return {
+    method: 'GET',
+    path: '/api/test',
+    ip: '203.0.113.9',
+    socket: { remoteAddress: '203.0.113.9' },
+    ...overrides,
+  } as RateLimitTestRequest;
+}
+
+describe('@oxyhq/core/server rate limiter', () => {
+  beforeEach(() => {
+    rateLimitMock.mockImplementation((options: CapturedRateLimitOptions) => {
+      return (req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+        req.observedMax = options.max(req);
+        req.observedKey = options.keyGenerator(req);
+        next();
+      };
+    });
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('does not trust locally decoded non-session JWT identities for quota or bucket keys', () => {
+    const oxy = makeOxy((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'attacker-controlled-user';
+      req.user = { id: 'attacker-controlled-user' };
+      next();
+    });
+    const req = makeRequest();
+    const next = jest.fn();
+
+    createOxyRateLimit(oxy, { authenticatedMax: 5000, anonymousMax: 600 })(
+      req,
+      {} as Response,
+      next,
+    );
+
+    expect(req.observedMax).toBe(600);
+    expect(req.observedKey).toBe('203.0.113.9');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses authenticated quota and per-user keys for server-validated sessions', () => {
+    const oxy = makeOxy((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'validated-user';
+      req.user = { id: 'validated-user' };
+      req.sessionId = 'validated-session';
+      next();
+    });
+    const req = makeRequest();
+
+    createOxyRateLimit(oxy, { authenticatedMax: 5000, anonymousMax: 600 })(
+      req,
+      {} as Response,
+      jest.fn(),
+    );
+
+    expect(req.observedMax).toBe(5000);
+    expect(req.observedKey).toBe('user:validated-user');
+  });
+
+  it('continues through the anonymous limiter if optional auth returns an error', () => {
+    const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => {
+      next(new Error('token rejected'));
+    });
+    const req = makeRequest();
+    const next = jest.fn();
+
+    createOxyRateLimit(oxy, { authenticatedMax: 5000, anonymousMax: 600 })(
+      req,
+      {} as Response,
+      next,
+    );
+
+    expect(req.observedMax).toBe(600);
+    expect(req.observedKey).toBe('203.0.113.9');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/src/server/cors.ts

@@ -11,10 +11,9 @@
  *
  * `createOxyCors` returns a self-contained Express middleware (no `cors`
  * package dependency) that:
- *   - allows the Oxy apex origin family (anything under `*.${CENTRAL_IDP_APEX}`,
- *     i.e. `oxy.so` — covering `auth.oxy.so`, `api.oxy.so`, `accounts.oxy.so`,
- *     `console.oxy.so`, `inbox.oxy.so`, the marketing site, …) reusing the
- *     central-origin constants already in core, NOT a fresh hardcoded list,
+ *   - allows the Oxy apex origin family over HTTPS only: the apex plus
+ *     one-label subdomains such as `auth.oxy.so`, `api.oxy.so`,
+ *     `accounts.oxy.so`, `console.oxy.so`, and `inbox.oxy.so`,
  *   - allows the caller's explicit `appOrigins`,
  *   - DENIES everything else (no reflection, never a wildcard with credentials),
  *   - echoes back the EXACT matched origin (so credentialed requests work) and
@@ -26,7 +25,6 @@
 
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl';
-import { registrableApex } from '../utils/fapiAutoDetect';
 
 /** Default HTTP methods allowed across origins. */
 const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
@@ -44,11 +42,16 @@ const DEFAULT_ALLOWED_HEADERS = [
 /** How long (seconds) a browser may cache a successful preflight. */
 const DEFAULT_MAX_AGE_SECONDS = 86_400;
 
+const OXY_ONE_LABEL_SUBDOMAIN_PATTERN = new RegExp(
+  `^[a-z0-9-]+\\.${CENTRAL_IDP_APEX.replace('.', '\\.')}$`,
+);
+
 export interface OxyCorsOptions {
   /**
    * Explicit additional allowed origins (exact-origin match, e.g.
    * `https://app.example.com`, `http://localhost:3000`). These are allowed IN
-   * ADDITION TO the Oxy apex origin family. Each is normalized via `new URL().origin`.
+   * ADDITION TO the built-in HTTPS Oxy apex origin family. Each is normalized
+   * via `new URL().origin`.
    */
   appOrigins?: string[];
   /**
@@ -68,25 +71,27 @@ export interface OxyCorsOptions {
 }
 
 /**
- * Whether `candidate` belongs to the Oxy apex origin family — i.e. its
- * registrable apex equals {@link CENTRAL_IDP_APEX} (`oxy.so`). This matches the
- * apex itself (`https://oxy.so`) and any subdomain (`https://auth.oxy.so`,
- * `https://api.oxy.so`, …) over http or https, ports allowed. Returns false on
- * any parse failure (fail closed).
+ * Whether `candidate` belongs to the built-in Oxy apex origin family. This
+ * intentionally mirrors the API allowlist shape: HTTPS only, no custom port,
+ * the apex itself (`https://oxy.so`), or exactly one lowercase subdomain label
+ * (`https://auth.oxy.so`, `https://api.oxy.so`, …).
+ *
+ * Arbitrary/multi-level subdomains and `http://*.oxy.so` are not implicitly
+ * trusted for credentialed CORS. If a service needs a non-standard development
+ * or tenant origin, it must opt in explicitly via `appOrigins`.
  */
 function isOxyFamilyOrigin(candidate: string): boolean {
-  let hostname: string;
-  let protocol: string;
   try {
     const url = new URL(candidate);
-    hostname = url.hostname.toLowerCase();
-    protocol = url.protocol;
+    if (url.protocol !== 'https:' || url.port !== '') return false;
+
+    const hostname = url.hostname;
+    if (hostname === CENTRAL_IDP_APEX) return true;
+
+    return OXY_ONE_LABEL_SUBDOMAIN_PATTERN.test(hostname);
   } catch {
     return false;
   }
-  if (protocol !== 'https:' && protocol !== 'http:') return false;
-  if (hostname === CENTRAL_IDP_APEX) return true;
-  return registrableApex(hostname) === CENTRAL_IDP_APEX;
 }
 
 /** Normalize a raw origin string to its canonical `scheme://host[:port]` form. */
@@ -99,8 +104,8 @@ function normalizeOrigin(raw: string): string | null {
 }
 
 /**
- * Build the origin-matching predicate: true iff `origin` is in the Oxy apex
- * family OR exactly matches one of the configured app origins.
+ * Build the origin-matching predicate: true iff `origin` is in the built-in
+ * HTTPS Oxy apex family OR exactly matches one of the configured app origins.
  */
 function buildOriginAllowed(appOrigins: string[]): (origin: string) => boolean {
   const explicit = new Set<string>();

package/src/server/rateLimit.ts

@@ -41,6 +41,9 @@ import type { OxyServices } from '../OxyServices';
 interface OxyAuthedRequest extends Request {
   userId?: string | null;
   user?: { id?: string; _id?: string } | null;
+  sessionId?: string | null;
+  serviceApp?: { appId?: string } | null;
+  serviceActingAs?: { userId?: string } | null;
 }
 
 export interface OxyRateLimitOptions {
@@ -101,12 +104,40 @@ function ipKeyGenerator(ip: string): string {
   return ip.replace(/:/g, '_');
 }
 
-/** Resolve the rate-limit key: per authenticated user, else per (IPv6-safe) IP. */
-function resolveKey(req: OxyAuthedRequest): string {
+/**
+ * Resolve the trusted authenticated rate-limit key.
+ *
+ * `oxy.auth({ optional: true })` preserves legacy non-session user tokens by
+ * decoding their JWT claims locally. Those claims are not cryptographically
+ * verified and therefore MUST NOT influence abuse-control buckets. Only use
+ * identities that came from a server-validated session or a verified service
+ * token/delegation.
+ */
+function resolveTrustedAuthenticatedKey(req: OxyAuthedRequest): string | null {
   const userId = req.userId ?? req.user?.id ?? req.user?._id;
-  if (userId) {
+  if (userId && req.sessionId) {
     return `user:${userId}`;
   }
+
+  const delegatedUserId = req.serviceActingAs?.userId;
+  if (delegatedUserId && req.serviceApp?.appId) {
+    return `user:${delegatedUserId}`;
+  }
+
+  const serviceAppId = req.serviceApp?.appId;
+  if (serviceAppId) {
+    return `service:${serviceAppId}`;
+  }
+
+  return null;
+}
+
+/** Resolve the rate-limit key: per trusted authenticated identity, else per (IPv6-safe) IP. */
+function resolveKey(req: OxyAuthedRequest): string {
+  const authenticatedKey = resolveTrustedAuthenticatedKey(req);
+  if (authenticatedKey) {
+    return authenticatedKey;
+  }
   const ip = req.ip || req.socket.remoteAddress || 'unknown';
   return ipKeyGenerator(ip);
 }
@@ -139,9 +170,9 @@ export function createOxyRateLimit(
     windowMs,
     ...(store ? { store } : {}),
     max: (req: Request): number => {
-      const authed = req as OxyAuthedRequest;
-      const userId = authed.userId ?? authed.user?.id ?? authed.user?._id;
-      return userId ? authenticatedMax : anonymousMax;
+      return resolveTrustedAuthenticatedKey(req as OxyAuthedRequest)
+        ? authenticatedMax
+        : anonymousMax;
     },
     keyGenerator: (req: Request): string => resolveKey(req as OxyAuthedRequest),
     message,
@@ -160,8 +191,8 @@ export function createOxyRateLimit(
     resolveSession(req, res, (err?: unknown) => {
       if (err) {
         // Optional auth never rejects; a token error just means "anonymous".
-        // Swallow the error and continue to limit as anonymous.
-        next();
+        // Swallow the error and continue through the anonymous limiter.
+        limiter(req, res, next);
         return;
       }
       limiter(req, res, next);

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

@@ -218,7 +218,7 @@ describe('consumeSsoReturn', () => {
     });
 
     expect(result).toEqual(SESSION);
-    expect(oxy.exchangeSsoCode).toHaveBeenCalledWith('opaque-code');
+    expect(oxy.exchangeSsoCode).toHaveBeenCalledWith('opaque-code', 's');
     expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoNoSessionKey(ORIGIN))).toBe(false);

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

@@ -0,0 +1,126 @@
+import { normalizeProfileLinks, type ProfileLink } from '../profileLinks';
+
+describe('normalizeProfileLinks', () => {
+  describe('linksMetadata path (preferred)', () => {
+    it('maps title + url and uses the entry id when present', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://oxy.so', title: 'Oxy', id: 'abc' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: 'abc', title: 'Oxy', url: 'https://oxy.so' },
+      ]);
+    });
+
+    it('falls back to the index when an entry has no id', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://a.example', title: 'A' },
+        { url: 'https://b.example', title: 'B' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', title: 'A', url: 'https://a.example' },
+        { id: '1', title: 'B', url: 'https://b.example' },
+      ]);
+    });
+
+    it('omits title when absent', () => {
+      const result = normalizeProfileLinks([{ url: 'https://no-title.example' }]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://no-title.example' },
+      ]);
+      expect(result[0]).not.toHaveProperty('title');
+    });
+
+    it('drops entries with missing or empty url and keeps stable index ids', () => {
+      const result = normalizeProfileLinks([
+        { url: 'https://keep.example', title: 'Keep', id: 'keep' },
+        { url: '', title: 'Empty' },
+        { url: '   ', title: 'Whitespace' },
+        { url: 'https://second.example', title: 'Second' },
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: 'keep', title: 'Keep', url: 'https://keep.example' },
+        // index is preserved from the source array position (3), not re-numbered
+        { id: '3', title: 'Second', url: 'https://second.example' },
+      ]);
+    });
+
+    it('trims surrounding whitespace from urls', () => {
+      const result = normalizeProfileLinks([{ url: '  https://trim.example  ' }]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://trim.example' },
+      ]);
+    });
+
+    it('does NOT add a scheme to bare urls', () => {
+      const result = normalizeProfileLinks([{ url: 'oxy.so', title: 'Bare' }]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', title: 'Bare', url: 'oxy.so' },
+      ]);
+    });
+  });
+
+  describe('legacy links path (no linksMetadata)', () => {
+    it('maps strings to { id, url } without titles', () => {
+      const result = normalizeProfileLinks(undefined, [
+        'https://a.example',
+        'https://b.example',
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://a.example' },
+        { id: '1', url: 'https://b.example' },
+      ]);
+      expect(result.every((link) => !('title' in link))).toBe(true);
+    });
+
+    it('drops empty and whitespace-only strings, preserving source index ids', () => {
+      const result = normalizeProfileLinks(undefined, [
+        'https://keep.example',
+        '',
+        '   ',
+        'https://second.example',
+      ]);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://keep.example' },
+        { id: '3', url: 'https://second.example' },
+      ]);
+    });
+  });
+
+  describe('fall-through and empty inputs', () => {
+    it('returns [] when both inputs are absent', () => {
+      expect(normalizeProfileLinks()).toEqual([]);
+      expect(normalizeProfileLinks(undefined, undefined)).toEqual([]);
+    });
+
+    it('returns [] when both inputs are empty arrays', () => {
+      expect(normalizeProfileLinks([], [])).toEqual([]);
+    });
+
+    it('falls through to legacy links when linksMetadata is empty', () => {
+      const result = normalizeProfileLinks([], ['https://legacy.example']);
+      expect(result).toEqual<ProfileLink[]>([
+        { id: '0', url: 'https://legacy.example' },
+      ]);
+    });
+
+    it('returns [] (does NOT fall back to links) when linksMetadata is non-empty but every entry is dropped', () => {
+      const result = normalizeProfileLinks(
+        [{ url: '' }, { url: '   ' }],
+        ['https://legacy.example'],
+      );
+      expect(result).toEqual([]);
+    });
+  });
+
+  it('is pure — does not mutate its inputs', () => {
+    const linksMetadata = [{ url: 'https://oxy.so', title: 'Oxy', id: 'abc' }];
+    const links = ['https://legacy.example'];
+    const metadataSnapshot = JSON.stringify(linksMetadata);
+    const linksSnapshot = JSON.stringify(links);
+
+    normalizeProfileLinks(linksMetadata, links);
+
+    expect(JSON.stringify(linksMetadata)).toBe(metadataSnapshot);
+    expect(JSON.stringify(links)).toBe(linksSnapshot);
+  });
+});

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

@@ -188,7 +188,7 @@ describe('consumeSsoReturn pre-hydration callback bootstrap', () => {
     );
 
     expect(session).toBe(exchangedSession);
-    expect(exchangeSsoCode).toHaveBeenCalledWith('opaque-code');
+    expect(exchangeSsoCode).toHaveBeenCalledWith('opaque-code', 'state-ok');
     expect(replaceStateCalls).toEqual(['/', '/explore?tab=home#top']);
     expect(dispatchPopState).toHaveBeenCalledTimes(1);
     expect(hardRedirect).not.toHaveBeenCalled();

package/src/utils/profileLinks.ts

@@ -0,0 +1,74 @@
+/**
+ * Normalized profile link shape for display.
+ *
+ * `id` is a stable key for list rendering (the source entry's id when present,
+ * otherwise the source index as a string). `url` is always a non-empty string.
+ */
+export interface ProfileLink {
+  id: string;
+  title?: string;
+  url: string;
+}
+
+/** Source shape of a single `User.linksMetadata` entry. */
+export interface ProfileLinkMetadata {
+  url: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  id?: string;
+}
+
+function cleanUrl(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url }`, using `entry.id` when present and falling back to the
+ *   entry index. Entries without a non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title). Empty/non-string values are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+export function normalizeProfileLinks(
+  linksMetadata?: ProfileLinkMetadata[],
+  links?: string[],
+): ProfileLink[] {
+  if (Array.isArray(linksMetadata) && linksMetadata.length > 0) {
+    const result: ProfileLink[] = [];
+    linksMetadata.forEach((entry, index) => {
+      const url = cleanUrl(entry?.url);
+      if (!url) return;
+      const id =
+        typeof entry?.id === 'string' && entry.id.trim().length > 0
+          ? entry.id
+          : String(index);
+      const title = typeof entry?.title === 'string' ? entry.title : undefined;
+      result.push({ id, url, ...(title !== undefined ? { title } : {}) });
+    });
+    return result;
+  }
+
+  if (Array.isArray(links) && links.length > 0) {
+    const result: ProfileLink[] = [];
+    links.forEach((value, index) => {
+      const url = cleanUrl(value);
+      if (!url) return;
+      result.push({ id: String(index), url });
+    });
+    return result;
+  }
+
+  return [];
+}

package/src/utils/ssoReturn.ts

@@ -202,7 +202,7 @@ export interface ConsumeSsoReturnDeps {
  * @returns The exchanged session on success, otherwise `null`.
  */
 export async function consumeSsoReturn(
-  oxy: { exchangeSsoCode: (code: string) => Promise<SessionLoginResponse> },
+  oxy: { exchangeSsoCode: (code: string, state?: string) => Promise<SessionLoginResponse> },
   deps: ConsumeSsoReturnDeps = {},
 ): Promise<SessionLoginResponse | null> {
   const isWeb =
@@ -344,7 +344,7 @@ export async function consumeSsoReturn(
 
   let session: SessionLoginResponse | undefined;
   try {
-    session = await oxy.exchangeSsoCode(ret.code);
+    session = await oxy.exchangeSsoCode(ret.code, ret.state);
   } catch (error) {
     onExchangeError?.(error);
     markNoSession();