### Install JWT for Nim Library

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Instructions for installing the JWT for Nim library using the nimble package manager. This is a prerequisite for running any of the provided JWT examples.

```bash
# Install JWT library
nimble install jwt
```

--------------------------------

### Install Nim and JWT Library (Bash)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

This snippet shows how to install a specific version of Nim and check if the JWT library is installed using nimble. It's useful for setting up the development environment.

```bash
# Ensure Nim 2.2.0+ is installed
choosenim install 2.2.0

# Check JWT library installation
nimble list jwt
```

--------------------------------

### Run All Nim JWT Examples

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Provides a sequence of commands to compile and run all the JWT examples included in the project. This allows for a comprehensive test of the library's capabilities.

```bash
# Basic example
nim c -r examples/basic_jwt.nim && echo ""

# RSA example
nim c -r examples/rsa_jwt.nim && echo ""

# Web API example
nim c -r examples/web_api_auth.nim && echo ""

# Security example
nim c -r examples/security_best_practices.nim
```

--------------------------------

### Compile and Run Nim JWT Examples

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Demonstrates how to compile and run a specific JWT example file using the Nim compiler. This is the standard method for executing the provided code snippets.

```bash
nim c -r examples/basic_jwt.nim
```

--------------------------------

### Run JWT Examples in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/README.md

Commands to compile and run the example JWT applications provided in the nim-jwt library. These examples cover basic usage, RSA signatures, and web API authentication scenarios.

```bash
nim c -r examples/basic_jwt.nim
nim c -r examples/web_api_auth.nim
```

--------------------------------

### Set Nim Version

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Command to install a specific version of Nim (2.2.0 or later) using the choosenim tool, ensuring compatibility with the JWT for Nim library.

```bash
# Ensure Nim 2.2.0+
choosenim install 2.2.0
```

--------------------------------

### Install JWT Library via Nimble

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/README.md

Installs the nim-jwt library using the Nimble package manager. Ensure you have Nim 2.0.0 or later and the BearSSL library installed.

```bash
nimble install jwt
```

--------------------------------

### Basic JWT Creation and Verification in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Demonstrates the fundamental JWT functionality in Nim, including creating tokens with custom claims, signing them using HMAC, and verifying their integrity. This example is useful for understanding the core operations of the JWT library.

```nim
import jwt
import times

let secretKey = "your-super-secret-key"

# Create claims
var claims = newClaims()
claims["sub"] = newStringClaim("1234567890")
claims["name"] = newStringClaim("John Doe")
claims["iat"] = newTimeClaim(getTime())
claims["exp"] = newTimeClaim(getTime() + 1.hours)

# Create token
let token = createToken(secretKey, HS256, claims)
echo "Token created: ", token

# Verify token
let verificationResult = verifyToken(token, secretKey)

echo "Token valid: ", verificationResult.isValid

if verificationResult.isValid:
  echo "Subject: ", verificationResult.claims.get("sub")
  echo "Name: ", verificationResult.claims.get("name")
  echo "Expires: ", verificationResult.claims.get("exp", "N/A")
else:
  echo "Token verification failed."
```

--------------------------------

### Build JWT Library from Source

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/README.md

Clones the nim-jwt repository and installs it locally using Nimble. This method is useful for development or when using the latest unreleased features.

```bash
git clone https://github.com/yglukhov/nim-jwt.git
cd nim-jwt
nimble install -y
```

--------------------------------

### Recommended Build Configuration (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Suggests compiler options for enhanced security and optimization when building projects that use the jwt-nim library. These are recommended for production environments.

```nim
# In your project's .nimble file or build script
# Enable security-focused compiler options
# --checks:on --warnings:on

# For production
# -d:release --opt:size
```

--------------------------------

### Nim: Configure Secure Key Sizes

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Provides examples for configuring secure key sizes for HMAC and RSA algorithms in Nim. For HMAC, a minimum of 32 bytes is recommended, and for RSA, a minimum of 2048 bits is required.

```nim
# HMAC: minimum 32 bytes
let hmacKey = "your-32-byte-secret-key-here-1234567890"  # 44+ characters

# RSA: minimum 2048 bits
# Generate with: openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
```

--------------------------------

### RSA Signed JWT with PEM Keys in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Illustrates how to use RSA for signing and verifying JWTs in Nim, utilizing PEM formatted public and private keys. This example highlights the use of key identifiers for managing key rotation and emphasizes algorithm security.

```nim
import jwt
import times

# Assume publicKey.pem and privateKey.pem are available
let publicKey = readFile("publicKey.pem")
let privateKey = readFile("privateKey.pem")

var claims = newClaims()
claims["sub"] = newStringClaim("user123")
claims["iat"] = newTimeClaim(getTime())
claims["exp"] = newTimeClaim(getTime() + 1.hours)

# Create token with RSA private key
let token = createToken(privateKey, RS256, claims)
echo "RSA Signed Token: ", token

# Verify token with RSA public key
let verificationResult = verifyToken(token, publicKey)

echo "Token valid: ", verificationResult.isValid

if verificationResult.isValid:
  echo "Subject: ", verificationResult.claims.get("sub")
else:
  echo "Token verification failed."
```

--------------------------------

### Change JWT Algorithm in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Illustrates how to change the signing algorithm for a JWT in Nim. This example shows replacing HS256 with RS384, demonstrating flexibility in algorithm selection.

```nim
# In any example, change the algorithm
let algorithm = RS384  # Instead of HS256
```

--------------------------------

### Bash: Update BearSSL Dependency

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Shows the bash commands to refresh Nimble package dependencies and install the latest version of the BearSSL library, which may be necessary for resolving dependency conflicts.

```bash
# Update to latest BearSSL
nimble refresh
nimble install bearssl@#head
```

--------------------------------

### Nim: Set Appropriate Expiration Times for Tokens

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Provides examples in Nim for setting appropriate expiration times for JWTs, differentiating between short-lived access tokens and longer-lived refresh tokens for better security and performance.

```nim
# Short tokens for better security and performance
claims["exp"] = newTimeClaim(getTime() + 15.minutes)  # Access token
claims["exp"] = newTimeClaim(getTime() + 7.days)      # Refresh token
```

--------------------------------

### Authorization Header Example (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

Shows the standard 'Authorization' header format using a Bearer token. It also highlights the security risk of transmitting tokens via query parameters.

```nim
# Standard Authorization header format
let headers = newHttpHeaders({
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
})

# Never use query parameters for sensitive tokens
# BAD: /api/users?token=eyJhbGciOiJIUzI1NiIs..."
```

--------------------------------

### Create JWT Token (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Demonstrates how to create a basic JWT token with header and claims using the jwt library. This function is backward compatible between v0.x and v2.0.

```nim
import jwt, json, tables

var token = toJWT(%*{
  "header": {"alg": "HS256", "typ": "JWT"},
  "claims": {"sub": "1234567890", "name": "John Doe"}
})

token.sign("secret")
echo $token
```

--------------------------------

### Web API Authentication with JWT in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Simulates a realistic web API authentication flow in Nim, including user login, access and refresh token generation, and protecting API endpoints. This example demonstrates how to manage user sessions and token lifecycles in a web context.

```nim
import jwt
import times

let secretKey = "your-api-secret-key"

proc login(username, password): (string, string) = 
  # In a real app, verify username and password against a database
  if username == "admin" and password == "password":
    var accessTokenClaims = newClaims()
    accessTokenClaims["sub"] = newStringClaim("1")
    accessTokenClaims["username"] = newStringClaim(username)
    accessTokenClaims["exp"] = newTimeClaim(getTime() + 15.minutes)
    let accessToken = createToken(secretKey, HS256, accessTokenClaims)

    var refreshTokenClaims = newClaims()
    refreshTokenClaims["sub"] = newStringClaim("1")
    refreshTokenClaims["type"] = newStringClaim("refresh")
    refreshTokenClaims["exp"] = newTimeClaim(getTime() + 24.hours)
    let refreshToken = createToken(secretKey, HS256, refreshTokenClaims)

    return (accessToken, refreshToken)
  else:
    raise newException(ValueError, "Invalid credentials")

proc protectedApiCall(token): Claims = 
  let verificationResult = verifyToken(token, secretKey)
  if verificationResult.isValid:
    return verificationResult.claims
  else:
    raise newException(ValueError, "Unauthorized")

# Example Usage
try:
  let (accessToken, refreshToken) = login("admin", "password")
  echo "Access Token: ", accessToken
  echo "Refresh Token: ", refreshToken

  let userClaims = protectedApiCall(accessToken)
  echo "User ID: ", userClaims.get("sub")
  echo "Username: ", userClaims.get("username")
  echo "API call successful!"
except ValueError as e:
  echo "Error: ", e.msg
```

--------------------------------

### RSA Signing and Verification with Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Demonstrates how to sign a JWT using an RSA private key and verify it with a public key in Nim. Requires the privateKeyPem and publicKeyPem variables to be defined.

```nim
# RS256 usage
let header = %*{"alg": "RS256", "typ": "JWT", "kid": "rsa-2048-001"}
var token = initJWT(header, claims)
token.sign(privateKeyPem)

# Verification with public key
let isValid = token.verify(publicKeyPem, RS256)
```

--------------------------------

### JWT Security Best Practices in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Explores advanced security features and patterns for JWTs in Nim, including secure key generation, token blacklisting for replay protection, and key rotation. This example demonstrates comprehensive security validation and attack scenario simulations.

```nim
import jwt
import times
import strutils

# Secure key generation (example)
let secretKey = generateRandomKey(32) # 32 bytes for HS256
echo "Generated secure HMAC key: ", secretKey

# Token blacklisting (conceptual - requires external storage like Redis or DB)
var blacklistedTokens = newHashSet[string]()

proc createSecureToken(key: string, algorithm: Algorithm, claims: Claims, issuer: string, audience: string, keyId: string): string = 
  var tokenClaims = claims
  tokenClaims["iss"] = newStringClaim(issuer)
  tokenClaims["aud"] = newStringClaim(audience)
  tokenClaims["jti"] = newStringClaim(newUUID().str)
  tokenClaims["iat"] = newTimeClaim(getTime())
  tokenClaims["exp"] = newTimeClaim(getTime() + 1.hours)
  
  return createToken(key, algorithm, tokenClaims, keyId=keyId)

proc verifySecureToken(token: string, key: string, expectedAudience: string): VerificationResult = 
  if blacklistedTokens.contains(token):
    return VerificationResult(isValid: false, error: "Token is blacklisted")
  
  let result = verifyToken(token, key)
  if result.isValid and result.claims.get("aud") == expectedAudience:
    return result
  else:
    return VerificationResult(isValid: false, error: "Verification failed")

# Example Usage
let issuer = "your-secure-app.com"
let audience = "api.example.com"
let keyId = "key-2023-12-001"

var claims = newClaims()
claims["sub"] = newStringClaim("user-123")

let token = createSecureToken(secretKey, HS256, claims, issuer, audience, keyId)
echo "Created valid token: ", token

let verificationResult = verifySecureToken(token, secretKey, audience)

echo "Token validation successful for user: ", verificationResult.claims.get("sub")
echo "  Algorithm: ", verificationResult.claims.get("alg")
echo "  Audience: ", verificationResult.claims.get("aud")
echo "  Key ID: ", verificationResult.claims.get("kid")
echo "  JWT ID: ", verificationResult.claims.get("jti")

echo "Verification result: ", verificationResult.isValid

# Simulate replay attack
blacklistedTokens.incl(token)
let replayResult = verifySecureToken(token, secretKey, audience)

echo "Replay attempt result: ", replayResult.isValid
if not replayResult.isValid:
  echo "Security Alert: Token replay detected"
```

--------------------------------

### ECDSA Signing and Verification with Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Shows how to sign a JWT using an ECDSA private key and verify it with the corresponding public key in Nim. Optimized for performance-critical scenarios.

```nim
# ES256 usage for performance-critical applications
let header = %*{"alg": "ES256", "typ": "JWT", "kid": "ec-p256-001"}
var token = initJWT(header, claims)
token.sign(ecPrivateKeyPem)

# Verification
let isValid = token.verify(ecPublicKeyPem, ES256)
```

--------------------------------

### Token Blacklisting Implementation (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

A Nim example demonstrating a basic token blacklisting mechanism using a HashSet to store used token IDs (jti) and their expiry times. This helps prevent replay attacks.

```nim
type
  TokenBlacklist = object
    usedTokens: HashSet[string]
    expiry: Time

proc addToBlacklist(blacklist: var TokenBlacklist, jti: string, exp: Time) = 
  blacklist.usedTokens.incl(jti)
  # Clean up expired entries periodically
```

--------------------------------

### Session Storage Example (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

A Nim object definition for server-side session storage, linking session data to a JWT ID (jti). This approach centralizes session management and can improve security.

```nim
# Store minimal session data server-side
type
  Session = object
    userId: string
    createdAt: Time
    lastActivity: Time
    jti: string  # Link to JWT ID
```

--------------------------------

### Nim: Optimize Algorithm Selection for Performance

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Recommends algorithm choices for JWTs in Nim based on performance. ES256 is suggested as faster than RSA, and HS256 is the fastest for symmetric keys.

```nim
# For high-performance scenarios
let algorithm = ES256  # Faster than RSA
# or
let algorithm = HS256  # Fastest for symmetric keys
```

--------------------------------

### Generate HMAC Key using OpenSSL (Bash)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Demonstrates how to generate HMAC keys of different sizes (256-bit and 384-bit) using the OpenSSL command-line tool. The output is in hexadecimal format.

```bash
# Generate 32-byte (256-bit) key
openssl rand -hex 32

# Generate 48-byte (384-bit) key  
openssl rand -hex 48
```

--------------------------------

### Test Basic JWT Functionality (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Nim code snippets for testing basic JWT token creation and verification. These tests ensure the core functionality works as expected after migration.

```nim
# Test basic token creation
test "basic token creation":
  var token = toJWT(testData)
  token.sign(testSecret)
  check $token != ""

test "basic token verification":
  let token = tokenString.toJWT()
  check token.verify(testSecret, HS256)
```

--------------------------------

### Generate RSA Private Key (Bash)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Generates a 3072-bit RSA private key using OpenSSL. This key is used for signing JWTs with RSA-based algorithms.

```bash
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:3072
```

--------------------------------

### Verify JWT Token (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Shows how to verify a JWT token using a secret key and algorithm. Version 2.0 includes enhanced security checks during verification.

```nim
let token = tokenString.toJWT()
let isValid = token.verify("secret", HS256)
```

--------------------------------

### Benchmark JWT Token Verification (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

A Nim procedure to benchmark the performance of JWT token verification. This helps in measuring the performance impact of the library's security enhancements.

```nim
import times

proc benchmarkVerification(iterations: int) =
  let start = cpuTime()
  
  for i in 0..<iterations:
    let token = tokenString.toJWT()
    discard token.verify(secret, HS256)
  
  let elapsed = cpuTime() - start
  echo "Verified $1 tokens in $2 seconds" % [$iterations, $elapsed]
  echo "Average: $1 ms per token" % [$(elapsed * 1000.0 / iterations)]
```

--------------------------------

### Nim: Update Algorithm from 'none' to HS256

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Demonstrates how to update JWT header algorithms from the insecure 'none' to a secure algorithm like 'HS256'. This is a common migration step to address security vulnerabilities.

```nim
let header = %*{"alg": "HS256", "typ": "JWT"}
```

--------------------------------

### Generate 64-byte HMAC Key

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Generates a 64-byte (512-bit) random key suitable for HMAC algorithms. This command uses OpenSSL to produce a hexadecimal string representation of the key.

```bash
openssl rand -hex 64
```

--------------------------------

### Select JWT Algorithm for Public Web APIs (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Demonstrates how to select the RS256 algorithm for public-facing web APIs, offering a balance between security and performance. It also suggests ES256 as a performant alternative.

```nim
# Recommended: RS256 for good balance
let algorithm = RS256  # 2048-bit keys

# Alternative: ES256 for better performance
let algorithm = ES256  # P-256 curve
```

--------------------------------

### Set JWT Expiration Claims (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/API.md

Provides examples of setting expiration times for JWT claims using Nim. It shows how to set reasonable expiration durations for access and refresh tokens.

```nim
# Set reasonable expiration times
claims["exp"] = newTimeClaim(getTime() + 15.minutes)  # Access tokens
claims["exp"] = newTimeClaim(getTime() + 7.days)      # Refresh tokens
```

--------------------------------

### Benchmark JWT Signing and Verification (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Benchmarks the performance of JWT signing and verification process for a given algorithm over a specified number of iterations. It measures the CPU time taken for the operations.

```nim
# Benchmark procedure
proc benchmarkAlgorithm(algorithm: SignatureAlgorithm, iterations: int): float =
  let start = cpuTime()
  
  for i in 0..<iterations:
    var token = initJWT(testHeader, testClaims)
    token.sign(testSecret)
    discard token.verify(testSecret, algorithm)
  
  result = cpuTime() - start
```

--------------------------------

### HS256 HMAC Signing and Verification in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Demonstrates basic HS256 (HMAC using SHA-256) signing and verification for JWTs. Requires a 32-byte secret key. Suitable for high-throughput scenarios.

```nim
import jwt

let header = %*{"alg": "HS256", "typ": "JWT"}
var token = initJWT(header, claims)
token.sign("your-32-byte-secret-key-here-1234567890")

# Verification
let isValid = token.verify("your-32-byte-secret-key-here-1234567890", HS256)
```

--------------------------------

### Nim: Optimize Token Claims for Size

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Suggests optimizing JWT token claims in Nim by using short claim keys to reduce token size and improve performance. Standard claims are noted as being optimized.

```nim
# Use short claim keys
claims["uid"] = newStringClaim(userId)    # Instead of "userId"
claims["exp"] = newTimeClaim(expires)     # Standard claims are optimized
```

--------------------------------

### RSA Private Key Generation using OpenSSL

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Generates a 2048-bit RSA private key using OpenSSL. This key is used for signing JWTs with RSA algorithms. The corresponding public key can be extracted for verification.

```bash
# Generate 2048-bit RSA private key openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Extract public key openssl rsa -pubout -in private_key.pem -out public_key.pem
```

--------------------------------

### Custom JWT Security Validation (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Provides examples of custom security validation for JWTs. Version 2.0 includes automatic validation for algorithms like 'none' and allows for additional custom checks.

```nim
# Automatic security validation
# Library handles 'none' algorithm rejection
# Additional custom validation can be added:

if not isSecureAlgorithm(token.header.alg):
  raise SecurityError("Insecure algorithm")

let hashStrength = getHashStrength(token.header.alg)
if hashStrength < 256:
  echo "Warning: Using weak hash algorithm"
```

--------------------------------

### Basic JWT Creation and Verification in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/README.md

Demonstrates the fundamental usage of the nim-jwt library to create, sign, and verify a JWT. It includes setting up headers, claims, and signing with a shared secret.

```nim
import jwt, json, times, tables

# Create token header and claims
let header = %*{"alg": "HS256", "typ": "JWT"}

var claims = newTable[string, Claim]()
claims["sub"] = newStringClaim("1234567890")
claims["name"] = newStringClaim("John Doe")
claims["iat"] = newTimeClaim(getTime())
claims["exp"] = newTimeClaim(getTime() + 1.hours)

# Initialize and sign token
var token = initJWT(header, claims)
token.sign("your-256-bit-secret")

echo "JWT Token: ", $token

# Verify token
let isValid = token.verify("your-256-bit-secret", HS256)
echo "Token valid: ", isValid
```

--------------------------------

### Update Nim Version Requirement

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

JWT for Nim v2.0 requires Nim version 2.2.0 or later, a change from v0.x's requirement of 0.19.0. Users must update their Nim installation to meet this new requirement.

```bash
# Update Nim to 2.2.0 or later
choosenim update self
choosenim install 2.2.0
```

--------------------------------

### Modify JWT Claims in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Shows how to add custom claims to a JWT payload in Nim. This example includes adding 'department', 'role', and 'permissions' claims to the token.

```nim
# Add custom claims to any example
claims["department"] = newStringClaim("engineering")
claims["role"] = newStringClaim("admin")
claims["permissions"] = newStringClaim("read:users write:users")
```

--------------------------------

### Create JWT Token with initJWT

Source: https://context7.com/katehonz/jwt-nim-baraba/llms.txt

Initializes a new JWT token with a specified header and claims. The header must include 'alg' and 'typ', while claims can contain standard JWT fields and custom data. The token is unsigned at this stage.

```nim
import jwt, json, times, tables

# Create JWT header specifying algorithm and type
let header = %*{
  "alg": "HS256",
  "typ": "JWT"
}

# Create claims table with standard and custom claims
var claims = newTable[string, Claim]()
claims["iss"] = newStringClaim("your-auth-server.com")
claims["sub"] = newStringClaim("user-12345")
claims["name"] = newStringClaim("John Doe")
claims["iat"] = newTimeClaim(getTime())
claims["exp"] = newTimeClaim(getTime() + 1.hours)
claims["jti"] = newStringClaim("unique-token-id-001")

# Initialize JWT token (unsigned)
var token = initJWT(header, claims)
echo "Token created (unsigned): ", token.header
# Output: Token created (unsigned): {"alg":"HS256","typ":"JWT"}
```

--------------------------------

### Adjust JWT Expiration Times in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/examples/README.md

Demonstrates how to modify the expiration times (exp claim) for JWTs in Nim. This example shows setting both shorter and longer token lifetimes.

```nim
# Change token lifetimes
claims["exp"] = newTimeClaim(getTime() + 5.minutes)  # Shorter
claims["exp"] = newTimeClaim(getTime() + 24.hours)  # Longer
```

--------------------------------

### JWT Algorithm Security Information in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/README.md

Demonstrates how to check the security status of JWT algorithms and retrieve hash strength information using the nim-jwt library. This helps in selecting appropriate and secure algorithms for token signing.

```nim
# Check algorithm security
assert isSecureAlgorithm(HS256) == true
assert isSecureAlgorithm(NONE) == false

# Get hash strength information
let bits = getHashStrength(RS256)  # Returns: 256
```

--------------------------------

### Select JWT Algorithm for Banking/Financial (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Recommends RS384 or ES384 for banking and financial applications, emphasizing the need for high security in these sensitive domains.

```nim
# Recommended: RS384 or ES384
let algorithm = RS384  # 3072-bit RSA
# or
let algorithm = ES384  # P-384 curve
```

--------------------------------

### Create JWT Claims and Token

Source: https://context7.com/katehonz/jwt-nim-baraba/llms.txt

Demonstrates creating JWT tokens with various claim types including strings, integers, booleans, and time-based claims. It also shows how to set standard claims like issuer, subject, audience, and expiration.

```nim
import jwt, json, times, tables

var claims = newTable[string, Claim]()

# String claims
claims["sub"] = newStringClaim("user-12345")
claims["iss"] = newStringClaim("auth.example.com")
claims["username"] = newStringClaim("johndoe")

# Integer claims
claims["level"] = newIntClaim(5)

# Boolean claims
claims["admin"] = newBoolClaim(true)

# Time claims (automatically converts to Unix timestamp)
claims["iat"] = newTimeClaim(getTime())
claims["exp"] = newTimeClaim(getTime() + 15.minutes)
claims["nbf"] = newTimeClaim(getTime() - 30.seconds)  # Valid from 30 seconds ago

# Audience claim (supports single string or array)
claims["aud"] = newAUD("api.example.com")
# Or for multiple audiences: newAUD("api.example.com", "web.example.com")

# JWT ID for replay protection
claims["jti"] = newStringClaim("unique-token-id-" & $epochTime())

let header = %*{"alg": "HS256", "typ": "JWT"}
var token = initJWT(header, claims)
token.sign("your-secret-key-minimum-32-bytes-long")
echo $token
```

--------------------------------

### Nim: Implement JWT Key Rotation Strategy

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Demonstrates a key rotation strategy in Nim for JWTs, using key identifiers (kid) in the token header. It shows how to support multiple keys during rotation and verify tokens against the appropriate public key.

```nim
# Implement key identifiers
let oldKeyId = "key-2023-01"
let newKeyId = "key-2023-12"

# Create headers with key IDs
let header = %*{
  "alg": "RS256",
  "typ": "JWT", 
  "kid": newKeyId
}

# Support multiple keys during rotation
proc verifyWithRotation(token: JWT): bool =
  let keyId = token.header{"kid"}.getStr("")
  let publicKey = getPublicKey(keyId)
  result = token.verify(publicKey, RS256)
```

--------------------------------

### Generate RSA Key with Specific Public Exponent and Certificate

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Demonstrates advanced RSA key generation, including specifying a public exponent (e.g., 65537) and creating a self-signed certificate for the key. This is useful for key rotation and identity management.

```bash
# With specific public exponent
openssl genpkey -algorithm RSA -out rsa_private.pem -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537

# With certificate for key rotation
openssl req -new -x509 -key rsa_private.pem -out rsa_cert.pem -days 365
```

--------------------------------

### New Features: Hash Strength Information

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

The `getHashStrength()` function in JWT for Nim v2.0 returns the security strength in bits for a given hashing algorithm, such as HS256.

```nim
# v2.0 - Get hash strength
let bits = getHashStrength(HS256)  # Returns: 256
```

--------------------------------

### Select JWT Algorithm for Microservices (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

Illustrates choosing JWT algorithms for microservice communication in Nim. Suggests HS256 for internal services due to its efficiency and ES256 for performance-critical scenarios.

```nim
# Recommended: HS256 for internal service communication
let algorithm = HS256

# Alternative: ES256 for performance-critical services
let algorithm = ES256
```

--------------------------------

### JWT Creation and Verification with RSA Signature in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/README.md

Shows how to create and verify a JWT using RSA asymmetric cryptography. This involves loading private and public keys and signing with the private key, then verifying with the public key.

```nim
# RSA keys (in production, load from secure files)
let privateKey = readFile("private_key.pem")
let publicKey = readFile("public_key.pem")

let header = %*{"alg": "RS256", "typ": "JWT", "kid": "key-001"}

var claims = newTable[string, Claim]()
claims["iss"] = newStringClaim("your-auth-server.com")
claims["sub"] = newStringClaim("user-12345")
claims["exp"] = newTimeClaim(getTime() + 15.minutes)

var token = initJWT(header, claims)
token.sign(privateKey)

# Verify with public key
let isValid = token.verify(publicKey, RS256)
```

--------------------------------

### Test JWT Error Handling (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

Nim code for testing the exception handling mechanisms for JWT operations. This test verifies that the correct exceptions are raised for invalid tokens.

```nim
# Test new exception types
test "exception handling":
  try:
    let invalidToken = "invalid".toJWT()
    fail("Should have raised InvalidToken")
  except InvalidToken:
    check true
  except:
    fail("Wrong exception type")
```

--------------------------------

### Verify JWT with Key Rotation (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

Illustrates a Nim procedure for verifying JWTs using a key rotation strategy. It checks the 'kid' claim in the header to select the appropriate public key for verification.

```nim
# Support multiple keys during transition
proc verifyWithKeyRotation(token: JWT, tokenString: string): bool =
  let keyId = token.header{"kid"}.getStr("")
  
  case keyId:
  of "old-key-id":
    return token.verify(OLD_PUBLIC_KEY, RS256)
  of "new-key-id":
    return token.verify(NEW_PUBLIC_KEY, RS256)
  else:
    return false  # Unknown key
```

--------------------------------

### Include Relevant JWT Claims (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/API.md

Illustrates how to include standard and custom claims in a JWT using Nim. Examples include issuer (`iss`), audience (`aud`), subject (`sub`), and JWT ID (`jti`) for replay prevention.

```nim
claims["iss"] = newStringClaim("your-app")    # Issuer
claims["aud"] = newStringClaim("your-audience")  # Audience
claims["sub"] = newStringClaim("user-id")    # Subject
claims["jti"] = newStringClaim(generateUUID())  # JWT ID for replay prevention
```

--------------------------------

### RSA Key Format in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Defines constants for RSA private and public keys in PEM format, as expected by the Nim JWT library. These should be replaced with actual key material.

```nim
# PEM format expected by library
const rsaPrivateKey = """
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...
-----END PRIVATE KEY-----
"""

const rsaPublicKey = """
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv...
-----END PUBLIC KEY-----
"""
```

--------------------------------

### Improved Error Handling: SecurityError Exception

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/MIGRATION.md

JWT for Nim v2.0 introduces a dedicated `SecurityError` exception type for better categorization of security-related validation failures during token processing.

```nim
# v2.0 - Better error categorization
try:
  token.verify(secret, algorithm)
except InvalidToken:
  echo "Token format or claims invalid"
except UnsupportedAlgorithm:
  echo "Algorithm not supported"
except SecurityError:
  echo "Security validation failed"
```

--------------------------------

### Select JWT Algorithm for Web APIs (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

Demonstrates selecting appropriate JWT algorithms for web APIs using Nim. Recommends RS256 for standard APIs and ES256 for mobile applications, balancing security and performance.

```nim
# Recommended: RS256 for standard web APIs
let algorithm = RS256

# Alternative: ES256 for mobile apps
let algorithm = ES256
```

--------------------------------

### HS256 HMAC Key Generation in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Generates a secure, random 32-byte secret key for HS256 HMAC operations in Nim. Ensures adequate key length for security.

```nim
import random, strutils

proc generateHMACKey(): string =
  var bytes = newSeq[byte](32)
  for i in 0..<32:
    bytes[i] = byte(random(255))
  result = encodeUrlSafe(bytes)
```

--------------------------------

### Create JWT Token Object in Nim

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/API.md

Provides functions to initialize a JWT object from its components or parse it from a string representation. `initJWT` constructs a JWT from header, claims, and signature, while `toJWT` parses a JWT string or JSON node.

```nim
proc initJWT*(header: JsonNode, claims: TableRef[string, Claim], 
             signature: seq[byte] = @[]): JWT

# Example:
import jwt, json, tables

let header = %*{"alg": "HS256", "typ": "JWT"}
let claims = newTable[string, Claim]()
claims["sub"] = newStringClaim("1234567890")
claims["name"] = newStringClaim("John Doe")

let token = initJWT(header, claims)

proc toJWT*(s: string): JWT
proc toJWT*(node: JsonNode): JWT

# Example:
let jwtString = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature"
let token = jwtString.toJWT()
```

--------------------------------

### Generate P-384 ECDSA Key Pair

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Generates a private and public key pair for the P-384 elliptic curve using ECDSA. This offers a higher level of security compared to P-256.

```bash
# Generate P-384 private key
openssl ecparam -name secp384r1 -genkey -noout -out ec384_private.pem

# Extract public key
openssl ec -in ec384_private.pem -pubout -out ec384_public.pem
```

--------------------------------

### Generate P-256 ECDSA Key Pair

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Generates a private and public key pair for the P-256 elliptic curve using ECDSA. This is a common and efficient choice for digital signatures in JWTs.

```bash
# Generate P-256 private key
openssl ecparam -name prime256v1 -genkey -noout -out ec256_private.pem

# Extract public key
openssl ec -in ec256_private.pem -pubout -out ec256_public.pem
```

--------------------------------

### Optimize JWT Payload Claims (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Illustrates techniques for optimizing JWT token size by using short claim names and minimizing the data within the payload. It emphasizes using standard claim names and concise data representations.

```nim
# Use efficient algorithms for size-constrained environments
# 1. ES256 for mobile (small, fast)
# 2. HS256 for internal APIs (smallest, fastest)
# 3. RS256 only when needed (larger, slower)

# Optimize claim names
claims["uid"] = newStringClaim(userId)    # Instead of "userId"
claims["exp"] = newTimeClaim(expires)      # Standard claims are short

# Minimize payload
claims["data"] = newStringClaim(minimalData)  # Avoid large objects
```

--------------------------------

### Handle Common JWT Errors (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/API.md

Demonstrates how to handle common JWT errors using try-except blocks in Nim. Covers invalid token formats, unsupported algorithms, and security validation failures.

```nim
# Invalid token format
try:
  let token = "invalid-token".toJWT()
except InvalidToken:
  echo "Invalid token format"

# Unsupported algorithm
try:
  let token = %*{"alg": "unsupported", "typ": "JWT"}.toHeader()
except UnsupportedAlgorithm:
  echo "Algorithm not supported"

# Security validation failure
try:
  verifyTimeClaims(expiredToken)
except InvalidToken:
  echo "Token is expired"
```

--------------------------------

### Generate RSA Keys (Bash)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/SECURITY.md

Uses OpenSSL commands in Bash to generate RSA private and public keys. Supports key generation with specified bit lengths and extraction of the public key.

```bash
# Generate 2048-bit RSA private key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Extract public key
openssl rsa -pubout -in private_key.pem -out public_key.pem
```

--------------------------------

### Select JWT Algorithm for IoT Devices (Nim)

Source: https://github.com/katehonz/jwt-nim-baraba/blob/main/docs/CRYPTOGRAPHY.md

Recommends ES256 for IoT devices due to its small footprint and performance benefits. HS256 is an alternative if secure key sharing is feasible.

```nim
# Recommended: ES256 for small footprint
let algorithm = ES256  # P-256 curve

# Alternative: HS256 if key sharing is secure
let algorithm = HS256  # 32-byte secret
```