Skip to content

The Open Source DocuSign Alternative.

feat: add CSC AES/QES signing (v1 instance-wide config) (#2874)

Lucas Smithd5ce222482c2
diff --git a/.env.example b/.env.example
index f723e1c66..aa6565f8c 100644
--- a/.env.example
+++ b/.env.example
@@ -48,7 +48,7 @@ NEXT_PRIVATE_DATABASE_URL="postgres://documenso:[email protected]:54320/documen
NEXT_PRIVATE_DIRECT_DATABASE_URL="postgres://documenso:[email protected]:54320/documenso"
# [[SIGNING]]
-# The transport to use for document signing. Available options: local (default) | gcloud-hsm
+# The transport to use for document signing. Available options: local (default) | gcloud-hsm | csc
NEXT_PRIVATE_SIGNING_TRANSPORT="local"
# OPTIONAL: The passphrase to use for the local file-based signing transport.
NEXT_PRIVATE_SIGNING_PASSPHRASE=
@@ -70,6 +70,14 @@ NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_FILE_PATH=
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTS=
# OPTIONAL: The Google Secret Manager path to retrieve the certificate for the gcloud-hsm signing transport.
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH=
+# OPTIONAL: The base URL of the Cloud Signature Consortium (CSC) provider for the csc signing transport.
+NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL=
+# OPTIONAL: The OAuth client ID registered with the CSC provider for the csc signing transport.
+NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID=
+# OPTIONAL: The OAuth client secret registered with the CSC provider for the csc signing transport.
+NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET=
+# OPTIONAL: Default signature level for envelopes created on a CSC instance when the caller doesn't specify one. Available options: AES (default) | QES. Explicit AES/QES requests always pass through unchanged.
+NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL=
# OPTIONAL: Comma-separated list of timestamp authority URLs for PDF signing (enables LTV and archival timestamps).
NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY=
# OPTIONAL: Contact info to embed in PDF signatures. Defaults to the webapp URL.
diff --git a/apps/docs/content/docs/self-hosting/configuration/environment.mdx b/apps/docs/content/docs/self-hosting/configuration/environment.mdx
index 1d57b5062..33f723c31 100644
--- a/apps/docs/content/docs/self-hosting/configuration/environment.mdx
+++ b/apps/docs/content/docs/self-hosting/configuration/environment.mdx
@@ -186,9 +186,9 @@ Documenso requires a certificate to digitally sign documents.
### Transport Selection
-| Variable | Description | Default |
-| -------------------------------- | ---------------------------------------- | ------- |
-| `NEXT_PRIVATE_SIGNING_TRANSPORT` | Signing backend: `local` or `gcloud-hsm` | `local` |
+| Variable | Description | Default |
+| -------------------------------- | ------------------------------------------------- | ------- |
+| `NEXT_PRIVATE_SIGNING_TRANSPORT` | Signing backend: `local`, `gcloud-hsm`, or `csc` | `local` |
### Local Signing
@@ -210,11 +210,36 @@ Documenso requires a certificate to digitally sign documents.
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTS` | Base64-encoded certificate chain |
| `NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH` | Google Secret Manager path for certificate retrieval |
+### Cloud Signature Consortium (CSC)
+
+Routes signing through a third-party Trust Service Provider for Advanced and Qualified Electronic Signatures (AES/QES). Instance-wide; set `NEXT_PRIVATE_SIGNING_TRANSPORT=csc` to enable. See [CSC (AES / QES)](/docs/self-hosting/configuration/signing-certificate/csc-qes) for the full setup walkthrough.
+
+CSC mode requires an active [Enterprise Edition](/docs/policies/enterprise-edition) license. Without a valid license, the instance will refuse to start in `csc` mode.
+
+| Variable | Description | Default |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL` | Base URL of the CSC provider's API | |
+| `NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID` | OAuth client ID registered with the CSC provider | |
+| `NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET` | OAuth client secret registered with the CSC provider | |
+| `NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL` | Default legal tier for new envelopes when the caller doesn't specify one. `AES` or `QES`. Explicit requests pass through. | `AES` |
+
+The OAuth callback URL registered with the CSC provider is fixed at `${NEXT_PUBLIC_WEBAPP_URL}/api/csc/oauth/callback` — register this exact URL with the TSP.
+
+#### Derived Public Variables
+
+The following client-visible variable is **derived automatically** from the private transport at server startup. Do not set it manually — any value set in the environment is overwritten on boot.
+
+| Variable | Derived from | Value |
+| ------------------------------------- | -------------------------------------------------- | ------------------------------------------------- |
+| `NEXT_PUBLIC_SIGNING_TRANSPORT_IS_CSC` | `NEXT_PRIVATE_SIGNING_TRANSPORT === 'csc'` | `'true'` when CSC mode is active, else `'false'` |
+
+The authoring UI uses this flag to gate features that AES/QES envelopes cannot support (parallel signing, assistant role, dictate next signer). Deriving it from the private transport prevents the client-side flag from drifting from the real server-side configuration.
+
### Signature Options
| Variable | Description | Default |
| ------------------------------------------- | ----------------------------------------------------------- | ---------- |
-| `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` | Comma-separated timestamp authority URLs for LTV signatures | |
+| `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` | Comma-separated timestamp authority URLs for LTV signatures. Optional for `local` / `gcloud-hsm` (signatures omit the timestamp when unset). **Required** when `NEXT_PRIVATE_SIGNING_TRANSPORT=csc` — the instance refuses to start without it. See [CSC (AES / QES)](/docs/self-hosting/configuration/signing-certificate/csc-qes#timestamp-authority-resolution). | |
| `NEXT_PUBLIC_SIGNING_CONTACT_INFO` | Contact info embedded in PDF signatures | Webapp URL |
| `NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER` | Use `adbe.pkcs7.detached` instead of `ETSI.CAdES.detached` | `false` |
diff --git a/apps/docs/content/docs/self-hosting/configuration/signing-certificate/csc-qes.mdx b/apps/docs/content/docs/self-hosting/configuration/signing-certificate/csc-qes.mdx
new file mode 100644
index 000000000..0495430d7
--- /dev/null
+++ b/apps/docs/content/docs/self-hosting/configuration/signing-certificate/csc-qes.mdx
@@ -0,0 +1,213 @@
+---
+title: CSC (AES / QES)
+description: Configure Cloud Signature Consortium signing for Advanced and Qualified Electronic Signatures via a third-party Trust Service Provider.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+The `csc` signing transport routes signatures through a third-party Trust Service Provider (TSP) using the [Cloud Signature Consortium API v1.0.4.0](https://cloudsignatureconsortium.org/). Each recipient authenticates directly with the TSP (Strong Customer Authentication) and the TSP returns a per-recipient signature bound to the document hash. Documenso assembles the resulting PAdES signature inside the PDF.
+
+This transport enables **Advanced Electronic Signatures (AES)** and **Qualified Electronic Signatures (QES)** under eIDAS. See [Signature Levels](/docs/compliance/signature-levels) for the legal framework.
+
+<Callout type="warn">
+ CSC mode is **instance-wide**: one CSC provider per Documenso install. All envelopes created
+ while the instance runs in `csc` mode use AES or QES. Switching `NEXT_PRIVATE_SIGNING_TRANSPORT`
+ is a one-way operational migration — see [Switching Transports](#switching-transports).
+</Callout>
+
+<Callout type="warn">
+ CSC mode requires an active [Enterprise Edition](/docs/policies/enterprise-edition) license. The
+ instance refuses to start in `csc` mode without it.
+</Callout>
+
+## Prerequisites
+
+{/* prettier-ignore */}
+<Steps>
+<Step>
+
+### A TSP account
+
+Establish a relationship with a CSC-compatible Trust Service Provider. The TSP issues qualified or advanced certificates to your signers, holds the private keys in its HSM, and exposes a CSC v1.0.4.0-compliant API.
+
+</Step>
+<Step>
+
+### OAuth client credentials
+
+Register Documenso as an OAuth client with the TSP. You will receive a client ID and client secret, and must supply Documenso's callback URL when registering:
+
+```
+${NEXT_PUBLIC_WEBAPP_URL}/api/csc/oauth/callback
+```
+
+The callback URL is fixed — Documenso derives it from `NEXT_PUBLIC_WEBAPP_URL` and the route mount path. There is no env var to override it; ensuring the registered URL matches your instance's webapp URL exactly is the operator's responsibility.
+
+</Step>
+<Step>
+
+### Enterprise Edition license
+
+CSC mode is gated by the `instanceCscSigning` license flag. Without a valid Enterprise license, the transport refuses to start (`CSC_UNLICENSED`).
+
+</Step>
+<Step>
+
+### S3 storage (strongly recommended)
+
+CSC produces multiple `DocumentData` rows per envelope item (one per recipient signature, plus the materialised and source rows). Database-backed storage base64-inflates each row by ~33% and is impractical at meaningful PDF sizes. Configure [S3 storage](/docs/self-hosting/configuration/storage) before enabling CSC.
+
+</Step>
+</Steps>
+
+## Environment Variables
+
+| Variable | Description | Default |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `NEXT_PRIVATE_SIGNING_TRANSPORT` | Set to `csc` | |
+| `NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL` | Base URL of the CSC provider's API | |
+| `NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID` | OAuth client ID registered with the CSC provider | |
+| `NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET` | OAuth client secret registered with the CSC provider | |
+| `NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL` | Default legal tier for new envelopes when the caller does not specify one. `AES` or `QES`. Explicit requests always pass through. | `AES` |
+| `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` | **Required.** Comma-separated RFC 3161 TSA URLs. Always used for B-LTA archival timestamps at seal time, and also serves as the B-T sign-time fallback when the TSP does not expose `signatures/timestamp`. The instance refuses to start in CSC mode without it. See [Timestamp Authority Resolution](#timestamp-authority-resolution). | |
+
+<Callout type="info">
+ `NEXT_PUBLIC_SIGNING_TRANSPORT_IS_CSC` is set automatically from
+ `NEXT_PRIVATE_SIGNING_TRANSPORT` at server startup. Do not set it manually — see
+ [Environment Variables](/docs/self-hosting/configuration/environment#derived-public-variables).
+</Callout>
+
+## Configuration Example
+
+```bash
+NEXT_PRIVATE_SIGNING_TRANSPORT=csc
+NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL=https://api.example-tsp.com/csc/v1
+NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID=documenso-prod
+NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET=...
+NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL=QES
+NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY=http://timestamp.example.com
+```
+
+Register `${NEXT_PUBLIC_WEBAPP_URL}/api/csc/oauth/callback` (e.g. `https://sign.example.com/api/csc/oauth/callback`) as the OAuth callback URL with the TSP.
+
+## Default Signature Level
+
+`NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL` selects the legal tier applied to envelopes that do not specify one explicitly. It is a default, not a capability gate: callers may still create AES or QES envelopes explicitly regardless of this setting.
+
+| Configured value | Caller passes nothing | Caller passes `AES` | Caller passes `QES` |
+| ---------------- | --------------------- | ------------------- | ------------------- |
+| `AES` (default) | Envelope is `AES` | Envelope is `AES` | Envelope is `QES` |
+| `QES` | Envelope is `QES` | Envelope is `AES` | Envelope is `QES` |
+
+Any value other than `AES` or `QES` causes the instance to refuse to start. This prevents silent qualified-to-advanced downgrades from a typo.
+
+## Timestamp Authority Resolution
+
+AES/QES envelopes use TSA-attested timestamps in two distinct phases. Resolution differs per phase.
+
+### Sign time — PAdES B-T per recipient
+
+Each recipient's CMS embeds a signature timestamp (CMS unsigned attribute) so proven time is bound to the recipient's signature itself. Resolution order:
+
+1. If the TSP advertises `signatures/timestamp` in its `info` response (CSC §11.10), the TSP endpoint is used. The call is authorised with **this recipient's** service-scope bearer token — the same one authorising the `signatures/signHash` call alongside it.
+2. Otherwise, the first URL from `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is used (RFC 3161 over HTTP).
+
+Selection is made at boot from the discovered transport, not at runtime; there is no try-then-fall-through. If the chosen source fails, the recipient's sign attempt fails.
+
+### Seal time — PAdES B-LTA archival
+
+The seal-document job emits a single archival `/DocTimeStamp` over the fully-signed envelope (plus DSS for the existing signatures and the timestamp's own chain). This phase is **env-only**: the first URL from `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is always used.
+
+The archival anchor is the operator's long-term trust anchor and SHOULD point at a dedicated qualified archival TSA (e.g. DigiCert) independent of the per-recipient TSP. We deliberately do not fall back to the TSP at seal time: archive longevity should not be coupled to a TSP that may rotate or revoke, and the seal-document job has no recipient context to carry a service-scope bearer.
+
+### Boot-time guard
+
+The instance refuses to start in CSC mode unless `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is set (`CSC_PROVIDER_NO_TSA` at transport construction). The env var is required unconditionally — even when the TSP advertises its own `signatures/timestamp`, seal-time B-LTA archival uses the env TSA. Catching this at boot prevents the failure mode where an envelope signs successfully at B-T and then hangs in `WAITING_FOR_SIGNATURE_COMPLETION` when the seal job throws.
+
+## Switching Transports
+
+`NEXT_PRIVATE_SIGNING_TRANSPORT` is a one-way operational migration. Existing envelopes route per the `signatureLevel` column they were created with — the runtime branching looks at the envelope, not the env var. After a switch:
+
+- Envelopes already at `SES` continue to use the new transport for sealing, but the new transport's signer must produce SES-compatible signatures (only `local` and `gcloud-hsm` qualify).
+- Envelopes already at `AES` / `QES` will fail at sign or seal time if the new transport is not `csc`.
+
+Plan migrations during a quiet window with no in-flight envelopes.
+
+## Behavioural Notes
+
+CSC mode changes a number of envelope-authoring behaviours that operators should communicate to users.
+
+### Mutation lock at distribution
+
+For AES/QES envelopes, all authoring routes refuse mutations once the envelope leaves DRAFT. This locks the PDF before any recipient begins Strong Customer Authentication, closing the PDF-swap window that would otherwise allow an owner to replace the PDF between view and sign and break the legal "what you see is what you sign" guarantee.
+
+In practice: edit envelope, recipients, fields, and items freely while DRAFT; once sent, no changes are accepted (including from the API).
+
+### Sequential signing only
+
+Parallel signing produces conflicting incremental updates over the same base PDF, breaking the per-recipient `/ByteRange` invariant. The signing order is forced to `SEQUENTIAL` on AES/QES envelopes — at the schema layer, at send time, and in the UI (the parallel-signing toggle is hidden).
+
+### Assistant role and Dictate Next Signer disabled
+
+Both features modify the recipient set after the envelope is sent, which is incompatible with the AES/QES mutation lock. They are hidden in the UI and rejected at the server schema layer.
+
+### Sidecar PDFs at download
+
+The signed PDF must remain byte-identical to what each recipient's TSP signature authorised — Documenso cannot decorate it after signing. Audit logs and the Certificate of Completion are generated on demand and delivered as separate PDFs:
+
+- `GET /sign/{token}/download` returns the signed PDF only (or a ZIP for multi-item envelopes).
+- `GET /sign/{token}/download?version=bundle` returns a ZIP containing the signed PDFs, audit log PDF, and Certificate of Completion.
+- The completion email attaches all three.
+
+## Recipient Flow
+
+For context when supporting end users, here is what a recipient experiences on an AES/QES envelope:
+
+1. Opens the email link, lands on the signing page.
+2. Documenso redirects to the TSP for Strong Customer Authentication (first visit only; cached for the session lifetime).
+3. Fills fields as normal.
+4. Clicks Sign → redirected to the TSP for a second authentication round (issues a per-document Signature Activation Data token).
+5. Returns to Documenso; the signing call completes within ~15 seconds.
+6. Sees the standard completion screen.
+
+If the TSP returns no eligible credentials for the recipient (e.g. they have not enrolled), they see a blocking page directing them to enrol with the TSP and retry.
+
+## Error Codes
+
+CSC-specific error codes surfaced through the standard error channels:
+
+| Code | Meaning | Recovery |
+| -------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
+| `CSC_UNLICENSED` | License flag absent at transport-create | Operator: enable Enterprise Edition, restart |
+| `CSC_PROVIDER_INFO_FAILED` | `info` discovery failed at startup | Operator: check TSP availability and `NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL` |
+| `CSC_PROVIDER_NO_TSA` | `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is unset | Operator: configure `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` |
+| `CSC_CREDENTIAL_LIST_EMPTY`| TSP returned no credentials for the user | Recipient: enrol with the TSP |
+| `CSC_CERT_INVALID` | Certificate refused at credential validation | Recipient: contact the TSP |
+| `CSC_ALGORITHM_REFUSED` | Signature algorithm fails policy | Operator/recipient: TSP does not meet policy (see below) |
+| `CSC_SAD_EXPIRED_PRE_SIGN` | Signature Activation Data expired before signing | Recipient: retry from Sign |
+| `CSC_TSP_TIMEOUT` | 15-second synchronous timeout reached | Recipient: retry (idempotent — the TSP enforces single-use SAD binding) |
+| `CSC_EMBED_FAILED` | Sign-time digest diverged from prep capture | Recipient: retry from Sign |
+| `CSC_BASE_DOCUMENT_MUTATED`| Document data changed between prep and sign | Operator: investigate (structural guard violation) |
+| `CSC_INSTANCE_MODE_MISMATCH`| Envelope created with wrong level for transport | Caller: use a level matching the instance transport |
+| `CSC_REQUEST_FAILED` | TSP HTTP transport failure — network error, non-2xx, or malformed response | Operator: check TSP availability; carries the TSP HTTP status and error in the message |
+
+## Algorithm Policy
+
+Documenso refuses TSP credentials that do not meet the following minimums, at the OAuth callback boundary and again at sign time:
+
+| Class | Allowed | Refused |
+| ----- | ---------------------------------- | ------------------------------------------------------ |
+| RSA | `key.len >= 2048` | Missing `key.len`, `key.len < 2048` |
+| ECDSA | P-256, P-384, P-521 | Missing `key.curve`, P-192, P-224, other curves |
+| Hash | SHA-256, SHA-384, SHA-512 | SHA-1, MD5 |
+| Other | — | DSA |
+
+This is the union of CSC v1.0.4.0 §11.5 requirements and current cryptographic guidance.
+
+## Related
+
+- [Signature Levels](/docs/compliance/signature-levels) — AES / QES legal framework
+- [Signing Certificate](/docs/self-hosting/configuration/signing-certificate) — overview of all signing transports
+- [Environment Variables](/docs/self-hosting/configuration/environment) — full env reference
+- [Enterprise Edition](/docs/policies/enterprise-edition) — license requirements
diff --git a/apps/docs/content/docs/self-hosting/configuration/signing-certificate/index.mdx b/apps/docs/content/docs/self-hosting/configuration/signing-certificate/index.mdx
index 89a12a327..a2d5a0a7c 100644
--- a/apps/docs/content/docs/self-hosting/configuration/signing-certificate/index.mdx
+++ b/apps/docs/content/docs/self-hosting/configuration/signing-certificate/index.mdx
@@ -24,6 +24,11 @@ Self-hosted Documenso instances require a signing certificate. You can generate
description="Hardware-based key protection with Google Cloud KMS."
href="/docs/self-hosting/configuration/signing-certificate/google-cloud-hsm"
/>
+ <Card
+ title="CSC (AES / QES)"
+ description="Route signing through a third-party Trust Service Provider for Advanced and Qualified Electronic Signatures."
+ href="/docs/self-hosting/configuration/signing-certificate/csc-qes"
+ />
<Card
title="Timestamp Server"
description="Add trusted timestamps and customise signature appearance."
@@ -38,7 +43,7 @@ Self-hosted Documenso instances require a signing certificate. You can generate
## Certificate Options
-<Tabs items={['Self-Signed', 'CA-Issued', 'Google Cloud HSM']}>
+<Tabs items={['Self-Signed', 'CA-Issued', 'Google Cloud HSM', 'CSC (AES / QES)']}>
<Tab value="Self-Signed">
A self-signed certificate is sufficient for most use cases where your industry has no special signing regulations.
@@ -79,6 +84,18 @@ For organisations requiring hardware-based key protection, Documenso supports Go
See [Google Cloud HSM](/docs/self-hosting/configuration/signing-certificate/google-cloud-hsm) for setup instructions.
+</Tab>
+<Tab value="CSC (AES / QES)">
+
+For Advanced and Qualified Electronic Signatures under eIDAS, Documenso integrates with third-party Trust Service Providers via the Cloud Signature Consortium API. Each recipient authenticates directly with the TSP, which holds the private key and issues the signature.
+
+- Per-recipient identity verification by an accredited TSP
+- Legally equivalent to a handwritten signature within the EU (QES)
+- Requires an [Enterprise Edition](/docs/policies/enterprise-edition) license
+- Instance-wide setting; one CSC provider per Documenso install
+
+See [CSC (AES / QES)](/docs/self-hosting/configuration/signing-certificate/csc-qes) for setup instructions.
+
</Tab>
</Tabs>
diff --git a/apps/docs/content/docs/self-hosting/configuration/signing-certificate/meta.json b/apps/docs/content/docs/self-hosting/configuration/signing-certificate/meta.json
index d37038af3..b52f83f9e 100644
--- a/apps/docs/content/docs/self-hosting/configuration/signing-certificate/meta.json
+++ b/apps/docs/content/docs/self-hosting/configuration/signing-certificate/meta.json
@@ -1,4 +1,4 @@
{
"title": "Signing Certificate",
- "pages": ["...index", "local", "google-cloud-hsm", "timestamp-server", "troubleshooting"]
+ "pages": ["...index", "local", "google-cloud-hsm", "csc-qes", "timestamp-server", "troubleshooting"]
}
diff --git a/apps/remix/app/components/general/direct-template/direct-template-page.tsx b/apps/remix/app/components/general/direct-template/direct-template-page.tsx
index 24753f7e0..9f6ea47dc 100644
--- a/apps/remix/app/components/general/direct-template/direct-template-page.tsx
+++ b/apps/remix/app/components/general/direct-template/direct-template-page.tsx
@@ -13,7 +13,7 @@ import { msg } from '@lingui/core/macro';
import { useLingui } from '@lingui/react';
import type { Field, Recipient } from '@prisma/client';
import { useState } from 'react';
-import { useNavigate, useSearchParams } from 'react-router';
+import { useSearchParams } from 'react-router';
import { useRequiredDocumentSigningAuthContext } from '~/components/general/document-signing/document-signing-auth-provider';
import { useRequiredDocumentSigningContext } from '~/components/general/document-signing/document-signing-provider';
@@ -37,7 +37,6 @@ export const DirectTemplatePageView = ({
directTemplateRecipient,
directTemplateToken,
}: DirectTemplatePageViewProps) => {
- const navigate = useNavigate();
const [searchParams] = useSearchParams();
const { _ } = useLingui();
@@ -119,7 +118,7 @@ export const DirectTemplatePageView = ({
if (redirectUrl) {
window.location.href = redirectUrl;
} else {
- await navigate(`/sign/${token}/complete`);
+ window.location.href = `/sign/${token}/complete`;
}
} catch (err) {
const error = AppError.parseError(err);
diff --git a/apps/remix/app/components/general/document-signing/csc-recipient-blocked-page.tsx b/apps/remix/app/components/general/document-signing/csc-recipient-blocked-page.tsx
new file mode 100644
index 000000000..0e2bb6fb2
--- /dev/null
+++ b/apps/remix/app/components/general/document-signing/csc-recipient-blocked-page.tsx
@@ -0,0 +1,68 @@
+import { AppErrorCode } from '@documenso/lib/errors/app-error';
+import { Button } from '@documenso/ui/primitives/button';
+import { Trans } from '@lingui/react/macro';
+import { AlertTriangleIcon } from 'lucide-react';
+
+export type CscRecipientBlockedPageProps = {
+ code: string;
+ recipientToken: string;
+};
+
+/**
+ * Terminal page rendered when the service-scope CSC OAuth callback surfaces a
+ * hard error the recipient can't resolve themselves (empty credential list,
+ * invalid cert, refused algorithm). The blocking-error cookie is read +
+ * cleared by the loader; this page only renders the message + retry CTA.
+ *
+ * The retry link kicks a fresh service-scope OAuth round-trip — useful when
+ * the TSP-side issue is transient (e.g. the recipient's admin has since
+ * provisioned a credential).
+ */
+export const CscRecipientBlockedPage = ({ code, recipientToken }: CscRecipientBlockedPageProps) => {
+ const retryUrl = `/api/csc/oauth/authorize?scope=service&token=${encodeURIComponent(recipientToken)}`;
+
+ return (
+ <div className="-mx-4 flex max-w-[100vw] flex-col items-center overflow-x-hidden px-4 pt-16 md:-mx-8 md:px-8 lg:pt-16 xl:pt-24">
+ <AlertTriangleIcon className="h-12 w-12 text-destructive" />
+
+ <h2 className="mt-6 max-w-[35ch] text-center font-semibold text-2xl leading-normal md:text-3xl lg:text-4xl">
+ {code === AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY ? (
+ <Trans>No signing credentials available</Trans>
+ ) : code === AppErrorCode.CSC_CERT_INVALID ? (
+ <Trans>Signing certificate is invalid</Trans>
+ ) : code === AppErrorCode.CSC_ALGORITHM_REFUSED ? (
+ <Trans>Signing algorithm is not supported</Trans>
+ ) : (
+ <Trans>Unable to start the signing flow</Trans>
+ )}
+ </h2>
+
+ <p className="mt-2.5 max-w-[60ch] text-center font-medium text-muted-foreground/60 text-sm md:text-base">
+ {code === AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY ? (
+ <Trans>
+ Your signing provider returned no usable credentials for this account. Contact your administrator or signing
+ provider for assistance.
+ </Trans>
+ ) : code === AppErrorCode.CSC_CERT_INVALID ? (
+ <Trans>
+ Your signing certificate is invalid, expired, or missing a required key. Contact your administrator or
+ signing provider for assistance.
+ </Trans>
+ ) : code === AppErrorCode.CSC_ALGORITHM_REFUSED ? (
+ <Trans>
+ Your signing provider does not advertise a signing algorithm this document accepts. Contact your
+ administrator or signing provider for assistance.
+ </Trans>
+ ) : (
+ <Trans>Something went wrong while preparing the remote signature. Please try again.</Trans>
+ )}
+ </p>
+
+ <Button asChild className="mt-8">
+ <a href={retryUrl}>
+ <Trans>Try again</Trans>
+ </a>
+ </Button>
+ </div>
+ );
+};
diff --git a/apps/remix/app/components/general/document-signing/csc-recipient-signing-in-progress-page.tsx b/apps/remix/app/components/general/document-signing/csc-recipient-signing-in-progress-page.tsx
new file mode 100644
index 000000000..1aa091b35
--- /dev/null
+++ b/apps/remix/app/components/general/document-signing/csc-recipient-signing-in-progress-page.tsx
@@ -0,0 +1,105 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { trpc } from '@documenso/trpc/react';
+import { Button } from '@documenso/ui/primitives/button';
+import { Trans } from '@lingui/react/macro';
+import { AlertTriangleIcon, Loader2Icon } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+
+export type CscRecipientSigningInProgressPageProps = {
+ sessionId: string;
+ recipientToken: string;
+};
+
+/**
+ * Rendered when the credential-scope OAuth callback has attached a SAD to the
+ * server-side `CscSession` and set the `csc_sad_session` cookie. The page
+ * auto-fires `enterprise.csc.signEnvelope` on mount and navigates to the
+ * completion page on success. On failure, it surfaces an error message and
+ * a retry CTA pointing at a fresh credential-scope OAuth round-trip.
+ */
+export const CscRecipientSigningInProgressPage = ({
+ sessionId,
+ recipientToken,
+}: CscRecipientSigningInProgressPageProps) => {
+ const { mutateAsync: signEnvelope } = trpc.enterprise.csc.signEnvelope.useMutation();
+
+ const [error, setError] = useState<string | null>(null);
+
+ // Ref rather than state for the fire-once guard. Refs mutate synchronously,
+ // so React StrictMode's double-invoke of the effect sees the updated value
+ // on the second pass and short-circuits. A useState guard would still let
+ // the second effect fire because the queued setState from the first run
+ // hasn't been committed yet when the second one reads it — that double-fire
+ // races two signEnvelope calls; whichever loses sees the SAD already
+ // consumed and flashes "Signing failed" before the winning call's
+ // navigation kicks in.
+ const hasFiredRef = useRef(false);
+
+ useEffect(() => {
+ if (hasFiredRef.current) {
+ return;
+ }
+
+ hasFiredRef.current = true;
+
+ const run = async () => {
+ try {
+ await signEnvelope({ sessionId, recipientToken });
+
+ window.location.href = `/sign/${recipientToken}/complete`;
+ } catch (err) {
+ const parsed = AppError.parseError(err);
+ setError(parsed.code || AppErrorCode.UNKNOWN_ERROR);
+ }
+ };
+
+ void run();
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ const retryUrl = `/api/csc/oauth/authorize?scope=credential&session=${encodeURIComponent(sessionId)}`;
+
+ return (
+ <div className="-mx-4 flex max-w-[100vw] flex-col items-center overflow-x-hidden px-4 pt-16 md:-mx-8 md:px-8 lg:pt-16 xl:pt-24">
+ {error ? (
+ <>
+ <AlertTriangleIcon className="h-12 w-12 text-destructive" />
+
+ <h2 className="mt-6 max-w-[35ch] text-center font-semibold text-2xl leading-normal md:text-3xl lg:text-4xl">
+ <Trans>Signing failed</Trans>
+ </h2>
+
+ <p className="mt-2.5 max-w-[60ch] text-center font-medium text-muted-foreground/60 text-sm md:text-base">
+ {error === AppErrorCode.CSC_TSP_TIMEOUT ? (
+ <Trans>The signing provider did not respond in time. Please retry.</Trans>
+ ) : error === AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN ? (
+ <Trans>
+ Your signing authorisation expired before the signature could be applied. Please reauthorise to retry.
+ </Trans>
+ ) : (
+ <Trans>Something went wrong while applying your signature. Please retry.</Trans>
+ )}
+ </p>
+
+ <Button asChild className="mt-8">
+ <a href={retryUrl}>
+ <Trans>Reauthorise and retry</Trans>
+ </a>
+ </Button>
+ </>
+ ) : (
+ <>
+ <Loader2Icon className="h-12 w-12 animate-spin text-primary" />
+
+ <h2 className="mt-6 max-w-[35ch] text-center font-semibold text-2xl leading-normal md:text-3xl lg:text-4xl">
+ <Trans>Applying your signature</Trans>
+ </h2>
+
+ <p className="mt-2.5 max-w-[60ch] text-center font-medium text-muted-foreground/60 text-sm md:text-base">
+ <Trans>Please don't close this tab. The signing provider is finalising your signature.</Trans>
+ </p>
+ </>
+ )}
+ </div>
+ );
+};
diff --git a/apps/remix/app/components/general/document-signing/document-signing-page-view-v1.tsx b/apps/remix/app/components/general/document-signing/document-signing-page-view-v1.tsx
index 3eea3753e..1979c63a2 100644
--- a/apps/remix/app/components/general/document-signing/document-signing-page-view-v1.tsx
+++ b/apps/remix/app/components/general/document-signing/document-signing-page-view-v1.tsx
@@ -27,7 +27,6 @@ import type { Field } from '@prisma/client';
import { FieldType, RecipientRole } from '@prisma/client';
import { LucideChevronDown, LucideChevronUp } from 'lucide-react';
import { useMemo, useState } from 'react';
-import { useNavigate } from 'react-router';
import { match, P } from 'ts-pattern';
import { DocumentSigningAttachmentsPopover } from '~/components/general/document-signing/document-signing-attachments-popover';
@@ -84,7 +83,6 @@ export const DocumentSigningPageViewV1 = ({
? authUser.twoFactorEnabled && authUser.email === recipient.email
: false;
- const navigate = useNavigate();
const analytics = useAnalytics();
const [selectedSignerId, setSelectedSignerId] = useState<number | null>(allRecipients?.[0]?.id);
@@ -129,7 +127,7 @@ export const DocumentSigningPageViewV1 = ({
if (documentMeta?.redirectUrl) {
window.location.href = documentMeta.redirectUrl;
} else {
- await navigate(`/sign/${recipient.token}/complete`);
+ window.location.href = `/sign/${recipient.token}/complete`;
}
};
diff --git a/apps/remix/app/components/general/document-signing/document-signing-reject-dialog.tsx b/apps/remix/app/components/general/document-signing/document-signing-reject-dialog.tsx
index 102238613..ba70ad048 100644
--- a/apps/remix/app/components/general/document-signing/document-signing-reject-dialog.tsx
+++ b/apps/remix/app/components/general/document-signing/document-signing-reject-dialog.tsx
@@ -17,7 +17,7 @@ import { msg } from '@lingui/core/macro';
import { Trans, useLingui } from '@lingui/react/macro';
import { useEffect, useState } from 'react';
import { useForm } from 'react-hook-form';
-import { useNavigate, useSearchParams } from 'react-router';
+import { useSearchParams } from 'react-router';
import { z } from 'zod';
const ZRejectDocumentFormSchema = z.object({
@@ -41,7 +41,6 @@ export function DocumentSigningRejectDialog({
}: DocumentSigningRejectDialogProps) {
const { t } = useLingui();
const { toast } = useToast();
- const navigate = useNavigate();
const [searchParams] = useSearchParams();
const [isOpen, setIsOpen] = useState(false);
@@ -74,7 +73,7 @@ export function DocumentSigningRejectDialog({
if (onRejected) {
await onRejected(reason);
} else {
- await navigate(`/sign/${token}/rejected`);
+ window.location.href = `/sign/${token}/rejected`;
}
} catch (err) {
toast({
diff --git a/apps/remix/app/components/general/document/document-page-view-button.tsx b/apps/remix/app/components/general/document/document-page-view-button.tsx
index 9eb96e768..730ae630b 100644
--- a/apps/remix/app/components/general/document/document-page-view-button.tsx
+++ b/apps/remix/app/components/general/document/document-page-view-button.tsx
@@ -38,7 +38,7 @@ export const DocumentPageViewButton = ({ envelope }: DocumentPageViewButtonProps
})
.with({ isRecipient: true, isPending: true, isSigned: false }, () => (
<Button className="w-full" asChild>
- <Link to={`/sign/${recipient?.token}`}>
+ <a href={`/sign/${recipient?.token}`}>
{match(role)
.with(RecipientRole.SIGNER, () => (
<>
@@ -58,7 +58,7 @@ export const DocumentPageViewButton = ({ envelope }: DocumentPageViewButtonProps
<Trans>View</Trans>
</>
))}
- </Link>
+ </a>
</Button>
))
.with({ isComplete: false }, () => (
diff --git a/apps/remix/app/components/general/envelope-signing/envelope-signing-complete-dialog.tsx b/apps/remix/app/components/general/envelope-signing/envelope-signing-complete-dialog.tsx
index c62db2f11..2035e65b8 100644
--- a/apps/remix/app/components/general/envelope-signing/envelope-signing-complete-dialog.tsx
+++ b/apps/remix/app/components/general/envelope-signing/envelope-signing-complete-dialog.tsx
@@ -89,7 +89,7 @@ export const EnvelopeSignerCompleteDialog = () => {
recipientDetails?: { name: string; email: string },
) => {
try {
- await completeDocument({
+ const result = await completeDocument({
token: recipient.token,
documentId: mapSecondaryIdToDocumentId(envelope.secondaryId),
accessAuthOptions,
@@ -97,6 +97,15 @@ export const EnvelopeSignerCompleteDialog = () => {
...(nextSigner?.email && nextSigner?.name ? { nextSigner } : {}),
});
+ // TSP envelopes can't be completed via the SES path; the mutation returns
+ // a credential-scope OAuth URL the recipient must follow to acquire a SAD
+ // before the sync sign mutation can run. Short-circuit here so the
+ // analytics / completion handlers don't run with a still-unsigned doc.
+ if (result.status === 'REDIRECT') {
+ window.location.href = result.redirectUrl;
+ return;
+ }
+
analytics.capture('App: Recipient has completed signing', {
signerId: recipient.id,
documentId: envelope.id,
@@ -119,7 +128,7 @@ export const EnvelopeSignerCompleteDialog = () => {
if (envelope.documentMeta.redirectUrl) {
window.location.href = envelope.documentMeta.redirectUrl;
} else {
- await navigate(`/sign/${recipient.token}/complete`);
+ window.location.href = `/sign/${recipient.token}/complete`;
}
} catch (err) {
const error = AppError.parseError(err);
@@ -197,7 +206,7 @@ export const EnvelopeSignerCompleteDialog = () => {
if (redirectUrl) {
window.location.href = redirectUrl;
} else {
- await navigate(`/sign/${token}/complete`);
+ window.location.href = `/sign/${token}/complete`;
}
} catch (err) {
console.log('err', err);
diff --git a/apps/remix/app/components/tables/documents-table-action-button.tsx b/apps/remix/app/components/tables/documents-table-action-button.tsx
index a6e9a9edd..000b46780 100644
--- a/apps/remix/app/components/tables/documents-table-action-button.tsx
+++ b/apps/remix/app/components/tables/documents-table-action-button.tsx
@@ -66,7 +66,7 @@ export const DocumentsTableActionButton = ({ row }: DocumentsTableActionButtonPr
))
.with({ isRecipient: true, isPending: true, isSigned: false }, () => (
<Button className="w-32" asChild>
- <Link to={`/sign/${recipient?.token}`}>
+ <a href={`/sign/${recipient?.token}`}>
{match(role)
.with(RecipientRole.SIGNER, () => (
<>
@@ -86,7 +86,7 @@ export const DocumentsTableActionButton = ({ row }: DocumentsTableActionButtonPr
<Trans>View</Trans>
</>
))}
- </Link>
+ </a>
</Button>
))
.with({ isPending: true, isSigned: true }, () => (
diff --git a/apps/remix/app/components/tables/documents-table-action-dropdown.tsx b/apps/remix/app/components/tables/documents-table-action-dropdown.tsx
index 1555d54a2..1d09e2900 100644
--- a/apps/remix/app/components/tables/documents-table-action-dropdown.tsx
+++ b/apps/remix/app/components/tables/documents-table-action-dropdown.tsx
@@ -105,7 +105,7 @@ export const DocumentsTableActionDropdown = ({ row, onMoveDocument }: DocumentsT
recipient?.role !== RecipientRole.CC &&
recipient?.role !== RecipientRole.ASSISTANT && (
<DropdownMenuItem disabled={!recipient || isComplete} asChild>
- <Link to={`/sign/${recipient?.token}`}>
+ <a href={`/sign/${recipient?.token}`}>
{recipient?.role === RecipientRole.VIEWER && (
<>
<EyeIcon className="mr-2 h-4 w-4" />
@@ -126,7 +126,7 @@ export const DocumentsTableActionDropdown = ({ row, onMoveDocument }: DocumentsT
<Trans>Approve</Trans>
</>
)}
- </Link>
+ </a>
</DropdownMenuItem>
)}
diff --git a/apps/remix/app/components/tables/inbox-table.tsx b/apps/remix/app/components/tables/inbox-table.tsx
index d0d6a9e21..f958da66d 100644
--- a/apps/remix/app/components/tables/inbox-table.tsx
+++ b/apps/remix/app/components/tables/inbox-table.tsx
@@ -17,7 +17,7 @@ import { DocumentStatus as DocumentStatusEnum, RecipientRole, SigningStatus } fr
import { CheckCircleIcon, DownloadIcon, EyeIcon, Loader, PencilIcon } from 'lucide-react';
import { DateTime } from 'luxon';
import { useMemo, useTransition } from 'react';
-import { Link, useSearchParams } from 'react-router';
+import { useSearchParams } from 'react-router';
import { match } from 'ts-pattern';
import { DocumentStatus } from '~/components/general/document/document-status';
@@ -200,7 +200,7 @@ export const InboxTableActionButton = ({ row }: InboxTableActionButtonProps) =>
})
.with({ isPending: true, isSigned: false }, () => (
<Button className="w-32" asChild>
- <Link to={`/sign/${recipient?.token}`}>
+ <a href={`/sign/${recipient?.token}`}>
{match(role)
.with(RecipientRole.SIGNER, () => (
<>
@@ -220,7 +220,7 @@ export const InboxTableActionButton = ({ row }: InboxTableActionButtonProps) =>
<Trans>View</Trans>
</>
))}
- </Link>
+ </a>
</Button>
))
.with({ isPending: true, isSigned: true }, () => (
diff --git a/apps/remix/app/routes/_recipient+/sign.$token+/_index.tsx b/apps/remix/app/routes/_recipient+/sign.$token+/_index.tsx
index e28947361..d35313fd8 100644
--- a/apps/remix/app/routes/_recipient+/sign.$token+/_index.tsx
+++ b/apps/remix/app/routes/_recipient+/sign.$token+/_index.tsx
@@ -1,7 +1,14 @@
import signingCelebration from '@documenso/assets/images/signing-celebration.png';
import { getOptionalSession } from '@documenso/auth/server/lib/utils/get-session';
+import {
+ buildClearCscBlockingErrorCookieHeader,
+ readCscBlockingErrorFromRequest,
+} from '@documenso/ee/server-only/signing/csc/cookies/blocking-error-cookie';
+import { readCscSadSessionFromRequest } from '@documenso/ee/server-only/signing/csc/cookies/sad-session-cookie';
+import { readCscServiceSessionFromRequest } from '@documenso/ee/server-only/signing/csc/cookies/service-session-cookie';
import { EnvelopeRenderProvider } from '@documenso/lib/client-only/providers/envelope-render-provider';
import { useOptionalSession } from '@documenso/lib/client-only/providers/session';
+import { IS_INSTANCE_CSC_MODE } from '@documenso/lib/constants/app';
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
import { loadRecipientBrandingByTeamId } from '@documenso/lib/server-only/branding/load-recipient-branding';
import { getDocumentAndSenderByToken } from '@documenso/lib/server-only/document/get-document-by-token';
@@ -18,6 +25,7 @@ import { getRecipientsForAssistant } from '@documenso/lib/server-only/recipient/
import { getTeamSettings } from '@documenso/lib/server-only/team/get-team-settings';
import { getUserByEmail } from '@documenso/lib/server-only/user/get-user-by-email';
import { DocumentAccessAuth } from '@documenso/lib/types/document-auth';
+import { isTspEnvelope } from '@documenso/lib/types/signature-level';
import { extractDocumentAuthMethods } from '@documenso/lib/utils/document-auth';
import { isRecipientExpired } from '@documenso/lib/utils/recipients';
import { prisma } from '@documenso/prisma';
@@ -30,6 +38,8 @@ import { getOptionalLoaderContext } from 'server/utils/get-loader-session';
import { match } from 'ts-pattern';
import { Header as AuthenticatedHeader } from '~/components/general/app-header';
+import { CscRecipientBlockedPage } from '~/components/general/document-signing/csc-recipient-blocked-page';
+import { CscRecipientSigningInProgressPage } from '~/components/general/document-signing/csc-recipient-signing-in-progress-page';
import { DocumentSigningAuthPageView } from '~/components/general/document-signing/document-signing-auth-page';
import { DocumentSigningAuthProvider } from '~/components/general/document-signing/document-signing-auth-provider';
import { DocumentSigningPageViewV1 } from '~/components/general/document-signing/document-signing-page-view-v1';
@@ -257,6 +267,58 @@ const handleV2Loader = async ({ params, request }: Route.LoaderArgs) => {
recipientAccessAuth: derivedRecipientAccessAuth,
}).catch(() => null);
+ // CSC / TSP routing. TSP envelopes have three terminal recipient-page
+ // states beyond the normal signing UI:
+ // 1. `blocked` — service-scope OAuth returned a hard error (set by the
+ // callback as a one-shot `csc_blocking_error` cookie).
+ // 2. `signing-in-progress` — credential-scope OAuth completed, SAD is
+ // attached server-side, page auto-fires the sync sign mutation.
+ // 3. pre-auth — no service token yet, kick the recipient into
+ // service-scope OAuth.
+ // The fourth state (service session valid, no SAD, no blocking error) falls
+ // through to the normal signing UI.
+ if (IS_INSTANCE_CSC_MODE() && isTspEnvelope(envelope)) {
+ const blockingError = await readCscBlockingErrorFromRequest(request);
+
+ if (blockingError && blockingError.recipientToken === token) {
+ return {
+ isDocumentAccessValid: true,
+ envelopeForSigning,
+ csc: { state: 'blocked', code: blockingError.code } as const,
+ responseHeaders: { 'Set-Cookie': buildClearCscBlockingErrorCookieHeader() },
+ } as const;
+ }
+
+ const sadSessionId = await readCscSadSessionFromRequest(request);
+
+ if (sadSessionId) {
+ const cscSession = await prisma.cscSession.findUnique({
+ where: { id: sadSessionId },
+ });
+
+ const isSadSessionValid =
+ cscSession !== null &&
+ cscSession.recipientId === recipient.id &&
+ cscSession.encryptedSad !== null &&
+ cscSession.sadExpiresAt !== null &&
+ cscSession.sadExpiresAt > new Date();
+
+ if (isSadSessionValid) {
+ return {
+ isDocumentAccessValid: true,
+ envelopeForSigning,
+ csc: { state: 'signing-in-progress', sessionId: sadSessionId } as const,
+ } as const;
+ }
+ }
+
+ const serviceSessionToken = await readCscServiceSessionFromRequest(request);
+
+ if (serviceSessionToken !== token) {
+ throw redirect(`/api/csc/oauth/authorize?scope=service&token=${encodeURIComponent(token)}`);
+ }
+ }
+
return {
isDocumentAccessValid: true,
envelopeForSigning,
@@ -296,11 +358,22 @@ export async function loader(loaderArgs: Route.LoaderArgs) {
if (foundRecipient.envelope.internalVersion === 2) {
const payloadV2 = await handleV2Loader(loaderArgs);
- return superLoaderJson({
- version: 2,
- payload: payloadV2,
- branding,
- } as const);
+ // V2 payload may carry a one-shot `Set-Cookie` header (used to clear the
+ // CSC blocking-error cookie after the loader reads it). Forward it via
+ // the `superLoaderJson` response init so the browser actually applies the
+ // header. The field stays on the payload — it's just a `Max-Age=0` clear
+ // directive, not sensitive — and isn't read by any consumer.
+ const responseHeaders =
+ 'responseHeaders' in payloadV2 && payloadV2.responseHeaders ? payloadV2.responseHeaders : undefined;
+
+ return superLoaderJson(
+ {
+ version: 2,
+ payload: payloadV2,
+ branding,
+ } as const,
+ responseHeaders ? { headers: responseHeaders } : undefined,
+ );
}
const payloadV1 = await handleV1Loader(loaderArgs);
@@ -430,6 +503,19 @@ const SigningPageV2 = ({ data }: { data: Awaited<ReturnType<typeof handleV2Loade
return <DocumentSigningAuthPageView email={data.recipientEmail} emailHasAccount={!!data.recipientHasAccount} />;
}
+ if ('csc' in data && data.csc?.state === 'blocked') {
+ return <CscRecipientBlockedPage code={data.csc.code} recipientToken={data.envelopeForSigning.recipient.token} />;
+ }
+
+ if ('csc' in data && data.csc?.state === 'signing-in-progress') {
+ return (
+ <CscRecipientSigningInProgressPage
+ sessionId={data.csc.sessionId}
+ recipientToken={data.envelopeForSigning.recipient.token}
+ />
+ );
+ }
+
const { envelope, recipientSignature, recipient } = data.envelopeForSigning;
if (envelope.deletedAt || envelope.status === DocumentStatus.REJECTED) {
diff --git a/apps/remix/server/router.ts b/apps/remix/server/router.ts
index 72e847ae0..19747d4b2 100644
--- a/apps/remix/server/router.ts
+++ b/apps/remix/server/router.ts
@@ -1,5 +1,6 @@
import { tsRestHonoApp } from '@documenso/api/hono';
import { auth } from '@documenso/auth/server';
+import { csc } from '@documenso/ee/server-only/signing/csc/hono';
import { jobsClient } from '@documenso/lib/jobs/client';
import { LicenseClient } from '@documenso/lib/server-only/license/license-client';
import { createRateLimitMiddleware } from '@documenso/lib/server-only/rate-limit/rate-limit-middleware';
@@ -111,6 +112,9 @@ app.route('/api/files', filesRoute);
app.use('/api/ai/*', aiRateLimitMiddleware);
app.route('/api/ai', aiRoute);
+// CSC OAuth routes (mounted from @documenso/ee).
+app.route('/api/csc', csc);
+
// API servers.
app.route('/api/v1', tsRestHonoApp);
app.use('/api/jobs/*', jobsClient.getApiHandler());
diff --git a/package-lock.json b/package-lock.json
index ca4111950..2b85538ce 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15,7 +15,7 @@
"dependencies": {
"@ai-sdk/google-vertex": "3.0.81",
"@documenso/prisma": "*",
- "@libpdf/core": "^0.3.6",
+ "@libpdf/core": "^0.4.0",
"@lingui/conf": "^5.6.0",
"@lingui/core": "^5.6.0",
"@marsidev/react-turnstile": "^1.5.0",
@@ -4661,16 +4661,16 @@
"license": "MIT"
},
"node_modules/@libpdf/core": {
- "version": "0.3.6",
- "resolved": "https://registry.npmjs.org/@libpdf/core/-/core-0.3.6.tgz",
- "integrity": "sha512-VzRUXaDq+M9qrroKiipCgePK2mwKM3M6DY7B0yfXnxD4aYnUxD/nUtkcsHCBUUnJpkX9rWikdEhYa5vU8ZlReg==",
+ "version": "0.4.0",
+ "resolved": "https://registry.npmjs.org/@libpdf/core/-/core-0.4.0.tgz",
+ "integrity": "sha512-G9nZRjf9DGDJaS/C23YWogk8akPM7O/6HfMslxVsKTKRbbbb+0szpQIetcGGUGRu7KtmBDmGDWCgz//DXSmq8A==",
"license": "MIT",
"dependencies": {
"@noble/ciphers": "^2.2.0",
"@noble/hashes": "^2.2.0",
"@scure/base": "^2.2.0",
"asn1js": "^3.0.10",
- "lru-cache": "^11.4.0",
+ "lru-cache": "^11.5.1",
"pako": "^2.1.0",
"pkijs": "^3.4.0"
},
@@ -4724,9 +4724,9 @@
}
},
"node_modules/@libpdf/core/node_modules/lru-cache": {
- "version": "11.4.0",
- "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.4.0.tgz",
- "integrity": "sha512-W+R+kFL4HgVxONq2bhXPi3bGpzGe/yEhVOp233qw9wCRtgncJ15P3bC+e4zZMu4Cq7d+WAJjXGW0uUkifhcatA==",
+ "version": "11.5.1",
+ "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.1.tgz",
+ "integrity": "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A==",
"license": "BlueOak-1.0.0",
"engines": {
"node": "20 || >=22"
@@ -30593,6 +30593,8 @@
"@aws-sdk/client-sesv2": "^3.998.0",
"@documenso/lib": "*",
"@documenso/prisma": "*",
+ "arctic": "^3.7.0",
+ "hono": "^4.12.14",
"luxon": "^3.7.2",
"react": "^18",
"ts-pattern": "^5.9.0",
diff --git a/package.json b/package.json
index d2a0c4b1b..e2c01cdd6 100644
--- a/package.json
+++ b/package.json
@@ -88,7 +88,7 @@
"dependencies": {
"@ai-sdk/google-vertex": "3.0.81",
"@documenso/prisma": "*",
- "@libpdf/core": "^0.3.6",
+ "@libpdf/core": "^0.4.0",
"@lingui/conf": "^5.6.0",
"@lingui/core": "^5.6.0",
"@prisma/extension-read-replicas": "^0.4.1",
diff --git a/packages/ee/package.json b/packages/ee/package.json
index 52a51512f..79cc3ba85 100644
--- a/packages/ee/package.json
+++ b/packages/ee/package.json
@@ -16,6 +16,8 @@
"@aws-sdk/client-sesv2": "^3.998.0",
"@documenso/lib": "*",
"@documenso/prisma": "*",
+ "arctic": "^3.7.0",
+ "hono": "^4.12.14",
"luxon": "^3.7.2",
"react": "^18",
"ts-pattern": "^5.9.0",
diff --git a/packages/ee/server-only/signing/csc/algorithm-resolver.ts b/packages/ee/server-only/signing/csc/algorithm-resolver.ts
new file mode 100644
index 000000000..184e3edde
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/algorithm-resolver.ts
@@ -0,0 +1,347 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+
+import type { TCscCredentialsInfoResponse } from './client/types';
+
+/**
+ * CSC QES V1 algorithm policy.
+ *
+ * Single OID-to-algorithm map + single helper that:
+ * - validates cert state (status, validity window) → `CSC_CERT_INVALID`,
+ * - validates the credential's key + algorithm against the spec's policy
+ * table (RSA ≥2048, ECDSA P-256/384/521, SHA-256/384/512) →
+ * `CSC_ALGORITHM_REFUSED`,
+ * - resolves a concrete `(signAlgo, hashAlgo)` OID pair for §11.9.
+ *
+ * Called at the service-scope OAuth callback (validation boundary) and
+ * re-called at sign time as a defence-in-depth pre-check. Persisted fields
+ * (`keyType` / `keyLenBits` / `digestAlgorithm` / `signAlgoOid`) round-trip
+ * through `CscCredential`.
+ */
+
+export type CscKeyType = 'RSA' | 'ECDSA';
+
+export type CscDigest = 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+export type CscEcdsaCurve = 'P-256' | 'P-384' | 'P-521';
+
+export type CscAlgorithmPolicy = {
+ keyType: CscKeyType;
+ keyLenBits: number;
+ digestAlgorithm: CscDigest;
+ /** OID for `signatures/signHash.signAlgo` + persisted on `CscCredential`. */
+ signAlgoOid: string;
+ /** OID for `signatures/signHash.hashAlgo`. */
+ hashAlgoOid: string;
+ /** ECDSA named curve (informational; not separately persisted). */
+ ecdsaCurve?: CscEcdsaCurve;
+};
+
+/**
+ * Default RSA digest when the TSP advertises only hash-agnostic RSA OIDs
+ * (plain `rsaEncryption` / RSASSA-PSS). SHA-256 matches the CSC §11.9
+ * sample and is universally TSP-supported.
+ */
+const DEFAULT_RSA_DIGEST: CscDigest = 'SHA-256';
+
+const HASH_OID_FOR_DIGEST: Record<CscDigest, string> = {
+ 'SHA-256': '2.16.840.1.101.3.4.2.1',
+ 'SHA-384': '2.16.840.1.101.3.4.2.2',
+ 'SHA-512': '2.16.840.1.101.3.4.2.3',
+};
+
+/**
+ * Exposed lookup for the `signatures/signHash.hashAlgo` OID corresponding to a
+ * resolved {@link CscDigest}. Useful at sign time when the policy's
+ * `hashAlgoOid` field is not in scope (e.g. when reconstructing a
+ * `LibpdfSignerAlgo` from a persisted `CscCredential` row).
+ */
+export const hashOidForDigest = (digest: CscDigest): string => HASH_OID_FOR_DIGEST[digest];
+
+const DIGEST_STRENGTH: Record<CscDigest, number> = {
+ 'SHA-256': 256,
+ 'SHA-384': 384,
+ 'SHA-512': 512,
+};
+
+const STRONG_DIGEST_SET = new Set<string>(['SHA-256', 'SHA-384', 'SHA-512']);
+
+type AlgoOidInfo = { family: 'RSA' | 'ECDSA'; boundDigest: CscDigest | 'SHA-1' | 'MD5' | null } | { family: 'DSA' };
+
+/**
+ * Source-of-truth registry for `key.algo` entries (§11.5). Anything not
+ * listed is treated as unknown and skipped at policy evaluation.
+ */
+const KEY_ALGO_OID_REGISTRY: Record<string, AlgoOidInfo> = {
+ // Hash-agnostic RSA — caller picks the hash via `hashAlgo`.
+ '1.2.840.113549.1.1.1': { family: 'RSA', boundDigest: null }, // rsaEncryption
+ '1.2.840.113549.1.1.10': { family: 'RSA', boundDigest: null }, // RSASSA-PSS
+
+ // Hash-bound legacy RSA combos.
+ '1.2.840.113549.1.1.4': { family: 'RSA', boundDigest: 'MD5' }, // md5WithRSAEncryption
+ '1.2.840.113549.1.1.5': { family: 'RSA', boundDigest: 'SHA-1' }, // sha1WithRSAEncryption
+ '1.2.840.113549.1.1.11': { family: 'RSA', boundDigest: 'SHA-256' }, // sha256WithRSAEncryption
+ '1.2.840.113549.1.1.12': { family: 'RSA', boundDigest: 'SHA-384' }, // sha384WithRSAEncryption
+ '1.2.840.113549.1.1.13': { family: 'RSA', boundDigest: 'SHA-512' }, // sha512WithRSAEncryption
+
+ // ECDSA with SHA-x (hash is always bound).
+ '1.2.840.10045.4.1': { family: 'ECDSA', boundDigest: 'SHA-1' }, // ecdsa-with-SHA1
+ '1.2.840.10045.4.3.2': { family: 'ECDSA', boundDigest: 'SHA-256' },
+ '1.2.840.10045.4.3.3': { family: 'ECDSA', boundDigest: 'SHA-384' },
+ '1.2.840.10045.4.3.4': { family: 'ECDSA', boundDigest: 'SHA-512' },
+
+ // DSA — refused outright.
+ '1.2.840.10040.4.1': { family: 'DSA' },
+ '1.2.840.10040.4.3': { family: 'DSA' }, // dsa-with-SHA1
+};
+
+/**
+ * ECDSA named-curve OID registry. Policy verdict (allow/refuse) is decided
+ * by the resolver from the resolved curve name, not encoded here.
+ */
+const CURVE_OID_REGISTRY: Record<string, CscEcdsaCurve | 'P-192' | 'P-224'> = {
+ '1.2.840.10045.3.1.7': 'P-256', // secp256r1
+ '1.3.132.0.34': 'P-384', // secp384r1
+ '1.3.132.0.35': 'P-521', // secp521r1
+ '1.2.840.10045.3.1.1': 'P-192', // secp192r1
+ '1.3.132.0.33': 'P-224', // secp224r1
+};
+
+/**
+ * Validate a CSC credential's cert + key/algorithm against V1 policy and
+ * resolve the `(signAlgo, hashAlgo)` OID pair used by `signatures/signHash`.
+ *
+ * Caller MUST fetch the credential with `certInfo: true` so `cert.validFrom`
+ * / `cert.validTo` are present.
+ *
+ * Throws:
+ * - `CSC_CERT_INVALID` for cert-state issues (status not `valid`, missing or
+ * malformed validity dates, current time outside the validity window).
+ * - `CSC_ALGORITHM_REFUSED` for key/algorithm policy failures (disabled key,
+ * missing `key.len`, RSA `< 2048`, ECDSA without an allowed curve, DSA, no
+ * acceptable digest advertised in `key.algo`).
+ */
+export const resolveCscAlgorithmPolicy = (credentialInfo: TCscCredentialsInfoResponse): CscAlgorithmPolicy => {
+ assertCertValid(credentialInfo.cert);
+
+ if (credentialInfo.key.status !== 'enabled') {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: `CSC credential key status is '${credentialInfo.key.status}'.`,
+ });
+ }
+
+ if (credentialInfo.key.len === undefined) {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: 'CSC credential omits required key.len (REQUIRED per §11.5).',
+ });
+ }
+
+ const choice = pickAlgorithmChoice(credentialInfo.key.algo);
+
+ if (choice.family === 'RSA') {
+ if (credentialInfo.key.len < 2048) {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: `CSC RSA credential keyLen ${credentialInfo.key.len} < 2048.`,
+ });
+ }
+
+ return {
+ keyType: 'RSA',
+ keyLenBits: credentialInfo.key.len,
+ digestAlgorithm: choice.digest,
+ signAlgoOid: choice.signAlgoOid,
+ hashAlgoOid: HASH_OID_FOR_DIGEST[choice.digest],
+ };
+ }
+
+ const curve = resolveEcdsaCurve(credentialInfo.key.curve);
+
+ return {
+ keyType: 'ECDSA',
+ keyLenBits: credentialInfo.key.len,
+ digestAlgorithm: choice.digest,
+ signAlgoOid: choice.signAlgoOid,
+ hashAlgoOid: HASH_OID_FOR_DIGEST[choice.digest],
+ ecdsaCurve: curve,
+ };
+};
+
+type AlgorithmChoice = {
+ family: 'RSA' | 'ECDSA';
+ signAlgoOid: string;
+ digest: CscDigest;
+};
+
+/**
+ * Iterate the TSP's advertised `key.algo` OIDs, drop the policy-refused
+ * entries, and pick the strongest survivor.
+ *
+ * Precedence: ECDSA before RSA (smaller signatures, modern); within each
+ * family, strongest advertised digest first. Hash-agnostic RSA OIDs pair
+ * with {@link DEFAULT_RSA_DIGEST}.
+ */
+const pickAlgorithmChoice = (algoOids: readonly string[]): AlgorithmChoice => {
+ const candidates: AlgorithmChoice[] = [];
+
+ for (const oid of algoOids) {
+ const info = KEY_ALGO_OID_REGISTRY[oid];
+
+ if (info === undefined) {
+ // Unknown OID — another entry in `key.algo` may still be acceptable.
+ continue;
+ }
+
+ if (info.family === 'DSA') {
+ continue;
+ }
+
+ if (info.boundDigest === null) {
+ candidates.push({
+ family: info.family,
+ signAlgoOid: oid,
+ digest: DEFAULT_RSA_DIGEST,
+ });
+ continue;
+ }
+
+ if (STRONG_DIGEST_SET.has(info.boundDigest)) {
+ candidates.push({
+ family: info.family,
+ signAlgoOid: oid,
+ digest: info.boundDigest as CscDigest,
+ });
+ }
+ }
+
+ if (candidates.length === 0) {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: `CSC credential advertises no policy-compliant key.algo OIDs (got: ${algoOids.join(', ') || '<empty>'}).`,
+ });
+ }
+
+ candidates.sort((a, b) => {
+ if (a.family !== b.family) {
+ return a.family === 'ECDSA' ? -1 : 1;
+ }
+
+ return DIGEST_STRENGTH[b.digest] - DIGEST_STRENGTH[a.digest];
+ });
+
+ return candidates[0];
+};
+
+const resolveEcdsaCurve = (curveOid: string | undefined): CscEcdsaCurve => {
+ if (curveOid === undefined || curveOid === '') {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: 'CSC ECDSA credential omits required key.curve.',
+ });
+ }
+
+ const named = CURVE_OID_REGISTRY[curveOid];
+
+ if (named === 'P-256' || named === 'P-384' || named === 'P-521') {
+ return named;
+ }
+
+ const detail = named ? `, named=${named}` : '';
+
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: `CSC ECDSA credential uses refused curve (oid=${curveOid}${detail}).`,
+ });
+};
+
+const assertCertValid = (cert: TCscCredentialsInfoResponse['cert']): void => {
+ if (cert.status !== undefined && cert.status !== 'valid') {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: `CSC credential certificate status is '${cert.status}'.`,
+ });
+ }
+
+ if (!cert.validFrom || !cert.validTo) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: 'CSC credential certificate omits validFrom/validTo (malformed).',
+ });
+ }
+
+ const validFromMs = parseGeneralizedTime(cert.validFrom);
+ const validToMs = parseGeneralizedTime(cert.validTo);
+
+ if (validFromMs === null || validToMs === null) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: `CSC credential certificate validity dates are malformed (validFrom=${cert.validFrom}, validTo=${cert.validTo}).`,
+ });
+ }
+
+ const now = Date.now();
+
+ if (now < validFromMs) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: `CSC credential certificate is not yet valid (validFrom=${cert.validFrom}).`,
+ });
+ }
+
+ if (now > validToMs) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: `CSC credential certificate has expired (validTo=${cert.validTo}).`,
+ });
+ }
+};
+
+/**
+ * Parse an X.509 GeneralizedTime string (`YYYYMMDDHHMMSSZ`) into epoch ms.
+ * Strict — returns null on any deviation from the §11.5 example format.
+ */
+const parseGeneralizedTime = (value: string): number | null => {
+ const matched = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/.exec(value);
+
+ if (matched === null) {
+ return null;
+ }
+
+ const [, y, mo, d, h, mi, s] = matched;
+
+ const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
+
+ return Number.isNaN(ms) ? null : ms;
+};
+
+/**
+ * Subset of libpdf's `Signer` interface fields derived from a `CscAlgorithmPolicy`.
+ * Used by `CscCaptureSigner` / `CscFifoSigner` to satisfy libpdf's signer
+ * contract without re-deriving the mapping at each call site. `keyLenBits`
+ * is carried through so the capture-signer can size its placeholder output
+ * appropriately for the chosen key.
+ */
+export type LibpdfSignerAlgo = {
+ keyType: 'RSA' | 'EC';
+ signatureAlgorithm: 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
+ digestAlgorithm: CscDigest;
+ keyLenBits: number;
+};
+
+/**
+ * Translate a `CscAlgorithmPolicy` (CSC §11.5 OIDs) into libpdf's `Signer`
+ * algorithm tuple. RSASSA-PSS is detected by the `signAlgoOid`; everything
+ * else maps directly from `keyType` + `digestAlgorithm`.
+ */
+export const policyToLibpdfSignerAlgo = (policy: CscAlgorithmPolicy): LibpdfSignerAlgo => {
+ if (policy.keyType === 'ECDSA') {
+ return {
+ keyType: 'EC',
+ signatureAlgorithm: 'ECDSA',
+ digestAlgorithm: policy.digestAlgorithm,
+ keyLenBits: policy.keyLenBits,
+ };
+ }
+
+ // RSA — distinguish PKCS1-v1.5 from PSS by the resolved sign-algo OID.
+ // RSASSA-PSS OID: '1.2.840.113549.1.1.10'.
+ const signatureAlgorithm: 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' =
+ policy.signAlgoOid === '1.2.840.113549.1.1.10' ? 'RSA-PSS' : 'RSASSA-PKCS1-v1_5';
+
+ return {
+ keyType: 'RSA',
+ signatureAlgorithm,
+ digestAlgorithm: policy.digestAlgorithm,
+ keyLenBits: policy.keyLenBits,
+ };
+};
diff --git a/packages/ee/server-only/signing/csc/cert-chain.ts b/packages/ee/server-only/signing/csc/cert-chain.ts
new file mode 100644
index 000000000..1967fdf1f
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/cert-chain.ts
@@ -0,0 +1,122 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+
+/**
+ * Length-prefixed X.509 chain for `CscCredential.certCache`. Schema column is
+ * `Bytes`; this gives a self-describing binary that round-trips without
+ * base64 inflation. Format: u32 BE cert count, then per-cert u32 BE byte
+ * length + raw DER bytes.
+ *
+ * Encoding inputs come from `cscCredentialsInfo.cert.certificates`, which the
+ * CSC §11.5 spec defines as an array of base64-encoded DER X.509 certificates
+ * (leaf-first). The encoder decodes each base64 entry once at persistence
+ * time; the decoder is the symmetric inverse used at sign time.
+ *
+ * Pure functions, no I/O.
+ */
+
+const BASE64_REGEX = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/**
+ * Encode a leaf-first chain of base64-encoded DER certs into the
+ * length-prefixed binary form persisted on `CscCredential.certCache`.
+ *
+ * Throws `INVALID_REQUEST` when the input is empty or any entry is not valid
+ * base64.
+ */
+export const encodeCscCertChain = (certs: string[]): Uint8Array => {
+ if (certs.length === 0) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain encoding requires at least one certificate.',
+ });
+ }
+
+ const derBuffers: Uint8Array[] = [];
+ let totalDerBytes = 0;
+
+ for (const entry of certs) {
+ if (entry.length === 0 || !BASE64_REGEX.test(entry)) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain entry is not valid base64.',
+ });
+ }
+
+ const der = Buffer.from(entry, 'base64');
+
+ if (der.length === 0) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain entry decoded to zero bytes.',
+ });
+ }
+
+ derBuffers.push(der);
+ totalDerBytes += der.length;
+ }
+
+ // 4 bytes for the count + 4 bytes per-cert length prefix + raw DER bytes.
+ const totalLength = 4 + derBuffers.length * 4 + totalDerBytes;
+ const out = new Uint8Array(totalLength);
+ const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+
+ view.setUint32(0, derBuffers.length, false);
+
+ let offset = 4;
+
+ for (const der of derBuffers) {
+ view.setUint32(offset, der.length, false);
+ offset += 4;
+ out.set(der, offset);
+ offset += der.length;
+ }
+
+ return out;
+};
+
+/**
+ * Decode a length-prefixed cert chain back into an array of DER cert byte
+ * arrays. Inverse of {@link encodeCscCertChain}.
+ *
+ * Throws `INVALID_REQUEST` when the buffer is truncated or any per-cert
+ * length prefix runs off the end of the buffer.
+ */
+export const decodeCscCertChain = (bytes: Uint8Array): Uint8Array[] => {
+ if (bytes.byteLength < 4) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain buffer is too short to contain a count prefix.',
+ });
+ }
+
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ const count = view.getUint32(0, false);
+
+ const result: Uint8Array[] = [];
+ let offset = 4;
+
+ for (let i = 0; i < count; i++) {
+ if (offset + 4 > bytes.byteLength) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain buffer truncated at length prefix.',
+ });
+ }
+
+ const length = view.getUint32(offset, false);
+ offset += 4;
+
+ if (length === 0 || offset + length > bytes.byteLength) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain buffer truncated within certificate body.',
+ });
+ }
+
+ // Slice copies the underlying bytes so callers can't mutate the source.
+ result.push(bytes.slice(offset, offset + length));
+ offset += length;
+ }
+
+ if (offset !== bytes.byteLength) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC certificate chain buffer has trailing bytes after declared chain end.',
+ });
+ }
+
+ return result;
+};
diff --git a/packages/ee/server-only/signing/csc/ciphers.ts b/packages/ee/server-only/signing/csc/ciphers.ts
new file mode 100644
index 000000000..7bb58f26e
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/ciphers.ts
@@ -0,0 +1,51 @@
+import { symmetricDecrypt, symmetricEncrypt } from '@documenso/lib/universal/crypto';
+import { requireEnv } from '@documenso/lib/utils/env';
+import { bytesToHex, hexToBytes } from '@noble/ciphers/utils';
+
+/**
+ * Bytes-based wrappers around {@link symmetricEncrypt} / {@link symmetricDecrypt}
+ * for the two CSC secrets stored on Prisma `Bytes` columns:
+ *
+ * - `CscCredential.serviceTokenCiphertext` — service-scope OAuth access token.
+ * - `CscSession.encryptedSad` — credential-scope SAD.
+ *
+ * Both use the primary `DOCUMENSO_ENCRYPTION_KEY` (same key family as 2FA
+ * secrets, OIDC client secrets, DKIM private keys). The underlying cipher
+ * returns hex; we round-trip through `bytesToHex` / `hexToBytes` so the
+ * persisted bytes are the raw XChaCha20-Poly1305 ciphertext (nonce + tag +
+ * payload), not a hex-string-as-bytes inflation.
+ */
+
+/**
+ * Encrypt a CSC plaintext secret (service token or SAD) for persistence.
+ * Throws `MISSING_ENV_VAR` on missing encryption key — encryption can't
+ * otherwise fail.
+ */
+export const encryptCscToken = (plaintext: string): Uint8Array => {
+ const key = requireEnv('NEXT_PRIVATE_ENCRYPTION_KEY');
+
+ const hex = symmetricEncrypt({ key, data: plaintext });
+
+ return hexToBytes(hex);
+};
+
+/**
+ * Decrypt a CSC ciphertext back to its UTF-8 plaintext. Returns `null` on
+ * any cipher-level failure (key rotation, payload tamper, row corruption)
+ * so the caller can map to a domain-appropriate AppError — typically
+ * re-auth for service tokens, `CSC_SAD_EXPIRED_PRE_SIGN` for SADs.
+ *
+ * A missing key throws (config error, must surface loudly) and is *not*
+ * folded into the null return.
+ */
+export const decryptCscToken = (ciphertext: Uint8Array): string | null => {
+ const key = requireEnv('NEXT_PRIVATE_ENCRYPTION_KEY');
+
+ try {
+ const buf = symmetricDecrypt({ key, data: bytesToHex(ciphertext) });
+
+ return Buffer.from(buf).toString('utf-8');
+ } catch {
+ return null;
+ }
+};
diff --git a/packages/ee/server-only/signing/csc/client/credentials.ts b/packages/ee/server-only/signing/csc/client/credentials.ts
new file mode 100644
index 000000000..ae4c5b7d0
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/credentials.ts
@@ -0,0 +1,122 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+
+import { cscJsonPost, joinCscUrl } from './http';
+import {
+ type TCscCredentialsInfoRequest,
+ type TCscCredentialsInfoResponse,
+ type TCscCredentialsListRequest,
+ type TCscCredentialsListResponse,
+ ZCscCredentialsInfoResponseSchema,
+ ZCscCredentialsListResponseSchema,
+} from './types';
+
+type CscCredentialsListOptions = TCscCredentialsListRequest & {
+ baseUrl: string;
+ /** Service-scope bearer token (CSC §11.4 + §11.9). */
+ accessToken: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * `credentials/list` (§11.4) — list the credentialIDs the bearer token's user
+ * owns at the TSP.
+ *
+ * Throws `CSC_CREDENTIAL_LIST_EMPTY` when the TSP returns a successful
+ * response with zero credentials — the recipient needs to enrol with the TSP
+ * before they can sign. Other failures throw `CSC_REQUEST_FAILED`.
+ *
+ * `userID` MUST be omitted when the service authorization is user-specific
+ * (true for OAuth `service` scope, which is V1's only flow). The spec rejects
+ * the call with `invalid_request` if both are present.
+ */
+export const cscCredentialsList = async (opts: CscCredentialsListOptions): Promise<TCscCredentialsListResponse> => {
+ const { baseUrl, accessToken, signal, userID, maxResults, pageToken, clientData } = opts;
+
+ const body: Record<string, unknown> = {};
+
+ if (userID !== undefined) {
+ body.userID = userID;
+ }
+
+ if (maxResults !== undefined) {
+ body.maxResults = maxResults;
+ }
+
+ if (pageToken !== undefined) {
+ body.pageToken = pageToken;
+ }
+
+ if (clientData !== undefined) {
+ body.clientData = clientData;
+ }
+
+ const response = await cscJsonPost(
+ {
+ url: joinCscUrl({ baseUrl, path: 'credentials/list' }),
+ body,
+ accessToken,
+ signal,
+ },
+ ZCscCredentialsListResponseSchema,
+ );
+
+ if (response.credentialIDs.length === 0) {
+ throw new AppError(AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY, {
+ message:
+ 'CSC provider returned no credentials for the authenticated user. Recipient must enrol with the TSP before signing.',
+ });
+ }
+
+ return response;
+};
+
+type CscCredentialsInfoOptions = TCscCredentialsInfoRequest & {
+ baseUrl: string;
+ /** Service-scope bearer token. */
+ accessToken: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * `credentials/info` (§11.5) — fetch credential metadata: key algorithm tuple,
+ * X.509 certificate chain, authorization mode, multisign capacity.
+ *
+ * Returns the parsed response verbatim. Cert validity, algorithm policy, and
+ * SCAL semantics are enforced by `csc/algorithm-resolver.ts` — that lives
+ * outside the client because it's domain logic, not transport.
+ */
+export const cscCredentialsInfo = async (opts: CscCredentialsInfoOptions): Promise<TCscCredentialsInfoResponse> => {
+ const { baseUrl, accessToken, signal, credentialID, certificates, certInfo, authInfo, lang, clientData } = opts;
+
+ const body: Record<string, unknown> = { credentialID };
+
+ if (certificates !== undefined) {
+ body.certificates = certificates;
+ }
+
+ if (certInfo !== undefined) {
+ body.certInfo = certInfo;
+ }
+
+ if (authInfo !== undefined) {
+ body.authInfo = authInfo;
+ }
+
+ if (lang !== undefined) {
+ body.lang = lang;
+ }
+
+ if (clientData !== undefined) {
+ body.clientData = clientData;
+ }
+
+ return await cscJsonPost(
+ {
+ url: joinCscUrl({ baseUrl, path: 'credentials/info' }),
+ body,
+ accessToken,
+ signal,
+ },
+ ZCscCredentialsInfoResponseSchema,
+ );
+};
diff --git a/packages/ee/server-only/signing/csc/client/http.ts b/packages/ee/server-only/signing/csc/client/http.ts
new file mode 100644
index 000000000..631aa0471
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/http.ts
@@ -0,0 +1,170 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { z } from 'zod';
+
+import { ZCscErrorResponseSchema } from './types';
+
+const LEADING_SLASHES_REGEX = /^\/+/;
+const TRAILING_SLASHES_REGEX = /\/+$/;
+
+/**
+ * Low-level fetch wrapper for the JSON-bodied CSC API methods (§7.1 mandates
+ * `Content-Type: application/json` for all API requests).
+ *
+ * OAuth 2.0 endpoints (`oauth2/token`, `oauth2/revoke`) use
+ * `application/x-www-form-urlencoded` per RFC 6749 and are handled by the
+ * `arctic` library — see `oauth.ts` in this directory.
+ *
+ * Normalises CSC error responses (§10.1: `{ error, error_description }`)
+ * into {@link AppError}s carrying the upstream HTTP status in
+ * {@link AppError.statusCode}, so callers can discriminate without
+ * re-parsing the body.
+ */
+
+type JoinUrlInput = {
+ baseUrl: string;
+ path: string;
+};
+
+/**
+ * Join a CSC base URL with a path segment. Strips trailing/leading slashes so
+ * `joinCscUrl({ baseUrl: 'https://x/csc/v1/', path: '/credentials/list' })`
+ * yields `https://x/csc/v1/credentials/list`.
+ */
+export const joinCscUrl = ({ baseUrl, path }: JoinUrlInput): string => {
+ const cleanBaseUrl = baseUrl.replace(TRAILING_SLASHES_REGEX, ''); // Strip trailing slashes from base URL.
+ const cleanPath = path.replace(LEADING_SLASHES_REGEX, ''); // Strip leading slashes from path.
+
+ const url = new URL(cleanPath, `${cleanBaseUrl}/`);
+
+ return url.toString();
+};
+
+type CscRequestErrorOptions = {
+ url: string;
+ status: number;
+ cscError?: { error: string; error_description?: string };
+ cause?: unknown;
+ errorCode?: string;
+};
+
+const buildCscRequestError = ({
+ url,
+ status,
+ cscError,
+ cause,
+ errorCode = AppErrorCode.CSC_REQUEST_FAILED,
+}: CscRequestErrorOptions): AppError => {
+ const causeMessage = cause instanceof Error ? cause.message : undefined;
+
+ const parts: string[] = [`CSC request to ${url} failed (HTTP ${status})`];
+
+ if (cscError) {
+ parts.push(cscError.error_description ? `${cscError.error}: ${cscError.error_description}` : cscError.error);
+ }
+
+ if (causeMessage) {
+ parts.push(causeMessage);
+ }
+
+ return new AppError(errorCode, {
+ message: parts.join(' — '),
+ statusCode: status,
+ });
+};
+
+/**
+ * Best-effort parse of a CSC error body. Returns `undefined` on non-JSON or
+ * schema mismatch so the caller still surfaces the HTTP status without
+ * masking it.
+ */
+const readCscErrorBody = async (
+ response: Response,
+): Promise<{ error: string; error_description?: string } | undefined> => {
+ try {
+ const json = await response.json();
+ const parsed = ZCscErrorResponseSchema.safeParse(json);
+
+ return parsed.success ? parsed.data : undefined;
+ } catch {
+ return undefined;
+ }
+};
+
+type CscJsonPostOptions = {
+ /** Fully-qualified endpoint URL (use {@link joinCscUrl} to build it). */
+ url: string;
+ /** Decoded JSON body; serialised via `JSON.stringify`. */
+ body: Record<string, unknown>;
+ /** Bearer access token. Omit for unauthenticated calls (e.g. `info`). */
+ accessToken?: string;
+ /** Override the AppError code thrown on failure. Defaults to `CSC_REQUEST_FAILED`. */
+ errorCode?: string;
+ /**
+ * Optional `AbortSignal` so callers can enforce their own deadlines
+ * (e.g. the 15s sign-time sync timeout).
+ */
+ signal?: AbortSignal;
+};
+
+/**
+ * POST a JSON body to a CSC API endpoint and parse the response against the
+ * supplied Zod schema.
+ *
+ * Throws {@link AppError} on:
+ * - network/transport error (fetch threw)
+ * - non-2xx HTTP response (with CSC error body folded into the message)
+ * - malformed JSON response
+ * - schema validation failure
+ */
+export const cscJsonPost = async <T>(opts: CscJsonPostOptions, responseSchema: z.ZodSchema<T>): Promise<T> => {
+ const { url, body, accessToken, errorCode, signal } = opts;
+
+ let response: Response;
+
+ try {
+ response = await fetch(url, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Accept: 'application/json',
+ ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
+ },
+ body: JSON.stringify(body),
+ signal,
+ });
+ } catch (cause) {
+ throw buildCscRequestError({ url, status: 0, cause, errorCode });
+ }
+
+ if (!response.ok) {
+ const cscError = await readCscErrorBody(response);
+
+ throw buildCscRequestError({
+ url,
+ status: response.status,
+ cscError,
+ errorCode,
+ });
+ }
+
+ let json: unknown;
+
+ try {
+ json = await response.json();
+ } catch (cause) {
+ throw buildCscRequestError({ url, status: response.status, cause, errorCode });
+ }
+
+ const parsed = responseSchema.safeParse(json);
+
+ if (!parsed.success) {
+ throw buildCscRequestError({
+ url,
+ status: response.status,
+ cause: parsed.error,
+ errorCode,
+ });
+ }
+
+ return parsed.data;
+};
diff --git a/packages/ee/server-only/signing/csc/client/index.ts b/packages/ee/server-only/signing/csc/client/index.ts
new file mode 100644
index 000000000..6e84c1a82
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/index.ts
@@ -0,0 +1,32 @@
+/**
+ * CSC v1.0.4.0 HTTP client. Stateless function wrappers — one per endpoint,
+ * grouped by spec section. Bring your own base URL(s) and bearer token.
+ *
+ * Endpoint coverage (V1 scope):
+ * - §11.1 info → {@link cscInfo}
+ * - §11.4 credentials/list → {@link cscCredentialsList}
+ * - §11.5 credentials/info → {@link cscCredentialsInfo}
+ * - §11.9 signatures/signHash → {@link cscSignHash}
+ * - §11.10 signatures/timestamp → {@link cscTimestamp}
+ * - §8.3.2 oauth2/authorize → {@link buildCscServiceScopeAuthorizeUrl},
+ * {@link buildCscCredentialScopeAuthorizeUrl}
+ * - §8.3.3 oauth2/token → {@link exchangeCscAuthorizationCode},
+ * {@link refreshCscServiceToken}
+ * - §8.3.4 oauth2/revoke → {@link revokeCscToken}
+ *
+ * Out of scope for V1 (intentionally excluded; we use OAuth + single-sig):
+ * - §11.2 auth/login (HTTP Basic)
+ * - §11.3 auth/revoke (HTTP Basic)
+ * - §11.6 credentials/authorize (alternative to OAuth credential scope)
+ * - §11.7 credentials/extendTransaction
+ * - §11.8 credentials/sendOTP
+ *
+ * OAuth is delegated to `arctic` (same library `packages/auth/` uses).
+ */
+
+export * from './credentials';
+export * from './http';
+export * from './info';
+export * from './oauth';
+export * from './signatures';
+export * from './types';
diff --git a/packages/ee/server-only/signing/csc/client/info.ts b/packages/ee/server-only/signing/csc/client/info.ts
new file mode 100644
index 000000000..39195ed6b
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/info.ts
@@ -0,0 +1,42 @@
+import { AppErrorCode } from '@documenso/lib/errors/app-error';
+
+import { cscJsonPost, joinCscUrl } from './http';
+import { type TCscInfoRequest, type TCscInfoResponse, ZCscInfoResponseSchema } from './types';
+
+type CscInfoOptions = TCscInfoRequest & {
+ /**
+ * Base URI of the CSC service (e.g. `https://service.example.org/csc/v1`).
+ * Per §7.2, `info` is mounted relative to the service base URI; the OAuth
+ * base URI returned in `oauth2` is discovered from this call.
+ */
+ baseUrl: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * `info` (§11.1) — discovery method every CSC-conformant TSP MUST implement.
+ *
+ * Used at startup to:
+ *
+ * 1. Learn the OAuth 2.0 base URI (`oauth2`) for subsequent token / revoke
+ * calls. Per §11.1, this MAY differ from the API base URI.
+ * 2. Enumerate supported methods (`methods`) so the caller can fail fast
+ * when a required endpoint is absent.
+ * 3. Surface `signatures/timestamp` capability for the B-LTA seal step.
+ *
+ * Unauthenticated — `info` requires no bearer token. Failures throw
+ * `CSC_PROVIDER_INFO_FAILED` per the spec's startup-discovery error code.
+ */
+export const cscInfo = async (opts: CscInfoOptions): Promise<TCscInfoResponse> => {
+ const { baseUrl, lang, signal } = opts;
+
+ return await cscJsonPost(
+ {
+ url: joinCscUrl({ baseUrl, path: 'info' }),
+ body: lang ? { lang } : {},
+ errorCode: AppErrorCode.CSC_PROVIDER_INFO_FAILED,
+ signal,
+ },
+ ZCscInfoResponseSchema,
+ );
+};
diff --git a/packages/ee/server-only/signing/csc/client/oauth.ts b/packages/ee/server-only/signing/csc/client/oauth.ts
new file mode 100644
index 000000000..7935ddc68
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/oauth.ts
@@ -0,0 +1,321 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import {
+ ArcticFetchError,
+ CodeChallengeMethod,
+ generateCodeVerifier,
+ generateState,
+ OAuth2Client,
+ OAuth2RequestError,
+ type OAuth2Tokens,
+ UnexpectedErrorResponseBodyError,
+ UnexpectedResponseError,
+} from 'arctic';
+
+import { joinCscUrl } from './http';
+
+/**
+ * OAuth 2.0 surface for the CSC v1.0.4.0 protocol (§8.3.2 authorize,
+ * §8.3.3 token, §8.3.4 revoke).
+ *
+ * Backed by `arctic` — the same library `packages/auth/` uses for sign-in
+ * OAuth — so PKCE + state generation, token parsing, and revocation share a
+ * proven implementation. CSC-specific extension parameters (`credentialID`,
+ * `numSignatures`, `hash`, `description`, `account_token`, `clientData`,
+ * `lang` — §8.3.2) layer on top of the returned `URL` via
+ * `searchParams.set()`.
+ *
+ * Non-standard CSC bits arctic doesn't model directly:
+ * - `token_type === 'SAD'` for credential-scope responses (§8.3.3). Read from
+ * `tokens.tokenType()` which sources from raw `data`.
+ * - SAD is single-use and short-lived per spec; no refresh_token is issued
+ * for the credential scope. Callers SHOULD NOT call `refreshAccessToken`
+ * with a SAD.
+ *
+ * Re-exports `generateState` and `generateCodeVerifier` for callers that
+ * persist these in the OAuth-flow cookie.
+ */
+
+export { generateCodeVerifier, generateState };
+
+// ─── Client construction ─────────────────────────────────────────────────────
+
+type CreateCscOAuthClientOptions = {
+ clientId: string;
+ clientSecret: string;
+ redirectUri: string;
+};
+
+/**
+ * Construct an `OAuth2Client` bound to the CSC TSP's OAuth registration. The
+ * three values come from the env (`NEXT_PRIVATE_SIGNING_CSC_OAUTH_*`).
+ * Stateless — instantiate per request or cache at the transport singleton
+ * level; arctic's client carries no per-call state.
+ */
+export const createCscOAuthClient = ({
+ clientId,
+ clientSecret,
+ redirectUri,
+}: CreateCscOAuthClientOptions): OAuth2Client => {
+ return new OAuth2Client(clientId, clientSecret, redirectUri);
+};
+
+// ─── Authorize URL builders (§8.3.2) ─────────────────────────────────────────
+
+type AuthorizeUrlBaseOptions = {
+ client: OAuth2Client;
+ /**
+ * The TSP's OAuth base URI as returned by `info.oauth2` (§11.1). The
+ * `oauth2/authorize` path is joined on; per §8.3.2 NOTE 1 this can live on
+ * a different host from the API base URI.
+ */
+ oauthBaseUrl: string;
+ /** Opaque CSRF token; see {@link generateState}. Caller persists it. */
+ state: string;
+ /** PKCE verifier; see {@link generateCodeVerifier}. Caller persists it. */
+ codeVerifier: string;
+ /** Preferred response language (§11.1 `lang` parameter). */
+ lang?: string;
+ /**
+ * Arbitrary application-defined string echoed back at callback. WARNING per
+ * §8.3.2: this is forwarded verbatim to the TSP; never put secrets here.
+ */
+ clientData?: string;
+};
+
+const applyCscAuthorizeExtras = (url: URL, opts: { lang?: string; clientData?: string }): URL => {
+ if (opts.lang) {
+ url.searchParams.set('lang', opts.lang);
+ }
+
+ if (opts.clientData) {
+ url.searchParams.set('clientData', opts.clientData);
+ }
+
+ return url;
+};
+
+/**
+ * Build the `oauth2/authorize` URL for the **service** scope. Recipient
+ * follows this URL to authenticate at the TSP and grant access to list
+ * credentials + fetch credential info.
+ */
+export const buildCscServiceScopeAuthorizeUrl = (opts: AuthorizeUrlBaseOptions): URL => {
+ const { client, oauthBaseUrl, state, codeVerifier, lang, clientData } = opts;
+
+ const url = client.createAuthorizationURLWithPKCE(
+ joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/authorize' }),
+ state,
+ CodeChallengeMethod.S256,
+ codeVerifier,
+ ['service'],
+ );
+
+ return applyCscAuthorizeExtras(url, { lang, clientData });
+};
+
+type CredentialScopeAuthorizeOptions = AuthorizeUrlBaseOptions & {
+ /** Target credential (§8.3.2 — REQUIRED for credential scope). */
+ credentialId: string;
+ /** Number of signatures this SAD will authorise (§8.3.2 — REQUIRED). */
+ numSignatures: number;
+ /**
+ * Standard-base64-encoded hash values the SAD will be bound to. REQUIRED for
+ * SCAL2 credentials (§8.3.2). The builder converts each value to base64url
+ * before joining with `,` per the spec — §8.3.2 mandates base64url for the
+ * `hash` URL parameter, but the rest of the codebase (and the
+ * `signatures/signHash` JSON body per §11.9) uses standard base64. Callers
+ * pass what `Buffer.from(...).toString('base64')` produces.
+ */
+ hashes: string[];
+ /** Human-readable transaction description shown on the TSP's SCA page. */
+ description?: string;
+ /** Optional restricted-access token (JWT) some TSPs require (§8.3.2). */
+ accountToken?: string;
+};
+
+/**
+ * Convert a standard-base64 string to base64url (RFC 4648 §5). The CSC §8.3.2
+ * `hash` URL parameter requires base64url; TSPs reject standard base64 even
+ * after percent-decoding because `+`, `/`, and `=` are invalid base64url
+ * characters. JSON-body fields (§11.9 `signatures/signHash`) keep standard
+ * base64.
+ */
+const toBase64Url = (standardBase64: string): string =>
+ standardBase64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+/**
+ * Build the `oauth2/authorize` URL for the **credential** scope. The TSP
+ * binds the issued SAD to `hashes` so it can only sign those exact digests.
+ *
+ * Hash ordering in the SAD is independent of the order passed to
+ * `signatures/signHash` (§8.3.2) — the TSP matches by hash value, not
+ * position.
+ */
+export const buildCscCredentialScopeAuthorizeUrl = (opts: CredentialScopeAuthorizeOptions): URL => {
+ const {
+ client,
+ oauthBaseUrl,
+ state,
+ codeVerifier,
+ credentialId,
+ numSignatures,
+ hashes,
+ description,
+ accountToken,
+ lang,
+ clientData,
+ } = opts;
+
+ const url = client.createAuthorizationURLWithPKCE(
+ joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/authorize' }),
+ state,
+ CodeChallengeMethod.S256,
+ codeVerifier,
+ ['credential'],
+ );
+
+ url.searchParams.set('credentialID', credentialId);
+ url.searchParams.set('numSignatures', String(numSignatures));
+ url.searchParams.set('hash', hashes.map(toBase64Url).join(','));
+
+ if (description) {
+ url.searchParams.set('description', description);
+ }
+
+ if (accountToken) {
+ url.searchParams.set('account_token', accountToken);
+ }
+
+ return applyCscAuthorizeExtras(url, { lang, clientData });
+};
+
+// ─── Token exchange (§8.3.3) ─────────────────────────────────────────────────
+
+type ExchangeCodeOptions = {
+ client: OAuth2Client;
+ /** OAuth base URI from `info.oauth2`. `oauth2/token` is joined on. */
+ oauthBaseUrl: string;
+ /** Authorization code from the callback's `code` query param. */
+ code: string;
+ /** Same PKCE verifier passed to the authorize URL builder. */
+ codeVerifier: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * Exchange an authorization code for an access token. Used for both scopes;
+ * the response shape differs only in `token_type`:
+ *
+ * - service scope: `token_type === 'Bearer'`, optional `refresh_token`.
+ * - credential scope: `token_type === 'SAD'`, single-use, no refresh_token.
+ *
+ * Inspect `tokens.tokenType()` (or `tokens.data` for raw access) to
+ * discriminate.
+ */
+export const exchangeCscAuthorizationCode = async (opts: ExchangeCodeOptions): Promise<OAuth2Tokens> => {
+ const { client, oauthBaseUrl, code, codeVerifier } = opts;
+
+ try {
+ return await client.validateAuthorizationCode(
+ joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/token' }),
+ code,
+ codeVerifier,
+ );
+ } catch (err) {
+ throw mapArcticError(err, 'oauth2/token');
+ }
+};
+
+type RefreshServiceTokenOptions = {
+ client: OAuth2Client;
+ oauthBaseUrl: string;
+ /** Service-scope refresh token from a prior token exchange. */
+ refreshToken: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * Refresh a service-scope access token. Credential-scope SADs are NOT
+ * refreshable per §8.3.3 — only service scope issues refresh tokens.
+ *
+ * Scopes passed as `['service']` to keep the refresh narrow; the TSP may
+ * ignore the scope parameter on refresh per RFC 6749 §6.
+ */
+export const refreshCscServiceToken = async (opts: RefreshServiceTokenOptions): Promise<OAuth2Tokens> => {
+ const { client, oauthBaseUrl, refreshToken } = opts;
+
+ try {
+ return await client.refreshAccessToken(joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/token' }), refreshToken, [
+ 'service',
+ ]);
+ } catch (err) {
+ throw mapArcticError(err, 'oauth2/token');
+ }
+};
+
+// ─── Revoke (§8.3.4) ─────────────────────────────────────────────────────────
+
+type RevokeTokenOptions = {
+ client: OAuth2Client;
+ oauthBaseUrl: string;
+ /** Access token or refresh token to revoke. */
+ token: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * Revoke a CSC OAuth token. Per §8.3.4, revoking a refresh token also
+ * invalidates every access token derived from the same grant; revoking an
+ * access token only invalidates that access token.
+ *
+ * `204 No Content` on success; arctic resolves the promise. Failures
+ * surface as `CSC_REQUEST_FAILED` via {@link mapArcticError}.
+ */
+export const revokeCscToken = async (opts: RevokeTokenOptions): Promise<void> => {
+ const { client, oauthBaseUrl, token } = opts;
+
+ try {
+ await client.revokeToken(joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/revoke' }), token);
+ } catch (err) {
+ throw mapArcticError(err, 'oauth2/revoke');
+ }
+};
+
+// ─── Error normalisation ────────────────────────────────────────────────────
+
+/**
+ * Translate arctic's typed exception hierarchy into AppErrors consistent with
+ * the rest of the CSC client (see http.ts). Preserves the HTTP status when
+ * arctic surfaces it.
+ */
+const mapArcticError = (err: unknown, endpoint: string): AppError => {
+ if (err instanceof OAuth2RequestError) {
+ return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: `CSC ${endpoint} rejected: ${err.code}${err.description ? ` — ${err.description}` : ''}`,
+ });
+ }
+
+ if (err instanceof ArcticFetchError) {
+ return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: `CSC ${endpoint} fetch failed: ${err.message}`,
+ });
+ }
+
+ if (err instanceof UnexpectedResponseError) {
+ return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: `CSC ${endpoint} returned unexpected HTTP ${err.status}`,
+ statusCode: err.status,
+ });
+ }
+
+ if (err instanceof UnexpectedErrorResponseBodyError) {
+ return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: `CSC ${endpoint} returned HTTP ${err.status} with unparseable body`,
+ statusCode: err.status,
+ });
+ }
+
+ return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: `CSC ${endpoint} failed: ${err instanceof Error ? err.message : String(err)}`,
+ });
+};
diff --git a/packages/ee/server-only/signing/csc/client/signatures.ts b/packages/ee/server-only/signing/csc/client/signatures.ts
new file mode 100644
index 000000000..5253bc622
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/signatures.ts
@@ -0,0 +1,111 @@
+import { cscJsonPost, joinCscUrl } from './http';
+import {
+ type TCscSignHashRequest,
+ type TCscSignHashResponse,
+ type TCscTimestampRequest,
+ type TCscTimestampResponse,
+ ZCscSignHashResponseSchema,
+ ZCscTimestampResponseSchema,
+} from './types';
+
+type CscSignHashOptions = TCscSignHashRequest & {
+ baseUrl: string;
+ /** Service-scope bearer token. The SAD (in the body) is the credential-scope grant. */
+ accessToken: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * `signatures/signHash` (§11.9) — submit one or more pre-computed hashes for
+ * the TSP to sign with the credential identified by `credentialID`.
+ *
+ * Authorisation is two-layered:
+ * - The service-scope bearer token authenticates the API call itself.
+ * - The credential-scope SAD (in the JSON body) authorises the specific
+ * hashes — the TSP rejects with `invalid_request` ("Hash is not authorized
+ * by the SAD") if any hash in the array wasn't bound at SAD issuance.
+ *
+ * The returned `signatures` array is position-ordered with `hash` per §11.9.
+ * Callers SHALL preserve order when mapping responses back to PDF embed
+ * slots (the fifoSigner relies on this).
+ */
+export const cscSignHash = async (opts: CscSignHashOptions): Promise<TCscSignHashResponse> => {
+ const { baseUrl, accessToken, signal, credentialID, SAD, hash, hashAlgo, signAlgo, signAlgoParams, clientData } =
+ opts;
+
+ const body: Record<string, unknown> = {
+ credentialID,
+ SAD,
+ hash,
+ signAlgo,
+ };
+
+ if (hashAlgo !== undefined) {
+ body.hashAlgo = hashAlgo;
+ }
+
+ if (signAlgoParams !== undefined) {
+ body.signAlgoParams = signAlgoParams;
+ }
+
+ if (clientData !== undefined) {
+ body.clientData = clientData;
+ }
+
+ return await cscJsonPost(
+ {
+ url: joinCscUrl({ baseUrl, path: 'signatures/signHash' }),
+ body,
+ accessToken,
+ signal,
+ },
+ ZCscSignHashResponseSchema,
+ );
+};
+
+type CscTimestampOptions = TCscTimestampRequest & {
+ baseUrl: string;
+ /**
+ * Service-scope bearer token. Per §11.10 the timestamp endpoint may or may
+ * not require auth depending on TSP policy; the spec is silent. We send the
+ * token unconditionally because all known TSPs gate this endpoint.
+ */
+ accessToken: string;
+ signal?: AbortSignal;
+};
+
+/**
+ * `signatures/timestamp` (§11.10) — request an RFC 3161 / RFC 5816 time-stamp
+ * token for a pre-computed hash. Driven by {@link CscTspTimestampAuthority}
+ * at sign time, when {@link resolveCscSignTimeTsa} selects the TSP source
+ * (TSP advertises `signatures/timestamp` in `info.methods`). The bearer is
+ * the current recipient's own service-scope token. Seal-time archival
+ * timestamps do not go through this endpoint — they use the env-configured
+ * RFC 3161 TSA directly.
+ *
+ * If `nonce` is supplied, the TSP MUST round-trip it in the token — we leave
+ * verification to LibPDF / our TSA helper, not this client.
+ */
+export const cscTimestamp = async (opts: CscTimestampOptions): Promise<TCscTimestampResponse> => {
+ const { baseUrl, accessToken, signal, hash, hashAlgo, nonce, clientData } = opts;
+
+ const body: Record<string, unknown> = { hash, hashAlgo };
+
+ if (nonce !== undefined) {
+ body.nonce = nonce;
+ }
+
+ if (clientData !== undefined) {
+ body.clientData = clientData;
+ }
+
+ return await cscJsonPost(
+ {
+ url: joinCscUrl({ baseUrl, path: 'signatures/timestamp' }),
+ body,
+ accessToken,
+ signal,
+ },
+ ZCscTimestampResponseSchema,
+ );
+};
diff --git a/packages/ee/server-only/signing/csc/client/types.ts b/packages/ee/server-only/signing/csc/client/types.ts
new file mode 100644
index 000000000..2106ba75c
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/client/types.ts
@@ -0,0 +1,179 @@
+import { z } from 'zod';
+
+/**
+ * Zod schemas + types for every CSC v1.0.4.0 request/response shape the V1
+ * client touches. Field names mirror the spec exactly. Unknown fields are
+ * silently dropped (Zod default `.strip()`); we don't `.passthrough()` to
+ * keep parsed objects narrow.
+ *
+ * Out-of-scope endpoints (`auth/login`, `auth/revoke`, `credentials/authorize`,
+ * `credentials/extendTransaction`, `credentials/sendOTP`) intentionally have
+ * no schemas here — V1 uses OAuth + sequential single-signature flows only.
+ */
+
+// ─── §10.1 common error envelope ─────────────────────────────────────────────
+
+export const ZCscErrorResponseSchema = z.object({
+ error: z.string(),
+ error_description: z.string().optional(),
+});
+
+export type TCscErrorResponse = z.infer<typeof ZCscErrorResponseSchema>;
+
+// ─── §11.1 info ──────────────────────────────────────────────────────────────
+
+export const ZCscInfoRequestSchema = z.object({
+ lang: z.string().optional(),
+});
+
+export type TCscInfoRequest = z.infer<typeof ZCscInfoRequestSchema>;
+
+export const ZCscInfoResponseSchema = z.object({
+ specs: z.string(),
+ name: z.string(),
+ logo: z.string(),
+ region: z.string(),
+ lang: z.string(),
+ description: z.string(),
+ authType: z.array(z.string()),
+ // REQUIRED Conditional — present when authType includes `oauth2code` /
+ // `oauth2client`, or when any credential supports `oauth2code` authMode.
+ // We always need it for V1, but keeping the schema permissive matches the
+ // spec; absence is detected at the call site.
+ oauth2: z.string().optional(),
+ methods: z.array(z.string()),
+});
+
+export type TCscInfoResponse = z.infer<typeof ZCscInfoResponseSchema>;
+
+// ─── §11.4 credentials/list ──────────────────────────────────────────────────
+
+export const ZCscCredentialsListRequestSchema = z.object({
+ // OAuth2 user-specific service auth → userID MUST be omitted (§11.4 NOTE 1).
+ userID: z.string().optional(),
+ maxResults: z.number().int().positive().optional(),
+ pageToken: z.string().optional(),
+ clientData: z.string().optional(),
+});
+
+export type TCscCredentialsListRequest = z.infer<typeof ZCscCredentialsListRequestSchema>;
+
+export const ZCscCredentialsListResponseSchema = z.object({
+ credentialIDs: z.array(z.string()),
+ nextPageToken: z.string().optional(),
+});
+
+export type TCscCredentialsListResponse = z.infer<typeof ZCscCredentialsListResponseSchema>;
+
+// ─── §11.5 credentials/info ──────────────────────────────────────────────────
+
+export const ZCscCredentialsInfoRequestSchema = z.object({
+ credentialID: z.string(),
+ certificates: z.enum(['none', 'single', 'chain']).optional(),
+ certInfo: z.boolean().optional(),
+ authInfo: z.boolean().optional(),
+ lang: z.string().optional(),
+ clientData: z.string().optional(),
+});
+
+export type TCscCredentialsInfoRequest = z.infer<typeof ZCscCredentialsInfoRequestSchema>;
+
+export const ZCscCredentialsInfoKeySchema = z.object({
+ status: z.enum(['enabled', 'disabled']),
+ algo: z.array(z.string()),
+ // REQUIRED per §11.5 but kept optional here so the algorithm-resolver can
+ // surface absence as a typed `CSC_ALGORITHM_REFUSED` (matching the spec's
+ // policy table) instead of a generic transport schema failure.
+ len: z.number().int().positive().optional(),
+ // REQUIRED Conditional for ECDSA per §11.5; absence handled by the resolver.
+ curve: z.string().optional(),
+});
+
+export const ZCscCredentialsInfoCertSchema = z.object({
+ status: z.enum(['valid', 'expired', 'revoked', 'suspended']).optional(),
+ certificates: z.array(z.string()).optional(),
+ issuerDN: z.string().optional(),
+ serialNumber: z.string().optional(),
+ subjectDN: z.string().optional(),
+ validFrom: z.string().optional(),
+ validTo: z.string().optional(),
+});
+
+export const ZCscCredentialsInfoPinSchema = z.object({
+ presence: z.enum(['true', 'false', 'optional']),
+ format: z.enum(['A', 'N']).optional(),
+ label: z.string().optional(),
+ description: z.string().optional(),
+});
+
+export const ZCscCredentialsInfoOtpSchema = z.object({
+ presence: z.enum(['true', 'false', 'optional']),
+ type: z.enum(['offline', 'online']).optional(),
+ format: z.enum(['A', 'N']).optional(),
+ label: z.string().optional(),
+ description: z.string().optional(),
+ ID: z.string().optional(),
+ provider: z.string().optional(),
+});
+
+export const ZCscCredentialsInfoResponseSchema = z.object({
+ description: z.string().optional(),
+ key: ZCscCredentialsInfoKeySchema,
+ cert: ZCscCredentialsInfoCertSchema,
+ authMode: z.enum(['implicit', 'explicit', 'oauth2code']),
+ SCAL: z.enum(['1', '2']).optional(),
+ PIN: ZCscCredentialsInfoPinSchema.optional(),
+ OTP: ZCscCredentialsInfoOtpSchema.optional(),
+ multisign: z.number().int().min(1),
+ lang: z.string().optional(),
+});
+
+export type TCscCredentialsInfoResponse = z.infer<typeof ZCscCredentialsInfoResponseSchema>;
+
+// ─── §11.9 signatures/signHash ───────────────────────────────────────────────
+
+export const ZCscSignHashRequestSchema = z.object({
+ credentialID: z.string(),
+ SAD: z.string(),
+ // Base64-encoded raw message digests.
+ hash: z.array(z.string()).nonempty(),
+ // REQUIRED Conditional — OID of the hash algorithm. Omit only when implied
+ // by signAlgo (per §11.9). The caller decides.
+ hashAlgo: z.string().optional(),
+ signAlgo: z.string(),
+ // REQUIRED Conditional for algorithms like RSASSA-PSS.
+ signAlgoParams: z.string().optional(),
+ clientData: z.string().optional(),
+});
+
+export type TCscSignHashRequest = z.infer<typeof ZCscSignHashRequestSchema>;
+
+export const ZCscSignHashResponseSchema = z.object({
+ // Position-ordered Base64-encoded signed hashes matching the input order.
+ signatures: z.array(z.string()).nonempty(),
+});
+
+export type TCscSignHashResponse = z.infer<typeof ZCscSignHashResponseSchema>;
+
+// ─── §11.10 signatures/timestamp ─────────────────────────────────────────────
+
+export const ZCscTimestampRequestSchema = z.object({
+ hash: z.string(),
+ hashAlgo: z.string(),
+ // Hex-encoded random; SHALL round-trip in the timestamp token when supplied.
+ nonce: z.string().optional(),
+ clientData: z.string().optional(),
+});
+
+export type TCscTimestampRequest = z.infer<typeof ZCscTimestampRequestSchema>;
+
+export const ZCscTimestampResponseSchema = z.object({
+ // Base64-encoded RFC 3161 (with RFC 5816 update) time-stamp token.
+ timestamp: z.string(),
+});
+
+export type TCscTimestampResponse = z.infer<typeof ZCscTimestampResponseSchema>;
+
+// OAuth 2.0 token + revoke shapes are handled by the `arctic` library — see
+// `oauth.ts` in this directory. Arctic exposes `OAuth2Tokens` (with `.data`
+// available for non-standard CSC fields like `token_type === 'SAD'`).
diff --git a/packages/ee/server-only/signing/csc/cookies/blocking-error-cookie.ts b/packages/ee/server-only/signing/csc/cookies/blocking-error-cookie.ts
new file mode 100644
index 000000000..7b44382d1
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/cookies/blocking-error-cookie.ts
@@ -0,0 +1,120 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { Context } from 'hono';
+import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
+import { parseSigned, serialize } from 'hono/utils/cookie';
+import { z } from 'zod';
+
+import { CSC_BLOCKING_ERROR_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
+
+/**
+ * `csc_blocking_error` — one-shot surface for service-scope OAuth callback
+ * failures the recipient can't self-resolve (empty credential list, invalid
+ * cert, refused algorithm, etc.). The `/sign/{token}` loader reads + clears
+ * it on next visit so no error state rides on URL query params.
+ */
+
+const CSC_BLOCKING_ERROR_MAX_AGE_SECONDS = 60 * 10; // 10 minutes — matches the other short-lived CSC cookies.
+
+export const ZCscBlockingErrorPayloadSchema = z.object({
+ /** `AppErrorCode` value, e.g. `'CSC_CREDENTIAL_LIST_EMPTY'`. */
+ code: z.string().min(1),
+ /** Recipient token from `/sign/{token}`; loader scopes the error to its recipient. */
+ recipientToken: z.string().min(1),
+});
+
+export type TCscBlockingErrorPayload = z.infer<typeof ZCscBlockingErrorPayloadSchema>;
+
+type SetCscBlockingErrorCookieOptions = {
+ c: Context;
+ payload: TCscBlockingErrorPayload;
+};
+
+export const setCscBlockingErrorCookie = async (options: SetCscBlockingErrorCookieOptions): Promise<void> => {
+ const { c, payload } = options;
+
+ await setSignedCookie(c, CSC_BLOCKING_ERROR_COOKIE_NAME, JSON.stringify(payload), getCscCookieSecret(), {
+ ...cscCookieBaseOptions,
+ maxAge: CSC_BLOCKING_ERROR_MAX_AGE_SECONDS,
+ });
+};
+
+/**
+ * Read + validate the blocking-error cookie. Returns `null` when absent or
+ * signature-invalid; throws `INVALID_REQUEST` when signed-but-malformed
+ * (tamper-shaped, mirroring `oauth-flow-cookie.ts`).
+ */
+export const getCscBlockingErrorCookie = async (c: Context): Promise<TCscBlockingErrorPayload | null> => {
+ const raw = await getSignedCookie(c, getCscCookieSecret(), CSC_BLOCKING_ERROR_COOKIE_NAME);
+
+ if (!raw) {
+ return null;
+ }
+
+ let parsedJson: unknown;
+
+ try {
+ parsedJson = JSON.parse(raw);
+ } catch {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC blocking error cookie payload is not valid JSON.',
+ });
+ }
+
+ const result = ZCscBlockingErrorPayloadSchema.safeParse(parsedJson);
+
+ if (!result.success) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC blocking error cookie payload failed schema validation.',
+ });
+ }
+
+ return result.data;
+};
+
+export const clearCscBlockingErrorCookie = (c: Context): void => {
+ deleteCookie(c, CSC_BLOCKING_ERROR_COOKIE_NAME, cscCookieBaseOptions);
+};
+
+/**
+ * Remix-compatible reader: parses + HMAC-verifies the blocking-error cookie
+ * from a raw `Cookie` header on a standard `Request`. Returns `null` when
+ * absent, signature-invalid, or payload-malformed (no throw — the loader
+ * only uses the cookie advisorily, so a bad cookie shouldn't break the page).
+ */
+export const readCscBlockingErrorFromRequest = async (request: Request): Promise<TCscBlockingErrorPayload | null> => {
+ const cookieHeader = request.headers.get('cookie');
+
+ if (!cookieHeader) {
+ return null;
+ }
+
+ const parsed = await parseSigned(cookieHeader, getCscCookieSecret(), CSC_BLOCKING_ERROR_COOKIE_NAME);
+
+ const value = parsed[CSC_BLOCKING_ERROR_COOKIE_NAME];
+
+ if (typeof value !== 'string') {
+ return null;
+ }
+
+ try {
+ const json = JSON.parse(value);
+
+ const result = ZCscBlockingErrorPayloadSchema.safeParse(json);
+
+ return result.success ? result.data : null;
+ } catch {
+ return null;
+ }
+};
+
+/**
+ * Serialised `Set-Cookie` header value that expires the cookie immediately.
+ * Use in a Remix loader's response headers to clear the cookie after the
+ * loader reads it once.
+ */
+export const buildClearCscBlockingErrorCookieHeader = (): string => {
+ return serialize(CSC_BLOCKING_ERROR_COOKIE_NAME, '', {
+ ...cscCookieBaseOptions,
+ maxAge: 0,
+ });
+};
diff --git a/packages/ee/server-only/signing/csc/cookies/oauth-flow-cookie.ts b/packages/ee/server-only/signing/csc/cookies/oauth-flow-cookie.ts
new file mode 100644
index 000000000..37eea9323
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/cookies/oauth-flow-cookie.ts
@@ -0,0 +1,85 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { Context } from 'hono';
+import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
+import { z } from 'zod';
+
+import { CSC_OAUTH_FLOW_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
+
+/**
+ * `csc_oauth_flow` — single-round-trip carrier across `/api/csc/oauth/authorize`
+ * → TSP → `/api/csc/oauth/callback`. Holds the PKCE verifier + state plus the
+ * Documenso-side context (`recipientToken`, optional `sessionId`) the
+ * callback needs to resume the right signing flow.
+ *
+ * JSON-encoded inside a single signed cookie; structurally validated on read
+ * so a tampered or stale shape can't smuggle bad state into the callback.
+ */
+
+const CSC_OAUTH_FLOW_MAX_AGE_SECONDS = 60 * 10; // 10 minutes — matches /api/auth/oauth/* convention.
+
+export const ZCscOAuthFlowPayloadSchema = z.object({
+ /** `'service'` for the first round-trip, `'credential'` for the SAD round-trip. */
+ scope: z.enum(['service', 'credential']),
+ /** Arctic-generated CSRF token; re-validated against `?state` at callback. */
+ state: z.string().min(1),
+ /** Arctic-generated PKCE verifier (RFC 7636); paired with the URL's `code_challenge`. */
+ codeVerifier: z.string().min(1),
+ /** Recipient signing token from `/sign/{token}`; threads recipient identity through the round-trip. */
+ recipientToken: z.string().min(1),
+ /** CSC session id — present only on `credential`-scope flows (set at prep). */
+ sessionId: z.string().min(1).optional(),
+});
+
+export type TCscOAuthFlowPayload = z.infer<typeof ZCscOAuthFlowPayloadSchema>;
+
+type SetCscOAuthFlowCookieOptions = {
+ c: Context;
+ payload: TCscOAuthFlowPayload;
+};
+
+export const setCscOAuthFlowCookie = async (options: SetCscOAuthFlowCookieOptions): Promise<void> => {
+ const { c, payload } = options;
+
+ await setSignedCookie(c, CSC_OAUTH_FLOW_COOKIE_NAME, JSON.stringify(payload), getCscCookieSecret(), {
+ ...cscCookieBaseOptions,
+ maxAge: CSC_OAUTH_FLOW_MAX_AGE_SECONDS,
+ });
+};
+
+/**
+ * Read + validate the OAuth-flow cookie. Returns `null` when the cookie is
+ * absent or the signature is invalid; throws `INVALID_REQUEST` when the
+ * payload is structurally bad (signed but malformed JSON / schema mismatch),
+ * since that's tamper-shaped, not a normal missing-cookie case.
+ */
+export const getCscOAuthFlowCookie = async (c: Context): Promise<TCscOAuthFlowPayload | null> => {
+ const raw = await getSignedCookie(c, getCscCookieSecret(), CSC_OAUTH_FLOW_COOKIE_NAME);
+
+ if (!raw) {
+ return null;
+ }
+
+ let parsedJson: unknown;
+
+ try {
+ parsedJson = JSON.parse(raw);
+ } catch {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC OAuth flow cookie payload is not valid JSON.',
+ });
+ }
+
+ const result = ZCscOAuthFlowPayloadSchema.safeParse(parsedJson);
+
+ if (!result.success) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC OAuth flow cookie payload failed schema validation.',
+ });
+ }
+
+ return result.data;
+};
+
+export const clearCscOAuthFlowCookie = (c: Context): void => {
+ deleteCookie(c, CSC_OAUTH_FLOW_COOKIE_NAME, cscCookieBaseOptions);
+};
diff --git a/packages/ee/server-only/signing/csc/cookies/sad-session-cookie.ts b/packages/ee/server-only/signing/csc/cookies/sad-session-cookie.ts
new file mode 100644
index 000000000..6c4df0d67
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/cookies/sad-session-cookie.ts
@@ -0,0 +1,61 @@
+import type { Context } from 'hono';
+import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
+import { parseSigned } from 'hono/utils/cookie';
+
+import { CSC_SAD_SESSION_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
+
+/**
+ * `csc_sad_session` — HMAC-signed `CscSession` cuid. Set after the
+ * credential-scope OAuth callback exchanges code → SAD; pointed at the
+ * server-side session row that owns the SAD + the prep-time item hashes.
+ *
+ * Lifetime mirrors the TSP-asserted SAD expiry (`sadExpiresAt`) so the cookie
+ * cannot outlive its server-side authorisation. Cleared by the sync sign
+ * mutation on success; otherwise decays naturally with the browser TTL.
+ */
+
+type SetCscSadSessionCookieOptions = {
+ c: Context;
+ sessionId: string;
+ /** Mirror of `CscSession.sadExpiresAt`; cookie expires no later than the SAD. */
+ expiresAt: Date;
+};
+
+export const setCscSadSessionCookie = async (options: SetCscSadSessionCookieOptions): Promise<void> => {
+ const { c, sessionId, expiresAt } = options;
+
+ await setSignedCookie(c, CSC_SAD_SESSION_COOKIE_NAME, sessionId, getCscCookieSecret(), {
+ ...cscCookieBaseOptions,
+ expires: expiresAt,
+ });
+};
+
+export const getCscSadSessionCookie = async (c: Context): Promise<string | null> => {
+ const value = await getSignedCookie(c, getCscCookieSecret(), CSC_SAD_SESSION_COOKIE_NAME);
+
+ // `getSignedCookie` returns `false` on signature mismatch, `undefined` when
+ // the cookie is absent. Both collapse to `null` for the caller's sake.
+ return value ? value : null;
+};
+
+export const clearCscSadSessionCookie = (c: Context): void => {
+ deleteCookie(c, CSC_SAD_SESSION_COOKIE_NAME, cscCookieBaseOptions);
+};
+
+/**
+ * Remix-compatible reader: parses + HMAC-verifies the SAD-session cookie
+ * from a raw `Cookie` header on a standard `Request`. Mirrors
+ * `getCscSadSessionCookie` but works outside Hono's `Context`.
+ */
+export const readCscSadSessionFromRequest = async (request: Request): Promise<string | null> => {
+ const cookieHeader = request.headers.get('cookie');
+
+ if (!cookieHeader) {
+ return null;
+ }
+
+ const parsed = await parseSigned(cookieHeader, getCscCookieSecret(), CSC_SAD_SESSION_COOKIE_NAME);
+ const value = parsed[CSC_SAD_SESSION_COOKIE_NAME];
+
+ return typeof value === 'string' ? value : null;
+};
diff --git a/packages/ee/server-only/signing/csc/cookies/service-session-cookie.ts b/packages/ee/server-only/signing/csc/cookies/service-session-cookie.ts
new file mode 100644
index 000000000..5a8267d78
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/cookies/service-session-cookie.ts
@@ -0,0 +1,65 @@
+import type { Context } from 'hono';
+import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
+import { parseSigned } from 'hono/utils/cookie';
+
+import { CSC_SERVICE_SESSION_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
+
+/**
+ * `csc_service_session` — recipient-scoped attestation that this browser just
+ * completed a service-scope OAuth round-trip for `<recipientToken>`. The
+ * `/sign/{token}` loader compares the cookie value against the path token; on
+ * match it skips re-auth, breaking the redirect loop that would otherwise
+ * occur when the TSP silently re-grants from its cached SCA session.
+ *
+ * Covers the long-lived T1→T3 window (recipient on the signing page filling
+ * fields, before clicking Sign). `csc_sad_session` covers the much shorter
+ * T4→T5 window (active signing transaction); the two are complementary, not
+ * substitutes.
+ *
+ * TTL = TSP-asserted service-scope `expires_in` so the trust window can never
+ * outlive the underlying access token.
+ */
+
+type SetCscServiceSessionCookieOptions = {
+ c: Context;
+ recipientToken: string;
+ /** TSP service-scope `expires_in` in seconds. Mirrored as the cookie max-age. */
+ ttlSeconds: number;
+};
+
+export const setCscServiceSessionCookie = async (options: SetCscServiceSessionCookieOptions): Promise<void> => {
+ const { c, recipientToken, ttlSeconds } = options;
+
+ await setSignedCookie(c, CSC_SERVICE_SESSION_COOKIE_NAME, recipientToken, getCscCookieSecret(), {
+ ...cscCookieBaseOptions,
+ maxAge: ttlSeconds,
+ });
+};
+
+export const getCscServiceSessionCookie = async (c: Context): Promise<string | null> => {
+ const value = await getSignedCookie(c, getCscCookieSecret(), CSC_SERVICE_SESSION_COOKIE_NAME);
+
+ return value ? value : null;
+};
+
+export const clearCscServiceSessionCookie = (c: Context): void => {
+ deleteCookie(c, CSC_SERVICE_SESSION_COOKIE_NAME, cscCookieBaseOptions);
+};
+
+/**
+ * Remix-compatible reader: parses + HMAC-verifies the service-session cookie
+ * from a raw `Cookie` header on a standard `Request`. Mirrors
+ * `getCscServiceSessionCookie` but works outside Hono's `Context`.
+ */
+export const readCscServiceSessionFromRequest = async (request: Request): Promise<string | null> => {
+ const cookieHeader = request.headers.get('cookie');
+
+ if (!cookieHeader) {
+ return null;
+ }
+
+ const parsed = await parseSigned(cookieHeader, getCscCookieSecret(), CSC_SERVICE_SESSION_COOKIE_NAME);
+ const value = parsed[CSC_SERVICE_SESSION_COOKIE_NAME];
+
+ return typeof value === 'string' ? value : null;
+};
diff --git a/packages/ee/server-only/signing/csc/cookies/shared.ts b/packages/ee/server-only/signing/csc/cookies/shared.ts
new file mode 100644
index 000000000..3280c0c2a
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/cookies/shared.ts
@@ -0,0 +1,46 @@
+import { formatSecureCookieName, getCookieDomain, useSecureCookies } from '@documenso/lib/constants/auth';
+import { requireEnv } from '@documenso/lib/utils/env';
+
+/**
+ * Shared HMAC secret + base attribute set for the CSC cookies.
+ *
+ * `NEXTAUTH_SECRET` is reused so signed-cookie verification stays uniform
+ * across the auth + CSC surfaces. The `sameSite` conditional matches
+ * `sessionCookieOptions` in `@documenso/auth` so a future embedding flow
+ * (CSC inside an `<iframe>` on a partner host) works without a separate
+ * cookie-attribute regime.
+ */
+
+/** HMAC secret for hono `setSignedCookie` / `getSignedCookie`. */
+export const getCscCookieSecret = (): string => requireEnv('NEXTAUTH_SECRET');
+
+/**
+ * CSC cookie names; prefixed with `__Secure-` in production over HTTPS.
+ *
+ * Naming maps 1:1 to the CSC OAuth scope each cookie attests:
+ * - `csc_service_session` — service-scope grant (long-lived per-browser SCA
+ * attestation; lifetime = TSP `expires_in`).
+ * - `csc_sad_session` — credential-scope grant in progress (in-flight signing
+ * transaction; lifetime = SAD lifetime).
+ * - `csc_oauth_flow` — single-round-trip carrier across authorize → callback
+ * (scope-agnostic; both flows reuse it).
+ * - `csc_blocking_error` — callback failure surface; carries an unresolvable
+ * service-scope error (e.g. empty credential list, refused algorithm) to
+ * the next `/sign/{token}` loader, read-once.
+ */
+export const CSC_SERVICE_SESSION_COOKIE_NAME = formatSecureCookieName('csc_service_session');
+export const CSC_SAD_SESSION_COOKIE_NAME = formatSecureCookieName('csc_sad_session');
+export const CSC_OAUTH_FLOW_COOKIE_NAME = formatSecureCookieName('csc_oauth_flow');
+export const CSC_BLOCKING_ERROR_COOKIE_NAME = formatSecureCookieName('csc_blocking_error');
+
+/**
+ * Base options spread into every CSC cookie. Callers add per-cookie expiry
+ * (`maxAge` or `expires`) on top.
+ */
+export const cscCookieBaseOptions = {
+ httpOnly: true,
+ path: '/',
+ sameSite: useSecureCookies ? 'none' : 'lax',
+ secure: useSecureCookies,
+ domain: getCookieDomain(),
+} as const;
diff --git a/packages/ee/server-only/signing/csc/credential.ts b/packages/ee/server-only/signing/csc/credential.ts
new file mode 100644
index 000000000..ef0a8c7e2
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/credential.ts
@@ -0,0 +1,184 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+import { Prisma } from '@prisma/client';
+
+/**
+ * DB helpers for `CscCredential` — the per-recipient row that holds the
+ * TSP-validated certificate chain, the resolved algorithm policy, and the
+ * encrypted service-scope access token.
+ *
+ * Lifecycle mirrors {@link sign-session.ts} but with a longer-lived row:
+ *
+ * - {@link upsertCscCredential} — service-scope OAuth callback writes the
+ * full credential after `credentials/info` + algorithm validation succeed.
+ * Re-runs replace prior bytes (cert / token rotates as the TSP refreshes).
+ * - {@link loadCscCredential} — sign-time fetches by `recipientId` to recover
+ * the persisted algorithm + encrypted service token; returns `null` when
+ * the recipient never completed service-scope OAuth.
+ *
+ * Encryption is the caller's job — both byte columns hold raw ciphertext
+ * produced by {@link encryptCscToken} so the helpers stay cipher-agnostic.
+ * Cascade cleanup on `Recipient` delete removes the row transitively.
+ */
+
+export type CscCredentialRow = {
+ id: string;
+ recipientId: number;
+ providerId: string;
+ credentialId: string;
+ certCache: Uint8Array | null;
+ signatureAlgorithm: string;
+ keyType: string;
+ digestAlgorithm: string;
+ keyLenBits: number | null;
+ signAlgoParams: string | null;
+ serviceTokenCiphertext: Uint8Array | null;
+ serviceTokenExpiresAt: Date | null;
+ createdAt: Date;
+ updatedAt: Date;
+};
+
+type UpsertCscCredentialInput = {
+ recipientId: number;
+ providerId: string;
+ credentialId: string;
+ /** Length-prefixed X.509 chain — produced from `cscCredentialsInfo.cert.certificates`. */
+ certCache: Uint8Array;
+ /** OID persisted from {@link CscAlgorithmPolicy.signAlgoOid}. */
+ signatureAlgorithm: string;
+ /** `'RSA'` or `'ECDSA'` from the resolved policy. */
+ keyType: string;
+ /** `'SHA-256'` / `'SHA-384'` / `'SHA-512'` from the resolved policy. */
+ digestAlgorithm: string;
+ keyLenBits: number;
+ /** RSASSA-PSS only; omit otherwise. */
+ signAlgoParams?: string;
+ /** Output of {@link encryptCscToken}. */
+ serviceTokenCiphertext: Uint8Array;
+ /** Mirrors the TSP's `expires_in` projected onto wall-clock. */
+ serviceTokenExpiresAt: Date;
+};
+
+/**
+ * Create or refresh the per-recipient credential row at service-scope OAuth
+ * callback success. Replaces every prior byte payload — a re-auth always
+ * supersedes the prior cert + token (TSPs may have rotated either).
+ */
+export const upsertCscCredential = async (input: UpsertCscCredentialInput): Promise<CscCredentialRow> => {
+ const {
+ recipientId,
+ providerId,
+ credentialId,
+ certCache,
+ signatureAlgorithm,
+ keyType,
+ digestAlgorithm,
+ keyLenBits,
+ signAlgoParams,
+ serviceTokenCiphertext,
+ serviceTokenExpiresAt,
+ } = input;
+
+ const row = await prisma.cscCredential.upsert({
+ where: { recipientId },
+ create: {
+ recipientId,
+ providerId,
+ credentialId,
+ certCache,
+ signatureAlgorithm,
+ keyType,
+ digestAlgorithm,
+ keyLenBits,
+ signAlgoParams: signAlgoParams ?? null,
+ serviceTokenCiphertext,
+ serviceTokenExpiresAt,
+ },
+ update: {
+ providerId,
+ credentialId,
+ certCache,
+ signatureAlgorithm,
+ keyType,
+ digestAlgorithm,
+ keyLenBits,
+ signAlgoParams: signAlgoParams ?? null,
+ serviceTokenCiphertext,
+ serviceTokenExpiresAt,
+ },
+ });
+
+ return toCscCredentialRow(row);
+};
+
+/**
+ * Fetch the credential row for a recipient. Returns `null` when absent — the
+ * recipient hasn't completed service-scope OAuth yet (loader path) or the
+ * recipient cascade fired (cleanup path). Both are normal terminal outcomes.
+ */
+export const loadCscCredential = async (recipientId: number): Promise<CscCredentialRow | null> => {
+ const row = await prisma.cscCredential.findUnique({
+ where: { recipientId },
+ });
+
+ return row ? toCscCredentialRow(row) : null;
+};
+
+/**
+ * Explicit delete by recipient id. Recipient-cascade handles routine cleanup;
+ * this helper is for operator-triggered re-auth flows (force the next visit
+ * to re-do service-scope OAuth even within the trust window).
+ *
+ * Throws `NOT_FOUND` when the row is already gone — semantically distinct
+ * from {@link loadCscCredential}'s nullable return because explicit delete
+ * is a deliberate operation and silent no-op would mask flow-state bugs.
+ */
+export const deleteCscCredential = async (recipientId: number): Promise<CscCredentialRow> => {
+ try {
+ const row = await prisma.cscCredential.delete({
+ where: { recipientId },
+ });
+
+ return toCscCredentialRow(row);
+ } catch (err) {
+ if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2025') {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `CSC credential for recipient ${recipientId} not found.`,
+ });
+ }
+
+ throw err;
+ }
+};
+
+const toCscCredentialRow = (row: {
+ id: string;
+ recipientId: number;
+ providerId: string;
+ credentialId: string;
+ certCache: Uint8Array | null;
+ signatureAlgorithm: string;
+ keyType: string;
+ digestAlgorithm: string;
+ keyLenBits: number | null;
+ signAlgoParams: string | null;
+ serviceTokenCiphertext: Uint8Array | null;
+ serviceTokenExpiresAt: Date | null;
+ createdAt: Date;
+ updatedAt: Date;
+}): CscCredentialRow => ({
+ id: row.id,
+ recipientId: row.recipientId,
+ providerId: row.providerId,
+ credentialId: row.credentialId,
+ certCache: row.certCache,
+ signatureAlgorithm: row.signatureAlgorithm,
+ keyType: row.keyType,
+ digestAlgorithm: row.digestAlgorithm,
+ keyLenBits: row.keyLenBits,
+ signAlgoParams: row.signAlgoParams,
+ serviceTokenCiphertext: row.serviceTokenCiphertext,
+ serviceTokenExpiresAt: row.serviceTokenExpiresAt,
+ createdAt: row.createdAt,
+ updatedAt: row.updatedAt,
+});
diff --git a/packages/ee/server-only/signing/csc/execute-tsp-sign.ts b/packages/ee/server-only/signing/csc/execute-tsp-sign.ts
new file mode 100644
index 000000000..5045b33d8
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/execute-tsp-sign.ts
@@ -0,0 +1,546 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { jobs } from '@documenso/lib/jobs/client';
+import { sendPendingEmail } from '@documenso/lib/server-only/document/send-pending-email';
+import { getRecipientByToken } from '@documenso/lib/server-only/recipient/get-recipient-by-token';
+import { triggerWebhook } from '@documenso/lib/server-only/webhooks/trigger/trigger-webhook';
+import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
+import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '@documenso/lib/types/webhook-payload';
+import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
+import { extractDocumentAuthMethods } from '@documenso/lib/utils/document-auth';
+import { mapSecondaryIdToDocumentId } from '@documenso/lib/utils/envelope';
+import { prisma } from '@documenso/prisma';
+import { PDF } from '@libpdf/core';
+import {
+ type DocumentDataType,
+ EnvelopeType,
+ RecipientRole,
+ SendStatus,
+ SigningStatus,
+ WebhookTriggerEvents,
+} from '@prisma/client';
+
+import { type CscDigest, hashOidForDigest, policyToLibpdfSignerAlgo } from './algorithm-resolver';
+import { decodeCscCertChain } from './cert-chain';
+import { decryptCscToken } from './ciphers';
+import { cscSignHash } from './client/signatures';
+import { loadCscCredential } from './credential';
+import { buildTspAnchorName } from './pdf-names';
+import { consumeCscSession, loadCscSession } from './sign-session';
+import { CscCaptureSigner } from './signers/capture-signer';
+import { CscFifoSigner } from './signers/fifo-signer';
+import { getCscTransport } from './transport';
+import { resolveCscSignTimeTsa } from './tsa-resolver';
+
+/**
+ * CSC TSP sign-time orchestrator.
+ *
+ * Two-pass run, both passes operating on the same prep-time-persisted PDF
+ * bytes (`CscSession.items[i].documentDataId` pins an immutable rendered
+ * orphan row — see `prepare-recipient-signing.ts`):
+ *
+ * 1. Capture re-derives each item's `signedAttrs` digest under the
+ * session-pinned `signingTime` and asserts it matches the prep-time hash
+ * bit-for-bit. Defense in depth — the bytes are identical so a mismatch
+ * means libpdf changed between prep and sign or the row was tampered
+ * with. Throws `CSC_BASE_DOCUMENT_MUTATED` on divergence.
+ * 2. A single batched `signatures/signHash` (§11.9) returns position-ordered
+ * signatures that the embed pass writes back into the same anchors via
+ * `CscFifoSigner`.
+ *
+ * Output bytes are in-place-copied onto `envelopeItem.documentData` (the
+ * row id stays stable; only `type` + `data` change) — same pattern as
+ * `materializeTspAnchorsForEnvelope`. The uploaded rows from
+ * `putPdfFileServerSide` orbit as orphans.
+ *
+ * Persistence is bundled into one outer transaction so document-content
+ * updates, recipient signing-status, audit log, and session consume commit
+ * atomically. Post-tx side effects (webhooks, emails) run after.
+ */
+
+export type ExecuteTspSignOptions = {
+ sessionId: string;
+ recipientToken: string;
+ requestMetadata?: RequestMetadata;
+};
+
+export type ExecuteTspSignResult = { outcome: 'signed' } | { outcome: 'already_signed' };
+
+type CapturedItem = {
+ envelopeItemId: string;
+ recapturedDigestB64: string;
+ anchorName: string;
+ pdfBytes: Uint8Array;
+};
+
+type SignedItemDataUpdate = {
+ /** Existing `envelopeItem.documentDataId` — receives the in-place data update. */
+ envelopeItemDataId: string;
+ /** Payload to copy onto the existing row. */
+ uploadedType: DocumentDataType;
+ uploadedData: string;
+};
+
+export const executeTspSign = async (opts: ExecuteTspSignOptions): Promise<ExecuteTspSignResult> => {
+ const { sessionId, recipientToken, requestMetadata } = opts;
+
+ const session = await loadCscSession(sessionId);
+
+ if (!session) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `CSC session "${sessionId}" not found.`,
+ });
+ }
+
+ const recipient = await getRecipientByToken({ token: recipientToken }).catch(() => null);
+
+ if (!recipient) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `Recipient with token "${recipientToken}" not found.`,
+ });
+ }
+
+ if (recipient.id !== session.recipientId) {
+ throw new AppError(AppErrorCode.UNAUTHORIZED, {
+ message: 'CSC session does not belong to the recipient identified by token.',
+ });
+ }
+
+ // Idempotency: a 15s tRPC timeout that races with a successful sign can
+ // leave the client retrying after the recipient row already flipped to
+ // SIGNED. Return success rather than re-running.
+ if (recipient.signingStatus === SigningStatus.SIGNED) {
+ return { outcome: 'already_signed' };
+ }
+
+ if (!session.encryptedSad || !session.sadExpiresAt) {
+ throw new AppError(AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN, {
+ message: 'CSC session has no attached SAD — credential-scope OAuth must complete first.',
+ });
+ }
+
+ if (session.sadExpiresAt.getTime() <= Date.now()) {
+ throw new AppError(AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN, {
+ message: 'CSC SAD expired before sign-time execution.',
+ });
+ }
+
+ const sad = decryptCscToken(session.encryptedSad);
+
+ if (!sad) {
+ throw new AppError(AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN, {
+ message: 'CSC SAD decrypt failed — key rotation or row corruption.',
+ });
+ }
+
+ const credential = await loadCscCredential(recipient.id);
+
+ if (!credential) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'CSC credential missing at sign time.',
+ });
+ }
+
+ if (!credential.certCache) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: 'CSC credential has no persisted certificate chain.',
+ });
+ }
+
+ if (credential.keyLenBits === null) {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: 'CSC credential omits persisted keyLenBits — service-scope OAuth must re-run.',
+ });
+ }
+
+ if (!credential.serviceTokenCiphertext || !credential.serviceTokenExpiresAt) {
+ throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: 'CSC credential has no persisted service token — recipient must re-auth.',
+ });
+ }
+
+ if (credential.serviceTokenExpiresAt.getTime() <= Date.now()) {
+ throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: 'CSC service token expired — recipient must re-auth via service-scope OAuth.',
+ });
+ }
+
+ const serviceToken = decryptCscToken(credential.serviceTokenCiphertext);
+
+ if (!serviceToken) {
+ throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: 'CSC service token decrypt failed — operator re-auth required.',
+ });
+ }
+
+ const chain = decodeCscCertChain(credential.certCache);
+
+ const algo = policyToLibpdfSignerAlgo({
+ keyType: credential.keyType as 'RSA' | 'ECDSA',
+ digestAlgorithm: credential.digestAlgorithm as CscDigest,
+ signAlgoOid: credential.signatureAlgorithm,
+ keyLenBits: credential.keyLenBits,
+ hashAlgoOid: '',
+ });
+
+ const envelope = await prisma.envelope.findUniqueOrThrow({
+ where: { id: session.envelopeId },
+ include: {
+ envelopeItems: { include: { documentData: true } },
+ recipients: true,
+ documentMeta: true,
+ },
+ });
+
+ // Capture pass: iterate session.items in order so the resulting hash array
+ // is position-bound to session.items[*].ordinal.
+ const capturedItems: CapturedItem[] = [];
+
+ for (let i = 0; i < session.items.length; i++) {
+ const sessionItem = session.items[i];
+
+ const envelopeItem = envelope.envelopeItems.find((item) => item.id === sessionItem.envelopeItemId);
+
+ if (!envelopeItem) {
+ throw new AppError(AppErrorCode.CSC_BASE_DOCUMENT_MUTATED, {
+ message: `Session references envelope item "${sessionItem.envelopeItemId}" not on envelope.`,
+ });
+ }
+
+ const pinnedDocumentData = await prisma.documentData.findUniqueOrThrow({
+ where: { id: sessionItem.documentDataId },
+ });
+
+ const bytes = await getFileServerSide(pinnedDocumentData);
+ const pdfDoc = await PDF.load(bytes);
+
+ const captureSigner = new CscCaptureSigner({
+ certificate: chain[0],
+ certificateChain: chain.slice(1),
+ algo,
+ });
+
+ const anchorName = buildTspAnchorName(recipient.id, envelopeItem.id);
+
+ // Capture pass stays at B-B even though the embed pass below is B-T:
+ // libpdf's B-T signature timestamp is added as a CMS *unsigned*
+ // attribute *after* `signer.sign()` runs over the signed-attrs digest.
+ // The signed-attrs builder (see CAdESDetachedBuilder.create in
+ // @libpdf/core) takes only (signer, documentHash, digestAlgorithm,
+ // signingTime) — no level-conditional attributes — so B-B and B-T
+ // produce byte-identical signed-attrs for the same inputs. Capturing
+ // at B-B avoids dragging the TSA into the dry-run.
+ await pdfDoc.sign({
+ signer: captureSigner,
+ fieldName: anchorName,
+ signingTime: session.signingTime,
+ level: 'B-B',
+ digestAlgorithm: algo.digestAlgorithm,
+ });
+
+ if (captureSigner.capturedDigest === null) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CscCaptureSigner was not invoked by pdf.sign during sign-time capture.',
+ });
+ }
+
+ const recapturedDigestB64 = Buffer.from(captureSigner.capturedDigest).toString('base64');
+
+ if (recapturedDigestB64 !== sessionItem.hashB64) {
+ throw new AppError(AppErrorCode.CSC_BASE_DOCUMENT_MUTATED, {
+ message: `Re-derived signedAttrs digest at sign time diverged from prep-time hash for envelope item "${envelopeItem.id}".`,
+ });
+ }
+
+ capturedItems.push({
+ envelopeItemId: envelopeItem.id,
+ recapturedDigestB64,
+ anchorName,
+ pdfBytes: bytes,
+ });
+ }
+
+ // Defensive: session-item / captured-item position binding must hold.
+ for (let i = 0; i < capturedItems.length; i++) {
+ if (capturedItems[i].envelopeItemId !== session.items[i].envelopeItemId) {
+ throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
+ message: 'Capture-pass item ordering diverged from session-pinned ordering.',
+ });
+ }
+ }
+
+ if (capturedItems.length === 0) {
+ throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
+ message: 'CSC session contains no items — nothing to sign.',
+ });
+ }
+
+ const hashes = capturedItems.map((c) => c.recapturedDigestB64);
+ // The cscSignHash request schema requires a non-empty tuple; the explicit
+ // check above narrows the array literal for the type system.
+ const [firstHash, ...restHashes] = hashes;
+
+ const transport = await getCscTransport();
+
+ const signHashResp = await cscSignHash({
+ baseUrl: transport.serviceBaseUrl,
+ accessToken: serviceToken,
+ credentialID: credential.credentialId,
+ SAD: sad,
+ hash: [firstHash, ...restHashes],
+ signAlgo: credential.signatureAlgorithm,
+ hashAlgo: hashOidForDigest(algo.digestAlgorithm),
+ });
+
+ if (signHashResp.signatures.length !== capturedItems.length) {
+ throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
+ message: `CSC signHash returned ${signHashResp.signatures.length} signatures for ${capturedItems.length} hashes.`,
+ });
+ }
+
+ // Embed pass: per-item, reload the same prep-persisted PDF bytes and sign
+ // with a single-signature FIFO signer. No re-render — bytes are exactly
+ // the ones whose digest the TSP just authorised. Level is B-T: each
+ // recipient's CMS gets a TSA-attested signature timestamp embedded as an
+ // unsigned attribute, binding proven time to the signature itself (the
+ // actual eIDAS AES/QES requirement). The TSA is resolved per-recipient
+ // via the sign-time resolver — TSP if advertised (authorised with this
+ // recipient's service-scope bearer), env otherwise.
+ const timestampAuthority = resolveCscSignTimeTsa(transport, serviceToken);
+
+ const signedItemDataUpdates: SignedItemDataUpdate[] = [];
+
+ for (let i = 0; i < capturedItems.length; i++) {
+ const captured = capturedItems[i];
+ const sigBytes = Buffer.from(signHashResp.signatures[i], 'base64');
+
+ const pdfDoc = await PDF.load(captured.pdfBytes);
+
+ const fifoSigner = new CscFifoSigner({
+ certificate: chain[0],
+ certificateChain: chain.slice(1),
+ algo,
+ signatures: [sigBytes],
+ });
+
+ const signResult = await pdfDoc.sign({
+ signer: fifoSigner,
+ fieldName: captured.anchorName,
+ signingTime: session.signingTime,
+ level: 'B-T',
+ timestampAuthority,
+ digestAlgorithm: algo.digestAlgorithm,
+ });
+
+ const envelopeItem = envelope.envelopeItems.find((item) => item.id === captured.envelopeItemId);
+
+ if (!envelopeItem) {
+ throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
+ message: `Envelope item "${captured.envelopeItemId}" missing during embed pass.`,
+ });
+ }
+
+ const fileName = envelope.title.endsWith('.pdf') ? envelope.title : `${envelope.title || 'envelope'}.pdf`;
+
+ const uploaded = await putPdfFileServerSide(
+ {
+ name: fileName,
+ type: 'application/pdf',
+ arrayBuffer: async () => Promise.resolve(signResult.bytes),
+ },
+ envelopeItem.documentData.initialData ?? undefined,
+ );
+
+ // In-place data update target: the existing envelopeItem.documentDataId
+ // row. `uploaded.documentData` is the freshly-created row whose payload
+ // we'll copy on; that row stays orphan after the copy. Mirrors the
+ // `materializeTspAnchorsForEnvelope` pattern.
+ signedItemDataUpdates.push({
+ envelopeItemDataId: envelopeItem.documentDataId,
+ uploadedType: uploaded.documentData.type,
+ uploadedData: uploaded.documentData.data,
+ });
+ }
+
+ const legacyDocumentId = mapSecondaryIdToDocumentId(envelope.secondaryId);
+
+ // Single tx: per-item in-place data updates + recipient flip + audit log +
+ // session consume. Atomic across items — if any write fails, the recipient
+ // stays unsigned and the session row stays attached. `envelopeItem.
+ // documentDataId` is preserved across the run; only `documentData.{type,
+ // data}` changes. Mirrors `materializeTspAnchorsForEnvelope`.
+ await prisma.$transaction(async (tx) => {
+ for (const { envelopeItemDataId, uploadedType, uploadedData } of signedItemDataUpdates) {
+ await tx.documentData.update({
+ where: { id: envelopeItemDataId },
+ data: { type: uploadedType, data: uploadedData },
+ });
+ }
+
+ await tx.recipient.update({
+ where: { id: recipient.id },
+ data: {
+ signingStatus: SigningStatus.SIGNED,
+ signedAt: new Date(),
+ },
+ });
+
+ const authOptions = extractDocumentAuthMethods({
+ documentAuth: envelope.authOptions,
+ recipientAuth: recipient.authOptions,
+ });
+
+ await tx.documentAuditLog.create({
+ data: createDocumentAuditLogData({
+ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_COMPLETED,
+ envelopeId: envelope.id,
+ user: {
+ name: recipient.name,
+ email: recipient.email,
+ },
+ requestMetadata,
+ data: {
+ recipientEmail: recipient.email,
+ recipientName: recipient.name,
+ recipientId: recipient.id,
+ recipientRole: recipient.role,
+ actionAuth: authOptions.derivedRecipientActionAuth,
+ },
+ }),
+ });
+
+ await tx.documentAuditLog.create({
+ data: createDocumentAuditLogData({
+ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGNED,
+ envelopeId: envelope.id,
+ user: { name: recipient.name, email: recipient.email },
+ requestMetadata,
+ data: {
+ recipientEmail: recipient.email,
+ recipientName: recipient.name,
+ recipientId: recipient.id,
+ recipientRole: recipient.role,
+ providerId: credential.providerId,
+ credentialId: credential.credentialId,
+ sessionId,
+ numItemsSigned: signedItemDataUpdates.length,
+ signatureAlgorithm: credential.signatureAlgorithm,
+ digestAlgorithm: credential.digestAlgorithm,
+ },
+ }),
+ });
+
+ await consumeCscSession(sessionId, tx);
+ });
+
+ // Post-tx side effects (webhooks, emails, next-signer advancement, seal
+ // job dispatch). Inlined rather than shared with the SES completion path —
+ // the in-tx shape diverges enough (TSP swaps documentDataIds + consumes
+ // the CSC session; SES doesn't) that a shared helper would obscure both.
+ const envelopeWithRelations = await prisma.envelope.findUniqueOrThrow({
+ where: { id: envelope.id },
+ include: { documentMeta: true, recipients: true },
+ });
+
+ await triggerWebhook({
+ event: WebhookTriggerEvents.DOCUMENT_RECIPIENT_COMPLETED,
+ data: ZWebhookDocumentSchema.parse(mapEnvelopeToWebhookDocumentPayload(envelopeWithRelations)),
+ userId: envelope.userId,
+ teamId: envelope.teamId,
+ });
+
+ await jobs.triggerJob({
+ name: 'send.recipient.signed.email',
+ payload: {
+ documentId: legacyDocumentId,
+ recipientId: recipient.id,
+ },
+ });
+
+ const pendingRecipients = await prisma.recipient.findMany({
+ select: {
+ id: true,
+ signingOrder: true,
+ role: true,
+ },
+ where: {
+ envelopeId: envelope.id,
+ signingStatus: { not: SigningStatus.SIGNED },
+ role: { not: RecipientRole.CC },
+ },
+ orderBy: [{ signingOrder: { sort: 'asc', nulls: 'last' } }, { id: 'asc' }],
+ });
+
+ if (pendingRecipients.length > 0) {
+ await sendPendingEmail({
+ id: { type: 'envelopeId', id: envelope.id },
+ recipientId: recipient.id,
+ });
+
+ // TSP envelopes are forced SEQUENTIAL at send-time; this branch always
+ // fires when pending recipients exist. No `nextSigner` dictation path
+ // — `prepareCscRecipientSigning` doesn't accept one.
+ const [nextRecipient] = pendingRecipients;
+
+ await prisma.recipient.update({
+ where: { id: nextRecipient.id },
+ data: {
+ sendStatus: SendStatus.SENT,
+ sentAt: new Date(),
+ },
+ });
+
+ await jobs.triggerJob({
+ name: 'send.signing.requested.email',
+ payload: {
+ userId: envelope.userId,
+ documentId: legacyDocumentId,
+ recipientId: nextRecipient.id,
+ requestMetadata,
+ },
+ });
+ }
+
+ const haveAllRecipientsSigned = await prisma.envelope.findFirst({
+ where: {
+ id: envelope.id,
+ recipients: {
+ every: {
+ OR: [{ signingStatus: SigningStatus.SIGNED }, { role: RecipientRole.CC }],
+ },
+ },
+ },
+ });
+
+ if (haveAllRecipientsSigned) {
+ await jobs.triggerJob({
+ name: 'internal.seal-document',
+ payload: {
+ documentId: legacyDocumentId,
+ requestMetadata,
+ },
+ });
+ }
+
+ const updatedDocument = await prisma.envelope.findFirstOrThrow({
+ where: {
+ id: envelope.id,
+ type: EnvelopeType.DOCUMENT,
+ },
+ include: {
+ documentMeta: true,
+ recipients: true,
+ },
+ });
+
+ await triggerWebhook({
+ event: WebhookTriggerEvents.DOCUMENT_SIGNED,
+ data: ZWebhookDocumentSchema.parse(mapEnvelopeToWebhookDocumentPayload(updatedDocument)),
+ userId: updatedDocument.userId,
+ teamId: updatedDocument.teamId ?? undefined,
+ });
+
+ return { outcome: 'signed' };
+};
diff --git a/packages/ee/server-only/signing/csc/finalize-tsp-completion.ts b/packages/ee/server-only/signing/csc/finalize-tsp-completion.ts
new file mode 100644
index 000000000..1f3e1e7f2
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/finalize-tsp-completion.ts
@@ -0,0 +1,130 @@
+import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import type { CreateDocumentAuditLogDataResponse } from '@documenso/lib/utils/document-audit-logs';
+import { prisma } from '@documenso/prisma';
+import { HttpTimestampAuthority, PDF, type TimestampAuthority } from '@libpdf/core';
+import type { DocumentData, DocumentMeta, Envelope, EnvelopeItem, Recipient, User } from '@prisma/client';
+import { DocumentStatus } from '@prisma/client';
+
+import { resolveCscSealTimeTsa } from './tsa-resolver';
+
+/**
+ * TSP envelope finalisation step run from the `seal-document` job.
+ *
+ * Replaces the SES "decorate + p12 sign" pass: recipient bytes are already
+ * PAdES-signed by each recipient's CSC TSP, so the seal step is reduced to
+ * a per-item PAdES B-LTA upgrade — libpdf's `pdf.addArchivalData()` runs
+ * the full archive sequence (DSS for every existing signature + archival
+ * `/DocTimeStamp` + DSS for the timestamp's own chain), and the resulting
+ * bytes are copied in-place onto each `envelopeItem.documentData` row.
+ * `envelopeItem.documentDataId` stays stable across the whole envelope
+ * lifecycle (materialise → per-recipient signs → finalise) — mirrors the
+ * pattern used by `materializeTspAnchorsForEnvelope` and `executeTspSign`.
+ *
+ * Certificate / audit-log sidecar PDFs are intentionally NOT merged into
+ * the signed bytes here — they're rendered on-demand at download time so
+ * the signed PDF stays byte-identical to what each recipient's SAD
+ * authorised. Rejection and resealing are unsupported in V1 and rejected
+ * by the caller before this runs.
+ */
+
+export type FinalizeTspEnvelopeCompletionOptions = {
+ envelope: Envelope & {
+ documentMeta: DocumentMeta | null;
+ recipients: Recipient[];
+ envelopeItems: Array<EnvelopeItem & { documentData: DocumentData }>;
+ user: Pick<User, 'name' | 'email'>;
+ };
+ envelopeCompletedAuditLog: CreateDocumentAuditLogDataResponse;
+ requestMetadata?: RequestMetadata;
+};
+
+type ArchivedItem = {
+ /** Existing `envelopeItem.documentDataId` — target of the in-place update. */
+ envelopeItemDataId: string;
+ uploadedType: DocumentData['type'];
+ uploadedData: string;
+};
+
+export const finalizeTspEnvelopeCompletion = async (opts: FinalizeTspEnvelopeCompletionOptions): Promise<void> => {
+ const { envelope, envelopeCompletedAuditLog } = opts;
+
+ // Resolve the TSA up-front — fail fast if the instance is mis-configured
+ // before we start round-tripping PDF bytes through storage.
+ const tsa = resolveCscSealTimeTsa();
+ const timestampAuthority = buildLibpdfTsa(tsa);
+
+ const archivedItems: ArchivedItem[] = [];
+
+ for (const envelopeItem of envelope.envelopeItems) {
+ const pdfBytes = await getFileServerSide(envelopeItem.documentData);
+ const pdfDoc = await PDF.load(pdfBytes);
+
+ // PAdES B-LTA in one call. Internally:
+ // 1. Gather LTV (certs/OCSP/CRL) for every existing signed field and
+ // write a single DSS incremental update.
+ // 2. Add an archival `/DocTimeStamp` over the result.
+ // 3. Gather LTV for the new timestamp's own certificate chain.
+ // All three are append-only incremental updates — every prior recipient
+ // signature's `/ByteRange` stays valid.
+ const archived = await pdfDoc.addArchivalData({ timestampAuthority });
+
+ const { documentData: uploaded } = await putPdfFileServerSide(
+ {
+ name: envelopeItem.title.endsWith('.pdf') ? envelopeItem.title : `${envelopeItem.title}.pdf`,
+ type: 'application/pdf',
+ arrayBuffer: async () => Promise.resolve(archived.bytes),
+ },
+ envelopeItem.documentData.initialData,
+ );
+
+ archivedItems.push({
+ envelopeItemDataId: envelopeItem.documentData.id,
+ uploadedType: uploaded.type,
+ uploadedData: uploaded.data,
+ });
+ }
+
+ // Single tx: per-item in-place data updates + envelope status flip +
+ // completion audit log. `envelopeItem.documentDataId` is preserved; the
+ // freshly-uploaded `DocumentData` rows orbit as orphans.
+ await prisma.$transaction(async (tx) => {
+ for (const { envelopeItemDataId, uploadedType, uploadedData } of archivedItems) {
+ await tx.documentData.update({
+ where: { id: envelopeItemDataId },
+ data: { type: uploadedType, data: uploadedData },
+ });
+ }
+
+ await tx.envelope.update({
+ where: { id: envelope.id },
+ data: {
+ status: DocumentStatus.COMPLETED,
+ completedAt: new Date(),
+ },
+ });
+
+ await tx.documentAuditLog.create({
+ data: envelopeCompletedAuditLog,
+ });
+ });
+};
+
+/**
+ * Wrap a resolved seal-time TSA config into a libpdf `TimestampAuthority`.
+ *
+ * Env only at seal time — the archival `/DocTimeStamp` is the operator's
+ * long-term trust anchor and SHOULD point at a dedicated qualified archival
+ * TSA (e.g. DigiCert) that's independent of the per-recipient TSP. We
+ * deliberately don't fall back to the TSP here: doing so would couple the
+ * archive's longevity to a TSP that may revoke or rotate without notice,
+ * and would require keeping a live service-scope bearer around at the
+ * seal-document job which has no recipient context anyway.
+ *
+ * First URL only — multi-URL fallback can layer on later via a composite
+ * wrapper if operators need it.
+ */
+const buildLibpdfTsa = (tsa: { urls: string[] }): TimestampAuthority => {
+ return new HttpTimestampAuthority(tsa.urls[0]);
+};
diff --git a/packages/ee/server-only/signing/csc/hono/context.ts b/packages/ee/server-only/signing/csc/hono/context.ts
new file mode 100644
index 000000000..f0198f22d
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/hono/context.ts
@@ -0,0 +1,16 @@
+import type { logger } from '@documenso/lib/utils/logger';
+
+/**
+ * CSC subapp Hono context. Mirrors the subset of `apps/remix/server/router.ts`
+ * `HonoEnv` that CSC handlers actually read. Duplicated (rather than imported
+ * from `apps/remix/`) to keep the `packages/ee` → `apps/remix` dep direction
+ * unidirectional.
+ *
+ * Runtime contract: the remix host's middleware sets `logger` on every request
+ * before the CSC subapp runs; the CSC subapp does not set it itself.
+ */
+export type HonoCscEnv = {
+ Variables: {
+ logger: typeof logger;
+ };
+};
diff --git a/packages/ee/server-only/signing/csc/hono/index.ts b/packages/ee/server-only/signing/csc/hono/index.ts
new file mode 100644
index 000000000..49939e0eb
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/hono/index.ts
@@ -0,0 +1,63 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+
+import type { HonoCscEnv } from './context';
+import { cscOAuthAuthorizeRoute } from './oauth-authorize';
+import { cscOAuthCallbackRoute } from './oauth-callback';
+
+/**
+ * `@documenso/ee` CSC subapp. Mount under `/api/csc` in the remix host (see
+ * `apps/remix/server/router.ts`). All CSC endpoints — OAuth authorize +
+ * callback — are composed here so the host only has to wire one route.
+ *
+ * Routes throw `AppError` freely; the `.onError` handler below normalises
+ * them into REST responses (mirrors `@documenso/auth/server`'s pattern).
+ */
+export const csc = new Hono<HonoCscEnv>()
+ .route('/oauth/authorize', cscOAuthAuthorizeRoute)
+ .route('/oauth/callback', cscOAuthCallbackRoute);
+
+csc.onError((err, c) => {
+ const logger = c.get('logger');
+
+ if (err instanceof HTTPException) {
+ return c.json(
+ {
+ code: AppErrorCode.UNKNOWN_ERROR,
+ message: err.message,
+ statusCode: err.status,
+ },
+ err.status,
+ );
+ }
+
+ if (err instanceof AppError) {
+ const { status, body } = AppError.toRestAPIError(err);
+
+ logger.error({
+ event: 'csc.error',
+ code: err.code,
+ message: err.message,
+ });
+
+ return c.json(body, status as ContentfulStatusCode);
+ }
+
+ logger.error({
+ event: 'csc.unknown_error',
+ error: err,
+ });
+
+ return c.json(
+ {
+ code: AppErrorCode.UNKNOWN_ERROR,
+ message: 'Internal Server Error',
+ statusCode: 500,
+ },
+ 500,
+ );
+});
+
+export type CscAppType = typeof csc;
diff --git a/packages/ee/server-only/signing/csc/hono/oauth-authorize.ts b/packages/ee/server-only/signing/csc/hono/oauth-authorize.ts
new file mode 100644
index 000000000..a83791864
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/hono/oauth-authorize.ts
@@ -0,0 +1,154 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { getRecipientByToken } from '@documenso/lib/server-only/recipient/get-recipient-by-token';
+import { prisma } from '@documenso/prisma';
+import { sValidator } from '@hono/standard-validator';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import {
+ buildCscCredentialScopeAuthorizeUrl,
+ buildCscServiceScopeAuthorizeUrl,
+ generateCodeVerifier,
+ generateState,
+} from '../client/oauth';
+import { setCscOAuthFlowCookie } from '../cookies/oauth-flow-cookie';
+import { loadCscCredential } from '../credential';
+import { loadCscSession } from '../sign-session';
+import { getCscTransport } from '../transport';
+import type { HonoCscEnv } from './context';
+
+/**
+ * `GET /api/csc/oauth/authorize` — initiates the CSC OAuth round-trip and
+ * 302-redirects to the TSP's authorize URL with a signed `csc_oauth_flow`
+ * cookie carrying the state, PKCE verifier, and recipient context the
+ * callback needs to resume the flow.
+ *
+ * Branches on `?scope=service|credential`:
+ * - `service`: authorised by recipient token; precedes credentials/list.
+ * - `credential`: authorised by an active `CscSession`; binds the issued SAD
+ * to the per-item hashes captured at prep.
+ *
+ * Errors bubble to the parent app's `.onError` handler (see `./index.ts`).
+ */
+
+const ZAuthorizeQuerySchema = z.discriminatedUnion('scope', [
+ z.object({
+ scope: z.literal('service'),
+ token: z.string().min(1),
+ }),
+ z.object({
+ scope: z.literal('credential'),
+ session: z.string().min(1),
+ }),
+]);
+
+export const cscOAuthAuthorizeRoute = new Hono<HonoCscEnv>().get(
+ '/',
+ sValidator('query', ZAuthorizeQuerySchema),
+ async (c) => {
+ const logger = c.get('logger');
+
+ const query = c.req.valid('query');
+
+ const transport = await getCscTransport();
+
+ if (query.scope === 'service') {
+ const recipient = await getRecipientByToken({ token: query.token }).catch(() => null);
+
+ if (!recipient) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'Recipient not found for the provided token.',
+ });
+ }
+
+ logger.info({
+ event: 'csc.oauth.authorize.start',
+ scope: 'service',
+ recipientId: recipient.id,
+ });
+
+ const state = generateState();
+ const codeVerifier = generateCodeVerifier();
+
+ const authorizeUrl = buildCscServiceScopeAuthorizeUrl({
+ client: transport.oauthClient,
+ oauthBaseUrl: transport.oauthBaseUrl,
+ state,
+ codeVerifier,
+ });
+
+ await setCscOAuthFlowCookie({
+ c,
+ payload: {
+ scope: 'service',
+ state,
+ codeVerifier,
+ recipientToken: query.token,
+ },
+ });
+
+ return c.redirect(authorizeUrl.toString(), 302);
+ }
+
+ const session = await loadCscSession(query.session);
+
+ if (!session) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'CSC session not found or already consumed.',
+ });
+ }
+
+ const credential = await loadCscCredential(session.recipientId);
+
+ if (!credential) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'CSC credential missing — service-scope OAuth must complete first.',
+ });
+ }
+
+ const recipient = await prisma.recipient.findUnique({
+ where: { id: session.recipientId },
+ select: { token: true },
+ });
+
+ if (!recipient) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'Recipient not found for the CSC session.',
+ });
+ }
+
+ logger.info({
+ event: 'csc.oauth.authorize.start',
+ scope: 'credential',
+ recipientId: session.recipientId,
+ sessionId: session.id,
+ numSignatures: session.items.length,
+ });
+
+ const state = generateState();
+ const codeVerifier = generateCodeVerifier();
+
+ const authorizeUrl = buildCscCredentialScopeAuthorizeUrl({
+ client: transport.oauthClient,
+ oauthBaseUrl: transport.oauthBaseUrl,
+ state,
+ codeVerifier,
+ credentialId: credential.credentialId,
+ numSignatures: session.items.length,
+ hashes: session.items.map((item) => item.hashB64),
+ });
+
+ await setCscOAuthFlowCookie({
+ c,
+ payload: {
+ scope: 'credential',
+ state,
+ codeVerifier,
+ recipientToken: recipient.token,
+ sessionId: session.id,
+ },
+ });
+
+ return c.redirect(authorizeUrl.toString(), 302);
+ },
+);
diff --git a/packages/ee/server-only/signing/csc/hono/oauth-callback.ts b/packages/ee/server-only/signing/csc/hono/oauth-callback.ts
new file mode 100644
index 000000000..d2549d0fb
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/hono/oauth-callback.ts
@@ -0,0 +1,303 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { getRecipientByToken } from '@documenso/lib/server-only/recipient/get-recipient-by-token';
+import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
+import { extractRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
+import { formatSigningLink } from '@documenso/lib/utils/recipients';
+import { prisma } from '@documenso/prisma';
+import { sValidator } from '@hono/standard-validator';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import { resolveCscAlgorithmPolicy } from '../algorithm-resolver';
+import { encodeCscCertChain } from '../cert-chain';
+import { encryptCscToken } from '../ciphers';
+import { cscCredentialsInfo, cscCredentialsList } from '../client/credentials';
+import { exchangeCscAuthorizationCode } from '../client/oauth';
+import { setCscBlockingErrorCookie } from '../cookies/blocking-error-cookie';
+import { clearCscOAuthFlowCookie, getCscOAuthFlowCookie } from '../cookies/oauth-flow-cookie';
+import { setCscSadSessionCookie } from '../cookies/sad-session-cookie';
+import { setCscServiceSessionCookie } from '../cookies/service-session-cookie';
+import { loadCscCredential, upsertCscCredential } from '../credential';
+import { updateCscSessionWithSad } from '../sign-session';
+import { getCscTransport } from '../transport';
+import type { HonoCscEnv } from './context';
+
+/**
+ * `GET /api/csc/oauth/callback` — landing point for the recipient's return
+ * from the TSP after the round-trip initiated by `oauth-authorize`. Reads
+ * the `csc_oauth_flow` cookie, verifies CSRF, exchanges the code, and
+ * branches on the cookie's `scope`:
+ *
+ * - `service`: pulls `credentials/list` + `credentials/info`, validates the
+ * cert + algorithm policy, persists the `CscCredential` row + service
+ * token, sets the `csc_service_session` cookie, and redirects to
+ * `/sign/{token}`. Blocking validation errors (empty list, bad cert,
+ * refused algorithm) round-trip via the `csc_blocking_error` cookie so the
+ * signing-page loader can render a stable error UI.
+ * - `credential`: exchanges code → SAD, stamps it onto the existing
+ * `CscSession`, sets the `csc_sad_session` cookie, and redirects to
+ * `/sign/{token}`. Credential-scope failures bubble to `.onError` — the
+ * recipient simply re-clicks Sign.
+ *
+ * Non-blocking errors bubble to the parent app's `.onError` (see
+ * `./index.ts`) — mirrors `oauth-authorize.ts`.
+ */
+
+const ZCallbackQuerySchema = z.object({
+ state: z.string().min(1),
+ code: z.string().min(1).optional(),
+ error: z.string().min(1).optional(),
+ error_description: z.string().optional(),
+});
+
+const BLOCKING_SERVICE_ERROR_CODES = new Set<string>([
+ AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY,
+ AppErrorCode.CSC_CERT_INVALID,
+ AppErrorCode.CSC_ALGORITHM_REFUSED,
+]);
+
+const isBlockingServiceError = (code: string): boolean => BLOCKING_SERVICE_ERROR_CODES.has(code);
+
+export const cscOAuthCallbackRoute = new Hono<HonoCscEnv>().get(
+ '/',
+ sValidator('query', ZCallbackQuerySchema),
+ async (c) => {
+ const logger = c.get('logger');
+
+ const query = c.req.valid('query');
+
+ const cookie = await getCscOAuthFlowCookie(c);
+
+ if (!cookie) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC OAuth flow cookie missing or expired.',
+ });
+ }
+
+ if (query.state !== cookie.state) {
+ throw new AppError(AppErrorCode.UNAUTHORIZED, {
+ message: 'CSC OAuth callback state mismatch — possible CSRF.',
+ });
+ }
+
+ // The single-round-trip carrier is spent regardless of subsequent
+ // outcome; clear it now so a retry restarts from `/api/csc/oauth/authorize`.
+ clearCscOAuthFlowCookie(c);
+
+ if (query.error) {
+ throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
+ message: `CSC TSP returned OAuth error: ${query.error}${query.error_description ? ' — ' + query.error_description : ''}`,
+ });
+ }
+
+ if (!query.code) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC OAuth callback missing code parameter.',
+ });
+ }
+
+ const transport = await getCscTransport();
+
+ const recipient = await getRecipientByToken({ token: cookie.recipientToken }).catch(() => null);
+
+ if (!recipient) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'Recipient not found for CSC OAuth flow cookie.',
+ });
+ }
+
+ if (cookie.scope === 'service') {
+ const tokens = await exchangeCscAuthorizationCode({
+ client: transport.oauthClient,
+ oauthBaseUrl: transport.oauthBaseUrl,
+ code: query.code,
+ codeVerifier: cookie.codeVerifier,
+ });
+
+ try {
+ const listResp = await cscCredentialsList({
+ baseUrl: transport.serviceBaseUrl,
+ accessToken: tokens.accessToken(),
+ });
+
+ // V1 picks the first credential per spec section "Out of scope for
+ // V1": multi-credential selection UI lands in a later iteration.
+ const credentialId = listResp.credentialIDs[0];
+
+ const infoResp = await cscCredentialsInfo({
+ baseUrl: transport.serviceBaseUrl,
+ accessToken: tokens.accessToken(),
+ credentialID: credentialId,
+ certificates: 'chain',
+ certInfo: true,
+ });
+
+ const policy = resolveCscAlgorithmPolicy(infoResp);
+
+ if (!infoResp.cert.certificates || infoResp.cert.certificates.length === 0) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: 'CSC credential info response omitted required certificate chain.',
+ });
+ }
+
+ const certCache = encodeCscCertChain(infoResp.cert.certificates);
+ const serviceTokenCiphertext = encryptCscToken(tokens.accessToken());
+ const serviceTokenExpiresAt = tokens.accessTokenExpiresAt();
+
+ await upsertCscCredential({
+ recipientId: recipient.id,
+ providerId: transport.serviceBaseUrl,
+ credentialId,
+ certCache,
+ signatureAlgorithm: policy.signAlgoOid,
+ keyType: policy.keyType,
+ digestAlgorithm: policy.digestAlgorithm,
+ keyLenBits: policy.keyLenBits,
+ serviceTokenCiphertext,
+ serviceTokenExpiresAt,
+ });
+
+ await setCscServiceSessionCookie({
+ c,
+ recipientToken: cookie.recipientToken,
+ ttlSeconds: tokens.accessTokenExpiresInSeconds(),
+ });
+
+ await prisma.documentAuditLog.create({
+ data: createDocumentAuditLogData({
+ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATED,
+ envelopeId: recipient.envelopeId,
+ user: { name: recipient.name, email: recipient.email },
+ requestMetadata: extractRequestMetadata(c.req.raw),
+ data: {
+ recipientEmail: recipient.email,
+ recipientName: recipient.name,
+ recipientId: recipient.id,
+ recipientRole: recipient.role,
+ providerId: transport.serviceBaseUrl,
+ credentialId,
+ signatureAlgorithm: policy.signAlgoOid,
+ digestAlgorithm: policy.digestAlgorithm,
+ },
+ }),
+ });
+
+ logger.info({
+ event: 'csc.oauth.callback.service.complete',
+ recipientId: recipient.id,
+ });
+
+ return c.redirect(formatSigningLink(cookie.recipientToken), 302);
+ } catch (err) {
+ if (err instanceof AppError && isBlockingServiceError(err.code)) {
+ await setCscBlockingErrorCookie({
+ c,
+ payload: { code: err.code, recipientToken: cookie.recipientToken },
+ });
+
+ await prisma.documentAuditLog.create({
+ data: createDocumentAuditLogData({
+ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATION_FAILED,
+ envelopeId: recipient.envelopeId,
+ user: { name: recipient.name, email: recipient.email },
+ requestMetadata: extractRequestMetadata(c.req.raw),
+ data: {
+ recipientEmail: recipient.email,
+ recipientName: recipient.name,
+ recipientId: recipient.id,
+ recipientRole: recipient.role,
+ providerId: transport.serviceBaseUrl,
+ reason: err.code,
+ },
+ }),
+ });
+
+ logger.warn({
+ event: 'csc.oauth.callback.service.blocking',
+ recipientId: recipient.id,
+ code: err.code,
+ });
+
+ return c.redirect(formatSigningLink(cookie.recipientToken), 302);
+ }
+
+ throw err;
+ }
+ }
+
+ if (!cookie.sessionId) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC credential-scope OAuth callback missing sessionId in cookie.',
+ });
+ }
+
+ const tokens = await exchangeCscAuthorizationCode({
+ client: transport.oauthClient,
+ oauthBaseUrl: transport.oauthBaseUrl,
+ code: query.code,
+ codeVerifier: cookie.codeVerifier,
+ });
+
+ // CSC §8.3.3 says credential-scope returns `token_type === 'SAD'`. We
+ // don't hard-fail on a divergent label — the binding is by scope + hash,
+ // not by `token_type` — but we log so operator metrics can spot loose
+ // TSPs.
+ if (tokens.tokenType() !== 'SAD') {
+ logger.warn({
+ event: 'csc.oauth.callback.credential.unexpected_token_type',
+ actual: tokens.tokenType(),
+ });
+ }
+
+ const sadCiphertext = encryptCscToken(tokens.accessToken());
+ const sadExpiresAt = tokens.accessTokenExpiresAt();
+
+ await updateCscSessionWithSad({
+ sessionId: cookie.sessionId,
+ encryptedSad: sadCiphertext,
+ sadExpiresAt,
+ });
+
+ await setCscSadSessionCookie({
+ c,
+ sessionId: cookie.sessionId,
+ expiresAt: sadExpiresAt,
+ });
+
+ const credential = await loadCscCredential(recipient.id);
+
+ if (!credential) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'CSC credential missing at credential-scope callback.',
+ });
+ }
+
+ await prisma.documentAuditLog.create({
+ data: createDocumentAuditLogData({
+ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHORIZED,
+ envelopeId: recipient.envelopeId,
+ user: { name: recipient.name, email: recipient.email },
+ requestMetadata: extractRequestMetadata(c.req.raw),
+ data: {
+ recipientEmail: recipient.email,
+ recipientName: recipient.name,
+ recipientId: recipient.id,
+ recipientRole: recipient.role,
+ providerId: credential.providerId,
+ credentialId: credential.credentialId,
+ sessionId: cookie.sessionId,
+ sadExpiresAt,
+ },
+ }),
+ });
+
+ logger.info({
+ event: 'csc.oauth.callback.credential.complete',
+ recipientId: recipient.id,
+ sessionId: cookie.sessionId,
+ });
+
+ return c.redirect(formatSigningLink(cookie.recipientToken), 302);
+ },
+);
diff --git a/packages/ee/server-only/signing/csc/materialize-anchors.ts b/packages/ee/server-only/signing/csc/materialize-anchors.ts
new file mode 100644
index 000000000..303842ba7
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/materialize-anchors.ts
@@ -0,0 +1,230 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { isTspEnvelope } from '@documenso/lib/types/signature-level';
+import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { prisma } from '@documenso/prisma';
+import { PDF } from '@libpdf/core';
+
+import { buildTspAnchorName, buildTspStampName } from './pdf-names';
+
+export type MaterializeTspAnchorsForEnvelopeOptions = {
+ envelopeId: string;
+};
+
+/**
+ * Pre-allocate per-recipient AcroForm signature anchors and per-page `/Stamp`
+ * overlay annotations on every envelope item of a TSP (AES/QES) envelope.
+ *
+ * Mutates the existing `DocumentData` row in place — the `envelopeItem.
+ * documentDataId` pointer is preserved across materialisation. Materialise
+ * is distribution housekeeping (pre-allocate fixed anchor slots before any
+ * recipient signs), not a content version bump, so a pointer swap +
+ * audit-log entry would mis-attribute the change. The new uploaded row
+ * created by `putPdfFileServerSide` is kept as an orphan rather than
+ * deleted — it preserves the standard upload mechanics (S3 PUT or BYTES_64
+ * encode) without a separate "copy then drop" dance.
+ *
+ * Idempotent: re-runs are no-ops when every expected anchor/stamp is
+ * already present. No-op for SES envelopes.
+ */
+export const materializeTspAnchorsForEnvelope = async ({
+ envelopeId,
+}: MaterializeTspAnchorsForEnvelopeOptions): Promise<void> => {
+ const envelope = await prisma.envelope.findUnique({
+ where: {
+ id: envelopeId,
+ },
+ include: {
+ recipients: true,
+ envelopeItems: {
+ include: {
+ documentData: true,
+ },
+ },
+ fields: {
+ select: {
+ recipientId: true,
+ envelopeItemId: true,
+ page: true,
+ },
+ },
+ },
+ });
+
+ if (!envelope) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `Envelope ${envelopeId} not found`,
+ });
+ }
+
+ if (!isTspEnvelope(envelope)) {
+ return;
+ }
+
+ if (envelope.recipients.length === 0) {
+ return;
+ }
+
+ for (const envelopeItem of envelope.envelopeItems) {
+ const expectedAnchorNames = envelope.recipients.map((recipient) =>
+ buildTspAnchorName(recipient.id, envelopeItem.id),
+ );
+
+ const expectedStampNames: string[] = [];
+
+ for (const recipient of envelope.recipients) {
+ const pagesWithFields = new Set<number>();
+
+ for (const field of envelope.fields) {
+ if (field.recipientId === recipient.id && field.envelopeItemId === envelopeItem.id) {
+ pagesWithFields.add(field.page);
+ }
+ }
+
+ for (const page of pagesWithFields) {
+ expectedStampNames.push(buildTspStampName(recipient.id, envelopeItem.id, page));
+ }
+ }
+
+ const bytes = await getFileServerSide(envelopeItem.documentData);
+ const pdfDoc = await PDF.load(bytes);
+
+ if (isAlreadyMaterialised(pdfDoc, expectedAnchorNames, expectedStampNames)) {
+ continue;
+ }
+
+ // Bake operator AcroForm, annotations and OCG layers into static graphics
+ // so the materialised PDF is a deterministic surface. `skipSignatures`
+ // preserves any operator-placed signature widgets and (on re-materialise)
+ // the TSP anchors created previously.
+ pdfDoc.flattenAll({
+ form: {
+ skipSignatures: true,
+ },
+ });
+
+ const form = pdfDoc.getOrCreateForm();
+
+ if (pdfDoc.getPageCount() === 0) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: `Envelope item ${envelopeItem.id} PDF has no pages`,
+ });
+ }
+
+ // Anchors are AcroForm signature fields with no pre-attached widget.
+ // libpdf forbids `drawField` for signature fields — at sign time
+ // `pdf.sign({ fieldName })` promotes the existing field dict in place
+ // to a merged field/widget (Type=Annot, Subtype=Widget, P=page0,
+ // Rect=[0,0,0,0]) without modifying the page object. That preserves the
+ // per-recipient `/ByteRange` invariant across sequential signatures.
+ for (const anchorName of expectedAnchorNames) {
+ if (form.getSignatureField(anchorName)) {
+ continue;
+ }
+
+ form.createSignatureField(anchorName);
+ }
+
+ for (const recipient of envelope.recipients) {
+ const pagesWithFields = new Set<number>();
+
+ for (const field of envelope.fields) {
+ if (field.recipientId === recipient.id && field.envelopeItemId === envelopeItem.id) {
+ pagesWithFields.add(field.page);
+ }
+ }
+
+ for (const pageNumber of pagesWithFields) {
+ const stampName = buildTspStampName(recipient.id, envelopeItem.id, pageNumber);
+ const page = pdfDoc.getPage(pageNumber - 1);
+
+ if (!page) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: `Envelope item ${envelopeItem.id} missing page ${pageNumber} referenced by field`,
+ });
+ }
+
+ const existing = page.getStampAnnotations().some((stamp) => stamp.stampName === stampName);
+
+ if (existing) {
+ continue;
+ }
+
+ page.addStampAnnotation({
+ name: stampName,
+ rect: {
+ x: 0,
+ y: 0,
+ width: page.width,
+ height: page.height,
+ },
+ });
+ }
+ }
+
+ const newBytes = await pdfDoc.save({ useXRefStream: true });
+
+ // CRITICAL: persist via `putPdfFileServerSide` (raw). The normalised path
+ // would call `form.flatten()` without `skipSignatures` and wipe anchors.
+ const fileName = envelope.title.endsWith('.pdf') ? envelope.title : `${envelope.title || 'envelope'}.pdf`;
+
+ const uploaded = await putPdfFileServerSide(
+ {
+ name: fileName,
+ type: 'application/pdf',
+ arrayBuffer: async () => Promise.resolve(newBytes),
+ },
+ envelopeItem.documentData.initialData ?? undefined,
+ );
+
+ // Copy the persisted bytes reference (S3 key or BYTES_64 payload) onto the
+ // existing DocumentData row in place. `envelopeItem.documentDataId` stays
+ // put — see file-level docblock for the rationale.
+ await prisma.documentData.update({
+ where: { id: envelopeItem.documentDataId },
+ data: {
+ type: uploaded.documentData.type,
+ data: uploaded.documentData.data,
+ },
+ });
+ }
+};
+
+/**
+ * Whole-item idempotency probe: returns true only when every expected anchor
+ * and stamp name is already present on the loaded PDF. Partial state is
+ * treated as not-materialised — the whole item is rebuilt.
+ */
+const isAlreadyMaterialised = (pdfDoc: PDF, expectedAnchorNames: string[], expectedStampNames: string[]): boolean => {
+ const form = pdfDoc.getForm();
+
+ if (!form) {
+ return expectedAnchorNames.length === 0 && expectedStampNames.length === 0;
+ }
+
+ for (const anchorName of expectedAnchorNames) {
+ if (!form.getSignatureField(anchorName)) {
+ return false;
+ }
+ }
+
+ if (expectedStampNames.length === 0) {
+ return true;
+ }
+
+ const presentStampNames = new Set<string>();
+
+ for (let i = 0; i < pdfDoc.getPageCount(); i++) {
+ const page = pdfDoc.getPage(i);
+
+ if (!page) {
+ continue;
+ }
+
+ for (const stamp of page.getStampAnnotations()) {
+ presentStampNames.add(stamp.stampName);
+ }
+ }
+
+ return expectedStampNames.every((name) => presentStampNames.has(name));
+};
diff --git a/packages/ee/server-only/signing/csc/pdf-names.ts b/packages/ee/server-only/signing/csc/pdf-names.ts
new file mode 100644
index 000000000..b7561c79a
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/pdf-names.ts
@@ -0,0 +1,23 @@
+import { bytesToHex, utf8ToBytes } from '@noble/ciphers/utils';
+import { sha1 } from '@noble/hashes/legacy';
+
+/**
+ * Deterministic PDF object names for CSC TSP signing.
+ *
+ * Materialise-time and sign-time both derive these from the same
+ * `(recipient, item [, page])` tuple — they MUST agree byte-for-byte.
+ *
+ * Output is opaque: SHA-1(label) hex-encoded uppercase (40 chars). The PDF
+ * persists only the hex serial so recipient / envelope-item IDs never leak
+ * into the document.
+ */
+
+const hashToOpaqueSerial = (label: string): string => bytesToHex(sha1(utf8ToBytes(label))).toUpperCase();
+
+/** AcroForm signature-field name (TSP anchor) for a recipient + envelope item. */
+export const buildTspAnchorName = (recipientId: number, envelopeItemId: string): string =>
+ hashToOpaqueSerial(`recipient:${recipientId}|item:${envelopeItemId}`);
+
+/** `/Stamp` annotation name for a recipient + envelope item on a specific page. */
+export const buildTspStampName = (recipientId: number, envelopeItemId: string, pageNumber: number): string =>
+ hashToOpaqueSerial(`recipient:${recipientId}|item:${envelopeItemId}|page:${pageNumber}`);
diff --git a/packages/ee/server-only/signing/csc/prepare-recipient-signing.ts b/packages/ee/server-only/signing/csc/prepare-recipient-signing.ts
new file mode 100644
index 000000000..38f671c42
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/prepare-recipient-signing.ts
@@ -0,0 +1,248 @@
+import { NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { TCscSessionItems } from '@documenso/lib/types/csc-session';
+import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
+import { isTspEnvelope } from '@documenso/lib/types/signature-level';
+import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
+import { prisma } from '@documenso/prisma';
+import type { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
+import { PDF } from '@libpdf/core';
+
+import { type CscDigest, policyToLibpdfSignerAlgo } from './algorithm-resolver';
+import { decodeCscCertChain } from './cert-chain';
+import { loadCscCredential } from './credential';
+import { buildTspAnchorName, buildTspStampName } from './pdf-names';
+import { renderRecipientOverlay } from './render-overlay';
+import { upsertCscSession } from './sign-session';
+import { CscCaptureSigner } from './signers/capture-signer';
+
+/**
+ * CSC TSP prep-phase orchestrator.
+ *
+ * Per envelope item:
+ *
+ * 1. Render the recipient's overlay into the materialised PDF in memory.
+ * 2. Persist the rendered bytes as a fresh `DocumentData` row — this is the
+ * immutable byte-source the sign pass will load. Pinning the rendered PDF
+ * (rather than re-rendering at sign time) eliminates the determinism risk
+ * of running Konva twice across the OAuth round-trip.
+ * 3. Reload `pdfDoc` from the persisted bytes and dry-run `pdf.sign` with
+ * `CscCaptureSigner` to derive the `signedAttrs` digest — captured over
+ * the same bytes the sign pass will load.
+ *
+ * The resulting `{ envelopeItemId, documentDataId, hashB64, ordinal }` tuples
+ * are stored on `CscSession.itemsJson`. `documentDataId` pins the orphan
+ * rendered row, not `envelopeItem.documentDataId` — the latter stays stable
+ * (in-place data updates only, mirroring the materialise pattern).
+ *
+ * Sequential per item — PDF parse + libpdf sign is CPU-heavy and per-recipient
+ * concurrency is wasted on a single Node event loop.
+ */
+
+export type PrepareCscRecipientSigningOptions = {
+ /** Recipient token from `/sign/{token}` URL. */
+ recipientToken: string;
+ /** Forwarded for audit log attribution. */
+ requestMetadata?: RequestMetadata;
+};
+
+export type PrepareCscRecipientSigningResult = {
+ status: 'REDIRECT';
+ redirectUrl: string;
+};
+
+export const prepareCscRecipientSigning = async (
+ opts: PrepareCscRecipientSigningOptions,
+): Promise<PrepareCscRecipientSigningResult> => {
+ const { recipientToken, requestMetadata } = opts;
+
+ const recipient = await prisma.recipient
+ .findFirst({
+ where: { token: recipientToken },
+ // `signature` must be eager-loaded — `renderRecipientOverlay` runs the
+ // field renderer in `export` mode, which throws `MISSING_SIGNATURE` for
+ // any inserted SIGNATURE field without signature data. Mirrors the
+ // include pattern in `seal-document.handler.ts`.
+ include: { fields: { include: { signature: true } } },
+ })
+ .catch(() => null);
+
+ if (!recipient) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `Recipient with token "${recipientToken}" not found.`,
+ });
+ }
+
+ const envelope = await prisma.envelope.findUniqueOrThrow({
+ where: { id: recipient.envelopeId },
+ include: {
+ envelopeItems: {
+ include: {
+ documentData: true,
+ },
+ },
+ recipients: true,
+ },
+ });
+
+ if (!isTspEnvelope(envelope)) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'prepareCscRecipientSigning called for a non-TSP envelope.',
+ });
+ }
+
+ const credential = await loadCscCredential(recipient.id);
+
+ if (!credential) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: 'CSC credential missing — service-scope OAuth must complete first.',
+ });
+ }
+
+ if (!credential.certCache) {
+ throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
+ message: 'CSC credential has no persisted certificate chain.',
+ });
+ }
+
+ if (credential.keyLenBits === null) {
+ throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
+ message: 'CSC credential omits persisted keyLenBits — service-scope OAuth must re-run.',
+ });
+ }
+
+ const chain = decodeCscCertChain(credential.certCache);
+
+ const algo = policyToLibpdfSignerAlgo({
+ keyType: credential.keyType as 'RSA' | 'ECDSA',
+ digestAlgorithm: credential.digestAlgorithm as CscDigest,
+ signAlgoOid: credential.signatureAlgorithm,
+ keyLenBits: credential.keyLenBits,
+ // `policyToLibpdfSignerAlgo` does not read `hashAlgoOid`; passing empty
+ // string keeps the synthetic policy type-correct without re-derivation.
+ hashAlgoOid: '',
+ });
+
+ // Pin a single signingTime for every per-item capture so the embed pass
+ // re-derives byte-identical signedAttrs digests.
+ const signingTime = new Date();
+
+ const items: TCscSessionItems = [];
+
+ for (const envelopeItem of envelope.envelopeItems) {
+ const recipientFieldsOnItem = recipient.fields.filter((field) => field.envelopeItemId === envelopeItem.id);
+
+ const pagesWithFields = new Set<number>();
+
+ for (const field of recipientFieldsOnItem) {
+ pagesWithFields.add(field.page);
+ }
+
+ const bytes = await getFileServerSide(envelopeItem.documentData);
+ const pdfDoc = await PDF.load(bytes);
+
+ for (const pageNumber of pagesWithFields) {
+ const fieldsOnPage: FieldWithSignature[] = recipientFieldsOnItem.filter((field) => field.page === pageNumber);
+
+ await renderRecipientOverlay({
+ pdfDoc,
+ stampName: buildTspStampName(recipient.id, envelopeItem.id, pageNumber),
+ pageNumber,
+ fields: fieldsOnPage,
+ });
+ }
+
+ // Persist the rendered PDF as an orphan `DocumentData` row before the
+ // capture pass so sign-time can load byte-identical input — eliminates
+ // the determinism risk of running Konva again after the OAuth round-trip.
+ const renderedBytes = await pdfDoc.save({ incremental: true });
+
+ const fileName = envelope.title.endsWith('.pdf') ? envelope.title : `${envelope.title || 'envelope'}.pdf`;
+
+ const renderedUpload = await putPdfFileServerSide(
+ {
+ name: fileName,
+ type: 'application/pdf',
+ arrayBuffer: async () => Promise.resolve(renderedBytes),
+ },
+ envelopeItem.documentData.initialData ?? undefined,
+ );
+
+ // Reload from the persisted bytes so the capture pass operates on the
+ // exact same bytes the sign pass will fetch from storage. Skipping the
+ // reload would compute the digest over an in-memory incremental update
+ // that diverges from what `PDF.load(renderedBytes)` produces.
+ const capturePdfDoc = await PDF.load(renderedBytes);
+
+ const captureSigner = new CscCaptureSigner({
+ certificate: chain[0],
+ certificateChain: chain.slice(1),
+ algo,
+ });
+
+ const anchorName = buildTspAnchorName(recipient.id, envelopeItem.id);
+
+ // Capture at B-B even though the eventual embed pass is B-T. The B-T
+ // signature timestamp is a CMS *unsigned* attribute, added by libpdf
+ // after `signer.sign()` runs over the signed-attrs digest — so B-B and
+ // B-T produce byte-identical signed-attrs for the same `(signer,
+ // documentHash, digestAlgorithm, signingTime)` tuple. See the matching
+ // note in `execute-tsp-sign.ts`.
+ await capturePdfDoc.sign({
+ signer: captureSigner,
+ fieldName: anchorName,
+ signingTime,
+ level: 'B-B',
+ digestAlgorithm: algo.digestAlgorithm,
+ });
+
+ if (captureSigner.capturedDigest === null) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CscCaptureSigner was not invoked by pdf.sign during prep.',
+ });
+ }
+
+ items.push({
+ envelopeItemId: envelopeItem.id,
+ documentDataId: renderedUpload.documentData.id,
+ hashB64: Buffer.from(captureSigner.capturedDigest).toString('base64'),
+ ordinal: items.length,
+ });
+ }
+
+ const session = await upsertCscSession({
+ recipientId: recipient.id,
+ envelopeId: envelope.id,
+ signingTime,
+ items,
+ });
+
+ await prisma.documentAuditLog.create({
+ data: createDocumentAuditLogData({
+ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGN_REQUESTED,
+ envelopeId: envelope.id,
+ user: { name: recipient.name, email: recipient.email },
+ requestMetadata,
+ data: {
+ recipientEmail: recipient.email,
+ recipientName: recipient.name,
+ recipientId: recipient.id,
+ recipientRole: recipient.role,
+ providerId: credential.providerId,
+ credentialId: credential.credentialId,
+ sessionId: session.id,
+ numSignatures: items.length,
+ },
+ }),
+ });
+
+ const redirectUrl = `${NEXT_PUBLIC_WEBAPP_URL()}/api/csc/oauth/authorize?scope=credential&session=${session.id}`;
+
+ return {
+ status: 'REDIRECT',
+ redirectUrl,
+ };
+};
diff --git a/packages/ee/server-only/signing/csc/render-overlay.ts b/packages/ee/server-only/signing/csc/render-overlay.ts
new file mode 100644
index 000000000..1ac5b9912
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/render-overlay.ts
@@ -0,0 +1,162 @@
+import { AnnotationFlags, ops, PDF, PdfArray, PdfDict, PdfName, PdfNumber } from '@libpdf/core';
+
+// `Operator` is declared in `@libpdf/core` but not exported. Derive it from
+// `ops.pushGraphicsState`'s return type instead of importing.
+type LibpdfOperator = ReturnType<typeof ops.pushGraphicsState>;
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { insertFieldInPDFV2 } from '@documenso/lib/server-only/pdf/insert-field-in-pdf-v2';
+import type { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
+
+/**
+ * CSC TSP recipient overlay renderer.
+ *
+ * Writes a recipient's per-page field values into the pre-allocated
+ * `/Stamp` annotation's normal appearance (`/AP /N`), reusing the Konva
+ * overlay generator that powers the SES path.
+ *
+ * SES uses `page.drawPage(embeddedPage)` to paint directly onto the page
+ * content stream. For TSP that would create a new page object in the
+ * incremental update and invalidate prior recipients' `/ByteRange`. Routing
+ * the same embedded FormXObject through a stamp's appearance keeps the page
+ * dict untouched while reusing the embed pipeline `drawPage` does.
+ *
+ * The appearance stream mirrors `drawPage`'s `x=0, y=0, scale=1, no-rotate`
+ * branch: a single `concatMatrix(1, 0, 0, 1, -box.x, -box.y)` compensates
+ * for any non-origin MediaBox on the overlay PDF before `paintXObject`. The
+ * stamp's `/Rect` and the appearance `/BBox` both span `[0, 0, page.width,
+ * page.height]`, so the PDF reader maps content 1:1 and page rotation
+ * applies at the page level (not inside the appearance).
+ */
+
+export type RenderRecipientOverlayOptions = {
+ /** The loaded PDF the stamp lives on. */
+ pdfDoc: PDF;
+ /** Stamp name from `buildTspStampName(recipientId, envelopeItemId, pageNumber)`. */
+ stampName: string;
+ /** 1-based page number. */
+ pageNumber: number;
+ /** Recipient's fields for THIS page only. */
+ fields: FieldWithSignature[];
+};
+
+/**
+ * Render `fields` into the pre-allocated `/Stamp` annotation named `stampName`
+ * on `pageNumber`. Mutates `pdfDoc` in place.
+ *
+ * Throws when the named stamp can't be located — every call site must have
+ * materialised the stamp first via `materializeTspAnchorsForEnvelope`.
+ */
+export const renderRecipientOverlay = async ({
+ pdfDoc,
+ stampName,
+ pageNumber,
+ fields,
+}: RenderRecipientOverlayOptions): Promise<void> => {
+ const page = pdfDoc.getPage(pageNumber - 1);
+
+ if (!page) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `Page ${pageNumber} not found on PDF.`,
+ });
+ }
+
+ const stamp = page.getStampAnnotations().find((annotation) => annotation.stampName === stampName);
+
+ if (!stamp) {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `TSP stamp ${stampName} not found on page ${pageNumber}.`,
+ });
+ }
+
+ const overlayBytes = await insertFieldInPDFV2({
+ pageWidth: page.width,
+ pageHeight: page.height,
+ fields,
+ });
+
+ const overlayDoc = await PDF.load(overlayBytes);
+ const embedded = await pdfDoc.embedPage(overlayDoc, 0);
+
+ // Bind the embedded page under a local XObject name in the appearance's
+ // own /Resources. Appearance streams are scoped — they can't see the
+ // parent page's resource dict.
+ const xobjectName = 'X0';
+
+ // Mirror `PDFPage.drawPage`'s no-rotation, no-scale branch:
+ // translateX = x - embedded.box.x * scaleX (x = 0, scaleX = 1)
+ // translateY = y - embedded.box.y * scaleY (y = 0, scaleY = 1)
+ // concatMatrix(scaleX, 0, 0, scaleY, translateX, translateY)
+ // Identity matrix when the overlay PDF has an origin-aligned MediaBox;
+ // a translate-only shift otherwise. No-op cost is negligible.
+ const operators: LibpdfOperator[] = [
+ ops.pushGraphicsState(),
+ ops.concatMatrix(1, 0, 0, 1, -embedded.box.x, -embedded.box.y),
+ ops.paintXObject(xobjectName),
+ ops.popGraphicsState(),
+ ];
+
+ const contentBytes = serializeOperators(operators);
+
+ const appearanceRef = pdfDoc.createStream(
+ {
+ Type: PdfName.of('XObject'),
+ Subtype: PdfName.of('Form'),
+ FormType: PdfNumber.of(1),
+ BBox: new PdfArray([PdfNumber.of(0), PdfNumber.of(0), PdfNumber.of(page.width), PdfNumber.of(page.height)]),
+ Resources: PdfDict.of({
+ XObject: PdfDict.of({
+ [xobjectName]: embedded.ref,
+ }),
+ }),
+ },
+ contentBytes,
+ );
+
+ // Direct dict write — bypasses `PDFAnnotation.setNormalAppearance`, which
+ // (a) re-registers the stream and (b) has a no-op branch when `/AP` is
+ // absent on the annotation. See `node_modules/@libpdf/core/dist/index.mjs:
+ // 4347-4357`. The PDF reader and libpdf's `getAppearance` (index.mjs:4337)
+ // both follow refs transparently, so `/AP -> { N: <ref> }` is valid.
+ stamp.dict.set('AP', PdfDict.of({ N: appearanceRef }));
+
+ stamp.setFlag(AnnotationFlags.Print, true);
+ stamp.setFlag(AnnotationFlags.ReadOnly, true);
+ stamp.setFlag(AnnotationFlags.Locked, true);
+ stamp.setFlag(AnnotationFlags.LockedContents, true);
+};
+
+/**
+ * Serialize a content-stream operator sequence into a single byte buffer,
+ * newline-separated. Mirrors libpdf's internal `serializeOperators` (not
+ * exported from `@libpdf/core`); each `Operator.toBytes()` returns one
+ * operator's `operand1 operand2 ... op` slice.
+ */
+const serializeOperators = (operators: LibpdfOperator[]): Uint8Array => {
+ if (operators.length === 0) {
+ return new Uint8Array(0);
+ }
+
+ const chunks = operators.map((operator) => operator.toBytes());
+
+ let totalLength = 0;
+
+ for (const chunk of chunks) {
+ totalLength += chunk.length + 1; // +1 for trailing newline
+ }
+
+ const out = new Uint8Array(totalLength);
+ let offset = 0;
+
+ for (const chunk of chunks) {
+ out.set(chunk, offset);
+
+ offset += chunk.length;
+
+ out[offset] = 0x0a;
+
+ offset += 1;
+ }
+
+ return out;
+};
diff --git a/packages/ee/server-only/signing/csc/sign-session.ts b/packages/ee/server-only/signing/csc/sign-session.ts
new file mode 100644
index 000000000..5fe5fff99
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/sign-session.ts
@@ -0,0 +1,181 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { type TCscSessionItems, ZCscSessionItemsSchema } from '@documenso/lib/types/csc-session';
+import { prisma } from '@documenso/prisma';
+import { Prisma } from '@prisma/client';
+
+/**
+ * DB helpers for `CscSession` — the per-recipient transient row that bridges
+ * prep, the credential-scope OAuth round-trip, and the sync sign mutation.
+ *
+ * Four operations cover the spec's lifecycle:
+ *
+ * - {@link upsertCscSession} — prep time; clears any prior SAD by writing
+ * `encryptedSad = null` so a re-clicked Sign starts fresh.
+ * - {@link updateCscSessionWithSad} — credential-scope callback; sets the
+ * SAD + its TSP-asserted expiry.
+ * - {@link loadCscSession} — authorize route, signing-page loader, sync
+ * mutation. Returns null on missing (cookie referenced a deleted session).
+ * - {@link consumeCscSession} — sync mutation success path; single-use delete
+ * returning the consumed row so the caller can use its data post-deletion.
+ *
+ * `itemsJson` is parsed through `ZCscSessionItemsSchema` on every read so the
+ * caller works with typed {@link TCscSessionItems}.
+ */
+
+export type CscSessionRow = {
+ id: string;
+ recipientId: number;
+ envelopeId: string;
+ signingTime: Date;
+ items: TCscSessionItems;
+ encryptedSad: Uint8Array | null;
+ sadExpiresAt: Date | null;
+ createdAt: Date;
+};
+
+type UpsertCscSessionInput = {
+ recipientId: number;
+ envelopeId: string;
+ signingTime: Date;
+ items: TCscSessionItems;
+};
+
+/**
+ * Create or refresh the per-recipient session row at prep time. The recipient
+ * has at most one in-flight session (`@@unique([recipientId])`); re-clicking
+ * Sign overwrites prior `itemsJson` + clears `encryptedSad` / `sadExpiresAt`
+ * so the next credential-scope callback starts from a clean SAD slot.
+ */
+export const upsertCscSession = async (input: UpsertCscSessionInput): Promise<CscSessionRow> => {
+ const { recipientId, envelopeId, signingTime, items } = input;
+
+ const row = await prisma.cscSession.upsert({
+ where: { recipientId },
+ create: {
+ recipientId,
+ envelopeId,
+ signingTime,
+ itemsJson: items,
+ encryptedSad: null,
+ sadExpiresAt: null,
+ },
+ update: {
+ envelopeId,
+ signingTime,
+ itemsJson: items,
+ encryptedSad: null,
+ sadExpiresAt: null,
+ },
+ });
+
+ return toCscSessionRow(row);
+};
+
+type UpdateCscSessionWithSadInput = {
+ sessionId: string;
+ encryptedSad: Uint8Array;
+ sadExpiresAt: Date;
+};
+
+/**
+ * Stamp the credential-scope SAD onto an existing session at the OAuth
+ * callback. Throws when the session id was already consumed or never existed
+ * — that's a flow-state bug the caller must surface, not silently skip.
+ */
+export const updateCscSessionWithSad = async (input: UpdateCscSessionWithSadInput): Promise<CscSessionRow> => {
+ const { sessionId, encryptedSad, sadExpiresAt } = input;
+
+ try {
+ const row = await prisma.cscSession.update({
+ where: {
+ id: sessionId,
+ },
+ data: {
+ encryptedSad: Buffer.from(encryptedSad),
+ sadExpiresAt,
+ },
+ });
+
+ return toCscSessionRow(row);
+ } catch (err) {
+ if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2025') {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `CSC session "${sessionId}" not found at SAD attach time.`,
+ });
+ }
+
+ throw err;
+ }
+};
+
+/**
+ * Fetch a session by id. Returns `null` when the row is absent — callers MUST
+ * handle the missing case (cookie outliving the row is a normal terminal
+ * outcome, not an error).
+ */
+export const loadCscSession = async (sessionId: string): Promise<CscSessionRow | null> => {
+ const row = await prisma.cscSession.findUnique({
+ where: { id: sessionId },
+ });
+
+ return row ? toCscSessionRow(row) : null;
+};
+
+/**
+ * Atomically delete the session row and return its parsed contents. Used by
+ * the sync mutation's success path so the caller still has the session data
+ * for post-sign side effects (audit log, webhook payloads).
+ *
+ * Throws `NOT_FOUND` when the row is already gone — semantically distinct
+ * from {@link loadCscSession}'s nullable return because consume is the
+ * success-path single-use closer; a missing row at that point means another
+ * branch raced to consume and the caller should not double-count.
+ */
+export const consumeCscSession = async (sessionId: string, tx?: Prisma.TransactionClient): Promise<CscSessionRow> => {
+ const client = tx ?? prisma;
+
+ try {
+ const row = await client.cscSession.delete({
+ where: { id: sessionId },
+ });
+
+ return toCscSessionRow(row);
+ } catch (err) {
+ if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2025') {
+ throw new AppError(AppErrorCode.NOT_FOUND, {
+ message: `CSC session "${sessionId}" already consumed or never existed.`,
+ });
+ }
+
+ throw err;
+ }
+};
+
+/**
+ * Project a raw Prisma `CscSession` into the helper's parsed shape. Throws
+ * on `itemsJson` parse failure — that's a data-integrity issue, not a
+ * recoverable runtime case.
+ */
+const toCscSessionRow = (row: {
+ id: string;
+ recipientId: number;
+ envelopeId: string;
+ signingTime: Date;
+ itemsJson: Prisma.JsonValue;
+ encryptedSad: Uint8Array | null;
+ sadExpiresAt: Date | null;
+ createdAt: Date;
+}): CscSessionRow => {
+ const items = ZCscSessionItemsSchema.parse(row.itemsJson);
+
+ return {
+ id: row.id,
+ recipientId: row.recipientId,
+ envelopeId: row.envelopeId,
+ signingTime: row.signingTime,
+ items,
+ encryptedSad: row.encryptedSad,
+ sadExpiresAt: row.sadExpiresAt,
+ createdAt: row.createdAt,
+ };
+};
diff --git a/packages/ee/server-only/signing/csc/signers/capture-signer.ts b/packages/ee/server-only/signing/csc/signers/capture-signer.ts
new file mode 100644
index 000000000..7fe3d8f0e
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/signers/capture-signer.ts
@@ -0,0 +1,123 @@
+/**
+ * CSC dry-run capture signer.
+ *
+ * Libpdf's signing flow expects an inline signer that hashes the
+ * `signedAttrs` bytes and returns a CMS signature. For the CSC §11.9
+ * `signatures/signHash` contract the actual signature is produced
+ * remotely by the TSP, so a single libpdf sign cycle has to be split
+ * into two passes:
+ *
+ * 1. Dry-run — drive `pdf.sign()` with this capture signer to derive
+ * the `signedAttrs` digest libpdf would otherwise sign. The
+ * resulting PDF is discarded; only `capturedDigest` matters.
+ * 2. Embed pass — the `CscFifoSigner` re-runs `pdf.sign()` and feeds
+ * the TSP-produced signature bytes back into the same byte slots.
+ *
+ * The placeholder bytes returned from `sign()` are sized to the
+ * chosen algorithm so libpdf's downstream CMS construction is not
+ * surprised by an unexpectedly short signature.
+ */
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { Signer } from '@libpdf/core';
+import { sha256, sha384, sha512 } from '@noble/hashes/sha2';
+
+import type { LibpdfSignerAlgo } from '../algorithm-resolver';
+
+type DigestAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+type KeyType = 'RSA' | 'EC';
+
+type SignatureAlgorithm = 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
+
+export type CscCaptureSignerOptions = {
+ certificate: Uint8Array;
+ certificateChain?: Uint8Array[];
+ algo: LibpdfSignerAlgo;
+};
+
+export class CscCaptureSigner implements Signer {
+ readonly certificate: Uint8Array;
+ readonly certificateChain?: Uint8Array[];
+ readonly keyType: KeyType;
+ readonly signatureAlgorithm: SignatureAlgorithm;
+ private readonly algo: LibpdfSignerAlgo;
+
+ /** Populated by `sign()`. `null` until libpdf calls into the signer. */
+ capturedDigest: Uint8Array | null = null;
+
+ constructor(options: CscCaptureSignerOptions) {
+ this.certificate = options.certificate;
+ this.certificateChain = options.certificateChain;
+ this.keyType = options.algo.keyType;
+ this.signatureAlgorithm = options.algo.signatureAlgorithm;
+ this.algo = options.algo;
+ }
+
+ /**
+ * Hash `data` with `algorithm` to derive the `signedAttrs` digest libpdf
+ * would normally sign, stash it on `capturedDigest`, then return a
+ * placeholder buffer sized to the chosen key so libpdf's CMS scaffolding
+ * accepts it. The placeholder bytes are never inspected — the resulting
+ * PDF is discarded after the digest is read.
+ */
+
+ // biome-ignore lint/suspicious/useAwait: intentional
+ async sign(data: Uint8Array, algorithm: DigestAlgorithm): Promise<Uint8Array> {
+ if (this.capturedDigest !== null) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CscCaptureSigner.sign() called more than once — capture signers are single-use.',
+ });
+ }
+
+ this.capturedDigest = hashData(data, algorithm);
+
+ return new Uint8Array(placeholderSize(this.algo));
+ }
+}
+
+const hashData = (data: Uint8Array, algorithm: DigestAlgorithm): Uint8Array => {
+ if (algorithm === 'SHA-256') {
+ return sha256(data);
+ }
+
+ if (algorithm === 'SHA-384') {
+ return sha384(data);
+ }
+
+ if (algorithm === 'SHA-512') {
+ return sha512(data);
+ }
+
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: `CscCaptureSigner.sign() called with unsupported digest algorithm '${String(algorithm)}'.`,
+ });
+};
+
+const placeholderSize = (algo: LibpdfSignerAlgo): number => {
+ if (algo.keyType === 'RSA') {
+ // RSA signature length === modulus length in bytes.
+ if (algo.keyLenBits >= 4096) {
+ return 512;
+ }
+
+ if (algo.keyLenBits >= 3072) {
+ return 384;
+ }
+
+ return 256;
+ }
+
+ // ECDSA DER-encoded SEQUENCE { INTEGER r, INTEGER s }. Upper bounds:
+ // P-256 ≈ 72 bytes, P-384 ≈ 104, P-521 ≈ 139. The dry-run PDF is
+ // discarded — exact size is informational, not load-bearing.
+ if (algo.keyLenBits >= 512) {
+ return 139;
+ }
+
+ if (algo.keyLenBits >= 384) {
+ return 104;
+ }
+
+ return 72;
+};
diff --git a/packages/ee/server-only/signing/csc/signers/fifo-signer.ts b/packages/ee/server-only/signing/csc/signers/fifo-signer.ts
new file mode 100644
index 000000000..c66eae7cc
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/signers/fifo-signer.ts
@@ -0,0 +1,57 @@
+/**
+ * CSC embed-pass FIFO signer.
+ *
+ * `signatures/signHash` (CSC §11.9) returns one signature per submitted
+ * hash, in the same position-bound order as the request `hash[]` array.
+ * The embed pass re-runs `pdf.sign()` once per anchor in that same order,
+ * so a FIFO queue of signature bytes — popped on each `sign()` call —
+ * is sufficient to feed libpdf without any per-anchor binding metadata.
+ */
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { Signer } from '@libpdf/core';
+
+import type { LibpdfSignerAlgo } from '../algorithm-resolver';
+
+type DigestAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+type KeyType = 'RSA' | 'EC';
+
+type SignatureAlgorithm = 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
+
+export type CscFifoSignerOptions = {
+ certificate: Uint8Array;
+ certificateChain?: Uint8Array[];
+ algo: LibpdfSignerAlgo;
+ /** Base64-decoded raw signature bytes in the order produced by `signatures/signHash`. */
+ signatures: Uint8Array[];
+};
+
+export class CscFifoSigner implements Signer {
+ readonly certificate: Uint8Array;
+ readonly certificateChain?: Uint8Array[];
+ readonly keyType: KeyType;
+ readonly signatureAlgorithm: SignatureAlgorithm;
+ private readonly queue: Uint8Array[];
+
+ constructor(options: CscFifoSignerOptions) {
+ this.certificate = options.certificate;
+ this.certificateChain = options.certificateChain;
+ this.keyType = options.algo.keyType;
+ this.signatureAlgorithm = options.algo.signatureAlgorithm;
+ this.queue = [...options.signatures];
+ }
+
+ // biome-ignore lint/suspicious/useAwait: intentional
+ async sign(_data: Uint8Array, _algorithm: DigestAlgorithm): Promise<Uint8Array> {
+ const next = this.queue.shift();
+
+ if (next === undefined) {
+ throw new AppError(AppErrorCode.INVALID_REQUEST, {
+ message: 'CSC FIFO signer exhausted — more sign() calls than queued signatures.',
+ });
+ }
+
+ return next;
+ }
+}
diff --git a/packages/ee/server-only/signing/csc/transport.ts b/packages/ee/server-only/signing/csc/transport.ts
new file mode 100644
index 000000000..162f0748e
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/transport.ts
@@ -0,0 +1,153 @@
+import { IS_INSTANCE_CSC_MODE, NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { assertLicensedFor } from '@documenso/lib/server-only/license/assert-licensed-for';
+import { requireEnv } from '@documenso/lib/utils/env';
+import type { OAuth2Client } from 'arctic';
+
+import { cscInfo } from './client/info';
+import { createCscOAuthClient } from './client/oauth';
+import type { TCscInfoResponse } from './client/types';
+import { isEnvTsaConfigured } from './tsa-resolver';
+
+/**
+ * Lazily-built, globally-cached CSC transport.
+ *
+ * Boot-discovers `cscInfo` (§11.1) once, caches the OAuth base URL +
+ * `signatures/timestamp` capability, and exposes a configured arctic
+ * `OAuth2Client`. License + env + discovery are gated at construction so a
+ * misconfigured instance fails at the first call site, not at sign time.
+ *
+ * Cached on `globalThis` so Hono routes and Remix loaders share one instance
+ * across bundles (mirrors {@link LicenseClient}'s strategy).
+ *
+ * A failed build is **not** cached — the next caller retries. This keeps a
+ * transient discovery hiccup from permanently breaking the transport while
+ * still amortising the success path to one round-trip per process.
+ */
+
+const DISCOVERY_TIMEOUT_MS = 10_000;
+
+const CSC_TIMESTAMP_METHOD = 'signatures/timestamp';
+
+export type CscTransport = {
+ /** Service base URI from `NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL`. */
+ serviceBaseUrl: string;
+ /** OAuth base URI from `info.oauth2` (§11.1). MAY differ from `serviceBaseUrl`. */
+ oauthBaseUrl: string;
+ /** Pre-configured arctic client bound to the TSP's OAuth registration. */
+ oauthClient: OAuth2Client;
+ /**
+ * Documenso's callback URL registered with the TSP. Derived from
+ * `NEXT_PUBLIC_WEBAPP_URL` and the fixed `/api/csc/oauth/callback` mount —
+ * mirrors `packages/auth/server/config.ts` for the sign-in OAuth providers.
+ * Operators must register this exact URL with the TSP.
+ */
+ oauthRedirectUri: string;
+ /** True when the TSP advertises `signatures/timestamp` in `info.methods`. */
+ supportsTimestamp: boolean;
+ /** Raw discovery response, exposed for callers needing other fields (`name`, `region`, `lang`). */
+ info: TCscInfoResponse;
+};
+
+declare global {
+ // eslint-disable-next-line no-var
+ var __documenso_csc_transport__: CscTransport | undefined;
+ // eslint-disable-next-line no-var
+ var __documenso_csc_transport_promise__: Promise<CscTransport> | undefined;
+}
+
+/**
+ * Get the current CSC transport, building + caching it on first call.
+ *
+ * Throws:
+ * - `NOT_SETUP` — instance is not in CSC mode, or a required env var is unset.
+ * - `CSC_UNLICENSED` — `instanceCscSigning` license flag missing.
+ * - `CSC_PROVIDER_INFO_FAILED` — `info` discovery failed or response omits
+ * the REQUIRED `oauth2` base URL.
+ *
+ * Safe to call concurrently — a second call during in-flight discovery
+ * awaits the same promise instead of starting a duplicate request.
+ */
+export const getCscTransport = async (): Promise<CscTransport> => {
+ if (globalThis.__documenso_csc_transport__) {
+ return globalThis.__documenso_csc_transport__;
+ }
+
+ if (!globalThis.__documenso_csc_transport_promise__) {
+ globalThis.__documenso_csc_transport_promise__ = buildCscTransport()
+ .then((transport) => {
+ globalThis.__documenso_csc_transport__ = transport;
+ return transport;
+ })
+ .finally(() => {
+ globalThis.__documenso_csc_transport_promise__ = undefined;
+ });
+ }
+
+ return await globalThis.__documenso_csc_transport_promise__;
+};
+
+/**
+ * Drop the cached transport. Intended for tests / operator-triggered reload
+ * after a license-key swap. Next {@link getCscTransport} call re-runs the
+ * full build pipeline (license + env + discovery).
+ */
+export const resetCscTransport = (): void => {
+ globalThis.__documenso_csc_transport__ = undefined;
+ globalThis.__documenso_csc_transport_promise__ = undefined;
+};
+
+const buildCscTransport = async (): Promise<CscTransport> => {
+ if (!IS_INSTANCE_CSC_MODE()) {
+ throw new AppError(AppErrorCode.NOT_SETUP, {
+ message: 'CSC transport requested but NEXT_PRIVATE_SIGNING_TRANSPORT is not "csc".',
+ });
+ }
+
+ await assertLicensedFor('instanceCscSigning', { errorCode: AppErrorCode.CSC_UNLICENSED });
+
+ const serviceBaseUrl = requireEnv('NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL');
+ const clientId = requireEnv('NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID');
+ const clientSecret = requireEnv('NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET');
+ const oauthRedirectUri = `${NEXT_PUBLIC_WEBAPP_URL()}/api/csc/oauth/callback`;
+
+ const oauthClient = createCscOAuthClient({ clientId, clientSecret, redirectUri: oauthRedirectUri });
+
+ const info = await cscInfo({
+ baseUrl: serviceBaseUrl,
+ signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
+ });
+
+ if (!info.oauth2) {
+ throw new AppError(AppErrorCode.CSC_PROVIDER_INFO_FAILED, {
+ message:
+ 'CSC TSP info response omits the required `oauth2` base URL. CSC QES V1 only supports OAuth-based authorization (§8.3) — non-OAuth TSPs are not compatible.',
+ });
+ }
+
+ const supportsTimestamp = info.methods.includes(CSC_TIMESTAMP_METHOD);
+
+ // Boot-time TSA invariant: `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is
+ // required unconditionally in CSC mode. Sign-time B-T can use the TSP's
+ // own `signatures/timestamp` endpoint when advertised, but seal-time
+ // B-LTA archival is env-only by design (operators should pin a dedicated
+ // qualified archival TSA — see `resolveCscSealTimeTsa`). Without env, an
+ // envelope would sign successfully and then hang in
+ // WAITING_FOR_SIGNATURE_COMPLETION when the seal job throws. Catch the
+ // misconfiguration at boot instead so the instance refuses to start.
+ if (!isEnvTsaConfigured()) {
+ throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
+ message:
+ 'NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is unset. AES/QES envelopes require a TSA for B-LTA archival at seal time regardless of whether the CSC TSP advertises signatures/timestamp for B-T sign-time. Configure NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY.',
+ });
+ }
+
+ return {
+ serviceBaseUrl,
+ oauthBaseUrl: info.oauth2,
+ oauthClient,
+ oauthRedirectUri,
+ supportsTimestamp,
+ info,
+ };
+};
diff --git a/packages/ee/server-only/signing/csc/tsa-resolver.ts b/packages/ee/server-only/signing/csc/tsa-resolver.ts
new file mode 100644
index 000000000..4dd92aba0
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/tsa-resolver.ts
@@ -0,0 +1,105 @@
+import { NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY } from '@documenso/lib/constants/app';
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { HttpTimestampAuthority, type TimestampAuthority } from '@libpdf/core';
+
+import type { CscTransport } from './transport';
+import { CscTspTimestampAuthority } from './tsp-timestamp-authority';
+
+/**
+ * Two-phase TSA resolution for the CSC transport.
+ *
+ * Phase 1 — sign time (PAdES B-T, per recipient signature).
+ * Each recipient's CMS gets a signature timestamp embedded as an unsigned
+ * attribute. {@link resolveCscSignTimeTsa} returns a libpdf-shaped
+ * `TimestampAuthority` bound to either the TSP's `signatures/timestamp`
+ * endpoint (authorised with the recipient's own service-scope bearer) or
+ * the operator's env-configured RFC 3161 TSA, whichever is configured.
+ * TSP wins precedence so a TSP-supplied TSA is the default when the TSP
+ * advertises the method.
+ *
+ * Phase 2 — seal time (PAdES B-LTA archival timestamp).
+ * The seal-document job emits one `/DocTimeStamp` over the fully-signed
+ * envelope. {@link resolveCscSealTimeTsa} returns the env-configured TSA
+ * only — the archival anchor SHOULD be a dedicated qualified archival
+ * TSA, independent of the per-recipient TSP. Using the TSP here would
+ * couple archive longevity to a TSP that may rotate or revoke, and seal
+ * time has no recipient context to carry a service-scope bearer anyway.
+ *
+ * Boot-time guard: {@link buildCscTransport} asserts
+ * `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is set unconditionally — seal
+ * time always needs it, so making it env-or-fail at boot also satisfies
+ * the sign-time fallback. The defensive throws inside the resolvers below
+ * should be unreachable in practice.
+ */
+
+/**
+ * Build a libpdf `TimestampAuthority` for a recipient's B-T sign-time
+ * signature timestamp.
+ *
+ * Precedence: TSP first, env fallback. Selection is made up-front based on
+ * the boot-discovered transport capability — we don't try TSP then fall
+ * through to env on a runtime error. If the chosen source fails at call
+ * time, the recipient's sign attempt fails (operator's recourse is to
+ * configure env, which then wins on the next sign).
+ *
+ * `serviceToken` is the decrypted, non-expired service-scope bearer for
+ * the current recipient — used only when the TSP source is selected.
+ */
+export const resolveCscSignTimeTsa = (transport: CscTransport, serviceToken: string): TimestampAuthority => {
+ if (transport.supportsTimestamp) {
+ return new CscTspTimestampAuthority({ transport, serviceToken });
+ }
+
+ const envUrls = parseTsaEnv(NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY());
+
+ if (envUrls.length > 0) {
+ return new HttpTimestampAuthority(envUrls[0]);
+ }
+
+ // Boot-time guard in `buildCscTransport` should have rejected this
+ // configuration before any recipient hit this code path.
+ throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
+ message:
+ 'CSC sign-time TSA unresolved: TSP does not advertise signatures/timestamp and NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is unset. This should have been caught by the boot-time guard in buildCscTransport.',
+ });
+};
+
+/**
+ * Resolve the seal-time archival TSA URLs (env only).
+ *
+ * Returns the parsed env list; the caller picks how to consume it (today
+ * `finalize-tsp-completion.ts` uses the first URL).
+ */
+export const resolveCscSealTimeTsa = (): { urls: string[] } => {
+ const envUrls = parseTsaEnv(NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY());
+
+ if (envUrls.length === 0) {
+ throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
+ message:
+ 'CSC seal-time archival timestamps require NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY. This should have been caught by the boot-time guard in buildCscTransport — the env var is required at seal time even when the TSP advertises signatures/timestamp.',
+ });
+ }
+
+ return { urls: envUrls };
+};
+
+/**
+ * Cheap boot-time predicate — used by `buildCscTransport` to decide
+ * whether the env TSA satisfies the "at least one source must be
+ * configured" invariant. Keeping the env parsing in one place avoids
+ * drift between the guard and the resolvers.
+ */
+export const isEnvTsaConfigured = (): boolean => {
+ return parseTsaEnv(NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY()).length > 0;
+};
+
+const parseTsaEnv = (raw: string | undefined): string[] => {
+ if (!raw) {
+ return [];
+ }
+
+ return raw
+ .split(',')
+ .map((url) => url.trim())
+ .filter(Boolean);
+};
diff --git a/packages/ee/server-only/signing/csc/tsp-timestamp-authority.ts b/packages/ee/server-only/signing/csc/tsp-timestamp-authority.ts
new file mode 100644
index 000000000..92a6558f6
--- /dev/null
+++ b/packages/ee/server-only/signing/csc/tsp-timestamp-authority.ts
@@ -0,0 +1,82 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { DigestAlgorithm, TimestampAuthority } from '@libpdf/core';
+
+import { hashOidForDigest } from './algorithm-resolver';
+import { cscTimestamp } from './client/signatures';
+import type { CscTransport } from './transport';
+
+/**
+ * libpdf {@link TimestampAuthority} backed by the CSC TSP's
+ * `signatures/timestamp` endpoint (§11.10).
+ *
+ * Used only at sign time, per recipient, when {@link resolveCscSignTimeTsa}
+ * selects the TSP source — that is, when the TSP advertises
+ * `signatures/timestamp` in `info.methods`. The token wired in is the
+ * current recipient's own service-scope bearer (the same one authorising
+ * the `signatures/signHash` call alongside it), so the timestamp gets
+ * attributed to the same identity that just authorised the signature.
+ *
+ * Seal-time archival timestamps do not use this class — they go through
+ * the env-only path in `finalize-tsp-completion.ts`.
+ *
+ * Failure semantics: a single `signatures/timestamp` call. On any error
+ * (HTTP, schema, expired token) we surface `CSC_PROVIDER_NO_TSA` with the
+ * upstream message folded in. There's no try-in-order — at sign time the
+ * recipient is fixed, so there's no other token to fall through to.
+ */
+
+type CscTspTimestampAuthorityOptions = {
+ transport: CscTransport;
+ /** Decrypted service-scope access token for the current recipient. */
+ serviceToken: string;
+ /** Optional deadline for the `signatures/timestamp` call. */
+ signal?: AbortSignal;
+};
+
+export class CscTspTimestampAuthority implements TimestampAuthority {
+ private readonly transport: CscTransport;
+
+ private readonly serviceToken: string;
+
+ private readonly signal?: AbortSignal;
+
+ constructor(opts: CscTspTimestampAuthorityOptions) {
+ this.transport = opts.transport;
+ this.serviceToken = opts.serviceToken;
+ this.signal = opts.signal;
+ }
+
+ /**
+ * Request a CSC §11.10 timestamp for the supplied digest, authorised with
+ * the recipient's service-scope bearer. Returns the decoded TimeStampToken
+ * bytes. Throws `CSC_PROVIDER_NO_TSA` carrying the upstream error message
+ * on failure.
+ *
+ * `algorithm` is libpdf's `DigestAlgorithm` (`SHA-256` / `SHA-384` /
+ * `SHA-512`), translated to the matching `hashAlgo` OID via the existing
+ * {@link hashOidForDigest} mapping so the spec's OID-typed payload stays
+ * in one place.
+ */
+ async timestamp(digest: Uint8Array, algorithm: DigestAlgorithm): Promise<Uint8Array> {
+ const hash = Buffer.from(digest).toString('base64');
+ const hashAlgo = hashOidForDigest(algorithm);
+
+ try {
+ const response = await cscTimestamp({
+ baseUrl: this.transport.serviceBaseUrl,
+ accessToken: this.serviceToken,
+ hash,
+ hashAlgo,
+ signal: this.signal,
+ });
+
+ return Buffer.from(response.timestamp, 'base64');
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+
+ throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
+ message: `CSC TSP timestamp endpoint refused the recipient's service token: ${message}.`,
+ });
+ }
+ }
+}
diff --git a/packages/lib/client-only/hooks/use-editor-recipients.ts b/packages/lib/client-only/hooks/use-editor-recipients.ts
index 4eae6418d..c4910b6ac 100644
--- a/packages/lib/client-only/hooks/use-editor-recipients.ts
+++ b/packages/lib/client-only/hooks/use-editor-recipients.ts
@@ -1,3 +1,4 @@
+import { IS_INSTANCE_CSC_MODE } from '@documenso/lib/constants/app';
import { ZRecipientActionAuthTypesSchema, ZRecipientAuthOptionsSchema } from '@documenso/lib/types/document-auth';
import type { TEditorEnvelope } from '@documenso/lib/types/envelope-editor';
import { ZRecipientEmailSchema } from '@documenso/lib/types/recipient';
@@ -21,11 +22,49 @@ const LocalRecipientSchema = z.object({
type TLocalRecipient = z.infer<typeof LocalRecipientSchema>;
-export const ZEditorRecipientsFormSchema = z.object({
- signers: z.array(LocalRecipientSchema),
- signingOrder: z.nativeEnum(DocumentSigningOrder),
- allowDictateNextSigner: z.boolean().default(false),
-});
+/**
+ * Backstop validation that mirrors the CSC-mode UI overrides in
+ * `EnvelopeEditorProvider`. If anything bypasses the disabled controls (URL
+ * tampering, legacy form state, embedded host) the form refuses to submit
+ * rather than persisting values the TSP flow can't honour.
+ */
+export const ZEditorRecipientsFormSchema = z
+ .object({
+ signers: z.array(LocalRecipientSchema),
+ signingOrder: z.nativeEnum(DocumentSigningOrder),
+ allowDictateNextSigner: z.boolean().default(false),
+ })
+ .superRefine((data, ctx) => {
+ if (!IS_INSTANCE_CSC_MODE()) {
+ return;
+ }
+
+ if (data.signingOrder !== DocumentSigningOrder.SEQUENTIAL) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: 'CSC envelopes must use SEQUENTIAL signing order.',
+ path: ['signingOrder'],
+ });
+ }
+
+ if (data.allowDictateNextSigner) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: 'CSC envelopes do not support next-signer dictation.',
+ path: ['allowDictateNextSigner'],
+ });
+ }
+
+ data.signers.forEach((signer, index) => {
+ if (signer.role === RecipientRole.ASSISTANT) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: 'CSC envelopes do not support the assistant role.',
+ path: ['signers', index, 'role'],
+ });
+ }
+ });
+ });
export type TEditorRecipientsFormSchema = z.infer<typeof ZEditorRecipientsFormSchema>;
diff --git a/packages/lib/client-only/providers/envelope-editor-provider.tsx b/packages/lib/client-only/providers/envelope-editor-provider.tsx
index 8b48e45f6..e61ed7ae0 100644
--- a/packages/lib/client-only/providers/envelope-editor-provider.tsx
+++ b/packages/lib/client-only/providers/envelope-editor-provider.tsx
@@ -1,3 +1,4 @@
+import { IS_INSTANCE_CSC_MODE } from '@documenso/lib/constants/app';
import { DO_NOT_INVALIDATE_QUERY_ON_MUTATION } from '@documenso/lib/constants/trpc';
import {
DEFAULT_EDITOR_CONFIG,
@@ -36,6 +37,12 @@ type EnvelopeEditorProviderValue = {
isEmbedded: boolean;
isDocument: boolean;
isTemplate: boolean;
+ /**
+ * Whether the instance is running in CSC (Cloud Signature Consortium) mode.
+ * Components can branch on this for any additional CSC-only UI gating
+ * beyond the overrides already baked into `editorConfig`.
+ */
+ isCscMode: boolean;
setLocalEnvelope: (localEnvelope: Partial<TEditorEnvelope>) => void;
updateEnvelope: (envelopeUpdates: UpdateEnvelopePayload) => void;
@@ -91,7 +98,7 @@ export const useCurrentEnvelopeEditor = () => {
export const EnvelopeEditorProvider = ({
children,
- editorConfig = DEFAULT_EDITOR_CONFIG,
+ editorConfig: providedEditorConfig = DEFAULT_EDITOR_CONFIG,
initialEnvelope,
organisationEmails,
}: EnvelopeEditorProviderProps) => {
@@ -103,6 +110,31 @@ export const EnvelopeEditorProvider = ({
const [envelope, _setEnvelope] = useState(initialEnvelope);
const [autosaveError, setAutosaveError] = useState<boolean>(false);
+ const isCscMode = IS_INSTANCE_CSC_MODE();
+
+ /**
+ * CSC-mode overrides applied on top of any caller-supplied editor config.
+ * TSP envelopes are forced SEQUENTIAL at send-time and the sign path has no
+ * nextSigner dictation; the assistant role's pre-fill semantics don't map
+ * onto each recipient signing their own complete PDF state. Hide all three
+ * up-front so authors don't pick options that would get silently coerced.
+ */
+ const editorConfig = useMemo<EnvelopeEditorConfig>(() => {
+ if (!isCscMode || !providedEditorConfig.recipients) {
+ return providedEditorConfig;
+ }
+
+ return {
+ ...providedEditorConfig,
+ recipients: {
+ ...providedEditorConfig.recipients,
+ allowConfigureSigningOrder: false,
+ allowConfigureDictateNextSigner: false,
+ allowAssistantRole: false,
+ },
+ };
+ }, [isCscMode, providedEditorConfig]);
+
const envelopeRef = useRef(initialEnvelope);
const externalFlushCallbacksRef = useRef<Map<string, () => Promise<void>>>(new Map());
@@ -467,6 +499,7 @@ export const EnvelopeEditorProvider = ({
isEmbedded,
isDocument: envelope.type === EnvelopeType.DOCUMENT,
isTemplate: envelope.type === EnvelopeType.TEMPLATE,
+ isCscMode,
setLocalEnvelope,
getRecipientColorKey,
updateEnvelope,
diff --git a/packages/lib/constants/app.ts b/packages/lib/constants/app.ts
index 1150a4ca7..0ab54d826 100644
--- a/packages/lib/constants/app.ts
+++ b/packages/lib/constants/app.ts
@@ -1,4 +1,6 @@
import { env } from '@documenso/lib/utils/env';
+import { AppError, AppErrorCode } from '../errors/app-error';
+import { SignatureLevel, type TSignatureLevel } from '../types/signature-level';
export const APP_DOCUMENT_UPLOAD_SIZE_LIMIT = Number(env('NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT')) || 50;
@@ -33,3 +35,54 @@ export const IS_AI_FEATURES_CONFIGURED = () => !!env('GOOGLE_VERTEX_PROJECT_ID')
export const NEXT_PRIVATE_USE_PLAYWRIGHT_PDF = () => env('NEXT_PRIVATE_USE_PLAYWRIGHT_PDF') === 'true';
export const NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY = () => env('NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY');
+
+/**
+ * Whether this Documenso instance is running in CSC (Cloud Signature Consortium) mode.
+ *
+ * CSC mode routes signing through a third-party Trust Service Provider for
+ * Advanced and Qualified Electronic Signatures (AES/QES). It is instance-wide
+ * and mutually exclusive with the other signing transports.
+ */
+export const IS_INSTANCE_CSC_MODE = (): boolean => {
+ if (typeof window === 'undefined') {
+ return env('NEXT_PRIVATE_SIGNING_TRANSPORT') === 'csc';
+ }
+
+ return env('NEXT_PUBLIC_SIGNING_TRANSPORT_IS_CSC') === 'true';
+};
+
+/**
+ * The default signature level applied to envelopes created on a CSC-mode
+ * instance when the caller doesn't specify one (or asks for `SES` and the
+ * resolver is in loose-coerce mode).
+ *
+ * Set via `NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL`; accepts `AES` or `QES`
+ * only; defaults to `AES` when unset. An explicit `AES`/`QES` request on
+ * envelope create still passes through unchanged — this constant only affects
+ * the coerced default.
+ *
+ * Throws on an invalid value rather than silently falling back. A typo here
+ * (e.g. `qes`) would otherwise silently downgrade qualified-tier instances
+ * to advanced-tier, which has legal consequences.
+ *
+ * Only consulted on CSC-mode instances. Non-CSC instances always default to
+ * `SES` regardless of this var.
+ */
+export const CSC_INSTANCE_SIGNATURE_LEVEL = (): TSignatureLevel => {
+ // Cast through `string | undefined` because shells can deliver
+ // `NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL=` as an empty string at runtime
+ // — the typed env signature narrows to `'AES' | 'QES' | undefined` only.
+ const value = env('NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL');
+
+ if (!value) {
+ return SignatureLevel.AES;
+ }
+
+ if (value !== SignatureLevel.AES && value !== SignatureLevel.QES) {
+ throw new AppError(AppErrorCode.NOT_SETUP, {
+ message: `NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL must be '${SignatureLevel.AES}' or '${SignatureLevel.QES}', got '${value}'.`,
+ });
+ }
+
+ return value;
+};
diff --git a/packages/lib/errors/app-error.ts b/packages/lib/errors/app-error.ts
index 5a64814b6..a5f2bdab1 100644
--- a/packages/lib/errors/app-error.ts
+++ b/packages/lib/errors/app-error.ts
@@ -14,6 +14,7 @@ export enum AppErrorCode {
NOT_FOUND = 'NOT_FOUND',
NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
NOT_SETUP = 'NOT_SETUP',
+ MISSING_ENV_VAR = 'MISSING_ENV_VAR',
INVALID_CAPTCHA = 'INVALID_CAPTCHA',
UNAUTHORIZED = 'UNAUTHORIZED',
FORBIDDEN = 'FORBIDDEN',
@@ -27,6 +28,35 @@ export enum AppErrorCode {
ENVELOPE_COMPLETED = 'ENVELOPE_COMPLETED',
ENVELOPE_REJECTED = 'ENVELOPE_REJECTED',
ENVELOPE_LEGACY = 'ENVELOPE_LEGACY',
+ /**
+ * Authoring mutation rejected because the envelope is an AES/QES envelope
+ * past DRAFT — the TSP mutation lock fires at distribution to preserve
+ * WYSIWYS. SES envelopes never hit this code.
+ */
+ ENVELOPE_TSP_LOCKED = 'ENVELOPE_TSP_LOCKED',
+
+ /**
+ * CSC (Cloud Signature Consortium) error codes. See the CSC QES V1 spec
+ * for the recovery taxonomy.
+ */
+ CSC_INSTANCE_MODE_MISMATCH = 'CSC_INSTANCE_MODE_MISMATCH',
+ CSC_UNLICENSED = 'CSC_UNLICENSED',
+ CSC_PROVIDER_INFO_FAILED = 'CSC_PROVIDER_INFO_FAILED',
+ CSC_PROVIDER_NO_TSA = 'CSC_PROVIDER_NO_TSA',
+ CSC_CREDENTIAL_LIST_EMPTY = 'CSC_CREDENTIAL_LIST_EMPTY',
+ CSC_CERT_INVALID = 'CSC_CERT_INVALID',
+ CSC_ALGORITHM_REFUSED = 'CSC_ALGORITHM_REFUSED',
+ CSC_SAD_EXPIRED_PRE_SIGN = 'CSC_SAD_EXPIRED_PRE_SIGN',
+ CSC_TSP_TIMEOUT = 'CSC_TSP_TIMEOUT',
+ CSC_EMBED_FAILED = 'CSC_EMBED_FAILED',
+ CSC_BASE_DOCUMENT_MUTATED = 'CSC_BASE_DOCUMENT_MUTATED',
+ /**
+ * Generic catch-all for CSC HTTP transport failures — network error, non-2xx
+ * response without a more specific semantic match, malformed JSON, or
+ * response schema mismatch. Carries the TSP's HTTP status in `statusCode`
+ * and the TSP's `error` / `error_description` in the message when available.
+ */
+ CSC_REQUEST_FAILED = 'CSC_REQUEST_FAILED',
}
export const genericErrorCodeToTrpcErrorCodeMap: Record<string, { code: string; status: number }> = {
@@ -39,6 +69,7 @@ export const genericErrorCodeToTrpcErrorCodeMap: Record<string, { code: string;
[AppErrorCode.NOT_FOUND]: { code: 'NOT_FOUND', status: 404 },
[AppErrorCode.NOT_IMPLEMENTED]: { code: 'INTERNAL_SERVER_ERROR', status: 501 },
[AppErrorCode.NOT_SETUP]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.MISSING_ENV_VAR]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
[AppErrorCode.UNAUTHORIZED]: { code: 'UNAUTHORIZED', status: 401 },
[AppErrorCode.FORBIDDEN]: { code: 'FORBIDDEN', status: 403 },
[AppErrorCode.UNKNOWN_ERROR]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
@@ -50,6 +81,23 @@ export const genericErrorCodeToTrpcErrorCodeMap: Record<string, { code: string;
[AppErrorCode.ENVELOPE_COMPLETED]: { code: 'BAD_REQUEST', status: 400 },
[AppErrorCode.ENVELOPE_REJECTED]: { code: 'BAD_REQUEST', status: 400 },
[AppErrorCode.ENVELOPE_LEGACY]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.ENVELOPE_TSP_LOCKED]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_INSTANCE_MODE_MISMATCH]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_UNLICENSED]: { code: 'FORBIDDEN', status: 403 },
+ [AppErrorCode.CSC_PROVIDER_INFO_FAILED]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
+ [AppErrorCode.CSC_PROVIDER_NO_TSA]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
+ [AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_CERT_INVALID]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_ALGORITHM_REFUSED]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_TSP_TIMEOUT]: { code: 'TIMEOUT', status: 408 },
+ [AppErrorCode.CSC_EMBED_FAILED]: { code: 'BAD_REQUEST', status: 400 },
+ [AppErrorCode.CSC_BASE_DOCUMENT_MUTATED]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
+ // Generic transport failure — the TSP is upstream so server-side from our
+ // perspective; 500 keeps the caller surface conservative. The TSP's actual
+ // HTTP status rides along in AppError.statusCode for the few callers that
+ // need to discriminate (e.g. 401 → re-auth, 429 → backoff).
+ [AppErrorCode.CSC_REQUEST_FAILED]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
};
export const ZAppErrorJsonSchema = z.object({
@@ -239,10 +287,17 @@ export class AppError extends Error {
AppErrorCode.ENVELOPE_COMPLETED,
AppErrorCode.ENVELOPE_REJECTED,
AppErrorCode.ENVELOPE_LEGACY,
+ AppErrorCode.ENVELOPE_TSP_LOCKED,
+ AppErrorCode.CSC_INSTANCE_MODE_MISMATCH,
+ AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY,
+ AppErrorCode.CSC_CERT_INVALID,
+ AppErrorCode.CSC_ALGORITHM_REFUSED,
+ AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN,
+ AppErrorCode.CSC_EMBED_FAILED,
() => 400 as const,
)
.with(AppErrorCode.UNAUTHORIZED, () => 401 as const)
- .with(AppErrorCode.FORBIDDEN, () => 403 as const)
+ .with(AppErrorCode.FORBIDDEN, AppErrorCode.CSC_UNLICENSED, () => 403 as const)
.with(AppErrorCode.NOT_FOUND, () => 404 as const)
.with(AppErrorCode.NOT_IMPLEMENTED, () => 501 as const)
.otherwise(() => 500 as const);
diff --git a/packages/lib/jobs/definitions/internal/backport-subscription-claims.ts b/packages/lib/jobs/definitions/internal/backport-subscription-claims.ts
index ce37bbd4c..ca6baf45a 100644
--- a/packages/lib/jobs/definitions/internal/backport-subscription-claims.ts
+++ b/packages/lib/jobs/definitions/internal/backport-subscription-claims.ts
@@ -20,6 +20,7 @@ const BACKPORT_SUBSCRIPTION_CLAIM_JOB_DEFINITION_SCHEMA = z.object({
cfr21: z.literal(true).optional(),
hipaa: z.literal(true).optional(),
signingReminders: z.literal(true).optional(),
+ cscQesSigning: z.literal(true).optional(),
// Do NOT backport disableEmails.
// Todo: Envelopes - Do we need to check?
// authenticationPortal & emailDomains missing here.
diff --git a/packages/lib/jobs/definitions/internal/seal-document.handler.ts b/packages/lib/jobs/definitions/internal/seal-document.handler.ts
index d78212642..49758b323 100644
--- a/packages/lib/jobs/definitions/internal/seal-document.handler.ts
+++ b/packages/lib/jobs/definitions/internal/seal-document.handler.ts
@@ -1,5 +1,6 @@
import path from 'node:path';
import { PDFDocument } from '@cantoo/pdf-lib';
+import { finalizeTspEnvelopeCompletion } from '@documenso/ee/server-only/signing/csc/finalize-tsp-completion';
import { addRejectionStampToPdf } from '@documenso/lib/server-only/pdf/add-rejection-stamp-to-pdf';
import { generateAuditLogPdf } from '@documenso/lib/server-only/pdf/generate-audit-log-pdf';
import { generateCertificatePdf } from '@documenso/lib/server-only/pdf/generate-certificate-pdf';
@@ -22,6 +23,7 @@ import { legacy_insertFieldInPDF } from '../../../server-only/pdf/legacy-insert-
import { getTeamSettings } from '../../../server-only/team/get-team-settings';
import { triggerWebhook } from '../../../server-only/webhooks/trigger/trigger-webhook';
import { DOCUMENT_AUDIT_LOG_TYPE, type TDocumentAuditLog } from '../../../types/document-audit-logs';
+import { isTspEnvelope } from '../../../types/signature-level';
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../../types/webhook-payload';
import { prefixedId } from '../../../universal/id';
import { getFileServerSide } from '../../../universal/upload/get-file.server';
@@ -164,6 +166,33 @@ export const run = async ({ payload, io }: { payload: TSealDocumentJobDefinition
const finalEnvelopeStatus = isRejected ? DocumentStatus.REJECTED : DocumentStatus.COMPLETED;
+ if (isTspEnvelope(envelope)) {
+ if (isResealing) {
+ throw new AppError(AppErrorCode.NOT_SETUP, {
+ message: 'Re-sealing TSP envelopes is not supported — recipient signatures cannot be regenerated externally.',
+ });
+ }
+
+ if (isRejected) {
+ throw new AppError(AppErrorCode.NOT_SETUP, {
+ message:
+ 'TSP envelope rejection is not supported in V1 — rejection stamps would invalidate PAdES signatures.',
+ });
+ }
+
+ await finalizeTspEnvelopeCompletion({
+ envelope,
+ envelopeCompletedAuditLog,
+ requestMetadata,
+ });
+
+ return {
+ envelopeId: envelope.id,
+ envelopeStatus: envelope.status,
+ isRejected,
+ };
+ }
+
// Pre-fetch all PDF data so we can read dimensions and pass it
// to decorateAndSignPdf without fetching again.
const prefetchedItems = await Promise.all(
diff --git a/packages/lib/server-only/document-meta/upsert-document-meta.ts b/packages/lib/server-only/document-meta/upsert-document-meta.ts
index 770c3ceb3..93b4c5240 100644
--- a/packages/lib/server-only/document-meta/upsert-document-meta.ts
+++ b/packages/lib/server-only/document-meta/upsert-document-meta.ts
@@ -8,7 +8,10 @@ import type { SupportedLanguageCodes } from '../../constants/i18n';
import { AppError, AppErrorCode } from '../../errors/app-error';
import type { TDocumentEmailSettings } from '../../types/document-email';
import type { EnvelopeIdOptions } from '../../utils/envelope';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
+import { assertCompatibleDictateNextSigner } from '../signature-level/assert-compatible-dictate-next-signer';
+import { assertCompatibleSigningOrder } from '../signature-level/assert-compatible-signing-order';
export type CreateDocumentMetaOptions = {
userId: number;
@@ -73,6 +76,22 @@ export const updateDocumentMeta = async ({
});
}
+ await assertEnvelopeMutable(envelope);
+
+ if (signingOrder !== undefined) {
+ assertCompatibleSigningOrder({
+ signatureLevel: envelope.signatureLevel,
+ signingOrder,
+ });
+ }
+
+ if (allowDictateNextSigner !== undefined) {
+ assertCompatibleDictateNextSigner({
+ signatureLevel: envelope.signatureLevel,
+ allowDictateNextSigner,
+ });
+ }
+
const { documentMeta: originalDocumentMeta } = envelope;
// Validate the emailId belongs to the organisation.
@@ -92,6 +111,8 @@ export const updateDocumentMeta = async ({
}
return await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
const upsertedDocumentMeta = await tx.documentMeta.update({
where: {
id: envelope.documentMetaId,
diff --git a/packages/lib/server-only/document/send-document.ts b/packages/lib/server-only/document/send-document.ts
index 1c42bd482..84821e2d5 100644
--- a/packages/lib/server-only/document/send-document.ts
+++ b/packages/lib/server-only/document/send-document.ts
@@ -1,3 +1,4 @@
+import { materializeTspAnchorsForEnvelope } from '@documenso/ee/server-only/signing/csc/materialize-anchors';
import { resolveExpiresAt } from '@documenso/lib/constants/envelope-expiration';
import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
import type { ApiRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
@@ -29,6 +30,7 @@ import {
ZRadioFieldMeta,
ZTextFieldMeta,
} from '../../types/field-meta';
+import { isTspEnvelope } from '../../types/signature-level';
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
import { getFileServerSide } from '../../universal/upload/get-file.server';
import { putNormalizedPdfFileServerSide } from '../../universal/upload/put-file.server';
@@ -124,7 +126,26 @@ export const sendDocument = async ({ id, userId, teamId, sendEmail, requestMetad
const legacyDocumentId = mapSecondaryIdToDocumentId(envelope.secondaryId);
- const signingOrder = envelope.documentMeta?.signingOrder || DocumentSigningOrder.PARALLEL;
+ let signingOrder = envelope.documentMeta?.signingOrder || DocumentSigningOrder.PARALLEL;
+
+ if (isTspEnvelope(envelope) && signingOrder === DocumentSigningOrder.PARALLEL && envelope.documentMeta) {
+ console.warn(
+ `[CSC] Coercing signingOrder=PARALLEL → SEQUENTIAL for ${envelope.signatureLevel} envelope ${envelope.id} at send time. The schema-layer guard should have caught this earlier.`,
+ );
+
+ await prisma.documentMeta.update({
+ where: {
+ id: envelope.documentMeta.id,
+ },
+ data: {
+ signingOrder: DocumentSigningOrder.SEQUENTIAL,
+ },
+ });
+
+ signingOrder = DocumentSigningOrder.SEQUENTIAL;
+
+ envelope.documentMeta.signingOrder = DocumentSigningOrder.SEQUENTIAL;
+ }
let recipientsToNotify = envelope.recipients;
@@ -139,7 +160,7 @@ export const sendDocument = async ({ id, userId, teamId, sendEmail, requestMetad
throw new Error('Missing envelope items');
}
- if (envelope.formValues) {
+ if (envelope.formValues && envelope.status === DocumentStatus.DRAFT) {
await Promise.all(
envelope.envelopeItems.map(async (envelopeItem) => {
await injectFormValuesIntoDocument(envelope, envelopeItem);
@@ -225,6 +246,12 @@ export const sendDocument = async ({ id, userId, teamId, sendEmail, requestMetad
}
}
+ if (isTspEnvelope(envelope) && envelope.status === DocumentStatus.DRAFT) {
+ await materializeTspAnchorsForEnvelope({
+ envelopeId: envelope.id,
+ });
+ }
+
const updatedEnvelope = await prisma.$transaction(async (tx) => {
if (envelope.status === DocumentStatus.DRAFT) {
await tx.documentAuditLog.create({
diff --git a/packages/lib/server-only/envelope-item/replace-envelope-item-pdf.ts b/packages/lib/server-only/envelope-item/replace-envelope-item-pdf.ts
index 108250aaf..fb305e311 100644
--- a/packages/lib/server-only/envelope-item/replace-envelope-item-pdf.ts
+++ b/packages/lib/server-only/envelope-item/replace-envelope-item-pdf.ts
@@ -6,6 +6,7 @@ import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-
import { prisma } from '@documenso/prisma';
import type { Envelope, Field, Recipient } from '@prisma/client';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { convertPlaceholdersToFieldInputs, extractPdfPlaceholders } from '../pdf/auto-place-fields';
import { findRecipientByPlaceholder } from '../pdf/helpers';
import { insertFormValuesInPdf } from '../pdf/insert-form-values-in-pdf';
@@ -96,6 +97,8 @@ export const UNSAFE_replaceEnvelopeItemPdf = async ({
let didFieldsChange = false;
const updatedEnvelopeItem = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
const updatedItem = await tx.envelopeItem.update({
where: {
id: envelopeItemId,
diff --git a/packages/lib/server-only/envelope/assert-envelope-mutable.ts b/packages/lib/server-only/envelope/assert-envelope-mutable.ts
new file mode 100644
index 000000000..5d303cc35
--- /dev/null
+++ b/packages/lib/server-only/envelope/assert-envelope-mutable.ts
@@ -0,0 +1,81 @@
+import { DocumentStatus, type Envelope, type Prisma } from '@prisma/client';
+import { match } from 'ts-pattern';
+
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { isTspEnvelope } from '../../types/signature-level';
+
+type EnvelopeMutableSnapshot = {
+ signatureLevel: string;
+ status: DocumentStatus;
+};
+
+type EnvelopeIdRef = Pick<Envelope, 'id'>;
+
+/**
+ * Reject authoring mutations on an AES/QES envelope past DRAFT.
+ *
+ * The TSP mutation lock fires at distribution so the owner cannot replace the
+ * PDF between a recipient completing service-scope OAuth (against PDF_v1) and
+ * clicking Sign (now against PDF_v2). The SAD would authorise PDF_v2's digest
+ * while the recipient viewed PDF_v1 — a WYSIWYS break.
+ *
+ * SES envelopes pass through unchanged. The existing per-route guards still
+ * enforce COMPLETED/REJECTED rejection for them.
+ *
+ * Call this **twice** at every TSP-eligible authoring route:
+ *
+ * 1. Outside the transaction with the pre-fetched envelope snapshot —
+ * `assertEnvelopeMutable(envelope)` — fast-fail without a DB round-trip.
+ * 2. Inside the transaction with `tx` — `assertEnvelopeMutable(envelope, tx)`
+ * — re-fetches under the transaction's snapshot, closing the TOCTOU
+ * window against a concurrent `sendDocument` committing DRAFT → PENDING
+ * between the snapshot read and the mutation.
+ *
+ * Throws:
+ * - `ENVELOPE_TSP_LOCKED` when the envelope is PENDING (the case unique to
+ * the TSP lock — SES routes happily allow PENDING).
+ * - `ENVELOPE_COMPLETED` / `ENVELOPE_REJECTED` for those terminal states, to
+ * stay consistent with the existing envelope-state error vocabulary.
+ */
+export function assertEnvelopeMutable(envelope: EnvelopeMutableSnapshot): Promise<void>;
+export function assertEnvelopeMutable(envelope: EnvelopeIdRef, tx: Prisma.TransactionClient): Promise<void>;
+
+export async function assertEnvelopeMutable(
+ envelope: EnvelopeMutableSnapshot | EnvelopeIdRef,
+ tx?: Prisma.TransactionClient,
+): Promise<void> {
+ if (tx) {
+ return await refetchAndAssert(tx, (envelope as EnvelopeIdRef).id);
+ }
+
+ assertSnapshotMutable(envelope as EnvelopeMutableSnapshot);
+}
+
+const refetchAndAssert = async (tx: Prisma.TransactionClient, envelopeId: string): Promise<void> => {
+ const refetched = await tx.envelope.findFirstOrThrow({
+ where: { id: envelopeId },
+ select: { signatureLevel: true, status: true },
+ });
+
+ assertSnapshotMutable(refetched);
+};
+
+const assertSnapshotMutable = (envelope: EnvelopeMutableSnapshot): void => {
+ if (!isTspEnvelope(envelope)) {
+ return;
+ }
+
+ if (envelope.status === DocumentStatus.DRAFT) {
+ return;
+ }
+
+ const errorCode = match(envelope.status)
+ .with(DocumentStatus.PENDING, () => AppErrorCode.ENVELOPE_TSP_LOCKED)
+ .with(DocumentStatus.COMPLETED, () => AppErrorCode.ENVELOPE_COMPLETED)
+ .with(DocumentStatus.REJECTED, () => AppErrorCode.ENVELOPE_REJECTED)
+ .otherwise(() => AppErrorCode.INVALID_REQUEST);
+
+ throw new AppError(errorCode, {
+ message: `Envelope is locked — AES/QES envelopes cannot be modified after leaving DRAFT (current status: ${envelope.status}).`,
+ });
+};
diff --git a/packages/lib/server-only/envelope/create-envelope.ts b/packages/lib/server-only/envelope/create-envelope.ts
index f1ddbe13e..4ca73a387 100644
--- a/packages/lib/server-only/envelope/create-envelope.ts
+++ b/packages/lib/server-only/envelope/create-envelope.ts
@@ -29,6 +29,7 @@ import type {
import type { TDocumentFormValues } from '../../types/document-form-values';
import type { TEnvelopeAttachmentType } from '../../types/envelope-attachment';
import type { TFieldAndMeta } from '../../types/field-meta';
+import type { TSignatureLevel } from '../../types/signature-level';
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
import { getFileServerSide } from '../../universal/upload/get-file.server';
import { putPdfFileServerSide } from '../../universal/upload/put-file.server';
@@ -36,6 +37,8 @@ import { extractDerivedDocumentMeta } from '../../utils/document';
import { createDocumentAuthOptions, createRecipientAuthOptions } from '../../utils/document-auth';
import { buildTeamWhereQuery } from '../../utils/teams';
import { incrementDocumentId, incrementTemplateId } from '../envelope/increment-id';
+import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
+import { resolveSignatureLevel } from '../signature-level/resolve-signature-level';
import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
import { getTeamSettings } from '../team/get-team-settings';
import { assertUserNotDisabledById } from '../user/assert-user-not-disabled';
@@ -89,6 +92,7 @@ export type CreateEnvelopeOptions = {
recipients?: CreateEnvelopeRecipientOptions[];
folderId?: string;
delegatedDocumentOwner?: string;
+ signatureLevel?: TSignatureLevel;
};
attachments?: Array<{
label: string;
@@ -137,8 +141,14 @@ export const createEnvelope = async ({
publicDescription,
visibility: visibilityOverride,
delegatedDocumentOwner,
+ signatureLevel: requestedSignatureLevel,
} = data;
+ const signatureLevel = resolveSignatureLevel({
+ requested: requestedSignatureLevel,
+ strict: true,
+ });
+
const team = await prisma.team.findFirst({
where: buildTeamWhereQuery({ teamId, userId }),
include: {
@@ -195,6 +205,17 @@ export const createEnvelope = async ({
});
}
+ // CSC / TSP signing flows assume the V2 envelope shape: per-recipient
+ // anchors, materialised PDF lineage, sequential signing, mutation lock.
+ // The legacy V1 (Document) model can't carry that state, so AES/QES on V1
+ // is structurally unsupported and must fail at create time — not later at
+ // sign or seal time when the cause is harder to attribute.
+ if (signatureLevel !== 'SES' && internalVersion === 1) {
+ throw new AppError(AppErrorCode.INVALID_BODY, {
+ message: `Envelopes signed at '${signatureLevel}' require internalVersion=2; the legacy V1 envelope shape cannot host TSP signing.`,
+ });
+ }
+
let envelopeItems = data.envelopeItems;
// Todo: Envelopes - Remove
@@ -255,6 +276,10 @@ export const createEnvelope = async ({
});
}
+ for (const recipient of data.recipients ?? []) {
+ assertCompatibleRecipientRole({ signatureLevel, role: recipient.role });
+ }
+
const visibility = visibilityOverride || settings.documentVisibility;
const emailId = meta?.emailId;
@@ -311,10 +336,14 @@ export const createEnvelope = async ({
const [documentMeta, secondaryId, delegatedOwner] = await Promise.all([
prisma.documentMeta.create({
- data: extractDerivedDocumentMeta(settings, {
- ...meta,
- timezone: timezoneToUse,
- }),
+ data: extractDerivedDocumentMeta(
+ settings,
+ {
+ ...meta,
+ timezone: timezoneToUse,
+ },
+ signatureLevel,
+ ),
}),
type === EnvelopeType.DOCUMENT
? incrementDocumentId().then((v) => v.formattedDocumentId)
@@ -331,6 +360,7 @@ export const createEnvelope = async ({
internalVersion,
type,
title,
+ signatureLevel,
qrToken: prefixedId('qr'),
externalId,
envelopeItems: {
diff --git a/packages/lib/server-only/envelope/duplicate-envelope.ts b/packages/lib/server-only/envelope/duplicate-envelope.ts
index bffedb4da..a904bb3f2 100644
--- a/packages/lib/server-only/envelope/duplicate-envelope.ts
+++ b/packages/lib/server-only/envelope/duplicate-envelope.ts
@@ -4,11 +4,13 @@ import pMap from 'p-map';
import { omit } from 'remeda';
import { AppError, AppErrorCode } from '../../errors/app-error';
+import { ZSignatureLevelSchema } from '../../types/signature-level';
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
import { nanoid, prefixedId } from '../../universal/id';
import type { EnvelopeIdOptions } from '../../utils/envelope';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
import { incrementDocumentId, incrementTemplateId } from '../envelope/increment-id';
+import { resolveSignatureLevel } from '../signature-level/resolve-signature-level';
import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
@@ -40,6 +42,7 @@ export const duplicateEnvelope = async ({ id, userId, teamId, overrides }: Dupli
title: true,
userId: true,
internalVersion: true,
+ signatureLevel: true,
templateType: true,
publicTitle: true,
publicDescription: true,
@@ -116,12 +119,21 @@ export const duplicateEnvelope = async ({ id, userId, teamId, overrides }: Dupli
? 'PRIVATE'
: (envelope.templateType ?? undefined);
+ // The source level is a free-form TEXT column — parse defensively before
+ // handing to the resolver. Coerce (not strict) because instance mode may have
+ // changed since the source envelope was created.
+ const duplicatedSignatureLevel = resolveSignatureLevel({
+ requested: ZSignatureLevelSchema.parse(envelope.signatureLevel),
+ strict: false,
+ });
+
const duplicatedEnvelope = await prisma.envelope.create({
data: {
id: prefixedId('envelope'),
secondaryId,
type: targetType,
internalVersion: envelope.internalVersion,
+ signatureLevel: duplicatedSignatureLevel,
userId,
teamId,
title: envelope.title + ' (copy)',
diff --git a/packages/lib/server-only/envelope/get-envelope-for-recipient-signing.ts b/packages/lib/server-only/envelope/get-envelope-for-recipient-signing.ts
index bde38be18..b178f4705 100644
--- a/packages/lib/server-only/envelope/get-envelope-for-recipient-signing.ts
+++ b/packages/lib/server-only/envelope/get-envelope-for-recipient-signing.ts
@@ -36,6 +36,7 @@ export const ZEnvelopeForSigningResponse = z.object({
authOptions: true,
userId: true,
teamId: true,
+ signatureLevel: true,
}).extend({
documentMeta: DocumentMetaSchema.pick({
signingOrder: true,
diff --git a/packages/lib/server-only/envelope/update-envelope.ts b/packages/lib/server-only/envelope/update-envelope.ts
index 4bb70e516..f16987807 100644
--- a/packages/lib/server-only/envelope/update-envelope.ts
+++ b/packages/lib/server-only/envelope/update-envelope.ts
@@ -15,7 +15,10 @@ import { createDocumentAuthOptions, extractDocumentAuthMethods } from '../../uti
import type { EnvelopeIdOptions } from '../../utils/envelope';
import { buildTeamWhereQuery, canAccessTeamDocument } from '../../utils/teams';
import { recomputeNextReminderForEnvelope } from '../recipient/update-recipient-next-reminder';
+import { assertCompatibleDictateNextSigner } from '../signature-level/assert-compatible-dictate-next-signer';
+import { assertCompatibleSigningOrder } from '../signature-level/assert-compatible-signing-order';
import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
+import { assertEnvelopeMutable } from './assert-envelope-mutable';
import { getEnvelopeWhereInput } from './get-envelope-by-id';
export type UpdateEnvelopeOptions = {
@@ -76,6 +79,22 @@ export const updateEnvelope = async ({
});
}
+ assertEnvelopeMutable(envelope);
+
+ if (meta.signingOrder !== undefined) {
+ assertCompatibleSigningOrder({
+ signatureLevel: envelope.signatureLevel,
+ signingOrder: meta.signingOrder,
+ });
+ }
+
+ if (meta.allowDictateNextSigner !== undefined) {
+ assertCompatibleDictateNextSigner({
+ signatureLevel: envelope.signatureLevel,
+ allowDictateNextSigner: meta.allowDictateNextSigner,
+ });
+ }
+
if (envelope.type !== EnvelopeType.TEMPLATE && (data.publicTitle || data.publicDescription || data.templateType)) {
throw new AppError(AppErrorCode.INVALID_BODY, {
message: 'You cannot update the template fields for document type envelopes',
@@ -297,6 +316,8 @@ export const updateEnvelope = async ({
// }
const updatedEnvelope = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
const result = await tx.envelope.update({
where: {
id: envelope.id,
diff --git a/packages/lib/server-only/field/create-envelope-fields.ts b/packages/lib/server-only/field/create-envelope-fields.ts
index 92d9f09c3..dde13f904 100644
--- a/packages/lib/server-only/field/create-envelope-fields.ts
+++ b/packages/lib/server-only/field/create-envelope-fields.ts
@@ -12,6 +12,7 @@ import { AppError, AppErrorCode } from '../../errors/app-error';
import type { EnvelopeIdOptions } from '../../utils/envelope';
import { mapFieldToLegacyField } from '../../utils/fields';
import { canRecipientFieldsBeModified } from '../../utils/recipients';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
import { type BoundingBox, whiteoutRegions } from '../pdf/auto-place-fields';
@@ -93,6 +94,8 @@ export const createEnvelopeFields = async ({
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.type === EnvelopeType.DOCUMENT && envelope.completedAt) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'Envelope already complete',
@@ -242,6 +245,8 @@ export const createEnvelopeFields = async ({
});
const createdFields = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
const newlyCreatedFields = await tx.field.createManyAndReturn({
data: validatedFields.map((field) => ({
type: field.type,
diff --git a/packages/lib/server-only/field/delete-document-field.ts b/packages/lib/server-only/field/delete-document-field.ts
index 7d53de62b..ae9cc1247 100644
--- a/packages/lib/server-only/field/delete-document-field.ts
+++ b/packages/lib/server-only/field/delete-document-field.ts
@@ -6,6 +6,7 @@ import { EnvelopeType } from '@prisma/client';
import { AppError, AppErrorCode } from '../../errors/app-error';
import { canRecipientFieldsBeModified } from '../../utils/recipients';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
export interface DeleteDocumentFieldOptions {
@@ -59,6 +60,8 @@ export const deleteDocumentField = async ({ userId, teamId, fieldId, requestMeta
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.completedAt) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'Document already complete',
@@ -81,6 +84,8 @@ export const deleteDocumentField = async ({ userId, teamId, fieldId, requestMeta
}
return await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
const deletedField = await tx.field.delete({
where: {
id: fieldId,
diff --git a/packages/lib/server-only/field/update-envelope-fields.ts b/packages/lib/server-only/field/update-envelope-fields.ts
index 52ae4fa2a..42d016ca6 100644
--- a/packages/lib/server-only/field/update-envelope-fields.ts
+++ b/packages/lib/server-only/field/update-envelope-fields.ts
@@ -9,6 +9,7 @@ import { AppError, AppErrorCode } from '../../errors/app-error';
import type { EnvelopeIdOptions } from '../../utils/envelope';
import { mapFieldToLegacyField } from '../../utils/fields';
import { canRecipientFieldsBeModified } from '../../utils/recipients';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
export interface UpdateEnvelopeFieldsOptions {
@@ -60,6 +61,8 @@ export const updateEnvelopeFields = async ({
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.completedAt) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'Envelope already complete',
@@ -115,6 +118,8 @@ export const updateEnvelopeFields = async ({
});
const updatedFields = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
return await Promise.all(
fieldsToUpdate.map(async ({ originalField, updateData, recipientEmail }) => {
const updatedField = await tx.field.update({
diff --git a/packages/lib/server-only/license/assert-licensed-for.ts b/packages/lib/server-only/license/assert-licensed-for.ts
new file mode 100644
index 000000000..5da2b12df
--- /dev/null
+++ b/packages/lib/server-only/license/assert-licensed-for.ts
@@ -0,0 +1,69 @@
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import type { LicenseFlag, TCachedLicense } from '../../types/license';
+import { env } from '../../utils/env';
+import { LicenseClient } from './license-client';
+
+type AssertLicensedForOptions = {
+ /**
+ * Override the AppError code thrown when the assertion fails.
+ *
+ * Defaults to `AppErrorCode.FORBIDDEN`. Callers that need a more specific
+ * surface — for example the CSC transport throwing `CSC_UNLICENSED` at
+ * transport-create time — pass their own code here.
+ */
+ errorCode?: string;
+
+ /**
+ * Override the AppError message thrown when the assertion fails.
+ */
+ message?: string;
+};
+
+/**
+ * Assert the configured Documenso licence grants `flag`. Reads the
+ * {@link LicenseClient} cache; never re-pings the licence server.
+ *
+ * - No `NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY` → throws. No licensing intent.
+ * - Key set, claim unverifiable (no client, null cache, read throws,
+ * `license: null`) → passes. Mirrors how org-claim gates keep running on
+ * last known state when the licence server is unreachable; paying
+ * operators shouldn't be locked out by transient infra.
+ * - Key set, claim loaded and denies the flag (bad standing or flag falsy)
+ * → throws.
+ */
+export const assertLicensedFor = async (flag: LicenseFlag, options?: AssertLicensedForOptions): Promise<void> => {
+ const denied = (): AppError =>
+ new AppError(options?.errorCode ?? AppErrorCode.FORBIDDEN, {
+ message: options?.message ?? `License does not include the "${flag}" feature.`,
+ });
+
+ // No licence key configured = no licensing intent. Fail closed unconditionally
+ // so unlicensed instances cannot reach gated features simply because the
+ // licence cache is empty.
+ if (!env('NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY')) {
+ throw denied();
+ }
+
+ let cached: TCachedLicense | null = null;
+
+ const licenseClient = LicenseClient.getInstance();
+
+ if (licenseClient) {
+ cached = await licenseClient?.getCachedLicense().catch(() => null);
+ }
+
+ // Licence key is configured but we have no positively-verified claim to
+ // check. Fail-open — see block comment for the full set of conditions and
+ // rationale.
+ if (!cached?.license) {
+ return;
+ }
+
+ const inGoodStanding = cached.derivedStatus === 'ACTIVE' || cached.derivedStatus === 'PAST_DUE';
+
+ const flagGranted = Boolean(cached.license.flags[flag]);
+
+ if (!inGoodStanding || !flagGranted) {
+ throw denied();
+ }
+};
diff --git a/packages/lib/server-only/recipient/create-envelope-recipients.ts b/packages/lib/server-only/recipient/create-envelope-recipients.ts
index d456b063f..58d5e68bd 100644
--- a/packages/lib/server-only/recipient/create-envelope-recipients.ts
+++ b/packages/lib/server-only/recipient/create-envelope-recipients.ts
@@ -10,7 +10,9 @@ import { EnvelopeType, RecipientRole, SendStatus, SigningStatus } from '@prisma/
import { AppError, AppErrorCode } from '../../errors/app-error';
import type { EnvelopeIdOptions } from '../../utils/envelope';
import { mapRecipientToLegacyRecipient } from '../../utils/recipients';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
+import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
export interface CreateEnvelopeRecipientsOptions {
userId: number;
@@ -63,6 +65,8 @@ export const createEnvelopeRecipients = async ({
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.completedAt) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'Envelope already complete',
@@ -80,12 +84,21 @@ export const createEnvelopeRecipients = async ({
});
}
+ for (const recipient of recipientsToCreate) {
+ assertCompatibleRecipientRole({
+ signatureLevel: envelope.signatureLevel,
+ role: recipient.role,
+ });
+ }
+
const normalizedRecipients = recipientsToCreate.map((recipient) => ({
...recipient,
email: recipient.email.toLowerCase(),
}));
const createdRecipients = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
return await Promise.all(
normalizedRecipients.map(async (recipient) => {
const authOptions = createRecipientAuthOptions({
diff --git a/packages/lib/server-only/recipient/delete-envelope-recipient.ts b/packages/lib/server-only/recipient/delete-envelope-recipient.ts
index 4b31770eb..06d90ca46 100644
--- a/packages/lib/server-only/recipient/delete-envelope-recipient.ts
+++ b/packages/lib/server-only/recipient/delete-envelope-recipient.ts
@@ -16,6 +16,7 @@ import { canRecipientBeModified, isRecipientEmailValidForSending } from '../../u
import { renderEmailWithI18N } from '../../utils/render-email-with-i18n';
import { buildTeamWhereQuery } from '../../utils/teams';
import { getEmailContext } from '../email/get-email-context';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
@@ -72,6 +73,8 @@ export const deleteEnvelopeRecipient = async ({
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.completedAt) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'Document already complete',
@@ -109,6 +112,8 @@ export const deleteEnvelopeRecipient = async ({
});
const deletedRecipient = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
if (envelope.type === EnvelopeType.DOCUMENT) {
await tx.documentAuditLog.create({
data: createDocumentAuditLogData({
diff --git a/packages/lib/server-only/recipient/set-document-recipients.ts b/packages/lib/server-only/recipient/set-document-recipients.ts
index 1bf55c6f8..2e58936ab 100644
--- a/packages/lib/server-only/recipient/set-document-recipients.ts
+++ b/packages/lib/server-only/recipient/set-document-recipients.ts
@@ -22,7 +22,9 @@ import { logger } from '../../utils/logger';
import { canRecipientBeModified, isRecipientEmailValidForSending } from '../../utils/recipients';
import { renderEmailWithI18N } from '../../utils/render-email-with-i18n';
import { getEmailContext } from '../email/get-email-context';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
+import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
export interface SetDocumentRecipientsOptions {
@@ -80,6 +82,8 @@ export const setDocumentRecipients = async ({
throw new Error('Document not found');
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.completedAt) {
throw new Error('Document already complete');
}
@@ -105,6 +109,13 @@ export const setDocumentRecipients = async ({
});
}
+ for (const recipient of recipients) {
+ assertCompatibleRecipientRole({
+ signatureLevel: envelope.signatureLevel,
+ role: recipient.role,
+ });
+ }
+
const normalizedRecipients = recipients.map((recipient) => ({
...recipient,
email: recipient.email.toLowerCase(),
@@ -139,6 +150,8 @@ export const setDocumentRecipients = async ({
});
const persistedRecipients = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
return await Promise.all(
linkedRecipients.map(async (recipient) => {
let authOptions = ZRecipientAuthOptionsSchema.parse(recipient._persisted?.authOptions);
diff --git a/packages/lib/server-only/recipient/set-template-recipients.ts b/packages/lib/server-only/recipient/set-template-recipients.ts
index 22b36a88a..b177f3315 100644
--- a/packages/lib/server-only/recipient/set-template-recipients.ts
+++ b/packages/lib/server-only/recipient/set-template-recipients.ts
@@ -12,6 +12,7 @@ import { nanoid } from '../../universal/id';
import { createRecipientAuthOptions } from '../../utils/document-auth';
import { type EnvelopeIdOptions, mapSecondaryIdToTemplateId } from '../../utils/envelope';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
+import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
export type SetTemplateRecipientsOptions = {
userId: number;
@@ -60,6 +61,13 @@ export const setTemplateRecipients = async ({ userId, teamId, id, recipients }:
});
}
+ for (const recipient of recipients) {
+ assertCompatibleRecipientRole({
+ signatureLevel: envelope.signatureLevel,
+ role: recipient.role,
+ });
+ }
+
const normalizedRecipients = recipients.map((recipient) => {
// Force replace any changes to the name or email of the direct recipient.
if (envelope.directLink && recipient.id === envelope.directLink.directTemplateRecipientId) {
diff --git a/packages/lib/server-only/recipient/update-envelope-recipients.ts b/packages/lib/server-only/recipient/update-envelope-recipients.ts
index d955a9911..553b30543 100644
--- a/packages/lib/server-only/recipient/update-envelope-recipients.ts
+++ b/packages/lib/server-only/recipient/update-envelope-recipients.ts
@@ -12,7 +12,9 @@ import { extractLegacyIds } from '../../universal/id';
import type { EnvelopeIdOptions } from '../../utils/envelope';
import { mapFieldToLegacyField } from '../../utils/fields';
import { canRecipientBeModified } from '../../utils/recipients';
+import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
+import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
export interface UpdateEnvelopeRecipientsOptions {
userId: number;
@@ -67,6 +69,8 @@ export const updateEnvelopeRecipients = async ({
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.completedAt) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'Envelope already complete',
@@ -84,6 +88,17 @@ export const updateEnvelopeRecipients = async ({
});
}
+ for (const recipient of recipients) {
+ if (recipient.role === undefined) {
+ continue;
+ }
+
+ assertCompatibleRecipientRole({
+ signatureLevel: envelope.signatureLevel,
+ role: recipient.role,
+ });
+ }
+
const recipientsToUpdate = recipients.map((recipient) => {
const originalRecipient = envelope.recipients.find((existingRecipient) => existingRecipient.id === recipient.id);
@@ -106,6 +121,8 @@ export const updateEnvelopeRecipients = async ({
});
const updatedRecipients = await prisma.$transaction(async (tx) => {
+ await assertEnvelopeMutable(envelope, tx);
+
return await Promise.all(
recipientsToUpdate.map(async ({ originalRecipient, updateData }) => {
let authOptions = ZRecipientAuthOptionsSchema.parse(originalRecipient.authOptions);
diff --git a/packages/lib/server-only/signature-level/assert-compatible-dictate-next-signer.ts b/packages/lib/server-only/signature-level/assert-compatible-dictate-next-signer.ts
new file mode 100644
index 000000000..0eec04ac2
--- /dev/null
+++ b/packages/lib/server-only/signature-level/assert-compatible-dictate-next-signer.ts
@@ -0,0 +1,35 @@
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { isTspEnvelope } from '../../types/signature-level';
+
+type AssertCompatibleDictateNextSignerOptions = {
+ signatureLevel: string;
+ allowDictateNextSigner: boolean | null | undefined;
+};
+
+/**
+ * Reject `allowDictateNextSigner = true` on AES/QES envelopes.
+ *
+ * The TSP sign path has no nextSigner dictation — `prepareCscRecipientSigning`
+ * doesn't accept one and `executeTspSign` always advances to the strict
+ * SEQUENTIAL next signer. Allowing the flag to persist on a TSP envelope
+ * would advertise a UX feature the sign-time flow silently drops.
+ *
+ * SES envelopes pass through unchanged. A `null` / `undefined` / `false`
+ * value also passes through.
+ */
+export const assertCompatibleDictateNextSigner = ({
+ signatureLevel,
+ allowDictateNextSigner,
+}: AssertCompatibleDictateNextSignerOptions): void => {
+ if (!isTspEnvelope({ signatureLevel })) {
+ return;
+ }
+
+ if (allowDictateNextSigner !== true) {
+ return;
+ }
+
+ throw new AppError(AppErrorCode.INVALID_BODY, {
+ message: `Envelopes signed at '${signatureLevel}' do not support next-signer dictation — the TSP sign path always advances to the strict SEQUENTIAL next recipient.`,
+ });
+};
diff --git a/packages/lib/server-only/signature-level/assert-compatible-recipient-role.ts b/packages/lib/server-only/signature-level/assert-compatible-recipient-role.ts
new file mode 100644
index 000000000..ec84d9906
--- /dev/null
+++ b/packages/lib/server-only/signature-level/assert-compatible-recipient-role.ts
@@ -0,0 +1,33 @@
+import { RecipientRole } from '@prisma/client';
+
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { isTspEnvelope } from '../../types/signature-level';
+
+type AssertCompatibleRecipientRoleOptions = {
+ signatureLevel: string;
+ role: RecipientRole;
+};
+
+/**
+ * Reject `RecipientRole.ASSISTANT` on AES/QES envelopes.
+ *
+ * Assistant recipients pre-fill fields on behalf of downstream signers. The
+ * TSP flow signs each recipient's complete PDF state with their own CSC
+ * credential, so an assistant role has no sign-time identity to bind to and
+ * `prepareCscRecipientSigning` has no handler for it.
+ *
+ * SES envelopes pass through unchanged.
+ */
+export const assertCompatibleRecipientRole = ({ signatureLevel, role }: AssertCompatibleRecipientRoleOptions): void => {
+ if (!isTspEnvelope({ signatureLevel })) {
+ return;
+ }
+
+ if (role === RecipientRole.ASSISTANT) {
+ throw new AppError(AppErrorCode.INVALID_BODY, {
+ message: `Envelopes signed at '${signatureLevel}' do not support the ASSISTANT role — the TSP flow signs each recipient's bytes with their own CSC credential and has no sign-time path for an assistant.`,
+ });
+ }
+
+ return;
+};
diff --git a/packages/lib/server-only/signature-level/assert-compatible-signing-order.ts b/packages/lib/server-only/signature-level/assert-compatible-signing-order.ts
new file mode 100644
index 000000000..c59f29198
--- /dev/null
+++ b/packages/lib/server-only/signature-level/assert-compatible-signing-order.ts
@@ -0,0 +1,41 @@
+import { DocumentSigningOrder } from '@prisma/client';
+
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { isTspEnvelope } from '../../types/signature-level';
+
+type AssertCompatibleSigningOrderOptions = {
+ signatureLevel: string;
+ signingOrder: DocumentSigningOrder | null | undefined;
+};
+
+/**
+ * Reject `signingOrder = PARALLEL` on AES/QES envelopes.
+ *
+ * Parallel signing produces conflicting incremental PDF updates over the
+ * same base state, breaking the per-recipient `/ByteRange` invariant that
+ * lets each TSP signature verify independently. Sequential is the only safe
+ * order for TSP-signed envelopes.
+ *
+ * SES envelopes pass through unchanged — PARALLEL remains the SES default.
+ * A `null` / `undefined` signingOrder also passes through (the create-envelope
+ * caller decides the default).
+ *
+ * Schema-layer guard. {@link sendDocument} re-coerces at distribution time
+ * as a defence-in-depth backstop.
+ */
+export const assertCompatibleSigningOrder = ({
+ signatureLevel,
+ signingOrder,
+}: AssertCompatibleSigningOrderOptions): void => {
+ if (!isTspEnvelope({ signatureLevel })) {
+ return;
+ }
+
+ if (signingOrder !== DocumentSigningOrder.PARALLEL) {
+ return;
+ }
+
+ throw new AppError(AppErrorCode.INVALID_BODY, {
+ message: `Envelopes signed at '${signatureLevel}' require signingOrder=SEQUENTIAL — PARALLEL breaks the per-recipient /ByteRange invariant required for TSP signatures to verify independently.`,
+ });
+};
diff --git a/packages/lib/server-only/signature-level/resolve-signature-level.ts b/packages/lib/server-only/signature-level/resolve-signature-level.ts
new file mode 100644
index 000000000..912876ecc
--- /dev/null
+++ b/packages/lib/server-only/signature-level/resolve-signature-level.ts
@@ -0,0 +1,87 @@
+import { CSC_INSTANCE_SIGNATURE_LEVEL, IS_INSTANCE_CSC_MODE } from '../../constants/app';
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { SignatureLevel, type TSignatureLevel } from '../../types/signature-level';
+
+type ResolveSignatureLevelOptions = {
+ /**
+ * The signature level the caller wants the envelope created at. Optional;
+ * when omitted the resolver returns the instance-mode default (`SES` for
+ * non-CSC instances, `AES` for CSC instances).
+ */
+ requested?: TSignatureLevel;
+
+ /**
+ * When `true`, a conflict between `requested` and the current instance mode
+ * throws `CSC_INSTANCE_MODE_MISMATCH` rather than being silently coerced.
+ * When `false` (default), the resolver coerces incompatible inputs to the
+ * instance default without throwing.
+ *
+ * Omitting `requested` is accepted in both modes — the resolver returns the
+ * instance default rather than throwing.
+ *
+ * Use `strict: true` at call sites that take the level from external input
+ * (e.g. a public API) where silent coercion would mask caller mistakes.
+ */
+ strict?: boolean;
+};
+
+/**
+ * Resolve the signature level for a new envelope.
+ *
+ * Server-only. Reads the `NEXT_PRIVATE_SIGNING_TRANSPORT` env var via
+ * {@link IS_INSTANCE_CSC_MODE} so call sites do not have to thread the
+ * instance mode through their own arguments. On CSC instances the coerced
+ * default also reads {@link CSC_INSTANCE_SIGNATURE_LEVEL} so operators can
+ * pick `AES` (default) or `QES` per their TSP capability.
+ *
+ * Source of truth for the `Envelope.signatureLevel` write at create-time. The
+ * column has no DB default by design — every caller flows through here so the
+ * instance-mode contract is enforced consistently.
+ *
+ * Coerce mode (default, `strict: false`):
+ *
+ * | Instance | requested | Result |
+ * |----------|----------------|-------------------------------------|
+ * | non-CSC | omitted | `SES` |
+ * | non-CSC | `SES` | `SES` |
+ * | non-CSC | `AES` / `QES` | `SES` (coerced) |
+ * | CSC | omitted | `CSC_INSTANCE_SIGNATURE_LEVEL()` |
+ * | CSC | `SES` | `CSC_INSTANCE_SIGNATURE_LEVEL()` |
+ * | CSC | `AES` / `QES` | passes through |
+ *
+ * Strict mode (`strict: true`): same instance defaults for the omitted case,
+ * but any conflict between `requested` and the instance mode throws
+ * `CSC_INSTANCE_MODE_MISMATCH` instead of silently coercing.
+ *
+ * Note: on CSC instances an explicit `AES`/`QES` request always passes
+ * through, even when it disagrees with `CSC_INSTANCE_SIGNATURE_LEVEL`. The
+ * env var sets the *default* legal tier; it doesn't restrict what callers
+ * can ask for. Cert-capability checks live at the TSP boundary.
+ */
+export const resolveSignatureLevel = ({
+ requested,
+ strict = false,
+}: ResolveSignatureLevelOptions = {}): TSignatureLevel => {
+ const isCscInstance = IS_INSTANCE_CSC_MODE();
+ const instanceDefault = isCscInstance ? CSC_INSTANCE_SIGNATURE_LEVEL() : SignatureLevel.SES;
+
+ if (requested === undefined) {
+ return instanceDefault;
+ }
+
+ const isCompatible = isCscInstance ? requested !== SignatureLevel.SES : requested === SignatureLevel.SES;
+
+ if (isCompatible) {
+ return requested;
+ }
+
+ if (strict) {
+ throw new AppError(AppErrorCode.CSC_INSTANCE_MODE_MISMATCH, {
+ message: isCscInstance
+ ? `signatureLevel '${requested}' is not supported on a CSC-mode instance — every recipient must sign through the configured Trust Service Provider.`
+ : `signatureLevel '${requested}' is not supported on a non-CSC instance — only 'SES' is permitted unless the CSC signing transport is configured.`,
+ });
+ }
+
+ return instanceDefault;
+};
diff --git a/packages/lib/server-only/signature-level/resolve-signing-order.ts b/packages/lib/server-only/signature-level/resolve-signing-order.ts
new file mode 100644
index 000000000..2830729dd
--- /dev/null
+++ b/packages/lib/server-only/signature-level/resolve-signing-order.ts
@@ -0,0 +1,36 @@
+import { DocumentSigningOrder } from '@prisma/client';
+
+import { isTspEnvelope } from '../../types/signature-level';
+import { assertCompatibleSigningOrder } from './assert-compatible-signing-order';
+
+type ResolveSigningOrderOptions = {
+ signatureLevel: string;
+ requested?: DocumentSigningOrder | null;
+};
+
+/**
+ * Resolve the persisted `signingOrder` for a new envelope's meta.
+ *
+ * - Explicit `requested` value: validated via
+ * {@link assertCompatibleSigningOrder} (throws on TSP + `PARALLEL`) and
+ * returned as-is.
+ * - Omitted `requested`: returns the level-appropriate default —
+ * `SEQUENTIAL` for AES/QES (the TSP `/ByteRange` invariant requires it),
+ * `PARALLEL` for SES (preserves existing SES default behaviour).
+ *
+ * Use at every create-time call site instead of the bare `|| PARALLEL`
+ * fallback. Mirrors {@link resolveSignatureLevel} in shape — the two pair
+ * up to keep create-time defaulting + TSP-mode coercion uniform.
+ */
+export const resolveSigningOrder = ({
+ signatureLevel,
+ requested,
+}: ResolveSigningOrderOptions): DocumentSigningOrder => {
+ if (requested) {
+ assertCompatibleSigningOrder({ signatureLevel, signingOrder: requested });
+
+ return requested;
+ }
+
+ return isTspEnvelope({ signatureLevel }) ? DocumentSigningOrder.SEQUENTIAL : DocumentSigningOrder.PARALLEL;
+};
diff --git a/packages/lib/server-only/template/create-document-from-direct-template.ts b/packages/lib/server-only/template/create-document-from-direct-template.ts
index 3ae9086a3..f7682d707 100644
--- a/packages/lib/server-only/template/create-document-from-direct-template.ts
+++ b/packages/lib/server-only/template/create-document-from-direct-template.ts
@@ -25,6 +25,7 @@ import type { TRecipientActionAuthTypes } from '../../types/document-auth';
import { DocumentAccessAuth, ZRecipientAuthOptionsSchema } from '../../types/document-auth';
import { extractDerivedDocumentEmailSettings } from '../../types/document-email';
import { ZFieldMetaSchema } from '../../types/field-meta';
+import { ZSignatureLevelSchema } from '../../types/signature-level';
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
import type { ApiRequestMetadata } from '../../universal/extract-request-metadata';
import { getFileServerSide } from '../../universal/upload/get-file.server';
@@ -43,6 +44,7 @@ import { sendDocument } from '../document/send-document';
import { validateFieldAuth } from '../document/validate-field-auth';
import { incrementDocumentId } from '../envelope/increment-id';
import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
+import { resolveSignatureLevel } from '../signature-level/resolve-signature-level';
import { getTeamSettings } from '../team/get-team-settings';
import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
@@ -197,6 +199,17 @@ export const createDocumentFromDirectTemplate = async ({
(recipient) => recipient.id !== directTemplateRecipient.id,
);
+ // Carry the template's level forward, coercing if the instance mode has
+ // changed since the template was created. ZSignatureLevelSchema parses the
+ // free-form TEXT column defensively. Resolved before meta extraction so
+ // signingOrder picks up the TSP-appropriate default + assertion.
+ const signatureLevel = resolveSignatureLevel({
+ requested: ZSignatureLevelSchema.parse(directTemplateEnvelope.signatureLevel),
+ strict: false,
+ });
+
+ const derivedDocumentMeta = extractDerivedDocumentMeta(settings, directTemplateEnvelope.documentMeta, signatureLevel);
+
// The resulting document contains every non-direct template recipient plus the
// direct recipient that is signing now. A recipientCount of 0 means unlimited.
// This mirrors the check in `sendDocument`, but must be done here because this
@@ -211,8 +224,6 @@ export const createDocumentFromDirectTemplate = async ({
});
}
- const derivedDocumentMeta = extractDerivedDocumentMeta(settings, directTemplateEnvelope.documentMeta);
-
// Associate, validate and map to a query every direct template recipient field with the provided fields.
// Only process fields that are either required or have been signed by the user
const fieldsToProcess = directTemplateRecipient.fields.filter((templateField) => {
@@ -352,6 +363,7 @@ export const createDocumentFromDirectTemplate = async ({
secondaryId: incrementedDocumentId.formattedDocumentId,
type: EnvelopeType.DOCUMENT,
internalVersion: directTemplateEnvelope.internalVersion,
+ signatureLevel,
qrToken: prefixedId('qr'),
source: DocumentSource.TEMPLATE_DIRECT_LINK,
templateId: directTemplateEnvelopeLegacyId,
diff --git a/packages/lib/server-only/template/create-document-from-template.ts b/packages/lib/server-only/template/create-document-from-template.ts
index 75c755b50..114a3c2ef 100644
--- a/packages/lib/server-only/template/create-document-from-template.ts
+++ b/packages/lib/server-only/template/create-document-from-template.ts
@@ -33,6 +33,7 @@ import type {
TTextFieldMeta,
} from '../../types/field-meta';
import { ZCheckboxFieldMeta, ZDropdownFieldMeta, ZFieldMetaSchema, ZRadioFieldMeta } from '../../types/field-meta';
+import { ZSignatureLevelSchema } from '../../types/signature-level';
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
import type { ApiRequestMetadata } from '../../universal/extract-request-metadata';
import { getFileServerSide } from '../../universal/upload/get-file.server';
@@ -50,6 +51,7 @@ import { buildTeamWhereQuery } from '../../utils/teams';
import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
import { incrementDocumentId } from '../envelope/increment-id';
import { insertFormValuesInPdf } from '../pdf/insert-form-values-in-pdf';
+import { resolveSignatureLevel } from '../signature-level/resolve-signature-level';
import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
import { getTeamSettings } from '../team/get-team-settings';
import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
@@ -513,23 +515,36 @@ export const createDocumentFromTemplate = async ({
const incrementedDocumentId = await incrementDocumentId();
+ // Carry the template's level forward, coercing if the instance mode has
+ // changed since the template was created. ZSignatureLevelSchema parses the
+ // free-form TEXT column defensively. Resolved before meta extraction so
+ // signingOrder picks up the TSP-appropriate default + assertion.
+ const signatureLevel = resolveSignatureLevel({
+ requested: ZSignatureLevelSchema.parse(template.signatureLevel),
+ strict: false,
+ });
+
const documentMeta = await prisma.documentMeta.create({
- data: extractDerivedDocumentMeta(settings, {
- subject: override?.subject || template.documentMeta?.subject,
- message: override?.message || template.documentMeta?.message,
- timezone: override?.timezone || template.documentMeta?.timezone,
- dateFormat: override?.dateFormat || template.documentMeta?.dateFormat,
- redirectUrl: override?.redirectUrl || template.documentMeta?.redirectUrl,
- distributionMethod: override?.distributionMethod || template.documentMeta?.distributionMethod,
- emailSettings: override?.emailSettings || template.documentMeta?.emailSettings,
- signingOrder: override?.signingOrder || template.documentMeta?.signingOrder,
- language: override?.language || template.documentMeta?.language || settings.documentLanguage,
- typedSignatureEnabled: override?.typedSignatureEnabled ?? template.documentMeta?.typedSignatureEnabled,
- uploadSignatureEnabled: override?.uploadSignatureEnabled ?? template.documentMeta?.uploadSignatureEnabled,
- drawSignatureEnabled: override?.drawSignatureEnabled ?? template.documentMeta?.drawSignatureEnabled,
- allowDictateNextSigner: override?.allowDictateNextSigner ?? template.documentMeta?.allowDictateNextSigner,
- envelopeExpirationPeriod: override?.envelopeExpirationPeriod ?? template.documentMeta?.envelopeExpirationPeriod,
- }),
+ data: extractDerivedDocumentMeta(
+ settings,
+ {
+ subject: override?.subject || template.documentMeta?.subject,
+ message: override?.message || template.documentMeta?.message,
+ timezone: override?.timezone || template.documentMeta?.timezone,
+ dateFormat: override?.dateFormat || template.documentMeta?.dateFormat,
+ redirectUrl: override?.redirectUrl || template.documentMeta?.redirectUrl,
+ distributionMethod: override?.distributionMethod || template.documentMeta?.distributionMethod,
+ emailSettings: override?.emailSettings || template.documentMeta?.emailSettings,
+ signingOrder: override?.signingOrder || template.documentMeta?.signingOrder,
+ language: override?.language || template.documentMeta?.language || settings.documentLanguage,
+ typedSignatureEnabled: override?.typedSignatureEnabled ?? template.documentMeta?.typedSignatureEnabled,
+ uploadSignatureEnabled: override?.uploadSignatureEnabled ?? template.documentMeta?.uploadSignatureEnabled,
+ drawSignatureEnabled: override?.drawSignatureEnabled ?? template.documentMeta?.drawSignatureEnabled,
+ allowDictateNextSigner: override?.allowDictateNextSigner ?? template.documentMeta?.allowDictateNextSigner,
+ envelopeExpirationPeriod: override?.envelopeExpirationPeriod ?? template.documentMeta?.envelopeExpirationPeriod,
+ },
+ signatureLevel,
+ ),
});
const { envelope, createdEnvelope } = await prisma.$transaction(async (tx) => {
@@ -539,6 +554,7 @@ export const createDocumentFromTemplate = async ({
secondaryId: incrementedDocumentId.formattedDocumentId,
type: EnvelopeType.DOCUMENT,
internalVersion: template.internalVersion,
+ signatureLevel,
qrToken: prefixedId('qr'),
source: DocumentSource.TEMPLATE,
externalId: externalId || template.externalId,
diff --git a/packages/lib/types/csc-session.ts b/packages/lib/types/csc-session.ts
new file mode 100644
index 000000000..925ea17f3
--- /dev/null
+++ b/packages/lib/types/csc-session.ts
@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/**
+ * One entry in a CSC sign-time session, pinning the bytes (`documentDataId`)
+ * whose digest (`hashB64`) was captured at prep time for a given envelope
+ * item. The `ordinal` is the position of this entry in the session items array
+ * — it lines up with the position-ordered `signatures/signHash` response per
+ * CSC v1.0.4.0 §11.9.
+ */
+export const ZCscSessionItemSchema = z.object({
+ envelopeItemId: z.string(),
+ documentDataId: z.string(),
+ hashB64: z.string(),
+ ordinal: z.number().int().nonnegative(),
+});
+
+/**
+ * Contract between CSC prep and sign on `CscSession.itemsJson`.
+ *
+ * Built at prep time alongside the captured signedAttrs digests. At sign time
+ * the mutation re-derives each item's digest against the pinned
+ * `documentDataId` bytes and dispatches one batched `signatures/signHash` per
+ * recipient.
+ */
+export const ZCscSessionItemsSchema = z.array(ZCscSessionItemSchema);
+
+export type TCscSessionItem = z.infer<typeof ZCscSessionItemSchema>;
+export type TCscSessionItems = z.infer<typeof ZCscSessionItemsSchema>;
diff --git a/packages/lib/types/document-audit-logs.ts b/packages/lib/types/document-audit-logs.ts
index 9e102ee22..92fa094bd 100644
--- a/packages/lib/types/document-audit-logs.ts
+++ b/packages/lib/types/document-audit-logs.ts
@@ -54,6 +54,13 @@ export const ZDocumentAuditLogTypeSchema = z.enum([
'DOCUMENT_ACCESS_AUTH_2FA_REQUESTED', // When ACCESS AUTH 2FA is requested.
'DOCUMENT_ACCESS_AUTH_2FA_VALIDATED', // When ACCESS AUTH 2FA is successfully validated.
'DOCUMENT_ACCESS_AUTH_2FA_FAILED', // When ACCESS AUTH 2FA validation fails.
+
+ // CSC / TSP signing events.
+ 'DOCUMENT_RECIPIENT_CSC_AUTHENTICATED', // Service-scope OAuth complete; CSC credential persisted.
+ 'DOCUMENT_RECIPIENT_CSC_AUTHENTICATION_FAILED', // Service-scope OAuth completed but TSP returned a blocking error (empty credential list / invalid cert / refused algorithm).
+ 'DOCUMENT_RECIPIENT_CSC_SIGN_REQUESTED', // Recipient clicked Sign; CSC session created with captured per-item hashes.
+ 'DOCUMENT_RECIPIENT_CSC_AUTHORIZED', // Credential-scope OAuth complete; SAD attached to the CSC session.
+ 'DOCUMENT_RECIPIENT_CSC_SIGNED', // TSP returned signatures and they were embedded into the recipient's PDF bytes.
]);
export const ZDocumentAuditLogEmailTypeSchema = z.enum([
@@ -722,6 +729,71 @@ export const ZDocumentAuditLogEventRecipientExpiredSchema = z.object({
}),
});
+/**
+ * Event: Recipient completed CSC service-scope OAuth — credential discovered, certificate persisted.
+ */
+export const ZDocumentAuditLogEventDocumentRecipientCscAuthenticatedSchema = z.object({
+ type: z.literal(DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATED),
+ data: ZBaseRecipientDataSchema.extend({
+ providerId: z.string(),
+ credentialId: z.string(),
+ signatureAlgorithm: z.string(),
+ digestAlgorithm: z.string(),
+ }),
+});
+
+/**
+ * Event: Recipient's CSC service-scope OAuth completed but the TSP returned a blocking error.
+ */
+export const ZDocumentAuditLogEventDocumentRecipientCscAuthenticationFailedSchema = z.object({
+ type: z.literal(DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATION_FAILED),
+ data: ZBaseRecipientDataSchema.extend({
+ providerId: z.string(),
+ reason: z.string(),
+ }),
+});
+
+/**
+ * Event: Recipient initiated TSP signing — CSC session created with per-item hashes.
+ */
+export const ZDocumentAuditLogEventDocumentRecipientCscSignRequestedSchema = z.object({
+ type: z.literal(DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGN_REQUESTED),
+ data: ZBaseRecipientDataSchema.extend({
+ providerId: z.string(),
+ credentialId: z.string(),
+ sessionId: z.string(),
+ numSignatures: z.number(),
+ }),
+});
+
+/**
+ * Event: Recipient completed CSC credential-scope OAuth — SAD attached to session.
+ */
+export const ZDocumentAuditLogEventDocumentRecipientCscAuthorizedSchema = z.object({
+ type: z.literal(DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHORIZED),
+ data: ZBaseRecipientDataSchema.extend({
+ providerId: z.string(),
+ credentialId: z.string(),
+ sessionId: z.string(),
+ sadExpiresAt: z.coerce.date(),
+ }),
+});
+
+/**
+ * Event: TSP returned signatures and they were embedded into the recipient's PDF bytes.
+ */
+export const ZDocumentAuditLogEventDocumentRecipientCscSignedSchema = z.object({
+ type: z.literal(DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGNED),
+ data: ZBaseRecipientDataSchema.extend({
+ providerId: z.string(),
+ credentialId: z.string(),
+ sessionId: z.string(),
+ numItemsSigned: z.number(),
+ signatureAlgorithm: z.string(),
+ digestAlgorithm: z.string(),
+ }),
+});
+
export const ZDocumentAuditLogBaseSchema = z.object({
id: z.string(),
createdAt: z.date(),
@@ -770,6 +842,11 @@ export const ZDocumentAuditLogSchema = ZDocumentAuditLogBaseSchema.and(
ZDocumentAuditLogEventRecipientUpdatedSchema,
ZDocumentAuditLogEventRecipientRemovedSchema,
ZDocumentAuditLogEventRecipientExpiredSchema,
+ ZDocumentAuditLogEventDocumentRecipientCscAuthenticatedSchema,
+ ZDocumentAuditLogEventDocumentRecipientCscAuthenticationFailedSchema,
+ ZDocumentAuditLogEventDocumentRecipientCscSignRequestedSchema,
+ ZDocumentAuditLogEventDocumentRecipientCscAuthorizedSchema,
+ ZDocumentAuditLogEventDocumentRecipientCscSignedSchema,
]),
);
diff --git a/packages/lib/types/license.ts b/packages/lib/types/license.ts
index 15c361fb8..a456e188c 100644
--- a/packages/lib/types/license.ts
+++ b/packages/lib/types/license.ts
@@ -11,6 +11,8 @@ export const ZLicenseClaimSchema = z.object({
hipaa: z.boolean().optional(),
authenticationPortal: z.boolean().optional(),
billing: z.boolean().optional(),
+ instanceCscSigning: z.boolean().optional(),
+ cscQesSigning: z.boolean().optional(),
});
/**
@@ -43,6 +45,13 @@ export type TLicenseClaim = z.infer<typeof ZLicenseClaimSchema>;
export type TLicenseRequest = z.infer<typeof ZLicenseRequestSchema>;
export type TLicenseResponse = z.infer<typeof ZLicenseResponseSchema>;
+/**
+ * String-literal union of every flag the licence server can grant. Adding a
+ * field to `ZLicenseClaimSchema` automatically extends this type so that
+ * `assertLicensedFor(flag)` and similar helpers stay in sync.
+ */
+export type LicenseFlag = keyof TLicenseClaim;
+
/**
* Schema for the cached license data stored in the file.
*/
diff --git a/packages/lib/types/signature-level.ts b/packages/lib/types/signature-level.ts
new file mode 100644
index 000000000..6ad023cb3
--- /dev/null
+++ b/packages/lib/types/signature-level.ts
@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+/**
+ * The cryptographic signature tier an envelope is signed at.
+ *
+ * - `SES` — Simple Electronic Signature; the default Documenso flow signed
+ * with the instance-held certificate.
+ * - `AES` — Advanced Electronic Signature; recipient-bound signing through a
+ * Cloud Signature Consortium (CSC) Trust Service Provider.
+ * - `QES` — Qualified Electronic Signature; the eIDAS-qualified variant of
+ * AES, also recipient-bound through a CSC TSP.
+ *
+ * Stored as free-form TEXT on `Envelope.signatureLevel` so the legal-tier
+ * taxonomy can expand without a DB enum migration. Validation lives here.
+ */
+export const ZSignatureLevelSchema = z.enum(['SES', 'AES', 'QES']);
+
+export const SignatureLevel = ZSignatureLevelSchema.enum;
+
+export type TSignatureLevel = z.infer<typeof ZSignatureLevelSchema>;
+
+/**
+ * Whether an envelope's signature level routes through a Cloud Signature
+ * Consortium Trust Service Provider (`AES` or `QES`). The single branch point
+ * for TSP-vs-SES runtime divergence — seal handler, download endpoint,
+ * completion email, and send-time PDF prep all key off this.
+ *
+ * Accepts a raw `string` because the Prisma column is TEXT; unknown values
+ * are conservatively treated as non-TSP so a malformed row can't accidentally
+ * trigger TSP-only code paths.
+ */
+export const isTspEnvelope = (envelope: { signatureLevel: string }): boolean =>
+ envelope.signatureLevel === SignatureLevel.AES || envelope.signatureLevel === SignatureLevel.QES;
diff --git a/packages/lib/types/subscription.ts b/packages/lib/types/subscription.ts
index 9ce0ea5ef..d25028e10 100644
--- a/packages/lib/types/subscription.ts
+++ b/packages/lib/types/subscription.ts
@@ -51,6 +51,8 @@ export const ZClaimFlagsSchema = z.object({
signingReminders: z.boolean().optional(),
+ cscQesSigning: z.boolean().optional(),
+
/**
* Controls whether an organisation is prevented from sending emails.
*
@@ -128,6 +130,11 @@ export const SUBSCRIPTION_CLAIM_FEATURE_FLAGS: Record<
key: 'signingReminders',
label: 'Signing reminders',
},
+ cscQesSigning: {
+ key: 'cscQesSigning',
+ label: 'QES signing',
+ isEnterprise: true,
+ },
disableEmails: {
key: 'disableEmails',
label: 'Disable emails',
diff --git a/packages/lib/utils/document-audit-logs.ts b/packages/lib/utils/document-audit-logs.ts
index f93376d2f..bcd824433 100644
--- a/packages/lib/utils/document-audit-logs.ts
+++ b/packages/lib/utils/document-audit-logs.ts
@@ -597,6 +597,31 @@ export const formatDocumentAuditLogAction = (i18n: I18n, auditLog: TDocumentAudi
user: message,
};
})
+ .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATED }, () => ({
+ anonymous: msg`Recipient authenticated with the signing provider`,
+ you: msg`You authenticated with the signing provider`,
+ user: msg`${user} authenticated with the signing provider`,
+ }))
+ .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATION_FAILED }, () => ({
+ anonymous: msg`Recipient's signing provider authentication failed`,
+ you: msg`Your signing provider authentication failed`,
+ user: msg`${user}'s signing provider authentication failed`,
+ }))
+ .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGN_REQUESTED }, () => ({
+ anonymous: msg`Recipient requested a remote signature`,
+ you: msg`You requested a remote signature`,
+ user: msg`${user} requested a remote signature`,
+ }))
+ .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHORIZED }, () => ({
+ anonymous: msg`Recipient authorised the remote signature`,
+ you: msg`You authorised the remote signature`,
+ user: msg`${user} authorised the remote signature`,
+ }))
+ .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGNED }, () => ({
+ anonymous: msg`Recipient's remote signature was applied`,
+ you: msg`Your remote signature was applied`,
+ user: msg`${user}'s remote signature was applied`,
+ }))
.exhaustive();
let selectedDescription = description.anonymous;
diff --git a/packages/lib/utils/document.ts b/packages/lib/utils/document.ts
index 7a9e9eb97..ddb5dbdca 100644
--- a/packages/lib/utils/document.ts
+++ b/packages/lib/utils/document.ts
@@ -1,9 +1,11 @@
import type { DocumentMeta, Envelope, OrganisationGlobalSettings, Recipient, Team, User } from '@prisma/client';
-import { DocumentDistributionMethod, DocumentSigningOrder, DocumentStatus } from '@prisma/client';
+import { DocumentDistributionMethod, DocumentStatus } from '@prisma/client';
import { DEFAULT_DOCUMENT_TIME_ZONE } from '../constants/time-zones';
+import { resolveSigningOrder } from '../server-only/signature-level/resolve-signing-order';
import type { TDocumentLite, TDocumentMany } from '../types/document';
import { DEFAULT_DOCUMENT_EMAIL_SETTINGS } from '../types/document-email';
+import { SignatureLevel } from '../types/signature-level';
import { mapSecondaryIdToDocumentId } from './envelope';
import { mapRecipientToLegacyRecipient } from './recipients';
@@ -23,11 +25,17 @@ export const isDocumentCompleted = (document: Pick<Envelope, 'status'> | Documen
*
* @param settings - The merged organisation/team settings.
* @param overrideMeta - The meta to override the settings with.
+ * @param signatureLevel - The envelope's signature level. Optional; defaults
+ * to `SES` for backward compatibility, which preserves the legacy `PARALLEL`
+ * signing-order default. New callers should pass the resolved level so the
+ * TSP envelopes get the `SEQUENTIAL` default + assertion against explicit
+ * `PARALLEL`.
* @returns The derived document meta.
*/
export const extractDerivedDocumentMeta = (
settings: Omit<OrganisationGlobalSettings, 'id'>,
overrideMeta: Partial<DocumentMeta> | undefined | null,
+ signatureLevel: string = SignatureLevel.SES,
) => {
const meta = overrideMeta ?? {};
@@ -41,7 +49,7 @@ export const extractDerivedDocumentMeta = (
subject: meta.subject || null,
redirectUrl: meta.redirectUrl || null,
- signingOrder: meta.signingOrder || DocumentSigningOrder.PARALLEL,
+ signingOrder: resolveSigningOrder({ signatureLevel, requested: meta.signingOrder }),
allowDictateNextSigner: meta.allowDictateNextSigner ?? false,
distributionMethod: meta.distributionMethod || DocumentDistributionMethod.EMAIL, // Todo: Make this a setting.
diff --git a/packages/lib/utils/env.ts b/packages/lib/utils/env.ts
index 9df0a4ee2..a8fbae65f 100644
--- a/packages/lib/utils/env.ts
+++ b/packages/lib/utils/env.ts
@@ -1,5 +1,7 @@
/// <reference types="@documenso/tsconfig/process-env.d.ts" />
+import { AppError, AppErrorCode } from '../errors/app-error';
+
declare global {
interface Window {
__ENV__?: Record<string, string | undefined>;
@@ -20,6 +22,30 @@ export const env = <K extends EnvKey>(variable: K): EnvValue<K> => {
return (typeof process !== 'undefined' ? process?.env?.[variable] : undefined) as EnvValue<K>;
};
+/**
+ * Read an env var and assert it is set and non-empty. Throws `error` when
+ * provided, otherwise an `AppError(MISSING_ENV_VAR)` naming the missing
+ * variable.
+ *
+ * Empty-string is treated as unset — a shell-supplied `FOO=` is functionally
+ * equivalent to omission.
+ */
+export const requireEnv = <K extends EnvKey>(variable: K, error?: Error): NonNullable<EnvValue<K>> => {
+ const value = env(variable);
+
+ if (!value) {
+ throw (
+ error ??
+ new AppError(AppErrorCode.MISSING_ENV_VAR, {
+ message: `Required environment variable "${String(variable)}" is unset.`,
+ })
+ );
+ }
+
+ // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+ return value as NonNullable<EnvValue<K>>;
+};
+
export const createPublicEnv = () => ({
...Object.fromEntries(Object.entries(process.env).filter(([key]) => key.startsWith('NEXT_PUBLIC_'))),
// Derived from the private URL so the public flag cannot drift from the
@@ -27,4 +53,7 @@ export const createPublicEnv = () => ({
// env var with the same name.
// The `? 'true' : 'false'` might seem dumb but it's because we're expecting env var strings.
NEXT_PUBLIC_DOCUMENT_CONVERSION_ENABLED: process.env.NEXT_PRIVATE_DOCUMENT_CONVERSION_URL ? 'true' : 'false',
+ // Derived from the private transport so the client can detect CSC mode for
+ // authoring UI gating without exposing the raw transport value.
+ NEXT_PUBLIC_SIGNING_TRANSPORT_IS_CSC: process.env.NEXT_PRIVATE_SIGNING_TRANSPORT === 'csc' ? 'true' : 'false',
});
diff --git a/packages/prisma/migrations/20260525103410_add_signature_level_and_csc_tables/migration.sql b/packages/prisma/migrations/20260525103410_add_signature_level_and_csc_tables/migration.sql
new file mode 100644
index 000000000..f5b1d7ae7
--- /dev/null
+++ b/packages/prisma/migrations/20260525103410_add_signature_level_and_csc_tables/migration.sql
@@ -0,0 +1,54 @@
+-- AlterTable
+-- Add the column with a temporary DEFAULT so Postgres backfills existing rows
+-- to 'SES' (the only level the instance supported before this migration). The
+-- DEFAULT is then dropped so future INSERTs must specify signatureLevel
+-- explicitly via resolveSignatureLevel — the column carries no DB-level default
+-- by design (see packages/lib/server-only/signature-level/resolve-signature-level.ts).
+ALTER TABLE "Envelope" ADD COLUMN "signatureLevel" TEXT NOT NULL DEFAULT 'SES';
+ALTER TABLE "Envelope" ALTER COLUMN "signatureLevel" DROP DEFAULT;
+
+-- CreateTable
+CREATE TABLE "CscCredential" (
+ "id" TEXT NOT NULL,
+ "providerId" TEXT NOT NULL,
+ "credentialId" TEXT NOT NULL,
+ "certCache" BYTEA,
+ "signatureAlgorithm" TEXT NOT NULL,
+ "keyType" TEXT NOT NULL,
+ "digestAlgorithm" TEXT NOT NULL,
+ "keyLenBits" INTEGER,
+ "signAlgoParams" TEXT,
+ "serviceTokenCiphertext" BYTEA,
+ "serviceTokenExpiresAt" TIMESTAMP(3),
+ "recipientId" INTEGER NOT NULL,
+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updatedAt" TIMESTAMP(3) NOT NULL,
+
+ CONSTRAINT "CscCredential_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "CscSession" (
+ "id" TEXT NOT NULL,
+ "envelopeId" TEXT NOT NULL,
+ "signingTime" TIMESTAMP(3) NOT NULL,
+ "itemsJson" JSONB NOT NULL,
+ "encryptedSad" BYTEA,
+ "sadExpiresAt" TIMESTAMP(3),
+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "recipientId" INTEGER NOT NULL,
+
+ CONSTRAINT "CscSession_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "CscCredential_recipientId_key" ON "CscCredential"("recipientId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "CscSession_recipientId_key" ON "CscSession"("recipientId");
+
+-- AddForeignKey
+ALTER TABLE "CscCredential" ADD CONSTRAINT "CscCredential_recipientId_fkey" FOREIGN KEY ("recipientId") REFERENCES "Recipient"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "CscSession" ADD CONSTRAINT "CscSession_recipientId_fkey" FOREIGN KEY ("recipientId") REFERENCES "Recipient"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/packages/prisma/schema.prisma b/packages/prisma/schema.prisma
index 98cfbcd1d..3e8872e1b 100644
--- a/packages/prisma/schema.prisma
+++ b/packages/prisma/schema.prisma
@@ -429,7 +429,7 @@ enum EnvelopeType {
TEMPLATE
}
-/// @zod.import(["import { ZDocumentAuthOptionsSchema } from '@documenso/lib/types/document-auth';", "import { ZDocumentFormValuesSchema } from '@documenso/lib/types/document-form-values';"])
+/// @zod.import(["import { ZDocumentAuthOptionsSchema } from '@documenso/lib/types/document-auth';", "import { ZDocumentFormValuesSchema } from '@documenso/lib/types/document-form-values';", "import { ZSignatureLevelSchema } from '@documenso/lib/types/signature-level';"])
model Envelope {
id String @id
secondaryId String @unique
@@ -447,6 +447,8 @@ model Envelope {
source DocumentSource
qrToken String? /// @zod.string.describe("The token for viewing the document using the QR code on the certificate.")
+ signatureLevel String /// [SignatureLevel] @zod.custom.use(ZSignatureLevelSchema)
+
internalVersion Int
useLegacyFieldInsertion Boolean @default(false)
@@ -650,6 +652,9 @@ model Recipient {
fields Field[]
signatures Signature[]
+ cscCredential CscCredential?
+ cscSession CscSession?
+
@@index([token])
@@index([email])
@@index([envelopeId])
@@ -717,6 +722,72 @@ model Signature {
@@index([recipientId])
}
+/// Per-recipient cached credential metadata for the configured Cloud Signature
+/// Consortium (CSC) provider. Holds the TSP-validated certificate chain and the
+/// symmetric-encrypted service-scope access token. One row per recipient on a
+/// CSC envelope; absent for SES recipients.
+model CscCredential {
+ id String @id @default(cuid())
+ providerId String
+ credentialId String
+
+ /// TSP-validated certificate chain (length-prefixed). Nullable until the
+ /// service-scope OAuth callback successfully retrieves and validates it.
+ certCache Bytes?
+
+ /// Algorithm metadata derived from the CSC `credentials/info` response.
+ /// Held as flat scalars so each is independently queryable.
+ signatureAlgorithm String
+ keyType String
+ digestAlgorithm String
+ keyLenBits Int?
+ signAlgoParams String?
+
+ /// Service-scope access token, symmetric-encrypted at the application layer
+ /// before persistence. Nullable until the service-scope OAuth callback runs.
+ serviceTokenCiphertext Bytes?
+ serviceTokenExpiresAt DateTime?
+
+ recipientId Int @unique
+ recipient Recipient @relation(fields: [recipientId], references: [id], onDelete: Cascade)
+
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+}
+
+/// Per-recipient transient sign-time state held across the credential-scope
+/// OAuth round-trip. The `recipientId @unique` constraint caps each recipient
+/// to at most one in-flight session — re-clicking Sign UPSERTs the row.
+/// Cleaned up transitively when the Recipient is deleted.
+/// @zod.import(["import { ZCscSessionItemsSchema } from '@documenso/lib/types/csc-session';"])
+model CscSession {
+ id String @id @default(cuid())
+
+ /// Denormalised envelope id for ergonomic lookups. No FK relation — cleanup
+ /// flows through the Recipient cascade.
+ envelopeId String
+
+ /// Pinned at prep time; stable across overlay re-renders so the captured
+ /// signedAttrs digest matches the bytes the TSP signs.
+ signingTime DateTime
+
+ /// Contract between prep and sign: an array of
+ /// `{ envelopeItemId, documentDataId, hashB64, ordinal }` per envelope item.
+ /// `documentDataId` pins the immutable bytes that produced the captured
+ /// digest so sign-time can re-derive the same hash against the same content.
+ itemsJson Json /// [CscSessionItems] @zod.custom.use(ZCscSessionItemsSchema)
+
+ /// Populated by the credential-scope OAuth callback. Both nullable at row
+ /// creation; set together when the SAD is exchanged.
+ encryptedSad Bytes?
+ sadExpiresAt DateTime?
+
+ createdAt DateTime @default(now())
+
+ recipientId Int @unique
+ recipient Recipient @relation(fields: [recipientId], references: [id], onDelete: Cascade)
+}
+
model DocumentShareLink {
id Int @id @default(autoincrement())
email String
diff --git a/packages/prisma/seed/documents.ts b/packages/prisma/seed/documents.ts
index 4010d0a38..a03d05553 100644
--- a/packages/prisma/seed/documents.ts
+++ b/packages/prisma/seed/documents.ts
@@ -14,6 +14,7 @@ import {
FIELD_SIGNATURE_META_DEFAULT_VALUES,
FIELD_TEXT_META_DEFAULT_VALUES,
} from '@documenso/lib/types/field-meta';
+import { SignatureLevel } from '@documenso/lib/types/signature-level';
import { prefixedId } from '@documenso/lib/universal/id';
import type { Team, User } from '@prisma/client';
import { nanoid } from 'nanoid';
@@ -93,6 +94,7 @@ export const seedBlankDocument = async (owner: User, teamId: number, options: Cr
id: prefixedId('envelope'),
secondaryId: documentId.formattedDocumentId,
internalVersion,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
@@ -313,6 +315,7 @@ export const seedDraftDocument = async (
id: prefixedId('envelope'),
secondaryId: documentId.formattedDocumentId,
internalVersion,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
@@ -407,6 +410,7 @@ export const seedPendingDocument = async (
id: prefixedId('envelope'),
secondaryId: documentId.formattedDocumentId,
internalVersion,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
@@ -660,6 +664,7 @@ export const seedCompletedDocument = async (
id: prefixedId('envelope'),
secondaryId: documentId.formattedDocumentId,
internalVersion,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
diff --git a/packages/prisma/seed/initial-seed.ts b/packages/prisma/seed/initial-seed.ts
index d93820ef1..2833b3350 100644
--- a/packages/prisma/seed/initial-seed.ts
+++ b/packages/prisma/seed/initial-seed.ts
@@ -6,6 +6,7 @@ import { FIELD_META_TEST_FIELDS } from '@documenso/app-tests/constants/field-met
import { OVERFLOW_TEST_FIELDS } from '@documenso/app-tests/constants/field-overflow-pdf';
import { isBase64Image } from '@documenso/lib/constants/signatures';
import { incrementDocumentId, incrementTemplateId } from '@documenso/lib/server-only/envelope/increment-id';
+import { SignatureLevel } from '@documenso/lib/types/signature-level';
import { nanoid, prefixedId } from '@documenso/lib/universal/id';
import { DIRECT_TEMPLATE_RECIPIENT_EMAIL, DIRECT_TEMPLATE_RECIPIENT_NAME } from '../../lib/constants/direct-templates';
import { prisma } from '..';
@@ -76,6 +77,7 @@ export const seedDatabase = async () => {
id: prefixedId('envelope'),
secondaryId: documentId.formattedDocumentId,
internalVersion: 1,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
@@ -115,6 +117,7 @@ export const seedDatabase = async () => {
id: prefixedId('envelope'),
secondaryId: documentId.formattedDocumentId,
internalVersion: 1,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
source: DocumentSource.DOCUMENT,
title: `Document ${i}`,
@@ -312,6 +315,7 @@ export const seedAlignmentTestDocument = async ({
id: prefixedId('envelope'),
secondaryId,
internalVersion: 2,
+ signatureLevel: SignatureLevel.SES,
type,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
@@ -474,6 +478,7 @@ export const seedOverflowTestDocument = async ({
id: prefixedId('envelope'),
secondaryId,
internalVersion: 2,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.DOCUMENT,
documentMetaId: documentMeta.id,
source: DocumentSource.DOCUMENT,
diff --git a/packages/prisma/seed/templates.ts b/packages/prisma/seed/templates.ts
index 160b613e0..b72e0a39c 100644
--- a/packages/prisma/seed/templates.ts
+++ b/packages/prisma/seed/templates.ts
@@ -6,6 +6,7 @@ import {
DIRECT_TEMPLATE_RECIPIENT_NAME,
} from '@documenso/lib/constants/direct-templates';
import { incrementTemplateId } from '@documenso/lib/server-only/envelope/increment-id';
+import { SignatureLevel } from '@documenso/lib/types/signature-level';
import { prefixedId } from '@documenso/lib/universal/id';
import { prisma } from '..';
@@ -57,6 +58,7 @@ export const seedBlankTemplate = async (owner: User, teamId: number, options: Cr
id: prefixedId('envelope'),
secondaryId: templateId.formattedTemplateId,
internalVersion: 1,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.TEMPLATE,
title: `[TEST] Template ${key}`,
teamId,
@@ -105,6 +107,7 @@ export const seedTemplate = async (options: SeedTemplateOptions) => {
id: prefixedId('envelope'),
secondaryId: templateId.formattedTemplateId,
internalVersion: options.internalVersion ?? 1,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.TEMPLATE,
title,
envelopeItems: {
@@ -164,6 +167,7 @@ export const seedDirectTemplate = async (options: SeedTemplateOptions) => {
id: prefixedId('envelope'),
secondaryId: templateId.formattedTemplateId,
internalVersion: options.internalVersion ?? 1,
+ signatureLevel: SignatureLevel.SES,
type: EnvelopeType.TEMPLATE,
title,
envelopeItems: {
diff --git a/packages/trpc/server/enterprise-router/csc-sign-envelope.ts b/packages/trpc/server/enterprise-router/csc-sign-envelope.ts
new file mode 100644
index 000000000..ec64796c5
--- /dev/null
+++ b/packages/trpc/server/enterprise-router/csc-sign-envelope.ts
@@ -0,0 +1,43 @@
+import { executeTspSign } from '@documenso/ee/server-only/signing/csc/execute-tsp-sign';
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+
+import { procedure } from '../trpc';
+import { ZCscSignEnvelopeRequestSchema, ZCscSignEnvelopeResponseSchema } from './csc-sign-envelope.types';
+
+/**
+ * Internal mutation that drives the CSC TSP sign-time pipeline.
+ *
+ * `executeTspSign` does the heavy lifting (capture → batched signHash →
+ * embed → tx). This route wraps it in a 15s `Promise.race` so an unresponsive
+ * TSP surfaces as `CSC_TSP_TIMEOUT` instead of hanging the request. The
+ * idle-timer is a soft cap on TSP round-trip latency; the underlying tx
+ * keeps running on the server until it completes or errors.
+ */
+
+const SIGN_TIMEOUT_MS = 15_000;
+
+export const cscSignEnvelopeRoute = procedure
+ .input(ZCscSignEnvelopeRequestSchema)
+ .output(ZCscSignEnvelopeResponseSchema)
+ .mutation(async ({ input, ctx }) => {
+ const result = await Promise.race([
+ executeTspSign({
+ sessionId: input.sessionId,
+ recipientToken: input.recipientToken,
+ requestMetadata: ctx.metadata.requestMetadata,
+ }),
+ new Promise<never>((_, reject) =>
+ setTimeout(
+ () =>
+ reject(
+ new AppError(AppErrorCode.CSC_TSP_TIMEOUT, {
+ message: 'CSC TSP did not respond within 15s.',
+ }),
+ ),
+ SIGN_TIMEOUT_MS,
+ ),
+ ),
+ ]);
+
+ return result;
+ });
diff --git a/packages/trpc/server/enterprise-router/csc-sign-envelope.types.ts b/packages/trpc/server/enterprise-router/csc-sign-envelope.types.ts
new file mode 100644
index 000000000..45f7e72ef
--- /dev/null
+++ b/packages/trpc/server/enterprise-router/csc-sign-envelope.types.ts
@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+export const ZCscSignEnvelopeRequestSchema = z.object({
+ recipientToken: z.string().min(1),
+ sessionId: z.string().min(1),
+});
+
+export const ZCscSignEnvelopeResponseSchema = z.object({
+ outcome: z.enum(['signed', 'already_signed']),
+});
+
+export type TCscSignEnvelopeRequest = z.infer<typeof ZCscSignEnvelopeRequestSchema>;
+export type TCscSignEnvelopeResponse = z.infer<typeof ZCscSignEnvelopeResponseSchema>;
diff --git a/packages/trpc/server/enterprise-router/router.ts b/packages/trpc/server/enterprise-router/router.ts
index 817753b41..81b88fef1 100644
--- a/packages/trpc/server/enterprise-router/router.ts
+++ b/packages/trpc/server/enterprise-router/router.ts
@@ -2,6 +2,7 @@ import { router } from '../trpc';
import { createOrganisationEmailRoute } from './create-organisation-email';
import { createOrganisationEmailDomainRoute } from './create-organisation-email-domain';
import { createSubscriptionRoute } from './create-subscription';
+import { cscSignEnvelopeRoute } from './csc-sign-envelope';
import { declineLinkOrganisationAccountRoute } from './decline-link-organisation-account';
import { deleteOrganisationEmailRoute } from './delete-organisation-email';
import { deleteOrganisationEmailDomainRoute } from './delete-organisation-email-domain';
@@ -55,4 +56,7 @@ export const enterpriseRouter = router({
get: getInvoicesRoute,
},
},
+ csc: {
+ signEnvelope: cscSignEnvelopeRoute,
+ },
});
diff --git a/packages/trpc/server/envelope-router/replace-envelope-item-pdf.ts b/packages/trpc/server/envelope-router/replace-envelope-item-pdf.ts
index 3c19d6532..65c993c56 100644
--- a/packages/trpc/server/envelope-router/replace-envelope-item-pdf.ts
+++ b/packages/trpc/server/envelope-router/replace-envelope-item-pdf.ts
@@ -1,4 +1,5 @@
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { assertEnvelopeMutable } from '@documenso/lib/server-only/envelope/assert-envelope-mutable';
import { getEnvelopeWhereInput } from '@documenso/lib/server-only/envelope/get-envelope-by-id';
import { UNSAFE_replaceEnvelopeItemPdf } from '@documenso/lib/server-only/envelope-item/replace-envelope-item-pdf';
import { getEnvelopeItemPermissions } from '@documenso/lib/utils/envelope';
@@ -59,6 +60,8 @@ export const replaceEnvelopeItemPdfRoute = authenticatedProcedure
});
}
+ assertEnvelopeMutable(envelope);
+
if (envelope.internalVersion !== 2) {
throw new AppError(AppErrorCode.INVALID_REQUEST, {
message: 'PDF replacement is only supported for version 2 envelopes',
diff --git a/packages/trpc/server/recipient-router/router.ts b/packages/trpc/server/recipient-router/router.ts
index 8b846684e..78dab10ab 100644
--- a/packages/trpc/server/recipient-router/router.ts
+++ b/packages/trpc/server/recipient-router/router.ts
@@ -1,3 +1,4 @@
+import { prepareCscRecipientSigning } from '@documenso/ee/server-only/signing/csc/prepare-recipient-signing';
import { completeDocumentWithToken } from '@documenso/lib/server-only/document/complete-document-with-token';
import { rejectDocumentWithToken } from '@documenso/lib/server-only/document/reject-document-with-token';
import { createEnvelopeRecipients } from '@documenso/lib/server-only/recipient/create-envelope-recipients';
@@ -6,6 +7,9 @@ import { getRecipientById } from '@documenso/lib/server-only/recipient/get-recip
import { setDocumentRecipients } from '@documenso/lib/server-only/recipient/set-document-recipients';
import { setTemplateRecipients } from '@documenso/lib/server-only/recipient/set-template-recipients';
import { updateEnvelopeRecipients } from '@documenso/lib/server-only/recipient/update-envelope-recipients';
+import { isTspEnvelope } from '@documenso/lib/types/signature-level';
+import { unsafeBuildEnvelopeIdQuery } from '@documenso/lib/utils/envelope';
+import { prisma } from '@documenso/prisma';
import { EnvelopeType } from '@prisma/client';
import { ZGenericSuccessResponse, ZSuccessResponseSchema } from '../schema';
@@ -13,6 +17,7 @@ import { authenticatedProcedure, procedure, router } from '../trpc';
import { findRecipientSuggestionsRoute } from './find-recipient-suggestions';
import {
ZCompleteDocumentWithTokenMutationSchema,
+ ZCompleteDocumentWithTokenResponseSchema,
ZCreateDocumentRecipientRequestSchema,
ZCreateDocumentRecipientResponseSchema,
ZCreateDocumentRecipientsRequestSchema,
@@ -559,6 +564,7 @@ export const recipientRouter = router({
*/
completeDocumentWithToken: procedure
.input(ZCompleteDocumentWithTokenMutationSchema)
+ .output(ZCompleteDocumentWithTokenResponseSchema)
.mutation(async ({ input, ctx }) => {
const { token, documentId, accessAuthOptions, nextSigner, recipientOverride } = input;
@@ -568,6 +574,25 @@ export const recipientRouter = router({
},
});
+ // Branch on TSP envelopes before any SES side effects: TSP recipients
+ // can't complete via this route — they go through the CSC sync sign
+ // flow (`enterprise.csc.signEnvelope`). This route returns the redirect URL
+ // for the credential-scope OAuth round-trip.
+ const envelope = await prisma.envelope.findFirstOrThrow({
+ where: {
+ ...unsafeBuildEnvelopeIdQuery({ type: 'documentId', id: documentId }, EnvelopeType.DOCUMENT),
+ recipients: { some: { token } },
+ },
+ select: { signatureLevel: true, internalVersion: true },
+ });
+
+ if (isTspEnvelope(envelope)) {
+ return await prepareCscRecipientSigning({
+ recipientToken: token,
+ requestMetadata: ctx.metadata.requestMetadata,
+ });
+ }
+
await completeDocumentWithToken({
token,
id: {
@@ -580,6 +605,8 @@ export const recipientRouter = router({
userId: ctx.user?.id,
requestMetadata: ctx.metadata.requestMetadata,
});
+
+ return { status: 'SIGNED' as const };
}),
/**
diff --git a/packages/trpc/server/recipient-router/schema.ts b/packages/trpc/server/recipient-router/schema.ts
index e785c55da..2834c2a62 100644
--- a/packages/trpc/server/recipient-router/schema.ts
+++ b/packages/trpc/server/recipient-router/schema.ts
@@ -178,6 +178,20 @@ export const ZCompleteDocumentWithTokenMutationSchema = z.object({
export type TCompleteDocumentWithTokenMutationSchema = z.infer<typeof ZCompleteDocumentWithTokenMutationSchema>;
+/**
+ * Discriminated response: SES envelopes return `{ status: 'SIGNED' }` after
+ * the in-place completion; TSP (AES/QES) envelopes return
+ * `{ status: 'REDIRECT', redirectUrl }` pointing at the credential-scope
+ * OAuth authorize endpoint. Frontend callers can branch on `status` —
+ * existing callers ignored the response and remain compatible.
+ */
+export const ZCompleteDocumentWithTokenResponseSchema = z.discriminatedUnion('status', [
+ z.object({ status: z.literal('REDIRECT'), redirectUrl: z.string() }),
+ z.object({ status: z.literal('SIGNED') }),
+]);
+
+export type TCompleteDocumentWithTokenResponseSchema = z.infer<typeof ZCompleteDocumentWithTokenResponseSchema>;
+
export const ZRejectDocumentWithTokenMutationSchema = z.object({
token: z.string(),
documentId: z.number(),
diff --git a/packages/tsconfig/process-env.d.ts b/packages/tsconfig/process-env.d.ts
index 31878ed6d..6757ed47c 100644
--- a/packages/tsconfig/process-env.d.ts
+++ b/packages/tsconfig/process-env.d.ts
@@ -37,7 +37,12 @@ declare namespace NodeJS {
NEXT_PRIVATE_UPLOAD_AZURE_CONTAINER?: string;
NEXT_PRIVATE_UPLOAD_AZURE_ENDPOINT?: string;
- NEXT_PRIVATE_SIGNING_TRANSPORT?: 'local' | 'http' | 'gcloud-hsm';
+ NEXT_PRIVATE_SIGNING_TRANSPORT?: 'local' | 'http' | 'gcloud-hsm' | 'csc';
+ /**
+ * Derived from `NEXT_PRIVATE_SIGNING_TRANSPORT` in `createPublicEnv()`; do
+ * not set manually. Lets the client detect CSC mode for authoring UI gating.
+ */
+ NEXT_PUBLIC_SIGNING_TRANSPORT_IS_CSC?: 'true' | 'false';
NEXT_PRIVATE_SIGNING_PASSPHRASE?: string;
NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH?: string;
NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS?: string;
@@ -49,6 +54,10 @@ declare namespace NodeJS {
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_FILE_PATH?: string;
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTS?: string;
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH?: string;
+ NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL?: string;
+ NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID?: string;
+ NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET?: string;
+ NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL?: 'AES' | 'QES';
NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY?: string;
NEXT_PUBLIC_SIGNING_CONTACT_INFO?: string;
NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER?: string;
diff --git a/turbo.json b/turbo.json
index 8fe691130..c5c0db0f7 100644
--- a/turbo.json
+++ b/turbo.json
@@ -71,6 +71,10 @@
"NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_FILE_PATH",
"NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTS",
"NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH",
+ "NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL",
+ "NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID",
+ "NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET",
+ "NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL",
"NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY",
"NEXT_PUBLIC_SIGNING_CONTACT_INFO",
"NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER",