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

Adds Cloud Signature Consortium (CSC) integration for AES/QES signing
against a configured TSP. v1 ships as instance-wide configuration via
environment variables, with per-envelope signature level selection,
license gating, and an OAuth-driven signing flow (capture + FIFO
signers, SAD session, blocking/in-progress recipient pages).

Includes signature level compatibility checks (role, signing order,
dictate next signer), envelope mutability assertions, Prisma migration
for signature level and CSC tables, and docs for the new signing
certificate options.

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;

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.
 

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',
 });