foxhunt/database/migrations/RLS_QUICK_REFERENCE.md

Row Level Security (RLS) Quick Reference Guide

Target Audience: Developers integrating with Foxhunt database Last Updated: 2025-10-03 (Wave 79 Agent 8)

---

TL;DR - What You Need to Know

1. Set session variables before querying audit tables
2. Use prepared statements to prevent SQL injection
3. Don't bypass RLS - it's there for compliance (SOX/MiFID II)

---

Required Session Variables

Before querying any table with RLS enabled, you MUST set these session variables:

-- Set current user's UUID
SET app.current_user_id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';

-- Set current user's role
SET app.current_user_role = 'trader';  -- or 'admin', 'compliance_officer', 'risk_manager'

Valid Roles:

• admin - Full access to everything
• compliance_officer - Access to all audit trails
• risk_manager - Access to risk-related audit trails
• trader - Access to trading-related data
• system - Insert-only access to audit tables

---

Rust/SQLx Integration

Connection Pool Setup

use sqlx::{PgPool, Postgres, Transaction};
use uuid::Uuid;

pub struct DatabaseConnection {
    pool: PgPool,
    user_id: Uuid,
    user_role: String,
}

impl DatabaseConnection {
    pub async fn new(database_url: &str, user_id: Uuid, user_role: String) -> Result<Self> {
        let pool = PgPool::connect(database_url).await?;
        Ok(Self { pool, user_id, user_role })
    }

    /// Get a connection with RLS session variables set
    pub async fn get_connection(&self) -> Result<Transaction<'_, Postgres>> {
        let mut tx = self.pool.begin().await?;

        // Set session variables for RLS
        sqlx::query("SET app.current_user_id = $1")
            .bind(self.user_id)
            .execute(&mut *tx)
            .await?;

        sqlx::query("SET app.current_user_role = $1")
            .bind(&self.user_role)
            .execute(&mut *tx)
            .await?;

        Ok(tx)
    }
}

Usage Example

use foxhunt_db::DatabaseConnection;

async fn query_audit_trail(conn: &DatabaseConnection, trade_id: Uuid) -> Result<Vec<AuditEvent>> {
    let mut tx = conn.get_connection().await?;

    // Query will automatically be filtered by RLS policies
    let events = sqlx::query_as::<_, AuditEvent>(
        "SELECT * FROM sox_trade_audit WHERE trade_id = $1"
    )
    .bind(trade_id)
    .fetch_all(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(events)
}

---

Tables with RLS Enabled

Audit Tables (Append-Only, No Updates/Deletes)

1. sox_trade_audit

   • Who can see: User's own trades, or admin/compliance/risk_manager
   • Permissions: SELECT, INSERT only

2. mifid_transaction_report

   • Who can see: admin, compliance_officer, trader
   • Permissions: SELECT, INSERT only

3. position_limits_audit

   • Who can see: User's own limits, or admin/risk_manager
   • Permissions: SELECT, INSERT only

4. kill_switch_audit

   • Who can see: admin, risk_manager ONLY
   • Permissions: SELECT, INSERT only

5. best_execution_analysis

   • Who can see: admin, compliance_officer, trader
   • Permissions: SELECT, INSERT only

6. transaction_audit_events

   • Who can see (SELECT): Own events, or admin/compliance/risk_manager
   • Who can insert (INSERT): admin, system ONLY
   • Permissions: SELECT, INSERT only (NO UPDATE/DELETE)

---

Common Patterns

Pattern 1: Query User's Own Audit Trail

async fn get_my_trades(conn: &DatabaseConnection) -> Result<Vec<Trade>> {
    let mut tx = conn.get_connection().await?;

    // RLS automatically filters to current user's trades
    let trades = sqlx::query_as::<_, Trade>(
        "SELECT * FROM sox_trade_audit ORDER BY order_timestamp DESC LIMIT 100"
    )
    .fetch_all(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(trades)
}

Pattern 2: Admin Queries All Audit Trails

async fn admin_query_all_trades(
    conn: &DatabaseConnection,
    start_date: DateTime<Utc>,
) -> Result<Vec<Trade>> {
    // Ensure user has admin role
    assert_eq!(conn.user_role, "admin", "Admin role required");

    let mut tx = conn.get_connection().await?;

    // Admin can see all trades
    let trades = sqlx::query_as::<_, Trade>(
        "SELECT * FROM sox_trade_audit WHERE order_timestamp >= $1"
    )
    .bind(start_date)
    .fetch_all(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(trades)
}

Pattern 3: Insert Audit Event (System Role)

async fn log_trade_activity(
    system_conn: &DatabaseConnection,  // Must have 'system' role
    trade: &Trade,
) -> Result<Uuid> {
    assert_eq!(system_conn.user_role, "system", "System role required");

    let mut tx = system_conn.get_connection().await?;

    let audit_id = sqlx::query_scalar::<_, Uuid>(
        "SELECT log_sox_trade_activity($1, $2, $3, $4, $5, $6, $7, $8, $9)"
    )
    .bind(trade.trade_id)
    .bind(trade.user_id)
    .bind(&trade.symbol)
    .bind(&trade.side)
    .bind(trade.quantity)
    .bind(trade.price)
    .bind(&trade.order_type)
    .bind(trade.trade_value)
    .bind(trade.order_timestamp)
    .fetch_one(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(audit_id)
}

---

Error Handling

RLS Policy Violation

If a query violates an RLS policy, PostgreSQL will silently filter results (returns empty set), NOT throw an error.

// Example: Trader tries to access kill switch audit
let mut tx = trader_conn.get_connection().await?;

// This will return 0 rows, not an error
let result = sqlx::query_as::<_, KillSwitchEvent>(
    "SELECT * FROM kill_switch_audit"
)
.fetch_all(&mut *tx)
.await?;

assert_eq!(result.len(), 0);  // Empty result, no error

Session Variable Not Set

If session variables are not set, RLS policies will fail:

// WRONG: Forgot to set session variables
let result = sqlx::query_as::<_, Trade>("SELECT * FROM sox_trade_audit")
    .fetch_all(&pool)
    .await;

// May return error or empty result

---

Testing RLS Policies

Test Helper Function

#[cfg(test)]
mod tests {
    use super::*;

    async fn setup_test_connection(
        role: &str,
        user_id: Uuid,
    ) -> DatabaseConnection {
        DatabaseConnection::new(
            &std::env::var("DATABASE_URL").unwrap(),
            user_id,
            role.to_string(),
        )
        .await
        .unwrap()
    }

    #[tokio::test]
    async fn test_user_can_see_own_trades() {
        let user_id = Uuid::new_v4();
        let conn = setup_test_connection("trader", user_id).await;

        // Insert test trade
        let trade_id = insert_test_trade(&conn, user_id).await.unwrap();

        // Verify user can see their own trade
        let trades = get_my_trades(&conn).await.unwrap();
        assert!(trades.iter().any(|t| t.trade_id == trade_id));
    }

    #[tokio::test]
    async fn test_user_cannot_see_other_trades() {
        let user1_id = Uuid::new_v4();
        let user2_id = Uuid::new_v4();

        let conn1 = setup_test_connection("trader", user1_id).await;
        let conn2 = setup_test_connection("trader", user2_id).await;

        // User 1 inserts trade
        let trade_id = insert_test_trade(&conn1, user1_id).await.unwrap();

        // User 2 tries to see User 1's trade
        let trades = get_my_trades(&conn2).await.unwrap();
        assert!(!trades.iter().any(|t| t.trade_id == trade_id));
    }

    #[tokio::test]
    async fn test_admin_can_see_all_trades() {
        let admin_id = Uuid::new_v4();
        let user_id = Uuid::new_v4();

        let admin_conn = setup_test_connection("admin", admin_id).await;
        let user_conn = setup_test_connection("trader", user_id).await;

        // User inserts trade
        let trade_id = insert_test_trade(&user_conn, user_id).await.unwrap();

        // Admin can see all trades
        let trades = admin_query_all_trades(&admin_conn, Utc::now() - Duration::hours(1))
            .await
            .unwrap();
        assert!(trades.iter().any(|t| t.trade_id == trade_id));
    }
}

---

Performance Considerations

RLS Policy Overhead

RLS policies add a WHERE clause to every query. For example:

-- Your query
SELECT * FROM sox_trade_audit WHERE symbol = 'AAPL';

-- What PostgreSQL actually executes (if user_role = 'trader')
SELECT * FROM sox_trade_audit
WHERE symbol = 'AAPL'
  AND (user_id = current_user_id() OR has_role('admin') OR ...);

Optimization Tips:

1. Add indexes on user_id columns
2. Use connection pooling to avoid repeated session variable setup
3. Cache role membership checks if possible

Recommended Indexes

-- Index on user_id for user-specific queries
CREATE INDEX idx_sox_trade_audit_user_id ON sox_trade_audit(user_id);
CREATE INDEX idx_position_limits_audit_user_id ON position_limits_audit(user_id);

-- Composite indexes for common queries
CREATE INDEX idx_sox_trade_audit_user_symbol ON sox_trade_audit(user_id, symbol);
CREATE INDEX idx_sox_trade_audit_timestamp ON sox_trade_audit(order_timestamp DESC);

---

Security Best Practices

1. Never Bypass RLS

// WRONG: Don't try to bypass RLS by using superuser connections
let superuser_pool = PgPool::connect("postgresql://postgres:...").await?;

// RIGHT: Always use application user with RLS enabled
let app_pool = PgPool::connect("postgresql://foxhunt_user:...").await?;

2. Validate Roles Before Privileged Operations

fn require_role(conn: &DatabaseConnection, required_role: &str) -> Result<()> {
    if conn.user_role != required_role {
        return Err(Error::Unauthorized(
            format!("Role '{}' required, got '{}'", required_role, conn.user_role)
        ));
    }
    Ok(())
}

async fn activate_kill_switch(conn: &DatabaseConnection) -> Result<()> {
    // Only admin and risk_manager can activate kill switch
    if conn.user_role != "admin" && conn.user_role != "risk_manager" {
        return Err(Error::Unauthorized("Insufficient privileges"));
    }

    // ... proceed with kill switch activation
}

3. Use Prepared Statements

// WRONG: String interpolation (SQL injection risk)
let query = format!("SELECT * FROM sox_trade_audit WHERE symbol = '{}'", symbol);

// RIGHT: Prepared statement with parameter binding
let trades = sqlx::query_as::<_, Trade>(
    "SELECT * FROM sox_trade_audit WHERE symbol = $1"
)
.bind(symbol)
.fetch_all(&pool)
.await?;

4. Audit Log Immutability

// WRONG: Trying to update audit trail (will fail)
let result = sqlx::query("UPDATE sox_trade_audit SET quantity = $1 WHERE trade_id = $2")
    .bind(new_quantity)
    .bind(trade_id)
    .execute(&pool)
    .await;

// Result: Permission denied (UPDATE revoked on audit tables)

// RIGHT: Audit trails are append-only
// If correction needed, insert a new correction record
let correction_id = sqlx::query_scalar::<_, Uuid>(
    "INSERT INTO sox_trade_audit_corrections (original_trade_id, corrected_quantity, reason)
     VALUES ($1, $2, $3) RETURNING id"
)
.bind(trade_id)
.bind(new_quantity)
.bind("User error - incorrect quantity entered")
.fetch_one(&pool)
.await?;

---

Troubleshooting

Problem: Empty Result Set

Symptom: Query returns 0 rows, but you know data exists.

Possible Causes:

1. Session variables not set
2. User doesn't have required role
3. RLS policy filtering out results

Debug Steps:

-- Check session variables
SHOW app.current_user_id;
SHOW app.current_user_role;

-- Check if user has required role
SELECT has_role('admin');

-- Bypass RLS temporarily (TESTING ONLY - requires superuser)
SET SESSION AUTHORIZATION foxhunt_test;
SELECT * FROM sox_trade_audit;  -- Should show all rows
RESET SESSION AUTHORIZATION;

Problem: Permission Denied

Symptom: ERROR: permission denied for table sox_trade_audit

Possible Causes:

1. Using wrong database user (not foxhunt_user or member of authenticated_users)
2. Public access revoked and user not granted explicit permissions

Debug Steps:

-- Check current user
SELECT current_user;

-- Check user's roles
SELECT rolname FROM pg_roles WHERE pg_has_role(current_user, oid, 'member');

-- Check table permissions
SELECT grantee, privilege_type
FROM information_schema.table_privileges
WHERE table_name = 'sox_trade_audit' AND grantee = current_user;

---

Migration History

This RLS implementation was created as part of:

• Wave 79 Agent 8: Production Database Configuration (2025-10-03)
• Migration File: 999_production_roles_setup.sql
• Documentation: WAVE79_AGENT8_DATABASE_PRODUCTION_SETUP.md

---

Further Reading

• PostgreSQL RLS Documentation
• SQLx Documentation
• Foxhunt Internal: /docs/WAVE79_AGENT8_DATABASE_PRODUCTION_SETUP.md

---

Last Updated: 2025-10-03 Maintained By: Foxhunt Database Team Questions?: Check /docs/WAVE79_AGENT8_DATABASE_PRODUCTION_SETUP.md for detailed information