# Project: API Security Hardening (V3)

**Status:** Draft / Planning
**Date:** Jan 18, 2026
**Owner:** Scott / Aether API Team

## 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.