Skip to content

Two-factor sign-in (TOTP and recovery codes) - #19

Open
Skyfuller1303 wants to merge 45 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:two-factor
Open

Skyfuller1303 wants to merge 45 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:two-factor

Conversation

@Skyfuller1303

@Skyfuller1303 Skyfuller1303 commented Nov 4, 2026 •

Copy link
Copy Markdown

Builds on #18 (security audit log), #17 (admin API) and #14 (device sessions); please review those first. This branch contains their commits until they are merged.

What

An optional second factor per account: TOTP (RFC 6238: HMAC-SHA-1, 6 digits, 30 s) with 10 one-time recovery codes. It covers the server, the agent and its local API, the app client and the desktop app.

Server

Sign-in and join

  • With two-factor on, POST /auth/login answers 401 two_factor_required with two_factor: {challenge, expires_ms} and issues no token. POST /auth/login/second-factor with the challenge and a totp_code or recovery_code finishes the sign-in.
    • A challenge lives 5 minutes and allows 5 tries. It is stored only as a hash, bound to the account, and dies with a password change, a reset, a disable or a change of the second factor.
  • Redeeming an invite or a reset code of such an account at /join needs totp_code or recovery_code. The code is not used up until the factor is right.
    • A valid pairing code stays authorized by the signed-in device that made it.
    • A reset code issued with reset_two_factor removes the second factor instead.

Account routes

  • /account/two-factor: status, setup, confirm, disable and recovery-codes.
  • A wrong password or code on these signed-in routes answers 403, never 401.
  • Turning two-factor on or off signs every other device out.

Replay and lock-out

  • A TOTP time step is accepted once, and after that only a later step is. This is shared by sign-in, join, disable and admin confirmations.
  • A recovery code is used up atomically.
  • Wrong proofs are counted in the transaction that checked them, under the account's row lock. 10 in a row lock the second factor for 15 minutes, doubling up to 24 h, never permanently. user reset-2fa <name> lifts the lock.
  • When a join limiter refuses, every code gets the same answer, so the limiter can't be used to probe codes.

Secrets at rest

  • The TOTP secret is stored only as AES-256-GCM ciphertext bound to the account, with a key from [two_factor] key_file.
  • init creates the key file; the server never does.
  • If the database holds secrets, the server opens all of them at start and refuses to start when the key is missing or wrong.
  • Rotation: set key_file to the new key and key_file_old to the old one, restart every instance, then run craft-cloud-server two-factor rekey. It rewrites each account's secrets under its lock and reports success only when nothing is left under the old key.

Admin API

  • Confirmations take totp_code or recovery_code when the acting admin has two-factor.
  • New route POST /admin/users/{id}/reset-two-factor.
  • reset_two_factor on password reset codes.
  • Resetting another admin needs the acting admin's own second factor.
  • The user list shows two_factor_enabled.

Audit log

These changes write their events in their own transaction:

  • account.two_factor_enabled, account.two_factor_disabled and account.recovery_codes_regenerated;
  • auth.recovery_code_used;
  • admin.two_factor_reset and cli.two_factor_reset;
  • auth.login on both sign-in paths (not when a challenge is issued);
  • join.reset_redeemed with two_factor_removed.

auth.second_factor_failed (aggregated per account and minute) and auth.two_factor_locked are written best-effort after the counters commit, so a failure of the log never weakens the lock-out. Wrong proofs on signed-in routes are not logged one by one; only a lock is.

Migration and errors

  • One migration for SQLite and Postgres (0010, after the audit log's 0009).
  • New error codes: two_factor_required, two_factor_invalid, two_factor_unavailable, two_factor_pending and two_factor_locked (429 with Retry-After).

Agent, local API and app

  • The agent finishes the second step at sign-in and join. It keeps the challenge only in memory.
  • The agent never treats a 403 two_factor_invalid or wrong_password as a revoked device.
  • It passes Retry-After on.
  • Local routes: /v1/account/two-factor… and the second step. Secrets are never stored or logged, and Debug is redacted.
  • craft-cloud-app gets the matching blocking calls and an error that carries the challenge and the retry delay (from the JSON or the Retry-After header).

Desktop

  • A Security page: turn two-factor on (QR code and secret), recovery codes shown once, turn it off, new recovery codes, change the password, sign other computers out.
  • A code step when a sign-in or join asks for it.
  • Every password and code field drops egui's undo history when it is sent, cancelled or left.

Dependencies

aes-gcm 0.10 is new (pure Rust, Apache-2.0 OR MIT, with its RustCrypto dependencies). hmac, sha1, subtle and zeroize were already locked as transitive dependencies and become direct. cargo xtask licenses: all crates on the allow-list.

Rollout

  1. Server first.
  2. Then the desktop package with its matching agent.
  3. Then standalone agents.

Older agents show every 401 at sign-in as "wrong password", so an account with two-factor can't sign in with them. The migration can't be rolled back. Back up the key file separately from database backups: without it, the second factors can't be read.

Testing

  • cargo fmt --all -- --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo xtask licenses
  • cargo test on SQLite for meta, server, api, proto and app
  • desktop lib tests (--test-threads=1)
  • agent two_factor, local_api and end_to_end
  • Postgres 17: meta with CRAFT_CLOUD_REQUIRE_BACKENDS=1, and the server's API and CLI tests with CRAFT_CLOUD_TEST_PG, disk store
  • MSRV 1.94 cargo check of meta, server, proto and api
  • RFC 6238 and 4226 test vectors.
  • Races on both databases, repeated with no flakes:
    • parallel wrong proofs count exactly 5 per challenge and lock for exactly 15 minutes;
    • step replay;
    • double completion makes one device;
    • a confirmation racing rekey, forced to overlap.
  • Key fail-closed and rekey tests.
  • Injected audit faults: every in-transaction change fails cleanly, and the lock still holds.
  • A log test that no secret reaches the logs, and kittest tests that no secret stays in egui's undo history.

Not tested

Left open

  • The desktop admin pages that forward a second factor come in the desktop admin PR.
  • user remove still has no audit writer.

Skyfuller1303 and others added 30 commits November 4, 2026 00:04
Migration 0007 gives a device its client kind, platform and app version
and, once revoked, the time and the reason, and gives a user the time of
the last password change (plus a disabled time nothing reads yet). All
of it is additive, BIGINT on Postgres, and the flag stays the check.

Meta gets create_device_with and redeem_with, rename_device,
revoke_device_as, revoke_other_devices, revoke_all_devices, account,
change_password and reset_password. Flag, time and reason are set
together and only by the first revoke. A password change or reset sets
the hash, revokes the devices and deletes the account's invite and
pairings in one transaction.

Tests run on both databases, including the migration from 0006.

Co-Authored-By: Claude <noreply@anthropic.com>
New: GET /account, POST /account/password, PATCH /devices/{id} and
POST /devices/revoke-others. Sign-in and join take an optional client
kind, platform and app version, checked before a try is counted. The
device list shows them with the time and reason of a revoke; all new
fields are optional on the wire.

Changing the password answers a wrong current password with 403
wrong_password, never 401, since the agent reads every 401 on a
signed-in route as a revoked device. It is limited to five tries per
account in 15 minutes, takes a password-check slot, and ends the revoked
devices' live connections at once. Password and name bodies are read up
to the new TINY_JSON_BYTES (4 KiB).

wrong_password and forbidden move into the shared error codes; the local
API refers to them. The agent, app and desktop only change where they
build the extended types.

Co-Authored-By: Claude <noreply@anthropic.com>
user reset-password now revokes every device of the account (reason
reset) and deletes its open invite and pairings, so a stolen token does
not outlive the old password. --keep-devices restores the old behaviour
for the devices. device revoke-all signs out an account's devices
without touching the password. Both print how many devices they ended;
device revoke records the admin as the reason.

Co-Authored-By: Claude <noreply@anthropic.com>
The API table and error codes in the design document, the password and
sign-out commands, the live-connection delay of the command line and the
rollout note (an older server refuses the newer database) in the
server guide.

Co-Authored-By: Claude <noreply@anthropic.com>
…evice

A /changes long-poll that was waiting when its device was signed out
through the API now ends at once, and one that wakes for any other reason
looks the device up again before it answers, so a device signed out by
the command line gets 401 instead of the next change set.

The live endpoint listens for revocations and looks the device up before
the upgrade, so a revoke between the sign-in check and the subscription
is not missed.

Co-Authored-By: Claude <noreply@anthropic.com>
change_password checks, inside its transaction, that the calling device
is still signed in (it may have been revoked while the password was
hashed) and answers 401 if not. A password that changed meanwhile is now
409 conflict instead of 400 invalid. Both are new MetaError variants
mapped in the server.

set_password_hash had no caller outside a test and is removed. A new test
breaks the pairing deletes with a trigger and checks that a password
change, an admin reset and a revoke-others undo everything on SQLite and
Postgres.

Co-Authored-By: Claude <noreply@anthropic.com>
The long-poll now listens for revocations and looks its device up before
it waits, so a revoke between the sign-in check and the wait is not
missed, and looks it up once more after the change set is fetched, as
the last step before the answer, so a revoke during the fetch is not
answered with changes.

Co-Authored-By: Claude <noreply@anthropic.com>
…changes a password

change_password locked the caller's device row and then the user's row,
while revoke_other_devices from another device locked its own device and
then the user's, and reset_password locked the user before the devices.
On Postgres two of them at once could deadlock and fail with a database
error. All of them now take the user's row first (a no-op update), then
the devices, then the pairings.

A new scenario runs password changes, sign-outs and an admin reset at the
same moment, over and over, on both databases and expects only successes,
conflicts and signed-out callers. The test trigger helper also drops its
Postgres function.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
…-in adds a device

redeem consumed the invite and then updated the user, while a password
reset locks the user and then deletes the invite, so the two could
deadlock on Postgres. redeem now finds the invite or pairing with a plain
read, locks the account, and consumes the code again under the lock; a
code that is gone by then is invalid_code. create_pairing locks the
account first too.

A password sign-in verified the password outside any transaction, so a
reset or change that committed meanwhile could be followed by a new
device. sign_in_device locks the account and compares the stored hash
again before it creates the device; if it differs, login answers as for
a wrong password.

New scenarios run redeems, a sign-in, a pairing and a reset at the same
moment on both databases and expect no database error and no live device
once the reset is done.

Co-Authored-By: Claude <noreply@anthropic.com>
The invite delete and the pairing update now name the account the plain
read found, so a code hash removed and made again for another account
between that read and the lock is refused as invalid_code instead of
adding a device to the wrong account.

Co-Authored-By: Claude <noreply@anthropic.com>
The admin API's server overview shows whether blobs are on disk, in S3 or in memory. A backend that does not say is reported as other, so nothing outside the store crate has to change.

Co-Authored-By: Claude <noreply@anthropic.com>
New request and answer types for the routes under /api/v1/admin, with a redacting Debug for everything that holds a password or a code, and the error codes account_disabled and last_admin. The confirmation is a body with an optional password today, so an optional totp_code can join it later without breaking a client.

Co-Authored-By: Claude <noreply@anthropic.com>
Migration 0008 adds the purpose of an invite (invite or reset), a quota per space and a removal mark per user. The new Meta methods for the admin API each re-check the acting admin inside their own transaction and take the locks in one order, with a transaction-wide lock before the last-admin count. Disabled accounts are refused by the token check, sign-in, redeem, pairing and device creation, decided under the account's row lock. A reset code always sets a new password, signs every device out and then signs the redeeming computer in. A space's quota replaces the server-wide cap in the preflight check and in the count that follows.

Co-Authored-By: Claude <noreply@anthropic.com>
The require_admin layer and the routes under /api/v1/admin: counters, a paged and searchable user list, creating accounts, changing role and quota, disabling, enabling and removing, invites, password reset codes and a user's devices. Every change asks for the acting admin's password in its body. Sign-in and join answer account_disabled for a disabled account, and a redeemed reset code ends the live connections of the devices it signed out. Documents the API, the confirmation and the rollout in the design document and the server guide.

Co-Authored-By: Claude <noreply@anthropic.com>
Limiter::count added the attempt before comparing it with the maximum, so tries refused at the limit still raised the count. A refund of an attempt that had been accepted at the same moment then left the key above its limit with fewer wrong passwords than allowed. A refused try now leaves the count alone.

Co-Authored-By: Claude <noreply@anthropic.com>
Disabling and enabling an account leaves the password hash as it was, so a sign-in that verified the password before the disable could still create a usable device after the enable. Users get an auth_gen counter (migration 0008) that a disable, an enable, a removal and every password change or reset bump. The sign-in reads it with the hash and sign_in_device compares both under the account's lock. The server's refunds test covers the limiter change.

Co-Authored-By: Claude <noreply@anthropic.com>
The typed details of a security event, an event, a page of them and the last line of the NDJSON export. Every
field of the details is a closed list of words or a number, and fields a later release adds are ignored.

Co-Authored-By: Claude <noreply@anthropic.com>
Migration 0009 adds audit_events, with no foreign keys so that an event outlives its account. Every change that the
log names writes its event in its own transaction before the commit, so a change whose event cannot be written is
not made. A change that changes nothing writes none. A failed sign-in is one row per account and minute whose
counter goes up, written in a transaction of its own. The values of an event are typed and come from closed
lists, never from what a client typed. Old events are pruned in batches outside those transactions.

Meta methods that had no way to say who asked get one: revoke_device_by takes the origin, and admin_enable_user and
admin_revoke_invite take the time.

Co-Authored-By: Claude <noreply@anthropic.com>
GET /account/activity, GET /admin/audit and the streamed GET /admin/audit/export; a failed sign-in is written
after the answer is decided and never changes it. [audit] retention_days (1 to 3650, default 365) and
audit list and audit prune on the command line. The export reads fixed pages through a bounded channel up to a
fixed end of the log and ends with a line that says complete or truncated, or breaks the connection.

Co-Authored-By: Claude <noreply@anthropic.com>
The routes and events in the design, and the retention, the personal data and the upgrade note in the server guide.

Co-Authored-By: Claude <noreply@anthropic.com>
…in the export, reword the append-only note

The account's own activity no longer shows the details (the device an admin signed out, roles, counts) of an event about another
account, which a former administrator would otherwise keep seeing. The export validates before_ms like the list and applies it
to every page and the probe besides its fixed end. The docs now say the append-only choice is a design decision, not that SQLite
has no triggers.

Co-Authored-By: Claude <noreply@anthropic.com>
aes-gcm 0.10.3 (MIT OR Apache-2.0, pure Rust) seals the stored TOTP secrets.
hmac 0.13, sha1 0.11, subtle 2.6 and zeroize 1.9 were in the lockfile already
as transitive packages and become direct dependencies of the server: HMAC-SHA-1
makes the codes authenticator apps speak, subtle compares them in constant
time, zeroize wipes secrets. The server's tests also turn on its own
test-support feature, to move its clock.

Co-Authored-By: Claude <noreply@anthropic.com>
Migration 0009 adds the secret and recovery-code tables, the sign-in
challenges and the invites' reset_two_factor flag. Everything that issues a
device or uses a proof up locks the account's row first and checks again, under
the lock, the device, the password hash, auth_gen, the account's current
two-factor state and the challenge. A time step is accepted once and only a
later one after it, a recovery code once, and a wrong proof is counted in a
transaction of its own after the refused one rolled back, so the counters
survive; ten in a row lock the second factor for 15 minutes, doubling up to 24
hours. Turning it on, off or resetting it ends what an earlier check let through
(auth_gen, challenges, invite, pairings, devices). Redeeming an invite or reset
code of an account that has it takes the second factor in the same
transaction; the admin's reset of another account's two-factor sign-in, the
reset_two_factor flag of reset codes and the admin's own two-factor state are
part of the admin changes.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Routes under /account/two-factor (status, setup, confirm, disable, recovery
codes), POST /auth/login/second-factor, a second factor on /join, a code on the
admin API's confirmations (one time step serves one change), POST
/admin/users/{id}/reset-two-factor and reset_two_factor on password-reset codes.
Resetting another admin's password or two-factor sign-in takes the acting
admin's own.

The secret is sealed with AES-256-GCM bound to the account (secretbox.rs) under
the key from [two_factor] key_file, which init makes and serve never does; serve
opens every stored secret at start and refuses to run when the key is missing or
one does not open. Rotation is key_file_old plus two-factor rekey. user
reset-2fa takes it away on the command line. TOTP (RFC 6238) is in totp.rs with
the RFC vectors.

Co-Authored-By: Claude <noreply@anthropic.com>
…ation

Co-Authored-By: Claude <noreply@anthropic.com>
…e secrets fresh per account

A wrong proof was counted after its transaction rolled back and released the
account's lock, so requests that waited for it checked a stale challenge and a
stale lock: more than five checks per challenge, and parallel failures could
jump the first lock from 15 to 30 minutes. Every check now runs before anything
is consumed (join checks the second factor before it deletes the invite), so
the refusing transaction commits the counters itself, still under the lock.

two_factor_rewrite reads an account's active and set-up ciphertexts fresh under
its lock and rewrites both; two_factor_all_secrets lists everything for the
final scan of rekey. join_code_locked_for lets the join route report a lock.

Co-Authored-By: Claude <noreply@anthropic.com>
…ock win at join

rekey no longer works from a snapshot: a confirmation that moves a set-up's
secret to the active one between the scan and the update was left under the old
key while the command said the old key could go. It now rewrites both
ciphertexts of an account under its lock, scans again, and fails unless nothing
is under another key. The join route reports an active two-factor lock (429
two_factor_locked with Retry-After) instead of the limiter's answer when the
code belongs to such an account. The key's name no longer claims to be unique.

Co-Authored-By: Claude <noreply@anthropic.com>
Skyfuller1303 and others added 11 commits November 4, 2026 11:24
…e key's name is

Co-Authored-By: Claude <noreply@anthropic.com>
…ce in its test

When a join limiter refuses, the answer is now the same for every code (429
rate_limited with Retry-After from the limiter's window), so it no longer tells a
guesser whether a code is real or its account locked; the lock is told only to a
request the limiters let through. The rekey test now holds rekey between its scan
and its rewrite (rekey_hooked) until the confirmations have committed, and checks
the first successful rekey instead of repairing with a second run.

Co-Authored-By: Claude <noreply@anthropic.com>
…lenge and the app client's methods

The local API gets the second step of a sign-in (/v1/login/second-factor), the
account's two-factor calls passed on to the server, the password change, other
computers and device rename, and a second factor on /v1/join. A refusal's
challenge and wait (ErrorExtras) reach the app as Error::RefusedWith, so code that
matches Error::Refused keeps working. The wire types the app needs move from
proto to api, which proto re-exports.

Co-Authored-By: Claude <noreply@anthropic.com>
…unt's two-factor calls

The agent keeps the server's refusals whole in a type of its own (CallError), so
a wrong code, a wrong password or a lock is never read as a revoked device while
a real 401 still is; sync's TransportError is unchanged. login and join prompt for
the code on standard input (three tries, a lock says how long to wait), the local
API passes the challenge and the wait on typed, and every new route has its own
small body limit.

Co-Authored-By: Claude <noreply@anthropic.com>
The signed-in view gets a Security button. The page shows the account's two-factor
status, sets it up (password, then the secret with a QR code and the first code),
shows the recovery codes once, turns it off, makes new codes, changes the password
and signs the other computers out. A join for an account with two-factor sign-in
asks for the code (or a recovery code) and sends the same join again with it.
Secrets live in the page's step only, are dropped when it is left, and are redacted
in Debug. The signed-in snapshots change by the new button.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
…etry-After header

The password and code fields of the Security page and of the join's second step get stable
ids, and every frame the egui state of each such field is dropped unless the model holds
text typed in it, so once a secret was sent, a step cancelled or the page left, Undo can't
bring it back. A kittest test types, sends, cancels and leaves, reopens and presses Ctrl+Z.

The local client keeps an answer's Retry-After header and uses it for the wait of a refusal
when the JSON has no retry_after_secs.

Co-Authored-By: Claude <noreply@anthropic.com>
Turning two-factor sign-in on and off, new recovery codes, a recovery code's use, an admin's and the command line's
reset, and auth.login on both successful sign-in paths are written in the transaction of the change, so an error in the
log fails the change. The wrong second step of a sign-in or a join is aggregated and written after the answer is decided,
and the lock's event after the counters and the lock are committed, so a fault in the log neither undoes the lock nor
changes an answer. A reset code that removes two-factor sign-in says so (two_factor_removed) on join.reset_redeemed, by
the account that redeemed it. Wrong proofs on signed-in routes are not written one by one.

Co-Authored-By: Claude <noreply@anthropic.com>
…ctor events over HTTP

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
The server (device sessions) shows a device's client_kind, platform and
app_version in the device list, but the agent never sent them. Every
sign-in and join of the agent now says it is an agent, which operating
system it runs on and its own version, cut to the server's 32-byte limit.
A server-backed test checks that the device list shows them after both.
Conflicts in apps/craft-cloud-agent/src/http.rs: join_over_with keeps the second
factor fields and now also sends the device details. The first step of a
two-factor sign-in (login_step_over) sends them too; the server keeps them in
the challenge, so the second-factor request needs none.
Skyfuller1303 added a commit to Skyfuller1303/craft-cloud that referenced this pull request Nov 7, 2026
The Security page tests (from itrycodinganditsbad#19) built their kittest harness with
.wgpu(), a new wgpu device per test, which crashed the test process with
STATUS_ACCESS_VIOLATION when run in parallel on Windows, like the other UI
tests did before itrycodinganditsbad#35. Use the shared device from itrycodinganditsbad#35 here too.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant