Spec, version 1
Vault format, version 1
Files
All in the KeyJar data directory ($KJ_HOME, else the
platform data dir, for example ~/.local/share/keyjar), mode
0700. First run creates the directory with that mode and sets it on a
directory that was already there. Every file KeyJar creates in it is
mode 0600, vault.lock included.
| File | Writer | Holds key material |
|---|---|---|
vault.kjv |
any process, under the lock | Yes, encrypted |
vault.kjv.prev |
any process, under the lock | Yes, encrypted. The save before the current one |
vault.kjv.corrupt.<unix seconds> |
kj restore-prev |
Yes, encrypted. A damaged file kept for inspection. One per restore, never replaced |
vault.lock |
nobody (lock target only) | No |
usage.log |
any process, append only | No |
license.json |
kj license activate, and a re-check that returns
"revoked" |
No |
The vault key is 32 random bytes in the OS keychain, service
keyjar, account vault:<vault_id>.
One more file can exist outside this directory.
kj recovery export <path> writes a recovery file
where the user says. It holds the vault key in plain text. See
Recovery.
vault.kjv
One JSON object on one line, mode 0600.
{"keyjar":"vault","format":1,"min_reader":1,"vault_id":"<uuid>","generation":42,
"nonce":"<base64, 24 bytes>","body":"<base64 ciphertext>"}- Cipher: XChaCha20-Poly1305 with a fresh random nonce per write.
- Associated data: the string
keyjar-vault|<format>|<min_reader>|<vault_id>|<generation>. - Subkeys: HKDF-SHA256 over the vault key with info
kj/body/1,kj/secret/1,kj/fingerprint/1.
The decrypted body is JSON.
{"schema":1,
"keys":[{"id":"<hex>","provider":"openai","label":"work","aliases":[],
"preview":"sk-proj-…Xk2a","projects":[],"created":null,"expiry":null,"spend":null,
"added_at":1700000000,"last_resolved":null,"sightings":[],"notes":"",
"reminded":[],"metadata_checked":null,
"fingerprint":"<hex, 16 bytes>",
"sealed":{"nonce":"<base64>","ct":"<base64>"}}],
"batches":[{"id":"b_7f3a","at":1700000000,"edits":[["<path>","<VAR>","<key id>","kj://openai/work"]]}]}sealedis the key, encrypted again under the secret subkey with the record id as associated data. Listing decrypts the body and no secret. Resolving decrypts exactly one.fingerprintis HMAC-SHA256 under the fingerprint subkey, truncated to 16 bytes. It answers "is this key already stored" without decrypting anything.metadata_checkedis the time the key's provider last answered a metadata request about it, or null. A reader treats a record without the field as null.auto_fillis the person's answer to "may KeyJar ask each key's own provider about it":"Off", or{"On":{"granted_at":1700000000}}. It sits besidekeysandbatches, and is left out until somebody answers. A reader treats a body without it as unanswered and sends nothing. A build from before the field drops it on its next write, which takes the answer back and never grants one.remindedlists the reminders already handed out for this key. It lives in the vault because two programs deliver reminders, the tray app andkj remind --check, and the vault lock is what stops both from showing the same one.
Three version numbers exist because they change for different reasons.
formatis the version of the build that wrote the envelope and the cryptography.min_readeris the oldestformata build needs in order to read this file correctly. A writer raises it only when an older reader would misread the file, not when the older reader would merely miss a field.schemacovers the body.
Reading
Read the whole file, check the versions, fetch the vault key, decrypt. No lock. Writers replace the file by rename, so a reader gets the old file or the new one.
The version check runs on the cleartext envelope, before any
decryption. F is the format the build knows.
| File says | The build |
|---|---|
min_reader > F |
Reads nothing and writes nothing. kj get exits 4. |
format > F, min_reader ≤
F |
Reads. kj get and kj run work. Every write
is refused, because a rewrite would drop fields this build does not
know. |
format ≤ F |
Reads and writes. |
A writer that raises schema also raises
format, so this one check on the envelope covers the body
too. A build that still meets a body with a schema above
its own treats the file as read-only.
The associated data is built from the format and
min_reader the file states, not from the build's own, so a
newer file still decrypts.
Writing
Every mutation runs the same steps.
- Take an exclusive OS file lock on
vault.lock. The OS releases it if the process dies. A process that waits 5 seconds for the lock gives up. - Delete any
vault.kjv.tmp.*left by a crashed writer. - Read and decrypt the current file. This is the only state the change is applied to. Stop here if the file is read-only for this build.
- If
schemais older, copy the file tovault.kjv.schema<N>.bak(ciphertext), then run the migrations in memory. - Fold the usage log (below).
- Apply the change. If the body is the same as it was read, including
after the fold, skip to step 10 and write nothing. Otherwise increase
generationby one. - Write
vault.kjv.tmp.<pid>with mode 0600 and fsync it. - Replace
vault.kjv.prevwith a hard link to the currentvault.kjv, or a copy where hard links are not available. The link is made asvault.kjv.tmp.<pid>.prevand renamed overvault.kjv.prev, so there is no moment without a previous save. - Rename the temp file over
vault.kjv. Fsync the directory. - Release the lock.
Step 6 skips the write for an unchanged body so that a repeated
command, such as kj add with a key already stored, does not
replace the previous save with a copy of the current one.
A crash before the rename leaves the old vault intact. A crash
between steps 8 and 9 leaves vault.kjv.prev as a second
name for the current save. A crash after the rename leaves the new one.
Two processes writing at once run one after the other, and the second
applies its change to the first one's result.
vault.kjv.prev always holds a complete earlier save,
because writers never change a file in place.
Migrations
migrations[N] is a pure function from the schema N body
to the schema N+1 body, both as JSON values. Opening a schema 1 file
with a schema 3 build runs two functions in memory. The file is
rewritten at the next mutation, not on open, so a read-only command
never changes the file.
usage.log
Resolving a key appends one line and nothing else.
<unix seconds> <key id>\n
Lines are under 100 bytes and written with one O_APPEND
write, so concurrent appends do not interleave. Readers merge the log
into last_resolved when they build a snapshot, taking the
latest stamp per key. A failed append never fails the resolve.
Folding, done inside step 5 of a write: rename usage.log
to usage.fold, read it, raise each record's
last_resolved to the latest stamp seen, and delete
usage.fold after the vault rename. A leftover
usage.fold from a crash is folded by the next writer. That
writer folds the leftover alone and leaves usage.log for
the write after it, because renaming the log over the leftover would
drop the leftover's stamps. Folding twice gives the same result because
it takes a maximum.
Known limit: an append that races the rename can land in
usage.fold after it was read and be lost. The cost is one
stamp, corrected by the next resolve.
First run
Neither a vault file nor a keychain entry exists. Only a command that
stores a key runs first run: kj add,
kj import, kj scan once the user agrees to
import at least one key, and quick-add in the app. A command that reads
(kj get, kj run, kj scan before
that answer, a list) creates nothing, not the directory, the lock file
or a key, and a resolve exits with code 3. A reader that could make a
vault would leave an empty one, with a keychain entry, wherever an agent
helper happened to run kj get.
The process takes vault.lock, checks again that no vault
file exists, and only then generates a vault id and a vault key, stores
the key in the keychain, and writes the empty vault with
generation 1. The key is stored before the file is written.
A crash between the two leaves a keychain entry no vault uses, where the
other order would leave a vault no key opens. Two first runs at the same
moment produce one vault and one key, and the second process opens what
the first one made.
This is the only place a vault key is generated. A vault file with no keychain entry never gets a new key.
Recovery
Damaged vault file. kj restore-prev
takes the lock and checks two things before it changes anything.
vault.kjv.prev must decrypt with the key in the keychain.
vault.kjv must be damaged: it does not parse as an
envelope, or it parses and decrypts with neither the previous save's key
nor the key the keychain holds for its own vault_id. The
command refuses in every other case:
- a vault file that opens, because the previous save is one change behind and restoring it would lose that change
- a vault file from a newer format, whether this build may read it or not, because this build cannot tell a newer file from a damaged one
- a previous save that is missing, does not decrypt, or belongs to another vault
Then it gives the damaged file a second name,
vault.kjv.corrupt.<unix seconds> (a hard link, or a
copy), and renames vault.kjv.prev over
vault.kjv. A name that is taken is never reused: the
command adds .1, .2 and so on, so every
restore keeps its own damaged file. The one change made by the last
write is lost. The swap is that single rename, so a crash at any point
leaves a vault file in place and the command can be run again.
Lost keychain entry. The vault file is present and the keychain has no key for it, for example after an OS reinstall or a keyring reset. Every command stops with exit code 4 and creates nothing. The way back is the recovery file.
kj recovery export <path>writes the recovery file. It refuses to overwrite an existing file and sets mode 0600. The file is text:keyjar-recovery 1 vault_id: <uuid> code: <vault key, base32, with a checksum>
The code is 58 characters: RFC 4648 base32 (
A-Z2-7, no padding) over 36 bytes. Those are the 32 key bytes followed by the first 4 bytes of SHA-256 over the ASCII textkj/recovery/1and the key. A reader accepts lowercase, skips whitespace and-, and refuses anything that is not then exactly 58 characters. The checksum tells a mistyped code from one for another vault. It protects nothing.kjnever prints the code. Printing would leave it in terminal scrollback and in the transcript of any agent that ran the command.The file is the vault key in plain text. Whoever holds it and the vault file can read every key. The user moves it off the machine or prints it, then deletes it. KeyJar does not delete it.
kj recover <path>takes the lock, checks that the code decrypts the vault file, and only then writes the keychain entry. A code that does not open the vault changes nothing. Running it again when the entry is already present changes nothing. An entry that holds a different key is replaced, since the code has just been shown to open the vault.
Vault file missing, keychain entry present. The next command that stores a key runs first run with a new vault id and leaves the old entry alone.
Vault file missing, vault.kjv.prev
present. This is a damaged vault and not a first run. Every
command stops with exit code 4 and creates nothing, and
kj restore-prev brings the previous save back. A first run
here would make an empty vault, and its second write would replace the
previous save with that empty vault.