stationery 0.7.0 → 0.9.0

data/lib/stationery/pdf/attachments.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Stationery
+  module PDF
+    # A file embedded in the document: its name, bytes, MIME type, an
+    # optional description and how it relates to the document (the
+    # /AFRelationship a Factur-X invoice or a PDF/A-3 attachment declares).
+    Attachment = Data.define(:name, :data, :mime, :description, :relationship, :modified_at)
+
+    # Builds and writes embedded files: each becomes a /Filespec with an
+    # /EmbeddedFile stream, listed in the catalog's /Names /EmbeddedFiles
+    # tree and its /AF array.
+    module Attachments
+      RELATIONSHIPS = { alternative: :Alternative, source: :Source, data: :Data, supplement: :Supplement,
+                        unspecified: :Unspecified }.freeze
+
+      module_function
+
+      def build(name, data, mime: "application/octet-stream", description: nil, relationship: :unspecified,
+                modified_at: nil)
+        name = name.to_s
+        raise ArgumentError, "an attachment needs a name" if name.empty?
+        raise ArgumentError, "attachment #{name.inspect} needs its data as a String" unless data.is_a?(String)
+        unless RELATIONSHIPS.key?(relationship)
+          raise ArgumentError, "unknown attachment relationship #{relationship.inspect}; use one of " \
+                               "#{RELATIONSHIPS.keys.map(&:inspect).join(", ")}"
+        end
+
+        Attachment.new(name:, data: data.b, mime: mime.to_s, description: description&.to_s, relationship:,
+                       modified_at:)
+      end
+
+      # One list from class-level attachments and per-render hashes
+      # (`{ name:, data:, mime:, … }`); the same name twice raises.
+      def merge(*lists)
+        lists.flatten.compact.map { |item| item.is_a?(Attachment) ? item : from_hash(item) }.tap do |all|
+          duplicate = all.map(&:name).tally.find { |_, count| count > 1 }&.first
+          raise ArgumentError, "attachment #{duplicate.inspect} is given twice" if duplicate
+        end
+      end
+
+      def from_hash(hash)
+        hash = hash.to_h.transform_keys(&:to_sym)
+        build(hash[:name], hash[:data], **hash.except(:name, :data))
+      end
+
+      # The catalog entries for the files, written through `writer`; empty without any.
+      def write(writer, attachments)
+        return {} if attachments.nil? || attachments.empty?
+
+        refs = attachments.sort_by(&:name).map do |attachment|
+          [attachment.name, writer.add(filespec(writer, attachment))]
+        end
+        { Names: { EmbeddedFiles: { Names: refs.flatten } }, AF: refs.map(&:last) }
+      end
+
+      def filespec(writer, attachment)
+        spec = { Type: :Filespec, F: attachment.name.b, UF: TextString.new(attachment.name),
+                 AFRelationship: RELATIONSHIPS.fetch(attachment.relationship),
+                 EF: { F: writer.add(stream(attachment)) } }
+        spec[:Desc] = TextString.new(attachment.description) if attachment.description
+        spec
+      end
+
+      def stream(attachment)
+        params = { Size: attachment.data.bytesize, CheckSum: HexString.new(Digest::MD5.digest(attachment.data)) }
+        if attachment.modified_at
+          params[:ModDate] = TextString.new(attachment.modified_at.utc.strftime("D:%Y%m%d%H%M%SZ"))
+        end
+        Stream.new(attachment.data, { Type: :EmbeddedFile, Subtype: attachment.mime.to_sym, Params: params })
+      end
+    end
+  end
+end

data/lib/stationery/pdf/conformance.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The archival and accessibility standards a render claims, and what each
+    # asks of the file: PDF/A-2b and PDF/A-3b (ISO 19005-2/3, level B) and
+    # PDF/UA-1 (ISO 14289-1). Levels combine: `Conformance.new(:pdf_a3b, :pdf_ua1)`.
+    #
+    # A claim is only written when the document keeps it: what cannot be made
+    # conformant raises (ArgumentError for options that contradict the level,
+    # ConformanceError for content), so a file is never mislabelled.
+    class Conformance
+      LEVELS = {
+        pdf_a2b: { standard: :pdf_a, part: 2, conformance: "B", label: "PDF/A-2b" },
+        pdf_a3b: { standard: :pdf_a, part: 3, conformance: "B", label: "PDF/A-3b" },
+        pdf_ua1: { standard: :pdf_ua, part: 1, label: "PDF/UA-1" }
+      }.freeze
+      PDFA_ID = "http://www.aiim.org/pdfa/ns/id/"
+      PDFUA_ID = "http://www.aiim.org/pdfua/ns/id/"
+      # PDF/A knows its own schema; PDF/UA's has to be described to it.
+      PDFUA_SCHEMA = {
+        name: "PDF/UA identification schema", uri: PDFUA_ID, prefix: "pdfuaid",
+        properties: [{ name: "part", type: "Integer", category: "internal",
+                       description: "The part of ISO 14289 the document conforms to" }]
+      }.freeze
+      ICC_PROFILE = File.expand_path("icc/sRGB2014.icc", __dir__)
+      OUTPUT_CONDITION = "sRGB IEC61966-2.1"
+      PRINT = 4
+      CMYK_OPERATOR = /^(?:-?[\d.]+ ){4}[kK]$/
+
+      attr_reader :levels
+
+      def self.label(level) = LEVELS.dig(level.to_sym, :label) || level.to_s
+
+      # The Conformance for `levels` (a Symbol, an Array or nil); nil without any.
+      def self.for(levels)
+        levels = Array(levels).flatten.compact
+        levels.empty? ? nil : new(*levels)
+      end
+
+      def initialize(*levels)
+        @levels = levels.flatten.map(&:to_sym).uniq
+        unknown = @levels - LEVELS.keys
+        raise ArgumentError, "unknown conformance #{unknown.map(&:inspect).join(", ")} (use #{names})" if unknown.any?
+        raise ArgumentError, "conformance takes one PDF/A level, got #{archival.join(" and ")}" if archival.size > 1
+      end
+
+      def pdf_a? = archival.any?
+      def pdf_ua? = @levels.include?(:pdf_ua1)
+      # The PDF/A part (2 or 3), nil without one.
+      def part = archival.first && LEVELS.dig(archival.first, :part)
+
+      # What can be refused before anything is drawn: options and metadata.
+      def validate!(encrypt:, metadata:, attachments:)
+        raise ArgumentError, "PDF/A forbids encryption: drop encrypt: or the conformance level" if pdf_a? && encrypt
+        if part == 2 && attachments.any?
+          raise ArgumentError, "PDF/A-2b only embeds PDF/A files: use conformance :pdf_a3b to attach " \
+                               "#{attachments.map(&:name).join(", ")}"
+        end
+
+        missing = pdf_ua? ? %i[title lang].select { |key| metadata[key].to_s.strip.empty? } : []
+        raise ConformanceError.new(@levels, missing.map { |key| "metadata #{key}: is missing" }) if missing.any?
+      end
+
+      # What only the finished pages show. Colour that the sRGB output intent
+      # does not cover is reported; what breaks the claim outright raises.
+      def audit!(pages, resources:, warnings:)
+        cmyk(pages, resources).each { |subject| warnings << Warnings::ConformanceIssue.new(level: archival.first, subject:) }
+        issues = fields(pages) + alternatives(warnings)
+        raise ConformanceError.new(@levels, issues) if issues.any?
+      end
+
+      # The identification schemas for the XMP packet (see XMP.packet).
+      def xmp_extensions
+        extensions = {}
+        extensions[PDFA_ID] = { prefix: "pdfaid", "part" => part, "conformance" => "B" } if pdf_a?
+        extensions[PDFUA_ID] = { prefix: "pdfuaid", "part" => 1 } if pdf_ua?
+        extensions
+      end
+
+      # Schemas PDF/A has to be told about: PDF/UA's, when both are claimed.
+      def xmp_schemas = pdf_a? && pdf_ua? ? [PDFUA_SCHEMA] : []
+
+      # The catalog's entries: the sRGB output intent of a PDF/A file.
+      def catalog_entries(writer)
+        return {} unless pdf_a?
+
+        profile = writer.add(Stream.new(File.binread(ICC_PROFILE), { N: 3 }))
+        { OutputIntents: [{ Type: :OutputIntent, S: :GTS_PDFA1, DestOutputProfile: profile,
+                            OutputConditionIdentifier: TextString.new(OUTPUT_CONDITION),
+                            Info: TextString.new(OUTPUT_CONDITION) }] }
+      end
+
+      # A page's entries: PDF/UA tabs through annotations in structure order.
+      # `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)
+        entries = { F: PRINT }
+        entries[:Contents] = TextString.new(description(link)) if pdf_ua?
+        entries
+      end
+
+      private
+
+      def archival = @levels.select { |level| LEVELS.dig(level, :standard) == :pdf_a }
+      def names = LEVELS.keys.map(&:inspect).join(", ")
+
+      def description(link)
+        link[:url] || "Page #{link[:dest].page + 1}"
+      end
+
+      # 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)
+        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
+
+      def alternatives(warnings)
+        return [] unless pdf_ua?
+
+        warnings.grep(Warnings::MissingAlt).map(&:message)
+      end
+
+      def cmyk(pages, resources)
+        return [] unless pdf_a?
+
+        images = resources.images.any? { |image| image.respond_to?(:color_space) && image.color_space == :DeviceCMYK }
+        subjects = images ? ["a CMYK image"] : []
+        pages.each_with_index do |page, index|
+          subjects << "CMYK colour on page #{index + 1}" if page.content.match?(CMYK_OPERATOR)
+        end
+        subjects
+      end
+    end
+  end
+end

data/lib/stationery/pdf/factur_x.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # A Factur-X / ZUGFeRD e-invoice: the invoice's Cross Industry Invoice XML
+    # embedded in a PDF/A-3b file and identified in XMP, so the one document
+    # is read by people and booked by machines.
+    #
+    # Stationery carries the XML, it does not write or validate it: `xml` is
+    # the finished document as a String, or a method name, block or callable
+    # that answers it for the document being rendered.
+    class FacturX
+      NAMESPACE = "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#"
+      PROFILES = { minimum: "MINIMUM", basic_wl: "BASIC WL", basic: "BASIC", en16931: "EN 16931",
+                   extended: "EXTENDED", xrechnung: "XRECHNUNG" }.freeze
+      # Profiles too small to stand for the invoice: their XML is data beside
+      # the page, not an alternative to it.
+      DATA_ONLY = %i[minimum basic_wl].freeze
+      FILENAMES = { xrechnung: "xrechnung.xml" }.freeze
+      DEFAULT_FILENAME = "factur-x.xml"
+      DESCRIPTION = "Factur-X Invoice"
+      ROOTS = ["<?xml", "<rsm:CrossIndustryInvoice"].freeze
+      SCHEMA = {
+        name: "Factur-X PDFA Extension Schema", uri: NAMESPACE, prefix: "fx",
+        properties: [
+          { name: "DocumentFileName", type: "Text", category: "external",
+            description: "The name of the embedded XML document" },
+          { name: "DocumentType", type: "Text", category: "external",
+            description: "The type of the hybrid document in capital letters, e.g. INVOICE or ORDER" },
+          { name: "Version", type: "Text", category: "external",
+            description: "The actual version of the standard applying to the embedded XML document" },
+          { name: "ConformanceLevel", type: "Text", category: "external",
+            description: "The conformance level of the embedded XML document" }
+        ].freeze
+      }.freeze
+
+      attr_reader :xml, :profile, :filename, :version
+
+      # The invoice for `spec` (`{ xml:, profile:, filename:, version:,
+      # relationship: }`, as `factur_x` and `to_pdf(factur_x:)` take it)
+      # resolved for `document`; nil without a spec.
+      def self.for(spec, document)
+        return unless spec
+
+        spec = spec.to_h.transform_keys(&:to_sym)
+        new(resolve(spec[:xml], document), **spec.except(:xml))
+      end
+
+      def self.resolve(xml, document)
+        case xml
+        when Symbol then document.send(xml)
+        when Proc then xml.arity.zero? ? document.instance_exec(&xml) : xml.call(document)
+        else xml.respond_to?(:call) ? xml.call(document) : xml
+        end
+      end
+
+      def self.profile(name)
+        name = name.to_s.downcase.to_sym
+        return name if PROFILES.key?(name)
+
+        raise ArgumentError, "unknown Factur-X profile #{name.inspect} (use #{PROFILES.keys.map(&:inspect).join(", ")})"
+      end
+
+      def self.invoice?(xml) = xml.is_a?(String) && xml.delete_prefix("").lstrip.start_with?(*ROOTS)
+
+      def initialize(xml, profile: :en16931, filename: nil, version: "1.0", relationship: nil)
+        @profile = self.class.profile(profile)
+        unless self.class.invoice?(xml)
+          raise ArgumentError, "factur_x needs the invoice XML (a String starting with #{ROOTS.join(" or ")}), " \
+                               "#{got(xml)}"
+        end
+
+        @xml = xml
+        @filename = (filename || FILENAMES.fetch(@profile, DEFAULT_FILENAME)).to_s
+        @version = version.to_s
+        @relationship = relationship || (DATA_ONLY.include?(@profile) ? :data : :alternative)
+      end
+
+      # The fx:ConformanceLevel of the profile ("EN 16931").
+      def level = PROFILES.fetch(@profile)
+
+      # The declared conformance levels with the PDF/A-3b the invoice needs.
+      def conformance(levels)
+        levels = Array(levels).flatten.compact.map(&:to_sym)
+        if levels.include?(:pdf_a2b)
+          raise ArgumentError, "Factur-X embeds its XML, which needs PDF/A-3b: drop conformance :pdf_a2b"
+        end
+
+        levels.include?(:pdf_a3b) ? levels : levels + [:pdf_a3b]
+      end
+
+      # The XML as the file to embed, stamped `at` (its /ModDate).
+      def attachment(at: Time.now)
+        Attachments.build(@filename, @xml, mime: "text/xml", description: DESCRIPTION, relationship: @relationship,
+                                           modified_at: at)
+      end
+
+      # The invoice's identification for the XMP packet (see XMP.packet).
+      def xmp_extensions
+        { NAMESPACE => { prefix: "fx", "DocumentType" => "INVOICE", "DocumentFileName" => @filename,
+                         "Version" => @version, "ConformanceLevel" => level } }
+      end
+
+      # The description of the `fx` schema PDF/A asks for.
+      def xmp_schema = SCHEMA
+
+      private
+
+      def got(xml)
+        return "got #{xml.nil? ? "nil" : "a #{xml.class}"}" unless xml.is_a?(String)
+        return "got an empty String" if xml.strip.empty?
+
+        "got #{xml[0, 40].inspect}"
+      end
+    end
+  end
+end

data/lib/stationery/pdf/icc/LICENSE.md

@@ -0,0 +1,14 @@
+# sRGB2014.icc
+
+`sRGB2014.icc` is the ICC's sRGB v2 profile ("sRGB2014", copyright International Color
+Consortium, 2015), downloaded unmodified from
+<https://registry.color.org/rgb-registry/profiles/sRGB2014.icc>
+(SHA-256 `384b832de3412066743b52a75ee906b6fb9fb8d9e09e936fc2c43223815c6e0a`).
+Stationery embeds it as the output intent of PDF/A documents.
+
+The ICC's terms for profiles it owns (<https://www.color.org/profiles2.xalter#license>):
+
+> This profile is made available by the International Color Consortium, and may be copied,
+> distributed, embedded, made, used, and sold without restriction. Altered versions of this
+> profile shall have the original identification and copyright information removed and shall
+> not be misrepresented as the original profile.

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/stream.rb

@@ -5,15 +5,17 @@ require "zlib"
 module Stationery
   module PDF
     # A stream object. Data is Flate-compressed unless the dictionary already
-    # names a filter (JPEG's DCTDecode, or PNG data that is already zlib).
+    # names a filter (JPEG's DCTDecode, or PNG data that is already zlib) or
+    # `compress: false` asks for it plain (XMP metadata, which PDF/A readers
+    # scan for without decoding).
     class Stream
       attr_reader :dictionary, :data
 
-      def initialize(data, dictionary = {})
+      def initialize(data, dictionary = {}, compress: !dictionary.key?(:Filter))
         data = data.b
         dictionary = dictionary.dup
 
-        unless dictionary.key?(:Filter)
+        if compress
           data = Zlib::Deflate.deflate(data)
           dictionary[:Filter] = :FlateDecode
         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