# 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/<pack>/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](./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](./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

```bash

# 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](./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](./oap-spec.md)
- [Passport Schema](./passport-schema.json)
- [Decision Schema](./decision-schema.json)
- [Security Guidelines](./security.md)
- [Capability Registry](./capability-registry.md)