@oxyhq/core 3.2.0 → 3.4.0

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

@@ -1,3 +1,4 @@
+import type { UserNameResponse } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -83,14 +84,14 @@ export interface User {
     avatar?: string;
     color?: string;
     privacySettings?: PrivacySettings;
-    name?: {
-        first?: string;
-        last?: string;
-        full?: string;
-        [key: string]: unknown;
-    };
+    /**
+     * Structured human name. The canonical wire shape ({@link UserNameResponse}):
+     * `{ first?, last?, full? }` where `full` is a Mongoose virtual (present only
+     * when the query materialised virtuals). The single source of truth lives in
+     * `@oxyhq/contracts` — do NOT re-declare a bare `string` here.
+     */
+    name?: UserNameResponse;
     bio?: string;
-    karma?: number;
     location?: string;
     website?: string;
     createdAt?: string;
@@ -228,24 +229,6 @@ export interface SearchProfilesResponse {
     data: User[];
     pagination: PaginationInfo;
 }
-export interface KarmaRule {
-    id: string;
-    description: string;
-}
-export interface KarmaHistory {
-    id: string;
-    userId: string;
-    points: number;
-}
-export interface KarmaLeaderboardEntry {
-    userId: string;
-    total: number;
-}
-export interface KarmaAwardRequest {
-    userId: string;
-    points: number;
-    reason?: string;
-}
 export interface ApiError {
     message: string;
     code: string;
@@ -552,7 +535,13 @@ export interface UpdateDeviceNameResponse {
 export interface RefreshAllAccountUser {
     id: string;
     username: string;
-    name?: string;
+    /**
+     * Structured human name as emitted by `formatUserResponse` (the canonical
+     * {@link UserNameResponse} `{ first?, last?, full? }` subdocument), NOT a bare
+     * string. The server projects `name` verbatim from the user document. The
+     * single source of truth is `@oxyhq/contracts`.
+     */
+    name?: UserNameResponse;
     avatar?: string | null;
     email?: string;
     color?: string | null;

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

@@ -32,6 +32,14 @@ export interface DisplayNameUserShape {
         full?: string;
         [key: string]: unknown;
     };
+    /**
+     * Pre-resolved display name as emitted by the server's `displayName` virtual
+     * (raw `/users/me` responses). NOTE: the server virtual resolves to
+     * `username || truncatedPublicKey || 'Anonymous'` — it does NOT compose the
+     * structured `name`. It is therefore preferred only AFTER a real structured
+     * name, so a first-name-only account never collapses to its username/key.
+     */
+    displayName?: string;
     username?: string;
     publicKey?: string;
 }
@@ -44,11 +52,16 @@ export declare const formatPublicKeyHandle: (publicKey: string) => string;
  * Resolve a friendly display name for a user.
  *
  * Order of preference:
- *  1. `name.full`, or composed `name.first name.last`
+ *  1. `name.full`, or composed `name.first name.last` (FIRST-NAME-ONLY SAFE —
+ *     a user with only a first name resolves to that first name, never to the
+ *     lowercase username; this is the exact drift bug the auth app hit).
  *  2. `name` (when stored as a plain string)
- *  3. `username`
- *  4. `Account 0x12345678…` (derived from publicKey, when present)
- *  5. Translated fallback (e.g. "Unnamed")
+ *  3. `displayName` (server `displayName` virtual — `username || truncatedKey`).
+ *     Placed AFTER the structured name on purpose: the server virtual ignores
+ *     `name`, so preferring it first would re-introduce the first-only bug.
+ *  4. `username`
+ *  5. `Account 0x12345678…` (derived from publicKey, when present)
+ *  6. Translated fallback (e.g. "Unnamed")
  *
  * The translation key `common.unnamed` is used for the final fallback. If the
  * caller does not pass a locale, the default English translation is used.

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

@@ -77,9 +77,22 @@ export interface ConsumeSsoReturnDeps {
      * location changed via `history.replaceState`, which does NOT itself emit
      * `popstate`. Default: dispatch a real `PopStateEvent` on `window` when
      * present; no-op off-web. Called ONLY after a successful same-origin
-     * dest restore (never when the dest is rejected/absent). NEVER throws.
+     * dest restore on the `ok` path (never when the dest is rejected/absent).
+     * NEVER throws.
      */
     dispatchPopState?: () => void;
+    /**
+     * Hard, full-document navigation used to leave the internal callback path on
+     * every NON-`ok` outcome (`none`/`error`, state-mismatch, missing code,
+     * failed exchange, missing sessionId). A SOFT `history.replaceState` +
+     * synthetic `popstate` does NOT reliably make Expo Router / TanStack Router
+     * re-resolve away from the 404 they have already rendered for the
+     * unregistered callback route — so for these outcomes (where there is no
+     * in-memory session to preserve) a full navigation is both safe and
+     * guaranteed to clear the 404. Default: `window.location.replace(url)` when
+     * present; feature-detected end to end so it never throws off-web.
+     */
+    hardRedirect?: (url: string) => void;
 }
 /**
  * Consume an SSO return: the commit-free, security-critical kernel of the
@@ -105,14 +118,22 @@ export interface ConsumeSsoReturnDeps {
  *     treated exactly like "no session" (never loops, never rethrows).
  *   - On EVERY consumed outcome (ok, none, error, state-mismatch, no-code,
  *     failed-exchange, no-sessionId) — not just ok — if the page landed on
- *     {@link SSO_CALLBACK_PATH}, the real pre-bounce destination is restored
- *     from the DEST key so the user is never stranded on the internal callback
- *     path. Same-origin only (an attacker-planted cross-origin or relative-evil
- *     dest is rejected). The DEST key is removed unconditionally.
- *   - After a same-origin dest restore (which uses `history.replaceState`, that
- *     does NOT itself emit `popstate`), a synthetic `popstate` is dispatched so
- *     URL-driven routers (Expo Router / React Navigation web) re-sync to the
- *     restored route. It is NOT dispatched when the dest is rejected/absent.
+ *     {@link SSO_CALLBACK_PATH}, the user is taken to a same-origin TARGET so
+ *     they are never stranded on the internal callback path (which is an
+ *     unregistered route in every consumer router → a hard 404). The target is
+ *     the stored DEST when it parses as same-origin (an attacker-planted
+ *     cross-origin / protocol-relative dest is rejected), ELSE the app root
+ *     (`origin + '/'`). The DEST key is removed unconditionally.
+ *   - For the `ok` outcome the target is applied via a SOFT
+ *     `history.replaceState` + synthetic `popstate` so the freshly exchanged
+ *     in-memory session the provider is about to commit is preserved (no
+ *     reload). `popstate` is dispatched only on the `ok` same-origin restore.
+ *   - For every NON-`ok` outcome there is no in-memory session to preserve, and
+ *     the consumer router has ALREADY synchronously rendered its 404 for the
+ *     unregistered callback route — a soft replaceState+popstate does not
+ *     reliably make it re-resolve. So these outcomes perform a HARD
+ *     full-document navigation to the target (`hardRedirect`), which is both
+ *     safe (nothing to lose) and guaranteed to clear the 404 in every router.
  *
  * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
  *

package/package.json

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

package/src/AuthManager.ts

@@ -1071,7 +1071,9 @@ export class AuthManager {
     const hydrated: RefreshAllAccountUser = {
       id: me.id,
       username: me.username,
-      name: typeof me.name === 'string' ? me.name : undefined,
+      // `User.name` and `RefreshAllAccountUser.name` are the same canonical
+      // structured `UserNameResponse` shape, so forward it verbatim.
+      name: me.name,
       avatar: me.avatar ?? null,
       email: me.email,
       color: me.color ?? null,

package/src/HttpService.ts

@@ -675,14 +675,79 @@ export class HttpService {
     return headers;
   }
 
+  /**
+   * Delimiter that separates the logical `method:url[:data]` portion of a
+   * cache key from its identity suffix. Always APPENDED, never used to parse
+   * a key apart, so the `method:url` prefix stays intact for
+   * `clearCacheByPrefix` sweeps and `clearCacheEntry` base-key matching.
+   * The `clearCacheEntry` callsites all pass fixed, dataless logical keys
+   * (`GET:/users/<id>`, `GET:/session/user/<sessionId>`,
+   * `GET:/fedcm/me/authorized-apps`), so this readable suffix can never be
+   * ambiguous with a serialized request body.
+   */
+  private static readonly CACHE_IDENTITY_DELIM = ' id=';
+
+  /**
+   * Derive a stable, non-sensitive identity discriminator for cache scoping.
+   *
+   * The GET-response cache MUST be partitioned by caller identity: endpoints
+   * with optional auth (e.g. `GET /profiles/recommendations`) return different
+   * content for an anonymous vs an authenticated caller, and per-user content
+   * for different authenticated users. Keying solely on `method:url:data`
+   * (the previous behavior) let an anonymous response be served to an
+   * authenticated caller — surfacing as "Who to follow" recommending accounts
+   * the user already follows after a cold-boot session restore.
+   *
+   * We use the access token's decoded user id (`userId || id`) rather than the
+   * raw JWT so the token never lands in a cache key (no token leakage through
+   * any cache-key logging, no key bloat). The acting-as id is folded in because
+   * managed-account responses differ per acting identity — and `X-Acting-As`
+   * already changes the server response for the same bearer token. Falls back
+   * to `'anon'` when there is no token, and to a short FNV-1a hash of the token
+   * only if it is present but cannot be decoded (degraded but still partitioned,
+   * never colliding anon with authed).
+   */
+  private computeIdentityTag(): string {
+    const accessToken = this.tokenStore.getAccessToken();
+    let principal = 'anon';
+    if (accessToken) {
+      try {
+        const decoded = jwtDecode<JwtPayload>(accessToken);
+        principal = decoded.userId || decoded.id || `t${fnv1a32(accessToken)}`;
+      } catch {
+        // Undecodable token — still partition it away from anon and from
+        // other tokens via a hash. Never silently fall back to 'anon'.
+        principal = `t${fnv1a32(accessToken)}`;
+      }
+    }
+    return this._actingAsUserId ? `${principal}~as${this._actingAsUserId}` : principal;
+  }
+
   /**
    * Generate cache key efficiently
    * Uses a content-addressed hash for large payloads so two requests with
    * the same shape but different values never collide on the same key
    * (which would silently serve stale data — e.g. paginated search results,
    * large object updates).
+   *
+   * The key is identity-scoped: the logical `method:url[:data]` portion is
+   * suffixed with ` id=<identityTag>` so two callers with different
+   * identities (anon vs authed, or two different users) never share an entry.
+   * The identity tag is placed at the END so the key still STARTS with
+   * `method:url`, preserving the prefix-based invalidation in
+   * `clearCacheByPrefix` (e.g. `GET:/session/user/`) and the base-key matching
+   * in `clearCacheEntry`.
    */
   private generateCacheKey(method: string, url: string, data?: unknown): string {
+    return `${this.generateBaseCacheKey(method, url, data)}${HttpService.CACHE_IDENTITY_DELIM}${this.computeIdentityTag()}`;
+  }
+
+  /**
+   * Build the identity-agnostic portion of a cache key (`method:url[:data]`).
+   * Kept separate so identity scoping is applied in exactly one place
+   * (`generateCacheKey`) and cannot drift between the cache and dedupe paths.
+   */
+  private generateBaseCacheKey(method: string, url: string, data?: unknown): string {
     if (!data || (typeof data === 'object' && Object.keys(data).length === 0)) {
       return `${method}:${url}`;
     }
@@ -943,6 +1008,15 @@ export class HttpService {
   clearTokens(): void {
     this.tokenStore.clearTokens();
     this.tokenStore.clearCsrfToken();
+    // Drop the response cache on logout. The cache is identity-scoped, so a
+    // different user could never read these entries, but a logged-out client
+    // must not keep the previous session's personalized data resident in
+    // memory (privacy + correct logout semantics). We do NOT clear on
+    // `setTokens` because a silent token refresh re-issues a token for the
+    // SAME user — the identity tag is unchanged and the warm cache is still
+    // valid; clearing there would defeat caching as refreshes fire near
+    // every token expiry.
+    this.cache.clear();
     this.notifyTokenChange();
   }
 
@@ -1001,8 +1075,25 @@ export class HttpService {
     this.cache.clear();
   }
 
+  /**
+   * Delete a cache entry by its LOGICAL key (`method:url[:data]`).
+   *
+   * Because the response cache is identity-scoped — stored keys carry an
+   * ` id=<identityTag>` suffix — a caller passing the logical key
+   * `GET:/users/<id>` must invalidate that resource for EVERY identity that
+   * cached it (e.g. `updateProfile` busting a user representation that may be
+   * cached under both the owner's id and a viewer's id). We therefore delete
+   * the exact key (for any pre-existing un-suffixed entries) AND every
+   * identity-scoped variant `<key> id=*`.
+   */
   clearCacheEntry(key: string): void {
     this.cache.delete(key);
+    const identityVariantPrefix = `${key}${HttpService.CACHE_IDENTITY_DELIM}`;
+    for (const existing of this.cache.keys()) {
+      if (existing.startsWith(identityVariantPrefix)) {
+        this.cache.delete(existing);
+      }
+    }
   }
 
   /**

package/src/OxyServices.ts

@@ -83,7 +83,7 @@ import { composeOxyServices } from './mixins';
  * - **Privacy**: Blocked and restricted users
  * - **Language**: Language detection and metadata
  * - **Payment**: Payment processing
- * - **Karma**: Karma system
+ * - **Reputation**: Reputation system (Oxy Trust)
  * - **Assets**: File upload and asset management
  * - **Applications**: Application, membership, and credential management
  * - **Workspaces**: Workspace and membership management

package/src/__tests__/httpServiceCache.test.ts

@@ -0,0 +1,198 @@
+/**
+ * HttpService response-cache identity-scoping tests.
+ *
+ * Regression coverage for the "Who to follow" bug: the GET-response cache used
+ * to key on only `method:url[:data]`, so an anonymous response cached during a
+ * web cold boot (session still restoring) was served back to the SAME URL once
+ * the session landed (now authenticated) — recommending accounts the user
+ * already follows. These tests pin down that:
+ *
+ *  - an anonymous GET response is NOT served to a later authenticated GET of
+ *    the same URL (different identity tag -> cache miss -> a fresh network call),
+ *  - two different authenticated users never share a cache entry,
+ *  - after `clearTokens()` a previously-cached authenticated response is not
+ *    served to an anonymous caller,
+ *  - the `clearCacheByPrefix` invalidation used by `updateProfile` still works
+ *    against identity-scoped keys.
+ */
+
+import { HttpService } from '../HttpService';
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check),
+ * so a fixed header + base64url(JSON) payload + dummy signature is enough.
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  // Far-future expiry so getAuthHeader() never tries to refresh it.
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('HttpService identity-scoped response cache', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+  const newService = (): HttpService =>
+    new HttpService({
+      baseURL: 'http://test.invalid',
+      enableRetry: false,
+      requestTimeout: 1000,
+    });
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('does NOT serve an anonymous cached GET to a later authenticated caller', async () => {
+    const http = newService();
+
+    // 1) Anonymous GET — caches the public response.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['popular-1', 'popular-2'] }));
+    const anon = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+    expect(anon.profiles).toEqual(['popular-1', 'popular-2']);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Session lands — now authenticated as user-1.
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+
+    // 3) Same URL, authenticated: MUST be a cache miss -> a real network call,
+    //    returning the personalized list (no already-followed accounts).
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['suggested-a', 'suggested-b'] }));
+    const authed = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(authed.profiles).toEqual(['suggested-a', 'suggested-b']);
+  });
+
+  it('serves a warm cache hit to the SAME authenticated identity (no extra network call)', async () => {
+    const http = newService();
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['suggested-a'] }));
+    const first = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+    const second = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+
+    expect(first).toEqual(second);
+    // Only one network call — the second read is a cache hit for the same id.
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('never shares a cache entry between two different authenticated users', async () => {
+    const http = newService();
+
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['for-user-1'] }));
+    const u1 = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+    expect(u1.profiles).toEqual(['for-user-1']);
+
+    // Switch identity to a different user (does not clear cache by itself).
+    http.setTokens(makeJwt({ userId: 'user-2' }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['for-user-2'] }));
+    const u2 = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(u2.profiles).toEqual(['for-user-2']);
+  });
+
+  it('partitions the cache by acting-as identity for the same bearer token', async () => {
+    const http = newService();
+    http.setTokens(makeJwt({ userId: 'owner-1' }));
+
+    // Acting as managed account A.
+    http.setActingAs('managed-a');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ items: ['a-only'] }));
+    const a = await http.get<{ items: string[] }>('/some/managed-resource', { cache: true });
+    expect(a.items).toEqual(['a-only']);
+
+    // Acting as managed account B — different content, must miss the cache.
+    http.setActingAs('managed-b');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ items: ['b-only'] }));
+    const b = await http.get<{ items: string[] }>('/some/managed-resource', { cache: true });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(b.items).toEqual(['b-only']);
+  });
+
+  it('does NOT serve an authenticated cached response to an anonymous caller after clearTokens()', async () => {
+    const http = newService();
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['private-suggestion'] }));
+    const authed = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+    expect(authed.profiles).toEqual(['private-suggestion']);
+
+    // Logout clears the response cache (privacy + correct logout semantics).
+    http.clearTokens();
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['popular-public'] }));
+    const anon = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(anon.profiles).toEqual(['popular-public']);
+  });
+
+  it('still honors clearCacheByPrefix against identity-scoped keys (updateProfile path)', async () => {
+    const http = newService();
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+
+    // Warm a `GET:/session/user/<id>` entry (as updateProfile's prefix targets).
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', name: 'old' }));
+    await http.get('/session/user/sess-1', { cache: true });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A cache hit confirms the entry is warm.
+    await http.get('/session/user/sess-1', { cache: true });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Prefix sweep used by updateProfile must match the identity-scoped key.
+    const removed = http.clearCacheByPrefix('GET:/session/user/');
+    expect(removed).toBe(1);
+
+    // Next read re-fetches (cache was invalidated).
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', name: 'new' }));
+    const after = await http.get<{ id: string; name: string }>('/session/user/sess-1', { cache: true });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(after.name).toBe('new');
+  });
+
+  it('clearCacheEntry busts every identity-scoped variant of a base key', async () => {
+    const http = newService();
+
+    // Anonymous reads /users/u1.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', name: 'anon-view' }));
+    await http.get('/users/u1', { cache: true });
+
+    // Authenticated user reads the same resource — separate cache entry.
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', name: 'authed-view' }));
+    await http.get('/users/u1', { cache: true });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // updateProfile-style exact invalidation must clear BOTH identity variants.
+    http.clearCacheEntry('GET:/users/u1');
+
+    // Both identities now re-fetch.
+    http.setTokens(makeJwt({ userId: 'user-1' }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', name: 'refetched' }));
+    await http.get('/users/u1', { cache: true });
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+});

package/src/constants/version.ts

@@ -6,7 +6,7 @@
 export const packageInfo = {
     name: "@oxyhq/services",
     version: "5.2.1",
-    description: "Reusable OxyHQ module to handle authentication, user management, karma system and more 🚀",
+    description: "Reusable OxyHQ module to handle authentication, user management, reputation system (Oxy Trust) and more 🚀",
     main: "lib/commonjs/node/index.js",
     module: "lib/module/node/index.js",
     types: "lib/typescript/node/index.d.ts"