fix(vv): resolve all 6 V&V issues — field trial unblocked

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>
2026-04-07 04:52:47 +00:00
parent d216096dfb
commit 7441c9f298
49 changed files with 8954 additions and 70 deletions
--- a/docs/openapi/metrics.yaml
+++ b/docs/openapi/metrics.yaml
@@ -0,0 +1,106 @@
+openapi: "3.0.3"
+
+info:
+  title: SentryAgent.ai — Prometheus Metrics Endpoint
+  version: 1.0.0
+  description: |
+    Internal Prometheus metrics endpoint for the SentryAgent.ai AgentIdP platform.
+
+    This endpoint returns metrics in **Prometheus text exposition format** (v0.0.4).
+    It is intended exclusively for internal Prometheus scraping.
+
+    **Security notice:** This endpoint is **unauthenticated** and MUST NOT be
+    exposed on a public-facing network interface. Restrict access via network
+    policy, firewall rules, or a reverse-proxy that only allows Prometheus
+    scraper IP ranges to reach `/metrics`.
+
+    Metrics exported include:
+    - HTTP request counts and latencies (by route and status code)
+    - Token issuance, introspection, and revocation counters
+    - Agent registration and decommission counters
+    - Active registered agent gauge
+    - Database connection pool metrics
+    - Process memory and CPU metrics (via `prom-client` defaults)
+
+servers:
+  - url: http://localhost:3000
+    description: Local development server (internal only)
+  - url: https://api.sentryagent.ai
+    description: Production server (restrict to Prometheus scraper)
+
+tags:
+  - name: Metrics
+    description: Prometheus metrics scrape endpoint
+
+components:
+  schemas:
+    PrometheusMetrics:
+      type: string
+      description: |
+        Metrics in Prometheus text exposition format (v0.0.4).
+        Each metric family is preceded by `# HELP` and `# TYPE` comment lines.
+      example: |
+        # HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
+        # TYPE process_cpu_user_seconds_total counter
+        process_cpu_user_seconds_total 0.123456
+        # HELP http_requests_total Total number of HTTP requests.
+        # TYPE http_requests_total counter
+        http_requests_total{method="POST",route="/api/v1/token",status_code="200"} 4201
+        http_requests_total{method="GET",route="/api/v1/agents",status_code="200"} 987
+
+    ErrorResponse:
+      type: object
+      description: Standard error response envelope.
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          example: "INTERNAL_SERVER_ERROR"
+        message:
+          type: string
+          example: "An unexpected error occurred. Please try again later."
+
+paths:
+  /metrics:
+    get:
+      operationId: scrapeMetrics
+      tags:
+        - Metrics
+      summary: Prometheus metrics scrape endpoint
+      description: |
+        Returns all registered metrics in Prometheus text exposition format.
+
+        The `Content-Type` header in the response is set to the value reported
+        by the `prom-client` registry (`text/plain; version=0.0.4; charset=utf-8`).
+
+        This endpoint is **unauthenticated** and is intended for internal
+        Prometheus scraping only. Do not expose on public interfaces.
+      security: []
+      responses:
+        '200':
+          description: Metrics in Prometheus text exposition format.
+          content:
+            text/plain:
+              schema:
+                $ref: '#/components/schemas/PrometheusMetrics'
+              example: |
+                # HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
+                # TYPE process_cpu_user_seconds_total counter
+                process_cpu_user_seconds_total 0.123456
+                # HELP sentryagent_tokens_issued_total Total tokens issued.
+                # TYPE sentryagent_tokens_issued_total counter
+                sentryagent_tokens_issued_total 4201
+                # HELP sentryagent_agents_registered_total Total agents registered.
+                # TYPE sentryagent_agents_registered_total counter
+                sentryagent_agents_registered_total 120
+        '500':
+          description: Unexpected error while collecting metrics.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                code: INTERNAL_SERVER_ERROR
+                message: "An unexpected error occurred. Please try again later."