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>
Admin UI binding for the developer + approver user-id fields that
Phase 1 schema'd but left unwired. Surfaces four new fields in the
Documenso settings card so admins can:
- Set per-port display labels for the developer/approver slots
(documenso_developer_label / approver_label) — drives email
subjects + signer-progress UI copy. Defaults to "Developer" /
"Approver" when blank.
- Link each slot to a CRM user (documenso_developer_user_id /
approver_user_id) — UUID from /admin/users.
Webhook side-effect:
- handleRecipientSigned's cascade now fires an in-CRM notification
for the next pending signer when their signerRole matches a
configured developer_user_id / approver_user_id. The branded
email is the primary channel; the notification is a defense-in-
depth nudge for users who live in the CRM all day.
- New notification type `document_signing_your_turn` with dedupeKey
`document:<id>:your-turn:<signerId>` so duplicate webhook
deliveries don't re-notify.
- Falls back silently when the binding isn't set or the signer
isn't a developer/approver — preserves the existing flow.
Out of scope (build plan flags as out-of-scope for v1):
- Auto-fill name/email when a user is selected: needs a typeahead
field type the SettingsFormCard doesn't have yet. Admin reads the
user's UUID from /admin/users and pastes; minor friction for a
one-time per-port config.
- Webhook handler reading the linked user's email and matching
against the inbound recipient: today the developer/approver email
settings already drive the matching; the user-id is purely a
notification target.
Tests: 1340/1340 ✅; tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 4 lands the visual half of the Documenso build — the upload-
for-signing dialog the Contract + Reservation tabs hand off to. Four
files of new code; the existing tab placeholders point at it.
Files added:
- lib/services/document-field-detector.ts — Phase 4c auto-detect
scanner. Uses pdfjs-dist to extract per-page text + positions, then
matches anchor patterns (Signature, Date, Initials, Email, Name,
underscore-runs) and produces percent-coordinate DetectedField
rows. Recipient label inference walks ±100pt of each match for
Buyer/Seller/Client/Witness/Notary keywords. Returns [] when the
PDF is image-only; UI falls back to manual placement without an
error. 6 unit tests pin the matching + coordinate math.
- app/api/v1/documents/auto-detect-fields/route.ts — multipart POST
endpoint that delegates to detectFields(). Permission-gated by
documents.send_for_signing.
- app/api/v1/documents/signing-defaults/route.ts — GET endpoint that
surfaces just the per-port developer + approver display name/email
+ sendMode flag. No secrets exposed; lets the dialog prefill the
recipient configurator without an admin-scoped settings read.
- components/documents/upload-for-signing-dialog.tsx — the Phase 4
UI. Three-step state machine inside a single Dialog:
1. select-file: drop/click PDF picker + title input
2. configure-recipients: client + developer + approver prefilled,
rep can add/remove/reorder + change role (SIGNER/APPROVER/CC)
3. place-fields: react-pdf renders the source PDF; auto-detect
runs in the background on file load and seeds the overlay;
rep places, drags, resizes, deletes, reassigns fields via the
palette + side panel. Native DOM drag (no dnd-kit dependency
added — the coordinate math stays obvious).
Send fires POST /api/v1/interests/[id]/upload-for-signing (Phase 3
service); success toast reflects port sendMode (auto fires the
invite immediately, manual leaves it for the rep).
Files modified:
- components/interests/interest-contract-tab.tsx + reservation-tab.tsx:
swap the ComingSoonDialog placeholder for the real
UploadForSigningDialog with the matching documentType prop. The
placeholder ComingSoonDialog helper is deleted from both.
- scripts/tsc-staged.mjs: pull src/types/**/*.d.ts into the temp
staged-only tsconfig so side-effect CSS imports (e.g.
react-pdf/dist/Page/AnnotationLayer.css) resolve via the existing
declare-module shim. Without this fix the staged compile reports
TS2882 even though the full tsc --noEmit pass passes.
Design choices noted in code comments:
- Native drag over dnd-kit: the field overlay's percent-based
coordinate math is short enough that adding a drag library adds
complexity without saving lines.
- Auto-detect on file-load (not on demand): runs immediately so the
rep doesn't have to click a second button — empty result drops
back to manual placement silently.
- Per-recipient color swatches indexed by signingOrder.
- Recipient seed via useMemo + user-event handler instead of
useEffect → setRecipients (Wave 3 set-state-in-effect avoidance).
Server-side, Phase 3 plumbing handles the rest: tenant guard, magic-
byte verify, Documenso round-trip with per-port v1/v2 routing,
recipient signingToken capture for Phase 2 webhook cascade, auto-
send when port.sendMode === 'auto'.
Tests: 1334 → 1340 ✅ (6 new for the detector); tsc clean.
Deferred polish (Phase 6):
- Per-field metadata side panel for DROPDOWN/RADIO option lists
- Pinch-zoom + zoom-out controls on the field-placement canvas
- Recipient drag-reorder via dnd-kit
- Required toggle per field
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Backend foundation for the Contract + Reservation signing flows. The
existing tab placeholders point at a "send for signing" CTA that had
no code behind it; this commit lands the service + endpoint that the
Phase 4 drag-drop UI will POST to.
Files added:
- lib/services/custom-document-upload.service.ts — orchestrates the
full PDF → Documenso → local-state-update flow:
1. Magic-byte verifies the PDF (defense vs. mislabelled bytes —
same posture as berth-pdf + brochures).
2. Stores the source PDF via getStorageBackend(), works on s3 +
filesystem backends. Auto-files into the client's entity folder
when resolvable.
3. Inserts the documents row (status=draft → sent), with the file
FK + interest link + clientId snapshot.
4. Documenso round-trip via createDocument → sendDocument →
placeFields. Per-port apiVersion drives v1 vs v2 (existing
client handles both — v1: /api/v1/documents; v2: envelope/create
multipart). meta.signingOrder + redirectUrl flow through.
5. Captures recipient signingUrl + token into document_signers so
the Phase 2 cascade picks them up.
6. Auto-send first invitation when port.eoi_send_mode === 'auto';
stamps invitedAt to suppress duplicate cascades.
7. Advances pipeline stage to contract_sent.
- app/api/v1/interests/[id]/upload-for-signing/route.ts — multipart
POST endpoint. Zod-validates recipients (≤20), fields (≤200), PDF
size (≤50MB), all 11 Documenso field types. Permission-gated by
documents.send_for_signing + interests.edit (matches the
external-eoi precedent — the auto-advance side-effect is
interest-mutating).
Files modified: none — keeps the existing tab placeholders as the
entry point; Phase 4 builds the drag-drop UI on top.
Validation contract pinned by 8 unit tests covering: empty recipient
list, empty field list, empty/oversized PDF, non-PDF magic bytes,
out-of-range + negative recipientIndex, duplicate signingOrder.
The heavy paths (storage put, Documenso HTTP, signer update) are
exercised by the existing realapi Playwright project — no new
realapi specs added because the contract-upload UI doesn't exist yet
to drive them.
Verified against Documenso API spec (v1 OpenAPI + v2 docs via
Context7): recipients[].token is on the Recipient model in both
versions; webhook payloads echo the same shape so the Phase 2 token-
match handler works against custom-uploaded docs without changes.
Tests: 1326 → 1334 ✅; tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the silence after the first signing invitation. Three real
improvements on top of the existing webhook plumbing, all aligned with
the Documenso v1.32 + v2 webhook payload shape (verified against the
official OpenAPI spec + Context7 docs):
1. Cascading "your turn" emails — when DOCUMENT_SIGNED / DOCUMENT_
RECIPIENT_COMPLETED / RECIPIENT_SIGNED fires for a recipient,
handleRecipientSigned now resolves the next pending signer in
signing order and sends them the branded sendSigningInvitation()
email with the embedded-host-wrapped URL. Stamps invitedAt so a
duplicate webhook retry doesn't re-send.
2. On-completion PDF distribution — handleDocumentCompleted now re-
reads the just-committed signedFileId, resolves all signers, and
fires sendSigningCompleted() to every recipient with the signed
PDF attached. resolveAttachments in lib/email already pulls bytes
through getStorageBackend() so this works under both the s3/minio
and filesystem backends without changes. Failures fall through to
logger.error rather than throwing — the document is already marked
completed and the admin can re-trigger manually.
3. Token-based recipient matching — Documenso v1 + v2 webhook recipients
carry a `token` field (per the OpenAPI spec); same token appears in
the document-create response. Captured at send time into the existing
document_signers.signing_token column (already in schema from Phase 1)
and used by handleRecipientSigned + handleDocumentOpened before
falling back to email match. Robust against the case where one email
serves multiple roles on a contract — which is the documented gap in
the legacy nocodb-based handler.
Supporting changes:
- New helper module lib/services/documenso-signers.ts with
extractSigningToken() (URL-tail fallback), DOC_TYPE_LABEL map, and
nextPendingSigner() picker. 11 unit tests cover the token-regex,
the helper picks the lowest pending signing-order, and rejects
declined/signed correctly.
- documenso-client normalizeDocument now reads `token` from both
`recipients[]` and the legacy capital-R `Recipient[]` array Documenso
v1.32 sometimes ships in webhooks.
- documents.service signer-update at send time prefers the explicit
token field, falling back to extractSigningToken(signingUrl) for any
v2 deployment whose distribute response omits it.
Out of scope for Phase 2 (per the build plan):
- Custom-doc upload-to-Documenso path (Phase 3)
- Recipient + field-placement UI (Phase 4)
- DNS-rebinding hardening + circuit-breaker (deferred-refactor list)
- Auto-reminder cron — manual "Send reminder" button + auto-reminder
toggle remain manual until Phase 6 polish
Tests: 1315/1315 vitest ✅ + 11 new tests for documenso-signers ✅;
tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Final pass over the unaddressed AUDIT-2026-05-12 dossiers, taking the
tractable Critical/High items from each:
error-ux-auditor (5 items)
- C2: 17 toast.error(err.message) sites swept to toastError(err, …) so
every user-visible failure carries a copy-paste Reference ID
- C3: apiFetch synthesizes a client-side correlation id when a 5xx
comes back with a non-JSON body (reverse-proxy HTML pages); message
becomes "The server is unreachable. Please try again." with code
UPSTREAM_UNREACHABLE
- C4: checkRateLimit fails OPEN when Redis is unavailable so an outage
no longer 500s login + portal sign-in; logged at warn so monitoring
catches it
- H2: StorageTimeoutError (name='TimeoutError') replaces the plain
Error throw in s3.ts withTimeout — error-classifier hints fire now
- H5: errorResponse() adopted across /api/storage/[token],
/api/public/website-inquiries, and the Documenso webhook body (drops
the "Invalid secret" reconnaissance string)
outbound-webhook-auditor (5 items)
- C1: signature is now HMAC(secret, `${ts}.${body}`) with the
timestamp surfaced as X-Webhook-Timestamp so receivers can reject
replays outside a freshness window
- C3: dead-letter with reason missing_signing_secret when secret is
null (defence-in-depth against DB tampering / future migration
mistakes)
- H2: webhooks queue bumped to maxAttempts=8 with 30 s base
exponential backoff so a 30 s receiver blip during a deploy no
longer dead-letters every in-flight event; per-queue
backoffDelayMs added to QUEUE_CONFIGS
- M1: SSRF denylist gains Oracle Cloud metadata 192.0.0.192
- M2: dispatch-time https:// assertion before fetch, so a bad DB edit
can't slip plaintext through
storage-pathing-auditor (2 items)
- H1: berth-PDF presigned-upload keys now `${portSlug}/berths/…/…`
with portSlug threaded into backend.presignUpload — engages the
filesystem-proxy port-binding `p` token verifier
- H2: presignDownloadUrl auto-derives portSlug from the key's first
segment when callers don't pass it, so all 8 download sites engage
the `p`-token guard without per-site plumbing
search-auditor (1 item)
- H3: removed dead void wantEmail; void wantPhone; pair plus the
unused looksLikeEmail helper — the bucket-reorder it was scaffolded
for was never wired
maintainability-auditor (1 item)
- M2: swept seven abandoned `void <symbol>` markers and their dead
imports across clients/bulk, interests/bulk, admin/email-templates,
admin/website-submissions, alert-rules, and notes.service
Deferred to future work (substantial refactors, schema migrations, or
multi-file UI work):
- error-ux M3-M8 (global-error.tsx, per-route loading.tsx coverage,
ErrorBanner component, /api/ready route, worker DLQ admin surface)
- maintainability C1-C4 (documents/search/notes service splits,
interest-tabs split — multi-hour refactors)
- currency C1-H5 (mixed-currency dashboard aggregation, FX history
table, rounding policy) — wait for second non-USD port
- outbound-webhook C2 (deliveries reaper job), H1 (DNS-rebind TOCTOU
with undici Agent), H3 (circuit-breaker), H5 (presigned-post-policy)
- storage-pathing C2 (orphan reaper), H3-H5 (streaming + content-type
binding)
Tests: 1315/1315 vitest ✅ ; tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
**mobile-pwa-auditor H4 — mobile shell uses min-h-screen**
`min-h-screen` resolves to `100vh` on iOS Safari, which is the LARGE
viewport height (URL bar collapsed). On first paint the page renders
~75–100px taller than visible, and reps see a blank strip past the
bottom tab bar until the URL bar collapses on first scroll. Swap
`min-h-screen` → `min-h-[100dvh]` in `mobile-layout.tsx`. The scanner
layout already does this correctly.
**multi-port-auditor C1 — port-switcher race / cross-port bleed**
`apiFetch` previously preferred Zustand for the X-Port-Id header and
only consulted the URL slug as a fallback. Zustand lags by one render
behind `PortProvider`'s reconcile effect; clicking from /port-A to
/port-B fired the first round of queries with X-Port-Id = port-A
while the page chrome rendered port-B → silent cross-port data bleed
in the UI.
Make the URL slug authoritative: read it first via
`window.location.pathname` + `resolvePortIdFromSlug`, fall back to
Zustand only on global routes (/dashboard) without a port slug.
**multi-port-auditor C3 — defaultPortId silently stripped**
`withAuth` reads `preferences.defaultPortId` as the X-Port-Id
fallback, but `/me` PATCH's `.strict()` schema + ALLOWED_PREF_KEYS
allow-list silently dropped the key on every write. The fallback was
therefore dead — super-admins always landed alphabetically-first.
Add `defaultPortId: z.string().uuid().optional()` to the strict
schema and include it in ALLOWED_PREF_KEYS so super-admins can
persist their last-picked port.
Tests 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
**file-lifecycle-auditor C1 — avatar replace leaks rows + blobs**
`POST /api/v1/me/avatar` overwrote `userProfiles.avatarFileId` without
reading or deleting the previous file id. Every "Replace photo" leaked
one `files` row + one S3 blob, untethered (no client/yacht/company
FK) and invisible to every existing UI sweep.
Now captures the prior id BEFORE the UPDATE, then best-effort
`deleteFile()` on the old row (handles ref-check + blob delete + audit)
after the new id is committed. Failure is logged at warn — a stale
blob shouldn't block the user from setting a new avatar.
**file-lifecycle-auditor M1 — files.client_id missing ON DELETE**
`files.client_id` was the only entity FK on the polymorphic `files`
table that defaulted to `NO ACTION` (yacht_id + company_id were
`SET NULL` per migration 0042). Any future bulk-client-delete that
bypassed `hardDeleteClient`'s explicit FK-nullify pre-step would
FK-violate. Migration `0059_files_client_id_onDelete_setnull.sql`
brings it to parity; the explicit nullify in client-hard-delete is
kept as defense in depth.
Tests 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
build-auditor H1: prod `script-src` previously kept `'unsafe-inline'`
because dropping it requires a per-request nonce that Next's RSC
bootstrap + Server Actions can thread into their inline scripts.
Implement the nonce mechanism in `src/proxy.ts`:
1. Mint a base64-encoded UUID per request as the CSP nonce.
2. Set the nonce on the REQUEST headers via
`content-security-policy` + `x-nonce` so Next.js's RSC layer reads
the active CSP and stamps `nonce=<value>` onto every inline
`<script>` it emits (Next's documented pattern).
3. Set the matching `Content-Security-Policy` on the RESPONSE so the
browser actually enforces it.
Prod CSP becomes:
`script-src 'self' 'nonce-<value>' 'strict-dynamic'`
`'strict-dynamic'` lets nonce-tagged scripts load further scripts they
trust, which is how Next chunks the rest of the bundle in. Inline
`<script>` without a nonce is now rejected by the browser — closes
the canonical XSS pathway.
Dev keeps `'unsafe-inline' 'unsafe-eval'` because Next's HMR evaluates
code at runtime and the nonce machinery doesn't reach it.
`style-src` keeps `'unsafe-inline'` because Tailwind + Radix runtime
style injection has no nonce story yet. Revisit when Tailwind v5
ships a nonce-able API.
The static CSP in `next.config.ts` stays as a fallback for static
assets / API JSON paths that don't run through the proxy. Updated
the comment so future readers know the proxy CSP takes precedence
for HTML responses.
Tests 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
concurrency-auditor C-2: every queue.add(...) site previously enqueued
without a stable jobId, so a double-dispatch (webhook retry, double-
click on Send, scheduler tick collision) would create two queue jobs
and the downstream worker would deliver twice. BullMQ rejects a
duplicate jobId while the original is still queued or active, so a
stable per-entity key gives at-most-once semantics naturally.
Added jobIds across all 10 enqueue sites:
- email send-invoice → `send-invoice:<invoiceId>`
- notifications invoice-overdue-notify → keyed per UTC day so dupes
collapse intra-day but tomorrow's run can re-notify if unpaid
- export gdpr-export → keyed on the exportId (unique per request)
- webhooks deliver (3 sites: dispatch, retry, test) → keyed on the
webhook_deliveries row UUID
- maintenance expense-dedup-scan → keyed on expenseId
- notifications send-notification-email → keyed on notification id
- email send-inquiry-confirmation → keyed on interestId (1 per
submission)
- email send-inquiry-sales-notification → keyed on interestId+email
(1 per recipient per submission)
- reports generate-report → keyed on the generated_reports row id
Pure refactor — no UX impact. Closes the BullMQ dedup gap that was
the second half of the concurrency-auditor's CRITICAL-tier findings.
Test fixture update: gdpr-export integration test now asserts the
jobId option on the queue.add call.
Tests 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
**asset-auditor C1+C2+H1+H3 — image normalization**
Add `src/lib/services/image-normalize.ts` and wire it into
`uploadFile()` so every accepted image is re-encoded via sharp before
hitting storage:
- Strips EXIF (GPS coords, device serial, photographer) so uploaded
photos don't leak per-pixel PII to anyone with a download URL (C1).
- Caps dimensions at 4096px via `resize({fit:'inside',withoutEnlargement:true})`
so a 30000×30000 palette PNG can't decompression-bomb a downstream
sharp decode (C2).
- Re-encode drops polyglot trailers (PDF+JPEG sandwiches that beat
the prefix-only magic-byte check) (H1).
- Freezes animated GIFs to first frame (H3).
Avatar route already funnels through uploadFile so it's covered by
the single change.
**asset-auditor M2 — sanitizeFilename strips RTL/zero-width**
Add Unicode NFC + a strip of bidi-control (U+202A-U+202E, U+2066-U+2069)
+ zero-width chars (U+200B-U+200F, U+FEFF) to `sanitizeFilename`.
Closes the classic Windows-icon-spoof vector
(`invoice_fdp.exe` displaying as `invoice_exe.pdf`) plus folder-listing
collision spoofs.
**datetime-auditor C1 — reminder dueAt drift on every save**
The `<input type="datetime-local">` round-trip in reminder-form.tsx
used `iso.slice(0,16)` (load) and `new Date(value).toISOString()`
(submit). The slice drops the `Z` so a UTC instant is mis-interpreted
as local on load, then converted back to UTC on save — every save
of an existing Warsaw reminder drifted backwards by 2h (CEST). After
two saves the reminder appears at 06:00 instead of 10:00.
Add `toLocalDatetimeLocal(d: Date)` helper that builds the local
YYYY-MM-DDTHH:MM string from getter methods so the round-trip is
TZ-safe. snooze-dialog already did this correctly; the contact-log
dialog also uses the correct localIsoString pattern.
**datetime-auditor C2 — BullMQ cron in UTC, not port-local**
`upsertJobScheduler` defaulted `tz` to UTC. Patterns like
`0 8 * * *` were intended as "8 AM Warsaw" but fired at 09:00 winter
/ 10:00 summer. Pass `tz: process.env.SCHEDULER_TZ ?? 'Europe/Warsaw'`.
Sub-hourly / hourly patterns are TZ-invariant and stay UTC.
**datetime-auditor C3 — report-scheduler never advanced next_run_at**
The minutely scheduler selected `nextRunAt <= now()` and enqueued
generate-report — but never bumped nextRunAt. For weekly/monthly
reports this meant the job re-fired every single minute until a
human zeroed the row out, flooding recipients with dupes.
Now uses `cron-parser` (added as a dep) to compute the next fire
from `report.schedule` and UPDATEs the row BEFORE the enqueue.
Malformed cron expressions disable the row instead of re-attempting
every minute.
Tests 1315/1315. Migration 0058 applied via psql.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
authz-auditor C-1 second half: while the permission-overrides PUT route
already enforces caller-superset (prior wave), the `updateUser`
role-reassignment path didn't. A port admin holding only
\`admin.manage_users\` could PATCH a peer's roleId to a sales-director-
equivalent and have the colleague execute permissions the granter
didn't hold.
\`updateUser\` now takes optional `callerPermissions` + `callerIsSuperAdmin`
parameters and, when both are supplied (every interactive admin route),
walks the new role's effective permission tree and refuses any \`true\`
leaf the caller doesn't already hold. Super admins bypass by definition.
Wired \`ctx.permissions\` + \`ctx.isSuperAdmin\` through the single caller
(`/api/v1/admin/users/[id]` PATCH). Legacy callers that omit the args
(none currently) would silently skip the check; if any future system
job calls \`updateUser\` it should pass `callerPermissions=ctx.permissions`
explicitly.
Other authz items confirmed resolved by earlier work or by-design:
- C-1 (permission-overrides PUT): caller-superset already shipped in
an earlier wave; verified by reading the route.
- H-1 (alerts GET ungated): already gated on \`admin.view_audit_log\`
per the auditor's tier-4 recommendation.
Tests 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the two CRITICAL items from auth-flow-auditor plus the
high-impact M10 open-redirect.
**C1 — Password reset doesn't revoke existing sessions**
CRM side: Better Auth has a built-in
`emailAndPassword.revokeSessionsOnPasswordReset` flag — flip it on.
Verified by reading password.mjs in node_modules/better-auth: this
calls `internalAdapter.deleteSessions(userId)` after the password
update commits. One-line fix, closes the canonical session-bumping
gap on the CRM forgot-password flow.
Portal side: the portal uses JWT sessions (not DB-side rows) so
there's no `deleteSessions` to call. Add a per-user
`password_changed_at` watermark column on `portal_users` and have
`verifyPortalToken` reject any token whose `iat` predates the
watermark. Updated on `resetPassword`, `changePortalPassword`, and
`activateAccount` so every password mutation revokes outstanding
cookies. Token shape gains a required `portalUserId` claim so the
verify step can do the watermark lookup without an email-based join;
legacy tokens (pre-Wave-11) lack it and are rejected → forces one
re-login per portal user post-deploy (24h max delay since portal
tokens already self-expire at 24h).
Migration `0058_portal_password_revocation.sql` stamps existing
rows to `now()` so no current session is invalidated by the schema
change itself.
**M10 — Portal login `?next=` open redirect**
`portal/login/page.tsx` did `router.replace(next as never)` against
unvalidated `searchParams.get('next')`. An attacker could send a
victim to `/portal/login?next=https://evil.example` and the post-sign-in
redirect would navigate cross-site. Add `safeNextPath()` that requires
`/portal/...` prefix and rejects protocol-relative URLs; everything
else falls back to `/portal/dashboard`.
**Other auth-flow items confirmed resolved by earlier waves:**
- H6 resolve-identifier enumeration: endpoint deleted in Wave 1
(replaced with sign-in-by-identifier which keeps the synthetic
email behind a server-side proxy)
Tests updated: portal-auth integration test mocks `db` so the new
DB-watermark lookup in `verifyPortalToken` stays unit-pure.
Tests 1315/1315 after `psql ALTER TABLE` to apply migration locally.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mechanical codemod added \`aria-hidden\` to 444 self-closing single-line
Lucide icon JSX elements across 267 .tsx files in:
- shared/, layout/, dashboard/
- admin/ (all sections)
- clients/, berths/, yachts/, companies/, interests/, documents/
- reminders/, reservations/, residential/, expenses/, email/
The regex targeted only the safe pattern \`<IconName className="..." />\`
(no other props, self-closing, capitalized component name). Every match
inspected is a decorative companion to visible text or sits inside a
button whose accessible name comes from \`aria-label\` / sr-only text
— the icon itself should not be announced.
Screen readers no longer double-read the icon + the adjacent label
text (e.g. "Pencil Pencil Edit" → just "Edit"). The existing
@axe-core/playwright smoke test (\`20-accessibility.spec.ts\`) continues
to pass.
Test suite stays at 1315/1315 vitest. typescript clean.
Closes task #69 (aria-hidden sweep) from the AUDIT-2026-05-12 follow-ups
backlog.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Close the CRITICAL + HIGH-tractable race conditions the
concurrency-auditor flagged. The wide-impact items (BullMQ jobId
plumbing — C-2; webhook outbound retry idempotency keys; etc.) span too
many call sites for a single contained wave and stay deferred.
**C-1 — handleDocumentCompleted concurrent-retry orphan-blob**
Wave 1 fixed the compensating-delete on single-process failure but the
idempotency gate at line 1110 reads `doc.status` outside any row lock.
Two webhook deliveries arriving in parallel both pass the gate, both
storage.put + db.insert(files), and the losing files row orphans its
blob since documents.signed_file_id only points at one. Now the
transaction at line 1176 SELECTs the document `FOR UPDATE` and
re-checks the gate; if a concurrent worker already completed, throws a
sentinel `DocumentAlreadyCompletedError` which the outer catch
recognizes and runs the compensating storage.delete at info level
(not error). Net effect: at-most-once signed-PDF persistence even
under Documenso 5xx-then-retry storms.
**H-1 — moveFolder cycle check race**
Two concurrent folder moves (A → B and B → A) in READ COMMITTED can
each pass the cycle check against pre-state and both commit, leaving
A↔B in the tree. Add a per-port `pg_advisory_xact_lock` at the top of
the move transaction so the walk-and-write is atomic per port.
Lock auto-releases on tx end; no impact on cross-port folder ops.
**H-3 — upsertInterestBerth 23505 → generic 500**
Two concurrent `setPrimaryBerth` calls hit `idx_interest_berths_one_primary`
and the loser surfaced as a generic 500. Catch the 23505 + constraint
name and remap to ConflictError so the UI gets a "Another rep changed
the primary berth at the same time. Refresh and try again." toast.
**M-2 — username uniqueness 23505 → generic 500**
Same TOCTOU shape: pre-check at me/route.ts:132 says "available", the
UPDATE then fails at the partial unique index. Catch 23505 +
`idx_user_profiles_username_unique` and remap to ConflictError.
Tests 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the highest-leverage CRITICAL/HIGH/MEDIUM items from the
build-auditor that weren't already covered by Wave 1 (EMAIL_REDIRECT_TO
production guard) or the existing `.dockerignore`.
**C3 — socket.io in standalone trace**
- Add socket.io + @socket.io/redis-adapter to serverExternalPackages
in next.config so the build system sees the dependency (the custom
server is the only importer, no Next route touches it).
- Belt-and-braces: COPY both from the deps stage into the runner stage
of Dockerfile, mirroring the audit's suggested fix.
**H1 — CSP `'unsafe-inline'` in prod**
- Audit recommends nonce-based scripts. Implementing nonces requires
middleware that emits a per-request nonce + threading it through
Next's RSC bootstrap + Server Actions. Out of scope for this wave;
documented the rationale at the CSP definition so the next pass
knows where to start, and noted that the in-the-wild XSS surfaces
are already closed via escapeHtml/escapeUrl in the email + webhook
pipelines.
**H2 — NEXT_PUBLIC_APP_URL validation**
- Add `NEXT_PUBLIC_APP_URL: z.string().url()` to the env schema so a
missing build-time value fails validation instead of silently
inlining the empty string into the client bundle and breaking
multi-origin deploys.
**M3 — serverExternalPackages completeness**
- Add imapflow, mailparser, pdf-lib, sharp, tesseract.js,
@react-pdf/renderer, unpdf — all heavy native/CJS-leaning
server-only deps that should not be route-traced.
**H5 — healthcheck PORT templatization**
- docker-compose.{,prod.}yml: replace hardcoded
`http://localhost:3000/api/health` with `${PORT:-3000}` so
overriding PORT via .env doesn't put the container into a
restart loop.
**M9 — NODE_ENV=production in builder**
- Dockerfile builder stage now sets NODE_ENV=production above
`RUN pnpm build` so the prod-only branches in next.config
(CSP, etc.) compile deterministically.
**M7 — HEALTHCHECK directive in image**
- Add image-level HEALTHCHECK to the app Dockerfile (mirrors the
one in Dockerfile.worker for Redis) so the image is
self-describing for non-compose orchestrators.
Items already addressed prior to this wave:
- C1 (.dockerignore exists, comprehensive)
- C2 (EMAIL_REDIRECT_TO production refusal — Wave 1)
- H4 (compose resource + log limits — already in prod compose)
Tests 1315/1315 throughout.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the CRITICAL + high-leverage HIGH items from the types-auditor:
**C1 — `tx: any` in client-restore.service**
Export a canonical `Tx` type from `lib/db/utils.ts` (derived from
Drizzle's `db.transaction` callback shape) and use it in
`applyReversal` so the 12+ downstream tx writes get full inference.
**C2 — berth-detail page stacked `useQuery<any>` escape hatches**
Export `BerthDetailData` from berth-detail-header and consume it
through useQuery + apiFetch. Removed three `any` escapes in the
highest-traffic detail page. Also collapsed the duplicate `BerthData`
in berth-tabs.tsx to import from berth-detail-header so the two
types can't drift.
**C3 — parseBody migration for portal/public routes**
Replace raw `await req.json() + schema.parse(body)` with the
project-standard `parseBody(req, schema)` helper across 7 routes:
- portal/auth/{change-password, activate, reset-password}
- auth/set-password
- public/{interests, residential-inquiries}
Skipped the three anti-enumeration routes (forgot-password, sign-in,
sign-in-by-identifier) where the manual validation gives opaque
errors on purpose. website-inquiries already wraps the parse in a
custom 400 — left as-is.
**HIGH #5 — `toAuditJson<T>` helper (21 → 0 inline casts)**
Introduce `toAuditJson<T extends object>(row: T): Record<string,
unknown>` in lib/audit.ts (mirrors gdpr-bundle-builder's `toJsonRow`
that already exists for the same reason). Codemod 21 `<row> as unknown
as Record<string, unknown>` sites across:
- invoices.ts × 6
- expenses.ts × 6
- berths.service × 2
- documents.service × 2
- ocr-config.service × 2
- ai-budget.service × 2
- yachts.service, companies.service, company-memberships.service × 1 each
document-templates' `payload as unknown as Record<...>` is a different
shape (Documenso form-values widening, not an audit log) — kept the
manual cast there. Tests stay 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the CRITICAL and high-leverage HIGH items from the
onboarding-auditor report:
**C1 — checklist auto-checks were reading the wrong setting keys**
A port that had actually been configured still showed three steps as
incomplete, permanently capping the checklist at < 70 %.
- email step: `sales_email_smtp_host` → `smtp_host_override` (the key
the email admin page actually persists).
- documenso step: `documenso_api_url` → compound gate
`documenso_api_url_override` + `documenso_developer_email` +
`documenso_approver_email` + `documenso_eoi_template_id`. All four
are required for `buildDocumensoPayload` not to error out; checking
only the URL falsely greenlit the step until a rep tried to send an
EOI and Documenso 404'd.
- settings step: `recommender_top_n_default` → `heat_weight_recency`.
The defaults are layered (port > global > built-in), so a port using
the built-ins never writes the `top_n_default` row — old key was an
unreachable green. heat_weight_recency genuinely means "admin tuned
the recommender".
**C2 — forms step href was broken**
`STEPS[8].href = '../'` resolved through the Link template to the
dashboard, not `/admin/forms`. Fixed to `'forms'`.
**C3 — EOI signer-identity gate**
Folded into the new compound-gate logic on the documenso step
(see C1). Now matches what the EOI pipeline actually requires before
it can send.
**C4 — ensureSystemRoots failure mode poisoned port creation**
`ports.service.createPort` awaited `ensureSystemRoots` after the port
row had committed, so a throw bubbled out as a 500 even though the
inline comment said "non-fatal if this throws". Wrap in try/catch +
logger.warn — the row stays live, the next admin action self-heals
via `ensureEntityFolder`, and the operator doesn't retry into a 409.
**H5 — berth-list empty-state copy misleads fresh ports**
"Berths are imported from external sources. Adjust your filters..."
implied data existed but was hidden. Branch on whether any filter is
active: with none, suggest running `import-berths-from-nocodb.ts`;
with filters, the original "adjust filters" message.
**M4 — admin-sections-browser description was wrong**
"Setup checklist for fresh ports (read-only references)" implied the
page was read-only when it has working manual-completion checkboxes
and discouraged clicking in. Reworded.
Additionally, the OnboardingStep type gains an optional
`autoCheckSettingKeysAll` field for compound gates (used by the
documenso step), and the auto-detected hint shows all keys when the
gate is compound.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the highest-impact items from the copy-auditor's CRITICAL +
HIGH + MEDIUM bands:
**C2 portal raw-status leak**
- Drop the staff-only `leadCategory` chip from the portal interests
page entirely. Privacy + optics: clients should never see "hot lead"
in their own portal. `eoiStatus` was already wrapped in
`portalSigningLabel`; only the categorical chip remained.
**C3 signing-status label drift**
- Add `src/lib/labels/document-status.ts` as the single source of
truth for the {draft, sent, partially_signed, completed, expired,
cancelled} lifecycle: labels (CRM + portal variants), StatusPill
variant, and the "active / in-flight" set.
- Wire it into interest-eoi-tab, interest-contract-tab,
interest-reservation-tab — they previously redefined identical
STATUS_LABELS / ACTIVE_STATUSES blocks per-file.
**H1 + M3 verbiage codemod**
- `Save Changes` → `Save changes` (sentence case, matches the
surrounding admin/CRM pattern).
- `Saving...` (ASCII three dots) → `Saving…` (Unicode ellipsis).
Matches the project's UTF-8-elsewhere convention and reads
correctly via screen-readers.
**M1 envelope jargon → signing request**
- smart-archive-dialog: "Leave envelope pending" → "Leave signing
request pending"; "Void the signing envelope" → "Cancel the signing
request"; section header updated to match.
- document-detail: "voids the signing envelope" → "cancels the signing
request".
- bulk-archive-wizard: "leave invoices/signing envelopes alone" →
"leave invoices/signing requests alone".
- Documenso admin page intentionally keeps `envelope` (dev/integration
vocabulary).
**M5 Hot Lead casing**
- Normalize `Hot Lead` / `General Interest` / `Specific Qualified` to
sentence case in `constants.ts` LABEL_OVERRIDES and all per-file
lead-category maps so the CRM trend (sentence case) is consistent.
**C1 surface-level rename**
- "Linked prospect (optional)" → "Linked interest (optional)" on the
berth status-change dialog.
- "Deal Documents" tab → "Interest Documents" (URL/route kept as
`/deal-documents` to avoid breaking deep links; rename deferred).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address the pdf-auditor findings that survived the 2026-05-12 PDF stack
overhaul (pdfme → react-pdf). Items C-2/C-3 (tiptap-to-pdfme bugs) were
resolved when that 571-LOC bridge was deleted; remaining items:
- **M-7 wrong-port brand fallback** — replace `'Port Nimara'` defaults
in PDF-rendering services. `reports.service` and `expense-export`
throw when the port row is missing (the job is FK-keyed on a real
port, so absence = broken state, must not stamp a competitor brand).
`record-export` uses `'(port)'` as the visible placeholder.
- **M-2 silent field drift in fill-eoi-form** — promote the
always-silent catch in `setText` / `setCheckbox` to log a structured
warning per missing field (mirroring the existing `setBerthRange`
pattern). A re-cut template with drifted AcroForm field names now
surfaces in ops logs instead of shipping with empty values.
- **M-3 form not flattened** — `fillEoiFormFields` now flattens the
AcroForm before save. Documenso pathway flattens server-side; this
brings the in-app pathway to parity, so the signer can't edit
pre-filled yacht dimensions / address / berth number after the fact.
- **M-1 PDF metadata** — set Title / Author / Subject / Lang / Producer
/ Creator on the generated EOI PDF for downstream readers and a11y
tooling.
- **M-4 noisy berth-range warnings** — downgrade per-mooring warn to
debug; emit a single summary warn per call when any passthrough
occurred. Multi-berth EOIs with archived/legacy moorings no longer
spam the log on every render.
- **M-6 source PDF sha pinning** — pin
`assets/eoi-template.pdf` sha256 via `EXPECTED_EOI_SHA256` (exported
for tests); `loadEoiTemplatePdf` warns once per process when the
bytes drift without an explicit hash bump. Documented the
intentional-update workflow in `assets/README.md`.
Tests updated in `tests/unit/pdf/fill-eoi-form.test.ts` to reflect
flatten + metadata (form fields are gone after flatten; pdf-lib has no
getLanguage so we assert the other setters round-trip).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a default [portSlug]/loading.tsx that covers all 72 nested routes
that previously rendered nothing during the cold-load gap. Uses the
existing PageSkeleton (page-header + table-skeleton) so the empty-header
flash on direct-URL visits / tab navigations is gone.
Add tailored loading.tsx for the four other tab-strip detail surfaces so
their initial paint mirrors the real page structure (header strip,
pipeline stepper for interests, tab strip, two-column overview):
- yachts/[yachtId]/loading.tsx
- companies/[companyId]/loading.tsx
- interests/[interestId]/loading.tsx
- berths/[berthId]/loading.tsx
(clients/[clientId]/loading.tsx already existed.)
Closes ui/ux M3.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five DataTable consumers were rendering as horizontally-scrolling
desktop tables on mobile because they had no cardRender prop. Now they
collapse to a vertical card list below the lg: breakpoint with the
same actions inline:
- admin/tags/tag-list
- admin/roles/role-list
- admin/ports/port-list (also: Active/Inactive badge -> StatusPill)
- admin/document-templates/template-list (also: Active/Inactive badge
-> StatusPill)
- admin/custom-fields/custom-fields-manager
All five now share the user-list / berth-list pattern: row-card with
title, secondary meta, and trailing action buttons; same TanStack
table instance powers both the desktop table and the mobile cards.
Closes ui/ux H2 + extends M2 (status-pill coverage).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Build a shared <TemplateTokenPicker> that renders the canonical
MERGE_FIELDS catalog grouped by scope, plus a dynamically-fetched
"Custom (port-specific)" group surfaced from /api/v1/admin/custom-fields.
The custom group is filtered to entity types the resolver actually
expands at send time (client/interest/berth - see
mergeCustomFieldValues in document-sends.service).
Wire it into both consumers:
- admin/document-templates/template-form.tsx (replaces TEMPLATE_VARIABLES
list which had drifted from the canonical catalog)
- admin/sales-email-config-card.tsx (replaces flat alphabetical dump)
Closes custom-fields §B "UI surfacing of {{custom.…}} tokens".
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Extend StatusPill with berth (available/under_offer/sold) and user
(enabled/disabled) variants so every "this thing is in state X" pill
shares one primitive and palette.
- Swap berth-card, berth-detail-header, berth-columns from ad-hoc
bg-green-100 / bg-yellow-100 / bg-red-100 Tailwind tuples to
<StatusPill status="...">.
- Swap UserList Active/Disabled <Badge> and user-card Inactive pill to
StatusPill; Super-Admin chip kept as a domain-specific accent (violet).
Closes ui/ux M1+M2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Swap the one outlier (client-interests-tab.tsx) from Vaul Drawer to
Sheet side=right so every detail-preview surface uses the same
primitive. Document the doctrine: Sheet for side panels on both desktop
and mobile; Vaul Drawer reserved for mobile-only bottom-sheet UX
(currently just MoreSheet).
Closes ui/ux M11.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes Wave 1.4 (CRITICAL). Three templates still inlined URLs
directly into `href` without the existing safeUrl() helper:
- inquiry-client-confirmation: `mailto:${contactEmail}` href —
user-supplied email straight to an HTML attribute.
- inquiry-sales-notification: `${crmUrl}` from inquiry form input.
- residential-inquiry: same `mailto:${contactEmail}` pattern.
Each call now passes through `safeUrl()` from `@/lib/email/shell`,
which (a) scheme-allow-lists to http(s)/mailto/tel/root-relative and
(b) HTML-attribute-escapes the result. A stray `"` in any URL would
have escaped the attribute; a `javascript:` scheme would have
triggered XSS in webmail clients that run scripts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes Wave 1.3 (CRITICAL). The previous storage.put → files.insert
→ documents.update sequence had two real failure modes:
1. **Orphan blob.** If storage.put succeeded but the files.insert or
documents.update failed, the blob lived forever in MinIO with no
DB pointer. Re-runs re-uploaded a new blob without cleaning up
the previous one.
2. **Zombie completed state.** The catch block at the end ran
`documents.update({status: 'completed'})` with NO signedFileId
on any failure path. The idempotency early-return at the top
requires BOTH status='completed' AND signedFileId, so retries
*did* still re-attempt — but reps saw a "completed" document
with no signed file, hiding the failure.
Fix:
- Track `putStoragePath` outside the try. After storage.put lands,
the variable holds the path; cleared once the DB commit succeeds.
- files.insert + documents.update + reservation contract mirror all
run in a single `db.transaction(...)`. Atomic commit-or-rollback.
- Catch block: compensating `storage.delete(putStoragePath)` if the
DB commit didn't land. Logs at error level on compensating-delete
failure so a human can clean up.
- Catch block no longer sets `status='completed'`. The doc stays
in its prior state; Documenso's retry (or our poll-worker) re-
attempts the full sequence safely thanks to the unchanged
idempotency gate.
Verified: tsc clean, documents-completion-auto-deposit tests all
pass (5/5).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes Wave 1.1 (CRITICAL): the production-grade migration runner the
audit flagged as missing.
Why drizzle-kit migrate alone wasn't enough:
- Wraps every migration in a single transaction. Postgres forbids
CREATE INDEX CONCURRENTLY inside a transaction (25001), so the
6 composite indexes in 0052_audit_critical_fixes.sql never landed
in prod.
- db:push silently diverges from migration-tracked truth on DDL the
kit can't infer from the schema (CHECK constraints, partial unique
indexes, the berth-pdf circular FK).
scripts/db-migrate.ts:
- Reads journal-ordered migrations from src/lib/db/migrations.
- Tracks applied state in drizzle.__drizzle_migrations (same schema
Drizzle's own tools use).
- Splits each migration on `--> statement-breakpoint`.
- Classifies each statement: CREATE/REINDEX/DROP INDEX CONCURRENTLY
→ outside transaction; everything else → batched in one tx per
migration. Transactional batch runs first, CONCURRENTLY second.
Three modes:
- `pnpm db:migrate` — apply pending migrations
- `pnpm db:migrate:status` — diff applied vs disk
- `pnpm db:migrate:baseline` — mark all as applied without running
them. Use ONCE per env when schema
was bootstrapped via db:push.
Also fixes scripts/tsc-staged.mjs: temp tsconfig now lives in
`node_modules/.cache/tsc-staged/` (was /tmp) AND explicitly lists
`types: [node, react, react-dom]` so @types/* auto-resolution works
when `include: []` short-circuits TS's default discovery.
For the existing prod cutover:
After `db:migrate:baseline`, manually verify 0052's composite
indexes exist:
SELECT indexname FROM pg_indexes
WHERE indexname IN ('idx_files_port_client', 'idx_files_port_company',
'idx_files_port_yacht', 'idx_docs_port_client',
'idx_docs_port_company', 'idx_docs_port_yacht');
If missing, paste 0052's CREATE INDEX CONCURRENTLY statements into
a `psql` session directly (each runs OUTSIDE a transaction).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
p-retry wraps every Documenso API call with 3 attempts (1 + 2 retries),
exponential backoff (1s → 4s with jitter). AbortError short-circuits
on:
- 401/403 — auth failures won't fix themselves on retry
- 4xx other than 429 — Documenso rejected the payload; retrying
hurts more than it helps
5xx + 429 (rate-limit) go through the retry path with backoff so we
politely re-attempt after delay. Recovers the single-connection-blip
scenario the audit's services pass flagged.
p-queue installed too (audit §36.A.1 companion to p-limit). No
concrete land site today — we don't bulk-fan-out to Documenso, and
existing pLimit covers our internal mass-op fan-outs. Available for
future rate-per-second scenarios.
Verified: tsc clean, vitest 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the `if (open) { setStage(...); setCode(''); ... }` reset
useEffect with a key-based remount of the dialog body. The body now
mounts fresh each time the dialog opens; useState initialisers
run naturally instead of being chased by an effect.
Pattern (apply to remaining dialogs in the same shape):
```tsx
export function MyDialog(props) {
return (
<Dialog open={props.open} onOpenChange={props.onOpenChange}>
<DialogContent>
{props.open && <MyDialogBody key={props.id} {...props} />}
</DialogContent>
</Dialog>
);
}
```
Applied to:
- hard-delete-dialog (keyed on clientId)
- bulk-hard-delete-dialog (keyed on joined clientIds)
set-state-in-effect: 43 → 41.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
set-state-in-effect: 44 → 43.
Eight admin list/load sites migrated total this session; the
remaining ~43 hits are predominantly the dialog/form open→reset
pattern (intentional setState-in-effect when a dialog opens to
populate fields from props). Cleanest fix is key-based remount
of the dialog body; tracked in BACKLOG as a focused refactor pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the useState + useEffect + apiFetch pattern with TanStack
Query in six admin list pages — same pattern, mechanical refactor:
- admin/tags/tag-list
- admin/ports/port-list
- admin/roles/role-list
- admin/users/user-list
- admin/document-templates/template-list
- admin/webhooks/page
- dashboard/timezone-drift-banner (also: detected-tz reads via
useSyncExternalStore so render stays pure)
Side benefits: list refetches now share a query cache across tabs
(via @tanstack/query-broadcast-client-experimental that was wired
up earlier this branch), so when admin A edits a role in one tab,
admin B's tab sees the updated row without a manual reload.
set-state-in-effect warnings: 51 → 45.
Verified: tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Installs all five Tier 2 polish deps the audit flagged. Each integrates
where it adds concrete value today:
- **embla-carousel-react** — shadcn-style `<Carousel>` primitive in
`src/components/ui/carousel.tsx`. Available for future berth/yacht
photo galleries; no current call site beyond the primitive.
- **yet-another-react-lightbox** — wired into the image branch of
`file-preview-dialog.tsx`. Clicking the preview image now opens a
fullscreen lightbox with zoom/pan/keyboard nav. Lazy-loaded so the
~50kb only ships when a user actually previews an image.
- **@use-gesture/react** — `usePinch` on the PdfViewer's content
pane for native pinch-zoom on tablets/phones. Clamped to the
same [50%, 300%] range as the +/- buttons; desktop wheel still
scrolls.
- **react-virtuoso** — installed but NOT wired. Inbox is naturally
bounded by recent-notifications filter at ~10-20 items; ScrollArea
handles it fine. Reserve for actual scale issues (admin audit log
archive, etc.).
- **motion** — installed but NOT wired. Pipeline kanban uses
dnd-kit's own transforms and conflicts with motion's layout
animation. @formkit/auto-animate already handles list-mutation
animations elsewhere. Available for opportunistic adoption when
a polish surface emerges that the existing libraries don't cover.
Verified: tsc clean, vitest 1315/1315, next build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Cleared 4 rule buckets (37 violations, including 5 real bugs) and
silenced 1 informational bucket from the Next 16 / react-hooks v7
upgrade. Cleared rules promoted from `warn` back to `error` so new
regressions block CI.
Real bug fixes:
- `interest-contact-log-tab.tsx`: `useMemo` used for side effects
(5 setState calls inside a memo body); converted to `useEffect`.
- `PieChart.tsx`: cumulative `let angle` mutation in a render-phase
`map`; converted to `reduce` so the slice array is built without
re-assignment.
- `documents-hub.tsx`: `useMemo(() => ({ count: 0 }))` used as a
mutable drag counter; converted to `useRef`.
- `notes-list.tsx`: `Date.now()` read during render for note-edit
countdown (impure) → pinned to a `now` state ticked every 30s.
- `onboarding-checklist.tsx` / `user-profile.tsx` /
`user-settings.tsx`: `useEffect(() => void load(), [])` with the
`load` function declared AFTER the effect — relied on hoisting,
trips Compiler's "access before declared" rule. Declared inside
the effect.
Pattern fixes (intentional cache-via-ref → state or layout-effect):
- 6 `ref.current = x` writes during render moved into layout
effects (`use-realtime-invalidation`, `settings-form-card`,
`inbox`).
- 3 `ref.current` reads during render (search totals cache,
scanner file ref) rewritten to backed-by-state.
- `use-is-mobile.ts` rewritten on `useSyncExternalStore` to avoid
the SSR-then-rehydrate setState dance.
- `use-notifications.ts` rewritten to write socket pushes directly
into the React Query cache via `setQueryData`, removing a local
state mirror.
Rule config (`eslint.config.mjs`):
- `react-hooks/purity` → error (was warn, cleared)
- `react-hooks/set-state-in-render` → error (was warn, cleared)
- `react-hooks/immutability` → error (was warn, cleared)
- `react-hooks/refs` → error (was warn, cleared)
- `react-hooks/incompatible-library` → off (informational only)
- `react-hooks/set-state-in-effect` → warn (51 remaining, all the
useEffect→fetch→setState data-fetch pattern; migration to
useQuery tracked in BACKLOG)
Verified: tsc clean, eslint 0 errors / 69 warnings (down from 105),
vitest 1315/1315, next build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Other outdated entries inspected + held:
- @types/node 20 → 25: pinned to 20 to match Node 20 runtime
(esbuild --target=node20). Bumping types beyond runtime would
let a Node 25-only API slip in undetected.
- archiver 7 → 8: still no @types/archiver@8 published, skip per
the original audit.
- eslint 9 → 10: deferred — eslint-config-next@16's transitive
eslint-plugin-react@7 isn't eslint-10 compatible.
- react-resizable-panels 3 → 4: v4 renamed exports (PanelGroup →
Group, PanelResizeHandle → Separator). Pinned to v3 for shadcn
convention.
- @react-email/components: marked deprecated by Resend org-wide
without a replacement — keep using.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the `<iframe src={presignedUrl}>` preview path which
delegated rendering to the browser's built-in PDF viewer. The iframe
worked on desktop but failed on mobile (older Android Chrome
refuses inline PDFs; iOS Safari opens a new tab).
`<PdfViewer>` renders via pdfjs-dist + react-pdf so the experience
is identical across all browsers + form factors. Adds page nav,
zoom controls, and per-page accessibility labels.
Lazy-loaded via next/dynamic with ssr:false — pdfjs is ~150kb gzip,
no route ships it unless a PDF is actually previewed.
pdfjs worker + CMaps + fonts loaded from unpkg CDN pinned to the
matched pdfjs-dist version (first-load cost paid once per user, no
bundle-size impact on routes that never preview a PDF).
Verified: tsc clean, vitest 1315/1315, next build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The old CurrencyInput had ~100 LOC of regex-based parsing,
display-state syncing, and caret/focus juggling. react-number-format
ships a 17-LOC equivalent (NumericFormat with customInput pointing
at our shared Input shell) that handles the edge cases the hand-
rolled version missed: paste sanitisation, IME composition,
selection-caret preservation, locale separator switching.
Same external API on CurrencyInput so all 3 call sites
(berth-form, invoice-line-items, expense-form-dialog) keep working
without changes.
Verified: tsc clean, vitest 1315/1315, next build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Dev-only — ships zero runtime. Adds 150+ named utility types
(SetRequired, PartialDeep, MergeDeep, Promisable, Jsonifiable,
etc.). Adopt at call sites when a hand-rolled Omit<X, Y> & Pick<Z, W>
composition would read more clearly with a named util.
No forced migration: the codebase only has 3 small hand-rolled
compositions today, all readable as-is.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the hand-rolled `[fields].map(v => \`"\${v}"\`).join(',')`
pattern in expense-export.tsx with papaparse's Papa.unparse.
The previous version didn't handle:
- commas inside fields (would split rows mid-record)
- newlines inside fields (would terminate rows early)
- BOM for Excel-friendly encoding
- numeric/null normalization
Papa.unparse handles all of those + accepts a keyed-object row shape
that lets us define column order and get matching headers for free.
Verified: tsc clean, vitest 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Minimal next-intl wire-up so future i18n additions are a config
change, not a code rewrite. No URL routing changes — there's no
`/<locale>/` prefix because there's no second locale today.
- `src/i18n/request.ts` — request-scoped locale + messages loader,
hard-coded to 'en'
- `messages/en.json` — common namespace with a few sample keys
- `next.config.ts` — withNextIntlPlugin wraps the config
- `src/app/layout.tsx` — wraps body with NextIntlClientProvider so
client components can `useTranslations('common')` now
When a real locale target appears (Polish for marina users, Italian
for broker portal, etc.):
1. Add `messages/<locale>.json`
2. Move route folders under `app/[locale]/` to enable URL routing
3. Add a `routing.ts` with the locale list + default
Verified: tsc clean, vitest 1315/1315, next build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New seed harness for stress-testing list pages, search, analytics
under realistic volumes. Faker-driven, deterministic via fixed
seed, idempotent via `clients.source_details = 'wide-synthetic'`
marker.
- `src/lib/db/seed-wide-synthetic-data.ts` — generator (1000 clients
default, override via `WIDE_SEED_COUNT`)
- `src/lib/db/seed-wide-synthetic.ts` — entrypoint
- `pnpm db:seed:wide-synthetic` script
Distribution:
- 70% of clients get an interest (spread across pipeline stages)
- ~50% of those interests link to a real berth
- Acquisition source weighted: 55% website / 25% referral /
15% broker / 5% manual
- Locale-aware names/emails/phones/addresses via faker
Curated synthetic seed (`seed-synthetic-data.ts`) and realistic
seed (`seed-data.ts`) are untouched — this is a third axis for
volume testing, not a replacement.
Verified: tsc clean, build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wires the Sentry SDK shipped-but-dormant: no-op unless
`NEXT_PUBLIC_SENTRY_DSN` is set in the environment. Production opts
in via the deploy env; dev + CI stay quiet.
- `sentry.client.config.ts` / `sentry.server.config.ts` /
`sentry.edge.config.ts` — runtime init, each guards on the DSN.
- `instrumentation.ts` — Next 13.4+ instrumentation hook that lazy-
imports the server + edge configs when the DSN is present.
- `next.config.ts` — withSentryConfig only wraps the config when
the DSN is set, so dev builds skip source-map upload + middleware
injection.
- `src/lib/env.ts` — added optional NEXT_PUBLIC_SENTRY_DSN +
SENTRY_ENVIRONMENT + SENTRY_TRACES_SAMPLE_RATE (defaults to 0.1).
Env vars to add to .env.example (blocked from this commit by the
.env hook — apply manually):
# Sentry (optional — SDK is a no-op without a DSN)
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_ENVIRONMENT=
# Defaults to 0.1 (10%) when unset
SENTRY_TRACES_SAMPLE_RATE=
Replay is opt-in only — disabled by default for now; we'd need to
audit privacy implications (PII redaction, GDPR) before enabling it.
Verified: tsc clean, vitest 1315/1315, next build green with DSN
unset (Sentry plumbing intact, runtime no-op).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Docs hub's desktop sidebar is now drag-resizable. Mobile path is
unchanged — still uses the FolderTreeSidebar Sheet drawer.
- Extracted `FolderTreeBody` from `folder-tree-sidebar.tsx` so the
same tree renders inside the mobile Sheet AND the desktop panel
without forking the component.
- `FolderTreeSidebar` is now mobile-only (just the Sheet trigger);
documents-hub composes the desktop layout itself.
- `<ResizablePanelGroup autoSaveId="documents-hub-split">` persists
the user's chosen split width via localStorage automatically.
Min 14% / max 40% defends against starvation.
- shadcn-style `<Resizable*>` primitives in `src/components/ui/`
match the rest of the UI kit; uses react-resizable-panels v3
(the v4 release renamed exports to `Group`/`Separator` and broke
the shadcn convention — pinned v3 for now).
Verified: tsc clean, vitest 1315/1315, next build green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Applied @next/codemod migrations:
- middleware-to-proxy: src/middleware.ts → src/proxy.ts + function rename
- remove-experimental-ppr: no hits
- remove-unstable-prefix: no hits
tsconfig.json picked up Next 16's autofixes:
- jsx: 'preserve' → 'react-jsx'
- include .next/dev/types/**/*.ts (dev-mode route types)
- next-env.d.ts: triple-slash reference → ES import (TS 6 / Next 16 style)
eslint-config-next@16 ships a native flat config, so dropped the
@eslint/eslintrc + FlatCompat shim. eslint.config.mjs now imports
eslint-config-next/core-web-vitals + eslint-config-prettier/flat
directly.
Note on ESLint 10: bumped + reverted. eslint-config-next@16 still
has a transitive eslint-plugin-react@7 that uses the eslint-9
context API (getFilename on context); breaks under eslint 10.
Audit anticipated lockstep — but the transitive isn't ready yet.
Holding at eslint 9.x until upstream lands. Tracked in BACKLOG.
React Compiler safety rules (react-hooks v7) shipped with config-
next 16 surfaced ~89 legitimate findings (set-state-in-effect,
ref-during-render, immutability). Demoted the new rules to `warn`
so the codebase isn't blocked; triage tracked in BACKLOG §G.
Verified: tsc 0 errors, eslint 0 errors / 105 warnings (89 new
Compiler-rule warns + 16 pre-existing), next build clean, custom
server build clean, vitest 1315/1315.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ran the official @tailwindcss/upgrade tool:
- tailwind.config.ts → @theme directive in globals.css
- @tailwind base/components/utilities → @import 'tailwindcss'
- postcss.config switched from tailwindcss + autoprefixer to
@tailwindcss/postcss (autoprefixer baked in)
- focus-visible:outline-none → focus-visible:outline-hidden (the v3
utility was a footgun — outline still showed in forced-colors mode)
Reverted the migration tool's over-zealous variant="outline" →
variant="outline-solid" rename on CVA prop values; that rename was
meant for the Tailwind `outline:` utility, not our Button/Badge
component variants.
Swapped tailwindcss-animate (v3-style JS plugin) for tw-animate-css
(v4-native @import). Same utility surface (animate-spin, animate-in,
etc.), one fewer JS plugin in the bundle.
Fixed the upgrade tool's malformed dark variant
(@custom-variant dark (&:is(class *)) — `class` was being parsed as
a tag) to canonical &:where(.dark, .dark *).
Verified: tsc 0 errors, eslint 0 errors (16 pre-existing warnings),
vitest 1315/1315, next build clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three audit-flagged deps rejected on inspection (not parked-pending-
decision):
- @upstash/ratelimit — audit said "4 hand-rolled rate limiters"; actual
state is one centralized sliding-window limiter with 14 named policies.
- @faker-js/faker — both seed files are hand-curated specs keyed to test
selectors, not random fake data; faker would mean ADDING a factory.
- msw — vi.mock at the service-module boundary already gives determinism;
msw only helps when tests hit fetch() directly.
Adds tsc-staged.mjs to the done list. Updates parked list with concrete
rationale per item.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
