@oxy.so/core 1.18.0 → 3.0.0

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

@@ -1,889 +0,0 @@
-/**
- * Service-token security regression tests
- *
- * Locks in the fixes for C3, H1, H2, H4 from the 1.11.14 security audit.
- * Each scenario maps to a vulnerability that previously let a service token
- * either (a) impersonate any user without proof, (b) leak across tenants
- * via the per-instance cache, (c) silently 500 on malformed input, or
- * (d) accept tokens signed for the wrong audience/issuer/type.
- *
- * The tests use a real OxyServices instance with `makeRequest` stubbed so we
- * can exercise the middleware's verification logic end-to-end without
- * hitting the network or jsonwebtoken (which is a server-only dep).
- */
-
-import crypto from 'node:crypto';
-import { OxyServices } from '../../OxyServices';
-import { ServiceCredentialMismatchError } from '../OxyServices.auth';
-
-// ---------------------------------------------------------------------------
-// Helpers — sign and decode HS256 JWTs the same way the API does. These match
-// the on-the-wire format produced by `jsonwebtoken.sign({...}, secret, {})`
-// in the API's `/auth/service-token` route, so the SDK middleware sees
-// byte-identical input to production.
-// ---------------------------------------------------------------------------
-
-interface ServiceTokenClaims {
-  type?: string;
-  appId?: string;
-  appName?: string;
-  scopes?: string[];
-  aud?: string | string[];
-  iss?: string;
-  environment?: string;
-  exp?: number;
-  iat?: number;
-  [key: string]: unknown;
-}
-
-const b64url = (input: Buffer | string): string => {
-  const buf = typeof input === 'string' ? Buffer.from(input, 'utf8') : input;
-  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-};
-
-const signServiceToken = (claims: ServiceTokenClaims, secret: string): string => {
-  const header = { alg: 'HS256', typ: 'JWT' };
-  const payload: ServiceTokenClaims = {
-    iat: Math.floor(Date.now() / 1000),
-    exp: Math.floor(Date.now() / 1000) + 3600,
-    type: 'service',
-    aud: 'oxy-api',
-    iss: 'oxy-auth',
-    credentialId: 'cred-1',
-    ownerAccountId: 'owner-account-1',
-    environment: 'production',
-    scopes: [],
-    ...claims,
-  };
-  const headerB64 = b64url(JSON.stringify(header));
-  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;
-  sessionId?: string | null;
-}
-
-interface MockRes {
-  statusCode: number;
-  body: unknown;
-  headersSent: boolean;
-  status(code: number): MockRes;
-  json(body: unknown): MockRes;
-}
-
-const makeReq = (overrides: Partial<MockReq> = {}): MockReq => ({
-  method: 'GET',
-  path: '/test',
-  headers: {},
-  query: {},
-  ...overrides,
-});
-
-const makeRes = (): MockRes => {
-  const res: 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;
-    },
-  };
-  return res;
-};
-
-const SERVICE_SECRET = 'test-service-secret-for-regression-only-not-production';
-const OTHER_SECRET = 'a-completely-different-key-that-must-not-validate-tokens';
-
-// ---------------------------------------------------------------------------
-// C3 — service tokens require a valid acting-as grant for X-Oxy-User-Id
-// ---------------------------------------------------------------------------
-
-describe('C3: service-token acting-as enforcement', () => {
-  let oxy: OxyServices;
-
-  beforeEach(() => {
-    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
-  });
-
-  it('rejects X-Oxy-User-Id when no delegation grant exists (403)', async () => {
-    const verifySpy = jest
-      .spyOn(oxy, 'verifyServiceActingAs')
-      .mockResolvedValue(null);
-
-    const token = signServiceToken({ appId: 'app-1', appName: 'attacker-service' }, SERVICE_SECRET);
-    const req = makeReq({
-      headers: {
-        authorization: `Bearer ${token}`,
-        'x-oxy-user-id': 'victim-user-id',
-      },
-    });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    // OxyServices' middleware uses a loose Express shape — cast through unknown
-    // so we don't take a dep on @types/express in core just for tests.
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(verifySpy).toHaveBeenCalledWith('app-1', 'victim-user-id');
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(403);
-    expect(res.body).toMatchObject({
-      code: 'SERVICE_ACTING_AS_UNAUTHORIZED',
-    });
-  });
-
-  it('allows X-Oxy-User-Id when an authorized grant exists', async () => {
-    const verifySpy = jest
-      .spyOn(oxy, 'verifyServiceActingAs')
-      .mockResolvedValue({ authorized: true, scopes: ['user:read', 'files:write'] });
-
-    const token = signServiceToken(
-      { appId: 'app-1', appName: 'trusted-service', scopes: ['user:read'] },
-      SERVICE_SECRET,
-    );
-    const req = makeReq({
-      headers: {
-        authorization: `Bearer ${token}`,
-        'x-oxy-user-id': 'user-1',
-      },
-    });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(verifySpy).toHaveBeenCalledWith('app-1', 'user-1');
-    expect(next).toHaveBeenCalledTimes(1);
-    expect(res.headersSent).toBe(false);
-    expect(req.userId).toBe('user-1');
-    expect(req.serviceActingAs).toEqual({ userId: 'user-1', scopes: ['user:read', 'files:write'] });
-    expect(req.serviceApp).toEqual({
-      appId: 'app-1',
-      appName: 'trusted-service',
-      credentialId: 'cred-1',
-      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')
-      .mockResolvedValue(null);
-
-    const token = signServiceToken({ appId: 'app-1', appName: 'self-acting' }, SERVICE_SECRET);
-    const req = makeReq({
-      headers: { authorization: `Bearer ${token}` },
-    });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(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).toBeNull();
-    expect(req.serviceApp).toMatchObject({ appId: 'app-1', credentialId: 'cred-1' });
-  });
-
-  it('caches positive grants per (appId, userId) — avoids hammering verify endpoint', async () => {
-    const verifySpy = jest.spyOn(oxy, 'verifyServiceActingAs');
-    verifySpy.mockResolvedValueOnce({ authorized: true, scopes: ['user:read'] });
-
-    const token = signServiceToken({ appId: 'app-1', appName: 'svc' }, SERVICE_SECRET);
-    const req1 = makeReq({ headers: { authorization: `Bearer ${token}`, 'x-oxy-user-id': 'u-1' } });
-    const req2 = makeReq({ headers: { authorization: `Bearer ${token}`, 'x-oxy-user-id': 'u-1' } });
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    const next1 = jest.fn();
-    const next2 = jest.fn();
-    await mw(req1 as unknown as never, makeRes() as unknown as never, next1 as unknown as never);
-    // Force the spy to return null the second time — if the cache works, this
-    // is never called and the second request still succeeds.
-    verifySpy.mockResolvedValueOnce(null);
-    await mw(req2 as unknown as never, makeRes() as unknown as never, next2 as unknown as never);
-
-    // The cache logic lives in verifyServiceActingAs itself, which we have
-    // mocked. Restore and re-exercise to prove the SDK cache exists.
-    verifySpy.mockRestore();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// H1 — service-token cache must be keyed by (apiKey hash) AND verified
-// against the supplied secret on every hit. Cross-tenant leak prevention.
-// ---------------------------------------------------------------------------
-
-describe('H1: getServiceToken per-credential cache + secret verification', () => {
-  let oxy: OxyServices;
-  // Spy holder so each test can install its own mock.
-  let makeRequestSpy: jest.SpyInstance;
-
-  beforeEach(() => {
-    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
-    makeRequestSpy = jest.spyOn(oxy as unknown as { makeRequest: jest.Mock }, 'makeRequest');
-  });
-
-  afterEach(() => {
-    makeRequestSpy.mockRestore();
-  });
-
-  it('returns a cached token for the same (apiKey, apiSecret) without re-issuing', async () => {
-    makeRequestSpy.mockResolvedValueOnce({
-      token: 'token-A',
-      expiresIn: 3600,
-      appName: 'tenant-A',
-    });
-
-    const t1 = await oxy.getServiceToken('key-A', 'secret-A');
-    const t2 = await oxy.getServiceToken('key-A', 'secret-A');
-
-    expect(t1).toBe('token-A');
-    expect(t2).toBe('token-A');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
-  });
-
-  it('does NOT return tenant A token when called with tenant B credentials (per-credential cache)', async () => {
-    makeRequestSpy
-      .mockResolvedValueOnce({ token: 'token-A', expiresIn: 3600, appName: 'tenant-A' })
-      .mockResolvedValueOnce({ token: 'token-B', expiresIn: 3600, appName: 'tenant-B' });
-
-    const tokenA = await oxy.getServiceToken('key-A', 'secret-A');
-    const tokenB = await oxy.getServiceToken('key-B', 'secret-B');
-
-    expect(tokenA).toBe('token-A');
-    expect(tokenB).toBe('token-B');
-    expect(tokenA).not.toBe(tokenB);
-    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
-  });
-
-  it('throws ServiceCredentialMismatchError on cache hit with wrong secret (no token returned)', async () => {
-    makeRequestSpy.mockResolvedValueOnce({
-      token: 'token-A',
-      expiresIn: 3600,
-      appName: 'tenant-A',
-    });
-
-    // Seed the cache for key-A with secret-A.
-    await oxy.getServiceToken('key-A', 'secret-A');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
-
-    // Same apiKey, WRONG secret — must NOT receive tenant A's token.
-    await expect(
-      oxy.getServiceToken('key-A', 'wrong-secret'),
-    ).rejects.toBeInstanceOf(ServiceCredentialMismatchError);
-
-    // No re-issue attempted either — we reject immediately.
-    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
-  });
-
-  it('throws even when the wrong secret has different length (no length-based bypass)', async () => {
-    makeRequestSpy.mockResolvedValueOnce({
-      token: 'token-A',
-      expiresIn: 3600,
-      appName: 'tenant-A',
-    });
-
-    await oxy.getServiceToken('key-A', 'secret-A-which-is-quite-long');
-
-    await expect(oxy.getServiceToken('key-A', 'short')).rejects.toBeInstanceOf(
-      ServiceCredentialMismatchError,
-    );
-  });
-
-  it('does not poison the cache when initial token fetch fails for an apiKey', async () => {
-    makeRequestSpy
-      .mockRejectedValueOnce(new Error('invalid service credentials'))
-      .mockResolvedValueOnce({
-        token: 'token-A',
-        expiresIn: 3600,
-        appName: 'tenant-A',
-      });
-
-    await expect(oxy.getServiceToken('key-A', 'attacker-secret')).rejects.toThrow(
-      'invalid service credentials',
-    );
-
-    const token = await oxy.getServiceToken('key-A', 'secret-A');
-
-    expect(token).toBe('token-A');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
-  });
-
-  it('refreshes the cached token when it expires (using the correct stored secret)', async () => {
-    // First token already past its buffer window.
-    makeRequestSpy.mockResolvedValueOnce({
-      token: 'token-stale',
-      expiresIn: 30, // <60s buffer, so next call must refresh
-      appName: 'tenant-A',
-    });
-    makeRequestSpy.mockResolvedValueOnce({
-      token: 'token-fresh',
-      expiresIn: 3600,
-      appName: 'tenant-A',
-    });
-
-    const t1 = await oxy.getServiceToken('key-A', 'secret-A');
-    const t2 = await oxy.getServiceToken('key-A', 'secret-A');
-
-    expect(t1).toBe('token-stale');
-    expect(t2).toBe('token-fresh');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// invalidateServiceToken — clears the cached service token so the next
-// getServiceToken() mints anew, enabling recovery from a mid-run 401 (e.g.
-// credential revocation) without waiting for natural token expiry.
-// ---------------------------------------------------------------------------
-
-describe('invalidateServiceToken: forces a fresh mint after a same-run 401', () => {
-  let oxy: OxyServices;
-  let makeRequestSpy: jest.SpyInstance;
-
-  beforeEach(() => {
-    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
-    makeRequestSpy = jest.spyOn(oxy as unknown as { makeRequest: jest.Mock }, 'makeRequest');
-  });
-
-  afterEach(() => {
-    makeRequestSpy.mockRestore();
-  });
-
-  it('re-mints on the next getServiceToken() after invalidation (configured credential)', async () => {
-    makeRequestSpy
-      .mockResolvedValueOnce({ token: 'token-first', expiresIn: 3600, appName: 'tenant-A' })
-      .mockResolvedValueOnce({ token: 'token-second', expiresIn: 3600, appName: 'tenant-A' });
-
-    oxy.configureServiceAuth('key-A', 'secret-A');
-
-    const first = await oxy.getServiceToken();
-    // Cached — would normally be returned again without re-minting.
-    const cached = await oxy.getServiceToken();
-    expect(first).toBe('token-first');
-    expect(cached).toBe('token-first');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
-
-    // Simulate a 401: invalidate, then the very next call must mint anew.
-    oxy.invalidateServiceToken();
-
-    const fresh = await oxy.getServiceToken();
-    expect(fresh).toBe('token-second');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
-  });
-
-  it('clears only the targeted apiKey entry, leaving other tenants cached', async () => {
-    makeRequestSpy
-      .mockResolvedValueOnce({ token: 'token-A1', expiresIn: 3600, appName: 'tenant-A' })
-      .mockResolvedValueOnce({ token: 'token-B1', expiresIn: 3600, appName: 'tenant-B' })
-      .mockResolvedValueOnce({ token: 'token-A2', expiresIn: 3600, appName: 'tenant-A' });
-
-    await oxy.getServiceToken('key-A', 'secret-A');
-    await oxy.getServiceToken('key-B', 'secret-B');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
-
-    // Invalidate only tenant A.
-    oxy.invalidateServiceToken('key-A');
-
-    // Tenant A re-mints...
-    const a2 = await oxy.getServiceToken('key-A', 'secret-A');
-    expect(a2).toBe('token-A2');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(3);
-
-    // ...tenant B is still cached (no extra mint).
-    const b1 = await oxy.getServiceToken('key-B', 'secret-B');
-    expect(b1).toBe('token-B1');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(3);
-  });
-
-  it('clears every entry when no key is configured and none is passed', async () => {
-    makeRequestSpy
-      .mockResolvedValueOnce({ token: 'token-A1', expiresIn: 3600, appName: 'tenant-A' })
-      .mockResolvedValueOnce({ token: 'token-B1', expiresIn: 3600, appName: 'tenant-B' })
-      .mockResolvedValueOnce({ token: 'token-A2', expiresIn: 3600, appName: 'tenant-A' })
-      .mockResolvedValueOnce({ token: 'token-B2', expiresIn: 3600, appName: 'tenant-B' });
-
-    await oxy.getServiceToken('key-A', 'secret-A');
-    await oxy.getServiceToken('key-B', 'secret-B');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
-
-    // No configureServiceAuth() and no argument → clear all.
-    oxy.invalidateServiceToken();
-
-    const a2 = await oxy.getServiceToken('key-A', 'secret-A');
-    const b2 = await oxy.getServiceToken('key-B', 'secret-B');
-    expect(a2).toBe('token-A2');
-    expect(b2).toBe('token-B2');
-    expect(makeRequestSpy).toHaveBeenCalledTimes(4);
-  });
-
-  it('is a no-op safe to call when nothing is cached', () => {
-    expect(() => oxy.invalidateServiceToken()).not.toThrow();
-    expect(() => oxy.invalidateServiceToken('key-unknown')).not.toThrow();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// H2 — malformed tokens must yield 401, not 500. Uses class-based error
-// detection so future failure modes can't silently fall through.
-// ---------------------------------------------------------------------------
-
-describe('H2: malformed service tokens return 401 (not 500)', () => {
-  let oxy: OxyServices;
-
-  beforeEach(() => {
-    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
-    // Ensure verifyServiceActingAs is never reached for these tests.
-    jest.spyOn(oxy, 'verifyServiceActingAs').mockResolvedValue(null);
-  });
-
-  it('rejects a token with only 2 parts as 401 (signature error)', async () => {
-    const headerB64 = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
-    const payloadB64 = b64url(JSON.stringify({ type: 'service', appId: 'a', exp: 99999999999 }));
-    const malformed = `${headerB64}.${payloadB64}`; // missing signature
-
-    const req = makeReq({ headers: { authorization: `Bearer ${malformed}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    // jwtDecode rejects 2-part tokens (it expects header.payload.sig), so
-    // we land in INVALID_TOKEN_FORMAT. Either way, status MUST be 401.
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.statusCode).not.toBe(500);
-  });
-
-  it('rejects a token with empty signature segment as 401', async () => {
-    const headerB64 = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
-    const payloadB64 = b64url(JSON.stringify({ type: 'service', appId: 'a', exp: 99999999999, aud: 'oxy-api', iss: 'oxy-auth' }));
-    const malformed = `${headerB64}.${payloadB64}.`; // empty signature
-
-    const req = makeReq({ headers: { authorization: `Bearer ${malformed}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.statusCode).not.toBe(500);
-  });
-
-  it('rejects a service token signed with the wrong secret as 401', async () => {
-    const token = signServiceToken({ appId: 'a', appName: 'svc' }, OTHER_SECRET);
-
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
-  });
-
-  it('does not call onError with a 500 for any malformed-token shape', async () => {
-    const onError = jest.fn();
-
-    for (const malformed of [
-      'not.a.jwt',
-      'too.many.parts.here.now',
-      'aaa.bbb.', // empty sig
-      Buffer.from('garbage').toString('base64'), // 1 segment
-    ]) {
-      const req = makeReq({ headers: { authorization: `Bearer ${malformed}` } });
-      const res = makeRes();
-      const next = jest.fn();
-      const mw = oxy.auth({ jwtSecret: SERVICE_SECRET, onError });
-      await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-    }
-
-    for (const call of onError.mock.calls) {
-      const err = call[0] as { status?: number };
-      expect(err.status).not.toBe(500);
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// H4 — aud / iss / type claim verification. A token signed with the right
-// secret but the wrong audience, issuer, or type MUST be rejected.
-// ---------------------------------------------------------------------------
-
-describe('H4: aud / iss / type claim verification', () => {
-  let oxy: OxyServices;
-
-  beforeEach(() => {
-    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
-    jest.spyOn(oxy, 'verifyServiceActingAs').mockResolvedValue({ authorized: true, scopes: [] });
-  });
-
-  it('rejects a token with the wrong audience', async () => {
-    const token = signServiceToken(
-      { appId: 'a', appName: 'svc', aud: 'wrong-audience' },
-      SERVICE_SECRET,
-    );
-
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN_CLAIMS' });
-  });
-
-  it('rejects a token with the wrong issuer', async () => {
-    const token = signServiceToken(
-      { appId: 'a', appName: 'svc', iss: 'evil-auth' },
-      SERVICE_SECRET,
-    );
-
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN_CLAIMS' });
-  });
-
-  it("rejects a recovery/access token (type !== 'service') replayed as a service token", async () => {
-    // This is the H4 cross-token-type attack: same shared secret, valid
-    // signature, but the original token was minted as `type: 'access'` or
-    // `type: 'recovery'`. Without claim binding it would be accepted.
-    const accessToken = signServiceToken(
-      { appId: 'a', appName: 'svc', type: 'access', userId: 'attacker' },
-      SERVICE_SECRET,
-    );
-
-    const req = makeReq({ headers: { authorization: `Bearer ${accessToken}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    // The middleware branches on `decoded.type === 'service'` first, so an
-    // access-type token never enters the service-token verification path —
-    // it falls through to the user-token path, where it would be rejected
-    // for missing sessionId on this fake. Either way, next() is NOT called
-    // with the service-app claim set.
-    expect(req.serviceApp).toBeUndefined();
-  });
-
-  it("rejects a token claiming type='service' but with a non-string type field (defence in depth)", async () => {
-    const token = signServiceToken(
-      // Casting through unknown to inject a malformed claim — production
-      // libraries should never emit this, but a malicious or buggy auth
-      // server might. The SDK must still refuse it.
-      { appId: 'a', appName: 'svc', type: 'service', iss: 'wrong-iss' } as unknown as ServiceTokenClaims,
-      SERVICE_SECRET,
-    );
-
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN_CLAIMS' });
-  });
-
-  it('accepts a token with array-form audience that includes oxy-api', async () => {
-    const token = signServiceToken(
-      { appId: 'a', appName: 'svc', aud: ['oxy-api', 'other-audience'] },
-      SERVICE_SECRET,
-    );
-
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).toHaveBeenCalledTimes(1);
-    expect(req.serviceApp).toMatchObject({ appId: 'a', credentialId: 'cred-1' });
-  });
-
-  it('honors expectedAudience and expectedIssuer overrides', async () => {
-    const token = signServiceToken(
-      { appId: 'a', appName: 'svc', aud: 'custom-api', iss: 'custom-auth' },
-      SERVICE_SECRET,
-    );
-
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({
-      jwtSecret: SERVICE_SECRET,
-      expectedAudience: 'custom-api',
-      expectedIssuer: 'custom-auth',
-    });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// requireScope — scope enforcement for service-token-protected routes.
-// ---------------------------------------------------------------------------
-
-describe('requireScope() middleware', () => {
-  let oxy: OxyServices;
-
-  beforeEach(() => {
-    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
-      // attached `serviceApp`. requireScope() only reads from that field.
-    });
-    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['files:write'] };
-    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);
-    expect(res.headersSent).toBe(false);
-  });
-
-  it('allows delegated requests only when both app and delegation carry the required scope', () => {
-    const req = makeReq();
-    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['user:read'] };
-    req.serviceActingAs = { userId: 'u-1', scopes: ['user:read'] };
-    const res = makeRes();
-    const next = jest.fn();
-
-    oxy.requireScope('user:read')(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('rejects delegated requests when only the app carries the required scope', () => {
-    const req = makeReq();
-    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['files:write'] };
-    req.serviceActingAs = { userId: 'u-1', scopes: ['profile:read'] };
-    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);
-    expect(res.body).toMatchObject({ code: 'INSUFFICIENT_SCOPE' });
-  });
-
-  it('rejects delegated requests when only the delegation carries the required scope', () => {
-    const req = makeReq();
-    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['profile:read'] };
-    req.serviceActingAs = { userId: 'u-1', scopes: ['files:write'] };
-    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);
-    expect(res.body).toMatchObject({ code: 'INSUFFICIENT_SCOPE' });
-  });
-
-  it('rejects requests missing the required scope with 403', () => {
-    const req = makeReq();
-    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['user:read'] };
-    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);
-    expect(res.body).toMatchObject({ code: 'INSUFFICIENT_SCOPE' });
-  });
-
-  it('rejects requests not authenticated via a service token with 403', () => {
-    const req = makeReq();
-    // No serviceApp attached — this is a regular user request.
-    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);
-    expect(res.body).toMatchObject({ code: 'SERVICE_TOKEN_REQUIRED' });
-  });
-
-  it('throws if scope argument is missing/empty (programmer error)', () => {
-    expect(() => oxy.requireScope('')).toThrow('requireScope');
-    expect(() => oxy.requireScope(undefined as unknown as string)).toThrow('requireScope');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// service-token environment claim (F2.0 task 1b) — test/live isolation.
-// ---------------------------------------------------------------------------
-
-describe('service-token environment claim (F2.0 task 1b)', () => {
-  let oxy: OxyServices;
-
-  beforeEach(() => {
-    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
-  });
-
-  it('populates req.serviceApp.environment from the token claim', async () => {
-    const token = signServiceToken(
-      { appId: 'app-1', appName: 'svc', environment: 'development' },
-      SERVICE_SECRET,
-    );
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).toHaveBeenCalledTimes(1);
-    expect(req.serviceApp).toMatchObject({ appId: 'app-1', environment: 'development' });
-  });
-
-  it('rejects a service token missing the environment claim (401)', async () => {
-    const token = signServiceToken(
-      { appId: 'app-1', appName: 'svc', environment: undefined },
-      SERVICE_SECRET,
-    );
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
-  });
-
-  it('rejects a service token with an environment value outside the known set (401)', async () => {
-    const token = signServiceToken(
-      { appId: 'app-1', appName: 'svc', environment: 'bogus' },
-      SERVICE_SECRET,
-    );
-    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
-    const res = makeRes();
-    const next = jest.fn();
-
-    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
-    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(401);
-    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
-  });
-});