@oxyhq/core 18.0.0 → 19.0.0

package/src/mixins/__tests__/identityWriteCacheInvalidation.test.ts

@@ -0,0 +1,370 @@
+/**
+ * Identity-cache invalidation for the profile WRITERS, against the REAL
+ * response cache.
+ *
+ * An account IS a user, and a profile screen never reads `/accounts/<id>` — it
+ * reads `GET /users/<id>` and `GET /profiles/username/<handle>`, both cached for
+ * five minutes in the caller's own process. `updateAccount` used to bust only
+ * the account-graph keys, so for up to five minutes after an edit a refetch
+ * handed back the PRE-EDIT profile from the client's own cache, with a
+ * perfectly healthy server ("I changed my channel's picture and it doesn't
+ * update until I reload the page").
+ *
+ * These tests drive the real `HttpService` cache over a mocked `fetch` rather
+ * than spying on `clearCacheEntry` / `clearCacheByPrefix`, because a spy proves
+ * only that SOME string was passed — not that the entry a read actually lands
+ * under was evicted. The load-bearing case is the RENAME: an implementation
+ * that busts the exact key for the handle in the write RESPONSE passes every
+ * assertion about the new handle while leaving the OLD handle's entry serving
+ * the pre-rename profile until its TTL. Both handles are warmed here so the two
+ * implementations disagree.
+ *
+ * `updateProfile` is covered here too, because it carried a SECOND, drifted
+ * hand-written copy of the same key list — it swept four of the six keys,
+ * missing `GET:/auth/lookup/` and `GET:/profiles/resolve`. Both writers now
+ * share one enumeration (`utils/identityCacheSweep`), and this is where that is
+ * asserted from the outside.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { AccountNode } from '../OxyServices.accounts';
+
+/**
+ * A non-verified JWT whose payload decodes to the given claims — enough for the
+ * cache's identity tag and the bearer preflight (`jwtDecode` never checks a
+ * signature).
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url({
+    exp: Math.floor(Date.now() / 1000) + 3600,
+    ...payload,
+  })}.sig`;
+}
+
+/** A JSON `Response` in the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const ACCOUNT_ID = 'acc1';
+const PARENT_ID = 'root1';
+const OLD_USERNAME = 'oldhandle';
+const NEW_USERNAME = 'newhandle';
+
+/** The write response: the account after a rename + a new picture. */
+const renamedNode: AccountNode = {
+  accountId: ACCOUNT_ID,
+  kind: 'channel',
+  parentAccountId: PARENT_ID,
+  account: {
+    id: ACCOUNT_ID,
+    publicKey: 'pk-acc1',
+    username: NEW_USERNAME,
+    name: { displayName: 'Renamed Channel' },
+    avatar: 'file_new',
+  },
+  relationship: 'owner',
+  callerMembership: null,
+};
+
+describe('updateAccount identity-cache invalidation (real cache)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    oxy = new OxyServices({
+      baseURL: 'http://test.invalid',
+      enableRetry: false,
+      requestTimeout: 1000,
+    });
+    oxy.httpService.setTokens(makeJwt({ userId: 'operator-1' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  /**
+   * Warm every cache entry an account can be served under, plus one unrelated
+   * entry that must SURVIVE. Returns the number of network calls made, so each
+   * assertion below can be expressed as "did this read hit the network again".
+   */
+  async function warmCaches(): Promise<number> {
+    // The profile screen's two reads, under the handle it had BEFORE the edit
+    // and under the id.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: OLD_USERNAME }));
+    await oxy.getProfileByUsername(OLD_USERNAME);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: OLD_USERNAME }));
+    await oxy.getUserById(ACCOUNT_ID);
+
+    // The handle the account is ABOUT to be renamed to may already be warm (a
+    // 404-shaped read, a previous holder, a same-session preview). Warming it
+    // is what makes the old-handle assertion below non-vacuous: an
+    // implementation that busts only the response's handle passes for this one.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    await oxy.getProfileByUsername(NEW_USERNAME);
+
+    // The pre-session login lookup (carries avatar + display name) and handle
+    // resolution — two keys the SDK's own profile-write sweep had drifted away
+    // from, and which no test previously covered from a write.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: true, username: OLD_USERNAME }));
+    await oxy.lookupUsername(OLD_USERNAME);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: OLD_USERNAME }));
+    await oxy.resolveProfile(`@${OLD_USERNAME}@test.invalid`);
+
+    // The account-graph reads.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: renamedNode }));
+    await oxy.getAccount(ACCOUNT_ID);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listAccounts();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listChildAccounts(PARENT_ID);
+
+    // An unrelated cached read. It must survive — the vacuity floor that tells
+    // a targeted sweep from a blanket `clearCache()`.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ count: 3 }));
+    await oxy.httpService.get('/notifications/unread-count', { cache: true });
+
+    return fetchMock.mock.calls.length;
+  }
+
+  /** Perform the rename + picture change. */
+  async function performUpdate(): Promise<void> {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: renamedNode }));
+    await oxy.updateAccount(ACCOUNT_ID, {
+      username: NEW_USERNAME,
+      avatar: 'file_new',
+    });
+  }
+
+  it('warms every read it later asserts on (control: all are cache hits before the write)', async () => {
+    const warmed = await warmCaches();
+
+    // Re-issue every read with no queued response. A cache MISS would call
+    // `fetch`, which now resolves `undefined` and throws — so a green run here
+    // is proof that each entry really is resident, and that the assertions
+    // below are measuring eviction rather than a cache that was never warm.
+    await oxy.getProfileByUsername(OLD_USERNAME);
+    await oxy.getProfileByUsername(NEW_USERNAME);
+    await oxy.getUserById(ACCOUNT_ID);
+    await oxy.lookupUsername(OLD_USERNAME);
+    await oxy.resolveProfile(`@${OLD_USERNAME}@test.invalid`);
+    await oxy.getAccount(ACCOUNT_ID);
+    await oxy.listAccounts();
+    await oxy.listChildAccounts(PARENT_ID);
+    await oxy.httpService.get('/notifications/unread-count', { cache: true });
+
+    expect(fetchMock).toHaveBeenCalledTimes(warmed);
+  });
+
+  it('evicts the OLD handle, not just the handle in the write response', async () => {
+    await warmCaches();
+    await performUpdate();
+    const afterWrite = fetchMock.mock.calls.length;
+
+    // THE assertion. `updateAccount` cannot know the pre-rename handle — it is
+    // in neither the request nor the response — so only a PREFIX sweep of
+    // `GET:/profiles/username/` reaches it. A targeted `clearCacheEntry` for
+    // the response's handle leaves this entry serving the pre-rename profile.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    const refetched = await oxy.getProfileByUsername(OLD_USERNAME);
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite + 1);
+    expect(refetched.username).toBe(NEW_USERNAME);
+  });
+
+  it('evicts the by-id profile read the account detail page uses', async () => {
+    await warmCaches();
+    await performUpdate();
+    const afterWrite = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, avatar: 'file_new' }));
+    const refetched = await oxy.getUserById(ACCOUNT_ID);
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite + 1);
+    expect(refetched.avatar).toBe('file_new');
+  });
+
+  it('evicts the new handle, the login lookup, and handle resolution', async () => {
+    await warmCaches();
+    await performUpdate();
+    let calls = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    await oxy.getProfileByUsername(NEW_USERNAME);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: false, username: OLD_USERNAME }));
+    await oxy.lookupUsername(OLD_USERNAME);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    await oxy.resolveProfile(`@${OLD_USERNAME}@test.invalid`);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+  });
+
+  it('evicts the account detail, the account lists, and the PARENT children list', async () => {
+    await warmCaches();
+    await performUpdate();
+    let calls = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: renamedNode }));
+    await oxy.getAccount(ACCOUNT_ID);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listAccounts();
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    // Keyed by the PARENT id, which is reachable only from the response node —
+    // the child's own id does not build this key.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listChildAccounts(PARENT_ID);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+  });
+
+  it('leaves unrelated cached reads alone (it is a sweep, not a cache wipe)', async () => {
+    await warmCaches();
+    await performUpdate();
+    const afterWrite = fetchMock.mock.calls.length;
+
+    // No queued response: a miss would call `fetch` and throw.
+    const cached = await oxy.httpService.get<{ count: number }>(
+      '/notifications/unread-count',
+      { cache: true },
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite);
+    expect(cached.count).toBe(3);
+  });
+
+  it('does not sweep when the write fails', async () => {
+    await warmCaches();
+    const warmed = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({ message: 'forbidden' }), {
+        status: 403,
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+    await expect(
+      oxy.updateAccount(ACCOUNT_ID, { avatar: 'file_new' }),
+    ).rejects.toThrow();
+
+    // The failed PATCH is one call; every read below must still be a cache hit.
+    await oxy.getProfileByUsername(OLD_USERNAME);
+    await oxy.getUserById(ACCOUNT_ID);
+    await oxy.getAccount(ACCOUNT_ID);
+
+    expect(fetchMock).toHaveBeenCalledTimes(warmed + 1);
+  });
+
+  it('still sweeps the identity keys when the response carries no parent', async () => {
+    await warmCaches();
+    const rootNode: AccountNode = { ...renamedNode, parentAccountId: null };
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: rootNode }));
+    await oxy.updateAccount(ACCOUNT_ID, { avatar: 'file_new' });
+    const afterWrite = fetchMock.mock.calls.length;
+
+    // A root account has no children list to bust, but its identity keys go
+    // stale exactly the same way — the `parentAccountId` guard must not gate
+    // the identity sweep.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, avatar: 'file_new' }));
+    await oxy.getUserById(ACCOUNT_ID);
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite + 1);
+  });
+});
+
+describe('updateProfile identity-cache invalidation (real cache)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  const SELF_ID = 'me-1';
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({
+      baseURL: 'http://test.invalid',
+      enableRetry: false,
+      requestTimeout: 1000,
+    });
+    oxy.httpService.setTokens(makeJwt({ userId: SELF_ID }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  /**
+   * The two keys `updateProfile`'s own hand-written sweep MISSED. They are the
+   * whole point of this block — a test that only re-checked `GET:/users/me` and
+   * `GET:/profiles/username/` would have passed against the drifted version.
+   */
+  it('evicts the login lookup and handle resolution, not just the keys it used to know', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: true, username: 'alice', avatar: 'old' }));
+    await oxy.lookupUsername('alice');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.resolveProfile('@alice@test.invalid');
+
+    // Control: both are warm (a miss would call the un-queued mock and throw).
+    await oxy.lookupUsername('alice');
+    await oxy.resolveProfile('@alice@test.invalid');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.updateProfile({ avatar: 'new' });
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: true, username: 'alice', avatar: 'new' }));
+    await oxy.lookupUsername('alice');
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.resolveProfile('@alice@test.invalid');
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('still evicts the self, by-id and handle reads it always did', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getCurrentUser();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getUserById(SELF_ID);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getProfileByUsername('alice');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getUserBySession('sess-1');
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.updateProfile({ avatar: 'new' });
+
+    let calls = 5;
+    for (const read of [
+      () => oxy.getCurrentUser(),
+      () => oxy.getUserById(SELF_ID),
+      () => oxy.getProfileByUsername('alice'),
+      () => oxy.getUserBySession('sess-1'),
+    ]) {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+      await read();
+      expect(fetchMock).toHaveBeenCalledTimes(++calls);
+    }
+  });
+});

package/src/models/interfaces.ts

@@ -1,6 +1,6 @@
 import type {
   AccountKind,
-  OrganizationCategory,
+  AccountCategoryId,
   UserNameResponse,
   UserRelationship,
   ThemePreference,
@@ -170,8 +170,16 @@ export interface User {
   // Managed account fields
   isManagedAccount?: boolean;
   managedBy?: string;
-  /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
-  organizationCategory?: OrganizationCategory;
+  /**
+   * What this account is about, for any NON-personal account. ORDERED — the
+   * first element is the primary category, and nothing may reorder it.
+   *
+   * Stable ids, not labels: render each through the
+   * `accounts.accountCategory.<id>` translation key so the reader sees their own
+   * language rather than the language of whoever chose it. Absent when the
+   * account has none.
+   */
+  accountCategories?: AccountCategoryId[];
   /**
    * The account's languages as full BCP-47 locales (`language-REGION`, e.g.
    * `en-US`, `es-MX`, `pt-BR`), ordered with the PRIMARY (UI) locale first.

package/src/server/__tests__/userInvalidation.test.ts

@@ -2,10 +2,11 @@ import { OXY_USER_INVALIDATION_CHANNEL } from '@oxyhq/contracts';
 
 import {
   createOxyUserInvalidationHandler,
-  evictOxyIdentityCache,
   publishOxyUserInvalidation,
-  type OxyIdentityCacheEvictor,
 } from '../userInvalidation';
+// The key enumeration this subscriber sweeps is platform-neutral and shared
+// with the client mixins — see `utils/identityCacheSweep` and its own suite.
+import type { OxyIdentityCacheEvictor } from '../../utils/identityCacheSweep';
 
 function makePublisher() {
   const calls: Array<{ channel: string; message: string }> = [];
@@ -200,21 +201,3 @@ describe('@oxyhq/core/server createOxyUserInvalidationHandler', () => {
     expect(() => createOxyUserInvalidationHandler()(validMessage)).not.toThrow();
   });
 });
-
-describe('@oxyhq/core/server evictOxyIdentityCache', () => {
-  it('clears the exact by-id entry and the handle-keyed prefixes', () => {
-    // The by-id key is exact. The handle-keyed ones cannot be derived from an
-    // id without the lookup being invalidated, so they are swept by prefix.
-    const { evictor, entries, prefixes } = makeEvictor();
-    evictOxyIdentityCache(evictor, 'abc123');
-
-    expect(entries).toEqual(['GET:/users/abc123']);
-    expect(prefixes).toEqual([
-      'GET:/session/user/',
-      'GET:/users/me',
-      'GET:/auth/lookup/',
-      'GET:/profiles/username/',
-      'GET:/profiles/resolve',
-    ]);
-  });
-});

package/src/server/index.ts

@@ -86,14 +86,17 @@ export { verifySecret } from './verifySecret';
 // changes, every consuming backend sweeps its caches instead of waiting out a TTL.
 export {
   createOxyUserInvalidationHandler,
-  evictOxyIdentityCache,
   publishOxyUserInvalidation,
 } from './userInvalidation';
 export type {
-  OxyIdentityCacheEvictor,
   OxyInvalidationPublisher,
   OxyUserInvalidationHandlerOptions,
 } from './userInvalidation';
+// The identity-key enumeration itself is platform-neutral (`src/utils/`) so the
+// client mixins and this Node-only subscriber sweep the SAME list — a second
+// copy is what let `updateAccount` and `updateProfile` drift apart.
+export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES } from '../utils/identityCacheSweep';
+export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 
 // Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
 // SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.

package/src/server/userInvalidation.ts

@@ -6,10 +6,10 @@
  * Every Oxy backend caches Oxy identity, and none of them find out when it
  * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
  * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
- * writes the profile (see the `clearCacheEntry` calls in the user mixin) and
- * never when somebody else does — which is the normal case, since profiles are
- * edited in Oxy's own apps. So an avatar or display-name change is invisible to
- * every consuming backend for up to five minutes, per process.
+ * writes the profile (the `evictOxyIdentityCache` calls in the user and accounts
+ * mixins) and never when somebody else does — which is the normal case, since
+ * profiles are edited in Oxy's own apps. So an avatar or display-name change is
+ * invisible to every consuming backend for up to five minutes, per process.
  *
  * oxy-api broadcasts {@link OXY_USER_INVALIDATION_CHANNEL} on the shared Valkey
  * when a user's identity changes. This module is the consumer half: it parses
@@ -58,6 +58,10 @@ import {
   type OxyUserChangeReason,
   type OxyUserInvalidationEvent,
 } from '@oxyhq/contracts';
+import {
+  evictOxyIdentityCache,
+  type OxyIdentityCacheEvictor,
+} from '../utils/identityCacheSweep';
 
 /**
  * The publish surface of a Redis client. Both `ioredis` and `node-redis`
@@ -67,15 +71,6 @@ export interface OxyInvalidationPublisher {
   publish(channel: string, message: string): unknown;
 }
 
-/**
- * The cache-eviction surface of an {@link OxyServices} instance. Declared
- * structurally so this Node-only module does not pull in the client.
- */
-export interface OxyIdentityCacheEvictor {
-  clearCacheEntry(key: string): void;
-  clearCacheByPrefix(prefix: string): number;
-}
-
 /**
  * Broadcast that an Oxy user's record changed.
  *
@@ -202,26 +197,3 @@ export function createOxyUserInvalidationHandler(
     }
   };
 }
-
-/**
- * Sweep an `OxyServices` GET response cache of everything that could carry the
- * given user's identity.
- *
- * The by-id entry is exact. The by-username and resolve entries are keyed by
- * HANDLE, which cannot be derived from an id without the very lookup we are
- * invalidating, so those are swept by prefix — the same imprecision the SDK
- * already accepts when it sweeps its own cache after a local profile write, and
- * bounded by the fact that over-eviction costs a refetch and can never serve
- * wrong data.
- */
-export function evictOxyIdentityCache(oxy: OxyIdentityCacheEvictor, userId: string): void {
-  // Match the sweep the user mixin runs after a local profile write — session-
-  // bound and /users/me entries are keyed without the user id, so they must be
-  // prefix-swept on cross-service invalidation too.
-  oxy.clearCacheByPrefix('GET:/session/user/');
-  oxy.clearCacheByPrefix('GET:/users/me');
-  oxy.clearCacheByPrefix('GET:/auth/lookup/');
-  oxy.clearCacheEntry(`GET:/users/${userId}`);
-  oxy.clearCacheByPrefix('GET:/profiles/username/');
-  oxy.clearCacheByPrefix('GET:/profiles/resolve');
-}

package/src/utils/__tests__/identityCacheSweep.test.ts

@@ -0,0 +1,151 @@
+/**
+ * The identity cache-key enumeration, checked against the keys REAL reads
+ * produce.
+ *
+ * A list-equality assertion on `OXY_IDENTITY_CACHE_PREFIXES` alone would be
+ * satisfied forever by a typo (`GET:/profile/username/`) — it pins the list's
+ * shape, not its correctness. So the load-bearing test here drives each prefix
+ * from the SDK method that actually reads under it, over the real
+ * `HttpService` cache, and asserts the sweep evicts every one. A prefix that
+ * stops matching its read fails here rather than in production.
+ *
+ * The list is shared by every profile writer (`updateProfile`,
+ * `updatePrivacySettings`, `updateAccount`) and by the Node-only
+ * `oxy:user:invalidate` subscriber in `@oxyhq/core/server`, precisely because
+ * two hand-written copies of it had already drifted apart.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import {
+  OXY_IDENTITY_CACHE_PREFIXES,
+  evictOxyIdentityCache,
+  oxyUserByIdCacheKey,
+  type OxyIdentityCacheEvictor,
+} from '../identityCacheSweep';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url({
+    exp: Math.floor(Date.now() / 1000) + 3600,
+    ...payload,
+  })}.sig`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function makeRecordingEvictor() {
+  const entries: string[] = [];
+  const prefixes: string[] = [];
+  const evictor: OxyIdentityCacheEvictor = {
+    clearCacheEntry: (key) => {
+      entries.push(key);
+    },
+    clearCacheByPrefix: (prefix) => {
+      prefixes.push(prefix);
+      return 0;
+    },
+  };
+  return { evictor, entries, prefixes };
+}
+
+describe('evictOxyIdentityCache — the key list', () => {
+  it('sweeps every identity prefix and the exact by-id entry', () => {
+    const { evictor, entries, prefixes } = makeRecordingEvictor();
+    evictOxyIdentityCache(evictor, 'abc123');
+
+    expect(prefixes).toEqual([
+      'GET:/session/user/',
+      'GET:/users/me',
+      'GET:/auth/lookup/',
+      'GET:/profiles/username/',
+      'GET:/profiles/resolve',
+    ]);
+    expect(prefixes).toEqual([...OXY_IDENTITY_CACHE_PREFIXES]);
+    expect(entries).toEqual([oxyUserByIdCacheKey('abc123')]);
+  });
+
+  it('sweeps the prefixes but writes no by-id entry when the id is unknown', () => {
+    const { evictor, entries, prefixes } = makeRecordingEvictor();
+    evictOxyIdentityCache(evictor);
+
+    expect(prefixes).toEqual([...OXY_IDENTITY_CACHE_PREFIXES]);
+    expect(entries).toEqual([]);
+  });
+
+  it('treats an empty-string id as unknown rather than building `GET:/users/`', () => {
+    // `GET:/users/` would be a prefix-shaped key handed to an EXACT-match
+    // deleter, so it evicts nothing while looking like it evicted something.
+    const { evictor, entries } = makeRecordingEvictor();
+    evictOxyIdentityCache(evictor, '');
+    expect(entries).toEqual([]);
+  });
+});
+
+describe('evictOxyIdentityCache — every prefix matches a real read', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  const USER_ID = 'user-77';
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({
+      baseURL: 'http://test.invalid',
+      enableRetry: false,
+      requestTimeout: 1000,
+    });
+    oxy.httpService.setTokens(makeJwt({ userId: USER_ID }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  /** One real read per swept key, each warmed into the real response cache. */
+  const reads: ReadonlyArray<{
+    key: string;
+    warm: (client: OxyServices) => Promise<unknown>;
+  }> = [
+    { key: 'GET:/session/user/', warm: (c) => c.getUserBySession('sess-1') },
+    { key: 'GET:/users/me', warm: (c) => c.getCurrentUser() },
+    { key: 'GET:/auth/lookup/', warm: (c) => c.lookupUsername('alice') },
+    { key: 'GET:/profiles/username/', warm: (c) => c.getProfileByUsername('alice') },
+    { key: 'GET:/profiles/resolve', warm: (c) => c.resolveProfile('@alice@test.invalid') },
+    { key: 'GET:/users/<id>', warm: (c) => c.getUserById(USER_ID) },
+  ];
+
+  it('covers every prefix in the list with a read (no prefix goes unexercised)', () => {
+    // Vacuity floor: adding a prefix to the list without adding the read that
+    // exercises it fails HERE, rather than silently shrinking the test below.
+    expect(reads).toHaveLength(OXY_IDENTITY_CACHE_PREFIXES.length + 1);
+    for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
+      expect(reads.some((read) => read.key === prefix)).toBe(true);
+    }
+  });
+
+  it.each(reads)('evicts the entry warmed by $key', async ({ warm }) => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: USER_ID, username: 'alice' }));
+    await warm(oxy);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Control: the entry really is warm (a miss would call the un-queued mock).
+    await warm(oxy);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    evictOxyIdentityCache(oxy, USER_ID);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: USER_ID, username: 'alice-2' }));
+    await warm(oxy);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});