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.

Options:

• Import additional public keys (alongside the user's own key pair)
• Or fetch them from a keyserver (out of scope for initial implementation)
• The PGP key import flow should allow importing multiple public keys
• PGPAgent.initKeys() already supports loading multiple keys from a single armored blob (both GopenPGPInterface and ObjectivePGPInterface parse multi-key armored input)

---

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
T	Tests (see testing section)	Steps 1-6

---

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.