《MMO 服务器开发》6.3 断线重连与重连票据

body  = ver(1) | connSeq(8) | expiryUnix(8) | nonce(16) | accountLen(2) | account(N)
token = base64url(body) + "." + base64url(HMAC-SHA256(secret, body))

// file: internal/ws/ticket.go
// tier: L1
// verify: go test ./internal/ws/ -run TestTicket -v

package ws

import (
	"crypto/hmac"
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
	"encoding/binary"
	"errors"
	"fmt"
	"strings"
	"sync"
	"time"
)

// Ticket errors stay distinct so the gateway can log why a reconnect was
// refused without telling the client which check failed.
var (
	ErrTicketMalformed = errors.New("ws: malformed ticket")
	ErrTicketSignature = errors.New("ws: ticket signature mismatch")
	ErrTicketExpired   = errors.New("ws: ticket expired")
	ErrTicketReplayed  = errors.New("ws: ticket already used")
)

// Ticket is the verified payload of a reconnection credential.
type Ticket struct {
	Account string
	ConnSeq uint64
	Expiry  time.Time
}

// TicketManager issues and verifies short-lived reconnection tickets. The
// signature is HMAC-SHA256 over a compact binary body; single use is enforced
// by remembering each ticket's nonce until it expires.
type TicketManager struct {
	secret []byte

	mu   sync.Mutex
	used map[string]time.Time // nonce -> expiry
}

// NewTicketManager builds a manager from a shared secret. In production the
// secret lives in the session/keys service, never on the client.
func NewTicketManager(secret []byte) *TicketManager {
	return &TicketManager{secret: secret, used: make(map[string]time.Time)}
}

const ticketVersion byte = 1

// body layout (big endian): ver(1) | connSeq(8) | expiryUnix(8) | nonce(16) |
// accountLen(2) | account. The nonce makes every issued ticket unique even for
// the same account and second, which is what the replay table keys on.
func (m *TicketManager) sign(body []byte) []byte {
	h := hmac.New(sha256.New, m.secret)
	h.Write(body)
	return h.Sum(nil)
}

// Issue mints a ticket bound to an account and the connection sequence number
// the client should resume from.
func (m *TicketManager) Issue(account string, connSeq uint64, ttl time.Duration, now time.Time) (string, error) {
	if len(account) > 0xFFFF {
		return "", fmt.Errorf("ws: account too long")
	}
	var nonce [16]byte
	if _, err := rand.Read(nonce[:]); err != nil {
		return "", err
	}
	body := make([]byte, 0, 1+8+8+16+2+len(account))
	body = append(body, ticketVersion)
	var tmp [8]byte
	binary.BigEndian.PutUint64(tmp[:], connSeq)
	body = append(body, tmp[:]...)
	binary.BigEndian.PutUint64(tmp[:], uint64(now.Add(ttl).Unix()))
	body = append(body, tmp[:]...)
	body = append(body, nonce[:]...)
	var l [2]byte
	binary.BigEndian.PutUint16(l[:], uint16(len(account)))
	body = append(body, l[:]...)
	body = append(body, account...)

	return base64.RawURLEncoding.EncodeToString(body) + "." +
		base64.RawURLEncoding.EncodeToString(m.sign(body)), nil
}

// Verify checks the signature, the expiry, and single use. On success the
// ticket is consumed: a second Verify of the same token returns
// ErrTicketReplayed.
func (m *TicketManager) Verify(token string, now time.Time) (*Ticket, error) {
	dot := strings.IndexByte(token, '.')
	if dot < 0 {
		return nil, ErrTicketMalformed
	}
	body, err := base64.RawURLEncoding.DecodeString(token[:dot])
	if err != nil {
		return nil, ErrTicketMalformed
	}
	sig, err := base64.RawURLEncoding.DecodeString(token[dot+1:])
	if err != nil {
		return nil, ErrTicketMalformed
	}
	// Constant-time compare; bytes.Equal would leak how much of the signature
	// the attacker guessed right.
	if !hmac.Equal(sig, m.sign(body)) {
		return nil, ErrTicketSignature
	}
	if len(body) < 35 || body[0] != ticketVersion {
		return nil, ErrTicketMalformed
	}
	connSeq := binary.BigEndian.Uint64(body[1:9])
	expiry := time.Unix(int64(binary.BigEndian.Uint64(body[9:17])), 0)
	nonce := string(body[17:33])
	alen := int(binary.BigEndian.Uint16(body[33:35]))
	if len(body) != 35+alen {
		return nil, ErrTicketMalformed
	}
	if now.After(expiry) {
		return nil, ErrTicketExpired
	}

	// Replay table, locked separately so the crypto above never holds it.
	m.mu.Lock()
	defer m.mu.Unlock()
	m.gcLocked(now)
	if _, seen := m.used[nonce]; seen {
		return nil, ErrTicketReplayed
	}
	m.used[nonce] = expiry

	return &Ticket{
		Account: string(body[35:]),
		ConnSeq: connSeq,
		Expiry:  expiry,
	}, nil
}

// gcLocked drops nonces whose tickets can no longer be replayed.
func (m *TicketManager) gcLocked(now time.Time) {
	for nonce, exp := range m.used {
		if now.After(exp) {
			delete(m.used, nonce)
		}
	}
}

// snippet: internal/ws/ticket_test.go（节选）

// TestTicketReplay is the anti-replay guarantee: the first Verify consumes the
// ticket, the second must be refused even though the signature is still valid.
func TestTicketReplay(t *testing.T) {
	m := NewTicketManager([]byte("k"))
	now := time.Unix(1_760_000_000, 0)
	tok, _ := m.Issue("alice", 1, time.Minute, now)

	if _, err := m.Verify(tok, now); err != nil {
		t.Fatalf("first verify: %v", err)
	}
	if _, err := m.Verify(tok, now.Add(time.Second)); !errors.Is(err, ErrTicketReplayed) {
		t.Fatalf("want ErrTicketReplayed, got %v", err)
	}
}

func TestTicketExpired(t *testing.T) {
	m := NewTicketManager([]byte("k"))
	now := time.Unix(1_760_000_000, 0)
	tok, _ := m.Issue("alice", 1, 10*time.Second, now)
	if _, err := m.Verify(tok, now.Add(11*time.Second)); !errors.Is(err, ErrTicketExpired) {
		t.Fatalf("want ErrTicketExpired, got %v", err)
	}
}

// TestTicketTamperedBody swaps the account bytes without re-signing; the
// signature check must catch it before the account is ever trusted.
func TestTicketTamperedBody(t *testing.T) {
	m := NewTicketManager([]byte("k"))
	now := time.Unix(1_760_000_000, 0)
	tok, _ := m.Issue("alice", 1, time.Minute, now)

	dot := strings.IndexByte(tok, '.')
	body := []byte(tok[:dot])
	body[len(body)-1] = 'x' // alice -> alicx, still valid base64
	forged := string(body) + tok[dot:]
	if _, err := m.Verify(forged, now); !errors.Is(err, ErrTicketSignature) {
		t.Fatalf("want ErrTicketSignature, got %v", err)
	}
}