@oxyhq/core 17.1.0 → 19.0.0

package/src/mixins/OxyServices.accounts.ts

@@ -33,10 +33,11 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
-import type { AccountKind, OrganizationCategory } from '@oxyhq/contracts';
+import type { AccountCategoryId, AccountKind, ChildAccountKind } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { normalizeUserIdentity } from '../utils/userIdentity';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
 import { CACHE_TIMES } from './mixinHelpers';
 
 // ---------------------------------------------------------------------------
@@ -52,8 +53,16 @@ import { CACHE_TIMES } from './mixinHelpers';
  *
  * Single source of truth is `@oxyhq/contracts`.
  */
-export type { AccountKind, OrganizationCategory } from '@oxyhq/contracts';
-export { ACCOUNT_KINDS, ORGANIZATION_CATEGORIES, isActAsEligibleKind } from '@oxyhq/contracts';
+export type { AccountCategoryId, AccountKind } from '@oxyhq/contracts';
+export {
+  ACCOUNT_CATEGORY_IDS,
+  ACCOUNT_KINDS,
+  MAX_ACCOUNT_CATEGORIES,
+  SELECTABLE_ACCOUNT_CATEGORY_IDS,
+  isActAsEligibleKind,
+  isSelectableAccountCategoryId,
+  kindAcceptsAccountCategories,
+} from '@oxyhq/contracts';
 
 /**
  * The calling user's relationship to an account node, as resolved by the API:
@@ -146,13 +155,23 @@ export interface ListAccountsOptions {
   tree?: boolean;
 }
 
-/** Kinds a signed-in user may create via `POST /accounts`. Channels are service-provisioned only. */
-export type UserCreatableAccountKind = 'organization' | 'project' | 'bot';
-
 /** Input accepted by `createAccount`. */
 export interface CreateAccountInput {
-  /** Classification of the new account. `personal` and `channel` are not creatable here. */
-  kind: UserCreatableAccountKind;
+  /**
+   * Classification of the new account. Every CHILD kind is creatable here with
+   * the caller's own bearer, `channel` included: a signed-in person has already
+   * proven who they are, and minting a child under their own tree is the same
+   * operation whichever kind it is.
+   *
+   * `channel` used to be excluded, on the reasoning that channels are
+   * service-provisioned only. What actually makes a channel safe does not depend
+   * on who creates it: `createChildAccount` writes no auth method, so it is born
+   * with no login, and `POST /accounts/:id/switch` refuses it via
+   * `isActAsEligibleKind`, so no session can ever have a channel as its subject
+   * and therefore no bearer exists that could add one. `personal` is excluded
+   * because it is a human login, minted at signup.
+   */
+  kind: ChildAccountKind;
   /**
    * Parent account `_id` to nest the new account under. Omitted → the API roots
    * it under the caller's personal account.
@@ -169,8 +188,17 @@ export interface CreateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   bio?: string;
   avatar?: string;
-  /** Meaningful only when `kind` is `organization`. */
-  organizationCategory?: OrganizationCategory;
+  /**
+   * What the account is about. ORDERED — the FIRST element is the primary
+   * category, so a picker must submit them in the order the user arranged them
+   * and must not sort. Stable ids, never labels: render each one through the
+   * `accounts.accountCategory.<id>` translation key.
+   *
+   * Offer `SELECTABLE_ACCOUNT_CATEGORY_IDS`, not `ACCOUNT_CATEGORY_IDS` — the
+   * latter still contains withdrawn ids so that accounts already carrying one
+   * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
+   */
+  accountCategories?: AccountCategoryId[];
 }
 
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
@@ -185,8 +213,19 @@ export interface UpdateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   bio?: string | null;
   avatar?: string | null;
-  /** Clears the category when `null`; only valid on `kind: 'organization'`. */
-  organizationCategory?: OrganizationCategory | null;
+  /**
+   * Replaces the WHOLE list, in the order given — there is no add/remove verb,
+   * because a partial edit cannot express a re-ordering and the order is what
+   * names the primary category. `[]` clears it.
+   *
+   * Not nullable, unlike `bio` and `avatar`: the empty case already has a
+   * spelling of its own, so a second one could only ever disagree with it.
+   *
+   * Rejected for a `personal` account, and rejected when it ADDS a withdrawn
+   * id the account did not already carry — keeping or re-ordering one it has is
+   * always allowed.
+   */
+  accountCategories?: AccountCategoryId[];
 }
 
 /** Input accepted by `provisionChannelAccount` (service token + `accounts:provision`). */
@@ -726,6 +765,18 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
     /**
      * Update an account's mutable profile fields. Tree placement changes
      * (reparenting) go through the dedicated move endpoint, not here.
+     *
+     * An account IS a user, so this write changes identity — and a profile
+     * screen never reads `/accounts/<id>`. It reads `GET /users/<id>` and
+     * `GET /profiles/username/<handle>`, both cached for 5 minutes in the
+     * CALLER'S OWN process, so busting only the account-graph keys left every
+     * profile surface serving the pre-edit avatar and name for the full TTL
+     * with a perfectly healthy server (the cross-service `oxy:user:invalidate`
+     * signal does not help: it evicts BACKEND caches, and cannot reach a cache
+     * living in a browser tab). {@link evictOxyIdentityCache} owns that key
+     * list — see its docs for why the handle-keyed entries are prefix-swept
+     * (a RENAME leaves the old handle's entry unreachable by any targeted key).
+     *
      * @param accountId - The account's Mongo `_id`.
      * @param data - Subset of updatable profile fields.
      */
@@ -744,6 +795,16 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
         // data) so neither serves the pre-update snapshot.
         this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
         this._invalidateAccountLists();
+        // The parent's children list embeds this account's profile and is keyed
+        // by the PARENT id, so it is reachable only from the response node.
+        const parentAccountId = res.account?.parentAccountId;
+        if (parentAccountId) {
+          this.clearCacheEntry(
+            `GET:/accounts/${encodeURIComponent(parentAccountId)}/children`,
+          );
+        }
+        // Every identity read of this account, whichever key it lands under.
+        evictOxyIdentityCache(this, accountId);
         return res.account;
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/OxyServices.deviceBoot.ts

@@ -70,8 +70,9 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
      * `POST /session/device/token` — NO bearer, NO cookies: possession of the
      * secret IS the device-ownership proof. Returns a fresh short access token
-     * for the device's active account plus `nextDeviceSecret` (rotation-in-use)
-     * and the projected device-session `state`.
+     * for the device's active account plus `nextDeviceSecret` (on mint, the same
+     * proven secret echoed back — rotation happens on sign-in, not mint) and
+     * the projected device-session `state`.
      *
      * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
      * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-

package/src/mixins/OxyServices.user.ts

@@ -28,6 +28,7 @@ import {
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
 import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
@@ -534,13 +535,15 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     /**
      * Update user profile.
      *
-     * Invalidates the SDK-side response cache for every endpoint that
-     * returns the current user (`GET /users/me`, `GET /session/user/*`,
-     * `GET /users/<id>`, `GET /profiles/username/*`) so the next read
-     * doesn't return a stale snapshot. Without this, a follow-up
-     * `getUserBySession` call inside the 2-minute cache window can return
-     * the pre-update user — most visibly during onboarding, where it
-     * causes the username step to flicker back as if nothing was saved.
+     * Invalidates the SDK-side response cache for every endpoint that can
+     * return this user — the list is owned by {@link evictOxyIdentityCache}, so
+     * a new identity read is added in one place instead of to each writer
+     * separately (this method's own hand-written copy had already drifted from
+     * the server-side one, missing `GET /auth/lookup/*` and
+     * `GET /profiles/resolve`). Without the sweep a follow-up
+     * `getUserBySession` inside the cache window returns the pre-update user —
+     * most visibly during onboarding, where the username step flickers back as
+     * if nothing was saved.
      *
      * TanStack Query handles offline queuing automatically.
      */
@@ -550,15 +553,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false }),
         );
 
-        // Bust every cached representation of the current user. We use a
-        // prefix sweep rather than an enumeration because the SDK never
-        // tracks the set of active session IDs centrally.
-        this.clearCacheByPrefix('GET:/session/user/');
-        this.clearCacheByPrefix('GET:/users/me');
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        if (result?.id) {
-          this.clearCacheEntry(`GET:/users/${result.id}`);
-        }
+        evictOxyIdentityCache(this, result?.id);
 
         return result;
       } catch (error) {
@@ -615,10 +610,9 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         const result = await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
-        this.clearCacheByPrefix('GET:/session/user/');
-        this.clearCacheByPrefix('GET:/users/me');
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheEntry(`GET:/users/${id}`);
+        // Privacy settings ride the user DTO, so every identity read goes stale
+        // too — same key list as any other profile write.
+        evictOxyIdentityCache(this, id);
         this.clearCacheEntry(`GET:/privacy/${id}/privacy`);
         return result;
       } catch (error) {

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.