passkeys-rails 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1c218e160d157a8ddcf931fae3a053fb6e130130b61a8e03f5a9a2bcade07b1
-  data.tar.gz: 42fb39898dd79867bd8d18fb95b39ac335a47ed5a06d3ccb13b5f3fc2b64b6af
+  metadata.gz: 6d6b32ba5bcfa9553687bb70a01ba4e1b9211ab50336e62f3f7eae7033c3f689
+  data.tar.gz: e53cc11ffec79936ec74319fb1ec6d47cd74d67f4f56ff0c2d234abf8800b1f3
 SHA512:
-  metadata.gz: 85c226aabf90e17b56744947b37eab49f98c4cbacc42a4963316ea60a68fa6c49b40ea81297d2786a16151361fa6e0f637a5af18d147db12894f5288ef260558
-  data.tar.gz: 9a26aa0b7c5e907b954f2564244ab222205775da8087c0c9b17cde3e00706aace1b21b4c3c57d728b91472ed035eeb3f4c87d2ecc4ccecb1e41c5f767d548ccc
+  metadata.gz: 87cb708335cfae465b142633dc829c92ac16c4d9d958807cbb682caf455ca18e2b13a24ad30b1bb3020f3493b6dd924151269eb37ba2eaeb09508d5b350a9572
+  data.tar.gz: 04fcd5259c6fe2b1d06f289254817fc1baee73e5d7c7d2aee3476a2155e02e2cb4c40c02deab4285a602bbe9c51806a3e90c5f15ed2b3de928ca9843b0f9fd14

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+### 0.2.0
+
+* Added passkeys/debug_login functionality.
+
+### 0.1.7
+
+* Added IntegrationHelpers to support client testing.
+* Updated methods for interfacing with Rails client app.
+* Changed route path added by the generator.
+
+### 0.1.6
+
+* Added default_class and class_whitelist config parameters.
+
+### 0.1.5
+
+* Updated validation to ensure the agent has completed registration to be considered valid.
+
 ### 0.1.4
 
 * Changed namespace from Passkeys::Rails to PasskeysRails

data/README.md

@@ -1,43 +1,38 @@
-[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=5)](https://badge.fury.io/rb/passkeys-rails)
+[![Gem Version](https://badge.fury.io/rb/passkeys-rails.svg?cachebust=7)](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
-Devise is awesome, but we don't need all that UI/UX for PassKeys.  This gem is to make
-it easy to provide a back end that authenticates a mobile front end with PassKeys.
+
+Devise is awesome, but we don't need all that UI/UX for PassKeys, especially for an API back end.
+
+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.
+
 
 ## Usage
-rails passkeys-rails::install
-PasskeysRails maintains an Agent model and related Passeys.  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.
 
-### 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** 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.
+
+### Optionally providing a **"user"** model during registration
 
-PasskeysRails supports multiple "user" models.  Whatever model name you supply in the finishRegiration call will
-be created and provided an opportunity to do any required initialization at that time.
+**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.
 
-There are two PasskeysRails configuration options related to this.
+**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.
 
-default_class and class_whitelist
+There are two **PasskeysRails** configuration options related to this: `default_class` and `class_whitelist` - see below.
 
-#### default_class
+#### `default_class`
 
-Configure default_class in passkeys_rails.rb.  Its value will be used during registration if none
-is provided in the API call.  It is "User" by default.  Since it's just a default, it can be overridden
-in the API call for any other model.  If no model is to be used, change it to nil.
+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.
 
-#### class_whitelist
+#### `class_whitelist`
 
-Configure class_whitelist in passkeys_rails.rb.  It is nil by default.  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 `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
@@ -45,8 +40,9 @@ gem "passkeys_rails"
 ```
 
 And then execute:
+
 ```bash
-$ bundle
+$ bundle install
 ```
 
 Or install it yourself as:
@@ -54,22 +50,364 @@ Or install it yourself as:
 $ gem install passkeys_rails
 ```
 
-Depending on your application's configuration some manual setup may be required:
+Finally, execute:
+
+```bash
+$ 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.
+
+### Adding to an standard rails project
+
+1. Add `before_action :authenticate_passkey!`
+
+ 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.
+
+1. 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)
+
+ 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
+
+1. 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:
+
+```ruby
+  helpers do
+    # Authenticate the request and cache the result
+    def passkey
+      @passkey ||= PasskeysRails.authenticate(request)
+    end
+
+    # Raise an exception if the request is not authentic
+    def authenticate_passkey!
+      error!({ code: passkey.code, message: passkey.message }, :unauthorized) if passkey.failure?
+    end
+
+    # Return the Passkeys::Agent if authentic, else return nil
+    def current_agent
+      passkey.agent
+    end
+
+    # If you have set authenticatable to be a User, you can use this to access the user from Grape endpoint methods
+    def current_user
+      user = current_agent&.authenticatable
+      user.is_a?(User) ? user : nil # sanity check to be sure authenticatable is a User
+    end
+  end
+```
+
+ 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`
+
+ 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
+
+1. In the event of authentication failure, PasskeysRails returns 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.
 
-  1. Add a before_action to all controllers that require authentication to use.
+1. In Grape, the error code and message are available in the result of the `PasskeysRails.authenticate(request)` method.
+
+1. From standard rails controllers, you can also access `passkey_authentication_result` to get the code and message.
+
+1. For `PasskeysRails.authenticate(request)` and `passkey_authentication_result`, the result is an object that respods to `.success?` and `.failure?`.
+ - When `.success?` is true (`.failure?` is false), the resources is authentic and it also responds to `.agent`, returning a PasskeysRails::Agent
+ - When `.success?` is false (`.failure?` is true), it responds to `.code` and `.message` to expose the error details.
+ - When `.code` is `:missing_token`, `.message` is **X-Auth header is required**, which means the caller didn't supply the auth header.
+ - When `.code` is `:invalid_token`, `.message` is **Invalid token - no agent exists with agent_id**, which means that the auth data is not valid.
+ - When `.code` is `:expired_token`, `.message` is **The token has expired**, which means that the token is valid, but expired, thuis it's not considered authentic.
+ - When `.code` is `:token_error`, `.message` is a description of the error.  This is a catch-all in the event we are unable to decode the token.
+
+ 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
+
+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
+class PostTests < ActionDispatch::IntegrationTest
+  include PasskeysRails::Test::IntegrationHelpers
+end
+```
+Now you can use the following `logged_in_headers` method in your integration tests.`
+
+```ruby
+  test 'authenticated users can see posts' do
+    user = User.create
+    get '/posts', headers: logged_in_headers('username-123', user)
+    assert_response :success
+  end
+```
+
+RSpec can include the `IntegrationHelpers` module in their `:feature` and `:request` specs.
+
+```ruby
+RSpec.configure do |config|
+  config.include PasskeysRails::Test::IntegrationHelpers, type: :feature
+  config.include PasskeysRails::Test::IntegrationHelpers, type: :request
+end
+```
+
+```ruby
+RSpec.describe 'Posts', type: :request do
+  let(:user) { User.create }
+  it "allows authenticated users to see posts" do
+    get '/posts', headers: logged_in_headers('username-123', user)
+    expect(response).to be_success
+  end
+end
+```
+
+### Mobile Application Integration
+
+There are n 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.
+
+**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.
+
+All Passkey endpoints accept and respond with JSON.
+
+On **success**, they will respond with a 200 or 201 response code and relevant JSON.
+
+On **error**, they will respond with a status code of `422` (Unprocessable Entity) and a JSON `ErrorResponse` structure:
+
+```JSON
+{
+  "error": {
+    "context": "authentication",
+    "code": "Specific text code",
+    "message": "Some human readable message"
+  }
+}
+```
+
+Some endpoints return an `AuthResponse`, which has this JSON structure:
+
+```JSON
+{
+    "username": String,   # the username used during registration
+    "auth_token": String  # an expiring token to use to authenticate with the back end (X-Auth header)
+}
+```
 
-     For example:
+#### POST /passkeys/challenge
 
-        before_action :authenticate_passkey!, except: [:index]
+Submit this to begin registration or authentication.
 
-  2. Optionally include PasskeysRails::Authenticatable to the model(s) you are using as
-     your user model(s).  For example, the User model.
+Supply a `{ "username": "unique username" } ` to register a new credential.
+If all goes well, the JSON response will be the `options_for_create` from webauthn.
+If the username is already in use, or anything else goes wrong, an error with code `validation_errors` will be returned.
 
-  3. See the reference mobile applications for how to use passkeys-rails for passkey
-     authentication.
+Omit the `username` when authenticating (logging in).
+The JSON response will be the `options_for_get` from webauthn.
+
+#### POST /passkeys/register
+
+After calling the `challenge` endpoint with a `username`, and handling its response, finish registering by calling this endpoint.
+
+Supply the following JSON structure:
+
+```JSON
+# POST body
+{
+  # NOTE: credential will likely come directly from the PassKeys class/library on the platform
+  "credential": {
+    "id": String,
+    "rawId": String,
+    "type": String,
+    "response": {
+      "attestationObject": String,
+      "clientDataJSON": String
+    }
+  },
+  # authenticatable is optional and is informas PasskeysRails how to build your "user" model
+  "authenticatable": { # optional
+    "class": "User", # whatever class to which you want this credential to apply (as described earlier)
+    "params": { }    # Any params you want passed as a hash to the registering_with method on that class
+  }
+}
+```
+
+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
+
+#### POST /passkeys/authenticate
+
+After calling the `challenge` endpoint without a `username`, and handling its response, finish authenticating by calling this endpoint.
+
+Supply the following JSON structure:
+
+```JSON
+# POST body
+{
+  # NOTE: all of this will likely come directly from the PassKeys class/library on the platform
+  "id": String,                   # Base64 encoded assertion.credentialID
+  "rawId": String,                # Base64 encoded assertion.credentialID
+  "type": "public-key",
+  "response": {
+    "authenticatorData": String,  # Base64 encoded assertion.rawAuthenticatorData
+    "clientDataJSON": String,     # Base64 encoded assertion.rawClientDataJSON
+    "signature": String,          # Base64 encoded signature
+    "userHandle":String           # Base64 encoded assertion.userID
+  }
+}
+```
+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
+
+#### 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.
+
+Supply the following JSON structure:
+
+```JSON
+# POST body
+{
+  token: String
+}
+```
+
+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
+
+#### POST /passkeys/debug_login
+
+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.
+
+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. Use the response as if it was from /passkeys/authenticate.
+
+If you supply a username that doesn't match the DEBUG_LOGIN_REGEX, the endpoint will respond with an error.
+
+```JSON
+# POST body
+{
+  "username": String
+}
+```
+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
-Contribution directions go here.
+
+### 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.
+
+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.
+
+4. Before submitting a pull request, ensure that your changes pass all existing tests and add relevant tests if applicable.
+
+5. Update the documentation if your changes introduce new features, modify existing behavior, or require user instructions.
+
+6. Squash your commits into a single logical commit if needed. Keep your commit history clean and focused.
+
+7. Submit a pull request against the `main` branch of the original repository.
+
+8. Add a comment at the top of the CHANGELOG.md describing the change.
+
+#### Pull Request Guidelines
+
+When submitting a pull request, please include the following details:
+
+- A clear description of the changes you made and the problem it solves.
+
+- Any relevant issue numbers that your pull request addresses or fixes.
+
+- The steps to test your changes, so the project maintainers can verify them.
+
+- Ensure that your pull request title and description are descriptive and informative.
+
+#### Code Review Process
+
+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.
+
+#### Contributor License Agreement
+
+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).
+
+#### Reporting Issues
+
+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
+
+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!
+
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+The gem is available as open source under the terms of the [MIT License](https://github.com/alliedcode/passkeys-rails/blob/main/MIT-LICENSE).

data/app/controllers/concerns/passkeys_rails/authentication.rb

@@ -9,22 +9,17 @@ module PasskeysRails
     end
 
     def current_agent
-      @current_agent ||= (request.headers['HTTP_X_AUTH'].present? &&
-                         passkey_authentication_result.success? &&
+      @current_agent ||= (passkey_authentication_result.success? &&
                          passkey_authentication_result.agent.registered? &&
                          passkey_authentication_result.agent) || nil
     end
 
     def authenticate_passkey!
-      return if current_agent.present?
-
-      raise PasskeysRails::Error.new(:authentication,
-                                     code: :unauthorized,
-                                     message: "You are not authorized to access this resource.")
+      @authenticate_passkey ||= PasskeysRails.authenticate!(request)
     end
 
     def passkey_authentication_result
-      @passkey_authentication_result ||= PasskeysRails::ValidateAuthToken.call(auth_token: request.headers['HTTP_X_AUTH'])
+      @passkey_authentication_result ||= PasskeysRails.authenticate(request)
     end
   end
 end

data/app/controllers/passkeys_rails/passkeys_controller.rb

@@ -11,7 +11,7 @@ module PasskeysRails
 
     def register
       result = PasskeysRails::FinishRegistration.call!(credential: attestation_credential_params.to_h,
-                                                       authenticatable_class:,
+                                                       authenticatable_info: authenticatable_info&.to_h,
                                                        username: session.dig(:passkeys_rails, :username),
                                                        challenge: session.dig(:passkeys_rails, :challenge))
 
@@ -30,6 +30,15 @@ module PasskeysRails
       render json: { username: result.username, auth_token: result.auth_token }
     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_login
+      result = PasskeysRails::DebugLogin.call!(username: debug_login_params[:username])
+      render json: { username: result.username, auth_token: result.auth_token }
+    end
+
     protected
 
     def challenge_params
@@ -43,8 +52,8 @@ module PasskeysRails
       credential.permit(:id, :rawId, :type, { response: %i[attestationObject clientDataJSON] })
     end
 
-    def authenticatable_class
-      params[:authenticatable_class]
+    def authenticatable_info
+      params.require[:authenticatable].permit(:class, :params) if params[:authenticatable].present?
     end
 
     def authentication_params
@@ -57,5 +66,10 @@ module PasskeysRails
       params.require(:auth_token)
       params.permit(:auth_token)
     end
+
+    def debug_login_params
+      params.require(:username)
+      params.permit(:username)
+    end
   end
 end

data/app/interactors/passkeys_rails/debug_login.rb

@@ -0,0 +1,43 @@
+# 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 DebugLogin
+    include Interactor
+
+    delegate :username, to: :context
+
+    def call
+      ensure_debug_mode
+      ensure_regex_match
+
+      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 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:)
+        context.fail!(code: :agent_not_found, message: "No agent found with that username") if agent.blank?
+        agent
+      end
+    end
+  end
+end

data/app/interactors/passkeys_rails/finish_registration.rb

@@ -3,7 +3,7 @@ module PasskeysRails
   class FinishRegistration
     include Interactor
 
-    delegate :credential, :username, :challenge, :authenticatable_class, to: :context
+    delegate :credential, :username, :challenge, :authenticatable_info, to: :context
 
     def call
       verify_credential!
@@ -44,6 +44,14 @@ module PasskeysRails
       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
@@ -52,25 +60,27 @@ module PasskeysRails
       whitelist = PasskeysRails.class_whitelist
 
       @aux_class ||= begin
-        case whitelist
-        when Array
+        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
-        when present?
+        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
 
-        aux_class_name.constantize
-      rescue StandardError
-        context.fail!(code: :invalid_authenticatable_class, message: "authenticatable_class (#{aux_class_name}) is not defined")
+        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
 
     def create_authenticatable!
       authenticatable = aux_class.create! do |obj|
-        obj.registering_with(agent) if obj.respond_to?(:registering_with)
+        obj.agent = agent if obj.respond_to?(:agent=)
+        obj.registering_with(authenticatable_params) if obj.respond_to?(:registering_with)
       end
 
       agent.update!(authenticatable:)

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

@@ -5,11 +5,11 @@ module PasskeysRails
     extend ActiveSupport::Concern
 
     included do
-      has_one :agent, as: :authenticatable
+      has_one :agent, as: :authenticatable, class_name: "PasskeysRails::Agent"
 
       delegate :registered?, to: :agent, allow_nil: true
 
-      def registering_with(_agent)
+      def registering_with(_params)
         # initialize required attributes
       end
     end

data/config/routes.rb

@@ -3,4 +3,11 @@ PasskeysRails::Engine.routes.draw do
   post 'passkeys/register'
   post 'passkeys/authenticate'
   post 'passkeys/refresh'
+
+  # This route exists 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'
+  end
 end

data/lib/generators/passkeys_rails/USAGE

@@ -2,7 +2,7 @@ Description:
     Creates a PasskeysRails config file, updates the routes and adds migrations.
 
 Example:
-    bin/rails generate passkeys-rails:install
+    bin/rails generate passkeys_rails:install
 
     This will:
         create config/passkeys_rails.rb

data/lib/generators/passkeys_rails/install_generator.rb

@@ -5,14 +5,22 @@ module PasskeysRails
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
+      desc "Adds passkeys config file to your application."
       def copy_config
         template 'passkeys_rails_config.rb', "config/initializers/passkeys_rails.rb"
       end
 
+      desc "Adds passkeys routes to your application."
       def add_routes
-        route 'mount PasskeysRails::Engine => "/passkeys_rails"'
+        route 'mount PasskeysRails::Engine => "/passkeys"'
       end
 
+      desc "Copies migrations to your application."
+      def copy_migrations
+        rake("passkeys_rails:install:migrations")
+      end
+
+      desc "Displays readme during installation."
       def show_readme
         readme "README" if behavior == :invoke
       end

data/lib/passkeys-rails.rb

@@ -4,6 +4,10 @@ require 'passkeys_rails/version'
 require_relative "generators/passkeys_rails/install_generator"
 
 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
@@ -41,6 +45,34 @@ module PasskeysRails
   # for example: %w[User AdminUser]
   mattr_accessor :class_whitelist, default: nil
 
+  # This is only used by the debug_login endpoint.
+  # CAUTION: It is very insecure to set DEBUG_LOGIN_REGEX in a production environment.
+  def self.debug_login_regex
+    ENV['DEBUG_LOGIN_REGEX'].present? ? Regexp.new(ENV['DEBUG_LOGIN_REGEX']) : nil
+  end
+
+  # Returns an Interactor::Context that indicates if the request is authentic.
+  #
+  # .success? is true if authentic
+  # .agent is the Passkey::Agent on success
+  #
+  # .failure? is true if failed (just the opposite of .success?)
+  # .code is the error code on failure
+  # .message is the human readable error message on failure
+  def self.authenticate(request)
+    PasskeysRails::ValidateAuthToken.call(auth_token: request.headers['X-Auth'])
+  end
+
+  # Raises a PasskeysRails::Error exception if the request is not authentic.
+  def self.authenticate!(request)
+    auth = authenticate(request)
+    return if auth.success?
+
+    raise PasskeysRails::Error.new(:authentication,
+                                   code: auth.code,
+                                   message: auth.message)
+  end
+
   class << self
     def config
       yield self

data/lib/passkeys_rails/test/integration_helpers.rb

@@ -0,0 +1,46 @@
+module PasskeysRails
+  # PasskeysRails::Test::IntegrationHelpers is a helper module for facilitating
+  # authentication on Rails integration tests to bypass the required steps for
+  # signin in or signin out a record.
+  #
+  # Examples
+  #
+  #  class PostsTest < ActionDispatch::IntegrationTest
+  #    include PasskeysRails::Test::IntegrationHelpers
+  #
+  #    test 'authenticated users can see posts' do
+  #      get '/posts', headers: logged_in_headers('username-1')
+  #      assert_response :success
+  #    end
+  #  end
+  module Test
+    module IntegrationHelpers
+      def self.included(base)
+        base.class_eval do
+          setup :setup_integration_for_passkeys_rails
+          teardown :teardown_integration_for_passkeys_rails
+        end
+      end
+
+      def logged_in_headers(username, authenticatable = nil, headers: {})
+        @agent = Agent.create(username:, registered_at: Time.current, authenticatable:)
+        result = PasskeysRails::GenerateAuthToken.call(agent:)
+        raise result.message if result.failure?
+
+        headers.merge("X-Auth" => result.auth_token)
+      end
+
+      protected
+
+      attr_reader :agent
+
+      def setup_integration_for_passkeys_rails
+        # Nothing to do here
+      end
+
+      def teardown_integration_for_passkeys_rails
+        @agent&.destroy
+      end
+    end
+  end
+end

data/lib/passkeys_rails/version.rb

@@ -1,3 +1,3 @@
 module PasskeysRails
-  VERSION = "0.1.6".freeze
+  VERSION = "0.2.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: passkeys-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Troy Anderson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-26 00:00:00.000000000 Z
+date: 2023-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -357,6 +357,7 @@ files:
 - app/interactors/passkeys_rails/begin_authentication.rb
 - 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/finish_authentication.rb
 - app/interactors/passkeys_rails/finish_registration.rb
 - app/interactors/passkeys_rails/generate_auth_token.rb
@@ -378,6 +379,7 @@ files:
 - lib/passkeys-rails.rb
 - lib/passkeys_rails/engine.rb
 - lib/passkeys_rails/railtie.rb
+- lib/passkeys_rails/test/integration_helpers.rb
 - lib/passkeys_rails/version.rb
 - lib/tasks/passkeys_rails_tasks.rake
 homepage: https://github.com/alliedcode/passkeys-rails