《游戏服务端编程实践》4.1.3 账号绑定与安全策略

// file: ch04/identity/policy.go
// tier: L1
// verify: go test ./ch04/identity/

package identity

import (
	"errors"
	"sort"
	"strings"
	"time"
)

type Provider string

const (
	ProviderEmail Provider = "email"
	ProviderPhone Provider = "phone"
	ProviderSteam Provider = "steam"
)

type BindingStatus string

const (
	BindingActive  BindingStatus = "active"
	BindingRevoked BindingStatus = "revoked"
)

// Binding is one verified external identity owned by an account.
type Binding struct {
	AccountID  AccountID
	Provider   Provider
	ExternalID string
	VerifiedAt time.Time
	Status     BindingStatus
}

var (
	ErrInvalidBinding = errors.New("identity: provider or external id is empty")
	ErrExternalBound  = errors.New("identity: external identity is bound to another account")
	ErrBindingMissing = errors.New("identity: binding not found")
	ErrBindingRevoked = errors.New("identity: binding is not active")
	ErrLastCredential = errors.New("identity: cannot unbind the last verified credential")
	ErrCooldown       = errors.New("identity: binding change is in cooldown")
	ErrStepUpRequired = errors.New("identity: step-up verification required")
)

type RiskLevel int

const (
	RiskLow RiskLevel = iota
	RiskMedium
	RiskHigh
	RiskCritical
)

type Operation string

const (
	OpLogin          Operation = "login"
	OpRefresh        Operation = "refresh"
	OpBind           Operation = "bind"
	OpUnbind         Operation = "unbind"
	OpChangePassword Operation = "change_password"
	OpDeleteAccount  Operation = "delete_account"
)

func RiskOf(op Operation) RiskLevel {
	switch op {
	case OpLogin, OpRefresh:
		return RiskLow
	case OpBind, OpUnbind:
		return RiskHigh
	case OpChangePassword, OpDeleteAccount:
		return RiskCritical
	default:
		return RiskHigh
	}
}

// RiskSignals are cheap hints collected before a sensitive decision. They
// raise the bar; they never replace authentication.
type RiskSignals struct {
	BindFailures  int
	NewCountry    bool
	DeviceChanged bool
}

func (s RiskSignals) Score() int {
	score := 0
	if s.BindFailures >= 3 {
		score += 3
	}
	if s.NewCountry {
		score += 2
	}
	if s.DeviceChanged {
		score++
	}
	return score
}

func RequireStepUp(op Operation, sig RiskSignals) bool {
	if RiskOf(op) >= RiskHigh {
		return true
	}
	return sig.Score() >= 3
}

// AuthContext is the session that requests the operation. StepUpSession must
// equal SessionID so a code verified in one session cannot authorize another.
type AuthContext struct {
	AccountID         AccountID
	SessionID         string
	StepUpSession     string
	StepUpAt          time.Time
	LastBindingChange time.Time
}

func StepUpFresh(ctx AuthContext, now time.Time) bool {
	if ctx.StepUpAt.IsZero() || ctx.StepUpSession == "" {
		return false
	}
	if ctx.StepUpSession != ctx.SessionID {
		return false
	}
	return now.Sub(ctx.StepUpAt) <= 10*time.Minute
}

// CanUnbind is the last gate before removing a credential. The caller must
// re-check ownership and step-up even if the UI already asked for a code.
func CanUnbind(b Binding, ctx AuthContext, activeCount int, now time.Time) error {
	if b.Status != BindingActive {
		return ErrBindingRevoked
	}
	if !StepUpFresh(ctx, now) {
		return ErrStepUpRequired
	}
	if activeCount <= 1 {
		return ErrLastCredential
	}
	if !ctx.LastBindingChange.IsZero() && now.Sub(ctx.LastBindingChange) < 24*time.Hour {
		return ErrCooldown
	}
	return nil
}

// BindingStore enforces one owner per (provider, external id).
type BindingStore struct {
	byKey map[string]Binding
}

func NewBindingStore() *BindingStore {
	return &BindingStore{byKey: make(map[string]Binding)}
}

func bindingKey(provider Provider, externalID string) string {
	return string(provider) + "\x00" + externalID
}

func (s *BindingStore) Bind(b Binding, now time.Time) error {
	b.ExternalID = strings.TrimSpace(b.ExternalID)
	if b.Provider == "" || b.ExternalID == "" {
		return ErrInvalidBinding
	}
	key := bindingKey(b.Provider, b.ExternalID)
	if old, ok := s.byKey[key]; ok {
		if old.Status == BindingActive && old.AccountID != b.AccountID {
			return ErrExternalBound
		}
	}
	b.VerifiedAt = now.UTC()
	b.Status = BindingActive
	s.byKey[key] = b
	return nil
}

func (s *BindingStore) Unbind(accountID AccountID, provider Provider, externalID string) error {
	key := bindingKey(provider, externalID)
	b, ok := s.byKey[key]
	if !ok || b.AccountID != accountID {
		return ErrBindingMissing
	}
	b.Status = BindingRevoked
	s.byKey[key] = b
	return nil
}

func (s *BindingStore) Lookup(provider Provider, externalID string) (Binding, bool) {
	b, ok := s.byKey[bindingKey(provider, externalID)]
	return b, ok
}

func (s *BindingStore) ActiveCount(accountID AccountID) int {
	n := 0
	for _, b := range s.byKey {
		if b.AccountID == accountID && b.Status == BindingActive {
			n++
		}
	}
	return n
}

// Session is one login session. RefreshToken and GatewayConn are revoked
// together; leaving either alive after a binding change keeps an attacker in.
type Session struct {
	ID           string
	AccountID    AccountID
	RefreshToken string
	GatewayConn  string
}

type SessionStore struct {
	byAccount map[AccountID]map[string]Session
}

func NewSessionStore() *SessionStore {
	return &SessionStore{byAccount: make(map[AccountID]map[string]Session)}
}

func (s *SessionStore) Add(sess Session) {
	if s.byAccount[sess.AccountID] == nil {
		s.byAccount[sess.AccountID] = make(map[string]Session)
	}
	s.byAccount[sess.AccountID][sess.ID] = sess
}

// RevokeSessionsOnChange removes every session of the account and returns a
// snapshot so the caller can disconnect gateway connections and audit them.
func RevokeSessionsOnChange(store *SessionStore, accountID AccountID) []Session {
	if store.byAccount[accountID] == nil {
		return nil
	}
	out := make([]Session, 0, len(store.byAccount[accountID]))
	for _, sess := range store.byAccount[accountID] {
		out = append(out, sess)
	}
	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
	delete(store.byAccount, accountID)
	return out
}

func (s *SessionStore) Count(accountID AccountID) int {
	return len(s.byAccount[accountID])
}