pdfrb 0.1.0

data/lib/pdfrb/document/pages.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Page-tree facade. Exposes +add+, +[]+, +each+, +count+,
+    # +delete+ against the Catalog's /Pages tree.
+    class Pages
+      include Enumerable
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Add a new page at the end of the page tree.
+      #
+      # Options:
+      #   media_box: [0, 0, 612, 792]   # default US Letter
+      #   rotate: 0                     # degrees
+      #
+      # Returns the new +Model::Type::Page+.
+      def add(media_box: [0, 0, 612, 792], rotate: 0)
+        root = pages_root
+        contents = document.add({}, type: Pdfrb::Model::Cos::Stream)
+        page = document.add(
+          {
+            Type: :Page,
+            Parent: Pdfrb::Model::Reference.new(root.oid, root.gen),
+            MediaBox: media_box,
+            Resources: {},
+            Contents: Pdfrb::Model::Reference.new(contents.oid, 0)
+          },
+          type: Pdfrb::Model::Type::Page
+        )
+        page.value[:Rotate] = rotate if rotate.nonzero?
+        kids = (root.value[:Kids] ||= [])
+        kids << Pdfrb::Model::Reference.new(page.oid, page.gen)
+        root.value[:Count] = (root.value[:Count] || 0) + 1
+        page
+      end
+      alias << add
+
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        walk(pages_root, &block)
+        self
+      end
+
+      def count
+        raw = pages_root[:Count]
+        resolved = raw.is_a?(Pdfrb::Model::Reference) ? document.object(raw)&.value : raw
+        case resolved
+        when Integer then resolved
+        when Numeric then resolved.to_i
+        else
+          # Fallback: walk the page tree.
+          count = 0
+          each { count += 1 }
+          count
+        end
+      end
+      alias size count
+      alias length count
+
+      def empty?
+        count.zero?
+      end
+
+      def [](index)
+        each_with_index { |p, i| return p if i == index }
+        nil
+      end
+
+      def delete(page)
+        ref = ref_to(page)
+        root = pages_root
+        kids = root.value[:Kids]
+        return unless kids&.delete(ref)
+
+        root.value[:Count] = (root.value[:Count] || 1) - 1
+        page
+      end
+
+      private
+
+      def pages_root
+        catalog = document.catalog
+        raise Pdfrb::Error, "Document has no Catalog" unless catalog
+
+        ref = catalog.value[:Pages]
+        return document.object(ref) if ref
+
+        # No /Pages yet — seed an empty tree.
+        root = document.add({ Type: :Pages, Kids: [], Count: 0 },
+                            type: Pdfrb::Model::Type::PageTreeNode)
+        catalog.value[:Pages] = Pdfrb::Model::Reference.new(root.oid, root.gen)
+        root
+      end
+
+      def walk(node, &block)
+        kids = node.respond_to?(:value) ? node.value[:Kids] : node[:Kids]
+        return unless kids
+
+        # Kids may itself be an indirect reference, especially in
+        # compressed-object PDFs (FOP output).
+        kids = document.object(kids).value if kids.is_a?(Pdfrb::Model::Reference)
+        kids = kids.value if kids.respond_to?(:value) && !kids.is_a?(::Hash)
+
+        Array(kids).each do |kid_ref|
+          kid = kid_ref.is_a?(Pdfrb::Model::Reference) ?
+                  document.object(kid_ref) : kid_ref
+          next unless kid
+
+          type = kid.respond_to?(:value) ? kid.value[:Type] : nil
+          case type
+          when :Pages then walk(kid, &block)
+          when :Page then yield kid
+          else
+            # Unknown type — best effort, treat as a Page.
+            yield kid if kid.respond_to?(:value)
+          end
+        end
+      end
+
+      def ref_to(page)
+        return page if page.is_a?(Pdfrb::Model::Reference)
+
+        Pdfrb::Model::Reference.new(page.oid, page.gen)
+      end
+    end
+  end
+end

data/lib/pdfrb/document.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Pdfrb
+  # Top-level PDF document facade. Owns:
+  #   * The IO it was read from (or nil for in-memory).
+  #   * An oid -> Object table for new/modified objects.
+  #   * A wrap() pipeline that upgrades raw Hashes to typed
+  #     Dictionary subclasses based on /Type or an explicit type.
+  #   * On read: an XrefSection + ObjectReader for lazy resolution.
+  #   * A revisions stack (TODO 30 — incremental updates).
+  class Document
+    autoload :Pages, "pdfrb/document/pages"
+    autoload :Fonts, "pdfrb/document/fonts"
+    autoload :Metadata, "pdfrb/document/metadata"
+    autoload :Images, "pdfrb/document/images"
+    autoload :Files, "pdfrb/document/files"
+    autoload :Destinations, "pdfrb/document/destinations"
+    autoload :Annotations, "pdfrb/document/annotations"
+
+    def initialize(io: nil, config: {})
+      @config = Configuration.new(config)
+      @io = io
+      @objects = {}        # oid -> Pdfrb::Model::Object (modified or new)
+      @next_oid = 1
+      @listeners = {}      # message_name -> [Proc]
+      @xref = nil
+      @object_reader = nil
+      @version = "1.4"
+      @empty_trailer = nil
+
+      if io
+        read_from_io(io)
+      else
+        seed_empty_structure
+      end
+    end
+
+    attr_reader :config, :io, :xref, :version
+
+    def self.open(path, **opts)
+      if block_given?
+        File.open(path, "rb") { |f| yield new(io: f, **opts) }
+      else
+        bytes = File.binread(path)
+        require "stringio"
+        new(io: StringIO.new(bytes), **opts)
+      end
+    end
+
+    def wrap(data, type: nil, oid: 0, gen: 0)
+      target_class = resolve_target_class(data, type)
+      value = unwrap_value(data)
+      if target_class <= Pdfrb::Model::Object
+        target_class.new(value, oid: oid, gen: gen, document: self)
+      else
+        target_class.new(value)
+      end
+    end
+
+    def add(value, type: nil)
+      oid = allocate_oid
+      obj = wrap(value, type: type, oid: oid, gen: 0)
+      register(obj)
+      obj
+    end
+
+    # Resolve a Reference to its Object. New/modified objects take
+    # precedence over xref-loaded ones; otherwise consult the
+    # ObjectReader (which caches per oid).
+    def object(reference)
+      return reference unless reference.is_a?(Pdfrb::Model::Reference)
+
+      modified = @objects[reference.oid]
+      return modified if modified
+      return nil if @object_reader.nil?
+
+      @object_reader.load_oid(reference.oid)
+    end
+    alias dereference object
+
+    def register_listener(message, &block)
+      (@listeners[message] ||= []) << block
+    end
+
+    def dispatch_message(message, *args)
+      return unless @listeners.key?(message)
+
+      @listeners[message].each { |blk| blk.call(*args) }
+    end
+
+    # ---- Facade accessors (Phase 13) ----
+    # Each returns a memoised helper object that knows how to mutate
+    # this document. Defined under Pdfrb::Document::*.
+
+    def pages
+      @pages ||= Document::Pages.new(self)
+    end
+
+    def fonts
+      @fonts ||= Document::Fonts.new(self)
+    end
+
+    def images
+      @images ||= Document::Images.new(self)
+    end
+
+    def files
+      @files ||= Document::Files.new(self)
+    end
+
+    def metadata
+      @metadata ||= Document::Metadata.new(self)
+    end
+
+    def destinations
+      @destinations ||= Document::Destinations.new(self)
+    end
+
+    def annotations
+      @annotations ||= Document::Annotations.new(self)
+    end
+
+    # Replace an indirect object in the @objects table. Used by the
+    # Importer when promoting a Dictionary stub to a Stream (so cycles
+    # resolve correctly). Idempotent.
+    def register_override(obj)
+      @objects[obj.oid] = obj
+    end
+
+    # Write this document to +path+ (or any IO via +io:).
+    def write(path = nil, io: nil)
+      target = io || (path && File.open(path, "wb"))
+      raise ArgumentError, "write needs a path or io:" unless target
+
+      Pdfrb::Writer.write(self, target)
+      target.close if path && io.nil? && target.respond_to?(:close)
+      self
+    end
+
+    # Convenience accessor for the document Catalog dict. Loads from
+    # trailer's /Root, which itself is loaded lazily from the xref.
+    def trailer
+      return @trailer if defined?(@trailer) && @trailer
+
+      @trailer = read_trailer
+    end
+
+    def catalog
+      return @catalog if defined?(@catalog) && @catalog
+
+      ref = trailer ? trailer[:Root] : nil
+      return nil unless ref
+
+      @catalog = object(ref)
+    end
+
+    # Yield every indirect object in this document: modified/new ones
+    # first (they shadow loaded ones), then every loaded entry the
+    # xref knows about.
+    def each_indirect_object
+      seen = Set.new
+      @objects.each_value do |obj|
+        next unless obj.indirect?
+
+        seen << obj.oid
+        yield obj
+      end
+      return if @xref.nil?
+
+      @xref.entries.each_key do |oid|
+        next if seen.include?(oid)
+        next if oid.zero?
+
+        obj = object(Pdfrb::Model::Reference.new(oid, 0))
+        next if obj.nil? || !obj.indirect?
+
+        yield obj
+      end
+    end
+
+    private
+
+    def allocate_oid
+      oid = @next_oid
+      @next_oid += 1
+      oid
+    end
+
+    def register(obj)
+      @objects[obj.oid] = obj
+    end
+
+    def read_from_io(io)
+      version = Pdfrb::Source::HeaderReader.read(io)
+      @version = version if version
+      sxref = Pdfrb::Source::TrailerReader.startxref_offset(io)
+      return unless sxref
+
+      @xref, @trailer_dict = load_xref_and_trailer(io, sxref)
+      @object_reader = Pdfrb::Source::ObjectReader.new(self, @xref) if @xref
+    end
+
+    def load_xref_and_trailer(io, sxref)
+      xref, trailer = load_single_xref(io, sxref)
+      return [nil, nil] unless xref && trailer
+
+      # Follow /Prev chain for incremental updates. Earlier entries
+      # fill gaps; later entries take precedence (already in xref).
+      prev_offset = trailer[:Prev]
+      while prev_offset
+        prev_xref, prev_trailer = load_single_xref(io, prev_offset)
+        break unless prev_xref
+
+        xref.merge!(prev_xref)
+        prev_offset = prev_trailer && prev_trailer[:Prev]
+      end
+
+      [xref, trailer]
+    end
+
+    def load_single_xref(io, sxref)
+      actual_xref_pos = find_xref_keyword(io, sxref)
+      if actual_xref_pos
+        xref = Pdfrb::Source::XrefTableReader.read(io, actual_xref_pos)
+        trailer = read_trailer_dict_after_xref(io)
+        return [xref, trailer]
+      end
+
+      # Try as XRef stream (PDF 1.5+).
+      io.seek(sxref, IO::SEEK_SET)
+      tok = Pdfrb::Source::Tokenizer.new(io)
+      parser = Pdfrb::Source::Parser.new(tok, document: self)
+      obj = parser.parse_indirect_object rescue nil
+      if obj.is_a?(Pdfrb::Model::Cos::Stream) && obj[:Type] == :XRef
+        xref = Pdfrb::Source::XrefStreamReader.read(obj, self)
+        [xref, obj.value]
+      else
+        # Last resort: recovery.
+        recover_or_raise(Pdfrb::ParseError.new("cannot locate xref at #{sxref}"))
+        [nil, nil]
+      end
+    rescue Pdfrb::ParseError => e
+      recover_or_raise(e)
+    end
+
+    # Search for the "xref" keyword near +offset+. Real PDFs have
+    # startxref values that drift (19-byte entries, generator bugs).
+    # Must exclude false matches inside "startxref\nNNNN\n%%EOF".
+    def find_xref_keyword(io, offset)
+      # First try the exact offset.
+      io.seek(offset, IO::SEEK_SET)
+      return offset if io.gets&.strip == "xref"
+
+      # Search backwards for "\nxref\n" (newline-anchored to avoid
+      # matching "startxref") within 2KB before the offset.
+      search_start = [offset - 2048, 0].max
+      io.seek(search_start, IO::SEEK_SET)
+      chunk = io.read(offset - search_start + 10)
+      # Find the last "\nxref\n" — the \n prefix ensures we don't
+      # match the "xref" inside "startxref".
+      pos = chunk.rindex("\nxref\n")
+      return search_start + pos + 1 if pos
+
+      # If not found with \n prefix, try from byte 0 (the xref might
+      # be at the very start of the search chunk with no \n before it).
+      pos = chunk.rindex("xref\n")
+      # Verify it's not inside "startxref".
+      if pos && pos > 4 && chunk.byteslice(pos - 4, 5) == "start"
+        pos = chunk.rindex("xref\n", pos - 1)
+      end
+      pos ? search_start + pos : nil
+    end
+
+    def read_trailer_dict_after_xref(io)
+      # XrefTableReader already consumed up to and including the
+      # "trailer" keyword line; skip any blank lines then parse the
+      # dict that follows.
+      while (line = io.gets)
+        break unless line.strip.empty?
+      end
+      io.seek(-line.bytesize, IO::SEEK_CUR) if line
+      tok = Pdfrb::Source::Tokenizer.new(io)
+      parser = Pdfrb::Source::Parser.new(tok, document: self)
+      parser.parse_dict
+    end
+
+    def read_trailer
+      return @trailer_dict if defined?(@trailer_dict) && @trailer_dict
+
+      @empty_trailer
+    end
+
+    def seed_empty_structure
+      pages = add({ Type: :Pages, Kids: [], Count: 0 })
+      catalog = add({ Type: :Catalog, Pages: Pdfrb::Model::Reference.new(pages.oid, 0) })
+      @catalog = catalog
+      @empty_trailer = { Size: @next_oid, Root: Pdfrb::Model::Reference.new(catalog.oid, 0) }
+    end
+
+    def recover_or_raise(error)
+      recover = @config["source.recover_malformed"]
+      raise error unless recover
+
+      recovered = Pdfrb::Source::Recovery.rebuild_xref(@io)
+      @xref = recovered
+      @object_reader = Pdfrb::Source::ObjectReader.new(self, recovered)
+      nil
+    end
+
+    def resolve_target_class(data, requested)
+      return requested if requested.is_a?(Class)
+      return data.class if data.is_a?(Pdfrb::Model::Object) && requested.nil? && typed_object?(data)
+
+      value = unwrap_value(data)
+      if value.is_a?(::Hash)
+        sym = value[:Type]
+        if sym
+          mapped = Pdfrb::Model::Cos::Dictionary.lookup_type(sym)
+          return mapped if mapped
+        end
+      end
+      default_class_for(value)
+    end
+
+    def typed_object?(obj)
+      obj.class != Pdfrb::Model::Object && obj.class != Pdfrb::Model::Cos::Dictionary
+    end
+
+    def unwrap_value(data)
+      data.is_a?(Pdfrb::Model::Object) ? data.value : data
+    end
+
+    def default_class_for(value)
+      case value
+      when ::Hash then Pdfrb::Model::Cos::Dictionary
+      when ::Array then Pdfrb::Model::PdfArray
+      else Pdfrb::Model::Object
+      end
+    end
+  end
+end

data/lib/pdfrb/encryption/aes.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Pdfrb
+  module Encryption
+    # AES cipher in CBC mode for PDF V4..V6 (s7.6.3.2 / 7.6.3.3).
+    # Backed by +openssl+ stdlib for performance and correctness.
+    # Caller derives the per-object key and the 16-byte IV (PDF V5+
+    # uses IV-in-ciphertext; PDF V4 uses random IV per stream).
+    class AES
+      attr_reader :key_size, :mode
+
+      def initialize(key_size: 128, mode: :CBC)
+        @key_size = key_size
+        @mode = mode
+      end
+
+      def encrypt(plain, key, iv)
+        cipher = openssl_cipher(:encrypt, key.bytesize)
+        cipher.key = key.b
+        cipher.iv = iv.b
+        cipher.padding = 0 # PDF pads itself (PKCS#7)
+        out = cipher.update(pad_pkcs7(plain.b, 16)) + cipher.final
+        iv.b + out
+      end
+
+      def decrypt(ciphertext, key)
+        cipher = openssl_cipher(:decrypt, key.bytesize)
+        iv = ciphertext.byteslice(0, 16)
+        body = ciphertext.byteslice(16..)
+        cipher.key = key.b
+        cipher.iv = iv
+        cipher.padding = 0
+        decrypted = cipher.update(body) + cipher.final
+        strip_pkcs7(decrypted)
+      end
+
+      private
+
+      def openssl_cipher(direction, key_bytes)
+        name = case key_bytes
+               when 16 then "AES-128-#{@mode}"
+               when 32 then "AES-256-#{@mode}"
+               else raise Pdfrb::EncryptionError,
+                            "unsupported AES key length #{key_bytes}"
+               end
+        c = OpenSSL::Cipher.new(name)
+        direction == :encrypt ? c.encrypt : c.decrypt
+        c
+      end
+
+      def pad_pkcs7(data, block_size)
+        pad = block_size - (data.bytesize % block_size)
+        data + (pad.chr * pad)
+      end
+
+      def strip_pkcs7(data)
+        return data if data.empty?
+
+        pad = data.getbyte(-1)
+        return data unless pad && pad.between?(1, 16)
+
+        data.byteslice(0, data.bytesize - pad)
+      end
+    end
+  end
+end

data/lib/pdfrb/encryption/password_verification.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+require "digest/sha2"
+
+module Pdfrb
+  module Encryption
+    # Password verification and key derivation for the Standard
+    # security handler (s7.6.3.3, Algorithms 2 / 3 / 5 / 6 / 7).
+    #
+    # All functions are pure (no IO); they consume and return bytes.
+    module PasswordVerification
+      PADDING_BYTES = [
+        0x28, 0xBF, 0x4E, 0x5E, 0x4E, 0x75, 0x8A, 0x41,
+        0x64, 0x00, 0x4E, 0x56, 0xFF, 0xFA, 0x01, 0x08,
+        0x2E, 0x2E, 0x00, 0xB6, 0xD0, 0x68, 0x3E, 0x80,
+        0x2F, 0x0C, 0xA9, 0xFE, 0x64, 0x53, 0x69, 0x7A
+      ].freeze
+      private_constant :PADDING_BYTES
+
+      module_function
+
+      # Algorithm 2: derive the encryption key from a user password
+      # for revisions 2..4 (RC4 and AES-128).
+      def derive_key_rc4(password:, o_entry:, p_flags:, id0:,
+                         revision:, key_length_bits:, encrypt_metadata: true)
+        padded = pad_password(password)
+        digest = Digest::MD5.new
+        digest.update(padded)
+        digest.update(o_entry.b)
+        digest.update([p_flags].pack("V"))
+        digest.update(id0.b)
+        unless encrypt_metadata
+          digest.update("\xFF\xFF\xFF\xFF".b)
+        end
+        hash = digest.digest
+        if revision >= 3
+          50.times { hash = Digest::MD5.digest(hash[0, key_length_bits / 8]) }
+        end
+        hash.byteslice(0, key_length_bits / 8)
+      end
+
+      # Algorithm 5: derive the encryption key for revision 6
+      # (AES-256, PDF 2.0).
+      def derive_key_v6(password:, u_entry:, o_entry:,
+                        p_flags:, oe_entry:)
+        # PDF 2.0 uses SHA-256 with password + validation salt.
+        raise NotImplementedError, "V6 key derivation TBD"
+      end
+
+      # Algorithm 4 (R=2): build the /U entry.
+      def build_u_r2(file_key)
+        rc4 = RC4.new(file_key)
+        rc4.process(pack_bytes(PADDING_BYTES))
+      end
+
+      # Algorithm 5 (R>=3): build the /U entry.
+      def build_u_r3plus(file_key:, id0:, revision:)
+        digest = Digest::MD5.new
+        digest.update(pack_bytes(PADDING_BYTES))
+        digest.update(id0.b)
+        hash = digest.digest
+        rc4 = RC4.new(file_key)
+        encrypted = rc4.process(hash)
+        # 19 more rounds with key XORed by round index.
+        19.times do |i|
+          key = file_key.bytes.map { |b| (b ^ i).chr }.join
+          encrypted = RC4.new(key).process(encrypted)
+        end
+        # Pad / truncate to 32 bytes.
+        encrypted = encrypted + ("\x00" * (32 - encrypted.bytesize))
+        encrypted.byteslice(0, 32)
+      end
+
+      # Algorithm 6: verify a user password. Returns true if it
+      # matches.
+      def verify_user_password(password:, encrypt_dict:, id0:)
+        o_entry = encrypt_dict[:O].b
+        p_flags = encrypt_dict[:P]
+        revision = encrypt_dict[:R]
+        key_bits = (encrypt_dict[:Length] || 40).to_i
+        encrypt_metadata = encrypt_dict.fetch(:EncryptMetadata, true)
+        key = derive_key_rc4(
+          password: password, o_entry: o_entry, p_flags: p_flags,
+          id0: id0, revision: revision, key_length_bits: key_bits,
+          encrypt_metadata: encrypt_metadata
+        )
+        expected_u = if revision == 2
+                       build_u_r2(key)
+                     else
+                       build_u_r3plus(file_key: key, id0: id0, revision: revision)
+                     end
+        u_entry = encrypt_dict[:U].b
+        # Compare the first 16 bytes for R>=3.
+        slice_len = revision == 2 ? 32 : 16
+        expected_u.byteslice(0, slice_len) == u_entry.byteslice(0, slice_len)
+      end
+
+      def pad_password(password)
+        bytes = password.to_s.b
+        padded = bytes + pack_bytes(PADDING_BYTES)
+        padded.byteslice(0, 32)
+      end
+      module_function :pad_password
+
+      def pack_bytes(arr)
+        arr.map(&:chr).join.force_encoding(Encoding::BINARY)
+      end
+      private_class_method :pack_bytes
+    end
+  end
+end

data/lib/pdfrb/encryption/rc4.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Encryption
+    # Pure-Ruby RC4 stream cipher (s7.6.3.1, Algorithm 1). Key can be
+    # 1..256 bytes (PDF uses 5..32). Stateless per call: build a new
+    # cipher for each (key, oid, gen) tuple.
+    class RC4
+      attr_reader :key
+
+      def initialize(key)
+        @key = key.b
+        @s = (0..255).to_a
+        @i = @j = 0
+        key_schedule
+      end
+
+      # Encrypt/decrypt +bytes+ (symmetric). Caller is responsible for
+      # prepending the per-object key (5..16 bytes derived via MD5 of
+      # file_key + oid + gen).
+      def process(bytes)
+        out = +""
+        bytes.b.each_byte do |b|
+          @i = (@i + 1) & 0xFF
+          @j = (@j + @s[@i]) & 0xFF
+          @s[@i], @s[@j] = @s[@j], @s[@i]
+          out << (b ^ @s[(@s[@i] + @s[@j]) & 0xFF]).chr
+        end
+        out.force_encoding(Encoding::BINARY)
+      end
+      alias encrypt process
+      alias decrypt process
+
+      private
+
+      def key_schedule
+        j = 0
+        256.times do |i|
+          j = (j + @s[i] + @key.getbyte(i % @key.bytesize)) & 0xFF
+          @s[i], @s[j] = @s[j], @s[i]
+        end
+      end
+    end
+  end
+end