gridauth 0.1.0

data/app/views/gridauth/grid_cards/print.html.erb

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="robots" content="noindex">
+    <title><%= t(".title", serial: @pending_card.serial) %></title>
+    <%= gridauth_styles %>
+    <%= tag.style nonce: content_security_policy_nonce do %>
+      body { margin: 0; }
+      .gridauth-print { display: inline-block; margin: 1.5rem; padding: 1rem 1.25rem; border: 2px dashed #555; font-family: system-ui, sans-serif; }
+      .gridauth-print h1 { font-size: 1.1rem; margin: 0 0 0.5rem; }
+      @media print { .gridauth-no-print { display: none; } }
+    <% end %>
+  </head>
+  <body>
+    <div class="gridauth-print">
+      <h1><%= t(".title", serial: @pending_card.serial) %></h1>
+      <%= render "gridauth/shared/grid", card: @pending_card, grid: @grid %>
+      <p class="gridauth-card-meta">
+        <% if (label = gridauth_user_label(@user)) %>
+          <%= t(".issued_to") %>: <%= label %><br>
+        <% end %>
+        <%= t(".issued_at") %>: <%= l(@pending_card.created_at.in_time_zone.to_date, format: :long) %>
+      </p>
+      <p class="gridauth-card-meta"><%= t(".keep_safe") %></p>
+    </div>
+    <p class="gridauth-no-print"><button type="button" id="gridauth-print-button"><%= t(".print") %></button></p>
+    <%= javascript_tag nonce: true do %>
+      document.getElementById("gridauth-print-button").addEventListener("click", function () { window.print() })
+    <% end %>
+  </body>
+</html>

data/app/views/gridauth/grid_cards/show.html.erb

@@ -0,0 +1,89 @@
+<%= gridauth_styles %>
+
+<div class="gridauth">
+  <h1><%= t(".title") %></h1>
+
+  <% if @grid %>
+    <section>
+      <h2><%= t(".new_title") %></h2>
+      <p><%= t(".new_intro") %></p>
+      <p class="gridauth-card-meta"><%= t(".serial") %>: <strong><%= @pending_card.serial %></strong></p>
+      <%= render "gridauth/shared/grid", card: @pending_card, grid: @grid %>
+      <p><%= link_to t(".print"), print_gridauth_grid_card_path, target: "_blank", rel: "noopener" %></p>
+    </section>
+
+    <section>
+      <h2><%= t(".activate_title") %></h2>
+      <% if @pending_card.locked? %>
+        <p class="gridauth-alert"><%= t(".locked", time: l(@pending_card.locked_until.in_time_zone, format: :short)) %></p>
+      <% else %>
+        <p><%= t(".activate_intro") %></p>
+        <%= form_with url: activate_gridauth_grid_card_path, method: :post do %>
+          <%= render "gridauth/shared/challenge_fields", cells: @cells, card: @pending_card %>
+          <% if Gridauth.config.require_password_for_changes %>
+            <p>
+              <%= label_tag :gridauth_activate_password, t(".password") %><br>
+              <%= password_field_tag :password, nil, id: :gridauth_activate_password, required: true, autocomplete: "current-password" %>
+            </p>
+          <% end %>
+          <%= submit_tag t(".activate") %>
+        <% end %>
+      <% end %>
+      <p><%= button_to t(".discard"), discard_gridauth_grid_card_path, method: :delete %></p>
+    </section>
+  <% elsif @pending_card %>
+    <section>
+      <h2><%= t(".lost_title") %></h2>
+      <p><%= t(".lost") %></p>
+      <%= button_to t(".reissue"), gridauth_grid_card_path, method: :post %>
+    </section>
+  <% end %>
+
+  <% if @card %>
+    <section>
+      <h2><%= t(".active_title") %></h2>
+      <dl>
+        <dt><%= t(".serial") %></dt>
+        <dd><%= @card.serial %></dd>
+        <dt><%= t(".activated_at") %></dt>
+        <dd><%= l(@card.activated_at.in_time_zone, format: :long) %></dd>
+        <dt><%= t(".last_used_at") %></dt>
+        <dd><%= @card.last_used_at ? l(@card.last_used_at.in_time_zone, format: :long) : t(".never") %></dd>
+        <dt><%= t(".use_count") %></dt>
+        <dd><%= @card.use_count %></dd>
+        <% if @card.rotation_due_at %>
+          <dt><%= t(".rotation_due_at") %></dt>
+          <dd><%= l(@card.rotation_due_at.in_time_zone.to_date, format: :long) %></dd>
+        <% end %>
+      </dl>
+      <% if @card.rotation_due? %>
+        <p class="gridauth-alert"><%= t(".rotation_due") %></p>
+      <% end %>
+      <% unless @grid %>
+        <p><%= t(".rotate_intro") %></p>
+        <%= button_to t(".rotate"), gridauth_grid_card_path, method: :post %>
+      <% end %>
+    </section>
+
+    <% if Gridauth.config.allow_disable && !Gridauth.config.enforce_enrollment %>
+      <section>
+        <h2><%= t(".disable_title") %></h2>
+        <p><%= t(".disable_intro") %></p>
+        <%= form_with url: gridauth_grid_card_path, method: :delete do %>
+          <% if Gridauth.config.require_password_for_changes %>
+            <p>
+              <%= label_tag :gridauth_disable_password, t(".password") %><br>
+              <%= password_field_tag :password, nil, id: :gridauth_disable_password, required: true, autocomplete: "current-password" %>
+            </p>
+          <% end %>
+          <%= submit_tag t(".disable") %>
+        <% end %>
+      </section>
+    <% end %>
+  <% elsif !@pending_card %>
+    <section>
+      <p><%= t(".none") %></p>
+      <%= button_to t(".issue"), gridauth_grid_card_path, method: :post %>
+    </section>
+  <% end %>
+</div>

data/app/views/gridauth/shared/_challenge_fields.html.erb

@@ -0,0 +1,18 @@
+<%# locals: (cells:, card:) -%>
+<div class="gridauth-fields">
+  <% cells.each_with_index do |cell, index| %>
+    <label class="gridauth-field">
+      <span aria-hidden="true"><%= cell %></span>
+      <%= text_field_tag "cells[#{cell}]", nil,
+            id: "gridauth_cell_#{cell}",
+            required: true,
+            autofocus: index.zero?,
+            autocomplete: "off",
+            autocapitalize: "characters",
+            spellcheck: false,
+            maxlength: card.cell_length,
+            size: card.cell_length + 1,
+            aria: { label: gridauth_cell_description(cell) } %>
+    </label>
+  <% end %>
+</div>

data/app/views/gridauth/shared/_grid.html.erb

@@ -0,0 +1,22 @@
+<%# locals: (card:, grid: nil, highlight: []) -%>
+<table class="gridauth-table" aria-label="<%= t("gridauth.grid_cards.print.title", serial: card.serial) %>">
+  <thead>
+    <tr>
+      <th scope="col"></th>
+      <% card.column_labels.each do |column| %>
+        <th scope="col"><%= column %></th>
+      <% end %>
+    </tr>
+  </thead>
+  <tbody>
+    <% card.row_labels.each do |row| %>
+      <tr>
+        <th scope="row"><%= row %></th>
+        <% card.column_labels.each do |column| %>
+          <% key = "#{column}#{row}" %>
+          <%= tag.td grid ? grid[key] : "", class: ("gridauth-highlight" if highlight.include?(key)) %>
+        <% end %>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/gridauth/shared/_styles.html.erb

@@ -0,0 +1,18 @@
+<%= tag.style nonce: content_security_policy_nonce do %>
+  .gridauth { max-width: 44rem; margin: 2rem auto; font-family: system-ui, sans-serif; line-height: 1.5; }
+  .gridauth section { margin: 1.5rem 0; padding: 1.25rem; border: 1px solid #d0d4da; border-radius: 0.5rem; }
+  .gridauth-table { border-collapse: collapse; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 1.05rem; }
+  .gridauth-table th, .gridauth-table td { border: 1px solid #9aa1ab; padding: 0.3rem 0.55rem; text-align: center; min-width: 2.2rem; }
+  .gridauth-table th { background: #eef0f3; font-weight: 600; }
+  .gridauth-table td.gridauth-highlight { background: #ffe58a; outline: 2px solid #b08800; }
+  .gridauth-card-meta { font-size: 0.9rem; color: #4a5160; }
+  .gridauth-fields { display: flex; flex-wrap: wrap; gap: 1rem; margin: 1rem 0; }
+  .gridauth-fields label { display: flex; flex-direction: column; font-weight: 600; }
+  .gridauth-fields input { font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 1.25rem; width: 5rem; text-align: center; text-transform: uppercase; }
+  .gridauth-field input { margin-top: 0.25rem; }
+  .gridauth-actions { display: flex; gap: 0.75rem; align-items: center; flex-wrap: wrap; }
+  .gridauth-alert { color: #9b1c1c; }
+  .gridauth dl { display: grid; grid-template-columns: max-content 1fr; gap: 0.25rem 1rem; }
+  .gridauth dt { font-weight: 600; }
+  .gridauth dd { margin: 0; }
+<% end %>

data/config/locales/en.yml

@@ -0,0 +1,61 @@
+en:
+  gridauth:
+    cell_description: "column %{column}, row %{row}"
+    policy:
+      enrollment_required: "Set up a grid card to finish securing your account."
+      rotation_required: "Your grid card is due to be replaced. Please issue and activate a new card."
+    challenges:
+      new:
+        title: "Grid card verification"
+        intro: "Enter the characters printed on your grid card (serial %{serial}) in each of the highlighted cells."
+        locked: "Too many incorrect answers. Your grid card is locked until %{time}."
+        submit: "Verify"
+        cancel: "Cancel and sign in again"
+      invalid: "That doesn't match your grid card. Please try again."
+      locked: "Too many incorrect answers. Your grid card has been temporarily locked."
+      expired: "Your sign-in attempt expired. Please sign in again."
+      rate_limited: "Too many attempts. Try again later."
+    grid_cards:
+      issued: "Your new grid card is ready. Save or print it, then activate it below."
+      activated: "Grid card activated. You'll be asked for it each time you sign in."
+      rotated: "Your new grid card is active. The previous card no longer works."
+      discarded: "The new card was discarded."
+      disabled: "Grid card authentication has been turned off."
+      disable_not_allowed: "Grid card authentication can't be turned off for this account."
+      wrong_password: "Your password was incorrect."
+      unavailable: "That card can no longer be displayed. Issue a new card to continue."
+      show:
+        title: "Grid card"
+        none: "Protect your account with a grid card: a printed table of characters you'll be asked for whenever you sign in, in addition to your password."
+        issue: "Set up a grid card"
+        active_title: "Your grid card"
+        serial: "Serial"
+        activated_at: "Activated"
+        last_used_at: "Last used"
+        never: "Never"
+        use_count: "Sign-ins"
+        rotation_due_at: "Replace by"
+        rotation_due: "This card is due to be replaced."
+        rotate_intro: "Replacing your card regularly limits the damage if someone has seen it. Your current card keeps working until the new one is activated."
+        rotate: "Replace grid card"
+        new_title: "Your new grid card"
+        new_intro: "Print this card or store it somewhere safe. It is shown only now; we don't keep a readable copy."
+        print: "Print card"
+        activate_title: "Activate the new card"
+        activate_intro: "To confirm you've saved it, enter the characters from the new card in the highlighted cells."
+        password: "Current password"
+        activate: "Activate card"
+        discard: "Discard new card"
+        lost_title: "New card pending"
+        lost: "A new card was issued in another browser session and can't be shown here."
+        reissue: "Issue another card"
+        disable_title: "Turn off grid card authentication"
+        disable_intro: "You'll only need your password to sign in."
+        disable: "Turn off"
+        locked: "Too many incorrect answers. Try again after %{time}."
+      print:
+        title: "Grid card %{serial}"
+        issued_to: "Issued to"
+        issued_at: "Issued"
+        keep_safe: "Keep this card private. Never share it or enter it anywhere except when signing in."
+        print: "Print"

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

@@ -0,0 +1,86 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Gridauth
+  module Generators
+    # Wires grid card 2FA into an app that uses `bin/rails generate authentication`.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :user_class, type: :string, default: "User", desc: "Model that signs in"
+      class_option :path, type: :string, default: "gridauth", desc: "URL path prefix for the grid card pages"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/gridauth.rb"
+      end
+
+      def create_grid_cards_migration
+        migration_template "create_gridauth_grid_cards.rb", "db/migrate/create_gridauth_grid_cards.rb"
+      end
+
+      def add_to_user_model
+        path = File.join("app/models", "#{options[:user_class].underscore}.rb")
+        if File.exist?(File.join(destination_root, path))
+          inject_into_class path, options[:user_class].demodulize, "  has_grid_card\n"
+        else
+          say_status :skip, "#{path} not found; add `has_grid_card` to your user model", :yellow
+        end
+      end
+
+      def add_to_application_controller
+        path = "app/controllers/application_controller.rb"
+        content = File.read(File.join(destination_root, path))
+        return if content.include?("Gridauth::Authentication")
+
+        if content.match?(/^\s*include Authentication\n/)
+          inject_into_file path, "  include Gridauth::Authentication\n", after: /^\s*include Authentication\n/
+        else
+          say_status :skip, "Authentication concern not found in #{path}. Run `bin/rails generate authentication` first", :red
+        end
+      end
+
+      SIGN_IN_PATTERN = /start_new_session_for(\(| )user\)?\n\s*redirect_to after_authentication_url/
+
+      def update_sessions_controller
+        path = "app/controllers/sessions_controller.rb"
+        full_path = File.join(destination_root, path)
+        content = File.exist?(full_path) ? File.read(full_path) : ""
+
+        if content.match?(SIGN_IN_PATTERN)
+          gsub_file path, SIGN_IN_PATTERN, "start_grid_card_challenge_for user"
+        elsif !content.include?("start_grid_card_challenge_for")
+          say_status :manual, "In SessionsController#create, replace `start_new_session_for user` and " \
+            "`redirect_to after_authentication_url` with `start_grid_card_challenge_for user`", :yellow
+        end
+      end
+
+      def add_routes
+        route options[:path] == "gridauth" ? "gridauth_routes" : %(gridauth_routes path: "#{options[:path]}")
+      end
+
+      def show_next_steps
+        say <<~MSG
+
+          Grid card 2FA installed. Next:
+
+            1. bin/rails db:migrate
+            2. Link signed-in users to the card page: gridauth_grid_card_path
+            3. Review config/initializers/gridauth.rb
+
+        MSG
+      end
+
+      private
+        def users_table
+          options[:user_class].tableize.tr("/", "_")
+        end
+
+        def primary_key_type
+          type = Rails.application&.config&.generators&.options&.dig(:active_record, :primary_key_type)
+          type ? ", type: :#{type}" : ""
+        end
+    end
+  end
+end

data/lib/generators/gridauth/install/templates/create_gridauth_grid_cards.rb.tt

@@ -0,0 +1,26 @@
+class CreateGridauthGridCards < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :gridauth_grid_cards<%= primary_key_type.sub(", type:", ", id:") %> do |t|
+      t.references :user, null: false, foreign_key: { to_table: :<%= users_table %> }<%= primary_key_type %>
+      t.string :serial, null: false
+      t.string :status, null: false, default: "pending"
+      t.integer :row_count, null: false
+      t.integer :column_count, null: false
+      t.integer :cell_length, null: false
+      t.string :salt, null: false
+      t.text :cell_digests, null: false
+      t.string :challenge_cells
+      t.integer :failed_attempts, null: false, default: 0
+      t.datetime :locked_until
+      t.integer :use_count, null: false, default: 0
+      t.datetime :last_used_at
+      t.datetime :activated_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_index :gridauth_grid_cards, :serial, unique: true
+    add_index :gridauth_grid_cards, [ :user_id, :status ]
+  end
+end

data/lib/generators/gridauth/install/templates/initializer.rb.tt

@@ -0,0 +1,44 @@
+Gridauth.configure do |config|
+  # Model that signs in, and the controller the engine's controllers inherit
+  # from (it must include the Rails `Authentication` concern).
+  config.user_class = "<%= options[:user_class] %>"
+  # config.parent_controller = "ApplicationController"
+  # config.sign_in_route = :new_session_path
+
+  # Card layout. Each cell holds `cell_length` characters from `alphabet`.
+  # config.rows = 5
+  # config.columns = 10
+  # config.cell_length = 2
+  # config.alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+  # config.case_sensitive = false
+
+  # Cells asked for at each sign-in, and how long the user has to answer.
+  # config.challenge_size = 3
+  # config.challenge_timeout = 5.minutes
+
+  # Lock the card after this many consecutive wrong answers.
+  # config.max_failed_attempts = 5
+  # config.lockout_period = 15.minutes
+
+  # Rotation: a card is due for replacement after this long (nil disables)
+  # or after this many sign-ins (nil disables).
+  # config.rotation_period = 180.days
+  # config.rotate_after_uses = nil
+
+  # Policy. With enforce_enrollment every user must set up a card; with
+  # enforce_rotation the app is blocked until a due card is replaced.
+  # config.enforce_enrollment = false
+  # config.enforce_rotation = false
+  # config.policy_exempt_controllers = %w[sessions passwords]
+
+  # Require the current password to activate a card or turn 2FA off.
+  # config.require_password_for_changes = true
+  # config.allow_disable = true
+
+  # Printed on the card.
+  # config.user_label_attribute = :email_address
+
+  # Key for HMACing card cells. Defaults to one derived from secret_key_base;
+  # changing it invalidates every issued card.
+  # config.secret_key = Rails.application.credentials.dig(:gridauth, :secret_key)
+end

data/lib/generators/gridauth/views/views_generator.rb

@@ -0,0 +1,14 @@
+require "rails/generators"
+
+module Gridauth
+  module Generators
+    # Copies the engine's views into app/views/gridauth for customization.
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../../app/views/gridauth", __dir__)
+
+      def copy_views
+        directory ".", "app/views/gridauth"
+      end
+    end
+  end
+end

data/lib/gridauth/authentication.rb

@@ -0,0 +1,76 @@
+module Gridauth
+  # Include in ApplicationController after the Rails `Authentication` concern:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Authentication
+  #     include Gridauth::Authentication
+  #   end
+  #
+  # and replace `start_new_session_for user` + `redirect_to after_authentication_url`
+  # in SessionsController#create with `start_grid_card_challenge_for user`.
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :enforce_grid_card_policy
+      helper_method :grid_card_challenge_pending?
+    end
+
+    class_methods do
+      # Opts controllers or actions out of the enrollment/rotation policy.
+      def skip_grid_card_policy(**options)
+        skip_before_action :enforce_grid_card_policy, **options
+      end
+    end
+
+    private
+      # Called once the user's password has been verified. Users with an
+      # active grid card are sent to the challenge; no Session is created until
+      # they answer it. Users without a card are signed in directly.
+      def start_grid_card_challenge_for(user)
+        if user.respond_to?(:grid_card_enabled?) && user.grid_card_enabled?
+          return_to = session[:return_to_after_authenticating]
+          reset_session
+          session[:return_to_after_authenticating] = return_to if return_to
+          session[Gridauth::PENDING_LOGIN_KEY] = { "user_id" => user.id, "started_at" => Time.current.to_i }
+          redirect_to new_gridauth_challenge_path
+        else
+          start_new_session_for user
+          if Gridauth.config.enforce_enrollment
+            redirect_to gridauth_grid_card_path, notice: I18n.t("gridauth.policy.enrollment_required")
+          else
+            redirect_to after_authentication_url
+          end
+        end
+      end
+
+      def grid_card_challenge_pending?
+        session[Gridauth::PENDING_LOGIN_KEY].present?
+      end
+
+      def enforce_grid_card_policy
+        return if Gridauth.config.policy_exempt_controllers.include?(controller_path)
+        return unless (user = grid_card_policy_user)
+
+        if Gridauth.config.enforce_enrollment && !user.grid_card_enabled?
+          grid_card_policy_redirect I18n.t("gridauth.policy.enrollment_required")
+        elsif Gridauth.config.enforce_rotation && user.grid_card&.rotation_due?
+          grid_card_policy_redirect I18n.t("gridauth.policy.rotation_required")
+        end
+      end
+
+      def grid_card_policy_user
+        session = respond_to?(:resume_session, true) ? resume_session : Current.session
+        user = session&.user
+        user if user.respond_to?(:grid_card_enabled?)
+      end
+
+      def grid_card_policy_redirect(message)
+        if request.format.html?
+          redirect_to gridauth_grid_card_path, alert: message
+        else
+          head :forbidden
+        end
+      end
+  end
+end

data/lib/gridauth/configuration.rb

@@ -0,0 +1,89 @@
+module Gridauth
+  class Configuration
+    # Name of the model that represents an account (generated as `User` by
+    # `bin/rails generate authentication`).
+    attr_accessor :user_class
+
+    # Controller the engine's controllers inherit from. It must include the
+    # app's `Authentication` concern.
+    attr_accessor :parent_controller
+
+    # Route helper (on `main_app`) for the username and password form.
+    attr_accessor :sign_in_route
+
+    # Card layout: rows are numbered 1..rows, columns are lettered A..
+    attr_accessor :rows, :columns
+
+    # Number of characters printed in each cell and the characters used.
+    attr_accessor :cell_length, :alphabet
+
+    # When false, answers are upcased before comparison.
+    attr_accessor :case_sensitive
+
+    # Number of cells the user must answer on each challenge.
+    attr_accessor :challenge_size
+
+    # How long a user has, after entering a correct password, to answer the
+    # grid card challenge before having to sign in again.
+    attr_accessor :challenge_timeout
+
+    # Consecutive wrong answers before the card is locked, and for how long.
+    attr_accessor :max_failed_attempts, :lockout_period
+
+    # A card is due for rotation once it is this old (nil to disable) ...
+    attr_accessor :rotation_period
+    # ... or once it has been used for this many sign-ins (nil to disable).
+    attr_accessor :rotate_after_uses
+
+    # Require every user to set up a grid card before using the app.
+    attr_accessor :enforce_enrollment
+
+    # Block the app until a card that is due for rotation has been replaced.
+    attr_accessor :enforce_rotation
+
+    # Require the account password to activate a new card or disable 2FA.
+    attr_accessor :require_password_for_changes
+
+    # Allow users to turn grid card authentication off themselves.
+    attr_accessor :allow_disable
+
+    # Attribute of the user printed on the card.
+    attr_accessor :user_label_attribute
+
+    # Controller paths that are never redirected by the enrollment/rotation
+    # policy (sign out and password reset must keep working).
+    attr_accessor :policy_exempt_controllers
+
+    # Secret used to HMAC card cell values. Defaults to a key derived from
+    # the application's secret_key_base. Rotating it invalidates all cards.
+    attr_writer :secret_key
+
+    def initialize
+      @user_class = "User"
+      @parent_controller = "ApplicationController"
+      @sign_in_route = :new_session_path
+      @rows = 5
+      @columns = 10
+      @cell_length = 2
+      @alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+      @case_sensitive = false
+      @challenge_size = 3
+      @challenge_timeout = 5.minutes
+      @max_failed_attempts = 5
+      @lockout_period = 15.minutes
+      @rotation_period = 180.days
+      @rotate_after_uses = nil
+      @enforce_enrollment = false
+      @enforce_rotation = false
+      @require_password_for_changes = true
+      @allow_disable = true
+      @user_label_attribute = :email_address
+      @policy_exempt_controllers = %w[sessions passwords]
+      @secret_key = nil
+    end
+
+    def secret_key
+      @secret_key ||= Rails.application.key_generator.generate_key("gridauth/grid-card-cells", 32)
+    end
+  end
+end

data/lib/gridauth/engine.rb

@@ -0,0 +1,14 @@
+module Gridauth
+  class Engine < ::Rails::Engine
+    initializer "gridauth.model" do
+      ActiveSupport.on_load(:active_record) do
+        extend Gridauth::Model
+      end
+    end
+
+    # Keep grid card answers out of the logs.
+    initializer "gridauth.filter_parameters" do |app|
+      app.config.filter_parameters += [ /\Acells\z/ ]
+    end
+  end
+end

data/lib/gridauth/grid.rb

@@ -0,0 +1,63 @@
+require "securerandom"
+
+module Gridauth
+  # The plaintext contents of a grid card. Instances only exist briefly while
+  # a new card is shown to its owner; the database stores HMAC digests.
+  class Grid
+    MAX_COLUMNS = 26
+
+    attr_reader :rows, :columns, :values
+
+    def self.generate(rows: Gridauth.config.rows, columns: Gridauth.config.columns,
+                      cell_length: Gridauth.config.cell_length, alphabet: Gridauth.config.alphabet)
+      chars = alphabet.chars.uniq
+      values = cell_keys(rows, columns).index_with do
+        Array.new(cell_length) { chars[SecureRandom.random_number(chars.size)] }.join
+      end
+      new(rows:, columns:, values:)
+    end
+
+    # Rebuilds a grid from #to_compact output.
+    def self.from_compact(string, rows:, columns:)
+      cell_length = string.length / (rows * columns)
+      values = cell_keys(rows, columns).each_with_index.to_h do |key, index|
+        [ key, string[index * cell_length, cell_length] ]
+      end
+      new(rows:, columns:, values:)
+    end
+
+    def self.column_labels(columns)
+      raise ArgumentError, "a grid card can have at most #{MAX_COLUMNS} columns" if columns > MAX_COLUMNS
+
+      ("A"..).first(columns)
+    end
+
+    def self.row_labels(rows)
+      (1..rows).map(&:to_s)
+    end
+
+    # Cell keys in row-major order, e.g. ["A1", "B1", ..., "A2", ...].
+    def self.cell_keys(rows, columns)
+      row_labels(rows).flat_map { |row| column_labels(columns).map { |column| "#{column}#{row}" } }
+    end
+
+    def initialize(rows:, columns:, values:)
+      @rows = rows
+      @columns = columns
+      @values = values
+    end
+
+    def column_labels = self.class.column_labels(columns)
+    def row_labels = self.class.row_labels(rows)
+    def cell_keys = self.class.cell_keys(rows, columns)
+
+    def [](key)
+      values[key.to_s.upcase]
+    end
+
+    # Compact form small enough to keep in the (encrypted) session cookie.
+    def to_compact
+      cell_keys.map { |key| values.fetch(key) }.join
+    end
+  end
+end