KeyJar specs

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>"}

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"]]}]}

Three version numbers exist because they change for different reasons.

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.

  1. 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.
  2. Delete any vault.kjv.tmp.* left by a crashed writer.
  3. 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.
  4. If schema is older, copy the file to vault.kjv.schema<N>.bak (ciphertext), then run the migrations in memory.
  5. Fold the usage log (below).
  6. 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 generation by one.
  7. Write vault.kjv.tmp.<pid> with mode 0600 and fsync it.
  8. Replace vault.kjv.prev with a hard link to the current vault.kjv, or a copy where hard links are not available. The link is made as vault.kjv.tmp.<pid>.prev and renamed over vault.kjv.prev, so there is no moment without a previous save.
  9. Rename the temp file over vault.kjv. Fsync the directory.
  10. 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:

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.

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.