documenso/.agents/plans/clear-amber-light-validate-signer-fields-on-distribute.md at b92c53dbb23b89d3cfd89a6b38d2282cf273dfba

mirror of https://github.com/documenso/documenso.git synced 2026-06-22 04:12:06 +10:00

Files

T

Lucas Smith 0a3e0b8727 feat: validate signers have signature fields before distribution (#2411 )

API users were inadvertently sending documents without signature fields,
causing confusion for recipients and breaking their signing flows.

- Add getRecipientsWithMissingFields helper in recipients.ts
- Add server-side validation in sendDocument to block distribution
- Fix v1 API to return 400 instead of 500 for validation errors
- Consolidate UI signature field checks to use isSignatureFieldType
- Add E2E tests for both v1 and v2 APIs

2026-01-26 15:22:12 +11:00

3.2 KiB

Raw Blame History

date, title

date	title
2026-01-26	Validate Signer Fields On Distribute

Summary

Validate that signers have at least one signature field before allowing document/envelope distribution via API, matching the existing UI behavior.

Background

The API originally allowed distributing documents/envelopes without validating that signers had signature fields assigned. This was intentional - we thought API users might have specific flows where this flexibility was needed.

However, after running it this way for a while, we've observed that more often than not, API users inadvertently send documents without fields assigned. This causes confusion for their recipients (who receive a document with nothing to sign) and breaks their own systems expecting a completed signing flow.

Problem

The API allowed distributing documents/envelopes even when signers had no signature fields assigned. This was inconsistent with the UI which validates this condition before allowing distribution.

Solution

1. Create centralized validation helper

File: packages/lib/utils/recipients.ts

Added RECIPIENT_ROLES_THAT_REQUIRE_FIELDS constant (currently only SIGNER)
Added getRecipientsWithMissingFields() function that returns recipients missing required fields
Uses existing isSignatureFieldType guard from packages/prisma/guards/is-signature-field.ts

2. Add server-side validation

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

Added validation check that throws AppError with INVALID_REQUEST code when signers are missing signature fields
This blocks both v1 and v2 API distribution endpoints since they both use sendDocument()

3. Fix v1 API error handling

File: packages/api/v1/implementation.ts

Changed sendDocument endpoint to use AppError.toRestAPIError(err) instead of always returning 500
Now returns 400 for validation errors

4. Update UI to use shared helper

Files:

apps/remix/app/components/dialogs/envelope-distribute-dialog.tsx
packages/ui/primitives/document-flow/add-fields.tsx

5. Consolidate `hasSignatureField` checks

Updated to use isSignatureFieldType guard (checks both SIGNATURE and FREE_SIGNATURE):

apps/remix/app/components/general/document-signing/document-signing-form.tsx
apps/remix/app/components/general/envelope-signing/envelope-signer-form.tsx
apps/remix/app/components/embed/multisign/multi-sign-document-signing-view.tsx
apps/remix/app/components/embed/embed-direct-template-client-page.tsx
apps/remix/app/components/embed/embed-document-signing-page-v1.tsx

6. Add E2E tests