qpdf_ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5f6da89731f271f230b6784f82f01bb4f1dfe4060d4caae6d956fa73d8fc13e
-  data.tar.gz: c3d2e9dc8baf1975acbca704b8b76dab210c0f959ce78b8655d1c3c295585d10
+  metadata.gz: 2c89e78922fbb1a3922b13c425086212a70454a28b6f17f9f75b8fe9ab772256
+  data.tar.gz: 3144ff7e6bae54b2b71fe80bd1b22652b5466120d03cf2fa7f7dcccab15c9d7a
 SHA512:
-  metadata.gz: c850b48c57e89e431b3d7340b1cd4819f28887402cdc03af7e108533249a4e8742351732c22217b0fed011e4799b9b00268219ec2b1ea17d6576ef50125ffbbb
-  data.tar.gz: 60f89a46753d7caa4d70a3832c2dc68bd01470528c5c6c6939df10920608f3e451ed7c11d42874fd6944df1a06bdd4847020e1289fb1b07c100fc502cc48e5ce
+  metadata.gz: 2e6736a64f275a612a85727c94ebe7e5ccde471b5024f974611b6a43ce747ee317f0544769996816f943aff50071e9fcc5eb5e92b08316af921b29cc6dea9c1d
+  data.tar.gz: 8941eff1af71bed2d082e4eb66256d9b284800aa9cfd95100fadc3eeb4888663f647d5f939816b82fbdd6e735b479aff0724ee6fc72ba8931456c6a64c67d822

data/CHANGELOG.md

@@ -1,5 +1,73 @@
-## [Unreleased]
+<!-- generated by git-cliff start -->
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+[unreleased]: https://github.com/dieter-medium/qpdf_ruby/compare/v0.2.0..HEAD
+
+<!-- generated by git-cliff end -->
+
+## [0.2.0] - 2026-10-02
+
+Makes the tagged PDFs Chromium prints (`Page.printToPDF` with `generateTaggedPDF`) PDF/UA-1
+conformant: `apply_pdfua_fixes` plus `ensure_bbox` take Chromium's output to a file veraPDF accepts
+as PDF/UA-1 and PAC 2024 passes without errors.
+
+### 🚀 Added
+
+- `apply_pdfua_fixes(link_texts:, title:)` runs every step below and returns a report.
+- `artifact_tagged_decorations`: CSS backgrounds and borders Chromium tags as content of a
+  grouping element (a `Table`'s cell backgrounds, an `<article>`'s card) become artifacts.
+- `mark_untagged_content_as_artifacts` and `untagged_content`: untagged paths, text, XObjects,
+  shadings and inline images are wrapped in `/Artifact` (7.1-3), never inside tagged content.
+- `describe_links`: Link annotations get `/Contents` (7.18), from given texts, the structure
+  element's `/Alt`, named and string destinations ("Page N"), or the URI.
+- `wrap_list_bodies`: list item content moves into `LBody` (7.2-20), ParentTree updated.
+- `map_nonstandard_roles`: PDF 2.0 structure types get a RoleMap entry (7.1-5).
+- `retag_grouping_figures`: the `Figure` Chromium wraps around an HTML `<figure>` becomes a `Div`
+  (7.3-1); `figures_without_alt` counts what only a person can fix.
+- `add_pdfua_identification(title:)`: XMP `pdfuaid:part` and `dc:title`, `DisplayDocTitle`,
+  `Marked` (7.1-8).
+- `ensure_bbox` computes Figure bounds from the painted content (images, forms, strokes with line
+  width, caps and joins) and sets `Placement /Block` outside a line of text.
+- `parent_tree_mismatches`, `links`, `metadata` and `role_map` for inspection.
+
+### 🐛 Fixed
+
+- `ensure_bbox`: an uninitialized crop box crashed it, the CTM was replaced instead of
+  concatenated, MCIDs were matched across pages and Form XObjects, and `/A` was overwritten.
+- `to_memory` leaked the QPDF buffer behind every call.
+- Ruby exceptions no longer skip C++ destructors, and a `#to_s` callback that reopens the document
+  can no longer leave a freed handle in use.
+- Builds against QPDF 11.9 as well as QPDF 12, and runs on Ruby 4.
+
+### 🛠️ Development
+
+- veraPDF runs in CI (`bin/install-verapdf.sh`); `bin/asan-rspec.sh` runs the specs under
+  AddressSanitizer and LeakSanitizer.
+- `rake release` checks the push credential first, following RubyGems' own order
+  (`GEM_HOST_API_KEY`, `gem.push_key`, push-host key, `rubygems_api_key`).
+- The Docker image is built in two stages and pushed for linux/amd64 and linux/arm64 from `main`
+  and `v*` tags.
+
+
+## [0.1.1] - 2025-06-30
+
+### 🚀 Features
+
+- Add PDF encryption support
+
+
 
 ## [0.1.0] - 2025-06-11
 
 - Initial release
+
+### 🔄 Released
+
+- [unreleased](https://github.com/dieter-medium/qpdf_ruby/compare/v0.2.0..HEAD)
+- [0.2.0](https://github.com/dieter-medium/qpdf_ruby/compare/v0.1.1..v0.2.0)
+- [0.1.1](https://github.com/dieter-medium/qpdf_ruby/compare/v0.1.0..v0.1.1) 

data/README.md

@@ -1,37 +1,73 @@
 # QpdfRuby
 
-> **Patch & polish PDFs so that PAC 2024 finally turns green.**
-
-QpdfRuby is a very small Ruby wrapper around the battle‑tested
-[QPDF \>= 12](https://qpdf.sourceforge.net/) C++ library.  Right now the
-library focuses on only **three specialised tasks** that are needed when
-PDFs are printed from Chromium‑based browsers and subsequently audited
-with the PAC 2024 accessibility checker:
-
-1. **Export the structure tree as XML** – handy for debugging.
-2. **Mark vector path objects as `/Artifact`** so that decorative lines,
-   boxes, &c. are ignored by assistive technologies.
-3. **Add missing `/BBox` entries to every `/Figure` element** (derived
-   from the page’s graphic operators) so that screen readers know the
-   physical extent of each image.
-
-Together these tweaks eliminate the most common complaints PAC 2024 has
-about browser‑generated PDFs.
-
----
-
-## Features in Detail
-
-| Feature                                        | Ruby API                                 |
-| ---------------------------------------------- | ---------------------------------------- |
-| Dump structure tree as XML                     | `doc.show_structure`                     |
-| Mark path objects ( `re … S/s/f/F/B/b` )       | `doc.mark_paths_as_artifacts`            |
-| Ensure `/Figure` elements have a layout BBox¹  | `doc.ensure_bbox`                        |
-
-_¹Internally the gem parses each page’s content stream, maps image
-`/MCID`s to their transformation matrix, computes the bounding box
-(courtesy of a little linear algebra) and finally writes the result into
-the structure tree._
+> **Make Chromium's tagged PDFs PDF/UA-1 conformant.**
+
+QpdfRuby is a small Ruby wrapper around the [QPDF](https://qpdf.sourceforge.net/) C++ library,
+made for PDFs printed by Chromium (`Page.printToPDF` with `generateTaggedPDF`) and checked with
+veraPDF or PAC 2024. Chromium tags the text of a page but leaves gaps that PDF/UA-1 rejects; the
+gem closes them without touching the content that is tagged:
+
+| PDF/UA-1 rule (veraPDF) | What Chromium does | What QpdfRuby does | Ruby API |
+| --- | --- | --- | --- |
+| 7.1-3 untagged content | backgrounds, borders, bars, `aria-hidden` and SVG decorations end up outside any marked content; it never writes `/Artifact` | wraps every painting operation outside marked content in `/Artifact BMC … EMC` (not a Form XObject that carries tagged content) | `doc.mark_untagged_content_as_artifacts` |
+| PAC: content in an inadmissible location, invalid TR | CSS backgrounds and borders are tagged as content of the grouping element they belong to (a `Table`'s cell backgrounds, an `<article>`'s card) | turns such shape-only content into artifacts and takes it out of the structure tree; content with text stays tagged | `doc.artifact_tagged_decorations` |
+| 7.18.1-2, 7.18.5-2 link descriptions | no `/Contents` on Link annotations | your text per URI, else the structure element's `/Alt`/`/ActualText`, else the URI (internal links: your text for `"#<destination>"`, else "Page N" - named destinations from `/Dests`, string destinations from the `/Names` tree) | `doc.describe_links(texts = {})` |
+| 7.2-20 list items | `LI` holds `Lbl` and the content directly, never `LBody` | moves the content into an `LBody`, ParentTree entries updated (a Form XObject's MCIDs in its own entry) | `doc.wrap_list_bodies` |
+| 7.1-5 non-standard types | PDF 2.0 types (`Strong`, `Em`, `Aside`, …) without a RoleMap | maps them to PDF 1.7 types in the RoleMap (table below) | `doc.map_nonstandard_roles` |
+| 7.3-1 figure alternative | an HTML `<figure>` becomes a `Figure` without alt text around the image's own `Figure` | retags that grouping `Figure` as `Div` | `doc.retag_grouping_figures` |
+| 7.1-8 metadata | no XMP `pdfuaid` identification | adds `pdfuaid:part 1` and `dc:title`, each only if missing (read namespace-aware - a commented-out one does not count, an empty one does; extends existing XMP, never replaces a title), sets `DisplayDocTitle` and `Marked` - the identification only for a file with a structure tree | `doc.add_pdfua_identification(title: nil)` |
+
+`doc.apply_pdfua_fixes(link_texts: {}, title: nil)` runs all of them and returns a report.
+Each step only adds what is missing, so running it twice changes nothing (the report's
+`identified` is true only when the identification step changed something). When the file cannot
+be identified - it has no structure tree, or its existing XMP has no RDF element the gem can find -
+the other steps still run and `unidentified_reason` says why; it is `nil` otherwise. Figures that
+have no alternative text at all cannot be fixed by a tool - `doc.figures_without_alt` counts them.
+
+The RoleMap entries `map_nonstandard_roles` adds, each only for a type the file uses and does not
+map yet. Some are lossy - an assistive technology reads `Title` as a paragraph, `Aside` as a
+section:
+
+| PDF 2.0 type | mapped to |
+| --- | --- |
+| `Aside` | `Sect` |
+| `DocumentFragment` | `Part` |
+| `Em`, `Strong`, `Sub` | `Span` |
+| `FENote` | `Note` |
+| `Title` | `P` |
+
+Untagged content is looked for in page content and the Form XObjects it draws - not in annotation
+appearance streams, tiling patterns or Type 3 glyph procedures, which Chromium does not emit.
+
+Also:
+
+| Feature | Ruby API |
+| --- | --- |
+| Count untagged content (dry run, per kind) | `doc.untagged_content` |
+| Add a layout `/BBox` to every `/Figure`¹, and `/Placement /Block` to one outside a line of text (PAC 2024 warns of a "possibly inappropriate use" of a Figure without it) | `doc.ensure_bbox` |
+| Dump the structure tree as XML | `doc.show_structure` |
+| Inspect links, XMP, RoleMap | `doc.links`, `doc.metadata`, `doc.role_map` |
+| Count ParentTree entries that do not name their content's structure element (0 = consistent) | `doc.parent_tree_mismatches` |
+| Encrypt | `doc.encrypt(user_pw:, owner_pw:, …)` |
+| Read/write files or memory | `Document.new(path, password = nil)`, `Document.from_memory(bytes, password = nil)`, `#write(path)`, `#to_memory` |
+
+_¹The gem parses each page's content stream, and the content of the Form XObjects it draws, under
+the full transformation matrix and unites what each piece of marked content paints - images, Form
+XObjects, paths - per page, content stream and MCID (a marked-content reference's `/Stm` names the
+form whose MCIDs it means). A stroked path counts with its line width, caps and joins (from `w`, `J`,
+`j`, `M` or an ExtGState); a curve's stroke is bounded a little generously. Text adds nothing (its extent needs font metrics), and content outside
+the crop box is ignored; a Figure with no other content gets the crop box._
+
+`#mark_paths_as_artifacts` is deprecated: it now does what `#mark_untagged_content_as_artifacts`
+does. Its old behaviour - wrapping rectangles anywhere, also inside tagged content - fixed few
+Chromium decorations and broke rules 7.1-1/7.1-2.
+
+Every error raises `QpdfRuby::Error` (a `RuntimeError`); an argument of the wrong type raises
+`TypeError`, an unknown keyword (`tittle:`) `ArgumentError`.
+
+Checked against veraPDF 1.30.2 on Chromium 154 output (`spec/fixtures/chromium/`): both
+fixtures are PDF/UA-1 compliant after `apply_pdfua_fixes`. A machine check covers the machine
+checkable part only - alternative texts, headings and reading order still need a person.
 
 ---
 
@@ -39,8 +75,8 @@ the structure tree._
 
 ### Requirements
 
-* **Ruby** \>= 3.1
-* **QPDF** \>= 12.0.0 (headers & libs)
+* **Ruby** \>= 3.3 (tested with 3.3, 3.4 and 4.0)
+* **QPDF** \>= 11.9 (headers & libs; tested with 11.9.1 and 12.2)
 
 ### macOS
 ```bash
@@ -50,12 +86,11 @@ bundle config set --local build.qpdf_ruby "--with-qpdf-dir=$(brew --prefix qpdf)
 
 ### Debian/Ubuntu
 ```bash
-# on Debian 11/Ubuntu 20.04 you may need newer packages from testing
+# Debian 13 (trixie) and newer ship QPDF 12
 sudo apt-get update && sudo apt-get install -y libqpdf-dev qpdf
 ```
-If `apt` cannot provide QPDF ≥ 12 you can compile it yourself or pull the
-package from *testing/unstable* – see the [Dockerfile](./docker/Dockerfile) for a working
-`apt preferences` snippet.
+If `apt` cannot provide QPDF ≥ 11.9, compile it yourself or use Debian trixie (see the
+[Dockerfile](./docker/Dockerfile)).
 
 ### Add the gem
 ```bash
@@ -70,24 +105,19 @@ bundle add qpdf_ruby
 ```ruby
 require "qpdf_ruby"
 
-pdf = QpdfRuby::Document.new("input.pdf")
-
-# 1. tag decorative paths
-pdf.mark_paths_as_artifacts
+pdf = QpdfRuby::Document.new("chromium-output.pdf")
 
-# 2. add BBox to every <Figure>
-pdf.ensure_bbox
+report = pdf.apply_pdfua_fixes(
+  link_texts: { "mailto:jana@example.com" => "E-mail Jana" }, # optional, per URI or "#destination"
+  title: "Curriculum vitae - Jana Example"                    # optional, else the PDF's /Title
+)
+# => { decorations: 3, artifacts: { paths: 75, texts: 101, …, total: 176 }, links: 2, list_bodies: 34,
+#      roles: 0, figure_groups: 0, figures_without_alt: 0, identified: true, unidentified_reason: nil }
 
-# 3. introspect structure tree (optional)
-File.write("structure.xml", pdf.show_structure)
-
-# 4. save 🎉
-pdf.write("fixed.pdf")
+pdf.ensure_bbox                     # layout BBoxes for figures (PAC 2024 asks for them)
+pdf.write("accessible.pdf")         # or pdf.to_memory
 ```
 
-Run PAC 2024 on `fixed.pdf` – it should report far fewer (or zero!)
-errors compared to the original browser output.
-
 ---
 
 ## Development
@@ -97,7 +127,17 @@ cd qpdf_ruby
 bin/setup        # install gem + test deps
 autotest         # guard & RSpec
 ```
-* Bump **version.rb** → `bundle exec rake release` to push a new gem.
+* Bump **version.rb** → `bundle exec rake release` to push a new gem. It first runs
+  `rake release_credentials_check`, which shows where the push credential comes from: a set
+  `GEM_HOST_API_KEY` wins (as in RubyGems), else `gem.push_key` in the credentials file RubyGems uses,
+  else that file's key for the push host, else its `rubygems_api_key`.
+* `bundle exec rspec` runs the specs; the veraPDF examples run only where `verapdf` is on the
+  `PATH` (`bin/install-verapdf.sh [DIR]` installs the pinned CLI; needs Java). They are skipped
+  otherwise - `REQUIRE_VERAPDF=1`, set in CI, makes them fail instead.
+* `bin/asan-rspec.sh [RSPEC_ARGS]` builds the extension with AddressSanitizer in a scratch copy and
+  runs the specs under it, with LeakSanitizer (`bin/lsan.supp` filters Ruby's own heap) - the way to
+  see a use-after-free a plain run survives by luck. A destructor skipped by a Ruby raise is the one
+  leak it cannot see; `spec/qpdf_ruby/document_error_path_memory_spec.rb` watches RSS for that.
 
 ### Testing with local QPDF builds
 If you tinker with QPDF itself, point Bundler to your custom prefix:
@@ -119,7 +159,7 @@ Bug reports & pull requests are welcome at
 
 ### Code Style
 * C++ 17, clang‑format enforced
-* Ruby 3.2, rubocop default rules
+* Ruby 3.3, rubocop default rules
 
 ---
 

data/ext/qpdf_ruby/document_handle.cpp

@@ -1,17 +1,22 @@
+#define POINTERHOLDER_TRANSITION 1
+
 #include "document_handle.hpp"
 
 #include <qpdf/QPDFWriter.hh>
+#include <qpdf/QPDF.hh>
 #include <stdexcept>
 #include <system_error>
 #include <cerrno>
 
 using namespace qpdf_ruby;
 
-std::unique_ptr<DocumentHandle> DocumentHandle::open(const std::string& filename) {
+std::unique_ptr<DocumentHandle> DocumentHandle::open(const std::string& filename, std::string const& pwd) {
   auto qpdf = std::make_shared<QPDF>();
   try {
-    // Use empty password → owner & user pwd same.
-    qpdf->processFile(filename.c_str());
+    qpdf->processFile(filename.c_str(), pwd.empty() ? nullptr : pwd.c_str());
+  } catch (const QPDFExc& qex) {
+    throw std::runtime_error(std::string("qpdf_ruby: failed to open \"") + filename + "\": " + qex.what() +
+                             " (code: " + std::to_string(qex.getErrorCode()) + ")");
   } catch (const std::exception& ex) {
     throw std::runtime_error(std::string("qpdf_ruby: failed to open “") + filename + "”: " + ex.what());
   }
@@ -40,6 +45,7 @@ void DocumentHandle::write(const std::string& out_filename) {
     // honour original file’s extension-level features (linearized? encrypted? …)
     QPDFWriter w(*m_qpdf, out_filename.c_str());
     w.setStaticID(true);  // deterministic IDs – helps tests
+    setup_encryption(w);
     w.write();
   } catch (const std::exception& ex) {
     throw std::runtime_error(std::string("qpdf_ruby: failed to write “") + out_filename + "”: " + ex.what());
@@ -50,36 +56,75 @@ std::string DocumentHandle::write_to_memory() {
   try {
     QPDFWriter w(*m_qpdf, nullptr);
     w.setStaticID(true);
+
+    setup_encryption(w);
+
     w.setOutputMemory();
     w.write();
 
-    auto b = w.getBuffer();
+    auto b = w.getBufferSharedPointer();  // getBuffer() hands over a Buffer the caller must delete
     return std::string(reinterpret_cast<char const*>(b->getBuffer()), b->getSize());
   } catch (std::exception const& ex) {
     throw std::runtime_error("qpdf_ruby: write_to_memory failed: " + std::string(ex.what()));
   }
 }
 
+void DocumentHandle::setup_encryption(QPDFWriter& w) const {
+  if (!m_encryption_requested) return;
+
+  switch (m_encrypt_R) {
+    case 4:
+      w.setR4EncryptionParametersInsecure(m_user_pw.c_str(), m_owner_pw.c_str(), m_encrypt_accessibility,
+                                          m_encrypt_allow_extract, m_encrypt_assemble, m_encrypt_annotate_and_form,
+                                          m_encrypt_form_filling, m_encrypt_allow_modify, m_encrypt_allow_print,
+                                          m_encrypt_encrypt_metadata, m_encrypt_use_aes);
+      break;
+    case 5:
+      w.setR5EncryptionParameters(m_user_pw.c_str(), m_owner_pw.c_str(), m_encrypt_accessibility,
+                                  m_encrypt_allow_extract, m_encrypt_assemble, m_encrypt_annotate_and_form,
+                                  m_encrypt_form_filling, m_encrypt_allow_modify, m_encrypt_allow_print,
+                                  m_encrypt_encrypt_metadata);
+      break;
+    case 6:
+      w.setR6EncryptionParameters(m_user_pw.c_str(), m_owner_pw.c_str(), m_encrypt_accessibility,
+                                  m_encrypt_allow_extract, m_encrypt_assemble, m_encrypt_annotate_and_form,
+                                  m_encrypt_form_filling, m_encrypt_allow_modify, m_encrypt_allow_print,
+                                  m_encrypt_encrypt_metadata);
+      break;
+    default:
+      throw std::runtime_error("Unsupported encryption revision (R): Only 4, 5, 6 are supported.");
+  }
+}
+
+void DocumentHandle::set_encryption(const std::string& user_pw, const std::string& owner_pw, int R,
+                                    qpdf_r3_print_e allow_print, bool allow_modify, bool allow_extract,
+                                    bool accessibility, bool assemble, bool annotate_and_form, bool form_filling,
+                                    bool encrypt_metadata, bool use_aes) {
+  m_user_pw = user_pw;
+  m_owner_pw = owner_pw;
+  m_encrypt_R = R;
+  m_encrypt_allow_print = allow_print;
+  m_encrypt_allow_modify = allow_modify;
+  m_encrypt_allow_extract = allow_extract;
+  m_encrypt_accessibility = accessibility;
+  m_encrypt_assemble = assemble;
+  m_encrypt_annotate_and_form = annotate_and_form;
+  m_encrypt_form_filling = form_filling;
+  m_encrypt_encrypt_metadata = encrypt_metadata;
+  m_encrypt_use_aes = use_aes;
+  m_encryption_requested = true;
+}
+
 // ------------------------- C bridge impl --------------------------------
 
 extern "C" {
-DocumentHandle* qpdf_ruby_open(const char* filename) {
-  try {
-    return DocumentHandle::open(filename).release();
-  } catch (const std::exception&) {
-    errno = EIO;
-    return nullptr;
-  }
+DocumentHandle* qpdf_ruby_open(const char* filename, char const* pwd) {
+  return DocumentHandle::open(filename, pwd ? pwd : "").release();
 }
 
 DocumentHandle* qpdf_ruby_open_memory(char const* desc, unsigned char const* buf, size_t len, char const* pwd) {
-  try {
-    std::vector<unsigned char> copy(buf, buf + len);  // simple ownership
-    return DocumentHandle::open_memory(desc, std::move(copy), pwd ? pwd : "").release();
-  } catch (...) {
-    errno = EIO;
-    return nullptr;
-  }
+  std::vector<unsigned char> copy(buf, buf + len);  // simple ownership
+  return DocumentHandle::open_memory(desc, std::move(copy), pwd ? pwd : "").release();
 }
 
 int qpdf_ruby_write(DocumentHandle* handle, const char* out_filename) {
@@ -87,13 +132,20 @@ int qpdf_ruby_write(DocumentHandle* handle, const char* out_filename) {
     errno = EBADF;
     return -1;
   }
-  try {
-    handle->write(out_filename);
-    return 0;
-  } catch (const std::exception&) {
-    errno = EIO;
-    return -1;
-  }
+
+  handle->write(out_filename);
+  return 0;
+}
+
+void qpdf_ruby_set_encryption(DocumentHandle* handle, const char* user_pw, const char* owner_pw, int R,
+                              qpdf_r3_print_e allow_print, int allow_modify, int allow_extract, int accessibility,
+                              int assemble, int annotate_and_form, int form_filling, int encrypt_metadata,
+                              int use_aes) {
+  if (!handle) return;
+
+  handle->set_encryption(std::string(user_pw ? user_pw : ""), std::string(owner_pw ? owner_pw : ""), R, allow_print,
+                         allow_modify != 0, allow_extract != 0, accessibility != 0, assemble != 0,
+                         annotate_and_form != 0, form_filling != 0, encrypt_metadata != 0, use_aes != 0);
 }
 
 void qpdf_ruby_close(DocumentHandle* handle) {

data/ext/qpdf_ruby/document_handle.hpp

@@ -1,8 +1,11 @@
 #pragma once
 
+#define POINTERHOLDER_TRANSITION 1
+
 #include <memory>
 #include <string>
 #include <qpdf/QPDF.hh>
+#include <qpdf/QPDFWriter.hh>
 
 namespace qpdf_ruby {
 
@@ -16,7 +19,7 @@ namespace qpdf_ruby {
 class DocumentHandle final {
  public:
   // ---- factory ----------------------------------------------------------
-  static std::unique_ptr<DocumentHandle> open(const std::string& filename);
+  static std::unique_ptr<DocumentHandle> open(const std::string& filename, std::string const& pwd);
   static std::unique_ptr<DocumentHandle> open_memory(std::string const& description, std::vector<unsigned char> data,
                                                      std::string const& password = "");
 
@@ -26,6 +29,12 @@ class DocumentHandle final {
 
   std::string write_to_memory();
 
+  void set_encryption(const std::string& user_pw, const std::string& owner_pw, int R, qpdf_r3_print_e allow_print,
+                      bool allow_modify, bool allow_extract, bool accessibility = true, bool assemble = true,
+                      bool annotate_and_form = true, bool form_filling = true, bool encrypt_metadata = true,
+                      bool use_aes = true);
+  void setup_encryption(QPDFWriter& w) const;
+
   /** Direct access for C++ helpers that need the raw QPDF. */
   QPDF& qpdf() { return *m_qpdf; }
   const QPDF& qpdf() const { return *m_qpdf; }
@@ -42,11 +51,26 @@ class DocumentHandle final {
 
   std::shared_ptr<QPDF> m_qpdf;
   std::vector<unsigned char> m_owned_buf;
+
+  // --- New encryption settings ---
+  bool m_encryption_requested = false;
+  std::string m_user_pw;
+  std::string m_owner_pw;
+  int m_encrypt_R = 4;
+  qpdf_r3_print_e m_encrypt_allow_print{qpdf_r3p_full};
+  bool m_encrypt_allow_modify = true;
+  bool m_encrypt_allow_extract = true;
+  bool m_encrypt_accessibility = true;
+  bool m_encrypt_assemble = true;
+  bool m_encrypt_annotate_and_form = true;
+  bool m_encrypt_form_filling = true;
+  bool m_encrypt_encrypt_metadata = true;
+  bool m_encrypt_use_aes = true;
 };
 
 extern "C" {
 /** Returns a freshly allocated handle or nullptr on error (see errno). */
-DocumentHandle* qpdf_ruby_open(const char* filename);
+DocumentHandle* qpdf_ruby_open(const char* filename, char const* pwd);
 
 DocumentHandle* qpdf_ruby_open_memory(char const* desc, unsigned char const* buf, size_t len, char const* pwd);
 
@@ -57,4 +81,10 @@ int qpdf_ruby_write(DocumentHandle* handle, const char* out_filename);
 void qpdf_ruby_close(DocumentHandle* handle);
 }
 
+void qpdf_ruby_set_encryption(struct DocumentHandle* handle, const char* user_pw, const char* owner_pw, int R,
+                              qpdf_r3_print_e allow_print,
+                              int allow_modify,  // bool as int (0/1)
+                              int allow_extract, int accessibility, int assemble, int annotate_and_form,
+                              int form_filling, int encrypt_metadata, int use_aes);
+
 }  // namespace qpdf_ruby