《游戏服务端架构·平台化与架构治理》3.1 权限、审批与双人复核

// file: internal/gmrbac/rbac.go
// tier: L1
// verify: go test ./internal/gmrbac/
package gmrbac

import (
	"errors"
	"time"
)

// Role is a duty, not a menu. Hiding a button only changes what an honest
// operator can click; the action check is what stops a crafted request.
type Role string

const (
	RoleCS      Role = "cs"
	RoleOps     Role = "ops"
	RoleGM      Role = "gm"
	RoleAdmin   Role = "admin"
	RoleAuditor Role = "auditor"
)

// Action names an effect on game state, never a screen. One screen can issue
// several actions, and one action can be reached from several screens.
type Action string

const (
	ActionViewProfile   Action = "player.view"
	ActionViewSensitive Action = "player.view_sensitive"
	ActionGrantItem     Action = "inventory.grant"
	ActionDeductItem    Action = "inventory.deduct"
	ActionBanAccount    Action = "account.ban"
	ActionUnbanAccount  Action = "account.unban"
	ActionCompensate    Action = "compensation.issue"
	ActionExportData    Action = "data.export"
	ActionViewAudit     Action = "audit.view"
)

// MaxGrantWindow caps every temporary elevation. A longer window is not a
// grant any more; it is a permanent role change that skipped review.
const MaxGrantWindow = 24 * time.Hour

var (
	ErrUnknownRole     = errors.New("gmrbac: unknown role")
	ErrDenied          = errors.New("gmrbac: action denied")
	ErrGrantExpired    = errors.New("gmrbac: temporary grant expired")
	ErrSelfReview      = errors.New("gmrbac: initiator cannot review own action")
	ErrReviewerDenied  = errors.New("gmrbac: reviewer lacks action permission")
	ErrSameManager     = errors.New("gmrbac: reviewer shares initiator manager")
	ErrNoReview        = errors.New("gmrbac: dual review required")
	ErrEmergencyNote   = errors.New("gmrbac: emergency approval needs reason")
	ErrBadGrant        = errors.New("gmrbac: invalid grant")
	ErrGrantTooLong    = errors.New("gmrbac: grant exceeds max window")
	ErrSameApprover    = errors.New("gmrbac: grant approver must differ")
	ErrDuplicateReview = errors.New("gmrbac: duplicate reviewer")
)

var roleActions = map[Role]map[Action]bool{
	RoleCS: {
		ActionViewProfile: true,
	},
	RoleOps: {
		ActionViewProfile:   true,
		ActionViewSensitive: true,
		ActionGrantItem:     true,
		ActionCompensate:    true,
	},
	RoleGM: {
		ActionViewProfile:   true,
		ActionViewSensitive: true,
		ActionGrantItem:     true,
		ActionDeductItem:    true,
		ActionBanAccount:    true,
		ActionUnbanAccount:  true,
		ActionCompensate:    true,
	},
	RoleAdmin: {
		ActionViewProfile:   true,
		ActionViewSensitive: true,
		ActionGrantItem:     true,
		ActionDeductItem:    true,
		ActionBanAccount:    true,
		ActionUnbanAccount:  true,
		ActionCompensate:    true,
		ActionExportData:    true,
		ActionViewAudit:     true,
	},
	RoleAuditor: {
		ActionViewProfile:   true,
		ActionViewSensitive: true,
		ActionExportData:    true,
		ActionViewAudit:     true,
	},
}

var allActions = map[Action]bool{
	ActionViewProfile:   true,
	ActionViewSensitive: true,
	ActionGrantItem:     true,
	ActionDeductItem:    true,
	ActionBanAccount:    true,
	ActionUnbanAccount:  true,
	ActionCompensate:    true,
	ActionExportData:    true,
	ActionViewAudit:     true,
}

// Grant is a time-boxed elevation. ApprovedBy and Ticket make the grant
// explainable after it expires, when the operator has already moved on.
type Grant struct {
	Action     Action
	ExpiresAt  time.Time
	ApprovedBy string
	Ticket     string
}

// Principal is one authenticated person. Roles are long-lived; Grants expire.
type Principal struct {
	ID        string
	Roles     []Role
	ManagerID string
	Grants    []Grant
	Disabled  bool
}

// Known reports whether the action is part of the policy vocabulary.
func (a Action) Known() bool { return allActions[a] }

// Known reports whether the role is part of the policy vocabulary.
func (r Role) Known() bool { _, ok := roleActions[r]; return ok }

// Authorize evaluates long-lived roles first and temporary grants second.
// An expired grant is reported distinctly so the UI can say "renew" instead
// of a misleading "denied".
func (p Principal) Authorize(action Action, now time.Time) error {
	if p.Disabled {
		return ErrDenied
	}
	if !action.Known() {
		return ErrDenied
	}
	expired := false
	for _, r := range p.Roles {
		if !r.Known() {
			return ErrUnknownRole
		}
		if roleActions[r][action] {
			return nil
		}
	}
	for _, g := range p.Grants {
		if g.Action != action {
			continue
		}
		if now.Before(g.ExpiresAt) {
			return nil
		}
		expired = true
	}
	if expired {
		return ErrGrantExpired
	}
	return ErrDenied
}

// AddGrant attaches a temporary elevation. The approver must already hold the
// same action, must be a different person, and the window is capped. A grant
// without a ticket is rejected because nobody can reconstruct why it existed.
func (p *Principal) AddGrant(g Grant, approver Principal, now time.Time) error {
	if p.Disabled || p.ID == "" || approver.Disabled || approver.ID == "" {
		return ErrBadGrant
	}
	if !g.Action.Known() || g.Ticket == "" || g.ApprovedBy == "" {
		return ErrBadGrant
	}
	if approver.ID == p.ID {
		return ErrSameApprover
	}
	window := g.ExpiresAt.Sub(now)
	if window <= 0 {
		return ErrBadGrant
	}
	if window > MaxGrantWindow {
		return ErrGrantTooLong
	}
	if err := approver.Authorize(g.Action, now); err != nil {
		return ErrReviewerDenied
	}
	p.Grants = append(p.Grants, g)
	return nil
}

// PruneGrants removes expired entries and returns how many were dropped.
// Expiry is checked at authorization time anyway; pruning only keeps the
// principal record small and the review screen honest.
func (p *Principal) PruneGrants(now time.Time) int {
	kept := p.Grants[:0]
	for _, g := range p.Grants {
		if now.Before(g.ExpiresAt) {
			kept = append(kept, g)
		}
	}
	dropped := len(p.Grants) - len(kept)
	p.Grants = kept
	return dropped
}

// file: internal/gmrbac/review.go
// tier: L1
// verify: go test ./internal/gmrbac/
package gmrbac

import (
	"sort"
	"time"
)

// dualReview lists actions whose blast radius is too large for one person.
// A temporary grant is deliberately absent: elevation itself needs an
// approver, and the granted action still follows this table.
var dualReview = map[Action]bool{
	ActionGrantItem:    true,
	ActionDeductItem:   true,
	ActionBanAccount:   true,
	ActionUnbanAccount: true,
	ActionCompensate:   true,
	ActionExportData:   true,
}

// Approval is one reviewer's decision. Emergency is not a free pass: it still
// needs a reason and it is stored on the command record.
type Approval struct {
	Reviewer  Principal
	At        time.Time
	Emergency bool
	Reason    string
}

// ReviewPolicy holds the exceptions a studio is willing to write down.
type ReviewPolicy struct {
	AllowSameManager bool
}

// RequiresDualReview reports whether the action needs a second person.
func RequiresDualReview(action Action) bool { return dualReview[action] }

// CheckReview validates the approval set for one action. It rejects self
// review, reviewers without the action, duplicate reviewers, same-manager
// pairs by default, and emergency approvals without a reason. Emergency mode
// relaxes only the same-manager rule; it never relaxes identity separation.
func CheckReview(initiator Principal, action Action, approvals []Approval, policy ReviewPolicy, now time.Time) error {
	if !RequiresDualReview(action) {
		return nil
	}
	seen := map[string]bool{}
	valid := 0
	for _, a := range approvals {
		if a.Reviewer.ID == "" || a.Reviewer.ID == initiator.ID {
			return ErrSelfReview
		}
		if seen[a.Reviewer.ID] {
			return ErrDuplicateReview
		}
		if err := a.Reviewer.Authorize(action, now); err != nil {
			return ErrReviewerDenied
		}
		sameManager := initiator.ManagerID != "" && a.Reviewer.ManagerID == initiator.ManagerID
		if sameManager && !policy.AllowSameManager && !a.Emergency {
			return ErrSameManager
		}
		if a.Emergency && a.Reason == "" {
			return ErrEmergencyNote
		}
		seen[a.Reviewer.ID] = true
		valid++
	}
	if valid == 0 {
		return ErrNoReview
	}
	return nil
}

// Actors returns every principal ID referenced by a review set, sorted, so an
// audit record does not depend on the order the UI sent approvals in.
func Actors(approvals []Approval) []string {
	ids := make([]string, 0, len(approvals))
	for _, a := range approvals {
		ids = append(ids, a.Reviewer.ID)
	}
	sort.Strings(ids)
	return ids
}