Merge pull request #577 from OmniZlatoon/compliance

feat: Implement Compliance Report Automation

Author: LaGodxy

.github/workflows/compliance-report.yml

@@ -0,0 +1,42 @@
+name: Monthly Compliance Report
+
+on:
+  schedule:
+    - cron: '0 0 1 * *'   # first day of month, midnight UTC
+  workflow_dispatch:      # manual trigger
+
+jobs:
+  generate-report:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        
+      - name: Install Soroban CLI
+        run: cargo install --locked soroban-cli --version 21.5.0
+        
+      - name: Install Pandoc
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+        
+      - name: Set up AWS credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1 # Adjust as needed
+          
+      - name: Run Compliance Report
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET || 'streminderminds-compliance-reports' }}
+        run: make compliance-report
+        
+      - name: Upload Report Artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: compliance-report-${{ github.sha }}
+          path: target/compliance/

Makefile

@@ -60,6 +60,7 @@ help:
 	@echo "  $(RED)perf-baseline$(NC)       - Save performance baseline"
 	@echo "  $(RED)load-test$(NC)           - Run configurable contract load tests and write reports"
 	@echo "  $(RED)load-test-ci$(NC)        - Run bounded load tests with CI-safe defaults"
+	@echo "  $(RED)compliance-report$(NC)  - Generate automated compliance report"
 	@echo ""
 	@echo "Examples:"
 	@echo "  make e2e-test              # Full E2E test cycle"
@@ -442,3 +443,13 @@ coverage-dashboard: test-coverage-comprehensive
 	chmod +x ./scripts/coverage-dashboard.sh
 	./scripts/coverage-dashboard.sh
 	@echo "$(GREEN)[COVERAGE]$(NC) Dashboard generated: target/coverage-dashboard/index.html"
+
+# ─────────────────────────────────────────────────────────────
+# Compliance Reporting
+# ─────────────────────────────────────────────────────────────
+
+# Generate automated compliance report
+compliance-report:
+	@echo "$(RED)[COMPLIANCE]$(NC) Generating compliance report..."
+	chmod +x ./scripts/generate_compliance_report.sh
+	./scripts/generate_compliance_report.sh

api/src/routes/admin.ts

@@ -0,0 +1,51 @@
+import { Router, Request, Response } from "express";
+import { authenticate, requireScope } from "../middleware/auth";
+import { complianceService } from "../services/complianceService";
+import { sendSuccess, sendLocalizedError } from "../utils/response";
+import { logger } from "../logger";
+
+const router = Router();
+
+/**
+ * POST /api/v1/admin/compliance-report
+ * 
+ * Trigger manual compliance report generation.
+ * Restricted to users with 'compliance' scope.
+ */
+router.post(
+  "/compliance-report",
+  authenticate,
+  requireScope("compliance"),
+  async (req: Request, res: Response) => {
+    try {
+      logger.info("Admin triggered manual compliance report", { 
+        userId: req.auth?.sub,
+        requestId: req.requestId 
+      });
+
+      const reportUrl = await complianceService.triggerReport();
+
+      sendSuccess(
+        res,
+        {
+          message: "Compliance report generation started successfully",
+          reportUrl,
+          timestamp: new Date().toISOString()
+        },
+        202,
+        req.requestId
+      );
+    } catch (error) {
+      logger.error("Failed to trigger compliance report", { error });
+      sendLocalizedError(
+        req, 
+        res, 
+        500, 
+        "COMPLIANCE_TRIGGER_FAILED", 
+        "Failed to trigger compliance report generation"
+      );
+    }
+  }
+);
+
+export default router;

api/src/services/complianceService.ts

@@ -0,0 +1,52 @@
+import { spawn } from "child_process";
+import path from "path";
+import { logger } from "../logger";
+
+export class ComplianceService {
+  /**
+   * Triggers the compliance report generation script.
+   * Returns a promise that resolves with the report URL if successful.
+   */
+  async triggerReport(): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const scriptPath = path.resolve(__dirname, "../../../scripts/generate_compliance_report.sh");
+      const year = new Date().getFullYear().toString();
+      const month = (new Date().getMonth() + 1).toString().padStart(2, "0");
+      
+      logger.info("Triggering compliance report generation", { scriptPath, year, month });
+
+      const child = spawn("bash", [scriptPath], {
+        env: {
+          ...process.env,
+          YEAR: year,
+          MONTH: month,
+        },
+      });
+
+      let output = "";
+      child.stdout.on("data", (data) => {
+        output += data.toString();
+      });
+
+      child.stderr.on("data", (data) => {
+        logger.error("Compliance script error output", { stderr: data.toString() });
+      });
+
+      child.on("close", (code) => {
+        if (code === 0) {
+          // Parse output for the S3 URL (assuming the script logs it at the end)
+          const match = output.match(/s3:\/\/[\w.-]+\/.+\.pdf/);
+          const reportUrl = match ? match[0] : `s3://streminderminds-compliance-reports/${year}/${month}/report_${year}_${month}.pdf`;
+          
+          logger.info("Compliance report generated successfully", { reportUrl });
+          resolve(reportUrl);
+        } else {
+          logger.error("Compliance report generation failed", { exitCode: code });
+          reject(new Error(`Compliance script failed with exit code ${code}`));
+        }
+      });
+    });
+  }
+}
+
+export const complianceService = new ComplianceService();

contracts/shared/src/compliance_tests.rs

@@ -0,0 +1,48 @@
+#[cfg(test)]
+mod tests {
+    use crate::roles::{RoleLevel, Permission};
+    use crate::permissions::RolePermissions;
+    use soroban_sdk::{Env, Vec};
+
+    #[test]
+    fn test_compliance_admin_role_level() {
+        let level = RoleLevel::ComplianceAdmin;
+        assert_eq!(level.to_u32(), 6);
+        assert_eq!(RoleLevel::from_u32(6), Some(RoleLevel::ComplianceAdmin));
+    }
+
+    #[test]
+    fn test_compliance_admin_permissions() {
+        let env = Env::default();
+        let permissions = RolePermissions::compliance_admin_permissions(&env);
+        
+        assert!(permissions.contains(&Permission::GenerateComplianceReport));
+        assert!(permissions.contains(&Permission::ViewAudit));
+        assert!(permissions.contains(&Permission::ViewSystemStats));
+    }
+
+    #[test]
+    fn test_admin_can_grant_compliance_admin() {
+        let admin = RoleLevel::Admin;
+        let compliance_admin = RoleLevel::ComplianceAdmin;
+        
+        // Admin (4) can grant ComplianceAdmin (6) due to explicit logic in can_grant
+        assert!(admin.can_grant(&compliance_admin));
+    }
+
+    #[test]
+    fn test_super_admin_can_grant_compliance_admin() {
+        let super_admin = RoleLevel::SuperAdmin;
+        let compliance_admin = RoleLevel::ComplianceAdmin;
+        
+        assert!(super_admin.can_grant(&compliance_admin));
+    }
+
+    #[test]
+    fn test_moderator_cannot_grant_compliance_admin() {
+        let moderator = RoleLevel::Moderator;
+        let compliance_admin = RoleLevel::ComplianceAdmin;
+        
+        assert!(!moderator.can_grant(&compliance_admin));
+    }
+}

contracts/shared/src/lib.rs

@@ -46,3 +46,5 @@ mod logger_tests;
 pub mod monitoring_tests;
 #[cfg(test)]
 pub mod performance_tests;
+#[cfg(test)]
+mod compliance_tests;

contracts/shared/src/permissions.rs

@@ -102,6 +102,18 @@ impl RolePermissions {
         permissions
     }
 
+    /// Get default permissions for a ComplianceAdmin role
+    pub fn compliance_admin_permissions(env: &Env) -> Vec<Permission> {
+        let mut permissions = Vec::new(env);
+        permissions.push_back(Permission::GenerateComplianceReport);
+        permissions.push_back(Permission::ViewAudit);
+        permissions.push_back(Permission::ViewSystemStats);
+        permissions.push_back(Permission::ViewAllUsers);
+        permissions.push_back(Permission::ViewAllCourses);
+        permissions.push_back(Permission::ViewAllCertificates);
+        permissions
+    }
+
     /// Get permissions for a specific role level
     pub fn get_permissions_for_level(env: &Env, level: &RoleLevel) -> Vec<Permission> {
         match level {
@@ -110,6 +122,7 @@ impl RolePermissions {
             RoleLevel::Instructor => Self::instructor_permissions(env),
             RoleLevel::Admin => Self::admin_permissions(env),
             RoleLevel::SuperAdmin => Self::super_admin_permissions(env),
+            RoleLevel::ComplianceAdmin => Self::compliance_admin_permissions(env),
         }
     }
 

contracts/shared/src/roles.rs

@@ -9,6 +9,7 @@ pub enum RoleLevel {
     Instructor = 3,
     Admin = 4,
     SuperAdmin = 5,
+    ComplianceAdmin = 6,
 }
 
 impl RoleLevel {
@@ -19,6 +20,7 @@ impl RoleLevel {
             3 => Some(RoleLevel::Instructor),
             4 => Some(RoleLevel::Admin),
             5 => Some(RoleLevel::SuperAdmin),
+            6 => Some(RoleLevel::ComplianceAdmin),
             _ => None,
         }
     }
@@ -30,14 +32,27 @@ impl RoleLevel {
             RoleLevel::Instructor => 3,
             RoleLevel::Admin => 4,
             RoleLevel::SuperAdmin => 5,
+            RoleLevel::ComplianceAdmin => 6,
         }
     }
 
     pub fn can_grant(&self, target_role: &RoleLevel) -> bool {
+        if *self == RoleLevel::SuperAdmin {
+            return true;
+        }
+        if *self == RoleLevel::Admin && *target_role == RoleLevel::ComplianceAdmin {
+            return true;
+        }
         self.to_u32() > target_role.to_u32()
     }
 
     pub fn can_revoke(&self, target_role: &RoleLevel) -> bool {
+        if *self == RoleLevel::SuperAdmin {
+            return true;
+        }
+        if *self == RoleLevel::Admin && *target_role == RoleLevel::ComplianceAdmin {
+            return true;
+        }
         self.to_u32() >= target_role.to_u32()
     }
 
@@ -48,6 +63,8 @@ impl RoleLevel {
                 | (RoleLevel::Admin, _)
                 | (RoleLevel::Instructor, Permission::ViewAudit)
                 | (RoleLevel::Moderator, Permission::ViewAudit)
+                | (RoleLevel::ComplianceAdmin, Permission::GenerateComplianceReport)
+                | (RoleLevel::ComplianceAdmin, Permission::ViewAudit)
         )
     }
 }
@@ -165,6 +182,9 @@ pub enum Permission {
     ViewSystemStats,
     ViewAudit,
 
+    // Compliance
+    GenerateComplianceReport,
+
     // Dynamic permission
     Custom(soroban_sdk::Symbol),
 }
@@ -201,6 +221,7 @@ impl Permission {
             Permission::ViewAllUsers => "ViewAllUsers",
             Permission::ViewSystemStats => "ViewSystemStats",
             Permission::ViewAudit => "ViewAudit",
+            Permission::GenerateComplianceReport => "GenerateComplianceReport",
             Permission::Custom(_) => "Custom",
         }
     }

docs/COMPLIANCE_REPORT.md

@@ -0,0 +1,41 @@
+# Compliance Report Automation
+
+## Overview
+This system automates the generation of audit-ready compliance reports for the StrellerMinds platform. It aggregates on-chain events from smart contracts and off-chain access logs from the API server.
+
+## Components
+
+### 1. Smart Contract Role: `ComplianceAdmin`
+A new privileged role `ComplianceAdmin` has been added to the RBAC system. This role has the `GenerateComplianceReport` permission.
+- **Permissions:** `GenerateComplianceReport`, `ViewAudit`, `ViewSystemStats`, `ViewAllUsers`, `ViewAllCourses`, `ViewAllCertificates`.
+- **Granting:** The `Admin` role can grant the `ComplianceAdmin` role.
+
+### 2. API Endpoint: `POST /api/v1/admin/compliance-report`
+A protected endpoint that allows an authorized compliance administrator to trigger report generation manually.
+- **Authentication:** Bearer JWT required.
+- **Scope:** Must have the `compliance` scope in the JWT.
+
+### 3. Generation Script: `scripts/generate_compliance_report.sh`
+The core logic for data aggregation and report formatting.
+- **On-chain:** Uses `soroban contract events` to pull contract activity.
+- **Off-chain:** Pulls `audit_logs` from the PostgreSQL database.
+- **Formatting:** Uses Markdown templates and `pandoc` to generate HTML/PDF reports.
+- **Storage:** Uploads generated artifacts to the configured S3 bucket.
+
+### 4. Scheduled Workflow: `.github/workflows/compliance-report.yml`
+A GitHub Action that runs automatically on the first day of every month at midnight UTC.
+
+## Configuration
+
+The following environment variables/secrets are required for the automated job:
+- `DATABASE_URL`: Connection string for the production PostgreSQL database.
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`: Credentials for S3 upload.
+- `AWS_S3_BUCKET`: The destination bucket (default: `streminderminds-compliance-reports`).
+
+## Manual Execution
+To generate a report manually from the command line:
+```bash
+make compliance-report YEAR=2024 MONTH=05
+```
+
+The reports will be saved in `target/compliance/YEAR/MONTH/`.