本技能用于加固 Documenso 文档签名集成,覆盖 API 密钥管理、Webhook 验证、文档访问控制与自托管签名证书配置。
用途:以最小权限方式配置 Documenso,设定作用域密钥、签名者/文档访问控制,以及事件响应与密钥撤销路径。
主要能力:
- API 密钥安全:禁止硬编码密钥,使用环境变量或密钥管理器(Vault、AWS Secrets Manager);将 .env 加入 .gitignore;团队资源使用团队级密钥,个人文档使用个人密钥;员工离职时立即在控制台撤销;CI/CD 使用掩码/加密密钥。
- 无停机轮换:通过主/备双密钥切换(DOCUMENSO_API_KEY_PRIMARY、DOCUMENSO_API_KEY_SECONDARY)实现轮换流程:生成新密钥→部署为备钥→验证→转为主钥→撤销旧钥。
- Webhook 密钥验证:校验 X-Documenso-Secret 请求头,使用恒定时间比较(Node 的 timingSafeEqual 或 Python 的 hmac.compare_digest)防时序攻击。
- 文档访问控制:按键级别区分个人/团队范围,校验请求者是否为文档所有者或收件人,否则拒绝。
- 自托管签名证书:需 .p12 证书,可用 openssl 生成自签名证书(仅开发),挂载到容器并配置 NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH 与 NEXT_PRIVATE_SIGNING_PASSPHRASE;生产环境应使用受信任 CA 证书。
- 自托管生产密钥:使用 openssl rand -hex 32 生成 NEXTAUTH_SECRET、NEXT_PRIVATE_ENCRYPTION_KEY、NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY,各环境不复用、不使用默认值。
使用前提:拥有 Documenso API 访问权限的账户、理解环境变量与密钥管理、已完成 documenso-install-auth 设置。
限制:自签名证书仅适用于开发;生产环境须使用受信任 CA 证书;文中未提供具体定价、完整生产部署步骤或其它平台支持信息。