gourdiantoken

func (*GormTokenRepository) CleanupAll ¶ added in v1.0.6

func (r *GormTokenRepository) CleanupAll(ctx context.Context) error

CleanupAll removes all expired tokens (both revoked and rotated) in one operation. Convenience method for comprehensive maintenance.

Operation Sequence:

1. Cleanup expired access tokens
2. Cleanup expired refresh tokens
3. Cleanup expired rotated tokens

Error Handling:

• Continues with next cleanup if one fails
• Returns first error encountered
• Provides detailed error context for each operation

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• error: If any cleanup operation fails, with detailed context

Example (Comprehensive cleanup):

// Run full cleanup daily
err := repo.CleanupAll(ctx)
if err != nil {
    log.Printf("Comprehensive cleanup failed: %v", err)
} else {
    log.Println("All expired tokens cleaned up successfully")
}

func (*GormTokenRepository) CleanupExpiredRevokedTokens ¶ added in v1.0.6

func (r *GormTokenRepository) CleanupExpiredRevokedTokens(ctx context.Context, tokenType TokenType) error

CleanupExpiredRevokedTokens removes expired revoked tokens from the database. Batch DELETE operations are efficient and don't need explicit transactions.

Performance Characteristics:

• Single DELETE statement with WHERE clause
• Database handles deletion atomically
• Index on expires_at enables efficient range scans
• Batch operation minimizes database round trips

Maintenance Considerations:

• Run periodically to prevent table bloat
• Monitor deletion performance on large tables
• Consider time-based partitioning for very large datasets
• Schedule during low-traffic periods for production

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of tokens to cleanup (AccessToken or RefreshToken)

Returns:

• error: If token type is invalid or database operation fails

Database Operation:

DELETE FROM revoked_tokens
WHERE token_type = ? AND expires_at <= ?

Example (Scheduled cleanup):

// Run cleanup every hour
ticker := time.NewTicker(time.Hour)
defer ticker.Stop()

for range ticker.C {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    err := repo.CleanupExpiredRevokedTokens(ctx, AccessToken)
    cancel()
    if err != nil {
        log.Printf("Cleanup failed: %v", err)
    }
}

func (*GormTokenRepository) CleanupExpiredRotatedTokens ¶ added in v1.0.6

func (r *GormTokenRepository) CleanupExpiredRotatedTokens(ctx context.Context) error

CleanupExpiredRotatedTokens removes expired rotated tokens from the database. Efficient batch operation using TTL index on expires_at.

Performance Optimizations:

• Single DELETE statement for all expired rotated tokens
• Index on expires_at enables efficient range query
• Database handles atomic deletion
• Minimal locking for read-heavy workloads

Maintenance Scheduling:

• Run less frequently than revoked token cleanup
• Rotated tokens typically have longer TTL
• Consider running daily or weekly

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• error: If database operation fails

Database Operation:

DELETE FROM rotated_tokens
WHERE expires_at <= ?

Example (Weekly cleanup):

// Run cleanup once per week
go func() {
    for range time.Tick(7*24*time.Hour) {
        ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
        err := repo.CleanupExpiredRotatedTokens(ctx)
        cancel()
        if err != nil {
            log.Printf("Rotated token cleanup failed: %v", err)
        }
    }
}()

func (*GormTokenRepository) Close ¶ added in v1.0.6

func (r *GormTokenRepository) Close() error

Close performs cleanup operations and closes the database connection. Implements graceful shutdown pattern for resource cleanup.

Cleanup Actions:

• Closes underlying database connection pool
• Releases all database connections
• Prevents connection leaks during application shutdown

Important: This should be called during application shutdown to prevent database connection leaks and ensure graceful termination.

Returns:

• error: If closing the database connection fails

Example (Graceful shutdown):

// Setup signal handling
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

// Wait for shutdown signal
<-ctx.Done()

// Close repository during shutdown
if err := repo.Close(); err != nil {
    log.Printf("Failed to close token repository: %v", err)
}

func (*GormTokenRepository) GetRotationTTL ¶ added in v1.0.6

func (r *GormTokenRepository) GetRotationTTL(ctx context.Context, token string) (time.Duration, error)

GetRotationTTL returns the remaining TTL for a rotated token. Useful for debugging, monitoring, and cache optimization.

Use Cases:

• Debugging rotation-related issues
• Monitoring token rotation patterns
• Optimizing cleanup scheduling
• Understanding token lifecycle

Parameters:

• ctx: Context for cancellation and timeout
• token: The token to check for remaining TTL

Returns:

• time.Duration: Remaining TTL if token is rotated and not expired, 0 otherwise
• error: If token is empty or database operation fails

Database Query:

SELECT expires_at FROM rotated_tokens
WHERE token_hash = ?

Example (Monitor rotation TTL):

ttl, err := repo.GetRotationTTL(ctx, "rotated-token")
if err != nil {
    return fmt.Errorf("failed to get rotation TTL: %w", err)
}
if ttl > 0 {
    log.Printf("Token will be automatically cleaned up in %v", ttl)
}

func (*GormTokenRepository) IsTokenRevoked ¶ added in v1.0.6

func (r *GormTokenRepository) IsTokenRevoked(ctx context.Context, tokenType TokenType, token string) (bool, error)

IsTokenRevoked checks if a token has been revoked by checking its hash. Performs efficient database lookup using composite index.

Performance Optimizations:

• Uses composite index (token_hash, token_type) for fast lookups
• Additional filter on expires_at for automatic cleanup
• COUNT operation is optimized at database level
• Read-only operation with minimal locking

Security Considerations:

• Only compares token hashes, never the actual tokens
• Automatic expiration check prevents false positives
• Database-level validation ensures data integrity

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of token to check (AccessToken or RefreshToken)
• token: The token string to check for revocation

Returns:

• bool: True if token is revoked and not expired, false otherwise
• error: If token is empty, token type is invalid, or database operation fails

Database Query:

SELECT COUNT(*) FROM revoked_tokens
WHERE token_hash = ? AND token_type = ? AND expires_at > ?

Example (Check access token):

revoked, err := repo.IsTokenRevoked(ctx, AccessToken, "eyJhbGciOiJIUzI1NiIs...")
if err != nil {
    return fmt.Errorf("failed to check token revocation: %w", err)
}
if revoked {
    return errors.New("token has been revoked")
}

Example (Check refresh token):

revoked, err := repo.IsTokenRevoked(ctx, RefreshToken, "refresh-token-here")
if err != nil {
    return fmt.Errorf("failed to check refresh token: %w", err)
}

func (*GormTokenRepository) IsTokenRotated ¶ added in v1.0.6

func (r *GormTokenRepository) IsTokenRotated(ctx context.Context, token string) (bool, error)

IsTokenRotated checks if a token has been rotated by checking its hash. Performs efficient database lookup with automatic expiration filtering.

Security Purpose:

• Detects if a refresh token has been previously rotated
• Prevents reuse of rotated tokens in replay attacks
• Essential for rotation-based security schemes

Performance Optimizations:

• Uses unique index on token_hash for fast lookups
• Automatic expiration filtering at database level
• COUNT operation is database-optimized

Parameters:

• ctx: Context for cancellation and timeout
• token: The token to check for rotation status

Returns:

• bool: True if token has been rotated and not expired, false otherwise
• error: If token is empty or database operation fails

Database Query:

SELECT COUNT(*) FROM rotated_tokens
WHERE token_hash = ? AND expires_at > ?

Example (Check rotation status):

rotated, err := repo.IsTokenRotated(ctx, "suspect-refresh-token")
if err != nil {
    return fmt.Errorf("failed to check rotation: %w", err)
}
if rotated {
    return errors.New("token has been rotated - do not accept")
}

func (*GormTokenRepository) MarkTokenRevoke ¶ added in v1.0.6

func (r *GormTokenRepository) MarkTokenRevoke(ctx context.Context, tokenType TokenType, token string, ttl time.Duration) error

MarkTokenRevoke marks a token as revoked by storing its hash. Uses atomic UPSERT operation to handle concurrent revocation attempts.

Security Implementation:

• Token is hashed using SHA-256 before storage
• Composite unique key prevents duplicate entries
• TTL-based automatic expiration
• No actual tokens stored in database

Performance Characteristics:

• Single database write operation
• Atomic UPSERT prevents race conditions
• Composite index enables fast conflict detection
• No explicit transaction needed (UPSERT is atomic)

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of token (AccessToken or RefreshToken)
• token: The actual token string to revoke
• ttl: Time-to-live duration for the revocation record

Returns:

• error: If token is empty, TTL is invalid, token type is invalid, or database operation fails

Database Operation:

INSERT INTO revoked_tokens (token_hash, token_type, expires_at, created_at)
VALUES (?, ?, ?, ?)
ON CONFLICT (token_hash, token_type)
DO UPDATE SET expires_at = EXCLUDED.expires_at

Example (Revoke access token):

err := repo.MarkTokenRevoke(ctx, AccessToken, "eyJhbGciOiJIUzI1NiIs...", 24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to revoke token: %w", err)
}

Example (Revoke refresh token with shorter TTL):

err := repo.MarkTokenRevoke(ctx, RefreshToken, "refresh-token-here", 7*24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to revoke refresh token: %w", err)
}

func (*GormTokenRepository) MarkTokenRotated ¶ added in v1.0.6

func (r *GormTokenRepository) MarkTokenRotated(ctx context.Context, token string, ttl time.Duration) error

MarkTokenRotated marks a token as rotated by storing its hash. Uses atomic UPSERT operation for idempotent rotation tracking.

Security Purpose:

• Prevents replay of rotated refresh tokens
• Enables one-time use during token rotation flow
• Protects against token replay attacks

Performance Characteristics:

• Single database write operation
• Atomic UPSERT handles concurrent rotation attempts
• Unique index enables fast conflict detection

Parameters:

• ctx: Context for cancellation and timeout
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record (typically matches refresh token expiry)

Returns:

• error: If token is empty, TTL is invalid, or database operation fails

Database Operation:

INSERT INTO rotated_tokens (token_hash, expires_at, created_at)
VALUES (?, ?, ?)
ON CONFLICT (token_hash)
DO UPDATE SET expires_at = EXCLUDED.expires_at

Example (Mark token as rotated):

err := repo.MarkTokenRotated(ctx, "old-refresh-token", 7*24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to mark token as rotated: %w", err)
}

func (*GormTokenRepository) MarkTokenRotatedAtomic ¶ added in v1.0.6

func (r *GormTokenRepository) MarkTokenRotatedAtomic(ctx context.Context, token string, ttl time.Duration) (bool, error)

MarkTokenRotatedAtomic marks a token as rotated atomically, returning whether it was newly rotated. This method provides true atomicity for rotation detection in concurrent scenarios.

Use Cases:

• Preventing race conditions during concurrent token rotation
• Ensuring exactly-once rotation semantics
• Distributed system environments with multiple token validators

Key Difference from MarkTokenRotated:

• Returns boolean indicating if rotation was actually performed
• Uses DO NOTHING on conflict instead of updating
• Essential for preventing double-spending in rotation flows

Parameters:

• ctx: Context for cancellation and timeout
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• bool: True if token was newly rotated, false if already rotated
• error: If token is empty, TTL is invalid, or database operation fails

Database Operation:

INSERT INTO rotated_tokens (token_hash, expires_at, created_at)
VALUES (?, ?, ?)
ON CONFLICT (token_hash)
DO NOTHING

Example (Atomic rotation check):

rotated, err := repo.MarkTokenRotatedAtomic(ctx, "refresh-token", 24*time.Hour)
if err != nil {
    return fmt.Errorf("rotation failed: %w", err)
}
if !rotated {
    return errors.New("token was already rotated - potential replay attack")
}
// Proceed with issuing new tokens

func (*GormTokenRepository) Stats ¶ added in v1.0.6

func (r *GormTokenRepository) Stats(ctx context.Context) (map[string]interface{}, error)

Stats returns statistics about the repository for monitoring and debugging. Provides insights into token revocation and rotation patterns.

Metrics Collected:

• Total revoked tokens (all types)
• Revoked access tokens count
• Revoked refresh tokens count
• Rotated tokens count

Use Cases:

• Monitoring system health and usage patterns
• Capacity planning and performance tuning
• Security auditing and anomaly detection
• Debugging token-related issues

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• map[string]interface{}: Dictionary of statistics metrics
• error: If any database count operation fails

Example (Prometheus metrics):

stats, err := repo.Stats(ctx)
if err != nil {
    log.Printf("Failed to get stats: %v", err)
    return
}

// Export to monitoring system
revokedTotal.Set(float64(stats["total_revoked_tokens"].(int64)))
rotatedCount.Set(float64(stats["rotated_tokens"].(int64)))

func (*JWTMaker) CreateAccessToken ¶

func (maker *JWTMaker) CreateAccessToken(ctx context.Context, userID uuid.UUID, username string, roles []string, sessionID uuid.UUID) (*AccessTokenResponse, error)

CreateAccessToken generates a new signed access token with the specified claims. Access tokens are short-lived and include user identity, session, and authorization roles.

Token Structure:

• Header: Algorithm and token type
• Payload: User claims (ID, username, roles, timestamps)
• Signature: Cryptographic signature for verification

Automatic Claims:

• jti: Unique token identifier (auto-generated UUIDv4)
• iat: Issued at timestamp (current time)
• exp: Expiration time (iat + AccessExpiryDuration)
• nbf: Not before time (current time)
• mle: Maximum lifetime expiry (iat + AccessMaxLifetimeExpiry)
• iss: Issuer from configuration
• aud: Audience from configuration
• typ: Token type ("access")

Validation:

• userID must not be uuid.Nil
• username must not exceed 1024 characters
• roles must contain at least one non-empty string
• sessionID can be any UUID (including Nil for sessionless tokens)

Parameters:

• ctx: Context for cancellation. Checks are performed before signing and during I/O.
• userID: The user's unique identifier (UUID, must not be Nil)
• username: Human-readable username (max 1024 characters, can be empty)
• roles: List of authorization roles (must contain at least one non-empty role)
• sessionID: Session identifier (UUID, can be Nil for sessionless operation)

Returns:

• *AccessTokenResponse: Complete token response with signed JWT and metadata
• error: If parameters are invalid, signing fails, or context is cancelled

Example (Basic usage):

userUUID := uuid.MustParse("123e4567-e89b-12d3-a456-426614174000")
sessionUUID := uuid.New()

token, err := maker.CreateAccessToken(
    ctx,
    userUUID,
    "john.doe",
    []string{"user", "admin"},
    sessionUUID,
)
if err != nil {
    return fmt.Errorf("failed to create token: %w", err)
}

// Use token.Token in Authorization header
fmt.Printf("Token: %s\n", token.Token)
fmt.Printf("Expires: %s\n", token.ExpiresAt)

Example (Multiple roles):

token, err := maker.CreateAccessToken(
    ctx,
    userUUID,
    "[email protected]",
    []string{"user", "admin", "moderator"},
    sessionUUID,
)

Example (With context timeout):

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

token, err := maker.CreateAccessToken(ctx, userUUID, username, roles, sessionUUID)

func (*JWTMaker) CreateRefreshToken ¶

func (maker *JWTMaker) CreateRefreshToken(ctx context.Context, userID uuid.UUID, username string, sessionID uuid.UUID) (*RefreshTokenResponse, error)

CreateRefreshToken generates a new signed refresh token for obtaining new access tokens. Refresh tokens are long-lived and do not include authorization roles.

Token Structure:

• Header: Algorithm and token type
• Payload: User identity and session (no roles)
• Signature: Cryptographic signature for verification

Automatic Claims:

• jti: Unique token identifier (auto-generated UUIDv4)
• iat: Issued at timestamp (current time)
• exp: Expiration time (iat + RefreshExpiryDuration)
• nbf: Not before time (current time)
• mle: Maximum lifetime expiry (iat + RefreshMaxLifetimeExpiry)
• iss: Issuer from configuration
• aud: Audience from configuration
• typ: Token type ("refresh")

Validation:

• userID must not be uuid.Nil
• username must not exceed 1024 characters
• sessionID can be any UUID (including Nil)

Parameters:

• ctx: Context for cancellation
• userID: The user's unique identifier (UUID, must not be Nil)
• username: Human-readable username (max 1024 characters)
• sessionID: Session identifier (UUID)

Returns:

• *RefreshTokenResponse: Complete token response with signed JWT and metadata
• error: If parameters are invalid, signing fails, or context is cancelled

Security Best Practices:

• Store refresh tokens securely (httpOnly cookies, secure storage)
• Use token rotation to prevent reuse
• Implement refresh token revocation for logout
• Monitor for suspicious refresh patterns

Example (Create refresh token):

refreshToken, err := maker.CreateRefreshToken(
    ctx,
    userUUID,
    "john.doe",
    sessionUUID,
)
if err != nil {
    return fmt.Errorf("failed to create refresh token: %w", err)
}

// Store securely (e.g., httpOnly cookie)
http.SetCookie(w, &http.Cookie{
    Name:     "refresh_token",
    Value:    refreshToken.Token,
    Expires:  refreshToken.ExpiresAt,
    HttpOnly: true,
    Secure:   true,
    SameSite: http.SameSiteStrictMode,
})

Example (Create token pair):

accessToken, err := maker.CreateAccessToken(ctx, userUUID, username, roles, sessionUUID)
if err != nil {
    return err
}

refreshToken, err := maker.CreateRefreshToken(ctx, userUUID, username, sessionUUID)
if err != nil {
    return err
}

return &TokenPair{
    AccessToken:  accessToken.Token,
    RefreshToken: refreshToken.Token,
}

func (*JWTMaker) RevokeAccessToken ¶ added in v1.0.2

func (maker *JWTMaker) RevokeAccessToken(ctx context.Context, token string) error

RevokeAccessToken marks an access token as revoked, preventing its further use. The token will fail verification even if it hasn't expired yet. Requires RevocationEnabled to be true in the configuration.

Revocation Process:

1. Parses the token to extract expiration time
2. Calculates time-to-live (TTL) until natural expiration
3. Stores token hash in repository with TTL
4. Token verification will now fail for this token
5. Token is automatically removed from storage after TTL expires

Storage Considerations:

• Tokens are stored with TTL matching their remaining lifetime
• After natural expiration, revoked tokens are cleaned up
• Only the token hash is stored (not the full token)
• Cleanup runs automatically at CleanupInterval

Parameters:

• ctx: Context for cancellation and timeout
• token: The JWT token string to revoke

Returns:

• error: If revocation is disabled, token is invalid, repository operation fails, or context is cancelled

Use Cases:

• User logout (revoke current access token)
• Security breach (revoke compromised token)
• Administrative action (revoke specific user's tokens)
• Password change (revoke all existing tokens)

Limitations:

• Requires RevocationEnabled = true
• Requires TokenRepository
• Adds latency to token verification (repository lookup)
• Requires distributed storage for multi-instance systems

Example (Logout - revoke access token):

err := maker.RevokeAccessToken(ctx, accessTokenString)
if err != nil {
    return fmt.Errorf("failed to revoke token: %w", err)
}

// Token is now invalid and will fail verification
fmt.Println("User logged out successfully")

Example (Revoke all session tokens):

// Get all tokens for a session from your database
tokens, err := db.GetSessionTokens(ctx, sessionID)
if err != nil {
    return err
}

// Revoke each token
for _, token := range tokens {
    if err := maker.RevokeAccessToken(ctx, token); err != nil {
        log.Printf("Failed to revoke token: %v", err)
    }
}

Example (Security breach response):

// Revoke access token immediately
if err := maker.RevokeAccessToken(ctx, compromisedToken); err != nil {
    log.Printf("Failed to revoke compromised token: %v", err)
}

// Also revoke refresh token to prevent new access tokens
if err := maker.RevokeRefreshToken(ctx, refreshToken); err != nil {
    log.Printf("Failed to revoke refresh token: %v", err)
}

func (*JWTMaker) RevokeRefreshToken ¶ added in v1.0.2

func (maker *JWTMaker) RevokeRefreshToken(ctx context.Context, token string) error

RevokeRefreshToken marks a refresh token as revoked, preventing its further use. The token cannot be used to obtain new access tokens after revocation. Requires RevocationEnabled to be true in the configuration.

Revocation Process:

1. Parses the token to extract expiration time
2. Calculates time-to-live (TTL) until natural expiration
3. Stores token hash in repository with TTL
4. Token verification will now fail for this token
5. Token is automatically removed from storage after TTL expires

Impact:

• Prevents token from being used in RotateRefreshToken
• Prevents token from being verified successfully
• Existing access tokens remain valid until they expire
• User must re-authenticate to get new refresh token

Parameters:

• ctx: Context for cancellation and timeout
• token: The JWT refresh token string to revoke

Returns:

• error: If revocation is disabled, token is invalid, repository operation fails, or context is cancelled

Use Cases:

• User logout (revoke refresh token to prevent new access tokens)
• Forced re-authentication (after password change)
• Security incident response
• Session termination

Best Practices:

• Always revoke both access and refresh tokens during logout
• Revoke refresh tokens after password changes
• Monitor failed verification attempts (may indicate stolen tokens)
• Use short-lived refresh tokens if revocation is disabled

Example (Complete logout):

// Revoke both access and refresh tokens
if err := maker.RevokeAccessToken(ctx, accessToken); err != nil {
    log.Printf("Failed to revoke access token: %v", err)
}

if err := maker.RevokeRefreshToken(ctx, refreshToken); err != nil {
    return fmt.Errorf("failed to revoke refresh token: %w", err)
}

fmt.Println("Logged out successfully")

Example (Password change - revoke all user tokens):

// Get all refresh tokens for user
tokens, err := db.GetUserRefreshTokens(ctx, userID)
if err != nil {
    return err
}

// Revoke each refresh token
for _, token := range tokens {
    if err := maker.RevokeRefreshToken(ctx, token); err != nil {
        log.Printf("Failed to revoke token: %v", err)
    }
}

// User must re-authenticate on all devices

func (*JWTMaker) RotateRefreshToken ¶

func (maker *JWTMaker) RotateRefreshToken(ctx context.Context, oldToken string) (*RefreshTokenResponse, error)

RotateRefreshToken exchanges an old refresh token for a new one with extended expiration. The old token is atomically marked as rotated and cannot be reused, preventing token theft. Requires RotationEnabled to be true in the configuration.

Rotation Process:

1. Verifies the old token is valid (signature, expiration, not revoked/rotated)
2. Atomically marks the old token as rotated using compare-and-swap
3. If already rotated (by another request), returns error
4. Creates a new refresh token with the same user and session
5. Returns the new token with fresh expiration time

Atomicity Guarantee:

Uses MarkTokenRotatedAtomic to ensure only ONE concurrent request succeeds.
If multiple requests attempt to rotate the same token simultaneously, only the first
succeeds and others receive an error. This detects token theft attempts.

Security Benefits:

• Prevents token reuse attacks
• Detects concurrent rotation attempts (possible token theft)
• Limits blast radius of compromised tokens
• Enforces one-time use of refresh tokens

Parameters:

• ctx: Context for cancellation and timeout
• oldToken: The current refresh token to rotate (will be invalidated)

Returns:

• *RefreshTokenResponse: New refresh token with extended expiration
• error: If rotation is disabled, old token is invalid/already rotated, atomic operation fails, or context is cancelled

Error Scenarios:

• Token already rotated: Possible replay attack, invalidate session
• Token invalid/expired: Require re-authentication
• Rotation disabled: Feature not configured
• Repository error: Storage system unavailable

Security Implications:

If rotation fails due to "already rotated":
- Indicates possible token theft
- Consider invalidating the entire session
- Alert security monitoring systems
- Require full re-authentication

Example (Token refresh endpoint):

func refreshTokenHandler(w http.ResponseWriter, r *http.Request) {
    // Get refresh token from cookie or body
    oldToken := r.Header.Get("X-Refresh-Token")

    // Rotate the token
    newRefresh, err := maker.RotateRefreshToken(r.Context(), oldToken)
    if err != nil {
        if strings.Contains(err.Error(), "rotated") {
            // Possible token theft detected
            log.Printf("Token reuse detected for token: %v", err)
            http.Error(w, "security violation", http.StatusForbidden)
            return
        }
        http.Error(w, "invalid token", http.StatusUnauthorized)
        return
    }

    // Create new access token
    claims, _ := maker.VerifyRefreshToken(r.Context(), newRefresh.Token)
    accessToken, err := maker.CreateAccessToken(
        r.Context(),
        claims.Subject,
        claims.Username,
        getUserRoles(claims.Subject), // Load from DB
        claims.SessionID,
    )

    // Return new token pair
    json.NewEncoder(w).Encode(map[string]string{
        "access_token":  accessToken.Token,
        "refresh_token": newRefresh.Token,
    })
}

Example (With security monitoring):

newToken, err := maker.RotateRefreshToken(ctx, oldToken)
if err != nil {
    if strings.Contains(err.Error(), "rotated") {
        // Token theft detected
        securityLog.Alert("Token reuse attempt detected", map[string]interface{}{
            "token_prefix": oldToken[:10],
            "ip_address":   clientIP,
            "timestamp":    time.Now(),
        })

        // Revoke all user tokens
        revokeAllUserTokens(ctx, userID)
        return nil, fmt.Errorf("security violation: session terminated")
    }
    return nil, err
}

Example (Race condition handling):

// Multiple concurrent requests with same token
var wg sync.WaitGroup
results := make(chan error, 3)

for i := 0; i < 3; i++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        _, err := maker.RotateRefreshToken(ctx, sameToken)
        results <- err
    }()
}

wg.Wait()
close(results)

// Only one should succeed, others should get "already rotated" error
successCount := 0
for err := range results {
    if err == nil {
        successCount++
    }
}
// successCount should be exactly 1

func (*JWTMaker) VerifyAccessToken ¶

func (maker *JWTMaker) VerifyAccessToken(ctx context.Context, tokenString string) (*AccessTokenClaims, error)

VerifyAccessToken validates an access token and returns its claims if valid. Performs comprehensive security checks including signature, expiration, and revocation.

Validation Steps:

1. Check context cancellation
2. Check revocation status (if RevocationEnabled)
3. Verify cryptographic signature
4. Validate token structure and algorithm
5. Check all timestamps (iat, exp, nbf, mle)
6. Verify required claims are present
7. Validate token type is "access"
8. Parse and return claims

Checks Performed:

• Signature matches expected algorithm
• Token has not expired (exp > now)
• Token is not used before valid time (nbf <= now)
• Token has not exceeded maximum lifetime (mle > now)
• Token has not been revoked (if revocation enabled)
• All required claims are present
• Token type is "access" (not "refresh")

Parameters:

• ctx: Context for cancellation. Checked multiple times during verification.
• tokenString: The JWT token string to verify (from Authorization header)

Returns:

• *AccessTokenClaims: Parsed and validated token claims with all user information
• error: If token is invalid, expired, revoked, or any validation check fails

Error Scenarios:

• Invalid signature: Token has been tampered with
• Expired: Token lifetime has ended
• Revoked: Token was explicitly invalidated
• Wrong type: Refresh token used where access token expected
• Missing claims: Token structure is incomplete
• Future issued: Token claims to be issued in the future
• Context cancelled: Operation was cancelled by caller

Example (Verify and use claims):

claims, err := maker.VerifyAccessToken(ctx, tokenString)
if err != nil {
    return nil, fmt.Errorf("invalid token: %w", err)
}

// Use claims for authorization
if !hasRole(claims.Roles, "admin") {
    return fmt.Errorf("insufficient permissions")
}

// Access user information
fmt.Printf("User: %s (%s)\n", claims.Username, claims.Subject)
fmt.Printf("Session: %s\n", claims.SessionID)
fmt.Printf("Roles: %v\n", claims.Roles)

Example (HTTP middleware):

func authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        authHeader := r.Header.Get("Authorization")
        if authHeader == "" {
            http.Error(w, "missing authorization", http.StatusUnauthorized)
            return
        }

        token := strings.TrimPrefix(authHeader, "Bearer ")
        claims, err := maker.VerifyAccessToken(r.Context(), token)
        if err != nil {
            http.Error(w, "invalid token", http.StatusUnauthorized)
            return
        }

        // Add claims to context
        ctx := context.WithValue(r.Context(), "user_claims", claims)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func (*JWTMaker) VerifyRefreshToken ¶

func (maker *JWTMaker) VerifyRefreshToken(ctx context.Context, tokenString string) (*RefreshTokenClaims, error)

VerifyRefreshToken validates a refresh token and returns its claims if valid. Performs comprehensive security checks including signature, expiration, revocation, and rotation.

Validation Steps:

1. Check context cancellation
2. Check revocation status (if RevocationEnabled)
3. Check rotation status (if RotationEnabled)
4. Verify cryptographic signature
5. Validate token structure and algorithm
6. Check all timestamps (iat, exp, nbf, mle)
7. Verify required claims are present
8. Validate token type is "refresh"
9. Parse and return claims

Checks Performed:

• Signature matches expected algorithm
• Token has not expired (exp > now)
• Token is not used before valid time (nbf <= now)
• Token has not exceeded maximum lifetime (mle > now)
• Token has not been revoked (if revocation enabled)
• Token has not been rotated (if rotation enabled)
• All required claims are present
• Token type is "refresh" (not "access")

Parameters:

• ctx: Context for cancellation
• tokenString: The JWT refresh token string to verify

Returns:

• *RefreshTokenClaims: Parsed and validated token claims
• error: If token is invalid, expired, revoked, rotated, or any validation check fails

Error Scenarios:

• Invalid signature: Token has been tampered with
• Expired: Token lifetime has ended
• Revoked: Token was explicitly invalidated
• Rotated: Token has been used to obtain a new token (rotation enabled)
• Wrong type: Access token used where refresh token expected
• Missing claims: Token structure is incomplete
• Context cancelled: Operation was cancelled

Use Cases:

• Validating refresh token before rotation
• Checking refresh token validity before issuing new access token
• Verifying refresh token in logout operations

Example (Refresh access token):

// Verify the refresh token
refreshClaims, err := maker.VerifyRefreshToken(ctx, refreshTokenString)
if err != nil {
    return nil, fmt.Errorf("invalid refresh token: %w", err)
}

// Create new access token with same user/session
newAccessToken, err := maker.CreateAccessToken(
    ctx,
    refreshClaims.Subject,
    refreshClaims.Username,
    []string{"user"}, // Load roles from database
    refreshClaims.SessionID,
)

Example (With rotation):

// Automatically rotates the token if rotation is enabled
newRefreshToken, err := maker.RotateRefreshToken(ctx, oldRefreshTokenString)
if err != nil {
    return fmt.Errorf("rotation failed: %w", err)
}

// Old token is now invalid, use new token

func (*MemoryTokenRepository) CleanupExpiredRevokedTokens ¶ added in v1.0.6

func (m *MemoryTokenRepository) CleanupExpiredRevokedTokens(ctx context.Context, tokenType TokenType) error

CleanupExpiredRevokedTokens removes expired revoked tokens from memory. Thread-safe operation with write lock protection.

Cleanup Strategy:

• Iterates through specified token type map
• Removes entries where expiration time has passed
• O(n) operation where n is number of entries for that type
• Run periodically to prevent memory leaks

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• tokenType: Type of tokens to cleanup (AccessToken or RefreshToken)

Returns:

• error: If token type is invalid

Example (Manual cleanup):

err := repo.CleanupExpiredRevokedTokens(ctx, AccessToken)
if err != nil {
    log.Printf("Failed to cleanup access tokens: %v", err)
}

func (*MemoryTokenRepository) CleanupExpiredRotatedTokens ¶ added in v1.0.6

func (m *MemoryTokenRepository) CleanupExpiredRotatedTokens(ctx context.Context) error

CleanupExpiredRotatedTokens removes expired rotated tokens from memory. Thread-safe operation with write lock protection.

Cleanup Efficiency:

• Single pass through rotated tokens map
• O(n) operation where n is number of rotated tokens
• Typically fewer rotated tokens than revoked tokens
• Helps prevent memory bloat

Parameters:

• ctx: Context for cancellation (not used in memory implementation)

Returns:

• error: Always nil (error included for interface compatibility)

Example (Manual cleanup):

err := repo.CleanupExpiredRotatedTokens(ctx)
if err != nil {
    log.Printf("Failed to cleanup rotated tokens: %v", err)
}

func (*MemoryTokenRepository) Close ¶ added in v1.0.6

func (m *MemoryTokenRepository) Close() error

Close stops the background cleanup goroutine. Implements graceful shutdown pattern to prevent goroutine leaks.

Important: Call this method when shutting down the application to ensure proper cleanup of resources and prevent goroutine leaks.

Implementation Details:

• Uses sync.Once to ensure idempotent operation
• Closes stopCleanup channel to signal goroutine termination
• Goroutine will complete current cleanup cycle before exiting
• Safe to call multiple times

Returns:

• error: Always nil (error included for interface compatibility)

Example (Application shutdown):

// Handle graceful shutdown
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

// Close repository
if err := repo.Close(); err != nil {
    log.Printf("Warning: failed to close token repository: %v", err)
}

func (*MemoryTokenRepository) GetRotationTTL ¶ added in v1.0.6

func (m *MemoryTokenRepository) GetRotationTTL(ctx context.Context, token string) (time.Duration, error)

GetRotationTTL returns the remaining TTL for a rotated token. Useful for debugging and monitoring rotation patterns.

Use Cases:

• Debugging rotation-related issues
• Monitoring token lifecycle
• Understanding cleanup timing

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• token: The token to check for remaining TTL

Returns:

• time.Duration: Remaining TTL if token is rotated and not expired, 0 otherwise
• error: If token is empty

Example (Monitor rotation TTL):

ttl, err := repo.GetRotationTTL(ctx, "rotated-token")
if err != nil {
    return fmt.Errorf("failed to get TTL: %w", err)
}
log.Printf("Token will be automatically cleaned up in %v", ttl)

func (*MemoryTokenRepository) IsTokenRevoked ¶ added in v1.0.6

func (m *MemoryTokenRepository) IsTokenRevoked(ctx context.Context, tokenType TokenType, token string) (bool, error)

IsTokenRevoked checks if a token has been revoked by checking its hash in memory. Thread-safe operation with read lock for high concurrency.

Performance Characteristics:

• O(1) average case lookup
• Read lock enables concurrent reads
• Automatic expiration check during lookup
• No network or disk I/O

Operation Sequence:

1. Hash the provided token
2. Acquire read lock
3. Lookup in appropriate token map
4. Check expiration time
5. Return revocation status

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• tokenType: Type of token to check (AccessToken or RefreshToken)
• token: The token string to check for revocation

Returns:

• bool: True if token is revoked and not expired, false otherwise
• error: If token is empty or token type is invalid

Example (Check access token):

revoked, err := repo.IsTokenRevoked(ctx, AccessToken, "jwt-token-here")
if err != nil {
    return fmt.Errorf("failed to check revocation: %w", err)
}
if revoked {
    return errors.New("token has been revoked")
}

func (*MemoryTokenRepository) IsTokenRotated ¶ added in v1.0.6

func (m *MemoryTokenRepository) IsTokenRotated(ctx context.Context, token string) (bool, error)

IsTokenRotated checks if a token has been rotated by checking its hash in memory. Thread-safe operation with read lock for high concurrency.

Security Purpose:

• Detects if a refresh token has been previously rotated
• Prevents reuse of rotated tokens
• Essential for rotation-based security

Performance:

• O(1) average case lookup
• Read lock enables concurrent access
• Automatic expiration check

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• token: The token to check for rotation status

Returns:

• bool: True if token has been rotated and not expired, false otherwise
• error: If token is empty

Example (Check rotation status):

rotated, err := repo.IsTokenRotated(ctx, "suspect-token")
if err != nil {
    return fmt.Errorf("failed to check rotation: %w", err)
}
if rotated {
    return errors.New("token has been rotated - do not accept")
}

func (*MemoryTokenRepository) MarkTokenRevoke ¶ added in v1.0.6

func (m *MemoryTokenRepository) MarkTokenRevoke(ctx context.Context, tokenType TokenType, token string, ttl time.Duration) error

MarkTokenRevoke marks a token as revoked by storing its hash in memory. Thread-safe operation with write lock protection.

Memory Storage:

• Token hash stored in type-specific map
• Expiration time stored for automatic cleanup
• Separate maps for access vs refresh tokens
• O(1) insertion time with map store

Security Implementation:

• Only SHA-256 hash of token stored
• No sensitive token data retained
• Automatic expiration via TTL

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• tokenType: Type of token (AccessToken or RefreshToken)
• token: The actual token string to revoke
• ttl: Time-to-live duration for the revocation record

Returns:

• error: If token is empty, TTL is invalid, or token type is invalid

Example (Revoke access token):

err := repo.MarkTokenRevoke(ctx, AccessToken, "jwt-token-here", 15*time.Minute)
if err != nil {
    return fmt.Errorf("failed to revoke token: %w", err)
}

Example (Revoke refresh token):

err := repo.MarkTokenRevoke(ctx, RefreshToken, "refresh-token-here", 7*24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to revoke refresh token: %w", err)
}

func (*MemoryTokenRepository) MarkTokenRotated ¶ added in v1.0.6

func (m *MemoryTokenRepository) MarkTokenRotated(ctx context.Context, token string, ttl time.Duration) error

MarkTokenRotated marks a token as rotated by storing its hash in memory. Thread-safe operation with write lock protection.

Security Purpose:

• Prevents replay of rotated refresh tokens
• Essential for rotation-based security
• Protects against token reuse attacks

Memory Storage:

• Single map for all rotated tokens
• O(1) insertion time
• Automatic expiration via TTL

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• error: If token is empty or TTL is invalid

Example (Mark token as rotated):

err := repo.MarkTokenRotated(ctx, "old-refresh-token", 24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to mark token as rotated: %w", err)
}

func (*MemoryTokenRepository) MarkTokenRotatedAtomic ¶ added in v1.0.6

func (m *MemoryTokenRepository) MarkTokenRotatedAtomic(ctx context.Context, token string, ttl time.Duration) (bool, error)

MarkTokenRotatedAtomic marks a token as rotated atomically, returning whether it was newly rotated. Provides true atomicity for rotation detection in concurrent scenarios.

Key Features:

• Atomic check-and-set operation
• Returns whether rotation was actually performed
• Essential for preventing double-spending in rotation flows
• Thread-safe with proper locking

Difference from MarkTokenRotated:

• Returns boolean indicating if rotation was new
• Performs existence check within critical section
• Prevents race conditions in concurrent environments

Parameters:

• ctx: Context for cancellation (not used in memory implementation)
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• bool: True if token was newly rotated, false if already rotated
• error: If token is empty or TTL is invalid

Example (Atomic rotation check):

rotated, err := repo.MarkTokenRotatedAtomic(ctx, "refresh-token", time.Hour)
if err != nil {
    return fmt.Errorf("rotation failed: %w", err)
}
if !rotated {
    return errors.New("token was already rotated - potential security issue")
}
// Safe to proceed with new token issuance

func (*MemoryTokenRepository) Stats ¶ added in v1.0.6

func (m *MemoryTokenRepository) Stats() map[string]int

Stats returns statistics about the repository for monitoring and debugging. Provides snapshot of current memory usage and token counts.

Metrics Provided:

• revoked_access_tokens: Count of currently revoked access tokens
• revoked_refresh_tokens: Count of currently revoked refresh tokens
• rotated_tokens: Count of currently rotated tokens

Use Cases:

• Monitoring memory usage patterns
• Debugging token-related issues
• Capacity planning and performance analysis
• Health checking and alerting

Returns:

• map[string]int: Dictionary of current repository statistics

Example (Monitoring endpoint):

// Expose stats via HTTP endpoint
http.HandleFunc("/stats", func(w http.ResponseWriter, r *http.Request) {
    stats := repo.Stats()
    json.NewEncoder(w).Encode(stats)
})

Example (Logging statistics):

stats := repo.Stats()
log.Printf("Token repository stats: %+v", stats)

func (*MongoTokenRepository) CleanupExpiredRevokedTokens ¶ added in v1.0.6

func (r *MongoTokenRepository) CleanupExpiredRevokedTokens(ctx context.Context, tokenType TokenType) error

CleanupExpiredRevokedTokens removes expired revoked tokens from MongoDB. Note: MongoDB TTL indexes handle automatic cleanup, but this provides manual control.

Use Cases:

• Force immediate cleanup of expired documents
• Handle cases where TTL monitor is delayed
• Bulk cleanup during maintenance windows
• Testing and development environments

Performance Characteristics:

• DeleteMany operation for batch processing
• Index on expires_at enables efficient range query
• Transaction wrapper ensures operation consistency
• Batch operation minimizes database round trips

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of tokens to cleanup (AccessToken or RefreshToken)

Returns:

• error: If token type is invalid or database operation fails

Example (Manual cleanup):

err := repo.CleanupExpiredRevokedTokens(ctx, AccessToken)
if err != nil {
    log.Printf("Failed to cleanup access tokens: %v", err)
}

MongoDB Operation:

db.revoked_tokens.deleteMany({
  token_type: "access",
  expires_at: { $lte: ISODate() }
})

func (*MongoTokenRepository) CleanupExpiredRotatedTokens ¶ added in v1.0.6

func (r *MongoTokenRepository) CleanupExpiredRotatedTokens(ctx context.Context) error

CleanupExpiredRotatedTokens removes expired rotated tokens from MongoDB. Provides manual control over TTL-based automatic cleanup.

Cleanup Strategy:

• DeleteMany operation with expires_at filter
• Leverages TTL index for efficient query
• Transaction wrapper for consistency
• Batch operation for efficiency

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• error: If database operation fails

Example (Scheduled manual cleanup):

// Run additional cleanup daily (TTL indexes handle most cases)
ticker := time.NewTicker(24 * time.Hour)
defer ticker.Stop()

for range ticker.C {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    err := repo.CleanupExpiredRotatedTokens(ctx)
    cancel()
    if err != nil {
        log.Printf("Manual rotated token cleanup failed: %v", err)
    }
}

MongoDB Operation:

db.rotated_tokens.deleteMany({
  expires_at: { $lte: ISODate() }
})

func (*MongoTokenRepository) Close ¶ added in v1.0.6

func (r *MongoTokenRepository) Close(ctx context.Context) error

Close performs cleanup operations for the MongoDB repository. Note: MongoDB driver manages connection pooling automatically.

Cleanup Behavior:

• MongoDB connections are managed by the driver
• No explicit connection closing needed for collections
• Client should be closed at application level
• This method exists for interface compatibility

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• error: Always nil (included for interface compatibility)

Important: While this repository doesn't require explicit closing, the MongoDB client should be closed during application shutdown:

defer func() {
    if err := client.Disconnect(ctx); err != nil {
        log.Printf("Failed to disconnect MongoDB: %v", err)
    }
}()

func (*MongoTokenRepository) GetRotationTTL ¶ added in v1.0.6

func (r *MongoTokenRepository) GetRotationTTL(ctx context.Context, token string) (time.Duration, error)

GetRotationTTL returns the remaining TTL for a rotated token. Useful for debugging, monitoring, and cache optimization.

Use Cases:

• Debugging rotation-related issues
• Monitoring token rotation patterns
• Optimizing cleanup scheduling
• Understanding token lifecycle

Parameters:

• ctx: Context for cancellation and timeout
• token: The token to check for remaining TTL

Returns:

• time.Duration: Remaining TTL if token is rotated and not expired, 0 otherwise
• error: If token is empty or database operation fails

Example (Monitor rotation TTL):

ttl, err := repo.GetRotationTTL(ctx, "rotated-token")
if err != nil {
    return fmt.Errorf("failed to get rotation TTL: %w", err)
}
if ttl > 0 {
    log.Printf("Token will be automatically cleaned up in %v", ttl)
}

MongoDB Query:

db.rotated_tokens.findOne({ token_hash: "hash" })

func (*MongoTokenRepository) IsTokenRevoked ¶ added in v1.0.6

func (r *MongoTokenRepository) IsTokenRevoked(ctx context.Context, tokenType TokenType, token string) (bool, error)

IsTokenRevoked checks if a token has been revoked by checking its hash in MongoDB. Performs efficient document lookup using composite index and expiration filter.

Query Optimization:

• Uses composite index (token_hash, token_type) for fast lookups
• Additional filter on expires_at leverages TTL index
• Single document read operation
• FindOne returns at most one document

Performance Characteristics:

• O(1) average case with proper indexing
• Index-only query possible with covered indexes
• Read operation with minimal locking
• No transaction overhead for reads

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of token to check (AccessToken or RefreshToken)
• token: The token string to check for revocation

Returns:

• bool: True if token is revoked and not expired, false otherwise
• error: If token is empty, token type is invalid, or database operation fails

Example (Check access token):

revoked, err := repo.IsTokenRevoked(ctx, AccessToken, "jwt-token-here")
if err != nil {
    return fmt.Errorf("failed to check revocation: %w", err)
}
if revoked {
    return errors.New("token has been revoked")
}

MongoDB Query:

db.revoked_tokens.findOne({
  token_hash: "hash",
  token_type: "access",
  expires_at: { $gt: ISODate() }
})

func (*MongoTokenRepository) IsTokenRotated ¶ added in v1.0.6

func (r *MongoTokenRepository) IsTokenRotated(ctx context.Context, token string) (bool, error)

IsTokenRotated checks if a token has been rotated by checking its hash in MongoDB. Performs efficient document lookup with automatic expiration filtering.

Security Purpose:

• Detects if a refresh token has been previously rotated
• Prevents reuse of rotated tokens in replay attacks
• Essential for rotation-based security schemes

Query Optimization:

• Uses unique index on token_hash for fast lookups
• Additional filter on expires_at leverages TTL index
• Single document read operation

Parameters:

• ctx: Context for cancellation and timeout
• token: The token to check for rotation status

Returns:

• bool: True if token has been rotated and not expired, false otherwise
• error: If token is empty or database operation fails

Example (Check rotation status):

rotated, err := repo.IsTokenRotated(ctx, "suspect-refresh-token")
if err != nil {
    return fmt.Errorf("failed to check rotation: %w", err)
}
if rotated {
    return errors.New("token has been rotated - do not accept")
}

MongoDB Query:

db.rotated_tokens.findOne({
  token_hash: "hash",
  expires_at: { $gt: ISODate() }
})

func (*MongoTokenRepository) MarkTokenRevoke ¶ added in v1.0.6

func (r *MongoTokenRepository) MarkTokenRevoke(ctx context.Context, tokenType TokenType, token string, ttl time.Duration) error

MarkTokenRevoke marks a token as revoked by storing its hash in MongoDB. Uses composite unique key (token_hash, token_type) for proper upsert behavior.

MongoDB Operation:

• Uses ReplaceOne with upsert for atomic create-or-update
• Composite unique index prevents duplicate entries
• Transaction wrapper ensures operation consistency
• Automatic TTL via index handles expiration

Performance Characteristics:

• Single document write operation
• Indexed fields enable fast conflict detection
• Upsert operation is atomic at document level
• Transaction overhead if enabled

Security Implementation:

• Only token hash stored, never actual token
• Composite key ensures type-specific revocation
• Automatic expiration prevents permanent storage

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of token (AccessToken or RefreshToken)
• token: The actual token string to revoke
• ttl: Time-to-live duration for the revocation record

Returns:

• error: If token is empty, TTL is invalid, token type is invalid, or database operation fails

Example (Revoke access token):

err := repo.MarkTokenRevoke(ctx, AccessToken, "jwt-token-here", 15*time.Minute)
if err != nil {
    return fmt.Errorf("failed to revoke token: %w", err)
}

MongoDB Query:

db.revoked_tokens.replaceOne(
  { token_hash: "hash", token_type: "access" },
  { token_hash: "hash", token_type: "access", expires_at: ISODate(), created_at: ISODate() },
  { upsert: true }
)

func (*MongoTokenRepository) MarkTokenRotated ¶ added in v1.0.6

func (r *MongoTokenRepository) MarkTokenRotated(ctx context.Context, token string, ttl time.Duration) error

MarkTokenRotated marks a token as rotated by storing its hash in MongoDB. Uses upsert operation for idempotent rotation tracking.

Security Purpose:

• Prevents replay of rotated refresh tokens
• Enables one-time use during token rotation flow
• Protects against token replay attacks

MongoDB Operation:

• ReplaceOne with upsert on token_hash field
• Unique index prevents duplicate rotations
• Transaction wrapper ensures operation consistency
• Automatic TTL via index handles expiration

Parameters:

• ctx: Context for cancellation and timeout
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• error: If token is empty, TTL is invalid, or database operation fails

Example (Mark token as rotated):

err := repo.MarkTokenRotated(ctx, "old-refresh-token", 7*24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to mark token as rotated: %w", err)
}

MongoDB Query:

db.rotated_tokens.replaceOne(
  { token_hash: "hash" },
  { token_hash: "hash", expires_at: ISODate(), created_at: ISODate() },
  { upsert: true }
)

func (*MongoTokenRepository) MarkTokenRotatedAtomic ¶ added in v1.0.6

func (r *MongoTokenRepository) MarkTokenRotatedAtomic(ctx context.Context, token string, ttl time.Duration) (bool, error)

MarkTokenRotatedAtomic marks a token as rotated atomically, returning whether it was newly rotated. Uses InsertOne instead of ReplaceOne to detect true first-time rotation.

Key Difference from MarkTokenRotated:

• Returns boolean indicating if rotation was actually performed
• Uses InsertOne which fails on duplicate key (already rotated)
• Essential for preventing double-spending in rotation flows
• Provides true atomicity for rotation detection

Use Cases:

• Preventing race conditions during concurrent token rotation
• Ensuring exactly-once rotation semantics
• Distributed system environments with multiple validators

Parameters:

• ctx: Context for cancellation and timeout
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• bool: True if token was newly rotated, false if already rotated
• error: If token is empty, TTL is invalid, or database operation fails

Example (Atomic rotation check):

rotated, err := repo.MarkTokenRotatedAtomic(ctx, "refresh-token", 24*time.Hour)
if err != nil {
    return fmt.Errorf("rotation failed: %w", err)
}
if !rotated {
    return errors.New("token was already rotated - potential replay attack")
}
// Proceed with issuing new tokens

MongoDB Operation:

db.rotated_tokens.insertOne({
  token_hash: "hash",
  expires_at: ISODate(),
  created_at: ISODate()
})
// Fails with duplicate key error if already exists

func (*MongoTokenRepository) Stats ¶ added in v1.0.6

func (r *MongoTokenRepository) Stats(ctx context.Context) (map[string]interface{}, error)

Stats returns statistics about the repository for monitoring and debugging. Provides insights into token revocation and rotation patterns.

Metrics Collected:

• Total revoked tokens (all types)
• Revoked access tokens count
• Revoked refresh tokens count
• Rotated tokens count

Performance Characteristics:

• CountDocuments operations use collection statistics
• Efficient counting with MongoDB's metadata
• Separate queries for different token types
• No document scanning for count operations

Use Cases:

• Monitoring system health and usage patterns
• Capacity planning and performance tuning
• Security auditing and anomaly detection
• Debugging token-related issues

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• map[string]interface{}: Dictionary of statistics metrics
• error: If any database count operation fails

Example (Prometheus metrics export):

stats, err := repo.Stats(ctx)
if err != nil {
    log.Printf("Failed to get stats: %v", err)
    return
}

revokedTotal.Set(float64(stats["total_revoked_tokens"].(int64)))
rotatedCount.Set(float64(stats["rotated_tokens"].(int64)))

func (*RedisTokenRepository) CleanupExpiredRevokedTokens ¶ added in v1.0.6

func (r *RedisTokenRepository) CleanupExpiredRevokedTokens(ctx context.Context, tokenType TokenType) error

CleanupExpiredRevokedTokens removes expired revoked tokens from Redis. Note: Redis automatically removes expired keys, but this provides manual control.

Use Cases:

• Force immediate cleanup of expired keys
• Handle memory fragmentation issues
• Bulk cleanup during maintenance windows
• Testing and development environments

Cleanup Strategy:

• SCAN iterates through keys with specified prefix
• PTTL checks remaining TTL for each key
• DEL removes keys that are expired or have no TTL
• Batch processing for memory efficiency

Performance Characteristics:

• O(N) where N is number of keys with prefix
• SCAN is non-blocking and production-safe
• Pipeline reduces round trips
• Batch deletion improves efficiency

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of tokens to cleanup (AccessToken or RefreshToken)

Returns:

• error: If token type is invalid or Redis operation fails

Example (Manual cleanup):

err := repo.CleanupExpiredRevokedTokens(ctx, AccessToken)
if err != nil {
    log.Printf("Failed to cleanup access tokens: %v", err)
}

func (*RedisTokenRepository) CleanupExpiredRotatedTokens ¶ added in v1.0.6

func (r *RedisTokenRepository) CleanupExpiredRotatedTokens(ctx context.Context) error

CleanupExpiredRotatedTokens removes expired rotated tokens from Redis. Provides manual control over Redis's automatic key expiration.

Cleanup Strategy:

• SCAN iterates through rotated token keys
• PTTL checks remaining TTL for each key
• DEL removes expired keys in batches
• Context cancellation support for long-running operations

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• error: If Redis operation fails

Example (Scheduled manual cleanup):

// Run additional cleanup weekly (Redis TTL handles most cases)
ticker := time.NewTicker(7 * 24 * time.Hour)
defer ticker.Stop()

for range ticker.C {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
    err := repo.CleanupExpiredRotatedTokens(ctx)
    cancel()
    if err != nil {
        log.Printf("Manual rotated token cleanup failed: %v", err)
    }
}

func (*RedisTokenRepository) Close ¶ added in v1.0.6

func (r *RedisTokenRepository) Close() error

Close performs cleanup operations and closes the Redis connection. Implements graceful shutdown pattern for resource cleanup.

Cleanup Actions:

• Closes Redis client connection pool
• Releases all Redis connections
• Prevents connection leaks during application shutdown

Important: This should be called during application shutdown to prevent Redis connection leaks and ensure graceful termination.

Returns:

• error: If closing the Redis client fails

Example (Graceful shutdown):

// Setup signal handling
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

// Wait for shutdown signal
<-ctx.Done()

// Close repository during shutdown
if err := repo.Close(); err != nil {
    log.Printf("Failed to close Redis token repository: %v", err)
}

func (*RedisTokenRepository) GetRotationTTL ¶ added in v1.0.6

func (r *RedisTokenRepository) GetRotationTTL(ctx context.Context, token string) (time.Duration, error)

GetRotationTTL returns the remaining TTL for a rotated token. Uses PTTL for millisecond precision TTL checking.

Use Cases:

• Debugging rotation-related issues
• Monitoring token rotation patterns
• Optimizing cleanup scheduling
• Understanding token lifecycle

Redis PTTL Behavior:

• Returns -2 if key doesn't exist
• Returns -1 if key exists but has no expiry
• Returns positive value for remaining TTL in milliseconds
• Millisecond precision for accurate timing

Parameters:

• ctx: Context for cancellation and timeout
• token: The token to check for remaining TTL

Returns:

• time.Duration: Remaining TTL if token is rotated and not expired, 0 otherwise
• error: If token is empty or Redis operation fails

Example (Monitor rotation TTL):

ttl, err := repo.GetRotationTTL(ctx, "rotated-token")
if err != nil {
    return fmt.Errorf("failed to get rotation TTL: %w", err)
}
if ttl > 0 {
    log.Printf("Token will be automatically cleaned up in %v", ttl)
}

Redis Command:

PTTL rotated:token_hash

func (*RedisTokenRepository) IsTokenRevoked ¶ added in v1.0.6

func (r *RedisTokenRepository) IsTokenRevoked(ctx context.Context, tokenType TokenType, token string) (bool, error)

IsTokenRevoked checks if a token has been revoked by checking its hash in Redis. Uses GET operation for reliable existence checking with TTL validation.

Redis Operation:

• GET key
• Returns value if key exists and TTL hasn't expired
• Returns nil if key doesn't exist or TTL has expired

Performance Characteristics:

• O(1) time complexity
• Single GET operation
• In-memory lookup for maximum speed
• Automatic TTL handling by Redis

Key Advantages over EXISTS:

• GET is atomic and reliable
• Works correctly with expiring keys
• Returns actual value for verification
• Consistent behavior in cluster environments

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of token to check (AccessToken or RefreshToken)
• token: The token string to check for revocation

Returns:

• bool: True if token is revoked and not expired, false otherwise
• error: If token is empty, token type is invalid, or Redis operation fails

Example (Check access token):

revoked, err := repo.IsTokenRevoked(ctx, AccessToken, "jwt-token-here")
if err != nil {
    return fmt.Errorf("failed to check revocation: %w", err)
}
if revoked {
    return errors.New("token has been revoked")
}

Redis Command:

GET revoked:access:token_hash

func (*RedisTokenRepository) IsTokenRotated ¶ added in v1.0.6

func (r *RedisTokenRepository) IsTokenRotated(ctx context.Context, token string) (bool, error)

IsTokenRotated checks if a token has been rotated by checking its hash in Redis. Uses GET operation for reliable existence checking with TTL validation.

Security Purpose:

• Detects if a refresh token has been previously rotated
• Prevents reuse of rotated tokens in replay attacks
• Essential for rotation-based security schemes

Performance Characteristics:

• O(1) time complexity
• Single GET operation
• In-memory lookup for maximum speed
• Automatic TTL handling by Redis

Parameters:

• ctx: Context for cancellation and timeout
• token: The token to check for rotation status

Returns:

• bool: True if token has been rotated and not expired, false otherwise
• error: If token is empty or Redis operation fails

Example (Check rotation status):

rotated, err := repo.IsTokenRotated(ctx, "suspect-refresh-token")
if err != nil {
    return fmt.Errorf("failed to check rotation: %w", err)
}
if rotated {
    return errors.New("token has been rotated - do not accept")
}

Redis Command:

GET rotated:token_hash

func (*RedisTokenRepository) MarkTokenRevoke ¶ added in v1.0.6

func (r *RedisTokenRepository) MarkTokenRevoke(ctx context.Context, tokenType TokenType, token string, ttl time.Duration) error

MarkTokenRevoke marks a token as revoked by storing its hash in Redis. Uses key with TTL for automatic expiration and pipeline for atomic operation.

Redis Operation:

• SET key value EX seconds
• Key format: "revoked:access:{hash}" or "revoked:refresh:{hash}"
• Value: "1" (simple marker)
• TTL: Automatic expiration after specified duration

Performance Characteristics:

• Single SET operation with TTL
• O(1) time complexity
• Pipeline ensures atomic execution
• In-memory operation for maximum speed

Security Implementation:

• Only token hash stored, never actual token
• Automatic expiration via TTL
• Separate namespaces for access vs refresh tokens

Parameters:

• ctx: Context for cancellation and timeout
• tokenType: Type of token (AccessToken or RefreshToken)
• token: The actual token string to revoke
• ttl: Time-to-live duration for the revocation record

Returns:

• error: If token is empty, TTL is invalid, token type is invalid, or Redis operation fails

Example (Revoke access token):

err := repo.MarkTokenRevoke(ctx, AccessToken, "jwt-token-here", 15*time.Minute)
if err != nil {
    return fmt.Errorf("failed to revoke token: %w", err)
}

Redis Command:

SET revoked:access:token_hash "1" EX 900

func (*RedisTokenRepository) MarkTokenRotated ¶ added in v1.0.6

func (r *RedisTokenRepository) MarkTokenRotated(ctx context.Context, token string, ttl time.Duration) error

MarkTokenRotated marks a token as rotated by storing its hash in Redis. Uses key with TTL for automatic expiration and pipeline for atomic operation.

Security Purpose:

• Prevents replay of rotated refresh tokens
• Enables one-time use during token rotation flow
• Protects against token replay attacks

Redis Operation:

• SET key value EX seconds
• Key format: "rotated:{hash}"
• Value: "1" (simple marker)
• TTL: Automatic expiration after specified duration

Parameters:

• ctx: Context for cancellation and timeout
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• error: If token is empty, TTL is invalid, or Redis operation fails

Example (Mark token as rotated):

err := repo.MarkTokenRotated(ctx, "old-refresh-token", 7*24*time.Hour)
if err != nil {
    return fmt.Errorf("failed to mark token as rotated: %w", err)
}

Redis Command:

SET rotated:token_hash "1" EX 604800

func (*RedisTokenRepository) MarkTokenRotatedAtomic ¶ added in v1.0.6

func (r *RedisTokenRepository) MarkTokenRotatedAtomic(ctx context.Context, token string, ttl time.Duration) (bool, error)

MarkTokenRotatedAtomic marks a token as rotated atomically, returning whether it was newly rotated. Uses SETNX (SET if Not eXists) for true atomic rotation detection.

Key Difference from MarkTokenRotated:

• Returns boolean indicating if rotation was actually performed
• Uses SETNX which only sets if key doesn't exist
• Essential for preventing double-spending in rotation flows
• Provides true atomicity for rotation detection

Redis Operation:

• SETNX key value
• EXPIRE key seconds (if SETNX succeeds)
• Atomic check-and-set operation

Use Cases:

• Preventing race conditions during concurrent token rotation
• Ensuring exactly-once rotation semantics
• Distributed system environments with multiple validators

Parameters:

• ctx: Context for cancellation and timeout
• token: The refresh token being rotated
• ttl: Time-to-live duration for rotation record

Returns:

• bool: True if token was newly rotated, false if already rotated
• error: If token is empty, TTL is invalid, or Redis operation fails

Example (Atomic rotation check):

rotated, err := repo.MarkTokenRotatedAtomic(ctx, "refresh-token", 24*time.Hour)
if err != nil {
    return fmt.Errorf("rotation failed: %w", err)
}
if !rotated {
    return errors.New("token was already rotated - potential replay attack")
}
// Safe to proceed with new token issuance

Redis Commands:

SETNX rotated:token_hash "1"
EXPIRE rotated:token_hash 86400

func (*RedisTokenRepository) Stats ¶ added in v1.0.6

func (r *RedisTokenRepository) Stats(ctx context.Context) (map[string]interface{}, error)

Stats returns statistics about the repository for monitoring and debugging. Provides insights into token revocation and rotation patterns using SCAN operations.

Metrics Collected:

• Total revoked tokens (all types)
• Revoked access tokens count
• Revoked refresh tokens count
• Rotated tokens count

Performance Characteristics:

• Uses SCAN for production-safe key counting
• O(N) where N is total number of keys
• Batch processing for memory efficiency
• Non-blocking operations

Use Cases:

• Monitoring system health and usage patterns
• Capacity planning and performance tuning
• Security auditing and anomaly detection
• Debugging token-related issues

Parameters:

• ctx: Context for cancellation and timeout

Returns:

• map[string]interface{}: Dictionary of statistics metrics
• error: If any Redis count operation fails

Example (Monitoring dashboard):

stats, err := repo.Stats(ctx)
if err != nil {
    log.Printf("Failed to get Redis stats: %v", err)
    return
}

fmt.Printf("Redis token statistics: %+v\n", stats)

func (RevokedTokenType) TableName ¶ added in v1.0.6

func (RevokedTokenType) TableName() string

TableName specifies the table name for RevokedTokenType Override GORM's default pluralization for consistent naming

func (RotatedTokenType) TableName ¶ added in v1.0.6

func (RotatedTokenType) TableName() string

TableName specifies the table name for RotatedTokenType Override GORM's default pluralization for consistent naming