docs(cryptojwt): enhance API documentation with security considerations

docs(cryptojwt): enhance API documentation with security considerations

Author: sgaunet

pkg/cryptojwt/esjwt.go

@@ -42,6 +42,21 @@ type esjwtDecoderWithCachedPublicKey struct {
 }
 
 // NewES256Encoder creates a new ECDSA-SHA256 JWT encoder with a private key file.
+//
+// Parameters:
+//   - privateKeyFile: Path to PEM-encoded ECDSA private key file (P-256 curve)
+//
+// Security: Private key files should be protected with strict file permissions (0600).
+// Never commit private keys to version control. ECDSA keys are typically smaller than
+// RSA keys while providing equivalent security (256-bit ECDSA ≈ 3072-bit RSA).
+//
+// Example:
+//
+//	encoder := cryptojwt.NewES256Encoder("ec-private.pem")
+//	token, err := encoder.Encode(`{"user":"alice","exp":1735689600}`)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
 func NewES256Encoder(privateKeyFile string) Encoder {
 	return &esjwtEncoderWithPrivateKeyFile{
 		method:         jwt.SigningMethodES256,
@@ -108,6 +123,21 @@ func NewES512DecoderWithPrivateKeyFileAndValidation(privateKeyFile string, valid
 }
 
 // NewES256DecoderWithPublicKeyFile creates a new ECDSA-SHA256 JWT decoder with a public key file.
+//
+// Parameters:
+//   - publicKeyFile: Path to PEM-encoded ECDSA public key file (P-256 curve)
+//
+// Note: Public keys can be safely distributed. Ensure you obtain public keys from
+// trusted sources to prevent signature validation bypasses.
+//
+// Example:
+//
+//	decoder := cryptojwt.NewES256DecoderWithPublicKeyFile("ec-public.pem")
+//	claims, err := decoder.Decode(token)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	fmt.Println(claims) // {"user":"alice","exp":1735689600}
 func NewES256DecoderWithPublicKeyFile(publicKeyFile string) Decoder {
 	return NewES256DecoderWithPublicKeyFileAndValidation(publicKeyFile, ValidationOptions{})
 }
@@ -122,7 +152,25 @@ func NewES256DecoderWithPublicKeyFileAndValidation(publicKeyFile string, validat
 }
 
 // NewES256EncoderWithCache creates a new ECDSA-SHA256 JWT encoder with cached private key.
-// The private key is loaded once at creation time, improving performance for repeated operations.
+//
+// The private key is loaded once at creation time, improving performance for repeated
+// operations. This is recommended for high-throughput scenarios.
+//
+// Security: The cached key remains in memory for the lifetime of the encoder. Private
+// key files should have strict file permissions (0600).
+//
+// Performance: Eliminates repeated file reads and key parsing for encoding many tokens.
+//
+// Example:
+//
+//	encoder, err := cryptojwt.NewES256EncoderWithCache("ec-private.pem")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	for i := 0; i < 1000; i++ {
+//	    token, _ := encoder.Encode(fmt.Sprintf(`{"id":%d}`, i))
+//	    fmt.Println(token)
+//	}
 func NewES256EncoderWithCache(privateKeyFile string) (Encoder, error) {
 	privateKey, _, err := readECDSAPrivateKey(privateKeyFile)
 	if err != nil {

pkg/cryptojwt/hsjwt.go

@@ -31,16 +31,46 @@ func validateSecretLength(secret []byte, minLength int, algorithm string) error
 }
 
 // NewHS256Encoder creates a new HMAC-SHA256 JWT encoder/decoder.
+//
+// Security: The secret should be at least 256 bits (32 bytes) for HS256.
+// Weak secrets are vulnerable to brute-force attacks. By default, this function
+// enforces minimum secret length according to RFC 7518. Use NewHS256EncoderWithOptions
+// with allowWeakSecret=true only for testing purposes.
+//
+// Example:
+//
+//	secret := []byte("my-32-byte-secret-key-for-hs256")
+//	encoder := cryptojwt.NewHS256Encoder(secret)
+//	token, err := encoder.Encode(`{"user":"alice","exp":1735689600}`)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	fmt.Println(token) // eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 func NewHS256Encoder(secret []byte) EncoderDecoder {
 	return NewHS256EncoderWithOptions(secret, false)
 }
 
 // NewHS256EncoderWithOptions creates a new HMAC-SHA256 JWT encoder/decoder with options.
+//
+// Parameters:
+//   - secret: The shared secret key (minimum 32 bytes recommended)
+//   - allowWeakSecret: If true, allows secrets shorter than 32 bytes (TESTING ONLY)
+//
+// Security: Setting allowWeakSecret=true bypasses RFC 7518 security requirements.
+// Only use this for testing with non-production data.
 func NewHS256EncoderWithOptions(secret []byte, allowWeakSecret bool) EncoderDecoder {
 	return NewHS256EncoderWithValidation(secret, allowWeakSecret, ValidationOptions{})
 }
 
 // NewHS256EncoderWithValidation creates a new HMAC-SHA256 JWT encoder/decoder with validation options.
+//
+// Parameters:
+//   - secret: The shared secret key (minimum 32 bytes recommended)
+//   - allowWeakSecret: If true, allows secrets shorter than 32 bytes (TESTING ONLY)
+//   - validationOpts: Options for validating JWT claims (exp, nbf, iat)
+//
+// Note: By default, time-based claims (exp, nbf, iat) are NOT validated.
+// Set validationOpts.ValidateClaims=true to enable automatic expiration checking.
 func NewHS256EncoderWithValidation(secret []byte, allowWeakSecret bool, validationOpts ValidationOptions) EncoderDecoder {
 	return &hsjwtEncoderDecoder{
 		method:          jwt.SigningMethodHS256,
@@ -67,6 +97,10 @@ func NewHS256DecoderWithValidation(secret []byte, allowWeakSecret bool, validati
 }
 
 // NewHS384Encoder creates a new HMAC-SHA384 JWT encoder/decoder.
+//
+// Security: The secret should be at least 384 bits (48 bytes) for HS384.
+// Weak secrets are vulnerable to brute-force attacks. By default, this function
+// enforces minimum secret length according to RFC 7518.
 func NewHS384Encoder(secret []byte) EncoderDecoder {
 	return NewHS384EncoderWithOptions(secret, false)
 }
@@ -103,6 +137,10 @@ func NewHS384DecoderWithValidation(secret []byte, allowWeakSecret bool, validati
 }
 
 // NewHS512Encoder creates a new HMAC-SHA512 JWT encoder/decoder.
+//
+// Security: The secret should be at least 512 bits (64 bytes) for HS512.
+// Weak secrets are vulnerable to brute-force attacks. By default, this function
+// enforces minimum secret length according to RFC 7518.
 func NewHS512Encoder(secret []byte) EncoderDecoder {
 	return NewHS512EncoderWithOptions(secret, false)
 }
@@ -138,6 +176,17 @@ func NewHS512DecoderWithValidation(secret []byte, allowWeakSecret bool, validati
 	return NewHS512EncoderWithValidation(secret, allowWeakSecret, validationOpts)
 }
 
+// Decode validates and decodes a JWT token using HMAC algorithm.
+//
+// Security: This function validates that the token's algorithm matches the expected
+// HMAC algorithm to prevent algorithm confusion attacks. Tokens signed with different
+// algorithms will be rejected.
+//
+// Note: By default, time-based claims (exp, nbf, iat) are NOT validated. Use
+// NewHS*EncoderWithValidation with ValidationOptions.ValidateClaims=true to enable
+// automatic expiration checking.
+//
+// Returns: JSON string representation of the token's claims, or an error if validation fails.
 func (j *hsjwtEncoderDecoder) Decode(token string) (string, error) {
 	if !j.allowWeakSecret {
 		if err := j.validateSecret(); err != nil {
@@ -147,6 +196,19 @@ func (j *hsjwtEncoderDecoder) Decode(token string) (string, error) {
 	return j.decoder.DecodeJWT(j.secret, token)
 }
 
+// Encode creates and signs a JWT token using HMAC algorithm.
+//
+// The payload must be a valid JSON string that can be unmarshaled into jwt.MapClaims.
+//
+// Security: The returned token is signed but NOT encrypted. Do not include sensitive
+// data (passwords, API keys, PII) in the payload as it can be decoded by anyone.
+// Always transmit JWT tokens over HTTPS.
+//
+// Example payload:
+//
+//	`{"user_id":"12345","role":"admin","exp":1735689600}`
+//
+// Returns: Base64-encoded JWT token (header.payload.signature) or an error if signing fails.
 func (j *hsjwtEncoderDecoder) Encode(payload string) (string, error) {
 	if !j.allowWeakSecret {
 		if err := j.validateSecret(); err != nil {

pkg/cryptojwt/rsjwt.go

@@ -39,6 +39,21 @@ type rsjwtDecoderWithCachedPublicKey struct {
 }
 
 // NewRS256Encoder creates a new RSA-SHA256 JWT encoder with a private key file.
+//
+// Parameters:
+//   - privateKeyFile: Path to PEM-encoded RSA private key file
+//
+// Security: Private key files should be protected with strict file permissions (0600).
+// Never commit private keys to version control or expose them in logs. Consider using
+// environment variables or secure key management systems for production deployments.
+//
+// Example:
+//
+//	encoder := cryptojwt.NewRS256Encoder("private.pem")
+//	token, err := encoder.Encode(`{"user":"alice","exp":1735689600}`)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
 func NewRS256Encoder(privateKeyFile string) Encoder {
 	return &rsjwtEncoderWithPrivateKeyFile{
 		method:         jwt.SigningMethodRS256,
@@ -61,6 +76,22 @@ func NewRS256DecoderWithPrivateKeyFileAndValidation(privateKeyFile string, valid
 }
 
 // NewRS256DecoderWithPublicKeyFile creates a new RSA-SHA256 JWT decoder with a public key file.
+//
+// Parameters:
+//   - publicKeyFile: Path to PEM-encoded RSA public key file
+//
+// Note: Public keys can be safely distributed and do not require special protection,
+// unlike private keys. However, ensure you obtain public keys from trusted sources to
+// prevent man-in-the-middle attacks.
+//
+// Example:
+//
+//	decoder := cryptojwt.NewRS256DecoderWithPublicKeyFile("public.pem")
+//	claims, err := decoder.Decode(token)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	fmt.Println(claims) // {"user":"alice","exp":1735689600}
 func NewRS256DecoderWithPublicKeyFile(publicKeyFile string) Decoder {
 	return NewRS256DecoderWithPublicKeyFileAndValidation(publicKeyFile, ValidationOptions{})
 }
@@ -75,7 +106,29 @@ func NewRS256DecoderWithPublicKeyFileAndValidation(publicKeyFile string, validat
 }
 
 // NewRS256EncoderWithCache creates a new RSA-SHA256 JWT encoder with cached private key.
-// The private key is loaded once at creation time, improving performance for repeated operations.
+//
+// The private key is loaded once at creation time, improving performance for repeated
+// operations. This is recommended for high-throughput scenarios where you need to encode
+// many tokens without repeated file I/O.
+//
+// Security: The cached key remains in memory for the lifetime of the encoder. Ensure
+// proper memory protection in production environments. Private key files should have
+// strict file permissions (0600).
+//
+// Performance: For applications encoding thousands of tokens, this can provide significant
+// performance improvements by eliminating repeated file reads and key parsing.
+//
+// Example:
+//
+//	encoder, err := cryptojwt.NewRS256EncoderWithCache("private.pem")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	// Encode many tokens efficiently
+//	for i := 0; i < 1000; i++ {
+//	    token, _ := encoder.Encode(fmt.Sprintf(`{"id":%d}`, i))
+//	    fmt.Println(token)
+//	}
 func NewRS256EncoderWithCache(privateKeyFile string) (Encoder, error) {
 	privateKey, _, err := readPrivateRSAKey(privateKeyFile)
 	if err != nil {