stabilizaiton work - projects rework for maintenanceability and ui livening

docs/technical/architecture/security-boundaries.md

@@ -31,6 +31,75 @@ Authoritative references:
 
 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:
+
+```csharp
+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).