# Proton Auth & Crypto Analysis

> Prepared for the hermes-proton shared auth plugin design (T1 architecture spec).
> Sources: go-proton-api (src), go-srp, gopenpgp v2, hydroxide (emersion), proton-python-client.

---

## 1. SRP-6a Authentication Flow

Proton implements **SRP-6a** (Secure Remote Password protocol) for all client-server
authentication. There is no OAuth2, OpenID Connect, or any standard web auth layer —
SRP is the only path to an API session.

### 1.1 Protocol Overview

```
Client                              Server
  │                                    │
  │  POST /auth/v4/info                │
  │  { username }                      │
  │ ─────────────────────────────►      │
  │                                    │
  │  { Version, Modulus (signed),      │
  │    ServerEphemeral, Salt,          │
  │    SRPSession }                    │
  │ ◄─────────────────────────────      │
  │                                    │
  │  Compute SRP proofs:               │
  │  • HashPassword(password, salt,    │
  │    modulus, version)                │
  │  • a = random()                    │
  │  • A = g^a mod N                   │
  │  • u = H(A || B)                   │
  │  • S = (B - k·g^x)^(a + u·x) mod N│
  │  • M1 = H(A || B || S)            │
  │                                    │
  │  POST /auth/v4                     │
  │  { Username, ClientEphemeral (A),  │
  │    ClientProof (M1), SRPSession }  │
  │ ─────────────────────────────►      │
  │                                    │
  │  { ServerProof, UID,              │
  │    AccessToken, RefreshToken,      │
  │    UserID, EventID, ExpiresAt }    │
  │ ◄─────────────────────────────      │
  │                                    │
  │  Verify ServerProof = M2           │
  │  (H(A || M1 || S))                 │
  │                                    │
```

### 1.2 Password Hashing (Version-Dependent)

Proton's SRP uses **bcrypt + SHA-512** for password pre-hashing before the SRP
computation. The hash version is negotiated via the `Version` field in `AuthInfo`.

| Version | Method | Key Detail |
|---------|--------|------------|
| **0**   | SHA-512(lower(username) + password) → base64 → V1 | Legacy, pre-V3 session |
| **1**   | MD5(lower(username)) → hex salt → bcrypt(password, salt) → expandHash(result + modulus) | Legacy |
| **2**   | Same as V1 after stripping `-._` from username | Legacy |
| **3**   | bcrypt(password, based64(salt + "proton")) → expandHash(result + modulus) | **Current** (majority of users) |
| **4**   | Same as V3 | Current (same algorithm) |

The `expandHash()` function uses 4x SHA-512 (with appended bytes 0,1,2,3) concatenated
to produce a 256-byte digest.

**Source:** `go-srp/hash.go` — `HashPassword()` dispatches by version.
`go-srp/srp.go` — `NewAuth()` calls `HashPassword()` then generates SRP proofs.

### 1.3 Modulus Verification

The SRP modulus `N` is signed using Proton's PGP key. Before any SRP computation:

1. Server returns the modulus as a **clearsigned PGP message** (armored + signature)
2. Client verifies the signature against Proton's hardcoded public key
3. Rejects if extra data follows the signature (`ErrDataAfterModulus`)

**Source:** `go-srp/srp.go` — `readClearSignedMessage()`, `modulusPubkey` constant.

### 1.4 Constant-Time Arithmetic

`go-srp` uses the `saferith` library (`github.com/cronokirby/saferith`) for all
modular exponentiation — **constant-time** big integer operations to prevent
timing/side-channel attacks. The classic `math/big` is only used for parameter
validation (bit-length checks, Lucas primality test on the modulus).

### 1.5 SRP Safety Checks

The Python client (`proton/srp/_pysrp.py`) implements SRP-6a safety checks that
the Go library inherits via protocol semantics:
- `B mod N == 0` → reject (invalid server)
- `u == 0` → reject (collision, tiny probability)
- `a` is random 32 bytes, clamped to `[2*bitLength, N-1]`

### 1.6 2FA (Two-Factor Authentication)

After the SRP `/auth/v4` call, if the account has 2FA enabled, the `Auth` response
includes:

```json
{
  "2FA": {
    "Enabled": 1,
    "U2F": null,
    "TOTP": 1
  }
}
```

The client must then call:

```
POST /auth/v4/2fa
{ "TwoFactorCode": "123456" }
```

**Two modes:**
- **TOTP** — Time-based one-time password (6-digit code). Sends `TwoFactorCode`
  in the body.
- **U2F/FIDO2** — WebAuthn challenge-response. The `U2F` field in `TwoFactor`
  carries challenge data (interface{} in Go — typed as `U2FData` in practice).

After successful 2FA, the response includes the granted `Scope` (e.g. "payments",
"locked", "full").

**Source:**
- `go-proton-api/auth.go` — `Auth2FA()` → `POST /auth/v4/2fa`
- `hydroxide/protonmail/auth.go` — `AuthTOTP()` implementation
- `hydroxide/auth/auth.go` — comment: "Two-factor authentication during re-auth
  is not supported (error message)"

**⚠️ Important:** The hydroxide auth cache does **not** support 2FA during
re-authentication (token refresh). If the auth refresh fails with a 2FA requirement,
it errors out. The go-proton-api manager handles this via the standard
401 → refresh flow with no special 2FA path for refresh.

---

## 2. Session Management

### 2.1 Token Set

A successful authentication returns:

| Field | Type | Purpose |
|-------|------|---------|
| `UID` | string | Session identifier, sent as `x-pm-uid` header |
| `AccessToken` | string | Bearer token, sent as `Authorization: Bearer <token>` |
| `RefreshToken` | string | Used to obtain new tokens without re-authentication |
| `EventID` | string | Cursor for event polling (mailbox changes) |
| `UserID` | string | Internal user identifier |
| `ExpiresAt` | time.Time | Token expiry |
| `Scope` | string | Granted scope (e.g. "full", "payments", "locked") |
| `PasswordMode` | int | 1 = single password, 2 = two-password mode |

### 2.2 Token Lifecycle

```
Authentication
     │
     ▼
  ┌──────────────────────────────────────┐
  │  UID + AccessToken + RefreshToken    │  ← Immutable UID, mutable tokens
  │  (set on client)                     │
  └──────────────────────────────────────┘
     │
     ▼
  API call with AccessToken
     │
     ├── 200 OK ──► continue
     │
     └── 401 Unauthorized ──► trigger auth refresh
              │
              ▼
    POST /auth/v4/refresh
    { GrantType: "refresh_token",
      RefreshToken: <ref>,
      ResponseType: "token",
      RedirectURI: "https://protonmail.ch",
      State: <random 32 bytes>,
      UID: <uid>,
      AccessToken: <acc> }
              │
              ├── 200 OK ──► update AccessToken + RefreshToken
              │               retry original request
              │
              └── 422/400 ──► deauth (tokens permanently invalid)
                              fire deauth handlers
                              (session lost, must re-login)
```

**Source:** `go-proton-api/client.go` — `doRes()` retry logic, `authRefresh()`.

### 2.3 Auto-Refresh Mechanics

The go-proton-api `Client` wraps every API call with automatic token refresh:

1. Every request includes `x-pm-uid` header + `Authorization: Bearer <acc>`
2. On 401 response, `doRes()` calls `authRefresh()`
3. `authRefresh` returns new `AccessToken` + `RefreshToken`
4. If refresh succeeds, the original request is **retried once**
5. If refresh fails with 400/422, `deauthOnce.Do()` fires all registered
   `deauthHandlers` — the session is dead

**Concurrency:** `authLock` (sync.RWMutex) protects token storage. Reads are
RLock'd (concurrent), writes are Lock'd (exclusive). This means parallel API
calls competing on the same client will share the first refresh result.

### 2.4 Session Persistence

The `Client` struct directly holds `uid`, `acc`, `ref` as plain strings in
memory. There is no built-in persistence layer — token storage is the
**plugin's responsibility**.

**hydroxide's approach** (reference):
- Encrypts `CachedAuth` (Auth + LoginPassword + MailboxPassword + KeySalts)
  with NaCl secretbox (XSalsa20-Poly1305) using a 32-byte key
- Stores as `map[username]encrypted-blob` in `auth.json`
- Decrypts on load, caches bcrypt hash of secret key in memory
- On token refresh, re-encrypts and writes back

**Source:** `hydroxide/auth/auth.go` — `EncryptAndSave()`, `CachedAuth`.

### 2.5 Session Logout

```
DELETE /auth/v4
```
- Server-side session invalidation
- Client resets `uid`, `acc`, `ref`, `keyRing` to empty/nil

Session management endpoints:
- `GET /auth/v4/sessions` — list active sessions
- `DELETE /auth/v4/sessions` — revoke all sessions
- `DELETE /auth/v4/sessions/<uid>` — revoke specific session

**Source:** `go-proton-api/auth.go` — `AuthDelete()`, `AuthSessions()`,
`AuthRevoke()`, `AuthRevokeAll()`.

---

## 3. Token Storage Requirements

### 3.1 What Must Be Persisted

| Data | Sensitivity | Size | Required For |
|------|-------------|------|-------------|
| `UID` | Low (public) | ~36 chars | Session identity |
| `AccessToken` | **High** | ~1 KB | API authorization |
| `RefreshToken` | **High** | ~1 KB | Token renewal |
| `UserID` | Low | ~36 chars | User identification |
| `EventID` | Low | ~36 chars | Event polling cursor |
| `PasswordMode` | Low | 1 byte | Key derivation strategy |
| `LoginPassword` | **Critical** | variable | Key unlocking (single password mode) |
| `MailboxPassword` | **Critical** | variable | Key unlocking (two-password mode) |
| `KeySalts` | Medium | map[string][]byte | Key derivation |

### 3.2 Security Requirements

1. **Encrypt at rest** — Tokens are bearer credentials. If disk is compromised,
   the attacker gains full Proton API access.
2. **Per-user encryption key** — Each user's tokens encrypted with a derived key
   (not a single master key for all users).
3. **No plaintext on disk** — Never write AccessToken or RefreshToken without
   encryption.
4. **Memory clearing** — After use, zero out sensitive buffers (`ClearPrivateParams()`
   pattern from gopenpgp).
5. **Anti-replay protection** — The `RefreshToken` is single-use in practice (server
   invalidates old refresh token on each `/auth/refresh` call).

### 3.3 Recommended Storage Schema

```
┌─────────────────────────────┐
│ encrypted_tokens.json        │
│ {                            │
│   "user@pm.me": <NaCl box>,  │
│   "user2@pm.me": <NaCl box>  │
│ }                            │
└─────────────────────────────┘
```

Where each `<NaCl box>` decrypts to:
```json
{
  "uid": "...",
  "access_token": "...",
  "refresh_token": "...",
  "user_id": "...",
  "event_id": "...",
  "password_mode": 1,
  "login_password": "<encrypted or empty>",
  "mailbox_password": "<encrypted or empty>",
  "key_salts": { "key-id": "<base64 salt>" }
}
```

**Encryption choice: NaCl secretbox (XSalsa20-Poly1305)**
- Used by hydroxide (reference implementation)
- 32-byte key, 24-byte random nonce per encryption
- Authenticated encryption (integrity + confidentiality)
- Available in Python (`PyNaCl`), Go (`golang.org/x/crypto/nacl/secretbox`),
  and TypeScript (`tweetnacl`)

### 3.4 Key Management for Storage

The **session encryption key** (32 bytes) must itself be protected:
- **Option A:** Derive from a master password (user provides on plugin init)
- **Option B:** Store in Hermes agent's secure keyring (if available)
- **Option C:** Environment variable (simplest, least secure)

**Recommended: Option A with bcrypt-locked cache** (mirrors hydroxide):
1. User provides a "session key" passphrase once
2. Derive 32-byte NaCl key via argon2id/bcrypt
3. Cache bcrypt hash in memory for fast re-auth
4. Offer "forget session" to clear memory

---

## 4. gopenpgp Crypto Requirements

### 4.1 Library Overview

`github.com/ProtonMail/gopenpgp/v2` — the **canonical crypto library** for all
Proton clients. Built on top of `github.com/ProtonMail/go-crypto` (Proton's
fork of golang.org/x/crypto/openpgp).

Key properties:
- Supports **RSA** (2048+ bit) and **X25519** (Curve25519 + EdDSA) keys
- Default cipher: AES-256, default hash: SHA-256
- Default compression: ZLIB
- Session key support for symmetric encryption
- Key ring abstraction for multi-key operations

### 4.2 Per-Product Crypto Requirements

#### Mail

| Operation | gopenpgp API | Frequency |
|-----------|-------------|-----------|
| **Encrypt message** | `KeyRing.Encrypt(plainMessage, keyRing)` | Per outgoing |
| **Decrypt message** | `KeyRing.Decrypt(pgpMessage, keyRing, verifyTime)` | Per incoming |
| **Encrypt with password** | `helper.EncryptMessageWithPassword(password, text)` | Outgoing to non-PGP |
| **Decrypt with password** | `helper.DecryptMessageWithPassword(password, armor)` | Incoming shared |
| **Sign message** | `KeyRing.SignDetached(message, trimNewlines)` | Outgoing |
| **Verify signature** | `KeyRing.VerifyDetached(message, sig, verifyTime)` | Incoming |
| **Cleartext signed** | `helper.SignCleartextMessageArmored(key, pass, text)` | Outgoing public |
| **PGP/MIME encrypt** | `EncryptRFC822(kr, literal)` (from go-proton-api) | Mail sending |
| **Get public keys** | `crypto.NewKeyFromArmored(armored)` → `KeyRing.AddKey()` | Key discovery |

**Key insight:** If using **Proton Bridge** for Mail, all PGP operations are
handled transparently by the Bridge — the skill only deals with IMAP/SMTP.
Direct API integration requires the full gopenpgp stack.

#### Drive

| Operation | gopenpgp API | Frequency |
|-----------|-------------|-----------|
| **Encrypt block** | `KeyRing.Encrypt(plainData, nil)` | Per upload chunk |
| **Decrypt block** | `KeyRing.Decrypt(encData, nil, 0)` | Per download chunk |
| **Key packet** | `KeyRing.EncryptSessionKey(sessionKey)` | Upload metadata |
| **Decrypt key packet** | `KeyRing.DecryptSessionKey(keyPacket)` | Download metadata |
| **Generate session key** | `crypto.GenerateSessionKey()` | Per file upload |
| **HMAC verification** | Verify content hash after decryption | Per download |

Drive uses a **content key + block key** structure:
1. File gets a random **content key** (session key)
2. Content key encrypted with user's keyring → stored in metadata
3. Each block (chunk) encrypted with AES-256 derived from content key
4. HMAC of each block for integrity verification

**Reference:** `rclone protondrive backend` for the most complete third-party
implementation of the block encryption scheme.

#### Pass

| Operation | gopenpgp API | Frequency |
|-----------|-------------|-----------|
| **Encrypt vault item** | `KeyRing.Encrypt(plainVaultItem, nil)` | Per item save |
| **Decrypt vault item** | `KeyRing.Decrypt(encItem, nil, 0)` | Per item read |
| **Share item** | `helper.EncryptMessageWithPassword(password, item)` | Sharing |

**Note:** Proton Pass *may* be accessible via the official `pass-cli` (Rust)
which handles all crypto internally. Direct API access would require implementing
the full Pass vault encryption scheme.

If doing **direct API** (without pass-cli):
- Items are encrypted with AES-256-GCM using a vault-level key
- Vault key encrypted with user's keyring
- Each vault item = `<encrypted blob>` + `<encrypted content key packet>`

### 4.3 Key Unlocking

The key unlocking process follows a specific chain:

```
                    ┌──────────────────────────────┐
                    │    User's Login/Mailbox       │
                    │    Password (from auth)        │
                    └──────────┬───────────────────┘
                               │
                    ┌──────────▼───────────────────┐
                    │  Fetch /keys/salts            │
                    │  Returns map[keyID]base64salt │
                    └──────────┬───────────────────┘
                               │
                    ┌──────────▼───────────────────┐
                    │  Step 1: Unlock User Key       │
                    │  (user key has no Token,       │
                    │   so passphrase is used        │
                    │   directly or derived          │
                    │   via keySalt)                  │
                    └──────────┬───────────────────┘
                               │
                    ┌──────────▼───────────────────┐
                    │  Step 2: For each Address Key: │
                    │  ┌─ If key.Token exists:      │
                    │  │  Decrypt Token using user   │
                    │  │  key ring (PGP decrypt)     │
                    │  │  → get passphrase           │
                    │  │  Verify token signature      │
                    │  └─ Else: use passphrase       │
                    │     directly or with keySalt   │
                    │                                │
                    │  Then: unlock key entity        │
                    │  (decrypt all PrivateKey +      │
                    │   subkey PrivateKey fields)     │
                    └──────────┬───────────────────┘
                               │
                    ┌──────────▼───────────────────┐
                    │  Result: KeyRing with all     │
                    │  decrypted address keys       │
                    │  (openpgp.EntityList)          │
                    └──────────────────────────────┘
```

**Source:** `go-proton-api/keyring.go` — `Keys.Unlock()`, `Key.Unlock()`,
`Key.getPassphraseFromToken()`.
`hydroxide/protonmail/auth.go` — `Unlock()`, `unlockKeyRing()`, `unlockPrivateKey()`.

---

## 5. Multi-Address Keyring

### 5.1 Problem

Proton accounts can have **multiple addresses** (e.g. `user@pm.me`,
`user@protonmail.com`, `custom@domain.com`), each with its own PGP key pair.
There may be multiple keys per address (key rotation).

### 5.2 Solution in go-proton-api

The `Unlock()` flow (in hydroxide's protonmail/auth.go):
1. `GetCurrentUser()` → get user object
2. Unlock **user keys** first (these are the "master" keys)
3. `ListAddresses()` → get all addresses
4. For each address, unlock its keys using the **user key ring** for token
   decryption
5. Combine **all unlocked address key rings** into a single `openpgp.EntityList`
6. Store as `client.keyRing`

The `Keys.Unlock()` method iterates over **active** keys only (skips inactive/revoked).
If any key fails to unlock, it logs a warning and continues — only fails if
**no** keys could be unlocked.

### 5.3 Encryption Target Selection

When encrypting a message, the client:
1. Fetches recipient's public keys via `GET /core/v4/keys?Email=<address>`
2. Builds a `KeyRing` from the returned `PublicKey` objects
3. Encrypts to both (a) the recipient's keyring and (b) the sender's keyring
   (for the sent folder)

Self-encryption uses `GetPublicKeys()` on the sender's own addresses, which
returns both active and expired keys to ensure old messages remain decryptable.

### 5.4 Implications for Auth Plugin

The plugin must:
1. After login, **fetch and unlock all address keys** — this is an async
   multi-step process
2. Cache the combined `KeyRing` in plugin state
3. On new message notification, determine the correct address key
4. On address change event, re-fetch and re-unlock keys

---

## 6. API Endpoint Reference

### Authentication

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/auth/v4/info` | Get SRP challenge (modulus, salt, server ephemeral) |
| POST | `/auth/v4` | SRP authentication (username, client ephemeral, client proof) |
| POST | `/auth/v4/2fa` | Two-factor authentication (TOTP code) |
| POST | `/auth/v4/refresh` | Refresh expired tokens |
| DELETE | `/auth/v4` | Logout (server-side session invalidation) |
| GET | `/auth/v4/sessions` | List active sessions |
| DELETE | `/auth/v4/sessions` | Revoke all sessions |
| DELETE | `/auth/v4/sessions/:uid` | Revoke specific session |
| GET | `/auth/v4/modulus` | Get modulus (for password change) |

### Keys

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/keys/salts` | Get key salts for passphrase derivation |
| GET | `/core/v4/keys?Email=<addr>` | Get public keys for an address |
| POST | `/core/v4/keys/address` | Create a new address key |
| PUT | `/core/v4/keys/:id/primary` | Make key primary |
| POST | `/core/v4/keys/:id/delete` | Delete address key |

**Source:** `go-proton-api/server/auth.go` (server-side routes) and
`go-proton-api/auth.go` (client-side calls).

---

## 7. Implementation Recommendations for Auth Plugin

### 7.1 Architecture

```
┌──────────────────────────────────────────────────┐
│              Auth Plugin State                     │
│                                                    │
│  ┌──────────────┐  ┌──────────────────────────┐   │
│  │  Session Mgr  │  │    Key Manager           │   │
│  │              │  │                          │   │
│  │  • UID       │  │  • User KeyRing          │   │
│  │  • AccessToken│  │  • Address KeyRings     │   │
│  │  • RefreshToken│  │  • KeySalts cache      │   │
│  │  • Expiry    │  │  • Combined EntityList   │   │
│  └──────┬───────┘  └──────────┬───────────────┘   │
│         │                     │                    │
│         │     ┌───────────────┴────────┐           │
│         └─────►   Token Store         │           │
│               │  (encrypted JSON on   │           │
│               │   Hermes skill dir)   │           │
│               └──────────────────────┘           │
└──────────────────────────────────────────────────┘
```

### 7.2 Login Flow

```
User provides username + password
        │
        ▼
  SRP-6a: POST /auth/v4/info → get challenge
        │
        ▼
  Compute SRP proofs (go-srp or port)
        │
        ▼
  POST /auth/v4 → get Auth (UID, AccessToken, RefreshToken)
        │
        ├── 2FA required?
        │   └── prompt for TOTP → POST /auth/v4/2fa
        │
        ▼
  POST /keys/salts → get key salts
        │
        ▼
  GET /core/v4/keys?Email=<self> → get user keys
        │
        ▼
  Unlock user key ring (password + salts)
        │
        ▼
  ListAddresses() → get all addresses
        │
        ▼
  For each address: unlock address keys (via user key ring)
        │
        ▼
  Save encrypted tokens to disk
  Cache key ring in memory
```

### 7.3 Token Refresh Flow

```
API call returns 401
        │
        ▼
  POST /auth/v4/refresh (with old RefreshToken)
        │
        ├── 200 OK → update AccessToken + RefreshToken
        │              re-encrypt and save tokens
        │              retry original API call
        │
        └── 422/400 → deauth
                        fire deauth handlers
                        clear key ring from memory
                        notify user: "Session expired, re-login required"
```

### 7.4 Language Recommendation

| Component | Language | Reason |
|-----------|----------|--------|
| **Auth HTTP client** | Python (via httpx/aiohttp) | Hermes skills are Python/JS; SRP math can use `srp` package |
| **SRP math** | Python (pure) | Port the 5 functions from go-srp (~200 lines) or use `srp._pysrp` |
| **Token storage** | Python (cryptography library) | `cryptography.Fernet` (AES-256-GCM) or NaCl secretbox |
| **gopenpgp ops** | Go (subprocess) or Python (PGPy) | gopenpgp is Go-only; alternatives: (a) proton-bridge subprocess, (b) PGPy for limited ops, (c) subprocess Go helper |
| **Key ring mgmt** | Python + PGPy or subprocess Go | Key generation/management needs Go for full compatibility |

**Alternative:** Use the **Proton Bridge** for Mail (handles all PGP transparently)
and only need SRP auth for token acquisition, then pass-cli/rclone for the
other products which handle their own crypto.

### 7.5 Error Code Reference

| Code | Meaning | Action |
|------|---------|--------|
| 8002 | Wrong password | Re-prompt user |
| 9001 | Human verification required | Forward to HV handler |
| 10002 | Account deleted | Notify user |
| 10003 | Account disabled | Notify user |
| 10013 | Invalid refresh token | Full re-login required |
| 12087 | 2FA code invalid | Re-prompt TOTP |

---

## 8. Key Risks & Open Questions

### Risks

1. **SRP implementation correctness** — The protocol is unforgiving. One wrong
   byte order (little-endian vs big-endian in the hash) produces a silent auth
   failure. Must match Proton's exact implementation.

2. **Refresh token single-use** — The server invalidates the old `RefreshToken`
   on each `/auth/refresh`. If two parallel requests try to refresh with the
   same token, one will get `10013` (invalid). The go-proton-api handles this
   with a mutex; the plugin must also serialize refresh attempts.

3. **Token expiry race** — Token lifetime is server-controlled (ExpiresAt).
   If the clock skew is too large, a token might appear valid on the client
   but rejected by the server. Always retry on 401 with refresh.

4. **2FA during re-auth** — Hydroxide explicitly doesn't support this. If a
   server-side policy change triggers 2FA re-verification during refresh,
   the session is dead.

5. **Key unlocking cost** — Unlocking 10+ address keys with bcrypt iterations
   is CPU-intensive (seconds). Cache aggressively, unlock lazily.

### Open Questions for Hannibal (T1)

- Should the auth plugin use **Hydroxide's** NaCl secretbox or **Fernet** for
  token storage? (NaCl is what Proton-adjacent tools use, Fernet is simpler)
- Python SRP: use `srp._pysrp` from the abandoned Python client (it works,
  just unmaintained) or re-implement from go-srp spec?
- Key ring: subprocess a small Go binary for gopenpgp, or use PGPy with
  Proton's fork of go-crypto?
- Single-password vs two-password mode detection and handling?

---

## Sources

| Repository | File | Key Information |
|-----------|------|----------------|
| ProtonMail/go-proton-api | `manager_auth.go` | `NewClientWithLogin()` — full SRP login flow |
| ProtonMail/go-proton-api | `client.go` | Auto-refresh on 401, deauth handlers |
| ProtonMail/go-proton-api | `auth.go` | 2FA, session management endpoints |
| ProtonMail/go-proton-api | `keys.go`, `keyring.go` | Key management, unlock chain |
| ProtonMail/go-proton-api | `keys_types.go` | PublicKey/KeyList types |
| ProtonMail/go-proton-api | `message_encrypt.go` | PGP/MIME encryption |
| ProtonMail/go-srp | `srp.go` | SRP protocol implementation, modulus verification |
| ProtonMail/go-srp | `hash.go` | Password hashing (versions 0-4), expandHash |
| ProtonMail/gopenpgp v2 | `crypto/key.go` | Key operations (lock, unlock, export) |
| ProtonMail/gopenpgp v2 | README | API overview for crypto operations |
| emersion/hydroxide | `auth/auth.go` | Auth caching, NaCl secretbox storage |
| emersion/hydroxide | `protonmail/auth.go` | AuthInfo, Auth, AuthTOTP, AuthRefresh, Unlock |
| ProtonMail/proton-python-client | `proton/srp/_pysrp.py` | Python SRP-6a implementation |
| ProtonMail/proton-python-client | `proton/api.py` | Session management in Python |