@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/data.report.ingest.v1/policy.json

@@ -0,0 +1,174 @@
+{
+  "id": "data.report.ingest.v1",
+  "name": "Report Data Ingestion Policy",
+  "description": "Pre-action governance for data being ingested by an AI agent for reporting purposes (e.g., ESG, financial disclosures). Enforces rules on data source credibility and freshness.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["data.report.ingest"],
+  "min_assurance": "L2",
+  "limits_required": [
+    "approved_sources",
+    "max_data_age_seconds",
+    "max_data_size_mb",
+    "max_ingest_frequency_per_hour",
+    "data_quality_threshold",
+    "required_validation_checks"
+  ],
+  "required_fields": ["report_type", "data_source_id", "data_timestamp"],
+  "optional_fields": [
+    "metric_type",
+    "data_size_mb",
+    "validation_checks",
+    "data_quality_score",
+    "ingest_reason",
+    "idempotency_key"
+  ],
+  "enforcement": {
+    "source_approved": true,
+    "data_freshness": true,
+    "data_size_limit": true,
+    "ingest_frequency_limit": true,
+    "data_quality_enforced": true,
+    "validation_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 data ingestion attempts for Verifiable Attestation",
+    "Implement data quality scoring before ingestion",
+    "Use data lineage tracking for audit compliance",
+    "Implement progressive data validation checks",
+    "Monitor for data anomalies and unusual patterns",
+    "Use data encryption for sensitive report data",
+    "Implement data retention policies based on report type",
+    "Maintain data source reputation scoring",
+    "Use idempotency keys to prevent duplicate ingestion",
+    "Implement data freshness monitoring and alerts"
+  ],
+  "cache": {
+    "default_ttl_seconds": 300,
+    "suspend_invalidate_seconds": 60
+  },
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["report_type", "data_source_id", "data_timestamp"],
+    "properties": {
+      "report_type": {
+        "type": "string",
+        "description": "The type of report being generated (e.g., 'ESG', 'QuarterlyFinancials')."
+      },
+      "data_source_id": {
+        "type": "string",
+        "description": "A unique identifier for the source of the data being ingested (e.g., 'api.climate-data.com', 'internal-hr-db')."
+      },
+      "data_timestamp": {
+        "type": "string",
+        "format": "date-time",
+        "description": "The ISO 8601 timestamp of when the data was generated."
+      },
+      "metric_type": {
+        "type": "string",
+        "description": "The specific metric this data point relates to (e.g., 'carbon_emissions', 'employee_diversity')."
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.climate-data.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"climate_data.reports.ingest\"])"
+      },
+      "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"
+    },
+    {
+      "name": "source_is_approved",
+      "condition": "context.data_source_id in passport.limits.data.report.ingest[context.report_type].approved_sources",
+      "deny_code": "oap.source_unapproved"
+    },
+    {
+      "name": "data_is_fresh",
+      "condition": "(now() - to_timestamp(context.data_timestamp)) <= passport.limits.data.report.ingest[context.report_type].max_data_age_seconds",
+      "deny_code": "oap.data_stale",
+      "description": "Data must not be older than maximum allowed age for the report type."
+    },
+    {
+      "name": "assurance_minimum",
+      "condition": "passport.assurance_level >= policy.min_assurance",
+      "deny_code": "oap.assurance_insufficient",
+      "description": "Assurance level must meet minimum requirement for data ingestion."
+    },
+    {
+      "name": "data_size_limit_check",
+      "condition": "not context.data_size_mb or context.data_size_mb <= passport.limits.data.report.ingest[context.report_type].max_data_size_mb",
+      "deny_code": "oap.data_size_exceeded",
+      "description": "Data size must not exceed maximum allowed for the report type."
+    },
+    {
+      "name": "ingest_frequency_check",
+      "condition": "ingest_count_per_hour[context.data_source_id] < passport.limits.data.report.ingest[context.report_type].max_ingest_frequency_per_hour",
+      "deny_code": "oap.ingest_frequency_exceeded",
+      "description": "Data source ingestion frequency must not exceed hourly limit."
+    },
+    {
+      "name": "data_quality_check",
+      "condition": "not context.data_quality_score or context.data_quality_score >= passport.limits.data.report.ingest[context.report_type].data_quality_threshold",
+      "deny_code": "oap.data_quality_insufficient",
+      "description": "Data quality score must meet minimum threshold."
+    },
+    {
+      "name": "validation_checks_required",
+      "condition": "context.validation_checks and all(check in passport.limits.data.report.ingest[context.report_type].required_validation_checks for check in context.validation_checks)",
+      "deny_code": "oap.validation_checks_missing",
+      "description": "All required validation checks must be performed."
+    },
+    {
+      "name": "idempotency_check",
+      "condition": "context.idempotency_key not in recent_keys",
+      "deny_code": "oap.idempotency_conflict",
+      "description": "Idempotency key must be unique to prevent duplicate ingestion."
+    },
+    {
+      "name": "report_type_allowed",
+      "condition": "context.report_type in passport.limits.data.report.ingest.allowed_report_types",
+      "deny_code": "oap.report_type_forbidden",
+      "description": "Report type must be in the allowed list."
+    },
+    {
+      "name": "data_source_reputation_check",
+      "condition": "data_source_reputation[context.data_source_id] >= passport.limits.data.report.ingest.min_source_reputation_score",
+      "deny_code": "oap.source_reputation_insufficient",
+      "description": "Data source must meet minimum reputation score."
+    },
+    {
+      "name": "metric_type_validation",
+      "condition": "not context.metric_type or context.metric_type in passport.limits.data.report.ingest[context.report_type].allowed_metric_types",
+      "deny_code": "oap.metric_type_forbidden",
+      "description": "Metric type must be allowed for the report type."
+    }
+  ]
+}

package/external/aport-policies/finance.crypto.trade.v1/README.md

@@ -0,0 +1,146 @@
+# Crypto Asset Trading Policy Pack v1
+
+Protect your crypto trading endpoints with APort's standardized policy pack. This pack ensures only verified agents with proper capabilities, assurance levels, and trading limits can execute crypto asset trades with appropriate security controls.
+
+## What This Pack Protects
+
+- **Route**: `/finance/crypto/trade/*` (POST)
+- **Risk**: Crypto trading, market manipulation, security breaches, regulatory compliance
+- **Impact**: Financial loss, regulatory violations, security incidents, market disruption
+
+## Requirements
+
+| Requirement | Value | Description |
+|-------------|-------|-------------|
+| **Capability** | `finance.crypto.trade` | Agent must have crypto trading capability |
+| **Assurance** | `L3` or higher | Enhanced verification minimum |
+| **Limits** | `allowed_exchanges[]` | Allowed crypto exchanges (coinbase, binance, etc.) |
+| **Limits** | `allowed_tokens[]` | Allowed cryptocurrency tokens |
+| **Limits** | `max_trade_size_usd` | Maximum trade size in USD |
+| **Limits** | `max_hot_wallet_trade_usd` | Maximum hot wallet trade size |
+| **Limits** | `max_daily_trade_volume_usd` | Maximum daily trading volume |
+| **Limits** | `max_trades_per_day` | Maximum number of trades per day |
+| **Regions** | Must match | Agent must be authorized in caller's region |
+| **Idempotency** | Required | Prevents duplicate trades |
+
+## Implementation
+
+### Express.js
+
+```javascript
+const { requirePolicy } = require('@aporthq/middleware-express');
+
+// Option 1: Explicit agent ID (preferred)
+app.post('/finance/crypto/trade', 
+  requirePolicy('finance.crypto.trade.v1', 'ap_a2d10232c6534523812423eec8a1425c45678'), 
+  async (req, res) => {
+    // Your crypto trading logic here
+    // req.policyResult contains the verified passport
+    const { exchange_id, pair, side, amount_usd } = req.body;
+    const passport = req.policyResult.passport;
+    
+    // Process crypto trade...
+    res.json({ success: true, trade_id: generateId() });
+  }
+);
+```
+
+**Client Request Example:**
+```javascript
+fetch('/finance/crypto/trade', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Agent-Passport-Id': 'ap_a2d10232c6534523812423eec8a1425c45678'
+  },
+  body: JSON.stringify({
+    exchange_id: "coinbase",
+    pair: "BTC-USD",
+    side: "buy",
+    amount_usd: 1000,
+    source_wallet_type: "hot",
+    idempotency_key: "crypto-trade-123"
+  })
+});
+```
+
+## Best Practices
+
+1. **Cache Verification**: Cache `/verify` responses with ETag for 30 seconds
+2. **Webhook Integration**: Subscribe to `status.changed` webhooks for instant suspension
+3. **Verifiable Attestation**: Log all crypto trade attempts for compliance
+4. **Real-time Price Validation**: Implement real-time price validation before trade execution
+5. **Wallet Security**: Use cold storage for large amounts and hot wallets for small trades
+6. **Exchange Monitoring**: Monitor exchange connectivity and implement circuit breakers
+7. **Slippage Protection**: Implement slippage protection for volatile markets
+8. **Idempotency**: Always use unique idempotency keys to prevent duplicate trades
+9. **Exchange Allowlists**: Maintain exchange allowlists for trusted platforms only
+10. **Progressive Limits**: Implement progressive limits for new trading pairs
+11. **Pattern Monitoring**: Monitor for unusual trading patterns and potential manipulation
+12. **Multi-signature Wallets**: Use multi-signature wallets for high-value transactions
+
+## Support
+
+- [Documentation](https://aport.io/docs/policies/finance.crypto.trade.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": [
+    "exchange_id",
+    "pair",
+    "side",
+    "amount_usd"
+  ],
+  "properties": {
+    "exchange_id": {
+      "type": "string",
+      "description": "The exchange where the trade is being executed (e.g., 'coinbase', 'binance')."
+    },
+    "pair": {
+      "type": "string",
+      "pattern": "^[A-Z]+-[A-Z]+$",
+      "description": "The trading pair (e.g., 'BTC-USD')."
+    },
+    "side": {
+      "type": "string",
+      "enum": [
+        "buy",
+        "sell"
+      ],
+      "description": "The side of the trade."
+    },
+    "amount_usd": {
+      "type": "integer",
+      "description": "The total value of the trade in USD minor units (cents)."
+    },
+    "source_wallet_type": {
+      "type": "string",
+      "enum": [
+        "hot",
+        "cold",
+        "custodial"
+      ],
+      "description": "The type of wallet initiating the trade."
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/finance.crypto.trade.v1?format=schema"
+```
+

package/external/aport-policies/finance.crypto.trade.v1/express.example.js

@@ -0,0 +1,109 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply finance.crypto.trade policy to all crypto trading routes
+app.post(
+  "/finance/crypto/trade",
+  requirePolicy("finance.crypto.trade.v1"),
+  async (req, res) => {
+    try {
+      const {
+        exchange_id,
+        pair,
+        side,
+        amount_usd,
+        source_wallet_type,
+        idempotency_key,
+        trade_reason,
+        risk_score,
+      } = req.body;
+
+      const passport = req.policyResult.passport;
+
+      // Additional business logic validation
+      if (amount_usd <= 0) {
+        return res.status(400).json({ error: "Invalid trade amount" });
+      }
+
+      // Check if required fields are provided
+      if (!exchange_id || !pair || !side) {
+        return res
+          .status(400)
+          .json({ error: "Exchange, pair, and side are required" });
+      }
+
+      // Process crypto trade using your trading system
+      const trade_id = await processCryptoTrade({
+        exchange_id,
+        pair,
+        side,
+        amount_usd,
+        source_wallet_type,
+        idempotency_key,
+        trade_reason,
+        risk_score,
+        agent_id: passport.passport_id,
+        agent_name: passport.metadata?.template_name || "Unknown Agent",
+      });
+
+      // Log the trade
+      console.log(
+        `Crypto trade processed: ${trade_id} for ${amount_usd} USD by agent ${passport.passport_id}`
+      );
+
+      res.json({
+        success: true,
+        trade_id,
+        exchange_id,
+        pair,
+        side,
+        amount_usd,
+        status: "processed",
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Crypto trade processing error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock crypto trade processing function
+async function processCryptoTrade({
+  exchange_id,
+  pair,
+  side,
+  amount_usd,
+  source_wallet_type,
+  idempotency_key,
+  trade_reason,
+  risk_score,
+  agent_id,
+}) {
+  // Simulate trading system call
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  // Log trade details for audit
+  console.log(`Processing crypto trade:`, {
+    exchange_id,
+    pair,
+    side,
+    amount_usd,
+    source_wallet_type,
+    idempotency_key,
+    trade_reason,
+    risk_score,
+    agent_id,
+  });
+
+  return `trade_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Crypto trading service running on port ${PORT}`);
+  console.log("Protected by APort finance.crypto.trade.v1 policy pack");
+});

package/external/aport-policies/finance.crypto.trade.v1/minimal-example.js

@@ -0,0 +1,65 @@
+/**
+ * Minimal Example: finance.crypto.trade.v1 Policy
+ *
+ * This is a quick-start example showing the basic usage of the finance.crypto.trade.v1 policy.
+ * For production use, see the full express.example.js file.
+ */
+
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Minimal crypto trade endpoint with policy protection
+app.post(
+  "/crypto/trade",
+  requirePolicy("finance.crypto.trade.v1"),
+  async (req, res) => {
+    try {
+      const { exchange_id, pair, side, amount_usd } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Process the crypto trade (your business logic here)
+      const trade_id = `trade_${Date.now()}`;
+
+      console.log(`Crypto trade processed: ${trade_id} for ${amount_usd} USD`);
+
+      res.json({
+        success: true,
+        trade_id,
+        exchange_id,
+        pair,
+        side,
+        amount_usd,
+        decision_id: req.policyResult.decision_id,
+      });
+    } catch (error) {
+      console.error("Crypto trade error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Example client request
+const exampleRequest = {
+  exchange_id: "coinbase",
+  pair: "BTC-USD",
+  side: "buy",
+  amount_usd: 1000,
+  source_wallet_type: "hot",
+  idempotency_key: "crypto-trade-123",
+};
+
+console.log("Example request:", JSON.stringify(exampleRequest, null, 2));
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Minimal crypto trading service running on port ${PORT}`);
+  console.log("Protected by APort finance.crypto.trade.v1 policy");
+  console.log(
+    `Try: curl -X POST http://localhost:${PORT}/crypto/trade -H "Content-Type: application/json" -d '${JSON.stringify(
+      exampleRequest
+    )}'`
+  );
+});

package/external/aport-policies/finance.crypto.trade.v1/policy.json

@@ -0,0 +1,176 @@
+{
+  "id": "finance.crypto.trade.v1",
+  "name": "Crypto Asset Trading Policy",
+  "description": "Pre-action governance for agent-initiated crypto asset trades. Enforces rules on specific tokens, exchanges, wallet types, and transaction value.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["finance.crypto.trade"],
+  "min_assurance": "L3",
+  "limits_required": [
+    "allowed_exchanges",
+    "allowed_tokens",
+    "max_trade_size_usd",
+    "max_hot_wallet_trade_usd",
+    "max_daily_trade_volume_usd",
+    "max_trades_per_day"
+  ],
+  "required_fields": ["exchange_id", "pair", "side", "amount_usd"],
+  "optional_fields": [
+    "source_wallet_type",
+    "idempotency_key",
+    "trade_reason",
+    "risk_score"
+  ],
+  "enforcement": {
+    "exchange_allowed": true,
+    "token_allowed": true,
+    "trade_size_limit": true,
+    "hot_wallet_limit": true,
+    "daily_volume_limit": true,
+    "trade_frequency_limit": 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 crypto trade attempts for Verifiable Attestation",
+    "Implement real-time price validation before trade execution",
+    "Use cold storage for large amounts and hot wallets for small trades",
+    "Monitor exchange connectivity and implement circuit breakers",
+    "Implement slippage protection for volatile markets",
+    "Use unique idempotency keys to prevent duplicate trades",
+    "Maintain exchange allowlists for trusted platforms only",
+    "Implement progressive limits for new trading pairs",
+    "Monitor for unusual trading patterns and potential manipulation",
+    "Use multi-signature wallets for high-value transactions"
+  ],
+  "cache": {
+    "default_ttl_seconds": 30,
+    "suspend_invalidate_seconds": 15
+  },
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["exchange_id", "pair", "side", "amount_usd"],
+    "properties": {
+      "exchange_id": {
+        "type": "string",
+        "description": "The exchange where the trade is being executed (e.g., 'coinbase', 'binance')."
+      },
+      "pair": {
+        "type": "string",
+        "pattern": "^[A-Z]+-[A-Z]+$",
+        "description": "The trading pair (e.g., 'BTC-USD')."
+      },
+      "side": {
+        "type": "string",
+        "enum": ["buy", "sell"],
+        "description": "The side of the trade."
+      },
+      "amount_usd": {
+        "type": "integer",
+        "description": "The total value of the trade in USD minor units (cents)."
+      },
+      "source_wallet_type": {
+        "type": "string",
+        "enum": ["hot", "cold", "custodial"],
+        "description": "The type of wallet initiating the trade."
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.coinbase.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"coinbase.trades.execute\"])"
+      },
+      "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"
+    },
+    {
+      "name": "exchange_is_allowed",
+      "condition": "context.exchange_id in passport.limits.finance.crypto.trade.allowed_exchanges",
+      "deny_code": "oap.exchange_forbidden"
+    },
+    {
+      "name": "token_is_allowed",
+      "condition": "all(token in passport.limits.finance.crypto.trade.allowed_tokens for token in context.pair.split('-'))",
+      "deny_code": "oap.token_forbidden"
+    },
+    {
+      "name": "trade_size_limit_check",
+      "condition": "context.amount_usd <= passport.limits.finance.crypto.trade.max_trade_size_usd",
+      "deny_code": "oap.limit_exceeded"
+    },
+    {
+      "name": "hot_wallet_limit_check",
+      "condition": "not (context.source_wallet_type == 'hot' and context.amount_usd > passport.limits.finance.crypto.trade.max_hot_wallet_trade_usd)",
+      "deny_code": "oap.wallet_limit_exceeded",
+      "description": "Hot wallet trades must not exceed maximum allowed amount."
+    },
+    {
+      "name": "assurance_minimum",
+      "condition": "passport.assurance_level >= policy.min_assurance",
+      "deny_code": "oap.assurance_insufficient",
+      "description": "Assurance level must meet minimum requirement for crypto trading."
+    },
+    {
+      "name": "daily_volume_limit_check",
+      "condition": "daily_volume_total + context.amount_usd <= passport.limits.finance.crypto.trade.max_daily_trade_volume_usd",
+      "deny_code": "oap.daily_volume_exceeded",
+      "description": "Daily trading volume must not exceed limit."
+    },
+    {
+      "name": "trade_frequency_check",
+      "condition": "trades_today_count < passport.limits.finance.crypto.trade.max_trades_per_day",
+      "deny_code": "oap.trade_frequency_exceeded",
+      "description": "Number of trades per day must not exceed limit."
+    },
+    {
+      "name": "idempotency_check",
+      "condition": "context.idempotency_key not in recent_keys",
+      "deny_code": "oap.idempotency_conflict",
+      "description": "Idempotency key must be unique to prevent duplicate trades."
+    },
+    {
+      "name": "pair_volatility_check",
+      "condition": "context.risk_score <= passport.limits.finance.crypto.trade.max_risk_score OR not context.risk_score",
+      "deny_code": "oap.risk_score_exceeded",
+      "description": "Trade risk score must not exceed maximum allowed."
+    },
+    {
+      "name": "exchange_connectivity_check",
+      "condition": "exchange_status[context.exchange_id] == 'online'",
+      "deny_code": "oap.exchange_offline",
+      "description": "Exchange must be online and accessible."
+    },
+    {
+      "name": "market_hours_check",
+      "condition": "is_market_open(context.exchange_id) OR context.side == 'sell'",
+      "deny_code": "oap.market_closed",
+      "description": "Trades must be during market hours unless selling."
+    }
+  ]
+}