authpls 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb1f8ab6bd4cc603980ffa7f719a43f5df8396a1a1ef682bce1948483266bf71
+  data.tar.gz: 840873ee17ff22053532747c7c49f1e0191804890d40f7f70edda3d8f4d996e2
+SHA512:
+  metadata.gz: 778244f8ccad0b8f30e5ac9970a753b764a56a1bf88c860d83693dc41eebe6114209898fcdbad5b842cd4dc5326ac1a237a31c78691a22a6376980b18cda17bb
+  data.tar.gz: 33133d57aafcdc8db64f747154bfddc453c9030534fed089b3aed60dd114ef19e1255095ed320afcabbe1aceb1f14a6ced57c7c670e6b780c2c21ab5792b9962

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-04
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alex Locke
+
+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,53 @@
+# Authpls
+
+A Ruby gem that scaffolds a complete API-only authentication and session system for Rails applications.
+
+## What It Generates
+
+Running the generator creates:
+
+- **User model** with `has_secure_password` and email normalization
+- **Session model** with secure token authentication and expiry
+- **Invite-only registration** via admin-issued signup tokens
+- **Password resets** with mailer
+- **Admin gating** for protected endpoints
+- **Rate limiting** on auth endpoints
+- **Session cleanup job** for expired sessions
+- All controllers, migrations, models, serializers, and routes under an `Auth::` namespace
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "authpls"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Generate the auth scaffold:
+
+```bash
+rails generate authpls:scaffold
+```
+
+Then run migrations:
+
+```bash
+rails db:migrate
+```
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails (API mode)
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/authpls/railtie.rb

@@ -0,0 +1,5 @@
+module Authpls
+  class Railtie < Rails::Railtie
+    railtie_name :authpls
+  end
+end

data/lib/authpls/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Authpls
+  VERSION = "0.1.0"
+end

data/lib/authpls.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "authpls/railtie" if defined?(Rails)
+require_relative "authpls/version"
+
+module Authpls
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/generators/authpls/scaffold/scaffold_generator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Authpls
+  module Generators
+    # Generates a complete authentication implementation
+    class ScaffoldGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      source_root File.expand_path("../../templates", __dir__)
+
+      def copy_application_controller_concerns
+        inject_into_file "app/controllers/application_controller.rb", after: "ActionController::API\n" do
+          <<~RUBY
+            include ActionController::HttpAuthentication::Token::ControllerMethods
+            include Auth::Authentication
+            rescue_from ArgumentError, with: :handle_argument_errors
+            rescue_from ActiveRecord::RecordNotFound do
+              render json: { error: 'Not found' }, status: :not_found
+            end
+            RATE_LIMIT_RESPONSE = -> { render json: { error: 'Try again later' }, status: :too_many_requests }
+            def handle_argument_errors(e)
+              logger.error e.full_message
+              render json: { error: e.message }, status: :unprocessable_content
+            end
+          RUBY
+        end
+      end
+
+      def copy_controllers
+        template "users_controller.rb.tt", "app/controllers/auth/users_controller.rb"
+        template "sessions_controller.rb.tt", "app/controllers/auth/sessions_controller.rb"
+        template "profiles_controller.rb.tt", "app/controllers/auth/profiles_controller.rb"
+        template "passwords_controller.rb.tt", "app/controllers/auth/passwords_controller.rb"
+        template "registrations_controller.rb.tt", "app/controllers/auth/registrations_controller.rb"
+        template "signup_tokens_controller.rb.tt", "app/controllers/auth/signup_tokens_controller.rb"
+        template "authentication_concern.rb.tt", "app/controllers/concerns/auth/authentication.rb"
+      end
+
+      def copy_migrations
+        migration_template "users_migration.rb.tt", "db/migrate/create_users.rb"
+        migration_template "sessions_migration.rb.tt", "db/migrate/create_sessions.rb"
+        migration_template "signup_tokens_migration.rb.tt", "db/migrate/create_signup_tokens.rb"
+      end
+
+      def copy_models
+        template "user_model.rb.tt", "app/models/auth/user.rb"
+        template "session_model.rb.tt", "app/models/auth/session.rb"
+        template "signup_token_model.rb.tt", "app/models/auth/signup_token.rb"
+        template "current_model.rb.tt", "app/models/current.rb"
+      end
+
+      def copy_jobs
+        template "cleanup_expired_sessions_job.rb.tt", "app/jobs/auth/cleanup_expired_sessions_job.rb"
+      end
+
+      def copy_mailers
+        template "passwords_mailer.rb.tt", "app/mailers/auth/passwords_mailer.rb"
+      end
+
+      def copy_serializers
+        template "user_serializer.rb.tt", "app/serializers/auth/user_serializer.rb"
+        template "session_serializer.rb.tt", "app/serializers/auth/session_serializer.rb"
+        template "signup_token_serializer.rb.tt", "app/serializers/auth/signup_token_serializer.rb"
+      end
+
+      def copy_routes
+        route <<~RUBY
+          namespace :auth do
+            resource :session, only: %i[create destroy]
+            resource :registration, only: %i[create]
+            resource :profile, only: %i[show update destroy]
+            resources :users, only: %i[index show update destroy]
+            resources :passwords, only: %i[create update]
+            resources :signup_tokens, only: %i[create]
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/templates/authentication_concern.rb.tt

@@ -0,0 +1,59 @@
+module Auth
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :require_authentication
+    end
+
+    class_methods do
+      def allow_unauthenticated_access(**options)
+        skip_before_action :require_authentication, **options
+      end
+
+      def require_admin_access(**options)
+        before_action :verify_is_admin, **options
+      end
+    end
+
+    private
+
+    def require_authentication
+      resume_session || render_unauthorized
+    end
+
+    def render_unauthorized
+      render json: { error: 'Unauthorized' }, status: 401
+    end
+
+    def resume_session
+      Current.session ||= find_session_by_token
+    end
+
+    def find_session_by_token
+      authenticate_with_http_token do |token, _options|
+        Session.where(expires_at: Time.current..).find_by(token: token)
+      end
+    end
+
+    def start_new_session_for(user)
+      user.sessions.create!(
+        user_agent: request.user_agent,
+        ip_address: request.remote_ip,
+        expires_at: 6.hours.from_now
+      ).tap { |session| Current.session = session }
+    end
+
+    def terminate_session
+      Current.session.destroy
+    end
+
+    def verify_is_admin
+      render_forbidden unless Current.session.user.admin?
+    end
+
+    def render_forbidden
+      render json: { error: 'Forbidden' }, status: 403
+    end
+  end
+end

data/lib/generators/templates/cleanup_expired_sessions_job.rb.tt

@@ -0,0 +1,7 @@
+module Auth
+  class CleanupExpiredSessionsJob < ApplicationJob
+    def perform
+      Session.where(expires_at: ..Time.current).delete_all
+    end
+  end
+end

data/lib/generators/templates/current_model.rb.tt

@@ -0,0 +1,4 @@
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session
+  delegate :user, to: :session, allow_nil: true
+end

data/lib/generators/templates/passwords_controller.rb.tt

@@ -0,0 +1,34 @@
+module Auth
+  class PasswordsController < ApplicationController
+    allow_unauthenticated_access only: %i[create update]
+    before_action :set_user_by_token, only: %i[update]
+    rate_limit to: 10, within: 3.minutes, only: :create, with: ApplicationController::RATE_LIMIT_RESPONSE
+
+    def create
+      if (user = User.find_by(email_address: params[:email_address]))
+        PasswordsMailer.reset(user).deliver_later
+      end
+
+      render json: { message: 'Password reset instructions sent' }, status: 202
+    end
+
+    def update
+      if @user.update(params.permit(:password, :password_confirmation))
+        @user.sessions.destroy_all
+        render json: { message: 'Password has been reset.' }, status: 200
+      else
+        render json: { errors: @user.errors.full_messages }, status: 422
+      end
+    end
+
+    private
+
+    def set_user_by_token
+      @user = User.find_by_password_reset_token!(params[:token])
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      render json: {
+        errors: ['Password reset link is invalid or has expired.']
+      }, status: 401
+    end
+  end
+end

data/lib/generators/templates/passwords_mailer.rb.tt

@@ -0,0 +1,8 @@
+module Auth
+  class PasswordsMailer < ApplicationMailer
+    def reset(user)
+      @user = user
+      mail subject: "Reset your password", to: user.email_address
+    end
+  end
+end

data/lib/generators/templates/profiles_controller.rb.tt

@@ -0,0 +1,40 @@
+module Auth
+  class ProfilesController < ApplicationController
+    rate_limit to: 10, within: 5.minutes, with: ApplicationController::RATE_LIMIT_RESPONSE
+
+    def show
+      render json: serializer.serialize_to_json(Current.session.user)
+    end
+
+    def update
+      user = Current.session.user
+      user.attributes = attributes
+
+      if user.save
+        render json: serializer.serialize_to_json(user)
+      else
+        render json: user.errors, status: :unprocessable_content
+      end
+    end
+
+    def destroy
+      if Current.session.user.destroy
+        head :no_content
+      else
+        head :unprocessable_content
+      end
+    end
+
+    private
+
+    def attributes
+      params.expect(profile: %i[email_address])
+    end
+
+    def serializer
+      UserSerializer.new(
+        only: { instance: %i[id email_address admin] }
+      )
+    end
+  end
+end

data/lib/generators/templates/registrations_controller.rb.tt

@@ -0,0 +1,62 @@
+module Auth
+  class RegistrationsController < ApplicationController
+    allow_unauthenticated_access only: :create
+    rate_limit to: 10, within: 3.minutes, only: :create, with: ApplicationController::RATE_LIMIT_RESPONSE
+
+    # Registers a user, requires a valid signup token from an admin
+    # Creates a session upon successful registration
+    # Renders token, + account info on success
+    # Renders error message on invalid request or unique constraint violation
+    def create
+      token = validate_signup_token
+      return unless token
+
+      user = register_user(token)
+      start_new_session_for user
+      render json: { token: Current.session.token, user: serializer.serialize(user) }, status: 201
+    rescue ActiveRecord::RecordInvalid => e
+      render json: { error: e.record.errors.full_messages.join(', ') }, status: 422
+    rescue ActiveRecord::RecordNotUnique
+      render json: { error: 'There was a problem creating your account' }, status: 422
+    end
+
+    private
+
+    # Validates a signup token
+    # Checks token exists, is not expired, and has not already been used
+    # Returns the token if valid, returns nil + renders error if invalid
+    def validate_signup_token
+      token = SignupToken.find_by(token: params[:signup_token])
+      return render_error('Unauthorised', :unauthorized) unless token
+      return render_error('Token Expired', :unauthorized) if token.expires_at < Time.current
+      return render_error('Invalid Token', :unauthorized) if token.used_at
+
+      token
+    end
+
+    # Creates a user with the request params, updates the token to used
+    def register_user(token)
+      user = User.new(attributes)
+      User.transaction do
+        user.save!
+        token.update!(used_at: Time.current, user: user)
+      end
+      user
+    end
+
+    def render_error(msg, status)
+      render(json: { error: msg }, status:)
+      nil
+    end
+
+    def attributes
+      params.expect(registration: %i[email_address password password_confirmation])
+    end
+
+    def serializer
+      UserSerializer.new(
+        only: { instance: %i[id email_address created_at admin] }
+      )
+    end
+  end
+end

data/lib/generators/templates/session_model.rb.tt

@@ -0,0 +1,6 @@
+module Auth
+  class Session < ApplicationRecord
+    has_secure_token :token
+    belongs_to :user
+  end
+end

data/lib/generators/templates/session_serializer.rb.tt

@@ -0,0 +1,5 @@
+module Auth
+  class SessionSerializer < Panko::Serializer
+    attributes :id, :ip_address, :user_agent, :created_at
+  end
+end

data/lib/generators/templates/sessions_controller.rb.tt

@@ -0,0 +1,27 @@
+module Auth
+  class SessionsController < ApplicationController
+    allow_unauthenticated_access only: %i[create]
+    rate_limit to: 10, within: 3.minutes, only: :create, with: ApplicationController::RATE_LIMIT_RESPONSE
+
+    def create
+      user = User.authenticate_by(session_params)
+      if user
+        start_new_session_for user
+        render json: { token: Current.session.token }, status: 201
+      else
+        render json: { error: 'Invalid email address or password' }, status: 401
+      end
+    end
+
+    def destroy
+      terminate_session
+      render json: { message: 'Logged out' }, status: 200
+    end
+
+    private
+
+    def session_params
+      params.require(:session).permit(:email_address, :password)
+    end
+  end
+end

data/lib/generators/templates/sessions_migration.rb.tt

@@ -0,0 +1,15 @@
+class CreateSessions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :sessions do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :ip_address
+      t.string :user_agent
+      t.datetime :expires_at
+
+      t.timestamps
+    end
+
+    add_column :sessions, :token, :string
+    add_index :sessions, :token, unique: true
+  end
+end

data/lib/generators/templates/signup_token_model.rb.tt

@@ -0,0 +1,6 @@
+module Auth
+  class SignupToken < ApplicationRecord
+    belongs_to :user, optional: true
+    has_secure_token :token
+  end
+end

data/lib/generators/templates/signup_token_serializer.rb.tt

@@ -0,0 +1,5 @@
+module Auth
+  class SignupTokenSerializer < Panko::Serializer
+    attributes :id, :token, :expires_at, :used_at
+  end
+end

data/lib/generators/templates/signup_tokens_controller.rb.tt

@@ -0,0 +1,24 @@
+module Auth
+  class SignupTokensController < ApplicationController
+    require_admin_access
+    rate_limit to: 20, within: 1.hour, with: ApplicationController::RATE_LIMIT_RESPONSE
+
+    # Create a signup token to be used to create an account
+    def create
+      signup_token = SignupToken.new(expires_at: 24.hours.from_now)
+      if signup_token.save
+        render json: serializer.serialize_to_json(signup_token), status: :created
+      else
+        render json: signup_token.errors, status: :unprocessable_content
+      end
+    end
+
+    private
+
+    def serializer
+      SignupTokenSerializer.new(
+        only: { instance: %i[token expires_at] }
+      )
+    end
+  end
+end

data/lib/generators/templates/signup_tokens_migration.rb.tt

@@ -0,0 +1,14 @@
+class CreateSignupTokens < ActiveRecord::Migration[8.1]
+  def change
+    create_table :signup_tokens do |t|
+      t.references :user, foreign_key: true
+      t.string :token, null: false
+      t.datetime :expires_at, null: false
+      t.datetime :used_at
+
+      t.timestamps
+    end
+
+    add_index :signup_tokens, :token, unique: true
+  end
+end

data/lib/generators/templates/user_model.rb.tt

@@ -0,0 +1,9 @@
+module Auth
+  class User < ApplicationRecord
+    has_secure_password
+    has_many :sessions, dependent: :destroy
+    has_one :signup_token, dependent: :destroy
+
+    normalizes :email_address, with: ->(e) { e.strip.downcase }
+  end
+end

data/lib/generators/templates/user_serializer.rb.tt

@@ -0,0 +1,6 @@
+module Auth
+  class UserSerializer < Panko::Serializer
+    attributes :id, :email_address, :admin, :created_at
+    has_many :sessions, serializer: SessionSerializer
+  end
+end

data/lib/generators/templates/users_controller.rb.tt

@@ -0,0 +1,62 @@
+module Auth
+  class UsersController < ApplicationController
+    require_admin_access
+    rate_limit to: 30, within: 1.minute, with: ApplicationController::RATE_LIMIT_RESPONSE
+
+    # Get all users
+    # Renders all users and their sessions
+    # TODO: include only active sessions
+    def index
+      users = User.all.includes(:sessions)
+      render json: Panko::ArraySerializer.new(
+        users,
+        each_serializer: UserSerializer,
+        only: { instance: %i[id email_address created_at admin sessions],
+                sessions: { instance: %i[id ip_address user_agent created_at] } }
+      ).to_json, status: :ok
+    end
+
+    # Get and render a user for a given id
+    def show
+      render json: serializer.serialize_to_json(user)
+    end
+
+    # Update and render user for a given id with a set of attributes
+    def update
+      user.attributes = attributes
+
+      if user.save
+        render json: serializer.serialize_to_json(user)
+      else
+        render json: user.errors, status: :unprocessable_content
+      end
+    end
+
+    # Delete a user for a given id
+    def destroy
+      if user.destroy
+        head :no_content
+      else
+        head :unprocessable_content
+      end
+    end
+
+    private
+
+    # Find a user from an id param
+    def user
+      @user ||= User.find(params[:id])
+    end
+
+    def attributes
+      params.expect(user: %i[email_address password password_confirmation])
+    end
+
+    def serializer
+      UserSerializer.new(
+        only: { instance: %i[id email_address created_at admin sessions],
+                sessions: { instance: %i[id ip_address user_agent created_at] } }
+      )
+    end
+  end
+end

data/lib/generators/templates/users_migration.rb.tt

@@ -0,0 +1,12 @@
+class CreateUsers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :users do |t|
+      t.string :email_address, null: false
+      t.string :password_digest, null: false
+      t.boolean :admin, null: false, default: false
+
+      t.timestamps
+    end
+    add_index :users, :email_address, unique: true
+  end
+end

data/sig/authpls.rbs

@@ -0,0 +1,4 @@
+module Authpls
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: authpls
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Locke
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bcrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: panko_serializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+email:
+- alocke322@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/authpls.rb
+- lib/authpls/railtie.rb
+- lib/authpls/version.rb
+- lib/generators/authpls/scaffold/scaffold_generator.rb
+- lib/generators/templates/authentication_concern.rb.tt
+- lib/generators/templates/cleanup_expired_sessions_job.rb.tt
+- lib/generators/templates/current_model.rb.tt
+- lib/generators/templates/passwords_controller.rb.tt
+- lib/generators/templates/passwords_mailer.rb.tt
+- lib/generators/templates/profiles_controller.rb.tt
+- lib/generators/templates/registrations_controller.rb.tt
+- lib/generators/templates/session_model.rb.tt
+- lib/generators/templates/session_serializer.rb.tt
+- lib/generators/templates/sessions_controller.rb.tt
+- lib/generators/templates/sessions_migration.rb.tt
+- lib/generators/templates/signup_token_model.rb.tt
+- lib/generators/templates/signup_token_serializer.rb.tt
+- lib/generators/templates/signup_tokens_controller.rb.tt
+- lib/generators/templates/signup_tokens_migration.rb.tt
+- lib/generators/templates/user_model.rb.tt
+- lib/generators/templates/user_serializer.rb.tt
+- lib/generators/templates/users_controller.rb.tt
+- lib/generators/templates/users_migration.rb.tt
+- sig/authpls.rbs
+homepage: https://github.com/ARLocke322/authpls
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ARLocke322/authpls
+  source_code_uri: https://github.com/ARLocke322/authpls
+  changelog_uri: https://github.com/ARLocke322/authpls/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: A Gem that scaffolds a complete API-only authentication and session system
+test_files: []