xlsxrb 0.1.8 → 0.1.9

data/lib/xlsxrb.rb

@@ -22,6 +22,7 @@ require_relative "xlsxrb/version"
 require_relative "xlsxrb/ooxml/zip_generator"
 require_relative "xlsxrb/ooxml/writer"
 require_relative "xlsxrb/ooxml/reader"
+require_relative "xlsxrb/ooxml/crypto"
 require_relative "xlsxrb/ooxml"
 require_relative "xlsxrb/elements"
 require_relative "xlsxrb/stream_row"
@@ -42,6 +43,9 @@ module Xlsxrb
   class ParseError < Error; end
   class ValidationError < Error; end
   class ZipError < Error; end
+  class EncryptedFileError < Error; end
+  class InvalidPasswordError < EncryptedFileError; end
+  class DecryptionError < EncryptedFileError; end
 
   TRACER = OpenTelemetry.tracer_provider.tracer("xlsxrb", Xlsxrb::VERSION)
 
@@ -385,14 +389,48 @@ module Xlsxrb
   #   puts doc_sheet["A1"].value     # coordinate random access
   #
   # @param source [String, IO] File path, binary content string (starting with PK..), or IO object.
+  # @param password [String, nil] Optional password to decrypt password-protected XLSX files.
   # @yield [sheet] Yields each streaming sheet.
   # @yieldparam sheet [StreamSheet] The streaming worksheet object.
   # @return [Elements::Workbook, void] Returns Elements::Workbook when no block is given.
   # @api public
-  #: (String | IO source) { (StreamSheet) -> void } -> void
-  #: (String | IO source) -> Elements::Workbook
-  def self.read(source, &)
-    source = StringIO.new(source) if source.is_a?(String) && (source.start_with?("PK\x03\x04") || source.include?("\x00"))
+  #: (untyped source, ?password: String?) { (StreamSheet) -> void } -> void
+  #: (untyped source, ?password: String?) -> Elements::Workbook
+  def self.read(source, password: nil, &)
+    if source.is_a?(String)
+      if source.start_with?("PK\x03\x04") || source.include?("\x00") || Ooxml::Cfb::Reader.cfb?(source)
+        if Ooxml::Cfb::Reader.cfb?(source)
+          decrypted_zip = Ooxml::Crypto.decrypt(source, password)
+          source = StringIO.new(decrypted_zip)
+        else
+          source = StringIO.new(source)
+        end
+      elsif File.file?(source)
+        first_bytes = begin
+          File.binread(source, 8)
+        rescue StandardError
+          nil
+        end
+        if Ooxml::Cfb::Reader.cfb?(first_bytes)
+          encrypted_data = File.binread(source)
+          decrypted_zip = Ooxml::Crypto.decrypt(encrypted_data, password)
+          source = StringIO.new(decrypted_zip)
+        end
+      end
+    elsif source.respond_to?(:read) && source.respond_to?(:pos) && source.respond_to?(:seek)
+      begin
+        cur_pos = source.pos
+        first_bytes = source.read(8)
+        source.seek(cur_pos)
+        if Ooxml::Cfb::Reader.cfb?(first_bytes)
+          full_data = source.read
+          decrypted_zip = Ooxml::Crypto.decrypt(full_data, password)
+          source = StringIO.new(decrypted_zip)
+        end
+      rescue StandardError
+        # Fall through to standard reader if seeking fails
+      end
+    end
 
     attributes = source.is_a?(String) ? { "filepath" => source } : {}
     Xlsxrb.in_span("Xlsxrb.read", attributes: attributes) do
@@ -431,23 +469,26 @@ module Xlsxrb
 
   # Writes an XLSX file or IO stream (streaming or in-memory), or returns a binary string.
   #
-  # @overload write(target, strict_excel_mode: true, &block)
+  # @overload write(target, password: nil, strict_excel_mode: true, &block)
   #   Streaming write: yields a StreamWriter context for high-speed, zero-allocation XLSX generation.
   #   @param target [String, IO] Destination file path or writable IO object.
+  #   @param password [String, nil] Optional password to encrypt the generated XLSX file.
   #   @param strict_excel_mode [Boolean] Whether to enforce Excel specifications.
   #   @yield [stream_writer]
   #   @yieldparam stream_writer [Xlsxrb::StreamWriter]
   #   @return [void]
   #
-  # @overload write(workbook)
+  # @overload write(workbook, password: nil)
   #   In-memory write: exports the workbook to an in-memory binary String.
   #   @param workbook [Elements::Workbook] The workbook to write.
+  #   @param password [String, nil] Optional password to encrypt the binary string.
   #   @return [String] Binary data representing the XLSX file.
   #
-  # @overload write(target, workbook)
+  # @overload write(target, workbook, password: nil)
   #   In-memory write: writes the workbook to a file path or IO stream.
   #   @param target [String, IO] Destination file path or writable IO object.
   #   @param workbook [Elements::Workbook] The workbook to write.
+  #   @param password [String, nil] Optional password to encrypt the output file.
   #   @return [void]
   #
   # @example Streaming write to file
@@ -455,6 +496,11 @@ module Xlsxrb
   #     writer.sheet("Sheet1") { |s| s.row(["Hello", "World"]) }
   #   end
   #
+  # @example Password-protected streaming write
+  #   Xlsxrb.write("protected.xlsx", password: "secret_password") do |writer|
+  #     writer.sheet("Confidential") { |s| s.row(["Private Data", 100]) }
+  #   end
+  #
   # @example In-memory export to binary string
   #   binary_data = Xlsxrb.write(workbook)
   #
@@ -462,22 +508,41 @@ module Xlsxrb
   #   Xlsxrb.write("output.xlsx", workbook)
   #
   # @api public
-  #: (Elements::Workbook workbook) -> String
-  #: (String | IO target, Elements::Workbook workbook) -> void
-  #: (String | IO target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
-  def self.write(target_or_workbook, workbook_or_nil = nil, strict_excel_mode: true, &block)
+  #: (Elements::Workbook workbook, ?password: String?, ?encryption_mode: Symbol) -> String
+  #: (untyped target, Elements::Workbook | untyped workbook, ?password: String?, ?encryption_mode: Symbol) -> void
+  #: (untyped target_or_workbook, ?Elements::Workbook | untyped workbook_or_nil, ?password: String?, ?encryption_mode: Symbol, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> untyped
+  def self.write(target_or_workbook, workbook_or_nil = nil, password: nil, encryption_mode: :standard, strict_excel_mode: true, &block)
     if block_given?
       target = target_or_workbook
       raise Error, "target is required" if target.nil?
 
       attributes = target.is_a?(String) ? { "filepath" => target } : {}
       return Xlsxrb.in_span("Xlsxrb.write", attributes: attributes) do
-        stream_writer = StreamWriter.new(target, strict_excel_mode: strict_excel_mode)
-        begin
-          yield stream_writer
-          stream_writer.close
-        ensure
-          stream_writer.cleanup!
+        if password && !password.empty?
+          buf = StringIO.new
+          buf.binmode
+          stream_writer = StreamWriter.new(buf, strict_excel_mode: strict_excel_mode)
+          begin
+            yield stream_writer
+            stream_writer.close
+            plain_bytes = buf.string.b
+            encrypted_bytes = Ooxml::Crypto.encrypt(plain_bytes, password, mode: encryption_mode)
+            if target.is_a?(String)
+              File.binwrite(target, encrypted_bytes)
+            elsif target.respond_to?(:write)
+              target.write(encrypted_bytes)
+            end
+          ensure
+            stream_writer.cleanup!
+          end
+        else
+          stream_writer = StreamWriter.new(target, strict_excel_mode: strict_excel_mode)
+          begin
+            yield stream_writer
+            stream_writer.close
+          ensure
+            stream_writer.cleanup!
+          end
         end
       end
     end
@@ -488,7 +553,7 @@ module Xlsxrb
 
       io = StringIO.new
       io.binmode
-      write(io, wb)
+      write(io, wb, password: password, encryption_mode: encryption_mode)
       return io.string.b
     end
 
@@ -532,19 +597,44 @@ module Xlsxrb
 
       # Extract workbook-level facade metadata
       wb_facade = workbook.unmapped_data[:facade] || {}
-      Ooxml::WorkbookWriter.write(
-        target,
-        sheets: sheet_data,
-        shared_strings: sst,
-        shared_strings_index: sst_index,
-        styles: workbook.styles,
-        defined_names: wb_facade[:defined_names],
-        core_properties: wb_facade[:core_properties],
-        app_properties: wb_facade[:app_properties],
-        custom_properties: wb_facade[:custom_properties],
-        workbook_protection: wb_facade[:workbook_protection],
-        workbook_properties: wb_facade[:workbook_properties]
-      )
+
+      if password && !password.empty?
+        buf = StringIO.new
+        buf.binmode
+        Ooxml::WorkbookWriter.write(
+          buf,
+          sheets: sheet_data,
+          shared_strings: sst,
+          shared_strings_index: sst_index,
+          styles: workbook.styles,
+          defined_names: wb_facade[:defined_names],
+          core_properties: wb_facade[:core_properties],
+          app_properties: wb_facade[:app_properties],
+          custom_properties: wb_facade[:custom_properties],
+          workbook_protection: wb_facade[:workbook_protection],
+          workbook_properties: wb_facade[:workbook_properties]
+        )
+        encrypted_bytes = Ooxml::Crypto.encrypt(buf.string.b, password, mode: encryption_mode)
+        if target.is_a?(String)
+          File.binwrite(target, encrypted_bytes)
+        elsif target.respond_to?(:write)
+          target.write(encrypted_bytes)
+        end
+      else
+        Ooxml::WorkbookWriter.write(
+          target,
+          sheets: sheet_data,
+          shared_strings: sst,
+          shared_strings_index: sst_index,
+          styles: workbook.styles,
+          defined_names: wb_facade[:defined_names],
+          core_properties: wb_facade[:core_properties],
+          app_properties: wb_facade[:app_properties],
+          custom_properties: wb_facade[:custom_properties],
+          workbook_protection: wb_facade[:workbook_protection],
+          workbook_properties: wb_facade[:workbook_properties]
+        )
+      end
     end
   end
 
@@ -563,22 +653,23 @@ module Xlsxrb
   #
   # @param source [String, IO] The source file path or IO object.
   # @param target [String, IO, nil] The target file path or IO object. If nil, overwrites source.
+  # @param password [String, nil] Optional password for reading and writing protected files.
   # @yield [workbook] Yields the parsed workbook.
   # @yieldparam workbook [Elements::Workbook] The parsed workbook.
   # @yieldreturn [Elements::Workbook] The modified workbook.
   # @return [void]
   # @api public
-  #: (untyped source, ?untyped target) ?{ (Elements::Workbook) -> untyped } -> void
-  def self.modify(source, target = nil)
+  #: (untyped source, ?untyped target, ?password: String?) ?{ (Elements::Workbook) -> untyped } -> void
+  def self.modify(source, target = nil, password: nil)
     raise Error, "source is required" if source.nil?
     raise Error, "block is required" unless block_given?
 
-    workbook = read(source).load
+    workbook = read(source, password: password).load
     result_workbook = yield workbook
     result_workbook = workbook unless result_workbook.is_a?(Elements::Workbook)
 
     write_target = target || source
-    write(write_target, result_workbook)
+    write(write_target, result_workbook, password: password)
   end
 
   # Represents a sheet being streamed sequentially from an XLSX file.
@@ -627,7 +718,7 @@ module Xlsxrb
     # @return [Enumerator, void]
     # @api public
     #: () { (StreamRow | Elements::Row) -> void } -> void
-    #: | () -> Enumerator[StreamRow | Elements::Row, void]
+    #: () -> Enumerator[StreamRow | Elements::Row, void]
     def each_row
       return enum_for(:each_row) unless block_given?
 
@@ -647,7 +738,7 @@ module Xlsxrb
     # @return [Enumerator, void]
     # @api public
     #: () { (Elements::Cell) -> void } -> void
-    #: | () -> Enumerator[Elements::Cell, void]
+    #: () -> Enumerator[Elements::Cell, void]
     def each_cell(&)
       return enum_for(:each_cell) unless block_given?
 
@@ -663,7 +754,7 @@ module Xlsxrb
     # @return [Enumerator, void]
     # @api public
     #: () { (StreamRow | Elements::Row) -> void } -> void
-    #: | () -> Enumerator[StreamRow | Elements::Row, void]
+    #: () -> Enumerator[StreamRow | Elements::Row, void]
     def each(&)
       each_row(&)
     end

data/sig/generated/xlsxrb/elements/worksheet.rbs

@@ -31,8 +31,8 @@ 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
-      def initialize: (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: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
 
       # Iterate over rows in the worksheet.
       #
@@ -46,8 +46,9 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       # : () { (Elements::Row) -> void } -> void
-      # : | () -> Enumerator[Elements::Row, void]
+      # : () -> Enumerator[Elements::Row, void]
       def each: () { (Elements::Row) -> void } -> void
+              | () -> Enumerator[Elements::Row, void]
 
       # Iterate over rows in the worksheet.
       #
@@ -61,8 +62,9 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       # : () { (Elements::Row) -> void } -> void
-      # : | () -> Enumerator[Elements::Row, void]
+      # : () -> Enumerator[Elements::Row, void]
       def each_row: () { (Elements::Row) -> void } -> void
+                  | () -> Enumerator[Elements::Row, void]
 
       # Iterate over all cells across rows.
       #
@@ -71,8 +73,9 @@ module Xlsxrb
       # @return [Enumerator, void]
       # @api public
       # : () { (Elements::Cell) -> void } -> void
-      # : | () -> Enumerator[Elements::Cell, void]
+      # : () -> Enumerator[Elements::Cell, void]
       def each_cell: () { (Elements::Cell) -> void } -> void
+                   | () -> Enumerator[Elements::Cell, void]
 
       # Returns whether the worksheet is valid according to OOXML specifications.
       #

data/sig/generated/xlsxrb/ooxml/cfb.rbs

@@ -0,0 +1,121 @@
+# Generated from lib/xlsxrb/ooxml/cfb.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    # Pure-Ruby Compound File Binary (CFB / OLE Structured Storage) implementation for [MS-CFB] / [MS-OFFCRYPTO].
+    module Cfb
+      MAGIC: untyped
+
+      FREESECT: ::Integer
+
+      ENDOFCHAIN: ::Integer
+
+      FATSECT: ::Integer
+
+      DIFATSECT: ::Integer
+
+      NOSTREAM: ::Integer
+
+      OBJ_UNKNOWN: ::Integer
+
+      OBJ_STORAGE: ::Integer
+
+      OBJ_STREAM: ::Integer
+
+      OBJ_ROOT: ::Integer
+
+      MINI_STREAM_CUTOFF: ::Integer
+
+      SECTOR_SIZE: ::Integer
+
+      MINI_SECTOR_SIZE: ::Integer
+
+      # Represents a directory entry in a Compound File.
+      class DirEntry
+        attr_accessor name: untyped
+
+        attr_accessor type: untyped
+
+        attr_accessor color: untyped
+
+        attr_accessor left_sibling_id: untyped
+
+        attr_accessor right_sibling_id: untyped
+
+        attr_accessor child_id: untyped
+
+        attr_accessor clsid: untyped
+
+        attr_accessor state_flags: untyped
+
+        attr_accessor created_time: untyped
+
+        attr_accessor modified_time: untyped
+
+        attr_accessor start_sector: untyped
+
+        attr_accessor size: untyped
+
+        attr_accessor entry_id: untyped
+
+        def initialize: (?name: untyped, ?type: untyped, ?start_sector: untyped, ?size: untyped) -> untyped
+
+        def stream?: () -> untyped
+
+        def root?: () -> untyped
+
+        def storage?: () -> untyped
+      end
+
+      # Reads streams from a Compound File Binary buffer.
+      class Reader
+        attr_reader entries: untyped
+
+        def self.cfb?: (untyped data) -> untyped
+
+        def initialize: (untyped data) -> untyped
+
+        def stream_names: () -> untyped
+
+        def read_stream: (untyped name) -> untyped
+
+        private
+
+        def parse_header: () -> untyped
+
+        def sector_offset: (untyped sector_id) -> untyped
+
+        def read_sector: (untyped sector_id) -> untyped
+
+        def build_fat: () -> untyped
+
+        def load_difat_and_fat: () -> untyped
+
+        def parse_directory: () -> untyped
+
+        def load_mini_stream: () -> untyped
+
+        def read_regular_stream_data: (untyped start_sector, untyped total_size) -> untyped
+
+        def read_mini_stream_data: (untyped start_mini_sector, untyped total_size) -> untyped
+      end
+
+      # Writes named streams into a Compound File Binary (v3, 512-byte sectors) format with Mini Stream support.
+      class Writer
+        def self.write: (untyped streams) -> untyped
+
+        def initialize: (untyped streams) -> untyped
+
+        def build: () -> untyped
+
+        private
+
+        def serialize_dir_entry: (untyped entry) -> untyped
+
+        def insert_entry_to_tree: (untyped entries, untyped root_node, untyped new_node) -> untyped
+
+        def compare_entry_names: (untyped a_name, untyped b_name) -> untyped
+      end
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/crypto/agile.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/xlsxrb/ooxml/crypto/agile.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    module Crypto
+      # Implements Microsoft Office Agile Encryption specified in [MS-OFFCRYPTO] Section 2.3.4.
+      class Agile
+        BLOCK_KEY_VERIFIER_INPUT: untyped
+
+        BLOCK_KEY_VERIFIER_VALUE: untyped
+
+        BLOCK_KEY_KEY: untyped
+
+        BLOCK_KEY_INTEGRITY_KEY: untyped
+
+        BLOCK_KEY_INTEGRITY_VALUE: untyped
+
+        SEGMENT_SIZE: ::Integer
+
+        # Decrypts an encrypted package given the EncryptionInfo stream data and EncryptedPackage stream data.
+        def self.decrypt: (untyped encryption_info_bytes, untyped encrypted_package_bytes, untyped password) -> untyped
+
+        # Encrypts a plain zip payload with the given password into EncryptionInfo and EncryptedPackage streams.
+        def self.encrypt: (untyped plain_bytes, untyped password) -> untyped
+
+        private def self.parse_encryption_info: (untyped bytes) -> untyped
+
+        private def self.digest_for: (untyped name) -> untyped
+
+        private def self.cipher_name_for: (untyped algo, untyped key_bits) -> untyped
+
+        private def self.derive_h_final: (untyped digest, untyped password, untyped salt, untyped spin_count) -> untyped
+
+        private def self.derive_key: (untyped digest, untyped h_final, untyped block_key, untyped key_bytes) -> untyped
+
+        private def self.aes_decrypt: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+
+        private def self.aes_encrypt: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+
+        private def self.aes_decrypt_block: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+
+        private def self.aes_encrypt_block: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+      end
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/crypto/standard.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/xlsxrb/ooxml/crypto/standard.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    module Crypto
+      # Implements Microsoft Office Standard Encryption specified in [MS-OFFCRYPTO] Section 2.3.6.
+      class Standard
+        CSP_NAME: untyped
+
+        ITERATION_COUNT: ::Integer
+
+        # Decrypts a Standard-encrypted package.
+        def self.decrypt: (untyped encryption_info_bytes, untyped encrypted_package_bytes, untyped password) -> untyped
+
+        # Encrypts plain zip data into Standard Encryption streams.
+        def self.encrypt: (untyped plain_bytes, untyped password) -> untyped
+
+        private def self.parse_encryption_info: (untyped bytes) -> untyped
+
+        private def self.derive_key: (untyped password, untyped salt, ?untyped block_num) -> untyped
+
+        private def self.aes_ecb_encrypt: (untyped key, untyped data) -> untyped
+
+        private def self.aes_ecb_decrypt: (untyped key, untyped data) -> untyped
+      end
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/crypto.rbs

@@ -0,0 +1,17 @@
+# Generated from lib/xlsxrb/ooxml/crypto.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    # High-level encryption and decryption facade for [MS-OFFCRYPTO] Excel document protection.
+    module Crypto
+      # Checks if the binary data is an encrypted Compound File Binary package.
+      def self.encrypted?: (untyped data) -> untyped
+
+      # Decrypts an encrypted XLSX (CFB) package with the given password.
+      def self.decrypt: (untyped cfb_data, untyped password) -> untyped
+
+      # Encrypts a plain ZIP payload with the given password into an encrypted CFB package.
+      def self.encrypt: (untyped plain_zip_data, untyped password, ?mode: untyped) -> untyped
+    end
+  end
+end

data/sig/generated/xlsxrb/stream_row.rbs

@@ -44,8 +44,9 @@ module Xlsxrb
     # @return [Enumerator, void]
     # @api public
     # : () { (Elements::Cell) -> void } -> void
-    # : | () -> Enumerator[Elements::Cell, void]
+    # : () -> Enumerator[Elements::Cell, void]
     def each_cell: () { (Elements::Cell) -> void } -> void
+                 | () -> Enumerator[Elements::Cell, void]
 
     # Iterate over cells in this streaming row.
     #
@@ -54,8 +55,9 @@ module Xlsxrb
     # @return [Enumerator, void]
     # @api public
     # : () { (Elements::Cell) -> void } -> void
-    # : | () -> Enumerator[Elements::Cell, void]
+    # : () -> Enumerator[Elements::Cell, void]
     def each: () { (Elements::Cell) -> void } -> void
+            | () -> Enumerator[Elements::Cell, void]
 
     # Returns all cells as an Array. Cached on first access.
     #