vault-share
End-to-end encrypted file sharing with a Go server and a React client: the browser encrypts each file, the key travels only in the part of the link that browsers never send, and the server stores ciphertext it cannot read.
Key metrics
- requests carrying the link secret, a decryption key, the file name or plaintext in one share and download
- 0 of 16
- security findings logged during development, a production readiness review and code review, 5 of them High; 63 fixed, 3 accepted, 4 open at Low or below
- 70
- black-box checks passing against the Docker Compose stack, and 30 browser checks
- 171
- Go tests passing under the race detector, S3 tests included, and 113 Vitest tests
- 173
A self-assessment against the OWASP Top 10:2025, on instances the tester ran: nine of the ten categories pass, and logging is partial because nothing alerts. Security test report
Problem and goals
vault-share shares files so that the server holding them cannot read them. The browser encrypts the file and its name before upload, and the key travels only in the part of the link after the #, which browsers never send. A link can expire after an hour, a day or seven days, allow 1 to 100 downloads, and burn after reading.
The specification asked for files up to 1 GiB, encrypted in streamed chunks instead of loaded into memory at once; an optional password the server never sees; an optional account that lists the files you shared without the server reading them; and a threat model and a self-assessment against the OWASP Top 10, written up as a report.
Encryption and decryption stream in 64 KiB records with constant memory, but the upload sends the ciphertext as one Blob, which browsers may keep in memory, so a file near 1 GiB can be heavy on a low-memory device. On download, Chromium-based browsers write the decrypted file straight to disk; other browsers hold it in browser storage until the download is complete. A compromised server could still send JavaScript that steals keys, as with most web-based encryption tools, and the server sees each file's size and when it is uploaded and downloaded, and can tell whether it has a password. The metadata holding the name is padded to whole KiB, so a name's length shows only beyond about 900 bytes. Monitoring and backups are left to the operator: the health check covers the database, the storage and free disk space but not the database's integrity, and nothing alerts or backs up automatically.
Architecture
The sender's browser encrypts the file and its name and uploads the ciphertext with an auth key derived from the link's secret, getting back the file id and a delete token. The sender passes the share link, /f/id#secret, to the recipient, and browsers never send the part after the #. On the server, Caddy terminates TLS and passes every request to vaultd, a Go service on chi, which keeps the encrypted names, token hashes and auth keys in SQLite and the ciphertext on local disk or in an S3 bucket. The recipient's browser derives the same keys from the link and signs the server's challenge with the auth key; vaultd checks the signature, counts one download and issues a one-time token, and the browser fetches the ciphertext and decrypts it, straight to disk in Chromium-based browsers.
Key decisions
-
D012 A published record format
Files are encrypted in the record format of RFC 8188, the
aes128gcmcontent encoding that Firefox Send used, with a 256-bit key: 64 KiB records, each sealed with AES-256-GCM, and a marked last record, so a changed, reordered or cut file fails to decrypt. Keeping the layout lets the RFC's section 3.1 test vector, with its 128-bit key, run unchanged. Where vault-share differs from Firefox Send it is stricter: it rejects a header with another record size or a key id, and an empty file still ends with a last record. -
D014 A download counts when its token is issued
A download is counted when a signed challenge is accepted and a one-time token issued, with a conditional UPDATE and the token insert in one transaction; the token is valid for 5 minutes and one use. Firefox Send counted a download when the stream finished and without atomicity, so parallel requests could exceed the limit and an aborted download cost nothing. In exchange, a download cut off by the network still uses a count. Challenges are stateless, 32 bytes with an HMAC tag under a key drawn at startup, so a flood of metadata requests has nothing to evict.
-
D019 The password wraps the secret in the link
With a password, the link carries the 16-byte secret wrapped with AES-256-GCM under a key that Argon2id derives from the password, at 64 MiB and 2 passes. The server is unchanged and never sees the password, though it can tell whether one exists: the download page asks for the metadata only after the right password is entered, and an entry kept in My files is 206 bytes with a password and 148 without. Firefox Send only re-keyed its server-side check with PBKDF2 at 100 iterations, so its link still carried the file key. Whoever holds the link can still guess offline, at Argon2id cost per guess, so a password needs at least 8 characters (F21).
-
D026 Account keys the server cannot open
The account password never leaves the browser. Argon2id turns it into a master key, from which HKDF derives the secret sent at sign-in, which the server hashes again with Argon2id, and a key that seals a random 256-bit account key. Each file shared while signed in gets an entry under the account key, bound to the file id, holding its secret, link key and delete token, so the server lists the files but only the browser opens their names. The split follows Bitwarden. A forgotten password loses the account, while the links it shared keep working.
-
D024 No public demo site
The project runs no public instance; a recorded demo and one command that starts the full stack stand in for it. An anonymous, end-to-end encrypted file host attracts malware and phishing, which the operator cannot inspect and can only answer by deleting links, and Firefox Send was shut down in 2020 for that reason. A public instance would also face the threat model's residual risks, quota filling and CPU saturation from many addresses, without protection upstream.
Challenges
-
Four of the five High findings were in the upload path
Four of the five High findings were about uploads (F1, F2, F3, F26); the fifth came from a later production readiness review, where a new database started over existing storage made cleanup delete every stored file (F47). The server's 60-second write timeout cut long uploads off before the reply reached the client (F3), which retried, and a second upload with the same owner token could overwrite the stored file, or delete it with a bad body (F2). Now stored content is never replaced, each transfer gets deadlines from its size, and a file takes one upload at a time. Before that rule, 40 uploads to one file took the server from 18 to 341 MiB on S3; with S3 uploads streamed instead of buffered, ten uploads to ten files moved it from 19 to 20 MiB (F26).
-
Limits checked before they were counted
Lockouts were asked before an attempt was checked and told after it, so attempts sent at once all got through. In tests, 40 wrong second-step codes on one ticket had 7 to 20 checked where the ticket allows 5, and 20 bad download signatures at once had 11 to 14 checked where 5 lock the client out (F38, F39). Now a ticket gives up an attempt in the statement that checks its count, and a lockout admits an attempt before checking it, refusing one while the failures counted and the attempts in flight could reach the limit; afterwards at most 5 codes are checked, and exactly 5 signatures. That fix first answered an attempt refused only because others were in flight with a 15-minute lockout; such an attempt now gets 503
busywithRetry-After: 5(F42). A later code review found the second step locked per account, so anyone who knew the password could shut the owner out of every sign-in and change. It is now counted per client, per known browser and for all other browsers together, and a change confirmed while signed in counts against that sign-in alone (F56). -
Showing that keys stay in the browser
A browser check records every request Chromium sends while a plain share is uploaded, downloaded and reopened, and searches each one, bodies included, for the fragment, the secret, the file and metadata keys, the file name and a slice of the plaintext: raw, as hex, as base64 at every alignment, percent-encoded and form-encoded. None appeared in the 16 requests; the auth key appears once, in the create request, by design. The assessment also found that the specification claimed the server keeps only a verifier of that key, while it keeps the key itself, as Firefox Send did, so a copy of the database can spend download counts, though not decrypt. The documents now say so (F20).