Refs are capabilities
'v1_' plus 32 random bytes as base64url -- 256 bits of entropy, unguessable, minted fresh on every push. It is never derived from the content, so holding a ref IS the permission to act on the entry. There is no other access control layer, and none is needed: an unguessable name is the capability.Why not content hashes
The obvious design -- ref = sha256(contents) -- is wrong here for two reasons. It leaks: a content hash is guessable by anyone who has the content, so an adversary who suspects a particular document was stashed can hash it and probe for the ref -- an enumeration oracle against exactly the deployments this store serves. And it buys nothing: dedup is the usual payoff, and dedup does not work on ciphertext -- two uploads of the same encrypted file are two different byte streams.
Validation is path-traversal defense
Refs become filenames in the disk backend, so every ref entering a public method is validated against a strict whitelist -- /^v1_[A-Za-z0-9_-]{43}$/, character for character -- before it touches any storage. No normalization, no cleanup-and-continue: a malformed ref dies at the regex with InvalidRef, not at the syscall. A digest is stored per entry, but only to verify integrity on read -- it is never a lookup key.
Keep refs out of logs
A ref in a log file is a leaked capability. The store never logs refs or meta contents, and no error message ever contains one -- messages describe the failure class, and the caller already holds the identifiers it passed in. The same rule binds the embedding application: log counts and error codes, never identifiers.