sign-cli

sign-cli

完全离线的电子签名命令行工具。内置的 PAdES 签名器（/ByteRange 中的 PKCS#7、自签发证书）可生成真实且可通过密码学验证的签名 PDF，无需注册，也无需第三方服务提供商；如果需要外部信任锚点，也可通过 Dropbox Sign / DocuSign / SignWell 处理。每位签署人各自的审批令牌（有 TTL 时限，仅限一个邮箱）、哈希链审计事件、RFC 3161 时间戳、命名配置文件、包含 19 个工具的 MCP 服务，以及包含 20 个路由的 HTTP API。

这种不对称性就是架构设计：Agent 可以驱动除实际签名操作之外的每个步骤；实际签名操作始终由人工把关。

属于 contract-ops 命令行工具套件——可选。 sign-cli 完全可以独立运行；它也是 contract-ops 套件中的签名 + 审计步骤：template-vault-cli → draft-cli → nda-review-cli → docx2pdf-cli → sign-cli，并通过 compare-cli 检测差异。

运行此命令

npx @drbaher/sign-cli demo

这一条命令即可运行完整生命周期——创建（启用同意和邮箱验证关卡）→ 发送 → 观察签名被关卡拦截 → 验证邮箱 → 记录同意 → 批准 → 签名 → 验证链 → 导出回执——所有操作都通过离线本地服务提供商完成，然后删除所有内容。无需注册。无需密钥。约 5 秒。

在线演示 → — 只读，每 4 小时重置一次。自托管：参见 deploy/README.md。

下一步

如果你是……	从这里开始
正在评估此工具的新用户	本 README 的快速入门，然后阅读标准用户流程
负责接入托管服务提供商的运维人员	docs/setup/ — Dropbox / DocuSign / SignWell / 嵌入式
驱动命令行工具的大模型 Agent	AGENTS.md → docs/agent-guide.md → docs/recipes/
验证签名文件包的审计人员	docs/reference/audit-chain.md、docs/reference/legal.md
贡献者	docs/reference/architecture.md、docs/regression-testing.md
要向套件中添加新的命令行工具	构建命令行工具指南——套件中每个命令行工具都遵循的约定

概念详解见 docs/reference/；按任务分类的操作指南见 docs/recipes/。

快速入门

# Install
npm i -g @drbaher/sign-cli

# Or run without installing
npx @drbaher/sign-cli demo

# After install, the binary is named `sign`
sign --version
sign demo
sign init        # wizard: provider selection + .env
sign doctor preflight   # structured per-check readiness report

或者从 Releases 下载独立二进制文件，然后运行 ./sign-linux-x64 demo。所有安装方式见 DISTRIBUTION.md。

你将获得什么

• 离线 PAdES 签名，使用自签发证书——生成真正的 PKCS#7 签名 PDF，无需注册，无需 API 密钥。
• 三个托管服务商供你按需使用：Dropbox Sign、DocuSign、SignWell。四种方式的操作界面一致。
• 每位签署人的审批令牌（单次使用、设有 TTL 时限，并绑定到一个电子邮件地址）。令牌发给真人，而不是 Agent。
• 同意与归属证明，按请求选择启用：--require-consent 要求在签署前记录签署意图声明和电子记录同意（规范文本带版本号，并经过哈希后写入审计链）；--require-email-verification 要求通过邮箱验证码验证；signer record-identity 会记录通过线下方式核验身份的情况。我们不会收集 KYC 数据，这是有意为之。请参阅 docs/reference/consent-and-identity.md。
• 哈希链式审计链，采用仅追加数据库触发器和 RFC 3161 时间戳锚点。请参阅 docs/reference/audit-chain.md。
• 幂等的 request send——除非使用 --force true，否则会拒绝重复发送；可配合 --idempotency-key 安全重试。
• 多文档、多签署人请求；支持通过 CSV 批量发送。
• 模板：通过 request from-template 使用各服务商控制面板中的模板。
• 自动检测签名字段（sign pdf detect-signature-field + sign sign --auto-place）。可检测 AcroForm /Sig 控件，以及符合英语和法语／欧盟惯例的锚点文本。
• 检查任何已签名 PDF：使用 sign pdf inspect 解析由 sign-cli 或其他工具（Adobe、DocuSign、Dropbox Sign、SignWell）生成的 PAdES PKCS#7。返回签署人 CN／电子邮件、证书主题和颁发者、有效期、指纹、信任标签（self_signed_local / self_signed_other / ca_signed / unknown）以及消息摘要匹配结果。
• 查看会签信息——signer fetch-document 和 MCP signer_fetch_document 工具会显示 existingSignatures，让签署人在签署前查看自己将要会签的内容。
• 一键将 DOCX 转为密封 PDF：通过 sign document 在一次调用中串联随附的 docx2pdf-cli、自动定位、盖章、PAdES 密封和验证，并使用作用域受限的临时数据库。
• 通过 --read-only true 启用沙盒模式，适用于 mcp serve 和 serve。修改数据的工具／路由会返回 FORBIDDEN_READ_ONLY。
• 对每个输入和输出路径进行路径遍历防护。请参阅 docs/reference/security-controls.md。
• 命名配置：将服务商、dbPath 和凭据打包在一起（支持通过 {{env:VAR}} 引用由 shell 管理的密钥）。请参阅 docs/reference/profiles.md。
• 端到端离线 PDF 验证：request verify-signed-pdf 会重新计算摘要、提取 X.509 签署人证书，支持使用 --recipient <email> 生成单一签署人的脱敏视图，并报告每位签署人的 trust 标签。

标准用户流程

sign request create \
  --title "Mutual NDA" \
  --document ./nda.pdf \
  --signer name:Alice,email:[email protected],order:1 \
  --signer name:Bob,email:[email protected],order:2 \
  --provider signwell

sign approve --request-id <id> --token <token1>
sign approve --request-id <id> --token <token2>

sign request send --request-id <id> --provider signwell --test-mode true

sign request watch \
  --request-id <id> --provider signwell \
  --interval-seconds 5 --fetch-final true \
  --out ./signed.pdf

sign audit show --request-id <id>

或者完全离线运行：

sign request create --title "Mutual NDA" --document ./nda.pdf \
  --signer name:Alice,email:[email protected],order:1 \
  --signer name:Bob,email:[email protected],order:2 \
  --provider local --auto-approve true
sign request send --request-id <id> --provider local
# Each signer runs:
sign sign --request-id <id> --token <their-token> \
  --require-hash <sha256> --require-title "^Mutual NDA$"

有关各服务商的完整设置说明，请参阅 docs/setup/。

一键将 DOCX 转为密封 PDF

sign document contract.docx \
  --signer "Alice Founder" --signer-email "[email protected]" \
  --name-signature "Alice Founder" --auto-place first \
  --out contract.sealed.pdf

sign document 会依次执行：转换（通过随附的 docx2pdf-cli）→ 检测签名字段 → 盖章 → PAdES 密封 → 验证链。所有中间状态都保存在作用域受限的临时数据库中。

MCP 服务（适用于大模型 Agent）

sign mcp serve                  # stdio MCP server
sign mcp serve --read-only true # sandboxed: mutating tools return FORBIDDEN_READ_ONLY
sign mcp tools                  # print the catalog (live; don't hardcode the list)

共 19 个工具，分为只读和修改数据两类。底层使用的 SignCliError 错误封装与命令行中的相同。完整的发现契约、接入示例（Claude Desktop、Cursor）和只读操作指南，请参阅 AGENTS.md。此外，还提供三种资源形式（request://<id> 快照、.../document PDF 二进制数据、.../audit 审计链），以及四种供 Agent 作为签署人使用的提示词模板（review_and_sign、policy_check、inbox_triage、verify_receipt）。

HTTP API（适用于非 MCP 客户端）

sign serve --port 4000 --auth-token <t> --read-only true --rate-limit 5
curl http://127.0.0.1:4000/v1/openapi.json    # discover the route catalog

/v1/* 下共有 20 个路由，与 MCP 工具接口完全一致——输入格式相同、路径遍历防护相同、只读模式限制相同。可通过 --auth-token 或 SIGN_HTTP_AUTH_TOKEN 使用 Bearer 身份验证。成功时响应格式为 { ok, result }，失败时返回标准错误封装。

签署方流程（适合 Agent）

对于 --provider local，Agent 无需通过电子邮件链接，即可端到端地充当签署方。设置 SIGN_LOCAL_AUTOCOMPLETE=false，让本地提供方保持在 sent 状态，直到每位签署方明确运行 sign sign。

# As the requester (agent or human)
sign request create --title "Mutual NDA" --document ./nda.pdf \
  --signer name:Alice,email:[email protected],order:1 \
  --signer name:Bob,email:[email protected],order:2 \
  --provider local --auto-approve true
# response includes per-signer tokens
sign request send --request-id <id> --provider local

# As the signer, with their token
sign signer list --signer-email [email protected]
sign signer fetch-document --request-id <id> --token alice-tok-... --out ./nda.pdf
# fetch-document surfaces `existingSignatures` so the signer can see what they're countersigning
sign sign --request-id <id> --token alice-tok-... \
  --require-hash <sha256> --require-title "^Mutual NDA$" --require-signer-email [email protected]
# or
sign signer decline --request-id <id> --token alice-tok-... --reason "Terms changed"

多签署方：只有当每位签署方都在 signedBy[] 中时，状态才会变为 completed。签署前安全检查（--require-hash / --require-title / --require-signer-email）会在任何状态变更之前抛出 PRE_SIGN_*_MISMATCH。

模板

复用提供方控制面板中定义的模板（无需上传 PDF）：

sign request from-template \
  --template-id tmpl_abc --provider dropbox \
  --signer role:Buyer,name:Alice,email:[email protected],order:1 \
  --signer role:Seller,name:Bob,email:[email protected],order:2 \
  --prefill name:purchase_price,value:1000 \
  --auto-approve true

sign request send --request-id <id> --provider dropbox --test-mode true

每个 --signer 都必须包含与模板角色相匹配的 role:<roleName>。--prefill name:K,value:V[,signer:N] 用于填充模板字段。各提供方的行为：DocuSign 使用每位签署方的文本选项卡；Dropbox 使用 custom_fields；SignWell 使用 placeholders。

字段放置

默认情况下，托管型提供方会自动追加通用签名页。对于实际合同，请在 request create 上传入 --field（可重复使用）：

sign request create \
  --title "NDA" --document ./contract.pdf \
  --signer name:Alice,email:[email protected],order:1 \
  --field signer:1,page:1,x:100,y:200,type:signature \
  --field signer:1,page:1,x:100,y:240,type:date

规范：signer:<order>（必需）、doc:<i>（多文档索引）、type:signature|initials|date|text|name|email、page:<n> x:<pt> y:<pt>（坐标），或仅限 DocuSign 的 anchor:"text"，可选 x-offset / y-offset / anchor-units。这些字段会保留在请求中，并在发送时转发给提供方。

自动检测签名字段

对于 --provider local，sign sign --auto-place 会调用检测器，并且仅在存在唯一高置信度（≥0.8）匹配项时使用排名最高的候选项。

# Inspect candidates first
sign pdf detect-signature-field --pdf ./contract.pdf

# Auto-place (errors loudly on ambiguity)
sign sign --request-id <id> --token <t> --name-signature "Alice" \
  --auto-place first   # or true | last | all | page:N | index:N

按优先级排序的调整策略：underline-snap（0.95）、below-anchor-probe（0.85，法语／欧盟惯例）、whitespace-probe（0.75）、shrink-to-fit（0.50）。日期锚点通过 sign pdf detect-date-field 单独检测。完整参考见 docs/agent-guide.md §6.4a。

批量发送

sign request bulk \
  --csv ./signers.csv \
  --document ./contract.pdf --provider dropbox \
  --title "Q2 NDA for {{email}}" --test-mode true

每行都会生成一个独立请求，并设置 autoApprove: true。标题模板支持 {{email}}、{{name}}、{{row}}。如果有任意一行失败，则退出码为 3；JSON 输出会列出每行的结果。

超越提供方的信任保障

# Inspect any signed PDF (ours, Adobe's, DocuSign's, …) — no DB lookup required
sign pdf inspect --pdf ./signed.pdf

# Inspect the embedded PKCS#7 of a request we sent
sign request verify-signed-pdf --request-id <id>
sign request verify-signed-pdf --request-id <id> --recipient [email protected]   # single-signer view

# Anchor the audit head against a public RFC 3161 TSA
sign audit anchor --request-id <id>

# Bundle for archival
sign audit export --request-id <id> --out ./bundle/

audit verify 会遍历本地哈希链。request verify-signed-pdf 会重新计算 /ByteRange 的 SHA-256，并将其与嵌入式 PKCS#7 中的 messageDigest 进行比较，同时根据签署方证书的公钥（RSA/ECDSA）验证 PKCS#7 签名值——因此，伪造或篡改的签名会验证失败，退出码为 3，而不仅仅是签署后被修改的文件。sign pdf inspect 可用于任何已签名的 PDF（无需请求 ID）。audit anchor 会从 TSA 获取时间戳令牌。完整模型见 docs/reference/audit-chain.md。

配置档案

sign profile init --name prod --provider signwell --db "~/.sign-cli/prod.db" --strict-provider true
sign profile set --name prod --key credentials.SIGNWELL_API_KEY --value "{{env:SIGNWELL_API_KEY}}"
sign --profile prod request show --request-id <id>
# Or implicitly via a project-level sign-profile.json (git/npm-style upward discovery)

解析顺序：标志 > 环境变量 > 项目配置档案 > 用户配置档案 > 内置默认值。默认情况下，profile show 会隐藏凭据（使用 --show-secrets true 可显示）。通过 MCP HTTP 传输时，除非配置了 --http-auth-token，否则会拒绝 show_secrets（stdio MCP 和 CLI 仍可使用该功能）。见 docs/reference/profiles.md。

诊断

sign doctor                       # legacy env-report; always exits 0
sign doctor preflight             # structured per-check report; exit 0 ok, 1 failed
sign doctor providers             # capability matrix across all providers
sign doctor account-check --provider signwell   # provider /me check

preflight 会对每个提供方运行环境健康检查（runtime:node_version、storage:db_path），随后叠加提供方专属检查。Agent 可根据 checks[].name 分支执行自我恢复。

安全说明

• 切勿提交 .env 或 API 密钥。
• 如果密钥在聊天或日志中泄露，请轮换密钥。
• 开发期间请保持测试模式开启。
• 有关路径遍历防护、机密信息隐藏、幂等性和只读模式，请参阅 docs/reference/security-controls.md。
• 有关哈希链能证明和不能证明的内容，请参阅 docs/reference/security-model.md。

许可证

MIT。见 LICENSE。

另请参阅

• AGENTS.md — Agent 快速入门（输出约定、退出代码、发现、故障恢复）。
• docs/agent-guide.md — Agent 权威参考（各命令的架构、副作用、幂等性）。
• docs/setup/ — 提供商设置（Dropbox、DocuSign、SignWell、嵌入式）。
• docs/recipes/ — 面向任务的操作指南（预检、agent-loop-mcp、每周锚点、审计员交接、以 Alice 的身份签署、欧盟 NDA）。
• docs/reference/ — 概念深入解析（审计链、退出代码、配置文件、安全模型、架构、法律立场、对比）。
• TROUBLESHOOTING.md — 错误目录。
• CHANGELOG.md — 新增内容及其时间。
• integrations/ — Claude Desktop 配置、LangChain 入门指南。
• deploy/ — 用于托管演示的 Fly / Render / Railway 配置。