Merge pull request #66 from davidortinau/feature/39-user-secrets

davidortinau · web-flow · commit 29f0b83fb025 · 2026-03-14T18:59:11.000-05:00
feat: set up .NET user-secrets workflow (#39)
diff --git a/.squad/agents/jayne/history.md b/.squad/agents/jayne/history.md
@@ -18,4 +18,22 @@
 - "It compiles" is NOT sufficient — must verify in running app
 - Must call `CacheService.InvalidateVocabSummary()` after recording attempts or dashboard is stale
 - Playwright must use `pressSequentially` not `fill()` for Blazor server-side binding
+- "It compiles" is NOT sufficient — must verify in running app
+- Must call `CacheService.InvalidateVocabSummary()` after recording attempts or dashboard is stale
+- Playwright must use `pressSequentially` not `fill()` for Blazor server-side binding
 - Test users: David (Korean, f452438c-...), Jose (Spanish, 8d5f7b4a-...), Gunther (German, c3bb57f7-...)
+
+## Work Sessions
+
+### 2026-03-13 — Cross-Agent Update: Azure Deployment Issues
+
+**Status:** In Progress  
+**GitHub Issues:** #39-#65 created by Zoe (Lead)  
+**Jayne's Assignment:** N/A (testing/QA support for phase execution)  
+
+**Phase Execution Order:** Phase 2 (Secrets) → Phase 1 (Auth, localhost-testable) → Phase 3 (Infra) → Phase 4 (Pipeline) → Phase 5 (Hardening)
+
+**E2E Testing Support:** Jayne to verify each phase's integration tests per e2e-testing skill (mandatory for every feature/fix).
+
+**Critical Path:** CoreSync SQLite→PostgreSQL migration (#55, XL) — requires comprehensive data migration testing.
+
diff --git a/.squad/agents/kaylee/history.md b/.squad/agents/kaylee/history.md
@@ -16,3 +16,26 @@
 - Activity pages: PageHeader, activity-content area, footer with activity-input-bar
 - Word Association activity at `/word-association` — latest activity, has Grade-first UX flow
 - Dashboard activities listed in `src/SentenceStudio.UI/Pages/Index.razor`
+
+## Work Sessions
+
+### 2026-03-13 — Cross-Agent Update: Azure Deployment Issues
+
+**Status:** In Progress  
+**GitHub Issues:** #39-#65 created by Zoe (Lead)  
+**Kaylee's Assignments:** 8 issues  
+
+**Issues Assigned to Kaylee:**
+- #44 WebApp OIDC Integration (Phase 1, size:L)
+- #45 MAUI MSAL Implementation (Phase 1, size:XL)
+- #56 CI Workflow Setup (Phase 4, size:M)
+- #57 Deploy Workflow (Phase 4, size:L)
+- #58 Staging Environment (Phase 4, size:M)
+- #60 Azure Monitor/Application Insights (Phase 5, size:M)
+- #62 CORS Configuration (Phase 5, size:S)
+- #64 Auto-Scaling Rules (Phase 5, size:M)
+
+**Phase Execution Order:** Phase 2 (Secrets) → Phase 1 (Auth, localhost-testable) → Phase 3 (Infra) → Phase 4 (Pipeline) → Phase 5 (Hardening)
+
+**Critical Path:** CoreSync SQLite→PostgreSQL migration (#55, XL).
+
diff --git a/.squad/agents/wash/history.md b/.squad/agents/wash/history.md
@@ -17,4 +17,23 @@
 - DI registration in `SentenceStudioAppBuilder.cs` (AppLib) and `Program.cs` (WebApp)
 - Aspire env var config: `builder.Configuration["AI:OpenAI:ApiKey"]` not `["AI__OpenAI__ApiKey"]`
 - Server DB at: `/Users/davidortinau/Library/Application Support/sentencestudio/server/sentencestudio.db`
+- Server DB at: `/Users/davidortinau/Library/Application Support/sentencestudio/server/sentencestudio.db`
 - UserProfileId columns for multi-user data isolation — all repos filter by active_profile_id
+
+## Work Sessions
+
+### 2026-03-13 — Cross-Agent Update: Azure Deployment Issues
+
+**Status:** In Progress  
+**GitHub Issues:** #39-#65 created by Zoe (Lead)  
+**Wash's Role:** Deployment orchestration support  
+
+**Phase Execution Order:** Phase 2 (Secrets) → Phase 1 (Auth, localhost-testable) → Phase 3 (Infra) → Phase 4 (Pipeline) → Phase 5 (Hardening)
+
+**Wash Coordination Points:**
+- Phase 4 (Pipeline) — CI/deploy workflows — coordinate with Kaylee's automation
+- Phase 3.5 (Container Apps) — deployment target provisioning
+- Critical Path: CoreSync SQLite→PostgreSQL migration (#55, XL) — coordinate safe data migration in production
+
+**Key Dependencies:** Zoe coordinates Phase 1-3 decisions; Kaylee implements CI/deploy automation; Captain provides Azure portal access.
+
diff --git a/.squad/agents/zoe/history.md b/.squad/agents/zoe/history.md
@@ -18,3 +18,46 @@
 - Build with TFM: `dotnet build -f net10.0-maccatalyst`
 - E2E testing is mandatory for every feature/fix
 - Activities follow pattern: `activity-page-wrapper` → `PageHeader` → `activity-content` → `activity-input-bar`
+
+## Work Sessions
+
+### 2026-03-13 — GitHub Issues Created for Azure + Entra ID Plan
+
+**Status:** Complete  
+**Issues Created:** 27 issues (#39–#65)  
+**Dependencies:** All cross-referenced with dependency links  
+
+**Cross-Team Impact:**
+- **Kaylee:** 8 issues assigned (#44–45, #56–59, #60)
+- **Captain:** 1 issue assigned (#42)
+- Issues propagated to respective agent history files
+
+See `.squad/decisions.md` for full decision record.
+
+### 2025-07-22 — Created GitHub Issues for Azure Deployment + Entra ID Plan
+
+**Status:** Complete  
+**Issues Created:** 27 issues (#39-#65)  
+**Decision:** Reframed issue #39 (2.1) from "security emergency" to "best practices" — no secrets were committed to git history.
+
+**Issue Mapping to Plan:**
+
+- **Phase 1 (Auth):** #42 (Entra registrations) → #43 (JWT API) → #44 (WebApp OIDC) → #45 (MAUI MSAL) → #46 (CoreSync) → #47 (Integration tests)
+- **Phase 2 (Secrets):** #39 (user-secrets) → #40 (config all projects) → #41 (HTTPS/headers) → #54 (Key Vault integration)
+- **Phase 3 (Infrastructure):** #48 (azure.yaml) → #49 (PostgreSQL) → #50 (Redis) → #51 (Blob) → #52 (Container Apps) → #53 (Key Vault) → #55 (CoreSync DB migration)
+- **Phase 4 (Pipeline):** #56 (CI) → #57 (Deploy) → #58 (Staging) → #59 (Migrations)
+- **Phase 5 (Hardening):** #60 (Monitoring) → #61 (Rate limit) → #62 (CORS) → #63 (Health) → #64 (Scaling) → #65 (Audit logging)
+
+**Team Assignments:**
+- Zoe (Lead): 14 issues (auth foundational work, infra decisions, hardening architecture)
+- Kaylee (Full-stack): 8 issues (WebApp OIDC, MAUI MSAL, CI/deploy workflows, monitoring)
+- Captain (David): 1 issue (#42 - requires Azure portal/Entra ID access)
+
+**Dependencies Validated:** All 27 issues cross-referenced with dependency links. Phase order preserved for execution.
+
+**Key Learnings:**
+- No security emergency: appsettings.json with secrets already in .gitignore
+- User-secrets workflow as team best practice (Phase 2.1)
+- Phase 1 testable entirely on localhost with Entra ID redirecting to `http://localhost`
+- CoreSync SQLite→PostgreSQL migration is critical path item (Phase 3.7, XL size)
+- Aspire-native provisioning via `azd` avoids manual Bicep maintenance
diff --git a/.squad/decisions.md b/.squad/decisions.md
@@ -2,7 +2,71 @@
 
 ## Active Decisions
 
-No decisions recorded yet.
+### 1. GitHub Issues Created for Azure + Entra ID Plan (2026-03-13)
+
+**Status:** DOCUMENTED  
+**Date:** 2026-03-13  
+**Author:** Zoe (Lead)  
+
+27 GitHub issues decompose the Azure deployment + Entra ID authentication plan into actionable work items across 5 phases. All issues linked with dependency references and assigned to team members.
+
+**Key Decisions:**
+- **Reframed Issue #39:** User-secrets workflow as team best practice (not security emergency) — no secrets accidentally committed; `appsettings.json` already in `.gitignore`
+- **Execution Order:** Phase 2 → Phase 1 → Phase 3 → Phase 4 → Phase 5 (security-first approach)
+- **Phase 1 Testable Locally:** Auth flow fully validates on `localhost` without Azure deployment
+- **Team Assignments:** Zoe (14 issues, architecture/infra), Kaylee (8 issues, UI/deploy), Captain (1 issue, Azure portal)
+- **Critical Path:** CoreSync SQLite→PostgreSQL migration (Phase 3.7, XL complexity)
+
+**Issue Mapping:**
+| Phase | Count | Issues |
+|-------|-------|--------|
+| Phase 1 (Auth) | 7 | #42-47 |
+| Phase 2 (Secrets) | 4 | #39-41, #54 |
+| Phase 3 (Infrastructure) | 8 | #48-53, #55 |
+| Phase 4 (Pipeline) | 4 | #56-59 |
+| Phase 5 (Hardening) | 6 | #60-65 |
+
+**Learnings:**
+- Aspire-native provisioning (`azd`) generates Bicep — no manual templates needed
+- Localhost testing of auth eliminates blocker for early validation
+- DevAuthHandler alongside Entra ID maintains developer velocity
+- User-secrets as team best practice enables secure local dev
+
+**Next Steps:**
+1. Captain: Register Entra ID app registrations (#42)
+2. Zoe: Begin user-secrets setup (#39-40)
+3. Kaylee: Begin CI workflow (#56)
+4. All phases proceed in parallel where dependencies allow
+
+---
+
+### 2. Architecture Plan: Azure Deployment with Entra ID Authentication (2026-03-13)
+
+**Status:** REFERENCE  
+**Date:** 2026-03-13  
+**Author:** Zoe (Lead)  
+
+Comprehensive architecture plan for transitioning SentenceStudio from local-dev-only to production-ready Azure deployment with real authentication. Covers 5 phases from secret management through hardening, with technical decisions, risk register, and cost estimates.
+
+**Key Technical Decisions:**
+1. **Aspire-Native Provisioning over Raw Bicep** — AppHost defines resources; `azd` generates Bicep
+2. **Keep DevAuthHandler Alongside Entra ID** — Developer velocity: use DevAuthHandler for local dev, Entra ID for production
+3. **PostgreSQL over Azure SQL** — Aligns with AppHost declaration and CoreSync support
+4. **Single-Tenant First** — Start with single Entra ID tenant; multi-tenant support added later
+5. **Token Caching:** SecureStorage (MAUI) and Redis (WebApp)
+
+**3 App Registrations Required:**
+- SentenceStudio API (Web API — resource server)
+- SentenceStudio WebApp (Web app, confidential — Blazor Server)
+- SentenceStudio Native (Mobile/Desktop, public — MAUI clients)
+
+**Scopes Exposed:**
+- `api://sentencestudio/user.read` — user profile, vocabulary
+- `api://sentencestudio/user.write` — modify user data, submit answers
+- `api://sentencestudio/ai.access` — AI chat, speech synthesis, image analysis
+- `api://sentencestudio/sync.readwrite` — CoreSync bi-directional sync
+
+**Estimated Monthly Cost (Production):** ~$107-252
 
 ## Governance
 
diff --git a/.squad/decisions/inbox/wash-user-secrets.md b/.squad/decisions/inbox/wash-user-secrets.md
@@ -0,0 +1,46 @@
+# Decision: Set up .NET user-secrets workflow
+
+**Author:** Wash (Backend Dev)
+**Issue:** #39
+**Date:** 2025-07-17
+**Branch:** feature/39-user-secrets
+
+## Summary
+
+Established the .NET user-secrets pattern for secure local development across all server-side projects.
+
+## What Changed
+
+1. **Initialized user-secrets** for `SentenceStudio.Api` and `SentenceStudio.WebApp` via `dotnet user-secrets init`. Workers and AppHost already had UserSecretsId configured.
+
+2. **Created `secrets.template.json`** at repo root documenting every secret key, organized by project context (AppHost/Aspire, Api standalone, WebApp standalone, MAUI apps).
+
+3. **Updated `README.md`** section 3 ("API Keys and Secrets") with three clear paths:
+   - Option A: Aspire (recommended) -- set secrets once in AppHost, they flow to all services via `WithEnvironment()`
+   - Option B: Standalone projects -- set secrets per-project with `dotnet user-secrets`
+   - Option C: MAUI mobile/desktop -- use gitignored `appsettings.json` in AppLib
+
+## How Secrets Flow
+
+The AppHost uses Aspire Parameters (`builder.AddParameter("openaikey", secret: true)`) which resolve from the AppHost's user-secrets under `Parameters:openaikey`. These are then passed to child projects via `.WithEnvironment("AI__OpenAI__ApiKey", openaikey)`. Aspire normalizes `__` to `:` in configuration, so `AI__OpenAI__ApiKey` becomes `AI:OpenAI:ApiKey` at the receiving end.
+
+## 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 existing secrets were moved or deleted. The AppHost's existing user-secrets remain intact and functional.
diff --git a/README.md b/README.md
@@ -131,56 +131,61 @@ cd src
 dotnet restore
 ```
 
-### 3. API Keys Configuration
+### 3. API Keys and Secrets
 
-Sentence Studio requires API keys for AI and text-to-speech functionality. You'll need to obtain and configure the following:
+Sentence Studio requires API keys for AI and text-to-speech functionality. Obtain the following keys before proceeding:
 
-#### Required API Keys
+| Secret | Required | Where to get it |
+|--------|----------|-----------------|
+| **OpenAI API Key** | Yes | https://platform.openai.com/api-keys |
+| **ElevenLabs API Key** | Yes | https://elevenlabs.io/app/speech-synthesis |
+| **Syncfusion License Key** | Optional | https://www.syncfusion.com/account/downloads |
+| **HuggingFace Token** | Optional | https://huggingface.co/settings/tokens |
 
-1. **OpenAI API Key** - For AI-powered language learning features
-   - Visit: https://platform.openai.com/api-keys
-   - Create an account and generate an API key
-   - Ensure your account has sufficient credits or an active subscription
+See `secrets.template.json` at the repo root for the full key structure.
 
-2. **ElevenLabs API Key** - For text-to-speech functionality
-   - Visit: https://elevenlabs.io/app/speech-synthesis
-   - Create an account and generate an API key
-   - Free tier available with usage limitations
+#### Option A: Running with .NET Aspire (recommended)
 
-3. **HuggingFace Token** (Optional) - For additional AI model access
-   - Visit: https://huggingface.co/settings/tokens
-   - Create an account and generate an access token
+When running through the AppHost, secrets are managed centrally and passed to all services automatically. Set them once in the AppHost project:
 
-4. **Syncfusion Key** (Optional) - For premium UI components
-   - Visit: https://www.syncfusion.com/account/downloads
-   - Create a community account for free license
+```bash
+cd src/SentenceStudio.AppHost
+
+dotnet user-secrets set "Parameters:openaikey" "sk-proj-your-key-here"
+dotnet user-secrets set "Parameters:elevenlabskey" "sk_your-key-here"
+dotnet user-secrets set "Parameters:syncfusionkey" "your-license-key-here"
+```
 
-#### Configuration Setup
+The AppHost passes these to Api, WebApp, Workers, and MAUI projects via `WithEnvironment()` at runtime. You do not need to configure secrets in each individual project when using Aspire.
 
-Copy the template configuration file and add your API keys:
+#### Option B: Running individual projects without Aspire
 
+If you run a project standalone (not through the AppHost), set its secrets directly:
+
+**Api:**
 ```bash
-# Copy the template file
-cp src/SentenceStudio/appsettings.template.json src/SentenceStudio/appsettings.json
+cd src/SentenceStudio.Api
+dotnet user-secrets set "AI:OpenAI:ApiKey" "sk-proj-your-key-here"
+dotnet user-secrets set "ElevenLabsKey" "sk_your-key-here"
+```
 
-# Edit the appsettings.json file with your actual API keys
-# Note: This file is gitignored for security
+**WebApp:**
+```bash
+cd src/SentenceStudio.WebApp
+dotnet user-secrets set "Settings:OpenAIKey" "sk-proj-your-key-here"
+dotnet user-secrets set "Settings:ElevenLabsKey" "sk_your-key-here"
 ```
 
-Your `appsettings.json` should look like:
-
-```json
-{
-  "Settings": {
-    "OpenAIKey": "sk-proj-your-actual-openai-key-here",
-    "HuggingFaceToken": "hf_your-actual-huggingface-token-here", 
-    "ElevenLabsKey": "sk_your-actual-elevenlabs-key-here",
-    "SyncfusionKey": "your-actual-syncfusion-key-here"
-  }
-}
+#### Option C: MAUI mobile/desktop apps (without Aspire)
+
+MAUI apps read from `appsettings.json` in the AppLib project. This file is gitignored:
+
+```bash
+cp src/SentenceStudio.AppLib/appsettings.template.json src/SentenceStudio.AppLib/appsettings.json
+# Edit src/SentenceStudio.AppLib/appsettings.json with your actual keys
 ```
 
-**⚠️ Security Warning**: Never commit the `appsettings.json` file containing real API keys to version control. The file is included in `.gitignore` to prevent accidental exposure.
+**Security note:** The `appsettings.json` files containing secrets are gitignored. Never commit real API keys to version control. Use `dotnet user-secrets` for all server-side projects.
 
 ## Building and Running
 
diff --git a/secrets.template.json b/secrets.template.json
@@ -0,0 +1,21 @@
+{
+  "_comment": "This file documents all secrets required for local development. NO actual values here.",
+  "_instructions": "Set values using: dotnet user-secrets set 'Key' 'value' --project src/<Project>",
+
+  "_section_apphost": "---- AppHost (Aspire orchestrator) ---- Run from src/SentenceStudio.AppHost",
+  "Parameters:openaikey": "<your-openai-api-key>",
+  "Parameters:elevenlabskey": "<your-elevenlabs-api-key>",
+  "Parameters:syncfusionkey": "<your-syncfusion-license-key>",
+
+  "_section_api": "---- Api (standalone, without Aspire) ---- Run from src/SentenceStudio.Api",
+  "AI:OpenAI:ApiKey": "<your-openai-api-key>",
+  "ElevenLabsKey": "<your-elevenlabs-api-key>",
+
+  "_section_webapp": "---- WebApp (standalone, without Aspire) ---- Run from src/SentenceStudio.WebApp",
+  "Settings:OpenAIKey": "<your-openai-api-key>",
+  "Settings:ElevenLabsKey": "<your-elevenlabs-api-key>",
+
+  "_section_maui": "---- MAUI Apps (AppLib appsettings.json, gitignored) ---- Copy appsettings.template.json to appsettings.json in src/SentenceStudio.AppLib/",
+  "Settings:SyncfusionKey": "<your-syncfusion-license-key>",
+  "Settings:HuggingFaceToken": "<your-huggingface-token (optional)>"
+}
diff --git a/src/SentenceStudio.Api/SentenceStudio.Api.csproj b/src/SentenceStudio.Api/SentenceStudio.Api.csproj
@@ -1,9 +1,10 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <UserSecretsId>9ae3953f-a490-41b3-a2b8-a8e2555b4615</UserSecretsId>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/src/SentenceStudio.WebApp/SentenceStudio.WebApp.csproj b/src/SentenceStudio.WebApp/SentenceStudio.WebApp.csproj
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <ItemGroup>
     <ProjectReference Include="..\SentenceStudio.AppLib\SentenceStudio.AppLib.csproj" />
@@ -13,6 +13,7 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>
+    <UserSecretsId>33f95f89-d495-4311-b6cb-53a47b5c34e6</UserSecretsId>
   </PropertyGroup>
 
 </Project>
