Router Architecture

Canonical specification for the Stella Ops Router — the single HTTP ingress and binary-transport dispatch layer for the Stella Ops release control plane. Audience: platform and service engineers who register microservices behind the gateway, plus operators configuring transports, routes, and TLS. The Router hosts StellaOps.Gateway.WebService; first-party services reach it over binary transports, never HTTP.

Companion specifications:

• Tenant selection and header propagation contract: ADR-002 — multi-tenant same-API-key selection
• Service impact ledger: multi-tenant-service-impact-ledger.md
• Flow sequences: multi-tenant-flow-sequences.md
• Rollout policy: multi-tenant-rollout-and-compatibility.md

Location clarification (updated 2026-03-04). The Router (src/Router/) hosts StellaOps.Gateway.WebService with configurable route tables via GatewayRouteCatalog, reverse proxy support, SPA fallback hosting, WebSocket routing, Valkey messaging transport integration, and StellaOpsRouteResolver for front-door dispatching. This is the canonical deployment for HTTP ingress. The standalone src/Gateway/ was deleted in Sprint 200.

System Architecture

Scope

• A single HTTP ingress service (StellaOps.Gateway.WebService) handles all external HTTP traffic
• Microservices communicate with the Gateway using binary transports (TCP, TLS, UDP, RabbitMQ)
• HTTP is not used for internal microservice-to-gateway traffic
• Request/response bodies are opaque to the router (raw bytes/streams)
• Forwarded HTTP headers remain case-insensitive across Router frame transport and ASP.NET bridge dispatch; lowercase HTTP/2 names such as content-type must be preserved for JSON-bound endpoints, and the ASP.NET bridge must mark POST/PUT/PATCH requests as body-capable so minimal-API JSON binding survives frame dispatch
• Gateway scope authorization evaluates against the resolved per-request scope set from identity expansion (GatewayContextKeys.Scopes), so coarse compatibility scopes such as orch:quota can satisfy their fine-grained frontdoor equivalents without changing downstream policy names

Transport Architecture

Mounted transport plugins (updated 2026-06-11). Router and Messaging transport bundles are composed at runtime from read-only mounted directories: devops/plugins/router/<profile>/<plugin-id>/ to /app/plugins/router/<profile>/<plugin-id>/ and devops/plugins/messaging/<profile>/<plugin-id>/ to /app/plugins/messaging/<profile>/<plugin-id>/. Trust roots mount at /app/trust-roots/plugins/{router,messaging}. The publish helper supports STELLAOPS_PLUGIN_PACKAGING_MODE=mounted, which skips baking Router/Messaging plugin payloads into service images; legacy image-staged mode remains only as a transition path until all mounted bundles and probes are green. Mounted mode is fail-closed for router-gateway: the publish helper audits the publish context before Docker build and rejects any remaining StellaOps.Router.Transport.* or StellaOps.Messaging.Transport.* implementation payloads. The companion ProjectReference audit reports direct gateway references to those implementation projects as mounted-router-messaging-coupling until the gateway host uses only abstractions plus signed mounted bundles for transport/backend registration.

Current source guard evidence (2026-06-11): docs/qa/feature-checks/runs/pluginized-compose/router-mounted-backend-admission-20260611/gateway-project-reference-audit.json scans the Router runtime host and passes with zero mounted-router-messaging-coupling references. The 2026-06-05 contract slice removed gateway compile-time references to optional TCP, TLS, and Messaging Postgres implementations and made gateway dispatch depend on host-owned interfaces from StellaOps.Router.Common: IGatewayConnectionTransportServer and IGatewayMessagingTransportServer. The 2026-06-06 Valkey diagnostics slice moved token-revocation propagation telemetry behind the transport-agnostic StellaOps.Messaging.Diagnostics contract and lets the Valkey backend plugin register the concrete store/writer. The 2026-06-06 mounted-bundle cutover removed the final StellaOps.Router.Transport.Messaging runtime ProjectReference, stopped defaulting Router/Messaging plugin discovery to image-resident assembly names, and teaches gateway startup to discover signed Router transport child bundles under /app/plugins/router/<profile>/<plugin-id>/. The actual Messaging backend registration path now receives the mounted Router:Messaging:PluginDirectory path via Gateway:Transports:Messaging:PluginDirectory, so a mounted Valkey bundle can be used without a gateway image dependency.

The 2026-06-11 backend admission slice extended the gateway Messaging backend path to pass Gateway:MessagingBackendPlugins:TrustRootPath, Profile, and EnforceSignatureVerification into MessagingPluginLoader and mirrors those values to Gateway:Transports:Messaging. Non-development startup forces signature verification on even if an operator sets the enforcement flag false. package-runtime-plugins.ps1 -Module router -Profile base produces the signed Router Messaging bundle with the dev signer, and -Module messaging -Profile base produces the signed Valkey backend bundle and matching cosign.pub.

This is still not full runtime acceptance. Runtime completion still requires a full compose startup/probe run that exercises static console routing, /connect/*, /api/*, route resync, and one Messaging/Valkey service call. The 2026-06-11 proof bundle refreshed static mount/admissibility evidence and a mounted-mode test image audit, but the live stellaops/router-gateway:dev compose tag and HTTP/runtime probes remain separate acceptance gates. The focused guard GatewayRuntimePluginReferenceGuardTests now freezes the zero-reference state so TCP, TLS, Router Messaging, Postgres, Valkey, or any new transport/backend implementation cannot re-enter the gateway project graph without failing the adjacent test.

Each transport connection carries:

• Initial identity (HELLO) and, when needed, endpoint metadata replay
• Ongoing heartbeats
• Request/response data frames
• Streaming data frames
• Cancellation frames

┌─────────────────┐                           ┌─────────────────┐
│   Microservice  │                           │     Gateway     │
│                 │         HELLO             │                 │
│   Identity      │ ─────────────────────────►│   Routing       │
│   - POST /items │         HEARTBEAT         │   State         │
│   - GET /items  │ ◄────────────────────────►│                 │
│   Metadata      │     RESYNC / ENDPOINTS    │   Connections[] │
│   replay        │ ◄────────────────────────►│                 │
│                 │                           │   Connections[] │
│                 │  REQUEST / RESPONSE       │                 │
│                 │ ◄────────────────────────►│                 │
│                 │                           │                 │
│                 │  STREAM_DATA / CANCEL     │                 │
│                 │ ◄────────────────────────►│                 │
└─────────────────┘                           └─────────────────┘

Front Door (Configurable Route Table)

The Router Gateway serves as the single HTTP entry point for the entire Stella Ops platform. In addition to binary transport routing for microservices, it handles:

• Static file serving (Angular SPA dist)
• Reverse proxy to HTTP-only backend services
• WebSocket proxy to upstream WebSocket servers
• SPA fallback (extensionless paths serve index.html)
• Custom error pages (404/500 HTML fallback)

Route Table Model

Routes are configured in Gateway:Routes as a StellaOpsRoute[] array, evaluated first-match-wins:

public sealed class StellaOpsRoute
{
    public StellaOpsRouteType Type { get; set; }
    public string Path { get; set; } = string.Empty;
    public bool IsRegex { get; set; }
    public string? TranslatesTo { get; set; }
    public Dictionary<string, string> Headers { get; set; } = new();

    // Optional route-level default timeout (e.g. "15s", "2m"); applied when
    // endpoint metadata does not provide a timeout.
    public string? DefaultTimeout { get; set; }

    // When true, the gateway preserves Authorization/DPoP headers instead of
    // stripping them. NOTE: defaults to true. Passthrough still requires the
    // route prefix to be in Gateway:Auth:ApprovedAuthPassthroughPrefixes.
    public bool PreserveAuthHeaders { get; set; } = true;
}

The StellaOpsRouteType enum members are declared in source order Microservice, ReverseProxy, StaticFiles, StaticFile, WebSocket, NotFoundPage, ServerErrorPage.

Route types:

Reverse proxy is reserved for external/bootstrap surfaces such as OIDC browser flows, Rekor, and frontdoor static assets. First-party Stella API surfaces are expected to use Microservice routing so the gateway remains the single routing authority instead of silently bypassing router registration state.

Regex microservice routes that own a root prefix must use a segment boundary when the same prefix can appear in static asset filenames. The local frontdoor uses ^/policy(?=/|$)(.*) rather than ^/policy(.*) so Angular chunks such as /policy-decisioning.routes-*.js stay on the SPA/static path instead of being misrouted to the Policy service.

Browser-facing compatibility prefixes that exist only at the frontdoor must also use segment boundaries and strip that prefix before dispatching to the target microservice. Local compose keeps /doctor/api/v1/doctor/* and /scheduler/api/v1/scheduler/* for the shell, but the route table translates ^/doctor(?=/|$)(.*) and ^/scheduler(?=/|$)(.*) to http://doctor.stella-ops.local$1 and http://scheduler.stella-ops.local$1 so the backend still receives its canonical /api/v1/<service>/* path without stealing SPA chunks such as doctor.routes-*.js.

Explicit v2 read-model routes must stay ahead of the generic ^/api/v2/{service} matcher. Local compose pins /api/v2/context*, /api/v2/releases*, /api/v2/topology*, /api/v2/evidence*, and /api/v2/integrations* to platform; /api/v2/security* is owned by findings-security. The related /api/risk/aggregated-status path is also routed to findings-security ahead of the Policy risk catch-all.

Deployment-topology setup aliases are owned by ReleaseOrchestrator, not Concelier. Both the source and local-compose route tables send regions, targets, infrastructure bindings, pending deletions, exact environment setup shapes, the exact /api/v1/agents list route, and exact agent/integration deletion-request routes to ReleaseOrchestrator while preserving authorization headers. Environment, agent, and integration patterns must remain narrow: never restore the former ^/api/v1/environments(.*) or ^/api/v1/agents(.*) Concelier rules, because they shadow unrelated owning-service routes.

Platform-owned admin subtrees that do not correspond to a standalone service must likewise stay explicit ahead of the generic ^/api/v1/{service} matcher. In particular, /api/v1/admin/migrations* routes to Platform’s migration-admin API and /api/v1/admin/crypto/secret-providers* routes to Platform’s sealed provider-discovery API with authorization headers preserved. Without these explicit routes the generic fallback treats admin as a service name and returns a false service-unavailable response.

Operational API families whose first path segment is not their owning service key also require explicit routes ahead of the generic matcher. /api/v1/issues* is owned by Concelier, while /api/v1/excititor/oci-trust-policies* is owned by Excititor and is rewritten to the handler’s canonical /excititor/oci-trust-policies* path. These rules are segment-bound so similarly prefixed paths cannot be captured accidentally.

Scanner’s /api/v1/reports* family also requires an explicit auth-preserving ReverseProxy route to scanner ahead of the generic matcher, matching Scanner’s existing HTTP-forwarded scan data plane. The rule preserves bearer authorization and prevents the generic /api/v1/{service} matcher from treating reports as a standalone service key.

Concelier raw-advisory readback has two explicit frontdoor routes ahead of the SPA/static fallback: /concelier/advisories/raw* is the public module-qualified contract, and /advisories/raw* is retained as a compatibility target for Concelier’s POST Location header. Both strip to Concelier’s canonical /advisories/raw* backend path and preserve auth headers. Broader /api/v1/advisories* traffic remains owned by AdvisoryAI.

Pipeline Order

System paths bypass the configured route table and the microservice pipeline. GatewayRoutes.IsSystemPath covers /health, /health/live, /health/ready, /health/startup, /metrics, /openapi.json, /openapi.yaml, /.well-known/openapi, /api/openapi/aggregate, the product-metadata endpoints (/.well-known/security.txt, /.well-known/stella-product-security.json, /api/v1/product/support-lifecycle), the router admin/operator surfaces (/api/v1/gateway/administration/router/resync, /api/v1/router/routing/weights, /api/v1/router/instances, /api/v1/operator/verify/*), and /buildinfo.json.

Actual middleware order from Program.cs (HTTPS redirect first, then):

CorrelationIdMiddleware
SecurityHeadersMiddleware
UseStellaOpsCors
UseAuthentication
SenderConstraintMiddleware
IdentityHeaderPolicyMiddleware   ← strips reserved identity headers, signs envelope
UseAuthorization
HealthCheckMiddleware            ← /health, /metrics
TryUseStellaRouter
UseWebSockets
ProductMetadataMiddleware        ← fail-closed product-security/lifecycle metadata
RouteDispatchMiddleware          ← static files, reverse proxy, websocket
MapGatewayOpenApiAggregator / MapGatewayBuildInfoAggregator / MapVerifyEndpoints /
  MapRoutingWeightEndpoints / MapRouterInstancesEndpoints / MapGatewayPluginProbeEndpoints /
  MapRouterAdministrationEndpoints
UseWhen(non-system):             ← microservice pipeline
  RequestLoggingMiddleware → GlobalErrorHandlerMiddleware → PayloadLimitsMiddleware →
  EndpointResolutionMiddleware → AuthorizationMiddleware → UseRateLimiting →
  RoutingDecisionMiddleware → RequestRoutingMiddleware
ErrorPageFallbackMiddleware      ← custom 404/500 pages

Regulatory Product Metadata Ingress

Router owns the externally visible product-security metadata endpoints before static console fallback and before generic /api/* dispatch:

• /.well-known/security.txt
• /.well-known/stella-product-security.json
• /api/v1/product/support-lifecycle

The endpoints are default-off and fail closed with 503 and an empty body when publication is disabled, sealed metadata config is absent, operational mailbox, key, placement, lifecycle, rotation, or escalation preflight is incomplete, the release manifest is missing, or manifest verification has not been recorded for the running product image. Published responses are generated from the sealed release metadata and carry strong ETags over the exact response bytes.

Router also owns regulatory feed minimisation at the ingress boundary. Route table entries opt in with the sealed route headers X-StellaOps-Regulatory-Feed: router-regulatory-feed-route-v1 and X-StellaOps-Regulatory-Purpose: <purpose>. The supported purpose values match Notify’s channel contract: general, dora-incident, dora-roi-distribution, dora-info-sharing, nis2-csirt, and enisa-cra. When a request hits an opted-in route, Router rewrites or replaces the downstream purpose query parameter before dispatching to Notify. Unknown or legacy route purposes fail closed to Notify’s backward-compatible general filter instead of leaking a regulatory feed to the wrong purpose.

Router does not duplicate Notify channel persistence. It only applies the sealed ingress purpose, forwards the normalized purpose to Notify, and emits a startup audit event using the shared EU catalog event name evidence.eu.public_metadata.published with a hash of the regulatory feed route table.

Docker Architecture

Browser → Router Gateway (port 80) → [microservices via binary transport]
                                    → [HTTP backends via reverse proxy]
                                    → [Angular SPA from /app/wwwroot]

Development compose may bind-mount the Angular dist at /app/wwwroot. Release images bake the verified dist directly into router-gateway at that same path; there is no separate console image or console-builder service in the release bundle.

When the gateway runs in-container, listener binding must honor explicit ASPNETCORE_URLS / ASPNETCORE_HTTP_PORTS / ASPNETCORE_HTTPS_PORTS values from compose. Wildcard hosts (+, *) are normalized to 0.0.0.0 before Kestrel listeners are created so the declared HTTP frontdoor contract actually comes up.

Service Identity

Instance Identity

Each microservice instance is identified by:

Version Matching

• Version matching is strict semver equality
• Router only routes to instances with exact version match
• Default version used when client doesn’t specify

Region Configuration

Gateway node identity comes from GatewayNodeOptions (bound from the Gateway:Node configuration section), which the host maps onto RouterNodeConfig (the routing-plugin’s node config; section name GatewayNode, legacy Router:Node):

public sealed class GatewayNodeOptions          // bound from "Gateway:Node"
{
    public string Region { get; set; } = "local";
    public string NodeId { get; set; } = string.Empty;
    public string Environment { get; set; } = "dev";
    public List<string> NeighborRegions { get; set; } = new();
}

RouterNodeConfig.Region is [Required]; the gateway fails to start without a region. NodeId is auto-generated as gw-<region>-<8hex> when left blank. NeighborRegions drives the Tier 1 region fallback in routing. Region is never derived from HTTP headers or URL hostnames.

Endpoint Model

Endpoint Identity

Endpoint identity is (HTTP Method, Path):

Endpoint Descriptor

Each endpoint includes:

public sealed record EndpointDescriptor
{
    public required string ServiceName { get; init; }
    public required string Version { get; init; }
    public required string Method { get; init; }
    public required string Path { get; init; }
    public TimeSpan DefaultTimeout { get; init; } = TimeSpan.FromSeconds(30);
    public IReadOnlyList<ClaimRequirement> RequiringClaims { get; init; } = [];
    public bool AllowAnonymous { get; init; }
    public bool RequiresAuthentication { get; init; }
    public IReadOnlyList<string> AuthorizationPolicies { get; init; } = [];
    public IReadOnlyList<string> Roles { get; init; } = [];
    public EndpointAuthorizationSource AuthorizationSource { get; init; } = EndpointAuthorizationSource.None;
    public bool SupportsStreaming { get; init; }
    public Type? HandlerType { get; init; }
    public EndpointSchemaInfo? SchemaInfo { get; init; }
}

EndpointDescriptor is a record (not a class) and carries richer authorization metadata than just RequiringClaims: discovered named policies, role names, an explicit anonymous/authenticated flag, and the AuthorizationSource (None, AspNetMetadata, YamlOverride, Hybrid, AuthorityOverride) that records where the authorization metadata was resolved from.

Path Matching

• ASP.NET-style route templates
• Parameter segments: {id}, {userId}
• Extra path segments are consumed only by explicit catch-all parameters ({**path}); ordinary terminal parameters must not behave like implicit catch-alls during messaging transport dispatch
• Case sensitivity and trailing slash handling follow ASP.NET conventions

Routing Algorithm

Instance Selection

Given (ServiceName, Version, Method, Path):

1. Filter candidates (DefaultRoutingPlugin):

   • Match ServiceName exactly
   • Match Version exactly (strict semver when StrictVersionMatching, which is the default; the requested version falls back to RoutingOptions.DefaultVersion when the caller omits it)
   • Draining instances are always excluded from new routing (they may only finish in-flight work)
   • Prefer Healthy; fall back to Degraded only when AllowDegradedInstances is enabled and no healthy instance remains

2. Region preference (only when PreferLocalRegion and a gateway region are set):

   • Tier 0: instances where Region == RouterNodeConfig.Region
   • Tier 1: configured NeighborRegions
   • Tier 2: all other regions

3. Within the best non-empty region tier:

   • Prefer lower AveragePingMs (within PingToleranceMs)
   • If tied, prefer more recent LastHeartbeatUtc
   • If multiple remain tied and they advertise differing non-default effective Weight values, use weighted random selection (canary)
   • Otherwise apply the configured tie-breaker: RoundRobin (per-service counter) or Random (default)

Instance Health

public enum InstanceHealthStatus
{
    Unknown,
    Healthy,
    Degraded,
    Draining,
    Unhealthy
}

Health metadata per connection:

Transport Layer

Transport Types

StellaOps.Router.Gateway is a legacy gateway library and is fail-closed by default: AddRouterGateway(...) does not register StellaOps.Router.Transport.InMemory or any other transport implicitly. Local process-only harnesses must opt in with AddRouterGatewayLocalInMemoryHarness(...), which is gated to Development, Testing, or Local host environments. Production ingress uses StellaOps.Gateway.WebService with configuration-driven transport activation.

Frame-layer Envelope HMAC

Every Request / Response / RequestStreamData / ResponseStreamData frame crossing a router transport carries an application-layer envelope MAC in addition to whatever transport-level integrity exists. Audit finding C9 in microservice-audit-pass2-2026-04-29.md recorded that messaging-transport consumers previously dispatched RPC payloads without verifying identity at the application layer, and finding C7 noted that TCP/UDP transports carry frames in cleartext. Sprint SPRINT_20260501_012 addresses both by adding a transport-agnostic frame-layer envelope.

Wire format. The seal is a sidecar struct travelling alongside the frame body, not a JSON wrapper around the payload. Stamped by StellaOps.Router.Common.Frames.HmacFrameEnvelopeSigner, verified by HmacFrameEnvelopeVerifier:

public sealed record FrameEnvelopeSeal {
    string KeyId;            // Key id; supports rotation via multiple loaded keys.
    string Algorithm;        // "HS256" — same marker used by GatewayIdentityEnvelope.
    DateTimeOffset IssuedAtUtc;
    string Mac;              // Base64Url-encoded HMAC-SHA256 output.
}

The seal hangs off Frame.EnvelopeSeal for in-process flow and is carried across transports as follows:

• Messaging (Valkey / Postgres / InMemory): a EnvelopeSeal field on RpcRequestMessage / RpcResponseMessage (JSON-serialised by the message broker).
• RabbitMQ: four AMQP headers — stellaops-frame-seal-keyid, stellaops-frame-seal-alg, stellaops-frame-seal-iat-ms, stellaops-frame-seal-mac.
• TCP / UDP / TLS: not yet wired into the binary frame protocol; these transports inherit application-layer integrity once the sidecar is added to the protocol header (follow-up sprint).

MAC input. Canonical bytes produced by FrameCanonicalBytes.Compute: explicit length-prefixed binary form with magic header FECB, version, frame type, correlation id, key id, and Unix-ms timestamp, payload bytes. Big-endian and length-delimited so the encoding is deterministic across processes / OS / language. JSON serialisation is not used — JSON property ordering is implementation-defined and would break sealing.

Key material. Configured via FrameEnvelopeOptions.Keys (a key-id -> UTF-8 secret map) bound from Router:Frame:Envelope. The Messaging and RabbitMQ transport plugins activate HmacFrameEnvelopeSigner plus HmacFrameEnvelopeVerifier when that section is present; a present but invalid section fails host registration rather than silently reverting to unsigned frames. The active key id on the signer side is FrameEnvelopeOptions.ActiveKeyId; the verifier trusts the key id carried inside the seal as long as it appears in the loaded Keys map. Rotation: load the new key on every host first, then flip ActiveKeyId on the gateway. The HMAC routes through StellaOps.Cryptography.IHmacAlgorithm so regional crypto plugins (FIPS, GOST, SM, eIDAS) can substitute the implementation; direct HMACSHA256 calls in product code are forbidden by the conformance test in src/Cryptography/__Tests/StellaOps.Cryptography.Tests/HmacBclCallSiteConformanceTests.cs.

Skew window. Default ±5 minutes (FrameEnvelopeOptions.ReplayWindow). Symmetric — past and future timestamps are checked. Air-gap deployments with significant clock drift may widen the window via configuration; document the chosen value in your operations runbook.

Failure modes. Verification rejects with a FrameEnvelopeRejectedException carrying a FrameEnvelopeRejectionReason: Missing, UnknownKeyId, UnsupportedAlgorithm, Malformed, TimestampOutOfWindow, MacMismatch, UnsupportedCanonicalVersion. The exception attaches structured metadata under keys frame.envelope.reason, frame.envelope.keyId, frame.envelope.issuedAt. The router_frame_envelope_verify_failed_total{reason} counter is incremented on each failure; the failure is logged at warning level with structured fields. On the messaging transport the forged frame is dead-lettered with reason envelope-invalid:<reason>. On RabbitMq the frame is dropped (autoAck=true) and the counter / log capture the audit.

Migration note. Existing dev compose deployments with unsigned frames in transit must drain queues before upgrading; otherwise legacy frames will hit the DLQ. Every supported Compose surface binds ActiveKeyId=primary and Keys:primary from the same value as STELLAOPS_IDENTITY_ENVELOPE_SIGNING_KEY: the canonical gateway and Router microservices, Findings Security canary, Tester, SmRemote, and the supported legacy monolith. The runtime-posture validator rejects any of these surfaces when its Router identity-envelope mapping lacks that matching frame-envelope pair. Custom hosts that omit FrameEnvelopeOptions retain the documented bootstrap posture: the messaging server / client log a startup warning and operate in verifier-disabled mode (no rejection); this is the documented bootstrap posture but must not persist into production. Setting only part of the section is not a compatibility escape hatch: registration fails closed when the active key, key material, or replay window is invalid.

Insecure Transport Gate (TCP/UDP)

Sprint SPRINT_20260501_012 demoted the TCP and UDP transports to dev-only. Their plugins (TcpTransportPlugin, UdpTransportPlugin) and registration helpers (AddTcpTransport*, AddUdpTransport*) call TcpTransportPlugin.IsInsecureTransportsAllowed() / UdpTransportPlugin.IsInsecureTransportsAllowed() at registration time and throw InvalidOperationException unless the environment variable STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS is set to a truthy value (true, 1, yes, case-insensitive).

When the override is in effect, the guard logs a loud warning indicating that TCP/UDP transports are unencrypted and replayable on the network layer; the override only relaxes the confidentiality and non-replay defenses. Frames over TCP/UDP still gain application-layer integrity through the frame-layer envelope HMAC described above.

Production composes (devops/compose/docker-compose.stella-services.yml) must not load these plugins. Migrate to StellaOps.Router.Transport.Tls or StellaOps.Router.Transport.Messaging for production traffic.

Signed Transport Plugin Loader (Sprint 20260501-005)

Sprint SPRINT_20260501_005 closed Pass-2 audit finding B5: the gateway transport plugin loader at src/Router/StellaOps.Gateway.WebService/Program.cs previously loaded any DLL matching StellaOps.Router.Transport.*.dll from plugins/router/transports/ with no signature verification. The gateway is the single public entry point of Stella Ops and therefore the highest- blast-radius plugin surface in the platform.

The loader (RouterTransportPluginLoader) now requires:

1. A signed manifest at plugins/router/transports/transports.signed.json that pins, per file name, the SHA-256 of the on-disk DLL and the leaf signing thumbprint. The manifest schema is stellaops.router.transports/v1 and is documented in RouterTransportManifest.
2. A valid X.509 chain from the manifest’s leaf signing certificate to the Stella-internal CA bundle distributed via the offline kit. The chain-build path reuses IPluginSignatureValidator / X509PinnedSignatureValidator from PSV-02 / PSV-03 — there is one validator implementation across the entire platform.
3. A directory whose *.dll files are an exact match for the manifest’s transports[] list. Any extra DLL fails the entire load closed (no pinned DLLs are loaded either) — this defends against drop-in attacks while a signature is being rotated.
4. Per-DLL SHA-256 match against the pinned digest. A mismatch fails the entire load closed with a ListedDllDigestMismatch rejection.

sequenceDiagram
    participant Op as Operator
    participant FS as plugins/router/transports/
    participant Loader as RouterTransportPluginLoader
    participant Trust as IPluginTrustRoot
    participant Val as X509PinnedSignatureValidator

    Op->>FS: drop *.dll + transports.signed.json
    Loader->>FS: open transports.signed.json
    Loader->>Loader: parse + validate schema shape
    Loader->>Val: ValidateAsync(canonicalBytes, signedJson, TrustRoot)
    Val->>Trust: GetAnchors()
    Val-->>Loader: PluginSignatureValidationResult
    Loader->>Loader: enforce AllowedSignerThumbprints policy
    Loader->>FS: enumerate *.dll
    Loader->>Loader: extra DLL? → fail-closed
    loop for each pinned entry
        Loader->>FS: read DLL bytes
        Loader->>Loader: SHA-256 vs manifest pin
    end
    Loader->>Loader: Assembly.LoadFrom each accepted DLL
    Loader-->>Op: RouterTransportTrustReport

Gateway.WebService/Program.cs reads the policy from configuration:

Gateway:
  TransportPlugins:
    Directory: "plugins/router/transports/"
    TrustRootDirectory: "trust-roots/plugins/"
    AllowedSignerThumbprints: ["…"]
    RequireSignedManifest: true   # default; only false when ASPNETCORE_ENVIRONMENT=Development

RequireSignedManifest=false is honoured only when IHostEnvironment.IsDevelopment(); in any other environment the override is rejected with a fatal log line and the value is forced back to true.

Threat-model footnote — AppDomain-resident transports. The transports loaded by the build system into the host AppDomain (TCP, TLS, Messaging, in-memory) are not verified at runtime by this pipeline. They ride the gateway image’s own signature: Authenticode on Windows, signed RPM/DEB on Linux, signed container image on container deploys. The signed-manifest pipeline only governs disk-resident drop-in transport plugins.

Gateway startup treats a missing or empty plugins/router/transports/ directory as “no operator-managed drop-ins configured” and continues with AppDomain-resident transports only. If the directory contains transports.signed.json or any DLL matching the configured Router transport glob, the signed-manifest pipeline is mandatory and still fails closed on a missing, malformed, unsigned, or mismatched manifest. Shared web-service publish targets therefore do not copy Stella’s built-in Router transport DLLs into plugins/router/transports/ by default; signed drop-in packaging requires an explicit MSBuild opt-in.

Trust-root sharing with the platform plugin pipeline. The IPluginTrustRoot registered in the gateway’s DI container is the same PEM-directory bundle distributed to the platform plugin host (PSV-05). Trust- root rotation is therefore one offline-kit operation that updates both pipelines.

Stella-internal signers only. The pre-prod plan assumes AllowedSignerThumbprints only ever contains Stella-internal CA-issued leaf thumbprints. Third-party transport plugins are out of scope for v1; the schema can be extended (per-tenant allowlists, expiry dates) when that business case lands. See the sprint’s Decisions & Risks for the open product question.

Release signing path. devops/docker/sign-router-transports keeps its local-key-generating development mode, but release engineering uses its external-key mode: --signer-pfx, --pfx-password-file, and --trust-root-pem are all mandatory and --keys-dir is forbidden. The tool writes the release trust root, signs the canonical manifest, then immediately runs RouterTransportTrustPipeline over the produced directory; a chain, signature, allowlist-shape, extra-DLL, or digest failure aborts preparation. Private release material remains outside the source repository.

Operator workflow. See docs/ops/runbooks/add-router-transport.md for the build-and-deploy steps. Operators can pre-validate a directory drop without restarting the gateway via stella router transports verify (documented in docs/modules/cli/operations/router-transports.md).

Transport Plugin Interface

public interface ITransportServer
{
    Task StartAsync(CancellationToken ct);
    Task StopAsync(CancellationToken ct);
    event Func<ConnectionState, HelloPayload, Task> OnHelloReceived;
    event Func<ConnectionState, HeartbeatPayload, Task> OnHeartbeatReceived;
    event Func<string, Task> OnConnectionClosed;
}

public interface ITransportClient
{
    Task ConnectAsync(CancellationToken ct);
    Task DisconnectAsync(CancellationToken ct);
    Task SendFrameAsync(Frame frame, CancellationToken ct);
}

TLS Validation Contract

The TLS transport (StellaOps.Router.Transport.Tls) enforces a strict validation contract on every TLS handshake — server-side (mTLS clients) and client-side (microservices validating the gateway). Audit finding C8 in microservice-audit-pass2-2026-04-29.md recorded the previous permissive behaviour and led to this rewrite (see also SPRINT_20260501_013).

Validation rules, in evaluation order:

1. Required-but-missing. When the role requires a peer certificate and none was presented, reject (certificate_required_but_missing).
2. RemoteCertificateNotAvailable. Reject (remote_certificate_not_available).
3. RemoteCertificateNameMismatch is always fatal. Even with AllowSelfSigned=true and a matching pin, a hostname mismatch is rejected unconditionally (name_mismatch). This is the central C8 fix; the previous validator accepted name mismatch when it was the only error.
4. RemoteCertificateChainErrors:
   • When AllowSelfSigned=false: reject (chain_error_and_self_signed_disallowed).
   • When AllowSelfSigned=true:
     • Accept only if the chain status is exactly UntrustedRoot or PartialChain (no other status flags), otherwise reject (chain_status_not_permitted).
     • The certificate must match at least one entry from the configured pin set (thumbprint OR subject OR SAN; pin matching uses StringComparer.Ordinal on a normalised SHA-256 hex thumbprint). Otherwise reject (pin_mismatch).
     • If the pin set is empty at runtime (should already have failed Options.Validate() at startup), reject (pin_set_empty).
5. No errors: accept.

Pinning options live on TlsTransportOptions.CertificatePinning:

Startup validation. Constructing TlsTransportServer or TlsTransportClient with AllowSelfSigned=true and an empty pin set throws InvalidOperationException referencing audit C8. This is intentionally breaking: any compose file that relied on the old permissive validator must add a pin set or set AllowSelfSigned=false. See the worked example for compose syntax.

Telemetry. Each rejection increments router_tls_validate_rejected_total{reason, role} (meter StellaOps.Router.Transport.Tls) and emits a structured-log warning with the reason field. role is either client_certificate or server_certificate.

Frame Types

public enum FrameType
{
    Hello,
    Heartbeat,
    Request,
    Response,
    RequestStreamData,
    ResponseStreamData,
    Cancel,
    ResyncRequest,
    EndpointsUpdate,
    Goodbye
}

The enum uses the default int backing type with implicit zero-based ordinals (no explicit : byte or numeric assignments). Goodbye is sent by a microservice immediately before shutdown to request prompt deregistration without waiting for lease expiry.

Gateway Pipeline

HTTP Middleware Stack

Request ─►│ ForwardedHeaders        │
          │ RequestLogging          │
          │ ErrorHandling           │
          │ Authentication          │
          │ EndpointResolution      │  ◄── (Method, Path) → EndpointDescriptor
          │ Authorization           │  ◄── RequiringClaims check
          │ RoutingDecision         │  ◄── Select connection/instance
          │ TransportDispatch       │  ◄── Send to microservice
          ▼

Identity Header Policy and Tenant Selection

• Gateway strips client-supplied reserved identity headers (X-StellaOps-*, legacy aliases, raw claim headers, and auth headers) before proxying.
• Effective tenant is claim-derived from validated principal claims (stellaops:tenant, then bounded legacy tid fallback).
• Effective scopes are the case-insensitive union of every validated individual scp claim and every token in the validated space-delimited scope claims. Empty values and duplicates are removed before the existing coarse-scope expansions run, and the signed identity envelope emits the result in deterministic ordinal order.
• Gateway signs an allow-listed set of downstream ABAC claims into the internal identity envelope after token validation. This includes the developer self-service release-control claims for owned service IDs, repository IDs, image namespaces, allowed environment IDs, maximum environment type, and direct-update permission. Microservice bridges restore only those signed claims into HttpContext.User; client-supplied claim headers are still stripped.
• Per-request tenant override is disabled by default and only works when explicitly enabled with Gateway:Auth:EnableTenantOverride=true and the requested tenant exists in stellaops:allowed_tenants.
• Authorization/DPoP passthrough is fail-closed:
• the matched route must be configured with PreserveAuthHeaders=true, and
• route prefix must also be in the approved passthrough allow-list configured under Gateway:Auth:ApprovedAuthPassthroughPrefixes.
• local frontdoor configs approve /connect, /console, /authority, /doctor, /api, /policy/shadow, and /policy/simulations so live policy compatibility endpoints can preserve DPoP/JWT passthrough without broadening unrelated routes.
• Gateway DPoP replay protection is durable in non-testing runtime: StellaOps.Gateway.WebService resolves IDpopReplayCache through messaging idempotency (valkey in compose, postgres when configured) and only permits InMemoryDpopReplayCache under the explicit Testing environment. When Gateway:Auth:DpopEnabled=true and no durable messaging idempotency backend is configured, the host fails fast instead of silently falling back to process-local replay state.
• Tenant override attempts are logged with deterministic fields including route, actor, requested tenant, and resolved tenant.

Downstream Service Trust Mode (GatewayAuthorizationTrustMode)

The rules above are gateway-side. How a microservice decides to trust the identity it receives is a separate knob: StellaRouterBridgeOptions.AuthorizationTrustMode (StellaOps.Microservice.AspNetCore/StellaRouterBridgeOptions.cs:95-96, mirrored on StellaRouterOptions.cs:79-80). It has three modes (StellaRouterBridgeOptions.cs:208-226):

Security posture — read this before leaving the default. Under the default Hybrid mode, a malformed or absent envelope does not produce a 401; it silently degrades to header trust. The reverse-proxy envelope middleware reinforces this: on a bad envelope it never throws and continues unauthenticated (IdentityEnvelopeMiddlewareExtensions.cs:158-162), leaving downstream authorization as the gate. This is acceptable only because those frames arrive over the internal binary transport, whose integrity is a separate mechanism — the frame-layer envelope HMAC (see Frame-layer Envelope HMAC). Note the compounding failure mode: that HMAC runs in verifier-disabled bootstrap mode until FrameEnvelopeOptions is bound on a host (see the Migration note in that section). When the identity envelope is absent and the frame verifier is unbound, any participant on the bus can assert an arbitrary actor, tenant, scope, or role set purely via headers — including the stellaops:tenant value that tenancy is derived from. Bind FrameEnvelopeOptions and prefer GatewayEnforced for services handling tenant-scoped or privileged data.

Connection State

Per-connection state maintained by Gateway:

public sealed class ConnectionState
{
    public required string ConnectionId { get; init; }
    public required InstanceDescriptor Instance { get; init; }
    public InstanceHealthStatus Status { get; set; } = InstanceHealthStatus.Unknown;
    public DateTime ConnectedAtUtc { get; init; } = DateTime.UtcNow;
    public DateTime LastHeartbeatUtc { get; set; } = DateTime.UtcNow;
    public double AveragePingMs { get; set; }
    public Dictionary<(string Method, string Path), EndpointDescriptor> Endpoints { get; } = new();
    public required TransportType TransportType { get; init; }
    public IReadOnlyDictionary<string, SchemaDefinition> Schemas { get; init; } = new Dictionary<string, SchemaDefinition>();
    public ServiceOpenApiInfo? OpenApiInfo { get; init; }
}

LastHeartbeatUtc is a non-nullable DateTime (initialised to the connection time); TransportType is required.

Payload Handling

The Gateway treats bodies as opaque byte sequences:

• No deserialization or schema interpretation
• Headers and bytes forwarded as-is
• Schema validation is microservice responsibility

Payload Limits

Configurable limits protect against resource exhaustion:

Exceeded limits result in:

• Early rejection (HTTP 413) if Content-Length known
• Mid-stream abort with CANCEL frame
• Appropriate error response (413 or 503)

Microservice SDK

Configuration

services.AddStellaMicroservice(options =>
{
    options.ServiceName = "billing";
    options.Version = "1.0.0";
    options.Region = "us-east-1";
    options.InstanceId = Guid.NewGuid().ToString();
    options.ServiceDescription = "Invoice processing service";
});

Endpoint Declaration

Attributes:

[StellaEndpoint("POST", "/invoices")]
public sealed class CreateInvoiceEndpoint : IStellaEndpoint<CreateInvoiceRequest, CreateInvoiceResponse>

Handler Interfaces

Typed handler (JSON serialization):

public interface IStellaEndpoint<TRequest, TResponse>
{
    Task<TResponse> HandleAsync(TRequest request, CancellationToken ct);
}

public interface IStellaEndpoint<TResponse>
{
    Task<TResponse> HandleAsync(CancellationToken ct);
}

Raw handler (streaming):

public interface IRawStellaEndpoint
{
    Task<RawResponse> HandleAsync(RawRequestContext ctx, CancellationToken ct);
}

Endpoint Discovery

Two mechanisms:

1. Source Generator (preferred): Compile-time discovery via Roslyn
2. Reflection (fallback): Runtime assembly scanning

Connection Behavior

On connection:

1. Send HELLO with instance identity.
2. Start heartbeat timer.
3. For messaging transport, replay endpoint/schema/OpenAPI metadata only when the router explicitly asks for it.
4. Listen for REQUEST frames.

HELLO payload:

public sealed class HelloPayload
{
    public required InstanceDescriptor Instance { get; init; }
    public required IReadOnlyList<EndpointDescriptor> Endpoints { get; init; }
    public IReadOnlyDictionary<string, SchemaDefinition> Schemas { get; init; } = new Dictionary<string, SchemaDefinition>();
    public ServiceOpenApiInfo? OpenApiInfo { get; init; }
}

For messaging transport the steady-state contract is intentionally slimmer than the generic shape above:

• startup HELLO carries identity and may leave Endpoints empty
• the gateway sends ResyncRequest on service startup, administrative replay, gateway-state miss, or a cooldown-gated heartbeat retry while a known connection still has no endpoint metadata
• the microservice answers with EndpointsUpdate containing endpoints, schemas, and OpenAPI metadata

Authorization

Claims-based Model

Authorization uses RequiringClaims, not roles:

public sealed record ClaimRequirement
{
    public required string Type { get; init; }

    // Single-value AND-style requirement. Ignored when AllowedValues is set.
    public string? Value { get; init; }

    // Any-of requirement: satisfied if the principal presents ANY one of these
    // values for Type (e.g. orch:read OR script:read). Takes precedence over Value.
    public IReadOnlyList<string>? AllowedValues { get; init; }
}

Precedence

1. Microservice provides defaults in registration metadata
2. Authority can override centrally
3. Gateway enforces final effective claims

Enforcement

Gateway AuthorizationMiddleware:

• Validates user principal has all required claims
• Empty claims list = authenticated access only
• Missing claim = 403 Forbidden

Gateway-owned HTTP endpoints

Beyond proxying to microservices, the gateway maps a small set of its own endpoints. These are registered as system paths, so they bypass RouteDispatchMiddleware and the microservice pipeline.

The router-routing and operator-verify scopes are declared in the canonical catalog StellaOps.Auth.Abstractions.StellaOpsScopes as router:routing:read, router:routing:write, operator.verify.read, and operator.verify.admin. MapRouterAdministrationEndpoints protects the complete /api/v1/gateway/administration group with policy router.routing.write; the policy requires the canonical router:routing:write scope. The resync request uses an omitted or null connectionId for intentional all-fleet replay and a non-blank exact value for targeted replay. Explicitly blank selectors return 400, while stale non-blank selectors return 404; neither is broadened to an all-fleet request.

Cancellation

CANCEL Frame

public sealed record CancelPayload
{
    public string? Reason { get; init; }
}

// Standard reason constants (StellaOps.Router.Common.Models.CancelReasons):
// "ClientDisconnected", "Timeout", "PayloadLimitExceeded", "Shutdown", "ConnectionClosed"

Gateway sends CANCEL when:

• HTTP client disconnects (HttpContext.RequestAborted)
• Request timeout elapses
• Payload limit exceeded
• Gateway shutdown

At the HTTP boundary, an aborted request or Kestrel’s known client-reset / client-disconnected IOException is recorded at debug level with status 499 when the response has not started. The gateway does not manufacture an RFC-7807 500 body for a client that is already gone. Other I/O failures remain unexpected server errors and retain the sealed 500 ProblemDetails path.

Microservice handles CANCEL:

• Maps correlation ID to CancellationTokenSource
• Calls Cancel() on the source
• Handler receives cancellation via CancellationToken

For the Messaging transport, authenticated capable clients consume CANCEL on a per-connection control queue instead of waiting behind the per-service request batch. The gateway signs a target binding for each capable live connection; mixed or legacy-only fleets retain one compatibility copy on the request queue, while all-capable fleets omit that redundant copy. Clients without a frame envelope verifier do not advertise or consume the dedicated lane. Exact- correlation tombstones make cancel-before-request and duplicate delivery bounded and idempotent. See Messaging Transport over Valkey for queue topology, rollout compatibility, and residual stream cleanup risk.

Streaming

Buffered vs Streaming

Frame Flow (Streaming)

Gateway                              Microservice
   │                                      │
   │  REQUEST (headers only)              │
   │ ────────────────────────────────────►│
   │                                      │
   │  REQUEST_STREAM_DATA (chunk 1)       │
   │ ────────────────────────────────────►│
   │                                      │
   │  REQUEST_STREAM_DATA (chunk n)       │
   │ ────────────────────────────────────►│
   │                                      │
   │  REQUEST_STREAM_DATA (final=true)    │
   │ ────────────────────────────────────►│
   │                                      │
   │                   RESPONSE           │
   │◄────────────────────────────────────│
   │                                      │
   │         RESPONSE_STREAM_DATA         │
   │◄────────────────────────────────────│

Heartbeat & Health

Heartbeat Frame

Sent at regular intervals over the same connection as requests:

public sealed class HeartbeatPayload
{
    public InstanceDescriptor? Instance { get; init; }
    public string InstanceId { get; init; }
    public required InstanceHealthStatus Status { get; init; }
    public int InFlightRequestCount { get; init; }
    public double ErrorRate { get; init; }
    public DateTime TimestampUtc { get; init; }
}

Health Tracking

Gateway tracks:

• LastHeartbeatUtc per connection
• Derives status from heartbeat recency
• Marks stale instances as Unhealthy
• Uses health in routing decisions
• Messaging heartbeats include instance identity so the gateway can rebuild minimal state after a gateway restart or local routing-state loss without waiting for a full reconnect.
• Messaging transports stay push-first even when backed by notifiable queues; the missed-notification safety-net timeout is derived from the configured heartbeat interval and clamped to a short bounded window instead of falling back to a fixed long poll.
• Gateway degraded and stale transitions are normalized against the messaging heartbeat contract. A gateway may not mark an instance Degraded earlier than 2x the heartbeat interval or Unhealthy earlier than 3x the heartbeat interval, even when looser defaults were configured.
• /health/ready is stricter than “process started”: it remains 503 until the configured required first-party microservices have live healthy or degraded registrations in router state. Local scratch compose uses this to hold the frontdoor unhealthy until the core Stella API surface has replayed HELLO after a rebuild.
• The required-service list must use canonical router serviceName values, not loose product-family aliases. Gateway readiness normalizes host-style suffixes such as -gateway, -web, .stella-ops.local, and ports, but it does not treat sibling services as interchangeable.
• When a request already matched a configured Microservice route but the target service has not registered yet, the gateway returns 503 Service Unavailable, not 404 Not Found. 404 remains reserved for genuinely unknown paths or missing endpoints on an otherwise registered service.
• Router-enabled ASP.NET microservices preload the default first-party Router transport assembly for each configured transport before scanning the default AppDomain. The service image still must carry the referenced transport assembly in its deps graph; this preload only removes the fragile “first type use” dependency that made otherwise-published messaging transports invisible at startup.
• Messaging resync is explicit instead of periodic: startup, administrative replay, and gateway-state misses trigger ResyncRequest. Normal heartbeats stay small; while a known connection’s endpoint catalog is still empty, they also trigger a cooldown-gated replay request until EndpointsUpdate clears the pending state. Healthy catalogs do not replay on heartbeat.
• The Valkey transport keeps its timeout fallback plus proactive randomized re-subscribe so silent Pub/Sub failures still recover. That fallback still produces some XREADGROUP/XAUTOCLAIM traffic, but it is resilience traffic rather than endpoint-catalog churn.

Configuration

Gateway configuration (GatewayOptions, section Gateway)

The StellaOps.Gateway.WebService host binds everything under the Gateway section into GatewayOptions. The shape below reflects the actual option classes (GatewayNodeOptions, GatewayTransportOptions, GatewayRoutingOptions, GatewayAuthOptions, GatewayOpenApiOptions, GatewayHealthOptions, and the Routes list). Durations are strings parsed by GatewayValueParser (e.g. "30s", "5m"); sizes accept "100MB".

Gateway:
  Node:
    Region: "us-east-1"
    NodeId: "gw-east-01"        # auto-generated gw-<region>-<8hex> when blank
    Environment: "production"
    NeighborRegions: ["us-west-2"]

  Routing:
    DefaultTimeout: "30s"
    GlobalTimeoutCap: "120s"     # cap applied after endpoint + route timeout resolution
    MaxRequestBodySize: "100MB"
    StreamingEnabled: true
    PreferLocalRegion: true
    AllowDegradedInstances: true
    StrictVersionMatching: true

  Transports:
    Tcp:   { Enabled: false, BindAddress: "0.0.0.0", Port: 9100 }
    Tls:   { Enabled: false, BindAddress: "0.0.0.0", Port: 9443 }
    Messaging:
      Enabled: true
      transport: "valkey"        # or "postgres"
      RequestQueueTemplate: "router:requests:{service}"
      ResponseQueueName: "router:responses"
      ConsumerGroup: "router-gateway"
      HeartbeatInterval: "10s"

  Auth:
    DpopEnabled: true
    AllowAnonymous: true
    EnableTenantOverride: false
    EmitIdentityEnvelope: true
    ApprovedAuthPassthroughPrefixes: ["/connect", "/console", "/authority", "/doctor", "/api"]

  OpenApi:
    Enabled: true
    Title: "StellaOps Gateway API"
    CacheTtlSeconds: 300

  Health:
    StaleThreshold: "30s"
    DegradedThreshold: "15s"
    CheckInterval: "5s"
    RequiredMicroservices: []

  Routes:
    - { Type: Microservice, Path: "^/billing(?=/|$)(.*)", IsRegex: true, TranslatesTo: "http://billing.stella-ops.local$1" }

Note: there is no top-level PayloadLimits / Services block. Payload limits are derived from Gateway:Routing:MaxRequestBodySize, and per-endpoint claims and timeouts are advertised by each microservice via HELLO/EndpointsUpdate, not declared in gateway config. OpenApi:CacheTtlSeconds defaults to 300.

Hot Reload

• Routing state (registered services/endpoints) is updated dynamically as microservices send HELLO / EndpointsUpdate and heartbeats; no gateway restart is required to add or remove a service instance
• Changes to the Gateway options block itself are bound at startup (ValidateOnStart); they are not hot-reloaded

Error Mapping

See Also

• schema-validation.md - JSON Schema validation
• openapi-aggregation.md - OpenAPI document generation
• migration-guide.md - WebService to Microservice migration
• rate-limiting.md - Centralized Router rate limiting