GJJ.Keystone.Toolkit 4.2.2

GJJ.Keystone.Toolkit

GJJ Keystone 体系的运行时通用工具库：国密加密、JWT 颁发与验证、AES 传输加密、Excel 导入导出、跨平台验证码、网络辅助等。不依赖 ASP.NET Core，可在 Worker / Console / Desktop 等任意宿主复用。

为什么独立成包

• GJJ.Keystone.Abstractions 只放契约，不能携带 BouncyCastle、NPOI 这类运行时依赖。
• GJJ.Keystone.AspNetCore 强依赖 HTTP 管道，但加解密 / Token 颁发 / Excel 处理本身与 Web 无关。
• 把这些工具沉淀到独立包，让定时任务、消息消费者、命令行工具等非 Web 宿主也能直接复用，且不会被迫引入 Microsoft.AspNetCore.App。

内容概览

国密 SM2/SM3/SM4（Security/SM/）

AES 传输加密（Security/AES/）

JWT（Security/Tokens/）

Excel（Excel/）

• ExcelCore：基于 NPOI 的轻量封装（WorkBook / Sheet / Cell / RowCollection），支持 .xls 和 .xlsx、样式、列宽、对齐、字体颜色等。
• Excel.Attributes：[Row] / [Column] 注解驱动的实体 ↔ 工作表映射。
• NpoiExcelExportHelper：常用导出辅助（创建行 / 单元格 / 样式、设置下拉框等）。

验证码与网络（Utils/）

• CaptchaHelper：基于 ImageSharp 的跨平台图形验证码（Linux 含银河麒麟可用，不依赖 System.Drawing.Common）。
• NetworkHelper：本机 IPv4 获取（跨 Windows / macOS / Linux），简单的带 Bearer Token 的 HTTP POST / GET 封装。

客户端 IP 解析（含 X-Forwarded-For 等代理头）请使用 GJJ.Keystone.AspNetCore.Utils.NetworkHelper.GetIP()。

典型用法

颁发与验证 JWT

using GJJ.Keystone.Toolkit.Security.Tokens;

var jwtSecurityKey = configuration["Jwt:SecurityKey"]
    ?? throw new InvalidOperationException("配置缺失：Jwt:SecurityKey");

var opts = new JwtIssuerOptions
{
    Issuer = "https://auth.gjj.local",
    Audience = "gjj-mgmt-api",
    SecurityKey = jwtSecurityKey,
    DefaultLifetime = TimeSpan.FromHours(1)
};

var svc = new JwtTokenService(opts);
var result = svc.GenerateToken(
    subject: "u-001",
    name: "张三",
    roles: new[] { "admin" },
    extraClaims: new Dictionary<string, object> { ["env"] = "dev" });

Console.WriteLine($"token={result.AccessToken}, expiresAt={result.ExpiresAtUtc:O}");

if (svc.TryValidate(result.AccessToken, out var principal))
    Console.WriteLine($"sub={principal!.FindFirst("sub")?.Value}");

服务断言 JWT（RS256）

JwtAssertionBuilder 用于服务端向授权中心提交短期断言 JWT。接当前授权中心时不要设置 Kid()，因为授权中心侧公钥没有 KeyId，设置后会导致验签失败。

using GJJ.Keystone.Toolkit.Security.Tokens;

var assertion = JwtAssertionBuilder.New()
    .Issuer("GJJ.Member.Api")
    .Audience("gjj-auth-center")
    .Subject("u-001")
    .Name("张三")
    .AddRole("member")
    .ExpiresIn(TimeSpan.FromSeconds(60))
    .UseRsaPrivateKeyPem(privateKeyPem)
    .Build();

在 macOS ARM64 上，标准 RSA 签名路径可能触发 rsa_priv_crypt failed(ccerr=-27)；JwtAssertionBuilder 在 Toolkit 4.2.2 起已内置 BouncyCastle CRT 签名分支，业务服务不要再复制本地版本。

SM4-GCM 加解密（v1 传输）

using GJJ.Keystone.Toolkit.Security.SM;
using Microsoft.Extensions.Options;

var opts = Options.Create(new SMTransportOptions
{
    Mode = "GCM",
    Kid = "sm4-2025",
    KeyHex = "00112233445566778899AABBCCDDEEFF",
    GcmTagBits = 128
});

var crypto = new SmTransportCrypto(opts);
var key = crypto.GetKeyBytesFromKid("sm4-2025");
var iv  = SmTransportCrypto.RandomBytes(12);
var aad = System.Text.Encoding.UTF8.GetBytes("POST\nsm4-2025\n1700000000\nnonce\n");

var (cipher, tag) = crypto.Sm4EncryptGcmSplit(plain: "hello"u8.ToArray(), key, iv, aad);
var plain = crypto.Sm4DecryptGcmSplit(cipher, tag, key, iv, aad);

NPOI Excel 导出

using GJJ.Keystone.Toolkit.Excel.ExcelCore;

using var book = new WorkBook(ExcelVersion.Xlsx);
var sheet = book.CreateSheet("用户");
sheet.AppendHeader<UserRow>(rowIndex: 0);
foreach (var u in users) sheet.AppendRow(u);
book.Save("users.xlsx");

设计约束

• 零 ASP.NET 依赖：所有类型不引用 Microsoft.AspNetCore.*，便于在任何宿主中使用。
• 启动期校验：SmTransportCrypto / AesTransportOptions 在构造时校验 KeyHex / Mode / GcmTagBits 等，避免到运行期才暴露配置错误。
• 跨平台：图像 / 验证码使用 ImageSharp（不依赖 System.Drawing.Common），在 Linux（含银河麒麟）下行为一致。

已知限制

• 仅 .NET 8.0；不支持更低版本。
• SmTransportCrypto 当前仅支持 SM4-GCM v1，CBC 模式仍保留启动期校验占位但已被 v1 协议放弃。
• JwtTokenService 仅接受 HS256；服务端断言 JWT 的 RS256 场景请使用 JwtAssertionBuilder。若要扩展访问 JWT 到 RS256 / ES256，需要另行设计验签配置和密钥发布策略。
• NetworkHelper.PostJson / GetJson 为简易封装，生产场景建议改用 IHttpClientFactory + Polly。