#MoonGrd

安全信道(PSK-CR 握手 / HKDF / AEAD seq-IV / 滑窗防重放)不属于本框架—— 那是 TLS 层的活,住传输侧(moonkcp secchan)。本框架的 token 走信道传。

#特性

• token 核:双 token 签发/校验/带门校验,定序 JSON + base64url 线形, HMAC 签名;时间与熵全参数注入(核心零时钟零随机)。
• 旋转语义:refresh 一次性作废,已用票再现 = 重放,自动撤全族。
• 四段门:段段审计、拒绝短路带拒因;三种姿势任选(回调方言 / 标签 钩子 / 泛型全权)。
• 五个换挡位(全 trait):算法 Signer、AEAD Cipher、认证协议 AuthProtocol、存储 RefreshStore/RevocationStore、信道 Handshake (外置 secchan)——新实现 = 新 impl,框架零改。
• stock 预制 + 一键换装:名单准入/回声派工/审计三形现成,FlexDoor swap_* 运行时热换(紧急停门一行)。

#安装

moon add thy1016/moongrd

#快速上手

#登录与校验(token 核)

let config = @moongrd.GuardConfig::make(
  issuer="demo-iss",
  audience="demo-app",
  access_ttl_ms=60000L,
  refresh_ttl_ms=600000L,
)
let signer : &@moongrd.Signer = @mooncry.HmacSha256Signer::new(session_key)
// 签发:时间与熵(jti)由调用方注入
let access = @moongrd.issue(config, signer, now, "alice", @moongrd.TokenType::Access, jti_a)
let refresh = @moongrd.issue(config, signer, now, "alice", @moongrd.TokenType::Refresh, jti_r)
// 业务门:typ 不对即拒
match @moongrd.verify_for(config, signer, now, access.token, @moongrd.TokenType::Access) {
  Ok(claims) => // claims.sub 即主体
  Err(e) => // 拒因:过期/签名不符/型不符……
}

#四段门(三种姿势,按手感选)

pub impl DoorHandler for MyDoor with admit(self : MyDoor, sub : String) -> Bool { ... }
pub impl DoorHandler for MyDoor with dispatch(self : MyDoor, sub : String, req : Json) -> Json { ... }
pub impl DoorHandler for MyDoor with audit(self : MyDoor, e : @moongrd.AuditEvent) -> Unit { ... }

let door = @handler.mount(config=config, signer=signer,
                          revocations=revocations, handler=my_door)
let resp = door.run(now, access_token, req)

let door = @moongrd.Guard::new(
  config=config, signer=signer, revocations=revocations,
  resolve=async fn(sub : String) -> User? { ... },        // sub → 主体
  dispatch=async fn(u : User, req : Req) -> Resp { ... }, // 业务到达
)

let door = @moongrd.Guard::new(
  config=config, signer=signer, revocations=revocations,
  resolve=..., dispatch=...,
  audit=async fn(e : @moongrd.AuditEvent) -> Unit { ... },
  protocol=my_protocol,
)

#换发与旋转

match @moongrd.refresh(config, signer, store, now, refresh_token, next_jti) {
  Ok(r) => // 新 refresh 到手;access 用 issue() 另发
  Err(@moongrd.RefreshErr::Replayed(family)) => // 盗用!全族已自动作废
  Err(@moongrd.RefreshErr::Verify(Expired(_))) => // 回握手重登录
  ...
}

#预制回调与一键换装

let handler = @handler.FlexDoor::demo(allow=["alice"], prefix="[admin] ")
// 运行时一键换装(已挂门即时生效):
handler.swap_admit(admit=@handler.admit_none())   // 紧急停门
handler.swap_admit(admit=@handler.admit_allowlist(allow=["alice", "carol"]))
handler.swap_audit(audit=@handler.audit_collector(log=lines))

#示例廊(四口,一键可跑)

moon run examples/walkthrough          # 全链六幕:登录/门/旋转/重放撤族/篡改拒
moon run examples/session_lifecycle    # 会话一生五幕:登录→过期→换发→登出
moon run examples/handler_demo         # 回调方言三幕
moon run examples/signer_swap          # 换 verify 算法三幕(HMAC-SHA512/CMAC/Ed25519)

#API 总览

#错误面

VerifyErr   Malformed(线形/编码/定型败) · BadMac(签名不符/篡改)
            · Expired(claims) · NotYetValid(claims) · WrongIssuer(claims)
            · WrongAudience(claims) · WrongType(claims)
RefreshErr  Verify(内含 VerifyErr;Expired = 回握手信号)
            · UnknownToken(mac 过但账本无记录) · Replayed(family)(已撤族)
            · Revoked(claims)
GuardErr    Verify(内含) · Revoked · Unresolved(sub)

#设计边界

#测试与验证

moon test --target native        # 38 罐

#许可证