@aporthq/aport-agent-guardrails 1.0.8

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

@@ -0,0 +1,396 @@
+{
+  "$id": "https://github.com/aporthq/aport-spec/oap/passport-schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Open Agent Passport",
+  "description": "Schema for Open Agent Passport (OAP) v1.0 passport objects",
+  "type": "object",
+  "required": [
+    "passport_id",
+    "kind",
+    "spec_version",
+    "owner_id",
+    "owner_type",
+    "status",
+    "assurance_level",
+    "capabilities",
+    "limits",
+    "regions",
+    "created_at",
+    "updated_at",
+    "version"
+  ],
+  "properties": {
+    "passport_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the passport (UUID v4)",
+      "example": "550e8400-e29b-41d4-a716-446655440000"
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["template", "instance"],
+      "description": "Type of passport - template (canonical identity) or instance (tenant-specific)",
+      "example": "template"
+    },
+    "spec_version": {
+      "type": "string",
+      "const": "oap/1.0",
+      "description": "OAP specification version",
+      "example": "oap/1.0"
+    },
+    "template_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Template passport ID (required for instances)",
+      "example": "550e8400-e29b-41d4-a716-446655440001"
+    },
+    "owner_id": {
+      "type": "string",
+      "description": "Unique identifier for the owner (organization or user)",
+      "example": "org_12345678"
+    },
+    "owner_type": {
+      "type": "string",
+      "enum": ["org", "user"],
+      "description": "Type of owner (organization or user)",
+      "example": "org"
+    },
+    "assurance_level": {
+      "type": "string",
+      "enum": ["L0", "L1", "L2", "L3", "L4KYC", "L4FIN"],
+      "description": "Assurance level of the passport owner",
+      "example": "L2"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "suspended", "revoked"],
+      "description": "Current status of the passport",
+      "example": "active"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(\\.[a-z0-9]+)*$",
+            "description": "Capability identifier",
+            "example": "finance.payment.refund"
+          },
+          "params": {
+            "type": "object",
+            "description": "Optional parameters for the capability",
+            "additionalProperties": true,
+            "example": {
+              "max_amount": 5000,
+              "currency": "USD"
+            }
+          }
+        }
+      },
+      "description": "List of capabilities granted to the agent",
+      "example": [
+        {
+          "id": "finance.payment.refund",
+          "params": {
+            "max_amount": 5000,
+            "currency": "USD"
+          }
+        },
+        {
+          "id": "data.export"
+        }
+      ]
+    },
+    "limits": {
+      "type": "object",
+      "description": "Operational limits for the agent",
+      "properties": {
+        "finance.payment.refund": {
+          "type": "object",
+          "properties": {
+            "currency_limits": {
+              "type": "object",
+              "patternProperties": {
+                "^[A-Z]{3}$": {
+                  "type": "object",
+                  "properties": {
+                    "max_per_tx": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "description": "Maximum amount per transaction in minor units"
+                    },
+                    "daily_cap": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "description": "Maximum daily total in minor units"
+                    }
+                  }
+                }
+              }
+            },
+            "reason_codes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Allowed reason codes for refunds"
+            },
+            "idempotency_required": {
+              "type": "boolean",
+              "description": "Whether idempotency keys are required"
+            }
+          }
+        },
+        "data.export": {
+          "type": "object",
+          "properties": {
+            "max_rows": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum number of rows per export"
+            },
+            "allow_pii": {
+              "type": "boolean",
+              "description": "Whether PII can be included in exports"
+            },
+            "allowed_collections": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Allowed data collections for export"
+            }
+          }
+        },
+        "messaging.send": {
+          "type": "object",
+          "properties": {
+            "msgs_per_min": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum messages per minute"
+            },
+            "msgs_per_day": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum messages per day"
+            },
+            "allowed_recipients": {
+              "oneOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Simple list of allowed recipient IDs"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["id"],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "description": "Recipient identifier (username, email, account ID, etc.)"
+                      },
+                      "limits": {
+                        "type": "object",
+                        "properties": {
+                          "currency": {
+                            "type": "string",
+                            "pattern": "^[A-Z]{3}$",
+                            "description": "ISO 4217 currency code"
+                          },
+                          "max_amount": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "description": "Maximum amount per transaction in minor units"
+                          },
+                          "daily_cap": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "description": "Daily spending cap in minor units"
+                          }
+                        }
+                      }
+                    }
+                  },
+                  "description": "List of recipients with per-recipient limits"
+                }
+              ]
+            },
+            "approval_required": {
+              "type": "boolean",
+              "description": "Whether messages require manual approval before sending"
+            }
+          }
+        },
+        "payments.payout": {
+          "type": "object",
+          "properties": {
+            "supported_currencies": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Z]{3}$"
+              },
+              "description": "Supported currencies for payouts"
+            },
+            "currency_limits": {
+              "type": "object",
+              "patternProperties": {
+                "^[A-Z]{3}$": {
+                  "type": "object",
+                  "properties": {
+                    "max_per_tx": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "description": "Maximum amount per transaction in minor units"
+                    },
+                    "max_daily_amount": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "description": "Maximum daily total in minor units"
+                    }
+                  }
+                }
+              }
+            },
+            "allowed_destination_types": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Allowed destination account types"
+            },
+            "allowed_recipients": {
+              "oneOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Simple list of allowed recipient IDs"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["id"],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "description": "Recipient identifier"
+                      },
+                      "limits": {
+                        "type": "object",
+                        "properties": {
+                          "currency": {
+                            "type": "string",
+                            "pattern": "^[A-Z]{3}$"
+                          },
+                          "max_amount": {
+                            "type": "integer",
+                            "minimum": 0
+                          },
+                          "daily_cap": {
+                            "type": "integer",
+                            "minimum": 0
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            },
+            "approval_required": {
+              "type": "boolean",
+              "description": "Whether payouts require manual approval"
+            },
+            "max_payouts_per_day": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum number of payouts per day"
+            },
+            "compliance_checks_required": {
+              "type": "boolean",
+              "description": "Whether compliance checks are required"
+            }
+          }
+        },
+        "repo.release.publish": {
+          "type": "object",
+          "properties": {
+            "allowed_branches": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Allowed branches for releases"
+            },
+            "max_releases_per_day": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum releases per day"
+            },
+            "require_signed_artifacts": {
+              "type": "boolean",
+              "description": "Whether artifacts must be signed"
+            }
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "regions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Z]{2}(-[A-Z]{2})?$"
+      },
+      "description": "Geographic regions where the agent is authorized to operate",
+      "example": ["US", "EU", "CA"]
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional metadata for the passport",
+      "additionalProperties": true
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of creation",
+      "example": "2024-01-01T00:00:00Z"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update",
+      "example": "2024-01-15T10:30:00Z"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Version of the passport schema",
+      "example": "1.0.0"
+    },
+    "spec_version": {
+      "type": "string",
+      "const": "oap/1.0",
+      "description": "OAP specification version",
+      "example": "oap/1.0"
+    },
+    "parent_agent_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Parent template passport ID (required for instances)",
+      "example": "550e8400-e29b-41d4-a716-446655440001"
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,213 @@
+# Open Agent Passport Security Model
+
+## Overview
+
+The Open Agent Passport (OAP) security model ensures the integrity, authenticity, and confidentiality of agent credentials and policy decisions through cryptographic verification and secure key management.
+
+## Cryptographic Primitives
+
+### Ed25519 Signatures
+
+All OAP objects use Ed25519 for digital signatures:
+
+- **Algorithm**: Edwards Curve Digital Signature Algorithm (EdDSA)
+- **Curve**: Curve25519
+- **Key Size**: 256 bits (32 bytes)
+- **Signature Size**: 512 bits (64 bytes)
+- **Performance**: Fast signing and verification, suitable for edge computing
+
+### SHA-256 Hashing
+
+Passport digests use SHA-256:
+
+- **Algorithm**: SHA-256
+- **Input**: JCS-canonicalized passport view
+- **Output**: 256-bit (32-byte) hash
+- **Format**: `sha256:<base64-encoded-hash>`
+
+### JCS Canonicalization
+
+All objects are canonicalized using RFC 8785 JCS before signing:
+
+- **Standard**: RFC 8785 JSON Canonicalization Scheme
+- **Purpose**: Deterministic JSON representation for consistent hashing
+- **Implementation**: Must follow RFC 8785 exactly
+
+## Key Management
+
+### Key Types
+
+#### Registry Keys
+
+Registry keys are used by the OAP registry to sign decisions:
+
+- **Format**: `oap:registry:<keyid>`
+- **Location**: `https://api.yourdomain/.well-known/oap/keys.json`
+- **Rotation**: Regular rotation schedule (e.g., quarterly)
+- **Backup**: Multiple keys for high availability
+
+#### Owner Keys
+
+Owner keys are used by passport owners for additional verification:
+
+- **Format**: `oap:owner:<domain>:<keyid>`
+- **Location**: `https://<domain>/.well-known/oap/keys.json`
+- **Optional**: Not required for basic OAP compliance
+- **Use Case**: Additional verification layers
+
+### Key Resolution
+
+Keys are resolved using the following process:
+
+1. **Parse kid**: Extract key type and identifier
+2. **Resolve URL**: Construct key resolution URL
+3. **Fetch key**: Retrieve public key from URL
+4. **Validate**: Verify key format and expiration
+5. **Cache**: Cache key for performance
+
+#### Key Resolution URLs
+
+```
+Registry keys: https://api.yourdomain/.well-known/oap/keys.json
+Owner keys:    https://<domain>/.well-known/oap/keys.json
+```
+
+#### Key Format
+
+```json
+
+{
+  "keys": [
+    {
+      "kid": "oap:registry:key-2025-01",
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "x": "base64url-encoded-public-key",
+      "use": "sig",
+      "alg": "EdDSA",
+      "exp": 1735689600
+    }
+  ]
+}
+```
+
+## Signature Verification
+
+### Decision Verification
+
+All decisions MUST be verified before acceptance:
+
+1. **Parse signature**: Extract Ed25519 signature from `signature` field
+2. **Resolve key**: Use `kid` to fetch public key
+3. **Canonicalize**: Apply JCS canonicalization to decision payload
+4. **Verify signature**: Use Ed25519 to verify signature
+5. **Check expiration**: Ensure `expires_at` is in the future
+6. **Validate digest**: Verify `passport_digest` matches evaluated passport
+
+### Passport Verification
+
+Passport integrity is verified through digests:
+
+1. **Canonicalize passport**: Apply JCS canonicalization
+2. **Compute digest**: SHA-256 of canonicalized passport
+3. **Compare**: Ensure computed digest matches `passport_digest`
+
+## Security Properties
+
+### Integrity
+
+- **Passport integrity**: SHA-256 digest ensures passport hasn't been tampered with
+- **Decision integrity**: Ed25519 signature ensures decision hasn't been modified
+- **Canonicalization**: JCS ensures consistent representation across implementations
+
+### Authenticity
+
+- **Decision authenticity**: Ed25519 signature proves decision came from registry
+- **Key authenticity**: HTTPS and certificate validation for key resolution
+- **Passport authenticity**: Registry signature on active passports
+
+### Non-repudiation
+
+- **Decision non-repudiation**: Ed25519 signature provides cryptographic proof
+- **Audit trail**: All decisions are logged with signatures
+- **Key rotation**: Old keys remain valid for historical verification
+
+## Threat Model
+
+### Threats Addressed
+
+1. **Passport tampering**: Prevented by SHA-256 digests
+2. **Decision forgery**: Prevented by Ed25519 signatures
+3. **Replay attacks**: Prevented by expiration times and idempotency keys
+4. **Key compromise**: Mitigated by key rotation and revocation
+5. **Man-in-the-middle**: Prevented by HTTPS and certificate validation
+
+### Threats Not Addressed
+
+1. **Key theft**: Physical security of private keys
+2. **Insider attacks**: Malicious registry operators
+3. **Side-channel attacks**: Implementation-specific vulnerabilities
+4. **Quantum attacks**: Future quantum computing threats
+
+## Security Best Practices
+
+### For Implementers
+
+1. **Use secure random**: Generate UUIDs and keys with cryptographically secure random
+2. **Validate inputs**: Strictly validate all input data
+3. **Check expiration**: Always verify decision expiration times
+4. **Cache securely**: Store decisions securely with proper access controls
+5. **Rotate keys**: Implement regular key rotation schedule
+6. **Monitor logs**: Monitor for suspicious activity and key usage
+
+### For Deployers
+
+1. **HTTPS only**: Use HTTPS for all key resolution and API calls
+2. **Certificate validation**: Validate TLS certificates properly
+3. **Key storage**: Store private keys securely (HSM recommended)
+4. **Access controls**: Implement proper access controls for key management
+5. **Monitoring**: Monitor key usage and decision patterns
+6. **Incident response**: Have procedures for key compromise
+
+## Suspend Semantics
+
+### Global Invalidation
+
+When a passport is suspended or revoked:
+
+1. **Immediate effect**: Status change takes effect immediately
+2. **Cache invalidation**: All caches MUST be purged within 30 seconds
+3. **Decision invalidation**: All cached decisions become invalid
+4. **Notification**: Relying parties SHOULD be notified via webhooks
+
+### Implementation Requirements
+
+- **Registry**: Must invalidate all cached decisions within 30 seconds
+- **Relying parties**: Must treat cached decisions as invalid after suspend
+- **Monitoring**: Must detect and alert on suspend/revoke events
+- **Recovery**: Must support passport reactivation with new decisions
+
+## Compliance
+
+### Security Standards
+
+OAP implementations should comply with:
+
+- **FIPS 140-2**: For cryptographic modules (if applicable)
+- **Common Criteria**: For high-assurance implementations
+- **SOC 2**: For service providers
+- **ISO 27001**: For information security management
+
+### Audit Requirements
+
+- **Key usage**: Log all key usage and signature operations
+- **Decision audit**: Log all policy decisions with full context
+- **Access audit**: Log all administrative access to keys and passports
+- **Retention**: Retain audit logs for required period (e.g., 7 years)
+
+## References
+
+- [RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)](https://tools.ietf.org/html/rfc8032)
+- [RFC 8785: JSON Canonicalization Scheme (JCS)](https://tools.ietf.org/html/rfc8785)
+- [NIST SP 800-57: Key Management Guidelines](https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final)
+- [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html)