Add PDF encryption support and tests (#33)

Introduces password protection (user and owner passwords) for PDFs across Chromium, LibreOffice, and PDF engine options. Adds dedicated encryptPDFs methods to GotenbergClient for both file and URL sources. Updates error handling for missing parameters, extends documentation with encryption usage and best practices, and adds comprehensive tests for encryption features. Also updates Docker image to gotenberg/gotenberg:8.25 and refines docker-compose configuration.

Author: thoven87

README.md

@@ -15,7 +15,8 @@ A modern Swift SDK for [Gotenberg](https://gotenberg.dev/) that provides a type-
 - 📄 **Multiple input formats** (HTML, Markdown, URLs, Office docs)
 - 🖼️ **Screenshot capture** from web pages
 - 📋 **PDF manipulation** (merge, split, metadata)
-- 🔐 **Authentication support** (Basic Auth + custom headers)
+- 🔐 **PDF encryption** (during conversion + dedicated endpoint)
+- 🔑 **Authentication support** (Basic Auth + custom headers)
 - 📱 **Cross-platform** (iOS, macOS, Linux, Windows)
 
 ## Quick Start
@@ -174,7 +175,7 @@ let response = try await client.splitPDF(
 )
 ```
 
-#### PDF Metadata
+### PDF Metadata
 
 Read and write PDF metadata:
 
@@ -196,6 +197,116 @@ let response = try await client.writePDFMetadata(
 )
 ```
 
+### PDF Encryption
+
+GotenbergKit provides two ways to encrypt PDFs with password protection:
+
+#### 1. Encrypt During Conversion
+
+Add password protection while converting documents to PDF:
+
+```swift
+// Encrypt HTML to PDF with both user and owner passwords
+let options = ConversionOptions(
+    userPassword: "user123",     // Password for opening/viewing the PDF
+    ownerPassword: "owner456"    // Password for full access/editing
+)
+
+let response = try await client.convertHTMLToPDF(
+    htmlContent: "<h1>Confidential Document</h1>",
+    options: options
+)
+
+// Encrypt office documents
+let libreOptions = LibreOfficeConversionOptions(
+    password: "source_password",      // Password for opening source file (if encrypted)
+    userPassword: "view_password",    // Password for viewing output PDF
+    ownerPassword: "edit_password"    // Password for editing output PDF
+)
+
+let response = try await client.convertWithLibreOffice(
+    documents: ["confidential.docx": docData],
+    options: libreOptions
+)
+
+// Encrypt when processing existing PDFs
+let pdfOptions = PDFEngineOptions(
+    userPassword: "reader_access",
+    ownerPassword: "full_access"
+)
+
+let encryptedPDF = try await client.mergeWithPDFEngines(
+    documents: ["file1.pdf": data1, "file2.pdf": data2],
+    options: pdfOptions
+)
+```
+
+#### 2. Encrypt Existing PDFs
+
+Use the dedicated encryption endpoint to add password protection to existing PDF files with full metadata override support:
+
+```swift
+// Basic encryption with passwords only
+let encryptedResponse = try await client.encryptPDFs(
+    documents: [
+        "document1.pdf": try Data(contentsOf: pdf1URL),
+        "document2.pdf": try Data(contentsOf: pdf2URL)
+    ],
+    options: PDFEngineOptions(
+        userPassword: "viewer_password",
+        ownerPassword: "admin_password"  // Optional
+    )
+)
+
+// Encrypt with custom metadata override
+let customMetadata = Metadata(
+    author: "Secure Author",
+    copyright: "Company Confidential",
+    creator: "GotenbergKit",
+    marked: true,
+    producer: "Swift PDF Processor",
+    subject: "Encrypted Document",
+    title: "Confidential Report"
+)
+
+let encryptedWithMetadata = try await client.encryptPDFs(
+    documents: ["report.pdf": reportData],
+    options: PDFEngineOptions(
+        metadata: customMetadata,        // Override metadata during encryption
+        userPassword: "user123",
+        ownerPassword: "owner456",
+        flatten: true,                   // Additional PDF processing options
+        pdfua: true
+    )
+)
+
+// Encrypt PDFs from URLs
+let pdfURLs = [
+    DownloadFrom(url: "https://example.com/file1.pdf"),
+    DownloadFrom(url: "https://example.com/file2.pdf")
+]
+
+let encryptedFromURLs = try await client.encryptPDFs(
+    urls: pdfURLs,
+    options: PDFEngineOptions(
+        userPassword: "required_password"
+    )
+)
+```
+
+**Key Features:**
+- **Password Protection**: User password (required) and owner password (optional)
+- **Metadata Override**: Set custom metadata during encryption process
+- **PDF Processing**: Support for flattening, PDF/UA compliance, and format options
+- **Flexible Input**: Encrypt from file data or URLs
+- **Consistent API**: Uses PDFEngineOptions like other PDF operations
+
+**Password Types:**
+- **User Password**: Required to open and view the PDF (required for encryption)
+- **Owner Password**: Required for full access (editing, copying, printing) (optional)
+
+
+
 ### Authentication
 
 #### Basic Authentication
@@ -272,6 +383,48 @@ let response = try await client.convertHTMLToPDF(
 )
 ```
 
+#### Encryption Best Practices
+
+```swift
+// Use strong, unique passwords for conversion
+let options = ConversionOptions(
+    userPassword: generateSecurePassword(length: 12),
+    ownerPassword: generateSecurePassword(length: 16)
+)
+
+// For dedicated encryption endpoint with metadata control
+let encryptionOptions = PDFEngineOptions(
+    metadata: Metadata(
+        author: "Document Owner",
+        copyright: "Confidential",
+        creator: "Secure App",
+        marked: true,
+        subject: "Encrypted Content",
+        title: "Protected Document"
+    ),
+    userPassword: generateSecurePassword(length: 12),
+    ownerPassword: generateSecurePassword(length: 16),
+    flatten: true  // Prevent form modifications
+)
+
+// User password only (allows viewing)
+let viewOnlyOptions = PDFEngineOptions(
+    userPassword: "view_password"
+)
+
+// Both passwords for maximum control
+let secureOptions = PDFEngineOptions(
+    userPassword: "user_access",    // Required to open
+    ownerPassword: "admin_access"   // Full permissions
+)
+
+// Apply encryption to existing PDFs
+let encrypted = try await client.encryptPDFs(
+    documents: ["sensitive.pdf": pdfData],
+    options: encryptionOptions
+)
+```
+
 ## Advanced Features
 
 ### Batch Processing

Sources/GotenbergKit/Chromium/ChromiumOptions.swift

@@ -107,6 +107,10 @@ public struct ChromiumOptions: Sendable {
     public var metadata: Metadata?
     /// Tags provide a logical structure that governs how the content of the PDF is presented through assistive technology
     public var generateTaggedPdf: Bool
+    /// Password for opening the resulting PDF
+    public var userPassword: String?
+    /// Password for full access on the resulting PDF
+    public var ownerPassword: String?
 
     private let logger = Logger(label: "com.gotenbergkit.chromiumoptions")
 
@@ -142,7 +146,9 @@ public struct ChromiumOptions: Sendable {
         pdfFormat: PDFFormat? = nil,
         pdfua: Bool = false,
         metadata: Metadata? = nil,
-        generateTaggedPdf: Bool = false
+        generateTaggedPdf: Bool = false,
+        userPassword: String? = nil,
+        ownerPassword: String? = nil
     ) {
         self.singlePage = singlePage
         self.paperWidth = paperWidth
@@ -176,6 +182,8 @@ public struct ChromiumOptions: Sendable {
         self.pdfua = pdfua
         self.metadata = metadata
         self.generateTaggedPdf = generateTaggedPdf
+        self.userPassword = userPassword
+        self.ownerPassword = ownerPassword
     }
 
     var formValues: [String: String] {
@@ -281,6 +289,14 @@ public struct ChromiumOptions: Sendable {
             }
         }
 
+        if let userPassword = userPassword {
+            values["userPassword"] = userPassword
+        }
+
+        if let ownerPassword = ownerPassword {
+            values["ownerPassword"] = ownerPassword
+        }
+
         return values
     }
 }

Sources/GotenbergKit/Common/GotenbergError.swift

@@ -20,6 +20,7 @@ public enum GotenbergError: Error {
     case paperHeightTooSmall
     case marginTooSmall
     case pageRangeInvalid
+    case missingRequiredParameter(String)
 
     public var errorDescription: String {
         switch self {
@@ -45,6 +46,8 @@ public enum GotenbergError: Error {
             return "Margin must be at least 0 inches"
         case .pageRangeInvalid:
             return "Page range must be in format start-end abd with positive integers for start and end and start <= end."
+        case .missingRequiredParameter(let parameter):
+            return "Missing required parameter: \(parameter)"
         }
     }
 }

Sources/GotenbergKit/LibreOffice/LibreOfficeConversionOptions.swift

@@ -94,6 +94,10 @@ public struct LibreOfficeConversionOptions {
     /// Flatten the resulting PDF.
     /// default false
     public var flatten: Bool
+    /// Password for opening the resulting PDF
+    public var userPassword: String?
+    /// Password for full access on the resulting PDF
+    public var ownerPassword: String?
 
     public struct PageRange {
         public let from: Int
@@ -145,7 +149,9 @@ public struct LibreOfficeConversionOptions {
         pdfFormat: PDFFormat? = nil,
         pdfua: Bool = false,
         metadata: Metadata? = nil,
-        flatten: Bool = false
+        flatten: Bool = false,
+        userPassword: String? = nil,
+        ownerPassword: String? = nil
     ) {
         self.password = password
         self.landscape = landscape
@@ -177,6 +183,8 @@ public struct LibreOfficeConversionOptions {
         self.pdfua = pdfua
         self.metadata = metadata
         self.flatten = flatten
+        self.userPassword = userPassword
+        self.ownerPassword = ownerPassword
     }
 
     /// Convert options to form values for the API request
@@ -258,14 +266,22 @@ public struct LibreOfficeConversionOptions {
                 values["metadata"] = String(decoding: data, as: UTF8.self)
             } catch {
                 logger.error(
-                    "Error serializing metadata",
+                    "Failed to serialize metadata",
                     metadata: [
                         "error": .string(error.localizedDescription)
                     ]
                 )
             }
         }
 
+        if let userPassword = userPassword {
+            values["userPassword"] = userPassword
+        }
+
+        if let ownerPassword = ownerPassword {
+            values["ownerPassword"] = ownerPassword
+        }
+
         return values
     }
 }