@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/prepress/outputIntent.md

@@ -0,0 +1,79 @@
+---
+module: pdfOutputIntent
+category: pdf/prepress
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfOutputIntent
+
+> Output intent — ISO 32000-2 §14.11.5.
+
+**Module** `pdfOutputIntent` | **Source** `packages/front/office/pdf/src/prepress/outputIntent.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Describes the target rendering colour environment (`/Type /OutputIntent`), referenced from the Catalog's `/OutputIntents` array. Fields: `/S` (subtype — `GTS_PDFX` / `GTS_PDFA1` / `GTS_PDFA2` / etc., required), `/OutputCondition`, `/OutputConditionIdentifier`, `/RegistryName`, `/Info`, `/DestOutputProfile` (ICC stream ref), `/DestOutputProfileRef` (PDF 2.0 — ref to an external stream), `/MixingHints`, `/SpectralData`.
+
+## Resolve
+
+```js
+const oi = runtime.resolve('pdfOutputIntent');
+// Returns: { typeOutputIntent }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeOutputIntent` | `(dict) => OutputIntent` | Typing. |
+
+### Shape
+
+```js
+{
+    subtype,                            // /S, e.g. 'GTS_PDFA2'
+    outputCondition, outputConditionIdentifier,
+    registryName, info,
+    destOutputProfile,                  // ICC stream ref
+    destOutputProfileRef,               // PDF 2.0
+    mixingHints, spectralData,
+    raw, _extras
+}
+```
+
+## Examples
+
+### PDF/A conformance
+
+```js
+const oi = runtime.resolve('pdfOutputIntent');
+for (const ref of catalog.outputIntents) {
+    const o = oi.typeOutputIntent(doc._raw.resolve(ref));
+    if (o.subtype === 'GTS_PDFA2') console.log('PDF/A-2 ready');
+}
+```
+
+### ICC extraction
+
+```js
+const profile = doc._raw.resolve(o.destOutputProfile);
+// profile.raw → ICC bytes for downstream colour management
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/output-intent/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/output-intent/bad-type` | `ParseError` | `/Type` is not `/OutputIntent`. |
+| `pdf/output-intent/missing-s` | `ParseError` | `/S` is absent. |
+| `pdf/output-intent/bad-str` | `ParseError` | A string field is mistyped. |
+| `pdf/output-intent/bad-profile` | `ParseError` | `/DestOutputProfile` is neither a stream nor a ref. |
+| `pdf/output-intent/bad-profile-ref` | `ParseError` | `/DestOutputProfileRef` is neither a dict nor a ref. |
+| `pdf/output-intent/bad-mixing` | `ParseError` | `/MixingHints` is not a dict. |
+| `pdf/output-intent/bad-spectral` | `ParseError` | `/SpectralData` is not a dict. |
+
+## See also
+
+- [`pdfPageBoundary`](./pageBoundary.md) · [`pdfCatalog`](../document/catalog.md)

package/docs/api/prepress/pageBoundary.md

@@ -0,0 +1,75 @@
+---
+module: pdfPageBoundary
+category: pdf/prepress
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfPageBoundary
+
+> Page boundary boxes — ISO 32000-2 §14.11.2.
+
+**Module** `pdfPageBoundary` | **Source** `packages/front/office/pdf/src/prepress/pageBoundary.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Computes a page's effective boundary boxes following the §14.11.2 Table 31 inheritance rules:
+- `/MediaBox` — paper size, mandatory.
+- `/CropBox` — visible area, defaults to `MediaBox`.
+- `/TrimBox` — finished trim area, defaults to `CropBox`.
+- `/BleedBox` — bleed area, defaults to `CropBox`.
+- `/ArtBox` — meaningful content area, defaults to `CropBox`.
+
+Each box is `[llx, lly, urx, ury]`. The module accepts either an already-typed page record (with `mediaBox`/`cropBox`/… own fields) or a raw dict-shape object (`{ entries: { MediaBox, … } }` or `{ raw: { entries: {...} } }`), and validates the box shape (4 numeric elements) before returning it.
+
+## Resolve
+
+```js
+const pb = runtime.resolve('pdfPageBoundary');
+// Returns: { effectiveMediaBox, effectiveCropBox, effectiveTrimBox, effectiveBleedBox, effectiveArtBox }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `effectiveMediaBox` | `(page) => [number,number,number,number]` | Throws if absent. |
+| `effectiveCropBox` | `(page) => Box` | Falls back to MediaBox. |
+| `effectiveTrimBox` | `(page) => Box` | Falls back to CropBox. |
+| `effectiveBleedBox` | `(page) => Box` | Falls back to CropBox. |
+| `effectiveArtBox` | `(page) => Box` | Falls back to CropBox. |
+
+`page` is the output of [`pdfPage.typePage`](../document/page.md).
+
+## Examples
+
+### Imposition
+
+```js
+const pb = runtime.resolve('pdfPageBoundary');
+for (const page of doc.pages) {
+    const trim  = pb.effectiveTrimBox(page);
+    const bleed = pb.effectiveBleedBox(page);
+    const margin = trim[0] - bleed[0];   // left bleed margin
+}
+```
+
+### Screen rendering
+
+```js
+const view = pb.effectiveCropBox(page);
+canvas.width  = view[2] - view[0];
+canvas.height = view[3] - view[1];
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/page-boundary/bad-box` | `ParseError` | Box is not a 4-element array. |
+| `pdf/page-boundary/bad-box-element` | `ParseError` | A box element is non-numeric. |
+| `pdf/page-boundary/no-mediabox` | `ParseError` | `/MediaBox` absent along the inheritance chain. |
+
+## See also
+
+- [`pdfPage`](../document/page.md) · [`pdfOutputIntent`](./outputIntent.md)

package/docs/api/sig/README.md

@@ -0,0 +1,32 @@
+# Digital Signatures — ISO 32000-2 §12.8
+
+PKCS#7 detached + CAdES + RFC 3161 timestamps, generation (`pdfSign`) and verification (`pdfSignature`/`pdfTimestamp`/`pdfCertChain`), plus the PAdES-LT Document Security Store builder (`pdfDssBuilder`). Most modules are `fwModules` (fw-bound: `asn1`, `rsa`, `ecc`, `ed25519`, `sha256`, `sha384`, `sha512`, `bitArray`, `pem`); `pdfSigOids` and `pdfSha1` are lighter dispatch/legacy-hash helpers shared by the rest of the family.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfSignature`](./signature.md) | `{ typeSignature, verifySignature, verifyAllSignatures, verifyPk, locatePkcs7, DIGEST_OIDS, SIG_OIDS }` | `pdfErrors`, `pdfParser`, `pdfSigOids`, fw crypto | §12.8 + ISO TS 32001/32002 — verify. |
+| [`pdfSign`](./sign.md) | `{ sign, HASH_TABLE, … }` (plus `_`-prefixed test helpers) | `pdfErrors`, `pdfSigOids`, `pdfByteRange`, `pdfDssBuilder`, `pdfIncrementalWriter`, `pdfParser`, `pdfDocument`, fw crypto | PAdES generation, levels B/T/LT/LTA. |
+| [`pdfByteRange`](./byteRange.md) | `{ computeByteRange, extractSignedBytes, findContentsField, auditByteRange }` | `pdfErrors` | `/ByteRange` §12.8.1 + hardened audit. |
+| [`pdfTimestamp`](./timestamp.md) | `{ parseTimestampToken, verifyTimestamp, extractTimestampFromUnsignedAttrs, OID_TST_INFO, OID_AA_TIMESTAMP }` | `pdfErrors`, `pdfSigOids`, fw crypto | RFC 3161 §12.8.5. |
+| [`pdfCertChain`](./certChain.md) | `{ parseCertificate, extractCertsFromCms, extractCertFromPem, findIssuer, validateChainOrder }` | `pdfErrors`, `pdfSigOids`, fw `asn1`, `pem` | X.509 chain §12.8.3. |
+| [`pdfDssBuilder`](./dss.md) | `{ buildDss }` | `pdfErrors`, `pdfSha1`, `bitArray` | PAdES-LT Document Security Store, §12.8.4.3. |
+| [`pdfSigOids`](./oids.md) | `{ DIGEST_OIDS, SIG_DISPATCH_OIDS, KEY_ALG_OIDS, SIG_ALG_OIDS_VERBOSE, OID_TST_INFO, OID_AA_TIMESTAMP, lookupDigest, lookupSigAlg, lookupKeyAlg, lookupSigVerbose, shortOid }` | `asn1Oid` | Shared OID dispatch tables. |
+| [`pdfSha1`](./sha1.md) | `{ fn, hash }` | `bitArray`, `utf8` | Legacy SHA-1 — DSS `/VRI` keys only. |
+
+## Verification pattern
+
+```js
+const sig = runtime.resolve('pdfSignature');
+const typed = sig.typeSignature(sigField.v);
+const result = sig.verifySignature(typed, documentBytes, fwBundle);
+// `result.verified` / `result.pkVerified` reflect the ACTUAL outcome of the
+// public-key check (RSA-PSS / ECDSA / Ed25519) — the check is wired and
+// executed by construction. There is no `pdf/sig/pk-verify-not-wired` code;
+// a failed check surfaces a specific `errors[]` record instead (see
+// `pdfSignature`'s Errors table).
+```
+
+## See also
+
+- [`pdfSignatureField`](../form/signature.md) — carrier in the AcroForm.
+- [Crypto](../crypto/README.md) — encryption (orthogonal).

package/docs/api/sig/byteRange.md

@@ -0,0 +1,120 @@
+---
+module: pdfByteRange
+category: pdf/sig
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfByteRange
+
+> `/ByteRange` computation and extraction — ISO 32000-2 §12.8.1.
+
+**Module** `pdfByteRange` | **Source** `packages/front/office/pdf/src/sig/byteRange.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+A signature's `/ByteRange` is an array `[start1 len1 start2 len2]` covering the whole document *except* the gap `[start1+len1, start2)` that holds the `/Contents` value. This module provides the mechanics: locating `/Contents` in the file bytes, computing the matching ByteRange, auditing a ByteRange against the file, and extracting the signed bytes (concatenation of the two ranges). Two gap forms exist in the field; see [Notes § Gap forms](#gap-forms).
+
+## Resolve
+
+```js
+const br = runtime.resolve('pdfByteRange');
+// Returns: { computeByteRange, extractSignedBytes, findContentsField, auditByteRange }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `computeByteRange` | `(docBytes, contentsOffset, contentsLength, opts?) => [s1, l1, s2, l2]` | Direct computation. Without `opts` the gap is the span given; `opts.token` makes it the `<…>` token (form b). |
+| `findContentsField` | `(docBytes, sigObjectOffset) => { offset, length }` | Hex-digit span of the `/Contents <…>` literal in the file (`offset` is the byte after `<`). |
+| `extractSignedBytes` | `(docBytes, byteRange) => Uint8Array` | Concatenation of the two intervals. |
+| `auditByteRange` | `(docBytes, byteRange, opts?) => { ok, issues, gapForm }` | Hardened audit (overlap, gap form, coverage). |
+
+### `computeByteRange(documentBytes, contentsOffset, contentsLength, opts?)`
+
+Returns `[0, gapStart, gapEnd, total - gapEnd]`. Without `opts` the gap is
+`[contentsOffset, contentsOffset + contentsLength)` — the historical
+call, unchanged. `opts.token` — `{ offset, length }`, the span of the whole
+`<…>` token — makes that span the gap (form b); it must enclose the digit
+span by exactly one byte on each side, and those bytes must be `<` and `>`,
+otherwise `pdf/sig/byterange/bad-token` is thrown. `pdfSign` calls it with
+`{ token: { offset: contentsOffset - 1, length: contentsLength + 2 } }`.
+
+### `auditByteRange(documentBytes, byteRange, opts?)`
+
+Non-throwing audit: returns `{ ok, issues, gapForm }` where each issue
+is a record `{ code, message, context }`. The caller decides whether to
+escalate to an error or a warning. `gapForm` is `'token'` (form b),
+`'digits'` (form a) or `null` — `null` when `opts.contents` is absent or
+the gap matches neither form. An accepted gap form does not mask the other
+checks: `ok` is `false` whenever any issue is recorded. `opts`:
+
+- `opts.contents` — `{ offset, length }` from `findContentsField` (the
+  hex-digit span); the gap must be exactly the `<…>` token or exactly the
+  digits. Any other gap records `gap-start-mismatch` and/or
+  `gap-end-mismatch`, measured against the token bounds.
+- `opts.others` — array of other `/ByteRange`s to cross-check, to
+  detect overlaps between concurrent signatures.
+- `opts.requireFullCoverage: true` — requires the second range to
+  reach `documentBytes.length`.
+
+## Examples
+
+### Hash the signature
+
+```js
+const br  = runtime.resolve('pdfByteRange');
+const sig = runtime.resolve('pdfSignature').typeSignature(dict);
+const signed = br.extractSignedBytes(docBytes, sig.byteRange);
+const hash = await crypto.subtle.digest('SHA-256', signed);
+```
+
+### Locate `/Contents` to re-sign (form b)
+
+```js
+const pos = br.findContentsField(docBytes, sigObjOffset);   // hex digits
+const byteRange = br.computeByteRange(docBytes, pos.offset, pos.length, {
+    token: { offset: pos.offset - 1, length: pos.length + 2 }
+});
+br.auditByteRange(docBytes, byteRange, { contents: pos }).gapForm;  // 'token'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/sig/byterange/bad-input` | `ParseError` | Bytes argument is not a Uint8Array. |
+| `pdf/sig/byterange/bad-offset` | `ParseError` | Offset < 0 or out of bounds. |
+| `pdf/sig/byterange/bad-length` | `ParseError` | Length < 0 or out of bounds. |
+| `pdf/sig/byterange/overflow` | `ParseError` | `offset + length` > file size. |
+| `pdf/sig/byterange/bad-token` | `ParseError` | `computeByteRange` `opts.token` is not the `<…>` token enclosing the digit span. |
+| `pdf/sig/byterange/bad-shape` | `ParseError` | ByteRange is not a 4-integer array. |
+| `pdf/sig/byterange/inconsistent` | `ParseError` | A range entry is negative, a range extends past the document, or range 2 starts before range 1 ends. |
+| `pdf/sig/byterange/non-zero-start` | record `issues[]` | Range 1 does not start at 0. |
+| `pdf/sig/byterange/self-overlap` | record `issues[]` | Range 2 starts before range 1 ends. |
+| `pdf/sig/byterange/out-of-bounds` | record `issues[]` | A range extends past the end of the document. |
+| `pdf/sig/byterange/gap-start-mismatch` | record `issues[]` | The gap is neither form and range 1 does not end at the `/Contents` literal's `<` (`context.expected` = the token start). |
+| `pdf/sig/byterange/gap-end-mismatch` | record `issues[]` | The gap is neither form and range 2 does not start right after the `/Contents` literal's `>` (`context.expected` = the token end). |
+| `pdf/sig/byterange/cross-overlap` | record `issues[]` | Overlap with another `/ByteRange` (`opts.others`). |
+| `pdf/sig/byterange/incomplete-coverage` | record `issues[]` | Range 2 does not cover the document up to its end (`opts.requireFullCoverage`). |
+| `pdf/sig/byterange/no-contents` | `ParseError` | `/Contents` marker not found. |
+| `pdf/sig/byterange/contents-not-hex` | `ParseError` | `/Contents` is not a hex string (`<…>`). |
+| `pdf/sig/byterange/contents-unterminated` | `ParseError` | `<` opened without a matching `>`. |
+
+## Notes
+
+### Gap forms
+
+| Form | `gapForm` | The gap is | Who emits it |
+|---|---|---|---|
+| (b) token | `'token'` | the whole `<…>` hex string, both delimiters included | `pdfSign` today; PDFBox (`COSWriter`) and pyHanko (`DERPlaceholder`) |
+| (a) digits | `'digits'` | the hex digits only; `<` and `>` are signed | `pdfSign` in earlier versions |
+
+ISO 32000-2:2020 §12.8.3.3.1 (CMS signatures, the clause governing `adbe.pkcs7.detached`, `pdfSign`'s default `/SubFilter`; unchanged since ISO 32000-1 §12.8.3.3) states that `/Contents` "shall be a hexadecimal string with "<" and ">" delimiters" and that "it shall fit precisely in the space between the ranges specified by ByteRange" — form (b). For `ETSI.CAdES.detached` and `ETSI.RFC3161` the text only says "excluding the Contents value", and ETSI EN 319 142-1 §6.3 i) disapplies the explicit clause; both reference implementations use form (b) there too. No clause describes form (a). Hence the signer moved to form (b), and the verifier accepts both.
+
+`pdfSign` emits form (b) for the `/Sig` and the LTA `/DocTimeStamp`. `auditByteRange` accepts **exactly** form (a) or form (b), so a signature written by an earlier version still audits clean; any other gap (off by one at either end, a delimiter only, part of the digits) is refused. `pdfSignature.verifySignature` / `verifyAllSignatures` apply the same rule to every `/Sig`, and `verifyAllSignatures` to every `/DocTimeStamp` too: any other gap sets `verified: false` and adds the `gap-start-mismatch` / `gap-end-mismatch` records to `errors`; a `timestamps[]` entry also names the accepted form in `gapForm`, with this module's vocabulary (see [`pdfSignature`](./signature.md)). The digest is always taken over the ranges the file declares; neither form is special-cased there.
+
+## See also
+
+- [`pdfSignature`](./signature.md) · [`pdfTimestamp`](./timestamp.md)

package/docs/api/sig/certChain.md

@@ -0,0 +1,84 @@
+---
+module: pdfCertChain
+category: pdf/sig
+dependencies: [pdfErrors, pdfSigOids, asn1, pem]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfCertChain
+
+> X.509 chain extraction and ordering — ISO 32000-2 §12.8.3.
+
+**Module** `pdfCertChain` | **Source** `packages/front/office/pdf/src/sig/certChain.js` | **Deps** `pdfErrors`, `pdfSigOids`, `asn1`, `pem` | **Worker-safe** yes
+
+Parses the DER certificates embedded in a CMS blob (signature or timestamp), extracts `tbsCertificate` (issuer, subject, validity, subjectPublicKeyInfo), finds the issuer within a set of candidates, and validates chain ordering (leaf → CA → root). Performs **no** trust validation (no trust-anchor evaluation, no CRL/OCSP) — that is left to the caller.
+
+## Resolve
+
+```js
+const cc = runtime.resolve('pdfCertChain');
+// Returns: { parseCertificate, extractCertsFromCms, extractCertFromPem,
+//            findIssuer, validateChainOrder }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `parseCertificate` | `(der: Uint8Array, asn1Mod?) => Cert` | Decodes tbsCertificate. |
+| `extractCertsFromCms` | `(blob, asn1Mod?, opts?) => Cert[]` | Looks up the SignedData's `certificates [0]` field; malformed certs are skipped and reported via `opts.warnings` if supplied. |
+| `extractCertFromPem` | `(pemString, pemMod?, asn1Mod?) => Cert` | Decodes a single PEM certificate. |
+| `findIssuer` | `(cert, candidates) => Cert \| null` | Matches by `candidate.subject === cert.issuer`. |
+| `validateChainOrder` | `(chain: Cert[]) => { valid: boolean, errors: object[] }` | Checks ordering (each cert's `issuer` must equal the next cert's `subject`). |
+
+### Shape `Cert`
+
+```js
+{
+    version, serialNumber: Uint8Array,
+    issuer: string, subject: string,      // rendered RDN sequences
+    notBefore: Date | null, notAfter: Date | null,
+    publicKey: Uint8Array,                // raw SPKI BIT STRING value
+    keyAlgorithm: string, sigAlgorithm: string,
+    raw: Uint8Array                        // full certificate DER
+}
+```
+
+## Examples
+
+### Extraction and sort
+
+```js
+const cc = runtime.resolve('pdfCertChain');
+const certs = cc.extractCertsFromCms(sig.contents);
+const leaf  = certs.find((c) => c.subject === pkcs7SignerSubject);
+const issuer = cc.findIssuer(leaf, certs);
+```
+
+### Order validation
+
+```js
+const ok = cc.validateChainOrder([leaf, issuer, root]);
+if (!ok.valid) console.warn(ok.errors);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/cert/malformed` | `ParseError` | Invalid ASN.1. |
+| `pdf/cert/short` | `ParseError` | DER too short. |
+| `pdf/cert/bad-tbs` | `ParseError` | Malformed tbsCertificate. |
+| `pdf/cert/bad-input` | `ParseError` | `extractCertsFromCms` received a non-Uint8Array. |
+| `pdf/cert/missing-fw` | `EncryptionError` | `asn1` bundle missing. |
+| `pdf/cert/bad-pem-input` | `ParseError` | PEM argument is not a string. |
+| `pdf/cert/missing-pem` | `EncryptionError` | `pem` provider not supplied. |
+| `pdf/cert/pem-decode-failed` | `ParseError` | Malformed PEM. |
+| `pdf/cert/empty-chain` | record `errors[]` | `validateChainOrder` received a non-array or empty chain. |
+| `pdf/cert/chain-break` | record `errors[]` | A cert's `issuer` does not equal the next cert's `subject`. |
+
+## See also
+
+- [`pdfSignature`](./signature.md) · [`pdfTimestamp`](./timestamp.md)

package/docs/api/sig/dss.md

@@ -0,0 +1,111 @@
+---
+module: pdfDssBuilder
+category: pdf/sig
+dependencies: [pdfErrors, pdfSha1, bitArray]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfDssBuilder
+
+> PAdES-LT Document Security Store builder — ETSI EN 319 142-1 §5.4 / ISO 32000-2:2020 §12.8.4.3.
+
+**Module** `pdfDssBuilder` | **Source** `packages/front/office/pdf/src/sig/dss.js` | **Deps** `pdfErrors`, `pdfSha1`, `bitArray` | **Worker-safe** yes
+
+Produces the indirect objects (cert/OCSP/CRL streams, the `/DSS` dict, and
+optionally a `/VRI` dict) that a level-LT/LTA signer appends to an
+already-signed PDF via [`pdfIncrementalWriter`](../document/incrementalWriter.md).
+The factory **does not touch the byte buffer** — it returns a plan of
+`{ num, gen, value }` updates plus the allocated DSS object number, so the
+caller can also append an updated Catalog carrying `/DSS dssNum 0 R`.
+`pdfSha1` is used solely for VRI key derivation (ISO 32000-2 §12.8.4.3
+mandates SHA-1 of the signature value as the `/VRI` dict key — legacy
+requirement, unrelated to signature strength).
+
+## Resolve
+
+```js
+const dss = runtime.resolve('pdfDssBuilder');
+// Returns: { buildDss }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `buildDss` | `(args: BuildDssArgs) => BuildDssResult` | The update plan for an incremental append. It returns plaintext typed objects; when signing an encrypted document `pdfSign` encrypts the streams and strings before writing them. |
+| `_refObj` / `_intObj` / `_nameObj` / `_strHexObj` / `_arrayObj` / `_dictObj` / `_streamObj` / `_sha1` / `_toHexUpper` / `_scanSignatureContentsHex` / `_pdfDate` | internal helpers | Returned for white-box tests only; not a stable contract — use `buildDss`. |
+
+### `BuildDssArgs`
+
+```js
+{
+    startNum: number,          // required, >= 2 — first free object number
+    certs?:  Uint8Array[],     // DER-encoded certificates
+    ocsps?:  Uint8Array[],     // DER-encoded OCSP responses
+    crls?:   Uint8Array[],     // DER-encoded CRLs
+    vri?:    { [sigHashHex: string]: {
+        certs?: number[] | Uint8Array[],   // indices into certs[], or raw DER to promote
+        ocsps?: number[] | Uint8Array[],
+        crls?:  number[] | Uint8Array[],
+        tu?:    string,        // PDF date string — validation-data-obtained time
+        ts?:    Uint8Array     // TimeStampToken DER, promoted to a /TS stream
+    } },
+    autoVri?:  boolean,        // scan parentBytes for every signature and synthesise VRI entries
+    parentBytes?: Uint8Array,  // required when autoVri is true
+    vriTime?:  Date            // overrides `new Date()` for autoVri's /TU (tests: deterministic value)
+}
+```
+
+### `BuildDssResult`
+
+```js
+{
+    updates: Array<{ num, gen, value }>,  // ready for pdfIncrementalWriter.appendIncremental
+    dssNum: number,
+    lastNum: number,
+    certNums: number[], ocspNums: number[], crlNums: number[]
+}
+```
+
+## Examples
+
+### Explicit VRI keyed by signature-value SHA-1
+
+```js
+const dss = runtime.resolve('pdfDssBuilder');
+const built = dss.buildDss({
+    startNum: 10,
+    certs: [leafDer, caDer],
+    vri: { 'A1B2C3...': { certs: [0, 1], tu: '(D:20260803120000+00\'00\')' } }
+});
+```
+
+### Auto-populated VRI over every signature in the parent bytes
+
+```js
+const built = dss.buildDss({
+    startNum: 10,
+    certs: [leafDer, caDer], ocsps: [ocspDer],
+    autoVri: true, parentBytes: signedBytes
+});
+built.dssNum;      // object number to reference from the updated Catalog
+built.updates;      // feed straight into pdfIncrementalWriter.appendIncremental
+```
+
+## Errors
+
+All thrown as `ContractError`.
+
+| Code | When |
+|------|------|
+| `pdf/dss/bad-startNum` | `startNum` missing or `< 2`. |
+| `pdf/dss/bad-cert` / `bad-ocsp` / `bad-crl` | An entry in `certs`/`ocsps`/`crls` is not a `Uint8Array`. |
+| `pdf/dss/vri-bad-index` | A `vri.<hex>.certs/ocsps/crls` numeric index is out of bounds of the corresponding parent list. |
+
+## See also
+
+- [`pdfSign`](./sign.md) — the only caller, for PAdES levels LT/LTA.
+- [`pdfIncrementalWriter`](../document/incrementalWriter.md) — consumes `buildDss`'s `updates`.
+- [`pdfSha1`](./sha1.md) — VRI key hash.

package/docs/api/sig/oids.md

@@ -0,0 +1,76 @@
+---
+module: pdfSigOids
+category: pdf/sig
+dependencies: [asn1Oid]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSigOids
+
+> Shared OID dispatch tables for the `pdf/sig/*` family.
+
+**Module** `pdfSigOids` | **Source** `packages/front/office/pdf/src/sig/oids.js` | **Deps** `asn1Oid` | **Worker-safe** yes
+
+A thin adapter over fw's `asn1Oid` (`@awacloud/fw/crypto/utils/asn1-oid.js`) — the
+canonical OID database (~150 entries: PKCS, X.509, CMS, JOSE, PAdES, ECC,
+AES). This module does **not** duplicate that data; it filters and
+normalises a subset into the dispatch semantics `signature.js`, `sign.js`,
+`timestamp.js` and `certChain.js` need — mapping OIDs to fw module names or
+PDF-domain dispatch labels. Adding or renaming an OID happens in fw's
+`asn1Oid` database; this module only decides how to surface an entry to PDF
+callers. Every table is rebuilt by filtering fw's database, so an OID fw
+doesn't recognise is silently dropped rather than fabricated.
+
+## Resolve
+
+```js
+const oids = runtime.resolve('pdfSigOids');
+// Returns: { DIGEST_OIDS, SIG_DISPATCH_OIDS, KEY_ALG_OIDS, SIG_ALG_OIDS_VERBOSE,
+//            OID_TST_INFO, OID_AA_TIMESTAMP,
+//            lookupDigest, lookupSigAlg, lookupKeyAlg, lookupSigVerbose, shortOid }
+```
+
+## API
+
+| Member | Shape | Description |
+|--------|-------|--------------|
+| `DIGEST_OIDS` | `Object.freeze({ [oid]: 'sha256'\|'sha384'\|'sha512'\|'sha1' })` | Digest OID → fw hash module name. |
+| `SIG_DISPATCH_OIDS` | `Object.freeze({ [oid]: 'rsa'\|'rsa-pss'\|'ecc'\|'ed25519' })` | Signature-algorithm OID → fw verifier dispatch name (all PKCS#1 v1.5 RSA OIDs map to `'rsa'`). |
+| `KEY_ALG_OIDS` | `Object.freeze({ [oid]: 'rsa'\|'ecc'\|'ed25519'\|'ed448' })` | SPKI base-algorithm OID (no hash suffix) → short algorithm name. |
+| `SIG_ALG_OIDS_VERBOSE` | `Object.freeze({ [oid]: string })` | Certificate `sigAlgorithm` verbose name (e.g. `'sha256WithRSAEncryption'`, `'ecdsa-with-SHA256'`, `'rsassa-pss'`). |
+| `OID_TST_INFO` | `string` | `id-ct-TSTInfo` (`1.2.840.113549.1.9.16.1.4`), RFC 3161. |
+| `OID_AA_TIMESTAMP` | `string` | `id-aa-timeStampToken` (`1.2.840.113549.1.9.16.2.14`), RFC 3161. |
+| `lookupDigest(oid)` | `(oid: string) => string \| null` | `DIGEST_OIDS[oid]` or `null`. |
+| `lookupSigAlg(oid)` | `(oid: string) => string \| null` | `SIG_DISPATCH_OIDS[oid]` or `null`. |
+| `lookupKeyAlg(oid)` | `(oid: string) => string \| null` | `KEY_ALG_OIDS[oid]` or `null`. |
+| `lookupSigVerbose(oid)` | `(oid: string) => string \| null` | `SIG_ALG_OIDS_VERBOSE[oid]` or `null`. |
+| `shortOid(oid)` | `(oid: string) => string` | DN attribute OID → short form (`'CN'`, `'O'`, `'OU'`, `'C'`, `'E'`…); falls back to the OID string itself when unrecognised. |
+
+## Examples
+
+### Resolving a certificate's signature algorithm
+
+```js
+const oids = runtime.resolve('pdfSigOids');
+const dispatch = oids.lookupSigAlg('1.2.840.113549.1.1.11'); // 'rsa'
+const verbose  = oids.lookupSigVerbose('1.2.840.113549.1.1.11'); // 'sha256WithRSAEncryption'
+```
+
+### Rendering a Distinguished Name
+
+```js
+const oids = runtime.resolve('pdfSigOids');
+const parts = rdnAttributes.map(({ oid, value }) => `${oids.shortOid(oid)}=${value}`);
+const dn = parts.join(', '); // e.g. 'CN=Example, O=Acme, C=FR'
+```
+
+## Errors
+
+None — every lookup returns `null` (or falls back to the OID string, for
+`shortOid`) rather than throwing on an unrecognised OID.
+
+## See also
+
+- [`pdfSignature`](./signature.md) · [`pdfSign`](./sign.md) · [`pdfTimestamp`](./timestamp.md) · [`pdfCertChain`](./certChain.md) — all consumers.

package/docs/api/sig/sha1.md

@@ -0,0 +1,72 @@
+---
+module: pdfSha1
+category: pdf/sig
+dependencies: [bitArray, utf8]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSha1
+
+> SHA-1 (FIPS 180-4 §6.1) — PDF-local legacy hash, DSS `/VRI` keys only.
+
+**Module** `pdfSha1` | **Source** `packages/front/office/pdf/src/sig/sha1.js` | **Deps** `bitArray`, `utf8` | **Worker-safe** yes
+
+SHA-1 is cryptographically broken for collision resistance and **must not**
+be used for new signatures, MACs, or password hashing. This module exists
+solely because ISO 32000-2 §12.8.4.3 mandates SHA-1 of the signature value
+as the DSS `/VRI` dict key — kept in `@awacloud/pdf` rather than `@awacloud/fw` so the
+legacy-only nature stays obvious to anyone reading fw's hash family
+(`sha256`/`sha384`/`sha512` only, no `sha1`). Exposes the same shape as fw's
+hash modules (`hash(data)` one-shot, `fn()` constructor) so dispatch code
+can treat it uniformly.
+
+## Resolve
+
+```js
+const sha1 = runtime.resolve('pdfSha1');
+// Returns: { fn, hash }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `hash` | `(data: Uint8Array \| bitArray \| string) => bitArray` | One-shot digest (20 bytes as a fw `bitArray`). |
+| `fn` | `(other?: HashState) => HashState` | Streaming constructor — `{ reset, update, finalize, blockSize: 512 }`. Passing an existing instance clones its internal state. |
+
+`update(data)` accepts a `string` (UTF-8 encoded via `utf8.toBytes` then
+converted to a `bitArray`) or an already-encoded `bitArray`.
+
+## Examples
+
+### One-shot digest
+
+```js
+const sha1 = runtime.resolve('pdfSha1');
+const bitArrayMod = runtime.resolve('bitArray');
+const digest = sha1.hash(bitArrayMod.ui8_to_ba(signatureValueBytes));
+const bytes = bitArrayMod.ba_to_ui8(digest); // 20 bytes
+```
+
+### Streaming
+
+```js
+const sha1 = runtime.resolve('pdfSha1');
+const ctx = sha1.fn();
+ctx.update(chunk1).update(chunk2);
+const digest = ctx.finalize();
+```
+
+## Errors
+
+None thrown. `update()` guards against hashing more than 2^53 − 1 bits by
+`console.warn`-ing and returning `false` instead of throwing — a limit that
+is unreachable for the DSS VRI-key use case (hashing a single signature
+value, at most a few KB).
+
+## See also
+
+- [`pdfDssBuilder`](./dss.md) — the only consumer, for `/VRI` key derivation.
+- [`pdfSignature`](./signature.md) — uses fw's `sha256`/`sha384`/`sha512` for the actual signature digest.