secrets is a library for keeping an application's secrets in one age-encrypted EDN file per environment, committed next to the code that uses them. The only secret you manage outside the repository is an age private key.
- The secrets are EDN: strings, numbers, sets, vectors, and nested maps.
- An application loads the whole map, or references single values from its EDN
config with
#secret/reqand#secret/opt. There is an Aero integration, and the plain map suits Integrant or Component. - A
bb secretstask creates, edits, and checks the encrypted file. - Every write also updates a committed manifest that holds no values. A diff of it shows which keys were added, removed, retyped, or changed, and CI can check it against the ciphertext without holding a key.
- A store is encrypted to your own key, or to a committed list of public keys so each teammate decrypts with their own.
- The private key is not kept in a plaintext file. On macOS it lives in the
login Keychain. Elsewhere, a password manager hands it over through a
command such as
op readorsecret-tool lookup. The library passes it toageon standard input and never writes it to disk.
The library shells out to the age binary and otherwise needs only Clojure or
Babashka. It is alpha software: the API, the commands, and the file formats
can still change between releases. It suits a solo developer or a small team
whose secrets change rarely. Security
says what it does not do.
Longer explanations live in the book under book/chapters
(Development shows how to build it), and
doc/threat-model.md is the design's decision rule.
Install age (brew install age, apt install age) and, for the bb secrets
task, Babashka. Babashka resolves :deps entries
through Java, so a JDK has to be on the PATH too. The library's only
runtime dependency is Clojure.
Nothing is published to Clojars yet. Depend on version 0.1.0 through git:
;; a release tag and the commit it names
io.github.kirahowe/secrets {:git/tag "v0.1.0" :git/sha "<commit the tag names>"}
;; Maven, once a release is on Clojars, or after `clojure -T:build install`
;; in a checkout
com.kirahowe/secrets {:mvn/version "0.1.0"}Replace the placeholder with the full commit that v0.1.0 names, or let the
initializer below write the coordinate for you.
Run the initializer from a checkout of this repository, in your project's directory. It previews by default:
bb -cp /path/to/secrets/src -m com.kirahowe.secrets.init --app myapp --keygenIn an empty project the preview lists two files it would create, a bb.edn
that declares the library and a secrets task and a template at
secrets/secrets.edn.example, plus an identity in the macOS Keychain. This is
the task it writes:
{secrets
{:doc "Manage encrypted secrets"
:requires ([com.kirahowe.secrets.cli :as cli])
:task
(cli/run!
{:app "myapp"
:default-environment :dev
:environments {:dev {:secrets-file "secrets/secrets.edn.age"}}}
*command-line-args*)}}Run it again with --apply to create those files. The initializer only
creates files that do not exist. For a bb.edn or deps.edn that is already
there, it prints the entries to add and leaves the file alone. In a project
with a deps.edn, the library goes into deps.edn and bb.edn reaches it
through a :local/root "." dependency, so the application and the task load
the same version.
The dependency it writes is the commit the checkout is at: :git/tag and
:git/sha when that commit is the release tag, and :git/sha alone otherwise.
A commit that is not a release tag has to be pushed before another machine can
resolve it. --env NAME names the environment (default dev), and --keygen
generates the identity and stores it in your login Keychain, as the item
com.kirahowe.secrets with account myapp. The key goes from age-keygen
into the Keychain without touching the disk. Without --keygen, run
bb secrets keygen later. An option's value is a separate argument:
--app myapp, not --app=myapp.
Back the identity up, for example in a password manager. It is not in git and cannot be recovered. This prints it:
security find-generic-password -s com.kirahowe.secrets -a myapp -w--keygen needs the macOS Keychain. On another system, store a key in your
password manager and tell the environment how to read it with :key-command
(Where the key lives).
Set a first value. From a terminal, set prompts for it with echo turned off:
bb secrets set :example/api-keyThe first set creates the ciphertext, secrets/secrets.edn.age, and its
manifest, secrets/secrets.edn.manifest. Check that they agree, then commit
bb.edn and everything under secrets/:
bb secrets verify✓ dev: manifest matches (secrets/secrets.edn.manifest)
Read the value from the application:
(require '[com.kirahowe.secrets :as secrets])
(def secret-values
(secrets/load-secrets "secrets/secrets.edn.age" {:app "myapp"}))
(secrets/get-secret secret-values :example/api-key)Day to day:
bb secrets edit # decrypt, open your editor, re-encrypt
bb secrets set :some/key # one value, from a hidden prompt or stdin
bb secrets rm :old/key # remove a value
bb secrets verify # check the manifest before committing
bb secrets doctor # report on the setup without printing values
bb secrets --help # every command; `bb secrets help set` for oneThe secrets task passes one map to com.kirahowe.secrets.cli/run!:
{:app "myapp"
:default-environment :dev
:environments
{:dev {:secrets-file "env/dev/resources/secrets.edn.age"}
:prod {:secrets-file "env/prod/resources/secrets.edn.age"
:recipients-file "env/prod/recipients.txt"}}}:app and :environments are required. :app names the app's macOS
Keychain item and is recorded in each manifest. A command that omits its
environment argument uses :default-environment.
| Environment key | Meaning |
|---|---|
:secrets-file |
Required. Path to the ciphertext. It must end in .age unless :template and :manifest are both set. |
:template |
What new opens in the editor. Default: the secrets file with .example in place of .age. |
:manifest |
Path to the manifest, or false to keep none. Default: the secrets file with .manifest in place of .age. |
:key-command |
A program and its arguments, as a vector of strings, that prints the private key. Commands read the key with it. |
:key-file |
A file that holds the private key, where keygen writes and commands read. |
:recipients-file |
A committed file of age public keys, one per line. When set, the store is encrypted to all of them. |
The config is validated before a command runs:
- A key the library does not know, at the top level or in an environment, is an error that names it, so a misspelling cannot be ignored silently.
:environmentsis a map from a keyword to a map, and:default-environmenthas to name one of them.- Every environment setting except
:key-commandis a string holding a local filesystem path, and:manifestmay also befalse. A leading~is expanded in every one of them.:key-commandis a vector of non-blank strings, and an environment sets at most one of:key-commandand:key-file. - A path that is URI-shaped, such as
https://…orfile:/…, is refused with:invalid-config(:disallowed-identityfor:key-file). - No file may serve two purposes. Environments may share a template, a key or identity file, or a recipients file. Two environments may name the same secrets file or manifest only when they name both the same, which makes them one store under two names.
Each environment is a separate encrypted file. Environments share the app's
Keychain key unless one sets its own :key-command or :key-file.
An environment's own key comes from the first of these that is set:
:key-command, a command that prints the key.:key-file, a file that holds it.- On macOS, the login Keychain item with service
com.kirahowe.secretsand the app name as its account.keygencreates it.
Off macOS, with neither setting, an environment has no key of its own. It can
still verify without a key, and the SECRETS_AGE_IDENTITY* variables still
supply one (Identity resolution).
:key-command works with any password manager that has a command to print
a stored value. The command runs without a shell and with no standard input,
and whatever it prints to standard output is the key. Store the key's
AGE-SECRET-KEY-1… line as the item's value. Some examples:
;; 1Password
{:key-command ["op" "read" "op://Private/myapp age key/password"]}
;; Bitwarden (with BW_SESSION set), or rbw
{:key-command ["bw" "get" "password" "myapp age key"]}
{:key-command ["rbw" "get" "myapp age key"]}
;; pass
{:key-command ["pass" "show" "myapp/age-key"]}
;; the Linux secret service (GNOME Keyring, KWallet)
{:key-command ["secret-tool" "lookup" "service" "com.kirahowe.secrets" "account" "myapp"]}keygen cannot write through a command, so store a new key with the password
manager's own tools. secret-tool reads the value from standard input, so a
key can go from age-keygen into the store without touching the disk:
age-keygen | grep AGE-SECRET-KEY | \
secret-tool store --label="myapp age key" service com.kirahowe.secrets account myappThe command runs each time a command or a load needs the key. A password manager that asks to be unlocked asks then.
A :key-file is a plaintext key on disk, written readable by its owner only.
Use it when nothing else is available, or for a throwaway key in tests.
(require '[clojure.java.io :as io]
'[com.kirahowe.secrets :as secrets])
(def m (secrets/load-secrets (io/resource "secrets.edn.age") {:app "myapp"}))
(secrets/get-secret m :database/url)
(secrets/get-secret m [:r2 :account-id]) ; a path into nested maps
(secrets/get-secret m :missing/key "default")The source is a filesystem path, given as a string, a File, or a Path, or
a classpath resource, given as the URL that io/resource returns. That URL
is a file: or a jar:file: one, so a resource inside an uberjar works.
Anything else, such as an HTTP URL or a file: string, is refused with
:reason :disallowed-source before it is opened.
The second argument chooses the identity. It is a path, or a map with
:identity-file, :key-command, :key-file, or :app.
Identity resolution gives the full order.
A vector path walks maps by key and vectors by integer index. It does not index into a string, set, or list, so a path that continues past such a value is not found.
Every failure is an ex-info whose data has a :reason keyword.
Failure reasons lists the ones worth branching on. A
failure about the source carries :source, which describes it by path, or by
scheme alone for a refused URL, and never repeats a refused value. An EDN
parse failure carries at most a line and column, never the text.
reader-literals returns the #secret/req and #secret/opt tag functions,
and merge-readers adds them to a readers map you already have:
(def readers
(secrets/merge-readers
{'env (fn [k] (System/getenv k))}
{:app "myapp" :resource "secrets.edn.age"}))
(clojure.edn/read-string {:readers readers} (slurp "config.edn"));; config.edn
{:db {:jdbc-url #secret/req :database/url}
:llm {:api-key #secret/opt :llm/api-key}
:auth {:admins #secret/req :auth/admins}}The options are :resource (a classpath resource name) or :file (a path),
plus :app, :key-command, :key-file, or :identity-file. Both tags take
a keyword or a vector path.
| Situation | #secret/req |
#secret/opt |
|---|---|---|
| The key is in the store | the value | the value |
| The key is not in the store | throws | nil |
| The secrets file is not found | throws | nil |
No identity was named and the app's key (its Keychain item or :key-file) is absent |
throws | nil |
| A named identity file does not exist | throws | throws |
| Decryption fails | throws | throws |
A readers map decrypts its store at most once, when the first tag is read, and keeps that result, or that decryption failure, for as long as the map lives. A config with no secret tags never touches the store or the key. After editing the store, build a new readers map.
Aero is not a dependency of this library. Add
it to your project, then read the config with this namespace's read-config
in place of aero.core/read-config:
(require '[com.kirahowe.secrets.aero :as secrets-aero])
(secrets-aero/read-config
"config.edn"
{:profile :dev
:secrets {:app "myapp" :resource "secrets.edn.age"}}):secrets takes the options reader-literals takes, and the tags behave the
same way. Every other key goes to Aero. Each call decrypts the store at most
once and keeps nothing afterwards, so the next call reads the store as it then
is. A config with secret tags read through aero.core/read-config directly
throws an error that names this function. read-config takes both arguments.
Without a :secrets option there is no store: #secret/req throws
:invalid-config, naming the option, and #secret/opt reads nil.
Aero evaluates only the branch a #profile selects, so a key one profile
needs can be absent from the store another profile reads:
:api-key #profile {:default #secret/req :openrouter/api-key
:evals #secret/req :openrouter/evals-api-key}The loaded map is an ordinary value, so a component that provides it is one method:
{::secrets {:resource "secrets.edn.age" :app "myapp"}}
(defmethod ig/init-key ::secrets [_ {:keys [resource app]}]
(secrets/load-secrets (io/resource resource) {:app app}))Or pass merge-readers output as the :readers of
integrant.core/read-string and reference secrets from the system config.
Every operation that decrypts resolves its identity when it runs, from the first of these that applies:
- An explicit path: the second argument of
load-secrets, or:identity-filein the options. The CLI config has no such key: a command's identity comes from 2 to 7. SECRETS_AGE_IDENTITY_FILE, a path to the key file.SECRETS_AGE_IDENTITY, the key file's contents.SECRETS_AGE_IDENTITY_B64, the key file's contents in base64.- A
:key-command: the environment's in the CLI, or the option at runtime. - A
:key-file, likewise. - On macOS, the Keychain item for the app, when an app name is known.
A path from 1 or 2 names a specific file, and it is an error (:no-identity)
if that file does not exist. 6 and 7 say where the key normally lives. When
the file or the Keychain item is not there, no identity is available:
#secret/opt reads nil, verify checks without a key, and a command that
needs the key says where it looked. A :key-command that fails or prints
nothing is an error that names the program. There is no default key file.
An identity variable that is set but empty is an error that names the variable: a CI runner expands a missing secret to the empty string, and falling through to another key would hide that. Unset the variable to fall back.
Identity paths are local paths with a leading ~ expanded. A value that
starts with a URI scheme is refused with :disallowed-identity. A bare
relative name with a colon in it, such as key:txt, reads as a scheme, so
write ./key:txt. Key contents placed in a path setting, raw or
base64-encoded, are refused the same way and are not echoed.
A key from 3, 4, 5, or 7 stays in memory. It reaches age on its standard
input (age -i -), so the library never writes it to a file.
Fixed bounds catch an accidental huge or deeply nested input, such as a path that names the wrong file. Loading refuses a ciphertext past 16 MiB and EDN nested more than 100 collections deep. The CLI refuses to write a plaintext past 8 MiB, and to read a recipients file past 256 KiB or a manifest past 1 MiB. They are not configurable.
A deployment needs the age binary, the ciphertext, and one identity. The
ciphertext ships with the code, on disk or inside the jar. Give the process
the identity through one of the three variables above. SECRETS_AGE_IDENTITY
takes the contents of the key file, which is how most platforms store a
secret.
A runtime that cannot start a subprocess cannot decrypt. There, use the platform's own secret store in production and this library in development and CI.
bb secrets verify exits 0 when every manifest agrees with its ciphertext and
1 when the only problem is drift. It exits 2 when anything else stopped it: a
missing file, an identity or decryption failure, an invalid recipients file,
an unknown environment, or an invalid configuration. A CI job can therefore
tell a stale manifest from a missing key. It runs in one of two modes per
environment.
Without an identity, it checks that the manifest is complete and that the
SHA-256 it records is the digest of the ciphertext. This needs no key and no
age, so any CI job can run it. It applies when no identity was named and no
key file is present, which is the usual state of a CI runner. An identity
named by SECRETS_AGE_IDENTITY_FILE has to exist: a missing one is an error,
not a reason to skip the comparison.
With an identity, it also decrypts the store and compares every key path, type, and value hash with the manifest. It reports drift as well when the recipients file no longer matches the set the store was last encrypted to.
With no environment argument, verify checks every environment and keeps
going past one that fails.
A job that holds the identity should give it to the one step that needs it, keep unreviewed code out, and pin its actions:
verify-secrets:
runs-on: ubuntu-latest
if: >-
github.event_name != 'pull_request' ||
github.event.pull_request.head.repo.full_name == github.repository
permissions:
contents: read
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
- uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
with: {distribution: temurin, java-version: '21'}
- uses: DeLaGuardo/setup-clojure@4c7a6f613e5089821bb3bb2a33a3ee115578580d # v13.6.1
with: {bb: 1.13.219}
- run: sudo apt-get update && sudo apt-get install -y age
- run: bb secrets verify
env:
SECRETS_AGE_IDENTITY: ${{ secrets.SECRETS_AGE_IDENTITY }}The repository secret holds the key itself, not a path. With the key in the macOS Keychain, it can go straight from there to GitHub:
security find-generic-password -s com.kirahowe.secrets -a myapp -w | \
gh secret set SECRETS_AGE_IDENTITYFor the keyless job, drop the env:, the age install, and the if:. The
book's production chapter walks through both jobs.
Point an environment at a recipients file and every write encrypts to all the public keys in it. Each person keeps their own private identity.
The first owner creates a key, adds its public half, and creates the store:
bb secrets keygen prod
bb secrets add-recipient prod
bb secrets set prod :service/token # or: bb secrets new prodTo add someone, a current recipient adds the newcomer's public key (the
newcomer gets it from bb secrets show-key) and re-encrypts:
bb secrets add-recipient prod age1...
bb secrets reencrypt prodTo remove someone, delete their line from the recipients file and run
bb secrets reencrypt prod. Commit the recipients file, the ciphertext, and
the manifest together. Editing the recipients file changes nothing by itself:
the store stays encrypted to the earlier set until it is re-encrypted, and a
verify that has an identity reports that as drift.
Removal stops that identity from decrypting ciphertext written afterwards. It does not take back anything already read, and the old ciphertext stays in git history, where the removed identity still decrypts it. Rotate the affected credentials at their providers.
reencrypt also gives the store a new manifest key, so every value hash in
the manifest changes once. edit, set, and rm do the same when they find
that the recipients file no longer matches the set the store was last
encrypted to. That catches a forgotten reencrypt. It is not the removal
step: reencrypt is, because it always renews the key.
The manifest explains why.
Each command that writes reads the recipients file once, before it decrypts
or opens an editor, and refuses a line that is not an age or SSH public key.
A verify that has an identity refuses it too, with exit 2.
bb secrets recipients lists the file and marks such lines.
Give deployments and CI their own recipient instead of a person's key.
A diff of secrets.edn.age says nothing, because age re-encrypts the whole
file. Every write therefore also writes secrets.edn.manifest:
{:version 3
:app "myapp"
:ciphertext-sha "0e6487cf6f4562d51ef450dbe7ce54d76e91b350425d65ea1ab94288fe3acd6e"
:keys
{[:auth/admins] {:type :set, :count 2, :vhash "ce4caccbfee081c6"}
[:example/api-key] {:type :string, :vhash "89ae7df577fa8bb8"}
[:r2 :account-id] {:type :string, :vhash "d32adde248640142"}}}Commit it. Its diff shows keys added, removed, or retyped, and a changed
:vhash shows that a value changed. :ciphertext-sha is the SHA-256 of the
ciphertext the manifest was written for, which is what the keyless verify
compares.
A :vhash is the first 64 bits of an HMAC-SHA-256 of the value. Its key is
256 random bits that the store holds inside its own encrypted EDN, so solo and
team stores work the same way and every recipient computes the same hashes.
At 64 bits a hash can collide: an unchanged hash is strong evidence that a
value did not change, not proof.
The store keeps that key, and a record of the recipient set it was encrypted
to, under one reserved top-level key, :com.kirahowe.secrets/store, that the
library owns. load-secrets, the reader literals, and the editor never show
it, and set, rm, and an edited plaintext cannot name it. A store's
plaintext has to be one EDN map.
new, or set when no store exists, generates the key. edit, set, and
rm keep it. reencrypt always replaces it, and so does any write that finds
the recipient set changed.
A store whose metadata is missing, malformed, or of another version fails
edit, set, and rm and is drift for a verify that has an identity. The
message says which it is and names bb secrets reencrypt, which writes
current metadata without reading the old. That is the state of a store
written by another tool, such as age itself. A store that is not a map at
all is told to start over with bb secrets new.
Anyone who can read the repository sees:
- every key path, through nested maps at every depth;
- each value's type, and the size of each collection;
- whether two values in one store are equal, and when a value changes or returns to an earlier one, for as long as the store keeps one manifest key;
- the size of the ciphertext and the commit history of both files.
Key paths are public, so never use a secret value as a map key.
Everyone who can decrypt the store holds its manifest key and can test guesses of a value against any manifest published while that key was in use. Someone without the key cannot. A removed recipient keeps the key they had, which is why the next write replaces it.
If a key name is itself sensitive, set :manifest false for that environment.
Its changes are then not reviewable at all.
A write validates the plaintext, encrypts it, and renders the manifest before
it replaces anything, so a rejected edit leaves both files alone. It then
replaces the ciphertext with an atomic rename, and then the manifest the same
way. The two renames are not one transaction and nothing is rolled back. If
the manifest cannot be replaced after the ciphertext was, the command says the
manifest is stale, verify reports the drift, and bb secrets reencrypt
regenerates it.
The ciphertext, the manifest, and the recipients file are each staged beside
their target under a name of the form .<target>.<uuid>.tmp. A generated key
is staged beside its target as .<target>.<random>.tmp, readable only by its
owner. A command deletes its staging file when
it ends, but one that is killed can leave it behind. Such a file is safe to
delete, and a .*.tmp line in .gitignore keeps it from being committed.
The ciphertext, manifest, and recipients file are written with ordinary file
permissions. Key files and the temporary plaintext that new, edit, set,
rm, and reencrypt use are readable only by their owner from the moment
they are created, and the temporary files are deleted when the command ends.
doc/threat-model.md states what the library protects
and what it leaves to the deployment. In short:
- age keeps the values confidential and detects a corrupted or truncated ciphertext. Only a holder of a matching private identity can decrypt.
- Nothing identifies who wrote a ciphertext. A public recipient is meant to be shared, and anyone who has one can encrypt a file that decrypts cleanly. An older valid file can also be put back in place of a newer one.
verifyshows that a ciphertext and its manifest agree. Someone who can replace both can make them agree, so a pass is not evidence of authorship or approval, with or without an identity.- The values a process loads are as trustworthy as the commit that carried them and the channel that delivered them. Protect the branches and tags a deploy builds from, and limit who can write to whatever serves the ciphertext.
- A leaked identity decrypts every ciphertext in git history that was encrypted to it. Rotate the secret values, not only the key.
- One identity decrypts a whole environment. There is no access control per secret.
- A key in the Keychain or a password manager stays out of backups and synced or committed dotfiles. Code running as you can still read it, the same way the library does.
- The decrypted map sits in process memory like any other config. The library does not defend a compromised host or application process.
editandnewput plaintext in an owner-only temporary file while the editor is open. Your editor's swap and backup files are outside the library's control, and deleting a file does not erase it from the disk.- The manifest discloses key paths, types, sizes, and value equality and change.
If you need dynamic credentials, access rules per secret, automatic rotation, or a central audit log, use a secrets manager.
Report a suspected vulnerability privately, as SECURITY.md describes.
Every command takes the environment first and uses the default when it is
omitted. Before a --, an argument that starts with a dash is an option, and
one the command does not define is an error. Everything after -- is an
argument, even one that looks like an option. Command names are case
sensitive. A usage error prints the command's usage and never the argument
that caused it, which may be a value typed in the wrong place. That includes
an unknown command and an unknown environment.
| Command | What it does |
|---|---|
keygen [env] |
Generate an identity, store it in the environment's :key-file or, without one, the macOS Keychain, and print its public key. Asks before replacing one. Refuses for an environment with a :key-command. |
new [env] |
Create the store from its template in $VISUAL, $EDITOR, or vim. |
edit [env] |
Decrypt, open the editor, and re-encrypt if the text changed. Comments are kept. |
set [env] <key> [--edn] |
Set one value from a hidden prompt, or from stdin when it is not a terminal. The prompt needs stdin and stdout both to be terminals: with stdout redirected, pipe the value in. Creates the store if there is none. |
rm [env] <key> |
Remove one key. Fails if the key or the store is absent. |
verify [env] |
Check manifests against ciphertexts. With no env, checks every environment. |
doctor [env] |
Report on the setup: age, the files, the identity, and the recipients. |
show-key [env] |
Print the public key of the environment's own key. |
add-recipient [env] [public-key] |
Append a public key to the recipients file. With no key, the environment's own. A single argument that is a public key goes to the default environment, and any other single argument is the environment. |
recipients [env] |
List the recipients file. |
reencrypt [env] |
Re-encrypt to the current recipients with a new manifest key. |
help [command] |
Show help. <command> --help does the same for one command. |
<key> is a keyword (:some/key) or a vector path ('[:a :b]'). set never
takes the value as an argument. Piped input loses one trailing newline, is
stored as a string unless --edn parses it, and is refused when blank (use
--edn with "" for an empty string). set and rm refuse a path that
passes through a value that is not a map. Both rewrite the plaintext, so
comments in it do not survive them.
doctor is for finding out why a command will not run. It does not open the
store or the manifest, and it prints paths and counts, never file contents,
recipient lines, or variable values. This is a team environment on a machine
that has no key:
Environment: prod
age: v1.3.2
Secrets file: env/prod/secrets.edn.age (present)
Manifest: env/prod/secrets.edn.manifest (present)
Recipients file: env/prod/recipients.txt (present)
Recipients: 1
Identity: key file keys/alice.txt (missing)
Warning: No identity, so only keyless verification works here. Create a key with: bb secrets keygen 'prod'
Status: warning
Exit codes:
| Command | 0 | 1 | 2 |
|---|---|---|---|
verify |
every manifest agrees | the only problem is drift | anything else stopped it: a missing file, an identity or decryption failure, an invalid recipients file, an unknown environment, an invalid configuration |
doctor |
healthy | a warning: age, the secrets file, the manifest, the recipients file, or the key is not there |
an invalid configuration, identity, or recipients file, or it could not run |
| every other command | success | any failure |
com.kirahowe.secrets is the runtime API:
(load-secrets source),(load-secrets source identity-or-opts)(get-secret secrets key-path),(get-secret secrets key-path default)(reader-literals opts),(merge-readers readers opts)(resolve-identity identity-or-opts)returns the identity an operation would use:{:identity-file path :identity-source source}, or{:identity-contents key :identity-source source}for a key held in memory.(identity-available? identity)says whether it holds a usable key.
com.kirahowe.secrets.aero has (read-config source opts).
com.kirahowe.secrets.cli has (run! config args), (normalize-config config), and one function per command: keygen!, new!, edit!,
set-secret!, remove-secret!, verify!, doctor!, show-key!,
add-recipient!, recipients!, and reencrypt!. set-secret! takes its
options as a map, (set-secret! config env key {:edn? true}). The command
functions return data, throw ex-info, and never exit. verify! and
doctor! report most failures in their result, with the exit code under
:exit. run! is the entry point of a process, on Babashka or the JVM, and
the one place that exits.
com.kirahowe.secrets.init has -main and (init! opts).
Those four namespaces are the public API. com.kirahowe.secrets.age,
.identity, .keychain, .manifest, .store, .fs, .safe-edn, and
.source are implementation namespaces and can change without notice. The
book's reference chapter lists every public API var with its docstring.
Every ex-info the library throws has a :reason keyword in its data. These
are the ones a caller can usefully branch on:
| Reasons | Meaning |
|---|---|
:no-identity, :invalid-identity, :disallowed-identity |
No identity is available, or a named identity file is missing. An identity variable is blank or not base64, or a :key-command is malformed or printed nothing. An identity path is URI-shaped or holds key contents. |
:key-command-failed, :keychain-failed |
The :key-command could not start or exited with an error. The macOS Keychain could not be read or written. |
:no-file, :disallowed-source, :source-too-large |
The source is nil, blank, absent, a directory, or unreadable, or a file the CLI needs cannot be read. It is not a local path or a classpath resource. The ciphertext is past 16 MiB, at runtime or in the CLI. |
:decrypt-failed, :age-not-installed |
age could not decrypt with this identity. The age binary is not on the PATH. |
:edn-empty, :edn-extra-values, :edn-malformed, :edn-too-deep |
The plaintext is not exactly one well-formed EDN value. |
:missing-key |
#secret/req named a key the store does not have. The tag also throws :no-file and :no-identity. |
:invalid-config, :unknown-config-key |
The CLI config, or the options of the Aero read-config, cannot be used. A URI-shaped path in the config is :invalid-config. |
:usage |
A command line the CLI cannot place: an unknown command, option, or environment, or a missing or surplus argument. |
:invalid-store, :secrets-not-a-map, :reserved-key, :path-not-a-map, :no-such-key, :blank-value |
A write the CLI refused, and why. |
:input-too-large, :invalid-recipient, :no-recipients, :no-recipients-file |
A recipients file, manifest, template, or plaintext the CLI was given is too large. The recipients file holds an invalid line, or nobody. add-recipient was run for an environment with no :recipients-file. |
:manifest-stale |
The ciphertext was replaced and the manifest was not. Run reencrypt. |
:private-file-remains |
A private temporary file could not be deleted. :remaining-file holds its path. |
The examples are runnable starter projects: quickstart-bb, integrant-service, aero-profiles, and team-ci.
The tests need age and a JDK. The book also needs
Quarto.
bb test # the suite under Babashka
clojure -M:test # the suite under JVM Clojure
bb lint # clj-kondo
bb format:check # cljfmt, without changing files (`bb format` fixes)
bb book:build # render the book into book/rendered
bb book:watch # re-render chapters as you save them
bb secrets help # the CLI against a throwaway store under tmp/Source lines stay within 100 columns. The chapters under book/chapters are
literate Clojure namespaces rendered with
Clay, so their examples run against the
library at build time.
The version and coordinates live in src/com/kirahowe/secrets/coordinate.edn.
A release is built from a v<version> tag by the release workflow, or by
hand with clojure -T:build release and clojure -M:deploy.
doc/release-dependency-review.md records
the dependencies of the deploy step.
MIT © 2026 Kira Howe. See LICENSE.