《后端架构设计·演进与治理》10.2 服务间身份：认证、授权与最小权限

// file: internal/platform/tenant/identity.go
// tier: L1
// verify: go test ./internal/platform/tenant/ -count=1
package tenant

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"strings"
	"time"
)

var (
	ErrTokenInvalid = errors.New("identity: invalid token")
	ErrTokenExpired = errors.New("identity: token expired")
	ErrAudience     = errors.New("identity: audience mismatch")
)

// Claims is the signed identity of a calling workload. Actions are the
// workload's own grant; the policy engine checks them again.
type Claims struct {
	Subject   string    `json:"sub"`
	Audience  string    `json:"aud"`
	Tenant    string    `json:"tenant"`
	Actions   []string  `json:"actions"`
	IssuedAt  time.Time `json:"iat"`
	ExpiresAt time.Time `json:"exp"`
}

func macPayload(payload, key []byte) []byte {
	mac := hmac.New(sha256.New, key)
	mac.Write(payload)
	return mac.Sum(nil)
}

// SignToken serializes claims and signs them with HMAC-SHA256. The encoding is
// payload.signature, both base64url without padding.
func SignToken(c Claims, key []byte) (string, error) {
	if len(key) == 0 {
		return "", errors.New("identity: signing key is empty")
	}
	if strings.TrimSpace(c.Subject) == "" || strings.TrimSpace(c.Audience) == "" {
		return "", errors.New("identity: subject and audience are required")
	}
	if c.ExpiresAt.IsZero() || !c.ExpiresAt.After(c.IssuedAt) {
		return "", errors.New("identity: expiry must be after issue time")
	}
	payload, err := json.Marshal(c)
	if err != nil {
		return "", err
	}
	sig := macPayload(payload, key)
	return base64.RawURLEncoding.EncodeToString(payload) + "." +
		base64.RawURLEncoding.EncodeToString(sig), nil
}

// VerifyToken checks signature, audience, issue time and expiry. skew allows
// bounded clock drift between the issuer and this process.
func VerifyToken(raw string, key []byte, audience string, now time.Time, skew time.Duration) (Claims, error) {
	parts := strings.Split(raw, ".")
	if len(parts) != 2 {
		return Claims{}, ErrTokenInvalid
	}
	payload, err := base64.RawURLEncoding.DecodeString(parts[0])
	if err != nil {
		return Claims{}, fmt.Errorf("%w: payload encoding", ErrTokenInvalid)
	}
	sig, err := base64.RawURLEncoding.DecodeString(parts[1])
	if err != nil {
		return Claims{}, fmt.Errorf("%w: signature encoding", ErrTokenInvalid)
	}
	if !hmac.Equal(macPayload(payload, key), sig) {
		return Claims{}, fmt.Errorf("%w: signature mismatch", ErrTokenInvalid)
	}
	var c Claims
	if err := json.Unmarshal(payload, &c); err != nil {
		return Claims{}, fmt.Errorf("%w: payload json", ErrTokenInvalid)
	}
	if strings.TrimSpace(c.Subject) == "" || strings.TrimSpace(c.Audience) == "" {
		return Claims{}, fmt.Errorf("%w: missing subject or audience", ErrTokenInvalid)
	}
	if audience == "" || c.Audience != audience {
		return Claims{}, fmt.Errorf("%w: want %q got %q", ErrAudience, audience, c.Audience)
	}
	if !now.Before(c.ExpiresAt.Add(skew)) {
		return Claims{}, fmt.Errorf("%w: expired at %s", ErrTokenExpired, c.ExpiresAt.Format(time.RFC3339))
	}
	if c.IssuedAt.After(now.Add(skew)) {
		return Claims{}, fmt.Errorf("%w: issued in the future", ErrTokenInvalid)
	}
	return c, nil
}

// Effect is the outcome declared by one policy rule.
type Effect string

const (
	Allow Effect = "allow"
	Deny  Effect = "deny"
)

// Rule grants or denies a service a set of actions on a resource prefix. An
// empty or "*" field matches everything.
type Rule struct {
	Service        string
	Actions        []string
	ResourcePrefix string
	Tenant         string
	Effect         Effect
}

// Policy is an ordered rule set, but deny always wins over allow.
type Policy struct {
	Rules []Rule
}

// Decision is a fully explained authorization result. Rule is -1 when no rule
// matched or the request was rejected before evaluation.
type Decision struct {
	Allowed bool
	Reason  string
	Rule    int
}

func matchValue(pattern, value string) bool {
	return pattern == "" || pattern == "*" || pattern == value
}

func matchAction(actions []string, action string) bool {
	for _, a := range actions {
		if a == "*" || a == action {
			return true
		}
	}
	return false
}

// matchResource requires a path boundary: /orders/ must not match
// /orders-secret, but /orders must match /orders/123.
func matchResource(prefix, resource string) bool {
	if prefix == "" || prefix == "*" || resource == prefix {
		return true
	}
	base := strings.TrimSuffix(prefix, "/")
	return base != "" && strings.HasPrefix(resource, base+"/")
}

// Authorize enforces two independent gates: the action must be in the signed
// identity grant, and an allow rule must match after all deny rules are
// considered. Absence of a rule is a denial, never an implicit allow.
func (p Policy) Authorize(c Claims, action, resource, tenantID string) Decision {
	if c.Subject == "" || action == "" || resource == "" || tenantID == "" {
		return Decision{Reason: "incomplete request", Rule: -1}
	}
	if c.Tenant != "*" && c.Tenant != tenantID {
		return Decision{Reason: "identity tenant does not match request tenant", Rule: -1}
	}
	if !matchAction(c.Actions, action) {
		return Decision{Reason: "action is not in the identity grant", Rule: -1}
	}
	allowed := -1
	for i, r := range p.Rules {
		if !matchValue(r.Service, c.Subject) || !matchValue(r.Tenant, tenantID) {
			continue
		}
		if !matchAction(r.Actions, action) || !matchResource(r.ResourcePrefix, resource) {
			continue
		}
		if r.Effect == Deny {
			return Decision{Reason: fmt.Sprintf("deny rule %d matched", i), Rule: i}
		}
		if r.Effect == Allow && allowed < 0 {
			allowed = i
		}
	}
	if allowed >= 0 {
		return Decision{Allowed: true, Reason: fmt.Sprintf("allow rule %d matched", allowed), Rule: allowed}
	}
	return Decision{Reason: "no allow rule matched", Rule: -1}
}

// file: internal/platform/tenant/identity_test.go
// tier: L1
// verify: go test ./internal/platform/tenant/ -count=1
package tenant

import (
	"encoding/base64"
	"errors"
	"strings"
	"testing"
	"time"
)

var fixedNow = time.Date(2026, 11, 3, 12, 0, 0, 0, time.UTC)

func testClaims() Claims {
	return Claims{
		Subject: "order-api", Audience: "inventory", Tenant: "acme",
		Actions:  []string{"reservation:read", "reservation:release"},
		IssuedAt: fixedNow.Add(-time.Minute), ExpiresAt: fixedNow.Add(time.Minute),
	}
}

func TestTokenVerify(t *testing.T) {
	key := []byte("arch-lab-key")
	raw, err := SignToken(testClaims(), key)
	if err != nil {
		t.Fatalf("SignToken: %v", err)
	}
	got, err := VerifyToken(raw, key, "inventory", fixedNow, 0)
	if err != nil {
		t.Fatalf("VerifyToken: %v", err)
	}
	if got.Subject != "order-api" || got.Tenant != "acme" || len(got.Actions) != 2 {
		t.Fatalf("claims=%+v", got)
	}
	if _, err := VerifyToken(raw, []byte("other-key"), "inventory", fixedNow, 0); !errors.Is(err, ErrTokenInvalid) {
		t.Fatalf("wrong key err=%v", err)
	}
	parts := strings.Split(raw, ".")
	payload, err := base64.RawURLEncoding.DecodeString(parts[0])
	if err != nil {
		t.Fatalf("decode: %v", err)
	}
	payload[0] ^= 0x01
	tampered := base64.RawURLEncoding.EncodeToString(payload) + "." + parts[1]
	if _, err := VerifyToken(tampered, key, "inventory", fixedNow, 0); !errors.Is(err, ErrTokenInvalid) {
		t.Fatalf("tampered err=%v", err)
	}
	if _, err := VerifyToken(raw, key, "payment", fixedNow, 0); !errors.Is(err, ErrAudience) {
		t.Fatalf("audience err=%v", err)
	}
	if _, err := VerifyToken(raw, key, "inventory", fixedNow.Add(2*time.Minute), 0); !errors.Is(err, ErrTokenExpired) {
		t.Fatalf("expired err=%v", err)
	}
	future := testClaims()
	future.IssuedAt = fixedNow.Add(10 * time.Minute)
	future.ExpiresAt = fixedNow.Add(20 * time.Minute)
	rawFuture, _ := SignToken(future, key)
	if _, err := VerifyToken(rawFuture, key, "inventory", fixedNow, 0); !errors.Is(err, ErrTokenInvalid) {
		t.Fatalf("future err=%v", err)
	}
}

func TestAuthorize(t *testing.T) {
	policy := Policy{Rules: []Rule{
		{Service: "order-api", Actions: []string{"reservation:read"}, ResourcePrefix: "/reservations/", Tenant: "acme", Effect: Allow},
		{Service: "order-api", Actions: []string{"reservation:read"}, ResourcePrefix: "/reservations/secret", Tenant: "acme", Effect: Deny},
		{Service: "*", Actions: []string{"*"}, ResourcePrefix: "/platform/", Tenant: "*", Effect: Allow},
	}}
	c := testClaims()
	if d := policy.Authorize(c, "reservation:read", "/reservations/order-1", "acme"); !d.Allowed {
		t.Fatalf("allow case rejected: %+v", d)
	}
	if d := policy.Authorize(c, "reservation:read", "/reservations/secret/1", "acme"); d.Allowed || d.Rule != 1 {
		t.Fatalf("deny did not win: %+v", d)
	}
	if d := policy.Authorize(c, "reservation:read", "/reservations-secret/1", "acme"); d.Allowed {
		t.Fatalf("prefix boundary leaked: %+v", d)
	}
	if d := policy.Authorize(c, "reservation:read", "/reservations/order-1", "globex"); d.Allowed {
		t.Fatalf("tenant mismatch allowed: %+v", d)
	}
	if d := policy.Authorize(c, "reservation:write", "/reservations/order-1", "acme"); d.Allowed {
		t.Fatalf("grant escape allowed: %+v", d)
	}
	platform := Claims{Subject: "platform-ops", Audience: "platform", Tenant: "*",
		Actions: []string{"*"}, IssuedAt: fixedNow.Add(-time.Minute), ExpiresAt: fixedNow.Add(time.Minute)}
	if d := policy.Authorize(platform, "tenant:inspect", "/platform/tenants/acme", "acme"); !d.Allowed {
		t.Fatalf("platform case rejected: %+v", d)
	}
	unknown := Policy{}
	if d := unknown.Authorize(c, "reservation:read", "/reservations/order-1", "acme"); d.Allowed {
		t.Fatalf("default deny failed: %+v", d)
	}
}

$ go version
go version go1.26.0 darwin/arm64
$ go test ./internal/platform/tenant/ -count=1 -v -run 'TestToken|TestAuthorize'
=== RUN   TestTokenVerify
--- PASS: TestTokenVerify (0.00s)
=== RUN   TestAuthorize
--- PASS: TestAuthorize (0.00s)
PASS
ok  	archlab/internal/platform/tenant	0.249s