pdfrb 0.3.0 → 0.7.1

data/lib/pdfrb/document/structure.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Facade for authoring tagged PDF structure trees (PDF/UA §7.9, ISO 32000-2 §14.8).
+    #
+    # A tagged PDF has:
+    #   * /StructTreeRoot on the Catalog — root of the structure hierarchy.
+    #   * /MarkInfo /Marked true on the Catalog — declares the PDF as tagged.
+    #   * /ParentTree on StructTreeRoot — maps marked-content BDC/EMC
+    #     references (via /MCID on BDC) back to their parent StructElem.
+    #
+    # Structure elements form a tree: a document has sections, sections
+    # have headings/paragraphs/figures, etc. Each element has a /S
+    # (structure type — :H1, :P, :Figure, :Table, ...) and optional
+    # /T (title), /Alt (alternate text), /Lang (language).
+    class Structure
+      attr_reader :document, :root
+
+      def initialize(document)
+        @document = document
+        @elements = []
+        @current_index = 0
+      end
+
+      # Enable tagged PDF: create /StructTreeRoot, set /MarkInfo.
+      # Idempotent — returns the existing root if already enabled.
+      # @return [Pdfrb::Model::Cos::Dictionary] the StructTreeRoot.
+      def enable!
+        return @root if @root
+
+        root_elem = document.add(
+          { Type: :StructTreeRoot },
+          type: Pdfrb::Model::Type::StructTreeRoot
+        )
+        catalog = document.catalog
+        catalog.value[:StructTreeRoot] =
+          Pdfrb::Model::Reference.new(root_elem.oid, root_elem.gen)
+        mark_info = catalog.value[:MarkInfo]
+        if mark_info.nil?
+          mark_info = document.add({ Marked: true },
+                                   type: Pdfrb::Model::Cos::Dictionary)
+          catalog.value[:MarkInfo] =
+            Pdfrb::Model::Reference.new(mark_info.oid, mark_info.gen)
+        end
+        @root = root_elem
+      end
+
+      # Add a top-level child element to the structure tree.
+      # @param type [Symbol] structure type (:Document, :Part, :H1, :P, ...).
+      # @param attrs [Hash] additional attributes (:T, :Alt, :Lang, ...).
+      # @return [Pdfrb::Model::Cos::Dictionary] the new element.
+      def add_element(type, page: nil, mcid: nil, **attrs)
+        ensure_root
+        elem = create_element(type, **attrs)
+        append_child(@root, elem)
+
+        if page
+          page_ref = if page.is_a?(Pdfrb::Model::Reference)
+                       page
+                     else
+                       Pdfrb::Model::Reference.new(page.oid, page.gen)
+                     end
+          elem.value[:Pg] = page_ref
+        end
+        elem.value[:K] = { MCID: mcid } if mcid
+
+        @elements << elem
+        elem
+      end
+
+      # Add a child element to a parent element.
+      # @param parent [Pdfrb::Model::Cos::Dictionary] the parent StructElem.
+      # @param type [Symbol] structure type.
+      # @param attrs [Hash] additional attributes.
+      # @return [Pdfrb::Model::Cos::Dictionary] the new element.
+      def add_child(parent, type, **attrs)
+        elem = create_element(type, **attrs)
+        append_child(parent, elem)
+        @elements << elem
+        elem
+      end
+
+      # Set alternate text on a structure element for screen readers.
+      # Required for /Figure elements per PDF/UA-1 Tech Note 001.
+      # @param element [Pdfrb::Model::Cos::Dictionary] the StructElem.
+      # @param text [String] the alt text.
+      def set_alt_text(element, text)
+        element.value[:Alt] = text.to_s
+      end
+
+      # Set actual text on a structure element. Overrides the visual
+      # text for screen readers (e.g., expanding abbreviations).
+      # @param element [Pdfrb::Model::Cos::Dictionary] the StructElem.
+      # @param text [String] the actual text.
+      def set_actual_text(element, text)
+        element.value[:ActualText] = text.to_s
+      end
+
+      # Set language on a structure element (overrides document /Lang).
+      # @param element [Pdfrb::Model::Cos::Dictionary] the StructElem.
+      # @param lang [String] BCP 47 language tag (e.g., "en-US").
+      def set_language(element, lang)
+        element.value[:Lang] = lang.to_s
+      end
+
+      # Check if a structure element has alt text (required for /Figure).
+      # @param element [Pdfrb::Model::Cos::Dictionary] the StructElem.
+      # @return [Boolean]
+      def has_alt_text?(element)
+        alt = element.value[:Alt]
+        alt && !alt.to_s.empty?
+      end
+
+      # Validate that all /Figure elements have /Alt text per PDF/UA-1.
+      # @return [Array<Hash>] list of violations (element + reason).
+      def validate_alt_text!
+        violations = []
+        each_element do |elem|
+          next unless elem.value[:S]&.to_sym == :Figure
+
+          unless has_alt_text?(elem)
+            violations << { element: elem, reason: "Figure missing /Alt text" }
+          end
+        end
+        violations
+      end
+
+      # Walk all structure elements depth-first.
+      def each_element(&block)
+        return enum_for(:each_element) unless block
+
+        @elements.each(&block)
+      end
+
+      # Define a role mapping: maps a custom structure type name to
+      # a standard one. Required for PDF/UA when custom types are used.
+      # @param custom [Symbol] the custom type name.
+      # @param standard [Symbol] the standard type (:H1, :P, :Figure, ...).
+      def map_role(custom, standard)
+        ensure_root
+        role_map = @root.value[:RoleMap]
+        if role_map.nil?
+          role_map = {}
+          @root.value[:RoleMap] = role_map
+        end
+        role_map[custom] = standard
+        role_map
+      end
+
+      private
+
+      def build_parent_tree
+        return if @root.nil?
+
+        page_map = Hash.new { |h, k| h[k] = [] }
+        max_page = -1
+        each_element_with_page do |elem, page_index, mcid|
+          page_map[page_index] << [mcid, elem]
+          max_page = page_index if page_index > max_page
+        end
+
+        nums = []
+        page_map.keys.sort.each do |page_idx|
+          entries = page_map[page_idx]
+          nums << page_idx
+          nums << entries.length
+          entries.each do |_mcid, elem| # rubocop:disable Style/HashEachMethods
+            nums << Pdfrb::Model::Reference.new(elem.oid, elem.gen)
+          end
+        end
+
+        @root.value[:ParentTree] = { Nums: nums }
+        @root.value[:ParentTreeNextKey] = max_page + 1 if max_page >= 0
+      end
+
+      def each_element_with_page
+        return enum_for(:each_element_with_page) unless block_given?
+
+        @elements.each do |elem|
+          page_ref = elem.value[:Pg]
+          page_index = page_index_for(page_ref)
+          mcid = mcid_for(elem)
+          yield elem, page_index, mcid
+        end
+      end
+
+      def page_index_for(page_ref)
+        return 0 unless page_ref
+
+        document.pages.each_with_index do |page, idx|
+          page_obj = page.is_a?(Pdfrb::Model::Reference) ? document.object(page) : page
+          return idx if page_obj == page_ref || page == page_ref
+        end
+        0
+      end
+
+      def mcid_for(elem)
+        k = elem.value[:K]
+        k.is_a?(::Hash) ? k[:MCID] || 0 : 0
+      end
+
+      def ensure_root
+        @root || enable!
+      end
+
+      def create_element(type, **attrs)
+        dict = { Type: :StructElem, S: type }
+        dict[:T] = attrs[:title] if attrs[:title]
+        dict[:Alt] = attrs[:alt] if attrs[:alt]
+        dict[:Lang] = attrs[:lang] if attrs[:lang]
+        document.add(dict, type: Pdfrb::Model::Type::StructElem)
+      end
+
+      def append_child(parent, child)
+        children = parent.value[:K]
+        if children.nil?
+          parent.value[:K] = [Pdfrb::Model::Reference.new(child.oid, child.gen)]
+        elsif children.is_a?(::Array)
+          children << Pdfrb::Model::Reference.new(child.oid, child.gen)
+        else
+          parent.value[:K] = [
+            children,
+            Pdfrb::Model::Reference.new(child.oid, child.gen),
+          ]
+        end
+        child.value[:P] = Pdfrb::Model::Reference.new(parent.oid, parent.gen)
+      end
+
+      public
+
+      # Build the structure tree, ParentTree, and set up /MarkInfo.
+      # Idempotent — safe to call multiple times.
+      def build!
+        enable! if @root.nil?
+        return if @elements.empty?
+
+        build_parent_tree
+      end
+    end
+  end
+end

data/lib/pdfrb/document.rb

@@ -1,7 +1,5 @@
 # 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).
@@ -20,8 +18,22 @@ module Pdfrb
     autoload :Annotations, "pdfrb/document/annotations"
     autoload :Outline, "pdfrb/document/outline"
     autoload :FormXObject, "pdfrb/document/form_xobject"
+    autoload :AssociatedFiles, "pdfrb/document/associated_files"
+    autoload :Colors, "pdfrb/document/colors"
+    autoload :Display, "pdfrb/document/display"
+    autoload :Form, "pdfrb/document/form"
+    autoload :GraphicsState, "pdfrb/document/graphics_state"
+    autoload :Layers, "pdfrb/document/layers"
+    autoload :Portfolio, "pdfrb/document/portfolio"
+    autoload :Structure, "pdfrb/document/structure"
+    autoload :Shadings, "pdfrb/document/shadings"
+    autoload :OutputIntents, "pdfrb/document/output_intents"
+    autoload :Info, "pdfrb/document/info"
+    autoload :PageLabels, "pdfrb/document/page_labels"
+    autoload :Stamps, "pdfrb/document/stamps"
 
     def initialize(io: nil, config: {})
+      Pdfrb::Model::Type.eager_load!
       @config = Configuration.new(config)
       @io = io
       @objects = {}        # oid -> Pdfrb::Model::Object (modified or new)
@@ -39,7 +51,7 @@ module Pdfrb
       end
     end
 
-    attr_reader :config, :io, :xref, :version
+    attr_reader :config, :io, :xref, :version, :next_oid
 
     def self.open(path, **opts)
       if block_given?
@@ -128,6 +140,53 @@ module Pdfrb
       @outline ||= Document::Outline.new(self)
     end
 
+    def structure; @structure ||= Document::Structure.new(self); end
+
+    def form; @form ||= Document::Form.new(self); end
+
+    def shadings; @shadings ||= Document::Shadings.new(self); end
+
+    def colors; @colors ||= Document::Colors.new(self); end
+
+    def graphics_state; @graphics_state ||= Document::GraphicsState.new(self); end
+
+    def layers; @layers ||= Document::Layers.new(self); end
+
+    def associated_files; @associated_files ||= Document::AssociatedFiles.new(self); end
+
+    def portfolio; @portfolio ||= Document::Portfolio.new(self); end
+
+    def output_intents; @output_intents ||= Document::OutputIntents.new(self); end
+
+    def page_labels; @page_labels ||= Document::PageLabels.new(self); end
+
+    def stamps; @stamps ||= Document::Stamps.new(self); end
+
+    def info; @info ||= Document::Info.new(self); end
+
+    def display; @display ||= Document::Display.new(self); end
+
+    def xmp
+      return @xmp if @xmp
+
+      packet = load_xmp_packet
+      return nil unless packet
+
+      title = metadata[:Title]
+      packet.title = title if title
+      author = metadata[:Author]
+      packet.author = author if author
+      @xmp = packet
+    end
+
+    def load_xmp_packet
+      Pdfrb::XMP::Packet.new
+    rescue LoadError
+      nil
+    end
+
+    def version=(v); @version = v.to_s; end
+
     def create_form_xobject(name: nil, bbox: nil, matrix: nil)
       FormXObject.new(self, name: name, bbox: bbox, matrix: matrix)
     end
@@ -139,13 +198,21 @@ module Pdfrb
       @objects[obj.oid] = obj
     end
 
+    # Drop a modified/new object from the in-memory table so it's no
+    # longer emitted by the writer. Used by Task::Optimize when a
+    # stream has been deduplicated against a canonical sibling.
+    # Returns the dropped object (or nil if not present).
+    def forget(oid)
+      @objects.delete(oid)
+    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)
+      target.close if path && io.nil? && target.is_a?(IO)
       self
     end
 
@@ -170,6 +237,8 @@ module Pdfrb
     # first (they shadow loaded ones), then every loaded entry the
     # xref knows about.
     def each_indirect_object
+      return enum_for(:each_indirect_object) unless block_given?
+
       seen = Set.new
       @objects.each_value do |obj|
         next unless obj.indirect?

data/lib/pdfrb/encryption/identity.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Encryption
+    module Identity
+      module_function
+
+      def encrypt(data, **_opts); data; end
+      def decrypt(data, **_opts); data; end
+      def key_length; 0; end
+    end
+  end
+end

data/lib/pdfrb/encryption/password_verification.rb

@@ -2,6 +2,7 @@
 
 require "digest/md5"
 require "digest/sha2"
+require "openssl"
 
 module Pdfrb
   module Encryption
@@ -20,8 +21,8 @@ module Pdfrb
 
       module_function
 
-      # Algorithm 2: derive the encryption key from a user password
-      # for revisions 2..4 (RC4 and AES-128).
+      # Algorithm 2 (revision 2..4, RC4 and AES-128 V4): derive the
+      # encryption key from a user password.
       def derive_key_rc4(password:, o_entry:, p_flags:, id0:,
                          revision:, key_length_bits:, encrypt_metadata: true)
         padded = pad_password(password)
@@ -40,12 +41,56 @@ module Pdfrb
         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"
+      # Algorithm 2.B / 8 (revision >= 5, AES-256, PDF 2.0): verify a
+      # user password by hashing password + 8-byte validation salt from
+      # /U[32..40]. Returns the 32-byte key on success, nil on mismatch.
+      def verify_user_password_v5(password:, u_entry:, validation_salt:)
+        hash = sha256_password_rounds(password: password.b, salt: validation_salt.b,
+                                      u_entry: u_entry.b)
+        hash.byteslice(0, 32) == u_entry.byteslice(0, 32) ? hash : nil
+      end
+
+      # Algorithm 2.B / 9: same for owner password. Owner password
+      # validation uses /O[0..32] + /U[0..48] in the hash chain.
+      def verify_owner_password_v5(password:, o_entry:, u_entry:,
+                                   validation_salt:)
+        hash = sha256_password_rounds(password: password.b, salt: validation_salt.b,
+                                      u_entry: u_entry.b, o_entry: o_entry.b)
+        hash.byteslice(0, 32) == o_entry.byteslice(0, 32) ? hash : nil
+      end
+
+      # Algorithm 2.B: the iterative SHA-256 hash loop (sha256 + 64 bytes
+      # of last output, XORed with input, repeated until the MSB of byte
+      # 0 is 0). Used for V5 password verification and key extraction.
+      def sha256_password_rounds(password:, salt:, u_entry: "", o_entry: nil)
+        input = password + salt + (o_entry ? o_entry.byteslice(0, 48) : u_entry.byteslice(0, 48))
+        hash = Digest::SHA256.digest(input)
+        round = 0
+        while hash.getbyte(0).nobits?(0x80)
+          round += 1
+          key = hash.byteslice(0, 16)
+          iv = hash.byteslice(16, 16)
+          cipher = OpenSSL::Cipher.new("aes-128-cbc")
+          cipher.encrypt
+          cipher.key = key
+          cipher.iv = iv
+          cipher.padding = 0
+          encrypted = cipher.update(input) + cipher.final
+          input = encrypted.bytes.zip(input.bytes).map { |a, b| a ^ b }.pack("C*")
+          hash = Digest::SHA256.digest(input)
+        end
+        hash
+      end
+      private_class_method :sha256_password_rounds
+
+      # Extract the validation salt (bytes 32..40) and key salt (40..48)
+      # from a /U or /O entry for V5.
+      def extract_v5_salts(entry)
+        bytes = entry.b
+        {
+          validation_salt: bytes.byteslice(32, 8) || "".b,
+          key_salt: bytes.byteslice(40, 8) || "".b,
+        }
       end
 
       # Algorithm 4 (R=2): build the /U entry.

data/lib/pdfrb/encryption/security_handler.rb

@@ -26,7 +26,7 @@ module Pdfrb
         return nil unless encrypt
 
         filter = encrypt[:Filter] || :Standard
-        klass = HANDLERS[filter.to_s] ||
+        klass = registry[filter.to_s] ||
                 raise(Pdfrb::EncryptionError, "unsupported /Filter #{filter.inspect}")
         handler = klass.new(document)
         handler.set_up_decryption(**decryption_opts)
@@ -50,15 +50,18 @@ module Pdfrb
         !@encrypt_dict.nil?
       end
 
-      HANDLERS = {}.freeze
-      private_constant :HANDLERS
-
       class << self
-        def registry; @registry ||= {}; end
+        def registry
+          @registry ||= {}
+        end
 
         def register(filter_name, klass)
           registry[filter_name.to_s] = klass
         end
+
+        def lookup(filter_name)
+          registry[filter_name.to_s]
+        end
       end
     end
   end