sqrl-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fcfd84f13a0b97bdd7742c8ff8d7cc918cada5c3ce355f51233c77e69463aa6
+  data.tar.gz: 0eef85f22ed8e989649837454f1ceb28994dfd3d3f71ac10b54dac0631ddbd93
+SHA512:
+  metadata.gz: 896a8745c0a4fdcb39babdb3ad61776b377eac8d60a45a50eb5edbababc62e3e8139f83667edb7ab9cdcd67903c1fa26427dc24f0424b5bd9f2c1ddc05a06442
+  data.tar.gz: 6651d2647ce80e827fe772770e69eae96bf46c1a7e9e4d1088e7c113759db729e9cafc0de2d7eac1c335a4c6cedf1843bc16fe9f4afc634f8605fa5e38e0ce29

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — 2026-10-20
+
+First release.
+
+- `SQRL::Client::Agent`: login, query, disable, enable, remove against any SQRL site, with
+  login-page discovery, previous-identity handling, `ask` and `sin` answering, transient
+  retry and CPS handoff on the same cookie jar.
+- Identities: S4 files, textual identities, ephemeral identities, environment loading,
+  rekey and password change.
+- `SQRL::Client::Transport` (Net::HTTP, cookie jar, TLS options; plain HTTP refused unless
+  `insecure: true`), `SQRL::Client::Capybara` helper, and the `sqrl-client` executable with
+  Netscape/JSON cookie export.
+- A 23-case server conformance suite usable from Ruby, RSpec (`it_behaves_like "a SQRL
+  server"`) and the command line, with JUnit output.
+- Requires Ruby 3.1+ and `http-cookie`.

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,154 @@
+# sqrl-client
+
+A bot-capable [SQRL](https://www.grc.com/sqrl/sqrl.htm) client for Ruby: everything a
+script, a test suite or an automated service needs to log in to a SQRL-enabled website
+without a browser or a human. It is also the test driver for the `sqrl-*` server gems and
+ships a conformance suite any SQRL server can be checked against.
+
+## Install
+
+```ruby
+gem "sqrl-client"
+```
+
+```ruby
+require "sqrl/client"
+
+identity = SQRL::Client::Identity.load("bot.sqrl", password: ENV["SQRL_PASSWORD"])
+agent    = SQRL::Client::Agent.new(identity: identity)
+result   = agent.login("https://example.com/login")   # a login page, a sqrl:// URL or a localhost:25519 link
+
+result.authenticated?   # => true
+result.created?         # => true on the first visit (the site created the account)
+result.idk              # => the site-specific public key, base64url
+result.landing          # => the response of following the CPS url= (logged-in page)
+agent.http.get("https://example.com/account")   # same cookie jar: already logged in
+```
+
+## Identities
+
+| Call | Use |
+| --- | --- |
+| `Identity.load(path, password:)` | an S4 identity file (binary `sqrldata` or `SQRLDATA` text), as exported by any SQRL client |
+| `Identity.from_textual(text, rescue_code:, password:)` | import a base56 textual identity |
+| `Identity.create(password:)` | a brand-new identity; `#rescue_code` is shown once |
+| `Identity.ephemeral` / `Identity.ephemeral("seed")` | an identity straight from a random or deterministic IUK, no EnScrypt; ideal for tests |
+| `Identity.from_env` | `SQRL_IUK_HEX`, or `SQRL_IDENTITY_FILE` + `SQRL_PASSWORD`/`SQRL_PASSWORD_FILE` (+ `SQRL_RESCUE_CODE`) |
+
+`enable`, `remove` and `rekey!` need the Identity Unlock Key. Ephemeral and freshly created
+identities have it; file identities get it from `rescue_code:` (slow: EnScrypt).
+
+## The agent
+
+```ruby
+agent = SQRL::Client::Agent.new(
+  identity: identity,
+  cps: true,                 # request a Client Provided Session and follow its url=
+  unknown_site: :create,     # or :refuse to never create accounts
+  options: { sqrlonly: false, hardlock: false, noiptest: false },
+  alt_id: nil,
+  ask_handler: ->(ask) { ask.buttons.index { |b| b.label =~ /allow/i }.to_i + 1 },
+  insecure: false            # true: accept plain http and qrl:// for loopback test servers only
+)
+
+agent.login(url)                       # query → (ask) → ident; creates / logs in / re-keys as the site answers
+agent.query(url)                       # does the site know me? (state :unknown / :known / :previous_known)
+agent.disable(url)
+agent.enable(url, rescue_code: "…")    # rescue code not needed for identities that hold the IUK
+agent.remove(url, rescue_code: "…")
+```
+
+Every result carries the full `transcript` of the exchange (signatures are not recorded),
+the TIF history, the cancel URL and the cookie jar. Failures raise `LoginFailed` with a
+`reason` (`:disabled`, `:superseded`, `:unknown_site`, `:ip_mismatch`, `:transient`, …),
+`AskRequired` when the site asks a question and no handler is set, `DiscoveryError` when no
+`sqrl://` link is on the page, or `TransportError`.
+
+Transient errors are retried with the fresh nut, previous identities are offered in turn
+(`PREVIOUS_ID_MATCH` re-keys the account), `sin`/`ins` and `pins` are answered, and the CPS
+`url=` is validated to point at the site before it is followed.
+
+SQRL is `sqrl://` over HTTPS, and that is all the agent speaks by default. `insecure: true`
+(CLI: `--insecure`) is a loopback-only testing mode that also accepts plain-http pages and
+`qrl://` links, which the browser extension's test server and this repository's own spec
+site use; `qrl://` is not part of the final SQRL specification and real clients refuse
+it. A self-signed development certificate is trusted with `Transport.new(ca_file:)`
+(CLI: `--ca-file`); `--no-verify-tls` turns verification off altogether.
+
+## Capybara
+
+```ruby
+visit "/login"
+SQRL::Client::Capybara.login(page, identity: SQRL::Client::Identity.ephemeral("bot"))
+expect(page).to have_content("Welcome")
+```
+
+The protocol runs out of band; the **browser** then visits the one-time CPS URL, exactly as a
+native client would redirect the tab, so the browser's own session is the one logged in.
+`cps: false` performs `ident` only and waits for the page's poller to redirect.
+
+## Command line
+
+```
+sqrl-client identity create  --out bot.sqrl --password-file pw.txt       # prints the rescue code once
+sqrl-client identity import  --textual id.txt --rescue-code 1234-… --out bot.sqrl
+sqrl-client identity show    --identity bot.sqrl [--json]
+sqrl-client identity export  --identity bot.sqrl --format s4-text|textual|binary [--out FILE]
+sqrl-client identity rekey   --identity bot.sqrl --password … --rescue-code …   # new IUK, old one kept as previous
+sqrl-client identity change-password --identity bot.sqrl --password OLD --new-password NEW
+sqrl-client identity previous --identity bot.sqrl                        # superseded identities, most recent first
+sqrl-client login   https://example.com/login --identity bot.sqrl --cookies-out jar.txt [--no-cps] [--alt-id ID] [--json]
+sqrl-client query | disable | enable | remove URL …                      # enable/remove need --rescue-code
+sqrl-client conformance https://example.com/login [--report junit.xml] [--feature ask=on] [--only CASE,…]
+```
+
+Identities come from `--identity FILE` with `--password`/`--password-file`, from the
+`SQRL_IDENTITY_FILE`/`SQRL_PASSWORD`/`SQRL_PASSWORD_FILE`/`SQRL_RESCUE_CODE` variables, or
+from `--iuk-hex`/`SQRL_IUK_HEX` for throwaway test identities. `--pw-seconds` and
+`--rescue-seconds` shorten EnScrypt for test identities. Exit codes: 0 success, 1 the site
+refused (protocol), 2 transport failure, 3 usage. Cookies are written in Netscape format
+(`curl -b jar.txt`) or JSON (`--cookies-format json`).
+
+## Conformance suite
+
+```ruby
+report = SQRL::Client::Conformance::Runner.new(login_url: "https://example.com/login").run
+puts report            # PASS / FAIL / SKIP per case
+report.passed?
+report.to_junit_xml
+```
+
+Cases cover account creation, login with and without CPS, disable/enable/remove, re-keying
+and superseded identities, `ask`/`btn`, `sin`/`ins`, Alt-IDs, nut replay, unknown nuts,
+tampered requests, wrong `server=` echoes, bad signatures, identity creation without
+`suk`/`vuk`, one-time CPS tokens, transient recovery and concurrent logins. Feature flags
+(`features: { ask: true, sin: true, cps_single_use: false, … }`) skip what a site does not
+do; a custom `site:` adapter handles pages with unusual layouts.
+
+In RSpec:
+
+```ruby
+require "sqrl/client/conformance/rspec"
+
+RSpec.describe "my site" do
+  let(:login_url) { "http://127.0.0.1:9292/login" }
+  it_behaves_like "a SQRL server"
+end
+```
+
+## Limits
+
+Ruby cannot wipe memory reliably; key material lives in ordinary Strings. Sites that show
+only a QR image (no `sqrl://` link anywhere in the page) are not supported yet. SQRL for
+APIs is not specified yet and therefore not implemented.
+
+## Testing
+
+The gem's own specs boot a small Rack site backed by `SQRL::Server::Handler`; this
+repository's integration suite (`spec/integration`) drives every example application with
+this client over HTTPS, and `spec/interop` runs the conformance suite against the Rust
+reference server. Run `bundle exec rake spec:sqrl-client`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/sqrl-client

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "sqrl/client"
+require "sqrl/client/cli"
+
+exit SQRL::Client::CLI.run(ARGV)

data/lib/sqrl/client/agent.rb

@@ -0,0 +1,399 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SQRL
+  module Client
+    # The outcome of one {Agent} operation.
+    class LoginResult
+      # @return [Symbol] +:query+, +:ident+, +:disable+, +:enable+ or +:remove+
+      attr_reader :command
+      # @return [String] the +sqrl://+ URL that was used
+      attr_reader :sqrl_url
+      # @return [SQRL::Session::State] state after the last exchange
+      attr_reader :state
+      # @return [SQRL::Tif, nil] TIF of the last response
+      attr_reader :tif
+      # @return [Array<SQRL::Tif>] every TIF received, in order
+      attr_reader :tif_history
+      # @return [String] the identity's per-site public key, base64url
+      attr_reader :idk
+      # @return [String, nil] the validated CPS +url=+ when the server sent one
+      attr_reader :cps_url
+      # @return [Transport::Response, nil] the response of following the CPS URL
+      attr_reader :landing
+      # @return [Hash, nil] the last JSON answer of the status poll (non-CPS logins)
+      attr_reader :status
+      # @return [HTTP::CookieJar] the cookies, including those set by the landing page
+      attr_reader :cookies
+      # @return [Array<Hash>] one entry per wire exchange (signatures are not recorded)
+      attr_reader :transcript
+      # @return [SQRL::Ask, nil] the question the server posed, if any
+      attr_reader :ask
+      # @return [Integer, nil] the button that answered it
+      attr_reader :button
+      # @return [String, nil] the cancel URL offered by the site
+      attr_reader :cancel_url
+
+      # @api private
+      def initialize(command:, sqrl_url:, state:, tif:, tif_history:, idk:, cookies:, transcript:, created: false,
+                     rekeyed: false, authenticated: false, cps_url: nil, landing: nil, status: nil, ask: nil,
+                     button: nil, cancel_url: nil)
+        @command = command
+        @sqrl_url = sqrl_url
+        @state = state
+        @tif = tif
+        @tif_history = tif_history
+        @idk = idk
+        @cookies = cookies
+        @transcript = transcript
+        @created = created
+        @rekeyed = rekeyed
+        @authenticated = authenticated
+        @cps_url = cps_url
+        @landing = landing
+        @status = status
+        @ask = ask
+        @button = button
+        @cancel_url = cancel_url
+      end
+
+      # Whether the site accepted the login (or enable) and the session is established.
+      def authenticated? = @authenticated
+      # Whether this operation created the account on the site.
+      def created? = @created
+      # Whether this operation moved the site's account to a re-keyed identity.
+      def rekeyed? = @rekeyed
+      # Whether the site knows the identity (after a +query+).
+      def known? = state.known?
+      def disabled? = state.disabled?
+
+      # @return [Hash] a JSON-friendly summary (no secrets)
+      def to_h
+        { command: command, sqrl_url: sqrl_url, state: state.kind, disabled: state.disabled?, tif: tif&.to_hex,
+          idk: idk, authenticated: authenticated?, created: created?, rekeyed: rekeyed?, cps_url: cps_url,
+          landing_status: landing&.status, landing_url: landing&.final_url, ask: ask&.message, button: button }
+      end
+
+      # @return [String] a short description with secret material redacted
+      def inspect
+        "#<SQRL::Client::LoginResult #{command} #{state.kind} authenticated=#{authenticated?}>"
+      end
+    end
+
+    # A headless SQRL client that performs whole transactions against a site: discovery of
+    # the login link, the +query+ → +ident+ dance (including account creation, re-keying,
+    # previous identities, +ask+ answers and +sin+/+ins+), the CPS handoff, and the account
+    # commands +disable+, +enable+ and +remove+.
+    class Agent
+      # Seconds between status polls for non-CPS logins.
+      DEFAULT_POLL_INTERVAL = 0.5
+
+      attr_reader :identity, :transport, :options, :alt_id, :logger
+      attr_accessor :cps, :follow_cps, :unknown_site, :ask_handler, :max_transient_retries, :poll, :poll_interval,
+                    :poll_timeout
+
+      # @param identity [Identity]
+      # @param transport [#get, #post_form] defaults to a fresh {Transport}
+      # @param cps [Boolean] request a Client Provided Session (+url=+)
+      # @param follow_cps [Boolean] GET the CPS +url=+ with the agent's own cookie jar; set
+      #   to false when something else (a browser) will visit it, since the token is one-time
+      # @param unknown_site [Symbol] +:create+ an account on sites that do not know the
+      #   identity, or +:refuse+ to
+      # @param options [Hash] +sqrlonly:+, +hardlock:+, +noiptest:+
+      # @param alt_id [String, nil] SQRL Alt-ID (a different identity on the same site)
+      # @param ask_handler [#call, nil] receives the {SQRL::Ask} and returns the button
+      #   number (0 for the plain OK, 1 or 2); without one an +ask+ raises {AskRequired}
+      # @param max_transient_retries [Integer]
+      # @param poll [Boolean] for non-CPS logins, poll the site's status URL when one was
+      #   discovered
+      # @param poll_timeout [Numeric] seconds
+      # +insecure: true+ accepts the loopback-only +qrl://+ (plain http) testing mode and
+      # lets the default transport speak plain http to loopback hosts. Off by default:
+      # SQRL is +sqrl://+ over HTTPS.
+      def initialize(identity:, transport: nil, cps: true, follow_cps: true, unknown_site: :create, options: {},
+                     alt_id: nil, ask_handler: nil, max_transient_retries: 2, poll: true,
+                     poll_interval: DEFAULT_POLL_INTERVAL, poll_timeout: 10, logger: nil, insecure: false)
+        raise ArgumentError, "unknown_site must be :create or :refuse" unless %i[create refuse].include?(unknown_site)
+
+        @identity = identity
+        @insecure = insecure ? true : false
+        @transport = transport || Transport.new(logger: logger, allow_http: @insecure ? :loopback : false)
+        @cps = cps
+        @follow_cps = follow_cps
+        @unknown_site = unknown_site
+        @options = { sqrlonly: false, hardlock: false, noiptest: false }.merge(options)
+        @alt_id = alt_id
+        @ask_handler = ask_handler
+        @max_transient_retries = max_transient_retries
+        @poll = poll
+        @poll_interval = poll_interval
+        @poll_timeout = poll_timeout
+        @logger = logger
+      end
+
+      # The transport, for the bot's own requests after logging in.
+      alias http transport
+
+      # Whether plain-http / +qrl://+ loopback testing mode is on.
+      def insecure? = @insecure
+
+      # Log in (creating the account, or re-keying it, as the site's answer dictates).
+      #
+      # @param target [String] a login page URL, a +sqrl://+ URL or a
+      #   +localhost:25519/<b64>+ CPS link
+      # @return [LoginResult]
+      # @raise [LoginFailed, AskRequired, DiscoveryError, TransportError]
+      def login(target)
+        run(target, :ident)
+      end
+
+      # Ask the site whether it knows the identity, without logging in.
+      def query(target)
+        run(target, :query)
+      end
+
+      # Disable SQRL login for the account on the site.
+      def disable(target)
+        run(target, :disable)
+      end
+
+      # Re-enable SQRL login. Needs the IUK (ephemeral/created identities have it; file
+      # identities take +rescue_code:+).
+      def enable(target, rescue_code: nil)
+        run(target, :enable, rescue_code: rescue_code)
+      end
+
+      # Remove the SQRL association from the account. Needs the IUK like {#enable}.
+      def remove(target, rescue_code: nil)
+        run(target, :remove, rescue_code: rescue_code)
+      end
+
+      # Discover the login link for +target+ without talking SQRL.
+      #
+      # @return [Discovery::Result]
+      def discover(target)
+        direct = Discovery.from_target(target)
+        return direct if direct
+
+        page = @transport.get(target)
+        unless page.success?
+          raise TransportError.new("login page #{target} answered #{page.status}", url: target, status: page.status)
+        end
+
+        Discovery.find(page.body, base_url: page.final_url)
+      end
+
+      private
+
+      def client_options
+        ClientOptions.new(cps: @cps, sqrlonly: @options[:sqrlonly], hardlock: @options[:hardlock],
+                          noiptest: @options[:noiptest])
+      end
+
+      def run(target, command, rescue_code: nil)
+        found = discover(target)
+        session = Session.new(@identity.unlocked, found.sqrl_url, options: client_options, alt_id: @alt_id,
+                                                                  insecure: @insecure)
+        ctx = Context.new(found, session)
+        transient = 0
+
+        loop do
+          query_until_settled(ctx)
+          break if command == :query
+
+          ctx.pre_state = session.state
+          answer_ask(ctx)
+          request = build_command(ctx, command, rescue_code)
+          exchange(ctx, request)
+          break unless session.state.transient?
+
+          transient += 1
+          next unless transient > @max_transient_retries
+
+          raise LoginFailed.new("the server kept answering with a transient error", reason: :transient,
+                                                                                    tif: session.last_response.tif,
+                                                                                    state: session.state)
+        end
+
+        finish(ctx, command)
+      end
+
+      # Small bag of per-transaction state. @api private
+      Context = Struct.new(:found, :session, :pre_state, :tifs, :transcript, :ask, :button, :landing, :status) do
+        def initialize(found, session)
+          super(found, session, nil, [], [], nil, nil, nil, nil)
+        end
+      end
+
+      # Query until the server has classified the identity, retrying on transient errors
+      # and walking the previous identities when the current one is unknown.
+      def query_until_settled(ctx)
+        session = ctx.session
+        transient = 0
+        loop do
+          exchange(ctx, session.query)
+          state = session.state
+          case state.kind
+          when :transient
+            transient += 1
+            next if transient <= @max_transient_retries
+
+            raise LoginFailed.new("the server kept answering with a transient error", reason: :transient,
+                                                                                      tif: session.last_response.tif, state: state)
+          when :unknown
+            next if session.has_previous? && session.try_next_previous
+
+            return
+          when :known, :previous_known
+            return
+          when :superseded
+            raise LoginFailed.new("this identity was superseded on the site by a newer one", reason: :superseded,
+                                                                                             tif: session.last_response.tif, state: state)
+          else
+            reason = session.ip_check_failed? ? :ip_mismatch : :failed
+            raise LoginFailed.new(state.message || "query failed", reason: reason, tif: session.last_response.tif,
+                                                                   state: state)
+          end
+        end
+      end
+
+      def answer_ask(ctx)
+        ask = ctx.session.pending_ask
+        return unless ask
+
+        ctx.ask = ask
+        raise AskRequired, ask unless @ask_handler
+
+        btn = @ask_handler.call(ask).to_i
+        ctx.button = btn
+        ctx.session.set_button(btn)
+      end
+
+      def build_command(ctx, command, rescue_code)
+        session = ctx.session
+        state = session.state
+        case command
+        when :ident
+          if state.unknown? && @unknown_site == :refuse
+            raise LoginFailed.new("#{session.url.host} does not know this identity and unknown_site is :refuse",
+                                  reason: :unknown_site, tif: session.last_response.tif, state: state)
+          end
+          if state.disabled?
+            raise LoginFailed.new("SQRL login is disabled for this account on #{session.url.host}", reason: :disabled,
+                                                                                                    tif: session.last_response.tif, state: state)
+          end
+          session.ident
+        when :disable
+          session.disable
+        when :enable, :remove
+          iuk = state.previous_known? ? nil : unlock_key(rescue_code)
+          command == :enable ? session.enable(iuk) : session.remove(iuk)
+        else
+          raise ArgumentError, "unknown command #{command.inspect}"
+        end
+      end
+
+      def unlock_key(rescue_code)
+        return @identity.iuk if @identity.iuk?
+        return @identity.unlock_iuk!(rescue_code) if rescue_code
+
+        raise IdentityLocked,
+              "enable/remove need the Identity Unlock Key: pass rescue_code: or use an identity that has it"
+      end
+
+      def exchange(ctx, request)
+        response = @transport.post_form(request.url, request.body, { "Accept" => "text/plain" })
+        unless response.success?
+          raise TransportError.new("SQRL endpoint #{request.url} answered HTTP #{response.status}", url: request.url,
+                                                                                                    status: response.status)
+        end
+
+        parsed = ctx.session.feed(response.body.strip)
+        ctx.tifs << parsed.tif
+        ctx.transcript << { command: request.command, url: request.url, client_text: request.client_text,
+                            http_status: response.status, tif: parsed.tif.to_hex, response: parsed.params.to_h }
+        @logger&.debug { "[sqrl-client] #{request.command} -> tif=0x#{parsed.tif.to_hex} (#{ctx.session.state.kind})" }
+        parsed
+      end
+
+      def finish(ctx, command)
+        session = ctx.session
+        state = session.state
+        tif = session.last_response&.tif
+        authenticated = false
+        created = false
+        rekeyed = false
+        cps_url = nil
+
+        case command
+        when :ident, :enable
+          unless !tif.error? && tif.id_match? && !(command == :ident && tif.sqrl_disabled?)
+            raise LoginFailed.new("#{command} failed: #{state.message || state.kind}", reason: failure_reason(session),
+                                                                                       tif: tif, state: state)
+          end
+          authenticated = true
+          created = command == :ident && ctx.pre_state&.unknown?
+          rekeyed = ctx.pre_state&.previous_known? || false
+        when :disable
+          unless !tif.error? && tif.sqrl_disabled?
+            raise LoginFailed.new("disable failed: #{state.message || state.kind}", reason: failure_reason(session),
+                                                                                    tif: tif, state: state)
+          end
+        when :remove
+          if tif.error? || tif.id_match?
+            raise LoginFailed.new("remove failed: #{state.message || state.kind}", reason: failure_reason(session),
+                                                                                   tif: tif, state: state)
+          end
+        end
+
+        if command != :query
+          cps_url = session.cps_url
+          if authenticated
+            if cps_url
+              ctx.landing = @transport.get(cps_url) if @follow_cps
+            elsif @poll && ctx.found.status_url
+              ctx.status = poll_status(ctx)
+            end
+          end
+        end
+
+        LoginResult.new(command: command, sqrl_url: ctx.found.sqrl_url, state: state, tif: tif, tif_history: ctx.tifs,
+                        idk: session.idk_b64, cookies: @transport.respond_to?(:cookies) ? @transport.cookies : nil,
+                        transcript: ctx.transcript, created: created, rekeyed: rekeyed, authenticated: authenticated,
+                        cps_url: cps_url, landing: ctx.landing, status: ctx.status, ask: ctx.ask, button: ctx.button,
+                        cancel_url: session.cancel_url)
+      end
+
+      def failure_reason(session)
+        tif = session.last_response&.tif
+        return :unknown if tif.nil?
+        return :superseded if tif.identity_superseded?
+        return :disabled if tif.sqrl_disabled?
+        return :ip_mismatch if session.ip_check_failed?
+        return :client_failure if tif.client_failure?
+        return :not_supported if tif.function_not_supported?
+
+        :command_failed
+      end
+
+      # Poll the discovered status URL until it reports the login, following its +next+
+      # URL (which completes a cookie-based login) when it gives one.
+      def poll_status(ctx)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @poll_timeout
+        last = nil
+        loop do
+          response = @transport.get(ctx.found.status_url, { "Accept" => "application/json" })
+          last = response.json || {}
+          if last["authenticated"]
+            ctx.landing = @transport.get(URI.join(ctx.found.status_url, last["next"]).to_s) if last["next"]
+            return last
+          end
+          return last if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep @poll_interval
+        end
+      end
+    end
+  end
+end

data/lib/sqrl/client/capybara.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SQRL
+  module Client
+    # Drives a Capybara session through a SQRL login, the way a native client on the same
+    # machine would: the protocol runs out of band with an {Agent}, then the *browser*
+    # visits the server's CPS +url=+, so the browser's own session cookie is the one that
+    # gets logged in.
+    #
+    #   visit "/login"
+    #   SQRL::Client::Capybara.login(page, identity: SQRL::Client::Identity.ephemeral("bot"))
+    #   expect(page).to have_content("Welcome")
+    module Capybara
+      module_function
+
+      # @param page [Capybara::Session] showing a page with a SQRL login link
+      # @param identity [Identity]
+      # @param cps [Boolean] +true+: visit the CPS URL in the browser; +false+: perform
+      #   +ident+ only and wait for the page's own poller to navigate
+      # @param wait [Numeric] seconds to wait for the non-CPS redirect
+      # @param agent_opts [Hash] passed to {Agent#initialize}
+      # @return [LoginResult]
+      def login(page, identity:, cps: true, wait: 10, **agent_opts)
+        found = Discovery.find(page.html, base_url: page.current_url)
+        agent = Agent.new(identity: identity, cps: cps, follow_cps: false, poll: false, **agent_opts)
+        result = agent.login(found.sqrl_url)
+        if cps
+          raise LoginFailed.new("the server sent no CPS url=", reason: :no_cps, tif: result.tif) unless result.cps_url
+
+          page.visit(result.cps_url)
+        else
+          start_path = page.current_path
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + wait
+          sleep 0.1 while page.current_path == start_path && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        end
+        result
+      end
+
+      # Run +disable+/+enable+/+remove+ against the page's login link.
+      def command(page, command, identity:, rescue_code: nil, **agent_opts)
+        found = Discovery.find(page.html, base_url: page.current_url)
+        agent = Agent.new(identity: identity, cps: false, poll: false, **agent_opts)
+        case command
+        when :disable then agent.disable(found.sqrl_url)
+        when :enable then agent.enable(found.sqrl_url, rescue_code: rescue_code)
+        when :remove then agent.remove(found.sqrl_url, rescue_code: rescue_code)
+        else raise ArgumentError, "command must be :disable, :enable or :remove"
+        end
+      end
+    end
+  end
+end