propel_authentication 0.1.3 → 0.2.0

data/lib/generators/propel_authentication/templates/core/configuration_methods.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+##
+# Module providing configuration detection and validation for PropelAuthentication generators
+#
+# INDEPENDENCE ARCHITECTURE:
+# - PropelAuthentication works completely standalone with sensible defaults
+# - PropelApi integration is OPTIONAL - when both gems are present, PropelAuthentication
+#   adopts PropelApi's namespace/version for consistency
+# - Neither gem requires the other as a dependency
+# - Graceful fallback ensures no errors when either gem is missing
+#
+# STANDALONE DEFAULTS:
+# - PropelAuthentication: Clean URLs (/login, /me, /signup) for simplicity
+# - PropelApi: REST convention (/api/v1/resources) for standard API patterns
+#
+# INTEGRATION BENEFITS:
+# - When both gems are used together, authentication routes automatically align
+#   with API namespace structure for consistent developer experience
+#
+module PropelAuthentication
+  module ConfigurationMethods
+    
+    # Shared class options across all PropelAuthentication generators
+    def self.included(base)
+      base.class_option :namespace,
+                        type: :string,
+                        default: nil,
+                        desc: "Authentication namespace (e.g., 'api', 'admin_api'). Use 'none' for no namespace. Defaults to PropelAuthentication configuration."
+      
+      base.class_option :version,
+                        type: :string,
+                        default: nil,
+                        desc: "Authentication version (e.g., 'v1', 'v2'). Use 'none' for no versioning. Defaults to PropelAuthentication configuration."
+
+      base.class_option :auth_scope,
+                        type: :string,
+                        default: nil,
+                        desc: "Authentication scope namespace (e.g., 'auth', 'admin'). Use 'none' for no auth scope. Defaults to nil for clean URLs."
+
+      # Legacy support for existing --api-version option
+      base.class_option :api_version,
+                        type: :string,
+                        default: nil,
+                        desc: "Legacy: Use --version instead. Authentication version (e.g., 'v1', 'v2')."
+    end
+
+    protected
+
+
+
+    # Single method to determine all authentication configuration
+    # Handles namespace, version, and auth_scope with consistent priority logic
+    def determine_configuration
+      @auth_namespace = determine_config_value(:namespace, nil)
+      @auth_version = determine_config_value(:version, nil) 
+      @auth_scope = determine_config_value(:auth_scope, nil)
+    end
+
+    # Generic configuration value determination with consistent priority
+    # Priority: 1) Command line, 2) PropelAuthentication config, 3) PropelApi config (optional), 4) Default
+    def determine_config_value(config_key, default_value)
+      option_key = config_key.to_s.gsub('_', '-').to_sym
+      
+      # 1. Explicit command line override
+      if options[option_key] == 'none'
+        return nil
+      end
+      
+      if options[option_key].present?
+        return options[option_key]
+      end
+      
+      # Legacy support for --api-version
+      if config_key == :version && options[:api_version].present?
+        return options[:api_version] unless options[:api_version] == 'none'
+      end
+      
+      # 2. Try PropelAuthentication configuration
+      begin
+        if defined?(PropelAuthentication) && 
+           PropelAuthentication.respond_to?(:configuration) &&
+           PropelAuthentication.configuration.respond_to?(config_key)
+          config_value = PropelAuthentication.configuration.send(config_key)
+          return config_value if config_value.present? && config_value != 'none'
+        end
+      rescue StandardError
+        # Configuration not available, continue
+      end
+      
+      # 3. OPTIONAL: Try PropelApi for namespace/version consistency (when both gems are used)
+      if [:namespace, :version].include?(config_key)
+        begin
+          if defined?(PropelApi) && 
+             PropelApi.respond_to?(:configuration) &&
+             PropelApi.configuration.respond_to?(config_key)
+            api_value = PropelApi.configuration.send(config_key)
+            return api_value if api_value.present? && api_value != 'none'
+          end
+        rescue StandardError
+          # PropelApi not available - this is fine, PropelAuthentication works independently
+        end
+      end
+      
+      # 4. Sensible default
+      default_value
+    end
+
+
+
+    # Display helpers for logging
+    def namespace_display
+      @auth_namespace.present? ? @auth_namespace : 'none'
+    end
+
+    def version_display
+      @auth_version.present? ? @auth_version : 'none'
+    end
+
+    def auth_scope_display
+      @auth_scope.present? ? @auth_scope : 'none'
+    end
+
+    # Authentication route path generation - single source of truth for complete route paths
+    def auth_route_prefix
+      path_parts = []
+      path_parts << @auth_namespace if @auth_namespace.present?
+      path_parts << @auth_version if @auth_version.present?
+      path_parts << @auth_scope if @auth_scope.present?
+      
+      return '/' if path_parts.empty?
+      '/' + path_parts.join('/')
+    end
+
+
+    # Single method to generate controller class names for all cases
+    # Handles both regular controllers and versioned controllers  
+    def auth_controller_class_name(controller_type = 'tokens', version = nil)
+      class_parts = []
+      class_parts << @auth_namespace.camelize if @auth_namespace.present?
+      class_parts << (version || @auth_version).upcase if (version || @auth_version).present?
+      class_parts << @auth_scope.camelize if @auth_scope.present?
+      class_parts << "#{controller_type.camelize}Controller"
+      
+      class_parts.join('::')
+    end
+
+    # Authentication controller directory path
+    def auth_controller_directory
+      path_parts = ['app', 'controllers']
+      path_parts << @auth_namespace if @auth_namespace.present?
+      path_parts << @auth_version if @auth_version.present?
+      path_parts << 'auth'
+      path_parts.join('/')
+    end
+
+    # Helper methods for templates
+    def api_versioned?
+      @auth_version.present? && @auth_version != 'none'
+    end
+
+    def api_only_app?
+      defined?(Rails.application.config.api_only) && Rails.application.config.api_only
+    end
+
+    # Extract namespace prefix for test class names (includes trailing :: when needed)
+    # E.g., "Api::V1::Auth::TokensController" → "Api::V1::Auth::"
+    # E.g., "TokensController" → "" (empty, no namespace)
+    def controller_namespace(controller_type)
+      controller_class = auth_controller_class_name(controller_type)
+      namespace_parts = controller_class.split('::')[0..-2]   # Remove "TokensController" part
+      
+      # Return namespace with trailing :: or empty string
+      namespace_parts.empty? ? '' : namespace_parts.join('::') + '::'
+    end
+
+    # Build dynamic controller file path based on current configuration
+    # E.g., Api::V1::Auth::TokensController → app/controllers/api/v1/auth/tokens_controller.rb
+    def controller_file_path(controller_type)
+      controller_class = auth_controller_class_name(controller_type)
+      
+      # Convert class name to file path
+      path_parts = ['app', 'controllers']
+      namespace_parts = controller_class.split('::')[0..-2] # Remove "TokensController" part
+      namespace_parts.each { |part| path_parts << part.downcase }
+      path_parts << "#{controller_type}_controller.rb"
+      
+      path_parts.join('/')
+    end
+  end
+end 

data/lib/generators/propel_authentication/templates/db/seeds.rb

@@ -0,0 +1,75 @@
+# This file should ensure the existence of records required to run the application in every environment (production,
+# development, test). The code here should be idempotent so that it can be executed at any point in every environment.
+# The data can then be loaded with the bin/rails db:seed command (or created alongside the database with db:setup).
+#
+# Example:
+#
+#   ["Action", "Comedy", "Drama", "Horror"].each do |genre_name|
+#     MovieGenre.find_or_create_by!(name: genre_name)
+#   end
+
+# Create comprehensive tenancy structure for authentication testing
+puts "🏢 Creating test organization structure..."
+
+organization = Organization.find_or_create_by!(name: 'Test Organization') do |org|
+  org.website = 'https://test.example.com'
+  org.time_zone = 'UTC'
+end
+
+# Create agencies for proper tenancy structure
+main_agency = Agency.find_or_create_by!(name: 'Main Department', organization: organization) do |agency|
+  agency.phone_number = '+1-555-0101'
+  agency.address = '123 Main Street'
+end
+
+support_agency = Agency.find_or_create_by!(name: 'Support Department', organization: organization) do |agency|
+  agency.phone_number = '+1-555-0102'
+  agency.address = '123 Support Street'
+end
+
+# Create test users with proper confirmations
+user = User.find_or_create_by!(email_address: 'test@example.com') do |u|
+  u.username = 'testuser'
+  u.email_address = 'test@example.com'
+  u.password = 'password123'
+  u.password_confirmation = 'password123'
+  u.organization = organization
+  u.first_name = 'Test'
+  u.last_name = 'User'
+  u.confirmed_at = 1.week.ago  # Confirmed user for easier testing
+end
+
+admin_user = User.find_or_create_by!(email_address: 'admin@example.com') do |u|
+  u.username = 'adminuser'
+  u.email_address = 'admin@example.com'
+  u.password = 'password123'
+  u.password_confirmation = 'password123'
+  u.organization = organization
+  u.first_name = 'Admin'
+  u.last_name = 'User'
+  u.confirmed_at = 1.week.ago  # Confirmed admin for easier testing
+end
+
+# Create agent associations for agency access (CRITICAL for tenancy validation)
+Agent.find_or_create_by!(user: user, agency: main_agency) do |agent|
+  agent.role = 'member'
+end
+
+Agent.find_or_create_by!(user: admin_user, agency: main_agency) do |agent|
+  agent.role = 'manager'
+end
+
+Agent.find_or_create_by!(user: admin_user, agency: support_agency) do |agent|
+  agent.role = 'admin'
+end
+
+puts "✅ Created test organization: #{organization.name}"
+puts "✅ Created agencies: #{Agency.where(organization: organization).pluck(:name).join(', ')}"
+puts "✅ Created test user: #{user.email_address} (password: password123)"
+puts "✅ Created admin user: #{admin_user.email_address} (password: password123)"
+puts "✅ Created agent associations for proper tenancy access"
+puts ""
+puts "🎯 Test user agency access: #{user.agency_ids}"
+puts "🎯 Admin user agency access: #{admin_user.agency_ids}"
+puts ""
+puts "🚀 You can now test login with POST /api/v1/login"

data/lib/generators/propel_authentication/templates/doc/signup_flow.md

@@ -0,0 +1,315 @@
+# Progressive Signup Flow
+
+This authentication system supports a **progressive multi-step signup flow** that allows users to create organizations and agencies based on their needs.
+
+## Overview
+
+The signup flow creates:
+1. **Organization** - The main tenant/company
+2. **User** - The primary user account (owner role)
+3. **Agency** - Optional organizational unit (if agency tenancy enabled + provided)
+4. **Agent** - Automatic relationship between user and agency (if agency created)
+
+## Configuration
+
+Agency tenancy can be enabled/disabled in `config/initializers/propel_api.rb`:
+
+```ruby
+PropelApi.configure do |config|
+  config.agency_tenancy = true  # Enable agency-level tenancy
+  # config.agency_tenancy = false # Disable for organization-only tenancy
+end
+```
+
+## Signup Endpoints
+
+### Simple Signup (Organization + User only)
+```http
+POST /signup
+Content-Type: application/json
+
+{
+  "user": {
+    "email_address": "john@newcompany.com",
+    "username": "john_doe",
+    "password": "securepassword123",
+    "password_confirmation": "securepassword123",
+    "first_name": "John",
+    "last_name": "Doe",
+    "phone_number": "+1-555-0123",
+    "time_zone": "America/New_York"
+  },
+  "organization": {
+    "name": "NewCo Inc",
+    "website": "https://newco.com",
+    "time_zone": "America/New_York",
+    "description": "Innovative solutions company"
+  }
+}
+```
+
+#### Response (agency tenancy disabled)
+```json
+{
+  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+  "user": {
+    "id": 123,
+    "email_address": "john@newcompany.com",
+    "username": "john_doe",
+    "first_name": "John",
+    "last_name": "Doe",
+    "organization_id": 456,
+    "created_at": "2024-01-15T10:30:00Z"
+  },
+  "organization": {
+    "id": 456,
+    "name": "NewCo Inc",
+    "website": "https://newco.com",
+    "time_zone": "America/New_York"
+  },
+  "agency": null,
+  "agent": null,
+  "message": "Account created successfully! Ready to start working.",
+  "next_steps": [
+    {
+      "action": "invite_team_members",
+      "description": "Invite colleagues to join your organization",
+      "endpoint": "/invitations",
+      "method": "POST"
+    },
+    {
+      "action": "start_creating_resources",
+      "description": "Begin creating and managing your content",
+      "endpoint": "/"
+    }
+  ]
+}
+```
+
+### Complete Signup (Organization + User + Agency + Agent)
+```http
+POST /signup
+Content-Type: application/json
+
+{
+  "user": {
+    "email_address": "sarah@designstudio.com",
+    "username": "sarah_creative",
+    "password": "securepassword123",
+    "password_confirmation": "securepassword123",
+    "first_name": "Sarah",
+    "last_name": "Designer"
+  },
+  "organization": {
+    "name": "Creative Design Studio",
+    "website": "https://designstudio.com",
+    "time_zone": "UTC"
+  },
+  "agency": {
+    "name": "Creative Department",
+    "description": "Main creative and design operations",
+    "website": "https://creative.designstudio.com",
+    "phone_number": "+1-555-DESIGN"
+  },
+  "agent": {
+    "role": "owner"
+  }
+}
+```
+
+#### Response (agency tenancy enabled)
+```json
+{
+  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+  "user": {
+    "id": 789,
+    "email_address": "sarah@designstudio.com",
+    "username": "sarah_creative",
+    "first_name": "Sarah",
+    "last_name": "Designer",
+    "organization_id": 101,
+    "created_at": "2024-01-15T14:20:00Z"
+  },
+  "organization": {
+    "id": 101,
+    "name": "Creative Design Studio",
+    "website": "https://designstudio.com",
+    "time_zone": "UTC"
+  },
+  "agency": {
+    "id": 202,
+    "name": "Creative Department",
+    "organization_id": 101,
+    "description": "Main creative and design operations",
+    "website": "https://creative.designstudio.com"
+  },
+  "agent": {
+    "id": 303,
+    "user_id": 789,
+    "agency_id": 202,
+    "role": "owner",
+    "created_at": "2024-01-15T14:20:00Z"
+  },
+  "message": "Account created successfully! Ready to start working.",
+  "next_steps": [
+    {
+      "action": "create_additional_agencies",
+      "description": "Add more agencies to organize your team",
+      "endpoint": "/agencies",
+      "method": "POST"
+    },
+    {
+      "action": "start_creating_resources",
+      "description": "Begin creating and managing your content (you can create resources immediately)",
+      "endpoint": "/",
+      "note": "Your agency is ready for resource creation"
+    },
+    {
+      "action": "invite_team_members",
+      "description": "Invite colleagues to join your organization",
+      "endpoint": "/invitations",
+      "method": "POST"
+    }
+  ]
+}
+```
+
+## Progressive Enhancement Flow
+
+### Step 1: Core Signup
+User creates account with minimal information (User + Organization).
+
+### Step 2: Add Agencies (Optional)
+```http
+POST /api/v1/agencies
+Authorization: Bearer {token_from_signup}
+Content-Type: application/json
+
+{
+  "data": {
+    "name": "Marketing Department",
+    "description": "Marketing and growth operations"
+  }
+}
+```
+
+### Step 3: Invite Team Members
+```http
+POST /api/v1/invitations
+Authorization: Bearer {token_from_signup}
+Content-Type: application/json
+
+{
+  "data": {
+    "email_address": "teammate@designstudio.com",
+    "agency_id": 202,
+    "role": "manager"
+  }
+}
+```
+
+### Step 4: Start Creating Resources
+With the JWT token, users can immediately create resources:
+
+```http
+POST /api/v1/projects
+Authorization: Bearer {token_from_signup}
+Content-Type: application/json
+
+{
+  "data": {
+    "name": "New Website Design",
+    "agency_id": 202
+  }
+}
+```
+
+## Error Handling
+
+### Missing Required Agency Data (when agency tenancy enabled)
+```json
+{
+  "error": "Agency information required",
+  "message": "Agency details must be provided when agency tenancy is enabled",
+  "code": "MISSING_AGENCY_DATA",
+  "hint": "Include an 'agency' object with name and other details in your request"
+}
+```
+
+### Validation Errors
+```json
+{
+  "error": "Validation failed",
+  "details": {
+    "email_address": ["Email address has already been taken"],
+    "password": ["Password confirmation doesn't match Password"]
+  },
+  "message": "Please correct the errors and try again"
+}
+```
+
+## JWT Token Structure
+
+The returned JWT token contains:
+```json
+{
+  "user_id": 789,
+  "email_address": "sarah@designstudio.com",
+  "organization_id": 101,
+  "agency_ids": [202],
+  "iat": 1705329600,
+  "exp": 1705416000
+}
+```
+
+This enables immediate API access with proper organizational and agency scoping.
+
+## User-Provided vs. System-Automatic
+
+### 🔴 REQUIRED User Input
+- **email_address** - Validated for format & uniqueness
+- **username** - Validated for uniqueness
+- **password** - Minimum 8 characters, secure validation
+- **password_confirmation** - Must match password
+- **organization.name** - Organization name (required)
+
+### 🟡 OPTIONAL User Input  
+- **first_name, last_name** - For personalization (optional)
+- **phone_number** - Contact information (optional)
+- **time_zone** - User/organization timezone (optional)
+- **organization.website** - Company website (optional)
+- **organization.description** - Company description (optional)
+- **agency.{name, description, etc}** - When agency tenancy enabled (optional)
+
+### 🤖 SYSTEM-AUTOMATIC
+- **user.id** - Auto-generated primary key
+- **password_digest** - Auto-hashed with bcrypt
+- **organization_id** - Auto-assigned from created organization  
+- **role: 'owner'** - Auto-assigned for signup user
+- **JWT token** - Auto-generated for immediate API access
+- **Agent record** - Auto-created if agency provided
+- **created_at/updated_at** - Auto-set timestamps
+- **Organization/agency scoping** - Auto-applied to all resources
+
+## Architecture Benefits
+
+1. **Immediate Access**: Users can start working immediately after signup
+2. **Progressive Enhancement**: Start simple, add complexity as needed
+3. **Proper Scoping**: All resources automatically scoped to organization/agency
+4. **Security**: JWT tokens contain proper context for authorization
+5. **Flexibility**: Works with or without agency tenancy
+6. **Smart Defaults**: Minimal required input, system handles the rest
+
+## Configuration Options
+
+Users can choose their tenancy model:
+
+- **Organization-only tenancy**: `agency_tenancy = false`
+  - Simpler data model
+  - Resources scoped to organization only
+  - Good for single-agency organizations
+
+- **Multi-agency tenancy**: `agency_tenancy = true` (default)
+  - More complex but flexible
+  - Resources scoped to organization + agency
+  - Good for multi-department organizations

data/lib/generators/propel_authentication/templates/models/agency.rb.tt

@@ -0,0 +1,13 @@
+class Agency < ApplicationRecord
+  # Multi-tenant associations
+  belongs_to :organization
+  has_many :agents, dependent: :destroy
+
+  validates :name, presence: true
+<% if @rendering_engine == 'json_facet' -%>
+
+  # Facets
+  json_facet :short, fields: [:id, :name]
+  json_facet :details, fields: [:id, :name, :organization_id, :created_at, :updated_at]
+<% end -%>
+end 

data/lib/generators/propel_authentication/templates/models/agent.rb.tt

@@ -0,0 +1,13 @@
+class Agent < ApplicationRecord
+  # Multi-tenant associations
+  belongs_to :agency
+  belongs_to :user
+
+  validates :user_id, uniqueness: { scope: :agency_id }
+<% if @rendering_engine == 'json_facet' -%>
+
+  # Facets
+  json_facet :short, fields: [:id, :title]
+  json_facet :details, fields: [:id, :title, :role, :organization_id, :created_at, :updated_at]
+<% end -%>
+end 

data/lib/generators/{propel_auth/templates/invitation.rb → propel_authentication/templates/models/invitation.rb.tt}

@@ -15,6 +15,12 @@ class Invitation < ApplicationRecord
   scope :valid, -> { where(status: :pending).where('created_at > ?', 7.days.ago) }
   scope :recent, -> { where('created_at > ?', 30.days.ago) }
 
+  <% if @rendering_engine == 'json_facet' -%>
+    # Facets
+    json_facet :short, fields: [:id, :email_address, :organization_id]
+    json_facet :details, fields: [:id, :name, :status, :organization_id, :created_at, :updated_at]
+  <% end -%>
+
   # Check if invitation is still valid (not expired)
   def invitation_valid?
     pending? && created_at > 7.days.ago
@@ -42,14 +48,14 @@ class Invitation < ApplicationRecord
       invitation_hash: generate_invitation_hash
     }
     
-    JWT.encode(payload, PropelAuth.configuration.jwt_secret, 'HS256')
+    JWT.encode(payload, PropelAuthentication.configuration.jwt_secret, 'HS256')
   end
 
   # Find invitation by JWT token with validation
   def self.find_by_invitation_token(token)
     begin
       # Decode and validate the JWT token
-      payload = JWT.decode(token, PropelAuth.configuration.jwt_secret, true, { algorithm: 'HS256' })[0]
+      payload = JWT.decode(token, PropelAuthentication.configuration.jwt_secret, true, { algorithm: 'HS256' })[0]
       
       # Verify this is an invitation token
       return nil unless payload['type'] == 'invitation'

data/lib/generators/propel_authentication/templates/models/organization.rb.tt

@@ -0,0 +1,12 @@
+class Organization < ApplicationRecord
+  # Multi-tenant associations
+  has_many :users, dependent: :destroy
+  has_many :agencies, dependent: :destroy
+
+  validates :name, presence: true
+<% if @rendering_engine == 'json_facet' -%>
+  # Facets
+  json_facet :short, fields: [:id, :name, :website, :time_zone]
+  json_facet :details, fields: [:id, :name, :website, :time_zone, :meta, :settings, :created_at, :updated_at]
+<% end -%>
+end 

data/lib/generators/{propel_auth/templates/user.rb → propel_authentication/templates/models/user.rb.tt}

@@ -3,6 +3,7 @@ class User < ApplicationRecord
   belongs_to :organization
   has_many :invitations, foreign_key: :inviter_id, dependent: :destroy
   has_many :agents, dependent: :destroy
+  has_many :agencies, through: :agents
 
   # Validations
   validates :email_address, presence: true, uniqueness: true
@@ -18,4 +19,8 @@ class User < ApplicationRecord
   # Future enhancements (Epic 2)
   # include Invitable
   # include Statusable
+
+  # Facets
+  json_facet :short, fields: [:id, :email_address, :username, :phone_number, :first_name, :middle_name, :last_name, :time_zone, :status]
+  json_facet :details, fields: [:id, :email_address, :username, :phone_number, :first_name, :middle_name, :last_name, :time_zone, :confirmation_sent_at, :unconfirmed_email_address, :confirmed_at, :status, :last_login_at, :failed_login_attempts, :locked_at, :organization_id, :meta, :settings, :created_at, :updated_at], include: [:organization]
 end