@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/governance.data.access.v1/README.md

@@ -0,0 +1,292 @@
+# Data Access Governance Policy Pack v1
+
+Protect your data access endpoints with APort's standardized policy pack. This pack ensures only verified agents with proper capabilities, assurance levels, and data access permissions can access sensitive data based on classification, entity types, and jurisdictional boundaries.
+
+## What This Pack Protects
+
+- **Route**: `/data/access/*` (GET, POST)
+- **Risk**: Data breaches, privacy violations, regulatory compliance, unauthorized access
+- **Impact**: Data exposure, GDPR violations, audit findings, reputational damage
+
+## Requirements
+
+| Requirement | Value | Description |
+|-------------|-------|-------------|
+| **Capability** | `data.access` | Agent must have data access capability |
+| **Assurance** | `L3` or higher | Enhanced verification minimum |
+| **Limits** | `allowed_classifications[]` | Allowed data classifications (PII, Financial, HR, ClientTier1) |
+| **Limits** | `permissions.{classification}.allowed_entity_types[]` | Entity types allowed per classification |
+| **Limits** | `permissions.{classification}.allowed_actions[]` | Actions allowed per classification |
+| **Limits** | `allowed_jurisdictions[]` | Allowed data jurisdictions |
+| **Limits** | `max_rows_per_export` | Maximum rows per data export |
+| **Limits** | `allowed_destination_jurisdictions[]` | Allowed destination jurisdictions for data transfer |
+| **Limits** | `balance_inquiry_cap_usd` | Maximum account balance for inquiry access |
+| **Regions** | Must match | Agent must be authorized in caller's region |
+
+## Implementation
+
+### Express.js
+
+```javascript
+const { requirePolicy } = require('@aporthq/middleware-express');
+
+// Option 1: Explicit agent ID (preferred)
+app.get('/data/access', 
+  requirePolicy('governance.data.access.v1', 'ap_a2d10232c6534523812423eec8a1425c45678'), 
+  async (req, res) => {
+    // Your data access logic here
+    // req.policyResult contains the verified passport
+    const { data_classification, accessing_entity_id, resource_id } = req.query;
+    const passport = req.policyResult.passport;
+    
+    // Process data access...
+    res.json({ success: true, data: retrievedData });
+  }
+);
+
+// Option 2: Header fallback (backward compatible)
+app.get('/data/access', 
+  requirePolicy('governance.data.access.v1'), 
+  async (req, res) => {
+    // Your data access logic here
+    // req.policyResult contains the verified passport
+    const { data_classification, accessing_entity_id, resource_id } = req.query;
+    const passport = req.policyResult.passport;
+    
+    // Process data access...
+    res.json({ success: true, data: retrievedData });
+  }
+);
+```
+
+**Client Request Example:**
+```javascript
+// The client must include the agent ID in the header (for Option 2)
+fetch('/data/access?data_classification=PII&accessing_entity_id=emp_123&resource_id=user_456', {
+  method: 'GET',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'  // ← Agent ID passed here
+  }
+});
+```
+
+### FastAPI
+
+```python
+from aport.middleware import require_policy
+
+@app.get("/data/access")
+@require_policy("governance.data.access.v1")
+async def access_data(request: Request, data_classification: str, accessing_entity_id: str, resource_id: str):
+    # Your data access logic here
+    # request.state.policy_result contains the verified passport
+    passport = request.state.policy_result.passport
+    
+    # Process data access...
+    return {"success": True, "data": retrieved_data}
+```
+
+**Client Request Example:**
+```python
+import requests
+
+# The client must include the agent ID in the header
+response = requests.get('/data/access', 
+    headers={
+        'Content-Type': 'application/json',
+        'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'  # ← Agent ID passed here
+    },
+    params={
+        'data_classification': 'PII',
+        'accessing_entity_id': 'emp_123',
+        'resource_id': 'user_456'
+    }
+)
+```
+
+## How It Works
+
+The `requirePolicy('governance.data.access.v1', agentId?)` middleware implements a flexible approach:
+
+1. **Agent ID Resolution** (in order of preference):
+   - **Function Parameter**: Uses explicit `agentId` if provided
+   - **Header Fallback**: Reads `X-Agent-Passport-Id` header from request
+   - **Validation**: Ensures agent ID format is valid (`ap_xxxxxxxxxxxxx`)
+   - **Failure**: Returns 400 error if neither provided
+
+2. **Policy Validation**:
+   - **Format Check**: Validates policy ID format (`governance.data.access.v1`)
+   - **API Call**: Calls `/api/verify/policy/governance.data.access.v1` with agent ID and context
+   - **Requirements Check**: Validates agent meets governance.data.access.v1 requirements:
+     - Has `data.access` capability
+     - Meets minimum assurance level (L3+)
+     - Data classification is allowed
+     - Entity type is allowed for the classification
+     - Action type is allowed for the classification
+     - Jurisdiction is allowed
+     - Row count within limits (for exports)
+     - Destination jurisdiction allowed (for transfers)
+     - Balance inquiry within limits
+     - Access frequency within limits
+     - Data retention policy compliance
+
+3. **Result Handling**:
+   - **Success**: Adds `req.policyResult` with verified data and continues
+   - **Failure**: Returns 403 with detailed error information
+   - **Logging**: Logs violations for monitoring and debugging
+
+## Error Responses
+
+When policy checks fail, you'll receive a `403 Forbidden` with detailed error information:
+
+```json
+{
+  "error": "policy_violation",
+  "code": "oap.classification_forbidden",
+  "message": "Data classification 'Sensitive' is not allowed",
+  "policy_id": "governance.data.access.v1",
+  "agent_id": "ap_a2d10232c6534523812423eec8a1425c45678",
+  "upgrade_instructions": "Request access to this data classification in your passport"
+}
+```
+
+## Test Payloads
+
+### Valid Request
+```json
+{
+  "data_classification": "PII",
+  "accessing_entity_id": "emp_123",
+  "accessing_entity_type": "employee",
+  "resource_id": "user_456",
+  "action_type": "read",
+  "jurisdiction": "US",
+  "row_count": 100
+}
+```
+
+### Invalid Request (classification forbidden)
+```json
+{
+  "data_classification": "Sensitive",
+  "accessing_entity_id": "emp_123",
+  "accessing_entity_type": "employee",
+  "resource_id": "user_456"
+}
+```
+*Returns 403: "Data classification 'Sensitive' is not allowed"*
+
+## 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. **Verifiable Attestation**: Log all data access attempts for compliance
+4. **Data Classification**: Implement data classification tagging for all resources
+5. **Entity Access Matrices**: Maintain entity access matrices for different data types
+6. **Jurisdiction Awareness**: Use jurisdiction-aware data routing for compliance
+7. **Progressive Disclosure**: Implement progressive disclosure for sensitive data access
+8. **Access Monitoring**: Monitor access patterns for unusual behavior
+9. **Audit Trails**: Maintain audit trails for all data access operations
+10. **Encryption**: Use encryption for data in transit and at rest
+11. **Data Retention**: Implement data retention policies based on classification
+
+## Compliance Badge
+
+Agents that meet this policy's requirements can display the "Data-Access-Ready" badge:
+
+```markdown
+[![Data-Access-Ready](https://api.aport.io/badge/ap_a2d10232c6534523812423eec8a1425c45678.svg)](https://aport.io/agents/ap_a2d10232c6534523812423eec8a1425c45678)
+```
+
+## Support
+
+- [Documentation](https://aport.io/docs/policies/governance.data.access.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": [
+    "data_classification",
+    "accessing_entity_id",
+    "accessing_entity_type",
+    "resource_id"
+  ],
+  "properties": {
+    "data_classification": {
+      "type": "string",
+      "description": "The classification of the data being accessed (e.g., 'PII', 'Financial', 'HR', 'ClientTier1')."
+    },
+    "accessing_entity_id": {
+      "type": "string",
+      "description": "The unique ID of the entity (user, agent, employee) attempting the access."
+    },
+    "accessing_entity_type": {
+      "type": "string",
+      "enum": [
+        "employee",
+        "client",
+        "system_agent"
+      ],
+      "description": "The type of entity attempting the access."
+    },
+    "resource_id": {
+      "type": "string",
+      "description": "The unique ID of the data resource being accessed (e.g., account number, user profile ID)."
+    },
+    "action_type": {
+      "type": "string",
+      "enum": [
+        "read",
+        "export",
+        "delete",
+        "update"
+      ],
+      "default": "read",
+      "description": "The type of data access action being performed."
+    },
+    "jurisdiction": {
+      "type": "string",
+      "pattern": "^[A-Z]{2}$",
+      "description": "The ISO 3166-1 alpha-2 country code relevant to the data's jurisdiction."
+    },
+    "row_count": {
+      "type": "integer",
+      "description": "The number of rows/records being accessed or exported. Solves for Row Limits."
+    },
+    "destination_jurisdiction": {
+      "type": "string",
+      "pattern": "^[A-Z]{2}$",
+      "description": "The destination country code for data transfers. Solves for Data Locality."
+    },
+    "resource_attributes": {
+      "type": "object",
+      "description": "A flexible object for passing specific attributes of the resource being accessed. Solves for Balance Inquiry.",
+      "properties": {
+        "account_balance_usd": {
+          "type": "integer",
+          "description": "The balance of the account in USD minor units, used for balance-based access rules."
+        }
+      }
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/governance.data.access.v1?format=schema"
+```
+

package/external/aport-policies/governance.data.access.v1/express.example.js

@@ -0,0 +1,321 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply governance.data.access policy to all data access routes
+app.get(
+  "/data/access",
+  requirePolicy("governance.data.access.v1"),
+  async (req, res) => {
+    try {
+      const {
+        data_classification,
+        accessing_entity_id,
+        accessing_entity_type,
+        resource_id,
+        action_type,
+        jurisdiction,
+        row_count,
+        destination_jurisdiction,
+        resource_attributes,
+      } = req.query;
+
+      const passport = req.policyResult.passport;
+
+      // Additional business logic validation
+      if (!data_classification || !accessing_entity_id || !resource_id) {
+        return res.status(400).json({ error: "Missing required parameters" });
+      }
+
+      // Process data access using your data system
+      const access_id = await processDataAccess({
+        data_classification,
+        accessing_entity_id,
+        accessing_entity_type,
+        resource_id,
+        action_type: action_type || "read",
+        jurisdiction,
+        row_count: row_count ? parseInt(row_count) : undefined,
+        destination_jurisdiction,
+        resource_attributes: resource_attributes
+          ? JSON.parse(resource_attributes)
+          : undefined,
+        agent_id: passport.passport_id,
+        agent_name: passport.metadata?.template_name || "Unknown Agent",
+      });
+
+      // Log the data access
+      console.log(
+        `Data access processed: ${access_id} for ${data_classification} data by agent ${passport.passport_id}`
+      );
+
+      res.json({
+        success: true,
+        access_id,
+        data_classification,
+        resource_id,
+        action_type: action_type || "read",
+        status: "processed",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Data access processing error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Data export endpoint
+app.post(
+  "/data/export",
+  requirePolicy("governance.data.access.v1"),
+  async (req, res) => {
+    try {
+      const {
+        data_classification,
+        accessing_entity_id,
+        accessing_entity_type,
+        resource_id,
+        action_type,
+        jurisdiction,
+        row_count,
+        destination_jurisdiction,
+        export_format,
+        filters,
+      } = req.body;
+
+      const passport = req.policyResult.passport;
+
+      // Check row count limits
+      const maxRowsPerExport =
+        passport.limits?.data?.access?.max_rows_per_export;
+      if (maxRowsPerExport && row_count > maxRowsPerExport) {
+        return res.status(403).json({
+          error: "Export row count exceeds limit",
+          row_count,
+          limit: maxRowsPerExport,
+        });
+      }
+
+      // Process data export
+      const export_id = await processDataExport({
+        data_classification,
+        accessing_entity_id,
+        accessing_entity_type,
+        resource_id,
+        action_type: action_type || "export",
+        jurisdiction,
+        row_count,
+        destination_jurisdiction,
+        export_format,
+        filters,
+        agent_id: passport.passport_id,
+      });
+
+      res.json({
+        success: true,
+        export_id,
+        data_classification,
+        row_count,
+        export_format,
+        status: "exported",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Data export error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Balance inquiry endpoint
+app.get(
+  "/data/balance/:account_id",
+  requirePolicy("governance.data.access.v1"),
+  async (req, res) => {
+    try {
+      const { account_id } = req.params;
+      const { accessing_entity_id, accessing_entity_type } = req.query;
+      const passport = req.policyResult.passport;
+
+      // Get account balance
+      const balance_info = await getAccountBalance(
+        account_id,
+        accessing_entity_id,
+        passport.passport_id
+      );
+
+      if (!balance_info) {
+        return res.status(404).json({ error: "Account not found" });
+      }
+
+      // Check balance inquiry limits
+      const balanceInquiryCap =
+        passport.limits?.data?.access?.balance_inquiry_cap_usd;
+      if (balanceInquiryCap && balance_info.balance_usd >= balanceInquiryCap) {
+        return res.status(403).json({
+          error: "Account balance exceeds inquiry cap",
+          balance: balance_info.balance_usd,
+          cap: balanceInquiryCap,
+        });
+      }
+
+      res.json({
+        success: true,
+        account_id,
+        balance_usd: balance_info.balance_usd,
+        currency: balance_info.currency,
+        last_updated: balance_info.last_updated,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Balance inquiry error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Data access audit endpoint
+app.get(
+  "/data/access/audit",
+  requirePolicy("governance.data.access.v1"),
+  async (req, res) => {
+    try {
+      const { start_date, end_date, data_classification } = req.query;
+      const passport = req.policyResult.passport;
+
+      const audit_logs = await getDataAccessAuditLogs({
+        start_date,
+        end_date,
+        data_classification,
+        agent_id: passport.passport_id,
+      });
+
+      res.json({
+        success: true,
+        audit_logs,
+        total_entries: audit_logs.length,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Audit log error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock data access processing function
+async function processDataAccess({
+  data_classification,
+  accessing_entity_id,
+  accessing_entity_type,
+  resource_id,
+  action_type,
+  jurisdiction,
+  row_count,
+  destination_jurisdiction,
+  resource_attributes,
+  agent_id,
+}) {
+  // Simulate data system call
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  // Log data access details for audit
+  console.log(`Processing data access:`, {
+    data_classification,
+    accessing_entity_id,
+    accessing_entity_type,
+    resource_id,
+    action_type,
+    jurisdiction,
+    row_count,
+    destination_jurisdiction,
+    resource_attributes,
+    agent_id,
+  });
+
+  return `access_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+// Mock data export processing function
+async function processDataExport({
+  data_classification,
+  accessing_entity_id,
+  accessing_entity_type,
+  resource_id,
+  action_type,
+  jurisdiction,
+  row_count,
+  destination_jurisdiction,
+  export_format,
+  filters,
+  agent_id,
+}) {
+  // Simulate data export processing
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  console.log(`Processing data export:`, {
+    data_classification,
+    accessing_entity_id,
+    accessing_entity_type,
+    resource_id,
+    action_type,
+    jurisdiction,
+    row_count,
+    destination_jurisdiction,
+    export_format,
+    filters,
+    agent_id,
+  });
+
+  return `export_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+// Mock account balance lookup
+async function getAccountBalance(account_id, accessing_entity_id, agent_id) {
+  // Simulate account balance lookup
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  return {
+    account_id,
+    balance_usd: 50000, // $500.00 in cents
+    currency: "USD",
+    last_updated: new Date().toISOString(),
+  };
+}
+
+// Mock audit log lookup
+async function getDataAccessAuditLogs({
+  start_date,
+  end_date,
+  data_classification,
+  agent_id,
+}) {
+  // Simulate audit log lookup
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  return [
+    {
+      access_id: "access_123",
+      data_classification: "PII",
+      resource_id: "user_456",
+      action_type: "read",
+      timestamp: new Date().toISOString(),
+      agent_id,
+    },
+    {
+      access_id: "access_124",
+      data_classification: "Financial",
+      resource_id: "account_789",
+      action_type: "export",
+      timestamp: new Date().toISOString(),
+      agent_id,
+    },
+  ];
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Data access governance service running on port ${PORT}`);
+  console.log("Protected by APort governance.data.access.v1 policy pack");
+});