Blob Write Mode

The bug this exists to prevent

The original code was reasonable-looking:

  if (blobEnabled) {
    if (privateToken) return writePrivate();
    return writePublic();      // fall back so the write still succeeds
  }
  return writeLocal();

A fallback that keeps working when configuration is incomplete is normally good practice. Here it is the whole defect. When the private store's token was absent — a rotated credential, a new environment, an env pull that returned an empty string — the write succeeded, the document was stored, the app showed no error, and the bytes were at a public URL.

Every observable signal said it worked. The upload returned 200. The document appeared in the list. It opened correctly when clicked. The only difference was that anyone holding the URL could fetch it too, and nothing anywhere said so.

The rule: blob-enabled with no private token is a HARD ERROR

resolveBlobWriteMode() returns 'private' or 'local', and throws for the third case. There is no public mode in the return type — the type itself makes the old fallback unrepresentable.

• blob enabled + private token present → 'private'
• blob enabled + private token absent → throws
• blob not enabled → 'local' (the ordinary development path)

Refusing is correct even though it takes the feature down. A failed upload is a support ticket; a public one is a disclosure you find out about later, from someone else.

Why this is a package and not four lines you write yourself

It is four lines. The value is knowing which four, and the ordering — that "is a blob store configured" and "can I write privately" are two separate questions, and that answering the second with a fallback is what published the documents.

Anyone can write this correctly once they have seen it go wrong. This is the cheapest available way to see it go wrong.

What this does NOT do

No I/O. It does not write, upload, or talk to any storage provider. It resolves two env-derived booleans into a decision, so the security-relevant branch is unit-testable without a blob store, a network, or a credential.

Verified

4 tests: the production path, the development path, and — the one that matters — that the blob-enabled-without-private-token case throws rather than returning anything at all.