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
• Router__Frame__Envelope__ActiveKeyId
• Router__Frame__Envelope__Keys__<key-id>

Gateway-side frame protection uses the same Router__Frame__Envelope__* key map. The canonical compose maps primary to STELLAOPS_IDENTITY_ENVELOPE_SIGNING_KEY on the gateway and every Router microservice. A partially configured frame-envelope section fails startup; an omitted section retains bootstrap verifier-disabled mode and is not an acceptable production posture.

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. Drain Router messaging queues before first enabling frame protection; unsigned in-flight frames are rejected/dead-lettered after the verifier activates.
2. Rotate Authority/gateway signing material using the Authority key-rotation SOP:

• docs/modules/authority/operations/key-rotation.md

3. Add the new frame key id/material to every gateway and service verifier map.
4. Restart services, verify the new key is accepted, then flip Router__Frame__Envelope__ActiveKeyId on frame producers.
5. Restart gateway and services in wave order and remove the previous key only after the old-frame replay window and queue leases have expired.
6. Validate with targeted tests, route smoke, and zero unexpected router_frame_envelope_verify_failed_total{reason} growth.

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:

$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):

$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).