摘要
Day 27 把 Day 26 的 PHI masking / privacy evidence 往 sandbox authorization boundary 補強：report 不只顯示 sandbox /metadata CapabilityStatement readiness，現在也會顯示 request-scoped SMART/OAuth sandbox token flow evidence。Day 27 讓 Quality Test Report 可以證明：sandbox token endpoint 必須被 allowlist、token request 必須明確啟用、non-PHI guard 與 sandbox auth boundary 必須通過，而且 report 只暴露 token hash、scope evidence 和狀態，不顯示 access token 或 client secret 原文。

這和「能不能交換」有什麼關係？

Day 26 可以回答：

report / AuditEvent / Provenance preview 會不會把 PHI 帶出去？

但正式接近 sandbox exchange 前，還有一個更具體的問題：

這個 sandbox preflight 有沒有可檢查的 token boundary evidence？

如果一個 quality gate 只能說 sandbox auth mode 是 bearer_token_configured，但完全不能證明 token endpoint 是否 allowlisted、token request 是否啟用、scope 是否被要求、token response 是否有被遮罩，那它仍然不能作為安全的 pre-exchange authorization evidence。

Day 27 的目標不是變成 production SMART app。
Day 27 的目標是：

sandbox readiness evidence -> SMART/OAuth token flow boundary evidence

也就是說，今天新增的是「可檢查的 sandbox OAuth token evidence」：

• 不是完整 SMART launch。
• 不是 authorization-code redirect UI flow。
• 不是 refresh token management。
• 不是 production SMART app registration。
• 不是 live Patient / Observation / DiagnosticReport read/search executor。
• 不是 Bundle submitter。
• 不是把 token、FHIR response 或 validation history 寫進資料庫。
• 而是先讓 report 能證明：token endpoint guard、token request guard、scope evidence、token masking policy 已經存在。

例如同一份 Bundle 進來時，Day 27 的判斷會是：

這讓 report 可以明確說明：

SMART/OAuth sandbox token flow evidence 已能 request-scoped 產生。
但目前只展示 token boundary evidence，不做完整 SMART client，也不執行 live resource read/search。

今天的實作範圍

Day 27 的 request / report flow 變成：

使用者上傳或貼上 Bundle
   │
   ├─ 執行原本 JSON / FHIR / TW Core / contract rules
   │
   ├─ terminology server evidence
   │     ├─ ValueSet/$expand
   │     └─ ValueSet/$validate-code
   │
   ├─ live FHIR metadata evidence
   │     └─ GET {FHIR_BASE_URL}/metadata
   │
   ├─ sandbox readiness evidence
   │     ├─ non-PHI preflight
   │     ├─ sandbox auth boundary
   │     ├─ CapabilityStatement interaction declarations
   │     └─ SMART/OAuth sandbox token evidence
   │           ├─ token endpoint allowlist
   │           ├─ token request enabled / disabled
   │           ├─ client auth mode evidence
   │           ├─ requested scopes
   │           ├─ granted scopes
   │           ├─ token type / expires_in
   │           ├─ token hash only
   │           └─ token retention policy
   │
   ├─ PHI masking / privacy evidence
   │     ├─ masking policy version
   │     ├─ masked field categories
   │     ├─ masking check result
   │     ├─ raw Bundle policy
   │     └─ retention policy = request-scoped only / no persistent history
   │
   └─ AuditEvent / Provenance resource preview
         ├─ input SHA-256
         ├─ selected contract id/version
         ├─ gate outcome
         ├─ rule count
         ├─ terminology status
         ├─ metadata status
         ├─ sandbox status
         ├─ PHI masking status
         └─ generation policy = generated request-scoped only; not persisted; not submitted

最後 Quality Test Report 的 evidence layer 變成：

Quality Gate blocking result
   ├─ FHIR / TW Core / contract local rules
   ├─ Terminology server evidence
   ├─ Live FHIR metadata evidence
   ├─ Sandbox readiness evidence
   │    ├─ CapabilityStatement interaction declarations
   │    └─ SMART/OAuth sandbox token evidence
   ├─ PHI masking / privacy evidence
   └─ AuditEvent / Provenance resource preview evidence
        ├─ AuditEvent JSON preview
        ├─ Provenance JSON preview
        └─ generation policy

SMART/OAuth token evidence 做到哪裡？

Day 27 新增的是 sandbox token flow evidence，不是 full SMART/OAuth implementation。

它會記錄：

• OAuth token status。
• token endpoint URL。
• token request enabled。
• token endpoint allowlist status。
• token endpoint called。
• token received。
• client auth mode。
• token type。
• expires_in。
• token SHA-256 hash。
• requested scopes。
• granted scopes。
• token retention policy。
• token safety evidence。
• token evidence statement。

目前支援的最小 token request 是：

grant_type=client_credentials

支援的 client auth mode evidence 包含：

• none
• client_secret_basic
• client_secret_post

這個 layer 的定位是：

report-visible OAuth token boundary evidence
不是 production SMART launch / authorization workflow

原因是 Day 27 還沒有 authorization-code redirect UI、SMART launch context、refresh token rotation、operator identity、consent scope enforcement、production app registration，也沒有 live resource execution policy。

Token masking / retention 邊界維持什麼？

Day 27 不把 raw access token 或 client secret 顯示在頁面。

token 可以在 request scope 內被 HTTP client 用來確認 sandbox token endpoint response shape，但 validation 完成後，report 使用：

• token endpoint URL。
• client auth mode。
• requested scopes。
• granted scopes。
• token type。
• expires_in。
• token SHA-256 hash。
• token retention policy。
• status evidence。

它不應輸出：

• raw access token。
• client secret。
• refresh token。
• raw token endpoint credentials。
• Patient / Observation / DiagnosticReport live response。
• raw Bundle JSON。

Token retention policy 明確顯示：

request-scoped only; token value is not displayed, persisted, or submitted

這表示目前版本仍然不會把 uploaded Bundle、token value、client secret、terminology response、FHIR metadata response、sandbox response、AuditEvent、Provenance 或 PHI 寫進資料庫，也不會送到外部 FHIR server。

今天新增 / 調整的主要類別

• SandboxOAuthTokenResult
• SandboxOAuthTokenService
• SandboxOAuthTokenHttpClient
• DefaultSandboxOAuthTokenHttpClient

SandboxFhirProperties 新增 OAuth token flow 設定：

• allowedOauthTokenUrls
• oauthTokenUrl
• oauthTokenRequestEnabled
• oauthClientAuthMode
• oauthClientId
• oauthClientSecret
• oauthScopes

SandboxFhirEndpointGuard 新增 token endpoint guard：

• token endpoint URL 必須使用 http 或 https。
• token endpoint URL 不可含 userinfo。
• token endpoint URL 不可含 query string。
• token endpoint URL 不可含 fragment。
• token endpoint URL 必須有 host。
• token endpoint URL 必須符合 token endpoint allowlist。
• 預設不允許 localhost、private network、link-local network 或 metadata IP。

SandboxFhirPreflightResult 新增：

• oauthTokenResult

SandboxFhirPreflightService 調整：

• sandbox base URL allowlist、auth mode、non-PHI guard 會一起決定 token flow 是否可被評估。
• token flow evidence 與 CapabilityStatement interaction declaration evidence 同屬 sandbox readiness evidence。
• 即使 token flow NOT_EVALUATED，也不改變 final Quality Gate blocking result。

index.html 調整：

• Layer summary 新增 SMART/OAuth sandbox token evidence。
• Sandbox readiness evidence 詳細區新增 token endpoint、token request enabled、token endpoint allowed/called、token received、client auth mode、token type、expires_in、token hash、requested/granted scopes、token retention policy、token safety evidence、token evidence。

Endpoint safety 設定

Day 27 新增的預設設定是全部關閉：

qualitygate.fhir.sandbox.allowed-oauth-token-urls=
qualitygate.fhir.sandbox.oauth-token-url=
qualitygate.fhir.sandbox.oauth-token-request-enabled=false
qualitygate.fhir.sandbox.oauth-client-auth-mode=none
qualitygate.fhir.sandbox.oauth-client-id=
qualitygate.fhir.sandbox.oauth-client-secret=
qualitygate.fhir.sandbox.oauth-scopes=

這代表預設狀態是：

SMART/OAuth token evidence = NOT_EVALUATED
HTTP token endpoint = not called

若要啟用 sandbox token evidence，至少需要：

• sandbox base URL allowlist。
• sandbox auth mode 不是 none。
• 使用者確認 synthetic / non-PHI test data。
• token endpoint URL。
• token endpoint allowlist。
• token request enabled。
• client auth mode 與必要 credentials。
• requested scopes。

測試重點

今天新增 / 更新測試確認：

• token endpoint 未設定時，OAuth evidence NOT_EVALUATED，HTTP client 不被呼叫。
• token endpoint 不在 allowlist 時，OAuth evidence NOT_EVALUATED，HTTP client 不被呼叫。
• sandbox auth mode 為 none 時，token flow 不執行。
• non-PHI guard 未通過時，token flow 不執行。
• token endpoint 回傳 access token 時，report evidence 顯示 PASSED、token type、expires_in、requested scopes、granted scopes、token hash。
• token endpoint 回傳 access token 時，不顯示 raw access token。
• token endpoint 回傳 HTTP error 時，OAuth evidence NOT_EVALUATED，不讓 local Quality Gate 崩潰。
• token endpoint 回傳 invalid JSON 時，OAuth evidence NOT_EVALUATED，不顯示 client secret。
• report UI 顯示 SMART/OAuth sandbox token evidence。
• report UI 顯示 token retention policy。
• 既有 sandbox /metadata preflight 仍然只呼叫 /metadata，不呼叫 Patient / Observation / DiagnosticReport endpoint。

目前測試結果：

Tests run: 110, Failures: 0, Errors: 0, Skipped: 0

Day 27 完成後的邊界

完成後，專案的定位變成：

pre-exchange quality gate
   ├─ FHIR / TW Core validation
   ├─ partner contract rules
   ├─ contract lifecycle / compatibility
   ├─ unit normalization evidence
   ├─ terminology server evidence
   ├─ metadata preflight
   ├─ sandbox readiness evidence
   │    ├─ CapabilityStatement interaction declarations
   │    └─ SMART/OAuth token flow evidence
   ├─ formal PHI masking / privacy evidence
   └─ request-scoped AuditEvent / Provenance preview

但它不是：

• production exchange platform。
• full SMART/OAuth client。
• SMART launch app。
• authorization-code redirect UI。
• refresh token manager。
• live resource read/search executor。
• Bundle submitter。
• persistent audit log。
• external FHIR AuditEvent / Provenance writer。
• PHI repository。
• production de-identification / pseudonymization engine。
• retention deletion workflow。

下一步

之後預計從 Day 27 的 SMART/OAuth token flow evidence 往下做：

• non-PHI test patient fixture / workflow。
• allowlisted live Patient / Observation / DiagnosticReport read/search execution checks。
• external FHIR AuditEvent / Provenance write policy。
• database-backed persistent history。
• retention deletion workflow。
• deeper terminology governance，例如 inactive code policy、CodeSystem version、UCUM algebra。

Repository：twcore-data-quality-gate