《MMO 服务器开发》7.1 权限与审计

// file: internal/gm/rbac.go
// tier: L1
// verify: go test ./internal/gm/
// Package gm is the operations domain of aegis: the permission model behind the
// GM console, the command bus that carries an operator action to a live shard,
// and the repair workflow customer service runs to fix a broken character.
//
// This file holds section 7.1: role-based access control and the append-only
// audit log. A console user acts through a role, a role grants a fixed set of
// permissions, a few permissions are high-risk and need two approvers, and
// every action lands in a tamper-evident log.
package gm

import (
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"time"
)

// Permission names one action a GM console user may perform.
type Permission string

const (
	PermPlayerQuery    Permission = "player:query"
	PermItemGrant      Permission = "item:grant"
	PermCurrencyAdjust Permission = "currency:adjust"
	PermPlayerKick     Permission = "player:kick"
	PermPlayerBan      Permission = "player:ban"
	PermConfigEdit     Permission = "config:edit"
	PermConfigPush     Permission = "config:push"
	PermDataRepair     Permission = "data:repair"
)

// Role names a GM console role, ordered by blast radius: a viewer only looks,
// ops never touches a character, and only admin spans both halves.
type Role string

const (
	RoleViewer Role = "viewer"
	RoleCS     Role = "cs"
	RoleGM     Role = "gm"
	RoleOps    Role = "ops"
	RoleAdmin  Role = "admin"
)

// rolePerms is the permission matrix. A permission absent from a role's set is
// denied; there is no inheritance and no wildcard, because a wildcard is how a
// "temporary" grant becomes permanent.
var rolePerms = map[Role]map[Permission]bool{
	RoleViewer: {PermPlayerQuery: true},
	RoleCS:     {PermPlayerQuery: true, PermItemGrant: true, PermCurrencyAdjust: true, PermDataRepair: true},
	RoleGM:     {PermPlayerQuery: true, PermItemGrant: true, PermCurrencyAdjust: true, PermPlayerKick: true, PermPlayerBan: true, PermDataRepair: true},
	RoleOps:    {PermPlayerQuery: true, PermConfigEdit: true, PermConfigPush: true},
	RoleAdmin:  {PermPlayerQuery: true, PermItemGrant: true, PermCurrencyAdjust: true, PermPlayerKick: true, PermPlayerBan: true, PermConfigEdit: true, PermConfigPush: true, PermDataRepair: true},
}

// Can reports whether a role may perform a permission. An unknown role is
// denied, never defaulted to allow.
func Can(r Role, p Permission) bool { return rolePerms[r][p] }

// highRisk lists the permissions that change value or reach a live shard
// irreversibly; they need a second pair of eyes.
var highRisk = map[Permission]bool{
	PermCurrencyAdjust: true, PermPlayerBan: true, PermConfigPush: true, PermDataRepair: true,
}

// HighRisk reports whether a permission needs two-person approval.
func HighRisk(p Permission) bool { return highRisk[p] }

// Approval tracks the approvers of one high-risk action. A non-high-risk action
// is always Ready; a high-risk one needs two distinct approvers.
type Approval struct {
	Permission Permission
	Target     string
	approvers  []string
}

// NewApproval starts an approval record for one action.
func NewApproval(p Permission, target string) *Approval {
	return &Approval{Permission: p, Target: target}
}

// Approve records one operator's approval. The same operator approving twice is
// rejected: two-person approval means two people, not one person twice.
func (a *Approval) Approve(operator string) error {
	if !HighRisk(a.Permission) {
		return fmt.Errorf("gm: %s is not high-risk", a.Permission)
	}
	for _, x := range a.approvers {
		if x == operator {
			return fmt.Errorf("gm: %s already approved", operator)
		}
	}
	a.approvers = append(a.approvers, operator)
	return nil
}

// Approvers returns a copy of the approver list.
func (a *Approval) Approvers() []string { return append([]string(nil), a.approvers...) }

// Ready reports whether the action may proceed.
func (a *Approval) Ready() bool { return !HighRisk(a.Permission) || len(a.approvers) >= 2 }

// AuditRecord answers the five questions every GM action must answer: who did
// it, when, to whom, what was done, and how it ended.
type AuditRecord struct {
	Seq      uint64
	Operator string
	Role     Role
	Action   Permission
	Target   string
	Detail   string
	Result   string
	At       time.Time
	PrevHash string
	Hash     string
}

// AuditLog is append-only by API: Append and a read-only Records view, no
// update or delete. Each record carries its predecessor's hash, so removing or
// editing a past line breaks Verify.
type AuditLog struct {
	recs []AuditRecord
	head string
}

// NewAuditLog returns an empty log rooted at a genesis hash.
func NewAuditLog() *AuditLog { return &AuditLog{head: "genesis"} }

// Append fills in Seq, PrevHash and Hash; the caller supplies the rest.
func (l *AuditLog) Append(r AuditRecord) AuditRecord {
	r.Seq = uint64(len(l.recs)) + 1
	r.PrevHash = l.head
	r.Hash = hashRecord(r)
	l.head = r.Hash
	l.recs = append(l.recs, r)
	return r
}

func hashRecord(r AuditRecord) string {
	h := sha256.New()
	fmt.Fprintf(h, "%d|%s|%s|%s|%s|%s|%s|%s|%s",
		r.Seq, r.Operator, r.Role, r.Action, r.Target, r.Detail, r.Result,
		r.At.UTC().Format(time.RFC3339Nano), r.PrevHash)
	return hex.EncodeToString(h.Sum(nil))
}

// Records returns a copy, so a caller cannot mutate the stored slice.
func (l *AuditLog) Records() []AuditRecord {
	out := make([]AuditRecord, len(l.recs))
	copy(out, l.recs)
	return out
}

// Verify recomputes the chain and reports the first record that does not match.
func (l *AuditLog) Verify() error {
	prev := "genesis"
	for i, r := range l.recs {
		if r.PrevHash != prev {
			return fmt.Errorf("gm: audit record %d has a broken chain link", i+1)
		}
		if hashRecord(r) != r.Hash {
			return fmt.Errorf("gm: audit record %d content does not match its hash", i+1)
		}
		prev = r.Hash
	}
	return nil
}

// file: internal/gm/rbac_test.go
// tier: L1
// verify: go test ./internal/gm/
package gm

import (
	"testing"
	"time"
)

func TestRolePermissionMatrix(t *testing.T) {
	// The matrix is the contract of section 7.1: a viewer looks, cs grants and
	// repairs but never bans or touches config, ops owns config only.
	cases := []struct {
		role Role
		perm Permission
		want bool
	}{
		{RoleViewer, PermPlayerQuery, true},
		{RoleViewer, PermItemGrant, false},
		{RoleCS, PermItemGrant, true},
		{RoleCS, PermDataRepair, true},
		{RoleCS, PermPlayerBan, false},
		{RoleGM, PermPlayerBan, true},
		{RoleGM, PermConfigPush, false},
		{RoleOps, PermConfigPush, true},
		{RoleOps, PermItemGrant, false},
		{RoleAdmin, PermConfigPush, true},
		{Role("unknown"), PermPlayerQuery, false},
	}
	for _, c := range cases {
		if got := Can(c.role, c.perm); got != c.want {
			t.Errorf("Can(%s, %s) = %v, want %v", c.role, c.perm, got, c.want)
		}
	}
}

func TestHighRiskNeedsTwoDistinctApprovers(t *testing.T) {
	a := NewApproval(PermCurrencyAdjust, "player:1001")
	if a.Ready() || a.Approve("alice") != nil || a.Ready() {
		t.Fatal("a high-risk action needs two approvers, not one")
	}
	if a.Approve("alice") == nil {
		t.Fatal("the same operator must not approve twice")
	}
	if a.Approve("bob") != nil || !a.Ready() {
		t.Fatal("two distinct approvers must make the action ready")
	}
	if !NewApproval(PermPlayerQuery, "p").Ready() {
		t.Fatal("a read-only action is ready without approval")
	}
}

func TestAuditLogIsTamperEvident(t *testing.T) {
	at := time.Date(2026, 10, 11, 20, 0, 0, 0, time.UTC)
	log := NewAuditLog()
	rec := log.Append(AuditRecord{Operator: "alice", Role: RoleCS, Action: PermItemGrant, Target: "player:1001", Detail: "item=1001 x5", Result: "ok", At: at})
	if rec.Seq != 1 || rec.Operator != "alice" || rec.Action != PermItemGrant || rec.Target != "player:1001" || rec.Result != "ok" || rec.PrevHash != "genesis" {
		t.Fatal("a record must carry who / what / whom / result and link to genesis")
	}
	log.Append(AuditRecord{Operator: "bob", Role: RoleGM, Action: PermPlayerBan, Target: "p:2", Result: "ok", At: at})
	if err := log.Verify(); err != nil {
		t.Fatalf("a fresh log must verify: %v", err)
	}
	log.recs[1].Result = "covered up" // simulate an edit past the append-only API
	if log.Verify() == nil {
		t.Fatal("editing a record must break the hash chain")
	}
}

=== RUN   TestRolePermissionMatrix
--- PASS: TestRolePermissionMatrix (0.00s)
=== RUN   TestHighRiskNeedsTwoDistinctApprovers
--- PASS: TestHighRiskNeedsTwoDistinctApprovers (0.00s)
=== RUN   TestAuditLogIsTamperEvident
--- PASS: TestAuditLogIsTamperEvident (0.00s)
PASS
ok  	aegis/internal/gm	0.527s