@oxyhq/core 3.4.8 → 3.4.10

package/dist/types/index.d.ts

@@ -34,6 +34,7 @@ export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServic
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
+export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull } from './utils/userIdentity';
 export type { Application, PublicApplication, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export type { Workspace, WorkspaceMember, WorkspaceRole, WorkspaceType, WorkspaceStatus, WorkspaceMemberStatus, CreateWorkspaceInput, UpdateWorkspaceInput, InviteWorkspaceMemberInput, UpdateWorkspaceMemberInput, TransferWorkspaceOwnershipInput, WorkspaceSuccessResult, } from './mixins/OxyServices.workspaces';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -71,13 +71,13 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
          * @throws {OxyAuthenticationError} If FedCM not supported or user cancels
          *
          * @example
-         * ```typescript
-         * try {
-         *   const session = await oxyServices.signInWithFedCM();
-         *   console.log('Signed in:', session.user);
-         * } catch (error) {
-         *   // Fallback to redirect auth
-         *   oxyServices.signInWithRedirect();
+       * ```typescript
+       * try {
+       *   const session = await oxyServices.signInWithFedCM();
+       *   const user = session.user;
+       * } catch (error) {
+       *   // Fallback to redirect auth
+       *   oxyServices.signInWithRedirect();
          * }
          * ```
          */

package/dist/types/utils/userIdentity.d.ts

@@ -0,0 +1,12 @@
+interface UserIdentityInput {
+    id?: unknown;
+    _id?: unknown;
+}
+export declare function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null;
+export declare function normalizeUserIdentity<T extends UserIdentityInput>(user: T): T & {
+    id: string;
+};
+export declare function normalizeUserIdentityOrNull<T extends UserIdentityInput>(user: T | null | undefined): (T & {
+    id: string;
+}) | null;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.8",
+  "version": "3.4.10",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -32,7 +32,7 @@ interface JwtPayload {
   userId?: string;
   id?: string;
   sessionId?: string;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 export type AuthRefreshReason = 'preflight' | 'response-401';
@@ -314,9 +314,11 @@ export class HttpService {
         // Get auth token (with auto-refresh)
         const authHeader = await this.getAuthHeader();
 
-        // Get CSRF token for state-changing requests
+        // CSRF protects cookie-authenticated browser writes. Bearer-authenticated
+        // SDK clients are not vulnerable to ambient-cookie CSRF, and linked app
+        // APIs should not need to implement a duplicate `/csrf-token` route.
         const isStateChangingMethod = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
-        const csrfToken = isStateChangingMethod ? await this.fetchCsrfToken() : null;
+        const csrfToken = isStateChangingMethod && !authHeader ? await this.fetchCsrfToken() : null;
 
         // Determine if data is FormData using robust detection
         const isFormData = this.isFormData(data);
@@ -356,10 +358,8 @@ export class HttpService {
           headers['X-Native-App'] = 'true';
         }
 
-        // Debug logging for CSRF issues — routed through the SimpleLogger so
-        // it only fires when consumers opt in via `enableLogging`. Previously
-        // this was a bare console.log that leaked noise into every host app's
-        // stdout in development.
+        // Debug logging for CSRF issues, routed through SimpleLogger so it only
+        // fires when consumers opt in via `enableLogging`.
         if (isStateChangingMethod) {
           this.logger.debug('CSRF Debug:', {
             url,

package/src/__tests__/httpServiceCsrf.test.ts

@@ -0,0 +1,92 @@
+import { HttpService } from '../HttpService';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit;
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function readHeaders(init: RequestInit | undefined): Record<string, string> {
+  const headers = init?.headers;
+  if (!headers) {
+    return {};
+  }
+  if (headers instanceof Headers) {
+    return Object.fromEntries(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers as Record<string, string>;
+}
+
+describe('HttpService CSRF behavior', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('does not fetch csrf-token before bearer-authenticated writes', async () => {
+    const calls: FetchCall[] = [];
+    const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+      calls.push({ url, init });
+      return jsonResponse({ ok: true });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    const accessToken = createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    http.setTokens(accessToken);
+
+    await http.post('/posts', { text: 'hello' });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://api.mention.earth/posts');
+    const headers = readHeaders(calls[0].init);
+    expect(headers.Authorization).toBe(`Bearer ${accessToken}`);
+    expect(headers['X-CSRF-Token']).toBeUndefined();
+  });
+
+  it('still fetches csrf-token for cookie-authenticated writes without bearer', async () => {
+    const calls: FetchCall[] = [];
+    const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+      calls.push({ url, init });
+      if (url.endsWith('/csrf-token')) {
+        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      return jsonResponse({ ok: true });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+
+    await http.post('/posts', { text: 'hello' });
+
+    expect(calls.map((call) => call.url)).toEqual([
+      'https://api.mention.earth/csrf-token',
+      'https://api.mention.earth/posts',
+    ]);
+    const headers = readHeaders(calls[1].init);
+    expect(headers.Authorization).toBeUndefined();
+    expect(headers['X-CSRF-Token']).toBe('csrf_1');
+  });
+});

package/src/__tests__/userIdentity.test.ts

@@ -0,0 +1,75 @@
+import { OxyServices } from '../OxyServices';
+import { getNormalizedUserId, normalizeUserIdentity } from '../utils/userIdentity';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+describe('user identity normalization', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('normalizes Mongo _id to id', () => {
+    expect(getNormalizedUserId({ _id: 'mongo_id' })).toBe('mongo_id');
+    expect(normalizeUserIdentity({ _id: 'mongo_id', username: 'nate' })).toEqual({
+      _id: 'mongo_id',
+      id: 'mongo_id',
+      username: 'nate',
+    });
+  });
+
+  it('normalizes getCurrentUser responses before exposing them to apps', async () => {
+    const calls: FetchCall[] = [];
+    const fetchMock = jest.fn(async (url: string, init: RequestInit) => {
+      calls.push({ url, init });
+      return jsonResponse({ _id: 'user_1', username: 'nate', publicKey: 'pub_1' });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    }));
+    const user = await oxy.getCurrentUser();
+
+    expect(user.id).toBe('user_1');
+    expect(user.username).toBe('nate');
+    expect(calls[0].url).toBe('https://api.oxy.so/users/me');
+  });
+
+  it('normalizes validateSession users before services stores them', async () => {
+    const fetchMock = jest.fn(async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-18T00:00:00.000Z',
+        user: { _id: 'user_1', username: 'nate', publicKey: 'pub_1' },
+      }),
+    );
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const validation = await oxy.validateSession('session_1', { useHeaderValidation: true });
+
+    expect(validation.user.id).toBe('user_1');
+    expect(validation.user.username).toBe('nate');
+  });
+});

package/src/index.ts

@@ -62,6 +62,7 @@ export type {
     ContactDiscoveryResponse,
 } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
+export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull } from './utils/userIdentity';
 
 // ---------------------------------------------------------------------------
 // Applications (multi-user apps: membership, roles, credentials)

package/src/mixins/OxyServices.auth.ts

@@ -15,6 +15,7 @@ import type { OxyServicesBase } from '../OxyServices.base';
 import { OxyAuthenticationError } from '../OxyServices.errors';
 import { loadNodeCrypto } from '../utils/platformCrypto';
 import { logger } from '../utils/loggerUtils';
+import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 
 export interface ChallengeResponse {
   challenge: string;
@@ -451,7 +452,10 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           this.setTokens(res.accessToken);
         }
 
-        return res;
+        return {
+          ...res,
+          user: normalizeUserIdentity(res.user),
+        };
       } catch (error) {
         throw this.handleError(error);
       }
@@ -478,12 +482,13 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserByPublicKey(publicKey: string): Promise<User> {
       try {
-        return await this.makeRequest<User>(
+        const user = await this.makeRequest<User>(
           'GET',
           `/auth/user/${encodeURIComponent(publicKey)}`,
           undefined,
           { cache: true, cacheTTL: 2 * 60 * 1000 }
         );
+        return normalizeUserIdentity(user);
       } catch (error) {
         throw this.handleError(error);
       }
@@ -494,10 +499,11 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserBySession(sessionId: string): Promise<User> {
       try {
-        return await this.makeRequest<User>('GET', `/session/user/${sessionId}`, undefined, {
+        const user = await this.makeRequest<User>('GET', `/session/user/${sessionId}`, undefined, {
           cache: true,
           cacheTTL: 2 * 60 * 1000,
         });
+        return normalizeUserIdentity(user);
       } catch (error) {
         throw this.handleError(error);
       }
@@ -514,7 +520,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         
         const uniqueSessionIds = Array.from(new Set(sessionIds)).sort();
         
-        return await this.makeRequest<Array<{ sessionId: string; user: User | null }>>(
+        const users = await this.makeRequest<Array<{ sessionId: string; user: User | null }>>(
           'POST',
           '/session/users/batch',
           { sessionIds: uniqueSessionIds },
@@ -524,6 +530,10 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
             deduplicate: true,
           }
         );
+        return users.map((entry) => ({
+          ...entry,
+          user: normalizeUserIdentityOrNull(entry.user),
+        }));
       } catch (error) {
         throw this.handleError(error);
       }
@@ -909,7 +919,18 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         const urlParams: Record<string, string> = {};
         if (options.deviceFingerprint) urlParams.deviceFingerprint = options.deviceFingerprint;
         if (options.useHeaderValidation) urlParams.useHeaderValidation = 'true';
-        return await this.makeRequest('GET', `/session/validate/${sessionId}`, urlParams, { cache: false });
+        const validation = await this.makeRequest<{
+          valid: boolean;
+          expiresAt: string;
+          lastActivity: string;
+          user: User;
+          sessionId?: string;
+          source?: string;
+        }>('GET', `/session/validate/${sessionId}`, urlParams, { cache: false });
+        return {
+          ...validation,
+          user: normalizeUserIdentity(validation.user),
+        };
       } catch (error) {
         // Session is invalid — clear any cached user data for this session (#196)
         this.clearCacheEntry(`GET:/session/user/${sessionId}`);
@@ -950,13 +971,17 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       deviceFingerprint?: any
     ): Promise<SessionLoginResponse> {
       try {
-        return await this.makeRequest<SessionLoginResponse>('POST', '/auth/signup', {
+        const session = await this.makeRequest<SessionLoginResponse>('POST', '/auth/signup', {
           username,
           email,
           password,
           deviceName,
           deviceFingerprint,
         }, { cache: false });
+        return {
+          ...session,
+          user: normalizeUserIdentity(session.user),
+        };
       } catch (error) {
         throw this.handleError(error);
       }
@@ -972,12 +997,16 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       deviceFingerprint?: any
     ): Promise<SessionLoginResponse> {
       try {
-        return await this.makeRequest<SessionLoginResponse>('POST', '/auth/login', {
+        const session = await this.makeRequest<SessionLoginResponse>('POST', '/auth/login', {
           identifier,
           password,
           deviceName,
           deviceFingerprint,
         }, { cache: false });
+        return {
+          ...session,
+          user: normalizeUserIdentity(session.user),
+        };
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.fedcm.ts

@@ -2,6 +2,7 @@ import type { OxyServicesBase } from '../OxyServices.base';
 import { OxyAuthenticationError } from '../OxyServices.errors';
 import type { SessionLoginResponse } from '../models/session';
 import { createDebugLogger } from '../shared/utils/debugUtils';
+import { normalizeUserIdentity } from '../utils/userIdentity';
 
 const debug = createDebugLogger('FedCM');
 
@@ -254,13 +255,13 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
    * @throws {OxyAuthenticationError} If FedCM not supported or user cancels
    *
    * @example
-   * ```typescript
-   * try {
-   *   const session = await oxyServices.signInWithFedCM();
-   *   console.log('Signed in:', session.user);
-   * } catch (error) {
-   *   // Fallback to redirect auth
-   *   oxyServices.signInWithRedirect();
+ * ```typescript
+ * try {
+ *   const session = await oxyServices.signInWithFedCM();
+ *   const user = session.user;
+ * } catch (error) {
+ *   // Fallback to redirect auth
+ *   oxyServices.signInWithRedirect();
    * }
    * ```
    */
@@ -776,7 +777,10 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         hasUser: !!response?.user,
       });
 
-      return response;
+      return {
+        ...response,
+        user: normalizeUserIdentity(response.user),
+      };
     } catch (error) {
       debug.error('Token exchange failed:', error instanceof Error ? error.message : String(error));
       throw error;

package/src/mixins/OxyServices.user.ts

@@ -14,6 +14,7 @@ import type { OxyServicesBase } from '../OxyServices.base';
 import { buildSearchParams, buildPaginationParams, type PaginationParams } from '../utils/apiUtils';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
+import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 
 export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -25,10 +26,11 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getProfileByUsername(username: string): Promise<User> {
       try {
-        return await this.makeRequest<User>('GET', `/profiles/username/${username}`, undefined, {
+        const user = await this.makeRequest<User>('GET', `/profiles/username/${username}`, undefined, {
           cache: true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache for profiles
         });
+        return normalizeUserIdentity(user);
       } catch (error) {
         throw this.handleError(error);
       }
@@ -109,7 +111,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           cache: true,
           cacheTTL: 24 * 60 * 60 * 1000, // 24h cache — matches server-side staleness window
         });
-        return result ?? null;
+        return normalizeUserIdentityOrNull(result);
       } catch {
         return null;
       }
@@ -130,7 +132,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       bio?: string;
       ownerId?: string;
     }): Promise<User> {
-      return this.makeRequest<User>('PUT', '/users/resolve', data);
+      return normalizeUserIdentity(await this.makeRequest<User>('PUT', '/users/resolve', data));
     }
 
     /**
@@ -175,10 +177,11 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     async getSimilarProfiles(userId: string, limit?: number): Promise<User[]> {
       const params: Record<string, string> = {};
       if (limit) params.limit = String(limit);
-      return await this.makeRequest<User[]>('GET', `/profiles/${userId}/similar`, params, {
+      const users = await this.makeRequest<User[]>('GET', `/profiles/${userId}/similar`, params, {
         cache: true,
         cacheTTL: 5 * 60 * 1000, // 5 min cache
       });
+      return users.map((user) => normalizeUserIdentity(user));
     }
 
     /**
@@ -186,10 +189,11 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserById(userId: string): Promise<User> {
       try {
-        return await this.makeRequest<User>('GET', `/users/${userId}`, undefined, {
+        const user = await this.makeRequest<User>('GET', `/users/${userId}`, undefined, {
           cache: true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache
         });
+        return normalizeUserIdentity(user);
       } catch (error) {
         throw this.handleError(error);
       }
@@ -200,10 +204,11 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getCurrentUser(): Promise<User> {
       return this.withAuthRetry(async () => {
-        return await this.makeRequest<User>('GET', '/users/me', undefined, {
+        const user = await this.makeRequest<User>('GET', '/users/me', undefined, {
           cache: true,
           cacheTTL: 1 * 60 * 1000, // 1 minute cache for current user
         });
+        return normalizeUserIdentity(user);
       }, 'getCurrentUser');
     }
 
@@ -222,7 +227,9 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async updateProfile(updates: Partial<User>): Promise<User> {
       try {
-        const result = await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false });
+        const result = normalizeUserIdentity(
+          await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false }),
+        );
 
         // Bust every cached representation of the current user. We use a
         // prefix sweep rather than an enumeration because the SDK never
@@ -236,12 +243,18 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
         return result;
       } catch (error) {
-        const errorAny = error as any;
         const errorMessage = error instanceof Error ? error.message : String(error);
-        const status = errorAny?.status || errorAny?.response?.status;
-        
+        const errorRecord = error && typeof error === 'object'
+          ? error as { status?: unknown; response?: { status?: unknown } }
+          : null;
+        const status = typeof errorRecord?.status === 'number'
+          ? errorRecord.status
+          : typeof errorRecord?.response?.status === 'number'
+            ? errorRecord.response.status
+            : undefined;
+
         // Check if it's an authentication error (401)
-        const isAuthError = status === 401 || 
+        const isAuthError = status === 401 ||
           errorMessage.includes('Authentication required') ||
           errorMessage.includes('Invalid or missing authorization header');
 
@@ -531,4 +544,3 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
   };
 }
-

package/src/utils/userIdentity.ts

@@ -0,0 +1,51 @@
+interface UserIdentityInput {
+  id?: unknown;
+  _id?: unknown;
+}
+
+function stringifyIdentity(value: unknown): string | null {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(value);
+  }
+
+  if (value && typeof value === 'object' && 'toString' in value) {
+    const toStringFn = value.toString;
+    if (typeof toStringFn === 'function' && toStringFn !== Object.prototype.toString) {
+      const rendered = toStringFn.call(value);
+      if (typeof rendered === 'string') {
+        const trimmed = rendered.trim();
+        return trimmed.length > 0 && trimmed !== '[object Object]' ? trimmed : null;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null {
+  if (!user) {
+    return null;
+  }
+
+  return stringifyIdentity(user.id) ?? stringifyIdentity(user._id);
+}
+
+export function normalizeUserIdentity<T extends UserIdentityInput>(user: T): T & { id: string } {
+  const id = getNormalizedUserId(user);
+  if (!id) {
+    throw new Error('User response missing id');
+  }
+
+  return { ...user, id };
+}
+
+export function normalizeUserIdentityOrNull<T extends UserIdentityInput>(
+  user: T | null | undefined,
+): (T & { id: string }) | null {
+  return user ? normalizeUserIdentity(user) : null;
+}