tokenzen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f4dde7ef56bd6c8ed1d4b23b43f4256b17dfce96f9a0b8a0272e294db5fbf30
+  data.tar.gz: c8fbddcc5c83663e8635063fc67dd0d48b085166ce1c8b8f13f3f5c01266bbe5
+SHA512:
+  metadata.gz: 13f223728ffc56a0609a1834b09c1e1bb4b5dc0d6d4a7a426a221d9d42bd316a52cea0135ef11d9430943057ae43ec67c2b5e8c98a624a624e3209e9b389100e
+  data.tar.gz: 4b38a201f3a87dd92e0c8c68d4eed112ff497f960c10cab5ebea806843e430b21d1c93f85247974649956bd8915701d1971c96ad442e9d461af19b928a367adb

data/README.md

@@ -0,0 +1,210 @@
+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.

data/lib/tokenzen/authenticatable.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Tokenzen
+  module Authenticatable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def tokenzen(options = {})
+        include Tokenzen::Authenticatable::InstanceMethods
+
+        class_attribute :tokenzen_options
+        self.tokenzen_options = options
+
+        before_save :_tokenzen_rotate_refresh_token
+        around_save :_tokenzen_handle_refresh_rotation
+        after_destroy :_tokenzen_clear_tokens
+      end
+    end
+
+    module InstanceMethods
+      attr_reader :current_access_token, :current_refresh_token
+
+      # Generate access + refresh token
+      def generate_tokens(access_expiry: nil, refresh_expiry: nil)
+        tokens = TokenStore.issue_tokens(self, access_expiry: access_expiry, refresh_expiry: refresh_expiry)
+        @current_access_token = tokens[:access_token]
+        @current_refresh_token = tokens[:refresh_token]
+        tokens
+      end
+
+      # Logout: clear all tokens
+      def logout
+        clear_all_access_tokens
+      end
+
+      # Clear all tokens
+      def clear_all_access_tokens
+        TokenStore.clear_tokens(self)
+        @current_access_token = nil
+        @current_refresh_token = nil
+      end
+
+      # Validate tokens for this record
+      def validate_tokens(access_token)
+        TokenStore.fetch_record_from_access(access_token)
+      end
+
+      # =============================
+      # Class-level login using token pair
+      # =============================
+      #
+      # Returns the record if tokens valid, else nil
+      #
+      def self.login(access_token, refresh_token = nil)
+        record = TokenStore.fetch_record_from_access(access_token)
+        return nil unless record
+
+        if refresh_token
+          refresh_record = TokenStore.fetch_record_from_refresh(refresh_token)
+          return nil unless refresh_record == record
+        end
+
+        record
+      end
+
+      # Refresh access token using refresh token
+      def self.refresh_access(refresh_token)
+        TokenStore.refresh_access_token(refresh_token)
+      end
+
+      private
+
+      def _tokenzen_rotate_refresh_token
+        return unless respond_to?(:password_digest_changed?) && password_digest_changed?
+        self.refresh_token = JwtProcessor.encode(model: self.class.name, id: id) if respond_to?(:refresh_token=)
+      end
+
+      def _tokenzen_handle_refresh_rotation
+        changed = respond_to?(:refresh_token_changed?) && refresh_token_changed?
+        yield
+        return unless changed
+        clear_all_access_tokens
+        generate_tokens
+      end
+
+      def _tokenzen_clear_tokens
+        clear_all_access_tokens
+      end
+    end
+  end
+end

data/lib/tokenzen/configuration.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/message_encryptor"
+require "active_support/key_generator"
+
+module Tokenzen
+  class Configuration
+    attr_accessor :cache_store,
+                  :access_token_expiry,
+                  :refresh_token_expiry,
+                  :secret_key
+
+    def initialize
+      @cache_store = Rails.cache
+      @access_token_expiry = 2.days
+      @refresh_token_expiry = 2.months
+
+      @secret_key = default_secret_key
+    end
+
+    # Public encrypt method
+    def encrypt(value)
+      message_encryptor.encrypt_and_sign(value)
+    end
+
+    # Public decrypt method
+    def decrypt(value)
+      message_encryptor.decrypt_and_verify(value)
+    end
+
+    private
+
+    def message_encryptor
+      @message_encryptor ||= begin
+        key_len = ActiveSupport::MessageEncryptor.key_len
+        generator = ActiveSupport::KeyGenerator.new(@secret_key)
+        key = generator.generate_key("tokenzen", key_len)
+
+        ActiveSupport::MessageEncryptor.new(key)
+      end
+    end
+
+    def default_secret_key
+      if defined?(Rails) && Rails.application.respond_to?(:secret_key_base)
+        Rails.application.secret_key_base
+      else
+        ENV["TOKENZEN_SECRET_KEY"] || raise("TOKENZEN_SECRET_KEY not set in ENV and Rails.secret_key_base not found")
+      end
+    end
+  end
+end

data/lib/tokenzen/model.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tokenzen
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      attr_reader :current_access_token
+
+      before_save :renew_refresh_token_on_password_change
+      around_save :handle_refresh_token_rotation
+      after_destroy :clear_all_access_tokens
+    end
+
+    # PUBLIC API
+    def generate_access_token
+      token = Tokenzen::TokenStore.write(id)
+      return unless token
+
+      Tokenzen::TokenStore.store_user_token(id, token)
+      @current_access_token = token
+    end
+
+    def clear_all_access_tokens
+      Tokenzen::TokenStore.clear_user_tokens(id)
+      @current_access_token = nil
+    end
+
+    private
+
+    def renew_refresh_token_on_password_change
+      return unless respond_to?(:password_digest_changed?) && password_digest_changed?
+
+      self.refresh_token = JwtProcessor.encode(id: id)
+    end
+
+    def handle_refresh_token_rotation
+      changed = respond_to?(:refresh_token_changed?) && refresh_token_changed?
+      yield
+      return unless changed
+
+      clear_all_access_tokens
+      generate_access_token
+    end
+  end
+end

data/lib/tokenzen/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tokenzen
+  class Railtie < Rails::Railtie
+    initializer "tokenzen.initialize" do
+      Tokenzen.configuration ||= Tokenzen::Configuration.new
+    end
+  end
+end

data/lib/tokenzen/token_store.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Tokenzen
+  class TokenStore
+    class << self
+
+      # Generate both tokens and store in cache
+      def issue_tokens(record, access_expiry: nil, refresh_expiry: nil)
+        access_expiry ||= Tokenzen.configuration.access_token_expiry
+        refresh_expiry ||= Tokenzen.configuration.refresh_token_expiry
+
+        access_key = SecureRandom.hex(32)
+        refresh_key = SecureRandom.hex(32)
+
+        access_payload = {
+          "model" => record.class.name,
+          "id" => record.id,
+          "type" => "access"
+        }
+
+        refresh_payload = {
+          "model" => record.class.name,
+          "id" => record.id,
+          "type" => "refresh"
+        }
+
+        cache.write(access_key, access_payload, expires_in: access_expiry)
+        cache.write(refresh_key, refresh_payload, expires_in: refresh_expiry)
+
+        register_token(record, access_key)
+        register_token(record, refresh_key)
+
+        {
+          access_token: encrypt(access_key),
+          refresh_token: encrypt(refresh_key)
+        }
+      end
+
+      # Fetch record using access token
+      def fetch_record_from_access(token)
+        raw_key = decrypt(token)
+        payload = cache.read(raw_key)
+        return nil unless payload && payload["type"] == "access"
+
+        payload["model"].constantize.find_by(id: payload["id"])
+      end
+
+      # Fetch record using refresh token
+      def fetch_record_from_refresh(token)
+        raw_key = decrypt(token)
+        payload = cache.read(raw_key)
+        return nil unless payload && payload["type"] == "refresh"
+
+        payload["model"].constantize.find_by(id: payload["id"])
+      end
+
+      # Refresh access token using refresh token
+      def refresh_access_token(refresh_token)
+        record = fetch_record_from_refresh(refresh_token)
+        return unless record
+
+        tokens = issue_tokens(record)
+        clear_tokens(record) # clear old tokens
+        tokens
+      end
+
+      # Clear all tokens for a record
+      def clear_tokens(record)
+        tokens_for(record).each { |key| cache.delete(key) }
+        cache.write(register_key(record), [], expires_in: Tokenzen.configuration.refresh_token_expiry)
+      end
+
+      private
+
+      def register_token(record, raw_key)
+        list = tokens_for(record)
+        list << raw_key
+        cache.write(register_key(record), list, expires_in: Tokenzen.configuration.refresh_token_expiry)
+      end
+
+      def tokens_for(record)
+        cache.read(register_key(record)) || []
+      end
+
+      def register_key(record)
+        "tokenzen:#{record.class.name}:#{record.id}:tokens"
+      end
+
+      def cache
+        Tokenzen.configuration.cache_store
+      end
+
+      def encrypt(value)
+        Tokenzen.configuration.encrypt(value)
+      end
+
+      def decrypt(value)
+        Tokenzen.configuration.decrypt(value)
+      end
+    end
+  end
+end

data/lib/tokenzen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tokenzen
+  VERSION = "0.1.0"
+end

data/lib/tokenzen.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "tokenzen/version"
+require_relative "tokenzen/configuration"
+require_relative "tokenzen/token_store"
+require_relative "tokenzen/authenticatable"
+require_relative "tokenzen/railtie"
+
+module Tokenzen
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: tokenzen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Satendra
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Tokenzen is a lightweight, model-agnostic authentication toolkit for
+  Rails. It provides secure, polymorphic access token management for any ActiveRecord
+  model with configurable expiration, AES-256 encryption, login, logout, and refresh
+  token rotation.
+email:
+- satendra.km@alumni.iitd.ac.in
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/tokenzen.rb
+- lib/tokenzen/authenticatable.rb
+- lib/tokenzen/configuration.rb
+- lib/tokenzen/model.rb
+- lib/tokenzen/railtie.rb
+- lib/tokenzen/token_store.rb
+- lib/tokenzen/version.rb
+homepage: https://github.com/stndrk/tokenzen
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/stndrk/tokenzen
+  source_code_uri: https://github.com/stndrk/tokenzen
+  changelog_uri: https://github.com/stndrk/tokenzen/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/stndrk/tokenzen/issues
+  documentation_uri: https://github.com/stndrk/tokenzen#readme
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: Model-agnostic token authentication for Rails
+test_files: []