@oxyhq/core 21.0.0 → 21.0.1

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

@@ -17,9 +17,6 @@ import type { User } from '../../models/interfaces';
 import type {
   AccountNode,
   AccountMember,
-  AccountCredential,
-  AccountCredentialWithSecret,
-  RotateAccountCredentialResult,
   Application,
   ApplicationCredential,
   ApplicationCredentialWithSecret,
@@ -62,20 +59,6 @@ const accountNodeFixture: AccountNode = {
   childCount: 2,
 };
 
-const credentialFixture: AccountCredential = {
-  _id: 'cred1',
-  accountId: 'acc1',
-  name: 'bot-prod',
-  publicKey: 'oxy_dk_abc',
-  type: 'service',
-  environment: 'production',
-  scopes: ['user:read'],
-  status: 'active',
-  createdByUserId: 'u1',
-  createdAt: '2026-06-29T00:00:00.000Z',
-  updatedAt: '2026-06-29T00:00:00.000Z',
-};
-
 const appFixture: Application = {
   _id: 'app1',
   name: 'Mention',
@@ -476,91 +459,6 @@ describe('OxyServices.accounts', () => {
     });
   });
 
-  describe('listAccountCredentials', () => {
-    it('unwraps the `credentials` array and caches the read', async () => {
-      makeRequestSpy.mockResolvedValue({ credentials: [credentialFixture] });
-
-      const result = await oxy.listAccountCredentials('acc1');
-
-      expect(result).toEqual([credentialFixture]);
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'GET',
-        '/accounts/acc1/credentials',
-        undefined,
-        expect.objectContaining({ cache: true }),
-      );
-    });
-
-    it('returns an empty array when `credentials` is absent', async () => {
-      makeRequestSpy.mockResolvedValue({});
-      expect(await oxy.listAccountCredentials('acc1')).toEqual([]);
-    });
-  });
-
-  describe('createAccountCredential', () => {
-    it('posts the config, returns the secret result, and busts the credentials cache', async () => {
-      const created: AccountCredentialWithSecret = {
-        credential: credentialFixture,
-        secret: 'sk_once',
-      };
-      makeRequestSpy.mockResolvedValue(created);
-
-      const result = await oxy.createAccountCredential('acc1', {
-        name: 'bot-prod',
-        environment: 'production',
-      });
-
-      expect(result).toEqual(created);
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'POST',
-        '/accounts/acc1/credentials',
-        { name: 'bot-prod', environment: 'production' },
-        expect.objectContaining({ cache: false }),
-      );
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/credentials');
-    });
-  });
-
-  describe('rotateAccountCredential', () => {
-    it('posts to /rotate, encodes ids, returns the audit result, and busts credentials', async () => {
-      const rotated: RotateAccountCredentialResult = {
-        credential: { ...credentialFixture, _id: 'cred2' },
-        secret: 'sk_new',
-        rotatedFrom: 'cred1',
-        graceExpiresAt: '2026-07-06T00:00:00.000Z',
-      };
-      makeRequestSpy.mockResolvedValue(rotated);
-
-      const result = await oxy.rotateAccountCredential('acc1', 'cred 1');
-
-      expect(result).toEqual(rotated);
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'POST',
-        '/accounts/acc1/credentials/cred%201/rotate',
-        undefined,
-        expect.objectContaining({ cache: false }),
-      );
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/credentials');
-    });
-  });
-
-  describe('revokeAccountCredential', () => {
-    it('deletes the credential and busts the credentials cache', async () => {
-      makeRequestSpy.mockResolvedValue({ success: true });
-
-      const result = await oxy.revokeAccountCredential('acc1', 'cred1');
-
-      expect(result).toEqual({ success: true });
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'DELETE',
-        '/accounts/acc1/credentials/cred1',
-        undefined,
-        expect.objectContaining({ cache: false }),
-      );
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/credentials');
-    });
-  });
-
   describe('createApp', () => {
     it('posts the payload, unwraps `application`, and busts every app list', async () => {
       makeRequestSpy.mockResolvedValue({ application: appFixture });
@@ -678,6 +576,39 @@ describe('OxyServices.accounts', () => {
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/applications/app1/credentials');
     });
+
+    it("forwards a machine credential's expiresInSeconds and its one-time token", async () => {
+      // A `machine` credential's material arrives in `token`, never `secret` —
+      // a surface rendering "the secret" must not silently print an API key.
+      const created: ApplicationCredentialWithSecret = {
+        credential: { ...appCredentialFixture, type: 'machine', tokenPrefix: 'oxy_sk_0123456789abcdef' },
+        secret: null,
+        token: 'oxy_sk_0123456789abcdef_' + 'a'.repeat(64),
+      };
+      makeRequestSpy.mockResolvedValue(created);
+
+      const result = await oxy.createAppCredential('app1', {
+        name: 'ci-runner',
+        type: 'machine',
+        environment: 'production',
+        scopes: ['inference:invoke'],
+        expiresInSeconds: 86_400,
+      });
+
+      expect(result.token).toBe(created.token);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/applications/app1/credentials',
+        {
+          name: 'ci-runner',
+          type: 'machine',
+          environment: 'production',
+          scopes: ['inference:invoke'],
+          expiresInSeconds: 86_400,
+        },
+        expect.objectContaining({ cache: false }),
+      );
+    });
   });
 
   describe('rotateAppCredential', () => {
@@ -701,6 +632,30 @@ describe('OxyServices.accounts', () => {
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/applications/app1/credentials');
     });
+
+    it('forwards an opt-in rotation grace window', async () => {
+      // Omitting it (the case above) sends `undefined`, and the server then
+      // revokes the superseded machine token immediately. Sending it must reach
+      // the body, or a caller asking for zero-downtime rotation would silently
+      // get the instant-revoke behaviour instead.
+      const rotated: RotateApplicationCredentialResult = {
+        credential: { ...appCredentialFixture, _id: 'appcred2', type: 'machine' },
+        secret: null,
+        token: 'oxy_sk_fedcba9876543210_' + 'b'.repeat(64),
+        rotatedFrom: 'appcred1',
+        graceExpiresAt: '2026-08-17T00:00:00.000Z',
+      };
+      makeRequestSpy.mockResolvedValue(rotated);
+
+      await oxy.rotateAppCredential('app1', 'appcred1', { graceSeconds: 3600 });
+
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/applications/app1/credentials/appcred1/rotate',
+        { graceSeconds: 3600 },
+        expect.objectContaining({ cache: false }),
+      );
+    });
   });
 
   describe('revokeAppCredential', () => {

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

@@ -0,0 +1,58 @@
+/**
+ * `oxyServices.inference()` — the binding, which is the only thing this mixin
+ * does.
+ *
+ * Two properties matter and neither is visible from the client's own suite: the
+ * client must inherit THIS instance's base URL, and it must read the bearer
+ * LATE, so a token planted after construction is the one that gets sent. A
+ * factory that captured `getAccessToken()` eagerly would pass every test that
+ * signs in first and fail on the cold-boot ordering every app actually has.
+ *
+ * Driven through the real global `fetch`, spied — the factory takes no
+ * transport, so a test that built its own client would be asserting against a
+ * re-implementation of the thing under test rather than against it.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import { OxyInferenceClient } from '../../inference/OxyInferenceClient';
+
+describe('OxyServices.inference()', () => {
+    let fetchSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+        fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(
+            new Response(JSON.stringify({ data: [], count: 0 }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+            }),
+        );
+    });
+
+    afterEach(() => {
+        fetchSpy.mockRestore();
+    });
+
+    it('returns one memoized client, so a consumer can hold it', () => {
+        const oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+
+        const first = oxy.inference();
+        expect(first).toBeInstanceOf(OxyInferenceClient);
+        expect(oxy.inference()).toBe(first);
+    });
+
+    it('binds this instance base URL and reads the bearer at request time', async () => {
+        const oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+        const client = oxy.inference();
+
+        // The token is planted AFTER the client exists — the cold-boot order.
+        oxy.setTokens('planted-later');
+        await client.listModels();
+
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+        expect(String(url)).toBe('http://test.invalid/v1/models');
+        expect((init.headers as Record<string, string>)['Authorization']).toBe(
+            'Bearer planted-later',
+        );
+    });
+});

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

@@ -50,6 +50,7 @@ const signServiceToken = (claims: ServiceTokenClaims, secret: string): string =>
     aud: 'oxy-api',
     iss: 'oxy-auth',
     credentialId: 'cred-1',
+    ownerAccountId: 'owner-account-1',
     environment: 'production',
     ...claims,
   };
@@ -184,6 +185,7 @@ describe('C3: service-token acting-as enforcement', () => {
       appId: 'app-1',
       appName: 'trusted-service',
       credentialId: 'cred-1',
+      ownerAccountId: 'owner-account-1',
       scopes: ['user:read'],
       environment: 'production',
     });

package/src/mixins/index.ts

@@ -33,6 +33,7 @@ import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
+import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 
@@ -72,6 +73,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
@@ -156,6 +158,12 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // shared across applications, with per-application context on top.
     OxyServicesFollowGraphMixin,
 
+    // The inference model catalogue (#972). Reads only, and deliberately no
+    // request/stream/receipt methods — the public inference edge those would
+    // call is workstream 4 and does not exist yet. See
+    // `docs/inference/README.md` for what is and is not built.
+    OxyServicesInferenceMixin,
+
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,

package/src/server/__tests__/serviceTokenAttribution.test.ts

@@ -0,0 +1,396 @@
+/**
+ * Canonical request attribution for service tokens (ADR 0007, issue #972 §2.2).
+ *
+ * Two claims are under test, and they are different claims:
+ *
+ *  1. A VERIFIED service token names the whole attribution tuple locally —
+ *     application, credential, owning account, environment and effective
+ *     scopes — so a verifier with no database can say who is responsible.
+ *  2. A delegated `X-Oxy-User-Id` can never become that responsible party. It
+ *     is visible exactly where delegation is meant to be visible
+ *     (`req.userId`, `getOxyDelegatedUserId`) and nowhere else.
+ *
+ * Everything runs through the REAL `oxy.auth()` middleware with a real HMAC
+ * signature, so the assertions are about the shipped lane rather than a
+ * hand-built request object. The one exception is deliberate and marked: the
+ * tampering cases plant fields on an already-authenticated request to prove the
+ * billing resolver does not read them.
+ */
+
+import crypto from 'node:crypto';
+import { OxyServices } from '../../OxyServices';
+import {
+  getOxyBillingPrincipal,
+  getOxyDelegatedUserId,
+  getOxyRequestAttribution,
+  getRequiredOxyBillingPrincipal,
+  getRequiredOxyUserId,
+} from '../auth';
+import type { Request } from 'express';
+
+const SERVICE_SECRET = 'attribution-suite-secret-not-production';
+const OWNER_ACCOUNT = 'account-owning-the-application';
+const DELEGATED_USER = 'end-user-the-service-acts-for';
+
+interface Claims {
+  [key: string]: unknown;
+}
+
+const b64url = (input: Buffer | string): string =>
+  (typeof input === 'string' ? Buffer.from(input, 'utf8') : input)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+/** Sign an HS256 JWT byte-identically to `POST /auth/service-token`. */
+function signServiceToken(claims: Claims = {}, secret = SERVICE_SECRET): string {
+  const now = Math.floor(Date.now() / 1000);
+  const payload: Claims = {
+    iat: now,
+    exp: now + 3600,
+    type: 'service',
+    aud: 'oxy-api',
+    iss: 'oxy-auth',
+    appId: 'app-1',
+    appName: 'relay',
+    credentialId: 'cred-1',
+    ownerAccountId: OWNER_ACCOUNT,
+    environment: 'production',
+    scopes: ['inference:invoke'],
+    ...claims,
+  };
+  const headerB64 = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const payloadB64 = b64url(JSON.stringify(payload));
+  const signature = crypto
+    .createHmac('sha256', secret)
+    .update(`${headerB64}.${payloadB64}`)
+    .digest('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+  return `${headerB64}.${payloadB64}.${signature}`;
+}
+
+interface MockReq {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  userId?: string | null;
+  user?: unknown;
+  serviceApp?: unknown;
+  serviceActingAs?: unknown;
+  accessToken?: string;
+}
+
+interface MockRes {
+  statusCode: number;
+  body: unknown;
+  headersSent: boolean;
+  status(code: number): MockRes;
+  json(body: unknown): MockRes;
+}
+
+const makeReq = (headers: Record<string, string> = {}): MockReq => ({
+  method: 'POST',
+  path: '/v1/responses',
+  headers,
+  query: {},
+});
+
+const makeRes = (): MockRes => ({
+  statusCode: 0,
+  body: undefined,
+  headersSent: false,
+  status(code: number) {
+    this.statusCode = code;
+    return this;
+  },
+  json(body: unknown) {
+    this.body = body;
+    this.headersSent = true;
+    return this;
+  },
+});
+
+/** Run `oxy.auth()` over a request and report what the middleware decided. */
+async function authenticate(
+  oxy: OxyServices,
+  headers: Record<string, string>,
+  options: Parameters<OxyServices['auth']>[0] = { jwtSecret: SERVICE_SECRET },
+): Promise<{ req: MockReq; res: MockRes; nextCalled: boolean }> {
+  const req = makeReq(headers);
+  const res = makeRes();
+  const next = jest.fn();
+  const middleware = oxy.auth(options);
+  await middleware(req as unknown as never, res as unknown as never, next as unknown as never);
+  return { req, res, nextCalled: next.mock.calls.length > 0 };
+}
+
+/** `MockReq` is the structural subset the resolvers read; Express's own shape is irrelevant here. */
+const asRequest = (req: MockReq): Request => req as unknown as Request;
+
+let oxy: OxyServices;
+
+beforeEach(() => {
+  oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+});
+
+describe('a verified service token resolves the whole attribution tuple locally', () => {
+  it('names application, credential, owning account, environment and effective scopes', async () => {
+    const { req, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    expect(nextCalled).toBe(true);
+    expect(getOxyBillingPrincipal(asRequest(req))).toEqual({
+      accountId: OWNER_ACCOUNT,
+      applicationId: 'app-1',
+      credentialId: 'cred-1',
+      environment: 'production',
+      scopes: ['inference:invoke'],
+    });
+  });
+
+  it('reports the effective scopes verbatim — nothing re-intersects them here', async () => {
+    // The mint already intersected credential ∩ application via the API's
+    // `intersectScopes`. If this side narrowed again it would be a second
+    // authority, and the two could disagree.
+    const token = signServiceToken({ scopes: ['inference:invoke', 'inference:models:read'] });
+    const { req } = await authenticate(oxy, { authorization: `Bearer ${token}` });
+
+    expect(getRequiredOxyBillingPrincipal(asRequest(req)).scopes).toEqual([
+      'inference:invoke',
+      'inference:models:read',
+    ]);
+  });
+
+  it('has no principal at all for an unauthenticated request', () => {
+    expect(getOxyBillingPrincipal(asRequest(makeReq()))).toBeNull();
+    expect(() => getRequiredOxyBillingPrincipal(asRequest(makeReq()))).toThrow(
+      'no verified Oxy service principal',
+    );
+  });
+});
+
+describe('a delegated X-Oxy-User-Id is attribution, never the payer', () => {
+  it('leaves the billing account untouched while the delegated user stays visible', async () => {
+    jest
+      .spyOn(oxy, 'verifyServiceActingAs')
+      .mockResolvedValue({ authorized: true, scopes: ['user:read'] });
+
+    const { req, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+      'x-oxy-user-id': DELEGATED_USER,
+    });
+
+    expect(nextCalled).toBe(true);
+
+    // The assertion that matters: who pays does not move.
+    const principal = getRequiredOxyBillingPrincipal(asRequest(req));
+    expect(principal.accountId).toBe(OWNER_ACCOUNT);
+    expect(principal.accountId).not.toBe(DELEGATED_USER);
+
+    // The POSITIVE CONTROL. Without it, a resolver that simply returned a
+    // constant would pass the line above. The delegated id must be visible
+    // exactly where delegation is supposed to be visible.
+    expect(getOxyDelegatedUserId(asRequest(req))).toBe(DELEGATED_USER);
+    expect(getRequiredOxyUserId(asRequest(req))).toBe(DELEGATED_USER);
+    expect(getOxyRequestAttribution(asRequest(req))).toEqual({
+      accountId: OWNER_ACCOUNT,
+      applicationId: 'app-1',
+      credentialId: 'cred-1',
+      environment: 'production',
+      scopes: ['inference:invoke'],
+      delegatedUserId: DELEGATED_USER,
+    });
+  });
+
+  it('resolves the SAME billing account with and without delegation', async () => {
+    jest
+      .spyOn(oxy, 'verifyServiceActingAs')
+      .mockResolvedValue({ authorized: true, scopes: ['user:read'] });
+
+    const withDelegation = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+      'x-oxy-user-id': DELEGATED_USER,
+    });
+    const withoutDelegation = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    // Restated as ADR 0007 states it: removing `userId` from a request must not
+    // change what any account is charged.
+    expect(getRequiredOxyBillingPrincipal(asRequest(withDelegation.req))).toEqual(
+      getRequiredOxyBillingPrincipal(asRequest(withoutDelegation.req)),
+    );
+    expect(getOxyDelegatedUserId(asRequest(withoutDelegation.req))).toBeNull();
+    expect(withoutDelegation.req.userId).toBeNull();
+  });
+
+  it('ignores a userId planted on an already-authenticated request', async () => {
+    const { req } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    // Deliberate tampering AFTER authentication: this is the shape a downstream
+    // middleware bug takes. `getOxyBillingPrincipal` must read `serviceApp` and
+    // nothing else, so none of these can move the answer.
+    req.userId = DELEGATED_USER;
+    req.user = { id: DELEGATED_USER };
+    req.serviceActingAs = { userId: DELEGATED_USER, scopes: [] };
+
+    expect(getRequiredOxyBillingPrincipal(asRequest(req)).accountId).toBe(OWNER_ACCOUNT);
+    // Control: the planted fields ARE readable through the user-identity
+    // accessor, so the assertion above is about the resolver's inputs and not
+    // about the fields being unset.
+    expect(getRequiredOxyUserId(asRequest(req))).toBe(DELEGATED_USER);
+  });
+
+  it('does not put the delegated user anywhere on the service principal', async () => {
+    jest
+      .spyOn(oxy, 'verifyServiceActingAs')
+      .mockResolvedValue({ authorized: true, scopes: ['user:read'] });
+
+    const { req } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+      'x-oxy-user-id': DELEGATED_USER,
+    });
+
+    // A field-name-agnostic sweep: no value of `req.serviceApp`, at any depth
+    // this object has, may equal the delegated id. A future field called
+    // `userId`/`subject`/`onBehalfOf` would fail here without anyone having to
+    // remember to extend the list above.
+    expect(JSON.stringify(req.serviceApp)).not.toContain(DELEGATED_USER);
+  });
+});
+
+describe('signature verification is mandatory before any claim is trusted', () => {
+  it('refuses a token signed with a different secret (401, no principal)', async () => {
+    const forged = signServiceToken({}, 'a-secret-the-issuer-never-used');
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${forged}`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+    expect(req.serviceApp).toBeUndefined();
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+
+  it('refuses a token whose payload was edited after signing', async () => {
+    // The attack the claim set invites: take a real token and rewrite
+    // `ownerAccountId` to somebody else's account. The signature covers the
+    // payload, so the edit must not survive.
+    const token = signServiceToken();
+    const [headerB64, , signatureB64] = token.split('.');
+    const tamperedPayload = b64url(
+      JSON.stringify({
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'service',
+        aud: 'oxy-api',
+        iss: 'oxy-auth',
+        appId: 'app-1',
+        appName: 'relay',
+        credentialId: 'cred-1',
+        ownerAccountId: 'somebody-elses-account',
+        environment: 'production',
+        scopes: ['inference:invoke'],
+      }),
+    );
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${headerB64}.${tamperedPayload}.${signatureB64}`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(req.serviceApp).toBeUndefined();
+  });
+
+  it('refuses an UNSIGNED token (alg: none, empty signature segment)', async () => {
+    const headerB64 = b64url(JSON.stringify({ alg: 'none', typ: 'JWT' }));
+    const payloadB64 = b64url(
+      JSON.stringify({
+        type: 'service',
+        appId: 'app-1',
+        appName: 'relay',
+        credentialId: 'cred-1',
+        ownerAccountId: OWNER_ACCOUNT,
+        environment: 'production',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        aud: 'oxy-api',
+        iss: 'oxy-auth',
+      }),
+    );
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${headerB64}.${payloadB64}.`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(req.serviceApp).toBeUndefined();
+  });
+
+  it('refuses every service token when no verification secret is configured', async () => {
+    // The secure default: without a secret the middleware CANNOT verify, so it
+    // must not fall back to reading the decoded claims.
+    const { req, res, nextCalled } = await authenticate(
+      oxy,
+      { authorization: `Bearer ${signServiceToken()}` },
+      {},
+    );
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(403);
+    expect(res.body).toMatchObject({ code: 'SERVICE_TOKEN_NOT_CONFIGURED' });
+    expect(req.serviceApp).toBeUndefined();
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+
+  it('attaches no principal on the OPTIONAL lane either', async () => {
+    // `optional: true` degrades to anonymous rather than 401 — the thing that
+    // must not happen is degrading to an UNVERIFIED principal.
+    const forged = signServiceToken({}, 'wrong-secret');
+    const { req, nextCalled } = await authenticate(
+      oxy,
+      { authorization: `Bearer ${forged}` },
+      { jwtSecret: SERVICE_SECRET, optional: true },
+    );
+
+    expect(nextCalled).toBe(true);
+    expect(req.serviceApp).toBeUndefined();
+    expect(req.userId).toBeNull();
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+});
+
+describe('the owning account is a required claim', () => {
+  it.each([
+    ['absent', undefined],
+    ['empty', ''],
+    ['a number', 42],
+    ['null', null],
+  ])('refuses a signature-valid token whose ownerAccountId is %s', async (_label, value) => {
+    const token = signServiceToken({ ownerAccountId: value });
+    const { req, res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${token}`,
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+    expect(getOxyBillingPrincipal(asRequest(req))).toBeNull();
+  });
+
+  it('accepts the same token once the claim is present — the control', async () => {
+    const { res, nextCalled } = await authenticate(oxy, {
+      authorization: `Bearer ${signServiceToken()}`,
+    });
+
+    expect(nextCalled).toBe(true);
+    expect(res.statusCode).toBe(0);
+  });
+});