standard_id 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a8069c98c5ede27fc1f485806e5a9b150d4f43294d177f59fe89008e11bd289
-  data.tar.gz: e88dae408bce4db81c42c780985d9e4a833b4864636a2d10b5ff979407dc9562
+  metadata.gz: 2878f305d6dfe83c5a1c0851cde68602cbd17899b1a676981afd8166f56995e0
+  data.tar.gz: 4c1802cc0bb54045165eb42289d75dda85db9a8838d61a6c1b4e7a7ff50e7828
 SHA512:
-  metadata.gz: 19f08dcd3da104952f2313669bc7bceb18ef0ce866ff234a0beb966e64d83294cefc76886c2f5e74080b935271444afeae0057deadcbac7bcfda40f6dd0441b4
-  data.tar.gz: 2531fba6a76ea0dd4800cebe0444a86cdea8ab516c64888b40b7d60aa681a957af2f3f4fb9622aebc6cf6f25b44a3caf0b3d03f16dcc673ce2f0a30c79599211
+  metadata.gz: 8073e2e1f0208261525be8218960ef6481e8a5558f281a56baf2316b4750f9557b37365831b9aa530706e2d52d6c088e3cc3e9c23c4a4ef722d641f2041ea357
+  data.tar.gz: a803c19a19f5fbcc3acae0511f629c6d4b1520d67a54cfa16d062fcc60333083d28cd5149a6658bfb16e37ae3a2ff1d7cdf06d657d16130010a08c67b8c851ff

data/README.md

@@ -123,9 +123,11 @@ StandardId.configure do |config|
   # config.use_inertia = true
   # config.inertia_component_namespace = "auth"
 
-  # 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) }
+  # 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
@@ -186,21 +188,24 @@ 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`.
 
+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.
@@ -355,22 +360,363 @@ end
 
 This will redirect unauthenticated users to the login page using `inertia_location` for Inertia requests, ensuring proper SPA navigation.
 
-### Passwordless Authentication
+### 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|
-  # Email delivery
-  config.passwordless_email_sender = ->(email, code) {
-    UserMailer.send_code(email, code).deliver_now
-  }
+  config.events.enable_logging = true
+end
+```
 
-  # SMS delivery
-  config.passwordless_sms_sender = ->(phone, code) {
-    SmsService.send_code(phone, code)
-  }
+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/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

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

@@ -2,64 +2,70 @@ module StandardId
   module SocialAuthentication
     extend ActiveSupport::Concern
 
+    included do
+      prepend_before_action :prepare_provider
+    end
+
     private
 
-    def get_user_info_from_provider(connection, redirect_uri: nil, flow: :web)
-      case connection
-      when "google"
-        StandardId::SocialProviders::Google.get_user_info(
-          code: params[:code],
-          id_token: params[:id_token],
-          access_token: params[:access_token],
-          redirect_uri: redirect_uri
-        )
-      when "apple"
-        StandardId::SocialProviders::Apple.get_user_info(
-        code: params[:code],
-          id_token: params[:id_token],
-          redirect_uri: redirect_uri,
-          client_id: apple_client_id_for_flow(flow)
-        )
-      else
-        raise StandardId::InvalidRequestError, "Unsupported provider: #{connection}"
-      end
+    attr_reader :provider
+
+    def prepare_provider
+      @provider = StandardId::ProviderRegistry.get(params[:provider])
+    rescue StandardId::ProviderRegistry::ProviderNotFoundError => e
+      raise StandardId::InvalidRequestError, e.message
     end
 
-    def apple_client_id_for_flow(flow)
-      flow == :web ? StandardId.config.apple_client_id : StandardId.config.apple_mobile_client_id
+    def get_user_info_from_provider(redirect_uri: nil, flow: :web)
+      provider_params = {
+        code: params[:code],
+        id_token: params[:id_token],
+        access_token: params[:access_token],
+        redirect_uri: redirect_uri
+      }
+
+      resolved_params = provider.resolve_params(provider_params, context: { flow: flow })
+      provider.get_user_info(**resolved_params.compact)
     end
 
-    def find_or_create_account_from_social(raw_social_info, provider)
+    def find_or_create_account_from_social(raw_social_info)
       social_info = raw_social_info.to_h.with_indifferent_access
       email = social_info[:email]
-      raise StandardId::InvalidRequestError, "No email provided by #{provider}" if email.blank?
+      raise StandardId::InvalidRequestError, "No email provided by #{provider.provider_name}" if email.blank?
+
+      emit_social_user_info_fetched(provider, social_info, email)
 
       identifier = StandardId::EmailIdentifier.find_by(value: email)
 
       if identifier.present?
+        emit_social_account_linked(identifier.account, provider, identifier)
         identifier.account
       else
-        account = build_account_from_social(social_info, provider)
+        account = build_account_from_social(social_info)
         identifier = StandardId::EmailIdentifier.create!(
           account: account,
           value: email
         )
         identifier.verify! if identifier.respond_to?(:verify!)
+        emit_social_account_created(account, provider, social_info)
         account
       end
     end
 
-    def build_account_from_social(social_info, provider)
-      attrs = resolve_account_attributes(social_info, provider)
-      StandardId.account_class.create!(attrs)
+    def build_account_from_social(social_info)
+      emit_account_creating_from_social(social_info)
+      attrs = resolve_account_attributes(social_info)
+      account = StandardId.account_class.create!(attrs)
+      emit_account_created_from_social(account)
+      account
     end
 
-    def resolve_account_attributes(social_info, provider)
+    def resolve_account_attributes(social_info)
       resolver = StandardId.config.social_account_attributes
       attrs = if resolver.respond_to?(:call)
                 payload = {
                   social_info: social_info,
-                  provider: provider
+                  provider: provider.provider_name
                 }
 
                 filtered_payload = StandardId::Utils::CallableParameterFilter.filter(resolver, payload)
@@ -95,18 +101,61 @@ module StandardId
     end
 
     def run_social_callback(provider:, social_info:, provider_tokens:, account:)
-      callback = StandardId.config.social_callback
-      return if callback.blank?
+      emit_social_auth_completed(provider, social_info, provider_tokens, account)
+    end
 
-      payload = {
+    def emit_social_user_info_fetched(provider, social_info, email)
+      StandardId::Events.publish(
+        StandardId::Events::SOCIAL_USER_INFO_FETCHED,
         provider: provider,
         social_info: social_info,
-        tokens: provider_tokens.presence,
-        account: account
-      }
+        email: email
+      )
+    end
+
+    def emit_social_account_created(account, provider, social_info)
+      StandardId::Events.publish(
+        StandardId::Events::SOCIAL_ACCOUNT_CREATED,
+        account: account,
+        provider: provider,
+        social_info: social_info
+      )
+    end
+
+    def emit_social_account_linked(account, provider, identifier)
+      StandardId::Events.publish(
+        StandardId::Events::SOCIAL_ACCOUNT_LINKED,
+        account: account,
+        provider: provider,
+        identifier: identifier
+      )
+    end
+
+    def emit_social_auth_completed(provider, social_info, provider_tokens, account)
+      StandardId::Events.publish(
+        StandardId::Events::SOCIAL_AUTH_COMPLETED,
+        account: account,
+        provider: provider,
+        social_info: social_info,
+        tokens: provider_tokens
+      )
+    end
+
+    def emit_account_creating_from_social(social_info)
+      StandardId::Events.publish(
+        StandardId::Events::ACCOUNT_CREATING,
+        account_params: resolve_account_attributes(social_info),
+        auth_method: "social:#{provider.provider_name}"
+      )
+    end
 
-      filtered_payload = StandardId::Utils::CallableParameterFilter.filter(callback, payload)
-      callback.call(**filtered_payload.symbolize_keys)
+    def emit_account_created_from_social(account)
+      StandardId::Events.publish(
+        StandardId::Events::ACCOUNT_CREATED,
+        account: account,
+        auth_method: "social:#{provider.provider_name}",
+        source: "social"
+      )
     end
   end
 end

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

@@ -49,11 +49,39 @@ module StandardId
       password = login_params[:password]
       remember_me = ActiveModel::Type::Boolean.new.cast(login_params[:remember_me])
 
+      StandardId::Events.publish(
+        StandardId::Events::AUTHENTICATION_ATTEMPT_STARTED,
+        account_lookup: login,
+        auth_method: "password"
+      )
+
       StandardId::PasswordCredential.find_by(login:).tap do |password_credential|
-        return nil unless password_credential&.authenticate(password)
+        unless password_credential&.authenticate(password)
+          StandardId::Events.publish(
+            StandardId::Events::AUTHENTICATION_FAILED,
+            account_lookup: login,
+            auth_method: "password",
+            error_code: "invalid_credentials",
+            error_message: "Invalid login or password"
+          )
+          return nil
+        end
+
+        StandardId::Events.publish(
+          StandardId::Events::PASSWORD_VALIDATED,
+          account: password_credential.account,
+          credential_id: password_credential.id
+        )
 
         session_manager.sign_in_account(password_credential.account)
         session_manager.set_remember_cookie(password_credential) if remember_me
+
+        StandardId::Events.publish(
+          StandardId::Events::AUTHENTICATION_SUCCEEDED,
+          account: password_credential.account,
+          auth_method: "password",
+          session_type: "browser"
+        )
       end
     end
 

data/app/controllers/standard_id/api/base_controller.rb

@@ -2,6 +2,7 @@ module StandardId
   module Api
     class BaseController < ActionController::API
       include StandardId::ApiAuthentication
+      include StandardId::SetCurrentRequestDetails
 
       before_action :validate_content_type!