feat(phase-2): workstream 5 — OPA Policy Engine

- policies/authz.rego: Rego policy with path normalisation and scope enforcement
- policies/data/scopes.json: all 13 endpoint → scope mappings
- src/middleware/opa.ts: OpaMiddleware with Wasm primary path + scopes.json fallback;
  exports createOpaMiddleware() and reloadOpaPolicy() for SIGHUP hot-reload
- All four route files: opaMiddleware wired after authMiddleware
- AuditController, OAuth2Service: manual scope checks removed (now centralised in OPA)
- src/server.ts: SIGHUP handler calls reloadOpaPolicy()
- docs/devops/environment-variables.md: POLICY_DIR documented
- 38 new tests; 302/302 passing; opa.ts coverage 98.66% statements

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tests/unit/services/OAuth2Service.test.ts

@@ -13,7 +13,6 @@ import {
   AuthenticationError,
   AuthorizationError,
   FreeTierLimitError,
-  InsufficientScopeError,
 } from '../../../src/utils/errors';
 import { IAgent, ICredential, ICredentialRow, ITokenPayload } from '../../../src/types/index';
 import { hashSecret, generateClientSecret } from '../../../src/utils/crypto';
@@ -91,7 +90,7 @@ describe('OAuth2Service', () => {
       revokedAt: null,
     };
 
-    credentialRow = { ...mockCredential, secretHash };
+    credentialRow = { ...mockCredential, secretHash, vaultPath: null };
 
     credentialRepo.findByAgentId.mockResolvedValue({ credentials: [mockCredential], total: 1 });
     credentialRepo.findById.mockResolvedValue(credentialRow);
@@ -188,11 +187,14 @@ describe('OAuth2Service', () => {
       expect(result.active).toBe(false);
     });
 
-    it('should throw InsufficientScopeError if caller lacks tokens:read', async () => {
+    it('should introspect successfully regardless of caller scope (tokens:read enforced by OPA middleware)', async () => {
+      // Scope enforcement for tokens:read has been moved to OpaMiddleware.
+      // The service introspects any token presented to it once the request has
+      // passed the middleware layer.
+      tokenRepo.isRevoked.mockResolvedValue(false);
       const noScopePayload = { ...callerPayload, scope: 'agents:read' };
-      await expect(
-        service.introspectToken(validToken, noScopePayload, IP, UA),
-      ).rejects.toThrow(InsufficientScopeError);
+      const result = await service.introspectToken(validToken, noScopePayload, IP, UA);
+      expect(result.active).toBe(true);
     });
 
     it('should return active: false for an expired token', async () => {