KeyJar specs

Spec, version 1

kj:// reference, version 1

A kj:// reference is a string that names a stored API key without containing it. It is safe to commit, paste and copy into worktrees. This document is the public contract. Any tool may write references and may resolve them by calling kj.

Grammar

reference = "kj://" provider "/" label
provider  = slug
label     = slug
slug      = start *62( start / "." / "_" / "-" )
start     = %x61-7A / DIGIT          ; a-z 0-9

Examples: kj://openai/work, kj://anthropic/main, kj://mistral/acme-api.

Rules

  1. One spelling. Lowercase only. No percent-encoding, no case folding, no trailing slash, no surrounding whitespace. A resolver compares bytes. grep -r 'kj://openai/work' finds every use.
  2. Identity is (provider, label). A reference has no project, path, vault id or version. One key used in 138 files is one string.
  3. Any slug is a valid provider. KeyJar's provider table adds detection and metadata for the providers it knows. A key from an unknown provider is stored under the slug the user picks, or other.
  4. Renames do not break references. When a label changes, the old label stays as an alias of the same key and keeps resolving. A vault refuses a new label that equals another key's label or alias for the same provider.
  5. The reference is the whole value. OPENAI_API_KEY=kj://openai/work is a reference. URL=https://x/?key=kj://openai/work is plain text and passes through unchanged. Surrounding dotenv quotes are stripped before the check. A value that starts with kj:// and is not a valid reference is an error, not plain text.
  6. Unknown syntax stops the resolver. Version 1 defines no ?query and no #fragment. A resolver that meets a valid reference followed by either one exits with code 5 and resolves nothing. Later versions add features only through those two positions, so a version 1 resolver never returns the wrong key for a newer reference. The part before the first ? or # must itself be a valid version 1 reference. If it is not, the exit code is 2.
  7. A reference never reaches a program. kj run resolves every reference before it starts the child. If one fails, the child does not start.

Resolver contract

kj get <reference> writes the key and one newline to stdout and exits 0. It writes nothing else to stdout.

kj run [--env-file <path>]... -- <command> reads env files and the current environment, resolves every value that is a reference, and starts the command. On Unix it replaces itself with the command.

Values are read as VAR=value with an optional export, one pair of surrounding quotes and a # comment. Only a value that would be set is checked as a reference.

Exit code Meaning
0 Resolved
2 Not a valid reference, or kj run found a variable as a reference in one env file and as another value in another, or only in an env file that is read in some modes
3 No key has this provider and label. This includes a machine with no vault yet: resolving never creates one
4 The vault cannot be read (no keychain, missing vault key, damaged file, or a file that needs a newer kj)
5 Valid reference that uses a feature this resolver does not support
1 Anything else

Error text goes to stderr. It never contains key material, and it never repeats the text that was passed as a reference, because people paste keys by mistake.

What a reference does not promise

Resolving puts the real key in the child's environment or on stdout. A process running as the same OS user can read both. A reference keeps the key out of files. It does not keep the key from an agent that runs as you.

Stability

Rules 1 to 7, the grammar and the exit codes do not change within version 1. Provider slugs that KeyJar ships are never renamed.