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/jwks.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/jwks.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: ≤ 100ms (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 spec/conformance (the conformance/ directory of aporthq/aport-spec):

• 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

Seven packs also ship fixtures under policies//tests/: deliverable.task.complete.v1, finance.payment.charge.v1, finance.payment.refund.v1, finance.transaction.execute.v1, governance.data.access.v1, legal.contract.review.v1, media.image.generate.v1.

Suite Status (2026-09-24)

The suite is Candidate entry criterion 3 (see VERSION.md) and does not pass it today, which is one of the reasons the specification is still a Working Draft:

• spec/conformance/cases/ holds cases for two packs under their pre-rename ids, payments.refunds.v1 and data.export.v1. The packs were renamed on 2025-10-08.
• node test-runner.js (simple mode) passed 5 of 5; it does not check pack ids against the registry.
• tsx src/runner.ts failed 5 of 5 with "Unknown policy pack".
• 20 of 22 registered packs have no cases in the suite.
• decision-schema.json cannot be satisfied as written (see the Status section of oap-spec.md), so any schema check of a decision fails until it is fixed.

Bringing the suite to green means renaming the case directories to the current pack ids, making test-runner.js check those ids so the two runners agree, and fixing the decision schema. Criterion 3 asks only that the suite run against the current registry and pass; cases for the remaining 20 packs are a Final criterion. Because the text is a Working Draft, none of this is constrained by a maturity rule.

Running Tests

# Install dependencies (from spec/conformance)
pnpm install

# Run all tests
pnpm test

# Run one currently present legacy case id (until the cases are renamed)
pnpm test --pack payments.refunds.v1

# Simple JavaScript runner
pnpm run test:simple

How a passing suite feeds a release (tag, publish, announce, deprecation window) is described under "How the Spec Is Released" in VERSION.md.

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

Certification is not available while OAP 1.0 is a Working Draft. Implementations may run the tests for editor feedback and interoperability development, but they must not claim OAP conformance until the specification reaches Candidate or Final status.

Self-Certification (Candidate or Final Only)

Once the text is Candidate or Final, 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 after Candidate or Final status, 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
• Passport Schema
• Decision Schema
• Security Guidelines
• Capability Registry