sqrl-rack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4513d44fc6444b9976a2e286cf6edb442c68a03fd02aede2aebce4c57d8c8b3a
+  data.tar.gz: 5963d6bf1ce3f90ea6f963d4495e03f23d551c69365d346a42aa4c2ac57e539d
+SHA512:
+  metadata.gz: 80aa33c71ed274a44c315c7a10b9d1292f412a13bc7d966fc9d72b05123b00f58d62b2b2bd186d18abf8b397a9bc3917c3bbf18c8e2153804460e05989b3aaf5
+  data.tar.gz: 66d970edec43830373ee5954d2753094e286896f3472d1800c365b689e5ab62e9b6c9d0304e6fcb9d4c65913d4c51e6536d50a97890caa65058dc5513c3da933

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 — 2026-10-20
+
+First release.
+
+- `SQRL::Rack::Middleware`: the SQRL endpoint, cookie-bound status poll, CPS and poll
+  callbacks, `sqrl.js` and a refresh endpoint, with a request facade (`env["sqrl.server"]`).
+- `Sinatra::SQRL` extension and a Roda `plugin :sqrl` with the same helpers.
+- `SQRL::Rack::LoginBlock` (accessible markup with a server-side SVG QR code) and
+  `sqrl.js` (same-device probe on `localhost:25519`, polling with back-off, DOM events,
+  `SQRL.refresh`).
+- `SQRL::Rack::HostResolver`: explicit `host`, `allowed_hosts`, a bounded per-host cache.
+- Always issues `sqrl://`; `insecure_http: true` is a loopback-only testing mode.
+- `poll_requires_ip_match` (off by default) and 429 handling for rate-limit hooks.
+- Requires Ruby 3.1+, Rack 2.2 or 3.x, `rqrcode`.

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,194 @@
+# sqrl-rack
+
+SQRL login for Rack applications and Sinatra: a middleware that mounts the SQRL endpoint,
+the browser's status poll and the login callback; a Sinatra extension with view helpers;
+the browser-side `sqrl.js`; and QR code rendering. Built on
+[`sqrl-core`](../sqrl-core).
+
+## Install
+
+```ruby
+gem "sqrl-rack"   # require "sqrl/rack", "sinatra/sqrl" or plugin :sqrl (Roda)
+```
+
+## Rack
+
+```ruby
+require "rack/session"
+require "sqrl/rack"
+
+use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET"), same_site: :lax
+use SQRL::Rack::Middleware,
+    stores: SQRL::Server::Memory.stores,     # swap for a persistent implementation
+    host: "example.com",                     # the public host that ends up in sqrl:// URLs
+    on_login: ->(env, identity, pending_login) { env["rack.session"]["user_id"] = identity.idk_b64 },
+    after_login: "/"
+
+run ->(env) {
+  sqrl = env["sqrl.server"]
+  [200, { "content-type" => "text/html" }, [sqrl.login_block]]
+}
+```
+
+The middleware serves `POST /sqrl/cli` (the SQRL protocol endpoint), `GET /sqrl/status`
+(cookie-bound JSON poll), `GET /sqrl/callback` (login completion, with or without a CPS
+token) and `GET /sqrl/sqrl.js`. Everything else gets `env["sqrl.server"]`, a
+`SQRL::Rack::Facade` with `login_url`, `login_block`, `script_tag`, `qr_svg`,
+`identity`, `authenticated?` and `logout!`.
+
+Every `SQRL::Server::Config` option is accepted (`on_unknown_identity`, `ask`, `sin`,
+`require_ip_match`, `nut_ttl`, `cps_token_ttl`, ...). Without `host:` the request host is
+used. URLs are always `sqrl://` (HTTPS); see "Testing without TLS" below.
+
+## Sinatra
+
+```ruby
+require "sinatra/sqrl"
+
+class App < Sinatra::Base
+  enable :sessions
+  register Sinatra::SQRL
+  set :sqrl, host: "example.com", stores: SQRL::Server::Memory.stores
+
+  sqrl_on_login { |identity, env| env["rack.session"]["user"] = identity.idk_b64 }
+
+  get("/login") { erb :login }   # <%= sqrl_login_block %>
+  get("/")      { sqrl_authenticated? ? "Hello #{current_sqrl_identity.idk_b64}" : redirect("/login") }
+  post("/logout") { sqrl_logout!; redirect "/" }
+end
+```
+
+Helpers: `sqrl_login_url`, `sqrl_qr_svg`, `sqrl_script_tag`, `sqrl_login_block`,
+`sqrl_authenticated?`, `current_sqrl_identity`, `sqrl_logout!`, and `sqrl` (the facade).
+
+## Roda
+
+```ruby
+require "roda/plugins/sqrl"
+
+class App < Roda
+  use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET"), same_site: :lax
+  plugin :sqrl, host: "example.com", stores: SQRL::Server::Memory.stores
+
+  sqrl_on_login { |identity, env| env["rack.session"]["user"] = identity.idk_b64 }
+
+  route do |r|
+    r.get("login") { sqrl_login_block }
+    r.root { sqrl_authenticated? ? "Hello #{current_sqrl_identity.idk_b64}" : r.redirect("/login") }
+  end
+end
+```
+
+`plugin :sqrl` takes every middleware option and adds the same helpers as the Sinatra
+extension (`sqrl`, `sqrl_login_block`, `sqrl_login_url`, `sqrl_qr_svg`, `sqrl_script_tag`,
+`sqrl_authenticated?`, `current_sqrl_identity`, `sqrl_logout!`, class-level
+`sqrl_on_login`). The session must come from a Rack session middleware added with `use`
+before the plugin; Roda's own `sessions` plugin lives inside the routing tree, after the
+middleware, and cannot be used for this. The `roda` gem is not a dependency of
+`sqrl-rack`; add it yourself. See [`examples/roda-app`](../../examples/roda-app).
+
+## Hosts
+
+The host in a `sqrl://` URL is the string every identity key is derived from, so configure
+it (`host: "example.com"`) in production. Without it the middleware uses the request's
+`Host` header: it warns once, accepts only hosts matching `allowed_hosts:` when that list
+is given (strings, with or without port, or regexps), and keeps per-host state for at most
+`host_cache_limit:` (default 16) distinct hosts; requests for further hosts get `400`.
+
+```ruby
+use SQRL::Rack::Middleware, stores: stores, allowed_hosts: ["example.com", /\A[a-z0-9-]+\.example\.com\z/]
+```
+
+The scheme is never derived from the request: a site served over plain http (for example
+with TLS terminated upstream) still issues `sqrl://`.
+
+## Testing without TLS
+
+`qrl://` (plain http) is not part of the final SQRL specification and real SQRL clients do
+not accept it. The browser extension's test server, and the `sqrl-client` gem with
+`insecure: true`, do, so a site can be tried on `localhost` without a certificate:
+
+```ruby
+use SQRL::Rack::Middleware, stores: stores, host: "localhost:9292", insecure_http: true
+```
+
+`insecure_http` is refused for any host that is not loopback and logs a warning once. For
+anything a real client will scan, serve HTTPS (a self-signed certificate is fine in
+development).
+
+## Poll completions and IP matching
+
+The protocol-level check (`require_ip_match`, on by default) refuses a client whose IP
+differs from the browser's unless the client sends `noiptest`. A separate, optional
+hardening, `poll_requires_ip_match: true`, additionally refuses to complete a login
+through the browser's own cookie (the poll path, no CPS token) when the client's IP did
+not match. It is off by default because a phone on another network completing a login
+through the page's poller is a normal SQRL use; turn it on for sites that only expect
+same-network logins.
+
+## Rate limiting and pruning
+
+Two hooks let you refuse abusive traffic before any state is written. Raise
+`SQRL::Server::RateLimited` (optionally with `retry_after:`) and the middleware answers
+`429`: the SQRL client sees it on `POST /sqrl/cli`, the page's refresh call gets a JSON
+error, and `login_block` degrades to a short "temporarily unavailable" message.
+
+```ruby
+use SQRL::Rack::Middleware,
+    stores: stores, host: "example.com",
+    before_issue: ->(ctx) { raise SQRL::Server::RateLimited.new(retry_after: 30) if LoginPages.too_many?(ctx[:ip]) },
+    before_handle: ->(ctx) { raise SQRL::Server::RateLimited if ctx[:phase] == :request && Cli.too_many?(ctx[:ip]) },
+    prune_every: 500      # run Handler#prune! every 500 requests (default 1000, nil to disable)
+```
+
+`before_handle` runs twice per POST: once as soon as the request arrives
+(`phase: :request`, with `ip` and `nut`) and again when the command is known
+(`phase: :command`, adding `command` and `idk`). With [Rack::Attack](https://github.com/rack/rack-attack)
+the same limits can sit in front of the middleware instead:
+
+```ruby
+Rack::Attack.throttle("sqrl/cli", limit: 60, period: 60) { |req| req.ip if req.post? && req.path == "/sqrl/cli" }
+Rack::Attack.throttle("sqrl/login-page", limit: 20, period: 60) { |req| req.ip if req.get? && req.path == "/login" }
+```
+
+Expired nuts and pending logins are deleted opportunistically every `prune_every`
+requests; call `handler.prune!` from a scheduler if you would rather control it.
+
+## The browser script
+
+`sqrl.js` probes for a local client on `localhost:25519`, polls `/sqrl/status` with
+exponential back-off after errors (capped at 10 s), and when the server reports the login
+code as expired shows a "Get a new code" button that calls `GET /sqrl/refresh`. That
+endpoint issues a new pending login and nut for the browser session and returns
+`{"sqrl_url", "status_url", "refresh_url", "qr_svg"}`, which the script swaps into the
+page without a reload (`SQRL.refresh(rootElement)` does the same from your code). The root
+element dispatches `sqrl:cps-detected`, `sqrl:authenticated` (`detail.next`),
+`sqrl:expired`, `sqrl:refreshed` (`detail.sqrlUrl`) and `sqrl:error` events.
+
+## How a login completes
+
+1. The login page calls `login_url`, which issues a nut and stores a pending-login id in
+   the browser session; `login_block` renders the `sqrl://` link, the QR code and
+   `sqrl.js`.
+2. The SQRL client POSTs `query` then `ident` to `/sqrl/cli`.
+3. Same device (CPS): the client receives a one-time `url=` and sends the browser to
+   `/sqrl/callback?t=TOKEN`. The token is claimed once and must belong to the pending
+   login in that browser's session.
+4. Other device: `sqrl.js` polls `/sqrl/status`; once authenticated it navigates to
+   `/sqrl/callback`, which completes the browser's own pending login once.
+5. The middleware stores the identity in the session, runs `on_login`, and redirects to the
+   pending login's `return_to` or `after_login`.
+
+See [`examples/rack-app`](../../examples/rack-app) and
+[`examples/sinatra-app`](../../examples/sinatra-app). and [`examples/roda-app`](../../examples/roda-app).
+
+## Testing
+
+`bundle exec rake spec:sqrl-rack` runs the middleware, Sinatra and Roda specs with
+Rack::Test, driving the client side with `SQRL::Session`; the repository's integration suite
+boots the three example apps over HTTPS and runs the `sqrl-client` conformance suite and a
+headless browser against them.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/assets/sqrl.js

@@ -0,0 +1,165 @@
+/*
+ * sqrl.js - browser side of SQRL login for the sqrl-rack / sqrl-rails gems.
+ *
+ * Attaches to every element with [data-sqrl-login]. Attributes:
+ *   data-sqrl-url      the sqrl:// login URL
+ *   data-sqrl-status   URL of the cookie-bound status poll endpoint
+ *   data-sqrl-refresh  URL of the JSON endpoint that hands out a fresh login URL (optional)
+ *   data-sqrl-poll     poll interval in milliseconds (default 2000)
+ *   data-sqrl-text-*   message texts (message, cps, done, expired)
+ * Children (optional): a[data-sqrl-link], [data-sqrl-qr], [data-sqrl-message],
+ * button[data-sqrl-refresh-button].
+ *
+ * 1. Same-device Client Provided Session (CPS) probe: native SQRL clients and the browser
+ *    extension listen on http://localhost:25519/. When the probe image loads, the login link
+ *    is pointed at http://localhost:25519/<base64url sqrl url>.
+ * 2. Polling for logins from another device: the status endpoint is bound to this
+ *    browser's session cookie and answers {"authenticated": true, "next": url} once done,
+ *    or {"expired": true} when the login code is no longer valid. Errors back the poll
+ *    off (up to 10 s) and a success resets it.
+ * 3. Refresh: SQRL.refresh(root) asks the refresh endpoint for a new login URL and swaps
+ *    the link and QR code in place; the "Get a new code" button appears on expiry.
+ *
+ * Events dispatched on the root element: sqrl:cps-detected, sqrl:authenticated (detail:
+ * {next}), sqrl:expired, sqrl:refreshed (detail: {sqrlUrl}), sqrl:error (detail: {error}).
+ */
+(function () {
+  "use strict";
+
+  var CPS_ORIGIN = "http://localhost:25519/";
+  var MAX_BACKOFF = 10000;
+
+  function base64url(str) {
+    var bytes = new TextEncoder().encode(str);
+    var bin = "";
+    for (var i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  }
+
+  function text(root, key, fallback) {
+    return root.getAttribute("data-sqrl-text-" + key) || fallback;
+  }
+
+  function setMessage(root, msg) {
+    var el = root.querySelector("[data-sqrl-message]");
+    if (el) el.textContent = msg;
+  }
+
+  function emit(root, name, detail) {
+    root.dispatchEvent(new CustomEvent(name, { bubbles: true, detail: detail || {} }));
+  }
+
+  function applyLink(root) {
+    var link = root.querySelector("a[data-sqrl-link]");
+    var url = root.getAttribute("data-sqrl-url");
+    if (!link || !url) return;
+    link.href = root.getAttribute("data-sqrl-cps") === "true" ? CPS_ORIGIN + base64url(url) : url;
+  }
+
+  function probeCps(root) {
+    var img = new Image();
+    img.onload = function () {
+      root.setAttribute("data-sqrl-cps", "true");
+      var link = root.querySelector("a[data-sqrl-link]");
+      if (link) link.setAttribute("data-sqrl-cps", "true");
+      applyLink(root);
+      setMessage(root, text(root, "cps", "Local SQRL client detected."));
+      emit(root, "sqrl:cps-detected");
+    };
+    img.onerror = function () {
+      root.setAttribute("data-sqrl-cps", "false");
+      var link = root.querySelector("a[data-sqrl-link]");
+      if (link) link.setAttribute("data-sqrl-cps", "false");
+    };
+    img.src = CPS_ORIGIN + Math.random().toString(36).slice(2) + ".gif";
+  }
+
+  function startPolling(root) {
+    if (root.sqrlStopPolling) root.sqrlStopPolling();
+    var statusUrl = root.getAttribute("data-sqrl-status");
+    if (!statusUrl) return;
+    var base = parseInt(root.getAttribute("data-sqrl-poll") || "2000", 10) || 2000;
+    var delay = base;
+    var stopped = false;
+    function schedule() { if (!stopped) window.setTimeout(tick, delay); }
+    function tick() {
+      if (stopped) return;
+      fetch(statusUrl, { credentials: "same-origin", cache: "no-store", headers: { Accept: "application/json" } })
+        .then(function (r) { if (!r.ok) throw new Error("status " + r.status); return r.json(); })
+        .then(function (j) {
+          delay = base;
+          if (j.authenticated && j.next) {
+            stopped = true;
+            setMessage(root, text(root, "done", "Logged in, redirecting…"));
+            emit(root, "sqrl:authenticated", { next: j.next });
+            window.location.href = j.next;
+          } else if (j.expired) {
+            stopped = true;
+            expire(root);
+          } else {
+            schedule();
+          }
+        })
+        .catch(function (e) {
+          delay = Math.min(delay * 2, MAX_BACKOFF);
+          emit(root, "sqrl:error", { error: e });
+          schedule();
+        });
+    }
+    schedule();
+    root.sqrlStopPolling = function () { stopped = true; };
+  }
+
+  function expire(root) {
+    root.setAttribute("data-sqrl-expired", "true");
+    setMessage(root, text(root, "expired", "This login code expired. Reload the page to get a new one."));
+    var button = root.querySelector("[data-sqrl-refresh-button]");
+    if (button && root.getAttribute("data-sqrl-refresh")) button.hidden = false;
+    emit(root, "sqrl:expired");
+  }
+
+  function refresh(root) {
+    var url = root.getAttribute("data-sqrl-refresh");
+    if (!url) return Promise.reject(new Error("no data-sqrl-refresh"));
+    return fetch(url, { credentials: "same-origin", cache: "no-store", headers: { Accept: "application/json" } })
+      .then(function (r) { if (!r.ok) throw new Error("refresh " + r.status); return r.json(); })
+      .then(function (j) {
+        root.setAttribute("data-sqrl-url", j.sqrl_url);
+        if (j.status_url) root.setAttribute("data-sqrl-status", j.status_url);
+        root.removeAttribute("data-sqrl-expired");
+        applyLink(root);
+        var qr = root.querySelector("[data-sqrl-qr]");
+        if (qr && j.qr_svg) qr.innerHTML = j.qr_svg;
+        var button = root.querySelector("[data-sqrl-refresh-button]");
+        if (button) button.hidden = true;
+        setMessage(root, text(root, "message", ""));
+        startPolling(root);
+        emit(root, "sqrl:refreshed", { sqrlUrl: j.sqrl_url });
+        return j;
+      });
+  }
+
+  function init(root) {
+    if (root.getAttribute("data-sqrl-initialized")) return;
+    root.setAttribute("data-sqrl-initialized", "true");
+    if (root.getAttribute("data-sqrl-url")) probeCps(root);
+    var button = root.querySelector("[data-sqrl-refresh-button]");
+    if (button) button.addEventListener("click", function () { refresh(root).catch(function () { expire(root); }); });
+    startPolling(root);
+  }
+
+  function initAll() {
+    var roots = document.querySelectorAll("[data-sqrl-login]");
+    for (var i = 0; i < roots.length; i++) init(roots[i]);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initAll);
+  } else {
+    initAll();
+  }
+  document.addEventListener("turbo:load", initAll);
+  window.SQRL = window.SQRL || {};
+  window.SQRL.init = initAll;
+  window.SQRL.refresh = refresh;
+})();

data/lib/roda/plugins/sqrl.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "roda"
+require "sqrl/rack"
+
+# Roda namespace, reopened to add the +:sqrl+ plugin.
+class Roda
+  # Roda's plugin namespace.
+  module RodaPlugins
+    # SQRL login for Roda.
+    #
+    #   require "roda"
+    #   require "roda/plugins/sqrl"   # or just `plugin :sqrl` with sqrl-rack on the load path
+    #
+    #   class App < Roda
+    #     use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET"), same_site: :lax
+    #     plugin :sqrl, host: "example.com", stores: SQRL::Server::Memory.stores
+    #
+    #     sqrl_on_login { |identity, env| env["rack.session"]["user"] = identity.idk_b64 }
+    #
+    #     route do |r|
+    #       r.get("login") { sqrl_login_block }
+    #       r.root { sqrl_authenticated? ? "hello #{current_sqrl_identity.idk_b64}" : r.redirect("/login") }
+    #     end
+    #   end
+    #
+    # The plugin adds {SQRL::Rack::Middleware} to the application's middleware stack with
+    # every option given to +plugin :sqrl+ (see {SQRL::Rack::Middleware} and
+    # {SQRL::Server::Config}). Because the middleware runs *before* the Roda routing tree,
+    # the session it binds logins to must come from a Rack session middleware
+    # (+Rack::Session::Cookie+, +Rack::Session::Pool+, ...) added with +use+ before
+    # +plugin :sqrl+. Roda's own +sessions+ plugin keeps the session inside the routing
+    # tree, where the middleware cannot see it, and is therefore not supported; the
+    # middleware raises a clear error when no +rack.session+ is present.
+    module SQRL
+      # Accepts every option of SQRL::Rack::Middleware.
+      def self.configure(app, opts = {})
+        app.opts[:sqrl] = (app.opts[:sqrl] || {}).merge(opts.transform_keys(&:to_sym))
+        app.opts[:sqrl_login_hooks] ||= []
+        return if app.opts[:sqrl_middleware_installed]
+
+        app.opts[:sqrl_middleware_installed] = true
+        app.use ::SQRL::Rack::Middleware, -> { SQRL.middleware_options(app) }
+      end
+
+      # Merge the user hooks into the middleware's +on_login+ (same shape as the Sinatra
+      # extension).
+      def self.middleware_options(app)
+        hooks = app.opts[:sqrl_login_hooks] || []
+        opts = (app.opts[:sqrl] || {}).dup
+        return opts if hooks.empty?
+
+        user_hook = opts[:on_login]
+        opts[:session_identity] = true unless opts.key?(:session_identity)
+        opts[:on_login] = lambda do |env, identity, pending_login|
+          user_hook&.call(env, identity, pending_login)
+          hooks.each { |h| h.call(identity, env, pending_login) }
+        end
+        opts
+      end
+
+      # Class-level API: +plugin :sqrl+ options and the +sqrl_on_login+ hook.
+      module ClassMethods
+        # Register a block called after every successful SQRL login with
+        # +(identity, env, pending_login)+.
+        def sqrl_on_login(&block)
+          opts[:sqrl_login_hooks] = (opts[:sqrl_login_hooks] || []) + [block]
+        end
+
+        # The options the middleware was installed with.
+        def sqrl_options = opts[:sqrl] || {}
+      end
+
+      # Helpers available inside the routing block.
+      module InstanceMethods
+        # @return [SQRL::Rack::Facade]
+        def sqrl
+          env["sqrl.server"] or raise ::SQRL::Rack::Error, "SQRL middleware did not run for this request"
+        end
+
+        # @return [String] a fresh +sqrl://+ login URL for this request
+        def sqrl_login_url(**options) = sqrl.login_url(**options).url
+        # @return [String] the login URL as an SVG QR code
+        def sqrl_qr_svg(**options) = sqrl.qr_svg(**options)
+        # @return [String] a +<script>+ tag loading +sqrl.js+
+        def sqrl_script_tag = sqrl.script_tag
+        # @return [String] the complete login block markup
+        def sqrl_login_block(**options) = sqrl.login_block(**options)
+        def sqrl_authenticated? = sqrl.authenticated?
+        # @return [SQRL::Server::Identity, nil] the identity logged in through SQRL in this session
+        def current_sqrl_identity = sqrl.identity
+        # Forget the SQRL identity held in the session.
+        # @return [void]
+        def sqrl_logout! = sqrl.logout!
+      end
+
+      # The same helpers on the request object, for people who route everything through +r+.
+      module RequestMethods
+        # @return [SQRL::Rack::Facade] the request-scoped facade
+        def sqrl = scope.sqrl
+        def sqrl_authenticated? = scope.sqrl_authenticated?
+        # @return [SQRL::Server::Identity, nil] the identity logged in through SQRL in this session
+        def current_sqrl_identity = scope.current_sqrl_identity
+      end
+    end
+
+    register_plugin(:sqrl, SQRL)
+  end
+end

data/lib/sinatra/sqrl.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "sinatra/base"
+require "sqrl/rack"
+
+# Sinatra namespace, reopened to add the SQRL extension.
+module Sinatra
+  # SQRL login for Sinatra.
+  #
+  #   require "sinatra/sqrl"
+  #
+  #   class App < Sinatra::Base
+  #     enable :sessions
+  #     register Sinatra::SQRL
+  #     set :sqrl, host: "example.com", stores: SQRL::Server::Memory.stores
+  #
+  #     sqrl_on_login { |identity, env| env["rack.session"]["user"] = identity.idk_b64 }
+  #
+  #     get("/login") { sqrl_login_block }
+  #     get("/") { sqrl_authenticated? ? "hello #{current_sqrl_identity.idk_b64}" : redirect("/login") }
+  #   end
+  #
+  # Registering adds {SQRL::Rack::Middleware} to the app. Sinatra builds its own session
+  # and +Rack::Protection+ middleware before any +use+d middleware, so the session is
+  # available and the SQRL endpoint is reached before the application; with sessions on,
+  # +Rack::Protection+'s defaults let the SQRL client's token-less POST through (it has
+  # no cross-site referrer). Options given with +set :sqrl+ are read when the app is
+  # built, so their order relative to +register+ does not matter.
+  module SQRL
+    # Instance helpers.
+    module Helpers
+      # @return [SQRL::Rack::Facade]
+      def sqrl
+        env["sqrl.server"] or raise ::SQRL::Rack::Error, "SQRL middleware did not run for this request"
+      end
+
+      # @return [String] a fresh +sqrl://+ login URL for this request (see {SQRL::Rack::Facade#login_url})
+      def sqrl_login_url(**options) = sqrl.login_url(**options).url
+      # @return [String] the login URL as an SVG QR code
+      def sqrl_qr_svg(**options) = sqrl.qr_svg(**options)
+      # @return [String] a +<script>+ tag loading +sqrl.js+
+      def sqrl_script_tag = sqrl.script_tag
+      # @return [String] the complete login block markup (see {SQRL::Rack::LoginBlock.render})
+      def sqrl_login_block(**options) = sqrl.login_block(**options)
+      def sqrl_authenticated? = sqrl.authenticated?
+      # @return [SQRL::Server::Identity, nil] the identity logged in through SQRL in this session
+      def current_sqrl_identity = sqrl.identity
+      # Forget the SQRL identity held in the session.
+      # @return [void]
+      def sqrl_logout! = sqrl.logout!
+    end
+
+    # Register a block called after every successful SQRL login with
+    # +(identity, env, pending_login)+.
+    def sqrl_on_login(&block)
+      set :sqrl_login_hooks, sqrl_login_hooks + [block]
+    end
+
+    # Sinatra extension hook: installs the middleware lazily and the helpers.
+    # @param app [Class] the Sinatra application
+    def self.registered(app)
+      app.helpers Helpers
+      app.set :sqrl, {} unless app.respond_to?(:sqrl)
+      app.set :sqrl_login_hooks, []
+      app.use ::SQRL::Rack::Middleware, -> { middleware_options(app) }
+    end
+
+    # The middleware options derived from +set :sqrl+.
+    # @api private
+    def self.middleware_options(app)
+      hooks = app.sqrl_login_hooks
+      opts = (app.sqrl || {}).transform_keys(&:to_sym)
+      return opts if hooks.empty?
+
+      user_hook = opts[:on_login]
+      opts[:session_identity] = true unless opts.key?(:session_identity)
+      opts[:on_login] = lambda do |env, identity, pending_login|
+        user_hook&.call(env, identity, pending_login)
+        hooks.each { |h| h.call(identity, env, pending_login) }
+      end
+      opts
+    end
+  end
+
+  register SQRL
+end

data/lib/sqrl/rack/assets.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SQRL
+  module Rack
+    # The browser-side script shipped with the gem (+assets/sqrl.js+).
+    module Assets
+      # Directory holding +sqrl.js+.
+      ASSETS_DIR = File.expand_path("../../../assets", __dir__)
+
+      module_function
+
+      # Absolute path of +sqrl.js+.
+      def javascript_path
+        File.join(ASSETS_DIR, "sqrl.js")
+      end
+
+      # Contents of +sqrl.js+ (memoized).
+      def javascript
+        @javascript ||= File.read(javascript_path, encoding: "UTF-8").freeze
+      end
+
+      # Short content digest, usable as an ETag or cache-busting token.
+      def javascript_digest
+        @javascript_digest ||= Digest::SHA256.hexdigest(javascript)[0, 16].freeze
+      end
+    end
+  end
+end