DOCSEARCHbyAlgolia
Submit Docs

Stirling PDF

repository·main·Indexed 10 days ago

https://github.com/stirling-tools/stirling-pdf

An open-source, privacy-focused PDF manipulation platform providing over 50 tools for editing, converting, and automating PDF workflows via a web UI, desktop client, or REST API. Includes developer documentation for deployment via Docker and Taskfile, RAG capabilities using PydanticAI, and backend license management.

Tokens
71.3K
Snippets
182
Records
301
Agent score
100%

What's inside Stirling PDF

  1. Overview of Stirling PDF capabilities

    main

    Stirling PDF is an open-source PDF platform designed for privacy and automation. It can be used as a desktop application, a browser-based UI, or a self-hosted server with a private API.

    Key features include:

    • 50+ PDF tools: Capabilities such as editing, merging, splitting, signing, redacting, converting, OCR, and compression.
    • Automation: No-code pipelines within the UI and REST APIs for high-volume processing.
    • Enterprise features: Support for SSO, auditing, and on-premise deployment.
    • Developer-centric: REST APIs are available for nearly all tools to allow integration into existing systems.

  2. Overview of the Shared Signing Feature

    main

    The Shared Signing feature allows a document owner to initiate collaborative signing workflows with multiple participants. Participants can access documents via secure UUID tokens (requiring no authentication) or via authenticated sign-request APIs for registered users.

    Key Capabilities:

    • Multi-participant sessions: Manage multiple signers for a single document.
    • Digital Signatures: Supports P12/PKCS12, JKS, SERVER, USER_CERT, and PEM/UPLOAD formats.
    • Wet Signature Overlays: Participants can provide visual signatures by drawing, typing, or uploading an image (supports multiple overlays per participant).
    • Progress Tracking: Owners can monitor the status of each participant (PENDING, VIEWED, SIGNED, or DECLINED).
    • Security: Automatic role downgrade (e.g., from COMMENTER to VIEWER) after a participant has signed or declined, and GDPR-compliant metadata cleanup for wet signatures.

  3. Review Stirling PDF Subprocessors and Data Processing

    main

    Stirling PDF uses several subprocessors to provide its services. For SaaS users, customer files are processed within Stirling's infrastructure. For self-hosted or air-gapped deployments, customer files remain entirely within the customer's environment, with Stirling only receiving license-validation and metering data (process counts, file sizes, and file hashes, but never file names or content).

    Key Data Handling Principles:

    • AI Features: These are optional and can be disabled. When enabled, AI providers (Anthropic, Voyage AI) receive only the document text or excerpts required for the specific feature, never the entire file.
    • AI Training: Contractually, AI providers do not use customer data for model training.
    • Payments: Payment card details are handled directly by Stripe, which acts as an independent controller.

    Subprocessor List:

    SubprocessorPurposeData processedLocation
    Amazon Web Services (AWS)Cloud infrastructure and storageCustomer files (encrypted at rest), account and usage dataUnited States
    StripePayment processingBilling contact and transaction dataUnited States
    SupabaseAccount and workspace data infrastructureAccount, workspace, and configuration dataUnited States
    GoogleTransactional and operational email deliveryNames, email addresses, message content of service emailsUnited States
    AnthropicAI models (Claude) for Stirling Agent/AI featuresPrompts and document text/excerpts (never whole files)United States
    Voyage AIEmbedding models for Ingestion/RAGExtracted text excerpts (never customer files)United States
    PostHogProduct telemetry and usage analyticsPseudonymous usage events and diagnostic dataEuropean Union (EU-hosted)

  4. Access the Stirling PDF Developer Guide Directory

    main
    The devGuide/ directory serves as the central repository for technical development documentation. It is organized into core development guides (setup, architecture, task management, exception handling, i18n, and encryption) and feature-specific documentation (agents and user guides).

  5. How the Type3 font library works at runtime

    main

    The Type3 font library is designed to eliminate the PDType3Font.encode limitation.

    When a font entry is correctly registered in app/core/src/main/resources/type3/library/index.json, the backend performs the following automatically:

    1. PDF $\rightarrow$ JSON: The backend identifies the font via its signature and attaches the corresponding TTF/OTF.
    2. Caching: It caches a normalized PDFont.
    3. JSON $\rightarrow$ PDF: It uses the cached font for regeneration, ensuring edited text remains visually identical to the original Type3 output.

  6. Understand Audit Levels

    main

    Stirling PDF supports four audit levels that determine the granularity of logged data:

    • Level 0: OFF: Disables all audit logging except critical security events. Recommended for development only.
    • Level 1: BASIC: Logs authentication events (login, logout, failed logins), password changes, user/role changes, system configuration changes, and HTTP request errors (status codes >= 400).
    • Level 2: STANDARD (Default): Includes everything in BASIC, plus all HTTP requests (URL, method, status), file operations (upload, download, process), PDF operations, and user operations.
    • Level 3: VERBOSE: Includes everything in STANDARD, plus request headers, parameters, method parameters, operation results, and detailed timing information.

  7. Naming conventions for extension modules

    main

    When creating extension modules and exporting functions or hooks, follow these naming rules to maintain architectural integrity:

    • Name by behavior, not by build: Modules and exports should be named after what they do, not which build target (e.g., desktop, saas) overrides them. Core code should remain unaware of the specific build target.
    • Avoid build-specific conditionals: Core code should never contain checks like if (isDesktop) or if (isTauri()). If behavior needs to vary, the variation should be encapsulated within an extension module that the core simply calls.

    Correct vs. Incorrect Examples:

    TypeExampleReason
    ✅ CorrectuseFrontendVersionInfo()Named after the behavior.
    ❌ WronguseDesktopVersionInfo()Core code reveals knowledge of the desktop layer.
    ❌ Wrongif (isDesktop())Indicates the extension point is not modeled correctly.

  8. Internationalise (i18n) error messages

    main

    To ensure error messages are translatable and centrally managed, follow this workflow:

    1. Define the Source: Add the English phrase to the primary translation file: messages_en_US.properties.
    2. Reference by Key: In your Java, JavaScript, or Python code, reference the specific message key instead of hard-coding the string.
    3. Translate: Update the corresponding language files for other supported languages using the same keys.

  9. Understand the Shared Signing Workflow Process

    main

    The lifecycle of a shared signing session follows these stages:

    1. Session Creation (Owner): The owner creates a session and defines participants. The system generates a unique shareToken for each participant.
    2. Participant Access: Participants access the document using their shareToken (token-based) or via the sign-requests API (if authenticated).
    3. Signature Submission: Participants submit their digital certificates or visual wet signatures (drawn, typed, or uploaded).
    4. Progress Tracking (Owner): The owner monitors the session status (e.g., 2/5 signatures collected) via the ActiveSessionsPanel.
    5. Session Finalization: Once all required signatures are collected, the owner triggers the finalization process. The system applies all signatures to the PDF and can optionally append a signature summary page.

  10. Understand Stirling PDF Metering and PDF Processes

    main

    Stirling PDF uses a drawdown model based on PDF Processes rather than a simple file count. Your Committed Volume (purchased PDFs per year) is converted into a total allowance of PDF Processes based on your selected governance posture.

    Conversion Schedule

    PosturePDF Processes per PDF
    Essentials2
    Governed4
    Regulated7

    What counts as a PDF Process?

    • One policy execution
    • One pipeline run (regardless of the number of operations in the chain)
    • One Stirling Agent returned artifact (regardless of the number of messages produced)
    • Data Processing increments (see below)

    Note: Failed processes that do not complete are not counted. Reprocessing the same file or duplicate submissions are counted. Counts are whole numbers with no rounding.

    Data Processing (File Size Increments)

    Large files consume additional processes based on size:

    • The first 25 MB (decimal) of a file is included at no additional drawdown.
    • Each additional 25 MB or part thereof (rounded up per file) draws down one (1) additional PDF Process.

    Calculation Example (Governed Posture)

    If you have a 60 MB file running four Governed policies:

    1. Base processes: 4 policies $\times$ 4 (Governed rate) = 16 processes.
    2. Data processing: 60 MB total - 25 MB free = 35 MB extra. 35 MB requires two 25 MB increments (rounded up) = 2 processes.
    3. Total drawdown: 18 PDF Processes.

  11. Logical operators in Bulk Selection Expressions

    main

    You can combine page selections using logical operators. The order of precedence (from highest to lowest) is:

    1. ! (NOT)
    2. & or and (AND)
    3. , or | or or (OR)

    Use parentheses (...) to override this precedence.

    ### Operators
- **OR (union)**: `,` | `|` | `or` 
- **AND (intersection)**: `&` | `and` 
- **NOT (complement)**: `!` | `not` 

### Precedence Example
- `1-10 & (even, 15)` selects even pages between 1 and 10.
- `!(1-5, odd)` removes pages 1-5 and all odd pages from the document.

  12. Understand File Sharing Architecture and Roles

    main

    Stirling-PDF's File Sharing feature allows users to store files server-side and share them via direct user-to-user permissions or token-based share links.

    Access Roles

    Permissions are governed by three roles:

    • EDITOR: Can read and write (replace) file content.
    • COMMENTER: Can read and submit signing actions (annotations), but cannot replace the file content.
    • VIEWER: Read-only access.

    Note on Signing Workflows: In the context of the signing workflow, COMMENTER is distinct from VIEWER because it allows the user to submit a signature. Once a participant has signed or declined, their role is automatically downgraded to VIEWER.

    Storage Providers

    You can configure the backend storage via storage.provider:

    • local: Files are stored on the filesystem under storage.local.basePath (default: ./storage).
    • database: Files are stored as BLOBs in the stored_file_blobs table.