@oxy.so/core 1.18.0 → 3.0.0

package/src/server/namespaces.ts

@@ -0,0 +1,257 @@
+/**
+ * The server-side halves of the namespaces: what exists only with a service
+ * credential. `OxyServer` returns these from its namespace getters, so
+ * `server.assets.metadataByIds(...)` sits beside every client method of
+ * `oxy.assets`.
+ */
+import type { CreateOxyNotificationRequest, AwardReputationInput, ReputationTransaction, ServiceLinkedAccountListResponse } from '@oxy.so/contracts';
+import type { OxyContext, ServiceLane } from '../client/context';
+import type {
+  Notification,
+  ServiceAssetMetadata,
+  ServiceAssetMetadataBySha,
+  ServiceLinkedDownloadUrl,
+} from '../models/interfaces';
+import { AssetsApi } from '../api/assets';
+import { NotificationsApi } from '../api/notifications';
+import { LinkedAccountsApi } from '../api/linkedAccounts';
+import { AgencyApi, type RequesterAssertionGrant, type RequesterAssertionIntrospection } from '../api/agency';
+import { ReputationApi } from '../api/reputation';
+import { ServiceAssetMetadataError, ServiceLinkedDownloadUrlError } from '../OxyServices.errors';
+import { extractErrorStatus } from '../utils/errorUtils';
+import { logger } from '../logger';
+
+/** Server-side cap of `POST /assets/service/by-ids`. */
+const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
+/** Server-side cap of `POST /assets/service/by-sha256`. */
+const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
+/** Server-side cap of `POST /assets/service/linked-url`. */
+const SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE = 25;
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+
+const REPUTATION_CACHE_PREFIX = 'GET:/reputation/';
+
+function lane(ctx: OxyContext): ServiceLane {
+  if (!ctx.service) {
+    throw new Error('This call needs a service credential (OxyServer from @oxy.so/core/server)');
+  }
+  return ctx.service;
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
+  return chunks;
+}
+
+function uniqueIds(ids: string[]): string[] {
+  return Array.from(new Set(ids.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)));
+}
+
+export class ServerAssetsApi extends AssetsApi {
+  /**
+   * Resolve many asset ids to their content-addressed metadata (`sha256`,
+   * `mime`, `size`, `status`) via `POST /assets/service/by-ids`, one call per
+   * chunk of 100. Service token with `files:read`.
+   *
+   * The server omits unknown/deleted ids, so a short result is normal — map by
+   * `id`. FAILURE IS NOT ABSENCE: a failed chunk throws
+   * {@link ServiceAssetMetadataError} carrying the ids it could not resolve,
+   * unless `{ partial: true }` asks for best-effort. Never cached.
+   */
+  async metadataByIds(ids: string[], options: { partial?: boolean } = {}): Promise<ServiceAssetMetadata[]> {
+    const unique = uniqueIds(ids);
+    if (unique.length === 0) return [];
+
+    const unresolvedIds: string[] = [];
+    const statuses: number[] = [];
+    let firstError: unknown;
+
+    const settled = await Promise.all(
+      chunk(unique, SERVICE_ASSET_METADATA_CHUNK_SIZE).map(async (part): Promise<ServiceAssetMetadata[]> => {
+        try {
+          const entries = await lane(this.ctx).request<ServiceAssetMetadata[]>('POST', '/assets/service/by-ids', { ids: part });
+          return Array.isArray(entries) ? entries : [];
+        } catch (error: unknown) {
+          const status = extractErrorStatus(error);
+          logger.warn('assets.metadataByIds: chunk failed', {
+            method: 'assets.metadataByIds',
+            chunkSize: part.length,
+            status,
+            partial: options.partial === true,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          unresolvedIds.push(...part);
+          if (typeof status === 'number') statuses.push(status);
+          firstError ??= error;
+          return [];
+        }
+      }),
+    );
+
+    if (unresolvedIds.length > 0 && options.partial !== true) {
+      throw new ServiceAssetMetadataError(unresolvedIds, statuses, firstError);
+    }
+    return settled.flat();
+  }
+
+  /**
+   * Mint short-lived direct download URLs for files the calling application's
+   * own users attached to it (`POST /assets/service/linked-url`, scope
+   * `files:linked:read`). The ONLY way a service token reaches file bytes.
+   *
+   * A URL comes back only for a file whose OWN OWNER linked it to this
+   * application; every other id is omitted, and the route answers identically
+   * for "no such file" and "not yours". ABSENCE IS A REFUSAL, not a fact about
+   * the file: decide what to tell your user from your own entitlement record.
+   * A failed chunk throws {@link ServiceLinkedDownloadUrlError}; there is no
+   * partial mode. Never cached — each URL is a live credential.
+   */
+  async linkedDownloadUrls(ids: string[]): Promise<ServiceLinkedDownloadUrl[]> {
+    const unique = uniqueIds(ids);
+    if (unique.length === 0) return [];
+
+    const unresolvedIds: string[] = [];
+    const statuses: number[] = [];
+    let firstError: unknown;
+
+    const settled = await Promise.all(
+      chunk(unique, SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE).map(async (part): Promise<ServiceLinkedDownloadUrl[]> => {
+        try {
+          const entries = await lane(this.ctx).request<ServiceLinkedDownloadUrl[]>('POST', '/assets/service/linked-url', { ids: part });
+          return Array.isArray(entries) ? entries : [];
+        } catch (error: unknown) {
+          const status = extractErrorStatus(error);
+          // `chunkSize` and `status`, never the ids and never a `url`: a minted
+          // URL in a log line is a credential in a log line.
+          logger.warn('assets.linkedDownloadUrls: chunk failed', {
+            method: 'assets.linkedDownloadUrls',
+            chunkSize: part.length,
+            status,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          unresolvedIds.push(...part);
+          if (typeof status === 'number') statuses.push(status);
+          firstError ??= error;
+          return [];
+        }
+      }),
+    );
+
+    if (unresolvedIds.length > 0) {
+      throw new ServiceLinkedDownloadUrlError(unresolvedIds, statuses, firstError);
+    }
+    return settled.flat();
+  }
+
+  /**
+   * Reverse content-address lookup: resolve `sha256` digests to the servable
+   * asset holding each (`POST /assets/service/by-sha256`, scope `files:read`),
+   * with a public `url` for active public assets. Malformed hashes are dropped
+   * client-side; the server omits unknown ones, so map by `sha256`. A failed
+   * chunk is logged and skipped. Never cached.
+   */
+  async metadataBySha256(sha256s: string[]): Promise<ServiceAssetMetadataBySha[]> {
+    const unique = Array.from(
+      new Set(
+        sha256s
+          .filter((sha): sha is string => typeof sha === 'string')
+          .map((sha) => sha.trim().toLowerCase())
+          .filter((sha) => SHA256_HEX_PATTERN.test(sha)),
+      ),
+    );
+    if (unique.length === 0) return [];
+
+    const settled = await Promise.all(
+      chunk(unique, SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE).map(async (part): Promise<ServiceAssetMetadataBySha[]> => {
+        try {
+          const entries = await lane(this.ctx).request<ServiceAssetMetadataBySha[]>('POST', '/assets/service/by-sha256', { sha256s: part });
+          return Array.isArray(entries) ? entries : [];
+        } catch (error: unknown) {
+          logger.warn('assets.metadataBySha256: chunk failed, continuing with remaining chunks', {
+            method: 'assets.metadataBySha256',
+            chunkSize: part.length,
+            status: extractErrorStatus(error),
+            error: error instanceof Error ? error.message : String(error),
+          });
+          return [];
+        }
+      }),
+    );
+    return settled.flat();
+  }
+}
+
+export class ServerNotificationsApi extends NotificationsApi {
+  /**
+   * Create a notification (`POST /notifications`; the application needs
+   * `notifications:write`). `type` is one of `OXY_NOTIFICATION_TYPES` from
+   * `@oxy.so/contracts` — `system` for a message from an Oxy service about the
+   * recipient's own account.
+   */
+  async create(data: CreateOxyNotificationRequest): Promise<Notification> {
+    const res = await lane(this.ctx).request<{ notification: Notification }>('POST', '/notifications', data);
+    return res.notification;
+  }
+}
+
+export class ServerLinkedAccountsApi extends LinkedAccountsApi {
+  /**
+   * A user's live linked accounts, each with the federated shadow user Oxy holds
+   * for it (`federatedUserId`). Needs the privileged `linked-accounts:read`.
+   */
+  async forUser(userId: string): Promise<ServiceLinkedAccountListResponse> {
+    return lane(this.ctx).request<ServiceLinkedAccountListResponse>(
+      'GET',
+      `/linked-accounts/by-user/${encodeURIComponent(userId)}`,
+    );
+  }
+}
+
+export class ServerAgencyApi extends AgencyApi {
+  /**
+   * Product backend → Oxy: trade the signed-in requester's access token for a
+   * one-use assertion naming `agentId` (ADR 0025), authenticated with this
+   * service's credential. `subjectToken` goes to Oxy only, in the body; never
+   * forward it anywhere else. Not retried: a refusal is an answer, and the
+   * caller mints per turn.
+   */
+  async mintRequesterAssertion(input: { agentId: string; subjectToken: string }): Promise<RequesterAssertionGrant> {
+    return lane(this.ctx).request<RequesterAssertionGrant>(
+      'POST',
+      '/internal/native-agents/requester-assertions',
+      { agentId: input.agentId, subjectToken: input.subjectToken },
+      { retry: false, timeout: 5000 },
+    );
+  }
+
+  /**
+   * Audience → Oxy: verify, live-revalidate and CONSUME a present-requester
+   * assertion (ADR 0025). A second call with the same assertion answers
+   * `active: false`. Authenticated with the audience's own service credential.
+   */
+  async introspectRequesterAssertion(input: {
+    assertion: string;
+    presenter: { applicationId: string; credentialId: string };
+  }): Promise<RequesterAssertionIntrospection> {
+    return lane(this.ctx).request<RequesterAssertionIntrospection>(
+      'POST',
+      '/internal/native-agents/requester-assertions/introspect',
+      { assertion: input.assertion, presenter: input.presenter },
+      { retry: false, timeout: 5000 },
+    );
+  }
+}
+
+export class ServerReputationApi extends ReputationApi {
+  /**
+   * Award (or penalise) reputation to a user by `actionType`. Service token with
+   * `reputation:write` only — people never award reputation, and nobody at Oxy
+   * moves it by hand. Invalidates cached reputation reads.
+   */
+  async award(input: AwardReputationInput): Promise<ReputationTransaction> {
+    const res = await lane(this.ctx).request<{ transaction: ReputationTransaction }>('POST', '/reputation/award', input);
+    this.ctx.oxy.cache.deletePrefix(REPUTATION_CACHE_PREFIX);
+    return res.transaction;
+  }
+}

package/src/server/rateLimit.ts

@@ -2,8 +2,8 @@ import { createHmac } from 'node:crypto';
 import { isIPv4, isIPv6 } from 'node:net';
 import type { Request, RequestHandler } from 'express';
 import rateLimit, { type Store } from 'express-rate-limit';
-import type { OxyServices } from '../OxyServices';
-import { createOptionalOxyAuth } from './auth';
+import type { AuthMiddlewareOptions } from './middleware';
+import { createOptionalOxyAuth, type OxyAuthHost } from './auth';
 
 /**
  * Server-only rate limiting for Oxy backends.
@@ -19,7 +19,7 @@ import { createOptionalOxyAuth } from './auth';
  *      ALB) many users share one egress IP, so a single bucket was split across
  *      all of them → frequent, spurious HTTP 429s.
  *
- * `@oxy.so/core` already owns the session: `oxy.auth()` resolves `req.user` /
+ * `@oxy.so/core` already owns the session: `server.middleware.auth()` resolves `req.user` /
  * `req.userId`. Per-user rate limiting is the same concern (session identity),
  * so it belongs here — once — instead of being re-implemented per app.
  *
@@ -78,10 +78,11 @@ export interface OxyRateLimitOptions {
   /** Response message body sent with a 429. */
   message?: string;
   /**
-   * Options forwarded to the internal `oxy.auth({ optional: true })` resolver
-   * (e.g. `{ jwtSecret }` to verify service tokens). `optional` is forced true.
+   * Options forwarded to the internal `server.middleware.auth({ optional: true })` resolver
+   * (e.g. `{ serviceTokenJwksUrl }` to verify service tokens against a
+   * non-default JWKS). `optional` is forced true.
    */
-  auth?: Parameters<OxyServices['auth']>[0];
+  auth?: AuthMiddlewareOptions;
 }
 
 /**
@@ -207,7 +208,7 @@ function hashAnonymousIp(ip: string): string {
  *
  * Only identities that came from a server-validated session or a verified
  * service token/delegation may pick a bucket. `req.sessionId` is the marker
- * for the former: `oxy.auth()` sets it only after `validateSession()` came
+ * for the former: `server.middleware.auth()` sets it only after `session.validate()` came
  * back valid, so requiring it here means an identity written by some OTHER
  * middleware — which this package cannot vouch for — shares the anonymous
  * per-IP bucket rather than getting the authenticated quota.
@@ -248,7 +249,7 @@ function resolveKey(req: OxyAuthedRequest): string {
  * Build the composed Oxy rate-limit middleware. See module docs for rationale.
  */
 export function createOxyRateLimit(
-  oxy: OxyServices,
+  oxy: OxyAuthHost,
   options: OxyRateLimitOptions = {},
 ): RequestHandler {
   const {
@@ -264,7 +265,7 @@ export function createOxyRateLimit(
   // Idempotent optional-auth resolver. Reuses the SAME session resolution as
   // every protected route, so the limiter keys by the real user identity.
   //
-  // `createOptionalOxyAuth` — NOT the raw `oxy.auth({ optional: true })` —
+  // `createOptionalOxyAuth` — NOT the raw `server.middleware.auth({ optional: true })` —
   // because only the former skips resolution when a preceding middleware has
   // already resolved a user. The raw middleware writes `req.userId = null` on
   // every request it cannot authenticate, and because it mutates the shared

package/src/server/requesterAssertion.ts

@@ -2,7 +2,7 @@
  * Present-requester assertions (ADR 0025).
  *
  * A first-party product backend holding a signed-in person's live Oxy session
- * trades it with Oxy (`OxyServices.mintRequesterAssertion`) for a one-use,
+ * trades it with Oxy (`server.agency.mintRequesterAssertion`) for a one-use,
  * short-lived `OXY-REQUESTER+JWT`, and sends that — never the person's bearer —
  * to the audience service (Alia) beside its own service token. The audience
  * mounts {@link createOxyRequesterAssertionAuth} after `createOxyAuthMiddleware`
@@ -291,12 +291,15 @@ export interface OxyRequesterAssertionIntrospection {
   readonly expiresAt?: string;
 }
 
+/** What the audience middleware needs of its `OxyServer`. */
 export interface OxyRequesterAssertionIntrospector {
-  introspectRequesterAssertion(input: {
-    assertion: string;
-    presenter: { applicationId: string; credentialId: string };
-  }): Promise<OxyRequesterAssertionIntrospection>;
-  getBaseURL(): string;
+  readonly baseURL: string;
+  readonly agency: {
+    introspectRequesterAssertion(input: {
+      assertion: string;
+      presenter: { applicationId: string; credentialId: string };
+    }): Promise<OxyRequesterAssertionIntrospection>;
+  };
 }
 
 /** What the audience learns about the present requester. */
@@ -358,8 +361,8 @@ function singleHeader(req: Request, name: string): string | null | 'invalid' {
  * token. Mount it after `createOxyAuthMiddleware`. Without the header it does
  * nothing, so it composes with every other lane.
  *
- * `introspector` must be an `OxyServices` configured with THIS service's own
- * credential (`configureServiceAuth`): Oxy only lets the audience's application
+ * `introspector` is this service's `OxyServer`, holding THIS service's own
+ * credential: Oxy only lets the audience's application
  * consume an assertion.
  */
 export function createOxyRequesterAssertionAuth(
@@ -371,7 +374,7 @@ export function createOxyRequesterAssertionAuth(
   const resolver = (): ((keyId: string) => Promise<KeyObject | undefined>) => {
     resolvePublicKey ??= createOxyJwksKeyResolver({
       jwksUrl: options.jwksUrl
-        ?? new URL('/capabilities/.well-known/jwks.json', introspector.getBaseURL()).toString(),
+        ?? new URL('/capabilities/.well-known/jwks.json', introspector.baseURL).toString(),
     });
     return resolvePublicKey;
   };
@@ -429,7 +432,7 @@ export function createOxyRequesterAssertionAuth(
 
     let introspection: OxyRequesterAssertionIntrospection;
     try {
-      introspection = await introspector.introspectRequesterAssertion({
+      introspection = await introspector.agency.introspectRequesterAssertion({
         assertion,
         presenter: { applicationId: serviceApp.appId, credentialId: serviceApp.credentialId },
       });

package/src/server/securityHeaders.ts

@@ -372,11 +372,10 @@ export interface OxyPagesHeadersOptions {
    * violation for a script we never asked for. The rest of the value is Pages'
    * own default, so caching is unchanged.
    *
-   * And, because this origin is where a web account is created, recovered and
-   * deleted and every Oxy passkey is asserted (ADR 0028, ADR 0029) — the rest
-   * of the holder policy: no `<base>` and no form posts (`base-uri` /
-   * `form-action 'none'`), no Referer to anyone, passkeys for this origin only
-   * with every other powerful feature off (`Permissions-Policy`), and its
+   * And, because this origin is where people sign in and approve third-party
+   * access (ADR 0028, ADR 0029, ADR 0030) — the rest of the holder policy: no
+   * `<base>` and no form posts (`base-uri` / `form-action 'none'`), no Referer
+   * to anyone, every powerful feature off (`Permissions-Policy`), and its
    * responses readable by no other origin (`Cross-Origin-Resource-Policy`).
    * Never `Cross-Origin-Opener-Policy`: the third-party OAuth popup reports
    * its code to the app that opened it, and COOP severs `window.opener`.
@@ -411,10 +410,10 @@ export interface OxyPagesHeadersOptions {
  * react-native-web's runtime stylesheet, and a style hash would silently switch
  * that off and render every Oxy web app unstyled.)
  */
-/** Passkeys for this origin itself; every other powerful feature off. */
+/** Every powerful feature off, WebAuthn included: Oxy has no passkeys (ADR 0030). */
 const SENSITIVE_PERMISSIONS_POLICY = [
-  'publickey-credentials-get=(self)',
-  'publickey-credentials-create=(self)',
+  'publickey-credentials-get=()',
+  'publickey-credentials-create=()',
   'camera=()',
   'microphone=()',
   'geolocation=()',

package/src/server/traffic.ts

@@ -2,8 +2,8 @@ import { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
 import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, type TrafficSocket } from '@oxy.so/telemetry/socket';
 import { randomUUID } from 'node:crypto';
 import type { RequestHandler } from 'express';
-import { OxyServices } from '../OxyServices';
-// Static, unlike the lazy import in `mixins/OxyServices.auth.ts`: that module is
+import { OxyServer } from './OxyServer';
+// Static, like `OxyServer`'s own import: this module is
 // reachable from the root barrel, which ships to React Native, so pulling
 // `node:crypto` in eagerly there would cost every mobile bundle. This file is
 // server-only and the server barrel already exports `./workloadIdentity`, so
@@ -65,11 +65,11 @@ export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
       'Ecosystem activity needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity this process can attest (ADR 0026).',
     );
   }
-  const oxy = new OxyServices({ baseURL });
-  // Left unconfigured when there is no pair on purpose: `getServiceToken()`
+  const oxy = new OxyServer({ baseURL });
+  // Left unconfigured when there is no pair on purpose: `serviceToken()`
   // attests instead of being handed half a credential to fail on.
   if (apiKey && apiSecret) oxy.configureServiceAuth(apiKey, apiSecret);
-  const credential = options.credential ?? (() => oxy.getServiceToken());
+  const credential = options.credential ?? (() => oxy.serviceToken());
   const fetcher = globalThis.fetch.bind(globalThis);
   const instanceId = randomUUID();
   const location = options.location ?? infrastructureLocation(region);
@@ -141,6 +141,6 @@ export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
       cleanups.add(cleanup);
       return cleanup;
     },
-    async stop() { if (stopped) return; stopped = true; cleanups.forEach(cleanup => cleanup()); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
+    async stop() { if (stopped) return; stopped = true; for (const cleanup of cleanups) cleanup(); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
   };
 }

package/src/server/trafficNodeHttp.ts

@@ -55,8 +55,8 @@ export function observeNodeHttp(
   const patches = [http, https].map(module => {
     const request = module.request;
     const get = module.get;
-    const wrappedRequest = function (...args: Parameters<typeof request>) { return safelyObserve(request.apply(module, args)); } as typeof request;
-    const wrappedGet = function (...args: Parameters<typeof get>) { return safelyObserve(get.apply(module, args)); } as typeof get;
+    const wrappedRequest = ((...args: Parameters<typeof request>) => safelyObserve(request.apply(module, args))) as typeof request;
+    const wrappedGet = ((...args: Parameters<typeof get>) => safelyObserve(get.apply(module, args))) as typeof get;
     module.request = wrappedRequest;
     module.get = wrappedGet;
     return () => {
@@ -65,5 +65,9 @@ export function observeNodeHttp(
     };
   });
   syncBuiltinESMExports();
-  return () => { patches.forEach(restore => restore()); restoreRequests.forEach(restore => restore()); syncBuiltinESMExports(); };
+  return () => {
+    for (const restore of patches) restore();
+    for (const restore of restoreRequests) restore();
+    syncBuiltinESMExports();
+  };
 }

package/src/server/userInvalidation.ts

@@ -6,8 +6,8 @@
  * 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 (the `evictOxyIdentityCache` calls in the user and accounts
- * mixins) and never when somebody else does — which is the normal case, since
+ * writes the profile (the `evictOxyIdentityCache` calls in the `users` and
+ * `accounts` namespaces) 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.
  *
@@ -34,11 +34,11 @@
  *     // node-redis
  *     await subscriber.subscribe(
  *       OXY_USER_INVALIDATION_CHANNEL,
- *       createOxyUserInvalidationHandler({ oxy: oxyClient }),
+ *       createOxyUserInvalidationHandler({ oxy: server }),
  *     );
  *
  *     // ioredis
- *     const handle = createOxyUserInvalidationHandler({ oxy: oxyClient });
+ *     const handle = createOxyUserInvalidationHandler({ oxy: server });
  *     await subscriber.subscribe(OXY_USER_INVALIDATION_CHANNEL);
  *     subscriber.on('message', (_channel, raw) => handle(raw));
  *
@@ -130,11 +130,11 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 /** Options for {@link createOxyUserInvalidationHandler}. */
 export interface OxyUserInvalidationHandlerOptions {
   /**
-   * The backend's `OxyServices` instance. When supplied, its GET response cache
-   * is swept for the invalidated user — this is the whole reason a backend that
-   * has no cache of its own still benefits from subscribing.
+   * The backend's `OxyServer` (or any `OxyServices`). When supplied, its GET
+   * response cache is swept for the invalidated user — this is the whole reason
+   * a backend that has no cache of its own still benefits from subscribing.
    */
-  oxy?: OxyIdentityCacheEvictor;
+  oxy?: { readonly http: OxyIdentityCacheEvictor };
   /**
    * App-specific eviction (e.g. a Redis identity cache the app maintains itself).
    * May be async; a rejection is routed to `onError` and never escapes.
@@ -179,7 +179,7 @@ export function createOxyUserInvalidationHandler(
 
     if (oxy) {
       try {
-        evictOxyIdentityCache(oxy, event.userId);
+        evictOxyIdentityCache(oxy.http, event.userId);
       } catch (error) {
         // A cache sweep must never cost us the app-specific eviction below.
         onError?.(error, raw);

package/src/session/accountDelegationAccess.ts

@@ -19,7 +19,7 @@ import type {
 	AccountKind,
 	AccountMember,
 	AccountRelationship,
-} from "../mixins/OxyServices.accounts";
+} from "../api/accounts";
 
 export interface AccountDelegationAccess {
 	/** The caller owns the account or has a live membership in it. */