stela ops usage fixes roles propagation and timoeut, one account to support multi tenants, migrations consolidation, search to support documentation, doctor and open api vector db search

docs/modules/router/authority-gateway-enforcement-runbook.md

@@ -0,0 +1,81 @@
+# 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`).