@oxyhq/core 20.1.0 → 21.0.1

package/src/mixins/OxyServices.accounts.ts

@@ -288,72 +288,6 @@ export interface TransferAccountOwnershipInput {
   userId: string;
 }
 
-// ---------------------------------------------------------------------------
-// Bot (account) service-credential types
-// ---------------------------------------------------------------------------
-
-/** Credential kind. Account (bot) credentials are always `service` tokens. */
-export type AccountCredentialType = 'service';
-
-/** Deployment environment a bot credential is scoped to. */
-export type AccountCredentialEnvironment = 'development' | 'staging' | 'production';
-
-/** Bot credential lifecycle status. */
-export type AccountCredentialStatus = 'active' | 'deprecated' | 'revoked';
-
-/** Input accepted by `createAccountCredential`. Credential `type` is always `service`. */
-export interface CreateAccountCredentialInput {
-  name: string;
-  environment: AccountCredentialEnvironment;
-  scopes?: string[];
-}
-
-/**
- * Client-facing AccountCredential shape (a bot account's service token). The raw
- * secret is NEVER part of this shape — it is returned exactly once, separately,
- * at creation/rotation.
- */
-export interface AccountCredential {
-  _id: string;
-  /** The bot account this credential authenticates as (account `_id`). */
-  accountId: string;
-  name: string;
-  publicKey: string;
-  type: AccountCredentialType;
-  environment: AccountCredentialEnvironment;
-  scopes: string[];
-  status: AccountCredentialStatus;
-  lastUsedAt?: string;
-  expiresAt?: string;
-  /**
-   * Audit link to the credential this one was rotated FROM. Populated on
-   * credentials created via rotation; absent on original credentials.
-   */
-  rotatedFromCredentialId?: string;
-  createdByUserId: string;
-  createdAt: string;
-  updatedAt: string;
-}
-
-/** Result of creating a bot credential — `secret` is returned ONCE. */
-export interface AccountCredentialWithSecret {
-  credential: AccountCredential;
-  secret: string;
-}
-
-/**
- * Result of rotating a bot credential. Extends the create result with audit
- * fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom` (the
- * previous credential's `credentialId`) and `graceExpiresAt` (ISO string marking
- * when the old credential stops being honoured during the rotation grace window).
- */
-export interface RotateAccountCredentialResult extends AccountCredentialWithSecret {
-  /** The previous credential's `credentialId` that this rotation supersedes. */
-  rotatedFrom: string;
-  /** ISO timestamp at which the rotated-from credential's grace window ends. */
-  graceExpiresAt: string;
-}
-
 // ---------------------------------------------------------------------------
 // Application (owned by an account) types
 // ---------------------------------------------------------------------------
@@ -367,8 +301,18 @@ export type ApplicationType = 'first_party' | 'third_party' | 'internal' | 'syst
 /** Lifecycle status of an application. */
 export type ApplicationStatus = 'active' | 'suspended' | 'deleted' | 'pending_review';
 
-/** OAuth credential kind. `service` credentials mint service tokens. */
-export type ApplicationCredentialType = 'public' | 'confidential' | 'service';
+/**
+ * Credential kind.
+ *
+ * The first three are OAuth clients: the `oxy_dk_…` `publicKey` is the
+ * `client_id`, and any secret is presented BESIDE it. `service` credentials
+ * additionally mint service tokens.
+ *
+ * `machine` is the OpenAI-SDK-compatible API key (issue #972 §2.3): its
+ * credential material is ONE `oxy_sk_…` bearer string returned in `token`
+ * exactly once on create/rotate, never in `secret`.
+ */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service' | 'machine';
 
 /** Deployment environment an application credential is scoped to. */
 export type ApplicationEnvironment = 'development' | 'staging' | 'production';
@@ -428,6 +372,12 @@ export interface ApplicationCredential {
   applicationId: string;
   name: string;
   publicKey: string;
+  /**
+   * `oxy_sk_<id>` — the PUBLIC lookup half of a `machine` credential's bearer
+   * token, present only on that type. Safe to render: the secret half is 256
+   * bits that were shown exactly once and are never returned again.
+   */
+  tokenPrefix?: string;
   type: ApplicationCredentialType;
   environment: ApplicationEnvironment;
   scopes: string[];
@@ -486,25 +436,70 @@ export interface CreateApplicationCredentialInput {
   type: ApplicationCredentialType;
   environment: ApplicationEnvironment;
   scopes?: string[];
+  /**
+   * Lifetime of a `machine` credential, in seconds — 60 to 730 days. Omit for a
+   * key that does not expire on its own.
+   *
+   * **`machine` only.** On every other credential type `expires_at` means the
+   * rotation grace deadline, so a caller setting it at creation would make a
+   * brand-new credential indistinguishable from a rotated one. The server
+   * REJECTS it for those types rather than ignoring it, so sending it with the
+   * wrong `type` is a 400, not a silently dropped field.
+   */
+  expiresInSeconds?: number;
+}
+
+/** Input accepted by `rotateAppCredential`. */
+export interface RotateApplicationCredentialInput {
+  /**
+   * How long the superseded `machine` token keeps working, in seconds — 1 to 30
+   * days. Omitting it revokes the previous token the instant the replacement is
+   * minted, which is the safe default for a leaked key.
+   *
+   * **`machine` only, and opt-in.** `confidential`/`service` credentials always
+   * retire on the platform's fixed seven-day grace and the server REJECTS this
+   * field for them, so their contract is unchanged.
+   */
+  graceSeconds?: number;
 }
 
-/** Result of creating an application credential — `secret` is returned ONCE. */
+/**
+ * Result of creating an application credential — credential material is returned
+ * ONCE and can never be read back.
+ *
+ * Exactly one of the two fields carries it, decided by
+ * {@link ApplicationCredentialType}: `secret` for a `confidential`/`service`
+ * client, `token` for a `machine` API key, and NEITHER for a `public` client
+ * (`secret` is `null`). They are separate fields rather than one, so a surface
+ * that renders "the secret" cannot silently render an API key's bearer token
+ * under the wrong label, or a `null` where a token should be.
+ */
 export interface ApplicationCredentialWithSecret {
   credential: ApplicationCredential;
-  secret: string;
+  /** The OAuth client secret. `null` for `public` and `machine` credentials. */
+  secret: string | null;
+  /** The full `oxy_sk_…` bearer token. Present ONLY for a `machine` credential. */
+  token?: string;
 }
 
 /**
  * Result of rotating an application credential. Extends the create result with
- * audit fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom`
- * (the previous credential's `credentialId`) and `graceExpiresAt` (ISO string
- * marking when the old credential stops being honoured during the grace window).
+ * audit fields: the new credential material is returned ONCE, plus `rotatedFrom`
+ * (the previous credential's `credentialId`) and `graceExpiresAt`.
  */
 export interface RotateApplicationCredentialResult extends ApplicationCredentialWithSecret {
   /** The previous credential's `credentialId` that this rotation supersedes. */
   rotatedFrom: string;
-  /** ISO timestamp at which the rotated-from credential's grace window ends. */
-  graceExpiresAt: string;
+  /**
+   * ISO timestamp at which the rotated-from credential stops being honoured, or
+   * `null` when no grace window was configured and it was revoked outright.
+   *
+   * Nullable because a `machine` credential's grace is OPT-IN (issue #972 §2.3):
+   * rotating an API key without asking for a window kills the old token
+   * immediately, and there is then no deadline to report. The OAuth/service
+   * types always carry their fixed seven-day deadline.
+   */
+  graceExpiresAt: string | null;
 }
 
 /** Time window for application usage statistics. */
@@ -1009,106 +1004,6 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
-    // =========================================================================
-    // Bot (account) service credentials  —  /accounts/:id/credentials
-    // =========================================================================
-
-    /**
-     * List a bot account's service credentials. The response NEVER includes
-     * secrets.
-     * @param accountId - The account's Mongo `_id`.
-     */
-    async listAccountCredentials(accountId: string): Promise<AccountCredential[]> {
-      try {
-        const res = await this.makeRequest<{ credentials?: AccountCredential[] }>(
-          'GET',
-          `/accounts/${encodeURIComponent(accountId)}/credentials`,
-          undefined,
-          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
-        );
-        return res.credentials ?? [];
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Create a service credential for a bot account. The plaintext `secret` is
-     * returned exactly ONCE; the server stores only a hash and will never return
-     * it again.
-     * @param accountId - The account's Mongo `_id`.
-     * @param data - Credential configuration (`type` is always `service`).
-     */
-    async createAccountCredential(
-      accountId: string,
-      data: CreateAccountCredentialInput,
-    ): Promise<AccountCredentialWithSecret> {
-      try {
-        const result = await this.makeRequest<AccountCredentialWithSecret>(
-          'POST',
-          `/accounts/${encodeURIComponent(accountId)}/credentials`,
-          data,
-          { cache: false },
-        );
-        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-        return result;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Rotate a bot credential's secret. The new plaintext `secret` is returned
-     * exactly ONCE, along with audit fields: `rotatedFrom` (the previous
-     * credentialId) and `graceExpiresAt` (ISO string for the grace window during
-     * which the old credential is still honoured).
-     * @param accountId - The account's Mongo `_id`.
-     * @param credentialId - The credential's Mongo `_id`.
-     */
-    async rotateAccountCredential(
-      accountId: string,
-      credentialId: string,
-    ): Promise<RotateAccountCredentialResult> {
-      try {
-        const result = await this.makeRequest<RotateAccountCredentialResult>(
-          'POST',
-          `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}/rotate`,
-          undefined,
-          { cache: false },
-        );
-        // Rotation changes credential status/audit fields surfaced by the list.
-        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-        return result;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Revoke a bot credential (`status='revoked'`). Revoked credentials can no
-     * longer authenticate.
-     * @param accountId - The account's Mongo `_id`.
-     * @param credentialId - The credential's Mongo `_id`.
-     */
-    async revokeAccountCredential(
-      accountId: string,
-      credentialId: string,
-    ): Promise<AccountSuccessResult> {
-      try {
-        const result = await this.makeRequest<AccountSuccessResult>(
-          'DELETE',
-          `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}`,
-          undefined,
-          { cache: false },
-        );
-        // Revocation flips the credential's status in the cached list.
-        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-        return result;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
     // =========================================================================
     // Applications owned by an account  —  /applications
     // =========================================================================
@@ -1273,16 +1168,20 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
      * which the old credential is still honoured).
      * @param applicationId - The application's Mongo `_id`.
      * @param credentialId - The credential's Mongo `_id`.
+     * @param options - `graceSeconds` keeps a superseded `machine` token working
+     *   for that long. Omitted, the previous token dies the moment the
+     *   replacement is minted.
      */
     async rotateAppCredential(
       applicationId: string,
       credentialId: string,
+      options?: RotateApplicationCredentialInput,
     ): Promise<RotateApplicationCredentialResult> {
       try {
         const result = await this.makeRequest<RotateApplicationCredentialResult>(
           'POST',
           `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`,
-          undefined,
+          options,
           { cache: false },
         );
         // Rotation changes credential status/audit fields surfaced by the list.

package/src/mixins/OxyServices.auth.ts

@@ -7,7 +7,6 @@ import type { User } from '../models/interfaces';
 import type {
   UserNameResponse,
   LoginResult,
-  LoginSessionResult,
   CommonsDenyReason,
 } from '@oxyhq/contracts';
 import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
@@ -74,6 +73,42 @@ export interface OAuthUserInfoResponse {
   picture?: string;
 }
 
+/**
+ * The session an OAuth authorization-code exchange yields.
+ *
+ * Deliberately NOT `LoginSessionResult`. That type mirrors the API's
+ * `buildSessionAuthResponse`, which every FIRST-PARTY sign-in lane emits, and it
+ * requires `deviceId` because those lanes always join the origin's DeviceSession.
+ * `POST /auth/oauth/token` is the RFC 6749 token endpoint and serves third
+ * parties, whose grant is deliberately ISOLATED: an untrusted application must be
+ * able to receive a session carrying NO DeviceSession credential at all.
+ *
+ * Both device fields are therefore optional here, and a response omitting them is
+ * a well-formed device-less grant rather than a malformed payload. What that
+ * costs the session is spelled out on `exchangeOAuthCode` below.
+ */
+export interface OAuthTokenExchangeResult {
+  sessionId: string;
+  /** ISO-8601 expiry of {@link accessToken}, derived from RFC 6749 `expires_in`. */
+  expiresAt: string;
+  accessToken?: string;
+  /**
+   * The DeviceSession this grant joined, when the server issued one. ABSENT for
+   * an isolated third-party grant — never assume a string.
+   */
+  deviceId?: string;
+  /**
+   * The zero-cookie mint credential for {@link deviceId}. Present only alongside
+   * it; absent for an isolated third-party grant.
+   */
+  deviceSecret?: string;
+  user: {
+    id: string;
+    username?: string;
+    avatar?: string;
+  };
+}
+
 // ===========================================================================
 // "Sign in with Oxy" — cross-device QR / app-to-app handoff (Workstream C)
 // ===========================================================================
@@ -1699,13 +1734,30 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * response this method used before were an Oxy invention no OAuth library
      * could interoperate with; the endpoint no longer accepts them. The method's
      * OWN signature is unchanged, so callers are unaffected.
+     *
+     * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
+     * outcome, not an error. A third-party grant is meant to be isolated from the
+     * browser's shared DeviceSession, so the token endpoint must be free to return
+     * no device credential at all — the guard that used to require the pair made
+     * that omission unshippable, since it turned every third-party sign-in through
+     * the SDK into a silent `exchange-failed`.
+     *
+     * The cost is real and deliberate: a DEVICE-LESS session cannot use the
+     * zero-cookie mint lane (`POST /session/device/token`), because that lane's
+     * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
+     * access token itself — nothing persists a restore credential, the cold boot's
+     * `device-secret-mint` step reports `no-secret` and skips, and the refresh
+     * scheduler has nothing to re-mint from. When the token expires the session
+     * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
+     * out, so the app can run the OAuth flow again. It never degrades into a
+     * session that looks alive and cannot refresh.
      */
     async exchangeOAuthCode(params: {
       code: string;
       clientId: string;
       redirectUri: string;
       codeVerifier: string;
-    }): Promise<LoginSessionResult> {
+    }): Promise<OAuthTokenExchangeResult> {
       try {
         const form = new URLSearchParams({
           grant_type: 'authorization_code',
@@ -1730,7 +1782,9 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         const deviceId = typeof record.deviceId === 'string' ? record.deviceId : undefined;
         const deviceSecret = typeof record.deviceSecret === 'string' ? record.deviceSecret : undefined;
         const userRaw = record.user;
-        if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
+        // The device pair is NOT part of this guard — see the note above. What is
+        // still mandatory is what identifies the session at all.
+        if (!sessionId || !userRaw || typeof userRaw !== 'object') {
           throw new Error('auth/oauth/token returned an incomplete session payload');
         }
         const userObj = userRaw as Record<string, unknown>;
@@ -1744,12 +1798,20 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         if (accessToken) {
           this.setTokens(accessToken);
         }
+        if (!deviceId || !deviceSecret) {
+          logger.debug(
+            'auth/oauth/token returned no device credential — this session lives only as long as its access token',
+            { component: 'oxy.auth', method: 'exchangeOAuthCode' },
+          );
+        }
         return {
           sessionId,
-          deviceId,
           expiresAt,
           accessToken,
-          deviceSecret,
+          // Omitted rather than set to `undefined` when the server sent no device
+          // credential, so a device-less grant serializes as the absence it is.
+          ...(deviceId ? { deviceId } : {}),
+          ...(deviceSecret ? { deviceSecret } : {}),
           user: {
             id: userId,
             username: typeof userObj.username === 'string' ? userObj.username : undefined,

package/src/mixins/OxyServices.inference.ts

@@ -0,0 +1,57 @@
+/**
+ * The inference API, reached with whatever bearer this session already holds
+ * (issue #972, workstream 15).
+ *
+ * ```typescript
+ * const models = await oxyServices.inference().listModels();
+ * ```
+ *
+ * One method, and it is a FACTORY rather than a set of inference methods on
+ * `OxyServices`. The calls themselves live once, in
+ * {@link OxyInferenceClient} — which an external developer holding only an
+ * `oxy_sk_…` machine key constructs directly, with no Oxy session anywhere in
+ * the picture. Declaring the same calls a second time here would give the
+ * ecosystem two spellings of one request, and only one of them would stay
+ * correct.
+ *
+ * This is the reasoning `createLinkedClient` is already built on: the plumbing
+ * that binds an Oxy bearer to a client belongs in core, once, rather than in
+ * each app.
+ *
+ * The credential is a FUNCTION, not the current token: a session bearer rotates
+ * on refresh and on account switch, and a client that captured one at
+ * construction would start answering 401 an hour into the process's life.
+ */
+
+import { OxyInferenceClient } from '../inference/OxyInferenceClient';
+import type { OxyServicesBase } from '../OxyServices.base';
+
+export function OxyServicesInferenceMixin<T extends typeof OxyServicesBase>(Base: T) {
+    return class extends Base {
+        /** @internal Memoized so repeated calls return one object identity. */
+        _inferenceClient: OxyInferenceClient | null = null;
+
+        /**
+         * The inference client for this session.
+         *
+         * Bound to this instance's base URL and to `getAccessToken()`, so it
+         * follows every refresh, sign-in and account switch without being
+         * rebuilt.
+         *
+         * A service-authenticated process wants a different credential and
+         * builds {@link OxyInferenceClient} directly:
+         * `new OxyInferenceClient({ credential: () => oxy.getServiceToken() })`.
+         * The mint is asynchronous and cached, which is exactly what a
+         * credential function is for.
+         */
+        inference(): OxyInferenceClient {
+            if (this._inferenceClient === null) {
+                this._inferenceClient = new OxyInferenceClient({
+                    baseURL: this.getBaseURL(),
+                    credential: () => this.getAccessToken(),
+                });
+            }
+            return this._inferenceClient;
+        }
+    };
+}

package/src/mixins/OxyServices.utility.ts

@@ -22,6 +22,7 @@ interface JwtPayload {
   type?: string;
   appId?: string;
   credentialId?: string;
+  ownerAccountId?: string;
   appName?: string;
   scopes?: string[];
   aud?: string | string[];
@@ -49,9 +50,21 @@ export interface ServiceActingAsVerification {
 
 /**
  * Service app metadata attached to requests authenticated with service tokens.
- * `scopes` reflects the scopes granted to the app at signup time (from the
- * `Application.scopes` field); route-level checks can require additional
- * scope-narrowing via `requireScope()`.
+ *
+ * Every field comes from the token's SIGNED payload and is populated only after
+ * the signature, `iss`/`aud`/`type` binding and expiry all pass — so a verifier
+ * holding this object can name the responsible principals without a lookup of
+ * its own. Together with `credentialId` and `ownerAccountId` it is the canonical
+ * attribution tuple of ADR 0007 minus the delegated user.
+ *
+ * `scopes` are the EFFECTIVE scopes: the credential's own scopes intersected
+ * with the owning application's grant at mint time (the API's `intersectScopes`
+ * is the single authority for that intersection — nothing re-intersects here).
+ * Route-level checks narrow further via `requireScope()`.
+ *
+ * A delegated end user is NOT a field of this type, and must never become one.
+ * It lives in `req.serviceActingAs` / `req.userId`, is authorised per request,
+ * and is attribution only.
  */
 export interface ServiceApp {
   appId: string;
@@ -59,6 +72,12 @@ export interface ServiceApp {
   scopes: string[];
   /** The credentialId of the specific service credential that minted this token. */
   credentialId: string;
+  /**
+   * The Oxy account that owns `appId` and is financially responsible for it.
+   * The BILLING principal — never a user id, and never the delegated
+   * `X-Oxy-User-Id` (ADR 0007).
+   */
+  ownerAccountId: string;
   /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
   environment: OxyServiceEnvironment;
 }
@@ -122,11 +141,24 @@ interface AuthMiddlewareOptions {
    * When provided, service tokens will be cryptographically verified.
    * When omitted, service tokens will be rejected (secure default).
    *
-   * **Migration note (>=1.11.14):** the Oxy API now signs service tokens
-   * with a dedicated `SERVICE_TOKEN_SECRET` distinct from `ACCESS_TOKEN_SECRET`.
-   * Pass that value here. If you keep passing the access-token secret you will
-   * still verify ALL signed-by-Oxy tokens (which is the whole class of bug
-   * H4 was supposed to prevent — DO NOT do that in production).
+   * **The only value that works is `ACCESS_TOKEN_SECRET`, and you should not
+   * want to hold it — see issue #987 and ADR 0012.** The Oxy API signs service
+   * tokens with `ACCESS_TOKEN_SECRET` (`packages/api/src/routes/auth.ts`),
+   * which is also the key that signs every user access token. There is no
+   * separate service-token secret: earlier revisions of this comment named a
+   * `SERVICE_TOKEN_SECRET` that has never existed in the API, in any workflow or
+   * in any task definition, and passing one would fail every verification.
+   *
+   * The consequence to hold onto: the scheme is symmetric, so a host that can
+   * VERIFY a service token can also MINT one — including a user access token.
+   * **Local verification is therefore appropriate only inside the Oxy API's own
+   * trust boundary, and no service outside it holds this key today.** Do not be
+   * the first: if you need to verify Oxy service tokens from another service,
+   * follow #987 rather than copying the secret.
+   *
+   * `docs/adr/0012-service-token-signing-key-model.md` records the decision to
+   * retire this option in favour of asymmetric signing against a published
+   * JWKS, at which point it is removed rather than deprecated.
    */
   jwtSecret?: string;
   /**
@@ -266,7 +298,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      *   additionally checked for `aud`, `iss`, and `type` claims to prevent
      *   cross-token-type confusion attacks.
      * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
-     *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
+     *   direct access to `ACCESS_TOKEN_SECRET`.
      *
      * **Why session-less user tokens are refused rather than trusted:**
      * every user access token the Oxy API issues carries a `sessionId` (see
@@ -298,7 +330,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
      *
      * // Protect all routes under /protected
-     * app.use('/protected', oxy.auth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
+     * app.use('/protected', oxy.auth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }));
      *
      * // Access user in route handler
      * app.get('/protected/me', (req, res) => {
@@ -312,7 +344,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * app.use('/public', oxy.auth({ optional: true }));
      *
      * // Require a specific scope on a service-token-protected route
-     * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }), oxy.requireScope('files:write'));
+     * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }), oxy.requireScope('files:write'));
      * ```
      *
      * @param options Optional configuration
@@ -490,14 +522,20 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               return res.status(401).json(error);
             }
 
-            // Validate required service token fields
+            // Validate required service token fields. All of them are
+            // required, `ownerAccountId` included: an optional billing
+            // principal is one fallback away from being resolved from the
+            // delegated user, which is the exact confusion ADR 0007 forbids.
             const appId = decoded.appId;
             const credentialId = decoded.credentialId;
+            const ownerAccountId = decoded.ownerAccountId;
             const environment = decoded.environment;
             if (
               !appId ||
               typeof credentialId !== 'string' ||
               credentialId.length === 0 ||
+              typeof ownerAccountId !== 'string' ||
+              ownerAccountId.length === 0 ||
               !isOxyServiceEnvironment(environment)
             ) {
               if (optional) {
@@ -538,6 +576,11 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
                 return res.status(403).json(error);
               }
 
+              // ATTRIBUTION ONLY. `req.userId` answers "on whose behalf", never
+              // "who pays": the billing principal stays `req.serviceApp
+              // .ownerAccountId`, which this branch does not touch. Read it
+              // through `getOxyBillingPrincipal` (`@oxyhq/core/server`), whose
+              // return type a user id cannot satisfy (ADR 0007).
               req.userId = oxyUserId;
               req.user = { id: oxyUserId } as User;
               req.serviceActingAs = { userId: oxyUserId, scopes: grant.scopes };
@@ -552,6 +595,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               appId,
               appName: decoded.appName || 'unknown',
               credentialId,
+              ownerAccountId,
               scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
               environment,
             };
@@ -896,7 +940,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * @example
      * ```typescript
      * // Protect internal endpoints
-     * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
+     * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }));
      *
      * app.post('/internal/trigger', (req, res) => {
      *   console.log('Service app:', req.serviceApp);
@@ -936,7 +980,7 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * ```typescript
      * app.use(
      *   '/internal/files',
-     *   oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }),
+     *   oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }),
      *   oxy.requireScope('files:write'),
      * );
      * ```