@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/metrics-schema.json

@@ -0,0 +1,504 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OAP Metrics Schema",
+  "description": "Observability and monitoring data schema for Open Agent Passport API",
+  "type": "object",
+  "required": ["timestamp", "service", "metrics"],
+  "properties": {
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when metrics were collected"
+    },
+    "service": {
+      "type": "string",
+      "description": "Service name generating the metrics",
+      "enum": ["aport-api", "aport-verify", "aport-policy", "aport-webhook"]
+    },
+    "version": {
+      "type": "string",
+      "description": "Service version",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["development", "staging", "production"],
+      "description": "Deployment environment"
+    },
+    "region": {
+      "type": "string",
+      "description": "Deployment region",
+      "enum": ["us", "eu", "ca", "ap", "global"]
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["counters", "gauges", "histograms"],
+      "properties": {
+        "counters": {
+          "type": "object",
+          "description": "Monotonically increasing counters",
+          "properties": {
+            "requests_total": {
+              "type": "object",
+              "description": "Total number of requests",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "method": {
+                      "type": "string",
+                      "enum": [
+                        "GET",
+                        "POST",
+                        "PUT",
+                        "DELETE",
+                        "PATCH",
+                        "OPTIONS"
+                      ]
+                    },
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "status_code": {
+                      "type": "integer",
+                      "minimum": 100,
+                      "maximum": 599
+                    },
+                    "region": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            },
+            "passports_created": {
+              "type": "object",
+              "description": "Total number of passports created",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "owner_type": {
+                      "type": "string",
+                      "enum": ["org", "user"]
+                    },
+                    "assurance_level": {
+                      "type": "string",
+                      "enum": ["L0", "L1", "L2", "L3", "L4KYC", "L4FIN"]
+                    }
+                  }
+                }
+              }
+            },
+            "decisions_created": {
+              "type": "object",
+              "description": "Total number of policy decisions created",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "policy_id": {
+                      "type": "string"
+                    },
+                    "decision": {
+                      "type": "string",
+                      "enum": ["allow", "deny"]
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            },
+            "errors_total": {
+              "type": "object",
+              "description": "Total number of errors",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "error_code": {
+                      "type": "string"
+                    },
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "severity": {
+                      "type": "string",
+                      "enum": ["low", "medium", "high", "critical"]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "gauges": {
+          "type": "object",
+          "description": "Current values that can go up or down",
+          "properties": {
+            "active_passports": {
+              "type": "object",
+              "description": "Number of currently active passports",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": ["active", "suspended", "revoked"]
+                    },
+                    "region": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            },
+            "active_connections": {
+              "type": "object",
+              "description": "Number of active connections",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "connection_type": {
+                      "type": "string",
+                      "enum": ["http", "websocket", "grpc"]
+                    }
+                  }
+                }
+              }
+            },
+            "memory_usage_bytes": {
+              "type": "object",
+              "description": "Current memory usage in bytes",
+              "properties": {
+                "value": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "cpu_usage_percent": {
+              "type": "object",
+              "description": "Current CPU usage percentage",
+              "properties": {
+                "value": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 100
+                }
+              }
+            }
+          }
+        },
+        "histograms": {
+          "type": "object",
+          "description": "Distribution of values over time",
+          "properties": {
+            "request_duration_seconds": {
+              "type": "object",
+              "description": "Request duration distribution",
+              "properties": {
+                "count": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "sum": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "buckets": {
+                  "type": "object",
+                  "description": "Histogram buckets",
+                  "properties": {
+                    "0.005": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "0.01": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "0.025": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "0.05": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "0.1": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "0.25": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "0.5": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "1": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "2.5": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "5": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "10": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "+Inf": {
+                      "type": "integer",
+                      "minimum": 0
+                    }
+                  }
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "method": {
+                      "type": "string"
+                    },
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "status_code": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            },
+            "policy_evaluation_duration_seconds": {
+              "type": "object",
+              "description": "Policy evaluation duration distribution",
+              "properties": {
+                "count": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "sum": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "buckets": {
+                  "type": "object",
+                  "description": "Histogram buckets for policy evaluation"
+                },
+                "labels": {
+                  "type": "object",
+                  "properties": {
+                    "policy_id": {
+                      "type": "string"
+                    },
+                    "decision": {
+                      "type": "string",
+                      "enum": ["allow", "deny"]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "traces": {
+      "type": "array",
+      "description": "Distributed tracing data",
+      "items": {
+        "type": "object",
+        "properties": {
+          "trace_id": {
+            "type": "string",
+            "description": "Unique trace identifier"
+          },
+          "span_id": {
+            "type": "string",
+            "description": "Unique span identifier"
+          },
+          "parent_span_id": {
+            "type": "string",
+            "description": "Parent span identifier"
+          },
+          "operation_name": {
+            "type": "string",
+            "description": "Operation name"
+          },
+          "start_time": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Span start time"
+          },
+          "duration": {
+            "type": "number",
+            "description": "Span duration in seconds"
+          },
+          "tags": {
+            "type": "object",
+            "description": "Span tags",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "logs": {
+            "type": "array",
+            "description": "Span logs",
+            "items": {
+              "type": "object",
+              "properties": {
+                "timestamp": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "fields": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "events": {
+      "type": "array",
+      "description": "Application events",
+      "items": {
+        "type": "object",
+        "properties": {
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "passport_created",
+              "passport_updated",
+              "passport_suspended",
+              "passport_revoked",
+              "decision_created",
+              "decision_updated",
+              "policy_evaluated",
+              "error_occurred",
+              "rate_limit_exceeded"
+            ]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "data": {
+            "type": "object",
+            "description": "Event-specific data",
+            "additionalProperties": true
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["debug", "info", "warn", "error", "fatal"]
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "timestamp": "2025-01-16T10:30:00Z",
+      "service": "aport-api",
+      "version": "1.0.0",
+      "environment": "production",
+      "region": "us",
+      "metrics": {
+        "counters": {
+          "requests_total": {
+            "value": 1000000,
+            "labels": {
+              "method": "GET",
+              "endpoint": "/api/verify/{agent_id}",
+              "status_code": 200,
+              "region": "us"
+            }
+          },
+          "passports_created": {
+            "value": 5000,
+            "labels": {
+              "owner_type": "org",
+              "assurance_level": "L4KYC"
+            }
+          }
+        },
+        "gauges": {
+          "active_passports": {
+            "value": 2500,
+            "labels": {
+              "status": "active",
+              "region": "us"
+            }
+          },
+          "memory_usage_bytes": {
+            "value": 1073741824
+          }
+        },
+        "histograms": {
+          "request_duration_seconds": {
+            "count": 1000000,
+            "sum": 50000,
+            "buckets": {
+              "0.005": 100000,
+              "0.01": 200000,
+              "0.025": 300000,
+              "0.05": 400000,
+              "0.1": 500000,
+              "0.25": 600000,
+              "0.5": 700000,
+              "1": 800000,
+              "2.5": 900000,
+              "5": 950000,
+              "10": 990000,
+              "+Inf": 1000000
+            },
+            "labels": {
+              "method": "GET",
+              "endpoint": "/api/verify/{agent_id}",
+              "status_code": 200
+            }
+          }
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,54 @@
+# Change Log
+
+All notable changes to the Open Agent Passport (OAP) specification will be documented in this file.
+
+The format is based on [Keep a Change Log](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-16
+
+### Added
+
+- Initial release of Open Agent Passport (OAP) v1 specification
+- Core passport schema with template/instance support
+- Decision schema with Ed25519 signing and JCS canonicalization
+- Capability registry with three initial policy packs:
+  - `finance.payment.refund.v1` - Financial transaction controls
+  - `data.export.create.v1` - Data export with PII controls
+  - `code.release.publish.v1` - Repository release controls
+- Assurance level system (L0-L4) with verification methods
+- Security model with Ed25519 signatures and key resolution
+- Verifiable Credential interoperability mapping
+- Conformance testing framework
+- Comprehensive documentation and examples
+
+### Security
+
+- Ed25519 signature scheme for decision signing
+- JCS (RFC 8785) canonicalization for deterministic hashing
+- Key resolution via `/.well-known/oap/keys.json`
+- Suspend semantics with 30-second global invalidation
+- Passport digest verification for decision integrity
+
+### Interoperability
+
+- W3C Verifiable Credential export/import support
+- JSON-LD context definitions
+- Standardized error codes and response formats
+- Multi-region and multi-tenant support
+
+### Performance
+
+- Decision caching with TTL support
+- Tiered cache invalidation on suspend/revoke
+- Optimized for edge computing environments
+- Server-Timing headers for performance monitoring
+
+## [Unreleased]
+
+### Planned
+
+- Additional policy packs for common use cases
+- Enhanced assurance level verification methods
+- Improved conformance testing coverage
+- Performance optimizations for large-scale deployments

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

@@ -0,0 +1,40 @@
+# Open Agent Passport (OAP) Versioning
+
+## Current Version: v1.0.0
+
+The Open Agent Passport specification follows [Semantic Versioning](https://semver.org/) principles.
+
+## Version Format
+
+- **Major Version (X)**: Breaking changes to the specification
+- **Minor Version (Y)**: New features that are backward compatible
+- **Patch Version (Z)**: Bug fixes and clarifications
+
+## Version History
+
+### v1.0.0 (2025-01-16)
+
+- Initial release of OAP specification
+- Core passport and decision schemas
+- Ed25519 signing and JCS canonicalization
+- Three initial policy packs: finance.payment.refund.v1, data.export.create.v1, code.release.publish.v1
+- Verifiable Credential interoperability
+- Conformance testing framework
+
+## Specification URLs
+
+- **Current**: `https://github.com/aporthq/aport-spec/oap/1.0`
+- **Latest**: `https://github.com/aporthq/aport-spec/oap/latest`
+- **Schema Base**: `https://github.com/aporthq/aport-spec/oap/`
+
+## Backward Compatibility
+
+- **v1.x**: All minor and patch versions are backward compatible
+- **v2.0+**: Major version changes may introduce breaking changes
+- **Deprecation Policy**: Features marked for deprecation will be supported for at least 12 months
+
+## Implementation Notes
+
+- Implementations MUST support the current major version
+- Implementations SHOULD support the latest minor version
+- Implementations MAY support multiple major versions simultaneously