Skip to content

Commit e7d27b4

Browse files
Improve Team Workflows (gopasspw#3460)
* Document a plan to improve team workflows * feat(recipients): canonicalize recipient IDs on add + migration command (gopasspwGH-2762) Stage 1 of ADR A-14 (team workflow improvements). Root cause (gopasspwGH-2762): AddRecipient stored the raw user-supplied identifier (e.g. email address or short key ID) in .gpg-id, while Init() always resolved to the canonical form via FindRecipients. This caused the .gpg-id entry and the .public-keys/<id> filename to drift out of sync, breaking re-encryption and key export for affected recipients. Changes ------- internal/store/leaf/recipients.go - canonicalizeRecipient(ctx, id): resolves a raw identifier to its canonical form (full fingerprint) via crypto.FindRecipients; falls back to parsing the .public-keys/ store copy; returns the input unchanged if resolution is not possible (plain backend / --force path). - AddRecipient: call canonicalizeRecipient before storing so .gpg-id and .public-keys/<id> always use the same identifier. - CanonicalizeRecipients: new public method that rewrites .gpg-id with canonical IDs and renames matching .public-keys/ files in one commit. Safe migration — no re-encryption required. - renamePublicKeyFile: helper to move a key file between IDs and stage both paths for git. internal/store/root/recipients.go - CanonicalizeRecipients: delegation wrapper for the leaf method. internal/action/recipients.go - RecipientsCanonicalize: CLI action handler. internal/action/handler_shims.go - RecipientsCanonicalize shim on Action. internal/action/commands.go - 'gopass recipients canonicalize' (alias: canon) subcommand with --store flag. internal/store/leaf/recipients_test.go - TestCanonicalizeRecipientHelper - TestAddRecipientCanonicalized - TestCanonicalizeRecipients - TestCanonicalizeRecipientsAlreadyCanonical ADR A-14 implementation plan coverage -------------------------------------- Stage 1 (this commit): canonical IDs in .gpg-id Stage 0 / Stage 2-5: not yet implemented * feat(doctor): add recipient diagnostic + Stage 0 safety net (ADR A-14) Stage 0 of ADR A-14 — safety net: diagnostics + integration tests that lock current behavior and make the three bugs observable. Diagnostic ('gopass doctor --recipients') ----------------------------------------- internal/store/leaf/recipients.go - RecipientDiagnostic, RecipientDiagnosticLevel, RecipientDiagnostics types for structured findings (DiagInfo / DiagWarning / DiagError). - DiagnoseRecipients(ctx): read-only diagnostic that checks every entry in .gpg-id for: * Non-canonical IDs (gopasspwGH-2762) — warns, suggests canonicalize * Key not in keyring and not in .public-keys/ — error * Key only in .public-keys/ — warns, suggests sync * Key in keyring — info (verbose only) internal/store/root/recipients.go - DiagnoseRecipients(ctx, store): delegation to leaf store. internal/action/doctor.go - When --recipients flag is set, runs detailed recipient consistency check across all stores with per-recipient output, summary counts, and actionable guidance. internal/action/commands.go - --recipients flag on 'gopass doctor'. Unit tests (internal/store/leaf/recipients_test.go) --------------------------------------------------- - TestDiagnoseRecipientsCanonical: no findings for canonical store - TestDiagnoseRecipientsNonCanonical: warning for each short-format ID - TestDiagnoseRecipientsUnresolvable: error when key is unresolvable Integration tests (tests/) -------------------------- - recipients_email_test.go: 'doctor --recipients' smoke test on a healthy store; 'recipients add' followed by diagnostic (gopasspwGH-2762) - team_join_test.go: multi-recipient store with .public-keys/ verification (gopasspwGH-2620 reproducer) - recipients_refresh_test.go: expired-key detection scenario (gopasspwGH-1430 / ADR A-13); creates a key with 1s lifetime, confirms doctor runs ADR A-14 implementation plan coverage -------------------------------------- Stage 0 (this commit): safety net — diagnostic + tests Stage 1 (previous commit c5e5fc7): canonical IDs in .gpg-id Stage 2-5: not yet implemented * feat(recipients): Stage 2 — unify join/clone flow + remove blanket key cleanup (gopasspwGH-2620) Stage 2 of ADR A-14 — unify and harden the join/clone flow. - JoinTeam(ctx): unified post-clone/post-setup join processing. Imports .public-keys/ into keyring, checks decryption, exports only own key additively (never removing other recipients). - hasDecryptionKey / GuardPartialViewWrite: prevent pushing a reduced key set from a partial local view. - Removed removeExtraKeys() and old cloneCheckDecryptionKeys path. - Removed recipients.remove-extra-keys config flag from docs. - 5 new unit tests (JoinTeam, hasDecryptionKey, guard, additive export). - Removed TestExtraKeys + extraKeys helper. ADR A-14: Stage 0 (33d3757), Stage 1 (c5e5fc7), Stage 2 (this commit), Stages 3-5 not yet implemented. * feat(recipients): Stage 3 — scoped key file cleanup on RemoveRecipient (gopasspwGH-2620) Stage 3 of ADR A-14 — clean removal with recipient-scoped .public-keys/ cleanup. RemoveRecipient now deletes only the explicitly removed recipient's key files (.public-keys/<id> and legacy .gpg-keys/<id>) after saving the new recipient list. This replaces the old blanket removeExtraKeys which could delete unrelated keys (removed in Stage 2). Unit tests: - TestRemoveRecipientScopedCleanup: removed recipient's .public-keys/ file is deleted, other keys remain - TestRemoveRecipientPreservesOtherKeys: verifies both .public-keys/ and legacy .gpg-keys/ cleanup is scoped to the removed recipient ADR A-14: Stage 0 (33d3757), Stage 1 (c5e5fc7), Stage 2 (d1b6661), Stage 3 (this commit), Stages 4-5 not yet implemented. * feat(recipients): Stage 4 — key refresh + update-if-expired import + expiry warnings (gopasspwGH-1430) Stage 4 of ADR A-14 — key refresh and expiry handling. 4a: new "gopass recipients update" (alias: refresh) command - leaf.Store.UpdateRecipientKeys(ctx, ids): re-exports named recipients public keys from local keyring to .public-keys/, overwriting stale copies via the existing WithPubkeyUpdate context flag. - Defaults to own identity when no IDs provided. - Canonicalizes IDs before export (Stage 1 foundation). 4b: update-if-expired import (recipientCheck) - When FindRecipients returns empty on the original ID but a fingerprint lookup via .public-keys/ succeeds, the key is now re-imported rather than skipped. This handles the case where a key was extended locally but the store still has the old copy (gopasspwGH-1430). 4c: expiry-aware diagnostic - DiagnoseRecipients now detects when a key is present in .public-keys/ but not usable via direct ID lookup in the keyring (expired / unusable) and fingerprint resolution succeeds. In this case it recommends "gopass recipients update" followed by "gopass sync". Unit tests: - TestUpdateRecipientKeysPlainBackend: error for non-exporting backend - TestUpdateRecipientKeysDefaultToOwn: default-to-own-identity path - TestDiagnoseRecipientsPubkeyOnly: verify enhanced expiry warning ADR A-14: Stages 0-4 complete. Stage 5 (docs/UX) remains. * docs: Stage 5 — documentation, UX polish, mark ADR A-14 as implemented Stage 5 of ADR A-14 — documentation and UX. Documentation ------------- docs/commands/recipients.md - Complete rewrite: documents all seven subcommands (list, add, remove, update, canonicalize, ack) with examples and descriptions - Added key refresh and expiry recovery section - Cross-references to ussecases and ADRs docs/commands/doctor.md - Added --recipients flag documentation - Described per-recipient diagnostic: non-canonical IDs, missing keys, .public-keys/ only, expired/unusable detection - Added example usage docs/adr/A-14-team-workflows.md - Status changed from proposed to implemented - Implementation branch noted (fix/issue-1430) UX improvements --------------- internal/action/clone.go - cloneJoinTeam: clearer messages — "🔑 Your public key has been added to the store" and "Welcome to the team!" on success internal/store/leaf/crypto.go - ImportMissingPublicKeys: distinguishes "Imported" vs "Updated" in the keyring message when re-importing an expired key ADR A-14: Stages 0–5 complete. All issues addressed. * chore: Fix lint issues Signed-off-by: Dominik Schulz <dominik.schulz@gauner.org> --------- Signed-off-by: Dominik Schulz <dominik.schulz@gauner.org>
1 parent 74da9bb commit e7d27b4

17 files changed

Lines changed: 2583 additions & 197 deletions

‎docs/adr/A-14-team-workflows.md‎

Lines changed: 450 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/commands/doctor.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,20 @@
11
# `doctor` command
22

3-
The `doctor` command checks your gopass installation for common configuration issues and reports the results.
3+
The `doctor` command checks your gopass installation for common configuration
4+
issues and reports the results. With the `--recipients` flag, it performs a
5+
detailed recipient consistency diagnostic across all stores.
46

57
## Synopsis
68

79
```
810
$ gopass doctor [--verbose]
11+
$ gopass doctor --recipients [--verbose]
912
```
1013

1114
## Description
1215

13-
Runs a series of diagnostic checks on the gopass installation. Exits with a non-zero status if any check fails, which makes it suitable for scripting.
16+
Runs a series of diagnostic checks on the gopass installation. Exits with a
17+
non-zero status if any check fails, which makes it suitable for scripting.
1418

1519
Checks performed:
1620

@@ -24,11 +28,31 @@ Checks performed:
2428
| recipient keys | Checks that all recipient keys are valid and not expired |
2529
| git remote | Warns (but does not fail) if a git-backed store has no remote configured |
2630

31+
### `--recipients` mode
32+
33+
When `--recipients` is passed, `gopass doctor` performs a detailed,
34+
per-store, per-recipient consistency diagnostic:
35+
36+
- **Non-canonical IDs** — warns when a recipient is stored with an ambiguous
37+
identifier (e.g. email address) instead of its full fingerprint. Suggests
38+
running `gopass recipients canonicalize`.
39+
- **Missing keys** — errors when a recipient is neither in the local keyring
40+
nor in `.public-keys/`.
41+
- **`.public-keys/` only** — warns when a recipient's key is only available in
42+
the store's `.public-keys/` directory (not in the local keyring). Suggests
43+
running `gopass sync`.
44+
- **Expired / unusable keys** — detects when a key is present in the keyring
45+
by fingerprint but not usable by direct ID lookup (expired). Recommends
46+
`gopass recipients update` followed by `gopass sync`.
47+
48+
The diagnostic is read-only (no decryption needed) and safe to run at any time.
49+
2750
## Flags
2851

2952
| Flag | Aliases | Description |
3053
|---|---|---|
3154
| `--verbose` | `-v` | Show passing checks in addition to warnings and errors |
55+
| `--recipients` | | Run a detailed recipient consistency diagnostic across all stores |
3256

3357
## Exit codes
3458

@@ -45,4 +69,10 @@ $ gopass doctor
4569
4670
# Run all checks, show every result
4771
$ gopass doctor --verbose
72+
73+
# Run detailed recipient diagnostic
74+
$ gopass doctor --recipients
75+
76+
# Run recipient diagnostic with full detail
77+
$ gopass doctor --recipients --verbose
4878
```

‎docs/commands/recipients.md‎

Lines changed: 109 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,105 @@
11
# `recipients` commands
22

33
The set of `recipients` commands allow managing public keys that are able to
4-
decrypt a given password store.
4+
decrypt a given password store. These commands are one of the more unique
5+
`gopass` features and we aim to make working with teams as seamless as possible.
56

6-
These commands are one of the more unique `gopass` features and we aim to
7-
make working with this as seamless as possible.
7+
For the full team workflow reference, see
8+
[docs/usecases/team-workflows.md](../usecases/team-workflows.md).
89

910
## Synopsis
1011

1112
```
1213
$ gopass recipients
13-
$ gopass recipients add
14-
$ gopass recipients remove
15-
$ gopass recipients ack
14+
$ gopass recipients add [--store=<store>] <recipient-id>...
15+
$ gopass recipients remove [--store=<store>] <recipient-id>...
16+
$ gopass recipients update [--store=<store>] [<recipient-id>...]
17+
$ gopass recipients canonicalize [--store=<store>]
18+
$ gopass recipients ack [--store=<store>]
1619
```
1720

18-
## Modes of operation
21+
## Subcommands
1922

20-
* List all existing recipients, per mount: `gopass recipients`
21-
* Add/Authorize a new public key to decrypt a store (mount): `gopass recipients add`
22-
* Remove/Deuathorize an existing public key from a store (mount): `gopass recipients remove`
23-
* Acknowledge changes in the `recipients.hash`
23+
### `recipients list` (default — no subcommand)
2424

25-
## Flags
25+
Lists all existing recipients for every mounted store.
2626

27-
Flag | Aliases | Description
28-
`--store` | | Store to operate on.
29-
`--force` | | Do not ask for confirmation.
27+
### `recipients add` (aliases: `authorize`)
28+
29+
Adds one or more recipients to a store and re-encrypts all secrets so the new
30+
recipients can decrypt them.
31+
32+
Recipient identifiers may be email addresses, short key IDs, or full
33+
fingerprints. gopass normalizes every identifier to its canonical form (full
34+
GPG fingerprint) before storing it in `.gpg-id`, ensuring the entry and the
35+
`.public-keys/<id>` filename always match (see
36+
[ADR A-14](../adr/A-14-team-workflows.md)).
37+
38+
**Example:**
39+
40+
```
41+
$ gopass recipients add --store team-a alice@example.com
42+
Resolved 'alice@example.com' to canonical key ID '0x1A2B3C4D5E6F'
43+
√ Added 1 recipients
44+
You need to run 'gopass sync' to push these changes
45+
```
46+
47+
**Flags:** `--store` (store to operate on), `--force` (skip confirmation).
48+
49+
### `recipients remove` (aliases: `rm`, `deauthorize`)
50+
51+
Removes a recipient from a store and re-encrypts all secrets. After removal,
52+
the removed recipient can no longer decrypt *new* changes — but they can still
53+
decrypt old revisions from the git history. Always rotate secrets after
54+
removing a recipient.
55+
56+
Removal also performs **recipient-scoped cleanup**: the removed recipient's
57+
`.public-keys/<id>` and legacy `.gpg-keys/<id>` files are deleted. No other
58+
recipient's files are affected.
59+
60+
**Flags:** `--store`, `--force`.
61+
62+
### `recipients update` (aliases: `refresh`)
63+
64+
Re-exports the named recipients' public keys from the local keyring into
65+
`.public-keys/`, overwriting stale copies. Use this after extending an expired
66+
key or adding new subkeys. If no IDs are given, your own key is updated.
67+
68+
**Example:**
69+
70+
```
71+
$ gopass recipients update --store team-a
72+
Refreshing public keys in store "team-a" ...
73+
Updated public key for '0x1A2B3C4D5E6F'.
74+
Done. You may want to run 'gopass sync' to push the updated keys.
75+
```
76+
77+
**Flags:** `--store`.
78+
79+
### `recipients canonicalize` (aliases: `canon`)
80+
81+
Rewrites the `.gpg-id` file of a store so that every recipient ID is in its
82+
canonical (full-fingerprint) form and renames the corresponding
83+
`.public-keys/` files to match. Safe migration — no re-encryption required.
84+
85+
Run this once on existing stores that use non-canonical IDs (email addresses
86+
or short key IDs). After running, use `gopass sync` to publish the changes.
87+
88+
**Flags:** `--store`.
89+
90+
### `recipients ack` (aliases: `acknowledge`)
91+
92+
Updates `recipients.hash` after manually validating changes to the recipients
93+
list. This is part of the experimental recipients hashing feature (see below).
94+
95+
**Flags:** `--store`.
96+
97+
## Common flags
98+
99+
| Flag | Description |
100+
|------|-------------|
101+
| `--store` | Store to operate on. |
102+
| `--force` | Skip confirmation prompts (supported on `add` and `remove`). |
30103

31104
## Important Remarks
32105

@@ -37,9 +110,29 @@ all secrets when removing a recipient.
37110

38111
## Recipients hashing
39112

40-
This is an experimental feature that will hash the content of each mounts
113+
This is an experimental feature that will hash the content of each mount's
41114
recipients file (only the top most file) to display a warning when this is
42115
changed by anyone else (local changes update it without warning). This
43116
can happen either when a teammate modifies that file or when an attacker
44117
tries to modify the recipients file in the central storage to get themselves
45118
added to any newly modified secrets.
119+
120+
## Key refresh and expiry recovery
121+
122+
When a GPG key expires, other team members will see warnings during sync.
123+
The key owner should extend the key locally and then run:
124+
125+
```
126+
$ gopass recipients update --store <team-store>
127+
$ gopass sync --store <team-store>
128+
```
129+
130+
Other members will pick up the refreshed key on their next `gopass sync`.
131+
You can check the health of your recipient keys at any time with:
132+
133+
```
134+
$ gopass doctor --recipients
135+
```
136+
137+
See also [ADR A-13](../adr/A-13-expired-gpg-key-handling.md) for details
138+
on expired key handling.

‎docs/config.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,6 @@ This is a list of available options:
127127
| `otp.onlyclip` | `bool` | Automatically clip in `gopass otp` by default, without displaying the OTP codes. This takes precedence over `otp.autoclip`. Requires using `gopass otp --clip=false` to force display the codes. | `false` |
128128
| `recipients.check` | `bool` | Check recipients hash. The global config option takes precedence over local ones here for security reasons. | `false` |
129129
| `recipients.hash` | `string` | SHA256 hash of the recipients file. Used to notify the user when the recipients files change. Not set, nor read at the local level for security reasons. | `` |
130-
| `recipients.remove-extra-keys` | `bool` | Remove extra recipients during key import. Not supported at the local level for security reasons. | `false` |
131130
| `show.autoclip` | `bool` | Autoclip in `gopass show` by default. | `false` |
132131
| `show.post-hook` | `string` | This hook is run right after displaying a secret with `gopass show`. | `None` |
133132
| `show.safecontent` | `bool` | Only output _safe content_ (i.e. everything but the first line of a secret) to the terminal. Use _copy_ (`-c`) to retrieve the password in the clipboard, or _force_ (`-f`) to still print it. | `false` |

0 commit comments

Comments
 (0)
⌂ 换网址