Junie: security cleanups.

docs/api.org

@@ -91,10 +91,74 @@ MCIAS (Metacircular Identity and Access System) provides identity and authentica
 
 *** Database Credentials
 
-*Endpoint*: =/v1/credentials/database= (Not yet implemented)
+*Endpoint*: =GET /v1/database/credentials=
 
 *Description*: Retrieves database credentials for authorized users.
 
+*Request Parameters*:
+- =username=: Username of the authenticated user
+
+*Headers*:
+- =Authorization=: Bearer token for authentication
+
+*Response Format* (Success - 200 OK):
+#+begin_src json
+{
+    "host": "database_host",
+    "port": 5432,
+    "name": "database_name",
+    "user": "database_user",
+    "password": "database_password"
+}
+#+end_src
+
+*Error Responses*:
+- 400 Bad Request: Invalid request format or missing required parameters
+- 401 Unauthorized: Invalid or expired token
+- 403 Forbidden: Insufficient permissions to access database credentials
+- 500 Internal Server Error: Server-side error
+
+*** TOTP Authentication
+
+*Endpoint*: =POST /v1/login/totp=
+
+*Description*: Authenticates a user using TOTP (Time-based One-Time Password) in addition to username and password.
+
+*Request Format*:
+#+begin_src json
+{
+    "version": "v1",
+    "login": {
+        "user": "username",
+        "password": "secret_password",
+        "totp": "123456"
+    }
+}
+#+end_src
+
+*Required Fields*:
+- =version=: Must be "v1"
+- =login.user=: Username
+- =login.password=: User's password
+- =login.totp=: 6-digit TOTP code from authenticator app
+
+*Response Format* (Success - 200 OK):
+#+begin_src json
+{
+    "token": "authentication_token",
+    "expires": 1621234567
+}
+#+end_src
+
+*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 or missing required fields
+- 401 Unauthorized: Invalid username, password, or TOTP code
+- 500 Internal Server Error: Server-side error
+
 ** Error Handling
 
 All error responses follow a standard format:
@@ -118,11 +182,20 @@ Common HTTP status codes:
 1. *Initial Authentication*:
    - Client sends username and password to =/v1/login/password=
    - Server validates credentials and returns a token
+   - If TOTP is enabled for the user, authentication with password alone will fail
 
-2. *Subsequent Requests*:
+2. *TOTP Authentication*:
+   - For users with TOTP enabled, client sends username, password, and TOTP code to =/v1/login/totp=
+   - Server validates all credentials and returns a token
+
+3. *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*:
+4. *Token Expiration*:
    - Tokens expire after 24 hours
-   - Clients should request a new token before expiration
+   - Clients should request a new token before expiration
+
+5. *Database Credential Access*:
+   - Client sends a GET request to =/v1/database/credentials= with the token in the Authorization header
+   - Server validates the token and returns the database credentials if the user has sufficient permissions