@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/data.export.create.v1/fastapi.example.py

@@ -0,0 +1,165 @@
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from aport.middleware import require_policy
+import asyncio
+from typing import List, Optional
+import io
+
+app = FastAPI(title="Data Export Service", version="1.0.0")
+
+class ExportRequest(BaseModel):
+    format: str
+    include_pii: bool = False
+    filters: dict
+
+class ExportStatus(BaseModel):
+    export_id: str
+    status: str
+    created_at: str
+    estimated_rows: int
+    actual_rows: Optional[int] = None
+    format: str
+    include_pii: bool
+
+@app.post("/exports")
+@require_policy("data.export.create.v1")
+async def create_export(request: Request, export_data: ExportRequest):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Check PII permission
+        if export_data.include_pii and not passport.limits.allow_pii:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "PII export not allowed",
+                    "agent_id": passport.agent_id,
+                    "upgrade_instructions": "Request PII export capability from your administrator"
+                }
+            )
+        
+        # Estimate row count (in real app, query your database)
+        estimated_rows = await estimate_export_rows(export_data.filters)
+        
+        # Check row limit
+        if estimated_rows > passport.limits.max_export_rows:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "Export exceeds row limit",
+                    "requested": estimated_rows,
+                    "limit": passport.limits.max_export_rows,
+                    "upgrade_instructions": "Request smaller export or upgrade limits"
+                }
+            )
+        
+        # Process export
+        export_id = await create_export_job({
+            "format": export_data.format,
+            "include_pii": export_data.include_pii,
+            "filters": export_data.filters,
+            "agent_id": passport.agent_id,
+            "agent_name": passport.name,
+            "estimated_rows": estimated_rows
+        })
+        
+        # Log the export request
+        print(f"Export created: {export_id} ({estimated_rows} rows) by agent {passport.agent_id}")
+        
+        return {
+            "success": True,
+            "export_id": export_id,
+            "format": export_data.format,
+            "estimated_rows": estimated_rows,
+            "status": "processing"
+        }
+        
+    except Exception as e:
+        print(f"Export creation error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.get("/exports/{export_id}")
+@require_policy("data.export.create.v1")
+async def get_export_status(request: Request, export_id: str):
+    try:
+        passport = request.state.policy_result.passport
+        
+        export_info = await get_export_status(export_id, passport.agent_id)
+        
+        if not export_info:
+            raise HTTPException(status_code=404, detail="Export not found")
+        
+        return export_info
+        
+    except Exception as e:
+        print(f"Export status error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.get("/exports/{export_id}/download")
+@require_policy("data.export.create.v1")
+async def download_export(request: Request, export_id: str):
+    try:
+        passport = request.state.policy_result.passport
+        
+        export_file = await get_export_file(export_id, passport.agent_id)
+        
+        if not export_file:
+            raise HTTPException(status_code=404, detail="Export file not found")
+        
+        if export_file["status"] != "completed":
+            raise HTTPException(status_code=400, detail="Export not ready for download")
+        
+        # Create streaming response
+        def generate_file():
+            yield export_file["data"]
+        
+        return StreamingResponse(
+            generate_file(),
+            media_type=export_file["content_type"],
+            headers={"Content-Disposition": f"attachment; filename={export_file['filename']}"}
+        )
+        
+    except Exception as e:
+        print(f"Export download error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+# Mock functions
+async def estimate_export_rows(filters: dict) -> int:
+    """Simulate database query to estimate rows"""
+    await asyncio.sleep(0.05)
+    return (hash(str(filters)) % 10000) + 1000
+
+async def create_export_job(export_data: dict) -> str:
+    """Simulate export creation"""
+    await asyncio.sleep(0.1)
+    return f"exp_{asyncio.get_event_loop().time()}_{hash(str(export_data)) % 1000000}"
+
+async def get_export_status(export_id: str, agent_id: str) -> Optional[ExportStatus]:
+    """Simulate export status lookup"""
+    await asyncio.sleep(0.05)
+    return ExportStatus(
+        export_id=export_id,
+        status="completed",
+        created_at="2024-01-16T00:00:00Z",
+        estimated_rows=5000,
+        actual_rows=4876,
+        format="csv",
+        include_pii=False
+    )
+
+async def get_export_file(export_id: str, agent_id: str) -> Optional[dict]:
+    """Simulate file retrieval"""
+    await asyncio.sleep(0.05)
+    return {
+        "data": "name,email,created_at\nJohn Doe,john@example.com,2024-01-01",
+        "content_type": "text/csv",
+        "filename": f"export_{export_id}.csv",
+        "status": "completed"
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Data export service starting...")
+    print("Protected by APort data.export.create.v1 policy pack")
+    uvicorn.run(app, host="0.0.0.0", port=8000)

package/external/aport-policies/data.export.create.v1/policy.json

@@ -0,0 +1,133 @@
+{
+  "id": "data.export.create.v1",
+  "name": "Data Export Protection Policy",
+  "description": "Pre-action governance for data export operations. Enforces row limits, PII handling requirements, and export capability validation.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["data.export"],
+  "min_assurance": "L1",
+  "limits_required": ["max_export_rows", "allow_pii"],
+  "required_fields": ["export_type", "format", "filters"],
+  "optional_fields": ["include_pii", "date_range", "columns"],
+  "enforcement": {
+    "rows_lte": "limits.data.export.max_export_rows",
+    "pii_allowed": "limits.data.export.allow_pii"
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Cache /verify with ETag; 60s TTL",
+    "Subscribe to status webhooks for instant suspend",
+    "Implement data retention policies",
+    "Consider Verifiable Attestation for sensitive exports",
+    "Log all export attempts for audit compliance",
+    "Implement progressive disclosure for large datasets",
+    "Use secure delivery methods for sensitive data"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["export_type", "format", "filters"],
+    "properties": {
+      "export_type": {
+        "type": "string",
+        "enum": ["users", "orders", "transactions", "analytics"],
+        "description": "Type of data to export"
+      },
+      "format": {
+        "type": "string",
+        "enum": ["csv", "json", "xlsx", "parquet"],
+        "description": "Export format"
+      },
+      "filters": {
+        "type": "object",
+        "description": "Filter criteria for the export",
+        "properties": {
+          "date_from": { "type": "string", "format": "date" },
+          "date_to": { "type": "string", "format": "date" },
+          "status": { "type": "string" },
+          "category": { "type": "string" }
+        }
+      },
+      "include_pii": {
+        "type": "boolean",
+        "description": "Whether to include personally identifiable information"
+      },
+      "date_range": {
+        "type": "object",
+        "description": "Date range for the export",
+        "properties": {
+          "start": { "type": "string", "format": "date" },
+          "end": { "type": "string", "format": "date" }
+        }
+      },
+      "columns": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Specific columns to include"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.notion.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"notion.pages.export\"])"
+      },
+      "mcp_server": {
+        "type": "string",
+        "description": "Single MCP server being used (backward compatibility - use mcp_servers array for multiple)"
+      },
+      "mcp_tool": {
+        "type": "string",
+        "description": "Single MCP tool being used (backward compatibility - use mcp_tools array for multiple)"
+      },
+      "mcp_session": {
+        "type": "string",
+        "description": "MCP session identifier for audit trail (optional)"
+      }
+    }
+  },
+  "evaluation_rules": [
+    {
+      "name": "passport_status_active",
+      "condition": "passport.status == 'active'",
+      "deny_code": "oap.passport_suspended",
+      "description": "Passport must be active"
+    },
+    {
+      "name": "export_capability",
+      "condition": "'data.export' in passport.capabilities",
+      "deny_code": "oap.unknown_capability",
+      "description": "Agent must have data.export capability"
+    },
+    {
+      "name": "row_limit_check",
+      "condition": "estimated_rows <= limits.max_export_rows",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Export size must not exceed row limit"
+    },
+    {
+      "name": "pii_handling",
+      "condition": "NOT (include_pii AND NOT limits.allow_pii)",
+      "deny_code": "oap.pii_not_allowed",
+      "description": "PII export not allowed for this agent"
+    },
+    {
+      "name": "format_support",
+      "condition": "format in ['csv', 'json', 'xlsx', 'parquet']",
+      "deny_code": "oap.format_unsupported",
+      "description": "Export format must be supported"
+    }
+  ],
+  "cache": {
+    "default_ttl_seconds": 60,
+    "suspend_invalidate_seconds": 30
+  },
+  "deprecation": null,
+  "created_at": "2025-01-16T00:00:00Z",
+  "updated_at": "2025-01-30T00:00:00Z"
+}

package/external/aport-policies/data.report.ingest.v1/README.md

@@ -0,0 +1,134 @@
+# Report Data Ingestion Policy Pack v1
+
+Protect your data ingestion endpoints with APort's standardized policy pack. This pack ensures only verified agents with proper capabilities, assurance levels, and data quality controls can ingest report data with appropriate validation and monitoring.
+
+## What This Pack Protects
+
+- **Route**: `/data/report/ingest/*` (POST)
+- **Risk**: Data quality issues, stale data, unauthorized sources, compliance violations
+- **Impact**: Poor reporting quality, regulatory violations, audit findings, data integrity issues
+
+## Requirements
+
+| Requirement | Value | Description |
+|-------------|-------|-------------|
+| **Capability** | `data.report.ingest` | Agent must have data ingestion capability |
+| **Assurance** | `L2` or higher | Standard verification minimum |
+| **Limits** | `approved_sources.{report_type}[]` | Approved data sources per report type |
+| **Limits** | `max_data_age_seconds.{report_type}` | Maximum data age per report type |
+| **Limits** | `max_data_size_mb.{report_type}` | Maximum data size per report type |
+| **Limits** | `max_ingest_frequency_per_hour.{report_type}` | Maximum ingestion frequency |
+| **Limits** | `data_quality_threshold.{report_type}` | Minimum data quality score |
+| **Limits** | `required_validation_checks.{report_type}[]` | Required validation checks |
+| **Regions** | Must match | Agent must be authorized in caller's region |
+| **Idempotency** | Required | Prevents duplicate ingestion |
+
+## Implementation
+
+### Express.js
+
+```javascript
+const { requirePolicy } = require('@aporthq/middleware-express');
+
+// Option 1: Explicit agent ID (preferred)
+app.post('/data/report/ingest', 
+  requirePolicy('data.report.ingest.v1', 'ap_a2d10232c6534523812423eec8a1425c45678'), 
+  async (req, res) => {
+    // Your data ingestion logic here
+    // req.policyResult contains the verified passport
+    const { report_type, data_source_id, data_timestamp } = req.body;
+    const passport = req.policyResult.passport;
+    
+    // Process data ingestion...
+    res.json({ success: true, ingest_id: generateId() });
+  }
+);
+```
+
+**Client Request Example:**
+```javascript
+fetch('/data/report/ingest', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'
+  },
+  body: JSON.stringify({
+    report_type: "ESG",
+    data_source_id: "api.climate-data.com",
+    data_timestamp: "2025-01-30T10:00:00Z",
+    metric_type: "carbon_emissions",
+    data_size_mb: 5.2,
+    validation_checks: ["schema_validation", "range_check"],
+    data_quality_score: 0.95,
+    idempotency_key: "ingest-esg-123"
+  })
+});
+```
+
+## Best Practices
+
+1. **Cache Verification**: Cache `/verify` responses with ETag for 300 seconds
+2. **Webhook Integration**: Subscribe to `status.changed` webhooks for instant suspension
+3. **Verifiable Attestation**: Log all data ingestion attempts for compliance
+4. **Data Quality Scoring**: Implement data quality scoring before ingestion
+5. **Data Lineage Tracking**: Use data lineage tracking for audit compliance
+6. **Progressive Validation**: Implement progressive data validation checks
+7. **Anomaly Monitoring**: Monitor for data anomalies and unusual patterns
+8. **Data Encryption**: Use data encryption for sensitive report data
+9. **Data Retention**: Implement data retention policies based on report type
+10. **Source Reputation**: Maintain data source reputation scoring
+11. **Idempotency**: Use idempotency keys to prevent duplicate ingestion
+12. **Freshness Monitoring**: Implement data freshness monitoring and alerts
+
+## Support
+
+- [Documentation](https://aport.io/docs/policies/data.report.ingest.v1)
+- [Community](https://github.com/aporthq/community)
+- [Support](https://aport.io/support)
+
+---
+**Last Updated**: 2025-01-30 00:00:00 UTC
+
+
+## Required Context
+
+This policy requires the following context (JSON Schema):
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "report_type",
+    "data_source_id",
+    "data_timestamp"
+  ],
+  "properties": {
+    "report_type": {
+      "type": "string",
+      "description": "The type of report being generated (e.g., 'ESG', 'QuarterlyFinancials')."
+    },
+    "data_source_id": {
+      "type": "string",
+      "description": "A unique identifier for the source of the data being ingested (e.g., 'api.climate-data.com', 'internal-hr-db')."
+    },
+    "data_timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The ISO 8601 timestamp of when the data was generated."
+    },
+    "metric_type": {
+      "type": "string",
+      "description": "The specific metric this data point relates to (e.g., 'carbon_emissions', 'employee_diversity')."
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/data.report.ingest.v1?format=schema"
+```
+

package/external/aport-policies/data.report.ingest.v1/express.example.js

@@ -0,0 +1,105 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply data.report.ingest policy to all data ingestion routes
+app.post(
+  "/data/report/ingest",
+  requirePolicy("data.report.ingest.v1"),
+  async (req, res) => {
+    try {
+      const {
+        report_type,
+        data_source_id,
+        data_timestamp,
+        metric_type,
+        data_size_mb,
+        validation_checks,
+        data_quality_score,
+        ingest_reason,
+        idempotency_key,
+      } = req.body;
+
+      const passport = req.policyResult.passport;
+
+      // Additional business logic validation
+      if (!report_type || !data_source_id || !data_timestamp) {
+        return res.status(400).json({ error: "Missing required fields" });
+      }
+
+      // Process data ingestion using your data system
+      const ingest_id = await processDataIngestion({
+        report_type,
+        data_source_id,
+        data_timestamp,
+        metric_type,
+        data_size_mb,
+        validation_checks,
+        data_quality_score,
+        ingest_reason,
+        idempotency_key,
+        agent_id: passport.passport_id,
+        agent_name: passport.metadata?.template_name || "Unknown Agent",
+      });
+
+      // Log the ingestion
+      console.log(
+        `Data ingestion processed: ${ingest_id} for ${report_type} report by agent ${passport.passport_id}`
+      );
+
+      res.json({
+        success: true,
+        ingest_id,
+        report_type,
+        data_source_id,
+        data_timestamp,
+        status: "processed",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Data ingestion processing error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock data ingestion processing function
+async function processDataIngestion({
+  report_type,
+  data_source_id,
+  data_timestamp,
+  metric_type,
+  data_size_mb,
+  validation_checks,
+  data_quality_score,
+  ingest_reason,
+  idempotency_key,
+  agent_id,
+}) {
+  // Simulate data system call
+  await new Promise((resolve) => setTimeout(resolve, 150));
+
+  // Log ingestion details for audit
+  console.log(`Processing data ingestion:`, {
+    report_type,
+    data_source_id,
+    data_timestamp,
+    metric_type,
+    data_size_mb,
+    validation_checks,
+    data_quality_score,
+    ingest_reason,
+    idempotency_key,
+    agent_id,
+  });
+
+  return `ingest_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Data ingestion service running on port ${PORT}`);
+  console.log("Protected by APort data.report.ingest.v1 policy pack");
+});

package/external/aport-policies/data.report.ingest.v1/minimal-example.js

@@ -0,0 +1,68 @@
+/**
+ * Minimal Example: data.report.ingest.v1 Policy
+ *
+ * This is a quick-start example showing the basic usage of the data.report.ingest.v1 policy.
+ * For production use, see the full express.example.js file.
+ */
+
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Minimal data ingestion endpoint with policy protection
+app.post(
+  "/data/ingest",
+  requirePolicy("data.report.ingest.v1"),
+  async (req, res) => {
+    try {
+      const { report_type, data_source_id, data_timestamp } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Process the data ingestion (your business logic here)
+      const ingest_id = `ingest_${Date.now()}`;
+
+      console.log(
+        `Data ingestion processed: ${ingest_id} for ${report_type} report`
+      );
+
+      res.json({
+        success: true,
+        ingest_id,
+        report_type,
+        data_source_id,
+        data_timestamp,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Data ingestion error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Example client request
+const exampleRequest = {
+  report_type: "ESG",
+  data_source_id: "api.climate-data.com",
+  data_timestamp: "2025-01-30T10:00:00Z",
+  metric_type: "carbon_emissions",
+  data_size_mb: 5.2,
+  validation_checks: ["schema_validation", "range_check"],
+  data_quality_score: 0.95,
+  idempotency_key: "ingest-esg-123",
+};
+
+console.log("Example request:", JSON.stringify(exampleRequest, null, 2));
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Minimal data ingestion service running on port ${PORT}`);
+  console.log("Protected by APort data.report.ingest.v1 policy");
+  console.log(
+    `Try: curl -X POST http://localhost:${PORT}/data/ingest -H "Content-Type: application/json" -d '${JSON.stringify(
+      exampleRequest
+    )}'`
+  );
+});