pwt

README

PWT — Protobuf Web Token

PWT (Protobuf Web Token) is a Go library that stores JWT-style claims in Protocol Buffers. Tokens use the signing algorithms from github.com/golang-jwt/jwt/v5 and the API mirrors JWT. This approach yields smaller tokens and faster parsing. Custom data lives in a protobuf Struct. The TokenBody type also implements jwt.Claims for easy validation.

---

⚡ Benchmark

Tested on Apple M1 Pro (arm64):

Metric	pwt.Parse	jwt.Parse (standard)	Improvement
Ops/sec	859,675	404,224	🏆 2.13× faster
Time (ns/op)	1,365	2,975	🏆 ~54% faster
Memory (B/op)	1,752	2,760	🏆 ~37% smaller
Allocs (per op)	32	59	🏆 ~46% fewer

✅ PWT outperforms standard JWT parsing in every metric — speed, memory, and allocation count.

---

Why PWT?

• ✅ Smaller tokens via protobuf serialization
• 🚀 Faster parse + verify routines
• 🔒 Uses JWT's mature signing algorithms under the hood
• 🔁 Drop-in compatible with jwt.Claims; custom data lives in TokenBody.Payload

---

Installation

go get github.com/mobinova/pwt-go

🔁 Migrating from JWT

PWT is designed to be a drop-in replacement for github.com/golang-jwt/jwt/v5.

Standard Claims

PWT maps 1:1 with standard JWT claims:

JWT Claim	PWT Field
iss	Iss
sub	Sub
aud	Aud
exp	Exp (int64)
nbf	Nbf (int64)
iat	Iat (int64)
jti	Jti

Custom Claims

JWT's custom claims (i.e., MapClaims) should be migrated to the Payload field of PWT:

Payload: &structpb.Struct{
    Fields: map[string]*structpb.Value{
        "your_key": structpb.NewStringValue("your_value"),
    },
}

Example Migration

// JWT
jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
    "sub": "123",
    "role": "admin",
})

// PWT
pwt.NewWithClaims(jwt.SigningMethodHS256, &pwt.TokenBody{
    Sub: "123",
    Payload: &structpb.Struct{
        Fields: map[string]*structpb.Value{
            "role": structpb.NewStringValue("admin"),
        },
    },
})

Building Libraries in Other Languages

See LIBRARY_GUIDE.md for how to generate bindings. It also covers security notes for libraries outside Go.

Contributing

See CONTRIBUTING.md for setup instructions and submission guidelines.

License

This project is licensed under the MIT License.

Documentation

Index

• Variables
• type KeyFunc
• type Token
  • func New(method jwt.SigningMethod, body *TokenBody) *Token
  • func NewVersioned(method jwt.SigningMethod, body *TokenBody, version string) *Token
  • func NewWithClaims(method jwt.SigningMethod, body *TokenBody) *Token
  • func Parse(tokenString string, keyFunc KeyFunc) (*Token, error)
  • func (t *Token) SignedString(key interface{}) (string, error)
• type TokenBody
  • func (*TokenBody) Descriptor() ([]byte, []int)
  • func (x *TokenBody) GetAud() string
  • func (x *TokenBody) GetExp() int64
  • func (x *TokenBody) GetIat() int64
  • func (x *TokenBody) GetIss() string
  • func (x *TokenBody) GetJti() string
  • func (x *TokenBody) GetNbf() int64
  • func (x *TokenBody) GetPayload() *structpb.Struct
  • func (x *TokenBody) GetSub() string
  • func (*TokenBody) ProtoMessage()
  • func (x *TokenBody) ProtoReflect() protoreflect.Message
  • func (x *TokenBody) Reset()
  • func (x *TokenBody) String() string
  • func (c *TokenBody) Valid() error
  • func (c *TokenBody) ValidWithLeeway(leeway time.Duration) error
• type TokenHeader
  • func (*TokenHeader) Descriptor() ([]byte, []int)
  • func (x *TokenHeader) GetAlg() string
  • func (x *TokenHeader) GetVersion() string
  • func (*TokenHeader) ProtoMessage()
  • func (x *TokenHeader) ProtoReflect() protoreflect.Message
  • func (x *TokenHeader) Reset()
  • func (x *TokenHeader) String() string

Variables

var (
	ErrTokenExpired     = errors.New("token is expired")
	ErrTokenNotValidYet = errors.New("token is not yet valid (nbf)")
)

Sentinel errors for token validation results.

var File_pwt_proto protoreflect.FileDescriptor

Types

type KeyFunc

type KeyFunc func(*Token) (interface{}, error)

KeyFunc returns the signing key used to verify a token. The function receives the parsed Token and may return an error if the key cannot be determined.

type Token

type Token struct {
	Header *TokenHeader
	Body   *TokenBody
	Method jwt.SigningMethod
}

Token is a Protobuf Web Token consisting of a header, body and the signing method used to create it.

func New

func New(method jwt.SigningMethod, body *TokenBody) *Token

New creates a Token with header version "1.0" using the provided signing method.

func NewVersioned

func NewVersioned(method jwt.SigningMethod, body *TokenBody, version string) *Token

NewVersioned creates a Token with the supplied version string and signing method.

func NewWithClaims

func NewWithClaims(method jwt.SigningMethod, body *TokenBody) *Token

NewWithClaims mirrors jwt.NewWithClaims for compatibility.

func Parse

func Parse(tokenString string, keyFunc KeyFunc) (*Token, error)

Parse decodes tokenString and verifies the signature using keyFunc. It returns the parsed Token if verification succeeds.

func (*Token) SignedString

func (t *Token) SignedString(key interface{}) (string, error)

SignedString marshals the token and returns a signed compact string. The provided key is passed to the signing method.

type TokenBody

type TokenBody struct {
	Iss     string           `protobuf:"bytes,1,opt,name=iss,proto3" json:"iss,omitempty"`
	Sub     string           `protobuf:"bytes,2,opt,name=sub,proto3" json:"sub,omitempty"`
	Aud     string           `protobuf:"bytes,3,opt,name=aud,proto3" json:"aud,omitempty"`
	Exp     int64            `protobuf:"varint,4,opt,name=exp,proto3" json:"exp,omitempty"`
	Nbf     int64            `protobuf:"varint,5,opt,name=nbf,proto3" json:"nbf,omitempty"`
	Iat     int64            `protobuf:"varint,6,opt,name=iat,proto3" json:"iat,omitempty"`
	Jti     string           `protobuf:"bytes,7,opt,name=jti,proto3" json:"jti,omitempty"`
	Payload *structpb.Struct `protobuf:"bytes,8,opt,name=payload,proto3" json:"payload,omitempty"`
	// contains filtered or unexported fields
}

func (*TokenBody) Descriptor

func (*TokenBody) Descriptor() ([]byte, []int)

Deprecated: Use TokenBody.ProtoReflect.Descriptor instead.

func (*TokenBody) GetAud

func (x *TokenBody) GetAud() string

func (*TokenBody) GetExp

func (x *TokenBody) GetExp() int64

func (*TokenBody) GetIat

func (x *TokenBody) GetIat() int64

func (*TokenBody) GetIss

func (x *TokenBody) GetIss() string

func (*TokenBody) GetJti

func (x *TokenBody) GetJti() string

func (*TokenBody) GetNbf

func (x *TokenBody) GetNbf() int64

func (*TokenBody) GetPayload

func (x *TokenBody) GetPayload() *structpb.Struct

func (*TokenBody) GetSub

func (x *TokenBody) GetSub() string

func (*TokenBody) ProtoMessage

func (*TokenBody) ProtoMessage()

func (*TokenBody) ProtoReflect

func (x *TokenBody) ProtoReflect() protoreflect.Message

func (*TokenBody) Reset

func (x *TokenBody) Reset()

func (*TokenBody) String

func (x *TokenBody) String() string

func (*TokenBody) Valid

func (c *TokenBody) Valid() error

Valid implements jwt.Claims.

func (*TokenBody) ValidWithLeeway

func (c *TokenBody) ValidWithLeeway(leeway time.Duration) error

ValidWithLeeway validates time-based claims with an allowed clock skew.

type TokenHeader

type TokenHeader struct {
	Alg     string `protobuf:"bytes,1,opt,name=alg,proto3" json:"alg,omitempty"`
	Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
	// contains filtered or unexported fields
}

func (*TokenHeader) Descriptor

func (*TokenHeader) Descriptor() ([]byte, []int)

Deprecated: Use TokenHeader.ProtoReflect.Descriptor instead.

func (*TokenHeader) GetAlg

func (x *TokenHeader) GetAlg() string

func (*TokenHeader) GetVersion

func (x *TokenHeader) GetVersion() string

func (*TokenHeader) ProtoMessage

func (*TokenHeader) ProtoMessage()

func (*TokenHeader) ProtoReflect

func (x *TokenHeader) ProtoReflect() protoreflect.Message

func (*TokenHeader) Reset

func (x *TokenHeader) Reset()

func (*TokenHeader) String

func (x *TokenHeader) String() string