chore(updater): move updater packages to pkg/updaters/<name>

pkg/updaters/protonvpn/api.go

@@ -0,0 +1,638 @@
+package protonvpn
+
+import (
+	"bytes"
+	"context"
+	crand "crypto/rand"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math/rand/v2"
+	"net/http"
+	"net/netip"
+	"slices"
+	"strings"
+
+	srp "github.com/ProtonMail/go-srp"
+)
+
+// apiClient is a minimal Proton v4 API client which can handle all the
+// oddities of Proton's authentication flow they want to keep hidden
+// from the public.
+type apiClient struct {
+	apiURLBase string
+	httpClient *http.Client
+	appVersion string
+	userAgent  string
+	generator  *rand.ChaCha8
+}
+
+// newAPIClient returns an [apiClient] with sane defaults matching Proton's
+// insane expectations.
+func newAPIClient(ctx context.Context, httpClient *http.Client) (client *apiClient, err error) {
+	var seed [32]byte
+	_, _ = crand.Read(seed[:])
+	generator := rand.NewChaCha8(seed)
+
+	// Pick a random user agent from this list. Because I'm not going to tell
+	// Proton shit on where all these funny requests are coming from, given their
+	// unhelpfulness in figuring out their authentication flow.
+	userAgents := [...]string{
+		"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:143.0) Gecko/20100101 Firefox/143.0",
+		"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:143.0) Gecko/20100101 Firefox/143.0",
+		"Mozilla/5.0 (X11; Linux x86_64; rv:143.0) Gecko/20100101 Firefox/143.0",
+	}
+	userAgent := userAgents[generator.Uint64()%uint64(len(userAgents))]
+
+	appVersion, err := getMostRecentStableTag(ctx, httpClient)
+	if err != nil {
+		return nil, fmt.Errorf("getting most recent version for proton app: %w", err)
+	}
+
+	return &apiClient{
+		apiURLBase: "https://account.proton.me/api",
+		httpClient: httpClient,
+		appVersion: appVersion,
+		userAgent:  userAgent,
+		generator:  generator,
+	}, nil
+}
+
+var ErrCodeNotSuccess = errors.New("response code is not success")
+
+// setHeaders sets the minimal necessary headers for Proton API requests
+// to succeed without being blocked by their "security" measures.
+// See for example [getMostRecentStableTag] on how the app version must
+// be set to a recent version or they block your request. "SeCuRiTy"...
+func (c *apiClient) setHeaders(request *http.Request, cookie cookie) {
+	request.Header.Set("Cookie", cookie.String())
+	request.Header.Set("User-Agent", c.userAgent)
+	request.Header.Set("x-pm-appversion", c.appVersion)
+	request.Header.Set("x-pm-locale", "en_US")
+	request.Header.Set("x-pm-uid", cookie.uid)
+}
+
+// authenticate performs the full Proton authentication flow
+// to obtain an authenticated cookie (uid, token and session ID).
+func (c *apiClient) authenticate(ctx context.Context, email, password string,
+) (authCookie cookie, err error) {
+	sessionID, err := c.getSessionID(ctx)
+	if err != nil {
+		return cookie{}, fmt.Errorf("getting session ID: %w", err)
+	}
+
+	tokenType, accessToken, refreshToken, uid, err := c.getUnauthSession(ctx, sessionID)
+	if err != nil {
+		return cookie{}, fmt.Errorf("getting unauthenticated session data: %w", err)
+	}
+
+	cookieToken, err := c.cookieToken(ctx, sessionID, tokenType, accessToken, refreshToken, uid)
+	if err != nil {
+		return cookie{}, fmt.Errorf("getting cookie token: %w", err)
+	}
+
+	unauthCookie := cookie{
+		uid:       uid,
+		token:     cookieToken,
+		sessionID: sessionID,
+	}
+	username, modulusPGPClearSigned, serverEphemeralBase64, saltBase64,
+		srpSessionHex, version, err := c.authInfo(ctx, email, unauthCookie)
+	if err != nil {
+		return cookie{}, fmt.Errorf("getting auth information: %w", err)
+	}
+
+	// Prepare SRP proof generator using Proton's official SRP parameters and hashing.
+	srpAuth, err := srp.NewAuth(version, username, []byte(password),
+		saltBase64, modulusPGPClearSigned, serverEphemeralBase64)
+	if err != nil {
+		return cookie{}, fmt.Errorf("initializing SRP auth: %w", err)
+	}
+
+	// Generate SRP proofs (A, M1) with the usual 2048-bit modulus.
+	const modulusBits = 2048
+	proofs, err := srpAuth.GenerateProofs(modulusBits)
+	if err != nil {
+		return cookie{}, fmt.Errorf("generating SRP proofs: %w", err)
+	}
+
+	authCookie, err = c.auth(ctx, unauthCookie, email, srpSessionHex, proofs)
+	if err != nil {
+		return cookie{}, fmt.Errorf("authentifying: %w", err)
+	}
+
+	return authCookie, nil
+}
+
+var ErrSessionIDNotFound = errors.New("session ID not found in cookies")
+
+func (c *apiClient) getSessionID(ctx context.Context) (sessionID string, err error) {
+	const url = "https://account.proton.me/vpn"
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return "", fmt.Errorf("creating request: %w", err)
+	}
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return "", err
+	}
+	err = response.Body.Close()
+	if err != nil {
+		return "", fmt.Errorf("closing response body: %w", err)
+	}
+
+	for _, cookie := range response.Cookies() {
+		if cookie.Name == "Session-Id" {
+			return cookie.Value, nil
+		}
+	}
+
+	return "", fmt.Errorf("%w", ErrSessionIDNotFound)
+}
+
+var ErrDataFieldMissing = errors.New("data field missing in response")
+
+func (c *apiClient) getUnauthSession(ctx context.Context, sessionID string) (
+	tokenType, accessToken, refreshToken, uid string, err error,
+) {
+	request, err := http.NewRequestWithContext(ctx, http.MethodPost, c.apiURLBase+"/auth/v4/sessions", nil)
+	if err != nil {
+		return "", "", "", "", fmt.Errorf("creating request: %w", err)
+	}
+	unauthCookie := cookie{
+		sessionID: sessionID,
+	}
+	c.setHeaders(request, unauthCookie)
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return "", "", "", "", err
+	}
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	if err != nil {
+		return "", "", "", "", fmt.Errorf("reading response body: %w", err)
+	} else if response.StatusCode != http.StatusOK {
+		return "", "", "", "", buildError(response.StatusCode, responseBody)
+	}
+
+	var data struct {
+		Code         uint     `json:"Code"`         // 1000 on success
+		AccessToken  string   `json:"AccessToken"`  // 32-chars lowercase and digits
+		RefreshToken string   `json:"RefreshToken"` // 32-chars lowercase and digits
+		TokenType    string   `json:"TokenType"`    // "Bearer"
+		Scopes       []string `json:"Scopes"`       // should be [] for our usage
+		UID          string   `json:"UID"`          // 32-chars lowercase and digits
+		LocalID      uint     `json:"LocalID"`      // 0 in my case
+	}
+
+	err = json.Unmarshal(responseBody, &data)
+	if err != nil {
+		return "", "", "", "", fmt.Errorf("decoding response body: %w", err)
+	}
+
+	const successCode = 1000
+	switch {
+	case data.Code != successCode:
+		return "", "", "", "", fmt.Errorf("%w: expected %d got %d",
+			ErrCodeNotSuccess, successCode, data.Code)
+	case data.AccessToken == "":
+		return "", "", "", "", fmt.Errorf("%w: access token is empty", ErrDataFieldMissing)
+	case data.RefreshToken == "":
+		return "", "", "", "", fmt.Errorf("%w: refresh token is empty", ErrDataFieldMissing)
+	case data.TokenType == "":
+		return "", "", "", "", fmt.Errorf("%w: token type is empty", ErrDataFieldMissing)
+	case data.UID == "":
+		return "", "", "", "", fmt.Errorf("%w: UID is empty", ErrDataFieldMissing)
+	}
+	// Ignore Scopes and LocalID fields, we don't use them.
+
+	return data.TokenType, data.AccessToken, data.RefreshToken, data.UID, nil
+}
+
+var ErrUIDMismatch = errors.New("UID in response does not match request UID")
+
+func (c *apiClient) cookieToken(ctx context.Context, sessionID, tokenType, accessToken,
+	refreshToken, uid string,
+) (cookieToken string, err error) {
+	type requestBodySchema struct {
+		GrantType    string `json:"GrantType"`    // "refresh_token"
+		Persistent   uint   `json:"Persistent"`   // 0
+		RedirectURI  string `json:"RedirectURI"`  // "https://protonmail.com"
+		RefreshToken string `json:"RefreshToken"` // 32-chars lowercase and digits
+		ResponseType string `json:"ResponseType"` // "token"
+		State        string `json:"State"`        // 24-chars letters and digits
+		UID          string `json:"UID"`          // 32-chars lowercase and digits
+	}
+	requestBody := requestBodySchema{
+		GrantType:    "refresh_token",
+		Persistent:   0,
+		RedirectURI:  "https://protonmail.com",
+		RefreshToken: refreshToken,
+		ResponseType: "token",
+		State:        generateLettersDigits(c.generator, 24), //nolint:mnd
+		UID:          uid,
+	}
+
+	buffer := bytes.NewBuffer(nil)
+	encoder := json.NewEncoder(buffer)
+	if err := encoder.Encode(requestBody); err != nil {
+		return "", fmt.Errorf("encoding request body: %w", err)
+	}
+
+	request, err := http.NewRequestWithContext(ctx, http.MethodPost, c.apiURLBase+"/core/v4/auth/cookies", buffer)
+	if err != nil {
+		return "", fmt.Errorf("creating request: %w", err)
+	}
+	unauthCookie := cookie{
+		uid:       uid,
+		sessionID: sessionID,
+	}
+	c.setHeaders(request, unauthCookie)
+	request.Header.Set("Authorization", tokenType+" "+accessToken)
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return "", err
+	}
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	if err != nil {
+		return "", fmt.Errorf("reading response body: %w", err)
+	} else if response.StatusCode != http.StatusOK {
+		return "", buildError(response.StatusCode, responseBody)
+	}
+
+	var cookies struct {
+		Code           uint   `json:"Code"`           // 1000 on success
+		UID            string `json:"UID"`            // should match request UID
+		LocalID        uint   `json:"LocalID"`        // 0
+		RefreshCounter uint   `json:"RefreshCounter"` // 1
+	}
+	err = json.Unmarshal(responseBody, &cookies)
+	if err != nil {
+		return "", fmt.Errorf("decoding response body: %w", err)
+	}
+
+	const successCode = 1000
+	switch {
+	case cookies.Code != successCode:
+		return "", fmt.Errorf("%w: expected %d got %d",
+			ErrCodeNotSuccess, successCode, cookies.Code)
+	case cookies.UID != requestBody.UID:
+		return "", fmt.Errorf("%w: expected %s got %s",
+			ErrUIDMismatch, requestBody.UID, cookies.UID)
+	}
+	// Ignore LocalID and RefreshCounter fields, we don't use them.
+
+	for _, cookie := range response.Cookies() {
+		if cookie.Name == "AUTH-"+uid {
+			return cookie.Value, nil
+		}
+	}
+
+	return "", fmt.Errorf("%w", ErrAuthCookieNotFound)
+}
+
+var ErrUsernameDoesNotExist = errors.New("username does not exist")
+
+// authInfo fetches SRP parameters for the account.
+func (c *apiClient) authInfo(ctx context.Context, email string, unauthCookie cookie) (
+	username, modulusPGPClearSigned, serverEphemeralBase64, saltBase64, srpSessionHex string,
+	version int, err error,
+) {
+	type requestBodySchema struct {
+		Intent   string `json:"Intent"` // "Proton"
+		Username string `json:"Username"`
+	}
+	requestBody := requestBodySchema{
+		Intent:   "Proton",
+		Username: email,
+	}
+
+	buffer := bytes.NewBuffer(nil)
+	encoder := json.NewEncoder(buffer)
+	if err := encoder.Encode(requestBody); err != nil {
+		return "", "", "", "", "", 0, fmt.Errorf("encoding request body: %w", err)
+	}
+
+	request, err := http.NewRequestWithContext(ctx, http.MethodPost, c.apiURLBase+"/core/v4/auth/info", buffer)
+	if err != nil {
+		return "", "", "", "", "", 0, fmt.Errorf("creating request: %w", err)
+	}
+	c.setHeaders(request, unauthCookie)
+	request.Header.Set("Content-Type", "application/json")
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return "", "", "", "", "", 0, err
+	}
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	if err != nil {
+		return "", "", "", "", "", 0, fmt.Errorf("reading response body: %w", err)
+	} else if response.StatusCode != http.StatusOK {
+		return "", "", "", "", "", 0, buildError(response.StatusCode, responseBody)
+	}
+
+	var info struct {
+		Code            uint   `json:"Code"`              // 1000 on success
+		Modulus         string `json:"Modulus"`           // PGP clearsigned modulus string
+		ServerEphemeral string `json:"ServerEphemeral"`   // base64
+		Version         *uint  `json:"Version,omitempty"` // 4 as of 2025-10-26
+		Salt            string `json:"Salt"`              // base64
+		SRPSession      string `json:"SRPSession"`        // hexadecimal
+		Username        string `json:"Username"`          // user without @domain.com. Mine has its first letter capitalized.
+	}
+	err = json.Unmarshal(responseBody, &info)
+	if err != nil {
+		return "", "", "", "", "", 0, fmt.Errorf("decoding response body: %w", err)
+	}
+
+	const successCode = 1000
+	switch {
+	case info.Code != successCode:
+		return "", "", "", "", "", 0, fmt.Errorf("%w: expected %d got %d",
+			ErrCodeNotSuccess, successCode, info.Code)
+	case info.Modulus == "":
+		return "", "", "", "", "", 0, fmt.Errorf("%w: modulus is empty", ErrDataFieldMissing)
+	case info.ServerEphemeral == "":
+		return "", "", "", "", "", 0, fmt.Errorf("%w: server ephemeral is empty", ErrDataFieldMissing)
+	case info.Salt == "":
+		return "", "", "", "", "", 0, fmt.Errorf("%w (salt data field is empty)", ErrUsernameDoesNotExist)
+	case info.SRPSession == "":
+		return "", "", "", "", "", 0, fmt.Errorf("%w: SRP session is empty", ErrDataFieldMissing)
+	case info.Username == "":
+		return "", "", "", "", "", 0, fmt.Errorf("%w: username is empty", ErrDataFieldMissing)
+	case info.Version == nil:
+		return "", "", "", "", "", 0, fmt.Errorf("%w: version is missing", ErrDataFieldMissing)
+	}
+
+	version = int(*info.Version) //nolint:gosec
+	return info.Username, info.Modulus, info.ServerEphemeral, info.Salt,
+		info.SRPSession, version, nil
+}
+
+type cookie struct {
+	uid       string
+	token     string
+	sessionID string
+}
+
+func (c *cookie) String() string {
+	s := ""
+	if c.token != "" {
+		s += fmt.Sprintf("AUTH-%s=%s; ", c.uid, c.token)
+	}
+	if c.sessionID != "" {
+		s += fmt.Sprintf("Session-Id=%s; ", c.sessionID)
+	}
+	if c.token != "" {
+		s += "Tag=default; iaas=W10; Domain=proton.me; Feature=VPNDashboard:A"
+	}
+	return s
+}
+
+var (
+	// ErrServerProofNotValid indicates the M2 from the server didn't match the expected proof.
+	ErrServerProofNotValid = errors.New("server proof from server is not valid")
+	ErrVPNScopeNotFound    = errors.New("VPN scope not found in scopes")
+	ErrTwoFANotSupported   = errors.New("two factor authentication not supported in this client")
+	ErrAuthCookieNotFound  = errors.New("auth cookie not found")
+)
+
+// auth performs the SRP proof submission (and optionally TOTP) to obtain tokens.
+func (c *apiClient) auth(ctx context.Context, unauthCookie cookie,
+	username, srpSession string, proofs *srp.Proofs,
+) (authCookie cookie, err error) {
+	clientEphemeral := base64.StdEncoding.EncodeToString(proofs.ClientEphemeral)
+	clientProof := base64.StdEncoding.EncodeToString(proofs.ClientProof)
+
+	type requestBodySchema struct {
+		ClientEphemeral string            `json:"ClientEphemeral"`   // base64(A)
+		ClientProof     string            `json:"ClientProof"`       // base64(M1)
+		Payload         map[string]string `json:"Payload,omitempty"` // not sure
+		SRPSession      string            `json:"SRPSession"`        // hexadecimal
+		Username        string            `json:"Username"`          // user@protonmail.com
+	}
+	requestBody := requestBodySchema{
+		ClientEphemeral: clientEphemeral,
+		ClientProof:     clientProof,
+		SRPSession:      srpSession,
+		Username:        username,
+	}
+
+	buffer := bytes.NewBuffer(nil)
+	encoder := json.NewEncoder(buffer)
+	if err := encoder.Encode(requestBody); err != nil {
+		return cookie{}, fmt.Errorf("encoding request body: %w", err)
+	}
+
+	request, err := http.NewRequestWithContext(ctx, http.MethodPost, c.apiURLBase+"/core/v4/auth", buffer)
+	if err != nil {
+		return cookie{}, fmt.Errorf("creating request: %w", err)
+	}
+	c.setHeaders(request, unauthCookie)
+	request.Header.Set("Content-Type", "application/json")
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return cookie{}, err
+	}
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	if err != nil {
+		return cookie{}, fmt.Errorf("reading response body: %w", err)
+	} else if response.StatusCode != http.StatusOK {
+		return cookie{}, buildError(response.StatusCode, responseBody)
+	}
+
+	type twoFAStatus uint
+	//nolint:unused
+	const (
+		twoFADisabled twoFAStatus = iota
+		twoFAHasTOTP
+		twoFAHasFIDO2
+		twoFAHasFIDO2AndTOTP
+	)
+	type twoFAInfo struct {
+		Enabled twoFAStatus `json:"Enabled"`
+		FIDO2   struct {
+			AuthenticationOptions any   `json:"AuthenticationOptions"`
+			RegisteredKeys        []any `json:"RegisteredKeys"`
+		} `json:"FIDO2"`
+		TOTP uint `json:"TOTP"`
+	}
+
+	var auth struct {
+		Code              uint      `json:"Code"`         // 1000 on success
+		LocalID           uint      `json:"LocalID"`      // 7 in my case
+		Scopes            []string  `json:"Scopes"`       // this should contain "vpn". Same as `Scope` field value.
+		UID               string    `json:"UID"`          // same as `Uid` field value
+		UserID            string    `json:"UserID"`       // base64
+		EventID           string    `json:"EventID"`      // base64
+		PasswordMode      uint      `json:"PasswordMode"` // 1 in my case
+		ServerProof       string    `json:"ServerProof"`  // base64(M2)
+		TwoFactor         uint      `json:"TwoFactor"`    // 0 if 2FA not required
+		TwoFA             twoFAInfo `json:"2FA"`
+		TemporaryPassword uint      `json:"TemporaryPassword"` // 0 in my case
+	}
+
+	err = json.Unmarshal(responseBody, &auth)
+	if err != nil {
+		return cookie{}, fmt.Errorf("decoding response body: %w", err)
+	}
+
+	m2, err := base64.StdEncoding.DecodeString(auth.ServerProof)
+	if err != nil {
+		return cookie{}, fmt.Errorf("decoding server proof: %w", err)
+	}
+	if !bytes.Equal(m2, proofs.ExpectedServerProof) {
+		return cookie{}, fmt.Errorf("%w: expected %x got %x",
+			ErrServerProofNotValid, proofs.ExpectedServerProof, m2)
+	}
+
+	const successCode = 1000
+	switch {
+	case auth.Code != successCode:
+		return cookie{}, fmt.Errorf("%w: expected %d got %d",
+			ErrCodeNotSuccess, successCode, auth.Code)
+	case auth.UID != unauthCookie.uid:
+		return cookie{}, fmt.Errorf("%w: expected %s got %s",
+			ErrUIDMismatch, unauthCookie.uid, auth.UID)
+	case auth.TwoFactor != 0:
+		return cookie{}, fmt.Errorf("%w", ErrTwoFANotSupported)
+	case !slices.Contains(auth.Scopes, "vpn"):
+		return cookie{}, fmt.Errorf("%w: in %v", ErrVPNScopeNotFound, auth.Scopes)
+	}
+
+	for _, setCookieHeader := range response.Header.Values("Set-Cookie") {
+		parts := strings.Split(setCookieHeader, ";")
+		for _, part := range parts {
+			if strings.HasPrefix(part, "AUTH-"+unauthCookie.uid+"=") {
+				authCookie = unauthCookie
+				authCookie.token = strings.TrimPrefix(part, "AUTH-"+unauthCookie.uid+"=")
+				return authCookie, nil
+			}
+		}
+	}
+
+	return cookie{}, fmt.Errorf("%w: in HTTP headers %s",
+		ErrAuthCookieNotFound, httpHeadersToString(response.Header))
+}
+
+// generateLettersDigits mimicing Proton's own random string generator:
+// https://github.com/ProtonMail/WebClients/blob/e4d7e4ab9babe15b79a131960185f9f8275512cd/packages/utils/generateLettersDigits.ts
+func generateLettersDigits(rng *rand.ChaCha8, length uint) string {
+	const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+	return generateFromCharset(rng, length, charset)
+}
+
+func generateFromCharset(rng *rand.ChaCha8, length uint, charset string) string {
+	result := make([]byte, length)
+	randomBytes := make([]byte, length)
+	_, _ = rng.Read(randomBytes)
+	for i := range length {
+		result[i] = charset[int(randomBytes[i])%len(charset)]
+	}
+	return string(result)
+}
+
+func httpHeadersToString(headers http.Header) string {
+	var builder strings.Builder
+	first := true
+	for key, values := range headers {
+		for _, value := range values {
+			if !first {
+				builder.WriteString(", ")
+			}
+			builder.WriteString(fmt.Sprintf("%s: %s", key, value))
+			first = false
+		}
+	}
+	return builder.String()
+}
+
+type apiData struct {
+	LogicalServers []logicalServer `json:"LogicalServers"`
+}
+
+type logicalServer struct {
+	Name        string           `json:"Name"`
+	ExitCountry string           `json:"ExitCountry"`
+	Region      *string          `json:"Region"`
+	City        *string          `json:"City"`
+	Servers     []physicalServer `json:"Servers"`
+	Features    uint16           `json:"Features"`
+	Tier        *uint8           `json:"Tier,omitempty"`
+}
+
+type physicalServer struct {
+	EntryIP         netip.Addr `json:"EntryIP"`
+	ExitIP          netip.Addr `json:"ExitIP"`
+	Domain          string     `json:"Domain"`
+	Status          uint8      `json:"Status"`
+	X25519PublicKey string     `json:"X25519PublicKey"`
+}
+
+func (c *apiClient) fetchServers(ctx context.Context, cookie cookie) (
+	data apiData, err error,
+) {
+	const url = "https://account.proton.me/api/vpn/logicals"
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return data, err
+	}
+	c.setHeaders(request, cookie)
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return data, err
+	}
+	defer response.Body.Close()
+
+	if response.StatusCode != http.StatusOK {
+		b, _ := io.ReadAll(response.Body)
+		return data, buildError(response.StatusCode, b)
+	}
+
+	decoder := json.NewDecoder(response.Body)
+	if err := decoder.Decode(&data); err != nil {
+		return data, fmt.Errorf("decoding response body: %w", err)
+	}
+
+	return data, nil
+}
+
+var ErrHTTPStatusCodeNotOK = errors.New("HTTP status code not OK")
+
+func buildError(httpCode int, body []byte) error {
+	prettyCode := http.StatusText(httpCode)
+	var protonError struct {
+		Code    *int              `json:"Code,omitempty"`
+		Error   *string           `json:"Error,omitempty"`
+		Details map[string]string `json:"Details"`
+	}
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.DisallowUnknownFields()
+	err := decoder.Decode(&protonError)
+	if err != nil || protonError.Error == nil || protonError.Code == nil {
+		return fmt.Errorf("%w: %s: %s",
+			ErrHTTPStatusCodeNotOK, prettyCode, body)
+	}
+
+	details := make([]string, 0, len(protonError.Details))
+	for key, value := range protonError.Details {
+		details = append(details, fmt.Sprintf("%s: %s", key, value))
+	}
+
+	return fmt.Errorf("%w: %s: %s (code %d with details: %s)",
+		ErrHTTPStatusCodeNotOK, prettyCode, *protonError.Error, *protonError.Code, strings.Join(details, ", "))
+}

pkg/updaters/protonvpn/countries.go

@@ -0,0 +1,15 @@
+package protonvpn
+
+import "strings"
+
+func codeToCountry(countryCode string, countryCodes map[string]string) (
+	country string, warning string,
+) {
+	countryCode = strings.ToLower(countryCode)
+	country, ok := countryCodes[countryCode]
+	if !ok {
+		warning = "unknown country code: " + countryCode
+		country = countryCode
+	}
+	return country, warning
+}

pkg/updaters/protonvpn/iptoserver.go

@@ -0,0 +1,66 @@
+package protonvpn
+
+import (
+	"net/netip"
+
+	"github.com/qdm12/gluetun/internal/constants/vpn"
+	"github.com/qdm12/gluetun/internal/models"
+)
+
+type ipToServers map[string][2]models.Server // first server is OpenVPN, second is Wireguard.
+
+type features struct {
+	secureCore bool
+	tor        bool
+	p2p        bool
+	stream     bool
+}
+
+func (its ipToServers) add(country, region, city, name, hostname, wgPubKey string,
+	free bool, entryIP netip.Addr, features features,
+) {
+	key := entryIP.String()
+
+	servers, ok := its[key]
+	if ok {
+		return
+	}
+
+	baseServer := models.Server{
+		Country:     country,
+		Region:      region,
+		City:        city,
+		ServerName:  name,
+		Hostname:    hostname,
+		Free:        free,
+		SecureCore:  features.secureCore,
+		Tor:         features.tor,
+		PortForward: features.p2p,
+		Stream:      features.stream,
+		IPs:         []netip.Addr{entryIP},
+	}
+	openvpnServer := baseServer
+	openvpnServer.VPN = vpn.OpenVPN
+	openvpnServer.UDP = true
+	openvpnServer.TCP = true
+	servers[0] = openvpnServer
+	wireguardServer := baseServer
+	wireguardServer.VPN = vpn.Wireguard
+	wireguardServer.WgPubKey = wgPubKey
+	servers[1] = wireguardServer
+	its[key] = servers
+}
+
+func (its ipToServers) toServersSlice() (serversSlice []models.Server) {
+	const vpnProtocols = 2
+	serversSlice = make([]models.Server, 0, vpnProtocols*len(its))
+	for _, servers := range its {
+		serversSlice = append(serversSlice, servers[0], servers[1])
+	}
+	return serversSlice
+}
+
+func (its ipToServers) numberOfServers() int {
+	const serversPerIP = 2
+	return len(its) * serversPerIP
+}

pkg/updaters/protonvpn/servers.go

@@ -0,0 +1,117 @@
+package protonvpn
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"github.com/qdm12/gluetun/internal/constants"
+	"github.com/qdm12/gluetun/internal/models"
+	"github.com/qdm12/gluetun/internal/provider/common"
+)
+
+func (u *Updater) FetchServers(ctx context.Context, minServers int) (
+	servers []models.Server, err error,
+) {
+	switch {
+	case u.email == "":
+		return nil, fmt.Errorf("%w: email is empty", common.ErrCredentialsMissing)
+	case u.password == "":
+		return nil, fmt.Errorf("%w: password is empty", common.ErrCredentialsMissing)
+	}
+
+	apiClient, err := newAPIClient(ctx, u.client)
+	if err != nil {
+		return nil, fmt.Errorf("creating API client: %w", err)
+	}
+
+	cookie, err := apiClient.authenticate(ctx, u.email, u.password)
+	if err != nil {
+		return nil, fmt.Errorf("authentifying with Proton: %w", err)
+	}
+
+	data, err := apiClient.fetchServers(ctx, cookie)
+	if err != nil {
+		return nil, fmt.Errorf("fetching logical servers: %w", err)
+	}
+
+	countryCodes := constants.CountryCodes()
+
+	var count int
+	for _, logicalServer := range data.LogicalServers {
+		count += len(logicalServer.Servers)
+	}
+
+	if count < minServers {
+		return nil, fmt.Errorf("%w: %d and expected at least %d",
+			common.ErrNotEnoughServers, count, minServers)
+	}
+
+	ipToServer := make(ipToServers, count)
+	for _, logicalServer := range data.LogicalServers {
+		region := getStringValue(logicalServer.Region)
+		city := getStringValue(logicalServer.City)
+		// TODO v4 remove `name` field because of
+		// https://github.com/qdm12/gluetun/issues/1018#issuecomment-1151750179
+		name := logicalServer.Name
+
+		//nolint:lll
+		// See https://github.com/ProtonVPN/protonvpn-nm-lib/blob/31d5f99fbc89274e4e977a11e7432c0eab5a3ef8/protonvpn_nm_lib/enums.py#L44-L49
+		featuresBits := logicalServer.Features
+		features := features{
+			secureCore: featuresBits&1 != 0,
+			tor:        featuresBits&2 != 0,
+			p2p:        featuresBits&4 != 0,
+			stream:     featuresBits&8 != 0,
+			// ipv6: featuresBits&16 != 0, - unused.
+		}
+
+		//nolint:lll
+		// See https://github.com/ProtonVPN/protonvpn-nm-lib/blob/31d5f99fbc89274e4e977a11e7432c0eab5a3ef8/protonvpn_nm_lib/enums.py#L56-L62
+		free := false
+		if logicalServer.Tier == nil {
+			u.warner.Warn("tier field not set for server " + logicalServer.Name)
+		} else if *logicalServer.Tier == 0 {
+			free = true
+		}
+
+		for _, physicalServer := range logicalServer.Servers {
+			if physicalServer.Status == 0 { // disabled so skip server
+				u.warner.Warn("ignoring server " + physicalServer.Domain + " with status 0")
+				continue
+			}
+
+			hostname := physicalServer.Domain
+			entryIP := physicalServer.EntryIP
+			wgPubKey := physicalServer.X25519PublicKey
+
+			// Note: for multi-hop use the server name or hostname
+			// instead of the country
+			countryCode := logicalServer.ExitCountry
+			country, warning := codeToCountry(countryCode, countryCodes)
+			if warning != "" {
+				u.warner.Warn(warning)
+			}
+
+			ipToServer.add(country, region, city, name, hostname, wgPubKey, free, entryIP, features)
+		}
+	}
+
+	if ipToServer.numberOfServers() < minServers {
+		return nil, fmt.Errorf("%w: %d and expected at least %d",
+			common.ErrNotEnoughServers, len(ipToServer), minServers)
+	}
+
+	servers = ipToServer.toServersSlice()
+
+	sort.Sort(models.SortableServers(servers))
+
+	return servers, nil
+}
+
+func getStringValue(ptr *string) string {
+	if ptr == nil {
+		return ""
+	}
+	return *ptr
+}

pkg/updaters/protonvpn/updater.go

@@ -0,0 +1,27 @@
+package protonvpn
+
+import (
+	"net/http"
+
+	"github.com/qdm12/gluetun/internal/provider/common"
+)
+
+type Updater struct {
+	client   *http.Client
+	email    string
+	password string
+	warner   common.Warner
+}
+
+func New(client *http.Client, warner common.Warner, email, password string) *Updater {
+	return &Updater{
+		client:   client,
+		email:    email,
+		password: password,
+		warner:   warner,
+	}
+}
+
+func (u *Updater) Version() uint16 {
+	return 4 //nolint:mnd
+}

pkg/updaters/protonvpn/version.go

@@ -0,0 +1,71 @@
+package protonvpn
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// getMostRecentStableTag finds the most recent proton-account stable tag version,
+// in order to use it in the x-pm-appversion http request header. Because if we do
+// fall behind on versioning, Proton doesn't like it because they like to create
+// complications where there is no need for it. Hence this function.
+func getMostRecentStableTag(ctx context.Context, client *http.Client) (version string, err error) {
+	page := 1
+	regexVersion := regexp.MustCompile(`^proton-account@(\d+\.\d+\.\d+\.\d+)$`)
+	for ctx.Err() == nil {
+		// Define a timeout since the default client has a large timeout and we don't
+		// want to wait too long.
+		const timeout = 5 * time.Second
+		ctx, cancel := context.WithTimeout(ctx, timeout)
+		defer cancel()
+
+		url := "https://api.github.com/repos/ProtonMail/WebClients/tags?per_page=30&page=" + fmt.Sprint(page)
+
+		request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			return "", fmt.Errorf("creating request: %w", err)
+		}
+		request.Header.Set("Accept", "application/vnd.github.v3+json")
+
+		response, err := client.Do(request)
+		if err != nil {
+			return "", err
+		}
+		defer response.Body.Close()
+
+		data, err := io.ReadAll(response.Body)
+		if err != nil {
+			return "", fmt.Errorf("reading response body: %w", err)
+		}
+
+		if response.StatusCode != http.StatusOK {
+			return "", fmt.Errorf("%w: %s: %s", ErrHTTPStatusCodeNotOK, response.Status, data)
+		}
+
+		var tags []struct {
+			Name string `json:"name"`
+		}
+		err = json.Unmarshal(data, &tags)
+		if err != nil {
+			return "", fmt.Errorf("decoding JSON response: %w", err)
+		}
+
+		for _, tag := range tags {
+			if !regexVersion.MatchString(tag.Name) {
+				continue
+			}
+			version := "web-account@" + strings.TrimPrefix(tag.Name, "proton-account@")
+			return version, nil
+		}
+
+		page++
+	}
+
+	return "", fmt.Errorf("%w (queried %d pages)", context.Canceled, page)
+}