@oxyhq/core 17.1.0 → 19.0.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/refresh.ts

@@ -88,10 +88,10 @@ export interface RefreshDeps {
  * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
  * the re-mint handler and the cold boot can react per the transport contract
  * without re-classifying the raw error:
- *  - `ok` — minted, persisted the rotated secret, planted the token.
+ *  - `ok` — minted, persisted `nextDeviceSecret`, planted the token.
  *  - `no-secret` — the store holds no `deviceId` + `deviceSecret` to mint from.
  *  - `invalid-secret` — 401 `invalid_device_secret`: the presented secret
- *    diverged (another tab/device rotated it past the grace window).
+ *    no longer matches the server's stored hash.
  *  - `no-session` — 401 `no_active_session`: the device is known but has no live
  *    session (authoritative signed-out).
  *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
@@ -99,10 +99,10 @@ export interface RefreshDeps {
  *    The device secret is FINE — it is the identity binding that went stale, so
  *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
- *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
- *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
- *    deliberately NOT planted: advertising a healthy session on a secret that
- *    will not survive a reload is exactly the divergence that logs users out.
+ *  - `persist-failed` — the mint succeeded but `nextDeviceSecret` could NOT be
+ *    durably persisted. The token is deliberately NOT planted: advertising a
+ *    healthy session on a secret that will not survive a reload is exactly the
+ *    divergence that logs users out.
  */
 export type DeviceSecretMintOutcome =
   | { status: 'ok'; token: string; sessionId: string; userId: string }
@@ -114,19 +114,14 @@ export type DeviceSecretMintOutcome =
   | { status: 'persist-failed' };
 
 /**
- * Arm 1 — the rotating device-secret mint, run under the owning client's
- * PROCESS-WIDE single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ * Arm 1 — the device-secret mint, run under the owning client's PROCESS-WIDE
+ * single-flight (`httpService.runSingleFlightDeviceSecretMint`).
  *
- * The server ROTATES the presented `deviceSecret` on every successful mint and
- * the just-presented secret is valid only for a short grace window. If two lanes
- * (cold boot, the proactive scheduler, a request-time preflight, a 401 retry,
- * the socket token transport, or a tab-focus reconcile) minted concurrently they
- * would double-rotate the server and the durable store could converge on the
- * SUPERSEDED secret — after the grace window the next cold boot mint 401s and the
- * user is signed out. Routing EVERY lane through this one single-flight makes
- * concurrent callers await the SAME in-flight mint and all receive its result, so
- * there is exactly one rotation and the store always converges on the true
- * `current` secret.
+ * Concurrent lanes (cold boot, the proactive scheduler, a request-time preflight,
+ * a 401 retry, the socket token transport, or a tab-focus reconcile) must not
+ * each persist a different view of the mint response. Routing EVERY lane through
+ * this one single-flight makes concurrent callers await the SAME in-flight mint
+ * and all receive its result, so the durable store converges on one credential.
  *
  * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
  * the access token; a failed durable persist yields `persist-failed` WITHOUT
@@ -200,8 +195,8 @@ export async function refreshDeviceSecretArm(deps: {
       expiresAt: mint.expiresAt,
       ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
     };
-    // Rotation-in-use anti-loss: persist the NEXT secret and read-back-VERIFY it
-    // landed BEFORE planting the token. A failed durable persist must NOT plant.
+    // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
+    // A failed durable persist must NOT plant.
     const persistedOk = await store.save(next);
     if (!persistedOk) {
       return { status: 'persist-failed' };

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