standard_id 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d55cdf40a33a4f541b1de5ecb1c19f827b92123b63bccd56781da4671944ff45
-  data.tar.gz: 714bc65bd0aa6a6913b51c0f59f659f41a425a5a21489103d89624149e3ff61d
+  metadata.gz: 2878f305d6dfe83c5a1c0851cde68602cbd17899b1a676981afd8166f56995e0
+  data.tar.gz: 4c1802cc0bb54045165eb42289d75dda85db9a8838d61a6c1b4e7a7ff50e7828
 SHA512:
-  metadata.gz: 0625c5efdb00b0e0d8558191c2b8ad7c9512c6ec13a5fe5896393497241f2f8313f8633b3e319358915b00ff33b23a3979b28e32c64fc20664b9a5e513625d5b
-  data.tar.gz: 0fb8080e7bee90799d27daa892fb9c221e5d4558b0a5c73916249988f6875793ec54ae2afdc6c93d11b526acee37f23e7350e3f2f47522c67b2e6c37c10e8626
+  metadata.gz: 8073e2e1f0208261525be8218960ef6481e8a5558f281a56baf2316b4750f9557b37365831b9aa530706e2d52d6c088e3cc3e9c23c4a4ef722d641f2041ea357
+  data.tar.gz: a803c19a19f5fbcc3acae0511f629c6d4b1520d67a54cfa16d062fcc60333083d28cd5149a6658bfb16e37ae3a2ff1d7cdf06d657d16130010a08c67b8c851ff

data/README.md

@@ -37,6 +37,11 @@ A comprehensive authentication engine for Rails applications, built on the secur
 - **Remember Me**: Extended session support
 - **Account Lockout**: Protection against brute force attacks
 
+### ⚡ Frontend Framework Support
+- **Inertia.js Integration**: Optional support for React, Vue, or Svelte frontends
+- **Conditional Rendering**: Automatically switches between ERB and Inertia based on configuration
+- **External Redirects**: Proper handling of OAuth redirects in SPA contexts
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -114,9 +119,15 @@ StandardId.configure do |config|
   # Custom layout for web views
   config.web_layout = "application"
 
-  # Passwordless delivery callbacks
-  # config.passwordless_email_sender = ->(email, code) { UserMailer.send_code(email, code).deliver_now }
-  # config.passwordless_sms_sender   = ->(phone, code) { SmsService.send_code(phone, code) }
+  # Inertia.js support (see Inertia.js Integration section below)
+  # config.use_inertia = true
+  # config.inertia_component_namespace = "auth"
+
+  # Session lifetimes
+  # config.session.browser_session_lifetime = 86400      # 24 hours (web sessions)
+  # config.session.browser_session_remember_me_lifetime = 2_592_000 # 30 days (remember me cookies)
+  # config.session.device_session_lifetime = 2_592_000   # 30 days (API device sessions)
+  # config.session.service_session_lifetime = 7_776_000  # 90 days (service-to-service sessions)
 
   # Subset configuration
   # config.password.minimum_length = 12
@@ -177,37 +188,535 @@ StandardId.configure do |config|
       name: social_info[:name] || social_info[:given_name]
     }
   }
-
-  # Optional: run a callback whenever a social login completes
-  config.social.social_callback = ->(social_info:, provider:, tokens:, account:) {
-    AuditLog.social_login(
-      provider: provider,
-      email: social_info[:email],
-      tokens: tokens,
-      account_id: account.id,
-    )
-  }
 end
 ```
 
 `social_info` is an indifferent-access hash containing at least `email`, `name`, and `provider_id`.
 
-### Passwordless Authentication
+To handle social login completion (e.g., for analytics or audit logging), subscribe to the `SOCIAL_AUTH_COMPLETED` event:
+
+```ruby
+# config/initializers/standard_id_events.rb
+StandardId::Events.subscribe(StandardId::Events::SOCIAL_AUTH_COMPLETED) do |event|
+  Analytics.track_social_login(
+    provider: event[:provider],
+    account_id: event[:account].id,
+    tokens: event[:tokens]
+  )
+end
+```
+
+### Inertia.js Integration
+
+StandardId supports [Inertia.js](https://inertiajs.com/) for modern React, Vue, or Svelte frontends. When enabled, web controllers render Inertia components instead of ERB views.
+
+#### Setup
+
+1. Add the `inertia_rails` gem to your Gemfile:
+
+```ruby
+gem "inertia_rails"
+```
+
+2. Enable Inertia in your StandardId configuration:
 
 ```ruby
 StandardId.configure do |config|
-  # Email delivery
-  config.passwordless_email_sender = ->(email, code) {
-    UserMailer.send_code(email, code).deliver_now
+  config.use_inertia = true
+  config.inertia_component_namespace = "auth" # Optional, defaults to "standard_id"
+end
+```
+
+3. Create the corresponding frontend components. The component path follows the pattern:
+   `{namespace}/{ControllerName}/{action}`
+
+For example, with `inertia_component_namespace = "auth"`:
+- Login page: `pages/auth/login/show.tsx`
+- Signup page: `pages/auth/signup/show.tsx`
+
+#### Example Component (React)
+
+```tsx
+// frontend/pages/auth/login/show.tsx
+import { useForm } from '@inertiajs/react'
+
+interface Props {
+  redirect_uri: string
+  connection: string | null
+  flash: { notice?: string; alert?: string }
+  social_providers: { google_enabled: boolean; apple_enabled: boolean }
+}
+
+export default function LoginShow({ redirect_uri, flash, social_providers }: Props) {
+  const { data, setData, post, processing } = useForm({
+    'login[email]': '',
+    'login[password]': '',
+    'login[remember_me]': false,
+    redirect_uri,
+  })
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    post('/login')
   }
 
-  # SMS delivery
-  config.passwordless_sms_sender = ->(phone, code) {
-    SmsService.send_code(phone, code)
+  const handleSocialLogin = (connection: string) => {
+    post('/login', { data: { connection, redirect_uri } })
   }
+
+  return (
+    <div className="login-container">
+      {flash.alert && <div className="alert alert-error">{flash.alert}</div>}
+      {flash.notice && <div className="alert alert-success">{flash.notice}</div>}
+
+      <form onSubmit={handleSubmit}>
+        <div>
+          <label htmlFor="email">Email</label>
+          <input
+            id="email"
+            type="email"
+            value={data['login[email]']}
+            onChange={e => setData('login[email]', e.target.value)}
+            required
+          />
+        </div>
+
+        <div>
+          <label htmlFor="password">Password</label>
+          <input
+            id="password"
+            type="password"
+            value={data['login[password]']}
+            onChange={e => setData('login[password]', e.target.value)}
+            required
+          />
+        </div>
+
+        <div>
+          <label>
+            <input
+              type="checkbox"
+              checked={data['login[remember_me]'] as boolean}
+              onChange={e => setData('login[remember_me]', e.target.checked)}
+            />
+            Remember me
+          </label>
+        </div>
+
+        <button type="submit" disabled={processing}>
+          {processing ? 'Signing in...' : 'Sign In'}
+        </button>
+      </form>
+
+      {(social_providers.google_enabled || social_providers.apple_enabled) && (
+        <div className="social-login">
+          <p>Or continue with</p>
+          {social_providers.google_enabled && (
+            <button type="button" onClick={() => handleSocialLogin('google')}>
+              Sign in with Google
+            </button>
+          )}
+          {social_providers.apple_enabled && (
+            <button type="button" onClick={() => handleSocialLogin('apple')}>
+              Sign in with Apple
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+> **Note:** The `useForm` hook from `@inertiajs/react` automatically handles CSRF tokens. When you call `post()`, `put()`, `patch()`, or `delete()`, Inertia reads the CSRF token from the `<meta name="csrf-token">` tag in your layout and includes it in the request headers.
+
+#### Props Passed to Components
+
+Authentication pages receive the following props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `redirect_uri` | `string` | URL to redirect to after authentication |
+| `connection` | `string \| null` | Social provider connection (if any) |
+| `flash` | `{ notice?: string, alert?: string }` | Flash messages |
+| `social_providers` | `{ google_enabled: boolean, apple_enabled: boolean }` | Available social providers |
+| `errors` | `object` | Validation errors (on form submission failures) |
+
+#### Using Authentication in Host App Controllers
+
+You can use the `authenticate_account!` method in your own controllers to require authentication with Inertia-compatible redirects:
+
+```ruby
+class DashboardController < ApplicationController
+  include StandardId::WebAuthentication
+
+  before_action :authenticate_account!
+
+  def show
+    # Only authenticated users can access this
+  end
+end
+```
+
+This will redirect unauthenticated users to the login page using `inertia_location` for Inertia requests, ensuring proper SPA navigation.
+
+### Passwordless Code Delivery
+
+Subscribe to the `PASSWORDLESS_CODE_GENERATED` event to deliver OTP codes:
+
+```ruby
+# config/initializers/standard_id_events.rb
+StandardId::Events.subscribe(StandardId::Events::PASSWORDLESS_CODE_GENERATED) do |event|
+  case event[:channel]
+  when "email"
+    UserMailer.send_code(event[:identifier], event[:code_challenge].code).deliver_now
+  when "sms"
+    SmsService.send_code(event[:identifier], event[:code_challenge].code)
+  end
+end
+```
+
+Event payload includes:
+- `channel` - `"email"` or `"sms"`
+- `identifier` - The email address or phone number
+- `code_challenge` - The code challenge object with `.code` method
+- `expires_at` - When the code expires
+
+> **Note**: If you're using the deprecated `passwordless_email_sender` or `passwordless_sms_sender` callbacks, see the [Migration Guide](docs/MIGRATION_GUIDE.md) for upgrade instructions.
+
+## Event System
+
+StandardId emits events throughout the authentication lifecycle using `ActiveSupport::Notifications`. This enables decoupled handling of cross-cutting concerns like logging, analytics, audit trails, and webhooks.
+
+### Enabling Event Logging
+
+Enable the built-in structured logging subscriber:
+
+```ruby
+StandardId.configure do |config|
+  config.events.enable_logging = true
+end
+```
+
+This outputs JSON-structured logs for all authentication events:
+
+```json
+{
+  "subject": "standard_id.authentication.attempt.succeeded",
+  "severity": "info",
+  "duration": 50.25,
+  "account_id": 123,
+  "auth_method": "password",
+  "ip_address": "192.168.1.1"
+}
+```
+
+### Available Events
+
+| Category | Events |
+|----------|--------|
+| **Authentication** | `authentication.attempt.started`, `authentication.attempt.succeeded`, `authentication.attempt.failed`, `authentication.password.validated`, `authentication.password.failed`, `authentication.otp.validated`, `authentication.otp.failed` |
+| **Session** | `session.creating`, `session.created`, `session.validating`, `session.validated`, `session.expired`, `session.revoked`, `session.refreshed` |
+| **Account** | `account.creating`, `account.created`, `account.verified`, `account.status_changed`, `account.activated`, `account.deactivated`, `account.locked`, `account.unlocked` |
+| **Identifier** | `identifier.created`, `identifier.verification.started`, `identifier.verification.succeeded`, `identifier.verification.failed`, `identifier.linked` |
+| **OAuth** | `oauth.authorization.requested`, `oauth.authorization.granted`, `oauth.authorization.denied`, `oauth.token.issuing`, `oauth.token.issued`, `oauth.token.refreshed`, `oauth.code.consumed` |
+| **Passwordless** | `passwordless.code.requested`, `passwordless.code.generated`, `passwordless.code.sent`, `passwordless.code.verified`, `passwordless.code.failed`, `passwordless.account.created` |
+| **Social** | `social.auth.started`, `social.auth.callback_received`, `social.user_info.fetched`, `social.account.created`, `social.account.linked`, `social.auth.completed` |
+| **Credential** | `credential.password.created`, `credential.password.reset_initiated`, `credential.password.reset_completed`, `credential.password.changed`, `credential.client_secret.created`, `credential.client_secret.rotated` |
+
+### Subscribing to Events
+
+#### Block-based (simple)
+
+```ruby
+# config/initializers/standard_id_events.rb
+StandardId::Events.subscribe(StandardId::Events::AUTHENTICATION_SUCCEEDED) do |event|
+  Analytics.track_login(
+    account_id: event[:account].id,
+    method: event[:auth_method],
+    ip: event[:ip_address]
+  )
+end
+
+# Subscribe to multiple events at once
+StandardId::Events.subscribe(
+  StandardId::Events::SESSION_CREATING,
+  StandardId::Events::SESSION_VALIDATING,
+  StandardId::Events::OAUTH_TOKEN_ISSUING
+) do |event|
+  # Handle all three events with the same block
+  check_rate_limit(event[:account], event[:ip_address])
+end
+
+# Subscribe to events with pattern matching
+StandardId::Events.subscribe(/social/) do |event|
+  Rails.logger.info("Social event: #{event.name}")
+end
+```
+
+#### Class-based (complex logic)
+
+```ruby
+# app/subscribers/audit_subscriber.rb
+class AuditSubscriber < StandardId::Events::Subscribers::Base
+  subscribe_to StandardId::Events::AUTHENTICATION_SUCCEEDED
+  subscribe_to StandardId::Events::AUTHENTICATION_FAILED
+  subscribe_to StandardId::Events::SESSION_REVOKED
+
+  def call(event)
+    AuditLog.create!(
+      event_type: event.short_name,
+      account_id: event[:account]&.id,
+      ip_address: event[:ip_address],
+      metadata: event.payload
+    )
+  end
+end
+
+# config/initializers/standard_id_events.rb
+AuditSubscriber.attach
+```
+
+## Account Status (Activation/Deactivation)
+
+StandardId provides an optional `AccountStatus` concern for managing account activation and deactivation. This uses Rails enum with the event system to enforce status checks and handle side effects without modifying core authentication logic.
+
+### Setup
+
+1. Add a migration for the status column. For PostgreSQL (recommended), use a native enum type:
+
+```ruby
+# PostgreSQL with native enum (recommended)
+class AddStatusToUsers < ActiveRecord::Migration[8.0]
+  def up
+    create_enum :account_status, %w[active inactive]
+
+    add_column :users, :status, :enum, enum_type: :account_status, default: "active", null: false
+    add_column :users, :activated_at, :datetime
+    add_column :users, :deactivated_at, :datetime
+  end
+
+  def down
+    remove_column :users, :status
+    remove_column :users, :activated_at
+    remove_column :users, :deactivated_at
+
+    drop_enum :account_status
+  end
+end
+```
+
+For other databases (MySQL, SQLite), use a string column:
+
+```ruby
+# String column (MySQL, SQLite)
+class AddStatusToUsers < ActiveRecord::Migration[8.0]
+  def change
+    add_column :users, :status, :string, default: "active", null: false
+    add_column :users, :activated_at, :datetime
+    add_column :users, :deactivated_at, :datetime
+    add_index :users, :status
+  end
+end
+```
+
+2. Include the concern in your account model:
+
+```ruby
+class User < ApplicationRecord
+  include StandardId::AccountStatus
+  # ...
+end
+```
+
+The concern works with both PostgreSQL enum and string columns - Rails enum handles both transparently.
+
+### Usage
+
+```ruby
+# Deactivate an account
+user.deactivate!
+# => Emits ACCOUNT_DEACTIVATED event
+# => All active sessions are automatically revoked
+
+# Reactivate an account
+user.activate!
+# => Emits ACCOUNT_ACTIVATED event
+# => User can log in again
+
+# Check status
+user.active?    # => true/false
+user.inactive?  # => true/false
+
+# Query scopes
+User.active     # => Users with status 'active'
+User.inactive   # => Users with status 'inactive'
+```
+
+### Handling AccountDeactivatedError
+
+When an inactive account attempts to authenticate, `StandardId::AccountDeactivatedError` is raised. You need to handle this error in your application controller:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include StandardId::WebAuthentication
+
+  rescue_from StandardId::AccountDeactivatedError, with: :handle_account_deactivated
+
+  private
+
+  def handle_account_deactivated
+    # For web requests, redirect with a message
+    redirect_to login_path, alert: "Your account has been deactivated. Please contact support."
+  end
+end
+```
+
+For API controllers:
+
+```ruby
+# app/controllers/api/base_controller.rb
+class Api::BaseController < ActionController::API
+  include StandardId::ApiAuthentication
+
+  rescue_from StandardId::AccountDeactivatedError, with: :handle_account_deactivated
+
+  private
+
+  def handle_account_deactivated
+    render json: {
+      error: "account_deactivated",
+      message: "Your account has been deactivated"
+    }, status: :forbidden
+  end
+end
+```
+
+## Account Locking (Administrative Security)
+
+StandardId provides an optional `AccountLocking` concern for administrative account locking. This is distinct from account deactivation - locking is for security enforcement by administrators, while deactivation is for lifecycle management.
+
+### Key Differences from Account Deactivation
+
+| Feature | Account Status | Account Locking |
+|---------|---------------|-----------------|
+| **Purpose** | Lifecycle management | Security enforcement |
+| **Who Controls** | System/User | Admin/Staff only |
+| **User Reversible** | Yes (future) | No |
+| **Use Cases** | Inactivity, user choice | Policy violation, security incident, fraud |
+
+An account can be in any combination:
+- Active + Unlocked ✅ (normal operation)
+- Active + Locked ⚠️ (admin locked for security)
+- Inactive + Unlocked ⚠️ (deactivated but not locked)
+- Inactive + Locked 🚫 (both restrictions apply)
+
+### Setup
+
+1. Add a migration for the locking columns:
+
+```ruby
+class AddLockingToUsers < ActiveRecord::Migration[8.0]
+  def change
+    add_column :users, :locked, :boolean, default: false, null: false
+    add_column :users, :locked_at, :datetime
+    add_column :users, :lock_reason, :string
+    add_column :users, :locked_by_id, :integer
+    add_column :users, :locked_by_type, :string
+    add_column :users, :unlocked_at, :datetime
+    add_column :users, :unlocked_by_id, :integer
+    add_column :users, :unlocked_by_type, :string
+
+    add_index :users, :locked
+    add_index :users, [:locked_by_type, :locked_by_id]
+  end
+end
+```
+
+2. Include the concern in your account model:
+
+```ruby
+class User < ApplicationRecord
+  include StandardId::AccountLocking  # For admin locking
+  include StandardId::AccountStatus   # Optional: for activation/deactivation
+  # ...
+end
+```
+
+### Usage
+
+```ruby
+# Lock an account (revokes all active sessions immediately)
+user.lock!(reason: "Suspicious activity detected", locked_by: current_admin)
+# => Emits ACCOUNT_LOCKED event
+# => All active sessions (browser, device, service) are revoked
+
+# Unlock an account (user must log in again)
+user.unlock!(unlocked_by: current_admin)
+# => Emits ACCOUNT_UNLOCKED event
+# => User can log in again
+
+# Check lock status
+user.locked?    # => true/false
+user.unlocked?  # => true/false
+
+# Query scopes
+User.locked     # => Users with locked = true
+User.unlocked   # => Users with locked = false
+
+# Combine with AccountStatus scopes
+User.unlocked.active  # => Users who can log in
+```
+
+### Handling AccountLockedError
+
+When a locked account attempts to authenticate, `StandardId::AccountLockedError` is raised. The error includes metadata about the lock:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include StandardId::WebAuthentication
+
+  rescue_from StandardId::AccountLockedError, with: :handle_account_locked
+
+  private
+
+  def handle_account_locked(error)
+    # error.account     - The locked account
+    # error.lock_reason - Why the account was locked
+    # error.locked_at   - When the account was locked
+    redirect_to login_path, alert: "Your account has been locked. Please contact support."
+  end
 end
 ```
 
+For API controllers:
+
+```ruby
+# app/controllers/api/base_controller.rb
+class Api::BaseController < ActionController::API
+  include StandardId::ApiAuthentication
+
+  rescue_from StandardId::AccountLockedError, with: :handle_account_locked
+
+  private
+
+  def handle_account_locked(error)
+    render json: {
+      error: "account_locked",
+      message: "Your account has been locked. Please contact support.",
+      locked_at: error.locked_at&.iso8601
+      # Note: Consider not exposing lock_reason to end users for security
+    }, status: :forbidden
+  end
+end
+```
+
+### Event Subscriptions
+
+Both `AccountStatus` and `AccountLocking` subscribe to the same events (`OAUTH_TOKEN_ISSUING`, `SESSION_CREATING`, `SESSION_VALIDATING`). The lock check runs alongside the status check - authentication fails if either condition prevents access.
+
 ## Usage Examples
 
 ### Web Authentication

data/app/controllers/concerns/standard_id/inertia_rendering.rb

@@ -0,0 +1,49 @@
+module StandardId
+  module InertiaRendering
+    extend ActiveSupport::Concern
+
+    included do
+      include StandardId::InertiaSupport
+    end
+
+    private
+
+    # Render with Inertia if enabled, otherwise use standard Rails rendering
+    def render_with_inertia(action: nil, props: {}, component: nil, status: :ok, **options)
+      if use_inertia?
+        component_name = component || inertia_component_name(action)
+        render inertia: component_name, props: props, status: status, **options
+      else
+        render_options = { status: status }
+        render_options[:action] = action if action.present?
+        render_options.merge!(options.except(:inertia, :props))
+        render(**render_options)
+      end
+    end
+
+    # Generate the Inertia component name based on controller and action
+    def inertia_component_name(action = nil)
+      namespace = StandardId.config.inertia_component_namespace.presence || "standard_id"
+      controller_name = self.class.name.demodulize.delete_suffix("Controller")
+      action_str = (action || self.action_name).to_s
+
+      "#{namespace}/#{controller_name}/#{action_str}"
+    end
+
+    # Build common props for authentication pages
+    def auth_page_props(additional_props = {})
+      {
+        redirect_uri: @redirect_uri,
+        connection: @connection,
+        flash: {
+          notice: flash[:notice],
+          alert: flash[:alert]
+        }.compact,
+        social_providers: {
+          google_enabled: StandardId.config.google_client_id.present?,
+          apple_enabled: StandardId.config.apple_client_id.present?
+        }
+      }.deep_merge(additional_props)
+    end
+  end
+end

data/app/controllers/concerns/standard_id/inertia_support.rb

@@ -0,0 +1,31 @@
+module StandardId
+  module InertiaSupport
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :use_inertia?
+    end
+
+    private
+
+    # Check if Inertia rendering should be used
+    def use_inertia?
+      StandardId.config.use_inertia && inertia_available?
+    end
+
+    # Check if inertia_rails gem is available in the host application
+    def inertia_available?
+      defined?(::InertiaRails)
+    end
+
+    # Redirect to an external URL or non-Inertia endpoint
+    # Uses inertia_location for Inertia requests, otherwise standard redirect_to
+    def redirect_with_inertia(url, **options)
+      if use_inertia? && request.inertia?
+        inertia_location url
+      else
+        redirect_to url, **options
+      end
+    end
+  end
+end

data/app/controllers/concerns/standard_id/set_current_request_details.rb

@@ -0,0 +1,19 @@
+module StandardId
+  module SetCurrentRequestDetails
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_current_request_details
+    end
+
+    private
+
+    def set_current_request_details
+      return unless defined?(::Current)
+
+      ::Current.request_id = request.request_id if ::Current.respond_to?(:request_id=)
+      ::Current.ip_address = request.remote_ip if ::Current.respond_to?(:ip_address=)
+      ::Current.user_agent = request.user_agent if ::Current.respond_to?(:user_agent=)
+    end
+  end
+end