fix(oauth): env vars override profile config; fix envelope restart-recovery gaps

- MCP4_ALLOW_UNREGISTERED_CLIENTS/MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS/
  MCP4_ALLOWED_ORIGINS now take full precedence over profile JSON when set;
  previously ?? meant allow_unregistered_clients=false in profile blocked env var
- Envelope restart-recovery: populate inboundAuthTokenStore after createSession
  so enterprise enforcement works for restored sessions; move oauthTokensByAccessToken
  population post-createSession to prevent map leaks on init failure
- Stale envelope (>30 days) now returns HTTP 401 instead of creating scopeless session
- Fix entry guard: !tokenData instead of !refreshToken to skip recovery when
  oauthTokensByAccessToken already populated (non-rotating IdPs with no refresh token)

Co-Authored-By: Agent <noreply@anthropic.com>

Author: David Ruzicka

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `ClientAuthGate` orchestrator wired into HTTP transport session init: validates inbound client API key before session establishment; resolves `AuthorizedPrincipal` (authType=`token`) and attaches it as `session.clientPrincipal`; mode-aware (`required` rejects with HTTP 401 when no identity is resolved, `optional` allows anonymous sessions); when configured, the gate becomes the inbound auth authority and bypasses the legacy `authConfigs` token-required guard so `mode='optional'` can permit anonymous initialization (AUTH-02; partial AUTH-03). JWT/OIDC gate added in Phase 4.
 
 ### Fixed
+- `MCP4_ALLOW_UNREGISTERED_CLIENTS`, `MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS`, and `MCP4_ALLOWED_ORIGINS` env vars now act as operator overrides: when set, they take full precedence over profile JSON values (previously `??` meant `allow_unregistered_clients: false` in profile silently blocked the env var).
+- Encrypted token envelope restart-recovery: `inboundAuthTokenStore` now populated after session creation (fixes enterprise enforcement on restored sessions); stale envelopes (>30 days) now return HTTP 401 instead of silently creating a scopeless session; map population moved post-`createSession` to prevent map leaks on init failure; entry guard changed from `!refreshToken` to `!tokenData` to correctly skip recovery when OAuth map already populated for non-rotating IdPs.
 - Invalid supplied tokens during HTTP session initialization now return HTTP 403 instead of 401, preventing VS Code from misclassifying bearer-token failures as OAuth discovery and showing an irrelevant dynamic client registration prompt.
 - Tenant OAuth degradation: auth gate now checks `isOAuthConfigOperational` on the effective OAuth config (which may be tenant-specific) so an inoperational tenant OAuth config no longer sends an uncompletable 401 OAuth challenge.
 - Server-side env token validation at session init: when a profile auth config has both `value_from_env` and `validation_endpoint`, the resolved env token is validated via the endpoint before the session is established, failing fast with HTTP 401 instead of accepting the connection and returning 401 on every tool call.

src/mcp/mcp-server.test.ts

@@ -867,6 +867,119 @@ paths:
       expect(context.oauthConfig?.allowed_unregistered_redirect_uris).toEqual(['http://localhost', 'cursor://']);
     });
 
+    it('MCP4_ALLOW_UNREGISTERED_CLIENTS=true overrides profile allow_unregistered_clients=false', () => {
+      const serverWithMock = new MCPServer({
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any);
+
+      (serverWithMock as any).parser = {
+        getBaseUrl: () => 'https://api.test',
+        getResourceMetadata: () => ({ name: 'Test', documentation: 'Docs' })
+      };
+
+      (serverWithMock as any).profile = {
+        profile_name: 'test',
+        description: 'test profile',
+        tools: [],
+        interceptors: {
+          auth: [{
+            type: 'oauth',
+            priority: 1,
+            oauth_config: {
+              issuer: 'https://issuer.test',
+              client_id: 'client-id',
+              redirect_uri: 'https://app.test/callback',
+              allow_unregistered_clients: false,
+            }
+          }]
+        }
+      };
+
+      process.env.MCP4_ALLOW_UNREGISTERED_CLIENTS = 'true';
+      process.env.MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS = 'http://localhost';
+
+      const context = serverWithMock.getHttpProfileContext();
+      expect(context.oauthConfig?.allow_unregistered_clients).toBe(true);
+    });
+
+    it('MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS overrides profile allowed_unregistered_redirect_uris', () => {
+      const serverWithMock = new MCPServer({
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any);
+
+      (serverWithMock as any).parser = {
+        getBaseUrl: () => 'https://api.test',
+        getResourceMetadata: () => ({ name: 'Test', documentation: 'Docs' })
+      };
+
+      (serverWithMock as any).profile = {
+        profile_name: 'test',
+        description: 'test profile',
+        tools: [],
+        interceptors: {
+          auth: [{
+            type: 'oauth',
+            priority: 1,
+            oauth_config: {
+              issuer: 'https://issuer.test',
+              client_id: 'client-id',
+              redirect_uri: 'https://app.test/callback',
+              allow_unregistered_clients: true,
+              allowed_unregistered_redirect_uris: ['http://profile-only.example.com'],
+            }
+          }]
+        }
+      };
+
+      process.env.MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS = 'http://localhost,http://127.0.0.1';
+
+      const context = serverWithMock.getHttpProfileContext();
+      expect(context.oauthConfig?.allowed_unregistered_redirect_uris).toEqual(['http://localhost', 'http://127.0.0.1']);
+    });
+
+    it('MCP4_ALLOWED_ORIGINS overrides profile allowed_redirect_hosts', () => {
+      const serverWithMock = new MCPServer({
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      } as any);
+
+      (serverWithMock as any).parser = {
+        getBaseUrl: () => 'https://api.test',
+        getResourceMetadata: () => ({ name: 'Test', documentation: 'Docs' })
+      };
+
+      (serverWithMock as any).profile = {
+        profile_name: 'test',
+        description: 'test profile',
+        tools: [],
+        interceptors: {
+          auth: [{
+            type: 'oauth',
+            priority: 1,
+            oauth_config: {
+              issuer: 'https://issuer.test',
+              client_id: 'client-id',
+              redirect_uri: 'https://app.test/callback',
+              allowed_redirect_hosts: ['profile-host.example.com'],
+            }
+          }]
+        }
+      };
+
+      process.env.MCP4_ALLOWED_ORIGINS = 'https://env-host.example.com';
+
+      const context = serverWithMock.getHttpProfileContext();
+      expect(context.oauthConfig?.allowed_redirect_hosts).toEqual(['env-host.example.com']);
+    });
+
     it('should derive OAuth redirect hosts and token limits from environment', async () => {
       const capturedConfigs: any[] = [];
 

src/mcp/mcp-server.ts

@@ -683,16 +683,15 @@ export class MCPServer {
 
     return {
       ...oauthConfig,
-      allowed_redirect_hosts: oauthConfig.allowed_redirect_hosts
-        || (process.env.MCP4_ALLOWED_ORIGINS
-          ? this.extractHostsFromOrigins(process.env.MCP4_ALLOWED_ORIGINS)
-          : undefined),
-      allow_unregistered_clients: oauthConfig.allow_unregistered_clients
-        ?? (process.env.MCP4_ALLOW_UNREGISTERED_CLIENTS === 'true'),
-      allowed_unregistered_redirect_uris: oauthConfig.allowed_unregistered_redirect_uris
-        || (allowedUnregisteredRedirectUris && allowedUnregisteredRedirectUris.length > 0
-          ? allowedUnregisteredRedirectUris
-          : undefined),
+      allowed_redirect_hosts: process.env.MCP4_ALLOWED_ORIGINS
+        ? this.extractHostsFromOrigins(process.env.MCP4_ALLOWED_ORIGINS)
+        : oauthConfig.allowed_redirect_hosts,
+      allow_unregistered_clients: process.env.MCP4_ALLOW_UNREGISTERED_CLIENTS !== undefined
+        ? process.env.MCP4_ALLOW_UNREGISTERED_CLIENTS === 'true'
+        : (oauthConfig.allow_unregistered_clients ?? false),
+      allowed_unregistered_redirect_uris: allowedUnregisteredRedirectUris && allowedUnregisteredRedirectUris.length > 0
+        ? allowedUnregisteredRedirectUris
+        : oauthConfig.allowed_unregistered_redirect_uris,
     };
   }
 

src/transport/http-transport.test.ts

@@ -2783,8 +2783,11 @@ describeIfListen('HttpTransport', () => {
     });
 
     it('does not warn about MCP4_TOKEN_KEY when tokenKey is set', async () => {
+      const savedKey = process.env.MCP4_TOKEN_KEY;
+      delete process.env.MCP4_TOKEN_KEY;
       const mockLogger = buildMockLogger();
       const t = new HttpTransport({ ...baseConfig, tokenKey: Buffer.alloc(32) }, mockLogger);
+      if (savedKey !== undefined) process.env.MCP4_TOKEN_KEY = savedKey;
       const warnCalls = mockLogger.warn.mock.calls;
       const matchingCall = warnCalls.find((args: unknown[]) =>
         typeof args[0] === 'string' && (args[0] as string).includes('MCP4_TOKEN_KEY'),
@@ -2793,6 +2796,21 @@ describeIfListen('HttpTransport', () => {
       await t.stop();
     });
 
+    it('warns when MCP4_TOKEN_KEY is a passphrase (non-hex key)', async () => {
+      const savedKey = process.env.MCP4_TOKEN_KEY;
+      process.env.MCP4_TOKEN_KEY = 'my-weak-passphrase';
+      const mockLogger = buildMockLogger();
+      const t = new HttpTransport({ ...baseConfig, tokenKey: Buffer.alloc(32) }, mockLogger);
+      if (savedKey !== undefined) process.env.MCP4_TOKEN_KEY = savedKey;
+      else delete process.env.MCP4_TOKEN_KEY;
+      const warnCalls = mockLogger.warn.mock.calls;
+      const matchingCall = warnCalls.find((args: unknown[]) =>
+        typeof args[0] === 'string' && (args[0] as string).includes('MCP4_TOKEN_KEY is a passphrase'),
+      );
+      expect(matchingCall).toBeDefined();
+      await t.stop();
+    });
+
     it('accepts a 4096-char token at the new DEFAULT_MAX_TOKEN_LENGTH boundary', async () => {
       const t = new HttpTransport({ ...baseConfig }, logger);
       const tApp = (t as any).app;
@@ -3881,6 +3899,8 @@ describeIfListen('HttpTransport', () => {
       expect(returned.startsWith('mcp4.v1.')).toBe(true);
       expect(profileState.oauthTokensByAccessToken.has(returned)).toBe(true);
       expect(profileState.oauthTokensByAccessToken.has(tokens.access_token)).toBe(false);
+      const mapEntry = profileState.oauthTokensByAccessToken.get(returned);
+      expect(mapEntry?.rawAccessToken).toBe('idp-access-d');
       await t.stop();
     });
 
@@ -4481,6 +4501,165 @@ describeIfListen('HttpTransport', () => {
       expect(restoredCall).toBeUndefined();
       await t.stop();
     });
+
+    it('Test S: stale envelope (>30 days old) returns 401 with warn log', async () => {
+      const { encryptTokenPayload } = await import('../auth/token-envelope.js');
+      const mockLogger = mkLogger();
+      const key = buildKey();
+      const t = buildTransport({ tokenKey: key, testLogger: mockLogger });
+      const tApp = (t as any).app;
+      t.setMessageHandler(async () => ({ protocolVersion: '2025-03-26', serverInfo: { name: 'test' } }));
+
+      const staleIat = Date.now() - (31 * 24 * 60 * 60 * 1000);
+      const envelope = encryptTokenPayload(
+        { v: 1, at: 'idp-access-s', rt: 'idp-refresh-s', pid: 'default', iat: staleIat },
+        key,
+      );
+
+      const response = await request(tApp)
+        .post('/mcp')
+        .set('Accept', 'application/json, text/event-stream')
+        .set('Authorization', `Bearer ${envelope}`)
+        .send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });
+
+      expect(response.status).toBe(401);
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        'Encrypted token envelope expired (iat too old)',
+        expect.objectContaining({ profileId: 'default' }),
+      );
+      // No session created
+      const profileState = (t as any).__test_profileState;
+      expect(profileState.sessions.size).toBe(0);
+      await t.stop();
+    });
+
+    it('Test T: envelope with creg but client already exists - registerClient NOT called, restoredClientReg=true', async () => {
+      const { encryptTokenPayload } = await import('../auth/token-envelope.js');
+      const key = buildKey();
+      const mockLogger = mkLogger();
+      const t = buildTransport({ tokenKey: key, testLogger: mockLogger });
+      const tApp = (t as any).app;
+      t.setMessageHandler(async () => ({ protocolVersion: '2025-03-26', serverInfo: { name: 'test' } }));
+
+      // Override getClient to return an existing client
+      const profileState = (t as any).__test_profileState;
+      const registerClientSpy = (t as any).__test_registerClientSpy;
+      profileState.oauthProvider.clientsStore.getClient = vi.fn(async () => ({ client_id: 'existing-t' }));
+
+      const envelope = encryptTokenPayload(
+        {
+          v: 1,
+          at: 'at-t',
+          rt: 'rt-t',
+          pid: 'default',
+          iat: Date.now(),
+          creg: { id: 'existing-t', ru: ['https://x/cb'] },
+        },
+        key,
+      );
+
+      await request(tApp)
+        .post('/mcp')
+        .set('Accept', 'application/json, text/event-stream')
+        .set('Authorization', `Bearer ${envelope}`)
+        .send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });
+
+      expect(registerClientSpy).not.toHaveBeenCalled();
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        'Session restored from encrypted token envelope after restart',
+        expect.objectContaining({ restoredClientReg: true }),
+      );
+      await t.stop();
+    });
+
+    it('Test U: registerClient throws during recovery - warn logged but session still created', async () => {
+      const { encryptTokenPayload } = await import('../auth/token-envelope.js');
+      const key = buildKey();
+      const mockLogger = mkLogger();
+      const t = buildTransport({ tokenKey: key, testLogger: mockLogger });
+      const tApp = (t as any).app;
+      t.setMessageHandler(async () => ({ protocolVersion: '2025-03-26', serverInfo: { name: 'test' } }));
+
+      const profileState = (t as any).__test_profileState;
+      class OAuthClientStoreCapacityError extends Error {
+        constructor() { super('capacity exceeded'); this.name = 'OAuthClientStoreCapacityError'; }
+      }
+      profileState.oauthProvider.clientsStore.registerClient = vi.fn(async () => { throw new OAuthClientStoreCapacityError(); });
+
+      const envelope = encryptTokenPayload(
+        {
+          v: 1,
+          at: 'at-u',
+          rt: 'rt-u',
+          pid: 'default',
+          iat: Date.now(),
+          creg: { id: 'client-u' },
+        },
+        key,
+      );
+
+      const response = await request(tApp)
+        .post('/mcp')
+        .set('Accept', 'application/json, text/event-stream')
+        .set('Authorization', `Bearer ${envelope}`)
+        .send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });
+
+      expect(response.status).toBe(200);
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        'Failed to re-register OAuth client from envelope during restart recovery',
+        expect.objectContaining({ clientId: 'client-u', errorType: 'OAuthClientStoreCapacityError' }),
+      );
+      // Session still created with refresh token
+      const session = findOnlySession(t);
+      expect(session).toBeDefined();
+      expect(session.refreshToken).toBe('rt-u');
+      await t.stop();
+    });
+
+    it('Test V: recovered envelope populates both oauthTokensByAccessToken and inboundAuthTokenStore', async () => {
+      const { encryptTokenPayload } = await import('../auth/token-envelope.js');
+      const key = buildKey();
+      const t = buildTransport({ tokenKey: key });
+      const tApp = (t as any).app;
+      t.setMessageHandler(async () => ({ protocolVersion: '2025-03-26', serverInfo: { name: 'test' } }));
+
+      const envelope = encryptTokenPayload(
+        {
+          v: 1,
+          at: 'raw-access-v',
+          rt: 'refresh-v',
+          exp: Date.now() + 60_000,
+          cid: 'client-v',
+          sc: ['read'],
+          pid: 'default',
+          iat: Date.now(),
+        },
+        key,
+      );
+
+      const response = await request(tApp)
+        .post('/mcp')
+        .set('Accept', 'application/json, text/event-stream')
+        .set('Authorization', `Bearer ${envelope}`)
+        .send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });
+
+      expect(response.status).toBe(200);
+
+      const profileState = (t as any).__test_profileState;
+      // oauthTokensByAccessToken must hold rawAccessToken for upstream calls
+      const mapEntry = profileState.oauthTokensByAccessToken.get(envelope);
+      expect(mapEntry).toBeDefined();
+      expect(mapEntry.rawAccessToken).toBe('raw-access-v');
+
+      // inboundAuthTokenStore must hold entry so enterprise/session checks resolve
+      const inboundStore = (t as any).inboundAuthTokenStore;
+      const record = inboundStore.get(envelope);
+      expect(record).toBeDefined();
+      expect(record.principal.authType).toBe('oauth');
+      expect(record.principal.clientId).toBe('client-v');
+
+      await t.stop();
+    });
   });
 
   describe('getSessionToken', () => {
@@ -4490,6 +4669,22 @@ describeIfListen('HttpTransport', () => {
       const token = transport.getSessionToken('default', sessionId);
       expect(token).toBe('my-auth-token');
     });
+
+    it('returns rawAccessToken when session.authToken is an encrypted envelope', () => {
+      const profileState = createProfileState(transport as any);
+      const envelopeToken = 'mcp4.v1.fake-envelope-token';
+      const rawAccessToken = 'real-idp-access-token';
+      const sessionId = (transport as any).createSession(profileState, envelopeToken);
+      profileState.oauthTokensByAccessToken.set(envelopeToken, {
+        refreshToken: 'refresh-x',
+        expiresAt: Date.now() + 60_000,
+        clientId: 'client-x',
+        scopes: ['read'],
+        rawAccessToken,
+      });
+      const token = transport.getSessionToken('default', sessionId);
+      expect(token).toBe(rawAccessToken);
+    });
   });
 
   describe('profile routing', () => {