passforios/plans/02-multi-recipient-encryption-plan.md

Multi-Recipient Encryption Plan

Concept

The pass password store format supports encrypting each password to multiple PGP keys via .gpg-id files (one key ID per line). This enables sharing a store with other users — each person imports the same git repository but decrypts with their own private key. When adding or editing a password, it must be encrypted to all key IDs listed in .gpg-id.

The app currently has a setting (isEnableGPGIDOn) that reads .gpg-id for per-directory key selection, but it only supports a single key ID. This plan fixes every layer to support multiple recipients.

This is standalone — it can be implemented before or after multi-store support.

---

Current State

The codebase does not support encrypting to multiple public keys. Every layer assumes a single recipient:

Layer	Current state	What needs to change
.gpg-id file format	Supports multiple key IDs (one per line)	No change needed
findGPGID(from:)	Returns the entire file as one trimmed string — does not split by newline	Split by newline, return [String]
PGPInterface.encrypt()	Signature: encrypt(plainData:keyID:) — singular keyID: String?	Add encrypt(plainData:keyIDs:[String]) or change keyID to keyIDs: [String]?
GopenPGPInterface	Creates a CryptoKeyRing with one public key	Add all recipient public keys to the keyring before encrypting
ObjectivePGPInterface	Passes keyring.keys (all keys, including private) — accidentally multi-recipient but not intentionally	Filter to only the specified public keys, pass those to ObjectivePGP.encrypt()
PGPAgent.encrypt()	Routes to a single key via keyID: String	Accept [String] and pass through to the interface
PasswordStore.encrypt()	Calls findGPGID() for a single key ID string	Call the updated findGPGID(), pass the key ID array

---

Implementation

1. findGPGID(from:) -> [String]

Split file contents by newline, trim each line, filter empty lines. Return array of key IDs. Callers that only need a single key (e.g. for decryption routing) can use .first.

2. PGPInterface protocol

Change encrypt(plainData:keyID:) to encrypt(plainData:keyIDs:) where keyIDs: [String]?. When nil, encrypt to the first/default key (backward compatible).

3. GopenPGPInterface.encrypt()

Look up all keys matching the keyIDs array from publicKeys. Add each to the CryptoKeyRing (GopenPGP's CryptoKeyRing supports multiple keys via add()). Encrypt with the multi-key ring.

4. ObjectivePGPInterface.encrypt()

Filter keyring.keys to only the public keys matching the requested keyIDs. Pass the filtered array to ObjectivePGP.encrypt().

5. PGPAgent.encrypt()

Update both overloads to accept keyIDs: [String]? and pass through to the interface.

6. PasswordStore.encrypt()

Call updated findGPGID(), pass the array to PGPAgent.

---

Public Key Management

When a store lists multiple key IDs in .gpg-id, the user needs the public keys of all recipients. The user's own private key is sufficient for decryption (since the message is encrypted to all recipients), but all public keys are needed for re-encryption when editing.

Current state

• The keychain holds exactly one pgpPublicKey blob and one pgpPrivateKey blob.
• The import UI (armor paste, URL, file picker) has one public key field + one private key field. Importing replaces the previous key pair entirely.
• Both GopenPGPInterface and ObjectivePGPInterface can parse multiple keys from a single armored blob (e.g. concatenated armor blocks). So if the user pastes multiple public keys into the single field, they would be parsed — but the encrypt path only uses one key, and the UI doesn't communicate this.
• There is no UI for viewing which key IDs are loaded.

Key storage approach

Store all public keys as a single concatenated armored blob in the keychain (pgpPublicKey). Both interface implementations already parse multi-key blobs into dictionaries/keyrings. This avoids schema changes — we just need to append instead of replace when importing additional public keys.

The user's own private key stays as a separate single blob (pgpPrivateKey).

7. UI: Import additional recipient public keys

Add an "Import Recipient Key" action to the PGP key settings (alongside the existing import that sets the user's own key pair). This flow:

• Imports a public-key-only armored blob
• Appends it to the existing pgpPublicKey keychain entry (concatenating armored blocks)
• Does not touch the private key
• On success, shows the newly imported key ID(s)

The existing import flow ("Set PGP Keys") continues to replace the user's own key pair (public + private).

8. UI: View loaded key IDs and metadata

PGP keys carry a User ID field, typically in the format "Name <email@example.com>". Both GopenPGP (key.entity.PrimaryIdentity()) and ObjectivePGP (key.keyID + user ID packets) can access this. The app currently doesn't expose it.

Add key metadata to the PGPInterface protocol:

struct PGPKeyInfo {
    let fingerprint: String    // full fingerprint
    let shortKeyID: String     // last 8 hex chars
    let userID: String?        // "Name <email>" from the primary identity
    let isPrivate: Bool        // has a matching private key
    let isExpired: Bool
    let isRevoked: Bool
}
var keyInfo: [PGPKeyInfo] { get }

Both GopenPGPInterface and ObjectivePGPInterface should implement this by iterating their loaded keys.

Add a read-only section to the PGP key settings showing all loaded public keys. Each row shows:

• User ID (e.g. "Alice <alice@example.com>") as the primary label — this is the human-readable identifier
• Short key ID (e.g. ABCD1234) as the secondary label
• Badge/icon if it's the user's own key (has matching private key) vs a recipient-only key
• Badge/icon if expired or revoked
• Swipe-to-delete to remove a recipient public key

This also informs the .gpg-id editing UI (§9) — when the user adds/removes recipients from .gpg-id, they see names and emails, not just opaque hex key IDs.

9. UI: View/edit .gpg-id files

When isEnableGPGIDOn is enabled, add visibility into .gpg-id:

• In the password detail view, show which key IDs the password is encrypted to (from the nearest .gpg-id file)
• In folder navigation, show an indicator on directories that have their own .gpg-id
• Tapping the indicator shows the .gpg-id contents (list of key IDs) with an option to edit
• Editing .gpg-id triggers re-encryption of all passwords in the directory (see §10)

Note: Viewing .gpg-id is low-effort and high-value. Editing is more complex due to re-encryption. These can be split into separate steps.

10. Re-encryption when .gpg-id changes

When the user edits a .gpg-id file (adding/removing a recipient), all .gpg files in that directory (and subdirectories without their own .gpg-id) must be re-encrypted to the new recipient list. This is equivalent to pass init -p subfolder KEY1 KEY2.

Steps:

1. Write the new .gpg-id file
2. For each .gpg file under the directory:
   • Decrypt with the user's private key
   • Re-encrypt to the new recipient list
   • Overwrite the .gpg file
3. Git add all changed files + .gpg-id
4. Git commit

This can be expensive for large directories. Show progress and allow cancellation.

---

Implementation Order

Step	Description	Depends On
1	findGPGID returns [String] + update callers	—
2	PGPInterface protocol change (keyIDs: [String]?)	—
3	GopenPGPInterface multi-key encryption	Step 2
4	ObjectivePGPInterface multi-key encryption	Step 2
5	PGPAgent updated overloads	Steps 2-4
6	PasswordStore.encrypt() uses [String] from findGPGID	Steps 1+5
7	UI: import additional recipient public keys	Step 5
8	UI: view loaded key IDs	Step 5
9a	UI: view .gpg-id in password detail / folder view	Step 1
9b	UI: edit .gpg-id	Step 9a
10	Re-encryption when .gpg-id changes	Steps 6+9b
T	Tests (see testing section)	Steps 1-10

---

Testing

Pre-work: existing encryption tests

The PGPAgentTest already covers single-key encrypt/decrypt with multiple key types. These serve as the regression baseline.

Multi-recipient encryption tests

• Test findGPGID with multi-line .gpg-id: File with two key IDs on separate lines → returns [String] with both.
• Test findGPGID with single-line .gpg-id: Backward compatible → returns [String] with one element.
• Test findGPGID with empty lines and whitespace: Trims and filters correctly.
• Test GopenPGPInterface.encrypt with multiple keys: Encrypt with two public keys → decrypt succeeds with either private key.
• Test ObjectivePGPInterface.encrypt with multiple keys: Same as above.
• Test PGPAgent.encrypt with keyIDs array: Routes through correctly to the interface.
• Test round-trip: Encrypt with key IDs [A, B] → user with private key A can decrypt, user with private key B can decrypt.
• Test encrypt with single keyID still works: Backward compatibility — keyIDs: ["X"] behaves like the old keyID: "X".
• Test encrypt with unknown keyID in list: If one of the key IDs is not in the keyring, appropriate error is thrown.
• Test multi-key public key import: Import an armored blob containing multiple public keys → all are available for encryption.

Key management tests

• Test appending recipient public key: Import user's key pair → append a second public key → both key IDs are available. Original private key still works for decryption.
• Test removing a recipient public key: Remove one public key from the concatenated blob → only the remaining key IDs are available.
• Test replacing key pair doesn't lose recipient keys: Import user's key pair → add recipient key → re-import user's key pair → recipient key is still present (or: design decision — should re-import clear everything?).

.gpg-id and re-encryption tests

• Test re-encryption: Edit .gpg-id to add a recipient → all passwords in directory are re-encrypted → new recipient can decrypt.
• Test re-encryption removes access: Edit .gpg-id to remove a recipient → re-encrypted passwords cannot be decrypted with the removed key.
• Test .gpg-id directory scoping: Subdirectory .gpg-id overrides parent. Passwords in subdirectory use subdirectory's recipients.
• Test multi-key public key import: Import an armored blob containing multiple public keys → all are available for encryption.