docs(planning): narrow phase 3 client auth gate to inline API keys only

Author: David Ruzicka

.planning/ROADMAP.md

@@ -60,14 +60,14 @@ Plans:
 **Depends on**: Phase 1
 **Requirements**: AUTH-02, AUTH-03 (partial)
 **Success Criteria** (what must be TRUE):
-  1. An inbound M2M client presenting an API key is validated against the configured key store (inline env-var keys or Sasanka) and resolved to a client identity before session establishment
+  1. An inbound M2M client presenting an API key is validated against the configured key store (inline env-var keys) and resolved to a client identity before session establishment; Sasanka token-passthrough store added in Phase 4
   2. An invalid or missing API key when mode=required is rejected with HTTP 401 before any upstream connection
   3. The resolved client identity (API key path) is attached to the session as clientPrincipal and included in session-creation log entries
 **Plans**: 3 plans
 
 Plans:
 - [ ] 03-01-PLAN.md - Types (ApiKeyStoreConfig, ClientAuthGateConfig without jwt), ClientAuthGateError, schema sync, and profile-load-time validator (AUTH-02, AUTH-03)
-- [ ] 03-02-PLAN.md - ApiKeyStore interface, InlineApiKeyStore, SasankaApiKeyStore, and factory (AUTH-02)
+- [ ] 03-02-PLAN.md - ApiKeyStore interface, InlineApiKeyStore, and factory (AUTH-02; SasankaApiKeyStore deferred to Phase 4)
 - [ ] 03-03-PLAN.md - ClientAuthGate orchestrator (API key path only), http-transport wiring, session clientPrincipal attachment (AUTH-02, AUTH-03)
 
 ### Phase 4: Client Authentication Gate (OIDC JWT)
@@ -83,6 +83,7 @@ Plans:
 Plans:
 - [ ] 04-01: ClientAuthJwtConfig types, oidc-discovery utility, EnterpriseAuthProvider refactor (AUTH-01)
 - [ ] 04-02: JWT path in ClientAuthGate, JwksCache wiring, integration tests (AUTH-01, AUTH-03)
+- [ ] 04-03: SasankaApiKeyStore (token-passthrough via /api/v1/users/me), sasanka variant in ApiKeyStoreConfig, factory extension (AUTH-02)
 
 ### Phase 5: Observability
 **Goal**: Every tool call is audited with identity and outcome; operators have metrics and health endpoints to monitor the gateway

.planning/phases/03-client-authentication-gate/03-01-PLAN.md

@@ -139,16 +139,8 @@ export function validateEnterpriseAuthorizationProfile(profile: Profile): Enterp
     }
 
     export type ApiKeyStoreConfig =
-      | { type: 'inline'; keys: InlineApiKeyEntry[] }
-      | {
-          type: 'sasanka';
-          /** Base URL for the Sasanka API. Defaults to https://sasanka.seznam.net */
-          base_url?: string;
-          /** Resolve base_url from env var. */
-          base_url_from_env?: string;
-          /** Request timeout in ms for /users/me. Default: 5000. */
-          timeout_ms?: number;
-        };
+      | { type: 'inline'; keys: InlineApiKeyEntry[] };
+      // Phase 4 adds: | { type: 'sasanka'; base_url?: string; base_url_from_env?: string; timeout_ms?: number }
 
     export interface ClientAuthGateConfig {
       /** 'required' (default): reject session if no valid identity resolved. 'optional': allow anonymous sessions. */
@@ -205,20 +197,23 @@ export function validateEnterpriseAuthorizationProfile(profile: Profile): Enterp
   <verify>
     <automated>npm run generate-schemas && npm run check-schema-sync && npm run typecheck</automated>
   </verify>
-  <done>All three commands exit 0. ClientAuthGateConfig, ApiKeyStoreConfig, ClientAuthJwtConfig appear in src/generated-schemas.ts. SessionData.clientPrincipal typed as AuthorizedPrincipal. ClientAuthGateError exported from src/core/errors.ts. HttpProfileContext.client_auth_gate and HttpTransportConfig.client_auth_gate present.</done>
+  <done>All three commands exit 0. ClientAuthGateConfig and ApiKeyStoreConfig appear in src/generated-schemas.ts (NO ClientAuthJwtConfig — Phase 4). SessionData.clientPrincipal typed as AuthorizedPrincipal. ClientAuthGateError exported from src/core/errors.ts. HttpProfileContext.client_auth_gate and HttpTransportConfig.client_auth_gate present.</done>
 </task>
 
 <task type="auto" tdd="true">
   <name>Task 2: Implement validateClientAuthGateProfile() validator and wire into profile-loader</name>
   <files>src/profile/client-auth-gate-validator.ts, src/profile/client-auth-gate-validator.test.ts, src/profile/profile-loader.ts</files>
   <behavior>
-    - Valid profile with api_keys inline (non-empty keys array, each entry has key_from_env + subject) returns config
-    - Valid profile with api_keys sasanka returns config
+    - Valid profile with api_keys inline (non-empty keys array, each entry has key_from_env + subject, env vars set) returns config
+    - Profile with api_keys.type='sasanka' throws ClientAuthGateError (not supported until Phase 4)
     - Profile with api_keys.type='vault' throws ClientAuthGateError (unknown backend)
     - Profile with api_keys inline and empty keys[] throws ClientAuthGateError
+    - Profile with api_keys inline where key_from_env is "" throws ClientAuthGateError (trim check)
+    - Profile with api_keys inline where key_from_env env var is not set throws ClientAuthGateError (fail-fast)
     - Profile with no client_auth_gate field returns undefined (no-op)
+    - Profile with OAuth interceptor AND client_auth_gate throws ClientAuthGateError (mutual exclusion)
     - env var resolution — mode_from_env: set to 'optional' → mode resolved to 'optional'; unset → throws ClientAuthGateError
-    - env var resolution — base_url_from_env (sasanka): set → base_url resolved; unset → throws ClientAuthGateError
+    - env var resolution — mode_from_env set to invalid value 'admin' → throws ClientAuthGateError
   </behavior>
   <action>
     Create src/profile/client-auth-gate-validator.ts following the pattern of enterprise-profile-validator.ts:
@@ -229,9 +224,8 @@ export function validateEnterpriseAuthorizationProfile(profile: Profile): Enterp
     import { ClientAuthGateError } from '../core/errors.js';
     import type { ClientAuthGateConfig, Profile } from '../types/profile.js';
 
-    const DEFAULT_SASANKA_BASE_URL = 'https://sasanka.seznam.net';
-    const DEFAULT_TIMEOUT_MS = 5000;
-    const ALLOWED_API_KEY_TYPES = ['inline', 'sasanka'] as const;
+    const ALLOWED_API_KEY_TYPES = ['inline'] as const;
+    // Phase 4 adds 'sasanka' to ALLOWED_API_KEY_TYPES
 
     function resolveEnv(value: string | undefined, fromEnv: string | undefined, fieldPath: string): string | undefined {
       if (value) return value;
@@ -247,6 +241,14 @@ export function validateEnterpriseAuthorizationProfile(profile: Profile): Enterp
       const config = profile.client_auth_gate;
       if (!config) return undefined;
 
+      // Mutual exclusion: client_auth_gate cannot coexist with OAuth interceptors
+      const auths = profile.interceptors?.auth
+        ? (Array.isArray(profile.interceptors.auth) ? profile.interceptors.auth : [profile.interceptors.auth])
+        : [];
+      if (auths.some(a => a.type === 'oauth')) {
+        throw new ClientAuthGateError('client_auth_gate cannot be combined with OAuth interceptors; configure one inbound auth method per profile');
+      }
+
       // Resolve mode
       const mode = resolveEnv(config.mode, config.mode_from_env, 'client_auth_gate.mode') ?? 'required';
       if (mode !== 'required' && mode !== 'optional') {
@@ -266,20 +268,16 @@ export function validateEnterpriseAuthorizationProfile(profile: Profile): Enterp
             throw new ClientAuthGateError('client_auth_gate.api_keys.keys must be a non-empty array for type=inline');
           }
           for (const entry of apiKeys.keys) {
-            if (!entry.key_from_env) throw new ClientAuthGateError('client_auth_gate.api_keys.keys[].key_from_env is required');
-            if (!entry.subject) throw new ClientAuthGateError('client_auth_gate.api_keys.keys[].subject is required');
-          }
-        }
-        if (apiKeys.type === 'sasanka') {
-          const baseUrl = resolveEnv(apiKeys.base_url, apiKeys.base_url_from_env, 'client_auth_gate.api_keys.base_url') ?? DEFAULT_SASANKA_BASE_URL;
-          if (process.env.NODE_ENV !== 'test') {
-            const parsed = new URL(baseUrl);
-            if (parsed.protocol !== 'https:') {
-              throw new ClientAuthGateError('client_auth_gate.api_keys.base_url must use https');
+            if (!entry.key_from_env?.trim()) throw new ClientAuthGateError('client_auth_gate.api_keys.keys[].key_from_env is required');
+            if (!entry.subject?.trim()) throw new ClientAuthGateError('client_auth_gate.api_keys.keys[].subject is required');
+            // Fail-fast: catch misconfigured env vars at load time so operators get
+            // an actionable error instead of silent all-key rejection at runtime.
+            if (!process.env[entry.key_from_env]) {
+              throw new ClientAuthGateError(`client_auth_gate.api_keys.keys[].key_from_env: env var '${entry.key_from_env}' is not set`);
             }
           }
-          apiKeys = { ...apiKeys, base_url: baseUrl, timeout_ms: apiKeys.timeout_ms ?? DEFAULT_TIMEOUT_MS };
         }
+        // Phase 4 adds sasanka branch here
       }
 
       if (!apiKeys && mode === 'required') {