gridauth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85097e7cf7d67aa8d52b82e97626bb04f0f3aa8046ed7309849afad8f974be0e
+  data.tar.gz: d939a2dbfeca35a2b5d272dc8c72f51198539a4ac637e95ff78f027dea4f8b1d
+SHA512:
+  metadata.gz: d78197f0d25364d893e93448cf78f152bf2e1457812fb5d2db76a923d5c92c339e080d48be1f4294e44ea83e0344307fb4811f1be0680f50edccdd30c6285fbc
+  data.tar.gz: fabc14d3a71e5d20db1516a01e1306563e47159eadad85e15e32f486c51c3703ded6bf7adaec3ef69a842f35187bb0042658f38f715302f3307a97a0c09be679

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: per-user grid cards, card rotation, sign-in challenge,
+  lockout, enrollment/rotation policies, install and views generators.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+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,261 @@
+# Gridauth
+
+Grid card two-factor authentication for Rails 8+ applications that use the
+built-in authentication generator (`bin/rails generate authentication`). It
+does not use Devise.
+
+A grid card is a small table of random characters, with lettered columns and
+numbered rows, that the user prints or saves:
+
+```
+     A   B   C   D   E   F   G   H   I   J
+ 1   7K  QF  M3  ...
+ 2   ...
+```
+
+After the usual email and password form, the user is asked for the characters
+in a few cells, for example **B3**, **F1** and **J4**. No session is created
+until those answers are correct.
+
+## Features
+
+- **One card per user**, generated with `SecureRandom`. The database stores
+  only per-cell HMAC-SHA256 digests, so the card can't be read back from it.
+- **Enrollment**: the user issues a card, views or prints it, and activates it
+  by answering a challenge from the new card. This proves they saved it.
+- **Rotation**: issuing a new card leaves the current one working until the
+  new one is activated. Then the old card is revoked. Cards can be due for
+  rotation by age (`rotation_period`), by number of sign-ins
+  (`rotate_after_uses`), or both. Rotation can be required (`enforce_rotation`).
+- **Sign-in challenge** after the password step, with:
+  - challenge cells that stay fixed until answered correctly, so repeated
+    sign-ins can't be used to "shop" for cells an attacker knows
+  - constant-time comparison of every cell
+  - a lockout after repeated failures, plus Rails `rate_limit`
+  - a time limit for the second step
+  - `reset_session` on both steps to prevent session fixation
+- **Optional enforcement**: every user can be required to enroll
+  (`enforce_enrollment`).
+- **Generators**: the install generator wires everything up. The views
+  generator copies the views into your app so you can customize them.
+- **I18n**: every message is in `config/locales/en.yml`.
+
+## Requirements
+
+- Rails 8.0 or later
+- Ruby 3.2 or later
+- An app that already ran `bin/rails generate authentication` (`User`,
+  `Session`, `Current` and the `Authentication` concern)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "gridauth"
+```
+
+```sh
+bundle install
+bin/rails generate gridauth:install
+bin/rails db:migrate
+```
+
+The install generator:
+
+1. creates `config/initializers/gridauth.rb`
+2. creates the `gridauth_grid_cards` migration
+3. adds `has_grid_card` to `app/models/user.rb`
+4. adds `include Gridauth::Authentication` to `ApplicationController`, after
+   `include Authentication`
+5. changes `SessionsController#create` from
+
+   ```ruby
+   start_new_session_for user
+   redirect_to after_authentication_url
+   ```
+
+   to
+
+   ```ruby
+   start_grid_card_challenge_for user
+   ```
+
+6. adds `gridauth_routes` to `config/routes.rb`
+
+If your `SessionsController` has been customized, the generator prints a
+message and you make step 5 by hand. Users without an active card still sign
+in with just their password.
+
+Then give signed-in users a link to their card settings:
+
+```erb
+<%= link_to "Two-factor authentication", gridauth_grid_card_path %>
+```
+
+## Routes
+
+`gridauth_routes` draws the routes straight into your app's route set (like
+`devise_for`), so the pages render in your layout and your route helpers work
+there. To use a different URL prefix, call `gridauth_routes path: "two-factor"`.
+
+| Helper | Request | Purpose |
+| --- | --- | --- |
+| `new_gridauth_challenge_path` | `GET /gridauth/challenge/new` | Challenge form shown after the password step |
+| `gridauth_challenge_path` | `POST /gridauth/challenge` | Check the answers and create the session |
+| `gridauth_challenge_path` | `DELETE /gridauth/challenge` | Cancel the sign-in |
+| `gridauth_grid_card_path` | `GET /gridauth/card` | Card status, enrollment and rotation |
+| `gridauth_grid_card_path` | `POST /gridauth/card` | Issue a new pending card |
+| `print_gridauth_grid_card_path` | `GET /gridauth/card/print` | Printable view of the pending card |
+| `activate_gridauth_grid_card_path` | `POST /gridauth/card/activate` | Activate the pending card |
+| `discard_gridauth_grid_card_path` | `DELETE /gridauth/card/discard` | Discard the pending card |
+| `gridauth_grid_card_path` | `DELETE /gridauth/card` | Turn grid card authentication off |
+
+## How it works
+
+### Sign-in
+
+1. `SessionsController#create` checks the password, then calls
+   `start_grid_card_challenge_for(user)`.
+2. If the user has an active card, Gridauth resets the Rails session and keeps
+   a short-lived "pending sign-in" (the user id and a timestamp) in it. It
+   then redirects to the challenge. The user is **not** signed in yet: no
+   `Session` record, no `session_id` cookie.
+3. The challenge page shows an empty grid with the requested cells
+   highlighted, plus one input per cell.
+4. If the answers are correct, Gridauth resets the session again, calls your
+   app's `start_new_session_for`, and redirects to `after_authentication_url`.
+   That is the page the user first asked for, or `root_url`. If the card is
+   due for rotation, the user goes to the card page instead.
+
+### Enrollment and rotation
+
+1. On `/gridauth/card` the user clicks **Set up a grid card** (or **Replace
+   grid card**). A *pending* card is created. Its plaintext is kept only in
+   the encrypted session cookie of the browser that issued it, so the user can
+   view and print it.
+2. The user activates it by entering the requested cells from the new card,
+   plus their current password (`require_password_for_changes`).
+3. Activation revokes any previous active card and removes the plaintext from
+   the session. After that the card can't be shown again. A lost card is
+   replaced by rotating, or reset by an administrator.
+
+## Configuration
+
+`config/initializers/gridauth.rb`:
+
+```ruby
+Gridauth.configure do |config|
+  config.user_class = "User"
+  config.parent_controller = "ApplicationController"
+  config.sign_in_route = :new_session_path
+
+  config.rows = 5                    # rows 1..5
+  config.columns = 10                # columns A..J (max 26)
+  config.cell_length = 2             # characters per cell
+  config.alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+  config.case_sensitive = false
+
+  config.challenge_size = 3          # cells per challenge
+  config.challenge_timeout = 5.minutes
+
+  config.max_failed_attempts = 5
+  config.lockout_period = 15.minutes
+
+  config.rotation_period = 180.days  # nil to disable
+  config.rotate_after_uses = nil     # e.g. 100
+
+  config.enforce_enrollment = false
+  config.enforce_rotation = false
+  config.policy_exempt_controllers = %w[sessions passwords]
+
+  config.require_password_for_changes = true
+  config.allow_disable = true
+  config.user_label_attribute = :email_address
+
+  # config.secret_key = Rails.application.credentials.dig(:gridauth, :secret_key)
+end
+```
+
+With the defaults, each cell has 32² = 1,024 possible values, so guessing a
+3-cell challenge has about a 1 in 10⁹ chance. Lockout and rate limiting cap
+how many guesses can be made.
+
+### Enforcement
+
+With `enforce_enrollment` or `enforce_rotation` turned on,
+`Gridauth::Authentication` adds a `before_action`. For a signed-in user who
+needs to act, it redirects HTML requests to the card page and answers other
+requests with `403 Forbidden`. To exempt more controllers, add them to
+`policy_exempt_controllers` or call this in the controller:
+
+```ruby
+skip_grid_card_policy only: :show
+```
+
+## Model API
+
+```ruby
+user.grid_card            # active Gridauth::GridCard, or nil
+user.pending_grid_card    # issued but not yet activated
+user.grid_card_enabled?
+card, grid = user.issue_grid_card!  # grid is the only plaintext copy
+user.revoke_grid_cards!   # e.g. after the user lost their card
+
+card.issue_challenge!     # => ["B3", "F1", "J4"]
+card.verify_challenge("B3" => "7K", "F1" => "QF", "J4" => "M3")  # => :success, :invalid or :locked
+card.rotation_due?
+card.rotation_due_at
+card.activate!
+card.revoke!
+```
+
+You can use `issue_grid_card!` to issue cards from your own code, for example
+to mail a printed card. Render `grid` with the
+`gridauth/shared/grid` partial.
+
+## Administration
+
+```sh
+bin/rails "gridauth:revoke[user@example.com]"   # lost card: back to password-only sign-in
+bin/rails gridauth:due                           # list cards due for rotation
+```
+
+## Customizing views
+
+```sh
+bin/rails generate gridauth:views
+```
+
+This copies the templates to `app/views/gridauth`. The pages render in your
+application layout. Their small amount of CSS is scoped under `.gridauth` and
+uses your Content Security Policy nonce, if you have one configured.
+
+## Security notes
+
+- Cell digests are HMAC-SHA256 with a per-card salt. The key is derived from
+  `secret_key_base`, or set with `config.secret_key`. **Changing that key
+  invalidates every issued card.**
+- A grid card is a "something you have" factor that can be photographed or
+  copied. Rotate cards regularly and keep `challenge_size` at 3 or more.
+- Anyone who knows a user's password can trigger the lockout, which locks
+  that user out temporarily. Tune `max_failed_attempts` and `lockout_period`
+  to balance this against brute-force protection.
+- The `cells` parameter, which holds challenge answers, is added to
+  `filter_parameters`, so answers never reach the logs.
+- The plaintext of a pending card lives in the Rails session until
+  activation. With the default cookie store, that cookie is encrypted.
+
+## Development
+
+```sh
+bundle install
+bin/rails test
+bin/rubocop
+```
+
+`test/dummy` is a Rails app built with `bin/rails generate authentication` and
+`bin/rails generate gridauth:install`.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/gridauth/application_controller.rb

@@ -0,0 +1,27 @@
+module Gridauth
+  class ApplicationController < Gridauth.config.parent_controller.to_s.constantize
+    helper Gridauth::GridHelper
+
+    skip_before_action :enforce_grid_card_policy, raise: false
+
+    private
+      def current_grid_card_user
+        Current.session&.user
+      end
+
+      def sign_in_url
+        public_send(Gridauth.config.sign_in_route)
+      end
+
+      # Hash of cell => answer submitted by the challenge form fields.
+      def challenge_answers
+        params.permit(cells: {}).fetch(:cells, {}).to_h
+      end
+
+      def password_confirmed?(user)
+        return true unless Gridauth.config.require_password_for_changes
+
+        params[:password].present? && user.authenticate(params[:password]).present?
+      end
+  end
+end

data/app/controllers/gridauth/challenges_controller.rb

@@ -0,0 +1,63 @@
+module Gridauth
+  # The second step of signing in: after SessionsController has checked the
+  # password, the user answers cells from their grid card here.
+  class ChallengesController < ApplicationController
+    allow_unauthenticated_access if respond_to?(:allow_unauthenticated_access)
+
+    rate_limit to: 10, within: 3.minutes, only: :create,
+      with: -> { redirect_to new_gridauth_challenge_path, alert: t("gridauth.challenges.rate_limited") }
+
+    before_action :load_pending_login, except: :destroy
+
+    def new
+      @cells = @card.issue_challenge! unless @card.locked?
+    end
+
+    def create
+      case @card.verify_challenge(challenge_answers)
+      when :success
+        complete_sign_in
+      when :locked
+        redirect_to new_gridauth_challenge_path, alert: t("gridauth.challenges.locked")
+      else
+        redirect_to new_gridauth_challenge_path, alert: t("gridauth.challenges.invalid")
+      end
+    end
+
+    def destroy
+      session.delete(Gridauth::PENDING_LOGIN_KEY)
+      redirect_to sign_in_url, status: :see_other
+    end
+
+    private
+      def load_pending_login
+        pending = session[Gridauth::PENDING_LOGIN_KEY]
+
+        unless pending.is_a?(Hash) && Time.zone.at(pending["started_at"].to_i) > Gridauth.config.challenge_timeout.ago
+          return abandon_sign_in(pending ? t("gridauth.challenges.expired") : nil)
+        end
+
+        @user = Gridauth.user_class.find_by(id: pending["user_id"])
+        @card = @user&.grid_card
+        abandon_sign_in(t("gridauth.challenges.expired")) unless @card
+      end
+
+      def abandon_sign_in(message)
+        session.delete(Gridauth::PENDING_LOGIN_KEY)
+        redirect_to sign_in_url, alert: message
+      end
+
+      def complete_sign_in
+        return_to = after_authentication_url
+        reset_session
+        start_new_session_for @user
+        @card.record_use!
+
+        if @card.rotation_due?
+          redirect_to gridauth_grid_card_path, notice: t("gridauth.policy.rotation_required")
+        else
+          redirect_to return_to
+        end
+      end
+  end
+end

data/app/controllers/gridauth/grid_cards_controller.rb

@@ -0,0 +1,85 @@
+module Gridauth
+  # Lets a signed-in user set up, print, rotate and (optionally) disable
+  # their grid card.
+  class GridCardsController < ApplicationController
+    before_action :set_user
+    before_action :set_pending_card, only: %i[ show print activate discard ]
+
+    def show
+      @card = @user.grid_card
+      @grid = new_card_grid
+      @cells = @pending_card.issue_challenge! if @grid && !@pending_card.locked?
+    end
+
+    # Issues a new pending card. If the user already has an active card it
+    # keeps working until the new one is activated (rotation).
+    def create
+      card, grid = @user.issue_grid_card!
+      session[Gridauth::NEW_CARD_KEY] = { "id" => card.id, "values" => grid.to_compact }
+      redirect_to gridauth_grid_card_path, notice: t("gridauth.grid_cards.issued")
+    end
+
+    def print
+      if (@grid = new_card_grid)
+        render layout: false
+      else
+        redirect_to gridauth_grid_card_path, alert: t("gridauth.grid_cards.unavailable")
+      end
+    end
+
+    # Confirms the user has saved the new card by answering a challenge from
+    # it, then makes it the active card and revokes the previous one.
+    def activate
+      return redirect_to(gridauth_grid_card_path, alert: t("gridauth.grid_cards.unavailable")) unless @pending_card
+      return redirect_to(gridauth_grid_card_path, alert: t("gridauth.grid_cards.wrong_password")) unless password_confirmed?(@user)
+
+      case @pending_card.verify_challenge(challenge_answers)
+      when :success
+        rotated = @user.grid_card_enabled?
+        @pending_card.activate!
+        session.delete(Gridauth::NEW_CARD_KEY)
+        redirect_to gridauth_grid_card_path, notice: t(rotated ? "gridauth.grid_cards.rotated" : "gridauth.grid_cards.activated")
+      when :locked
+        redirect_to gridauth_grid_card_path, alert: t("gridauth.challenges.locked")
+      else
+        redirect_to gridauth_grid_card_path, alert: t("gridauth.challenges.invalid")
+      end
+    end
+
+    def discard
+      @pending_card&.destroy!
+      session.delete(Gridauth::NEW_CARD_KEY)
+      redirect_to gridauth_grid_card_path, notice: t("gridauth.grid_cards.discarded"), status: :see_other
+    end
+
+    def destroy
+      if !Gridauth.config.allow_disable || Gridauth.config.enforce_enrollment
+        redirect_to gridauth_grid_card_path, alert: t("gridauth.grid_cards.disable_not_allowed"), status: :see_other
+      elsif !password_confirmed?(@user)
+        redirect_to gridauth_grid_card_path, alert: t("gridauth.grid_cards.wrong_password"), status: :see_other
+      else
+        @user.revoke_grid_cards!
+        session.delete(Gridauth::NEW_CARD_KEY)
+        redirect_to gridauth_grid_card_path, notice: t("gridauth.grid_cards.disabled"), status: :see_other
+      end
+    end
+
+    private
+      def set_user
+        @user = current_grid_card_user
+      end
+
+      def set_pending_card
+        @pending_card = @user.pending_grid_card
+      end
+
+      # The plaintext of the pending card, available only in the browser
+      # session that issued it.
+      def new_card_grid
+        stored = session[Gridauth::NEW_CARD_KEY]
+        return unless @pending_card && stored.is_a?(Hash) && stored["id"] == @pending_card.id
+
+        Grid.from_compact(stored["values"], rows: @pending_card.row_count, columns: @pending_card.column_count)
+      end
+  end
+end

data/app/helpers/gridauth/grid_helper.rb

@@ -0,0 +1,18 @@
+module Gridauth
+  module GridHelper
+    # Accessible description of a cell key, e.g. "B3" => "column B, row 3".
+    def gridauth_cell_description(cell)
+      column, row = cell.to_s.match(/\A([A-Z])(\d+)\z/)&.captures
+      t("gridauth.cell_description", column:, row:)
+    end
+
+    def gridauth_user_label(user)
+      attribute = Gridauth.config.user_label_attribute
+      user.public_send(attribute) if attribute && user.respond_to?(attribute)
+    end
+
+    def gridauth_styles
+      render "gridauth/shared/styles"
+    end
+  end
+end

data/app/models/gridauth/application_record.rb

@@ -0,0 +1,5 @@
+module Gridauth
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/gridauth/grid_card.rb

@@ -0,0 +1,154 @@
+require "openssl"
+
+module Gridauth
+  # A grid card belonging to a user. Only HMAC digests of the cell values are
+  # stored; the plaintext is shown once, when the card is issued.
+  #
+  # Lifecycle: pending (issued, awaiting confirmation) -> active -> revoked.
+  # A user has at most one active card; activating a new card revokes the old
+  # one, which is how rotation works.
+  class GridCard < ApplicationRecord
+    STATUSES = %w[pending active revoked].freeze
+    SERIAL_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789".chars.freeze
+
+    belongs_to :user, class_name: Gridauth.config.user_class, inverse_of: :grid_cards
+
+    serialize :cell_digests, coder: JSON
+
+    enum :status, STATUSES.index_by(&:itself), validate: true
+
+    validates :serial, presence: true, uniqueness: true
+    validates :row_count, :column_count, :cell_length, numericality: { only_integer: true, greater_than: 0 }
+    validates :salt, :cell_digests, presence: true
+
+    # Creates a pending card for `user` and returns `[card, grid]`.
+    def self.issue_for!(user, grid: Grid.generate)
+      transaction do
+        user.grid_cards.pending.delete_all
+
+        card = user.grid_cards.build(
+          serial: generate_serial,
+          row_count: grid.rows,
+          column_count: grid.columns,
+          cell_length: grid.values.each_value.first.length,
+          salt: SecureRandom.hex(16)
+        )
+        card.cell_digests = grid.values.to_h { |key, value| [ key, card.send(:digest_cell, key, value) ] }
+        card.save!
+
+        [ card, grid ]
+      end
+    end
+
+    def self.generate_serial
+      loop do
+        serial = Array.new(8) { SERIAL_ALPHABET[SecureRandom.random_number(SERIAL_ALPHABET.size)] }
+          .each_slice(4).map(&:join).join("-")
+        break serial unless exists?(serial:)
+      end
+    end
+
+    def column_labels = Grid.column_labels(column_count)
+    def row_labels = Grid.row_labels(row_count)
+    def cell_keys = Grid.cell_keys(row_count, column_count)
+
+    # Cells the user must answer next, e.g. ["B2", "F4", "J1"].
+    #
+    # A challenge stays the same until it has been answered correctly, so
+    # signing in over and over cannot be used to "shop" for cells an attacker
+    # happens to know.
+    def challenge_cells
+      self[:challenge_cells].to_s.split(",")
+    end
+
+    def issue_challenge!
+      with_lock do
+        if challenge_cells.empty?
+          size = Gridauth.config.challenge_size.clamp(1, cell_keys.size)
+          cells = cell_keys.sample(size, random: SecureRandom).sort_by { |key| cell_keys.index(key) }
+          update!(challenge_cells: cells.join(","))
+        end
+      end
+      challenge_cells
+    end
+
+    # Checks answers (a hash of cell => value) against the current challenge.
+    # Returns :success, :invalid or :locked. Wrong answers count towards the
+    # lockout; a correct answer resets the count and retires the challenge.
+    def verify_challenge(answers)
+      answers = (answers || {}).to_h.transform_keys { |key| key.to_s.upcase }
+
+      with_lock do
+        if locked?
+          :locked
+        elsif challenge_cells.empty?
+          :invalid
+        elsif challenge_cells.map { |cell| cell_matches?(cell, answers[cell]) }.all?
+          update!(challenge_cells: nil, failed_attempts: 0, locked_until: nil)
+          :success
+        else
+          register_failed_attempt
+        end
+      end
+    end
+
+    def locked?
+      locked_until.present? && locked_until.future?
+    end
+
+    def activate!
+      transaction do
+        user.grid_cards.active.where.not(id: id).find_each(&:revoke!)
+        update!(status: "active", activated_at: Time.current, challenge_cells: nil,
+          failed_attempts: 0, locked_until: nil, use_count: 0)
+      end
+    end
+
+    def revoke!
+      update!(status: "revoked", revoked_at: Time.current, challenge_cells: nil)
+    end
+
+    def record_use!
+      update!(use_count: use_count + 1, last_used_at: Time.current)
+    end
+
+    # When the card should be replaced based on age, if age-based rotation is on.
+    def rotation_due_at
+      activated_at + Gridauth.config.rotation_period if activated_at && Gridauth.config.rotation_period
+    end
+
+    def rotation_due?
+      return false unless active?
+
+      expired = rotation_due_at.present? && rotation_due_at <= Time.current
+      worn_out = Gridauth.config.rotate_after_uses.present? && use_count >= Gridauth.config.rotate_after_uses
+      expired || worn_out
+    end
+
+    private
+      def cell_matches?(cell, answer)
+        expected = cell_digests[cell]
+        expected.present? && ActiveSupport::SecurityUtils.secure_compare(expected, digest_cell(cell, answer))
+      end
+
+      def digest_cell(cell, value)
+        OpenSSL::HMAC.hexdigest("SHA256", Gridauth.config.secret_key, [ salt, cell, normalize(value) ].join(":"))
+      end
+
+      def normalize(value)
+        value = value.to_s.gsub(/\s+/, "")
+        Gridauth.config.case_sensitive ? value : value.upcase
+      end
+
+      def register_failed_attempt
+        attempts = failed_attempts + 1
+        if attempts >= Gridauth.config.max_failed_attempts
+          update!(failed_attempts: 0, locked_until: Time.current + Gridauth.config.lockout_period)
+          :locked
+        else
+          update!(failed_attempts: attempts)
+          :invalid
+        end
+      end
+  end
+end

data/app/views/gridauth/challenges/new.html.erb

@@ -0,0 +1,20 @@
+<%= gridauth_styles %>
+
+<div class="gridauth">
+  <h1><%= t(".title") %></h1>
+
+  <% if @card.locked? %>
+    <p class="gridauth-alert"><%= t(".locked", time: l(@card.locked_until.in_time_zone, format: :short)) %></p>
+  <% else %>
+    <p><%= t(".intro", serial: @card.serial) %></p>
+
+    <%= render "gridauth/shared/grid", card: @card, highlight: @cells %>
+
+    <%= form_with url: gridauth_challenge_path, method: :post do %>
+      <%= render "gridauth/shared/challenge_fields", cells: @cells, card: @card %>
+      <%= submit_tag t(".submit") %>
+    <% end %>
+  <% end %>
+
+  <p><%= button_to t(".cancel"), gridauth_challenge_path, method: :delete %></p>
+</div>