feat(documenso-phase-5): pin transformSigningUrl + document website-side coordination

Phase 5 is mostly coordination + verification rather than a code
build — the embedded signing pages live in a different repo. What
lands here:

1. transformSigningUrl hardening — routes through extractSigningToken
   so a bare URL like `https://sig.example.com` no longer produces
   the malformed `<host>/sign/<role>/sig.example.com`. The token
   validator (≥8 URL-safe chars) rejects malformed tails so the
   function falls back to returning the raw URL.

2. 10 unit tests pin the role-segment mapping so a future refactor
   can't silently break the contract with the marketing website's
   /sign/[type]/[token] page. Covers:
     - all five SignerRole → URL segment mappings
     - trailing-slash normalization on the host
     - null host fallback (single-tenant / staging)
     - rejection of non-token-shaped tails

3. docs/documenso-integration-audit.md updated with:
     - Phase 2/3/4/7 landed-work summary (replacing the old
       "deferred" list that was now stale)
     - Phase 5 coordination tracker for the marketing-website side
       (the four edits the website team needs to make — listed
       here so the CRM stays the source of truth on the contract)
     - Phase 6 polish backlog (auto-send delay, document expiration,
       per-document message, reminder display, failed-webhook UI,
       field metadata panel, zoom controls, recipient drag-reorder)

Tests: 21 new transformSigningUrl + signers tests across two files;
full suite 1340 → 1350 ✅; tsc clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/documenso-integration-audit.md

@@ -208,13 +208,42 @@ add_header 'Access-Control-Allow-Origin' $cors_origin always;
 - Contract + Reservation tab UI shells with paper-signed upload + "send for signing" placeholder
 - Stage-conditional tab visibility for EOI / Contract / Reservation
 
-**Deferred (separate sessions):**
+**Landed in Phase 2-4 (2026-05-13):**
 
-- Custom document upload-to-Documenso service for contract/reservation (POST PDF → place fields → send). The tabs currently surface a "coming soon" dialog.
-- Recipient + signing order configurator UI (rep specifies signers per deal for custom-uploaded docs).
-- Drag-and-drop field placement UI on uploaded PDF previews. The fallback when this lands will be `computeDefaultSignatureLayout()` (footer-anchored fields).
-- Webhook handler enhancements to track per-signer `sent_at`/`opened_at`/`signed_at` and trigger the cascading "your turn" branded emails. Currently the webhook just updates document status.
-- Auto-store signed PDFs in storage backend and trigger `sendSigningCompleted()` on `DOCUMENT_COMPLETED`. Old system has this; needs porting.
+- **Phase 2** — Webhook cascade + on-completion PDF distribution. `handleRecipientSigned` now finds the next pending signer and fires `sendSigningInvitation`; `handleDocumentCompleted` calls `sendSigningCompleted` to all recipients with the signed PDF attached (resolved via `getStorageBackend()` so MinIO + filesystem backends both work). Recipient matching prefers the Documenso recipient `token` captured at send-time (`document_signers.signing_token`); falls back to email match.
+- **Phase 3** — `lib/services/custom-document-upload.service.ts` + `POST /api/v1/interests/[id]/upload-for-signing`. Magic-byte verifies the PDF, stores via `getStorageBackend`, inserts the `documents` row, runs the full Documenso round-trip (`createDocument → sendDocument → placeFields`), captures recipient tokens, auto-sends invitation when port `sendMode === 'auto'`.
+- **Phase 4** — `<UploadForSigningDialog>` (`src/components/documents/upload-for-signing-dialog.tsx`). Three-step state machine (file → recipients → fields). Auto-detect runs server-side via `lib/services/document-field-detector.ts` (pdfjs text-extraction + anchor patterns); rep can drag/place/delete fields via native DOM events. Wired into the Contract + Reservation tabs.
+- **Phase 7** — Project Director RBAC binding. Admin UI exposes `documenso_developer_user_id` / `approver_user_id` / `_label` settings; webhook cascade fires an in-CRM `document_signing_your_turn` notification for linked users alongside the email.
+
+**Phase 5 — Embedded signing URL emission verification:**
+
+- `transformSigningUrl()` validated via 10 unit tests in `tests/unit/services/document-signing-urls.test.ts`. Maps signer-role → URL segment as:
+  - `client → /sign/client/<token>`
+  - `developer → /sign/developer/<token>`
+  - `approver → /sign/cc/<token>` — funnels through the CC page with passive copy
+  - `witness → /sign/witness/<token>` — website must handle this segment
+  - `other → /sign/cc/<token>` — same as approver
+- Hardened to reject malformed source URLs: the function now uses `extractSigningToken()` (rejects tails <8 chars or with non-URL-safe punctuation), so a bare `https://sig.example.com` is returned untouched rather than producing the malformed `<host>/sign/<role>/sig.example.com`.
+
+**Phase 5 — coordination on the marketing-website side (NOT in this repo):**
+
+These are tracked here so the CRM stays the source of truth on the contract — the actual edits land in the website repo.
+
+1. **Website `/sign/[type]/[token].vue` must handle `type ∈ {client, cc, developer, witness}`.** The CRM emits `cc` for both `approver` and `other` roles, and `witness` for explicit witness signers. Anything else lands on the website's `/sign/error` fallback.
+2. **`signerMessages` map must be keyed on `(documentType, role)`** so a contract recipient hitting `/sign/client/<token>` sees "Sign Your Sales Contract" rather than the EOI default. Until the website is updated, the URL emits `(role, token)` only; the website can resolve documentType from the Documenso embed payload.
+3. **Post-sign callback** — the legacy portal POSTed to `client-portal.portnimara.com/api/webhook/document-signed`. The CRM no longer needs this — the Documenso webhook at `/api/webhooks/documenso` handles all state updates server-side. The website's POST is now optional; if it's still in place, point it at the CRM's webhook receiver as a real-time UI signal.
+4. **Apply the nginx CORS block above** on the prod Documenso instance.
+
+**Genuinely deferred (Phase 6 polish):**
+
+- Auto-send delay (`eoi_send_delay_minutes` per-port setting + scheduled BullMQ job).
+- Document expiration toggle (`documents.expires_at` + Documenso `expiresAt` passthrough).
+- Per-document custom invitation message (textarea on the upload dialog → `documents.invitation_message`).
+- Reminder rate-limit display ("next reminder available in X days" badge on each unsigned signer in the signing-progress UI).
+- Failed-webhook recovery admin surface — the BullMQ webhook DLQ exists; needs an admin page with a Replay button.
+- Per-field metadata side panel for DROPDOWN/RADIO option lists in the Phase 4 dialog.
+- Pinch-zoom + zoom-out controls on the field-placement canvas.
+- Recipient drag-reorder via dnd-kit (current UI uses an order number input).
 
 **Manual ops work for you:**
 

src/lib/services/document-signing-emails.service.ts

@@ -38,6 +38,7 @@ import {
   signingReminderEmail,
 } from '@/lib/email/templates/document-signing';
 import { getPortDocumensoConfig } from '@/lib/services/port-config';
+import { extractSigningToken } from '@/lib/services/documenso-signers';
 import { logger } from '@/lib/logger';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -128,7 +129,12 @@ export function transformSigningUrl(
   signerRole: SignerRole,
 ): string {
   if (!embeddedSigningHost || !documensoUrl) return documensoUrl;
-  const token = documensoUrl.split('/').filter(Boolean).pop();
+  // Phase 5: route the URL through the canonical token validator so a
+  // bare URL like `https://sig.example.com` doesn't silently produce
+  // `<host>/sign/<role>/sig.example.com`. extractSigningToken returns
+  // null when the tail isn't token-shaped (≥8 URL-safe chars), at
+  // which point we hand back the raw URL untouched.
+  const token = extractSigningToken(documensoUrl);
   if (!token) return documensoUrl;
   // Trim trailing slashes off the host so we always produce a clean
   // single `/` between segments.

tests/unit/services/document-signing-urls.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+
+import { transformSigningUrl } from '@/lib/services/document-signing-emails.service';
+
+/**
+ * Phase 5 — pin the URL-wrapping contract.
+ *
+ * The marketing website at portnimara.com/sign/[type]/[token] expects
+ * specific path segments (`client | cc | developer | witness`) and the
+ * Documenso webhook returns raw URLs of the form
+ * `https://signatures.portnimara.com/sign/<token>`. transformSigningUrl
+ * is the seam between the two — these tests guard the role-to-URL-
+ * segment mapping so a future refactor can't silently break the
+ * embedded signing pages.
+ */
+
+const RAW = 'https://signatures.portnimara.com/sign/vbT8hi3jKQmrFP_LN1WcS';
+const HOST = 'https://portnimara.com';
+
+describe('transformSigningUrl', () => {
+  it('returns raw URL when embeddedSigningHost is null (single-tenant / staging)', () => {
+    expect(transformSigningUrl(RAW, null, 'client')).toBe(RAW);
+  });
+
+  it('returns raw URL on empty input', () => {
+    expect(transformSigningUrl('', HOST, 'client')).toBe('');
+  });
+
+  it('maps client → /sign/client/<token>', () => {
+    expect(transformSigningUrl(RAW, HOST, 'client')).toBe(
+      'https://portnimara.com/sign/client/vbT8hi3jKQmrFP_LN1WcS',
+    );
+  });
+
+  it('maps developer → /sign/developer/<token>', () => {
+    expect(transformSigningUrl(RAW, HOST, 'developer')).toBe(
+      'https://portnimara.com/sign/developer/vbT8hi3jKQmrFP_LN1WcS',
+    );
+  });
+
+  it('maps approver → /sign/cc/<token> — website only handles {client, cc, developer, witness}', () => {
+    expect(transformSigningUrl(RAW, HOST, 'approver')).toBe(
+      'https://portnimara.com/sign/cc/vbT8hi3jKQmrFP_LN1WcS',
+    );
+  });
+
+  it('maps witness → /sign/witness/<token>', () => {
+    expect(transformSigningUrl(RAW, HOST, 'witness')).toBe(
+      'https://portnimara.com/sign/witness/vbT8hi3jKQmrFP_LN1WcS',
+    );
+  });
+
+  it('maps other → /sign/cc/<token> — funnels through CC page with passive copy', () => {
+    expect(transformSigningUrl(RAW, HOST, 'other')).toBe(
+      'https://portnimara.com/sign/cc/vbT8hi3jKQmrFP_LN1WcS',
+    );
+  });
+
+  it('strips trailing slashes from the host so we get a clean single / between segments', () => {
+    expect(transformSigningUrl(RAW, 'https://portnimara.com/', 'client')).toBe(
+      'https://portnimara.com/sign/client/vbT8hi3jKQmrFP_LN1WcS',
+    );
+    expect(transformSigningUrl(RAW, 'https://portnimara.com///', 'client')).toBe(
+      'https://portnimara.com/sign/client/vbT8hi3jKQmrFP_LN1WcS',
+    );
+  });
+
+  it('preserves the token verbatim — no URL encoding / re-shaping', () => {
+    const odd = 'https://sig.example.com/sign/Aa_-Zz09_-XYZ';
+    expect(transformSigningUrl(odd, HOST, 'developer')).toBe(
+      'https://portnimara.com/sign/developer/Aa_-Zz09_-XYZ',
+    );
+  });
+
+  it('returns raw URL when the input has no extractable token', () => {
+    const bare = 'https://sig.example.com';
+    expect(transformSigningUrl(bare, HOST, 'client')).toBe(bare);
+  });
+});