@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/sig/sign.md

@@ -0,0 +1,317 @@
+---
+module: pdfSign
+category: pdf/sig
+dependencies: [pdfErrors, pdfSigOids, pdfByteRange, pdfDssBuilder, pdfIncrementalWriter, pdfParser, asn1, rsa, ecc, ed25519, sha256, sha384, sha512, bitArray, pdfDocument, pdfSecurity, pdfStandardV4, pdfStandardV5, pdfStandardV6]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSign
+
+> PAdES signature generation (write side) — levels B / T / LT / LTA.
+
+**Module** `pdfSign` | **Source** `packages/front/office/pdf/src/sig/sign.js` | **Deps** `pdfErrors`, `pdfSigOids`, `pdfByteRange`, `pdfDssBuilder`, `pdfIncrementalWriter`, `pdfParser`, `asn1`, `rsa`, `ecc`, `ed25519`, `sha256`, `sha384`, `sha512`, `bitArray`, `pdfDocument`, `pdfSecurity`, `pdfStandardV4`, `pdfStandardV5`, `pdfStandardV6` | **Worker-safe** yes
+
+Companion of [`pdfSignature`](./signature.md) (verify side). Produces a
+detached PKCS#7/CMS `SignedData` blob and embeds it into a signature
+dictionary whose `/ByteRange` covers the whole document minus the
+whole `/Contents` `<…>` token, delimiters included (ISO 32000-2 §12.8.3.3.1
+— see [`pdfByteRange`](./byteRange.md)); `_emitWithPlaceholder`'s
+`contentsOffset` / `contentsLength` still name the hex-digit span. Algorithms: RSA-PSS, ECDSA (P-256/P-384/P-521),
+Ed25519 — PKCS#1 v1.5 is deliberately refused (fw policy, NIST SP
+800-131A Rev.2). ECDSA signature values are DER `ECDSA-Sig-Value`
+(RFC 3279 §2.2.3); Ed25519 always uses SHA-512 (RFC 8419 §3.1).
+**Default `subFilter` is `adbe.pkcs7.detached`** — a PAdES
+emitter MUST explicitly pass `subFilter: 'ETSI.CAdES.detached'`.
+
+## PAdES levels
+
+| Level | Requires | Behavior |
+|-------|----------|----------|
+| `B` (default) | — | Single embedded signature, `eContentInfo` absent, no `signedAttrs` unless `opts.useSignedAttrs`. |
+| `T` | `opts.tsaSign` callback | Adds `signedAttrs` (contentType, messageDigest, signingTime, ESS `signing-certificate-v2`) and an `unsignedAttrs` RFC 3161 timestamp token. |
+| `LT` | `T` requirements + `pdfDssBuilder`/`pdfDocument` (always present via the registered `modules` deps) | As `T`, then appends a DSS (`/Certs`, `/OCSPs`, `/CRLs`, `/VRI`) and an updated Catalog via an incremental update. |
+| `LTA` | `LT` requirements | As `LT`, then appends a second incremental update carrying a `/DocTimeStamp` (fresh `tsaSign` call over the LT bytes). |
+
+Every level signs by **incremental update** (§7.5.6, non-destructive): the
+base bytes are kept verbatim and the signature object is appended through
+[`pdfIncrementalWriter`](../document/incrementalWriter.md). The update section
+therefore takes the form of the base's newest cross-reference section
+(classical table or cross-reference stream), and its `/Root`, `/Info` and
+`/ID` come from the newest-first merged trailer. The signature takes the
+first object number at or past the merged `/Size`, so an object held in an
+object stream is never overwritten. The fixed-width `/ByteRange`
+and `/Contents` placeholders are found inside the signature object from its
+own offset, and they are patched without changing the byte length. `LT`
+adds a second update: the DSS, plus the Catalog re-defined under its own
+number with `/DSS`. The Catalog is resolved through `readDocument` from the
+trailer `/Root`, wherever it lives, including inside an object stream.
+`LTA` adds a third update, the DocTimeStamp, appended the same way
+as the signature. A hybrid-reference base (a classical trailer carrying
+`/XRefStm`) is refused, and nothing is written.
+
+The `pdfParser` dependency is no longer read. It keeps its position so that
+code calling the factory with positional arguments still works.
+`pdfDocument` comes next. Every level needs it, because the signature
+field is written from the Catalog and page 1 that `readDocument` resolves.
+`pdfSecurity`, `pdfStandardV4`, `pdfStandardV5` and `pdfStandardV6` are
+appended last. They are read only when the base is encrypted, so a
+hand-wired factory that signs only unencrypted documents may pass `null`
+for them.
+
+## What the update contains
+
+ISO 32000-2 §12.7.5.5 makes a signature dictionary the value (`/V`) of a
+signature field (`/FT /Sig`), and §12.8.5.2 says a document timestamp is
+found the same way, by examining signature fields. So the incremental
+update that carries a signature dictionary also carries the field that
+holds it:
+
+| Object | Content |
+|--------|---------|
+| Signature dictionary | `/Type /Sig` (`/Type /DocTimeStamp` for the LTA timestamp), `/Filter /Adobe.PPKLite`, `/SubFilter`, `/ByteRange`, `/Contents`. It takes the first object number at or past the merged `/Size`. |
+| Field / widget | One object, the field dictionary merged with its widget annotation (§12.7.4, §12.5.6.19), numbered right after the signature: `/Type /Annot`, `/Subtype /Widget`, `/FT /Sig`, `/T (Signature<n>)`, `/V` → the signature dictionary, `/Rect [0 0 0 0]` (invisible), `/F 132` (Print + Locked), `/P` → page 1. `<n>` is the lowest index no root field of the document already uses, so a second `sign()` writes `Signature2`. |
+| Page 1 | Re-emitted under its own number with the widget appended to `/Annots`. If `/Annots` is an indirect array, that array object is re-emitted instead and the page is not. Page 1 is the first leaf of the page tree. |
+| `/AcroForm` | `/Fields` gets the new field appended, and `/SigFlags` is set to `3` (SignaturesExist + AppendOnly). An indirect `/AcroForm` is re-emitted under its own number. A direct or absent one is written into a re-emission of the Catalog. An indirect `/Fields` array is re-emitted under its own number. |
+
+Every entry these objects already had is copied as it is, so existing form
+fields, annotations and `/AcroForm` keys (`/DA`, `/DR`, `/NeedAppearances`
+and so on) are kept. All new objects come before the update's
+cross-reference section, so the `/ByteRange` covers them like every other
+byte. `LT` copies the Catalog, `/AcroForm` included, when it adds `/DSS`.
+`LTA` then appends a second field for its `/DocTimeStamp` in the timestamp's
+own update.
+
+### Ed25519: the ISO/TS 32002 declaration
+
+EdDSA signatures come from ISO/TS 32002, which requires "PDF documents
+using enhancements described in this document" to declare it in the
+Catalog (ISO/TS 32002 §4). For `algorithm: 'ed25519'`, at every level and
+with every `subFilter`, the signing update therefore also re-emits the
+Catalog under its own number with:
+
+- `/Extensions` holding the prefix `ISO_` → a developer extensions
+  dictionary (ISO 32000-2 §7.12.3) with exactly `/Type /DeveloperExtensions`,
+  `/BaseVersion /2.0`, `/ExtensionLevel 32002`, `/ExtensionRevision (:2022)`
+  and `/URL (https://www.iso.org/standard/45875.html)`;
+- `/Version /2.0` when the document's effective version is below 2.0: the
+  Catalog `/Version` name when there is one, else the header version
+  (ISO 32000-2 §7.7.2, the entry exists so that an incremental update can
+  raise the version; ISO/TS 32002 Table 2 marks EdDSA as PDF 2.x). A PDF 2.0
+  document gets no `/Version` entry. A `/Version` that is not a name counts
+  as absent.
+
+The declaration is merged with what the document already has (ISO 32000-2
+§7.12.2: the value of a prefix is a developer extensions dictionary or an
+array of them):
+
+| Existing `/Extensions` | Result |
+|------------------------|--------|
+| absent | `<< /ISO_ ext >>` |
+| present, no `ISO_` | `ISO_` added; the other prefixes (`ADBE_`, …) kept |
+| `ISO_` a dictionary at `/ExtensionLevel 32002` | unchanged — signing an already declared document again adds nothing |
+| `ISO_` a dictionary at another level | `ISO_` becomes the array `[existing ext]` |
+| `ISO_` an array | `ext` appended, unless an element is already at level 32002 |
+| any of these held by an indirect reference | resolved; the merged result is written as a direct dictionary in the Catalog, the referenced object stays in the file, no longer referenced by it |
+| any other shape (`/Extensions 5`, an `ISO_` string, an array element that is not a dictionary) | `pdf/sign/bad-extensions`, nothing written |
+
+The Catalog is re-emitted whenever the declaration or the version changes
+it, including when the `/AcroForm` is indirect (otherwise the signature
+field alone does not touch the Catalog); every other Catalog entry is
+copied as it is. The `LT` and `LTA` updates copy the Catalog, so the
+declaration stays in the newest Catalog. ECDSA and RSA-PSS signatures do
+not touch `/Extensions` or `/Version`.
+
+**Viewers.** Adobe Acrobat Reader does not validate Ed25519 (EdDSA)
+signatures: it reports an error about the formatting of the signature,
+with or without the declaration, and also on an Ed25519 signature produced
+by OpenSSL (measured 2026-10-05). OpenSSL 3.5 and later verify them
+(`openssl cms -verify`). Use ECDSA P-256 where Acrobat interoperability
+matters — see the [PAdES guide](../../guide/pades-integration.md).
+
+### Encrypted base
+
+A base whose trailer carries `/Encrypt` gets the same field, with its
+field name encrypted:
+
+- **Password.** `opts.password` is required. It may be the owner or the
+  user password, and `''` is a valid empty user password. The document key
+  is derived from it through the standard security handler, once per
+  `sign()` call and before anything is written.
+- **Permissions.** With the user password, `/P` must grant bit 4 (modify)
+  and bit 6 (annotations and form fields), ISO 32000-2 Table 22. The owner
+  password is not checked against `/P`.
+- **Supported encryption.** AES only, for both the string and the stream
+  crypt filters: V=4 R=4 with `AESV2`, V=5 R=5 and V=5 R=6 with `AESV3`.
+  RC4 (V below 4, or a `/V2` crypt filter), AES-GCM (`AESV4`, ISO/TS
+  32003) and any handler other than `/Standard` are refused with a typed
+  error. Nothing is ever signed without its field.
+- **What is encrypted.** The new field's `/T` is encrypted with the string
+  crypt filter, keyed by the field's own object number, behind a fresh
+  16-byte IV from `opts.randomBytes` (default `crypto.getRandomValues`).
+  When the string filter is `Identity`, the name is written in clear.
+  The signature dictionary's `/Contents` is never encrypted (ISO 32000-2
+  §7.6.2), and `/ByteRange` holds integers. Re-emitted objects (Catalog,
+  page 1, `/AcroForm`, `/Fields`) keep their number and generation, so the
+  encrypted strings they already held keep their key.
+- **Ed25519 declaration.** The two new strings of the ISO/TS 32002
+  dictionary (`/ExtensionRevision`, `/URL`) are encrypted with the string
+  crypt filter under the Catalog's object number and generation, each
+  behind a fresh IV; names and integers are never encrypted. The strings
+  of an indirect `/Extensions` value that is inlined into the Catalog are
+  decrypted under their former object and encrypted again under the
+  Catalog's, since the V=4 key depends on the object number.
+- **Trailer.** Every incremental update written over an encrypted base
+  repeats the base's `/Encrypt` in its trailer or cross-reference stream
+  dictionary (ISO 32000-2 §7.5.6).
+- **Levels LT and LTA.** Levels LT and LTA are supported on an encrypted
+  base. The DSS certificate, OCSP and CRL streams, any VRI timestamp
+  stream and the VRI `/TU` string are encrypted with the document key
+  (stream and string crypt filters of the base's `/Encrypt`), as is the
+  DocTimeStamp field's `/T`. Each of these strings and streams gets its
+  own fresh 16-byte IV from `opts.randomBytes`. The hexadecimal
+  `/Contents` of the `/Sig` and `/DocTimeStamp` dictionaries is never
+  encrypted (ISO 32000-2 §7.6.2). Every incremental update repeats the
+  base's `/Encrypt` (§7.5.6). Copied objects (Catalog, page, AcroForm)
+  keep their existing ciphertext under their own object numbers.
+
+To pick a field name that is not taken yet, the existing root field names
+are decrypted first.
+
+### Signed attributes
+
+When signed attributes are emitted (levels T, LT and LTA, or
+`useSignedAttrs: true`), they are written in DER `SET OF` order. Each
+attribute is encoded first. The encodings are then sorted as unsigned byte
+strings, and an encoding that is a prefix of a longer one sorts first
+(X.690 §11.6). The signature covers these sorted bytes (RFC 5652 §5.4).
+A verifier that re-encodes the attributes before it checks the signature,
+as OpenSSL does for Ed25519, therefore checks the bytes that were signed.
+Signatures written in the earlier fixed order (contentType, messageDigest,
+signingTime, signing-certificate-v2) still verify with `pdfSignature`,
+which checks the attributes as received.
+
+## Resolve
+
+```js
+const s = runtime.resolve('pdfSign');
+// Returns: { sign, _buildPkcs7, _buildSignedAttrs, _sortDerSetOf,
+//            _buildUnsignedAttrsTsa, _extractIssuerSerial,
+//            _emitWithPlaceholder, _hashBytes, _toDer, HASH_TABLE }
+```
+
+The factory also returns internal helpers with a leading underscore,
+exposed for white-box testing only — prefer `sign` for the stable contract.
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `sign` | `(pdfBytes: Uint8Array, opts: SignOpts) => Uint8Array` | The signed PDF bytes: the base kept verbatim plus one incremental update for the signature and its field, then one for the DSS (`LT`/`LTA`) and one for the DocTimeStamp and its field (`LTA`). |
+| `HASH_TABLE` | `{ sha256, sha384, sha512 }` → `{ mod, oid, len }` | The supported digest algorithms, by `opts.hashAlg` name. |
+| `_buildPkcs7` / `_buildSignedAttrs` / `_sortDerSetOf` / `_buildUnsignedAttrsTsa` / `_extractIssuerSerial` / `_emitWithPlaceholder` / `_hashBytes` / `_toDer` | internal helpers | Returned for white-box tests only; not a stable contract — use `sign`. |
+
+### `SignOpts`
+
+```js
+{
+    cert: Uint8Array | string,        // X.509 DER bytes or PEM string
+    privateKey:                        // algorithm-specific:
+        { n, e, d }                    //   RSA-PSS — Uint8Array each
+      | { curve, secretKey }           //   ECDSA — ecc.curves.c256|c384|c521 + ecc.ecdsa.secretKey
+      | Uint8Array,                    //   Ed25519 — 64 bytes (seed || pub)
+    algorithm: 'rsa-pss' | 'ecdsa' | 'ed25519',
+    hashAlg?: 'sha256' | 'sha384' | 'sha512',  // default 'sha256'; 'sha512' only (and default) for Ed25519
+    level?: 'B' | 'T' | 'LT' | 'LTA',           // default 'B'
+    subFilter?: string,                          // default 'adbe.pkcs7.detached'
+    useSignedAttrs?: boolean,                    // default false for level 'B'
+    placeholderBytes?: number,                   // default 8192
+    docTimeStamp?: boolean,                      // internal — DocTimeStamp object emission
+    signingTime?: Date,
+    tsaSign?: (args: { digest, hashAlg }) => Uint8Array,  // required for T/LT/LTA
+    dss?: { certs?, ocsps?, crls?, vri?, autoVri?, vriTime? },  // LT/LTA — see pdfDssBuilder
+    docTimeStampPlaceholder?: number,            // LTA — default = placeholderBytes
+    password?: string | Uint8Array,              // encrypted base: owner or user password ('' = empty user password)
+    randomBytes?: (n: number) => Uint8Array      // encrypted base: IV source (field names, DSS strings and streams), default crypto.getRandomValues
+}
+```
+
+## Examples
+
+### Level B — RSA-PSS, PAdES `SubFilter`
+
+```js
+const s = runtime.resolve('pdfSign');
+const signed = s.sign(pdfBytes, {
+    cert, privateKey: { n, e, d },
+    algorithm: 'rsa-pss', hashAlg: 'sha256',
+    subFilter: 'ETSI.CAdES.detached'   // required for PAdES — not the default
+});
+```
+
+### Level T — with a timestamp authority callback
+
+```js
+const signed = s.sign(pdfBytes, {
+    cert, privateKey, algorithm: 'ecdsa',
+    level: 'T',
+    tsaSign: ({ digest, hashAlg }) => callRealTsa(digest, hashAlg) // returns RFC 3161 TimeStampToken DER
+});
+```
+
+### Level LTA — full chain with DSS + DocTimeStamp
+
+```js
+const signed = s.sign(pdfBytes, {
+    cert, privateKey, algorithm: 'ed25519',
+    level: 'LTA',
+    tsaSign: myTsaCallback,
+    dss: { certs: [leafDer, caDer], ocsps: [ocspDer], autoVri: true }
+});
+```
+
+## Errors
+
+Raised as `ContractError` unless noted.
+
+| Code | When |
+|------|------|
+| `pdf/sign/bad-input` | `pdfBytes` not `Uint8Array`, or a cert/privateKey argument neither `Uint8Array` nor PEM string. |
+| `pdf/sign/bad-opts` | `opts` missing or not an object. |
+| `pdf/sign/level-not-implemented` | `opts.level` outside `B`/`T`/`LT`/`LTA`. |
+| `pdf/sign/no-dss-builder` | Level `LT`/`LTA` requested without `pdfDssBuilder` wired. |
+| `pdf/sign/no-document-reader` | Any level requested without `pdfDocument` wired (the signature field needs the Catalog and page 1). |
+| `pdf/sign/no-incremental-writer` | Any level requested without `pdfIncrementalWriter` wired. |
+| `pdf/sign/no-algorithm` | `opts.algorithm` missing. |
+| `pdf/sign/bad-hash-alg` | `opts.hashAlg` outside `sha256`/`sha384`/`sha512`. |
+| `pdf/sign/ed25519-requires-sha512` | `algorithm: 'ed25519'` with an `opts.hashAlg` other than `sha512` (RFC 8419 §3.1); `context.hashAlg` names it. Omit `hashAlg` or pass `'sha512'`. |
+| `pdf/sign/tsa-required-for-level-T` | Level `T`/`LT`/`LTA` without `opts.tsaSign`. |
+| `pdf/sign/tsa-bad-result` / `tsa-bad-result-lta` | `tsaSign` did not return a `Uint8Array`. |
+| `pdf/sign/cert-parse` | Cert DER doesn't parse as a valid X.509 SEQUENCE (issuer/serial extraction). |
+| `pdf/sign/unknown-hash` / `unknown-sigalg` / `unknown-algorithm` | Unsupported `hashAlg`/`signatureAlg`/`algorithm` value reaching the PKCS#7 builder or signer dispatch. |
+| `pdf/sign/no-startxref` / `bad-startxref` | Base `pdfBytes` has no (or an unparsable) `startxref` — required to append the placeholder signature object. |
+| `pdf/sign/no-trailer` | No cross-reference section of the base supplies a usable `/Size` and `/Root`. |
+| `pdf/incremental/hybrid-base` (`RenderError`) | The base is a hybrid-reference file; propagated from `pdfIncrementalWriter`, nothing written. `pdf/incremental/unsupported-base` likewise when `startxref` designates neither a table nor an xref stream. |
+| `pdf/sign/br-placeholder-missing` / `br-overflow` | Internal `/ByteRange` / `/Contents` placeholder location or patching failed (should not occur in practice). |
+| `pdf/sign/no-rsa` / `no-ecc` / `no-ed25519` (`EncryptionError`) | The matching fw crypto primitive (`rsa.pssSign`, `ecc.ecdsa`, `ed25519.sign`) is unavailable. |
+| `pdf/sign/bad-rsa-key` / `bad-ecdsa-key` / `bad-ed25519-key` | `privateKey` shape doesn't match the selected `algorithm`. |
+| `pdf/sign/rsa-failed` / `ed25519-failed` (`EncryptionError`) | The underlying fw signer returned `false`. |
+| `pdf/sign/pkcs7-too-large` | The built PKCS#7 blob exceeds `placeholderBytes`. |
+| `pdf/sign/hex-overflow` / `dts-hex-overflow` | PKCS#7 (or TimeStampToken) hex exceeds the reserved `/Contents` placeholder length. |
+| `pdf/sign/tst-too-large` | LTA `DocTimeStamp` TimeStampToken exceeds its placeholder. |
+| `pdf/sign/bad-extensions` | `algorithm: 'ed25519'` and the Catalog `/Extensions` (or its `ISO_` entry, or an element of an `ISO_` array) is not a dictionary, an array of dictionaries or a reference to one (ISO 32000-2 §7.12). `context: { shape }` names the offending value's type. Nothing is written. |
+| `pdf/sign/catalog-not-found` | The trailer `/Root` does not resolve to a dictionary (signature field, or the LT/LTA Catalog update). |
+| `pdf/sign/no-security-handler` | Encrypted base, and `pdfSecurity`, `pdfStandardV4`, `pdfStandardV5` or `pdfStandardV6` is not wired. |
+| `pdf/sign/encrypted-password-required` | Encrypted base without `opts.password`. Pass `''` for an empty user password. |
+| `pdf/sign/encrypted-bad-password` | `opts.password` is neither the owner nor the user password. The password is not echoed in the error. |
+| `pdf/sign/encrypted-unsupported` | Encryption that cannot be signed: `context.filter` names a handler other than `Standard`; `context.reason` is `'rc4'` (V below 4, or a `/V2` crypt filter), `'aes-gcm'` (`AESV4`) or `'no-id'` (V=4 without a trailer `/ID`); `context.cause` carries the handler's error code for an unreadable or unsupported `/Encrypt`. |
+| `pdf/sign/encrypted-permission-denied` | User password, and `/P` lacks bit 4 or bit 6. `context: { P, required: ['modify', 'annot'] }`. Use the owner password. |
+| `pdf/sign/no-random` (`EncryptionError`) | Encrypted base, and neither `opts.randomBytes` nor `crypto.getRandomValues` is available for the IV. |
+
+## See also
+
+- [`pdfSignature`](./signature.md) — verify side (the counterpart this module's output is checked against).
+- [`pdfDssBuilder`](./dss.md) — DSS construction for levels LT/LTA.
+- [`pdfByteRange`](./byteRange.md) · [`pdfTimestamp`](./timestamp.md) · [`pdfCertChain`](./certChain.md)
+- [`pdfIncrementalWriter`](../document/incrementalWriter.md) — underlying append mechanism for every level.

package/docs/api/sig/signature.md

@@ -0,0 +1,178 @@
+---
+module: pdfSignature
+category: pdf/sig
+dependencies: [pdfErrors, pdfParser, pdfSigOids, asn1, rsa, ecc, ed25519, sha256, sha384, sha512, bitArray]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSignature
+
+> Digital signature handler — ISO 32000-2 §12.8 + ISO TS 32001 (CAdES) + ISO TS 32002 (Ed25519).
+
+**Module** `pdfSignature` | **Source** `packages/front/office/pdf/src/sig/signature.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfSigOids`, `asn1`, `rsa`, `ecc`, `ed25519`, `sha256`, `sha384`, `sha512`, `bitArray` | **Worker-safe** yes
+
+Typing and end-to-end verification of PDF signatures (detached PKCS#7/CMS). Supported SubFilters: `adbe.pkcs7.detached`, `adbe.pkcs7.sha1` (legacy), `ETSI.CAdES.detached`, `ETSI.RFC3161` (timestamp only), plus Ed25519 (ISO TS 32002). `verifySignature` reconstructs the `/ByteRange`-covered bytes, recomputes the digest, locates the signer's certificate inside the embedded PKCS#7 `SignedData`, and **does dispatch and execute** the public-key check itself (`rsa.pssVerify` / ECDSA / `ed25519.verify` via the internal `verifyPk` dispatcher) — see § *Semantics of `verified` vs `valid` vs `pkVerified`* below. The result's `valid` field is a deprecated alias of `verified`: read `verified`.
+
+## Resolve
+
+```js
+const sig = runtime.resolve('pdfSignature');
+// Returns: { typeSignature, verifySignature, verifyAllSignatures, verifyPk,
+//            locatePkcs7, DIGEST_OIDS, SIG_OIDS }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeSignature` | `(dict, refInfo?) => Signature` | Strict typing, §12.8.1 Table 252. |
+| `verifySignature` | `(typedSig, documentBytes, fwBundle?) => VerifyResult` | Full verification — digests `/ByteRange`, locates the signer cert, and runs the public-key check. |
+| `verifyAllSignatures` | `(documentBytes, fwBundle?) => { signatures: VerifyResult[], timestamps: TsVerifyResult[] }` | Scans the raw bytes for every `/Type /Sig` and `/Type /DocTimeStamp` object (across incremental updates) and verifies each. |
+| `verifyPk` | `(args: { algorithm, pubKey, signature, message?, digest?, hashMod?, sLen? }) => { verified: boolean, code?: string, error?: string }` | Public-key verification primitive dispatcher — routes to `rsa.pssVerify` (`'rsa-pss'`), fw's deliberate RSA PKCS#1 v1.5 refusal (`'rsa-v15'`/`'rsa'`), ECDSA (`'ecdsa'`/`'ecc'`) or `ed25519.verify` (`'ed25519'`). For ECDSA, `signature` is the DER `ECDSA-Sig-Value` or the legacy fixed-width raw r‖s (DER tried first; anything else → `pdf/sig/verify-pk/bad-ecdsa-sig`). |
+| `locatePkcs7` | `(blob: Uint8Array, asn1Mod?) => asn1Children \| false` | Decodes the CMS `ContentInfo` → `SignedData` and returns its parsed children (`false` on malformed input). |
+
+`DIGEST_OIDS` and `SIG_OIDS` (constants, re-exported from `pdfSigOids`) are also returned for callers that need to map OIDs to algorithm names directly.
+
+The factory also returns five internal helpers with a leading underscore
+(`_hashByteRange`, `_scanSignatureObjects`, `_verifyPkcs7Signature`,
+`_verifyTsaSignature`, `_ecdsaSigToRaw`) — exposed for internal reuse/testing, not part of the
+stable public contract; prefer the methods above.
+
+### Shape `Signature`
+
+```js
+{
+    kind: 'Sig' | 'DocTimeStamp',
+    filter, subFilter, contents: Uint8Array,
+    byteRange: [start1, len1, start2, len2],
+    reference, cert, name, m, location, reason, contactInfo,
+    v, propBuild, propAuthTime, propAuthType,
+    raw   // the source dict
+}
+```
+
+## Examples
+
+### Semantics of `verified` vs `valid` vs `pkVerified`
+
+`verifySignature(...)` returns:
+
+```js
+{
+    verified:    true,           // public-key check executed AND succeeded
+    valid:       true,           // deprecated alias of verified
+    pkVerified:  true,           // explicit strict-crypto boolean
+    errors:      [ /* { code, message, context?, cause? } */ ],
+    signerCerts: [ /* { der } */ ],
+    hashAlg:     'sha256' | 'sha384' | 'sha512' | null,
+    signatureAlg:'rsa' | 'rsa-pss' | 'ecc' | 'ed25519' | null,
+    computedDigest: Uint8Array | null   // digest recomputed over /ByteRange
+}
+```
+
+`valid` is a **deprecated alias of `verified`**: it always carries the same
+value, is kept for compatibility, and will be removed in a future major
+version. Read `verified`. The same holds for the `valid` field of each
+`verifyAllSignatures` entry, signatures and document timestamps alike.
+
+`verified` / `pkVerified` are `true` only when the public-key check
+(`verifyPk`, dispatched internally) actually ran and succeeded against the
+signer's certificate SPKI. There is **no** `pdf/sig/pk-verify-not-wired`
+code in this module — the public-key verification path is wired by
+construction; a failed check surfaces a specific `errors[]` record instead
+(e.g. `pdf/sig/pk-verify-failed`, `pdf/sig/rsa-pkcs1v15-deprecated` for the
+deliberately-refused legacy scheme).
+
+### Structural verification + digest
+
+```js
+const sig = runtime.resolve('pdfSignature');
+const typed = sig.typeSignature(sigFieldDict.v);
+const result = sig.verifySignature(typed, documentBytes, fwBundle);
+result.verified;                 // true when the PK check passed
+result.computedDigest;           // Uint8Array — /ByteRange digest
+result.pkVerified;                // strict-crypto boolean, same as `verified`
+```
+
+### Multi-signature + timestamp scan
+
+```js
+const sig = runtime.resolve('pdfSignature');
+const { signatures, timestamps } = sig.verifyAllSignatures(documentBytes, fwBundle);
+signatures.every((s) => s.verified);
+timestamps.every((t) => t.verified);
+```
+
+Each `timestamps[]` entry (`TsVerifyResult`) has this shape:
+
+```js
+{
+    objNum, objGen,                 // the /DocTimeStamp object
+    verified:        true,          // imprint matches AND the gap is exact
+    valid:           true,          // deprecated alias of verified
+    kind:            'DocTimeStamp',
+    subFilter:       'ETSI.RFC3161' | string | null,
+    hashAlg:         'sha256' | 'sha384' | 'sha512' | string | null,
+    tstInfo:         { hashAlg, imprint, rawSd } | null,
+    imprintVerified: true,          // messageImprint == /ByteRange digest (imprint outcome alone)
+    tsaVerified:     false,         // TSA signature check — informational
+    gapForm:         'token' | 'digits' | null,
+    errors:          [ /* { code, message, context?, cause? } */ ],
+    signerCerts:     [ /* the TSA signer certificates, when located */ ]
+}
+```
+
+`gapForm` names the accepted `/ByteRange` gap form, in the vocabulary of
+`pdfByteRange.auditByteRange`: `'token'` when the gap is exactly the whole
+`<…>` token of the `/Contents` value, `'digits'` when it is exactly its hex
+digits, `null` for any other gap. It is present on every entry, failure
+paths included. A non-exact gap adds a
+`pdf/sig/byterange/gap-start-mismatch` / `gap-end-mismatch` record to
+`errors[]` and leaves `verified: false` even when `imprintVerified` is
+`true`; the earlier `pdf/ts/*` failures keep their first error code.
+`signatures[]` entries carry `objNum` / `objGen` plus the `verifySignature`
+result shape above, with no `gapForm` key.
+
+### Inspecting the decoded CMS
+
+```js
+const sd = sig.locatePkcs7(typed.contents);
+// sd is the parsed SignedData children array (ASN.1 nodes), or `false`.
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/sig/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/sig/bad-type` | `ParseError` | `/Type` is neither `/Sig` nor `/DocTimeStamp`. |
+| `pdf/sig/missing-filter` | `ParseError` | `/Filter` missing. |
+| `pdf/sig/missing-subfilter` | `ParseError` | `/SubFilter` missing. |
+| `pdf/sig/unknown-subfilter` | `ParseError` | SubFilter outside the supported set. |
+| `pdf/sig/missing-contents` | `ParseError` | `/Contents` missing. |
+| `pdf/sig/missing-byterange` | `ParseError` | `/ByteRange` missing. |
+| `pdf/sig/bad-byterange` | `ParseError` | `/ByteRange` malformed (≠ 4 integers). |
+| `pdf/sig/missing-fw` | `EncryptionError` | fw bundle incomplete for `verifySignature`. |
+| `pdf/sig/byterange/inconsistent` | `ParseError` | ByteRange offsets inconsistent with the document length. |
+| `pdf/sig/pkcs7-malformed` | record `errors[]` | PKCS#7 `SignedData` parse failed. |
+| `pdf/sig/no-signer` / `empty-signers` / `bad-signer` | record `errors[]` | `signerInfos` absent / empty / malformed. |
+| `pdf/sig/unknown-digest` / `unknown-sigalg` | record `errors[]` | digestAlgorithm / signatureAlgorithm OID outside the supported set. |
+| `pdf/sig/no-hash` | record `errors[]` | Hash module unavailable for the resolved `hashAlg`. |
+| `pdf/sig/signer-info-short` / `no-encrypted-digest` | record `errors[]` | SignerInfo ASN.1 shape unexpected. |
+| `pdf/sig/digest-failed` | record `errors[]` | Failed to recompute the `/ByteRange` digest. The record is `{ code, message }`: the underlying error's message is appended to `message`, and no `cause` is attached. |
+| `pdf/sig/signed-attrs-parse-failed` / `digest-not-computed` / `digest-length-mismatch` / `digest-mismatch` / `no-message-digest-attr` | record `errors[]` | `signedAttrs` present but its `messageDigest` attribute fails to parse or match. |
+| `pdf/sig/signer-cert-not-found` | record `errors[]` | No embedded cert matches the SignerInfo's `IssuerAndSerialNumber`. |
+| `pdf/sig/spki-*` (`cert-parse`, `not-found`, `malformed`, `rsa-parse`, `rsa-fields`, `ecc-not-uncompressed`, `ed25519-bad-len`, `unsupported-alg`) | record `errors[]` | SubjectPublicKeyInfo extraction/shape failure. |
+| `pdf/sig/byterange/gap-start-mismatch` / `gap-end-mismatch` | record `errors[]` (`verified: false`) | `/Sig` and `/DocTimeStamp`: the `/ByteRange` gap is neither exactly the hex digits of `/Contents` nor exactly its whole `<…>` token — both forms are accepted, every other gap is refused by `verifySignature` / `verifyAllSignatures` (a `/Sig`) and by `verifyAllSignatures` (a `/DocTimeStamp`, whose `imprintVerified` still reports the imprint outcome alone). The `timestamps[]` entry names the accepted form in `gapForm`. |
+| `pdf/sig/byterange-concat-failed` | record `errors[]` | Failed to extract the ByteRange-covered bytes for the fallback signed-payload path. |
+| `pdf/sig/pk-verify-failed` | record `errors[]` | `verifyPk` ran and returned `verified: false` (see `verifyPk` codes below). |
+| `pdf/sig/verify-pk/bad-args` / `no-alg` / `bad-sig` / `no-message` / `no-hash` / `no-rsa` / `bad-rsa-key` / `no-ecc` / `bad-ecc-key` / `unknown-curve` / `bad-ecc-point` / `bad-ecdsa-sig` / `no-digest` / `no-ed25519` / `bad-ed25519-key` / `unknown-alg` / `throw` | `verifyPk` return `{ code }` | Invalid inputs or dispatch failure inside `verifyPk`. |
+| `pdf/sig/rsa-pkcs1v15-deprecated` | `verifyPk` return `{ code }` | RSA PKCS#1 v1.5 is deliberately refused (NIST SP 800-131A Rev.2) — use RSA-PSS. |
+| `pdf/ts/*` (`empty-contents`, `parse-failed`, `unknown-hash`, `imprint-length-mismatch`, `imprint-mismatch`, `byterange-failed`, `no-ci`, `short-ci`, `no-sd`, `short-sd`, `no-eci`, `no-econtent`, `no-tst`, `short-tstinfo`, `no-imprint`, `tsa-no-sd`, `tsa-throw`) | record `errors[]` | Emitted by `verifyAllSignatures`'s `/DocTimeStamp` branch (RFC 3161 TimeStampToken parsing + TSA signature check). |
+
+## See also
+
+- [`pdfByteRange`](./byteRange.md) · [`pdfTimestamp`](./timestamp.md) · [`pdfCertChain`](./certChain.md)
+- [`pdfSignatureField`](../form/signature.md)

package/docs/api/sig/timestamp.md

@@ -0,0 +1,84 @@
+---
+module: pdfTimestamp
+category: pdf/sig
+dependencies: [pdfErrors, pdfSigOids, asn1, rsa, ecc, ed25519, sha256, sha384, sha512]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTimestamp
+
+> Document Timestamp + TSA tokens — ISO 32000-2 §12.8.5 / RFC 3161.
+
+**Module** `pdfTimestamp` | **Source** `packages/front/office/pdf/src/sig/timestamp.js` | **Deps** `pdfErrors`, `pdfSigOids`, `asn1`, `rsa`, `ecc`, `ed25519`, `sha256`, `sha384`, `sha512` | **Worker-safe** yes
+
+Parsing and verification of RFC 3161 Time-Stamp Authority tokens — used either as a standalone document timestamp (`SubFilter = ETSI.RFC3161`) or as an unsigned attribute of a signature for proof of existence. The module extracts `TSTInfo` (genTime, policy, messageImprint, serialNumber) and verifies the TSA signature against the embedded certificate.
+
+## Resolve
+
+```js
+const ts = runtime.resolve('pdfTimestamp');
+// Returns: { parseTimestampToken, verifyTimestamp,
+//            extractTimestampFromUnsignedAttrs,
+//            OID_TST_INFO, OID_AA_TIMESTAMP }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `parseTimestampToken` | `(blob: Uint8Array, asn1Mod?) => TstInfo` | Decodes the RFC 3161 ContentInfo. |
+| `verifyTimestamp` | `(blob: Uint8Array, fwBundle?) => VerifyResult` | Cryptographic verification. |
+| `extractTimestampFromUnsignedAttrs` | `(signedAttrs, asn1Mod?) => Uint8Array \| null` | Looks up `id-aa-timeStampToken` (1.2.840.113549.1.9.16.2.14). |
+| `OID_TST_INFO` | `string` (constant) | `id-ct-TSTInfo` OID (1.2.840.113549.1.9.16.1.4), used to validate `encapContentInfo`'s eContentType. |
+| `OID_AA_TIMESTAMP` | `string` (constant) | `id-aa-timeStampToken` OID, used by `extractTimestampFromUnsignedAttrs`. |
+
+### Shape `TstInfo`
+
+```js
+{
+    version, policy: oid,
+    serialNumber: Uint8Array,
+    messageImprint: { hashAlg, hashedMessage: Uint8Array } | null,
+    genTime: Date | null,
+    nonce?: Uint8Array, tsa?: Uint8Array
+}
+```
+
+## Examples
+
+### Document timestamp
+
+```js
+const ts = runtime.resolve('pdfTimestamp');
+const result = ts.verifyTimestamp(sig.contents);
+result.valid;
+result.tstInfo.genTime;     // Date — proof of existence
+```
+
+### Timestamp embedded in a signature
+
+```js
+const pk7 = runtime.resolve('pdfSignature').locatePkcs7(sig.contents);
+const tsBytes = ts.extractTimestampFromUnsignedAttrs(pk7.signerInfo.unsignedAttrs);
+if (tsBytes) {
+    const tstInfo = ts.parseTimestampToken(tsBytes);
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/ts/bad-input` | `ParseError` | Argument is not a Uint8Array. |
+| `pdf/ts/missing-fw` | `EncryptionError` | fw bundle incomplete. |
+| `pdf/ts/malformed` | `ParseError` | Invalid ASN.1 structure (ContentInfo, SignedData, or top-level TSTInfo). |
+| `pdf/ts/no-econtent` | `ParseError` | `encapContentInfo` has no `eContent`. |
+| `pdf/ts/wrong-econtent` | `ParseError` | eContentType ≠ `id-ct-TSTInfo`. |
+| `pdf/ts/no-tstinfo` | `ParseError` | TSTInfo not found inside eContent. |
+| `pdf/ts/bad-tstinfo` | `ParseError` | Required fields missing or mistyped. |
+
+## See also
+
+- [`pdfSignature`](./signature.md) · [`pdfByteRange`](./byteRange.md) · [`pdfCertChain`](./certChain.md)

package/docs/api/syntax/README.md

@@ -0,0 +1,29 @@
+# Syntax — ISO 32000-2 §7.2–§7.5
+
+Binary layer: `Uint8Array` → tokens → typed objects → xref table → trailer.
+
+| Module | Returns | Deps | Description |
+|--------|---------|------|-------------|
+| [`pdfTokenizer`](./tokenizer.md) | `{ tokenize, lastIndexOfBytes }` | `pdfErrors`, `pdfShared` | Lexer §7.2. |
+| [`pdfParserObj`](./parser-obj.md) | `{ obj, getEntry, isType }` | none | Typed-object builders and reflection helpers. |
+| [`pdfParser`](./parser.md) | `{ tokenize, parseObject, parseIndirect, parseFromBytes, parseIndirectFromBytes, parserLimits, setParserLimits, obj, getEntry, isType }` | `pdfErrors`, `pdfParserObj`, `pdfTokenizer` | Typed objects §7.3. |
+| [`pdfXref`](./xref.md) | `{ locateStartXref, readStartXref, parseXrefTable, parseTrailerDict, readXrefStreamDict, buildXrefStream }` | `pdfErrors`, `pdfTokenizer`, `pdfParser` | Classical table §7.5.4. |
+| [`pdfTrailer`](./trailer.md) | `{ typeTrailer }` | `pdfErrors`, `pdfParserObj` | Typed trailer §7.5.5. |
+| [`pdfSerializer`](./serializer.md) | `{ serializeObject, serializeIndirect, formatReal }` | `pdfErrors` | Object emission §7.3. |
+| [`pdfObjStream`](./objStream.md) | `{ parseObjectStream }` | `pdfErrors`, `pdfParserObj`, `pdfTokenizer`, `pdfParser` | Object streams §7.5.7. |
+| [`pdfCrossRefStream`](./crossRefStream.md) | `{ parseCrossRefStream }` | `pdfErrors`, `pdfParserObj` | Cross-reference streams §7.5.8. |
+| [Filters](./filters/README.md) | `{ decode, encode }` × 4 + dispatch | `pdfErrors`, `zlib` | The `/Filter` chain §7.4. |
+
+## Common pattern
+
+```js
+const tokMod = runtime.resolve('pdfTokenizer');
+const tok = tokMod.tokenize(bytes);
+let t;
+while ((t = tok.next())) { /* … */ }
+```
+
+## See also
+
+- [Document layer](../document/README.md)
+- [Read pipeline](../../guide/read-pdf.md)