jwtpeek

README

jwtpeek

Decode and verify JWT tokens in Go.

CLI

go install github.com/alesr/jwtpeek/cmd/jwtpeek@latest

jwtpeek -token eyJhbGciOiJIUzI1NiIs...

Decode and verify the signature (if you have the secret):

~ ❱ jwtpeek -token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30 -secret a-string-secret-at-least-256-bits-long
── HEADER ──────────────────────────────────
  Algorithm        HS256
  Type             JWT

── PAYLOAD ──────────────────────────────────
  Subject          1234567890
  Issued At        2018-01-18T01:30:22Z (8 years ago)
  ────────────────────────────────────
  admin            true
  name             John Doe

── STATUS ──────────────────────────────────
  ✓ Structure      Valid JWT with 3 parts
  ✓ Algorithm      HS256
  ✓ Issued At      Issued 8 years ago
  ⚠ Expiration     No 'exp' claim present
  ✓ Signature      Valid (verified with provided secret)

Library

go get github.com/alesr/jwtpeek

tok, err := jwtpeek.Decode(rawToken)
if err != nil {
    // malformed token
}

tok.Subject()   // "user-123"
tok.IsExpired() // true
tok.IsActive()  // not expired and nbf has passed

valid, err := tok.VerifyHMAC("my-secret") // HS256, HS384, HS512

All claims are also available as a raw map via tok.Claims.

Development

The library and CLI are separate Go modules. After cloning, set up a workspace so the CLI picks up the local library:

go work init . ./cmd/jwtpeek

Documentation

Overview

Package jwtpeek provides JWT token decoding, inspection, and validation without requiring the signing key upfront.

Tokens are decoded without signature verification by default. Signature verification can be performed separately via Token.VerifyHMAC.

Index

• func HeaderLabel(key string) string
• func IsTimeClaim(key string) bool
• func StandardClaimKeys() map[string]string
• type Header
• type Token
  • func Decode(tokenString string) (*Token, error)
  • func (t *Token) Audience() []string
  • func (t *Token) ExpiresAt() *time.Time
  • func (t *Token) ExtraClaimKeys() []string
  • func (t *Token) IsActive() bool
  • func (t *Token) IsExpired() bool
  • func (t *Token) IsNotYetValid() bool
  • func (t *Token) IssuedAt() *time.Time
  • func (t *Token) Issuer() string
  • func (t *Token) JWTID() string
  • func (t *Token) NotBefore() *time.Time
  • func (t *Token) Subject() string
  • func (t *Token) VerifyHMAC(secret string) (bool, error)

Functions

func HeaderLabel

func HeaderLabel(key string) string

HeaderLabel returns a human-readable label for known JOSE header parameters. For unrecognized keys it returns the key itself.

func IsTimeClaim

func IsTimeClaim(key string) bool

IsTimeClaim reports whether the given claim key is a registered time-based claim (exp, nbf, or iat).

func StandardClaimKeys

func StandardClaimKeys() map[string]string

StandardClaimKeys returns the set of registered JWT claim names as defined in RFC 7519 Section 4.1.

Types

type Header

type Header struct {
	Algorithm   string
	Type        string
	KeyID       string
	ContentType string
	Raw         map[string]any
}

Header represents the JOSE header of a JWT.

type Token

type Token struct {
	Header Header
	// standard claims (iss, sub, aud, exp, nbf, iat, jti)
	// can also be accessed via typed convenience methods
	Claims map[string]any
	// contains filtered or unexported fields
}

Token represents a decoded JWT.

func Decode

func Decode(tokenString string) (*Token, error)

Decode parses a JWT token string without verifying its signature. It returns the fully decoded Token or an error if the token is malformed.

func (*Token) Audience

func (t *Token) Audience() []string

Audience returns the "aud" claim value as a string slice.

func (*Token) ExpiresAt

func (t *Token) ExpiresAt() *time.Time

ExpiresAt returns the "exp" claim as a time.Time.

func (*Token) ExtraClaimKeys

func (t *Token) ExtraClaimKeys() []string

ExtraClaimKeys returns claim keys that are not part of the standard registered set, sorted alphabetically.

func (*Token) IsActive

func (t *Token) IsActive() bool

IsActive reports whether the token is currently usable: it is not expired and its "not before" time (if present) has passed.

func (*Token) IsExpired

func (t *Token) IsExpired() bool

IsExpired reports whether the token has an "exp" claim that is in the past.

func (*Token) IsNotYetValid

func (t *Token) IsNotYetValid() bool

IsNotYetValid reports whether the token has an "nbf" claim that is in the future.

func (*Token) IssuedAt

func (t *Token) IssuedAt() *time.Time

IssuedAt returns the "iat" claim as a time.Time.

func (*Token) Issuer

func (t *Token) Issuer() string

Issuer returns the "iss" claim value.

func (*Token) JWTID

func (t *Token) JWTID() string

JWTID returns the "jti" claim value.

func (*Token) NotBefore

func (t *Token) NotBefore() *time.Time

NotBefore returns the "nbf" claim as a time.Time.

func (*Token) Subject

func (t *Token) Subject() string

Subject returns the "sub" claim value.

func (*Token) VerifyHMAC

func (t *Token) VerifyHMAC(secret string) (bool, error)

VerifyHMAC verifies the token signature using the given HMAC secret. It supports HS256, HS384, and HS512 algorithms. Returns true if the signature is valid, false otherwise. Error only if the algorithm is unsupported for HMAC verification.