@oxyhq/core 18.0.0 → 19.1.0

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/session/__tests__/accountProjection.test.ts

@@ -1,7 +1,9 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
+import { ACCOUNT_KINDS } from '@oxyhq/contracts';
 import type { User } from '../../models/interfaces';
 import type { AccountNode } from '../../mixins/OxyServices.accounts';
 import {
+  isSwitchTargetAccount,
   projectSwitchableAccounts,
   switchableAccountIds,
 } from '../accountProjection';
@@ -49,6 +51,57 @@ const mapOf = (...users: User[]): Map<string, User> => {
 
 const noAvatar = (): undefined => undefined;
 
+describe('isSwitchTargetAccount', () => {
+  /**
+   * EXHAUSTIVE over `ACCOUNT_KINDS`, as one object equality rather than a
+   * per-kind assertion, for two reasons that a `channel → false` spot-check
+   * cannot give:
+   *
+   *  - It distinguishes "excludes channels" from "excludes everything". Three
+   *    kinds must come back `true` here, so a predicate that answered `false`
+   *    unconditionally — the shape that empties a switcher instead of filtering
+   *    it — fails on those three, not on the channel.
+   *  - Adding a sixth kind fails this test with a missing key, forcing the
+   *    decision to be made HERE rather than inherited silently from whichever
+   *    literal comparison happened to be written first.
+   */
+  it('answers by kind for an account the caller merely owns or is a member of', () => {
+    expect(
+      Object.fromEntries(
+        ACCOUNT_KINDS.map((kind) => [kind, isSwitchTargetAccount({ kind, relationship: 'owner' })]),
+      ),
+    ).toEqual({
+      personal: false,
+      organization: true,
+      project: true,
+      bot: true,
+      channel: false,
+    });
+  });
+
+  /**
+   * The `self` ground, and the reason this predicate is not `isActAsEligibleKind`.
+   *
+   * `personal` is act-as INELIGIBLE — assuming somebody's human login would be
+   * impersonation — so a switcher gated on that predicate alone would drop the
+   * caller's OWN account and render an empty list. `GET /accounts` resolves its
+   * caller through `resolveOperatorId`, so a `self` node is always the human
+   * operator's own personal account, even while they operate an org.
+   */
+  it('admits the caller’s own personal account, which is act-as ineligible', () => {
+    expect(isSwitchTargetAccount({ kind: 'personal', relationship: 'self' })).toBe(true);
+    // Same kind, not the caller's own → refused. The `relationship` is doing the
+    // work, so neither half of the predicate can be deleted without a failure.
+    expect(isSwitchTargetAccount({ kind: 'personal', relationship: 'member' })).toBe(false);
+  });
+
+  it('refuses an account with no kind information rather than assuming', () => {
+    expect(isSwitchTargetAccount({})).toBe(false);
+    expect(isSwitchTargetAccount({ kind: null })).toBe(false);
+    expect(isSwitchTargetAccount({ kind: undefined, relationship: 'owner' })).toBe(false);
+  });
+});
+
 describe('projectSwitchableAccounts', () => {
   it('returns [] for null state and empty graph', () => {
     expect(
@@ -138,6 +191,50 @@ describe('projectSwitchableAccounts', () => {
     expect(rows.some((r) => r.kind === 'channel')).toBe(false);
   });
 
+  /**
+   * The same rule as the `isSwitchTargetAccount` matrix above, asserted through
+   * the projection so the WIRING is covered and not just the predicate.
+   *
+   * The fixture deliberately carries one graph-only node of every kind, and
+   * FOUR of the five must survive: a fixture list of channels alone could not
+   * tell "omits channels" from "omits every graph-only row", which is the
+   * failure mode that would silently empty an operator's switcher of the orgs
+   * they actually work in. `a1` is a device row and is asserted separately, so
+   * the graph lane's output is never confused with the device lane's.
+   */
+  it('keeps every switchable kind while dropping the channel (graph lane)', () => {
+    const rows = projectSwitchableAccounts({
+      state: state([{ accountId: 'a1', sessionId: 's1' }], 'a1'),
+      graph: [
+        graphNode('self1', { kind: 'personal', relationship: 'self' }),
+        graphNode('org1', { kind: 'organization' }),
+        graphNode('proj1', { kind: 'project' }),
+        graphNode('bot1', { kind: 'bot' }),
+        graphNode('chan1', { kind: 'channel' }),
+      ],
+      profilesById: mapOf(
+        user('a1'),
+        user('self1'),
+        user('org1'),
+        user('proj1'),
+        user('bot1'),
+        user('chan1'),
+      ),
+      resolveAvatarUrl: noAvatar,
+    });
+
+    expect(rows.map((r) => r.accountId)).toEqual(['a1', 'self1', 'org1', 'proj1', 'bot1']);
+    // Stated the other way round too, so a fixture that stopped reaching the
+    // graph lane at all could not pass this as a vacuous "no channels found".
+    expect(rows.map((r) => r.kind)).toEqual([
+      undefined,
+      'personal',
+      'organization',
+      'project',
+      'bot',
+    ]);
+  });
+
   it('dedups an account present as BOTH device session and graph node into ONE enriched row', () => {
     const rows = projectSwitchableAccounts({
       state: state([{ accountId: 'a1', sessionId: 's1', authuser: 0 }], 'a1'),
@@ -232,11 +329,21 @@ describe('switchableAccountIds', () => {
     expect(switchableAccountIds(null, [])).toEqual([]);
   });
 
-  it('omits a graph-only channel, so no profile is fetched for a dropped row', () => {
+  /**
+   * Must stay in lockstep with the projection's own filter in BOTH directions:
+   * an id fetched for a dropped row is wasted work, but an id NOT fetched for a
+   * row the projection keeps is worse — that row has no profile, so the
+   * projection's device lane skips it and it silently never renders.
+   */
+  it('applies the same switch-target filter as the projection', () => {
     const ids = switchableAccountIds(null, [
+      graphNode('self1', { kind: 'personal', relationship: 'self' }),
       graphNode('org1', { kind: 'organization' }),
+      graphNode('proj1', { kind: 'project' }),
+      graphNode('bot1', { kind: 'bot' }),
       graphNode('chan1', { kind: 'channel' }),
+      graphNode('other1', { kind: 'personal', relationship: 'member' }),
     ]);
-    expect(ids).toEqual(['org1']);
+    expect(ids).toEqual(['bot1', 'org1', 'proj1', 'self1']);
   });
 });

package/src/session/accountProjection.ts

@@ -103,6 +103,38 @@ export interface SwitchableAccount {
   user: SwitchableAccountUser;
 }
 
+/**
+ * Whether the caller can BECOME this account — the one question every account
+ * switcher asks, answered here so no surface has to re-derive it.
+ *
+ * Two independent grounds, either of which suffices:
+ *
+ *  - **It is already the caller's own identity** (`relationship: 'self'`).
+ *    `GET /accounts` resolves its caller through `resolveOperatorId`, so `self`
+ *    is the HUMAN operator's personal account even while they are operating an
+ *    org — never the operated account. Kind is irrelevant on this ground: the
+ *    caller IS that account, so returning to it asks the server for nothing.
+ *  - **The server will mint a session for it** — `isActAsEligibleKind(kind)` is
+ *    the exact predicate `POST /accounts/:id/switch` enforces, so a row offered
+ *    on this ground is never a dead button.
+ *
+ * `isActAsEligibleKind` ALONE is not this question, and reaching for it
+ * directly is the mistake this function exists to prevent: it is false for
+ * `personal` as well as `channel`, so a switcher gated on it alone renders an
+ * empty list rather than a filtered one. Equally, `kind !== 'channel'` is not
+ * this question either — it silently admits every kind invented after it was
+ * written, which is the same trap `isActAsEligibleKind` was introduced to close
+ * on the server.
+ *
+ * Takes a structural subset rather than a whole {@link AccountNode} so a caller
+ * holding a projected {@link SwitchableAccount} can ask it too.
+ */
+export function isSwitchTargetAccount(
+  node: { kind?: AccountKind | null; relationship?: AccountRelationship },
+): boolean {
+  return node.relationship === 'self' || isActAsEligibleKind(node.kind);
+}
+
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
   /**
@@ -144,8 +176,9 @@ export interface ProjectSwitchableAccountsInput {
  * and a graph node is deduped into ONE device row enriched with the graph
  * metadata (relationship / kind / parent / membership).
  *
- * Graph nodes of a kind nobody may act as (`channel`) are omitted — see the
- * filter below.
+ * Graph nodes that are not switch targets — a `channel`, which nobody may act
+ * as — are omitted. {@link isSwitchTargetAccount} is the rule; see the filter
+ * below.
  */
 export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[] {
   const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -236,10 +269,12 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
     // construction": the graph contributes accounts that have no device session
     // and no credentials at all, which is exactly how an org first becomes
     // switchable. So a kind that must never be switched into has to be filtered
-    // HERE, and `isActAsEligibleKind` is the same predicate the server enforces
-    // on `POST /accounts/:id/switch` — offering a row the server would 403 is a
-    // dead button.
-    if (!isActAsEligibleKind(node.kind)) {
+    // HERE — offering a row the server would 403 is a dead button.
+    //
+    // An account already on the device skipped this check via the branch above,
+    // and correctly: whatever its kind, the caller is signed into it, so
+    // switching is a local activation that asks the server for nothing.
+    if (!isSwitchTargetAccount(node)) {
       continue;
     }
     remember(toRow(node.account, {
@@ -263,8 +298,11 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME act-as filter as {@link projectSwitchableAccounts} to graph
- * nodes, so this never fetches a profile for a row the projection will drop.
+ * Applies the SAME {@link isSwitchTargetAccount} filter as
+ * {@link projectSwitchableAccounts} to graph nodes, so this never fetches a
+ * profile for a row the projection will drop — and, just as importantly, never
+ * SKIPS one the projection will keep, which would leave that row unrendered
+ * until some later fetch happened to resolve it.
  */
 export function switchableAccountIds(
   state: DeviceSessionState | null,
@@ -277,7 +315,7 @@ export function switchableAccountIds(
     }
   }
   for (const node of graph) {
-    if (node.accountId && isActAsEligibleKind(node.kind)) {
+    if (node.accountId && isSwitchTargetAccount(node)) {
       ids.add(node.accountId);
     }
   }

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

package/src/utils/accountCacheSweep.ts

@@ -0,0 +1,93 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that serve the ACCOUNT FOREST
+ * — the caller's accessible accounts, as lists and as individual detail rows —
+ * and the one sweep that clears them.
+ *
+ * WHY THIS IS NOT A METHOD ON THE ACCOUNTS MIXIN
+ * ---------------------------------------------
+ * `AccountNode.account` is a whole `User`, so a forest read embeds the very
+ * profile the identity reads serve. That makes an IDENTITY write a writer of
+ * these keys too: `updateProfile` edits the caller's own personal account,
+ * which is a row in `GET /accounts` and is its own `GET /accounts/<id>`. Leave
+ * those cached and the account switcher keeps drawing the pre-edit name and
+ * picture for the full TTL, against a perfectly healthy server.
+ *
+ * The mixins compose into one class at runtime but are typed one at a time, so
+ * the user mixin cannot call a method the accounts mixin owns. The key list
+ * therefore lives here, once, and every writer calls {@link
+ * evictOxyAccountForestCache} — exactly like the identity key list in
+ * `identityCacheSweep`, which the accounts mixin already calls for the
+ * mirror-image case (an account write staling the identity reads). The
+ * alternative — a second hand-written copy of these keys in the other mixin —
+ * is the drift that shipped the two stale-profile bugs `identityCacheSweep`
+ * documents.
+ *
+ * WHY THE LIST NEEDS A PREFIX AND THE DETAIL DOES NOT
+ * --------------------------------------------------
+ * `listAccounts({tree?})` keys the flat list as `GET:/accounts` and every
+ * option variant as `GET:/accounts?<query>` (the query string is part of the
+ * URL, hence of the key), and a writer cannot enumerate which variants a caller
+ * has read. The detail key, by contrast, is derivable from the account id the
+ * writer already holds.
+ *
+ * The `GET:/accounts?` prefix matches ONLY the query-string list variants —
+ * never `GET:/accounts/<id>` or its `…/members`, `…/credentials`, `…/children`
+ * sub-resources, which are the accounts mixin's own business and stay there.
+ */
+
+import type { OxyIdentityCacheEvictor } from './identityCacheSweep';
+
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Reused from
+ * `identityCacheSweep` rather than re-declared: it is the SDK's one published
+ * name for these two methods, and a second identical interface would be one
+ * more shape to keep in step.
+ */
+export type OxyAccountCacheEvictor = OxyIdentityCacheEvictor;
+
+/** The cache key `listAccounts()` reads under with no options. */
+export const OXY_ACCOUNT_LIST_CACHE_KEY = 'GET:/accounts';
+
+/**
+ * The prefix covering every option-carrying `listAccounts(opts)` variant
+ * (`?tree=true`, …), none of which a writer can enumerate.
+ */
+export const OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX = 'GET:/accounts?';
+
+/**
+ * Prefix covering every per-account sub-resource cache key
+ * (`GET:/accounts/<id>`, `…/members`, `…/credentials`, `…/children`). A
+ * membership mutation on an ancestor must sweep ALL of these, not only the
+ * account named in the path: descendant member rosters embed inherited rows
+ * resolved from that ancestor, and the writer cannot enumerate which descendant
+ * ids a caller has already read. The trailing slash deliberately excludes the
+ * forest list keys (`GET:/accounts`, `GET:/accounts?…`) documented above.
+ */
+export const OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = 'GET:/accounts/';
+
+/**
+ * Build the exact cache key `getAccount(accountId)` reads under.
+ */
+export function oxyAccountDetailCacheKey(accountId: string): string {
+  return `GET:/accounts/${encodeURIComponent(accountId)}`;
+}
+
+/**
+ * Sweep an `OxyServices` GET response cache of the account forest.
+ *
+ * @param oxy       - Anything exposing the SDK's two eviction methods.
+ * @param accountId - The account whose detail row to drop as well. Optional: a
+ *                    writer that changed the SHAPE of the forest rather than one
+ *                    account in it (create, archive, ownership transfer) has no
+ *                    detail row to name, and clears only the lists.
+ */
+export function evictOxyAccountForestCache(
+  oxy: OxyAccountCacheEvictor,
+  accountId?: string,
+): void {
+  oxy.clearCacheEntry(OXY_ACCOUNT_LIST_CACHE_KEY);
+  oxy.clearCacheByPrefix(OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX);
+  if (accountId) {
+    oxy.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
+  }
+}

package/src/utils/identityCacheSweep.ts

@@ -0,0 +1,104 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that can carry a single
+ * account's identity, and the one sweep that clears them.
+ *
+ * WHY THIS IS ONE LIST
+ * --------------------
+ * An Oxy account is readable under SEVERAL cache keys, and a write that only
+ * busts the key it happens to know about leaves every other one serving the
+ * pre-write snapshot for up to its TTL — from the caller's OWN in-memory cache,
+ * with a perfectly healthy server. That failure has already shipped twice with
+ * two different sets of keys:
+ *
+ *   - `updateAccount` busted `GET:/accounts/<id>` and the account lists, but a
+ *     profile screen reads `GET:/profiles/username/<name>` and
+ *     `GET:/users/<id>`, so a channel's new picture stayed invisible for the
+ *     full 5-minute profile TTL.
+ *   - `updateProfile` busted four of the six keys below, missing
+ *     `GET:/auth/lookup/` (the login-flow avatar/display-name lookup) and
+ *     `GET:/profiles/resolve` (handle resolution) — two independently-drifted
+ *     copies of a list that has to agree.
+ *
+ * So the list lives here, once, and every writer calls
+ * {@link evictOxyIdentityCache}. Adding a new identity read means adding its key
+ * HERE and every writer inherits it.
+ *
+ * WHERE THE LINE IS DRAWN
+ * -----------------------
+ * These are the SINGLE-PROFILE reads — the account is the subject of the
+ * response and is addressable by id, handle, or session. Reads that merely
+ * CONTAIN an account among many (`GET:/profiles/search`,
+ * `GET:/users/<other>/followers`, `GET:/profiles/<other>/similar`) are
+ * deliberately NOT swept: an account cannot be located in them without the very
+ * lookup being invalidated, so sweeping them means sweeping the whole namespace
+ * on every identity change — a real cost on a backend consuming the
+ * cross-service invalidation signal, for a surface where a stale thumbnail
+ * expires on its own in ~2 minutes.
+ *
+ * WHY PREFIXES RATHER THAN EXACT KEYS
+ * -----------------------------------
+ * Only the by-id key can be built from a user id. The handle-keyed and
+ * session-keyed entries cannot — deriving a handle from an id needs the lookup
+ * we are invalidating, and the SDK never tracks active session ids centrally.
+ * Prefix sweeping is also what makes a USERNAME CHANGE correct: the entry under
+ * the OLD handle is unreachable by construction (nothing in the write response
+ * carries it), and a sweep targeted at the new handle alone would leave the old
+ * one serving the pre-rename profile until its TTL. Over-eviction costs a
+ * refetch; under-eviction serves wrong data.
+ *
+ * Platform-neutral by construction (no imports, no `OxyServices` reference) so
+ * the client mixins and the Node-only `@oxyhq/core/server` invalidation
+ * subscriber can share it without either pulling in the other.
+ */
+
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Declared
+ * structurally so this module stays free of any client import.
+ */
+export interface OxyIdentityCacheEvictor {
+  clearCacheEntry(key: string): void;
+  clearCacheByPrefix(prefix: string): number;
+}
+
+/**
+ * Cache-key PREFIXES under which an account's identity can be served, for the
+ * reads whose key cannot be derived from a user id. Swept wholesale.
+ */
+export const OXY_IDENTITY_CACHE_PREFIXES: readonly string[] = [
+  // `getUserBySession` — keyed by session id, which the SDK never enumerates.
+  'GET:/session/user/',
+  // `getCurrentUser` (and `GET:/users/me/graph`, harmlessly included).
+  'GET:/users/me',
+  // `lookupUsername` — the pre-session login lookup; carries avatar + display name.
+  'GET:/auth/lookup/',
+  // `getProfileByUsername` — keyed by handle, including the pre-rename handle.
+  'GET:/profiles/username/',
+  // `resolveProfile` — keyed by fediverse handle in the query payload.
+  'GET:/profiles/resolve',
+];
+
+/**
+ * Build the exact cache key `getUserById` reads under. The only identity key
+ * derivable from a user id, so the only one that does not need a prefix sweep.
+ */
+export function oxyUserByIdCacheKey(userId: string): string {
+  return `GET:/users/${userId}`;
+}
+
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given account's identity.
+ *
+ * @param oxy    - Anything exposing the SDK's two eviction methods.
+ * @param userId - The account whose by-id entry to drop. Optional: a caller
+ *                 that does not know the id still clears every handle-, session-
+ *                 and self-keyed entry, which is the majority of the surface.
+ */
+export function evictOxyIdentityCache(oxy: OxyIdentityCacheEvictor, userId?: string): void {
+  for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
+    oxy.clearCacheByPrefix(prefix);
+  }
+  if (userId) {
+    oxy.clearCacheEntry(oxyUserByIdCacheKey(userId));
+  }
+}