gamba 2.0.0

data/lib/gamba/pdf/writer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+require "zlib"
+
+module PDF
+  module Core
+    # Writes a PDF 1.5 file: streams compressed, every other object packed into one compressed object stream, and
+    # a compressed cross-reference stream instead of the xref table (ISO 32000-1 §7.5.7, §7.5.8).
+    class Writer
+      MINIMUM_VERSION = 1.5
+      BINARY_MARKER = "%\xE2\xE3\xCF\xD3\n".b
+
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(objects:, root:, info:, version:, trailer: {}, encryption: nil, identified: false)
+        @objects = objects
+        @root = root
+        @info = info
+        @version = [version, MINIMUM_VERSION].max
+        @trailer = trailer
+        return unless encryption || identified
+
+        file_identifier = PDF::Core::ByteString.new(document_digest)
+        @trailer = trailer.merge(ID: [file_identifier, file_identifier])
+        return unless encryption
+
+        @encryption_key = encryption.key(file_identifier)
+        @trailer[:Encrypt] = encryption.dictionary(file_identifier)
+      end
+
+      def call
+        output = "%PDF-#{version}\n".b << BINARY_MARKER
+        location_by_identifier = {}
+
+        stream_objects, packed_objects = objects.partition(&:stream?)
+        stream_objects.each do |reference|
+          location_by_identifier[reference.identifier] = [1, output.bytesize]
+          output << indirect_stream(reference.identifier, reference.data, reference.stream, compressed: !reference.uncompressed)
+        end
+
+        object_stream_identifier = objects.size + 1
+        unless packed_objects.empty?
+          location_by_identifier[object_stream_identifier] = [1, output.bytesize]
+          output << object_stream(object_stream_identifier, packed_objects, location_by_identifier)
+        end
+
+        cross_reference_identifier = object_stream_identifier + 1
+        location_by_identifier[cross_reference_identifier] = [1, output.bytesize]
+        output << cross_reference_stream(cross_reference_identifier, location_by_identifier)
+      end
+
+      private
+
+      attr_reader :objects, :root, :info, :version, :trailer
+
+      # A file identifier derived from the document's content, so the same document always gets the same one.
+      def document_digest
+        digest = Digest::MD5.new
+        objects.each do |reference|
+          digest << PDF::Core.serialize(reference.data)
+          digest << reference.stream if reference.stream?
+        end
+        digest.digest
+      end
+
+      # Streams are encrypted once compressed; the cross-reference stream never is (ISO 32000-1 §7.5.8.4).
+      def indirect_stream(identifier, dictionary, bytes, encrypted: true, compressed: true)
+        compressed &&= dictionary[:Filter].nil?
+        bytes = Zlib::Deflate.deflate(bytes) if compressed
+        bytes = Prawn::Document::Arcfour.new(Prawn::Document::Security.object_key(@encryption_key, identifier, 0)).encrypt(bytes) if @encryption_key && encrypted
+        dictionary = dictionary.merge(Length: bytes.bytesize)
+        dictionary[:Filter] = :FlateDecode if compressed
+        "#{identifier} 0 obj\n#{PDF::Core.serialize(dictionary)}\nstream\n".b << bytes.b << "\nendstream\nendobj\n"
+      end
+
+      def object_stream(identifier, references, location_by_identifier)
+        offsets = +""
+        body = +""
+        references.each_with_index do |reference, index|
+          location_by_identifier[reference.identifier] = [2, identifier, index]
+          offsets << "#{reference.identifier} #{body.bytesize} "
+          body << PDF::Core.serialize(reference.data) << "\n"
+        end
+        dictionary = {Type: :ObjStm, N: references.size, First: offsets.bytesize}
+        indirect_stream(identifier, dictionary, offsets << body)
+      end
+
+      # Each row is one byte of type, then the offset or the object stream, then the generation or the index.
+      def cross_reference_stream(identifier, location_by_identifier)
+        size = identifier + 1
+        offset_width = [(location_by_identifier.values.map { _1[1] }.max.bit_length + 7) / 8, 1].max
+        rows = (+"\x00".b) << ("\x00" * offset_width).b << "\xFF\xFF".b
+        (1...size).each do |object_identifier|
+          type, field, generation_or_index = location_by_identifier.fetch(object_identifier)
+          rows << type.chr << [field].pack("Q>").byteslice(8 - offset_width, offset_width) << [generation_or_index.to_i].pack("n")
+        end
+        dictionary = {Type: :XRef, Size: size, W: [1, offset_width, 2], Root: root, Info: info}.merge(trailer)
+        indirect_stream(identifier, dictionary, rows, encrypted: false) << "startxref\n#{location_by_identifier.fetch(identifier)[1]}\n%%EOF\n"
+      end
+    end
+  end
+end

data/lib/gamba/pdf.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PDF
+  # PDF syntax: numbers, names, strings, arrays and dictionaries, as ISO 32000-1 §7.3 writes them.
+  module Core
+    Name = Data.define(:value)
+    # A real number read from another file, written back exactly as it was read.
+    Real = Data.define(:source) do
+      def to_f = source.to_f
+    end
+
+    # Objects that build their dictionary when the document is written, once every reference they hold is known.
+    module Serializable
+    end
+    LiteralString = Class.new(String)
+    ByteString = Class.new(String)
+
+    DELIMITER_OR_IRREGULAR_BYTES = ((0..32).to_a + [35, 37, 40, 41, 47, 60, 62, 91, 93, 123, 125] + (127..255).to_a).freeze
+    LITERAL_STRING_ESCAPES = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r"}.freeze
+    REGULAR_NAME = %r{\A[!-~&&[^#%()<>\[\]{}/]]*\z}
+    # Dictionary keys read from other files are symbols too: past a size no document of ours reaches, stop caching.
+    NAME_CACHE_LIMIT = 10_000
+    NAME_BY_SYMBOL = Hash.new do |cache, symbol|
+      name = escape_name(symbol.to_s).freeze
+      (cache.size < NAME_CACHE_LIMIT) ? cache[symbol] = name : name
+    end
+
+    module_function
+
+    def escape_name(name)
+      return "/#{name}" if name.match?(REGULAR_NAME)
+
+      (+"/").concat(*name.b.each_byte.map { |byte| DELIMITER_OR_IRREGULAR_BYTES.include?(byte) ? format("#%02X", byte) : byte.chr })
+    end
+
+    # Five decimals, trailing zeros dropped but one: 1 is "1.0", 0.5 is "0.5", 1/3 is "0.33333".
+    def real(number)
+      digits = format("%.5f", number)
+      last = digits.bytesize - 1
+      last -= 1 while digits.getbyte(last) == 48 && digits.getbyte(last - 1) != 46
+      digits.byteslice(0, last + 1)
+    end
+
+    def real_params(numbers)
+      numbers.map { real(_1) }.join(" ")
+    end
+
+    # Integers as integers, other numbers to five decimals without a trailing ".0".
+    def number(value)
+      return value.to_s if value.is_a?(Integer)
+
+      digits = real(value)
+      digits.end_with?(".0") ? digits.delete_suffix(".0") : digits
+    end
+
+    def serialize(value, in_content_stream = false)
+      case value
+      when nil then "null"
+      when true then "true"
+      when false then "false"
+      when Numeric then number(value)
+      when Symbol then NAME_BY_SYMBOL[value]
+      # Names read from other files are escaped every time: caching them would keep every font subset name forever.
+      when Name then escape_name(value.value)
+      when Real then value.source
+      when LiteralString then "(#{value.gsub(/[\\\r()]/, LITERAL_STRING_ESCAPES)})"
+      when ByteString then "<#{value.unpack1("H*")}>"
+      when Time then "(#{value.strftime("D:%Y%m%d%H%M%S%z").chop.chop}'00')"
+      when String then "<#{(in_content_stream ? value : utf16be(value)).unpack1("H*")}>"
+      when Array then "[#{value.map { serialize(_1, in_content_stream) }.join(" ")}]"
+      when Hash then "<<#{value.map { |key, entry| "#{serialize(key.to_sym)} #{serialize(entry, in_content_stream)}" }.join("\n")}>>"
+      when Reference then value.to_s
+      when Serializable then serialize(value.to_hash, in_content_stream)
+      else raise Prawn::Errors::FailedObjectConversion, "This object cannot be serialized to PDF (#{value.inspect})"
+      end
+    end
+
+    # PDF::Core's name for serialize, which code written for Prawn calls, prawn-svg among it.
+    def pdf_object(object, in_content_stream = false)
+      serialize(object, in_content_stream)
+    end
+
+    def utf16be(string)
+      "\xFE\xFF".b + string.encode(::Encoding::UTF_16BE).b
+    end
+  end
+end

data/lib/gamba/pdf_a/srgb_profile.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Gamba
+  module PdfA
+    # An ICC version 2 display profile for sRGB (IEC 61966-2.1), built from the standard's primaries adapted to D50
+    # (ICC.1:2001-04): PDF/A needs one as output intent, and building it avoids shipping a third-party file.
+    module SrgbProfile
+      DESCRIPTION = "sRGB IEC61966-2.1"
+      D50_WHITE = [0.9642, 1.0, 0.8249].freeze
+      # sRGB primaries, Bradford-adapted from D65 to D50.
+      RED = [0.4361, 0.2225, 0.0139].freeze
+      GREEN = [0.3851, 0.7169, 0.0971].freeze
+      BLUE = [0.1431, 0.0606, 0.7141].freeze
+      # The sRGB tone curve, approximated by a 2.2 gamma, as u8Fixed8Number.
+      GAMMA = 0x0233
+
+      module_function
+
+      def bytes
+        @bytes ||= begin
+          curve = "curv".b + "\x00" * 4 + [1, GAMMA].pack("Nn") + "\x00\x00".b
+          tags = [
+            ["desc", text_description(DESCRIPTION)],
+            ["cprt", "text".b + ("\x00" * 4) + "No copyright, use freely\x00".b],
+            ["wtpt", xyz(D50_WHITE)],
+            ["rXYZ", xyz(RED)], ["gXYZ", xyz(GREEN)], ["bXYZ", xyz(BLUE)],
+            ["rTRC", curve], ["gTRC", curve], ["bTRC", curve]
+          ]
+          table_size = 4 + (tags.size * 12)
+          offset = 128 + table_size
+          directory = [tags.size].pack("N")
+          data = +"".b
+          tags.each do |signature, tag|
+            directory << [signature, offset + data.bytesize, tag.bytesize].pack("a4N2")
+            data << tag << ("\x00" * ((4 - (tag.bytesize % 4)) % 4))
+          end
+          body = directory + data
+          header(128 + body.bytesize) + body
+        end
+      end
+
+      def header(size)
+        [size, "", 0x02100000, "mntr", "RGB ", "XYZ ", 2026, 1, 1, 0, 0, 0, "acsp", "APPL", 0, "", "", 0, 0,
+          *D50_WHITE.map { s15_fixed16(_1) }, ""].pack("N a4 N a4 a4 a4 n6 a4 a4 N a4 a4 Q> N N3 a4") + ("\x00" * 44)
+      end
+
+      def xyz(values)
+        "XYZ ".b + ("\x00" * 4) + values.map { s15_fixed16(_1) }.pack("N3")
+      end
+
+      def s15_fixed16(value)
+        (value * 65_536).round & 0xFFFFFFFF
+      end
+
+      def text_description(text)
+        ascii = "#{text}\x00".b
+        "desc".b + ("\x00" * 4) + [ascii.bytesize].pack("N") + ascii + [0, 0, 0].pack("N2n") + ("\x00" * 67)
+      end
+    end
+  end
+end

data/lib/gamba/pdf_a.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Prawn
+  module Errors
+    PdfAViolation = Class.new(StandardError)
+  end
+end
+
+module Gamba
+  # PDF/A-3b (ISO 19005-3), switched on with Prawn::Document.new(pdf_a: true): XMP metadata matching the
+  # document information, an sRGB output intent, a file identifier, and errors for what PDF/A forbids.
+  # Factur-X invoices (pdf.factur_x) embed their CII XML into such a document.
+  module PdfA
+    FACTUR_X_NAMESPACE = "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#"
+    FACTUR_X_FILENAME = "factur-x.xml"
+    # Profile names of the Factur-X specification, and the relationship it gives the XML of each (§ 6.2.2).
+    FACTUR_X_LEVEL_BY_PROFILE = {
+      minimum: "MINIMUM", basic_wl: "BASIC WL", basic: "BASIC", en16931: "EN 16931", extended: "EXTENDED"
+    }.freeze
+    RELATIONSHIP_BY_PROFILE = {
+      minimum: :Data, basic_wl: :Data, basic: :Alternative, en16931: :Alternative, extended: :Alternative
+    }.freeze
+    # Annotation flag 3, Print: PDF/A requires printing every annotation (ISO 19005-2 §6.3.2).
+    PRINT_FLAG = 4
+    XMP_PROPERTY_BY_INFO_KEY = {
+      Title: "dc:title", Author: "dc:creator", Subject: "dc:description", Keywords: "pdf:Keywords",
+      Creator: "xmp:CreatorTool", Producer: "pdf:Producer", CreationDate: "xmp:CreateDate", ModDate: "xmp:ModifyDate"
+    }.freeze
+
+    def pdf_a?
+      @pdf_a == true
+    end
+
+    def factur_x(xml, profile: :en16931, filename: FACTUR_X_FILENAME, description: "Factur-X invoice")
+      raise Prawn::Errors::PdfAViolation, "Factur-X invoices are PDF/A-3 documents: create this one with pdf_a: true" unless pdf_a?
+
+      level = FACTUR_X_LEVEL_BY_PROFILE.fetch(profile) { raise ArgumentError, "Unknown Factur-X profile #{profile.inspect}: #{FACTUR_X_LEVEL_BY_PROFILE.keys.join(", ")}" }
+      @factur_x = {xml: xml.b, level:, relationship: RELATIONSHIP_BY_PROFILE.fetch(profile), filename:, description:}
+    end
+
+    private
+
+    def finalize_pdf_a
+      min_version(1.7)
+      icc_profile = ref!({N: 3}, PdfA::SrgbProfile.bytes)
+      @root.data[:OutputIntents] = [{
+        Type: :OutputIntent, S: :GTS_PDFA1, OutputConditionIdentifier: PDF::Core::LiteralString.new(SrgbProfile::DESCRIPTION),
+        Info: PDF::Core::LiteralString.new(SrgbProfile::DESCRIPTION), DestOutputProfile: icc_profile
+      }]
+      embed_factur_x if @factur_x
+      metadata = ref!({Type: :Metadata, Subtype: :XML}, xmp_packet)
+      metadata.uncompressed = true
+      @root.data[:Metadata] = metadata
+    end
+
+    def embed_factur_x
+      xml = @factur_x[:xml]
+      modification_date = @info.data[:ModDate] || @info.data[:CreationDate]
+      params = {Size: xml.bytesize}
+      params[:ModDate] = modification_date if modification_date
+      embedded_file = ref!({Type: :EmbeddedFile, Subtype: :"text/xml", Params: params}, xml)
+      file_specification = ref!(
+        Type: :Filespec, F: PDF::Core::LiteralString.new(@factur_x[:filename]), UF: @factur_x[:filename],
+        Desc: @factur_x[:description], AFRelationship: @factur_x[:relationship], EF: {F: embedded_file, UF: embedded_file}
+      )
+      @root.data[:AF] = [file_specification]
+      (names.data[:EmbeddedFiles] ||= ref!(PDF::Core::NameTree.new)).data.add(@factur_x[:filename], file_specification)
+    end
+
+    def xmp_packet
+      properties = XMP_PROPERTY_BY_INFO_KEY.filter_map do |key, property|
+        value = @info.data[key]
+        next unless value
+
+        text = value.is_a?(Time) ? value.iso8601 : escape_xml(value.to_s)
+        case property
+        when "dc:title", "dc:description" then "<#{property}><rdf:Alt><rdf:li xml:lang=\"x-default\">#{text}</rdf:li></rdf:Alt></#{property}>"
+        when "dc:creator" then "<#{property}><rdf:Seq><rdf:li>#{text}</rdf:li></rdf:Seq></#{property}>"
+        else "<#{property}>#{text}</#{property}>"
+        end
+      end
+      <<~XMP
+        <?xpacket begin="\u{FEFF}" id="W5M0MpCehiHzreSzNTczkc9d"?>
+        <x:xmpmeta xmlns:x="adobe:ns:meta/">
+        <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+        <rdf:Description rdf:about="" xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:pdf="http://ns.adobe.com/pdf/1.3/" xmlns:xmp="http://ns.adobe.com/xap/1.0/">
+        <pdfaid:part>3</pdfaid:part>
+        <pdfaid:conformance>B</pdfaid:conformance>
+        #{properties.join("\n")}
+        </rdf:Description>
+        #{factur_x_xmp}
+        </rdf:RDF>
+        </x:xmpmeta>
+        <?xpacket end="w"?>
+      XMP
+    end
+
+    # The Factur-X properties, and the PDF/A extension schema declaring them (Factur-X specification § 6.2.1).
+    def factur_x_xmp
+      return "" unless @factur_x
+
+      fields = {DocumentFileName: "name of the embedded XML invoice file", DocumentType: "INVOICE",
+                Version: "The actual version of the Factur-X XML schema", ConformanceLevel: "The conformance level of the embedded Factur-X data"}
+      described = fields.map do |name, description|
+        "<rdf:li rdf:parseType=\"Resource\"><pdfaProperty:name>#{name}</pdfaProperty:name><pdfaProperty:valueType>Text</pdfaProperty:valueType>" \
+          "<pdfaProperty:category>external</pdfaProperty:category><pdfaProperty:description>#{description}</pdfaProperty:description></rdf:li>"
+      end
+      <<~XMP
+        <rdf:Description rdf:about="" xmlns:fx="#{FACTUR_X_NAMESPACE}">
+        <fx:DocumentType>INVOICE</fx:DocumentType>
+        <fx:DocumentFileName>#{escape_xml(@factur_x[:filename])}</fx:DocumentFileName>
+        <fx:Version>1.0</fx:Version>
+        <fx:ConformanceLevel>#{@factur_x[:level]}</fx:ConformanceLevel>
+        </rdf:Description>
+        <rdf:Description rdf:about="" xmlns:pdfaExtension="http://www.aiim.org/pdfa/ns/extension/" xmlns:pdfaSchema="http://www.aiim.org/pdfa/ns/schema#" xmlns:pdfaProperty="http://www.aiim.org/pdfa/ns/property#">
+        <pdfaExtension:schemas><rdf:Bag><rdf:li rdf:parseType="Resource">
+        <pdfaSchema:schema>Factur-X PDFA Extension Schema</pdfaSchema:schema>
+        <pdfaSchema:namespaceURI>#{FACTUR_X_NAMESPACE}</pdfaSchema:namespaceURI>
+        <pdfaSchema:prefix>fx</pdfaSchema:prefix>
+        <pdfaSchema:property><rdf:Seq>#{described.join}</rdf:Seq></pdfaSchema:property>
+        </rdf:li></rdf:Bag></pdfaExtension:schemas>
+        </rdf:Description>
+      XMP
+    end
+
+    def escape_xml(text)
+      text.encode(xml: :text)
+    end
+  end
+end

data/lib/gamba/repeater.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Prawn
+  class Document
+    def repeat(page_filter, options = {}, &)
+      repeaters << Repeater.new(self, page_filter, options.fetch(:dynamic, false), &)
+    end
+
+    def number_pages(string, options = {})
+      options = options.dup
+      start_count_at = options.delete(:start_count_at)
+      page_filter = options.key?(:page_filter) ? options.delete(:page_filter) : :all
+      total_pages = options.delete(:total_pages)
+      text_color = options.delete(:color)
+      options[:height] = 50 unless options.key?(:height)
+
+      counting = false
+      pseudo_page = 0
+      (1..page_count).each do |page_number|
+        unless counting
+          pseudo_page =
+            case start_count_at
+            when String then Integer(start_count_at, 10)
+            when (1..) then Integer(start_count_at)
+            else 1
+            end
+        end
+        if page_match?(page_filter, page_number)
+          go_to_page(page_number)
+          fill_color(text_color) unless text_color.nil?
+          total_pages = page_count if total_pages.nil?
+          text_box(string.gsub("<page>", pseudo_page.to_s).gsub("<total>", total_pages.to_s), options)
+          counting = true
+        end
+        pseudo_page += 1 if counting
+      end
+    end
+  end
+
+  # Content drawn on every page matching a filter when the document renders: stamped once, or drawn again on
+  # each page when dynamic.
+  class Repeater
+    class << self
+      attr_writer :count
+
+      def count
+        @count ||= 0
+      end
+    end
+
+    attr_reader :name
+
+    def initialize(document, page_filter, dynamic = false, &block)
+      @document = document
+      @page_filter = page_filter
+      @dynamic = dynamic
+      @stamp_name = "prawn_repeater(#{document.repeaters.size})"
+      @document.create_stamp(@stamp_name, &block) unless dynamic
+      @block = block if dynamic
+      @graphic_state = document.page.graphic_state.dup
+      Repeater.count += 1
+    end
+
+    def match?(page_number)
+      @document.page_match?(@page_filter, page_number)
+    end
+
+    def run(page_number)
+      return unless match?(page_number)
+      return @document.stamp(@stamp_name) unless @dynamic
+      return unless @block
+
+      @document.save_graphics_state(@graphic_state) do
+        @document.__send__(:freeze_stamp_graphics)
+        @block.call
+      end
+    end
+  end
+end

data/lib/gamba/security.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Prawn
+  class Document
+    # The standard security handler, revision 2: 40-bit RC4 (ISO 32000-1 §7.6.3).
+    module Security
+      PERMISSIONS_BITS = {print_document: 3, modify_contents: 4, copy_contents: 5, modify_annotations: 6}.freeze
+      FULL_PERMISSIONS = 0xFFFFFFFF
+      PASSWORD_PADDING = ["28BF4E5E4E758A4164004E56FFFA01082E2E00B6D0683E802F0CA9FE6453697A"].pack("H*").freeze
+      KEY_LENGTH_BYTES = 5
+      private_constant :PERMISSIONS_BITS, :FULL_PERMISSIONS
+
+      def encrypt_document(options = {})
+        raise Errors::PdfAViolation, "PDF/A forbids encryption" if pdf_a?
+
+        Prawn.verify_options(%i[user_password owner_password permissions], options)
+        @user_password = options.delete(:user_password) || ""
+        @owner_password = options.delete(:owner_password) || @user_password
+        @owner_password = Random.bytes(32) if @owner_password == :random
+        self.permissions = options.delete(:permissions) || {}
+        @encryption = Encryption.new(user_password: @user_password, owner_password: @owner_password, permissions: permissions_value)
+      end
+
+      def self.encrypt_string(string, key, identifier, generation)
+        Arcfour.new(object_key(key, identifier, generation)).encrypt(string)
+      end
+
+      # The key of one object: the document key extended with its number and generation (algorithm 1), and with
+      # "sAlT" for AES-128, which only PDF::Core::Decryption reads.
+      def self.object_key(key, identifier, generation, salt = nil)
+        seed = key + [identifier].pack("V")[0, 3] + [generation].pack("V")[0, 2]
+        seed << salt if salt
+        Digest::MD5.digest(seed)[0, key.bytesize + 5]
+      end
+
+      def self.pad_password(password)
+        password = password.b[0, 32]
+        password + PASSWORD_PADDING[0, 32 - password.bytesize]
+      end
+
+      private
+
+      def permissions=(permissions = {})
+        @permissions ||= FULL_PERMISSIONS
+        permissions.each do |key, value|
+          raise ArgumentError, "Unknown permission :#{key}. Valid options: #{PERMISSIONS_BITS.keys.map(&:inspect).join(", ")}" unless PERMISSIONS_BITS[key]
+
+          bit = 1 << (PERMISSIONS_BITS[key] - 1)
+          @permissions = value ? @permissions | bit : @permissions & ~bit
+        end
+      end
+
+      def permissions_value
+        @permissions || FULL_PERMISSIONS
+      end
+    end
+
+    # The keys and dictionary of an encrypted document, which depend on its file identifier.
+    class Encryption
+      def initialize(user_password:, owner_password:, permissions:)
+        @user_password = user_password
+        @owner_password = owner_password
+        @permissions = permissions
+      end
+
+      def owner_password_hash
+        @owner_password_hash ||= begin
+          key = Digest::MD5.digest(Security.pad_password(@owner_password))[0, Security::KEY_LENGTH_BYTES]
+          Arcfour.new(key).encrypt(Security.pad_password(@user_password))
+        end
+      end
+
+      def key(file_identifier)
+        Digest::MD5.digest(Security.pad_password(@user_password) + owner_password_hash + [@permissions].pack("V") + file_identifier)[0, Security::KEY_LENGTH_BYTES]
+      end
+
+      def dictionary(file_identifier)
+        user_password_hash = Arcfour.new(key(file_identifier)).encrypt(Security::PASSWORD_PADDING)
+        {Filter: :Standard, V: 1, R: 2, O: PDF::Core::ByteString.new(owner_password_hash), U: PDF::Core::ByteString.new(user_password_hash),
+         P: [@permissions].pack("L").unpack1("l")}
+      end
+    end
+
+    # RC4, the stream cipher of the standard security handler's first revisions.
+    class Arcfour
+      def initialize(key)
+        @state = (0..255).to_a
+        j = 0
+        key_bytes = key.bytes
+        256.times do |i|
+          j = (j + @state[i] + key_bytes[i % key_bytes.size]) & 0xFF
+          @state[i], @state[j] = @state[j], @state[i]
+        end
+      end
+
+      def encrypt(string)
+        state = @state.dup
+        i = 0
+        j = 0
+        string.b.bytes.map do |byte|
+          i = (i + 1) & 0xFF
+          j = (j + state[i]) & 0xFF
+          state[i], state[j] = state[j], state[i]
+          byte ^ state[(state[i] + state[j]) & 0xFF]
+        end.pack("C*")
+      end
+    end
+  end
+end

data/lib/gamba/stamp.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Prawn
+  # Content drawn once into a form XObject, then placed on any page by name.
+  module Stamp
+    def stamp(name)
+      dictionary_name, dictionary = stamp_dictionary(name)
+      add_content("/#{dictionary_name} Do")
+      annotations = dictionary.data[:Annots]
+      page.dictionary.data[:Annots] = (page.dictionary.data[:Annots] || []) | annotations if annotations&.any?
+      page.xobjects[dictionary_name] = dictionary
+    end
+
+    def stamp_at(name, point, &)
+      translate(point[0], point[1]) { stamp(name) }
+    end
+
+    def create_stamp(name, &)
+      page.stamp_stream(create_stamp_dictionary(name), &)
+    end
+
+    private
+
+    def stamp_dictionary_registry
+      @stamp_dictionary_registry ||= {}
+    end
+
+    def stamp_dictionary(name)
+      raise Errors::InvalidName if name.empty?
+      raise Errors::UndefinedObjectName unless stamp_dictionary_registry.key?(name)
+
+      stamp_dictionary_registry[name].values_at(:stamp_dictionary_name, :stamp_dictionary)
+    end
+
+    def create_stamp_dictionary(name)
+      raise Errors::InvalidName if name.empty?
+      raise Errors::NameTaken if stamp_dictionary_registry.key?(name)
+
+      _left, _bottom, width, height = page.dimensions
+      dictionary = ref!({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height]}, +"")
+      stamp_dictionary_registry[name] = {stamp_dictionary_name: "Stamp#{stamp_dictionary_registry.length + 1}", stamp_dictionary: dictionary}
+      dictionary
+    end
+
+    def freeze_stamp_graphics
+      update_colors
+      write_line_width
+      write_stroke_cap_style
+      write_stroke_join_style
+      write_stroke_dash
+    end
+  end
+
+  module SoftMask
+    def soft_mask(&)
+      min_version(1.4)
+      group_attributes = ref!(Type: :Group, S: :Transparency, CS: :DeviceRGB, I: false, K: false)
+      group = ref!({Type: :XObject, Subtype: :Form, BBox: page.dimensions, Group: group_attributes}, +"")
+      page.stamp_stream(group, &)
+      mask = ref!(Type: :Mask, S: :Luminosity, G: group)
+      graphic_state_dictionary = ref!(Type: :ExtGState, SMask: mask, AIS: false, BM: :Normal, OP: false, op: false, OPM: 1, SA: true)
+
+      registry_key = [page.dimensions, group.stream, page_count].hash
+      @soft_mask_registry ||= {}
+      unless @soft_mask_registry[registry_key]
+        masks = page.resources[:ExtGState] ||= {}
+        name = masks.empty? ? "GS1" : masks.keys.max.succ
+        masks[name] = graphic_state_dictionary
+        @soft_mask_registry[registry_key] = name
+      end
+      add_content("/#{@soft_mask_registry[registry_key]} gs")
+      # Its ExtGState sets the blend mode back to Normal.
+      graphic_state.blend_mode = nil
+    end
+  end
+end