feat: 补齐模块接口契约与管理 API 文档

internal/auth/stub.go

@@ -0,0 +1,105 @@
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"strings"
+	"sync"
+	"time"
+)
+
+// StubHashPool 是测试用假哈希池：明文加前缀，不做 argon2。
+type StubHashPool struct {
+	mu    sync.Mutex
+	queue int
+}
+
+func NewStubHashPool() *StubHashPool { return &StubHashPool{} }
+
+func (p *StubHashPool) Hash(_ context.Context, _ PasswordKind, password string) (string, error) {
+	return "stub$" + password, nil
+}
+
+func (p *StubHashPool) Verify(_ context.Context, _ PasswordKind, password, phc string) (bool, error) {
+	return phc == "stub$"+password, nil
+}
+
+func (p *StubHashPool) QueueLen() int {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.queue
+}
+
+// StubSessionTokens 假会话令牌。
+type StubSessionTokens struct{}
+
+func NewStubSessionTokens() *StubSessionTokens { return &StubSessionTokens{} }
+
+func (s *StubSessionTokens) Issue(_ context.Context) (string, []byte, error) {
+	tok := "nst_stub_session_token_000000000000"
+	sum := sha256.Sum256([]byte(tok))
+	return tok, sum[:], nil
+}
+
+func (s *StubSessionTokens) HashToken(token string) []byte {
+	sum := sha256.Sum256([]byte(token))
+	return sum[:]
+}
+
+func (s *StubSessionTokens) LooksLikeSessionToken(credential string) bool {
+	return strings.HasPrefix(credential, "nst_")
+}
+
+// StubAPITokens 假 API 令牌。
+type StubAPITokens struct{}
+
+func NewStubAPITokens() *StubAPITokens { return &StubAPITokens{} }
+
+func (s *StubAPITokens) Issue(_ context.Context) (string, []byte, error) {
+	tok := "nxm_stub_api_token_0000000000000000"
+	sum := sha256.Sum256([]byte(tok))
+	return tok, sum[:], nil
+}
+
+func (s *StubAPITokens) HashToken(token string) []byte {
+	sum := sha256.Sum256([]byte(token))
+	return sum[:]
+}
+
+func (s *StubAPITokens) LooksLikeAPIToken(credential string) bool {
+	return strings.HasPrefix(credential, "nxm_")
+}
+
+// StubLoginLocks 假锁定：永不锁定，记录调用便于测试。
+type StubLoginLocks struct {
+	mu      sync.Mutex
+	Fails   []LockKey
+	Cleared []string
+}
+
+func NewStubLoginLocks() *StubLoginLocks { return &StubLoginLocks{} }
+
+func (l *StubLoginLocks) Check(LockKey) (bool, time.Duration) { return false, 0 }
+
+func (l *StubLoginLocks) Fail(key LockKey) (bool, time.Duration) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.Fails = append(l.Fails, key)
+	return false, 0
+}
+
+func (l *StubLoginLocks) ClearEndpoint(endpointID string) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.Cleared = append(l.Cleared, endpointID)
+}
+
+func (l *StubLoginLocks) Clear(LockKey) {}
+
+// 编译期检查：假实现满足接口。
+var (
+	_ HashPool      = (*StubHashPool)(nil)
+	_ SessionTokens = (*StubSessionTokens)(nil)
+	_ APITokens     = (*StubAPITokens)(nil)
+	_ LoginLocks    = (*StubLoginLocks)(nil)
+)