Episodes · EP002 · By design
Folio: By Design
Why you can trust a new secret manager: what Folio is built on, where your secrets go, how they travel, and how it stays easy to use.
EP001 showed what Folio is for. But a new secret manager asks for your most sensitive values, your tokens and your passwords, and being suspicious of one is fair. So don't take Folio on faith. This is how it is built, and why:
- Trusted. It is built on
pass, gpg and git, and it is one bash script you can check and read. - Secure. A secret goes straight to the one command that needs it, and nowhere else.
- Portable. Some items, or the whole store, travel as one locked file.
- Usable. Variable names come from the path, a project says what it needs in a vars file, a secret can go to the clipboard, and you pick how often the passphrase is asked.
Here is what is under your store, in one picture:
Trusted: built on pass
Folio brings no vault of its own, no account and no service. It stands on a few plain pieces:
your GPG key, a pass store, and git. folio init sets them up.
Your own GPG key
The store key lives in your GPG keyring (~/.gnupg), with any other keys you have.
Like every GPG key, it has two halves. The public half encrypts, and checks signatures:
anyone may have it. The secret half decrypts, and signs, and it is locked by the
passphrase you chose. This is the sandbox's key, as gpg lists it (a post-quantum one: its
encryption subkey is ML-KEM, ky768):
A plain pass store, and its .gpg-id
The store is a folder, ~/.folio by default, kept apart from your own ~/.password-store. folio init makes it private (700):
even encrypted, the names of your items and the plain texts would show to other users. A fresh
store holds only this:
.gpg-id is how the store knows its key: one line, the key's fingerprint, written by pass init. Everything in the store is encrypted to, or signed by, the key it names.
Secrets and texts
A secret is a <name>.gpg file, encrypted to the store
key: exactly a pass entry. A text is a plain <name>.txt file, for a value that is not secret but must not be tampered with
(a URL, a user name, a region). It is signed with the store key in <name>.txt.sig, so a text changed outside Folio, or signed by another key, is
refused rather than used. The commands always say which kind they mean, so a secret is never
shown by accident.
Which half of the key a command needs decides whether you are asked for the passphrase. Writing a secret only uses the public half; reading one, or writing a text, needs the secret half:
| You… | The key does | Passphrase? |
|---|---|---|
| add a secret | encrypt (public half) | no |
| read a secret, or run a command with one | decrypt (secret half) | yes |
| add or edit a text | sign (secret half) | yes |
| read a text | check the signature (public half) | no |
| back up the store | export the secret half | yes |
Every change, in git
The store is a git repository, and every change is committed, by pass or by Folio.
A removed item is still in the history. This is the sandbox's, after a first setup and a few more commands:
One script you can check, and read
Folio is one bash script, folio: plain text from start to end. First check that the
one you run is the one released. The install script checks the download for you; at any time after, go to where folio is, fetch the SHA256SUMS its release publishes, and check the file against it (on macOS, shasum -a 256 -c for sha256sum -c):
Then read it. It is plain, linear bash, written so that anyone can read it top to bottom and see that no secret is sent anywhere.
Or have an AI read it for you. Give it the file and ask: does any secret leave this machine, land in a file, or reach the screen when I did not ask? That is your own check, of the very file you run, not a promise from us.
Nothing locked in
folio runs pass, gpg and git for you, and
that is all. And because the store is a plain pass store, pass itself still opens every secret in it. If you ever stop using Folio, nothing is
locked in:
Secure: straight to the process
folio exec runs a command with your items as environment variables, the way op run and aws-vault exec do. The command gets them; nothing else
does. Texts come by default, and secrets only when you
say -s (--secrets):
release.sh stands in for any script of yours. It uses what it is given: it prints
the text, and only says that the secret is there. The
secret never has to reach the screen.
- Never on a command line, in a file, or on the screen, unless you ask to see one. A
secret is read at a hidden prompt or from a pipe, and handed to
passon stdin. No option takes a secret as an argument, so none ends up in your shell history. - See before it runs.
--namesshows which variable would get which item, and stops;--debugshows it and runs;--confirmshows it and asks first. No value is read before that. - All or nothing. Every item is checked and read before the command starts. If one fails, the command does not run.
What it does not do: once a command has a secret in its environment, anything running as you can
read it (/proc/<pid>/environ on Linux), so run only commands you trust. And Folio
does not protect against someone who already runs code as you, or as root. Your secrets are as safe
as your GPG key and its passphrase.
Portable: one locked file
folio export copies just the items a machine needs into one file, and the file is always locked: with a passphrase, or with --to, to the public key of where
it is going, so it can travel through places you do not trust. Your store's own key never leaves
your machine: each secret is encrypted again, to a key made for this export only, through a
pipe, never touching the disk.
There, folio import brings the items into a store. Or skip the store: with --from, folio exec uses the file itself as the store. It is unpacked into
a private temporary folder, read, and removed before the command starts; nothing is kept.
For the whole store, key and all, there is folio backup and folio restore: one file, and back, on a new machine.
Usable
A secret manager you don't enjoy using is one you stop using. So:
An item's variable name comes from its path
/, - and . turn into _, then it is
uppercased, and a top folder whose name starts with @ (a namespace) is
dropped. No mapping to write:
| Item | Variable |
|---|---|
gh/token | GH_TOKEN |
@me/gh/token | GH_TOKEN |
gh/api-key | GH_API_KEY |
gh/api+key | none: not a valid name, left out with a warning |
A namespace lets you keep items in groups, such as the GitHub tokens of two accounts under @work/ and @me/, without the group's name ending up in the variable.
To pick the name yourself, write it on the command line:
folio exec --secrets GITHUB_TOKEN=gh/token -- gh release list A vars file says what a project needs
A vars file names what a command needs, by its own names, and where each value comes from: @{name} is an item, ${NAME} a variable already
set. Think of it as the project's .env.example: a record of which variables the
application needs. It holds no value itself, so it can go in the repository with the code, while
the values stay in your store:
# deploy.vars
GITHUB_TOKEN=@{gh/token} # gh/token, as GITHUB_TOKEN
AUTH=Bearer @{gh/token} # put into a longer value
REGION=@{aws/region:-${AWS_REGION}} # with a fallback when the item is not there
@{aws/*} # every item under aws/, each named by its path folio check vars deploy.vars # check how it is written (no store needed)
folio exec --secrets --names --vars deploy.vars # show where each variable would come from
folio exec --secrets --vars deploy.vars -- ./deploy.sh With --vars, the command gets only what the file sets.
A secret to the clipboard, for a while
Some secrets go into a password box, not a command. -c copies one to the clipboard
instead of showing it, and the clipboard is cleared after 45 seconds (PASSWORD_STORE_CLIP_TIME). A text can be copied too, and is not cleared.
The passphrase, three ways
Folio never asks for a passphrase itself. gpg does, through its agent: gpg-agent runs a small program, pinentry, that asks you, in the terminal or
in a window. The agent then remembers the passphrase for its cache time, so the next folio, pass or gpg needs none. How often you type it is up
to you:
| Way | Asked | How |
|---|---|---|
| Default | once, then not for a while | pinentry asks, gpg-agent remembers |
| Auto, a machine you trust | never | FOLIO_STORE_PASSPHRASE_FILE=<file>: a file only you can read (chmod 600, or Folio refuses it) |
| Strict, a machine you trust less | every command | --fresh-passphrase, or FOLIO_FRESH_PASSPHRASE=1: the agent
forgets it when each command starts and ends |
- Default: how long the agent remembers is
default-cache-ttlandmax-cache-ttl(seconds), in~/.gnupg/gpg-agent.conf. For a window instead of the terminal, install a GUI pinentry (pinentry-gnome3,pinentry-qt, orpinentry-macon macOS) and name it there:echo "pinentry-program $(command -v pinentry-gnome3)" >> ~/.gnupg/gpg-agent.conf gpgconf --kill gpg-agent - Auto: anyone who can read that file, or run commands as you, can open the store. Use it
only where you would leave the store unlocked. The command
execruns does not get the variable. - Strict:
execandshellhave the agent forget it before the command starts: they hold the values, not the passphrase.
Bottom line
Folio asks for your trust in the plainest way it can. Your secrets sit in a pass store, under your own GPG key, in one bash script you can read. They go
straight to the command that needs them, and nowhere else. They travel as one locked file, and
never with your key. And it stays easy to use: names from the path, a vars file per project, the
clipboard, and the passphrase as often as you like. To make your own store and use it, start from its README.
Keep your secrets out of plain sight.
Links
- EP001: what Folio is for
- All episodes, the Shorts and the articles
- Folio's README: how to install it, and where everything is
- The latest release
- The manual: every command, with examples
pass, the standard Unix password manager