Changelog

What changed in the custodian command line, newest release first.

v0.5.2

Fixed on macOS: `custodian device approve` now completes on a Mac

In v0.5.0 and v0.5.1, custodian device approve failed on a Mac at the step where your machine signs the approval. This happened whether the device key was in the Secure Enclave or in the Keychain on a Mac with no Secure Enclave. The failure was always reported as a declined presence prompt, even when you had approved the prompt. The v0.5.0 fix to custodian device approve did not make it complete on a Mac. This release does.

If an approval failed with the declined-prompt message in v0.5.0 or v0.5.1:

Upgrade your Mac to v0.5.2. custodian --version prints the version you have. To get the signed macOS bundle, see verifying a release download.
Run custodian device approve again on your Mac with the same request line — the line custodian device enrol printed on the new machine. If you no longer have it, run the same custodian device enrol command on the new machine again; it prints the same request.
If the new machine has stopped waiting, run custodian device enrol --resume on it once the approval succeeds.

A failed signature on a Mac is now reported in one of two ways:

the presence prompt was declined, so this device unwrapped no key (SecKeyCreateSignature failed: …) now means only that the prompt was cancelled or authentication failed. Run the command again and approve the prompt.
Any other signing failure now reads SecKeyCreateSignature failed signing with the device key (<domain> <code>). This is not a declined prompt, and running the command again and approving the prompt will not fix it. Approve the new machine from another already-enrolled machine instead, as described under on macOS. If your Mac is the only enrolled machine, it stays enrolled; keep the request line, which does not expire, and follow the steps on that page. Do not revoke your Mac to use custodian recover: revoking the last live device is irreversible.

v0.5.1

No change to any command or its output. The upgrade step in v0.5.0 applies to this release too: if you are upgrading from v0.4.0 or earlier, follow it.

v0.5.0

After upgrading: re-apply each vault's schema once

The way a schema's digest is computed has changed, so the digest of every schema file changes, even one you have not edited. Stored values, tokens and blind indexes are unaffected.

After upgrading, re-apply each vault's schema once, on the file as it was last applied:

custodian schema apply schema.yaml

Add --vault <slug> if you are signed in to more than one vault. The apply advances the schema version with no changes. If you skip it, nothing stops working; the version advance happens the next time you apply the file. Before you run it, and for what to do if the file holds edits you have not applied yet, see the one-time step after upgrading.

Send files through your vault

You can now store a file in a record's file field and retrieve it on another enrolled machine:

custodian file put seals a file on this machine, stores it, and prints a one-line custodian file get command you can send to whoever needs the file.
custodian file get takes that token, opens the file on an enrolled machine and writes it into ~/Custodian/<vault>/ with permissions 0600, so only your user account can open it.
custodian exec --capture-output stores a program's standard output in a file field instead of printing it.

See custodian file, capturing a program's output and the guide sending a file.

Name the field that holds a file's name

A file field in the schema file can set filename_field to name the field holding the file's name, and custodian file get writes the file under that name. custodian schema show lists it as filename field: <name>, and schema diff and schema apply show a change to it as ~ field <collection>.<field> filename field: <from> → <to>. See file fields.

`custodian schema apply` always sends an unchanged file

Before, applying a file with no changes stopped on your machine and printed no changes — already at schema version N. Nothing to apply. Now the apply is always sent, and the server may advance the version:

no changes to send (at schema version 3) — asking the server to re-apply.
  applied · schema version 4

If a script reads schema apply --json, update it. An unchanged file no longer returns {"applied":false,"no_op":true,"version":…}. It returns the same shape as any other apply, {"applied":true,"version":…,"wrote_version":…,"changes":[]}.

Key rotation now covers files

custodian key rotate now recomputes the token of every file in the vault, without downloading or decrypting any file. Every retrieval line already sent for a file stops working and must be re-issued with the file's new token, and the rotation's warning now says so:

! Every file in this vault is among those tokens: any retrieval line already sent for a
  file — printed or emailed — stops working and must be re-issued once this completes.

See custodian key rotate.

Fixed: `custodian device approve` now completes

Before this release, approving a new device always failed with This machine is not an enrolled, live device …, even on an enrolled machine. It now completes. See custodian device approve.

macOS: a clear message when you decline the presence prompt

When you decline the Touch ID or passcode prompt for the Secure Enclave key, commands now report the presence prompt was declined, so this device unwrapped no key, followed by the status the system returned. See on macOS.

v0.4.0

`custodian whoami` now names who you are signed in as

custodian whoami now opens with a Principal: line — the principal you are signed in as and its kind (operator, agent or service), read from the vault. It no longer prints a Keys: line. See signing in.

A machine with an unreadable stored credential can still run on `CUSTODIAN_TOKEN`

When a machine has a stored credential whose secret cannot be read back — the store is locked, or the platform tool will not return it — custodian now falls through to the CUSTODIAN_TOKEN environment variable, provided you name the deployment with --url and --vault. A machine with a broken store entry but a valid token in the environment still runs. When nothing resolves, the error names the store and says the secret could not be read. See when a stored secret cannot be read.

Releases now publish the macOS provisioning profile

Each release now also publishes embedded.provisionprofile, the Developer ID provisioning profile the macOS bundle embeds, covered by checksums.txt. It is a build input, not a download you run. See verifying a release download.

v0.3.0

The macOS download is now a signed app bundle

Each macOS download now ships as custodian-darwin-arm64.app.tar.gz or custodian-darwin-x64.app.tar.gz — a gzip-tar of a custodian.app bundle, no longer a bare binary. The bundle is signed with a Developer ID certificate, notarised and now stapled, so Gatekeeper admits it without a network round-trip on first run. This is the change from the v0.1.0 status that the macOS binaries were not notarised.

You run the binary inside the bundle, at custodian.app/Contents/MacOS/custodian. The new verifying a release download guide covers unpacking it, the run path, and checking the signature, notarisation and stapling.

A device key can now be created on macOS

On the signed, entitled bundle, a Mac holds its device key in the Secure Enclave. A Mac with no Secure Enclave falls back to the software Keychain, and a build that is not the signed bundle is refused until you install the signed bundle. See enrolling and managing devices.

v0.2.0

Signing in on macOS

custodian login now stores your operator token on macOS, in the macOS login keychain — the same way it already stored it on Linux, in the system secret service. logout removes it, and whoami shows where it is held. On a Mac you no longer need to set CUSTODIAN_TOKEN just to sign in.

Windows is not covered yet. On a machine that is neither macOS nor Linux, sign in by setting CUSTODIAN_TOKEN and naming the deployment with --url and --vault.

v0.1.0

The first release of custodian, the command-line client for Custodian. Everything is new, and there is nothing earlier to migrate from — no stored data needs re-tokenising, re-indexing or re-encrypting.

Before you download: which build to take

The x64 builds require an x86-64-v3 CPU (AVX2). A host older than that will not run them — use the arm64 build there instead. Builds are published for Linux, macOS and Windows.

Signing

This release's binaries are not code-signed or notarised, because no signing certificate is provisioned yet.

On Windows, the unsigned binary triggers a SmartScreen "unrecognised app" warning on first run, which you dismiss to continue.
On macOS, the binaries are not notarised. A binary downloaded through a browser may be held by Gatekeeper; one fetched with curl or a release download is not.

The release publishes a checksums.txt so you can verify your download with sha256sum -c --ignore-missing checksums.txt. Treat the checksum file as trusted only to the extent you trust the channel you fetched it over.

The command surface

Session and account — version, login, logout, whoami, unlock, lock, and doctor, the one-page vault report.
Vault lifecycle — init to enrol this machine as a vault's first device, and recover to reconstruct a vault from its recovery code when every device is lost.
Reading values — resolve and exec.
Records — records with import, create, get, search, update and delete.
Schema — schema with diff, apply, show and history.
Devices — device with list, enrol, approve and revoke.
Access — principal and grant, each with create, list and revoke.
Keys — key with rotate and destroy.
Audit — audit list, following the trail to its end.

On this page