5 Commits

Author	SHA1	Message	Date
shankar0123	ff75361553	mcp(coverage): add 34 tools across 7 domains to close 2026-05-05 parity audit P1 findings ... Closes findings P1-1..P1-35 from the 2026-05-05 CLI/API/MCP↔GUI parity audit (cowork/cli-gui-parity-audit-2026-05-05/RESULTS.md). Before this bundle, 35 operator-facing API endpoints had GUI surfaces but no MCP counterpart — operators using AI assistants for cert lifecycle work in regulated environments had to drop to curl for approve/reject, health-check acknowledgement, renewal-policy CRUD, network-scan triggering, discovery triage, intermediate-CA management, and job verification. Tool count: 87→121 in tools.go (+34), 6 unchanged in tools_est.go. Re-derive via grep -cE 'gomcp\\.AddTool\\(' internal/mcp/tools.go internal/mcp/tools_est.go. The 7 phases (matching the bundle prompt at cowork/mcp-coverage-expansion-prompt.md): Phase A — Approvals (P1-28..P1-31, 4 tools) list_approvals, get_approval, approve_request, reject_request. Two-person-integrity contract (ErrApproveBySameActor → HTTP 403) is preserved automatically: the decided_by actor is derived server-side from middleware.UserKey, NOT from request body, so the MCP server's authenticated API-key identity becomes the audit-trail actor. The MCP input schema deliberately omits any actor_id field to prevent client-side spoofing. Phase B — Health Checks (P1-20..P1-27, 8 tools) list, summary, get, create, update, delete, history, acknowledge. Mirrors the existing target-resource shape; acknowledge takes optional 'actor' string captured in the audit row (handler defaults to 'unknown' if absent). Phase C — Renewal Policies (P1-1..P1-5, 5 tools) Standard CRUD against /api/v1/renewal-policies. Distinct from the legacy 'policy' tools that point at the same path — these expose the renewal-policy domain explicitly with full alert_channels + alert_severity_map field shape. Phase D — Network Scan Targets (P1-14..P1-19, 6 tools) CRUD + trigger_scan. trigger_network_scan returns the discovery- scan body so the AI can chain into list_discovered_certificates filtered by agent_id. Phase E — Discovery read-side (P1-10..P1-13, 4 tools) list_discovered_certificates, get_discovered_certificate, list_discovery_scans, discovery_summary. Complements the pre-existing claim/dismiss tools (registered alongside Health historically per the I-2 closure). Phase F — Intermediate CAs (P1-6..P1-9, 4 tools) list, create (root + child via discriminator on body shape), get, retire. The handler is admin-gated via middleware.IsAdmin; the least-privilege boundary is enforced at the API layer (HTTP 403 for non-admin Bearer callers) — not by transport carve-out. Phase G — Verification + deployments (P1-32, P1-34, P1-35, 3 tools) list_certificate_deployments, verify_job, get_job_verification. P1-33 (POST /api/v1/agents/{id}/discoveries) is intentionally excluded — machine-to-machine push channel for agents reporting filesystem-scan results, not an operator-driven flow. Documented inline in the RegisterTools dispatch. Implementation: - 14 new input types in internal/mcp/types.go with jsonschema struct tags driving LLM tool discovery. - 7 register* functions in internal/mcp/tools.go each handling one phase, wired into RegisterTools dispatch in declaration order. - 34 new entries in tools_per_tool_test.go::allHappyPathCases — the existing in-process MCP harness (TestMCP_AllTools_HappyPath + TestMCP_AllTools_ErrorPath + TestMCP_RegisterTools_DispatchableToolCount) auto-extends coverage to cover every new tool: happy-path round- trip with fence-shape assertion, 5xx error-path with MCP_ERROR fence propagation, and 'every registered tool is dispatchable' guard. - docs/reference/mcp.md 'Available Tools' table expanded from 16 to 22 resource domains with current per-domain tool counts. Acceptance gate (verified): - go build ./cmd/server/... ./cmd/agent/... ./cmd/cli/... ./cmd/mcp-server/... clean across all four production binaries. - go vet ./... clean. - go test -short -count=1 ./internal/mcp/... pass (TestMCP_AllTools_* expanded to 127 tool round-trips). - go test -short -count=1 ./... pass repo-wide. - bash scripts/ci-guards/openapi-handler-parity.sh clean (router 178, OpenAPI 144, exceptions 36 — unchanged; we add MCP wrappers, not routes). - gofmt -l clean across the four touched files.	2026-05-05 19:29:57 +00:00
shankar0123	75097909e9		2026-05-05 18:18:29 +00:00
shankar0123	622cd29f20	docs: factuality sweep — fix 3 broken links + 12 count claims (audit findings 2026-05-05) ... Per the cowork/docs-audit-2026-05-05/ end-to-end factuality audit (20 confirmed findings across 76 docs, 7 parallel subagents + audit-of-the-audit). Hot + Warm tier fixes ship here; STALE findings (qa-test-suite.md test-count snapshot) need 'make qa-stats' which is operator-side. BROKEN links repaired (3): - docs/reference/api.md L195: [Quick Start](quickstart.md) → ../getting-started/quickstart.md (404 pre-fix) - docs/reference/api.md L196: [Connector Guide](connectors.md) → connectors/index.md (Phase 4 rename, was 404 pre-fix) - docs/reference/protocols/scep-intune.md L377: [legacy-est-scep.md](legacy-est-scep.md) → scep-server.md (file was deleted in Phase 7 commit e9b1510) INCORRECT count claims repaired (12): - api.md L5 + L18-19 + L155: '78 API operations' / '# 78' / 'all 78 documented operations' → re-derive via grep -cE '^\s+operationId:' (actual at HEAD: 144) - architecture.md L66 (Mermaid label) + L502 + L1047 + L1253: '8 always-on + 4 optional loops' / '12-loop topology' → 9 always-on + 5 opt-in loops (14 total). Always-on/opt-in breakdown derived from cmd/server/main.go startup wiring: always-on are agentHealthCheck, crlGeneration, jobProcessor, jobRetry, jobTimeout, notificationProcess, notificationRetry, renewalCheck, shortLivedExpiryCheck (9); opt-in are networkScan, digest, healthCheck, cloudDiscovery, acmeGC (5). Re-derive count via grep -cE '^func \(s \*Scheduler\) [a-zA-Z]+Loop' internal/scheduler/scheduler.go. - configuration.md L31: '12 loops, 8 always-on + 4 opt-in' → '14 loops, 9 always-on + 5 opt-in'. Self-introduced regression from commit 3275f9f (2026-05-05). - mcp.md L11 + L65: 'all 78 API endpoints' / '78 available tools' → re-derive via grep -cE 'mcp\.AddTool\(' (actual at HEAD: 87 MCP tools, 144 API operations). - connectors/index.md L111: '9 built-in' issuer connectors → '12 built-in', extending the inline enumeration to include Entrust, GlobalSign, EJBCA (which had been added since the L111 prose was written). Local-CA framing extended to mention tree mode + ADCS sub-CA mode-doc. - connectors/index.md L112: '14 built-in' target connectors → '15 built-in', adding AWS ACM target + Azure Key Vault target (which had been added since the L112 prose was written). - why-certctl.md L37 + the inline list: 'Nine issuer connectors ship today' → 'Twelve issuer connectors', adding AWS ACM PCA, Entrust, GlobalSign, EJBCA to the list and removing the misleading 'EST enrollment' bullet (EST is a protocol surface, not an issuer; clarified in trailing note). - why-certctl.md L66: '13 deployment targets' → '15', adding Kubernetes Secrets, AWS ACM, and Azure KV to the inline list. - why-certctl.md L92: 'supports 9 issuer types' → '12 issuer types'. - quickstart.md L135: '35 demo certificates across 5 issuers' → re-derive cert count via 'grep -oE "mc-[a-z0-9_-]+" migrations/seed_demo.sql | sort -u | wc -l' (actual: 32, matches README L86; quickstart was off-by-3). - quickstart.md L452 (Demo Data Reference table): Certificates '35' → '32' (matches the cert count from seed_demo.sql). Verification: - grep confirms no remaining stale refs across the touched files (8 files, 31 insertions / 28 deletions). - All 24 ci-guards/*.sh pass locally. - The audit's STALE findings (S-1, S-2 qa-test-suite.md Bundle-P snapshot) are operator-side: run 'make qa-stats' to refresh the Test Suite Health table. Companion: cowork/docs-audit-2026-05-05/RESULTS.md captures the full audit with subagent false positives and missed findings called out.	2026-05-05 06:15:35 +00:00
shankar0123	19c8fafe84	docs: Phase 14 — Last reviewed line sweep across docs/ ... Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/. Adds a `> Last reviewed: 2026-05-05` line right after the H1 heading of every doc that didn't already have one (41 files). This dates the freshness clock for the future Phase 4 per-doc review. The discipline going forward: when a doc's content gets a meaningful edit, bump the date. When the date gets old (e.g., >6 months), the doc earns a freshness-review pass. Mechanical insertion via awk one-liner, applied to every docs/*.md that didn't already match `grep -q 'Last reviewed:'`. Files that already carried the line from earlier Phase 2 work (the navigation index, the new connector docs, the new SCEP server / legacy-clients- TLS-1.2 / release-verification docs, and the 5 per-connector deep dives) were skipped to avoid duplicate insertion. Net: every doc in docs/ now has a Last reviewed line.	2026-05-05 03:26:46 +00:00
shankar0123	3a807ae37e	docs: Phase 2 mechanical file moves to subdirectory structure ... Pure git mv operations; no content edits. Internal links remain pointing at old paths and will be fixed in Phase 11. Per the Phase 1 audit recommendations at cowork/docs-overhaul-phase-1-audit-2026-05-04/. 35 files moved across 8 audience-organized subdirectories: docs/getting-started/ (5): quickstart.md, concepts.md, examples.md, advanced-demo.md (was demo-advanced.md), why-certctl.md docs/reference/ (6): architecture.md, api.md (was openapi.md), mcp.md, intermediate-ca-hierarchy.md, deployment-model.md (was deployment-atomicity.md), vendor-matrix.md (was deployment-vendor-matrix.md) docs/reference/protocols/ (6): acme-server.md, acme-server-threat-model.md, scep-intune.md, est.md, crl-ocsp.md, async-ca-polling.md (was async-polling.md) docs/operator/ (4): security.md, tls.md, database-tls.md, approval-workflow.md docs/operator/runbooks/ (3): cloud-targets.md (was runbook-cloud-targets.md), expiry-alerts.md (was runbook-expiry-alerts.md), disaster-recovery.md docs/migration/ (3): from-certbot.md (was migrate-from-certbot.md), from-acmesh.md (was migrate-from-acmesh.md), cert-manager-coexistence.md (was certctl-for-cert-manager-users.md) docs/compliance/ (4): index.md (was compliance.md), soc2.md (was compliance-soc2.md), pci-dss.md (was compliance-pci-dss.md), nist-sp-800-57.md (was compliance-nist.md) docs/contributor/ (4): testing-strategy.md, test-environment.md (was test-env.md), ci-pipeline.md, qa-test-suite.md (was qa-test-guide.md) Deferred to later Phase 2 sub-phases: - connectors.md split (Phase 4): docs/connectors.md + docs/connector-{apache,f5,iis,k8s,nginx}.md still at top level - testing-guide.md prune (Phase 5): docs/testing-guide.md still at top level - features.md disperse (Phase 6): docs/features.md still at top level - legacy-est-scep.md split (Phase 7): docs/legacy-est-scep.md still at top level - ACME walkthrough re-homing (Phase 8): three docs/acme-*-walkthrough.md still at top level - Upgrade docs archive (Phase 3): two docs/upgrade-*.md still at top level Cross-reference updates (Phase 11) will happen after all moves and content edits land. Internal links to docs/* paths are temporarily broken until that phase completes.	2026-05-05 02:49:28 +00:00