shieldify 0.1.2.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6517cc618765bddd3e12fae12071e15d5c1fce7caba98f48468b8997d7269d72
+  data.tar.gz: b62d7d9fd12ffbaa0dd40261925e537bbfe88dbcaafa40f54b2fb666b44c400d
+SHA512:
+  metadata.gz: cde0954c079bd2fa807002523e8f0b9d6fa929efef4c8c2154fb737625fa6c8e9a54041426718172e663f46cc664eb158f42fd3b2e783acdf3a7f375a7ec9394
+  data.tar.gz: 05e5de36f1b7344fbdd56610ad32b0169be7e9e57c4cbea03b32483a7f7972a220d7915fa024dbb1f298b4eac00204852df081a4f456cc7ccfd6bc45f2ccf4ac

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Armando Alejandre
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,375 @@
+# Shieldify
+
+![Gem Version](https://img.shields.io/gem/v/shieldify.svg)
+
+Shieldify is a Ruby on Rails user authentication plugin. It handles authentication through email and API authentication via JWT (JSON Web Tokens). The gem includes functionalities for user registration, email confirmation, and user authentication via email/password and JWT.
+
+## Features
+
+- **Authentication**:
+  - **Email Authentication**: Allows users to authenticate using their email and password, generating a JWT that is managed in a whitelist.
+  - **API Authentication with JWT**: Manages API authentication using JSON Web Tokens to secure requests.
+
+- **User Management**:
+  - **Email**:
+    - **Registration**: Facilitates new user registration and sends confirmation emails upon registration.
+    - **Confirmation**: Manages email address confirmation for user accounts through confirmation emails.
+
+## Installation
+
+To install the Shieldify gem, follow these steps:
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'shieldify'
+```
+
+Run `bundle install` to install the gem:
+
+```sh
+bundle install
+```
+
+Run the Shieldify install generator to set up the necessary files and configurations:
+
+```sh
+rails generate shieldify:install
+```
+
+### Install Generator Steps
+
+The `rails generate shieldify:install` command performs the following steps:
+
+1. **Copy Initializer**:
+    - **Description**: Copies the initializer file for Shieldify to the application's initializer directory.
+    - **Generated File**: `config/initializers/shieldify.rb`
+    - **Purpose**: This file is used to configure settings for Shieldify, such as JWT parameters, password complexity requirements, and other authentication-related settings.
+
+2. **Generate Migration**:
+    - **Description**: Creates a migration file to set up the users table with necessary fields for authentication.
+    - **Generated File**: `db/migrate/[timestamp]_shieldify_create_users.rb`
+    - **Purpose**: This migration creates the users table with fields like `email`, `password_digest`, `email_confirmation_token`, `email_confirmation_token_generated_at`, etc., which are essential for managing user authentication.
+
+3. **Generate Model**:
+    - **Description**: Generates the User model if it does not already exist.
+    - **Generated File**: `app/models/user.rb`
+    - **Purpose**: Defines the User model and includes necessary modules for email authentication, user registration, and email confirmation.
+
+4. **Inject Method**:
+    - **Description**: Injects the `shieldify` method call into the User model to include the necessary Shieldify modules.
+    - **Injected Code**: `shieldify email_authenticatable: %i[registerable confirmable]`
+    - **Purpose**: This call specifies which Shieldify modules should be included in the User model, enabling email authentication, user registration, and email confirmation functionalities.
+
+5. **Copy Mailer Layouts**:
+    - **Description**: Copies mailer layout files to the application's views directory.
+    - **Generated Directory**: `app/views/layouts/shieldify`
+    - **Purpose**: Provides the layout templates used for sending emails related to user authentication, such as confirmation emails and password reset emails.
+
+6. **Copy Mailer Views**:
+    - **Description**: Copies mailer view templates to the application's views directory.
+    - **Generated Directory**: `app/views/shieldify/mailer`
+    - **Purpose**: Provides the email templates used for various user authentication-related emails, including email confirmation instructions and email changed notification.
+
+7. **Copy Locale File**:
+    - **Description**: Copies the locale file to the application's locales directory.
+    - **Generated File**: `config/locales/en.shieldify.yml`
+    - **Purpose**: Contains translations for the messages and notifications used by Shieldify, ensuring that they are properly localized.
+
+### Final Steps
+
+Run the migrations to update your database schema:
+
+```sh
+rails db:migrate
+```
+
+Configure your mailer settings to ensure that confirmation emails are sent correctly. Update your environment configuration (e.g., `config/environments/development.rb`) with the appropriate settings.
+
+```ruby
+config.action_mailer.delivery_method = :smtp
+config.action_mailer.smtp_settings = {
+  address: 'smtp.example.com',
+  port: 587,
+  user_name: 'your_email@example.com',
+  password: 'your_password',
+  authentication: 'plain',
+  enable_starttls_auto: true
+}
+```
+
+That's it! You have successfully installed and configured the Shieldify gem in your Rails application.
+
+## Usage
+
+### Authentication
+
+#### Email and Password
+
+Authentication using email and password in this plugin provides a robust and secure way to verify users and generate JSON Web Tokens (JWT) for session management. This method leverages middleware and Warden strategies to seamlessly handle authentication requests. Below is a detailed overview of how this process works:
+
+- **Middleware and Warden Strategy**:
+  Authentication is processed through middleware that intercepts requests. If the request ends with `/shfy/login`, the Warden strategy is used to authenticate the user. If authentication is successful, a JWT is generated and sent in the response headers as `Authorization: Bearer <token>`.
+
+  - **Shieldify Middleware**:
+    The middleware intercepts requests to handle authentication based on the URL.
+
+  - **Warden Email Strategy**:
+    The Warden strategy validates the user's credentials (`email` and `password`) that have to come with the request and, if correct, generates a JWT and sends it in the response headers.
+
+- **Custom Response**:
+  In the controller (not generated by the plugin), you can return whatever you want in the body, customizing the response according to your needs.
+
+  ```ruby
+  render json: { message: 'Authenticated successfully', user: current_user }
+  ```
+
+##### Usage Example
+
+1. **Add the Route**:
+
+  ```ruby
+  # config/routes.rb
+  post '/shfy/login', to: 'sessions#create'
+  ```
+
+2. **Create the Controller that Handles the Login**:
+
+  ```ruby
+  # app/controllers/sessions_controller.rb
+  class SessionsController < ApplicationController
+    def create
+      # Authentication will be handled by Warden
+
+      # Custom Response
+      render json: { message: 'Authenticated successfully', user: current_user }
+    end
+  end
+  ```
+
+3. **Example Request using curl**:
+
+  ```sh
+  curl -X POST http://localhost:3000/shfy/login -d '{
+    "email": "user@example.com",
+    "password": "password"
+  }' -H "Content-Type: application/json"
+  ```
+
+With this setup, you can authenticate users using email and password, generate a JWT, and handle the response logic in your sessions controller or any controller.
+
+#### JSON Web Token (JWT)
+
+Authentication using JSON Web Tokens (JWT) in this plugin ensures secure and stateless user sessions. This method leverages middleware and Warden strategies to handle authentication requests seamlessly. Below is a detailed overview of how this process works:
+
+- **Middleware and Warden Strategy**:
+  Authentication is processed through middleware that intercepts requests containing a JWT in the `Authorization` header. If a valid JWT is present, the Warden strategy is used to authenticate the user.
+
+  - **Shieldify Middleware**:
+    The middleware intercepts requests to handle authentication based on the presence of the `Authorization` header.
+
+  - **Warden JWT Strategy**:
+    The Warden strategy extracts the JWT from the `Authorization` header, validates it, and authenticates the user if the token is valid.
+
+- **Protected Request**:
+  You can protect specific actions in your controllers by using a `before_action` filter that ensures the user is authenticated.
+
+  ```ruby
+  before_action :authenticate_user!
+  ```
+
+##### Usage Example
+
+1. **Protect Controller Action**:
+
+  ```ruby
+  # app/controllers/protected_controller.rb
+  class ProtectedController < ApplicationController
+    before_action :authenticate_user!
+
+    def index
+      render json: { message: 'You have accessed a protected resource' }
+    end
+  end
+  ```
+
+2. **Example Request using curl**:
+
+  ```sh
+  curl -X GET http://localhost:3000/protected_resource -H "Authorization: Bearer <your_jwt_token>"
+  ```
+
+With this setup, you can authenticate requests using JWTs, ensuring secure and stateless authentication in your Rails application.
+
+Tu documentación se ve excelente. Aquí está con algunas pequeñas correcciones para mejorar la claridad y el formato:
+
+## Controller Helpers
+
+The `Shieldify::Controllers::Helpers` module, which is already included in `ActionController::API`, provides several helper methods to manage user authentication within your controllers. Below is a detailed explanation of each method and how to use them:
+
+- **current_user**
+
+  This method returns the currently authenticated user based on the Warden strategy.
+
+  **Usage Example:**
+  ```ruby
+  # app/controllers/user_controller.rb
+  class UserController < ApplicationController
+    def index
+      user = current_user
+      render json: { user: user }
+    end
+  end
+  ```
+
+- **user_signed_in?**
+
+  This method checks if a user is currently signed in. It returns `true` if a user is signed in, otherwise `false`.
+
+  **Usage Example:**
+  ```ruby
+  # app/controllers/home_controller.rb
+  class HomeController < ApplicationController
+    def index
+      if user_signed_in?
+        render json: { message: 'User is signed in' }
+      else
+        render json: { message: 'User is not signed in' }
+      end
+    end
+  end
+  ```
+
+- **authenticate_user!**
+
+  This method ensures that a user is authenticated before accessing certain actions. If the user is not signed in, it responds with an unauthorized status.
+
+  **Usage Example:**
+  ```ruby
+  # app/controllers/protected_controller.rb
+  class ProtectedController < ApplicationController
+    before_action :authenticate_user!
+
+    def index
+      render json: { message: 'You have accessed a protected resource' }
+    end
+  end
+  ```
+
+With these helper methods, you can easily manage user authentication and access control in your Rails application.
+
+## Model Extensions
+
+### Email Authenticatable
+
+The `Shieldify::Models::EmailAuthenticatable` module provides email and password authentication functionality for users. It includes methods to authenticate users by their email and password, and uses `has_secure_password` for secure password handling.
+
+- **Email and Password Authentication**:
+  - Adds methods to set and authenticate against a BCrypt password.
+  - Requires a `password_digest` attribute.
+
+  **Usage Example**:
+  ```ruby
+  # app/models/user.rb
+  class User < ApplicationRecord
+    include Shieldify::Models::EmailAuthenticatable
+    # or
+    shieldify email_authenticatable: %i[]
+  end
+  ```
+
+  **Authenticate by Email**:
+  ```ruby
+  # Authenticate a user by email and password
+  user = User.authenticate_by_email(email: 'user@example.com', password: 'password')
+  if user.errors.any?
+    # Handle authentication failure
+  else
+    # Handle authentication success
+  end
+  ```
+
+#### Confirmable
+
+The `Shieldify::Models::EmailAuthenticatable::Confirmable` module implements email confirmation using tokens. It generates confirmation tokens when registering or changing a user's email address, enabling confirmation through a secure process. It includes functionality to automatically send confirmation instructions and manage email confirmations.
+
+- **Email Confirmation**:
+  - Generates confirmation tokens for email confirmation.
+  - Sends email confirmation instructions.
+  - Manages email confirmations and checks token expiration.
+
+  **Usage Example**:
+  ```ruby
+  # app/models/user.rb
+  class User < ApplicationRecord
+    include Shieldify::Models::EmailAuthenticatable::Confirmable
+    # or
+    shieldify email_authenticatable: %i[confirmable]
+  end
+  ```
+
+  **Confirm Email by Token**:
+  ```ruby
+  # Confirm a user's email by token
+  user = User.confirm_email_by_token('confirmation_token')
+  if user.errors.any?
+    # Handle confirmation failure
+  else
+    # Handle confirmation success
+  end
+  ```
+
+#### Registerable
+
+The `Shieldify::Models::EmailAuthenticatable::Registerable` module provides registration functionality for users, including email normalization, validation of email and password, and methods for registering a user and updating their email and password.
+
+- **User Registration**:
+  - Normalizes email before validation.
+  - Validates email format, uniqueness, and presence.
+  - Validates password complexity and minimum length.
+  - Provides methods to register a new user, update password, and update email.
+
+  **Usage Example**:
+  ```ruby
+  # app/models/user.rb
+  class User < ApplicationRecord
+    include Shieldify::Models::EmailAuthenticatable::Registerable
+    # or
+    shieldify email_authenticatable: %i[registerable]
+  end
+  ```
+
+  **Register a New User**:
+  ```ruby
+  # Register a new user
+  user = User.register(email: 'newuser@example.com', password: 'password', password_confirmation: 'password')
+  if user.errors.any?
+    # Handle registration failure
+  else
+    # Handle registration success
+  end
+  ```
+
+  **Update Password**:
+  ```ruby
+  # Update user's password
+  user.update_password(current_password: 'current_password', new_password: 'new_password', password_confirmation: 'new_password')
+  if user.errors.any?
+    # Handle password update failure
+  else
+    # Handle password update success
+  end
+  ```
+
+  **Update Email**:
+  ```ruby
+  # Update user's email
+  user.update_email(current_password: 'current_password', new_email: 'newemail@example.com')
+  if user.errors.any?
+    # Handle email update failure
+  else
+    # Handle email update success
+  end
+  ```
+
+With these modules, you can easily manage user authentication, email confirmation, and registration within your Rails application.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/controllers/users/access_controller.rb

@@ -0,0 +1,16 @@
+module Users
+  class AccessController < ActionController::Base
+    # GET /users/access/:token/unlock
+    def show
+      user = User.find_by(unlock_token: params[:token])
+
+      if user.present? && user.unlock_access
+        # Asume que `unlock_access` es un método en tu modelo User que realiza la lógica necesaria
+        # para desbloquear el acceso del usuario y limpiar el token de desbloqueo.
+        render json: { message: 'Tu cuenta ha sido desbloqueada exitosamente. Ahora puedes iniciar sesión.' }, status: :ok
+      else
+        render json: { error: 'El token proporcionado no es válido o ya ha sido utilizado.' }, status: :not_found
+      end
+    end
+  end
+end

data/app/controllers/users/emails/reset_passwords_controller.rb

@@ -0,0 +1,30 @@
+module Users
+  module Emails
+    class ResetPasswordsController < ActionController::Base
+      # POST /users/email/reset_password
+      def create
+        user = User.find_by(email: params[:email])
+
+        if user.present?
+          # Aquí se asume la existencia de un método que genera un token de restablecimiento
+          # de contraseña y envía un correo electrónico al usuario con instrucciones.
+          user.send_reset_email_password_instructions
+          render json: { message: 'Se ha enviado un correo con instrucciones para restablecer tu contraseña.' }, status: :ok
+        else
+          render json: { error: 'No se encontró un usuario con ese correo electrónico.' }, status: :not_found
+        end
+      end
+
+      # PUT /users/email/:token/reset_password
+      def update
+        user = User.find_by(reset_email_password_token: params[:token])
+
+        if user.present? && user.reset_password(params[:password], params[:password_confirmation])
+          render json: { message: 'Tu contraseña ha sido restablecida exitosamente.' }, status: :ok
+        else
+          render json: { error: 'El token no es válido o las contraseñas no coinciden.' }, status: :unprocessable_entity
+        end
+      end
+    end
+  end
+end

data/app/controllers/users/emails_controller.rb

@@ -0,0 +1,17 @@
+module Users
+  class EmailsController < ActionController::Base
+    def show
+      token = params[:token]
+      user = User.confirm_email_by_token(token)
+
+      if user.errors.blank?
+        render(
+          json: { message: I18n.t("shieldify.controllers.emails.confirmation.success_messages") },
+          status: :ok
+        )
+      else
+        render json: { errors: user.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/app/models/jwt_session.rb

@@ -0,0 +1,5 @@
+class JwtSession < ActiveRecord::Base
+  belongs_to :user
+
+  validates :jti, presence: true, uniqueness: true
+end

data/lib/generators/shieldify/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate initializer Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/shieldify/install_generator.rb

@@ -0,0 +1,52 @@
+module Shieldify
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    
+    source_root File.expand_path("templates", __dir__)
+
+    def copy_initializer
+      template 'initializer.rb', File.join("config", "initializers", "shieldify.rb")
+    end
+
+    def generate_migration
+      migration_template 'migration.rb', File.join("db", "migrate", "shieldify_create_users.rb"), migration_version: migration_version
+    end
+
+    def generate_model
+      template 'model.rb', File.join("app", "models", "user.rb")
+    end
+
+    def inject_method
+      inject_into_class File.join("app", "models", "user.rb"), :User, model_contents
+    end
+
+    def copy_mailer_layouts
+      directory File.join("mailer_layouts"), File.join("app", "views", "layouts", "shieldify")
+    end
+
+    def copy_mailer_views      
+      directory File.join("mailer_views"), File.join("app", "views", "shieldify", "mailer")
+    end
+
+    def copy_locale_file
+      template "locales/en.shieldify.yml", File.join("config", "locales", "en.shieldify.yml")
+    end
+
+    private
+
+    def model_contents
+      <<-CONTENT
+  shieldify email_authenticatable: %i[registerable confirmable]
+CONTENT
+    end
+
+    def migration_version
+      "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+    end
+
+    def self.next_migration_number(dirname)
+      next_migration_number = current_migration_number(dirname) + 1
+      ActiveRecord::Migration.next_migration_number(next_migration_number)
+    end
+  end
+end

data/lib/generators/shieldify/templates/initializer.rb.tt

@@ -0,0 +1,52 @@
+Shieldify.setup do |conf|
+  ## Mailer
+
+  # The parent mailer for internal mailers.
+  # The default value is "ActionMailer::Base", which sets the base class for all internal mailers.
+  # You can change this to another mailer class if your application requires a different base mailer.
+  # conf.parent_mailer = "ActionMailer::Base"
+
+  # The default email address used as the sender for outgoing emails.
+  # The default value is "shieldify@example.com", and it is necessary to change this to a valid email address for your application.
+  # conf.mailer_sender = "shieldify@example.com"
+
+  # The default email address used for the "Reply-To" field in outgoing emails.
+  # The default value is "shieldify@example.com", and it is necessary to change this to a valid email address for your application.
+  # conf.reply_to = "shieldify@example.com"
+
+  # Used to send notification to the original user email when their email is changed.
+  # The default value is true, and it is recommended to keep this enabled for security purposes.
+  # conf.send_email_changed_notification = false
+
+  # Used to enable sending notification to user when their password is changed.
+  # The default value is true, and it is recommended to keep this enabled for security purposes.
+  # conf.send_password_changed_notification = false
+
+  ## Password
+
+  # Password complexity regex.
+  # Explanation of the regular expression:
+  # - (?=.*\d) ensures there is at least one digit
+  # - (?=.*[a-z]) ensures there is at least one lowercase letter
+  # - (?=.*[A-Z]) ensures there is at least one uppercase letter
+  # - (?=.*[@$#!%*?&]) ensures there is at least one of these special characters
+  # - \S{8,} ensures the password is at least 8 characters in length and contains no spaces
+  # The default value enforces the above rules, ensuring a strong password policy.
+  # It is possible to change this regex to suit your application's specific requirements.
+  # conf.password_complexity = /[expression-here]/
+
+  # JWT Related Configuration
+
+  # The secret key used to encode and decode JWT tokens.
+  # The default value is "whatever", but it is highly recommended to change this to a strong,
+  # unique secret for your application.
+  # conf.jwt_secret = Rails.application.credentials.jwt_secret
+
+  # The issuer claim for the JWT tokens.
+  # The default value is "Shieldify". You can change this to match your application's name or domain.
+  # conf.jwt_issuer = "Shieldify"
+
+  # The expiration time for the JWT tokens in hours.
+  # The default value is 24 hours. You can adjust this to set the desired token validity period.
+  # conf.jwt_exp = 24.hours.from_now.to_i
+end

data/lib/generators/shieldify/templates/locales/en.shieldify.yml.tt

@@ -0,0 +1,58 @@
+en:
+  shieldify:
+    controllers:
+      emails:
+        confirmation:
+          success_messages: "Email successfully confirmed"
+    models:
+      email_authenticatable:
+        registerable:
+          password:
+            errors:
+              invalid: "invalid"
+          password_complexity:
+            format: It must include at least one uppercase letter, one lowercase letter, one number, and one special character (@$!%*?&)
+        confirmable:
+          email_confirmation_token:
+            errors:
+              invalid: "invalid"
+              expired: "has expired"
+          unconfirmed_email:
+            errors:
+              not_found: "not found"
+          email_confirmation_token_generated_at:
+    mailer:
+      email_confirmation_instructions:
+        subject: "Email Confirmation Instructions"
+        title: "Email Confirmation Instructions"
+        greeting: "Hello %{email},"
+        thanks: "Please confirm your email by clicking on the following link:"
+        confirm_account: "Confirm email"
+        ignore: "If you did not request this confirmation, please ignore this email."
+      reset_password_instructions:
+        subject: "Password Reset Instructions"
+        title: "Password Reset Instructions"
+        greeting: "Hello %{email},"
+        instructions: "Someone has requested a link to change your password. You can do this through the link below:"
+        change_password: "Change my password"
+        ignore: "If you didn't request this, please ignore this email. Your password will not change."
+        link_expiration: "This link will expire in %{expiration_hours} hours."
+      unlock_instructions:
+        subject: "Account Unlock Instructions"
+        title: "Account Unlock Instructions"
+        greeting: "Hello %{email},"
+        instructions: "Your account has been locked due to an excessive number of failed login attempts. Please unlock your account by clicking on the following link:"
+        unlock_account: "Unlock Account"
+        ignore: "If you did not request this, please ignore this email. Your account will remain secure."
+      email_changed:
+        subject: "Email Updated"
+        title: "Email Updated"
+        greeting: "Hello %{email},"
+        message: "We received a request to change the email address associated with your account to %{unconfirmed_email}."
+        ignore: "If you did not make this change, please contact support immediately."
+      password_changed:
+        subject: "Password Updated"
+        title: "Password Updated"
+        greeting: "Hello %{email},"
+        message: "This is a notification that your password has been successfully changed."
+        advice: "If you did not make this change, please contact our support team immediately."