auth_rails 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a80fe0179e20db84cc1966bd18331d98b3172c4cd5c3b652949ef7bc7a508b0a
-  data.tar.gz: 6cc51206c4381735dd92f118c8268df20998739cad769bcd2e01211dabb20e76
+  metadata.gz: 15e71bc7d2e92cc25d3433db5adbd5608f70c5fbf9de27a234106d95d54d9957
+  data.tar.gz: cfab483acafa215d5530e8ec90904cdceadb55bb53074b69ad73c2ef756ab7ca
 SHA512:
-  metadata.gz: e7d2ccb1bbd06e8cf115267a998cd0490ac8e9583e5a351ca61c486d0ceafd26fda66eee7995a84e01dd4dd82ed29fa29c4af865cbf2f232b445a48bd6d0bc86
-  data.tar.gz: 7a2057151c16ea45d74eb88f9a501a232f5e714a713a22dc125b56fbb6f9710c0b02dd39d9364af8ab7a54e002b8cc511d95389d0d1467050470b970f2814ab1
+  metadata.gz: 92bbbfb5274f625b03f8879d9b5cf3f6e61d577a8c30e53bda9cd374e74b46fc821717c7bac9f116502d64f5f1fb55571cd424d0583de3a4b260726c0d4c5ffc
+  data.tar.gz: c4479a4db819b2ba649fed888c074185c751ffbccb71ba4278c9747c01adb9cb3bcf8e0db5eb47c3db60d7b015cb37bb64c4d4c63cb77bab869a4a0ef45d9da2

data/README.md

@@ -165,6 +165,50 @@ module Api
 end
 ```
 
+- In case your identifier is not email
+
+```rb
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User # required
+    config.identifier_name = :username # must be string or symbol, default is email
+  end
+end
+```
+
+- If you have a custom method to validate password
+
+```rb
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User # required
+    config.identifier_name = :username # must be string or symbol, default is email
+    config.authenticate = ->(resource, password) { resource.password == password } # must be a proc, validate password
+  end
+end
+```
+
+- Sometimes, you have a complex logic to get the user
+
+```rb
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User # required
+    config.identifier_name = :username # this one is sub in jwt
+    config.dig_params = ->(params) { params[:identifier] } # must be a proc, how to get identifier from params
+
+    # how to get user from identifier
+    # identifier default is params[<identifier_name>]
+    # or extract from dig_params
+    config.retrieve_resource = lambda { |identifier|
+      User.where(email: identifier)
+          .or(User.where(username: identifier))
+          .first
+    }
+  end
+end
+```
+
 # Strategy list
 
 - allowed_token

data/app/controllers/auth_rails/api/auth_controller.rb

@@ -4,9 +4,9 @@ module AuthRails
   module Api
     class AuthController < ApiController
       def create
-        resource = AuthRails.resource_class.find_by(email: params[:email])
+        resource = AuthRails.retrieve_resource(params: params)
 
-        raise AuthRails.error_class, :unauthenticated if resource.blank? || !resource.authenticate(params[:password])
+        raise AuthRails.error_class, :unauthenticated if resource.blank? || !AuthRails.authenticate(resource: resource, password: params[:password])
 
         respond_to_create(generate_token(resource))
       end
@@ -43,7 +43,7 @@ module AuthRails
 
       def payload(resource)
         {
-          sub: resource.email
+          sub: resource.send(AuthRails.identifier_name)
         }
       end
 

data/app/controllers/concerns/auth_rails/authentication.rb

@@ -10,7 +10,7 @@ module AuthRails
         secret_key: Configuration::Jwt::AccessToken.secret_key
       )
 
-      CurrentAuth.user = AuthRails.resource_class.find_by(email: payload[:sub])
+      CurrentAuth.user = AuthRails.resource_class.find_by(AuthRails.identifier_name => payload[:sub])
 
       raise AuthRails.error_class, :unauthenticated unless CurrentAuth.user
     end

data/auth_rails.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
             .git
             .circleci
             appveyor
+            examples/
             Gemfile
             .rubocop.yml
             .vscode/settings.json

data/biome.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.4.1/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "useArrowFunction": "off"
+      },
+      "style": {
+        "noParameterAssign": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "indentStyle": "space",
+      "quoteStyle": "single"
+    }
+  }
+}

data/docs/.vitepress/config.mts

@@ -0,0 +1,90 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'AuthRails',
+  description: 'Simple authentication for Rails',
+  srcDir: './src',
+  base: '/auth_rails/',
+  themeConfig: {
+    nav: [
+      {
+        text: 'Guide',
+        link: '/introduction/what-is-it',
+      },
+    ],
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          {
+            text: 'What is AuthRails?',
+            link: '/introduction/what-is-it',
+          },
+          {
+            text: 'Getting Started',
+            link: '/introduction/getting-started',
+          },
+        ],
+      },
+      {
+        text: 'CLI',
+        items: [
+          {
+            text: 'Configuration',
+            link: '/cli/configuration',
+          },
+          {
+            text: 'Migration',
+            link: '/cli/migration',
+          },
+        ],
+      },
+      {
+        text: 'Customization',
+        items: [
+          {
+            text: 'Custom Strategy',
+            link: '/customization/custom-strategy',
+          },
+          {
+            text: 'Custom Response Data',
+            link: '/customization/custom-response',
+          },
+          {
+            text: 'Custom Password Validation',
+            link: '/customization/custom-password-validation',
+          },
+          {
+            text: 'Custom Identifier Column',
+            link: '/customization/custom-identifier',
+          },
+          {
+            text: 'Complex Retrieve Resource',
+            link: '/customization/complex-retrieve-resource',
+          },
+        ],
+      },
+      {
+        text: 'API Reference',
+        link: '/api-reference',
+      },
+    ],
+    outline: {
+      level: [2, 3],
+      label: 'On this page',
+    },
+    lastUpdated: {
+      text: 'Last updated',
+      formatOptions: {
+        dateStyle: 'full',
+        timeStyle: 'medium',
+      },
+    },
+    socialLinks: [
+      {
+        icon: 'github',
+        link: 'https://github.com/zgid123/auth_rails',
+      },
+    ],
+  },
+});

data/docs/src/api-reference.md

@@ -0,0 +1,362 @@
+# API Reference
+
+All features of AuthRails.
+
+## Configuration
+
+### dig_params
+
+- Type: `Proc`
+- Default: `nil`
+- Required: `false`
+
+Method to extract `identifier` for [`retrieve_resource`](/api-reference.html#retrieve-resource).
+
+```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
+```
+
+`identifier_name` will be used for JWT's payload's `sub` if you have `dig_params` configuration.
+
+### error_class
+
+- Type: `Class`
+- Default: `nil`
+- Required: `false`
+
+Custom error class for AuthRails.
+
+Whenever AuthRails raises error, it will raise your error.
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+    config.error_class = YourError
+  end
+end
+```
+
+### authenticate
+
+- Type: `Proc`
+- Default: `nil`
+- Required: `false`
+
+Custom method to validate your user password. If not provided, you must add `has_secure_password` to your model. Or create a method called `authenticate` to do the validation for your model. Or else it will raise error.
+
+```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
+```
+
+### resource_class
+
+- Type: `Class`
+- Default: `nil`
+- Required: `true`
+
+Your own class to do sign in. Usually it is `User`.
+
+```rb
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  AuthRails.configure do |config|
+    config.resource_class = User
+  end
+end
+```
+
+### identifier_name
+
+- Type: `String` | `Symbol`
+- Default: `:email`
+- Required: `false`
+
+Your resource class identifier.
+
+```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
+```
+
+### retrieve_resource
+
+- Type: `Proc`
+- Default: `nil`
+- Required: `false`
+
+Method to custom how to get resource when your project requires a complex logic.
+
+```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 is used for JWT's payload's `sub`.
+
+#### config.dig_params
+
+This extracts `identifier` from parameters for the provided method.
+
+## JWT Configuration
+
+### jwt.strategy
+
+- Type: `Class`
+- Default: `AuthRails::Strategies::BaseStrategy`
+- Required: `false`
+
+Specify which strategy to handle `refresh_token`.
+
+```rb
+# frozen_string_literal: true
+
+class YourOwnStrategy < AuthRails::Strategies::BaseStrategy
+end
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = YourOwnStrategy
+  end
+end
+```
+
+## JWT Access Token Configuration
+
+### access_token.exp
+
+- Type: `ActiveSupport::TimeWithZone`
+- Default: `nil`
+- Required: `false`
+
+Expiry time for `access_token`.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+    end
+  end
+end
+```
+
+### access_token.algorithm
+
+- Type: `string`
+- Default: `HS256`
+- Required: `false`
+
+Algorithm for JWT generator.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+      access_token.algorithm = 'HS384'
+    end
+  end
+end
+```
+
+### access_token.secret_key
+
+- Type: `string`
+- Default: `nil`
+- Required: `false`
+
+Secret token for JWT generator.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.access_token do |access_token|
+      access_token.exp = 1.hour.since
+      access_token.algorithm = 'HS384'
+      access_token.secret_key = 'My Secret Key'
+    end
+  end
+end
+```
+
+## JWT Refresh Token Configuration
+
+### refresh_token.exp
+
+- Type: `ActiveSupport::TimeWithZone`
+- Default: `nil`
+- Required: `false`
+
+Expiry time for `refresh_token`.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.refresh_token do |refresh_token|
+      refresh_token.exp = 1.hour.since
+    end
+  end
+end
+```
+
+### refresh_token.algorithm
+
+- Type: `string`
+- Default: `nil`
+- Required: `false`
+
+Algorithm for JWT generator.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.refresh_token do |refresh_token|
+      refresh_token.exp = 1.hour.since
+      refresh_token.algorithm = 'HS384'
+    end
+  end
+end
+```
+
+### refresh_token.secret_key
+
+- Type: `string`
+- Default: `nil`
+- Required: `false`
+
+Secret token for JWT generator.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.refresh_token do |refresh_token|
+      refresh_token.exp = 1.hour.since
+      refresh_token.algorithm = 'HS384'
+      refresh_token.secret_key = 'My Secret Key'
+    end
+  end
+end
+```
+
+### refresh_token.http_only
+
+- Type: `boolean`
+- Default: `false`
+- Required: `false`
+
+If true, before respond the `refresh_token`, AuthRails will set `refresh_token` as `httpOnly` cookie.
+
+Cookie key will be `ref_tok`.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.refresh_token do |refresh_token|
+      refresh_token.http_only = true
+      refresh_token.exp = 1.hour.since
+      refresh_token.algorithm = 'HS384'
+      refresh_token.secret_key = 'My Secret Key'
+    end
+  end
+end
+```
+
+### refresh_token.cookie_key
+
+- Type: `String` | `Symbol`
+- Default: `false`
+- Required: `false`
+
+Set cookie key for AuthRails when [`refresh_token.http_only`](/api-reference.html#refresh-token-http-only) is enabled.
+
+```rb
+# frozen_string_literal: true
+
+AuthRails.configure do |config|
+  config.jwt do |jwt|
+    jwt.strategy = AuthRails::Strategies::AllowedTokenStrategy
+
+    jwt.refresh_token do |refresh_token|
+      refresh_token.http_only = true
+      refresh_token.exp = 1.hour.since
+      refresh_token.algorithm = 'HS384'
+      refresh_token.cookie_key = :my_ref_tok
+      refresh_token.secret_key = 'My Secret Key'
+    end
+  end
+end
+```