Junie: security cleanups.

docs/api.md

@@ -12,7 +12,7 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
 
 **Endpoint**: `POST /v1/login/password`
 
-**Description**: Authenticates a user using username and password credentials.
+**Description**: Authenticates a user using username and password credentials. This endpoint does not require TOTP verification, even if TOTP is enabled for the user.
 
 **Request Format**:
 ```json
@@ -34,13 +34,15 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
 ```json
 {
     "token": "authentication_token",
-    "expires": 1621234567
+    "expires": 1621234567,
+    "totp_enabled": true
 }
 ```
 
 **Response Fields**:
 - `token`: Authentication token to be used for subsequent requests
 - `expires`: Unix timestamp when the token expires
+- `totp_enabled`: Boolean indicating whether TOTP is enabled for the user
 
 **Error Responses**:
 - 400 Bad Request: Invalid request format or missing required fields
@@ -86,6 +88,43 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
 - 401 Unauthorized: Invalid or expired token
 - 500 Internal Server Error: Server-side error
 
+#### TOTP Verification
+
+**Endpoint**: `POST /v1/login/totp`
+
+**Description**: Verifies a TOTP code for a user and issues a token upon successful verification. This endpoint is used as a separate flow from password authentication.
+
+**Request Format**:
+```json
+{
+    "version": "v1",
+    "username": "username",
+    "totp_code": "123456"
+}
+```
+
+**Required Fields**:
+- `version`: Must be "v1"
+- `username`: Username
+- `totp_code`: Time-based One-Time Password code
+
+**Response Format** (Success - 200 OK):
+```json
+{
+    "token": "authentication_token",
+    "expires": 1621234567
+}
+```
+
+**Response Fields**:
+- `token`: Authentication token to be used for subsequent requests
+- `expires`: Unix timestamp when the token expires
+
+**Error Responses**:
+- 400 Bad Request: Invalid request format, missing required fields, or TOTP not enabled for user
+- 401 Unauthorized: Invalid TOTP code
+- 500 Internal Server Error: Server-side error
+
 ### Database Credentials
 
 **Endpoint**: `/v1/credentials/database` (Not yet implemented)
@@ -112,14 +151,34 @@ Common HTTP status codes:
 
 ## Authentication Flow
 
+### Password Authentication Flow
+
 1. **Initial Authentication**:
    - Client sends username and password to `/v1/login/password`
    - Server validates credentials and returns a token
+   - The response includes a `totp_enabled` flag indicating whether TOTP is enabled for the user
 
 2. **Subsequent Requests**:
    - Client uses the token for authentication by sending it to `/v1/login/token`
    - Server validates the token and issues a new token
 
-3. **Token Expiration**:
+### TOTP Authentication Flow
+
+1. **TOTP Verification** (separate from password authentication):
+   - Client sends username and TOTP code to `/v1/login/totp`
+   - Server validates the TOTP code and returns a token if valid
+
+### Token Management
+
+1. **Token Expiration**:
    - Tokens expire after 24 hours
-   - Clients should request a new token before expiration
+   - Clients should request a new token before expiration
+
+### Multi-Factor Authentication
+
+For users with TOTP enabled, a complete multi-factor authentication flow would involve:
+1. Authenticate with username and password using `/v1/login/password`
+2. Check the `totp_enabled` flag in the response
+3. If TOTP is enabled, prompt the user for their TOTP code
+4. Verify the TOTP code using `/v1/login/totp` to get a second token
+5. Use either token for subsequent requests (both are valid)