From 06667fc104bc5eeba0fa929884717bec2d06b553 Mon Sep 17 00:00:00 2001 From: Adam Fowler Date: Thu, 9 Oct 2025 12:44:52 +0100 Subject: [PATCH 1/3] Add TOTP example documentation --- .../Examples/OTPAuthenticationExample.md | 49 +++++++++++++++++++ .../HummingbirdOTP/OneTimePasswords.md | 3 +- Hummingbird.docc/index.md | 4 ++ 3 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 Hummingbird.docc/Examples/OTPAuthenticationExample.md diff --git a/Hummingbird.docc/Examples/OTPAuthenticationExample.md b/Hummingbird.docc/Examples/OTPAuthenticationExample.md new file mode 100644 index 0000000000..cb0d86cf11 --- /dev/null +++ b/Hummingbird.docc/Examples/OTPAuthenticationExample.md @@ -0,0 +1,49 @@ +# OTP Authentication Example + +Example demonstrating how to setup one time passwords, using sessions. + +> The source code for this example can be found [here](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp) + +This example starts with a standard username/password login. There is a link to a signup screen where you can enter your name, email and password. When you return to the login screen you can use your email and password to access the main page. On the main page is a button to add an OTP token to your account. This links to a page consisting of a QR code generated from the OTP secret and a text input for you to verify your OTP password generation is correct. Use Apple Passwords or Google Authenticator to scan the QR code. Once verified you are allowed to press the button that adds the OTP secret to your account. From this point on when you login you will also be requested for your one time password. + +## Database + +`PostgresNIO` and ``PostgresMigrations`` are used in this example to access and store your persistent data. The demo creates two tables and an index. +- Table `users` with columns `id`, `name`, `email`, `passwordHash` +- Table `totp` with columns `user_id` and `secret` +- Index for `email` in table `users` + +You can find the migrations for these in the [Migrations folder](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Migrations). These are added to the migration list in the `buildApplication` function. We need to apply these migrations before the server starts but after the PostgresClient connection manager background process has started. This can be done by calling the ``/PostgresMigrations/DatabaseMigrations/apply(client:groups:logger:dryRun:)`` function inside a closure sent to ``/Hummingbird/Application/beforeServerStarts(perform:)``. + +On top of the two tables created, the example uses the postgres driver ``/HummingbirdPostgres/PostgresPersistDriver`` for the persist framework to store session keys. You will find out more about the persist framework at and there is a guide to the migration support in . + +There is a docker-compose file available to run a local Postgres database. + +## Walkthrough + +### Controllers + +The example has three controllers +- [`UserController`](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Controllers/UserController.swift): API for completing user creation/login/logout +- [`WebController`](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Controllers/WebController.swift): The app uses ``/Hummingbird/FileMiddleware`` to serve most web pages but this controller is used to create the dynamic main web page. +- [`TOTPController`](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Controllers/TOTPController.swift): API for starting, verifying and completing TOTP creation. + +### Authentication + +For authentication purposes the example uses ``/HummingbirdBasicAuth/BasicAuthenticator`` to provide a standard username/password login and ``/HummingbirdAuth/SessionAuthenticator`` for authenticating based off a session id. Both of these require a repository type that defines how to access a user based off either a username or session identifier. We create a protocol [`UserRepository`](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Repositories/UserRepository.swift) for the repository and conform it to the relevant protocols to be used with the basic and session authenticator middleware. And then we implement a concrete version of this protocol that uses `PostgresNIO`. + +To use the `SessionAuthenticator` we need to add the ``/HummingbirdAuth/SessionMiddleware``. This extracts session id from the request and responds with `set-cookie` headers if the session needs updated. The session middleware converts the session id into an associated session type. In the case of this example the session type consists of two possible authentication states, either `authenticated` or `challenge`. The only challenge available is the TOTP. A user is only considered to be authenticated is the session state is `authenticated`. + +To convert the session state from `challenge` to `authenticated` we have included a [`TOTPMiddleware`](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Middleware/TOTPMiddleware.swift). This will extract the TOTP token from the request headers and then compare it to the TOTP tokens generated by ``/HummingbirdOTP/TOTP``. If one of them is equal then we change the session state to `authenticated`. + +### RequestContexts + +This example uses multiple ``/Hummingbird/RequestContext``. If starts with ``/Hummingbird/BasicRequestContext`` which provides the functionality for a basic Hummingbird application, but does not support authentication or sessions. When we call any route that requires authentication or sessions we convert this context to a [`AppSessionRequestContext`](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/RequestContext.swift). This conversion is done using ``/Hummingbird/RouterMethods/group(_:context:)-w6fz`` which creates a new ``/Hummingbird/RouterGroup`` using the new `AppSessionRequestContext`. + +And then in routes that require an authenticated state we have added conversion to an `AuthenticatedRequestContext` which requires an authenticated identity. This means those routes don't need to check the authenticated state they are provided with a non-optional identity. + +You can find out more about `RequestContext` transformations in . + +### Dynamic HTML + +The `WebController` generates dynamic content for the logged in screen. It uses ``Mustache`` to render the content. The mustache templates are stored in the [Resources](https://github.com/hummingbird-project/hummingbird-examples/tree/main/auth-otp/Sources/App/Resources) folder in the App. The templates are loaded at initialization using `Bundle.module.resourcePath`. \ No newline at end of file diff --git a/Hummingbird.docc/HummingbirdOTP/OneTimePasswords.md b/Hummingbird.docc/HummingbirdOTP/OneTimePasswords.md index 204189164e..3c03978a7e 100644 --- a/Hummingbird.docc/HummingbirdOTP/OneTimePasswords.md +++ b/Hummingbird.docc/HummingbirdOTP/OneTimePasswords.md @@ -41,4 +41,5 @@ Compare it with the password provided by the user to verify the user credentials ## See Also - ``HummingbirdOTP/TOTP`` -- ``HummingbirdOTP/HOTP`` \ No newline at end of file +- ``HummingbirdOTP/HOTP`` +- \ No newline at end of file diff --git a/Hummingbird.docc/index.md b/Hummingbird.docc/index.md index 57edcbbbe9..93dc638980 100644 --- a/Hummingbird.docc/index.md +++ b/Hummingbird.docc/index.md @@ -77,6 +77,10 @@ Below is a list of guides and tutorials to help you get started with building yo - - +### Examples + +- + ### Reference Documentation - ``/Hummingbird`` From 37cd75a93af97fa3a8bf715a97ca694deec3c3a2 Mon Sep 17 00:00:00 2001 From: Adam Fowler Date: Thu, 9 Oct 2025 12:58:12 +0100 Subject: [PATCH 2/3] Minor update to OTP example docs --- Hummingbird.docc/Examples/OTPAuthenticationExample.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Hummingbird.docc/Examples/OTPAuthenticationExample.md b/Hummingbird.docc/Examples/OTPAuthenticationExample.md index cb0d86cf11..e201047512 100644 --- a/Hummingbird.docc/Examples/OTPAuthenticationExample.md +++ b/Hummingbird.docc/Examples/OTPAuthenticationExample.md @@ -46,4 +46,4 @@ You can find out more about `RequestContext` transformations in Date: Thu, 9 Oct 2025 17:13:50 +0100 Subject: [PATCH 3/3] Add docker compose up --- Hummingbird.docc/Examples/OTPAuthenticationExample.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Hummingbird.docc/Examples/OTPAuthenticationExample.md b/Hummingbird.docc/Examples/OTPAuthenticationExample.md index e201047512..d88362621d 100644 --- a/Hummingbird.docc/Examples/OTPAuthenticationExample.md +++ b/Hummingbird.docc/Examples/OTPAuthenticationExample.md @@ -17,7 +17,11 @@ You can find the migrations for these in the [Migrations folder](https://github. On top of the two tables created, the example uses the postgres driver ``/HummingbirdPostgres/PostgresPersistDriver`` for the persist framework to store session keys. You will find out more about the persist framework at and there is a guide to the migration support in . -There is a docker-compose file available to run a local Postgres database. +There is a docker-compose file available to run a local Postgres database. You can run the Postgres database using + +``` +docker compose up +``` ## Walkthrough