Plan: FTI Audit Logging

/// Record of a single FTI data access, per IRS Publication 1075 section 4.
#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
pub struct FtiAuditEntry {
    pub id: Uuid,
    pub accessed_by: String,
    pub accessed_at: DateTime<Utc>,
    pub purpose_code: String,
    pub data_elements_accessed: Vec<String>,
    pub originating_system: String,
    pub action: String,
    pub resource_type: String,
    pub resource_id: Option<Uuid>,
    pub request_id: Option<Uuid>,
    pub ip_address: Option<String>,
    pub success: bool,
    pub created_at: DateTime<Utc>,
}

/// Purpose codes mapped to authorizing IRC sections.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum FtiPurposeCode {
    /// IRC section 6103(l)(7) -- TANF eligibility determination
    TanfEligibility,
    /// IRC section 6103(l)(7) -- TANF benefit computation
    TanfBenefitComputation,
    /// IRC section 6103(l)(7) -- TANF periodic redetermination
    TanfRedetermination,
    /// IRC section 6103(l)(12) -- Medicaid eligibility determination
    MedicaidEligibility,
    /// IRC section 6103(l)(12) -- Medicaid MAGI income verification
    MedicaidMagi,
    /// IRC section 6103(l)(12) -- CHIP eligibility determination
    ChipEligibility,
    /// Pub 1075 section 4 -- IRS auditor reviewing FTI access logs
    AuditReview,
    /// Pub 1075 section 7 -- Authorized system maintenance
    SystemMaintenance,
}

impl FtiPurposeCode {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::TanfEligibility => "TANF_ELIG",
            Self::TanfBenefitComputation => "TANF_BENEFIT",
            Self::TanfRedetermination => "TANF_REDETERMINATION",
            Self::MedicaidEligibility => "MEDICAID_ELIG",
            Self::MedicaidMagi => "MEDICAID_MAGI",
            Self::ChipEligibility => "CHIP_ELIG",
            Self::AuditReview => "AUDIT_REVIEW",
            Self::SystemMaintenance => "SYSTEM_MAINTENANCE",
        }
    }

    pub fn irc_section(&self) -> &'static str {
        match self {
            Self::TanfEligibility | Self::TanfBenefitComputation | Self::TanfRedetermination
                => "IRC 6103(l)(7)(A)",
            Self::MedicaidEligibility | Self::MedicaidMagi | Self::ChipEligibility
                => "IRC 6103(l)(12)(A)",
            Self::AuditReview => "Pub 1075 section 4",
            Self::SystemMaintenance => "Pub 1075 section 7",
        }
    }
}

/// Actions performed on FTI data.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum FtiAction {
    Read,
    Write,
    Delete,
}

impl FtiAction {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Read => "read",
            Self::Write => "write",
            Self::Delete => "delete",
        }
    }
}

/// Filter for querying the FTI audit log. Used by the auditor query endpoint.
#[derive(Debug, Clone, Deserialize)]
pub struct FtiAuditFilter {
    pub from: Option<DateTime<Utc>>,
    pub to: Option<DateTime<Utc>>,
    pub accessed_by: Option<String>,
    pub purpose_code: Option<String>,
    pub action: Option<String>,
    pub resource_type: Option<String>,
    pub page: Option<i64>,
    pub page_size: Option<i64>,
}

/// Paginated query result returned by the auditor query endpoint.
#[derive(Debug, Serialize)]
pub struct FtiAuditPage {
    pub items: Vec<FtiAuditEntry>,
    pub total: i64,
    pub page: i64,
    pub page_size: i64,
}

/// Summary statistics for the IRS inspection dashboard.
#[derive(Debug, Serialize, sqlx::FromRow)]
pub struct FtiAuditSummaryRow {
    pub purpose_code: String,
    pub access_count: i64,
    pub unique_users: i64,
    pub first_access: DateTime<Utc>,
    pub last_access: DateTime<Utc>,
}

/// Error type for FTI audit operations.
#[derive(Debug, thiserror::Error)]
pub enum FtiAuditError {
    #[error("database error: {0}")]
    Database(#[from] sqlx::Error),
    #[error("unauthorized: {0}")]
    Unauthorized(String),
    #[error("invalid purpose code: {0}")]
    InvalidPurposeCode(String),
}

/// Trait for logging FTI access. Implemented once, used by canopy-tanf and canopy-medicaid.
#[async_trait]
pub trait FtiAuditLogger: Send + Sync {
    async fn log_access(&self, entry: FtiAuditEntry) -> Result<(), FtiAuditError>;
    async fn query_log(&self, filter: FtiAuditFilter) -> Result<FtiAuditPage, FtiAuditError>;
    async fn get_entry(&self, id: Uuid) -> Result<Option<FtiAuditEntry>, FtiAuditError>;
    async fn summary(&self, from: DateTime<Utc>, to: DateTime<Utc>) -> Result<Vec<FtiAuditSummaryRow>, FtiAuditError>;
}

/// Concrete implementation that writes directly to the fti_audit_log table.
pub struct PostgresFtiAuditLogger {
    pool: DbPool,
}

impl PostgresFtiAuditLogger {
    pub fn new(pool: DbPool) -> Self {
        Self { pool }
    }
}

#[async_trait]
impl FtiAuditLogger for PostgresFtiAuditLogger {
    async fn log_access(&self, entry: FtiAuditEntry) -> Result<(), FtiAuditError> {
        sqlx::query(
            "INSERT INTO fti_audit_log
                (id, accessed_by, accessed_at, purpose_code, data_elements_accessed,
                 originating_system, action, resource_type, resource_id,
                 request_id, ip_address, success)
             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)"
        )
        .bind(Uuid::now_v7())
        .bind(&entry.accessed_by)
        .bind(Utc::now())
        .bind(&entry.purpose_code)
        .bind(&entry.data_elements_accessed)
        .bind(&entry.originating_system)
        .bind(&entry.action)
        .bind(&entry.resource_type)
        .bind(entry.resource_id)
        .bind(entry.request_id)
        .bind(entry.ip_address.as_deref())
        .bind(entry.success)
        .execute(self.pool.inner())
        .await?;
        Ok(())
    }

    async fn query_log(&self, filter: FtiAuditFilter) -> Result<FtiAuditPage, FtiAuditError> {
        let page = filter.page.unwrap_or(0);
        let page_size = filter.page_size.unwrap_or(50).min(200);
        let offset = page * page_size;

        let total: (i64,) = sqlx::query_as(
            "SELECT COUNT(*) FROM fti_audit_log
             WHERE ($1::timestamptz IS NULL OR accessed_at >= $1)
               AND ($2::timestamptz IS NULL OR accessed_at <= $2)
               AND ($3::text IS NULL OR accessed_by = $3)
               AND ($4::text IS NULL OR purpose_code = $4)
               AND ($5::text IS NULL OR action = $5)
               AND ($6::text IS NULL OR resource_type = $6)"
        )
        .bind(filter.from)
        .bind(filter.to)
        .bind(&filter.accessed_by)
        .bind(&filter.purpose_code)
        .bind(&filter.action)
        .bind(&filter.resource_type)
        .fetch_one(self.pool.inner())
        .await?;

        let items = sqlx::query_as::<_, FtiAuditEntry>(
            "SELECT * FROM fti_audit_log
             WHERE ($1::timestamptz IS NULL OR accessed_at >= $1)
               AND ($2::timestamptz IS NULL OR accessed_at <= $2)
               AND ($3::text IS NULL OR accessed_by = $3)
               AND ($4::text IS NULL OR purpose_code = $4)
               AND ($5::text IS NULL OR action = $5)
               AND ($6::text IS NULL OR resource_type = $6)
             ORDER BY accessed_at DESC
             LIMIT $7 OFFSET $8"
        )
        .bind(filter.from)
        .bind(filter.to)
        .bind(&filter.accessed_by)
        .bind(&filter.purpose_code)
        .bind(&filter.action)
        .bind(&filter.resource_type)
        .bind(page_size)
        .bind(offset)
        .fetch_all(self.pool.inner())
        .await?;

        Ok(FtiAuditPage { items, total: total.0, page, page_size })
    }

    async fn get_entry(&self, id: Uuid) -> Result<Option<FtiAuditEntry>, FtiAuditError> {
        let entry = sqlx::query_as::<_, FtiAuditEntry>(
            "SELECT * FROM fti_audit_log WHERE id = $1"
        )
        .bind(id)
        .fetch_optional(self.pool.inner())
        .await?;
        Ok(entry)
    }

    async fn summary(
        &self,
        from: DateTime<Utc>,
        to: DateTime<Utc>,
    ) -> Result<Vec<FtiAuditSummaryRow>, FtiAuditError> {
        let rows = sqlx::query_as::<_, FtiAuditSummaryRow>(
            "SELECT
                purpose_code,
                COUNT(*) AS access_count,
                COUNT(DISTINCT accessed_by) AS unique_users,
                MIN(accessed_at) AS first_access,
                MAX(accessed_at) AS last_access
             FROM fti_audit_log
             WHERE accessed_at >= $1 AND accessed_at <= $2
             GROUP BY purpose_code
             ORDER BY access_count DESC"
        )
        .bind(from)
        .bind(to)
        .fetch_all(self.pool.inner())
        .await?;
        Ok(rows)
    }
}

/// Wrap any FTI data access with automatic audit logging.
/// Use this for every function that reads or writes FTI data.
///
/// The audit entry is written BEFORE the operation executes.
/// If the operation subsequently fails, we still have the audit record.
/// After the operation completes, the entry's success field is updated.
pub async fn fti_audited<T, F, Fut>(
    pool: &PgPool,
    accessed_by: &str,
    purpose_code: FtiPurposeCode,
    data_elements: &[&str],
    originating_system: &str,
    action: FtiAction,
    resource_type: &str,
    resource_id: Option<Uuid>,
    request_id: Option<Uuid>,
    ip_address: Option<&str>,
    operation: F,
) -> Result<T, FtiAuditError>
where
    F: FnOnce() -> Fut,
    Fut: std::future::Future<Output = Result<T, FtiAuditError>>,
{
    let entry_id = Uuid::now_v7();
    let now = Utc::now();

    // Log BEFORE the access -- if the access fails, we still have the audit record
    sqlx::query(
        "INSERT INTO fti_audit_log
            (id, accessed_by, accessed_at, purpose_code, data_elements_accessed,
             originating_system, action, resource_type, resource_id,
             request_id, ip_address, success)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, true)"
    )
    .bind(entry_id)
    .bind(accessed_by)
    .bind(now)
    .bind(purpose_code.as_str())
    .bind(&data_elements.iter().map(|s| s.to_string()).collect::<Vec<_>>())
    .bind(originating_system)
    .bind(action.as_str())
    .bind(resource_type)
    .bind(resource_id)
    .bind(request_id)
    .bind(ip_address)
    .execute(pool)
    .await?;

    // Perform the actual FTI data access
    let result = operation().await;

    // If the operation failed, update the audit record to reflect failure
    if result.is_err() {
        let _ = sqlx::query("UPDATE fti_audit_log SET success = false WHERE id = $1")
            .bind(entry_id)
            .execute(pool)
            .await;
    }

    result
}

/// FTI field names that must never appear in event payloads.
const FTI_FIELD_NAMES: &[&str] = &[
    "tax_return", "adjusted_gross_income", "agi", "filing_status",
    "taxable_income", "tax_liability", "w2_wages", "1099_income",
    "fti_data", "irs_data", "federal_tax", "wages_salaries_tips",
    "self_employment_income", "social_security_benefits",
    "tax_exempt_interest", "foreign_earned_income", "fti_gross_income",
];

/// Removes any FTI-named fields from a JSON value.
/// This is a defense-in-depth measure; the primary protection is
/// using separate EventPayload structs that never include FTI.
pub fn scrub_fti_fields(value: &mut serde_json::Value) {
    if let serde_json::Value::Object(map) = value {
        map.retain(|key, _| !FTI_FIELD_NAMES.iter().any(|f| key.contains(f)));
        for (_, v) in map.iter_mut() {
            scrub_fti_fields(v);
        }
    }
}

// WRONG -- never do this:
// publisher.publish(&EventEnvelope::new("canopy-tanf", "tanf.determined",
//     json!({ "household_id": id, "fti_gross_income": 45000 })))  // FTI FIELD!

// RIGHT -- IDs and status only:
publisher.publish(&EventEnvelope::new("canopy-tanf", "tanf.determined",
    json!({ "household_id": id, "status": "approved", "determined_at": Utc::now() })))

pub mod fti_audit;

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

    #[test]
    fn scrub_fti_fields_removes_known_fti_field_names() {
        let mut payload = serde_json::json!({
            "household_id": "abc-123",
            "adjusted_gross_income": 45000,
            "status": "approved"
        });
        scrub_fti_fields(&mut payload);
        assert!(payload.get("adjusted_gross_income").is_none());
        assert!(payload.get("household_id").is_some());
        assert!(payload.get("status").is_some());
    }

    #[test]
    fn scrub_fti_fields_handles_nested_objects() {
        let mut payload = serde_json::json!({
            "household_id": "abc-123",
            "details": {
                "fti_data": { "agi": 50000 },
                "status": "ok"
            }
        });
        scrub_fti_fields(&mut payload);
        let details = payload.get("details").unwrap().as_object().unwrap();
        assert!(details.get("fti_data").is_none());
        assert!(details.get("status").is_some());
    }

    #[test]
    fn scrub_fti_fields_preserves_non_fti_fields() {
        let mut payload = serde_json::json!({
            "household_id": "abc-123",
            "status": "approved",
            "determined_at": "2025-11-15T14:22:33Z"
        });
        let original = payload.clone();
        scrub_fti_fields(&mut payload);
        assert_eq!(payload, original);
    }

    #[test]
    fn fti_purpose_code_string_roundtrip() {
        let code = FtiPurposeCode::TanfEligibility;
        assert_eq!(code.as_str(), "TANF_ELIG");
        assert_eq!(code.irc_section(), "IRC 6103(l)(7)(A)");

        let code = FtiPurposeCode::MedicaidEligibility;
        assert_eq!(code.as_str(), "MEDICAID_ELIG");
        assert_eq!(code.irc_section(), "IRC 6103(l)(12)(A)");
    }

    #[test]
    fn fti_purpose_codes_map_to_irc_sections() {
        // All TANF codes map to 6103(l)(7)
        assert!(FtiPurposeCode::TanfEligibility.irc_section().contains("6103(l)(7)"));
        assert!(FtiPurposeCode::TanfBenefitComputation.irc_section().contains("6103(l)(7)"));
        assert!(FtiPurposeCode::TanfRedetermination.irc_section().contains("6103(l)(7)"));

        // All Medicaid/CHIP codes map to 6103(l)(12)
        assert!(FtiPurposeCode::MedicaidEligibility.irc_section().contains("6103(l)(12)"));
        assert!(FtiPurposeCode::MedicaidMagi.irc_section().contains("6103(l)(12)"));
        assert!(FtiPurposeCode::ChipEligibility.irc_section().contains("6103(l)(12)"));
    }

    #[test]
    fn fti_action_as_str() {
        assert_eq!(FtiAction::Read.as_str(), "read");
        assert_eq!(FtiAction::Write.as_str(), "write");
        assert_eq!(FtiAction::Delete.as_str(), "delete");
    }
}

use canopy_common::fti_audit::*;

#[tokio::test]
async fn fti_access_creates_audit_entry() {
    // Setup: testcontainers Postgres, run migrations
    // Act: call fti_audited with a mock FTI read operation
    // Assert: query fti_audit_log, verify exactly one entry with correct fields
    //   - accessed_by matches the test user
    //   - purpose_code = "TANF_ELIG"
    //   - data_elements_accessed = ["adjusted_gross_income", "filing_status"]
    //   - originating_system = "canopy-tanf"
    //   - action = "read"
    //   - success = true
}

#[tokio::test]
async fn fti_audit_log_independent_of_app_audit() {
    // Setup: testcontainers Postgres with BOTH fti_audit_log and audit_events tables
    // Act: perform an FTI read (which creates fti_audit_log entry)
    //      perform a non-FTI operation (which would create audit_events entry via event bus)
    // Assert: fti_audit_log has exactly 1 entry
    //         audit_events has 0 entries (FTI audit does not go through event bus)
}

#[tokio::test]
async fn fti_audit_logs_failed_access_attempts() {
    // Setup: testcontainers Postgres, run migrations
    // Act: call fti_audited with an operation that returns Err
    // Assert: fti_audit_log entry exists with success = false
}

#[tokio::test]
async fn scrub_fti_from_event_payload() {
    // Setup: construct a JSON payload that accidentally includes FTI fields
    // Act: call scrub_fti_fields
    // Assert: all FTI fields removed, non-FTI fields preserved
    let mut payload = serde_json::json!({
        "household_id": "abc",
        "fti_gross_income": 45000,
        "adjusted_gross_income": 45000,
        "status": "approved",
        "determined_at": "2025-11-15T14:22:33Z"
    });
    scrub_fti_fields(&mut payload);
    assert!(payload.get("fti_gross_income").is_none());
    assert!(payload.get("adjusted_gross_income").is_none());
    assert!(payload.get("household_id").is_some());
    assert!(payload.get("status").is_some());
}

#[tokio::test]
async fn fti_auditor_role_required_for_query() {
    // Setup: testcontainers Postgres, run migrations, start Axum test server
    // Act: call GET /v1/fti-audit-log with a token that has role "caseworker" (not "fti_auditor")
    // Assert: response status 403
    // Act: call GET /v1/fti-audit-log with a token that has role "fti_auditor"
    // Assert: response status 200
}

#[tokio::test]
async fn fti_audit_query_pagination() {
    // Setup: insert 25 fti_audit_log entries
    // Act: query with page_size=10, page=0
    // Assert: 10 items returned, total=25, page=0
    // Act: query with page_size=10, page=2
    // Assert: 5 items returned, total=25, page=2
}

#[tokio::test]
async fn fti_audit_retention_archive() {
    // Setup: insert entries with accessed_at spanning 6 years
    // Act: call archive_expired_records with retention_years=5
    // Assert: entries older than 5 years moved to fti_audit_log_archive
    //         entries newer than 5 years remain in fti_audit_log
}