Merge branch 'main' into feature/pdf-placeholder-selection-fields

packages/lib/client-only/cookies.ts

@@ -0,0 +1,17 @@
+/**
+ * Read a cookie value from `document.cookie`.
+ *
+ * Client-side counterpart of `extractCookieFromHeaders`. Only works for cookies that
+ * are not `HttpOnly`, such as the preferred team URL cookie.
+ */
+export const extractCookieFromDocument = (cookieName: string): string | null => {
+  const cookiePairs = document.cookie.split(';');
+
+  const cookie = cookiePairs.find((pair) => pair.trim().startsWith(`${cookieName}=`));
+
+  if (!cookie) {
+    return null;
+  }
+
+  return cookie.split('=')[1].trim();
+};

packages/lib/client-only/create-zip-writer.ts

@@ -0,0 +1,178 @@
+import { Zip, ZipPassThrough } from 'fflate';
+
+export type ZipFileEntry = {
+  /**
+   * The path of the file within the archive. Forward slashes create folders.
+   * Individual path segments should be sanitized with
+   * {@link sanitizeZipPathSegment} when derived from user-controlled values.
+   */
+  filename: string;
+  data: Blob;
+};
+
+/**
+ * Sanitizes a single path segment (folder or file name) for use inside a zip
+ * archive, replacing characters that are path separators or invalid on
+ * Windows extraction.
+ */
+export const sanitizeZipPathSegment = (segment: string): string => {
+  const sanitized = segment
+    .replace(/[\\/:*?"<>|\p{Cc}]/gu, '-')
+    .trim()
+    // Windows cannot extract folders or files ending with a dot.
+    .replace(/\.+$/, '');
+
+  return sanitized || 'untitled';
+};
+
+export type ZipWriter = {
+  /**
+   * Adds a file to the zip stream. Files are written incrementally so the
+   * input blob can be garbage collected once this resolves.
+   */
+  addFile: (entry: ZipFileEntry) => Promise<void>;
+
+  /**
+   * Finishes the zip stream and returns the archive as a blob.
+   */
+  finalize: () => Blob;
+
+  /**
+   * Discards the zip stream and any buffered output.
+   */
+  abort: () => void;
+};
+
+/**
+ * How many bytes of a blob to materialise into the JS heap per read. Blobs
+ * (e.g. fetch responses) can be disk-backed by the browser, it is only
+ * `arrayBuffer()` that forces them into memory, so we read in slices.
+ */
+const READ_SLICE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Once this many bytes of zip output have accumulated in the JS heap they are
+ * coalesced into an intermediate blob. Browsers can page blob storage to disk
+ * under memory pressure, and the final `new Blob(parts)` composes parts by
+ * reference, so this keeps the heap bounded regardless of archive size.
+ */
+const OUTPUT_COALESCE_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Creates an incremental client-side zip writer.
+ *
+ * Files are stored without compression (PDFs are already internally
+ * compressed) and streamed through the archive as they are added, so peak JS
+ * heap usage is bounded by roughly one read slice plus one output buffer
+ * rather than the total size of the archive.
+ */
+export const createZipWriter = (): ZipWriter => {
+  const usedNames = new Set<string>();
+
+  const outputParts: Blob[] = [];
+  let pendingChunks: Uint8Array[] = [];
+  let pendingSize = 0;
+
+  let zipError: Error | null = null;
+
+  const flushPendingChunks = () => {
+    if (pendingChunks.length === 0) {
+      return;
+    }
+
+    outputParts.push(new Blob(pendingChunks));
+    pendingChunks = [];
+    pendingSize = 0;
+  };
+
+  // ZipPassThrough is synchronous (no workers), so output callbacks have
+  // always fired by the time `push`/`end` return.
+  const zipStream = new Zip((error, chunk, isFinal) => {
+    if (error) {
+      zipError = error;
+      return;
+    }
+
+    pendingChunks.push(chunk);
+    pendingSize += chunk.length;
+
+    if (pendingSize >= OUTPUT_COALESCE_BYTES || isFinal) {
+      flushPendingChunks();
+    }
+  });
+
+  /**
+   * Deduplicates filenames case-insensitively (Windows extraction is
+   * case-insensitive) by appending " (n)" before the extension.
+   */
+  const deduplicateFilename = (filename: string) => {
+    const match = filename.match(/^(.*?)(\.[^./]+)?$/);
+
+    const baseName = match?.[1] ?? filename;
+    const extension = match?.[2] ?? '';
+
+    let candidate = filename;
+    let counter = 1;
+
+    while (usedNames.has(candidate.toLowerCase())) {
+      candidate = `${baseName} (${counter})${extension}`;
+      counter += 1;
+    }
+
+    usedNames.add(candidate.toLowerCase());
+
+    return candidate;
+  };
+
+  const addFile = async ({ filename, data }: ZipFileEntry) => {
+    if (zipError) {
+      throw zipError;
+    }
+
+    const file = new ZipPassThrough(deduplicateFilename(filename));
+
+    zipStream.add(file);
+
+    for (let offset = 0; offset < data.size; offset += READ_SLICE_BYTES) {
+      const slice = data.slice(offset, offset + READ_SLICE_BYTES);
+
+      file.push(new Uint8Array(await slice.arrayBuffer()));
+
+      if (zipError) {
+        throw zipError;
+      }
+    }
+
+    file.push(new Uint8Array(0), true);
+
+    if (zipError) {
+      throw zipError;
+    }
+  };
+
+  const finalize = () => {
+    zipStream.end();
+
+    if (zipError) {
+      throw zipError;
+    }
+
+    flushPendingChunks();
+
+    return new Blob(outputParts, { type: 'application/zip' });
+  };
+
+  const abort = () => {
+    zipStream.terminate();
+
+    pendingChunks = [];
+    pendingSize = 0;
+    outputParts.length = 0;
+  };
+
+  return {
+    addFile,
+    finalize,
+    abort,
+  };
+};

packages/lib/client-only/download-pdf.ts

@@ -32,7 +32,11 @@ const versionToFilenameSuffix = (version: DocumentVersion): string => {
   }
 };
 
-export const downloadPDF = async ({ envelopeItem, token, fileName, version = 'signed' }: DownloadPDFProps) => {
+/**
+ * Fetches a PDF for an envelope item and returns it as a blob alongside the
+ * filename it should be saved as. Throws on non-OK responses.
+ */
+export const fetchPDF = async ({ envelopeItem, token, fileName, version = 'signed' }: DownloadPDFProps) => {
   const downloadUrl = getEnvelopeItemPdfUrl({
     type: 'download',
     envelopeItem: envelopeItem,
@@ -40,12 +44,27 @@ export const downloadPDF = async ({ envelopeItem, token, fileName, version = 'si
     version,
   });
 
-  const blob = await fetch(downloadUrl).then(async (res) => await res.blob());
+  const response = await fetch(downloadUrl);
+
+  if (!response.ok) {
+    throw new Error(`Failed to download PDF: ${response.status}`);
+  }
+
+  const blob = await response.blob();
 
   const baseTitle = (fileName ?? 'document').replace(/\.pdf$/, '');
 
-  downloadFile({
+  return {
     filename: `${baseTitle}${versionToFilenameSuffix(version)}`,
+    blob,
+  };
+};
+
+export const downloadPDF = async (options: DownloadPDFProps) => {
+  const { filename, blob } = await fetchPDF(options);
+
+  downloadFile({
+    filename,
     data: blob,
   });
 };

packages/lib/client-only/hooks/use-autosave.ts

@@ -8,7 +8,7 @@ type SaveRequest<T, R> = {
 export const useAutoSave = <T, R = void>(onSave: (data: T) => Promise<R>, options: { delay?: number } = {}) => {
   const { delay = 2000 } = options;
 
-  const saveTimeoutRef = useRef<NodeJS.Timeout>();
+  const saveTimeoutRef = useRef<NodeJS.Timeout | undefined>(undefined);
   const saveQueueRef = useRef<SaveRequest<T, R>[]>([]);
   const isProcessingRef = useRef(false);
 

packages/lib/client-only/hooks/use-child-route-flags.ts

@@ -0,0 +1,55 @@
+import { useMatches } from 'react-router';
+
+/**
+ * The layout treatment a route wants from its parent layout(s).
+ *
+ * - `'settings'` — the full-height unified settings layout: no centered page
+ *   container, a full-width app header, and a viewport-height flex column so the
+ *   settings shell can fill the available space and scroll internally.
+ * - `null` — the default layout (centered `<PageContainer />`, normal flow).
+ */
+export type LayoutMode = 'settings' | null;
+
+/**
+ * Typed route `handle` export. Controls layout rendering.
+ *
+ * - `hideAppHeader` — tells the parent layout to skip rendering `<AppHeader />`.
+ * - `layoutMode` — selects the layout treatment the parent layout(s) apply. See
+ *   {@link LayoutMode}.
+ */
+export type RouteHandle = {
+  hideAppHeader?: boolean;
+  layoutMode?: LayoutMode;
+};
+
+/**
+ * Returns layout flags from the deepest matching route that sets any.
+ * Layouts call this to decide whether to render certain elements.
+ */
+export function useChildRouteFlags(): { hideAppHeader: boolean; layoutMode: LayoutMode } {
+  const matches = useMatches();
+
+  let hideAppHeader = false;
+  let layoutMode: LayoutMode = null;
+
+  // Walk from deepest match backward so the leaf route wins per flag.
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const handle = matches[i].handle;
+
+    if (handle == null || typeof handle !== 'object') {
+      continue;
+    }
+
+    const h = handle as RouteHandle;
+
+    if (layoutMode === null && h.layoutMode) {
+      layoutMode = h.layoutMode;
+    }
+
+    if (!hideAppHeader && h.hideAppHeader) {
+      hideAppHeader = true;
+    }
+  }
+
+  return { hideAppHeader, layoutMode };
+}

packages/lib/client-only/hooks/use-editor-recipients.ts

@@ -7,9 +7,10 @@ import { DocumentSigningOrder, RecipientRole } from '@prisma/client';
 import { useId } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
 import { useForm } from 'react-hook-form';
-import { prop, sortBy } from 'remeda';
 import { z } from 'zod';
 
+import { isCcRecipient, normalizeRecipientSigningOrders, sortRecipientsForSigningOrder } from '../../utils/recipients';
+
 const LocalRecipientSchema = z.object({
   formId: z.string().min(1),
   id: z.number().optional(),
@@ -94,13 +95,13 @@ export const useEditorRecipients = ({ envelope }: EditorRecipientsProps): UseEdi
       name: recipient.name,
       email: recipient.email,
       role: recipient.role,
-      signingOrder: recipient.signingOrder ?? index + 1,
+      signingOrder: isCcRecipient(recipient) ? undefined : (recipient.signingOrder ?? index + 1),
       actionAuth: ZRecipientAuthOptionsSchema.parse(recipient.authOptions)?.actionAuth ?? undefined,
     }));
 
     const signers: TLocalRecipient[] =
       formRecipients.length > 0
-        ? sortBy(formRecipients, [prop('signingOrder'), 'asc'], [prop('id'), 'asc'])
+        ? normalizeRecipientSigningOrders(sortRecipientsForSigningOrder(formRecipients))
         : [
             {
               formId: initialId,

packages/lib/client-only/providers/envelope-editor-provider.tsx

@@ -15,7 +15,7 @@ import { useToast } from '@documenso/ui/primitives/use-toast';
 import { useLingui } from '@lingui/react/macro';
 import { EnvelopeType, Prisma, ReadStatus, SendStatus, SigningStatus } from '@prisma/client';
 import type React from 'react';
-import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { createContext, useCallback, useContext, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { useSearchParams } from 'react-router';
 
 import type { TDocumentEmailSettings } from '../../types/document-email';
@@ -107,7 +107,39 @@ export const EnvelopeEditorProvider = ({
 
   const [_searchParams, setSearchParams] = useSearchParams();
 
-  const [envelope, _setEnvelope] = useState(initialEnvelope);
+  /**
+   * The envelope is kept in a ref-backed external store instead of useState so
+   * that async consumers (debounced autosave callbacks, flushAutosave, resetForms)
+   * can synchronously read the latest value via `getEnvelope`.
+   *
+   * React subscribes to the store through useSyncExternalStore, keeping renders in
+   * sync without maintaining a separate copy of the state.
+   */
+  const envelopeStoreRef = useRef(initialEnvelope);
+  const envelopeStoreSubscribersRef = useRef(new Set<() => void>());
+
+  const subscribeToEnvelopeStore = useCallback((onStoreChange: () => void) => {
+    envelopeStoreSubscribersRef.current.add(onStoreChange);
+
+    return () => {
+      envelopeStoreSubscribersRef.current.delete(onStoreChange);
+    };
+  }, []);
+
+  const getEnvelope = useCallback(() => envelopeStoreRef.current, []);
+
+  const setEnvelope = useCallback((action: React.SetStateAction<TEditorEnvelope>) => {
+    const next = typeof action === 'function' ? action(envelopeStoreRef.current) : action;
+
+    envelopeStoreRef.current = next;
+
+    for (const onStoreChange of envelopeStoreSubscribersRef.current) {
+      onStoreChange();
+    }
+  }, []);
+
+  const envelope = useSyncExternalStore(subscribeToEnvelopeStore, getEnvelope, getEnvelope);
+
   const [autosaveError, setAutosaveError] = useState<boolean>(false);
 
   const isCscMode = IS_INSTANCE_CSC_MODE();
@@ -135,8 +167,6 @@ export const EnvelopeEditorProvider = ({
     };
   }, [isCscMode, providedEditorConfig]);
 
-  const envelopeRef = useRef(initialEnvelope);
-
   const externalFlushCallbacksRef = useRef<Map<string, () => Promise<void>>>(new Map());
   const pendingMutationsRef = useRef<Set<Promise<unknown>>>(new Set());
 
@@ -156,14 +186,6 @@ export const EnvelopeEditorProvider = ({
     });
   }, []);
 
-  const setEnvelope: typeof _setEnvelope = (action) => {
-    _setEnvelope((prev) => {
-      const next = typeof action === 'function' ? action(prev) : action;
-      envelopeRef.current = next;
-      return next;
-    });
-  };
-
   const isEmbedded = editorConfig.embedded !== undefined;
 
   const editorFields = useEditorFields({
@@ -192,16 +214,18 @@ export const EnvelopeEditorProvider = ({
     try {
       let recipients: TEditorEnvelope['recipients'] = [];
 
+      const currentEnvelope = getEnvelope();
+
       if (!isEmbedded) {
         const response = await setRecipientsMutation.mutateAsync({
-          envelopeId: envelope.id,
-          envelopeType: envelope.type,
+          envelopeId: currentEnvelope.id,
+          envelopeType: currentEnvelope.type,
           recipients: localRecipients,
         });
 
         recipients = response.data;
       } else {
-        recipients = mapLocalRecipientsToRecipients({ envelope, localRecipients });
+        recipients = mapLocalRecipientsToRecipients({ envelope: currentEnvelope, localRecipients });
       }
 
       setEnvelope((prev) => ({
@@ -211,9 +235,7 @@ export const EnvelopeEditorProvider = ({
       }));
 
       // Reset the local fields to ensure deleted recipient fields are removed.
-      editorFields.resetForm(
-        envelope.fields.filter((field) => recipients.some((recipient) => recipient.id === field.recipientId)),
-      );
+      editorFields.resetForm(getEnvelope().fields);
 
       setAutosaveError(false);
     } catch (err) {
@@ -248,16 +270,18 @@ export const EnvelopeEditorProvider = ({
     try {
       let fields: TSetEnvelopeFieldsResponse['data'] = [];
 
+      const currentEnvelope = getEnvelope();
+
       if (!isEmbedded) {
         const response = await setFieldsMutation.mutateAsync({
-          envelopeId: envelope.id,
-          envelopeType: envelope.type,
+          envelopeId: currentEnvelope.id,
+          envelopeType: currentEnvelope.type,
           fields: localFields,
         });
 
         fields = response.data;
       } else {
-        fields = mapLocalFieldsToFields({ envelope, localFields });
+        fields = mapLocalFieldsToFields({ envelope: currentEnvelope, localFields });
       }
 
       setEnvelope((prev) => ({
@@ -309,7 +333,7 @@ export const EnvelopeEditorProvider = ({
     try {
       const response = !isEmbedded
         ? await updateEnvelopeMutation.mutateAsync({
-            envelopeId: envelope.id,
+            envelopeId: getEnvelope().id,
             data,
             meta,
           })
@@ -467,12 +491,14 @@ export const EnvelopeEditorProvider = ({
   };
 
   const resetForms = () => {
+    const currentEnvelope = getEnvelope();
+
     editorRecipients.resetForm({
-      recipients: envelopeRef.current.recipients,
-      documentMeta: envelopeRef.current.documentMeta,
+      recipients: currentEnvelope.recipients,
+      documentMeta: currentEnvelope.documentMeta,
     });
 
-    editorFields.resetForm(envelopeRef.current.fields);
+    editorFields.resetForm(currentEnvelope.fields);
   };
 
   const flushAutosave = async (): Promise<TEditorEnvelope> => {
@@ -488,7 +514,7 @@ export const EnvelopeEditorProvider = ({
       await Promise.allSettled(Array.from(pendingMutationsRef.current));
     }
 
-    return envelopeRef.current;
+    return getEnvelope();
   };
 
   return (

packages/lib/constants/app.ts

@@ -6,6 +6,42 @@ export const APP_DOCUMENT_UPLOAD_SIZE_LIMIT = Number(env('NEXT_PUBLIC_DOCUMENT_S
 
 export const NEXT_PUBLIC_WEBAPP_URL = () => env('NEXT_PUBLIC_WEBAPP_URL') ?? 'http://localhost:3000';
 
+/**
+ * The sub-path the app is served under (no trailing slash), e.g. "/ESign".
+ * Returns an empty string when served at root.
+ *
+ * Prefers the explicit NEXT_PUBLIC_BASE_PATH (which is the same value baked
+ * into the Vite/React Router build). Falls back to the pathname of
+ * NEXT_PUBLIC_WEBAPP_URL so the function still works in dev when the env
+ * variable is unset.
+ *
+ * Avoid using this to build URLs, use {@link formatPath} instead. Reserve this
+ * for cases where the raw prefix itself is needed, such as path comparisons.
+ */
+export const getBasePath = (): string => {
+  const explicit = env('NEXT_PUBLIC_BASE_PATH');
+
+  if (explicit) {
+    return explicit.replace(/\/$/, '');
+  }
+
+  try {
+    return new URL(NEXT_PUBLIC_WEBAPP_URL()).pathname.replace(/\/$/, '');
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * Prefix a root-relative path with the app's base path.
+ *
+ * `formatPath('/api/trpc')` -> `/ESign/api/trpc` under sub-path hosting,
+ * `/api/trpc` otherwise.
+ */
+export const formatPath = (path: string): string => {
+  return `${getBasePath()}${path}`;
+};
+
 export const NEXT_PUBLIC_SIGNING_CONTACT_INFO = () =>
   env('NEXT_PUBLIC_SIGNING_CONTACT_INFO') ?? NEXT_PUBLIC_WEBAPP_URL();
 
@@ -17,6 +53,14 @@ export const NEXT_PRIVATE_INTERNAL_WEBAPP_URL = () =>
 
 export const IS_BILLING_ENABLED = () => env('NEXT_PUBLIC_FEATURE_BILLING_ENABLED') === 'true';
 
+/**
+ * Whether this instance is Documenso Cloud (managed SaaS).
+ *
+ * Used so we can show a different UI for Documenso Cloud and self-hosted instances since
+ * there are things like billing, upsells, documenso links, etc that don't make sense for self-hosted instances.
+ */
+export const IS_DOCUMENSO_CLOUD = () => env('NEXT_PUBLIC_IS_DOCUMENSO_CLOUD') === 'true';
+
 export const API_V2_BETA_URL = '/api/v2-beta';
 export const API_V2_URL = '/api/v2';
 
@@ -24,7 +68,20 @@ export const SUPPORT_EMAIL = env('NEXT_PUBLIC_SUPPORT_EMAIL') ?? 'support@docume
 
 export const USE_INTERNAL_URL_BROWSERLESS = () => env('NEXT_PUBLIC_USE_INTERNAL_URL_BROWSERLESS') === 'true';
 
-export const IS_AI_FEATURES_CONFIGURED = () => !!env('GOOGLE_VERTEX_PROJECT_ID') && !!env('GOOGLE_VERTEX_API_KEY');
+/**
+ * Returns whether AI features are configured for this instance.
+ *
+ * Platform-aware:
+ * - On the server, checks the private Vertex credentials are configured.
+ * - On the client, reads the derived public flag injected via `window.__ENV__`.
+ */
+export const IS_AI_FEATURES_CONFIGURED = (): boolean => {
+  if (typeof window === 'undefined') {
+    return !!env('GOOGLE_VERTEX_PROJECT_ID') && !!env('GOOGLE_VERTEX_API_KEY');
+  }
+
+  return env('NEXT_PUBLIC_AI_FEATURES_ENABLED') === 'true';
+};
 
 /**
  * Temporary flag to toggle between Playwright-based and Konva-based PDF generation
@@ -86,3 +143,5 @@ export const CSC_INSTANCE_SIGNATURE_LEVEL = (): TSignatureLevel => {
 
   return value;
 };
+
+export const DOCUMENSO_CLOUD_ENTERPRISE_CTA_URL = 'https://documen.so/enterprise-cta';

packages/lib/constants/cookies.ts

@@ -0,0 +1 @@
+export const PREFERRED_TEAM_URL_COOKIE = 'preferred-team-url';

packages/lib/errors/app-error.ts

@@ -36,6 +36,20 @@ export enum AppErrorCode {
    */
   ENVELOPE_TSP_LOCKED = 'ENVELOPE_TSP_LOCKED',
 
+  /**
+   * A completion request was made for a recipient that has already signed.
+   * Thrown for retried, stale or concurrent duplicate submissions so callers
+   * can resolve them idempotently instead of surfacing an error.
+   */
+  RECIPIENT_ALREADY_SIGNED = 'RECIPIENT_ALREADY_SIGNED',
+
+  /**
+   * A signer recipient does not have a signature field assigned. Thrown when
+   * distributing an envelope or using a direct template where at least one
+   * signer has no signature field.
+   */
+  MISSING_SIGNATURE_FIELD = 'MISSING_SIGNATURE_FIELD',
+
   /**
    * CSC (Cloud Signature Consortium) error codes. See the CSC QES V1 spec
    * for the recovery taxonomy.
@@ -84,6 +98,7 @@ export const genericErrorCodeToTrpcErrorCodeMap: Record<string, { code: string;
   [AppErrorCode.ENVELOPE_CANCELLED]: { code: 'BAD_REQUEST', status: 400 },
   [AppErrorCode.ENVELOPE_LEGACY]: { code: 'BAD_REQUEST', status: 400 },
   [AppErrorCode.ENVELOPE_TSP_LOCKED]: { code: 'BAD_REQUEST', status: 400 },
+  [AppErrorCode.MISSING_SIGNATURE_FIELD]: { 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 },
@@ -291,6 +306,7 @@ export class AppError extends Error {
         AppErrorCode.ENVELOPE_CANCELLED,
         AppErrorCode.ENVELOPE_LEGACY,
         AppErrorCode.ENVELOPE_TSP_LOCKED,
+        AppErrorCode.MISSING_SIGNATURE_FIELD,
         AppErrorCode.CSC_INSTANCE_MODE_MISMATCH,
         AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY,
         AppErrorCode.CSC_CERT_INVALID,

packages/lib/jobs/client.ts

@@ -17,6 +17,7 @@ import { SEND_SIGNING_REJECTION_EMAILS_JOB_DEFINITION } from './definitions/emai
 import { SEND_SIGNING_EMAIL_JOB_DEFINITION } from './definitions/emails/send-signing-email';
 import { SEND_TEAM_DELETED_EMAIL_JOB_DEFINITION } from './definitions/emails/send-team-deleted-email';
 import { ADMIN_DELETE_ORGANISATION_JOB_DEFINITION } from './definitions/internal/admin-delete-organisation';
+import { ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION } from './definitions/internal/alert-organisation-seat-drift';
 import { BACKPORT_SUBSCRIPTION_CLAIM_JOB_DEFINITION } from './definitions/internal/backport-subscription-claims';
 import { BULK_SEND_TEMPLATE_JOB_DEFINITION } from './definitions/internal/bulk-send-template';
 import { CANCEL_ORGANISATION_SUBSCRIPTION_JOB_DEFINITION } from './definitions/internal/cancel-organisation-subscription';
@@ -29,6 +30,7 @@ import { SEAL_DOCUMENT_JOB_DEFINITION } from './definitions/internal/seal-docume
 import { SEAL_DOCUMENT_SWEEP_JOB_DEFINITION } from './definitions/internal/seal-document-sweep';
 import { SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION } from './definitions/internal/send-signing-reminders-sweep';
 import { SYNC_EMAIL_DOMAINS_JOB_DEFINITION } from './definitions/internal/sync-email-domains';
+import { SYNC_ORGANISATION_SEATS_JOB_DEFINITION } from './definitions/internal/sync-organisation-seats';
 
 /**
  * The `as const` assertion is load bearing as it provides the correct level of type inference for
@@ -64,7 +66,9 @@ export const jobsClient = new JobClient([
   CLEANUP_RATE_LIMITS_JOB_DEFINITION,
   SYNC_EMAIL_DOMAINS_JOB_DEFINITION,
   ADMIN_DELETE_ORGANISATION_JOB_DEFINITION,
+  ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION,
   CANCEL_ORGANISATION_SUBSCRIPTION_JOB_DEFINITION,
+  SYNC_ORGANISATION_SEATS_JOB_DEFINITION,
 ] as const);
 
 export const jobs = jobsClient;

packages/lib/jobs/definitions/internal/alert-organisation-seat-drift.handler.ts

@@ -0,0 +1,67 @@
+import { mailer } from '@documenso/email/mailer';
+import { prisma } from '@documenso/prisma';
+import { IS_BILLING_ENABLED, SUPPORT_EMAIL } from '../../../constants/app';
+import { DOCUMENSO_INTERNAL_EMAIL } from '../../../constants/email';
+import type { JobRunIO } from '../../client/_internal/job';
+import type { TAlertOrganisationSeatDriftJobDefinition } from './alert-organisation-seat-drift';
+
+/**
+ * Daily check for organisations whose member count exceeds their paid seat
+ * count (`organisationClaim.memberCount`, where `0` means unlimited).
+ */
+export const run = async ({ io }: { payload: TAlertOrganisationSeatDriftJobDefinition; io: JobRunIO }) => {
+  if (!IS_BILLING_ENABLED()) {
+    return;
+  }
+
+  const organisations = await prisma.organisation.findMany({
+    where: {
+      // Exclude unlimited-seat plans (memberCount === 0).
+      organisationClaim: {
+        memberCount: {
+          not: 0,
+        },
+      },
+    },
+    select: {
+      id: true,
+      name: true,
+      organisationClaim: {
+        select: {
+          memberCount: true,
+        },
+      },
+      _count: {
+        select: {
+          members: true,
+        },
+      },
+    },
+  });
+
+  const driftedOrganisations = organisations.filter(
+    (organisation) =>
+      organisation.organisationClaim !== null &&
+      organisation._count.members > organisation.organisationClaim.memberCount,
+  );
+
+  if (driftedOrganisations.length === 0) {
+    io.logger.info('No organisations exceed their paid seat count');
+
+    return;
+  }
+
+  await mailer.sendMail({
+    to: SUPPORT_EMAIL,
+    from: DOCUMENSO_INTERNAL_EMAIL,
+    subject: `[Billing] ${driftedOrganisations.length} organisation(s) exceed their paid seat count`,
+    text: [
+      `${driftedOrganisations.length} organisation(s) have more members than their paid seat count:`,
+      '',
+      ...driftedOrganisations.map(
+        (organisation) =>
+          `- ${organisation.name} (${organisation.id}): ${organisation._count.members} members vs ${organisation.organisationClaim?.memberCount ?? 0} paid seats`,
+      ),
+    ].join('\n'),
+  });
+};

packages/lib/jobs/definitions/internal/alert-organisation-seat-drift.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+import type { JobDefinition } from '../../client/_internal/job';
+
+const ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_ID = 'internal.alert-organisation-seat-drift';
+
+const ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_SCHEMA = z.object({});
+
+export type TAlertOrganisationSeatDriftJobDefinition = z.infer<
+  typeof ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_SCHEMA
+>;
+
+export const ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION = {
+  id: ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_ID,
+  name: 'Alert Organisation Seat Drift',
+  version: '1.0.0',
+  trigger: {
+    name: ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_ID,
+    schema: ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_SCHEMA,
+    cron: '0 0 * * *', // Once a day at midnight.
+  },
+  handler: async ({ payload, io }) => {
+    const handler = await import('./alert-organisation-seat-drift.handler');
+
+    await handler.run({ payload, io });
+  },
+} as const satisfies JobDefinition<
+  typeof ALERT_ORGANISATION_SEAT_DRIFT_JOB_DEFINITION_ID,
+  TAlertOrganisationSeatDriftJobDefinition
+>;

packages/lib/jobs/definitions/internal/sync-organisation-seats.handler.ts

@@ -0,0 +1,54 @@
+import { syncMemberCountWithStripeSeatPlan } from '@documenso/ee/server-only/stripe/update-subscription-item-quantity';
+import { prisma } from '@documenso/prisma';
+import { SubscriptionStatus } from '@prisma/client';
+import { IS_BILLING_ENABLED } from '../../../constants/app';
+import type { JobRunIO } from '../../client/_internal/job';
+import type { TSyncOrganisationSeatsJobDefinition } from './sync-organisation-seats';
+
+export const run = async ({ payload }: { payload: TSyncOrganisationSeatsJobDefinition; io: JobRunIO }) => {
+  const { organisationId } = payload;
+
+  if (!IS_BILLING_ENABLED()) {
+    return;
+  }
+
+  const organisation = await prisma.organisation.findUnique({
+    where: {
+      id: organisationId,
+    },
+    include: {
+      subscription: true,
+      organisationClaim: true,
+    },
+  });
+
+  if (!organisation || !organisation.subscription) {
+    return;
+  }
+
+  // Skip canceled/terminal subscriptions — Stripe rejects quantity updates on a
+  // canceled subscription. PAST_DUE is still live and a no-proration shrink is
+  // safe, so it's allowed through.
+  if (organisation.subscription.status === SubscriptionStatus.INACTIVE) {
+    return;
+  }
+
+  const memberCount = await prisma.organisationMember.count({
+    where: {
+      organisationId,
+    },
+  });
+
+  // An organisation always retains its owner; guarding zero avoids writing the
+  // unlimited sentinel to the claim.
+  if (memberCount === 0) {
+    return;
+  }
+
+  await syncMemberCountWithStripeSeatPlan(
+    organisation.subscription,
+    organisation.organisationClaim,
+    memberCount,
+    'shrink',
+  );
+};

packages/lib/jobs/definitions/internal/sync-organisation-seats.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+import type { JobDefinition } from '../../client/_internal/job';
+
+const SYNC_ORGANISATION_SEATS_JOB_DEFINITION_ID = 'internal.sync-organisation-seats';
+
+const SYNC_ORGANISATION_SEATS_JOB_DEFINITION_SCHEMA = z.object({
+  organisationId: z.string(),
+});
+
+export type TSyncOrganisationSeatsJobDefinition = z.infer<typeof SYNC_ORGANISATION_SEATS_JOB_DEFINITION_SCHEMA>;
+
+export const SYNC_ORGANISATION_SEATS_JOB_DEFINITION = {
+  id: SYNC_ORGANISATION_SEATS_JOB_DEFINITION_ID,
+  name: 'Sync Organisation Seats',
+  version: '1.0.0',
+  trigger: {
+    name: SYNC_ORGANISATION_SEATS_JOB_DEFINITION_ID,
+    schema: SYNC_ORGANISATION_SEATS_JOB_DEFINITION_SCHEMA,
+  },
+  handler: async ({ payload, io }) => {
+    const handler = await import('./sync-organisation-seats.handler');
+
+    await handler.run({ payload, io });
+  },
+} as const satisfies JobDefinition<
+  typeof SYNC_ORGANISATION_SEATS_JOB_DEFINITION_ID,
+  TSyncOrganisationSeatsJobDefinition
+>;

packages/lib/package.json

@@ -29,6 +29,7 @@
     "@documenso/email": "*",
     "@documenso/prisma": "*",
     "@documenso/signing": "*",
+    "@documenso/skia-canvas": "^3.0.8-documenso.3",
     "@lingui/core": "^5.6.0",
     "@lingui/macro": "^5.6.0",
     "@lingui/react": "^5.6.0",
@@ -64,10 +65,9 @@
     "postcss-selector-parser": "^7.1.4",
     "posthog-js": "^1.297.2",
     "posthog-node": "4.18.0",
-    "react": "^18",
+    "react": "^19.2.7",
     "remeda": "^2.32.0",
     "sharp": "0.34.5",
-    "skia-canvas": "^3.0.8",
     "stripe": "^12.18.0",
     "ts-pattern": "^5.9.0",
     "zod": "^3.25.76"

packages/lib/server-only/admin/admin-global-search.ts

@@ -0,0 +1,372 @@
+import { prisma } from '@documenso/prisma';
+import { EnvelopeType } from '@prisma/client';
+
+export const ADMIN_SEARCH_RESULTS_PER_TYPE = 5;
+
+const MAX_POSTGRES_INT = 2147483647;
+
+const GROUP_ORDER = ['document', 'user', 'organisation', 'team', 'recipient', 'subscription'] as const;
+
+export type AdminGlobalSearchResultType = (typeof GROUP_ORDER)[number];
+
+export type AdminGlobalSearchResult = {
+  label: string;
+  sublabel?: string;
+  path: string;
+  value: string;
+};
+
+export type AdminGlobalSearchGroup = {
+  type: AdminGlobalSearchResultType;
+  results: AdminGlobalSearchResult[];
+};
+
+export type AdminGlobalSearchOptions = {
+  query: string;
+};
+
+type PartialResults = Partial<Record<AdminGlobalSearchResultType, AdminGlobalSearchResult[]>>;
+
+export const adminGlobalSearch = async ({ query }: AdminGlobalSearchOptions): Promise<AdminGlobalSearchGroup[]> => {
+  const trimmedQuery = query.trim();
+
+  if (trimmedQuery.length === 0) {
+    return [];
+  }
+
+  const resultsByType = await resolveSearch(trimmedQuery);
+
+  return GROUP_ORDER.map((type) => ({
+    type,
+    results: (resultsByType[type] ?? []).map((result) => ({
+      ...result,
+      // Append the raw query so cmdk's client-side filter never hides
+      // server-verified results.
+      value: `${result.value} ${trimmedQuery}`,
+    })),
+  })).filter((group) => group.results.length > 0);
+};
+
+const resolveSearch = async (query: string): Promise<PartialResults> => {
+  // Recognized ID prefixes resolve to a single exact lookup.
+  if (query.startsWith('envelope_')) {
+    return { document: await findDocumentsByExactId({ id: query }) };
+  }
+
+  if (query.startsWith('document_')) {
+    return { document: await findDocumentsByExactId({ secondaryId: query }) };
+  }
+
+  if (query.startsWith('org_')) {
+    return { organisation: await findOrganisationsByIdOrUrl(query) };
+  }
+
+  // Bare numbers are treated as verified ID lookups only. Oversized numbers
+  // fall through to text search.
+  const numericId = Number(query);
+
+  if (/^\d+$/.test(query) && numericId <= MAX_POSTGRES_INT) {
+    const [document, user, team, recipient, subscription] = await Promise.all([
+      findDocumentsByExactId({ secondaryId: `document_${numericId}` }),
+      findUsersById(numericId),
+      findTeamsById(numericId),
+      findRecipientsById(numericId),
+      findSubscriptionsById(numericId),
+    ]);
+
+    return { document, user, team, recipient, subscription };
+  }
+
+  // Free text searches all resource types in parallel.
+  const [document, user, organisation, team, recipient, subscription] = await Promise.all([
+    findDocumentsByText(query),
+    findUsersByText(query),
+    findOrganisationsByText(query),
+    findTeamsByText(query),
+    findRecipientsByText(query),
+    findSubscriptionsByText(query),
+  ]);
+
+  return {
+    document,
+    user,
+    organisation,
+    team,
+    recipient,
+    subscription,
+  };
+};
+
+const joinSublabel = (parts: Array<string | null | undefined>) =>
+  parts.filter((part) => part && part.length > 0).join(' · ') || undefined;
+
+// ─── Documents ────────────────────────────────────────────────────────────────
+
+const documentSelect = {
+  id: true,
+  title: true,
+  secondaryId: true,
+  user: { select: { email: true } },
+} as const;
+
+type DocumentRow = {
+  id: string;
+  title: string;
+  secondaryId: string;
+  user: { email: string };
+};
+
+const mapDocument = (envelope: DocumentRow): AdminGlobalSearchResult => ({
+  label: envelope.title,
+  sublabel: joinSublabel([envelope.secondaryId, envelope.user.email]),
+  path: `/admin/documents/${envelope.id}`,
+  value: `document ${envelope.id} ${envelope.secondaryId} ${envelope.title} ${envelope.user.email}`,
+});
+
+const findDocumentsByExactId = async (where: { id: string } | { secondaryId: string }) => {
+  const envelope = await prisma.envelope.findFirst({
+    where: { ...where, type: EnvelopeType.DOCUMENT },
+    select: documentSelect,
+  });
+
+  return envelope ? [mapDocument(envelope)] : [];
+};
+
+const findDocumentsByText = async (query: string) => {
+  const envelopes = await prisma.envelope.findMany({
+    where: {
+      type: EnvelopeType.DOCUMENT,
+      title: { contains: query, mode: 'insensitive' },
+    },
+    orderBy: { createdAt: 'desc' },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: documentSelect,
+  });
+
+  return envelopes.map(mapDocument);
+};
+
+// ─── Users ────────────────────────────────────────────────────────────────────
+
+const userSelect = {
+  id: true,
+  name: true,
+  email: true,
+} as const;
+
+type UserRow = { id: number; name: string | null; email: string };
+
+const mapUser = (user: UserRow): AdminGlobalSearchResult => ({
+  label: user.name || user.email,
+  sublabel: joinSublabel([`#${user.id}`, user.email]),
+  path: `/admin/users/${user.id}`,
+  value: `user ${user.id} ${user.name ?? ''} ${user.email}`,
+});
+
+const findUsersById = async (id: number) => {
+  const user = await prisma.user.findFirst({
+    where: { id },
+    select: userSelect,
+  });
+
+  return user ? [mapUser(user)] : [];
+};
+
+const findUsersByText = async (query: string) => {
+  const users = await prisma.user.findMany({
+    where: {
+      OR: [{ name: { contains: query, mode: 'insensitive' } }, { email: { contains: query, mode: 'insensitive' } }],
+    },
+    orderBy: { id: 'desc' },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: userSelect,
+  });
+
+  return users.map(mapUser);
+};
+
+// ─── Organisations ────────────────────────────────────────────────────────────
+
+const organisationSelect = {
+  id: true,
+  name: true,
+  owner: { select: { email: true } },
+} as const;
+
+type OrganisationRow = { id: string; name: string; owner: { email: string } };
+
+const mapOrganisation = (organisation: OrganisationRow): AdminGlobalSearchResult => ({
+  label: organisation.name,
+  sublabel: joinSublabel([organisation.id, organisation.owner.email]),
+  path: `/admin/organisations/${organisation.id}`,
+  value: `organisation ${organisation.id} ${organisation.name} ${organisation.owner.email}`,
+});
+
+const findOrganisationsByIdOrUrl = async (query: string) => {
+  const organisations = await prisma.organisation.findMany({
+    where: {
+      OR: [{ id: query }, { url: query }],
+    },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: organisationSelect,
+  });
+
+  return organisations.map(mapOrganisation);
+};
+
+const findOrganisationsByText = async (query: string) => {
+  const organisations = await prisma.organisation.findMany({
+    where: {
+      OR: [
+        { name: { contains: query, mode: 'insensitive' } },
+        { url: { contains: query, mode: 'insensitive' } },
+        { customerId: { contains: query, mode: 'insensitive' } },
+        { owner: { email: { contains: query, mode: 'insensitive' } } },
+      ],
+    },
+    orderBy: { createdAt: 'desc' },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: organisationSelect,
+  });
+
+  return organisations.map(mapOrganisation);
+};
+
+// ─── Teams ────────────────────────────────────────────────────────────────────
+
+const teamSelect = {
+  id: true,
+  name: true,
+  url: true,
+  organisation: { select: { name: true } },
+} as const;
+
+type TeamRow = { id: number; name: string; url: string; organisation: { name: string } };
+
+const mapTeam = (team: TeamRow): AdminGlobalSearchResult => ({
+  label: team.name,
+  sublabel: joinSublabel([`#${team.id}`, `/${team.url}`, team.organisation.name]),
+  path: `/admin/teams/${team.id}`,
+  value: `team ${team.id} ${team.name} ${team.url} ${team.organisation.name}`,
+});
+
+const findTeamsById = async (id: number) => {
+  const team = await prisma.team.findFirst({
+    where: { id },
+    select: teamSelect,
+  });
+
+  return team ? [mapTeam(team)] : [];
+};
+
+const findTeamsByText = async (query: string) => {
+  const teams = await prisma.team.findMany({
+    where: {
+      OR: [{ name: { contains: query, mode: 'insensitive' } }, { url: { contains: query, mode: 'insensitive' } }],
+    },
+    orderBy: { createdAt: 'desc' },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: teamSelect,
+  });
+
+  return teams.map(mapTeam);
+};
+
+// ─── Recipients ───────────────────────────────────────────────────────────────
+
+const recipientSelect = {
+  id: true,
+  name: true,
+  email: true,
+  envelope: { select: { id: true, title: true } },
+} as const;
+
+type RecipientRow = {
+  id: number;
+  name: string;
+  email: string;
+  envelope: { id: string; title: string };
+};
+
+const mapRecipient = (recipient: RecipientRow): AdminGlobalSearchResult => ({
+  label: recipient.email,
+  sublabel: joinSublabel([`#${recipient.id}`, recipient.name, recipient.envelope.title]),
+  path: `/admin/documents/${recipient.envelope.id}`,
+  value: `recipient ${recipient.id} ${recipient.name} ${recipient.email} ${recipient.envelope.title}`,
+});
+
+const findRecipientsById = async (id: number) => {
+  const recipient = await prisma.recipient.findFirst({
+    where: {
+      id,
+      envelope: { type: EnvelopeType.DOCUMENT },
+    },
+    select: recipientSelect,
+  });
+
+  return recipient ? [mapRecipient(recipient)] : [];
+};
+
+const findRecipientsByText = async (query: string) => {
+  const recipients = await prisma.recipient.findMany({
+    where: {
+      envelope: { type: EnvelopeType.DOCUMENT },
+      OR: [{ email: { contains: query, mode: 'insensitive' } }, { name: { contains: query, mode: 'insensitive' } }],
+    },
+    orderBy: { id: 'desc' },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: recipientSelect,
+  });
+
+  return recipients.map(mapRecipient);
+};
+
+// ─── Subscriptions ────────────────────────────────────────────────────────────
+
+const subscriptionSelect = {
+  id: true,
+  status: true,
+  planId: true,
+  customerId: true,
+  organisationId: true,
+} as const;
+
+type SubscriptionRow = {
+  id: number;
+  status: string;
+  planId: string;
+  customerId: string;
+  organisationId: string;
+};
+
+const mapSubscription = (subscription: SubscriptionRow): AdminGlobalSearchResult => ({
+  label: `Subscription #${subscription.id}`,
+  sublabel: joinSublabel([subscription.status, subscription.planId]),
+  path: `/admin/organisations/${subscription.organisationId}`,
+  value: `subscription ${subscription.id} ${subscription.planId} ${subscription.customerId}`,
+});
+
+const findSubscriptionsById = async (id: number) => {
+  const subscription = await prisma.subscription.findFirst({
+    where: { id },
+    select: subscriptionSelect,
+  });
+
+  return subscription ? [mapSubscription(subscription)] : [];
+};
+
+const findSubscriptionsByText = async (query: string) => {
+  const subscriptions = await prisma.subscription.findMany({
+    where: {
+      OR: [
+        { planId: { contains: query, mode: 'insensitive' } },
+        { customerId: { contains: query, mode: 'insensitive' } },
+      ],
+    },
+    orderBy: { createdAt: 'desc' },
+    take: ADMIN_SEARCH_RESULTS_PER_TYPE,
+    select: subscriptionSelect,
+  });
+
+  return subscriptions.map(mapSubscription);
+};

packages/lib/server-only/admin/get-documents-stats.ts

@@ -13,7 +13,7 @@ export const getDocumentStats = async () => {
     },
   });
 
-  const stats: Record<Exclude<ExtendedDocumentStatus, 'INBOX'>, number> = {
+  const stats: Record<Exclude<ExtendedDocumentStatus, 'INBOX' | 'EXPIRED'>, number> = {
     [ExtendedDocumentStatus.DRAFT]: 0,
     [ExtendedDocumentStatus.PENDING]: 0,
     [ExtendedDocumentStatus.COMPLETED]: 0,

packages/lib/server-only/ai/pdf-to-images.ts

@@ -1,6 +1,6 @@
+import { Canvas, Image, Path2D } from '@documenso/skia-canvas';
 import pMap from 'p-map';
 import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
-import { Canvas, Image, Path2D } from 'skia-canvas';
 
 // @ts-expect-error napi-rs/canvas satisfies the requirements
 globalThis.Path2D = Path2D;

packages/lib/server-only/document/complete-document-with-token.ts

@@ -80,22 +80,29 @@ export const completeDocumentWithToken = async ({
 
   const legacyDocumentId = mapSecondaryIdToDocumentId(envelope.secondaryId);
 
-  if (envelope.status !== DocumentStatus.PENDING) {
-    throw new Error(`Document ${envelope.id} must be pending`);
-  }
-
   if (envelope.recipients.length === 0) {
     throw new Error(`Document ${envelope.id} has no recipient with token ${token}`);
   }
 
   const [recipient] = envelope.recipients;
 
-  assertRecipientNotExpired(recipient);
-
+  // A retried or duplicate completion request for an already signed
+  // recipient throws a code the router resolves idempotently. This must be
+  // checked before the envelope status guard since the envelope may have
+  // been completed and sealed by the recipient's original request.
   if (recipient.signingStatus === SigningStatus.SIGNED) {
-    throw new Error(`Recipient ${recipient.id} has already signed`);
+    throw new AppError(AppErrorCode.RECIPIENT_ALREADY_SIGNED, {
+      message: `Recipient ${recipient.id} has already signed`,
+      statusCode: 400,
+    });
   }
 
+  if (envelope.status !== DocumentStatus.PENDING) {
+    throw new Error(`Document ${envelope.id} must be pending`);
+  }
+
+  assertRecipientNotExpired(recipient);
+
   if (recipient.signingStatus === SigningStatus.REJECTED) {
     throw new AppError(AppErrorCode.UNKNOWN_ERROR, {
       message: 'Recipient has already rejected the document',
@@ -276,9 +283,15 @@ export const completeDocumentWithToken = async ({
   }
 
   await prisma.$transaction(async (tx) => {
-    await tx.recipient.update({
+    // Conditional update so two concurrent completion requests can't both
+    // proceed: only the request that transitions the recipient to SIGNED
+    // continues, the loser sees a count of 0 and aborts.
+    const { count: updatedRecipientCount } = await tx.recipient.updateMany({
       where: {
         id: recipient.id,
+        signingStatus: {
+          not: SigningStatus.SIGNED,
+        },
       },
       data: {
         signingStatus: SigningStatus.SIGNED,
@@ -288,6 +301,16 @@ export const completeDocumentWithToken = async ({
       },
     });
 
+    // A concurrent request completed the recipient between our initial read
+    // and this transaction. Abort so the winning request handles all side
+    // effects, the router resolves this code idempotently.
+    if (updatedRecipientCount === 0) {
+      throw new AppError(AppErrorCode.RECIPIENT_ALREADY_SIGNED, {
+        message: `Recipient ${recipient.id} has already signed`,
+        statusCode: 400,
+      });
+    }
+
     if (recipientEmail !== recipient.email || recipientName !== recipient.name) {
       await tx.documentAuditLog.create({
         data: createDocumentAuditLogData({

packages/lib/server-only/document/find-documents.ts

@@ -16,6 +16,7 @@ import { match } from 'ts-pattern';
 
 import type { FindResultResponse } from '../../types/search-params';
 import { maskRecipientTokensForDocument } from '../../utils/mask-recipient-tokens-for-document';
+import { hasExpiredRecipient } from '../envelope/query-helpers';
 import { getTeamById } from '../team/get-team';
 
 export type PeriodSelectorValue = '' | '7d' | '14d' | '30d';
@@ -36,6 +37,11 @@ export type FindDocumentsOptions = {
   senderIds?: number[];
   query?: string;
   folderId?: string;
+  /**
+   * When true, restrict results to envelopes with at least one recipient whose signing
+   * link has expired. Orthogonal to `status` — applied additively.
+   */
+  hasExpiredRecipients?: boolean;
   /**
    * When true (default), use a windowed count that caps early for faster pagination.
    * When false, use a full COUNT(*) for exact totals — preferred for external API consumers.
@@ -115,6 +121,7 @@ export const findDocuments = async ({
   senderIds,
   query = '',
   folderId,
+  hasExpiredRecipients,
   useWindowedCount = true,
 }: FindDocumentsOptions) => {
   const user = await prisma.user.findFirstOrThrow({
@@ -199,6 +206,11 @@ export const findDocuments = async ({
       );
     }
 
+    // Expired recipient filter (orthogonal to status, additive)
+    if (hasExpiredRecipients) {
+      qb = qb.where((eb) => hasExpiredRecipient(eb));
+    }
+
     return qb;
   };
 
@@ -305,6 +317,15 @@ export const findDocuments = async ({
             ]),
           ),
       )
+      .with(ExtendedDocumentStatus.EXPIRED, () =>
+        qb.where((eb) =>
+          eb.and([
+            personalDeletedFilter(eb),
+            hasExpiredRecipient(eb),
+            eb.or([eb('Envelope.userId', '=', user.id), recipientExists(eb, user.email)]),
+          ]),
+        ),
+      )
       .exhaustive();
   };
 
@@ -455,6 +476,18 @@ export const findDocuments = async ({
           return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), eb.or(accessBranches)]);
         }),
       )
+      .with(ExtendedDocumentStatus.EXPIRED, () =>
+        qb.where((eb) => {
+          const accessBranches = [eb('Envelope.teamId', '=', teamData.id)];
+
+          if (teamEmail) {
+            accessBranches.push(senderEmailIs(eb, teamEmail));
+            accessBranches.push(recipientExists(eb, teamEmail));
+          }
+
+          return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), hasExpiredRecipient(eb), eb.or(accessBranches)]);
+        }),
+      )
       .exhaustive();
   };
 

packages/lib/server-only/document/get-stats.ts

@@ -8,6 +8,7 @@ import { DateTime } from 'luxon';
 
 import { STATS_COUNT_CAP } from '../../constants/document';
 import { TEAM_DOCUMENT_VISIBILITY_MAP } from '../../constants/teams';
+import { hasExpiredRecipient } from '../envelope/query-helpers';
 import { getTeamById } from '../team/get-team';
 
 // Kysely query builder type for Envelope queries.
@@ -253,6 +254,19 @@ export const getStats = async ({ userId, teamId, period, search = '', folderId,
       return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), eb.or(accessBranches)]);
     });
 
+  // EXPIRED: docs visible to the team/user with at least one expired, unsigned recipient.
+  // Access control mirrors the EXPIRED branch in findDocuments so the count matches the listing.
+  const expiredQuery = buildBaseQuery().where((eb) => {
+    const accessBranches = [eb('Envelope.teamId', '=', team.id)];
+
+    if (teamEmail) {
+      accessBranches.push(senderEmailIs(eb, teamEmail));
+      accessBranches.push(recipientExists(eb, teamEmail));
+    }
+
+    return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), hasExpiredRecipient(eb), eb.or(accessBranches)]);
+  });
+
   // INBOX: non-draft docs where team email is a NOT_SIGNED, non-CC recipient
   // Returns 0 if the team has no team email.
   const inboxQuery = teamEmail
@@ -274,15 +288,17 @@ export const getStats = async ({ userId, teamId, period, search = '', folderId,
 
   // ─── Execute all counts in parallel ──────────────────────────────────
 
-  const [draft, pending, completed, rejected, cancelled, inbox] = await Promise.all([
+  const [draft, pending, completed, rejected, cancelled, expired, inbox] = await Promise.all([
     cappedCount(draftQuery),
     cappedCount(pendingQuery),
     cappedCount(completedQuery),
     cappedCount(rejectedQuery),
     cappedCount(cancelledQuery),
+    cappedCount(expiredQuery),
     inboxQuery ? cappedCount(inboxQuery) : Promise.resolve(0),
   ]);
 
+  // `expired` is intentionally excluded from `all` — it overlaps PENDING.
   const all = Math.min(draft + pending + completed + rejected + cancelled + inbox, STATS_COUNT_CAP);
 
   const stats: Record<ExtendedDocumentStatus, number> = {
@@ -291,6 +307,7 @@ export const getStats = async ({ userId, teamId, period, search = '', folderId,
     [ExtendedDocumentStatus.COMPLETED]: completed,
     [ExtendedDocumentStatus.REJECTED]: rejected,
     [ExtendedDocumentStatus.CANCELLED]: cancelled,
+    [ExtendedDocumentStatus.EXPIRED]: expired,
     [ExtendedDocumentStatus.INBOX]: inbox,
     [ExtendedDocumentStatus.ALL]: all,
   };

packages/lib/server-only/document/send-document.ts

@@ -194,7 +194,7 @@ export const sendDocument = async ({ id, userId, teamId, sendEmail, requestMetad
       .map((r) => (r.name ? `${r.name} (${r.email}, id: ${r.id})` : `${r.email} (id: ${r.id})`))
       .join(', ');
 
-    throw new AppError(AppErrorCode.INVALID_REQUEST, {
+    throw new AppError(AppErrorCode.MISSING_SIGNATURE_FIELD, {
       message: `The following recipients are missing required fields: ${missingRecipientDescriptions}. Signers must have at least one signature field.`,
     });
   }

packages/lib/server-only/envelope/find-envelopes.ts

@@ -7,6 +7,7 @@ import { TEAM_DOCUMENT_VISIBILITY_MAP } from '../../constants/teams';
 import type { FindResultResponse } from '../../types/search-params';
 import { maskRecipientTokensForDocument } from '../../utils/mask-recipient-tokens-for-document';
 import { getTeamById } from '../team/get-team';
+import { hasExpiredRecipient } from './query-helpers';
 
 export type FindEnvelopesOptions = {
   userId: number;
@@ -23,6 +24,11 @@ export type FindEnvelopesOptions = {
   };
   query?: string;
   folderId?: string;
+  /**
+   * When true, restrict results to envelopes with at least one recipient whose signing
+   * link has expired. Orthogonal to `status` — applied additively.
+   */
+  hasExpiredRecipients?: boolean;
   /**
    * When true (default), use a windowed count that caps early for faster pagination.
    * When false, use a full COUNT(*) for exact totals — preferred for external API consumers.
@@ -106,6 +112,7 @@ export const findEnvelopes = async ({
   orderBy,
   query = '',
   folderId,
+  hasExpiredRecipients,
   useWindowedCount = true,
 }: FindEnvelopesOptions) => {
   const user = await prisma.user.findFirstOrThrow({
@@ -182,6 +189,11 @@ export const findEnvelopes = async ({
     );
   }
 
+  // Expired recipient filter (orthogonal to status, additive)
+  if (hasExpiredRecipients) {
+    qb = qb.where((eb) => hasExpiredRecipient(eb));
+  }
+
   // ─── Access control ──────────────────────────────────────────────────
   //
   // An envelope is visible if ANY of:

packages/lib/server-only/envelope/get-envelope-for-direct-template-signing.ts

@@ -5,6 +5,7 @@ import { match } from 'ts-pattern';
 import { AppError, AppErrorCode } from '../../errors/app-error';
 import { DocumentAccessAuth, type TDocumentAuthMethods } from '../../types/document-auth';
 import { extractDocumentAuthMethods } from '../../utils/document-auth';
+import { getRecipientsWithMissingFields } from '../../utils/recipients';
 import { extractFieldAutoInsertValues } from '../document/send-document';
 import { getTeamSettings } from '../team/get-team-settings';
 import type { EnvelopeForSigningResponse } from './get-envelope-for-recipient-signing';
@@ -125,6 +126,17 @@ export const getEnvelopeForDirectTemplateSigning = async ({
     });
   }
 
+  const recipientsWithMissingFields = getRecipientsWithMissingFields(
+    envelope.recipients,
+    envelope.recipients.flatMap((envelopeRecipient) => envelopeRecipient.fields),
+  );
+
+  if (recipientsWithMissingFields.length > 0) {
+    throw new AppError(AppErrorCode.MISSING_SIGNATURE_FIELD, {
+      message: 'One or more signers on this direct template are missing a signature field',
+    });
+  }
+
   const settings = await getTeamSettings({ teamId: envelope.teamId });
 
   const sender = settings.includeSenderDetails

packages/lib/server-only/envelope/get-envelope-for-recipient-signing.ts

@@ -5,7 +5,7 @@ import EnvelopeSchema from '@documenso/prisma/generated/zod/modelSchema/Envelope
 import SignatureSchema from '@documenso/prisma/generated/zod/modelSchema/SignatureSchema';
 import TeamSchema from '@documenso/prisma/generated/zod/modelSchema/TeamSchema';
 import UserSchema from '@documenso/prisma/generated/zod/modelSchema/UserSchema';
-import { DocumentSigningOrder, DocumentStatus, EnvelopeType, SigningStatus } from '@prisma/client';
+import { DocumentSigningOrder, DocumentStatus, EnvelopeType, RecipientRole, SigningStatus } from '@prisma/client';
 import { z } from 'zod';
 
 import { AppError, AppErrorCode } from '../../errors/app-error';
@@ -266,6 +266,11 @@ export const getEnvelopeForRecipientSigning = async ({
 
   if (envelope.documentMeta.signingOrder === DocumentSigningOrder.SEQUENTIAL && currentRecipientIndex !== -1) {
     for (let i = 0; i < currentRecipientIndex; i++) {
+      // CC recipients have no action to take, so they can never block the flow.
+      if (envelope.recipients[i].role === RecipientRole.CC) {
+        continue;
+      }
+
       if (envelope.recipients[i].signingStatus !== SigningStatus.SIGNED) {
         isRecipientsTurn = false;
         break;

packages/lib/server-only/envelope/query-helpers.ts

@@ -0,0 +1,27 @@
+import { sql } from '@documenso/prisma';
+import type { DB } from '@documenso/prisma/generated/types';
+import { RecipientRole, SigningStatus } from '@prisma/client';
+import type { ExpressionBuilder } from 'kysely';
+
+// Expression builder type scoped to the Envelope table context.
+type EnvelopeExpressionBuilder = ExpressionBuilder<DB, 'Envelope'>;
+
+/**
+ * Reusable EXISTS subquery: checks that the envelope has at least one recipient whose
+ * signing link has expired — `expiresAt` in the past, still unsigned, and not a CC.
+ *
+ * This is the single source of truth for the "expired recipient" predicate used by
+ * `findDocuments`, `findEnvelopes`, and `getStats`. It must stay in sync with
+ * `isRecipientExpired` (packages/lib/utils/recipients.ts).
+ */
+export const hasExpiredRecipient = (eb: EnvelopeExpressionBuilder) =>
+  eb.exists(
+    eb
+      .selectFrom('Recipient')
+      .whereRef('Recipient.envelopeId', '=', 'Envelope.id')
+      .where('Recipient.expiresAt', 'is not', null)
+      .where('Recipient.expiresAt', '<=', new Date())
+      .where('Recipient.signingStatus', '=', sql.lit(SigningStatus.NOT_SIGNED))
+      .where('Recipient.role', '!=', sql.lit(RecipientRole.CC))
+      .select(sql.lit(1).as('one')),
+  );

packages/lib/server-only/konva/skia-backend.ts

@@ -2,8 +2,9 @@
  * !: This is a workaround to fix the memory leak in the skia-canvas library.
  * !: Internals are ported from the original `konva/skia-backend.js` file.
  */
+
+import { Canvas, DOMMatrix, Image, Path2D } from '@documenso/skia-canvas';
 import { Konva } from 'konva/lib/_CoreInternals';
-import { Canvas, DOMMatrix, Image, Path2D } from 'skia-canvas';
 
 // @ts-expect-error skia-canvas satisfies the requirements
 global.DOMMatrix = DOMMatrix;
@@ -37,6 +38,6 @@ Konva.Util.createImageElement = () => {
   return node as unknown as HTMLImageElement;
 };
 
-Konva._renderBackend = 'skia-canvas';
+Konva._renderBackend = '@documenso/skia-canvas';
 
 export default Konva;

packages/lib/server-only/organisation/accept-organisation-invitation.ts

@@ -1,7 +1,12 @@
+import {
+  assertMemberCountWithinCap,
+  syncMemberCountWithStripeSeatPlan,
+} from '@documenso/ee/server-only/stripe/update-subscription-item-quantity';
 import { prisma } from '@documenso/prisma';
 import type { OrganisationGroup, OrganisationMemberRole } from '@prisma/client';
-import { OrganisationGroupType, OrganisationMemberInviteStatus } from '@prisma/client';
+import { OrganisationGroupType, OrganisationMemberInviteStatus, SubscriptionStatus } from '@prisma/client';
 
+import { IS_BILLING_ENABLED } from '../../constants/app';
 import { AppError, AppErrorCode } from '../../errors/app-error';
 import { jobs } from '../../jobs/client';
 import { generateDatabaseId } from '../../universal/id';
@@ -22,6 +27,13 @@ export const acceptOrganisationInvitation = async ({ token }: AcceptOrganisation
       organisation: {
         include: {
           groups: true,
+          organisationClaim: true,
+          subscription: true,
+          members: {
+            select: {
+              id: true,
+            },
+          },
         },
       },
     },
@@ -66,6 +78,35 @@ export const acceptOrganisationInvitation = async ({ token }: AcceptOrganisation
     return;
   }
 
+  const newMemberCount = organisation.members.length + 1;
+
+  // Billing occurs when a user accepts an invite.
+  // Assert that the new member count is within the cap and sync the seat plan with Stripe.
+  if (IS_BILLING_ENABLED()) {
+    const { subscription, organisationClaim } = organisation;
+
+    // A canceled subscription cannot have its seat quantity updated in Stripe,
+    // and an organisation with lapsed billing should not gain new members.
+    // Throw a deliberate error so the invite page can render an accurate
+    // message instead of an opaque Stripe failure.
+    if (subscription && subscription.status === SubscriptionStatus.INACTIVE) {
+      throw new AppError('SUBSCRIPTION_INACTIVE', {
+        message: 'The organisation subscription is inactive',
+      });
+    }
+
+    // Organisations can exist without a subscription (e.g. after being
+    // downgraded to the free plan). The claim cap remains authoritative in
+    // that case, surfacing LIMIT_EXCEEDED instead of an opaque "subscription
+    // not found" error.
+    await assertMemberCountWithinCap(subscription, organisationClaim, newMemberCount);
+
+    if (subscription) {
+      await syncMemberCountWithStripeSeatPlan(subscription, organisationClaim, newMemberCount, 'grow');
+    }
+  }
+
+  // Todo: Logging
   await addUserToOrganisation({
     userId: user.id,
     organisationId: organisation.id,

packages/lib/server-only/organisation/create-organisation-member-invites.ts

@@ -1,7 +1,3 @@
-import {
-  assertMemberCountWithinCap,
-  syncMemberCountWithStripeSeatPlan,
-} from '@documenso/ee/server-only/stripe/update-subscription-item-quantity';
 import { OrganisationInviteEmailTemplate } from '@documenso/email/templates/organisation-invite';
 import { NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
 import { ORGANISATION_MEMBER_ROLE_PERMISSIONS_MAP } from '@documenso/lib/constants/organisations';
@@ -17,7 +13,6 @@ import { createElement } from 'react';
 
 import { getI18nInstance } from '../../client-only/providers/i18n-server';
 import { generateDatabaseId } from '../../universal/id';
-import { validateIfSubscriptionIsRequired } from '../../utils/billing';
 import { buildOrganisationWhereQuery } from '../../utils/organisations';
 import { renderEmailWithI18N } from '../../utils/render-email-with-i18n';
 import { getEmailContext } from '../email/get-email-context';
@@ -62,8 +57,6 @@ export const createOrganisationMemberInvites = async ({
         },
       },
       organisationGlobalSettings: true,
-      organisationClaim: true,
-      subscription: true,
     },
   });
 
@@ -71,10 +64,6 @@ export const createOrganisationMemberInvites = async ({
     throw new AppError(AppErrorCode.NOT_FOUND);
   }
 
-  const { organisationClaim } = organisation;
-
-  const subscription = validateIfSubscriptionIsRequired(organisation.subscription);
-
   const currentOrganisationMemberRole = await getMemberOrganisationRole({
     organisationId: organisation.id,
     reference: {
@@ -120,19 +109,6 @@ export const createOrganisationMemberInvites = async ({
     }),
   );
 
-  const numberOfCurrentMembers = organisation.members.length;
-  const numberOfCurrentInvites = organisation.invites.length;
-  const numberOfNewInvites = organisationMemberInvites.length;
-
-  const totalMemberCountWithInvites = numberOfCurrentMembers + numberOfCurrentInvites + numberOfNewInvites;
-
-  // Enforce the seat cap and sync billing for seat based plans.
-  if (subscription) {
-    await assertMemberCountWithinCap(subscription, organisationClaim, totalMemberCountWithInvites);
-
-    await syncMemberCountWithStripeSeatPlan(subscription, organisationClaim, totalMemberCountWithInvites);
-  }
-
   await prisma.organisationMemberInvite.createMany({
     data: organisationMemberInvites,
   });

packages/lib/server-only/pdf/helpers.ts

@@ -1,8 +1,8 @@
 import path from 'node:path';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { FontLibrary } from '@documenso/skia-canvas';
 import type { Recipient } from '@prisma/client';
 import { FieldType } from '@prisma/client';
-import { FontLibrary } from 'skia-canvas';
 import { match } from 'ts-pattern';
 
 /**

packages/lib/server-only/pdf/insert-field-in-pdf-v2.ts

@@ -2,8 +2,8 @@
 import '../konva/skia-backend';
 
 import type { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
+import type { Canvas } from '@documenso/skia-canvas';
 import Konva from 'konva';
-import type { Canvas } from 'skia-canvas';
 
 import { renderField } from '../../universal/field-renderer/render-field';
 import { ensureFontLibrary } from './helpers';

packages/lib/server-only/pdf/render-audit-logs.ts

@@ -1,14 +1,16 @@
+// sort-imports-ignore
+import '../konva/skia-backend';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Canvas } from '@documenso/skia-canvas';
+import { Image as SkiaImage } from '@documenso/skia-canvas';
 import type { I18n } from '@lingui/core';
 import { msg } from '@lingui/core/macro';
 import type { DocumentMeta, Envelope, RecipientRole } from '@prisma/client';
 import Konva from 'konva';
-import 'konva/skia-backend';
-import fs from 'node:fs';
-import path from 'node:path';
 import type { DateTimeFormatOptions } from 'luxon';
 import { DateTime } from 'luxon';
-import type { Canvas } from 'skia-canvas';
-import { Image as SkiaImage } from 'skia-canvas';
 import { match, P } from 'ts-pattern';
 import { UAParser } from 'ua-parser-js';
 

packages/lib/server-only/pdf/render-certificate.ts

@@ -1,14 +1,16 @@
+// sort-imports-ignore
+import '../konva/skia-backend';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Canvas } from '@documenso/skia-canvas';
+import { Image as SkiaImage } from '@documenso/skia-canvas';
 import type { I18n } from '@lingui/core';
 import { msg } from '@lingui/core/macro';
 import type { Field, RecipientRole, Signature } from '@prisma/client';
 import { SigningStatus } from '@prisma/client';
 import Konva from 'konva';
-import 'konva/skia-backend';
-import fs from 'node:fs';
-import path from 'node:path';
 import { DateTime } from 'luxon';
-import type { Canvas } from 'skia-canvas';
-import { Image as SkiaImage } from 'skia-canvas';
 import { UAParser } from 'ua-parser-js';
 import { renderSVG } from 'uqr';
 

packages/lib/server-only/rate-limit/rate-limits.ts

@@ -84,13 +84,13 @@ export const syncSubscriptionRateLimit = createRateLimit({
 
 export const apiV1RateLimit = createRateLimit({
   action: 'api.v1',
-  max: 100,
+  max: 1000,
   window: '1m',
 });
 
 export const apiV2RateLimit = createRateLimit({
   action: 'api.v2',
-  max: 100,
+  max: 1000,
   window: '1m',
 });
 

packages/lib/server-only/recipient/get-is-recipient-turn.ts

@@ -1,5 +1,5 @@
 import { prisma } from '@documenso/prisma';
-import { DocumentSigningOrder, EnvelopeType, SigningStatus } from '@prisma/client';
+import { DocumentSigningOrder, EnvelopeType, RecipientRole, SigningStatus } from '@prisma/client';
 
 export type GetIsRecipientTurnOptions = {
   token: string;
@@ -38,6 +38,11 @@ export async function getIsRecipientsTurnToSign({ token }: GetIsRecipientTurnOpt
   }
 
   for (let i = 0; i < currentRecipientIndex; i++) {
+    // CC recipients have no action to take, so they can never block the flow.
+    if (recipients[i].role === RecipientRole.CC) {
+      continue;
+    }
+
     if (recipients[i].signingStatus !== SigningStatus.SIGNED) {
       return false;
     }

packages/lib/server-only/recipient/get-next-pending-recipient.ts

@@ -1,5 +1,5 @@
 import { prisma } from '@documenso/prisma';
-import { EnvelopeType } from '@prisma/client';
+import { EnvelopeType, RecipientRole } from '@prisma/client';
 
 import { mapDocumentIdToSecondaryId } from '../../utils/envelope';
 
@@ -16,6 +16,11 @@ export const getNextPendingRecipient = async ({
         type: EnvelopeType.DOCUMENT,
         secondaryId: mapDocumentIdToSecondaryId(documentId),
       },
+      // CC recipients are informational only and never take part in signing,
+      // so they must never be offered as the next pending recipient.
+      role: {
+        not: RecipientRole.CC,
+      },
     },
     orderBy: [
       {

packages/lib/server-only/team/get-team-email-by-email.ts

@@ -1,37 +0,0 @@
-import { prisma } from '@documenso/prisma';
-
-import { buildTeamWhereQuery } from '../../utils/teams';
-
-export type GetTeamEmailByEmailOptions = {
-  email: string;
-};
-
-export const getTeamEmailByEmail = async ({ email }: GetTeamEmailByEmailOptions) => {
-  return await prisma.teamEmail.findFirst({
-    where: {
-      email,
-    },
-    include: {
-      team: {
-        select: {
-          id: true,
-          name: true,
-          url: true,
-        },
-      },
-    },
-  });
-};
-
-export const getTeamWithEmail = async ({ userId, teamUrl }: { userId: number; teamUrl: string }) => {
-  return await prisma.team.findFirstOrThrow({
-    where: {
-      ...buildTeamWhereQuery({ teamId: undefined, userId }),
-      url: teamUrl,
-    },
-    include: {
-      teamEmail: true,
-      emailVerification: true,
-    },
-  });
-};

packages/lib/server-only/team/get-teams.ts

@@ -15,12 +15,12 @@ export type GetTeamsOptions = {
 };
 
 export const ZGetTeamsResponseSchema = TeamSchema.extend({
-  teamRole: z.nativeEnum(TeamMemberRole),
+  currentTeamRole: z.nativeEnum(TeamMemberRole),
 }).array();
 
 export type TGetTeamsResponse = z.infer<typeof ZGetTeamsResponseSchema>;
 
-export const getTeams = async ({ userId, teamId }: GetTeamsOptions) => {
+export const getTeams = async ({ userId, teamId }: GetTeamsOptions): Promise<TGetTeamsResponse> => {
   const teams = await prisma.team.findMany({
     where: buildTeamWhereQuery({ teamId, userId }),
     include: {

packages/lib/server-only/template/create-document-from-direct-template.ts

@@ -40,6 +40,7 @@ import {
   extractDocumentAuthMethods,
 } from '../../utils/document-auth';
 import { mapSecondaryIdToTemplateId } from '../../utils/envelope';
+import { getRecipientsWithMissingFields } from '../../utils/recipients';
 import { sendDocument } from '../document/send-document';
 import { validateFieldAuth } from '../document/validate-field-auth';
 import { incrementDocumentId } from '../envelope/increment-id';
@@ -172,6 +173,17 @@ export const createDocumentFromDirectTemplate = async ({
     });
   }
 
+  const recipientsWithMissingFields = getRecipientsWithMissingFields(
+    recipients,
+    recipients.flatMap((recipient) => recipient.fields),
+  );
+
+  if (recipientsWithMissingFields.length > 0) {
+    throw new AppError(AppErrorCode.MISSING_SIGNATURE_FIELD, {
+      message: 'One or more signers on this direct template are missing a signature field',
+    });
+  }
+
   if (directTemplateEnvelope.updatedAt.getTime() !== templateUpdatedAt.getTime()) {
     throw new AppError(AppErrorCode.INVALID_REQUEST, { message: 'Template no longer matches' });
   }

packages/lib/server-only/user/delete-user.ts

@@ -1,6 +1,7 @@
 import { prisma } from '@documenso/prisma';
 
 import { AppError, AppErrorCode } from '../../errors/app-error';
+import { jobs } from '../../jobs/client';
 import { deleteOrganisation } from '../organisation/delete-organisation';
 
 export type DeleteUserOptions = {
@@ -59,6 +60,13 @@ export const deleteUser = async ({ id }: DeleteUserOptions) => {
       })),
     );
 
+  // Organisations the user is a member of (but not owner). Owned organisations
+  // are fully torn down below (including subscription cancellation), so only
+  // these need a seat sync after the user's memberships cascade away.
+  const memberOrganisationIds = user.organisationMember
+    .filter((member) => member.organisation.ownerUserId !== user.id)
+    .map((member) => member.organisationId);
+
   // For organisations the user owns - fully tear them down (orphan envelopes,
   // delete the organisation, and cancel any Stripe subscription). Without this
   // the organisations would only cascade away when the user row is deleted,
@@ -82,9 +90,21 @@ export const deleteUser = async ({ id }: DeleteUserOptions) => {
     }),
   );
 
-  return await prisma.user.delete({
+  const deletedUser = await prisma.user.delete({
     where: {
       id: user.id,
     },
   });
+
+  // The user's memberships were cascade-deleted with the user row — queue a
+  // seat sync for each organisation they belonged to so the Stripe quantity
+  // trues down to the new member count (no proration, no credit).
+  for (const organisationId of memberOrganisationIds) {
+    await jobs.triggerJob({
+      name: 'internal.sync-organisation-seats',
+      payload: { organisationId },
+    });
+  }
+
+  return deletedUser;
 };

packages/lib/server-only/user/verify-email.ts

@@ -3,6 +3,7 @@ import { DateTime } from 'luxon';
 
 import { EMAIL_VERIFICATION_STATE, USER_SIGNUP_VERIFICATION_TOKEN_IDENTIFIER } from '../../constants/email';
 import { jobsClient } from '../../jobs/client';
+import { getMostRecentEmailVerificationToken } from './get-most-recent-email-verification-token';
 
 export type VerifyEmailProps = {
   token: string;
@@ -36,13 +37,8 @@ export const verifyEmail = async ({ token }: VerifyEmailProps) => {
   const valid = verificationToken.expires > new Date();
 
   if (!valid) {
-    const mostRecentToken = await prisma.verificationToken.findFirst({
-      where: {
-        userId: verificationToken.userId,
-      },
-      orderBy: {
-        createdAt: 'desc',
-      },
+    const mostRecentToken = await getMostRecentEmailVerificationToken({
+      userId: verificationToken.userId,
     });
 
     // If there isn't a recent token or it's older than 1 hour, send a new token
@@ -80,6 +76,7 @@ export const verifyEmail = async ({ token }: VerifyEmailProps) => {
     prisma.verificationToken.updateMany({
       where: {
         userId: verificationToken.userId,
+        identifier: USER_SIGNUP_VERIFICATION_TOKEN_IDENTIFIER,
       },
       data: {
         completed: true,
@@ -89,6 +86,7 @@ export const verifyEmail = async ({ token }: VerifyEmailProps) => {
     prisma.verificationToken.deleteMany({
       where: {
         userId: verificationToken.userId,
+        identifier: USER_SIGNUP_VERIFICATION_TOKEN_IDENTIFIER,
         expires: {
           lt: new Date(),
         },

packages/lib/server-only/webhooks/get-webhooks-by-team-id.ts

@@ -1,24 +1,26 @@
 import { prisma } from '@documenso/prisma';
+import { TEAM_MEMBER_ROLE_PERMISSIONS_MAP } from '../../constants/teams';
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { buildTeamWhereQuery } from '../../utils/teams';
 
 export const getWebhooksByTeamId = async (teamId: number, userId: number) => {
+  const team = await prisma.team.findFirst({
+    where: buildTeamWhereQuery({
+      teamId,
+      userId,
+      roles: TEAM_MEMBER_ROLE_PERMISSIONS_MAP['MANAGE_TEAM'],
+    }),
+  });
+
+  if (!team) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Team not found',
+    });
+  }
+
   return await prisma.webhook.findMany({
     where: {
-      team: {
-        id: teamId,
-        teamGroups: {
-          some: {
-            organisationGroup: {
-              organisationGroupMembers: {
-                some: {
-                  organisationMember: {
-                    userId,
-                  },
-                },
-              },
-            },
-          },
-        },
-      },
+      teamId,
     },
     orderBy: {
       createdAt: 'desc',

packages/lib/universal/field-renderer/render-signature-field.ts

@@ -14,7 +14,7 @@ let SkiaImage: any;
 
 void (async () => {
   if (typeof window === 'undefined') {
-    const mod = await import('skia-canvas');
+    const mod = await import('@documenso/skia-canvas');
     SkiaImage = mod.Image;
   }
 })();

packages/lib/universal/get-base-url.ts

@@ -1,10 +1,10 @@
 /* eslint-disable turbo/no-undeclared-env-vars */
-import { NEXT_PUBLIC_WEBAPP_URL } from '../constants/app';
+import { NEXT_PUBLIC_WEBAPP_URL, getBasePath } from '../constants/app';
 import { env } from '../utils/env';
 
 export const getBaseUrl = () => {
   if (typeof window !== 'undefined') {
-    return '';
+    return getBasePath();
   }
 
   const webAppUrl = NEXT_PUBLIC_WEBAPP_URL();

packages/lib/universal/upload/get-file.ts

@@ -2,6 +2,8 @@ import { DocumentDataType } from '@prisma/client';
 import { base64 } from '@scure/base';
 import { match } from 'ts-pattern';
 
+import { formatPath } from '../../constants/app';
+
 export type GetFileOptions = {
   type: DocumentDataType;
   data: string;
@@ -36,7 +38,7 @@ const getFileFromBytes64 = (data: string) => {
 };
 
 const getFileFromS3 = async (key: string) => {
-  const getPresignedUrlResponse = await fetch(`/api/files/presigned-get-url`, {
+  const getPresignedUrlResponse = await fetch(formatPath('/api/files/presigned-get-url'), {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',

packages/lib/universal/upload/put-file.ts

@@ -1,5 +1,6 @@
 import type { TUploadPdfResponse } from '@documenso/remix/server/api/files/files.types';
 
+import { formatPath } from '../../constants/app';
 import { AppError } from '../../errors/app-error';
 
 type File = {
@@ -38,7 +39,7 @@ export const putPdfFile = async (file: File, options?: PutFileOptions) => {
 
   formData.append('file', properFile);
 
-  const response = await fetch('/api/files/upload-pdf', {
+  const response = await fetch(formatPath('/api/files/upload-pdf'), {
     method: 'POST',
     headers: buildUploadAuthHeaders(options),
     body: formData,

packages/lib/utils/env.ts

@@ -56,4 +56,8 @@ export const createPublicEnv = () => ({
   // 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',
+  // Derived from the private Vertex credentials so the client can gate AI
+  // feature UI on a boolean.
+  NEXT_PUBLIC_AI_FEATURES_ENABLED:
+    process.env.GOOGLE_VERTEX_PROJECT_ID && process.env.GOOGLE_VERTEX_API_KEY ? 'true' : 'false',
 });

packages/lib/utils/is-valid-return-to.ts

@@ -1,4 +1,15 @@
-import { NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
+import { getBasePath, NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
+
+/**
+ * The origin of the web app, ignoring any sub-path NEXT_PUBLIC_WEBAPP_URL carries.
+ */
+const getWebAppOrigin = () => {
+  try {
+    return new URL(NEXT_PUBLIC_WEBAPP_URL()).origin;
+  } catch {
+    return NEXT_PUBLIC_WEBAPP_URL();
+  }
+};
 
 export const isValidReturnTo = (returnTo?: string) => {
   if (!returnTo) {
@@ -10,7 +21,10 @@ export const isValidReturnTo = (returnTo?: string) => {
     const decodedReturnTo = decodeURIComponent(returnTo);
     const returnToUrl = new URL(decodedReturnTo, NEXT_PUBLIC_WEBAPP_URL());
 
-    if (returnToUrl.origin !== NEXT_PUBLIC_WEBAPP_URL()) {
+    // Compare against the origin, not the raw env value: when the app is served
+    // under a sub-path NEXT_PUBLIC_WEBAPP_URL is e.g. "https://host/ESign", which
+    // never equals a URL's origin ("https://host").
+    if (returnToUrl.origin !== getWebAppOrigin()) {
       return false;
     }
 
@@ -30,7 +44,17 @@ export const normalizeReturnTo = (returnTo?: string) => {
     const decodedReturnTo = decodeURIComponent(returnTo);
     const returnToUrl = new URL(decodedReturnTo, NEXT_PUBLIC_WEBAPP_URL());
 
-    return `${returnToUrl.pathname}${returnToUrl.search}${returnToUrl.hash}`;
+    const basePath = getBasePath();
+
+    let pathname = returnToUrl.pathname;
+
+    // A root-relative returnTo ("/inbox") resolves to a pathname without the
+    // sub-path, so re-apply it when it is missing.
+    if (basePath && pathname !== basePath && !pathname.startsWith(`${basePath}/`)) {
+      pathname = `${basePath}${pathname}`;
+    }
+
+    return `${pathname}${returnToUrl.search}${returnToUrl.hash}`;
   } catch {
     return undefined;
   }

packages/lib/utils/recipients.test.ts

@@ -0,0 +1,71 @@
+import { RecipientRole } from '@prisma/client';
+import { describe, expect, it } from 'vitest';
+
+import { isAssistantLastSigner, normalizeRecipientSigningOrders, sortRecipientsForSigningOrder } from './recipients';
+
+describe('recipient signing order helpers', () => {
+  it('sorts CC recipients after ordered active recipients', () => {
+    const recipients = [
+      { id: 1, role: RecipientRole.CC, signingOrder: 1 },
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 2 },
+      { id: 3, role: RecipientRole.APPROVER, signingOrder: 1 },
+    ];
+
+    expect(sortRecipientsForSigningOrder(recipients).map((recipient) => recipient.id)).toEqual([3, 2, 1]);
+  });
+
+  it('keeps original order when recipients have the same signing order', () => {
+    const recipients = [
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 1 },
+      { id: 1, role: RecipientRole.APPROVER, signingOrder: 1 },
+    ];
+
+    expect(sortRecipientsForSigningOrder(recipients).map((recipient) => recipient.id)).toEqual([2, 1]);
+  });
+
+  it('sorts and normalizes active recipient signing order and removes it from CC recipients', () => {
+    const recipients = [
+      { id: 1, role: RecipientRole.CC, signingOrder: 1 },
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 4 },
+      { id: 3, role: RecipientRole.APPROVER, signingOrder: 2 },
+    ];
+
+    expect(normalizeRecipientSigningOrders(sortRecipientsForSigningOrder(recipients))).toEqual([
+      { id: 3, role: RecipientRole.APPROVER, signingOrder: 1 },
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 2 },
+      { id: 1, role: RecipientRole.CC, signingOrder: undefined },
+    ]);
+  });
+
+  it('preserves caller order while normalizing signing order', () => {
+    const recipients = [
+      { id: 2, role: RecipientRole.ASSISTANT, signingOrder: 2 },
+      { id: 1, role: RecipientRole.SIGNER, signingOrder: 1 },
+      { id: 3, role: RecipientRole.CC, signingOrder: 1 },
+    ];
+
+    expect(normalizeRecipientSigningOrders(recipients)).toEqual([
+      { id: 2, role: RecipientRole.ASSISTANT, signingOrder: 1 },
+      { id: 1, role: RecipientRole.SIGNER, signingOrder: 2 },
+      { id: 3, role: RecipientRole.CC, signingOrder: undefined },
+    ]);
+  });
+
+  it('checks whether the last non-CC recipient is an assistant', () => {
+    expect(
+      isAssistantLastSigner([
+        { role: RecipientRole.SIGNER },
+        { role: RecipientRole.ASSISTANT },
+        { role: RecipientRole.CC },
+      ]),
+    ).toBe(true);
+
+    expect(
+      isAssistantLastSigner([
+        { role: RecipientRole.ASSISTANT },
+        { role: RecipientRole.SIGNER },
+        { role: RecipientRole.CC },
+      ]),
+    ).toBe(false);
+  });
+});

packages/lib/utils/recipients.ts

@@ -1,6 +1,6 @@
 import { isSignatureFieldType } from '@documenso/prisma/guards/is-signature-field';
-import type { Envelope } from '@prisma/client';
-import { type Field, RecipientRole, SigningStatus } from '@prisma/client';
+import type { Envelope, Field, Recipient } from '@prisma/client';
+import { RecipientRole, SigningStatus } from '@prisma/client';
 
 import { NEXT_PUBLIC_WEBAPP_URL } from '../constants/app';
 import { AppError, AppErrorCode } from '../errors/app-error';
@@ -15,6 +15,58 @@ import { zEmail } from './zod';
  */
 export const RECIPIENT_ROLES_THAT_REQUIRE_FIELDS = [RecipientRole.SIGNER] as const;
 
+// signingOrder isn't required when submitting the recipient form (Zod: z.number().optional())
+type RecipientWithSigningOrder = Pick<Recipient, 'role'> & Partial<Pick<Recipient, 'signingOrder'>>;
+
+export const isCcRecipient = (recipient: Pick<Recipient, 'role'>) => {
+  return recipient.role === RecipientRole.CC;
+};
+
+export const isAssistantLastSigner = (recipients: Pick<Recipient, 'role'>[]) => {
+  const nonCcRecipients = recipients.filter((recipient) => !isCcRecipient(recipient));
+  const lastNonCcRecipient = nonCcRecipients[nonCcRecipients.length - 1];
+
+  return lastNonCcRecipient?.role === RecipientRole.ASSISTANT;
+};
+
+export const sortRecipientsForSigningOrder = <T extends RecipientWithSigningOrder>(recipients: T[]): T[] => {
+  return [...recipients].sort((r1, r2) => {
+    const r1IsCcRecipient = isCcRecipient(r1);
+    const r2IsCcRecipient = isCcRecipient(r2);
+
+    // CC recipients always sort after non-CC recipients.
+    if (r1IsCcRecipient !== r2IsCcRecipient) {
+      return r1IsCcRecipient ? 1 : -1;
+    }
+
+    // Order by signing order; missing orders sort last.
+    const r1SigningOrder = r1.signingOrder ?? Number.MAX_SAFE_INTEGER;
+    const r2SigningOrder = r2.signingOrder ?? Number.MAX_SAFE_INTEGER;
+
+    return r1SigningOrder - r2SigningOrder;
+  });
+};
+
+export const normalizeRecipientSigningOrders = <T extends RecipientWithSigningOrder>(
+  recipients: T[],
+  canUpdateRecipient: (recipient: T) => boolean = () => true,
+): Array<T & { signingOrder?: number }> => {
+  const nonCcRecipients = recipients.filter((recipient) => !isCcRecipient(recipient));
+  const ccRecipients = recipients.filter((recipient) => isCcRecipient(recipient));
+
+  const normalizedNonCcRecipients = nonCcRecipients.map((recipient, index) => ({
+    ...recipient,
+    signingOrder: canUpdateRecipient(recipient) ? index + 1 : (recipient.signingOrder ?? index + 1),
+  }));
+
+  const normalizedCcRecipients = ccRecipients.map((recipient) => ({
+    ...recipient,
+    signingOrder: undefined,
+  }));
+
+  return [...normalizedNonCcRecipients, ...normalizedCcRecipients];
+};
+
 /**
  * Returns recipients who are missing required fields for their role.
  *

packages/lib/utils/settings-nav.ts

@@ -0,0 +1,299 @@
+import type { MessageDescriptor } from '@lingui/core';
+import { msg } from '@lingui/core/macro';
+import type { OrganisationMemberRole, TeamMemberRole } from '@prisma/client';
+import {
+  BracesIcon,
+  Building2Icon,
+  CreditCardIcon,
+  Globe2Icon,
+  GroupIcon,
+  LockIcon,
+  MailboxIcon,
+  Settings2Icon,
+  SettingsIcon,
+  ShieldCheckIcon,
+  UserIcon,
+  Users2Icon,
+  WebhookIcon,
+} from 'lucide-react';
+import type { ComponentType } from 'react';
+import { FaUsers } from 'react-icons/fa6';
+import { IS_BILLING_ENABLED, IS_DOCUMENSO_CLOUD } from '../constants/app';
+import { canExecuteOrganisationAction } from './organisations';
+import { canExecuteTeamAction } from './teams';
+
+export type SettingsNavScope = 'organisation' | 'team' | 'account';
+
+export type SettingsNavItem = {
+  key: string;
+  path: string;
+  label: MessageDescriptor;
+  icon?: ComponentType<{ className?: string }>;
+  isSubNav?: boolean;
+  isSubNavParent?: boolean;
+};
+
+export type SettingsNavGroup = {
+  scope: SettingsNavScope;
+  items: SettingsNavItem[];
+};
+
+export type SettingsNavGroups = {
+  organisation: SettingsNavGroup | null;
+  team: SettingsNavGroup | null;
+  account: SettingsNavGroup;
+};
+
+export type GetSettingsNavGroupsArgs = {
+  organisation: {
+    url: string;
+    currentOrganisationRole: OrganisationMemberRole;
+    organisationClaim: { flags: { emailDomains?: boolean; authenticationPortal?: boolean } };
+  } | null;
+  team: {
+    url: string;
+    currentTeamRole: TeamMemberRole;
+  } | null;
+  hasManageableBillingOrgs: boolean;
+};
+
+/**
+ * Build the nav-group structure for the unified settings sidebar.
+ *
+ * Pure data helper — given a current organisation, optional current team, and the billing-enabled
+ * flag, returns the items that should appear in each scope group. Groups the user has no manage
+ * permission for are returned as `null` (not empty arrays) so consumers can branch on visibility.
+ *
+ * Item ordering, claim-flag gating, and which sections are scope-specific are encoded here as the
+ * single source of truth for the unified-settings sidebar.
+ */
+export const getSettingsNavGroups = ({
+  organisation,
+  team,
+  hasManageableBillingOrgs,
+}: GetSettingsNavGroupsArgs): SettingsNavGroups => {
+  const isBillingEnabled = IS_BILLING_ENABLED();
+  const isDocumensoCloud = IS_DOCUMENSO_CLOUD();
+
+  const canManageOrg =
+    organisation !== null && canExecuteOrganisationAction('MANAGE_ORGANISATION', organisation.currentOrganisationRole);
+
+  const canManageTeam = team !== null && canExecuteTeamAction('MANAGE_TEAM', team.currentTeamRole);
+
+  const orgGroup: SettingsNavGroup | null = canManageOrg
+    ? {
+        scope: 'organisation',
+        items: [
+          {
+            key: 'general',
+            path: `/o/${organisation.url}/settings/general`,
+            label: msg`General`,
+            icon: Building2Icon,
+          },
+          {
+            key: 'preferences',
+            path: `/o/${organisation.url}/settings/document`,
+            label: msg`Preferences`,
+            icon: Settings2Icon,
+            isSubNavParent: true,
+          },
+          {
+            key: 'preferences-document',
+            path: `/o/${organisation.url}/settings/document`,
+            label: msg`General`,
+            isSubNav: true,
+          },
+          {
+            key: 'preferences-branding',
+            path: `/o/${organisation.url}/settings/branding`,
+            label: msg`Branding`,
+            isSubNav: true,
+          },
+          {
+            key: 'preferences-email',
+            path: `/o/${organisation.url}/settings/email`,
+            label: msg`Email`,
+            isSubNav: true,
+          },
+          {
+            key: 'preferences-reminders',
+            path: `/o/${organisation.url}/settings/reminders`,
+            label: msg`Reminders`,
+            isSubNav: true,
+          },
+          {
+            key: 'preferences-certificates',
+            path: `/o/${organisation.url}/settings/certificates`,
+            label: msg`Certificates`,
+            isSubNav: true,
+          },
+          ...((isBillingEnabled && organisation.organisationClaim.flags.emailDomains) || isDocumensoCloud
+            ? [
+                {
+                  key: 'email-domains',
+                  path: `/o/${organisation.url}/settings/email-domains`,
+                  label: msg`Email Domains`,
+                  icon: MailboxIcon,
+                },
+              ]
+            : []),
+          {
+            key: 'teams',
+            path: `/o/${organisation.url}/settings/teams`,
+            label: msg`Teams`,
+            icon: FaUsers,
+          },
+          {
+            key: 'members',
+            path: `/o/${organisation.url}/settings/members`,
+            label: msg`Members`,
+            icon: Users2Icon,
+          },
+          {
+            key: 'groups',
+            path: `/o/${organisation.url}/settings/groups`,
+            label: msg`Groups`,
+            icon: GroupIcon,
+          },
+          ...((isBillingEnabled && organisation.organisationClaim.flags.authenticationPortal) || isDocumensoCloud
+            ? [
+                {
+                  key: 'sso',
+                  path: `/o/${organisation.url}/settings/sso`,
+                  label: msg`SSO`,
+                  icon: ShieldCheckIcon,
+                },
+              ]
+            : []),
+          ...(isBillingEnabled
+            ? [
+                {
+                  key: 'billing',
+                  path: `/o/${organisation.url}/settings/billing`,
+                  label: msg`Billing`,
+                  icon: CreditCardIcon,
+                },
+              ]
+            : []),
+        ],
+      }
+    : null;
+
+  const teamGroup: SettingsNavGroup | null =
+    canManageTeam && team
+      ? {
+          scope: 'team',
+          items: [
+            {
+              key: 'general',
+              path: `/t/${team.url}/settings/general`,
+              label: msg`General`,
+              icon: SettingsIcon,
+            },
+            {
+              key: 'preferences',
+              path: `/t/${team.url}/settings/document`,
+              label: msg`Preferences`,
+              icon: Settings2Icon,
+              isSubNavParent: true,
+            },
+            {
+              key: 'preferences-document',
+              path: `/t/${team.url}/settings/document`,
+              label: msg`General`,
+              isSubNav: true,
+            },
+            {
+              key: 'preferences-branding',
+              path: `/t/${team.url}/settings/branding`,
+              label: msg`Branding`,
+              isSubNav: true,
+            },
+            {
+              key: 'preferences-email',
+              path: `/t/${team.url}/settings/email`,
+              label: msg`Email`,
+              isSubNav: true,
+            },
+            {
+              key: 'preferences-reminders',
+              path: `/t/${team.url}/settings/reminders`,
+              label: msg`Reminders`,
+              isSubNav: true,
+            },
+            {
+              key: 'preferences-certificates',
+              path: `/t/${team.url}/settings/certificates`,
+              label: msg`Certificates`,
+              isSubNav: true,
+            },
+            {
+              key: 'members',
+              path: `/t/${team.url}/settings/members`,
+              label: msg`Members`,
+              icon: Users2Icon,
+            },
+            {
+              key: 'groups',
+              path: `/t/${team.url}/settings/groups`,
+              label: msg`Groups`,
+              icon: GroupIcon,
+            },
+            {
+              key: 'public-profile',
+              path: `/t/${team.url}/settings/public-profile`,
+              label: msg`Public Profile`,
+              icon: Globe2Icon,
+            },
+            {
+              key: 'tokens',
+              path: `/t/${team.url}/settings/tokens`,
+              label: msg`API Tokens`,
+              icon: BracesIcon,
+            },
+            {
+              key: 'webhooks',
+              path: `/t/${team.url}/settings/webhooks`,
+              label: msg`Webhooks`,
+              icon: WebhookIcon,
+            },
+          ],
+        }
+      : null;
+
+  const accountGroup: SettingsNavGroup = {
+    scope: 'account',
+    items: [
+      {
+        key: 'profile',
+        path: '/settings/profile',
+        label: msg`Profile`,
+        icon: UserIcon,
+      },
+      {
+        key: 'organisations',
+        path: '/settings/organisations',
+        label: msg`Organisations`,
+        icon: Building2Icon,
+      },
+      {
+        key: 'security',
+        path: '/settings/security',
+        label: msg`Security`,
+        icon: LockIcon,
+      },
+      ...(IS_BILLING_ENABLED() && hasManageableBillingOrgs
+        ? [
+            {
+              key: 'billing',
+              path: '/settings/billing',
+              label: msg`Billing`,
+              icon: CreditCardIcon,
+            },
+          ]
+        : []),
+    ],
+  };
+
+  return { organisation: orgGroup, team: teamGroup, account: accountGroup };
+};

packages/lib/utils/settings-switcher.ts

@@ -0,0 +1,57 @@
+export type ComputeSwitcherContinuityPathArgs = {
+  currentPath: string;
+
+  /**
+   * Every settings path navigable in the destination scope — pass the destination's
+   * `SettingsNavGroup.items` paths from `getSettingsNavGroups`.
+   *
+   * Sourcing these from the nav builder (rather than a hardcoded list) means the switcher
+   * can only ever land on a page that is actually reachable there: permission and
+   * claim/billing gating are already applied when the group is built.
+   */
+  destinationPaths: string[];
+
+  /** Where to land when the current section has no equivalent in the destination. */
+  fallbackPath: string;
+};
+
+/**
+ * Extract the "section" portion of a settings URL. Returns null if not a scoped
+ * settings URL (account settings and non-settings pages have no equivalent to carry over).
+ *
+ * Examples:
+ *   /o/acme/settings/members      → 'members'
+ *   /o/acme/settings              → 'general'  (bare index redirects to General)
+ *   /t/eng/settings/webhooks/42   → 'webhooks'
+ *   /o/acme/documents             → null
+ *   /settings/profile             → null
+ */
+const parseSettingsSection = (path: string): string | null => {
+  const match = /^\/[ot]\/[^/]+\/settings(?:\/([^/?#]+))?(?:[/?#]|$)/.exec(path);
+
+  if (!match) {
+    return null;
+  }
+
+  return match[1] ?? 'general';
+};
+
+/**
+ * Compute the destination URL when the user switches organisation or team via the
+ * unified settings sidebar's switcher.
+ *
+ * Rule: stay on the same section if the destination has one; else use the fallback.
+ */
+export const computeSwitcherContinuityPath = ({
+  currentPath,
+  destinationPaths,
+  fallbackPath,
+}: ComputeSwitcherContinuityPathArgs): string => {
+  const currentSection = parseSettingsSection(currentPath);
+
+  if (!currentSection) {
+    return fallbackPath;
+  }
+
+  return destinationPaths.find((path) => parseSettingsSection(path) === currentSection) ?? fallbackPath;
+};

packages/lib/vitest.config.ts

@@ -1,6 +1,9 @@
+import macrosPlugin from 'vite-plugin-babel-macros';
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
+  // Transform lingui macros (e.g. `msg`) used by the code under test.
+  plugins: [macrosPlugin()],
   test: {
     include: ['**/*.test.ts'],
   },