ShipRust
Sign inStart my project

Documentation

Two-factor authentication

Generated projects let users add an authenticator app as a second step when signing in with a password.

Authenticator apps, included

Every generated project ships two-factor authentication with any TOTP authenticator app (1Password, Google Authenticator, Authy and the like), with no Cargo feature to choose and nothing to configure. A signed-in user opens Account settings, confirms their password, scans a server-rendered QR code or types the key by hand, and enters one code to turn it on. They are shown eight single-use recovery codes exactly once.

From then on, signing in with the password stops at a code prompt before any session exists. A correct authenticator code or an unused recovery code completes the sign-in; five wrong codes send the user back to the password form. Passkey sign-in skips the prompt, because a passkey already proves a device and a biometric or PIN. Regenerating recovery codes and turning the feature off both require the current password. shiprust.com itself offers the same in account settings.

How it is built

  • Codes follow RFC 6238: HMAC-SHA1 through ring (already in every ShipRust binary for passkeys), six digits, 30-second steps, one step of drift either way, and each code accepted at most once.
  • The secret is created server side, shown only on the enrolment page after a password check, and counts only once a code has proven the app works.
  • Recovery codes are stored as SHA-256 hashes and burned on use. Between password and code the browser holds a random challenge token in an HttpOnly, SameSite=Strict cookie; the server stores its hash, allows five attempts and forgets it after ten minutes.
  • The QR code is inline SVG from the qrcode crate with no default features, so generated projects gain no image or rendering stack.

The arithmetic and storage live in the shared shiprust-auth crate (totp.rs and two_factor.rs, with the RFC test vectors as unit tests), the handlers in app/src/two_factor.rs and the pages in app/src/views/two_factor.rs. Integration tests enrol an account, sign in with codes and recovery codes, exhaust the attempts and turn it off again. The generated project's docs include a Two-factor authentication guide with the details.