sentryagent-idp/openspec/vv_audit/VV_ISSUE_002.md

VV_ISSUE_002 — 15 route groups lack OpenAPI specifications

Status: RESOLVED Severity: BLOCKER Category: DOCS Logged by: LeadValidator Date: 2026-04-07 Audit phase: Phase B — API Surface Audit

Finding

The PRD (Section 6.3, Section 10.1) and README.md mandate: "Every API endpoint MUST have an OpenAPI 3.0 specification BEFORE implementation begins. No exceptions."

The codebase currently registers 20 route groups (plus inline routes) in src/app.ts. Only 5 OpenAPI specs exist in docs/openapi/. This means at least 15 route groups have no corresponding OpenAPI specification at all. These are not minor or experimental routes — they include the entire Phase 3–6 feature surface: organizations, federation, billing, tiers, marketplace, analytics, delegation, OIDC, webhooks, DID, and scaffold.

This is not a post-hoc documentation gap. The PRD requires the spec to exist before implementation. These features were shipped without specs, which means:

1. The API contract was never formally reviewed or approved
2. There is no authoritative reference for what these endpoints do
3. Integration with external consumers (SDKs, field trial runbook) relies on undocumented behavior

Evidence

OpenAPI specs that exist (docs/openapi/):

• agent-registry.yaml — covers /api/v1/agents
• audit-log.yaml — covers /api/v1/audit
• compliance.yaml — covers /api/v1/compliance
• credential-management.yaml — covers /api/v1/agents/:agentId/credentials
• oauth2-token.yaml — covers /api/v1/token

Route groups registered in src/app.ts with NO OpenAPI spec:

Route prefix	Router function	File
/health	createHealthRouter	src/routes/health.ts
/metrics	createMetricsRouter	src/routes/metrics.ts
/.well-known/did.json	inline didController.getInstanceDIDDocument	src/app.ts:329
/ (OIDC well-known)	createOIDCRouter	src/routes/oidc.ts
/api/v1 (DID)	createDIDRouter	src/routes/did.ts
/api/v1/organizations	createOrgsRouter	src/routes/organizations.ts
/api/v1 (federation)	createFederationRouter	src/routes/federation.ts
/api/v1/webhooks	createWebhooksRouter	src/routes/webhooks.ts
/api/v1/marketplace	createMarketplaceRouter	src/routes/marketplace.ts
/api/v1/billing	createBillingRouter	src/routes/billing.ts
/api/v1/tiers	createTiersRouter	src/routes/tiers.ts
/api/v1/oidc (trust policies)	createOIDCTrustPoliciesRouter	src/routes/oidcTrustPolicies.ts
/api/v1/oidc (token exchange)	createOIDCTokenExchangeRouter	src/routes/oidcTokenExchange.ts
/api/v1 (delegation)	createDelegationRouter	src/routes/delegation.ts
/api/v1/analytics	createAnalyticsRouter	src/routes/analytics.ts
/api/v1 (scaffold)	createScaffoldRouter	src/routes/scaffold.ts

Required Action

Create an OpenAPI 3.0 specification for every route group listed above. Each spec must cover:

• All endpoints (path, method)
• Request body schemas with validation rules
• Response schemas for all status codes (2xx, 4xx, 5xx)
• Authentication requirements (Bearer token, scopes)
• Example requests and responses

Recommended approach: create one YAML file per route group in docs/openapi/, matching the pattern of the existing 5 specs.

This is a BLOCKER. No production release is permitted while this finding is OPEN.

CTO Response

All 15 required OpenAPI 3.0 specification files have been created in docs/openapi/. Each file covers every endpoint in its route group with full request/response schemas, authentication requirements, error codes, and examples. The Virtual Architect confirmed completeness by reading each route file and its controller before writing the spec.

Resolution

Status updated to RESOLVED — 2026-04-07

All 15 OpenAPI 3.0 YAML files now exist in docs/openapi/:

Route group	Spec file	Endpoints
/health	health.yaml	2 (GET /health, GET /health/detailed)
/metrics	metrics.yaml	1 (GET /metrics)
/.well-known/did.json + DID routes	did.yaml	4 (instance DID + 3 agent DID)
OIDC well-known + agent-info	oidc-wellknown.yaml	3 (discovery, JWKS, agent-info)
/api/v1/organizations	organizations.yaml	6 (CRUD + members)
/api/v1/federation	federation.yaml	6 (partners CRUD + verify)
/api/v1/webhooks	webhooks.yaml	6 (subscriptions CRUD + deliveries)
/api/v1/marketplace	marketplace.yaml	2 (list + detail)
/api/v1/billing	billing.yaml	3 (checkout, webhook, usage)
/api/v1/tiers	tiers.yaml	2 (status + upgrade)
/api/v1/oidc/trust-policies	oidc-trust-policies.yaml	3 (create, list, delete)
/api/v1/oidc/token	oidc-token-exchange.yaml	1 (exchange)
/api/v1/oauth2/token/delegate	delegation.yaml	3 (create, verify, revoke)
/api/v1/analytics	analytics.yaml	3 (tokens, activity, agents)
/api/v1/sdk/scaffold	scaffold.yaml	1 (GET scaffold ZIP)

Every spec conforms to OpenAPI 3.0.3 with: complete schemas, BearerAuth security scheme, all applicable HTTP status codes (2xx/4xx/5xx), examples per endpoint, and $ref reuse for shared schemas. The Virtual Architect verified accuracy against the implementation by reading each route file and controller before writing.