《游戏服务端架构·核心系统与契约》1.3 账号安全、找回与风控

// file: internal/accountrisk/risk.go
// tier: L1
// verify: go test ./internal/accountrisk/
package accountrisk

import (
	"time"
)

type Action string

const (
	Allow     Action = "ALLOW"
	Challenge Action = "CHALLENGE"
	Block     Action = "BLOCK"
)

// Request is what the login edge already knows before it asks for a decision.
// It deliberately contains no password, token or provider secret.
type Request struct {
	RequestID      string
	AccountID      string
	DeviceID       string
	KnownDevice    bool
	Geo            string
	LastGeo        string
	Guest          bool
	AccountAgeDays int
}

// Policy is deployment configuration. Thresholds are integers because the
// score is an explanation tool, not a probability.
type Policy struct {
	ChallengeAt    int
	BlockAt        int
	FailureBlockAt int
	FailureWindow  time.Duration
	LockFor        time.Duration
}

func DefaultPolicy() Policy {
	return Policy{
		ChallengeAt:    30,
		BlockAt:        70,
		FailureBlockAt: 8,
		FailureWindow:  15 * time.Minute,
		LockFor:        15 * time.Minute,
	}
}

// Decision is both the answer and the audit record. Rules names the exact
// signals that fired, so support can explain a challenge without replaying
// the score by hand.
type Decision struct {
	RequestID string
	AccountID string
	Action    Action
	Score     int
	Rules     []string
	LockUntil time.Time
	At        time.Time
}

type Engine struct {
	policy   Policy
	clock    func() time.Time
	locks    map[string]time.Time
	failures map[string][]time.Time
	events   []Decision
}

func New(policy Policy, clock func() time.Time) *Engine {
	return &Engine{
		policy:   policy,
		clock:    clock,
		locks:    make(map[string]time.Time),
		failures: make(map[string][]time.Time),
	}
}

// NoteFailure records one failed credential attempt and returns the count
// still inside the window. The window is what keeps a bad night from becoming
// a permanent lock: old failures age out instead of accumulating forever.
func (e *Engine) NoteFailure(accountID string) int {
	now := e.clock()
	kept := e.trim(accountID, now)
	kept = append(kept, now)
	e.failures[accountID] = kept
	return len(kept)
}

func (e *Engine) ResetFailures(accountID string) {
	delete(e.failures, accountID)
}

func (e *Engine) trim(accountID string, now time.Time) []time.Time {
	cutoff := now.Add(-e.policy.FailureWindow)
	old := e.failures[accountID]
	kept := make([]time.Time, 0, len(old))
	for _, at := range old {
		if at.After(cutoff) {
			kept = append(kept, at)
		}
	}
	return kept
}

// Evaluate returns allow, challenge or block. A block always carries an
// expiry; there is no code path that produces an indefinite lock.
func (e *Engine) Evaluate(req Request) Decision {
	now := e.clock()
	d := Decision{RequestID: req.RequestID, AccountID: req.AccountID, At: now}
	if until, ok := e.locks[req.AccountID]; ok {
		if now.Before(until) {
			d.Action = Block
			d.LockUntil = until
			d.Rules = []string{"lock.active"}
			e.record(d)
			return d
		}
		delete(e.locks, req.AccountID)
	}

	score, rules := e.score(req, now)
	failures := len(e.trim(req.AccountID, now))
	d.Score = score
	d.Rules = rules
	switch {
	case failures >= e.policy.FailureBlockAt:
		d.Action = Block
		d.Rules = append(d.Rules, "auth.failures.block")
	case score >= e.policy.BlockAt:
		d.Action = Block
	case score >= e.policy.ChallengeAt:
		d.Action = Challenge
	default:
		d.Action = Allow
	}
	if d.Action == Block {
		d.LockUntil = now.Add(e.policy.LockFor)
		e.locks[req.AccountID] = d.LockUntil
	}
	e.record(d)
	return d
}

func (e *Engine) score(req Request, now time.Time) (int, []string) {
	score := 0
	rules := make([]string, 0, 5)
	add := func(id string, weight int) {
		score += weight
		rules = append(rules, id)
	}
	if !req.KnownDevice {
		add("device.new", 30)
	}
	if req.LastGeo != "" && req.LastGeo != req.Geo {
		add("geo.jump", 25)
	}
	if req.Guest {
		add("credential.guest", 10)
	}
	if req.AccountAgeDays >= 0 && req.AccountAgeDays < 3 {
		add("account.young", 10)
	}
	if failures := len(e.trim(req.AccountID, now)); failures >= 3 {
		add("auth.failures", 15)
	}
	return score, rules
}

func (e *Engine) record(d Decision) {
	d.Rules = append([]string(nil), d.Rules...)
	e.events = append(e.events, d)
}

$ go test -count=1 ./internal/accountrisk/
ok  	gsarchlab/internal/accountrisk	0.498s