@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/messaging.message.send.v1/express.example.js

@@ -0,0 +1,183 @@
+const express = require("express");
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+const app = express();
+app.use(express.json());
+
+// Apply messaging policy to all messaging routes
+app.post(
+  "/messages",
+  requirePolicy("messaging.message.send.v1"),
+  async (req, res) => {
+    try {
+      const { channel, recipients, content, mentions } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Check channel allowlist
+      const allowedChannels =
+        passport.capabilities.find((cap) => cap.id === "messaging.send")?.params
+          ?.channels_allowlist || [];
+
+      if (allowedChannels.length > 0 && !allowedChannels.includes(channel)) {
+        return res.status(403).json({
+          error: "Channel not allowed",
+          allowed_channels: allowedChannels,
+          upgrade_instructions:
+            "Add channel to your passport's channels_allowlist",
+        });
+      }
+
+      // Check mention policy
+      const mentionPolicy =
+        passport.capabilities.find((cap) => cap.id === "messaging.send")?.params
+          ?.mention_policy || "limited";
+
+      if (mentions && mentions.length > 0) {
+        if (mentionPolicy === "none") {
+          return res.status(403).json({
+            error: "Mentions not allowed",
+            mention_policy: mentionPolicy,
+          });
+        }
+        if (mentionPolicy === "limited" && mentions.includes("@everyone")) {
+          return res.status(403).json({
+            error: "@everyone mentions not allowed with limited mention policy",
+          });
+        }
+      }
+
+      // Rate limiting check (would integrate with actual rate limiter)
+      const rateLimitCheck = await checkMessageRateLimit(passport.agent_id);
+      if (!rateLimitCheck.allowed) {
+        return res.status(429).json({
+          error: "Rate limit exceeded",
+          retry_after: rateLimitCheck.retry_after,
+          limits: {
+            per_minute: passport.limits.msgs_per_min,
+            per_day: passport.limits.msgs_per_day,
+          },
+        });
+      }
+
+      // Send message using your messaging service
+      const message_id = await sendMessage({
+        channel,
+        recipients,
+        content,
+        mentions,
+        agent_id: passport.agent_id,
+        agent_name: passport.name,
+      });
+
+      // Record usage for rate limiting
+      await recordMessageUsage(passport.agent_id);
+
+      // Log the message
+      console.log(
+        `Message sent: ${message_id} to ${channel} by agent ${passport.agent_id}`
+      );
+
+      res.json({
+        success: true,
+        message_id,
+        channel,
+        recipients: recipients.length,
+        status: "sent",
+      });
+    } catch (error) {
+      console.error("Message sending error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Broadcast message endpoint
+app.post(
+  "/messages/broadcast",
+  requirePolicy("messaging.message.send.v1"),
+  async (req, res) => {
+    try {
+      const { channels, content, mentions } = req.body;
+      const passport = req.policyResult.passport;
+
+      // Check if broadcast is within daily limits
+      const estimatedMessages = channels.length;
+      const dailyUsage = await getDailyMessageUsage(passport.agent_id);
+
+      if (dailyUsage + estimatedMessages > passport.limits.msgs_per_day) {
+        return res.status(403).json({
+          error: "Broadcast would exceed daily message limit",
+          current_usage: dailyUsage,
+          limit: passport.limits.msgs_per_day,
+          requested: estimatedMessages,
+        });
+      }
+
+      // Process broadcast
+      const results = [];
+      for (const channel of channels) {
+        try {
+          const message_id = await sendMessage({
+            channel,
+            content,
+            mentions,
+            agent_id: passport.agent_id,
+            agent_name: passport.name,
+          });
+          results.push({ channel, message_id, status: "sent" });
+        } catch (error) {
+          results.push({ channel, error: error.message, status: "failed" });
+        }
+      }
+
+      // Record usage
+      await recordMessageUsage(passport.agent_id, channels.length);
+
+      res.json({
+        success: true,
+        results,
+        total_sent: results.filter((r) => r.status === "sent").length,
+        total_failed: results.filter((r) => r.status === "failed").length,
+      });
+    } catch (error) {
+      console.error("Broadcast error:", error);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+);
+
+// Mock functions (implement with your actual messaging service)
+async function sendMessage({
+  channel,
+  recipients,
+  content,
+  mentions,
+  agent_id,
+  agent_name,
+}) {
+  // Simulate message sending
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  return `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+async function checkMessageRateLimit(agent_id) {
+  // Implement with Redis or in-memory rate limiter
+  // For demo, always allow
+  return { allowed: true };
+}
+
+async function recordMessageUsage(agent_id, count = 1) {
+  // Record usage in your rate limiting system
+  console.log(`Recorded ${count} message(s) for agent ${agent_id}`);
+}
+
+async function getDailyMessageUsage(agent_id) {
+  // Get current daily usage from your tracking system
+  return 0; // Mock value
+}
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Messaging service running on port ${PORT}`);
+  console.log("Protected by APort messaging.message.send.v1 policy pack");
+});

package/external/aport-policies/messaging.message.send.v1/fastapi.example.py

@@ -0,0 +1,193 @@
+from fastapi import FastAPI, HTTPException, Request
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from aport.middleware import require_policy
+import asyncio
+
+app = FastAPI(title="Messaging Service", version="1.0.0")
+
+class MessageRequest(BaseModel):
+    channel: str
+    recipients: List[str]
+    content: str
+    mentions: Optional[List[str]] = []
+
+class BroadcastRequest(BaseModel):
+    channels: List[str]
+    content: str
+    mentions: Optional[List[str]] = []
+
+@app.post("/messages")
+@require_policy("messaging.message.send.v1")
+async def send_message(request: Request, message_data: MessageRequest):
+    try:
+        passport = request.state.policy_result.passport
+        
+        # Check channel allowlist
+        messaging_capability = next(
+            (cap for cap in passport.capabilities if cap.id == "messaging.send"), 
+            None
+        )
+        allowed_channels = (
+            messaging_capability.params.get("channels_allowlist", []) 
+            if messaging_capability and messaging_capability.params 
+            else []
+        )
+        
+        if allowed_channels and message_data.channel not in allowed_channels:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "Channel not allowed",
+                    "allowed_channels": allowed_channels,
+                    "upgrade_instructions": "Add channel to your passport's channels_allowlist"
+                }
+            )
+
+        # Check mention policy
+        mention_policy = (
+            messaging_capability.params.get("mention_policy", "limited")
+            if messaging_capability and messaging_capability.params
+            else "limited"
+        )
+        
+        if message_data.mentions:
+            if mention_policy == "none":
+                raise HTTPException(
+                    status_code=403,
+                    detail={
+                        "error": "Mentions not allowed",
+                        "mention_policy": mention_policy
+                    }
+                )
+            if mention_policy == "limited" and "@everyone" in message_data.mentions:
+                raise HTTPException(
+                    status_code=403,
+                    detail={
+                        "error": "@everyone mentions not allowed with limited mention policy"
+                    }
+                )
+
+        # Rate limiting check (would integrate with actual rate limiter)
+        rate_limit_check = await check_message_rate_limit(passport.agent_id)
+        if not rate_limit_check["allowed"]:
+            raise HTTPException(
+                status_code=429,
+                detail={
+                    "error": "Rate limit exceeded",
+                    "retry_after": rate_limit_check.get("retry_after"),
+                    "limits": {
+                        "per_minute": passport.limits.get("msgs_per_min"),
+                        "per_day": passport.limits.get("msgs_per_day")
+                    }
+                }
+            )
+
+        # Send message using your messaging service
+        message_id = await send_message_service({
+            "channel": message_data.channel,
+            "recipients": message_data.recipients,
+            "content": message_data.content,
+            "mentions": message_data.mentions,
+            "agent_id": passport.agent_id,
+            "agent_name": passport.name,
+        })
+
+        # Record usage for rate limiting
+        await record_message_usage(passport.agent_id)
+
+        # Log the message
+        print(f"Message sent: {message_id} to {message_data.channel} by agent {passport.agent_id}")
+
+        return {
+            "success": True,
+            "message_id": message_id,
+            "channel": message_data.channel,
+            "recipients": len(message_data.recipients),
+            "status": "sent",
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"Message sending error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+@app.post("/messages/broadcast")
+@require_policy("messaging.message.send.v1")
+async def broadcast_message(request: Request, broadcast_data: BroadcastRequest):
+    try:
+        passport = request.state.policy_result.passport
+
+        # Check if broadcast is within daily limits
+        estimated_messages = len(broadcast_data.channels)
+        daily_usage = await get_daily_message_usage(passport.agent_id)
+        
+        daily_limit = passport.limits.get("msgs_per_day", float('inf'))
+        if daily_usage + estimated_messages > daily_limit:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": "Broadcast would exceed daily message limit",
+                    "current_usage": daily_usage,
+                    "limit": daily_limit,
+                    "requested": estimated_messages
+                }
+            )
+
+        # Process broadcast
+        results = []
+        for channel in broadcast_data.channels:
+            try:
+                message_id = await send_message_service({
+                    "channel": channel,
+                    "content": broadcast_data.content,
+                    "mentions": broadcast_data.mentions,
+                    "agent_id": passport.agent_id,
+                    "agent_name": passport.name,
+                })
+                results.append({"channel": channel, "message_id": message_id, "status": "sent"})
+            except Exception as error:
+                results.append({"channel": channel, "error": str(error), "status": "failed"})
+
+        # Record usage
+        await record_message_usage(passport.agent_id, len(broadcast_data.channels))
+
+        return {
+            "success": True,
+            "results": results,
+            "total_sent": len([r for r in results if r["status"] == "sent"]),
+            "total_failed": len([r for r in results if r["status"] == "failed"]),
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"Broadcast error: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+# Mock functions (implement with your actual messaging service)
+async def send_message_service(message_data: dict) -> str:
+    """Mock message sending function"""
+    await asyncio.sleep(0.1)  # Simulate API call
+    return f"msg_{asyncio.get_event_loop().time()}_{hash(str(message_data)) % 1000000}"
+
+async def check_message_rate_limit(agent_id: str) -> dict:
+    """Mock rate limit checker"""
+    # Implement with Redis or in-memory rate limiter
+    # For demo, always allow
+    return {"allowed": True}
+
+async def record_message_usage(agent_id: str, count: int = 1) -> None:
+    """Record message usage in your tracking system"""
+    print(f"Recorded {count} message(s) for agent {agent_id}")
+
+async def get_daily_message_usage(agent_id: str) -> int:
+    """Get current daily usage from your tracking system"""
+    return 0  # Mock value
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Messaging service starting...")
+    print("Protected by APort messaging.message.send.v1 policy pack")
+    uvicorn.run(app, host="0.0.0.0", port=8000)

package/external/aport-policies/messaging.message.send.v1/policy.json

@@ -0,0 +1,144 @@
+{
+  "id": "messaging.message.send.v1",
+  "name": "Messaging Protection Policy",
+  "description": "Pre-action governance for messaging operations. Enforces rate limits, channel restrictions, mention policies, and content validation for PLG on-ramp.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["messaging.send"],
+  "min_assurance": "L0",
+  "limits_required": [
+    "msgs_per_min",
+    "msgs_per_day",
+    "allowed_recipients",
+    "approval_required"
+  ],
+  "required_fields": ["channel_id", "message", "message_type"],
+  "optional_fields": ["mentions", "attachments", "thread_id", "reply_to"],
+  "enforcement": {
+    "channels_allowlist_enforced": true,
+    "mention_policy_enforced": true,
+    "rate_limits_enforced": true
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Implement rate limiting per agent and per channel",
+    "Monitor for spam patterns and suspicious activity",
+    "Log all message attempts for Verifiable Attestation",
+    "Consider implementing channel-specific limits",
+    "Use mention policies to prevent @everyone abuse",
+    "Subscribe to status webhooks for instant suspend",
+    "Implement content filtering for inappropriate messages",
+    "Use progressive rate limiting for new agents"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["channel_id", "message", "message_type"],
+    "properties": {
+      "channel_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Target channel identifier"
+      },
+      "message": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 2000,
+        "description": "Message content"
+      },
+      "message_type": {
+        "type": "string",
+        "enum": ["text", "embed", "file", "reaction"],
+        "description": "Type of message"
+      },
+      "mentions": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "User or role mentions in the message"
+      },
+      "attachments": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "filename": { "type": "string" },
+            "size": { "type": "integer" }
+          }
+        },
+        "description": "File attachments"
+      },
+      "thread_id": {
+        "type": "string",
+        "description": "Thread identifier for threaded messages"
+      },
+      "reply_to": {
+        "type": "string",
+        "description": "Message ID being replied to"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.slack.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"slack.messages.send\"])"
+      },
+      "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": "messaging_capability",
+      "condition": "'messaging.send' in passport.capabilities",
+      "deny_code": "oap.unknown_capability",
+      "description": "Agent must have messaging.send capability"
+    },
+    {
+      "name": "rate_limit_minute",
+      "condition": "minute_count < limits.msgs_per_min",
+      "deny_code": "oap.rate_limit_exceeded",
+      "description": "Per-minute rate limit must not be exceeded"
+    },
+    {
+      "name": "rate_limit_daily",
+      "condition": "daily_count < limits.msgs_per_day",
+      "deny_code": "oap.rate_limit_exceeded",
+      "description": "Daily rate limit must not be exceeded"
+    },
+    {
+      "name": "content_validation",
+      "condition": "message.length <= 2000",
+      "deny_code": "oap.content_too_long",
+      "description": "Message must not exceed length limit"
+    }
+  ],
+  "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"
+}

package/external/aport-policies/policy-template.json

@@ -0,0 +1,107 @@
+{
+  "id": "policy.{operation}.v1",
+  "name": "{Operation} Policy",
+  "description": "Pre-action governance for {operation} operations. {Brief description of what this policy protects and enforces}.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["{capability.name}"],
+  "min_assurance": "L2",
+  "limits_required": ["require_assurance_at_least", "idempotency_required"],
+  "required_fields": ["field1", "field2"],
+  "optional_fields": ["optional_field1", "optional_field2"],
+  "enforcement": {
+    "assurance_required": "limits.{capability}.require_assurance_at_least",
+    "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 {operation} attempts for Verifiable Attestation",
+    "Implement appropriate rate limiting",
+    "Use idempotency keys to prevent duplicate operations",
+    "Provide clear error messages to help agents self-remediate"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["field1", "field2"],
+    "properties": {
+      "field1": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Description of field1"
+      },
+      "field2": {
+        "type": "string",
+        "description": "Description of field2"
+      },
+      "optional_field1": {
+        "type": "string",
+        "description": "Description of optional field1"
+      },
+      "optional_field2": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Description of optional field2"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers being used in this request (e.g., [\"https://mcp.stripe.com\", \"https://mcp.notion.com\"])"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools being used in this request (e.g., [\"stripe.refunds.create\", \"notion.pages.export\"])"
+      },
+      "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 >= limits.{capability}.require_assurance_at_least",
+      "deny_code": "oap.assurance_insufficient",
+      "description": "Assurance level must meet minimum requirement"
+    },
+    {
+      "name": "capability_check",
+      "condition": "'{capability.name}' in passport.capabilities",
+      "deny_code": "oap.unknown_capability",
+      "description": "Agent must have required capability"
+    },
+    {
+      "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"
+}