@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/content/ops.md

@@ -0,0 +1,100 @@
+---
+module: pdfContentOps
+category: pdf/content
+dependencies: []
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfContentOps
+
+> Exhaustive catalogue of content-stream operators — ISO 32000-2 §8.2 Table 60 + §9.4.
+
+**Module** `pdfContentOps` | **Source** `packages/front/office/pdf/src/content/ops.js` | **Deps** none | **Worker-safe** yes
+
+Single source of truth for the PDF operator mnemonics, their **category**
+(`gstate`, `path`, `paint`, `clip`, `color`, `shading`, `image`, `xobject`,
+`marked`, `text`) and their expected **arity**. Consumed by `pdfContentStream`
+for categorisation, and by any linter wanting to validate a stream's coherence.
+71 operators are registered.
+
+## Resolve
+
+```js
+const opsMod = runtime.resolve('pdfContentOps');
+// Returns: { OPS, OP_NAMES, lookupOp, isOp }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `OPS` | `Object<string, OpRecord>` (frozen) | Full table, keyed by mnemonic. |
+| `OP_NAMES` | `string[]` (frozen) | Alphabetically sorted list (71 entries). |
+| `lookupOp` | `(mnemonic: string) => OpRecord \| undefined` | Direct lookup. |
+| `isOp` | `(mnemonic: string) => boolean` | Membership test. |
+
+### `OpRecord` shape
+
+```js
+{ op: string, category: string, arity: number | 'var', desc: string }
+```
+
+`arity` is `'var'` for exactly four operators — `SC`, `sc`, `SCN`, `scn` —
+whose operand count depends on the current colour space. `TJ` has arity `1`
+(the single positioning array).
+
+### Categories covered
+
+| Category | §ISO | Count | Operators |
+|----------|------|-------|-----------|
+| `gstate` | §8.4 | 13 | `q`, `Q`, `cm`, `w`, `J`, `j`, `M`, `d`, `ri`, `i`, `gs`, `d0`, `d1` |
+| `path` | §8.5.2 | 7 | `m`, `l`, `c`, `v`, `y`, `h`, `re` |
+| `paint` | §8.5.3 | 10 | `S`, `s`, `f`, `F`, `f*`, `B`, `B*`, `b`, `b*`, `n` |
+| `clip` | §8.5.4 | 2 | `W`, `W*` |
+| `color` | §8.6 | 12 | `CS`, `cs`, `SC`, `sc`, `SCN`, `scn`, `G`, `g`, `RG`, `rg`, `K`, `k` |
+| `shading` | §8.7 | 1 | `sh` |
+| `image` | §8.9.7 | 3 | `BI`, `ID`, `EI` |
+| `xobject` | §8.10 | 1 | `Do` |
+| `marked` | §14.6 | 5 | `MP`, `DP`, `BMC`, `BDC`, `EMC` |
+| `text` | §9.3 / §9.4 | 17 | `BT`, `ET`, `Tc`, `Tw`, `Tz`, `TL`, `Tf`, `Tr`, `Ts`, `Td`, `TD`, `Tm`, `T*`, `Tj`, `'`, `"`, `TJ` |
+
+## Examples
+
+### Lookup
+
+```js
+const { lookupOp, isOp } = runtime.resolve('pdfContentOps');
+lookupOp('Tj');  // { op: 'Tj', category: 'text', arity: 1, desc: 'show text' }
+isOp('xyz');     // false
+isOp('cm');      // true
+```
+
+### Iterating by category
+
+```js
+const { OPS } = runtime.resolve('pdfContentOps');
+const textOps = Object.values(OPS).filter(o => o.category === 'text');
+textOps.length;  // 17
+```
+
+### Validating an operator's arity
+
+```js
+const rec = lookupOp(op.op);
+if (rec.arity !== 'var' && op.args.length !== rec.arity) {
+    throw new Error(`${op.op}: expected ${rec.arity} args, got ${op.args.length}`);
+}
+```
+
+## Errors
+
+A table module with no I/O — it emits no `PdfError`. Consumers
+(`pdfContentStream`, linters) surface their own errors.
+
+## See also
+
+- [`pdfContentStream`](./stream.md) — consumes `isOp` to recognise operators.
+- [`pdfGraphics`](./graphics.md), [`pdfText`](./text.md), [`pdfColor`](./color.md) — dispatch by category.
+- [`pdfImages`](./images.md) — types the XObjects invoked by `Do`.

package/docs/api/content/stream.md

@@ -0,0 +1,107 @@
+---
+module: pdfContentStream
+category: pdf/content
+dependencies: [pdfErrors, pdfParser, pdfContentOps]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfContentStream
+
+> Content-stream parser — decoded `Uint8Array` → ordered list of typed operations. ISO 32000-2 §7.8 + §8.2 + Table 60.
+
+**Module** `pdfContentStream` | **Source** `packages/front/office/pdf/src/content/stream.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfContentOps` | **Worker-safe** yes
+
+Reads the bytes of an **already decoded** content stream (the `/Filter` chain
+must have been applied by `pdfFilterDispatch` upstream) and produces
+`[{ op, args, data? }]`. Operands stay **typed** (`{ type, value, … }`) — a `Tj`
+carries its typed `string`, ready for ToUnicode resolution; a `gs` carries its
+`name`, usable directly against `/Resources /ExtGState`. Inline images
+`BI … ID … EI` (§8.9.7) are captured as a single synthetic op with
+`data: Uint8Array`.
+
+## Resolve
+
+```js
+const csMod = runtime.resolve('pdfContentStream');
+// Returns: { parseContentStream }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `parseContentStream` | `(bytes: Uint8Array) => Op[]` | Ordered list of operations. |
+
+### `Op` shape
+
+```js
+{
+    op: string,         // mnemonic (e.g. 'Tj', 'cm', 'BI', '__trailing__')
+    args: PdfObject[],  // typed operands, in stack order
+    data?: Uint8Array   // present only for 'BI' (raw image data)
+}
+```
+
+A synthetic `{ op: '__trailing__', args }` is appended when the stream ends on
+unconsumed operands — this preserves rewrite fidelity.
+
+### Inline images
+
+```js
+{
+    op: 'BI',
+    args: [{ type: 'dict', entries: { Width, Height, ColorSpace, Filter, … } }],
+    data: Uint8Array  // raw bytes between `ID\n` and the space before `EI`
+}
+```
+
+## Examples
+
+### Parse a minimal stream
+
+```js
+const cs = runtime.resolve('pdfContentStream');
+const bytes = new TextEncoder().encode('BT /F1 12 Tf (Hello) Tj ET');
+const ops = cs.parseContentStream(bytes);
+// → [{op:'BT',args:[]}, {op:'Tf',args:[name,int]}, {op:'Tj',args:[string]}, {op:'ET',args:[]}]
+```
+
+### Extract the font names in use
+
+```js
+const fonts = new Set();
+for (const op of ops) {
+    if (op.op === 'Tf') fonts.add(op.args[0].value);  // args[0] = name
+}
+```
+
+### Inline image
+
+```js
+const ops = cs.parseContentStream(streamBytes);
+const img = ops.find(o => o.op === 'BI');
+img.args[0].entries.W;   // typed int
+img.data;                // Uint8Array — feed to pdfFilterDispatch when /F is set
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/content/bad-input` | `ParseError` | Argument is not a `Uint8Array`. |
+| `pdf/content/unknown-op` | `ParseError` | Unknown mnemonic (absent from `pdfContentOps`). |
+| `pdf/content/inline-image/no-ID` | `ParseError` | `BI` without a matching `ID`. |
+| `pdf/content/inline-image/bad-key` | `ParseError` | Non-`name` key in the inline dictionary. |
+| `pdf/content/inline-image/no-EI` | `ParseError` | `ID` without a matching `EI`. |
+
+It also propagates the `pdf/parser/*` codes while parsing operands.
+
+## See also
+
+- [`pdfContentOps`](./ops.md) — operator table.
+- [`pdfGraphics`](./graphics.md) — applies the `gstate` ops.
+- [`pdfText`](./text.md) — decodes the `text` ops.
+- [`pdfColor`](./color.md) — applies the `color` ops.
+- [`pdfImages`](./images.md) — types the XObjects (`Do`).

package/docs/api/content/text.md

@@ -0,0 +1,98 @@
+---
+module: pdfText
+category: pdf/content
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfText
+
+> Text state + Tm/Tlm matrices + Unicode extraction — ISO 32000-2 §9.3 / §9.4.
+
+**Module** `pdfText` | **Source** `packages/front/office/pdf/src/content/text.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Applies the operators that mutate `gstate.text` (`Tf`, `BT`, `Td`, `TD`, `Tm`,
+`T*`) and exposes `extractText`, which decodes a `Tj`/`TJ`/`'`/`"` operand into
+Unicode through a caller-supplied `cidToUnicode` function (typically built from
+`@awacloud/fonts`' `cmapToUnicode` module, `@awacloud/fonts/cmap-to-unicode`). ToUnicode
+resolution is deliberately **not** done here, so the module stays worker-safe
+with no font dependency.
+
+## Resolve
+
+```js
+const t = runtime.resolve('pdfText');
+// Returns: { setFont, beginTextObject, td, tdSetLeading,
+//            setTextMatrix, nextLine, rawStringBytes, extractText }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `setFont` | `(gstate, fontResource: string, size: number) => void` | Applies `Tf`. |
+| `beginTextObject` | `() => { Tm, Tlm }` | Initialises `BT` — both matrices identity. |
+| `td` | `(state, tx, ty) => void` | Operator `Td`. |
+| `tdSetLeading` | `(gstate, state, tx, ty) => void` | Operator `TD` — also sets `gstate.text.leading = -ty`. |
+| `setTextMatrix` | `(state, m: number[6]) => void` | Operator `Tm`. |
+| `nextLine` | `(gstate, state) => void` | Operator `T*`. |
+| `rawStringBytes` | `(stringObj) => Uint8Array` | Raw bytes of a typed `string` operand. |
+| `extractText` | `(op, font, cidToUnicode) => string` | Decodes `Tj`/`TJ`/`'`/`"`. |
+
+`state` is the `{ Tm, Tlm }` record returned by `beginTextObject`; `gstate` is a
+graphics state from [`pdfGraphics`](./graphics.md), whose `text` sub-object is
+mutated in place.
+
+### `extractText`
+
+- Single-byte fonts (`font.subtype !== 'Type0'`): each byte is a CID.
+- CID fonts (`font.subtype === 'Type0'`): big-endian byte pairs.
+- Numbers inside a `TJ` array (positioning adjustments) contribute no text.
+- The `"` operator reads its string from `args[2]`; `Tj` and `'` from `args[0]`.
+- A glyph with no ToUnicode mapping yields the replacement character `'�'`.
+
+## Examples
+
+### Minimal extraction pipeline
+
+```js
+const t = runtime.resolve('pdfText');
+const state = t.beginTextObject();
+let acc = '';
+for (const op of ops) {
+    if (op.op === 'Tf')      t.setFont(gstate, op.args[0].value, op.args[1].value);
+    else if (op.op === 'Td') t.td(state, op.args[0].value, op.args[1].value);
+    else if (op.op === 'Tj' || op.op === 'TJ') {
+        acc += t.extractText(op, currentFont, cidToUnicode);
+    }
+}
+```
+
+### Set the text matrix
+
+```js
+t.setTextMatrix(state, [1, 0, 0, 1, 72, 720]);  // (72, 720) in user space
+```
+
+### Raw bytes for an external ToUnicode
+
+```js
+const raw = t.rawStringBytes(op.args[0]);  // Uint8Array
+const text = customCmap.decode(raw);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/text/bad-matrix` | `ContractError` | `Tm` matrix is not 6 elements. |
+| `pdf/text/bad-string` | `ContractError` | `rawStringBytes` given something other than a `{type:'string'}`. |
+
+## See also
+
+- [`pdfContentStream`](./stream.md) — produces the `Tj`/`TJ` ops.
+- [`pdfGraphics`](./graphics.md) — hosts `gstate.text`.
+- [`pdfFont`](../font/font.md) — supplies `subtype` to `extractText`.
+- [`pdfFontEncoding`](../font/encoding.md) — `/Encoding` resolution.

package/docs/api/crypto/README.md

@@ -0,0 +1,29 @@
+# Crypto — ISO 32000-2 §7.6 + ISO TS 32003
+
+Encryption handlers and permissions. All modules are `fwModules`; the handlers' fw-crypto deps resolve from `@awacloud/fw/crypto`.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfSecurity`](./security.md) | `{ typeEncryptDict, selectHandler, isEmbeddedFileStream, dispatchDecryptStream }` | `pdfErrors` | Dispatch, §7.6.2. |
+| [`pdfStandardV4`](./standardV4.md) | `{ tryPassword, decryptString, decryptStream, decryptEmbeddedFile, encryptEmbeddedFile, encryptString, encryptStream, buildOU, buildPerms, computeFileKey, computeU, computeO, objectKey, rc4, md5, padPassword, PASSWORD_PADDING }` | `pdfErrors`, `aes`, `cbc`, `bitArray` | PDF 1.6 legacy — RC4-128 / AES-128-CBC. |
+| [`pdfStandardV5`](./standardV5.md) | `{ tryPassword, decryptString, decryptStream, encryptString, encryptStream, buildUUE, buildOOE, buildPerms }` | `pdfErrors`, fw crypto, `pdfAesGcm`? | Historical R=5 AES-256. |
+| [`pdfStandardV6`](./standardV6.md) | `{ tryPassword, decryptString, decryptStream, encryptString, encryptStream, buildUUE, buildOOE, buildPerms }` | `pdfErrors`, fw crypto, `pdfAesGcm`? | R=6 hardening, §7.6.4. |
+| [`pdfPermissions`](./permissions.md) | `{ decodePermissions, verifyPermsField }` | `pdfErrors`, fw `aes` | `/P` + `/Perms` MAC. |
+| [`pdfAesGcm`](./aesGcm.md) | `{ encryptObjectGcm, decryptObjectGcm }` | `pdfErrors`, fw `aes`, `gcm`, `bitArray` | AES-GCM (ISO TS 32003). |
+
+## Decryption pattern
+
+```js
+const sec  = runtime.resolve('pdfSecurity');
+const enc  = sec.typeEncryptDict(trailer.encrypt);
+const selection = sec.selectHandler(enc, {
+    v5: runtime.resolve('pdfStandardV5'),
+    v6: runtime.resolve('pdfStandardV6')
+});
+const { fileEncryptionKey } = selection.handler.tryPassword(enc, password, false);
+```
+
+## See also
+
+- [`pdfTrailer`](../syntax/trailer.md) — carrier of the `/Encrypt` dict.
+- [Signature](../sig/README.md) — orthogonal to the encryption handlers.

package/docs/api/crypto/aesGcm.md

@@ -0,0 +1,72 @@
+---
+module: pdfAesGcm
+category: pdf/crypto
+dependencies: [pdfErrors, aes, gcm, bitArray]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAesGcm
+
+> AES-GCM cipher for PDF objects — ISO TS 32003.
+
+**Module** `pdfAesGcm` | **Source** `packages/front/office/pdf/src/crypto/aesGcm.js` | **Deps** `pdfErrors`, `aes`, `gcm`, `bitArray` | **Worker-safe** yes
+
+Implements the `AESV4` cipher introduced by ISO TS 32003: AES-256 in GCM mode with a 12-byte IV and a 16-byte authentication tag. Both functions operate on the PDF wire format directly — a single `Uint8Array` framed as `IV (12) ‖ ciphertext (n) ‖ tag (16)` — rather than a `{ iv, ciphertext, tag }` object. Decryption rejects truncated ciphertext or a mismatched tag.
+
+## Resolve
+
+```js
+const gcm = runtime.resolve('pdfAesGcm');
+// Returns: { encryptObjectGcm, decryptObjectGcm }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `encryptObjectGcm` | `(fek: Uint8Array, plaintext: Uint8Array, ivProvider: () => Uint8Array) => Uint8Array` | Framed `iv ‖ ciphertext ‖ tag`. `ivProvider` is called with no arguments and must return exactly 12 bytes. |
+| `decryptObjectGcm` | `(fek: Uint8Array, framed: Uint8Array) => Uint8Array` | Splits `framed` into `iv`/`ciphertext`/`tag`, verifies the tag, and returns the plaintext. Throws on tag mismatch. |
+
+`fek` (File Encryption Key) must be exactly 32 bytes (AES-256).
+
+## Examples
+
+### Deterministic encrypt (tests)
+
+```js
+const gcm = runtime.resolve('pdfAesGcm');
+const framed = gcm.encryptObjectGcm(
+    fek,
+    new TextEncoder().encode('hello'),
+    () => new Uint8Array(12)   // ZERO IV — test only
+);
+```
+
+### Decrypt the wire format
+
+```js
+const gcm = runtime.resolve('pdfAesGcm');
+const plain = gcm.decryptObjectGcm(fek, framed);
+// framed === iv(12) ‖ ciphertext ‖ tag(16), exactly as read from the PDF object.
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/crypto/gcm/missing-fw` | `EncryptionError` | fw bundle incomplete (thrown at module construction). |
+| `pdf/crypto/gcm/bad-fek` | `EncryptionError` | FEK ≠ 32 bytes. |
+| `pdf/crypto/gcm/aes-schedule-failed` | `EncryptionError` | AES-256 key schedule failed. |
+| `pdf/crypto/gcm/bad-input` | `EncryptionError` | `framed` is not a Uint8Array of at least 28 bytes. |
+| `pdf/crypto/gcm/tag-mismatch` | `EncryptionError` | Authentication tag invalid — data tampered or wrong key. |
+| `pdf/crypto/gcm/bad-plaintext` | `EncryptionError` | Plaintext is not a Uint8Array. |
+| `pdf/crypto/gcm/bad-iv-provider` | `EncryptionError` | `ivProvider` is not a function. |
+| `pdf/crypto/gcm/bad-iv` | `EncryptionError` | `ivProvider()` did not return exactly 12 bytes. |
+| `pdf/crypto/gcm/encrypt-failed` | `EncryptionError` | The GCM provider failed. |
+
+## See also
+
+- [`pdfStandardV6`](./standardV6.md) — handler carrying the CFM.
+- [`pdfSecurity`](./security.md)

package/docs/api/crypto/permissions.md

@@ -0,0 +1,79 @@
+---
+module: pdfPermissions
+category: pdf/crypto
+dependencies: [pdfErrors, aes]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfPermissions
+
+> `/P` decoding + `/Perms` verification — ISO 32000-2 §7.6.3.2 Table 22.
+
+**Module** `pdfPermissions` | **Source** `packages/front/office/pdf/src/crypto/permissions.js` | **Deps** `pdfErrors`, `aes` | **Worker-safe** yes
+
+The `/P` field is a signed 32-bit integer whose bits encode permissions (bit 3 = print, 4 = modify, 5 = copy/extract, 6 = annotate, 9 = fill forms, 10 = accessibility extraction, 11 = assemble, 12 = high-quality print). `verifyPermsField` decrypts the 16-byte `/Perms` string (AES-256-ECB with the FEK) and checks that it encodes the same `/P` — a de facto MAC protecting against post-encryption tampering.
+
+## Resolve
+
+```js
+const perms = runtime.resolve('pdfPermissions');
+// Returns: { decodePermissions, verifyPermsField }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `decodePermissions` | `(p: number) => PermFlags` | Decomposes `/P` into readable booleans. |
+| `verifyPermsField` | `(typedEncrypt: { Perms }, fek: Uint8Array) => { ok, p, encryptMetadata }` | Verifies the `/Perms` MAC. |
+
+### Shape `PermFlags`
+
+```js
+{
+    raw: number,
+    print: boolean,             // bit 3
+    modify: boolean,            // bit 4
+    copy: boolean,               // bit 5
+    annot: boolean,              // bit 6
+    formFill: boolean,           // bit 9
+    accessible: boolean,         // bit 10 — accessibility extraction
+    assemble: boolean,           // bit 11
+    printHighQuality: boolean    // bit 12
+}
+```
+
+## Examples
+
+### Decoding the flags
+
+```js
+const p = runtime.resolve('pdfPermissions').decodePermissions(enc.P);
+if (!p.copy) viewer.disableTextSelection();
+```
+
+### MAC verification
+
+```js
+const v = perms.verifyPermsField(enc, fek);
+if (!v.ok) throw new Error('permissions tampered');
+v.encryptMetadata === enc.EncryptMetadata;
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/crypto/permissions/bad-input` | `EncryptionError` | `p` argument is not an integer. |
+| `pdf/crypto/permissions/missing-fw` | `EncryptionError` | fw bundle incomplete (thrown at module construction). |
+| `pdf/crypto/permissions/missing-perms` | `EncryptionError` | `/Perms` absent. |
+| `pdf/crypto/permissions/bad-perms-length` | `EncryptionError` | `/Perms` ≠ 16 bytes. |
+| `pdf/crypto/permissions/bad-fek` | `EncryptionError` | FEK ≠ 32 bytes. |
+| `pdf/crypto/permissions/aes-schedule-failed` | `EncryptionError` | Key schedule failed. |
+| `pdf/crypto/permissions/aes-decrypt-failed` | `EncryptionError` | Block decryption failed. |
+
+## See also
+
+- [`pdfSecurity`](./security.md) · [`pdfStandardV5`](./standardV5.md) · [`pdfStandardV6`](./standardV6.md)

package/docs/api/crypto/security.md

@@ -0,0 +1,98 @@
+---
+module: pdfSecurity
+category: pdf/crypto
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSecurity
+
+> `/Encrypt` dict typing and handler selection — ISO 32000-2 §7.6.
+
+**Module** `pdfSecurity` | **Source** `packages/front/office/pdf/src/crypto/security.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Neutral layer that interprets the trailer's `/Encrypt` dict (§7.6.2 Table 21) and selects the appropriate handler (`v4` = RC4/AES-128 legacy, `v5` = historical AES-256 ISO 32000-1 R5, `v6` = AES-256 ISO 32000-2 R6, transparently including ISO/TS 32003 AES-GCM when `/CFM = AESV4`). Performs no key derivation itself — delegates to the specialized handlers, and additionally routes stream decryption between the regular stream path and the embedded-file path (`/EFF`, ISO 32000-1 §7.6.5).
+
+## Resolve
+
+```js
+const sec = runtime.resolve('pdfSecurity');
+// Returns: { typeEncryptDict, selectHandler, isEmbeddedFileStream, dispatchDecryptStream }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeEncryptDict` | `(dict \| Map) => Encrypt` | Strict typing of the `/Encrypt` entries. |
+| `selectHandler` | `(typedEncrypt: Encrypt, handlers: { v4?, v5?, v6? }) => { handler, revision, method, strMethod, effMethod }` | Dispatches `V=4` → `handlers.v4`, `V=5,R=5` → `handlers.v5`, `V=5,R=6` → `handlers.v6`; also resolves the `/CF`/`/StmF`/`/StrF`/`/EFF` crypt-filter method (`'AESV2'`/`'V2'`/`'Identity'` for V=4, `'AESV3'`/`'AESV4'`/`'Identity'` for V=5) into `method` (streams), `strMethod` (strings) and `effMethod` (embedded files). |
+| `isEmbeddedFileStream` | `(stream) => boolean` | `true` when the stream dict has `/Type /EmbeddedFile`. |
+| `dispatchDecryptStream` | `(selection, stream, fek, objNum, gen, ciphertext) => Uint8Array` | Routes to `selection.handler.decryptEmbeddedFile` (with `effMethod`) when `stream` is an embedded file, else to `handler.decryptStream` (with `method`). Returns `ciphertext` unchanged, without calling the handler, when that method is `'Identity'`. |
+
+### Identity crypt filter
+
+A class whose crypt filter is `Identity` — named explicitly, or absent, which is the ISO 32000-2 §7.6.6 Table 20 default for `/StmF` and `/StrF` — is not encrypted. `selectHandler` resolves each class on its own: `/StmF` gives `method`, `/StrF` gives `strMethod`, and `/EFF` gives `effMethod`, where an absent `/EFF` follows `/StmF`. A V=5 file with `/StmF /StdCF` and `/StrF /Identity` therefore has encrypted streams and clear strings. `dispatchDecryptStream` returns the bytes of an `Identity` class unchanged on every revision (V=4, V=5 R=5, V=5 R=6), and signing such a file writes its new strings in the clear. On V=4, a `/StmF /Identity` paired with a named `/StrF` keeps its existing behaviour: streams use the `/StrF` filter.
+
+### Shape `Encrypt`
+
+```js
+{
+    V, R, Filter, SubFilter, Length, CF, StmF, StrF, EFF,
+    O, U, OE, UE, Perms,    // Uint8Array
+    EncryptMetadata: boolean,
+    P: number,              // permissions bitmask, §7.6.3.2 Table 22
+    raw
+}
+```
+
+## Examples
+
+### Dispatcher
+
+```js
+const sec = runtime.resolve('pdfSecurity');
+const enc = sec.typeEncryptDict(trailer.encrypt);
+const selection = sec.selectHandler(enc, {
+    v5: runtime.resolve('pdfStandardV5'),
+    v6: runtime.resolve('pdfStandardV6')
+});
+const fek = selection.handler.tryPassword(enc, password, false).fileEncryptionKey;
+```
+
+### Stream decryption routing (regular vs embedded file)
+
+```js
+const plain = sec.dispatchDecryptStream(selection, streamObj, fek, num, gen, ciphertext);
+```
+
+### Inspecting permissions
+
+```js
+const perms = runtime.resolve('pdfPermissions').decodePermissions(enc.P);
+perms.print;
+perms.copy;
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/crypto/encrypt-dict/bad-input` | `EncryptionError` | Argument is not an object. |
+| `pdf/crypto/encrypt-dict/missing-V-R` | `EncryptionError` | `/V` or `/R` missing. |
+| `pdf/crypto/encrypt-dict/bad-V-R-type` | `EncryptionError` | `/V` or `/R` not an integer. |
+| `pdf/crypto/v4/missing-cf-entry` | `EncryptionError` | `V=4` requires a `/CF /<name>` entry that is absent. |
+| `pdf/crypto/v4/bad-cfm` | `EncryptionError` | `V=4` CFM is neither `AESV2` nor `V2`. |
+| `pdf/crypto/v5/bad-cfm` | `EncryptionError` | `V=5` CFM is neither `AESV3` nor `AESV4`. |
+| `pdf/crypto/security/bad-typed` | `EncryptionError` | `selectHandler` receives a non-typed encrypt dict. |
+| `pdf/crypto/unsupported-version` | `EncryptionError` | `V`/`R` combination outside `4`/`5`+`5`/`5`+`6`. |
+| `pdf/crypto/missing-handler` | `EncryptionError` | Required `v4`/`v5`/`v6` handler not supplied. |
+| `pdf/crypto/security/bad-selection` | `EncryptionError` | `dispatchDecryptStream` receives a selection without a `handler`. |
+| `pdf/crypto/security/no-eff` | `EncryptionError` | Embedded-file stream but the handler exposes neither `decryptEmbeddedFile` nor `decryptStream`. |
+| `pdf/crypto/security/no-stream` | `EncryptionError` | Regular stream but the handler lacks `decryptStream`. |
+
+## See also
+
+- [`pdfStandardV5`](./standardV5.md) · [`pdfStandardV6`](./standardV6.md) · [`pdfAesGcm`](./aesGcm.md)
+- [`pdfPermissions`](./permissions.md)