@aporthq/aport-agent-guardrails 1.0.8

package/external/aport-spec/rate-limiting.md

@@ -0,0 +1,136 @@
+# Rate Limiting Specification
+
+## Overview
+
+The Open Agent Passport (OAP) API implements comprehensive rate limiting to ensure fair usage and system stability. This document defines the rate limiting rules, headers, and enforcement mechanisms.
+
+## Rate Limiting Headers
+
+### Standard Headers
+
+All API responses include the following rate limiting headers:
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1640995200
+X-RateLimit-Window: 3600
+```
+
+### Header Definitions
+
+- **X-RateLimit-Limit**: Maximum number of requests allowed in the current window
+- **X-RateLimit-Remaining**: Number of requests remaining in the current window
+- **X-RateLimit-Reset**: Unix timestamp when the current window resets
+- **X-RateLimit-Window**: Duration of the rate limit window in seconds
+
+## Rate Limits by Endpoint
+
+### Verification Endpoints
+
+| Endpoint | Limit | Window | Notes |
+|----------|-------|--------|-------|
+| `/api/verify/{agent_id}` | 1000 | 1 hour | Per agent ID |
+| `/api/verify/policy/{pack_id}` | 500 | 1 hour | Per policy pack |
+| `/api/verify/decisions/{agent_id}` | 100 | 1 hour | Per agent ID |
+
+### Passport Management
+
+| Endpoint | Limit | Window | Notes |
+|----------|-------|--------|-------|
+| `/api/passports` (POST) | 10 | 1 hour | Per owner |
+| `/api/passports/{agent_id}` (PUT) | 50 | 1 hour | Per agent ID |
+| `/api/passports/{agent_id}/status` (PUT) | 20 | 1 hour | Per agent ID |
+
+### Public Endpoints
+
+| Endpoint | Limit | Window | Notes |
+|----------|-------|--------|-------|
+| `/api/verify/attestation/{id}` | 2000 | 1 hour | Public endpoint |
+| `/api/policies/{policy_name}` | 1000 | 1 hour | Public policy lookup |
+
+## Rate Limiting Strategies
+
+### Tiered Limiting
+
+Rate limits are applied in tiers:
+
+1. **Global Rate Limit**: 10,000 requests per hour per IP
+2. **Endpoint Rate Limit**: Specific limits per endpoint
+3. **User Rate Limit**: Additional limits for authenticated users
+4. **Agent Rate Limit**: Limits specific to agent operations
+
+### Burst Allowance
+
+Short-term burst requests are allowed:
+
+- **Burst Factor**: 2x the normal rate limit
+- **Burst Window**: 1 minute
+- **Burst Reset**: 5 minutes
+
+## Error Responses
+
+### Rate Limit Exceeded
+
+When rate limits are exceeded, the API returns:
+
+```json
+{
+  "error": "rate_limit_exceeded",
+  "message": "Rate limit exceeded. Please try again later.",
+  "retry_after": 3600,
+  "rate_limit_info": {
+    "limit": 1000,
+    "remaining": 0,
+    "reset": 1640995200,
+    "window": 3600
+  }
+}
+```
+
+### HTTP Status Codes
+
+- **429 Too Many Requests**: Rate limit exceeded
+- **503 Service Unavailable**: System overload protection
+
+## Implementation Notes
+
+### Distributed Rate Limiting
+
+Rate limiting is implemented using:
+
+- **Redis**: For distributed rate limit counters
+- **Sliding Window**: For smooth rate limit enforcement
+- **Token Bucket**: For burst allowance
+
+### Monitoring
+
+Rate limiting metrics are tracked:
+
+- Requests per second by endpoint
+- Rate limit violations by IP/user
+- System load and performance impact
+
+## Best Practices
+
+### Client Implementation
+
+1. **Respect Headers**: Always check rate limit headers
+2. **Exponential Backoff**: Implement retry with backoff
+3. **Caching**: Cache responses to reduce API calls
+4. **Batching**: Combine multiple requests when possible
+
+### Error Handling
+
+1. **Retry Logic**: Implement intelligent retry mechanisms
+2. **Fallback**: Have fallback strategies for rate limit scenarios
+3. **Monitoring**: Track rate limit usage and violations
+
+## Compliance
+
+This rate limiting specification ensures:
+
+- **Fair Usage**: Prevents abuse while allowing legitimate use
+- **System Stability**: Protects against overload
+- **Scalability**: Supports high-volume operations
+- **Transparency**: Clear communication of limits and status

package/external/aport-spec/transport-profile.md

@@ -0,0 +1,325 @@
+# Transport Profile Specification
+
+## Overview
+
+The Transport Profile defines how AI agents identify themselves and communicate their Open Agent Passport (OAP) credentials across different transport mechanisms. This specification ensures consistent agent identification regardless of the underlying communication protocol.
+
+## Transport Mechanisms
+
+### HTTP/HTTPS
+
+The primary transport mechanism for web-based agent interactions.
+
+#### Headers
+
+Agents must include the following headers in HTTP requests:
+
+```
+X-Agent-Passport: ap_a2d10232c6534523812423eec8a1425c
+X-Agent-Signature: ed25519:abc123def456...
+X-Agent-Timestamp: 1640995200
+X-Agent-Nonce: nonce_123456789
+```
+
+#### Header Definitions
+
+- **X-Agent-Passport**: The agent's passport ID
+- **X-Agent-Signature**: Ed25519 signature of the request
+- **X-Agent-Timestamp**: Unix timestamp of the request
+- **X-Agent-Nonce**: Unique nonce for replay protection
+
+### WebSocket
+
+For real-time agent communications.
+
+#### Connection Handshake
+
+```json
+{
+  "type": "agent_handshake",
+  "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
+  "signature": "ed25519:abc123def456...",
+  "timestamp": 1640995200,
+  "nonce": "nonce_123456789",
+  "capabilities": ["finance.payment.refund", "data.export"]
+}
+```
+
+#### Message Format
+
+```json
+{
+  "type": "agent_message",
+  "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
+  "message_id": "msg_123456789",
+  "payload": {
+    // Message content
+  },
+  "signature": "ed25519:xyz789...",
+  "timestamp": 1640995200
+}
+```
+
+### gRPC
+
+For high-performance agent-to-agent communication.
+
+#### Service Definition
+
+```protobuf
+service AgentService {
+  rpc Identify(AgentIdentity) returns (AgentResponse);
+  rpc Execute(AgentRequest) returns (AgentResponse);
+  rpc Verify(VerificationRequest) returns (VerificationResponse);
+}
+
+message AgentIdentity {
+  string passport_id = 1;
+  string signature = 2;
+  int64 timestamp = 3;
+  string nonce = 4;
+  repeated string capabilities = 5;
+}
+```
+
+### Message Queues
+
+For asynchronous agent communication.
+
+#### Message Structure
+
+```json
+{
+  "headers": {
+    "x-agent-passport": "ap_a2d10232c6534523812423eec8a1425c",
+    "x-agent-signature": "ed25519:abc123def456...",
+    "x-agent-timestamp": "1640995200",
+    "x-agent-nonce": "nonce_123456789"
+  },
+  "body": {
+    // Message payload
+  }
+}
+```
+
+## Agent Identification
+
+### Passport ID Format
+
+Agent passport IDs follow this format:
+
+```
+ap_[a-zA-Z0-9]{8,16}
+```
+
+Examples:
+- `ap_a2d10232c6534523812423eec8a1425c`
+- `ap_abc123def456`
+- `ap_myagent001`
+
+### Signature Generation
+
+All agent communications must be signed using Ed25519:
+
+```javascript
+const crypto = require('crypto');
+
+function signRequest(passportId, privateKey, timestamp, nonce, payload) {
+  const message = `${passportId}:${timestamp}:${nonce}:${JSON.stringify(payload)}`;
+  const signature = crypto
+    .createSign('ed25519')
+    .update(message)
+    .sign(privateKey);
+  return `ed25519:${signature.toString('hex')}`;
+}
+```
+
+### Timestamp Validation
+
+Timestamps must be:
+
+- **Current**: Within 5 minutes of current time
+- **Monotonic**: Never decrease for the same agent
+- **Format**: Unix timestamp in seconds
+
+### Nonce Requirements
+
+Nonces must be:
+
+- **Unique**: Never reused for the same agent
+- **Random**: Cryptographically secure random generation
+- **Format**: `nonce_[a-zA-Z0-9]{16,32}`
+
+## Transport Security
+
+### TLS Requirements
+
+All agent communications must use TLS 1.3 or higher:
+
+- **Minimum Version**: TLS 1.3
+- **Cipher Suites**: Only approved cipher suites
+- **Certificate Validation**: Full certificate chain validation
+- **Perfect Forward Secrecy**: Required for all connections
+
+### Signature Verification
+
+Receiving systems must verify agent signatures:
+
+```javascript
+function verifySignature(passportId, signature, publicKey, timestamp, nonce, payload) {
+  const message = `${passportId}:${timestamp}:${nonce}:${JSON.stringify(payload)}`;
+  const sig = signature.replace('ed25519:', '');
+  
+  return crypto
+    .createVerify('ed25519')
+    .update(message)
+    .verify(publicKey, Buffer.from(sig, 'hex'));
+}
+```
+
+### Replay Protection
+
+Implement replay protection using:
+
+1. **Nonce Tracking**: Store used nonces for 24 hours
+2. **Timestamp Windows**: Reject requests outside time window
+3. **Sequence Numbers**: Optional sequence number validation
+
+## Agent Discovery
+
+### Service Discovery
+
+Agents can discover other agents through:
+
+#### DNS SRV Records
+
+```
+_agent._tcp.example.com. 300 IN SRV 10 5 443 agent1.example.com.
+_agent._tcp.example.com. 300 IN SRV 20 5 443 agent2.example.com.
+```
+
+#### mDNS/Bonjour
+
+```
+_agent._tcp.local. PTR agent1._agent._tcp.local.
+agent1._agent._tcp.local. SRV 0 0 443 agent1.local.
+agent1._agent._tcp.local. TXT "passport=ap_a2d10232c6534523812423eec8a1425c"
+```
+
+### Agent Registry
+
+Centralized agent discovery service:
+
+```json
+{
+  "agents": [
+    {
+      "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
+      "name": "Acme Support Bot",
+      "endpoint": "https://agent1.example.com",
+      "capabilities": ["finance.payment.refund", "data.export"],
+      "status": "active",
+      "last_seen": "2025-01-16T10:30:00Z"
+    }
+  ]
+}
+```
+
+## Error Handling
+
+### Transport Errors
+
+| Error Code | Description | Action |
+|------------|-------------|--------|
+| `TRANSPORT_ERROR` | Connection failed | Retry with backoff |
+| `SIGNATURE_INVALID` | Invalid signature | Reject request |
+| `TIMESTAMP_EXPIRED` | Timestamp too old | Reject request |
+| `NONCE_REUSED` | Nonce already used | Reject request |
+| `PASSPORT_INVALID` | Invalid passport ID | Reject request |
+
+### Error Response Format
+
+```json
+{
+  "error": {
+    "code": "SIGNATURE_INVALID",
+    "message": "Invalid agent signature",
+    "details": {
+      "passport_id": "ap_a2d10232c6534523812423eec8a1425c",
+      "expected": "ed25519:abc123...",
+      "received": "ed25519:xyz789..."
+    }
+  },
+  "timestamp": "2025-01-16T10:30:00Z"
+}
+```
+
+## Implementation Guidelines
+
+### Client Libraries
+
+Transport profile implementations should provide:
+
+1. **Automatic Signing**: Sign all outgoing requests
+2. **Signature Verification**: Verify incoming requests
+3. **Nonce Management**: Generate and track nonces
+4. **Error Handling**: Handle transport errors gracefully
+5. **Retry Logic**: Implement exponential backoff
+
+### Server Implementation
+
+Receiving systems should:
+
+1. **Validate Signatures**: Verify all agent signatures
+2. **Check Timestamps**: Validate timestamp freshness
+3. **Track Nonces**: Prevent replay attacks
+4. **Rate Limiting**: Implement per-agent rate limiting
+5. **Logging**: Log all agent interactions
+
+## Testing
+
+### Test Vectors
+
+Standard test vectors for signature verification:
+
+```json
+{
+  "passport_id": "ap_test123",
+  "timestamp": 1640995200,
+  "nonce": "nonce_test123",
+  "payload": {"action": "test"},
+  "private_key": "test_private_key",
+  "expected_signature": "ed25519:test_signature"
+}
+```
+
+### Conformance Testing
+
+Use the OAP conformance test suite to verify transport profile implementation:
+
+```bash
+npm run test:transport-profile
+```
+
+## Best Practices
+
+### Security
+
+1. **Key Management**: Store private keys securely
+2. **Key Rotation**: Implement regular key rotation
+3. **Audit Logging**: Log all agent communications
+4. **Monitoring**: Monitor for suspicious activity
+
+### Performance
+
+1. **Connection Pooling**: Reuse connections when possible
+2. **Async Processing**: Process requests asynchronously
+3. **Caching**: Cache passport data appropriately
+4. **Load Balancing**: Distribute agent load
+
+### Reliability
+
+1. **Circuit Breakers**: Implement circuit breaker patterns
+2. **Health Checks**: Regular health check endpoints
+3. **Graceful Degradation**: Handle partial failures
+4. **Monitoring**: Comprehensive monitoring and alerting