feat(api): production security, cors hardening, latency optimizations, postman artifacts & frontend documentation

2026-08-31 13:48:54 +05:30
parent 4e21d617ce
commit e91cdbae6e
48 changed files with 3742 additions and 65 deletions
@@ -0,0 +1,79 @@
+# Authentication & Patient Security Specification
+
+**Module**: API Security & Identity Management  
+**Implementation Source**: [`app/core/security.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/core/security.py)
+
+---
+
+## 1. Authentication Mechanisms
+
+The API supports two authentication methods for frontend applications and client services:
+
+### Method A: HTTP Bearer Token (Standard)
+Send the access token in the `Authorization` request header:
+```http
+Authorization: Bearer <ACCESS_TOKEN>
+```
+
+### Method B: `X-API-Key` Custom Header
+Send the API key in the custom `X-API-Key` header:
+```http
+X-API-Key: <API_KEY>
+```
+
+---
+
+## 2. Supported Access Tokens
+
+### 1. Service Secret API Key
+For service-to-service integration or administrative access:
+- **Default Key**: `skyheal_secure_api_key_2026` (configurable via `API_SECRET_KEY` in server environment).
+
+### 2. Patient Development / Testing Tokens
+For patient-specific web or mobile client authentication:
+- **Format**: `test_token_<PATIENT_ID>`
+- **Example**: `test_token_PAT-10023`
+
+When `test_token_<PATIENT_ID>` is passed, the backend automatically establishes the patient context with `patient_id = "<PATIENT_ID>"`.
+
+---
+
+## 3. Patient Isolation & IDOR Protection Rules
+
+The backend enforces strict **Broken Object Level Authorization (IDOR) Protection**:
+1. When starting an onboarding session (`/v1/onboarding/start` or `/v1/voice-onboarding/start`), the `patient.id` provided in the JSON body is bound as the session owner (`session.patient_id`).
+2. Subsequent requests to `/message`, `/turn`, `/upload`, or `/complete` verify that the caller's authenticated `patient_id` matches the session owner.
+3. If Client B attempts to send a message to Client A's session, the server immediately returns **`HTTP 403 Forbidden`**:
+   ```json
+   {
+     "detail": "Forbidden: You do not have authorization to access or modify this patient onboarding session."
+   }
+   ```
+
+---
+
+## 4. Authentication Error Responses
+
+### Missing Credentials (HTTP 401)
+Triggered when no `Authorization` or `X-API-Key` header is present:
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer
+Content-Type: application/json
+
+{
+  "detail": "Authentication credentials required. Please provide X-API-Key or Bearer token."
+}
+```
+
+### Invalid Token (HTTP 401)
+Triggered when an invalid token string is provided:
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer
+Content-Type: application/json
+
+{
+  "detail": "Invalid authentication token or API key."
+}
+```