passkeys-rails 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 631e7354b6296e5fcc14144ba3bd305ca9047c31f9e5b0173f5eb7123f14fa71
-  data.tar.gz: 65e1f2d4cbd179ddee7449318b49a838d166db64db9221e1f079ac7e57735bf3
+  metadata.gz: 6d6b32ba5bcfa9553687bb70a01ba4e1b9211ab50336e62f3f7eae7033c3f689
+  data.tar.gz: e53cc11ffec79936ec74319fb1ec6d47cd74d67f4f56ff0c2d234abf8800b1f3
 SHA512:
-  metadata.gz: f8799f782713ae01ca312506c39ef2bed3a56448fb0b4e78d4c75a441b4a3fbac731a5bcf3f23421f9b240e84346f80028bd4545c8edbc14b4ed67769e92e3ef
-  data.tar.gz: 23ce3eab9360b27dd23732589dc3794bb6c6c8cfe6ca9bf289830265ad8697ce0a2779836c0b4ff37c2a5c3211dffaaf74e817e63d0bc96417ad62af8048e444
+  metadata.gz: 87cb708335cfae465b142633dc829c92ac16c4d9d958807cbb682caf455ca18e2b13a24ad30b1bb3020f3493b6dd924151269eb37ba2eaeb09508d5b350a9572
+  data.tar.gz: 04fcd5259c6fe2b1d06f289254817fc1baee73e5d7c7d2aee3476a2155e02e2cb4c40c02deab4285a602bbe9c51806a3e90c5f15ed2b3de928ca9843b0f9fd14

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+### 0.2.0
+
+* Added passkeys/debug_login functionality.
+
 ### 0.1.7
 
 * Added IntegrationHelpers to support client testing.

data/README.md

@@ -4,7 +4,7 @@
 
 # PasskeysRails
 
-Devise is awesome, but we don't need all that UI/UX for 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.
 
@@ -177,12 +177,237 @@ end
 
 ### Mobile Application Integration
 
-**TODO**: Describe the APIs and point to the soon-to-be-created reference mobile applications for how to use **passkeys-rails** for passkey authentication.
+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)
+}
+```
+
+#### POST /passkeys/challenge
+
+Submit this to begin registration or authentication.
+
+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.
+
+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
 
-Contact me if you'd like to contribute time, energy, etc. to this project.
+### 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/passkeys_rails/passkeys_controller.rb

@@ -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
@@ -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/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/passkeys-rails.rb

@@ -45,6 +45,12 @@ 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

data/lib/passkeys_rails/version.rb

@@ -1,3 +1,3 @@
 module PasskeysRails
-  VERSION = "0.1.7".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.7
+  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