@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/finance.payment.payout.v1/policy.json

@@ -0,0 +1,181 @@
+{
+  "id": "finance.payment.payout.v1",
+  "name": "Payment Payout Policy",
+  "description": "Pre-action governance for payment payout operations. Enforces per-currency caps, destination restrictions, and compliance requirements.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["payments.payout"],
+  "min_assurance": "L3",
+  "limits_required": [
+    "supported_currencies",
+    "currency_limits",
+    "allowed_destination_types",
+    "allowed_recipients",
+    "max_payouts_per_day",
+    "compliance_checks_required",
+    "approval_required"
+  ],
+  "required_fields": [
+    "amount",
+    "currency",
+    "destination_type",
+    "destination_id",
+    "payout_method",
+    "idempotency_key"
+  ],
+  "optional_fields": ["description", "compliance_notes", "approval_required"],
+  "enforcement": {
+    "currency_supported": true,
+    "destination_type_allowed": true,
+    "daily_cap_check": true,
+    "compliance_required": true,
+    "idempotency_required": true
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Cache /verify with ETag; 60s TTL",
+    "Subscribe to status webhooks for instant suspend",
+    "Log all payout attempts for Verifiable Attestation",
+    "Implement daily payout tracking per currency to prevent abuse",
+    "Always use unique idempotency keys to prevent duplicate payouts",
+    "Verify destination accounts before processing payouts",
+    "Implement compliance checks for high-value payouts",
+    "Maintain audit trails for all payout operations"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": [
+      "amount",
+      "currency",
+      "destination_type",
+      "destination_id",
+      "payout_method",
+      "idempotency_key"
+    ],
+    "properties": {
+      "amount": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "Payout amount in minor units (e.g., cents)"
+      },
+      "currency": {
+        "type": "string",
+        "pattern": "^[A-Z]{3}$",
+        "description": "ISO 4217 currency code"
+      },
+      "destination_type": {
+        "type": "string",
+        "enum": ["bank_account", "digital_wallet", "crypto_address"],
+        "description": "Type of destination account"
+      },
+      "destination_id": {
+        "type": "string",
+        "description": "Destination account identifier"
+      },
+      "payout_method": {
+        "type": "string",
+        "enum": ["wire_transfer", "ach", "crypto_transfer", "digital_wallet"],
+        "description": "Method of payout"
+      },
+      "idempotency_key": {
+        "type": "string",
+        "minLength": 8,
+        "description": "Idempotency key for duplicate prevention"
+      },
+      "description": {
+        "type": "string",
+        "description": "Optional payout description"
+      },
+      "compliance_notes": {
+        "type": "string",
+        "description": "Compliance verification notes"
+      },
+      "approval_required": {
+        "type": "boolean",
+        "description": "Whether payout requires manual approval"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.stripe.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"stripe.payouts.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": "assurance_minimum",
+      "condition": "passport.assurance_level >= 'L3'",
+      "deny_code": "oap.assurance_insufficient",
+      "description": "Assurance level must be L3 or higher for payouts"
+    },
+    {
+      "name": "currency_supported",
+      "condition": "currency in limits.supported_currencies",
+      "deny_code": "oap.currency_unsupported",
+      "description": "Currency must be supported"
+    },
+    {
+      "name": "per_tx_amount_cap",
+      "condition": "amount <= limits.currency_limits[currency].max_per_tx",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Amount must not exceed per-transaction limit"
+    },
+    {
+      "name": "destination_type_allowed",
+      "condition": "destination_type in limits.allowed_destination_types",
+      "deny_code": "oap.destination_type_forbidden",
+      "description": "Destination type must be allowed"
+    },
+    {
+      "name": "daily_cap_check",
+      "condition": "daily_payout_count < limits.max_payouts_per_day",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Daily payout limit must not be exceeded"
+    },
+    {
+      "name": "compliance_check",
+      "condition": "limits.compliance_checks_required == false OR compliance_notes is not empty",
+      "deny_code": "oap.compliance_check_required",
+      "description": "Compliance checks must be completed for high-value payouts"
+    },
+    {
+      "name": "idempotency_check",
+      "condition": "idempotency_key not in recent_keys",
+      "deny_code": "oap.idempotency_conflict",
+      "description": "Idempotency key must be unique"
+    }
+  ],
+  "cache": {
+    "default_ttl_seconds": 60,
+    "suspend_invalidate_seconds": 30
+  },
+  "deprecation": null,
+  "created_at": "2025-01-30T00:00:00Z",
+  "updated_at": "2025-01-30T00:00:00Z"
+}

package/external/aport-policies/finance.payment.refund.v1/README.md

@@ -0,0 +1,275 @@
+# Refunds Protection Policy Pack v1
+
+Protect your refund endpoints with APort's standardized policy pack. This pack ensures only verified agents with proper capabilities, assurance levels, and transaction limits can process refunds.
+
+## What This Pack Protects
+
+- **Route**: `/refunds/*` (POST, PUT, PATCH)
+- **Risk**: Financial transactions, potential fraud, regulatory compliance
+- **Impact**: Direct monetary loss, customer disputes, audit findings
+
+## Requirements
+
+| Requirement | Value | Description |
+|-------------|-------|-------------|
+| **Capability** | `finance.payment.refund` | Agent must have refund capability |
+| **Assurance** | `L2` or higher | Email + GitHub verification minimum |
+| **Limits** | `refund_amount_max_per_tx` | Maximum per-transaction refund amount |
+| **Limits** | `refund_amount_daily_cap` | Maximum daily refund total |
+| **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.post('/refunds', 
+  requirePolicy('finance.payment.refund.v1', 'ap_a2d10232c6534523812423eec8a1425c45678'), 
+  async (req, res) => {
+    // Your refund logic here
+    // req.policyResult contains the verified passport
+    const { amount, reason } = req.body;
+    const passport = req.policyResult.passport;
+    
+    // Process refund...
+    res.json({ success: true, refund_id: generateId() });
+  }
+);
+
+// Option 2: Header fallback (backward compatible)
+app.post('/refunds', 
+  requirePolicy('finance.payment.refund.v1'), 
+  async (req, res) => {
+    // Your refund logic here
+    // req.policyResult contains the verified passport
+    const { amount, reason } = req.body;
+    const passport = req.policyResult.passport;
+    
+    // Process refund...
+    res.json({ success: true, refund_id: generateId() });
+  }
+);
+```
+
+**Client Request Example:**
+```javascript
+// The client must include the agent ID in the header (for Option 2)
+fetch('/refunds', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'  // ← Agent ID passed here
+  },
+  body: JSON.stringify({
+    amount: 25.00,
+    reason: 'Customer requested refund'
+  })
+});
+```
+
+### FastAPI
+
+```python
+from aport.middleware import require_policy
+
+@app.post("/refunds")
+@require_policy("finance.payment.refund.v1")
+async def process_refund(request: Request, refund_data: RefundRequest):
+    # Your refund logic here
+    # request.state.policy_result contains the verified passport
+    passport = request.state.policy_result.passport
+    
+    # Process refund...
+    return {"success": True, "refund_id": generate_id()}
+```
+
+**Client Request Example:**
+```python
+import requests
+
+# The client must include the agent ID in the header
+response = requests.post('/refunds', 
+    headers={
+        'Content-Type': 'application/json',
+        'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'  # ← Agent ID passed here
+    },
+    json={
+        'amount': 25.00,
+        'reason': 'Customer requested refund'
+    }
+)
+```
+
+## How It Works
+
+The `requirePolicy('finance.payment.refund.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 (`finance.payment.refund.v1`)
+   - **API Call**: Calls `/api/verify/policy/finance.payment.refund.v1` with agent ID and context
+   - **Requirements Check**: Validates agent meets finance.payment.refund.v1 requirements:
+     - Has `finance.payment.refund` capability
+     - Meets minimum assurance level (L2+)
+     - Within transaction and daily limits
+     - Authorized in the request region
+
+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": "MISSING_CAPABILITY",
+  "message": "Agent missing required capability: finance.payment.refund",
+  "policy_id": "finance.payment.refund.v1",
+  "agent_id": "ap_a2d10232c6534523812423eec8a1425c45678",
+  "upgrade_instructions": "Add 'finance.payment.refund' capability to your passport"
+}
+```
+
+## Test Payloads
+
+### Valid Request
+```json
+{
+  "amount": 25.00,
+  "reason": "Customer requested refund",
+  "order_id": "ORD-12345"
+}
+```
+
+### Invalid Request (exceeds limit)
+```json
+{
+  "amount": 1000.00,
+  "reason": "Customer requested refund",
+  "order_id": "ORD-12345"
+}
+```
+*Returns 403: "Amount $1000.00 exceeds limit $500.00"*
+
+## 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 refund attempts for compliance
+4. **Daily Tracking**: Implement daily spend tracking to prevent abuse
+5. **Error Handling**: Provide clear error messages to help agents self-remediate
+
+## Compliance Badge
+
+Agents that meet this policy's requirements can display the "Refunds-Ready" badge:
+
+```markdown
+[![Refunds-Ready](https://api.aport.io/badge/ap_a2d10232c6534523812423eec8a1425c45678.svg)](https://aport.io/agents/ap_a2d10232c6534523812423eec8a1425c45678)
+```
+
+## Support
+
+- [Documentation](https://aport.io/docs/policies/finance.payment.refund.v1)
+- [Community](https://github.com/aporthq/community)
+- [Support](https://aport.io/support)
+
+---
+**Last Updated**: 2025-09-24 23:15:00 UTC
+
+
+## Required Context
+
+This policy requires the following context (JSON Schema):
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "order_id",
+    "customer_id",
+    "amount",
+    "currency",
+    "region",
+    "reason_code",
+    "idempotency_key"
+  ],
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Original order identifier"
+    },
+    "customer_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Customer identifier"
+    },
+    "amount": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Refund amount in minor units (e.g., cents)"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "ISO 4217 currency code"
+    },
+    "region": {
+      "type": "string",
+      "description": "Geographic region"
+    },
+    "reason_code": {
+      "type": "string",
+      "description": "Refund reason code"
+    },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 8,
+      "description": "Idempotency key for duplicate prevention"
+    },
+    "note": {
+      "type": "string",
+      "description": "Optional refund note"
+    },
+    "merchant_case_id": {
+      "type": "string",
+      "description": "Merchant's internal case ID"
+    },
+    "order_currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "Original order currency"
+    },
+    "order_total_minor": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Original order total in minor units"
+    },
+    "already_refunded_minor": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount already refunded in minor units"
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/finance.payment.refund.v1?format=schema"
+```
+

package/external/aport-policies/finance.payment.refund.v1/express.example.js

@@ -0,0 +1,167 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply refunds policy to all refund routes
+app.post(
+  "/refunds",
+  requirePolicy("finance.payment.refund.v1"),
+  async (req, res) => {
+    try {
+      const {
+        amount_minor,
+        currency,
+        order_id,
+        customer_id,
+        reason_code,
+        region,
+        idempotency_key,
+        order_currency,
+        order_total_minor,
+        already_refunded_minor,
+        note,
+        merchant_case_id,
+      } = req.body;
+
+      const passport = req.policyResult.passport;
+
+      // Additional business logic validation
+      if (amount_minor <= 0) {
+        return res.status(400).json({ error: "Invalid refund amount" });
+      }
+
+      // Process refund using your payment processor
+      const refund_id = await processRefund({
+        amount_minor,
+        currency,
+        order_id,
+        customer_id,
+        reason_code,
+        region,
+        idempotency_key,
+        order_currency,
+        order_total_minor,
+        already_refunded_minor,
+        note,
+        merchant_case_id,
+        agent_id: passport.agent_id,
+        agent_name: passport.name,
+      });
+
+      // Log the transaction
+      console.log(
+        `Refund processed: ${refund_id} for ${amount_minor} ${currency} by agent ${passport.agent_id}`
+      );
+
+      res.json({
+        success: true,
+        refund_id,
+        amount_minor,
+        currency,
+        status: "processed",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Refund processing error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Batch refunds endpoint
+app.post(
+  "/refunds/batch",
+  requirePolicy("finance.payment.refund.v1"),
+  async (req, res) => {
+    try {
+      const { refunds } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Group refunds by currency for daily cap checking
+      const currencyTotals = {};
+      for (const refund of refunds) {
+        const currency = refund.currency || "USD";
+        currencyTotals[currency] =
+          (currencyTotals[currency] || 0) + (refund.amount_minor || 0);
+      }
+
+      // Check daily caps per currency
+      for (const [currency, totalAmount] of Object.entries(currencyTotals)) {
+        const currencyLimits = passport.limits?.currency_limits?.[currency];
+        if (
+          currencyLimits?.daily_cap &&
+          totalAmount > currencyLimits.daily_cap
+        ) {
+          return res.status(403).json({
+            error: "Batch total exceeds daily cap",
+            currency,
+            total: totalAmount,
+            limit: currencyLimits.daily_cap,
+          });
+        }
+      }
+
+      // Process batch refunds
+      const results = await Promise.all(
+        refunds.map((refund) =>
+          processRefund({
+            ...refund,
+            agent_id: passport.agent_id,
+          })
+        )
+      );
+
+      res.json({
+        success: true,
+        processed: results.length,
+        currency_totals: currencyTotals,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Batch refund error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock refund processing function
+async function processRefund({
+  amount_minor,
+  currency,
+  order_id,
+  customer_id,
+  reason_code,
+  region,
+  idempotency_key,
+  order_currency,
+  order_total_minor,
+  already_refunded_minor,
+  note,
+  merchant_case_id,
+  agent_id,
+}) {
+  // Simulate payment processor call
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  // Log refund details for audit
+  console.log(`Processing refund:`, {
+    amount_minor,
+    currency,
+    order_id,
+    customer_id,
+    reason_code,
+    region,
+    idempotency_key,
+    agent_id,
+  });
+
+  return `ref_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Refunds service running on port ${PORT}`);
+  console.log("Protected by APort finance.payment.refund.v1 policy pack");
+});