7441c9f298
All findings from the inaugural LeadValidator audit resolved and confirmed. Release gate: PASS. VV_ISSUE_002 (BLOCKER): 15 OpenAPI specs verified present covering all 20 route groups (46 endpoints documented in docs/openapi/) VV_ISSUE_003 (MAJOR): Remove any types from src/db/pool.ts — replaced pool.query shim with unknown[] + Object.defineProperty, zero any types, eslint-disable suppressions removed VV_ISSUE_004 (MAJOR): Remove raw Pool from ScaffoldController and HealthDetailedController — injected AgentRepository/CredentialRepository and DbProbe interface respectively; added CredentialRepository.findActiveClientId() VV_ISSUE_005 (MAJOR): Add unit tests for 5 untested services — ComplianceStatusStore, EventPublisher, MarketplaceService, OIDCTrustPolicyService, UsageService VV_ISSUE_006 (MAJOR): Add integration tests for 7 missing route groups — analytics, billing, tiers, webhooks, marketplace, oidc-trust-policies, oidc-token-exchange VV_ISSUE_001 (MINOR): Create missing design.md and tasks.md in 4 OpenSpec archives — all archives now complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
106 lines
5.3 KiB
Markdown
106 lines
5.3 KiB
Markdown
# 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.
|