Sparkdo.VerificationCode.Abstractions 3.0.0-preview.1

This is a prerelease version of Sparkdo.VerificationCode.Abstractions.

dotnet add package Sparkdo.VerificationCode.Abstractions --version 3.0.0-preview.1

NuGet\Install-Package Sparkdo.VerificationCode.Abstractions -Version 3.0.0-preview.1

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Sparkdo.VerificationCode.Abstractions" Version="3.0.0-preview.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Sparkdo.VerificationCode.Abstractions" Version="3.0.0-preview.1" />
                    

                            Directory.Packages.props

<PackageReference Include="Sparkdo.VerificationCode.Abstractions" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Sparkdo.VerificationCode.Abstractions --version 3.0.0-preview.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Sparkdo.VerificationCode.Abstractions, 3.0.0-preview.1"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Sparkdo.VerificationCode.Abstractions@3.0.0-preview.1

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Sparkdo.VerificationCode.Abstractions&version=3.0.0-preview.1&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=Sparkdo.VerificationCode.Abstractions&version=3.0.0-preview.1&prerelease
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Sparkdo.VerificationCode.Abstractions

验证码产品域的稳定公共契约：创建并一次性校验验证码。零依赖（仅 net11.0 BCL），AOT 与裁剪安全。

能做什么

定义验证码的创建（IVerificationCodeManager.CreateAsync）与一次性校验（VerifyAsync）契约。
声明全局配置（VerificationCodeOptions）与单次配置（VerificationCodeCreateOptions）。
声明生成器（IVerificationCodeGenerator）与 hasher（IVerificationCodeHasher）的可替换契约。
稳定错误码（VerificationCodeErrorCodes）与领域异常（VerificationCodeException）。

不能做什么（红线）

不生成图片验证码、滑块、人机校验；不负责短信/邮件发送——这些是交付通道 adapter 的事。
不持久化明文：明文只在 VerificationCodeInfo.Code 出现一次，交给发送方后即不可恢复。
不定义存储与锁的实现：存储复用 Sparkdo.Caching，串行化复用 Sparkdo.DistributedLocking。
不做用户侧限流策略（如按 IP/账号风控）——本域只做同 key 发送间隔限频。

核心类型速览

类型	责任
`IVerificationCodeManager`	创建并一次性校验验证码；实现负责限频、过期、失败上限、hash 存储
`IVerificationCodeGenerator`	用密码学安全随机源按字符集生成长度为 N 的明文
`IVerificationCodeHasher`	不可逆 hash 与固定时间校验；payload 自带版本与参数便于平滑升级
`VerificationCodeOptions`	字符集/长度/有效期/忽略大小写/pepper/迭代次数/发送间隔/最大失败次数/锁超时
`VerificationCodeCreateOptions`	单次覆盖：key/字符集/长度/有效期/发送间隔（均不得突破全局上限）
`VerificationCodeInfo`	key + 明文 + 到期时间；明文只交给发送 adapter
`VerificationCodeException` + `VerificationCodeErrorCodes`	稳定错误码：`GetTooFrequently`、`LockTimeout`、`InvalidOptions`
`VerificationCodeCapability`	公开 API：能力稳定标识（`Id = "Sparkdo.VerificationCode"`），供能力发现/接线断言使用

全局配置项

属性	默认	约束
`Alphabet`	`"0123456789"`	非空白；不得含空白或重复字符（重复会静默降低熵）
`Length`	`6`	> 0 且 ≤ `MaxLength`
`MaxLength`（常量）	`64`	长度全局硬上限；配置校验与生成上下文构造期都拒绝超界值
`Duration`	5 分钟	> 0；单次有效期不得超过它
`VerifyIgnoreCase`	`true`	hash 与校验按同一设置执行（随 cache payload 固化）
`HashSecret`	`null`	可选 pepper；来自 secrets provider，禁止入库/源码
`HashIterations`	`600000`	(0, 10000000]；仅作用于新 hash，校验按 payload 内的值执行
`SendInterval`	1 分钟	> 0 或 `null`（禁用）；单次间隔不得超过它
`MaxFailedAttempts`	`5`	> 0；失败达到该值后验证码即删除
`DistributedLockTimeout`	5 秒	≥ 0；`TimeSpan.Zero` 表示只尝试一次

字符集与长度校验

VerificationCodeGenerationContext 在构造期校验字符集：空白与重复字符直接抛 ArgumentException。重复字符会让部分字符获得更高出现概率，静默稀释熵——本域选择 fail-closed 而不是容忍。默认实现使用拒绝采样保证字符集中每个字符等概率出现。

长度同样在构造期校验：零/负数或超过 VerificationCodeOptions.MaxLength（64）抛 ArgumentOutOfRangeException。生成路径按请求长度分配结果字符串，这道闸保证宿主把用户可控值透传给 Length 时无法触发任意大分配。

语义要点

一次性：校验成功即消费；并发校验由实现串行化（同 key 分布式锁），不会双花。
失败上限：失败计数达到 MaxFailedAttempts 后验证码删除，正确明文也随之作废。
限频：发送间隔内同 key 重复创建抛 GetTooFrequently；间隔过期后可再次创建。
过期双保险：逻辑过期（payload 内 ExpireAt）由 manager 读取时校验；物理 TTL 只承担存储清理。
大小写：VerifyIgnoreCase 在创建时写入 cache payload，校验沿用创建时的设置。
错误码稳定：格式 Sparkdo.VerificationCode:xxxxx，只增不改，供上游翻译/告警。

接线

引用 Sparkdo.VerificationCode 后一行完成：

services.AddSparkdoVerificationCode();

默认实现均以 TryAdd 语义注册，按接口替换即可自定义生成、hash 或管理策略。

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- No dependencies.
net11.0
- No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Sparkdo.VerificationCode.Abstractions:

Package	Downloads
Sparkdo.VerificationCode Sparkdo 验证码核心实现：CSPRNG 生成器、零分配校验路径的 PBKDF2 hash、cache/lock-backed manager、发送间隔限频、cache TTL 投影与 AddSparkdoVerificationCode 一行接线。	1.5K

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
3.0.0-preview.1	65	10/30/2026
2.0.0-preview.2	105	7/20/2026
2.0.0-preview.1	83	7/18/2026