@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/oap/capability-registry.md

@@ -0,0 +1,229 @@
+# Open Agent Passport Capability Registry
+
+## Overview
+
+The Open Agent Passport (OAP) Capability Registry defines standardized capabilities that can be granted to AI agents. Each capability includes:
+
+- **Context fields**: Required input data for policy evaluation
+- **Limits**: Configurable operational constraints
+- **Deny codes**: Standardized error codes for policy violations
+
+## Capability Naming Convention
+
+### Format
+
+Capabilities use a hierarchical namespace format: `category.action`
+
+Examples:
+- `finance.payment.refund` - Financial refund operations
+- `data.export` - Data export operations
+- `repo.release.publish` - Repository release operations
+
+## Policy Packs
+
+### Structure
+
+Policy packs define the complete policy logic for one or more capabilities. They include:
+
+- **Policy ID**: Unique identifier (e.g., `finance.payment.refund.v1`)
+- **Required capabilities**: List of capabilities this pack handles
+- **Minimum assurance**: Required assurance level
+- **Context schema**: Expected input data structure
+- **Limit schema**: Configurable limits structure
+- **Deny codes**: Standardized error codes
+
+## Standard Policy Packs
+
+### finance.payment.refund.v1
+
+### finance.payment.refund.v1
+
+**Purpose**: Protects financial refund operations with amount limits, currency controls, and idempotency requirements.
+
+**Required Capability**: `finance.payment.refund`
+
+**Minimum Assurance**: L2 (GitHub Verified)
+
+**Context Fields**:
+- `amount` (integer): Refund amount in minor units
+- `currency` (string): ISO 4217 currency code
+- `order_id` (string): Original order identifier
+- `customer_id` (string): Customer identifier
+- `reason_code` (string): Refund reason code
+- `region` (string): Geographic region
+- `idempotency_key` (string): Idempotency key for duplicate prevention
+
+**Limits Structure**:
+```json
+{
+  "finance.payment.refund": {
+    "currency_limits": {
+      "USD": {
+        "max_per_tx": 5000,
+        "daily_cap": 50000
+      },
+      "EUR": {
+        "max_per_tx": 4500,
+        "daily_cap": 45000
+      }
+    },
+    "reason_codes": ["customer_request", "defective_product", "fraud"],
+    "regions": ["US", "CA", "EU"],
+    "idempotency_required": true
+  }
+}
+```
+
+**Deny Codes**:
+- `oap.limit_exceeded` - Transaction or daily limit exceeded
+- `oap.currency_unsupported` - Currency not supported
+- `oap.region_blocked` - Operation not allowed in this region
+- `oap.invalid_reason` - Invalid reason code
+- `oap.idempotency_conflict` - Idempotency key already used
+
+### data.export.create.v1
+
+**Purpose**: Protects data export operations with row limits, PII controls, and collection restrictions.
+
+**Required Capability**: `data.export`
+
+**Minimum Assurance**: L1 (Email Verified)
+
+**Context Fields**:
+- `collection` (string): Data collection name
+- `estimated_rows` (integer): Estimated number of rows
+- `include_pii` (boolean): Whether to include PII data
+- `region` (string): Geographic region
+
+**Limits Structure**:
+```json
+{
+  "data.export": {
+    "allowed_collections": ["users", "orders", "products"],
+    "max_rows": 100000,
+    "allow_pii": false,
+    "regions": ["US", "CA", "EU"]
+  }
+}
+```
+
+**Deny Codes**:
+- `oap.pii_blocked` - PII export not allowed
+- `oap.collection_forbidden` - Collection not in allowlist
+- `oap.limit_exceeded` - Row limit exceeded
+
+### repo.release.publish.v1
+
+**Purpose**: Protects repository release operations with branch controls, artifact verification, and rate limiting.
+
+**Required Capability**: `repo.release.publish`
+
+**Minimum Assurance**: L2 (GitHub Verified)
+
+**Context Fields**:
+- `repo` (string): Repository identifier
+- `branch` (string): Source branch
+- `tag` (string): Release tag
+- `artifact_sha` (string): Artifact SHA-256 hash
+- `signer` (string): Artifact signer identifier
+
+**Limits Structure**:
+```json
+{
+  "repo.release.publish": {
+    "allowed_branches": ["main", "develop"],
+    "allowed_repos": ["org/project1", "org/project2"],
+    "max_releases_per_day": 10,
+    "require_signed_artifacts": true
+  }
+}
+```
+
+**Deny Codes**:
+- `oap.branch_forbidden` - Branch not in allowlist
+- `oap.repo_forbidden` - Repository not in allowlist
+- `oap.unsigned_artifact` - Artifact signature required
+- `oap.limit_exceeded` - Daily release limit exceeded
+
+## Custom Capabilities
+
+### Definition Process
+
+Organizations can define custom capabilities by:
+
+1. **Choosing a namespace**: Use your organization domain (e.g., `acme.inventory.update`)
+2. **Defining context fields**: Specify required input data
+3. **Defining limits**: Specify configurable constraints
+4. **Defining deny codes**: Specify error conditions
+5. **Creating policy pack**: Implement the policy logic
+
+### Example Custom Capability
+
+```json
+{
+  "acme.inventory.update": {
+    "context_fields": {
+      "product_id": "string",
+      "quantity_change": "integer",
+      "warehouse_id": "string",
+      "reason": "string"
+    },
+    "limits": {
+      "max_quantity_change": 1000,
+      "allowed_warehouses": ["warehouse_1", "warehouse_2"],
+      "require_approval": true
+    },
+    "deny_codes": [
+      "acme.quantity_exceeded",
+      "acme.warehouse_forbidden",
+      "acme.approval_required"
+    ]
+  }
+}
+```
+
+## Capability Lifecycle
+
+### Registration
+
+### Registration
+
+1. **Define capability**: Specify context fields, limits, and deny codes
+2. **Create policy pack**: Implement policy evaluation logic
+3. **Submit for review**: Submit to OAP registry for standardization
+4. **Publish**: Once approved, capability is published in the registry
+
+### Deprecation
+
+1. **Announce deprecation**: 12-month notice period
+2. **Mark deprecated**: Update registry with deprecation notice
+3. **Remove support**: After notice period, remove from registry
+
+## Registry Access
+
+### Endpoints
+
+The capability registry is available at:
+- **Current version**: `https://github.com/aporthq/aport-spec/oap/capabilities.json`
+- **Latest version**: `https://github.com/aporthq/aport-spec/oap/capabilities/latest.json`
+- **Specific version**: `https://github.com/aporthq/aport-spec/oap/capabilities/v1.0.json`
+
+## Contributing
+
+### Process
+
+To contribute new capabilities:
+
+1. **Fork the specification repository**
+2. **Create capability definition** following the standard format
+3. **Implement policy pack** with test cases
+4. **Submit pull request** with capability and policy pack
+5. **Address feedback** and iterate until approved
+6. **Merge and publish** once approved
+
+## References
+
+- [OAP Specification](./oap-spec.md)
+- [Passport Schema](./passport-schema.json)
+- [Decision Schema](./decision-schema.json)
+- [Security Guidelines](./security.md)

package/external/aport-spec/oap/conformance.md

@@ -0,0 +1,257 @@
+# Open Agent Passport Conformance
+
+## Overview
+
+This document defines the conformance requirements for Open Agent Passport (OAP) implementations. Conformance ensures interoperability and security across different implementations.
+
+## Conformance Levels
+
+### Basic Conformance
+
+Basic conformance requires:
+
+1. **Schema validation**: Validate passports against `passport-schema.json`
+2. **Decision generation**: Generate decisions matching `decision-schema.json`
+3. **Signature verification**: Verify Ed25519 signatures on decisions
+4. **Error handling**: Return standardized error codes
+
+### Full Conformance
+
+Full conformance requires all basic conformance requirements plus:
+
+1. **Policy evaluation**: Implement policy pack evaluation logic
+2. **JCS canonicalization**: Use RFC 8785 for canonicalization
+3. **Key resolution**: Resolve keys via `/.well-known/oap/keys.json`
+4. **Suspend semantics**: Implement 30-second global invalidation
+5. **Performance**: Meet performance requirements (see below)
+
+## Implementation Requirements
+
+### Passport Validation
+
+Implementations MUST:
+
+1. **Validate schema**: Ensure passport matches `passport-schema.json`
+2. **Check required fields**: Verify all required fields are present
+3. **Validate formats**: Check UUID, date-time, and enum formats
+4. **Verify assurance**: Ensure assurance level is valid
+5. **Check status**: Validate status transitions (draft → active → suspended/revoked)
+
+#### Status State Machine
+
+```
+draft → active → suspended → active
+  ↓       ↓         ↓
+revoked  revoked   revoked
+```
+
+### Decision Generation
+
+Implementations MUST:
+
+1. **Generate decision_id**: Create unique UUID v4 for each decision
+2. **Include all required fields**: Populate all required decision fields
+3. **Set expiration**: Set `expires_at` based on policy and context
+4. **Compute digest**: Calculate `passport_digest` using SHA-256(JCS(passport))
+5. **Sign decision**: Create Ed25519 signature over JCS-canonicalized decision
+6. **Set kid**: Include proper key identifier
+
+### Policy Evaluation
+
+Implementations MUST:
+
+1. **Load policy pack**: Retrieve policy pack by ID
+2. **Validate context**: Check context against policy requirements
+3. **Check capabilities**: Verify passport has required capabilities
+4. **Validate limits**: Ensure operation within configured limits
+5. **Check assurance**: Verify assurance level meets minimum requirement
+6. **Check regions**: Validate operation is allowed in request region
+7. **Generate reasons**: Create appropriate reason codes and messages
+
+### Signature Verification
+
+Implementations MUST:
+
+1. **Parse signature**: Extract Ed25519 signature from decision
+2. **Resolve key**: Fetch public key using `kid` and `/.well-known/oap/keys.json`
+3. **Canonicalize**: Apply JCS canonicalization to decision payload
+4. **Verify signature**: Use Ed25519 to verify signature
+5. **Check expiration**: Ensure decision hasn't expired
+6. **Validate digest**: Verify passport digest matches
+
+### Error Handling
+
+Implementations MUST:
+
+1. **Return standard codes**: Use normative error codes from specification
+2. **Include context**: Provide relevant context in error messages
+3. **Log errors**: Log all errors for debugging and monitoring
+4. **Handle gracefully**: Don't expose internal implementation details
+
+#### Standard Error Codes
+
+- `oap.invalid_context` - Context data is invalid
+- `oap.unknown_capability` - Capability not recognized
+- `oap.limit_exceeded` - Operation exceeds limits
+- `oap.currency_unsupported` - Currency not supported
+- `oap.region_blocked` - Operation not allowed in region
+- `oap.assurance_insufficient` - Assurance level too low
+- `oap.passport_suspended` - Passport is suspended/revoked
+- `oap.idempotency_conflict` - Idempotency key conflict
+- `oap.policy_error` - Policy evaluation error
+
+## Performance Requirements
+
+### Response Times
+
+Implementations SHOULD meet these performance targets:
+
+- **Passport verification**: ≤ 100ms (95th percentile)
+- **Policy evaluation**: ≤ 200ms (95th percentile)
+- **Decision generation**: ≤ 300ms (95th percentile)
+- **Signature verification**: ≤ 50ms (95th percentile)
+
+### Throughput
+
+Implementations SHOULD support:
+
+- **Decision rate**: ≥ 1000 decisions/second
+- **Concurrent requests**: ≥ 100 concurrent requests
+- **Cache hit rate**: ≥ 95% for passport lookups
+
+### Scalability
+
+Implementations SHOULD:
+
+1. **Horizontal scaling**: Support multiple instances
+2. **Load balancing**: Distribute load across instances
+3. **Caching**: Implement multi-level caching
+4. **Database optimization**: Use appropriate indexes and queries
+
+## Test Requirements
+
+### Conformance Tests
+
+Implementations MUST pass all conformance tests:
+
+1. **Schema validation tests**: Test valid and invalid passports
+2. **Decision generation tests**: Test decision creation and validation
+3. **Signature tests**: Test signature creation and verification
+4. **Policy tests**: Test policy pack evaluation
+5. **Error handling tests**: Test error conditions and responses
+6. **Performance tests**: Test response times and throughput
+
+### Test Vectors
+
+Test vectors are provided in the `/conformance` directory:
+
+- **Passport examples**: Valid and invalid passport samples
+- **Context data**: Policy evaluation context samples
+- **Expected decisions**: Expected decision outputs
+- **Signature tests**: Signature creation and verification tests
+
+### Running Tests
+
+```bash
+
+# Install dependencies
+npm install
+
+# Run all tests
+npm test
+
+# Run specific test suite
+npm test -- --suite finance.payment.refund.v1
+
+# Run performance tests
+npm test -- --suite performance
+```
+
+## Security Requirements
+
+### Cryptographic Security
+
+Implementations MUST:
+
+1. **Use Ed25519**: Use Ed25519 for all signatures
+2. **Secure random**: Use cryptographically secure random for UUIDs
+3. **Key management**: Implement secure key storage and rotation
+4. **HTTPS**: Use HTTPS for all network communication
+5. **Certificate validation**: Validate TLS certificates properly
+
+### Data Protection
+
+Implementations MUST:
+
+1. **Encrypt sensitive data**: Encrypt passports and decisions at rest
+2. **Access controls**: Implement proper access controls
+3. **Audit logging**: Log all security-relevant events
+4. **Data retention**: Implement appropriate data retention policies
+
+## Interoperability
+
+### Standard Compliance
+
+Implementations MUST:
+
+1. **Follow specifications**: Implement all normative requirements
+2. **Use standard formats**: Use standard JSON and UUID formats
+3. **Support standard capabilities**: Support all standard capabilities
+4. **Handle extensions**: Gracefully handle unknown fields and capabilities
+
+### Cross-Implementation Testing
+
+Implementations SHOULD:
+
+1. **Test with other implementations**: Verify interoperability
+2. **Share test results**: Publish conformance test results
+3. **Report issues**: Report interoperability issues
+4. **Contribute tests**: Contribute additional test cases
+
+## Certification
+
+### Self-Certification
+
+Implementations can self-certify by:
+
+1. **Running conformance tests**: Pass all required tests
+2. **Documenting compliance**: Document conformance to requirements
+3. **Publishing results**: Publish test results publicly
+4. **Maintaining compliance**: Keep implementation up to date
+
+### Third-Party Certification
+
+For higher assurance, implementations can seek third-party certification:
+
+1. **Security audit**: Independent security review
+2. **Performance testing**: Independent performance validation
+3. **Compliance review**: Independent conformance verification
+4. **Certification mark**: Use official OAP certification mark
+
+## Compliance Monitoring
+
+### Continuous Monitoring
+
+Implementations SHOULD:
+
+1. **Monitor performance**: Track response times and throughput
+2. **Monitor errors**: Track error rates and types
+3. **Monitor security**: Track security events and anomalies
+4. **Monitor compliance**: Track conformance to requirements
+
+### Reporting
+
+Implementations SHOULD:
+
+1. **Regular reports**: Publish regular compliance reports
+2. **Incident reporting**: Report security incidents promptly
+3. **Update notifications**: Notify users of updates and changes
+4. **Deprecation notices**: Provide advance notice of deprecations
+
+## References
+
+- [OAP Specification](./oap-spec.md)
+- [Passport Schema](./passport-schema.json)
+- [Decision Schema](./decision-schema.json)
+- [Security Guidelines](./security.md)
+- [Capability Registry](./capability-registry.md)

package/external/aport-spec/oap/decision-schema.json

@@ -0,0 +1,114 @@
+{
+  "$id": "https://github.com/aporthq/aport-spec/oap/decision-schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Open Agent Passport Decision",
+  "description": "Schema for Open Agent Passport (OAP) v1.0 decision objects",
+  "type": "object",
+  "required": [
+    "decision_id",
+    "passport_id",
+    "policy_id",
+    "owner_id",
+    "assurance_level",
+    "allow",
+    "reasons",
+    "issued_at",
+    "expires_at",
+    "passport_digest",
+    "signature",
+    "kid"
+  ],
+  "properties": {
+    "decision_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the decision (UUID v4)",
+      "example": "550e8400-e29b-41d4-a716-446655440000"
+    },
+    "policy_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(\\.[a-z0-9]+)*\\.v[0-9]+$",
+      "description": "Policy pack identifier",
+      "example": "finance.payment.refund.v1"
+    },
+    "agent_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Agent ID that was evaluated",
+      "example": "550e8400-e29b-41d4-a716-446655440001"
+    },
+    "owner_id": {
+      "type": "string",
+      "description": "Owner ID from the passport",
+      "example": "org_12345678"
+    },
+    "assurance_level": {
+      "type": "string",
+      "enum": ["L0", "L1", "L2", "L3", "L4KYC", "L4FIN"],
+      "description": "Assurance level from the passport",
+      "example": "L2"
+    },
+    "allow": {
+      "type": "boolean",
+      "description": "Whether the action is allowed",
+      "example": true
+    },
+    "reasons": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Error or success code",
+            "example": "oap.limit_exceeded"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable message",
+            "example": "Transaction amount exceeds daily limit"
+          }
+        }
+      },
+      "description": "Array of reasons for the decision",
+      "minItems": 1
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the decision was created",
+      "example": "2024-01-15T10:30:00Z"
+    },
+    "expires_in": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of seconds until the decision expires",
+      "example": 3600
+    },
+    "passport_digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 hash of JCS-canonicalized passport view",
+      "example": "sha256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^ed25519:[A-Za-z0-9+/=]+$",
+      "description": "Ed25519 signature over JCS-canonicalized decision payload",
+      "example": "ed25519:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef=="
+    },
+    "kid": {
+      "type": "string",
+      "pattern": "^oap:(registry|owner):[a-zA-Z0-9._-]+$",
+      "description": "Key identifier for signature verification",
+      "example": "oap:registry:key-2025-01"
+    },
+    "decision_token": {
+      "type": "string",
+      "description": "Optional compact JWT for sub-TTL caching",
+      "example": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
+    }
+  },
+  "additionalProperties": false
+}

package/external/aport-spec/oap/examples/context.refund.usd.50.json

@@ -0,0 +1,9 @@
+{
+  "amount": 5000,
+  "currency": "USD",
+  "order_id": "order_123456789",
+  "customer_id": "cust_987654321",
+  "reason_code": "customer_request",
+  "region": "US",
+  "idempotency_key": "refund_20240115_001"
+}

package/external/aport-spec/oap/examples/decision.allow.sample.json

@@ -0,0 +1,20 @@
+{
+  "decision_id": "550e8400-e29b-41d4-a716-446655440002",
+  "policy_id": "finance.payment.refund.v1",
+  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
+  "owner_id": "org_87654321",
+  "assurance_level": "L3",
+  "allow": true,
+  "reasons": [
+    {
+      "code": "oap.allowed",
+      "message": "Transaction within limits and policy requirements"
+    }
+  ],
+  "created_at": "2024-01-15T10:30:00Z",
+  "expires_in": 3600,
+  "passport_digest": "sha256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef",
+  "signature": "ed25519:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef==",
+  "kid": "oap:registry:key-2025-01",
+  "decision_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZWNpc2lvbl9pZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMiIsInBvbGljeV9pZCI6InBheW1lbnRzLnJlZnVuZC52MSIsInBhc3Nwb3J0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAxIiwib3duZXJfaWQiOiJvcmdfODc2NTQzMjEiLCJhbGxvd190cnVlIiwiaXNzdWVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJleHBpcmVzX2F0IjoiMjAyNC0wMS0xNVQxMTozMDowMFoifQ.signature"
+}

package/external/aport-spec/oap/examples/decision.deny.sample.json

@@ -0,0 +1,23 @@
+{
+  "decision_id": "550e8400-e29b-41d4-a716-446655440003",
+  "policy_id": "finance.payment.refund.v1",
+  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
+  "owner_id": "org_87654321",
+  "assurance_level": "L3",
+  "allow": false,
+  "reasons": [
+    {
+      "code": "oap.limit_exceeded",
+      "message": "Transaction amount exceeds daily limit"
+    },
+    {
+      "code": "oap.currency_unsupported",
+      "message": "Currency JPY not supported for this passport"
+    }
+  ],
+  "created_at": "2024-01-15T10:30:00Z",
+  "expires_in": 3600,
+  "passport_digest": "sha256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef",
+  "signature": "ed25519:efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdefabcd1234==",
+  "kid": "oap:registry:key-2025-01"
+}