本專案為非官方的個人專案。本文件是我個人整理的安全實務建議，不構成任何法規符合性聲明，也不取代歐付寶官方的安全規範或你所屬組織的資安政策。

• 1. 金鑰處理原則
• 2. 絕對不要做的事
• 3. 不得把真實資料貼進 AI 對話
• 4. 金鑰外洩的處置流程
• 5. 傳輸與環境安全
• 6. 稽核與可追溯性
• 7. 漏洞回報
• 8. 本專案自身的安全承諾
• 9. 上線前安全檢查清單

歐付寶電子發票的敏感憑證有三個：MerchantID、HashKey、HashIV。 其中 HashKey 與 HashIV 是 AES-128 的金鑰與 IV，拿到這兩個就能偽造與解密所有請求。

# .gitignore 必須包含
.env
.env.*
!.env.example
*.pem
*.key
secrets/

# ✅ 正確
import os
hash_key = os.environ["OPAY_HASH_KEY"]

# ❌ 錯誤
hash_key = "ejCk326UnaZWKisg"   # 就算是測試值，也不要寫死在程式邏輯裡

本 repo 的文件與 .env.example 中出現的以下數值，是歐付寶官方技術文件公開列出的測試環境值：

它們只能用在 einvoice-stage.opay.tw。 正式環境的憑證必須向歐付寶申請，且永遠不得出現在任何 repo 中。

⚠️ 測試環境也會產生真實的發票紀錄、消耗真實的字軌號碼，且只能作廢不能刪除。不要把測試環境當沙箱亂打。

• 多數 AI 服務的對話可能被保存、可能被用於服務改善（依方案與設定而定）。
• 對話記錄可能被同組織其他成員存取。
• 個資外洩涉及《個人資料保護法》責任，責任在你不在 AI 廠商。
• 加密後的 Data 配上金鑰即可還原——貼了金鑰又貼封包等於直接公開明文。

- 我的請求是 {"MerchantID":"3012345","HashKey":"aB3xK9pQ2mN7vL4z", ...}
- 開立失敗，發票號碼 AB12345678，買受人 wang@example.com，統編 12345678
+ 我的請求結構是 {"MerchantID":"<REDACTED>","HashKey":"<REDACTED>", ...}
+ 開立失敗，發票號碼 AA00000000，買受人 user@example.com，統編 00000000
+ 錯誤是 TransCode=0，訊息「時間戳記錯誤」

脫敏對照表：

錯誤訊息、欄位名稱、程式碼結構、狀態碼都可以貼——AI 需要的是這些，不是你的真實資料。

一旦懷疑 HashKey / HashIV 外洩（誤 commit、貼錯視窗、離職交接、第三方服務被入侵），立即依序執行：

1. 登入歐付寶廠商後台：
   • 正式環境 https://vendor.opay.tw
   • 測試環境 https://vendor-stage.opay.tw
2. 依後台指示重新產生 HashKey / HashIV。
3. 若後台無法自助輪換，立即聯繫歐付寶客服／業務窗口，說明是資安事件並要求緊急處理。

舊金鑰在新金鑰生效前仍然有效。時間就是損害範圍，不要為了「先查清楚」而延後輪換。

• Secret Manager / .env / CI secrets / 容器 secret 全部更新。
• 逐一重啟服務並確認新金鑰生效（跑一次唯讀 API，例如 GetInvoiceWordSetting）。
• 檢查有沒有遺漏的環境（排程主機、備援機、開發者本機）。

# 如果是誤 commit：先確認範圍
git log --all -S 'HashKey' --oneline

# 從歷史移除（會改寫歷史，需協調所有協作者重新 clone）
# 建議使用 git-filter-repo 或 BFG Repo-Cleaner

⚠️ 改寫 git 歷史不代表金鑰安全了。 只要曾經 push 到遠端（尤其是公開 repo），就必須假設它已經外洩——輪換是唯一的補救，清歷史只是善後。

• 到廠商後台查詢近期發票開立紀錄，確認有無非預期的開立、作廢、折讓。
• 比對自家稽核記錄與後台紀錄，找出差異。
• 檢查字軌剩餘量是否有異常消耗。

• 記錄事件時間軸、影響範圍、處置動作。
• 依你所屬組織的規範判斷是否需要通報。
• 補上防呆：pre-commit hook、secret scanning、CI 檢查。

# .git/hooks/pre-commit（記得 chmod +x）
#!/bin/sh
if git diff --cached | grep -nE 'Hash(Key|IV)\s*[=:]\s*["\x27][A-Za-z0-9]{16}["\x27]'; then
  echo "❌ 偵測到疑似金鑰，已阻擋 commit。確認無誤請用 --no-verify。"
  exit 1
fi

也建議在 GitHub repo 設定中啟用 Secret scanning 與 Push protection。

發票是帳務憑證，不可逆操作必須留下可追溯的記錄。

• 開立（Issue / DelayIssue / OfflineIssue）
• 作廢（Invalid / OfflineInvalid / AllowanceInvalid）
• 折讓（Allowance / AllowanceByCollegiate）
• 註銷重開（VoidWithReIssue）
• 字軌設定變更（AddInvoiceWordSetting / UpdateInvoiceWordStatus）

• 存取權限最小化，不要放進全公司可讀的日誌平台。
• 個資欄位（Email、手機、統編）遮蔽後再寫入。
• 保存期限依你所屬組織與相關法規規定辦理（發票相關憑證的法定保存年限請諮詢會計師或稅務專業人員，本文件不提供法律意見）。
• 不可修改（append-only）或有變更記錄。

本政策涵蓋本 repo 的內容：程式碼模板、文件中的安全建議、測試工具。

不涵蓋歐付寶的服務本身。若你發現的是歐付寶平台的漏洞，請直接聯繫歐付寶官方，不要在本 repo 公開。

請走以下私下管道（擇一）：

1. GitHub Security Advisory（建議）：在本 repo 的 Security → Report a vulnerability 提交私密回報。
2. 透過維護者網站的聯絡方式：https://www.mitch.tw

• 問題描述與影響範圍
• 重現步驟（請用測試環境與脫敏資料）
• 受影響的檔案與版本
• 你認為的修復方向（若有）

本專案由我一個人在下班時間維護，無法承諾 SLA。以上是努力目標，不是保證。 我不提供漏洞獎金，但會在 CHANGELOG.md 致謝（除非你希望匿名）。

• 文件中出現官方公開的測試環境金鑰（2000132 / ejCk326UnaZWKisg / q9jcZX8Ib9LM8wYk、2045501 / 9XWzRmj7UJESChyn / sriQzbe1llJqk67P）——這些是官方技術文件明列的公開值，僅適用測試環境。
• 模板程式碼未實作某項防護，但文件中已明確標示「這是模板，正式使用前請自行補強」。

• ✅ 本 repo 不含任何正式環境金鑰，也不接受含正式金鑰的 PR。
• ✅ 本 repo 不收集任何使用者資料，沒有 telemetry、沒有追蹤、沒有外部呼叫（除了你自己主動發出的 API 請求）。
• ✅ 模板程式碼的相依套件刻意最小化：Node.js 驗證器零相依、PHP client 只用內建擴充。
• ✅ 所有 .env.example 中的金鑰皆為官方公開測試值，且逐處標註「僅測試環境」。
• ✅ 測試主控台的「開立測試發票」預設關閉，需同時設定環境變數與前端勾選確認才會送出。

金鑰
[ ] .env 已在 .gitignore 中，且 git status 看不到它
[ ] git log -S 'HashKey' 查不到任何真實金鑰
[ ] 正式金鑰存在 Secret Manager，不在程式碼、不在設定檔
[ ] 前端 bundle 中搜尋 HashKey / HashIV 無結果
[ ] 已啟用 GitHub secret scanning 與 push protection

環境
[ ] 測試與正式環境的金鑰、資料庫、log 完全分離
[ ] 主機 NTP 正常，時間偏移 < 1 分鐘
[ ] 防火牆以 FQDN 設定，非鎖 IP
[ ] TLS 憑證驗證未被停用

程式
[ ] 兩層回應碼（TransCode 與 RtnCode）都有檢查
[ ] 開立／作廢／折讓／註銷重開沒有自動重試
[ ] 逾時處理是「先用 GetIssue 查詢」而非直接重送
[ ] 每筆不可逆操作都有冪等鍵與稽核記錄
[ ] log 中沒有完整的 Data 明文、沒有金鑰、個資已遮蔽
[ ] 正式環境沒有任何以 Issue 作為健康檢查的排程

流程
[ ] 有金鑰輪換的操作手冊與負責人
[ ] 有字軌餘量告警與負責人
[ ] 團隊都知道「不可把真實資料貼進 AI 對話」

本文件為個人整理的實務建議，不構成法律或資安顧問意見，也不宣稱符合任何標準或法規。 正式環境的安全要求請以歐付寶官方規範、你所屬組織的資安政策，以及專業人員的意見為準。