shithub Public

Watch 1 Fork 0 Star 0
markdown · 2431 bytes Raw Blame History

Two-factor authentication

Two-factor authentication (2FA) requires a second proof — beyond your password — before you can sign in. shithub supports TOTP (Time-based One-Time Password): six-digit codes from an authenticator app that change every 30 seconds.

Strongly recommended. Account takeover is the most common bad outcome on a forge; a stolen password by itself can't sign in if 2FA is on.

Setting up TOTP

  1. Settings → Account security → Two-factor authentication → "Enable TOTP".
  2. Open your authenticator (Google Authenticator, 1Password, Authy, etc.) and scan the QR code. The text-form secret is shown beneath the QR if your app needs it.
  3. Enter the six-digit code from the app to confirm enrollment.
  4. Save the recovery codes that appear. There are 10. Each is single-use. Store them somewhere your authenticator-device loss won't take with it (password manager, paper safe).

You're now enrolled. The next sign-in will ask for the code after the password.

Recovery codes

If you lose your authenticator (phone died, factory reset, etc.), recovery codes are your way back in.

  • Each code works once.
  • Used codes are crossed off — you can see which are spent.
  • When you have ≤2 unused codes left, the UI nudges you to regenerate. Regenerating invalidates all previous codes.

If you exhaust all 10 codes, the only path back in is operator intervention — they cannot give you your codes back, but they can disable 2FA on the account after verifying your identity through a side channel.

Disabling 2FA

Settings → Account security → "Disable TOTP". Requires entering the current TOTP code.

This is recorded in your audit log. If you didn't disable 2FA, treat that audit row as evidence of compromise and rotate everything (password, all PATs, all SSH keys).

Sign-in flow with 2FA

  1. Username + password.
  2. If correct, you're prompted for the six-digit code (or "use a recovery code").
  3. Code accepted → signed in.

What 2FA does and doesn't protect

  • Protects against stolen passwords (phishing, leaked-DB reuse, shoulder-surfing).
  • Does not protect against stolen sessions — once you're signed in, the session cookie is the access. Use "Sign out everywhere" if a device is lost.
  • Does not protect PAT-based git or API access — PATs are separate credentials; rotate them on the same cadence as passwords.
View source
1 # Two-factor authentication
2
3 Two-factor authentication (2FA) requires a second proof — beyond
4 your password — before you can sign in. shithub supports
5 **TOTP** (Time-based One-Time Password): six-digit codes from an
6 authenticator app that change every 30 seconds.
7
8 Strongly recommended. Account takeover is the most common bad
9 outcome on a forge; a stolen password by itself can't sign in if
10 2FA is on.
11
12 ## Setting up TOTP
13
14 1. Settings → Account security → Two-factor authentication →
15 "Enable TOTP".
16 2. Open your authenticator (Google Authenticator, 1Password,
17 Authy, etc.) and scan the QR code. The text-form secret is
18 shown beneath the QR if your app needs it.
19 3. Enter the six-digit code from the app to confirm enrollment.
20 4. **Save the recovery codes** that appear. There are 10. Each is
21 single-use. Store them somewhere your authenticator-device
22 loss won't take with it (password manager, paper safe).
23
24 You're now enrolled. The next sign-in will ask for the code after
25 the password.
26
27 ## Recovery codes
28
29 If you lose your authenticator (phone died, factory reset, etc.),
30 recovery codes are your way back in.
31
32 - Each code works **once**.
33 - Used codes are crossed off — you can see which are spent.
34 - When you have ≤2 unused codes left, the UI nudges you to
35 regenerate. Regenerating invalidates all previous codes.
36
37 If you exhaust all 10 codes, the only path back in is operator
38 intervention — they cannot give you your codes back, but they can
39 disable 2FA on the account after verifying your identity through
40 a side channel.
41
42 ## Disabling 2FA
43
44 Settings → Account security → "Disable TOTP". Requires entering
45 the current TOTP code.
46
47 This is recorded in your audit log. If you didn't disable 2FA,
48 treat that audit row as evidence of compromise and rotate
49 everything (password, all PATs, all SSH keys).
50
51 ## Sign-in flow with 2FA
52
53 1. Username + password.
54 2. If correct, you're prompted for the six-digit code (or "use a
55 recovery code").
56 3. Code accepted → signed in.
57
58 ## What 2FA does and doesn't protect
59
60 - **Protects against** stolen passwords (phishing, leaked-DB
61 reuse, shoulder-surfing).
62 - **Does not protect against** stolen sessions — once you're
63 signed in, the session cookie is the access. Use "Sign out
64 everywhere" if a device is lost.
65 - **Does not protect** PAT-based git or API access — PATs are
66 separate credentials; rotate them on the same cadence as
67 passwords.