pi-opa

Enterprise-grade Open Policy Agent (OPA) integration for pi coding agent. Provides comprehensive authorization, authentication, and policy enforcement for multi-agent systems.

Overview

pi-opa brings enterprise-class authorization to pi using the industry-standard Open Policy Agent (OPA). It enables:

• Policy-as-Code - Define authorization rules in Rego language
• Multi-dimensional Access Control - WHO, WHAT, WHEN, WHERE, WHY
• Audit Logging - Complete decision trail for compliance
• A2A Integration - Secure multi-agent authorization
• Dynamic Policy Updates - Hot-reload without restarting

Prerequisites

• pi coding agent >= 1.0.0
• Node.js >= 18.0.0
• OPA binary installed (opa) - Install OPA

Installation

# Via npm (recommended)
pi install npm:pi-opa

# Via git
pi install git:github.com/DrOlu/pi-opa

Quick Start

1. Start OPA Server

/opa-start
# OPA server started on localhost:8181

2. Create a Policy

/opa-template my_policy
# Created: ~/.pi/agent/opa/policies/my_policy.rego

3. Edit the Policy

Edit the generated policy file to add your rules.

4. Test Authorization

/opa-check ci-bot deploy production
# ✅ ALLOWED
# Agent: ci-bot
# Action: deploy
# Resource: production
# Reason: Agent has high trust level and is within business hours

Features

Authorization Commands

| Command | Description | |---------|-------------| | /opa-check | Check authorization for an action | | /opa-start | Start OPA server | | /opa-stop | Stop OPA server | | /opa-status | Show OPA status |

Policy Management

| Command | Description | |---------|-------------| | /opa-load | Load policies from directory | | /opa-test | Test policies | | /opa-validate | Validate policy syntax | | /opa-template | Create policy template |

Audit & Logging

| Command | Description | |---------|-------------| | /opa-audit | Show authorization audit log | | /opa-export-audit | Export audit log (json/csv) |

Configuration

| Command | Description | |---------|-------------| | /opa-config | Configure settings | | /opa-help | Show help |

Policy Language (Rego)

Policies are written in OPA's Rego language:

package pi.authz

# Default deny
default allow := false

# Allow trusted agents to read non-sensitive resources
allow if {
    input.agent.trust_level == "high"
    input.action.category == "read"
    input.resource.classification != "secret"
}

# Deny destructive actions after hours
deny contains violation if {
    input.action.category == "delete"
    not is_business_hours
    violation := {
        "policy": "business_hours",
        "rule": "no_destructive_after_hours",
        "message": "Destructive actions not allowed outside 9-5"
    }
}

is_business_hours if {
    time.now_ns >= time.parse_rfc3339_ns("2026-01-01T09:00:00Z")
    time.now_ns <= time.parse_rfc3339_ns("2026-01-01T17:00:00Z")
}

Multi-Dimensional Access Control

OPA can evaluate multiple factors:

• WHO - Agent identity, roles, trust level
• WHAT - Action type, sensitivity
• WHERE - Network zone, IP address, VPN status
• WHEN - Time of day, business hours
• WHY - Purpose, ticket ID, approval chain

A2A Integration

pi-opa integrates with pi-a2a-communication for agent-to-agent authorization:

# Enable A2A authorization
/opa-config integration.a2aEnabled true
/opa-config integration.requireOPAForA2A true

# Now all A2A requests go through OPA
/a2a-send some-agent "do something"
# → OPA evaluates authorization first

Tools

opa_evaluate

Evaluate authorization programmatically:

{
  "tool": "opa_evaluate",
  "params": {
    "agent": "ci-bot",
    "action": "deploy",
    "resource": "production",
    "context": {
      "time": "14:00",
      "emergency": false
    }
  }
}

opa_check_policy

Validate policy syntax:

{
  "tool": "opa_check_policy",
  "params": {
    "policy_file": "./my_policy.rego"
  }
}

Configuration

Default configuration location: ~/.pi/agent/opa/config.json

{
  "opa": {
    "binaryPath": "opa",
    "serverPort": 8181,
    "serverHost": "localhost",
    "autoStart": true,
    "logLevel": "info"
  },
  "policies": {
    "directory": "~/.pi/agent/opa/policies",
    "defaultPackage": "pi.authz",
    "autoReload": true,
    "testOnLoad": true
  },
  "authorization": {
    "defaultDecision": "deny",
    "cacheDecisions": true,
    "cacheTTL": 300000,
    "requireAuthentication": true
  },
  "audit": {
    "enabled": true,
    "logDirectory": "~/.pi/agent/opa/audit",
    "retentionDays": 90,
    "logSuccessful": true,
    "logFailed": true
  }
}

Enterprise Features

Audit Logging

All authorization decisions are logged with:

• Timestamp
• Agent identity
• Action and resource
• Decision (allow/deny)
• Policy violations
• Duration
• Context

Export to JSON or CSV for compliance reporting.

Policy Testing

Write tests for your policies:

package pi.authz_test

import data.pi.authz

test_allow_trusted_read if {
    authz.allow with input as {
        "agent": {"trust_level": "high"},
        "action": {"category": "read"},
        "resource": {"classification": "internal"}
    }
}

Decision Caching

Frequently evaluated decisions are cached for performance (configurable TTL).

Hot Reload

Update policies without restarting - changes take effect immediately.

Examples

Example 1: Time-Based Access

# No destructive operations after 6 PM
deny contains violation if {
    input.action.category == "delete"
    time.now_ns > time.parse_rfc3339_ns("${TODAY}T18:00:00Z")
    violation := {
        "policy": "time_based",
        "message": "Destructive ops only allowed 9-6"
    }
}

Example 2: Need-to-Know

# Customer data only for assigned agents
allow if {
    input.resource.type == "customer_data"
    input.agent.id == input.resource.assigned_agent
}

Example 3: Emergency Override

# Emergency break-glass
allow if {
    input.context.emergency == true
    input.context.incident_id != ""
    input.agent.on_call == true
}

Integration with OPA Ecosystem

pi-opa works with:

• OPA CLI - Local policy testing
• OPA Server - Production deployment
• OPA Bundles - Distributed policy updates
• OPA Discovery - Dynamic configuration
• Styra DAS - Managed OPA service

Documentation

• OPA Documentation
• Rego Language Reference
• OPA Policy Testing

License

MIT License - See LICENSE

Contributing

Contributions welcome! Please ensure:

1. Code follows TypeScript best practices
2. All new features include tests
3. Documentation is updated
4. Changes are backward compatible

Support

• GitHub Issues: https://github.com/DrOlu/pi-opa/issues
• pi Discord: Link on pi.dev

Secure your multi-agent workflows with pi-opa! 🔒