mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 11:11:30 +00:00

Files

T

shankar0123 a0404f2d21 fix(docs,code): ARCH-004 + SEC-003-K8S + ARCH-003 — marketing claims now match code truth

Sprint 4 unified-master-audit closure. Three claim-truth-alignment
findings whose README edits land on shared lines, bundled into one
commit.

ARCH-004 — 'full REST API exposed as MCP tools' overclaim:
  Pre-fix the README said 'the full REST API is exposed as MCP
  tools'; the actual MCP coverage is 162 tools / 220 routes
  (~74%). The remaining gap is intentional: protocol-conformance
  endpoints (ACME/SCEP/EST/OCSP/CRL), browser-only auth flow,
  health/ready, and streaming/binary downloads — categories that
  don't fit the request-response JSON tool shape.

  Fix:
    - README L78 qualified to 'the bulk of the REST API surface'
      with explicit numbers + pointer to the new coverage doc.
    - New docs/reference/mcp-coverage.md publishes the exclusion
      categories with rationale + the canonical commands to
      re-derive route + tool counts.
    - New scripts/ci-guards/mcp-coverage-parity.sh fails the build
      if the tool count drops below (routes − exclusions − 40-slack),
      so a future regression that drops 50+ tools surfaces in CI.
      Verified locally: clean at 162 tools / 220 routes / 37
      intentional exclusions.

SEC-003-K8S — Kubernetes Secrets connector is a runtime stub:
  Pre-fix README L67 marketed 'fifteen native target connectors'
  with Kubernetes Secrets in the list, but realK8sClient's CRUD
  methods returned 'real Kubernetes client not implemented' in
  production. Per the audit's option (b) recommendation: downgrade
  marketing + runtime-guard the stub.

  Fix:
    - README L12 + L67: 'fourteen production-ready native deployment-
      target connectors plus Kubernetes Secrets (preview)'.
    - k8ssecret.New() now refuses to construct unless
      CERTCTL_K8SSECRET_PREVIEW_ACK=true is set, mirroring the
      SEC-H3 ACK pattern. NewWithClient path (test injection)
      unchanged.
    - docs/reference/connectors/index.md moves Kubernetes Secrets
      out of the canonical fourteen-target list into a new 'Preview
      connectors' subsection.
    - Regression tests in k8ssecret_test.go pin the new gate
      (rejects without ACK, accepts with ACK, still rejects nil
      config even with ACK).

ARCH-003 — CERTCTL_KEYGEN_MODE=server breaks the blanket claim:
  Pre-fix README L12 + L82 said 'private keys stay on your
  infrastructure' and 'never touch the control plane' as blanket
  promises. Flipping CERTCTL_KEYGEN_MODE=server makes the control
  plane mint keys in process memory — breaking the claim — and
  the only signal was a boot-time slog WARN. An operator who set
  the flag and didn't read logs ran in silent contradiction to the
  marketed posture.

  Fix:
    - config.Validate() refuses to accept KeygenMode='server'
      unless DemoModeAck=true (mirroring SEC-H3). Production
      deploys (the default Mode='agent' path) are unaffected.
    - README L12 + L82 qualified: 'In agent-mode (the default),
      private keys ...; a demo-only CERTCTL_KEYGEN_MODE=server
      flag mints keys server-side, refuses to start without an
      explicit CERTCTL_DEMO_MODE_ACK=true acknowledgement.'
    - Regression tests for the new Validate gate land in
      config_test.go (note: gate tests landed in the ARCH-002
      commit because of contiguous-hunk constraint at the bottom
      of the file).

Closes ARCH-004, SEC-003-K8S, ARCH-003.

2026-05-16 04:55:34 +00:00

4.2 KiB

Raw Permalink Blame History

MCP ↔ REST API parity coverage

Last reviewed: 2026-05-16

What this file is

This is the canonical record of which certctl REST routes are exposed as MCP (Model Context Protocol) tools, plus the explicit allowlist of routes that are intentionally NOT exposed. The companion CI guard scripts/ci-guards/mcp-coverage-parity.sh fails the build if a new REST route lands without either an MCP tool wrapping it or an explicit allowlist entry justifying the exclusion.

Before ARCH-004 (Sprint 4, 2026-05-16) the README said "the full REST API is exposed as MCP tools" with no published coverage data. That wording was an overclaim — see the audit trail in git log --grep='ARCH-004'.

Current numbers

Re-derive at any time:

# REST routes registered by the router
grep -cE '^\s*r\.Register\(' internal/api/router/router.go

# MCP tools registered (counts gomcp.AddTool call sites)
grep -rcE 'gomcp\.AddTool' internal/mcp/ --include='*.go' \
  | grep -v '_test.go' | awk -F: '{s+=$2} END{print s}'

At the most recent verification (2026-05-16): 221 routes / 162 tools.

Coverage categories

The gap between routes and tools is intentional and falls into four named exclusion categories. Adding a new REST route in any of these categories does NOT require a paired MCP tool — but it DOES require an allowlist entry in the CI guard.

1. Protocol-conformance endpoints

Routes that implement a wire protocol an automated client (cert-manager, certbot, lego, MS Intune, EST devices, OCSP responders, CRL fetchers) talks to directly. These are not human-driven API calls; the MCP "natural language → tool call" model doesn't fit them. The MCP server SHOULD NOT wrap these because exposing them would invite operators to ask an AI agent to "renew the cert via ACME" when the right answer is "the ACME client your existing infra already runs handles that."

/acme/* — RFC 8555 + RFC 9773 (ACME server)
/scep/* — RFC 8894 (SCEP server, MS Intune)
/.well-known/est/* — RFC 7030 (EST server)
/ocsp — RFC 6960 (OCSP responder)
/.well-known/pki/crl/* — RFC 5280 CRL distribution

2. Browser-only auth flow endpoints

OIDC SSO + CSRF + bootstrap routes that exist solely for the GUI's session establishment dance. An MCP client should authenticate via the same API-key Bearer path the REST callers use; exposing the browser flow as a tool would be incoherent.

/auth/oidc/login
/auth/oidc/callback
/auth/oidc/back-channel-logout
POST /api/v1/auth/bootstrap (one-shot day-0 admin)
POST /api/v1/auth/login, POST /api/v1/auth/logout
GET /api/v1/auth/csrf

3. Liveness / readiness / version

Out of scope for natural-language workflows.

/health
/ready
/api/v1/version

4. Streaming / binary download endpoints

The MCP tool contract is request → response JSON. Binary streaming and chunked transfer don't fit the shape and would force lossy encoding (base64-wrapped JSON blobs) the operator wouldn't actually use through an AI assistant.

GET /api/v1/certificates/{id}/download — raw PEM
GET /api/v1/certificates/{id}/chain — chain PEM
GET /api/v1/intermediate-cas/{id}/cert — raw cert
GET /api/v1/metrics/prometheus — Prometheus text format

How to add a new route

Add the route in internal/api/router/router.go.
Decide: should an AI assistant be able to invoke this?
- Yes → add a matching gomcp.AddTool call in internal/mcp/.
- No → confirm the route fits one of the four exclusion categories above AND add an entry to the allowlist in scripts/ci-guards/mcp-coverage-parity.sh.
The CI guard will fail until either branch is satisfied.

If the route doesn't fit any of the four categories and you don't want it in MCP for another reason, name a fifth category in this file and update the CI guard. The list is meant to grow with the product, not contain it.

Why this matters

certctl is sold to operators who'll use AI assistants to drive it. "Most of the REST API" is a meaningful coverage claim; "the full REST API" was not. Diligence reviewers and operators evaluating MCP-driven workflows need the explicit gap surface — both to plan their automation around the gap and to spot when the gap drifts.

4.2 KiB Raw Permalink Blame History