feat: add api for authentication

docs/openapi.yaml

@@ -17,7 +17,87 @@ tags:
   - name: Objects
   - name: Buckets
   - name: Multipart uploads
+  - name: Dashboard Auth
 paths:
+  /auth/login:
+    post:
+      tags: [Dashboard Auth]
+      operationId: authLogin
+      summary: Login to dashboard
+      description: Authenticate with SHA-256 hashed dashboard password.
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/LoginRequest' }
+      responses:
+        '200':
+          description: Login successful.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/LoginResponse' }
+        '400':
+          description: Invalid request.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
+        '401':
+          description: Invalid password.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
+        '429':
+          description: Too many failed attempts.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
+        '503':
+          description: Dashboard authentication not configured.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
+  /auth/session:
+    get:
+      tags: [Dashboard Auth]
+      operationId: authSession
+      summary: Verify session token
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Session is valid.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  valid: { type: boolean, example: true }
+        '401':
+          description: Invalid or expired session.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
+        '503':
+          description: Dashboard authentication not configured.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
+  /auth/logout:
+    post:
+      tags: [Dashboard Auth]
+      operationId: authLogout
+      summary: Logout of dashboard session
+      security:
+        - bearerAuth: []
+      responses:
+        '204':
+          description: Successfully logged out.
+        '503':
+          description: Dashboard authentication not configured.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AuthError' }
   /{bucket}:
     parameters:
       - $ref: '#/components/parameters/Bucket'
@@ -236,6 +316,10 @@ components:
       in: header
       name: Authorization
       description: AWS Signature Version 4 header authentication or equivalent `X-Amz-*` presigned query parameters.
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: Session token returned from `/auth/login`.
   parameters:
     Bucket:
       name: bucket
@@ -299,6 +383,32 @@ components:
       description: The method/path combination is unsupported.
       content: { application/xml: { schema: { $ref: '#/components/schemas/S3Error' } } }
   schemas:
+    LoginRequest:
+      type: object
+      required: [passwordHash]
+      properties:
+        passwordHash:
+          type: string
+          description: SHA-256 hash of the dashboard password in lowercase hex.
+          example: ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f
+    LoginResponse:
+      type: object
+      required: [token, expiresIn]
+      properties:
+        token:
+          type: string
+          description: Session token.
+        expiresIn:
+          type: integer
+          description: Token TTL in seconds.
+          example: 43200
+    AuthError:
+      type: object
+      required: [message]
+      properties:
+        message:
+          type: string
+          example: Invalid password
     S3Error:
       type: object
       xml: { name: Error }