passkey_auth 0.1.0

data/app/models/passkey_auth/magic_link.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PasskeyAuth
+  class MagicLink < ApplicationRecord
+    self.table_name = "passkey_auth_magic_links"
+
+    belongs_to :user, class_name: PasskeyAuth.user_model_name, foreign_key: :user_id
+
+    PURPOSES = %w[login recovery email_confirmation].freeze
+
+    has_secure_token :token, length: 32
+
+    validates :expires_at, presence: true
+    validates :purpose, inclusion: { in: PURPOSES }
+
+    scope :active, -> { where(used_at: nil).where("expires_at > ?", Time.current) }
+    scope :expired, -> { where("expires_at <= ?", Time.current) }
+    scope :used, -> { where.not(used_at: nil) }
+
+    before_validation :set_defaults, on: :create
+
+    def expired?
+      expires_at <= Time.current
+    end
+
+    def used?
+      used_at.present?
+    end
+
+    def valid_for_use?
+      !expired? && !used?
+    end
+
+    def use!(ip: nil, user_agent: nil)
+      with_lock do
+        return false unless valid_for_use?
+
+        update!(
+          used_at: Time.current,
+          ip_address: ip,
+          user_agent: user_agent
+        )
+      end
+    end
+
+    def self.consume_by_token(token, ip:, user_agent:)
+      link = find_by(token: token)
+
+      return unless link
+
+      link.use!(ip: ip, user_agent: user_agent) ? link : nil
+    end
+
+    def self.consume_by_email_and_code(email, code, ip:, user_agent:)
+      cleaned_code  = code&.upcase&.strip
+      cleaned_email = email&.downcase&.strip
+
+      # Use configured email attribute
+      email_attr = PasskeyAuth.user_email_attribute
+      link = includes(:user).find_by(short_code: cleaned_code, user: { email_attr => cleaned_email })
+
+      return unless link
+
+      link.use!(ip: ip, user_agent: user_agent) ? link : nil
+    end
+
+    def self.generate_short_code
+      ShortCode.generate
+    end
+
+    def self.cleanup_expired
+      expired.destroy_all
+    end
+
+    def invalid_reason
+      if expired?
+        :expired
+      elsif used?
+        :used
+      else
+        :generic
+      end
+    end
+
+    private
+
+    def set_defaults
+      self.short_code ||= self.class.generate_short_code
+      self.expires_at ||= PasskeyAuth.magic_link_expiration.from_now
+    end
+  end
+end

data/app/models/passkey_auth/webauthn_credential.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PasskeyAuth
+  class WebauthnCredential < ApplicationRecord
+    self.table_name = "passkey_auth_webauthn_credentials"
+
+    belongs_to :user, class_name: PasskeyAuth.user_model_name, foreign_key: :user_id
+
+    validates :external_id, presence: true, uniqueness: true
+    validates :public_key, presence: true
+    validates :nickname, presence: true, uniqueness: { scope: :user_id }
+    validates :sign_count, presence: true, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+  end
+end

data/app/views/passkey_auth/magic_link_mailer/login_link.html.erb

@@ -0,0 +1,45 @@
+<div style="padding: 40px;">
+  <h1 style="color: #1a1a1a; font-size: 24px; font-weight: 600; margin: 0 0 24px 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.title") %>
+  </h1>
+
+  <p style="color: #4a4a4a; font-size: 16px; line-height: 24px; margin: 0 0 16px 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.greeting", name: @user.try(:first_name) || PasskeyAuth.user_email(@user).split("@").first) %>
+  </p>
+
+  <p style="color: #4a4a4a; font-size: 16px; line-height: 24px; margin: 0 0 32px 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.body") %>
+  </p>
+
+  <div style="text-align: center; margin: 32px 0;">
+    <%= link_to I18n.t("passkey_auth.magic_link_mailer.login_link.button"), @url,
+        style: "display: inline-block; padding: 14px 32px; background-color: #5469d4; color: white; text-decoration: none; border-radius: 6px; font-weight: 600; font-size: 16px;" %>
+  </div>
+
+  <p style="color: #4a4a4a; font-size: 16px; line-height: 24px; margin: 32px 0 16px 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.code_prompt") %>
+  </p>
+
+  <p style="font-size: 28px; font-weight: 600; text-align: center; letter-spacing: 2px; color: #1a1a1a; margin: 16px 0 32px 0;" data-otp="<%= @short_code.tr('-', '') %>">
+    <%= @short_code %>
+  </p>
+
+  <p style="color: #6b6b6b; font-size: 14px; line-height: 20px; margin: 0 0 16px 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.copy_link") %><br>
+    <%= @url %>
+  </p>
+
+  <p style="color: #6b6b6b; font-size: 14px; line-height: 20px; margin: 0 0 16px 0;">
+    <strong><%= I18n.t("passkey_auth.magic_link_mailer.login_link.expires", minutes: @expires_in) %></strong>
+  </p>
+
+  <p style="color: #6b6b6b; font-size: 14px; line-height: 20px; margin: 0 0 16px 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.ignore") %>
+  </p>
+
+  <hr style="border: none; border-top: 1px solid #e5e5e5; margin: 32px 0;">
+
+  <p style="color: #9a9a9a; font-size: 12px; line-height: 18px; margin: 0;">
+    <%= I18n.t("passkey_auth.magic_link_mailer.login_link.security_notice") %>
+  </p>
+</div>

data/app/views/passkey_auth/magic_links/new.html.erb

@@ -0,0 +1,19 @@
+<div class="passkey-auth-container">
+  <h1><%= I18n.t("passkey_auth.magic_links.new.title") %></h1>
+  <p><%= I18n.t("passkey_auth.magic_links.new.description") %></p>
+
+  <%= form_with url: magic_links_path do |form| %>
+    <div class="form-group">
+      <%= form.label :email %>
+      <%= form.email_field :email,
+          required: true,
+          autofocus: true,
+          placeholder: I18n.t("passkey_auth.magic_links.new.email_placeholder"),
+          value: @email || params[:email] %>
+    </div>
+
+    <%= form.submit I18n.t("passkey_auth.magic_links.new.submit_button"), class: "btn btn-primary" %>
+  <% end %>
+
+  <p><%= link_to I18n.t("passkey_auth.magic_links.new.back_to_login"), new_session_path %></p>
+</div>

data/app/views/passkey_auth/magic_links/verify_code.html.erb

@@ -0,0 +1,21 @@
+<div class="passkey-auth-container">
+  <h1><%= I18n.t("passkey_auth.magic_links.verify_code.title") %></h1>
+  <p><%= I18n.t("passkey_auth.magic_links.verify_code.description", email: @email) %></p>
+
+  <%= form_with url: verify_with_code_magic_links_path do |form| %>
+    <%= form.hidden_field :email, value: @email %>
+
+    <div class="form-group">
+      <%= form.label :code, I18n.t("passkey_auth.magic_links.verify_code.code_label") %>
+      <%= form.text_field :code,
+          required: true,
+          autofocus: true,
+          autocomplete: "one-time-code",
+          placeholder: "XXXX-XXXX" %>
+    </div>
+
+    <%= form.submit I18n.t("passkey_auth.magic_links.verify_code.submit_button"), class: "btn btn-primary" %>
+  <% end %>
+
+  <p><%= I18n.t("passkey_auth.magic_links.verify_code.cant_find_code_html", request_new_url: new_magic_link_path(email: @email)) %></p>
+</div>

data/config/locales/en.yml

@@ -0,0 +1,53 @@
+en:
+  passkey_auth:
+    sessions:
+      new:
+        title: "Sign In"
+        email_placeholder: "Enter your email"
+        submit: "Continue with Email"
+      invalid_credentials: "Invalid credentials"
+
+    magic_links:
+      new:
+        title: "Sign In with Magic Link"
+        description: "Enter your email to receive a sign-in link"
+        email_placeholder: "your@email.com"
+        submit_button: "Send Magic Link"
+        back_to_login: "Back to sign in"
+      verify_code:
+        title: "Enter Your Code"
+        description: "We sent a code to %{email}"
+        code_label: "Verification Code"
+        submit_button: "Verify Code"
+        cant_find_code_html: "Can't find the code? <a href='%{request_new_url}'>Request a new one</a>"
+      success: "Successfully signed in"
+      success_with_passkey_prompt: "Successfully signed in. Consider setting up a passkey for faster sign-in next time."
+      errors:
+        rate_limited: "Too many requests. Please wait a moment before trying again."
+        user_not_found: "No account found with that email address."
+        send_failed: "Failed to send magic link. Please try again."
+        invalid_code: "Invalid or expired code"
+        expired: "This link has expired. Please request a new one."
+        already_used: "This link has already been used"
+        generic: "Something went wrong. Please try again."
+
+    magic_link_mailer:
+      login_link:
+        subject: "Your login code is %{code}"
+        title: "Sign In"
+        greeting: "Hi %{name},"
+        body: "You requested a sign-in link. Click the button below to sign in:"
+        button: "Sign In"
+        code_prompt: "Or enter this code if prompted:"
+        copy_link: "Or copy and paste this link into your browser:"
+        expires: "This link and code will expire in %{minutes} minutes."
+        ignore: "If you didn't request this link, you can safely ignore this email."
+        security_notice: "For security reasons, this link can only be used once. If you need another link, please request a new one."
+
+    webauthn:
+      session_expired: "Session expired. Please refresh the page and try again."
+      verification_failed: "Passkey verification failed"
+      authentication_failed: "Passkey verification failed. Please try signing in with your email."
+      passkey_not_registered: "This passkey is not registered. Please sign in with your email and register this passkey."
+      unexpected_error: "An unexpected error occurred. Please try signing in with your email."
+      credential_deleted: "Passkey deleted successfully"

data/config/routes.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+PasskeyAuth::Engine.routes.draw do
+  resource :session, only: %i[new show create destroy]
+
+  resources :magic_links, only: %i[new create] do
+    collection do
+      get :verify_code
+      post :verify_with_code
+    end
+  end
+
+  get "magic_links/:token", to: "magic_links#show", as: :verify_magic_link
+
+  namespace :webauthn do
+    resources :credentials, only: %i[index create destroy] do
+      collection do
+        resource :challenge, only: %i[create], module: :credentials, as: :credentials_challenge
+      end
+    end
+
+    resources :authentications, only: %i[index create] do
+      collection do
+        resource :challenge, only: %i[create], module: :authentications, as: :authentications_challenge
+      end
+    end
+  end
+end

data/lib/generators/passkey_auth/install/install_generator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module PasskeyAuth
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs PasskeyAuth and generates necessary migrations and initializer"
+
+      def copy_migrations
+        migration_template "create_passkey_auth_magic_links.rb.erb",
+                          "db/migrate/create_passkey_auth_magic_links.rb",
+                          migration_version: migration_version
+        migration_template "create_passkey_auth_webauthn_credentials.rb.erb",
+                          "db/migrate/create_passkey_auth_webauthn_credentials.rb",
+                          migration_version: migration_version
+        migration_template "add_passwordless_to_users.rb.erb",
+                          "db/migrate/add_passwordless_to_users.rb",
+                          migration_version: migration_version
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/passkey_auth.rb"
+      end
+
+      def add_routes
+        route 'mount PasskeyAuth::Engine => "/auth"'
+      end
+
+      def copy_javascript_files
+        # Copy JavaScript controllers from the gem's app/javascript directory
+        source_paths << File.expand_path("../../../../app/javascript", __dir__)
+        directory "passkey_auth", "app/javascript/passkey_auth"
+      end
+
+      def install_javascript_dependencies
+        say "\nInstalling JavaScript dependencies...", :yellow
+
+        if File.exist?("config/importmap.rb")
+          append_to_file "config/importmap.rb" do
+            <<~RUBY
+
+              # PasskeyAuth dependencies
+              pin "@github/webauthn-json", to: "https://ga.jspm.io/npm:@github/webauthn-json@2.1.1/dist/esm/webauthn-json.js"
+              pin "@rails/request.js", to: "https://ga.jspm.io/npm:@rails/request.js@0.0.9/src/index.js"
+              pin "passkey_auth/controllers", to: "passkey_auth/controllers/index.js"
+              pin "passkey_auth/controllers/passkey_authentication_controller"
+              pin "passkey_auth/controllers/webauthn_register_controller"
+              pin "passkey_auth/controllers/webauthn_auth_controller"
+              pin "passkey_auth/lib/passkey"
+            RUBY
+          end
+          say "Added importmap pins for PasskeyAuth", :green
+        else
+          say "\nWARNING: config/importmap.rb not found.", :yellow
+          say "If you're using a different JavaScript bundler (esbuild, webpack, etc.),"
+          say "make sure to add @github/webauthn-json as a dependency:", :yellow
+          say "\n  npm install @github/webauthn-json\n", :cyan
+        end
+      end
+
+      def display_post_install_message
+        say "\n"
+        say "PasskeyAuth installed successfully!", :green
+        say "\n"
+        say "Next steps:", :yellow
+        say "  1. Ensure you have Rails authentication installed (rails generate authentication)"
+        say "  2. Add 'include PasskeyAuth::Concerns::Passwordless' to your User model"
+        say "  3. Run 'rails db:migrate' to create the necessary tables"
+        say "  4. Configure the initializer at config/initializers/passkey_auth.rb"
+        say "  5. Register Stimulus controllers in app/javascript/controllers/application.js:"
+        say ""
+        say "     import { PasskeyAuthenticationController, WebauthnRegisterController, WebauthnAuthController }", :cyan
+        say "       from 'passkey_auth/controllers'", :cyan
+        say "     application.register('passkey-authentication', PasskeyAuthenticationController)", :cyan
+        say "     application.register('webauthn-register', WebauthnRegisterController)", :cyan
+        say "     application.register('webauthn-auth', WebauthnAuthController)", :cyan
+        say "\n"
+        say "PasskeyAuth works alongside Rails' authentication system.", :yellow
+        say "Users can authenticate with passwords (Rails) OR passwordless methods (this gem)."
+        say "\n"
+        say "See the README for more details: https://github.com/jhubert/passkey_auth"
+        say "\n"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/passkey_auth/install/templates/add_passwordless_to_users.rb.erb

@@ -0,0 +1,8 @@
+class AddPasswordlessToUsers < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :users, :webauthn_id, :string
+    add_column :users, :magic_link_sent_at, :datetime
+
+    add_index :users, :webauthn_id, unique: true
+  end
+end

data/lib/generators/passkey_auth/install/templates/create_passkey_auth_magic_links.rb.erb

@@ -0,0 +1,21 @@
+class CreatePasskeyAuthMagicLinks < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :passkey_auth_magic_links do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :token, null: false
+      t.string :short_code, null: false
+      t.datetime :expires_at, null: false
+      t.datetime :used_at
+      t.string :ip_address
+      t.string :user_agent
+      t.string :purpose, default: "login", null: false
+
+      t.timestamps
+    end
+
+    add_index :passkey_auth_magic_links, :token, unique: true
+    add_index :passkey_auth_magic_links, :short_code
+    add_index :passkey_auth_magic_links, [:user_id, :expires_at]
+    add_index :passkey_auth_magic_links, :expires_at
+  end
+end

data/lib/generators/passkey_auth/install/templates/create_passkey_auth_webauthn_credentials.rb.erb

@@ -0,0 +1,16 @@
+class CreatePasskeyAuthWebauthnCredentials < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :passkey_auth_webauthn_credentials do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :external_id, null: false
+      t.string :public_key, null: false
+      t.string :nickname, null: false
+      t.integer :sign_count, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :passkey_auth_webauthn_credentials, :external_id, unique: true
+    add_index :passkey_auth_webauthn_credentials, [:nickname, :user_id], unique: true
+  end
+end

data/lib/generators/passkey_auth/install/templates/initializer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+PasskeyAuth.setup do |config|
+  # The name of your User model (default: "User")
+  # config.user_model_name = "User"
+
+  # The email attribute on your User model (default: :email_address)
+  # Rails 8 uses :email_address by default
+  # If your User model uses :email, set this to :email
+  # Or use alias_attribute in your User model: alias_attribute :email, :email_address
+  # config.user_email_attribute = :email_address
+
+  # How long magic links are valid (default: 10.minutes)
+  # config.magic_link_expiration = 10.minutes
+
+  # Rate limit for magic link requests (default: 1.minute)
+  # config.magic_link_rate_limit = 1.minute
+
+  # WebAuthn configuration
+  # config.webauthn_origin = ENV.fetch("WEBAUTHN_ORIGIN", "http://localhost:3000")
+  # config.webauthn_rp_name = "Your App Name"
+
+  # Hooks - add custom behavior to passwordless authentication events
+  # config.on_magic_link_requested = ->(user, magic_link) { puts "Magic link requested" }
+  # config.on_passkey_created = ->(user, credential) { puts "Passkey created" }
+end

data/lib/passkey_auth/concerns/passwordless.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module PasskeyAuth
+  module Concerns
+    module Passwordless
+      extend ActiveSupport::Concern
+
+      class AuthenticationError < StandardError; end
+
+      included do
+        has_many :passkey_auth_magic_links,
+          class_name: "PasskeyAuth::MagicLink",
+          foreign_key: :user_id,
+          dependent: :delete_all
+
+        has_many :passkey_auth_webauthn_credentials,
+          class_name: "PasskeyAuth::WebauthnCredential",
+          foreign_key: :user_id,
+          dependent: :delete_all
+
+        # Friendly aliases
+        alias_method :magic_links, :passkey_auth_magic_links
+        alias_method :webauthn_credentials, :passkey_auth_webauthn_credentials
+
+        validates :webauthn_id, uniqueness: true, allow_blank: true
+      end
+
+      # Magic link authentication methods
+      def can_request_magic_link?
+        return true if magic_link_sent_at.nil?
+
+        # Rate limit based on configuration
+        magic_link_sent_at < PasskeyAuth.magic_link_rate_limit.ago
+      end
+
+      def create_magic_link!(purpose: "login")
+        return nil unless can_request_magic_link?
+
+        transaction do
+          # Expire any existing active magic links
+          magic_links.active.update_all(used_at: Time.current)
+
+          # Create new magic link
+          magic_link = magic_links.create!(purpose: purpose)
+
+          # Update rate limiting timestamp
+          update!(magic_link_sent_at: Time.current)
+
+          magic_link
+        end
+      end
+
+      def send_magic_link!
+        unless can_request_magic_link?
+          return { success: false, error: "rate_limited" }
+        end
+
+        magic_link = create_magic_link!
+
+        if magic_link
+          PasskeyAuth::MagicLinkMailer.login_link(magic_link).deliver_later
+
+          # Call hook if configured
+          PasskeyAuth.on_magic_link_requested&.call(self, magic_link)
+
+          { success: true, magic_link: magic_link }
+        else
+          { success: false, error: "creation_failed" }
+        end
+      rescue StandardError => e
+        Rails.logger.error "MagicLink error: #{e.message}"
+        { success: false, error: "unexpected_error" }
+      end
+
+      class_methods do
+        def authenticate_with_webauthn(credential, challenge)
+          # Find the stored credential by external_id
+          stored_credential = PasskeyAuth::WebauthnCredential.find_by(external_id: credential.id)
+
+          raise AuthenticationError, "Passkey not registered" unless stored_credential
+
+          # Verify the credential against the stored_credential
+          credential.verify(
+            challenge,
+            public_key: stored_credential.public_key,
+            sign_count: stored_credential.sign_count
+          )
+
+          # Update the sign count to prevent replay attacks
+          stored_credential.update!(sign_count: credential.sign_count)
+
+          # Return the user
+          stored_credential.user
+        end
+      end
+
+      def passwordless?
+        webauthn_credentials.exists? || magic_links.active.exists?
+      end
+    end
+  end
+end

data/lib/passkey_auth/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "webauthn"
+
+module PasskeyAuth
+  class Engine < ::Rails::Engine
+    isolate_namespace PasskeyAuth
+
+    config.generators do |g|
+      g.test_framework :minitest
+      g.fixture_replacement :minitest
+    end
+
+    initializer "passkey_auth.set_configs" do
+      # Set WebAuthn configuration based on Rails environment
+      PasskeyAuth.webauthn_origin ||= begin
+        if Rails.env.production?
+          ENV.fetch("WEBAUTHN_ORIGIN", "https://example.com")
+        else
+          "http://localhost:3000"
+        end
+      end
+
+      # Configure WebAuthn gem
+      WebAuthn.configure do |config|
+        config.origin = PasskeyAuth.webauthn_origin
+        config.rp_name = PasskeyAuth.webauthn_rp_name
+      end
+    end
+  end
+end

data/lib/passkey_auth/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PasskeyAuth
+  VERSION = "0.1.0"
+end

data/lib/passkey_auth.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "passkey_auth/version"
+require_relative "passkey_auth/engine"
+require_relative "passkey_auth/concerns/passwordless"
+
+module PasskeyAuth
+  class Error < StandardError; end
+
+  # Configuration
+  mattr_accessor :user_model_name, default: "User"
+  mattr_accessor :user_email_attribute, default: :email_address # Rails 8 default
+  mattr_accessor :magic_link_expiration, default: 10.minutes
+  mattr_accessor :magic_link_rate_limit, default: 1.minute
+  mattr_accessor :webauthn_origin
+  mattr_accessor :webauthn_rp_name, default: "PasskeyAuth"
+
+  # Hooks - allow apps to add custom behavior
+  mattr_accessor :on_magic_link_requested, default: nil
+  mattr_accessor :on_passkey_created, default: nil
+
+  def self.setup
+    yield self
+  end
+
+  def self.user_class
+    user_model_name.constantize
+  end
+
+  # Helper to get the email attribute value from a user
+  def self.user_email(user)
+    user.public_send(user_email_attribute)
+  end
+end

data/sig/passkey_auth.rbs

@@ -0,0 +1,4 @@
+module PasskeyAuth
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end