auth_rails 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c69df81c88cacdf202e2c49cf329423ded23e509fc2dc67fd60d07fda1fbe12e
-  data.tar.gz: abbad690e4211d181950af7bf542e2df367b79c0c79c049f32c5192188106f4f
+  metadata.gz: ec319ee060ab65bae9b8352f0273020bce76b16b747c7fd0563d4469f493fa7f
+  data.tar.gz: 8ff6a24a175f38e3e7faad76c129889d56607710a1371af678cdd41a6e592e34
 SHA512:
-  metadata.gz: b97b6c42ed2386b526ce58bbc9e8fd2982e7b60357adebfb0c547f3b3cbf6d07f6cbca8e4cf13871a42f69935ae09daf2dc7528563dd024dcc95dc95e8611f5a
-  data.tar.gz: 758425cb02330e2efd68fedc8730e4b8879136098f0ecfb1d9543812e8220fdbc51f8ec1eaa15c19a09d17e29788c4968969121e08c9a6cf922a2ea4b60e005e
+  metadata.gz: 68f21b701758b484019f1ecee6b5b7cf69e038793eb2adfc30c7c288f27818c83714c217988286afbcc010d26ad9a0e716d0221d13861544de536c90839a2f06
+  data.tar.gz: 7c807efb6163c2c8ab27ed168e10565495ef2f4bcc7cd288428795722b73fa7cec64fd44b84160ee61158d97b60efd07dd01e7bf95a58bdf71d4a766a38739c4

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

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

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,94 @@
+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',
+      },
+      {
+        text: 'Changelogs',
+        link: '/changelogs',
+      },
+    ],
+    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
+```

data/docs/src/changelogs.md

@@ -0,0 +1,22 @@
+# Changelogs
+
+## v1.1.1
+
+add optional chaning when `identifier_name` is not provided from config
+
+**Full Changelog**: https://github.com/zgid123/auth_rails/compare/v1.1.0...v1.1.1
+
+## v1.1.0
+
+- allow custom identifier column and validate password method
+- allow custom `retrieve_resource` method
+
+**Full Changelog**: https://github.com/zgid123/auth_rails/compare/v1.0.2...v1.1.0
+
+## v1.0.2
+
+- require `jwt` inside gem
+- remove `allowed_token` when doing refresh for api controller
+- create generator for configuration and migration for `allowed_token` strategy
+
+**Full Changelog**: https://github.com/zgid123/auth_rails/compare/v1.0.0...v1.0.2

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
+```