// Package auth 定义密码哈希池、会话令牌、API 令牌与登录锁定计数的接口。
// 本包在 T0.4 只提供契约与测试假实现；真正的 argon2 池与令牌逻辑由平台 P 实现。
package auth

import (
	"context"
	"errors"
	"time"
)

// ErrNotImplemented 表示假实现尚未提供业务能力。
var ErrNotImplemented = errors.New("auth: not implemented")

// PasswordKind 区分哈希用途（便于日志与限流，不影响算法）。
type PasswordKind string

const (
	PasswordLogin PasswordKind = "login"
	PasswordTalk  PasswordKind = "talk"
	PasswordAdmin PasswordKind = "admin"
)

// HashPool 是 argon2id 并发池（DEVELOPMENT 第 12 节）。
type HashPool interface {
	// Hash 计算 PHC 格式哈希。
	Hash(ctx context.Context, kind PasswordKind, password string) (phc string, err error)
	// Verify 常量时间比较；ok 为 false 时 err 仍可为 nil（密码不匹配）。
	Verify(ctx context.Context, kind PasswordKind, password, phc string) (ok bool, err error)
	// QueueLen 返回等待哈希的任务数（指标用）。
	QueueLen() int
}

// SessionTokens 管理端会话令牌（nst_ 前缀，库中存 SHA-256）。
type SessionTokens interface {
	// Issue 生成新令牌明文，返回明文与 SHA-256 十六进制（或原始哈希字节由实现约定）。
	Issue(ctx context.Context) (token string, hash []byte, err error)
	// HashToken 对已有令牌做 SHA-256（校验用，不走 argon2）。
	HashToken(token string) []byte
	// LooksLikeSessionToken 判断密码字段是否以 nst_ 开头。
	LooksLikeSessionToken(credential string) bool
}

// APITokenInfo 是列表项（不含令牌明文）。
type APITokenInfo struct {
	ID         int64
	Name       string
	Enabled    bool
	CreatedAt  time.Time
	LastUsedAt *time.Time
}

// APITokens 管理后台 API 令牌（nxm_ 前缀）。
type APITokens interface {
	Issue(ctx context.Context) (token string, hash []byte, err error)
	HashToken(token string) []byte
	LooksLikeAPIToken(credential string) bool
}

// LockKind 区分锁定计数器类型。
type LockKind string

const (
	// LockLoginEndpointIP：编号 + IP，5 分钟内 10 次错 → 锁该组合 5 分钟。
	LockLoginEndpointIP LockKind = "login_endpoint_ip"
	// LockLoginEndpoint：编号总数，1 小时内 50 次错 → 暂停该编号密码登录 1 小时。
	LockLoginEndpoint LockKind = "login_endpoint"
	// LockTalkPair：发送方 + 对方对话密码。
	LockTalkPair LockKind = "talk_pair"
	// LockTalkTarget：对方对话密码总数。
	LockTalkTarget LockKind = "talk_target"
	// LockAdminIP：管理员登录 / 错误 API 令牌。
	LockAdminIP LockKind = "admin_ip"
	// LockRegisterIP：注册安全码错误。
	LockRegisterIP LockKind = "register_ip"
)

// LockKey 是一次锁定查询/计数的键。
type LockKey struct {
	Kind       LockKind
	EndpointID string // 端编号；管理员/注册场景可空
	PeerID     string // 对话密码对方；可空
	IP         string // 来源 IP；按编号总数等场景可空
}

// LoginLocks 是内存锁定计数器（重启清零）。
type LoginLocks interface {
	// Check 若当前已锁定返回 locked=true 与剩余时间。
	Check(key LockKey) (locked bool, retryAfter time.Duration)
	// Fail 记录一次失败；若因此触发锁定，返回 locked=true。
	Fail(key LockKey) (locked bool, retryAfter time.Duration)
	// ClearEndpoint 清除某端编号相关的登录锁定（两种都清），对应管理 unlock。
	ClearEndpoint(endpointID string)
	// Clear 清除精确键。
	Clear(key LockKey)
}