# PostgreSQL Security Guide for QuantEngine

This document outlines the security configuration, role definitions, and access control policies for the `quantengine` schema in the PostgreSQL database.

---

## 1. Schema Isolation

The Quant Investment Engine operates strictly within the `quantengine` schema to prevent namespace pollution and protect system catalog tables.

* **Schema**: `quantengine`
* **Default Database**: `giteadb`

---

## 2. Role Definitions & Privileges

To ensure the principle of least privilege, we define three main database roles:

### A. Schema Owner (`quantengine_owner`)
* **Purpose**: Full access to schema objects, responsible for executing DDL (migrations, table creation).
* **Permissions**:
  ```sql
  CREATE ROLE quantengine_owner WITH LOGIN PASSWORD 'OwnerPasswordSecure';
  GRANT ALL PRIVILEGES ON DATABASE giteadb TO quantengine_owner;
  GRANT ALL PRIVILEGES ON SCHEMA quantengine TO quantengine_owner;
  ALTER DEFAULT PRIVILEGES IN SCHEMA quantengine GRANT ALL ON TABLES TO quantengine_owner;
  ```

### B. Read-Write Application Role (`quantengine_app`)
* **Purpose**: Used by the live .NET application to insert daily data feeds, update portfolio states, and insert qualitative sell strategy results.
* **Permissions**:
  ```sql
  CREATE ROLE quantengine_app WITH LOGIN PASSWORD 'AppPasswordSecure';
  GRANT CONNECT ON DATABASE giteadb TO quantengine_app;
  GRANT USAGE ON SCHEMA quantengine TO quantengine_app;
  
  -- Grant CRUD permissions on tables & sequences
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA quantengine TO quantengine_app;
  GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA quantengine TO quantengine_app;
  
  -- Restrict DDL operations
  ALTER DEFAULT PRIVILEGES IN SCHEMA quantengine GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO quantengine_app;
  ```

### C. Read-Only Analytical Role (`quantengine_readonly`)
* **Purpose**: Used by external reporting tools, dashboards, or manual audit scripts.
* **Permissions**:
  ```sql
  CREATE ROLE quantengine_readonly WITH LOGIN PASSWORD 'ReadonlyPasswordSecure';
  GRANT CONNECT ON DATABASE giteadb TO quantengine_readonly;
  GRANT USAGE ON SCHEMA quantengine TO quantengine_readonly;
  
  GRANT SELECT ON ALL TABLES IN SCHEMA quantengine TO quantengine_readonly;
  ALTER DEFAULT PRIVILEGES IN SCHEMA quantengine GRANT SELECT ON TABLES TO quantengine_readonly;
  ```

---

## 3. Configuration Best Practices

1. **Connection String Hygiene**: 
   * Never store connection strings with plaintext passwords in version control.
   * `appsettings.json` must only contain placeholder configurations.
   * Inject the connection string at runtime using environment variables:
     `ConnectionStrings__DefaultConnection="Host=127.0.0.1;Database=giteadb;Username=quantengine_app;Password=YourSecurePassword;Search Path=quantengine;"`

2. **Network Security**:
   * Bind PostgreSQL only to local interfaces (`127.0.0.1`) or secure private network interfaces.
   * Restrict access in `pg_hba.conf` to allow connections only from the Gitea runner or application host.