fix(verify): one-shot consumption of email confirmation tokens

The email confirmation JWT issued by VerifyHandler.sendConfirmation was
only protected by its 30-minute expiry: any party who could read the
confirmation link (forwarded email, mail-gateway logs, mailbox archive)
could redeem it independently within the window, creating a separate
authenticated session for the same address.

Add a VerifConfirmationStore interface (MarkUsed key, ttl -> bool) and a
default in-memory implementation (sync.Mutex-protected map keyed by
SHA-256 of the raw token). When VerifyHandler.ConfirmationStore is
non-nil, LoginHandler records the token as consumed on first redemption
and rejects replays with 403 "confirmation token already consumed".

The store key is the SHA-256 of the raw token rather than a jti claim,
so existing token fixtures (which carry no jti) are still de-dup'd
correctly without changing the wire format.

Wired through Service.AddVerifProvider in both auth.go and v2/auth.go.
The store is selected once via sync.Once, with this precedence:

  1. Opts.VerifConfirmationStore if non-nil (caller-supplied; required
     for multi-instance deployments — Redis or any shared KV).
  2. provider.NewInMemoryVerifStore() default — fine for single
     instance, broken for LB-fronted multi-instance deployments where
     instance A's "used" set is unknown to instance B. Documented in
     README under "Confirmation token replay protection".

Tests:
* TestInMemoryVerifStore — store-level coverage (replay, expiry, key
  independence).
* TestVerifyHandler_LoginAcceptConfirm_RejectsReplay — integration:
  same token redeemed twice -> 200 then 403.
* TestService_AddVerifProvider_UsesCustomConfirmationStore — Opts
  injection works.
* TestService_AddVerifProvider_DefaultsToInMemory — default install
  + sync.Once reuse on subsequent AddVerifProvider calls.

Author: paskal

README.md

@@ -296,6 +296,25 @@ The API for this provider:
 
 The provider acts like any other, i.e. will be registered as `/auth/email/login`.
 
+#### Confirmation token replay protection
+
+Confirmation tokens are one-shot: a token redeemed once cannot be redeemed again within its TTL. This stops anyone with read access to the email link (forwarded mail, mail-gateway logs, mailbox archive) from independently consuming it after the user has.
+
+By default the library installs an in-memory store on first call to `AddVerifProvider`. This is correct for **single-instance** deployments.
+
+**Multi-instance deployments behind a load balancer MUST supply a shared backend.** With the default in-memory store, replay protection works only on the instance that originally consumed the token; an attacker who hits any other instance can still replay within the TTL. **This is silent: the request succeeds and the auth flow completes normally, with no log indicating the protection was bypassed.** Plug in Redis or any shared KV by setting `Opts.VerifConfirmationStore` to a value implementing `provider.VerifConfirmationStore`:
+
+```go
+type VerifConfirmationStore interface {
+    // MarkUsed records key as consumed and returns alreadyUsed=true if it was
+    // already recorded. err signals a backend failure -- callers fail-closed
+    // (reject the redemption) on non-nil err to avoid replay during outages.
+    MarkUsed(key string, ttl time.Duration) (alreadyUsed bool, err error)
+}
+```
+
+The store key is the SHA-256 of the raw confirmation token, so existing tokens issued before this protection landed are de-dup'd correctly without changing the wire format. Consumption is final: a transient downstream failure after the mark burns the token; the user must request a new confirmation email rather than retry the same link.
+
 #### Email-as-identity caveat
 
 The verify provider returns a local user id of the form `<provider>_<sha1(address)>`. The confirmation round-trip proves current control of the address at the moment of login; it does **not** prove stable+unique identity over time. The owner of an address can change without the address changing:

auth.go

@@ -7,6 +7,7 @@ import (
 	"net/url"
 	"regexp"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/go-pkgz/rest"
@@ -26,14 +27,16 @@ type Client struct {
 
 // Service provides higher level wrapper allowing to construct everything and get back token middleware
 type Service struct {
-	logger         logger.L
-	opts           Opts
-	jwtService     *token.Service
-	providers      []provider.Service
-	authMiddleware middleware.Authenticator
-	avatarProxy    *avatar.Proxy
-	issuer         string
-	useGravatar    bool
+	logger             logger.L
+	opts               Opts
+	jwtService         *token.Service
+	providers          []provider.Service
+	authMiddleware     middleware.Authenticator
+	avatarProxy        *avatar.Proxy
+	issuer             string
+	useGravatar        bool
+	verifConfirmStore  provider.VerifConfirmationStore
+	verifConfirmStoreO sync.Once
 }
 
 // Opts is a full set of all parameters to initialize Service
@@ -83,6 +86,15 @@ type Opts struct {
 	AudSecrets       bool                     // allow multiple secrets (secret per aud)
 	Logger           logger.L                 // logger interface, default is no logging at all
 	RefreshCache     middleware.RefreshCache  // optional cache to keep refreshed tokens
+
+	// VerifConfirmationStore enforces one-shot consumption of email
+	// confirmation tokens issued by the verify provider. The default
+	// (nil) installs an in-memory store on first use of AddVerifProvider —
+	// fine for single-instance deployments. Multi-instance deployments
+	// MUST supply a shared backend (e.g. Redis) implementing
+	// provider.VerifConfirmationStore, otherwise replay rejection works
+	// only on the instance that consumed the token.
+	VerifConfirmationStore provider.VerifConfirmationStore
 }
 
 // NewService initializes everything
@@ -434,6 +446,13 @@ func (s *Service) AddDirectProviderWithUserIDFunc(name string, credChecker provi
 
 // AddVerifProvider adds provider user's verification sent by sender
 func (s *Service) AddVerifProvider(name, msgTmpl string, sender provider.Sender) {
+	s.verifConfirmStoreO.Do(func() {
+		if s.opts.VerifConfirmationStore != nil {
+			s.verifConfirmStore = s.opts.VerifConfirmationStore
+			return
+		}
+		s.verifConfirmStore = provider.NewInMemoryVerifStore()
+	})
 	dh := provider.VerifyHandler{
 		L:                    s.logger,
 		ProviderName:         name,
@@ -445,6 +464,7 @@ func (s *Service) AddVerifProvider(name, msgTmpl string, sender provider.Sender)
 		UseGravatar:          s.useGravatar,
 		URL:                  s.opts.URL,
 		AllowedRedirectHosts: s.opts.AllowedRedirectHosts,
+		ConfirmationStore:    s.verifConfirmStore,
 	}
 	s.addProvider(dh)
 }

auth_test.go

@@ -117,6 +117,39 @@ func TestService_AddMicrosoftProvider(t *testing.T) {
 	})
 }
 
+func TestService_AddVerifProvider_UsesCustomConfirmationStore(t *testing.T) {
+	custom := &countingVerifStore{}
+	svc := NewService(Opts{
+		SecretReader:           token.SecretFunc(func(string) (string, error) { return "secret", nil }),
+		URL:                    "http://127.0.0.1",
+		Logger:                 logger.Std,
+		VerifConfirmationStore: custom,
+	})
+	svc.AddVerifProvider("email", "{{.Token}}", provider.SenderFunc(func(string, string) error { return nil }))
+	assert.Same(t, custom, svc.verifConfirmStore, "custom store from Opts must be used, not the in-memory default")
+}
+
+func TestService_AddVerifProvider_DefaultsToInMemory(t *testing.T) {
+	svc := NewService(Opts{
+		SecretReader: token.SecretFunc(func(string) (string, error) { return "secret", nil }),
+		URL:          "http://127.0.0.1",
+		Logger:       logger.Std,
+	})
+	svc.AddVerifProvider("email", "{{.Token}}", provider.SenderFunc(func(string, string) error { return nil }))
+	require.NotNil(t, svc.verifConfirmStore, "default store must be installed when Opts.VerifConfirmationStore is nil")
+	// second call must reuse the same store (sync.Once guards against re-init)
+	first := svc.verifConfirmStore
+	svc.AddVerifProvider("email2", "{{.Token}}", provider.SenderFunc(func(string, string) error { return nil }))
+	assert.Same(t, first, svc.verifConfirmStore, "subsequent AddVerifProvider calls must reuse the same store")
+}
+
+type countingVerifStore struct{ calls int }
+
+func (s *countingVerifStore) MarkUsed(string, time.Duration) (bool, error) {
+	s.calls++
+	return false, nil
+}
+
 func TestService_AddAppleProvider(t *testing.T) {
 
 	options := Opts{

provider/verify.go

@@ -3,10 +3,13 @@ package provider
 import (
 	"bytes"
 	"crypto/sha1"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"html/template"
 	"net/http"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/go-pkgz/rest"
@@ -50,6 +53,87 @@ type VerifyHandler struct {
 	// here. Nil disables validation and preserves legacy permissive
 	// behavior — any non-empty "from" value is honored.
 	AllowedRedirectHosts token.AllowedHosts
+
+	// ConfirmationStore enforces one-shot consumption of confirmation tokens.
+	// When non-nil, a token cannot be redeemed twice within its TTL window.
+	// Leave nil to keep the legacy behavior (token replayable until expiry).
+	ConfirmationStore VerifConfirmationStore
+}
+
+// VerifConfirmationStore tracks consumed confirmation tokens to prevent replay.
+// Implementations must be safe for concurrent use.
+type VerifConfirmationStore interface {
+	// MarkUsed records key as consumed and returns alreadyUsed=true if it was
+	// already recorded. ttl is an upper bound on how long the entry needs to
+	// live; the implementation may evict earlier under memory pressure. err
+	// signals a backend failure (network, disk, etc.) -- callers MUST treat a
+	// non-nil err as fail-closed (reject the redemption) to avoid replay
+	// during outages.
+	MarkUsed(key string, ttl time.Duration) (alreadyUsed bool, err error)
+}
+
+// VerifConfirmationStoreFunc is an adapter to use ordinary functions as
+// VerifConfirmationStore, mirroring the SenderFunc / token.AllowedHostsFunc
+// house pattern for closure-based config.
+type VerifConfirmationStoreFunc func(key string, ttl time.Duration) (alreadyUsed bool, err error)
+
+// MarkUsed calls f(key, ttl) to implement VerifConfirmationStore.
+func (f VerifConfirmationStoreFunc) MarkUsed(key string, ttl time.Duration) (bool, error) {
+	return f(key, ttl)
+}
+
+// NewInMemoryVerifStore returns a process-local default VerifConfirmationStore.
+// Suitable for single-instance deployments. Multi-instance deployments behind
+// a load balancer MUST supply a shared backend (e.g. Redis) -- otherwise an
+// attacker who lands on a different instance from the legitimate user can
+// replay the token there. The default's failure is silent: the request
+// completes normally and no log indicates the protection was bypassed.
+func NewInMemoryVerifStore() VerifConfirmationStore {
+	return &inMemoryVerifStore{used: make(map[string]time.Time)}
+}
+
+type inMemoryVerifStore struct {
+	mu          sync.Mutex
+	used        map[string]time.Time // key -> expiry
+	insertCount int
+}
+
+// inMemoryVerifStoreSweepEvery is the in-memory store's amortization cadence.
+// Walking the whole map on every redemption is O(n) under a single mutex,
+// which serializes the hot path. Sweeping every N inserts keeps the map size
+// bounded by ~N + (concurrent redemptions during the gap) without holding
+// the lock through a full walk on most calls.
+const inMemoryVerifStoreSweepEvery = 256
+
+func (s *inMemoryVerifStore) MarkUsed(key string, ttl time.Duration) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	now := time.Now()
+	if exp, ok := s.used[key]; ok && exp.After(now) {
+		return true, nil
+	}
+	// amortized eviction: walk the map only every Nth insert, not on every
+	// hot-path call. The lookup above already rejects unexpired duplicates,
+	// so worst-case staleness is bounded by N inserts between sweeps.
+	s.insertCount++
+	if s.insertCount >= inMemoryVerifStoreSweepEvery {
+		s.insertCount = 0
+		for k, exp := range s.used {
+			if !exp.After(now) {
+				delete(s.used, k)
+			}
+		}
+	}
+	s.used[key] = now.Add(ttl)
+	return false, nil
+}
+
+// confirmationKey hashes the raw token so the store key length is bounded
+// regardless of token size, and so the in-memory map doesn't retain the
+// signed token itself.
+func confirmationKey(rawToken string) string {
+	sum := sha256.Sum256([]byte(rawToken))
+	return hex.EncodeToString(sum[:])
 }
 
 // Sender defines interface to send emails
@@ -78,7 +162,13 @@ type VerifTokenService interface {
 func (e VerifyHandler) Name() string { return e.ProviderName }
 
 // LoginHandler gets name and address from query, makes confirmation token and sends it to user.
-// In case if confirmation token presented in the query uses it to create auth token
+// In case if confirmation token presented in the query uses it to create auth token.
+//
+// Consumption is final when ConfirmationStore is configured: the token is
+// marked used before any further side effects (avatar fetch, token issuance),
+// so a transient downstream failure burns the token and the user must request
+// a new confirmation email rather than retry the same link. This trade-off
+// keeps the replay check atomic with the security boundary.
 func (e VerifyHandler) LoginHandler(w http.ResponseWriter, r *http.Request) {
 
 	// GET /login?site=site&user=name&address=someone@example.com
@@ -101,6 +191,24 @@ func (e VerifyHandler) LoginHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if e.ConfirmationStore != nil {
+		ttl := time.Until(time.Unix(confClaims.ExpiresAt, 0))
+		if ttl <= 0 {
+			ttl = time.Minute
+		}
+		alreadyUsed, markErr := e.ConfirmationStore.MarkUsed(confirmationKey(tkn), ttl)
+		if markErr != nil {
+			// fail-closed: a backend outage must not let attackers replay
+			// tokens. Log and reject; the user can request a fresh email.
+			rest.SendErrorJSON(w, r, e.L, http.StatusForbidden, markErr, "confirmation token store unavailable")
+			return
+		}
+		if alreadyUsed {
+			rest.SendErrorJSON(w, r, e.L, http.StatusForbidden, fmt.Errorf("token already used"), "confirmation token already consumed")
+			return
+		}
+	}
+
 	elems := strings.Split(confClaims.Handshake.ID, "::")
 	if len(elems) != 2 {
 		rest.SendErrorJSON(w, r, e.L, http.StatusBadRequest, fmt.Errorf("%s", confClaims.Handshake.ID), "invalid handshake token")

provider/verify_test.go

@@ -6,6 +6,8 @@ import (
 	"net/http/httptest"
 	"net/url"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -259,6 +261,110 @@ func TestVerifyHandler_LoginAcceptConfirmFromAllowsAllowlistedHost(t *testing.T)
 	assert.Equal(t, "https://trusted.example.com/back", rr.Header().Get("Location"))
 }
 
+func TestInMemoryVerifStore(t *testing.T) {
+	mark := func(s VerifConfirmationStore, k string, ttl time.Duration) bool {
+		used, err := s.MarkUsed(k, ttl)
+		require.NoError(t, err)
+		return used
+	}
+
+	t.Run("first MarkUsed returns false, second returns true", func(t *testing.T) {
+		s := NewInMemoryVerifStore()
+		assert.False(t, mark(s, "k1", time.Hour), "first call must mark and return not-used")
+		assert.True(t, mark(s, "k1", time.Hour), "second call must report already-used")
+	})
+	t.Run("expired entry is not considered used", func(t *testing.T) {
+		s := NewInMemoryVerifStore()
+		assert.False(t, mark(s, "k1", time.Nanosecond))
+		time.Sleep(2 * time.Millisecond)
+		assert.False(t, mark(s, "k1", time.Hour), "expired entry should be reusable")
+	})
+	t.Run("distinct keys are independent", func(t *testing.T) {
+		s := NewInMemoryVerifStore()
+		assert.False(t, mark(s, "k1", time.Hour))
+		assert.False(t, mark(s, "k2", time.Hour))
+		assert.True(t, mark(s, "k1", time.Hour))
+		assert.True(t, mark(s, "k2", time.Hour))
+	})
+	t.Run("concurrent same-key redemption: exactly one succeeds", func(t *testing.T) {
+		s := NewInMemoryVerifStore()
+		const goroutines = 50
+		var wg sync.WaitGroup
+		successes := int32(0)
+		errs := int32(0)
+		wg.Add(goroutines)
+		for i := 0; i < goroutines; i++ {
+			go func() {
+				defer wg.Done()
+				used, err := s.MarkUsed("hot-key", time.Hour)
+				if err != nil {
+					atomic.AddInt32(&errs, 1)
+					return
+				}
+				if !used {
+					atomic.AddInt32(&successes, 1)
+				}
+			}()
+		}
+		wg.Wait()
+		assert.EqualValues(t, 0, errs)
+		assert.EqualValues(t, 1, successes, "exactly one redemption must observe alreadyUsed=false")
+	})
+}
+
+func TestVerifConfirmationStoreFunc(t *testing.T) {
+	calls := 0
+	var lastKey string
+	var lastTTL time.Duration
+	var s VerifConfirmationStore = VerifConfirmationStoreFunc(func(key string, ttl time.Duration) (bool, error) {
+		calls++
+		lastKey, lastTTL = key, ttl
+		return calls > 1, nil
+	})
+
+	used, err := s.MarkUsed("k1", 5*time.Minute)
+	require.NoError(t, err)
+	assert.False(t, used)
+	assert.Equal(t, "k1", lastKey)
+	assert.Equal(t, 5*time.Minute, lastTTL)
+
+	used, err = s.MarkUsed("k1", 5*time.Minute)
+	require.NoError(t, err)
+	assert.True(t, used)
+	assert.Equal(t, 2, calls)
+}
+
+func TestVerifyHandler_LoginAcceptConfirm_RejectsReplay(t *testing.T) {
+	e := VerifyHandler{
+		ProviderName: "test",
+		TokenService: token.NewService(token.Opts{
+			SecretReader:   token.SecretFunc(func(string) (string, error) { return "secret", nil }),
+			TokenDuration:  time.Hour,
+			CookieDuration: time.Hour * 24 * 31,
+		}),
+		Issuer:            "iss-test",
+		L:                 logger.Std,
+		ConfirmationStore: NewInMemoryVerifStore(),
+	}
+
+	handler := http.HandlerFunc(e.LoginHandler)
+
+	// first use: success
+	rr1 := httptest.NewRecorder()
+	req1, err := http.NewRequest("GET", "/login?token="+testConfirmedToken, http.NoBody)
+	require.NoError(t, err)
+	handler.ServeHTTP(rr1, req1)
+	require.Equal(t, 200, rr1.Code, "first consumption must succeed")
+
+	// second use: must be rejected
+	rr2 := httptest.NewRecorder()
+	req2, err := http.NewRequest("GET", "/login?token="+testConfirmedToken, http.NoBody)
+	require.NoError(t, err)
+	handler.ServeHTTP(rr2, req2)
+	assert.Equal(t, 403, rr2.Code, "replay must be rejected")
+	assert.Contains(t, rr2.Body.String(), "already")
+}
+
 func TestVerifyHandler_LoginAcceptConfirmWithAvatar(t *testing.T) {
 	e := VerifyHandler{
 		ProviderName: "test",