Add email verification functionality, including backend support, email handling, and user interface integration.

open_api/src/main/resources/api.yml

@@ -26,6 +26,8 @@ tags:
     description: All actions shared between forms
   - name: appeals
     description: All action related to appeals
+  - name: mail
+    description: All actions related to user email verification
 paths:
   /api/team/{team}:
     $ref: './schemas/team/team.yml#/getTeam'
@@ -67,3 +69,13 @@ paths:
     $ref: './schemas/particles/particles.yml#/DownloadFile'
   /api/files/download/{uuid}/{filename}:
     $ref: './schemas/particles/particles.yml#/DownloadFileForUser'
+  /api/mail/submit:
+    $ref: './schemas/forms/mail/mail.yml#/SubmitEmail'
+  /api/mail/verify:
+    $ref: './schemas/forms/mail/mail.yml#/VerifyCode'
+  /api/mail/resend:
+    $ref: './schemas/forms/mail/mail.yml#/ResendEmail'
+  /api/mail/delete:
+    $ref: './schemas/forms/mail/mail.yml#/DeleteEmail'
+  /api/mail/list:
+    $ref: './schemas/forms/mail/mail.yml#/GetEmails'

open_api/src/main/resources/schemas/forms/mail/mail.yml

@@ -0,0 +1,166 @@
+SubmitEmail:
+  post:
+    tags:
+      - mail
+    summary: Submit an email for verification
+    description: Store a new email for the authenticated user and send a verification code
+    operationId: submitEmailForVerification
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/SubmitEmail'
+    responses:
+      '201':
+        description: Verification email sent
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MailResponse'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
+VerifyCode:
+  post:
+    tags:
+      - mail
+    summary: Verify an email using a code
+    description: Verify the email for the authenticated user by providing the received code
+    operationId: verifyEmailCode
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/VerifyCode'
+    responses:
+      '200':
+        description: Email verified successfully
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MailResponse'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
+ResendEmail:
+  post:
+    tags:
+      - mail
+    summary: Resend verification email
+    description: Request a new verification email to be sent for a pending email
+    operationId: resendVerificationEmail
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/SubmitEmail'
+    responses:
+      '200':
+        description: Verification email resent
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MailResponse'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
+DeleteEmail:
+  delete:
+    tags:
+      - mail
+    summary: Delete an email
+    description: Delete an email associated with the authenticated user
+    operationId: deleteEmail
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/SubmitEmail'
+    responses:
+      '204':
+        description: Email deleted
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
+GetEmails:
+  get:
+    tags:
+      - mail
+    summary: Get all emails for the authenticated user
+    description: Returns both verified and unverified emails for the authenticated user
+    operationId: getUserEmails
+    responses:
+      '200':
+        description: Emails retrieved successfully
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/EmailEntry'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
+
+components:
+  schemas:
+    SubmitEmail:
+      type: object
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          description: Email address to verify
+    VerifyCode:
+      type: object
+      required:
+        - code
+      properties:
+        code:
+          type: string
+          description: Verification code received by email
+    MailResponse:
+      type: object
+      required:
+        - message
+        - email
+        - verified
+      properties:
+        email:
+          type: string
+        message:
+          type: string
+        verified:
+          type: boolean
+    EmailEntry:
+      type: object
+      required:
+        - email
+        - verified
+      properties:
+        email:
+          type: string
+          description: The user's email address
+        verified:
+          type: boolean
+          description: Whether the email has been verified