#moon-httpsig

Project/module: xiguaAp6y3/moon-httpsig Repository: https://github.com/xiguaAp6y3/moon-httpsig Version: 0.1.0 License: Apache-2.0

#中文项目介绍

• HTTP 消息模型：保序、可含同名多值、区分 Header/Trailer 的请求与响应模型；
• Structured Field 子集：RFC 9651 的 Dictionary / Inner List / Item / Parameters 解析与规范序列化；
• 组件解析：@method、@target-uri、@authority、@scheme、 @request-target、@path、@query、@query-param、@status 等派生组件， 以及普通 Header / Trailer / related request 字段组件（含 sf、bs、 key、tr、req 参数）；
• 签名基：按 RFC 9421 §2.5 逐字节构造签名基；
• 算法：内置 hmac-sha256（基于成熟 SHA-256 依赖，按 RFC 2104 构造）， 其余算法名只预留、不实现、不返回假的验签成功；
• 验证策略：算法白名单、时间（created/expires/最大年龄/时钟偏移）、 required components、keyid、nonce、tag、Content-Digest 绑定、多签名策略；
• CLI：httpsig-tool，输出稳定 JSON；
• 可执行示例：签名/验签/响应签名/多签名/防重放/Content-Digest 绑定；
• HTTP/1.1 文本适配器：adapters/http11。

#English Summary

#RFC 9421 简介

#项目价值

• 为 MoonBit 提供 RFC 9421 的标准能力，作为 API/Webhook 消息完整性基础件；
• 签名基逐字节与 RFC Appendix B 测试向量比对；
• 结构化错误（HsErrorStage/HsErrorKind/offset/context），便于自动化处理；
• 默认安全：算法白名单、时间校验、防重放、Content-Digest 绑定；
• 不联网解析 keyid，不把 keyid 当作可信身份。

#功能支持矩阵

#不支持内容

• JWT 库；
• HTTP 服务器或客户端；
• TLS 实现；
• 通用密码学库；
• 身份认证/授权平台；
• 旧版 Cavage HTTP Signatures Draft 实现。

#本地使用方式

git clone https://github.com/xiguaAp6y3/moon-httpsig.git
cd moon-httpsig
moon add gmlewis/sha256          # 已写入 moon.mod，无需重复执行
moon test                        # 运行全部测试（默认目标）
moon run cmd/httpsig-tool -- --help

moon check --target wasm-gc && moon build --target wasm-gc && moon test --target wasm-gc
moon check --target js && moon build --target js && moon test --target js
moon check --target native && moon build --target native && moon test --target native

powershell -ExecutionPolicy Bypass -File scripts\verify_all.ps1

#请求签名

let options : SignOptions = {
  label: "sig1",
  components: [
    covered_derived(DerivedComponent::Method),
    covered_field("content-type"),
  ],
  parameters: params,   // created/keyid/...
  algorithm: "hmac-sha256",
  key,
}
let signed = sign_request(request, options, Limits::default()).unwrap()
// signed.signature_input / signed.signature / signed.signature_base

#请求验签

let report = verify_request(
  request,
  signed.signature_input,
  signed.signature,
  resolver,       // InMemoryKeyResolver（生产环境应替换为共享存储）
  policy,         // VerificationPolicy
  clock,          // FixedClock / SystemClock
  nonces,         // InMemoryNonceStore
  Limits::default(),
  MultiSignaturePolicy::AnyValid,
).unwrap()
// report.verified / report.rejected

#响应签名

let req_component = covered_derived_with_params(
  DerivedComponent::Method,
  { sf: false, key: None, bs: false, tr: false, req: true, name: None },
)
let signed = sign_response(response, options_with(req_component), Limits::default()).unwrap()

#多签名

#HMAC 安全说明

• hmac-sha256 是共享密钥方案，不提供公钥验签；密钥分发与管理由应用负责。
• MAC 比较使用 constant_time_equal，禁止用 == 直接比较。
• 本库不实现 SHA-256，而是使用成熟依赖 gmlewis/sha256（Apache-2.0）。
• 详见 docs/security.md。

#Content-Digest

#CLI

moon run cmd/httpsig-tool -- --help
moon run cmd/httpsig-tool -- --version
moon run cmd/httpsig-tool -- parse-input --signature-input 'sig1=("@method" "@target-uri");created=1618884473;keyid="k1"'
moon run cmd/httpsig-tool -- parse-signature --signature 'sig1=:dGVzdA==:'
moon run cmd/httpsig-tool -- parse-accept --accept-signature 'a=("@method");created;keyid="k"'
moon run cmd/httpsig-tool -- build-base --method POST --path /foo --header 'content-type=application/json' --signature-input 'sig1=("@method" "content-type");created=1618884473;keyid="k1";alg="hmac-sha256"'
moon run cmd/httpsig-tool -- sign-hmac --method POST --path /foo --header 'content-type=application/json' --secret-hex 736563726574 --keyid k1 --created 1700000000 --component @method
moon run cmd/httpsig-tool -- verify-hmac --method POST --path /foo --header 'content-type=application/json' --secret-hex 736563726574 --keyid k1 --now 1700000000 --signature-input 'sig1=("@method");created=1700000000;keyid="k1";alg="hmac-sha256"' --signature 'sig1=:...:'
moon run cmd/httpsig-tool -- inspect --signature-input 'sig1=("@method");created=1618884473;keyid="k1"'
moon run cmd/httpsig-tool -- check-policy --signature-input 'sig1=("@method");created=1618884473;keyid="k1"' --required-component @method
moon run cmd/httpsig-tool -- rfc-example

#Examples

moon run examples/sign_request
moon run examples/verify_request
moon run examples/sign_response
moon run examples/multiple_signatures
moon run examples/replay_policy
moon run examples/content_digest_binding

#测试结果

• 具名测试：101 个（根目录 94 + 适配器 7）；
• 表格案例：91 个表驱动条目；
• 确定性属性测试：1100 组固定种子 sign→verify 循环（1000 组完整循环 + 100 组覆盖/未覆盖变更判定）；
• RFC 9421 Appendix B 的 HMAC 示例与签名基示例逐字节通过；
• wasm-gc、js、native 三目标：check/build/test 均通过，0 errors， 0 warnings（reserved_keyword 因规范要求保留 method 字段名而被抑制）。

#目录结构

├── cmd/httpsig-tool/        CLI
├── adapters/http11/         HTTP/1.1 文本适配器
├── docs/                    文档
├── examples/                6 个可执行示例
├── scripts/                 行数统计、fixture 生成/校验、一键验证
├── testdata/rfc9421/        RFC 测试向量
├── moon.mod / moon.pkg
└── *.mbt                    核心库

#Roadmap

• v0.1.0（当前）：RFC 9421 核心、HMAC、策略、CLI、测试。
• v0.2.0：完整 RFC 9651 Adapter、更多 HTTP Adapter。
• v0.3.0：Ed25519 Provider 与远程 Resolver 示例。
• v0.4.0：Webhook、ActivityPub、API Gateway Profile。

#License

#发布状态