feat(FR-2616): handle totp and concurrent-session inline in STokenLoginBoundary

- STokenLoginError gains `totp-required` (with `invalidOtp` hint); the
  existing `concurrent-session` kind is now wired up end-to-end.
- `tokenLogin` helper throws a structured `TokenLoginFailedError` instead
  of a generic `Error`, fixing a latent bug where a `{ fail_reason }`
  return value (truthy object) was treated as success by the caller.
- `STokenLoginBoundary` keeps a pending OTP ref (single-use) and a sticky
  `forceApprovedRef`; both fold into `extraParams` on the next retry.
- `DefaultErrorCard` swaps its action area in place for `totp-required`
  (OTP input + Submit) and `concurrent-session` (Copy details + Sign in
  anyway) — no separate modal, no layout split. Card status shifts from
  `error` to `warning` for these two kinds so the user reads them as
  required follow-ups, not terminal failures.
- Classification uses duck-typed field extraction instead of
  `instanceof TokenLoginFailedError` so cross-module-instance errors
  (Jest mocks, HMR reloads) classify the same.
- TODO(user-tunable): once `client.token_login` surfaces the probe
  `type`, replace the string-matching classifier with `type`
  comparisons. The current substrings mirror LoginView's legacy
  fallback.

Author: nowgnuesLee

react/src/components/STokenLoginBoundary.tsx

@@ -19,7 +19,7 @@ import {
 import { useResolvedApiEndpoint } from '../hooks/useResolvedApiEndpoint';
 import { loginConfigState } from '../hooks/useWebUIConfig';
 import { jotaiStore } from './DefaultProviders';
-import { App, Spin, Typography } from 'antd';
+import { App, Form, Input, Spin, Typography } from 'antd';
 import { BAIButton, BAICard, BAIFlex, useBAILogger } from 'backend.ai-ui';
 import { useAtomValue } from 'jotai';
 import {
@@ -42,9 +42,86 @@ export type STokenLoginError =
   | { kind: 'endpoint-unresolved'; cause?: unknown }
   | { kind: 'server-unreachable'; cause: unknown }
   | { kind: 'token-invalid'; cause: unknown }
+  /**
+   * Webserver responded `require-totp-authentication` (or the equivalent
+   * legacy detail string). The default error card swaps its action area
+   * for an inline OTP input; submitting retries `token_login` with
+   * `{ otp }` folded into `extraParams`. `invalidOtp` is set true when the
+   * retry itself returned a TOTP rejection, so the card can show an
+   * invalid-code hint above the input without re-classifying the error.
+   */
+  | { kind: 'totp-required'; cause: unknown; invalidOtp?: boolean }
+  /**
+   * Webserver reported an existing active session for this user
+   * (`active-login-session-exists`). The default error card swaps its
+   * action area for a "terminate previous session?" confirm pair;
+   * confirming retries `token_login` with `force: true` folded into
+   * `extraParams` (sticky for subsequent retries within the same mount,
+   * mirroring LoginView's `forceLoginApprovedRef`).
+   */
   | { kind: 'concurrent-session'; cause: unknown }
   | { kind: 'unknown'; cause: unknown };
 
+/**
+ * Classify a `tokenLogin` failure into the appropriate `STokenLoginError`
+ * kind.
+ *
+ * Uses duck-typed extraction (not `instanceof TokenLoginFailedError`) so
+ * that error objects crossing module boundaries — e.g. Jest mocked
+ * imports, or HMR where two copies of the helper module coexist —
+ * classify the same as direct throws.
+ *
+ * TODO(user-tunable): once `client.token_login` surfaces the authenticated
+ * probe `type` (see `TokenLoginFailedError.failType`), replace the
+ * substring checks with strict `type` comparisons. The substrings below
+ * are copied verbatim from `LoginView.handleLoginError`'s legacy fallback
+ * so the two code paths classify identically until the structured type
+ * plumbing lands.
+ */
+const classifyTokenLoginFailure = (
+  err: unknown,
+  submittedOtp: string | null,
+): STokenLoginError => {
+  const bag =
+    typeof err === 'object' && err !== null
+      ? (err as Record<string, unknown>)
+      : {};
+  const failReason =
+    typeof bag.failReason === 'string'
+      ? bag.failReason
+      : typeof (err as Error | undefined)?.message === 'string'
+        ? (err as Error).message
+        : '';
+  const failType = typeof bag.failType === 'string' ? bag.failType : '';
+  const needle = `${failType}\n${failReason}`;
+
+  const isTotpRequired =
+    needle.includes('require-totp-authentication') ||
+    needle.includes('You must authenticate using Two-Factor Authentication') ||
+    needle.includes('OTP not provided');
+  const isInvalidTotp =
+    needle.includes('Invalid TOTP code provided') ||
+    needle.includes('Failed to validate OTP');
+  if (isTotpRequired || isInvalidTotp) {
+    return {
+      kind: 'totp-required',
+      cause: err,
+      // If we submitted an OTP and the server still rejected with a TOTP
+      // signal, the code must have been wrong. Surface the invalid hint.
+      invalidOtp: !!submittedOtp && (isInvalidTotp || isTotpRequired),
+    };
+  }
+
+  if (
+    needle.includes('active-login-session-exists') ||
+    needle.includes('existing active login session')
+  ) {
+    return { kind: 'concurrent-session', cause: err };
+  }
+
+  return { kind: 'token-invalid', cause: err };
+};
+
 export interface STokenLoginBoundaryProps {
   /**
    * Canonical sToken value sourced by the caller via nuqs. Required — the
@@ -135,6 +212,15 @@ const STokenLoginBoundaryInner: React.FC<STokenLoginBoundaryProps> = ({
   // most once per successful login; downstream subscribers (Relay, plugin
   // endpoint wiring) assume idempotency does not hold for them.
   const eventDispatchedRef = useRef(false);
+  // OTP pending submission for the next retry, if any. Cleared once the
+  // retry sequence reads it — TOTP codes are single-use and should not be
+  // replayed silently on an unrelated retry.
+  const pendingOtpRef = useRef<string | null>(null);
+  // Sticky force-login approval: once the user confirms "terminate previous
+  // session", every subsequent retry in this mount includes `force: true`
+  // (mirrors LoginView's `forceLoginApprovedRef` so a TOTP challenge that
+  // follows a force approval does not silently drop the force flag).
+  const forceApprovedRef = useRef(false);
 
   const surfaceError = useEffectEvent((error: STokenLoginError) => {
     setPhase({ name: 'error', error });
@@ -195,6 +281,17 @@ const STokenLoginBoundaryInner: React.FC<STokenLoginBoundaryProps> = ({
         globalThis as { backendaioptions?: { get: (k: string) => unknown } }
       ).backendaioptions?.get('endpoints') as string[] | undefined) ?? [];
 
+    // Read and consume interactive-retry state once per sequence run. OTP
+    // is single-use (cleared regardless of outcome); `force` is sticky
+    // across retries once approved.
+    const submittedOtp = pendingOtpRef.current;
+    pendingOtpRef.current = null;
+    const effectiveParams: Record<string, string | boolean> = {
+      ...extraParams,
+      ...(submittedOtp ? { otp: submittedOtp } : {}),
+      ...(forceApprovedRef.current ? { force: true } : {}),
+    };
+
     try {
       if (alreadyLoggedIn) {
         // Session already exists — wire up the GraphQL client / groups /
@@ -204,16 +301,11 @@ const STokenLoginBoundaryInner: React.FC<STokenLoginBoundaryProps> = ({
         // fast-path.
         await connectViaGQL(client, cfg, endpoints);
       } else {
-        await tokenLogin(client, sToken!, cfg, endpoints, extraParams);
+        await tokenLogin(client, sToken!, cfg, endpoints, effectiveParams);
       }
     } catch (cause) {
-      // `concurrent-session` detection is deferred (spec Q6); all
-      // `token_login` failures map to `token-invalid` for now, with a TODO
-      // pointing at the sibling concurrent-login-guard spec.
-      // TODO(FR-2616 Q6): classify `concurrent-session` once the backend
-      // signal from `.specs/draft-concurrent-login-guard/` lands.
       logger.error('[STokenLoginBoundary] token_login failed', cause);
-      surfaceError({ kind: 'token-invalid', cause });
+      surfaceError(classifyTokenLoginFailure(cause, submittedOtp));
       return;
     }
 
@@ -241,11 +333,32 @@ const STokenLoginBoundaryInner: React.FC<STokenLoginBoundaryProps> = ({
     setRetryKey((k) => k + 1);
   };
 
+  // Fold a user-supplied OTP into the next retry. Called from the inline
+  // TOTP form inside `DefaultErrorCard`.
+  const retryWithOtp = (otp: string) => {
+    pendingOtpRef.current = otp;
+    retry();
+  };
+
+  // Approve force-login for all subsequent retries in this mount and
+  // immediately retry. Called from the inline concurrent-session confirm.
+  const retryWithForce = () => {
+    forceApprovedRef.current = true;
+    retry();
+  };
+
   if (phase.name === 'error') {
     if (errorFallback) {
       return <>{errorFallback(phase.error, retry)}</>;
     }
-    return <DefaultErrorCard error={phase.error} onRetry={retry} />;
+    return (
+      <DefaultErrorCard
+        error={phase.error}
+        onRetry={retry}
+        onSubmitOtp={retryWithOtp}
+        onConfirmForce={retryWithForce}
+      />
+    );
   }
 
   if (phase.name === 'success') {
@@ -300,15 +413,28 @@ const DefaultFallback: React.FC = () => {
 
 /**
  * Built-in error card rendered when `errorFallback` is not provided.
- * Offers two actions: Retry (runs the sequence again via BAIButton's
- * async `action` prop so the loading state appears automatically) and
- * Copy details (serializes the `{ kind, cause }` payload to JSON and
- * writes it to the clipboard for support follow-up).
+ *
+ * For most error kinds the card shows a description + {Copy details,
+ * Retry} action pair. Two kinds swap the action area inline (per design:
+ * no separate modal — the user stays on the same card layout and only
+ * the lower half changes):
+ *
+ *   - `totp-required`       → OTP input + Submit button; on submit the
+ *                             parent retries `token_login` with the `otp`
+ *                             folded into `extraParams`.
+ *   - `concurrent-session`  → "terminate previous session?" confirm pair;
+ *                             Login button retries with `force: true`.
+ *
+ * Card `status` color also shifts for these two kinds (`warning` vs.
+ * `error`) so the user reads the required follow-up action, not a
+ * terminal failure.
  */
 const DefaultErrorCard: React.FC<{
   error: STokenLoginError;
   onRetry: () => void;
-}> = ({ error, onRetry }) => {
+  onSubmitOtp: (otp: string) => void;
+  onConfirmForce: () => void;
+}> = ({ error, onRetry, onSubmitOtp, onConfirmForce }) => {
   'use memo';
   const { t } = useTranslation();
   const { message } = App.useApp();
@@ -321,6 +447,11 @@ const DefaultErrorCard: React.FC<{
       ? String((error.cause as Error)?.message ?? error.cause)
       : null;
 
+  const status: 'error' | 'warning' =
+    error.kind === 'totp-required' || error.kind === 'concurrent-session'
+      ? 'warning'
+      : 'error';
+
   // Wrap in a Promise so BAIButton.action triggers its async loading
   // state; the synchronous state reset completes before the next render,
   // which is visually indistinguishable from the live sequence restart.
@@ -346,32 +477,101 @@ const DefaultErrorCard: React.FC<{
       style={{ minHeight: '60vh', padding: 24 }}
     >
       <BAICard
-        status="error"
+        status={status}
         title={title}
         style={{ maxWidth: 520, width: '100%' }}
       >
         <BAIFlex direction="column" gap="md" align="stretch">
           <Typography.Paragraph style={{ margin: 0 }}>
             {description}
           </Typography.Paragraph>
-          {causeDetail && (
+          {causeDetail && error.kind !== 'totp-required' && (
             <Typography.Paragraph
               type="secondary"
               style={{ margin: 0, fontSize: 12, whiteSpace: 'pre-wrap' }}
             >
               {causeDetail}
             </Typography.Paragraph>
           )}
-          <BAIFlex direction="row" gap="sm" justify="end">
-            <BAIButton onClick={handleCopy}>
-              {t('sTokenLoginBoundary.CopyErrorDetails')}
-            </BAIButton>
-            <BAIButton type="primary" action={handleRetry}>
-              {t('sTokenLoginBoundary.Retry')}
-            </BAIButton>
-          </BAIFlex>
+
+          {error.kind === 'totp-required' ? (
+            <TotpInlineForm
+              invalidOtp={!!error.invalidOtp}
+              onSubmit={onSubmitOtp}
+            />
+          ) : error.kind === 'concurrent-session' ? (
+            <BAIFlex direction="row" gap="sm" justify="end">
+              <BAIButton onClick={handleCopy}>
+                {t('sTokenLoginBoundary.CopyErrorDetails')}
+              </BAIButton>
+              <BAIButton
+                type="primary"
+                action={async () => {
+                  await Promise.resolve();
+                  onConfirmForce();
+                }}
+              >
+                {t('sTokenLoginBoundary.ForceLogin')}
+              </BAIButton>
+            </BAIFlex>
+          ) : (
+            <BAIFlex direction="row" gap="sm" justify="end">
+              <BAIButton onClick={handleCopy}>
+                {t('sTokenLoginBoundary.CopyErrorDetails')}
+              </BAIButton>
+              <BAIButton type="primary" action={handleRetry}>
+                {t('sTokenLoginBoundary.Retry')}
+              </BAIButton>
+            </BAIFlex>
+          )}
         </BAIFlex>
       </BAICard>
     </BAIFlex>
   );
 };
+
+/**
+ * Inline OTP input + Submit button rendered inside `DefaultErrorCard`
+ * when the boundary classifies the failure as `totp-required`. Trimmed
+ * locally — the webserver ignores whitespace but users routinely paste a
+ * code with trailing spaces from authenticator apps.
+ */
+const TotpInlineForm: React.FC<{
+  invalidOtp: boolean;
+  onSubmit: (otp: string) => void;
+}> = ({ invalidOtp, onSubmit }) => {
+  'use memo';
+  const { t } = useTranslation();
+  const [form] = Form.useForm<{ otp: string }>();
+  return (
+    <Form
+      form={form}
+      layout="vertical"
+      onFinish={(values) => {
+        const trimmed = (values.otp ?? '').trim();
+        if (!trimmed) return;
+        onSubmit(trimmed);
+      }}
+    >
+      <Form.Item
+        name="otp"
+        validateStatus={invalidOtp ? 'error' : undefined}
+        help={invalidOtp ? t('sTokenLoginBoundary.ErrorTotpInvalidHint') : null}
+        style={{ marginBottom: 12 }}
+      >
+        <Input
+          autoFocus
+          autoComplete="one-time-code"
+          inputMode="numeric"
+          maxLength={8}
+          placeholder={t('sTokenLoginBoundary.TotpPlaceholder')}
+        />
+      </Form.Item>
+      <BAIFlex direction="row" gap="sm" justify="end">
+        <BAIButton type="primary" htmlType="submit">
+          {t('sTokenLoginBoundary.SubmitOtp')}
+        </BAIButton>
+      </BAIFlex>
+    </Form>
+  );
+};