#MoonGard

#包结构

#特性

• token 核:双 token 签发/校验/带门校验,定序 JSON + base64url 线形,HMAC 签名;时间与熵全参数注入(核心零时钟零随机)。
• 旋转语义:refresh 一次性作废;已用票再现判定为重放,自动撤销 全族。
• 四段门:段段审计、拒绝短路带拒因;回调方言 / 标签钩子 / 泛型 钩子三种接入方式。
• 五个 trait 换挡位:Signer、Cipher、AuthProtocol、 RefreshStore、RevocationStore——新实现即新 impl,框架不改。
• 预制回调与运行时换装:名单准入、回声派工、审计三形现成; FlexDoor swap_* 运行时替换,即时生效。

#安装

moon add thy1016/moongard

#快速上手

#签发与校验(token 核)

let config = @moongard.GuardConfig::make(
  issuer="demo-iss",
  audience="demo-app",
  access_ttl_ms=60000L,
  refresh_ttl_ms=600000L,
)
let signer : &@moongard.Signer = @mooncry.HmacSha256Signer::new(session_key)
// 签发:时间与熵(jti)由调用方注入
let access = @moongard.issue(config, signer, now, "alice", @moongard.TokenType::Access, jti_a)
let refresh = @moongard.issue(config, signer, now, "alice", @moongard.TokenType::Refresh, jti_r)
// 业务门:typ 不对即拒
match @moongard.verify_for(config, signer, now, access.token, @moongard.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 : @moongard.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 = @moongard.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 = @moongard.Guard::new(
  config=config, signer=signer, revocations=revocations,
  resolve=..., dispatch=...,
  audit=async fn(e : @moongard.AuditEvent) -> Unit { ... },
  protocol=my_protocol,
)

#换发与旋转

match @moongard.refresh(config, signer, store, now, refresh_token, next_jti) {
  Ok(r) => // 新 refresh 到手;access 用 issue() 另发
  Err(@moongard.RefreshErr::Replayed(family)) => // 重放:全族已自动作废
  Err(@moongard.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 项测试

#许可证