mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:21:30 +00:00
shankar0123
4f42dfb053
Phase 1b push (commit 27bd660) 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.
57 lines
3.3 KiB
YAML
57 lines
3.3 KiB
YAML
# Routes registered in internal/api/router/router.go that are intentionally
|
|
# NOT in api/openapi.yaml. Each entry needs a one-line `why:` justification.
|
|
# Adding a new entry requires PR-time review.
|
|
#
|
|
# OpenAPI-shaped REST endpoints belong in api/openapi.yaml, NOT here.
|
|
# This list is for protocol-shaped (SCEP wire endpoints) and operational
|
|
# (health, metrics, pprof) routes only.
|
|
#
|
|
# Per ci-pipeline-cleanup bundle Phase 9 / frozen decision 0.11.
|
|
|
|
documented_exceptions:
|
|
- route: "GET /scep"
|
|
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; serves CA certs via GetCACert/GetCACaps query params, NOT a REST resource."
|
|
- route: "POST /scep"
|
|
why: "SCEP wire-protocol endpoint per RFC 8894 §3.1; receives PKCSReq / RenewalReq PKIMessages, NOT a REST resource."
|
|
- route: "GET /scep/"
|
|
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
|
|
- route: "POST /scep/"
|
|
why: "SCEP wire-protocol endpoint with trailing-slash variant; ChromeOS clients send the trailing-slash form."
|
|
- route: "GET /scep-mtls"
|
|
why: "SCEP-mTLS sibling endpoint per ci-pipeline-cleanup-prerequisite EST RFC 7030 hardening Phase 6.5; same wire-protocol semantics, mutually-authenticated TLS variant."
|
|
- route: "POST /scep-mtls"
|
|
why: "SCEP-mTLS sibling endpoint, POST variant."
|
|
- route: "GET /scep-mtls/"
|
|
why: "SCEP-mTLS sibling endpoint, trailing-slash variant."
|
|
- route: "POST /scep-mtls/"
|
|
why: "SCEP-mTLS sibling endpoint, trailing-slash POST variant."
|
|
|
|
# ACME server (RFC 8555 + RFC 9773 ARI) — wire-protocol surface.
|
|
# Like SCEP/EST, ACME is a JWS-signed-JSON wire protocol whose
|
|
# semantics are dictated by the RFC, not by an OpenAPI schema.
|
|
# Documenting every endpoint in openapi.yaml would duplicate
|
|
# RFC 8555 §7.1 + §7.2 + §7.3 with no information gain. The
|
|
# canonical operator-facing reference is docs/acme-server.md.
|
|
# Phases 2-4 will extend this list as new-order, finalize, authz,
|
|
# challenge, cert, key-change, revoke-cert, renewal-info routes land.
|
|
- route: "GET /acme/profile/{id}/directory"
|
|
why: "ACME server RFC 8555 §7.1.1 directory; documented in docs/acme-server.md."
|
|
- route: "HEAD /acme/profile/{id}/new-nonce"
|
|
why: "ACME server RFC 8555 §7.2 new-nonce; documented in docs/acme-server.md."
|
|
- route: "GET /acme/profile/{id}/new-nonce"
|
|
why: "ACME server RFC 8555 §7.2 new-nonce GET form; documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/new-account"
|
|
why: "ACME server RFC 8555 §7.3 new-account (JWS jwk); documented in docs/acme-server.md."
|
|
- route: "POST /acme/profile/{id}/account/{acc_id}"
|
|
why: "ACME server RFC 8555 §7.3.2 + §7.3.6 (JWS kid) account update + deactivation; documented in docs/acme-server.md."
|
|
- route: "GET /acme/directory"
|
|
why: "ACME server default-profile shorthand; mirrors per-profile when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID is set."
|
|
- route: "HEAD /acme/new-nonce"
|
|
why: "ACME server default-profile shorthand for new-nonce HEAD."
|
|
- route: "GET /acme/new-nonce"
|
|
why: "ACME server default-profile shorthand for new-nonce GET."
|
|
- route: "POST /acme/new-account"
|
|
why: "ACME server default-profile shorthand for new-account."
|
|
- route: "POST /acme/account/{acc_id}"
|
|
why: "ACME server default-profile shorthand for account update + deactivation."
|