@oxy.so/core 1.7.4 → 1.8.1

package/dist/types/crypto/polyfill.d.ts

@@ -13,8 +13,23 @@
  *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
  *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
  *      (Node 18 script entrypoints, some embedded hosts) falls back to.
- *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
- *      per-platform `platform/crypto` module in `@oxy.so/protocol`).
+ *   3. React Native — `expo-crypto.getRandomBytes`, through the dependency-free
+ *      `@oxy.so/protocol/random` entry.
+ *
+ * # Evaluation order — this module must import NOTHING that can capture the global
+ *
+ * `@noble/hashes` 1.x reads `globalThis.crypto` exactly once, when its
+ * `crypto.js` is evaluated, and `randomBytes` uses that captured binding for
+ * the lifetime of the app. ES imports are evaluated before the importing
+ * module's body, so every module this file imports runs BEFORE the shim below
+ * is installed. This file used to import `@oxy.so/protocol`'s root entry,
+ * which reaches `@noble/curves` → `@noble/hashes` through the envelope signer:
+ * on Hermes (no `globalThis.crypto` at startup) noble captured `undefined`
+ * before the shim existed, and every identity creation on Android failed with
+ * `crypto.getRandomValues must be defined`. Its imports are therefore limited
+ * to `buffer` and `@oxy.so/protocol/random`, both free of crypto libraries,
+ * and `index.ts` imports this file first. `__tests__/polyfillOrder.test.ts`
+ * guards both halves.
  *
  * Historically step (2) delegated to `@oxy.so/protocol`'s RN-only
  * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global

package/dist/types/inference/OxyInferenceClient.d.ts

@@ -49,7 +49,7 @@
  * schema, so a rename on either side fails a build rather than a customer's
  * request.
  */
-import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceRequestOutcome, InferenceAudioMediaType, InferenceStreamEvent, InferenceSpeechParameters, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxy.so/contracts';
+import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceReasoning, InferenceRequestOutcome, InferenceAudioMediaType, InferenceStreamEvent, InferenceSpeechParameters, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxy.so/contracts';
 /** The base URL of the Oxy API, when a caller names none. */
 export declare const OXY_INFERENCE_BASE_URL = "https://api.oxy.so";
 /**
@@ -105,6 +105,12 @@ export interface OxyResponsesRequest {
     readonly tools?: readonly ToolDefinition[];
     readonly toolChoice?: ToolChoice;
     readonly responseFormat?: ResponseFormat;
+    /**
+     * `{ effort: 'low' | 'medium' | 'high' }`. Name only an effort the model
+     * lists in its catalogue entry's `capabilities.reasoningEfforts`; any other
+     * is refused with `invalid_request` (HTTP 400) before anything is charged.
+     */
+    readonly reasoning?: InferenceReasoning;
     /** Cost-attribution tags, echoed back on the receipt. At most 16. */
     readonly labels?: Readonly<Record<string, string>>;
     /** Your own correlation id, echoed on the response. */
@@ -282,9 +288,14 @@ export declare class OxyInferenceClient {
      * both see the PUBLIC catalogue; only an internal/system application's
      * service token sees internal-only routes.
      *
-     * **`[]` is a normal answer**, and is the only answer today: the catalogue
-     * is populated by operators, and a route is not publicly exposed until
-     * somebody has reviewed the right to resell it.
+     * **`[]` is a normal answer**: a route is not publicly exposed until
+     * somebody has reviewed the right to resell it. An official application's
+     * credential also sees the internal catalogue Oxy keeps in step with
+     * Kaana automatically.
+     *
+     * Each entry's `capabilities.reasoningEfforts` lists the efforts a request
+     * may name in `reasoning.effort` (empty: none), and `releasedAt`, when
+     * present, is the date the upstream provider published the model.
      */
     listModels(options?: {
         signal?: AbortSignal;

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

@@ -47,6 +47,14 @@ export interface ServiceApp {
     appId: string;
     appName: string;
     scopes: string[];
+    /**
+     * `internal` when the caller is one of Oxy's own applications: app to app it
+     * is trusted outright — {@link requireScope} passes and it may act for a user
+     * without a delegation grant. `external` keeps every scope and grant rule.
+     * What the USER may do (their accounts, plan, limits) is still for the
+     * receiving service to decide. A token without the claim reads as `external`.
+     */
+    tier: 'internal' | 'external';
     /** The credentialId of the specific service credential that minted this token. */
     credentialId: string;
     /**

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

@@ -24,6 +24,8 @@ export interface OxyServiceAppContext {
      */
     ownerAccountId: string;
     environment: OxyServiceEnvironment;
+    /** `internal` for one of Oxy's own applications, else `external` (see `ServiceApp.tier`). */
+    tier: 'internal' | 'external';
 }
 export interface OxyServiceActingAsContext {
     userId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -118,8 +118,8 @@
     "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^1.3.0",
-    "@oxy.so/protocol": "^1.1.0",
+    "@oxy.so/contracts": "^1.4.0",
+    "@oxy.so/protocol": "^1.1.1",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "express-rate-limit": "^8.6.0",

package/src/crypto/__tests__/polyfill.test.ts

@@ -13,7 +13,7 @@
 const mockGetRandomBytesRN = jest.fn<Uint8Array, [number]>();
 const mockState = { isNodeJS: true };
 
-jest.mock('@oxy.so/protocol', () => ({
+jest.mock('@oxy.so/protocol/random', () => ({
   isNodeJS: () => mockState.isNodeJS,
   getRandomBytesRN: (byteCount: number) => mockGetRandomBytesRN(byteCount),
 }));

package/src/crypto/__tests__/polyfillOrder.test.ts

@@ -0,0 +1,114 @@
+/**
+ * The crypto polyfill must be installed before ANY `@noble/*` module evaluates.
+ *
+ * `@noble/hashes` 1.x's `crypto.js` captures `globalThis.crypto` once, at module
+ * evaluation, and `randomBytes` uses that captured binding forever. Hermes has
+ * no `globalThis.crypto` at startup, so if noble is evaluated before
+ * `./polyfill` installs the shim, every random draw throws
+ * `crypto.getRandomValues must be defined` — which is exactly how identity
+ * creation broke on Android: the polyfill imported `@oxy.so/protocol`'s root
+ * entry, whose envelope signer reaches `@noble/curves` → `@noble/hashes`, and
+ * imports are evaluated before the polyfill body.
+ *
+ * Node's resolver picks noble's `cryptoNode.js` (the `node` export condition),
+ * which never captures the global, so a plain Node run cannot see the bug. The
+ * suites below substitute the REAL `crypto.js` that Metro resolves for React
+ * Native, remove `globalThis.crypto`, and load core in a fresh module registry.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+type RandomBytes = (length?: number) => Uint8Array;
+
+const ORIGINAL_CRYPTO_DESCRIPTOR = Object.getOwnPropertyDescriptor(globalThis, 'crypto');
+
+/** noble's browser / React Native `crypto.js`: the variant that captures the global. */
+const NOBLE_CAPTURING_CRYPTO = join(dirname(require.resolve('@noble/hashes/utils')), 'crypto.js');
+
+/** Remove `globalThis.crypto` the way a Hermes host starts: no property at all. */
+function removeHostCrypto(): void {
+  if (!Reflect.deleteProperty(globalThis, 'crypto') || 'crypto' in globalThis) {
+    Object.defineProperty(globalThis, 'crypto', {
+      value: undefined,
+      configurable: true,
+      writable: true,
+    });
+  }
+}
+
+function restoreHostCrypto(): void {
+  Reflect.deleteProperty(globalThis, 'crypto');
+  if (ORIGINAL_CRYPTO_DESCRIPTOR) {
+    Object.defineProperty(globalThis, 'crypto', ORIGINAL_CRYPTO_DESCRIPTOR);
+  }
+}
+
+/**
+ * Run `body` in a fresh module registry that resolves `@noble/hashes/crypto` as
+ * a React Native bundle does, with no host `globalThis.crypto`.
+ */
+function withReactNativeNobleAndNoHostCrypto(body: () => void): void {
+  removeHostCrypto();
+  try {
+    jest.isolateModules(() => {
+      jest.doMock('@noble/hashes/crypto', () => jest.requireActual(NOBLE_CAPTURING_CRYPTO));
+      body();
+    });
+  } finally {
+    restoreHostCrypto();
+  }
+}
+
+describe('crypto polyfill evaluation order', () => {
+  it('reproduces the capture: noble evaluated before the polyfill has no randomness', () => {
+    // Guards the harness itself — if this ever stops throwing, the substitution
+    // no longer models the capturing variant and the suites below prove nothing.
+    withReactNativeNobleAndNoHostCrypto(() => {
+      const { randomBytes } = require('@noble/hashes/utils') as { randomBytes: RandomBytes };
+      require('../polyfill');
+      expect(() => randomBytes(32)).toThrow('crypto.getRandomValues must be defined');
+    });
+  });
+
+  it('importing @oxy.so/core installs the shim before noble captures the global', () => {
+    withReactNativeNobleAndNoHostCrypto(() => {
+      require('../../index');
+      const { randomBytes } = require('@noble/hashes/utils') as { randomBytes: RandomBytes };
+
+      const bytes = randomBytes(32);
+      expect(bytes).toHaveLength(32);
+      expect(bytes.some((byte) => byte !== 0)).toBe(true);
+    });
+  });
+
+  it('generates an identity (key pair + recovery mnemonic) through core', () => {
+    withReactNativeNobleAndNoHostCrypto(() => {
+      const core = require('../../index') as typeof import('../../index');
+      const { generateMnemonic } = require('@scure/bip39') as typeof import('@scure/bip39');
+      const { wordlist } = require('@scure/bip39/wordlists/english') as {
+        wordlist: string[];
+      };
+
+      // The two random draws `RecoveryPhraseService.generateIdentityWithRecovery`
+      // and `KeyManager.generateKeyPairSync` make — the ones Commons failed on.
+      expect(generateMnemonic(wordlist, 128).split(' ')).toHaveLength(12);
+      const keyPair = core.KeyManager.generateKeyPairSync();
+      expect(keyPair.privateKey).toMatch(/^[0-9a-f]{64}$/);
+    });
+  });
+
+  it('the polyfill imports nothing that can reach a crypto library', () => {
+    const source = readFileSync(resolve(__dirname, '..', 'polyfill.ts'), 'utf8');
+    const specifiers = [...source.matchAll(/^import\s+[^'"]*?['"]([^'"]+)['"]/gm)].map(
+      (match) => match[1],
+    );
+    expect(specifiers.sort()).toEqual(['@oxy.so/protocol/random', 'buffer']);
+  });
+
+  it('the core entry imports the polyfill before anything else', () => {
+    const source = readFileSync(resolve(__dirname, '..', '..', 'index.ts'), 'utf8');
+    const firstModuleReference = source.match(/^(?:import|export)\s[^;]*?['"]([^'"]+)['"]/m);
+    expect(firstModuleReference?.[1]).toBe('./crypto/polyfill');
+  });
+});

package/src/crypto/polyfill.ts

@@ -13,8 +13,23 @@
  *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
  *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
  *      (Node 18 script entrypoints, some embedded hosts) falls back to.
- *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
- *      per-platform `platform/crypto` module in `@oxy.so/protocol`).
+ *   3. React Native — `expo-crypto.getRandomBytes`, through the dependency-free
+ *      `@oxy.so/protocol/random` entry.
+ *
+ * # Evaluation order — this module must import NOTHING that can capture the global
+ *
+ * `@noble/hashes` 1.x reads `globalThis.crypto` exactly once, when its
+ * `crypto.js` is evaluated, and `randomBytes` uses that captured binding for
+ * the lifetime of the app. ES imports are evaluated before the importing
+ * module's body, so every module this file imports runs BEFORE the shim below
+ * is installed. This file used to import `@oxy.so/protocol`'s root entry,
+ * which reaches `@noble/curves` → `@noble/hashes` through the envelope signer:
+ * on Hermes (no `globalThis.crypto` at startup) noble captured `undefined`
+ * before the shim existed, and every identity creation on Android failed with
+ * `crypto.getRandomValues must be defined`. Its imports are therefore limited
+ * to `buffer` and `@oxy.so/protocol/random`, both free of crypto libraries,
+ * and `index.ts` imports this file first. `__tests__/polyfillOrder.test.ts`
+ * guards both halves.
  *
  * Historically step (2) delegated to `@oxy.so/protocol`'s RN-only
  * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
@@ -23,7 +38,7 @@
  */
 
 import { Buffer } from 'buffer';
-import { getRandomBytesRN, isNodeJS } from '@oxy.so/protocol';
+import { getRandomBytesRN, isNodeJS } from '@oxy.so/protocol/random';
 
 const getGlobalObject = (): typeof globalThis => {
   if (typeof globalThis !== 'undefined') return globalThis;
@@ -125,7 +140,7 @@ const cryptoPolyfill: CryptoLike = {
       return array;
     }
     // React Native (and any non-Node host without WebCrypto): synchronous
-    // expo-crypto via @oxy.so/protocol's RN `platform/crypto` variant.
+    // expo-crypto via @oxy.so/protocol's RN `platform/random` variant.
     const bytes = getRandomBytesRN(array.byteLength);
     const uint8View = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
     uint8View.set(bytes);

package/src/index.ts

@@ -17,7 +17,10 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 
-// Ensure crypto polyfills are loaded before anything else
+// Ensure crypto polyfills are loaded before anything else. This MUST stay the
+// first import: `@noble/hashes` captures `globalThis.crypto` when it is
+// evaluated, so the shim has to exist before any module below reaches it (see
+// the evaluation-order note in `./crypto/polyfill`).
 import './crypto/polyfill';
 
 // ---------------------------------------------------------------------------

package/src/inference/OxyInferenceClient.ts

@@ -57,6 +57,7 @@ import type {
     InferenceErrorCode,
     InferenceFinishReason,
     InferenceMessage,
+    InferenceReasoning,
     InferenceRequestOutcome,
     InferenceAudioMediaType,
     InferenceStreamEvent,
@@ -140,6 +141,12 @@ export interface OxyResponsesRequest {
     readonly tools?: readonly ToolDefinition[];
     readonly toolChoice?: ToolChoice;
     readonly responseFormat?: ResponseFormat;
+    /**
+     * `{ effort: 'low' | 'medium' | 'high' }`. Name only an effort the model
+     * lists in its catalogue entry's `capabilities.reasoningEfforts`; any other
+     * is refused with `invalid_request` (HTTP 400) before anything is charged.
+     */
+    readonly reasoning?: InferenceReasoning;
     /** Cost-attribution tags, echoed back on the receipt. At most 16. */
     readonly labels?: Readonly<Record<string, string>>;
     /** Your own correlation id, echoed on the response. */
@@ -370,9 +377,14 @@ export class OxyInferenceClient {
      * both see the PUBLIC catalogue; only an internal/system application's
      * service token sees internal-only routes.
      *
-     * **`[]` is a normal answer**, and is the only answer today: the catalogue
-     * is populated by operators, and a route is not publicly exposed until
-     * somebody has reviewed the right to resell it.
+     * **`[]` is a normal answer**: a route is not publicly exposed until
+     * somebody has reviewed the right to resell it. An official application's
+     * credential also sees the internal catalogue Oxy keeps in step with
+     * Kaana automatically.
+     *
+     * Each entry's `capabilities.reasoningEfforts` lists the efforts a request
+     * may name in `reasoning.effort` (empty: none), and `releasedAt`, when
+     * present, is the date the upstream provider published the model.
      */
     async listModels(options: { signal?: AbortSignal } = {}): Promise<ModelCatalogueEntry[]> {
         const body = await this.#request<CatalogueCollection<ModelCatalogueEntry>>(

package/src/inference/__tests__/OxyInferenceClient.test.ts

@@ -296,6 +296,23 @@ describe('OxyInferenceClient', () => {
             expect(answer.requestId).toBe('req-1');
         });
 
+        it('sends a reasoning effort as the edge expects it', async () => {
+            const { impl, calls } = stubFetch([{ status: 200, body: {} }]);
+            const client = new OxyInferenceClient({
+                credential: 'k',
+                baseURL: 'http://test.invalid',
+                fetch: impl,
+            });
+
+            await client.respond({ model: 'acme/thinker', input: 'hello', reasoning: { effort: 'high' } });
+
+            expect(JSON.parse(String(calls[0].init.body))).toEqual({
+                model: 'acme/thinker',
+                input: 'hello',
+                reasoning: { effort: 'high' },
+            });
+        });
+
         it('serializes an exact routing-profile ID byte-for-byte', async () => {
             const { impl, calls } = stubFetch([{ status: 200, body: {} }]);
             const client = new OxyInferenceClient({

package/src/mixins/OxyServices.utility.ts

@@ -24,6 +24,7 @@ interface JwtPayload {
   ownerAccountId?: string;
   appName?: string;
   scopes?: string[];
+  tier?: string;
   aud?: string | string[];
   iss?: string;
   environment?: string;
@@ -78,6 +79,14 @@ export interface ServiceApp {
   appId: string;
   appName: string;
   scopes: string[];
+  /**
+   * `internal` when the caller is one of Oxy's own applications: app to app it
+   * is trusted outright — {@link requireScope} passes and it may act for a user
+   * without a delegation grant. `external` keeps every scope and grant rule.
+   * What the USER may do (their accounts, plan, limits) is still for the
+   * receiving service to decide. A token without the claim reads as `external`.
+   */
+  tier: 'internal' | 'external';
   /** The credentialId of the specific service credential that minted this token. */
   credentialId: string;
   /**
@@ -705,6 +714,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               return res.status(401).json(error);
             }
 
+            const tier: ServiceApp['tier'] = decoded.tier === 'internal' ? 'internal' : 'external';
+
             // Read delegated user ID from header
             const oxyUserIdRaw = req.headers['x-oxy-user-id'];
             const oxyUserId = isExactNonEmptyServiceClaim(oxyUserIdRaw) ? oxyUserIdRaw : null;
@@ -725,12 +736,20 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               return res.status(401).json(error);
             }
 
-            // C3: a service may only act as a user when an explicit
-            // ServiceActingAs grant exists for that (appId, userId) pair.
-            // Without the grant we MUST refuse — silently attaching
-            // `req.userId = oxyUserId` would let any service impersonate
-            // any user simply by setting the header.
-            if (oxyUserId) {
+            // One of Oxy's own applications acts for a user without a grant:
+            // inside the ecosystem that is trust, not consent. It still acts
+            // with the USER's authority only — what that user may do is for the
+            // receiving service to check.
+            if (oxyUserId && tier === 'internal') {
+              req.userId = oxyUserId;
+              req.user = { id: oxyUserId } as User;
+              req.serviceActingAs = { userId: oxyUserId, scopes: [] };
+            } else if (oxyUserId) {
+              // C3: an EXTERNAL service may only act as a user when an explicit
+              // ServiceActingAs grant exists for that (appId, userId) pair.
+              // Without the grant we MUST refuse — silently attaching
+              // `req.userId = oxyUserId` would let any service impersonate
+              // any user simply by setting the header.
               const grant = await oxyInstance.verifyServiceActingAs(appId, oxyUserId);
               if (!grant || !grant.authorized) {
                 logger.warn('[oxy.auth] Service token rejected — no delegation grant', {
@@ -781,6 +800,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               ownerAccountId,
               scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
               environment,
+              tier,
             };
 
             if (debug) {
@@ -1255,6 +1275,13 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
           return;
         }
 
+        // Oxy's own applications are trusted app to app; scopes are the
+        // external lane.
+        if (req.serviceApp.tier === 'internal') {
+          next();
+          return;
+        }
+
         const appHasScope = appScopes.includes(scope);
         const delegationHasScope = delegatedScopes.includes(scope);
         const hasRequiredScope = req.serviceActingAs

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

@@ -189,9 +189,42 @@ describe('C3: service-token acting-as enforcement', () => {
       ownerAccountId: 'owner-account-1',
       scopes: ['user:read'],
       environment: 'production',
+      // No `tier` claim: a token minted before it existed is external.
+      tier: 'external',
     });
   });
 
+  it("lets one of Oxy's own applications act for a user without a grant", async () => {
+    const verifySpy = jest.spyOn(oxy, 'verifyServiceActingAs');
+    const token = signServiceToken(
+      { appId: 'alia', appName: 'Alia', scopes: [], tier: 'internal' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}`, 'x-oxy-user-id': 'user-1' } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    await oxy.auth({ jwtSecret: SERVICE_SECRET })(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(verifySpy).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.userId).toBe('user-1');
+    expect(req.serviceApp?.tier).toBe('internal');
+  });
+
+  it('still refuses an EXTERNAL application acting for a user without a grant', async () => {
+    jest.spyOn(oxy, 'verifyServiceActingAs').mockResolvedValue(null);
+    const token = signServiceToken({ appId: 'app-1', appName: 'third-party', tier: 'external' }, SERVICE_SECRET);
+    const req = makeReq({ headers: { authorization: `Bearer ${token}`, 'x-oxy-user-id': 'user-1' } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    await oxy.auth({ jwtSecret: SERVICE_SECRET })(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(403);
+  });
+
   it('does NOT call verifyServiceActingAs when X-Oxy-User-Id is absent (service acts as itself)', async () => {
     const verifySpy = jest
       .spyOn(oxy, 'verifyServiceActingAs')
@@ -682,6 +715,30 @@ describe('requireScope() middleware', () => {
     oxy = new OxyServices({ baseURL: 'http://test.invalid' });
   });
 
+  it("passes one of Oxy's own applications whatever scope is asked for", () => {
+    const req = makeReq();
+    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: [], tier: 'internal' };
+    req.serviceActingAs = { userId: 'u-1', scopes: [] };
+    const res = makeRes();
+    const next = jest.fn();
+
+    oxy.requireScope('files:write')(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('holds an external application to its scopes', () => {
+    const req = makeReq();
+    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['user:read'], tier: 'external' };
+    const res = makeRes();
+    const next = jest.fn();
+
+    oxy.requireScope('files:write')(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(403);
+  });
+
   it('allows requests where the app holds the required scope', () => {
     const req = makeReq({
       // Simulate a fully-authenticated service request — auth() has already

package/src/server/auth.ts

@@ -28,6 +28,8 @@ export interface OxyServiceAppContext {
    */
   ownerAccountId: string;
   environment: OxyServiceEnvironment;
+  /** `internal` for one of Oxy's own applications, else `external` (see `ServiceApp.tier`). */
+  tier: 'internal' | 'external';
 }
 
 export interface OxyServiceActingAsContext {