OSIT-AE-API-FastAPI/documentation/archive/PLAN__SECURITY_HARDENING.md

Project: API Security Hardening (V3)

Status: Complete / Archived (Reviewed March 18, 2026) Date: Jan 18, 2026 Owner: Scott / Aether API Team

This plan was fully implemented and reviewed on March 18, 2026. All critical and high vulnerabilities described have been addressed in the current codebase. See dependencies in app/routers/dependencies_v3.py and JWT logic in app/lib_jwt.py for details.

1. Executive Summary

This project aims to close a critical security vulnerability in the Aether API V3 dependencies where the x_no_account_id header allows unauthorized "Superuser/Bypass" access without validation. Additionally, it addresses the lack of cryptographic verification for JWTs in the V3 CRUD layer.

2. The Vulnerabilities

A. The "Bypass Header" (Critical)

• Issue: The get_account_context_optional dependency in app/routers/dependencies_v3.py accepts a header x_no_account_id. If present, it sets auth_method = 'bypass' and grants full administrative privileges (super=True).
• Note: This header may be sent as x_no_account_id or x-no-account-id. FastAPI's Header logic should handle the conversion, but validation must be explicit.
• Current State: There is no validation of this header. Sending x_no_account_id: anything works.
• Risk: Total system compromise via simple header injection.

B. JWT Verification (High)

• Issue: The system validates users by looking up the x_account_id string in the database (Redis/MariaDB).
• Current State: It does not cryptographically verify the JWT signature or expiration in the V3 dependency chain.
• Risk: Account impersonation if an Account ID is leaked.

3. Implementation Plan

Phase 1: Secure the Bypass Header (Immediate)

Goal: Restrict "Bypass Mode" to clients possessing a valid, active API Key.

1. Refactor Dependencies:

   • Update get_account_context_optional to accept x_aether_api_key.
   • Logic Change: If x_no_account_id header is detected:
     • Require x_aether_api_key.
     • Lookup key in api_key table.
     • Verify enable = 1 and now() is between enable_from and enable_to.
   • Failure Behavior: If key is invalid/missing, log warning and deny 'bypass' status (fall back to 'guest').

2. Verification:

   • Test curl with header only -> Expect 403/Forbidden.
   • Test curl with header + valid Key -> Expect 200/OK.
   • Test Frontend File Download (uses x_no_account_id_token param) -> Expect 200/OK (No regression).

Phase 2: JWT Verification (Subsequent)

Goal: Replace DB-lookup auth with cryptographic JWT validation.

1. Audit: Confirm app/lib_jwt.py logic is sound.
2. Middleware/Dependency: Integrate decode_jwt into the get_account_context flow.
3. Transition: Allow dual-mode (DB lookup OR JWT) for a transition period if necessary, or cut over if frontend sends valid JWTs.

4. Impact Analysis

• Frontend (SvelteKit):
  • Audit confirmed no usage of x_no_account_id header in active source code.
  • Usage of x_no_account_id_token (Query Param) is safe and distinct from the header logic.
• Scripts/External Tools:
  • Any external scripts using the "Bypass" header must be updated to send a valid API Key.

5. Action Items

• Create PROJECT_SECURITY_HARDENING.md (This document).
• Refactor app/routers/dependencies_v3.py.
• Verify fix with curl tests.
• Commit changes.