Final audit pass on feat/berth-recommender (3 parallel Opus agents)
caught 5 critical and ~12 high-severity findings. All addressed in-branch;
medium/low items deferred to docs/audit-final-deferred.md.
Critical:
- Add filesystem-backend PUT handler at /api/storage/[token] so
presigned uploads stop 405-ing in filesystem mode (every browser-driven
berth-PDF + brochure upload was broken). Same token-verify + replay
protection as GET, plus magic-byte gate when c=application/pdf.
- Forward req.signal into streamExpensePdf so an aborted 1000-receipt
export no longer keeps grinding for minutes.
- Strengthen Content-Disposition filename sanitization: \s matches CR/LF
which would let documentName forge headers; restrict to [\w. -]+ and
add filename* RFC 5987 fallback.
- Lock public berths feed behind an explicit slug allowlist instead of
?portSlug= enumeration.
- Reject cross-port interest_berths upserts (defense-in-depth on top of
the recommender SQL port filter).
High:
- Recommender: width-only feasibility now caps length via L/W ratio so a
200ft berth doesn't surface for a 30ft beam request; total_interest_count
filters out junction rows whose interest is in another port.
- Mooring normalization follow-up migration (0034) catches un-hyphenated
padded forms (A01) the original 0024 WHERE missed.
- Send-out rate limit moved AFTER validation and scoped per-(port, user)
so typos don't burn a slot and a multi-port rep can't be DoS'd by
another tenant.
- Default-brochure path now blocks an archived row from sneaking through
the partial unique index.
- NocoDB import --update-snapshot honoured under --dry-run so reps can
refresh the seed JSON without committing DB writes.
- PDF export: orderBy desc(expenseDate); apply isNull(archivedAt) when
expenseIds are passed (was bypassed); flag rate-unavailable rows with
an amber footer instead of silently treating them as 1:1; skip the
USD->EUR chain when source already matches target.
- expense-form-dialog: revokeObjectURL captures the URL in the closure
instead of revoking the still-displayed one; reset upload state on
close.
- scan/page: handleClearReceipt resets in-flight scan/upload mutations;
Save disabled while upload pending.
- updateExpense re-asserts receipt-or-acknowledgement at the merged
row so PATCH can't slip past the create-time refine.
Plus the in-progress receipt upload UI for the expense form dialog
(receipt picker + "I have no receipt" checkbox + warning banner) and
a noReceiptAcknowledged flag on ExpenseRow for edit-mode hydration.
Includes the canonical plan doc (referenced in CLAUDE.md), the handoff
prompt, and a deferred-findings index for follow-up issues.
1163/1163 vitest passing. Typecheck clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two reviewer agents did a second-pass deep audit of the 21-commit
refactor. Eight findings; four fixed here (one was deferred with a
schema comment, three were 🟡 nice-to-haves left for follow-up).
Integration regressions (🟠 high):
- Outbound webhook `interest.berth_linked` now fires from the new
junction-add handler. Was emitting a socket-only event, leaving
external integrations silent post-refactor.
- Two new webhook events `interest.berth_unlinked` and
`interest.berth_link_updated` added to WEBHOOK_EVENTS +
INTERNAL_TO_WEBHOOK_MAP. PATCH and DELETE handlers now dispatch them
alongside the existing socket emits — lifecycle parity restored.
- BerthInterestPulse adds useRealtimeInvalidation for berth-link
events. The query key was berth-scoped while the linked-berths
dialog invalidates interest-scoped keys (no prefix match), so the
pulse went stale. Bridges via the realtime hook now.
Recommender semantic fix (🟠 medium-high):
- aggregates CTE: active_interest_count now filters on
`ib.is_specific_interest = true`, matching the public-map "Under
Offer" derivation. EOI-bundle-only links no longer demote a berth
to Tier C for other reps. Smoke test confirms previously-all-Tier-C
results now correctly classify as Tier A.
- Same CTE: `total_interest_count` uses COUNT(ib.berth_id) instead of
COUNT(*) so a berth with no junction rows reports 0 (not 1 from
the LEFT JOIN's NULL-right-side row). Prevents heat over-counting.
Data integrity (🟠):
- AcroForm tier rejects negative numerics in coerceFieldValue (was
letting through `length_ft="-50"` which would poison the
recommender feasibility filter on apply).
- FilesystemBackend.resolveHmacSecret throws in production when
storage_proxy_hmac_secret_encrypted is null. Dev still derives from
BETTER_AUTH_SECRET for ergonomics; prod must explicitly configure.
- Documented the circular FK between berths.current_pdf_version_id
and berth_pdf_versions.id. Drizzle's `.references()` can't express
the cycle so the schema column is plain text + a comment; the FK
is authoritatively maintained by migration 0030.
Tests still 1163/1163. tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
15 of 17 findings from the consolidated audit (3 reviewer agents on
the previously-shipped phase commits). Remaining two are nice-to-have
follow-ups deferred.
Critical (data integrity / security):
- Public berths API: closed-deal junction rows no longer flip a berth
to "Under Offer" - filter on `interests.outcome IS NULL` so won/
lost/cancelled don't pollute public-map status. Both list +
single-mooring routes.
- Recommender heat: cancelled outcomes now count as fall-throughs
(SQL was `LIKE 'lost%'` which silently dropped them, leaving
cancelled-only berths stuck in tier A).
- Filesystem presignDownload returns an absolute URL (origin from
APP_URL) so emailed download links resolve from external mail
clients.
- Magic-byte verification on the presigned-PUT path: both per-berth
PDFs and brochures stream the first 5 bytes via the storage backend
and reject + delete on `%PDF-` mismatch (was only enforced when the
server saw the buffer; presign-PUT was wide open).
- Replay-protection TTL aligned to the token's own expiry (was a
fixed 30 min, but send-out tokens live 24 h). Floor 60 s, ceiling
25 days.
- Brochures unique partial index on (port_id) WHERE is_default=true
+ 0032 migration. Closes the read-then-write race in the create/
update transactions.
Important:
- Recommender SQL: defense-in-depth `i.port_id = $portId` filter on
the aggregates CTE.
- berth-pdf service: per-berth pg_advisory_xact_lock around the
version-number SELECT + insert. Storage key is now UUID-based so
concurrent uploads can't collide on blob paths. Replaces
`nextVersionNumber` with the tx-bound variant.
- berth-pdf apply: rejects with ConflictError when parse_results
contain a mooring-mismatch warning unless the caller passes
`confirmMooringMismatch: true` (force-reconfirm gate was UI-only).
- Send-out body: HTML-escape brochure filename in the download-link
fallback (XSS guard).
- parseDecimalWithUnit rejects negative numbers.
- listClients DISTINCT ON for primary contact resolution: bounds
contact-row count to ~2 per client.
Defensive:
- verifyProxyToken rejects NaN/Infinity expiries via Number.isFinite.
- Replaced sql ANY() with inArray() in interest-berths.
Tests: 1145 -> 1163 passing.
Deferred: bulk-send rate limit (no bulk endpoint today), markdown
italic regex breaking links with asterisks (cosmetic).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan §4.4 + §13: pure SQL recommender, no AI. Single CTE chain
(feasible -> aggregates) + JS-side tier classification, fall-through
cooldown filter, heat scoring, and fit ranking. Per-port settings via
system_settings layered over global + DEFAULT_RECOMMENDER_SETTINGS.
Tier ladder (default):
A : no interest history
B : lost-only history (still recommendable + boosted by heat)
C : active interest in early stage (open..eoi_signed)
D : active interest at deposit_10pct or beyond (hidden by default)
Heat (only for tier B):
recency weight 30 full @ <=30 days, decays to 0 @ 365 days
furthest stage weight 40 full when prior reached deposit
interest count weight 15 saturates at 5+
EOI count weight 15 saturates at 3+
Multi-port isolation enforced (§14.10 critical): the SQL filters by
port_id AND the entry-point function rejects cross-port interest
lookups with an explicit error. Fall-through policy supports
immediate_with_heat (default), cooldown, and never_auto_recommend.
15 unit tests covering tier classification, heat saturation, weight
tuning, zero-weight guard. Smoke-tested end-to-end via
scripts/dev-recommender-smoke.ts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
