跳到內容
Turing Space TCS

保管模式 vs 非保管模式

挑端點之前，先決定你要對接哪一種運作模式。模式只改變一件事：誰扮演 Holder 角色。 其他一切 — Issuer 流程、Verifier 流程、治理、標準 — 都一樣。

多數 TCS 部署跑保管模式，我們也推薦多數整合者選保管模式。 Holder Service 之所以存在，就是因為多數整合 digital identity wallet 的產品都需要一個方便好用的雲端錢包服務 — 選保管模式你直接拿到一個，不用自己實作 OID4VCI / OID4VP。如果不確定哪個適合你，就選保管模式。

一句話差異

Section titled “一句話差異”
模式誰扮演 Holder你會呼叫的 TCS service
保管模式TCS Holder Service — 一個以 REST API 暴露的託管錢包Issuer Service + Holder Service + Verifier Service
非保管模式end-user 自己的錢包 App（任何符合 OID4VCI/OID4VP 規範的錢包）Issuer Service + Verifier Service。錢包在 user 裝置上，你不會呼叫它。

保管模式下，你的後端透過 TCS API 驅動 IHV 全部三個角色。非保管模式下你只驅動兩個（Issuer、Verifier），Holder 在 user 裝置上、用 deep-link / QR 跟 TCS 對話。

快速開始 走完整的 保管模式 流程。如果你的目的是這個，先快速掃過本頁建立心智模型，然後直接跳到 Quick Start —— 之後需要對照時再回來看。

Holder Service 是託管錢包，不是 SDK

Section titled “Holder Service 是託管錢包，不是 SDK”

保管模式裡最重要的觀念：

Holder Service = 一個由 TCS 託管、以 REST API 暴露的錢包。

它不是你嵌入產品的 library，也不是你導向過去的 UI。它是一個 HTTP service，代表你的 end user 執行錢包該做的所有事情：

  • 保管 end-user 帳號與金鑰對
  • 解析 issuer 的 offer 與 verifier 的 authorization request
  • 產出 proof JWT 與 key-binding JWT
  • 決定要揭露哪些 disclosure
  • 用正確的 payload 呼叫 Credential Issuer / Verifier Service
  • 儲存收到的憑證，並提供列／取／刪 API

你的後端拿著（登入時 Holder Service 簽發的）每位使用者的 JWT，呼叫 /v1/oid4vci/*、/v1/oid4vp/*、/v1/did/*、/v1/vc/*，代替使用者操作。你完全不需要自己手刻任何 OID4VCI / OID4VP payload。

非保管模式下整個這層 API 就消失了 — 同樣的事改由 user 的錢包在本地做，並直接跟 Issuer Service + Verifier Service 對話。

拓樸

Section titled “拓樸”
保管模式                                            非保管模式
─────────────────                                   ─────────────────
[你的後端]                                          [你的後端]
   │                                                   │
   ├──► Issuer Service        (POST /v1/offers)        ├──► Issuer Service        (POST /v1/offers)
   ├──► Holder Service        (完整錢包 API)            │      ↓ 透過 QR / deep-link 把 offer 給 user
   └──► Verifier Service      (auth-request / result)  │
                                                       ├──► Verifier Service      (auth-request / result)
                                                       │      ↓ 透過 QR / deep-link 把 request 給 user
                                                       ▼
                                                  [User 的錢包 App]
                                                  在 end user 的裝置上
                                                  （任何符合 OID4VCI/OID4VP 的錢包）

兩種模式共用同一套治理層（Trust Registry、Schema Registry），與同一種 wire format（SD-JWT VC，dc+sd-jwt）。

為什麼 TCS 要提供 Holder Service

Section titled “為什麼 TCS 要提供 Holder Service”

多數整合 digital identity wallet 的系統，都需要一個方便好用的錢包服務 — 一個讓憑證有地方存、protocol 細節有人處理、使用者錢包能用 API 大規模管理的服務。多數團隊不想自己做，更不想自己維護。

Holder Service 就是這個服務。 它是一個通用的雲端錢包管理 API：任何需要「可驗證憑證錢包」能力的產品，都可以用 Holder Service 而不用接 OID4VCI / OID4VP。它不是「TCS 發行流程的 holder 那一半」 — 它是一個獨立的錢包服務，剛好跟發行端、驗證端一起部署。

即使 end user 手機上已經有錢包 App，Holder Service 仍然是「在你產品裡發出的憑證」最方便的歸宿 — 使用者不必再裝一個錢包，你的產品保留乾淨的 API 來列出、出示、撤銷這些憑證。

如果你曾經問過「我這些 user 的可驗證憑證該放哪？怎麼讓出示憑證這件事不痛苦？」 — 答案就是 Holder Service。

兩種模式各做什麼

Section titled “兩種模式各做什麼”
範疇保管模式非保管模式
End-user 帳號你呼叫 Holder Service 的 POST /v1/user/register錢包 App 自己管理
Holder DID + 金鑰你呼叫 POST /v1/did 為每位 user 建 DID。回傳的私鑰由你保存。錢包自己產生並保管
收憑證你的後端呼叫 POST /v1/oid4vci/receive，傳 offer URI + holder DID + 私鑰錢包自己換 token、組 proof JWT、打 /credential
列／管理憑證你的後端呼叫 GET /v1/vc、DELETE /v1/vc/:id錢包在本地顯示、儲存
出示憑證你的後端呼叫 POST /v1/oid4vp/request-details 與 POST /v1/oid4vp/presentation錢包自己組 VP token 與 key-binding JWT
錢包 UI你在自己的產品裡實作同意、選擇憑證的畫面user 的錢包 App 已經有

Holder 金鑰放在哪

Section titled “Holder 金鑰放在哪”

Holder Service 不持久化 holder 私鑰。私鑰只在建 DID 時回傳一次，請求結束後伺服器端就丟掉。這是安全特性，不是摩擦 — 私鑰從來不在 TCS 的基礎設施內，只在你的 secret manager / KMS 裡，跟你產品中其他每位 user 的 secret 一樣（session 簽章金鑰、tenant API token、加密欄位等）。

實務上：

  1. POST /v1/did 回傳時就把 end-user 的 DID 私鑰存起來。 視同任何每位 user 的 secret — secret manager、KMS、加密欄位都行。後續每次呼叫 /v1/oid4vci/receive 與 /v1/oid4vp/presentation 都要把它傳回去。
  2. 登入時拿到的 Holder Service JWT 是該位 user 的 session token。
  3. End-user 身分資料。 Holder Service 存帳號，但只會看到你主動傳的東西。

你不需要自己建構、簽、或驗任何加密 payload。Holder Service 用你呼叫時傳入的私鑰做完所有 crypto，請求結束後丟掉。

結果：TCS、你的產品、end user 都只看到自己該看到的東西。可驗證憑證跟金鑰素材住在它們該在的位置 — 這是設計帶來的特性，不是你要自己強制執行的事。

何時選哪個

Section titled “何時選哪個”

選保管模式（推薦），如果：

  • 你在把 digital identity wallet 整進產品，想要一個服務替你處理錢包端機制。多數團隊都是這種。
  • End user 還沒有 digital wallet — 也不會去裝。
  • 你想要單一整合介面、單一營運面、可以用 API 列出 / 稽核 / 救援的憑證紀錄。
  • 即使 end user 有別的錢包 — Holder Service 仍是「在你產品裡發出的憑證」乾淨的雲端歸宿。

選非保管模式，如果：

  • 你已經自己實作或對接了 OID4VCI / OID4VP 錢包，再用 Holder Service 等於做兩次。
  • 你的目標 user 在已建立的 digital wallet 生態系（HAIP-conformant 錢包、EUDI Wallet、政府 identity 錢包），你是要接進那個生態系而非在自己產品內做。
  • 你正在做自己的錢包 App，TCS 只負責發行 / 驗證的邊界。

簡單講：選非保管模式的典型情況就是「你已經熟 OID4VCI / OID4VP，並且有現成的錢包實作要繼續用」。 否則 Holder Service 幾乎都能省下你工作量。

兩種模式可以在同一套 TCS 部署上、針對不同 tenant 並存 — 模式選擇不會綁死平台。不確定就選保管模式，先把產品出貨；之後若有特定 user case 需要非保管，再加一個 tenant 就好。

文件其餘部分如何組織

Section titled “文件其餘部分如何組織”

Development 指南都以保管模式為預設：

跑保管模式的話可以直接跳過非保管模式那頁 — 對你的整合沒影響。

接下來

Section titled “接下來”