eli-389 added mild documentation of the middleware implementation

Author: eddalmond1

docs/security-headers.md

@@ -0,0 +1,46 @@
+# Security Headers Implementation
+
+This document describes the implementation of security headers for the Eligibility Signposting API.
+
+## Overview
+
+Security headers have been implemented using a two-layer approach:
+
+1. **API Gateway Responses** (Terraform) - For error responses (4xx, 5xx) generated by API Gateway
+2. **Flask Middleware** (Python) - For all successful responses (200, 201, etc.) from the Lambda function
+
+This ensures security headers are present on **all** responses, regardless of where they originate.
+
+## Security Headers
+
+The following security headers are applied to all responses:
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `Cache-Control` | `no-store, private` | Prevents caching of sensitive data |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Enforces HTTPS for 1 year on all subdomains |
+| `X-Content-Type-Options` | `nosniff` | Prevents MIME type sniffing |
+
+## Implementation Details
+
+### 1. API Gateway Responses (Terraform)
+
+File: `infrastructure/stacks/api-layer/gateway_responses.tf`
+
+Gateway responses handle error responses generated by API Gateway itself (e.g., validation failures, authorization errors, throttling).
+
+The following response types have been configured:
+- `DEFAULT_4XX` - All 4xx errors
+- `DEFAULT_5XX` - All 5xx errors
+- `UNAUTHORIZED` (401)
+- `ACCESS_DENIED` (403)
+- `THROTTLED` (429)
+
+### 2. Flask Middleware
+
+Files:
+- `src/eligibility_signposting_api/middleware/security_headers.py` - Middleware implementation
+- `src/eligibility_signposting_api/middleware/__init__.py` - Package exports
+- `src/eligibility_signposting_api/app.py` - Middleware registration
+
+The middleware uses Flask's `after_request` hook to add security headers to all responses from the Lambda function. It's non-overriding: Allows specific endpoints to override headers if needed