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>

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