@oxyhq/core 3.10.1 → 3.11.0

package/dist/types/models/interfaces.d.ts

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

package/dist/types/server/cors.d.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
@@ -28,7 +27,8 @@ 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[];
     /**

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

@@ -142,5 +142,5 @@ export interface ConsumeSsoReturnDeps {
  * @returns The exchanged session on success, otherwise `null`.
  */
 export declare function consumeSsoReturn(oxy: {
-    exchangeSsoCode: (code: string) => Promise<SessionLoginResponse>;
+    exchangeSsoCode: (code: string, state?: string) => Promise<SessionLoginResponse>;
 }, deps?: ConsumeSsoReturnDeps): Promise<SessionLoginResponse | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.10.1",
+  "version": "3.11.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -98,7 +98,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.2.1",
+    "@oxyhq/contracts": "^0.3.0",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/AuthManager.ts

@@ -445,8 +445,14 @@ export class AuthManager {
    * Get default storage based on environment.
    */
   private getDefaultStorage(): StorageAdapter {
-    if (typeof window !== 'undefined' && window.localStorage) {
-      return new LocalStorageAdapter();
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        return new LocalStorageAdapter();
+      }
+    } catch {
+      // Accessing window.localStorage can throw in opaque-origin/sandboxed
+      // browser contexts or when storage is disabled. Fall back to memory so
+      // AuthManager construction remains safe during provider render.
     }
     return new MemoryStorage();
   }

package/src/HttpService.ts

@@ -68,6 +68,7 @@ export interface RequestOptions {
   timeout?: number;
   signal?: AbortSignal;
   headers?: Record<string, string>;
+  responseType?: 'blob';
 }
 
 interface RequestConfig extends RequestOptions {
@@ -496,13 +497,21 @@ export class HttpService {
         const useXhrForUpload = isFormData && isReactNative() && typeof XMLHttpRequest !== 'undefined';
 
         const response = useXhrForUpload
-          ? await this.uploadViaXHR(fullUrl, method, headers, bodyValue as FormData, controller.signal, timeout)
+          ? await this.uploadViaXHR(
+              fullUrl,
+              method,
+              headers,
+              bodyValue as FormData,
+              controller.signal,
+              timeout,
+              this.shouldSendCredentials(fullUrl),
+            )
           : await fetch(fullUrl, {
               method,
               headers,
               body: bodyValue as BodyInit | null | undefined,
               signal: controller.signal,
-              credentials: 'include', // Include cookies for cross-origin requests (CSRF, session)
+              credentials: this.getCredentialsMode(fullUrl),
             });
 
         if (timeoutId) clearTimeout(timeoutId);
@@ -530,7 +539,7 @@ export class HttpService {
               const errBody = await clonedResponse.json() as { code?: string } | null;
               if (errBody?.code === 'CSRF_TOKEN_INVALID' || errBody?.code === 'CSRF_TOKEN_MISSING') {
                 this.tokenStore.clearCsrfToken();
-                return this.request<T>({ ...config, _isCsrfRetry: true, retry: false });
+                return this.request<T>({ ...config, _isCsrfRetry: true, retry: false, deduplicate: false });
               }
             } catch {
               // Failed to parse error body — not a CSRF error
@@ -568,7 +577,9 @@ export class HttpService {
         const contentType = response.headers.get('content-type');
         let responseData: unknown;
         
-        if (contentType && contentType.includes('application/json')) {
+        if (config.responseType === 'blob') {
+          responseData = await response.blob();
+        } else if (contentType && contentType.includes('application/json')) {
           // Use response.json() directly for better performance
           try {
             responseData = await response.json();
@@ -694,13 +705,15 @@ export class HttpService {
     body: FormData,
     abortSignal: AbortSignal,
     timeout: number,
+    withCredentials: boolean,
   ): Promise<Response> {
     return new Promise<Response>((resolve, reject) => {
       const xhr = new XMLHttpRequest();
       xhr.open(method, url, true);
-      // withCredentials mirrors fetch's `credentials: 'include'` so the
-      // session cookie and CSRF cookie continue to flow.
-      xhr.withCredentials = true;
+      // Only send ambient cookies to the configured API origin. Absolute
+      // caller-supplied URLs can target arbitrary origins, so they must not
+      // receive credential-bearing requests by default.
+      xhr.withCredentials = withCredentials;
 
       // Forward headers but skip Content-Type — XHR sets the multipart
       // boundary automatically and overriding it breaks the upload.
@@ -874,6 +887,18 @@ export class HttpService {
     return queryString ? `${base}${base.includes('?') ? '&' : '?'}${queryString}` : base;
   }
 
+  private getCredentialsMode(url: string): RequestCredentials {
+    return this.shouldSendCredentials(url) ? 'include' : 'omit';
+  }
+
+  private shouldSendCredentials(url: string): boolean {
+    try {
+      return new URL(url).origin === new URL(this.baseURL).origin;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Fetch CSRF token from server (with deduplication)
    * Required for state-changing requests (POST, PUT, PATCH, DELETE)
@@ -915,8 +940,11 @@ export class HttpService {
 
           if (response.ok) {
             const data = await response.json() as { csrfToken?: string };
-            this.logger.debug('CSRF response data:', data);
             const token = data.csrfToken || null;
+            this.logger.debug('CSRF response data:', {
+              hasCsrfToken: typeof token === 'string' && token.length > 0,
+              csrfTokenLength: token?.length,
+            });
             this.tokenStore.setCsrfToken(token);
             this.logger.debug('CSRF token fetched');
             return token;

package/src/OxyServices.base.ts

@@ -287,8 +287,9 @@ export class OxyServicesBase {
 
     try {
       const decoded = jwtDecode<JwtPayload>(accessToken);
-      this._cachedUserId = decoded.userId || decoded.id || null;
-      return this._cachedUserId;
+      const userId = decoded.userId || decoded.id || null;
+      this._cachedUserId = userId;
+      return userId;
     } catch {
       this._cachedUserId = null;
       return null;

package/src/OxyServices.ts

@@ -153,7 +153,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   signUpWithRedirect(options?: RedirectAuthOptions): void;
 
   // Central cross-domain SSO (opaque single-use code exchange)
-  exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+  exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
   generateSsoState(): string;
 
   // Express.js middleware

package/src/__tests__/authManager.security.test.ts

@@ -164,6 +164,37 @@ describe('AuthManager.switchAuthuser — concurrency lock', () => {
   });
 });
 
+describe('AuthManager default storage selection', () => {
+  const originalWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
+
+  afterEach(() => {
+    if (originalWindow) {
+      Object.defineProperty(globalThis, 'window', originalWindow);
+    } else {
+      Reflect.deleteProperty(globalThis, 'window');
+    }
+  });
+
+  it('falls back to memory storage when localStorage access throws', () => {
+    const blockedWindow = {};
+    Object.defineProperty(blockedWindow, 'localStorage', {
+      configurable: true,
+      get() {
+        throw new DOMException('Blocked localStorage', 'SecurityError');
+      },
+    });
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      value: blockedWindow,
+    });
+
+    expect(() => new AuthManager(makeMockServices() as unknown as OxyServices, {
+      autoRefresh: false,
+      crossTabSync: false,
+    })).not.toThrow();
+  });
+});
+
 describe('AuthManager.switchAuthuser — hydration of unknown slots', () => {
   it('hydrates a slot with no prior user metadata via getCurrentUser()', async () => {
     const services = makeMockServices();

package/src/__tests__/httpServiceCsrf.test.ts

@@ -157,4 +157,79 @@ describe('HttpService CSRF behavior', () => {
     expect(headers.Authorization).toBeUndefined();
     expect(headers['X-CSRF-Token']).toBe('csrf_1');
   });
+
+  it('includes credentials for configured API origin requests', async () => {
+    const calls: FetchCall[] = [];
+    globalThis.fetch = async (input, init) => {
+      calls.push({ url: String(input), init });
+      return jsonResponse({ ok: true });
+    };
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+
+    await http.get('/users/me');
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://api.oxy.so/users/me');
+    expect(calls[0].init?.credentials).toBe('include');
+  });
+
+  it('omits credentials for caller-supplied absolute URLs outside the configured API origin', async () => {
+    const calls: FetchCall[] = [];
+    globalThis.fetch = async (input, init) => {
+      calls.push({ url: String(input), init });
+      return jsonResponse({ ok: true });
+    };
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+
+    await http.get('https://attacker.oxy.so/collect');
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://attacker.oxy.so/collect');
+    expect(calls[0].init?.credentials).toBe('omit');
+  });
+
+  it('bypasses request deduplication for the internal CSRF retry', async () => {
+    const calls: FetchCall[] = [];
+    let csrfFetches = 0;
+    let postFetches = 0;
+
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
+      calls.push({ url, init });
+
+      if (url.endsWith('/csrf-token')) {
+        csrfFetches += 1;
+        return new Response(JSON.stringify({ csrfToken: `csrf_${csrfFetches}` }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+
+      postFetches += 1;
+      if (postFetches === 1) {
+        return new Response(JSON.stringify({ code: 'CSRF_TOKEN_INVALID' }), {
+          status: 403,
+          statusText: 'Forbidden',
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+
+      return jsonResponse({ ok: true });
+    };
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+
+    await expect(http.post('/posts', { text: 'hello' })).resolves.toEqual({ ok: true });
+    expect(calls.map((call) => call.url)).toEqual([
+      'https://api.mention.earth/csrf-token',
+      'https://api.mention.earth/posts',
+      'https://api.mention.earth/csrf-token',
+      'https://api.mention.earth/posts',
+    ]);
+
+    expect(readHeaders(calls[1].init)['X-CSRF-Token']).toBe('csrf_1');
+    expect(readHeaders(calls[3].init)['X-CSRF-Token']).toBe('csrf_2');
+  });
 });

package/src/crypto/__tests__/canonicalJson.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical JSON tests.
+ *
+ * The whole point of `canonicalize` is that two structurally-equal values
+ * produce identical strings regardless of how their keys were ordered, so a
+ * client which signs and a server which verifies agree on the signing input.
+ * These tests pin that determinism, the array-order guarantee, the nesting
+ * behaviour, and the JSON value/omit semantics.
+ */
+
+import { canonicalize } from '../canonicalJson';
+
+describe('canonicalize', () => {
+  describe('object key ordering', () => {
+    it('produces identical output regardless of insertion order', () => {
+      const a = canonicalize({ b: 1, a: 2, c: 3 });
+      const b = canonicalize({ c: 3, a: 2, b: 1 });
+      const c = canonicalize({ a: 2, b: 1, c: 3 });
+      expect(a).toBe(b);
+      expect(b).toBe(c);
+      expect(a).toBe('{"a":2,"b":1,"c":3}');
+    });
+
+    it('sorts keys recursively at every level', () => {
+      const value = {
+        z: { y: 1, x: 2 },
+        a: { c: 3, b: { e: 5, d: 4 } },
+      };
+      expect(canonicalize(value)).toBe(
+        '{"a":{"b":{"d":4,"e":5},"c":3},"z":{"x":2,"y":1}}',
+      );
+    });
+
+    it('is order-insensitive across deep nesting', () => {
+      const first = canonicalize({
+        outer: { inner: { p: 1, q: 2 }, lead: 'x' },
+        meta: { issuedAt: 10, version: 1 },
+      });
+      const second = canonicalize({
+        meta: { version: 1, issuedAt: 10 },
+        outer: { lead: 'x', inner: { q: 2, p: 1 } },
+      });
+      expect(first).toBe(second);
+    });
+  });
+
+  describe('array ordering', () => {
+    it('preserves array element order (never sorts arrays)', () => {
+      expect(canonicalize([3, 1, 2])).toBe('[3,1,2]');
+      expect(canonicalize(['b', 'a', 'c'])).toBe('["b","a","c"]');
+    });
+
+    it('distinguishes arrays that differ only in order', () => {
+      expect(canonicalize([1, 2])).not.toBe(canonicalize([2, 1]));
+    });
+
+    it('canonicalizes objects inside arrays without reordering the array', () => {
+      const value = [
+        { b: 1, a: 2 },
+        { d: 3, c: 4 },
+      ];
+      expect(canonicalize(value)).toBe('[{"a":2,"b":1},{"c":4,"d":3}]');
+    });
+  });
+
+  describe('primitives', () => {
+    it('serializes null, booleans, strings and numbers as JSON', () => {
+      expect(canonicalize(null)).toBe('null');
+      expect(canonicalize(true)).toBe('true');
+      expect(canonicalize(false)).toBe('false');
+      expect(canonicalize('hi')).toBe('"hi"');
+      expect(canonicalize(42)).toBe('42');
+      expect(canonicalize(-1.5)).toBe('-1.5');
+      expect(canonicalize(0)).toBe('0');
+    });
+
+    it('escapes strings the same way JSON does', () => {
+      expect(canonicalize('a"b\\c\n')).toBe(JSON.stringify('a"b\\c\n'));
+    });
+  });
+
+  describe('JSON value/omit semantics', () => {
+    it('omits object properties whose value is undefined', () => {
+      expect(canonicalize({ a: 1, b: undefined, c: 3 })).toBe('{"a":1,"c":3}');
+    });
+
+    it('renders undefined array elements as null (preserving length)', () => {
+      expect(canonicalize([1, undefined, 3])).toBe('[1,null,3]');
+    });
+
+    it('respects toJSON (Date and its ISO string canonicalize identically)', () => {
+      const date = new Date('2026-06-26T00:00:00.000Z');
+      expect(canonicalize(date)).toBe(JSON.stringify(date.toISOString()));
+      expect(canonicalize({ at: date })).toBe(
+        canonicalize({ at: '2026-06-26T00:00:00.000Z' }),
+      );
+    });
+  });
+
+  describe('rejects values outside the JSON data model', () => {
+    it('throws on non-finite numbers', () => {
+      expect(() => canonicalize(NaN)).toThrow();
+      expect(() => canonicalize(Infinity)).toThrow();
+      expect(() => canonicalize({ x: Infinity })).toThrow();
+    });
+
+    it('throws on bigint', () => {
+      expect(() => canonicalize(BigInt(1))).toThrow();
+    });
+
+    it('throws on a bare undefined / function at the top level', () => {
+      expect(() => canonicalize(undefined)).toThrow();
+      expect(() => canonicalize(() => 1)).toThrow();
+    });
+  });
+});

package/src/crypto/__tests__/keyManager.atomicity.test.ts

@@ -21,7 +21,7 @@ import { setPlatformOS } from '../../utils/platform';
 // Fault-injectable in-memory secure store. `failPlan` lets a test make a
 // specific (op, key) pair throw to simulate a keychain that fails mid-write or
 // is transiently locked.
-const failPlan: { failKey?: string; failOp?: 'set' | 'get' } = {};
+const failPlan: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number } = {};
 
 jest.mock(
   'expo-secure-store',
@@ -29,6 +29,14 @@ jest.mock(
     const store = new Map<string, string>();
     const maybeFail = (op: 'set' | 'get', key: string) => {
       if (failPlan.failOp === op && failPlan.failKey === key) {
+        if (failPlan.failTimes !== undefined) {
+          failPlan.failTimes -= 1;
+          if (failPlan.failTimes <= 0) {
+            failPlan.failKey = undefined;
+            failPlan.failOp = undefined;
+            failPlan.failTimes = undefined;
+          }
+        }
         throw new Error(`Simulated ${op} failure for ${key}`);
       }
     };
@@ -51,6 +59,7 @@ jest.mock(
         store.clear();
         failPlan.failKey = undefined;
         failPlan.failOp = undefined;
+        failPlan.failTimes = undefined;
       },
       __getStore__: () => store,
       __failPlan__: failPlan,
@@ -92,7 +101,7 @@ jest.mock('../../utils/platformCrypto', () => ({
 interface SecureStoreTestHandle {
   __resetStore__: () => void;
   __getStore__: () => Map<string, string>;
-  __failPlan__: { failKey?: string; failOp?: 'set' | 'get' };
+  __failPlan__: { failKey?: string; failOp?: 'set' | 'get'; failTimes?: number };
 }
 
 describe('KeyManager atomicity & recoverability under flaky storage', () => {
@@ -146,6 +155,36 @@ describe('KeyManager atomicity & recoverability under flaky storage', () => {
     expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
   });
 
+  it('a failed final backup refresh rejects and rolls back instead of succeeding with a stale backup', async () => {
+    const originalPublic = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    const originalPriv = ss.__getStore__().get('oxy_identity_private_key');
+    resetCaches();
+
+    // Let the new primary write and verify, then fail exactly once while
+    // refreshing the backup to the new identity. This used to return success
+    // with primary=B and backup=A, enabling a later absent-primary restore to
+    // silently switch back to A.
+    ss.__failPlan__.failOp = 'set';
+    ss.__failPlan__.failKey = 'oxy_identity_backup_public_key';
+    ss.__failPlan__.failTimes = 1;
+    await expect(KeyManager.createIdentity({ overwrite: true })).rejects.toBeDefined();
+
+    resetCaches();
+
+    // The operation failed atomically: primary and backup both still identify
+    // the original account, so callers cannot observe success with a stale
+    // cross-account backup.
+    expect(await KeyManager.hasIdentity()).toBe(true);
+    expect(await KeyManager.getPublicKey()).toBe(originalPublic);
+    const m = ss.__getStore__();
+    expect(m.get('oxy_identity_private_key')).toBe(originalPriv);
+    expect(m.get('oxy_identity_public_key')).toBe(originalPublic);
+    expect(m.get('oxy_identity_backup_private_key')).toBe(originalPriv);
+    expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
+  });
+
+
   it('restoreIdentityFromBackup does NOT clobber a healthy primary that is only transiently unreadable', async () => {
     const original = await KeyManager.createIdentity();
     const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;

package/src/crypto/__tests__/signChallengeShared.test.ts

@@ -0,0 +1,64 @@
+/**
+ * `signChallengeWithSharedKey` tests.
+ *
+ * Verifies the shared-key challenge signer mirrors `signChallenge` exactly —
+ * same `auth:${publicKey}:${challenge}:${timestamp}` message format so the
+ * server verification path is unchanged — but sources the SHARED key from
+ * `KeyManager` (not the primary device key). We mock the shared key access with
+ * a REAL elliptic secp256k1 keypair so signing/verification is genuine.
+ */
+
+import { ec as EC } from 'elliptic';
+import { KeyManager } from '../keyManager';
+import { SignatureService } from '../signatureService';
+
+const ec = new EC('secp256k1');
+
+describe('SignatureService.signChallengeWithSharedKey', () => {
+  const sharedKeyPair = ec.genKeyPair();
+  const sharedPublicKey = sharedKeyPair.getPublic('hex');
+  const sharedPrivateKey = sharedKeyPair.getPrivate('hex');
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('signs with the shared key and uses the unchanged message format', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(sharedPublicKey);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(sharedPrivateKey);
+    // Guard: it must NOT fall back to the primary device key.
+    const primarySpy = jest.spyOn(KeyManager, 'getPublicKey');
+
+    const result = await SignatureService.signChallengeWithSharedKey('chal-123');
+
+    expect(result.publicKey).toBe(sharedPublicKey);
+    expect(typeof result.challenge).toBe('string'); // the signature
+    expect(typeof result.timestamp).toBe('number');
+    expect(primarySpy).not.toHaveBeenCalled();
+
+    // The signature verifies against the SAME message format `signChallenge`
+    // uses, proving the format is unchanged and the shared key signed it.
+    const message = `auth:${sharedPublicKey}:chal-123:${result.timestamp}`;
+    await expect(
+      SignatureService.verify(message, result.challenge, sharedPublicKey),
+    ).resolves.toBe(true);
+  });
+
+  it('throws when no shared identity exists', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(null);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(null);
+
+    await expect(
+      SignatureService.signChallengeWithSharedKey('chal-123'),
+    ).rejects.toThrow(/No shared identity/);
+  });
+
+  it('throws when the shared private key is missing even if the public key is present', async () => {
+    jest.spyOn(KeyManager, 'getSharedPublicKey').mockResolvedValue(sharedPublicKey);
+    jest.spyOn(KeyManager, 'getSharedPrivateKey').mockResolvedValue(null);
+
+    await expect(
+      SignatureService.signChallengeWithSharedKey('chal-123'),
+    ).rejects.toThrow(/No shared identity/);
+  });
+});