sentryagent-idp/openspec/changes/phase-6-market-expansion/specs/agntcy-compliance/spec.md

ADDED Requirements

Requirement: System generates an on-demand AGNTCY compliance report

The system SHALL expose GET /api/compliance/report returning a structured JSON compliance report covering: agent identity verification, audit trail integrity, credential rotation status, and federation readiness. The report SHALL be generated on-demand and cached in Redis for 5 minutes (compliance:report:<tenant_id>).

The report SHALL include:

• generated_at: ISO 8601 timestamp
• tenant_id: tenant identifier
• agntcy_schema_version: pinned version string (e.g., "1.0")
• sections: array of compliance sections, each with name, status (pass/fail/warn), and details
• overall_status: pass if all sections pass, fail if any section fails, warn if any section warns

Scenario: Successful compliance report generation

• WHEN an authenticated tenant admin calls GET /api/compliance/report
• THEN the response SHALL be HTTP 200 with a JSON compliance report containing all required sections

Scenario: Compliance report is served from cache within TTL

• WHEN GET /api/compliance/report is called twice within 5 minutes
• THEN the second response SHALL be served from Redis cache (not recomputed) and include a X-Cache: HIT header

Scenario: Compliance report requires authentication

• WHEN GET /api/compliance/report is called without a valid JWT
• THEN the response SHALL be HTTP 401

Requirement: Compliance report covers agent identity verification

The compliance report SHALL include an agent-identity section validating that all active agents have: a valid DID:WEB identifier, a current credential (not expired), and an AGNTCY agent card on record. The section SHALL report pass only if all agents satisfy all three checks.

Scenario: All agents compliant — agent identity section passes

• WHEN all active agents have valid DIDs, non-expired credentials, and agent cards
• THEN the agent-identity section SHALL have status: "pass"

Scenario: Agent with expired credential — section warns

• WHEN one or more active agents have credentials expiring within 7 days
• THEN the agent-identity section SHALL have status: "warn" with details listing affected agents

Scenario: Agent missing DID — section fails

• WHEN one or more active agents have no DID:WEB identifier
• THEN the agent-identity section SHALL have status: "fail" with details listing affected agents

Requirement: Compliance report covers audit trail integrity

The compliance report SHALL include an audit-trail section verifying the Merkle chain integrity of the audit_events table for the tenant. The section SHALL report pass if the chain is unbroken, fail if any hash mismatch is detected.

Scenario: Intact audit chain passes

• WHEN the Merkle chain for all audit events is valid
• THEN the audit-trail section SHALL have status: "pass" with the total event count

Scenario: Broken audit chain fails

• WHEN a hash mismatch is detected in the audit event chain
• THEN the audit-trail section SHALL have status: "fail" with the sequence number of the first invalid event

Requirement: System exports AGNTCY-standard agent cards

The system SHALL expose GET /api/compliance/agent-cards returning an array of all active agents as AGNTCY agent card objects in the standard JSON format. Each agent card SHALL include: id (DID:WEB), name, capabilities (from agent metadata), endpoint, created_at, and agntcy_schema_version.

Scenario: Successful agent card export

• WHEN an authenticated tenant admin calls GET /api/compliance/agent-cards
• THEN the response SHALL be HTTP 200 with a JSON array of agent card objects for all active agents

Scenario: Agent card export respects tenant isolation

• WHEN tenant A exports agent cards
• THEN the response SHALL contain ONLY agents belonging to tenant A

Scenario: Empty tenant returns empty array

• WHEN the tenant has no active agents
• THEN the response SHALL be HTTP 200 with an empty array

Requirement: AGNTCY interoperability test suite validates protocol conformance

The system SHALL include an interoperability test suite at tests/agntcy-conformance/ that validates the platform's conformance to the AGNTCY agent identity protocol. The suite SHALL test: agent registration (DID:WEB creation), token issuance for agent clients, A2A delegation chain creation and verification, and compliance report generation. All tests SHALL pass in CI.

Scenario: Conformance suite passes in CI environment

• WHEN npm run test:agntcy-conformance is executed in a CI environment with a live test database
• THEN all conformance tests SHALL pass with exit code 0

Scenario: Conformance suite fails on missing DID endpoint

• WHEN the DID resolution endpoint is unreachable
• THEN the conformance test for DID:WEB SHALL fail with a descriptive error message

Requirement: Compliance features can be toggled via feature flag

The system SHALL respect a COMPLIANCE_ENABLED environment variable (default: true). When COMPLIANCE_ENABLED=false, all /api/compliance/* endpoints SHALL return HTTP 404.

Scenario: Compliance disabled returns 404

• WHEN COMPLIANCE_ENABLED=false and GET /api/compliance/report is called
• THEN the response SHALL be HTTP 404