devise-passkeys 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2447f73b6085c64f92155f7fbef7e0fec400c1d0850e267bd75d0c5f5d1c5131
-  data.tar.gz: 4574971ab7925b50c8513273c9dd077e09732a22952533c7a92ceabee7071115
+  metadata.gz: ad58f89b95e34fd2da78725ca88415708d0bcb9f461b3ced274065782dd6758d
+  data.tar.gz: cf5c43539eee37968339470855580544c2a366dd2a09231e55810203369b7116
 SHA512:
-  metadata.gz: a0be4cd6b62abe8589b238b09684abaed8a1434cc3377880111dbb521edea92a085fd4d108490bc0bafb0270d642bc1b1426d4141420fce7198aa14e3d7da47c
-  data.tar.gz: 93752f8ef25cb01502abc1420d6fda0861a43719ab38dfd843b5699ec6f51126668e91da6bc5fce681f94c153c3a64d192b19829657bbedd4945a4f9e68b62ca
+  metadata.gz: c59f446a7aaf5e93f9d1e11414f0cdb26c2273e39897d912eb1c63d8852cae8de793b975c9e29583b9c6edb34ba2a300dba9d428d6174411800ad2d1e76acbf5
+  data.tar.gz: 60d088c413ed62b9be3254dfc3c9d83a2582c67a382575cdbfabd441135fc7a60e5891d3ecc981a8e4fb9cc00a9be40fe9368372af62e3207ad19c66846d5f78

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -1,5 +1,43 @@
-## [Unreleased]
+## [0.2.0] - 2023-07-07
 
-## [0.1.0] - 2022-10-13
+### Bugfixes
+- Fixed bug with `Devise::Strategies::PasskeyReauthentication` clearing the CSRF token after reauthentication
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/45
+- Fixed bug where `RegistrationsControllerConcern` was using `:user` as the Strong Parameters key, rather than `resource_key`
+  - https://github.com/ruby-passkeys/devise-passkeys/commit/5ef8c83ffe57b3719ab574a01c710ee3ba7dcfb1
+- Rename `create_resource_and_passkey` => `create_passkey_for_resource`
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/37
+- `ReauthenticationControllerConcern` and `SessionsControllerConcern` raise `NoMethodError` if the `relying_party` has not been overridden
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/32
+
+### Refactoring
+
+- Refactor PasskeysControllerConcern to have clearer credential verify with `verify_credential_integrity`
+  -https://github.com/ruby-passkeys/devise-passkeys/pull/29/commits/f1400cb4b217c20b9e74fda3f55f74284e373d25
+- Refactor Controller concerns to not use `Warden::WebAuthn::StrategyHelpers`
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/29
+- Rename `Devise::Passkeys::Controllers::Concerns::PasskeyReauthentication` => `Devise::Passkeys::Controllers::Concerns::Reauthentication`
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/7/
+- Add `passkey:` keyword param to `after_passkey_authentication` callback
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/26
+- Removed unused `:maximum_passkeys_per_user` attribute
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/41
+
+### Etc.
+- Bump to warden-webauthn 0.2.1
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/29/commits/d825ffded91aa98801bdd5530442761aa60538f9
+- Use `Warden::WebAuthn::RackHelper.set_relying_party_in_request_env` to streamline setup
+  https://github.com/ruby-passkeys/devise-passkeys/pull/29/commits/7b7d50129ebe83b0a224d0ace0e4cff8ea407f4a
+- Bump `Devise` requirement to `>= 4.7.1`
+  - https://github.com/ruby-passkeys/devise-passkeys/pull/11
+- Documentation
+    - https://github.com/ruby-passkeys/devise-passkeys/pull/12
+    - https://github.com/ruby-passkeys/devise-passkeys/pull/44
+    - https://github.com/ruby-passkeys/devise-passkeys/pull/43
+    - https://github.com/ruby-passkeys/devise-passkeys/pull/39
+    - https://github.com/ruby-passkeys/devise-passkeys/pull/38
+
+
+## [0.1.0] - 2023-05-07
 
 - Initial release

data/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+## Installation
+
+After checking out the repo, run the following to install both Bundler and Appraisal dependencies:
+
+```sh
+bin/setup
+```
+
+# Run tests
+
+To run the test suite for all Appraisal variants, run:
+
+```sh
+bundle exec appraisal rake test
+```
+
+or
+
+```sh
+bin/test
+```
+
+## Writing Documentation
+
+Documentation is written using [YARD](http://yardoc.org/).
+
+You can start a YARD server to view the generated documentation (with automatic reloading) by running:
+
+```sh
+bin/yard
+```
+
+The documentation site will now be available at [http://localhost:8808](http://localhost:8808)
+
+## Interactive Console
+
+You can also run the following for an interactive prompt that will allow you to experiment:
+
+```sh
+bin/console
+```
+
+# Gem installation & cutting
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Gemfile

@@ -10,6 +10,8 @@ group :development, :test do
   gem "debug"
   gem "rake", "~> 13.0"
   gem "rubocop", "~> 1.21"
+  gem 'yard'
+  gem 'webrick'
 end
 
 group :test do

data/Gemfile.lock

@@ -1,19 +1,32 @@
 PATH
   remote: .
   specs:
-    devise-passkeys (0.1.0)
-      devise
-      warden-webauthn (>= 0.2.0)
+    devise-passkeys (0.2.0)
+      devise (>= 4.7.1)
+      warden-webauthn (>= 0.2.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.0.4.2)
-      activesupport (= 7.0.4.2)
-    activerecord (7.0.4.2)
-      activemodel (= 7.0.4.2)
-      activesupport (= 7.0.4.2)
-    activesupport (7.0.4.2)
+    actionpack (7.0.6)
+      actionview (= 7.0.6)
+      activesupport (= 7.0.6)
+      rack (~> 2.0, >= 2.2.4)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (7.0.6)
+      activesupport (= 7.0.6)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activemodel (7.0.6)
+      activesupport (= 7.0.6)
+    activerecord (7.0.6)
+      activemodel (= 7.0.6)
+      activesupport (= 7.0.6)
+    activesupport (7.0.6)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -25,16 +38,16 @@ GEM
       thor (>= 0.14.0)
     ast (2.4.2)
     awrence (1.2.1)
-    bcrypt (3.1.18)
-    bcrypt-ruby (3.1.5)
-      bcrypt (>= 3.1.3)
+    bcrypt (3.1.19)
     bindata (2.4.15)
     bson (4.15.0)
+    builder (3.2.4)
     cbor (0.5.9.6)
-    concurrent-ruby (1.2.0)
+    concurrent-ruby (1.2.2)
     cose (1.3.0)
       cbor (~> 0.5.9)
       openssl-signature_algorithm (~> 1.0)
+    crass (1.0.6)
     database_cleaner-active_record (2.1.0)
       activerecord (>= 5.a)
       database_cleaner-core (~> 2.0.0)
@@ -42,61 +55,95 @@ GEM
     database_cleaner-mongoid (2.0.1)
       database_cleaner-core (~> 2.0.0)
       mongoid
-    debug (1.7.1)
+    debug (1.8.0)
       irb (>= 1.5.0)
       reline (>= 0.3.1)
-    devise (1.5.4)
-      bcrypt-ruby (~> 3.0)
-      orm_adapter (~> 0.0.3)
-      warden (~> 1.1)
+    devise (4.9.2)
+      bcrypt (~> 3.0)
+      orm_adapter (~> 0.1)
+      railties (>= 4.1.0)
+      responders
+      warden (~> 1.2.3)
     docile (1.4.0)
-    i18n (1.12.0)
+    erubi (1.12.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     io-console (0.6.0)
-    irb (1.6.2)
+    irb (1.7.1)
       reline (>= 0.3.0)
     json (2.6.3)
-    jwt (2.7.0)
+    jwt (2.7.1)
+    language_server-protocol (3.17.0.3)
+    loofah (2.21.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
     m (1.6.1)
       method_source (>= 0.6.7)
       rake (>= 0.9.2.2)
     method_source (1.0.0)
-    minitest (5.17.0)
+    minitest (5.18.1)
     minitest-ci (3.4.0)
       minitest (>= 5.0.6)
-    mongo (2.18.2)
+    mongo (2.19.0)
       bson (>= 4.14.1, < 5.0.0)
-    mongoid (8.0.3)
+    mongoid (8.1.0)
       activemodel (>= 5.1, < 7.1, != 7.0.0)
+      concurrent-ruby (>= 1.0.5, < 2.0)
       mongo (>= 2.18.0, < 3.0.0)
       ruby2_keywords (~> 0.0.5)
+    nokogiri (1.15.3-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.15.3-x86_64-linux)
+      racc (~> 1.4)
     openssl (3.1.0)
     openssl-signature_algorithm (1.3.0)
       openssl (> 2.0)
-    orm_adapter (0.0.7)
-    parallel (1.22.1)
-    parser (3.2.1.0)
+    orm_adapter (0.5.0)
+    parallel (1.23.0)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
-    rack (3.0.4.1)
+      racc
+    racc (1.7.1)
+    rack (2.2.7)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rails-dom-testing (2.1.1)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.0)
+      loofah (~> 2.21)
+      nokogiri (~> 1.14)
+    railties (7.0.6)
+      actionpack (= 7.0.6)
+      activesupport (= 7.0.6)
+      method_source
+      rake (>= 12.2)
+      thor (~> 1.0)
+      zeitwerk (~> 2.5)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.7.0)
-    reline (0.3.2)
+    regexp_parser (2.8.1)
+    reline (0.3.5)
       io-console (~> 0.5)
+    responders (3.1.0)
+      actionpack (>= 5.2)
+      railties (>= 5.2)
     rexml (3.2.5)
-    rubocop (1.45.1)
+    rubocop (1.54.1)
       json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.2.2.3)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.24.1, < 2.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.26.0)
+    rubocop-ast (1.29.0)
       parser (>= 3.2.1.0)
-    ruby-progressbar (1.11.0)
+    ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
     safety_net_attestation (0.4.0)
       jwt (~> 2.0)
@@ -106,7 +153,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    thor (1.2.1)
+    thor (1.2.2)
     tpm-key_attestation (0.12.0)
       bindata (~> 2.4)
       openssl (> 2.0)
@@ -116,7 +163,7 @@ GEM
     unicode-display_width (2.4.2)
     warden (1.2.9)
       rack (>= 2.0.9)
-    warden-webauthn (0.2.0)
+    warden-webauthn (0.2.1)
       warden
       webauthn (>= 3)
     webauthn (3.0.0)
@@ -128,6 +175,9 @@ GEM
       openssl (>= 2.2)
       safety_net_attestation (~> 0.4.0)
       tpm-key_attestation (~> 0.12.0)
+    webrick (1.8.1)
+    yard (0.9.34)
+    zeitwerk (2.6.8)
 
 PLATFORMS
   arm64-darwin-21
@@ -146,6 +196,8 @@ DEPENDENCIES
   rake (~> 13.0)
   rubocop (~> 1.21)
   simplecov
+  webrick
+  yard
 
 BUNDLED WITH
-   2.3.7
+   2.4.12

data/README.md

@@ -19,7 +19,7 @@ $ bundle
 
 # Usage
 
-1. Add `:passkey_authenticatable` in your Devise-enabled model
+## Add `:passkey_authenticatable`
 
 ```ruby
 class User < ApplicationRecord
@@ -35,7 +35,7 @@ class User < ApplicationRecord
     self.find_by(id: passkey.user.id)
   end
 
-  def after_passkey_authentication
+  def after_passkey_authentication(passkey:)
   end
 end
 ```
@@ -47,7 +47,7 @@ The Devise-enabled model must have a `webauthn_id` field in the model; which is:
 
 This will allow you to explictly establish the relationship between a user & its passkeys (to help both your app & the user's authenticator with credential management)
 
-2. Generate the model that will store passkeys. The model name is not important, but the Devise-enabled model should have:
+## Generate the Model That Will Store Passkeys. Should Have:
 - A `has_many :passkeys` association
 - A `passkey_class` class method that returns the passkey class
 - A `find_for_passkey(passkey)` class method that finds the user for a given passkey
@@ -66,7 +66,7 @@ The following fields are required:
 
 It's recommended to add unique indexes on `external_id` and `public_key`
 
-3. Generate custom devise controllers & views for your Devise-enabled model
+## Generate Custom Devise Controllers & Views 
 
 [Since Devise does not have built-in passkeys support yet](https://github.com/heartcombo/devise/issues/5527), you'll need to customize both the controllers & the views
 
@@ -77,7 +77,7 @@ rails generate devise:views users
 
 If you're trying to keep your codebase small, these instructions only concern the `Users::SessionsController` & `Users::RegistrationsController`, so you can delete any other generated custom controllers if needed. You will likely need to modify the `views/users/shared/*` partials though, because they assume passwords are being used.
 
-4. Include the passkeys concerns into your controllers
+## Include the Passkeys Concerns in Your Controllers
 
 Rather than having base classes, `Devise::Passkeys` has a series of concerns that can be mixed into your controllers. This allows you to change behavior, and does not keep you stuck down a path that could be incompatible with your existing authentication setup.
 
@@ -96,10 +96,6 @@ class Users::SessionsController < Devise::SessionsController
   def relying_party
      WebAuthn::RelyingParty.new(...)
   end
-
-  def set_relying_party_in_request_env
-    request.env[relying_party_key] = relying_party
-  end
 end
 
 # frozen_string_literal: true
@@ -111,10 +107,6 @@ class Users::ReauthenticationController < DeviseController
   def relying_party
      WebAuthn::RelyingParty.new(...)
   end
-
-  def set_relying_party_in_request_env
-    request.env[relying_party_key] = relying_party
-  end
 end
 
 # frozen_string_literal: true
@@ -126,15 +118,11 @@ class Users::PasskeysController < DeviseController
   def relying_party
      WebAuthn::RelyingParty.new(...)
   end
-
-  def set_relying_party_in_request_env
-    request.env[relying_party_key] = relying_party
-  end
 end
 
 ```
 
-6. Add necessary routes
+## Add Routes
 
 Given the customization routes usually require, you'll need to hook up the routes yourself. Here's an example:
 
@@ -165,6 +153,22 @@ devise_scope :user do
 end
 ```
 
+## Reimplement the `:passkey_authenticatable` Module
+
+**Important**: You will need to reimplement the `:passkey_authenticatable` Devise module. This will override the module definition with your implementation specific definitions; pointing to the specific route, controller, etc.
+
+Here's an example from [devise-passkeys-template](https://github.com/ruby-passkeys/devise-passkeys-template/blob/main/app/models/user.rb#L18): 
+
+```ruby
+Devise.add_module :passkey_authenticatable,
+                  model: 'devise/passkeys/model',
+                  route: {session: [nil, :new, :create, :destroy] },
+                  controller: 'controller/sessions',
+                  strategy: true,
+                  no_input: true
+```
+
+# FAQs
 
 ## What about the Webauthn javascript? Mailers? Error handling?
 
@@ -176,13 +180,11 @@ Here's a template repo! https://github.com/ruby-passkeys/devise-passkeys-templat
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Please see [CONTRIBUTING.md](https://github.com/ruby-passkeys/devise-passkeys/blob/main/CONTRIBUTING.md) for guidance on how to help out!
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/devise-passkeys. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/devise-passkeys/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-passkeys/devise-passkeys. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/ruby-passkeys/devise-passkeys/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -190,7 +192,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Devise::Passkeys project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/devise-passkeys/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Devise::Passkeys project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ruby-passkeys/devise-passkeys/blob/main/CODE_OF_CONDUCT.md).
 
 
 ## Acknowledgements

data/THANKS.md

@@ -0,0 +1,9 @@
+# Thanks to everyone's who's contributed or helped out!
+
+## Contributors
+
+- [@heliocola](https://github.com/heliocola)
+- [@JanaganSaravanan](https://github.com/JanaganSaravanan)
+- [@johalloran01](https://github.com/johalloran01)
+- [@tcannonfodder](https://github.com/tcannonfodder)
+- [@Vagab](https://github.com/Vagab)

data/devise-passkeys.gemspec

@@ -32,8 +32,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "devise"
-  spec.add_dependency "warden-webauthn", ">= 0.2.0"
+  spec.add_dependency "devise", ">= 4.7.1"
+  spec.add_dependency "warden-webauthn", ">= 0.2.1"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/gemfiles/rails_6.gemfile

@@ -10,6 +10,8 @@ group :development, :test do
   gem "debug"
   gem "rake", "~> 13.0"
   gem "rubocop", "~> 1.21"
+  gem "yard"
+  gem "webrick"
 end
 
 group :test do

data/gemfiles/rails_7.gemfile

@@ -10,6 +10,8 @@ group :development, :test do
   gem "debug"
   gem "rake", "~> 13.0"
   gem "rubocop", "~> 1.21"
+  gem "yard"
+  gem "webrick"
 end
 
 group :test do

data/lib/devise/passkeys/controllers/concerns/reauthentication.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Devise
+  module Passkeys
+    module Controllers
+      module Concerns
+        # This concern is responsible for storing, retrieving, clearing, consuming,
+        # and validating the reauthentication token in the session.
+        #
+        # A reauthentication token is a one-time random value that is used to
+        # indicate that the user has successfully been reauthenticated. This can be
+        # used for scenarios such as:
+        #
+        # - Adding a new passkey
+        # - Deleting a passkey
+        # - Performing sensitive actions inside your application
+        #
+        # You can customize which reauthentication token you're using by changing
+        # the `passkey_reauthentication_token_key` method after including this concern
+        #
+        # @see Devise::Passkeys::Controllers::ReauthenticationControllerConcern
+        module Reauthentication
+          extend ActiveSupport::Concern
+
+          # This method is responsible for storing the reauthentication token
+          # in the session.
+          #
+          # The reauthentication token is securely generated using `Devise.friendly_token`
+          #
+          # @return [String] The reauthentication token
+          # @see passkey_reauthentication_token_key
+          def store_reauthentication_token_in_session
+            session[passkey_reauthentication_token_key] = Devise.friendly_token(50)
+          end
+
+          # This method is responsible for retrieving the reauthentication token
+          # from the session.
+          #
+          # @return [String] The reauthentication token
+          # @see passkey_reauthentication_token_key
+          # @see store_reauthentication_token_in_session
+          def stored_reauthentication_token
+            session[passkey_reauthentication_token_key]
+          end
+
+          # This method is responsible for clearing the reauthentication token from
+          # the session.
+          #
+          # @return [String] The reauthentication token
+          # @see passkey_reauthentication_token_key
+          def clear_reauthentication_token!
+            session.delete(passkey_reauthentication_token_key)
+          end
+
+          # This method is responsible for consuming (i.e. retrieving & clearing)
+          # the reauthentication token from the session.
+          #
+          # @return [String] The reauthentication token
+          # @see stored_reauthentication_token
+          # @see clear_reauthentication_token!
+          def consume_reauthentication_token!
+            value = stored_reauthentication_token
+            clear_reauthentication_token!
+            value
+          end
+
+          # This method is responsible for validating the given reauthentication token
+          # against the one currently in the session.
+          #
+          # **Note**: Whenever a reauthentication token is checked using `valid_reauthentication_token?`,
+          # It will be consumed. This means that a new token will need to be generated & stored
+          # (by reauthenticating the user) if there were any issues.
+          #
+          # @param [String] given_reauthentication_token token to compare store token against
+          # @return [Boolean] whether the `given_reauthentication_token` is the same as the
+          #         `stored_reauthentication_token`
+          # @see consume_reauthentication_token!
+          def valid_reauthentication_token?(given_reauthentication_token:)
+            Devise.secure_compare(consume_reauthentication_token!, given_reauthentication_token)
+          end
+
+          # This method is responsible for generating the key that will be used
+          # to store the reauthentication token in the session hash.
+          #
+          # @return [String] The key that will be used to access the reauthentication token in the session
+          def passkey_reauthentication_token_key
+            "#{resource_name}_current_reauthentication_token"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/devise/passkeys/controllers/concerns/reauthentication_challenge.rb

@@ -4,13 +4,39 @@ module Devise
   module Passkeys
     module Controllers
       module Concerns
+        # This concern is responsible for storing the reauthentication challenge in the session.
+        #
+        # A reauthentication challenge is a WebAuthn challenge exchange (i.e. authentication)
+        # to verify the user's identity and confirm they're able to perform a sensitive action
+        # by performing the entire authentication process.
+        #
+        # This can be used for scenarios such as:
+        #
+        # - Adding a new passkey
+        # - Deleting a passkey
+        # - Performing sensitive actions inside your application
+        #
+        # You can customize which reauthentication challenge you're using by changing
+        # the `passkey_reauthentication_challenge_session_key` method after including this concern
+        #
+        # @see Devise::Passkeys::Controllers::ReauthenticationControllerConcern
         module ReauthenticationChallenge
           extend ActiveSupport::Concern
 
+          # This method is responsible for generating the key that will be used to store the
+          # reauthentication challenge in the session hash.
+          #
+          # @return [String] The reauthentication challenge session key
           def passkey_reauthentication_challenge_session_key
             "#{resource_name}_current_reauthentication_challenge"
           end
 
+          # This method is responsible for storing the reauthentication challenge in the session.
+          #
+          # @param [WebAuthn::PublicKeyCredential::RequestOptions] options_for_authentication the options for authentication,
+          #         generated by `webauthn-ruby`
+          # @return [String] The reauthentication challenge
+          # @see Devise::Passkeys::Controllers::ReauthenticationControllerConcern#new_challenge
           def store_reauthentication_challenge_in_session(options_for_authentication:)
             session[passkey_reauthentication_challenge_session_key] = options_for_authentication.challenge
           end