ooxml-encryption

A compact, dependency-free TypeScript library for decrypting and encrypting password-protected OOXML workbooks (.xlsx, .xlsm).

Use it to unlock a password-protected spreadsheet when you know the password, or to add password protection to a workbook.

Features

• Decrypt modern, Agile-encrypted .xlsx / .xlsm files with their password.
• Encrypt a plain workbook with a password (AES-256, SHA-512, 100,000-round key derivation — matching modern Office defaults).
• Byte-preserving. A decrypt → encrypt round-trip keeps the workbook bytes intact, so .xlsm VBA projects survive unchanged.
• Zero runtime dependencies. Built entirely on the standard WebCrypto API (globalThis.crypto.subtle).
• Cross-platform. Runs in Node 20+ and modern browsers.
• Typed, ESM-first, with full TypeScript declarations.

Install

pnpm add ooxml-encryption
# or: npm install ooxml-encryption
# or: yarn add ooxml-encryption

Quick start

import { readFile, writeFile } from "node:fs/promises";
import { decryptWorkbook, encryptWorkbook } from "ooxml-encryption";

const encrypted = new Uint8Array(await readFile("protected.xlsx"));

// Unlock with the current password.
const workbook = await decryptWorkbook(encrypted, "current-password");
await writeFile("unlocked.xlsx", workbook);

// Re-protect a workbook with a new password.
const reprotected = await encryptWorkbook(workbook, "new-password");
await writeFile("protected-new.xlsx", reprotected);

• decryptWorkbook returns the decrypted OOXML package — ordinary .xlsx ZIP bytes you can write straight to disk.
• encryptWorkbook takes those package bytes and returns an encrypted file ready to be opened in Excel with the password.

Both functions accept and return Uint8Array, so the same code runs in the browser (e.g. against bytes from a File or fetch).

Handling wrong passwords

Passwords are case-sensitive. When the password is incorrect, decryptWorkbook throws an OoxmlEncryptionError with code "invalidPassword":

import { decryptWorkbook, OoxmlEncryptionError } from "ooxml-encryption";

try {
  const workbook = await decryptWorkbook(encrypted, userInput);
  // ...use workbook
} catch (error) {
  if (error instanceof OoxmlEncryptionError && error.code === "invalidPassword") {
    console.error("Wrong password.");
  } else {
    throw error;
  }
}

Reading Sheet!A1

readCellA1 reads a single cell from decrypted workbook bytes without a full spreadsheet parser. It resolves shared strings, inline strings, and cached formula strings. Because worksheet parts are usually deflated inside the ZIP, you supply an inflateRaw function from your platform.

Node:

import { promisify } from "node:util";
import { inflateRaw } from "node:zlib";
import { readCellA1 } from "ooxml-encryption";

const inflateRawAsync = promisify(inflateRaw);

const value = await readCellA1(decryptedWorkbook, {
  inflateRaw: async (deflated) => new Uint8Array(await inflateRawAsync(deflated)),
});

Browser:

import { readCellA1 } from "ooxml-encryption";

const value = await readCellA1(decryptedWorkbook, {
  sheetName: "Sheet1", // optional; defaults to the first worksheet
  inflateRaw: async (deflated) => {
    const stream = new DecompressionStream("deflate-raw");
    const writer = stream.writable.getWriter();
    void writer.write(deflated);
    void writer.close();
    return new Uint8Array(await new Response(stream.readable).arrayBuffer());
  },
});

Scope and limitations

Supported: modern Agile-encrypted .xlsx and .xlsm files (AES in CBC mode, with SHA-1/256/384/512 and 128/192/256-bit keys). Encryption output is always AES-256 + SHA-512.

Not supported: legacy .xls, OOXML Standard (binary) encryption, IRM-protected or sensitivity-label-protected files, and certificate-based key encryptors. Attempting these raises an OoxmlEncryptionError with an unsupported* code rather than producing incorrect output.

API

See API.md for the full reference. At a glance:

| Export | Description | | --- | --- | | decryptWorkbook(bytes, password) | Decrypt an encrypted workbook to OOXML package bytes. | | encryptWorkbook(bytes, password) | Encrypt OOXML package bytes with a password. | | readCellA1(bytes, options?) | Read Sheet!A1 from decrypted package bytes. | | OoxmlEncryptionError | Error thrown for all failures, with a typed code. |

License

MIT © Boram Uyar