No description
  • Go 99.2%
  • Just 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Viktor Varland 9580cdd9a3
All checks were successful
ci/woodpecker/push/build Pipeline was successful
ci/woodpecker/tag/release Pipeline was successful
docs: changelog for v0.16.1
2026-10-30 13:34:49 +01:00
.just chore: sync the files wrangle manages 2026-10-15 09:35:26 +02:00
.woodpecker chore: sync the files wrangle manages 2026-10-20 21:23:18 +02:00
docs docs: name the whole origin in cred brig's answer 2026-10-29 10:46:48 +01:00
internal/stash feat: cred brig, a command's keys with where each may be sent 2026-10-29 10:46:34 +01:00
.gitignore feat: seal, enroll and open token stashes with age 2026-10-15 09:24:59 +02:00
audit.go feat: record every value handed out in the system journal 2026-10-27 22:14:22 +01:00
audit_test.go feat: track when each token stops working, and warn before it does 2026-10-28 10:18:56 +01:00
CHANGELOG.md docs: changelog for v0.16.1 2026-10-30 13:34:49 +01:00
config.go feat: have sage open stashes instead of handing over the identity 2026-10-28 09:33:06 +01:00
cred.go feat: cred brig, a command's keys with where each may be sent 2026-10-29 10:46:34 +01:00
cred_test.go feat: cred brig, a command's keys with where each may be sent 2026-10-29 10:46:34 +01:00
exec.go feat!: seal stashes as TOML, read strictly 2026-10-28 10:34:25 +01:00
exec_test.go fix!: resolve references only into the stash exec takes keys from 2026-10-28 09:23:30 +01:00
expiry.go feat: bind a key to the origins it may be sent to 2026-10-29 10:45:15 +01:00
expiry_test.go refactor!: stop reading stashes sealed as dotenv 2026-10-28 12:59:08 +01:00
go.mod refactor: open the editor through cli.OpenEditor 2026-10-30 13:32:59 +01:00
go.sum refactor: open the editor through cli.OpenEditor 2026-10-30 13:32:59 +01:00
justfile feat: seal, enroll and open token stashes with age 2026-10-15 09:24:59 +02:00
main.go refactor: open the editor through cli.OpenEditor 2026-10-30 13:32:59 +01:00
main_test.go feat: add enroll --all, for every stash the store has 2026-10-28 11:08:40 +01:00
README.md feat: cred brig, a command's keys with where each may be sent 2026-10-29 10:46:34 +01:00
sage.go refactor: drop the fallback for a sage agent that hands out the identity 2026-10-28 11:39:03 +01:00
sage_test.go refactor: drop the fallback for a sage agent that hands out the identity 2026-10-28 11:39:03 +01:00

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.