Chapter 20 — Frontend ↔ Backend File Handoff (Signed URLs)

The two ways to move a file between client and S3

There are exactly two patterns. Pick the right one for the use case.

Pattern A — Backend proxy

Client  ─────[ multipart upload ]────►  Backend (validate, scan)  ─────►  S3
Client  ◄────[ binary stream ]──────  Backend (read from S3)      ◄─────  S3

• Backend sees every byte.
• Bandwidth flows through your servers (you pay for it twice — ingress + egress).
• Easy to do AV scanning, transformation, policy checks inline.

Pattern B — Presigned URLs (recommended)

Client  ─────[ ask for a permission ]────►  Backend
Client  ◄────[ short-lived signed URL ]──  Backend
Client  ─────[ PUT bytes directly ]──────►  S3      (backend never sees the bytes)
 
Client  ─────[ ask for a download URL ]──►  Backend
Client  ◄────[ short-lived signed URL ]──  Backend
Client  ─────[ GET bytes directly ]──────►  S3

• Backend issues a signed URL that grants the client temporary permission to PUT or GET one specific S3 object.
• Bytes go client ↔ S3 directly. No bandwidth on your API server.
• Scales infinitely — even a 10 GB upload doesn't touch your container.

Generating a presigned PUT (upload) URL

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 
@Injectable()
export class S3Service {
  constructor(private readonly config: ConfigService) {}
  private s3

Notes:

• The backend chooses the key. Never let the client pass the S3 key. Otherwise, an attacker overwrites another user's file by guessing/leaking keys.
• expiresIn is short (5–15 minutes for uploads). The URL is a permission slip; long-lived permission slips get pasted into Slack and leaked.
• ContentType must match what the client sends. S3 will reject the PUT if the client uses a different Content-Type header. The frontend must pass it back exactly.
• The URL leaks the bucket name and key. That's fine, those are not secrets — but don't put PII in the key.

The frontend side — uploading with the signed URL

// React/Next/whatever — pseudo-code
async function uploadKyc(file: File) {
  // 1. Ask backend for a permission
  const { url, key } = await api.post('/kyc/upload-url', {
    contentType: file.

Notice that step 3 is essential — without it, your DB has no record of the file. See "Two-step upload" below.

Generating a presigned GET (download) URL

async getDownloadUrl(documentId: string, requesterId: string) {
  const doc = await this.documentModel.findByPk(documentId);
  if (!doc) throw new NotFoundException();

The authorisation check is the most important line. The signed URL is a bearer token — anyone with it can download — so the only thing standing between an attacker and "every customer's passport" is the if (doc.owner_id !== requesterId) check.

The expiration trap — and how to handle it

This is the question that motivated this chapter:

"Providers like S3 file links have a session — the link does not work after expiration. How do we handle this?"

The signed URL is valid for the expiresIn window only. After that, S3 returns 403 Forbidden even to the user who legitimately owns the file. Forgetting this leads to two real-world bugs:

Bug 1 — Storing the signed URL in the database

// ❌ NEVER do this
await this.documentModel.update(
  { download_url: signedUrl },
  { where: { id: doc.id } },
);

Within 10 minutes that URL is dead. You now have a column full of garbage. Generate the URL at the moment of use, never persist it.

Bug 2 — Sending a signed URL by email

// ❌ NEVER do this
await mail.send({ to: user.email, body: `Download: ${signedUrl}` });

The user reads the email two hours later. The link is dead. Worse — anyone who forwards the email can download the file (during the validity window).

The right pattern: send a link to your app (https://app.example.com/documents/{id}/download). When the user clicks it, the backend checks auth and then redirects to a freshly-signed URL.

@Get('documents/:id/download')
async download(@Param('id') id: string, @Req() req, @Res() res) {
  const url = await this.s3

Bug 3 — Frontend caches the URL across navigations

// ❌ Loaded once at page mount, used 30 minutes later
const [url] = useState(await api.get(...));
<img src={url} />

The page is left open. The user clicks the image. 403.

The right pattern: catch the 403, request a fresh URL, retry once.

async function fetchSigned(documentId: string): Promise<string> {
  const { url } = await api.get(`/documents/${documentId}/download-url`);
  return url;
}
 
async

For an SPA with many images on screen, prefer a proxy endpoint instead — /documents/:id/download always works because the backend redirects to a fresh URL each time.

Two-step upload confirmation (and why you need it)

Pattern B uploads bytes directly to S3. The backend never sees the upload. So how does the backend know the file actually arrived?

Naïve approach — trust the client

Client → ask for upload URL
Client → upload to S3
Client → "I'm done" → backend writes a DB row

Risk: the client lies. The DB has a row pointing to an S3 key that doesn't exist.

Better — verify on confirmation

@Post('kyc/confirm-upload')
async confirm(@Body() body: ConfirmDto, @Req() req) {
  // 1. Verify the object exists and is small enough
  const head = await this.s3.headObject(body

Best — S3 event → Lambda → backend

S3 can fire an event the moment an upload completes:

S3 PutObject → S3 Event Notification → SQS → Worker (validate + write DB row + AV scan)

This is fully event-driven. The backend doesn't need a "confirm" endpoint — the event drives the workflow.

Multipart upload — for large files (>100 MB)

A single PUT is fine for files up to a few hundred MB. Beyond that:

• The connection might drop halfway and force a full restart.
• The browser has to keep all the bytes in memory.

S3 multipart upload splits the file into parts (5 MB minimum, up to 10,000 parts) and uploads them independently. If a part fails, only that part retries.

The browser-friendly way:

1. Backend calls CreateMultipartUpload → gets an UploadId.
2. Frontend asks backend for a presigned URL for each part: UploadPart with partNumber=1, 2, 3....
3. Frontend uploads parts in parallel. Each PUT returns an ETag.
4. Frontend sends the list of {partNumber, etag} to backend.
5. Backend calls CompleteMultipartUpload with that list.

Signed cookies — for batch downloads

Signed URLs work per-object. If a user is going to load 50 thumbnails on a page, generating 50 signed URLs is wasteful.

CloudFront signed cookies sign the user's browser session for a CloudFront distribution. The browser can then load any object behind that distribution for the cookie's lifetime, no per-URL signing.

Use this for paginated galleries, document viewers with many images, etc. Use signed URLs for one-off downloads.

Practical rules (print these on a sticky note)

1. Always Pattern B (presigned URLs) unless you have a specific reason for Pattern A.
2. Backend chooses the key. Never the client.
3. Upload URL: 5–15 min. Download URL: 5–15 min. Longer than that and you're inviting leaks.
4. Generate at the moment of use. Never persist a signed URL.
5. Never email or message a signed URL. Email a link to your app, redirect from there.
6. Authorise before signing the URL. The check that the requester owns the document goes BEFORE getSignedUrl().
7. Catch 403 on the frontend, refresh once, then retry. Don't loop.
8. Verify uploads on confirm. Use headObject to check size and existence.
9. Use S3 event notifications for fully event-driven post-upload processing.
10. Multipart upload for >100 MB. TUS / Uppy is the easy on-ramp.