omnizip 0.4.7-aarch64-linux

data/lib/omnizip/algorithms/lzma/lzip_decoder.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+require "stringio"
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      #
+      # Decoder for .lz (lzip) format
+      #
+      # This is the lzip format, a DIFFERENT container format from both
+      # XZ and .lzma (LZMA_Alone). Lzip was created as an alternative to
+      # the legacy .lzma format with better integrity checking.
+      #
+      # File format:
+      # - Magic bytes: "LZIP" (0x4C 0x5A 0x49 0x50)
+      # - Version (1 byte): 0 or 1
+      # - Dictionary size (1 byte): encoded format
+      # - LZMA1 compressed stream (with fixed LC=3, LP=0, PB=2)
+      # - Footer:
+      #   - Version 0 (12 bytes): CRC32 (4) + Uncompressed size (8)
+      #   - Version 1 (20 bytes): CRC32 (4) + Uncompressed size (8) + Member size (8)
+      #
+      # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/lzip_decoder.c
+      #
+      # This decoder uses the same LZMA1 decoding engine as XZ format,
+      # but with the lzip container format and CRC32 integrity checking.
+      #
+      # @example Decode .lz file
+      #   data = File.binread("file.lz")
+      #   decoder = Omnizip::Algorithms::LZMA::LzipDecoder.new(StringIO.new(data))
+      #   result = decoder.decode_stream
+      #
+      class LzipDecoder
+        attr_reader :version, :dict_size, :member_size
+
+        # Lzip magic bytes: "LZIP" in ASCII
+        # Reference: lzip_decoder.c:106
+        MAGIC = [0x4C, 0x5A, 0x49, 0x50].freeze
+
+        # Fixed LC/LP/PB values for lzip format
+        # Reference: lzip_decoder.c:23-26
+        LZIP_LC = 3
+        LZIP_LP = 0
+        LZIP_PB = 2
+
+        # Footer sizes
+        # Reference: lzip_decoder.c:19-21
+        LZIP_V0_FOOTER_SIZE = 12
+        LZIP_V1_FOOTER_SIZE = 20
+        LZIP_FOOTER_SIZE_MAX = LZIP_V1_FOOTER_SIZE
+
+        # Minimum and maximum dictionary sizes (in bytes)
+        # Reference: lzip_decoder.c:197-198
+        MIN_DICT_SIZE = 4096 # 4 KiB
+        MAX_DICT_SIZE = (512 << 20) # 512 MiB
+
+        # Initialize the decoder with .lz format input
+        #
+        # @param input [IO] Input stream of .lz compressed data
+        # @param options [Hash] Decoding options
+        # @option options [Boolean] :ignore_check If true, skip CRC32 verification (default: false)
+        # @option options [Boolean] :concatenated If true, decode concatenated .lz members (default: false)
+        # @raise [Omnizip::DecompressionError] If header is invalid or unsupported
+        def initialize(input, options = {})
+          @input = input
+          @ignore_check = options.fetch(:ignore_check, false)
+          # Concatenated mode is enabled by default (lzip natively supports multiple members)
+          @concatenated = options.fetch(:concatenated, true)
+
+          # Parse .lz header
+          parse_header
+
+          # Track member size (including header and footer)
+          # We start with the 6 bytes we've already read (magic + version + dict_size)
+          @member_size = 6
+
+          # For concatenated mode, track if this is the first member
+          @first_member = true
+
+          # Initialize CRC32 calculator
+          @crc32 = 0
+          @uncompressed_size = 0
+        end
+
+        # Decode the .lz stream
+        #
+        # @param output [IO, nil] Optional output stream
+        # @return [String, Integer] Decompressed data or bytes written
+        def decode_stream(output = nil)
+          # For concatenated mode, accumulate all decoded data
+          all_decoded_data = String.new(encoding: Encoding::BINARY)
+          bytes_written = 0
+          result = nil # Initialize result variable
+
+          loop do
+            # Track the starting position of compressed data
+            start_pos = @input.pos
+
+            # Initialize the XZ Utils LZMA decoder with fixed lzip parameters
+            decoder = XzUtilsDecoder.new(@input,
+                                         lzma2_mode: true,
+                                         lc: LZIP_LC,
+                                         lp: LZIP_LP,
+                                         pb: LZIP_PB,
+                                         dict_size: @dict_size,
+                                         uncompressed_size: 0xFFFFFFFFFFFFFFFF) # Unknown size, allow EOPM
+
+            # Decode the LZMA stream (allow EOPM for .lz format)
+            # Get decoded data as string (no output stream)
+            decoded_data = decoder.decode_stream(nil, check_rc_finished: false)
+
+            # If caller provided output stream, write to it
+            if output
+              output.write(decoded_data)
+              bytes_written += decoded_data.bytesize
+              result = bytes_written
+            else
+              all_decoded_data << decoded_data
+              result = all_decoded_data
+            end
+
+            # Calculate member size (header + compressed data + footer)
+            # We calculate it here (compressed data + header), then add footer size below
+            @member_size = @input.pos - start_pos + 6 # +6 for header bytes
+
+            # Calculate and verify CRC32
+            if @ignore_check
+              # Skip footer
+              footer_size = @version.zero? ? LZIP_V0_FOOTER_SIZE : LZIP_V1_FOOTER_SIZE
+              @input.read(footer_size)
+              @member_size += footer_size
+            else
+              data_to_crc = decoded_data || +""
+              calculated_crc = Omnizip::Checksums::Crc32.calculate(data_to_crc)
+              @uncompressed_size = data_to_crc.bytesize
+
+              # Read and verify footer (also updates @member_size to include footer)
+              verify_footer(calculated_crc)
+            end
+
+            # Check for concatenated members
+            break unless @concatenated
+
+            # Peek ahead to check if there's another LZIP member
+            break unless has_next_member?
+
+            # Parse header for next member
+            parse_header
+          end
+
+          # Return decoded data or bytes written
+          result
+        end
+
+        private
+
+        # Check if there's another concatenated LZIP member
+        # Peeks ahead without consuming the magic bytes
+        #
+        # @return [Boolean] true if another member is present
+        def has_next_member?
+          # Peek at next 4 bytes to check for magic
+          magic_bytes = @input.read(4)
+          return false if magic_bytes.nil? || magic_bytes.bytesize < 4
+
+          # Check if it's LZIP magic
+          is_lzip = magic_bytes.getbyte(0) == MAGIC[0] &&
+            magic_bytes.getbyte(1) == MAGIC[1] &&
+            magic_bytes.getbyte(2) == MAGIC[2] &&
+            magic_bytes.getbyte(3) == MAGIC[3]
+
+          # Put the bytes back by seeking back
+          @input.seek(-4, ::IO::SEEK_CUR) if is_lzip
+
+          is_lzip
+        end
+
+        # Parse .lz format header
+        #
+        # Format (from lzip_decoder.c):
+        # - Magic bytes: "LZIP" (4 bytes)
+        # - Version (1 byte): 0 or 1
+        # - Dictionary size (1 byte): encoded format
+        #
+        # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/lzip_decoder.c
+        #
+        # @return [void]
+        # @raise [Omnizip::DecompressionError] If header is invalid
+        def parse_header
+          # Step 1: Verify magic bytes (SEQ_ID_STRING)
+          # Reference: lzip_decoder.c:104-153
+          magic_bytes = @input.read(4)
+          if magic_bytes.nil? || magic_bytes.bytesize < 4
+            raise Omnizip::DecompressionError,
+                  "Incomplete .lz header: missing magic bytes"
+          end
+
+          4.times do |i|
+            if magic_bytes.getbyte(i) != MAGIC[i]
+              raise Omnizip::DecompressionError, "Invalid .lz header: magic bytes don't match LZIP (expected #{MAGIC.map do |b|
+                "0x#{b.to_s(16).upcase}"
+              end.join(' ')}, got #{magic_bytes.bytes.map do |b|
+                                    "0x#{b.to_s(16).upcase}"
+                                  end.join(' ')})"
+            end
+          end
+
+          # Step 2: Read version byte (SEQ_VERSION)
+          # Reference: lzip_decoder.c:156-174
+          version_byte = @input.getbyte
+          if version_byte.nil?
+            raise Omnizip::DecompressionError,
+                  "Incomplete .lz header: missing version byte"
+          end
+
+          @version = version_byte
+
+          # We support version 0 and unextended version 1
+          # Reference: lzip_decoder.c:163-164
+          if @version > 1
+            raise Omnizip::UnsupportedFormatError,
+                  "Unsupported .lz version: #{@version} (only 0 and 1 are supported)"
+          end
+
+          # Step 3: Parse dictionary size (SEQ_DICT_SIZE)
+          # Reference: lzip_decoder.c:177-222
+          dict_size_byte = @input.getbyte
+          if dict_size_byte.nil?
+            raise Omnizip::DecompressionError,
+                  "Incomplete .lz header: missing dictionary size byte"
+          end
+
+          # Decode dictionary size from the encoded byte
+          # The five lowest bits are for the base-2 logarithm of the dictionary size
+          # and the highest three bits are the fractional part (0/16 to 7/16)
+          # Reference: lzip_decoder.c:183-204
+          b2log = dict_size_byte & 0x1F
+          fracnum = dict_size_byte >> 5
+
+          # Validate range: [4 KiB, 512 MiB]
+          # Reference: lzip_decoder.c:198-199
+          if b2log < 12 || b2log > 29 || (b2log == 12 && fracnum.positive?)
+            raise Omnizip::DecompressionError,
+                  "Invalid .lz header: dictionary size byte 0x#{dict_size_byte.to_s(16).upcase} is out of valid range"
+          end
+
+          # Calculate: 2^[b2log] - [fracnum] * 2^([b2log] - 4)
+          # Reference: lzip_decoder.c:201-204
+          @dict_size = (1 << b2log) - (fracnum << (b2log - 4))
+
+          # Sanity checks
+          if @dict_size < MIN_DICT_SIZE
+            raise Omnizip::DecompressionError,
+                  "Dictionary size calculation error: too small"
+          end
+          if @dict_size > MAX_DICT_SIZE
+            raise Omnizip::DecompressionError,
+                  "Dictionary size calculation error: too large"
+          end
+        end
+
+        # Verify .lz format footer
+        #
+        # Format (from lzip_decoder.c):
+        # - CRC32 of uncompressed data (4 bytes, little-endian)
+        # - Uncompressed size (8 bytes, little-endian)
+        # - Member size (8 bytes, little-endian) - only for version 1
+        #
+        # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/lzip_decoder.c:277-309
+        #
+        # @param calculated_crc [Integer] Calculated CRC32 of uncompressed data
+        # @raise [Omnizip::DecompressionError] If footer is invalid or checksum mismatch
+        def verify_footer(calculated_crc)
+          footer_size = @version.zero? ? LZIP_V0_FOOTER_SIZE : LZIP_V1_FOOTER_SIZE
+          footer = @input.read(footer_size)
+          if footer.nil? || footer.bytesize < footer_size
+            raise Omnizip::DecompressionError,
+                  "Incomplete .lz footer: expected #{footer_size} bytes, got #{footer&.bytesize || 0}"
+          end
+
+          # Update member_size to include the footer
+          @member_size += footer_size
+
+          # Parse CRC32 (little-endian)
+          stored_crc = footer.getbyte(0) | (footer.getbyte(1) << 8) |
+            (footer.getbyte(2) << 16) | (footer.getbyte(3) << 24)
+
+          # Verify CRC32
+          if calculated_crc != stored_crc
+            raise Omnizip::ChecksumError,
+                  "CRC32 mismatch: calculated 0x#{calculated_crc.to_s(16).upcase}, stored 0x#{stored_crc.to_s(16).upcase}"
+          end
+
+          # Parse and verify uncompressed size (little-endian)
+          stored_uncompressed_size = footer.getbyte(4) | (footer.getbyte(5) << 8) |
+            (footer.getbyte(6) << 16) | (footer.getbyte(7) << 24) |
+            (footer.getbyte(8) << 32) | (footer.getbyte(9) << 40) |
+            (footer.getbyte(10) << 48) | (footer.getbyte(11) << 56)
+
+          if @uncompressed_size != stored_uncompressed_size
+            raise Omnizip::ChecksumError,
+                  "Uncompressed size mismatch: decoded #{@uncompressed_size}, stored #{stored_uncompressed_size}"
+          end
+
+          # For version 1, verify member size
+          if @version.positive?
+            stored_member_size = footer.getbyte(12) | (footer.getbyte(13) << 8) |
+              (footer.getbyte(14) << 16) | (footer.getbyte(15) << 24) |
+              (footer.getbyte(16) << 32) | (footer.getbyte(17) << 40) |
+              (footer.getbyte(18) << 48) | (footer.getbyte(19) << 56)
+
+            if @member_size != stored_member_size
+              raise Omnizip::ChecksumError,
+                    "Member size mismatch: decoded #{@member_size}, stored #{stored_member_size}"
+            end
+          end
+        end
+
+        # Wrapper input stream that tracks bytes read
+        class TrackingInputStream
+          attr_reader :bytes_read
+
+          def initialize(input, start_offset = 0)
+            @input = input
+            @bytes_read = start_offset
+          end
+
+          def read(size = nil)
+            data = @input.read(size)
+            @bytes_read += data.bytesize if data
+            data
+          end
+
+          def getbyte
+            byte = @input.getbyte
+            @bytes_read += 1 if byte
+            byte
+          end
+
+          def eof?
+            @input.eof?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/lzma/lzma1_encoder.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+module Omnizip
+  module Algorithms
+    class LZMA
+      # Raw LZMA1 stream encoder (one continuous range-coded stream
+      # with the end-of-stream marker), reusing the XZ Utils symbol
+      # coders. This is the payload for the legacy .lzma container
+      # and the lzip member body.
+      class Lzma1Encoder < Implementations::XZUtils::LZMA2::Encoder
+        UINT32_MAX = 0xFFFFFFFF
+        REPS = 4
+
+        # Encode `input` as a complete standalone LZMA1 stream,
+        # terminated by the end-of-stream marker (dist = 0xFFFFFFFF,
+        # length 2) so decoders that do not know the size can stop.
+        #
+        # @param input [String]
+        # @param emit_eopm [Boolean] omit when the container carries
+        #   the uncompressed size (the legacy .lzma form)
+        # @return [String] binary stream
+        # rubocop:disable-next Metrics/MethodLength
+        def encode(input, emit_eopm: true)
+          @match_finder.reset
+          output_buffer = StringIO.new
+          output_buffer.set_encoding(Encoding::BINARY)
+          encoder = XzRangeEncoder.new(output_buffer)
+          @match_finder.feed(input)
+          @match_finder.skip(@match_finder.buffer.bytesize)
+
+          start_pos = 0
+          @current_start_pos = start_pos
+          pos = 0
+          while pos < input.bytesize
+            encode_queued_symbols(encoder, output_buffer)
+
+            match_pos = start_pos + pos
+            distance, length = @optimal.find_optimal(
+              match_pos, @match_finder, @state, @state.reps, @models
+            )
+
+            if distance == UINT32_MAX || length == 1
+              encode_literal(input.getbyte(pos), encoder, match_pos)
+              pos += 1
+            elsif distance < REPS
+              encode_repeated_match(distance, length, encoder, match_pos,
+                                    match_pos)
+              pos += length
+            else
+              encode_match(distance - REPS, length, encoder, match_pos,
+                           match_pos, input)
+              pos += length
+            end
+          end
+
+          encode_eopm(encoder, output_buffer, input.bytesize) if emit_eopm
+          encode_queued_symbols(encoder, output_buffer)
+          encoder.queue_flush
+          encode_queued_symbols(encoder, output_buffer)
+          output_buffer.string
+        end
+
+        private
+
+        # End-of-stream marker: a normal match header with
+        # dist0 = 0xFFFFFFFF and length 2. The distance slot is 63,
+        # whose 30 footer bits the parent's distance coder emits as
+        # 26 direct bits + the 4 align bits.
+        def encode_eopm(encoder, output_buffer, total_pos)
+          pos_state = total_pos & ((1 << @pb) - 1)
+          encoder.queue_bit(@models.is_match[@state.value][pos_state], 1)
+          encoder.queue_bit(@models.is_rep[@state.value], 0)
+          @state.update_match!(UINT32_MAX)
+          encode_match_length(2, pos_state, encoder)
+          # Slot 63's 30 footer bits plus the length/header symbols
+          # exceed the 53-slot symbol queue in one go.
+          encode_queued_symbols(encoder, output_buffer)
+          encode_distance(UINT32_MAX + 1, 2, encoder)
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/lzma/lzma_alone_decoder.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+require "stringio"
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      #
+      # Decoder for .lzma (LZMA_Alone) format
+      #
+      # This is the legacy LZMA_Alone format used by LZMA Utils 4.32.x.
+      # It is DIFFERENT from the XZ format's LZMA2 compression!
+      #
+      # File format:
+      # - Properties (1 byte): encodes lc, lp, pb values
+      # - Dictionary size (4 bytes, little-endian)
+      # - Uncompressed size (8 bytes, little-endian, UINT64_MAX = unknown)
+      # - LZMA1 compressed stream (no footer, no CRC32)
+      #
+      # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/alone_decoder.c
+      #
+      # This decoder uses the same LZMA1 decoding engine as XZ format,
+      # but with the legacy .lzma container format.
+      #
+      # @example Decode .lzma file
+      #   data = File.binread("file.lzma")
+      #   decoder = Omnizip::Algorithms::LZMA::LzmaAloneDecoder.new(StringIO.new(data))
+      #   result = decoder.decode_stream
+      #
+      class LzmaAloneDecoder
+        # Maximum valid uncompressed size (256 GiB)
+        # From alone_decoder.c:118
+        MAX_UNCOMPRESSED_SIZE = (1 << 38)
+
+        # Property byte validation limits
+        # From lzma_decoder.c:1218
+        MAX_PROPERTY_BYTE = (((4 * 5) + 4) * 9) + 8 # = 233
+
+        # Header fields exposed to container callers.
+        attr_reader :lc, :lp, :pb, :dict_size, :uncompressed_size
+
+        # Initialize the decoder with .lzma format input
+        #
+        # @param input [IO] Input stream of .lzma compressed data
+        # @param options [Hash] Decoding options
+        # @option options [Boolean] :picky If true, reject files unlikely to be .lzma (default: false)
+        # @raise [RuntimeError] If header is invalid or unsupported
+        def initialize(input, options = {})
+          @input = input
+          @picky = options.fetch(:picky, false)
+
+          # Parse .lzma header
+          parse_header
+
+          # Create a wrapper stream that starts after the header
+          # The XzUtilsDecoder will read from this stream
+          @lzma_stream = @input
+
+          # Initialize the XZ Utils LZMA decoder with parsed parameters
+          # validate_size=true because .lzma format has explicit uncompressed size
+          # allow_eopm=true because .lzma format allows EOPM even with known size
+          # Reference: alone_decoder.c:127 (LZMA_LZMA1EXT_ALLOW_EOPM)
+          @decoder = XzUtilsDecoder.new(@lzma_stream,
+                                        lzma2_mode: true,
+                                        validate_size: true,
+                                        allow_eopm: true,
+                                        lc: @lc,
+                                        lp: @lp,
+                                        pb: @pb,
+                                        dict_size: @dict_size,
+                                        uncompressed_size: @uncompressed_size)
+        end
+
+        # Decode the .lzma stream
+        #
+        # @param output [IO, nil] Optional output stream
+        # @return [String, Integer] Decompressed data or bytes written
+        def decode_stream(output = nil)
+          # .lzma format allows EOPM even when uncompressed size is known
+          # Reference: alone_decoder.c:127 (LZMA_LZMA1EXT_ALLOW_EOPM)
+          @decoder.decode_stream(output, check_rc_finished: false)
+        end
+
+        private
+
+        # Parse .lzma format header
+        #
+        # Format (from alone_decoder.c):
+        # - Properties (1 byte): lc/lp/pb encoded
+        # - Dictionary size (4 bytes, little-endian)
+        # - Uncompressed size (8 bytes, little-endian, UINT64_MAX = unknown)
+        #
+        # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/alone_decoder.c
+        #
+        # @return [void]
+        # @raise [RuntimeError] If header is invalid
+        def parse_header
+          # Step 1: Parse properties byte (SEQ_PROPERTIES)
+          # Reference: alone_decoder.c:64-68
+          props = @input.getbyte
+          raise Omnizip::DecompressionError, "Invalid .lzma header: missing properties byte" if props.nil?
+
+          # Use XZ Utils property byte parsing
+          # Reference: /Users/mulgogi/src/external/xz/src/liblzma/lzma/lzma_decoder.c:1216-1228
+          if props > MAX_PROPERTY_BYTE
+            raise Omnizip::DecompressionError, "Invalid .lzma header: properties byte #{props} exceeds maximum #{MAX_PROPERTY_BYTE}"
+          end
+
+          # Parse lc, lp, pb from properties byte
+          # Formula: pb = props / (9 * 5); lp = (props % 45) / 9; lc = (props % 45) % 9
+          @pb = props / (9 * 5)
+          remainder = props - (@pb * 9 * 5)
+          @lp = remainder / 9
+          @lc = remainder - (@lp * 9)
+
+          # Validate lc + lp <= 4 (LZMA_LCLP_MAX)
+          # Reference: lzma_decoder.c:1227
+          if @lc + @lp > 4
+            raise Omnizip::DecompressionError, "Invalid .lzma header: lc (#{@lc}) + lp (#{@lp}) exceeds maximum 4"
+          end
+
+          # Step 2: Parse dictionary size (SEQ_DICTIONARY_SIZE)
+          # Reference: alone_decoder.c:71-96
+          @dict_size = 0
+          4.times do |i|
+            byte = @input.getbyte
+            raise Omnizip::DecompressionError, "Incomplete .lzma header: missing dictionary size byte" if byte.nil?
+
+            @dict_size |= (byte << (i * 8))
+          end
+
+          # Picky mode validation: only accept dictionary sizes that are
+          # 2^n or 2^n + 2^(n-1). This reduces false positives.
+          # Reference: alone_decoder.c:76-93
+          if @picky && @dict_size != 0xFFFFFFFF
+            # Check if dict_size is valid: 2^n or 2^n + 2^(n-1)
+            d = @dict_size - 1
+            d |= d >> 2
+            d |= d >> 3
+            d |= d >> 4
+            d |= d >> 8
+            d |= d >> 16
+            d += 1
+
+            if d != @dict_size
+              raise Omnizip::DecompressionError, "Invalid .lzma header: dictionary size #{@dict_size} is not 2^n or 2^n + 2^(n-1)"
+            end
+          end
+
+          # Step 3: Parse uncompressed size (SEQ_UNCOMPRESSED_SIZE)
+          # Reference: alone_decoder.c:102-120
+          @uncompressed_size = 0
+          8.times do |i|
+            byte = @input.getbyte
+            raise Omnizip::DecompressionError, "Incomplete .lzma header: missing uncompressed size byte" if byte.nil?
+
+            @uncompressed_size |= (byte << (i * 8))
+          end
+
+          # Picky mode validation: if uncompressed size is known (not UINT64_MAX),
+          # it must be less than 256 GiB
+          # Reference: alone_decoder.c:116-120
+          if @picky && @uncompressed_size != 0xFFFFFFFFFFFFFFFF &&
+              @uncompressed_size >= MAX_UNCOMPRESSED_SIZE
+            raise Omnizip::DecompressionError, "Invalid .lzma header: uncompressed size #{@uncompressed_size} exceeds maximum #{MAX_UNCOMPRESSED_SIZE}"
+          end
+
+          # Note: XZ Utils uses UINT64_MAX (0xFFFFFFFFFFFFFFFF) for unknown size
+          # Our decoder treats this as "allow end-of-payload marker"
+        end
+      end
+    end
+  end
+end