kataras/jwt

The jwt package is designed to prevent the classic JWT attack where an attacker changes the header to {"alg":"none"} to bypass signature verification.

This protection is achieved because the jwt.Verify function requires you to pass the expected algorithm as an argument. The package performs a byte-exact comparison between the algorithm you provided and the one in the token header. If they do not match exactly, it returns ErrTokenAlg before any signature check is even attempted.

Key Security Rules:

1. Always pin the algorithm: Never let the token header decide which algorithm to use. Always call jwt.Verify(jwt.HS256, ...) or similar.
2. Avoid NONE for credentials: The Enrich function (which adds claims and signs) refuses to work with the NONE algorithm to prevent creating unsigned credentials.
3. Explicit NONE usage: If you genuinely need an unsecured token (e.g., for client-side preferences), you must pass jwt.NONE explicitly to Sign and Verify.

There are two primary ways to include RFC 7519 standard claims alongside your custom data:

1. Struct Embedding: Embed jwt.Claims directly into your custom struct. This inlines the standard fields into a single flat JSON object.
2. Sign Options: Pass standard claims as variadic SignOption arguments to jwt.Sign. The package merges these options into the final payload. If multiple options set the same field, the last one wins.

Note on NoMaxAge: Because jwt.Claims options only write non-zero values (to avoid overwriting existing data with zeros), you cannot use a Claims struct to clear an existing expiry. Use jwt.NoMaxAge to explicitly clear Expiry and IssuedAt.

// Method 1: Embedding
type userClaims struct {
	Username string `json:"username"`
	Role     string `json:"role"`
	jwt.Claims
}

// Method 2: Sign Options
token, err := jwt.Sign(jwt.HS256, key, jwt.Map{"role": "admin"}, 
	jwt.MaxAge(15*time.Minute), 
	jwt.Issuer("auth.example.com"),
)

The jwt package contains several deliberate design choices that can lead to unexpected behavior if not understood. These 'sharp edges' fall into four categories:

1. Misleading Names: Some names suggest behavior contrary to the implementation. For example, Leeway is noted as particularly counter-intuitive.
2. Quiet Defaults: Certain defaults do not fail loudly when they should. Specifically:
   • MaxAge can collapse to 'no expiry' if misconfigured.
   • LoadHMAC can turn a file path into a secret if not used carefully.
3. High-Performance Hazards: To maintain speed, the package uses specific patterns that require strict adherence to rules:
   • Unsafe String Conversion: Used in BytesToString (based on unsafe.String).
   • Raw JSON Splice: Used in Merge, which can emit duplicate keys.
4. Breaking Changes: Significant behavioral shifts introduced in v0.2.0 to align with RFC standards.

The jwt.Claims struct models the seven registered claims defined by RFC 7519. It uses short JSON keys (e.g., exp, sub, iss) for the wire format and longer Go names for code readability.

Key characteristics:

• Timestamp fields (NotBefore, IssuedAt, Expiry) use omitzero to ensure that an unset value (0) is omitted from the JSON payload rather than being emitted as 0.
• Zero values are omitted: All fields use omitempty or omitzero, meaning a zero-value field (like an empty string or 0) will be absent from the resulting token. This allows Claims to be used as a partial template.
• origin_jti: This is a package-specific convention (not an RFC standard) used to link a refresh token to an access token for revocation purposes.

type Claims struct {
	NotBefore int64    `json:"nbf,omitzero"` 
	IssuedAt  int64    `json:"iat,omitzero"` 
	Expiry    int64    `json:"exp,omitzero"` 
	ID        string   `json:"jti,omitempty"` 
	OriginID  string   `json:"origin_jti,omitempty"` 
	Issuer    string   `json:"iss,omitempty"` 
	Subject   string   `json:"sub,omitempty"` 
	Audience  Audience `json:"aud,omitempty"` 
}

The choice between symmetric and asymmetric algorithms depends on your trust boundaries:

Symmetric (HMAC)

• Mechanism: The same []byte is used for both signing and verifying.
• Security Model: Anyone who can verify a token can also mint (sign) one.
• Best Use Case: Inside a single trust boundary (e.g., one process signing and verifying its own session tokens, or two closely related services sharing a secret).
• Trade-offs: Faster and simpler, but lacks non-repudiation (you cannot prove which specific service issued a token if multiple services share the key).

Asymmetric (RSA, ECDSA, EdDSA)

• Mechanism: Uses a private key for signing and a public key for verification.
• Security Model: The issuer holds the private key; verifiers only hold the public key. Verifiers cannot mint tokens.
• Best Use Case: When third parties need to verify tokens, or when verifiers live in environments where you would not want to store a signing secret.
• Trade-offs: Higher CPU cost for verification/signing and larger token sizes, but provides a clear separation of concerns.