jwt

Overview ¶

Package jwt implements JWT (JSON Web Token) authentication for Aegis.

This plugin provides stateless token-based authentication using industry-standard JWT tokens with RSA signing. Features include:

• Token Generation: Access tokens (15min) and refresh tokens (7d)
• RSA Signing: RS256 algorithm with database-backed key storage
• Key Rotation: Automatic key rotation with configurable intervals
• JWKS Endpoint: Public key discovery for token verification
• Token Blacklist: Redis-backed token revocation
• Refresh Flow: Secure token refresh without re-authentication

JWT vs Session Tokens:

Session Tokens (core):
  - Stateful: Requires database lookup on every request
  - Revocable: Can be deleted from database immediately
  - Simple: Just random strings, no cryptography

JWT Tokens (this plugin):
  - Stateless: Can be verified without database (using public key)
  - Self-contained: Includes user ID and expiry in token
  - Distributed: Multiple services can verify without shared database
  - Revocation: Requires blacklist (Redis) for immediate revocation

Architecture:

Token Pair:
  - Access Token: Short-lived (15min), used for API requests
  - Refresh Token: Long-lived (7d), used to get new access tokens

Key Storage:
  - Private keys: Stored in database, used for signing
  - Public keys: Exposed via /jwt/.well-known/jwks.json (JWKS endpoint)
  - Key rotation: Old keys retained for token verification

Token Flow:
  1. User authenticates (email/password, OAuth, etc.)
  2. POST /jwt/token → Get access + refresh token
  3. Use access token in Authorization header
  4. When access token expires, POST /jwt/refreshToken with refresh token
  5. Get new access + refresh token pair

Use Cases:

• Microservices: Stateless authentication across services
• Mobile apps: Long-lived refresh tokens
• SPAs: JavaScript apps with token storage
• Third-party integrations: Standard JWT format

Security Considerations:

• Access tokens are short-lived (minimize exposure window)
• Refresh tokens are long-lived (balance UX vs security)
• Token blacklist requires Redis (for logout/revocation)
• HTTPS is REQUIRED (tokens are bearer credentials)
• Store tokens securely (httpOnly cookies, secure storage, not localStorage)

Example:

package main

import (
	"context"
	"github.com/theinventorylib/aegis"
	"github.com/theinventorylib/aegis/plugins/jwt"
)

func main() {
	a, _ := aegis.New(context.Background(), ...)

	// Configure JWT plugin
	jwtConfig := &jwt.Config{
		Issuer:              "myapp",
		AccessTokenExpiry:   15 * time.Minute,
		RefreshTokenExpiry:  7 * 24 * time.Hour,
		KeyRotationInterval: 24 * time.Hour,
	}

	// Register JWT plugin
	a.Use(context.Background(), jwt.New(jwtConfig, nil, plugins.DialectPostgres))

	a.MountRoutes("/auth")
	// Routes available:
	// POST /auth/jwt/token
	// POST /auth/jwt/getAccessToken
	// POST /auth/jwt/refreshToken
	// POST /auth/jwt/logout
	// GET  /auth/jwt/.well-known/jwks.json
}

Package jwt provides database migration management for the JWT plugin.

This file handles parsing and loading migration files from the embedded filesystem, supporting multiple SQL dialects (PostgreSQL, MySQL, SQLite).

Migration Versioning:

• Version 001+: Migrations from migrations/<dialect>/<version>_<description>.<up|down>.sql

File Naming Convention:

• Up migrations: 001_initial.up.sql
• Down migrations: 001_initial.down.sql

Directory Structure:

jwt/
  migrations/
    postgres/
      002_altered.up.sql
      002_altered.down.sql
    mysql/
      002_altered.up.sql
      002_altered.down.sql

The migration system ensures the correct schema version is applied for each SQL dialect, supporting forward (up) and backward (down) migrations.