auth_rails 1.0.2 → 1.1.1

data/docs/src/cli/configuration.md

@@ -0,0 +1,152 @@
+# CLI to generate Configuration
+
+## Default Option
+
+```sh
+rails g auth_rails
+```
+
+This will create a default configuration for AuthRails.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+      access_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    end
+
+    # jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    # if you wanna use refresh token
+    # uncomment those lines below
+    # jwt.refresh_token do |refresh_token|
+    #   refresh_token.http_only = true
+    #   refresh_token.exp = 1.year.since
+    #   refresh_token.algorithm = 'HS256'
+    #   refresh_token.cookie_key = :ref_tok
+    #   refresh_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    # end
+  end
+end
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+
+    # if you wanna use custom error classes
+    # uncomment code below
+    # config.error_class = AuthError
+  end
+end
+```
+
+## Strategy Option
+
+```sh
+rails g auth_rails --strategy allowed_token
+```
+
+This will create a configuration and enable strategy `AuthRails::Strategies::AlloedTokenStrategy` as default.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+      access_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    end
+
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    # remember uncomment those ones
+    jwt.refresh_token do |refresh_token|
+      refresh_token.http_only = true
+      refresh_token.exp = 1.year.since
+      refresh_token.algorithm = 'HS256'
+      refresh_token.cookie_key = :ref_tok
+      refresh_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    end
+  end
+end
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+
+    # if you wanna use custom error classes
+    # uncomment code below
+    # config.error_class = AuthError
+  end
+end
+```
+
+You must modify User model to make this works.
+
+```rb
+# app/models/user.rb
+# frozen_string_literal: true
+
+class User < ApplicationRecord
+  include AuthRails::Concerns::AllowedTokenStrategy
+
+  has_secure_password
+end
+```
+
+## Model Option
+
+```sh
+rails g auth_rails --model CustomUser
+```
+
+This will create a configuration with the `resource_class` as `CustomUser`.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+      access_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    end
+
+    # jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    # if you wanna use refresh token
+    # uncomment those lines below
+    # jwt.refresh_token do |refresh_token|
+    #   refresh_token.http_only = true
+    #   refresh_token.exp = 1.year.since
+    #   refresh_token.algorithm = 'HS256'
+    #   refresh_token.cookie_key = :ref_tok
+    #   refresh_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    # end
+  end
+end
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = CustomUser
+
+    # if you wanna use custom error classes
+    # uncomment code below
+    # config.error_class = AuthError
+  end
+end
+```
+
+Remember to modify the `CustomUser` class.
+
+```rb
+# frozen_string_literal: true
+
+class CustomUser < ApplicationRecord
+  has_secure_password
+end
+```

data/docs/src/cli/migration.md

@@ -0,0 +1,59 @@
+# CLI to generate Migration
+
+This CLI always need to provide a strategy option to know which migration file should be created.
+
+## Default Option
+
+```sh
+rails g auth_rails:migration --strategy allowed_token
+```
+
+This will create a migration file for `AllowedToken` model.
+
+```rb
+# frozen_string_literal: true
+
+class CreateAllowedTokens < ActiveRecord::Migration[7.1]
+  def change
+    create_table :allowed_tokens do |t|
+      t.string :jti, null: false
+      t.string :aud
+      t.datetime :exp, null: false
+
+      t.timestamps
+
+      t.references :user, foreign_key: { on_delete: :cascade }, null: false
+
+      t.index %i[jti aud]
+    end
+  end
+end
+```
+
+## Model Option
+
+```sh
+rails g auth_rails:migration --strategy allowed_token --model CustomUser
+```
+
+This will create a migration file for `AllowedToken` model and add reference with `CustomUser`.
+
+```rb
+# frozen_string_literal: true
+
+class CreateAllowedTokens < ActiveRecord::Migration[7.1]
+  def change
+    create_table :allowed_tokens do |t|
+      t.string :jti, null: false
+      t.string :aud
+      t.datetime :exp, null: false
+
+      t.timestamps
+
+      t.references :custom_user, foreign_key: { on_delete: :cascade }, null: false
+
+      t.index %i[jti aud]
+    end
+  end
+end
+```

data/docs/src/customization/complex-retrieve-resource.md

@@ -0,0 +1,33 @@
+# Custom retrieve resource
+
+Sometimes, your logic to retrieve user is too complex. It is not simple `User.find_by(email: identifier)`.
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+    config.identifier_name = :username
+    config.dig_params = ->(params) { params[:identifier] }
+
+    config.retrieve_resource = lambda { |identifier|
+      User.where(email: identifier)
+          .or(User.where(username: identifier))
+          .first
+    }
+  end
+end
+```
+
+## config.identifier_name
+
+This will be used to set to `sub` of JWT's `payload`.
+
+## config.dig_params
+
+To extract `identifier` for the `retrieve_resource` config.
+
+## config.retrieve_resource
+
+This is where you define how to get your resource to do the sign in.

data/docs/src/customization/custom-identifier.md

@@ -0,0 +1,16 @@
+# Custom your own identifier for your model
+
+My model does not use `email` as its `identifier`, how to make AuthRails works with my model?
+
+Tell AuthRails what it is.
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+    config.identifier_name = :username
+  end
+end
+```

data/docs/src/customization/custom-password-validation.md

@@ -0,0 +1,14 @@
+# Use your own validation password
+
+The method `authenticate` of `has_secure_password` is not good for you? Then make your own validation password.
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+    config.authenticate = ->(resource, password) { resource.password == password }
+  end
+end
+```

data/docs/src/customization/custom-response.md

@@ -0,0 +1,63 @@
+# Response your own data structure
+
+Not happy with the default response? Do not worry, you can override it easily.
+
+## Sign In Response
+
+To custom your sign in response data structure, you should override the method `respond_to_create`.
+
+```rb
+# frozen_string_literal: true
+
+module Api
+  class AuthController < AuthRails::Api::AuthController
+    private
+
+    def respond_to_create(data)
+      render json: {
+        profile: CurrentAuth.user,
+        tokens: {
+          auth_token: data[:access_token],
+          refresh_token: data[:refresh_token]
+        }
+      }
+    end
+  end
+end
+```
+
+If your response for refresh token action is the same, make this as its alias.
+
+```rb
+alias respond_to_refresh respond_to_create
+```
+
+## Refresh Response
+
+To custom your refresh action response data structure, you should override the method `respond_to_refresh`.
+
+```rb
+# frozen_string_literal: true
+
+module Api
+  class AuthController < AuthRails::Api::AuthController
+    private
+
+    def respond_to_refresh(data)
+      render json: {
+        profile: CurrentAuth.user,
+        tokens: {
+          auth_token: data[:access_token],
+          refresh_token: data[:refresh_token]
+        }
+      }
+    end
+  end
+end
+```
+
+In case your sign in action's response is the same, make this as its alias.
+
+```rb
+alias respond_to_create respond_to_refresh
+```

data/docs/src/customization/custom-strategy.md

@@ -0,0 +1,33 @@
+# Use your own strategy
+
+AuthRails provides a base strategy that has two methods: `retrieve_resource` and `gen_token`.
+
+In your project, you may need to handle `refresh_token` in another approach instead of `allowed_token`. You can inherit base strategy and override those two methods to do your own strategy.
+
+```rb
+# frozen_string_literal: true
+
+class YourOwnStrategy < AuthRails::Strategies::BaseStrategy
+  class << self
+    def retrieve_resource(payload:)
+      # handle payload and retrieve the user using that payload
+    end
+
+    def gen_token(resource:, payload:, exp: nil, secret_key: nil, algorithm: nil, jti: nil)
+      # handle how to generate refresh_token
+    end
+  end
+end
+```
+
+Next, add this class to the configuration.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = YourOwnStrategy
+  end
+end
+```

data/docs/src/index.md

@@ -0,0 +1,14 @@
+---
+layout: home
+
+hero:
+  name: AuthRails
+  tagline: Simple authentication for Rails
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /introduction/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/zgid123/auth_rails
+---

data/docs/src/introduction/getting-started.md

@@ -0,0 +1,111 @@
+# Getting Started
+
+## Installation
+
+```rb
+gem 'auth_rails'
+```
+
+## Configuration
+
+AuthRails provides a rake task to generate a configuration file.
+
+```sh
+rails g auth_rails
+```
+
+It will create a file `config/initializers/auth_rails.rb` with a default configuration.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+      access_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    end
+
+    # jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    # if you wanna use refresh token
+    # uncomment those lines below
+    # jwt.refresh_token do |refresh_token|
+    #   refresh_token.http_only = true
+    #   refresh_token.exp = 1.year.since
+    #   refresh_token.algorithm = 'HS256'
+    #   refresh_token.cookie_key = :ref_tok
+    #   refresh_token.secret_key = ENV.fetch('JWT_SECRET', '')
+    # end
+  end
+end
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+
+    # if you wanna use custom error classes
+    # uncomment code below
+    # config.error_class = AuthError
+  end
+end
+```
+
+> [!NOTE]
+> [Check here](/api-reference) to see full API.
+
+### access_token.exp
+
+Expires time for `access_token`.
+
+### access_token.secret_key
+
+Secret key for JWT when creating `access_token`.
+
+### config.resource_class
+
+User model in your application. Usually is `User`.
+
+## Modify User model
+
+AuthRails will use method `authenticate` from `has_secure_password` as default.
+
+```rb
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+end
+```
+
+## Use AuthRails' default controller
+
+Define a route for sign in controller.
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  namespace :api do
+    resource :auth, path: 'auth', controller: 'auth', only: %i[create] do
+      collection do
+        get :refresh
+      end
+    end
+  end
+end
+```
+
+Create a controller that is inherited from default controller.
+
+```rb
+# frozen_string_literal: true
+
+module Api
+  class AuthController < AuthRails::Api::AuthController
+  end
+end
+```
+
+Now you can sign in using `POST: /api/auth` and refresh the token using `GET: /api/auth/refresh`.
+
+Access current user as anytime using `CurrentAuth.user`.

data/docs/src/introduction/what-is-it.md

@@ -0,0 +1,21 @@
+# Introduction
+
+AuthRails provides a simple authentication API for Ruby on Rails application.
+
+## Features
+
+### API Controller to Sign In User
+
+AuthRails provides a default controller to do sign in for your user using JWT.
+
+This controller will generate `access_token` to verify user for their next access and `refresh_token` to re-generate `access_token` when it is expired.
+
+### Allowed Token Strategy
+
+Allowed Token Strategy will store the `refresh_token` to the database. Only those valid tokens can be used to re-generate `access_token`.
+
+Whenever the `refresh_token` is used, it will be deleted and new `refresh_token` is stored in the database.
+
+## Alternative
+
+- [devise](https://github.com/heartcombo/devise)

data/lib/auth_rails/class_methods.rb

@@ -14,6 +14,10 @@ module AuthRails
       @resource_class ||= Config.resource_class
     end
 
+    def identifier_name
+      @identifier_name ||= Config.identifier_name&.to_sym || :email
+    end
+
     def error_class
       @error_class ||= Config.error_class || Error
     end
@@ -21,5 +25,45 @@ module AuthRails
     def jwt_strategy
       @jwt_strategy ||= Configuration::Jwt.strategy || Strategies::BaseStrategy
     end
+
+    def authenticate(resource:, password:)
+      if Config.authenticate.present?
+        raise_if_not_proc(Config.authenticate, 'Config.authenticate')
+
+        Config.authenticate.call(resource, password)
+      else
+        raise 'Don\'t know how to authenticate resource with password' unless resource.respond_to?(:authenticate)
+
+        resource.authenticate(password)
+      end
+    end
+
+    def dig_params(params:)
+      if Config.dig_params.present?
+        raise_if_not_proc(Config.dig_params, 'Config.dig_params')
+
+        Config.dig_params.call(params)
+      else
+        params[AuthRails.identifier_name]
+      end
+    end
+
+    def retrieve_resource(params:)
+      identifier = dig_params(params: params)
+
+      if Config.retrieve_resource.present?
+        raise_if_not_proc(Config.retrieve_resource, 'Config.retrieve_resource')
+
+        return Config.retrieve_resource.call(identifier)
+      end
+
+      AuthRails.resource_class.find_by(AuthRails.identifier_name => identifier)
+    end
+
+    private
+
+    def raise_if_not_proc(source, name)
+      raise "#{name} must be a Proc" unless source.is_a?(Proc)
+    end
   end
 end

data/lib/auth_rails/config.rb

@@ -3,8 +3,12 @@
 module AuthRails
   class Config
     class << self
-      attr_accessor :error_class,
-                    :resource_class
+      attr_accessor :dig_params,
+                    :error_class,
+                    :authenticate,
+                    :resource_class,
+                    :identifier_name,
+                    :retrieve_resource
 
       def jwt
         yield Configuration::Jwt

data/lib/auth_rails/strategies/allowed_token_strategy.rb

@@ -11,7 +11,7 @@ module AuthRails
                    .joins(:allowed_tokens)
                    .where(allowed_tokens: symbolized_payload.slice(:jti, :aud))
                    .where('allowed_tokens.exp > ?', Time.current)
-                   .find_by(email: symbolized_payload[:sub])
+                   .find_by(AuthRails.identifier_name => symbolized_payload[:sub])
         end
 
         def gen_token(resource:, payload:, exp: nil, secret_key: nil, algorithm: nil)

data/lib/auth_rails/strategies/base_strategy.rb

@@ -8,7 +8,7 @@ module AuthRails
           symbolized_payload = payload.symbolize_keys
 
           AuthRails.resource_class
-                   .find_by(email: symbolized_payload[:sub])
+                   .find_by(AuthRails.identifier_name => symbolized_payload[:sub])
         end
 
         def gen_token(payload:, exp: nil, secret_key: nil, algorithm: nil, jti: nil, **)

data/lib/auth_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AuthRails
-  VERSION = '1.0.2'
+  VERSION = '1.1.1'
 end

data/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "auth_rails",
+  "version": "1.0.0",
+  "author": "Alpha",
+  "license": "MIT",
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.5.3",
+    "typescript": "^5.3.3",
+    "vitepress": "1.0.0-rc.40"
+  }
+}