auth_rails 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c69df81c88cacdf202e2c49cf329423ded23e509fc2dc67fd60d07fda1fbe12e
-  data.tar.gz: abbad690e4211d181950af7bf542e2df367b79c0c79c049f32c5192188106f4f
+  metadata.gz: 15e71bc7d2e92cc25d3433db5adbd5608f70c5fbf9de27a234106d95d54d9957
+  data.tar.gz: cfab483acafa215d5530e8ec90904cdceadb55bb53074b69ad73c2ef756ab7ca
 SHA512:
-  metadata.gz: b97b6c42ed2386b526ce58bbc9e8fd2982e7b60357adebfb0c547f3b3cbf6d07f6cbca8e4cf13871a42f69935ae09daf2dc7528563dd024dcc95dc95e8611f5a
-  data.tar.gz: 758425cb02330e2efd68fedc8730e4b8879136098f0ecfb1d9543812e8220fdbc51f8ec1eaa15c19a09d17e29788c4968969121e08c9a6cf922a2ea4b60e005e
+  metadata.gz: 92bbbfb5274f625b03f8879d9b5cf3f6e61d577a8c30e53bda9cd374e74b46fc821717c7bac9f116502d64f5f1fb55571cd424d0583de3a4b260726c0d4c5ffc
+  data.tar.gz: c4479a4db819b2ba649fed888c074185c751ffbccb71ba4278c9747c01adb9cb3bcf8e0db5eb47c3db60d7b015cb37bb64c4d4c63cb77bab869a4a0ef45d9da2

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

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