Tokenzen

Tokenzen is a lightweight, model-agnostic token authentication toolkit for Rails.

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

Tokenzen is designed to be: - Model agnostic - Multi-model compatible - Cache-backed and scalable - Configurable - Lightweight - Easy to integrate

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

- Works with any model (Admin, Customer, Account, etc.)
- Access and refresh token generation
- Token revocation (logout)
- Multi-device support
- Automatic token rotation on refresh token change
- Token validation
- Refresh access token using refresh token
- Configurable expiration
- AES-256 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.

Example:

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 generates secure encrypted tokens and stores them in cache with separate expiries.

======================================== LOGIN / VALIDATE TOKENS

Use the class-level login method to validate a token pair:

record = Admin.login(tokens[:access_token], tokens[:refresh_token])
# returns Admin instance if valid, nil if invalid

You can also validate token pair from an instance:

valid = admin.validate_tokens(tokens[:access_token])
# => ActiveRecord or nil

======================================== REFRESH ACCESS TOKEN

Use the refresh token to generate a new access token:

new_tokens = Admin.refresh_access(tokens[:refresh_token])
# returns { access_token: "...", refresh_token: "..." }

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

admin.logout
# 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.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 token is issued:

- A secure random key is generated for access and refresh tokens.
- Tokens are stored in cache along with model name and record ID.
- Tokens are encrypted using AES-256.
- Tokens are tracked per record for easy revocation.

Stored payload example:

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

This allows Tokenzen to work with any ActiveRecord model automatically.

======================================== TOKEN ROTATION

If your model includes:

- refresh_token
- password_digest

Tokenzen will automatically:

- Rotate the refresh token when password changes
- Clear all access tokens when refresh token changes

This behavior is optional and safely guarded.

======================================== 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 are encrypted using AES-256
- Tokens are stored in cache (Redis recommended)
- Tokens are namespaced per model
- Clearing tokens invalidates all sessions instantly

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

- Controller helpers (current_resource)
- Rack middleware
- Stateless JWT mode
- Device/session tracking
- Revokable single-session tokens
- OAuth support

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

Bug reports and pull requests are welcome at:

https://github.com/stndrk/tokenzen

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

Tokenzen is released under the MIT License.

tokenzen

Runtime