@oxyhq/core 12.4.1 → 12.5.1

package/dist/types/crypto/polyfill.d.ts

@@ -4,10 +4,22 @@
  * Ensures Buffer and crypto.getRandomValues are available
  * across all platforms (Node.js, Browser, React Native).
  *
- * - Browser/Node.js: Uses native crypto
- * - React Native: Uses expo-crypto (statically imported via the
- *   per-platform `platform/crypto` module in `@oxyhq/protocol` — see that
- *   file's doc-comment for how platform routing works).
+ * Guard order when installing a `getRandomValues` shim (see bottom of file and
+ * {@link cryptoPolyfill}):
+ *
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *      >= 20, modern Hermes). The shim below is only installed when the host is
+ *      missing it, so this branch is the install-time gate.
+ *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
+ *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
+ *      (Node 18 script entrypoints, some embedded hosts) falls back to.
+ *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
+ *      per-platform `platform/crypto` module in `@oxyhq/protocol`).
+ *
+ * Historically step (2) delegated to `@oxyhq/protocol`'s RN-only
+ * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
+ * WebCrypto crashed here instead of getting randomness. It is now a proper
+ * Node-backed implementation.
  */
 import { Buffer } from 'buffer';
 export { Buffer };

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

@@ -2,7 +2,7 @@
  * User Management Methods Mixin
  */
 import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
-import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem } from '@oxyhq/contracts';
+import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem, ThemePreference } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams } from '../utils/apiUtils';
 /**
@@ -292,6 +292,15 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * `PUT /users/me` — same cache-invalidation behaviour as `updateProfile`.
          */
         updateUserPreferences(preferences: Partial<UserPreferences>): Promise<User>;
+        /**
+         * Update the authenticated user's portable theme preference (light/dark/
+         * system + Bloom color-preset key). Persisted on the User document via the
+         * SAME `PUT /users/me` settings path as the other preferences — same cache
+         * invalidation — so the next cold boot serves it on the self/session payload
+         * with no extra network call. The full object is written (both `mode` and
+         * `colorPreset` are required by the API).
+         */
+        updateThemePreference(themePreference: ThemePreference): Promise<User>;
         /**
          * Request account verification
          */

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

@@ -1,4 +1,4 @@
-import type { OrganizationCategory, UserNameResponse } from '@oxyhq/contracts';
+import type { OrganizationCategory, UserNameResponse, UserRelationship, ThemePreference } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -147,6 +147,20 @@ export interface User {
     languages?: string[];
     notificationPreferences?: NotificationPreferences;
     userPreferences?: UserPreferences;
+    /**
+     * Portable theme preference (mode + Bloom color-preset key). Rides the
+     * self/session payload so it is present on the current-user DTO at cold boot
+     * (`useAuth().user.themePreference`) with no extra fetch. Absent until the
+     * user sets it. Updated via `updateThemePreference` / `updateProfile`.
+     */
+    themePreference?: ThemePreference;
+    /**
+     * The authenticated viewer's relationship to THIS profile. Populated ONLY on
+     * single-profile fetches (`getProfileByUsername` / `getUserById`) when the
+     * request is authenticated; absent for anonymous requests, self-views, and
+     * bulk fetches — so `undefined` means "unknown", not "not following".
+     */
+    relationship?: UserRelationship;
     [key: string]: unknown;
 }
 /**

package/dist/types/server/safeFetch.d.ts

@@ -91,6 +91,8 @@ export interface SafeFetchOptions {
     method?: string;
     /** Extra request headers. A `User-Agent` is added if none is provided. */
     headers?: Record<string, string>;
+    /** Request body for POST/PUT/PATCH. */
+    body?: string | Buffer;
     /**
      * Maximum number of redirects to follow (each re-validated). Defaults to
      * {@link MAX_REDIRECTS}. Set to `0` to disallow redirects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.4.1",
+  "version": "12.5.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -111,7 +111,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.16.0",
+    "@oxyhq/contracts": "^0.17.0",
     "@oxyhq/protocol": "^0.1.5",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

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

@@ -0,0 +1,109 @@
+/**
+ * Crypto polyfill — `getRandomValues` install + platform routing.
+ *
+ * Regression coverage for the latent Node crash: when a Node runtime ships
+ * WITHOUT a global WebCrypto (Node 18 script entrypoints, some embedded hosts),
+ * the installed `getRandomValues` shim must be backed by `node:crypto` and MUST
+ * NOT fall through to `@oxyhq/protocol`'s RN-only `getRandomBytesRN` stub (which
+ * throws `Tried to load 'expo-crypto...' outside React Native`).
+ */
+
+// Controllable stand-ins for `@oxyhq/protocol`'s platform predicates. Names are
+// `mock`-prefixed so the (hoisted) `jest.mock` factory may reference them.
+const mockGetRandomBytesRN = jest.fn<Uint8Array, [number]>();
+const mockState = { isNodeJS: true };
+
+jest.mock('@oxyhq/protocol', () => ({
+  isNodeJS: () => mockState.isNodeJS,
+  getRandomBytesRN: (byteCount: number) => mockGetRandomBytesRN(byteCount),
+}));
+
+type CryptoLike = {
+  getRandomValues: <T extends ArrayBufferView>(array: T) => T;
+};
+
+const ORIGINAL_CRYPTO_DESCRIPTOR = Object.getOwnPropertyDescriptor(globalThis, 'crypto');
+
+/**
+ * Re-run the polyfill module with NO host `globalThis.crypto`, returning the
+ * `getRandomValues` shim it installs. Restores the real global afterwards so
+ * the manipulation never leaks into other tests.
+ */
+function installShimWithoutHostCrypto(): CryptoLike {
+  Object.defineProperty(globalThis, 'crypto', {
+    value: undefined,
+    configurable: true,
+    writable: true,
+  });
+  try {
+    jest.isolateModules(() => {
+      require('../polyfill');
+    });
+    const installed = (globalThis as { crypto?: CryptoLike }).crypto;
+    if (!installed || typeof installed.getRandomValues !== 'function') {
+      throw new Error('polyfill did not install a getRandomValues shim');
+    }
+    return installed;
+  } finally {
+    Object.defineProperty(
+      globalThis,
+      'crypto',
+      ORIGINAL_CRYPTO_DESCRIPTOR ?? { value: undefined, configurable: true, writable: true },
+    );
+  }
+}
+
+beforeEach(() => {
+  mockGetRandomBytesRN.mockReset();
+  mockState.isNodeJS = true;
+});
+
+describe('crypto polyfill getRandomValues', () => {
+  it('on Node without global WebCrypto, fills from node:crypto and never calls the RN stub', () => {
+    mockState.isNodeJS = true;
+    // If the shim ever fell through to the RN path on Node, this would throw —
+    // exactly the latent crash we are guarding against.
+    mockGetRandomBytesRN.mockImplementation(() => {
+      throw new Error('RN getRandomBytesRN must not be called on Node');
+    });
+
+    const shim = installShimWithoutHostCrypto();
+    const array = new Uint8Array(16);
+
+    expect(() => shim.getRandomValues(array)).not.toThrow();
+    // Backed by a real CSPRNG: all-zero output is cryptographically impossible.
+    expect(array.some((byte) => byte !== 0)).toBe(true);
+    expect(mockGetRandomBytesRN).not.toHaveBeenCalled();
+  });
+
+  it('on Node, routes a non-integer view (DataView) through randomFillSync', () => {
+    mockState.isNodeJS = true;
+    mockGetRandomBytesRN.mockImplementation(() => {
+      throw new Error('RN getRandomBytesRN must not be called on Node');
+    });
+
+    const shim = installShimWithoutHostCrypto();
+    const view = new DataView(new ArrayBuffer(16));
+
+    expect(() => shim.getRandomValues(view)).not.toThrow();
+    let anyNonZero = false;
+    for (let i = 0; i < view.byteLength; i += 1) {
+      if (view.getUint8(i) !== 0) anyNonZero = true;
+    }
+    expect(anyNonZero).toBe(true);
+    expect(mockGetRandomBytesRN).not.toHaveBeenCalled();
+  });
+
+  it('on React Native, delegates to expo-crypto via getRandomBytesRN (path unchanged)', () => {
+    mockState.isNodeJS = false;
+    const rnBytes = Uint8Array.from([1, 2, 3, 4, 5, 6, 7, 8]);
+    mockGetRandomBytesRN.mockReturnValue(rnBytes);
+
+    const shim = installShimWithoutHostCrypto();
+    const array = new Uint8Array(8);
+    const result = shim.getRandomValues(array);
+
+    expect(mockGetRandomBytesRN).toHaveBeenCalledWith(8);
+    expect(Array.from(result)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+  });
+});

package/src/crypto/polyfill.ts

@@ -4,14 +4,26 @@
  * Ensures Buffer and crypto.getRandomValues are available
  * across all platforms (Node.js, Browser, React Native).
  *
- * - Browser/Node.js: Uses native crypto
- * - React Native: Uses expo-crypto (statically imported via the
- *   per-platform `platform/crypto` module in `@oxyhq/protocol` — see that
- *   file's doc-comment for how platform routing works).
+ * Guard order when installing a `getRandomValues` shim (see bottom of file and
+ * {@link cryptoPolyfill}):
+ *
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *      >= 20, modern Hermes). The shim below is only installed when the host is
+ *      missing it, so this branch is the install-time gate.
+ *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
+ *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
+ *      (Node 18 script entrypoints, some embedded hosts) falls back to.
+ *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
+ *      per-platform `platform/crypto` module in `@oxyhq/protocol`).
+ *
+ * Historically step (2) delegated to `@oxyhq/protocol`'s RN-only
+ * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
+ * WebCrypto crashed here instead of getting randomness. It is now a proper
+ * Node-backed implementation.
  */
 
 import { Buffer } from 'buffer';
-import { getRandomBytesRN } from '@oxyhq/protocol';
+import { getRandomBytesRN, isNodeJS } from '@oxyhq/protocol';
 
 const getGlobalObject = (): typeof globalThis => {
   if (typeof globalThis !== 'undefined') return globalThis;
@@ -32,25 +44,89 @@ type CryptoLike = {
   getRandomValues: <T extends ArrayBufferView>(array: T) => T;
 };
 
+/** Minimal structural shape of the parts of `node:crypto` this polyfill uses. */
+interface NodeCryptoLike {
+  webcrypto?: {
+    getRandomValues?: <T extends ArrayBufferView>(array: T) => T;
+  };
+  randomFillSync?: <T extends ArrayBufferView>(buffer: T) => T;
+}
+
+/**
+ * Lazily-resolved `node:crypto` module, cached after the first attempt.
+ * `undefined` = not tried yet; `null` = tried and unavailable (non-Node host).
+ */
+let cachedNodeCrypto: NodeCryptoLike | null | undefined;
+
+/**
+ * Synchronously load `node:crypto` on a Node runtime, or `null` elsewhere.
+ *
+ * Uses a guarded, Node-only `require`. Every runtime that actually reaches this
+ * branch has a working CommonJS `require`: `@oxyhq/core` publishes no
+ * `"type": "module"`, so Node loads it as CommonJS and the `require` free
+ * variable is present. Browsers never reach here (they own `globalThis.crypto`,
+ * so this polyfill is never installed) and React Native takes the
+ * `getRandomBytesRN` branch — so the `node:crypto` reference is dead code in
+ * those bundles, and Expo's Metro resolver shims `node:*` builtins, keeping
+ * web/native bundles green.
+ */
+function loadNodeCryptoSync(): NodeCryptoLike | null {
+  if (cachedNodeCrypto !== undefined) {
+    return cachedNodeCrypto;
+  }
+  if (typeof require !== 'function') {
+    cachedNodeCrypto = null;
+    return cachedNodeCrypto;
+  }
+  try {
+    cachedNodeCrypto = require('node:crypto') as NodeCryptoLike;
+  } catch {
+    // No Node crypto (unexpected on a real Node host) — degrade to the next
+    // mechanism rather than crash.
+    cachedNodeCrypto = null;
+  }
+  return cachedNodeCrypto;
+}
+
 /**
- * Synchronous random-bytes shim. On RN, this delegates to
- * `expo-crypto.getRandomBytes` (statically imported by the RN variant of
- * `@oxyhq/protocol`'s `platform/crypto`, so available without any async
- * warm-up). On Node /
- * browser, this throws — but is never called there because both platforms
- * already provide `globalThis.crypto.getRandomValues` natively.
+ * Fill `array` with cryptographically-secure random bytes from `node:crypto`.
+ * Prefers `webcrypto.getRandomValues`; falls back to `randomFillSync`. Returns
+ * `false` when Node crypto is unavailable so the caller can try the next
+ * mechanism.
  */
-function getRandomBytesSync(byteCount: number): Uint8Array {
-  // `getRandomBytesRN` throws on non-RN platforms. That's fine: this
-  // function is only ever called as a fallback when the native
-  // `globalThis.crypto.getRandomValues` is missing, which on a normal
-  // Node/browser host never happens.
-  return getRandomBytesRN(byteCount);
+function fillFromNodeCrypto(array: ArrayBufferView): boolean {
+  const nodeCrypto = loadNodeCryptoSync();
+  if (!nodeCrypto) {
+    return false;
+  }
+  const webcrypto = nodeCrypto.webcrypto;
+  if (webcrypto && typeof webcrypto.getRandomValues === 'function') {
+    try {
+      webcrypto.getRandomValues(array);
+      return true;
+    } catch {
+      // `webcrypto.getRandomValues` rejects non-integer views (Float*Array,
+      // DataView); fall through to `randomFillSync`, which accepts any view.
+    }
+  }
+  if (typeof nodeCrypto.randomFillSync === 'function') {
+    nodeCrypto.randomFillSync(array);
+    return true;
+  }
+  return false;
 }
 
 const cryptoPolyfill: CryptoLike = {
   getRandomValues<T extends ArrayBufferView>(array: T): T {
-    const bytes = getRandomBytesSync(array.byteLength);
+    // Node: back the CSPRNG with `node:crypto`. This is the path that matters on
+    // Node runtimes shipping WITHOUT a global WebCrypto — where delegating to
+    // the RN-only expo-crypto stub would throw.
+    if (isNodeJS() && fillFromNodeCrypto(array)) {
+      return array;
+    }
+    // React Native (and any non-Node host without WebCrypto): synchronous
+    // expo-crypto via @oxyhq/protocol's RN `platform/crypto` variant.
+    const bytes = getRandomBytesRN(array.byteLength);
     const uint8View = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
     uint8View.set(bytes);
     return array;

package/src/mixins/OxyServices.user.ts

@@ -15,6 +15,7 @@ import type {
   UserProfileUpdate,
   RecommendationRequest,
   RecommendationItem,
+  ThemePreference,
 } from '@oxyhq/contracts';
 import { recommendationRequestSchema } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
@@ -628,6 +629,20 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       return this.updateProfile({ userPreferences: preferences });
     }
 
+    /**
+     * Update the authenticated user's portable theme preference (light/dark/
+     * system + Bloom color-preset key). Persisted on the User document via the
+     * SAME `PUT /users/me` settings path as the other preferences — same cache
+     * invalidation — so the next cold boot serves it on the self/session payload
+     * with no extra network call. The full object is written (both `mode` and
+     * `colorPreset` are required by the API).
+     */
+    async updateThemePreference(
+      themePreference: ThemePreference
+    ): Promise<User> {
+      return this.updateProfile({ themePreference });
+    }
+
     /**
      * Request account verification
      */

package/src/models/interfaces.ts

@@ -1,4 +1,9 @@
-import type { OrganizationCategory, UserNameResponse } from '@oxyhq/contracts';
+import type {
+  OrganizationCategory,
+  UserNameResponse,
+  UserRelationship,
+  ThemePreference,
+} from '@oxyhq/contracts';
 
 export interface OxyConfig {
   baseURL: string;
@@ -163,6 +168,20 @@ export interface User {
   notificationPreferences?: NotificationPreferences;
   // General app-wide user preferences. Updated via `PUT /users/me`.
   userPreferences?: UserPreferences;
+  /**
+   * Portable theme preference (mode + Bloom color-preset key). Rides the
+   * self/session payload so it is present on the current-user DTO at cold boot
+   * (`useAuth().user.themePreference`) with no extra fetch. Absent until the
+   * user sets it. Updated via `updateThemePreference` / `updateProfile`.
+   */
+  themePreference?: ThemePreference;
+  /**
+   * The authenticated viewer's relationship to THIS profile. Populated ONLY on
+   * single-profile fetches (`getProfileByUsername` / `getUserById`) when the
+   * request is authenticated; absent for anonymous requests, self-views, and
+   * bulk fetches — so `undefined` means "unknown", not "not following".
+   */
+  relationship?: UserRelationship;
   [key: string]: unknown;
 }
 

package/src/server/safeFetch.ts

@@ -390,6 +390,8 @@ export interface SafeFetchOptions {
   method?: string;
   /** Extra request headers. A `User-Agent` is added if none is provided. */
   headers?: Record<string, string>;
+  /** Request body for POST/PUT/PATCH. */
+  body?: string | Buffer;
   /**
    * Maximum number of redirects to follow (each re-validated). Defaults to
    * {@link MAX_REDIRECTS}. Set to `0` to disallow redirects.
@@ -475,6 +477,7 @@ function fetchOnce(
   options: https.RequestOptions,
   isHttps: boolean,
   headersTimeoutMs: number,
+  body?: string | Buffer,
 ): Promise<IncomingMessage> {
   return new Promise<IncomingMessage>((resolve, reject) => {
     const transport = isHttps ? https : http;
@@ -484,7 +487,7 @@ function fetchOnce(
       req.destroy(new UpstreamError('upstream headers timeout'));
     });
     req.on('error', (err) => reject(err));
-    req.end();
+    req.end(body);
   });
 }
 
@@ -506,6 +509,7 @@ export async function safeFetch(
   const {
     method = 'GET',
     headers: callerHeaders,
+    body,
     maxRedirects = MAX_REDIRECTS,
     headersTimeoutMs = UPSTREAM_HEADERS_TIMEOUT_MS,
     signal,
@@ -548,6 +552,7 @@ export async function safeFetch(
       requestOptions,
       target.protocol === 'https:',
       headersTimeoutMs,
+      body,
     );
 
     const status = response.statusCode ?? 0;