Presigned upload flow

Issue a presigned PUT URL where every constraint is bound into the signature, not checked after the fact. The API generates a server-assigned UUID key (never caller-chosen), a short expiry (e.g. 60–300s), an allowed Content-Type (e.g. image/jpeg), and a max Content-Length (e.g. 5 MB) — all encoded in the presigned URL's policy/signature so S3 itself enforces them before writing a byte. A tampered URL (wrong content-type, oversize, expired) is rejected by storage with a 403/SignatureDoesNotMatch, not by application logic that fires after the bytes are already stored. This matters because the webhook fires after storage — if constraints are only checked there, a malicious client has already stored a script disguised as an image. Prove it: try uploading with a tampered content-type and an oversize payload and show storage rejects both before the webhook ever fires.

Configure the bucket so the browser uploads directly with no bytes through your API server — proxying ties one handler thread per upload for the full transfer (100 concurrent 100 MB uploads at 10 MB/s = 1000 thread-seconds of I/O). Set a minimal CORS policy: the exact allowed origin(s) (not `*`), the specific headers needed (`Content-Type`, `x-amz-*`), a short `Access-Control-Max-Age` for the preflight cache, and the allowed method `PUT`. Verify the flow: the browser sends OPTIONS preflight, receives CORS headers, then PUTs directly to the presigned URL. No file bytes touch your API — the server only sees the presign request and later the completion confirmation. Explain why `*` on a public bucket with no cookies is not a vulnerability but still wrong on a private bucket where presigned URLs carry the authorization.

Prevent key-clobber and replay abuse. If the caller chooses the object key (e.g. username or client-chosen filename), any authenticated user can overwrite another user's file by guessing the key, and can repeatedly PUT to the same key within the URL's TTL to replace a legitimate file after the webhook already confirmed it. Fix it: the presign endpoint generates a UUID key, stores a pending-upload record `{uploadId, key, expectedContentType, maxSize, createdAt, status:'pending'}`, and the completion webhook only marks the upload whose UUID matches. The pending record also holds the expiry window so you can reason about the race: a client could upload a valid file, pass verification, then re-PUT a different file to the same key before the URL expires. Mitigate by storing the expected ETag contract or by short expiry + one-time-use semantics (invalidate the pending record on first completion). Document the tradeoff: short expiry shrinks the race window but forces clients to re-presign more often.

Verify receipt server-side — never trust the client's 'I uploaded' message. The completion webhook (or client-triggered POST /uploads/:id/complete) fetches the object's metadata from storage (HEAD Object → ETag + Content-Length) and confirms it matches the expected values from the presign contract (content-type, size within max, key matches pending record). The webhook is idempotent: a retry or duplicate delivery (network retry, S3 event fan-out) with the same uploadId is a no-op, not a double-process. Two failure modes matter: (1) substitution — HEAD shows a different ETag/size than expected because the client re-PUT a different file within the TTL window (see milestone 3); (2) ghost completion — the client reports completion but the object never arrived (HEAD 404). Both are rejected, never marked 'received'. Document why ETag verification breaks multipart uploads (composite ETag from part hashes) and what you'd do there instead (store part ETags or switch to S3 Multipart Complete checksum).

Prove it under production-like load and make it observable when it misbehaves. Load-test the full flow (presign → direct PUT → completion) with many concurrent clients (e.g. 50 parallel uploads, mixed valid/invalid, expired URLs, oversize attempts) and find the QPS where the presign endpoint or webhook — not the direct-to-storage PUT — is the bottleneck. Emit RED metrics (presign rate, presign error rate, completion rate, webhook verification duration p50/p99) and a trace span for the HEAD verification so the flag system's own latency is visible in the waterfall. Then work an incident: inject a flood of expired-URL retries or a burst of oversize uploads and watch the presign error rate spike while direct PUTs stay healthy. Detect it from your dashboard (not logs), mitigate (shorter expiry / size reject at presign / rate-limit presign), and write a 5-line post-mortem whose prevention is not 'increase storage'.