Doc Storage Keys

The bug this exists to prevent

The natural key for an uploaded file is the thing you already have:

  documents/{orgId}/{documentId}/{originalFilename}

Two problems, and neither raises an error.

The filename is user data. People name files Q3 termination letter - Sarah.pdf and 2026 offer — Chen (final).docx. That name now lives in a storage key, which appears in logs, in CDN access records, in error traces, and in support screenshots. You have leaked the contents of the document via the path to it, and nothing about it looks like a leak.

The key is guessable. Document ids are frequently sequential, or exposed in URLs, or recoverable from an API. Anyone who learns one and can guess the filename can construct the key directly — and object stores serve keys, not sessions.

Rule 1 — a random slug, so knowing the id is not enough

Every key ends in a 16-byte random hex slug rather than the uploaded filename. If a document id leaks entirely, the full key still cannot be constructed.

This composes with whatever randomisation your store adds on top; it does not rely on it. Defence in depth is the point — a key that is unguessable for exactly one reason stops being unguessable when that reason changes.

Rule 2 — one layout, so lifecycle stages cannot collide

  documents/{orgId}/{documentId}/original/{slug}.{ext}
  documents/{orgId}/{documentId}/versions/v{n}/{slug}.{ext}
  documents/{orgId}/{documentId}/converted/{slug}.{ext}
  documents/{orgId}/{documentId}/signed/{slug}.{ext}
  documents/{orgId}/{documentId}/audit/{name}.json

The stage is a path segment, so a converted copy can never overwrite the original and a signed copy can never overwrite the draft. Where that has gone wrong elsewhere, the symptom is an executed contract quietly replaced by its unsigned version, discovered much later by someone opening it.

The org id is in the path so that a misrouted key is visible at a glance rather than requiring a database lookup to attribute.

The one exception, stated plainly

temporary/jobs/{jobId}/{filename} does carry the uploaded filename. It is the scratch path for in-flight processing, keyed by an unguessable job id, and it is meant to be short-lived.

It is called out here rather than buried because it is the one place the reasoning above does not hold: if you retain those objects, or log that path, the filename travels with it. Either expire them or route them through original/ instead.

Rule 3 — keys are paths, never URLs

These are addresses inside your object store. They are not public, not signed, and not directly fetchable. Handing one to a browser is a category error, and the naming here is deliberate so that a caller who does it is doing something obviously wrong rather than something that happens to work in development.

What this does NOT do

No uploading, no signing, no fetching, no store access of any kind. It generates and parses keys. Swap Vercel Blob for S3 or R2 without touching it.

It does not enforce access — see the ACL layer for that. An unguessable key is a defence in depth, not an authorisation model.

Verified

42 tests covering every layout, slug randomness and length, extension normalisation, round-tripping, and per-stage separation.

What they do NOT cover: there is no test asserting that a filename never reaches a durable key. The layout achieves it by construction, and the temporary-jobs path is a deliberate exception — but that is an argument, not a test, and it is worth saying so.