feat(account): VK ID web login to link a VK identity from a browser

A browser has no signed VK Mini App launch params, so linking VK on the web uses VK ID's raw OAuth 2.1 flow (PKCE, no @vkid/sdk): the SPA redirects to VK's hosted login and returns with an authorization code, which the gateway exchanges server-side (confidential, under the VK "Web" app's protected key) for the trusted vk user id — then the existing link/merge machinery attaches or merges it. - fbs LinkVKRequest{code, device_id, code_verifier}; codec + TS bindings. - backend link.Service ConfirmVK/MergeVK/attachVK (KindVK, mirror Telegram), handleLinkVK[Merge], routes /user/link/vk[/merge], backendclient LinkVK[Merge]. - gateway internal/vkid confidential code exchange (id.vk.com/oauth2/auth); transcode link.vk.confirm/merge (registered only when configured) + config GATEWAY_VK_ID_{APP_ID,CLIENT_SECRET,REDIRECT_URL} + main wiring. - UI lib/vkid (PKCE authorize redirect + callback), Profile "Link VK" control, boot callback handling; a merge re-authorizes for a fresh code (VK codes are single-use). Web-only (a redirect strands a Mini App webview). - Deploy: VITE_VK_APP_ID + VITE_VK_ID_REDIRECT_URL build args + gateway env, ci.yaml/prod-deploy TEST_/PROD_ vars, compose/Dockerfile/.env.example/README. - Tests: vkid exchange unit (string/number user_id, id_token fallback, errors), transcode link.vk, backend ConfirmVK/MergeVK inttest, codec encodeLinkVK. - Docs: ARCHITECTURE §4, FUNCTIONAL(+ru), gateway README.
2026-07-03 17:59:33 +02:00
parent 60faa4f064
commit 2c465c01d2
36 changed files with 1131 additions and 16 deletions
@@ -0,0 +1,163 @@
+// Package vkid completes VK ID web authorization on the server. A browser linking a
+// VK identity has no signed Mini App launch parameters (that offline HMAC path is
+// vkauth); instead the frontend runs the VK ID raw OAuth 2.1 flow (PKCE) and hands the
+// gateway the authorization code, which the gateway exchanges — confidentially, under
+// the app's protected key — for the launching user's trusted VK id. Unlike the Mini App
+// path this makes an outbound call to VK (there is no offline verification for the web
+// flow). See docs/ARCHITECTURE.md §12.
+package vkid
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+const (
+	// tokenEndpoint is VK ID's OAuth 2.1 token endpoint. The frontend obtains the
+	// authorization code against the same host, so the confidential exchange targets it
+	// too. It is a fixed constant (not user input), so the outbound request carries no
+	// SSRF risk.
+	tokenEndpoint = "https://id.vk.com/oauth2/auth"
+	// exchangeTimeout bounds one code-for-token exchange. Linking is interactive, so an
+	// unreachable VK must fail fast rather than hold the request open.
+	exchangeTimeout = 10 * time.Second
+	// maxResponseBytes caps the token-response read to bound memory on an oversized body.
+	maxResponseBytes = 1 << 16
+)
+
+// ErrInvalid reports an authorization fault: the exchange was rejected or yielded no vk
+// user id (a bad or expired code, a mismatched verifier or redirect). It is distinct
+// from a transport failure reaching VK, which surfaces as a wrapped error.
+var ErrInvalid = errors.New("vkid: vk id authorization exchange failed")
+
+// Identity is the user resolved from a completed VK ID exchange. ExternalID is the vk
+// user id, used as the identities external_id.
+type Identity struct {
+	ExternalID string
+}
+
+// numericID accepts a VK user id that the token endpoint returns inconsistently as a
+// JSON string or a JSON number, normalising both to their decimal string form (empty
+// for a null or absent field).
+type numericID string
+
+func (n *numericID) UnmarshalJSON(b []byte) error {
+	s := strings.Trim(string(b), `"`)
+	if s == "null" {
+		s = ""
+	}
+	*n = numericID(s)
+	return nil
+}
+
+// Exchanger completes VK ID confidential authorization-code exchanges for one app.
+type Exchanger struct {
+	appID        string
+	clientSecret string
+	redirectURI  string
+	endpoint     string
+	httpClient   *http.Client
+}
+
+// New constructs an Exchanger for the app credentials. redirectURI must equal the
+// trusted redirect URL registered with the app and the one the frontend used, or VK
+// rejects the exchange.
+func New(appID, clientSecret, redirectURI string) *Exchanger {
+	return &Exchanger{
+		appID:        appID,
+		clientSecret: clientSecret,
+		redirectURI:  redirectURI,
+		endpoint:     tokenEndpoint,
+		httpClient:   &http.Client{Timeout: exchangeTimeout},
+	}
+}
+
+// Exchange completes the authorization-code grant and returns the trusted vk user id.
+// code, deviceID and codeVerifier are the PKCE inputs the frontend obtained from the VK
+// ID authorization redirect; the exchange authenticates with the app's protected key.
+func (e *Exchanger) Exchange(ctx context.Context, code, deviceID, codeVerifier string) (Identity, error) {
+	if code == "" || deviceID == "" || codeVerifier == "" {
+		return Identity{}, ErrInvalid
+	}
+	form := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"code_verifier": {codeVerifier},
+		"device_id":     {deviceID},
+		"client_id":     {e.appID},
+		"client_secret": {e.clientSecret},
+		"redirect_uri":  {e.redirectURI},
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, e.endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return Identity{}, fmt.Errorf("vkid: build exchange request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+	resp, err := e.httpClient.Do(req)
+	if err != nil {
+		return Identity{}, fmt.Errorf("vkid: exchange request: %w", err)
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes))
+	if err != nil {
+		return Identity{}, fmt.Errorf("vkid: read exchange response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		// VK answers 400 with {error, error_description} on a bad/expired code or a
+		// verifier/redirect mismatch — an authorization fault, not a transport error.
+		return Identity{}, ErrInvalid
+	}
+	var out struct {
+		UserID  numericID `json:"user_id"`
+		IDToken string    `json:"id_token"`
+		Error   string    `json:"error"`
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return Identity{}, ErrInvalid
+	}
+	if out.Error != "" {
+		return Identity{}, ErrInvalid
+	}
+	uid := string(out.UserID)
+	if uid == "" || uid == "0" {
+		uid = subjectFromIDToken(out.IDToken)
+	}
+	if uid == "" {
+		return Identity{}, ErrInvalid
+	}
+	return Identity{ExternalID: uid}, nil
+}
+
+// subjectFromIDToken extracts the OIDC subject (the vk user id) from the payload of a
+// VK ID id_token. The token arrives inside a direct TLS response from VK, so its
+// signature is not re-verified here; the claim is only a fallback for a response that
+// omits an explicit user_id.
+func subjectFromIDToken(idToken string) string {
+	parts := strings.Split(idToken, ".")
+	if len(parts) != 3 {
+		return ""
+	}
+	payload, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return ""
+	}
+	var claims struct {
+		Sub numericID `json:"sub"`
+	}
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		return ""
+	}
+	if s := string(claims.Sub); s != "0" {
+		return s
+	}
+	return ""
+}
@@ -0,0 +1,131 @@
+package vkid
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+)
+
+// testExchanger builds an Exchanger pointed at a test server.
+func testExchanger(endpoint string) *Exchanger {
+	return &Exchanger{
+		appID:        "app-1",
+		clientSecret: "secret-1",
+		redirectURI:  "https://example.test/app/",
+		endpoint:     endpoint,
+		httpClient:   &http.Client{},
+	}
+}
+
+func TestExchangeSuccessSendsConfidentialPKCE(t *testing.T) {
+	var gotForm url.Values
+	var gotContentType string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotContentType = r.Header.Get("Content-Type")
+		body, _ := io.ReadAll(r.Body)
+		gotForm, _ = url.ParseQuery(string(body))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"user_id":"12345","access_token":"a","id_token":"h.e.s"}`)
+	}))
+	defer srv.Close()
+
+	id, err := testExchanger(srv.URL).Exchange(context.Background(), "the-code", "dev-9", "verifier-xyz")
+	if err != nil {
+		t.Fatalf("Exchange: %v", err)
+	}
+	if id.ExternalID != "12345" {
+		t.Fatalf("ExternalID = %q, want 12345", id.ExternalID)
+	}
+	if gotContentType != "application/x-www-form-urlencoded" {
+		t.Errorf("Content-Type = %q", gotContentType)
+	}
+	// The confidential exchange must carry the PKCE inputs and the app credentials.
+	want := map[string]string{
+		"grant_type":    "authorization_code",
+		"code":          "the-code",
+		"code_verifier": "verifier-xyz",
+		"device_id":     "dev-9",
+		"client_id":     "app-1",
+		"client_secret": "secret-1",
+		"redirect_uri":  "https://example.test/app/",
+	}
+	for k, v := range want {
+		if gotForm.Get(k) != v {
+			t.Errorf("form[%s] = %q, want %q", k, gotForm.Get(k), v)
+		}
+	}
+}
+
+func TestExchangeAcceptsNumericUserID(t *testing.T) {
+	// VK returns user_id as a bare JSON number in some responses; it must parse too.
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.WriteString(w, `{"user_id":1234567890,"access_token":"a"}`)
+	}))
+	defer srv.Close()
+
+	id, err := testExchanger(srv.URL).Exchange(context.Background(), "c", "d", "v")
+	if err != nil {
+		t.Fatalf("Exchange: %v", err)
+	}
+	if id.ExternalID != "1234567890" {
+		t.Fatalf("ExternalID = %q, want 1234567890", id.ExternalID)
+	}
+}
+
+func TestExchangeFallsBackToIDTokenSub(t *testing.T) {
+	sub := "987654321"
+	payload := base64.RawURLEncoding.EncodeToString([]byte(`{"sub":"` + sub + `"}`))
+	idToken := "header." + payload + ".sig"
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.WriteString(w, `{"access_token":"a","id_token":"`+idToken+`"}`)
+	}))
+	defer srv.Close()
+
+	id, err := testExchanger(srv.URL).Exchange(context.Background(), "c", "d", "v")
+	if err != nil {
+		t.Fatalf("Exchange: %v", err)
+	}
+	if id.ExternalID != sub {
+		t.Fatalf("ExternalID = %q, want %q (from id_token sub)", id.ExternalID, sub)
+	}
+}
+
+func TestExchangeRejectedIsErrInvalid(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = io.WriteString(w, `{"error":"invalid_grant","error_description":"code expired"}`)
+	}))
+	defer srv.Close()
+
+	_, err := testExchanger(srv.URL).Exchange(context.Background(), "c", "d", "v")
+	if !errors.Is(err, ErrInvalid) {
+		t.Fatalf("err = %v, want ErrInvalid", err)
+	}
+}
+
+func TestExchangeEmptyInputsFailFast(t *testing.T) {
+	// Missing PKCE inputs are rejected without any network call.
+	ex := testExchanger("http://127.0.0.1:0/never")
+	for _, args := range [][3]string{{"", "d", "v"}, {"c", "", "v"}, {"c", "d", ""}} {
+		if _, err := ex.Exchange(context.Background(), args[0], args[1], args[2]); !errors.Is(err, ErrInvalid) {
+			t.Errorf("Exchange%v err = %v, want ErrInvalid", args, err)
+		}
+	}
+}
+
+func TestExchangeTransportErrorIsNotErrInvalid(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	srv.Close() // closed listener → connection refused
+	_, err := testExchanger(srv.URL).Exchange(context.Background(), "c", "d", "v")
+	if err == nil {
+		t.Fatal("want a transport error")
+	}
+	if errors.Is(err, ErrInvalid) {
+		t.Fatalf("transport error must not be ErrInvalid: %v", err)
+	}
+}