passkeys-rails 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 666859b1227428b580202f3c2f9822cf937db0ecaf26381dddefd45b6d8e9b3e
-  data.tar.gz: 7cbce30a6f2efb7eb15aa4a747156da1e355c795ca346fdc8af2ecad6af837d6
+  metadata.gz: a137b9b4f2ab7aac24fef0747ff112588215d496034f0542983df3790bc32de7
+  data.tar.gz: 412185131a984a883a11af7fae1bbbb69806819a978871a08e0929921c766fe4
 SHA512:
-  metadata.gz: d0bff5cc099209252fa1853c9e75e8f23edce8de4ac910f2e958e9279ec81a4452074fa6611d42424e4809fc010a129072e7d719e9de8b4e0a3e40e7619ad7f9
-  data.tar.gz: 98e62cd971c37781aecadc0dbe09b1c32d6aa2e0837f24c816971c660d8d00c19c738a339a43f021a4a27e843b79b04b3128f65f7ff21b971289fa232dd0df75
+  metadata.gz: bdf2974d31cb561bbeabaf599a29d99bb9cda2e4050cff913cbe5104a747c4eba2eb11a53936fcef013861ede39051208a2edbc3062a6b25a34476678388eba9
+  data.tar.gz: 149c795d0b56a7569170160426b466ff42abc75bcb2f46fc5adae3b35ad3eb9d6d465ce05f0834cbbfaf3bc30944d809b776c1112913c0e490175c316784e859

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+### 0.3.1
+
+* Fixed a bug in reading session/cookie variables
+* Added webauthn configuration parameters to this gem's configuration
+* Moved configuration to its own class
+* Added more info to the README
+
+### 0.3.0
+
+* Added debug_register endpoint.
+* Fixed authenticatable_params for register enpoint.
+* Added notifications to certain controller actions.
+* Improved spec error helper.
+
+### 0.2.1
+
+Added ability to pass either the auth token string or a request with one in the header to authenticate methods.
+
 ### 0.2.0
 
 * Added passkeys/debug_login functionality.

data/README.md

@@ -1,42 +1,60 @@
+# PasskeysRails - easy to integrate back end for implementing mobile passkeys
+
 [![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=0.2.1)](https://badge.fury.io/rb/passkeys-rails)
 [![Build Status](https://app.travis-ci.com/alliedcode/passkeys-rails.svg?branch=main)](https://travis-ci.org/alliedcode/passkeys-rails)
 [![codecov](https://codecov.io/gh/alliedcode/passkeys-rails/branch/main/graph/badge.svg?token=UHSNJDUL21)](https://codecov.io/gh/alliedcode/passkeys-rails)
 
-# PasskeysRails
+<p align="center" >
+Created by <b>Troy Anderson, Allied Code</b> - <a href="https://alliedcode.com">alliedcode.com</a>
+</p>
 
-Devise is awesome, but we don't need all that UI/UX for PassKeys, especially for an API back end.
+PasskeysRails is a gem you can add to a Rails app to enable passskey registration and authorization from mobile front ends.  PasskeysRails leverages webauthn for the cryptographic work, and presents a simple API interface for passkey registration, authentication, and testing.
 
 The purpose of this gem is to make it easy to provide a rails back end API that supports PassKey authentication.  It uses the [`webauthn`](https://github.com/w3c/webauthn) gem to do the cryptographic work and presents a simple API interface for passkey registration and authentication.
 
 The target use case for this gem is a mobile application that uses a rails based API service to manage resources.  The goal is to make it simple to register and authenticate users using passkeys from mobile applications in a rails API service.
 
+What about [devise](https://github.com/heartcombo/devise)?  Devise is awesome, but we don't need all that UI/UX for PassKeys, especially for an API back end.
+
+## Documentation
+* [Usage](#usage)
+* [Installation](#installation)
+* [Rails Integration - Standard](#rails-Integration-standard)
+* [Rails Integration - Grape](#rails-Integration-grape)
+* [Notifications](#notifications)
+* [Failure Codes](#failure-codes)
+* [Testing](#testing)
+* [Mobile App Integration](#mobile-application-integration)
+* [Reference/Example Mobile Applications](#referenceexample-mobile-applications)
 
 ## Usage
 
-**PasskeysRails** maintains an `Agent` model and related `Passkeys`.  If you have a user model, add `include PasskeysRails::Authenticatable` to your model and include the name of that class (e.g. `"User"`) in the `authenticatable_class` param when calling the register API or set the `PasskeysRails.default_class` to the name of that class.
+**PasskeysRails** maintains a `PasskeysRails::Agent` model and related `PasskeysRails::Passkeys`.  In rails apps that maintain their own "user" model, add `include PasskeysRails::Authenticatable` to that model and include the name of that class (e.g. `"User"`) in the `authenticatable_class` param when calling the register API or set the `PasskeysRails.default_class` to the name of that class.
+
+In mobile apps, leverage the platform specific Passkeys APIs for ***registration*** and ***authentication***, and call the **PasskeysRails** API endpoints to complete the ceremony.  **PasskeysRails** provides endpoints to support ***registration***, ***authentication***, ***token refresh***, and ***debugging***.
 
 ### Optionally providing a **"user"** model during registration
 
-**PasskeysRails** does not require that you supply your own model, but it's often useful to do so.  For example, if you have a User model that you would like to have created at registration, you can supply the model name in the `finishRegistration` API call.
+**PasskeysRails** does not require any application specific models, but it's often useful to have one.  For example, a User model can be created at registration.  **PasskeysRails** provides two mechanisms to support this.  Either provide the name of the model in the `authenticatable_class` param when calling the `finishRegistration` endpoint, or set a `default_class` in `config/initializers/passkeys_rails.rb`.
 
-**PasskeysRails** supports multiple `"user"` models.  Whatever model name you supply will be created during a successful the `finishRegiration` API call. When created, it will be provided an opportunity to do any initialization at that time.
+**PasskeysRails** supports multiple different application specific models.  Whatever model name supplied when calling the `finishRegistration` endpoint will be created during a successful the `finishRegiration` process. When created, it will be provided an opportunity to do any initialization at that time.
 
-There are two **PasskeysRails** configuration options related to this: `default_class` and `class_whitelist` - see below.
+There are two **PasskeysRails** configuration options related to this: `default_class` and `class_whitelist`:
 
 #### `default_class`
 
-Configure `default_class` in `passkeys_rails.rb`.  Its value will be used during registration if none is provided in the API call.  The default value is `"User"`.  Since the `default_class` is just a default, it can be overridden in the `finishRegiration` API call to use a different model.  If no model is to be used by default, set it to nil.
+Configure `default_class` in `config/initializers/passkeys_rails.rb`.  Its value will be used during registration if none is provided in the API call.  The default value is `"User"`.  Since the `default_class` is just a default, it can be overridden in the `finishRegiration` API call to use a different model.  If no model is to be used by default, set it to nil.
 
 #### `class_whitelist`
 
-Configure `class_whitelist` in `passkeys_rails.rb`.  The default value is `nil`.  When `nil`, no whitelist will be applied. If it is non-nil, it should be an array of class names that are allowed during registration.  Supply an empty array to prevent **PasskeysRails** from attempting to create anything other than its own `PasskeysRails::Agent` during registration.
+Configure `class_whitelist` in `config/initializers/passkeys_rails.rb`.  The default value is `nil`.  When `nil`, no whitelist will be applied. If it is non-nil, it should be an array of class names that are allowed during registration.  Supply an empty array to prevent **PasskeysRails** from attempting to create anything other than its own `PasskeysRails::Agent` during registration.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "passkeys_rails"
+gem "passkeys-rails"
 ```
 
 And then execute:
@@ -56,31 +74,34 @@ Finally, execute:
 $ rails generate passkeys_rails:install
 ```
 
-This will add the `passkeys_rails.rb` configuration file, passkeys routes, and a couple of database migrations to your project.
+This will add the `config/initializers/passkeys_rails.rb` configuration file, passkeys routes, and a couple of database migrations to your project.
 
-### Adding to an standard rails project
 
-1. Add `before_action :authenticate_passkey!`
+<a id="rails-Integration-standard"></a>
+## Rails Integration <p><small>Adding to a standard rails project</small></p>
 
- To prevent access to controller actions, add `before_action :authenticate_passkey!`.  If an action is attempted without an authenticated entity, an error will be rendered in JSON with an :unauthorized result code.
+- ### Add `before_action :authenticate_passkey!`
 
-1. Use `current_agent` and `current_agent.authenticatable`
+To prevent access to controller actions, add `before_action :authenticate_passkey!`.  If an action is attempted without an authenticated entity, an error will be rendered in JSON with an :unauthorized result code.
 
- To access the currently authenticated entity, use `current_agent`.  If you associated the registration of the agent with one of your own models, use `current_agent.authenticatable`.  For example, if you associated the `User` class with the registration, `current_agent.authenticatable` will be a User object.
+- ### Use `current_agent` and `current_agent.authenticatable`
+
+To access the currently authenticated entity, use `current_agent`.  If you associated the registration of the agent with one of your own models, use `current_agent.authenticatable`.  For example, if you associated the `User` class with the registration, `current_agent.authenticatable` will be a User object.
 
-1. Add `include PasskeysRails::Authenticatable` to model class(es)
+- ### Add `include PasskeysRails::Authenticatable` to model class(es)
 
  If you have one or more classes that you want to use with authentication - e.g. a User class and an AdminUser class - add `include PasskeysRails::Authenticatable` to each of those classes.  That adds a `registered?` method that you can call on your model to determine if they are registerd with your service, and a `registering_with(params)` method that you can override to initialize attributes of your model when it is created during registration. `params` is a hash with params passed to the API when registering.  When called, your object has been built, but not yet saved.  Upon return, **PasskeysRails** will attempt to save your object before finishing registration.  If it is not valid, the registration will fail as well, returning the error error details to the caller.
 
-### Adding to a Grape API rails project
+<a id="rails-Integration-grape"></a>
+## Rails Integration - <p><small>Adding to a Grape API rails project</small></p>
 
-1. Call `PasskeysRails.authenticate(request)` to authenticate the request.
+- ### Call `PasskeysRails.authenticate(request)` to authenticate the request.
 
  Call `PasskeysRails.authenticate(request)` to get an object back that responds to `.success?` and `.failure?` as well as `.agent`, `.code`, and `.message`.
 
  Alternatively, call `PasskeysRails.authenticate!(request)` from a helper in your base class.  It will raise a `PasskeysRails.Error` exception if the caller isn't authenticated.  You can catch the exception and render an appropriate error.  The exception contains the error code and message.
 
-1. Consider adding the following helpers to your base API class:
+- ### Consider adding the following helpers to your base API class:
 
 ```ruby
   helpers do
@@ -109,13 +130,49 @@ This will add the `passkeys_rails.rb` configuration file, passkeys routes, and a
 
  To prevent access to various endpoints, add `before_action :authenticate_passkey!` or call `authenticate_passkey!` from any method that requires authentication.  If an action is attempted without an authenticated entity, an error will be rendered in JSON with an :unauthorized result code.
 
-1. Use `current_agent` and `current_agent.authenticatable`
+- ### Use `current_agent` and `current_agent.authenticatable`
 
  To access the currently authenticated entity, use `current_agent`.  If you associated the registration of the agent with one of your own models, use `current_agent.authenticatable`.  For example, if you associated the `User` class with the registration, `current_agent.authenticatable` will be a User object.
 
-### Authentication Failure
+## Notifications
+
+Certain actions trigger notifications that can be subscribed.  See `subscribe` in `config/initializers/passkeys_rails.rb`.
+
+These are completely optional.  **PasskeysRails** will manage all the credentials and keys without these being implemented.  They are useful for taking application specific actions like logging based on the authentication related events.
+
+### Events
+
+- `:did_register ` - a new agent has registered
+
+- `:did_authenticate` - an agent has been authenticated
+
+- `:did_refresh` - an agent's auth token has been refreshed
+
+A convenient place to set these up in is in `config/initializers/passkeys_rails.rb`
+
+```ruby
+PasskeysRails.config do |c|
+  c.subscribe(:did_register) do |event, agent, request|
+    # do something with the agent and/or request
+  end
+
+  c.subscribe(:did_authenticate) do |event, agent, request|
+    # do something with the agent and/or request
+  end
+end
+```
 
-1. In the event of authentication failure, PasskeysRails returns an error code and message.
+Subscriptions can also be done elsewhere as subscribe is a PasskeysRails class method.
+
+```ruby
+PasskeysRails.subscribe(:did_register) do |event, agent, request|
+  # do something with the agent and/or request
+end
+```
+
+## Failure Codes
+
+1. In the event of authentication failure, **PasskeysRails** API endpoints render an error code and message.
 
 1. In a standard rails controller, the error code and message are rendered in JSON if `before_action :authenticate_passkey!` fails.
 
@@ -133,12 +190,10 @@ This will add the `passkeys_rails.rb` configuration file, passkeys routes, and a
 
  In the future, the intention is to have the `.code` value stay consistent even if the `.message` changes.  This also allows you to localize the messages as need using the code.
 
-### Test Helpers
+## Testing
 
 PasskeysRails includes some test helpers for integration tests.  In order to use them, you need to include the module in your test cases/specs.
 
-### Integration tests
-
 Integration test helpers are available by including the `PasskeysRails::IntegrationHelpers` module.
 
 ```ruby
@@ -175,20 +230,38 @@ RSpec.describe 'Posts', type: :request do
 end
 ```
 
-### Mobile Application Integration
+## Mobile Application Integration
+
+### Prerequisites
+
+For iOS, you need to associate your app with your server.  This amounts to setting up a special file on your server that defines the association.  See [setup your apple-app-site-association](#Ensure-`.well-known/apple-app-site-association`-is-in-place)
 
-There are n groups of API endpoints that your mobile application may consume.
+
+### Mobile API Endpoints
+
+There are 3 groups of API endpoints that your mobile application may consume.
 
 1. Unauthenticated (public) endpoints
 1. Authenticated (private) endpoints
 1. Passey endpoints (for supporting authentication)
 
-**Unauthenticated endpoints** can be consumed without and authentication.
+**Unauthenticated endpoints** can be consumed without any authentication.
 
 **Authenticated endpoints** are protected by `authenticate_passkey!` or `PasskeysRails.authenticate!(request)`.  Those methods check for and validate the `X-Auth` header, which must be set to the auth token returned in the `AuthResponse`, described below.
 
 **Passkey endpoints** are supplied by this gem and allow you to register a user, authenticate (login) a user, and refresh the token.  This section describes these endpoints.
 
+This gem supports the Passkey endpoints.
+
+### Endpoints
+
+* [POST /passkeys/challenge](post-passkeys-challenge)
+* [POST /passkeys/register](post-passkeys-register)
+* [POST /passkeys/authenticate](post-passkeys-authenticate)
+* [POST /passkeys/refresh](post-passkeys-refresh)
+* [POST /passkeys/debug_register](post-passkeys-debug-register)
+* [POST /passkeys/debug_login](post-passkeys-debug-login)
+
 All Passkey endpoints accept and respond with JSON.
 
 On **success**, they will respond with a 200 or 201 response code and relevant JSON.
@@ -214,7 +287,7 @@ Some endpoints return an `AuthResponse`, which has this JSON structure:
 }
 ```
 
-#### POST /passkeys/challenge
+### POST /passkeys/challenge
 
 Submit this to begin registration or authentication.
 
@@ -225,7 +298,7 @@ If the username is already in use, or anything else goes wrong, an error with co
 Omit the `username` when authenticating (logging in).
 The JSON response will be the `options_for_get` from webauthn.
 
-#### POST /passkeys/register
+### POST /passkeys/register
 
 After calling the `challenge` endpoint with a `username`, and handling its response, finish registering by calling this endpoint.
 
@@ -256,16 +329,16 @@ On **success**, the response is an `AuthResponse`.
 
 Possible **failure codes** (using the `ErrorResponse` structure) are:
 
-- webauthn_error - something is wrong with the credential
-- error - something else went wrong during credentail validation - see the `message` in the `ErrorResponse`
-- passkey_error - unable to persiste the passkey
-- invalid_authenticatable_class - the supplied authenticatable class can't be created/found (check spelling & capitalization)
-- invalid_class_whitelist - the whitelist in the passkeys_rails.rb configuration is invalid - be sure it's nil or an array
-- invalid_authenticatable_class - the supplied authenticatable class is not allowed - maybe it's not in the whitelist
-- record_invalid - the object of the supplied authenticatable class cannot be saved due to validation errors
-- agent_not_found - the agent referenced in the credential cannot be found in the database
+- `webauthn_error` - something is wrong with the credential
+- `error` - something else went wrong during credentail validation - see the `message` in the `ErrorResponse`
+- `passkey_error` - unable to persist the passkey
+- `invalid_authenticatable_class` - the supplied authenticatable class can't be created/found (check spelling & capitalization)
+- `invalid_class_whitelist` - the whitelist in the passkeys_rails.rb configuration is invalid - be sure it's nil or an array
+- `invalid_authenticatable_class` - the supplied authenticatable class is not allowed - maybe it's not in the whitelist
+- `record_invalid` - the object of the supplied authenticatable class cannot be saved due to validation errors
+- `agent_not_found` - the agent referenced in the credential cannot be found in the database
 
-#### POST /passkeys/authenticate
+### POST /passkeys/authenticate
 
 After calling the `challenge` endpoint without a `username`, and handling its response, finish authenticating by calling this endpoint.
 
@@ -290,12 +363,12 @@ On **success**, the response is an `AuthResponse`.
 
 Possible **failure codes** (using the `ErrorResponse` structure) are:
 
-- webauthn_error - something is wrong with the credential
-- passkey_not_found - the passkey referenced in the credential cannot be found in the database
+- `webauthn_error` - something is wrong with the credential
+- `passkey_not_found` - the passkey referenced in the credential cannot be found in the database
 
-#### POST /passkeys/refresh
+### POST /passkeys/refresh
 
-The token will expire after some time (configurable in passkeys_rails.rb).  Before that happens, refresh it using this API.  Once it's expired, to get a new token, use the /authentication API.
+The token will expire after some time (configurable in `config/initializers/passkeys_rails.rb`).  Before that happens, refresh it using this API.  Once it expires, to get a new token, use the `/authentication` API.
 
 Supply the following JSON structure:
 
@@ -310,28 +383,28 @@ On **success**, the response is an `AuthResponse` with a new, refreshed token.
 
 Possible **failure codes** (using the `ErrorResponse` structure) are:
 
-- invalid_token - the token data is invalid
-- expired_token - the token is expired
-- token_error - some other error ocurred when decoding the token
+- `invalid_token` - the token data is invalid
+- `expired_token` - the token is expired
+- `token_error` - some other error ocurred when decoding the token
 
-#### POST /passkeys/debug_login
+### POST /passkeys/debug_register
 
-As it may not be possible to acess Passkey functionality in mobile simulators, this endpoint may be called to login (authenticate) a username while bypassing the normal challenge/response sequence.
+As it may not be possible to acess Passkey functionality in mobile simulators, this endpoint may be called to register a username while bypassing the normal challenge/response sequence.
 
-This endpoint only responds if DEBUG_LOGIN_REGEX is set in the server environment.  It is very insecure to set this variable in a production environment as it bypasses all Passkey checks.  It is only intended to be used during mobile application development.
+This endpoint only responds if DEBUG_LOGIN_REGEX is set in the server environment.  It is **very insecure to set this variable in a production environment** as it bypasses all Passkey checks.  It is only intended to be used during mobile application development.
 
 To use this endpoint:
 
-1. Manually create one or more PasskeysRails::Agent records in the database.  A unique username is required for each.
-
 1. Set DEBUG_LOGIN_REGEX to a regex that matches any username you want to use during development - for example `^test(-\d+)?$` will match `test`, `test-1`, `test-123`, etc.
 
-1. In the mobile application, call this endpoint in stead of the /passkeys/challenge and /passkeys/authenticate.  The response is identicial to that of /passkeys/authenticate.
+1. In the mobile application, call this endpoint in stead of the /passkeys/challenge and /passkeys/register.  The response is identicial to that of /passkeys/register.
 
-1. Use the response as if it was from /passkeys/authenticate.
+1. Use the response as if it was from /passkeys/register.
 
 If you supply a username that doesn't match the DEBUG_LOGIN_REGEX, the endpoint will respond with an error.
 
+Supply the following JSON structure:
+
 ```JSON
 # POST body
 {
@@ -342,71 +415,62 @@ On **success**, the response is an `AuthResponse`.
 
 Possible **failure codes** (using the `ErrorResponse` structure) are:
 
-- not_allowed - Invalid username (the username doesn't match the regex)
-- agent_not_found - No agent found with that username
-
-## Reference/Example Mobile Applications
-
-**TODO**: Point to the soon-to-be-created reference mobile applications for how to use **passkeys-rails** for passkey authentication.
-
-## Contributing
+- `not_allowed` - Invalid username (the username doesn't match the regex)
+- `invalid_authenticatable_class` - the supplied authenticatable class can't be created/found (check spelling & capitalization)
+- `invalid_class_whitelist` - the whitelist in the passkeys_rails.rb configuration is invalid - be sure it's nil or an array
+- `invalid_authenticatable_class` - the supplied authenticatable class is not allowed - maybe it's not in the whitelist
+- `record_invalid` - the object of the supplied authenticatable class cannot be saved due to validation errors
 
-### Contributing Guidelines
-
-Thank you for considering contributing to PasskeysRails! We welcome your help to improve and enhance this project. Whether it's a bug fix, documentation update, or a new feature, your contributions are valuable to the community.
+### POST /passkeys/debug_login
 
-To ensure a smooth collaboration, please follow the guidelines below when submitting your contributions:
-
-#### Code of Conduct
-
-Please note that this project follows the [Code of Conduct](https://github.com/alliedcode/passkeys-rails/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. If you encounter any behavior that violates the code, please report it to the project maintainers.
-
-#### How to Contribute
-
-1. Fork the repository on GitHub.
-
-2. Create a new branch for your contribution. Use a descriptive name that reflects the purpose of your changes.
-
-3. Make your changes and commit them with clear and concise messages. Remember to follow the project's coding style and guidelines.
+As it may not be possible to acess Passkey functionality in mobile simulators, this endpoint may be called to login (authenticate) a username while bypassing the normal challenge/response sequence.
 
-4. Before submitting a pull request, ensure that your changes pass all existing tests and add relevant tests if applicable.
+This endpoint only responds if DEBUG_LOGIN_REGEX is set in the server environment.  It is **very insecure to set this variable in a production environment** as it bypasses all Passkey checks.  It is only intended to be used during mobile application development.
 
-5. Update the documentation if your changes introduce new features, modify existing behavior, or require user instructions.
+To use this endpoint:
 
-6. Squash your commits into a single logical commit if needed. Keep your commit history clean and focused.
+1. Manually create one or more PasskeysRails::Agent records in the database.  A unique username is required for each.
 
-7. Submit a pull request against the `main` branch of the original repository.
+1. Set DEBUG_LOGIN_REGEX to a regex that matches any username you want to use during development - for example `^test(-\d+)?$` will match `test`, `test-1`, `test-123`, etc.
 
-8. Add a comment at the top of the CHANGELOG.md describing the change.
+1. In the mobile application, call this endpoint in stead of the /passkeys/challenge and /passkeys/authenticate.  The response is identicial to that of /passkeys/authenticate.
 
-#### Pull Request Guidelines
+1. Use the response as if it was from /passkeys/authenticate.
 
-When submitting a pull request, please include the following details:
+If you supply a username that doesn't match the DEBUG_LOGIN_REGEX, the endpoint will respond with an error.
 
-- A clear description of the changes you made and the problem it solves.
+Supply the following JSON structure:
 
-- Any relevant issue numbers that your pull request addresses or fixes.
+```JSON
+# POST body
+{
+  "username": String
+}
+```
+On **success**, the response is an `AuthResponse`.
 
-- The steps to test your changes, so the project maintainers can verify them.
+Possible **failure codes** (using the `ErrorResponse` structure) are:
 
-- Ensure that your pull request title and description are descriptive and informative.
+- `not_allowed` - Invalid username (the username doesn't match the regex)
+- `agent_not_found` - No agent found with that username
 
-#### Code Review Process
+## Reference/Example Mobile Applications
 
-All pull requests will undergo a code review process by the project maintainers. We appreciate your patience during this review process. Constructive feedback may be provided, and further changes might be requested.
+There is a sample iOS app that integrates with **passkeys-rails** based server implementations.  It's a great place to get a quick start on implementing passkyes in your iOS, iPadOS or MacOS apps.
 
-#### Contributor License Agreement
+Check out the [PasskeysRailsDemo](https://github.com/alliedcode/PasskeysRailsDemo) app.
 
-By submitting a pull request, you acknowledge that your contributions will be licensed under the project's [MIT License](https://github.com/alliedcode/passkeys-rails/blob/main/MIT-LICENSE).
+## Contributing
 
-#### Reporting Issues
+### Contribution Guidelines
 
-If you encounter any bugs, problems, or have suggestions for improvement, please create an issue on the GitHub repository. Provide clear and detailed information about the issue to help us address it efficiently.
+Thank you for considering contributing to PasskeysRails! We welcome your help to improve and enhance this project. Whether it's a bug fix, documentation update, or a new feature, your contributions are valuable to the community.
 
-#### Thank You
+To ensure a smooth collaboration, please follow the [Contribution Guidelines](https://github.com/alliedcode/passkeys-rails/blob/main/CONTRIBUTION_GUIDELINES.md) when submitting your contributions.
 
-Your contributions are valuable, and we sincerely appreciate your efforts to improve PasskeysRails. Together, we can build a better software ecosystem for the community. Thank you for your support and happy contributing!
+### Code of Conduct
 
+Please note that this project follows the [Code of Conduct](https://github.com/alliedcode/passkeys-rails/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. If you encounter any behavior that violates the code, please report it to the project maintainers.
 
 ## License
 

data/app/controllers/passkeys_rails/application_controller.rb

@@ -1,10 +1,15 @@
 module PasskeysRails
   class ApplicationController < ActionController::Base
+    rescue_from StandardError, with: :handle_standard_error
     rescue_from ::Interactor::Failure, with: :handle_interactor_failure
     rescue_from ActionController::ParameterMissing, with: :handle_missing_parameter
 
     protected
 
+    def handle_standard_error(error)
+      render_error(:authentication, 'error', error.message.truncate(512), status: 500)
+    end
+
     def handle_missing_parameter(error)
       render_error(:authentication, 'missing_parameter', error.message)
     end

data/app/controllers/passkeys_rails/passkeys_controller.rb

@@ -1,33 +1,45 @@
 module PasskeysRails
   class PasskeysController < ApplicationController
+    skip_before_action :verify_authenticity_token
+    wrap_parameters false
+
     def challenge
       result = PasskeysRails::BeginChallenge.call!(username: challenge_params[:username])
 
       # Store the challenge so we can verify the future register or authentication request
-      session[:passkeys_rails] = result.session_data
+      cookies[:passkeys_rails] = result.cookie_data
 
       render json: result.response.as_json
     end
 
     def register
+      cookie_data = cookies["passkeys_rails"] || {}
       result = PasskeysRails::FinishRegistration.call!(credential: attestation_credential_params.to_h,
-                                                       authenticatable_info: authenticatable_info&.to_h,
-                                                       username: session.dig(:passkeys_rails, :username),
-                                                       challenge: session.dig(:passkeys_rails, :challenge))
+                                                       authenticatable_info: authenticatable_params&.to_h,
+                                                       username: cookie_data["username"],
+                                                       challenge: cookie_data["challenge"])
+
+      broadcast(:did_register, agent: result.agent)
 
-      render json: { username: result.username, auth_token: result.auth_token }
+      render json: auth_response(result)
     end
 
     def authenticate
+      cookie_data = cookies["passkeys_rails"] || {}
       result = PasskeysRails::FinishAuthentication.call!(credential: authentication_params.to_h,
-                                                         challenge: session.dig(:passkeys_rails, :challenge))
+                                                         challenge: cookie_data["challenge"])
+
+      broadcast(:did_authenticate, agent: result.agent)
 
-      render json: { username: result.username, auth_token: result.auth_token }
+      render json: auth_response(result)
     end
 
     def refresh
       result = PasskeysRails::RefreshToken.call!(token: refresh_params[:auth_token])
-      render json: { username: result.username, auth_token: result.auth_token }
+
+      broadcast(:did_refresh, agent: result.agent)
+
+      render json: auth_response(result)
     end
 
     # This action exists to allow easier mobile app debugging as it may not
@@ -36,11 +48,31 @@ module PasskeysRails
     # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
     def debug_login
       result = PasskeysRails::DebugLogin.call!(username: debug_login_params[:username])
-      render json: { username: result.username, auth_token: result.auth_token }
+
+      broadcast(:did_authenticate, agent: result.agent)
+
+      render json: auth_response(result)
+    end
+
+    # This action exists to allow easier mobile app debugging as it may not
+    # be possible to acess Passkey functionality in mobile simulators.
+    # It is only routable if DEBUG_LOGIN_REGEX is set in the server environment.
+    # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
+    def debug_register
+      result = PasskeysRails::DebugRegister.call!(username: debug_login_params[:username],
+                                                  authenticatable_info: authenticatable_params&.to_h)
+
+      broadcast(:did_register, agent: result.agent)
+
+      render json: auth_response(result)
     end
 
     protected
 
+    def auth_response(result)
+      { username: result.username, auth_token: result.auth_token }
+    end
+
     def challenge_params
       params.permit(:username)
     end
@@ -52,8 +84,8 @@ module PasskeysRails
       credential.permit(:id, :rawId, :type, { response: %i[attestationObject clientDataJSON] })
     end
 
-    def authenticatable_info
-      params.require[:authenticatable].permit(:class, :params) if params[:authenticatable].present?
+    def authenticatable_params
+      params.require(:authenticatable).permit(:class, params: {}) if params[:authenticatable].present?
     end
 
     def authentication_params
@@ -71,5 +103,9 @@ module PasskeysRails
       params.require(:username)
       params.permit(:username)
     end
+
+    def broadcast(event_name, agent:)
+      ActiveSupport::Notifications.instrument("passkeys_rails.#{event_name}", { agent:, request: })
+    end
   end
 end

data/app/interactors/passkeys_rails/begin_challenge.rb

@@ -10,7 +10,7 @@ module PasskeysRails
       options = result.options
 
       context.response = options
-      context.session_data = session_data(options)
+      context.cookie_data = cookie_data(options)
     rescue Interactor::Failure => e
       context.fail! code: e.context.code, message: e.context.message
     end
@@ -25,7 +25,7 @@ module PasskeysRails
       end
     end
 
-    def session_data(options)
+    def cookie_data(options)
       {
         username:,
         challenge: WebAuthn.standard_encoder.encode(options.challenge)

data/app/interactors/passkeys_rails/begin_registration.rb

@@ -13,6 +13,8 @@ module PasskeysRails
     private
 
     def create_or_replace_unregistered_agent
+      context.fail! code: :origin_error, message: "config.wa_origin must be set" if WebAuthn.configuration.origin.blank?
+
       Agent.unregistered.where(username:).destroy_all
 
       agent = Agent.create(username:, webauthn_identifier: WebAuthn.generate_user_id)

data/app/interactors/passkeys_rails/debug_login.rb

@@ -5,6 +5,7 @@
 module PasskeysRails
   class DebugLogin
     include Interactor
+    include Debuggable
 
     delegate :username, to: :context
 
@@ -12,6 +13,7 @@ module PasskeysRails
       ensure_debug_mode
       ensure_regex_match
 
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e
@@ -20,18 +22,6 @@ module PasskeysRails
 
     private
 
-    def ensure_debug_mode
-      context.fail!(code: :not_allowed, message: 'Action not allowed') if username_regex.blank?
-    end
-
-    def ensure_regex_match
-      context.fail!(code: :not_allowed, message: 'Invalid username') unless username&.match?(username_regex)
-    end
-
-    def username_regex
-      PasskeysRails.debug_login_regex
-    end
-
     def agent
       @agent ||= begin
         agent = Agent.find_by(username:)

data/app/interactors/passkeys_rails/debug_register.rb

@@ -0,0 +1,44 @@
+# This functionality exists to allow easier mobile app debugging as it may not
+# be possible to acess Passkey functionality in mobile simulators.
+# It is only operational if DEBUG_LOGIN_REGEX is set in the server environment.
+# CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
+module PasskeysRails
+  class DebugRegister
+    include Interactor
+    include Debuggable
+    include AuthenticatableCreator
+
+    delegate :username, :authenticatable_info, to: :context
+
+    def call
+      ensure_debug_mode
+      ensure_regex_match
+
+      ActiveRecord::Base.transaction do
+        create_authenticatable! if aux_class_name.present?
+      end
+
+      context.agent = agent
+      context.username = agent.username
+      context.auth_token = GenerateAuthToken.call!(agent:).auth_token
+    rescue Interactor::Failure => e
+      context.fail! code: e.context.code, message: e.context.message
+    end
+
+    private
+
+    def agent
+      @agent ||= begin
+        result = BeginRegistration.call(username:)
+        context.fail!(code: result.code, message: result.message) if result.failure?
+
+        agent = Agent.find_by(username:)
+        context.fail!(code: :agent_not_found, message: "No agent found with that username") if agent.blank?
+
+        agent.update! registered_at: Time.current
+
+        agent
+      end
+    end
+  end
+end

data/app/interactors/passkeys_rails/finish_authentication.rb

@@ -8,6 +8,7 @@ module PasskeysRails
     def call
       verify_credential!
 
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e

data/app/interactors/passkeys_rails/finish_registration.rb

@@ -2,13 +2,19 @@
 module PasskeysRails
   class FinishRegistration
     include Interactor
+    include AuthenticatableCreator
 
     delegate :credential, :username, :challenge, :authenticatable_info, to: :context
 
     def call
       verify_credential!
-      store_passkey_and_register_agent!
 
+      agent.transaction do
+        store_passkey_and_register_agent!
+        create_authenticatable! if aux_class_name.present?
+      end
+
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e
@@ -22,70 +28,24 @@ module PasskeysRails
     rescue WebAuthn::Error => e
       context.fail!(code: :webauthn_error, message: e.message)
     rescue StandardError => e
-      context.fail!(code: :error, message: e.message)
-    end
-
-    def store_passkey_and_register_agent!
-      agent.transaction do
-        begin
-          # Store Credential ID, Credential Public Key and Sign Count for future authentications
-          agent.passkeys.create!(
-            identifier: webauthn_credential.id,
-            public_key: webauthn_credential.public_key,
-            sign_count: webauthn_credential.sign_count
-          )
-
-          agent.update! registered_at: Time.current
-        rescue StandardError => e
-          context.fail! code: :passkey_error, message: e.message
-        end
-
-        create_authenticatable! if aux_class_name.present?
-      end
-    end
-
-    def authenticatable_class
-      authenticatable_info && authenticatable_info[:class]
-    end
-
-    def authenticatable_params
-      authenticatable_info && authenticatable_info[:params]
-    end
-
-    def aux_class_name
-      @aux_class_name ||= authenticatable_class || PasskeysRails.default_class
-    end
-
-    def aux_class
-      whitelist = PasskeysRails.class_whitelist
-
-      @aux_class ||= begin
-        if whitelist.is_a?(Array)
-          unless whitelist.include?(aux_class_name)
-            context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not in the whitelist")
-          end
-        elsif whitelist.present?
-          context.fail!(code: :invalid_class_whitelist,
-                        message: "class_whitelist is invalid.  It should be nil or an array of zero or more class names.")
-        end
-
-        begin
-          aux_class_name.constantize
-        rescue StandardError
-          context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not defined")
-        end
+      if e.message == "undefined method `end_with?' for nil:NilClass"
+        context.fail!(code: :webauthn_error, message: "origin is not set")
+      else
+        context.fail!(code: :error, message: e.message)
       end
     end
 
-    def create_authenticatable!
-      authenticatable = aux_class.create! do |obj|
-        obj.agent = agent if obj.respond_to?(:agent=)
-        obj.registering_with(authenticatable_params) if obj.respond_to?(:registering_with)
-      end
-
-      agent.update!(authenticatable:)
-    rescue ActiveRecord::RecordInvalid => e
-      context.fail!(code: :record_invalid, message: e.message)
+    def store_passkey_and_register_agent!
+      # Store Credential ID, Credential Public Key and Sign Count for future authentications
+      agent.passkeys.create!(
+        identifier: webauthn_credential.id,
+        public_key: webauthn_credential.public_key,
+        sign_count: webauthn_credential.sign_count
+      )
+
+      agent.update! registered_at: Time.current
+    rescue StandardError => e
+      context.fail! code: :passkey_error, message: e.message
     end
 
     def webauthn_credential
@@ -95,7 +55,7 @@ module PasskeysRails
     def agent
       @agent ||= begin
         agent = Agent.find_by(username:)
-        context.fail!(code: :agent_not_found, message: "Agent not found for session value: \"#{username}\"") if agent.blank?
+        context.fail!(code: :agent_not_found, message: "Agent not found for cookie value: \"#{username}\"") if agent.blank?
 
         agent
       end

data/app/interactors/passkeys_rails/refresh_token.rb

@@ -8,6 +8,7 @@ module PasskeysRails
     def call
       agent = ValidateAuthToken.call!(auth_token: token).agent
 
+      context.agent = agent
       context.username = agent.username
       context.auth_token = GenerateAuthToken.call!(agent:).auth_token
     rescue Interactor::Failure => e

data/app/models/concerns/passkeys_rails/authenticatable_creator.rb

@@ -0,0 +1,53 @@
+module PasskeysRails
+  module AuthenticatableCreator
+    extend ActiveSupport::Concern
+
+    protected
+
+    def create_authenticatable!
+      authenticatable = aux_class.new
+      authenticatable.agent = agent if authenticatable.respond_to?(:agent=)
+      authenticatable.registering_with(authenticatable_params) if authenticatable.respond_to?(:registering_with)
+      authenticatable.save!
+
+      agent.update!(authenticatable:)
+    rescue ActiveRecord::RecordInvalid => e
+      context.fail!(code: :record_invalid, message: e.message)
+    end
+
+    def aux_class_name
+      @aux_class_name ||= authenticatable_class || PasskeysRails.default_class
+    end
+
+    private
+
+    def authenticatable_class
+      authenticatable_info && authenticatable_info[:class]
+    end
+
+    def authenticatable_params
+      authenticatable_info && authenticatable_info[:params]
+    end
+
+    def aux_class
+      whitelist = PasskeysRails.class_whitelist
+
+      @aux_class ||= begin
+        if whitelist.is_a?(Array)
+          unless whitelist.include?(aux_class_name)
+            context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not in the whitelist")
+          end
+        elsif whitelist.present?
+          context.fail!(code: :invalid_class_whitelist,
+                        message: "class_whitelist is invalid.  It should be nil or an array of zero or more class names.")
+        end
+
+        begin
+          aux_class_name.constantize
+        rescue StandardError
+          context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not defined")
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/passkeys_rails/debuggable.rb

@@ -0,0 +1,19 @@
+module PasskeysRails
+  module Debuggable
+    extend ActiveSupport::Concern
+
+    protected
+
+    def ensure_debug_mode
+      context.fail!(code: :not_allowed, message: 'Action not allowed') if username_regex.blank?
+    end
+
+    def ensure_regex_match
+      context.fail!(code: :not_allowed, message: 'Invalid username') unless username&.match?(username_regex)
+    end
+
+    def username_regex
+      PasskeysRails.debug_login_regex
+    end
+  end
+end

data/config/routes.rb

@@ -1,13 +1,14 @@
 PasskeysRails::Engine.routes.draw do
-  post 'passkeys/challenge'
-  post 'passkeys/register'
-  post 'passkeys/authenticate'
-  post 'passkeys/refresh'
+  post 'challenge', to: 'passkeys#challenge'
+  post 'register', to: 'passkeys#register'
+  post 'authenticate', to: 'passkeys#authenticate'
+  post 'refresh', to: 'passkeys#refresh'
 
-  # This route exists to allow easier mobile app debugging as it may not
+  # These routes exist to allow easier mobile app debugging as it may not
   # be possible to acess Passkey functionality in mobile simulators.
   # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
   constraints(->(_request) { PasskeysRails.debug_login_regex.present? }) do
-    post 'passkeys/debug_login'
+    post 'debug_login', to: 'passkeys#debug_login'
+    post 'debug_register', to: 'passkeys#debug_register'
   end
 end

data/lib/generators/passkeys_rails/templates/passkeys_rails_config.rb

@@ -45,4 +45,60 @@ PasskeysRails.config do |c|
   # for example: %w[User AdminUser]
   #
   # c.class_whitelist = nil
+
+  # To subscribe to various events in PasskeysRails, use the subscribe method.
+  # It can be called multiple times to subscribe to more than one event.
+  #
+  # Valid events:
+  #   :did_register
+  #   :did_authenticate
+  #   :did_refresh
+  #
+  # Each event will include the event name, current agent and http request.
+  #
+  # For example:
+  # c.subscribe(:did_register) do |event, agent, request|
+  #   puts("#{event} | #{agent.id} | #{request.headers}")
+  # end
+
+  # PasskeysRails uses webauthn to help with the protocol.
+  # The following settings are passed throught webauthn.
+  # wa_origin is the only one requried
+
+  # This value needs to match `window.location.origin` evaluated by
+  # the User Agent during registration and authentication ceremonies.
+  # c.wa_origin = ENV['DEFAULT_HOST'] || https://myapp.mydomain.com
+
+  # Relying Party name for display purposes
+  # c.wa_relying_party_name = "My App Name"
+
+  # Optionally configure a client timeout hint, in milliseconds.
+  # This hint specifies how long the browser should wait for any
+  # interaction with the user.
+  # This hint may be overridden by the browser.
+  # https://www.w3.org/TR/webauthn/#dom-publickeycredentialcreationoptions-timeout
+  # c.wa_credential_options_timeout = 120_000
+
+  # You can optionally specify a different Relying Party ID
+  # (https://www.w3.org/TR/webauthn/#relying-party-identifier)
+  # if it differs from the default one.
+  #
+  # In this case the default would be "auth.example.com", but you can set it to
+  # the suffix "example.com"
+  #
+  # c.wa_rp_id = "example.com"
+
+  # Configure preferred binary-to-text encoding scheme. This should match the encoding scheme
+  # used in your client-side (user agent) code before sending the credential to the server.
+  # Supported values: `:base64url` (default), `:base64` or `false` to disable all encoding.
+  #
+  # c.wa_encoding = :base64url
+
+  # Possible values: "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "RS1"
+  # Default: ["ES256", "PS256", "RS256"]
+  #
+  # c.wa_algorithms = ["ES256", "PS256", "RS256"]
+
+  # Append an algorithm to the existing set
+  # c.wa_algorithm = "PS512"
 end

data/lib/passkeys-rails.rb

@@ -1,49 +1,62 @@
 # rubocop:disable Naming/FileName
 require 'passkeys_rails/engine'
+require 'passkeys_rails/configuration'
 require 'passkeys_rails/version'
 require_relative "generators/passkeys_rails/install_generator"
+require 'forwardable'
 
 module PasskeysRails
   module Test
     autoload :IntegrationHelpers, 'passkeys_rails/test/integration_helpers'
   end
 
-  # Secret used to encode the auth token.
-  # Rails.application.secret_key_base is used if none is defined here.
-  # Changing this value will invalidate all tokens that have been fetched
-  # through the API.
-  mattr_accessor(:auth_token_secret)
+  class << self
+    extend Forwardable
 
-  # Algorithm used to generate the auth token.
-  # Changing this value will invalidate all tokens that have been fetched
-  # through the API.
-  mattr_accessor :auth_token_algorithm, default: "HS256"
+    def_delegators :config, :auth_token_secret, :auth_token_algorithm, :auth_token_expires_in, :default_class, :class_whitelist
 
-  # How long the auth token is valid before requiring a refresh or new login.
-  # Set it to 0 for no expiration (not recommended in production).
-  mattr_accessor :auth_token_expires_in, default: 30.days
+    def config
+      @config ||= begin
+        config = Configuration.new
+        yield(config) if block_given?
+        apply_webauthn_configuration(config)
 
-  # Model to use when creating or authenticating a passkey.
-  # This can be overridden when calling the API, but if no
-  # value is supplied when calling the API, this value is used.
-  # If nil, there is no default, and if none is supplied when
-  # calling the API, no resource is created other than
-  # a PaskeysRails::Agent that is used to track the passkey.
-  #
-  # This library doesn't assume that there will only be one
-  # model, but it is a common use case, so setting the
-  # default_class simplifies the use of the API in that case.
-  mattr_accessor :default_class, default: "User"
+        config
+      end
+    end
+  end
 
-  # By providing a class_whitelist, the API will require that
-  # any supplied class is in the whitelist.  If it is not, the
-  # auth API will return an error.  This prevents a caller from
-  # attempting to create an unintended record on registration.
-  # If nil, any model will be allowed.
-  # If [], no model will be allowed.
-  # This should be an array of symbols or strings,
-  # for example: %w[User AdminUser]
-  mattr_accessor :class_whitelist, default: nil
+  def self.apply_webauthn_configuration(config)
+    WebAuthn.configure do |c|
+      c.origin = config.wa_origin
+      c.rp_name = config.wa_relying_party_name if config.wa_relying_party_name
+      c.credential_options_timeout = config.wa_credential_options_timeout if config.wa_credential_options_timeout
+      c.rp_id = config.wa_rp_id if config.wa_rp_id
+      c.encoding = config.wa_encoding if config.wa_encoding
+      c.algorithms = config.wa_algorithms if config.wa_algorithms
+      c.algorithms << config.wa_algorithm if config.wa_algorithm
+    end
+  end
+
+  # Convenience method to subscribe to various events in PasskeysRails.
+  #
+  # Valid events:
+  #   :did_register
+  #   :did_authenticate
+  #   :did_refresh
+  #
+  # Each event will include the event name, current agent and http request.
+  # For example:
+  #
+  # subscribe(:did_register) do |event, agent, request|
+  #   # do something with the agent and/or request
+  # end
+  #
+  def self.subscribe(event_name)
+    ActiveSupport::Notifications.subscribe("passkeys_rails.#{event_name}") do |name, _start, _finish, _id, payload|
+      yield(name.gsub(/^passkeys_rails\./, ''), payload[:agent], payload[:request]) if block_given?
+    end
+  end
 
   # This is only used by the debug_login endpoint.
   # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
@@ -84,16 +97,6 @@ module PasskeysRails
                                    message: auth.message)
   end
 
-  class << self
-    def config
-      yield self
-    end
-  end
-
   require 'passkeys_rails/railtie' if defined?(Rails)
 end
-
-ActiveSupport.on_load(:before_initialize) do
-  PasskeysRails.auth_token_secret ||= Rails.application.secret_key_base
-end
 # rubocop:enable Naming/FileName

data/lib/passkeys_rails/configuration.rb

@@ -0,0 +1,62 @@
+module PasskeysRails
+  class Configuration
+    # Secret used to encode the auth token.
+    # Rails.application.secret_key_base is used if none is defined here.
+    # Changing this value will invalidate all tokens that have been fetched
+    # through the API.
+    attr_accessor :auth_token_secret
+
+    # Algorithm used to generate the auth token.
+    # Changing this value will invalidate all tokens that have been fetched
+    # through the API.
+    attr_accessor :auth_token_algorithm
+
+    # How long the auth token is valid before requiring a refresh or new login.
+    # Set it to 0 for no expiration (not recommended in production).
+    attr_accessor :auth_token_expires_in
+
+    # Model to use when creating or authenticating a passkey.
+    # This can be overridden when calling the API, but if no
+    # value is supplied when calling the API, this value is used.
+    # If nil, there is no default, and if none is supplied when
+    # calling the API, no resource is created other than
+    # a PaskeysRails::Agent that is used to track the passkey.
+    #
+    # This library doesn't assume that there will only be one
+    # model, but it is a common use case, so setting the
+    # default_class simplifies the use of the API in that case.
+    attr_accessor :default_class
+
+    # By providing a class_whitelist, the API will require that
+    # any supplied class is in the whitelist.  If it is not, the
+    # auth API will return an error.  This prevents a caller from
+    # attempting to create an unintended record on registration.
+    # If nil, any model will be allowed.
+    # If [], no model will be allowed.
+    # This should be an array of symbols or strings,
+    # for example: %w[User AdminUser]
+    attr_accessor :class_whitelist
+
+    # webauthn settings
+    attr_accessor :wa_origin,
+                  :wa_relying_party_name,
+                  :wa_credential_options_timeout,
+                  :wa_rp_id,
+                  :wa_encoding,
+                  :wa_algorithms,
+                  :wa_algorithm
+
+    def initialize
+      # defaults
+      @auth_token_secret = Rails.application.secret_key_base
+      @auth_token_algorithm = "HS256"
+      @auth_token_expires_in = 30.days
+      @default_class = "User"
+      @wa_origin = "https://example.com"
+    end
+
+    def subscribe(event_name)
+      PasskeysRails.subscribe(event_name)
+    end
+  end
+end

data/lib/passkeys_rails/version.rb

@@ -1,3 +1,3 @@
 module PasskeysRails
-  VERSION = "0.2.1".freeze
+  VERSION = "0.3.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: passkeys-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Troy Anderson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-29 00:00:00.000000000 Z
+date: 2023-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -358,12 +358,15 @@ files:
 - app/interactors/passkeys_rails/begin_challenge.rb
 - app/interactors/passkeys_rails/begin_registration.rb
 - app/interactors/passkeys_rails/debug_login.rb
+- app/interactors/passkeys_rails/debug_register.rb
 - app/interactors/passkeys_rails/finish_authentication.rb
 - app/interactors/passkeys_rails/finish_registration.rb
 - app/interactors/passkeys_rails/generate_auth_token.rb
 - app/interactors/passkeys_rails/refresh_token.rb
 - app/interactors/passkeys_rails/validate_auth_token.rb
 - app/models/concerns/passkeys_rails/authenticatable.rb
+- app/models/concerns/passkeys_rails/authenticatable_creator.rb
+- app/models/concerns/passkeys_rails/debuggable.rb
 - app/models/passkeys_rails/agent.rb
 - app/models/passkeys_rails/application_record.rb
 - app/models/passkeys_rails/error.rb
@@ -377,6 +380,7 @@ files:
 - lib/generators/passkeys_rails/templates/README
 - lib/generators/passkeys_rails/templates/passkeys_rails_config.rb
 - lib/passkeys-rails.rb
+- lib/passkeys_rails/configuration.rb
 - lib/passkeys_rails/engine.rb
 - lib/passkeys_rails/railtie.rb
 - lib/passkeys_rails/test/integration_helpers.rb