Please do NOT open a public issue for security vulnerabilities.
To report a security vulnerability, please use GitHub's private vulnerability reporting.
Alternatively, contact us at: [email protected]
We will acknowledge receipt within 48 hours and aim to provide a fix within 7 days for critical issues.
| Version | Supported |
|---|---|
| 1.6.x | ✅ |
| 1.5.x | ✅ (security fixes) |
| < 1.5 | ❌ |
| 1.x | What a minor may change | |
|---|---|---|
| Node.js | Every line in Active or Maintenance LTS: Node.js 22 and 24, both run by the ci workflow on Linux, and 22 on Windows and macOS, all four as required checks (v1.6.0). The newest LTS line (Node.js 26, in LTS since 2026-10-28) is run by the advisory node-current workflow and promised by nothing until it joins ci.yml at the first minor after a green history |
Drop a line after its end of life (Node 22: 2027-04-30), announced one minor ahead |
| Operating systems | Ubuntu, Windows and macOS: the full gate (--ci --require-all) runs on each, so a path separator, a case-insensitive file system or a CRLF checkout cannot break a release unnoticed |
— |
| Deno, Bun, browsers | Not promised: the CLI is a Node binary (node: built-ins throughout — fs, crypto, dns, http); dist/cli.js (ESM) exists for programmatic consumption and is smoke-tested on Node only |
— |
engines.node is >=22. npm warns, and refuses only under engine-strict, when a runtime is outside the range.
From 1.6.0, pdfnative-cli proves its process contract mechanically for the whole 1.x line, on every pull request, so that "no breaking change" is a check and not a sentence:
| Leg | What is promised | Held by |
|---|---|---|
| The command surface | Every command, flag, global flag, E_* error code, exit code, schema subject and envelope field of a 1.x release keeps its name and its type; a minor only adds (a flag, a code, a subject, an additive envelope field) |
tests/compat/manifest-<previous>.json, status-<previous>.json and subjects-<previous>.json (the previous release's schema manifest / schema status / schema list, as published) against the current command in tests/tools/manifest-compat.test.ts |
| The behaviour | The previous release's own test suite, exactly as tagged, passes against the current sources; the files it may skip are listed in tests/compat/allow-<previous>.json, each with a reason and, for a behaviour change, the ledger entry that justifies it |
npm run compat:previous (scripts/run-compat.ts), the required compat-previous check and the publish gate |
| The bytes | A sample of the baseline emits the bytes its reference release emitted, unless the release note's compatibility ledger says why it moved | tests/regression/baselines/samples.sha256.json and the required sample-regression check |
What a 1.x minor may change, and how it is declared:
| Change | Semver | Declared in |
|---|---|---|
| A command, flag, error code, subject or envelope field removed or renamed; an exit code changed; a default value changed | major | — |
| Emitted bytes that differ from the previous release's for the same input, because the engine's previous bytes were wrong or its encoding changed (a font subset, a text object per line, a transparency group) | minor | The release note's Compatibility section, one ledger entry (C1, C2, …) per cause, naming which samples of the baseline were re-anchored |
| A new command, flag, error code, subject, envelope field, script or diagnostic code | minor | The release note's Added section; schema manifest and schema status carry it |
| A capability added where the CLI refused before (a joint PDF/A + PDF/X claim, an offline LTV material); a refusal the engine now makes earlier or with another code | minor | The release note's ledger, with the old and the new message |
pdfnative-cli is a thin dispatch layer over the pdfnative library. It introduces zero additional runtime dependencies. All PDF cryptographic operations are performed inside pdfnative — see the pdfnative security policy for the full cryptographic implementation notes (RSA, ECDSA, AES).
The CLI exposes 21 commands (run pdfnative --help or pdfnative schema manifest
for the authoritative list). The sign, verify, ltv and doc-timestamp
commands handle key material, certificate chains and trusted-timestamp tokens;
security invariants for each are described below.
The agent-native contract is a pure local presentation/validation layer and adds no network surface:
--jsononly changes how diagnostics are formatted on stderr (a machine-readable envelope). It never opens sockets, never alters what is written to stdout, and never relaxes any security check.--dry-runvalidates inputs and short-circuits before producing or writing output — and never performs network I/O, even when a network flag (--timestamp,--url,--online) is present. Forsignit stops after credentials are parsed and the PDF is prepared, before any signature value is computed — and still never logs key material.- Stable
E_*error codes carry only a failure class and a redacted message; internal byte offsets, parser state, and key bytes are never exposed (thesignfailure message stays the fixedFailed to sign PDF.). TSA / OCSP / CRL response bodies are never echoed into CLI output (E_NETWORKmessages are generic). - The CLI remains offline by default in every mode; network I/O happens only behind the explicit opt-in flags listed under Network Access below, and only through the SSRF guard.
- Private keys are loaded from the
PDFNATIVE_SIGN_KEYenvironment variable (PEM string) or from a file via--key. Environment variable takes precedence over file paths. - Keys are never written to disk, logged, or included in error messages. All
signPdfBytesfailures are replaced with the fixed stringFailed to sign PDF.(error codeE_SIGN). - PEM strings are consumed directly from memory and not persisted beyond the signing call.
- Native constant-time crypto by default. CMS signing routes through Node's
node:crypto(createNativeCryptoProvider) for side-channel-resistant RSA/ECDSA.--pure-cryptoselects pdfnative's portable pure-JS bignum path; both keep key material in memory only. - Recommendation for high-frequency pipelines: use
PDFNATIVE_SIGN_KEYwith a secrets manager (AWS Secrets Manager, Vault, GitHub Actions secrets) rather than a file on disk.
- All file path arguments (
--input,--output,--output-dir,--key,--cert,--cert-chain,--layout,--attachment,--watermark-image,--outline,--annotations,--trust,--data,--from-json,--manifest,--output-intent-icc,--font-file, the positional source paths ofmergeandcompare, and every path-carrying value inside abatch --manifestfile) are validated against path traversal (../) sequences before any filesystem access. - JSON input size is capped at 50 MB before
JSON.parseto prevent memory exhaustion (this also covers--layoutfiles, theannotate --annotationsspec,govern verify-issuedrafts,ltv --datafiles andbatch --manifestfiles; manifests are additionally capped at 1 000 tasks). - Binary inputs are bounded and validated (v1.5.0): an ICC profile passed with
--output-intent-iccis capped at 16 MiB and must carry theacspsignature (the engine additionally requires aprtrCMYK profile for PDF/X); a font passed with--font-fileis capped at 32 MiB, must start with a TrueType/OpenType magic (00 01 00 00,true,OTTO— collections and WOFF are refused), and is parsed byparseFontDataand checked byvalidateFontDatabefore it is registered. Neither a document JSON nor a--layoutfile can name a font or profile path — no code or data is loaded from a payload. --creation-dateandSOURCE_DATE_EPOCHare parsed strictly (ISO 8601 / integer seconds); an invalid value is a usage error, never silently ignored, so a reproducibility promise is either honoured or refused.- A manifest has the filesystem access of the user who invokes
batch— the same trust level as flags typed on the command line. Only network access is additionally gated: any network-reaching flag inside a manifest requires--allow-networkon the invocation itself, so a manifest obtained from elsewhere can never open a socket on its own. - The global
--max-inflate-size <bytes>flag caps the decompressed size of any single PDF stream while parsing untrusted input (anti zip-bomb; engine default 100 MiB). merge/split/extractenforce an optional--max-output-sizecap and bound the number of source PDFs;extract/annotatebounds-check every page reference against the document before writing.annotatere-keys only the annotation fields pdfnative's builders understand — the raw JSON is never spread into the emitted dictionary, so unknown keys cannot be injected. Alinkannotation'surlgoes through the engine'svalidateURL(http,https,mailto; nojavascript:, no control characters) and is escaped as a PDF string before it lands in the/URIaction.inspectJSON output sanitizes all values — no raw binary blobs are emitted in default mode.
- No
eval(),Function(), or dynamic code execution (batch --manifestdispatches only to a fixed whitelist of CLI command modules — never to arbitrary code). - Offline by default — no command opens a socket unless you pass one of the
explicit opt-in flags listed below. The
governcommand (AI-governance / HITL) is fully offline: it never contacts GitHub or the network, andgovern verify-issueis a pure local validator. See Network Access below. - NPM provenance — signed builds via GitHub Actions OIDC (see Supply chain below).
- Parser robustness — the nine ClusterFuzzLite targets under
fuzz/(argv, the config file, batch manifests, annotation specs, layout JSON, page selectors, dates, the URL guard,--font-file) rethrow any engine error (TypeError,RangeError, …) and swallow only aCliErrorcarrying one of the 12 stable codes;tests/fuzz/targets.test.tsruns them on a seeded, truncated and mutated corpus at every gate run, next to the deterministic hostile-input suites oftests/fuzz/.
The CLI is offline by default. Exactly four flags can cause a network request, each naming the operation it enables:
| Opt-in | Command | What is fetched |
|---|---|---|
--revocation online |
verify |
OCSP (AIA) + CRL (CDP) revocation data |
--timestamp <url> |
sign |
An RFC 3161 timestamp token from the named TSA |
--url <url> |
doc-timestamp |
An RFC 3161 token for the /DocTimeStamp revision |
--online |
ltv collect / ltv add |
OCSP + CRL validation data to archive in /DSS |
Inside a batch --manifest pipeline these flags are additionally refused unless the
batch invocation itself carries --allow-network. ltv embed is network-free by
design (air-gapped embedding of pre-collected data), and --dry-run never opens a
socket in any command.
Every request passes through the same SSRF guard (src/utils/fetch-guard.ts) that
enforces:
- an http/https-only scheme allow-list;
- DNS resolution followed by address vetting — requests to private (RFC 1918),
loopback, link-local (incl. the
169.254.169.254cloud-metadata address), unique-local, CGNAT (100.64.0.0/10), multicast, benchmarking (198.18.0.0/15), documentation (192.0.2.0/24, TEST-NET-1) and NAT64 (64:ff9b::/96) ranges are refused, for both IPv4 and IPv6 (including IPv4-mapped IPv6); - no redirect following (a 3xx is refused rather than followed, so a redirect to an internal host cannot bypass the address check);
- a 10 s timeout and a 5 MiB response cap;
- no cookies, no auth, no connection reuse.
Embedded revocation data (OCSP responses / CRLs in the PDF /DSS) and RFC 3161
timestamp tokens are parsed offline with no network access. All such signatures
(CRL tbsCertList, OCSP tbsResponseData, TSA SignerInfo) are cryptographically
verified against the issuing certificate; unverifiable data yields an unknown
status, never a good one.
The verify command verifies, with no network access by default:
- Byte-range integrity — the signer's declared digest (SHA-256, SHA-384 or
SHA-512) of the covered bytes vs the CMS
messageDigest. - CMS signature value — RSA-PKCS#1 v1.5 with SHA-256/384/512, and ECDSA-SHA256
(P-256), over the re-encoded
signedAttrs. ECDSA with SHA-384/512 is detected and labelled but never reported valid (verification is P-256 + SHA-256 only). - Certificate chain & trust — chain construction and evaluation against
--trustroots (or self-signed acceptance when no roots are supplied). - RFC 3161 timestamp (PAdES-T) — the TSA SignerInfo signature, the TSTInfo
eContent digest, and the
messageImprintbinding to the document signature are validated, and the TSA chain is built/trust-evaluated. Reported astimestampValid. /DocTimeStamprevisions (PAdES B-LTA) — each document timestamp's token is parsed, itsmessageImprintis checked against the covered byte range, and the TSA token signature is verified; reported withisDocTimestamp: true.- OCSP (RFC 6960) + CRL (RFC 5280) revocation — embedded
/DSSdata (offline) and, with--revocation online, AIA/CDP fetches via the SSRF-guarded client.
Sign-side LTV is available since v1.4.0: sign --timestamp (PAdES B-T),
ltv collect|embed|add (B-LT, /DSS + /VRI) and doc-timestamp (B-LTA). The
engine (pdfnative 1.9.0) verifies every TSA token before embedding it and never
opens a socket itself — the CLI injects the SSRF-guarded transport, with the
sign --timestamp-timeout <ms> bound on the TSA round-trip (default 10 s).
Out of scope (do not rely on for legal / regulatory non-repudiation):
- Full PAdES-B-LTA archival validation — evaluation of a document-timestamp chain over time (renewal policy, algorithm rollover assessment) is not performed; each timestamp is validated individually.
- TSA certificate revocation — the revocation status of the TSA's own certificate is not checked.
All signature-relevant hashing and verification uses SHA-256 or stronger (see the scope above). SHA-1 appears in two deliberate places:
- Verification of legacy timestamp imprints — an existing RFC 3161 token whose
messageImprintwas computed with SHA-1 is still checked (the digest named by the token's ownhashAlgorithmis used for the comparison), reported astimestampDigest: "sha1"with the noteweak digest: RFC 3161 messageImprint uses SHA-1 (refused under --strict), and fails the timestamp underverify --strict(v1.5.0). This affects verification of third-party documents only; the CLI always requests SHA-256+ imprints when it timestamps (--timestamp-digest/--digest, default sha256), and the token's TSA signature itself must verify with SHA-256+. - The OCSP
CertIDbuilt bybuildOcspRequestand matched inocspCertIdMatches(src/utils/revocation.ts). (SHA-1 of a signature's/Contentsis also used as the — non-cryptographic —/VRIdictionary key, as required by ISO 32000-2.)
The CertID usage is intentional and safe:
- RFC 6960 §B.1 defines SHA-1 as the default
CertIDhash algorithm, and it is the only one reliably indexed by deployed OCSP responders; using SHA-256 would make most responders answerunknown. - The
CertIDhash is a non-security identifier computed over the issuer's public subject DN and public key — it is not an integrity or signature primitive. OCSP trust is established solely by the responder's digital signature, which is verified independently with SHA-256/ECDSA. - NIST SP 800-131A explicitly permits SHA-1 for such non-digital-signature applications.
Static analysers (e.g. CodeQL js/weak-cryptographic-algorithm) may flag this line
because certificate-derived bytes are treated as "sensitive data". This is a
reviewed false positive: the data is public and the hash is not used for any
security decision. The call sites are annotated in source, and the alert is dismissed
as "Won't fix" in code scanning with this rationale.
- The global
--creation-date <iso8601>(orSOURCE_DATE_EPOCH=<seconds>) pins every date the engine writes —/CreationDate,xmp:CreateDate, the{date}placeholder and the trailer/ID— in UTC, so the same input produces byte-identical output on every host and in every timezone. A consumer can therefore verify a PDF by hash. - Encrypted output is never byte-reproducible (the file key and IVs come from the CSPRNG,
by design), and a signed PDF's incremental revision carries a per-revision
/IDdrawn at signing time (see ROADMAP.md).sign --signing-timeandmetadata --mod-dateare deliberate legal instants and are not pinned by--creation-date. - The repository proves the promise on itself: every generated sample is held to
tests/regression/baselines/samples.sha256.json(byte-exact for plain output, semantic for encrypted and signed output) bynpm run verify:samples, blocking in CI.
- Zero extra runtime dependencies —
pdfnativeis the only one;npm ci --ignore-scriptseverywhere in CI,.npmrcsetsignore-scripts=trueandaudit-level=high. - Hardened workflows — every action pinned to a commit SHA and resolved to one SHA across
the tree,
persist-credentials: falseon every checkout,step-security/harden-runneron every job (block mode with an allow-list where the endpoints are known, audit with a dated reason elsewhere),npm ci --ignore-scriptseverywhere, write permissions at job level only, Dependency Review on every pull request, a weeklynpm audit, Dependabot with a seven-day cooldown on all four ecosystems (npm, GitHub Actions, the fuzzing engine, its Docker base image), the workflows themselves linted by zizmor and actionlint on every pull request (workflow lint), CodeQL (security-extended, theactionslanguage included) on every push, and the parser surface fuzzed by ClusterFuzzLite (fuzz/, Jazzer.js pinned by lockfile inside the build image, never in the package) — all of it held bytests/tools/workflows.test.ts. - Trusted Publishing —
publish.ymlpublishes in four jobs (v1.6.0): aguardthat refuses anything but av*tag matchingpackage.jsonbefore any approval is asked; abuildthat runs the publish gate and packs the tarball once, recording its SHA-256 and SHA-512, without the right to mint a token; apublishbehind the protectednpm-publishenvironment that installs nothing, verifies the handed-on tarball against those digests and uploads exactly it through GitHub OIDC (no long-lived token) with an npm client pinned by the SHA-512 of its registry tarball,npm publish --provenance; and anattestthat fetches the published tarball back from the registry, checks it against the same digests andnpm audit signatures, and attests the bytes npm serves together with the CycloneDX and SPDX SBOMs and a toolchain SBOM, attaching them and the Sigstore bundle to the GitHub release. The provenance is SLSA Build L2 (hosted platform, signed provenance). Verify an install withnpm audit signatures. - One release gate —
npx tsx scripts/gate.ts --publish --require-allruns typecheck, lint, the build, the built-binary smoke test, the bundle-size budget, the bundle probe (the engine stays external; no font data, PEM block,console.logor undeclaredrequireindist/cli.cjs), the sample generation, the tests with coverage, the docs verifier, the sample baseline, the PDF/A corpus (veraPDF 1.30.2, installer SHA-256 verified), the PDF/X corpus and the previous release's suite (compat:previous); a skipped step fails the publish. - Branch and tag protection —
.github/rulesets/main.jsonandtags.jsonare the committed copies of the GitHub rulesets (required checksci (22),ci (24),windows,macos,compat-previous,workflow lint,sample-regression; release tags are never deleted or moved). - OpenSSF Scorecard — scanned weekly on
main(scorecard.yml, results in the Security tab). Two findings are deliberate and stay: theattestjob holdscontents: writeat the job level (the pipeline's only write grant, needed to attach the files to the release), and that job installspdfnative-cli@<exact version>with--ignore-scriptsinto a throwaway project after checking the tarball against the build digests, becausenpm audit signaturesverifies an installed tree (Scorecard reads everynpm installas unpinned). Code review by a second maintainer is not available in a single-maintainer project; the seven required checks, CodeQL, the previous release's suite replayed on every pull request, the fuzzers and thenpm-publishenvironment approval stand in for it. The OpenSSF Best Practices badge is in progress. - Agents never publish — the human-in-the-loop policy (
.github/AGENT_RULES.md,pdfnative govern) is enforced in Claude Code sessions by.claude/hooks/guard.mjs, which refusesnpm publish,git push,git tag,gh pr/issue/releasewrites.
We follow coordinated disclosure. We ask that you:
- Report vulnerabilities privately (see above).
- Allow us reasonable time to fix and release a patch before public disclosure.
- Avoid testing against systems you do not own.