Table of Contents

KernLab.Claim 引擎包使用指南

1. 定位

KernLab.Claim 是认证引擎包:JOSE/JWT 签发与验证(ES256 零第三方)、签名密钥环(双 key 宽限)、 PKCE、PBKDF2、TOTP、KEK、TokenService 授权流、IClaimStore 存储抽象——面向嵌入式/自建形态的 引擎级复用。部署统一认证中心请用宿主 kernlab-claim;消费方取 token/验签请用 KernLab.Claim.Client SDK。

2. 快速上手

using KernLab.Claim.Hosting;
using KernLab.Claim.Security;
using KernLab.Claim.Services;
using KernLab.Claim.Store.Tier;

var options = new ClaimOptions { DataDir = null };            // null = memory 介质(介质是配置)
var store = await TierClaimStore.CreateAsync(options.TierFsSpec);
var keys = SigningKeyRing.Load(options.DataDir, store.CreateKeyStore());
var tokens = new TokenService(store, keys, options);

var issued = await tokens.ClientCredentialsAsync(client, scope: "kernlab.cohort.config.read");

异步优先(禁 GetAwaiter().GetResult());示例与当前源码同构。

3. 概念与术语

术语 含义
签名密钥环 ES256 密钥集(持久化于根域 keys/signing 目录域);kid 锚点 + 双 key 宽限(轮换期新旧并行验签)
LogicalAddress KV 引擎全局单调地址——即身份/版本/游标/fencing(CAS 令牌)
会话原子批 多 key 全或无提交(BeginAtomicBatch/CommitBatchAsync)
KEK 私钥静态加密主钥(AES-GCM,env CLAIM_KEK 注入;v1kek: 前缀识别明文/密文共存)
恢复码 TOTP 不可用的一次性替代因子(SHA-256 Hex 库存、消费即删)

4. 怎么选

需求 用什么
部署完整认证中心 宿主 kernlab-claim(见其使用指南)
消费方取 token / 验签 KernLab.Claim.Client SDK(分层纪律——不背引擎)
自建存储适配 IClaimStore 实现(多实现挂同一契约测试:memory/Tier 缺省在树,Synod 待 KernLab.Synod.Client alpha.3 回归)
嵌入式引擎复用 本包

5. 怎么用

5.1 TokenService(五流)

var issued = await tokens.ClientCredentialsAsync(client, scope: "...");
var issued = await tokens.AuthorizationCodeAsync(client, code, redirectUri, codeVerifier);   // 签发 id_token+refresh
var issued = await tokens.RefreshAsync(client, refreshToken);                                 // 轮换(旧值即弃)
var issued = await tokens.TokenExchangeAsync(client, subjectToken, audience, scope);          // 代唤(act 串联)
var issued = await tokens.DeviceAuthorizeAsync(client, scope);                                // 设备流发起(WP9)
var issued = await tokens.DeviceTokenAsync(client, deviceCode, now);                          // 设备轮询(pending/slow_down/deny/granted 单次取走)

轮换语义:旧 refresh 一经换新即标记,二次使用视为泄露——撤销该客户端该用户全部 refresh(RFC 6749 §10.5)。

5.2 JwtValidator(验证面)

alg 白名单(ES256;none 恒禁)→ 签名 → 时间窗(时钟偏移容忍)→ iss/aud——消费方线上验签请用 Client SDK(同语义独立实现 + JWKS 自动刷新);本包验证器用于签发侧自检与测试。

5.3 SigningKeyRing(密钥环)

keys.Rotate(graceCount);            // 新 kid 接任,旧 kid 入宽限(宽限数 = options.KeyGraceCount)

集群形态下 kid 未命中自动 ReloadFromStore 重验一次(他副本轮换可见——与消费方 JWKS 刷新同构)。

5.4 安全原语

PasswordHasher.Hash/Verify(PBKDF2,随哈希存迭代参数)、PasswordPolicy.Validate(长度/复杂度)、 Totp.Compute/Verify(RFC 6238)、KekProtector(私钥加密;env CLAIM_KEK)、 DpopProofValidator.ValidateAsync(WP11——RFC 9449 proof 矩阵 + cnf.jkt 解析:宿主与资源方共用, htu 规范化 / jwk 含私钥即拒 / jti NX 单次 / ath 绑定)。

5.5 存储抽象

IClaimStore 十域(clients/users/users-by-email/账户令牌/codes/refresh/login-fail/sessions/jti + settings)+ ISigningKeyStore + IAuditLog(TierTimeSeries)+ IStoreMigration(export/import 快照)。 存储实现唯一性——上层零手搓 store(介质是配置:ClaimOptions.FsKind → TierFsSpec;新介质 = 新 TierKv 介质 spec,不是新适配器)。WP7 增量三件:邮箱唯一索引 TrySaveUserWithEmailIndexAsync (值版 CAS NX 恰一注册,改绑即迁槽)与账户一次性令牌 Save/ConsumeAccountTokenAsync (email-verify 24h / pw-reset 30min,授权码同款 CAS 单次消费)。

5.6 限流器(WP10)

RateLimiter.HitAsync(dim, identity, now) = 固定窗计数(TierKv 限流域 CAS 递增, 争用 3 次降级放行——限流器故障不得化为全拒);维度阈值住 RateLimitSettings(0 = 关闭)。

5.7 账户自助与标准 claims(WP7/WP8)

AccountService(注册/验证/找回域逻辑——令牌落库只存 SHA-256、防枚举形态在宿主层呈文)+ UsernamePolicy(3–64 字符,键段安全)+ IEmailSender 端口(宿主缺省 = 自研最小 SMTP 客户端, 测试 = 进程内接箱桩)。StandardClaims.Project(tokenClaims, user) = userinfo 单点投影 (token scp × 用户档:profile → name/preferred_username;email → email/email_verified; 只发有值字段,id_token 维持最小集)。

5.8 WebAuthn 验证器与联邦服务(WP12/WP13)

  • passkey(WP12):Security.WebAuthn 命名空间——CborDecoder(RFC 8949 子集:定长形态, 不定长/浮点/非法 UTF-8 恒拒;游标式入口服务嵌入段)、CoseKey(EC2/P-256 ES256 + RSA RS256, kty/alg/crv 越白名单 fail-fast)、AuthenticatorData(rpIdHash/flags/signCount/凭证段解析)、 WebAuthnVerifier(clientDataJSON 矩阵 + attestation none/packed 自证 + assertion 验签, challenge 恒时比对)、WebAuthnService(挑战编排 + signCount CAS 克隆检测)。
  • 联邦(WP13):UpstreamJwks(上游 JWKS 拉取缓存 + kid 未命中刷新重验一次——不动 Client 包 JwksFetcher 包边界)+ UpstreamIdToken.ValidateAsync(alg 白名单按上游配置——独立于本域 ES256 红线;iss/aud/exp/nonce 回填矩阵)+ FederationService(state+nonce+PKCE 三防、 code 换 ID token、ident 绑定解析、MFA 待定态、idp-link/unlink 编排)。

5.9 可观测原语(WP14)

Diagnostics.ClaimDiagnostics(ActivitySource KernLab.Claim + W3C traceparent 注入——无监听器 零开销直通)+ TracedClaimStore(IClaimStore 装饰器——claim.store.<op> span,零业务代码侵入)+ TracedEmailSender + OtlpTraceExporter(自研 OTLP/HTTP JSON 编码;有界队列 1024 满即丢、 批量 5s/256、FlushAsync 手工驱动——宿主按 options.Otel 装配,嵌入形态按需自接)。

6. 反模式

症状 为什么错 正确形态
手写 JWT/手拼签名 alg 混淆攻击面(RFC 8725) JwtCodec 签发 + JwtValidator/SDK 验签(none 恒禁)
自解 CBOR / 手拼 COSE WebAuthn 攻击面(恶意嵌套/不定长/编码混淆) CborDecoder 子集(不定长与浮点恒拒)+ CoseKey 白名单
上游 ID token 只解不验签 联邦伪造(iss/aud/nonce 全可冒) UpstreamIdToken.ValidateAsync(验签矩阵 + alg 白名单独立于本域签发)
自管内存 store / 字典缓存 存储实现唯一性红线(两次判例:InMemory*Store 被删) IClaimStore + TierKv 介质 spec
应用层自拼「读-改-写」 破坏原子性分层(CAS/Functions/原子批是唯一原语) 引擎原子面(见 TIER.md 红线)
业务代码直用 System.IO IO 纪律红线 KernLab.Tier.Core.IO(TierFs)
TokenService 构造后改 Issuer 不回填 签发 iss 与 discovery 漂移 启动回填(BuildAsync 形态)后再发 token

7. 想深入