certctl

gsadmin/certctl

Fork 0

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

Commit Graph

Author	SHA1	Message	Date
shankar0123	ec88a61274	acme-server: foundation — directory + new-nonce + per-profile routing (Phase 1a/7) First slice of the RFC 8555 ACME server endpoint (master plan at cowork/acme-server-endpoint-prompt.md, per-phase prompts at cowork/acme-server-prompts/). This commit lands the smallest viable end-to-end deployable slice: an ACME client running curl -sk https://certctl/acme/profile/<id>/directory curl -sk -I https://certctl/acme/profile/<id>/new-nonce successfully fetches the directory document and a Replay-Nonce. Account creation, JWS verification, orders, challenges, and revocation are all out of scope for this phase and arrive in Phases 1b–4. Closes the Rank 1 LHF from the 2026-05-03 Infisical deep-research (cowork/infisical-deep-research-results.md). Pre-fix, certctl was an ACME consumer only — no /acme/directory endpoint, no JWS verifier, no challenge validators. K8s customers running cert-manager could not point at certctl as an ACME issuer; they had to deploy a certctl agent on every node. What ships: - internal/api/acme/{directory,nonce,errors}.go (+ tests). - internal/api/handler/acme.go + acme_handler_test.go. - internal/repository/postgres/acme.go (nonce ops only — Phase 1b extends with account CRUD; Phases 2-4 extend with order / authz / challenge CRUD). - internal/service/acme.go (BuildDirectory + IssueNonce stubs; Phase 1b adds VerifyJWS / NewAccount / etc.). - migrations/000025_acme_server.{up,down}.sql ships the full 5-table ACME schema (acme_accounts / acme_orders / acme_authorizations / acme_challenges / acme_nonces) PLUS the per-profile certificate_profiles.acme_auth_mode column. Phase 1a actively uses only acme_nonces; remaining tables are empty until Phases 1b-4 plug in. - internal/config/config.go: ACMEServerConfig struct + ACMEServer field on Config. Env vars use CERTCTL_ACME_SERVER_* prefix to avoid colliding with the existing consumer-side ACMEConfig at config.go:1746 (CERTCTL_ACME_DIRECTORY_URL / PROFILE / CHALLENGE_TYPE etc.). Phase 1a wires Enabled + DefaultAuthMode + DefaultProfileID + NonceTTL + DirectoryMeta; Order/Authz TTLs + per-challenge-type concurrency caps + DNS01 resolver are reserved fields parsed in 1a so operators can set them ahead of Phases 2/3. - cmd/server/main.go: wire ACMEHandler into the HandlerRegistry literal alongside the existing certificate / EST / SCEP / etc. handlers. - internal/api/router/router.go: HandlerRegistry.ACME field + 6 Register calls (3 per-profile + 3 shorthand). - internal/api/router/openapi_parity_test.go: 6 new entries in SpecParityExceptions. ACME is a wire-protocol surface (JWS-signed JSON over HTTPS per RFC 7515) whose semantics are dictated by RFC 8555 + RFC 9773 rather than by an OpenAPI document, same precedent as SCEP/EST. The canonical reference is docs/acme-server.md. - docs/acme-server.md: Phase-1a-shaped reference. Configuration table for every CERTCTL_ACME_SERVER_* env var. Per-profile auth-mode decision tree skeleton. TLS trust bootstrap section flagging cert-manager's ClusterIssuer.spec.acme.caBundle requirement (the single biggest first-time-deploy footgun; the full cert-manager walkthrough lands in Phase 6 but the requirement is documented up front). Architecture decisions baked in: - URL family is /acme/profile/<id>/* (per-profile, canonical) with /acme/* shorthand active when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID is set. Path matches existing per-profile precedent in EST + SCEP. - Auth mode is per-profile (acme_auth_mode column on certificate_profiles), NOT server-wide. One certctl-server can serve trust_authenticated for an internal-PKI profile and challenge for a public-trust-style profile simultaneously. The column is read at request time, not cached at server start — operators flipping a profile's mode via SQL take effect on the next order without restart. - Nonces are DB-backed (acme_nonces table). Survive server restart. The RFC 8555 §6.5 replay defense requires the store to outlast the client's nonce caching window; an in-memory-only nonce store would lose every in-flight order on restart. - Per-op atomic counters on service.ACMEService.Metrics() — certctl_acme_directory_total, certctl_acme_directory_failures_total, certctl_acme_new_nonce_total, certctl_acme_new_nonce_failures_total. Naming follows certctl frozen decision 0.10 cardinality discipline. Phase 1b will extend with new_account counters; Phase 2 with order / finalize / cert; Phase 3 with per-challenge-type counters. Audit fixes #11 + #12 (cowork/acme-server-prompts/audit-additions.md) applied: - #11: CERTCTL_ACME_SERVER_* prefix avoids the consumer-side CERTCTL_ACME_* namespace collision. - #12: prior-attempt WIP from two failed Phase-1 dispatches was discarded at phase start; this commit starts from a clean tree. Tests: - 14 unit tests in internal/api/acme/ (directory, nonce, errors). - 7 handler-level tests via httptest.NewServer + mockACMEService (mirrors the mockSCEPService pattern at scep_handler_test.go). - 7 service-layer tests with mocked repo + injected profileLookup. - All pass under -race -count=1 -short. Deferred to Phase 1b: - JWS verification (go-jose v4 — see master-prompt §8a for the API surface and audit doc for the speculation pitfalls). - new-account / account/<id> endpoints + AccountService. - Nonce consumption path (issue path is in this commit; consume is only invoked by JWS-verified POSTs which Phase 1b adds). Engineering history: cowork/WORKSPACE-CHANGELOG.md "ACME-Server-1a". Per-phase implementation plan: cowork/acme-server-prompts/. Master plan + audit fixes: cowork/acme-server-endpoint-prompt.md + cowork/acme-server-prompt-audit.md + cowork/acme-server-prompts/audit-additions.md.	2026-05-03 12:55:40 +00:00
shankar0123	a12a437664	feat(scep): mTLS sibling route /scep-mtls/<pathID> (opt-in) SCEP RFC 8894 + Intune master bundle — Phase 6.5 of 14 (opt-in, enterprise-procurement-checkbox). Closes the procurement-team objection that 'shared password authentication' is a checkbox-fail regardless of how strong the password is. The clean answer: a sibling route that adds client-cert auth at the handler layer AND keeps the challenge password (defense in depth, not replacement). Devices present a bootstrap cert from a trusted CA (e.g. a manufacturing-time cert), then SCEP-enroll for their long-lived cert. Same model Apple's MDM and Cisco's BRSKI use. internal/config/config.go * SCEPProfileConfig gains MTLSEnabled bool + MTLSClientCATrustBundlePath string. Indexed env-var loader reads CERTCTL_SCEP_PROFILE_<NAME>_MTLS_ENABLED + CERTCTL_SCEP_PROFILE_<NAME>_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH. * Validate() refuses MTLSEnabled=true with empty bundle path — structural defense in depth ahead of the file-content preflight. cmd/server/main.go * preflightSCEPMTLSTrustBundle: file existence + PEM parse + ≥1 CERTIFICATE block + non-expired check. Returns the parsed x509.CertPool ready to inject into the per-profile SCEPHandler. Failures os.Exit(1) with the offending PathID in the structured log. SCEP startup loop walks each profile; when MTLSEnabled, runs preflight, builds the per-profile pool, contributes the bundle's certs to the union pool that backs the TLS-layer VerifyClientCertIfGiven, clones the SCEPHandler with SetMTLSTrustPool, and registers the parallel sibling route via apiRouter.RegisterSCEPMTLSHandlers. * Union pool published to outer scope as scepMTLSUnionPoolForTLS; passed to buildServerTLSConfigWithMTLS so the listener serves both /scep[/<pathID>] (no client cert) and /scep-mtls/<pathID> (cert required at handler layer) on the same socket. * Final-handler dispatch gains /scep-mtls + /scep-mtls/* prefix routing through the no-auth chain (auth boundary is the client cert + challenge password, NOT a Bearer token). cmd/server/tls.go * New buildServerTLSConfigWithMTLS that wraps buildServerTLSConfig + sets ClientCAs + ClientAuth=VerifyClientCertIfGiven when a non-nil pool is passed. nil pool = identical TLS shape to the pre-Phase-6.5 builder (no behavior change for deploys without mTLS profiles). * Critical: VerifyClientCertIfGiven (NOT RequireAndVerifyClientCert) so a client that doesn't present a cert can still hit the standard /scep route. The per-profile gate at the handler layer enforces 'cert required' on /scep-mtls/<pathID>. internal/api/handler/scep.go * SCEPHandler gains mtlsTrustPool x509.CertPool field + SetMTLSTrustPool method. Per-profile pool injected by cmd/server/main.go after preflight. HandleSCEPMTLS wrapper: gates on r.TLS.PeerCertificates non-empty + per-profile cert.Verify against THIS profile's pool. Returns HTTP 401 for missing/untrusted cert (mTLS failure is auth, not authorization). Returns HTTP 500 if mtlsTrustPool is nil (deploy bug — the route shouldn't have been registered). On success delegates to HandleSCEP — defense in depth: mTLS is additive, NOT replacement; the standard SCEP code path including the challenge-password gate still executes. * Per-profile re-verification via cert.Verify(...) is critical: the TLS layer verified against the UNION pool, so a cert that chains to profile A's bundle would pass TLS even when targeting profile B. The handler-layer gate prevents cross-profile bleed-through. internal/api/router/router.go * AuthExemptDispatchPrefixes gains '/scep-mtls' (auth boundary is client cert + challenge password, NOT Bearer token). * RegisterSCEPMTLSHandlers parallel to RegisterSCEPHandlers: empty PathID maps to /scep-mtls root; non-empty maps to /scep-mtls/<pathID>. Each handler in the map MUST have had SetMTLSTrustPool called. internal/api/router/openapi_parity_test.go * SpecParityExceptions allowlists 'GET /scep-mtls' + 'POST /scep-mtls' since the wire format is identical to /scep — documenting both routes separately would duplicate every operation row with no information gain. Documented alternative in docs/legacy-est-scep.md. internal/api/handler/scep_mtls_test.go (new, ~210 LoC) * 6 tests + 2 helpers covering the auth contract: 1. RejectsMissingClientCert — request with r.TLS=nil → 401 2. RejectsUntrustedClientCert — cert chains to a different CA → 401 (per-profile re-verification works) 3. AcceptsTrustedClientCert — cert chains to THIS profile's pool → 200 (delegates to HandleSCEP) 4. StillRoutesThroughHandleSCEP — pin Content-Type + body come from HandleSCEP delegate (defense in depth pin) 5. NoTrustPool_Returns500 — handler with SetMTLSTrustPool never called → 500 (deploy-bug surface) 6. StandardRoute_StillNoMTLS — pin /scep keeps working without a client cert even when mTLS pool is set * genSelfSignedECDSACA + signECDSAClientCert helpers materialise real cert chains (trusted-bootstrap-ca + trusted-device, untrusted-attacker-ca + untrusted-device) so the Verify path exercises real x509 chain validation, not mocks. docs/features.md * SCEP env-vars table extended with the two new MTLS env vars (CERTCTL_SCEP_PROFILE_<NAME>_MTLS_ENABLED, CERTCTL_SCEP_PROFILE_<NAME>_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH). Closes the G-3 'env var defined in Go but never documented' gate. docs/legacy-est-scep.md * New 'mTLS sibling route (Phase 6.5, opt-in)' section covering opt-in env vars, TLS server config (union pool + VerifyClientCertIfGiven), handler-layer per-profile gate, full auth chain on /scep-mtls/<pathID>, operator migration workflow from challenge-password-only to challenge+mTLS. cowork/CLAUDE.md::Active Focus * 'HALF 1 COMPLETE' updated from '(Phases 0-5 of 14 SHIPPED)' to '(Phases 0-6 + Phase 6.5 of 14 SHIPPED)'. Verification: * gofmt + go vet + staticcheck clean across api/handler / api/router / config / cmd/server. * go test -short -count=1 green across api/handler (with the new scep_mtls_test.go) / api/router / service / config / pkcs7 / cmd/server / connector/issuer/local. * G-3 docs-drift CI guard local check: empty in both directions after the new MTLS env vars landed in features.md. * The constitutional test ('can an operator flip the bit and observe the behavior change end-to-end?') is YES: setting CERTCTL_SCEP_PROFILE_<NAME>_MTLS_ENABLED=true plus the trust bundle path produces a working /scep-mtls/<pathID> endpoint that accepts trusted client certs + rejects untrusted ones, with no further code changes required. Phase 6.5 of 14 in SCEP RFC 8894 + Intune master bundle. Half 1 (Phases 0-6 + 6.5) is now FEATURE-COMPLETE for the ChromeOS / general-MDM use case. Half 2 (Phases 7-12) adds the Microsoft Intune dynamic-challenge layer.	2026-04-29 13:58:18 +00:00
shankar0123	e720474fb7	Bundle D: Documentation & transparency sweep — 8 findings closed Closes H-009 + L-001 + L-007 + L-008 + L-016 + L-017 + L-018 + M-027 from comprehensive-audit-2026-04-25. H-009 — README JWT verified-already-clean README has zero JWT mentions at audit time. docs/architecture.md correctly documents JWT/OIDC integration via authenticating-gateway pattern (line 905-912). .github/workflows/ci.yml: new step 'Forbidden README JWT advertising regression guard (H-009)' greps README for JWT-as-supported phrasing; passes verbatim (gateway / pre-G-1) but fails build on net-new advertising. L-001 (CWE-295) — InsecureSkipVerify per-site justification Audit count was 8; recon found 13 production sites. docs/tls.md: new 'InsecureSkipVerify justifications' table enumerates each site by file:line with per-site rationale. cmd/agent/verify.go:78, internal/tlsprobe/probe.go:54, internal/service/network_scan.go:460: each previously-bare InsecureSkipVerify: true now carries //nolint:gosec. .github/workflows/ci.yml: new step 'Forbidden bare InsecureSkipVerify regression guard (L-001)' fails build if any net-new ISV lands in non-test .go without nolint:gosec on the same or preceding line. L-007 — README dependency-audit commands README.md: new Dependencies section with go list -m all \| wc -l, go mod why, govulncheck ./.... Honors operating-rules invariant. L-008 — Release-time govulncheck gate .github/workflows/release.yml: new 'Install govulncheck' + 'Run govulncheck (release gate)' steps in the matrix job. Pinned to same install path as ci.yml. Default exit code semantics (fail on called-vuln only, deferred-call advisories tracked on master via L-021) keeps the gate appropriate. L-016 — architecture.md drift fixes docs/architecture.md: system-components diagram's '21 tables' annotation removed (current 23; replaced with TEXT-keys descriptor); connector-architecture '9 connectors' prose replaced with grep ref + current 12-issuer list (added Entrust/GlobalSign/EJBCA which were missing); API-design '97 operations / 107 total' replaced with grep commands. Connector subgraphs verified-current at 12/13/6. L-017 — workspace CLAUDE.md verified-already-clean Bundle B's pre-commit-gate refactor already converted current- state numeric claims to grep commands. Phase 0 recon confirmed zero remaining hardcoded counts. L-018 — Defect age table cowork/comprehensive-audit-2026-04-25/defect-age.md (NEW): Tabulates all 9 High findings with first-mentioned commit, closing bundle, days-open. Methodology snippet for re-running. Key finding: 8 of 9 closed within 24h of audit publication. M-027 — OpenAPI parity verified-already-clean Audit's 'router 121 vs OpenAPI 125 — 4-op gap' was wrong methodology. The 4-op 'gap' was exactly the 4 routes registered via r.mux.Handle (auth-exempt allowlist) instead of r.Register. When you count both dispatch shapes the totals match exactly. internal/api/router/openapi_parity_test.go (NEW): TestRouter_OpenAPIParity AST-walks router.go for both Register and mux.Handle calls + walks api/openapi.yaml's path/method nesting + asserts the sets match. Adding a route without updating the spec fails CI permanently. Audit deliverables: audit-report.md: score 38/55 -> 46/55 closed (High 7/9 -> 8/9; Medium 20/27 -> 21/27; Low 8/19 -> 14/19) findings.yaml: 8 status flips open -> closed defect-age.md: new file certctl/CHANGELOG.md: Bundle D section Verification: TestRouter_OpenAPIParity PASS L-001 grep guard self-test (after //nolint:gosec adds) PASS H-009 grep guard self-test PASS go test -count=1 -short on changed packages green	2026-04-27 00:47:15 +00:00

Author

SHA1

Message

Date

shankar0123

ec88a61274

acme-server: foundation — directory + new-nonce + per-profile routing (Phase 1a/7)

First slice of the RFC 8555 ACME server endpoint (master plan at
cowork/acme-server-endpoint-prompt.md, per-phase prompts at
cowork/acme-server-prompts/). This commit lands the smallest viable
end-to-end deployable slice: an ACME client running

  curl -sk https://certctl/acme/profile/<id>/directory
  curl -sk -I https://certctl/acme/profile/<id>/new-nonce

successfully fetches the directory document and a Replay-Nonce.
Account creation, JWS verification, orders, challenges, and
revocation are all out of scope for this phase and arrive in Phases
1b–4.

Closes the Rank 1 LHF from the 2026-05-03 Infisical deep-research
(cowork/infisical-deep-research-results.md). Pre-fix, certctl was an
ACME consumer only — no /acme/directory endpoint, no JWS verifier,
no challenge validators. K8s customers running cert-manager could
not point at certctl as an ACME issuer; they had to deploy a certctl
agent on every node.

What ships:
  - internal/api/acme/{directory,nonce,errors}.go (+ tests).
  - internal/api/handler/acme.go + acme_handler_test.go.
  - internal/repository/postgres/acme.go (nonce ops only — Phase 1b
    extends with account CRUD; Phases 2-4 extend with order / authz /
    challenge CRUD).
  - internal/service/acme.go (BuildDirectory + IssueNonce stubs;
    Phase 1b adds VerifyJWS / NewAccount / etc.).
  - migrations/000025_acme_server.{up,down}.sql ships the full 5-table
    ACME schema (acme_accounts / acme_orders / acme_authorizations /
    acme_challenges / acme_nonces) PLUS the per-profile
    certificate_profiles.acme_auth_mode column. Phase 1a actively
    uses only acme_nonces; remaining tables are empty until Phases
    1b-4 plug in.
  - internal/config/config.go: ACMEServerConfig struct + ACMEServer
    field on Config. Env vars use CERTCTL_ACME_SERVER_* prefix to
    avoid colliding with the existing consumer-side ACMEConfig at
    config.go:1746 (CERTCTL_ACME_DIRECTORY_URL / PROFILE /
    CHALLENGE_TYPE etc.). Phase 1a wires Enabled +
    DefaultAuthMode + DefaultProfileID + NonceTTL + DirectoryMeta;
    Order/Authz TTLs + per-challenge-type concurrency caps + DNS01
    resolver are reserved fields parsed in 1a so operators can set
    them ahead of Phases 2/3.
  - cmd/server/main.go: wire ACMEHandler into the HandlerRegistry
    literal alongside the existing certificate / EST / SCEP / etc.
    handlers.
  - internal/api/router/router.go: HandlerRegistry.ACME field + 6
    Register calls (3 per-profile + 3 shorthand).
  - internal/api/router/openapi_parity_test.go: 6 new entries in
    SpecParityExceptions. ACME is a wire-protocol surface (JWS-signed
    JSON over HTTPS per RFC 7515) whose semantics are dictated by
    RFC 8555 + RFC 9773 rather than by an OpenAPI document, same
    precedent as SCEP/EST. The canonical reference is
    docs/acme-server.md.
  - docs/acme-server.md: Phase-1a-shaped reference. Configuration
    table for every CERTCTL_ACME_SERVER_* env var. Per-profile
    auth-mode decision tree skeleton. TLS trust bootstrap section
    flagging cert-manager's ClusterIssuer.spec.acme.caBundle
    requirement (the single biggest first-time-deploy footgun;
    the full cert-manager walkthrough lands in Phase 6 but the
    requirement is documented up front).

Architecture decisions baked in:
  - URL family is /acme/profile/<id>/* (per-profile, canonical) with
    /acme/* shorthand active when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID
    is set. Path matches existing per-profile precedent in EST + SCEP.
  - Auth mode is per-profile (acme_auth_mode column on
    certificate_profiles), NOT server-wide. One certctl-server can
    serve trust_authenticated for an internal-PKI profile and
    challenge for a public-trust-style profile simultaneously. The
    column is read at request time, not cached at server start —
    operators flipping a profile's mode via SQL take effect on the
    next order without restart.
  - Nonces are DB-backed (acme_nonces table). Survive server restart.
    The RFC 8555 §6.5 replay defense requires the store to outlast
    the client's nonce caching window; an in-memory-only nonce
    store would lose every in-flight order on restart.
  - Per-op atomic counters on service.ACMEService.Metrics() —
    certctl_acme_directory_total, certctl_acme_directory_failures_total,
    certctl_acme_new_nonce_total, certctl_acme_new_nonce_failures_total.
    Naming follows certctl frozen decision 0.10 cardinality discipline.
    Phase 1b will extend with new_account counters; Phase 2 with
    order / finalize / cert; Phase 3 with per-challenge-type counters.

Audit fixes #11 + #12 (cowork/acme-server-prompts/audit-additions.md)
applied:
  - #11: CERTCTL_ACME_SERVER_* prefix avoids the consumer-side
    CERTCTL_ACME_* namespace collision.
  - #12: prior-attempt WIP from two failed Phase-1 dispatches was
    discarded at phase start; this commit starts from a clean tree.

Tests:
  - 14 unit tests in internal/api/acme/ (directory, nonce, errors).
  - 7 handler-level tests via httptest.NewServer + mockACMEService
    (mirrors the mockSCEPService pattern at scep_handler_test.go).
  - 7 service-layer tests with mocked repo + injected profileLookup.
  - All pass under -race -count=1 -short.

Deferred to Phase 1b:
  - JWS verification (go-jose v4 — see master-prompt §8a for the API
    surface and audit doc for the speculation pitfalls).
  - new-account / account/<id> endpoints + AccountService.
  - Nonce *consumption* path (issue path is in this commit; consume
    is only invoked by JWS-verified POSTs which Phase 1b adds).

Engineering history: cowork/WORKSPACE-CHANGELOG.md "ACME-Server-1a".
Per-phase implementation plan: cowork/acme-server-prompts/.
Master plan + audit fixes: cowork/acme-server-endpoint-prompt.md +
cowork/acme-server-prompt-audit.md +
cowork/acme-server-prompts/audit-additions.md.

2026-05-03 12:55:40 +00:00

shankar0123

a12a437664

feat(scep): mTLS sibling route /scep-mtls/<pathID> (opt-in)

SCEP RFC 8894 + Intune master bundle — Phase 6.5 of 14 (opt-in,
enterprise-procurement-checkbox).

Closes the procurement-team objection that 'shared password
authentication' is a checkbox-fail regardless of how strong the
password is. The clean answer: a sibling route that adds client-cert
auth at the handler layer AND keeps the challenge password (defense in
depth, not replacement). Devices present a bootstrap cert from a
trusted CA (e.g. a manufacturing-time cert), then SCEP-enroll for
their long-lived cert. Same model Apple's MDM and Cisco's BRSKI use.

internal/config/config.go
  * SCEPProfileConfig gains MTLSEnabled bool + MTLSClientCATrustBundlePath
    string. Indexed env-var loader reads
    CERTCTL_SCEP_PROFILE_<NAME>_MTLS_ENABLED +
    CERTCTL_SCEP_PROFILE_<NAME>_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH.
  * Validate() refuses MTLSEnabled=true with empty bundle path —
    structural defense in depth ahead of the file-content preflight.

cmd/server/main.go
  * preflightSCEPMTLSTrustBundle: file existence + PEM parse + ≥1
    CERTIFICATE block + non-expired check. Returns the parsed
    *x509.CertPool ready to inject into the per-profile SCEPHandler.
    Failures os.Exit(1) with the offending PathID in the structured log.
  * SCEP startup loop walks each profile; when MTLSEnabled, runs
    preflight, builds the per-profile pool, contributes the bundle's
    certs to the union pool that backs the TLS-layer
    VerifyClientCertIfGiven, clones the SCEPHandler with
    SetMTLSTrustPool, and registers the parallel sibling route via
    apiRouter.RegisterSCEPMTLSHandlers.
  * Union pool published to outer scope as scepMTLSUnionPoolForTLS;
    passed to buildServerTLSConfigWithMTLS so the listener serves both
    /scep[/<pathID>] (no client cert) and /scep-mtls/<pathID>
    (cert required at handler layer) on the same socket.
  * Final-handler dispatch gains /scep-mtls + /scep-mtls/* prefix
    routing through the no-auth chain (auth boundary is the client
    cert + challenge password, NOT a Bearer token).

cmd/server/tls.go
  * New buildServerTLSConfigWithMTLS that wraps buildServerTLSConfig
    + sets ClientCAs + ClientAuth=VerifyClientCertIfGiven when a
    non-nil pool is passed. nil pool = identical TLS shape to the
    pre-Phase-6.5 builder (no behavior change for deploys without
    mTLS profiles).
  * Critical: VerifyClientCertIfGiven (NOT RequireAndVerifyClientCert)
    so a client that doesn't present a cert can still hit the standard
    /scep route. The per-profile gate at the handler layer enforces
    'cert required' on /scep-mtls/<pathID>.

internal/api/handler/scep.go
  * SCEPHandler gains mtlsTrustPool *x509.CertPool field +
    SetMTLSTrustPool method. Per-profile pool injected by
    cmd/server/main.go after preflight.
  * HandleSCEPMTLS wrapper: gates on r.TLS.PeerCertificates non-empty
    + per-profile cert.Verify against THIS profile's pool. Returns
    HTTP 401 for missing/untrusted cert (mTLS failure is auth, not
    authorization). Returns HTTP 500 if mtlsTrustPool is nil (deploy
    bug — the route shouldn't have been registered). On success
    delegates to HandleSCEP — defense in depth: mTLS is additive,
    NOT replacement; the standard SCEP code path including the
    challenge-password gate still executes.
  * Per-profile re-verification via cert.Verify(...) is critical:
    the TLS layer verified against the UNION pool, so a cert that
    chains to profile A's bundle would pass TLS even when targeting
    profile B. The handler-layer gate prevents cross-profile
    bleed-through.

internal/api/router/router.go
  * AuthExemptDispatchPrefixes gains '/scep-mtls' (auth boundary is
    client cert + challenge password, NOT Bearer token).
  * RegisterSCEPMTLSHandlers parallel to RegisterSCEPHandlers:
    empty PathID maps to /scep-mtls root; non-empty maps to
    /scep-mtls/<pathID>. Each handler in the map MUST have had
    SetMTLSTrustPool called.

internal/api/router/openapi_parity_test.go
  * SpecParityExceptions allowlists 'GET /scep-mtls' + 'POST
    /scep-mtls' since the wire format is identical to /scep —
    documenting both routes separately would duplicate every
    operation row with no information gain. Documented alternative
    in docs/legacy-est-scep.md.

internal/api/handler/scep_mtls_test.go (new, ~210 LoC)
  * 6 tests + 2 helpers covering the auth contract:
    1. RejectsMissingClientCert — request with r.TLS=nil → 401
    2. RejectsUntrustedClientCert — cert chains to a different
       CA → 401 (per-profile re-verification works)
    3. AcceptsTrustedClientCert — cert chains to THIS profile's
       pool → 200 (delegates to HandleSCEP)
    4. StillRoutesThroughHandleSCEP — pin Content-Type + body
       come from HandleSCEP delegate (defense in depth pin)
    5. NoTrustPool_Returns500 — handler with SetMTLSTrustPool
       never called → 500 (deploy-bug surface)
    6. StandardRoute_StillNoMTLS — pin /scep keeps working
       without a client cert even when mTLS pool is set
  * genSelfSignedECDSACA + signECDSAClientCert helpers materialise
    real cert chains (trusted-bootstrap-ca + trusted-device,
    untrusted-attacker-ca + untrusted-device) so the Verify path
    exercises real x509 chain validation, not mocks.

docs/features.md
  * SCEP env-vars table extended with the two new MTLS env vars
    (CERTCTL_SCEP_PROFILE_<NAME>_MTLS_ENABLED,
    CERTCTL_SCEP_PROFILE_<NAME>_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH).
    Closes the G-3 'env var defined in Go but never documented' gate.

docs/legacy-est-scep.md
  * New 'mTLS sibling route (Phase 6.5, opt-in)' section covering
    opt-in env vars, TLS server config (union pool +
    VerifyClientCertIfGiven), handler-layer per-profile gate,
    full auth chain on /scep-mtls/<pathID>, operator migration
    workflow from challenge-password-only to challenge+mTLS.

cowork/CLAUDE.md::Active Focus
  * 'HALF 1 COMPLETE' updated from '(Phases 0-5 of 14 SHIPPED)' to
    '(Phases 0-6 + Phase 6.5 of 14 SHIPPED)'.

Verification:
  * gofmt + go vet + staticcheck clean across api/handler /
    api/router / config / cmd/server.
  * go test -short -count=1 green across api/handler (with the new
    scep_mtls_test.go) / api/router / service / config / pkcs7 /
    cmd/server / connector/issuer/local.
  * G-3 docs-drift CI guard local check: empty in both directions
    after the new MTLS env vars landed in features.md.
  * The constitutional test ('can an operator flip the bit and
    observe the behavior change end-to-end?') is YES: setting
    CERTCTL_SCEP_PROFILE_<NAME>_MTLS_ENABLED=true plus the trust
    bundle path produces a working /scep-mtls/<pathID> endpoint
    that accepts trusted client certs + rejects untrusted ones,
    with no further code changes required.

Phase 6.5 of 14 in SCEP RFC 8894 + Intune master bundle.
Half 1 (Phases 0-6 + 6.5) is now FEATURE-COMPLETE for the
ChromeOS / general-MDM use case. Half 2 (Phases 7-12) adds the
Microsoft Intune dynamic-challenge layer.

2026-04-29 13:58:18 +00:00

shankar0123

e720474fb7

Bundle D: Documentation & transparency sweep — 8 findings closed

Closes H-009 + L-001 + L-007 + L-008 + L-016 + L-017 + L-018 + M-027
from comprehensive-audit-2026-04-25.

H-009 — README JWT verified-already-clean
  README has zero JWT mentions at audit time. docs/architecture.md
  correctly documents JWT/OIDC integration via authenticating-gateway
  pattern (line 905-912).
  .github/workflows/ci.yml: new step
    'Forbidden README JWT advertising regression guard (H-009)'
    greps README for JWT-as-supported phrasing; passes verbatim
    (gateway / pre-G-1) but fails build on net-new advertising.

L-001 (CWE-295) — InsecureSkipVerify per-site justification
  Audit count was 8; recon found 13 production sites.
  docs/tls.md: new 'InsecureSkipVerify justifications' table
    enumerates each site by file:line with per-site rationale.
  cmd/agent/verify.go:78, internal/tlsprobe/probe.go:54,
  internal/service/network_scan.go:460: each previously-bare
    InsecureSkipVerify: true now carries //nolint:gosec.
  .github/workflows/ci.yml: new step
    'Forbidden bare InsecureSkipVerify regression guard (L-001)'
    fails build if any net-new ISV lands in non-test .go without
    nolint:gosec on the same or preceding line.

L-007 — README dependency-audit commands
  README.md: new Dependencies section with go list -m all | wc -l,
    go mod why, govulncheck ./.... Honors operating-rules invariant.

L-008 — Release-time govulncheck gate
  .github/workflows/release.yml: new 'Install govulncheck' +
    'Run govulncheck (release gate)' steps in the matrix job.
    Pinned to same install path as ci.yml. Default exit code
    semantics (fail on called-vuln only, deferred-call advisories
    tracked on master via L-021) keeps the gate appropriate.

L-016 — architecture.md drift fixes
  docs/architecture.md: system-components diagram's '21 tables'
    annotation removed (current 23; replaced with TEXT-keys
    descriptor); connector-architecture '9 connectors' prose
    replaced with grep ref + current 12-issuer list (added
    Entrust/GlobalSign/EJBCA which were missing); API-design
    '97 operations / 107 total' replaced with grep commands.
  Connector subgraphs verified-current at 12/13/6.

L-017 — workspace CLAUDE.md verified-already-clean
  Bundle B's pre-commit-gate refactor already converted current-
  state numeric claims to grep commands. Phase 0 recon confirmed
  zero remaining hardcoded counts.

L-018 — Defect age table
  cowork/comprehensive-audit-2026-04-25/defect-age.md (NEW):
    Tabulates all 9 High findings with first-mentioned commit,
    closing bundle, days-open. Methodology snippet for re-running.
    Key finding: 8 of 9 closed within 24h of audit publication.

M-027 — OpenAPI parity verified-already-clean
  Audit's 'router 121 vs OpenAPI 125 — 4-op gap' was wrong
  methodology. The 4-op 'gap' was exactly the 4 routes registered
  via r.mux.Handle (auth-exempt allowlist) instead of r.Register.
  When you count both dispatch shapes the totals match exactly.
  internal/api/router/openapi_parity_test.go (NEW):
    TestRouter_OpenAPIParity AST-walks router.go for both
    Register and mux.Handle calls + walks api/openapi.yaml's
    path/method nesting + asserts the sets match. Adding a route
    without updating the spec fails CI permanently.

Audit deliverables:
  audit-report.md: score 38/55 -> 46/55 closed
    (High 7/9 -> 8/9; Medium 20/27 -> 21/27; Low 8/19 -> 14/19)
  findings.yaml: 8 status flips open -> closed
  defect-age.md: new file
  certctl/CHANGELOG.md: Bundle D section

Verification:
  TestRouter_OpenAPIParity                                   PASS
  L-001 grep guard self-test (after //nolint:gosec adds)     PASS
  H-009 grep guard self-test                                 PASS
  go test -count=1 -short on changed packages                green

2026-04-27 00:47:15 +00:00

3 Commits