pdfrb 0.6.0 → 0.7.10

data/lib/pdfrb/conformance/tagged_pdf.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/BlockLength
+module Pdfrb
+  module Conformance
+    # Tagged PDF validation per ISO 32000-1 §14.8 (and ISO 32000-2
+    # §14.8). Tagged PDF is the foundation of PDF/UA and PDF/A-2a/3a;
+    # this rule set checks the structural requirements that any
+    # tagged PDF must satisfy, regardless of higher-level profile.
+    #
+    # This is intentionally a subset of PDF/UA. Use PdfUA for the
+    # full accessibility profile; use TaggedPdf for a baseline
+    # structural pass that doesn't require accessibility annotations
+    # (alt text, reading order).
+    module TaggedPdf
+      STANDARD_STRUCTURE_TYPES = %i[
+        Document Part Div Art Sect BlockQuote Caption TOC TOCI
+        Index NonStruct Private H H1 H2 H3 H4 H5 H6 P L LI Lbl LBody
+        Table TR TH TD THead TBody TFoot Caption Span Quote Note
+        Reference BibEntry Code Figure Formula Form
+      ].freeze
+
+      module_function
+
+      RULESET = RuleSet.new("TaggedPDF").tap do |rs|
+        rs.register(Rule.new(
+                      id: "tag-1",
+                      description: "/MarkInfo /Marked must be true",
+                      severity: :error,
+                      spec_clause: "ISO 32000-2 14.8.1",
+                      check: ->(doc) {
+                        mark_info = doc.catalog[:MarkInfo]
+                        mark_info = doc.object(mark_info) if mark_info.is_a?(Pdfrb::Model::Reference)
+                        next nil if mark_info && mark_info[:Marked] == true
+
+                        Violation.new(
+                          rule_id: "tag-1",
+                          message: "/MarkInfo /Marked true is required for tagged PDF",
+                          object: "Catalog",
+                          severity: :error,
+                          spec_clause: "ISO 32000-2 14.8.1"
+                        )
+                      }
+                    ))
+
+        rs.register(Rule.new(
+                      id: "tag-2",
+                      description: "/StructTreeRoot must be present",
+                      severity: :error,
+                      spec_clause: "ISO 32000-2 14.7.2",
+                      check: ->(doc) {
+                        next nil if doc.catalog[:StructTreeRoot]
+
+                        Violation.new(
+                          rule_id: "tag-2",
+                          message: "/StructTreeRoot required for tagged PDF",
+                          object: "Catalog",
+                          severity: :error,
+                          spec_clause: "ISO 32000-2 14.7.2"
+                        )
+                      }
+                    ))
+
+        rs.register(Rule.new(
+                      id: "tag-3",
+                      description: "Structure elements must use standard types",
+                      severity: :warning,
+                      spec_clause: "ISO 32000-2 14.8.4",
+                      check: ->(doc) {
+                        violations = []
+                        walk_structure(doc) do |elem|
+                          s = elem[:S]
+                          next if s.nil? || STANDARD_STRUCTURE_TYPES.include?(s.to_sym)
+
+                          violations << Violation.new(
+                            rule_id: "tag-3",
+                            message: "Non-standard structure type '#{s}' on element",
+                            object: "StructElem",
+                            severity: :warning,
+                            spec_clause: "ISO 32000-2 14.8.4"
+                          )
+                        end
+                        violations
+                      }
+                    ))
+
+        rs.register(Rule.new(
+                      id: "tag-4",
+                      description: "Figure elements should have /Alt or /ActualText",
+                      severity: :warning,
+                      spec_clause: "ISO 32000-2 14.9.2",
+                      check: ->(doc) {
+                        violations = []
+                        walk_structure(doc) do |elem|
+                          next unless elem[:S] == :Figure
+                          next if elem[:Alt] || elem[:ActualText]
+
+                          violations << Violation.new(
+                            rule_id: "tag-4",
+                            message: "Figure without /Alt or /ActualText",
+                            object: "StructElem/Figure",
+                            severity: :warning,
+                            spec_clause: "ISO 32000-2 14.9.2"
+                          )
+                        end
+                        violations
+                      }
+                    ))
+
+        rs.register(Rule.new(
+                      id: "tag-5",
+                      description: "Table structure should include rows",
+                      severity: :warning,
+                      spec_clause: "ISO 32000-2 14.8.5",
+                      check: ->(doc) {
+                        violations = []
+                        walk_structure(doc) do |elem|
+                          next unless elem[:S] == :Table
+
+                          kids = structure_kids(elem, doc)
+                          has_tr = kids.any? { |k| k[:S] == :TR }
+                          next if has_tr
+
+                          violations << Violation.new(
+                            rule_id: "tag-5",
+                            message: "Table has no TR child rows",
+                            object: "StructElem/Table",
+                            severity: :warning,
+                            spec_clause: "ISO 32000-2 14.8.5"
+                          )
+                        end
+                        violations
+                      }
+                    ))
+      end
+
+      def validate(document)
+        RULESET.validate(document)
+      end
+
+      # Walk the structure tree starting at /StructTreeRoot, yielding
+      # each element dict. Silently skips cycles and missing refs.
+      def walk_structure(document)
+        seen = ::Set.new
+        root_ref = document.catalog[:StructTreeRoot]
+        return unless root_ref
+
+        root = root_ref.is_a?(Pdfrb::Model::Reference) ? document.object(root_ref) : root_ref
+        return unless root
+
+        first_kids = structure_kids(root, document)
+        queue = first_kids.dup
+        until queue.empty?
+          elem = queue.shift
+          next unless elem
+          next if seen.include?(elem.object_id)
+
+          seen << elem.object_id
+          yield elem
+          queue.concat(structure_kids(elem, document))
+        end
+      end
+
+      def structure_kids(element, document)
+        kids = element[:K]
+        return [] unless kids
+
+        kids = kids.value if kids.is_a?(Pdfrb::Model::PdfArray)
+        kids = [kids] unless kids.is_a?(::Array)
+        kids.filter_map do |k|
+          next nil unless k.is_a?(Pdfrb::Model::Reference)
+
+          obj = document.object(k)
+          next nil unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+          obj
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/pdfrb/conformance.rb

@@ -7,8 +7,16 @@ module Pdfrb
     autoload :Violation, "pdfrb/conformance/rule"
     autoload :ValidationResult, "pdfrb/conformance/rule"
     autoload :PdfA, "pdfrb/conformance/pdf_a"
+    autoload :PdfA4Deep, "pdfrb/conformance/pdf_a4_deep"
     autoload :PdfUA, "pdfrb/conformance/pdf_ua"
+    autoload :PdfUA2Deep, "pdfrb/conformance/pdf_ua2_deep"
+    autoload :PdfUATaggingDeep, "pdfrb/conformance/pdf_ua_tagging_deep"
     autoload :PdfX, "pdfrb/conformance/pdf_x"
+    autoload :PdfVT, "pdfrb/conformance/pdf_vt"
+    autoload :Pdf2AF, "pdfrb/conformance/pdf_2_af"
+    autoload :Pades, "pdfrb/conformance/pades"
+    autoload :Ltv, "pdfrb/conformance/ltv"
+    autoload :TaggedPdf, "pdfrb/conformance/tagged_pdf"
     autoload :StructureElements, "pdfrb/conformance/structure_elements"
     autoload :VeraPdfBridge, "pdfrb/conformance/verapdf_bridge"
   end

data/lib/pdfrb/content/canvas.rb

@@ -68,6 +68,122 @@ module Pdfrb
         move_to(x1, y1).line_to(x2, y2)
       end
 
+      # Draw a connected polyline through +points+. Each point is
+      # [x, y]. If +close+ is true, append a close-path operator.
+      def polyline(points, close: false)
+        return self if points.empty?
+
+        first = points.first
+        move_to(first[0], first[1])
+        points.drop(1).each { |x, y| line_to(x, y) }
+        close_path if close
+        self
+      end
+
+      # Draw a closed polygon through +points+.
+      def polygon(points)
+        polyline(points, close: true)
+      end
+
+      # Approximate a circular arc from +start_angle+ to +end_angle+
+      # (radians) centered at (cx, cy) with +radius+. Uses 16-line
+      # segment approximation per full revolution.
+      def arc(cx, cy, radius, start_angle:, end_angle:, segments_per_rev: 16)
+        span = end_angle - start_angle
+        return self if span.abs < 1e-6
+
+        seg_count = [(segments_per_rev * span.abs / (2 * Math::PI)).ceil, 1].max
+        step = span / seg_count
+        seg_count.times do |i|
+          a0 = start_angle + (i * step)
+          a1 = a0 + step
+          x0 = cx + (radius * Math.cos(a0))
+          y0 = cy + (radius * Math.sin(a0))
+          x1 = cx + (radius * Math.cos(a1))
+          y1 = cy + (radius * Math.sin(a1))
+          i.zero? ? move_to(x0, y0) : line_to(x0, y0)
+          line_to(x1, y1)
+        end
+        self
+      end
+
+      # Full circle centered at (cx, cy) with +radius+.
+      def circle(cx, cy, radius)
+        arc(cx, cy, radius, start_angle: 0, end_angle: 2 * Math::PI)
+        close_path
+      end
+
+      # Ellipse centered at (cx, cy) with x/y radii (rx, ry).
+      # Built from a scaled circle.
+      def ellipse(cx, cy, rx, ry)
+        save_graphics_state do
+          translate(cx, cy)
+          concat(1, 0, 0, 1, 0, 0)
+          # Approximate ellipse by scaling a unit circle.
+          segments = 32
+          segments.times do |i|
+            a0 = (i / segments.to_f) * 2 * Math::PI
+            a1 = ((i + 1) / segments.to_f) * 2 * Math::PI
+            x0 = rx * Math.cos(a0)
+            y0 = ry * Math.sin(a0)
+            x1 = rx * Math.cos(a1)
+            y1 = ry * Math.sin(a1)
+            i.zero? ? move_to(x0, y0) : line_to(x0, y0)
+            line_to(x1, y1)
+          end
+          close_path
+        end
+        self
+      end
+
+      # Rectangle with rounded corners. +radius+ is the corner radius
+      # (a single value or 4-element [tl, tr, br, bl]).
+      def rounded_rectangle(x, y, width, height, radius)
+        radii = radius.is_a?(::Array) ? radius : [radius] * 4
+        tl, tr, br, bl = radii
+        # bottom edge
+        move_to(x + bl, y)
+        line_to(x + width - br, y)
+        corner(x + width - br, y, x + width, y + br)
+        line_to(x + width, y + height - tr)
+        corner(x + width, y + height - tr,
+               x + width - tr, y + height)
+        line_to(x + tl, y + height)
+        corner(x + tl, y + height, x, y + height - tl)
+        line_to(x, y + bl)
+        corner(x, y + bl, x + bl, y)
+        close_path
+        self
+      end
+
+      # Convenience alias matching HexaPDF's naming. Accepts either
+      # an Array (interpreted as the dash array, phase 0) or an
+      # [array, phase] pair.
+      def dash=(spec)
+        array, phase = case spec
+                       when ::Array
+                         if spec.first.is_a?(::Array)
+                           spec
+                         else
+                           [spec, 0]
+                         end
+                       else
+                         [[spec], 0]
+                       end
+        emit_op(Pdfrb::Content::Operator::DashPattern, array, phase)
+      end
+
+      # Draw a quarter-circle corner from (x0, y0) to (x1, y1) by
+      # multi-segment linear interpolation. Adequate for typical
+      # radii (< 30 pts); for larger radii use curve_to directly.
+      def corner(x0, y0, x1, y1)
+        segments = 6
+        segments.times do |i|
+          t = (i + 1) / segments.to_f
+          line_to(x0 + ((x1 - x0) * t), y0 + ((y1 - y0) * t))
+        end
+      end
+
       def curve_to(c1x, c1y, c2x, c2y, x, y)
         emit_op(Pdfrb::Content::Operator::CurveTo, c1x, c1y, c2x, c2y, x, y)
         self
@@ -214,6 +330,27 @@ module Pdfrb
         self
       end
 
+      # Emit an inline image (BI ... ID ... EI) directly into the
+      # content stream. Avoids the /Resources /XObject registration
+      # overhead for one-shot images. The +dict+ keys are the image
+      # header keys (/W, /H, /CS, /BPC, /F, etc.); +data+ is the
+      # encoded image bytes (raw, Flate-compressed, or DCT).
+      #
+      # @param dict [Hash{Symbol=>Object}] inline image header entries
+      #   (e.g. { W: 100, H: 100, CS: :RGB, BPC: 8, F: :DCTDecode }).
+      # @param data [String] raw image bytes (binary-encoded).
+      def inline_image(dict:, data:)
+        header = +"BI\n"
+        dict.each do |k, v|
+          header << @serializer.serialize(k) << " " << @serializer.serialize(v) << "\n"
+        end
+        header << "ID\n"
+        append(header)
+        append(data)
+        append("\nEI\n")
+        self
+      end
+
       def text(str, at:, font:, size:, char_spacing: nil, word_spacing: nil)
         @used_fonts[font] = size
         encoded = encode_for_font(str.to_s, font)

data/lib/pdfrb/content/operators/inline_image.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module Operator
+      # Inline image operators (s8.9.7). Inline images embed raw image
+      # data directly in the content stream, framed by BI ... ID ...
+      # EI. They're an alternative to /XObject /Image for one-shot
+      # images: smaller overhead per image, no /Resources entry
+      # needed, but the bytes live in the content stream so they
+      # can't be reused.
+      #
+      # The serialise path emits the BI dict, ID marker, raw bytes,
+      # and EI marker. The invoke path is intentionally a no-op; the
+      # content Parser handles BI/ID/EI as a single bounded block
+      # rather than via the operator dispatch table.
+      class BeginInlineImage < Base
+        class << self
+          def name; "BI"; end
+
+          def serialize(serializer, **dict)
+            buf = +"BI\n"
+            dict.each do |k, v|
+              buf << serializer.serialize(k) << " " << serializer.serialize(v) << "\n"
+            end
+            buf << "ID\n"
+            buf
+          end
+
+          def invoke(_processor, *_operands); end
+          register
+        end
+      end
+
+      class EndInlineImage < Base
+        class << self
+          def name; "EI"; end
+
+          # The byte payload sits between ID and EI. The serializer
+          # for inline images writes the payload directly via
+          # Canvas#inline_image; this method is here so the registry
+          # knows about EI.
+          def serialize(_serializer, *_operands)
+            "EI\n"
+          end
+
+          def invoke(_processor, *_operands); end
+          register
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/operators.rb

@@ -16,6 +16,7 @@ module Pdfrb
       autoload :GraphicsStateParams, "pdfrb/content/operators/graphics_state_params"
       autoload :MarkedContent, "pdfrb/content/operators/marked_content"
       autoload :Clipping, "pdfrb/content/operators/clipping"
+      autoload :InlineImage, "pdfrb/content/operators/inline_image"
     end
   end
 end

data/lib/pdfrb/content/parser.rb

@@ -23,11 +23,21 @@ module Pdfrb
 
       # Yields (operator_class, operands) pairs. Returns an Enumerator
       # if no block.
+      #
+      # Special-cases the BI/ID/EI inline image sequence: when BI is
+      # seen, the inline image dict + raw byte payload are read as a
+      # single InlineImage invocation rather than as discrete tokens.
       def each_invocation
         return enum_for(:each_invocation) unless block_given?
 
         operands = []
         while (tok = tokenizer.next_token)
+          if tok.type == :keyword && tok.value == "BI"
+            yield Pdfrb::Content::Operator::BeginInlineImage, [parse_inline_image]
+            operands = []
+            next
+          end
+
           case tok.type
           when :keyword
             op = Pdfrb::Content::Operator[tok.value]
@@ -48,6 +58,78 @@ module Pdfrb
         self
       end
 
+      # Parse a BI ... ID <bytes> EI inline image sequence. The BI
+      # keyword has already been consumed; the next tokens form the
+      # image header (key/value pairs), then ID introduces the raw
+      # byte payload terminated by EI.
+      #
+      # Returns a Hash with :header (the key-value pairs) and
+      # :data (the raw image bytes).
+      def parse_inline_image
+        header = {}
+        # Read header pairs until we hit the ID keyword.
+        while (tok = tokenizer.next_token)
+          break if tok.type == :keyword && tok.value == "ID"
+
+          if tok.type == :name
+            key = abbrev_for(tok.value) || tok.value.to_sym
+            val_tok = tokenizer.next_token
+            header[key] = token_value(val_tok)
+          end
+        end
+
+        # After ID, exactly one whitespace byte separates the
+        # keyword from the data. Read raw bytes until "\nEI" or
+        # " EI" terminator.
+        data = read_inline_image_data
+        { header: header, data: data }
+      end
+
+      # Map inline-image abbreviation keys to full PDF names per
+      # ISO 32000-2 §8.9.7 Table 89.
+      def abbrev_for(name)
+        ABBREV_TABLE[name.to_sym]
+      end
+
+      ABBREV_TABLE = {
+        BPC: :BitsPerComponent,
+        CS: :ColorSpace,
+        D: :Decode,
+        DP: :DecodeParms,
+        F: :Filter,
+        H: :Height,
+        IM: :ImageMask,
+        Intent: :Intent,
+        I: :Interpolate,
+        W: :Width,
+      }.freeze
+
+      def read_inline_image_data
+        # Skip exactly one whitespace byte after ID.
+        tokenizer.skip_whitespace
+        bytes = +"".b
+        # Read until we see the "EI" marker. The marker is usually
+        # preceded by whitespace and followed by whitespace or EOF.
+        until tokenizer.eof?
+          b = tokenizer.read_byte
+          break if b.nil?
+
+          bytes << b
+          if bytes.bytesize >= 3 &&
+              whitespace_byte?(bytes.getbyte(-3)) &&
+              bytes.byteslice(-2, 2) == "EI"
+            return bytes.byteslice(0, bytes.bytesize - 3).b
+          end
+        end
+        bytes.b
+      end
+
+      WHITESPACE_BYTE_VALUES = [0, 9, 10, 12, 13, 32].freeze
+
+      def whitespace_byte?(byte)
+        WHITESPACE_BYTE_VALUES.include?(byte)
+      end
+
       private
 
       def consume_array

data/lib/pdfrb/digital_signature/timestamp_client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "net/https"
+require "uri"
+
+module Pdfrb
+  module DigitalSignature
+    # RFC 3161 trusted timestamp client. Submits a hash to a Time
+    # Stamp Authority (TSA) over HTTPS and returns the resulting
+    # timestamp token (TSTInfo) as DER bytes, suitable for inclusion
+    # in a PAdES B-T/LTA signature.
+    #
+    # Pure-Ruby: uses Net::HTTP with OpenSSL. The TSA URL is
+    # configurable; defaults to a free public TSA. Callers in
+    # production should configure a trusted TSA endpoint.
+    module TimestampClient
+      DEFAULT_TSA_URL = "https://freetsa.org/tsr"
+      DEFAULT_HASH_ALGORITHM = "sha256"
+
+      module_function
+
+      # Submit +data+ (or its digest) to the TSA at +url+ and return
+      # the DER-encoded TimeStampResp.
+      #
+      # @param data [String] the bytes to timestamp.
+      # @param url [String] TSA endpoint URL.
+      # @param hash_algorithm [String] OpenSSL digest name.
+      # @param cert [OpenSSL::X509::Certificate, nil] client cert.
+      # @param key [OpenSSL::PKey::RSA, nil] client key.
+      # @return [String] DER-encoded TimeStampResp bytes.
+      def request_timestamp(data:, url: DEFAULT_TSA_URL,
+                            hash_algorithm: DEFAULT_HASH_ALGORITHM,
+                            cert: nil, key: nil)
+        digest = OpenSSL::Digest.new(hash_algorithm)
+        hashed = digest.digest(data)
+        req = build_tsq_request(hashed, hash_algorithm)
+        https_post(url, req, cert: cert, key: key)
+      end
+
+      DIGEST_OIDS = {
+        "sha1" => "1.3.14.3.2.26",
+        "sha256" => "2.16.840.1.101.3.4.2.1",
+        "sha384" => "2.16.840.1.101.3.4.2.2",
+        "sha512" => "2.16.840.1.101.3.4.2.3",
+      }.freeze
+
+      # Build the TimeStampReq DER. Pure OpenSSL::ASN1 construction.
+      def build_tsq_request(hashed_bytes, hash_algorithm)
+        oid = DIGEST_OIDS[hash_algorithm.to_s] || DIGEST_OIDS["sha256"]
+        OpenSSL::ASN1::Sequence.new([
+                                      OpenSSL::ASN1::Integer.new(1), # version
+                                      OpenSSL::ASN1::Sequence.new([ # messageImprint
+                                                                    OpenSSL::ASN1::Sequence.new([
+                                                                                                  OpenSSL::ASN1::ObjectId.new(oid),
+                                                                                                  OpenSSL::ASN1::Null.new(nil),
+                                                                                                ]),
+                                                                    OpenSSL::ASN1::OctetString.new(hashed_bytes),
+                                                                  ]),
+                                      OpenSSL::ASN1::Boolean.new(true), # reqCert
+                                    ]).to_der
+      end
+
+      def https_post(url, body, cert: nil, key: nil)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true if uri.is_a?(URI::HTTPS)
+        http.ssl_timeout = 30
+
+        if cert && key
+          http.cert = cert
+          http.key = key
+        end
+
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req["Content-Type"] = "application/timestamp-query"
+        req.body = body
+
+        response = http.request(req)
+        raise "TSA error: #{response.code} #{response.message}" unless response.code == "200"
+
+        response.body
+      end
+    end
+  end
+end

data/lib/pdfrb/digital_signature.rb

@@ -11,6 +11,7 @@ module Pdfrb
     autoload :VerificationResult, "pdfrb/digital_signature/verification_result"
     autoload :CmsHandler, "pdfrb/digital_signature/cms_handler"
     autoload :TimestampHandler, "pdfrb/digital_signature/timestamp_handler"
+    autoload :TimestampClient, "pdfrb/digital_signature/timestamp_client"
 
     HANDLERS = {
       "adbe.pkcs7.detached": CmsHandler,

data/lib/pdfrb/document.rb

@@ -43,6 +43,7 @@ module Pdfrb
       @object_reader = nil
       @version = "1.4"
       @empty_trailer = nil
+      @revisions = []      # array of [xref, trailer] tuples, latest first
 
       if io
         read_from_io(io)
@@ -259,6 +260,29 @@ module Pdfrb
       end
     end
 
+    # Walk every revision in the document's incremental-update chain,
+    # from the latest (most recent) revision backward via /Prev.
+    # Each revision yields a (revision_index, xref, trailer) tuple
+    # where revision_index 0 is the latest. Documents without
+    # incremental updates yield a single tuple.
+    #
+    # Useful for forensic inspection, version-aware rendering, and
+    # debugging "ghost" objects that were modified in a later
+    # revision.
+    def each_revision
+      return enum_for(:each_revision) unless block_given?
+
+      return (yield 0, @xref, trailer) if @revisions.empty? && @xref
+
+      @revisions.each_with_index { |(xref, tr), i| yield i, xref, tr }
+    end
+
+    # Number of revisions in the document. 1 for a freshly written
+    # PDF; >1 for incrementally-updated PDFs.
+    def revision_count
+      @revisions.empty? ? 1 : @revisions.length
+    end
+
     private
 
     def allocate_oid
@@ -285,6 +309,10 @@ module Pdfrb
       xref, trailer = load_single_xref(io, sxref)
       return [nil, nil] unless xref && trailer
 
+      # Track each revision's xref + trailer so callers can walk the
+      # history (Document#each_revision).
+      @revisions = [[xref, trailer]]
+
       # Follow /Prev chain for incremental updates. Earlier entries
       # fill gaps; later entries take precedence (already in xref).
       prev_offset = trailer[:Prev]
@@ -292,6 +320,7 @@ module Pdfrb
         prev_xref, prev_trailer = load_single_xref(io, prev_offset)
         break unless prev_xref
 
+        @revisions << [prev_xref, prev_trailer]
         xref.merge!(prev_xref)
         prev_offset = prev_trailer && prev_trailer[:Prev]
       end