Skip to content

Two-factor sign-in with an authenticator app - #24

Merged
ssenerg merged 1 commit into
mainfrom
two-factor
Oct 25, 2026
Merged

ssenerg merged 1 commit into
mainfrom
two-factor

Conversation

@ssenerg

@ssenerg ssenerg commented Oct 25, 2026

Copy link
Copy Markdown
Owner

Stacked on #23 (folder sharing), which is stacked on #22 (chunked WebDAV uploads). Merge #22, then #23, then this one.

What it does

  • Two-factor sign-in in the account menu (/.auth/two-factor). Setup:
    • the user scans a QR code, or types the key, into any authenticator app;
    • then enters the code it shows to turn it on.
    • That signs them out everywhere else and shows 10 recovery codes once.
  • Signing in asks for a code after the password, on a second step. A recovery code works there too.
    • After a recovery code, the user lands on the two-factor page, which says how many are left.
  • Recovery codes and turning it off both take the password.
  • Superadmins turn it off for someone who lost their app and codes: a lock button on Users, where those users are marked two-factor. The CLI does the same with goftp user two-factor-off NAME.
  • Scripts can do all of this:
    • POST /.auth/login with "code";
    • or answer its 401 {"two_factor":true,"challenge":"…"} with {"challenge","code"};
    • POST /.auth/two-factor with action=start|confirm|codes|off, answered in JSON.
  • App passwords (WebDAV) are unchanged: each is already per app and revocable.

How it works

  • TOTP follows RFC 6238, written here (HMAC-SHA1, 30 s, 6 digits), and is checked against the RFC's test vectors.
    • Codes are accepted one step early or late.
    • The last used step is stored and updated atomically (totp_step < $2), so no code works twice, even in two parallel sign-ins.
  • Setup keeps the new secret as pending in the database until a code of it arrives. A cross-site or replayed form can't swap in another secret.
  • The second step uses an in-memory challenge (5 minutes, 5 tries, at most 10,000 open), so the password isn't posted twice. Wrong codes count against the client's existing failure budget.
  • Storage:
    • Recovery codes are 10 base32 characters (50 bits); only their SHA-256 is stored, and each is deleted when used.
    • The TOTP secret has to be stored as is. The README notes this.
  • New dependency: rsc.io/qr (BSD, pure Go), only to encode the QR code, which is drawn as inline SVG.
  • Migration 010 adds users.totp_secret, totp_pending, totp_step and the recovery_codes table.

Tests

  • internal/auth/twofactor_test.go, on both the memory and Postgres stores:
    • the RFC test vectors;
    • setup: wrong code, confirm, sign-out everywhere;
    • the challenge flow and replay;
    • recovery codes, once each and case-insensitive;
    • the 5-try limit;
    • new codes and turning off, both needing the password;
    • the admin reset.
  • internal/server/twofactor_test.go:
    • the page and the QR;
    • the HTML two-step sign-in and its errors;
    • the recovery-code redirect and notice;
    • the JSON flows;
    • new codes, turning off, superadmin reset and logging;
    • wrong codes using up the client's budget.
  • CLI test for two-factor-off.
  • Full suite passes on Linux (Docker) and with -race + Postgres on macOS (except the known macOS-only TestLongNonASCIIPath).
  • Checked in a browser against a local server:
    • the setup page, with the QR read by the browser's barcode detector back to the right otpauth:// URI;
    • turning it on with a real code;
    • the recovery codes view;
    • the code step at sign-in, which signed in.

🤖 Generated with Claude Code

Users can turn on two-factor sign-in under Two-factor sign-in in their
account menu: they add a secret to an authenticator app by QR code or
by hand, and confirm it with a code (TOTP, RFC 6238, implemented here).
That signs them out everywhere else and shows ten recovery codes once,
each good for one sign-in. Signing in then asks for a code after the
password; a sign-in waits for it five minutes, five tries at most, and
wrong codes count against the client's budget. No code works twice.

Scripts send the code with the password, or answer the challenge the
login returns. Turning it off and making new recovery codes take the
password. Superadmins, or goftp user two-factor-off, turn it off for
someone who lost their app. App passwords are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssenerg
ssenerg changed the base branch from home-sharing to main October 25, 2026 14:44
@ssenerg
ssenerg merged commit 55708e8 into main Oct 25, 2026
4 checks passed
@ssenerg
ssenerg deleted the two-factor branch October 25, 2026 14:58
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