fix(audit): non-Documenso backlog sweep — port-binding, NULLS NOT DISTINCT, custom merge tokens, company docs

Wave through the remaining audit-final-deferred items that aren't blocked
on the back-burnered Documenso work.

Multi-tenant isolation:
- Storage proxy ProxyTokenPayload gains optional `p` (port slug) claim;
  verifier asserts `key.startsWith(${p}/)`. Defense-in-depth against a
  buggy issuer in some future code path that mixes port scopes — every
  storage key generated by generateStorageKey() already prefixes the
  slug. document-sends opts in for 24h emailed download links; other
  callers continue working unchanged via the optional field.

DB schema reconciliation:
- Migration 0047 rebuilds system_settings unique index with NULLS NOT
  DISTINCT (Postgres 15+) so global settings (port_id IS NULL) are
  uniquely keyed by `key` alone. Surfaced + dedupe'd 65 duplicate
  (storage_backend, NULL) rows that had accumulated from race-prone
  delete-then-insert patterns in ocr-config / settings / residential-
  stages / ai-budget services. All four services converted to true
  onConflictDoUpdate upserts so the race window is closed.

API uniformity:
- Response shape standardization: 16 routes converted from
  `{ success: true }` to 204 No Content. CLAUDE.md documents the
  convention (`{ data: <T> }` for content, 204 for empty mutations,
  portal-auth retains `{ success: true }` for the frontend's auth chain).
- req.json() → parseBody() migration across 9 admin/CRM routes
  (custom-fields, expenses/export ×3, currency convert,
  search/recently-viewed, admin/duplicates, berths/pdf-{upload-url,
  versions, parse-results}). Uniform 400 error shapes for
  ZodError-flagged bodies.

Custom-fields merge tokens (shipped end-to-end):
- merge-fields.ts gains CUSTOM_MERGE_TOKEN_RE + helpers for the
  `{{custom.<fieldName>}}` shape.
- document-templates validator accepts the dynamic shape alongside
  the static catalog tokens.
- document-sends.service mergeCustomFieldValues resolver fetches
  per-port custom_field_definitions for client/interest/berth contexts
  and substitutes stored values keyed by `{{custom.fieldName}}`.
- custom-fields-manager amber banner updated to reflect that merge
  tokens now expand (search index + entity-diff remain documented
  design limitations).

/api/v1/files cross-entity filtering:
- Validator + listFiles + uploadFile accept companyId AND yachtId
  alongside clientId. file-upload-zone propagates both.
- New CompanyFilesTab component mirrors ClientFilesTab; restored as a
  visible Documents tab in company-tabs.tsx (was a hidden stub).

Inline TODOs:
- Reviewed remaining two TODOs (per-user reminder schedule, import
  worker handlers). Both are placeholders for future feature surfaces,
  not bugs — per-port digest works for every customer; nothing
  currently enqueues import jobs (verified). Annotated in BACKLOG.

BACKLOG.md updated to reflect what landed and what's still pending
(Documenso-related items still bundled with the back-burnered phases).

Tests: 1185/1185 vitest, tsc clean.

src/lib/storage/filesystem.ts

@@ -97,6 +97,17 @@ interface ProxyTokenPayload {
   f?: string;
   /** Optional content-type override. */
   c?: string;
+  /**
+   * Port-binding: the port slug the issuer was scoped to when minting
+   * the token. The verifier asserts the storage key starts with
+   * `${p}/`. Defense-in-depth against a buggy issuer in some future
+   * code path that mixes up port scopes — every storage key generated
+   * by `generateStorageKey()` already prefixes the port slug, so this
+   * check costs nothing and catches any drift. Optional for backwards
+   * compatibility with tokens minted before this field shipped; new
+   * tokens always include it.
+   */
+  p?: string;
 }
 
 function b64urlEncode(buf: Buffer): string {
@@ -165,6 +176,16 @@ export function verifyProxyToken(
   if (payload.op !== expectedOp) {
     return { ok: false, reason: 'op-mismatch' };
   }
+  // Port-binding: when the issuer attached `p`, assert the key starts
+  // with `${p}/`. This is the actual enforcement — `validateStorageKey`
+  // already prevents path traversal but doesn't constrain which port's
+  // namespace the key belongs to. Tokens without `p` skip this check
+  // (legacy / non-port-scoped issuers continue to work).
+  if (payload.p !== undefined) {
+    if (!payload.k.startsWith(`${payload.p}/`)) {
+      return { ok: false, reason: 'port-mismatch' };
+    }
+  }
   return { ok: true, payload };
 }
 
@@ -301,7 +322,14 @@ export class FilesystemBackend implements StorageBackend {
     validateStorageKey(key);
     const expiresAt = Math.floor(Date.now() / 1000) + (opts.expirySeconds ?? 900);
     const token = signProxyToken(
-      { k: key, e: expiresAt, n: randomUUID(), op: 'put', c: opts.contentType },
+      {
+        k: key,
+        e: expiresAt,
+        n: randomUUID(),
+        op: 'put',
+        c: opts.contentType,
+        ...(opts.portSlug ? { p: opts.portSlug } : {}),
+      },
       this.hmacSecret,
     );
     return { url: `/api/storage/${token}`, method: 'PUT' };
@@ -319,6 +347,7 @@ export class FilesystemBackend implements StorageBackend {
         op: 'get',
         f: opts.filename,
         c: opts.contentType,
+        ...(opts.portSlug ? { p: opts.portSlug } : {}),
       },
       this.hmacSecret,
     );

src/lib/storage/index.ts

@@ -38,6 +38,15 @@ export interface PresignOpts {
   contentType?: string;
   /** Filename used in Content-Disposition for downloads. */
   filename?: string;
+  /**
+   * Optional port slug to bind the token to. The filesystem proxy
+   * verifier asserts the storage key starts with `${portSlug}/` when
+   * present. S3 backend ignores this field (presigned S3 URLs carry
+   * their own signature scope). Pass it whenever the issuer is in a
+   * port-scoped request — `generateStorageKey()` already prefixes the
+   * slug, so this is the matching enforcement.
+   */
+  portSlug?: string;
 }
 
 export interface StorageBackend {
@@ -216,9 +225,10 @@ export async function presignDownloadUrl(
   key: string,
   expirySeconds = 900,
   filename?: string,
+  portSlug?: string,
 ): Promise<string> {
   const backend = await getStorageBackend();
-  const { url } = await backend.presignDownload(key, { expirySeconds, filename });
+  const { url } = await backend.presignDownload(key, { expirySeconds, filename, portSlug });
   return url;
 }