@oxyhq/core 21.0.2 → 21.2.0

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -180,6 +180,21 @@ export interface CreateAccountInput {
     };
     bio?: string;
     avatar?: string;
+    /**
+     * Named color preset KEY — `'blue'`, `'mint'`, … — never a hex value. The
+     * account graph's half of `User.color`, which every account DTO already
+     * carries; this is how one gets WRITTEN for an account you administer.
+     *
+     * Set it HERE rather than after the fact. For a managed account the colour is
+     * a visual identity, and an account that is discoverable without one and
+     * acquires it on a second request is a face that changes by itself.
+     *
+     * Omitted is not "no colour": the platform assigns a random preset, exactly as
+     * it did before this field existed. A reserved preset is refused unless the
+     * account has a claim to it — the administrator's own entitlements are not the
+     * ones weighed.
+     */
+    color?: string;
     /**
      * 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
@@ -191,6 +206,22 @@ export interface CreateAccountInput {
      * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
      */
     accountCategories?: AccountCategoryId[];
+    /**
+     * Create the account already opted OUT of discovery — kept out of people
+     * search, the follow-graph lists, `/similar` and the recommendation pools,
+     * with non-public media follower-gated.
+     *
+     * Pass `true` when the account is not something its owner has published yet:
+     * an agent, an unlaunched project, an organization for something unannounced.
+     * OMITTED IS NOT `false` IN MEANING, only in effect — saying nothing leaves
+     * the platform default, which is discoverable, and that default is not
+     * changed by this option existing.
+     *
+     * Setting it later is `PUT /users/:userId/privacy`, which needs the ACCOUNT's
+     * own bearer. Passing it here is the only way to have the account never be
+     * discoverable at all, rather than discoverable until a second call lands.
+     */
+    isPrivateAccount?: boolean;
 }
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
 export interface UpdateAccountInput {
@@ -208,6 +239,15 @@ export interface UpdateAccountInput {
     };
     bio?: string | null;
     avatar?: string | null;
+    /**
+     * Named color preset KEY, same vocabulary as `CreateAccountInput['color']`.
+     *
+     * NOT nullable, unlike `bio` and `avatar`: the column is `NOT NULL` with a
+     * default, so an account always HAS a colour and there is no "clear" to
+     * express. Sending the value the account already carries is always accepted,
+     * so a client may PATCH back the object it was served.
+     */
+    color?: string;
     /**
      * 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

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -6,8 +6,16 @@ import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
  * Confirms that a given service app holds an active delegation grant for
  * the supplied user, along with the explicit scope list the grant covers.
  *
- * The api side persists these via the `ServiceActingAs` model:
- *   { serviceAppId, userId, scopes: string[], grantedAt, expiresAt }
+ * The API side stores this as an ordinary `app_grants` row — the SAME revocable
+ * record the OAuth consent screen writes and the "Connected apps" UI lists and
+ * deletes — whose `scopes` name `acting-as:offline`. There is deliberately no
+ * separate delegation table: a second store would be a second revocation
+ * surface, and a user who disconnects an application in "Connected apps" means
+ * it, so one revoke has to end everything.
+ *
+ * `scopes` is what THAT USER consented to, not what the application may do in
+ * general. `requireScope` intersects it with the token's own app-wide scopes for
+ * a delegated request, and the intersection is the effective authority.
  *
  * The SDK never inspects the grant directly — it round-trips through
  * `GET /internal/service-acting-as/verify?appId=...&userId=...` so the
@@ -266,6 +274,20 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * service requests require the app scope. Delegated user requests require
          * BOTH the app scope and the per-user delegation scope.
          *
+         * The intersection is the point, not a redundancy, because the two scope
+         * lists answer different questions and neither implies the other:
+         *
+         *   `serviceApp.scopes`      what the PLATFORM allows this application to do
+         *                            (credential ∩ application ceiling, at mint time)
+         *   `serviceActingAs.scopes` what THIS USER allowed it to do (`app_grants`)
+         *
+         * Requiring only the app scope would let an application do to a user
+         * something that user never consented to; requiring only the grant would let
+         * a user hand an application authority staff never gave it, so a revoked
+         * platform scope would keep working for every user who had already
+         * consented. Effective authority is the intersection, and this is where it
+         * is taken.
+         *
          * Requests authenticated as a regular user (no service token) are rejected
          * with 403 — scope-protected endpoints are service-to-service by design.
          *

package/dist/types/server/index.d.ts

@@ -22,7 +22,7 @@ export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamErr
 export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, SsrfCheckResult, } from './safeFetch';
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
-export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, formatOxyCspPolicy, OXY_CSP_BASELINE, } from './securityHeaders';
+export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, cspSourcesFor, extractInlineScripts, formatOxyCspPolicy, inlineScriptCspHash, OXY_CSP_BASELINE, } from './securityHeaders';
 export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
 export { verifySecret } from './verifySecret';
 export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation';

package/dist/types/server/securityHeaders.d.ts

@@ -33,6 +33,19 @@
  *     cannot pass their own `contentSecurityPolicy` through to Helmet at all
  *     (the option is typed `never`).
  *
+ *  3. A STATIC EXPO EXPORT SHIPS AN INLINE SCRIPT THE BASELINE FORBIDS.
+ *     `web.output: 'static'` makes Expo Router emit
+ *     `<script type="module">globalThis.__EXPO_ROUTER_HYDRATE__=true;</script>`,
+ *     which is what tells the client entry to call `hydrateRoot` instead of
+ *     `createRoot().render()`. Nothing in app code puts it there, so — like the
+ *     Cloudflare beacon above — an app cannot allowlist it from the app side.
+ *     Measured on `accounts.oxy.so` 2026-08-21: blocked, so every visit threw
+ *     away the server-rendered markup and re-rendered from scratch, with only a
+ *     console error to show for it. The hashes are therefore DERIVED from the
+ *     built output rather than hand-written (see {@link extractInlineScripts}):
+ *     a hash pasted into config is correct exactly until the build changes one
+ *     byte, and then it fails the same silent way.
+ *
  * WHAT IT PROVIDES
  * ----------------
  * `createOxySecurityHeaders(options)` returns the Helmet middleware with the
@@ -102,6 +115,43 @@ export declare function buildOxyCspDirectives(extensions?: OxyCspExtensions): Re
  * `upgrade-insecure-requests`) emit the name alone.
  */
 export declare function formatOxyCspPolicy(directives: Record<string, string[]>): string;
+/**
+ * The source list one directive carries in a serialized policy, or `[]` when
+ * the policy does not name that directive. The inverse of
+ * {@link formatOxyCspPolicy}, and the reason it lives here rather than beside
+ * either caller: the post-deploy gate parses the policy the ORIGIN serves while
+ * the unit test parses the one the middleware renders, so a copy in each would
+ * let the header shape change with the test still green and the gate reading
+ * `[]` — reporting every script blocked, which reads as a broken app rather
+ * than as a broken parser.
+ *
+ * A directive present with no sources (`upgrade-insecure-requests`) and a
+ * directive absent entirely both answer `[]`. Callers that need to tell those
+ * apart are asking a different question than "what is allowed here".
+ */
+export declare function cspSourcesFor(policy: string, directive: string): string[];
+/**
+ * Every inline `<script>` body in an HTML document, in document order. A
+ * `<script src=…>` is a URL the source list already governs and is skipped.
+ *
+ * Scanned rather than matched with one regex because the two failure modes are
+ * not symmetric: an EXTRA body costs a redundant hash nobody notices, while a
+ * MISSED body silently reinstates the exact breakage this exists to prevent.
+ * So the scan errs toward finding them — it walks the open tag quote-aware
+ * instead of letting a `>` inside an attribute value truncate it.
+ *
+ * The type attribute is deliberately not consulted. Whether a given `type`
+ * executes is a browser decision (and it changes: `importmap` and
+ * `speculationrules` were both once inert), and pinning the exact bytes of a
+ * data block we ship ourselves weakens nothing.
+ */
+export declare function extractInlineScripts(html: string): string[];
+/**
+ * The `'sha256-…'` source that allows one inline script, hashed over its exact
+ * bytes as CSP specifies — no trimming, no normalization. One byte of
+ * whitespace either way is a different hash and the script stays blocked.
+ */
+export declare function inlineScriptCspHash(source: string): string;
 export interface OxyPagesHeadersOptions {
     /** Per-app additions merged into {@link OXY_CSP_BASELINE}. */
     csp?: OxyCspExtensions;
@@ -110,11 +160,28 @@ export interface OxyPagesHeadersOptions {
      * HTTPS only, so static deploys should keep this on.
      */
     hsts?: boolean;
+    /**
+     * The BUILT HTML documents this `_headers` will be served alongside. Every
+     * inline script found in them is allowed by hash, added to `script-src`.
+     *
+     * Passing the built output — rather than hand-writing a hash into
+     * `oxy.pages-headers.json` — is the whole point: a pasted hash is correct
+     * until the generator changes one byte of that script, and then the script is
+     * blocked again with nothing but a console error to show for it.
+     */
+    html?: readonly string[];
 }
 /**
  * Build a Cloudflare Pages `_headers` block for an Oxy HTML origin. Uses the
  * same CSP resolution as {@link createOxySecurityHeaders} plus the non-CSP
  * hardening headers Helmet would add on an Express HTML backend.
+ *
+ * Adding a hash to `script-src` does not narrow it: per CSP Level 3 a hash is
+ * an additional source, so `'self'` and the beacon host keep matching external
+ * scripts. (It WOULD neutralize `'unsafe-inline'` in the same directive — which
+ * is why this hashes scripts only. `style-src` keeps `'unsafe-inline'` for
+ * react-native-web's runtime stylesheet, and a style hash would silently switch
+ * that off and render every Oxy web app unstyled.)
  */
 export declare function buildOxyPagesHeaders(options?: OxyPagesHeadersOptions): string;
 export interface OxySecurityHeadersOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "21.0.2",
+  "version": "21.2.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -116,7 +116,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.30.0",
+    "@oxyhq/contracts": "^0.32.0",
     "@oxyhq/protocol": "^0.2.0",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",
@@ -153,7 +153,7 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@react-native-async-storage/async-storage": "^2.2.0",
-    "@types/express": "^4.17.21",
+    "@types/express": "^4.17.25",
     "@types/invariant": "^2.2.34",
     "@types/node": "^20.19.43",
     "expo-crypto": "~56.0.3",

package/src/mixins/OxyServices.accounts.ts

@@ -201,6 +201,21 @@ export interface CreateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   bio?: string;
   avatar?: string;
+  /**
+   * Named color preset KEY — `'blue'`, `'mint'`, … — never a hex value. The
+   * account graph's half of `User.color`, which every account DTO already
+   * carries; this is how one gets WRITTEN for an account you administer.
+   *
+   * Set it HERE rather than after the fact. For a managed account the colour is
+   * a visual identity, and an account that is discoverable without one and
+   * acquires it on a second request is a face that changes by itself.
+   *
+   * Omitted is not "no colour": the platform assigns a random preset, exactly as
+   * it did before this field existed. A reserved preset is refused unless the
+   * account has a claim to it — the administrator's own entitlements are not the
+   * ones weighed.
+   */
+  color?: string;
   /**
    * 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
@@ -212,6 +227,22 @@ export interface CreateAccountInput {
    * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
    */
   accountCategories?: AccountCategoryId[];
+  /**
+   * Create the account already opted OUT of discovery — kept out of people
+   * search, the follow-graph lists, `/similar` and the recommendation pools,
+   * with non-public media follower-gated.
+   *
+   * Pass `true` when the account is not something its owner has published yet:
+   * an agent, an unlaunched project, an organization for something unannounced.
+   * OMITTED IS NOT `false` IN MEANING, only in effect — saying nothing leaves
+   * the platform default, which is discoverable, and that default is not
+   * changed by this option existing.
+   *
+   * Setting it later is `PUT /users/:userId/privacy`, which needs the ACCOUNT's
+   * own bearer. Passing it here is the only way to have the account never be
+   * discoverable at all, rather than discoverable until a second call lands.
+   */
+  isPrivateAccount?: boolean;
 }
 
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
@@ -226,6 +257,15 @@ export interface UpdateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   bio?: string | null;
   avatar?: string | null;
+  /**
+   * Named color preset KEY, same vocabulary as `CreateAccountInput['color']`.
+   *
+   * NOT nullable, unlike `bio` and `avatar`: the column is `NOT NULL` with a
+   * default, so an account always HAS a colour and there is no "clear" to
+   * express. Sending the value the account already carries is always accepted,
+   * so a client may PATCH back the object it was served.
+   */
+  color?: string;
   /**
    * 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

package/src/mixins/OxyServices.utility.ts

@@ -36,8 +36,16 @@ interface JwtPayload {
  * Confirms that a given service app holds an active delegation grant for
  * the supplied user, along with the explicit scope list the grant covers.
  *
- * The api side persists these via the `ServiceActingAs` model:
- *   { serviceAppId, userId, scopes: string[], grantedAt, expiresAt }
+ * The API side stores this as an ordinary `app_grants` row — the SAME revocable
+ * record the OAuth consent screen writes and the "Connected apps" UI lists and
+ * deletes — whose `scopes` name `acting-as:offline`. There is deliberately no
+ * separate delegation table: a second store would be a second revocation
+ * surface, and a user who disconnects an application in "Connected apps" means
+ * it, so one revoke has to end everything.
+ *
+ * `scopes` is what THAT USER consented to, not what the application may do in
+ * general. `requireScope` intersects it with the token's own app-wide scopes for
+ * a delegated request, and the intersection is the effective authority.
  *
  * The SDK never inspects the grant directly — it round-trips through
  * `GET /internal/service-acting-as/verify?appId=...&userId=...` so the
@@ -217,11 +225,31 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
       }
 
       try {
+        // The verify endpoint is service-to-service and admits only a
+        // platform-TRUSTED calling application, so this call must carry the
+        // VERIFIER's own service token. Sent explicitly rather than through
+        // `makeServiceRequest`, which would drop `retry: false` and the timeout
+        // — and those two are not incidental: this runs inside request-handling
+        // middleware, so an inner retry loop multiplies the latency of every
+        // delegated request by the number of attempts.
+        //
+        // A verifier with no service credentials configured throws here and
+        // lands in the catch below, which is the correct outcome. A host that
+        // cannot prove who it is has no business being told which users have
+        // delegated to which applications, and the 60s negative cache stops a
+        // misconfigured deployment from turning every request into a round trip.
+        const serviceToken = await (this as unknown as OxyAuthInstance).getServiceToken();
+
         const result = await this.makeRequest<ServiceActingAsVerification>(
           'GET',
           '/internal/service-acting-as/verify',
           { appId, userId },
-          { cache: false, retry: false, timeout: 5000 },
+          {
+            cache: false,
+            retry: false,
+            timeout: 5000,
+            headers: { Authorization: `Bearer ${serviceToken}` },
+          },
         );
 
         const authorized = Boolean(result && result.authorized);
@@ -973,6 +1001,20 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * service requests require the app scope. Delegated user requests require
      * BOTH the app scope and the per-user delegation scope.
      *
+     * The intersection is the point, not a redundancy, because the two scope
+     * lists answer different questions and neither implies the other:
+     *
+     *   `serviceApp.scopes`      what the PLATFORM allows this application to do
+     *                            (credential ∩ application ceiling, at mint time)
+     *   `serviceActingAs.scopes` what THIS USER allowed it to do (`app_grants`)
+     *
+     * Requiring only the app scope would let an application do to a user
+     * something that user never consented to; requiring only the grant would let
+     * a user hand an application authority staff never gave it, so a revoked
+     * platform scope would keep working for every user who had already
+     * consented. Effective authority is the intersection, and this is where it
+     * is taken.
+     *
      * Requests authenticated as a regular user (no service token) are rejected
      * with 403 — scope-protected endpoints are service-to-service by design.
      *
@@ -1155,6 +1197,7 @@ interface SocketLike {
 
 interface OxyAuthInstance {
   verifyServiceActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+  getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
   validateSession(
     sessionId: string,
     options?: { deviceFingerprint?: string; useHeaderValidation?: boolean },

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

@@ -255,13 +255,20 @@ describe('OxyServices.accounts', () => {
     it('posts the payload, unwraps `account`, and busts every list', async () => {
       makeRequestSpy.mockResolvedValue({ account: accountNodeFixture });
 
-      const result = await oxy.createAccount({ kind: 'organization', username: 'oxy-org' });
+      const result = await oxy.createAccount({
+        kind: 'organization',
+        username: 'oxy-org',
+        color: 'purple',
+      });
 
       expect(result).toEqual(accountNodeFixture);
+      // `color` rides the CREATE body, not a follow-up patch: an account that is
+      // discoverable without its colour and acquires one on a second request is
+      // a face that changes by itself.
       expect(makeRequestSpy).toHaveBeenCalledWith(
         'POST',
         '/accounts',
-        { kind: 'organization', username: 'oxy-org' },
+        { kind: 'organization', username: 'oxy-org', color: 'purple' },
         expect.objectContaining({ cache: false }),
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts');
@@ -273,13 +280,13 @@ describe('OxyServices.accounts', () => {
     it('patches, unwraps `account`, and busts the detail + lists', async () => {
       makeRequestSpy.mockResolvedValue({ account: accountNodeFixture });
 
-      const result = await oxy.updateAccount('acc1', { bio: 'hello' });
+      const result = await oxy.updateAccount('acc1', { bio: 'hello', color: 'mint' });
 
       expect(result).toEqual(accountNodeFixture);
       expect(makeRequestSpy).toHaveBeenCalledWith(
         'PATCH',
         '/accounts/acc1',
-        { bio: 'hello' },
+        { bio: 'hello', color: 'mint' },
         expect.objectContaining({ cache: false }),
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1');

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

@@ -0,0 +1,167 @@
+/**
+ * `verifyServiceActingAs` — the SDK half of the delegation check.
+ *
+ * `serviceAuth.test.ts` covers what the MIDDLEWARE does with this method's
+ * answer, and it does so by stubbing the method out. So nothing there exercises
+ * the method itself: how it authenticates, what it sends, and what it does when
+ * the answer is no or never arrives. That is this file.
+ *
+ * The property under test throughout is fail-closed. `null` is the only value
+ * this method may return when it is not certain, because the middleware turns
+ * `null` into a 403 and anything else into an attached `req.userId`.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { RequestOptions } from '../../types';
+
+const APP = 'delegating-app';
+const USER = 'subject-user';
+
+interface CapturedCall {
+  method: string;
+  url: string;
+  data: unknown;
+  options: RequestOptions | undefined;
+}
+
+/**
+ * Stub `makeRequest` and record what it was handed.
+ *
+ * Deliberately not a network mock: the assertion that matters is the exact
+ * request the SDK composes — an unauthenticated one now gets a 403 from the API
+ * rather than an answer, so the Authorization header is part of the contract and
+ * not an implementation detail.
+ */
+function captureRequests(oxy: OxyServices, result: unknown) {
+  const calls: CapturedCall[] = [];
+  jest
+    .spyOn(oxy, 'makeRequest')
+    .mockImplementation(async (method, url, data, options) => {
+      calls.push({ method, url, data, options });
+      if (result instanceof Error) throw result;
+      return result as never;
+    });
+  return calls;
+}
+
+describe('verifyServiceActingAs', () => {
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('verifier-service-token');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("authenticates with the VERIFIER's own service token", async () => {
+    const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+    await oxy.verifyServiceActingAs(APP, USER);
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].options?.headers).toEqual({
+      Authorization: 'Bearer verifier-service-token',
+    });
+  });
+
+  it('sends the pair as query params, with retries off and a bounded timeout', async () => {
+    // This runs inside request-handling middleware. A retry loop here multiplies
+    // the latency of every delegated request by the number of attempts, and a
+    // cached GET would serve a revoked grant.
+    const calls = captureRequests(oxy, { authorized: true, scopes: [] });
+
+    await oxy.verifyServiceActingAs(APP, USER);
+
+    expect(calls[0].method).toBe('GET');
+    expect(calls[0].url).toBe('/internal/service-acting-as/verify');
+    expect(calls[0].data).toEqual({ appId: APP, userId: USER });
+    expect(calls[0].options).toMatchObject({ cache: false, retry: false, timeout: 5000 });
+  });
+
+  it('returns the grant when the API authorizes, carrying the scopes through', async () => {
+    captureRequests(oxy, { authorized: true, scopes: ['acting-as:offline', 'podcasts:write'] });
+
+    const grant = await oxy.verifyServiceActingAs(APP, USER);
+
+    expect(grant).toEqual({
+      authorized: true,
+      scopes: ['acting-as:offline', 'podcasts:write'],
+    });
+  });
+
+  it('returns null when the API answers authorized:false', async () => {
+    captureRequests(oxy, { authorized: false, scopes: [] });
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+  });
+
+  it('returns null when the API answers with scopes but NO authorized flag', async () => {
+    // A truthy `scopes` array must never stand in for authorization: a caller
+    // reading the array and skipping the boolean is the mistake, and the SDK
+    // refuses to produce a value that would reward it.
+    captureRequests(oxy, { scopes: ['podcasts:write'] });
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+  });
+
+  it('returns null when the endpoint is UNREACHABLE — there is no fail-open path', async () => {
+    captureRequests(oxy, new Error('ECONNREFUSED'));
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+  });
+
+  it('returns null, and never calls the endpoint, when the verifier has no service credentials', async () => {
+    // A host that cannot prove who it is has no business being told which users
+    // delegated to which applications. `getServiceToken()` throws, and that is
+    // the whole outcome.
+    jest
+      .spyOn(oxy, 'getServiceToken')
+      .mockRejectedValue(new Error('Service credentials not provided.'));
+    const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+    expect(calls).toHaveLength(0);
+  });
+
+  describe('caching', () => {
+    it('serves a positive grant from cache rather than re-asking', async () => {
+      const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+      await oxy.verifyServiceActingAs(APP, USER);
+      await oxy.verifyServiceActingAs(APP, USER);
+
+      expect(calls).toHaveLength(1);
+    });
+
+    it('caches a REFUSAL too, so a misconfigured caller cannot hammer the endpoint', async () => {
+      const calls = captureRequests(oxy, { authorized: false, scopes: [] });
+
+      await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+      await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+
+      expect(calls).toHaveLength(1);
+    });
+
+    it('keys the cache on BOTH app and user — one grant never answers for another', async () => {
+      // The cache key is the whole security boundary of this method. Keyed on
+      // the user alone, one application's grant would authorize every other
+      // application for that user; keyed on the app alone, one user's grant
+      // would authorize acting as everybody.
+      const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+      await oxy.verifyServiceActingAs(APP, USER);
+      await oxy.verifyServiceActingAs('other-app', USER);
+      await oxy.verifyServiceActingAs(APP, 'other-user');
+
+      expect(calls).toHaveLength(3);
+      expect(calls.map((c) => c.data)).toEqual([
+        { appId: APP, userId: USER },
+        { appId: 'other-app', userId: USER },
+        { appId: APP, userId: 'other-user' },
+      ]);
+    });
+  });
+});