Skip to main content

Sovereign Deployment

In sovereign mode the control plane and the data plane both run inside the operator's own perimeter (ADR-037). The hosted service was shut down on 2026-05-23; STOA is deployed on site. This page is a generic reference pattern: names are placeholders, no real infrastructure is described, and every statement points to a published ADR or a file of the stoa repository. Sizing, ports and DNS live in Deployment Prerequisites.

Data plane status

ADR-073 (2026-10-22) decides that the data plane uses upstream Envoy, configured only over xDS served on site by STOA Link, with STOA logic in external services called by Envoy. The Link xDS server is decided but not yet implemented (ADR-073 §7); the diagrams below show the decided target. The current data plane, STOA Gateway (Rust), is in maintenance (ADR-073 §9).

1. Network topology​

FlowDirection and protocolSource
Consumers, agents and operators → edgeHTTPS, initiated by the client; the only inbound entry to the sitePrerequisites §2
Edge → Envoy, Console, Portal, API, KeycloakTLS terminated at the edge; client-certificate data forwarded as headers from a trusted proxy onlyADR-027, ADR-039
Envoy → authorization and processing servicesgRPC ext_authz and ext_proc; services co-located with EnvoyADR-073 §4, Mitigations
Envoy ↔ STOA LinkEnvoy opens the xDS stream to the local Link; Link serves versioned snapshots generated from UAC contractsADR-073 §2
STOA Link → Control Plane APIOutbound SSE from Link plus HTTPS callback; the control plane never opens a connection towards the data planeADR-059, ADR-073 §2
Enforcement point → Control Plane APIPeriodic fetch of the signed policy artifact, initiated by the enforcement pointADR-070 A7
Site → InternetNone required: sovereign mode never requires outbound connectivity; images are mirrored to an on-site registryADR-037, Prerequisites §5, ADR-073 Mitigations

Every Envoy instance keeps its admin interface on loopback and is never configured by hand or through an administration API (ADR-073 §2 and Mitigations). Kafka, when deployed, stays internal to the site and only carries side-effect events (ADR-059).

2. Access control from an external network​

StepControlSource
IdentityADR-026 defines a target federation model with a dedicated realm per tenant, brokering to the operator's IdP (OIDC, SAML or LDAP), no local user records, and audience/realm checks. Current tenant provisioning instead creates groups and an admin user in the configured realm (see Identity below); it does not establish this realm-per-tenant model.ADR-026
AI agentsMCP clients use OAuth 2.1 with PKCE; the gateway serves the discovery metadata and proxies dynamic client registration to Keycloak.ADR-044
TransportTLS at the edge; optional mTLS with certificate-bound tokens (cnf.x5t#S256), checked by Envoy's JWT filter or by the authorization service. Sender-constrained tokens (DPoP, mTLS) are designed to support the FAPI 2.0 profile for clients that require it; no conformance certification is claimed.ADR-039, ADR-073 §5, ADR-056
Token validationEnvoy jwt_authn validates signature and claims against a JWKS delivered over xDS, so validation needs no call outside the site; coarse rbac and local_ratelimit follow.ADR-073 §10
AuthorizationThe authorization service checks tenant, active subscription, API key, OPA policy and consumer quotas. On failure Envoy denies with 503, a neutral body identical to the 403, and no automatic retry of non-idempotent requests.ADR-073 §4, §10
Tool permissionsDeny by default. A tool is allowed only if a Control-Plane-signed artifact (Ed25519 JWS, scoped to one tenant, time-bounded) lists it; revocation overrides the cache; tools flagged requires_human_approval need an approval token.ADR-070 §1, Annex
OperatorsConsole, Portal and CLI go through Keycloak OIDC. Roles cpi-admin, tenant-admin, devops and viewer map to scopes stoa:admin, stoa:write, stoa:read. Production configuration changes go through a Git pull request, not a UI write.ADR-054, ADR-040

In the prod and staging profiles the Rust gateway refuses to start if its policy engine cannot load (state.rs: resolve_policy_engine), and readiness fails when no verified policy artifact is available (ADR-070 §4).

3. Tenant and component isolation​

LayerMechanismSource
IdentityADR-026 defines a realm-per-tenant target. Delivered provisioning creates tenant groups in the configured Keycloak realm, not separate realms; it therefore does not establish separate realm signing keys, clients or sessions per tenant.ADR-026; tenant creation; provisioning; configured realm; setup_tenant_group
AuthorizationThe Control Plane API rejects access to another tenant unless the caller is cpi-admin (require_tenant_access); the gateway applies the same rule with enforce_tenant_isolation, on by default.Control Plane RBAC; require_tenant_access; gateway default; gateway tenant check
ContractOne complete, self-contained UAC file per tenant, no inheritance; environment overlays live in Git.ADR-022, ADR-040
PolicyEach signed policy artifact carries a single tenant_id; a missing artifact for one tenant denies that tenant only, never the others.ADR-070 §4, Annex A2
NetworkFor the reference pattern, the operator must isolate tenant workloads with namespaces and NetworkPolicy objects. The chart includes conditional bootstrap and first-admin egress policies, but these do not provide general tenant workload isolation. Examples: Security Hardening.Helm templates; bootstrap policy; first-admin policy; ADR-026 Security Considerations
ComponentsControl plane and data plane are separate processes with a single deployment path; Envoy loads no extension and STOA logic runs in separate services; the policy signing key is mounted read-only and readable only by the Control Plane API; gateway containers run as non-root with a read-only filesystem and all capabilities dropped.ADR-073 §1, §4; ADR-070 A5; gateway security context
Supply chainImages are signed with Cosign, with SLSA provenance and an SPDX SBOM attached at publication; verify them before mirroring to the on-site registry.image publication workflow