docs consolidation

docs/modules/gateway/identity-header-policy.md

@@ -1,8 +1,9 @@
-# Gateway · Identity Header Policy for Router Dispatch (Draft v0.1)
+# Gateway · Identity Header Policy for Router Dispatch
 
 ## Status
-- Draft; intended for implementation via a dedicated sprint.
-- Last updated: 2025-12-23 (UTC).
+- **Implemented** in Sprint 8100.0011.0002.
+- Middleware: `src/Gateway/StellaOps.Gateway.WebService/Middleware/IdentityHeaderPolicyMiddleware.cs`
+- Last updated: 2025-12-24 (UTC).
 
 ## Why This Exists
 The Gateway is the single HTTP ingress point and routes requests to internal microservices over Router transports. Many services (and legacy components) still rely on **header-based identity context** (tenant/scopes/actor) rather than (or in addition to) `HttpContext.User` claims.
@@ -11,16 +12,17 @@ This creates a hard security requirement:
 - **Clients must never be able to inject/override “roles/scopes” headers** that the downstream service trusts.
 - The Gateway must derive the effective identity from the validated JWT/JWK token (or explicit anonymous identity) and **overwrite** downstream identity headers accordingly.
 
-## Current State (Repo Reality)
-The Gateway WebService currently contains middleware that propagates claims into request headers:
-- `src/Gateway/StellaOps.Gateway.WebService/Middleware/ClaimsPropagationMiddleware.cs`
-- `src/Gateway/StellaOps.Gateway.WebService/Middleware/TenantMiddleware.cs`
+## Implementation
 
-### Known gaps vs intended behavior
-1) **Spoofing risk:** claim propagation uses “set if missing”, so client-supplied headers can pass through unmodified.
-2) **Claim type mismatch:** current middleware uses `tid`, but canonical tenant claim type is `stellaops:tenant` (`StellaOpsClaimTypes.Tenant`).
-3) **Scope claim mismatch:** tokens may use `scp` (individual scope items) and/or `scope` (space-separated). Current middleware reads only `scope`.
-4) **Docs drift:** `docs/api/gateway/tenant-auth.md` describes `X-Stella-*` headers and scope override behavior that is not implemented in the Gateway WebService.
+The `IdentityHeaderPolicyMiddleware` (introduced in Sprint 8100.0011.0002) replaces the legacy middleware:
+- ~~`src/Gateway/StellaOps.Gateway.WebService/Middleware/ClaimsPropagationMiddleware.cs`~~ (retired)
+- ~~`src/Gateway/StellaOps.Gateway.WebService/Middleware/TenantMiddleware.cs`~~ (retired)
+
+### Resolved issues
+1) **Spoofing risk:** ✅ Fixed. Middleware uses "strip-and-overwrite" semantics—reserved headers are stripped before claims are extracted and downstream headers are written.
+2) **Claim type mismatch:** ✅ Fixed. Middleware uses `StellaOpsClaimTypes.Tenant` (`stellaops:tenant`) with fallback to legacy `tid` claim.
+3) **Scope claim mismatch:** ✅ Fixed. Middleware extracts scopes from both `scp` (individual claims) and `scope` (space-separated) claims.
+4) **Docs alignment:** ✅ Reconciled in this sprint.
 
 ## Policy Goals
 - **No client-controlled identity headers:** the Gateway rejects or strips identity headers coming from external clients.
@@ -83,21 +85,45 @@ Draft enforcement:
 - Optional controlled override: allow only when `Gateway:Auth:AllowScopeHeader=true`, and only for explicitly allowed environments (offline/pre-prod).
 - Even when allowed, the override must not silently escalate a request beyond what the token allows unless the request is explicitly unauthenticated and the environment is configured for offline operation.
 
-## Implementation Notes (Draft)
-### Suggested refactor
-Replace the current “set-if-missing” propagation with a single middleware:
-- `IdentityHeaderPolicyMiddleware`
-  - strips reserved headers
-  - overwrites headers from claims
-  - stores normalized values in `HttpContext.Items` (tenant, actor, scope set) for use by rate limits, routing decisions, and audit logs
+## Implementation Details
+
+### Middleware Registration
+The middleware is registered in `Program.cs` after authentication:
+```csharp
+app.UseAuthentication();
+app.UseMiddleware<SenderConstraintMiddleware>();
+app.UseMiddleware<IdentityHeaderPolicyMiddleware>();
+```
+
+### Configuration
+Options are configured via `GatewayOptions.Auth`:
+```yaml
+Gateway:
+  Auth:
+    EnableLegacyHeaders: true     # Write X-Stella-* in addition to X-StellaOps-*
+    AllowScopeHeader: false       # Forbid client scope headers (default)
+```
+
+### HttpContext.Items Keys
+The middleware stores normalized identity in `HttpContext.Items` using `GatewayContextKeys`:
+- `Gateway.TenantId` — extracted tenant identifier
+- `Gateway.ProjectId` — extracted project identifier (optional)
+- `Gateway.Actor` — subject/actor from claims or "anonymous"
+- `Gateway.Scopes` — `HashSet<string>` of scopes
+- `Gateway.IsAnonymous` — `bool` indicating anonymous request
+- `Gateway.DpopThumbprint` — JKT from cnf claim (if present)
+- `Gateway.CnfJson` — raw cnf claim JSON (if present)
 
 ### Tests
-- Unit tests: spoofed identity headers are removed and overwritten.
-- Unit tests: claim type mapping uses `StellaOpsClaimTypes.*` correctly.
-- Integration tests: routed request arrives at microservice with correct identity headers.
+Located in `src/Gateway/__Tests/StellaOps.Gateway.WebService.Tests/Middleware/IdentityHeaderPolicyMiddlewareTests.cs`:
+- ✅ Spoofed identity headers are stripped and overwritten
+- ✅ Claim type mapping uses `StellaOpsClaimTypes.*` correctly
+- ✅ Anonymous requests receive explicit `anonymous` identity
+- ✅ Legacy headers are written when `EnableLegacyHeaders=true`
+- ✅ Scopes are sorted deterministically
 
 ## Related Documents
 - Gateway architecture: `docs/modules/gateway/architecture.md`
-- Tenant auth contract (Web V): `docs/api/gateway/tenant-auth.md` (note: currently drifts from implementation)
+- Tenant auth contract (Web V): `docs/api/gateway/tenant-auth.md`
 - Router ASP.NET bridge: `docs/modules/router/aspnet-endpoint-bridge.md`