propel_authentication 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cd8cca14e91a3fc54848cd5a245510df52d76255b79185462477311677724b8
+  data.tar.gz: 30ad644249b3619934c8b81287feef6b92cad1707a4f3d2627b128cc0e76f0a6
+SHA512:
+  metadata.gz: eff271364092358d28c82b91a4d757ee92f962b1acb56ded0a74cb5c5707446d64c0e89f47f4698b2051813979c455c29ddb8e298c71cbdfb0eed88718b253ea
+  data.tar.gz: 985be8cf0e9c27361fb622caeb1e36ac39a99fe2d317828d812fb8add592eb79fdac86ea66c4b5b4caf5a64cba1662eea4ff9df2f95b2f4fdb883c332aeedb92

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Propel Auth Generator
+
+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,290 @@
+# PropelAuth
+
+A comprehensive Rails generator that creates a complete JWT-based authentication system with agencies, agents, tokens, password resets, account locking, and email confirmation.
+
+## Installation
+
+PropelAuth is designed as a **self-extracting generator gem**. You install it temporarily, run the generators to extract the code into your application, then remove the gem dependency.
+
+### Step 1: Add to Gemfile as a Path Gem
+
+```ruby
+# In your Gemfile
+gem 'propel_auth', path: 'propel_auth'
+```
+
+### Step 2: Bundle Install
+
+```bash
+bundle install
+```
+
+### Step 3: Unpack the Generator (Optional)
+
+If you want to customize the generator templates:
+
+```bash
+rails generate propel_auth:unpack
+```
+
+This extracts the generator into `lib/generators/propel_auth/` for customization.
+
+### Step 4: Install PropelAuth
+
+```bash
+rails generate propel_auth:install
+```
+
+This installs the complete authentication system including models, controllers, services, and mailers.
+
+### Step 5: Remove Gem Dependency (Optional)
+
+After installation, you can remove the gem from your Gemfile. All functionality remains in your application.
+
+## Usage
+
+### Generated Authentication System
+
+The generator creates a complete authentication system with:
+
+- **User model** - Primary user accounts with authentication
+- **Organization model** - Multi-tenant organization structure  
+- **Agency model** - Intermediate organization management
+- **Agent model** - User accounts with JWT authentication
+- **Invitation model** - User invitation system
+- **Authentication controllers** - Login, logout, token management
+- **Password controllers** - Password reset functionality
+- **Email confirmation** - Account verification system
+- **Account locking** - Security protection against brute force
+- **Auth mailer** - Email notifications for auth events
+- **Auth service** - Centralized authentication logic
+
+### Authentication Flow
+
+```ruby
+# Login
+POST /auth/tokens
+{
+  "email": "user@example.com",
+  "password": "password"
+}
+
+# Response
+{
+  "data": {
+    "user": { ... },
+    "organization": { ... },
+    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+  }
+}
+
+# Access protected resources
+GET /api/v1/protected_resource
+Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+```
+
+### Authentication Concerns
+
+PropelAuth generates several reusable concerns:
+
+```ruby
+# In your models
+class User < ApplicationRecord
+  include Authenticatable  # JWT token generation and validation
+  include Lockable        # Account locking after failed attempts
+  include Recoverable     # Password reset functionality
+  include Confirmable     # Email confirmation
+
+  # Your model customizations here
+end
+
+# In your controllers  
+class ApplicationController < ActionController::API
+  include PropelAuthentication     # Authentication helpers
+  include RackSessionDisable       # Disable Rails sessions for API
+end
+```
+
+### Password Reset Flow
+
+```ruby
+# Request password reset
+POST /auth/passwords
+{ "email": "user@example.com" }
+
+# Reset password with token
+PATCH /auth/passwords
+{
+  "token": "reset_token_from_email",
+  "password": "new_password", 
+  "password_confirmation": "new_password"
+}
+```
+
+### Account Features
+
+- **Email confirmation** - Verify email addresses before activation
+- **Account locking** - Automatic lockout after failed attempts
+- **Password expiration** - Configurable password aging
+- **JWT tokens** - Secure stateless authentication
+- **Multi-tenancy** - Organization-based structure with agencies
+
+## Features
+
+### Complete Authentication System
+- **JWT-based authentication** - Stateless, scalable token system
+- **Multi-tenant architecture** - User/Organization/Agency/Agent model hierarchy
+- **Email verification** - Confirm email addresses before activation
+- **Password security** - Reset, expiration, and strength requirements
+- **Account protection** - Automatic locking and unlock mechanisms
+- **Invitation system** - User invitation workflow
+
+### Production-Ready Security
+- **BCrypt password hashing** - Industry standard password protection
+- **JWT token validation** - Secure token-based authentication
+- **Rate limiting ready** - Designed for rate limiting integration
+- **Email notifications** - Automated security and account emails
+- **Configurable policies** - Adjust security settings per requirements
+
+### Rails Integration
+- **Standard Rails patterns** - Follows Rails conventions throughout
+- **ActiveRecord models** - Standard model associations and validations
+- **ActionMailer integration** - Built-in email functionality
+- **Controller concerns** - Reusable authentication logic
+- **Environment configuration** - Different settings per environment
+
+## Self-Extracting Architecture
+
+PropelAuth follows a self-extracting pattern that provides:
+
+- **No runtime dependencies** - all code lives in your application
+- **Full control** - modify any component after installation
+- **No black boxes** - transparent, readable Rails code
+- **Easy maintenance** - standard Rails patterns throughout
+
+After installation, you can:
+- Remove the gem from your Gemfile
+- Customize all generated code
+- Maintain and extend functionality independently
+- Integrate with existing authentication systems
+
+## Configuration
+
+Configure PropelAuth in `config/initializers/propel_auth.rb`:
+
+```ruby
+PropelAuth.configure do |config|
+  # JWT Configuration
+  config.jwt_secret = Rails.application.credentials.secret_key_base
+  config.jwt_expiration = 24.hours  # 2.hours in production
+  config.jwt_algorithm = 'HS256'
+  
+  # Password requirements
+  config.password_length = 8..128
+  
+  # Account lockout settings
+  config.max_failed_attempts = 10
+  config.lockout_duration = 30.minutes
+  
+  # Password reset settings
+  config.password_reset_expiration = 15.minutes
+  config.password_reset_rate_limit = 1.minute
+  
+  # Email settings
+  config.frontend_url = 'http://localhost:3000'  # For email links
+  config.email_from_address = "noreply@#{Rails.application.class.module_parent.name.downcase}.com"
+  config.enable_email_notifications = true
+end
+```
+
+## Generated Files
+
+After installation, PropelAuth creates:
+
+### Models
+- `app/models/user.rb` - Primary user model
+- `app/models/organization.rb` - Organization/tenant model
+- `app/models/agency.rb` - Agency management model
+- `app/models/agent.rb` - Agent user accounts
+- `app/models/invitation.rb` - User invitation system
+- `app/models/concerns/authenticatable.rb` - JWT authentication logic
+- `app/models/concerns/confirmable.rb` - Email confirmation
+- `app/models/concerns/lockable.rb` - Account locking
+- `app/models/concerns/recoverable.rb` - Password recovery
+
+### Controllers
+- `app/controllers/auth/tokens_controller.rb` - Login/logout
+- `app/controllers/auth/passwords_controller.rb` - Password reset
+- `app/controllers/concerns/propel_authentication.rb` - Authentication helpers
+- `app/controllers/concerns/rack_session_disable.rb` - Session management
+
+### Services
+- `app/services/auth_notification_service.rb` - Email notifications
+
+### Mailers
+- `app/mailers/auth_mailer.rb` - Authentication emails
+- `app/views/auth_mailer/` - Email templates for confirmations, resets, lockouts
+
+### Migrations
+- User, Organization, Agency, Agent, and Invitation table creation
+- Authentication-related fields and indexes
+
+### Tests
+- Complete test coverage for all authentication functionality
+- Model tests for validations and business logic
+- Controller tests for authentication flows
+- Integration tests for complete user journeys
+
+### Configuration
+- `config/initializers/propel_auth.rb` - PropelAuth configuration
+- `lib/propel_auth.rb` - Runtime library (extracted from gem)
+
+## API Versioning Support
+
+PropelAuth supports API versioning for authentication routes:
+
+```bash
+# Install with custom API version
+rails generate propel_auth:install --api-version=v2
+
+# Creates routes like: /api/v2/auth/tokens
+```
+
+## Dependencies
+
+- **Rails 7.0+** - Modern Rails framework support
+- **BCrypt ~> 3.1.20** - Secure password hashing
+- **JWT ~> 2.7** - JSON Web Token authentication
+
+## Development
+
+```bash
+# Run generator tests
+cd propel_auth
+bundle exec rake test
+
+# Test authentication flows
+bundle exec ruby -Ilib:test test/generators/authentication/install_generator_test.rb
+```
+
+## Integration with PropelApi
+
+PropelAuth integrates seamlessly with PropelApi for complete API authentication:
+
+```ruby
+# Generated API controllers automatically include authentication
+class Api::V1::ApiController < ApplicationController
+  include PropelAuthentication
+  before_action :authenticate_user
+  
+  # Your API methods here
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT). 

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test