passkey_auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a60423909de7215a1cc93d2c5d3d9720f33dbe36a845de57df87fb99035eef08
+  data.tar.gz: '0985d40feba5052547a0a1855513aab775fb8c8770186409ea328cf32cd8d007'
+SHA512:
+  metadata.gz: 06af92a77355abde48623fad8fd6044f7b031ab67d576cb7075de84a384dd0ecec2842f0714e56ad24b07ea3bc472b244c948d7d67e5159056d1c5ef7d117d3f
+  data.tar.gz: 2f1070b3717de924749f3660f4b6c04051f4e38cc984acd35568825670e3720900c4cce145befa988eb9c9b24d641c8cf947e7b2573591f53ce6df3796b0159e

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-30
+
+### Initial Release
+
+#### Features
+- **Passwordless Authentication**: Magic links with email verification codes and WebAuthn passkeys
+- **Session Management**: Secure session tracking with user agent and IP address
+- **Rate Limiting**: Built-in rate limiting for magic link requests (configurable)
+- **WebAuthn/Passkey Support**: Full passkey authentication with platform authenticators and security keys
+- **Customizable Hooks**: Add custom behavior to authentication events (login, logout, magic link requested, passkey created)
+- **I18n Support**: Internationalization with English translations included
+- **JavaScript Integration**: Stimulus controllers for passkey authentication and registration
+- **Rails Engine**: Mountable Rails engine with isolated namespace
+- **Installation Generator**: One-command installation with migrations, initializer, and JavaScript setup
+
+#### Components
+- **Models**: Session, MagicLink, WebauthnCredential, and Authenticatable concern for User model
+- **Controllers**: Sessions, MagicLinks, WebAuthn Credentials/Authentications with challenge endpoints
+- **Views**: Minimal, customizable views for login, magic link creation, and code verification
+- **Mailers**: Magic link email with both link and verification code
+- **JavaScript**: Stimulus controllers for passkey authentication, registration, and auth flows
+- **Configuration**: Flexible configuration with sensible defaults
+
+#### Requirements
+- Ruby >= 3.2
+- Rails >= 7.0
+- Hotwire (Turbo + Stimulus)
+- @github/webauthn-json (automatically configured via importmap)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jeremy Baker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,334 @@
+# PasskeyAuth
+
+A Rails engine that adds passwordless authentication methods to your Rails app using WebAuthn passkeys and magic links with email verification codes. Works seamlessly alongside Rails' built-in authentication system.
+
+## Features
+
+- **Complements Rails Authentication**: Works with `rails generate authentication` - doesn't replace it
+- **Passwordless Options**: Give users alternatives to password authentication
+- **WebAuthn/Passkey Support**: Modern biometric and hardware-key authentication
+- **Magic Links**: Email-based authentication with short verification codes
+- **Rate Limiting**: Built-in protection against abuse
+- **Customizable Hooks**: Add your own behavior to authentication events
+- **I18n Support**: Fully internationalized with English translations included
+- **Rails 8+ Compatible**: Designed for modern Rails applications
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'passkey_auth'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install passkey_auth
+```
+
+## Setup
+
+### 1. Install Rails Authentication (if not already done)
+
+PasskeyAuth requires Rails' authentication system. If you haven't already:
+
+```bash
+rails generate authentication
+```
+
+This creates the base authentication system with sessions, User model, and the Authentication concern.
+
+**Important:** Ensure your Rails app has a `root` route defined in `config/routes.rb`. PasskeyAuth redirects users to the root URL after authentication.
+
+### 2. Install PasskeyAuth
+
+```bash
+rails generate passkey_auth:install
+```
+
+This will:
+- Create migrations for magic links and WebAuthn credentials
+- Add passwordless fields to your users table
+- Add an initializer at `config/initializers/passkey_auth.rb`
+- Mount the engine routes
+- Copy JavaScript controllers
+
+### 3. Add to your User model
+
+```ruby
+class User < ApplicationRecord
+  has_secure_password  # From Rails authentication
+  include PasskeyAuth::Concerns::Passwordless  # Add passwordless methods
+
+  # Optional: If you prefer using :email instead of :email_address
+  alias_attribute :email, :email_address
+end
+```
+
+**Note:** Rails 8's authentication uses `email_address` as the attribute name. PasskeyAuth defaults to this, but you can configure it in the initializer if your app uses a different attribute name.
+
+### 4. Register Stimulus Controllers
+
+Add the PasskeyAuth Stimulus controllers to your `app/javascript/controllers/application.js`:
+
+```javascript
+import { application } from "./application"
+import { PasskeyAuthenticationController, WebauthnRegisterController, WebauthnAuthController }
+  from "passkey_auth/controllers"
+
+// Register PasskeyAuth controllers
+application.register("passkey-authentication", PasskeyAuthenticationController)
+application.register("webauthn-register", WebauthnRegisterController)
+application.register("webauthn-auth", WebauthnAuthController)
+```
+
+**Note:** The installer automatically adds the required JavaScript dependencies to your importmap. If you're using a different bundler (esbuild, webpack, etc.), install the WebAuthn dependency:
+
+```bash
+npm install @github/webauthn-json
+```
+
+### 5. Run migrations
+
+```bash
+rails db:migrate
+```
+
+## Usage
+
+### How It Works
+
+PasskeyAuth provides **alternative authentication methods** that work alongside password-based auth:
+
+- **Password auth** (Rails): `SessionsController` handles traditional email/password login
+- **Magic links** (PasskeyAuth): Users can request email-based login codes
+- **Passkeys** (PasskeyAuth): Users can register biometric/hardware keys for login
+
+All three methods use the **same session management** from Rails' Authentication concern. You simply give users more options for how they authenticate.
+
+### Session Management
+
+PasskeyAuth uses Rails' session management methods from the Authentication concern:
+
+- `current_user` - Access the authenticated user
+- `start_new_session_for(user)` - Log a user in
+- `terminate_session` - Log the user out
+- `allow_unauthenticated_access` - Allow public access to actions
+
+These are provided by Rails' `Authentication` concern in your `ApplicationController`.
+
+### Magic Links
+
+Offer magic link authentication as an alternative to passwords:
+
+```erb
+<!-- In your login page -->
+<%= link_to "Sign in with email code", passkey_auth.new_magic_link_path %>
+```
+
+Users can then:
+1. Enter their email address
+2. Receive an email with a magic link and short code
+3. Click the link or enter the code to authenticate
+
+The magic link flow:
+- `GET /auth/magic_links/new` - Request form
+- `POST /auth/magic_links` - Send magic link email
+- `GET /auth/magic_links/verify_code` - Code entry form
+- `POST /auth/magic_links/verify_with_code` - Verify code
+- `GET /auth/magic_links/:token` - Verify token from email link
+
+### Passkeys (WebAuthn)
+
+Configure the WebAuthn origin in the initializer:
+
+```ruby
+PasskeyAuth.setup do |config|
+  config.webauthn_origin = ENV.fetch("WEBAUTHN_ORIGIN", "http://localhost:3000")
+  config.webauthn_rp_name = "Your App Name"
+end
+```
+
+#### Adding Passkey Sign-In Button
+
+Add the passkey authentication UI to your sign-in page:
+
+```erb
+<div data-controller="passkey-authentication"
+     data-passkey-authentication-challenge-path-value="<%= passkey_auth.webauthn_credentials_challenge_path(format: :json) %>"
+     data-passkey-authentication-authentication-path-value="<%= passkey_auth.webauthn_authentications_path(format: :json) %>">
+
+  <button type="button"
+          data-passkey-authentication-target="signinButton"
+          data-action="click->passkey-authentication#signIn">
+    Sign in with Passkey
+  </button>
+</div>
+```
+
+#### Registering a New Passkey
+
+Allow users to register new passkeys in their profile:
+
+```erb
+<%= form_with url: passkey_auth.webauthn_credentials_path,
+              data: {
+                controller: "webauthn-register",
+                webauthn_register_callback_url_value: passkey_auth.webauthn_credentials_path,
+                action: "submit->webauthn-register#submit"
+              } do |form| %>
+  <%= form.text_field :nickname, placeholder: "Name this passkey", data: { webauthn_register_target: "nickname" } %>
+  <%= form.submit "Add Passkey" %>
+<% end %>
+```
+
+## Configuration
+
+Edit `config/initializers/passkey_auth.rb`:
+
+```ruby
+PasskeyAuth.setup do |config|
+  # User model (default: "User")
+  config.user_model_name = "User"
+
+  # Email attribute on User model (default: :email_address)
+  # Rails 8 uses :email_address, but you can change this if your app uses :email
+  # Or use alias_attribute in your User model instead
+  config.user_email_attribute = :email_address
+
+  # Magic link expiration (default: 10.minutes)
+  config.magic_link_expiration = 10.minutes
+
+  # Rate limit for magic links (default: 1.minute)
+  config.magic_link_rate_limit = 1.minute
+
+  # WebAuthn settings
+  config.webauthn_origin = ENV.fetch("WEBAUTHN_ORIGIN")
+  config.webauthn_rp_name = "Your App"
+end
+```
+
+### Email Attribute Configuration
+
+Rails 8's authentication uses `email_address` as the default attribute name. PasskeyAuth respects this default, but you have two options if you prefer using `email`:
+
+**Option 1: Use alias_attribute in your User model (recommended)**
+```ruby
+class User < ApplicationRecord
+  has_secure_password
+  include PasskeyAuth::Concerns::Passwordless
+
+  alias_attribute :email, :email_address
+end
+```
+
+**Option 2: Configure PasskeyAuth to use :email**
+```ruby
+PasskeyAuth.setup do |config|
+  config.user_email_attribute = :email
+end
+```
+
+### Hooks
+
+Add custom behavior to authentication events:
+
+```ruby
+PasskeyAuth.setup do |config|
+  config.on_magic_link_requested = ->(user, magic_link) {
+    # Track magic link requests
+    Analytics.track(user_id: user.id, event: 'magic_link_requested')
+  }
+
+  config.on_passkey_created = ->(user, credential) {
+    # Track passkey creation
+    Analytics.track(user_id: user.id, event: 'passkey_created')
+  }
+end
+```
+
+## Customization
+
+### Views
+
+Override any view by creating a file at the corresponding path in your app:
+
+```
+app/views/passkey_auth/magic_links/new.html.erb
+app/views/passkey_auth/magic_links/verify_code.html.erb
+app/views/passkey_auth/webauthn/credentials/index.html.erb
+```
+
+### Mailers
+
+Override the magic link email template:
+
+```
+app/views/passkey_auth/magic_link_mailer/login_link.html.erb
+```
+
+### Routes
+
+The engine is mounted at `/auth` by default. Change this in `config/routes.rb`:
+
+```ruby
+mount PasskeyAuth::Engine => "/authentication"
+```
+
+## Security Considerations
+
+- Magic links expire after 10 minutes by default
+- Magic links can only be used once
+- Rate limiting prevents abuse (1 request per minute by default)
+- Sessions are managed by Rails' Authentication concern
+- WebAuthn credentials use public key cryptography
+- All sensitive operations use database transactions
+
+## Architecture
+
+PasskeyAuth is designed to complement, not replace, Rails authentication:
+
+**What Rails Provides:**
+- `Authentication` concern for session management
+- `SessionsController` for password-based login
+- `current_user`, `start_new_session_for`, etc.
+- User model with `has_secure_password`
+
+**What PasskeyAuth Adds:**
+- `Passwordless` concern with magic link and passkey methods
+- Controllers for magic link and WebAuthn flows
+- Models for storing magic links and WebAuthn credentials
+- JavaScript for browser WebAuthn integration
+
+Users can authenticate with **any of these methods**, and all use the same session system.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 8.0 (with `rails generate authentication` installed)
+- PostgreSQL, MySQL, or SQLite
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/passkey_auth. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/passkey_auth/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PasskeyAuth project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/passkey_auth/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/app/controllers/passkey_auth/application_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PasskeyAuth
+  class ApplicationController < ::ApplicationController
+    private
+
+    # Override after_authentication_url to work in engine context
+    # The main app's Authentication concern calls root_url which doesn't exist here
+    def after_authentication_url
+      session.delete(:return_to_after_authenticating) || main_app.root_url
+    end
+  end
+end

data/app/controllers/passkey_auth/magic_links_controller.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module PasskeyAuth
+  class MagicLinksController < PasskeyAuth::ApplicationController
+    # Expects Rails Authentication concern to provide:
+    # - allow_unauthenticated_access
+    # - start_new_session_for(user)
+    # - after_authentication_url
+    # - new_session_path (for error redirects)
+
+    allow_unauthenticated_access
+
+    def new
+      @email = params[:email]
+    end
+
+    def create
+      email = params[:email]&.downcase&.strip
+      user = PasskeyAuth.user_class.find_by(email: email)
+
+      if user
+        result = user.send_magic_link!
+      else
+        result = { success: false, error: "user_not_found" }
+      end
+
+      if result[:success]
+        session[:passkey_auth_magic_link_email] = email
+        redirect_to verify_code_magic_links_path
+      else
+        handle_error(result[:error])
+      end
+    end
+
+    def show
+      link = MagicLink.consume_by_token(params[:token], ip: request.ip, user_agent: request.user_agent)
+
+      if link
+        user = link.user
+
+        # Clear any previous session values
+        if current_user && current_user.id != user.id
+          reset_session
+        end
+
+        # Log the user in
+        start_new_session_for(user)
+
+        # If user has no passkeys, suggest setting one up after login
+        if user.webauthn_credentials.none?
+          session[:suggest_passkey_setup] = true
+          redirect_to after_authentication_url, notice: I18n.t("passkey_auth.magic_links.success_with_passkey_prompt")
+        else
+          redirect_to after_authentication_url, notice: I18n.t("passkey_auth.magic_links.success")
+        end
+      else
+        redirect_to new_session_path, alert: error_message(link)
+      end
+    end
+
+    def verify_code
+      @email = session[:passkey_auth_magic_link_email]
+      redirect_to new_magic_link_path if @email.blank?
+    end
+
+    def verify_with_code
+      email = params[:email]&.downcase&.strip
+      short_code = MagicLink::ShortCode.clean(params[:code])
+
+      link = MagicLink.consume_by_email_and_code(email, short_code, ip: request.ip, user_agent: request.user_agent)
+
+      if link
+        user = link.user
+
+        # Clear the session email
+        session.delete(:passkey_auth_magic_link_email)
+
+        # Log the user in
+        start_new_session_for(user)
+
+        # If user has no passkeys, suggest setting one up after login
+        if user.webauthn_credentials.none?
+          session[:suggest_passkey_setup] = true
+          redirect_to after_authentication_url, notice: I18n.t("passkey_auth.magic_links.success_with_passkey_prompt")
+        else
+          redirect_to after_authentication_url, notice: I18n.t("passkey_auth.magic_links.success")
+        end
+      else
+        flash.now[:alert] = error_message(link)
+        @email = email
+        render :verify_code, status: :unprocessable_content
+      end
+    end
+
+    private
+
+    def handle_error(error)
+      case error
+      when "rate_limited"
+        redirect_to new_session_path, alert: I18n.t("passkey_auth.magic_links.errors.rate_limited")
+      when "user_not_found"
+        redirect_to new_session_path, alert: I18n.t("passkey_auth.magic_links.errors.user_not_found")
+      else
+        redirect_to new_session_path, alert: I18n.t("passkey_auth.magic_links.errors.send_failed")
+      end
+    end
+
+    def error_message(link)
+      if link.nil?
+        I18n.t("passkey_auth.magic_links.errors.invalid_code")
+      elsif link.expired?
+        I18n.t("passkey_auth.magic_links.errors.expired")
+      elsif link.used?
+        I18n.t("passkey_auth.magic_links.errors.already_used")
+      else
+        I18n.t("passkey_auth.magic_links.errors.generic")
+      end
+    end
+  end
+end