propel_authentication 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 398a15d5453a8bf229939184ce6bc1dc8ed81a11174b914e0d0986b246c7d7a4
-  data.tar.gz: 40280ffa68a4bc3623ee664bb5149aedff359cf1ee0ad8985532a0b5af6837a2
+  metadata.gz: 6b1f57ecf3f4af5949e584a1a3999763ba8bbf5b558bfb0bbd8505de249c2603
+  data.tar.gz: d83ba00e83a944dfafac07fadc250cded1c6ba631108d91e5cd46c13c8592703
 SHA512:
-  metadata.gz: eb69b2697271838f9b17468aa59ae8a885a44cf832a4123e0a7dba280d80d1099d14af430685d1d6f05907f914d37a83887dd27d3ae57b4a2bbfb8cd69f688f0
-  data.tar.gz: '086ecddb5806eb00028dec493b601537935b7bf944a41e773d39c268fe495729693eae695840826751ded9650161e7e5abe35eab40d3ef777a68a17182b3bdc0'
+  metadata.gz: a8fcdcbd5e287c80e989d9c7ebca67ca43b2eb5ee894aa330de5c3bbb1e08c25776837d24345b3c96bd04055cd960a8b433dd79dc912f1b316bec0a0fb45cf1e
+  data.tar.gz: f90e403196ba6e4df6adae2359331fbb82354b890ed8b2594d702d24f19318d65ad0e87d498530bd9848ced16a490fc6f5e006221a08f68539c364e12f17aeef

data/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned Features
+- OAuth provider integration (Google, GitHub, etc.)
+- Two-factor authentication (TOTP)
+- Session management and device tracking
+- Advanced password policies
+
+## [0.1.4] - 2025-01-23
+
+### Fixed
+- **Critical generator extraction issue** - Core infrastructure files now properly extracted during installation
+  - Fixed `require_relative 'core/configuration_methods'` LoadError
+  - Enhanced unpack generator to include all necessary infrastructure
+  - Complete "no black box" policy implementation
+- **JWT authentication system** - Comprehensive fixes and improvements
+  - Proper JWT secret configuration using Rails secret_key_base
+  - Fixed token expiration error messages
+  - Improved parameter validation with Rails conventions (before_action)
+  - ActionCable configuration for test environment
+- **Test suite** - All authentication tests now passing (11/11 - 100% success)
+  - Fixed fixture data foreign key constraints
+  - Proper multi-tenant JWT token verification
+  - Real database operations (no mocks) for confidence in production
+
+### Added
+- **Standalone operation** - Complete extraction of all authentication functionality
+  - All runtime code extracted to host application
+  - Zero gem dependencies after installation
+  - Full customization control for developers
+
+### Improved
+- **Rails conventions** - Better adherence to Rails patterns
+  - Clean before_action callbacks for parameter validation
+  - Proper error handling and status codes
+  - Enhanced test coverage with behavior-driven assertions
+
+## [0.1.3] - 2025-01-XX
+
+### Added
+- **Self-extracting generator gem architecture** - Install temporarily, extract code, remove dependency
+- **JWT-based authentication system** with complete feature set:
+  - User registration and login
+  - Password reset with email notifications
+  - Account lockout after failed attempts
+  - Email confirmation system
+  - Multi-tenant organization support
+- **Rails generator system** with install and unpack commands
+- **Complete authentication infrastructure**:
+  - User, Organization, and Agency models
+  - Authentication controllers with full CRUD
+  - Email templates for notifications
+  - Comprehensive test suite
+  - Database migrations and seeds
+
+### Features
+- **JWT token management** with configurable expiration
+- **Multi-tenant architecture** with organization-based isolation
+- **Email notifications** for password reset and account actions
+- **Account security** with lockout and unlock mechanisms
+- **Flexible configuration** system for all authentication settings
+- **Production-ready** with comprehensive error handling
+
+### Technical Implementation
+- Clean generator architecture following Rails conventions
+- Template-based code generation for easy customization
+- Proper Ruby module structure with namespace isolation
+- Comprehensive test suite with real database operations
+- Zero runtime dependencies after code extraction
+
+### Generator Commands
+- `rails generate propel_authentication:install` - Install authentication system
+- `rails generate propel_authentication:unpack` - Extract generator for customization
+- Selective unpacking with component-specific options
+
+### Self-Extracting Benefits
+- **No runtime gem dependencies** - all code lives in host application
+- **Full customization control** - modify any authentication component
+- **Standard Rails patterns** - follows established conventions
+- **Easy maintenance** - no hidden gem complexity in production

data/README.md

@@ -1,16 +1,16 @@
-# PropelAuth
+# PropelAuthentication
 
-A comprehensive Rails generator that creates a complete JWT-based authentication system with agencies, agents, tokens, password resets, account locking, and email confirmation.
+A comprehensive Rails generator that creates a complete JWT-based authentication system with multi-tenant organization structure, user management, password security, and email notifications.
 
 ## 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.
+PropelAuthentication is designed as a **self-extracting generator gem** following the "no black box" policy. You install it temporarily, run the generators to extract all code into your application, then optionally remove the gem dependency.
 
-### Step 1: Add to Gemfile as a Path Gem
+### Step 1: Add to Gemfile
 
 ```ruby
 # In your Gemfile
-gem 'propel_auth', path: 'propel_auth'
+gem 'propel_authentication', '~> 0.1.4'
 ```
 
 ### Step 2: Bundle Install
@@ -19,27 +19,23 @@ gem 'propel_auth', path: 'propel_auth'
 bundle install
 ```
 
-### Step 3: Unpack the Generator (Optional)
-
-If you want to customize the generator templates:
+### Step 3: Install PropelAuthentication
 
 ```bash
-rails generate propel_auth:unpack
+rails generate propel_authentication:install
 ```
 
-This extracts the generator into `lib/generators/propel_auth/` for customization.
+This installs the complete authentication system including models, controllers, services, mailers, and tests.
 
-### Step 4: Install PropelAuth
+### Step 4: Run Migrations
 
 ```bash
-rails generate propel_auth:install
+rails db:migrate
 ```
 
-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.
+After installation, you can remove the gem from your Gemfile. All functionality remains in your application as extracted code.
 
 ## Usage
 
@@ -47,45 +43,77 @@ After installation, you can remove the gem from your Gemfile. All functionality
 
 The generator creates a complete authentication system with:
 
-- **User model** - Primary user accounts with authentication
+- **User model** - Primary user accounts with JWT 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
+- **Agency model** - Intermediate organization management layer
+- **Agent model** - Agent user accounts within agencies
+- **Invitation model** - User invitation and onboarding system
+- **Authentication controllers** - Login, logout, token management, password reset
+- **Email system** - Password reset, account unlock, and invitation emails
+- **Security features** - Account locking, password validation, JWT tokens
 
 ### Authentication Flow
 
-```ruby
+```bash
 # Login
-POST /auth/tokens
+POST /login
+Content-Type: application/json
+
 {
-  "email": "user@example.com",
-  "password": "password"
+  "user": {
+    "email_address": "user@example.com",
+    "password": "password"
+  }
 }
 
 # Response
 {
-  "data": {
-    "user": { ... },
-    "organization": { ... },
-    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+  "user": {
+    "id": 1,
+    "email_address": "user@example.com",
+    "first_name": "John",
+    "last_name": "Doe",
+    "organization": {
+      "id": 1,
+      "name": "Acme Corp"
+    }
   }
 }
 
 # Access protected resources
 GET /api/v1/protected_resource
 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+
+# Get current user info
+GET /me
+Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+
+# Logout (client-side token removal)
+DELETE /logout
+Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+```
+
+### Authentication Routes
+
+The system generates these authentication routes:
+
+```ruby
+# JWT Authentication routes
+post 'login', to: 'auth/tokens#create'
+get 'me', to: 'auth/tokens#me'
+delete 'logout', to: 'auth/tokens#destroy'
+post 'unlock', to: 'auth/tokens#unlock'
+
+# Password reset routes
+post 'reset', to: 'auth/passwords#create'
+get 'reset', to: 'auth/passwords#show'
+patch 'reset', to: 'auth/passwords#update'
 ```
 
 ### Authentication Concerns
 
-PropelAuth generates several reusable concerns:
+PropelAuthentication generates reusable concerns for models and controllers:
 
 ```ruby
 # In your models
@@ -93,7 +121,7 @@ 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
+  include Confirmable     # Email confirmation (future feature)
 
   # Your model customizations here
 end
@@ -101,19 +129,24 @@ end
 # In your controllers  
 class ApplicationController < ActionController::API
   include PropelAuthentication     # Authentication helpers
-  include RackSessionDisable       # Disable Rails sessions for API
+  include RackSessionDisable       # Disable Rails sessions for API-only apps
+
+  # Use authenticate_user to protect endpoints
+  before_action :authenticate_user, except: [:public_endpoint]
 end
 ```
 
 ### Password Reset Flow
 
-```ruby
+```bash
 # Request password reset
-POST /auth/passwords
-{ "email": "user@example.com" }
+POST /reset
+{
+  "email_address": "user@example.com"
+}
 
-# Reset password with token
-PATCH /auth/passwords
+# Reset password with token (from email)
+PATCH /reset
 {
   "token": "reset_token_from_email",
   "password": "new_password", 
@@ -121,46 +154,50 @@ PATCH /auth/passwords
 }
 ```
 
-### Account Features
+### Account Security 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
+- **JWT Authentication** - Stateless, secure token-based authentication
+- **Account Locking** - Automatic lockout after failed login attempts
+- **Password Security** - BCrypt hashing with configurable requirements
+- **Password Reset** - Secure token-based password reset via email
+- **Multi-tenancy** - Organization-based user isolation
+- **Email Notifications** - Automated emails for security events
 
 ## 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
+- **Password security** - BCrypt hashing, reset functionality, strength requirements
 - **Account protection** - Automatic locking and unlock mechanisms
-- **Invitation system** - User invitation workflow
+- **Email notifications** - Password reset, account unlock, user invitations
+- **Invitation system** - Complete user invitation and onboarding 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
+- **JWT token validation** - Secure token-based authentication with configurable expiration
+- **Account lockout protection** - Configurable failed attempt limits and lockout duration
+- **Rate limiting ready** - Designed for integration with rate limiting systems
+- **Secure token generation** - Cryptographically secure tokens for password reset
+- **Environment-specific configuration** - Different security settings per environment
 
 ### Rails Integration
 - **Standard Rails patterns** - Follows Rails conventions throughout
 - **ActiveRecord models** - Standard model associations and validations
-- **ActionMailer integration** - Built-in email functionality
+- **ActionMailer integration** - Built-in email functionality with templates
 - **Controller concerns** - Reusable authentication logic
-- **Environment configuration** - Different settings per environment
+- **Comprehensive testing** - Complete test suite included
+- **Migration support** - Database schema with proper indexes
 
 ## Self-Extracting Architecture
 
-PropelAuth follows a self-extracting pattern that provides:
+PropelAuthentication follows a "no black box" self-extracting pattern:
 
-- **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
+- **Complete code extraction** - All functionality copied to your application
+- **No runtime dependencies** - Remove the gem after installation
+- **Full customization** - Modify any component after installation
+- **Transparent implementation** - Readable, standard Rails code
+- **Generator extraction** - Optionally extract generator templates for customization
 
 After installation, you can:
 - Remove the gem from your Gemfile
@@ -170,18 +207,23 @@ After installation, you can:
 
 ## Configuration
 
-Configure PropelAuth in `config/initializers/propel_auth.rb`:
+Configure PropelAuthentication in the generated `config/initializers/propel_authentication.rb`:
 
 ```ruby
-PropelAuth.configure do |config|
+PropelAuthentication.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_secret = Rails.application.config.secret_key_base || 
+                     Rails.application.credentials.secret_key_base || 
+                     ENV['SECRET_KEY_BASE']
+  config.jwt_expiration = Rails.env.production? ? 2.hours : 24.hours
   config.jwt_algorithm = 'HS256'
   
   # Password requirements
   config.password_length = 8..128
   
+  # User registration settings
+  config.allow_registration = true
+  
   # Account lockout settings
   config.max_failed_attempts = 10
   config.lockout_duration = 30.minutes
@@ -191,86 +233,144 @@ PropelAuth.configure do |config|
   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.frontend_url = Rails.env.development? ? 'http://localhost:3000' : 'https://yourapp.com'
+  config.email_from_address = "noreply@yourapp.com"
+  config.support_email = "support@yourapp.com"
   config.enable_email_notifications = true
 end
 ```
 
 ## Generated Files
 
-After installation, PropelAuth creates:
+After installation, PropelAuthentication 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/user.rb` - Primary user model with authentication
+- `app/models/organization.rb` - Multi-tenant organization model
+- `app/models/agency.rb` - Agency management within organizations
 - `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
+- `app/models/concerns/confirmable.rb` - Email confirmation (future feature)
+- `app/models/concerns/lockable.rb` - Account locking functionality
+- `app/models/concerns/recoverable.rb` - Password recovery logic
 
 ### Controllers
-- `app/controllers/auth/tokens_controller.rb` - Login/logout
-- `app/controllers/auth/passwords_controller.rb` - Password reset
+- `app/controllers/auth/tokens_controller.rb` - Login, logout, user info
+- `app/controllers/auth/passwords_controller.rb` - Password reset functionality
 - `app/controllers/concerns/propel_authentication.rb` - Authentication helpers
-- `app/controllers/concerns/rack_session_disable.rb` - Session management
+- `app/controllers/concerns/rack_session_disable.rb` - Session management for APIs
 
 ### 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
+- `app/services/auth_notification_service.rb` - Email notification service
+
+### Mailers and Views
+- `app/mailers/auth_mailer.rb` - Authentication email mailer
+- `app/views/auth_mailer/password_reset.html.erb` - Password reset email template
+- `app/views/auth_mailer/password_reset.text.erb` - Text version
+- `app/views/auth_mailer/account_unlock.html.erb` - Account unlock email template
+- `app/views/auth_mailer/account_unlock.text.erb` - Text version
+- `app/views/auth_mailer/user_invitation.html.erb` - User invitation email template
+- `app/views/auth_mailer/user_invitation.text.erb` - Text version
+- `app/views/auth_mailer/email_confirmation.html.erb` - Email confirmation template
+- `app/views/auth_mailer/email_confirmation.text.erb` - Text version
+
+### Database Migrations
 - User, Organization, Agency, Agent, and Invitation table creation
-- Authentication-related fields and indexes
+- Authentication-related fields (password_digest, failed_attempts, locked_at, etc.)
+- Proper indexes for performance
+- Foreign key relationships
 
 ### 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
+- `test/models/user_test.rb` - User model tests
+- `test/controllers/auth/tokens_controller_test.rb` - Authentication controller tests
+- `test/mailers/auth_mailer_test.rb` - Email functionality tests
+- `test/concerns/` - Tests for all authentication concerns
+- `test/controllers/auth/` - Integration tests for authentication flows
+- Complete fixture files for all models
 
-### Configuration
-- `config/initializers/propel_auth.rb` - PropelAuth configuration
-- `lib/propel_auth.rb` - Runtime library (extracted from gem)
+### Configuration and Runtime
+- `config/initializers/propel_authentication.rb` - Configuration file
+- `lib/propel_authentication.rb` - Complete runtime library (extracted from gem)
+- `config/environments/development_email.rb` - Email configuration for development
 
-## API Versioning Support
+## Advanced Usage
 
-PropelAuth supports API versioning for authentication routes:
+### Custom Authentication Logic
 
-```bash
-# Install with custom API version
-rails generate propel_auth:install --api-version=v2
+```ruby
+class Api::V1::UsersController < ApplicationController
+  include PropelAuthentication
+  before_action :authenticate_user
+  
+  def index
+    # current_user is available after authenticate_user
+    users = current_user.organization.users
+    render json: users
+  end
+  
+  def show
+    # Access control based on organization
+    user = current_user.organization.users.find(params[:id])
+    render json: user
+  end
+end
+```
 
-# Creates routes like: /api/v2/auth/tokens
+### Multi-Tenant Organization Structure
+
+```ruby
+# Users belong to organizations
+user = User.find(1)
+user.organization.name # => "Acme Corp"
+
+# Organizations can have multiple agencies
+organization = Organization.find(1)
+organization.agencies.count # => 3
+
+# Agencies have agents (specialized users)
+agency = Agency.find(1)
+agency.agents.active.count # => 5
 ```
 
-## Dependencies
+### Email Customization
 
-- **Rails 7.0+** - Modern Rails framework support
-- **BCrypt ~> 3.1.20** - Secure password hashing
-- **JWT ~> 2.7** - JSON Web Token authentication
+All email templates are extracted to your application and can be customized:
 
-## Development
+```erb
+<!-- app/views/auth_mailer/password_reset.html.erb -->
+<h1>Password Reset Request</h1>
+<p>Hello <%= @user.first_name %>,</p>
+<p>You requested a password reset for your account.</p>
+<p><%= link_to "Reset Password", @reset_url %></p>
+```
 
-```bash
-# Run generator tests
-cd propel_auth
-bundle exec rake test
+## Generator Customization
+
+Extract generator templates for customization:
 
-# Test authentication flows
-bundle exec ruby -Ilib:test test/generators/authentication/install_generator_test.rb
+```bash
+rails generate propel_authentication:unpack
 ```
 
-## Integration with PropelApi
+This creates `lib/generators/propel_authentication/` with all templates, allowing you to:
+- Modify model templates
+- Customize controller logic
+- Change email templates
+- Adjust migration structure
 
-PropelAuth integrates seamlessly with PropelApi for complete API authentication:
+## Dependencies
 
+- **Rails 7.0+** - Modern Rails framework support
+- **BCrypt ~> 3.1.20** - Secure password hashing
+- **JWT ~> 2.7** - JSON Web Token authentication
+- **Letter Opener** (development) - Email preview in development
+
+## Integration with PropelRails Ecosystem
+
+PropelAuthentication integrates seamlessly with other PropelRails gems:
+
+### With PropelAPI
 ```ruby
 # Generated API controllers automatically include authentication
 class Api::V1::ApiController < ApplicationController
@@ -281,10 +381,48 @@ class Api::V1::ApiController < ApplicationController
 end
 ```
 
+### With PropelFacets
+```ruby
+# Use authentication with JSON facets
+class Api::V1::UsersController < Api::V1::ApiController
+  def index
+    users = current_user.organization.users
+    render_facet users, :summary
+  end
+end
+```
+
+## Development and Testing
+
+```bash
+# Run all authentication tests
+rails test test/models/user_test.rb
+rails test test/controllers/auth/
+rails test test/concerns/
+rails test test/mailers/
+
+# Test specific authentication flows
+rails test test/controllers/auth/tokens_controller_test.rb
+rails test test/controllers/auth/password_reset_integration_test.rb
+
+# Run generator tests (if gem is in development)
+cd propel_authentication
+bundle exec rake test
+```
+
+## Version History
+
+### 0.1.4 (Current)
+- Fixed generator extraction issues
+- Enhanced JWT authentication with proper secret handling
+- Complete test suite passing
+- Improved "no black box" policy implementation
+- Better integration with PropelRails ecosystem
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub.
+Bug reports and pull requests are welcome on GitHub at https://github.com/propel-web/propel_rails.
 
 ## License
 
-The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT). 
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT).