auth

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Unlicense Imports: 20 Imported by: 0

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

View Source
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

func FetchKeyData(ctx context.Context, api papi.API) (proton.User, []proton.Address, error)

FetchKeyData fetches the user and addresses concurrently. Addresses are sorted by their Order field (mirroring go-proton-api's GetAddresses).

func Login

func Login(ctx context.Context, prompter Prompter, cfg config.Config) (string, error)

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

func Logout(ctx context.Context) error

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

func UnlockKeys(ctx context.Context, store *config.SessionStore, api papi.API) (*Unlocked, error)

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`.

func (*Unlocked) PrimaryAddrKR

func (u *Unlocked) PrimaryAddrKR(addressID string) (*crypto.KeyRing, error)

PrimaryAddrKR returns the unlocked keyring for addressID, falling back to any unlocked address keyring; errors when none are unlocked at all.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址