@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/code.repository.merge.v1/policy.json

@@ -0,0 +1,162 @@
+{
+  "id": "code.repository.merge.v1",
+  "name": "Repository Safety Policy",
+  "description": "Pre-action governance for repository operations. Enforces PR limits, merge controls, path restrictions, and review requirements for dev-first safety.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["repo.pr.create", "repo.merge"],
+  "min_assurance": "L2",
+  "limits_required": [
+    "max_prs_per_day",
+    "max_merges_per_day",
+    "max_pr_size_kb"
+  ],
+  "required_fields": ["repository", "action", "branch"],
+  "optional_fields": [
+    "base_branch",
+    "title",
+    "description",
+    "files_changed",
+    "lines_added",
+    "lines_removed"
+  ],
+  "enforcement": {
+    "allowed_repos_enforced": true,
+    "allowed_base_branches_enforced": true,
+    "path_allowlist_enforced": true,
+    "size_limits_enforced": true,
+    "review_requirements_enforced": true
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Implement repository allowlists to prevent unauthorized access",
+    "Use branch protection rules for critical branches",
+    "Monitor PR size and complexity to prevent oversized changes",
+    "Require code reviews for production merges",
+    "Log all repository operations for Verifiable Attestation",
+    "Use path allowlists to restrict file access patterns",
+    "Subscribe to status webhooks for instant suspend",
+    "Implement progressive limits for new agents",
+    "Use automated testing requirements for large changes"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["repository", "action", "branch"],
+    "properties": {
+      "repository": {
+        "type": "string",
+        "pattern": "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$",
+        "description": "Repository in owner/repo format"
+      },
+      "action": {
+        "type": "string",
+        "enum": [
+          "pr.create",
+          "pr.merge",
+          "pr.update",
+          "branch.create",
+          "branch.delete"
+        ],
+        "description": "Repository action being performed"
+      },
+      "branch": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Target branch name"
+      },
+      "base_branch": {
+        "type": "string",
+        "description": "Base branch for PR operations"
+      },
+      "title": {
+        "type": "string",
+        "maxLength": 200,
+        "description": "PR or commit title"
+      },
+      "description": {
+        "type": "string",
+        "maxLength": 5000,
+        "description": "PR or commit description"
+      },
+      "files_changed": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "List of files being changed"
+      },
+      "lines_added": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Number of lines added"
+      },
+      "lines_removed": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Number of lines removed"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.github.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"github.pull_requests.create\"])"
+      },
+      "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": "repo_capability",
+      "condition": "action in passport.capabilities",
+      "deny_code": "oap.unknown_capability",
+      "description": "Agent must have required repository capability"
+    },
+    {
+      "name": "pr_size_limit",
+      "condition": "lines_added + lines_removed <= limits.max_pr_size_kb * 1000",
+      "deny_code": "oap.limit_exceeded",
+      "description": "PR size must not exceed limit"
+    },
+    {
+      "name": "daily_pr_limit",
+      "condition": "daily_pr_count < limits.max_prs_per_day",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Daily PR limit must not be exceeded"
+    },
+    {
+      "name": "daily_merge_limit",
+      "condition": "daily_merge_count < limits.max_merges_per_day",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Daily merge limit must not be exceeded"
+    }
+  ],
+  "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.export.create.v1/README.md

@@ -0,0 +1,226 @@
+# Data Export Protection Policy Pack v1
+
+Protect your data export endpoints with APort's standardized policy pack. This pack ensures only verified agents with proper capabilities, row limits, and PII handling can export sensitive data.
+
+## What This Pack Protects
+
+- **Route**: `/exports/*` (GET, POST)
+- **Risk**: Data breaches, privacy violations, regulatory non-compliance
+- **Impact**: Customer data exposure, GDPR/CCPA violations, reputation damage
+
+## Requirements
+
+| Requirement | Value | Description |
+|-------------|-------|-------------|
+| **Capability** | `data.export` | Agent must have data export capability |
+| **Assurance** | `L1` or higher | Email verification minimum |
+| **Limits** | `max_export_rows` | Maximum number of rows per export |
+| **Limits** | `allow_pii` | Whether PII can be included in exports |
+
+## Implementation
+
+### Express.js
+
+```javascript
+const { requirePolicy } = require('@aporthq/middleware-express');
+
+app.post('/exports', requirePolicy('data.export.create.v1'), async (req, res) => {
+  // Your export logic here
+  // req.policyResult contains the verified passport
+  const { format, include_pii } = req.body;
+  const passport = req.policyResult.passport;
+  
+  // Check PII permission
+  if (include_pii && !passport.limits.allow_pii) {
+    return res.status(403).json({ error: 'PII export not allowed' });
+  }
+  
+  // Process export...
+  res.json({ success: true, export_id: generateId() });
+});
+```
+
+### FastAPI
+
+```python
+from aport.middleware import require_policy
+
+@app.post("/exports")
+@require_policy("data.export.create.v1")
+async def create_export(request: Request, export_data: ExportRequest):
+    # Your export logic here
+    # request.state.policy_result contains the verified passport
+    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="PII export not allowed")
+    
+    # Process export...
+    return {"success": True, "export_id": generate_id()}
+```
+
+## Error Responses
+
+When policy checks fail, you'll receive a `403 Forbidden` with detailed error information:
+
+```json
+{
+  "error": "policy_violation",
+  "code": "EXCEEDS_ROW_LIMIT",
+  "message": "Requested 10000 rows exceeds limit 5000",
+  "policy_id": "data.export.create.v1",
+  "agent_id": "ap_a2d10232c6534523812423eec8a1425c45678",
+  "upgrade_instructions": "Request smaller export or upgrade limits"
+}
+```
+
+## Test Payloads
+
+### Valid Request (CSV export)
+```json
+{
+  "format": "csv",
+  "include_pii": false,
+  "filters": {
+    "date_range": "2024-01-01 to 2024-12-31"
+  }
+}
+```
+
+### Valid Request (with PII)
+```json
+{
+  "format": "json",
+  "include_pii": true,
+  "filters": {
+    "user_id": "12345"
+  }
+}
+```
+*Requires `allow_pii: true` in agent limits*
+
+### Invalid Request (exceeds row limit)
+```json
+{
+  "format": "csv",
+  "include_pii": false,
+  "filters": {
+    "date_range": "2020-01-01 to 2024-12-31"
+  }
+}
+```
+*Returns 403: "Requested 50000 rows exceeds limit 10000"*
+
+## Best Practices
+
+1. **Cache Verification**: Cache `/verify` responses with ETag for 60 seconds
+2. **Webhook Integration**: Subscribe to `status.changed` webhooks for instant suspension
+3. **Data Retention**: Implement data retention policies for exported files
+4. **Verifiable Attestation**: Log all export attempts for compliance
+5. **PII Handling**: Clearly separate PII and non-PII export capabilities
+
+## Compliance Badge
+
+Agents that meet this policy's requirements can display the "Data Export-Ready" badge:
+
+```markdown
+[![Data Export-Ready](https://api.aport.io/badge/ap_a2d10232c6534523812423eec8a1425c45678.svg)](https://aport.io/agents/ap_a2d10232c6534523812423eec8a1425c45678)
+```
+
+## Support
+
+- [Documentation](https://aport.io/docs/policies/data.export.create.v1)
+- [Community](https://github.com/aporthq/community)
+- [Support](https://aport.io/support)
+
+
+## Required Context
+
+This policy requires the following context (JSON Schema):
+
+```json
+{
+  "$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"
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/data.export.create.v1?format=schema"
+```
+

package/external/aport-policies/data.export.create.v1/express.example.js

@@ -0,0 +1,172 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply data export policy to all export routes
+app.post(
+  "/exports",
+  requirePolicy("data.export.create.v1"),
+  async (req, res) => {
+    try {
+      const { format, include_pii, filters } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Check PII permission
+      if (include_pii && !passport.limits.allow_pii) {
+        return res.status(403).json({
+          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)
+      const estimatedRows = await estimateExportRows(filters);
+
+      // Check row limit
+      if (estimatedRows > passport.limits.max_export_rows) {
+        return res.status(403).json({
+          error: "Export exceeds row limit",
+          requested: estimatedRows,
+          limit: passport.limits.max_export_rows,
+          upgrade_instructions: "Request smaller export or upgrade limits",
+        });
+      }
+
+      // Process export
+      const export_id = await createExport({
+        format,
+        include_pii,
+        filters,
+        agent_id: passport.agent_id,
+        agent_name: passport.name,
+        estimated_rows: estimatedRows,
+      });
+
+      // Log the export request
+      console.log(
+        `Export created: ${export_id} (${estimatedRows} rows) by agent ${passport.agent_id}`
+      );
+
+      res.json({
+        success: true,
+        export_id,
+        format,
+        estimated_rows: estimatedRows,
+        status: "processing",
+      });
+    } catch (error) {
+      console.error("Export creation error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Get export status
+app.get(
+  "/exports/:export_id",
+  requirePolicy("data.export.create.v1"),
+  async (req, res) => {
+    try {
+      const { export_id } = req.params;
+      const passport = req.policyResult.passport;
+
+      const export_info = await getExportStatus(export_id, passport.agent_id);
+
+      if (!export_info) {
+        return res.status(404).json({ error: "Export not found" });
+      }
+
+      res.json(export_info);
+    } catch (error) {
+      console.error("Export status error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Download export file
+app.get(
+  "/exports/:export_id/download",
+  requirePolicy("data.export.create.v1"),
+  async (req, res) => {
+    try {
+      const { export_id } = req.params;
+      const passport = req.policyResult.passport;
+
+      const export_file = await getExportFile(export_id, passport.agent_id);
+
+      if (!export_file) {
+        return res.status(404).json({ error: "Export file not found" });
+      }
+
+      if (export_file.status !== "completed") {
+        return res.status(400).json({ error: "Export not ready for download" });
+      }
+
+      // Set appropriate headers for file download
+      res.setHeader("Content-Type", export_file.content_type);
+      res.setHeader(
+        "Content-Disposition",
+        `attachment; filename="${export_file.filename}"`
+      );
+      res.send(export_file.data);
+    } catch (error) {
+      console.error("Export download error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock functions
+async function estimateExportRows(filters) {
+  // Simulate database query to estimate rows
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  return Math.floor(Math.random() * 10000) + 1000;
+}
+
+async function createExport({
+  format,
+  include_pii,
+  filters,
+  agent_id,
+  estimated_rows,
+}) {
+  // Simulate export creation
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  return `exp_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+async function getExportStatus(export_id, agent_id) {
+  // Simulate export status lookup
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  return {
+    export_id,
+    status: "completed",
+    created_at: new Date().toISOString(),
+    estimated_rows: 5000,
+    actual_rows: 4876,
+    format: "csv",
+    include_pii: false,
+  };
+}
+
+async function getExportFile(export_id, agent_id) {
+  // Simulate file retrieval
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  return {
+    data: "name,email,created_at\nJohn Doe,john@example.com,2024-01-01",
+    content_type: "text/csv",
+    filename: `export_${export_id}.csv`,
+    status: "completed",
+  };
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Data export service running on port ${PORT}`);
+  console.log("Protected by APort data.export.create.v1 policy pack");
+});