dsh-pdf-sign

PDF electronic signing for DeepSeek Harness (DSH) — generate a handwritten-style signature image, stamp it on a PDF, and apply a real PKCS#7 digital signature.

DeepSeek Harness 的 PDF 电子签名插件 —— 生成手写风格签名图、在 PDF 上盖章、并用你自己的证书做真正的 PKCS#7 数字签名。

English · 中文

English

What it does

Three capabilities, kept deliberately separate because they mean very different things:

The distinction matters: a stamped signature looks signed but proves nothing. A digital signature proves the document was not altered after signing and identifies who holds the key — but only a certificate from a real CA makes a reader display it as trusted.

Install

dsh plugin --profile web add dsh-pdf-sign

Restart DSH, then the pdf_sign_* tools are available to the agent.

Quick start

# 1. Make a signature image
pdf_signature_image(text="Juntao Xiao", output_path="/abs/path/sig.png")

# 2. Stamp it on the last page
pdf_sign_stamp(pdf_path="/abs/path/contract.pdf",
image_path="/abs/path/sig.png",
text="Juntao Xiao", date_text="2026-09-20",
anchor="bottom-right", width=200)

# 3. Add a real digital signature
pdf_sign_cert_generate(common_name="Juntao Xiao", passphrase="secret",
output_dir="/abs/path/certs")
pdf_sign_digital(pdf_path="/abs/path/contract.pdf",
output_path="/abs/path/contract-signed.pdf",
p12_path="/abs/path/certs/signing-cert.p12",
passphrase="secret", reason="Approval")

Tool reference

pdf_signature_image

Each glyph is emitted as its own rotated, vertically jittered node using a text-seeded pattern — so the same name always produces the identical signature, which matters when a document is re-signed.

Best available fonts are auto-detected: 楷体/标楷体/华文行楷 on Windows, Songti/Kai on macOS, Noto Serif CJK/AR PL UKai on Linux.

pdf_sign_stamp

Non-Latin text (Chinese, Japanese, Korean, …) is drawn with a subset-embedded system TrueType font, because pdf-lib's standard fonts are WinAnsi-only and cannot encode those characters at all.

Background transparency — read this before stacking two images

Signature and seal images are normally exported as opaque images on a solid background. An opaque background is a filled rectangle: it hides whatever it is drawn over. So a seal placed on top of a signature erases the signature, and a stamp over body text whitens that text. If you feed such an image without drop_background, the tool says so in its note rather than failing silently.

pdf_sign_stamp(pdf_path="contract.pdf", image_path="signature.png",
drop_background="white")          # opaque white export
pdf_sign_stamp(pdf_path="contract.pdf", image_path="scan.jpg",
drop_background="auto")           # samples the border

• white — for the usual white-background export.
• auto — samples the image border and keys out the dominant border colour. Use when the background is off-white or you don't know it. (It takes the most frequent border colour, not the mean, so ink that runs off the edge does not drag the estimate toward grey.)
• #rrggbb — an explicit colour.

Colour fidelity is preserved: the toolkit un-composites each pixel (I = (C − B·(1−a)) / a) instead of just fading it, so the result over the page reproduces the original pixel rather than looking washed out. Only light backgrounds can be keyed this way (darkest channel must be ≥ 32); a dark background is rejected with an explanatory error. PNG and JPEG sources both work.

trim_image then crops the transparent margins, so the placement box follows the actual ink instead of the source canvas — important because a padded canvas otherwise makes the stamp look far smaller and more offset than intended.

pdf_sign_digital

pdf_sign_cert_generate

Creates a self-signed certificate and .p12, or bundles an existing key + certificate pair (pass both key_path and cert_path). Requires OpenSSL; the bundled OpenSSL in Git for Windows is found automatically.

pdf_sign_inspect

Reports signature form fields, how many byte ranges are signed, the CMS sub-filter, and placeholder metadata. Structural inspection only — it does not verify cryptographic validity, which requires the signer's certificate chain.

Security stance

• Ships no keys, no CA, no trust anchor. Nothing here can forge a signature that a reader would trust.
• Self-signed certificates produce signatures that validate as intact but display as untrusted. That is the correct and expected outcome; obtaining a CA-issued certificate is your job.
• Your private key and passphrase stay on your machine. The plugin does not transmit anything anywhere.
• Signing writes the placeholder without object streams, which is required for the incremental-update signing scheme — not a stylistic choice.

Requirements

• Node.js ≥ 20
• OpenSSL, only for pdf_sign_cert_generate (auto-detected, including Git for Windows)
• Optional: the native @resvg/resvg-js binding for PNG rasterization. It ships as a dependency; if it cannot load on your platform, pdf_signature_image writes SVG instead and says so explicitly.

Known limitations

• pdf_sign_inspect does not perform cryptographic verification, and does not consult a trust store.
• Encrypted PDFs are loaded with ignoreEncryption, so signing an encrypted document is not supported.
• Subset-embedded CJK fonts increase file size modestly (subset only, not the whole font).
• ETSI.CAdES.detached is offered, but only adbe.pkcs7.detached has been exercised end to end.

License

MIT

中文

它做什么

五种能力，刻意分开——因为它们代表的东西完全不同：

这个区分很关键：盖章看起来像签了名，但什么都证明不了；数字签名能证明文件在签名后未被改动、并标识持钥者身份——但只有来自真实 CA 的证书，PDF 阅读器才会显示为「受信任」。

安装

dsh plugin --profile web add dsh-pdf-sign

重启 DSH 后，agent 即可使用 pdf_sign_* 系列工具。

快速开始

# 1. 生成签名图
pdf_signature_image(text="肖俊涛", output_path="D:/sign/sig.png")

# 2. 盖到最后一页
pdf_sign_stamp(pdf_path="D:/contract.pdf",
image_path="D:/sign/sig.png",
text="肖俊涛", date_text="2026-09-20",
anchor="bottom-right", width=200)

# 3. 加真正的数字签名
pdf_sign_cert_generate(common_name="肖俊涛", passphrase="你的口令",
output_dir="D:/sign/certs")
pdf_sign_digital(pdf_path="D:/contract.pdf",
output_path="D:/contract-signed.pdf",
p12_path="D:/sign/certs/signing-cert.p12",
passphrase="你的口令", reason="合同审批")

五个实现要点

1. 确定性签名：每个字以独立的旋转+抖动节点渲染，抖动由文本内容做种子——同一个名字永远生成一模一样的签名，重复签署不会出现两种笔迹。
2. 中文文字盖章需要嵌入字体：pdf-lib 的标准字体是 WinAnsi 编码，无法编码任何中文。插件会自动寻找系统中可嵌入的 TrueType 中文字体（楷体／黑体／仿宋／等线）并做子集嵌入。
3. 数字签名的占位符必须禁用对象流保存（useObjectStreams: false），这是增量更新签名方案的硬性要求，不是代码风格选择。
4. 白底必须转透明，否则叠放会互相遮盖（drop_background）。签名与印章图通常是不透明的实底图，而不透明背景就是一个实心矩形——印章盖在签名上会把签名整个擦掉，盖在正文上会把正文涂白。所以：

pdf_sign_stamp(pdf_path="合同.pdf", image_path="签名.png",
drop_background="white")     # 常见白底导出图
pdf_sign_stamp(pdf_path="合同.pdf", image_path="扫描件.jpg",
drop_background="auto")      # 自动采样边框色

• white：常规白底导出图；auto：采样边框并去掉占主导的边框色；也可直接给 #rrggbb。
• 保留颜色保真：不是简单地把白变透明（那会让墨迹发灰），而是对每个像素做反合成（I = (C − B·(1−a)) / a），使结果叠到页面上后与原图像素完全一致。
• 取的是边框众数而非均值——墨迹触到画布边缘时，均值会被拉灰（实测会把 250,248,245 误算成 238,236,233），众数不受影响。
• 仅支持浅色背景（最暗通道 ≥ 32）；深色背景会明确报错，不静默出错。PNG 与 JPEG 均可。
• 未指定 drop_background 而图片又是「全不透明且 ≥90% 近白」时，工具会在 note 里主动提示该开这个参数，而不是让你事后才发现白块盖住了东西。
  5. trim_image（默认开）裁掉透明留白：让放置框跟着真实墨迹走，而不是源画布。否则带大量留白的画布会让印章看起来远小于预期、位置也偏。

安全立场

• 不内置任何密钥、CA 或信任锚。这里没有任何东西能伪造出阅读器会信任的签名。
• 自签名证书产生的签名「完整性有效」但显示为「不受信任」——这是正确且预期的结果；取得 CA 签发的证书是你自己的事。
• 你的私钥与口令只留在本机，插件不向任何地方传输数据。

已知限制

• pdf_sign_inspect 不做密码学验证，也不查询信任库。
• 加密 PDF 以 ignoreEncryption 方式加载，因此不支持对加密文档签名。
• ETSI.CAdES.detached 虽已提供，但只有 adbe.pkcs7.detached 经过端到端实测。
• 文本图章使用子集嵌入字体，会让 PDF 略微变大（只嵌入用到的字形，不是整个字体）。

许可

MIT

本项目是 DeepSeek Harness 的社区插件，并非 DeepSeek 官方产品。
本插件与 Adobe、OpenSSL 及任何证书颁发机构均无从属关系。