@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/mcp.tool.execute.v1/README.md

@@ -0,0 +1,301 @@
+# MCP Tool Execution Policy v1
+
+**Policy ID:** `mcp.tool.execute.v1`
+**Status:** Active
+**Min Assurance:** L1
+
+## Overview
+
+The MCP Tool Execution Policy provides pre-action governance for Model Context Protocol (MCP) tool execution by AI agents. This policy enforces server allowlists, tool restrictions, parameter validation, and rate limits to ensure secure MCP integration.
+
+## Use Cases
+
+- **Multi-Tool AI Agents**: Executing tools across multiple MCP servers
+- **GitHub Integration**: Using GitHub MCP tools (pull requests, issues, etc.)
+- **Database Operations**: Executing database queries via MCP
+- **API Integration**: Calling external APIs through MCP tools
+- **Development Workflows**: Automating development tasks with MCP
+
+## Required Capabilities
+
+- `mcp.tool.execute`
+
+## Required Limits
+
+- `allowed_servers` (array of strings): Allowlist of MCP server URLs
+- `max_calls_per_minute` (integer): Maximum tool calls per minute
+
+## Optional Limits
+
+- `allowed_tools` (array of strings): Specific tools allowed
+- `allowed_tool_prefixes` (array of strings): Tool name prefixes allowed
+- `blocked_tools` (array of strings): Specific tools blocked
+- `max_timeout` (integer): Maximum tool execution timeout
+- `max_parameter_size` (integer): Maximum parameter size in bytes
+- `require_session_tracking` (boolean): Require session IDs for all calls
+
+## Context Schema
+
+### Required Fields
+
+- `server` (string): MCP server URL
+- `tool` (string): MCP tool name
+- `parameters` (object): Tool-specific parameters
+
+### Optional Fields
+
+- `session_id` (string): MCP session identifier
+- `timeout` (integer): Tool execution timeout
+- `context` (object): Additional context
+- `user_id` (string): User on whose behalf tool is executed
+- `mcp_servers`, `mcp_tools`, `mcp_session`: Audit trail fields
+
+## Evaluation Rules
+
+1. **passport_status_active**: Passport must be active
+2. **mcp_capability**: Agent must have `mcp.tool.execute` capability
+3. **server_allowlist**: MCP server must be in allowed list
+4. **tool_allowlist**: Tool must be allowed (exact match or prefix match)
+5. **rate_limit**: Calls per minute must not exceed limit
+6. **timeout_limit**: Timeout must not exceed maximum
+7. **parameter_size_limit**: Parameters must not exceed size limit
+
+## Example Passport Limits
+
+```json
+{
+  "limits": {
+    "mcp.tool.execute": {
+      "allowed_servers": [
+        "https://mcp.github.com",
+        "https://mcp.stripe.com",
+        "https://mcp.internal.company.com"
+      ],
+      "allowed_tools": [
+        "github.pull_requests.create",
+        "github.pull_requests.merge",
+        "github.issues.create",
+        "stripe.customers.create",
+        "stripe.charges.create"
+      ],
+      "allowed_tool_prefixes": [
+        "github.pull_requests.",
+        "github.issues.",
+        "stripe.customers."
+      ],
+      "blocked_tools": [
+        "github.repos.delete",
+        "stripe.subscriptions.cancel"
+      ],
+      "max_calls_per_minute": 60,
+      "max_timeout": 120,
+      "max_parameter_size": 102400,
+      "require_session_tracking": true
+    }
+  }
+}
+```
+
+## Example Request Context
+
+```json
+{
+  "server": "https://mcp.github.com",
+  "tool": "github.pull_requests.create",
+  "parameters": {
+    "owner": "myorg",
+    "repo": "myrepo",
+    "title": "Add new feature",
+    "head": "feature-branch",
+    "base": "main",
+    "body": "This PR adds a new feature"
+  },
+  "session_id": "sess_abc123",
+  "timeout": 60,
+  "user_id": "user_xyz789"
+}
+```
+
+## Example Decision (Allow)
+
+```json
+{
+  "decision_id": "dec_mcp001",
+  "policy_id": "mcp.tool.execute.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L1",
+  "allow": true,
+  "reasons": [{
+    "code": "oap.allowed",
+    "message": "All policy checks passed"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:00:30Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Example Decision (Deny - Tool Not Allowed)
+
+```json
+{
+  "decision_id": "dec_mcp002",
+  "policy_id": "mcp.tool.execute.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L1",
+  "allow": false,
+  "reasons": [{
+    "code": "oap.tool_not_allowed",
+    "message": "MCP tool 'github.repos.delete' is not in allowed list"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:00:30Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Security Best Practices
+
+1. **Server Allowlist**: Only allow trusted MCP servers
+2. **Tool Restrictions**: Use granular tool permissions (not wildcards)
+3. **Rate Limiting**: Prevent abuse with conservative rate limits
+4. **Session Tracking**: Require session IDs for audit trails
+5. **Parameter Validation**: Enforce parameter size limits
+6. **Tool Prefixes**: Use prefixes for tool families (e.g., "github.pull_requests.")
+7. **Block Dangerous Tools**: Explicitly block destructive operations
+8. **Progressive Limits**: Start strict and relax based on behavior
+9. **Status Webhooks**: Subscribe for instant revocation
+10. **Audit Logging**: Log all MCP tool calls with parameters
+
+## Error Codes
+
+- `oap.passport_suspended`: Passport is not active
+- `oap.unknown_capability`: Missing mcp.tool.execute capability
+- `oap.server_not_allowed`: MCP server not in allowlist
+- `oap.tool_not_allowed`: Tool not in allowlist
+- `oap.rate_limit_exceeded`: Too many calls per minute
+- `oap.timeout_exceeded`: Timeout exceeds maximum
+- `oap.parameter_size_exceeded`: Parameters too large
+
+## Integration Examples
+
+### TypeScript (MCP Client)
+
+```typescript
+import { MCPClient } from '@modelcontextprotocol/client';
+import axios from 'axios';
+
+async function executeMCPTool(
+  passport: Passport,
+  server: string,
+  tool: string,
+  parameters: Record<string, any>
+) {
+  const context = {
+    server,
+    tool,
+    parameters,
+    session_id: generateSessionId(),
+    timeout: 60
+  };
+
+  // Check policy
+  const decision = await axios.post('https://api.aport.io/v1/decide', {
+    passport_id: passport.passport_id,
+    policy_id: 'mcp.tool.execute.v1',
+    context
+  });
+
+  if (!decision.data.allow) {
+    throw new Error(`MCP tool blocked: ${decision.data.reasons[0].message}`);
+  }
+
+  // Execute MCP tool
+  const client = new MCPClient(server);
+  const result = await client.callTool(tool, parameters, {
+    timeout: context.timeout * 1000
+  });
+
+  return result;
+}
+```
+
+### Python (MCP Integration)
+
+```python
+import httpx
+from mcp_client import MCPClient
+
+async def execute_mcp_tool(
+    passport: dict,
+    server: str,
+    tool: str,
+    parameters: dict
+):
+    context = {
+        "server": server,
+        "tool": tool,
+        "parameters": parameters,
+        "session_id": generate_session_id(),
+        "timeout": 60
+    }
+
+    # Check policy
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "https://api.aport.io/v1/decide",
+            json={
+                "passport_id": passport["passport_id"],
+                "policy_id": "mcp.tool.execute.v1",
+                "context": context
+            }
+        )
+        decision = response.json()
+
+    if not decision["allow"]:
+        raise PermissionError(f"MCP tool blocked: {decision['reasons'][0]['message']}")
+
+    # Execute MCP tool
+    mcp_client = MCPClient(server)
+    result = await mcp_client.call_tool(
+        tool,
+        parameters,
+        timeout=context["timeout"]
+    )
+
+    return result
+```
+
+## MCP Tool Name Conventions
+
+MCP tools follow the convention: `<service>.<resource>.<action>`
+
+Examples:
+- `github.pull_requests.create`
+- `github.pull_requests.merge`
+- `github.issues.create`
+- `stripe.customers.create`
+- `stripe.charges.refund`
+- `database.queries.execute`
+- `api.endpoints.call`
+
+Use `allowed_tool_prefixes` for tool families:
+- `github.pull_requests.*` → All PR operations
+- `github.issues.*` → All issue operations
+- `stripe.customers.*` → All customer operations
+
+## Version History
+
+- **v1.0.0** (2026-02-14): Initial release
+
+## References
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io)
+- [OAP Specification](https://github.com/aporthq/aport-spec)
+- [MCP Tool Registry](https://mcp.tools)

package/external/aport-policies/mcp.tool.execute.v1/policy.json

@@ -0,0 +1,141 @@
+{
+  "id": "mcp.tool.execute.v1",
+  "name": "MCP Tool Execution Policy",
+  "description": "Pre-action governance for Model Context Protocol (MCP) tool execution. Enforces server allowlists, tool restrictions, parameter validation, and rate limits for secure MCP integration.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["mcp.tool.execute"],
+  "min_assurance": "L0",
+  "limits_required": ["allowed_servers", "max_calls_per_minute"],
+  "required_fields": ["server", "tool", "parameters"],
+  "optional_fields": ["session_id", "timeout", "context", "user_id"],
+  "enforcement": {
+    "server_allowlist_enforced": true,
+    "tool_allowlist_enforced": true,
+    "rate_limits_enforced": true,
+    "parameter_validation_enforced": true,
+    "session_tracking_enforced": false
+  },
+  "mcp": {
+    "require_allowlisted_if_present": true
+  },
+  "advice": [
+    "Use server allowlists to prevent unauthorized MCP connections",
+    "Restrict tools to minimum required for agent functionality",
+    "Enforce rate limits to prevent MCP server abuse",
+    "Validate tool parameters against expected schemas",
+    "Log all MCP tool calls for Verifiable Attestation",
+    "Use session tracking for cross-tool audit trails",
+    "Subscribe to status webhooks for instant suspend",
+    "Implement progressive limits for new MCP integrations",
+    "Monitor MCP usage patterns for anomalies",
+    "Consider tool-specific parameter restrictions"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["server", "tool", "parameters"],
+    "properties": {
+      "server": {
+        "type": "string",
+        "format": "uri",
+        "description": "MCP server URL (e.g., 'https://mcp.github.com')"
+      },
+      "tool": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 200,
+        "pattern": "^[a-zA-Z0-9._-]+$",
+        "description": "MCP tool name (e.g., 'github.pull_requests.create')"
+      },
+      "parameters": {
+        "type": "object",
+        "description": "Tool-specific parameters"
+      },
+      "session_id": {
+        "type": "string",
+        "description": "MCP session identifier for tracking"
+      },
+      "timeout": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 300,
+        "description": "Tool execution timeout in seconds"
+      },
+      "context": {
+        "type": "object",
+        "description": "Additional context for tool execution"
+      },
+      "user_id": {
+        "type": "string",
+        "description": "User on whose behalf the tool is being executed"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Additional MCP servers being used"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Additional MCP tools being used"
+      },
+      "mcp_session": {
+        "type": "string",
+        "description": "MCP session identifier for audit trail"
+      }
+    }
+  },
+  "evaluation_rules_version": "1.0",
+  "evaluation_rules": [
+    {
+      "name": "server_allowlist",
+      "type": "expression",
+      "condition": "limits.allowed_servers.includes(context.server) || limits.allowed_servers.includes('*')",
+      "deny_code": "oap.server_not_allowed",
+      "description": "MCP server must be in allowed list"
+    },
+    {
+      "name": "server_url_format",
+      "type": "custom_validator",
+      "validator": "validateMCPServer",
+      "deny_code": "oap.invalid_server_url",
+      "description": "MCP server URL must be valid and secure"
+    },
+    {
+      "name": "tool_allowlist",
+      "type": "expression",
+      "condition": "(limits.allowed_tools && (limits.allowed_tools.includes(context.tool) || limits.allowed_tools.includes('*'))) || (limits.allowed_tool_prefixes && limits.allowed_tool_prefixes.some(prefix => context.tool.startsWith(prefix)))",
+      "deny_code": "oap.tool_not_allowed",
+      "description": "MCP tool must be in allowed list or match allowed prefix"
+    },
+    {
+      "name": "rate_limit",
+      "type": "custom_validator",
+      "validator": "validateMCPRateLimit",
+      "deny_code": "oap.rate_limit_exceeded",
+      "description": "MCP tool calls must not exceed rate limit"
+    },
+    {
+      "name": "timeout_limit",
+      "type": "expression",
+      "condition": "!context.timeout || !limits.max_timeout || context.timeout <= limits.max_timeout",
+      "deny_code": "oap.timeout_exceeded",
+      "description": "Tool timeout must not exceed limit"
+    },
+    {
+      "name": "parameter_size_limit",
+      "type": "custom_validator",
+      "validator": "validateParameterSize",
+      "deny_code": "oap.parameter_size_exceeded",
+      "description": "Tool parameters must not exceed size limit"
+    }
+  ],
+  "cache": {
+    "default_ttl_seconds": 30,
+    "suspend_invalidate_seconds": 15
+  },
+  "deprecation": null,
+  "created_at": "2026-02-14T00:00:00Z",
+  "updated_at": "2026-02-14T00:00:00Z"
+}

package/external/aport-policies/messaging.message.send.v1/README.md

@@ -0,0 +1,230 @@
+# Messaging Policy Pack v1
+
+## Overview
+
+The `messaging.message.send.v1` policy pack protects messaging endpoints with rate limits, channel restrictions, and mention policies. This is designed as a PLG (Product-Led Growth) on-ramp for harmless messaging use cases across Slack, Discord, Email, and other channels.
+
+## Policy Requirements
+
+| **Requirement** | **Value** | **Description** |
+|-----------------|-----------|-----------------|
+| **Capability** | `messaging.send` | Agent must have messaging capability |
+| **Assurance** | L0 | Minimum assurance level required |
+| **Rate Limits** | `msgs_per_min`, `msgs_per_day` | Required rate limiting configuration |
+
+## Limits Configuration
+
+### Required Limits
+
+- **`msgs_per_min`**: Maximum messages per minute (1-1000)
+- **`msgs_per_day`**: Maximum messages per day (1-50000)
+
+### Capability Parameters
+
+- **`channels_allowlist`**: Comma-separated list of allowed channels (slack, discord, email)
+- **`mention_policy`**: Policy for @mentions (none, limited, all)
+- **`max_recipients`**: Maximum number of recipients per message
+
+## Example Usage
+
+### Express.js
+
+```javascript
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+app.post("/messages", requirePolicy("messaging.message.send.v1"), async (req, res) => {
+  const { channel, recipients, content, mentions } = req.body;
+  const passport = req.policyResult.passport;
+
+  // Policy automatically enforces:
+  // - Channel allowlist validation
+  // - Rate limiting (msgs_per_min, msgs_per_day)
+  // - Mention policy enforcement
+  // - Assurance level checking (L0+)
+
+  // Your messaging logic here
+  const message_id = await sendMessage({
+    channel,
+    recipients,
+    content,
+    mentions,
+    agent_id: passport.agent_id,
+  });
+
+  res.json({ success: true, message_id });
+});
+```
+
+### FastAPI
+
+```python
+from aport.middleware import require_policy
+
+@app.post("/messages")
+@require_policy("messaging.message.send.v1")
+async def send_message(request: Request, message_data: MessageRequest):
+    passport = request.state.policy_result.passport
+    
+    # Policy automatically enforces all requirements
+    # Your messaging logic here
+    
+    return {"success": True, "message_id": message_id}
+```
+
+## Policy Violations
+
+### Channel Not Allowlisted
+
+```json
+{
+  "error": "messaging_policy_violation",
+  "reason": "channel_not_allowlisted",
+  "channel": "teams",
+  "allowed_channels": ["slack", "discord", "email"],
+  "upgrade_instructions": "Add 'teams' to your passport's channels_allowlist parameter"
+}
+```
+
+### Rate Limit Exceeded
+
+```json
+{
+  "error": "messaging_policy_violation",
+  "reason": "rate_limit_exceeded",
+  "limit_type": "per_minute",
+  "current_usage": 95,
+  "limit": 100,
+  "retry_after": 60
+}
+```
+
+### Mention Policy Violation
+
+```json
+{
+  "error": "messaging_policy_violation",
+  "reason": "mention_not_allowed",
+  "mention_policy": "limited",
+  "violation": "@everyone mentions not allowed with limited policy"
+}
+```
+
+## Best Practices
+
+### Implementation
+
+1. **Rate Limiting**: Implement proper rate limiting per agent and per channel
+2. **Channel Validation**: Always validate channels against the allowlist
+3. **Mention Control**: Enforce mention policies to prevent spam
+4. **Verifiable Attestation**: Log all message attempts for security monitoring
+5. **Error Handling**: Provide clear error messages for policy violations
+
+### Security
+
+1. **Monitor Patterns**: Watch for spam patterns and suspicious activity
+2. **Webhook Integration**: Subscribe to status webhooks for instant suspend
+3. **Content Filtering**: Consider implementing content filtering for harmful messages
+4. **Channel-Specific Limits**: Implement different limits for different channels
+
+### Performance
+
+1. **Cache Verification**: Cache passport verification results (60s TTL recommended)
+2. **Async Processing**: Use async processing for bulk message operations
+3. **Rate Limiter**: Use Redis or similar for distributed rate limiting
+4. **Batch Operations**: Support batch messaging with proper limit checking
+
+## Why This Policy Pack?
+
+- **Mass Market**: Messaging is harmless and perfect for PLG onboarding
+- **Demo Friendly**: Easy to demonstrate limits and suspend functionality
+- **Channel Diversity**: Supports multiple messaging platforms (Slack, Discord, Email)
+- **Scalable**: Rate limits prevent abuse while allowing legitimate use
+- **Compliance Ready**: Built-in Verifiable Attestation and policy enforcement
+
+## Integration Examples
+
+- **Customer Support**: Automated responses via Slack/Discord
+- **Marketing**: Email campaigns with rate limiting
+- **Notifications**: System alerts across multiple channels
+- **Community Management**: Moderated Discord/Slack interactions
+- **Internal Tools**: Employee messaging and announcements
+
+
+## Required Context
+
+This policy requires the following context (JSON Schema):
+
+```json
+{
+  "$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"
+    }
+  }
+}
+```
+
+You can also fetch this live via the discovery endpoint:
+
+```bash
+curl -s "https://aport.io/api/policies/messaging.message.send.v1?format=schema"
+```
+