fix: add OTP validate rate limiting, standardize error responses, i18n compliance

Author: adbergen

src/SEBT.Portal.Api/Controllers/Auth/OidcController.cs

@@ -64,14 +64,14 @@ public async Task<IActionResult> GetConfig([FromRoute] string code, Cancellation
             var authEndpoint = root.TryGetProperty("authorization_endpoint", out var ae) ? ae.GetString() : null;
             var tokenEndpoint = root.TryGetProperty("token_endpoint", out var te) ? te.GetString() : null;
             if (string.IsNullOrEmpty(authEndpoint) || string.IsNullOrEmpty(tokenEndpoint))
-                return StatusCode(StatusCodes.Status502BadGateway, new { error = "Invalid discovery document." });
+                return StatusCode(StatusCodes.Status502BadGateway, new ErrorResponse("Invalid discovery document."));
             var languageParam = config["Oidc:LanguageParam"] ?? "en";
             return Ok(new { authorizationEndpoint = authEndpoint, tokenEndpoint, clientId, redirectUri, languageParam });
         }
         catch (Exception ex)
         {
             logger.LogWarning(ex, "Failed to fetch OIDC discovery document");
-            return StatusCode(StatusCodes.Status502BadGateway, new { error = "Unable to load OIDC config." });
+            return StatusCode(StatusCodes.Status502BadGateway, new ErrorResponse("Unable to load OIDC config."));
         }
     }
 
@@ -89,7 +89,7 @@ public async Task<IActionResult> CompleteLogin(
         CancellationToken cancellationToken)
     {
         if (body == null || string.IsNullOrEmpty(body.StateCode) || string.IsNullOrEmpty(body.CallbackToken))
-            return BadRequest(new { error = "Missing stateCode or callbackToken." });
+            return BadRequest(new ErrorResponse("Missing stateCode or callbackToken."));
 
         var stateKey = body.StateCode.ToLowerInvariant();
         var signingKey = config["Oidc:CompleteLoginSigningKey"];
@@ -122,7 +122,7 @@ public async Task<IActionResult> CompleteLogin(
         catch (Exception ex)
         {
             logger.LogWarning(ex, "Invalid or expired callback token for state {StateCode}", body.StateCode);
-            return BadRequest(new { error = "Invalid or expired callback token." });
+            return BadRequest(new ErrorResponse("Invalid or expired callback token."));
         }
 
         // Copy non-common IdP claims into the portal JWT (e.g. phone, givenName, familyName, userId, email, sub)
@@ -137,7 +137,7 @@ public async Task<IActionResult> CompleteLogin(
         if (string.IsNullOrWhiteSpace(email))
         {
             logger.LogWarning("Callback token had no email claim");
-            return BadRequest(new { error = "Callback token must contain an email claim." });
+            return BadRequest(new ErrorResponse("Callback token must contain an email claim."));
         }
 
         var normalizedEmail = EmailNormalizer.Normalize(email);

src/SEBT.Portal.Api/Controllers/Auth/OtpController.cs

@@ -36,7 +36,7 @@ public async Task<IActionResult> RequestOtp(
     {
         if (command == null)
         {
-            return BadRequest(new { Error = "Request body is required." });
+            return BadRequest(new ErrorResponse("Request body is required."));
         }
 
         logger.LogInformation("OTP request received for email {Email}", command.Email);
@@ -49,7 +49,7 @@ public async Task<IActionResult> RequestOtp(
         }
         else
         {
-            return BadRequest(new { Error = result.Message });
+            return BadRequest(new ErrorResponse(result.Message));
         }
 
     }
@@ -64,16 +64,18 @@ public async Task<IActionResult> RequestOtp(
     /// <response code="400">Invalid OTP or request.</response>
     /// <response code="500">An error occurred while generating the authentication token.</response>
     [HttpPost("validate")]
+    [EnableRateLimiting(RateLimitPolicies.Otp)]
     [ProducesResponseType(typeof(ValidateOtpResponse), StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status429TooManyRequests)]
     [ProducesResponseType(StatusCodes.Status500InternalServerError)]
     public async Task<IActionResult> ValidateOtp(
         [FromBody] ValidateOtpCommand command,
         [FromServices] ICommandHandler<ValidateOtpCommand, string> handler)
     {
         if (command == null)
         {
-            return BadRequest(new { Error = "Request body is required." });
+            return BadRequest(new ErrorResponse("Request body is required."));
         }
 
         logger.LogInformation("OTP validation request received for email {Email}", command.Email);
@@ -88,7 +90,7 @@ public async Task<IActionResult> ValidateOtp(
         else
         {
             logger.LogWarning("OTP validation failed for email {Email}: {Message}", command.Email, result.Message);
-            return BadRequest(new { Error = result.Message });
+            return BadRequest(new ErrorResponse(result.Message));
         }
     }
 }

src/SEBT.Portal.Infrastructure/Dependencies.cs

@@ -164,9 +164,6 @@ public static IServiceCollection AddPortalInfrastructureAppSettings(this IServic
         services.AddOptionsWithValidateOnStart<EnrollmentCheckRateLimitSettings>()
             .BindConfiguration(EnrollmentCheckRateLimitSettings.SectionName);
 
-        services.AddOptionsWithValidateOnStart<EnrollmentCheckRateLimitSettings>()
-            .BindConfiguration(EnrollmentCheckRateLimitSettings.SectionName);
-
         services.AddOptions<SeedingSettings>()
             .BindConfiguration(SeedingSettings.SectionName);
 

src/SEBT.Portal.Web/src/api/client.ts

@@ -82,7 +82,9 @@ export async function apiFetch<T>(endpoint: string, options: ApiFetchOptions<T>
   }
 
   if (response.status === 201 || response.status === 204) {
-    return undefined as T
+    // 201/204 responses have no body. Callers for these endpoints
+    // should expect void or ignore the return value.
+    return undefined as unknown as T
   }
 
   let data: T | ApiErrorResponse | undefined

src/SEBT.Portal.Web/src/features/auth/components/doc-verify/DocVerifyInterstitial.tsx

@@ -1,5 +1,7 @@
 'use client'
 
+import { useTranslation } from 'react-i18next'
+
 import { Button } from '@sebt/design-system'
 
 interface DocVerifyInterstitialProps {
@@ -17,33 +19,36 @@ export function DocVerifyInterstitial({
   onEnterIdNumber,
   contactLink
 }: DocVerifyInterstitialProps) {
+  const { t } = useTranslation('idProofing')
+
   return (
     <section aria-labelledby="doc-verify-title">
-      {/* TODO: Use t('docVerify.title') once key is available in dc.csv */}
       <h1
         id="doc-verify-title"
         className="font-sans-xl text-bold line-height-sans-1 margin-bottom-3"
       >
-        We want to keep your account safe
+        {t('interstitialHeading', 'We want to keep your account safe')}
       </h1>
 
-      {/* TODO: Use t('docVerify.body') once key is available in dc.csv */}
       <p className="font-sans-sm">
-        In order to confirm your identity we need to ask for additional documentation. On the next
-        screen, we&apos;ll ask you to upload a photo of your:
+        {t(
+          'interstitialBody',
+          "In order to confirm your identity we need to ask for additional documentation. On the next screen, we'll ask you to upload a photo of your:"
+        )}
       </p>
 
       <ul className="usa-list font-sans-sm">
-        {/* TODO: Use t('docVerify.docTypes.*') once keys are available in dc.csv */}
-        <li>driver&apos;s license</li>
-        <li>foreign passport</li>
-        <li>or another photo ID</li>
+        <li>{t('interstitialIdTypeDriversLicense', "driver's license")}</li>
+        <li>{t('interstitialIdTypeForeignPassport', 'foreign passport')}</li>
+        <li>{t('interstitialIdTypeOtherPhotoId', 'or another photo ID')}</li>
       </ul>
 
       {allowIdRetry && (
         <p className="font-sans-sm">
-          {/* TODO: Use t('docVerify.skipHint') once key is available in dc.csv */}
-          You can skip this step by going back and typing in your ID number instead.
+          {t(
+            'interstitialSkipHint',
+            'You can skip this step by going back and typing in your ID number instead.'
+          )}
         </p>
       )}
 
@@ -54,42 +59,39 @@ export function DocVerifyInterstitial({
             className="usa-button--outline margin-right-2"
             onClick={onEnterIdNumber}
           >
-            {/* TODO: Use t('docVerify.actionEnterId') once key is available in dc.csv */}
-            Enter an ID number
+            {t('interstitialActionEnterId', 'Enter an ID number')}
           </Button>
         )}
 
         <Button
           type="button"
           onClick={onContinue}
           isLoading={isStartingChallenge}
-          loadingText="Loading..."
+          loadingText={t('interstitialLoading', 'Loading...')}
           disabled={isStartingChallenge}
         >
-          {/* TODO: Use t('docVerify.actionContinue') once key is available in dc.csv */}
-          Continue
+          {t('interstitialActionContinue', 'Continue')}
         </Button>
       </div>
 
       {/* FAQs placeholder */}
       <div className="margin-top-6">
-        {/* TODO: Use t('docVerify.faqs') once key is available in dc.csv */}
-        <h2 className="font-sans-lg text-bold">FAQs</h2>
+        <h2 className="font-sans-lg text-bold">{t('interstitialFaqsHeading', 'FAQs')}</h2>
       </div>
 
       {/* Contact Us */}
       <div className="margin-top-4">
-        {/* TODO: Use t('docVerify.contactUs') once key is available in dc.csv */}
-        <h2 className="font-sans-lg text-bold">Contact Us</h2>
+        <h2 className="font-sans-lg text-bold">
+          {t('interstitialContactUsHeading', 'Contact Us')}
+        </h2>
         <p className="font-sans-sm">
           <a
             href={contactLink}
             target="_blank"
             rel="noopener noreferrer"
             className="usa-link"
           >
-            {/* TODO: Use t('docVerify.contactUsLink') once key is available in dc.csv */}
-            Need help? Contact us.
+            {t('interstitialContactUsLink', 'Need help? Contact us.')}
           </a>
         </p>
       </div>

src/SEBT.Portal.Web/src/features/auth/components/doc-verify/DocVerifyPage.tsx

@@ -2,6 +2,7 @@
 
 import { useRouter, useSearchParams } from 'next/navigation'
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
 
 import { Alert } from '@sebt/design-system'
 
@@ -40,6 +41,7 @@ function clearChallengeContext(): void {
 export function DocVerifyPage({ contactLink, sdkKey }: DocVerifyPageProps) {
   const router = useRouter()
   const searchParams = useSearchParams()
+  const { t } = useTranslation('idProofing')
   const startChallenge = useStartChallenge()
 
   const [subState, setSubState] = useState<SubState>('interstitial')
@@ -118,8 +120,12 @@ export function DocVerifyPage({ contactLink, sdkKey }: DocVerifyPageProps) {
       sessionStorage.setItem(SK_SUB_STATE, 'capture')
       setSubState('capture')
     } catch {
-      // TODO: Use t('docVerify.errorStartChallenge') once key is available in dc.csv
-      setError('Something went wrong starting document verification. Please try again.')
+      setError(
+        t(
+          'docVerifyStartError',
+          'Something went wrong starting document verification. Please try again.'
+        )
+      )
     }
   }
 

src/SEBT.Portal.Web/src/features/auth/components/doc-verify/VerificationPending.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
 
 import { Button } from '@sebt/design-system'
 
@@ -20,6 +21,7 @@ export function VerificationPending({
   onVerified,
   onRejected
 }: VerificationPendingProps) {
+  const { t } = useTranslation('idProofing')
   const [timerExpired, setTimerExpired] = useState(false)
 
   const { data, error, refetch } = useVerificationStatus(challengeId)
@@ -46,39 +48,42 @@ export function VerificationPending({
   }, [data?.status, data?.offboardingReason, onVerified, onRejected])
 
   return (
-    <section aria-label="Verification status">
+    <section aria-label={t('verificationPendingAriaLabel', 'Verification status')}>
       {!showStillChecking ? (
         <div className="text-center padding-y-6">
-          {/* TODO: Use t('docVerify.verifying') once key is available in dc.csv */}
-          <p className="font-sans-lg text-bold margin-bottom-2">Verifying your document...</p>
+          <p className="font-sans-lg text-bold margin-bottom-2">
+            {t('verificationPendingHeading', 'Verifying your document...')}
+          </p>
           <p className="font-sans-sm text-base-dark">
-            This may take a moment. Please don&apos;t close this page.
+            {t('verificationPendingBody', "This may take a moment. Please don't close this page.")}
           </p>
           {/* USWDS loading indicator */}
           <div
             className="margin-top-3"
             aria-busy="true"
             aria-live="polite"
           >
-            <span className="text-base-dark">Checking verification status</span>
+            <span className="text-base-dark">
+              {t('verificationPendingStatusLabel', 'Checking verification status')}
+            </span>
           </div>
         </div>
       ) : (
         <div className="text-center padding-y-6">
-          {/* TODO: Use t('docVerify.stillChecking') once key is available in dc.csv */}
           <p className="font-sans-lg text-bold margin-bottom-2">
-            We&apos;re still checking your document
+            {t('verificationPendingStillCheckingHeading', "We're still checking your document")}
           </p>
           <p className="font-sans-sm text-base-dark margin-bottom-3">
-            Verification is taking longer than expected. You can check the status or try again
-            later.
+            {t(
+              'verificationPendingStillCheckingBody',
+              'Verification is taking longer than expected. You can check the status or try again later.'
+            )}
           </p>
           <Button
             type="button"
             onClick={() => refetch()}
           >
-            {/* TODO: Use t('docVerify.actionCheckStatus') once key is available in dc.csv */}
-            Check status
+            {t('verificationPendingActionCheckStatus', 'Check status')}
           </Button>
         </div>
       )}

src/SEBT.Portal.Web/src/features/auth/components/id-proofing/IdProofingForm.tsx

@@ -107,8 +107,9 @@ export function IdProofingForm({ idOptions, contactLink }: IdProofingFormProps)
 
       if (response.result === 'documentVerificationRequired') {
         if (!response.challengeId) {
-          // TODO: Use t('idProofing.errorNoChallengeId') once key is available in dc.csv
-          setSubmitError('Unable to start document verification. Please try again.')
+          setSubmitError(
+            t('idProofingStartError', 'Unable to start document verification. Please try again.')
+          )
           return
         }
         sessionStorage.setItem(SK_CHALLENGE_ID, response.challengeId)
@@ -124,11 +125,10 @@ export function IdProofingForm({ idOptions, contactLink }: IdProofingFormProps)
         router.push('/dashboard')
       }
     } catch (err) {
-      // TODO: Use t('errorUnexpected') once key is available in dc.csv
       // All errors get the same user-facing message. Raw ApiError.message may contain
       // backend wording not intended for end users — avoid displaying it directly.
       void err
-      setSubmitError('Something went wrong. Please try again.')
+      setSubmitError(t('idProofingGenericError', 'Something went wrong. Please try again.'))
     }
   }