Skip to content

server

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

server

README.md

@cloudpdf/server

The self-hostable CloudPDF document engine server: a Fastify-based HTTP/REST API in front of a Node worker_thread pool running native PDFium via @embedpdf/engine-runtime. It executes the same @embedpdf/engine-services code as the local browser engine, so results are identical wherever a document is processed.

Clients speak to it through:

  • @cloudpdf/engine — the browser engine client (Engine v3 over HTTPS), used standalone or injected into the EmbedPDF viewer / @cloudpdf/viewer.
  • @cloudpdf/sdk — the generated API client plus the integrity-pinned upload workflow for backend applications.

Documentation

Deployment and configuration guides: https://www.cloudpdf.com

Upload transport policy

Document uploads use init → transfer → commit. The server pins the expected SHA-256, byte length, and selected transport during init; commit verifies the stored object against that intent.

CLOUDPDF_UPLOAD_PROXY_POLICY controls whether PDF bytes may pass through the API origin:

  • fallback-only (default) prefers a storage-adapter presigned PUT and uses the bounded multipart proxy only when the adapter cannot presign. An explicit request for proxy is rejected when presigning is available.
  • allowed also permits clients to explicitly request the proxy.
  • disabled never accepts proxy uploads; init fails when the storage adapter cannot presign.

Keep the default for compatibility, or use disabled when every configured storage adapter supports presigned uploads. The proxy is still constrained by the server body/file-size limit; it is not an unbounded streaming bypass.

License configuration

The server fails closed when no valid CloudPDF license is available. For a connected development or production license, configure:

export CLOUDPDF_LICENSE_MODE=connected
export CLOUDPDF_LICENSE_KEY='your-key-or-secret://-reference'
cloudpdf-server license status

Do not commit a license key or paste it into CI logs. secret:// references can be resolved through the server's configured secrets provider.

The production licensing identity is compiled into the package. Connected validation goes to https://api.keygen.sh, and aggregated usage reporting, when required by the signed license metadata, goes to https://api.cloudpdf.com. These hosts, the CloudPDF product ID, and the Ed25519 verification key cannot be replaced with environment variables.

Every successful connected decision must have a fresh Keygen response signature bound to the request nonce, deployment fingerprint, CloudPDF product, account, and license key. The exact signed proof is encrypted in the license-state database and its signature is verified again before cache or offline-grace access is granted. Unsigned, stale, replayed, modified, or operator-authored database values never grant full access.

Air-gapped deployments use cloudpdf-server license request and cloudpdf-server license install; the installed machine certificate is verified against the same compiled CloudPDF identity on every refresh.

License

The source is Fair Source under FCL-1.0-ALv2, but the server is commercially licensed at runtime. Running it requires a valid CloudPDF license key or a signed certificate for an air-gapped deployment. The license-key functionality may not be removed, changed, disabled, or circumvented. See LICENSE for the authoritative terms.