File upload pipeline: spike + endpoint skeleton (Phase 1, in progress)

Lays groundwork for closing the file-upload gap discovered while wiring
the org-contact custom fields. Currently no file fields in the form
actually persist to CiviCRM -- the renderer FileList drops at the
onSubmit JSON.stringify, and there is no /api/upload route or
Attachment.create call anywhere.

This commit adds:

1. scripts/spike-attachment-upload.mjs

   One-off spike to answer the open question that gates the rest of the
   work: does APIv4 Attachment.create accept an unbound upload, or must
   we attach to an entity at create time? If unbound works we can use
   the planned two-step pattern (upload returns a file id; submit
   references it). If not, activity-bound file fields need a different
   flow because the activity does not exist yet at upload time.

   The spike also exercises the Contact.update + .file_name read-back
   path against the Certificate_of_Incorporation field on a real org
   contact, then cleans up after itself.

   Usage:
     node --env-file=.env.local scripts/spike-attachment-upload.mjs \
       --org-id=<id> [--keep]

2. app/api/upload/route.ts

   Structural pieces that do not depend on the spike outcome:
     - multipart parsing via Request.formData()
     - 5 MB hard cap (under Amplify Lambda 6 MB sync payload limit)
     - MIME allowlist (PDF, DOC/DOCX, XLS/XLSX, JPEG/PNG/GIF/WEBP)
     - magic-byte sniff to cross-check the client-reported MIME
     - filename sanitization (path traversal scrub, length cap)
     - checksum verification, rate limiting, field-ref allowlist
     - STUB-mode short-circuit for local dev without live Civi
     - explicit 501 where the Civi Attachment.create wiring goes,
       with a comment pointing at the spike that resolves it

   Result: endpoint compiles, registers as a Next route, returns 501
   with a clear message; build passes; nothing wired into the frontend
   yet so the existing form is unaffected.

Phase 2 (renderer upload-on-pick), Phase 3 (submit reshape), Phase 4
(promote Certificate_of_Incorporation to editable) follow once the
spike output picks the Attachment.create variant.

app/api/upload/route.ts

@@ -0,0 +1,233 @@
+/**
+ * POST /api/upload
+ *
+ * Multipart endpoint that accepts a single file plus the form's auth pair
+ * (cid + cs) and the target Civi field reference. Verifies, validates,
+ * stores in CiviCRM via Attachment.create, returns { id, file_name }.
+ *
+ * The form's file renderer calls this on file-pick (not at submit time)
+ * so submit can stay a simple JSON POST. The returned { id, file_name }
+ * is what gets put into RHF state and ultimately submitted as the field
+ * value — the same shape /api/data uses for prefill, so the renderer's
+ * FilePriorIndicator works unchanged for fresh uploads too.
+ *
+ * Request: multipart/form-data with parts:
+ *   - file       the binary
+ *   - cid        contact id (form auth)
+ *   - cs         checksum    (form auth)
+ *   - fieldRef   the Civi field reference, e.g. "Stage_1.Vision_Upload"
+ *                or "Food_Co_op_Organizing.Certificate_of_Incorporation"
+ *
+ * Response: { id: number, file_name: string }  OR  { error: string }
+ *
+ * STUB MODE: if CiviCRM env vars are unset, returns a fake id + the
+ * uploaded filename so frontend dev works without a live CRM.
+ */
+
+import { NextResponse } from "next/server";
+import { verifyChecksum } from "@/lib/civicrm";
+import { allFields } from "@/config/form";
+import { rateLimit, clientIp } from "@/lib/rate-limit";
+
+// 5 MB hard cap. Sits under AWS Amplify Lambda's 6 MB sync invocation
+// payload limit with headroom for multipart envelope overhead.
+const MAX_BYTES = 5 * 1024 * 1024;
+
+// Per the v1 spec: PDF, DOC/DOCX, XLS/XLSX, common image types.
+const ALLOWED_MIME = new Set<string>([
+  "application/pdf",
+  "application/msword",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.ms-excel",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+]);
+
+// Magic-byte sniff for the most common forgeries. Don't trust client-
+// reported MIME alone — a renamed .exe shouldn't slip past us on the
+// strength of a "Content-Type: application/pdf" header.
+function sniffMime(bytes: Uint8Array): string | null {
+  if (bytes.length < 8) return null;
+  const b = bytes;
+  // %PDF
+  if (b[0] === 0x25 && b[1] === 0x50 && b[2] === 0x44 && b[3] === 0x46) {
+    return "application/pdf";
+  }
+  // PK (ZIP container — docx/xlsx)
+  if (b[0] === 0x50 && b[1] === 0x4b && (b[2] === 0x03 || b[2] === 0x05 || b[2] === 0x07)) {
+    return "application/zip"; // accept-with-allowlist handles docx/xlsx
+  }
+  // OLE compound (legacy doc/xls)
+  if (
+    b[0] === 0xd0 && b[1] === 0xcf && b[2] === 0x11 && b[3] === 0xe0 &&
+    b[4] === 0xa1 && b[5] === 0xb1 && b[6] === 0x1a && b[7] === 0xe1
+  ) {
+    return "application/x-ole-storage";
+  }
+  // JPEG
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "image/jpeg";
+  // PNG
+  if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return "image/png";
+  // GIF
+  if (b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38) return "image/gif";
+  // WEBP — "RIFF????WEBP"
+  if (b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+      b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) {
+    return "image/webp";
+  }
+  return null;
+}
+
+// Office formats (docx/xlsx) sniff as application/zip via PK header but
+// are allowed at the client-reported MIME level. The mime check below
+// keeps both axes honest: client mime must be in ALLOWED_MIME, AND the
+// magic bytes must be plausible for that mime.
+function mimePlausible(clientMime: string, sniffed: string | null): boolean {
+  if (!sniffed) return false;
+  if (sniffed === clientMime) return true;
+  // docx/xlsx are zips under the hood — accept the alias.
+  const zipAliased = new Set([
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ]);
+  if (sniffed === "application/zip" && zipAliased.has(clientMime)) return true;
+  // Legacy doc/xls share the OLE container.
+  const oleAliased = new Set(["application/msword", "application/vnd.ms-excel"]);
+  if (sniffed === "application/x-ole-storage" && oleAliased.has(clientMime)) return true;
+  return false;
+}
+
+// Path-traversal scrub + length cap. Civi will store its own normalized
+// name internally; this is purely defensive.
+function sanitizeFilename(name: string): string {
+  const base = name.split(/[\\/]/).pop() ?? name;
+  // Drop control chars and anything that's not letters/digits/dot/dash/underscore/space.
+  const cleaned = base.replace(/[^\w.\- ]/g, "_").trim();
+  return cleaned.slice(0, 200) || "upload";
+}
+
+function isStubMode(): boolean {
+  return !(
+    process.env.CIVI_BASE_URL &&
+    process.env.CIVI_API_KEY &&
+    process.env.CIVI_SITE_KEY
+  );
+}
+
+const FILE_FIELD_REFS = new Set(
+  allFields
+    .filter((f) => f.type === "file" && (f.civiField || f.civiContactField))
+    .map((f) => f.civiField ?? f.civiContactField!),
+);
+
+export async function POST(req: Request) {
+  // Generous-but-not-unlimited: 5 uploads per minute per IP. Captures
+  // accidental retry loops without throttling legitimate use (a form
+  // with 4 file fields fills in well under a minute).
+  const ip = clientIp(req);
+  const rl = rateLimit(`upload:${ip}`, { capacity: 5, windowMs: 60_000 });
+  if (!rl.allowed) {
+    return NextResponse.json(
+      { error: "Too many uploads. Please wait a moment and try again." },
+      { status: 429, headers: { "Retry-After": String(Math.ceil(rl.resetMs / 1000)) } },
+    );
+  }
+
+  // Parse multipart. Next 16 supports Request.formData() natively.
+  let form: FormData;
+  try {
+    form = await req.formData();
+  } catch {
+    return NextResponse.json({ error: "Expected multipart/form-data." }, { status: 400 });
+  }
+
+  const cid = (form.get("cid") as string | null) ?? "";
+  const cs = (form.get("cs") as string | null) ?? "";
+  const fieldRef = (form.get("fieldRef") as string | null) ?? "";
+  const fileEntry = form.get("file");
+
+  if (!cid || !cs) {
+    return NextResponse.json({ error: "Missing cid or cs." }, { status: 400 });
+  }
+  if (!fieldRef || !FILE_FIELD_REFS.has(fieldRef)) {
+    // Refusing unknown fieldRefs blocks the obvious abuse vector: a
+    // client posting an upload pointed at an arbitrary Civi field.
+    return NextResponse.json({ error: "Unknown or non-file field reference." }, { status: 400 });
+  }
+  if (!(fileEntry instanceof File)) {
+    return NextResponse.json({ error: "Missing file part." }, { status: 400 });
+  }
+  if (fileEntry.size === 0) {
+    return NextResponse.json({ error: "Empty file." }, { status: 400 });
+  }
+  if (fileEntry.size > MAX_BYTES) {
+    return NextResponse.json(
+      { error: `File too large. Maximum is ${MAX_BYTES / (1024 * 1024)} MB.` },
+      { status: 413 },
+    );
+  }
+  const clientMime = fileEntry.type || "application/octet-stream";
+  if (!ALLOWED_MIME.has(clientMime)) {
+    return NextResponse.json(
+      { error: `File type ${clientMime} is not allowed.` },
+      { status: 415 },
+    );
+  }
+
+  const bytes = new Uint8Array(await fileEntry.arrayBuffer());
+  const sniffed = sniffMime(bytes);
+  if (!mimePlausible(clientMime, sniffed)) {
+    return NextResponse.json(
+      { error: "File contents don't match the declared type." },
+      { status: 415 },
+    );
+  }
+
+  const safeName = sanitizeFilename(fileEntry.name);
+
+  if (isStubMode()) {
+    console.warn(
+      "[upload:STUB] would Attachment.create",
+      JSON.stringify({ name: safeName, mime: clientMime, bytes: fileEntry.size, fieldRef }),
+    );
+    return NextResponse.json({ id: -1, file_name: safeName, stub: true });
+  }
+
+  // Auth: verify the form's checksum before doing anything Civi-side.
+  const ok = await verifyChecksum(cid, cs);
+  if (!ok) {
+    return NextResponse.json(
+      { error: "Link is invalid or has expired." },
+      { status: 401 },
+    );
+  }
+
+  // TODO(file-pipeline-phase-1): wire CiviCRM Attachment.create.
+  //
+  // Awaiting spike output from scripts/spike-attachment-upload.mjs to
+  // determine which of two patterns to use:
+  //
+  //   A. Unbound: Attachment.create with no entity_table/entity_id, then
+  //      use the returned id as the field value at submit time. Preferred.
+  //
+  //   B. Bound-at-upload: Attachment.create requires entity_table +
+  //      entity_id. For contact-bound fields (Food_Co_op_Organizing.*)
+  //      we can bind to the org contact. For activity-bound fields the
+  //      activity doesn't exist yet — we'd need to attach to the org
+  //      contact temporarily, then re-link to the activity post-create
+  //      (or restructure submit to two-phase: create activity, then attach).
+  //
+  // Until the spike resolves, this endpoint returns 501 so it can't
+  // silently confuse the frontend.
+  return NextResponse.json(
+    {
+      error:
+        "Upload pipeline pending: CiviCRM Attachment.create wiring blocked on spike. " +
+        "See scripts/spike-attachment-upload.mjs.",
+    },
+    { status: 501 },
+  );
+}