Add endpoints, services, and security controls for particle file management, including save and download APIs.

open_api/src/main/resources/api.yml

@@ -10,11 +10,18 @@ components:
   schemas:
     PermissionClaim:
       $ref: './schemas/permissions/permissions.yml#/components/schemas/PermissionClaim'
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
 tags:
   - name: history
     description: Retrieves punishment history
   - name: team
     description: Retrieves information about the staff team
+  - name: particles
+    description: All actions related to particles
 paths:
   /team/{team}:
     $ref: './schemas/team/team.yml#/getTeam'
@@ -46,3 +53,11 @@ paths:
     $ref: './schemas/login/login.yml#/RequestNewUserLogin'
   /login/userLogin/{code}:
     $ref: './schemas/login/login.yml#/UserLogin'
+  /files/save/{filename}:
+    $ref: './schemas/particles/particles.yml#/SaveFile'
+  /files/save/{uuid}/{filename}:
+    $ref: './schemas/particles/particles.yml#/SaveFileForUser'
+  /files/download/{filename}/{secret}:
+    $ref: './schemas/particles/particles.yml#/DownloadFile'
+  /files/download/{uuid}/{filename}:
+    $ref: './schemas/particles/particles.yml#/DownloadFileForUser'

open_api/src/main/resources/schemas/particles/particles.yml

@@ -0,0 +1,176 @@
+components:
+  parameters:
+    Filename:
+      name: filename
+      in: path
+      required: true
+      schema:
+        type: string
+        description: The name of the file
+    Secret:
+      name: Authorization
+      in: header
+      required: true
+      schema:
+        type: string
+        description: Secret
+  schemas:
+    FileData:
+      type: object
+      required:
+        - content
+      properties:
+        content:
+          type: string
+          format: binary
+          description: The content of the file
+
+SaveFile:
+  post:
+    tags:
+      - particles
+    summary: Save a file
+    description: Save a file to the server (requires authorization)
+    operationId: saveFile
+    security:
+      - bearerAuth: []
+    parameters:
+      - $ref: '#/components/parameters/Filename'
+    requestBody:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            $ref: '#/components/schemas/FileData'
+    responses:
+      '200':
+        description: File saved successfully
+      '401':
+        description: Unauthorized - Invalid or missing token
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      '403':
+        description: Forbidden - Insufficient permissions
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+
+SaveFileForUser:
+  post:
+    tags:
+      - particles
+    summary: Save a file for a specific user
+    description: Save a file to the server for a specific user (requires head_mod permission)
+    operationId: saveFileForUser
+    security:
+      - bearerAuth: []
+    parameters:
+      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
+      - $ref: '#/components/parameters/Filename'
+    requestBody:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            $ref: '#/components/schemas/FileData'
+    responses:
+      '200':
+        description: File saved successfully
+      '401':
+        description: Unauthorized - Invalid or missing token
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      '403':
+        description: Forbidden - Insufficient permissions
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+
+DownloadFile:
+  get:
+    tags:
+      - particles
+    summary: Download a file
+    description: Download a file from the server using a secret key
+    operationId: downloadFile
+    parameters:
+      - $ref: '#/components/parameters/Secret'
+      - $ref: '#/components/parameters/Filename'
+    responses:
+      '200':
+        description: File downloaded successfully
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      '404':
+        description: File not found
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+
+DownloadFileForUser:
+  get:
+    tags:
+      - particles
+    summary: Download a file for a specific user
+    description: Download a file from the server for a specific user (requires authorization)
+    operationId: downloadFileForUser
+    security:
+      - bearerAuth: []
+    parameters:
+      - $ref: '#/components/parameters/Secret'
+      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
+      - $ref: '#/components/parameters/Filename'
+    responses:
+      '200':
+        description: File downloaded successfully
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      '401':
+        description: Unauthorized - Invalid or missing token
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      '404':
+        description: File not found
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'