ppt-codec 1.2.12 → 1.3.0

package/README.md

@@ -57,7 +57,30 @@ for (const slide of slides) {
 }
 ```
 
-`readPptStreams(currentUserStream, powerPointDocumentStream)` is the same read one level down, for a caller that already holds the two streams — the compound file beneath them is `archive-codec`'s business, and separating the two is what lets every record-level behaviour be tested without a container around it.
+`readPptStreams(currentUserStream, powerPointDocumentStream, password)` is the same read one level down, for a caller that already holds the two streams — the compound file beneath them is `archive-codec`'s business, and separating the two is what lets every record-level behaviour be tested without a container around it.
+
+## Encryption
+
+A `.ppt` protected with a password to open uses [MS-OFFCRYPTO] 2.3.5 "RC4 CryptoAPI Encryption" — genuinely different from the MD5-based scheme `xls-codec` and `doc-codec` share (ExaDev/documents.js#1108/#1113): SHA-1-based key derivation with no intermediate-hash iteration, and re-keying per persist object rather than at a fixed byte interval. `readPpt`/`readPptContent`/`readPptStreams` take an optional `password`, ignored for an unencrypted presentation; a missing or incorrect password against an encrypted one throws `PptEncryptedError` rather than returning a partial or garbled document, and so does an encryption shape this package does not implement (anything other than RC4 CryptoAPI — [MS-PPT] itself never specifies any other scheme for the binary format).
+
+```ts
+import { readPptContent } from "ppt-codec";
+
+const { metadata, slides } = readPptContent(
+  pptBytes,
+  "correct horse battery staple",
+);
+```
+
+`archive-codec`'s `crypto/office-rc4-cryptoapi` module (ExaDev/documents.js#1116) carries the key derivation and password verification; this package's own `src/encryption.ts` carries the container-specific pieces, which differ from both xls-codec's and doc-codec's shared scheme in three real ways:
+
+- **Location.** There is no fixed-offset header at all. The `DocumentEncryptionAtom` (`RT_CryptSession10Container`, [MS-PPT]'s own name for record type 0x2F14) is just another persist object, reached only by walking the current `UserEditAtom.encryptSessionPersistIdRef` through the same persist directory every other record uses.
+- **Re-keying granularity.** Each top-level persist object gets its own RC4 key, derived from its own persist ID as the "block number" — not a running byte offset within one continuous stream, the way both `xls-codec`'s FilePass scheme and `doc-codec`'s own EncryptionHeader scheme re-key.
+- **Encrypted headers.** A persist object's own 8-byte record header is encrypted along with its data, unlike the never-encrypted headers the shared xls/doc scheme leaves alone — `decryptPptDocumentStream` decrypts a peek of those 8 bytes first, under the object's own key, to learn its real length before decrypting the object in full.
+
+Pictures in a separate `Pictures` stream are also RC4 CryptoAPI-encrypted per [MS-PPT], but this package does not read the `Pictures` stream at all today (see [Images, tables, and OLE embeddings](#what-it-does-not-read-yet)), so decrypting it is out of scope until something needs to.
+
+`writePptContent` never encrypts.
 
 ## Writing a document
 
@@ -84,6 +107,7 @@ The whole path from a file's first byte to a slide's text, record by record:
 | Container       | The `Current User` and `PowerPoint Document` streams, read through `archive-codec`'s bounded [MS-CFB] reader.                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | Record framing  | The generic 8-byte `RecordHeader`, the container/atom distinction, sibling sequences, child walks, and typed-descendant search — shared with [MS-ODRAW]'s records, which carry the identical header.                                                                                                                                                                                                                                                                                                                           |
 | Edit resolution | `CurrentUserAtom` (including its encrypted/plaintext `headerToken`), the `UserEditAtom` chain, `PersistDirectoryAtom`/`PersistDirectoryEntry`'s packed 20-bit/12-bit run form, and the oldest-first directory construction whose later entries supersede earlier ones — [MS-PPT] 2.1.2's own "live record" process, Part 1.                                                                                                                                                                                                    |
+| Encryption      | `DocumentEncryptionAtom` (`UserEditAtom.encryptSessionPersistIdRef` → the persist directory), [MS-OFFCRYPTO] 2.3.5's RC4 CryptoAPI scheme — see [Encryption](#encryption).                                                                                                                                                                                                                                                                                                                                                     |
 | Document        | `DocumentContainer` → `DocumentAtom` (slide size, in master units), `DocumentTextInfoContainer`'s `FontCollectionContainer`/`FontEntityAtom` typeface names, and `SlideListWithTextContainer` (distinguished from the master and notes lists by `recInstance`, which does not run in the order the names suggest).                                                                                                                                                                                                             |
 | Slides          | `SlidePersistAtom` → the persist directory → each `SlideContainer`, and the placeholder texts the slide list carries for it.                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Speaker notes   | `NotesListWithTextContainer` (the third of the three containers sharing `RT_SlideListWithText`) → `NotesPersistAtom` → the persist directory → each `NotesContainer`, and the `NotesAtom.slideIdRef` naming the presentation slide those notes belong to. The text comes from the notes slide's own drawing, since the notes list — unlike the slide list — carries no texts for an `OutlineTextRefAtom` to reach into.                                                                                                        |
@@ -97,7 +121,6 @@ Geometry is converted from master units (1/576 inch) to points on the way out, s
 
 Each of these is a real construct of the format that this package currently ignores or cannot represent — not a claim that it does not exist:
 
-- **Encrypted documents.** Recognised and refused by name (`PptEncryptedError`) rather than misparsed, but not decrypted.
 - **`DocumentSummaryInformation`'s extended and user-defined properties** (company, manager, custom properties) — a genuinely different stream from the one [Metadata](#metadata) covers, not attempted at all.
 - **Master and layout inheritance.** A run that states no size, typeface, or weight inherits it from the master's `TextMasterStyleAtom`; this reader reports such a property as absent rather than resolving the cascade, so a run's formatting is what the slide itself states and no more.
 - **Scheme colours.** A `ColorIndexStruct` naming a colour-scheme slot (rather than a literal sRGB value) yields no colour, because resolving it needs the slide's `SlideSchemeColorSchemeAtom`.
@@ -198,6 +221,7 @@ import { readStyleTextPropAtom } from "ppt-codec/text/style";
 | `stream/current-user-write`    | Writes a real `CurrentUserAtom` pointing at the single edit this writer always produces.                                                                                                                                                                                                                                 |
 | `stream/persist`               | `UserEditAtom`, `PersistDirectoryAtom`, and the persist directory the edit chain builds.                                                                                                                                                                                                                                 |
 | `stream/persist-write`         | Writes a single-edit `UserEditAtom`/`PersistDirectoryAtom` pair covering the document container and every slide container.                                                                                                                                                                                               |
+| `encryption`                   | `readDocumentEncryptionAtom`, `decryptPptDocumentStream` — [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI decryption, wired against `archive-codec`'s own key derivation (see [Encryption](#encryption)).                                                                                                                            |
 | `document/document-atom`       | `DocumentAtom`: slide and notes sizes, master persist references.                                                                                                                                                                                                                                                        |
 | `document/document-atom-write` | Writes a `DocumentAtom` for the one slide size every slide must share.                                                                                                                                                                                                                                                   |
 | `document/fonts`               | The font collection, resolved to typeface names a `FontIndexRef` indexes.                                                                                                                                                                                                                                                |
@@ -221,7 +245,7 @@ import { readStyleTextPropAtom } from "ppt-codec/text/style";
 | `read`                         | The whole read pipeline, and the `readPpt`/`readPptContent`/`readPptStreams` surface.                                                                                                                                                                                                                                    |
 | `write`                        | The whole write pipeline, and the `writePpt`/`writePptContent`/`writePptStreams` surface.                                                                                                                                                                                                                                |
 | `units`                        | Master units to points, and points to master units.                                                                                                                                                                                                                                                                      |
-| `errors`                       | `PptFormatError` for malformed input, `PptEncryptedError` for well-formed input this package cannot decrypt, `PptUnsupportedContentError` for well-formed content this package's writer cannot express.                                                                                                                  |
+| `errors`                       | `PptFormatError` for malformed input, `PptEncryptedError` for encrypted input given no password, an incorrect one, or an encryption scheme this package does not implement (anything other than RC4 CryptoAPI), `PptUnsupportedContentError` for well-formed content this package's writer cannot express.               |
 
 ### Every fixture is built from the specification, not captured
 

package/dist/encryption.cjs

@@ -0,0 +1,82 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("./errors.cjs");
+require("./record/header.cjs");
+const require_record_tree = require("./record/tree.cjs");
+const require_record_types = require("./record/types.cjs");
+let archive_codec = require("archive-codec");
+//#region src/encryption.ts
+const ALG_ID_RC4 = 26625;
+const ALG_ID_HASH_SHA1 = 32772;
+const CRYPTOAPI_VERSION_MINOR = 2;
+const CRYPTOAPI_VERSION_MAJOR_MIN = 2;
+const CRYPTOAPI_VERSION_MAJOR_MAX = 4;
+const VERSION_MAJOR_OFFSET = 0;
+const VERSION_MINOR_OFFSET = 2;
+const HEADER_SIZE_FIELD_OFFSET = 8;
+const HEADER_START = 12;
+const DEFAULT_KEY_SIZE_BITS = 40;
+const MIN_HEADER_FIELDS_LENGTH = 32;
+/** Parses a DocumentEncryptionAtom's own fields -- never encrypted, since it is what a decryptor needs before it can decrypt anything else. */
+function readDocumentEncryptionAtom(record) {
+	if (record.header.recType !== 12052) throw new require_errors.PptFormatError(`expected the DocumentEncryptionAtom's own record type (0x${require_record_types.RT_CryptSession10Container.toString(16)}) at offset ${record.offset}, found 0x${record.header.recType.toString(16)}`);
+	const { data } = record;
+	if (data.length < HEADER_START) throw new require_errors.PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} carries ${data.length} bytes, fewer than the ${HEADER_START}-byte fixed portion (version, encryptionFlags, headerSize) it requires`);
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const versionMajor = view.getUint16(VERSION_MAJOR_OFFSET, true);
+	const versionMinor = view.getUint16(VERSION_MINOR_OFFSET, true);
+	if (versionMajor < CRYPTOAPI_VERSION_MAJOR_MIN || versionMajor > CRYPTOAPI_VERSION_MAJOR_MAX || versionMinor !== CRYPTOAPI_VERSION_MINOR) throw new require_errors.PptEncryptedError(`DocumentEncryptionAtom declares version ${versionMajor}.${versionMinor}, outside [MS-OFFCRYPTO] 2.3.5.1's RC4 CryptoAPI range (major 2-4, minor 2); this package only decrypts RC4 CryptoAPI-encrypted presentations`);
+	const headerSize = view.getUint32(HEADER_SIZE_FIELD_OFFSET, true);
+	const headerEnd = HEADER_START + headerSize;
+	if (headerSize < MIN_HEADER_FIELDS_LENGTH || headerEnd > data.length) throw new require_errors.PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} declares a ${headerSize}-byte EncryptionHeader, which is either shorter than the ${MIN_HEADER_FIELDS_LENGTH} fixed fields require or runs past the atom's own ${data.length} bytes`);
+	const algId = view.getUint32(20, true);
+	if (algId !== ALG_ID_RC4) throw new require_errors.PptEncryptedError(`DocumentEncryptionAtom's EncryptionHeader names cipher algorithm 0x${algId.toString(16)}, not RC4 (0x${ALG_ID_RC4.toString(16)}); this package only decrypts RC4 CryptoAPI-encrypted presentations`);
+	const algIdHash = view.getUint32(24, true);
+	if (algIdHash !== ALG_ID_HASH_SHA1) throw new require_errors.PptEncryptedError(`DocumentEncryptionAtom's EncryptionHeader names hash algorithm 0x${algIdHash.toString(16)}, not SHA-1 (0x${ALG_ID_HASH_SHA1.toString(16)}) as [MS-OFFCRYPTO] 2.3.5.1 requires of RC4 CryptoAPI`);
+	const rawKeySize = view.getUint32(28, true);
+	const keySizeBits = rawKeySize === 0 ? DEFAULT_KEY_SIZE_BITS : rawKeySize;
+	if (headerEnd + 4 > data.length) throw new require_errors.PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} has no room for its EncryptionVerifier's saltSize field after the ${headerSize}-byte header`);
+	const saltSize = view.getUint32(headerEnd, true);
+	if (saltSize !== archive_codec.RC4_CRYPTOAPI_SALT_LENGTH) throw new require_errors.PptFormatError(`DocumentEncryptionAtom's EncryptionVerifier declares saltSize ${saltSize}, not the mandated ${archive_codec.RC4_CRYPTOAPI_SALT_LENGTH}`);
+	const saltStart = headerEnd + 4;
+	const encryptedVerifierStart = saltStart + archive_codec.RC4_CRYPTOAPI_SALT_LENGTH;
+	const verifierHashSizeFieldStart = encryptedVerifierStart + archive_codec.RC4_CRYPTOAPI_VERIFIER_LENGTH;
+	const encryptedVerifierHashStart = verifierHashSizeFieldStart + 4;
+	const encryptedVerifierHashEnd = encryptedVerifierHashStart + archive_codec.RC4_CRYPTOAPI_VERIFIER_HASH_LENGTH;
+	if (encryptedVerifierHashEnd > data.length) throw new require_errors.PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} carries ${data.length} bytes, too few for its EncryptionVerifier's salt/encryptedVerifier/encryptedVerifierHash fields`);
+	return {
+		keySizeBits,
+		salt: data.subarray(saltStart, encryptedVerifierStart),
+		encryptedVerifier: data.subarray(encryptedVerifierStart, verifierHashSizeFieldStart),
+		encryptedVerifierHash: data.subarray(encryptedVerifierHashStart, encryptedVerifierHashEnd)
+	};
+}
+/**
+* Decrypts a PowerPoint Document stream protected by [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI, given the password and the persist directory/`encryptSessionPersistIdRef` `buildPersistDirectory` already resolved -- both come from parsing the stream's own never-encrypted UserEditAtom/PersistDirectoryAtom chain, which is why this module needs them handed in rather than deriving them itself.
+*
+* Returns a new, fully decrypted copy of the stream: every persist object in `directory` except the DocumentEncryptionAtom itself gets its own key, derived from its own persist ID as the RC4 CryptoAPI "block number" (see this file's own top comment), and is decrypted as one continuous keystream covering its header and data together -- the header is encrypted too here, unlike the shared xls/doc RC4 scheme, so each object's own recLen has to be learned by decrypting its header first.
+*
+* Throws `PptEncryptedError` for a missing password, an incorrect one, or an encryption shape this module does not implement (anything other than RC4 CryptoAPI) -- there is no partial or best-effort result to return in any of those cases.
+*/
+function decryptPptDocumentStream(streamBytes, directory, encryptSessionPersistIdRef, password) {
+	const encryptionAtomOffset = directory.get(encryptSessionPersistIdRef);
+	if (encryptionAtomOffset === void 0) throw new require_errors.PptFormatError(`UserEditAtom.encryptSessionPersistIdRef ${encryptSessionPersistIdRef} references persist object ${encryptSessionPersistIdRef}, which the persist directory does not contain`);
+	const info = readDocumentEncryptionAtom(require_record_tree.readRecordAt(streamBytes, encryptionAtomOffset));
+	if (!(0, archive_codec.verifyRc4CryptoApiPassword)(password, info.salt, info.keySizeBits, info.encryptedVerifier, info.encryptedVerifierHash)) throw new require_errors.PptEncryptedError("incorrect password for RC4 CryptoAPI-encrypted presentation");
+	const decrypted = new Uint8Array(streamBytes.length);
+	decrypted.set(streamBytes);
+	for (const [persistId, offset] of directory) {
+		if (persistId === encryptSessionPersistIdRef) continue;
+		if (offset + 8 > streamBytes.length) throw new require_errors.PptFormatError(`persist object ${persistId} at offset ${offset} needs 8 bytes for its own record header, but only ${streamBytes.length - offset} remain in the stream`);
+		const key = (0, archive_codec.deriveRc4CryptoApiBlockKey)(password, info.salt, persistId, info.keySizeBits);
+		const headerPlaintext = (0, archive_codec.rc4)(key, streamBytes.subarray(offset, offset + 8));
+		const recLen = new DataView(headerPlaintext.buffer, headerPlaintext.byteOffset, headerPlaintext.byteLength).getUint32(4, true);
+		const objectEnd = offset + 8 + recLen;
+		if (objectEnd > streamBytes.length) throw new require_errors.PptFormatError(`persist object ${persistId} at offset ${offset} decrypts to a ${recLen}-byte record, which runs past the stream's own ${streamBytes.length} bytes`);
+		const plaintext = (0, archive_codec.rc4)(key, streamBytes.subarray(offset, objectEnd));
+		decrypted.set(plaintext, offset);
+	}
+	return decrypted;
+}
+//#endregion
+exports.decryptPptDocumentStream = decryptPptDocumentStream;
+exports.readDocumentEncryptionAtom = readDocumentEncryptionAtom;

package/dist/encryption.d.cts

@@ -0,0 +1,20 @@
+import { t as PptRecord } from "./tree-Du_LXAF0.cjs";
+//#region src/encryption.d.ts
+interface PptEncryptionInfo {
+  readonly keySizeBits: number;
+  readonly salt: Uint8Array<ArrayBuffer>;
+  readonly encryptedVerifier: Uint8Array<ArrayBuffer>;
+  readonly encryptedVerifierHash: Uint8Array<ArrayBuffer>;
+}
+/** Parses a DocumentEncryptionAtom's own fields -- never encrypted, since it is what a decryptor needs before it can decrypt anything else. */
+declare function readDocumentEncryptionAtom(record: PptRecord): PptEncryptionInfo;
+/**
+ * Decrypts a PowerPoint Document stream protected by [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI, given the password and the persist directory/`encryptSessionPersistIdRef` `buildPersistDirectory` already resolved -- both come from parsing the stream's own never-encrypted UserEditAtom/PersistDirectoryAtom chain, which is why this module needs them handed in rather than deriving them itself.
+ *
+ * Returns a new, fully decrypted copy of the stream: every persist object in `directory` except the DocumentEncryptionAtom itself gets its own key, derived from its own persist ID as the RC4 CryptoAPI "block number" (see this file's own top comment), and is decrypted as one continuous keystream covering its header and data together -- the header is encrypted too here, unlike the shared xls/doc RC4 scheme, so each object's own recLen has to be learned by decrypting its header first.
+ *
+ * Throws `PptEncryptedError` for a missing password, an incorrect one, or an encryption shape this module does not implement (anything other than RC4 CryptoAPI) -- there is no partial or best-effort result to return in any of those cases.
+ */
+declare function decryptPptDocumentStream(streamBytes: Uint8Array<ArrayBuffer>, directory: ReadonlyMap<number, number>, encryptSessionPersistIdRef: number, password: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { PptEncryptionInfo, decryptPptDocumentStream, readDocumentEncryptionAtom };

package/dist/encryption.d.ts

@@ -0,0 +1,20 @@
+import { t as PptRecord } from "./tree-PMcPNgd-.js";
+//#region src/encryption.d.ts
+interface PptEncryptionInfo {
+  readonly keySizeBits: number;
+  readonly salt: Uint8Array<ArrayBuffer>;
+  readonly encryptedVerifier: Uint8Array<ArrayBuffer>;
+  readonly encryptedVerifierHash: Uint8Array<ArrayBuffer>;
+}
+/** Parses a DocumentEncryptionAtom's own fields -- never encrypted, since it is what a decryptor needs before it can decrypt anything else. */
+declare function readDocumentEncryptionAtom(record: PptRecord): PptEncryptionInfo;
+/**
+ * Decrypts a PowerPoint Document stream protected by [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI, given the password and the persist directory/`encryptSessionPersistIdRef` `buildPersistDirectory` already resolved -- both come from parsing the stream's own never-encrypted UserEditAtom/PersistDirectoryAtom chain, which is why this module needs them handed in rather than deriving them itself.
+ *
+ * Returns a new, fully decrypted copy of the stream: every persist object in `directory` except the DocumentEncryptionAtom itself gets its own key, derived from its own persist ID as the RC4 CryptoAPI "block number" (see this file's own top comment), and is decrypted as one continuous keystream covering its header and data together -- the header is encrypted too here, unlike the shared xls/doc RC4 scheme, so each object's own recLen has to be learned by decrypting its header first.
+ *
+ * Throws `PptEncryptedError` for a missing password, an incorrect one, or an encryption shape this module does not implement (anything other than RC4 CryptoAPI) -- there is no partial or best-effort result to return in any of those cases.
+ */
+declare function decryptPptDocumentStream(streamBytes: Uint8Array<ArrayBuffer>, directory: ReadonlyMap<number, number>, encryptSessionPersistIdRef: number, password: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { PptEncryptionInfo, decryptPptDocumentStream, readDocumentEncryptionAtom };

package/dist/encryption.js

@@ -0,0 +1,80 @@
+import { PptEncryptedError, PptFormatError } from "./errors.js";
+import "./record/header.js";
+import { readRecordAt } from "./record/tree.js";
+import { RT_CryptSession10Container } from "./record/types.js";
+import { RC4_CRYPTOAPI_SALT_LENGTH, RC4_CRYPTOAPI_VERIFIER_HASH_LENGTH, RC4_CRYPTOAPI_VERIFIER_LENGTH, deriveRc4CryptoApiBlockKey, rc4, verifyRc4CryptoApiPassword } from "archive-codec";
+//#region src/encryption.ts
+const ALG_ID_RC4 = 26625;
+const ALG_ID_HASH_SHA1 = 32772;
+const CRYPTOAPI_VERSION_MINOR = 2;
+const CRYPTOAPI_VERSION_MAJOR_MIN = 2;
+const CRYPTOAPI_VERSION_MAJOR_MAX = 4;
+const VERSION_MAJOR_OFFSET = 0;
+const VERSION_MINOR_OFFSET = 2;
+const HEADER_SIZE_FIELD_OFFSET = 8;
+const HEADER_START = 12;
+const DEFAULT_KEY_SIZE_BITS = 40;
+const MIN_HEADER_FIELDS_LENGTH = 32;
+/** Parses a DocumentEncryptionAtom's own fields -- never encrypted, since it is what a decryptor needs before it can decrypt anything else. */
+function readDocumentEncryptionAtom(record) {
+	if (record.header.recType !== 12052) throw new PptFormatError(`expected the DocumentEncryptionAtom's own record type (0x${RT_CryptSession10Container.toString(16)}) at offset ${record.offset}, found 0x${record.header.recType.toString(16)}`);
+	const { data } = record;
+	if (data.length < HEADER_START) throw new PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} carries ${data.length} bytes, fewer than the ${HEADER_START}-byte fixed portion (version, encryptionFlags, headerSize) it requires`);
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const versionMajor = view.getUint16(VERSION_MAJOR_OFFSET, true);
+	const versionMinor = view.getUint16(VERSION_MINOR_OFFSET, true);
+	if (versionMajor < CRYPTOAPI_VERSION_MAJOR_MIN || versionMajor > CRYPTOAPI_VERSION_MAJOR_MAX || versionMinor !== CRYPTOAPI_VERSION_MINOR) throw new PptEncryptedError(`DocumentEncryptionAtom declares version ${versionMajor}.${versionMinor}, outside [MS-OFFCRYPTO] 2.3.5.1's RC4 CryptoAPI range (major 2-4, minor 2); this package only decrypts RC4 CryptoAPI-encrypted presentations`);
+	const headerSize = view.getUint32(HEADER_SIZE_FIELD_OFFSET, true);
+	const headerEnd = HEADER_START + headerSize;
+	if (headerSize < MIN_HEADER_FIELDS_LENGTH || headerEnd > data.length) throw new PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} declares a ${headerSize}-byte EncryptionHeader, which is either shorter than the ${MIN_HEADER_FIELDS_LENGTH} fixed fields require or runs past the atom's own ${data.length} bytes`);
+	const algId = view.getUint32(20, true);
+	if (algId !== ALG_ID_RC4) throw new PptEncryptedError(`DocumentEncryptionAtom's EncryptionHeader names cipher algorithm 0x${algId.toString(16)}, not RC4 (0x${ALG_ID_RC4.toString(16)}); this package only decrypts RC4 CryptoAPI-encrypted presentations`);
+	const algIdHash = view.getUint32(24, true);
+	if (algIdHash !== ALG_ID_HASH_SHA1) throw new PptEncryptedError(`DocumentEncryptionAtom's EncryptionHeader names hash algorithm 0x${algIdHash.toString(16)}, not SHA-1 (0x${ALG_ID_HASH_SHA1.toString(16)}) as [MS-OFFCRYPTO] 2.3.5.1 requires of RC4 CryptoAPI`);
+	const rawKeySize = view.getUint32(28, true);
+	const keySizeBits = rawKeySize === 0 ? DEFAULT_KEY_SIZE_BITS : rawKeySize;
+	if (headerEnd + 4 > data.length) throw new PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} has no room for its EncryptionVerifier's saltSize field after the ${headerSize}-byte header`);
+	const saltSize = view.getUint32(headerEnd, true);
+	if (saltSize !== RC4_CRYPTOAPI_SALT_LENGTH) throw new PptFormatError(`DocumentEncryptionAtom's EncryptionVerifier declares saltSize ${saltSize}, not the mandated ${RC4_CRYPTOAPI_SALT_LENGTH}`);
+	const saltStart = headerEnd + 4;
+	const encryptedVerifierStart = saltStart + RC4_CRYPTOAPI_SALT_LENGTH;
+	const verifierHashSizeFieldStart = encryptedVerifierStart + RC4_CRYPTOAPI_VERIFIER_LENGTH;
+	const encryptedVerifierHashStart = verifierHashSizeFieldStart + 4;
+	const encryptedVerifierHashEnd = encryptedVerifierHashStart + RC4_CRYPTOAPI_VERIFIER_HASH_LENGTH;
+	if (encryptedVerifierHashEnd > data.length) throw new PptFormatError(`DocumentEncryptionAtom at offset ${record.offset} carries ${data.length} bytes, too few for its EncryptionVerifier's salt/encryptedVerifier/encryptedVerifierHash fields`);
+	return {
+		keySizeBits,
+		salt: data.subarray(saltStart, encryptedVerifierStart),
+		encryptedVerifier: data.subarray(encryptedVerifierStart, verifierHashSizeFieldStart),
+		encryptedVerifierHash: data.subarray(encryptedVerifierHashStart, encryptedVerifierHashEnd)
+	};
+}
+/**
+* Decrypts a PowerPoint Document stream protected by [MS-OFFCRYPTO] 2.3.5 RC4 CryptoAPI, given the password and the persist directory/`encryptSessionPersistIdRef` `buildPersistDirectory` already resolved -- both come from parsing the stream's own never-encrypted UserEditAtom/PersistDirectoryAtom chain, which is why this module needs them handed in rather than deriving them itself.
+*
+* Returns a new, fully decrypted copy of the stream: every persist object in `directory` except the DocumentEncryptionAtom itself gets its own key, derived from its own persist ID as the RC4 CryptoAPI "block number" (see this file's own top comment), and is decrypted as one continuous keystream covering its header and data together -- the header is encrypted too here, unlike the shared xls/doc RC4 scheme, so each object's own recLen has to be learned by decrypting its header first.
+*
+* Throws `PptEncryptedError` for a missing password, an incorrect one, or an encryption shape this module does not implement (anything other than RC4 CryptoAPI) -- there is no partial or best-effort result to return in any of those cases.
+*/
+function decryptPptDocumentStream(streamBytes, directory, encryptSessionPersistIdRef, password) {
+	const encryptionAtomOffset = directory.get(encryptSessionPersistIdRef);
+	if (encryptionAtomOffset === void 0) throw new PptFormatError(`UserEditAtom.encryptSessionPersistIdRef ${encryptSessionPersistIdRef} references persist object ${encryptSessionPersistIdRef}, which the persist directory does not contain`);
+	const info = readDocumentEncryptionAtom(readRecordAt(streamBytes, encryptionAtomOffset));
+	if (!verifyRc4CryptoApiPassword(password, info.salt, info.keySizeBits, info.encryptedVerifier, info.encryptedVerifierHash)) throw new PptEncryptedError("incorrect password for RC4 CryptoAPI-encrypted presentation");
+	const decrypted = new Uint8Array(streamBytes.length);
+	decrypted.set(streamBytes);
+	for (const [persistId, offset] of directory) {
+		if (persistId === encryptSessionPersistIdRef) continue;
+		if (offset + 8 > streamBytes.length) throw new PptFormatError(`persist object ${persistId} at offset ${offset} needs 8 bytes for its own record header, but only ${streamBytes.length - offset} remain in the stream`);
+		const key = deriveRc4CryptoApiBlockKey(password, info.salt, persistId, info.keySizeBits);
+		const headerPlaintext = rc4(key, streamBytes.subarray(offset, offset + 8));
+		const recLen = new DataView(headerPlaintext.buffer, headerPlaintext.byteOffset, headerPlaintext.byteLength).getUint32(4, true);
+		const objectEnd = offset + 8 + recLen;
+		if (objectEnd > streamBytes.length) throw new PptFormatError(`persist object ${persistId} at offset ${offset} decrypts to a ${recLen}-byte record, which runs past the stream's own ${streamBytes.length} bytes`);
+		const plaintext = rc4(key, streamBytes.subarray(offset, objectEnd));
+		decrypted.set(plaintext, offset);
+	}
+	return decrypted;
+}
+//#endregion
+export { decryptPptDocumentStream, readDocumentEncryptionAtom };

package/dist/read.cjs

@@ -6,6 +6,7 @@ const require_text_style = require("./text/style.cjs");
 const require_text_atoms = require("./text/atoms.cjs");
 const require_units = require("./units.cjs");
 const require_content = require("./content.cjs");
+const require_encryption = require("./encryption.cjs");
 const require_document_document_atom = require("./document/document-atom.cjs");
 const require_document_fonts = require("./document/fonts.cjs");
 const require_document_notes_list = require("./document/notes-list.cjs");
@@ -89,11 +90,16 @@ function readSlide(streamBytes, directory, persist, size, fontNames, notes) {
 		notes
 	};
 }
-function readPptStreams(currentUserStream, powerPointDocumentStream) {
+function readPptStreams(currentUserStream, powerPointDocumentStream, password) {
 	const currentUser = require_stream_current_user.readCurrentUserAtom(currentUserStream);
-	if (currentUser.encrypted) throw new require_errors.PptEncryptedError("the CurrentUserAtom's headerToken marks this document as encrypted, and this package does not implement [MS-PPT]'s encryption");
 	const { directory, currentEdit } = require_stream_persist.buildPersistDirectory(powerPointDocumentStream, currentUser.offsetToCurrentEdit);
-	const documentContainer = require_stream_persist.resolvePersistObject(powerPointDocumentStream, directory, currentEdit.docPersistIdRef, "UserEditAtom.docPersistIdRef");
+	let streamBytes = powerPointDocumentStream;
+	if (currentUser.encrypted) {
+		if (password === void 0) throw new require_errors.PptEncryptedError("the CurrentUserAtom's headerToken marks this document as RC4 CryptoAPI-encrypted ([MS-OFFCRYPTO] 2.3.5); call readPptStreams with a password to decrypt it");
+		if (currentEdit.encryptSessionPersistIdRef === void 0) throw new require_errors.PptFormatError("the CurrentUserAtom marks this document as encrypted, but its current UserEditAtom carries no encryptSessionPersistIdRef");
+		streamBytes = require_encryption.decryptPptDocumentStream(powerPointDocumentStream, directory, currentEdit.encryptSessionPersistIdRef, password);
+	}
+	const documentContainer = require_stream_persist.resolvePersistObject(streamBytes, directory, currentEdit.docPersistIdRef, "UserEditAtom.docPersistIdRef");
 	if (documentContainer.header.recType !== 1e3) throw new require_errors.PptFormatError(`the document persist object is record type 0x${documentContainer.header.recType.toString(16)}, not RT_Document (0x${require_record_types.RT_Document.toString(16)})`);
 	const children = require_record_tree.childRecords(documentContainer);
 	const documentAtomRecord = require_record_tree.findChild(children, require_record_types.RT_DocumentAtom);
@@ -108,15 +114,15 @@ function readPptStreams(currentUserStream, powerPointDocumentStream) {
 	const listWithInstance = (instance) => children.find((record) => record.header.recType === 4080 && record.header.recInstance === instance);
 	const slideList = listWithInstance(0);
 	const persists = slideList === void 0 ? [] : require_document_slide_list.readSlideListWithText(slideList);
-	const notesBySlideId = readNotesBySlideId(powerPointDocumentStream, directory, listWithInstance(2));
+	const notesBySlideId = readNotesBySlideId(streamBytes, directory, listWithInstance(2));
 	return {
 		metadata: {},
-		slides: persists.map((persist) => readSlide(powerPointDocumentStream, directory, persist, size, fontNames, notesBySlideId.get(persist.slideId) ?? ""))
+		slides: persists.map((persist) => readSlide(streamBytes, directory, persist, size, fontNames, notesBySlideId.get(persist.slideId) ?? ""))
 	};
 }
-function readPptContent(bytes) {
+function readPptContent(bytes, password) {
 	const streams = (0, archive_codec.readCompoundFile)(bytes);
-	const document = readPptStreams(requireStream(streams, CURRENT_USER_STREAM), requireStream(streams, POWERPOINT_DOCUMENT_STREAM));
+	const document = readPptStreams(requireStream(streams, CURRENT_USER_STREAM), requireStream(streams, POWERPOINT_DOCUMENT_STREAM), password);
 	const metadataStream = streams.find((stream) => stream.path === SUMMARY_INFORMATION_STREAM);
 	if (metadataStream === void 0) return document;
 	return {
@@ -124,8 +130,8 @@ function readPptContent(bytes) {
 		metadata: (0, archive_codec.summaryInformationToLayoutMetadata)((0, archive_codec.readSummaryInformation)(metadataStream.bytes))
 	};
 }
-function readPpt(bytes) {
-	const { metadata, slides } = readPptContent(bytes);
+function readPpt(bytes, password) {
+	const { metadata, slides } = readPptContent(bytes, password);
 	const document = {
 		kind: "presentation",
 		metadata,

package/dist/read.d.cts

@@ -10,8 +10,8 @@ interface PptDocument {
   readonly metadata: LayoutMetadata;
   readonly slides: readonly ContentSlide[];
 }
-declare function readPptStreams(currentUserStream: Uint8Array<ArrayBuffer>, powerPointDocumentStream: Uint8Array<ArrayBuffer>): PptDocument;
-declare function readPptContent(bytes: Uint8Array<ArrayBuffer>): PptDocument;
-declare function readPpt(bytes: Uint8Array<ArrayBuffer>): DocumentTree;
+declare function readPptStreams(currentUserStream: Uint8Array<ArrayBuffer>, powerPointDocumentStream: Uint8Array<ArrayBuffer>, password?: string): PptDocument;
+declare function readPptContent(bytes: Uint8Array<ArrayBuffer>, password?: string): PptDocument;
+declare function readPpt(bytes: Uint8Array<ArrayBuffer>, password?: string): DocumentTree;
 //#endregion
 export { CURRENT_USER_STREAM, DEFAULT_INSET_LEFT_RIGHT_PT, DEFAULT_INSET_TOP_BOTTOM_PT, POWERPOINT_DOCUMENT_STREAM, PptDocument, SUMMARY_INFORMATION_STREAM, readPpt, readPptContent, readPptStreams };

package/dist/read.d.ts

@@ -10,8 +10,8 @@ interface PptDocument {
   readonly metadata: LayoutMetadata;
   readonly slides: readonly ContentSlide[];
 }
-declare function readPptStreams(currentUserStream: Uint8Array<ArrayBuffer>, powerPointDocumentStream: Uint8Array<ArrayBuffer>): PptDocument;
-declare function readPptContent(bytes: Uint8Array<ArrayBuffer>): PptDocument;
-declare function readPpt(bytes: Uint8Array<ArrayBuffer>): DocumentTree;
+declare function readPptStreams(currentUserStream: Uint8Array<ArrayBuffer>, powerPointDocumentStream: Uint8Array<ArrayBuffer>, password?: string): PptDocument;
+declare function readPptContent(bytes: Uint8Array<ArrayBuffer>, password?: string): PptDocument;
+declare function readPpt(bytes: Uint8Array<ArrayBuffer>, password?: string): DocumentTree;
 //#endregion
 export { CURRENT_USER_STREAM, DEFAULT_INSET_LEFT_RIGHT_PT, DEFAULT_INSET_TOP_BOTTOM_PT, POWERPOINT_DOCUMENT_STREAM, PptDocument, SUMMARY_INFORMATION_STREAM, readPpt, readPptContent, readPptStreams };

package/dist/read.js

@@ -5,6 +5,7 @@ import { readStyleTextPropAtom } from "./text/style.js";
 import { characterCountOf, readTextBody } from "./text/atoms.js";
 import { masterUnitsToPoints } from "./units.js";
 import { buildParagraphs } from "./content.js";
+import { decryptPptDocumentStream } from "./encryption.js";
 import { readDocumentAtom } from "./document/document-atom.js";
 import { readFontNames } from "./document/fonts.js";
 import { readNotesListWithText } from "./document/notes-list.js";
@@ -88,11 +89,16 @@ function readSlide(streamBytes, directory, persist, size, fontNames, notes) {
 		notes
 	};
 }
-function readPptStreams(currentUserStream, powerPointDocumentStream) {
+function readPptStreams(currentUserStream, powerPointDocumentStream, password) {
 	const currentUser = readCurrentUserAtom(currentUserStream);
-	if (currentUser.encrypted) throw new PptEncryptedError("the CurrentUserAtom's headerToken marks this document as encrypted, and this package does not implement [MS-PPT]'s encryption");
 	const { directory, currentEdit } = buildPersistDirectory(powerPointDocumentStream, currentUser.offsetToCurrentEdit);
-	const documentContainer = resolvePersistObject(powerPointDocumentStream, directory, currentEdit.docPersistIdRef, "UserEditAtom.docPersistIdRef");
+	let streamBytes = powerPointDocumentStream;
+	if (currentUser.encrypted) {
+		if (password === void 0) throw new PptEncryptedError("the CurrentUserAtom's headerToken marks this document as RC4 CryptoAPI-encrypted ([MS-OFFCRYPTO] 2.3.5); call readPptStreams with a password to decrypt it");
+		if (currentEdit.encryptSessionPersistIdRef === void 0) throw new PptFormatError("the CurrentUserAtom marks this document as encrypted, but its current UserEditAtom carries no encryptSessionPersistIdRef");
+		streamBytes = decryptPptDocumentStream(powerPointDocumentStream, directory, currentEdit.encryptSessionPersistIdRef, password);
+	}
+	const documentContainer = resolvePersistObject(streamBytes, directory, currentEdit.docPersistIdRef, "UserEditAtom.docPersistIdRef");
 	if (documentContainer.header.recType !== 1e3) throw new PptFormatError(`the document persist object is record type 0x${documentContainer.header.recType.toString(16)}, not RT_Document (0x${RT_Document.toString(16)})`);
 	const children = childRecords(documentContainer);
 	const documentAtomRecord = findChild(children, RT_DocumentAtom);
@@ -107,15 +113,15 @@ function readPptStreams(currentUserStream, powerPointDocumentStream) {
 	const listWithInstance = (instance) => children.find((record) => record.header.recType === 4080 && record.header.recInstance === instance);
 	const slideList = listWithInstance(0);
 	const persists = slideList === void 0 ? [] : readSlideListWithText(slideList);
-	const notesBySlideId = readNotesBySlideId(powerPointDocumentStream, directory, listWithInstance(2));
+	const notesBySlideId = readNotesBySlideId(streamBytes, directory, listWithInstance(2));
 	return {
 		metadata: {},
-		slides: persists.map((persist) => readSlide(powerPointDocumentStream, directory, persist, size, fontNames, notesBySlideId.get(persist.slideId) ?? ""))
+		slides: persists.map((persist) => readSlide(streamBytes, directory, persist, size, fontNames, notesBySlideId.get(persist.slideId) ?? ""))
 	};
 }
-function readPptContent(bytes) {
+function readPptContent(bytes, password) {
 	const streams = readCompoundFile(bytes);
-	const document = readPptStreams(requireStream(streams, CURRENT_USER_STREAM), requireStream(streams, POWERPOINT_DOCUMENT_STREAM));
+	const document = readPptStreams(requireStream(streams, CURRENT_USER_STREAM), requireStream(streams, POWERPOINT_DOCUMENT_STREAM), password);
 	const metadataStream = streams.find((stream) => stream.path === SUMMARY_INFORMATION_STREAM);
 	if (metadataStream === void 0) return document;
 	return {
@@ -123,8 +129,8 @@ function readPptContent(bytes) {
 		metadata: summaryInformationToLayoutMetadata(readSummaryInformation(metadataStream.bytes))
 	};
 }
-function readPpt(bytes) {
-	const { metadata, slides } = readPptContent(bytes);
+function readPpt(bytes, password) {
+	const { metadata, slides } = readPptContent(bytes, password);
 	const document = {
 		kind: "presentation",
 		metadata,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppt-codec",
-  "version": "1.2.12",
+  "version": "1.3.0",
   "description": "Hand-written PowerPoint 97-2003 binary (.ppt, [MS-PPT]) reader and writer against the shared document-schema.js content pivot.",
   "type": "module",
   "repository": {
@@ -78,7 +78,7 @@
   "license": "MIT",
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "archive-codec": "1.7.2",
+    "archive-codec": "1.9.0",
     "document-schema.js": "7.3.1"
   },
   "devDependencies": {