@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-policies/README.md

@@ -0,0 +1,363 @@
+# 🛡️ APort Policy Packs
+
+> **Open Agent Passport (OAP) v1.0 compliant policy definitions for AI agent governance**
+
+This directory contains production-ready policy packs that implement the [Open Agent Passport (OAP) v1.0 specification](https://github.com/aporthq/aport-spec) for real-time AI agent authorization and policy enforcement.
+
+## 🎯 What Are Policy Packs?
+
+Policy packs are **pre-built, OAP-compliant policy definitions** that provide instant governance for your most sensitive AI agent operations. Each pack includes:
+
+- **📋 Standardized Rules** - OAP v1.0 compliant evaluation logic
+- **🔐 Capability Requirements** - What agents need to perform actions
+- **⚡ Real-time Enforcement** - Sub-100ms policy decisions
+- **🛡️ Security Controls** - Multi-level assurance and limits
+- **📊 Audit Trail** - Cryptographically signed decisions
+
+## 🚀 Available Policy Packs
+
+### 🤖 **Agent Management**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`agent.session.create.v1`** | `agent.session.create` | L0 | Session limits, duration restrictions, concurrent session controls |
+| **`agent.tool.register.v1`** | `agent.tool.register` | L0 | Tool naming conventions, capability declarations, registration limits |
+
+### 💳 **Finance & Payments**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`finance.payment.charge.v1`** | `payments.charge` | L2 | Multi-currency limits, merchant allowlists, category blocking |
+| **`finance.payment.refund.v1`** | `finance.payment.refund` | L2 | Cross-currency denial, reason codes, order validation |
+| **`finance.payment.payout.v1`** | `payments.payout` | L3 | Per-currency caps, destination restrictions, compliance requirements |
+| **`finance.transaction.execute.v1`** | `finance.transaction` | L3 | Transaction limits, risk scoring, compliance checks |
+| **`finance.crypto.trade.v1`** | `finance.crypto.trade` | L3 | Crypto trading limits, exchange validation, volatility controls |
+
+### 📊 **Data & Privacy**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`data.export.create.v1`** | `data.export` | L1 | Row limits, PII handling, format validation |
+| **`data.report.ingest.v1`** | `data.report.ingest` | L2 | Data quality checks, schema validation, rate limiting |
+| **`governance.data.access.v1`** | `data.access` | L3 | Access controls, data classification, audit logging |
+
+### 🔀 **Code & Infrastructure**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`code.repository.merge.v1`** | `repo.merge`, `repo.pr.create` | L2 | PR limits, path restrictions, review requirements |
+| **`code.release.publish.v1`** | `release` | L3 | Release validation, environment checks, approval workflows |
+
+### ⚙️ **System & Tools**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`system.command.execute.v1`** | `system.command.execute` | L0 | Command allowlists, blocked patterns, execution time limits |
+| **`mcp.tool.execute.v1`** | `mcp.tool.execute` | L0 | Server allowlists, tool restrictions, parameter validation |
+
+### 💬 **Communication**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`messaging.message.send.v1`** | `messaging.send` | L0 | Rate limiting, channel restrictions, mention policies |
+
+### ⚖️ **Legal & Compliance**
+
+| Policy Pack | Capability | Min Assurance | Key Features |
+|-------------|------------|---------------|--------------|
+| **`legal.contract.review.v1`** | `legal.contract.review` | L3 | Firm-specific guardrails, privilege protection, attorney supervision |
+
+## 🏗️ Policy Pack Structure
+
+All policy packs follow the [OAP v1.0 specification](https://github.com/aporthq/aport-spec) and include:
+
+### **Core OAP Fields**
+```json
+{
+  "id": "finance.payment.charge.v1",
+  "name": "Payment Charge Policy", 
+  "description": "Pre-action governance for agent-initiated payments...",
+  "version": "1.0.0",
+  "status": "active",
+  "requires_capabilities": ["payments.charge"],
+  "min_assurance": "L2"
+}
+```
+
+### **OAP Compliance Features**
+- ✅ **Standardized Error Codes** - Uses `oap.*` error codes
+- ✅ **JSON Schema Validation** - Full context validation via `required_context`
+- ✅ **Nested Limits Structure** - `limits.{capability}.*` format
+- ✅ **Capability-based Authorization** - Proper capability checking
+- ✅ **Assurance Level Validation** - Dynamic assurance requirements
+- ✅ **Idempotency Support** - Duplicate prevention
+- ✅ **Cache Configuration** - TTL and invalidation settings
+
+### **Evaluation Rules**
+```json
+{
+  "evaluation_rules_version": "1.0",
+  "evaluation_rules": [
+    {
+      "name": "command_allowlist",
+      "type": "expression",
+      "condition": "limits.allowed_commands.includes('*') || limits.allowed_commands.includes(context.command)",
+      "deny_code": "oap.command_not_allowed",
+      "description": "Command must be in allowed list"
+    },
+    {
+      "name": "blocked_patterns",
+      "type": "custom_validator",
+      "validator": "validateBlockedPatterns",
+      "deny_code": "oap.blocked_pattern",
+      "description": "Command must not contain blocked patterns"
+    }
+  ]
+}
+```
+
+**Note**: Evaluation rules support two types:
+- **`expression`**: Uses the `condition` field with JavaScript-like expressions
+- **`custom_validator`**: Uses the `validator` field to reference custom validation functions
+
+## 🛠️ Implementation Examples
+
+### Express.js Middleware
+```javascript
+const { requirePolicy } = require("@aporthq/middleware-express");
+
+// Apply payment charge policy
+app.post("/api/charges", 
+  requirePolicy("finance.payment.charge.v1"),
+  async (req, res) => {
+    // Policy already verified! Check specific limits
+    const passport = req.policyResult.passport;
+    
+    if (req.body.amount > passport.limits.payments.charge.currency_limits.USD.max_per_tx) {
+      return res.status(403).json({
+        error: "Charge exceeds limit",
+        requested: req.body.amount,
+        limit: passport.limits.payments.charge.currency_limits.USD.max_per_tx
+      });
+    }
+
+    // Process charge safely
+    const charge = await stripe.charges.create(req.body);
+    res.json({ success: true, charge });
+  }
+);
+```
+
+### FastAPI Middleware
+```python
+from aport.middleware import require_policy
+
+@app.post("/api/charges")
+@require_policy("finance.payment.charge.v1")
+async def create_charge(request: Request, charge_data: dict):
+    passport = request.state.policy_result.passport
+    
+    # Check currency limits
+    currency_limits = passport.limits["payments.charge"]["currency_limits"]
+    if charge_data["amount"] > currency_limits[charge_data["currency"]]["max_per_tx"]:
+        raise HTTPException(403, {
+            "error": "Charge exceeds limit",
+            "requested": charge_data["amount"],
+            "limit": currency_limits[charge_data["currency"]]["max_per_tx"]
+        })
+    
+    # Process charge safely
+    return {"success": True, "charge_id": f"chg_{int(time.time())}"}
+```
+
+### GitHub Actions Integration
+```yaml
+name: APort Verify PR
+on: [pull_request]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify via APort
+        run: |
+          curl -s -X POST "https://api.aport.io/api/verify/policy/code.repository.merge.v1" \
+            -H "Content-Type: application/json" \
+            -d '{
+              "agent_id": "${{ secrets.APORT_AGENT_ID }}",
+              "context": {
+                "repo": "${{ github.repository }}",
+                "base": "${{ github.event.pull_request.base.ref }}",
+                "head": "${{ github.event.pull_request.head.ref }}",
+                "files_changed": ${{ toJson(github.event.pull_request.changed_files) }},
+                "author": "${{ github.event.pull_request.user.login }}"
+              }
+            }'
+        env:
+          APORT_AGENT_ID: ${{ secrets.APORT_AGENT_ID }}
+```
+
+## 🔧 Creating Custom Policy Packs
+
+### 1. Use the Template
+Copy `policy-template.json` and replace placeholders:
+```bash
+cp policy-template.json my-custom-policy.v1.json
+```
+
+### 2. Define Context Schema
+Update `required_context` with your specific fields:
+```json
+{
+  "type": "object",
+  "required": ["amount", "currency", "merchant_id"],
+  "properties": {
+    "amount": {
+      "type": "number",
+      "minimum": 0.01,
+      "description": "Transaction amount"
+    },
+    "currency": {
+      "type": "string",
+      "enum": ["USD", "EUR", "GBP"],
+      "description": "Transaction currency"
+    }
+  }
+}
+```
+
+### 3. Add Evaluation Rules
+Define OAP-compliant evaluation rules:
+```json
+{
+  "evaluation_rules": [
+    {
+      "name": "amount_within_limits",
+      "condition": "context.amount <= limits.my_capability.max_amount",
+      "deny_code": "oap.limit_exceeded",
+      "description": "Transaction amount exceeds allowed limit"
+    }
+  ]
+}
+```
+
+### 4. Configure Enforcement
+Set up enforcement rules in the `enforcement` object:
+```json
+{
+  "enforcement": {
+    "assurance_required": "limits.my_capability.require_assurance_at_least",
+    "idempotency_required": true,
+    "custom_rule": "limits.my_capability.custom_limit"
+  }
+}
+```
+
+## 🧪 Testing Policy Packs
+
+Each policy pack includes comprehensive test suites:
+
+### Test Structure
+```
+policy-name.v1/
+├── policy.json              # Policy definition
+├── README.md                # Documentation
+├── express.example.js       # Express.js example
+├── fastapi.example.py       # FastAPI example
+├── minimal-example.js       # Minimal implementation
+└── tests/
+    ├── passport.template.json    # Template passport
+    ├── passport.instance.json    # Instance passport
+    ├── contexts.jsonl           # Test contexts
+    ├── expected.jsonl           # Expected decisions
+    ├── policy-name.test.js      # JavaScript tests
+    └── test_policy_name.py      # Python tests
+```
+
+### Running Tests
+```bash
+# JavaScript tests
+npm test
+
+# Python tests  
+python -m pytest
+
+# Conformance testing
+npx @aporthq/oap-conformance policy-name.v1/
+```
+
+## 📊 OAP Compliance Standards
+
+### Error Codes
+Always use OAP standard error codes:
+- `oap.passport_suspended` - Agent is suspended
+- `oap.assurance_insufficient` - Assurance level too low
+- `oap.unknown_capability` - Missing required capability
+- `oap.limit_exceeded` - Exceeded limits
+- `oap.currency_unsupported` - Unsupported currency
+- `oap.region_blocked` - Region not allowed
+- `oap.idempotency_conflict` - Duplicate idempotency key
+
+### Limits Structure
+Use nested limits under capability names:
+```json
+{
+  "limits": {
+    "payments.charge": {
+      "currency_limits": { 
+        "USD": { "max_per_tx": 10000 },
+        "EUR": { "max_per_tx": 8500 }
+      },
+      "require_assurance_at_least": "L2",
+      "idempotency_required": true,
+      "allowed_merchant_ids": ["merchant_123", "merchant_456"]
+    }
+  }
+}
+```
+
+### Assurance Levels
+- **L1** - Basic verification (email, domain)
+- **L2** - Enhanced verification (GitHub, social proof)
+- **L3** - High assurance (KYC, legal verification)
+
+## 🔄 Migration Guide
+
+### From Legacy Policies
+1. Add missing OAP fields (`status`, `cache`, `evaluation_rules`)
+2. Update error codes to OAP standard (`oap.*`)
+3. Add JSON Schema validation (`required_context`)
+4. Update limits structure to nested format
+5. Add comprehensive evaluation rules
+
+### Version Updates
+- Update `version` field
+- Update `updated_at` timestamp
+- Document changes in policy description
+- Maintain backward compatibility where possible
+
+## 📚 Resources
+
+- **[OAP v1.0 Specification](https://github.com/aporthq/aport-spec)** - Complete normative specification
+- **[Policy Verification API](../functions/api/verify/policy/)** - Real-time policy evaluation
+- **[Middleware Examples](../middleware/)** - Framework integrations
+- **[SDK Documentation](../sdk/)** - Client libraries
+- **[Conformance Testing](https://github.com/aporthq/aport-spec/tree/main/conformance)** - OAP compliance validation
+
+## 🤝 Contributing
+
+We welcome contributions to policy packs! Whether it's:
+
+- 🐛 **Bug fixes** in existing policies
+- ✨ **New policy packs** for additional use cases
+- 📚 **Documentation** improvements
+- 🧪 **Test coverage** enhancements
+
+Check out our [Contributing Guide](CONTRIBUTING.md) to get started.
+
+---
+
+**🛡️ Secure your AI agents. Trust but verify.**
+
+**Last Updated**: 2026-02-15 18:32:09 UTC

package/external/aport-policies/agent.session.create.v1/README.md

@@ -0,0 +1,345 @@
+# Agent Session Creation Policy v1
+
+**Policy ID:** `agent.session.create.v1`
+**Status:** Active
+**Min Assurance:** L1
+
+## Overview
+
+The Agent Session Creation Policy provides pre-action governance for AI agent session creation. This policy enforces session limits, duration restrictions, concurrent session controls, and resource allocation to ensure secure and efficient multi-session agent deployments.
+
+## Use Cases
+
+- **Multi-User AI Platforms**: Managing sessions across multiple users
+- **Development Agents**: Creating sessions for different projects/workspaces
+- **Batch Processing**: Creating ephemeral sessions for background tasks
+- **Interactive Chat**: Managing conversational agent sessions
+- **Scheduled Tasks**: Creating sessions for cron-like operations
+
+## Required Capabilities
+
+- `agent.session.create`
+
+## Required Limits
+
+- `max_sessions_per_user` (integer): Maximum sessions per user
+- `max_session_duration` (integer): Maximum session duration in seconds
+
+## Optional Limits
+
+- `max_concurrent_sessions` (integer): Maximum concurrent active sessions
+- `allowed_session_types` (array): Allowed session types
+- `max_sessions_per_day` (integer): Maximum sessions created per day
+- `resource_quota` (object): Resource limits (memory, CPU, storage)
+- `default_session_duration` (integer): Default duration if not specified
+- `require_session_names` (boolean): Require human-readable names
+
+## Context Schema
+
+### Required Fields
+
+- `user_id` (string): User identifier for session owner
+- `session_type` (enum): Type of session (interactive, batch, webhook, scheduled, ephemeral)
+
+### Optional Fields
+
+- `session_name` (string): Human-readable session name
+- `requested_duration` (integer): Requested session duration in seconds
+- `resources` (object): Resource requirements (memory_mb, cpu_millicores, storage_gb)
+- `metadata` (object): Custom metadata
+- `parent_session_id` (string): Parent session for nested sessions
+- `tags` (array): Tags for organization
+- `mcp_servers`, `mcp_tools`, `mcp_session`: MCP integration fields
+
+## Evaluation Rules
+
+1. **passport_status_active**: Passport must be active
+2. **session_capability**: Agent must have `agent.session.create` capability
+3. **session_limit_per_user**: User must not exceed max sessions
+4. **concurrent_session_limit**: Agent must not exceed concurrent sessions
+5. **session_duration_limit**: Duration must not exceed maximum
+6. **session_type_allowed**: Session type must be allowed
+7. **resource_quota**: Requested resources must be within quota
+8. **daily_session_limit**: Daily session creations must not exceed limit
+
+## Example Passport Limits
+
+```json
+{
+  "limits": {
+    "agent.session.create": {
+      "max_sessions_per_user": 10,
+      "max_concurrent_sessions": 50,
+      "max_session_duration": 3600,
+      "max_sessions_per_day": 100,
+      "allowed_session_types": [
+        "interactive",
+        "batch",
+        "scheduled",
+        "ephemeral"
+      ],
+      "resource_quota": {
+        "memory_mb": 4096,
+        "cpu_millicores": 2000,
+        "storage_gb": 10
+      },
+      "default_session_duration": 1800,
+      "require_session_names": false
+    }
+  }
+}
+```
+
+## Example Request Context
+
+```json
+{
+  "user_id": "user_abc123",
+  "session_type": "interactive",
+  "session_name": "Code Review Session",
+  "requested_duration": 3600,
+  "resources": {
+    "memory_mb": 2048,
+    "cpu_millicores": 1000,
+    "storage_gb": 5
+  },
+  "metadata": {
+    "project": "myproject",
+    "environment": "development"
+  },
+  "tags": ["code-review", "pr-123"]
+}
+```
+
+## Example Decision (Allow)
+
+```json
+{
+  "decision_id": "dec_sess001",
+  "policy_id": "agent.session.create.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:01:00Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Example Decision (Deny - Session Limit)
+
+```json
+{
+  "decision_id": "dec_sess002",
+  "policy_id": "agent.session.create.v1",
+  "passport_id": "pass_abc123",
+  "owner_id": "org_12345",
+  "assurance_level": "L1",
+  "allow": false,
+  "reasons": [{
+    "code": "oap.session_limit_exceeded",
+    "message": "User has reached maximum of 10 sessions"
+  }],
+  "issued_at": "2026-02-14T22:00:00Z",
+  "expires_at": "2026-02-14T22:01:00Z",
+  "passport_digest": "sha256:...",
+  "signature": "ed25519:...",
+  "kid": "oap:registry:key-2026-02"
+}
+```
+
+## Security Best Practices
+
+1. **Session Limits**: Prevent resource exhaustion with per-user limits
+2. **Duration Caps**: Set maximum durations to prevent zombie sessions
+3. **Concurrent Controls**: Limit active sessions to manage system load
+4. **Resource Quotas**: Enforce memory/CPU/storage limits
+5. **Session Tracking**: Log all session creations for auditing
+6. **Session Types**: Use types to apply different policies
+7. **Auto-Expiration**: Implement automatic session cleanup
+8. **Progressive Limits**: Start strict and relax for trusted users
+9. **Status Webhooks**: Subscribe for instant revocation
+10. **Session Tagging**: Enable organization and cost allocation
+
+## Session Types
+
+### Interactive
+- User-facing chat or CLI sessions
+- Typically shorter duration (minutes to hours)
+- Requires real-time responsiveness
+
+### Batch
+- Background processing tasks
+- Can be longer duration (hours)
+- Lower priority for resources
+
+### Webhook
+- Triggered by external events
+- Short-lived (seconds to minutes)
+- Event-driven lifecycle
+
+### Scheduled
+- Cron-like scheduled tasks
+- Predictable execution patterns
+- Can be recurring
+
+### Ephemeral
+- Temporary, disposable sessions
+- Very short duration (seconds)
+- Minimal resource allocation
+
+## Error Codes
+
+- `oap.passport_suspended`: Passport is not active
+- `oap.unknown_capability`: Missing agent.session.create capability
+- `oap.session_limit_exceeded`: User exceeded max sessions
+- `oap.concurrent_limit_exceeded`: Too many concurrent sessions
+- `oap.duration_limit_exceeded`: Requested duration too long
+- `oap.session_type_not_allowed`: Session type not allowed
+- `oap.resource_quota_exceeded`: Requested resources exceed quota
+- `oap.daily_limit_exceeded`: Daily session creation limit exceeded
+
+## Integration Examples
+
+### TypeScript (Session Manager)
+
+```typescript
+import axios from 'axios';
+
+interface SessionRequest {
+  userId: string;
+  sessionType: 'interactive' | 'batch' | 'webhook' | 'scheduled' | 'ephemeral';
+  sessionName?: string;
+  requestedDuration?: number;
+  resources?: {
+    memory_mb?: number;
+    cpu_millicores?: number;
+    storage_gb?: number;
+  };
+  metadata?: Record<string, any>;
+  tags?: string[];
+}
+
+async function createSession(
+  passport: Passport,
+  request: SessionRequest
+): Promise<Session> {
+  const context = {
+    user_id: request.userId,
+    session_type: request.sessionType,
+    session_name: request.sessionName,
+    requested_duration: request.requestedDuration || 1800,
+    resources: request.resources,
+    metadata: request.metadata,
+    tags: request.tags
+  };
+
+  // Check policy
+  const decision = await axios.post('https://api.aport.io/v1/decide', {
+    passport_id: passport.passport_id,
+    policy_id: 'agent.session.create.v1',
+    context
+  });
+
+  if (!decision.data.allow) {
+    throw new Error(`Session creation blocked: ${decision.data.reasons[0].message}`);
+  }
+
+  // Create session
+  const session = await createSessionInDatabase(context);
+
+  // Schedule auto-cleanup
+  scheduleSessionCleanup(session.id, context.requested_duration);
+
+  return session;
+}
+```
+
+### Python (FastAPI)
+
+```python
+from datetime import datetime, timedelta
+import httpx
+
+async def create_session(
+    passport: dict,
+    user_id: str,
+    session_type: str,
+    session_name: str | None = None,
+    requested_duration: int = 1800,
+    resources: dict | None = None,
+    metadata: dict | None = None,
+    tags: list[str] | None = None
+) -> dict:
+    context = {
+        "user_id": user_id,
+        "session_type": session_type,
+        "session_name": session_name,
+        "requested_duration": requested_duration,
+        "resources": resources or {},
+        "metadata": metadata or {},
+        "tags": tags or []
+    }
+
+    # 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.session.create.v1",
+                "context": context
+            }
+        )
+        decision = response.json()
+
+    if not decision["allow"]:
+        raise PermissionError(f"Session creation blocked: {decision['reasons'][0]['message']}")
+
+    # Create session
+    session = await create_session_in_database(context)
+
+    # Schedule auto-cleanup
+    expires_at = datetime.utcnow() + timedelta(seconds=requested_duration)
+    await schedule_session_cleanup(session["id"], expires_at)
+
+    return session
+```
+
+## Resource Management
+
+Sessions should track and enforce resource usage:
+
+```typescript
+interface SessionResources {
+  memory_mb: number;      // RAM allocation
+  cpu_millicores: number; // CPU allocation (1000 = 1 core)
+  storage_gb: number;     // Disk allocation
+  network_mbps: number;   // Network bandwidth
+}
+
+// Calculate resource costs
+function calculateResourceCost(resources: SessionResources, duration_hours: number): number {
+  const memory_cost = (resources.memory_mb / 1024) * 0.01 * duration_hours;
+  const cpu_cost = (resources.cpu_millicores / 1000) * 0.05 * duration_hours;
+  const storage_cost = resources.storage_gb * 0.001 * duration_hours;
+
+  return memory_cost + cpu_cost + storage_cost;
+}
+```
+
+## Version History
+
+- **v1.0.0** (2026-02-14): Initial release
+
+## References
+
+- [OAP Specification](https://github.com/aporthq/aport-spec)
+- [Session Management Best Practices](https://docs.aport.io/sessions)