# 5D auth / Swagger 邊界分析

本文件承接 [第五階段 Loader 到 Service 後續文件 / 實作 / 驗收範圍補齊表](phase-five-loader-to-service-scope-acceptance-plan.md) 與 [5C DB audit 實作與驗收紀錄](phase-five-c-db-audit-implementation-acceptance-record.md)。

5D 的目標是先固定 WebApi auth / Swagger 的外部暴露邊界、候選程式位置、測試策略與停止線。5D 會碰到 API 權限、Swagger 是否開放、secret 保存與正式部署設定，因此在使用者完成七項確認前，不修改程式 repo，不新增套件，不啟用 Swagger，不導入 auth middleware，也不改 production 部署設定。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 歷史前置文件；5D 已於 `c92342b` 完成實作與驗收 |
| 建立日期 | 2026-06-07 |
| 對應節點 | 第五階段 5D auth / Swagger |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 | 本文件建立時為 `354fecd`；後續實作完成基準為 `c92342b` |
| 本次是否修改程式 repo | 否，只做唯讀檢查、測試基準與文件整理 |
| 下一步 | 5D 已完成；後續進入 5E Windows Service 最小實作前最後確認 |

## 1. 5D 目標

| 目標 | 說明 |
|---|---|
| 固定 WebApi 安全邊界 | 先確認哪些 API 需要保護、哪些可匿名、錯誤格式與測試方式。 |
| 避免 secret 入 repo | 不保存正式 API key、token、JWT secret、client secret、正式 IP 或正式網域設定。 |
| Swagger dev-only | Swagger 若要導入，第一版只允許 development / local gate，不作為正式外網文件入口。 |
| 保留標準錯誤格式 | 未授權、權限不足與停用 Swagger 都需回標準 HTTP 狀態或可測試結果，不吞例外。 |
| 不擴大部署面 | 不修改正式 reverse proxy、DNS、TLS、Cloudflare、GitHub secret 或 Windows Service 設定。 |
| 建立 API 測試證據 | 需覆蓋未授權、權限不足、成功、Health 例外規則、Swagger dev-only / production disabled。 |

## 2. WebApi 唯讀檢查結果

| 檢查項目 | 結果 |
|---|---|
| 文件 repo 狀態 | `main...origin/main`，乾淨。 |
| 程式 repo 狀態 | `poc/nmodbus-tcp...origin/poc/nmodbus-tcp`，乾淨。 |
| 現有 WebApi 專案 | `src/HS.DeviceControl.WebApi` 已存在，TargetFramework 為 `net5.0`。 |
| 現有 controller | `TasksController`、`DevicesController`、`SchemaController`、`HealthController`。 |
| 現有 Startup | 目前只有 `AddControllers()`、mock / in-memory DI、`UseRouting()`、`MapControllers()`。 |
| Auth / Authorization | 未命中 `AddAuthentication`、`UseAuthentication`、`AddAuthorization`、`UseAuthorization`、`Authorize`。 |
| Swagger / OpenAPI | 未命中 `Swagger`、`OpenApi`、`AddSwaggerGen`、`UseSwagger`。 |
| 現有 API tests | `WebApiControllerTests` 覆蓋 tasks、devices、schema、health 基本 controller mapping。 |
| 5D 測試基準 | `dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --no-restore`，7 passed / 0 failed / 0 skipped。 |

備註：WebApi 測試仍出現既有 `.NET 5.0` EOL warning，與 5D 文件節點無關。

## 3. API 保護範圍草案

| API 類型 | 建議 5D 第一版規則 | 原因 |
|---|---|---|
| `POST /api/tasks` | 需授權 | 會建立任務，屬操作入口。 |
| `GET /api/tasks/{taskId}` | 需授權 | 會查詢任務狀態與可能的節點歷程。 |
| `POST /api/tasks/{taskId}/cancel` | 需授權，後續可加較高權限 | 會改變任務狀態。 |
| `GET /api/devices/{deviceId}/status` | 需授權 | 會暴露設備狀態與錯誤摘要。 |
| `POST /api/schema/preview` | 需授權，建議只允許 reviewer / admin | 會暴露 schema preview 與檢查結果。 |
| `GET /health` | 可保留匿名或另設內網 gate，需決策 | 方便本機 / service health probe，但也可能暴露系統狀態。 |
| Swagger UI / OpenAPI JSON | 僅 development / local gate，production disabled | 避免正式外網暴露 API 結構。 |

## 4. Auth 模型草案

5D 第一版建議先採「可測試的最小 API gate」，不直接導入外部身分系統：

| 選項 | 建議 |
|---|---|
| API key / header gate | 可作第一版本機測試策略，但不得保存正式 key；測試使用固定假值。 |
| JWT / OAuth / OIDC | 暫不建議第一批導入，除非另行確認 provider、issuer、audience、secret 管理。 |
| Role / policy | 可先建立 `Operator`、`Admin` 或 `SchemaReviewer` 之類 policy 草案；若要落程式需測試未授權與權限不足。 |
| Secret 來源 | 不寫入 repo；正式 secret 需外部環境變數 / secret store，且另行確認。 |
| Error response | 401 / 403 不應暴露 secret、token 原文或 stack trace。 |

## 5. Swagger 邊界草案

| 項目 | 建議規則 |
|---|---|
| 套件 | 若需要 `Swashbuckle.AspNetCore` 或其他 OpenAPI 套件，需在 5D 七項確認後才可新增。 |
| 啟用環境 | Development / local only，production 預設 disabled。 |
| UI 暴露 | 不作為正式外網入口；若需要正式文件，需另開部署與權限確認。 |
| 文件內容 | 不放 secret、正式 URL、正式 IP、正式帳號、正式 token 或案場資訊。 |
| 測試 | 需測 dev 可用、production disabled、swagger 不繞過 auth gate。 |

## 6. 候選程式檔案

若使用者確認 5D 七項，建議第一批只做 WebApi 層與測試：

| 類型 | 候選檔案 | 說明 |
|---|---|---|
| Auth options | `src/HS.DeviceControl.WebApi/Security/WebApiAuthOptions.cs` | 定義測試用 header 名稱、啟用開關與 safe default。 |
| Auth handler | `src/HS.DeviceControl.WebApi/Security/ApiKeyAuthenticationHandler.cs` | 第一版可測試 handler；不得保存正式 secret。 |
| Policy constants | `src/HS.DeviceControl.WebApi/Security/WebApiPolicies.cs` | 集中定義 policy / role 名稱。 |
| Startup | `src/HS.DeviceControl.WebApi/Startup.cs` | 加入 `AddAuthentication` / `AddAuthorization` / pipeline，需測試順序。 |
| Controllers | `src/HS.DeviceControl.WebApi/Controllers/*.cs` | 加上 `[Authorize]` / `[AllowAnonymous]`，不得改 route 語意。 |
| Swagger | `src/HS.DeviceControl.WebApi/Startup.cs`、`.csproj` | 若要導入 Swagger，需新增套件與 dev-only gate；屬確認後才能做。 |
| Tests | `tests/HS.DeviceControl.WebApi.Tests` | 新增 auth / Swagger tests，並保留既有 controller tests。 |

若實作時發現必須新增正式 secret、修改 API route、導入外部 IdP、修改 GitHub / Cloudflare / deployment setting、加入 production Swagger 或新增核心套件，需停下重新確認。

## 7. 驗收策略

| 驗收項目 | 預期證據 |
|---|---|
| Auth gate | API tests 確認缺少 credential 回 401，錯誤 credential 回 401。 |
| Authorization | 需要高權限的 API 需測權限不足回 403。 |
| 成功流程 | 合法測試 credential 可呼叫既有 controller，結果仍符合既有 Application contract。 |
| Health 例外 | 明確決定 `GET /health` 是否匿名；若匿名需測仍不暴露敏感資料。 |
| Swagger dev-only | Development 可用且 production disabled；若不導入套件，需在文件中明確保留。 |
| Secret stop-line | 掃描確認無正式 key、token、JWT secret、connection string、正式 URL / IP。 |
| 回歸測試 | WebApi tests、Application tests、solution tests 通過。 |

## 8. 明確排除

- 不新增正式 API key、JWT secret、OAuth client secret 或任何真實 credential。
- 不修改 GitHub Secret、Cloudflare、DNS、TLS、reverse proxy 或正式部署設定。
- 不將 Swagger 開放為 production 外網入口。
- 不修改既有 API route 語意。
- 不新增 DB table、DB DDL、formal Apply 或真實 DB 寫入。
- 不修改 ServiceHost / Windows Service。
- 不載入外部 DLL，不掃描 plugin folder。
- 不修改 Adapter public contract。

## 9. 下一步

請先確認 [5D auth / Swagger 實作前確認表](phase-five-d-auth-swagger-preimplementation-checklist.md) 七項。確認前，只能停留在文件、唯讀檢查與測試基準；確認後才可進入 5D 第一批 WebApi auth / Swagger 程式實作。