pass-coffin

A pass extension that hides password-store metadata inside a signed, GPG-encrypted coffin.

pass-coffin is a pass extension that moves password-store contents into a GPG-encrypted archive when the store is not in use.

The v2 line is a maintained fork focused on safer local operation, stronger authentication defaults, and reproducible local development. The historical master branch is preserved as legacy-master.

Repository: https://codeberg.org/rch/pass-coffin

Why Use pass-coffin?

pass encrypts each password file, but the password-store tree still exposes metadata. Directory names, entry names, account names, and service names can reveal what you use even when every .gpg file is encrypted.

pass-coffin helps when you want to keep using pass, Git, GPG, shell scripts, and the normal Unix file layout while hiding that tree when it is not in use.

• Hide password-store metadata by moving entries into one encrypted archive when the store is closed.
• Keep the ordinary pass workflow after opening the coffin.
• Avoid a mounted encrypted volume or root-only workflow for normal open and close operations.
• Sign coffins so open can verify integrity and authenticity before extraction.
• Automatically close the store after a timer when desired.
• Keep the closed coffin as a simple archive that can be synced or backed up like any other file.

This tool does not replace backups, full-disk encryption, or good session locking. It reduces metadata exposure while the store is closed.

Security Model

v2 changes the defaults deliberately:

• .coffin-signing-key is the default signing-key configuration.
• PASSWORD_STORE_SIGNING_KEY remains supported as an override.
• Unsigned coffins are allowed only when PASS_COFFIN_ALLOW_UNSIGNED=true is set.
• open and close require a valid PASSWORD_STORE_DIR/PREFIX and will not operate in the caller's current directory by accident.
• Operations use a password-store lock file to avoid concurrent open/close races.
• Archives are validated before extraction and unsafe paths or entry types are rejected.
• open refuses to overwrite existing plaintext password-store files.

Keep your password store in Git or another backup system before relying on any metadata-hiding extension. See SECURITY.md for reporting guidance and security guarantees.

Requirements

• pass
• bash
• gpg
• GNU tar
• GNU find
• flock from util-linux
• systemd-run and systemctl for optional timer support

Installation

Enable pass extensions first:

export PASSWORD_STORE_ENABLE_EXTENSIONS=true

Install from a release tarball:

curl -LO https://codeberg.org/rch/pass-coffin/releases/download/v2.1.1/pass-coffin-2.1.1.tar.gz
tar -xzf pass-coffin-2.1.1.tar.gz
cd pass-coffin-2.1.1
sudo make install

Install from a git checkout:

git clone https://codeberg.org/rch/pass-coffin
cd pass-coffin
sudo make install

Package maintainers can override install paths:

make DESTDIR="$pkgdir" PREFIX=/usr install

The default install layout is:

• extensions: /usr/lib/password-store/extensions
• bash completion: /usr/share/bash-completion/completions/pass-coffin

The bash completion path matches upstream pass and Arch packaging guidance for packaged completions.

Override PREFIX, LIBDIR, SYSTEM_EXTENSION_DIR, or BASHCOMPDIR when packaging for a distribution with different paths.

Configuration

v2 requires a signing key by default. The default configuration is a root-level file in your password store:

printf '%s\n' <your-gpg-key-fingerprint> > "${PASSWORD_STORE_DIR:-$HOME/.password-store}/.coffin-signing-key"

Use the full GPG fingerprint, not a short key ID. The fingerprint is not secret; the private key in your GPG keyring is the secret.

If you already use the same key for pass encryption and signing, this is often enough:

cp "${PASSWORD_STORE_DIR:-$HOME/.password-store}/.gpg-id" "${PASSWORD_STORE_DIR:-$HOME/.password-store}/.coffin-signing-key"

Only do this when .gpg-id contains one key that belongs to you and appears in gpg --list-secret-keys.

PASSWORD_STORE_SIGNING_KEY is still supported for compatibility and overrides .coffin-signing-key when set:

export PASSWORD_STORE_SIGNING_KEY=<your-gpg-key-fingerprint>

Unsigned legacy mode is intentionally explicit:

PASS_COFFIN_ALLOW_UNSIGNED=true pass open

Use unsigned mode only to migrate old coffins or after accepting the integrity risk.

Usage

Close the password store into a signed encrypted coffin:

pass close

Open the coffin back into the password store:

pass open

Open and schedule automatic close using systemd time syntax:

pass open --timer 10min

Show or stop the active timer:

pass timer
pass timer stop

Project Background and Credits

pass-coffin was originally created by Ayush Agarwal (ayushnix). The original project lives at https://github.com/ayushnix/pass-coffin and was archived by its maintainer in 2025 after reaching a feature-complete state for the original author.

This fork continues that work for users who still want a small pass extension that hides password-store metadata without changing the normal pass workflow. The v2 series keeps the original coffin idea and adds stricter safety checks around signing, archive extraction, locking, and local development.

Thanks also to the projects that made this tool possible or shaped its design:

• pass, by Jason A. Donenfeld, provides the password-store model and extension interface.
• pass-tomb, by roddhjav, showed how a pass tree can be closed into a protected container.
• pass-grave, by 8go, explored a lighter archive-based approach to hiding password-store metadata.
• Tomb, by Dyne.org, underpins the pass-tomb workflow and influenced the broader password-store metadata-hiding ecosystem.

The original pass-coffin README explicitly credited pass-tomb and pass-grave as major inspirations. This fork preserves that attribution.

Documentation

• docs/migration-v1.md describes migration from legacy v1 coffins.
• docs/hacking.md describes local checks, container verification, and test isolation rules.
• docs/release.md describes the release-tools and GoReleaser release process.
• docs/license.md documents the GPL-3.0-only clarification from the original maintainer.
• SECURITY.md describes security reporting and guarantees.
• NEWS summarizes user-visible release changes.
• ChangeLog records source-level project history.

License

This project is licensed under GPL-3.0-only. See COPYING and docs/license.md for details.