Repository navigation
Commit e7d27b4
authored
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
File tree
- docs
- adr
- commands
- usecases
- internal
- action
- store
- leaf
- root
- tests
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
4 | 6 | | |
5 | 7 | | |
6 | 8 | | |
7 | 9 | | |
8 | 10 | | |
| 11 | + | |
9 | 12 | | |
10 | 13 | | |
11 | 14 | | |
12 | 15 | | |
13 | | - | |
| 16 | + | |
| 17 | + | |
14 | 18 | | |
15 | 19 | | |
16 | 20 | | |
| |||
24 | 28 | | |
25 | 29 | | |
26 | 30 | | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
27 | 50 | | |
28 | 51 | | |
29 | 52 | | |
30 | 53 | | |
31 | 54 | | |
| 55 | + | |
32 | 56 | | |
33 | 57 | | |
34 | 58 | | |
| |||
45 | 69 | | |
46 | 70 | | |
47 | 71 | | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
48 | 78 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
| 5 | + | |
5 | 6 | | |
6 | | - | |
7 | | - | |
| 7 | + | |
| 8 | + | |
8 | 9 | | |
9 | 10 | | |
10 | 11 | | |
11 | 12 | | |
12 | 13 | | |
13 | | - | |
14 | | - | |
15 | | - | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
16 | 19 | | |
17 | 20 | | |
18 | | - | |
| 21 | + | |
19 | 22 | | |
20 | | - | |
21 | | - | |
22 | | - | |
23 | | - | |
| 23 | + | |
24 | 24 | | |
25 | | - | |
| 25 | + | |
26 | 26 | | |
27 | | - | |
28 | | - | |
29 | | - | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
30 | 103 | | |
31 | 104 | | |
32 | 105 | | |
| |||
37 | 110 | | |
38 | 111 | | |
39 | 112 | | |
40 | | - | |
| 113 | + | |
41 | 114 | | |
42 | 115 | | |
43 | 116 | | |
44 | 117 | | |
45 | 118 | | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
127 | 127 | | |
128 | 128 | | |
129 | 129 | | |
130 | | - | |
131 | 130 | | |
132 | 131 | | |
133 | 132 | | |
| |||
0 commit comments