《后端架构设计·演进与治理》10.3 密钥、审计与合规边界

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

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

var (
	ErrKeyUnknown  = errors.New("audit: unknown key version")
	ErrKeyRetired  = errors.New("audit: key version retired")
	ErrChainBroken = errors.New("audit: hash chain broken")
)

// KeyState is the lifecycle state of one encryption key version.
type KeyState string

const (
	KeyActive   KeyState = "active"
	KeyRetiring KeyState = "retiring"
	KeyRetired  KeyState = "retired"
)

// KeyVersion is one key in a rotation ring. RetireAt is meaningful only while
// the version is retiring.
type KeyVersion struct {
	ID        string
	CreatedAt time.Time
	RetireAt  time.Time
	State     KeyState
}

// Keyring holds every version still usable for decryption.
type Keyring struct {
	versions []KeyVersion
}

// NewKeyring creates a ring with one active version.
func NewKeyring(firstID string, now time.Time) (*Keyring, error) {
	if strings.TrimSpace(firstID) == "" || now.IsZero() {
		return nil, errors.New("audit: first key id and creation time are required")
	}
	return &Keyring{versions: []KeyVersion{{
		ID: firstID, CreatedAt: now, State: KeyActive,
	}}}, nil
}

// Rotate creates a new active version and moves the old one to retiring. The
// overlap window is the only period in which both versions may decrypt.
func (k *Keyring) Rotate(id string, now time.Time, overlap time.Duration) (KeyVersion, error) {
	if strings.TrimSpace(id) == "" {
		return KeyVersion{}, errors.New("audit: new key id is empty")
	}
	if overlap <= 0 {
		return KeyVersion{}, errors.New("audit: overlap must be positive")
	}
	active := -1
	for i, v := range k.versions {
		if v.ID == id {
			return KeyVersion{}, fmt.Errorf("audit: duplicate key %q", id)
		}
		if v.State == KeyActive {
			active = i
		}
	}
	if active < 0 {
		return KeyVersion{}, errors.New("audit: no active key to rotate")
	}
	if !now.After(k.versions[active].CreatedAt) {
		return KeyVersion{}, errors.New("audit: rotation must advance time")
	}
	k.versions[active].State = KeyRetiring
	k.versions[active].RetireAt = now.Add(overlap)
	v := KeyVersion{ID: id, CreatedAt: now, State: KeyActive}
	k.versions = append(k.versions, v)
	return v, nil
}

// Resolve returns a version that may still decrypt data at now. A retiring key
// is refused once the overlap window has closed.
func (k *Keyring) Resolve(id string, now time.Time) (KeyVersion, error) {
	for _, v := range k.versions {
		if v.ID != id {
			continue
		}
		switch v.State {
		case KeyActive:
			return v, nil
		case KeyRetiring:
			if now.Before(v.RetireAt) {
				return v, nil
			}
			return v, fmt.Errorf("%w: %s closed at %s", ErrKeyRetired, id, v.RetireAt.Format(time.RFC3339))
		default:
			return v, fmt.Errorf("%w: %s", ErrKeyRetired, id)
		}
	}
	return KeyVersion{}, fmt.Errorf("%w: %s", ErrKeyUnknown, id)
}

// Active returns the single active version at now.
func (k *Keyring) Active(now time.Time) (KeyVersion, error) {
	for _, v := range k.versions {
		if v.State == KeyActive {
			if now.Before(v.CreatedAt) {
				return KeyVersion{}, errors.New("audit: active key is not valid yet")
			}
			return v, nil
		}
	}
	return KeyVersion{}, errors.New("audit: no active key")
}

// AuditEntry is one append-only audit record. PrevHash links it to the record
// before it; Hash covers every identity and payload field.
type AuditEntry struct {
	Seq      uint64
	At       time.Time
	Actor    string
	Action   string
	Tenant   string
	Resource string
	PrevHash string
	Hash     string
}

func entryHash(e AuditEntry) string {
	h := sha256.New()
	fmt.Fprintf(h, "%d\x00%s\x00%s\x00%s\x00%s\x00%s\x00%s",
		e.Seq, e.At.UTC().Format(time.RFC3339Nano),
		e.Actor, e.Action, e.Tenant, e.Resource, e.PrevHash)
	return hex.EncodeToString(h.Sum(nil))
}

// AuditLog assigns sequence numbers and hashes on append.
type AuditLog struct {
	entries []AuditEntry
}

// NewAuditLog returns an empty log.
func NewAuditLog() *AuditLog { return &AuditLog{} }

// Append fills Seq, PrevHash and Hash. Callers cannot choose the sequence, so
// reordering requires breaking the chain.
func (l *AuditLog) Append(e AuditEntry) (AuditEntry, error) {
	if e.At.IsZero() || strings.TrimSpace(e.Actor) == "" ||
		strings.TrimSpace(e.Action) == "" || strings.TrimSpace(e.Tenant) == "" ||
		strings.TrimSpace(e.Resource) == "" {
		return AuditEntry{}, errors.New("audit: entry has an empty required field")
	}
	e.Seq = uint64(len(l.entries) + 1)
	e.PrevHash = ""
	if n := len(l.entries); n > 0 {
		e.PrevHash = l.entries[n-1].Hash
	}
	e.Hash = entryHash(e)
	l.entries = append(l.entries, e)
	return e, nil
}

// VerifyChain detects edited fields, reordered entries and deleted middle
// entries. Truncating the tail is invisible without an external anchor.
func VerifyChain(entries []AuditEntry) error {
	prev := ""
	for i, e := range entries {
		if e.Seq != uint64(i+1) {
			return fmt.Errorf("%w: position %d has seq %d", ErrChainBroken, i, e.Seq)
		}
		if e.PrevHash != prev {
			return fmt.Errorf("%w: seq %d has wrong prev hash", ErrChainBroken, e.Seq)
		}
		if entryHash(e) != e.Hash {
			return fmt.Errorf("%w: seq %d content changed", ErrChainBroken, e.Seq)
		}
		prev = e.Hash
	}
	return nil
}

// Entries returns a copy so callers cannot mutate the log through the slice.
func (l *AuditLog) Entries() []AuditEntry {
	return append([]AuditEntry(nil), l.entries...)
}

// ExportTenant returns only one tenant's records. The filtered slice is for
// disclosure, not for chain verification; verify the full log first.
func (l *AuditLog) ExportTenant(tenantID string) []AuditEntry {
	out := make([]AuditEntry, 0)
	for _, e := range l.entries {
		if e.Tenant == tenantID {
			out = append(out, e)
		}
	}
	return out
}

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

import (
	"errors"
	"testing"
	"time"
)

func TestKeyringRotation(t *testing.T) {
	t0 := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
	ring, err := NewKeyring("k1", t0)
	if err != nil {
		t.Fatalf("NewKeyring: %v", err)
	}
	if _, err := ring.Rotate("k2", t0, 7*24*time.Hour); err == nil {
		t.Fatal("rotation without advancing time should fail")
	}
	if _, err := ring.Rotate("k2", t0.Add(24*time.Hour), 7*24*time.Hour); err != nil {
		t.Fatalf("Rotate: %v", err)
	}
	if _, err := ring.Rotate("k2", t0.Add(48*time.Hour), time.Hour); err == nil {
		t.Fatal("duplicate key should fail")
	}
	if _, err := ring.Resolve("k1", t0.Add(7*24*time.Hour)); err != nil {
		t.Fatalf("overlap decrypt: %v", err)
	}
	if _, err := ring.Resolve("k1", t0.Add(8*24*time.Hour)); !errors.Is(err, ErrKeyRetired) {
		t.Fatalf("closed overlap err=%v", err)
	}
	active, err := ring.Active(t0.Add(8 * 24 * time.Hour))
	if err != nil || active.ID != "k2" {
		t.Fatalf("active=%+v err=%v", active, err)
	}
	if _, err := ring.Resolve("k9", t0); !errors.Is(err, ErrKeyUnknown) {
		t.Fatalf("unknown err=%v", err)
	}
}

func TestAuditChain(t *testing.T) {
	log := NewAuditLog()
	base := time.Date(2026, 11, 3, 10, 0, 0, 0, time.UTC)
	inputs := []AuditEntry{
		{At: base, Actor: "order-api", Action: "order.create", Tenant: "acme", Resource: "order-1"},
		{At: base.Add(time.Second), Actor: "payment-api", Action: "payment.capture", Tenant: "acme", Resource: "order-1"},
		{At: base.Add(2 * time.Second), Actor: "order-api", Action: "order.create", Tenant: "globex", Resource: "order-2"},
	}
	for _, in := range inputs {
		if _, err := log.Append(in); err != nil {
			t.Fatalf("Append: %v", err)
		}
	}
	entries := log.Entries()
	if len(entries) != 3 || entries[2].Seq != 3 || entries[1].PrevHash != entries[0].Hash {
		t.Fatalf("entries=%+v", entries)
	}
	if err := VerifyChain(entries); err != nil {
		t.Fatalf("VerifyChain: %v", err)
	}
	if got := log.ExportTenant("acme"); len(got) != 2 {
		t.Fatalf("acme export=%d", len(got))
	}
	tampered := append([]AuditEntry(nil), entries...)
	tampered[1].Actor = "attacker"
	if err := VerifyChain(tampered); !errors.Is(err, ErrChainBroken) {
		t.Fatalf("tamper err=%v", err)
	}
	gap := []AuditEntry{entries[0], entries[2]}
	if err := VerifyChain(gap); !errors.Is(err, ErrChainBroken) {
		t.Fatalf("gap err=%v", err)
	}
	if err := VerifyChain(entries[:2]); err != nil {
		t.Fatalf("tail truncation is not detectable: %v", err)
	}
	if _, err := log.Append(AuditEntry{At: base}); err == nil {
		t.Fatal("expected missing field error")
	}
	t.Logf("entries=%d acme_export=%d", len(entries), len(log.ExportTenant("acme")))
}

$ go version
go version go1.26.0 darwin/arm64
$ go test ./internal/platform/tenant/ -count=1 -v -run 'TestKeyring|TestAudit'
=== RUN   TestKeyringRotation
--- PASS: TestKeyringRotation (0.00s)
=== RUN   TestAuditChain
    audit_test.go:80: entries=3 acme_export=2
--- PASS: TestAuditChain (0.00s)
PASS
ok  	archlab/internal/platform/tenant	0.252s