git.stella-ops.org/docs/technical/architecture/security-boundaries.md

Security boundaries (platform-level)

This document describes the baseline security boundaries expected across StellaOps modules. Module dossiers may impose stricter requirements.

Authentication and authorization

All externally reachable services are expected to enforce:

1. Token validation (short-lived, tenant-scoped access tokens).
2. Sender constraints where configured (DPoP / mTLS).
3. Scope-based authorization (least privilege).
4. Tenant isolation: requests and data access are filtered by tenant context.

Hard gates (typical examples)

Exact gates are module-specific, but common patterns include:

• Authority: nonce-based sender constraints (DPoP), strict token lifetimes, tenant-scoped issuance, and rate limiting.
• Signing/attestation services: narrow scopes, service identity requirements (often mTLS), and verification of the artifact being signed/attested (for example digest checks) before producing evidence.

Authoritative references:

• docs/security/scopes-and-roles.md
• docs/modules/authority/architecture.md
• docs/modules/signer/architecture.md
• docs/modules/attestor/architecture.md

Network segmentation (typical deployment)

• Front door / ingress: TLS termination, rate limiting, and WAF controls.
• Gateway layer: authenticated routing and tenant resolution; exposes only required service surfaces.
• Private service network: internal service-to-service traffic (least privilege, explicit allowlists).
• Stateful infrastructure: PostgreSQL, Valkey, object storage, message brokers (not directly internet-exposed).

Deployment bundles under deploy/ are the authoritative source of concrete network layouts.

Cross-Origin Resource Sharing (CORS)

All Stella Ops web services use a shared CORS extension provided by StellaOps.AspNet.Extensions (StellaOpsCorsExtensions), with settings resolved by StellaOps.Settings (StellaOpsCorsSettings).

Development mode

When the host environment is Development, CORS is automatically enabled with specific origins, AllowAnyHeader, AllowAnyMethod, and AllowCredentials.

Default dev origins (used when no explicit origin is configured):

• https://stella-ops.local
• https://stella-ops.local:10000
• https://localhost:10000

Override the defaults by setting STELLAOPS_WEBSERVICES_CORS_ORIGIN.

Non-development (staging / production)

CORS is disabled by default. To enable, set the following environment variables (or their YAML/appsettings equivalents):

Environment variable	Config key	Dev default	Prod default	Description
STELLAOPS_WEBSERVICES_CORS	StellaOps:WebServices:Cors:Enabled	true	false	Set to true or 1 to enable CORS
STELLAOPS_WEBSERVICES_CORS_ORIGIN	StellaOps:WebServices:Cors:Origin	https://stella-ops.local, https://stella-ops.local:10000, https://localhost:10000	(must be set)	Comma-separated list of allowed origins

Legacy fallback

The following legacy env vars and config keys are still supported as fallbacks (resolved after the primary keys above):

Legacy env var	Legacy config key
STELLAOPS_CORS_ENABLED	StellaOps:Cors:Enabled
STELLAOPS_CORS_ALLOWED_ORIGIN	StellaOps:Cors:AllowedOrigin

Resolution order

Settings are resolved with a priority cascade (first non-empty value wins):

1. Primary env var (STELLAOPS_WEBSERVICES_CORS / STELLAOPS_WEBSERVICES_CORS_ORIGIN)
2. Primary config key (StellaOps:WebServices:Cors:Enabled / StellaOps:WebServices:Cors:Origin)
3. Legacy env var (STELLAOPS_CORS_ENABLED / STELLAOPS_CORS_ALLOWED_ORIGIN)
4. Legacy config key (StellaOps:Cors:Enabled / StellaOps:Cors:AllowedOrigin)
5. Default: true in Development, false otherwise

When CORS is enabled, the policy always uses:

• WithOrigins(...) (only the configured/default origins — never AllowAnyOrigin)
• AllowAnyHeader
• AllowAnyMethod
• AllowCredentials

Integration in services

Every web service's Program.cs includes:

using StellaOps.Auth.ServerIntegration;

// In service registration (before builder.Build())
builder.Services.AddStellaOpsCors(builder.Environment, builder.Configuration);

// In middleware pipeline (before UseAuthentication)
app.UseStellaOpsCors();

Source

The implementation lives in:

• src/__Libraries/StellaOps.Settings/StellaOpsCorsSettings.cs (POCO + resolution logic)
• src/__Libraries/StellaOps.AspNet.Extensions/StellaOpsCorsExtensions.cs (ASP.NET DI + middleware)
• Transitive reference via StellaOps.Auth.ServerIntegration (so existing service references continue to work)

Data protection

• TLS for in-transit protection (including internal traffic where required by the profile).
• Secrets must not be embedded in documentation examples; use a secrets provider (file, Docker secrets, Kubernetes secrets, vault).
• Evidence artifacts should be written to content-addressed or immutable stores where replay/audit requires it.

Auditability

The platform is designed for audits:

• Deterministic outputs for the same inputs.
• Evidence artifacts (SBOM slices, advisories/VEX observations, explain traces) linkable to digests.
• Structured logs and correlation IDs for tracing request paths across services.