@oxyhq/core 3.10.0 → 3.11.0

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

@@ -225,9 +225,9 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Express.js middleware that enforces a specific service-token scope.
          *
          * Mount AFTER `auth()` / `serviceAuth()` — relies on `req.serviceApp` and
-         * (when delegation is in effect) `req.serviceActingAs.scopes`. The scope
-         * is granted if EITHER list contains it, mirroring the OAuth2 model where
-         * the app's app-level scopes and the per-user delegated scopes both count.
+         * (when delegation is in effect) `req.serviceActingAs.scopes`. App-only
+         * service requests require the app scope. Delegated user requests require
+         * BOTH the app scope and the per-user delegation scope.
          *
          * Requests authenticated as a regular user (no service token) are rejected
          * with 403 — scope-protected endpoints are service-to-service by design.

package/dist/types/mixins/index.d.ts

@@ -11,6 +11,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';
@@ -37,7 +38,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & 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>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

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/fapiAutoDetect.d.ts

@@ -20,10 +20,9 @@
  *   - SSR / non-browser (no `window`).
  *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
  *   - Hostnames with fewer than two labels.
- *   - Hostnames whose trailing two labels form a known multi-part public
- *     suffix (e.g. `co.uk`), where the naive `labels.slice(-2)` apex would be
- *     an attacker-registrable suffix like `auth.co.uk` rather than the real
- *     registrable domain.
+ *   - Hostnames where a registrable domain cannot be determined from the
+ *     Public Suffix List, including private hosted suffixes such as
+ *     `github.io`, `pages.dev`, and `netlify.app`.
  *
  * When the page is already loaded ON the IdP itself (`auth.<anything>`),
  * the helper returns the current origin so the SDK keeps everything
@@ -35,21 +34,8 @@
  * is required for end-to-end FedCM correctness — no per-RP config.
  */
 /**
- * Known multi-part public suffixes where the registrable domain is the LAST
- * THREE labels, not two. Deriving an apex from `labels.slice(-2)` against any
- * of these would yield an attacker-registrable suffix (e.g. `auth.co.uk`),
- * so we bail out instead.
- *
- * This is intentionally a small, explicit allow-list rather than the full
- * Public Suffix List — it covers the suffixes the Oxy ecosystem's RPs use.
- * Any multi-part-TLD RP MUST extend this set (or wire in a proper PSL check)
- * before relying on this helper, otherwise auto-detection silently bails to
- * `undefined` and the consumer must pass `authWebUrl` explicitly.
- */
-export declare const MULTIPART_TLDS: ReadonlySet<string>;
-/**
- * Compute the bare registrable apex (eTLD+1) of a hostname, guarding against
- * multi-part public suffixes.
+ * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
+ * Suffix List, including private hosted suffixes.
  *
  * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
  * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
@@ -61,10 +47,7 @@ export declare const MULTIPART_TLDS: ReadonlySet<string>;
  *   - IPv4 literals (`192.168.1.10`);
  *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
  *   - single-label hosts (`intranet`, `localhost`);
- *   - hosts whose trailing two labels form a known multi-part public suffix
- *     (e.g. `foo.co.uk`), where `labels.slice(-2)` would yield an
- *     attacker-registrable suffix (`co.uk`) rather than a real registrable
- *     domain. Such hosts MUST configure `authWebUrl` explicitly.
+ *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
  *
  * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
  * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.

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.0",
+  "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,13 +98,14 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.2.1",
+    "@oxyhq/contracts": "^0.3.0",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
     "socket.io-client": "^4.8.1",
+    "tldts": "^7.0.22",
     "zod": "^3.25.64"
   },
   "peerDependencies": {

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__/authSocket.test.ts

@@ -0,0 +1,96 @@
+import { OxyServices } from '../OxyServices';
+
+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)}.forged-signature`;
+}
+
+async function runAuthSocket(oxy: OxyServices, token: string) {
+  const socket: {
+    handshake: { auth: { token: string } };
+    data?: Record<string, unknown>;
+    user?: { id: string; userId: string; sessionId?: string | null };
+  } = { handshake: { auth: { token } } };
+  let nextError: Error | undefined;
+
+  await oxy.authSocket()(socket, (err?: Error) => {
+    nextError = err;
+  });
+
+  return { socket, nextError };
+}
+
+describe('authSocket', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('rejects decoded JWT payloads that do not include a server-validated session', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const fetchMock = jest.fn();
+    globalThis.fetch = fetchMock;
+
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'victimUserId',
+      exp: 4102444800,
+    }));
+
+    expect(nextError?.message).toBe('Session required');
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(socket.data?.userId).toBeUndefined();
+    expect(socket.user).toBeUndefined();
+  });
+
+  it('rejects tokens whose decoded user does not match the validated session user', async () => {
+    globalThis.fetch = async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-24T00:00:00.000Z',
+        user: { id: 'realUserId', username: 'real', publicKey: 'pub_1' },
+      });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'victimUserId',
+      sessionId: 'session_1',
+      exp: 4102444800,
+    }));
+
+    expect(nextError?.message).toBe('Session user mismatch');
+    expect(socket.data?.userId).toBeUndefined();
+    expect(socket.user).toBeUndefined();
+  });
+
+  it('attaches the validated session user when the decoded user matches', async () => {
+    globalThis.fetch = async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-24T00:00:00.000Z',
+        user: { id: 'user_1', username: 'nate', publicKey: 'pub_1' },
+      });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'user_1',
+      sessionId: 'session_1',
+      exp: 4102444800,
+    }));
+
+    expect(nextError).toBeUndefined();
+    expect(socket.data?.userId).toBe('user_1');
+    expect(socket.data?.sessionId).toBe('session_1');
+    expect(socket.user).toEqual({ id: 'user_1', userId: 'user_1', sessionId: 'session_1' });
+  });
+});

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();
+    });
+  });
+});