Installation

npm install @stackline/cfb@1.1.0

To replace cfb without changing application code:

npm install cfb@npm:@stackline/cfb@1.1.0

Node.js: >=0.8. Read the compatibility notes before migrating.

Usage and API

@stackline/cfb

Drop-in replacement for cfb 1.2.2 that ends the endless loops on damaged files, fixes the CVE-2024-22363 regular expression, and reads ZIP64 archives, with identical results everywhere else. Zero dependencies; Node.js 0.8 and newer, browsers, and TypeScript.

Documentation | npm | Issues | Repository

Current package version: 1.1.0

Why this package?

Change one line in package.json. Keep every result. Stop the hangs.

cfb@1.2.2 reads and writes OLE compound files (XLS, DOC, PPT, MSG, MSI), ZIP containers, and MIME aggregate documents. It was last published in April 2022. Since then SheetJS has fixed several bugs in the copy of this code embedded in xlsx, including the regular expression behind CVE-2024-22363 and ZIP64 support, but never released those fixes to the cfb package. A damaged file can still make cfb@1.2.2 loop forever.

@stackline/cfb is built for the swap:

• Same results. For intact files, every read result matches cfb@1.2.2: paths, entry fields, dates, and content bytes. Written CFB and ZIP files are byte-identical, except that names of 32 or more characters are written as 31 characters instead of an invalid name record.
• Fixed by default. Damaged files raise errors instead of hanging or leaking uninitialized memory into content, the MIME parser runs in linear time, and valid files that cfb@1.2.2 rejects (ZIP64, stored entries with data descriptors) are read.
• Verified against the original. A differential harness runs both packages on the SheetJS test corpus and on deterministic corruptions of it, and compares every observable result.
• Same runtimes. No runtime dependencies, the same entry points and browser field, and CI on every Node.js line from 0.8 to 24.

Trust and maintenance

• No runtime dependencies.
• Every release is built from the public repository by GitHub Actions and published with npm provenance.
• CI runs the upstream test suite, regression tests for every fix, the differential harness, type checks, a packed-consumer test, and a smoke test on Node.js 0.8.28 through 24.20.0.
• Security reports have a private process in SECURITY.md.
• Release history is recorded in CHANGELOG.md.

Compatibility

Installation

Replace cfb without changing application code:

npm install cfb@npm:@stackline/cfb

Or install under the package's public name:

npm install @stackline/cfb

In the browser:

<script src="dist/cfb.min.js" type="text/javascript"></script>

The xlscfb.js file is designed to be embedded in js-xlsx.

Usage

const CFB = require('cfb'); // or require('@stackline/cfb')

const container = CFB.read('report.xls', { type: 'file' });
const workbook = CFB.find(container, 'Workbook');
const data = workbook.content;

Create a ZIP file:

const archive = CFB.utils.cfb_new();
CFB.utils.cfb_add(archive, 'hello.txt', Buffer.from('Hello'));
const bytes = CFB.write(archive, { type: 'buffer', fileType: 'zip' });

What the swap fixes

See Compatibility for the full contract and how it is verified, and Upstream issues for every upstream issue, pull request, embedded xlsx fix, advisory, and fork.

Write without the seed stream

cfb@1.2.2 adds a \u0001Sh33tJ5 stream to every CFB file it writes. Set noseed to leave it out (js-cfb#22):

const bytes = CFB.write(container, { type: 'buffer', noseed: true });

Without the option, output is unchanged.

Add many entries

cfb_add rebuilds the directory after every call. For bulk additions, skip the checks with unsafe and rebuild once with cfb_gc (js-cfb#2):

const archive = CFB.utils.cfb_new();
for (const [name, content] of entries) {
  CFB.utils.cfb_add(archive, `/data/${name}`, content, { unsafe: true });
}
CFB.utils.cfb_gc(archive);

With unsafe, adding a name that already exists creates a duplicate entry.

Replace a stream

cfb_add replaces the content of an existing entry (js-cfb#21):

const container = CFB.read('report.xls', { type: 'file' });
CFB.utils.cfb_add(container, '/Workbook', updatedBytes);
CFB.writeFile(container, 'report-updated.xls');

API

TypeScript definitions are maintained in types/index.d.ts.

The CFB object exposes the following methods and properties:

CFB.parse(blob) takes a nodejs Buffer or an array of bytes and returns a parsed representation of the data.

CFB.read(blob, opts) wraps parse.

CFB.find(cfb, path) performs a case-insensitive match for the path (or file name, if there are no slashes) and returns an entry object or null if not found.

CFB.write(cfb, opts) generates a file based on the container.

CFB.writeFile(cfb, filename, opts) creates a file with the specified name.

Parse Options

CFB.read takes an options argument. opts.type controls the behavior:

type: "file" needs the Node.js fs module. In browsers, read the file first and pass its bytes (js-cfb#16).

Write Options

CFB.write and CFB.writeFile take an options argument.

opts.type controls the behavior:

opts.fileType controls the output file type:

opts.compression enables DEFLATE compression for ZIP file type.

opts.noseed leaves the \u0001Sh33tJ5 stream out of CFB output.

Utility Functions

The utility functions are available in the CFB.utils object. Functions that accept a name argument strictly deal with absolute file names:

• .cfb_new(?opts) creates a new container object.
• .cfb_add(cfb, name, ?content, ?opts) adds a new file to the cfb, or replaces the content of an existing one. Set the option {unsafe:true} to skip existence checks (for bulk additions)
• .cfb_del(cfb, name) deletes the specified file
• .cfb_mov(cfb, old_name, new_name) moves the old file to new path and name
• .cfb_gc(cfb) rebuilds the directory, for example after bulk additions
• .use_zlib(require("zlib")) loads a nodejs zlib instance.

By default, the library uses a pure JS inflate/deflate implementation. NodeJS zlib.InflateRaw exposes the number of bytes read in versions after 8.11.0. If a supplied zlib does not support the required features, a warning will be displayed in the console and the pure JS fallback will be used.

Container Object Description

The objects returned by parse and read have the following properties:

• .FullPaths is an array of the names of all of the streams (files) and storages (directories) in the container. The paths are properly prefixed from the root entry (so the entries are unique)

• .FileIndex is an array, in the same order as .FullPaths, whose values are objects following the schema:

interface CFBEntry {
  name: string; /** Case-sensitive internal name */
  type: number; /** 1 = dir, 2 = file, 5 = root ; see [MS-CFB] 2.6.1 */
  content: Buffer | number[] | Uint8Array; /** Raw Content */
  ct?: Date; /** Creation Time */
  mt?: Date; /** Modification Time */
  ctype?: String; /** Content-Type (for MAD) */
}

Command-Line Utility

The cfb-cli module ships with a CLI tool for manipulating and inspecting supported files.

References

• MS-CFB: Compound File Binary File Format
• ZIP APPNOTE.TXT: .ZIP File Format Specification
• RFC1951: https://www.ietf.org/rfc/rfc1951.txt
• RFC2045: https://www.ietf.org/rfc/rfc2045.txt
• RFC2557: https://www.ietf.org/rfc/rfc2557.txt

Security

Damaged or hostile input raises an error instead of hanging: looping FAT chains, looping directory links, and truncated or invalid DEFLATE data are detected, and the MIME header parser runs in linear time. Parsed content never includes uninitialized memory, which cfb@1.2.2 returns for a DEFLATE stream shorter than its declared size.

The parser does not cap sizes. A valid archive can still declare a large decompressed size, as with any ZIP reader. Limit input sizes and run untrusted files in a worker or process with resource limits.

See the security policy.

Local Development

Clone the repository and run the following commands from its root:

npm ci
npm test

npm test builds the CommonJS and browser files from bits/, then runs the upstream API suite, the regression tests, the Node.js 0.8-compatible smoke test, and the type checks. Source changes belong in bits/; the build regenerates cfb.js, xlscfb.js, and dist/.

Differential testing

Compare this package with cfb@1.2.2 on any directory of CFB, ZIP, and MIME files:

npm run test:differential -- <corpus-directory>
npm run test:differential -- <corpus-directory> --mutations 10 --max-size 65536

Each input runs in child processes with time and memory limits. The harness reports each input as identical, a long-name write difference, newly readable, or a regression, and exits with 1 on a regression or on a failure that only this package has. To reproduce a finding, pass its label from the report to --match and add --save <directory> to keep the corrupted input. See how compatibility is verified.

Consumer Smoke Test

npm run test:package packs the library and exercises an isolated consumer using the repository fixture.

Release Checklist

1. Update the package version, lockfile, generated version fields, and changelog together.
2. Run the development checks above and audit both npm audit and npm audit --omit=dev.
3. Use the GitHub publish workflow with its Prod environment to publish the exact CI tarball.
4. Verify public npm bytes, package identity, provenance, and the immutable GitHub release evidence.

License

Apache-2.0. Original copyright notices and upstream attribution are retained.

Please consult the attached LICENSE file for details. All rights not explicitly granted by the Apache 2.0 License are reserved by the Original Author.

@stackline/cfb is an independent project and is not affiliated with or endorsed by SheetJS LLC.

Credits and original authors

• Original project: js-cfb.
• sheetjs.
• Copyright (C) 2013-present SheetJS LLC.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.

Compatibility with cfb 1.2.2

Compatibility

@stackline/cfb is a drop-in replacement for cfb@1.2.2. Code that works with cfb 1.2.2 reads the same containers and writes the same bytes after the swap. Behavior changes only where cfb@1.2.2 never returns, cannot read a valid file, or produces an invalid or wrong result.

npm install cfb@npm:@stackline/cfb

Contract

• The API is unchanged: read, parse, find, write, writeFile, utils, and every option of cfb@1.2.2.
• Read results for intact files are identical: FullPaths, every FileIndex field, entry key order, dates, and content bytes. Damaged input differs only as listed under intentional differences below.
• Write results are byte-identical for CFB, ZIP, and ZIP with compression, except for names of 32 or more characters (see below).
• The package keeps the files, entry points, browser field, and type declarations of cfb@1.2.2.
• It has no runtime dependencies. cfb@1.2.2 declared adler-32 and crc-32 but embeds the code it uses.
• It runs on Node.js 0.8 and newer, as cfb@1.2.2 declares; CI exercises 0.8.28 through 24.
• CFB.version reports this package's version, 1.1.0, instead of 1.2.2.

How compatibility is verified

scripts/differential.mjs runs cfb@1.2.2 and this package side by side, each input in its own child process with time and memory limits, and compares every observable result: the read container, find, CFB output, ZIP output with and without compression, the container after each write, and a write-read round trip. With --mutations N it also corrupts each small input N times with a fixed seed.

npm run test:differential -- <corpus-directory>

Each input is reported in one class:

CI runs the harness on the repository fixtures. Results for release 1.1.0, against the SheetJS test corpus (1,284 compound files and 1,674 ZIP containers):

The corruption run:

cfb@1.2.2 also varies from run to run on damaged input: it returns uninitialized memory, and its Huffman tables keep entries from earlier streams. Replayed one at a time against cfb@1.2.2 with zero-filled buffers, the 5 memory cases are identical, and of 20 error-text inputs sampled evenly, 17 are identical, 2 hang in cfb@1.2.2, and 1 decodes about 4 billion bits past the end of its data in cfb@1.2.2 before failing its checksum.

test/fixes.test.cjs covers each intentional difference with a reproduction, and asserts what cfb@1.2.2 does where it finishes.

Intentional differences

console.error reports a truncated name in both versions; the message now names the 31-character result.

Opt-in additions

The type declarations also describe utils.use_zlib, utils._deflateRaw, utils._inflateRaw, and utils.consts, which cfb@1.2.2 exports without types.

See UPSTREAM.md for every upstream issue, pull request, embedded xlsx fix, advisory, and fork.

Upstream issues, pull requests, and forks

Upstream issues, pull requests, and forks

This page maps the original project and everything reported against it to how @stackline/cfb handles each item. It was last reviewed on 2026-10-13.

The rule for every decision: results for existing cfb@1.2.2 code do not change. A fix becomes the default only when cfb@1.2.2 never returns, fails on a valid file, or produces a wrong or invalid result. Everything else is opt-in or declined.

Where the original stands

• npm cfb stops at 1.2.2 (2022-04-06). It is not deprecated.
• SheetJS/js-cfb and its git.sheetjs.com mirror were last updated on 2022-11-10. master is two commits past 1.2.2: a README link change and the 31-character name limit (PR #19), never published.
• SheetJS kept fixing its embedded copy of this code in xlsx (bits/18_cfb.js). Those fixes never reached the cfb package; they are listed below.

Issues (SheetJS/js-cfb)

Pull requests (SheetJS/js-cfb)

Fixes from the copy embedded in xlsx

Security advisories

• No advisory targets the cfb package (GitHub Advisory Database, OSV, and npm audit).
• CVE-2024-22363 (ReDoS) is filed against xlsx; its MIME header expression is present verbatim in cfb@1.2.2 and is fixed here.
• CVE-2023-30533 (prototype pollution) and CVE-2021-32012/32013/32014 are in xlsx workbook parsing, not in this code.

Problems found during this review

Downstream reports in SheetJS/sheetjs about this code

Forks

All 16 GitHub forks of SheetJS/js-cfb were compared with upstream master. Two carry their own code:

isabella232/js-cfb could not be inspected (the API returns 404). The others have no commits of their own.

Release changes

Changelog

1.1.0 - 2026-10-13

A drop-in replacement for cfb@1.2.2. On the SheetJS test corpus every read result is identical, and written bytes differ only where cfb@1.2.2 wrote invalid names. On damaged input this release finishes where cfb@1.2.2 never returns, and it never returns uninitialized memory. See docs/COMPATIBILITY.md and docs/UPSTREAM.md.

Fixed

• A ZIP entry whose DEFLATE stream is shorter than its declared size no longer returns uninitialized process memory in the rest of its content; the rest is zero-filled. cfb@1.2.2 returns that memory when a data descriptor turns the CRC mismatch into a warning, and from utils._inflateRaw with a size.
• inflate no longer loops forever on a DEFLATE stream that ends before its final block, and no longer allocates without bound on a zero-bit code.
• The MIME header regular expression no longer backtracks quadratically (the cfb part of CVE-2024-22363).
• ZIP64 archives are read: end records, central directory and local fields, and 8-byte data descriptors (sheetjs#2766).
• Stored ZIP entries followed by a data descriptor are read, including streamed entries whose local sizes are zero; two encrypted ODS files in the test corpus now open.
• An entry listed before its parent storage keeps its full path (js-cfb#15), and so do the siblings of a stream whose child link points at itself.
• ZIP dates read on the 29th-31st of a month no longer shift by a month.
• Names of 32 or more characters are written as 31 characters, as on upstream master (js-cfb#18). cfb@1.2.2 wrote a 66-byte name length, which read back as a corrupt name and is rejected by strict readers.
• String content is written correctly to ZIP output.
• Directory parent links that loop raise Directory tree cycle at entry N.
• Passing a parsed container to read raises a TypeError that explains the mistake (js-cfb#20).
• CRC tables no longer require Int32Array#subarray.
• CFB.version reports the package version again; 1.0.3 and 1.0.4 reported 1.0.2.
• engines is >=0.8 again, as in cfb@1.2.2; 1.0.x required Node.js 20.19 although the code runs on 0.8.

Added

• CFB.write(cfb, {noseed: true}) writes CFB output without the \u0001Sh33tJ5 seed stream (js-cfb#22).
• Type declarations for noseed, utils.use_zlib, utils._deflateRaw, utils._inflateRaw, and utils.consts.
• scripts/differential.mjs: compares every observable result with cfb@1.2.2 over a corpus, with optional deterministic corruption.
• Regression tests for each fix, a Node.js 0.8-compatible smoke test, and CI jobs for Node.js 0.8.28 through 18.

1.0.4 - 2026-09-28

• Validate documentation badges and synchronize version labels. Published from the 1.0.2 tarball with only the README and package metadata changed.

1.0.3 - 2026-09-28

• Standardize the README, credits, and discovery metadata. Published from the 1.0.2 tarball with only the README and package metadata changed.

1.0.2 - 2026-09-28

• Reuse the verified Stackline crc-32 and uglify-js forks for compatibility validation and the distribution build.

1.0.1 (2026-09-28)

• Standardize package documentation, preserve the API reference and upstream attribution, and add Stackline community links.
• Add focused npm discovery keywords and consistent repository metadata.
• Keep runtime behavior and dependency versions unchanged.
• Correct the pinned artifact-upload action commit while preserving the publish.yml workflow and Prod environment.

1.0.0

• Forked cfb 1.2.2 at ad93f76a36f893362efe96f738a327c290c1f2a9.
• Reject cyclic FAT chains in get_sector_list, covering upstream issue #11.
• Remove unused declared checksum runtime dependencies; keep the embedded code.
• Add bounded child-process regression, browser bundle regression and CFB/ZIP tests.
• Replace legacy development tooling with a portable build and current test tools.

Upstream history

CHANGELOG

This log is intended to keep track of backwards-incompatible changes, including but not limited to API changes and file location changes. Minor behavioral changes may not be included if they are not expected to break existing code.

1.2.1 (2021-09-06)

• CFB write optimizations (h/t @rossj Ross Johnson)
• read in NodeJS will treat Buffer input as type "buffer" by default
• deflate / ZIP support fixed Huffman compression
• inflate more aggressive reallocs

1.2.0 (2020-07-09)

• Support for MAD file format (MIME aggregate document)
• Spun off the CLI tool to the cfb-cli module

1.1.0 (2018-09-04)

• Support for ZIP file format

1.0.6 (2018-04-09)

• lastIndexOf in FAT builder enables larger file parsing at minor cost

1.0.0 (2017-11-05)

• Actually walk mini-fat

0.14.0 (2017-11-04)

• Completely removed FullPathDir

• Adapt the build to the existing UglifyJS 2-compatible Stackline API with named input, ES3/IE8 output, and external source maps; retain the minified-browser regression tests.

Release files and references

• README.md
• CHANGELOG.md
• LICENSE
• Package and publication metadata
• Full text documentation
• Compatibility with cfb 1.2.2
• Upstream issues, pull requests, and forks

Package bytes, npm provenance and the immutable GitHub release were verified for this version. Security checks describe the reviewed release; documented compatibility risks and upstream reports are not blanket claims of resolution.