feat: add a signed challenge store that keeps no server state

The server signs each challenge with secret_key_base and checks the signature when the credential returns it in clientDataJSON. API clients need no session and no shared cache. A signed challenge can be reused until it expires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: RenzoMinelli

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Add `Devise::Webauthn.challenge_store` to configure where WebAuthn challenges are kept between the options request and the verification request. It takes a symbol such as `:session`, or a store class. The default, `:session`, keeps them in the session as before. [#150](https://github.com/cedarcode/devise-webauthn/pull/150) [@RenzoMinelli]
 - Add the `:cache` challenge store, which keeps challenges in `Rails.cache` so API clients without a session can use passkeys. [#152](https://github.com/cedarcode/devise-webauthn/pull/152) [@RenzoMinelli]
+- Add the `:signed` challenge store, which signs each challenge instead of storing it. API clients can use passkeys without a session or a shared cache. [@RenzoMinelli]
 - Accept `public_key_credential` as a JSON object as well as a JSON string. [#152](https://github.com/cedarcode/devise-webauthn/pull/152) [@RenzoMinelli]
 
 ### Changed

README.md

@@ -137,15 +137,24 @@ Mobile apps and other API clients can use passkeys without a cookie session, for
 
 ### Server setup
 
-1. Keep challenges in a cache shared by all your servers (Redis, Memcached or Solid Cache), not in the session:
-   ```ruby
-   # config/initializers/devise_webauthn.rb
-   Devise::Webauthn.challenge_store = :cache
-   # Optional. Defaults to Rails.cache and 5 minutes.
-   Devise::Webauthn::ChallengeStores::Cache.cache = Rails.cache
-   Devise::Webauthn::ChallengeStores::Cache.expires_in = 5.minutes
-   ```
-   Each challenge can be used once. The options request and the sign-in request can reach different servers or processes, so they must share the cache. `ActiveSupport::Cache::MemoryStore` and `FileStore` are local to one process or host.
+1. Keep challenges outside the session. Choose one store:
+   - `:cache` keeps challenges in a cache shared by all your servers (Redis, Memcached or Solid Cache):
+     ```ruby
+     # config/initializers/devise_webauthn.rb
+     Devise::Webauthn.challenge_store = :cache
+     # Optional. Defaults to Rails.cache and 5 minutes.
+     Devise::Webauthn::ChallengeStores::Cache.cache = Rails.cache
+     Devise::Webauthn::ChallengeStores::Cache.expires_in = 5.minutes
+     ```
+     Each challenge can be used once. The options request and the sign-in request can reach different servers or processes, so they must share the cache. `ActiveSupport::Cache::MemoryStore` and `FileStore` are local to one process or host.
+   - `:signed` stores nothing. The server signs each challenge with `secret_key_base`, and checks the signature when the credential comes back:
+     ```ruby
+     # config/initializers/devise_webauthn.rb
+     Devise::Webauthn.challenge_store = :signed
+     # Optional. Defaults to 5 minutes.
+     Devise::Webauthn::ChallengeStores::Signed.expires_in = 5.minutes
+     ```
+     A signed challenge can be used more than once until it expires, like a challenge in a cookie session. Keep `expires_in` short.
 2. Stop Devise from writing the user to the session. Passkey sign-in follows the `:params_auth` setting:
    ```ruby
    # config/initializers/devise.rb

lib/devise/webauthn.rb

@@ -6,6 +6,7 @@
 require_relative "webauthn/version"
 require_relative "webauthn/challenge_stores/credential_challenge"
 require_relative "webauthn/challenge_stores/session"
+require_relative "webauthn/challenge_stores/signed"
 require_relative "webauthn/challenge_stores/cache"
 require_relative "webauthn/challenge_store_access"
 require_relative "webauthn/public_key_credential_param"

lib/devise/webauthn/challenge_stores/signed.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Devise
+  module Webauthn
+    module ChallengeStores
+      class Signed
+        include CredentialChallenge
+
+        cattr_accessor :expires_in, default: 5.minutes
+
+        def initialize(request)
+          @request = request
+        end
+
+        # The client signs the returned challenge, so it comes back in clientDataJSON with no server state.
+        def write(purpose, challenge)
+          encoder.encode(verifier.generate(challenge, purpose: purpose, expires_in: expires_in))
+        end
+
+        def pending?(purpose)
+          consume(purpose).present?
+        end
+
+        def consume(purpose)
+          challenge = challenge_from_credential
+          challenge if challenge && verifier.verified(encoder.decode(challenge), purpose: purpose)
+        rescue ArgumentError, TypeError, EncodingError
+          nil
+        end
+
+        private
+
+        def verifier
+          Rails.application.message_verifier(:devise_webauthn_challenge)
+        end
+      end
+    end
+  end
+end

lib/generators/devise/webauthn/install/templates/webauthn.rb

@@ -36,5 +36,5 @@
   # config.algorithms << "ES384"
 end
 
-# Where challenges are kept between requests: `:session` (default), `:cache` or a store class.
+# Where challenges are kept between requests: `:session` (default), `:cache`, `:signed` or a store class.
 # Devise::Webauthn.challenge_store = :session

spec/devise/webauthn/challenge_stores/signed_spec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "webauthn/fake_client"
+
+RSpec.describe Devise::Webauthn::ChallengeStores::Signed do
+  include ActiveSupport::Testing::TimeHelpers
+
+  let(:client) { WebAuthn::FakeClient.new(WebAuthn.configuration.allowed_origins.first) }
+  let(:issued_challenge) { store_for(nil).write(:passkey_authentication, WebAuthn::Credential.options_for_get.challenge) }
+
+  def store_for(credential)
+    described_class.new(instance_double(ActionDispatch::Request, params: { public_key_credential: credential }))
+  end
+
+  def store_signing(challenge)
+    client.create(challenge: WebAuthn::Credential.options_for_get.challenge)
+    store_for(client.get(challenge: challenge))
+  end
+
+  it "accepts the challenge it issued when the credential signs it" do
+    store = store_signing(issued_challenge)
+
+    expect(store.pending?(:passkey_authentication)).to be(true)
+    expect(store.consume(:passkey_authentication)).to eq(issued_challenge)
+  end
+
+  it "rejects a challenge it did not issue" do
+    store = store_signing(WebAuthn::Credential.options_for_get.challenge)
+
+    expect(store.consume(:passkey_authentication)).to be_nil
+  end
+
+  it "rejects a challenge issued for another purpose" do
+    store = store_signing(issued_challenge)
+
+    expect(store.consume(:two_factor_authentication)).to be_nil
+  end
+
+  it "expires challenges" do
+    store = store_signing(issued_challenge)
+
+    travel_to(described_class.expires_in.from_now + 1.second) do
+      expect(store.consume(:passkey_authentication)).to be_nil
+    end
+  end
+
+  it "accepts a challenge more than once until it expires, because it keeps no state" do
+    store = store_signing(issued_challenge)
+
+    expect(store.consume(:passkey_authentication)).to eq(issued_challenge)
+    expect(store.consume(:passkey_authentication)).to eq(issued_challenge)
+  end
+
+  it "ignores malformed credentials" do
+    [nil, "{}", {}, { "response" => "x" }, { "response" => { "clientDataJSON" => "%%%" } }].each do |malformed|
+      expect(store_for(malformed).pending?(:passkey_authentication)).to be(false)
+    end
+  end
+end

spec/requests/devise/api_client_spec.rb

@@ -82,4 +82,33 @@ def request_challenge
       expect(response).to have_http_status(:unauthorized)
     end
   end
+
+  describe "passkey sign-in with the signed challenge store" do
+    let!(:passkey) { create_credential_for(user, :first_factor) }
+
+    before { Devise::Webauthn.challenge_store = :signed }
+
+    def passkey_assertion(challenge)
+      client.get(challenge: challenge, allow_credentials: [passkey.external_id], user_verified: true,
+                 user_handle: WebAuthn.configuration.encoder.decode(user.webauthn_id))
+    end
+
+    it "signs in with a challenge the server signed, without keeping any state" do
+      api_post account_passkey_authentication_options_path
+      challenge = response.parsed_body["challenge"]
+
+      api_post account_session_path, public_key_credential: passkey_assertion(challenge)
+
+      expect(response).to have_http_status(:created)
+      expect(response.parsed_body["email"]).to eq(user.email)
+    end
+
+    it "rejects a challenge the server never signed" do
+      challenge = WebAuthn.configuration.encoder.encode(SecureRandom.random_bytes(32))
+
+      api_post account_session_path, public_key_credential: passkey_assertion(challenge)
+
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
 end