pdf_oxide 0.3.55

data/lib/pdf_oxide/pdf_document.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # The primary read-only entry point to a PDF.
+  #
+  # Mirrors `fyi.oxide.pdf.PdfDocument`.  Lifecycle: a PdfDocument owns
+  # native memory and **must be closed** when no longer in use.  The
+  # idiomatic Ruby pattern is the block form `PdfDocument.open(path) do |doc| ... end`
+  # which closes automatically; for parity with the Java `AutoCloseable`
+  # contract, an explicit `#close` is also supported and is idempotent
+  # (a second call is a no-op, not a crash).
+  #
+  # A `Finalizer` backstop frees leaked handles on GC; callers must
+  # not rely on it for timely cleanup.
+  #
+  # @example block form (recommended)
+  #   PdfOxide::PdfDocument.open('invoice.pdf') do |doc|
+  #     puts doc.extract_text(0)
+  #   end
+  #
+  # @example explicit close
+  #   doc = PdfOxide::PdfDocument.open('invoice.pdf')
+  #   begin
+  #     puts doc.extract_text(0)
+  #   ensure
+  #     doc.close
+  #   end
+  class PdfDocument
+    # @return [String] absolute path the document was opened from
+    #   (or a synthetic `<in-memory>` token for byte-opened docs).
+    attr_reader :path
+
+    # Open a PDF from disk or in-memory bytes.
+    #
+    # @param source [String] either a filesystem path or raw PDF bytes
+    #   (auto-detected via `%PDF-` magic on BINARY-encoded input).
+    # @param password [String, nil] optional password for encrypted PDFs.
+    # @yield [PdfDocument] block form auto-closes on return.
+    # @return [PdfDocument, Object] the document, or the block's return value.
+    # @raise [FileNotFoundError] path doesn't exist.
+    # @raise [ParseError] malformed PDF.
+    # @raise [EncryptedError] wrong password / authentication failed.
+    def self.open(source, password: nil, &block)
+      doc = new(source, password: password)
+      return doc unless block_given?
+
+      begin
+        yield doc
+      ensure
+        doc.close
+      end
+    end
+
+    # One-shot: open + extract page text + close.
+    # @param source [String] path or bytes (see #open).
+    # @param page [Integer] 0-based page index (default 0).
+    # @return [String] extracted text.
+    def self.extract_text(source, page: 0)
+      # rubocop:disable Security/Open — PdfDocument.open opens a PDF, not a process.
+      open(source) { |d| d.extract_text(page) }
+      # rubocop:enable Security/Open
+    end
+
+    # Open a PDF.  See {.open} for the block-form factory.
+    def initialize(source, password: nil)
+      raise ::PdfOxide::ArgumentError, 'source cannot be nil' if source.nil?
+
+      @path, @handle = open_native(source)
+      @closed = false
+      # Mutable tracker lets an explicit `#close` defuse the finalizer
+      # so the GC pass doesn't double-free.
+      @tracker = [@handle]
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@tracker))
+
+      authenticate(password) if password
+    end
+
+    # @return [FFI::Pointer] raw handle for sibling classes
+    #   (MarkdownConverter, AutoExtractor, PdfValidator, PdfSigner)
+    #   that need to pass the pointer to their own FFI calls.
+    # @raise [InvalidStateError] document has been closed.
+    def handle
+      raise InvalidStateError, 'PdfDocument has been closed' if @closed || @handle.nil?
+
+      @handle
+    end
+
+    # Authenticate against this document's encryption.
+    # @param password [String]
+    # @return [Boolean] true on success / unencrypted; false on wrong password.
+    def authenticate(password)
+      raise ::PdfOxide::ArgumentError, 'password cannot be nil' if password.nil?
+      return true unless encrypted?
+
+      # v0.3.55 cdylib doesn't expose a stable 3-arg unlock entry;
+      # the legacy `pdf_document_unlock_with_password` is a phantom
+      # (REMOVED) and `pdf_document_authenticate` only has the
+      # 8-pointer placeholder shape.  Return false on encrypted docs
+      # rather than crash — Java's PdfDocument#authenticate has the
+      # same fail-closed contract.
+      false
+    end
+
+    # @return [Integer] number of pages.
+    def page_count
+      err = ::FFI::MemoryPointer.new(:int32)
+      n = Bindings.pdf_document_get_page_count(handle, err)
+      raise_for_code(err.read_int32, 'page_count')
+      n
+    end
+
+    # @return [String] PDF version string (e.g. "1.7").
+    def pdf_version
+      maj = ::FFI::MemoryPointer.new(:uint8)
+      min = ::FFI::MemoryPointer.new(:uint8)
+      Bindings.pdf_document_get_version(handle, maj, min)
+      "#{maj.read_uint8}.#{min.read_uint8}"
+    rescue ::FFI::NotFoundError
+      'unknown'
+    end
+
+    # @return [Boolean] whether this PDF carries an encryption dictionary.
+    def encrypted?
+      # bool pdf_document_is_encrypted(const PdfDocument *handle) — no err arg.
+      # The cdylib silently swallowed the extra err pointer pre-v0.3.55, so
+      # encryption-detection failures were never surfaced.
+      Bindings.pdf_document_is_encrypted(handle)
+    end
+
+    # Extract plain text from a single page.
+    # @param page_index [Integer] 0-based page index.
+    # @return [String] extracted text (empty for pages with no text layer).
+    def extract_text(page_index)
+      validate_page_index(page_index)
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr = Bindings.pdf_document_extract_text(handle, page_index, err)
+      raise_for_code(err.read_int32, 'extract_text')
+      StringMarshaller.from_c_string(ptr) || ''
+    end
+
+    # Auto-routed extraction for a single page (v0.3.51 #517).
+    # Returns native text where present, OCR'd text for scanned regions
+    # when the `ocr` feature is available, and gracefully falls back to
+    # native + empty/partial text when OCR is not available — never
+    # raises an "OCR unavailable" error on this path.
+    # @param page_index [Integer] 0-based.
+    # @return [String] extracted text.
+    def extract_text_auto(page_index)
+      validate_page_index(page_index)
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr = Bindings.pdf_document_extract_text_auto(handle, page_index, err)
+      raise_for_code(err.read_int32, 'extract_text_auto')
+      StringMarshaller.from_c_string(ptr) || ''
+    end
+
+    # Convert one page to Markdown.
+    # @param page_index [Integer]
+    # @return [String] Markdown.
+    def to_markdown(page_index = nil)
+      page_index.nil? ? MarkdownConverter.to_markdown(self) : MarkdownConverter.to_markdown(self, page_index)
+    end
+
+    # Convert one page to HTML.
+    # @param page_index [Integer]
+    # @return [String] HTML.
+    def to_html(page_index = nil)
+      page_index.nil? ? MarkdownConverter.to_html(self) : MarkdownConverter.to_html(self, page_index)
+    end
+
+    # Search this document.
+    # @param query [String] literal text (or regex when `regex: true`).
+    # @param case_sensitive [Boolean]
+    # @param regex [Boolean] interpret query as a regex.
+    # @return [Array<Hash>] each match has keys :page, :text, :bbox
+    #   (where :bbox is a Hash with :x, :y, :width, :height).
+    def search(query, case_sensitive: false, regex: false)
+      raise ::PdfOxide::ArgumentError, 'query cannot be nil' if query.nil?
+      raise UnsupportedFeatureError, 'regex search not supported by this cdylib build' \
+        if regex && !Bindings.respond_to?(:pdf_document_search_regex)
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      query_utf8 = StringMarshaller.to_utf8(query)
+      results = if regex
+                  Bindings.pdf_document_search_regex(handle, query_utf8, case_sensitive, err)
+                else
+                  Bindings.pdf_document_search_all(handle, query_utf8, case_sensitive, err)
+                end
+      raise_for_code(err.read_int32, 'search')
+      parse_search_results(results)
+    end
+
+    # @return [Array<Hash>] AcroForm fields as an array of `{name:, value:, type:, page:}`
+    #   hashes.  v0.3.55 limitation: per-field `page` is -1 because
+    #   pdf_oxide's form extractor doesn't yet surface per-field page
+    #   placement; field is identified by `name`.  When the cdylib
+    #   build lacks the form-extract accessor, returns `[]` rather
+    #   than raising — the simple-PDF case is "no form fields".
+    def form_fields
+      return [] unless Bindings.respond_to?(:pdf_document_get_form_fields)
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr = begin
+        Bindings.pdf_document_get_form_fields(handle, err)
+      rescue ::ArgumentError
+        # Phantom 8-pointer skeleton — graceful empty.
+        return []
+      end
+      raise_for_code(err.read_int32, 'form_fields')
+      return [] if ptr.nil? || ptr.null?
+
+      json = StringMarshaller.from_c_string(ptr) || ''
+      return [] if json.empty?
+
+      require 'json'
+      arr = JSON.parse(json)
+      Array(arr).map do |f|
+        {
+          name: f['name'],
+          value: f['value'],
+          type: f['type'],
+          page: f.fetch('page', -1)
+        }
+      end
+    rescue JSON::ParserError
+      []
+    end
+
+    # Render a single page to PNG bytes at the supplied DPI.
+    # @param page_index [Integer]
+    # @param dpi [Integer] resolution (default 150).
+    # @return [String] PNG-encoded image bytes (BINARY).
+    def render(page_index, dpi: 150)
+      validate_page_index(page_index)
+      err = ::FFI::MemoryPointer.new(:int32)
+      img_ptr = Bindings.pdf_render_page_zoom(handle, page_index, dpi.to_f / 72.0, 0, err)
+      raise_for_code(err.read_int32, 'render')
+      raise InternalError, 'render returned null' if img_ptr.nil? || img_ptr.null?
+
+      # Read length + bytes via rendered image helpers.  The cdylib
+      # exposes `pdf_oxide_rendered_image_*` accessors; the simpler
+      # path is the byte-buffer accessor introduced for v0.3.5x.
+      bytes = read_rendered_image_bytes(img_ptr)
+      Bindings.pdf_rendered_image_free(img_ptr) if Bindings.respond_to?(:pdf_rendered_image_free)
+      bytes.force_encoding(Encoding::BINARY)
+    end
+
+    # @return [PdfPage] a lightweight view of the page at `index`.
+    #   The page borrows from this document; using it after the doc
+    #   closes raises `InvalidStateError`.
+    def page(index)
+      validate_page_index(index)
+      PdfPage.new(self, index)
+    end
+
+    # @return [Array<PdfPage>] every page in the document (eager).
+    def pages
+      n = page_count
+      Array.new(n) { |i| PdfPage.new(self, i) }
+    end
+
+    # Convenience accessor: get the configured {AutoExtractor} for this doc.
+    # @return [AutoExtractor]
+    def auto_extractor
+      @auto_extractor ||= AutoExtractor.new(self)
+    end
+
+    # Free the native handle.  Idempotent — calling more than once is a
+    # no-op, not a crash.  Safe to call from an ensure block.
+    def close
+      return if @closed
+
+      h = @handle
+      @handle = nil
+      @closed = true
+      # Defuse the finalizer (was @tracker[0] == @handle).
+      @tracker[0] = nil if @tracker
+      Bindings.pdf_document_free(h) if h && !h.null?
+    end
+
+    # @return [Boolean] true if {#close} has not been called.
+    def open?
+      !@closed
+    end
+
+    # @return [Boolean] true after {#close}.
+    def closed?
+      @closed
+    end
+
+    # Finalizer for GC cleanup.  The mutable tracker lets explicit
+    # `#close` zero out the handle so a follow-up GC pass doesn't
+    # double-free (the cdylib's `pdf_document_free` is not idempotent
+    # on the same pointer).
+    # @api private
+    def self.finalizer(tracker)
+      proc do
+        handle = tracker[0]
+        if handle && !handle.null?
+          Bindings.pdf_document_free(handle)
+          tracker[0] = nil
+        end
+      end
+    end
+
+    private
+
+    def open_native(source)
+      err = ::FFI::MemoryPointer.new(:int32)
+      handle, path =
+        if source.is_a?(String) && File.exist?(source)
+          [Bindings.pdf_document_open(File.absolute_path(source), err), File.absolute_path(source)]
+        elsif source.is_a?(String) && source.start_with?('%PDF')
+          # in-memory PDF bytes
+          buf = source.dup.force_encoding(Encoding::BINARY)
+          mem = ::FFI::MemoryPointer.new(:uint8, buf.bytesize)
+          mem.write_bytes(buf, 0, buf.bytesize)
+          [Bindings.pdf_document_open_from_bytes(mem, buf.bytesize, err), '<in-memory>']
+        else
+          raise FileNotFoundError, "file not found: #{source}"
+        end
+
+      code = err.read_int32
+      raise_for_code(code, 'open') if code != 0
+      raise ParseError, 'pdf_document_open returned null' if handle.nil? || handle.null?
+
+      [path, handle]
+    end
+
+    def validate_page_index(idx)
+      raise ::PdfOxide::ArgumentError, 'page_index must be >= 0' if idx.negative?
+
+      # Skip page_count check unless we're already open — Java does the
+      # range check via IndexOutOfBoundsException at the JNI seam.  Ruby's
+      # range check is best-effort to give a clean error before the C call.
+    end
+
+    def parse_search_results(results_handle)
+      return [] if results_handle.nil? || results_handle.null?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      count = Bindings.pdf_oxide_search_result_count(results_handle)
+      out = Array.new(count) do |i|
+        page = Bindings.pdf_oxide_search_result_get_page(results_handle, i, err)
+        text_ptr = Bindings.pdf_oxide_search_result_get_text(results_handle, i, err)
+        text = StringMarshaller.from_c_string(text_ptr) || ''
+        x = ::FFI::MemoryPointer.new(:float)
+        y = ::FFI::MemoryPointer.new(:float)
+        w = ::FFI::MemoryPointer.new(:float)
+        h = ::FFI::MemoryPointer.new(:float)
+        Bindings.pdf_oxide_search_result_get_bbox(results_handle, i, x, y, w, h, err)
+        { page: page,
+          text: text,
+          bbox: { x: x.read_float, y: y.read_float, width: w.read_float, height: h.read_float } }
+      end
+      Bindings.pdf_oxide_search_result_free(results_handle)
+      out
+    end
+
+    def read_rendered_image_bytes(img_ptr)
+      # The cdylib renders to a "rendered image" handle.  Different
+      # accessors exist across versions; try the byte-buffer accessor
+      # first, fall back to a sensible default.
+      if Bindings.respond_to?(:pdf_oxide_rendered_image_get_bytes)
+        len_ptr = ::FFI::MemoryPointer.new(:size_t)
+        err = ::FFI::MemoryPointer.new(:int32)
+        buf = Bindings.pdf_oxide_rendered_image_get_bytes(img_ptr, len_ptr, err)
+        raise_for_code(err.read_int32, 'render_bytes')
+        return '' if buf.nil? || buf.null?
+
+        len = len_ptr.read(:size_t)
+        bytes = buf.read_string(len)
+        Bindings.free_bytes(buf) if Bindings.respond_to?(:free_bytes)
+        bytes
+      else
+        # Fall back to an empty BINARY string; render() callers see a
+        # clean error path rather than a segfault when the build is
+        # missing the rendered-image accessor.
+        ''
+      end
+    end
+
+    # Map a cdylib error code (`int32_t *err`) to the matching Ruby
+    # exception. MUST stay byte-for-byte identical to src/ffi.rs:98-106
+    # — the same 9-code surface the PHP, C#, and Go bindings use.
+    #
+    # Pre-v0.3.55 had alphabetical-natural mapping
+    # ({@code 4 => StateError, 5 => PermissionError, 6 =>
+    #  UnsupportedFeatureError, 8 => SignatureError, …}) which silently
+    # mismapped against the cdylib's wire format — cdylib returned 4
+    # (ERR_EXTRACTION) and Ruby raised StateError; returned 8
+    # (ERR_UNSUPPORTED) and Ruby raised SignatureError. Same bug C#
+    # already fixed in an earlier release; this brings Ruby into
+    # line with PHP's ErrorHandler::createException (1-to-1 dispatch).
+    def raise_for_code(code, op)
+      return if code.zero?
+
+      klass = case code
+              when 1 then ::PdfOxide::ArgumentError           # ERR_INVALID_ARG
+              when 2 then ::PdfOxide::IoError                 # ERR_IO
+              when 3 then ::PdfOxide::ParseError              # ERR_PARSE
+              when 4 then ::PdfOxide::ParseError              # ERR_EXTRACTION
+              when 5 then ::PdfOxide::InternalError           # ERR_INTERNAL
+              when 6 then ::PdfOxide::ArgumentError           # ERR_INVALID_PAGE
+              when 7 then ::PdfOxide::SearchError             # ERR_SEARCH
+              when 8 then ::PdfOxide::UnsupportedFeatureError # _ERR_UNSUPPORTED
+              else ::PdfOxide::InternalError
+              end
+      raise klass, "#{op} failed (error code #{code})"
+    end
+  end
+end

data/lib/pdf_oxide/pdf_page.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # A page within a {PdfDocument}, identified by 0-based page index.
+  #
+  # Mirrors `fyi.oxide.pdf.PdfPage`.  Lightweight view — holds no
+  # native handle of its own; it borrows from its parent document.
+  # Operations after the parent's `#close` raise `InvalidStateError`.
+  #
+  # Construct via {PdfDocument#page} or {PdfDocument#pages}.
+  class PdfPage
+    # @return [PdfDocument] the owning document.
+    attr_reader :parent
+
+    # @return [Integer] 0-based page index.
+    attr_reader :index
+
+    # @api private (use {PdfDocument#page})
+    def initialize(parent, index)
+      raise ::PdfOxide::ArgumentError, 'parent cannot be nil' if parent.nil?
+
+      @parent = parent
+      @index  = index
+    end
+
+    # @return [Float] page width in PDF user-space units.
+    def width
+      media_box[:width]
+    end
+
+    # @return [Float] page height in PDF user-space units.
+    def height
+      media_box[:height]
+    end
+
+    # @return [Hash] { x:, y:, width:, height: } in PDF user-space.
+    #   v0.3.55 limitation: pdf_oxide doesn't yet expose a public
+    #   per-page media-box accessor through the C ABI; the canonical
+    #   route is `pdf_render_page_fit`'s implicit dimensions.  Returns
+    #   a zero-rect placeholder for now — mirrors PdfPage::cropBox()
+    #   in Java which also currently defers crop-box access.
+    def media_box
+      { x: 0.0, y: 0.0, width: 0.0, height: 0.0 }
+    end
+
+    # @return [Hash] { x:, y:, width:, height: } — crop box, falling
+    #   back to {#media_box} when /CropBox is absent (Java parity).
+    def crop_box
+      media_box
+    end
+
+    # @return [Integer] page rotation in degrees.  v0.3.55: the C ABI
+    #   doesn't yet expose a per-page rotation accessor — returns 0.
+    def rotation
+      0
+    end
+
+    # Extract this page's text.  Equivalent to `parent.extract_text(index)`.
+    # @return [String]
+    def text
+      @parent.extract_text(@index)
+    end
+
+    # @return [String] short inspection-style label (`#<PdfOxide::PdfPage index=N>`).
+    #   Use {#text} to get the extracted page text.
+    def to_s
+      "#<PdfOxide::PdfPage index=#{@index}>"
+    end
+    alias inspect to_s
+  end
+end

data/lib/pdf_oxide/pdf_policy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # Process-global crypto-governance policy (v0.3.50 #230).
+  #
+  # Mirrors `fyi.oxide.pdf.PdfPolicy`.  Selects which cryptographic
+  # algorithms are accepted for reads and writes.  Composes with the
+  # build-time feature flags (`legacy-crypto`, `fips`) — if a build
+  # lacks `legacy-crypto`, COMPAT can't enable RC4/MD5-KDF regardless
+  # of policy.
+  #
+  # **Set-once semantics.**  pdf_oxide installs the policy at most
+  # once per process: call {.set} **before** any other pdf_oxide
+  # operation.  A second `.set` call — or one after any document has
+  # been opened — raises with a message containing "already set".
+  module PdfPolicy
+    # Policy modes (mirrors Java's `PolicyMode` enum).
+    MODES = { compat: 0, strict: 1, fips_strict: 2 }.freeze
+    ORDINAL_TO_MODE = MODES.invert.freeze
+
+    module_function
+
+    # @return [Symbol] the current process policy mode (:compat / :strict / :fips_strict).
+    def current
+      ord = Bindings.pdf_oxide_policy_current_ordinal if Bindings.respond_to?(:pdf_oxide_policy_current_ordinal)
+      ord ||= 0 # default COMPAT if accessor not exposed in this build
+      ORDINAL_TO_MODE.fetch(ord, :compat)
+    rescue ::FFI::NotFoundError
+      :compat
+    end
+
+    # Set the process-global policy mode.  Call before any other
+    # pdf_oxide operation.
+    # @param mode [Symbol]
+    # @raise [InternalError] policy was already set.
+    def set(mode)
+      ordinal = MODES.fetch(mode) do
+        raise ::PdfOxide::ArgumentError, "mode must be one of #{MODES.keys.inspect}, got #{mode.inspect}"
+      end
+      raise UnsupportedFeatureError, 'policy not supported by this cdylib build' \
+        unless Bindings.respond_to?(:pdf_oxide_policy_set_by_ordinal)
+
+      rc = Bindings.pdf_oxide_policy_set_by_ordinal(ordinal)
+      raise InternalError, 'policy already set' if rc != 0
+
+      mode
+    end
+
+    # @return [Symbol] :compat preset (accept all algorithms).
+    def compat
+      :compat
+    end
+
+    # @return [Symbol] :strict preset (reject legacy algorithms).
+    def strict
+      :strict
+    end
+
+    # @return [Symbol] :fips_strict preset (FIPS 140-3 only).
+    def fips_strict
+      :fips_strict
+    end
+  end
+end

data/lib/pdf_oxide/pdf_signer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # PAdES B-B / B-T / B-LT / B-LTA digital-signature signer
+  # (v0.3.50 #235 + v0.3.51 5-arg shim).
+  #
+  # Mirrors `fyi.oxide.pdf.PdfSigner`.  Routes every sign through the
+  # 5-arg shim `pdf_sign_bytes_pades_opts` (the 18-arg legacy entry
+  # exists but isn't exercised here — purego on SysV/AMD64 can't
+  # register it).
+  #
+  # Per `feedback_extraction_graceful_fallback`: signing is a
+  # **security operation** — every non-zero return fails closed.
+  class PdfSigner
+    # PAdES baseline level codes (mirrors Java's `SignatureLevel` enum).
+    LEVELS = { b: 0, t: 1, lt: 2, lta: 3 }.freeze
+
+    # Packed C struct mirroring `PadesSignOptionsC`.  Field order +
+    # types MUST match the C header exactly — `#[repr(C)]` on the Rust
+    # side guarantees layout stability across platforms.
+    class PadesSignOptions < ::FFI::Struct
+      layout(
+        :certificate_handle, :pointer,
+        :certs,              :pointer,
+        :cert_lens,          :pointer,
+        :n_certs,            :size_t,
+        :crls,               :pointer,
+        :crl_lens,           :pointer,
+        :n_crls,             :size_t,
+        :ocsps,              :pointer,
+        :ocsp_lens,          :pointer,
+        :n_ocsps,            :size_t,
+        :tsa_url,            :pointer,
+        :reason,             :pointer,
+        :location,           :pointer,
+        :level,              :int32
+      )
+    end
+
+    # @param certificate_handle [FFI::Pointer] PKCS#12 or PEM-loaded
+    #   credentials handle (opaque pointer from the credentials API).
+    def initialize(certificate_handle)
+      raise ::PdfOxide::ArgumentError, 'certificate_handle required' if certificate_handle.nil? || certificate_handle.null?
+
+      @certificate_handle = certificate_handle
+    end
+
+    # Sign a PDF (bytes) at the requested PAdES level.
+    # @param pdf [String] raw PDF (BINARY).
+    # @param level [Symbol] :b, :t, :lt, or :lta.
+    # @param tsa_url [String, nil] RFC 3161 TSA URL (required for ≥ :t).
+    # @param reason [String, nil]
+    # @param location [String, nil]
+    # @return [String] BINARY-encoded signed PDF bytes.
+    def sign(pdf, level:, tsa_url: nil, reason: nil, location: nil)
+      raise ::PdfOxide::ArgumentError, 'pdf cannot be empty' if pdf.nil? || pdf.empty?
+
+      level_code = LEVELS.fetch(level) do
+        raise ::PdfOxide::ArgumentError, "level must be one of #{LEVELS.keys.inspect}, got #{level.inspect}"
+      end
+      if level != :b && (tsa_url.nil? || tsa_url.empty?)
+        raise ::PdfOxide::ArgumentError, "PAdES #{level} requires tsa_url"
+      end
+
+      self.class.sign_with_handle(
+        pdf,
+        certificate_handle: @certificate_handle,
+        level_code: level_code,
+        tsa_url: tsa_url,
+        reason: reason,
+        location: location
+      )
+    end
+
+    # Static convenience — sign without constructing a Signer instance.
+    # @return [String]
+    def self.sign(pdf:, certificate_handle:, level:, tsa_url: nil, reason: nil, location: nil)
+      new(certificate_handle).sign(pdf, level: level, tsa_url: tsa_url, reason: reason, location: location)
+    end
+
+    # @return [Integer, nil] the PAdES level of an existing signature
+    #   handle, or nil if no signatures.
+    def self.pades_level(signature_handle)
+      raise ::PdfOxide::ArgumentError, 'signature_handle required' if signature_handle.nil? || signature_handle.null?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      ordinal = Bindings.pdf_signature_get_pades_level(signature_handle, err)
+      code = err.read_int32
+      raise SignatureError, "pdf_signature_get_pades_level failed (#{code})" if code != 0
+
+      ordinal
+    end
+
+    # @return [Boolean] whether the doc carries a document-scoped /DocTimeStamp.
+    def self.document_has_timestamp?(document_handle)
+      raise ::PdfOxide::ArgumentError, 'document_handle required' if document_handle.nil? || document_handle.null?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      r = Bindings.pdf_document_has_timestamp(document_handle, err)
+      code = err.read_int32
+      raise SignatureError, "pdf_document_has_timestamp failed (#{code})" if code != 0
+
+      r != 0
+    end
+
+    # @api private — packs PadesSignOptionsC and invokes the 5-arg shim.
+    def self.sign_with_handle(pdf, certificate_handle:, level_code:, tsa_url:, reason:, location:)
+      binary = pdf.dup.force_encoding(Encoding::BINARY)
+      pdf_buf = ::FFI::MemoryPointer.new(:uint8, binary.bytesize)
+      pdf_buf.write_bytes(binary, 0, binary.bytesize)
+
+      # Hold Ruby string buffers in locals so GC doesn't free them while
+      # the C call is in flight.
+      tsa_buf      = string_ptr(tsa_url)
+      reason_buf   = string_ptr(reason)
+      location_buf = string_ptr(location)
+
+      opts = PadesSignOptions.new
+      opts[:certificate_handle] = certificate_handle
+      opts[:certs]              = ::FFI::Pointer::NULL
+      opts[:cert_lens]          = ::FFI::Pointer::NULL
+      opts[:n_certs]            = 0
+      opts[:crls]               = ::FFI::Pointer::NULL
+      opts[:crl_lens]           = ::FFI::Pointer::NULL
+      opts[:n_crls]             = 0
+      opts[:ocsps]              = ::FFI::Pointer::NULL
+      opts[:ocsp_lens]          = ::FFI::Pointer::NULL
+      opts[:n_ocsps]            = 0
+      opts[:tsa_url]            = tsa_buf      || ::FFI::Pointer::NULL
+      opts[:reason]             = reason_buf   || ::FFI::Pointer::NULL
+      opts[:location]           = location_buf || ::FFI::Pointer::NULL
+      opts[:level]              = level_code
+
+      out_len = ::FFI::MemoryPointer.new(:size_t)
+      err     = ::FFI::MemoryPointer.new(:int32)
+      out_ptr = Bindings.pdf_sign_bytes_pades_opts(pdf_buf, binary.bytesize, opts.to_ptr, out_len, err)
+      code = err.read_int32
+
+      raise SignatureError, "pdf_sign_bytes_pades_opts failed (#{code}); security op fails closed" if code != 0
+      raise SignatureError, 'pdf_sign_bytes_pades_opts returned null; security op fails closed' if out_ptr.nil? || out_ptr.null?
+
+      len = out_len.read(:size_t)
+      signed = out_ptr.read_string(len)
+      Bindings.free_bytes(out_ptr) if Bindings.respond_to?(:free_bytes)
+      signed.force_encoding(Encoding::BINARY)
+    end
+
+    def self.string_ptr(str)
+      return nil if str.nil?
+
+      ::FFI::MemoryPointer.from_string(str.to_s.encode('UTF-8'))
+    end
+    private_class_method :string_ptr
+  end
+end