From 1d41a85fcad3dcca8459052402206262f6c41c09 Mon Sep 17 00:00:00 2001
From: Filippo Valsorda <hi@filippo.io>
Date: Fri, 17 Dec 2021 20:20:03 +0100
Subject: [PATCH] passage: update README and split extensions

---
 INSTALL               |  5 +++++
 README                | 42 ++++++++++++++++++++++++++++++++++++++----
 src/password-store.sh |  3 ++-
 3 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/INSTALL b/INSTALL
index a962f35..c56c01a 100644
--- a/INSTALL
+++ b/INSTALL
@@ -4,6 +4,11 @@ Simply typing
 
 should install passage to the standard locations.
 
+To install on a macOS system with Homebrew type
+
+    make install PREFIX="$(brew --cellar)/passage/$(git describe --tags)"
+    brew link passage
+
 The makefile is aware of the following environment variables:
 
 PREFIX      default: /usr
diff --git a/README b/README
index 30ea4cc..60cbed3 100644
--- a/README
+++ b/README
@@ -12,16 +12,50 @@ The password store is at $HOME/.passage/store by default.
 For decryption, the age identities at $HOME/.passage/identities are used with
 the -i age CLI option.
 
-For encryption, the nearest .age-recipients file is used with the -R age CLI
+For encryption, the nearest .age-recipients file (that is, the one in the same
+directory as the secret, or in the closest parent) is used with the -R age CLI
 option. If no .age-recipients files are found, the identities file is used with
 the -i option.
 
-Extensions by default are searched at $HOME/.passage/store. Most password-store
-extensions should work with passage.
+Extensions are searched at $HOME/.passage/store. password-store extensions that
+wish to be compatible with passage can switch on the PASSAGE variable.
 
 The init command is not currently available, and moving or copying a secret
 always re-encrypts it.
 
+Example: simple set up
+----------------------
+
+In this setup, the key is simply saved on disk, which can be useful if the
+password store is synced to a location less trusted than the local disk.
+
+    age-keygen >> $HOME/.passage/identities
+
+Example: set up with a password-protected key
+--------------------------------------------
+
+This setup allows using the identity file password as the primary password
+to unlock the store.
+
+    KEY="$(age-keygen)"
+    echo "$KEY" | age -p -a >> $HOME/.passage/identities
+    echo "$KEY" | age-keygen -y >> $HOME/.passage/store/.age-recipients
+
+Example: set up with rage and age-plugin-yubikey
+------------------------------------------------
+
+This setup uses rage (https://github.com/str4d/rage), since age v1.0.0 does
+not support plugins yet, and the PIV plugin age-plugin-yubikey
+(https://github.com/str4d/age-plugin-yubikey).
+
+It's recommended to add more YubiKeys and/or age keys to the .age-recipients
+file as recovery options, in case this YubiKey is lost.
+
+    export PASSAGE_AGE=rage
+    age-plugin-yubikey # run interactive setup
+    age-plugin-yubikey --identity >> $HOME/.passage/identities
+    age-plugin-yubikey --list >> $HOME/.passage/store/.age-recipients
+
 Migrating from pass
 -------------------
 
@@ -50,4 +84,4 @@ Environment variables
                             Space separated, each passed to age with -r
 
 All other environment variables from password-store are respected, such as
-PASSWORD_STORE_EXTENSIONS_DIR and PASSWORD_STORE_GENERATED_LENGTH.
+PASSWORD_STORE_CLIP_TIME and PASSWORD_STORE_GENERATED_LENGTH.
diff --git a/src/password-store.sh b/src/password-store.sh
index 1f824b2..83549ef 100755
--- a/src/password-store.sh
+++ b/src/password-store.sh
@@ -7,10 +7,11 @@ umask "${PASSWORD_STORE_UMASK:-077}"
 set -o pipefail
 
 AGE="${PASSAGE_AGE:-age}"
+PASSAGE="1"
 
 PREFIX="${PASSAGE_DIR:-$HOME/.passage/store}"
 IDENTITIES_FILE="${PASSAGE_IDENTITIES_FILE:-$HOME/.passage/identities}"
-EXTENSIONS="${PASSWORD_STORE_EXTENSIONS_DIR:-$HOME/.passage/extensions}"
+EXTENSIONS="${PASSAGE_EXTENSIONS_DIR:-$HOME/.passage/extensions}"
 X_SELECTION="${PASSWORD_STORE_X_SELECTION:-clipboard}"
 CLIP_TIME="${PASSWORD_STORE_CLIP_TIME:-45}"
 GENERATED_LENGTH="${PASSWORD_STORE_GENERATED_LENGTH:-25}"