0.2.38: optional two-factor authentication (authenticator-app TOTP)

Per-user opt-in 2FA: enroll from the Two-factor option next to Change
password (QR + confirm code + 8 one-time recovery codes), login becomes
two-step for enrolled users, disable requires the account password.
Escape hatch for lost phones: reset-2fa CLI + Reset Two-Factor StartOS
action. Second-factor guesses share the login rate limiter; the pending
login window expires after 5 minutes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

deploy/startos/actions/index.ts

@@ -177,6 +177,54 @@ const resetPasswordAction = Action.withInput(
   },
 )
 
+// ============================================
+// Action: Reset Two-Factor
+// ============================================
+const resetTwoFactorInputSpec = InputSpec.of({
+  username: Value.text({
+    name: 'Username',
+    description: 'Username of the account whose two-factor should be cleared (lost phone)',
+    default: '',
+    required: true,
+    placeholder: 'admin',
+  }),
+})
+
+const resetTwoFactorAction = Action.withInput(
+  'reset-2fa',
+  {
+    name: 'Reset Two-Factor',
+    description:
+      "Clear a user's two-factor enrollment so they can sign in with just their password (e.g. after losing their authenticator)",
+    warning: null,
+    allowedStatuses: 'only-running',
+    group: null,
+    visibility: 'enabled',
+  },
+  resetTwoFactorInputSpec,
+  async () => ({ username: '' }),
+  async ({ input, effects }) => {
+    try {
+      const result = await runCli(
+        effects,
+        ['reset-2fa', '--username', input.username],
+        'reset-2fa-task',
+      )
+      if (result.exitCode !== 0) {
+        return errorResult(result.stderr?.toString() || 'Failed to reset two-factor')
+      }
+      return {
+        version: '1' as const,
+        title: 'Two-Factor Reset',
+        message: `Two-factor cleared for ${input.username}. They can sign in with their password and re-enroll from the app.`,
+        result: null,
+      }
+    } catch (e: any) {
+      return errorResult(`Failed to reset two-factor: ${e.message || e}`)
+    }
+  },
+)
+
 // ============================================
 // Action: List Users
 // ============================================
@@ -500,6 +548,7 @@ const enableInvestorLoginsAction = Action.withoutInput(
 export const actions = sdk.Actions.of()
   .addAction(createUserAction)
   .addAction(resetPasswordAction)
+  .addAction(resetTwoFactorAction)
   .addAction(showAdminPasswordAction)
   .addAction(listUsersAction)
   .addAction(enableInvestorLoginsAction)

deploy/startos/install/versions/index.ts

@@ -1,4 +1,4 @@
-export { v_0_2_37 as current } from './v_0_2_37'
+export { v_0_2_38 as current } from './v_0_2_38'
 import { v_0_1_0 } from './v_0_1_0'
 import { v_0_2_0 } from './v_0_2_0'
 import { v_0_2_1 } from './v_0_2_1'
@@ -36,4 +36,5 @@ import { v_0_2_33 } from './v_0_2_33'
 import { v_0_2_34 } from './v_0_2_34'
 import { v_0_2_35 } from './v_0_2_35'
 import { v_0_2_36 } from './v_0_2_36'
-export const other = [v_0_1_0, v_0_2_0, v_0_2_1, v_0_2_3, v_0_2_4, v_0_2_5, v_0_2_6, v_0_2_7, v_0_2_8, v_0_2_9, v_0_2_10, v_0_2_11, v_0_2_12, v_0_2_13, v_0_2_14, v_0_2_15, v_0_2_16, v_0_2_17, v_0_2_18, v_0_2_19, v_0_2_20, v_0_2_21, v_0_2_22, v_0_2_23, v_0_2_24, v_0_2_25, v_0_2_26, v_0_2_27, v_0_2_28, v_0_2_29, v_0_2_30, v_0_2_31, v_0_2_32, v_0_2_33, v_0_2_34, v_0_2_35, v_0_2_36]
+import { v_0_2_37 } from './v_0_2_37'
+export const other = [v_0_1_0, v_0_2_0, v_0_2_1, v_0_2_3, v_0_2_4, v_0_2_5, v_0_2_6, v_0_2_7, v_0_2_8, v_0_2_9, v_0_2_10, v_0_2_11, v_0_2_12, v_0_2_13, v_0_2_14, v_0_2_15, v_0_2_16, v_0_2_17, v_0_2_18, v_0_2_19, v_0_2_20, v_0_2_21, v_0_2_22, v_0_2_23, v_0_2_24, v_0_2_25, v_0_2_26, v_0_2_27, v_0_2_28, v_0_2_29, v_0_2_30, v_0_2_31, v_0_2_32, v_0_2_33, v_0_2_34, v_0_2_35, v_0_2_36, v_0_2_37]

deploy/startos/install/versions/v_0_2_38.ts

@@ -0,0 +1,13 @@
+import { VersionInfo } from '@start9labs/start-sdk'
+
+export const v_0_2_38 = VersionInfo.of({
+  version: '0.2.38:0',
+  releaseNotes: {
+    en_US:
+      'Two-factor authentication (optional, per user): enroll an authenticator app from the "Two-factor" option next to Change password; sign-in then asks for a 6-digit code. One-time recovery codes are issued at enrollment, and a new "Reset Two-Factor" action clears a lost enrollment so the user can sign in with just their password.',
+  },
+  migrations: {
+    up: async ({ effects }) => {},
+    down: async ({ effects }) => {},
+  },
+})