Tokenzen

Tokenzen is a lightweight, session-based token authentication toolkit for Rails.

It provides secure, encrypted access + refresh token management for any ActiveRecord model — not just User.

Tokenzen is designed to be: - Model agnostic - Multi-model compatible - Multi-device aware - Session-limited - Secure refresh-rotation enabled - Cache-backed and scalable - Lightweight - Easy to integrate

======================================== FEATURES

- Works with any model (Admin, Customer, Account, etc.)
- Access + Refresh token generation
- Secure refresh token rotation (replay-safe)
- Multi-device login support
- Configurable max session limit
- Automatic session revocation on password change
- Logout from all devices
- Token validation via class-level API
- Configurable expiration
- AES-256-GCM encryption of tokens
- Rails auto-loading via Railtie

======================================== INSTALLATION

Add this to your application's Gemfile: gem "tokenzen"

Then run: bundle install

Or install manually: gem install tokenzen

======================================== BASIC USAGE

Include Tokenzen in any ActiveRecord model.

class Admin < ApplicationRecord
    include Tokenzen::Authenticatable
    tokenzen
end

You can use Tokenzen in multiple models at the same time:

class Customer < ApplicationRecord
    include Tokenzen::Authenticatable
    tokenzen
end

======================================== GENERATE ACCESS + REFRESH TOKEN

admin = Admin.first
tokens = admin.generate_tokens
    # tokens => { access_token: "...", refresh_token: "..." }

This: - Creates a new session - Enforces max session limit - Stores tokens in cache - Encrypts them using AES-256 - Returns encrypted tokens

======================================== AUTHENTICATE ACCESS TOKEN

You can also validate token pair from an instance:

admin = Admin.validate_token(access_token)
    # => Admin record or nil

======================================== REFRESH / ROTATE TOKENS

Use the refresh token to generate a new access token:

new_tokens = Admin.rotate_tokens(refresh_token)
    # returns { access_token: "...", refresh_token: "..." }

======================================== LOGOUT / CLEAR ALL TOKENS

admin.logout(access_token)-> delete current session
admin.logout_all
 # clears all access and refresh tokens for this record

======================================== CONFIGURATION

Create an initializer:

config/initializers/tokenzen.rb

Tokenzen.configure do |config|
    config.access_token_expiry  = 2.days
    config.refresh_token_expiry = 2.months
    config.max_sessions         = 3
    config.secret_key           = ENV["TOKENZEN_SECRET_KEY"] || Rails.application.secret_key_base
end

The gem automatically encrypts all tokens using AES-256 with this secret key.

======================================== HOW IT WORKS

When a user logs in: - A new session_id is created. - Secure random keys are generated for access + refresh tokens. - Tokens are stored in cache (Redis recommended). - Tokens are encrypted using AES-256-GCM. - Sessions are tracked per model record. - Oldest session is removed if max_sessions limit is reached.

Stored payload example:

{
    "model" => "Admin",
    "id"    => 1,
    "type"  => "access"   # or "refresh",
    "session_id" => "uuid"
}

This allows Tokenzen to work with any ActiveRecord model automatically.

======================================== SESSION MANAGEMENT

Tokenzen supports: - Multiple devices per user - Configurable max session limit - Automatic removal of oldest session when limit exceeded - Full session revocation

Example: If max_sessions = 3

Logging in from 4th device will revoke the oldest session.

======================================== PRODUCTION RECOMMENDATION

Use Redis as your cache store for production environments:

config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }

Redis provides better performance and scalability for token storage.

======================================== REQUIREMENTS

- Ruby >= 3.0.0
- Rails >= 6.0
- ActiveRecord-backed models

======================================== SECURITY NOTES

- Tokens encrypted using AES-256-GCM
- Refresh tokens rotate on use
- Old refresh tokens invalidated immediately
- Sessions revocable instantly
- No tokens stored in database
- No fingerprint/device binding required
- Replay attack resistant refresh flow

======================================== ROADMAP

- Per-device logout
- Session listing API
- Sliding expiration
- Controller helpers
- Rack middleware
- Optional JWT mode
- OAuth compatibility layer

======================================== CONTRIBUTING

Bug reports and pull requests are welcome at:

https://github.com/stndrk/tokenzen

======================================== LICENSE

Tokenzen is released under the MIT License.

tokenzen

Runtime