feat: codify submission identity policy rules with tests

Author: brianfunk

docs/plan/M04-public-commenting-workflow.md

@@ -21,8 +21,8 @@ Deliver complete public submission workflow with configurable identity policy.
 
 ## Acceptance criteria
 
-- [ ] Public can submit according to docket policy.
-- [ ] Submitted comments enter moderation correctly.
+- [x] Public can submit according to docket policy.
+- [x] Submitted comments enter moderation correctly.
 
 ## Risks/blockers
 
@@ -39,3 +39,4 @@ Deliver complete public submission workflow with configurable identity policy.
 - 2026-02-11: Added edge function `supabase/functions/submit-comment/index.ts` for server-side comment submission with hCaptcha verification, identity-mode enforcement, per-docket limits, IP rate limiting, and deterministic status assignment.
 - 2026-02-11: Updated `src/pages/public/CommentWizard.tsx` to submit through server function, enforce per-docket identity requirements in UX/validation, and support authenticated-required dockets without hardcoded global login redirects.
 - 2026-02-11: Hardened attachment lifecycle in `src/pages/public/CommentWizard.tsx` by removing uploaded files from storage when metadata insert fails, preventing orphaned attachment objects.
+- 2026-02-11: Extracted identity/status policy logic into `supabase/functions/_shared/submissionPolicy.ts` and added `tests/submission-policy.test.ts` to validate docket identity modes and deterministic moderation-entry status behavior.

docs/plan/README.md

@@ -33,9 +33,9 @@ This folder tracks implementation progress for the OpenComments production roadm
 
 - `M00`: Completed
 - `M01`: In progress
-- `M02`: In progress
+- `M02`: Completed
 - `M03`: Completed
-- `M04`: In progress
+- `M04`: Completed
 - `M05`: Completed
 - `M06`: Completed
 - `M07`: In progress

supabase/functions/_shared/submissionPolicy.ts

@@ -0,0 +1,65 @@
+export type IdentityMode = 'optional' | 'name_required' | 'name_email_required' | 'authenticated'
+
+interface IdentityValidationInput {
+  identityMode: IdentityMode
+  isAuthenticated: boolean
+  commenterName: string | null
+  commenterEmail: string | null
+}
+
+export interface IdentityValidationResult {
+  ok: boolean
+  status: number
+  error?: string
+  abuseEventType?: string
+}
+
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}
+
+export function validateIdentityRequirements(input: IdentityValidationInput): IdentityValidationResult {
+  const { identityMode, isAuthenticated, commenterName, commenterEmail } = input
+
+  if (identityMode === 'authenticated' && !isAuthenticated) {
+    return {
+      ok: false,
+      status: 401,
+      error: 'Authentication is required for this docket',
+      abuseEventType: 'identity_auth_required'
+    }
+  }
+
+  if ((identityMode === 'name_required' || identityMode === 'name_email_required') && !commenterName) {
+    return {
+      ok: false,
+      status: 400,
+      error: 'Name is required for this docket'
+    }
+  }
+
+  if (identityMode === 'name_email_required' && !commenterEmail) {
+    return {
+      ok: false,
+      status: 400,
+      error: 'Email is required for this docket'
+    }
+  }
+
+  if (commenterEmail && !isValidEmail(commenterEmail)) {
+    return {
+      ok: false,
+      status: 400,
+      error: 'A valid email address is required'
+    }
+  }
+
+  return {
+    ok: true,
+    status: 200
+  }
+}
+
+export function determineSubmissionStatus(autoPublish: boolean): 'published' | 'submitted' {
+  return autoPublish ? 'published' : 'submitted'
+}

supabase/functions/submit-comment/index.ts

@@ -1,14 +1,17 @@
 import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
 import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+import {
+  type IdentityMode,
+  validateIdentityRequirements,
+  determineSubmissionStatus
+} from '../_shared/submissionPolicy.ts'
 
 const corsHeaders = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
   'Access-Control-Allow-Methods': 'POST,OPTIONS'
 }
 
-type IdentityMode = 'optional' | 'name_required' | 'name_email_required' | 'authenticated'
-
 interface SubmissionRequest {
   docket_slug?: string
   docket_id?: string
@@ -61,10 +64,6 @@ function normalizeText(value?: string): string | null {
   return text
 }
 
-function isValidEmail(email: string): boolean {
-  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
-}
-
 function toHex(buffer: ArrayBuffer): string {
   return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, '0')).join('')
 }
@@ -232,24 +231,23 @@ serve(async (req) => {
     }
 
     const identityMode: IdentityMode = (docket.identity_mode as IdentityMode) || 'optional'
-    if (identityMode === 'authenticated' && !user) {
-      await logAbuseEvent(serviceClient, {
-        agencyId: docket.agency_id,
-        docketId: docket.id,
-        ipAddress,
-        eventType: 'identity_auth_required',
-        details: { identity_mode: identityMode }
-      })
-      return jsonResponse({ error: 'Authentication is required for this docket' }, 401)
-    }
-    if ((identityMode === 'name_required' || identityMode === 'name_email_required') && !commenterName) {
-      return jsonResponse({ error: 'Name is required for this docket' }, 400)
-    }
-    if (identityMode === 'name_email_required' && !commenterEmail) {
-      return jsonResponse({ error: 'Email is required for this docket' }, 400)
-    }
-    if (commenterEmail && !isValidEmail(commenterEmail)) {
-      return jsonResponse({ error: 'A valid email address is required' }, 400)
+    const identityValidation = validateIdentityRequirements({
+      identityMode,
+      isAuthenticated: Boolean(user),
+      commenterName,
+      commenterEmail
+    })
+    if (!identityValidation.ok) {
+      if (identityValidation.abuseEventType) {
+        await logAbuseEvent(serviceClient, {
+          agencyId: docket.agency_id,
+          docketId: docket.id,
+          ipAddress,
+          eventType: identityValidation.abuseEventType,
+          details: { identity_mode: identityMode }
+        })
+      }
+      return jsonResponse({ error: identityValidation.error }, identityValidation.status)
     }
 
     const maxLength = docket.max_comment_length || 4000
@@ -348,7 +346,7 @@ serve(async (req) => {
     }
 
     const trackingId = `CMT-${Date.now().toString(36).toUpperCase()}-${crypto.randomUUID().slice(0, 6).toUpperCase()}`
-    const status = docket.auto_publish ? 'published' : 'submitted'
+    const status = determineSubmissionStatus(Boolean(docket.auto_publish))
     const contentHash = await hashContent(content)
 
     const { data: insertedComment, error: insertError } = await serviceClient

tests/submission-policy.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import {
+  determineSubmissionStatus,
+  validateIdentityRequirements
+} from '../supabase/functions/_shared/submissionPolicy'
+
+describe('submission policy', () => {
+  it('accepts optional identity with no user profile fields', () => {
+    const result = validateIdentityRequirements({
+      identityMode: 'optional',
+      isAuthenticated: false,
+      commenterName: null,
+      commenterEmail: null
+    })
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('requires authentication when docket mode is authenticated', () => {
+    const result = validateIdentityRequirements({
+      identityMode: 'authenticated',
+      isAuthenticated: false,
+      commenterName: null,
+      commenterEmail: null
+    })
+
+    expect(result).toEqual({
+      ok: false,
+      status: 401,
+      error: 'Authentication is required for this docket',
+      abuseEventType: 'identity_auth_required'
+    })
+  })
+
+  it('requires name when docket mode requires name', () => {
+    const result = validateIdentityRequirements({
+      identityMode: 'name_required',
+      isAuthenticated: false,
+      commenterName: null,
+      commenterEmail: null
+    })
+
+    expect(result).toEqual({
+      ok: false,
+      status: 400,
+      error: 'Name is required for this docket'
+    })
+  })
+
+  it('requires email when docket mode requires name and email', () => {
+    const result = validateIdentityRequirements({
+      identityMode: 'name_email_required',
+      isAuthenticated: false,
+      commenterName: 'Jane Smith',
+      commenterEmail: null
+    })
+
+    expect(result).toEqual({
+      ok: false,
+      status: 400,
+      error: 'Email is required for this docket'
+    })
+  })
+
+  it('rejects invalid email formatting', () => {
+    const result = validateIdentityRequirements({
+      identityMode: 'optional',
+      isAuthenticated: false,
+      commenterName: 'Jane Smith',
+      commenterEmail: 'not-an-email'
+    })
+
+    expect(result).toEqual({
+      ok: false,
+      status: 400,
+      error: 'A valid email address is required'
+    })
+  })
+
+  it('returns published status when auto-publish is enabled', () => {
+    expect(determineSubmissionStatus(true)).toBe('published')
+  })
+
+  it('returns submitted status when auto-publish is disabled', () => {
+    expect(determineSubmissionStatus(false)).toBe('submitted')
+  })
+})