sqrl-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5e531c844edf1a741273c373f1f310549df1cd2434a371a240ffa1c14eddf885
+  data.tar.gz: f01f6e38861b0a286f0ac1138d46750e7fe9336e8c25d067736d2a55420f3901
+SHA512:
+  metadata.gz: 38266ffecad16700685b01f50bb189b1c425036392787c8de14867232d24971da0491ef10754cbce43f7699aaa8ed0fabf0980ea5d4c98fe1e074abb721fcf0d
+  data.tar.gz: 118424b7a269f1b30c87567475062c63c9cd6c38b3842b42203f311a4f4eddc7a3b77bc34afb8d4458695ddf3ff0a71653092ba6801d60981e2d73777ccecd43

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 — 2026-10-20
+
+First release.
+
+- Isolated engine serving the SQRL endpoint, status poll, CPS/poll callback, login page,
+  script, refresh endpoint and identity-management pages.
+- ActiveRecord stores (`sqrl_identities`, `sqrl_nuts`, `sqrl_pending_logins`) with atomic
+  single use, plus an `ActiveSupport::Cache` store set.
+- `bin/rails generate sqrl:install`: migration, mount, initializer, user association,
+  login block in `sessions/new`, password-policy includes.
+- Sign-in adapter for the Rails 8 `generate authentication` concern, with Warden and plain
+  session fallbacks; `:create` / `:link` / `:refuse` policies for unknown identities.
+- `sqrlonly` / `hardlock` enforcement for password login and reset; identity management;
+  per-IP rate limiting; `ask` with deny button; `allowed_hosts`, hooks, `prune` task.
+- `insecure_http` testing mode; `poll_requires_ip_match` off by default.
+- Requires Ruby 3.2+ and Rails 7.1, 7.2, 8.0 or 8.1.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel P. Clark
+
+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,196 @@
+# sqrl-rails
+
+SQRL login for Rails applications: an isolated engine that serves the SQRL protocol
+endpoint, the status poll, the login callback and the browser script; ActiveRecord
+stores; a view helper that renders the login block; and a sign-in adapter that plugs
+into the authentication stack generated by `bin/rails generate authentication` (Rails 8)
+or into any custom session scheme.
+
+Devise applications should use [`devise-sqrl`](../devise-sqrl), which builds on this gem.
+
+## Install
+
+```ruby
+# Gemfile
+gem "sqrl-rails"
+```
+
+```sh
+bin/rails generate sqrl:install   # migration, mount, initializer, User association, login block
+bin/rails db:migrate
+```
+
+The generator:
+
+- copies the `create_sqrl_tables` migration (`sqrl_identities`, `sqrl_nuts`,
+  `sqrl_pending_logins`);
+- mounts the engine: `mount SQRL::Rails::Engine, at: "/sqrl", as: :sqrl`;
+- writes `config/initializers/sqrl.rb` (every option documented inline);
+- adds `has_many :sqrl_identities` to `app/models/user.rb`;
+- appends `<%= sqrl_login_block %>` to `app/views/sessions/new.html.erb` when that view
+  exists (the Rails 8 generated login form).
+
+Every step is idempotent. Options: `--host`, `--mount`, `--user-model`,
+`--skip-migration`, `--skip-routes`, `--skip-views`.
+
+## How a login works
+
+1. `sqrl_login_block` issues a `sqrl://host/sqrl/cli?nut=…` URL, remembers the pending
+   login in the browser session and renders the link, the QR code and the status text
+   that `/sqrl/sqrl.js` drives.
+2. The SQRL client POSTs its signed `query`/`ident` to `/sqrl/cli`. On success the
+   identity is marked authenticated on the pending login and, when the client asked for
+   Client Provided Session, a one-time token is handed back in `url=`.
+3. The browser lands on `/sqrl/callback?t=TOKEN` (CPS) or, after the poller saw
+   `{"authenticated": true}` on `/sqrl/status`, on `/sqrl/callback` with its own cookie.
+   The callback resolves the user, signs them in and redirects.
+
+## Configuration
+
+`config/initializers/sqrl.rb`:
+
+```ruby
+Rails.application.config.sqrl.tap do |sqrl|
+  sqrl.host = ENV["SQRL_HOST"].presence   # public host for sqrl:// URLs (default: request host)
+  sqrl.user_class = "User"
+  sqrl.on_unknown_identity = :create       # :create | :link | :refuse
+  # sqrl.create_user = ->(identity) { User.create!(name: "SQRL user", password: SecureRandom.hex(32)) }
+  # sqrl.sign_in = ->(controller, identity, user) { controller.send(:start_new_session_for, user) }
+  # sqrl.after_sign_in = ->(controller, completion) { controller.send(:after_authentication_url) }
+  # sqrl.failure_path = "/session/new"
+  # sqrl.stores = :active_record           # or :memory, or an SQRL::Server::Stores
+end
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `host` | request host | host placed in the `sqrl://` URLs issued to clients |
+| `insecure_http` | `false` | loopback-only testing mode issuing `qrl://` (plain http) URLs, for trying the browser extension against `bin/rails server`; not part of SQRL, refused for other hosts |
+| `poll_requires_ip_match` | `false` | optional hardening: refuse poll (cookie) completions when the client's IP did not match the browser's |
+| `on_unknown_identity` | `:create` | `:create` a user ({SQRL::Rails::UserFactory}), `:link` to the signed-in user, or `:refuse` |
+| `create_user` | `UserFactory` | `(identity) -> user`; the default fills placeholder columns (random password, `sqrl-…@sqrl.invalid`) |
+| `find_user` | by `user_ref` | `(identity) -> user or nil` |
+| `current_user` | `Current.user`, else `session[:user_id]` | `(controller) -> user` used for `:link` |
+| `sign_in` | `SignIn.default` | `(controller, identity, user)`; default calls `start_new_session_for` when the Rails 8 concern is present, else Warden, else `session[:user_id]` |
+| `after_sign_in` | `after_authentication_url` / root | `(controller, completion) -> url`; a same-site `return_to` wins |
+| `failure_path` | `/sqrl/login` | where a failed callback redirects |
+| `stores` | `:active_record` | storage back end |
+| `nut_ttl`, `cps_token_ttl`, `require_ip_match`, `ask`, `sin`, `path_extension`, `on_authenticated` | see `SQRL::Server::Config` | protocol options |
+
+### Rails 8 `generate authentication`
+
+Nothing to configure: when `Authentication` (the generated concern) exists, the
+callback controller includes it and calls `start_new_session_for(user)`, so SQRL logins
+produce the same `Session` rows and cookies as the password form, and
+`after_authentication_url` sends the browser back to the page that required login.
+
+### Custom session schemes
+
+Set `sign_in` (and usually `after_sign_in`) to whatever your application does; `identity`
+is an `SQRL::Server::Identity` (`idk_b64`, `user_ref`, `disabled?`, …).
+
+## Helpers
+
+In views: `sqrl_login_block(return_to:, cancel_url:, link_user:, script:, **login_block_options)`,
+`sqrl_login_url`, `sqrl_qr_svg`, `sqrl_script_tag`, `sqrl_status_path`, `sqrl_script_path`.
+In controllers: `current_sqrl_identity`, `sqrl_authenticated?`, `sqrl_logout!`
+(call it from your sign-out action), `sqrl_endpoint`.
+
+## Storage
+
+`SQRL::Rails::Identity` (`sqrl_identities`): `idk`, `suk`, `vuk` (base64url), `disabled`,
+`sqrlonly`, `hardlock`, `ins`, `logins`, polymorphic `user`, `superseded_by` (tombstone
+rows left by a re-key), `last_login_at`. `SQRL::Rails::Nut` and
+`SQRL::Rails::PendingLogin` are single-use records; `bin/rails sqrl:prune` deletes the
+expired ones (run it from cron or a job).
+
+Nut consumption and CPS-token claims are single conditional `UPDATE`s, so they stay
+single-use under concurrent requests.
+
+## Account policies: `sqrlonly` and `hardlock`
+
+A SQRL client can ask the site to refuse every non-SQRL way of signing in (`sqrlonly`)
+and of recovering the account (`hardlock`). The flags are stored on the identity;
+`SQRL::Rails.sqrl_only?(user)` and `SQRL::Rails.hard_locked?(user)` answer for a user,
+and `SQRL::Rails::Identity.sqrl_only` / `.hard_locked` are scopes.
+
+`bin/rails generate sqrl:install` enforces them in the controllers that
+`generate authentication` produced:
+
+```ruby
+class SessionsController < ApplicationController
+  include SQRL::Rails::PasswordPolicy::Sessions    # refuses password login for sqrlonly users (create)
+end
+
+class PasswordsController < ApplicationController
+  include SQRL::Rails::PasswordPolicy::Passwords   # refuses password reset for hardlock users (create, edit, update)
+end
+```
+
+Both look the user up by `email_address`/`email` parameter or by reset token
+(`sqrl_policy_user`) and redirect to the sign-in page with a flash alert
+(`sqrl_policy_refused`); override either method for other flows. Messages are the
+`sqrl.password_policy.*` translations.
+
+## Identity management
+
+`GET /sqrl/identities` lists the signed-in user's identities (short key, linked date,
+last login, login count, flags) with an Unlink button (`DELETE /sqrl/identities/:id`).
+Unlinking detaches the identity from the user; the site keeps the protocol association,
+so the next login with it is treated as an unknown identity again. The view helper
+`sqrl_identities_path` links to the page. `last_login_at` and `logins` are updated on
+every successful `ident` and `enable`.
+
+## `ask`, `sin` and the deny button
+
+```ruby
+sqrl.ask = SQRL::Ask.new(message: "Allow this login?", buttons: [{ label: "Allow" }, { label: "Deny" }],
+                         accept: [1])   # only "Allow" (btn=1) lets the ident proceed
+sqrl.ask_deny_button = 2               # a "Deny" answer is also refused at the callback
+sqrl.sin = "0"                         # secret-index challenge; the client answers with ins=
+```
+
+Both may be callables receiving the request context. The generated initializer turns
+them on with `SQRL_ASK=1` / `SQRL_SIN=1` for testing.
+
+## Rate limiting, hooks and hosts
+
+```ruby
+sqrl.rate_limit = { to: 60, within: 1.minute }            # per client IP, counted in Rails.cache; 429 over the limit
+sqrl.before_handle = ->(ctx) { raise SQRL::Server::RateLimited.new(retry_after: 10) if ... }
+sqrl.before_issue = ->(ctx) { ... }                        # before a login URL is issued
+sqrl.allowed_hosts = ["example.com", /\.example\.com\z/]  # when sqrl.host is not set
+sqrl.host_cache_limit = 16                                 # distinct request hosts kept per process
+sqrl.prune_every = 1000                                    # opportunistic pruning of expired rows
+```
+
+`rate_limit` applies to the protocol endpoint, the login and refresh pages, the status
+poll, the callback and the identities page (`only:` narrows it; `by:` and `cache:`
+override the key and store). A request whose host is not allowed answers 400.
+`GET /sqrl/refresh` hands the page a fresh login URL when a nut expires (`sqrl.js`
+calls it through `SQRL.refresh`).
+
+## Storage back ends
+
+`sqrl.stores` is `:active_record` (default), `:cache` (`SQRL::Rails::Stores::Cache` on
+`Rails.cache` or `sqrl.cache_store`; needs a store that deletes atomically such as Redis
+or Memcached, and a persistent one if identities live there too) or `:memory`. Every
+store set passes the shared store contract spec from `sqrl-core`.
+
+## Linking identities to existing accounts
+
+With `on_unknown_identity = :link`, unknown identities are only accepted while a user is
+signed in; render `sqrl_login_block` on an authenticated settings page and the new
+identity is attached to `Current.user` (or whatever `current_user` returns).
+
+## Example and testing
+
+[`examples/rails-auth-app`](../../examples/rails-auth-app) is a Rails 8 application built
+with `rails generate authentication` followed by `rails generate sqrl:install`.
+`bundle exec rake spec:sqrl-rails` runs the engine, store, policy and generator specs
+against an in-gem dummy application; the `gemfiles/` directory runs them on Rails 7.1, 7.2
+and 8.0 as well.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/app/controllers/sqrl/rails/application_controller.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Base controller of the engine. Deliberately not derived from the host's
+    # +ApplicationController+, so host filters (authentication, browser checks) do not
+    # apply to the protocol endpoints.
+    class ApplicationController < ::ActionController::Base
+      protect_from_forgery with: :exception
+
+      # A before_issue / before_handle hook refused the request.
+      rescue_from SQRL::Server::RateLimited do |error|
+        render_rack(sqrl_endpoint.rate_limited(error, json: request.format.json?))
+      end
+
+      # The request host may not be used to issue SQRL URLs (allowed_hosts, host cache
+      # limit).
+      rescue_from SQRL::Rack::HostNotAllowed do |error|
+        render plain: error.message, status: :bad_request
+      end
+
+      private
+
+      def sqrl_endpoint
+        @sqrl_endpoint ||= SQRL::Rails.endpoint_for(request)
+      end
+
+      def sqrl_config
+        SQRL::Rails.config
+      end
+
+      # The host application's URL prefix (its relative URL root), without the engine
+      # mount the current request came in through.
+      def host_script_name
+        name = request.script_name.to_s
+        mount = SQRL::Rails.mount_path
+        name.end_with?(mount) ? name[0, name.length - mount.length] : name
+      end
+
+      # Public path of an engine route (+:login+, +:status+, ...).
+      def engine_path(name)
+        SQRL::Rails.path_for(name, script_name: host_script_name)
+      end
+
+      def render_rack(triple)
+        status, headers, body = triple
+        headers.each { |k, v| response.set_header(k, v) }
+        render body: body.join, status: status, content_type: headers["content-type"]
+      end
+
+      # The host's Authentication concern uses the host's route helpers (root_url,
+      # new_session_path); resolve them through the main_app proxy.
+      def method_missing(name, ...)
+        if host_route_helper?(name)
+          main_app.public_send(name, ...)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        host_route_helper?(name) || super
+      end
+
+      def host_route_helper?(name)
+        name.to_s.match?(/_(url|path)\z/) && respond_to?(:main_app) && main_app.respond_to?(name)
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/assets_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Serves +sqrl.js+ with an ETag.
+    class AssetsController < ApplicationController
+      # A public static script; Rails' cross-origin JavaScript check does not apply.
+      skip_forgery_protection
+
+      # Serve +sqrl.js+ with an ETag.
+      def script
+        status, headers, body = sqrl_endpoint.script(request)
+        headers.each { |k, v| response.set_header(k, v) }
+        if status == 304
+          head :not_modified
+        else
+          render body: body.join, status: status, content_type: "application/javascript"
+        end
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/callback_controller.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Completes a login: with +t=+ (the one-time CPS token the SQRL client sent the
+    # browser to) or without it (the browser's own pending login, after the poller saw
+    # it authenticated). Resolves or creates the user, signs them in through the
+    # configured adapter and redirects.
+    class CallbackController < ApplicationController
+      include RateLimited
+
+      concern = SQRL::Rails.host_authentication_concern
+      if concern
+        include concern
+
+        allow_unauthenticated_access if respond_to?(:allow_unauthenticated_access)
+      end
+
+      # Complete a login (CPS token or the browser's own pending login), resolve the user and sign in.
+      def show
+        completion = sqrl_endpoint.callback(request)
+        return failure("SQRL login failed or expired. Please try again.") unless completion
+        return failure(I18n.t("sqrl.callback.declined", default: "You declined the SQRL login."), completion) if declined?(completion)
+
+        user = resolve_user(completion)
+        return failure("This SQRL identity is not linked to an account.", completion) unless user
+
+        sign_in = SQRL::Rails.config.sign_in || SignIn.method(:default)
+        sign_in.call(self, completion.identity, user)
+        redirect_to SignIn.after(self, completion), allow_other_host: false
+      rescue SQRL::Rails::Error, ActiveRecord::RecordInvalid, ActiveRecord::RecordNotSaved,
+             ActionController::Redirecting::UnsafeRedirectError => e
+        failure(e.message, completion)
+      end
+
+      private
+
+      def sqrl_rate_limit_scope
+        :callback
+      end
+
+      # The client answered the site's +ask+ with the button configured as "deny".
+      def declined?(completion)
+        deny = sqrl_config.ask_deny_button
+        !deny.nil? && completion.pending_login.btn == deny.to_i
+      end
+
+      # The user behind an identity; for a brand-new identity apply the configured
+      # policy.
+      def resolve_user(completion)
+        identity = completion.identity
+        user = find_user(identity)
+        return user if user
+
+        case sqrl_config.on_unknown_identity
+        when :refuse
+          nil
+        when :link
+          link_to_current_user(identity)
+        else
+          create_user(identity)
+        end
+      end
+
+      def find_user(identity)
+        return sqrl_config.find_user.call(identity) if sqrl_config.find_user
+
+        SQRL::Rails.user_from_ref(identity.user_ref)
+      end
+
+      def create_user(identity)
+        user = sqrl_config.create_user ? sqrl_config.create_user.call(identity) : UserFactory.call(identity)
+        attach(identity, user)
+      end
+
+      def link_to_current_user(identity)
+        user = SignIn.current_user(self)
+        return nil unless user
+
+        attach(identity, user)
+      end
+
+      def attach(identity, user)
+        return nil unless user
+
+        SQRL::Rails.stores.identities.update(identity.idk, user_ref: SQRL::Rails.user_ref(user))
+        user
+      end
+
+      # +completion+ is passed when the pending login was already consumed: the endpoint
+      # recorded the identity in the session at that point, so a failed sign-in must clear
+      # it again, otherwise the controller helpers would report a refused identity as
+      # authenticated.
+      def failure(message, completion = nil)
+        sqrl_endpoint.logout(request) if completion
+        flash[:alert] = message if respond_to?(:flash)
+        redirect_to(sqrl_config.failure_path || engine_path(:login), allow_other_host: false)
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/cli_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # The SQRL endpoint: the client's signed POSTs. Authenticated by the protocol's own
+    # signatures, so forgery protection does not apply.
+    class CliController < ApplicationController
+      include RateLimited
+
+      skip_forgery_protection
+
+      # The SQRL protocol endpoint: hands the signed POST to the handler and renders its reply.
+      def create
+        render_rack(sqrl_endpoint.cli(request))
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/identities_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Lets a signed-in user see the SQRL identities attached to their account and unlink
+    # one. Unlinking detaches the identity from the user (the site keeps the protocol
+    # association, so the SQRL client still "knows" the site); the next login with that
+    # identity is treated as an unknown identity again.
+    #
+    # The signed-in user comes from the host's +Authentication+ concern (Rails 8), from
+    # +config.sqrl.current_user+, or from the session fallback of {SignIn}.
+    class IdentitiesController < ApplicationController
+      include RateLimited
+
+      concern = SQRL::Rails.host_authentication_concern
+      include concern if concern
+
+      layout "sqrl/rails/application"
+
+      before_action :require_sqrl_user
+
+      # List the current user's SQRL identities.
+      def index
+        @identities = Identity.active.for_user(@sqrl_user).order(:created_at)
+        @current_idk = sqrl_endpoint.current_identity(request)&.idk_b64
+      end
+
+      # Unlink one of the current user's SQRL identities.
+      def destroy
+        identity = Identity.active.for_user(@sqrl_user).find_by(id: params[:id])
+        if identity
+          current = sqrl_endpoint.current_identity(request)&.idk_b64
+          identity.update!(user: nil)
+          sqrl_endpoint.logout(request) if current && current == identity.idk
+          flash[:notice] = I18n.t("sqrl.identities.unlinked", default: "SQRL identity unlinked.")
+        else
+          flash[:alert] = I18n.t("sqrl.identities.not_found", default: "That SQRL identity is not linked to your account.")
+        end
+        redirect_to engine_path(:identities), status: :see_other
+      end
+
+      private
+
+      def sqrl_rate_limit_scope
+        :identities
+      end
+
+      def require_sqrl_user
+        @sqrl_user = SignIn.current_user(self)
+        return if @sqrl_user
+
+        flash[:alert] = I18n.t("sqrl.identities.sign_in_required", default: "Sign in to manage your SQRL identities.")
+        redirect_to(sqrl_config.failure_path || engine_path(:login), allow_other_host: false)
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/logins_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # A stand-alone login page, for applications that do not embed
+    # +sqrl_login_block+ in their own view.
+    class LoginsController < ApplicationController
+      include RateLimited
+
+      layout "sqrl/rails/application"
+
+      # Render the stand-alone login page.
+      def new
+        @return_to = params[:return_to].presence
+      end
+
+      private
+
+      def sqrl_rate_limit_scope
+        :login
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/refresh_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Hands the login page a fresh login URL (and QR code) for its browser session when
+    # the previous nut expired, as JSON; +sqrl.js+ calls it through +SQRL.refresh+.
+    class RefreshController < ApplicationController
+      include RateLimited
+
+      # Issue a fresh login URL for the browser's session as JSON (used by +SQRL.refresh+).
+      def show
+        render_rack(sqrl_endpoint.refresh(request))
+      end
+
+      private
+
+      def sqrl_rate_limit_scope
+        :refresh
+      end
+    end
+  end
+end

data/app/controllers/sqrl/rails/status_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # Cookie-bound poll answered with +{"authenticated": bool, "next": url}+.
+    class StatusController < ApplicationController
+      include RateLimited
+
+      # The cookie-bound poll: is this browser's pending login authenticated yet?
+      def show
+        render_rack(sqrl_endpoint.status(request))
+      end
+
+      private
+
+      def sqrl_rate_limit_scope
+        :status
+      end
+    end
+  end
+end

data/app/helpers/sqrl/rails/login_helper.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Rails
+    # View helpers available in the host application and the engine.
+    module LoginHelper
+      # The complete SQRL login markup (link, QR code, status text and script tag),
+      # wired to the engine's endpoints. Each render issues a fresh login URL.
+      #
+      # @param return_to [String, nil] same-site path to land on after login (defaults to
+      #   +params[:return_to]+ or Rails 8's +session[:return_to_after_authenticating]+)
+      # @param cancel_url [String, nil]
+      # @param link_user [Object, nil, false] user to link a new identity to; defaults to
+      #   the signed-in user when known, +false+ disables linking
+      # @param script [Boolean] append the +sqrl.js+ script tag
+      # @param options [Hash] passed to {SQRL::Rack::LoginBlock.render}
+      # @return [ActiveSupport::SafeBuffer]
+      def sqrl_login_block(return_to: nil, cancel_url: nil, link_user: nil, script: true, **options)
+        login = sqrl_login_url(return_to: return_to, cancel_url: cancel_url, link_user: link_user)
+        SQRL::Rack::LoginBlock.render(login_url: login.url, status_url: sqrl_status_path,
+                                      cancel_url: cancel_url, script_url: (sqrl_script_path if script),
+                                      refresh_url: sqrl_refresh_path,
+                                      **options).html_safe
+      end
+
+      # Issue (once per request) and return the +sqrl://+ login URL.
+      #
+      # @return [SQRL::Server::LoginURL]
+      def sqrl_login_url(return_to: nil, cancel_url: nil, link_user: nil)
+        @sqrl_login_url ||= begin
+          return_to ||= sqrl_default_return_to
+          link_ref = link_user == false ? nil : SQRL::Rails.user_ref(link_user || sqrl_linkable_user)
+          SQRL::Rails.endpoint_for(request).issue(request, return_to: return_to, cancel_url: cancel_url,
+                                                           link_user_ref: link_ref)
+        end
+      end
+
+      # The QR code of the login URL as inline SVG.
+      def sqrl_qr_svg(**options)
+        SQRL::Rack::QR.svg(sqrl_login_url.url, **options).html_safe
+      end
+
+      # +<script src="/sqrl/sqrl.js" defer>+
+      def sqrl_script_tag
+        SQRL::Rack::LoginBlock.script_tag(src: sqrl_script_path).html_safe
+      end
+
+      # @return [String] public path of the status poll
+      def sqrl_status_path = SQRL::Rails.path_for(:status, script_name: sqrl_host_script_name)
+      # The identity-management page of the engine (list and unlink SQRL identities).
+      def sqrl_identities_path = SQRL::Rails.path_for(:identities, script_name: sqrl_host_script_name)
+      # @return [String] public path of the login callback
+      def sqrl_callback_path = SQRL::Rails.path_for(:callback, script_name: sqrl_host_script_name)
+      # @return [String] public path of +sqrl.js+
+      def sqrl_script_path = SQRL::Rails.path_for(:script, script_name: sqrl_host_script_name)
+      # @return [String] public path of the refresh endpoint
+      def sqrl_refresh_path = SQRL::Rails.path_for(:refresh, script_name: sqrl_host_script_name)
+
+      private
+
+      # The host application's own prefix (its relative URL root), excluding the engine
+      # mount when rendering inside the engine.
+      def sqrl_host_script_name
+        name = request.script_name.to_s
+        mount = SQRL::Rails.mount_path
+        name.end_with?(mount) ? name[0, name.length - mount.length] : name
+      end
+
+      def sqrl_default_return_to
+        candidate = params[:return_to].presence || (session[:return_to_after_authenticating] if respond_to?(:session))
+        SignIn.same_site_path?(candidate) ? candidate : nil
+      rescue StandardError
+        nil
+      end
+
+      def sqrl_linkable_user
+        return nil unless SQRL::Rails.config.on_unknown_identity == :link
+
+        SignIn.current_user(controller)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end