Merge pull request 'Separate second-factor verification and delivery from authentication' (#41) from twofactor-40 into main

Reviewed-on: #41

AGENTS.md

@@ -8,6 +8,20 @@
 - For cross-module work, apply every relevant scoped instruction file and
   completion workflow.
 
+## Autogenerated code
+
+- Never commit autogenerated code to the repository. This applies to backend,
+  frontend, shared packages, and every other module, including generated
+  protobuf bindings, API clients, serializers, and framework-generated code.
+- Commit the source definitions, generator configuration, and reproducible
+  generation commands instead. Generate code locally or during build and CI
+  workflows before any dependent validation or compilation steps.
+- Keep generated outputs ignored by Git. Do not force-add ignored generated
+  files or copy generated code into tracked source files.
+- Change the source definitions or generator inputs rather than editing
+  generated outputs. Document the generation workflow so a clean checkout can
+  build without committed generated code.
+
 ## Data and state architecture
 
 Preserve explicit **DTO → mapper → service → data model → provider → UI**

Makefile

@@ -5,6 +5,7 @@ test: test-backend test-frontend
 .PHONY: test-frontend
 
 test-frontend:
+	cd frontend/app && flutter gen-l10n
 	cd frontend/packages/sxchnge_wallet && flutter test
 	cd frontend/packages/sxchnge_kyc && flutter test
 	cd frontend/packages/sxchnge_analytics && flutter test

backend/PROVENANCE.md

@@ -71,3 +71,11 @@ code. Auth and verification configurations moved out of application interfaces.
 All 112 unconsumed public API snapshot files and their snapshot-only check were
 removed. Future public adapters will own just the wire types they consume.
 Backoffice is a separate future executable module, not an alias for product.
+
+## Second-factor separation (#40)
+
+The new `product/twofactor` domain service reuses the already copied
+`product/verification/store` issuance and consumption implementation at the pinned
+Sendico revision. No additional Sendico source files were copied. Coupled
+verification HTTP/session/private-messaging handlers were inspected but excluded.
+See [reuse decisions and domain boundary](../docs/architecture/two-factor.md).

backend/notifications/README.md

@@ -46,7 +46,8 @@ Multiple service workers can safely compete for jobs through atomic claims.
 
 ## Templates and parameters
 
-See `templates.example.json`. Parameters use Go template map syntax such as
+See `templates.example.json`, including the `auth.activation` and `auth.login`
+English/Russian templates used by [product authentication](../../docs/auth-notifications.md). Parameters use Go template map syntax such as
 `{{.first_name}}`. Each revision declares the exact allowed parameter names and
 locale-specific content. Missing/extra parameters, unknown revisions/locales and
 invalid content are rejected before acceptance. Empty locale uses the default.

backend/notifications/templates.example.json

@@ -3,7 +3,11 @@
     "id": "exchange.completed",
     "version": "1",
     "default_locale": "en",
-    "parameters": ["first_name", "amount", "currency"],
+    "parameters": [
+      "first_name",
+      "amount",
+      "currency"
+    ],
     "locales": {
       "en": {
         "subject": "Your exchange is complete",
@@ -11,5 +15,65 @@
         "text": "Hi {{.first_name}}, your exchange of {{.amount}} {{.currency}} is complete."
       }
     }
+  },
+  {
+    "id": "auth.activation",
+    "version": "1",
+    "default_locale": "en",
+    "parameters": [
+      "url"
+    ],
+    "locales": {
+      "en": {
+        "subject": "Verify your SXCHNGE email",
+        "text": "Confirm your email: {{.url}}\nThis link expires in 24 hours. If you did not sign up, ignore this email.",
+        "html": "<p>Confirm your email to finish signing up.</p><p><a href=\"{{.url}}\">Verify email</a></p><p>This link expires in 24 hours. If you did not sign up, ignore this email.</p>"
+      },
+      "ru": {
+        "subject": "Подтвердите почту SXCHNGE",
+        "text": "Подтвердите почту: {{.url}}\nСсылка действует 24 часа. Если вы не регистрировались, проигнорируйте письмо.",
+        "html": "<p><a href=\"{{.url}}\">Подтвердить почту</a></p><p>Ссылка действует 24 часа. Если вы не регистрировались, проигнорируйте письмо.</p>"
+      }
+    }
+  },
+  {
+    "id": "auth.login",
+    "version": "1",
+    "default_locale": "en",
+    "parameters": [
+      "code"
+    ],
+    "locales": {
+      "en": {
+        "subject": "Your SXCHNGE login code",
+        "text": "Your login code is {{.code}}. It expires in 10 minutes. Never share this code.",
+        "html": "<p>Your login code is <strong>{{.code}}</strong>.</p><p>It expires in 10 minutes. Never share this code.</p>"
+      },
+      "ru": {
+        "subject": "Код входа SXCHNGE",
+        "text": "Ваш код входа: {{.code}}. Он действует 10 минут. Никому не сообщайте код.",
+        "html": "<p>Ваш код входа: <strong>{{.code}}</strong>.</p><p>Он действует 10 минут. Никому не сообщайте код.</p>"
+      }
+    }
+  },
+  {
+    "id": "twofactor.code",
+    "version": "1",
+    "default_locale": "en",
+    "parameters": [
+      "code"
+    ],
+    "locales": {
+      "en": {
+        "subject": "Your SXCHNGE verification code",
+        "text": "Your verification code is {{.code}}. It expires in 10 minutes. Only enter it for the operation you requested. Never share this code.",
+        "html": "<p>Your verification code is <strong>{{.code}}</strong>.</p><p>It expires in 10 minutes. Only enter it for the operation you requested. Never share this code.</p>"
+      },
+      "ru": {
+        "subject": "Код подтверждения SXCHNGE",
+        "text": "Ваш код подтверждения: {{.code}}. Он действует 10 минут. Вводите его только для запрошенной вами операции. Никому не сообщайте код.",
+        "html": "<p>Ваш код подтверждения: <strong>{{.code}}</strong>.</p><p>Он действует 10 минут. Вводите его только для запрошенной вами операции. Никому не сообщайте код.</p>"
+      }
+    }
   }
 ]

backend/product/README.md

@@ -24,8 +24,11 @@ organization, role, policy or seed; the runtime creates its indexes.
 The runtime mounts health, login, API login, refresh, rotation and logout routes.
 Customer/application-client records must exist for login. The customer service
 supports atomic account/activation creation and deletion with session revocation.
-Signup/profile HTTP wiring and verification delivery/completion remain follow-up
-work. The frontend still uses dummy services.
+Signup and email verification delivery/completion are available when
+`api.notifications` is configured. Flutter selects the backend using
+`SXCHNGE_API_URL` and `SXCHNGE_CLIENT_ID`. See
+[auth notification setup and contracts](../../docs/auth-notifications.md).
+Profile HTTP wiring remains follow-up work.
 
 Sendico integration is not wired. Its organization context belongs only to the
 future public HTTP adapter. There is no unused public API snapshot in this module;

backend/product/app/api/config.go

@@ -2,13 +2,15 @@ package api
 
 import (
 	mwa "git.sendico.io/tech/sxchnge/product/auth/config"
+	"git.sendico.io/tech/sxchnge/product/notifications"
 	verificationconfig "git.sendico.io/tech/sxchnge/product/verification/config"
 )
 
 type Config struct {
-	Mw           *mwa.Config                `yaml:"middleware"`
-	AuthStorage  *mwa.AuthStorageConfig     `yaml:"auth_storage"`
-	Verification *verificationconfig.Config `yaml:"verification"`
+	Notifications *notifications.Config      `yaml:"notifications"`
+	Mw            *mwa.Config                `yaml:"middleware"`
+	AuthStorage   *mwa.AuthStorageConfig     `yaml:"auth_storage"`
+	Verification  *verificationconfig.Config `yaml:"verification"`
 }
 
 func (c *Config) SharedConfig() *Config {

backend/product/app/http/middleware.go

@@ -7,10 +7,18 @@ import (
 
 	mr "git.sendico.io/tech/sxchnge/product/app/metrics"
 	"git.sendico.io/tech/sxchnge/product/auth/config"
+	"git.sendico.io/tech/sxchnge/product/auth/flow"
 	httprouter "git.sendico.io/tech/sxchnge/product/auth/http"
+	public "git.sendico.io/tech/sxchnge/product/auth/http/public"
 	"git.sendico.io/tech/sxchnge/product/auth/response"
 	authstorage "git.sendico.io/tech/sxchnge/product/auth/storage"
+	accountservice "git.sendico.io/tech/sxchnge/product/customers"
+	"git.sendico.io/tech/sxchnge/product/notifications"
 	"git.sendico.io/tech/sxchnge/product/sessions/browser"
+	"git.sendico.io/tech/sxchnge/product/twofactor"
+	delivery "git.sendico.io/tech/sxchnge/product/twofactor/delivery"
+	factorhttp "git.sendico.io/tech/sxchnge/product/twofactor/http"
+	factorstore "git.sendico.io/tech/sxchnge/product/twofactor/store"
 	"git.sendico.io/tech/sxchnge/shared/database"
 	"git.sendico.io/tech/sxchnge/shared/errors"
 	api "git.sendico.io/tech/sxchnge/shared/http"
@@ -26,11 +34,12 @@ import (
 )
 
 type Middleware struct {
-	logger       mlogger.Logger
-	router       *chi.Mux
-	apiEndpoint  string
-	metrics      mr.Metrics
-	epdispatcher *httprouter.Dispatcher
+	notifications *notifications.Client
+	logger        mlogger.Logger
+	router        *chi.Mux
+	apiEndpoint   string
+	metrics       mr.Metrics
+	epdispatcher  *httprouter.Dispatcher
 }
 
 func (mw *Middleware) Handler(service mservice.Type, endpoint string, method api.HTTPMethod, handler sresponse.HandlerFunc) {
@@ -47,6 +56,9 @@ func (mw *Middleware) PendingAccountHandler(service mservice.Type, endpoint stri
 
 func (mw *Middleware) Finish() {
 	mw.metrics.Finish()
+	if mw.notifications != nil {
+		_ = mw.notifications.Close()
+	}
 }
 
 func (mw *Middleware) installMiddleware(config *middleware.Config, debug bool) {
@@ -107,6 +119,7 @@ func CreateMiddleware(
 	config *middleware.Config,
 	authStorage *middleware.AuthStorageConfig,
 	debug bool,
+	notificationConfig ...*notifications.Config,
 ) (*Middleware, error) {
 	if config == nil {
 		return nil, merrors.InvalidArgument("middleware configuration is required", "middleware")
@@ -139,15 +152,50 @@ func CreateMiddleware(
 		return nil, err
 	}
 
+	var authFlow *flow.Service
+	var factors *twofactor.Service
+	if len(notificationConfig) > 0 && notificationConfig[0] != nil {
+		c := notificationConfig[0]
+		customers, err := accountservice.NewAccountService(p.logger, db, &config.Password, authStorage)
+		if err != nil {
+			return nil, err
+		}
+		authFlow = &flow.Service{Accounts: stores.Accounts, Customers: customers, Tokens: stores.Verification, Transactions: db.TransactionFactory(), Attempts: stores.LoginAttempts, Secret: middleware.SignatureConf(config).PrivateKey, ActivationURL: c.ActivationURL}
+		if err = authFlow.Validate(); err != nil {
+			return nil, err
+		}
+		p.notifications, err = notifications.Open(*c)
+		if err != nil {
+			return nil, err
+		}
+		authFlow.Sender = p.notifications
+		records, err := factorstore.Open(p.logger, db)
+		if err != nil {
+			_ = p.notifications.Close()
+			return nil, err
+		}
+		factors, err = twofactor.New(stores.Accounts, stores.Verification, records, db.TransactionFactory(), middleware.SignatureConf(config).PrivateKey, p.logger, delivery.Email{Sender: p.notifications})
+		if err != nil {
+			_ = p.notifications.Close()
+			return nil, err
+		}
+	}
+	flows := public.Flows{Onboarding: authFlow}
+	if factors != nil {
+		flows.Factors = factors
+	}
 	p.epdispatcher = httprouter.NewDispatcher(
 		p.logger,
 		p.router,
 		stores.Accounts,
-		stores.Verification,
 		stores.RefreshTokens,
 		stores.LoginAttempts,
 		config,
 		loginRateLimits,
+		flows,
 	)
+	if factors != nil {
+		factorhttp.Install(p.epdispatcher, factors, p.logger)
+	}
 	return p, nil
 }

backend/product/app/runtime/bootstrap.go

@@ -83,6 +83,7 @@ func (a *APIImp) installRuntimeBasics(
 		a.config.Mw,
 		a.config.AuthStorage,
 		debug,
+		a.config.Notifications,
 	); err != nil {
 		a.logger.Error("Failed to create middleware", zap.Error(err))
 		return err

backend/product/app/runtime/bootstrap_test.go

@@ -2,7 +2,6 @@ package runtime_test
 
 import (
 	"context"
-	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -14,6 +13,7 @@ import (
 	"git.sendico.io/tech/sxchnge/product/app/profile"
 	sharedruntime "git.sendico.io/tech/sxchnge/product/app/runtime"
 	"git.sendico.io/tech/sxchnge/shared/database"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
 	"github.com/go-chi/chi/v5"
 	"github.com/stretchr/testify/require"
 	"github.com/testcontainers/testcontainers-go/modules/mongodb"
@@ -48,6 +48,8 @@ func TestProfileStartsOnEmptyDatabase(t *testing.T) {
 	t.Setenv("SXCHNGE_API_PROTOCOL", "http")
 	t.Setenv("SXCHNGE_API_ENDPOINT", "/api/v1")
 	t.Setenv("SXCHNGE_JWT_SECRET", "test-only-signing-key-at-least-32-bytes")
+	t.Setenv("SXCHNGE_NOTIFICATIONS_TOKEN", "test-notification-token-at-least-32-bytes")
+	example.API.Notifications.CAFile = "" // This startup test makes no notification RPCs.
 	root, routes := chi.NewRouter(), chi.NewRouter()
 	runtime, err := sharedruntime.CreateAPI(ctx, zap.NewNop(), &example.API, &example.API, factory, root, routes, false, profile.Runtime())
 	require.NoError(t, err)

backend/product/architecture/twofactor_test.go

@@ -0,0 +1,48 @@
+package architecture
+
+import (
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// Keep the reusable domain independent of transport and session ownership.
+func TestSecondFactorDomainBoundary(t *testing.T) {
+	err := filepath.WalkDir("../twofactor", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			if d.Name() == "http" {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		file, err := parser.ParseFile(token.NewFileSet(), path, nil, parser.ImportsOnly)
+		if err != nil {
+			return err
+		}
+		for _, im := range file.Imports {
+			name, err := strconv.Unquote(im.Path.Value)
+			if err != nil {
+				return err
+			}
+			for _, blocked := range []string{"/product/auth/", "/product/sessions/", "/jwtauth", "/jwt/"} {
+				if strings.Contains(name, blocked) {
+					t.Errorf("2FA domain imports operation/transport dependency %s in %s", name, path)
+				}
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+}

backend/product/auth/flow/service.go

@@ -0,0 +1,182 @@
+// Package flow owns signup and account activation, independently of second-factor checks.
+package flow
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"net/url"
+	"strings"
+	"time"
+
+	accountservice "git.sendico.io/tech/sxchnge/product/customers"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	account "git.sendico.io/tech/sxchnge/product/customers/store"
+	"git.sendico.io/tech/sxchnge/product/notifications"
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	"git.sendico.io/tech/sxchnge/shared/database/repository"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	ratelimits "git.sendico.io/tech/sxchnge/shared/ratelimit/store"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+const Cooldown = time.Minute
+
+type Service struct {
+	Accounts      account.DB
+	Customers     accountservice.AccountService
+	Tokens        verification.DB
+	Transactions  transaction.Factory
+	Attempts      ratelimits.Store
+	Sender        notifications.Sender
+	Secret        []byte
+	ActivationURL string
+}
+
+func (s *Service) Validate() error {
+	u, err := url.Parse(s.ActivationURL)
+	if err != nil || u.Host == "" || (u.Scheme != "https" && !(u.Scheme == "http" && (u.Hostname() == "localhost" || u.Hostname() == "127.0.0.1"))) || u.User != nil || u.Fragment != "" {
+		return merrors.InvalidArgument("activation URL must be an absolute HTTPS URL (HTTP allowed on localhost)")
+	}
+	if len(s.Secret) < 32 {
+		return merrors.InvalidArgument("authentication signing secret must be at least 32 bytes")
+	}
+	return nil
+}
+func (s *Service) key(parts ...string) string {
+	h := hmac.New(sha256.New, s.Secret)
+	for _, p := range parts {
+		h.Write([]byte(p))
+		h.Write([]byte{0})
+	}
+	return hex.EncodeToString(h.Sum(nil))
+}
+func (s *Service) Limit(ctx context.Context, ip, email string) error {
+	now := time.Now().UTC()
+	start := now.Truncate(time.Hour)
+	for _, scope := range []struct {
+		kind, value string
+		limit       int
+	}{{"auth_email", email, 10}, {"auth_ip", ip, 30}} {
+		count, err := s.Attempts.Increment(ctx, scope.kind, ratelimits.HashScope(scope.kind, scope.value), start, start.Add(time.Hour))
+		if err != nil {
+			return merrors.ServiceUnavailableWrap(err, "authentication rate limit unavailable")
+		}
+		if count > scope.limit {
+			return verification.ErrorIssuanceRateLimited(scope.kind, start.Add(time.Hour).Sub(now))
+		}
+	}
+	return nil
+}
+func (s *Service) Signup(ctx context.Context, a *customer.Account, ip, key string) (*customer.Account, error) {
+	email, err := customer.NormalizeEmail(a.Login)
+	if err != nil {
+		return nil, err
+	}
+	a.Login = email
+	a.Name = strings.TrimSpace(a.Name)
+	if len(a.Name) > 200 || len(a.Password) > 72 {
+		return nil, merrors.InvalidArgument("name or password too long")
+	}
+	if err = s.Limit(ctx, ip, email); err != nil {
+		return nil, err
+	}
+	raw, err := s.Customers.CreateAccount(ctx, a)
+	if errors.Is(err, merrors.ErrDataConflict) {
+		existing, lookup := s.Accounts.GetByEmail(ctx, email)
+		if lookup != nil {
+			return nil, lookup
+		}
+		// A retry after a queue failure may resume only with the original password.
+		if existing.Status != customer.AccountPendingVerification || !existing.MatchPassword(a.Password) {
+			return nil, merrors.DataConflict("email already registered")
+		}
+		a = existing
+	} else if err != nil {
+		return nil, err
+	}
+	if raw != "" {
+		u, _ := url.Parse(s.ActivationURL)
+		q := u.Query()
+		q.Set("token", raw)
+		u.RawQuery = q.Encode()
+		locale := "en"
+		if strings.HasPrefix(a.Locale, "ru") {
+			locale = "ru"
+		}
+		err = s.Sender.Send(ctx, notifications.Message{Key: s.key("signup", raw), UserID: a.ID.Hex(), Email: a.Login, Locale: locale, Template: "auth.activation", Parameters: map[string]string{"url": u.String()}, ExpiresAt: time.Now().UTC().Add(23 * time.Hour)})
+	} else {
+		_, err = s.sendActivation(ctx, a, key)
+	}
+	return a, err
+}
+func (s *Service) ResendActivation(ctx context.Context, email, ip, key string) error {
+	email, err := customer.NormalizeEmail(email)
+	if err != nil {
+		return err
+	}
+	if err = s.Limit(ctx, ip, email); err != nil {
+		return err
+	}
+	a, err := s.Accounts.GetByEmail(ctx, email)
+	if errors.Is(err, merrors.ErrNoData) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if a.Status != customer.AccountPendingVerification || a.IsArchived() {
+		return nil
+	}
+	_, err = s.sendActivation(ctx, a, key)
+	return err
+}
+func (s *Service) sendActivation(ctx context.Context, a *customer.Account, key string) (time.Time, error) {
+	if strings.TrimSpace(key) == "" || len(key) > 128 {
+		return time.Time{}, merrors.InvalidArgument("idempotency key required")
+	}
+	secretKey := s.key(a.ID.Hex(), string(verificationmodel.PurposeAccountActivation), "", key)
+	req := verification.NewLinkRequest(a.ID, verificationmodel.PurposeAccountActivation, "").WithTTL(24 * time.Hour).WithCooldown(Cooldown).WithIdempotencyKey(secretKey)
+	req.WithIssuanceLimits(verification.NewIssuanceLimit("auth_delivery", a.Login, 5, time.Hour, time.Now().UTC()))
+	result, err := s.Tokens.CreateWithResult(ctx, req)
+	if err != nil {
+		return time.Time{}, err
+	}
+	if !result.ExpiresAt.After(time.Now()) {
+		return time.Time{}, verification.ErorrTokenExpired()
+	}
+	locale := "en"
+	if strings.HasPrefix(strings.ToLower(a.Locale), "ru") {
+		locale = "ru"
+	}
+	u, _ := url.Parse(s.ActivationURL)
+	q := u.Query()
+	q.Set("token", result.VerificationToken)
+	u.RawQuery = q.Encode()
+	err = s.Sender.Send(ctx, notifications.Message{Key: secretKey, UserID: a.ID.Hex(), Email: a.Login, Locale: locale, Template: "auth.activation", ExpiresAt: result.ExpiresAt, Parameters: map[string]string{"url": u.String()}})
+	return result.ExpiresAt, err
+}
+func (s *Service) Activate(ctx context.Context, raw string) error {
+	if len(raw) != 43 {
+		return verification.ErorrTokenNotFound()
+	}
+	_, err := s.Transactions.CreateTransaction().Execute(ctx, func(tx context.Context) (any, error) {
+		token, err := s.Tokens.Consume(tx, bson.NilObjectID, verificationmodel.PurposeAccountActivation, "", raw)
+		if err != nil {
+			return nil, err
+		}
+		a := &customer.Account{}
+		if err = s.Accounts.Get(tx, token.AccountRef, a); err != nil {
+			return nil, err
+		}
+		if a.Status != customer.AccountPendingVerification || a.IsArchived() {
+			return nil, merrors.Unauthorized("account cannot be activated")
+		}
+		return nil, s.Accounts.Patch(tx, a.ID, repository.Patch().Set(repository.Field("status"), customer.AccountActive))
+	})
+	return err
+}

backend/product/auth/flow/service_test.go

@@ -0,0 +1,73 @@
+package flow
+
+import (
+	"context"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	"git.sendico.io/tech/sxchnge/product/notifications"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"github.com/stretchr/testify/require"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"strings"
+	"testing"
+	"time"
+)
+
+type tokenStub struct {
+	verification.DB
+	request *verification.Request
+	result  verification.CreateResult
+	err     error
+}
+
+func (s *tokenStub) CreateWithResult(_ context.Context, r *verification.Request) (verification.CreateResult, error) {
+	s.request = r
+	return s.result, s.err
+}
+
+type senderStub struct {
+	messages []notifications.Message
+	err      error
+}
+
+func (s *senderStub) Send(_ context.Context, m notifications.Message) error {
+	s.messages = append(s.messages, m)
+	return s.err
+}
+func TestIssueRetriesSamePayloadAndBindsServerSecret(t *testing.T) {
+	expiry := time.Now().UTC().Add(time.Minute)
+	tokens := &tokenStub{result: verification.CreateResult{VerificationToken: "123456", ExpiresAt: expiry}}
+	sender := &senderStub{err: merrors.ServiceUnavailable("queue")}
+	service := &Service{Tokens: tokens, Sender: sender, Secret: []byte(strings.Repeat("s", 32)), ActivationURL: "https://app.example/verify-email"}
+	a := &customer.Account{}
+	a.ID = bson.NewObjectID()
+	a.Login = "user@example.com"
+	a.Locale = "ru-RU"
+	_, err := service.sendActivation(context.Background(), a, "client-key")
+	require.Error(t, err)
+	key := *tokens.request.IdempotencyKey
+	require.NotEqual(t, "client-key", key)
+	require.Equal(t, verification.TokenKindLink, tokens.request.Kind)
+	require.Equal(t, 24*time.Hour, tokens.request.Ttl)
+	sender.err = nil
+	_, err = service.sendActivation(context.Background(), a, "client-key")
+	require.NoError(t, err)
+	require.Equal(t, sender.messages[0], sender.messages[1])
+	require.Equal(t, "ru", sender.messages[0].Locale)
+	service.Secret = []byte(strings.Repeat("b", 32))
+	require.NotEqual(t, key, service.key(a.ID.Hex(), "account_activation", "client-key"))
+	tokens.result.ExpiresAt = time.Now().Add(-time.Minute)
+	_, err = service.sendActivation(context.Background(), a, "expired")
+	require.ErrorIs(t, err, verification.ErrTokenExpired)
+	require.Len(t, sender.messages, 2)
+}
+func TestValidateActivationDestination(t *testing.T) {
+	for _, destination := range []string{"https://app.example/verify-email", "http://localhost:5126/verify-email"} {
+		s := &Service{Secret: []byte(strings.Repeat("s", 32)), ActivationURL: destination}
+		require.NoError(t, s.Validate())
+	}
+	for _, destination := range []string{"http://app.example/verify-email", "//app.example", "https://user:pass@app.example/verify-email", "https://app.example/#/verify"} {
+		s := &Service{Secret: []byte(strings.Repeat("s", 32)), ActivationURL: destination}
+		require.Error(t, s.Validate())
+	}
+}

backend/product/auth/http/dispatcher.go

@@ -3,19 +3,17 @@ package router
 import (
 	"os"
 
-	"github.com/go-chi/chi/v5"
-
 	"git.sendico.io/tech/sxchnge/product/auth/config"
 	rauthorized "git.sendico.io/tech/sxchnge/product/auth/http/authorized"
 	rpublic "git.sendico.io/tech/sxchnge/product/auth/http/public"
 	"git.sendico.io/tech/sxchnge/product/auth/response"
 	"git.sendico.io/tech/sxchnge/product/customers/store"
 	"git.sendico.io/tech/sxchnge/product/sessions/store"
-	"git.sendico.io/tech/sxchnge/product/verification/store"
 	api "git.sendico.io/tech/sxchnge/shared/http"
 	"git.sendico.io/tech/sxchnge/shared/logging"
 	"git.sendico.io/tech/sxchnge/shared/ratelimit/store"
 	"git.sendico.io/tech/sxchnge/shared/service"
+	"github.com/go-chi/chi/v5"
 )
 
 type Dispatcher struct {
@@ -40,11 +38,11 @@ func NewDispatcher(
 	logger mlogger.Logger,
 	router chi.Router,
 	db account.DB,
-	vdb verification.DB,
 	rtdb refreshtokens.DB,
 	attempts ratelimits.Store,
 	config *middleware.Config,
 	loginRateLimits middleware.LoginRateLimits,
+	flows ...rpublic.Flows,
 ) *Dispatcher {
 	d := &Dispatcher{
 		logger: logger.Named("api_dispatcher"),
@@ -54,7 +52,7 @@ func NewDispatcher(
 	endpoint := os.Getenv(config.EndPointEnv)
 	signature := middleware.SignatureConf(config)
 	router.Group(func(r chi.Router) {
-		d.public = rpublic.NewRouter(d.logger, endpoint, db, vdb, rtdb, attempts, r, &config.Token, &signature, loginRateLimits)
+		d.public = rpublic.NewRouter(d.logger, endpoint, db, rtdb, attempts, r, &config.Token, &signature, loginRateLimits, flows...)
 	})
 	router.Group(func(r chi.Router) {
 		d.protected = rauthorized.NewRouter(d.logger, endpoint, r, db, rtdb, &config.Token, &signature)

backend/product/auth/http/public/login.go

@@ -5,8 +5,6 @@ import (
 	"crypto/subtle"
 	"encoding/json"
 	"errors"
-	customermodel "git.sendico.io/tech/sxchnge/product/customers/model"
-	sessionmodel "git.sendico.io/tech/sxchnge/product/sessions/model"
 	"net/http"
 	"strings"
 
@@ -14,6 +12,8 @@ import (
 	"git.sendico.io/tech/sxchnge/product/auth/ipguard"
 	"git.sendico.io/tech/sxchnge/product/auth/request"
 	"git.sendico.io/tech/sxchnge/product/auth/response"
+	customermodel "git.sendico.io/tech/sxchnge/product/customers/model"
+	sessionmodel "git.sendico.io/tech/sxchnge/product/sessions/model"
 	"git.sendico.io/tech/sxchnge/shared/errors"
 	"git.sendico.io/tech/sxchnge/shared/http/response"
 	"git.sendico.io/tech/sxchnge/shared/logging"
@@ -195,7 +195,7 @@ func decodeLogin(r *http.Request, logger mlogger.Logger) (*srequest.Login, http.
 		return nil, response.BadPayload(logger, mservice.Accounts, err)
 	}
 	req.Login = strings.TrimSpace(req.Login)
-	req.Password = strings.TrimSpace(req.Password)
+	// Preserve passwords exactly as entered.
 	req.ClientID = strings.TrimSpace(req.ClientID)
 	req.DeviceID = strings.TrimSpace(req.DeviceID)
 	req.ClientSecret = strings.TrimSpace(req.ClientSecret)
@@ -225,6 +225,9 @@ func (a *PublicRouter) login(r *http.Request) http.HandlerFunc {
 	if h = a.validateClientAccountBinding(client, account); h != nil {
 		return h
 	}
+	if a.factors != nil {
+		return a.beginLogin(r, account, req.SessionIdentifier, randomKey())
+	}
 	return a.respondPendingLogin(account)
 }
 

backend/product/auth/http/public/login_test.go

@@ -187,7 +187,6 @@ func TestAPILoginAllowsLoginAgainAfterRevokeSameSession(t *testing.T) {
 		zap.NewNop(),
 		"/",
 		&testAccountDB{result: account},
-		nil,
 		rtdb,
 		nil,
 		chi.NewRouter(),

backend/product/auth/http/public/metrics.go

@@ -0,0 +1,35 @@
+package public
+
+import (
+	"net/http"
+	"time"
+
+	sresponse "git.sendico.io/tech/sxchnge/product/auth/response"
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var flowRequests = promauto.NewCounterVec(prometheus.CounterOpts{Name: "sxchnge_auth_flow_requests_total", Help: "Authentication flow outcomes; success means this HTTP step completed, not email delivery."}, []string{"operation", "outcome"})
+var flowDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{Name: "sxchnge_auth_flow_duration_seconds", Help: "Authentication HTTP step latency."}, []string{"operation"})
+
+func measured(operation string, handler sresponse.HandlerFunc) sresponse.HandlerFunc {
+	return func(r *http.Request) http.HandlerFunc {
+		start := time.Now()
+		response := handler(r)
+		return func(w http.ResponseWriter, r *http.Request) {
+			wrapped := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
+			response(wrapped, r)
+			outcome := "accepted"
+			if wrapped.Status() >= 500 {
+				outcome = "unavailable"
+			} else if wrapped.Status() == 429 {
+				outcome = "limited"
+			} else if wrapped.Status() >= 400 {
+				outcome = "rejected"
+			}
+			flowRequests.WithLabelValues(operation, outcome).Inc()
+			flowDuration.WithLabelValues(operation).Observe(time.Since(start).Seconds())
+		}
+	}
+}

backend/product/auth/http/public/refresh_test.go

@@ -51,7 +51,6 @@ func newBrowserRefreshRouter(t *testing.T, expiresAt time.Time) (*PublicRouter,
 		zap.NewNop(),
 		"/api/v1",
 		&testAccountDB{result: account},
-		nil,
 		rtdb,
 		nil,
 		chi.NewRouter(),

backend/product/auth/http/public/respond.go

@@ -19,6 +19,14 @@ func (pr *PublicRouter) refreshAndRespondLogin(
 	session *sessionmodel.SessionIdentifier,
 	account *customermodel.Account,
 ) http.HandlerFunc {
+	result, err := pr.prepareLogin(ctx, r, session, account)
+	if err != nil {
+		return response.Internal(pr.logger, pr.service, err)
+	}
+	return result
+}
+
+func (pr *PublicRouter) prepareLogin(ctx context.Context, r *http.Request, session *sessionmodel.SessionIdentifier, account *customermodel.Account) (http.HandlerFunc, error) {
 	refreshToken, err := rtokens.PrepareRefreshToken(
 		ctx,
 		r,
@@ -32,18 +40,18 @@ func (pr *PublicRouter) refreshAndRespondLogin(
 	if err != nil {
 		pr.logger.Warn("Failed to create refresh token", zap.Error(err), mzap.StorableRef(account),
 			zap.String("client_id", session.ClientID), zap.String("device_id", session.DeviceID))
-		return response.Internal(pr.logger, pr.service, err)
+		return nil, err
 	}
 	accessToken, err := pr.imp.CreateAccessTokenForSession(account, refreshToken.SessionIdentifier)
 	if err != nil {
 		pr.logger.Warn("Failed to generate access token", zap.Error(err), mzap.StorableRef(account),
 			zap.String("client_id", session.ClientID), zap.String("device_id", session.DeviceID))
-		return response.Internal(pr.logger, pr.service, err)
+		return nil, err
 	}
 
 	token := sresponse.TokenData{
 		Token:      refreshToken.RefreshToken,
 		Expiration: refreshToken.ExpiresAt,
 	}
-	return sresponse.Login(pr.logger, account, &accessToken, &token)
+	return sresponse.Login(pr.logger, account, &accessToken, &token), nil
 }

backend/product/auth/http/public/router.go

@@ -4,11 +4,12 @@ import (
 	"time"
 
 	"git.sendico.io/tech/sxchnge/product/auth/config"
+	"git.sendico.io/tech/sxchnge/product/auth/flow"
 	re "git.sendico.io/tech/sxchnge/product/auth/http/endpoint"
 	"git.sendico.io/tech/sxchnge/product/auth/response"
 	"git.sendico.io/tech/sxchnge/product/customers/store"
 	"git.sendico.io/tech/sxchnge/product/sessions/store"
-	"git.sendico.io/tech/sxchnge/product/verification/store"
+	"git.sendico.io/tech/sxchnge/product/twofactor"
 	api "git.sendico.io/tech/sxchnge/shared/http"
 	"git.sendico.io/tech/sxchnge/shared/logging"
 	"git.sendico.io/tech/sxchnge/shared/ratelimit/store"
@@ -16,7 +17,14 @@ import (
 	"github.com/go-chi/chi/v5"
 )
 
+type Flows struct {
+	Onboarding *flow.Service
+	Factors    twofactor.API
+}
+
 type PublicRouter struct {
+	factors   twofactor.API
+	flow      *flow.Service
 	logger    mlogger.Logger
 	db        account.DB
 	imp       *re.HttpEndpointRouter
@@ -37,13 +45,13 @@ func NewRouter(
 	logger mlogger.Logger,
 	apiEndpoint string,
 	db account.DB,
-	vdb verification.DB,
 	rtdb refreshtokens.DB,
 	attempts ratelimits.Store,
 	router chi.Router,
 	config *middleware.TokenConfig,
 	signature *middleware.Signature,
 	limits middleware.LoginRateLimits,
+	flows ...Flows,
 ) *PublicRouter {
 	l := logger.Named("public")
 	hr := PublicRouter{
@@ -59,7 +67,20 @@ func NewRouter(
 		now:       time.Now,
 	}
 
-	hr.InstallHandler(hr.service, "/login", api.Post, hr.login)
+	if len(flows) > 0 {
+		hr.flow = flows[0].Onboarding
+		hr.factors = flows[0].Factors
+	}
+	if hr.flow != nil {
+		hr.InstallHandler(hr.service, "/signup", api.Post, measured("signup", hr.signup))
+		hr.InstallHandler(hr.service, "/verification/send", api.Post, measured("activation_send", hr.resendActivation))
+		hr.InstallHandler(hr.service, "/verification/confirm", api.Post, measured("activation", hr.activate))
+	}
+	if hr.factors != nil {
+		hr.InstallHandler(hr.service, "/login/resend", api.Post, measured("login_send", hr.resendLogin))
+		hr.InstallHandler(hr.service, "/login/verify", api.Post, measured("login_verify", hr.verifyLogin))
+	}
+	hr.InstallHandler(hr.service, "/login", api.Post, measured("login", hr.login))
 	hr.InstallHandler(hr.service, "/login/api", api.Post, hr.apiLogin)
 	hr.InstallHandler(hr.service, "/rotate", api.Post, hr.rotateRefreshToken)
 	hr.InstallHandler(hr.service, "/refresh", api.Post, hr.refreshAccessToken)

backend/product/auth/http/public/verification.go

@@ -0,0 +1,259 @@
+package public
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/product/auth/ipguard"
+	authmodel "git.sendico.io/tech/sxchnge/product/auth/model"
+	sresponse "git.sendico.io/tech/sxchnge/product/auth/response"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	session "git.sendico.io/tech/sxchnge/product/sessions/model"
+	factor "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"git.sendico.io/tech/sxchnge/shared/http/response"
+	"github.com/go-chi/jwtauth/v5"
+	"go.uber.org/zap"
+)
+
+type signupRequest struct {
+	Name     string `json:"name"`
+	Email    string `json:"email"`
+	Password string `json:"password"`
+	Locale   string `json:"locale"`
+	Key      string `json:"idempotencyKey"`
+}
+type challengeRequest struct {
+	ChallengeID  string                    `json:"challengeId"`
+	PendingToken string                    `json:"pendingToken"`
+	Code         string                    `json:"code"`
+	Key          string                    `json:"idempotencyKey"`
+	Session      session.SessionIdentifier `json:"sessionIdentifier"`
+}
+type challengeResponse struct {
+	ChallengeID  string              `json:"challengeId"`
+	Channel      factor.Channel      `json:"channel"`
+	UserID       string              `json:"userId"`
+	PendingToken sresponse.TokenData `json:"pendingToken"`
+	Target       string              `json:"target"`
+	ExpiresAt    time.Time           `json:"expiresAt"`
+	ResendAt     time.Time           `json:"resendAt"`
+}
+
+func decodeFlow(r *http.Request, dst any) error {
+	d := json.NewDecoder(io.LimitReader(r.Body, 8193))
+	d.DisallowUnknownFields()
+	if err := d.Decode(dst); err != nil {
+		return merrors.InvalidArgument("invalid request")
+	}
+	var extra any
+	if err := d.Decode(&extra); err != io.EOF {
+		return merrors.InvalidArgument("invalid request")
+	}
+	return nil
+}
+func requestIP(r *http.Request) string {
+	if ip := ipguard.ClientIP(r); ip != nil {
+		return ip.String()
+	}
+	return "unresolved"
+}
+func (pr *PublicRouter) flowError(err error) http.HandlerFunc {
+	if details, ok := verification.Throttle(err); ok {
+		return pr.loginRateLimited(details.RetryAfter)
+	}
+	switch {
+	case errors.Is(err, verification.ErrTokenExpired):
+		return response.BadRequest(pr.logger, pr.service, "expired", "Verification expired; request a new email")
+	case errors.Is(err, verification.ErrTokenAttemptsExceeded):
+		return response.BadRequest(pr.logger, pr.service, "locked", "Too many attempts; request a new code")
+	case errors.Is(err, verification.ErrTokenNotFound), errors.Is(err, verification.ErrTokenAlreadyUsed):
+		return response.BadRequest(pr.logger, pr.service, "invalid", "Verification is invalid or already used")
+	case errors.Is(err, merrors.ErrDataConflict):
+		return response.BadRequest(pr.logger, pr.service, "email_in_use", "Email is already registered")
+	case errors.Is(err, merrors.ErrInvalidArg):
+		return response.BadRequest(pr.logger, pr.service, "invalid_request", "Check the request fields")
+	case errors.Is(err, merrors.ErrUnauthorized):
+		return response.Unauthorized(pr.logger, pr.service, "credentials required")
+	default:
+		// Do not include downstream errors: they may contain transport/request details.
+		pr.logger.Warn("Authentication flow dependency failed")
+		return func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			w.Header().Set("Cache-Control", "no-store")
+			w.WriteHeader(http.StatusServiceUnavailable)
+			_, _ = w.Write([]byte(`{"data":{"code":"unavailable","details":"Unable to complete verification. Please retry."}}`))
+		}
+	}
+}
+func (pr *PublicRouter) signup(r *http.Request) http.HandlerFunc {
+	var req signupRequest
+	if err := decodeFlow(r, &req); err != nil {
+		return pr.flowError(err)
+	}
+	if req.Key == "" || len(req.Key) > 128 {
+		return pr.flowError(merrors.InvalidArgument("idempotency key required"))
+	}
+	a := &customer.Account{Password: req.Password}
+	a.Name = req.Name
+	a.Login = req.Email
+	a.Locale = req.Locale
+	a, err := pr.flow.Signup(r.Context(), a, requestIP(r), req.Key)
+	if err != nil {
+		return pr.flowError(err)
+	}
+	pr.logger.Info("Signup verification queued", zap.String("account_ref", a.ID.Hex()))
+	return response.Accepted(pr.logger, map[string]string{"userId": a.ID.Hex()})
+}
+func (pr *PublicRouter) resendActivation(r *http.Request) http.HandlerFunc {
+	var req struct {
+		Email string `json:"email"`
+		Key   string `json:"idempotencyKey"`
+	}
+	if err := decodeFlow(r, &req); err != nil {
+		return pr.flowError(err)
+	}
+	if req.Key == "" || len(req.Key) > 128 {
+		return pr.flowError(merrors.InvalidArgument("idempotency key required"))
+	}
+	if err := pr.flow.ResendActivation(r.Context(), req.Email, requestIP(r), req.Key); err != nil {
+		return pr.flowError(err)
+	}
+	return response.Accepted(pr.logger, map[string]bool{"accepted": true})
+}
+func (pr *PublicRouter) activate(r *http.Request) http.HandlerFunc {
+	var req struct {
+		Token string `json:"token"`
+	}
+	if err := decodeFlow(r, &req); err != nil {
+		return pr.flowError(err)
+	}
+	if err := pr.flow.Activate(r.Context(), req.Token); err != nil {
+		return pr.flowError(err)
+	}
+	pr.logger.Info("Account activation completed")
+	return response.Accepted(pr.logger, map[string]bool{"verified": true})
+}
+func challengeScope(raw string) string {
+	h := sha256.Sum256([]byte(raw))
+	return hex.EncodeToString(h[:])
+}
+func (pr *PublicRouter) beginLogin(r *http.Request, a *customer.Account, sessionID session.SessionIdentifier, key string) http.HandlerFunc {
+	if sessionID.ClientID == "" || sessionID.DeviceID == "" || len(sessionID.DeviceID) > 128 {
+		return pr.flowError(merrors.InvalidArgument("session identifier required"))
+	}
+	claims := authmodel.PendingAccount2Claims(a, pendingLoginTTLMinutes)
+	claims["clientId"] = sessionID.ClientID
+	claims["deviceId"] = sessionID.DeviceID
+	// Independent challenges, even when password requests arrive within one second.
+	claims["nonce"] = randomKey()
+	ja := jwtauth.New(pr.signature.Algorithm, pr.signature.PrivateKey, pr.signature.PublicKey)
+	_, raw, err := ja.Encode(claims)
+	if err != nil {
+		return pr.flowError(err)
+	}
+	token := sresponse.TokenData{Token: raw, Expiration: time.Unix(claims["exp"].(int64), 0)}
+	return pr.queueLogin(r, a, token, key, "")
+}
+func randomKey() string { return rand.Text() }
+func loginScope(raw string) factor.Scope {
+	return factor.Scope{Purpose: verificationmodel.PurposeLogin, ContextRef: challengeScope(raw)}
+}
+func (pr *PublicRouter) queueLogin(r *http.Request, a *customer.Account, token sresponse.TokenData, key, id string) http.HandlerFunc {
+	if pr.factors == nil {
+		return pr.flowError(merrors.ServiceUnavailable("second-factor service unavailable"))
+	}
+	req := factor.Request{Subject: a.ID, Scope: loginScope(token.Token), Deadline: token.Expiration, IdempotencyKey: key, IP: requestIP(r)}
+	var challenge factor.Challenge
+	var err error
+	if id == "" {
+		challenge, err = pr.factors.Begin(r.Context(), req)
+	} else {
+		challenge, err = pr.factors.Resend(r.Context(), req, id)
+	}
+	if err != nil {
+		return pr.flowError(err)
+	}
+	return response.Accepted(pr.logger, challengeResponse{ChallengeID: challenge.ID, Channel: challenge.Channel, UserID: a.ID.Hex(), PendingToken: token, Target: challenge.Target, ExpiresAt: challenge.ExpiresAt, ResendAt: challenge.ResendAt})
+}
+func (pr *PublicRouter) pending(ctx context.Context, raw string) (*customer.Account, *authmodel.AccountToken, error) {
+	if len(raw) > 8192 {
+		return nil, nil, merrors.Unauthorized("invalid pending token")
+	}
+	ja := jwtauth.New(pr.signature.Algorithm, pr.signature.PrivateKey, pr.signature.PublicKey)
+	t, err := jwtauth.VerifyToken(ja, raw)
+	if err != nil {
+		return nil, nil, merrors.Unauthorized("invalid pending token")
+	}
+	_, claims, err := jwtauth.FromContext(jwtauth.NewContext(ctx, t, nil))
+	if err != nil {
+		return nil, nil, err
+	}
+	token, err := authmodel.Claims2Token(claims)
+	if err != nil || !token.Pending || token.ClientID == "" || token.DeviceID == "" {
+		return nil, nil, merrors.Unauthorized("pending login required")
+	}
+	a := &customer.Account{}
+	if err = pr.db.Get(ctx, token.AccountRef, a); err != nil {
+		return nil, nil, err
+	}
+	if !a.IsActive() || a.IsArchived() {
+		return nil, nil, merrors.Unauthorized("inactive account")
+	}
+	return a, token, nil
+}
+func (pr *PublicRouter) resendLogin(r *http.Request) http.HandlerFunc {
+	var req challengeRequest
+	if err := decodeFlow(r, &req); err != nil {
+		return pr.flowError(err)
+	}
+	if req.ChallengeID == "" {
+		return pr.flowError(merrors.InvalidArgument("challenge ID required"))
+	}
+	a, t, err := pr.pending(r.Context(), req.PendingToken)
+	if err != nil {
+		return pr.flowError(err)
+	}
+	return pr.queueLogin(r, a, sresponse.TokenData{Token: req.PendingToken, Expiration: t.Expiration}, req.Key, req.ChallengeID)
+}
+func (pr *PublicRouter) verifyLogin(r *http.Request) http.HandlerFunc {
+	var req challengeRequest
+	if err := decodeFlow(r, &req); err != nil {
+		return pr.flowError(err)
+	}
+	a, t, err := pr.pending(r.Context(), req.PendingToken)
+	if err != nil {
+		return pr.flowError(err)
+	}
+	client, h := pr.resolveLoginClient(r.Context(), r, t.ClientID)
+	if h != nil {
+		return h
+	}
+	if h = pr.validateClientAccountBinding(client, a); h != nil {
+		return h
+	}
+	if pr.factors == nil {
+		return pr.flowError(merrors.ServiceUnavailable("second-factor service unavailable"))
+	}
+	scope := loginScope(req.PendingToken)
+	var result http.HandlerFunc
+	err = pr.factors.Complete(r.Context(), a.ID, scope, req.ChallengeID, req.Code, func(tx context.Context) error {
+		var err error
+		result, err = pr.prepareLogin(tx, r, &t.SessionIdentifier, a)
+		return err
+	})
+	if err != nil {
+		return pr.flowError(err)
+	}
+	pr.logger.Info("Login completed after second-factor proof consumption", zap.String("account_ref", a.ID.Hex()))
+	return result
+}

backend/product/auth/http/public/verification_integration_test.go

@@ -0,0 +1,136 @@
+package public
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	middleware "git.sendico.io/tech/sxchnge/product/auth/config"
+	"git.sendico.io/tech/sxchnge/product/auth/flow"
+	authstorage "git.sendico.io/tech/sxchnge/product/auth/storage"
+	accountservice "git.sendico.io/tech/sxchnge/product/customers"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	"git.sendico.io/tech/sxchnge/product/notifications"
+	session "git.sendico.io/tech/sxchnge/product/sessions/model"
+	"git.sendico.io/tech/sxchnge/product/twofactor"
+	"git.sendico.io/tech/sxchnge/product/twofactor/delivery"
+	factorstore "git.sendico.io/tech/sxchnge/product/twofactor/store"
+	db "git.sendico.io/tech/sxchnge/shared/database"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+	"github.com/go-chi/chi/v5"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"go.uber.org/zap"
+)
+
+type capturedMail struct {
+	messages []notifications.Message
+	fail     bool
+}
+
+func (m *capturedMail) Send(_ context.Context, r notifications.Message) error {
+	m.messages = append(m.messages, r)
+	if m.fail {
+		return merrors.ServiceUnavailable("test queue unavailable")
+	}
+	return nil
+}
+func TestSignupActivationAndLoginEmailFlow(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	container, err := mongodb.Run(ctx, "mongo:8", mongodb.WithReplicaSet("rs"))
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, container.Terminate(context.Background())) })
+	uri, err := container.ConnectionString(ctx)
+	require.NoError(t, err)
+	u, err := url.Parse(uri)
+	require.NoError(t, err)
+	q := u.Query()
+	q.Set("directConnection", "true")
+	u.RawQuery = q.Encode()
+	factory, err := db.NewConnection(zap.NewNop(), &db.Config{Driver: db.Mongo, Settings: sharedmodel.SettingsT{"uri": u.String(), "database": "auth_flow"}})
+	require.NoError(t, err)
+	t.Cleanup(factory.CloseConnection)
+	stores, err := authstorage.OpenStores(zap.NewNop(), factory, nil)
+	require.NoError(t, err)
+	customers, err := accountservice.NewAccountService(zap.NewNop(), factory, &middleware.PasswordConfig{Check: middleware.PasswordChecks{MinLength: 12}}, nil)
+	require.NoError(t, err)
+	mail := &capturedMail{}
+	service := &flow.Service{Accounts: stores.Accounts, Customers: customers, Tokens: stores.Verification, Transactions: factory.TransactionFactory(), Attempts: stores.LoginAttempts, Sender: mail, Secret: []byte(strings.Repeat("s", 32)), ActivationURL: "https://app.example/verify-email"}
+	require.NoError(t, service.Validate())
+	// Keep the real verification/customer stores and capture only session writes.
+	sessions := &testRefreshTokenDB{client: &session.Client{ClientID: "web"}}
+	records, err := factorstore.Open(zap.NewNop(), factory)
+	require.NoError(t, err)
+	factors, err := twofactor.New(stores.Accounts, stores.Verification, records, factory.TransactionFactory(), service.Secret, zap.NewNop(), delivery.Email{Sender: mail})
+	require.NoError(t, err)
+	routes := chi.NewRouter()
+	NewRouter(zap.NewNop(), "/api/v1", stores.Accounts, sessions, nil, routes, &middleware.TokenConfig{Length: 32, Expiration: middleware.TokenExpiration{Account: 1, Refresh: 24}}, &middleware.Signature{Algorithm: "HS256", PrivateKey: service.Secret}, middleware.LoginRateLimits{}, Flows{Onboarding: service, Factors: factors})
+	post := func(path string, body any) *httptest.ResponseRecorder {
+		raw, err := json.Marshal(body)
+		require.NoError(t, err)
+		r := httptest.NewRequest(http.MethodPost, "/api/v1/accounts/"+path, strings.NewReader(string(raw)))
+		r.RemoteAddr = "192.0.2.1:1234"
+		w := httptest.NewRecorder()
+		routes.ServeHTTP(w, r)
+		return w
+	}
+	signup := map[string]any{"name": "Customer", "email": "USER@example.com", "password": " correct password ", "locale": "ru", "idempotencyKey": "signup-one"}
+	w := post("signup", signup)
+	require.Equal(t, 202, w.Code, w.Body.String())
+	require.Len(t, mail.messages, 1)
+	require.Equal(t, "auth.activation", mail.messages[0].Template)
+	require.Equal(t, "user@example.com", mail.messages[0].Email)
+	require.Equal(t, "ru", mail.messages[0].Locale)
+	activationURL, err := url.Parse(mail.messages[0].Parameters["url"])
+	require.NoError(t, err)
+	activation := activationURL.Query().Get("token")
+	require.NotEmpty(t, activation)
+	a, err := stores.Accounts.GetByEmail(ctx, "user@example.com")
+	require.NoError(t, err)
+	require.False(t, a.IsActive())
+	login := map[string]any{"login": map[string]string{"login": "user@example.com", "password": " correct password "}, "clientId": "web", "deviceId": "browser"}
+	require.Equal(t, 403, post("login", login).Code)
+	require.Equal(t, 400, post("verification/confirm", map[string]string{"token": "invalid"}).Code)
+	w = post("verification/confirm", map[string]string{"token": activation})
+	require.Equal(t, 202, w.Code, w.Body.String())
+	require.Equal(t, 400, post("verification/confirm", map[string]string{"token": activation}).Code)
+	a, err = stores.Accounts.GetByEmail(ctx, a.Login)
+	require.NoError(t, err)
+	require.Equal(t, customer.AccountActive, a.Status)
+	w = post("login", login)
+	require.Equal(t, 202, w.Code, w.Body.String())
+	require.Len(t, mail.messages, 2)
+	require.Empty(t, sessions.tokens)
+	var pending struct {
+		Data challengeResponse `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &pending))
+	require.NotEmpty(t, pending.Data.PendingToken.Token)
+	require.NotContains(t, w.Body.String(), mail.messages[1].Parameters["code"])
+	code := mail.messages[1].Parameters["code"]
+	require.Len(t, code, 6)
+	wrong := "000000"
+	if code == wrong {
+		wrong = "111111"
+	}
+	require.Equal(t, 400, post("login/verify", map[string]string{"pendingToken": pending.Data.PendingToken.Token, "challengeId": pending.Data.ChallengeID, "code": wrong}).Code)
+	require.Empty(t, sessions.tokens)
+	require.Equal(t, 429, post("login/resend", map[string]string{"pendingToken": pending.Data.PendingToken.Token, "challengeId": pending.Data.ChallengeID, "idempotencyKey": "resend-too-soon"}).Code)
+	w = post("login/verify", map[string]string{"pendingToken": pending.Data.PendingToken.Token, "challengeId": pending.Data.ChallengeID, "code": code})
+	require.Equal(t, 200, w.Code, w.Body.String())
+	require.Len(t, sessions.tokens, 1)
+	require.Equal(t, "browser", sessions.tokens[0].DeviceID)
+	require.Equal(t, 400, post("login/verify", map[string]string{"pendingToken": pending.Data.PendingToken.Token, "challengeId": pending.Data.ChallengeID, "code": code}).Code)
+	require.Len(t, sessions.tokens, 1)
+	// A queue outage cannot report a successful login challenge or create a session.
+	mail.fail = true
+	require.Equal(t, 503, post("login", login).Code)
+	require.Len(t, sessions.tokens, 1)
+}

backend/product/config.example.yml

@@ -31,3 +31,9 @@ api:
       token_length: 32
       check:
         min_length: 12
+  notifications:
+    address: localhost:8443
+    token_env: SXCHNGE_NOTIFICATIONS_TOKEN
+    ca_file: ../notifications/tls/ca.pem
+    server_name: localhost
+    activation_url: http://localhost:5126/verify-email

backend/product/customers/model/email.go

@@ -0,0 +1,16 @@
+package model
+
+import (
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"net/mail"
+	"strings"
+)
+
+func NormalizeEmail(email string) (string, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	a, err := mail.ParseAddress(email)
+	if err != nil || a.Address != email || len(email) > 254 {
+		return "", merrors.InvalidArgument("valid email required")
+	}
+	return email, nil
+}

backend/product/go.mod

@@ -69,13 +69,17 @@ require (
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/net v0.58.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
 	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/text v0.41.0 // indirect
-	google.golang.org/protobuf v1.36.11 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
 )
 
+replace git.sendico.io/tech/sxchnge/shared => ../shared
+
 require (
+	git.sendico.io/tech/sxchnge/notifications/interface v0.0.0
 	git.sendico.io/tech/sxchnge/shared v0.0.0
 	github.com/go-chi/chi/v5 v5.3.2
 	github.com/go-chi/cors v1.2.2
@@ -89,8 +93,10 @@ require (
 	go.mongodb.org/mongo-driver/v2 v2.9.0
 	go.uber.org/zap v1.28.0
 	golang.org/x/crypto v0.56.0
+	google.golang.org/grpc v1.83.2
+	google.golang.org/protobuf v1.36.12
 	gopkg.in/yaml.v3 v3.0.1
 	moul.io/chizap v1.0.3
 )
 
-replace git.sendico.io/tech/sxchnge/shared => ../shared
+replace git.sendico.io/tech/sxchnge/notifications/interface => ../notifications/interface

backend/product/go.sum

@@ -63,6 +63,8 @@ github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPE
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/goccy/go-json v0.10.3 h1:KZ5WoDbxAIgm2HNbYckL0se1fHD6rz5j4ywS6ebzDqA=
 github.com/goccy/go-json v0.10.3/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -226,6 +228,8 @@ golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwY
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
+golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -267,8 +271,14 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
-google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa h1:mZHHdPZl0dbGHCflZgAq/Q468DWVFcU2whhB2KAo8fk=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.83.2 h1:EManeRomTObA0BU7I8vXgg/78uE5MJ9M8B39EX2WscU=
+google.golang.org/grpc v1.83.2/go.mod h1:YPI1hK3kDked6iHvgX3tR0y+nX/qpMFKhPgFsokw1S8=
+google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
+google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=

backend/product/notifications/client.go

@@ -0,0 +1,88 @@
+// Package notifications adapts the internal notification wire contract to product models.
+package notifications
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"os"
+	"time"
+
+	pb "git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+type Config struct {
+	Address       string `yaml:"address"`
+	TokenEnv      string `yaml:"token_env"`
+	CAFile        string `yaml:"ca_file"`
+	ServerName    string `yaml:"server_name"`
+	ActivationURL string `yaml:"activation_url"`
+}
+type Message struct {
+	Key, UserID, Email, Locale, Template string
+	Parameters                           map[string]string
+	ExpiresAt                            time.Time
+}
+type Sender interface {
+	Send(context.Context, Message) error
+}
+type Client struct {
+	conn  *grpc.ClientConn
+	rpc   pb.NotificationsServiceClient
+	token string
+}
+
+func Open(c Config) (*Client, error) {
+	token := os.Getenv(c.TokenEnv)
+	if c.Address == "" || len(token) < 32 {
+		return nil, merrors.InvalidArgument("notification address and caller token of at least 32 bytes are required")
+	}
+	tlsConfig := &tls.Config{MinVersion: tls.VersionTLS12, ServerName: c.ServerName}
+	if c.CAFile != "" {
+		pem, err := os.ReadFile(c.CAFile)
+		if err != nil {
+			return nil, merrors.InternalWrap(err, "read notification CA")
+		}
+		pool, err := x509.SystemCertPool()
+		if err != nil {
+			pool = x509.NewCertPool()
+		}
+		if !pool.AppendCertsFromPEM(pem) {
+			return nil, merrors.InvalidArgument("invalid notification CA")
+		}
+		tlsConfig.RootCAs = pool
+	}
+	conn, err := grpc.NewClient(c.Address, grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)))
+	if err != nil {
+		return nil, merrors.InternalWrap(err, "create notification client")
+	}
+	return &Client{conn: conn, rpc: pb.NewNotificationsServiceClient(conn), token: token}, nil
+}
+func (c *Client) Close() error { return c.conn.Close() }
+func (c *Client) Send(ctx context.Context, m Message) error {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+c.token)
+	res, err := c.rpc.Send(ctx, request(m))
+	if err != nil {
+		return merrors.ServiceUnavailableWrap(err, "notification queue unavailable")
+	}
+	if res.GetNotification().GetId() == "" || len(res.GetNotification().GetDeliveries()) != 1 {
+		return merrors.ServiceUnavailable("notification queue returned no receipt")
+	}
+	for _, d := range res.Notification.Deliveries {
+		switch d.State {
+		case pb.DeliveryState_DELIVERY_STATE_FAILED, pb.DeliveryState_DELIVERY_STATE_EXPIRED, pb.DeliveryState_DELIVERY_STATE_UNKNOWN:
+			return merrors.ServiceUnavailable("notification could not be delivered")
+		}
+	}
+	return nil
+}
+func request(m Message) *pb.SendRequest {
+	return &pb.SendRequest{IdempotencyKey: m.Key, UserId: m.UserID, TemplateId: m.Template, TemplateVersion: "1", Locale: m.Locale, Parameters: m.Parameters, ExpiresAt: timestamppb.New(m.ExpiresAt), Targets: []*pb.Target{{Destination: &pb.Target_Email{Email: &pb.EmailTarget{Address: m.Email}}}}}
+}

backend/product/notifications/client_test.go

@@ -0,0 +1,90 @@
+package notifications
+
+import (
+	"context"
+	"crypto/tls"
+	"encoding/pem"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	pb "git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/metadata"
+)
+
+type rpcStub struct {
+	pb.NotificationsServiceClient
+	request *pb.SendRequest
+	auth    string
+	result  *pb.SendResponse
+	err     error
+}
+
+func (s *rpcStub) Send(ctx context.Context, r *pb.SendRequest, _ ...grpc.CallOption) (*pb.SendResponse, error) {
+	s.request = r
+	md, _ := metadata.FromOutgoingContext(ctx)
+	s.auth = md.Get("authorization")[0]
+	return s.result, s.err
+}
+func TestSendMapsOwnedContractAndRejectsFailedReceipt(t *testing.T) {
+	rpc := &rpcStub{result: &pb.SendResponse{Notification: &pb.Notification{Id: "job", Deliveries: []*pb.Delivery{{State: pb.DeliveryState_DELIVERY_STATE_QUEUED}}}}}
+	client := &Client{rpc: rpc, token: "service-secret"}
+	expiry := time.Now().Add(time.Minute)
+	m := Message{Key: "key", UserID: "customer", Email: "user@example.com", Locale: "ru", Template: "auth.login", Parameters: map[string]string{"code": "123456"}, ExpiresAt: expiry}
+	require.NoError(t, client.Send(context.Background(), m))
+	require.Equal(t, "Bearer service-secret", rpc.auth)
+	require.Equal(t, m.Email, rpc.request.Targets[0].GetEmail().Address)
+	require.Equal(t, "1", rpc.request.TemplateVersion)
+	require.Equal(t, m.Parameters, rpc.request.Parameters)
+	require.WithinDuration(t, expiry, rpc.request.ExpiresAt.AsTime(), time.Nanosecond)
+	rpc.result.Notification.Deliveries[0].State = pb.DeliveryState_DELIVERY_STATE_UNKNOWN
+	require.ErrorIs(t, client.Send(context.Background(), m), merrors.ErrServiceUnavailable)
+	rpc.result = nil
+	require.ErrorIs(t, client.Send(context.Background(), m), merrors.ErrServiceUnavailable)
+}
+func TestOpenRequiresCredentialsAndValidCA(t *testing.T) {
+	_, err := Open(Config{Address: "localhost:8443", TokenEnv: "ABSENT_NOTIFICATION_TEST_TOKEN"})
+	require.ErrorIs(t, err, merrors.ErrInvalidArg)
+	t.Setenv("TEST_NOTIFICATION_TOKEN", "test-token-that-is-at-least-32-bytes")
+	_, err = Open(Config{Address: "localhost:8443", TokenEnv: "TEST_NOTIFICATION_TOKEN", CAFile: "missing.pem"})
+	require.Error(t, err)
+}
+
+type tlsRPC struct {
+	pb.UnimplementedNotificationsServiceServer
+	auth chan string
+}
+
+func (s *tlsRPC) Send(ctx context.Context, _ *pb.SendRequest) (*pb.SendResponse, error) {
+	md, _ := metadata.FromIncomingContext(ctx)
+	s.auth <- md.Get("authorization")[0]
+	return &pb.SendResponse{Notification: &pb.Notification{Id: "tls-job", Deliveries: []*pb.Delivery{{State: pb.DeliveryState_DELIVERY_STATE_QUEUED}}}}, nil
+}
+func TestOpenUsesVerifiedTLSAndCallerAuthentication(t *testing.T) {
+	fixture := httptest.NewTLSServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	cert := fixture.TLS.Certificates[0]
+	fixture.Close()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	server := grpc.NewServer(grpc.Creds(credentials.NewTLS(&tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS12})))
+	rpc := &tlsRPC{auth: make(chan string, 1)}
+	pb.RegisterNotificationsServiceServer(server, rpc)
+	go func() { _ = server.Serve(listener) }()
+	t.Cleanup(server.Stop)
+	ca := filepath.Join(t.TempDir(), "ca.pem")
+	require.NoError(t, os.WriteFile(ca, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cert.Certificate[0]}), 0600))
+	t.Setenv("TEST_TLS_CALLER_TOKEN", "test-service-token-with-at-least-32-bytes")
+	client, err := Open(Config{Address: listener.Addr().String(), TokenEnv: "TEST_TLS_CALLER_TOKEN", CAFile: ca})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = client.Close() })
+	require.NoError(t, client.Send(context.Background(), Message{ExpiresAt: time.Now().Add(time.Minute)}))
+	require.Equal(t, "Bearer test-service-token-with-at-least-32-bytes", <-rpc.auth)
+}

backend/product/twofactor/challenge.go

@@ -0,0 +1,138 @@
+package twofactor
+
+import (
+	"context"
+	"errors"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	vmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+	"strings"
+	"time"
+)
+
+func (s *Service) Begin(ctx context.Context, req model.Request) (model.Challenge, error) {
+	if !validScope(req.Scope) {
+		return model.Challenge{}, merrors.InvalidArgument("unsupported second-factor operation scope")
+	}
+	return s.begin(ctx, req, nil)
+}
+func (s *Service) begin(ctx context.Context, req model.Request, enrollment *model.Factor) (model.Challenge, error) {
+	if req.Subject.IsZero() || strings.TrimSpace(req.IdempotencyKey) == "" || len(req.IdempotencyKey) > 128 || strings.ContainsRune(req.IdempotencyKey, 0) {
+		return model.Challenge{}, merrors.InvalidArgument("subject and idempotency key required")
+	}
+	a, p, version, err := s.profile(ctx, req.Subject)
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	factor, err := s.preferred(p)
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	if enrollment != nil {
+		factor = *enrollment
+	}
+	// Repeating an operation key resolves to the same immutable challenge snapshot.
+	id, _ := bson.ObjectIDFromHex(s.key("challenge", req.Subject.Hex(), scopeKey(req.Scope), req.IdempotencyKey)[:24])
+	expires := time.Now().UTC().Add(TTL).Truncate(time.Millisecond)
+	if !req.Deadline.IsZero() && req.Deadline.Before(expires) {
+		expires = req.Deadline.UTC().Truncate(time.Millisecond)
+	}
+	if !expires.After(time.Now()) {
+		return model.Challenge{}, verification.ErorrTokenExpired()
+	}
+	locale := "en"
+	if strings.HasPrefix(strings.ToLower(a.Locale), "ru") {
+		locale = "ru"
+	}
+	candidate := &model.Record{Subject: req.Subject, Scope: req.Scope, Factor: factor, ProfileVersion: version, Locale: locale, ExpiresAt: expires}
+	candidate.ID = id
+	result, err := s.tx.CreateTransaction().Execute(ctx, func(tx context.Context) (any, error) {
+		r, err := s.store.Challenge(tx, id)
+		if errors.Is(err, merrors.ErrNoData) {
+			r = candidate
+			if err = s.store.CreateChallenge(tx, r); err != nil {
+				return nil, err
+			}
+		} else if err != nil {
+			return nil, err
+		}
+		if r.Subject != req.Subject || r.Scope != req.Scope || r.Factor != factor || r.ProfileVersion != version {
+			return nil, merrors.DataConflict("second-factor request changed")
+		}
+		return s.issue(tx, r, req.IdempotencyKey, req.IP)
+	})
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	return s.deliver(ctx, result)
+}
+func (s *Service) Resend(ctx context.Context, req model.Request, id string) (model.Challenge, error) {
+	result, err := s.tx.CreateTransaction().Execute(ctx, func(tx context.Context) (any, error) {
+		r, err := s.record(tx, id, req.Subject, req.Scope)
+		if err != nil {
+			return nil, err
+		}
+		return s.issue(tx, r, req.IdempotencyKey, req.IP)
+	})
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	return s.deliver(ctx, result)
+}
+
+type issued struct {
+	record   *model.Record
+	delivery model.Delivery
+	resendAt time.Time
+}
+
+func (s *Service) issue(ctx context.Context, r *model.Record, key, ip string) (issued, error) {
+	if r.VerifiedAt != nil {
+		return issued{}, verification.ErorrTokenAlreadyUsed()
+	}
+	if !r.ExpiresAt.After(time.Now()) {
+		return issued{}, verification.ErorrTokenExpired()
+	}
+	if strings.TrimSpace(key) == "" || len(key) > 128 || strings.ContainsRune(key, 0) {
+		return issued{}, merrors.InvalidArgument("idempotency key required")
+	}
+	if ip == "" {
+		ip = "unresolved"
+	}
+	secretKey := s.key("code", r.ID.Hex(), key)
+	now := time.Now().UTC()
+	req := verification.NewOTPRequest(r.Subject, r.Scope.Purpose, r.Factor.ID).
+		WithContextRef(r.ID.Hex()).WithTTL(time.Until(r.ExpiresAt)).WithCooldown(Cooldown).WithMaxRetries(5).WithIdempotencyKey(secretKey).
+		WithIssuanceLimits(verification.NewIssuanceLimit("twofactor_subject", r.Subject.Hex(), 5, time.Hour, now), verification.NewIssuanceLimit("twofactor_ip", ip, 20, time.Hour, now))
+	token, err := s.tokens.CreateWithResult(ctx, req)
+	if err != nil {
+		return issued{}, err
+	}
+	if !token.ExpiresAt.After(now) {
+		return issued{}, verification.ErorrTokenExpired()
+	}
+	return issued{record: r, delivery: model.Delivery{Key: secretKey, Subject: r.Subject, Scope: r.Scope, Factor: r.Factor, Locale: r.Locale, Code: token.VerificationToken, ExpiresAt: token.ExpiresAt}, resendAt: now.Add(Cooldown)}, nil
+}
+func (s *Service) deliver(ctx context.Context, result any) (model.Challenge, error) {
+	issued, ok := result.(issued)
+	if !ok {
+		return model.Challenge{}, merrors.Internal("invalid second-factor issuance result")
+	}
+	driver := s.drivers[issued.record.Factor.Channel]
+	if driver == nil {
+		return model.Challenge{}, merrors.NotImplemented("second-factor channel unavailable")
+	}
+	if err := driver.Send(ctx, issued.delivery); err != nil {
+		s.logger.Warn("Second-factor delivery unavailable", zap.String("challenge", issued.record.ID.Hex()), zap.String("channel", string(driver.Channel())))
+		return model.Challenge{}, merrors.ServiceUnavailableWrap(err, "second-factor delivery unavailable")
+	}
+	s.logger.Info("Second-factor challenge queued", zap.String("challenge", issued.record.ID.Hex()), zap.String("purpose", string(issued.record.Scope.Purpose)), zap.String("channel", string(driver.Channel())))
+	return model.Challenge{ID: issued.record.ID.Hex(), Channel: driver.Channel(), Target: driver.Mask(issued.record.Factor.Address), ExpiresAt: issued.delivery.ExpiresAt, ResendAt: issued.resendAt}, nil
+}
+
+func preferenceScope(factorID string) model.Scope {
+	return model.Scope{Purpose: vmodel.PurposeFactorPreference, ContextRef: "preferred:" + factorID}
+}

backend/product/twofactor/delivery/email.go

@@ -0,0 +1,23 @@
+package delivery
+
+import (
+	"context"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	"git.sendico.io/tech/sxchnge/product/notifications"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	vmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	"git.sendico.io/tech/sxchnge/shared/logging/mask"
+)
+
+type Email struct{ Sender notifications.Sender }
+
+func (Email) Channel() model.Channel                   { return model.Email }
+func (Email) Normalize(address string) (string, error) { return customer.NormalizeEmail(address) }
+func (Email) Mask(address string) string               { return mask.Email(address) }
+func (d Email) Send(ctx context.Context, m model.Delivery) error {
+	template := "twofactor.code"
+	if m.Scope.Purpose == vmodel.PurposeLogin {
+		template = "auth.login"
+	}
+	return d.Sender.Send(ctx, notifications.Message{Key: m.Key, UserID: m.Subject.Hex(), Email: m.Factor.Address, Locale: m.Locale, Template: template, Parameters: map[string]string{"code": m.Code}, ExpiresAt: m.ExpiresAt})
+}

backend/product/twofactor/http/router.go

@@ -0,0 +1,188 @@
+// Package factorhttp exposes authenticated factor settings. Operation scope and
+// account ownership are resolved on the server; raw proofs never cross HTTP.
+package factorhttp
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"math"
+	"net/http"
+	"strconv"
+	"time"
+
+	"git.sendico.io/tech/sxchnge/product/auth/ipguard"
+	sresponse "git.sendico.io/tech/sxchnge/product/auth/response"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	"git.sendico.io/tech/sxchnge/product/twofactor"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	api "git.sendico.io/tech/sxchnge/shared/http"
+	"git.sendico.io/tech/sxchnge/shared/http/response"
+	mlogger "git.sendico.io/tech/sxchnge/shared/logging"
+	mservice "git.sendico.io/tech/sxchnge/shared/service"
+)
+
+type Registrar interface {
+	AccountHandler(mservice.Type, string, api.HTTPMethod, sresponse.AccountHandlerFunc)
+}
+type router struct {
+	service *twofactor.Service
+	logger  mlogger.Logger
+}
+
+func Install(reg Registrar, service *twofactor.Service, logger mlogger.Logger) {
+	h := &router{service: service, logger: logger.Named("twofactor_http")}
+	reg.AccountHandler(mservice.Accounts, "/two-factor", api.Get, h.settings)
+	reg.AccountHandler(mservice.Accounts, "/two-factor/enroll", api.Post, h.enroll)
+	reg.AccountHandler(mservice.Accounts, "/two-factor/enroll/verify", api.Post, h.confirmEnrollment)
+	reg.AccountHandler(mservice.Accounts, "/two-factor/preference", api.Post, h.preference)
+	reg.AccountHandler(mservice.Accounts, "/two-factor/preference/verify", api.Post, h.confirmPreference)
+	reg.AccountHandler(mservice.Accounts, "/two-factor/resend", api.Post, h.resend)
+}
+func decode(r *http.Request, dst any) error {
+	d := json.NewDecoder(io.LimitReader(r.Body, 8193))
+	d.DisallowUnknownFields()
+	if err := d.Decode(dst); err != nil {
+		return merrors.InvalidArgument("invalid request")
+	}
+	var extra any
+	if err := d.Decode(&extra); err != io.EOF {
+		return merrors.InvalidArgument("invalid request")
+	}
+	return nil
+}
+func requestIP(r *http.Request) string {
+	if ip := ipguard.ClientIP(r); ip != nil {
+		return ip.String()
+	}
+	return "unresolved"
+}
+func (h *router) result(data any, err error) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Cache-Control", "no-store")
+		if err == nil {
+			response.Accepted(h.logger, data).ServeHTTP(w, r)
+			return
+		}
+		var handler http.HandlerFunc
+		if throttle, ok := verification.Throttle(err); ok {
+			w.Header().Set("Retry-After", strconv.Itoa(max(1, int(math.Ceil(throttle.RetryAfter.Seconds())))))
+			handler = response.TooManyRequests(h.logger, mservice.Accounts, "Wait before requesting another code")
+		} else {
+			switch {
+			case errors.Is(err, verification.ErrTokenExpired):
+				handler = response.BadRequest(h.logger, mservice.Accounts, "expired", "Verification expired; restart the operation")
+			case errors.Is(err, verification.ErrTokenAttemptsExceeded):
+				handler = response.BadRequest(h.logger, mservice.Accounts, "locked", "Too many attempts; restart the operation")
+			case errors.Is(err, verification.ErrTokenNotFound), errors.Is(err, verification.ErrTokenAlreadyUsed), errors.Is(err, merrors.ErrNoData):
+				handler = response.BadRequest(h.logger, mservice.Accounts, "invalid", "Verification is invalid or already used")
+			case errors.Is(err, merrors.ErrInvalidArg):
+				handler = response.BadRequest(h.logger, mservice.Accounts, "invalid_request", "Check the request fields")
+			case errors.Is(err, merrors.ErrUnauthorized):
+				handler = response.Unauthorized(h.logger, mservice.Accounts, "Verification settings changed or account is inactive; restart the operation")
+			case errors.Is(err, merrors.ErrDataConflict):
+				handler = response.DataConflict(h.logger, mservice.Accounts, "Factor or request already exists")
+			case errors.Is(err, merrors.ErrNotImplemented):
+				handler = response.NotImplemented(h.logger, mservice.Accounts, "Second-factor channel is unavailable")
+			default:
+				h.logger.Warn("Second-factor settings dependency failed")
+				handler = response.Error(h.logger, mservice.Accounts, http.StatusServiceUnavailable, "unavailable", "Unable to complete verification; retry")
+			}
+		}
+		handler.ServeHTTP(w, r)
+	}
+}
+
+type challengeDTO struct {
+	ID        string        `json:"challengeId"`
+	Channel   model.Channel `json:"channel"`
+	Target    string        `json:"target"`
+	ExpiresAt time.Time     `json:"expiresAt"`
+	ResendAt  time.Time     `json:"resendAt"`
+}
+
+func mapChallenge(c model.Challenge) challengeDTO {
+	return challengeDTO{c.ID, c.Channel, c.Target, c.ExpiresAt, c.ResendAt}
+}
+
+type choiceDTO struct {
+	ID      string        `json:"id"`
+	Channel model.Channel `json:"channel"`
+	Target  string        `json:"target"`
+}
+type settingsDTO struct {
+	Required  bool        `json:"required"`
+	Preferred string      `json:"preferred"`
+	Factors   []choiceDTO `json:"factors"`
+}
+
+func mapSettings(s model.Settings) settingsDTO {
+	result := settingsDTO{Required: s.Required, Preferred: s.Preferred, Factors: []choiceDTO{}}
+	for _, f := range s.Factors {
+		result.Factors = append(result.Factors, choiceDTO{f.ID, f.Channel, f.Target})
+	}
+	return result
+}
+func (h *router) settings(r *http.Request, a *customer.Account, _ *sresponse.TokenData) http.HandlerFunc {
+	s, err := h.service.Settings(r.Context(), a.ID)
+	return h.result(mapSettings(s), err)
+}
+func (h *router) enroll(r *http.Request, a *customer.Account, _ *sresponse.TokenData) http.HandlerFunc {
+	var req struct {
+		Channel model.Channel `json:"channel"`
+		Address string        `json:"address"`
+		Key     string        `json:"idempotencyKey"`
+	}
+	if err := decode(r, &req); err != nil {
+		return h.result(nil, err)
+	}
+	c, err := h.service.Enroll(r.Context(), a.ID, req.Channel, req.Address, req.Key, requestIP(r))
+	return h.result(mapChallenge(c), err)
+}
+func (h *router) confirmEnrollment(r *http.Request, a *customer.Account, _ *sresponse.TokenData) http.HandlerFunc {
+	var req struct {
+		ID   string `json:"challengeId"`
+		Code string `json:"code"`
+	}
+	if err := decode(r, &req); err != nil {
+		return h.result(nil, err)
+	}
+	s, err := h.service.ConfirmEnrollment(r.Context(), a.ID, req.ID, req.Code)
+	return h.result(mapSettings(s), err)
+}
+func (h *router) preference(r *http.Request, a *customer.Account, _ *sresponse.TokenData) http.HandlerFunc {
+	var req struct {
+		ID  string `json:"factorId"`
+		Key string `json:"idempotencyKey"`
+	}
+	if err := decode(r, &req); err != nil {
+		return h.result(nil, err)
+	}
+	c, err := h.service.BeginPreference(r.Context(), a.ID, req.ID, req.Key, requestIP(r))
+	return h.result(mapChallenge(c), err)
+}
+func (h *router) confirmPreference(r *http.Request, a *customer.Account, _ *sresponse.TokenData) http.HandlerFunc {
+	var req struct {
+		Factor string `json:"factorId"`
+		ID     string `json:"challengeId"`
+		Code   string `json:"code"`
+	}
+	if err := decode(r, &req); err != nil {
+		return h.result(nil, err)
+	}
+	s, err := h.service.ConfirmPreference(r.Context(), a.ID, req.Factor, req.ID, req.Code)
+	return h.result(mapSettings(s), err)
+}
+func (h *router) resend(r *http.Request, a *customer.Account, _ *sresponse.TokenData) http.HandlerFunc {
+	var req struct {
+		ID  string `json:"challengeId"`
+		Key string `json:"idempotencyKey"`
+	}
+	if err := decode(r, &req); err != nil {
+		return h.result(nil, err)
+	}
+	c, err := h.service.ResendSettings(r.Context(), a.ID, req.ID, req.Key, requestIP(r))
+	return h.result(mapChallenge(c), err)
+}

backend/product/twofactor/http/router_test.go

@@ -0,0 +1,45 @@
+package factorhttp
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	sresponse "git.sendico.io/tech/sxchnge/product/auth/response"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	api "git.sendico.io/tech/sxchnge/shared/http"
+	mservice "git.sendico.io/tech/sxchnge/shared/service"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+)
+
+type accountRoutes map[string]sresponse.AccountHandlerFunc
+
+func (r accountRoutes) AccountHandler(_ mservice.Type, path string, _ api.HTTPMethod, h sresponse.AccountHandlerFunc) {
+	r[path] = h
+}
+
+func TestSettingsTransportRejectsCallerOwnedScopeAndDestinationOverrides(t *testing.T) {
+	routes := accountRoutes{}
+	Install(routes, nil, zap.NewNop())
+	// Every route is registered through the authenticated-account contract.
+	require.Len(t, routes, 6)
+	for _, tc := range []struct{ path, body string }{
+		{"/two-factor/enroll", `{"channel":"email","address":"a@example.com","subject":"other-account"}`},
+		{"/two-factor/enroll/verify", `{"challengeId":"id","code":"123456","purpose":"login"}`},
+		{"/two-factor/preference", `{"factorId":"id","address":"arbitrary@example.com"}`},
+		{"/two-factor/preference/verify", `{"factorId":"id","code":"123456","verified":true}`},
+		{"/two-factor/resend", `{"challengeId":"id","target":"arbitrary@example.com"}`},
+		{"/two-factor/enroll", `{"channel":"email"} {"channel":"sms"}`},
+	} {
+		t.Run(tc.path+tc.body, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodPost, tc.path, strings.NewReader(tc.body))
+			w := httptest.NewRecorder()
+			routes[tc.path](req, &customer.Account{}, nil).ServeHTTP(w, req)
+			require.Equal(t, http.StatusBadRequest, w.Code, w.Body.String())
+			require.Equal(t, "no-store", w.Header().Get("Cache-Control"))
+			require.NotContains(t, w.Body.String(), "arbitrary@example.com")
+		})
+	}
+}

backend/product/twofactor/model/model.go

@@ -0,0 +1,83 @@
+package model
+
+import (
+	verification "git.sendico.io/tech/sxchnge/product/verification/model"
+	storable "git.sendico.io/tech/sxchnge/shared/database/record"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"time"
+)
+
+type Channel string
+
+const Email Channel = "email"
+
+// Scope is supplied by the owning operation, never accepted as an authorization
+// decision from a caller's HTTP body. ContextRef identifies the exact operation.
+type Scope struct {
+	Purpose    verification.VerificationPurpose `bson:"purpose"`
+	ContextRef string                           `bson:"contextRef"`
+}
+type Request struct {
+	Subject        bson.ObjectID
+	Scope          Scope
+	Deadline       time.Time
+	IdempotencyKey string
+	IP             string
+}
+type Factor struct {
+	ID       string  `bson:"id"`
+	Channel  Channel `bson:"channel"`
+	Address  string  `bson:"address"`
+	Verified bool    `bson:"verified"`
+}
+type Profile struct {
+	storable.Base `bson:",inline"`
+	Preferred     string   `bson:"preferred"`
+	Factors       []Factor `bson:"factors"`
+	Revision      string   `bson:"revision"`
+	Fence         string   `bson:"fence"`
+}
+
+func (*Profile) Collection() string { return "two_factor_profiles" }
+
+type Record struct {
+	storable.Base  `bson:",inline"`
+	Subject        bson.ObjectID `bson:"subject"`
+	Scope          Scope         `bson:"scope"`
+	Factor         Factor        `bson:"factor"`
+	ProfileVersion string        `bson:"profileVersion"`
+	Locale         string        `bson:"locale"`
+	ExpiresAt      time.Time     `bson:"expiresAt"`
+	VerifiedAt     *time.Time    `bson:"verifiedAt,omitempty"`
+}
+
+func (*Record) Collection() string { return "two_factor_challenges" }
+
+type Challenge struct {
+	ID                  string
+	Channel             Channel
+	Target              string
+	ExpiresAt, ResendAt time.Time
+}
+type Proof struct {
+	Token     string
+	ExpiresAt time.Time
+}
+type Delivery struct {
+	Key          string
+	Subject      bson.ObjectID
+	Scope        Scope
+	Factor       Factor
+	Locale, Code string
+	ExpiresAt    time.Time
+}
+type Choice struct {
+	ID      string
+	Channel Channel
+	Target  string
+}
+type Settings struct {
+	Required  bool
+	Preferred string
+	Factors   []Choice
+}

backend/product/twofactor/preferences.go

@@ -0,0 +1,156 @@
+package twofactor
+
+import (
+	"context"
+	"crypto/rand"
+	"errors"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	vmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"time"
+)
+
+func isRejection(err error) bool {
+	return errors.Is(err, verification.ErrTokenNotFound) || errors.Is(err, verification.ErrTokenAlreadyUsed) || errors.Is(err, verification.ErrTokenExpired) || errors.Is(err, verification.ErrTokenAttemptsExceeded)
+}
+func (s *Service) saveProfile(ctx context.Context, p *model.Profile) error {
+	_, err := s.store.Profile(ctx, p.ID)
+	if errors.Is(err, merrors.ErrNoData) {
+		return s.store.CreateProfile(ctx, p)
+	}
+	if err != nil {
+		return err
+	}
+	return s.store.UpdateProfile(ctx, p)
+}
+func (s *Service) Settings(ctx context.Context, subject bson.ObjectID) (model.Settings, error) {
+	_, p, _, err := s.profile(ctx, subject)
+	if err != nil {
+		return model.Settings{}, err
+	}
+	result := model.Settings{Required: true, Preferred: p.Preferred}
+	for _, f := range p.Factors {
+		if f.Verified {
+			if driver := s.drivers[f.Channel]; driver != nil {
+				result.Factors = append(result.Factors, model.Choice{ID: f.ID, Channel: f.Channel, Target: driver.Mask(f.Address)})
+			}
+		}
+	}
+	return result, nil
+}
+func (s *Service) Enroll(ctx context.Context, subject bson.ObjectID, channel model.Channel, address, key, ip string) (model.Challenge, error) {
+	driver := s.drivers[channel]
+	if driver == nil {
+		return model.Challenge{}, merrors.NotImplemented("second-factor channel is not supported")
+	}
+	normalized, err := driver.Normalize(address)
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	_, p, _, err := s.profile(ctx, subject)
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	if len(p.Factors) >= 5 {
+		return model.Challenge{}, merrors.InvalidArgument("maximum enrolled factors reached")
+	}
+	for _, f := range p.Factors {
+		if f.Channel == channel && f.Address == normalized {
+			return model.Challenge{}, merrors.DataConflict("factor already enrolled")
+		}
+	}
+	f := model.Factor{ID: s.key("factor", subject.Hex(), string(channel), normalized)[:24], Channel: channel, Address: normalized}
+	scope := model.Scope{Purpose: vmodel.PurposeFactorEnrollment, ContextRef: "enroll:" + f.ID}
+	return s.begin(ctx, model.Request{Subject: subject, Scope: scope, IdempotencyKey: key, IP: ip}, &f)
+}
+func (s *Service) ConfirmEnrollment(ctx context.Context, subject bson.ObjectID, id, code string) (model.Settings, error) {
+	cid, err := bson.ObjectIDFromHex(id)
+	if err != nil {
+		return model.Settings{}, verification.ErorrTokenNotFound()
+	}
+	r, err := s.store.Challenge(ctx, cid)
+	if err != nil {
+		return model.Settings{}, err
+	}
+	if r.Subject != subject || r.Scope.Purpose != vmodel.PurposeFactorEnrollment {
+		return model.Settings{}, verification.ErorrTokenNotFound()
+	}
+	err = s.complete(ctx, subject, r.Scope, id, code, func(tx context.Context) error {
+		_, p, _, err := s.profile(tx, subject)
+		if err != nil {
+			return err
+		}
+		if len(p.Factors) >= 5 {
+			return merrors.InvalidArgument("maximum enrolled factors reached")
+		}
+		for _, f := range p.Factors {
+			if f.ID == r.Factor.ID {
+				return merrors.DataConflict("factor already enrolled")
+			}
+		}
+		factor := r.Factor
+		factor.Verified = true
+		p.Factors = append(p.Factors, factor)
+		p.Revision = rand.Text()
+		return s.saveProfile(tx, p)
+	})
+	if err != nil {
+		return model.Settings{}, err
+	}
+	return s.Settings(ctx, subject)
+}
+func (s *Service) BeginPreference(ctx context.Context, subject bson.ObjectID, factorID, key, ip string) (model.Challenge, error) {
+	_, p, _, err := s.profile(ctx, subject)
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	if !s.available(p, factorID) {
+		return model.Challenge{}, merrors.InvalidArgument("verified supported factor required")
+	}
+	return s.Begin(ctx, model.Request{Subject: subject, Scope: preferenceScope(factorID), IdempotencyKey: key, IP: ip, Deadline: time.Now().Add(TTL)})
+}
+func (s *Service) ConfirmPreference(ctx context.Context, subject bson.ObjectID, factorID, id, code string) (model.Settings, error) {
+	scope := preferenceScope(factorID)
+	err := s.Complete(ctx, subject, scope, id, code, func(tx context.Context) error {
+		_, p, _, err := s.profile(tx, subject)
+		if err != nil {
+			return err
+		}
+		if !s.available(p, factorID) {
+			return merrors.InvalidArgument("verified supported factor required")
+		}
+		p.Preferred = factorID
+		p.Revision = rand.Text()
+		return s.saveProfile(tx, p)
+	})
+	if err != nil {
+		return model.Settings{}, err
+	}
+	return s.Settings(ctx, subject)
+}
+func (s *Service) available(p *model.Profile, id string) bool {
+	for _, f := range p.Factors {
+		if f.ID == id && f.Verified && s.drivers[f.Channel] != nil {
+			return true
+		}
+	}
+	return false
+}
+
+// ResendSettings cannot be used to send or authorize a pending login challenge.
+func (s *Service) ResendSettings(ctx context.Context, subject bson.ObjectID, id, key, ip string) (model.Challenge, error) {
+	cid, err := bson.ObjectIDFromHex(id)
+	if err != nil {
+		return model.Challenge{}, verification.ErorrTokenNotFound()
+	}
+	r, err := s.store.Challenge(ctx, cid)
+	if err != nil {
+		return model.Challenge{}, err
+	}
+	if r.Subject != subject || (r.Scope.Purpose != vmodel.PurposeFactorEnrollment && r.Scope.Purpose != vmodel.PurposeFactorPreference) {
+		return model.Challenge{}, verification.ErorrTokenNotFound()
+	}
+	return s.Resend(ctx, model.Request{Subject: subject, Scope: r.Scope, IdempotencyKey: key, IP: ip}, id)
+}

backend/product/twofactor/proof.go

@@ -0,0 +1,153 @@
+package twofactor
+
+import (
+	"context"
+	"crypto/rand"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	vmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+	"strings"
+	"time"
+)
+
+type verificationOutcome struct {
+	proof    model.Proof
+	rejected error
+}
+
+func (s *Service) Verify(ctx context.Context, subject bson.ObjectID, scope model.Scope, id, code string) (model.Proof, error) {
+	if !validScope(scope) {
+		return model.Proof{}, merrors.InvalidArgument("unsupported second-factor operation scope")
+	}
+	return s.verify(ctx, subject, scope, id, code)
+}
+func (s *Service) verify(ctx context.Context, subject bson.ObjectID, scope model.Scope, id, code string) (model.Proof, error) {
+	code = strings.TrimSpace(code)
+	if len(code) != 6 || strings.IndexFunc(code, func(r rune) bool { return r < '0' || r > '9' }) >= 0 {
+		return model.Proof{}, verification.ErorrTokenNotFound()
+	}
+	result, err := s.tx.CreateTransaction().Execute(ctx, func(tx context.Context) (any, error) {
+		r, err := s.record(tx, id, subject, scope)
+		if err != nil {
+			return nil, err
+		}
+		if r.VerifiedAt != nil {
+			return nil, verification.ErorrTokenAlreadyUsed()
+		}
+		// Commit rejected verification attempts while rolling back infrastructure
+		// failures. Sendico's Consume records misses in the enclosing transaction.
+		_, err = s.tokens.Consume(tx, subject, scope.Purpose, r.ID.Hex(), code)
+		if err != nil {
+			if isRejection(err) {
+				return verificationOutcome{rejected: err}, nil
+			}
+			return nil, err
+		}
+		ttl := min(proofTTL, time.Until(r.ExpiresAt))
+		if ttl <= 0 {
+			return nil, verification.ErorrTokenExpired()
+		}
+		token, err := s.tokens.CreateWithResult(tx, verification.NewLinkRequest(subject, vmodel.PurposeFactorProof, r.ID.Hex()).WithContextRef(scopeKey(scope)).WithTTL(ttl).WithIdempotencyKey(s.key("proof", r.ID.Hex())))
+		if err != nil {
+			return nil, err
+		}
+		now := time.Now().UTC()
+		r.VerifiedAt = &now
+		if err = s.store.UpdateChallenge(tx, r); err != nil {
+			return nil, err
+		}
+		return verificationOutcome{proof: model.Proof{Token: token.VerificationToken, ExpiresAt: token.ExpiresAt}}, nil
+	})
+	if err != nil {
+		return model.Proof{}, err
+	}
+	outcome, ok := result.(verificationOutcome)
+	if !ok {
+		return model.Proof{}, merrors.Internal("invalid second-factor verification result")
+	}
+	if outcome.rejected != nil {
+		return model.Proof{}, outcome.rejected
+	}
+	s.logger.Debug("Second-factor proof prepared", zap.String("challenge", id), zap.String("purpose", string(scope.Purpose)))
+	return outcome.proof, nil
+}
+func (s *Service) Consume(ctx context.Context, subject bson.ObjectID, scope model.Scope, proof model.Proof, action func(context.Context) error) error {
+	if !validScope(scope) {
+		return merrors.InvalidArgument("unsupported second-factor operation scope")
+	}
+	return s.consume(ctx, subject, scope, proof, action)
+}
+func (s *Service) consume(ctx context.Context, subject bson.ObjectID, scope model.Scope, proof model.Proof, action func(context.Context) error) error {
+	if action == nil || len(proof.Token) != 43 {
+		return merrors.InvalidArgument("proof and transactional action required")
+	}
+	_, err := s.tx.CreateTransaction().Execute(ctx, func(tx context.Context) (any, error) {
+		token, err := s.tokens.Consume(tx, subject, vmodel.PurposeFactorProof, scopeKey(scope), proof.Token)
+		if err != nil {
+			return nil, err
+		}
+		r, err := s.record(tx, token.Target, subject, scope)
+		if err != nil {
+			return nil, err
+		}
+		if r.VerifiedAt == nil {
+			return nil, verification.ErorrTokenNotFound()
+		}
+		// Touch the profile in this transaction so a concurrent preference update
+		// conflicts and cannot let an old-factor proof authorize a later action.
+		_, p, _, err := s.profile(tx, subject)
+		if err != nil {
+			return nil, err
+		}
+		p.Fence = rand.Text()
+		if err = s.saveProfile(tx, p); err != nil {
+			return nil, err
+		}
+		return nil, action(tx)
+	})
+	if err == nil {
+		s.logger.Debug("Second-factor proof consumption prepared", zap.String("purpose", string(scope.Purpose)))
+	}
+	return err
+}
+
+// Complete atomically verifies the code, consumes its proof and commits the
+// owning operation. A failed operation leaves the code retryable; a rejected
+// code still commits its attempt counter.
+func (s *Service) Complete(ctx context.Context, subject bson.ObjectID, scope model.Scope, id, code string, action func(context.Context) error) error {
+	if !validScope(scope) {
+		return merrors.InvalidArgument("unsupported second-factor operation scope")
+	}
+	return s.complete(ctx, subject, scope, id, code, action)
+}
+func (s *Service) complete(ctx context.Context, subject bson.ObjectID, scope model.Scope, id, code string, action func(context.Context) error) error {
+	result, err := s.tx.CreateTransaction().Execute(ctx, func(tx context.Context) (any, error) {
+		proof, err := s.verify(tx, subject, scope, id, code)
+		if err != nil {
+			if isRejection(err) {
+				return verificationOutcome{rejected: err}, nil
+			}
+			return nil, err
+		}
+		if err = s.consume(tx, subject, scope, proof, action); err != nil {
+			return nil, err
+		}
+		return verificationOutcome{}, nil
+	})
+	if err != nil {
+		return err
+	}
+	outcome, ok := result.(verificationOutcome)
+	if !ok {
+		return merrors.Internal("invalid second-factor completion result")
+	}
+	if outcome.rejected == nil {
+		s.logger.Info("Second-factor operation completed", zap.String("challenge", id), zap.String("purpose", string(scope.Purpose)))
+	} else {
+		s.logger.Info("Second-factor code rejected", zap.String("challenge", id), zap.String("purpose", string(scope.Purpose)))
+	}
+	return outcome.rejected
+}

backend/product/twofactor/service.go

@@ -0,0 +1,159 @@
+// Package twofactor owns second-factor policy, challenges and one-use proofs.
+// It deliberately has no dependency on auth HTTP, JWTs or session creation.
+package twofactor
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"strings"
+	"time"
+
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	account "git.sendico.io/tech/sxchnge/product/customers/store"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	vmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	"git.sendico.io/tech/sxchnge/shared/database/transaction"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	mlogger "git.sendico.io/tech/sxchnge/shared/logging"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+const TTL = 10 * time.Minute
+const Cooldown = time.Minute
+const proofTTL = 2 * time.Minute
+const primary = "primary-email"
+
+// API is consumed by auth and other operation owners. Complete joins code
+// verification, proof consumption and the owner's local database action.
+type API interface {
+	Begin(context.Context, model.Request) (model.Challenge, error)
+	Resend(context.Context, model.Request, string) (model.Challenge, error)
+	Complete(context.Context, bson.ObjectID, model.Scope, string, string, func(context.Context) error) error
+}
+type Store interface {
+	Profile(context.Context, bson.ObjectID) (*model.Profile, error)
+	CreateProfile(context.Context, *model.Profile) error
+	UpdateProfile(context.Context, *model.Profile) error
+	Challenge(context.Context, bson.ObjectID) (*model.Record, error)
+	CreateChallenge(context.Context, *model.Record) error
+	UpdateChallenge(context.Context, *model.Record) error
+}
+type Driver interface {
+	Channel() model.Channel
+	Normalize(string) (string, error)
+	Mask(string) string
+	Send(context.Context, model.Delivery) error
+}
+type Service struct {
+	accounts account.DB
+	tokens   verification.DB
+	store    Store
+	tx       transaction.Factory
+	secret   []byte
+	drivers  map[model.Channel]Driver
+	logger   mlogger.Logger
+}
+
+func New(accounts account.DB, tokens verification.DB, store Store, tx transaction.Factory, secret []byte, logger mlogger.Logger, drivers ...Driver) (*Service, error) {
+	if accounts == nil || tokens == nil || store == nil || tx == nil || len(secret) < 32 || logger == nil {
+		return nil, merrors.InvalidArgument("2FA dependencies and private key material are required")
+	}
+	s := &Service{accounts: accounts, tokens: tokens, store: store, tx: tx, secret: append([]byte(nil), secret...), drivers: map[model.Channel]Driver{}, logger: logger.Named("twofactor")}
+	for _, d := range drivers {
+		if d == nil || s.drivers[d.Channel()] != nil {
+			return nil, merrors.InvalidArgument("unique second-factor channel drivers required")
+		}
+		s.drivers[d.Channel()] = d
+	}
+	if s.drivers[model.Email] == nil {
+		return nil, merrors.InvalidArgument("verified account email channel is required")
+	}
+	return s, nil
+}
+func (s *Service) key(parts ...string) string {
+	h := hmac.New(sha256.New, s.secret)
+	for _, p := range parts {
+		h.Write([]byte(p))
+		h.Write([]byte{0})
+	}
+	return hex.EncodeToString(h.Sum(nil))
+}
+func validScope(scope model.Scope) bool {
+	if strings.TrimSpace(scope.ContextRef) == "" || len(scope.ContextRef) > 256 || strings.ContainsRune(scope.ContextRef, 0) {
+		return false
+	}
+	switch scope.Purpose {
+	case vmodel.PurposeLogin, vmodel.PurposePayout, vmodel.PurposeFactorPreference:
+		return true
+	}
+	return false
+}
+func scopeKey(scope model.Scope) string { return string(scope.Purpose) + ":" + scope.ContextRef }
+func (s *Service) profile(ctx context.Context, id bson.ObjectID) (*customer.Account, *model.Profile, string, error) {
+	a := &customer.Account{}
+	if err := s.accounts.Get(ctx, id, a); err != nil {
+		return nil, nil, "", err
+	}
+	if !a.IsActive() || a.IsArchived() {
+		return nil, nil, "", merrors.Unauthorized("active verified account required")
+	}
+	p, err := s.store.Profile(ctx, id)
+	if errors.Is(err, merrors.ErrNoData) {
+		p = &model.Profile{Preferred: primary, Revision: "initial"}
+		p.ID = id
+	} else if err != nil {
+		return nil, nil, "", err
+	}
+	// The primary address is authorized by account activation, never by request data.
+	factors := []model.Factor{{ID: primary, Channel: model.Email, Address: a.Login, Verified: true}}
+	for _, f := range p.Factors {
+		if f.ID != primary {
+			factors = append(factors, f)
+		}
+	}
+	p.Factors = factors
+	version := s.key("profile", id.Hex(), a.Login, p.Revision)
+	return a, p, version, nil
+}
+func (s *Service) preferred(p *model.Profile) (model.Factor, error) {
+	for _, f := range p.Factors {
+		if f.ID == p.Preferred && f.Verified && s.drivers[f.Channel] != nil {
+			return f, nil
+		}
+	}
+	return model.Factor{}, merrors.Unauthorized("configured second factor is unavailable")
+}
+func (s *Service) record(ctx context.Context, idText string, subject bson.ObjectID, scope model.Scope) (*model.Record, error) {
+	id, err := bson.ObjectIDFromHex(idText)
+	if err != nil {
+		return nil, verification.ErorrTokenNotFound()
+	}
+	r, err := s.store.Challenge(ctx, id)
+	if errors.Is(err, merrors.ErrNoData) {
+		return nil, verification.ErorrTokenNotFound()
+	}
+	if err != nil {
+		return nil, err
+	}
+	if r.Subject != subject || r.Scope != scope {
+		return nil, verification.ErorrTokenNotFound()
+	}
+	if !r.ExpiresAt.After(time.Now()) {
+		return nil, verification.ErorrTokenExpired()
+	}
+	_, _, version, err := s.profile(ctx, subject)
+	if err != nil {
+		return nil, err
+	}
+	if version != r.ProfileVersion {
+		return nil, merrors.Unauthorized("second-factor settings changed; restart verification")
+	}
+	if s.drivers[r.Factor.Channel] == nil {
+		return nil, merrors.NotImplemented("second-factor channel unavailable")
+	}
+	return r, nil
+}

backend/product/twofactor/service_test.go

@@ -0,0 +1,235 @@
+package twofactor_test
+
+import (
+	"context"
+	"net/url"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	authstorage "git.sendico.io/tech/sxchnge/product/auth/storage"
+	customer "git.sendico.io/tech/sxchnge/product/customers/model"
+	"git.sendico.io/tech/sxchnge/product/twofactor"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	factorstore "git.sendico.io/tech/sxchnge/product/twofactor/store"
+	vmodel "git.sendico.io/tech/sxchnge/product/verification/model"
+	verification "git.sendico.io/tech/sxchnge/product/verification/store"
+	db "git.sendico.io/tech/sxchnge/shared/database"
+	merrors "git.sendico.io/tech/sxchnge/shared/errors"
+	sharedmodel "git.sendico.io/tech/sxchnge/shared/model"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go/modules/mongodb"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+)
+
+type capturedDriver struct {
+	deliveries []model.Delivery
+	fail       bool
+}
+
+func (*capturedDriver) Channel() model.Channel             { return model.Email }
+func (*capturedDriver) Normalize(s string) (string, error) { return customer.NormalizeEmail(s) }
+func (*capturedDriver) Mask(string) string                 { return "masked" }
+func (d *capturedDriver) Send(_ context.Context, m model.Delivery) error {
+	d.deliveries = append(d.deliveries, m)
+	if d.fail {
+		return merrors.ServiceUnavailable("queue unavailable")
+	}
+	return nil
+}
+func TestServiceTransactionsAndFactors(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	container, err := mongodb.Run(ctx, "mongo:8", mongodb.WithReplicaSet("rs"))
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, container.Terminate(context.Background())) })
+	uri, err := container.ConnectionString(ctx)
+	require.NoError(t, err)
+	u, err := url.Parse(uri)
+	require.NoError(t, err)
+	q := u.Query()
+	q.Set("directConnection", "true")
+	u.RawQuery = q.Encode()
+	factory, err := db.NewConnection(zap.NewNop(), &db.Config{Driver: db.Mongo, Settings: sharedmodel.SettingsT{"uri": u.String(), "database": "twofactor"}})
+	require.NoError(t, err)
+	t.Cleanup(factory.CloseConnection)
+	stores, err := authstorage.OpenStores(zap.NewNop(), factory, nil)
+	require.NoError(t, err)
+	records, err := factorstore.Open(zap.NewNop(), factory)
+	require.NoError(t, err)
+	driver := &capturedDriver{}
+	service, err := twofactor.New(stores.Accounts, stores.Verification, records, factory.TransactionFactory(), []byte(strings.Repeat("s", 32)), zap.NewNop(), driver)
+	require.NoError(t, err)
+	account := func() *customer.Account {
+		a := &customer.Account{Status: customer.AccountActive}
+		a.ID = bson.NewObjectID()
+		a.Login = a.ID.Hex() + "@example.com"
+		a.Locale = "ru"
+		require.NoError(t, stores.Accounts.Create(ctx, a))
+		return a
+	}
+	request := func(a *customer.Account) model.Request {
+		return model.Request{Subject: a.ID, Scope: model.Scope{Purpose: vmodel.PurposeLogin, ContextRef: bson.NewObjectID().Hex()}, IdempotencyKey: "begin", IP: a.ID.Hex()}
+	}
+	begin := func(r model.Request) (model.Challenge, string) {
+		c, err := service.Begin(ctx, r)
+		require.NoError(t, err)
+		return c, driver.deliveries[len(driver.deliveries)-1].Code
+	}
+	action := func(context.Context) error { return nil }
+	t.Run("delivery retry and immutable deadline", func(t *testing.T) {
+		a := account()
+		r := request(a)
+		r.Deadline = time.Now().Add(3 * time.Minute)
+		driver.fail = true
+		_, err := service.Begin(ctx, r)
+		require.ErrorIs(t, err, merrors.ErrServiceUnavailable)
+		first := driver.deliveries[len(driver.deliveries)-1]
+		driver.fail = false
+		c, code := begin(r)
+		require.Equal(t, first.Code, code)
+		require.Equal(t, first.Key, driver.deliveries[len(driver.deliveries)-1].Key)
+		require.WithinDuration(t, first.ExpiresAt, c.ExpiresAt, time.Millisecond)
+		require.False(t, c.ExpiresAt.After(r.Deadline))
+		require.Equal(t, a.Login, first.Factor.Address)
+		require.Equal(t, "ru", first.Locale)
+		require.Equal(t, "masked", c.Target)
+		r.IdempotencyKey = "resend"
+		_, err = service.Resend(ctx, r, c.ID)
+		_, throttled := verification.Throttle(err)
+		require.True(t, throttled)
+		_, err = service.ResendSettings(ctx, a.ID, c.ID, "settings", r.IP)
+		require.ErrorIs(t, err, verification.ErrTokenNotFound)
+	})
+	t.Run("scope and one use proof", func(t *testing.T) {
+		a := account()
+		r := request(a)
+		c, code := begin(r)
+		_, err := service.Verify(ctx, account().ID, r.Scope, c.ID, code)
+		require.ErrorIs(t, err, verification.ErrTokenNotFound)
+		other := r.Scope
+		other.ContextRef = "another-operation"
+		_, err = service.Verify(ctx, a.ID, other, c.ID, code)
+		require.ErrorIs(t, err, verification.ErrTokenNotFound)
+		other = r.Scope
+		other.Purpose = vmodel.PurposePayout
+		_, err = service.Verify(ctx, a.ID, other, c.ID, code)
+		require.ErrorIs(t, err, verification.ErrTokenNotFound)
+		proof, err := service.Verify(ctx, a.ID, r.Scope, c.ID, code)
+		require.NoError(t, err)
+		require.Len(t, proof.Token, 43)
+		require.Error(t, service.Consume(ctx, a.ID, other, proof, action))
+		require.ErrorIs(t, service.Consume(ctx, a.ID, r.Scope, proof, func(context.Context) error { return merrors.ServiceUnavailable("operation failed") }), merrors.ErrServiceUnavailable)
+		require.NoError(t, service.Consume(ctx, a.ID, r.Scope, proof, action))
+		require.Error(t, service.Consume(ctx, a.ID, r.Scope, proof, action))
+		_, err = service.Verify(ctx, a.ID, r.Scope, c.ID, code)
+		require.ErrorIs(t, err, verification.ErrTokenAlreadyUsed)
+	})
+	t.Run("atomic operation rollback and concurrent completion", func(t *testing.T) {
+		a := account()
+		r := request(a)
+		c, code := begin(r)
+		err := service.Complete(ctx, a.ID, r.Scope, c.ID, code, func(tx context.Context) error {
+			updated := &customer.Account{}
+			if err := stores.Accounts.Get(tx, a.ID, updated); err != nil {
+				return err
+			}
+			updated.Name = "should rollback"
+			if err := stores.Accounts.Update(tx, updated); err != nil {
+				return err
+			}
+			return merrors.ServiceUnavailable("session write failed")
+		})
+		require.ErrorIs(t, err, merrors.ErrServiceUnavailable)
+		saved := &customer.Account{}
+		require.NoError(t, stores.Accounts.Get(ctx, a.ID, saved))
+		require.Empty(t, saved.Name)
+		id, err := bson.ObjectIDFromHex(c.ID)
+		require.NoError(t, err)
+		record, err := records.Challenge(ctx, id)
+		require.NoError(t, err)
+		require.Nil(t, record.VerifiedAt)
+		var successes atomic.Int32
+		var wg sync.WaitGroup
+		for range 4 {
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				if service.Complete(ctx, a.ID, r.Scope, c.ID, code, action) == nil {
+					successes.Add(1)
+				}
+			}()
+		}
+		wg.Wait()
+		require.EqualValues(t, 1, successes.Load())
+	})
+	t.Run("bad attempts are committed even with an outer operation", func(t *testing.T) {
+		a := account()
+		r := request(a)
+		c, code := begin(r)
+		wrong := "000000"
+		if code == wrong {
+			wrong = "111111"
+		}
+		for range 5 {
+			require.Error(t, service.Complete(ctx, a.ID, r.Scope, c.ID, wrong, action))
+		}
+		require.ErrorIs(t, service.Complete(ctx, a.ID, r.Scope, c.ID, code, action), verification.ErrTokenAttemptsExceeded)
+	})
+	t.Run("expired and inactive challenges fail closed", func(t *testing.T) {
+		a := account()
+		r := request(a)
+		c, code := begin(r)
+		id, err := bson.ObjectIDFromHex(c.ID)
+		require.NoError(t, err)
+		record, err := records.Challenge(ctx, id)
+		require.NoError(t, err)
+		record.ExpiresAt = time.Now().Add(-time.Second)
+		require.NoError(t, records.UpdateChallenge(ctx, record))
+		_, err = service.Verify(ctx, a.ID, r.Scope, c.ID, code)
+		require.ErrorIs(t, err, verification.ErrTokenExpired)
+		a = account()
+		r = request(a)
+		c, code = begin(r)
+		a.Status = customer.AccountBlocked
+		require.NoError(t, stores.Accounts.Update(ctx, a))
+		require.ErrorIs(t, service.Complete(ctx, a.ID, r.Scope, c.ID, code, action), merrors.ErrUnauthorized)
+	})
+	t.Run("verified preference controls delivery and invalidates old proofs", func(t *testing.T) {
+		a := account()
+		r := request(a)
+		old, oldCode := begin(r)
+		proof, err := service.Verify(ctx, a.ID, r.Scope, old.ID, oldCode)
+		require.NoError(t, err)
+		_, err = service.Enroll(ctx, a.ID, "sms", "+10000000000", "sms", r.IP)
+		require.ErrorIs(t, err, merrors.ErrNotImplemented)
+		enroll, err := service.Enroll(ctx, a.ID, model.Email, "SECOND@example.com", "enroll", r.IP)
+		require.NoError(t, err)
+		code := driver.deliveries[len(driver.deliveries)-1].Code
+		require.Equal(t, "second@example.com", driver.deliveries[len(driver.deliveries)-1].Factor.Address)
+		settings, err := service.Settings(ctx, a.ID)
+		require.NoError(t, err)
+		require.Len(t, settings.Factors, 1)
+		settings, err = service.ConfirmEnrollment(ctx, a.ID, enroll.ID, code)
+		require.NoError(t, err)
+		require.Len(t, settings.Factors, 2)
+		require.Equal(t, "primary-email", settings.Preferred)
+		require.ErrorIs(t, service.Consume(ctx, a.ID, r.Scope, proof, action), merrors.ErrUnauthorized)
+		selected := settings.Factors[1].ID
+		change, err := service.BeginPreference(ctx, a.ID, selected, "preference", r.IP)
+		require.NoError(t, err)
+		d := driver.deliveries[len(driver.deliveries)-1]
+		require.Equal(t, a.Login, d.Factor.Address)
+		_, err = service.ConfirmPreference(ctx, a.ID, "primary-email", change.ID, d.Code)
+		require.ErrorIs(t, err, verification.ErrTokenNotFound)
+		settings, err = service.ConfirmPreference(ctx, a.ID, selected, change.ID, d.Code)
+		require.NoError(t, err)
+		require.Equal(t, selected, settings.Preferred)
+		next := request(a)
+		_, _ = begin(next)
+		require.Equal(t, "second@example.com", driver.deliveries[len(driver.deliveries)-1].Factor.Address)
+	})
+}

backend/product/twofactor/store/mongo.go

@@ -0,0 +1,53 @@
+package store
+
+import (
+	"context"
+	model "git.sendico.io/tech/sxchnge/product/twofactor/model"
+	db "git.sendico.io/tech/sxchnge/shared/database"
+	deps "git.sendico.io/tech/sxchnge/shared/database/dependencies"
+	ri "git.sendico.io/tech/sxchnge/shared/database/repository/index"
+	"git.sendico.io/tech/sxchnge/shared/database/template"
+	mlogger "git.sendico.io/tech/sxchnge/shared/logging"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type Store struct {
+	profiles   *template.DBImp[*model.Profile]
+	challenges *template.DBImp[*model.Record]
+}
+
+func Open(logger mlogger.Logger, factory db.Factory) (*Store, error) {
+	d, err := deps.ResolveDependencies(factory)
+	if err != nil {
+		return nil, err
+	}
+	s := &Store{profiles: template.Create[*model.Profile](logger, "two_factor_profiles", d.Database), challenges: template.Create[*model.Record](logger, "two_factor_challenges", d.Database)}
+	retention := int32(86400)
+	err = s.challenges.Repository.CreateIndex(&ri.Definition{Name: "two_factor_expiry", Keys: []ri.Key{{Field: "expiresAt", Sort: ri.Asc}}, TTL: &retention})
+	if err != nil {
+		return nil, err
+	}
+	return s, nil
+}
+func (s *Store) Profile(ctx context.Context, id bson.ObjectID) (*model.Profile, error) {
+	p := &model.Profile{}
+	err := s.profiles.Get(ctx, id, p)
+	return p, err
+}
+func (s *Store) CreateProfile(ctx context.Context, p *model.Profile) error {
+	return s.profiles.Create(ctx, p)
+}
+func (s *Store) UpdateProfile(ctx context.Context, p *model.Profile) error {
+	return s.profiles.Update(ctx, p)
+}
+func (s *Store) Challenge(ctx context.Context, id bson.ObjectID) (*model.Record, error) {
+	r := &model.Record{}
+	err := s.challenges.Get(ctx, id, r)
+	return r, err
+}
+func (s *Store) CreateChallenge(ctx context.Context, r *model.Record) error {
+	return s.challenges.Create(ctx, r)
+}
+func (s *Store) UpdateChallenge(ctx context.Context, r *model.Record) error {
+	return s.challenges.Update(ctx, r)
+}

backend/product/verification/model/verificaton.go

@@ -17,6 +17,9 @@ const (
 	PurposePasswordReset     VerificationPurpose = "password_reset"
 	PurposeMagicLogin        VerificationPurpose = "magic_login"
 	PurposeLogin             VerificationPurpose = "login"
+	PurposeFactorEnrollment  VerificationPurpose = "factor_enrollment"
+	PurposeFactorPreference  VerificationPurpose = "factor_preference"
+	PurposeFactorProof       VerificationPurpose = "factor_proof"
 	PurposePayout            VerificationPurpose = "payout"
 )
 
@@ -36,6 +39,12 @@ func VPFromString(s string) (VerificationPurpose, error) {
 		return PurposeMagicLogin, nil
 	case string(PurposeLogin):
 		return PurposeLogin, nil
+	case string(PurposeFactorEnrollment):
+		return PurposeFactorEnrollment, nil
+	case string(PurposeFactorPreference):
+		return PurposeFactorPreference, nil
+	case string(PurposeFactorProof):
+		return PurposeFactorProof, nil
 	case string(PurposePayout):
 		return PurposePayout, nil
 	default:

backend/product/verification/store/consume_logging.go

@@ -1,24 +1,13 @@
 package verification
 
 import (
+	"strings"
+
 	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"git.sendico.io/tech/sxchnge/shared/logging/fields"
 	"go.uber.org/zap"
-	"strings"
 )
 
-const hashPreviewChars = 12
-
-func hashPreview(value string) string {
-	if value == "" {
-		return ""
-	}
-	if len(value) <= hashPreviewChars {
-		return value
-	}
-	return value[:hashPreviewChars] + "..."
-}
-
 func tokenIsDigitsOnly(value string) bool {
 	if value == "" {
 		return false
@@ -38,7 +27,6 @@ func tokenStateFields(token *verificationmodel.VerificationToken) []zap.Field {
 		zap.String("token_purpose", string(token.Purpose)),
 		zap.Bool("token_has_target", strings.TrimSpace(token.Target) != ""),
 		zap.Bool("token_has_idempotency_key", token.IdempotencyKey != nil),
-		zap.String("token_verify_hash_prefix", hashPreview(token.VerifyTokenHash)),
 		zap.Bool("token_has_salt", token.Salt != nil),
 		zap.Bool("token_used", token.UsedAt != nil),
 		zap.Time("token_expires_at", token.ExpiresAt),
@@ -46,18 +34,12 @@ func tokenStateFields(token *verificationmodel.VerificationToken) []zap.Field {
 		zap.Bool("token_has_max_retries", token.MaxRetries != nil),
 	}
 
-	if token.Salt != nil {
-		fields = append(fields, zap.String("token_salt_prefix", hashPreview(*token.Salt)))
-	}
 	if token.UsedAt != nil {
 		fields = append(fields, zap.Time("token_used_at", *token.UsedAt))
 	}
 	if token.MaxRetries != nil {
 		fields = append(fields, zap.Int("token_max_retries", *token.MaxRetries))
 	}
-	if token.IdempotencyKey != nil {
-		fields = append(fields, zap.String("token_idempotency_key_prefix", hashPreview(*token.IdempotencyKey)))
-	}
 	if strings.TrimSpace(token.ContextRef) != "" {
 		fields = append(fields, zap.String("token_context_ref", token.ContextRef))
 	}

backend/product/verification/store/consume_lookup.go

@@ -3,8 +3,8 @@ package verification
 import (
 	"context"
 	"errors"
-	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	mutil "git.sendico.io/tech/sxchnge/shared/database/query"
 	"git.sendico.io/tech/sxchnge/shared/database/repository"
 	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
@@ -132,8 +132,6 @@ func (db *verificationDB) lookupConsumeOTPToken(
 			zap.Time("candidate_expires_at", token.ExpiresAt),
 			zap.Int("candidate_attempts", token.Attempts),
 			zap.Bool("candidate_has_max_retries", token.MaxRetries != nil),
-			zap.String("candidate_stored_hash_prefix", hashPreview(token.VerifyTokenHash)),
-			zap.String("candidate_computed_hash_prefix", hashPreview(hash)),
 			zap.Bool("candidate_match", match),
 		)
 		if match {

backend/product/verification/store/consume_scope.go

@@ -1,10 +1,10 @@
 package verification
 
 import (
-	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"strings"
 	"time"
 
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"git.sendico.io/tech/sxchnge/shared/database/repository"
 	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
 	"go.mongodb.org/mongo-driver/v2/bson"
@@ -72,7 +72,6 @@ func (scope consumeScope) startFields() []zap.Field {
 		zap.Int("raw_token_trimmed_len", len(scope.trimmedRawToken)),
 		zap.Bool("raw_token_digits_only", tokenIsDigitsOnly(scope.rawToken)),
 		zap.Bool("raw_token_has_edge_whitespace", scope.rawToken != scope.trimmedRawToken),
-		zap.String("raw_token_hash_prefix", hashPreview(tokenHash(scope.rawToken))),
 	)
 }
 

backend/product/verification/store/create.go

@@ -3,9 +3,9 @@ package verification
 import (
 	"context"
 	"errors"
-	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"time"
 
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"git.sendico.io/tech/sxchnge/shared/database/repository"
 	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
 	"git.sendico.io/tech/sxchnge/shared/errors"
@@ -21,7 +21,7 @@ func activeContextFilter(request *Request, now time.Time) builder.Query {
 	filters := []builder.Query{
 		repository.Filter("accountRef", request.AccountRef),
 		repository.Filter("purpose", request.Purpose),
-		repository.Filter("target", request.Target),
+		targetFilter(request.Target),
 		repository.Filter("usedAt", nil),
 		repository.Query().Comparison(repository.Field("expiresAt"), builder.Gt, now),
 	}
@@ -33,7 +33,7 @@ func cooldownActiveContextFilter(request *Request, now, cutoff time.Time) builde
 	filters := []builder.Query{
 		repository.Filter("accountRef", request.AccountRef),
 		repository.Filter("purpose", request.Purpose),
-		repository.Filter("target", request.Target),
+		targetFilter(request.Target),
 		repository.Filter("usedAt", nil),
 		repository.Query().Comparison(repository.Field("expiresAt"), builder.Gt, now),
 		repository.Query().Comparison(repository.Field("createdAt"), builder.Gt, cutoff),
@@ -140,7 +140,10 @@ func (db *verificationDB) CreateWithResult(
 		// Always store an idempotency key. Client keys enable replay; generated
 		// keys avoid null-key collisions on older Mongo indexes and keep
 		// transaction retries deterministic.
-		idempotencyKey = syntheticIdempotencyKey()
+		idempotencyKey, err = syntheticIdempotencyKey()
+		if err != nil {
+			return CreateResult{}, err
+		}
 		hasIdempotency = true
 	}
 
@@ -246,3 +249,12 @@ func (db *verificationDB) CreateWithResult(
 	createResult.VerificationToken = raw
 	return createResult, nil
 }
+
+// Older records omit an empty target; Mongo does not equate a missing field
+// with the empty string. Match both forms for cooldown, invalidation and replay.
+func targetFilter(target string) builder.Query {
+	if target != "" {
+		return repository.Filter("target", target)
+	}
+	return repository.Query().Or(repository.Filter("target", ""), repository.Filter("target", nil))
+}

backend/product/verification/store/idempotency.go

@@ -2,15 +2,16 @@ package verification
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/base64"
 	"errors"
-	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"strings"
 
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	mutil "git.sendico.io/tech/sxchnge/shared/database/query"
 	"git.sendico.io/tech/sxchnge/shared/database/repository"
 	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
 	"git.sendico.io/tech/sxchnge/shared/errors"
-	"go.mongodb.org/mongo-driver/v2/bson"
 )
 
 func normalizedIdempotencyKey(value *string) (string, bool) {
@@ -24,8 +25,12 @@ func normalizedIdempotencyKey(value *string) (string, bool) {
 	return key, true
 }
 
-func syntheticIdempotencyKey() string {
-	return "auto:" + bson.NewObjectID().Hex()
+func syntheticIdempotencyKey() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", merrors.InternalWrap(err, "generate verification key")
+	}
+	return "auto:" + base64.RawURLEncoding.EncodeToString(b), nil
 }
 
 func idempotencyContextFilter(
@@ -35,7 +40,7 @@ func idempotencyContextFilter(
 	return repository.Query().And(
 		repository.Filter("accountRef", request.AccountRef),
 		repository.Filter("purpose", request.Purpose),
-		repository.Filter("target", request.Target),
+		targetFilter(request.Target),
 		repository.Filter("idempotencyKey", idempotencyKey),
 	)
 }
@@ -75,6 +80,12 @@ func (db *verificationDB) lookupIdempotencyReplay(ctx context.Context, request *
 		if existingContextRef != request.ContextRef {
 			return nil, false, ErrorIdempotencyConflict()
 		}
+		if tokens[i].UsedAt != nil {
+			return nil, false, ErorrTokenAlreadyUsed()
+		}
+		if tokens[i].MaxRetries != nil && tokens[i].Attempts >= *tokens[i].MaxRetries {
+			return nil, false, ErrorTokenAttemptsExceeded()
+		}
 		if replayed == nil {
 			token := tokens[i]
 			replayed = &token

backend/product/verification/store/token_query_matcher_test.go

@@ -1,9 +1,9 @@
 package verification
 
 import (
-	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"time"
 
+	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"git.sendico.io/tech/sxchnge/shared/database/repository/builder"
 	"go.mongodb.org/mongo-driver/v2/bson"
 )
@@ -62,6 +62,18 @@ func matchBsonD(filter bson.D, tok *verificationmodel.VerificationToken) bool {
 
 func matchElem(elem bson.E, tok *verificationmodel.VerificationToken) bool {
 	switch elem.Key {
+	case "$or":
+		arr, ok := elem.Value.(bson.A)
+		if !ok {
+			return false
+		}
+		for _, sub := range arr {
+			d, ok := sub.(bson.D)
+			if ok && matchBsonD(d, tok) {
+				return true
+			}
+		}
+		return false
 	case "$and":
 		arr, ok := elem.Value.(bson.A)
 		if !ok {

backend/product/verification/store/verification_idempotency_test.go

@@ -3,12 +3,13 @@ package verification
 import (
 	"context"
 	"errors"
+	"testing"
+	"time"
+
 	verificationmodel "git.sendico.io/tech/sxchnge/product/verification/model"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.mongodb.org/mongo-driver/v2/bson"
-	"testing"
-	"time"
 )
 
 func TestCreate_CooldownBlocksCreation(t *testing.T) {
@@ -174,3 +175,16 @@ func TestCreate_IdempotencySurvivesCallbackRetry(t *testing.T) {
 	}
 	repo.mu.Unlock()
 }
+
+func TestCreateWithResultReplayCannotRedeliverConsumedCode(t *testing.T) {
+	db := newTestVerificationDB(t)
+	ctx := context.Background()
+	id := bson.NewObjectID()
+	r := NewOTPRequest(id, verificationmodel.PurposeLogin, "").WithIdempotencyKey("private-server-key").WithContextRef("login")
+	first, err := db.Create(ctx, r)
+	require.NoError(t, err)
+	_, err = db.Consume(ctx, id, verificationmodel.PurposeLogin, "login", first)
+	require.NoError(t, err)
+	_, err = db.CreateWithResult(ctx, r)
+	require.ErrorIs(t, err, ErrTokenAlreadyUsed)
+}

docs/architecture/two-factor.md

@@ -0,0 +1,156 @@
+# Second-factor service
+
+Task [#40](https://git.sendico.io/tech/sxchnge/issues/40),
+[PR #41](https://git.sendico.io/tech/sxchnge/pulls/41), branch `twofactor-40`.
+
+## Ownership
+
+`backend/product/twofactor` is a domain service inside the product executable.
+It owns verified factors, preferred delivery channels, challenge snapshots,
+issuance limits, code verification and single-use authorization proofs.
+Its domain has no dependency on auth HTTP, JWTs or sessions. Shared Mongo
+wrappers supply persistence and transactions; notifications only deliver messages.
+
+Auth verifies the password, account and client, creates a pending JWT bound to the
+client/device, and passes its hash as the login operation context. The service
+selects the account's verified preferred factor and returns a masked challenge.
+Auth calls `Complete` with the code and a callback that creates the session.
+The service verifies the code, issues and consumes a proof, and commits the
+callback's database changes in one transaction. Rejected guesses commit attempt
+counters; callback failures roll back the code, proof and session together.
+The HTTP response is written only after commit.
+
+`Verify` and `Consume` also support separate domain steps for an operation that
+needs a short-lived proof. Proofs bind the customer, purpose, operation and
+challenge; they expire within two minutes and never outlive the challenge.
+`Consume` checks the current profile and consumes the proof with the owner's
+callback. Callbacks must only use this shared Mongo transaction: no external I/O,
+response writes or irreversible side effects. Mongo may retry the callback.
+An eventual remote service would need an explicit distributed completion protocol;
+the callback contract cannot simply be translated into an RPC.
+
+Signup email activation remains in `auth/flow`, with separate purpose and link
+semantics. API-client secret login retains its existing separate behavior.
+No generic public endpoint can choose an arbitrary authorization purpose.
+
+## Sendico reuse
+
+The token engine is the existing locally owned copy in
+`backend/product/verification/store`. Its source is Sendico
+`S_I/sendico` commit `8bb20dcd622dd8eb92d289b6b34411e7eccab083`, already recorded
+in `backend/PROVENANCE.json` and `backend/PROVENANCE.md`. The new service uses
+`NewOTPRequest`, `NewLinkRequest`, `CreateWithResult`, `Consume`, context binding,
+idempotency, cooldown, max retries and issuance limits from that engine. It
+retains SXCHNGE's subsequent random-key, empty-target-query and safe-log fixes.
+No alternative OTP generator or token-consumption database was introduced.
+
+The committed Sendico handlers inspected under
+`api/edge/product/internal/server/verificationimp/` include `request.go`,
+`verify.go`, `sendcode.go`, `target.go`, `service.go`, `types.go` and `token.go`.
+They mix verification with session creation and private platform messaging and
+allow recipient resolution unsuitable for a verified-factor boundary. Those
+handlers were not copied. The orchestration, profile store, delivery interface
+and HTTP settings adapter are new local code. There is no Sendico runtime,
+private messaging or database dependency.
+
+## Factors and policy
+
+An active account's activated primary email is the initial verified factor.
+Profiles are persisted in `two_factor_profiles`; challenge snapshots in
+`two_factor_challenges` bind the chosen factor, locale, profile revision and
+operation deadline. Snapshots cannot redirect a code during resend. Profile
+changes invalidate outstanding challenges and proofs. A transactional profile
+write serializes proof consumption against concurrent preference changes.
+Challenge documents expire through a TTL index one day after their logical expiry;
+logical expiry is checked synchronously and does not depend on TTL cleanup.
+No existing customer migration is required: the initial profile is resolved
+from the verified account and persisted on first completed verification.
+
+Email is the installed channel driver. Users can enroll an additional email,
+prove ownership and select it. Selection requires a fresh code at the current
+preferred factor; enrollment alone cannot replace it. At most five factors
+(including the primary email) are enrolled. Registered drivers form the supported
+channel allow-list; unsupported or unavailable channels fail closed. There is no
+automatic fallback, disable endpoint, factor removal or account recovery flow.
+SMS, push, authenticator apps and passkeys require concrete implementations and
+client support before use. The Flutter settings screen is still the existing
+preview; these authenticated settings APIs are ready for a separate UI adapter.
+
+Login, payout and preference scopes are recognized internally. Payout integration
+is not added here; the payout owner must validate its immutable operation details
+and call this service. An auth proof cannot authorize money operations.
+
+## HTTP settings contract
+
+All routes below are under `/api/v1/accounts` and require an existing active
+account session through the standard `AccountHandler`. Pending login credentials
+cannot access them. Account identity and operation scope come from the server,
+not request fields. Responses use the existing `data` envelope and `no-store`.
+
+| Method/path | Body | Result (202) |
+| --- | --- | --- |
+| GET `/two-factor` | none | `required: true`, `preferred`, `factors: [{id, channel, target}]` |
+| POST `/two-factor/enroll` | `channel`, `address`, `idempotencyKey` | Challenge at the proposed address |
+| POST `/two-factor/enroll/verify` | `challengeId`, `code` | Settings after ownership verification |
+| POST `/two-factor/preference` | `factorId`, `idempotencyKey` | Challenge at the current preferred factor |
+| POST `/two-factor/preference/verify` | `factorId`, `challengeId`, `code` | Settings after preference changes |
+| POST `/two-factor/resend` | `challengeId`, `idempotencyKey` | Same settings operation and target, renewed code |
+
+Challenge responses contain `challengeId`, `channel`, masked `target`, `expiresAt`
+and `resendAt`. Login responses additionally include the pending JWT; login
+resend/verify now require both `challengeId` and `pendingToken`. Codes, raw proofs
+and full enrolled addresses are never returned in these responses.
+
+Codes expire within ten minutes with five guesses per issued code. New issuance
+uses a one-minute cooldown per challenge, plus shared fixed-window limits of five
+per customer and twenty per requesting IP per hour across purposes. New challenges
+cannot reset these delivery budgets. Same-key delivery retries recover the same
+code, notification key and expiry; notification enqueueing deduplicates them.
+A new accepted resend invalidates the prior code. A locked/expired operation must
+restart. Replaying a used code or proof cannot execute the callback again.
+
+## Rollout and recovery
+
+Load revision 1 of `twofactor.code` alongside `auth.activation` and `auth.login`
+from `backend/notifications/templates.example.json`; all have English/Russian
+variants. Existing notification TLS/caller configuration and the private signing
+key supply delivery and secret-derived issuance keys. No new service deployment
+or network credentials are required. Mongo must support transactions (replica set).
+The application creates the two new collections/index on startup.
+
+Deploy backend and Flutter contract changes together. Earlier pending login codes
+have no new challenge record and must restart password login after rollout.
+Existing sessions and activation links are preserved. Key rotation invalidates
+outstanding factor snapshots/proofs. Keep factors on an available driver when
+changing configured drivers; there is no silent fallback.
+
+A failed session write permits retrying the same code. A lost HTTP response after
+a successful commit cannot replay the operation: restart login. Enrollment and
+preference confirmation can be reconciled with GET settings after an ambiguous
+response. Tokens and challenges commit before notification Send; a product crash
+before Send still requires resend. No product delivery outbox or inbox receipts
+are claimed. No live emails were sent during tests.
+
+## Verification and observability
+
+Real Mongo tests cover failed delivery replay, scope/customer isolation, expiry,
+inactive accounts, attempts committed through outer transactions, proof replay,
+callback rollback, concurrent completion, enrollment and preference invalidation.
+The signup/login integration test exercises the new auth boundary. Transport
+checks reject caller identity/purpose/destination overrides. Architecture tests
+prevent the 2FA domain importing auth or sessions. Flutter adapter tests exercise
+server challenge binding, resend recovery and unsupported channels.
+
+Existing auth HTTP counters/timers and frontend journey events remain authoritative
+for login outcomes. Domain logs record queued challenges, rejected codes and
+completed operations with challenge IDs and purpose/channel, without codes,
+proofs, keys or destinations. Prepared proof logs are debug-level and do not
+represent a committed operation. See `docs/ux/auth-journeys.md` for attempt windows,
+retry/abandonment rules and the existing production analytics export gap.
+No new settings UI journey or production analytics sink is claimed.
+
+The UI composition is unchanged. The shared DTO/mapper/service adapter preserves
+masked delivery targets, provider error/retry handling and in-memory credential
+storage. Existing widget tests cover mobile forms, keyboard behavior, loading,
+cooldown and recovery; new adapter tests cover the changed backend contract.
+Required completion checks and delivery are recorded in `docs/implementation.md`.

docs/auth-notifications.md

@@ -0,0 +1,148 @@
+# Signup and login email integration
+
+Task [#38](https://git.sendico.io/tech/sxchnge/issues/38), [PR #39](https://git.sendico.io/tech/sxchnge/pulls/39), branch `auth-38`.
+Primary module: auth; secondary modules: notification templates and Flutter auth.
+The initial integration is merged. Task #40 separates login verification into
+the [second-factor service](architecture/two-factor.md).
+
+## Configuration
+
+Load the `auth.activation`, `auth.login` and `twofactor.code` revision 1 templates from
+`backend/notifications/templates.example.json` into the notification catalog.
+These templates have English and Russian variants; product account locale selects
+Russian for `ru` variants and English otherwise. Publish subsequent template
+changes under a new revision rather than mutating deployed content.
+
+Configure `api.notifications` in the product YAML:
+
+- `address`: internal notifications gRPC address.
+- `token_env`: environment variable containing the configured caller's token
+  (at least 32 bytes); example `SXCHNGE_NOTIFICATIONS_TOKEN`.
+- `ca_file`: trusted PEM CA bundle; omit to use system roots.
+- `server_name`: optional TLS certificate hostname override, never a TLS bypass.
+- `activation_url`: absolute frontend `/verify-email` URL. HTTPS is required,
+  except HTTP on localhost/127.0.0.1 for development. No user-supplied redirect is
+  accepted. The token is appended as a query parameter.
+
+The caller token must map to the product caller in the notification service's
+configuration. Keep Mongo, notification caller, TLS and provider credentials out
+of Git. JWT signing configuration must contain at least 32 bytes of private key
+material; HMAC-derived issuance keys depend on this key. Rotation changes replay
+keys and existing pending JWT validity. Omission of `api.notifications` preserves
+the bootstrap-only legacy routes; it does not enable signup or code completion.
+The example config enables the integration and therefore requires credentials.
+
+The notification service must be reachable over TLS, with its Mongo/NATS/email
+provider configured. Product startup creates a lazy gRPC channel; dependency
+outages appear as HTTP 503 when attempting delivery. A successful Send means
+persisted queue acceptance, not inbox delivery or a provider receipt.
+
+Start Flutter with:
+
+```sh
+flutter run --dart-define=SXCHNGE_API_URL=https://api.example/api/v1 \
+  --dart-define=SXCHNGE_CLIENT_ID=your-provisioned-public-client
+```
+
+Provision that client using the existing local application-client configuration
+workflow. Its ID must exist in the BFF's client store and allow the user's IP.
+Do not put a confidential client secret in Flutter. Match BFF CORS to the exact
+frontend origin. Browser requests use credentials, the existing CSRF headers,
+and Secure/HttpOnly/SameSite=Strict refresh cookies; deploy frontend and API on
+HTTPS origins within the same site. Native adapters retain credentials in memory.
+No API URL keeps the existing explicit preview services. With an API URL, auth
+is real, the preview shortcut is hidden, and workspace routes require the local
+confirmed session. Wallet, identity and factor-settings backend adapters remain
+outside this change; those screens still use their existing preview data. The
+real factor adapter refuses unsupported money/settings operations.
+
+## HTTP contract
+
+All paths have prefix `/api/v1/accounts`. Responses use the existing `data`
+envelope. Credentials, codes and activation tokens are sent in POST bodies.
+
+| Route | Request | Successful result |
+| --- | --- | --- |
+| POST `/signup` | `name`, `email`, `password`, `locale`, `idempotencyKey` | 202 with `userId`, after activation email queue acceptance |
+| POST `/verification/send` | `email`, `idempotencyKey` | 202; generic acceptance also applies to absent/already-active accounts |
+| POST `/verification/confirm` | `token` | 202 with `verified: true` after activation commits |
+| POST `/login` | `login: {login, password}`, `clientId`, `deviceId` | 202 with `userId`, `pendingToken: {token, expiration}`, `challengeId`, `channel`, masked `target`, `expiresAt`, `resendAt` |
+| POST `/login/resend` | `pendingToken`, `challengeId`, `idempotencyKey` | 202 with the challenge timing and same pending credential |
+| POST `/login/verify` | `pendingToken`, `challengeId`, six-digit `code` | 200 with account and existing access/refresh response |
+
+The pending JWT binds the customer, client and device. The verification record
+binds its code to a hash of that JWT. Password login does not create a session.
+The API-login client-secret endpoint retains its pre-existing separate behavior.
+Unverified customers cannot log in; Flutter routes them to verification recovery.
+Passwords preserve whitespace, matching signup hashing. Activation is single-use
+and commits the account transition with token consumption in one transaction.
+
+Login codes expire within 10 minutes and cannot outlive their pending JWT.
+Resending uses a one-minute cooldown, invalidates the previous code in that
+challenge, and allows five deliveries per customer and twenty per requesting IP per hour
+across second-factor purposes. Incorrect codes
+consume the existing five-attempt budget. Restart login after a pending credential
+expires or a challenge locks. Signup/resend request limits also apply per email
+(10/hour) and IP (30/hour), using shared atomic fixed-window counters.
+
+New idempotency keys are server-secret-derived before token generation. Automatic
+verification keys now use 32 cryptographically random bytes. Empty-target queries
+match both omitted and empty-string stored fields, fixing Mongo cooldown,
+invalidation and replay semantics without rewriting existing documents.
+Consumed or locked records cannot be replayed to redeliver an unusable code.
+Token/hash/salt/key previews are excluded from verification logs.
+
+## Recovery and delivery limits
+
+A resend retries its same idempotency key after a failed/ambiguous RPC. Token
+replay reconstructs the same code/link and stored expiry, and notification Send
+deduplicates the same payload. A new accepted resend gets a new key. A failed
+initial signup leaves the account pending; retry the same credentials or request
+another activation email after cooldown. Initial signup and password-login
+retries can create replacement messages; they are not distributed exactly-once
+operations. Tokens are stored before the RPC, so a process crash between those
+steps requires user recovery; there is no product-side delivery outbox.
+
+Code verification, one-use proof consumption and session creation now commit in
+one transaction. A session-write failure leaves the code retryable; a lost HTTP
+response after commit requires restarting password login. The adapter
+retains a confirmed session in memory and has no refresh/restore-on-reload flow
+in this contribution. Backend authorization remains authoritative for future
+protected APIs. Notification provider failures after queue acceptance are visible
+in the notification service; no inbox/delivery-receipt status is claimed here.
+No live emails were sent during implementation tests.
+
+## Measurement and UX review
+
+Existing `InstrumentedAuthServices`, `JourneyRecorder`, and factor providers track
+signup, initial email acceptance, confirmation, login challenge verification,
+completion, failure, retry, and navigation abandonment. Requests retain the
+existing journey correlation and timeout rules in `docs/ux/auth-journeys.md`.
+The initial confirmation-page send consumes the signup queue receipt once to
+avoid sending a duplicate email. Success is based on backend acceptance or
+verification, with `simulated: false`; it never means an inbox receipt.
+
+Backend metrics `sxchnge_auth_flow_requests_total{operation,outcome}` and
+`sxchnge_auth_flow_duration_seconds{operation}` expose accepted, rejected, limited
+and unavailable HTTP steps without email, tokens or account labels. Combine
+login-verify acceptance with login requests to inspect completion and dependency
+failures. Counts are HTTP attempts, so retries are not distinct users. The current
+frontend analytics sink is still the existing injected/default preview sink;
+a production sink and cross-device confirmation correlation remain deployment
+work. Do not interpret default in-memory analytics as retained production data.
+
+UX checks cover unchanged mobile/keyboard form composition, preserved input after
+errors, loading and cooldown feedback, invalid/expired/locked code recovery,
+unverified-account recovery, and English/Russian copy. Queue feedback is phrased
+conditionally because absent/already-active emails deliberately receive the same
+acceptance response. Auth credentials are absent from provider state, analytics,
+URLs (except the existing activation link) and local persistent storage. Existing
+widget suites cover screen behavior; new adapter tests cover real response state
+mapping, duplicate initial delivery, failures and one-use completion grants.
+
+## Validation
+
+Required validation: `make test` (including `make test-frontend`),
+`make lint-backend`, Dart format checks for every changed Dart file,
+and `flutter analyze` in `frontend/packages/sxchnge_auth` and `frontend/app`.
+Results and the delivery PR are recorded in `docs/implementation.md` and task #38.

docs/implementation.md

@@ -497,3 +497,89 @@ in [PR #35](https://git.sendico.io/tech/sxchnge/pulls/35), which remains unmerge
   an isolated clean checkout containing this contribution. Shared-workspace runs
   initially failed because concurrent product/auth work had missing module
   dependencies and unformatted files; that work was excluded and left untouched.
+
+## Signup and login notifications (#38)
+
+Task [#38](https://git.sendico.io/tech/sxchnge/issues/38), branch `auth-38`.
+Added signup/activation and login-code routes using the local customer,
+verification and session stores, with a TLS-authenticated adapter to the
+notifications interface module. English/Russian email templates and Flutter
+DTO/mapper/service adapters preserve provider/UI boundaries. Backend mode hides
+the preview shortcut and requires confirmed login for workspace navigation;
+unverified accounts go to email recovery.
+
+Review fixed real Mongo empty-target matching for cooldown/invalidation/replay,
+replaced predictable automatic verification keys with cryptographic randomness,
+removed token/hash/key previews from verification logging, bounded resend expiry
+by the pending JWT, preserved password whitespace and prevented consumed-code
+redelivery. Structured flow outcomes and latency metrics supplement existing
+journey instrumentation. Generated localization files are now ignored/untracked;
+`make test-frontend` regenerates them from ARB sources before tests.
+
+Validation passed: `make test` (Go race tests and all frontend suites),
+`make lint-backend`, `flutter analyze` in both `frontend/packages/sxchnge_auth`
+and `frontend/app`, and Dart format verification for all 17 changed hand-written
+Dart files. Tests include a real Mongo signup/activation/login journey, caller
+TLS authentication, unavailable delivery, invalid/single-use codes, immutable
+resend payloads, Flutter adapter/session mapping, unverified-account recovery,
+and backend-mode route gating. Initial failures in query-test OR support,
+localized-copy expectations and formatting were fixed and the checks rerun.
+No live email or optional security scan was run.
+
+See [configuration, contracts, UX evidence and recovery limits](auth-notifications.md).
+Queue acceptance is not inbox delivery. Product-side crashes before Send require
+user resend; initial signup/login retries are not exactly-once operations.
+Session response failures require restarting login. Session restore/refresh,
+production analytics export and wallet/settings backend adapters remain outside
+this contribution. Configure notification credentials/TLS/templates and the
+frontend API URL/public client before enabling real auth.
+
+
+Delivered in [PR #39](https://git.sendico.io/tech/sxchnge/pulls/39). Merge order: #35 → #37 → #39. The auth branch incorporates notification completion commit `4b14649`; only the delivery-log append conflicted, and both task records are preserved.
+
+## Dedicated second-factor service (#40)
+
+Task [#40](https://git.sendico.io/tech/sxchnge/issues/40), branch `twofactor-40`,
+based on main after merged PR #39. Primary module: twofactor; secondary modules:
+auth, verification purpose definitions, notification templates and Flutter auth.
+
+`product/twofactor` now owns challenge issuance/delivery, verified destinations,
+preferences, attempt/cooldown limits and single-use proofs. It reuses the
+Sendico-derived verification store at the existing pinned revision. No new
+Sendico handler or private messaging code was copied. Auth owns credentials,
+pending JWTs and session creation; signup activation remains in `auth/flow`.
+The service's `Complete` transaction commits code verification, proof consumption
+and the owner's session write together. Review fixed rejected-attempt rollback,
+ensured failed session writes preserve retryability, retained activation replay
+key compatibility and removed the unused verification-store injection from auth
+HTTP. A profile write serializes consumption against preference changes.
+
+Authenticated APIs enroll additional verified emails and change the preferred
+factor only after verifying the current factor. Unsupported channels fail closed.
+Flutter's shared DTO/mapper/service adapter sends the server challenge ID with
+the pending JWT, preserves resend keys after failure and rejects unknown channels.
+No widgets or provider/analytics boundaries changed. Existing login journey
+measurement and error/recovery UI remain in use; settings UI integration is not
+part of this separation.
+
+Validation passed: `make test` (all Go race suites and `make test-frontend`),
+`make lint-backend`, `flutter analyze` in `frontend/packages/sxchnge_auth`, and
+Dart format verification for all four changed Dart files. New real Mongo tests
+cover single-use proofs, customer/purpose/context isolation, delivery retries,
+committed failed guesses, expiry, inactive accounts, operation rollback,
+concurrent completion, verified enrollment, preference selection and old-proof
+invalidation. The updated signup/login test covers the full auth boundary;
+transport and architecture tests cover scope injection and domain dependencies.
+Frontend tests cover challenge binding, resend recovery and unsupported channels.
+No live email or optional security scan was run.
+
+See [ownership, Sendico provenance, HTTP contract and rollout](architecture/two-factor.md).
+Deploy backend and client together, load `twofactor.code` revision 1, and restart
+previously pending logins after rollout. Email is the implemented channel.
+Existing settings screens still use preview adapters; SMS/push/TOTP/passkeys,
+factor removal/recovery, payout integration and a separate process are not
+implemented. Successful-commit response loss still requires login restart;
+notification queue acceptance is not inbox delivery.
+
+Delivered in [PR #41](https://git.sendico.io/tech/sxchnge/pulls/41) against `main`.
+Branch `twofactor-40` is pushed. The PR is left open for review; no merge was performed.

frontend/app/.gitignore

@@ -46,3 +46,6 @@ app.*.map.json
 
 # Widget Preview related
 .widget_preview/
+
+# Localization bindings are regenerated from ARB sources.
+/lib/generated/i18n/

frontend/app/README.md

@@ -32,7 +32,7 @@ From the repository root, `make test-frontend` runs both theme suites and the ap
 
 ## English and Russian
 
-Localization follows Sendico's Flutter pattern: `lib/l10n/en.arb` is the template, `ru.arb` contains Russian translations, and `flutter gen-l10n` writes `lib/generated/i18n/`. Edit ARB files, not generated Dart files. Flutter's Material and Cupertino localizations are included through the generated delegates.
+Localization follows Sendico's Flutter pattern: `lib/l10n/en.arb` is the template, `ru.arb` contains Russian translations, and `flutter gen-l10n` writes `lib/generated/i18n/`. Generated Dart files are ignored and untracked. Run `flutter gen-l10n` after a clean checkout and after editing ARB files; `make test-frontend` runs it before tests. Edit ARB files, not generated Dart files. Flutter's Material and Cupertino localizations are included through the generated delegates.
 
 The language dropdown is available in both authentication modes. Startup reads `sxchnge_last_locale` using shared preferences; without a saved choice it uses the device language. Russian regional variants resolve to Russian and unsupported languages fall back to English. Preference writes are serialized, and storage failures leave the selected language usable for the current session with a localized notice. Only the language preference is stored; credentials remain transient.
 

frontend/app/lib/auth/feedback.dart

@@ -19,6 +19,7 @@ class AuthFeedback extends StatelessWidget {
               ? (signUp ? l.signupPreview : l.loginPreview)
               : l.authCompleted)
         : switch (error) {
+            AuthError.accountNotVerified => l.authVerifyEmail,
             AuthError.invalidCredentials => l.authInvalidCredentials,
             AuthError.emailInUse => l.authEmailInUse,
             AuthError.unavailable => l.authUnavailable,

frontend/app/lib/auth/form.dart

@@ -104,6 +104,11 @@ class _AuthFormState extends State<AuthForm> {
         locale: locale,
       );
       if (!mounted || _signUp) return;
+      if (login.state.error == AuthError.accountNotVerified) {
+        _password.clear();
+        context.goNamed(AppRoutes.verificationSent, extra: _email.text.trim());
+        return;
+      }
       final challenge = login.state.result?.challenge;
       if (challenge != null) {
         _password.clear();
@@ -329,10 +334,11 @@ class _AuthFormState extends State<AuthForm> {
           AuthFeedback(state: state, signUp: _signUp),
         ],
         const SizedBox(height: 20),
-        TextButton(
-          onPressed: () => context.go('/accounts'),
-          child: Text(l.wEnter),
-        ),
+        if (context.read<TwoFactorService>().isSimulated)
+          TextButton(
+            onPressed: () => context.go('/accounts'),
+            child: Text(l.wEnter),
+          ),
         Wrap(
           alignment: WrapAlignment.center,
           crossAxisAlignment: WrapCrossAlignment.center,

frontend/app/lib/generated/i18n/app_localizations_en.dart

@@ -1,860 +0,0 @@
-// ignore: unused_import
-import 'package:intl/intl.dart' as intl;
-
-import 'app_localizations.dart';
-
-// ignore_for_file: type=lint
-
-/// The translations for English (`en`).
-class AppLocalizationsEn extends AppLocalizations {
-  AppLocalizationsEn([String locale = 'en']) : super(locale);
-
-  @override
-  String get appTitle => 'SXCHNGE · Your next move';
-
-  @override
-  String get nextChapter => 'YOUR NEXT CHAPTER';
-
-  @override
-  String get loginHeading => 'Hey, welcome\nback.';
-
-  @override
-  String get signupHeading => 'Make your\nfirst move.';
-
-  @override
-  String get loginIntro => 'Your next move is just a login away.';
-
-  @override
-  String get signupIntro => 'A new account. A world of possibility.';
-
-  @override
-  String get login => 'Log in';
-
-  @override
-  String get signup => 'Sign up';
-
-  @override
-  String get name => 'Your name';
-
-  @override
-  String get email => 'Email address';
-
-  @override
-  String get emailHint => 'you@example.com';
-
-  @override
-  String get password => 'Password';
-
-  @override
-  String get confirmPassword => 'Confirm password';
-
-  @override
-  String get passwordHint => 'Use at least 12 characters.';
-
-  @override
-  String get showPassword => 'Show password';
-
-  @override
-  String get hidePassword => 'Hide password';
-
-  @override
-  String get showConfirmation => 'Show confirmation';
-
-  @override
-  String get hideConfirmation => 'Hide confirmation';
-
-  @override
-  String get createAccount => 'Create account';
-
-  @override
-  String get letsGo => 'Let’s go';
-
-  @override
-  String get loginPreview => 'You’re signed in.';
-
-  @override
-  String get signupPreview => 'Your account is ready.';
-
-  @override
-  String get alreadyMember => 'Already part of sxchnge?';
-
-  @override
-  String get newHere => 'New around here?';
-
-  @override
-  String get loginInstead => 'Log in instead';
-
-  @override
-  String get createAnAccount => 'Create an account';
-
-  @override
-  String get brandEyebrow => 'A LITTLE CHANGE. A BIG NEXT STEP.';
-
-  @override
-  String get brandHeading => 'Good moves.\nStart here.';
-
-  @override
-  String get brandIntro => 'A fresh way forward.\nMake it yours with sxchnge.';
-
-  @override
-  String get brandCard => 'Less friction.\nMore possibility.';
-
-  @override
-  String get brandFooter => 'YOUR NEXT MOVE STARTS WITH YOU.';
-
-  @override
-  String get emailRequired => 'Enter your email address.';
-
-  @override
-  String get emailInvalid => 'Enter a valid email address.';
-
-  @override
-  String get nameRequired => 'Enter your name.';
-
-  @override
-  String get passwordRequired => 'Enter your password.';
-
-  @override
-  String get confirmationRequired => 'Confirm your password.';
-
-  @override
-  String get passwordMismatch => 'Passwords do not match.';
-
-  @override
-  String get language => 'Language';
-
-  @override
-  String get preferenceNotSaved =>
-      'Language changed for this session. Your preference could not be saved.';
-
-  @override
-  String get authWorking => 'Please wait…';
-
-  @override
-  String get authCompleted => 'Request completed.';
-
-  @override
-  String get authInvalidCredentials =>
-      'Email or password is incorrect. Please try again.';
-
-  @override
-  String get authEmailInUse =>
-      'This email is already registered. Try logging in.';
-
-  @override
-  String get authUnavailable => 'The service is unavailable. Please try again.';
-
-  @override
-  String get authUnexpected => 'Something went wrong. Please try again.';
-
-  @override
-  String get checkInbox => 'Check your inbox.';
-
-  @override
-  String get verificationSent =>
-      'We’ve sent you a verification email. Open the link in your inbox to confirm your email address.';
-
-  @override
-  String get verificationSending => 'Preparing your verification email…';
-
-  @override
-  String get verificationChecking => 'Verifying your email…';
-
-  @override
-  String get verificationVerified => 'Your email\nis verified.';
-
-  @override
-  String get verificationVerifiedBody =>
-      'One step done. You can now return to login. Identity verification is a separate step.';
-
-  @override
-  String get verificationExpired => 'This link has expired.';
-
-  @override
-  String get verificationExpiredBody =>
-      'Request a new verification email and use the latest link.';
-
-  @override
-  String get verificationInvalid => 'This link isn’t valid.';
-
-  @override
-  String get verificationInvalidBody =>
-      'The confirmation link is missing or invalid. Open the complete link from your email, or request a new one.';
-
-  @override
-  String get verificationInternal => 'Something went wrong.';
-
-  @override
-  String get verificationInternalBody =>
-      'We couldn’t complete your request because of an internal error. Please try again.';
-
-  @override
-  String get verificationResend => 'Resend verification email';
-
-  @override
-  String get verificationRequest => 'Send a new verification email';
-
-  @override
-  String get verificationRetry => 'Retry verification';
-
-  @override
-  String get verificationBack => 'Back to login';
-
-  @override
-  String get verificationHint =>
-      'No email? Check your spam folder or request another below.';
-
-  @override
-  String get verificationDemoLink => 'Continue to confirmation';
-
-  @override
-  String get verificationStep => 'CONFIRM YOUR EMAIL';
-
-  @override
-  String get verificationRecipient => 'Recipient';
-
-  @override
-  String get verificationChangeEmail => 'Change email';
-
-  @override
-  String get kycTitle => 'Verification & limits';
-
-  @override
-  String get kycIntro =>
-      'Your account, at your pace. Verify your identity when you need higher limits.';
-
-  @override
-  String get kycUnverified => 'Not verified';
-
-  @override
-  String get kycPending => 'In review';
-
-  @override
-  String get kycApproved => 'Identity verified';
-
-  @override
-  String get kycChanges => 'New photos needed';
-
-  @override
-  String get kycDenied => 'Verification declined';
-
-  @override
-  String get kycUnverifiedBody =>
-      'You can keep using your account with basic limits. Submit a passport photo and a selfie holding it to request an upgrade.';
-
-  @override
-  String get kycPendingBody =>
-      'Your submission is awaiting a human review. Basic limits remain active until approval. You do not need to submit again.';
-
-  @override
-  String get kycApprovedBody =>
-      'Your review is complete. Check your current limits below.';
-
-  @override
-  String get kycChangesBody =>
-      'Your account remains available with basic limits. Replace the photos and submit a new review request.';
-
-  @override
-  String get kycDeniedBody =>
-      'Basic limits remain available. If you believe this decision is incorrect, contact support for a review.';
-
-  @override
-  String get kycPassportReason =>
-      'The passport details could not be read. Retake the photo in good light, with every edge visible.';
-
-  @override
-  String get kycSelfieReason =>
-      'Your face or passport was not clear in the selfie. Keep both visible and in focus.';
-
-  @override
-  String get kycExpiredReason =>
-      'The passport has expired. Use a valid passport and take both photos again.';
-
-  @override
-  String get kycDeniedReason =>
-      'We could not verify your identity from this submission.';
-
-  @override
-  String get kycStart => 'Verify identity';
-
-  @override
-  String get kycResubmit => 'Replace photos';
-
-  @override
-  String get kycRefresh => 'Refresh status & limits';
-
-  @override
-  String get kycSupport => 'Contact support';
-
-  @override
-  String get kycSupportBody =>
-      'Support is currently unavailable. Please try again later.';
-
-  @override
-  String get kycBasic => 'Basic';
-
-  @override
-  String get kycVerifiedTier => 'Verified';
-
-  @override
-  String get kycLimits => 'Your limits';
-
-  @override
-  String get kycDay => 'Daily volume';
-
-  @override
-  String get kycMonth => 'Monthly volume';
-
-  @override
-  String get kycCurrent => 'Current cap';
-
-  @override
-  String get kycRemaining => 'Available';
-
-  @override
-  String get kycAfter => 'After approval';
-
-  @override
-  String get kycLimitsError =>
-      'Limits could not be refreshed. Any values below are out of date. Retry to see your current access.';
-
-  @override
-  String get kycLimitsEmpty =>
-      'No limits were returned. Refresh or check with support before making a transaction.';
-
-  @override
-  String get kycLoading => 'Loading your status…';
-
-  @override
-  String get kycPassport => 'Passport photo';
-
-  @override
-  String get kycSelfie => 'Selfie with passport';
-
-  @override
-  String get kycReview => 'Review your photos';
-
-  @override
-  String get kycPassportHelp =>
-      'Open your valid passport to the photo page. Show all four edges and keep text sharp. Avoid glare, blur and covered details.';
-
-  @override
-  String get kycSelfieHelp =>
-      'Hold the open passport beside your face. Show your whole face and the photo page in the same image. Keep both sharp and uncovered.';
-
-  @override
-  String get kycFileRules =>
-      'JPEG or PNG · up to 10 MB · at least 600 × 600 pixels. Take a photo with your camera, then choose it here.';
-
-  @override
-  String get kycChoose => 'Choose photo';
-
-  @override
-  String get kycReplace => 'Choose a different photo';
-
-  @override
-  String get kycRemove => 'Remove photo';
-
-  @override
-  String get kycNext => 'Continue';
-
-  @override
-  String get kycBack => 'Back';
-
-  @override
-  String get kycSkip => 'Keep basic limits';
-
-  @override
-  String get kycClose => 'Back to account';
-
-  @override
-  String get kycReviewHelp =>
-      'Check that both photos are readable and show the same passport. A staff member will review them; submission does not immediately raise your limits.';
-
-  @override
-  String get kycConfirm => 'These photos show me and my own valid passport.';
-
-  @override
-  String get kycSubmit => 'Submit for review';
-
-  @override
-  String get kycWorking => 'Processing… Please keep this page open.';
-
-  @override
-  String get kycDiscardTitle => 'Discard these photos?';
-
-  @override
-  String get kycDiscardBody =>
-      'Your draft is only in memory. Leaving will remove the selected photos; you can start again later.';
-
-  @override
-  String get kycStay => 'Keep editing';
-
-  @override
-  String get kycDiscard => 'Discard & leave';
-
-  @override
-  String get kycErrorUnavailable =>
-      'The service is unavailable. Your selected photos are still here. Try again.';
-
-  @override
-  String get kycErrorInternal =>
-      'Something went wrong. Try again; your selected photos have been kept.';
-
-  @override
-  String get kycErrorPermission =>
-      'We could not open that photo. Check file access or choose another image.';
-
-  @override
-  String get kycErrorFormat =>
-      'Choose a JPEG or PNG image. Other formats are not supported.';
-
-  @override
-  String get kycErrorLarge =>
-      'This image is too large. Choose one under 10 MB and 40 megapixels.';
-
-  @override
-  String get kycErrorUnreadable =>
-      'This image is damaged or cannot be read. Choose another photo.';
-
-  @override
-  String get kycErrorSmall =>
-      'The photo is too small. Use an image at least 600 pixels wide and high.';
-
-  @override
-  String get kycErrorIncomplete =>
-      'Choose both photos and confirm they belong to you before submitting.';
-
-  @override
-  String get kycErrorSession =>
-      'Your session has expired. Return to login, then check your verification status.';
-
-  @override
-  String get kycErrorRate =>
-      'Too many requests. Wait a moment before trying again.';
-
-  @override
-  String get kycErrorConflict =>
-      'Your review status has changed. Refresh it before continuing.';
-
-  @override
-  String get kycDemoControls => 'Review scenarios';
-
-  @override
-  String get kycDemoApprove => 'Approve';
-
-  @override
-  String get kycDemoCorrect => 'Request clearer passport';
-
-  @override
-  String get kycDemoSelfie => 'Request clearer selfie';
-
-  @override
-  String get kycDemoExpired => 'Passport expired';
-
-  @override
-  String get kycDemoDeny => 'Decline';
-
-  @override
-  String get kycPreview => 'Explore verification & limits';
-
-  @override
-  String get kycChooseFirst => 'Choose a photo to continue.';
-
-  @override
-  String get kycStatusStale =>
-      'Status could not be refreshed. The status shown is the last known result.';
-
-  @override
-  String get kycUsed => 'Used';
-
-  @override
-  String get kycReserved => 'Reserved';
-
-  @override
-  String get kycUsageHelp =>
-      'Used is completed activity. Reserved is held for pending transactions. Both count toward your limit.';
-
-  @override
-  String get kycOccupied => 'Used + reserved';
-
-  @override
-  String get kycNoCapacity => 'No capacity available';
-
-  @override
-  String get wAccounts => 'Accounts';
-
-  @override
-  String get wActivity => 'Activity';
-
-  @override
-  String get wLimits => 'Limits';
-
-  @override
-  String get wSettings => 'Settings';
-
-  @override
-  String get wHeadline => 'Your money.\nYour next move.';
-
-  @override
-  String get wSubheading => 'Top up. Exchange. Go further.';
-
-  @override
-  String get wAvailable => 'Available to you';
-
-  @override
-  String get wTopUp => 'Top up';
-
-  @override
-  String get wExchange => 'Exchange';
-
-  @override
-  String get wPayout => 'Pay out';
-
-  @override
-  String get wRecent => 'Recent activity';
-
-  @override
-  String get wSeeAll => 'See all';
-
-  @override
-  String get wEmptyActivity =>
-      'Your next move starts here. Your transactions will appear below.';
-
-  @override
-  String get wEmptyAccounts =>
-      'Your accounts are not ready yet. Try refreshing.';
-
-  @override
-  String get wRefresh => 'Refresh';
-
-  @override
-  String get wSource => 'From account';
-
-  @override
-  String get wDestination => 'To account';
-
-  @override
-  String get wReceiveAccount => 'Receiving account';
-
-  @override
-  String get wAmount => 'Amount';
-
-  @override
-  String get wRecipient => 'Recipient';
-
-  @override
-  String get wRecipientHint => 'Recipient name or reference';
-
-  @override
-  String get wReview => 'Review';
-
-  @override
-  String get wReviewTitle => 'One last look.';
-
-  @override
-  String get wFee => 'Fee';
-
-  @override
-  String get wTotalDebit => 'Leaves your account';
-
-  @override
-  String get wCredit => 'Arrives in your account';
-
-  @override
-  String get wRecipientGets => 'Recipient receives';
-
-  @override
-  String get wYouPay => 'You pay';
-
-  @override
-  String get wRate => 'Exchange rate';
-
-  @override
-  String get wQuoteNotice =>
-      'These terms are valid for 60 seconds. Confirm them before continuing.';
-
-  @override
-  String get wExpired =>
-      'This quote expired. Refresh it and review the new terms.';
-
-  @override
-  String get wNewQuote => 'Refresh quote';
-
-  @override
-  String get wConfirm => 'Confirm transaction';
-
-  @override
-  String get wEdit => 'Edit details';
-
-  @override
-  String get wClose => 'Close';
-
-  @override
-  String get wWorking => 'Working on it…';
-
-  @override
-  String get wPending => 'Processing';
-
-  @override
-  String get wCompleted => 'Completed';
-
-  @override
-  String get wFailed => 'Not completed';
-
-  @override
-  String get wPendingTopUp =>
-      'Your top-up is processing. Your available balance has not changed yet.';
-
-  @override
-  String get wPendingExchange =>
-      'The amount and fee have left your available balance. The exchanged amount will appear in the receiving account when completed.';
-
-  @override
-  String get wPendingPayout =>
-      'The amount and fee have left your available balance. The payout is still processing.';
-
-  @override
-  String get wCompleteTopUp =>
-      'Your account has been credited. The money is available to use.';
-
-  @override
-  String get wCompleteExchange =>
-      'Your exchange is complete. The money is available in the receiving account.';
-
-  @override
-  String get wCompletePayout =>
-      'Your payout is complete. The amount and fee have been deducted from your account.';
-
-  @override
-  String get wFailedTopUp =>
-      'The top-up did not complete. No money was added to your account.';
-
-  @override
-  String get wFailedOutgoing =>
-      'The transaction did not complete. The amount and fee are available in your account again.';
-
-  @override
-  String get wUnavailable =>
-      'Could not refresh. The displayed information may be out of date. Try again.';
-
-  @override
-  String get wInvalidAmount =>
-      'Enter an amount greater than zero, using the currency’s decimal precision.';
-
-  @override
-  String get wInsufficient =>
-      'Not enough available money for this amount and fee. Top up or enter a smaller amount.';
-
-  @override
-  String get wLimitError =>
-      'This amount exceeds your available limit. Check your limits before continuing.';
-
-  @override
-  String get wRecipientError =>
-      'Enter a sample recipient between 6 and 140 characters.';
-
-  @override
-  String get wUnsupported =>
-      'This combination is unavailable. Choose another account.';
-
-  @override
-  String get wNotFound =>
-      'This item could not be found. Return to your accounts.';
-
-  @override
-  String get wUncertain =>
-      'We could not confirm the outcome. Check it before trying another transaction.';
-
-  @override
-  String get wCheckOutcome => 'Check outcome';
-
-  @override
-  String get wNoSubmission =>
-      'No transaction was found. You can review and confirm again.';
-
-  @override
-  String get wDiscardTitle => 'Leave this transaction?';
-
-  @override
-  String get wDiscardBody =>
-      'Your entered details will be cleared. No new transaction will be submitted.';
-
-  @override
-  String get wStay => 'Keep editing';
-
-  @override
-  String get wAll => 'All';
-
-  @override
-  String get wSearch => 'Search by reference';
-
-  @override
-  String get wNoMatches => 'No matching transactions. Try another filter.';
-
-  @override
-  String get wClearFilters => 'Clear filters';
-
-  @override
-  String get wReference => 'Reference';
-
-  @override
-  String get wWhen => 'Created';
-
-  @override
-  String get wViewAccount => 'View account';
-
-  @override
-  String get wPreferences => 'Make it yours.';
-
-  @override
-  String get wLanguage => 'Account language';
-
-  @override
-  String get wLanguageHelp => 'Used throughout your account.';
-
-  @override
-  String get wLanguageSaved => 'Saved to your account.';
-
-  @override
-  String get wLanguageFailed =>
-      'Changed for this session, but not saved to your account. Retry below.';
-
-  @override
-  String get wProfileError =>
-      'Account preferences could not be loaded. Try again.';
-
-  @override
-  String get wSecurity => 'Security';
-
-  @override
-  String get wSecurityBody =>
-      'Password and security settings are not available yet.';
-
-  @override
-  String get wIdentity => 'Identity verification';
-
-  @override
-  String get wIdentityHelp => 'Optional verification for higher limits.';
-
-  @override
-  String get wBackLogin => 'Back to login';
-
-  @override
-  String get wEnter => 'Explore your accounts';
-
-  @override
-  String get wUsage => 'Used this period';
-
-  @override
-  String get wLimitsScope => 'Outgoing activity · EUR equivalent';
-
-  @override
-  String get wPendingHint =>
-      'Refresh to check the latest status. You can keep using your other accounts.';
-
-  @override
-  String get wFundsHeading => 'Where is my money?';
-
-  @override
-  String get wAnother => 'Make another transaction';
-
-  @override
-  String get factorTitle => 'One more check.';
-
-  @override
-  String get factorLogin => 'Confirm it’s you to finish signing in.';
-
-  @override
-  String get factorMoney =>
-      'Confirm this transaction. No money moves before confirmation.';
-
-  @override
-  String get factorEnableHelp =>
-      'Confirm to turn on two-factor verification for sign-in and money operations.';
-
-  @override
-  String get factorDisableHelp =>
-      'Confirm to turn off two-factor verification. Sign-in and money operations will no longer ask for a second code.';
-
-  @override
-  String get factorEmail => 'Enter the six-digit code sent to your email.';
-
-  @override
-  String get factorAuthenticator =>
-      'Enter the current six-digit code from your authenticator app.';
-
-  @override
-  String get factorCode => 'Verification code';
-
-  @override
-  String get factorConfirm => 'Verify and continue';
-
-  @override
-  String get factorResend => 'Send a new code';
-
-  @override
-  String get factorHelp =>
-      'Check your inbox and spam folder. A new code replaces the previous one.';
-
-  @override
-  String get factorAppHelp =>
-      'Use the current code. If you cannot access your authenticator, cancel this action.';
-
-  @override
-  String get factorInvalid =>
-      'That code is not valid. Check all six digits and try again.';
-
-  @override
-  String get factorExpired =>
-      'This verification has expired. Request a new code or return to start again.';
-
-  @override
-  String get factorLocked =>
-      'Too many incorrect attempts. Wait five minutes, then start verification again.';
-
-  @override
-  String get factorWait => 'Please wait before requesting another code.';
-
-  @override
-  String get factorRequired =>
-      'Verification is needed again. Please confirm this action once more.';
-
-  @override
-  String get factorUnavailable =>
-      'Could not complete verification. Try again or cancel this action.';
-
-  @override
-  String factorCooldown(int seconds) {
-    return 'Send a new code in ${seconds}s';
-  }
-
-  @override
-  String get factorSettings => 'Two-factor verification';
-
-  @override
-  String get factorSettingsHelp =>
-      'Add a verification code when you sign in, top up, exchange or pay out.';
-
-  @override
-  String get factorOn => 'On';
-
-  @override
-  String get factorOff => 'Off';
-
-  @override
-  String get factorEnable => 'Turn on';
-
-  @override
-  String get factorDisable => 'Turn off';
-
-  @override
-  String get factorEmailMethod => 'Email code';
-
-  @override
-  String get factorAppMethod => 'Authenticator app';
-
-  @override
-  String get factorAppExpired =>
-      'This verification has expired. Return and start again.';
-}

frontend/app/lib/generated/i18n/app_localizations_ru.dart

@@ -1,857 +0,0 @@
-// ignore: unused_import
-import 'package:intl/intl.dart' as intl;
-
-import 'app_localizations.dart';
-
-// ignore_for_file: type=lint
-
-/// The translations for Russian (`ru`).
-class AppLocalizationsRu extends AppLocalizations {
-  AppLocalizationsRu([String locale = 'ru']) : super(locale);
-
-  @override
-  String get appTitle => 'SXCHNGE · Ваш следующий шаг';
-
-  @override
-  String get nextChapter => 'НОВАЯ ГЛАВА';
-
-  @override
-  String get loginHeading => 'Рады видеть\nвас снова.';
-
-  @override
-  String get signupHeading => 'Сделайте\nпервый шаг.';
-
-  @override
-  String get loginIntro => 'Войдите, чтобы сделать следующий шаг.';
-
-  @override
-  String get signupIntro => 'Новый аккаунт. Новые возможности.';
-
-  @override
-  String get login => 'Войти';
-
-  @override
-  String get signup => 'Регистрация';
-
-  @override
-  String get name => 'Ваше имя';
-
-  @override
-  String get email => 'Электронная почта';
-
-  @override
-  String get emailHint => 'you@example.com';
-
-  @override
-  String get password => 'Пароль';
-
-  @override
-  String get confirmPassword => 'Повторите пароль';
-
-  @override
-  String get passwordHint => 'Используйте не менее 12 символов.';
-
-  @override
-  String get showPassword => 'Показать пароль';
-
-  @override
-  String get hidePassword => 'Скрыть пароль';
-
-  @override
-  String get showConfirmation => 'Показать повтор пароля';
-
-  @override
-  String get hideConfirmation => 'Скрыть повтор пароля';
-
-  @override
-  String get createAccount => 'Создать аккаунт';
-
-  @override
-  String get letsGo => 'Продолжить';
-
-  @override
-  String get loginPreview => 'Вы вошли в аккаунт.';
-
-  @override
-  String get signupPreview => 'Ваш аккаунт готов.';
-
-  @override
-  String get alreadyMember => 'Уже есть аккаунт sxchnge?';
-
-  @override
-  String get newHere => 'Впервые здесь?';
-
-  @override
-  String get loginInstead => 'Войти в аккаунт';
-
-  @override
-  String get createAnAccount => 'Зарегистрироваться';
-
-  @override
-  String get brandEyebrow => 'МАЛЕНЬКАЯ ПЕРЕМЕНА. БОЛЬШОЙ ШАГ.';
-
-  @override
-  String get brandHeading => 'Всё начинается\nс перемен.';
-
-  @override
-  String get brandIntro =>
-      'Новый путь вперёд.\nОткройте его вместе со sxchnge.';
-
-  @override
-  String get brandCard => 'Меньше преград.\nБольше возможностей.';
-
-  @override
-  String get brandFooter => 'СЛЕДУЮЩИЙ ШАГ — ЗА ВАМИ.';
-
-  @override
-  String get emailRequired => 'Введите электронную почту.';
-
-  @override
-  String get emailInvalid => 'Введите корректный адрес почты.';
-
-  @override
-  String get nameRequired => 'Введите ваше имя.';
-
-  @override
-  String get passwordRequired => 'Введите пароль.';
-
-  @override
-  String get confirmationRequired => 'Повторите пароль.';
-
-  @override
-  String get passwordMismatch => 'Пароли не совпадают.';
-
-  @override
-  String get language => 'Язык';
-
-  @override
-  String get preferenceNotSaved =>
-      'Язык изменён для этого сеанса. Сохранить выбор не удалось.';
-
-  @override
-  String get authWorking => 'Подождите…';
-
-  @override
-  String get authCompleted => 'Запрос выполнен.';
-
-  @override
-  String get authInvalidCredentials =>
-      'Неверная почта или пароль. Попробуйте ещё раз.';
-
-  @override
-  String get authEmailInUse =>
-      'Эта почта уже зарегистрирована. Попробуйте войти.';
-
-  @override
-  String get authUnavailable => 'Сервис недоступен. Попробуйте ещё раз.';
-
-  @override
-  String get authUnexpected => 'Что-то пошло не так. Попробуйте ещё раз.';
-
-  @override
-  String get checkInbox => 'Проверьте почту.';
-
-  @override
-  String get verificationSent =>
-      'Мы отправили вам письмо для подтверждения. Откройте ссылку в письме, чтобы подтвердить электронную почту.';
-
-  @override
-  String get verificationSending => 'Готовим письмо для подтверждения…';
-
-  @override
-  String get verificationChecking => 'Подтверждаем вашу почту…';
-
-  @override
-  String get verificationVerified => 'Ваша почта\nподтверждена.';
-
-  @override
-  String get verificationVerifiedBody =>
-      'Первый шаг пройден. Теперь можно вернуться ко входу. Подтверждение личности — отдельный этап.';
-
-  @override
-  String get verificationExpired => 'Срок действия ссылки истёк.';
-
-  @override
-  String get verificationExpiredBody =>
-      'Запросите новое письмо и перейдите по ссылке из него.';
-
-  @override
-  String get verificationInvalid => 'Ссылка недействительна.';
-
-  @override
-  String get verificationInvalidBody =>
-      'Ссылка подтверждения отсутствует или недействительна. Откройте полную ссылку из письма или запросите новую.';
-
-  @override
-  String get verificationInternal => 'Что-то пошло не так.';
-
-  @override
-  String get verificationInternalBody =>
-      'Не удалось выполнить запрос из-за внутренней ошибки. Попробуйте ещё раз.';
-
-  @override
-  String get verificationResend => 'Отправить письмо ещё раз';
-
-  @override
-  String get verificationRequest => 'Отправить новое письмо';
-
-  @override
-  String get verificationRetry => 'Повторить подтверждение';
-
-  @override
-  String get verificationBack => 'Вернуться ко входу';
-
-  @override
-  String get verificationHint =>
-      'Нет письма? Проверьте папку «Спам» или запросите новое ниже.';
-
-  @override
-  String get verificationDemoLink => 'Перейти к подтверждению';
-
-  @override
-  String get verificationStep => 'ПОДТВЕРДИТЕ ПОЧТУ';
-
-  @override
-  String get verificationRecipient => 'Получатель';
-
-  @override
-  String get verificationChangeEmail => 'Изменить почту';
-
-  @override
-  String get kycTitle => 'Верификация и лимиты';
-
-  @override
-  String get kycIntro =>
-      'Ваш аккаунт — ваш темп. Подтвердите личность, когда понадобятся более высокие лимиты.';
-
-  @override
-  String get kycUnverified => 'Личность не подтверждена';
-
-  @override
-  String get kycPending => 'На проверке';
-
-  @override
-  String get kycApproved => 'Личность подтверждена';
-
-  @override
-  String get kycChanges => 'Нужны новые фото';
-
-  @override
-  String get kycDenied => 'Верификация отклонена';
-
-  @override
-  String get kycUnverifiedBody =>
-      'Вы можете пользоваться аккаунтом с базовыми лимитами. Для повышения отправьте фото паспорта и селфи с ним.';
-
-  @override
-  String get kycPendingBody =>
-      'Заявка ожидает проверки сотрудником. До одобрения действуют базовые лимиты. Повторная отправка не нужна.';
-
-  @override
-  String get kycApprovedBody =>
-      'Проверка завершена. Актуальные лимиты указаны ниже.';
-
-  @override
-  String get kycChangesBody =>
-      'Аккаунт доступен с базовыми лимитами. Замените фото и отправьте новую заявку.';
-
-  @override
-  String get kycDeniedBody =>
-      'Базовые лимиты остаются доступными. Если вы не согласны с решением, обратитесь в поддержку для пересмотра.';
-
-  @override
-  String get kycPassportReason =>
-      'Данные паспорта не удалось прочитать. Переснимите при хорошем освещении, чтобы все края были видны.';
-
-  @override
-  String get kycSelfieReason =>
-      'На селфи плохо видно лицо или паспорт. Оба должны быть в кадре и в фокусе.';
-
-  @override
-  String get kycExpiredReason =>
-      'Срок действия паспорта истёк. Используйте действующий паспорт и сделайте оба фото заново.';
-
-  @override
-  String get kycDeniedReason =>
-      'По этой заявке не удалось подтвердить вашу личность.';
-
-  @override
-  String get kycStart => 'Подтвердить личность';
-
-  @override
-  String get kycResubmit => 'Заменить фото';
-
-  @override
-  String get kycRefresh => 'Обновить статус и лимиты';
-
-  @override
-  String get kycSupport => 'Обратиться в поддержку';
-
-  @override
-  String get kycSupportBody => 'Поддержка сейчас недоступна. Попробуйте позже.';
-
-  @override
-  String get kycBasic => 'Базовый';
-
-  @override
-  String get kycVerifiedTier => 'Подтверждённый';
-
-  @override
-  String get kycLimits => 'Ваши лимиты';
-
-  @override
-  String get kycDay => 'Объём за день';
-
-  @override
-  String get kycMonth => 'Объём за месяц';
-
-  @override
-  String get kycCurrent => 'Текущий лимит';
-
-  @override
-  String get kycRemaining => 'Доступно';
-
-  @override
-  String get kycAfter => 'После одобрения';
-
-  @override
-  String get kycLimitsError =>
-      'Не удалось обновить лимиты. Значения ниже могут быть устаревшими. Повторите запрос.';
-
-  @override
-  String get kycLimitsEmpty =>
-      'Сервис не вернул лимиты. Обновите данные или уточните их в поддержке перед операцией.';
-
-  @override
-  String get kycLoading => 'Загружаем ваш статус…';
-
-  @override
-  String get kycPassport => 'Фото паспорта';
-
-  @override
-  String get kycSelfie => 'Селфи с паспортом';
-
-  @override
-  String get kycReview => 'Проверьте фото';
-
-  @override
-  String get kycPassportHelp =>
-      'Откройте действующий паспорт на странице с фото. Все четыре края и текст должны быть чётко видны. Избегайте бликов и размытия, не закрывайте данные.';
-
-  @override
-  String get kycSelfieHelp =>
-      'Держите открытый паспорт рядом с лицом. Лицо целиком и страница с фото должны быть в одном кадре, чёткими и ничем не закрытыми.';
-
-  @override
-  String get kycFileRules =>
-      'JPEG или PNG · до 10 МБ · не менее 600 × 600 пикселей. Сделайте фото камерой, затем выберите его здесь.';
-
-  @override
-  String get kycChoose => 'Выбрать фото';
-
-  @override
-  String get kycReplace => 'Выбрать другое фото';
-
-  @override
-  String get kycRemove => 'Удалить фото';
-
-  @override
-  String get kycNext => 'Продолжить';
-
-  @override
-  String get kycBack => 'Назад';
-
-  @override
-  String get kycSkip => 'Оставить базовые лимиты';
-
-  @override
-  String get kycClose => 'К аккаунту';
-
-  @override
-  String get kycReviewHelp =>
-      'Убедитесь, что оба фото читаемы и на них один паспорт. Их проверит сотрудник. Отправка не повышает лимиты сразу.';
-
-  @override
-  String get kycConfirm => 'На фото я и мой действующий паспорт.';
-
-  @override
-  String get kycSubmit => 'Отправить на проверку';
-
-  @override
-  String get kycWorking => 'Обработка… Не закрывайте страницу.';
-
-  @override
-  String get kycDiscardTitle => 'Удалить выбранные фото?';
-
-  @override
-  String get kycDiscardBody =>
-      'Черновик хранится только в памяти. При выходе выбранные фото будут удалены. Позже можно начать заново.';
-
-  @override
-  String get kycStay => 'Продолжить';
-
-  @override
-  String get kycDiscard => 'Удалить и выйти';
-
-  @override
-  String get kycErrorUnavailable =>
-      'Сервис недоступен. Выбранные фото сохранены в памяти. Повторите попытку.';
-
-  @override
-  String get kycErrorInternal =>
-      'Произошла ошибка. Повторите попытку; выбранные фото сохранены.';
-
-  @override
-  String get kycErrorPermission =>
-      'Не удалось открыть фото. Проверьте доступ к файлам или выберите другое изображение.';
-
-  @override
-  String get kycErrorFormat =>
-      'Выберите изображение JPEG или PNG. Другие форматы не поддерживаются.';
-
-  @override
-  String get kycErrorLarge =>
-      'Изображение слишком большое. Выберите файл до 10 МБ и 40 мегапикселей.';
-
-  @override
-  String get kycErrorUnreadable =>
-      'Изображение повреждено или не читается. Выберите другое фото.';
-
-  @override
-  String get kycErrorSmall =>
-      'Фото слишком маленькое. Ширина и высота должны быть не менее 600 пикселей.';
-
-  @override
-  String get kycErrorIncomplete =>
-      'Выберите оба фото и подтвердите, что на них вы и ваш паспорт.';
-
-  @override
-  String get kycErrorSession =>
-      'Сессия истекла. Войдите снова и проверьте статус верификации.';
-
-  @override
-  String get kycErrorRate =>
-      'Слишком много запросов. Немного подождите и повторите попытку.';
-
-  @override
-  String get kycErrorConflict =>
-      'Статус проверки изменился. Обновите его, прежде чем продолжить.';
-
-  @override
-  String get kycDemoControls => 'Сценарии проверки';
-
-  @override
-  String get kycDemoApprove => 'Одобрить';
-
-  @override
-  String get kycDemoCorrect => 'Запросить чёткое фото паспорта';
-
-  @override
-  String get kycDemoSelfie => 'Запросить чёткое селфи';
-
-  @override
-  String get kycDemoExpired => 'Паспорт просрочен';
-
-  @override
-  String get kycDemoDeny => 'Отклонить';
-
-  @override
-  String get kycPreview => 'Посмотреть верификацию и лимиты';
-
-  @override
-  String get kycChooseFirst => 'Выберите фото для продолжения.';
-
-  @override
-  String get kycStatusStale =>
-      'Не удалось обновить статус. Показан последний известный результат.';
-
-  @override
-  String get kycUsed => 'Использовано';
-
-  @override
-  String get kycReserved => 'Зарезервировано';
-
-  @override
-  String get kycUsageHelp =>
-      'Использовано — завершённые операции. Зарезервировано — суммы, удержанные для ожидающих операций. Обе суммы учитываются в лимите.';
-
-  @override
-  String get kycOccupied => 'Использовано + зарезервировано';
-
-  @override
-  String get kycNoCapacity => 'Доступный объём исчерпан';
-
-  @override
-  String get wAccounts => 'Счета';
-
-  @override
-  String get wActivity => 'История';
-
-  @override
-  String get wLimits => 'Лимиты';
-
-  @override
-  String get wSettings => 'Настройки';
-
-  @override
-  String get wHeadline => 'Ваши деньги.\nВаш следующий шаг.';
-
-  @override
-  String get wSubheading => 'Пополняйте. Обменивайте. Двигайтесь дальше.';
-
-  @override
-  String get wAvailable => 'Вам доступно';
-
-  @override
-  String get wTopUp => 'Пополнить';
-
-  @override
-  String get wExchange => 'Обменять';
-
-  @override
-  String get wPayout => 'Вывести';
-
-  @override
-  String get wRecent => 'Последние операции';
-
-  @override
-  String get wSeeAll => 'Смотреть все';
-
-  @override
-  String get wEmptyActivity =>
-      'Ваш следующий шаг начинается здесь. Здесь появятся ваши операции.';
-
-  @override
-  String get wEmptyAccounts =>
-      'Ваши счета ещё не готовы. Попробуйте обновить страницу.';
-
-  @override
-  String get wRefresh => 'Обновить';
-
-  @override
-  String get wSource => 'Со счёта';
-
-  @override
-  String get wDestination => 'На счёт';
-
-  @override
-  String get wReceiveAccount => 'Счёт для зачисления';
-
-  @override
-  String get wAmount => 'Сумма';
-
-  @override
-  String get wRecipient => 'Получатель';
-
-  @override
-  String get wRecipientHint => 'Имя или реквизиты получателя';
-
-  @override
-  String get wReview => 'Проверить';
-
-  @override
-  String get wReviewTitle => 'Проверьте детали.';
-
-  @override
-  String get wFee => 'Комиссия';
-
-  @override
-  String get wTotalDebit => 'Спишется со счёта';
-
-  @override
-  String get wCredit => 'Поступит на счёт';
-
-  @override
-  String get wRecipientGets => 'Получатель получит';
-
-  @override
-  String get wYouPay => 'Вы платите';
-
-  @override
-  String get wRate => 'Курс обмена';
-
-  @override
-  String get wQuoteNotice =>
-      'Эти условия действуют 60 секунд. Подтвердите их, прежде чем продолжить.';
-
-  @override
-  String get wExpired =>
-      'Срок действия расчёта истёк. Обновите его и проверьте новые условия.';
-
-  @override
-  String get wNewQuote => 'Обновить расчёт';
-
-  @override
-  String get wConfirm => 'Подтвердить операцию';
-
-  @override
-  String get wEdit => 'Изменить данные';
-
-  @override
-  String get wClose => 'Закрыть';
-
-  @override
-  String get wWorking => 'Обрабатываем…';
-
-  @override
-  String get wPending => 'В обработке';
-
-  @override
-  String get wCompleted => 'Завершено';
-
-  @override
-  String get wFailed => 'Не выполнено';
-
-  @override
-  String get wPendingTopUp =>
-      'Пополнение обрабатывается. Доступный баланс пока не изменился.';
-
-  @override
-  String get wPendingExchange =>
-      'Сумма и комиссия уже вычтены из доступного баланса. После завершения обмена деньги появятся на счёте зачисления.';
-
-  @override
-  String get wPendingPayout =>
-      'Сумма и комиссия уже вычтены из доступного баланса. Вывод ещё обрабатывается.';
-
-  @override
-  String get wCompleteTopUp => 'Счёт пополнен. Деньги доступны для операций.';
-
-  @override
-  String get wCompleteExchange =>
-      'Обмен завершён. Деньги доступны на счёте зачисления.';
-
-  @override
-  String get wCompletePayout =>
-      'Вывод завершён. Сумма и комиссия списаны с вашего счёта.';
-
-  @override
-  String get wFailedTopUp =>
-      'Пополнение не выполнено. На счёт ничего не зачислено.';
-
-  @override
-  String get wFailedOutgoing =>
-      'Операция не выполнена. Сумма и комиссия снова доступны на вашем счёте.';
-
-  @override
-  String get wUnavailable =>
-      'Не удалось обновить данные. Информация может быть устаревшей. Повторите попытку.';
-
-  @override
-  String get wInvalidAmount =>
-      'Введите сумму больше нуля с допустимым для валюты числом знаков после запятой.';
-
-  @override
-  String get wInsufficient =>
-      'Для этой суммы и комиссии недостаточно доступных средств. Пополните счёт или уменьшите сумму.';
-
-  @override
-  String get wLimitError =>
-      'Сумма превышает доступный лимит. Проверьте лимиты перед продолжением.';
-
-  @override
-  String get wRecipientError =>
-      'Введите тестового получателя длиной от 6 до 140 символов.';
-
-  @override
-  String get wUnsupported => 'Эта комбинация недоступна. Выберите другой счёт.';
-
-  @override
-  String get wNotFound => 'Не удалось найти запись. Вернитесь к счетам.';
-
-  @override
-  String get wUncertain =>
-      'Не удалось подтвердить результат. Проверьте его, прежде чем создавать другую операцию.';
-
-  @override
-  String get wCheckOutcome => 'Проверить результат';
-
-  @override
-  String get wNoSubmission =>
-      'Операция не найдена. Вы можете снова проверить и подтвердить её.';
-
-  @override
-  String get wDiscardTitle => 'Выйти из операции?';
-
-  @override
-  String get wDiscardBody =>
-      'Введённые данные будут удалены. Новая операция не будет отправлена.';
-
-  @override
-  String get wStay => 'Продолжить';
-
-  @override
-  String get wAll => 'Все';
-
-  @override
-  String get wSearch => 'Поиск по номеру';
-
-  @override
-  String get wNoMatches => 'Операции не найдены. Измените фильтр.';
-
-  @override
-  String get wClearFilters => 'Сбросить фильтры';
-
-  @override
-  String get wReference => 'Номер операции';
-
-  @override
-  String get wWhen => 'Создано';
-
-  @override
-  String get wViewAccount => 'Открыть счёт';
-
-  @override
-  String get wPreferences => 'Настройте под себя.';
-
-  @override
-  String get wLanguage => 'Язык аккаунта';
-
-  @override
-  String get wLanguageHelp => 'Используется во всём аккаунте.';
-
-  @override
-  String get wLanguageSaved => 'Сохранено в аккаунте.';
-
-  @override
-  String get wLanguageFailed =>
-      'Изменено для текущей сессии, но не сохранено в аккаунте. Повторите попытку ниже.';
-
-  @override
-  String get wProfileError =>
-      'Не удалось загрузить настройки аккаунта. Повторите попытку.';
-
-  @override
-  String get wSecurity => 'Безопасность';
-
-  @override
-  String get wSecurityBody =>
-      'Настройки пароля и безопасности пока недоступны.';
-
-  @override
-  String get wIdentity => 'Подтверждение личности';
-
-  @override
-  String get wIdentityHelp => 'Необязательная проверка для повышения лимитов.';
-
-  @override
-  String get wBackLogin => 'Вернуться ко входу';
-
-  @override
-  String get wEnter => 'Открыть свои счета';
-
-  @override
-  String get wUsage => 'Использовано за период';
-
-  @override
-  String get wLimitsScope => 'Исходящие операции · эквивалент в EUR';
-
-  @override
-  String get wPendingHint =>
-      'Обновите, чтобы узнать текущий статус. Остальными счетами можно пользоваться.';
-
-  @override
-  String get wFundsHeading => 'Где мои деньги?';
-
-  @override
-  String get wAnother => 'Создать новую операцию';
-
-  @override
-  String get factorTitle => 'Ещё одна проверка.';
-
-  @override
-  String get factorLogin => 'Подтвердите, что это вы, чтобы завершить вход.';
-
-  @override
-  String get factorMoney =>
-      'Подтвердите эту операцию. До подтверждения деньги не переводятся.';
-
-  @override
-  String get factorEnableHelp =>
-      'Подтвердите включение двухфакторной проверки для входа и операций с деньгами.';
-
-  @override
-  String get factorDisableHelp =>
-      'Подтвердите отключение двухфакторной проверки. Для входа и операций больше не потребуется второй код.';
-
-  @override
-  String get factorEmail => 'Введите шестизначный код из письма.';
-
-  @override
-  String get factorAuthenticator =>
-      'Введите текущий шестизначный код из приложения-аутентификатора.';
-
-  @override
-  String get factorCode => 'Код подтверждения';
-
-  @override
-  String get factorConfirm => 'Подтвердить и продолжить';
-
-  @override
-  String get factorResend => 'Отправить новый код';
-
-  @override
-  String get factorHelp =>
-      'Проверьте входящие и папку «Спам». Новый код заменяет предыдущий.';
-
-  @override
-  String get factorAppHelp =>
-      'Используйте текущий код. Если приложение недоступно, отмените это действие.';
-
-  @override
-  String get factorInvalid =>
-      'Неверный код. Проверьте все шесть цифр и попробуйте ещё раз.';
-
-  @override
-  String get factorExpired =>
-      'Срок проверки истёк. Запросите новый код или вернитесь и начните снова.';
-
-  @override
-  String get factorLocked =>
-      'Слишком много неверных попыток. Подождите пять минут и начните проверку снова.';
-
-  @override
-  String get factorWait => 'Подождите перед повторным запросом кода.';
-
-  @override
-  String get factorRequired =>
-      'Нужна повторная проверка. Подтвердите это действие ещё раз.';
-
-  @override
-  String get factorUnavailable =>
-      'Не удалось завершить проверку. Повторите попытку или отмените действие.';
-
-  @override
-  String factorCooldown(int seconds) {
-    return 'Новый код через $seconds с';
-  }
-
-  @override
-  String get factorSettings => 'Двухфакторная проверка';
-
-  @override
-  String get factorSettingsHelp =>
-      'Подтверждайте кодом вход, пополнение, обмен и вывод средств.';
-
-  @override
-  String get factorOn => 'Включена';
-
-  @override
-  String get factorOff => 'Выключена';
-
-  @override
-  String get factorEnable => 'Включить';
-
-  @override
-  String get factorDisable => 'Выключить';
-
-  @override
-  String get factorEmailMethod => 'Код из письма';
-
-  @override
-  String get factorAppMethod => 'Приложение-аутентификатор';
-
-  @override
-  String get factorAppExpired =>
-      'Срок проверки истёк. Вернитесь и начните снова.';
-}

frontend/app/lib/l10n/en.arb

@@ -43,10 +43,11 @@
   "authCompleted": "Request completed.",
   "authInvalidCredentials": "Email or password is incorrect. Please try again.",
   "authEmailInUse": "This email is already registered. Try logging in.",
+  "authVerifyEmail": "Confirm your email before signing in.",
   "authUnavailable": "The service is unavailable. Please try again.",
   "authUnexpected": "Something went wrong. Please try again.",
   "checkInbox": "Check your inbox.",
-  "verificationSent": "We’ve sent you a verification email. Open the link in your inbox to confirm your email address.",
+  "verificationSent": "If this email belongs to an unverified account, a verification email is on its way. Open the link in your inbox to confirm your address.",
   "verificationSending": "Preparing your verification email…",
   "verificationChecking": "Verifying your email…",
   "verificationVerified": "Your email\nis verified.",

frontend/app/lib/l10n/ru.arb

@@ -43,10 +43,11 @@
   "authCompleted": "Запрос выполнен.",
   "authInvalidCredentials": "Неверная почта или пароль. Попробуйте ещё раз.",
   "authEmailInUse": "Эта почта уже зарегистрирована. Попробуйте войти.",
+  "authVerifyEmail": "Подтвердите почту перед входом.",
   "authUnavailable": "Сервис недоступен. Попробуйте ещё раз.",
   "authUnexpected": "Что-то пошло не так. Попробуйте ещё раз.",
   "checkInbox": "Проверьте почту.",
-  "verificationSent": "Мы отправили вам письмо для подтверждения. Откройте ссылку в письме, чтобы подтвердить электронную почту.",
+  "verificationSent": "Если эта почта принадлежит неподтверждённому аккаунту, письмо с подтверждением уже в пути. Откройте ссылку в письме, чтобы подтвердить адрес.",
   "verificationSending": "Готовим письмо для подтверждения…",
   "verificationChecking": "Подтверждаем вашу почту…",
   "verificationVerified": "Ваша почта\nподтверждена.",

frontend/app/lib/main.dart

@@ -20,13 +20,19 @@ import 'generated/i18n/app_localizations.dart';
 Future<void> main() async {
   final binding = WidgetsFlutterBinding.ensureInitialized();
   final locale = await LocaleProvider.load(binding.platformDispatcher.locales);
-  runApp(SxchngeApp(localeProvider: locale));
+  const apiUrl = String.fromEnvironment('SXCHNGE_API_URL');
+  const clientId = String.fromEnvironment('SXCHNGE_CLIENT_ID');
+  final backend = apiUrl.isEmpty
+      ? null
+      : BackendAuthServices(baseUri: Uri.parse(apiUrl), clientId: clientId);
+  runApp(SxchngeApp(localeProvider: locale, backend: backend));
 }
 
 class SxchngeApp extends StatefulWidget {
   const SxchngeApp({
     super.key,
     this.localeProvider,
+    this.backend,
     this.analyticsService,
     this.identityService,
     this.limitsService,
@@ -38,6 +44,7 @@ class SxchngeApp extends StatefulWidget {
     this.verificationService = const DummyVerificationService(),
   });
   final LocaleProvider? localeProvider;
+  final BackendAuthServices? backend;
   final AnalyticsService? analyticsService;
   final IdentityService? identityService;
   final LimitsService? limitsService;
@@ -56,7 +63,8 @@ class _SxchngeAppState extends State<SxchngeApp> {
   late final _locale = widget.localeProvider ?? LocaleProvider();
 
   late final _analytics = widget.analyticsService ?? DummyAnalyticsService();
-  late final _factors = widget.twoFactorService ?? DummyTwoFactorService();
+  late final _factors =
+      widget.backend ?? widget.twoFactorService ?? DummyTwoFactorService();
   late final _security = SecurityProvider(_factors, _analytics);
   late final _identity = widget.identityService ?? DummyIdentityService();
   late final _walletService =
@@ -79,12 +87,18 @@ class _SxchngeAppState extends State<SxchngeApp> {
   late final _journeys = JourneyRecorder(_analytics);
   late final _services = InstrumentedAuthServices(
     recorder: _journeys,
-    loginService: GuardedLoginService(widget.loginService, _factors),
-    signupService: widget.signupService,
-    verificationService: widget.verificationService,
+    loginService: GuardedLoginService(
+      widget.backend ?? widget.loginService,
+      _factors,
+    ),
+    signupService: widget.backend ?? widget.signupService,
+    verificationService: widget.backend ?? widget.verificationService,
   );
-  late final _router = createAppRouter()
-    ..routeInformationProvider.addListener(_routeChanged);
+  late final _router = createAppRouter(
+    authenticated: widget.backend == null
+        ? null
+        : () => widget.backend!.session != null,
+  )..routeInformationProvider.addListener(_routeChanged);
   String _previousPath = '/';
 
   @override
@@ -109,6 +123,7 @@ class _SxchngeAppState extends State<SxchngeApp> {
     _wallet.dispose();
     _security.dispose();
     _locale.dispose();
+    widget.backend?.close();
     super.dispose();
   }
 

frontend/app/lib/routing/router.dart

@@ -19,12 +19,23 @@ import '../workspace/shell.dart';
 import '../workspace/transfer.dart';
 import 'routes.dart';
 
-GoRouter createAppRouter() {
+GoRouter createAppRouter({bool Function()? authenticated}) {
   final topUpKey = GlobalKey<TransferPageState>();
   final exchangeKey = GlobalKey<TransferPageState>();
   final payoutKey = GlobalKey<TransferPageState>();
   final identityKey = GlobalKey<IdentityPageState>();
   return GoRouter(
+    redirect: (context, state) {
+      if (authenticated == null || authenticated()) return null;
+      final path = state.uri.path;
+      if (path == '/' ||
+          path == '/verify-email' ||
+          path == '/verification-sent' ||
+          path == '/two-factor') {
+        return null;
+      }
+      return '/';
+    },
     // Signup email is an in-memory navigation extra, never browser-history data.
     extraCodec: const _TransientExtras(),
     routes: [

frontend/app/test/auth_services_test.dart

@@ -4,6 +4,8 @@ import 'package:flutter/material.dart';
 
 import 'package:flutter_test/flutter_test.dart';
 
+import 'package:go_router/go_router.dart';
+
 import 'package:sxchnge_auth/sxchnge_auth.dart';
 
 import 'package:sxchnge_app/main.dart';
@@ -21,7 +23,63 @@ class ControlledLogin implements LoginService {
   }
 }
 
+class UnverifiedBackend extends BackendAuthServices {
+  UnverifiedBackend()
+    : super(baseUri: Uri.parse('https://api.example/api/v1'), clientId: 'web');
+  int sends = 0;
+  @override
+  Future<AuthResult> login(LoginRequest request) async =>
+      throw const AuthException(AuthError.accountNotVerified);
+  @override
+  Future<VerificationResult> send({
+    required String email,
+    required String locale,
+  }) async {
+    sends++;
+    return const VerificationResult(isSimulated: false);
+  }
+}
+
 void main() {
+  testWidgets('backend mode gates workspace and recovers unverified login', (
+    tester,
+  ) async {
+    tester.view.physicalSize = const Size(1440, 1200);
+    tester.view.devicePixelRatio = 1;
+    addTearDown(tester.view.resetPhysicalSize);
+    addTearDown(tester.view.resetDevicePixelRatio);
+    final backend = UnverifiedBackend();
+    await tester.pumpWidget(SxchngeApp(backend: backend));
+    await tester.pumpAndSettle();
+    final router = GoRouter.of(
+      tester.element(find.byKey(const ValueKey('email'))),
+    );
+    router.go('/accounts');
+    await tester.pumpAndSettle();
+    expect(router.routeInformationProvider.value.uri.path, '/');
+    await tester.enterText(
+      find.byKey(const ValueKey('email')),
+      'user@example.com',
+    );
+    await tester.enterText(
+      find.byKey(const ValueKey('password')),
+      'password-value',
+    );
+    await tester.ensureVisible(find.byKey(const ValueKey('submit')));
+    await tester.tap(find.byKey(const ValueKey('submit')));
+    await tester.pumpAndSettle();
+    expect(
+      router.routeInformationProvider.value.uri.path,
+      '/verification-sent',
+    );
+    expect(backend.sends, 1);
+    expect(
+      find.textContaining('a verification email is on its way'),
+      findsOneWidget,
+    );
+    expect(tester.takeException(), isNull);
+  });
+
   testWidgets(
     'app shows loading, localized failure, and retries through injected service',
     (tester) async {

frontend/app/test/ux_analytics_test.dart

@@ -131,7 +131,10 @@ void main() {
       );
       await tap(tester, find.byKey(const ValueKey('submit')));
       expect(find.text('Check your inbox.'), findsOneWidget);
-      expect(find.textContaining('We’ve sent you'), findsOneWidget);
+      expect(
+        find.textContaining('a verification email is on its way'),
+        findsOneWidget,
+      );
       await tap(tester, find.byKey(const ValueKey('demo-confirmation')));
       expect(find.text('Your email\nis verified.'), findsOneWidget);
       expect(sink.events.map((e) => e.journeyId).toSet().length, 1);

frontend/packages/sxchnge_auth/lib/src/dto/backend.dart

@@ -0,0 +1,25 @@
+import 'dart:convert';
+
+class BackendDTO {
+  BackendDTO(this.data);
+  factory BackendDTO.decode(String body) => BackendDTO(
+    (jsonDecode(body) as Map<String, dynamic>)['data'] as Map<String, dynamic>,
+  );
+  final Map<String, dynamic> data;
+  String get error => data['error'] as String? ?? 'unavailable';
+  String get userId =>
+      data['userId'] as String? ??
+      (data['account'] as Map<String, dynamic>?)?['id'] as String? ??
+      '';
+  String get pendingToken =>
+      (data['pendingToken'] as Map<String, dynamic>)['token'] as String;
+  String get challengeId => data['challengeId'] as String? ?? '';
+  String get channel => data['channel'] as String? ?? '';
+  String get target => data['target'] as String;
+  DateTime get expiresAt => DateTime.parse(data['expiresAt'] as String);
+  DateTime get resendAt => DateTime.parse(data['resendAt'] as String);
+  String get accessToken =>
+      (data['accessToken'] as Map<String, dynamic>)['token'] as String;
+  String get refreshToken =>
+      (data['refreshToken'] as Map<String, dynamic>)['token'] as String;
+}

frontend/packages/sxchnge_auth/lib/src/mappers/backend.dart

@@ -0,0 +1,50 @@
+import '../dto/backend.dart';
+import '../models/auth.dart';
+import '../models/session.dart';
+import '../models/two_factor.dart';
+
+abstract final class BackendMapper {
+  static AuthResult signup(BackendDTO dto) {
+    if (dto.userId.isEmpty) throw const FormatException('Missing user');
+    return AuthResult(userId: dto.userId, isSimulated: false);
+  }
+
+  static FactorChallenge challenge(BackendDTO dto, String id) {
+    if (dto.challengeId.isEmpty || dto.channel != 'email') {
+      throw const FactorException(FactorError.unavailable);
+    }
+    return FactorChallenge(
+      id: id,
+      purpose: FactorPurpose.login,
+      operation: id,
+      target: dto.target,
+      expiresAt: dto.expiresAt,
+      resendAt: dto.resendAt,
+    );
+  }
+
+  static AuthSession session(BackendDTO dto) {
+    if (dto.accessToken.isEmpty || dto.userId.isEmpty) {
+      throw const FormatException('Missing session');
+    }
+    return AuthSession(dto.userId, dto.accessToken, dto.refreshToken);
+  }
+
+  static AuthException authFailure(int status, BackendDTO dto) =>
+      AuthException(switch (dto.error) {
+        'email_in_use' => AuthError.emailInUse,
+        'account_not_verified' => AuthError.accountNotVerified,
+        _ when status == 401 => AuthError.invalidCredentials,
+        _ when status == 429 => AuthError.factorCooldown,
+        _ => AuthError.unavailable,
+      });
+  static FactorException factorFailure(int status, BackendDTO dto) =>
+      FactorException(switch (dto.error) {
+        'expired' => FactorError.expired,
+        'locked' => FactorError.locked,
+        'invalid' => FactorError.invalid,
+        _ when status == 429 => FactorError.cooldown,
+        _ when status == 401 => FactorError.expired,
+        _ => FactorError.unavailable,
+      });
+}

frontend/packages/sxchnge_auth/lib/src/models/auth.dart

@@ -39,6 +39,7 @@ class AuthResult {
 
 enum AuthError {
   invalidCredentials,
+  accountNotVerified,
   emailInUse,
   unavailable,
   unexpected,

frontend/packages/sxchnge_auth/lib/src/models/session.dart

@@ -0,0 +1,5 @@
+/// In-memory credentials. Never include these in analytics or provider state.
+class AuthSession {
+  const AuthSession(this.userId, this.accessToken, this.refreshToken);
+  final String userId, accessToken, refreshToken;
+}

frontend/packages/sxchnge_auth/lib/src/services/backend.dart

@@ -0,0 +1,256 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:math';
+
+import 'package:flutter/foundation.dart';
+
+import 'package:http/http.dart' as http;
+
+import '../dto/backend.dart';
+import '../dto/results.dart';
+import '../mappers/backend.dart';
+import '../mappers/results.dart';
+import '../models/auth.dart';
+import '../models/session.dart';
+import '../models/two_factor.dart';
+import '../models/verification.dart';
+import 'contracts.dart';
+import 'guarded_login.dart';
+import 'http/client.dart';
+import 'two_factor.dart';
+import 'verification.dart';
+
+/// Real authentication; wallet/settings operations remain separate adapters.
+class BackendAuthServices
+    implements
+        PendingLoginService,
+        SignupService,
+        VerificationService,
+        TwoFactorService,
+        SimulationInfo {
+  BackendAuthServices({
+    required this.baseUri,
+    required this.clientId,
+    http.Client? client,
+  }) : _client = client ?? createClient() {
+    if (clientId.isEmpty ||
+        !baseUri.hasAuthority ||
+        (baseUri.scheme != 'https' &&
+            !(baseUri.scheme == 'http' &&
+                ['localhost', '127.0.0.1'].contains(baseUri.host))) ||
+        baseUri.hasQuery ||
+        baseUri.hasFragment ||
+        baseUri.userInfo.isNotEmpty) {
+      throw ArgumentError('Valid API URL and client ID required');
+    }
+  }
+  final Uri baseUri;
+  final String clientId;
+  final http.Client _client;
+  final String _deviceId = _key();
+  final _pending = <String, ({String token, String challengeId})>{};
+  final _grants = <String, AuthSession>{};
+  final _retryKeys = <String, String>{};
+  String? _queuedSignup;
+  AuthSession? _session;
+  AuthSession? get session => _session;
+  @override
+  bool get isSimulated => false;
+  static String _key() => base64UrlEncode(
+    List<int>.generate(24, (_) => Random.secure().nextInt(256)),
+  );
+  Future<BackendDTO> _post(
+    String path,
+    Map<String, Object?> body, {
+    bool factor = false,
+  }) async {
+    try {
+      final uri = baseUri.replace(
+        path: '${baseUri.path.replaceFirst(RegExp(r'/$'), '')}/accounts/$path',
+      );
+      final res = await _client
+          .post(
+            uri,
+            headers: {
+              'Content-Type': 'application/json',
+              if (kIsWeb) 'X-Auth-Transport': 'cookie',
+              if (kIsWeb) 'X-CSRF-Protection': '1',
+            },
+            body: jsonEncode(body),
+          )
+          .timeout(const Duration(seconds: 15));
+      final dto = BackendDTO.decode(res.body);
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        throw factor
+            ? BackendMapper.factorFailure(res.statusCode, dto)
+            : BackendMapper.authFailure(res.statusCode, dto);
+      }
+      return dto;
+    } on AuthException {
+      rethrow;
+    } on FactorException {
+      rethrow;
+    } catch (_) {
+      if (factor) throw const FactorException(FactorError.unavailable);
+      throw const AuthException(AuthError.unavailable);
+    }
+  }
+
+  @override
+  Future<AuthResult> signup(SignupRequest r) async {
+    final email = r.email.trim().toLowerCase();
+    final key = _retryKeys.putIfAbsent('signup:$email', _key);
+    final dto = await _post('signup', {
+      'name': r.name,
+      'email': email,
+      'password': r.password,
+      'locale': r.locale,
+      'idempotencyKey': key,
+    });
+    final result = BackendMapper.signup(dto);
+    _retryKeys.remove('signup:$email');
+    _queuedSignup = email;
+    return result;
+  }
+
+  @override
+  Future<AuthResult> login(LoginRequest r) async {
+    _pending.clear();
+    _grants.clear();
+    _session = null;
+    final dto = await _post('login', {
+      'login': {'login': r.email, 'password': r.password},
+      'clientId': clientId,
+      'deviceId': _deviceId,
+    });
+    final id = _key();
+    final challenge = BackendMapper.challenge(dto, id);
+    _pending[id] = (token: dto.pendingToken, challengeId: dto.challengeId);
+    return AuthResult(userId: '', isSimulated: false, challenge: challenge);
+  }
+
+  @override
+  Future<VerificationResult> send({
+    required String email,
+    required String locale,
+  }) async {
+    final normalized = email.trim().toLowerCase();
+    // Signup already queued this email. The existing confirmation page requests
+    // its initial delivery on mount; consume that receipt once.
+    if (_queuedSignup == normalized) {
+      _queuedSignup = null;
+      return VerificationMapper.fromDTO(
+        const VerificationDTO(simulated: false),
+      );
+    }
+    final key = _retryKeys.putIfAbsent('activation:$normalized', _key);
+    try {
+      await _post('verification/send', {
+        'email': normalized,
+        'idempotencyKey': key,
+      }, factor: true);
+      _retryKeys.remove('activation:$normalized');
+      return VerificationMapper.fromDTO(
+        const VerificationDTO(simulated: false),
+      );
+    } on FactorException catch (e) {
+      if (e.code == FactorError.expired || e.code == FactorError.invalid) {
+        _retryKeys.remove('activation:$normalized');
+      }
+      throw const VerificationException(VerificationError.internal);
+    } catch (_) {
+      throw const VerificationException(VerificationError.internal);
+    }
+  }
+
+  @override
+  Future<VerificationResult> confirm({required String token}) async {
+    try {
+      await _post('verification/confirm', {'token': token}, factor: true);
+      return VerificationMapper.fromDTO(
+        const VerificationDTO(simulated: false),
+      );
+    } on FactorException catch (e) {
+      throw VerificationException(switch (e.code) {
+        FactorError.expired => VerificationError.expired,
+        FactorError.invalid => VerificationError.invalid,
+        _ => VerificationError.internal,
+      });
+    }
+  }
+
+  @override
+  Future<FactorChallenge> resend(String challengeId) async {
+    final pending = _pending[challengeId];
+    if (pending == null) throw const FactorException(FactorError.expired);
+    final key = _retryKeys.putIfAbsent('login:$challengeId', _key);
+    final dto = await _post('login/resend', {
+      'pendingToken': pending.token,
+      'challengeId': pending.challengeId,
+      'idempotencyKey': key,
+    }, factor: true);
+    final challenge = BackendMapper.challenge(dto, challengeId);
+    if (dto.challengeId != pending.challengeId) {
+      throw const FactorException(FactorError.unavailable);
+    }
+    _retryKeys.remove('login:$challengeId');
+    return challenge;
+  }
+
+  @override
+  Future<FactorGrant> verify(String challengeId, String code) async {
+    final pending = _pending[challengeId];
+    if (pending == null) throw const FactorException(FactorError.expired);
+    final dto = await _post('login/verify', {
+      'pendingToken': pending.token,
+      'challengeId': pending.challengeId,
+      'code': code,
+    }, factor: true);
+    final session = BackendMapper.session(dto);
+    _pending.remove(challengeId);
+    _grants[challengeId] = session;
+    return FactorGrant(challengeId);
+  }
+
+  @override
+  Future<AuthResult> completeLogin(
+    FactorChallenge challenge,
+    FactorGrant grant,
+  ) async {
+    if (challenge.id != grant.token ||
+        challenge.purpose != FactorPurpose.login) {
+      throw const AuthException(AuthError.factorRequired);
+    }
+    final accepted = _grants.remove(grant.token);
+    if (accepted == null) throw const AuthException(AuthError.factorRequired);
+    _session = accepted;
+    return AuthResult(userId: accepted.userId, isSimulated: false);
+  }
+
+  // Unsupported settings and money operations fail closed until their own
+  // backend adapters exist. They cannot borrow an authentication grant.
+  @override
+  Future<FactorSettings> fetch() async =>
+      throw const FactorException(FactorError.unavailable);
+  @override
+  Future<FactorChallenge?> begin(
+    FactorPurpose purpose,
+    String operation,
+  ) async => throw const FactorException(FactorError.unavailable);
+  @override
+  Future<void> authorize(
+    FactorPurpose purpose,
+    String operation,
+    String? grant,
+  ) async => throw const FactorException(FactorError.required);
+  @override
+  Future<FactorSettings> setEnabled(bool enabled, String grant) async =>
+      throw const FactorException(FactorError.unavailable);
+  void close() {
+    _client.close();
+    _pending.clear();
+    _grants.clear();
+    _retryKeys.clear();
+    _session = null;
+  }
+}

frontend/packages/sxchnge_auth/lib/src/services/http/browser.dart

@@ -0,0 +1,4 @@
+import 'package:http/browser_client.dart';
+import 'package:http/http.dart' as http;
+
+http.Client createClient() => BrowserClient()..withCredentials = true;

frontend/packages/sxchnge_auth/lib/src/services/http/client.dart

@@ -0,0 +1 @@
+export 'native.dart' if (dart.library.js_interop) 'browser.dart';

frontend/packages/sxchnge_auth/lib/src/services/http/native.dart

@@ -0,0 +1,3 @@
+import 'package:http/http.dart' as http;
+
+http.Client createClient() => http.Client();

frontend/packages/sxchnge_auth/lib/src/services/instrumented.dart

@@ -56,6 +56,7 @@ class InstrumentedAuthServices
     } catch (error) {
       final failure = switch (error) {
         AuthException(code: final code) => switch (code) {
+          AuthError.accountNotVerified => JourneyFailure.invalid,
           AuthError.invalidCredentials => JourneyFailure.invalidCredentials,
           AuthError.emailInUse => JourneyFailure.emailInUse,
           AuthError.unavailable => JourneyFailure.unavailable,

frontend/packages/sxchnge_auth/lib/sxchnge_auth.dart

@@ -20,3 +20,6 @@ export 'src/services/two_factor.dart';
 export 'src/services/dummy_factor.dart';
 export 'src/widgets/two_factor.dart';
 export 'src/services/guarded_login.dart';
+
+export 'src/services/backend.dart';
+export 'src/models/session.dart';

frontend/packages/sxchnge_auth/pubspec.yaml

@@ -6,6 +6,7 @@ environment:
   sdk: '>=3.13.0 <4.0.0'
   flutter: '>=3.47.0'
 dependencies:
+  http: ^1.6.0
   sxchnge_analytics:
     path: ../sxchnge_analytics
   flutter:

frontend/packages/sxchnge_auth/test/backend_test.dart

@@ -0,0 +1,222 @@
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+
+import 'package:sxchnge_auth/sxchnge_auth.dart';
+
+void main() {
+  http.Response response(Map<String, Object?> data, [int status = 202]) =>
+      http.Response(jsonEncode({'data': data}), status);
+  test('signup receipt avoids duplicate delivery and subsequent resend reaches API', () async {
+    final paths = <String>[];
+    final service = BackendAuthServices(
+      baseUri: Uri.parse('https://api.example/api/v1'),
+      clientId: 'web',
+      client: MockClient((request) async {
+        paths.add(request.url.path);
+        if (request.url.path.endsWith('/signup')) {
+          expect(jsonDecode(request.body)['password'], ' password preserved ');
+          return response({'userId': 'user'});
+        }
+        return response({'accepted': true});
+      }),
+    );
+    addTearDown(service.close);
+    final result = await service.signup(
+      const SignupRequest(
+        name: 'User',
+        email: 'USER@example.com',
+        password: ' password preserved ',
+        locale: 'en',
+      ),
+    );
+    expect(result.isSimulated, isFalse);
+    await service.send(email: 'user@example.com', locale: 'en');
+    expect(paths, ['/api/v1/accounts/signup']);
+    await service.send(email: 'user@example.com', locale: 'en');
+    expect(paths.last, '/api/v1/accounts/verification/send');
+  });
+  test('login confirms backend session only after factor and consumes local grant once', () async {
+    final now = DateTime.now();
+    var verified = false;
+    final service = BackendAuthServices(
+      baseUri: Uri.parse('https://api.example/api/v1'),
+      clientId: 'web',
+      client: MockClient((request) async {
+        final body = jsonDecode(request.body);
+        if (request.url.path.endsWith('/login')) {
+          expect(body['login'], {
+            'login': 'user@example.com',
+            'password': ' password ',
+          });
+          expect(body['clientId'], 'web');
+          return response({
+            'userId': 'user',
+            'pendingToken': {'token': 'signed-pending'},
+            'challengeId': 'server-challenge',
+            'channel': 'email',
+            'target': 'u***@example.com',
+            'expiresAt': now.add(const Duration(minutes: 10)).toIso8601String(),
+            'resendAt': now.add(const Duration(minutes: 1)).toIso8601String(),
+          });
+        }
+        expect(request.url.path, '/api/v1/accounts/login/verify');
+        expect(body['pendingToken'], 'signed-pending');
+        expect(body['challengeId'], 'server-challenge');
+        if (body['code'] != '123456')
+          return response({'error': 'invalid'}, 400);
+        verified = true;
+        return response({
+          'account': {'id': 'user'},
+          'accessToken': {'token': 'access'},
+          'refreshToken': {'token': 'refresh'},
+        }, 200);
+      }),
+    );
+    addTearDown(service.close);
+    final result = await service.login(
+      const LoginRequest(
+        email: 'user@example.com',
+        password: ' password ',
+        locale: 'en',
+      ),
+    );
+    expect(result.challenge, isNotNull);
+    expect(service.session, isNull);
+    final challenge = result.challenge!;
+    expect(challenge.id, isNot('signed-pending'));
+    await expectLater(
+      service.verify(challenge.id, '000000'),
+      throwsA(isA<FactorException>()),
+    );
+    expect(verified, isFalse);
+    expect(service.session, isNull);
+    final grant = await service.verify(challenge.id, '123456');
+    final accepted = await service.completeLogin(challenge, grant);
+    expect(accepted.userId, 'user');
+    expect(accepted.isSimulated, isFalse);
+    expect(service.session!.accessToken, 'access');
+    await expectLater(
+      service.completeLogin(challenge, grant),
+      throwsA(isA<AuthException>()),
+    );
+    await expectLater(
+      service.authorize(FactorPurpose.payout, 'payment', grant.token),
+      throwsA(isA<FactorException>()),
+    );
+  });
+  test(
+    'failed delivery preserves resend idempotency and never claims success',
+    () async {
+      final keys = <String>[];
+      final service = BackendAuthServices(
+        baseUri: Uri.parse('https://api.example/api/v1'),
+        clientId: 'web',
+        client: MockClient((request) async {
+          keys.add(jsonDecode(request.body)['idempotencyKey'] as String);
+          return response({'error': 'unavailable'}, 503);
+        }),
+      );
+      addTearDown(service.close);
+      for (var i = 0; i < 2; i++) {
+        await expectLater(
+          service.send(email: 'user@example.com', locale: 'en'),
+          throwsA(isA<VerificationException>()),
+        );
+      }
+      expect(keys[0], keys[1]);
+    },
+  );
+  test('expired activation maps to recovery state', () async {
+    final service = BackendAuthServices(
+      baseUri: Uri.parse('https://api.example/api/v1'),
+      clientId: 'web',
+      client: MockClient((_) async => response({'error': 'expired'}, 400)),
+    );
+    addTearDown(service.close);
+    await expectLater(
+      service.confirm(token: 'expired'),
+      throwsA(
+        isA<VerificationException>().having(
+          (e) => e.code,
+          'code',
+          VerificationError.expired,
+        ),
+      ),
+    );
+  });
+  test(
+    'resend preserves server challenge and retries the same delivery key',
+    () async {
+      final now = DateTime.now();
+      final keys = <String>[];
+      Map<String, Object?> challenge() => {
+        'userId': 'user',
+        'pendingToken': {'token': 'pending'},
+        'challengeId': 'server-challenge',
+        'channel': 'email',
+        'target': 's***@example.com',
+        'expiresAt': now.add(const Duration(minutes: 10)).toIso8601String(),
+        'resendAt': now.add(const Duration(minutes: 1)).toIso8601String(),
+      };
+      final service = BackendAuthServices(
+        baseUri: Uri.parse('https://api.example/api/v1'),
+        clientId: 'web',
+        client: MockClient((request) async {
+          if (request.url.path.endsWith('/login')) return response(challenge());
+          final body = jsonDecode(request.body);
+          expect(body['challengeId'], 'server-challenge');
+          expect(body['pendingToken'], 'pending');
+          keys.add(body['idempotencyKey'] as String);
+          if (keys.length == 1) return response({'error': 'unavailable'}, 503);
+          return response(challenge());
+        }),
+      );
+      addTearDown(service.close);
+      final result = await service.login(
+        const LoginRequest(
+          email: 'user@example.com',
+          password: 'password',
+          locale: 'en',
+        ),
+      );
+      final id = result.challenge!.id;
+      await expectLater(service.resend(id), throwsA(isA<FactorException>()));
+      final resent = await service.resend(id);
+      expect(resent.id, id);
+      expect(resent.target, 's***@example.com');
+      expect(keys[0], keys[1]);
+      expect(service.session, isNull);
+    },
+  );
+  for (final channel in ['sms', '']) {
+    test(
+      'unsupported or missing channel $channel cannot create a login challenge',
+      () async {
+        final service = BackendAuthServices(
+          baseUri: Uri.parse('https://api.example/api/v1'),
+          clientId: 'web',
+          client: MockClient(
+            (_) async =>
+                response({'challengeId': 'server', 'channel': channel}),
+          ),
+        );
+        addTearDown(service.close);
+        await expectLater(
+          service.login(
+            const LoginRequest(
+              email: 'user@example.com',
+              password: 'password',
+              locale: 'en',
+            ),
+          ),
+          throwsA(isA<FactorException>()),
+        );
+        expect(service.session, isNull);
+      },
+    );
+  }
+}