# README

jwthelperV2

jwt标准过于简单,往往在生产上并不是简单使用,本项目基于我的这篇博文.在可以进行简单签名简单验签的同时也支持使用伴生的刷新jwt做自动刷新令牌.

本项目本质上只是github.com/golang-jwt/jwt/v4的封装,只是提供了相对更友好的接口和一些专用模式封装而已

V2版本只支持go 1.18+,低版本请使用V0版本

特性

有Signer类用于作为签名器
有Verifier类用于做签名校验器
提供Meta函数用于查看签名器和签名校验器的元信息
提供接口UniversalJwtSigner和UniversalJwtVerifier方便抽象
支持主流的RS256,RS384,RS512,ES256,ES384,ES512,HS256,HS384,HS5129种算法用于签名和校验
支持构造jwt时同时创建伴生的刷新jwt,同时也支持校验这种token
使用类似grpc的函数接口风格构造可选参数,提供丰富的可选项

用法

简单签名和验签

```golang
//签名,默认使用HS256算法,jti使用uuid4生成可以配置改为sonyflake或者自己实现一个满足接口`utils/idgener.IDGen`的id生成器
signer, err := NewSigner()
if err != nil {
    return err
}
payload := testPayLoad{
    A: 1,
    B: "B",
    C: 1.2,
}
//签名时可以添加sub等信息
token, err := signer.Sign(payload, signoptions.WithSub("test"),signoptions.WithAud("testaud"))

//验签,默认使用HS256算法
verifier, err := NewVerifier(WithDefaultAUD("testaud"), WithDefaultISSRange(signer.Meta().Iss))
if err != nil {
    return err
}
payload1 := testPayLoad{}
//可以校验iss,aud和sub等
jti, timeleft, err := verifier.Verify(token, &payload1,veriffyoptions.WithSUBMustBe(test))
if err == nil {
    return err
}
```

带fresh_token的签名和对应验签

```golang
//签名
signer, err := NewSigner()
if err != nil {
    return err
}
payload := testPayLoad{
    A: 1,
    B: "B",
    C: 1.2,
}
//签名的不同之处只是增加了选项`signoptions.WithRefreshTTL`
token, err := signer.Sign(payload, signoptions.WithSub("test"),signoptions.WithAud("testaud"),signoptions.WithRefreshTTL(time.Hour*24))

//验签
verifier, err := NewVerifier(WithDefaultAUD("testaud"), WithDefaultISSRange(signer.Meta().Iss))
if err != nil {
    return err
}
payload1 := testPayLoad{}
//会根据token中`RefreshToken`字段是否为空值来确定是简单jwt还是带伴生fresh_tokende的
jti, timeleft, err := verifier.Verify(token, &payload1,veriffyoptions.WithSUBMustBe(test))
if err == nil {
    return err
}
```

更多的方法可选项可以看文档

附加工具

cmd目录用于构造jwthelper的命令行工具,这个工具提供如下工具:

jwthelper createkey用于创建公私钥对
jwthelper signer,用于启动一个基于grpc的签名器服务端,具体接口请查看pbschema/jwtsigner.proto
jwthelper verifier,用于启动一个基于grpc的签名校验器服务端,具体接口请查看pbschema/jwtverifier.proto

这个工具也可以使用docker使用,托管在dockerhub上的hsz1273327/jwthelper下

附加模块

utils/idgener模块提供两个IDGen接口的实现分别是
- UUID4Gen,使用uuid4生成全局唯一id
- SonyflakeGen,使用github.com/sony/sonyflake生成全局唯一id
utils/machineid模块用于通过本机的第一张网卡的ip生成机器id
utils/keygener模块用于生成随机的公私钥对
proxy用于代理满足UniversalJwtSigner和UniversalJwtVerifier接口的对象
sdk用于对接cmd中提供的grpc,使用它构造的对象也分别满足UniversalJwtSigner和UniversalJwtVerifier接口
gin_middlewaregin的校验模块工具