pwd

type HistoryCheck ¶

type HistoryCheck struct {
	// Count 回溯条数（必须 ≥ 1）。
	Count int
	// Fetch 历史取数面（必须非 nil）。
	Fetch HistorySource
	// Match 哈希比对器（必须非 nil）。
	Match Matcher
}

HistoryCheck 历史防复用检查（#121）：候选密码不得与最近 Count 条历史密码 重复。

fail-closed 契约（#121 的核心取舍）：Fetch/Match 出错 ≠ 放行——历史查询 失败时绝不能降级成「没查到历史 ⇒ 新密码可用」，错误原样上抛（归 500）， 让调用方决定重试还是失败。命中任一历史 ⇒ *Violation（Kind=KindHistory， 400）。

零值不设防，Count 必须显式 ≥ 1 且 Fetch/Match 非 nil（Check 期 fail-fast 报配置错，归 500——配置 bug 不归 400，#115 同口径）。

func (h HistoryCheck) Check(ctx context.Context, userID, candidate string) error

type HistorySource ¶

type HistorySource func(ctx context.Context, userID string, count int) ([]string, error)

HistorySource 历史密码取数面：返回该用户最近 count 条历史密码的**存储形态** （典型 bcrypt hash，顺序不限，逐条比对）。存储形态而非明文——历史表落的 本来就是哈希。

type Kind ¶

type Kind string

Kind 标注密码策略违规的类别（供调用方按类别定制响应文案/指标）。

const (
	// KindLength 长度违规（不足/超长）。
	KindLength Kind = "length"
	// KindComplexity 复杂度违规（缺字符类别）。
	KindComplexity Kind = "complexity"
	// KindWeak 弱口令违规（常见弱口令/结构性弱模式）。
	KindWeak Kind = "weak"
	// KindHistory 历史复用违规（与最近历史密码重复）。
	KindHistory Kind = "history"
)

type Matcher ¶

type Matcher func(stored, candidate string) (bool, error)

Matcher 历史比对器：候选明文与存储形态比对（典型 bcrypt.CompareHashAndPassword 包装：`func(stored, candidate string) (bool, error) { return nil == bcrypt.CompareHashAndPassword([]byte(stored), []byte(candidate)) }`）。

库层不绑哈希算法（纯 Go 零依赖是本包边界）：比对语义由调用方注入，错误 形态（哈希格式坏等）经 error 上抛，HistoryCheck 按 fail-closed 处理。

type Policy ¶

type Policy struct {
	// MinLength 最小长度（rune 口径，必须 ≥ 1）。
	MinLength int
	// MaxLength 最大长度（rune 口径；0 = 不限）。防超长输入的存储/哈希层 DoS。
	MaxLength int
	// RequireUpper 要求含大写字母。
	RequireUpper bool
	// RequireLower 要求含小写字母。
	RequireLower bool
	// RequireDigit 要求含数字。
	RequireDigit bool
	// RequireSpecial 要求含特殊字符（非字母非数字，含空格）。
	RequireSpecial bool
}

Policy 是密码策略（#121）：长度/复杂度/常见弱口令拒绝面，Check 全量判据。

判定顺序固定（长度 → 复杂度 → 弱口令），一次返回首个违规——密码设置场景 给用户一条可执行的整改指引即可，聚合多条反而淹没重点（与 validator 的 字段聚合场景不同域）。

零值不设防，构造时 MinLength 必须显式 ≥ 1（Check 期 fail-fast 报配置错）： 「无最小长度的密码策略」是最危险的缺省（配置零值透传即全员短密码）， 与 WithTTL(0) panic（jwt #65）同一纪律——此处以 error 表达（Check 有 error 出口，策略配置 bug 归 500）。

func (p Policy) Check(password string) error

type Violation ¶

type Violation struct {
	// Kind 违规类别。
	Kind Kind
	// Message 用户可读文案（msgFormat/默认文案产物）。
	Message string
}

Violation 是密码策略违规错误：Message 为用户可读文案（可直接进响应）， Unwrap 为 pkg/errors BizError 400（middleware.Fail 自动映射 HTTP 400， 与 validator.ValidationError 同款分型纪律）。

func AsViolation(err error) (*Violation, bool)

func (e *Violation) Error() string

func (e *Violation) Unwrap() error