xlsxrb 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1be4d5d307820e8ed44e46d2a990e069501f413cace5e4920f61c6c43f964ff
-  data.tar.gz: 22df70618c1f06ccc7bdcd3e4a1d0529bc6385f122f9563e29370ef13e16dcf1
+  metadata.gz: 9930be8e04f9dee4e380c4789398da0b6a95b0c54d2a157265a2d1ee14340132
+  data.tar.gz: '086f0abccab70ef69d1e885b9f8d0ec69a77e81e3067fa718764c24c0f37a13f'
 SHA512:
-  metadata.gz: 80cd57b81f5649d930e873b354f2b587a05c19557ff2906ffc85aadd630d38db5487ba1bfda4a4588658c2902343658aac09c3cfbd59e3550d35be45187ae80d
-  data.tar.gz: 474385c247bed4e3b35182f7e3ecb4949d2eb5fa4adaea91b221179103cc1dc278ccd041b50cffd3dd3c3e31572e29e816f7a03ac99580f30096d0cebdd18290
+  metadata.gz: 2097ccb3e8b3e5344e5d55c459db6b06c298b116074bcc41a06fafa034eda67bf0c46d7eaa58184aebc970812cfa91f68388c4a6b4e7d7069a45114507aa9e83
+  data.tar.gz: d95b39449b15b2eec1415d1ae65e398cc2c006adefd19b54340727fc4ee2135322040a73bf0b3d2b0ca8f6d171153e88b8f64badb53b7fb841e9d7b8a87afd55

data/CHANGELOG.md

@@ -1,5 +1,18 @@
-## [Unreleased]
-- No unreleased changes.
+## [0.1.9] - 2026-08-18
+
+### Added
+- **Password Protection & Document Encryption ([MS-OFFCRYPTO] / [MS-CFB])**: Full native Pure-Ruby support for reading, writing, and modifying password-protected Excel spreadsheets without any external C-extension dependencies.
+  - **Standard Encryption**: AES-128-ECB and SHA-1 Key Derivation with CryptoAPI 50,000-spin hashing, fully interoperable across Microsoft Excel, LibreOffice, and Google Sheets.
+  - **Agile Encryption**: Modern AES-256-CBC, PBKDF2/SHA-512, and HMAC-SHA512 data integrity verification.
+  - **Compound File Binary (CFB) Engine**: Pure-Ruby reader and writer for OLE structured storage containers with Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory management.
+  - **Transparent Public API Integration**: Added `password:` and `encryption_mode:` arguments to `Xlsxrb.read`, `Xlsxrb.write`, and `Xlsxrb.modify`.
+  - **Security & Threat Model Hardening**:
+    - Constant-time hash verification via `OpenSSL.secure_compare` to prevent timing attacks (CWE-208).
+    - CSPRNG-backed salt, IV, and session key generation via `SecureRandom` (CWE-330).
+    - Robust DoS defense: spinCount limit ($\le 10\text{M}$), CFB circular sector chain loop detection in directory/FAT parsing, and `total_size` bounds validation (CWE-400, CWE-835).
+    - Strict exception hierarchy (`EncryptedFileError`, `InvalidPasswordError`, `DecryptionError`).
+  - **Cross-Platform & Interoperability Validation**: Bidirectional validation with Microsoft .NET OpenXML SDK and LibreOffice Calc.
+  - **WebAssembly (ruby.wasm) Support**: Pre-packaged `docs/wasm/ruby.wasm` updated with document encryption support for browser playground.
 
 ## [0.1.8] - 2026-08-18
 

data/README.md

@@ -6,18 +6,18 @@ A Ruby library for reading and writing XLSX files with streaming support.
 
 The Ruby ecosystem already has great XLSX libraries. Each is well-designed for its purpose:
 
-| Library                                                    | Read | Write | Model                 | Write String Storage | Rich Formatting |
-| ---------------------------------------------------------- | ---- | ----- | --------------------- | -------------------- | --------------- |
-| [roo](https://rubygems.org/gems/roo)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ⚠️ (Formulas, Basic styles) |
-| [creek](https://rubygems.org/gems/creek)                   | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Raw cell values) |
-| [xsv](https://rubygems.org/gems/xsv)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Fast plain text) |
-| [simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader) | ✅ | ❌ | Streaming         | N/A (Read-only)      | ❌ (Plain data & types) |
-| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx)         | ❌   | ✅    | In-Memory             | Inline (opt: SST)    | ✅ (Charts, Styles) |
-| [write_xlsx](https://rubygems.org/gems/write_xlsx)         | ❌   | ✅    | In-Memory             | SST                  | ✅ (Charts, Styles) |
-| [xlsxtream](https://rubygems.org/gems/xlsxtream)           | ❌   | ✅    | Streaming             | Inline (opt: SST)    | ❌ (Plain data only) |
-| [fast_excel](https://rubygems.org/gems/fast_excel)         | ❌   | ✅    | Streaming (C Ext)     | SST (opt: Inline)    | ⚠️ (Basic styles) |
-| [rubyXL](https://rubygems.org/gems/rubyXL)                 | ✅   | ✅    | In-Memory             | Inline / Direct      | ✅ (DOM editing) |
-| **[xlsxrb](https://github.com/niku/xlsxrb)**               | ✅   | ✅    | **Streaming / In-Memory** | **SST**          | ✅ **(Full Features)** |
+| Library                                                    | Read | Write | Model                 | Write String Storage | Rich Formatting | Password Encryption |
+| ---------------------------------------------------------- | ---- | ----- | --------------------- | -------------------- | --------------- | :-----------------: |
+| [roo](https://rubygems.org/gems/roo)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ⚠️ (Formulas, Basic styles) | ❌ |
+| [creek](https://rubygems.org/gems/creek)                   | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Raw cell values) | ❌ |
+| [xsv](https://rubygems.org/gems/xsv)                       | ✅   | ❌    | Streaming             | N/A (Read-only)      | ❌ (Fast plain text) | ❌ |
+| [simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader) | ✅ | ❌ | Streaming         | N/A (Read-only)      | ❌ (Plain data & types) | ❌ |
+| [caxlsx / axlsx](https://rubygems.org/gems/caxlsx)         | ❌   | ✅    | In-Memory             | Inline (opt: SST)    | ✅ (Charts, Styles) | ❌ |
+| [write_xlsx](https://rubygems.org/gems/write_xlsx)         | ❌   | ✅    | In-Memory             | SST                  | ✅ (Charts, Styles) | ❌ |
+| [xlsxtream](https://rubygems.org/gems/xlsxtream)           | ❌   | ✅    | Streaming             | Inline (opt: SST)    | ❌ (Plain data only) | ❌ |
+| [fast_excel](https://rubygems.org/gems/fast_excel)         | ❌   | ✅    | Streaming (C Ext)     | SST (opt: Inline)    | ⚠️ (Basic styles) | ❌ |
+| [rubyXL](https://rubygems.org/gems/rubyXL)                 | ✅   | ✅    | In-Memory             | Inline / Direct      | ✅ (DOM editing) | ❌ |
+| **[xlsxrb](https://github.com/niku/xlsxrb)**               | ✅   | ✅    | **Streaming / In-Memory** | **SST**          | ✅ **(Full Features)** | ✅ **(Standard & Agile)** |
 
 Each of these libraries makes deliberate tradeoffs, and they do so thoughtfully:
 * **Memory & Execution Model (Streaming vs In-Memory)**: Streaming libraries write or read rows sequentially on-the-fly to maintain a constant, low-memory footprint regardless of row count. In-memory libraries build complete document object trees, offering flexible random access and cell updates at the cost of high RAM usage on large sheets.
@@ -197,6 +197,43 @@ Xlsxrb.build do |builder|
 end
 ```
 
+### Password Protection & Document Encryption ([MS-OFFCRYPTO])
+
+`xlsxrb` natively supports reading and writing password-protected Excel files with zero external C-extension dependencies, fully compliant with **[MS-OFFCRYPTO]** (Standard Encryption & Agile Encryption) and **[MS-CFB]** (Compound File Binary Format):
+
+#### Writing Password-Protected Spreadsheets
+```ruby
+# 1. Streaming write with password protection
+Xlsxrb.write("confidential.xlsx", password: "SecretPassword123") do |writer|
+  writer.sheet("Financials") do |sheet|
+    sheet.row(["Account", "Balance"])
+    sheet.row(["Assets", 5_000_000])
+  end
+end
+
+# 2. In-Memory write with password protection
+wb = Xlsxrb.build do |b|
+  b.sheet("Private") { |s| s.row(["Confidential", 100]) }
+end
+encrypted_binary = Xlsxrb.write(wb, password: "SecretPassword123")
+```
+
+#### Reading Password-Protected Spreadsheets
+```ruby
+# 1. Read directly with password (O(1) constant memory streaming)
+Xlsxrb.read("confidential.xlsx", password: "SecretPassword123") do |sheet|
+  sheet.each_row { |row| puts row.cells.map(&:value) }
+end
+
+# 2. In-Memory load with password
+workbook = Xlsxrb.read("confidential.xlsx", password: "SecretPassword123").load
+puts workbook.sheets.first["A1"].value
+
+# Attempting to read without password or with invalid password raises clear exceptions:
+# Xlsxrb::EncryptedFileError   -> Missing password
+# Xlsxrb::InvalidPasswordError -> Incorrect password
+```
+
 ### IDE Autocompletion & Ruby LSP Support
 
 `xlsxrb` bundles a native **Ruby LSP Add-on** (`RubyLsp::Xlsxrb::Addon`) and full **RBS signatures**, enabling zero-configuration method autocompletion and rich Markdown documentation in VS Code and other LSP-enabled editors.
@@ -299,7 +336,7 @@ To support reliability, compliance with the ECMA-376 specification, and consiste
 * **Visual Regression Testing (VRT)**: Spreadsheets are rendered via a headless LibreOffice Calc engine and compared pixel-by-pixel against visual baselines to catch subtle rendering regressions.
 
 ### Performance & Types
-* **Continuous Benchmarking**: Memory usage and processing speeds are profiled in CI on large datasets to prevent performance regressions and OOM leaks.
+* **Continuous Performance & Memory Validation**: Memory retention and processing throughput are profiled in CI on large datasets to prevent regressions and OOM leaks.
 * **Runtime Type Validation**: Strong dynamic typing using `RBS::Test` to ensure the library's types are perfectly sound at runtime.
 
 For a comprehensive breakdown of our QA matrix, see [docs/QUALITY_ASSURANCE.md](docs/QUALITY_ASSURANCE.md). For details on running tests locally, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

data/Rakefile

@@ -93,8 +93,8 @@ end
 Rake::TestTask.new(test: :ensure_reader_fixtures) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-  workers = ENV.fetch("TEST_WORKERS", Etc.nprocessors)
+  t.test_files = FileList["test/xlsxrb/**/*_test.rb", "test/*_test.rb", "test/contract/**/*_test.rb"]
+  workers = ENV.fetch("TEST_WORKERS", [Etc.nprocessors, 4].min)
   t.options = "--parallel --n-workers=#{workers}"
 end
 
@@ -121,6 +121,24 @@ namespace :test do
     t.options = "--parallel --n-workers=#{workers}"
   end
 
+  desc "Run property-based tests (PBT)"
+  Rake::TestTask.new(:pbt) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/pbt/**/*_test.rb"]
+    workers = ENV.fetch("TEST_WORKERS", Etc.nprocessors)
+    t.options = "--parallel --n-workers=#{workers}"
+  end
+
+  desc "Run memory and performance tests"
+  Rake::TestTask.new(:performance) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/performance/**/*_test.rb"]
+  end
+  desc "Alias for test:performance"
+  task perf: :performance
+
   Rake::TestTask.new(:e2e) do |t|
     t.libs << "test"
     t.libs << "lib"

data/docs/DEVELOPMENT.md

@@ -14,17 +14,25 @@ To run the different tiers of our testing strategy:
    ```bash
    bundle exec rake test:contract
    ```
-3. **Interoperability (E2E) Tests:**
+3. **Property-Based Tests (PBT):**
+   ```bash
+   bundle exec rake test:pbt
+   ```
+4. **Memory & Performance Tests:**
+   ```bash
+   bundle exec rake test:perf
+   ```
+5. **Interoperability (E2E) Tests:**
    Requires .NET SDK to be installed (pre-configured in Dev Container).
    ```bash
    bundle exec rake test:e2e
    ```
-4. **Visual Regression Tests (VRT):**
+6. **Visual Regression Tests (VRT):**
    Requires LibreOffice, ImageMagick, and `poppler-utils`.
    ```bash
    bundle exec rake test:visual
    ```
-5. **Run All Tests:**
+7. **Run All Tests:**
    ```bash
    bundle exec rake test
    ```

data/docs/QUALITY_ASSURANCE.md

@@ -14,13 +14,12 @@ Below is an overview of the inspection mechanisms, when they run, the quality at
 | **Dependabot** | `.github/dependabot.yml` | - | - | ⭕ | Currency / Maintenance | Repository Monitoring | Outdated dependencies or CI actions. |
 | **Unit & Contract Tests** | `rake test:unit test:contract` | ⭕ | ⭕ | - | Accuracy / Functional Reqs | Dynamic Analysis (Assertions) | Method specification violations, unexpected return values, edge-case failures. |
 | **Runtime Type Validation (RBS::Test)** | `rake test:rbs` | △ (Opt-in) | ⭕ | - | Type Safety (Dynamic) | Dynamic Analysis (Runtime Hooks) | Type errors slipping past static checks, divergence between RBS docs and implementation. |
-| **Property-Based Testing (PBT)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
-
+| **Property-Based Testing (PBT)** | `rake test:pbt` | ⭕ | ⭕ | - | Robustness / Exhaustiveness | Automated Random Generation | Crashes caused by "unexpected inputs" (e.g., empty strings, huge numbers, special symbols like `=`). |
 | **Security Validation (DoS Protection)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Availability / Safety | Dynamic Analysis (Malicious Input) | Memory/disk exhaustion from ZIP bombs, infinite parsing loops from malformed files. |
 | **Concurrency Validation (Thread/Ractor)** | Included in `rake test:unit` | ⭕ | ⭕ | - | Thread Safety | Dynamic Analysis (Parallel Execution) | Global variable pollution, data mixing during concurrent request processing. |
 | **XSD Schema Validation** | Included in `rake test:unit` | ⭕ | ⭕ | - | Compatibility / Compliance | Structural Validation | "We found a problem with some content in it" errors when opening in Excel. |
 | **E2E Interoperability Tests** | `rake test:e2e` | △ (Opt-in) | ⭕ | - | Compatibility (Real-world) | 3rd-party SDK Execution | Structural defects so severe that the official .NET SDK cannot read them. |
-| **Load / Stress Testing** | Action: `benchmark.yml` | - | ⭕ | - | Performance / Stability | Massive Data Generation (e.g., 10k+ rows) | Out of Memory (OOM) crashes or extreme delays when processing large datasets. |
-| **Memory & Speed Benchmark** | Action: `benchmark.yml` | - | ⭕ | - | Performance | Continuous Profiling | Memory leaks, severe performance degradation due to inefficient loop additions. |
+| **Memory & Performance Tests** | `rake test:perf` / Action: `performance.yml` | ⭕ | ⭕ | - | Performance / Stability | Continuous Profiling (10k+ rows) | Out of Memory (OOM) leaks or unbounded memory retention in streaming mode. |
+| **Ecosystem Benchmarks** | `ruby benchmark.rb` | ⭕ | - | - | Performance Comparison | Multi-Gem Isolated Profiling (1M cells) | Throughput and allocation comparison against competing libraries. |
 | **Visual Regression Testing (VRT)** | `rake test:visual` | - | ⭕ | - | Visual Accuracy (UI/UX) | Headless Rendering / Pixel Diff | Visual bugs like "cell background colors dropping" or "chart layouts breaking" after code changes. |
 

data/docs/SPEC_SOURCES.md

@@ -22,8 +22,11 @@ To address gaps between the official ECMA standard and actual implementations in
    - **Role:** Identifies how Excel actually reads/writes files, including deviations and compatibility behaviors.
    - **Referenced Version:** July 2024 / Version 12.0 (or current release).
 3. **[[MS-OFFCRYPTO]: Office Document Cryptography Structure](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-offcrypto/)**
-   - **Role:** Provides details on encryption, passwords, and hashing algorithms used for document/sheet protection.
+   - **Role:** Provides details on encryption, passwords, and hashing algorithms used for document/sheet protection (Agile Encryption and Standard Encryption).
    - **Referenced Version:** July 2024 / Version 12.0 (or current release).
+4. **[[MS-CFB]: Compound File Binary File Format](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb/)**
+   - **Role:** Container format (OLE structured storage) wrapping encrypted Office documents (`EncryptionInfo` and `EncryptedPackage` streams).
+   - **Referenced Version:** July 2024 / Version 14.0 (or current release).
 
 ### ISO/IEC 29500 Note
 ISO/IEC 29500 is contents-wise equivalent to ECMA-376. However, ISO/IEC 29500 requires paid purchase in general, whereas ECMA-376 is freely available. Therefore, we primarily cite ECMA-376 sections.
@@ -40,3 +43,6 @@ When implementing features or fixing bugs that depend on specific behaviors defi
 | Shared Strings | ECMA-376 Part 1 | §18.4 (Shared String Table) | Handling of `<sst>` and `<si>` for cell value reuse |
 | Styles & Formatting | ECMA-376 Part 1 | §18.8 (Styles) | Cell style XF indexes, font, fill, border mappings |
 | Hyperlinks | ECMA-376 Part 1 | §18.3.1.48 (hyperlink) | Worksheet hyperlinks referencing external URLs or internal targets |
+| Document Encryption (Agile) | [MS-OFFCRYPTO] | §2.3.4 (Agile Encryption) | AES-256-CBC, PBKDF2/SHA-512, HMAC-SHA512 data integrity |
+| Document Encryption (Standard) | [MS-OFFCRYPTO] | §2.3.6 (Standard Encryption) | AES-128-ECB, SHA-1 with CryptoAPI 50,000-spin key derivation |
+| Encryption Container | [MS-CFB] | §2 (Compound File Structure) | Mini Stream, FAT/MiniFAT sectors, and Red-Black tree directory |

data/lib/xlsxrb/elements/row.rb

@@ -75,7 +75,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Cell) -> void } -> void
-      #: | () -> Enumerator[Elements::Cell, void]
+      #: () -> Enumerator[Elements::Cell, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
@@ -94,7 +94,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Cell) -> void } -> void
-      #: | () -> Enumerator[Elements::Cell, void]
+      #: () -> Enumerator[Elements::Cell, void]
       def each_cell(&)
         return to_enum(:each_cell) unless block_given?
 

data/lib/xlsxrb/elements/workbook.rb

@@ -38,7 +38,7 @@ module Xlsxrb
       # @yieldparam sheet [Elements::Worksheet]
       # @return [Enumerator, void]
       #: () { (Elements::Worksheet) -> void } -> void
-      #: | () -> Enumerator[Elements::Worksheet, void]
+      #: () -> Enumerator[Elements::Worksheet, void]
       def each(&)
         sheets.each(&)
       end

data/lib/xlsxrb/elements/worksheet.rb

@@ -25,7 +25,7 @@ module Xlsxrb
       # @param charts [Array<Hash>] Charts in the sheet.
       # @param unmapped_data [Hash] Additional metadata for round-tripping.
       # @param errors [Array<String>, nil] Validation errors.
-      #: (name: String, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      #: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       def initialize(name:, rows: [], columns: [], charts: [], unmapped_data: {}, errors: nil)
         @name = name
         @rows = (rows || []).freeze
@@ -48,7 +48,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Row) -> void } -> void
-      #: | () -> Enumerator[Elements::Row, void]
+      #: () -> Enumerator[Elements::Row, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
@@ -67,7 +67,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Row) -> void } -> void
-      #: | () -> Enumerator[Elements::Row, void]
+      #: () -> Enumerator[Elements::Row, void]
       def each_row(&)
         return to_enum(:each_row) unless block_given?
 
@@ -81,7 +81,7 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       #: () { (Elements::Cell) -> void } -> void
-      #: | () -> Enumerator[Elements::Cell, void]
+      #: () -> Enumerator[Elements::Cell, void]
       def each_cell(&)
         return to_enum(:each_cell) unless block_given?