rodauth-openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ce74f8234f280f924c119e914ee31e88ee7714ccd10770626de4034edcac7da
+  data.tar.gz: 42f9cd22c79d36a6ae06e4703ce80a0da926908e5bd72f4eeb0a77644db1cf68
+SHA512:
+  metadata.gz: e3797f271d6735174e03beda40c98f2392a338d295dcb15d06d323d52cc8828a1b0c654d798a8c3380039759a7eb769f8c9747ad4a7f0678a0f293e07eaa16de
+  data.tar.gz: bbdd36a6a8ab3d499b4f2af8487291111084e7a51851ef3e5463b861a6118922a20d217e2f5e56c185ca74e8f2a2b01b50d9694cbebd1f6312bf51cb18316b84

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Janko Marohnić
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Rodauth OpenAPI
+
+Generates [OpenAPI] documentation for your Rodauth endpoints.
+
+## Installation
+
+```sh
+bundle add rodauth-openapi --group development
+```
+
+## Usage
+
+The generated OpenAPI documentation can be uploaded to renderers such as [Swagger Editor] or [Redoc].
+
+### Rails
+
+Assuming you have Rodauth installed in your Rails application, you can use the generator provided by this gem:
+
+```sh
+rails g rodauth:openapi
+```
+
+This will generate OpenAPI documentation in YAML format for the default Rodauth configuration and print it to standard output.
+
+The generator accepts the following options:
+
+```sh
+rails g rodauth:openapi --name admin # secondary configuration
+rails g rodauth:openapi --format json # JSON format
+rails g rodauth:openapi --json # generate JSON API endpoints
+rails g rodauth:openapi --no-password # assume account without password
+rails g rodauth:openapi --save openapi.yml # save to a file
+```
+
+### Outside of Rails
+
+If you're not using Rails, you can generate the OpenAPI documentation programmatically:
+
+```rb
+require "rodauth/openapi"
+
+auth_class = RodauthApp.rodauth # or RodauthApp.rodauth(:admin)
+open_api = Rodauth::OpenAPI.new(auth_class)
+
+File.write("openapi.yml", open_api.to_yaml)
+```
+
+To generate JSON API endpoints:
+
+```rb
+Roduath::OpenAPI.new(auth_class, json: true)
+```
+
+To assume the account doesn't have a password:
+
+```rb
+Roduath::OpenAPI.new(auth_class, password: false)
+```
+
+To generate the documentation in JSON format:
+
+```rb
+Roduath::OpenAPI.new(auth_class).to_json
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Rodauth::Openapi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/janko/rodauth-openapi/blob/main/CODE_OF_CONDUCT.md).
+
+[OpenAPI]: https://swagger.io/specification/
+[Swagger Editor]: https://editor.swagger.io/
+[Redoc]: https://redocly.github.io/redoc/

data/lib/generators/rodauth/openapi_generator.rb

@@ -0,0 +1,46 @@
+require "rodauth/openapi"
+require "rails/generators"
+
+module Rodauth
+  module Generators
+    class OpenAPIGenerator < ::Rails::Generators::Base
+      namespace "rodauth:openapi"
+
+      class_option :password, type: :boolean, default: true,
+        desc: "Whether to assume the account has a password"
+
+      class_option :json, type: :boolean,
+        desc: "Whether to generate JSON API documentation"
+
+      class_option :name, type: :string, default: nil,
+        desc: "The configuration name for which to generate documentation"
+
+      class_option :format, type: :string, default: "yaml",
+        desc: "The format to output the documentation in (yaml, json)"
+
+      class_option :save, type: :string, default: nil,
+        desc: "File to save the documentation to (by default prints to stdout)"
+
+      def print_documentation
+        open_api = Rodauth::OpenAPI.new(auth_class, password: options[:password], json: options[:json])
+        documentation = open_api.public_send(:"to_#{options[:format]}")
+
+        if options[:save]
+          File.write(options[:save], documentation)
+        else
+          puts documentation
+        end
+      end
+
+      private
+
+      def auth_class
+        Rodauth::Rails.app.rodauth!(configuration_name)
+      end
+
+      def configuration_name
+        options[:name]&.to_sym
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/change_login.rb

@@ -0,0 +1,27 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :change_login, "Change Login" do
+      get :change_login, "View login change page" do
+        redirect_error_response :login_required, "login required"
+
+        html_response "login change form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+
+      post :change_login, "Perform login change" do
+        param :password, "Current account password", type: :password, required: true if rodauth.change_login_requires_password?
+        param :login, "Email to set", type: :email, required: true
+        param :login_confirm, "Email confirmation", type: :email, required: true if rodauth.require_login_confirmation?
+
+        error_response :invalid_password, "invalid password" if rodauth.change_login_requires_password?
+        error_response :invalid_field, "login does not meet requirements"
+        error_response :unmatched_field, "logins do not match" if rodauth.require_login_confirmation?
+        error_response :invalid_field, "same as current login"
+        error_response :invalid_field, "already an account with this login"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/change_password.rb

@@ -0,0 +1,25 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :change_password, "Change Password" do
+      get :change_password, "View change password page" do
+        html_response "change password form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+
+      post :change_password, "Perform password change" do
+        param :password, "Current account password", type: :password, example: "oldsecret123", required: true if rodauth.change_password_requires_password?
+        param :new_password, "Password to set", type: :password, example: "newsecret123", required: true
+        param :password_confirm, "Password confirmation", type: :password, example: "newsecret123", required: true if rodauth.require_password_confirmation?
+
+        success_response "successful password change"
+        error_response :invalid_password, "invalid previous password" if rodauth.change_password_requires_password?
+        error_response :invalid_field, "same as existing password"
+        error_response :invalid_field, "invalid password"
+        error_response :unmatched_field, "passwords do not match" if rodauth.require_password_confirmation?
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/close_account.rb

@@ -0,0 +1,20 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :close_account, "Close Account" do
+      get :close_account, "View close account page" do
+        html_response "close account form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+
+      post :close_account, "Perform closing account" do
+        param :password, "Current account password", type: :password, required: true if rodauth.close_account_requires_password?
+
+        success_response "account successfully closed"
+        error_response :invalid_password, "invalid password" if rodauth.close_account_requires_password?
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/confirm_account.rb

@@ -0,0 +1,18 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :confirm_password, "Confirm Password" do
+      get :confirm_password, "View password confirmation page" do
+        html_response "password confirmation form"
+        redirect_error_response :login_required, "login required"
+      end
+
+      post :confirm_password, "Perform password confirmation" do
+        param :password, "Current account password", type: :password, required: true
+
+        success_response "password successfully confirmed"
+        error_response :invalid_password, "invalid password"
+        redirect_error_response :login_required, "login required"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/create_account.rb

@@ -0,0 +1,22 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :create_account, "Create Account" do
+      get :create_account, "View registration page" do
+        html_response "registration form"
+      end
+
+      post :create_account, "Perform registration" do
+        param :login, "Email address for the account", type: :email, required: true
+        param :login_confirm, "Email address confirmation", type: :email, required: true if rodauth.require_login_confirmation?
+        param :password, "Password to set", type: :password, required: true if rodauth.create_account_set_password?
+        param :password_confirm, "Password confirmation", type: :password, required: true if rodauth.create_account_set_password? && rodauth.require_password_confirmation?
+
+        success_response "successful registration"
+        error_response :invalid_field, "invalid login"
+        error_response :unmatched_field, "logins do not match" if rodauth.require_login_confirmation?
+        error_response :invalid_field, "invalid password" if rodauth.create_account_set_password?
+        error_response :unmatched_field, "passwords do not match" if rodauth.create_account_set_password? && rodauth.require_password_confirmation?
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/email_auth.rb

@@ -0,0 +1,28 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :email_auth, "Email Authentication" do
+      post :email_auth_request, "Perform email authentication request" do
+        param :login, "Email address for the account", type: :email, required: true
+
+        success_response "successfully sent email authentication email"
+        redirect_error_response :no_matching_login, "no matching login"
+        redirect_error_response "email recently sent"
+      end
+
+      get :email_auth, "View email authentication page" do
+        param :email_auth_key, "Email authentication token", type: :token, required: true
+
+        response 302, "token stored in session"
+        html_response "email authentication form"
+        redirect_error_response "invalid email authentication key"
+      end
+
+      post :email_auth, "Perform email authentication" do
+        param :email_auth_key, "Email authentication token", type: :token, required: json
+
+        success_response "successful email authentication"
+        redirect_error_response :invalid_key, "invalid email authentication key"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/jwt_refresh.rb

@@ -0,0 +1,13 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :jwt_refresh, "JWT Refresh" do
+      post :jwt_refresh, "Refresh JWT access token" do
+        param :jwt_refresh_token_key, "JWT refresh token", type: :string, required: true
+
+        json_response({ rodauth.jwt_refresh_token_key => "...", rodauth.jwt_access_token_key => "..." })
+        error_response rodauth.jwt_refresh_without_access_token_status, "no JWT access token provided"
+        error_response "invalid JWT refresh token"
+      end if json
+    end
+  end
+end

data/lib/rodauth/openapi/routes/lockout.rb

@@ -0,0 +1,30 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :lockout, "Lockout" do
+      post :unlock_account_request, "Perform account unlock request" do
+        param :login, "Email address for the account", type: :email, required: true
+
+        success_response "successfully sent unlock account email"
+        error_response :no_matching_login, "no matching login"
+        redirect_error_response "email recently sent"
+      end
+
+      get :unlock_account, "View account unlock page" do
+        param :unlock_account_key, "Account unlock token", type: :token, required: true
+
+        response 302, "token stored in session"
+        html_response "account unlock form"
+        redirect_error_response "invalid or expired unlock account key"
+      end
+
+      post :unlock_account, "Perform account unlock" do
+        param :unlock_account_key, "Account unlock token", type: :token, required: json
+        param :password, "Current account password", type: :password, required: true if rodauth.unlock_account_requires_password?
+
+        success_response "account successfully unlocked"
+        redirect_error_response :invalid_key, "invalid or expired unlock account key"
+        error_response :invalid_password, "invalid password" if rodauth.unlock_account_requires_password?
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/login.rb

@@ -0,0 +1,20 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :login, "Login" do
+      get :login, "View Login page" do
+        html_response "login form"
+      end
+
+      post :login, "Perform login" do
+        param :login, "Email address for the account", type: :email, required: true
+        param :password, "Password for the account", type: :password, required: !rodauth.use_multi_phase_login?
+
+        success_response "successful login"
+        error_response :no_matching_login, "no matching login"
+        error_response :unopen_account, "unverified account"
+        error_response :lockout, "account locked out" if feature?(:lockout)
+        error_response :login, "invalid password"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/logout.rb

@@ -0,0 +1,16 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :logout, "Logout" do
+      get :logout, "View logout page" do
+        html_response "logout form"
+      end
+
+      post :logout, "Perform logout" do
+        param :global_logout, "Whether to logout all active sessions", type: :boolean if feature?(:active_sessions)
+        param :jwt_refresh_token_key, "JWT refresh token to delete (\"all\" deletes all tokens)", type: :string if feature?(:jwt_refresh)
+
+        success_response "successful logout"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/otp.rb

@@ -0,0 +1,75 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :otp, "OTP" do
+      get :otp_auth, "View TOTP authentication page" do
+        html_response "TOTP authentication form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via TOTP"
+        redirect_error_response :two_factor_not_setup, "TOTP not setup"
+        redirect_error_response :lockout, "TOTP locked out"
+      end
+
+      post :otp_auth, "Perform TOTP authentication" do
+        param :otp_auth, "TOTP code", type: :string, required: true
+
+        success_response "successfully authenticated via TOTP"
+        error_response :invalid_key, "invalid TOTP code"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via TOTP"
+        redirect_error_response :two_factor_not_setup, "TOTP not setup"
+        redirect_error_response :lockout, "TOTP locked out"
+      end
+
+      get :otp_setup, "View TOTP setup page" do
+        html_response "TOTP setup form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response "TOTP already setup"
+      end
+
+      post :otp_setup, "Perform TOTP setup" do
+        if json
+          description <<~MARKDOWN
+            In JSON mode, if TOTP secret wasn't provided (and HMACs are used), the response will include a valid TOTP secret that can be included in the subsequent setup request:
+            ```json
+            {
+              "#{rodauth.otp_setup_param}": "...",
+              "#{rodauth.otp_setup_raw_param}": "..."
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :otp_setup, "TOTP secret", type: :string, required: true
+        param :otp_setup_raw, "TOTP raw secret", type: :string, required: true if rodauth.otp_keys_use_hmac?
+        param :otp_auth, "TOTP code", type: :string, required: true
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "TOTP successfully setup"
+        error_response :invalid_field, "invalid TOTP secret"
+        error_response :invalid_password, "invalid password" if rodauth.two_factor_modifications_require_password?
+        error_response :invalid_key, "Invalid TOTP code"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response "TOTP already setup"
+      end
+
+      get :otp_disable, "View TOTP disable page" do
+        success_response "TOTP disable form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "TOTP not setup"
+      end
+
+      post :otp_disable, "Perform TOTP disable" do
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "TOTP successfully disabled"
+        error_response :invalid_password, "invalid password" if rodauth.two_factor_modifications_require_password?
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "TOTP not setup"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/otp_unlock.rb

@@ -0,0 +1,38 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :otp_unlock, "OTP Unlock" do
+      get :otp_unlock, "View TOTP unlock page" do
+        html_response "TOTP unlock form"
+        redirect_error_response :otp_unlock_not_locked_out, "TOTP not locked out"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "TOTP not setup"
+      end
+
+      post :otp_unlock, "Perform TOTP unlock step" do
+        if json
+          description <<~MARKDOWN
+            In JSON mode, the response of TOTP unlock steps will include progress information:
+            ```json
+            {
+              "num_successes": 2,
+              "required_successes": 3,
+              "next_attempt_after": 1728512721,
+              "deadline": 1728512769
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :otp_auth, "TOTP code", type: :string, required: true
+
+        success_response "TOTP authentication successful, TOTP successfully unlocked"
+        error_response :otp_unlock_auth_failure, "TOTP code invalid"
+        redirect_error_response :otp_unlock_auth_deadline_passed, "TOTP unlock deadline passed"
+        redirect_error_response :otp_unlock_auth_not_yet_available, "TOTP unlock not yet available"
+        redirect_error_response :otp_unlock_not_locked_out, "TOTP not locked out"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "TOTP not setup"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/recovery_codes.rb

@@ -0,0 +1,45 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :recovery_codes, "Recovery Codes" do
+      get :recovery_auth, "View recovery code authentication page" do
+        html_response "recovery code authentication form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via recovery code"
+      end
+
+      post :recovery_auth, "Authenticate via recovery code" do
+        param :recovery_codes, "Recovery code", type: :string, required: true
+
+        success_response "successfully authenticated via recovery code"
+        error_response :invalid_key, "invalid recovery code"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via recovery code"
+      end
+
+      get :recovery_codes, "View recovery codes page" do
+        html_response "recovery codes form"
+
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+
+      post :recovery_codes, "See recovery codes" do
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+        param :add_recovery_codes, "Whether to create missing recovery codes", type: :boolean
+
+        if json
+          json_response("available recovery codes", { "codes": ["..."] })
+        else
+          html_response "displayed recovery codes"
+        end
+        error_response :invalid_password, "invalid password" if rodauth.two_factor_modifications_require_password?
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/remember.rb

@@ -0,0 +1,24 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :remember, "Remember" do
+      get :remember, "View remember settings page" do
+        html_response "remember settings form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+
+      post :remember, "Change remember settings" do
+        param :remember, "Remember action to perform", type: :string, required: true, enum: [
+          rodauth.remember_remember_param_value,
+          rodauth.remember_forget_param_value,
+          rodauth.remember_disable_param_value,
+        ]
+
+        success_response "remember setting successfully changed"
+        error_response :invalid_field, "invalid remember param"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2FA required" if feature?(:two_factor_base)
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/reset_password.rb

@@ -0,0 +1,36 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :reset_password, "Reset Password" do
+      get :reset_password_request, "View password reset request page" do
+        html_response "password reset request form"
+      end
+
+      post :reset_password_request, "Perform password reset request" do
+        param :login, "Email address for the account", type: :email, required: true
+
+        success_response "successfully sent reset password email"
+        error_response :no_matching_login, "no matching login"
+        error_response :unopen_account, "unverified account"
+        redirect_error_response "email recently sent"
+      end
+
+      get :reset_password, "View password reset page" do
+        param :reset_password_key, "Password reset token", type: :token, required: true
+
+        response 302, "token stored in session"
+        html_response "password reset form"
+        redirect_error_response "invalid or expired password reset key"
+      end
+
+      post :reset_password, "Perform password reset" do
+        param :reset_password_key, "Password reset token", type: :token, required: json
+
+        success_response "successfully reset password"
+        redirect_error_response :invalid_key, "invalid or expired password reset key"
+        error_response :invalid_field, "invalid password"
+        error_response :invalid_field, "same as existing password"
+        error_response :unmatched_field, "passwords do no match" if rodauth.require_password_confirmation?
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/sms_codes.rb

@@ -0,0 +1,99 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :sms_codes, "SMS Codes" do
+      get :sms_request, "View SMS code request page" do
+        html_response "SMS code request form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via SMS code"
+        redirect_error_response :two_factor_not_setup, "SMS codes not setup"
+        redirect_error_response :lockout, "SMS codes locked out"
+      end
+
+      post :sms_request, "Request SMS code" do
+        success_response "SMS code successfully sent"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via SMS code"
+        redirect_error_response :two_factor_not_setup, "SMS codes not setup"
+        redirect_error_response :lockout, "SMS codes locked out"
+      end
+
+      get :sms_auth, "View SMS code authentication page" do
+        html_response "SMS code authentication form"
+        redirect_error_response :invalid_key, "no current SMS code"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via SMS code"
+        redirect_error_response :two_factor_not_setup, "SMS codes not setup"
+        redirect_error_response :lockout, "SMS codes locked out"
+      end
+
+      post :sms_auth, "Authenticate via SMS code" do
+        param :sms_code, "SMS code", type: :string, required: true
+
+        success_response "successfully authenticated via SMS code"
+        error_response :invalid_key, "invalid SMS code"
+        redirect_error_response :invalid_key, "no current SMS code"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via SMS code"
+        redirect_error_response :two_factor_not_setup, "SMS codes not setup"
+        redirect_error_response :lockout, "SMS codes locked out"
+      end
+
+      get :sms_setup, "View SMS codes setup page" do
+        html_response "SMS codes setup form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :sms_already_setup, "SMS codes already setup"
+        redirect_error_response :sms_needs_confirmation, "SMS phone number needs confirmation"
+      end
+
+      post :sms_setup, "Setup SMS codes" do
+        param :sms_phone, "SMS phone number", type: :string, required: true
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "SMS codes successfully setup"
+        error_response :invalid_field, "invalid phone number"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :sms_already_setup, "SMS codes already setup"
+        redirect_error_response :sms_needs_confirmation, "SMS phone number needs confirmation"
+      end
+
+      get :sms_confirm, "View SMS phone number confirmation page" do
+        html_response "SMS confirmation form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :sms_already_setup, "SMS codes already setup"
+      end
+
+      post :sms_confirm, "Confirm SMS phone number" do
+        param :sms_code, "SMS code", type: :string, required: true
+
+        success_response "SMS phone number successfully confirmed"
+        error_response :invalid_key, "invalid SMS code"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :sms_already_setup, "SMS codes already setup"
+      end
+
+      get :sms_disable, "View SMS disable page" do
+        html_response "SMS disable form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "SMS codes not setup"
+      end
+
+      post :sms_disable, "Disable SMS codes" do
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "SMS codes successfully disabled"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :two_factor_not_setup, "SMS codes not setup"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/two_factor_base.rb

@@ -0,0 +1,43 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :two_factor_base, "Two Factor Base" do
+      route (json ? :post : :get), :two_factor_manage, "View two factor management page" do
+        if json
+          json_response({ "setup_links": ["..."], "remove_links": ["..."] })
+        else
+          html_response "two factor management page"
+        end
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+
+      route (json ? :post : :get), :two_factor_auth, "View two factor authentication page" do
+        if json
+          json_response({ "auth_links": ["..."] })
+        else
+          html_response "two factor authentication page"
+        end
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :two_factor_already_authenticated, "2nd factor already authenticated"
+      end
+
+      get :two_factor_disable, "View two factor disable page" do
+        html_response "two factor disable page"
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+
+      post :two_factor_disable, "Disable two factor authentication" do
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "2nd factor successfully disabled"
+        error_response :invalid_password, "invalid password" if rodauth.two_factor_modifications_require_password?
+        redirect_error_response :two_factor_not_setup, "2nd factor not setup"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/verify_account.rb

@@ -0,0 +1,59 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :verify_account, "Verify Account" do
+      get :verify_account, "View account verification page" do
+        param :verify_account_key, "Account verification token", type: :token, required: true
+
+        response 302, "token stored in session"
+        if feature?(:webauthn_verify_account)
+          html_response "WebAuthn setup form"
+        else
+          html_response "account verification form"
+        end
+        redirect_error_response "invalid verify account key"
+      end
+
+      post :verify_account, "Perform account verification" do
+        if json && feature?(:webauthn_verify_account)
+          description <<~MARKDOWN
+            In JSON mode, if WebAuthn credential data wasn't provided, input credential params will be returned in the response:
+            ```json
+            {
+              "#{rodauth.webauthn_setup_param}": { ... },
+              "#{rodauth.webauthn_setup_challenge_param}": "...",
+              "#{rodauth.webauthn_setup_challenge_hmac_param}": "..."
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :verify_account_key, "Account verification token", type: :token, required: json
+        param :password, "Password to set", type: :password, required: true if rodauth.verify_account_set_password?
+        param :password_confirm, "Password confirmation", type: :password, required: true if rodauth.verify_account_set_password? && rodauth.require_password_confirmation?
+        if feature?(:webauthn_verify_account)
+          param :webauthn_setup, "WebAuthn credential data", type: :object, required: true
+          param :webauthn_setup_challenge, "WebAuthn credential challenge", type: :string, required: true
+          param :webauthn_setup_challenge_hmac, "WebAuthn credential challenge HMAC", type: :string, required: true
+        end
+
+        success_response "successful account verification"
+        redirect_error_response :invalid_key, "missing or invalid token"
+        error_response :invalid_field, "invalid password" if rodauth.verify_account_set_password?
+        error_response :unmatched_field, "passwords do not match" if rodauth.verify_account_set_password? && rodauth.require_password_confirmation?
+        error_response :invalid_field, "invalid WebAuthn credential data"
+      end
+
+      get :verify_account_resend, "Resend account verification email page" do
+        html_response "resend account verification form"
+      end
+
+      post :verify_account_resend, "Perform resending account verification email" do
+        param :login, "Email address for the account", type: :email, required: true
+
+        success_response "successful resend"
+        redirect_error_response "email recently sent"
+        error_response :no_matching_login, "no matching login"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/verify_login_change.rb

@@ -0,0 +1,21 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :verify_login_change, "Verify Login Change" do
+      get :verify_login_change, "View login change verification page" do
+        param :verify_login_change_key, "Login change verification token", type: :token, required: true
+
+        response 302, "token stored in session"
+        html_response "login change verification form"
+        redirect_error_response "invalid verify login change key"
+      end
+
+      post :verify_login_change, "Perform login change verification" do
+        param :verify_login_change_key, "Login change verification token", type: :token, required: json
+
+        success_response "successfully verified login change"
+        redirect_error_response :invalid_key, "invalid verify login change key"
+        redirect_error_response :invalid_key, "already an account with this login"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/webauthn.rb

@@ -0,0 +1,103 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :webauthn, "WebAuthn" do
+      get :webauthn_auth, "View WebAuthn authentication page" do
+        html_response "WebAuthn authentication form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via WebAuthn"
+        redirect_error_response :webauthn_not_setup, "WebAuthn not setup"
+      end
+
+      post :webauthn_auth, "Perform WebAuthn authentication" do
+        if json
+          description <<~MARKDOWN
+            In JSON mode, if credential data wasn't provided, input credential params will be returned in the response:
+            ```json
+            {
+              "#{rodauth.webauthn_auth_param}": { ... },
+              "#{rodauth.webauthn_auth_challenge_param}": "...",
+              "#{rodauth.webauthn_auth_challenge_hmac_param}": "..."
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :webauthn_auth, "Credential data", type: :object, required: true
+        param :webauthn_auth_challenge, "Credential challenge", type: :string, required: true
+        param :webauthn_auth_challenge_hmac, "Credential challenge HMAC", type: :string, required: true
+
+        success_response "successfully authenticated via WebAuthn"
+        error_response :invalid_key, "invalid credential data"
+        error_response :invalid_field, "invalid credential sign count"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_already_authenticated, "already authenticated via WebAuthn"
+        redirect_error_response :webauthn_not_setup, "WebAuthn not setup"
+      end
+
+      get :webauthn_setup, "View WebAuthn setup page" do
+        html_response "WebAuthn setup form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+
+      post :webauthn_setup, "Perform WebAuthn setup" do
+        if json
+          description <<~MARKDOWN
+            In JSON mode, if credential data wasn't provided, input credential params will be returned in the response:
+            ```json
+            {
+              "#{rodauth.webauthn_setup_param}": { ... },
+              "#{rodauth.webauthn_setup_challenge_param}": "...",
+              "#{rodauth.webauthn_setup_challenge_hmac_param}": "..."
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :webauthn_setup, "Credential data", type: :object, required: true
+        param :webauthn_setup_challenge, "Credential challenge", type: :string, required: true
+        param :webauthn_setup_challenge_hmac, "Credential challenge HMAC", type: :string, required: true
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "WebAuthn successfully setup"
+        error_response :invalid_field, "invalid credential data"
+        error_response :invalid_field, "duplicate credential ID"
+        error_response :invalid_password, "invalid password" if rodauth.two_factor_modifications_require_password?
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+      end
+
+      get :webauthn_remove, "View WebAuthn authenticator removal page" do
+        html_response "WebAuthn authenticator removal form"
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :webauthn_not_setup, "WebAuthn not setup"
+      end
+
+      post :webauthn_remove, "Remove WebAuthn authenticator" do
+        if json
+          description <<~MARKDOWN
+            In JSON mode, if credential ID wasn't provided, last usage of every credential will be returned in the response:
+            ```json
+            {
+              "#{rodauth.webauthn_remove_param}": {
+                "abc123": "2024-10-10 00:37:10 UTC"
+              }
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :webauthn_remove, "Credential ID", type: :string, required: true
+        param :password, "Current account password", type: :password, required: true if rodauth.two_factor_modifications_require_password?
+
+        success_response "WebAuthn authenticator successfully removed"
+        error_response :invalid_field, "invalid credential ID"
+        error_response :invalid_password, "invalid password" if rodauth.two_factor_modifications_require_password?
+        redirect_error_response :login_required, "login required"
+        redirect_error_response :two_factor_need_authentication, "2nd factor required"
+        redirect_error_response :webauthn_not_setup, "WebAuthn not setup"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes/webauthn_login.rb

@@ -0,0 +1,29 @@
+module Rodauth
+  class OpenAPI
+    Routes.define :webauthn_login, "WebAuthn Login" do
+      post :webauthn_login, "Perform WebAuthn login" do
+        if json
+          description <<~MARKDOWN
+            In JSON mode, if credential data wasn't provided, input credential params will be returned in the response:
+            ```json
+            {
+              "#{rodauth.webauthn_auth_param}": { ... },
+              "#{rodauth.webauthn_auth_challenge_param}": "...",
+              "#{rodauth.webauthn_auth_challenge_hmac_param}": "..."
+            }
+            ```
+          MARKDOWN
+        end
+
+        param :login, "Account email", type: :email, required: !feature?(:webauthn_autofill)
+        param :webauthn_auth, "Credential data", type: :object, required: true
+
+        success_response "successfully logged in via WebAuthn"
+        error_response :invalid_key, "invalid credential data"
+        error_response :invalid_field, "invalid credential sign count"
+        error_response :invalid_field, "credential not found" if feature?(:webauthn_autofill)
+        error_response :no_matching_login, "no matching login"
+      end
+    end
+  end
+end

data/lib/rodauth/openapi/routes.rb

@@ -0,0 +1,129 @@
+module Rodauth
+  class OpenAPI
+    class Routes
+      FEATURES = {}
+
+      def self.define(name, tag, &definition)
+        FEATURES[name] = -> do
+          section tag, name
+          instance_exec(&definition)
+        end
+      end
+
+      attr_reader :data, :rodauth, :json
+
+      def initialize(data, rodauth:, json:)
+        @data = data
+        @rodauth = rodauth
+        @json = json
+      end
+
+      def section(tag, name)
+        data[:tags] << {
+          name: tag,
+          externalDocs: {
+            description: "Feature documentation",
+            url: "http://rodauth.jeremyevans.net/rdoc/files/doc/#{name}_rdoc.html"
+          }
+        }
+      end
+
+      def get(...)
+        route(:get, ...) unless json
+      end
+
+      def post(...)
+        route(:post, ...)
+      end
+
+      def route(verb, name, summary, &block)
+        path = rodauth.send(:"#{name}_path")
+        return if path.nil?
+
+        tag = data[:tags].last[:name]
+
+        data[:paths][path] ||= {}
+        data[:paths][path][verb] = {
+          tags: [tag],
+          summary: summary,
+          responses: {},
+          parameters: [],
+        }
+
+        instance_exec(&block)
+      end
+
+      def description(text)
+        data[:paths].values.last.values.last[:description] = text
+      end
+
+      def param(name, description, type:, example: nil, required: false, enum: nil)
+        example ||= case type
+        when :email then "user@example.com"
+        when :password then "secret123"
+        when :boolean then "true"
+        when :token then "{account_id}#{rodauth.token_separator}{key_hmac}"
+        end
+
+        parameters = data[:paths].values.last.values.last[:parameters]
+        parameters << {
+          name: rodauth.send(:"#{name}_param"),
+          in: "query",
+          description: description,
+          required: required,
+          style: "form",
+          example: example,
+          schema: { type: type == :boolean ? "boolean" : "string", enum: enum }.compact,
+        }.compact
+      end
+
+      def html_response(description)
+        response(200, description)
+      end
+
+      def json_response(description = "", example)
+        response(200, description, content: { "application/json" => { example: example } })
+      end
+
+      def success_response(description)
+        status = json ? 200 : 302
+        response(status, description)
+      end
+
+      def error_response(status = nil, description)
+        status = rodauth.send(:"#{status}_error_status") if status.is_a?(Symbol)
+        if json && (status.nil? || !rodauth.json_response_custom_error_status?)
+          status = rodauth.json_response_error_status
+        end
+        response(status, description)
+      end
+
+      def redirect_error_response(name = nil, description)
+        status = if json
+          if rodauth.json_response_custom_error_status? && name
+            rodauth.send(:"#{name}_error_status")
+          else
+            rodauth.json_response_error_status
+          end
+        else
+          302
+        end
+        response(status, description)
+      end
+
+      def response(status, description = "", **fields)
+        responses = data[:paths].values.last.values.last[:responses]
+        if responses[status]
+          responses[status][:description] = [responses[status][:description], description].join(", ")
+        else
+          responses[status] = { description: description }
+        end
+        responses[status].merge!(fields)
+      end
+
+      def feature?(name)
+        rodauth.features.include?(name)
+      end
+    end
+  end
+end

data/lib/rodauth/openapi.rb

@@ -0,0 +1,79 @@
+require "yaml"
+require "json"
+require "rodauth/version"
+require "rodauth/openapi/routes"
+
+module Rodauth
+  class OpenAPI
+    DOCS_URL = "https://rodauth.jeremyevans.net/documentation.html"
+    SPEC_VERSION = "3.0.1"
+
+    def initialize(auth_class, json: nil, password: true)
+      @auth_class = auth_class
+      @json = json
+      @password = password
+    end
+
+    def to_yaml
+      YAML.dump(JSON.parse(JSON.generate(generate))).lines[1..-1].join
+    end
+
+    def to_json
+      JSON.pretty_generate(generate)
+    end
+
+    def generate
+      data = {
+        openapi: SPEC_VERSION,
+        info: {
+          title: "Rodauth",
+          description: "This lists all the endpoints provided by Rodauth features.",
+          version: Rodauth::VERSION,
+        },
+        externalDocs: {
+          description: "Rodauth documentation",
+          url: DOCS_URL,
+        },
+        tags: [],
+        paths: {},
+      }
+
+      rodauth.features.each do |feature|
+        begin
+          require "rodauth/openapi/routes/#{feature}"
+        rescue LoadError
+          next
+        end
+
+        routes = Routes.new(data, rodauth: rodauth, json: json?)
+        routes.instance_exec(&Routes::FEATURES[feature])
+      end
+
+      # remove tags that don't have any routes
+      all_tags = data[:paths].values.flat_map(&:values).flat_map { |route| route[:tags] }.uniq
+      data[:tags].select! { |tag| all_tags.include?(tag[:name]) }
+
+      data
+    end
+
+    private
+
+    def json?
+      @json || rodauth.only_json?
+    end
+
+    def rodauth
+      rodauth = @auth_class.new(scope)
+      rodauth.instance_variable_set(:@has_password, password?)
+      rodauth
+    end
+
+    def password?
+      @password
+    end
+
+    def scope
+      @auth_class.roda_class.new({ "rack.session" => {} })
+    end
+  end
+end

data/lib/rodauth-openapi.rb

@@ -0,0 +1 @@
+require "rodauth/openapi"

data/rodauth-openapi.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |spec|
+  spec.name          = "rodauth-openapi"
+  spec.version       = "0.1.0"
+  spec.authors       = ["Janko Marohnić"]
+  spec.email         = ["janko.marohnic@gmail.com"]
+
+  spec.summary       = %q{Allows dynamically generating OpenAPI documentation based on Rodauth configuration.}
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/janko/rodauth-openapi"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 2.5"
+
+  spec.files         = Dir["README.md", "LICENSE.txt", "lib/**/*", "*.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rodauth"
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: rodauth-openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Janko Marohnić
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rodauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows dynamically generating OpenAPI documentation based on Rodauth
+  configuration.
+email:
+- janko.marohnic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/rodauth/openapi_generator.rb
+- lib/rodauth-openapi.rb
+- lib/rodauth/openapi.rb
+- lib/rodauth/openapi/routes.rb
+- lib/rodauth/openapi/routes/change_login.rb
+- lib/rodauth/openapi/routes/change_password.rb
+- lib/rodauth/openapi/routes/close_account.rb
+- lib/rodauth/openapi/routes/confirm_account.rb
+- lib/rodauth/openapi/routes/create_account.rb
+- lib/rodauth/openapi/routes/email_auth.rb
+- lib/rodauth/openapi/routes/jwt_refresh.rb
+- lib/rodauth/openapi/routes/lockout.rb
+- lib/rodauth/openapi/routes/login.rb
+- lib/rodauth/openapi/routes/logout.rb
+- lib/rodauth/openapi/routes/otp.rb
+- lib/rodauth/openapi/routes/otp_unlock.rb
+- lib/rodauth/openapi/routes/recovery_codes.rb
+- lib/rodauth/openapi/routes/remember.rb
+- lib/rodauth/openapi/routes/reset_password.rb
+- lib/rodauth/openapi/routes/sms_codes.rb
+- lib/rodauth/openapi/routes/two_factor_base.rb
+- lib/rodauth/openapi/routes/verify_account.rb
+- lib/rodauth/openapi/routes/verify_login_change.rb
+- lib/rodauth/openapi/routes/webauthn.rb
+- lib/rodauth/openapi/routes/webauthn_login.rb
+- rodauth-openapi.gemspec
+homepage: https://github.com/janko/rodauth-openapi
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Allows dynamically generating OpenAPI documentation based on Rodauth configuration.
+test_files: []