DC-48(feat): Add id-proofing form, route, API hook, and mock handler (#51)

* DC-48(feat): Add id-proofing form, route, API hook, and mock handler

* DC-48(feat): Harden id-proofing validation and wire requiresIdProofing routing

- Add idType required validation to IdProofingForm; show error when no option selected
- Add superRefine to SubmitIdProofingRequestSchema enforcing idType/idValue consistency
- Add requiresIdProofing field to ValidateOtpResponse schema; route post-OTP to
  id-proofing only when the flag is true, otherwise proceed to dashboard
- Pass nonce to GoogleAnalytics for CSP strict-dynamic compliance
- Expand IdProofingForm tests: fix error counts, add MSW-backed API error test,
  add idType-required test

* DC-48(test): Cover requiresIdProofing=false and absent routing paths

Both the false and absent cases route to /dashboard via the strict
=== true guard, but neither path had test coverage. Adds two new
email fixtures to the MSW handler to exercise each scenario.

* DC-48(review): Address PR #51 review feedback and add hook test

Author: necampanini

src/SEBT.Portal.Web/src/app/(public)/login/id-proofing/page.tsx

@@ -0,0 +1,79 @@
+import { IdProofingForm, type IdOption } from '@/features/auth'
+import { getStateLinks } from '@/lib/links'
+import { getState } from '@/lib/state'
+import { getTranslations } from '@/lib/translations'
+
+// DC-only: CO uses external auth and never reaches this route.
+// If a future state adopts OTP auth with id-proofing, add a state-based options
+// map or guard here.
+//
+// The full set shown here is for non-co-loaded users. Once the backend confirms
+// which options are available for co-loaded users (via JWT claim), this list can
+// be made dynamic at the page level.
+// TODO: Filter options based on co-loaded status once that claim is available in the JWT.
+const DC_ID_OPTIONS: IdOption[] = [
+  {
+    value: 'ssn',
+    labelKey: 'optionLabelSsn',
+    inputLabelKey: 'labelSsn'
+  },
+  {
+    value: 'itin',
+    labelKey: 'optionLabelItin',
+    inputLabelKey: 'labelItin'
+  },
+  {
+    value: 'medicaidId',
+    labelKey: 'optionLabelMedicaidId',
+    helperKey: 'optionHelperMedicaidId',
+    inputLabelKey: 'labelMedicaidId'
+  },
+  {
+    value: 'snapAccountId',
+    labelKey: 'optionAccountId',
+    helperKey: 'optionHelperAccountId',
+    inputLabelKey: 'labelAccountId'
+  },
+  {
+    value: 'snapPersonId',
+    labelKey: 'optionPersonId',
+    helperKey: 'optionHelperPersonId',
+    inputLabelKey: 'labelPersonId'
+  },
+  {
+    value: 'none',
+    // TODO: Use t('optionLabelNone') once key is available in dc.csv
+    labelKey: 'optionLabelNone'
+  }
+]
+
+export default function IdProofingPage() {
+  const state = getState()
+  const links = getStateLinks(state)
+  const t = getTranslations('idProofing')
+
+  return (
+    <div className="usa-section">
+      <div className="grid-container maxw-tablet">
+        <section aria-labelledby="id-proofing-title">
+          <h1
+            id="id-proofing-title"
+            className="font-sans-xl text-bold line-height-sans-1 margin-bottom-3"
+          >
+            {t('title')}
+          </h1>
+
+          <p className="margin-top-0 font-sans-sm">{t('body')}</p>
+
+          {/* TODO: Use t('requiredDisclaimer') once key is available in dc.csv */}
+          <p className="margin-top-2 font-sans-sm">Asterisks (*) indicate a required field.</p>
+
+          <IdProofingForm
+            idOptions={DC_ID_OPTIONS}
+            contactLink={links.external.contactUsAssistance}
+          />
+        </section>
+      </div>
+    </div>
+  )
+}

src/SEBT.Portal.Web/src/app/layout.tsx

@@ -113,7 +113,13 @@ export default async function RootLayout({
         />
       </body>
       {/* Google Analytics - only rendered when GA_ID is configured */}
-      {gaId && <GoogleAnalytics gaId={gaId} />}
+      {/* nonce is required for CSP compliance: proxy.ts enforces nonce-based strict-dynamic */}
+      {gaId && (
+        <GoogleAnalytics
+          gaId={gaId}
+          {...(nonce ? { nonce } : {})}
+        />
+      )}
     </html>
   )
 }

src/SEBT.Portal.Web/src/features/auth/api/index.ts

@@ -1,5 +1,13 @@
 export { useRefreshToken } from './refresh-token'
 
+export {
+  IdTypeSchema,
+  SubmitIdProofingRequestSchema,
+  useSubmitIdProofing,
+  type IdType,
+  type SubmitIdProofingRequest
+} from './submit-id-proofing'
+
 export { RequestOtpRequestSchema, useRequestOtp, type RequestOtpRequest } from './request-otp'
 
 export {

src/SEBT.Portal.Web/src/features/auth/api/submit-id-proofing/index.ts

@@ -0,0 +1,7 @@
+export {
+  IdTypeSchema,
+  SubmitIdProofingRequestSchema,
+  type IdType,
+  type SubmitIdProofingRequest
+} from './schema'
+export { useSubmitIdProofing } from './useSubmitIdProofing'

src/SEBT.Portal.Web/src/features/auth/api/submit-id-proofing/schema.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod'
+
+// The ID types the user can provide for identity proofing.
+// 'none' is a UI-only sentinel — the API receives null when the user selects "none of the above".
+export const IdTypeSchema = z.enum(['snapAccountId', 'snapPersonId', 'medicaidId', 'ssn', 'itin'])
+export type IdType = z.infer<typeof IdTypeSchema>
+
+export const SubmitIdProofingRequestSchema = z
+  .object({
+    dateOfBirth: z.object({
+      month: z.string(),
+      day: z.string(),
+      year: z.string()
+    }),
+    // null when the user selects "none of the above"
+    idType: IdTypeSchema.nullable(),
+    // null when idType is null
+    idValue: z.string().nullable()
+  })
+  .superRefine((data, ctx) => {
+    if (data.idType === null && data.idValue !== null) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['idValue'],
+        message: 'idValue must be null when idType is null'
+      })
+    }
+    if (data.idType !== null) {
+      const v = data.idValue
+      if (v === null || v.trim() === '') {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['idValue'],
+          message: 'idValue is required when idType is not null'
+        })
+      }
+    }
+  })
+
+export type SubmitIdProofingRequest = z.infer<typeof SubmitIdProofingRequestSchema>

src/SEBT.Portal.Web/src/features/auth/api/submit-id-proofing/useSubmitIdProofing.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * useSubmitIdProofing Hook Unit Tests
+ *
+ * Tests the id-proofing mutation hook behavior including:
+ * - Successful submission (204 No Content)
+ * - Correct payload sent to the endpoint
+ * - Error handling for 4xx errors (no retry)
+ * - Retry behavior for 5xx errors
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderHook, waitFor } from '@testing-library/react'
+import { http, HttpResponse } from 'msw'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { server } from '@/mocks/server'
+
+import type { SubmitIdProofingRequest } from './schema'
+import { useSubmitIdProofing } from './useSubmitIdProofing'
+
+// Obviously fake PII values per CLAUDE.md PII conventions
+const VALID_PAYLOAD: SubmitIdProofingRequest = {
+  dateOfBirth: { month: '01', day: '15', year: '1990' },
+  idType: 'ssn',
+  idValue: '999999999'
+}
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false }
+    }
+  })
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  }
+}
+
+describe('useSubmitIdProofing', () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('Successful Submission', () => {
+    it('should succeed on valid id-proofing submission', async () => {
+      const { result } = renderHook(() => useSubmitIdProofing(), {
+        wrapper: createWrapper()
+      })
+
+      result.current.mutate(VALID_PAYLOAD)
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+    })
+
+    it('should send the correct payload to the endpoint', async () => {
+      let capturedBody: SubmitIdProofingRequest | null = null
+
+      server.use(
+        http.post('/api/id-proofing', async ({ request }) => {
+          capturedBody = (await request.json()) as SubmitIdProofingRequest
+          return HttpResponse.json(null, { status: 204 })
+        })
+      )
+
+      const { result } = renderHook(() => useSubmitIdProofing(), {
+        wrapper: createWrapper()
+      })
+
+      result.current.mutate(VALID_PAYLOAD)
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(capturedBody).toEqual(VALID_PAYLOAD)
+    })
+  })
+
+  describe('Error Handling', () => {
+    it('should NOT retry on 400 bad request', async () => {
+      let requestCount = 0
+
+      server.use(
+        http.post('/api/id-proofing', () => {
+          requestCount++
+          return HttpResponse.json({ error: 'Bad Request' }, { status: 400 })
+        })
+      )
+
+      const queryClient = new QueryClient()
+
+      const { result } = renderHook(() => useSubmitIdProofing(), {
+        wrapper: ({ children }) => (
+          <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+        )
+      })
+
+      result.current.mutate(VALID_PAYLOAD)
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true)
+      })
+
+      // Should only make 1 request - no retries for 4xx
+      expect(requestCount).toBe(1)
+    })
+
+    it('should NOT retry on 401 unauthorized', async () => {
+      let requestCount = 0
+
+      server.use(
+        http.post('/api/id-proofing', () => {
+          requestCount++
+          return HttpResponse.json({ error: 'Unauthorized' }, { status: 401 })
+        })
+      )
+
+      const queryClient = new QueryClient()
+
+      const { result } = renderHook(() => useSubmitIdProofing(), {
+        wrapper: ({ children }) => (
+          <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+        )
+      })
+
+      result.current.mutate(VALID_PAYLOAD)
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true)
+      })
+
+      expect(requestCount).toBe(1)
+    })
+  })
+
+  describe('Retry Logic', () => {
+    it('should retry on 5xx server errors up to 2 times', async () => {
+      let requestCount = 0
+
+      server.use(
+        http.post('/api/id-proofing', () => {
+          requestCount++
+          return HttpResponse.json({ error: 'Server Error' }, { status: 500 })
+        })
+      )
+
+      const queryClient = new QueryClient()
+
+      const { result } = renderHook(() => useSubmitIdProofing(), {
+        wrapper: ({ children }) => (
+          <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+        )
+      })
+
+      result.current.mutate(VALID_PAYLOAD)
+
+      // Advance timers to allow retries with exponential backoff
+      await vi.advanceTimersByTimeAsync(1000) // First retry delay
+      await vi.advanceTimersByTimeAsync(2000) // Second retry delay
+      await vi.advanceTimersByTimeAsync(4000) // Extra time for processing
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true)
+      })
+
+      // Should make 3 requests total: initial + 2 retries
+      expect(requestCount).toBe(3)
+    })
+
+    it('should succeed on retry after transient server error', async () => {
+      let requestCount = 0
+
+      server.use(
+        http.post('/api/id-proofing', () => {
+          requestCount++
+          if (requestCount === 1) {
+            return HttpResponse.json({ error: 'Service Unavailable' }, { status: 503 })
+          }
+          return HttpResponse.json(null, { status: 204 })
+        })
+      )
+
+      const queryClient = new QueryClient()
+
+      const { result } = renderHook(() => useSubmitIdProofing(), {
+        wrapper: ({ children }) => (
+          <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+        )
+      })
+
+      result.current.mutate(VALID_PAYLOAD)
+
+      // Advance timer for retry
+      await vi.advanceTimersByTimeAsync(1000)
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(requestCount).toBe(2)
+    })
+  })
+})