propel_authentication 0.1.4 → 0.2.0

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_authentication/templates/{invitation.rb → 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

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_authentication/templates/{user.rb → 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 

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

@@ -44,8 +44,12 @@ module PropelAuthentication
                   :support_email,
                   :enable_email_notifications,
                   :enable_sms_notifications,
+                  :agency_tenancy,
+                  :require_organization_id,
+                  :require_user_id,
                   :namespace,
-                  :version
+                  :version,
+                  :auth_scope
 
     def initialize
       # JWT Configuration defaults
@@ -73,19 +77,48 @@ module PropelAuthentication
       @password_reset_rate_limit = 1.minute
       
       # Frontend URL for email links (configure for your frontend application)
-      @frontend_url = Rails.env.development? ? 'http://localhost:3000' : nil
+      # Priority: Rails credentials -> ENV variables -> environment-specific fallbacks
+      @frontend_url = Rails.application.credentials.frontend_url ||
+                      ENV['FRONTEND_URL'] ||
+                      case Rails.env
+                      when 'development', 'test'
+                        'http://localhost:3000'
+                      when 'staging'
+                        'https://staging.yourapp.com'  # Replace with your staging URL
+                      when 'production'
+                        'https://yourapp.com'  # Replace with your production URL
+                      else
+                        'http://localhost:3000'  # Safe fallback for any other environment
+                      end
       
       # Email configuration
-      @email_from_address = "noreply@#{Rails.application.class.module_parent.name.downcase}.com"
-      @support_email = "support@#{Rails.application.class.module_parent.name.downcase}.com"
+      # Priority: Rails credentials -> ENV variables -> sensible defaults
+      @email_from_address = Rails.application.credentials.email_from_address ||
+                            ENV['EMAIL_FROM_ADDRESS'] ||
+                            "noreply@#{Rails.application.class.module_parent.name.downcase}.com"
+                            
+      @support_email = Rails.application.credentials.support_email ||
+                       ENV['SUPPORT_EMAIL'] ||
+                       "support@#{Rails.application.class.module_parent.name.downcase}.com"
       
       # Notification preferences
       @enable_email_notifications = true
       @enable_sms_notifications = false # Requires SMS provider configuration
       
-      # API namespace and versioning configuration
-      @namespace = nil     # Default to no namespace for clean URLs like /login
-      @version = nil       # Default to no version for clean URLs like /login
+      # Tenancy configuration
+      # Controls whether multi-agency tenancy is enabled within organizations
+      @agency_tenancy = true  # Enable agency-level tenancy by default
+      
+      # API tenancy requirements (for PropelApi integration)
+      # Controls whether APIs require explicit tenancy context in requests
+      @require_organization_id = false  # Auto-assign organization when missing (developer-friendly default)
+      @require_user_id = false          # Auto-assign current user when missing (common workflow default)
+      
+      # API namespace and versioning configuration  
+      # Default to no namespace/version/auth_scope for clean URLs like /login, /me, /signup
+      @namespace = nil
+      @version = nil
+      @auth_scope = nil
     end
   end
 end
@@ -93,7 +126,13 @@ end
 # Configure PropelAuthentication with secure defaults
 PropelAuthentication.configure do |config|
   # JWT Configuration for API authentication
-  config.jwt_secret = Rails.application.credentials.secret_key_base || ENV['SECRET_KEY_BASE'] || 'your-secret-key'
+  # Priority: Rails credentials -> ENV variables -> fallback (development/test only)
+  config.jwt_secret = Rails.application.credentials.jwt_secret ||
+                      ENV['JWT_SECRET'] ||
+                      Rails.application.credentials.secret_key_base ||
+                      ENV['SECRET_KEY_BASE'] ||
+                      (Rails.env.development? || Rails.env.test? ? 'development-secret-key' : 
+                       raise('JWT_SECRET must be set in production'))
   config.jwt_expiration = 24.hours
   
   # Password requirements
@@ -102,6 +141,25 @@ PropelAuthentication.configure do |config|
   # User registration settings
   config.allow_registration = true
   
+  # Multi-tenancy settings  
+  # Controls whether agency-level tenancy is enabled within organizations
+  # When true: Organization -> Agency -> Resources structure
+  # When false: Organization -> Resources structure (simpler)
+  config.agency_tenancy = true
+  
+  # API tenancy requirements (for PropelApi integration)
+  # Controls whether clients must provide explicit tenancy context in API requests
+  
+  # Require explicit organization_id in API requests?
+  # false (recommended): Auto-assigns current user's organization_id when missing
+  # true (strict): Returns 422 error if organization_id not provided by client
+  config.require_organization_id = false
+  
+  # Require explicit user_id in API requests?  
+  # false (recommended): Auto-assigns current user as creator when missing
+  # true (admin mode): Returns 422 error if user_id not provided (for delegation scenarios)
+  config.require_user_id = false
+  
   # Email confirmation (for future use)
   config.require_email_confirmation = false
   
@@ -122,9 +180,36 @@ PropelAuthentication.configure do |config|
     config.jwt_expiration = 2.hours
   end
   
-  # URL structure configuration (set by generator)
+  # URL structure configuration (set by generator based on your choices)
+  # - Default: Clean URLs like /login, /me, /signup (no additional namespacing)  
+  # - With PropelApi: Automatically adopts API namespace for consistency
+  # - Override: Set explicit values to customize URL structure
+  #
+  # Current configuration:
   config.namespace = <%= @auth_namespace ? "'#{@auth_namespace}'" : 'nil' %>
   config.version = <%= @auth_version ? "'#{@auth_version}'" : 'nil' %>
+  config.auth_scope = <%= @auth_scope ? "'#{@auth_scope}'" : 'nil' %>
+  
+  # Examples for customization:
+  # For clean URLs (default):
+  #   config.namespace = nil
+  #   config.version = nil  
+  #   config.auth_scope = nil        # → /login, /me → TokensController
+  #
+  # For organized URLs with auth scope:
+  #   config.namespace = nil
+  #   config.version = nil
+  #   config.auth_scope = 'auth'     # → /auth/login, /auth/me → Auth::TokensController
+  #
+  # For API-style URLs:
+  #   config.namespace = 'api'  
+  #   config.version = 'v1'
+  #   config.auth_scope = nil        # → /api/v1/login, /api/v1/me → Api::V1::TokensController
+  #
+  # For API-style URLs with auth scope:
+  #   config.namespace = 'api'
+  #   config.version = 'v1'
+  #   config.auth_scope = 'auth'     # → /api/v1/auth/login → Api::V1::Auth::TokensController
 end
 
 # PropelAuthentication is now fully extracted to your application!

data/lib/generators/propel_authentication/templates/routes/auth_routes.rb.tt

@@ -0,0 +1,55 @@
+# JWT Authentication routes for <%= auth_route_prefix %>
+<%- if @auth_namespace.present? || @auth_version.present? || @auth_scope.present? -%>
+<%- namespace_parts = [] -%>
+<%- namespace_parts << @auth_namespace if @auth_namespace.present? -%>
+<%- namespace_parts << @auth_version if @auth_version.present? -%>
+<%- namespace_parts.each_with_index do |part, index| -%>
+<%= "  " * index %>namespace :<%= part %> do
+<%- end -%>
+  <%- if @auth_scope.present? -%>
+<%= "  " * namespace_parts.length %>namespace :<%= @auth_scope %> do
+<%= "  " * (namespace_parts.length + 1) %>post 'signup', to: 'signup#create', as: :signup
+<%= "  " * (namespace_parts.length + 1) %>post 'login', to: 'tokens#create', as: :login
+<%= "  " * (namespace_parts.length + 1) %>get 'me', to: 'tokens#show', as: :me
+<%= "  " * (namespace_parts.length + 1) %>delete 'logout', to: 'tokens#destroy', as: :logout
+<%= "  " * (namespace_parts.length + 1) %>post 'unlock', to: 'tokens#unlock', as: :unlock
+<%= "  " * (namespace_parts.length + 1) %>post 'reset', to: 'passwords#create', as: :reset
+<%= "  " * (namespace_parts.length + 1) %>get 'reset', to: 'passwords#show', as: :verify_reset
+<%= "  " * (namespace_parts.length + 1) %>patch 'reset', to: 'passwords#update', as: :update_reset
+<%= "  " * namespace_parts.length %>end
+  <%- else -%>
+<%= "  " * namespace_parts.length %>post 'signup', to: 'signup#create', as: :signup
+<%= "  " * namespace_parts.length %>post 'login', to: 'tokens#create', as: :login
+<%= "  " * namespace_parts.length %>get 'me', to: 'tokens#show', as: :me
+<%= "  " * namespace_parts.length %>delete 'logout', to: 'tokens#destroy', as: :logout
+<%= "  " * namespace_parts.length %>post 'unlock', to: 'tokens#unlock', as: :unlock
+<%= "  " * namespace_parts.length %>post 'reset', to: 'passwords#create', as: :reset
+<%= "  " * namespace_parts.length %>get 'reset', to: 'passwords#show', as: :verify_reset
+<%= "  " * namespace_parts.length %>patch 'reset', to: 'passwords#update', as: :update_reset
+  <%- end -%>
+<%- namespace_parts.length.times do |index| -%>
+<%= "  " * (namespace_parts.length - 1 - index) %>end
+<%- end -%>
+<%- else -%>
+  <%- if @auth_scope.present? -%>
+namespace :<%= @auth_scope %> do
+  post 'signup', to: 'signup#create', as: :signup
+  post 'login', to: 'tokens#create', as: :login
+  get 'me', to: 'tokens#show', as: :me
+  delete 'logout', to: 'tokens#destroy', as: :logout
+  post 'unlock', to: 'tokens#unlock', as: :unlock
+  post 'reset', to: 'passwords#create', as: :reset
+  get 'reset', to: 'passwords#show', as: :verify_reset
+  patch 'reset', to: 'passwords#update', as: :update_reset
+end
+  <%- else -%>
+post 'signup', to: 'signup#create', as: :signup
+post 'login', to: 'tokens#create', as: :login
+get 'me', to: 'tokens#show', as: :me
+delete 'logout', to: 'tokens#destroy', as: :logout
+post 'unlock', to: 'tokens#unlock', as: :unlock
+post 'reset', to: 'passwords#create', as: :reset
+get 'reset', to: 'passwords#show', as: :verify_reset  
+patch 'reset', to: 'passwords#update', as: :update_reset
+  <%- end -%>
+<%- end -%>

data/lib/generators/propel_authentication/templates/services/auth_notification_service.rb

@@ -64,17 +64,17 @@ class AuthNotificationService
     private
 
     def build_password_reset_url(token)
-      base_url = PropelAuth.configuration.frontend_url || default_frontend_url
+      base_url = PropelAuthentication.configuration.frontend_url || default_frontend_url
       "#{base_url}/reset-password?token=#{token}"
     end
 
     def build_account_unlock_url(token)
-      base_url = PropelAuth.configuration.frontend_url || default_frontend_url
+      base_url = PropelAuthentication.configuration.frontend_url || default_frontend_url
       "#{base_url}/unlock-account?token=#{token}"
     end
 
     def build_invitation_url(token)
-      base_url = PropelAuth.configuration.frontend_url || default_frontend_url
+      base_url = PropelAuthentication.configuration.frontend_url || default_frontend_url
       "#{base_url}/accept-invitation?token=#{token}"
     end