Documentation
¶
Overview ¶
Package auth implements the interactive Proton login flow, session teardown, and key unlocking for proton-cal.
Credential model (bridge-style): Login derives the salted key passphrase once (from the account/mailbox password and the primary key salt) and persists it in the session store alongside the session tokens. The account password itself is never persisted. Later commands restore the session and call UnlockKeys, which unlocks user/address keys from the stored salted passphrase without re-prompting.
Scope note (live-verified): GET /core/v4/keys/salts requires the elevated "locked" scope, which a freshly logged-in or restored session may lack (HTTP 403, Proton code 9101). Gaining it requires a full SRP proof to PUT /core/v4/users/unlock, which go-proton-api does not implement; see unlockScope. The scope is dropped again (PUT /core/v4/users/lock) as soon as the salts have been fetched; see docs/overview.md for the full unlock/lock dance.
Index ¶
- Constants
- func FetchKeyData(ctx context.Context, api papi.API) (proton.User, []proton.Address, error)
- func Login(ctx context.Context, prompter Prompter, cfg config.Config) (string, error)
- func Logout(ctx context.Context) error
- func WithLockedScope(ctx context.Context, m *proton.Manager, raw *papi.Client, ...) (err error)
- type Prompter
- type Unlocked
Constants ¶
const ( UsersPath = "/core/v4/users" AddressesPath = "/core/v4/addresses" )
UsersPath and AddressesPath are the key-material endpoints, fetched via the raw request path (so a caching papi.API decorator can serve them).
Variables ¶
This section is empty.
Functions ¶
func FetchKeyData ¶
FetchKeyData fetches the user and addresses concurrently. Addresses are sorted by their Order field (mirroring go-proton-api's GetAddresses).
func Login ¶
Login runs the interactive login flow and persists the session (tokens + salted key passphrase), returning the logged-in username for the caller to persist. Handles browser-based captcha and TOTP; FIDO2-only 2FA and email-code verification are unsupported.
func Logout ¶
Logout clears the local session and cache before best-effort API revocation. A missing session is not an error.
func WithLockedScope ¶
func WithLockedScope(ctx context.Context, m *proton.Manager, raw *papi.Client, username, password string, fn func() error) (err error)
WithLockedScope gains the "locked" scope using the login password, runs fn, then drops it. Cleanup is best effort except for session refresh failures.
Types ¶
type Prompter ¶
type Prompter interface {
// Prompt reads a line of visible input (username, TOTP code, confirmation).
// The returned string has the trailing newline removed.
Prompt(label string) (string, error)
// PromptSecret reads a line of hidden input (passwords).
PromptSecret(label string) (string, error)
// Notify shows a user-facing progress/instruction message (on stderr).
Notify(msg string)
}
Prompter abstracts interactive input so the login flow is testable.
func NewTerminalPrompter ¶
func NewTerminalPrompter() Prompter
NewTerminalPrompter returns a Prompter over stdin/stderr (hidden input via golang.org/x/term, with a visible fallback when stdin is not a terminal).
type Unlocked ¶
type Unlocked struct {
// User is the Proton user the session belongs to.
User proton.User
// Addresses are the user's addresses, in API order.
Addresses []proton.Address
// AddrKRs maps address ID to its unlocked keyring. Addresses whose keys
// could not be unlocked are absent.
AddrKRs map[string]*crypto.KeyRing
}
Unlocked holds unlocked key material for a session.
func UnlockKeys ¶
UnlockKeys restores key material using the stored salted key passphrase: fetches user/addresses via api and unlocks the keyrings. A session without a stored passphrase errors, directing the user to run `proton-cal login`.