cd ..

$ cat ~/field-notes/presigned-urls-direct-uploads.md

Presigned URLs: Direct Uploads Without Handing Out Storage Keys

A browser uploads a video through your API. The API spends most of its time forwarding bytes to object storage while holding a connection open.

A direct upload moves those bytes from the browser to storage. Your backend still controls permission and completion; it just stops acting as a pipe.

Separate Permission from Transfer

For Amazon S3, a presigned URL grants a time-limited operation using the permissions of its signer. The recipient does not receive the signer's storage credentials. The URL itself is sensitive: anyone holding it can use its granted capability. See the S3 presigned URL documentation.

An application flow can be:

browser → backend: request an upload for this account
backend → database: create pending upload with a server-chosen key
backend → browser: return upload ID, URL, and required headers
browser → storage: upload bytes
browser → backend: request completion by upload ID
backend → storage: verify the stored object
backend → database: mark verified upload ready

Each arrow has a different responsibility. A successful byte transfer does not establish ownership, acceptable content, or readiness for other users.

The Server Chooses the Destination

An illustrative private staging key might be:

staging/accounts/account_42/uploads/random-upload-id

Build that key from authenticated server state. Store its relationship to the account and upload ID. Do not let a submitted filename choose the bucket, another tenant's prefix, or the key of an existing published object.

Keep the filename as display metadata after normalization. A name like invoice.pdf is neither a unique identity nor evidence of file type.

The signer should have only the storage permissions this flow requires. Bound issuance by account quotas and request limits so a valid user cannot create unlimited pending uploads.

Keep the Browser Contract Explicit

For a presigned PUT, the browser sends the file body and the headers required by that particular signature:

const response = await fetch(upload.url, {
    method: 'PUT',
    headers: upload.headers,
    body: file,
});

if (!response.ok) throw new Error('Upload failed');
await completeUpload(upload.id);

Configure storage CORS for the intended application origins, method, and headers. Do not attach your application's API authorization header to the storage request. AWS's upload guide shows the required match between signing and upload details.

Client-side size and type checks are useful feedback. The backend must enforce the actual acceptance policy after upload, including stored size, required checksum, and content inspection where appropriate. A declared content type is not a content scanner.

A Presigned URL Is Not Single Use

S3 permits reuse until a URL expires, and uploading to the same key can replace the existing object. Temporary signing credentials can also expire before the requested URL lifetime. These behaviors are documented in S3's URL lifecycle rules.

That creates a subtle completion race: you inspect the staging object, mark it ready, and the client overwrites it using the still-valid URL.

Design publication around an immutable object identity. For example, enable versioning and verify a specific version, then serve or copy that exact version to a final key the client cannot write. Another design binds the upload to a verified checksum and enforces conditional publication. The exact storage features differ; choose a protocol that cannot publish bytes other than the ones you validated.

Merely copying "whatever is at this key now" after inspecting it does not close the race.

Complete and Clean Up Deliberately

Make completion idempotent. Repeating completeUpload(id) should return the existing ready result, rather than creating another attachment. Reject a completion request from another account even if it supplies a real upload ID.

Leave failed validation private and record why it failed. Clean up abandoned staging objects and expired pending rows using a retention policy. For multipart uploads, include abandoned multipart state in cleanup too.

Avoid recording full signed URLs in logs or analytics. Record the upload ID, account, size, validation result, and final object identity instead.

Direct uploads reduce work on your API. Their reliability comes from the backend's permission and publication protocol, not from assuming a successful PUT means the file is ready.