@aporthq/aport-agent-guardrails 1.0.8

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

@@ -0,0 +1,326 @@
+# Payment Charge Policy Pack v1
+
+Protect your payment charge endpoints with APort's standardized policy pack. This pack ensures only verified agents with proper capabilities, assurance levels, and transaction limits can initiate payments.
+
+## What This Pack Protects
+
+- **Route**: `/payments/charge/*` (POST)
+- **Risk**: Financial transactions, fraud prevention, regulatory compliance
+- **Impact**: Direct monetary loss, chargeback disputes, audit findings
+
+## Requirements
+
+| Requirement | Value | Description |
+|-------------|-------|-------------|
+| **Capability** | `payments.charge` | Agent must have charge capability |
+| **Assurance** | `L2` or higher | Email + GitHub verification minimum |
+| **Limits** | `currency_limits.{ISO4217}.{max_per_tx,daily_cap}` | Per-currency transaction and daily limits |
+| **Limits** | `allowed_merchant_ids[]` | Merchant allowlist (optional) |
+| **Limits** | `allowed_countries[]` | Country allowlist (optional) |
+| **Limits** | `blocked_categories[]` | Category blocklist (optional) |
+| **Limits** | `max_items_per_tx` | Maximum items per transaction (optional) |
+| **Regions** | Must match | Agent must be authorized in caller's region |
+| **Idempotency** | Required | Prevents duplicate charges |
+
+## Implementation
+
+### Express.js
+
+```javascript
+const { requirePolicy } = require('@aporthq/middleware-express');
+
+// Option 1: Explicit agent ID (preferred)
+app.post('/payments/charge', 
+  requirePolicy('finance.payment.charge.v1', 'ap_a2d10232c6534523812423eec8a1425c45678'), 
+  async (req, res) => {
+    // Your charge logic here
+    // req.policyResult contains the verified passport
+    const { amount, currency, merchant_id, items } = req.body;
+    const passport = req.policyResult.passport;
+    
+    // Process charge...
+    res.json({ success: true, charge_id: generateId() });
+  }
+);
+
+// Option 2: Header fallback (backward compatible)
+app.post('/payments/charge', 
+  requirePolicy('finance.payment.charge.v1'), 
+  async (req, res) => {
+    // Your charge logic here
+    // req.policyResult contains the verified passport
+    const { amount, currency, merchant_id, items } = req.body;
+    const passport = req.policyResult.passport;
+    
+    // Process charge...
+    res.json({ success: true, charge_id: generateId() });
+  }
+);
+```
+
+**Client Request Example:**
+```javascript
+// The client must include the agent ID in the header (for Option 2)
+fetch('/payments/charge', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'  // ← Agent ID passed here
+  },
+  body: JSON.stringify({
+    amount: 1299,
+    currency: "USD",
+    merchant_id: "merch_abc",
+    region: "US",
+    shipping_country: "US",
+    items: [
+      { sku: "SKU-1", qty: 1, category: "electronics" }
+    ],
+    idempotency_key: "charge-ord-123"
+  })
+});
+```
+
+### FastAPI
+
+```python
+from aport.middleware import require_policy
+
+@app.post("/payments/charge")
+@require_policy("finance.payment.charge.v1")
+async def process_charge(request: Request, charge_data: ChargeRequest):
+    # Your charge logic here
+    # request.state.policy_result contains the verified passport
+    passport = request.state.policy_result.passport
+    
+    # Process charge...
+    return {"success": True, "charge_id": generate_id()}
+```
+
+**Client Request Example:**
+```python
+import requests
+
+# The client must include the agent ID in the header
+response = requests.post('/payments/charge', 
+    headers={
+        'Content-Type': 'application/json',
+        'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'  # ← Agent ID passed here
+    },
+    json={
+        'amount': 1299,
+        'currency': 'USD',
+        'merchant_id': 'merch_abc',
+        'region': 'US',
+        'shipping_country': 'US',
+        'items': [
+            {'sku': 'SKU-1', 'qty': 1, 'category': 'electronics'}
+        ],
+        'idempotency_key': 'charge-ord-123'
+    }
+)
+```
+
+## How It Works
+
+The `requirePolicy('finance.payment.charge.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.charge.v1`)
+   - **API Call**: Calls `/api/verify/policy/finance.payment.charge.v1` with agent ID and context
+   - **Requirements Check**: Validates agent meets finance.payment.charge.v1 requirements:
+     - Has `payments.charge` capability
+     - Meets minimum assurance level (L2+)
+     - Within per-currency transaction and daily limits
+     - Merchant is allowed (if allowlist configured)
+     - Country is allowed (if allowlist configured)
+     - No blocked categories in items
+     - Item count within limits
+     - Idempotency key is unique
+     - 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": "oap.limit_exceeded",
+  "message": "Amount $25.00 exceeds per-transaction limit $20.00",
+  "policy_id": "finance.payment.charge.v1",
+  "agent_id": "ap_a2d10232c6534523812423eec8a1425c45678",
+  "upgrade_instructions": "Request higher limits in your passport"
+}
+```
+
+## Test Payloads
+
+### Valid Request
+```json
+{
+  "amount": 1299,
+  "currency": "USD",
+  "merchant_id": "merch_abc",
+  "region": "US",
+  "shipping_country": "US",
+  "items": [
+    { "sku": "SKU-1", "qty": 1, "category": "electronics" }
+  ],
+  "idempotency_key": "charge-ord-123"
+}
+```
+
+### Invalid Request (exceeds limit)
+```json
+{
+  "amount": 25000,
+  "currency": "USD",
+  "merchant_id": "merch_abc",
+  "region": "US",
+  "items": [
+    { "sku": "SKU-1", "qty": 1, "category": "electronics" }
+  ],
+  "idempotency_key": "charge-ord-124"
+}
+```
+*Returns 403: "Amount $250.00 exceeds per-transaction limit $200.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 charge attempts for compliance
+4. **Daily Tracking**: Implement daily spend tracking per currency to prevent abuse
+5. **Idempotency**: Always use unique idempotency keys to prevent duplicate charges
+6. **Error Handling**: Provide clear error messages to help agents self-remediate
+7. **Merchant Validation**: Maintain merchant allowlists for trusted partners
+8. **Category Filtering**: Block high-risk categories (weapons, illicit goods)
+
+## Compliance Badge
+
+Agents that meet this policy's requirements can display the "Charge-Ready" badge:
+
+```markdown
+[![Charge-Ready](https://api.aport.io/badge/ap_a2d10232c6534523812423eec8a1425c45678.svg)](https://aport.io/agents/ap_a2d10232c6534523812423eec8a1425c45678)
+```
+
+## Support
+
+- [Documentation](https://aport.io/docs/policies/finance.payment.charge.v1)
+- [Community](https://github.com/aporthq/community)
+- [Support](https://aport.io/support)
+
+---
+**Last Updated**: 2025-09-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": [
+    "amount",
+    "currency",
+    "merchant_id",
+    "region",
+    "items",
+    "idempotency_key"
+  ],
+  "properties": {
+    "amount": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Minor units (e.g., cents)"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "ISO 4217 currency code"
+    },
+    "merchant_id": {
+      "type": "string",
+      "description": "Merchant identifier"
+    },
+    "region": {
+      "type": "string",
+      "description": "Geographic region"
+    },
+    "shipping_country": {
+      "type": "string",
+      "description": "Shipping country code"
+    },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Array of items being purchased",
+      "items": {
+        "type": "object",
+        "required": [
+          "sku",
+          "qty",
+          "price"
+        ],
+        "properties": {
+          "sku": {
+            "type": "string",
+            "description": "Stock keeping unit"
+          },
+          "qty": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Quantity"
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "Item name for audit and compliance"
+          },
+          "price": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Price in minor currency units (e.g., cents)"
+          },
+          "category": {
+            "type": "string",
+            "description": "Item category"
+          }
+        }
+      }
+    },
+    "risk_score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Risk score (0-100)"
+    },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 8,
+      "description": "Idempotency key for duplicate prevention"
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/finance.payment.charge.v1?format=schema"
+```
+

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

@@ -0,0 +1,250 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply payments.charge policy to all charge routes
+app.post(
+  "/payments/charge",
+  requirePolicy("finance.payment.charge.v1"),
+  async (req, res) => {
+    try {
+      const {
+        amount,
+        currency,
+        merchant_id,
+        region,
+        shipping_country,
+        items,
+        risk_score,
+        idempotency_key,
+      } = req.body;
+
+      const passport = req.policyResult.passport;
+
+      // Additional business logic validation
+      if (amount <= 0) {
+        return res.status(400).json({ error: "Invalid charge amount" });
+      }
+
+      // Check if items are provided
+      if (!items || items.length === 0) {
+        return res.status(400).json({ error: "Items are required" });
+      }
+
+      // Process charge using your payment processor
+      const charge_id = await processCharge({
+        amount,
+        currency,
+        merchant_id,
+        region,
+        shipping_country,
+        items,
+        risk_score,
+        idempotency_key,
+        agent_id: passport.passport_id,
+        agent_name: passport.metadata?.template_name || "Unknown Agent",
+      });
+
+      // Log the transaction
+      console.log(
+        `Charge processed: ${charge_id} for ${amount} ${currency} by agent ${passport.passport_id}`
+      );
+
+      res.json({
+        success: true,
+        charge_id,
+        amount,
+        currency,
+        status: "processed",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Charge processing error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Batch charges endpoint
+app.post(
+  "/payments/charge/batch",
+  requirePolicy("finance.payment.charge.v1"),
+  async (req, res) => {
+    try {
+      const { charges } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Group charges by currency for daily cap checking
+      const currencyTotals = {};
+      for (const charge of charges) {
+        const currency = charge.currency || "USD";
+        currencyTotals[currency] =
+          (currencyTotals[currency] || 0) + (charge.amount || 0);
+      }
+
+      // Check daily caps per currency
+      for (const [currency, totalAmount] of Object.entries(currencyTotals)) {
+        const currencyLimits =
+          passport.limits?.payments?.charge?.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 charges
+      const results = await Promise.all(
+        charges.map((charge) =>
+          processCharge({
+            ...charge,
+            agent_id: passport.passport_id,
+          })
+        )
+      );
+
+      res.json({
+        success: true,
+        processed: results.length,
+        currency_totals: currencyTotals,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Batch charge error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Get charge status
+app.get(
+  "/payments/charge/:charge_id",
+  requirePolicy("finance.payment.charge.v1"),
+  async (req, res) => {
+    try {
+      const { charge_id } = req.params;
+      const passport = req.policyResult.passport;
+
+      const charge_info = await getChargeStatus(
+        charge_id,
+        passport.passport_id
+      );
+
+      if (!charge_info) {
+        return res.status(404).json({ error: "Charge not found" });
+      }
+
+      res.json(charge_info);
+    } catch (error) {
+      console.error("Charge status error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Refund charge endpoint
+app.post(
+  "/payments/charge/:charge_id/refund",
+  requirePolicy("finance.payment.charge.v1"),
+  async (req, res) => {
+    try {
+      const { charge_id } = req.params;
+      const { amount, reason } = req.body;
+      const passport = req.policyResult.passport;
+
+      const refund_id = await processRefund({
+        charge_id,
+        amount,
+        reason,
+        agent_id: passport.passport_id,
+      });
+
+      res.json({
+        success: true,
+        refund_id,
+        charge_id,
+        amount,
+        status: "refunded",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Refund processing error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock charge processing function
+async function processCharge({
+  amount,
+  currency,
+  merchant_id,
+  region,
+  shipping_country,
+  items,
+  risk_score,
+  idempotency_key,
+  agent_id,
+}) {
+  // Simulate payment processor call
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  // Log charge details for audit
+  console.log(`Processing charge:`, {
+    amount,
+    currency,
+    merchant_id,
+    region,
+    shipping_country,
+    items: items?.length || 0,
+    risk_score,
+    idempotency_key,
+    agent_id,
+  });
+
+  return `chg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+// Mock charge status lookup
+async function getChargeStatus(charge_id, agent_id) {
+  // Simulate charge status lookup
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  return {
+    charge_id,
+    status: "completed",
+    created_at: new Date().toISOString(),
+    amount: 1299,
+    currency: "USD",
+    merchant_id: "merch_abc",
+    items: [{ sku: "SKU-1", qty: 1, category: "electronics" }],
+  };
+}
+
+// Mock refund processing function
+async function processRefund({ charge_id, amount, reason, agent_id }) {
+  // Simulate refund processing
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  console.log(`Processing refund:`, {
+    charge_id,
+    amount,
+    reason,
+    agent_id,
+  });
+
+  return `ref_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Payment charge service running on port ${PORT}`);
+  console.log("Protected by APort finance.payment.charge.v1 policy pack");
+});