Merge pull request #67 from davidortinau/feature/41-security-headers

feat: add HTTPS enforcement and security headers (#41)

Author: davidortinau

.squad/agents/kaylee/history.md

@@ -39,3 +39,21 @@
 
 **Critical Path:** CoreSync SQLite→PostgreSQL migration (#55, XL).
 
+### 2026-03-14 — Phase 2 (Secrets & Security) Completion
+
+**Status:** COMPLETED  
+**Issues:** #39 (user-secrets setup), #41 (security headers)
+
+**Kaylee Completed #41 — Security Headers & HTTPS:**
+- Added shared `SecurityHeadersExtensions` in `src/Shared/SecurityHeadersExtensions.cs` (linked to web projects via `<Compile Include>`)
+- Security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy, Permissions-Policy (camera/mic/geo)
+- HTTPS redirect environment-aware (skipped in dev, Aspire proxy terminates TLS)
+- API explicit HSTS: 365-day max-age, includeSubDomains, preload
+- CORS: AllowWebApp policy (config-driven) + AllowDevClients (dev-only localhost)
+- AllowedHosts restrictions in Production appsettings
+
+**Key Decision:** Linked source file instead of WebServiceDefaults to avoid ambiguous call errors with MAUI defaults.
+
+**Wash Completed #39 (user-secrets setup):**
+- Kaylee coordination: CORS setup confirmed not required for MAUI clients (use service discovery)
+- Phase 2 ready for Phase 1 (Entra ID auth) — Captain has provisioned 3 app registrations

.squad/agents/wash/history.md

@@ -37,3 +37,20 @@
 
 **Key Dependencies:** Zoe coordinates Phase 1-3 decisions; Kaylee implements CI/deploy automation; Captain provides Azure portal access.
 
+### 2026-03-14 — Phase 2 (Secrets) Completion
+
+**Status:** COMPLETED  
+**Issues:** #39 (user-secrets setup), #41 (security headers)
+
+**Wash Completed #39:**
+- Initialized user-secrets for Api, WebApp
+- Created secrets.template.json with full inventory
+- Updated README with three secrets management paths
+- Documented AppHost → service flow via Aspire Parameters and env var normalization
+
+**Kaylee Completed #41:**
+- Added SecurityHeadersExtensions to shared lib (linked to all web projects)
+- Implemented HSTS, CORS, AllowedHosts across API/WebApp/Marketing
+- Environment-aware HTTPS redirect
+
+**Phase 2 Closed:** Ready to begin Phase 1 (Entra ID) now that Captain has provisioned app registrations.

.squad/decisions.md

@@ -68,6 +68,72 @@ Comprehensive architecture plan for transitioning SentenceStudio from local-dev-
 
 **Estimated Monthly Cost (Production):** ~$107-252
 
+### 3. User-Secrets Workflow for Local Development (2026-03-14)
+
+**Status:** IMPLEMENTED  
+**Date:** 2026-03-14  
+**Author:** Wash (Backend Dev)  
+**Issue:** #39  
+
+Established .NET user-secrets pattern for secure local development across all server-side projects.
+
+**Key Decisions:**
+- AppHost uses Aspire Parameters (`builder.AddParameter("openaikey", secret: true)`) resolving from AppHost user-secrets under `Parameters:openaikey`
+- Parameters passed to child projects via `.WithEnvironment("AI__OpenAI__ApiKey", openaikey)`
+- Aspire normalizes `__` to `:` in configuration across services
+- Three paths documented in README:
+  - **Option A:** Aspire (recommended) — set secrets in AppHost, flow to all services
+  - **Option B:** Standalone projects — per-project `dotnet user-secrets`
+  - **Option C:** MAUI mobile/desktop — gitignored `appsettings.json` in AppLib
+
+**Projects with UserSecretsId:**
+| Project | UserSecretsId |
+|---------|---------------|
+| AppHost | d8521a4e-969b-4696-9990-45dea324bda8 |
+| Api | 9ae3953f-a490-41b3-a2b8-a8e2555b4615 |
+| WebApp | 33f95f89-d495-4311-b6cb-53a47b5c34e6 |
+| Workers | dotnet-SentenceStudio.Workers-8ded0183-d135-40b2-b2d4-b49b096922b8 |
+
+**Secrets Inventory:**
+| Secret | AppHost Parameter | Api Key | WebApp Key |
+|--------|-------------------|---------|------------|
+| OpenAI | Parameters:openaikey | AI:OpenAI:ApiKey | Settings:OpenAIKey |
+| ElevenLabs | Parameters:elevenlabskey | ElevenLabsKey | Settings:ElevenLabsKey |
+| Syncfusion | Parameters:syncfusionkey | N/A | N/A |
+
+**No Data Impact:** No database changes, no secret migrations, AppHost user-secrets remain intact.
+
+---
+
+### 4. Security Headers and HTTPS Enforcement (2026-03-14)
+
+**Status:** IMPLEMENTED  
+**Date:** 2026-03-14  
+**Author:** Kaylee (Full-stack Dev)  
+**Issue:** #41  
+
+Added security hardening across API, WebApp, and Marketing services.
+
+**Security Headers (all services):**
+- Shared extension `UseSecurityHeaders()` in `src/Shared/SecurityHeadersExtensions.cs`
+- Linked via `<Compile Include>` to prevent ambiguous call errors with MAUI defaults
+- Headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy: camera=(), microphone=(), geolocation=()
+
+**HTTPS and HSTS:**
+- HTTPS redirect environment-aware: skipped in Development (Aspire terminates TLS at proxy)
+- API explicit HSTS: 365-day max-age, includeSubDomains, preload
+- WebApp and Marketing HSTS unchanged (already configured in non-dev block)
+
+**CORS (API only):**
+- `AllowWebApp` policy: restricts to `Cors:AllowedOrigins` config
+- `AllowDevClients` policy: dev-only, localhost with credentials
+- Production origins in `appsettings.Production.json`
+- MAUI clients unaffected (service discovery, not browser CORS)
+
+**AllowedHosts:** Production `appsettings.json` files restrict to specific domains, not wildcard.
+
+**Deferred:** Production CORS fine-tuning (#62), CSP header (Blazor inline scripts), production auth (still DevAuthHandler).
+
 ## Governance
 
 - All meaningful changes require team consensus

.squad/decisions/inbox/wash-user-secrets.md

@@ -0,0 +1,44 @@
+# Orchestration Log: Zoe GitHub Issues Spawn
+
+**Date:** 2026-03-13T2352  
+**Agent:** Zoe (Lead)  
+**Task:** Create 27 GitHub issues from Azure deployment plan  
+**Status:** SUCCESS  
+
+## Outcome Summary
+
+- **Issues Created:** 27 (#39–#65)
+- **Repository:** davidortinau/SentenceStudio
+- **Labels Applied:** phase tags, size tags, squad tags, individual agent assignments
+- **Dependencies:** All 27 issues cross-referenced with dependency links
+
+## Issue Mapping
+
+**Phase 1 (Auth):** #42, #43, #44, #45, #46, #47  
+**Phase 2 (Secrets):** #39, #40, #41, #54  
+**Phase 3 (Infrastructure):** #48, #49, #50, #51, #52, #53, #55  
+**Phase 4 (Pipeline):** #56, #57, #58, #59  
+**Phase 5 (Hardening):** #60, #61, #62, #63, #64, #65  
+
+## Team Assignments
+
+- **Zoe (Lead):** 14 issues — foundational auth, infrastructure, hardening decisions
+- **Kaylee (Full-stack):** 8 issues — WebApp OIDC, MAUI MSAL, CI/deploy, monitoring
+- **Captain (David):** 1 issue — Entra ID app registrations (Azure portal)
+
+## Key Decisions Documented
+
+1. **Reframed Issue #39:** User-secrets as team best practice (not security emergency)
+2. **Phase Execution Order:** Phase 2 → 1 → 3 → 4 → 5 (security-first approach)
+3. **Localhost-Testable:** Phase 1 auth entirely testable without Azure deployment
+4. **Critical Path:** CoreSync SQLite→PostgreSQL migration (Phase 3.7, XL)
+
+## Files Affected
+
+- `.squad/agents/zoe/history.md` — Updated with work session
+- `.squad/decisions/inbox/zoe-github-issues-created.md` — Decision record created
+- `.squad/decisions/inbox/zoe-azure-auth-plan.md` — Existing plan reference
+
+## Next Actions
+
+Scribe to merge inbox decisions into `decisions.md`, propagate cross-agent updates, and commit.

.squad/orchestration-log/2026-03-13T2352-zoe-github-issues.md

@@ -0,0 +1,40 @@
+# Orchestration Log: Kaylee (agent-6)
+
+**Date:** 2026-03-14T01:00:00Z  
+**Agent:** Kaylee (Full-stack Dev)  
+**Mode:** Background, Standard  
+**Issue:** #41  
+
+## Outcome
+
+DONE
+
+## Work Summary
+
+- Implemented security hardening across API, WebApp, and Marketing services
+- Created shared extension `UseSecurityHeaders()` in `src/Shared/SecurityHeadersExtensions.cs` with security headers:
+  - X-Content-Type-Options: nosniff (prevent MIME-sniffing)
+  - X-Frame-Options: DENY (prevent clickjacking)
+  - Referrer-Policy: strict-origin-when-cross-origin
+  - Permissions-Policy: camera=(), microphone=(), geolocation=()
+- Implemented environment-aware HTTPS redirect: skipped in Development (Aspire terminates TLS at proxy)
+- Added HSTS to API: 365-day max-age, includeSubDomains, preload
+- Implemented CORS policies on API:
+  - `AllowWebApp` policy: restricts to configured origins
+  - `AllowDevClients` policy: dev-only, allows localhost with credentials
+- Created `appsettings.Production.json` for all three services with AllowedHosts restrictions
+
+## Branch
+
+`feature/41-security-headers`
+
+## Key Decisions
+
+- Linked source file for `SecurityHeadersExtensions.cs` instead of WebServiceDefaults (avoids ambiguous call errors with MAUI defaults)
+- CORS not applied to MAUI clients (use service discovery, not browser CORS)
+- Production CORS fine-tuning deferred to #62
+- Content-Security-Policy header deferred (complex for Blazor inline scripts)
+
+## Blockers
+
+None

.squad/orchestration-log/2026-03-14T01-00-kaylee.md

@@ -0,0 +1,35 @@
+# Orchestration Log: Wash (agent-5)
+
+**Date:** 2026-03-14T01:00:00Z  
+**Agent:** Wash (Backend Dev)  
+**Mode:** Background, Standard  
+**Issue:** #39  
+
+## Outcome
+
+DONE
+
+## Work Summary
+
+- Initialized `.NET user-secrets` for `SentenceStudio.Api` and `SentenceStudio.WebApp`
+- Created `secrets.template.json` at repo root documenting all secret keys organized by project context
+- Updated `README.md` (Section 3) with three paths for secrets management:
+  - Option A: Aspire (recommended) — set secrets in AppHost, flow to all services
+  - Option B: Standalone projects — per-project `dotnet user-secrets`
+  - Option C: MAUI mobile/desktop — gitignored `appsettings.json`
+- Documented secret flow: AppHost uses Aspire Parameters → `.WithEnvironment()` → services via env var normalization (`__` → `:`)
+- Captured all UserSecretsId GUIDs and secrets inventory (OpenAI, ElevenLabs, Syncfusion)
+
+## Branch
+
+`feature/39-user-secrets`
+
+## Key Decisions
+
+- AppHost's existing user-secrets remain intact — no migration needed
+- Parameter flow leverages Aspire's `__` to `:` normalization for clean cross-platform config
+- No database changes; no secrets moved or deleted
+
+## Blockers
+
+None

.squad/orchestration-log/2026-03-14T01-00-wash.md

@@ -17,6 +17,7 @@
 using SentenceStudio.Contracts.Vocabulary;
 using SentenceStudio.Data;
 using SentenceStudio.Domain.Abstractions;
+using SentenceStudio.Infrastructure;
 using SentenceStudio.Services;
 using SentenceStudio.Shared.Models;
 
@@ -31,6 +32,42 @@
 builder.Services.AddAuthorization();
 builder.Services.AddScoped<ITenantContext, TenantContext>();
 
+// CORS — basic policies for known callers.
+// Production fine-tuning is tracked in issue #62.
+var allowedOrigins = builder.Configuration.GetSection("Cors:AllowedOrigins").Get<string[]>();
+builder.Services.AddCors(options =>
+{
+    if (allowedOrigins?.Length > 0)
+    {
+        options.AddPolicy("AllowWebApp", policy =>
+        {
+            policy.WithOrigins(allowedOrigins)
+                .AllowAnyHeader()
+                .AllowAnyMethod();
+        });
+    }
+
+    if (builder.Environment.IsDevelopment())
+    {
+        options.AddPolicy("AllowDevClients", policy =>
+        {
+            policy.SetIsOriginAllowed(origin =>
+                    Uri.TryCreate(origin, UriKind.Absolute, out var uri)
+                    && uri.Host is "localhost" or "127.0.0.1")
+                .AllowAnyHeader()
+                .AllowAnyMethod()
+                .AllowCredentials();
+        });
+    }
+});
+
+builder.Services.AddHsts(options =>
+{
+    options.MaxAge = TimeSpan.FromDays(365);
+    options.IncludeSubDomains = true;
+    options.Preload = true;
+});
+
 // Database - shared with WebApp server instance
 var serverDbFolder = Path.Combine(
     Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
@@ -68,7 +105,19 @@
     app.MapOpenApi();
 }
 
-app.UseHttpsRedirection();
+if (!app.Environment.IsDevelopment())
+{
+    app.UseHsts();
+}
+
+// Skip HTTPS redirect in development — Aspire may terminate TLS at the proxy.
+if (!app.Environment.IsDevelopment())
+{
+    app.UseHttpsRedirection();
+}
+
+app.UseSecurityHeaders();
+app.UseCors(app.Environment.IsDevelopment() ? "AllowDevClients" : "AllowWebApp");
 app.UseAuthentication();
 app.UseAuthorization();
 app.UseMiddleware<TenantContextMiddleware>();

src/SentenceStudio.Api/Program.cs

@@ -20,4 +20,8 @@
     <ProjectReference Include="..\SentenceStudio.ServiceDefaults\SentenceStudio.ServiceDefaults.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="..\Shared\SecurityHeadersExtensions.cs" Link="Infrastructure\SecurityHeadersExtensions.cs" />
+  </ItemGroup>
+
 </Project>

src/SentenceStudio.Api/SentenceStudio.Api.csproj

@@ -0,0 +1,9 @@
+{
+  "AllowedHosts": "api.sentencestudio.com;sentencestudio.com",
+  "Cors": {
+    "AllowedOrigins": [
+      "https://sentencestudio.com",
+      "https://www.sentencestudio.com"
+    ]
+  }
+}