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.

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);

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>
+  );
+};

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>
+  );
+};

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`;
     }
   };
 

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({

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 }, () => (

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);

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 }, () => (

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>
           )}
 

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 }, () => (