standard_id 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9b8808e874cdc6e89dca4b7ed1bb9636ae510d3947d48eb6f82933d40a6d9d1
-  data.tar.gz: 9fbd9e342e280da87695e011d5d6f031530eee53ced1c9ef93dbba4af072c141
+  metadata.gz: d8da5350b060ff2f0494489d5cc6718cc08b2dbca835a9c28927e228b712e39d
+  data.tar.gz: 96ac14f364fd07b8d6750d31bd015b7bc2717d692206a203b3fe8161a6a1008f
 SHA512:
-  metadata.gz: 1a6264b3b7f1dcf8e0f3f00861eb265d535bc8254352e6dd6c95c64dd59756db7ddf96cace31200ac0a9bb557710316a2306cdf1c52e75b5d13644530c0749e4
-  data.tar.gz: 5c6f5126077d8e8ca4598cf9668001b5517004ad8b444cb1fb04301979790cb2da2ed44b7f8ebeb7d75bbbd50f0ddc0fb758c40a4bbeeb9a453d975b1a66825a
+  metadata.gz: 195c91598a768df91279b0c6bda4d8b312f73a94d4c52c68b2864fd75453f2c474059c4f7d740e0d8c0b4086471ea193c9ded4bb7b492f3c098c950f941f6140
+  data.tar.gz: 80d64202a7b69456e241952b79f0a65ea9a88ed8b242ff31015e11854d141bd32ccbeaccc2f60ccddf78d188dbbec74e48f839c9181a2b4cdce01917001e4125

data/README.md

@@ -1,10 +1,44 @@
 # StandardId
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+A comprehensive authentication engine for Rails applications, built on the security primitives introduced in Rails 7/8. StandardId provides a complete, secure-by-default solution for identity management, reducing boilerplate and eliminating common security pitfalls.
+
+## Features
+
+### 🔐 Complete Authentication System
+- **Web Authentication**: Cookie-based sessions with CSRF protection
+- **API Authentication**: JWT-based tokens for API access
+- **Dual Engine Architecture**: Separate web (`/`) and API (`/api`) endpoints
+- **Session Management**: Browser sessions, device sessions, and service sessions with STI
+
+### 🚀 OAuth 2.0 & OpenID Connect
+- **Authorization Code Flow**: Standard OAuth flow with PKCE support
+- **Implicit Flow**: For single-page applications
+- **Client Credentials Flow**: For service-to-service authentication
+- **Password Flow**: Direct username/password authentication
+- **Refresh Token Flow**: Automatic token renewal
+- **Social Login**: Google OAuth and Apple Sign In integration
+
+### 📱 Passwordless Authentication
+- **Email OTP**: Send one-time passwords via email
+- **SMS OTP**: Send one-time passwords via SMS
+- **Configurable Delivery**: Host app controls message delivery
+- **10-minute Expiry**: Secure time-limited codes
+
+### 🏢 Multi-Tenant Support
+- **Client Management**: OAuth clients with secret rotation
+- **Polymorphic Ownership**: Clients can belong to accounts, organizations, etc.
+- **Scope Management**: Fine-grained permission control
+- **Redirect URI Validation**: Secure callback handling
+
+### 🔑 Advanced Security
+- **PKCE Support**: Proof Key for Code Exchange
+- **JWT Tokens**: Stateless authentication with configurable expiry
+- **Secret Rotation**: Client secret management with audit trail
+- **Remember Me**: Extended session support
+- **Account Lockout**: Protection against brute force attacks
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -13,16 +47,322 @@ gem "standard_id"
 
 And then execute:
 ```bash
-$ bundle
+$ bundle install
+```
+
+## Quick Start
+
+### 1. Generate Configuration
+
+```bash
+rails generate standard_id:install
+```
+
+### 2. Configure Your Account Model
+
+```ruby
+# config/initializers/standard_id.rb
+StandardId.configure do |config|
+  config.account_class_name = "User" # or "Account"
+  config.issuer = "https://your-app.com"
+  config.login_url = "/login"
+end
+```
+
+### 3. Mount the Engines
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount StandardId::WebEngine, at: "/", as: :standard_id_web
+
+  namespace :api do
+    mount StandardId::ApiEngine, at: "/", as: :standard_id_api
+  end
+end
+```
+
+### 4. Include Authentication in Controllers
+
+```ruby
+# For web controllers
+class ApplicationController < ActionController::Base
+  include StandardId::WebAuthentication
+end
+
+# For API controllers
+class ApiController < ActionController::API
+  include StandardId::ApiAuthentication
+end
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+StandardId.configure do |config|
+  # Required: Your account model
+  config.account_class_name = "User"
+
+  # OAuth issuer for ID tokens
+  config.issuer = "https://your-app.com"
+
+  # Login URL for redirects
+  config.login_url = "/login"
+
+  # 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) }
+
+  # Subset configuration
+  # config.password.minimum_length = 12
+  # config.password.require_special_chars = true
+  # config.passwordless.code_ttl = 600
+  # config.oauth.default_token_lifetime = 3600
+  # config.oauth.refresh_token_lifetime = 2_592_000
+  # config.oauth.token_lifetimes = {
+  #   password: 8.hours.to_i,
+  #   implicit: 15.minutes.to_i
+  # }
+end
+```
+
+`default_token_lifetime` is applied to every OAuth grant unless you override it in `oauth.token_lifetimes`. Keys map to OAuth grant types (for example `:password`, `:client_credentials`, `:refresh_token`) and should return durations in seconds. Non-token endpoint flows such as the implicit flow can be customized with their symbol key (e.g. `:implicit`). Refresh tokens can be tuned separately through `oauth.refresh_token_lifetime`.
+
+### Social Login Setup
+
+```ruby
+StandardId.configure do |config|
+  # Google OAuth
+  config.social.google_client_id = ENV["GOOGLE_CLIENT_ID"]
+  config.social.google_client_secret = ENV["GOOGLE_CLIENT_SECRET"]
+
+  # Apple Sign In
+  config.social.apple_client_id = ENV["APPLE_CLIENT_ID"]
+  config.social.apple_private_key = ENV["APPLE_PRIVATE_KEY"]
+  config.social.apple_key_id = ENV["APPLE_KEY_ID"]
+  config.social.apple_team_id = ENV["APPLE_TEAM_ID"]
+end
+```
+
+### Passwordless Authentication
+
+```ruby
+StandardId.configure do |config|
+  # Email delivery
+  config.passwordless_email_sender = ->(email, code) {
+    UserMailer.send_code(email, code).deliver_now
+  }
+
+  # SMS delivery
+  config.passwordless_sms_sender = ->(phone, code) {
+    SmsService.send_code(phone, code)
+  }
+end
+```
+
+## Usage Examples
+
+### Web Authentication
+
+```erb
+<!-- Login form -->
+<%= form_with url: login_path, local: true do |f| %>
+  <%= f.email_field :email, placeholder: "Email" %>
+  <%= f.password_field :password, placeholder: "Password" %>
+  <%= f.check_box :remember_me %>
+  <%= f.label :remember_me, "Remember me" %>
+  <%= f.submit "Sign In" %>
+<% end %>
+```
+
+### OAuth Authorization
+
+```ruby
+# Redirect to authorization endpoint
+redirect_to "/api/authorize?" + {
+  response_type: "code",
+  client_id: "your_client_id",
+  redirect_uri: "https://your-app.com/callback",
+  scope: "openid profile email",
+  state: "random_state_value"
+}.to_query
+```
+
+### Social Login
+
+```ruby
+# Google login
+redirect_to "/api/authorize?" + {
+  response_type: "code",
+  client_id: "your_client_id",
+  redirect_uri: "https://your-app.com/callback",
+  connection: "google-oauth2"
+}.to_query
+
+# Apple login
+redirect_to "/api/authorize?" + {
+  response_type: "code",
+  client_id: "your_client_id",
+  redirect_uri: "https://your-app.com/callback",
+  connection: "apple"
+}.to_query
+```
+
+### Passwordless Authentication
+
+```ruby
+# Start passwordless flow
+POST /api/passwordless/start
+{
+  "connection": "email",
+  "username": "user@example.com"
+}
+
+# Verify code
+POST /api/passwordless/verify
+{
+  "connection": "email",
+  "username": "user@example.com",
+  "otp": "123456"
+}
+```
+
+### API Authentication
+
+```ruby
+# In your API controllers
+class Api::UsersController < ApiController
+  before_action :authenticate_account!
+
+  def show
+    render json: current_account
+  end
+end
+```
+
+## Database Schema
+
+StandardId creates the following tables:
+
+- `standard_id_accounts` - User accounts
+- `standard_id_identifiers` - Email/phone identifiers (STI)
+- `standard_id_sessions` - Authentication sessions (STI)
+- `standard_id_clients` - OAuth clients
+- `standard_id_client_secret_credentials` - Client secrets
+- `standard_id_password_credentials` - Password storage
+- `standard_id_code_challenges` - OTP codes for authentication and verification
+
+## API Endpoints
+
+### Web Routes (mounted at `/`)
+- `GET /login` - Login form
+- `POST /login` - Process login
+- `POST /logout` - Logout
+- `GET /signup` - Signup form
+- `POST /signup` - Process signup
+- `GET /account` - Account management
+- `GET /sessions` - Active sessions
+
+### API Routes (mounted at `/api`)
+- `GET /authorize` - OAuth authorization endpoint
+- `POST /oauth/token` - Token exchange endpoint
+- `GET /userinfo` - OpenID Connect userinfo
+- `POST /passwordless/start` - Start passwordless flow
+- `POST /passwordless/verify` - Verify OTP code
+- `GET /oauth/callback/google` - Google OAuth callback
+- `POST /oauth/callback/apple` - Apple Sign In callback
+
+## Client Management
+
+```ruby
+# Create OAuth client
+client = StandardId::ClientApplication.create!(
+  owner: current_account,
+  name: "My Application",
+  redirect_uris: "https://app.com/callback",
+  grant_types: ["authorization_code", "refresh_token"],
+  response_types: ["code"],
+  scopes: ["openid", "profile", "email"]
+)
+
+# Generate client secret
+secret = client.create_client_secret!(name: "Production Secret")
+
+# Rotate client secret
+new_secret = client.rotate_client_secret!
 ```
 
-Or install it yourself as:
+## Schema DSL
+
+Schema is declared using a routes-like DSL and can be extended by provider gems:
+
+```ruby
+# core gem (already provided)
+require "standard_id/config/schema"
+
+StandardConfig.schema.draw do
+  scope :base do
+    field :account_class_name, type: :string, default: "User"
+  end
+
+  scope :social do
+    field :google_client_id, type: :string, default: nil
+  end
+end
+
+# provider gem
+require "standard_id/config/schema"
+
+StandardConfig.schema.draw do
+  scope :social do
+    field :my_provider_client_id, type: :string, default: nil
+  end
+end
+```
+
+Notes:
+
+- Multiple `schema.draw` calls are additive; the same scope can be extended in multiple files/gems.
+- Redefining an existing field will emit a warning; last definition wins.
+
+## Testing
+
+StandardId includes comprehensive test coverage:
+
 ```bash
-$ gem install standard_id
+# Run all tests
+bundle exec rspec
+
+# Run specific test suites
+bundle exec rspec spec/models/
+bundle exec rspec spec/controllers/
 ```
 
+## Security Considerations
+
+- All passwords are hashed using bcrypt
+- JWT tokens are signed and verified
+- CSRF protection enabled for web requests
+- Secure session management with proper expiry
+- Client secrets are rotatable with audit trail
+- PKCE support for public clients
+- Rate limiting on authentication endpoints
+
 ## Contributing
-Contribution directions go here.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`bin/rspec`)
+5. Commit your changes (`git commit -am 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -123,22 +123,21 @@ module StandardId
 
         identifier = StandardId::EmailIdentifier.find_by(value: email)
 
-        if identifier
-          identifier.account
-        else
-          account = Account.create!(
-            name: (user_info["name"] || user_info["given_name"] || email),
-            email: email
-          )
-
-          StandardId::EmailIdentifier.create!(
-            account: account,
-            value: email,
-            verified_at: Time.current
-          )
-
-          account
-        end
+        return identifier.account if identifier.present?
+
+        account = Account.create!(
+          name: (user_info["name"] || user_info["given_name"] || email),
+          email:
+        )
+
+        identifier = StandardId::EmailIdentifier.create!(
+          account:,
+          value: email
+        )
+
+        identifier.verify!
+
+        account
       end
 
       def generate_authorization_code

data/app/controllers/standard_id/web/verify_email/base_controller.rb

@@ -0,0 +1,9 @@
+module StandardId
+  module Web
+    module VerifyEmail
+      class BaseController < StandardId::Web::BaseController
+        skip_before_action :require_browser_session!
+      end
+    end
+  end
+end

data/app/controllers/standard_id/web/verify_email/confirm_controller.rb

@@ -0,0 +1,41 @@
+module StandardId
+  module Web
+    module VerifyEmail
+      class ConfirmController < BaseController
+        before_action :prepare_code_challenge
+
+        def show
+          return redirect_to(standard_id_web.login_path, alert: "Invalid or expired verification code") if @challenge.nil?
+          render plain: "verify email confirm", status: :ok
+        end
+
+        def update
+          return redirect_to(standard_id_web.login_path, alert: "Invalid or expired verification code") if @challenge.nil?
+
+          identifier = StandardId::EmailIdentifier.find_by(value: @challenge.target)
+          if identifier.present?
+            identifier.verify!
+          end
+          @challenge.use!
+
+          redirect_to standard_id_web.login_path, notice: "Your email has been verified. Please sign in.", status: :see_other
+        end
+
+        private
+
+        def prepare_code_challenge
+          email = params[:email].to_s.strip.downcase
+          code = params[:code].to_s
+          return @challenge = nil if email.blank? || code.blank?
+
+          @challenge = StandardId::CodeChallenge.active.find_by(
+            realm: "verification",
+            channel: "email",
+            target: email,
+            code: code
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/standard_id/web/verify_email/start_controller.rb

@@ -0,0 +1,39 @@
+module StandardId
+  module Web
+    module VerifyEmail
+      class StartController < BaseController
+        def show
+          render plain: "verify email start", status: :ok
+        end
+
+        def create
+          email = params[:email].to_s.strip.downcase
+          if email.blank?
+            flash[:alert] = "Please enter your email address"
+            render plain: "missing email", status: :unprocessable_content and return
+          end
+
+          challenge = StandardId::CodeChallenge.create!(
+            realm: "verification",
+            channel: "email",
+            target: email,
+            code: generate_otp_code,
+            expires_at: 10.minutes.from_now,
+            ip_address: request.remote_ip,
+            user_agent: request.user_agent
+          )
+
+          StandardId.config.passwordless_email_sender&.call(email, challenge.code)
+
+          redirect_to standard_id_web.login_path, notice: "Verification code sent to your email", status: :see_other
+        end
+
+        private
+
+        def generate_otp_code
+          (SecureRandom.random_number(900_000) + 100_000).to_s
+        end
+      end
+    end
+  end
+end

data/app/controllers/standard_id/web/verify_phone/base_controller.rb

@@ -0,0 +1,9 @@
+module StandardId
+  module Web
+    module VerifyPhone
+      class BaseController < StandardId::Web::BaseController
+        skip_before_action :require_browser_session!
+      end
+    end
+  end
+end

data/app/controllers/standard_id/web/verify_phone/confirm_controller.rb

@@ -0,0 +1,41 @@
+module StandardId
+  module Web
+    module VerifyPhone
+      class ConfirmController < BaseController
+        before_action :prepare_code_challenge
+
+        def show
+          return redirect_to(standard_id_web.login_path, alert: "Invalid or expired verification code") if @challenge.nil?
+          render plain: "verify phone confirm", status: :ok
+        end
+
+        def update
+          return redirect_to(standard_id_web.login_path, alert: "Invalid or expired verification code") if @challenge.nil?
+
+          identifier = StandardId::PhoneNumberIdentifier.find_by(value: @challenge.target)
+          if identifier.present?
+            identifier.verify!
+          end
+          @challenge.use!
+
+          redirect_to standard_id_web.login_path, notice: "Your phone number has been verified. Please sign in.", status: :see_other
+        end
+
+        private
+
+        def prepare_code_challenge
+          phone = params[:phone_number].to_s.strip
+          code = params[:code].to_s
+          return @challenge = nil if phone.blank? || code.blank?
+
+          @challenge = StandardId::CodeChallenge.active.find_by(
+            realm: "verification",
+            channel: "sms",
+            target: phone,
+            code: code
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/standard_id/web/verify_phone/start_controller.rb

@@ -0,0 +1,39 @@
+module StandardId
+  module Web
+    module VerifyPhone
+      class StartController < BaseController
+        def show
+          render plain: "verify phone start", status: :ok
+        end
+
+        def create
+          phone = params[:phone_number].to_s.strip
+          if phone.blank? || !(phone.match?(/\A\+?[1-9]\d{1,14}\z/))
+            flash[:alert] = "Please enter a valid phone number"
+            render plain: "invalid phone", status: :unprocessable_content and return
+          end
+
+          challenge = StandardId::CodeChallenge.create!(
+            realm: "verification",
+            channel: "sms",
+            target: phone,
+            code: generate_otp_code,
+            expires_at: 10.minutes.from_now,
+            ip_address: request.remote_ip,
+            user_agent: request.user_agent
+          )
+
+          StandardId.config.passwordless_sms_sender&.call(phone, challenge.code)
+
+          redirect_to standard_id_web.login_path, notice: "Verification code sent via SMS", status: :see_other
+        end
+
+        private
+
+        def generate_otp_code
+          (SecureRandom.random_number(900_000) + 100_000).to_s
+        end
+      end
+    end
+  end
+end

data/app/forms/standard_id/web/signup_form.rb

@@ -39,26 +39,15 @@ module StandardId
       private
 
       def account_params
-        # Placeholder for account fields. Add/permit additional attributes as needed.
-        {
-          name: (email.to_s.split("@").first.presence || "User"),
-          email: email
-        }
+        { name: (email.to_s.split("@").first.presence || "User"), email: }
       end
 
       def email_identifier_params
-        {
-          value: email,
-          verified_at: Time.current,
-          type: "StandardId::EmailIdentifier"
-        }
+        { type: "StandardId::EmailIdentifier", value: email }
       end
 
       def password_credential_params
-        {
-          login: email,
-          password: password
-        }
+        { login: email, password: }
       end
     end
   end

data/app/models/standard_id/client_application.rb

@@ -94,7 +94,8 @@ module StandardId
     def create_client_secret!(name: "Default Secret", **options)
       client_secret_credentials.create!({
         name: name,
-        client_id: client_id
+        client_id: client_id,
+        scopes: scopes
       }.merge(options))
     end
 

data/app/models/standard_id/{passwordless_challenge.rb → code_challenge.rb}

@@ -1,10 +1,14 @@
 module StandardId
-  class PasswordlessChallenge < ApplicationRecord
-    self.table_name = "standard_id_passwordless_challenges"
+  class CodeChallenge < ApplicationRecord
+    self.table_name = "standard_id_code_challenges"
 
-    validates :connection_type, presence: true, inclusion: { in: %w[email sms] }
-    validates :username, presence: true
-    validates :code, presence: true, uniqueness: { scope: [:connection_type, :username, :expires_at] }
+    REALMS = %w[authentication verification].freeze
+    CHANNELS = %w[email sms].freeze
+
+    validates :realm, presence: true, inclusion: { in: REALMS }
+    validates :channel, presence: true, inclusion: { in: CHANNELS }
+    validates :target, presence: true
+    validates :code, presence: true
     validates :expires_at, presence: true
 
     scope :active, -> { where(used_at: nil).where("expires_at > ?", Time.current) }

data/app/models/standard_id/email_identifier.rb

@@ -1,5 +1,7 @@
 module StandardId
   class EmailIdentifier < Identifier
+    normalizes :value, with: ->(e) { e.strip.downcase }
+
     validates :value, format: { with: URI::MailTo::EMAIL_REGEXP }
   end
 end