mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 20:21:29 +00:00
shankar0123
a05a7d3dad
Phase 1b push (commit 44a85d6) failed three CI guards. None were
caught by `make verify` locally because they're CI-only guards
that aren't part of the Makefile target. This commit fixes all
three.
1. go.mod tidy diff. The go-jose v4 dep was added with `// indirect`
in go.mod after the initial `go get`, but the codebase imports it
directly from internal/api/acme/jws.go + service/acme.go +
handler/acme.go. CI's `go mod tidy && git diff --exit-code go.mod
go.sum` flagged the staleness. Promoted to a direct require in
the same `require (...)` block as github.com/aws/aws-sdk-go-v2
etc.
2. G-3-env-docs-drift.sh. The guard greps `\bCERTCTL_[A-Z_]+\b` in
docs/ and complains when the bare-prefix forms don't match
anything defined in config.go. Phase 1a + 1b's docs/acme-server.md
intro and migration header use bare-prefix forms `CERTCTL_ACME_*`
and `CERTCTL_ACME_SERVER_*` to describe namespace separation
(consumer-side ACMEConfig vs server-side ACMEServerConfig). Same
precedent as the existing CERTCTL_SCEP_ + CERTCTL_TLS_ +
CERTCTL_QA_* prefix entries already in the guard's ALLOWED list.
Added CERTCTL_ACME_ + CERTCTL_ACME_SERVER_ to the ALLOWED list
with a justification comment block matching the existing
integration-surface allowlist convention.
3. openapi-handler-parity.sh. Distinct from
internal/api/router/openapi_parity_test.go (which runs at `go
test` time and has its own SpecParityExceptions map I extended
in 1a + 1b) — this is a separate CI-only guard that reads
api/openapi-handler-exceptions.yaml. The 6 Phase-1a routes + 4
Phase-1b routes (10 ACME endpoints total) were never added to
that yaml. Same rationale as the SCEP/SCEP-mTLS entries already
in the file: ACME is a JWS-signed-JSON wire protocol per
RFC 8555 + RFC 9773, not an OpenAPI-shape REST surface.
Documenting every endpoint in openapi.yaml would duplicate the
RFC. The canonical reference is docs/acme-server.md. Phases 2-4
will add their routes to this yaml in lockstep with router.go.
Verified locally:
- bash scripts/ci-guards/G-3-env-docs-drift.sh → clean.
- bash scripts/ci-guards/openapi-handler-parity.sh → clean
(152 router routes, 136 OpenAPI ops, 18 documented exceptions).
- All other ci-guards/*.sh → clean.
- go.mod diff after `go mod tidy` is empty.
108 lines
4.7 KiB
Bash
Executable File
108 lines
4.7 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# scripts/ci-guards/G-3-env-docs-drift.sh
|
|
#
|
|
# G-3 master closed cat-g-163dae19bc59 (docs-only env vars
|
|
# phantom in features.md), cat-g-b8f8f8796159 (6 config-only
|
|
# env vars never documented), and cat-g-renewal_check_interval_rename_drift
|
|
# (features.md still advertised the pre-rename
|
|
# CERTCTL_RENEWAL_CHECK_INTERVAL after it was renamed to
|
|
# CERTCTL_SCHEDULER_RENEWAL_CHECK_INTERVAL). This script runs
|
|
# `comm -23` both ways between the env vars defined in Go
|
|
# source (config.go + cmd/agent + deploy/test fixtures + ACME
|
|
# DNS-01 script env exports) and the env vars mentioned in
|
|
# README + docs/ + deploy/helm/.
|
|
#
|
|
# Allowlist: env vars that are documented as integration-
|
|
# surface contracts (script env exports for ACME DNS-01,
|
|
# OpenSSL CA scripts, StepCA per-issuer-config-blob fields,
|
|
# Webhook per-notifier-config-blob fields, ACME EAB, audit
|
|
# exclusion, demo-stack overrides) but not consumed directly
|
|
# by config.go. Each entry below has a one-line justification
|
|
# — if you add a new entry, add the justification too.
|
|
#
|
|
# See coverage-gap-audit-2026-04-24-v5/unified-audit.md
|
|
# cat-g-* for closure rationale.
|
|
|
|
set -e
|
|
# Defined: config.go + agent + cli + mcp-server + server cmds + test fixtures + ACME DNS export
|
|
{
|
|
grep -nE '"CERTCTL_[A-Z_]+"' internal/config/config.go | sed -E 's/.*"(CERTCTL_[A-Z_]+)".*/\1/'
|
|
grep -rhoE '"CERTCTL_[A-Z_]+"' cmd/agent/*.go cmd/cli/*.go cmd/mcp-server/*.go cmd/server/*.go 2>/dev/null | sed -E 's/"(CERTCTL_[A-Z_]+)"/\1/'
|
|
grep -rhoE 'CERTCTL_[A-Z_]+' deploy/test/qa_test.go internal/connector/issuer/acme/dns.go 2>/dev/null
|
|
} | grep -E '^CERTCTL_' | sort -u > /tmp/g3-defined.txt
|
|
# Documented: README + docs + helm
|
|
grep -rhoE '\bCERTCTL_[A-Z_]+\b' README.md docs/ deploy/helm/ 2>/dev/null | sort -u > /tmp/g3-docs.txt
|
|
# Allowlist of env vars documented as external integration contracts.
|
|
# Each entry justifies itself in one line; if you add to this list,
|
|
# add the justification.
|
|
ALLOWED='^(
|
|
CERTCTL_OPENSSL_SIGN_SCRIPT|
|
|
CERTCTL_OPENSSL_REVOKE_SCRIPT|
|
|
CERTCTL_OPENSSL_CRL_SCRIPT|
|
|
CERTCTL_OPENSSL_TIMEOUT_SECONDS|
|
|
CERTCTL_STEPCA_URL|
|
|
CERTCTL_STEPCA_FINGERPRINT|
|
|
CERTCTL_STEPCA_PROVISIONER|
|
|
CERTCTL_STEPCA_PROVISIONER_NAME|
|
|
CERTCTL_STEPCA_PROVISIONER_KEY|
|
|
CERTCTL_STEPCA_PROVISIONER_JWK|
|
|
CERTCTL_STEPCA_PROVISIONER_PASSWORD|
|
|
CERTCTL_STEPCA_PASSWORD|
|
|
CERTCTL_STEPCA_KEY_PATH|
|
|
CERTCTL_STEPCA_ROOT_CA|
|
|
CERTCTL_WEBHOOK_URL|
|
|
CERTCTL_WEBHOOK_SECRET|
|
|
CERTCTL_ACME_EAB_KID|
|
|
CERTCTL_ACME_EAB_HMAC|
|
|
CERTCTL_ACME_DNS_PROPAGATION_WAIT|
|
|
CERTCTL_AUDIT_EXCLUDE_PATHS|
|
|
CERTCTL_TLS_|
|
|
CERTCTL_TLS_INSECURE_SKIP_VERIFY|
|
|
CERTCTL_SCEP_|
|
|
CERTCTL_SERVER_CA_BUNDLE_PATH|
|
|
CERTCTL_SERVER_TLS_INSECURE_SKIP_VERIFY|
|
|
CERTCTL_QA_[A-Z_]+|
|
|
CERTCTL_ACME_|
|
|
CERTCTL_ACME_SERVER_
|
|
)$'
|
|
# ^ The CERTCTL_OPENSSL_* / CERTCTL_STEPCA_* / CERTCTL_WEBHOOK_* /
|
|
# CERTCTL_ACME_EAB_* / CERTCTL_ACME_DNS_PROPAGATION_WAIT /
|
|
# CERTCTL_AUDIT_EXCLUDE_PATHS / CERTCTL_TLS_* / CERTCTL_SERVER_* /
|
|
# CERTCTL_QA_* sets are documented integration-surface contracts
|
|
# (script invocations, per-issuer config-blob field names,
|
|
# per-notifier config-blob field names, demo-stack overrides,
|
|
# test fixtures) — not server-side env vars in config.go.
|
|
#
|
|
# CERTCTL_ACME_ + CERTCTL_ACME_SERVER_ are bare-prefix forms
|
|
# operator docs use to describe namespace separation between the
|
|
# consumer-side ACMEConfig (full names like CERTCTL_ACME_DIRECTORY_URL
|
|
# defined in config.go) and the ACME server's CERTCTL_ACME_SERVER_*
|
|
# prefix (full names like CERTCTL_ACME_SERVER_ENABLED defined in
|
|
# config.go::ACMEServerConfig). The bare prefixes themselves are
|
|
# never read by config.go — they're only doc prose — so they
|
|
# allowlist alongside the existing CERTCTL_SCEP_ + CERTCTL_TLS_
|
|
# bare-prefix entries.
|
|
# The audit's "37 docs-only" count over-flagged these; the
|
|
# closure narrows the gate to the specific drift sites
|
|
# (renewal-interval rename + 6 config-only) and allowlists
|
|
# the documented external contracts here.
|
|
ALLOWED_FLAT=$(echo "$ALLOWED" | tr -d '\n ')
|
|
DOCS_ONLY=$(comm -13 /tmp/g3-defined.txt /tmp/g3-docs.txt | grep -vE "$ALLOWED_FLAT" || true)
|
|
CONFIG_ONLY=$(comm -23 /tmp/g3-defined.txt /tmp/g3-docs.txt || true)
|
|
if [ -n "$DOCS_ONLY" ]; then
|
|
echo "::error::G-3 regression: env var(s) mentioned in docs but not defined in Go source AND not in the documented integration-surface allowlist:"
|
|
echo "$DOCS_ONLY"
|
|
echo ""
|
|
echo "Either delete from docs (phantom/typo) or add to config.go,"
|
|
echo "or add to the ALLOWED list with a one-line justification."
|
|
exit 1
|
|
fi
|
|
if [ -n "$CONFIG_ONLY" ]; then
|
|
echo "::error::G-3 regression: env var(s) defined in Go source but never documented:"
|
|
echo "$CONFIG_ONLY"
|
|
echo ""
|
|
echo "Add an entry to docs/features.md (or another canonical doc) so operators can find it."
|
|
exit 1
|
|
fi
|
|
echo "G-3 env-docs-drift: clean."
|