stationery 0.8.0 → 0.10.0

data/lib/stationery/pdf/signature.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # A digital signature over the whole file, as PAdES baseline B-B asks for
+    # it: a signature dictionary with `/SubFilter /ETSI.CAdES.detached` whose
+    # /Contents is a detached CMS over every byte but itself (see CMS).
+    #
+    # The file is written once with room for the signature (`contents_size:`
+    # bytes) and a placeholder /ByteRange; #apply then fills both in place, so
+    # no offset moves. `timestamp:` adds a time-stamping authority's token to
+    # the signature (PAdES baseline B-T, see Timestamp). Long-term validation
+    # data and a second signature need incremental updates, which Stationery
+    # does not write.
+    #
+    # OpenSSL is loaded when the first signature is made, never before.
+    class Signature
+      SUBFILTER = :"ETSI.CAdES.detached"
+      CONTENTS_SIZE = 8192
+      # A timestamp token brings the TSA's certificate chain along.
+      TIMESTAMPED_CONTENTS_SIZE = 16_384
+      BYTE_RANGE = "[0 0000000000 0000000000 0000000000]"
+      OPTIONS = %i[certificate key chain passphrase reason location contact name field at contents_size
+                   timestamp].freeze
+      # Options a Symbol names a document method for; elsewhere it is a value.
+      SECRETS = %i[certificate key chain passphrase].freeze
+      # Print and Locked: the widget of a signature that fills no field.
+      INVISIBLE = 132
+
+      attr_reader :certificate, :key, :chain, :field, :at, :contents_size, :timestamp
+
+      class << self
+        # The signature for `spec` (the options of `sign` and `to_pdf(sign:)`,
+        # or a block answering them) resolved for `document`; nil without one.
+        def for(spec, document)
+          return unless spec
+
+          spec = resolve(spec, document) if spec.respond_to?(:call)
+          spec = check(spec).to_h { |name, value| [name, resolve(value, document, method: SECRETS.include?(name))] }
+          new(**spec)
+        end
+
+        # The options with Symbol keys; an unknown one raises.
+        def check(spec)
+          spec = spec.to_h.transform_keys(&:to_sym)
+          unknown = spec.keys - OPTIONS
+          return spec if unknown.empty?
+
+          raise ArgumentError, "unknown sign option: #{unknown.join(", ")} (use #{OPTIONS.join(", ")})"
+        end
+
+        # Whether any of the options is only known when a document renders.
+        def deferred?(spec)
+          spec.any? { |name, value| value.respond_to?(:call) || (SECRETS.include?(name) && value.is_a?(Symbol)) }
+        end
+
+        # The first DER object in `bytes`: a signature's /Contents without the
+        # zeros that pad it.
+        def der(bytes)
+          length = bytes.getbyte(1).to_i
+          return bytes.byteslice(0, 2 + length) if length < 0x80
+
+          size = length & 0x7F
+          content = bytes.byteslice(2, size).unpack("C*").inject(0) { |sum, byte| (sum << 8) | byte }
+          bytes.byteslice(0, 2 + size + content)
+        end
+
+        private
+
+        def resolve(value, document, method: false)
+          case value
+          when Symbol then method ? document.send(value) : value
+          when Proc then value.arity.zero? ? document.instance_exec(&value) : value.call(document)
+          else value.respond_to?(:call) ? value.call(document) : value
+          end
+        end
+      end
+
+      def initialize(certificate: nil, key: nil, chain: [], passphrase: nil, field: nil, at: Time.now,
+                     contents_size: nil, timestamp: nil, **details)
+        require "openssl"
+        @certificate = certificate_for(certificate, "certificate:")
+        @key = key_for(key, passphrase)
+        @chain = Array(chain).map { |link| certificate_for(link, "chain:") }
+        @field = field&.to_s
+        @at = at
+        @timestamp = Timestamp.for(timestamp)
+        @contents_size = contents_size || (@timestamp ? TIMESTAMPED_CONTENTS_SIZE : CONTENTS_SIZE)
+        @details = self.class.check(details)
+        match!
+      end
+
+      # Whether it adds its own field, a widget nobody sees, to the first page.
+      def invisible? = @field.nil?
+
+      # The signer's name: `name:`, else the certificate's common name.
+      def name
+        @details[:name] || @certificate.subject.to_utf8[/(?:\A|,)CN=((?:\\.|[^,])*)/, 1]&.gsub(/\\(.)/, '\1')
+      end
+
+      # The signature dictionary, with placeholders #apply fills in. Its
+      # /Contents and /ByteRange are written as they are, never encrypted.
+      def dictionary
+        entries = { Type: :Sig, Filter: :"Adobe.PPKLite", SubFilter: SUBFILTER,
+                    ByteRange: Verbatim.new(BYTE_RANGE), Contents: Verbatim.new(placeholder),
+                    M: TextString.new(@at.utc.strftime("D:%Y%m%d%H%M%SZ")) }
+        text = { Name: name, Reason: @details[:reason], Location: @details[:location],
+                 ContactInfo: @details[:contact] }.compact
+        entries.merge(text.transform_values { |value| TextString.new(value.to_s) })
+      end
+
+      # Signs `pdf` (the file as written with #dictionary in it): fills in the
+      # byte range and the signature over it, and answers the same String.
+      def apply(pdf)
+        range, first, last = gap(pdf)
+        pdf.bytesplice(range, BYTE_RANGE.bytesize,
+                       "[0 #{first} #{last} #{pdf.bytesize - last}]".ljust(BYTE_RANGE.bytesize))
+        signed = pdf.byteslice(0, first) + pdf.byteslice(last..)
+        signature = CMS.new(@certificate, @key, @chain).sign(signed, timestamp: @timestamp&.method(:token))
+        raise ArgumentError, too_large(signature) if signature.bytesize > @contents_size
+
+        pdf.bytesplice(first + 1, @contents_size * 2, signature.unpack1("H*").upcase.ljust(@contents_size * 2, "0"))
+        pdf
+      end
+
+      private
+
+      def placeholder = "<#{"0" * (@contents_size * 2)}>"
+
+      # Where the byte range is written, and where the /Contents string
+      # starts and ends: the gap the signature does not cover.
+      def gap(pdf)
+        range = pdf.index("/ByteRange #{BYTE_RANGE}")
+        contents = range && pdf.index("/Contents #{placeholder}", range)
+        raise Error, "the signature dictionary is not in the file" unless contents
+
+        first = contents + "/Contents ".bytesize
+        [range + "/ByteRange ".bytesize, first, first + placeholder.bytesize]
+      end
+
+      def too_large(signature)
+        what = @timestamp ? "the signature and its timestamp take" : "the signature takes"
+        "#{what} #{signature.bytesize} bytes, more than contents_size: #{@contents_size} leaves for it; " \
+          "pass a larger contents_size:"
+      end
+
+      def certificate_for(value, option)
+        return value if value.is_a?(OpenSSL::X509::Certificate)
+
+        OpenSSL::X509::Certificate.new(value.to_s)
+      rescue OpenSSL::X509::CertificateError
+        raise ArgumentError, "sign #{option} needs an OpenSSL::X509::Certificate or its PEM, #{got(value)}"
+      end
+
+      def key_for(value, passphrase)
+        key = value.is_a?(OpenSSL::PKey::PKey) ? value : OpenSSL::PKey.read(value.to_s, passphrase.to_s)
+        return key if key.is_a?(OpenSSL::PKey::RSA) || key.is_a?(OpenSSL::PKey::EC)
+
+        raise ArgumentError, "sign key: needs an RSA or EC key, got #{key.class}"
+      rescue OpenSSL::PKey::PKeyError
+        raise ArgumentError, "sign key: needs an OpenSSL::PKey or its PEM (with passphrase: when encrypted), " \
+                             "#{got(value)}"
+      end
+
+      def got(value) = value.nil? ? "got nil" : "got a #{value.class}"
+
+      def match!
+        return if @key.private? && @certificate.check_private_key(@key)
+
+        raise ArgumentError, "sign key: is not the private key of certificate: (#{@certificate.subject.to_utf8})"
+      end
+    end
+  end
+end

data/lib/stationery/pdf/types.rb

@@ -11,5 +11,9 @@ module Stationery
     # A human-readable string (document info, outline titles): written as a
     # literal when ASCII, as UTF-16BE with a byte order mark otherwise.
     TextString = Data.define(:value)
+
+    # PDF syntax written as it is and never encrypted: a signature's /Contents
+    # and /ByteRange, which are filled in once the file is written.
+    Verbatim = Data.define(:source)
   end
 end

data/lib/stationery/pdf/writer.rb

@@ -5,15 +5,26 @@ require "digest/md5"
 module Stationery
   module PDF
     # Collects numbered objects and writes them as a PDF file with a classic
-    # cross-reference table.
+    # cross-reference table. `render` returns the file as a String with the
+    # objects in numbered order. With a `sink:` (anything answering
+    # `call(bytes)`) the file goes there in pieces instead: `flush` writes every
+    # object set so far and drops it, so objects leave in the order they were
+    # flushed and the first bytes leave before the last page is assembled.
     class Writer
       HEADER = "%PDF-1.7\n%\xE2\xE3\xCF\xD3\n".b
+      WRITTEN = Object.new.freeze
 
       # `encryption` (an Encryption::StandardSecurity) encrypts every string
       # and stream except those of its own /Encrypt dictionary.
-      def initialize(encryption: nil)
+      def initialize(encryption: nil, sink: nil)
         @objects = []
+        @offsets = []
         @encryption = encryption
+        @sink = sink
+        @buffer = HEADER.dup unless sink
+        @size = HEADER.bytesize
+        @digest = Digest::MD5.new if sink && !encryption
+        announce(HEADER) if sink
       end
 
       # Hands out a reference now and lets the object be set later, so a page
@@ -24,6 +35,8 @@ module Stationery
       end
 
       def set(ref, value)
+        raise Error, "object #{ref.id} is already written" if @objects[ref.id - 1].equal?(WRITTEN)
+
         @objects[ref.id - 1] = value
         ref
       end
@@ -32,43 +45,84 @@ module Stationery
         set(reserve, value)
       end
 
+      # With a sink: writes every object set and not yet written, lowest number
+      # first, and drops it. References to objects still unset stay valid, as
+      # the cross-reference table is written last. Without a sink it does
+      # nothing: the String keeps its objects in numbered order.
+      def flush
+        return unless @sink
+
+        @encrypt ||= reserve if @encryption
+        write_pending
+      end
+
+      # Finishes the file: the remaining objects, the cross-reference table
+      # and the trailer. Returns the whole file as a String when there is no
+      # sink, else the number of bytes handed to it.
       def render(root:, info:)
+        set(@encrypt ||= reserve, @encryption.dictionary) if @encryption
         if (missing = @objects.index(nil))
           raise Error, "object #{missing + 1} reserved but never set"
         end
 
-        @encrypt = @encryption && add(@encryption.dictionary)
-        out = HEADER.dup
-        offsets = @objects.each_with_index.map { |object, index| write_object(out, index + 1, object) }
-        xref = out.bytesize
-        id = HexString.new(@encryption ? @encryption.file_id : Digest::MD5.digest(out))
+        write_pending
+        xref = @size
+        id = HexString.new(file_id)
 
-        out << "xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n"
-        offsets.each { |offset| out << format("%010d 00000 n \n", offset) }
-        out << "trailer\n" << Serializer.dump(trailer(root, info, id))
-        out << "\nstartxref\n#{xref}\n%%EOF\n"
+        emit("xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n")
+        @offsets.each { |offset| emit(format("%010d 00000 n \n", offset)) }
+        emit("trailer\n#{Serializer.dump(trailer(root, info, id))}")
+        emit("\nstartxref\n#{xref}\n%%EOF\n")
+        @buffer || @size
       end
 
       private
 
+      def write_pending
+        @objects.each_with_index do |object, index|
+          next if object.nil? || object.equal?(WRITTEN)
+
+          write_object(index + 1, object)
+          @objects[index] = WRITTEN
+        end
+      end
+
       def trailer(root, info, id)
         trailer = { Size: @objects.size + 1, Root: root, Info: info, ID: [id, id] }
         @encrypt ? trailer.merge(Encrypt: @encrypt) : trailer
       end
 
-      def write_object(out, number, object)
-        offset = out.bytesize
+      def write_object(number, object)
+        @offsets[number - 1] = @size
         crypt = crypt_for(number)
-        out << "#{number} 0 obj\n"
+        emit("#{number} 0 obj\n")
         if object.is_a?(Stream)
           data = crypt ? crypt.call(object.data) : object.data
-          out << Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt)
-          out << "\nstream\n" << data << "\nendstream"
+          emit(Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt))
+          emit("\nstream\n")
+          emit(data)
+          emit("\nendstream")
         else
-          out << Serializer.dump(object, crypt)
+          emit(Serializer.dump(object, crypt))
         end
-        out << "\nendobj\n"
-        offset
+        emit("\nendobj\n")
+      end
+
+      def emit(bytes)
+        @size += bytes.bytesize
+        @sink ? announce(bytes) : @buffer << bytes
+      end
+
+      def announce(bytes)
+        @digest&.update(bytes)
+        @sink.call(bytes)
+      end
+
+      # The encryption's own identifier, else a digest of the file so far.
+      def file_id
+        return @encryption.file_id if @encryption
+
+        @digest ? @digest.digest : Digest::MD5.digest(@buffer)
       end
 
       # The Serializer hook: encrypts a string or stream with this object's key.

data/lib/stationery/rich/nesting.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    # How deep one html or markdown source may nest, and how deep it went.
+    # Parsing, layout and painting all recurse over the nesting, so a parser
+    # flattens what lies deeper than `limit` into the deepest element it kept
+    # (text stays, structure goes) and records the depth it saw here.
+    class Nesting
+      DEFAULT = 64
+
+      attr_reader :limit, :deepest
+
+      def initialize(limit = DEFAULT)
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError, "max_depth must be a positive Integer (got #{limit.inspect})"
+        end
+
+        @limit = limit
+        @deepest = 0
+      end
+
+      def record(depth)
+        @deepest = depth if depth > @deepest
+      end
+
+      def exceeded? = @deepest > @limit
+    end
+  end
+end

data/lib/stationery/rich/nodes.rb

@@ -4,7 +4,9 @@ module Stationery
   # The block model rich-text parsers (HTML, Markdown) produce and elements render.
   module Rich
     # A run of text with its marks: any of bold:, italic:, underline:, strike:, code:, link: (href),
-    # script: (:sub/:sup) and break: true, a hard line break whose text is "".
+    # script: (:sub/:sup), color: (a colour), size: (points), scale: (a factor of the text size)
+    # and break: true, a hard line break whose text is "". A false bold:, italic:, underline: or
+    # strike: switches the mark off inside an element that has it.
     Inline = Data.define(:text, :marks) do
       def self.break = new(text: "", marks: { break: true })
 
@@ -12,15 +14,39 @@ module Stationery
       def break? = marks[:break] == true
     end
 
-    Paragraph = Data.define(:inlines)
-    Heading = Data.define(:level, :inlines)
-    List = Data.define(:ordered, :start, :items)
-    Blockquote = Data.define(:blocks)
-    CodeBlock = Data.define(:text, :language)
+    # Every block carries a `style` Hash from the source's CSS (see HTML::Css):
+    # align:, background:, padding:, margin:/margin_top:/margin_bottom:,
+    # border:, width:, break_before:, break_after:, keep_together:. Empty
+    # for Markdown and for HTML without styles.
+    Paragraph = Data.define(:inlines, :style) do
+      def initialize(inlines:, style: {}) = super
+    end
+    Heading = Data.define(:level, :inlines, :style) do
+      def initialize(level:, inlines:, style: {}) = super
+    end
+    List = Data.define(:ordered, :start, :items, :style) do
+      def initialize(ordered:, start:, items:, style: {}) = super
+    end
+    Blockquote = Data.define(:blocks, :style) do
+      def initialize(blocks:, style: {}) = super
+    end
+    CodeBlock = Data.define(:text, :language, :style) do
+      def initialize(text:, language:, style: {}) = super
+    end
     Rule = Data.define
-    Table = Data.define(:rows)
-    Cell = Data.define(:header, :align, :blocks)
-    Image = Data.define(:src, :alt, :width, :height)
+    Table = Data.define(:rows, :style) do
+      def initialize(rows:, style: {}) = super
+    end
+    Cell = Data.define(:header, :align, :blocks, :style) do
+      def initialize(header:, align:, blocks:, style: {}) = super
+    end
+    Image = Data.define(:src, :alt, :width, :height, :style) do
+      def initialize(src:, alt:, width:, height:, style: {}) = super
+    end
+    # A styled container (a `div` with a background, padding, margins or a
+    # page-break rule) holding blocks; an unstyled one flattens into its parent.
+    Container = Data.define(:blocks, :style)
+    PageBreak = Data.define
 
     # Operations on inline sequences shared by the parsers.
     module Inlines
@@ -42,12 +68,12 @@ module Stationery
       end
 
       # Groups inlines into paragraphs, with each image standing as a block between them.
-      def paragraphs(items)
+      def paragraphs(items, style: {})
         items.chunk_while { |a, b| !a.is_a?(Image) && !b.is_a?(Image) }.filter_map do |run|
           next run.first if run.first.is_a?(Image)
 
           inlines = merge(block_given? ? yield(run) : run)
-          Paragraph.new(inlines:) unless inlines.empty?
+          Paragraph.new(inlines:, style:) unless inlines.empty?
         end
       end
     end

data/lib/stationery/rich/renderer/boxes.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # What a block's CSS style becomes around the block: margins as spacers,
+      # a background and padding as a box, page-break rules as page breaks and
+      # kept-together groups, borders and widths as table options.
+      module Boxes
+        PADDING = { padding_top: 0, padding_right: 1, padding_bottom: 2, padding_left: 3 }.freeze
+
+        private
+
+        # Draws the block inside its margins and its box. A block styled with
+        # nothing but an alignment draws as it is.
+        def styled(style, &)
+          return yield if style.empty?
+
+          spaced(style) { boxed(style, &) }
+        end
+
+        # Page breaks and margins around the block, and the rule that keeps it
+        # on one page.
+        def spaced(style)
+          return yield unless spacing?(style)
+
+          top, bottom = margins(style)
+          @component.page_break if style[:break_before]
+          @component.group(keep_together: style[:keep_together] == true) do
+            @component.spacer(top) if top.positive?
+            yield
+            @component.spacer(bottom) if bottom.positive?
+          end
+          @component.page_break if style[:break_after]
+        end
+
+        def spacing?(style)
+          style[:break_before] || style[:break_after] || style[:keep_together] || margins(style).any?(&:positive?)
+        end
+
+        def margins(style)
+          all = style[:margin]
+          [style[:margin_top] || all&.[](0) || 0, style[:margin_bottom] || all&.[](2) || 0]
+        end
+
+        def boxed(style, &)
+          options = box_options(style)
+          options.empty? ? yield : @component.box(**options, &)
+        end
+
+        # The background and padding a style gives a box, to merge over a
+        # block's own (`styles[:blockquote]`, `styles[:pre]`).
+        def box_options(style)
+          options = {}
+          options[:background] = style[:background] if style[:background]
+          padding = padding_of(style)
+          options[:padding] = padding if padding
+          options
+        end
+
+        def padding_of(style)
+          sides = PADDING.select { |key, _| style[key] }
+          return style[:padding] if sides.empty?
+
+          padding = (style[:padding] || [0, 0, 0, 0]).dup
+          sides.each { |key, index| padding[index] = style[key] }
+          padding
+        end
+
+        def aligned(style) = style[:align] ? { align: style[:align] } : {}
+
+        def border_options(border)
+          return {} unless border
+          return { borders: [] } if border[:width].zero?
+
+          { border_width: border[:width], border_color: border[:color] }
+        end
+
+        def cell_options(style)
+          options = border_options(style[:border]).merge(box_options(style))
+          options[:borders] = %i[top right bottom left] if options[:border_width]
+          options
+        end
+
+        # Column widths from the first row, when every cell of it has one. A
+        # percentage is a share of the table, which then takes the full width
+        # unless it has a width of its own.
+        def column_widths(table)
+          widths = table.rows.first.map { |cell| cell.style[:width] }
+          return {} unless widths.all?
+
+          widths.any? { |width| fraction?(width) } && !table.style[:width] ? { widths:, width: :full } : { widths: }
+        end
+
+        # A table's own width: points, the full width for 100%, or a share of
+        # the space through a box of that width.
+        def sized(width)
+          return yield({}) unless width
+          return yield({ width: }) unless fraction?(width)
+          return yield({ width: :full }) if width >= 1
+
+          @component.box(width:) { yield({ width: :full }) }
+        end
+
+        def fraction?(value) = value.is_a?(Float) && value <= 1
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer/indents.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # Block quotes and lists each indent what they hold, so nested deep
+      # enough they leave their text no width and it is lost. Past LIMIT
+      # levels the content is drawn where the last indented level put it:
+      # a block quote without its bar, list items without their markers.
+      module Indents
+        LIMIT = 12
+
+        private
+
+        def indented(block)
+          return flat(block) if @indents >= LIMIT
+
+          @indents += 1
+          begin
+            yield
+          ensure
+            @indents -= 1
+          end
+        end
+
+        def flat(block) = group(block.is_a?(List) ? block.items.flatten(1) : block.blocks)
+
+        # How many block quotes and lists deep the blocks go.
+        def indents_of(blocks)
+          blocks.map do |block|
+            case block
+            when Blockquote then 1 + indents_of(block.blocks)
+            when Container then indents_of(block.blocks)
+            when List then 1 + (block.items.map { |item| indents_of(item) }.max || 0)
+            when Table then block.rows.flatten.map { |cell| indents_of(cell.blocks) }.max || 0
+            else 0
+            end
+          end.max || 0
+        end
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer/inlines.rb

@@ -15,8 +15,12 @@ module Stationery
           font: ->(value) { [:font, value] if value }
         }.freeze
 
+        # A true mark switches the style on, a false one (from CSS) switches it off again.
         MARK_STEPS = {
-          bold: [[:b]], italic: [[:i]], underline: [[:u]], strike: [[:strikethrough]]
+          bold: { true => [[:b]], false => [[:with, { weight: :regular }]] },
+          italic: { true => [[:i]], false => [[:with, { style: :normal }]] },
+          underline: { true => [[:u]], false => [[:with, { underline: false }]] },
+          strike: { true => [[:strikethrough]], false => [[:with, { strikethrough: false }]] }
         }.freeze
 
         def initialize(runs, styles, links = Links.new(:all, nil))
@@ -50,7 +54,10 @@ module Stationery
           when :link then [[:link, value], *style_steps(@styles[:a])]
           when :code then style_steps(@styles[:code])
           when :script then [[value]]
-          else MARK_STEPS.fetch(mark, [])
+          when :color then [[:color, value]]
+          when :size then [[:size, value]]
+          when :scale then [[:scale, value]]
+          else MARK_STEPS.dig(mark, value) || []
           end
         end