propel_authentication 0.1.3 → 0.2.0

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.2.0'
 ```
 
 ### 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,27 +121,32 @@ 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
 
 # In your controllers  
 class ApplicationController < ActionController::API
-  include PropelAuthentication     # Authentication helpers
-  include RackSessionDisable       # Disable Rails sessions for API
+  include PropelAuthenticationConcernConcern     # Authentication helpers
+  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,100 +233,196 @@ 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/concerns/propel_authentication.rb` - Authentication helpers
-- `app/controllers/concerns/rack_session_disable.rb` - Session management
+- `app/controllers/auth/tokens_controller.rb` - Login, logout, user info
+- `app/controllers/auth/passwords_controller.rb` - Password reset functionality
+- `app/controllers/concerns/propel_authentication_concern.rb` - Authentication helpers
+- `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 PropelAuthenticationConcern
+  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
+```
+
+### Multi-Tenant Organization Structure
 
-# Creates routes like: /api/v2/auth/tokens
+```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
 
-# Test authentication flows
-bundle exec ruby -Ilib:test test/generators/authentication/install_generator_test.rb
+Extract generator templates for customization:
+
+```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
+
+## 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
 
-PropelAuth integrates seamlessly with PropelApi for complete API authentication:
+PropelAuthentication integrates seamlessly with other PropelRails gems:
 
+### With PropelAPI
 ```ruby
 # Generated API controllers automatically include authentication
 class Api::V1::ApiController < ApplicationController
-  include PropelAuthentication
+  include PropelAuthenticationConcern
   before_action :authenticate_user
   
   # Your API methods here
 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.2.0 (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).