# Router Authority Enforcement Runbook

This runbook documents operational semantics for gateway-enforced authorization and signed user-identity propagation in Stella Router deployments.

## Scope
- Router gateway as centralized policy decision point (PDP).
- Authority-driven effective claims.
- Signed identity envelope propagation to webservices using Router trust mode.

## Required Configuration

Gateway-side:
- `Gateway__Auth__Authority__Issuer`
- `Gateway__Auth__Authority__RequireHttpsMetadata`
- `Router__OnMissingAuthorization`

Service-side (per service `Router` section):
- `Router__Enabled`
- `Router__AuthorizationTrustMode`
- `Router__IdentityEnvelopeSigningKey`
- `Router__IdentityEnvelopeClockSkewSeconds`

Identity transport headers emitted by gateway:
- `X-StellaOps-Identity-Envelope`
- `X-StellaOps-Identity-Envelope-Signature`
- `X-StellaOps-Identity-Envelope-Alg`
- `X-StellaOps-Identity-Envelope-Kid`
- `X-StellaOps-Identity-Envelope-Iat`
- `X-StellaOps-Identity-Envelope-Exp`

## Trust Modes

`ServiceEnforced`
- Service enforces its local policies.
- Gateway envelope is optional for service authorization.

`Hybrid`
- Service accepts gateway envelope when present.
- Service can fall back to local checks for compatibility.

`GatewayEnforced`
- Service requires valid signed gateway envelope.
- Missing/invalid envelope is fail-closed (`403`/`401` based on service policy).
- Use for centralized authorization rollout after verification.

## Key Rotation Procedure
1. Rotate Authority/gateway signing material using the Authority key-rotation SOP:
- `docs/modules/authority/operations/key-rotation.md`
2. Update `Router__IdentityEnvelopeSigningKey` for gateway and services.
3. Restart gateway and services in wave order (gateway first).
4. Validate with targeted tests and route smoke.

## Authority Outage and Fallback

If Authority is degraded/unreachable:
1. Keep gateway running with last known effective claim cache.
2. For critical service continuity, temporarily switch affected services:
- `Router__AuthorizationTrustMode=Hybrid`
3. If envelope verification is disrupted by key mismatch, switch to `ServiceEnforced` only as emergency fallback.
4. Record incident window and restore target mode (`GatewayEnforced` or `Hybrid`) after recovery.

## Compose Toggle Examples

Global gateway mode:
```powershell
$env:ROUTER_GATEWAY_CONFIG = "./router-gateway-local.json"
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d
```

Emergency compatibility fallback (example service):
```powershell
$env:SCANNER_ROUTER_ENABLED = "true"
$env:Router__AuthorizationTrustMode = "Hybrid"
docker compose -f devops/compose/docker-compose.stella-ops.yml up -d scanner-web
```

## Verification Checklist
- Gateway route smoke has `500=0`.
- OpenAPI operations expose `x-stellaops-gateway-auth`.
- Envelope spoofing tests pass (`IdentityHeaderPolicyMiddlewareTests`).
- Authority refresh tests pass (`AuthorityClaimsRefreshServiceTests`).