stationery 0.8.0 → 0.9.0

data/lib/stationery/pdf/assembler.rb

@@ -10,12 +10,14 @@ module Stationery
       # PDF::Attachment files to embed; `xmp:` (true) writes the XMP packet,
       # with `xmp_extensions:` as further schemas and `xmp_schemas:` describing
       # them to PDF/A (see XMP); `conformance:` (a PDF::Conformance) adds what
-      # PDF/A and PDF/UA ask of the file.
+      # PDF/A and PDF/UA ask of the file; `signature:` (a PDF::Signature)
+      # signs it.
       def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil,
                      page_labels: nil, attachments: [], xmp: true, xmp_extensions: {}, xmp_schemas: [],
-                     conformance: nil)
+                     conformance: nil, signature: nil)
         @xmp_schemas = xmp_schemas
         @conformance = conformance
+        @signature = signature
         @tagging = tagging
         @lang = lang
         @page_labels = page_labels
@@ -31,9 +33,10 @@ module Stationery
 
       def render
         writer = Writer.new(encryption: @encryption)
-        @form = Forms::AcroForm.new(writer)
         tree = writer.reserve
         refs = @resources.build(writer)
+        @form = Forms::AcroForm.new(writer, fonts: refs.fetch(:Font), signature: @signature,
+                                            need_appearances: @conformance.nil? && @signature.nil?)
         kids = @kids = @pages.map { writer.reserve }
         @structure = @tagging && Tagging::Writer.new(@tagging, pages: @pages, refs: kids)
         @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
@@ -44,7 +47,8 @@ module Stationery
         entries = catalog(tree, outlines, @form.write)
                   .merge(accessibility(writer), metadata(writer, info, now), Attachments.write(writer, @attachments))
         entries.merge!(@conformance.catalog_entries(writer)) if @conformance
-        writer.render(root: writer.add(entries), info: writer.add(info))
+        pdf = writer.render(root: writer.add(entries), info: writer.add(info))
+        @signature ? @signature.apply(pdf) : pdf
       end
 
       private
@@ -69,14 +73,20 @@ module Stationery
           Type: :Page, Parent: tree, MediaBox: [0, 0, *page.size],
           Contents: writer.add(Stream.new(page.content)), Resources: page_resources(page, refs)
         }
-        if page.annotations.any?
-          dictionary[:Annots] = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
-        end
+        annotations = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
+        annotations << @form.sign(ref, taken: field_names) if @signature&.invisible? && ref == @kids.first
+        dictionary[:Annots] = annotations if annotations.any?
         dictionary.merge!(@structure.page_entries(page)) if @structure
-        dictionary.merge!(@conformance.page_entries(page)) if @conformance
+        dictionary.merge!(@conformance.page_entries(page, annotated: annotations.any?)) if @conformance
         writer.set(ref, dictionary)
       end
 
+      # Every field name of the document and the group each one starts with.
+      def field_names
+        names = @pages.flat_map(&:annotations).filter_map { |annotation| annotation[:widget]&.name }
+        names.flat_map { |name| [name, name.split(".").first] }.uniq
+      end
+
       def page_resources(page, refs)
         page.resource_names.to_h do |category, names|
           [category, names.to_h { |name| [name, refs.fetch(category).fetch(name)] }]
@@ -85,7 +95,7 @@ module Stationery
 
       def annotation_ref(writer, annotation, page)
         if annotation[:widget]
-          return @form.add(annotation[:widget], annotation[:rect], page) do |widget_ref|
+          return @form.add(annotation, page) do |widget_ref|
             @structure ? @structure.annotation(annotation, widget_ref) : {}
           end
         end

data/lib/stationery/pdf/conformance.rb

@@ -92,7 +92,8 @@ module Stationery
       end
 
       # A page's entries: PDF/UA tabs through annotations in structure order.
-      def page_entries(page) = pdf_ua? && page.annotations.any? ? { Tabs: :S } : {}
+      # `annotated` is whether the page has any, its own or a signature's.
+      def page_entries(page, annotated: page.annotations.any?) = pdf_ua? && annotated ? { Tabs: :S } : {}
 
       # A link annotation's entries: printable, and described for PDF/UA.
       def annotation_entries(link)
@@ -110,11 +111,12 @@ module Stationery
         link[:url] || "Page #{link[:dest].page + 1}"
       end
 
-      # Form fields draw with the standard Helvetica and ZapfDingbats, which
-      # are not embedded, and ask the viewer to regenerate appearances:
-      # neither PDF/A nor PDF/UA accepts that.
+      # A form field draws with the document's embedded fonts; one made
+      # without a font book draws with the standard Helvetica, which is not
+      # embedded: neither PDF/A nor PDF/UA accepts that.
       def fields(pages)
-        names = pages.flat_map(&:annotations).filter_map { |annotation| annotation[:widget]&.name }.uniq
+        widgets = pages.flat_map(&:annotations).select { |annotation| annotation[:widget] }
+        names = widgets.reject { |annotation| annotation[:appearance].embedded? }.map { |a| a[:widget].name }.uniq
         names.map { |name| %(form field "#{name}" draws with a font that is not embedded) }
       end
 

data/lib/stationery/pdf/serializer.rb

@@ -9,7 +9,8 @@ module Stationery
     # TextString for human-readable text that may need UTF-16.
     #
     # `crypt`, when given, receives every string's bytes (the writer binds it
-    # to the object being written) and the result is written as hex.
+    # to the object being written) and the result is written as hex. A
+    # Verbatim is written as it is.
     module Serializer
       NAME_ESCAPE = %r{[^\x21-\x7E]|[#%()/<>\[\]{}]}n
       LITERAL_ESCAPE = /[\\()\r]/n
@@ -25,6 +26,7 @@ module Stationery
         when Array then "[#{value.map { |v| dump(v, crypt) }.join(" ")}]"
         when HexString then hex(value.bytes, crypt)
         when TextString then text(value.value, crypt)
+        when Verbatim then value.source
         when String then crypt ? hex(value, crypt) : literal(value)
         when Integer, true, false then value.to_s
         when Float then number(value)

data/lib/stationery/pdf/signature/cms.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    class Signature
+      # The signature value: a detached CMS SignedData (RFC 5652) over the
+      # signed bytes, as CAdES and PAdES baseline ask for it. The signed
+      # attributes are the content type, the SHA-256 message digest and the
+      # ESS signing-certificate-v2 (RFC 5035) that binds the signature to the
+      # signer's certificate; there is no signing-time attribute, a PDF keeps
+      # that in the signature dictionary's /M.
+      #
+      # Ruby's OpenSSL::PKCS7 cannot add signed attributes, so the structure
+      # is built with OpenSSL::ASN1. RSA keys sign with PKCS #1 v1.5, EC keys
+      # with ECDSA, both over SHA-256.
+      class CMS
+        OIDS = {
+          data: "1.2.840.113549.1.7.1", signed_data: "1.2.840.113549.1.7.2",
+          content_type: "1.2.840.113549.1.9.3", message_digest: "1.2.840.113549.1.9.4",
+          signing_certificate_v2: "1.2.840.113549.1.9.16.2.47", sha256: "2.16.840.1.101.3.4.2.1",
+          rsa: "1.2.840.113549.1.1.1", ecdsa_sha256: "1.2.840.10045.4.3.2"
+        }.freeze
+
+        # `chain` are the certificates between the signer's and its root.
+        def initialize(certificate, key, chain = [])
+          @certificate = certificate
+          @key = key
+          @chain = chain
+        end
+
+        # The DER of the SignedData signing `data`.
+        def sign(data)
+          attributes = attributes(OpenSSL::Digest::SHA256.digest(data))
+          signature = @key.sign("SHA256", asn1::Set.new(attributes).to_der)
+          content = asn1::Sequence.new([
+                                         asn1::Integer.new(1),
+                                         asn1::Set.new([algorithm(:sha256)]),
+                                         asn1::Sequence.new([oid(:data)]),
+                                         implicit(certificates),
+                                         asn1::Set.new([signer(attributes, signature)])
+                                       ])
+          asn1::Sequence.new([oid(:signed_data), asn1::ASN1Data.new([content], 0, :CONTEXT_SPECIFIC)]).to_der
+        end
+
+        private
+
+        def asn1 = OpenSSL::ASN1
+        def oid(name) = asn1::ObjectId.new(OIDS.fetch(name))
+        def implicit(items) = asn1::Set.new(items, 0, :IMPLICIT, :CONTEXT_SPECIFIC)
+        def certificates = [@certificate, *@chain].map { |certificate| asn1.decode(certificate.to_der) }
+
+        # RSA and the digests carry an explicit NULL parameter, ECDSA none.
+        def algorithm(name, null: true) = asn1::Sequence.new(null ? [oid(name), asn1::Null.new(nil)] : [oid(name)])
+
+        def attribute(name, value) = asn1::Sequence.new([oid(name), asn1::Set.new([value])])
+
+        # DER orders the members of a SET OF by their encoding.
+        def attributes(digest)
+          [
+            attribute(:content_type, oid(:data)),
+            attribute(:message_digest, asn1::OctetString.new(digest)),
+            attribute(:signing_certificate_v2, signing_certificate)
+          ].sort_by(&:to_der)
+        end
+
+        # SigningCertificateV2 with one ESSCertIDv2: the certificate's SHA-256
+        # (the default hash algorithm, so it is left out).
+        def signing_certificate
+          hash = asn1::OctetString.new(OpenSSL::Digest::SHA256.digest(@certificate.to_der))
+          asn1::Sequence.new([asn1::Sequence.new([asn1::Sequence.new([hash])])])
+        end
+
+        def signer(attributes, signature)
+          issuer = asn1.decode(@certificate.issuer.to_der)
+          asn1::Sequence.new([
+                               asn1::Integer.new(1),
+                               asn1::Sequence.new([issuer, asn1::Integer.new(@certificate.serial)]),
+                               algorithm(:sha256),
+                               implicit(attributes),
+                               @key.is_a?(OpenSSL::PKey::EC) ? algorithm(:ecdsa_sha256, null: false) : algorithm(:rsa),
+                               asn1::OctetString.new(signature)
+                             ])
+        end
+      end
+    end
+  end
+end

data/lib/stationery/pdf/signature.rb

@@ -0,0 +1,167 @@
+# 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. Timestamps (PAdES-T), 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
+      BYTE_RANGE = "[0 0000000000 0000000000 0000000000]"
+      OPTIONS = %i[certificate key chain passphrase reason location contact name field at contents_size].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
+
+      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: CONTENTS_SIZE, **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
+        @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))
+        signature = CMS.new(@certificate, @key, @chain).sign(pdf.byteslice(0, first) + pdf.byteslice(last..))
+        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)
+        "the signature takes #{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/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/renderer/indents.rb

@@ -0,0 +1,42 @@
+# 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 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.rb

@@ -2,6 +2,7 @@
 
 require_relative "nodes"
 require_relative "styles"
+require_relative "renderer/indents"
 require_relative "renderer/inlines"
 require_relative "renderer/links"
 
@@ -9,8 +10,12 @@ module Stationery
   module Rich
     # Draws rich-text blocks with a component's element DSL. Images come from
     # `images:` (a callable given the src, returning a path, an IO or nil) or
-    # from files under `base_path:`; remote URLs are never fetched.
+    # from files under `base_path:`; remote URLs are never fetched. Block
+    # quotes and lists nested deeper than Indents::LIMIT stop indenting, which
+    # is reported as a NestingLimit warning.
     class Renderer
+      include Indents
+
       REMOTE = /\A[a-z][a-z0-9+.-]*:/i
       LINK_SCHEMES = %w[http https mailto tel].freeze
 
@@ -23,18 +28,25 @@ module Stationery
         @base_path = base_path && File.expand_path(base_path.to_s)
         @bookmarks = bookmarks
         @links = Links.new(links || LINK_SCHEMES, builder.warnings)
+        @indents = 0
       end
 
-      def render(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+      def render(blocks)
+        depth = indents_of(blocks)
+        @builder.warnings << Warnings::NestingLimit.new(depth:, limit: Indents::LIMIT) if depth > Indents::LIMIT
+        group(blocks)
+      end
 
       private
 
+      def group(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+
       def block(block)
         case block
         when Paragraph then paragraph(block.inlines, **@styles[:p])
         when Heading then heading(block)
-        when List then list(block)
-        when Blockquote then @component.box(role: :blockquote, **@styles[:blockquote]) { render(block.blocks) }
+        when List then indented(block) { list(block) }
+        when Blockquote then indented(block) { blockquote(block) }
         when CodeBlock then code(block)
         when Rule then @component.rule(**@styles[:hr])
         when Table then table(block)
@@ -59,11 +71,15 @@ module Stationery
         { title: heading.inlines.grep(Inline).map(&:text).join, level: heading.level }
       end
 
+      def blockquote(quote)
+        @component.box(role: :blockquote, **@styles[:blockquote]) { group(quote.blocks) }
+      end
+
       def list(list)
         options = list.ordered ? { **@styles[:ol], start: list.start || 1 } : @styles[:ul]
         @component.public_send(list.ordered ? :ol : :ul, **options) do
           list.items.each do |blocks|
-            @component.li { @component.text_style(**@styles[:li]) { render(blocks) } }
+            @component.li { @component.text_style(**@styles[:li]) { group(blocks) } }
           end
         end
       end
@@ -81,7 +97,7 @@ module Stationery
 
       def cell_content(cell)
         style = cell.header ? @styles[:table][:header] : {}
-        -> { @component.text_style(**style, align: cell.align) { render(cell.blocks) } }
+        -> { @component.text_style(**style, align: cell.align) { group(cell.blocks) } }
       end
 
       def image(node)

data/lib/stationery/svg/document.rb

@@ -16,16 +16,20 @@ module Stationery
                            tspan use symbol clipPath]).freeze
 
       def self.parse(source)
-        root = Parser.parse(source)
+        nesting = nil
+        root = Parser.parse(source) { |depth| nesting = depth }
         raise Error, "not an svg document" unless root&.name == "svg"
 
-        new(root)
+        new(root, nesting:)
       end
 
-      attr_reader :view_box, :unsupported
+      # `nesting` is how deep the source nested when that was deeper than
+      # Parser::MAX_DEPTH (and was flattened there), else nil.
+      attr_reader :view_box, :unsupported, :nesting
 
-      def initialize(root)
+      def initialize(root, nesting: nil)
         @root = root
+        @nesting = nesting
         @view_box = read_view_box
         @sheet = Stylesheet.parse(style_text)
         @gradients = Gradient.collect(root, @sheet)

data/lib/stationery/svg/parser.rb

@@ -8,10 +8,15 @@ module Stationery
     # Comments, processing instructions and doctypes are skipped; text content
     # (CDATA included) is kept only inside text, tspan and style, as String
     # children with entities decoded and each whitespace run one space.
+    #
+    # An element nested deeper than MAX_DEPTH is not descended into: it takes
+    # its place in the deepest element kept and so does what it holds, so
+    # nothing that walks the tree recurses deeper than that.
     module Parser
       Element = Data.define(:name, :attributes, :children)
 
       TEXT = %w[text tspan style].freeze
+      MAX_DEPTH = 128
 
       IGNORED = /<!--.*?-->|<\?.*?\?>|<!DOCTYPE[^>]*>/m
       CDATA = /<!\[CDATA\[(.*?)\]\]>/m
@@ -21,17 +26,19 @@ module Stationery
 
       module_function
 
-      def parse(source)
+      # The root element. The block is given how deep the source nested when
+      # that was deeper than `max_depth`.
+      def parse(source, max_depth: MAX_DEPTH)
         source = source.to_s.gsub(IGNORED, "").gsub(CDATA) { Regexp.last_match(1).gsub(/[&<>]/, ESCAPES) }
         scanner = StringScanner.new(source)
-        root = Element.new("document", {}, [])
-        stack = [root]
+        tree = Tree.new(max_depth)
         while (content = scanner.scan_until(/(?=<)/))
-          keep(stack.last, content)
+          keep(tree.open, content)
           tag = scanner.scan(TAG) or (scanner.getch && next)
-          handle(stack, *tag.match(TAG).captures)
+          tree.tag(*tag.match(TAG).captures)
         end
-        root.children.first
+        yield tree.deepest if block_given? && tree.deepest > max_depth
+        tree.root
       end
 
       # Yields the element and every element below it, depth first.
@@ -46,12 +53,45 @@ module Stationery
         element.children << Stationery::Text::Entities.decode(content).gsub(/\s+/, " ")
       end
 
-      def handle(stack, closing, name, attributes, self_closing)
-        return stack.pop if closing == "/" && stack.size > 1
+      # The elements open while the source is read. `hoisted` counts the open
+      # ones too deep to descend into; their end tags are counted off again.
+      class Tree
+        attr_reader :deepest
 
-        element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
-        stack.last.children << element
-        stack << element if self_closing.empty?
+        def initialize(max_depth)
+          @document = Element.new("document", {}, [])
+          @stack = [@document]
+          @max_depth = max_depth
+          @hoisted = 0
+          @deepest = 0
+        end
+
+        def root = @document.children.first
+        def open = @stack.last
+
+        def tag(closing, name, attributes, self_closing)
+          return close if closing == "/"
+
+          element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
+          open.children << element
+          descend(element) if self_closing.empty?
+        end
+
+        private
+
+        def close
+          return @hoisted -= 1 if @hoisted.positive?
+
+          @stack.pop if @stack.size > 1
+        end
+
+        def descend(element)
+          depth = @stack.size + @hoisted
+          @deepest = depth if depth > @deepest
+          return @stack << element if @stack.size <= @max_depth
+
+          @hoisted += 1
+        end
       end
     end
   end

data/lib/stationery/svg/walker.rb

@@ -11,6 +11,7 @@ module Stationery
     class Walker
       RENDERED = (Shapes::NAMES + %w[text g use svg]).freeze
       VIEWPORTS = %w[symbol svg].freeze
+      MAX_USES = 32 # a use of a use of a use …
 
       attr_reader :issues
 
@@ -69,6 +70,7 @@ module Stationery
         target, id = target_of(element)
         return unless target
         return issue("use: circular reference ##{id}") if chain.include?(id)
+        return issue("use: nested deeper than #{MAX_USES}") if chain.size >= MAX_USES
 
         attributes = element.attributes
         placed = style.transformed([1, 0, 0, 1, Shapes.f(attributes, "x"), Shapes.f(attributes, "y")])