🛡️ 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 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

💳 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.transaction.execute.v1	finance.transaction	L2	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	L1	Data quality checks, schema validation, rate limiting
governance.data.access.v1	data.access	L2	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	repo.release	L3	Release validation, environment checks, approval workflows

💬 Communication

Policy Pack	Capability	Min Assurance	Key Features
messaging.message.send.v1	messaging.send	L1	Rate limiting, channel restrictions, mention policies

🏗️ Policy Pack Structure

All policy packs follow the OAP v1.0 specification and include:

Core OAP Fields

{
  "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

{
  "evaluation_rules": [
    {
      "name": "passport_active",
      "condition": "passport.status == 'active'",
      "deny_code": "oap.passport_suspended",
      "description": "Agent passport must be active"
    },
    {
      "name": "assurance_sufficient", 
      "condition": "passport.assurance_level >= limits.payments.charge.require_assurance_at_least",
      "deny_code": "oap.assurance_insufficient",
      "description": "Insufficient assurance level for payment operations"
    }
  ]
}

🛠️ Implementation Examples

Express.js Middleware

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

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

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:

cp policy-template.json my-custom-policy.v1.json

2. Define Context Schema

Update required_context with your specific fields:

{
  "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:

{
  "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:

{
  "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

# 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:

{
  "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 - Complete normative specification
• Policy Verification API - Real-time policy evaluation
• Middleware Examples - Framework integrations
• SDK Documentation - Client libraries
• Conformance Testing - 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 to get started.

---

🛡️ Secure your AI agents. Trust but verify.

Last Updated: 2025-10-08 14:54:16 UTC