CodeIgniter 4 上 NextPDF 的安全性與維運

概覽

本頁列出這套整合必須抵禦的威脅，並說明套件原始碼中實作的各項控制措施，同時提供安全部署的維運規則。

威脅模型

攻擊者可能影響下列三個介面。

佇列任務酬載。 佇列會儲存任務資料。具有 broker（訊息中介者）存取權的攻擊者可以變更這些資料。這屬於未經信任且已反序列化的輸入。
回應檔名。 使用者可以提供下載檔名。惡意檔名可能注入標頭內容。
組態路徑。 字型路徑與簽章路徑都來自組態。錯誤的路徑可能導致讀取或寫入錯誤的位置。

控制措施 1——佇列酬載允許清單

佇列任務會將其酬載視為未經信任且已反序列化的資料來處理。OWASP ASVS 要求對已反序列化的未信任資料做安全的輸入處理（ASVS V1.5.2）。

已驗證的控制措施位於 GeneratePdfJob：

builder（建構器）必須是非空字串。任務會拒絕其他型別。
builder 必須符合 App\PdfBuilders\<Class>::<method> 這個樣式。任務會拒絕任何其他 namespace（命名空間）、普通函式，以及加上前綴或後綴的酬載。
builder 必須是可呼叫的。若字串符合樣式但無法 resolve（解析）成可呼叫目標，任務會予以拒絕。

這些規則可阻擋透過竄改佇列酬載執行任意程式碼。套件測試會逐一斷言每一種拒絕情境。

控制措施 2——佇列輸出路徑限制

任務會將檔案寫入磁碟。當應用程式為檔案操作建構檔案路徑時，OWASP ASVS 要求做安全的路徑處理（ASVS V5.3.2）。

已驗證的控制措施位於 GeneratePdfJob：

輸出路徑必須是非空字串。
任務會將路徑正規化。它會在任何檢查之前先解析 . 與 .. 區段，並轉換分隔符號。
正規化後的路徑必須位於 WRITEPATH/pdfs/ 之內。任務會拒絕名稱前綴相同的同層目錄（pdfs-evil/）。
路徑必須以 .pdf 結尾（不分大小寫）。

這些規則可阻擋透過竄改酬載任意寫入檔案。

控制措施 3——回應標頭強化

PdfResponse 會為每個 PDF 回應附上一組固定的標頭：

標頭	值
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Content-Security-Policy`	`default-src 'none'`
`X-Robots-Tag`	`noindex, nofollow`
`Referrer-Policy`	`no-referrer`
`Cache-Control`	`private, max-age=0, must-revalidate`

檔名在寫入標頭之前會先經過清理。套件會移除路徑分隔符號、null 位元組與 CR/LF，並為帶引號的形式跳脫雙引號。對於非 ASCII 名稱，它會加上 RFC 5987 的 filename*=UTF-8''… 參數。空白名稱會變成 document.pdf。

控制措施 4——組態路徑驗證

字型登錄會拒絕含有串流包裝器（stream wrapper，://）或 null 位元組的 fontsPath，並引發執行階段錯誤。這可阻擋像 php:// 或 phar:// 這類包裝路徑。

控制措施 5——最小化的 service-locator 介面

CodeIgniter 4 沒有 PSR-11 container（容器），而是使用 Services locator（服務定位器）。PSR-11 §1.3 將 service-locator 模式視為不建議使用（modal SHOULD NOT）。套件刻意將定位器介面維持精簡。每個服務都是一個具名的 factory（工廠）方法。請在 controller（控制器）邊界處解析服務，並把具體物件往內傳入。請勿把 Services 類別傳入領域程式碼。

簽章與 TSA 維運作業（NextPDF Pro/Enterprise）

簽章服務預設為停用狀態。只有當 signature.enabled 為 true，且 signature.certificate 為非空值時，它才會啟用。套件預設的簽章等級為 B-B。NextPDF Pro 提供 B-B 基準簽章。長期驗證（LTV）是另一項獨立的 Enterprise 功能。相關內容記載於 Premium 參考文件，不在此處說明。

維運規則：

請勿將憑證與金鑰檔案納入版本控管。請透過 .env 或祕密管理工具來提供它們。
在正式環境中，請將 tsa.allow_insecure_http 維持為 false。明文的 TSA 通道並不可接受。
當 TSA 發布穩定的金鑰時，請設定 tsa.pinned_public_keys。請將 tsa.warn_on_key_rotation 維持為 true。
請將金鑰檔案的讀取權限限制為應用程式使用者。

維運檢查清單

請在 composer.lock 中釘選所有已解析的版本。
在執行 worker 的應用程式中，請要求 codeigniter4/queue。
請以低權限使用者身分執行佇列 worker。只給它對 WRITEPATH/pdfs/ 的寫入權限。
請讓 worker 具備與 web 層相同的 NextPDF 擴充套件。已簽章的 PDF 需要 worker 環境中安裝 NextPDF Pro 或 Enterprise。
請在每個會建構 PDF 的執行環境中，確認已安裝 mbstring 與 zlib 擴充套件。
請確認回應標頭通過 reverse proxy（反向轉送伺服器）後仍會保留下來。
請記錄帶有情境資訊的 PDF 產生作業。請勿記錄憑證內容或金鑰密碼。

符合性

佇列酬載的處理方式符合 OWASP ASVS V1.5.2。
佇列輸出路徑的處理方式符合 OWASP ASVS V5.3.2。
定位器的設計遵循 PSR-11 §1.3 的指引。

商業情境

NextPDF core 採用 Apache-2.0。只有安裝 NextPDF Pro 或 Enterprise 時，簽章信任錨點與 TSA 強化才會生效。CodeIgniter 套件會公開對應的服務方法；在尚未安裝相符的 Premium 套件之前，這些方法會回傳 null。詳見 </get-license/?intent=codeigniter-signing>。

另請參閱

/integrations/codeigniter/production-usage/ —— 正確的佇列註冊與派送。
/integrations/codeigniter/configuration/ —— 簽章、TSA，以及路徑相關的鍵。
/integrations/codeigniter/troubleshooting/ —— 已驗證的拒絕訊息。
/integrations/codeigniter/overview/ —— 完整的 API 介面。