pn-new-crm/docs/audit-findings-tmp/07-email-integrations.md

Email + Integrations Audit (EM-01-19, IN-01-29) — agent #7

Headline: Broadly well-implemented. Primary issue: missing SMTP timeouts on sales transporter (HIGH — risks worker starvation). Plus 8 medium gaps in portal-email portId scoping, digest catalog key, receipt scanner config, presign TTL.

Counts: 0 critical · 1 high · 8 medium · 0 low · 30 passing

---

🟠 HIGH EM-XX: Sales transporter missing SMTP timeouts

• File: src/lib/services/sales-email-config.service.ts:331-337
• What: createSalesTransporter builds nodemailer transport with no timeout options. Compare createTransporter in src/lib/email/index.ts:26-37 which uses SMTP_TIMEOUTS = { connectionTimeout: 10_000, greetingTimeout: 10_000, socketTimeout: 30_000 }.
• Why it matters: Hung SMTP relay can stall send-out indefinitely. Email queue concurrency=5, maxAttempts=5. Without socket timeouts, one stuck TCP connection holds a worker for nodemailer's 2-min default × 5 retries = 10min/job × 5 slots = whole pool blocked for 10min by a single flaky send.
• Suggested fix: Apply SMTP_TIMEOUTS constant to nodemailer.createTransport in createSalesTransporter.

🟡 MEDIUM EM-05a: Per-port branding not threaded into portal activation/reset emails

• File: src/lib/services/portal-auth.service.ts:163-164
• What: issueActivationToken and issuePasswordReset call sendEmail(email, subject, html, undefined, text) without the 6th portId argument. Without portId, createTransporter() uses global env SMTP. Branding is threaded into HTML via getBrandingShell(portId) but the SMTP transport falls back to global.
• Why it matters: Multi-port deploys: portal auth emails for port B go through global env SMTP, defeating per-port SMTP override.
• Suggested fix: Pass portId as 6th arg to sendEmail in both issueActivationToken and the reset send.

🟡 MEDIUM EM-07: CC/BCC not supported in main sendEmail

• File: src/lib/email/index.ts:54-68
• What: SendEmailOptions lacks cc/bcc. Sales send-out path also lacks them.
• Suggested fix: Add optional cc/bcc to SendEmailOptions. Low urgency.

🟡 MEDIUM EM-11: Bounce-to-interest linking not implemented

• File: src/lib/services/sales-email-config.service.ts:13 (header comment)
• What: getSalesImapConfig exposes IMAP creds but no BullMQ worker reads IMAP. Failed deliveries don't update document_sends.failedAt.
• Suggested fix: Wire BullMQ recurring job using imapflow to scan inbox for bounce NDRs, match against document_sends.messageId. Phase 7 §14.9 deferred.

🟡 MEDIUM EM-16: Notification digest uses wrong catalog key for subject resolution

• File: src/lib/services/notification-digest.service.ts:161-169
• What: Calls resolveSubject with key: 'crm_invite' as any because 'notification_digest' is not in TEMPLATE_KEYS in src/lib/email/template-catalog.ts.
• Why it matters: Admin-set CRM invite subject override bleeds into digest emails.
• Suggested fix: Add 'notification_digest' to TEMPLATE_KEYS; update digest service to use it.

🟡 MEDIUM IN-11: Presigned URL TTL fixed at 900s for portal downloads

• File: src/lib/storage/index.ts:240-254 (presignDownloadUrl); src/lib/services/portal.service.ts:350 (getDocumentDownloadUrl)
• What: presignDownloadUrl defaults expirySeconds=900 (15min). Sales send-out correctly overrides to 24h. getDocumentDownloadUrl calls without expiry → 15min default.
• Why it matters: Portal users opening their doc list and clicking after >15min get 403.
• Suggested fix: Pass expirySeconds: 4 * 3600 for portal download links, or sign on-demand from API.

🟡 MEDIUM IN-21: OpenAI receipt-scanner module-level instantiation, no credential health check

• File: src/lib/services/receipt-scanner.ts:4
• What: const openai = new OpenAI(); at module level reads OPENAI_API_KEY at import. SDK throws on first call when unset; catch returns zero-confidence empty result. No admin-visible health check.
• Suggested fix: Guard OPENAI_API_KEY upfront with clear error. Add a health-check endpoint similar to checkDocumensoHealth.

🟡 MEDIUM IN-23: Receipt OCR ignores per-port config; hardcoded gpt-4o

• File: src/lib/services/receipt-scanner.ts:19
• What: model: 'gpt-4o' hardcoded; per-port getResolvedOcrConfig not consulted; aiEnabled flag does nothing. Module-level singleton OpenAI client.
• Suggested fix: Accept portId, call getResolvedOcrConfig(portId), check aiEnabled, use config.apiKey and config.model. Branch on provider for OpenAI vs Anthropic.

🟡 MEDIUM IN-24: Stale "pdfme" references in comments/seed

• File: src/lib/db/seed-data.ts:807, src/lib/services/document-templates.ts:573
• What: Comments still reference pdfme even though the rendering path was removed; tiptap-validation.ts:8 confirms pdfme retired. document-templates.ts:648-652 throws ValidationError for non-EOI templates.
• Suggested fix: Update comments to reference pdf-lib AcroForm fill; remove "pdfme" from seed-data description.

🟡 MEDIUM IN-29: Umami testConnection throws instead of returning typed result

• File: src/lib/services/umami.service.ts:80-101, 292
• What: loadUmamiConfig returns null gracefully; all public APIs return null when unconfigured. But testConnection throws CodedError('UMAMI_NOT_CONFIGURED') instead of returning { ok: false, error } like checkDocumensoHealth.
• Suggested fix: Return { ok: false, error: string } to match Documenso convention.

---

✅ Passing checks

• EM-01 per-port SMTP override (getPortEmailConfig in port-config.ts:136)
• EM-02/03 default send-froms cascade (explicit from → cfg.fromAddress → env.SMTP_FROM → noreply@${SMTP_HOST})
• EM-04 EMAIL_REDIRECT_TO subject prefix [redirected from <orig>]; documenso-client also applies applyRecipientRedirect/applyPayloadRedirect; env.ts:110 prod boot guard
• EM-05 branded shell (renderShell in src/lib/email/shell.ts:37)
• EM-06 reply-to override applied
• EM-08 send rate limit 50/user/hour Redis sliding-window keyed ${portId}:${userId}
• EM-09 streamAttachmentOrLink threshold + filename HTML-escape pre-SMTP
• EM-10 IMAP probe script + getSalesImapConfig AES-256-GCM decrypted
• EM-12 document_sends audit row in success + failure branches
• EM-13 portal activation token: 32-byte token, hash stored in portalAuthTokens, #token=... fragment to stay out of logs
• EM-14/15 reset/invite emails wired
• EM-17 EOI sent via Documenso (not as nodemailer attachment)
• EM-18/19 renderEmailBody escape-first + isSafeHref (https/mailto only) + MERGE_VALUE_ESCAPE_MAP neutralizes markdown chars
• IN-01 v1 template-generate path (generateDocumentFromTemplate)
• IN-02 v2 envelope/create multipart (FormData with payload JSON + files Blob)
• IN-03 v2 distribute returns recipients[].signingUrl in one round-trip
• IN-04 redistribute version-aware (v2 caveat: recipientIds may not target single recipient — API behavior risk, not code bug)
• IN-05 downloadSignedPdf version-aware
• IN-06 voidDocument version-aware (idempotent on 404)
• IN-07 placeFields v2 bulk field/create-many percent coords + fieldMeta; v1 one POST per field with pixel coords
• IN-08 normalizeDocument id ?? documentId for both docs and recipients (handles legacy r.Recipient capital-R)
• IN-09 NocoDB pg_advisory_xact_lock + skip rows where updated_at > last_imported_at
• IN-10 S3Backend with SSE AES256, all calls wrapped in withTimeout(30_000), never imports MinIO directly
• IN-12 filesystem MULTI_NODE_DEPLOYMENT guard (boot-time throw)
• IN-13 BullMQ exponential backoff: email/docs 5×1s, webhooks 8×30s
• IN-14 Redis noeviction in both compose files
• IN-15 src/worker.ts imports all 10 workers + SIGTERM/SIGINT graceful shutdown
• IN-16 public berths cache s-maxage=300, stale-while-revalidate=60
• IN-17 status filter Sold > Under Offer (status OR has active is_specific_interest with isNull(end_date)+outcome) > Available
• IN-18 mooring regex ^[A-Z]+\d+$ checked pre-DB; returns 400 for malformed
• IN-19/20 dual-mode health endpoint with timingSafeEqual
• IN-22 berth-pdf-parser tier-2 is unpdf (not Tesseract — prior comment correction); 30s timeout
• IN-25 fillEoiFormFields flatten + metadata; missing fields warn rather than throw
• IN-26 VALID_MERGE_TOKENS allow-list including {{eoi.berthRange}}
• IN-27 formatBerthRange handles all cases (single/contig/non-contig/cross-pontoon/dedup)
• IN-28 portal magic-link rate-limited 10/h/IP via enforcePublicRateLimit(req, 'portalToken')