@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/finance.payment.refund.v1/fastapi.example.py

@@ -0,0 +1,136 @@
+from fastapi import FastAPI, HTTPException, Request
+from pydantic import BaseModel
+from aport.middleware import require_policy
+import asyncio
+from typing import List, Optional
+
+app = FastAPI(title="Refunds Service", version="1.0.0")
+
+class RefundRequest(BaseModel):
+    amount_minor: int
+    currency: str
+    order_id: str
+    customer_id: str
+    reason_code: str
+    region: str
+    idempotency_key: str
+    order_currency: Optional[str] = None
+    order_total_minor: Optional[int] = None
+    already_refunded_minor: Optional[int] = None
+    note: Optional[str] = None
+    merchant_case_id: Optional[str] = None
+
+class BatchRefundRequest(BaseModel):
+    refunds: List[RefundRequest]
+
+@app.post("/refunds")
+@require_policy("finance.payment.refund.v1")
+async def process_refund(request: Request, refund_data: RefundRequest):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Additional business logic validation
+        if refund_data.amount_minor <= 0:
+            raise HTTPException(status_code=400, detail="Invalid refund amount")
+        
+        # Process refund using your payment processor
+        refund_id = await process_refund_payment({
+            "amount_minor": refund_data.amount_minor,
+            "currency": refund_data.currency,
+            "order_id": refund_data.order_id,
+            "customer_id": refund_data.customer_id,
+            "reason_code": refund_data.reason_code,
+            "region": refund_data.region,
+            "idempotency_key": refund_data.idempotency_key,
+            "order_currency": refund_data.order_currency,
+            "order_total_minor": refund_data.order_total_minor,
+            "already_refunded_minor": refund_data.already_refunded_minor,
+            "note": refund_data.note,
+            "merchant_case_id": refund_data.merchant_case_id,
+            "agent_id": passport.agent_id,
+            "agent_name": passport.name
+        })
+        
+        # Log the transaction
+        print(f"Refund processed: {refund_id} for {refund_data.amount_minor} {refund_data.currency} by agent {passport.agent_id}")
+        
+        return {
+            "success": True,
+            "refund_id": refund_id,
+            "amount_minor": refund_data.amount_minor,
+            "currency": refund_data.currency,
+            "status": "processed",
+            "decision_id": request.state.policy_result.decision_id
+        }
+        
+    except Exception as e:
+        print(f"Refund processing error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.post("/refunds/batch")
+@require_policy("finance.payment.refund.v1")
+async def process_batch_refunds(request: Request, batch_data: BatchRefundRequest):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Group refunds by currency for daily cap checking
+        currency_totals = {}
+        for refund in batch_data.refunds:
+            currency = refund.currency
+            currency_totals[currency] = currency_totals.get(currency, 0) + refund.amount_minor
+        
+        # Check daily caps per currency
+        for currency, total_amount in currency_totals.items():
+            currency_limits = passport.limits.get("currency_limits", {}).get(currency)
+            if currency_limits and currency_limits.get("daily_cap") and total_amount > currency_limits["daily_cap"]:
+                raise HTTPException(
+                    status_code=403,
+                    detail={
+                        "error": "Batch total exceeds daily cap",
+                        "currency": currency,
+                        "total": total_amount,
+                        "limit": currency_limits["daily_cap"]
+                    }
+                )
+        
+        # Process batch refunds
+        results = await asyncio.gather(*[
+            process_refund_payment({
+                "amount_minor": refund.amount_minor,
+                "currency": refund.currency,
+                "order_id": refund.order_id,
+                "customer_id": refund.customer_id,
+                "reason_code": refund.reason_code,
+                "region": refund.region,
+                "idempotency_key": refund.idempotency_key,
+                "agent_id": passport.agent_id
+            })
+            for refund in batch_data.refunds
+        ])
+        
+        return {
+            "success": True,
+            "processed": len(results),
+            "currency_totals": currency_totals,
+            "decision_id": request.state.policy_result.decision_id
+        }
+        
+    except Exception as e:
+        print(f"Batch refund error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+async def process_refund_payment(refund_data: dict) -> str:
+    """Mock refund processing function"""
+    # Simulate payment processor call
+    await asyncio.sleep(0.1)
+    
+    # Log refund details for audit
+    print(f"Processing refund: {refund_data}")
+    
+    return f"ref_{asyncio.get_event_loop().time()}_{hash(str(refund_data)) % 1000000}"
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Refunds service starting...")
+    print("Protected by APort finance.payment.refund.v1 policy pack")
+    uvicorn.run(app, host="0.0.0.0", port=8000)

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

@@ -0,0 +1,183 @@
+/**
+ * Minimal Refunds v1 Policy Example
+ *
+ * This is a simple, working example of how to use the finance.payment.refund.v1 policy
+ * with all required fields and proper error handling.
+ */
+
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express"); // Assuming this exists
+
+const app = express();
+app.use(express.json());
+
+// Mock Agent ID for demonstration
+const AGENT_ID = "agents/ap_minimal_refund_agent";
+
+// Minimal Refund Endpoint
+app.post(
+  "/minimal-refund",
+  requirePolicy("finance.payment.refund.v1", AGENT_ID),
+  async (req, res) => {
+    try {
+      // Extract required fields from request
+      const {
+        amount_minor, // Amount in smallest currency unit (e.g., cents)
+        currency, // Currency code (e.g., "USD", "EUR", "JPY")
+        order_id, // Unique order identifier
+        customer_id, // Customer identifier
+        reason_code, // Reason for refund (e.g., "defective")
+        region, // Region code (e.g., "US", "EU", "APAC")
+        idempotency_key, // Unique key to prevent duplicate refunds
+      } = req.body;
+
+      // Optional fields
+      const {
+        order_currency, // Original order currency
+        order_total_minor, // Total order amount
+        already_refunded_minor, // Already refunded amount
+        note, // Additional notes
+        merchant_case_id, // Merchant's case ID
+      } = req.body;
+
+      // Policy is already verified by middleware
+      const policyResult = req.policyResult;
+
+      if (!policyResult.allow) {
+        return res.status(403).json({
+          success: false,
+          decision_id: policyResult.decision_id,
+          error: "Policy violation",
+          reasons: policyResult.reasons,
+        });
+      }
+
+      // Simulate processing the refund
+      const refund_id = `ref_${Date.now()}_${Math.random()
+        .toString(36)
+        .substr(2, 9)}`;
+      console.log(
+        `Minimal Refund Processed: ${refund_id} for ${amount_minor} ${currency} by agent ${policyResult.passport.agent_id}`
+      );
+
+      res.json({
+        success: true,
+        refund_id,
+        amount_minor,
+        currency,
+        status: "processed",
+        decision_id: policyResult.decision_id,
+        remaining_daily_cap: policyResult.remaining_daily_cap,
+      });
+    } catch (error) {
+      console.error("Minimal refund processing error:", error);
+      res.status(500).json({
+        error: "Internal server error",
+        message: "Failed to process refund",
+      });
+    }
+  }
+);
+
+// Batch Refund Endpoint (for multiple refunds)
+app.post(
+  "/minimal-batch-refund",
+  requirePolicy("finance.payment.refund.v1", AGENT_ID),
+  async (req, res) => {
+    try {
+      const { refunds } = req.body; // Array of refund objects
+
+      if (!Array.isArray(refunds) || refunds.length === 0) {
+        return res.status(400).json({
+          error: "Invalid request",
+          message: "refunds array is required and must not be empty",
+        });
+      }
+
+      const policyResult = req.policyResult;
+
+      if (!policyResult.allow) {
+        return res.status(403).json({
+          success: false,
+          decision_id: policyResult.decision_id,
+          error: "Policy violation",
+          reasons: policyResult.reasons,
+        });
+      }
+
+      // Process each refund
+      const results = [];
+      for (const refund of refunds) {
+        const refund_id = `ref_${Date.now()}_${Math.random()
+          .toString(36)
+          .substr(2, 9)}`;
+        results.push({
+          refund_id,
+          amount_minor: refund.amount_minor,
+          currency: refund.currency,
+          status: "processed",
+        });
+      }
+
+      res.json({
+        success: true,
+        processed_count: results.length,
+        refunds: results,
+        decision_id: policyResult.decision_id,
+        remaining_daily_cap: policyResult.remaining_daily_cap,
+      });
+    } catch (error) {
+      console.error("Batch refund processing error:", error);
+      res.status(500).json({
+        error: "Internal server error",
+        message: "Failed to process batch refunds",
+      });
+    }
+  }
+);
+
+// Health check endpoint
+app.get("/health", (req, res) => {
+  res.json({
+    status: "healthy",
+    service: "minimal-refunds",
+    policy: "finance.payment.refund.v1",
+    agent_id: AGENT_ID,
+  });
+});
+
+const PORT = process.env.PORT || 3001;
+app.listen(PORT, () => {
+  console.log(`Minimal Refunds service running on port ${PORT}`);
+  console.log("Protected by APort finance.payment.refund.v1 policy pack");
+  console.log("\nTo test (example for allowed refund):");
+  console.log(`curl -X POST http://localhost:${PORT}/minimal-refund \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{`);
+  console.log(`    "amount_minor": 7500,`);
+  console.log(`    "currency": "USD",`);
+  console.log(`    "order_id": "ORD-MIN-001",`);
+  console.log(`    "customer_id": "CUST-MIN-001",`);
+  console.log(`    "reason_code": "customer_request",`);
+  console.log(`    "region": "US",`);
+  console.log(`    "idempotency_key": "min_idempotency_key_123"`);
+  console.log(`  }'`);
+  console.log("\nTo test batch refunds:");
+  console.log(`curl -X POST http://localhost:${PORT}/minimal-batch-refund \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{`);
+  console.log(`    "refunds": [`);
+  console.log(`      {`);
+  console.log(`        "amount_minor": 5000,`);
+  console.log(`        "currency": "USD",`);
+  console.log(`        "order_id": "ORD-MIN-002",`);
+  console.log(`        "customer_id": "CUST-MIN-002",`);
+  console.log(`        "reason_code": "defective",`);
+  console.log(`        "region": "US",`);
+  console.log(`        "idempotency_key": "batch_key_001"`);
+  console.log(`      }`);
+  console.log(`    ]`);
+  console.log(`  }'`);
+});
+
+module.exports = app;

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

@@ -0,0 +1,216 @@
+{
+  "id": "finance.payment.refund.v1",
+  "name": "Refunds Protection Policy",
+  "description": "Pre-act governance for refund operations. Enforces per-currency caps, reason code validation, cross-currency restrictions, and idempotency.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["finance.payment.refund"],
+  "min_assurance": "L2",
+  "limits_required": [
+    "supported_currencies",
+    "currency_limits",
+    "refund_reason_codes",
+    "regions",
+    "approval_required"
+  ],
+  "enforcement": {
+    "amount_lte": "limits.finance.payment.refund.currency_limits.{currency}.max_per_tx",
+    "currency_supported": "limits.finance.payment.refund.supported_currencies",
+    "region_in": "regions",
+    "reason_code_valid": "limits.finance.payment.refund.refund_reason_codes",
+    "assurance_tier_enforced": "true",
+    "idempotency_required": "true",
+    "order_id_required": "true",
+    "customer_id_required": "true",
+    "cross_currency_denied": "true"
+  },
+  "assurance_rules": [
+    { "lte_minor": 10000, "min_level": "L2" },
+    { "lte_minor": 50000, "min_level": "L3" }
+  ],
+  "required_fields": [
+    "order_id",
+    "customer_id",
+    "amount",
+    "currency",
+    "region",
+    "reason_code",
+    "idempotency_key"
+  ],
+  "optional_fields": [
+    "note",
+    "merchant_case_id",
+    "order_currency",
+    "order_total_minor",
+    "already_refunded_minor"
+  ],
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Cache /verify with ETag; 60s TTL",
+    "Subscribe to status webhooks for instant suspend",
+    "Log all refund attempts for Verifiable Attestation",
+    "Implement daily spend tracking with atomic counters",
+    "Use idempotency keys to prevent duplicate refunds",
+    "Validate remaining order balance before processing",
+    "Enforce reason code validation for compliance",
+    "Block cross-currency refunds to prevent abuse"
+  ],
+  "required_context": {
+    "$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"
+      },
+      "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.refunds.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 >= getRequiredAssuranceLevel(amount, currency)",
+      "deny_code": "oap.assurance_insufficient",
+      "description": "Assurance level must meet minimum requirement based on amount"
+    },
+    {
+      "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": "reason_code_valid",
+      "condition": "reason_code in limits.refund_reason_codes",
+      "deny_code": "oap.invalid_reason_code",
+      "description": "Reason code must be valid"
+    },
+    {
+      "name": "cross_currency_check",
+      "condition": "NOT (order_currency AND currency != order_currency)",
+      "deny_code": "oap.cross_currency_denied",
+      "description": "Cross-currency refunds are not allowed"
+    },
+    {
+      "name": "daily_cap_check",
+      "condition": "daily_total + amount <= limits.currency_limits[currency].daily_cap",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Daily cap must not be exceeded"
+    },
+    {
+      "name": "idempotency_check",
+      "condition": "idempotency_key not in recent_keys",
+      "deny_code": "oap.idempotency_conflict",
+      "description": "Idempotency key must be unique"
+    },
+    {
+      "name": "region_authorization",
+      "condition": "region in passport.regions",
+      "deny_code": "oap.region_blocked",
+      "description": "Region must be authorized"
+    }
+  ],
+  "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"
+}