以 FIDO2 金鑰為身分根(不需第三方登入)、Passkey 與 CAFECA 卡操作的智能合約錢包,整合端對端加密聊天、聊天內支付、AI 子錢包與 Visa 支出通道。部署在 Boltchain 測試網(chainId 8018)。
需要 Node.js 24.22.1(repo 根目錄的 .nvmrc/.node-version;用 nvm 時在 repo 內執行 nvm install && nvm use)。
npm install # 會一併下載 MediaPipe 臉部模型到 public/mediapipe(npm run fetch-models 可重跑)
# 1. 第一次執行:自動產生部署者私鑰與所有服務金鑰(寫入 .env.local),並印出部署者地址
npm run deploy
# 2. 轉入至少 8 BOLT 到印出的部署者地址,再執行一次即開始部署
npm run deploy
npm run dev # http://localhost:10002
npm run demo:signin # 選用:第三方登入範例網站 http://localhost:10003IdentityRegistry v2(規格 §16.2):已經部署過的環境執行 npm run deploy -- --identity,只增量部署 v2、把 v1 仍有效的證明遷移過去,並重新部署改讀 v2 的 paymaster(會取回舊 paymaster 的押金,需要約 6.5 BOLT)。工廠與 KeyringValidator 不動,既有身分地址不變。完成後重新啟動 npm run dev/npm start。
- 身分恢復執行後,由
POST /api/identity/sync重新簽發或暫停 v2 證明。恢復頁面會自動觸發;正式環境請再加排程(例如每 5 分鐘curl -X POST https://<網域>/api/identity/sync)。 - 部署在反向代理後方時設定
PUBLIC_ORIGIN=https://<網域>;公開 RPC 預設為<PUBLIC_ORIGIN>/api/rpc,可用PUBLIC_RPC_URL覆寫。 KYC_SIGNER_CLASS=PRODUCTION只在正式 KYC 後台上線、換上 HSM 金鑰後使用;原型期維持預設(PROTOTYPE)。
已經部署過、之後合約有變更(例如 v0.3 金鑰模型)時,npm run deploy 會補上缺少的服務金鑰(GUARDIAN_ROOT_KEY、GUARDIAN_SEED)並整套重新部署;舊身分不會搬到新合約,需重新建立。只改了工廠合約時可用 npm run deploy -- --factory。
Passkey 需要安全環境:本機請用 http://localhost:10002,其他網域須為 https。
在伺服器的 app 目錄執行一個指令即可(可重複執行,已完成的步驟會略過):
PUBLIC_ORIGIN=https://cafeca.io npm run deploy:server依序完成:
- 確認 Node.js 為
.nvmrc指定的 24.22.1(有 nvm 時自動安裝並切換,否則停止) - 安裝
ffmpeg(apt/dnf/yum/apk/brew,需要 sudo) git pull --ff-onlynpm install(含 MediaPipe 與 KYC 模型,約 140 MB,需能連 huggingface.co).env.local:寫入PUBLIC_ORIGIN;沒有KYC_REVIEW_TOKEN(建立第一位管理者用)就產生一組;提醒開發用旗標,CAFECA_MODE=production時上線閘門不通過就停止- 尚未部署 IdentityRegistry v2 時執行
npm run deploy -- --identity(部署者需約 6.5 BOLT) npm run build(合約地址在建置時寫入)- 重新啟動:有 pm2 用
pm2 restart cafeca(沒有就pm2 start npm --name cafeca -- start),或SYSTEMD_UNIT=<服務名>改用 systemctl - crontab 每 5 分鐘呼叫
POST /api/identity/sync - 檢查
/.well-known/cafeca-configuration的issuer、chain.rpc、contracts.identityRegistry
選項:SKIP_PULL=1、SKIP_IDENTITY=1、SKIP_CRON=1、PM2_NAME=<名稱>、SYSTEMD_UNIT=<服務>、PORT=<npm start 的埠,預設 10002>。
第一次部署(還沒有 .env.local)請先照上面「啟動」執行 npm run deploy 產生金鑰並部署合約。
健康檢查與自動修復:在 repo 根目錄執行 shell/auto_redeploy.sh。系統正常就不處理;異常時依序嘗試修復:
| 檢查 | 自動修復 |
|---|---|
錢包服務回應、設定檔含合約位址、/start//wallet//admin 可開啟 |
重新啟動 → 重新建置後啟動 → npm ci、建置後啟動(建置不存在或比程式碼舊時直接重新建置) |
事件索引 5 分鐘沒有進度且落後超過 INDEX_MAX_LAG 區塊 |
重新啟動 → 索引資料移到 data/index.broken-<時間> 重新同步 |
| 排程(身分同步、法人監控、每日維護) | 重新寫入 crontab |
| KYC 模型 | npm run fetch-models |
磁碟使用率超過 DISK_MAX_PCT |
清除 .next/cache |
| 對外網址 | 反向代理(nginx/caddy/apache)沒有執行時啟動它 |
| 鏈 RPC、ffmpeg、paymaster 押金與營運錢包餘額 | 不自動處理,只發出警示 |
shell/auto_redeploy.sh --check只檢查不修復;--install-cron每 5 分鐘自動執行,--uninstall-cron移除。- 設定
ALERT_WEBHOOK(Slack/Google Chat/Discord 相容)就會在修復或需要人工處理時通知;同一則持續異常 1 小時內只通知一次、餘額偏低 6 小時一次。 - 一小時內自動修復超過
MAX_REPAIRS_PER_HOUR(預設 3)次就停止修復,只發警示,避免反覆重啟。 - 不會
git pull、部署或變更合約、移動資金、修改金鑰;要套用新程式仍用npm run deploy:server。 - 紀錄在
app/data/auto-redeploy/。其他選項(PORT、PM2_NAME、SYSTEMD_UNIT、門檻值)見腳本開頭說明。
| 頁面 | 功能 | 規格章節 |
|---|---|---|
/ |
Landing page:數位身分證是什麼、為什麼需要、怎麼使用、三種金鑰與備援金鑰被盜的緩解、FAQ | — |
/start |
建立身分:在裝置建立 FIDO2 金鑰 → 地址=CREATE2(公鑰) → 一筆 UserOp 完成部署+登記聊天裝置;裝置已有金鑰則直接登入 | §3、§4.4 |
/link |
新裝置加入既有身分:建立金鑰 → 配對碼/QR → 在已登入的裝置確認,所有裝置金鑰同級 | §4.2 |
/kyc |
實名驗證:身分證件照片+引導式臉部影像(轉頭、眨眼、念隨機數字)→ 送出後顯示送出的證件與審核進度(不顯示臉部影片)(審核中不能重送,退件才能重拍)→ L2 證明 → 安裝平台備援金鑰 | §3.4、§5.3 |
/wallet |
TWDC 與 BOLT 餘額、轉帳(即時預覽需要手機或卡片)、收款 QR、測試幣、額度、紀錄;BOLT 預設可轉帳:新版工廠開戶時即設定平台預設 BOLT 額度(每筆 10、每日 50 BOLT,部署時讀 NATIVE_DEFAULT_PER_TX/NATIVE_DEFAULT_DAILY);舊工廠建立、BOLT 額度為 0 的帳戶可在錢包內啟用(v2 由管理者帳戶代為設定;v1 由帳戶自己設定,綁卡即時、否則排程 72 小時,bundler 只放行這一種自行設定) |
§4.3 |
/card |
完成 KYC 後付費購買實體卡(TWDC 付款給發卡方)→ 綁定、掛失補發、Visa 通道、POS 刷卡模擬 | §4.5、§6.4、§9 |
/agents |
AI 代理與支出通道、x402 商家購買、超額 intent 以卡片核准、撥款、撤銷 | §6 |
/chat |
「+」選單:轉帳、收款、相機、檔案(10 MB 內,本機加密後才上傳)、分享位置(確認後才送出);代稱(第一次設定免費、之後固定,變更需付 150 TWDC,舊代稱保留)、裝置金鑰上鏈、E2EE 訊息、付款請求與聊天內付款、AI 核准通知 | §7 |
/security |
資料調閱紀錄(誰依什麼依據調閱了哪些實名資料,當事人同意類以 Passkey 回覆)、裝置金鑰(同級、可互相移除)、實體卡與平台備援金鑰(不可移除)、連結其他裝置、額度(唯讀)、恢復狀態與取消、登出 | §4、§5 |
/company |
公司帳戶:建立(你成為第一位管理者)、以統編申請商工登記驗證(代表人本人自動通過,否則上傳授權書)、成員(管理者/經辦)、代公司轉帳;登入網站時可選「以公司身分」 | §16.4 |
/admin/entity |
法人驗證人工複核:商工登記資料、申請人與代表人比對、授權書;核准後簽發法人證明 | §16.4 |
/admin |
管理後台首頁:以人員 Passkey 登入,依角色列出功能;/admin/staff 人員管理(邀請、角色、Passkey、停用),/admin/join 受邀者加入 |
§16.6 P3 |
/admin/rp |
依賴方登記:名稱、統編、網域、法遵聯絡人、加密公鑰;API 金鑰只在建立時顯示一次;可停用 | §16.6 P2 |
/admin/disclosures |
資料調閱雙人覆核:法律依據、客戶關係證明、當事人同意、資料預覽;第一位核准欄位、第二位(不同人)放行或退件 | §16.6 P2 |
/admin/audit |
稽核紀錄(hash-chained):查詢與整條鏈驗證,竄改或刪除任一筆都會指出位置 | §16.6 P2 |
/admin/limits |
交易額度管理(只給管理者):查詢帳戶額度與今日已用、調升或調降(原因碼+備註必填)、鏈上調整紀錄 | §4.3 |
/dl/auth |
Sign in with CAFECA:第三方網站免註冊登入(彈出視窗/整頁導向/跨裝置 QR),顯示網域與第一次連線提醒、可取消提供的資料;/security 列出登入過的網站。串接說明見根目錄 README |
§15 |
/dl/sign |
簽章通道:登入時同意開啟後,網站可請你簽署訊息、EIP-712 或付款;並列顯示網站說明與錢包解析的實際內容,逐筆確認;跨裝置經加密中繼,錢包開啟時跳出提示;/security 可關閉通道 |
§15.8 |
/recover |
找到身分 → 新裝置建立金鑰 → 實體卡立即新增,或以證件+臉部影像讓平台備援金鑰發起恢復(48h/有卡 7 天) | §5 |
瀏覽器
├─ Passkey(WebAuthn,裝置金鑰:每台裝置同級)
├─ 卡片模擬器(WebCrypto 不可匯出 P-256,實體卡金鑰,CTXD 螢幕確認)
├─ 聊天裝置金鑰(ECDH P-256 → AES-GCM)
└─ /api/rpc(唯讀 RPC 代理)
Next.js Route Handlers(伺服器)
├─ /api/bundler 組 UserOp、paymaster 簽章、handleOps 送出
├─ /api/auth ERC-1271 登入挑戰 → session cookie
├─ /api/signin /.well-known/cafeca-configuration(第三方登入探索文件)
├─ /api/identity 恢復後的實名證明同步(IdentityRegistry v2 重新簽發或暫停)
├─ /api/channel 簽章通道中繼信箱(只存端對端加密的密文)
├─ /api/issuer 發卡方簽署卡片證明
├─ /api/kyc 模擬 KYC 單位(證件+臉部影像、活體挑戰)
├─ /api/recovery 平台備援金鑰(模擬 HSM):重新驗證本人後簽署恢復
├─ /api/card 實體卡訂單(核對鏈上付款)
├─ /api/visa 模擬發卡處理商(authorize/capture)
├─ /api/agent AI 代理(規則式,金鑰代表 TEE)
├─ /api/merchant x402 商家
└─ /api/chat 密文轉存
Boltchain 測試網:EntryPoint v0.8 + CAFECA 合約(../contracts)
| 項目 | 測試網做法 | 正式版 |
|---|---|---|
| 身分建立防濫用 | 每 IP 每日 10 個身分(MAX_IDENTITIES_PER_IP_PER_DAY) |
裝置認證(App Attest/Play Integrity)+Redis |
| CAFECA 卡 | 瀏覽器卡片模擬器 | 實體卡(安全晶片驅動電子紙) |
| KYC 擷取 | 證件即時拍攝(引導框偵測、自動拍攝、裝置端浮水印)+6 動作活體(MediaPipe 臉部特徵點);上傳只有浮水印版 | 同左,並加原生 App 裝置認證 |
| KYC 後台 | 自建驗證已接上(OCR、活體重檢、語音、人臉比對、證號重複);自動通過預設關閉,全部轉人工複核 /admin/kyc |
以真實樣本校準門檻後開啟 KYC_AUTO_APPROVE=1;補翻拍/深偽分類器、ISO 30107-3 送測、領補換查詢 |
| 平台備援金鑰 | 由 GUARDIAN_SEED+帳戶地址衍生 |
每帳戶於 HSM 內產生、不可匯出,簽署需雙人覆核 |
| 平台根金鑰 | .env.local 的 GUARDIAN_ROOT_KEY |
離線冷儲存(多簽) |
| 重新 KYC 恢復 | 新裝置重新即時拍證件+6 動作活體;統一編號 HMAC 相同且人臉相似度 ≥ 0.45 才發起恢復,否則轉人工 | 同左,並加原生 App 裝置認證 |
| KYC/Visa | 模擬 | 持照 KYC 單位、發卡處理商 |
| AI 代理金鑰 | 伺服器 data/store.json |
TDX enclave |
| 聊天 | ECDH+AES-GCM | MLS(RFC 9420) |
| 資料儲存 | data/store.json |
資料庫 |
| Bundler | 內建(不套用 ERC-7562 限制) | 獨立 bundler 或原生 AA |
npm run typecheck
npx eslint src
npm run build合約 ABI 在 src/lib/contracts/abis.ts,部署用 bytecode 在 scripts/artifacts/,都由 ../contracts 編譯產生。
證件與臉部影像只在自己的伺服器上以 onnxruntime-node 推論,不送往任何第三方;只處理浮水印版影像。
| 模組 | 做法 | 模型(Apache-2.0,由 npm run fetch-models 下載到 models/kyc,約 140 MB) |
|---|---|---|
| 證件 OCR | 文字偵測+辨識 → 依標籤列取姓名、出生日期、性別、發證日期、住址(「出生/年月日」上下兩行的標籤依版面位置判斷);統一編號以檢查碼驗證,容許常見誤讀(O/0、I/1、S/5、B/8),讀不到時把右下角放大兩倍重讀 | PP-OCRv5 mobile(繁簡中文) |
| 欄位合理性 | 檢查碼、性別與統一編號第二碼、日期範圍 | — |
| 活體重檢 | 影片每秒 8 格:YuNet 找臉 → 478 點特徵 → 與裝置端相同公式的頭部轉向、眼睛與嘴巴開合;逐一核對 6 個動作在裝置回報的時間窗內真的出現 | YuNet、MediaPipe 臉部 478 點(與裝置端同一份權重的 ONNX 版) |
| 念數字 | 只取念數字那段音訊,Whisper 辨識後比對 4 位數字(中文、大寫數字、英文都可)。只錯一碼時,若其餘活體動作、單一人臉與人臉比對都通過即接受(KYC_SPEECH_PARTIAL_OK=0 可關閉) |
Whisper base(int8) |
| 人臉比對 | 影片最正面的一格 vs 證件照,SFace 餘弦相似度 | YuNet、SFace |
| 證號重複 | 統一編號 HMAC 是否已綁定其他 CAFECA 身分 | — |
決策
- 明確不是同一人(相似度 < 0.15)或影片中幾乎沒有臉 → 退件,使用者可重拍。
- 全部通過且相似度 ≥
KYC_AUTO_FACE(預設 0.45),並且KYC_AUTO_APPROVE=1→ 自動通過。 - 其他一律轉人工複核。
KYC_AUTO_APPROVE預設關閉:門檻用真實(經同意的)樣本校準前,所有案件都由人審,複核紀錄與分數就是校準資料。
人工複核後台 /admin/kyc:需要「KYC 與法人複核」角色(見下方「管理後台人員」)。可以看到浮水印版證件、臉部影片、每項檢查、擷取欄位、分數與 OCR 原始文字(統一編號已遮罩),然後核准或退件。核准開戶案件時要對照證件確認姓名、出生日期與統一編號:OCR 讀錯的直接改,讀不到統一編號的必須輸入(只存 HMAC,與其他身分重複時不能核准)。已核准的案件可在「更正欄位」修正,必須填寫原因。每次登入、檢視檔案與決策都寫入稽核紀錄 data/audit/audit.jsonl(見下方「稽核紀錄」;P2 以前的舊紀錄留在 data/kyc/review-log.jsonl)。核准開戶案件=寫入 L2;核准恢復案件=以平台備援金鑰發起恢復。
KYC Credential(規格 §16.3):第三方登入要求 legal_name、doc_type、nationality、pairwise_id 時,同意畫面向 /api/kyc/credential 取得由 KYC 簽章者簽署、綁定網站與這次登入 nonce 的 credential(src/server/kyc-credential.ts)。資料來自最新一筆核准案件的擷取欄位。pairwise_id 使用 .env.local 的 KYC_PAIRWISE_KEY(npm run deploy/deploy:server 會自動產生);這把金鑰一旦有網站使用就不能更換,否則所有網站看到的同一人識別碼都會改變。沒有設定時不提供 pairwise_id。
交易額度只能由管理者調整:KeyringValidator v2 的 setLimits 與排程修改額度一律拒絕(實體卡也不行),只有 limitAdmin 能呼叫 setLimitsFor(account, token, perTx, daily, reason),每次調整發出 LimitsSetByAdmin。測試網 limitAdmin=部署者(營運錢包),正式環境請以 transferLimitAdmin/acceptLimitAdmin 移交給多簽。管理後台 /admin/limits 需要「交易額度」角色,每次查詢與調整都寫入稽核紀錄。
已部署的測試網仍是 v1。 v1 的額度寫在使用者帳戶可自行修改的位置,管理者無法調整;目前由 bundler 拒絕贊助任何修改額度的操作(暫時防護,自備 BOLT 直接送交易仍可繞過)。要換成 v2 必須重新部署帳戶相關合約(
npm run deploy,KeyringValidator 與工廠都會換新),既有測試網身分的地址會改變、需要重新開戶。
法人帳戶(規格 §16.4):MemberValidator(成員代簽、額度只能由管理者調整)+EntityAccountFactory。已部署的環境執行 npm run deploy -- --entity 增量部署,不影響既有身分(deploy:server 會自動執行)。商工登記以 data.gcis.nat.gov.tw 查詢(測試可用 GCIS_COMPANY_URL 指向模擬服務),每日監控由排程呼叫 POST /api/entity/sync;/api/entity/sync?force=1 需管理後台登入,立即重查全部法人。
鏈上事件索引(規格 §16.6 P0-d):伺服器持續同步 TWDC 轉帳、金鑰增減、實名證明狀態、恢復、額度調整與法人帳戶事件(src/server/indexer.ts,存在 data/index/,可隨時刪除重建)。錢包紀錄、聊天中的轉帳、「以此裝置的 Passkey 登入」反查身分與管理後台都改讀索引,瀏覽器不再從部署區塊掃描整條鏈(Boltchain RPC 的 eth_getLogs 每次最多 10,000 個區塊)。每次同步把所有合約合併成一個查詢、每段 ≤ 10,000 區塊,並重掃最後 5 個區塊去重;部署位址改變時自動重建。API:GET /api/index/transfers?address=&limit=&before=、GET /api/index/key-accounts?keyId=、GET /api/index/status(deploy:server 會檢查同步落後)。
工商憑證綁定(P1.5 PoC):/company 的「以工商憑證綁定」透過使用者電腦上的 HiPKI 跨平台網頁元件(http://localhost:61161,src/lib/hipki.ts)以 IC 卡簽署 PKCS#7;伺服器 src/server/moeaca.ts 驗證簽章、憑證鏈(內建 GRCA/GRCA G3 根與 MOEACA 第二、三代中繼,src/server/moeaca-anchors.ts)、效期、金鑰用途、憑證政策 2.16.886.101.0.3.3 與分區 CRL,取出統一編號與正卡/附卡。憑證欄位已以 MOEACA 公開下載的真實憑證核對;元件的 postMessage 參數與錯誤碼依公開範例實作,尚待以實體卡片與讀卡機確認。可用 npm run moeaca:inspect -- <憑證.cer> 檢查一張實體卡的憑證,或 --sig <PKCS#7> --tbs <內容> 檢查元件產生的簽章。MOEACA_TEST_ANCHORS 只供自動化測試使用測試 PKI,正式環境不得設定。
管理後台人員(規格 §16.6 P3-A3):/admin 每位人員一個帳號、以自己的 Passkey 登入(與錢包的 Passkey 分開),稽核紀錄的操作人是「姓名(人員 id)」。
- 第一位管理者:還沒有任何啟用中的管理者時,
/admin會要求.env.local的KYC_REVIEW_TOKEN(部署時自動產生),並在這台裝置建立 Passkey。之後這個密碼就不能再登入。升級到這一版後,第一位打開/admin並輸入密碼的人就是管理者,請盡快完成。 - 其他人員:管理者在
/admin/staff產生邀請連結(72 小時、一次性),受邀者在自己的裝置建立 Passkey。遺失裝置時由管理者發「新增 Passkey」邀請,或移除舊的 Passkey、停用帳號。 - 角色:
admin(人員與依賴方管理)、kyc(KYC 與法人複核)、disclosure(資料調閱核准)、limits(交易額度)、audit(稽核紀錄唯讀)。管理者不會自動擁有其他角色;資料調閱需要兩位不同的人員具備disclosure。 - 伺服器端驗證 WebAuthn:challenge(5 分鐘、一次性)、來源網址(正式模式只接受
PUBLIC_ORIGIN)、rpId、使用者驗證旗標與 ES256 簽章。停用與角色調整立即生效。
正式模式上線閘門(P3-A4):.env.local 設定 CAFECA_MODE=production 後,伺服器啟動與 deploy:server 都會檢查,以下任一項存在就拒絕啟動:KYC_PROTOTYPE_AUTO_APPROVE、NEXT_PUBLIC_KYC_SIMULATE、MOEACA_TEST_ANCHORS、GCIS_COMPANY_URL、未校準的 KYC_AUTO_APPROVE(校準後另設 KYC_AUTO_CALIBRATED=1)、非 https 的 PUBLIC_ORIGIN、未設定 CRON_SECRET。可先執行 npm run gate 自行檢查。正式簽章者只會在閘門通過的環境登記。
伺服器金鑰介面(P3-A1):KYC 簽章(Attested/Suspended/Revoked、KycCredential)、資料包 ES256 簽章與 pairwise_id 的 HMAC 一律經過 src/server/keys.ts。KEY_BACKEND=local(預設)從 .env.local 讀金鑰;改用 KMS/HSM 時新增一個實作並在 BACKENDS 註冊,其他程式不用改。KMS 回傳的 secp256k1 簽章多半是 DER、可能是 high-s,請用 secp256k1FromDer 轉換(OpenZeppelin ECDSA 拒收 high-s)。發卡方、備援金鑰根金鑰、paymaster 等其他金鑰尚未移入這個介面。
HSM(PKCS#11,P3-A1):KEY_BACKEND=pkcs11 時,KYC 簽章(secp256k1)、資料包簽章(P-256)與 pairwise HMAC 都在 HSM 內執行,金鑰在 HSM 產生、不可匯出、只能簽章(src/server/keys-pkcs11.ts)。設定:
| 變數 | 說明 |
|---|---|
PKCS11_MODULE |
HSM 廠商的 PKCS#11 函式庫路徑(測試用 SoftHSM:/usr/lib/softhsm/libsofthsm2.so) |
PKCS11_TOKEN_LABEL、PKCS11_PIN |
token(partition)名稱與使用者 PIN |
PKCS11_KYC_SIGNER_LABEL、PKCS11_PAIRWISE_LABEL、PKCS11_DISCLOSURE_LABEL |
目前使用的金鑰 label(由 cutover 自動寫入) |
從 .env.local 的金鑰換到 HSM:先設好 PKCS11_MODULE、PKCS11_TOKEN_LABEL、PKCS11_PIN 與 KEY_BACKEND_NEXT=pkcs11,npm run cutover -- prepare 會在 HSM 內產生下一把簽章金鑰、新的 pairwise 金鑰與資料包簽章金鑰,npm run hsm -- status 檢查每把金鑰存在、不可匯出並做一次簽章自我測試;之後照下面的切換步驟 execute,完成後 .env.local 改為 KEY_BACKEND=pkcs11,明文金鑰移除(備份檔確認後請安全刪除)。正式模式的上線閘門要求簽章金鑰在 HSM。pkcs11js 是 optionalDependency(原生模組,伺服器需要編譯工具),沒有 HSM 的環境安裝失敗也不影響。已用 SoftHSM 完成演練;實體 HSM 請確認廠商支援 secp256k1(CKM_ECDSA 搭配 OID 1.3.132.0.10)。
切換正式 KYC 簽章者(P3-A5):
npm run cutover -- prepare:產生下一把簽章金鑰與新的 pairwise 金鑰(.env.local的NEXT_KYC_SIGNER_KEY、NEXT_KYC_PAIRWISE_KEY),印出新簽章者位址。npm run cutover -- plan:列出會以新簽章者重新簽發的帳戶(案件由自動驗證或人工複核核准;法人經人工或工商憑證驗證),以及需要重新驗證的帳戶(原型期放行)。不送任何交易。npm run cutover -- execute:上線閘門必須通過。依序登記新簽章者為 PRODUCTION(v1、v2)→ 重新簽發 → 標記需要重新驗證並把 v1 降為 L0 → 移除舊簽章者(原型期證明在鏈上降為 L0)→.env.local換成新金鑰(舊檔備份為.env.cutover-<時間>.local)。每一步都可重跑。治理權在多簽時,會印出要由多簽送出的交易,送出後再重跑。- 重新啟動服務。需要重新驗證的使用者在
/kyc會看到提示;pairwise 金鑰一併更換,依賴方先前拿到的pairwise_id全部失效,請事先通知。
本機演練可加 --skip-gate(只允許連到本機 RPC)。
治理權移交多簽(P3-A2):
- 準備 2 到 5 位成員的 EOA(各自保管,建議硬體錢包,不放在伺服器)。
npm run multisig -- deploy --owners 0xA,0xB,0xC --threshold 2:部署CafecaMultisig。npm run multisig -- handover:部署者把 IdentityRegistry 治理權(兩段式)與 AuditAnchor 管理權交給多簽,並產生「多簽接受治理權」的提案檔(data/multisig/)。營運錢包仍是 anchorer,每日上鏈照常。- 各成員在自己的裝置
MULTISIG_SIGNER_KEY=0x… npm run multisig -- sign <提案檔>,達門檻後npm run multisig -- execute <提案檔>。 - 之後登記或移除 KYC 簽章者都要多簽:
npm run cutover -- execute遇到多簽會印出npm run multisig -- propose …,執行、簽署後重跑即可。npm run multisig -- status查看目前狀態。
額度管理權(limitAdmin)預設不移交:/admin/limits 由營運錢包直接調整,移交後後台無法調整。要移交請加 handover --limits。v1 AttestationRegistry 的治理權是 immutable,只能留在部署者(只影響綁卡門檻,依賴方讀 v2)。
依賴方資料調閱(規格 §16.6 P2):依賴方(交易所等)平常只拿得到使用者同意提供的 claims;遇到洗錢防制調查或司法機關調閱,才以這個 API 申請 CAFECA 保存的實名資料(src/server/disclosure.ts)。
-
CAFECA 在
/admin/rp登記依賴方與其 P-256 加密公鑰(對方以npm run rp -- keygen產生,私鑰自己保管),發給 API 金鑰(只存 SHA-256)。 -
依賴方
POST /api/rp/disclosures(Authorization: Bearer cafeca_rp…):{ "account": "0x…", "fields": ["legal_name", "kyc_history", "doc_images"], "legalBasis": { "type": "aml", "ref": "文號", "text": "依據說明" }, "reason": "調閱原因", "caseRef": "內部案號", "signIn": { "…": "該帳戶登入你網站時的 SignIn 回應" } }fields:legal_name、birthday、sex、doc_type、nationality、issue_date、kyc_history、doc_images(浮水印版)、entity(法人統編、名稱、成員、代簽紀錄)。legalBasis.type:court、prosecutor、police、aml、consent。aml與consent必須證明對方是自己的客戶:附上signIn(網域須是登記的網域)或pairwiseId。只有court/prosecutor/police可以帶deferNoticeUntil(一年內)暫緩通知當事人。 -
consent類先由使用者在/security的「資料調閱紀錄」以 Passkey 同意或拒絕(ERC-1271 簽章存證)。 -
複核人員在
/admin/disclosures雙人覆核:第一位核准(可刪減欄位),第二位不同的人放行。 -
依賴方
GET /api/rp/disclosures?id=取得狀態;放行後 7 天內附package:以依賴方公鑰加密的 JWE(ECDH-ES+A256GCM),內容是 CAFECA 以DISCLOSURE_SIGNING_KEY簽章的 JWS(ES256),驗章公鑰公布在/.well-known/cafeca-configuration的disclosure.jwks。參考實作:CAFECA_RP_KEY=… npm run rp -- fetch <錢包網址> <id> rp-key.json out/(解密、驗章、另存證件影像)。 -
使用者在
/security看得到誰、依什麼依據、調閱了哪些欄位;暫緩通知的案件到期後才顯示。
時限、同意期限與資料處理約定(P3-B3/B4):依賴方登記時必須填寫雙方簽署的 DPA 版本與日期,未登記的依賴方 API 回 403(POST /api/admin/rp { id, dpaVersion, dpaSignedAt } 可補登)。每件申請有回應期限 dueAt:洗錢防制與同意類(同意後起算)預設 5 個工作天;司法機關可帶 respondBy(文書所載期限),沒帶則 5 個工作天。同意請求 7 天未回覆即失效(視為不同意)。逾期案件在 /admin/disclosures 標示。
保存期限(P3-B5):未通過的案件、以及被較新核准案件取代的舊案件,180 天後清除證件影像、臉部影片與人臉特徵(保留案件紀錄與檔案雜湊,清除寫入稽核紀錄);目前依據的核准案件、調閱與稽核紀錄不自動刪除。每日排程 POST /api/maintenance(帶 x-cafeca-cron: $CRON_SECRET,deploy:server 會產生密鑰並建立 crontab)同時處理同意逾期。/admin/policy 顯示目前的數值與即將清除的案件。
條款同意版本(P3-B2):服務條款與隱私權告知放在 content/terms/<版本>/{terms,privacy}.md,TERMS_VERSION 指定目前版本(預設草案 draft-2026-09),/terms、/privacy 顯示目前版本與內容雜湊。登入後未同意目前版本(版本號或內容雜湊不同都算)時,App 內頁只顯示條款;使用者以 Passkey 簽署「版本+內容雜湊+帳戶」(ERC-1271 驗證),簽章存證並寫入稽核紀錄,「安全」頁列出同意紀錄。實名驗證送件要求已同意目前版本(未同意回 428)。定稿後新增一個版本資料夾並改 TERMS_VERSION,所有人都會被要求重新同意。
以上天數都是給法律顧問審閱的草案預設值(
src/server/policy.ts),可用DISCLOSURE_SLA_AML_DAYS、DISCLOSURE_SLA_AUTHORITY_DAYS、DISCLOSURE_CONSENT_DAYS、DISCLOSURE_PACKAGE_DAYS、RETENTION_REJECTED_CASE_DAYS、RETENTION_SUPERSEDED_CASE_DAYS調整;法遵定案後設POLICY_APPROVED=1與POLICY_VERSION。工作天尚未計入國定假日;帳戶關閉後的保存年限、服務條款同意版本的紀錄,待條款定稿後實作。
DISCLOSURE_SIGNING_KEY 由 npm run deploy/deploy:server 自動產生;更換後依賴方要重新抓 disclosure.jwks。法人帳戶目前不接受 consent 類申請。
上線前須由法遵確認:依賴方服務條款與資料處理約定(DPA)、各類法律依據的審核標準(文件真偽查核、必要欄位最小化)、暫緩通知的條件、資料包與稽核紀錄的保存期限,以及個資法第 8/9 條告知與第 20 條目的外利用的處理方式。目前的流程與欄位是技術原型。
稽核紀錄:複核後台登入、檢視證件、KYC 決策、法人驗證、額度調整、依賴方登記與資料調閱每個步驟都寫入 data/audit/audit.jsonl。每筆含 seq、prev(上一筆 hash)與 hash = SHA-256(prev ‖ 正規化 JSON),/admin/audit 每次開啟都重新驗證整條鏈。每日排程會把(筆數, 最新 hash)寫進 AuditAnchor 合約(P3-A6,npm run deploy -- --anchor 增量部署,deploy:server 會自動執行):hash 鏈只能證明沒有被改一筆,鏈上錨點連整份重寫(重新計算所有 hash)都驗得出來。/admin/audit 每次開啟都用鏈上的 Anchored 事件核對,hash 鏈斷裂時拒絕上鏈;管理者可按「立即上鏈」。
伺服器需求
- 系統要有
ffmpeg(或以FFMPEG_PATH指定),用來解碼臉部影片與音訊。 - 一件案件在 2 核 CPU 上約 15–30 秒,依序在背景處理;
KYC_THREADS可調整推論執行緒數。 - 缺少模型或 ffmpeg 時,案件會標示原因並轉人工,不會自動通過。
開發與測試
NEXT_PUBLIC_KYC_SIMULATE=1:前端活體步驟改為按鈕模擬完成動作(沒有真人臉部的 E2E 環境)。KYC_PROTOTYPE_AUTO_APPROVE=1:後台略過模型、全部放行。兩者都只限開發,正式環境不得開啟。- 證件、臉部影像與動作序列存放在
data/kyc/<身分地址>/<案件>/(只有浮水印版);case.json另存 128 維人臉特徵,供恢復時比對本人。