- Go 99.2%
- Just 0.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .just | ||
| .woodpecker | ||
| docs | ||
| internal/stash | ||
| .gitignore | ||
| audit.go | ||
| audit_test.go | ||
| CHANGELOG.md | ||
| config.go | ||
| cred.go | ||
| cred_test.go | ||
| exec.go | ||
| exec_test.go | ||
| expiry.go | ||
| expiry_test.go | ||
| go.mod | ||
| go.sum | ||
| justfile | ||
| main.go | ||
| main_test.go | ||
| README.md | ||
| sage.go | ||
| sage_test.go | ||
locker
A token stash that follows you between machines. Each stash is a TOML file
sealed with age, kept in a directory you already
sync — a dotfiles repo does nicely — and opened only by the machines enrolled
for it. The plaintext never touches disk: locker exec hands a command the
keys it names and no others, and locker env prints a whole stash as exports
for a shell to eval. moor points each
domain at its stash, so a wrapped tool gets that domain's token.
Install
Requires Go 1.26+ and just.
just install # builds and copies to ~/.local/bin ($XDG_BIN_HOME)
Usage
locker init # mint this machine's identity and list it in the store
locker pubkey # print its public key
locker machines # the machines listed, and their keys (--json)
locker enroll amedia laptop # let a listed machine open a stash (run on an enrolled one)
locker enroll amedia laptop age1… # or name its key, for a machine not listed
locker enroll --all laptop # every stash the store has (those listing it already are left alone)
locker edit amedia # decrypt into $EDITOR, re-seal what you save
# (a new stash is created, this machine enrolled)
locker edit amedia < tokens.env # or pipe it in whole: TOML, or a dotenv to convert
locker revoke amedia laptop # re-seal without it — then rotate the values
locker expires amedia NPM_TOKEN 90d # the day its token stops working (a date, Nd, or never)
eval "$(locker env amedia)" # global's exports, then amedia's
token=$(locker get global GITHUB_TOKEN) # one value, for scripts (amedia's, else global's)
locker exec -k GH_TOKEN=GITHUB_TOKEN -- gh pr list # one command, one key
locker cred git get # git's credential helper; locker cred aws: aws's credential_process
locker show amedia # one stash's values (--json)
locker list # stashes, their state here, who may open them (--json)
locker # status: identity, store, stashes (--json)
env is built to run unattended: a machine with no identity, a stash that does
not exist, or one this machine is not enrolled for prints nothing and exits 0,
so a shell switching into a domain never breaks over it. Only a stash this
machine should open and cannot read is an error.
get is the opposite: asked for one value by name, it fails out loud — a
stash or key not there, or a stash this machine is not enrolled for, is exit 1
— so $(locker get …) never quietly hands a script an empty string. It answers
what the stash's shell would hold: the stash's own value, else global's.
revoke is forward-only. The stash as sealed before stays in whatever history
synced it, readable by the dropped key; rotating the values and sealing the new
ones with locker edit is what actually revokes.
One command, its keys
env puts a whole stash in a shell, where everything started from it
inherits every key: the build, the dev server, an install script, whatever
dumps its environment into a crash report. exec hands keys to one command
instead:
locker exec -k GH_TOKEN=GITHUB_TOKEN -- gh pr list # VAR=KEY: renamed
locker exec -k TF_TOKEN -- terraform plan # VAR: the key of that name
locker exec -o NPM_TOKEN -- npm install # only where the stash has one
locker exec --all -- ./deploy # the whole stash
locker exec -r -- npm run dev # the references in the env
Keys come from the stash -s names, else $LOCKER_STASH — which moor sets
to the domain's stash on a switch — else global, read as get reads them.
Every -k must resolve, or nothing runs. An -o is for a tool used
everywhere that needs a key only in some places: where the stash lacks it, or
there is no stash to read, the command runs without it. locker then becomes
the command, leaving no process behind that holds the stash, so the exit
status and signals are the command's own.
Wrapped in a shell function, a tool gets its token wherever it runs and nothing else does:
(( $+commands[locker] )) && gh() { locker exec -k GH_TOKEN=GITHUB_TOKEN -- gh "$@" }
exec finds gh on PATH, never the function, so it does not recurse.
References
A value of the form locker:<stash>/<KEY> names a key instead of holding it.
A .env file of references holds nothing secret — it can be committed, read
by an agent, or auto-loaded by a framework, which only ever sees the string.
exec -r resolves the references the environment carries, so with moor
loading a project's env_file, locker exec -r -- npm run dev gives the dev
server the real values. Without -r they pass through as written: a wrapper
run inside the project gets only the keys it asks for.
The whole value is the reference; one inside a longer value is not resolved.
A reference resolves only into the stash exec takes keys from, and only to
a key that stash holds itself, not global's beneath it. The file is repo
content, so it may name keys but not choose the stash: a committed
NPM_TOKEN=locker:global/GITHUB_TOKEN would otherwise hand a dev server
your personal token. Anything else stops the command; -s names another
stash on purpose.
Tools that ask
A tool with a credential protocol of its own asks locker itself, when it
needs the credential, so no wrapper and no environment carries it: only the
tool gets it, never what the tool starts. Each is set up once, in the tool's
own config, and takes keys from -s, else $LOCKER_STASH, else global, as
exec does — the environment the tool runs in decides.
# gitconfig: git's credential helper, for one host
[credential "https://github.com"]
helper = !locker cred git -k GITHUB_TOKEN -u x-access-token
# ~/.aws/config: aws's credential_process
[default]
credential_process = locker cred aws
cred git answers git's get with the key's value as the password, and the
username -u names, else the one git sent; store and erase change
nothing, since the stash is where the value lives. cred aws answers with
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, both required, and
AWS_SESSION_TOKEN where the stash has one; --id, --secret and
--session name other keys, one aws profile each. A profile's session token
follows its id's name — --id CUE_AWS_ACCESS_KEY_ID takes
CUE_AWS_SESSION_TOKEN — so it never picks up another profile's. Both are
audited as cred, and warn of an expiring key on stderr, which git and aws
show.
cred brig answers brig, which asks for
the keys a command's policy names and the references in its environment, and
injects each into requests to the origins it is bound to. It answers in JSON,
values and bindings, and only to a pipe: never to a terminal, where the
values would land in scrollback. locker cred brig -h has the shape.
The stash
A stash is TOML. A key with nothing more to it is a string; a key with more is a table, whose value is one field among others:
GITHUB_TOKEN = "ghp_…"
[NPM_TOKEN]
value = "npm_…"
expires = 2027-01-27
bind = ["registry.npmjs.org=bearer"]
bind says where a key may be sent, for brig
to inject it into requests to those origins alone, so the command brig runs
holds a placeholder and never the value. Each is <origin>=<form>: a host,
https unless the origin names http, with a port where it is not the
scheme's own, and one of bearer, token, basic:<user>, basic-user or
header:<Name> for the header the key goes in. No wildcards: bind each
host. It lives in the seal, beside the value, because a binding someone
else could edit sends your token to their host.
It is read strictly. A field locker does not know, a value that is not a
string, or a key that is no variable name stops the seal and says which, so a
misspelt setting is never quietly ignored. locker edit hands a stash with
a mistake back to $EDITOR with the mistake on its first line; quitting then
seals nothing. Values are literal: nothing in one is expanded.
edit also takes a dotenv, piped in, and seals it as TOML.
Stashes were sealed as dotenv files, <stash>.env.age, until v0.12, which
converted each at its next seal. This locker no longer reads one: status
names any left, to open with v0.13 or delete.
Expiry
A token that expires stops working quietly: npm answers a dead one with a 404, as if the package were not there. locker can track the day each one stops working, and warn before it does:
locker expires amedia NPM_TOKEN 90d # as the token was issued: 90 days from today
locker expires global GITHUB_TOKEN 2027-01-27
locker expires amedia NPM_TOKEN never # stop tracking it
The day is kept inside the seal, as the key's expires (see
the stash); locker edit sets it by hand as well. expires
writes the stash out in locker's own layout, so comments in it are not kept.
An expiry belongs to the stash that sets the key: a key amedia sets over
global's carries amedia's expiry or none. From 14 days before the day, exec and get warn on stderr
for each key they hand out, naming the stash to record the new day in, and the
command still runs. env warns of nothing, since it runs in a shell hook.
status lists every key tracked, soonest first.
Rotating stays yours to do: locker edit the new value in, then
locker expires its new day.
Audit
Every value locker hands out — get, exec, env, show, and edit into
$EDITOR — is recorded in the system journal: which keys, from which stash,
the command exec ran, and which programs asked (the executable and pid of
locker's parent and grandparent, never their arguments, which may hold
anything). The values never are.
journalctl -t locker # everything handed out
journalctl -t locker LOCKER_KEY=NPM_TOKEN # one key
journalctl -t locker LOCKER_OP=exec -o verbose
get global/GITHUB_TOKEN, asked by bash[50355] in git[50351]
exec amedia/NPM_TOKEN, asked by zsh[4120] in alacritty[1032], for npm ci
journald stamps each entry with fields the sender cannot forge (_PID,
_EXE, _UID), and a user process cannot delete what it wrote, so the record
outlasts whatever asked. It shows what went where; it does not stop anything —
code running as you can still read an identity kept in a file, or run locker
while sage's keyring is unlocked.
Without journald (the mac) the line goes to syslog; a record that cannot be
written is dropped rather than failing the command waiting on the value.
Layout
The store is a directory of pairs, laid out as the secrets script left it,
with TOML sealed where that sealed a dotenv:
<stash>.recipients age public keys, each under a "# <machine>" line
<stash>.toml.age the sealed stash
machines every machine's public key, in the same format
machines is the store's list of who can be enrolled. locker init adds the
machine it runs on, by its short hostname, so once the store has synced a
machine already enrolled lets it in by name: locker enroll amedia laptop.
Running init again on a machine with an identity mints nothing and only
lists it — which is how a machine that predates the list joins it. A machine
that lists itself with a new key replaces its old one, and must be enrolled
again for the stashes sealed to that.
The stash named global is layered under every other: locker env amedia
prints global's exports first, so a key set in both takes amedia's. It is for
what every context should have — a personal token, an API key used
everywhere — and is listed even before it holds anything; locker edit global
starts it.
Each machine has one identity, ~/.config/locker/identity.txt (0600, never
synced). It is unencrypted on purpose: env runs inside a shell hook, where
nothing can ask for a passphrase.
Identity in sage's keyring
With sage, the identity can live in its keyring instead, so it is not on disk unencrypted:
sage keyring locker add # from ~/.config/locker/identity.txt
locker status # identity: sage's keyring, once the file is gone
rm ~/.config/locker/identity.txt
The identity never leaves sage. When the identity file is absent, locker sends the sage agent each stash's header and gets back that stash's file key, and the agent answers only the installed locker binary. So whatever reads locker's memory, or takes its place, gets the stashes it opens while the keyring is unlocked and nothing after it locks. It never gets the identity, which opens every stash and every earlier version of one in the store's history, until you rotate the values.
At a terminal, a locked keyring has sage keyring unlock ask for the keyring
passphrase. env never asks — it runs in a shell hook — so while the keyring
is locked it prints nothing, as on a machine with no identity; status and
the other commands say the keyring did not answer, or that it refused a locker
not installed where sage expects it. init refuses while the keyring holds an
identity, since a new one would shadow the one the stashes are sealed to.
Config
~/.config/locker/config.toml ($XDG_CONFIG_HOME), every key optional:
store = "~/.local/share/chezmoi/secrets" # default ~/.local/share/locker
identity = "~/.config/locker/identity.txt" # the default
--store, --identity and --config override them per run.
Moving from secrets
A store the secrets script wrote holds dotenv stashes, which this locker
does not read. Move it with locker v0.13, which does, per machine:
mkdir -p ~/.config/locker && chmod 700 ~/.config/locker
mv ~/.config/secrets/identity.txt ~/.config/locker/identity.txt
printf 'store = "~/.local/share/chezmoi/secrets"\n' > ~/.config/locker/config.toml
then convert each stash there with locker enroll <stash> <this machine>, which
re-seals it as TOML, before taking up this version.