@oxyhq/core 3.10.1 → 3.12.0

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

@@ -0,0 +1,249 @@
+/**
+ * Identity Methods Mixin (self-sovereign identity layer)
+ *
+ * Provides typed access to Oxy's AtProto/Bluesky-flavoured identity &
+ * portability layer:
+ *  - DID resolution (`did:web:oxy.so:u:<userId>`, derived on demand by the API).
+ *  - The auth-method ↔ DID verification-method mapping and its reversibility
+ *    (link/unlink an identity key, link a password) via the existing
+ *    `/auth/link` surface.
+ *  - Signed records: clients sign an envelope with their own cryptographic key
+ *    (`SignatureService.signRecord` + the shared `canonicalize`) and publish it;
+ *    anyone can fetch and verify it.
+ *  - The signed data-export ("credible exit") bundle.
+ *  - Verified-domain badges (prove ownership of `nate.com`).
+ *
+ * Wire shapes come from `@oxyhq/contracts` (`DidDocument`,
+ * `SignedRecordEnvelope`, `AuthMethodsResponse`, `VerifiedDomain`,
+ * `DomainVerificationInstructions`, `ExportBundle`) — the single source of truth
+ * the API validates its output against, so producer and consumer cannot drift.
+ *
+ * Identity signing is NATIVE-ONLY: the private key lives in native secure
+ * storage, so `linkIdentityKey`, `signRecord`, and `publishRecord` require an
+ * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
+ * always `null`).
+ */
+import type { AuthMethodsResponse, DidDocument, DomainVerificationInstructions, ExportBundle, SignedRecordEnvelope, VerifiedDomain } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+/** Record categories a client may sign and publish. */
+export type IdentityRecordType = SignedRecordEnvelope['type'];
+/** Auth-method types that can be unlinked via {@link OxyServicesIdentityMixin}. */
+export type UnlinkableAuthMethodType = 'identity' | 'password' | 'google' | 'apple' | 'github';
+/**
+ * Result of a link/unlink auth-method mutation (`POST /auth/link`,
+ * `DELETE /auth/link/:type`).
+ */
+export interface LinkAuthMethodResult {
+    success: boolean;
+    message: string;
+}
+/**
+ * Result of publishing a signed record (`POST /identity/records`). Echoes the
+ * stored envelope plus the server's verification verdict.
+ */
+export interface PublishRecordResult {
+    envelope: SignedRecordEnvelope;
+    verified: boolean;
+}
+/**
+ * Result of verifying a stored record (`GET /identity/records/:userId/:type/verify`).
+ * `verified` is the server's verdict; `reason` is present when it is `false`.
+ */
+export interface VerifyRecordResult {
+    verified: boolean;
+    reason?: string;
+}
+/** Result of a successful domain verification (`POST /identity/domains/:domain/verify`). */
+export interface VerifyDomainResult {
+    verified: boolean;
+    domain: VerifiedDomain;
+}
+/** Result of removing a verified domain (`DELETE /identity/domains/:domain`). */
+export interface RemoveDomainResult {
+    success: boolean;
+}
+/**
+ * Derive a user's Oxy DID from their stable account id.
+ * `did:web:oxy.so:u:<userId>`.
+ */
+export declare function buildUserDid(userId: string): string;
+export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Resolve the W3C DID document for any user. The API derives it on demand
+         * from the account's `authMethods` + `publicKey` — there is no stored
+         * document. Public (no auth required); short-TTL cached.
+         *
+         * @param userId - The account's Mongo `_id`. URL-encoded into the path.
+         */
+        resolveDid(userId: string): Promise<DidDocument>;
+        /**
+         * The current user's DID (`did:web:oxy.so:u:<userId>`), derived locally from
+         * the access token's user id. Throws if no user is authenticated.
+         */
+        getMyDid(): string;
+        /** Resolve the current user's DID document. Requires an authenticated session. */
+        getMyDidDocument(): Promise<DidDocument>;
+        /**
+         * List the current user's linked authentication methods plus their DID.
+         * Each `identity` method carries a `verificationMethodId` linking it to its
+         * DID verification-method fragment.
+         */
+        listAuthMethods(): Promise<AuthMethodsResponse>;
+        /**
+         * Link the on-device cryptographic identity to the current account,
+         * upgrading it from custodial to self-sovereign. Signs a proof of private
+         * key ownership and posts it to `POST /auth/link`.
+         *
+         * NATIVE-ONLY: requires a stored identity (throws if `KeyManager` has no key
+         * or no user is authenticated). The signed payload is
+         * `JSON.stringify({ action: 'link_identity', userId, timestamp })` — the
+         * exact bytes the server reconstructs and verifies.
+         */
+        linkIdentityKey(): Promise<LinkAuthMethodResult>;
+        /**
+         * Link password authentication to the current account. Adds a `password`
+         * auth method (does not remove existing methods).
+         *
+         * @param email - The email to associate with password auth.
+         * @param password - The new password (server enforces strength rules).
+         */
+        linkPassword(email: string, password: string): Promise<LinkAuthMethodResult>;
+        /**
+         * Unlink an authentication method from the current account. The server
+         * refuses to remove the last remaining method (the account would become
+         * inaccessible). Unlinking `identity` downgrades the account to custodial.
+         *
+         * @param type - The auth-method type to remove.
+         */
+        unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult>;
+        /**
+         * Sign a record with the on-device identity key, WITHOUT publishing it.
+         * The subject is the current user's DID. NATIVE-ONLY (requires a stored
+         * key). Use {@link publishRecord} to sign and store in one step.
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        signRecord(type: IdentityRecordType, record: Record<string, unknown>): Promise<SignedRecordEnvelope>;
+        /**
+         * Sign a record and publish it to the append-only record store
+         * (`POST /identity/records`). NATIVE-ONLY (requires a stored key).
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        publishRecord(type: IdentityRecordType, record: Record<string, unknown>): Promise<PublishRecordResult>;
+        /**
+         * Fetch a user's most recent signed record of a given type. Public (no auth
+         * required); short-TTL cached.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to fetch.
+         */
+        getRecord(userId: string, type: IdentityRecordType): Promise<SignedRecordEnvelope>;
+        /**
+         * Ask the server to verify a user's stored record: it recomputes the
+         * canonical signing input, checks the signature, and asserts the signing key
+         * is a current verification method on the subject's DID.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to verify.
+         */
+        verifyRecord(userId: string, type: IdentityRecordType): Promise<VerifyRecordResult>;
+        /**
+         * Download the current user's signed, open-format data-export bundle
+         * (`GET /users/me/export`) — the "credible exit" snapshot. Always carries an
+         * Oxy provenance `attestation`; carries an optional client `proof` when the
+         * account holds its own key.
+         */
+        exportMyData(): Promise<ExportBundle>;
+        /**
+         * Start verifying ownership of a domain. Returns the instructions: publish
+         * EITHER the DNS-TXT record OR the `/.well-known/oxy-domain` file, then call
+         * {@link verifyDomain}.
+         *
+         * @param domain - The domain to claim (e.g. `nate.com`).
+         */
+        requestDomainVerification(domain: string): Promise<DomainVerificationInstructions>;
+        /**
+         * Complete domain verification: the server checks the DNS-TXT record or
+         * well-known file and, on success, attaches the domain to the account
+         * (surfaced in the DID's `alsoKnownAs` and the user's `verifiedDomains`).
+         *
+         * @param domain - The domain previously requested via
+         *   {@link requestDomainVerification}.
+         */
+        verifyDomain(domain: string): Promise<VerifyDomainResult>;
+        /** List the current user's verified domains. */
+        listDomains(): Promise<VerifiedDomain[]>;
+        /**
+         * Remove a verified domain from the current account.
+         * @param domain - The verified domain to remove.
+         */
+        removeDomain(domain: string): Promise<RemoveDomainResult>;
+        /**
+         * Bust the cached reads that an identity mutation invalidates: the current
+         * user (`/users/me*`), the linked auth-methods list, the verified-domains
+         * list, and the user's derived DID document (which embeds auth methods +
+         * verified domains, so it goes stale on link/unlink/domain changes).
+         *
+         * Internal helper (leading underscore); not part of the supported public
+         * surface. Public rather than `private` because mixins compose into an
+         * exported anonymous class, where TypeScript cannot represent a private
+         * member in the emitted declaration file (TS4094).
+         */
+        _invalidateIdentityCaches(userId: string | null): void;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getSessionBaseUrl(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

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

@@ -53,9 +53,12 @@ export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Ba
          * @param code - The opaque single-use code delivered in the SSO return
          *   fragment (see {@link parseSsoReturnFragment}). The central store burns
          *   it atomically on exchange.
+         * @param state - The state value returned alongside the code. In browsers,
+         *   when an SSO bounce state is still stored for the current origin, this
+         *   must match before any token-committing exchange is attempted.
          * @returns The resolved {@link SessionLoginResponse}.
          */
-        exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+        exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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';
@@ -28,6 +29,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
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -37,7 +39,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 OxyServicesCivicMixin<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/profileLinks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function normalizeProfileLinks(linksMetadata?: ProfileLinkMetadata[], links?: string[]): ProfileLink[];

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.12.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.4.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');
+  });
 });