原生 App OAuth（Google）

HSystem 支援原生 App 以 Google SDK 或 系統瀏覽器 / Custom Tab + PKCE 整合，無須整頁嵌入 hosted 登入。

兩條路徑

| 路徑 | 適用 | 入口 | |------|------|------| | A — SDK Exchange | iOS／Android 官方 Google Sign-In | POST {{api_base}}/oauth/google/exchange | | B — 瀏覽器 PKCE | Custom Tab／ASWebAuthenticationSession | GET {{api_base}}/oauth/google/start（與 Web 相同，可加 response_mode=code） |

> 平臺仍使用統一 GOOGLE_*；bind-first 規則不變。

redirect_uri

與 Web OAuth 共用 App 設定的 redirect_uris 白名單。
原生可填自訂 scheme，例如 myapp://oauth/callback。
須與請求中的 redirect_uri 完全一致（含尾斜線）。

response_mode

| 值 | 成功回傳 | |----|----------| | session（預設） | HSystem 平台 JWT（end_user），App 可再呼叫 /oauth/authorize | | code | 直接回 OAuth 授權碼（需已完成 consent／補資料） |

POST /oauth/google/exchange

{
  "client_id": "hs_xxx",
  "redirect_uri": "myapp://oauth/callback",
  "state": "app-state",
  "code_challenge": "…",
  "code_challenge_method": "S256",
  "response_mode": "code",
  "id_token": "eyJ…"
}

id_token 與 google_code 二選一。SDK 整合建議使用 id_token。

成功

{ "status": "ok", "response_mode": "code", "code": "…", "state": "…" }

或

{ "status": "ok", "response_mode": "session", "session": "eyJ…" }

待續（WebView）

{
  "status": "pending",
  "next_step": "consent",
  "session": "eyJ…",
  "hosted_url": "https://…/hosted/consent?…",
  "authorize_params": { "client_id": "…", "redirect_uri": "…", "response_mode": "code" }
}

以 WebView 開啟 hosted_url；使用者完成後呼叫 resume。

POST /oauth/google/resume

{
  "client_id": "hs_xxx",
  "redirect_uri": "myapp://oauth/callback",
  "state": "…",
  "code_challenge": "…",
  "code_challenge_method": "S256",
  "response_mode": "code",
  "session": "eyJ…",
  "consent": "1"
}

WebView 若已導向帶 consent=1 的 authorize URL，App 可在 resume 時帶 "consent": "1"。

常見錯誤

| code | 說明 | |------|------| | google_oauth_not_bound | Google 尚未在 /account 綁定 | | invalid_id_token | id_token 驗簽失敗 | | invalid_google_code | google_code 換 token 失敗 | | google_oauth_not_configured | 平臺未配置 GOOGLE_* |

瀏覽器 PKCE（路徑 B）

GET {{api_base}}/oauth/google/start
  ?client_id=…
  &redirect_uri=myapp://oauth/callback
  &state=…
  &code_challenge=…
  &code_challenge_method=S256
  &response_mode=code

完成 Google 登入後，若可直接發碼會 redirect 至 myapp://…?code=…；否則 redirect 至 hosted 中間頁。