@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/agent.session.create.v1/policy.json

@@ -0,0 +1,162 @@
+{
+  "id": "agent.session.create.v1",
+  "name": "Agent Session Creation Policy",
+  "description": "Pre-action governance for AI agent session creation. Enforces session limits, duration restrictions, concurrent session controls, and resource allocation for secure multi-session agent deployments.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["agent.session.create"],
+  "min_assurance": "L0",
+  "limits_required": ["max_sessions_per_user", "max_session_duration"],
+  "required_fields": ["user_id", "session_type"],
+  "optional_fields": [
+    "session_name",
+    "requested_duration",
+    "resources",
+    "metadata",
+    "parent_session_id",
+    "tags"
+  ],
+  "enforcement": {
+    "session_limit_enforced": true,
+    "duration_limit_enforced": true,
+    "concurrent_session_enforced": true,
+    "resource_quota_enforced": true,
+    "session_type_enforced": true
+  },
+  "mcp": {
+    "require_allowlisted_if_present": false
+  },
+  "advice": [
+    "Enforce session limits per user to prevent resource exhaustion",
+    "Set maximum session durations to prevent zombie sessions",
+    "Limit concurrent sessions to manage system load",
+    "Track session creation for billing and auditing",
+    "Use session types to apply different policies",
+    "Implement session tagging for organization and tracking",
+    "Monitor session creation patterns for anomalies",
+    "Log all session creations for Verifiable Attestation",
+    "Subscribe to status webhooks for instant suspend",
+    "Implement progressive limits for new users"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["user_id", "session_type"],
+    "properties": {
+      "user_id": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 200,
+        "description": "User identifier for session owner"
+      },
+      "session_type": {
+        "type": "string",
+        "enum": ["interactive", "batch", "webhook", "scheduled", "ephemeral"],
+        "description": "Type of session being created"
+      },
+      "session_name": {
+        "type": "string",
+        "maxLength": 200,
+        "description": "Human-readable session name"
+      },
+      "requested_duration": {
+        "type": "integer",
+        "minimum": 60,
+        "maximum": 86400,
+        "description": "Requested session duration in seconds"
+      },
+      "resources": {
+        "type": "object",
+        "properties": {
+          "memory_mb": {
+            "type": "integer",
+            "minimum": 128,
+            "maximum": 32768,
+            "description": "Requested memory in MB"
+          },
+          "cpu_millicores": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 8000,
+            "description": "Requested CPU in millicores"
+          },
+          "storage_gb": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "description": "Requested storage in GB"
+          }
+        },
+        "description": "Resource requirements for session"
+      },
+      "metadata": {
+        "type": "object",
+        "additionalProperties": true,
+        "maxProperties": 50,
+        "description": "Custom metadata for session"
+      },
+      "parent_session_id": {
+        "type": "string",
+        "description": "Parent session ID for nested sessions"
+      },
+      "tags": {
+        "type": "array",
+        "items": { "type": "string" },
+        "maxItems": 20,
+        "description": "Tags for session organization"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers to be used in session"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools to be used in session"
+      },
+      "mcp_session": {
+        "type": "string",
+        "description": "MCP session identifier for audit trail"
+      }
+    }
+  },
+  "evaluation_rules_version": "1.0",
+  "evaluation_rules": [
+    {
+      "name": "session_duration_limit",
+      "type": "expression",
+      "condition": "!context.requested_duration || context.requested_duration <= limits.max_session_duration",
+      "deny_code": "oap.duration_limit_exceeded",
+      "description": "Session duration must not exceed limit"
+    },
+    {
+      "name": "session_type_allowed",
+      "type": "expression",
+      "condition": "!limits.allowed_session_types || limits.allowed_session_types.includes(context.session_type)",
+      "deny_code": "oap.session_type_not_allowed",
+      "description": "Session type must be in allowed list"
+    },
+    {
+      "name": "resource_quota",
+      "type": "custom_validator",
+      "validator": "validateResourceQuota",
+      "deny_code": "oap.resource_quota_exceeded",
+      "description": "Requested resources must not exceed quota"
+    },
+    {
+      "name": "concurrent_session_limit",
+      "type": "custom_validator",
+      "validator": "validateConcurrentSessions",
+      "deny_code": "oap.concurrent_limit_exceeded",
+      "description": "Agent must not exceed concurrent session limit"
+    }
+  ],
+  "cache": {
+    "default_ttl_seconds": 60,
+    "suspend_invalidate_seconds": 30
+  },
+  "deprecation": null,
+  "created_at": "2026-02-14T00:00:00Z",
+  "updated_at": "2026-02-14T00:00:00Z"
+}

package/external/aport-policies/agent.tool.register.v1/README.md

@@ -0,0 +1,361 @@
+# Agent Tool Registration Policy v1
+
+**Policy ID:** `agent.tool.register.v1`
+**Status:** Active
+**Min Assurance:** L2
+
+## Overview
+
+The Agent Tool Registration Policy provides pre-action governance for AI agent tool registration. This policy enforces tool naming conventions, capability declarations, security validations, and registration limits to ensure a secure and well-managed tool ecosystem.
+
+## Use Cases
+
+- **Tool Marketplaces**: Registering tools in agent marketplaces
+- **Custom Tools**: Registering custom functions for agent use
+- **MCP Tools**: Registering MCP tool wrappers
+- **API Integrations**: Registering API endpoint tools
+- **Workflow Tools**: Registering multi-step workflow tools
+
+## Required Capabilities
+
+- `agent.tool.register`
+
+## Required Limits
+
+- `max_tools_per_agent` (integer): Maximum tools an agent can register
+- `max_registrations_per_day` (integer): Maximum registrations per day
+
+## Optional Limits
+
+- `allowed_tool_types` (array): Allowed tool types
+- `allowed_capabilities` (array): Allowed capability declarations
+- `require_schema` (boolean): Require JSON schema for tools
+- `require_version` (boolean): Require semantic versioning
+- `require_repository` (boolean): Require source repository URL
+- `allowed_licenses` (array): Allowed licenses
+
+## Context Schema
+
+### Required Fields
+
+- `tool_name` (string): Unique tool name (lowercase, alphanumeric, dots, dashes)
+- `tool_type` (enum): Tool type (function, mcp_tool, api, command, workflow, agent)
+- `capabilities` (array): List of required capabilities
+
+### Optional Fields
+
+- `tool_description` (string): Human-readable description
+- `tool_version` (string): Semantic version
+- `schema` (object): JSON Schema for parameters
+- `author` (string): Tool author
+- `repository` (string): Source code repository URL
+- `license` (enum): Tool license
+- `tags` (array): Categorization tags
+- `metadata` (object): Custom metadata
+- `mcp_servers`, `mcp_tools`, `mcp_session`: MCP integration fields
+
+## Tool Types
+
+- **function**: Simple callable function
+- **mcp_tool**: MCP protocol tool wrapper
+- **api**: RESTful API endpoint wrapper
+- **command**: Shell command wrapper
+- **workflow**: Multi-step workflow orchestrator
+- **agent**: Nested agent invocation
+
+## Evaluation Rules
+
+1. **passport_status_active**: Passport must be active
+2. **tool_register_capability**: Agent must have `agent.tool.register` capability
+3. **tool_count_limit**: Must not exceed max tools per agent
+4. **daily_registration_limit**: Must not exceed daily limit
+5. **tool_name_unique**: Tool name must be unique
+6. **tool_type_allowed**: Tool type must be allowed
+7. **capability_allowed**: All capabilities must be allowed
+8. **naming_convention**: Tool name must follow convention
+
+## Example Passport Limits
+
+```json
+{
+  "limits": {
+    "agent.tool.register": {
+      "max_tools_per_agent": 100,
+      "max_registrations_per_day": 50,
+      "allowed_tool_types": [
+        "function",
+        "mcp_tool",
+        "api",
+        "command",
+        "workflow"
+      ],
+      "allowed_capabilities": [
+        "system.command.execute",
+        "mcp.tool.execute",
+        "data.export",
+        "messaging.message.send"
+      ],
+      "require_schema": true,
+      "require_version": true,
+      "require_repository": false,
+      "allowed_licenses": [
+        "MIT",
+        "Apache-2.0",
+        "BSD-3-Clause",
+        "ISC",
+        "proprietary"
+      ]
+    }
+  }
+}
+```
+
+## Example Request Context
+
+```json
+{
+  "tool_name": "github.pr.create",
+  "tool_type": "mcp_tool",
+  "capabilities": ["mcp.tool.execute", "code.repository.merge"],
+  "tool_description": "Create a GitHub pull request",
+  "tool_version": "1.0.0",
+  "schema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["repo", "title", "head", "base"],
+    "properties": {
+      "repo": { "type": "string" },
+      "title": { "type": "string" },
+      "head": { "type": "string" },
+      "base": { "type": "string" },
+      "body": { "type": "string" }
+    }
+  },
+  "author": "MyOrg Engineering",
+  "repository": "https://github.com/myorg/tools",
+  "license": "MIT",
+  "tags": ["github", "pr", "git"]
+}
+```
+
+## Example Decision (Allow)
+
+```json
+{
+  "decision_id": "dec_tool001",
+  "policy_id": "agent.tool.register.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L2",
+  "allow": true,
+  "reasons": [{
+    "code": "oap.allowed",
+    "message": "All policy checks passed"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:05:00Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Example Decision (Deny - Tool Limit)
+
+```json
+{
+  "decision_id": "dec_tool002",
+  "policy_id": "agent.tool.register.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L2",
+  "allow": false,
+  "reasons": [{
+    "code": "oap.tool_limit_exceeded",
+    "message": "Agent has reached maximum of 100 tool registrations"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:05:00Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Tool Naming Convention
+
+Tool names must follow the pattern: `^[a-z0-9][a-z0-9._-]*[a-z0-9]$`
+
+**Valid Names:**
+- `github.pr.create`
+- `stripe-payment-create`
+- `my_custom_tool`
+- `tool-v2.0`
+
+**Invalid Names:**
+- `GitHub.PR.Create` (uppercase)
+- `-tool-name` (starts with dash)
+- `tool.name.` (ends with dot)
+- `tool name` (contains space)
+
+## Security Best Practices
+
+1. **Tool Limits**: Prevent namespace pollution with registration limits
+2. **Capability Declarations**: Require explicit capability declarations
+3. **Schema Validation**: Enforce JSON schemas for parameter safety
+4. **Versioning**: Use semantic versioning for compatibility
+5. **License Checking**: Validate licenses for compliance
+6. **Repository Links**: Track source code for security audits
+7. **Uniqueness**: Enforce unique tool names to prevent conflicts
+8. **Audit Logging**: Log all registrations for security review
+9. **Progressive Limits**: Start strict and relax for trusted developers
+10. **Status Webhooks**: Subscribe for instant revocation
+
+## Error Codes
+
+- `oap.passport_suspended`: Passport is not active
+- `oap.unknown_capability`: Missing agent.tool.register capability
+- `oap.tool_limit_exceeded`: Exceeded max tools per agent
+- `oap.daily_limit_exceeded`: Exceeded daily registration limit
+- `oap.tool_already_exists`: Tool name already registered
+- `oap.tool_type_not_allowed`: Tool type not allowed
+- `oap.capability_not_allowed`: Capability not allowed
+- `oap.invalid_tool_name`: Tool name doesn't follow convention
+
+## Integration Examples
+
+### TypeScript (Tool Registry)
+
+```typescript
+import axios from 'axios';
+
+interface ToolRegistration {
+  toolName: string;
+  toolType: 'function' | 'mcp_tool' | 'api' | 'command' | 'workflow' | 'agent';
+  capabilities: string[];
+  toolDescription?: string;
+  toolVersion?: string;
+  schema?: object;
+  author?: string;
+  repository?: string;
+  license?: string;
+  tags?: string[];
+  metadata?: Record<string, any>;
+}
+
+async function registerTool(
+  passport: Passport,
+  registration: ToolRegistration
+): Promise<Tool> {
+  const context = {
+    tool_name: registration.toolName,
+    tool_type: registration.toolType,
+    capabilities: registration.capabilities,
+    tool_description: registration.toolDescription,
+    tool_version: registration.toolVersion,
+    schema: registration.schema,
+    author: registration.author,
+    repository: registration.repository,
+    license: registration.license,
+    tags: registration.tags,
+    metadata: registration.metadata
+  };
+
+  // Check policy
+  const decision = await axios.post('https://api.aport.io/v1/decide', {
+    passport_id: passport.passport_id,
+    policy_id: 'agent.tool.register.v1',
+    context
+  });
+
+  if (!decision.data.allow) {
+    throw new Error(`Tool registration blocked: ${decision.data.reasons[0].message}`);
+  }
+
+  // Register tool
+  const tool = await registerToolInDatabase(context);
+
+  // Publish to tool registry
+  await publishToolToRegistry(tool);
+
+  return tool;
+}
+```
+
+### Python (FastAPI)
+
+```python
+from pydantic import BaseModel, Field
+import httpx
+
+class ToolRegistration(BaseModel):
+    tool_name: str = Field(..., pattern=r'^[a-z0-9][a-z0-9._-]*[a-z0-9]$')
+    tool_type: str = Field(..., pattern=r'^(function|mcp_tool|api|command|workflow|agent)$')
+    capabilities: list[str]
+    tool_description: str | None = None
+    tool_version: str | None = Field(None, pattern=r'^\d+\.\d+\.\d+')
+    schema_: dict | None = Field(None, alias='schema')
+    author: str | None = None
+    repository: str | None = None
+    license: str | None = None
+    tags: list[str] = []
+    metadata: dict = {}
+
+async def register_tool(
+    passport: dict,
+    registration: ToolRegistration
+) -> dict:
+    context = registration.dict(by_alias=True, exclude_none=True)
+
+    # 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": "agent.tool.register.v1",
+                "context": context
+            }
+        )
+        decision = response.json()
+
+    if not decision["allow"]:
+        raise PermissionError(f"Tool registration blocked: {decision['reasons'][0]['message']}")
+
+    # Register tool
+    tool = await register_tool_in_database(context)
+
+    # Publish to tool registry
+    await publish_tool_to_registry(tool)
+
+    return tool
+```
+
+## Tool Discovery
+
+Registered tools can be discovered via:
+
+```typescript
+// Search by tags
+const tools = await searchTools({ tags: ['github', 'pr'] });
+
+// Search by capability
+const tools = await searchTools({ capability: 'code.repository.merge' });
+
+// Search by type
+const tools = await searchTools({ type: 'mcp_tool' });
+
+// Full-text search
+const tools = await searchTools({ query: 'pull request' });
+```
+
+## Version History
+
+- **v1.0.0** (2026-02-14): Initial release
+
+## References
+
+- [OAP Specification](https://github.com/aporthq/aport-spec)
+- [Tool Registry Guidelines](https://docs.aport.io/tools)
+- [JSON Schema Documentation](https://json-schema.org/)
+- [Semantic Versioning](https://semver.org/)

package/external/aport-policies/agent.tool.register.v1/policy.json

@@ -0,0 +1,172 @@
+{
+  "id": "agent.tool.register.v1",
+  "name": "Agent Tool Registration Policy",
+  "description": "Pre-action governance for AI agent tool registration. Enforces tool naming conventions, capability declarations, security validations, and registration limits for secure tool ecosystem management.",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["agent.tool.register"],
+  "min_assurance": "L0",
+  "limits_required": ["max_tools_per_agent", "max_registrations_per_day"],
+  "required_fields": ["tool_name", "tool_type", "capabilities"],
+  "optional_fields": [
+    "tool_description",
+    "tool_version",
+    "schema",
+    "author",
+    "repository",
+    "license",
+    "tags",
+    "metadata"
+  ],
+  "enforcement": {
+    "naming_convention_enforced": true,
+    "tool_limit_enforced": true,
+    "capability_validation_enforced": true,
+    "schema_validation_enforced": true,
+    "uniqueness_enforced": true
+  },
+  "mcp": {
+    "require_allowlisted_if_present": false
+  },
+  "advice": [
+    "Enforce tool registration limits to prevent namespace pollution",
+    "Validate tool naming conventions for consistency",
+    "Require capability declarations for security transparency",
+    "Use schema validation for tool parameter safety",
+    "Track tool registrations for auditing and discovery",
+    "Implement tool versioning for compatibility management",
+    "Use tags for tool categorization and search",
+    "Log all tool registrations for Verifiable Attestation",
+    "Subscribe to status webhooks for instant suspend",
+    "Implement progressive limits for new developers"
+  ],
+  "required_context": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["tool_name", "tool_type", "capabilities"],
+    "properties": {
+      "tool_name": {
+        "type": "string",
+        "minLength": 3,
+        "maxLength": 100,
+        "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$",
+        "description": "Unique tool name (lowercase, alphanumeric, dots, dashes, underscores)"
+      },
+      "tool_type": {
+        "type": "string",
+        "enum": ["function", "mcp_tool", "api", "command", "workflow", "agent"],
+        "description": "Type of tool being registered"
+      },
+      "capabilities": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$"
+        },
+        "minItems": 1,
+        "maxItems": 50,
+        "description": "List of capabilities this tool requires"
+      },
+      "tool_description": {
+        "type": "string",
+        "maxLength": 1000,
+        "description": "Human-readable tool description"
+      },
+      "tool_version": {
+        "type": "string",
+        "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?(\\+[a-z0-9.]+)?$",
+        "description": "Semantic version (e.g., 1.0.0, 1.0.0-beta.1)"
+      },
+      "schema": {
+        "type": "object",
+        "description": "JSON Schema for tool parameters"
+      },
+      "author": {
+        "type": "string",
+        "maxLength": 200,
+        "description": "Tool author name or organization"
+      },
+      "repository": {
+        "type": "string",
+        "format": "uri",
+        "description": "Source code repository URL"
+      },
+      "license": {
+        "type": "string",
+        "enum": [
+          "MIT",
+          "Apache-2.0",
+          "GPL-3.0",
+          "BSD-3-Clause",
+          "ISC",
+          "proprietary"
+        ],
+        "description": "Tool license"
+      },
+      "tags": {
+        "type": "array",
+        "items": { "type": "string" },
+        "maxItems": 20,
+        "description": "Tags for tool categorization"
+      },
+      "metadata": {
+        "type": "object",
+        "additionalProperties": true,
+        "maxProperties": 50,
+        "description": "Custom metadata for tool"
+      },
+      "mcp_servers": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP servers used by this tool"
+      },
+      "mcp_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "MCP tools used by this tool"
+      },
+      "mcp_session": {
+        "type": "string",
+        "description": "MCP session identifier for audit trail"
+      }
+    }
+  },
+  "evaluation_rules_version": "1.0",
+  "evaluation_rules": [
+    {
+      "name": "tool_type_allowed",
+      "type": "expression",
+      "condition": "!limits.allowed_tool_types || limits.allowed_tool_types.includes(context.tool_type)",
+      "deny_code": "oap.tool_type_not_allowed",
+      "description": "Tool type must be in allowed list"
+    },
+    {
+      "name": "naming_convention",
+      "type": "custom_validator",
+      "validator": "validateToolNaming",
+      "deny_code": "oap.invalid_tool_name",
+      "description": "Tool name must follow naming convention"
+    },
+    {
+      "name": "tool_name_unique",
+      "type": "custom_validator",
+      "validator": "validateToolUniqueness",
+      "deny_code": "oap.tool_already_exists",
+      "description": "Tool name must be unique"
+    },
+    {
+      "name": "capability_validation",
+      "type": "custom_validator",
+      "validator": "validateToolCapabilities",
+      "deny_code": "oap.capability_not_allowed",
+      "description": "All tool capabilities must be allowed"
+    }
+  ],
+  "cache": {
+    "default_ttl_seconds": 300,
+    "suspend_invalidate_seconds": 60
+  },
+  "deprecation": null,
+  "created_at": "2026-02-14T00:00:00Z",
+  "updated_at": "2026-02-14T00:00:00Z"
+}