Closes Bundle 8 of the 2026-05-02 deployment-target coverage audit
(see cowork/deployment-target-audit-2026-05-02/RESULTS.md). Pre-fix,
DeployCertificate at javakeystore.go:172-272 ran an irreversible
keytool -delete against the existing alias, then keytool
-importkeystore. If the import failed after the delete succeeded,
the keystore was missing the alias entirely — previous cert gone,
new cert never landed. docs/deployment-atomicity.md L94 promised
"keytool snapshot; rollback via keytool -delete + re-import"; the
code didn't deliver. Separately, the operator-facing keystore
password is passed via -storepass argv (a standard keytool
limitation) which is visible to ps(1) for the duration of each
subprocess; this was undocumented as an operator-playbook caveat.
This commit:
1. Pre-delete snapshot. When os.Stat(KeystorePath) succeeds,
snapshotKeystore runs keytool -exportkeystore to
<BackupDir>/.certctl-bak.<unix-nanos>.p12 BEFORE the existing
-delete step. Backup path persisted in a local variable for
the rollback path; export-step failure aborts the deploy
entirely (no mutation has happened yet — the keystore is
untouched). Snapshot skipped on first-time deploys (no
keystore file = nothing to roll back to). The "alias not
present in pre-existing keystore" case is recognised via the
well-known keytool error string and treated as a clean
first-time-on-existing-keystore signal — the deploy proceeds
without a backup, and rollback (if needed) becomes the
no-backup branch.
2. On-import-failure rollback. When keytool -importkeystore
returns error, rollbackImport(ctx, backupPath) runs:
- keytool -delete -alias <Alias> ... (best-effort; the failed
import may have created a partial alias entry).
- keytool -importkeystore from the backup PKCS#12 to restore
the previous state.
On rollback success, the deploy returns wrapped error noting
"rolled back from <backup_path>". On rollback failure,
returns operator-actionable wrapped error containing both the
import error AND the rollback error AND the backup path so
the operator can manually keytool -importkeystore from the
.p12 file to recover.
3. Backup retention. Successful deploys prune older
.certctl-bak.*.p12 files beyond Config.BackupRetention.
Sort by ModTime newest-first; keep most recent N. Defaults:
BackupRetention=0 → keep most recent 3 (the default).
BackupRetention=N → keep most recent N.
BackupRetention=-1 → opt out of pruning entirely (operators
that wire their own archival/rotation).
Pruning runs in the success path AFTER the optional reload
command so it doesn't interfere with deploy-time signals.
ReadDir / Remove failures are non-fatal (debug log only) —
the deploy already succeeded.
4. Config gains BackupRetention int and BackupDir string fields.
BackupDir defaults to filepath.Dir(KeystorePath) so backups
land on the same filesystem as the keystore (atomic-ish
writes, disk-full failures fail fast at snapshot time).
5. Helper extraction. snapshotKeystore + rollbackImport +
pruneBackups + backupDir are private methods on Connector.
Constants backupFilePrefix=".certctl-bak." and
backupFileSuffix=".p12" centralise the naming convention so
the snapshot writer, the rollback reader, and the retention
pruner all agree.
6. Operator-playbook section added to docs/connectors.md
JavaKeystore section. Documents the standard keytool
-storepass argv exposure: ps(1)-visible for the duration
of each subprocess. Lists mitigations:
- Restrict shell access to the agent host.
- Linux user namespaces / AppArmor / SystemD ProtectProc=
invisible to deny ps-visibility.
- Single-purpose container for proper PID-namespace
isolation.
- Post-deploy keystore password rotation via reload_command
for high-security environments.
- BCFKS keystore type for FIPS environments (same argv
caveat applies).
Also documents an "Atomic rollback" subsection covering the
snapshot/rollback flow, the new backup_retention /
backup_dir Config fields, and the design choice to reuse
the keystore password for the snapshot (rather than
generating a separate transient password) — operator
already trusts the connector with this secret, surface area
doesn't grow, rollback's matching -srcstorepass stays
simple.
Tests added to javakeystore_test.go (7 new tests, ~430 LOC):
- TestJKS_Snapshot_RunsBefore_Delete: mock executor records call
order; asserts -exportkeystore is call[0], -delete is call[1],
-importkeystore is call[2]. The snapshot MUST run before the
delete — otherwise the delete destroys the very state the
snapshot is meant to capture.
- TestJKS_Snapshot_FirstTimeDeploy_NoExport: no keystore file
pre-created; asserts exactly 1 keytool call (-importkeystore
only), no -exportkeystore.
- TestJKS_ImportFails_RollsBack: happy rollback path with one
same-Subject backup. Asserts rollback re-import references the
same backup path the snapshot wrote (verified via arg
comparison between call[0] and call[4]).
- TestJKS_ImportFails_RollbackAlsoFails_OperatorActionable:
wrapped-error escalation with backup path in the error
message.
- TestJKS_BackupRetention_PrunesOldBackups: 5 pre-existing
staggered-ModTime backups + 1 deploy-created → retention=3 →
exactly 3 newest survive (deploy-created + 2 newest
pre-existing); 3 oldest pre-existing pruned.
- TestJKS_BackupRetention_Zero_DefaultsTo3: BackupRetention=0
must default to 3 (not "keep none").
- TestJKS_BackupRetention_Negative_OptsOut: BackupRetention=-1
pre-existing 5 + deploy 1 = 6 total, all 6 remain.
- TestJKS_Snapshot_AliasNotInKeystore_ProceedsCleanly: keystore
exists but alias missing; -exportkeystore returns "alias does
not exist" → snapshot helper recognises this signal and
returns ("", nil) so the deploy proceeds cleanly.
mockExecutor extended with optional `onCall` hook so the
retention-pruning tests can simulate keytool -exportkeystore's
file-write side effect (via the simulateExportSideEffect helper
that parses -destkeystore from args and writes a placeholder
.p12 file). Existing tests that don't set onCall behave
identically to before — backward compatible.
docs/deployment-atomicity.md L94 unchanged from today's text —
Bundle 1 doc-realignment hasn't shipped, so the "keytool snapshot;
rollback via keytool -delete + re-import" line was never softened.
Post-Bundle-8 the claim is honest (was aspirational pre-fix).
Verified locally (sandbox lacks staticcheck install due to disk
pressure; CI runs the full lint gate):
- gofmt -l ./internal/connector/target/javakeystore/ clean
- go vet ./internal/connector/target/javakeystore/ clean
- go build ./cmd/agent/... clean
- go test -race -count=1 ./internal/connector/target/javakeystore/
green (16 tests total: 9 pre-existing + 7 new)
Audit reference: cowork/deployment-target-audit-2026-05-02/RESULTS.md
Bundle 8.
Closes the #10 acquisition-readiness blocker from the 2026-05-01 issuer
coverage audit. Pre-fix, GlobalSign reloaded the mTLS cert/key from
disk on every API call (globalsign.go::getHTTPClient) and Entrust
loaded once in ValidateConfig with no rotation handling — both shapes
were broken for different reasons. Per-call disk reads under a 100-
cert renewal sweep meant 200 file opens / parses / tls.X509KeyPair
calls in flight, each adding 5–50ms of latency for nothing; the
single-load Entrust shape served stale credentials forever after a
cert rotation, requiring a process restart.
This commit:
- Adds a new shared package internal/connector/issuer/mtlscache/
with a Cache type holding a parsed tls.Certificate plus a
precomputed *http.Transport. RWMutex serialises reloads; reads
are lock-free in the hot path (read lock briefly held to copy
out the *http.Client pointer, then released — the HTTP request
itself happens with no lock held, per the audit prompt's anti-
pattern about holding the write lock across an API call).
- RefreshIfStale stats the cert file; if mtime advanced beyond
the last load, the keypair is re-parsed and the transport is
rebuilt. The fast path (mtime unchanged) takes the read lock
for the comparison and returns immediately. Double-checked-lock
pattern (read lock → stat → release → write lock → re-stat)
prevents two callers who observed the same stale mtime from
both reloading.
- Options.TLSConfigBuilder lets the caller customise the *tls.Config
built around the parsed leaf certificate. GlobalSign uses this
to inject the ServerCAPath-pinning RootCAs pool that
buildServerTLSConfig already produces; entrust uses the default
builder.
- New() performs the initial load so a broken cert path fails
fast at construction rather than at first API call.
- GlobalSign.Connector gains an mtls field. getHTTPClient now:
(1) preserves the test-mode short-circuit when httpClient has
a non-nil Transport;
(2) preserves the bare-default-client short-circuit when cert
paths aren't configured;
(3) lazy-builds the cache on the first call so the constructor
stays cheap;
(4) calls RefreshIfStale on every subsequent call.
The error wrap preserves the substring "client certificate" so
existing TestGlobalsign_GetHTTPClient_MTLSPathConfigured_LoadsKeyPair
keeps its assertion.
- Entrust.Connector gains an mtls field plus a new getHTTPClient
helper mirroring GlobalSign's shape. The three IssueCertificate /
RevokeCertificate / pollEnrollmentOnce sites that previously hit
c.httpClient.Do(req) directly now route through getHTTPClient,
which falls through to the test-injected client (same logic as
GlobalSign) and otherwise serves the cached mTLS client. The
legacy ValidateConfig flow that pre-built c.httpClient with its
own transport stays intact — its transport wins because
getHTTPClient short-circuits when c.httpClient.Transport != nil.
- Tests at internal/connector/issuer/mtlscache/cache_test.go cover:
* fail-fast on missing paths (constructor input validation)
* load on construction (positive + negative)
* NoReloadWhenMtimeStable — 100 RefreshIfStale calls, LoadedAt
must stay equal to the constructor's stamp (the load-bearing
regression guard against per-call disk reads)
* ReloadsOnMtimeAdvance — os.Chtimes forward, next refresh
must observe the new LoadedAt (the load-bearing regression
guard for rotation-without-process-restart)
* StatErrorBubbles — missing cert file surfaces as an error
rather than silently serving stale credentials
* ConcurrentNoRace — 100 goroutines × 50 iterations under
-race; no race detected, all calls succeed
* TLSConfigBuilderUsed — custom builder is invoked at New AND
on reload; verifies MinVersion=TLS1.3 takes effect
* ClientHonoursTimeout — Options.HTTPTimeout reaches the
constructed *http.Client
- docs/connectors.md GlobalSign + Entrust sections each gain an
"mTLS keypair caching (audit fix#10)" paragraph documenting the
steady-state caching, mtime-based rotation contract, and
operator workflow (mv -f new.crt /etc/certctl/.../client.crt).
Acquirer impact: removes the per-call disk-read latency floor and
makes operator-driven cert rotation a no-restart event. Combined
with audit fix#9's bounded scheduler concurrency, the renewal
sweep's hot path now has predictable steady-state cost: capN
concurrent goroutines, each reusing the cached keypair, no per-
call file I/O.
Verified locally:
- gofmt -l . clean
- go vet ./... clean
- staticcheck ./... clean
- go test -race -count=1 ./internal/connector/issuer/mtlscache/...
green (8 tests)
- go test -count=1 -short across globalsign / entrust / sectigo /
ejbca / mtlscache / connector packages: green
Audit reference: cowork/issuer-coverage-audit-2026-05-01/RESULTS.md
Top-10 fix#10. Closes the audit's full Top-10 list (fixes #1-10
all shipped to master).
Closes the #7 acquisition-readiness blocker from the 2026-05-01 issuer
coverage audit. Pre-fix, ACME RevokeCertificate at acme.go:L519-L529
returned the literal error "ACME revocation by serial not supported in
V1; provide certificate DER". RFC 8555 §7.6 genuinely requires the
cert DER bytes (not just the serial), but a CLM platform's job is to
abstract over that limitation. Operators routinely have only the
serial in hand: lost PEM, rotated key, GUI revoke action driven by a
row in the certs list.
This commit:
- Adds CertificateLookupRepo interface at the ACME connector boundary
(connector boundary, NOT a service/repository import — the connector
accepts whatever satisfies the shape). Production wiring in
cmd/server/main.go injects the postgres CertificateRepository; tests
inject a fake.
- Adds CertificateRepository.GetVersionBySerial(ctx, issuerID, serial)
+ interface declaration in repository/interfaces.go, returning the
certificate_versions row whose SerialNumber matches, scoped to the
issuer via JOIN on managed_certificates. Mirrors the existing
GetByIssuerAndSerial shape but returns the version (where PEMChain
lives). Per RFC 5280 §5.2.3 the issuer scope is required for
determinism.
- Adds SetCertificateLookup + SetIssuerID setters on *acme.Connector.
Mirror the pattern local.Connector already uses for OCSP responder
wiring. Both must be wired before serial-only revoke works;
unwired state falls back to a more actionable error pointing at the
wiring requirement (the historical "not supported" wording is
retired).
- Rewrites RevokeCertificate end-to-end: lookup → empty-PEM check →
pem.Decode → block.Type == "CERTIFICATE" check → ensureClient →
golang.org/x/crypto/acme.Client.RevokeCert(ctx, accountKey, der,
reasonCode). RFC 8555 §7.6 case 1 (revocation request signed with
account key) — the same account key issued the cert, so authority
is intrinsic. The not-found path returns an actionable operator-
facing error pointing at the local-store requirement.
- Adds mapRevocationReason translating RFC 5280 §5.3.1 reason strings
(unspecified, keyCompromise, cACompromise, affiliationChanged,
superseded, cessationOfOperation, certificateHold, removeFromCRL,
privilegeWithdrawn, aACompromise) into golang.org/x/crypto/acme.
CRLReasonCode. Accepts canonical camelCase + underscore_lower +
ALL_CAPS_UNDERSCORE. Nil reason → 0 (unspecified). Unknown reason
errors rather than silently demoting (operators rely on the reason
for compliance reporting).
- Wiring update in service/issuer_registry.go: SetACMECertLookup
setter on the registry; Rebuild type-asserts *acme.Connector and
calls SetCertificateLookup + SetIssuerID, mirroring the existing
*local.Connector branch. cmd/server/main.go calls
issuerRegistry.SetACMECertLookup(certificateRepo) immediately after
SetIssuanceMetrics — the postgres repo satisfies the interface via
GetVersionBySerial.
- Tests:
* acme_revoke_test.go (new): TestRevokeCertificate_NoCertLookupWired,
TestRevokeCertificate_NoIssuerIDWired,
TestRevokeCertificate_LookupReturnsNotFound (operator-facing
"may not have been issued through certctl" hint pinned),
TestRevokeCertificate_LookupArbitraryError,
TestRevokeCertificate_VersionPEMEmpty (corrupt-row guard),
TestRevokeCertificate_PEMMalformed_NoBlock,
TestRevokeCertificate_PEMMalformed_WrongType (PRIVATE KEY block
rejected as not a CERTIFICATE).
* TestMapRevocationReason_TableDriven: full RFC 5280 reason set
plus camelCase / underscore / ALL-CAPS variants plus
nil-reason and unknown-reason cases.
* acme_failure_test.go: renamed TestRevokeCertificate_AlwaysError
→ TestRevokeCertificate_UnwiredCertLookupFallback; the test
still exercises the same backward-compat branch but now
asserts the new "CertificateLookup wiring" error wording.
- Mock-repo updates (3 sites): mockCertificateRepository in
internal/integration/lifecycle_test.go, mockCertRepo in
internal/service/testutil_test.go, mockCertRepoWithGetError in
internal/service/shortlived_test.go each gain a GetVersionBySerial
implementation that mirrors the GetByIssuerAndSerial logic but
returns the version row.
- docs/connectors.md ACME section: new "Revocation by serial number"
subsection covering the workflow, the local-store requirement
(cert was issued through certctl, not imported), the reason-code
mapping with the three accepted spelling variants, and a pointer
to the audit reference.
Out of scope (intentional, per spec):
- Recovering the DER from outside the local cert store (CT logs,
CSR + signature reconstruction). If the cert wasn't issued through
certctl, revoke-by-serial via certctl isn't possible.
- Revocation via the cert's private key (RFC 8555 §7.6 case 2). The
account-key path covers all certctl-issued certs because the same
account key issued them.
- Pebble-backed integration test for the happy path. Pebble integration
is the right home for that — the unit tests in this commit pin all
failure-mode branches before the network call, and the wiring
branch in Rebuild is exercised by the existing
TestIssuerRegistryRebuild paths.
Verified locally:
- gofmt -l . clean
- go vet ./... clean
- staticcheck ./... clean
- go test -short -count=1 across connector, service, repository,
integration, api/middleware, api/handler: green
Audit reference: cowork/issuer-coverage-audit-2026-05-01/RESULTS.md
Top-10 fix#7.
Phase 2 of the #5 acquisition-readiness fix from the 2026-05-01 issuer
coverage audit. Phase 1 (commit 711265b) shipped the shared asyncpoll
package and refactored DigiCert as the reference. This commit applies
the same pattern to the remaining three async-CA connectors and adds
the operator-facing docs.
Per-connector refactors:
- Sectigo (sectigo.go): GetOrderStatus now wraps pollEnrollmentOnce in
asyncpoll.Poll. The collectNotReady sentinel (cert approved by SCM
but not yet retrievable from the collect endpoint) maps to
StillPending and rides the backoff schedule rather than the prior
"return pending immediately" branch. Added isPermanentStatusError
helper to distinguish transient HTTP errors (5xx / 429 / network)
from permanent ones (4xx / parse failure) — the wrapped checkStatus
errors get triaged at the poll closure boundary.
- Entrust (entrust.go): GetOrderStatus wraps pollEnrollmentOnce. The
AWAITING_APPROVAL status maps to StillPending; operators using
approval-pending workflows where humans approve enrollments should
bump CERTCTL_ENTRUST_POLL_MAX_WAIT_SECONDS to 86400 (24h) so a
single scheduler tick can wait through the approval window. The
default 10-minute deadline matches the other three connectors.
- GlobalSign (globalsign.go): GetOrderStatus wraps pollCertificateOnce.
GlobalSign tracks orders by serial number rather than order ID, but
the polling shape is identical to the other three. Status-code
triage matches DigiCert: 4xx (not 429) is permanent, 5xx / 429 /
network is transient.
Per-connector Config field added:
- DigiCert.PollMaxWaitSeconds (env CERTCTL_DIGICERT_POLL_MAX_WAIT_SECONDS)
- Sectigo.PollMaxWaitSeconds (env CERTCTL_SECTIGO_POLL_MAX_WAIT_SECONDS)
- Entrust.PollMaxWaitSeconds (env CERTCTL_ENTRUST_POLL_MAX_WAIT_SECONDS)
- GlobalSign.PollMaxWaitSeconds (env CERTCTL_GLOBALSIGN_POLL_MAX_WAIT_SECONDS)
internal/config/config.go env-var loaders updated for all four. Default
is 600 seconds (10 minutes); zero falls back to the asyncpoll package
default.
Test-helper updates: every existing test that exercises the pending
branch (collectNotReady, AWAITING_APPROVAL, status="pending", etc.)
now sets PollMaxWaitSeconds=1 in its Config so the test doesn't block
on the production-default 10-minute deadline. Tests that exercise
permanent-error branches (404, 401, malformed JSON, etc.) continue
to return immediately.
Test sites updated:
- buildSectigoConnector helper + GetOrderStatus_CollectNotReady test
- buildEntrustConnector helper + GetOrderStatus_Pending test
- buildGlobalsignConnector helper + GetOrderStatus_Pending test +
the GetHTTPClient_NoMTLSCertPaths test (network failure now rides
the backoff schedule rather than returning immediately)
Documentation:
- docs/async-polling.md: new operator reference covering the backoff
schedule, status-code triage, the four env vars, failure modes, and
where the implementation lives. Audit blocker citation included.
- docs/connectors.md: per-issuer sections for DigiCert, Sectigo,
Entrust, GlobalSign each gain the PollMaxWaitSeconds env var row
and a cross-link to async-polling.md.
Lint cleanup: simplified the isPermanentStatusError branch to satisfy
staticcheck S1008 (single-line return for a final boolean check).
Verified locally:
- gofmt -l . clean
- go vet ./... clean
- staticcheck ./... clean
- golangci-lint run --timeout 5m ./... → 0 issues
- go test -short -count=1 across all 4 connector packages + config + asyncpoll: green
Audit reference: cowork/issuer-coverage-audit-2026-05-01/RESULTS.md
Top-10 fix#5 — Phase 2.
Closes the #1 acquisition-readiness blocker from the 2026-05-01 issuer
coverage audit. The production New() constructor previously hardcoded
&stubClient{}, which returned "AWS SDK client not initialized (stub)" on
every method. Tests passed green via NewWithClient mock injection — a
path the production constructor never took. AWSACMPCA was wired into
the factory, the seed file, the test suite, and marketing collateral
but did not actually issue, retrieve, or revoke certificates.
This commit:
- Adds aws-sdk-go-v2/{config,service/acmpca,aws} to go.mod (with
acmpca/types as a sub-package). go mod tidy could not be completed
in the sandbox due to virtiofs concurrent-open-file ceiling on the
module cache; the require blocks were arranged manually so the three
directly-imported packages are non-indirect. Build, vet, staticcheck,
and the full test suite are green; operator should run `go mod tidy`
on the workstation to confirm cosmetic ordering before pushing.
- Implements sdkClient wrapping *acmpca.Client with local input/output
type translation. Each method translates the connector's local input
type to the SDK's typed input, calls the SDK, and translates the SDK
output back to the local output type. aws-sdk-go-v2 types do not
leak out of the awsacmpca package.
- Deletes stubClient (the four "AWS SDK client not initialized (stub)"
methods). After this commit, there is no fall-back stub; production
New() always wires the SDK.
- Rewrites New() to load credentials via awsconfig.LoadDefaultConfig
with awsconfig.WithRegion(config.Region) and construct the SDK client
via acmpca.NewFromConfig. Returns (*Connector, error). When config
is nil or config.Region is empty, New defers SDK loading; ValidateConfig
builds the client lazily on the first successful validation. This
preserves the test pattern of New(nil, logger) → ValidateConfig.
- Wires acmpca.NewCertificateIssuedWaiter (5-minute default timeout)
inside sdkClient.IssueCertificate so the connector's two-call
pattern (IssueCertificate → GetCertificate) sees synchronous-via-
waiter semantics. The waiter is hidden from the ACMPCAClient
interface so mock implementations stay simple.
- Maps RFC 5280 revocation reasons to acmpcatypes.RevocationReason
via the existing mapRevocationReason helper plus a cast at the
sdkClient.RevokeCertificate boundary.
- Updates the issuerfactory.NewFromConfig call site at factory.go:L88
for the new (*Connector, error) signature; the factory's outer
signature already returns (issuer.Connector, error) so the change
is local.
- Adds nil-client guards on the four client-using connector methods
(IssueCertificate, RevokeCertificate, GetCACertPEM, plus the
RenewCertificate path via IssueCertificate). When the connector is
used before ValidateConfig has been called, these methods fail-fast
with a "client not initialized" sentinel error instead of panicking.
- Fixes the copy-paste env-var doc-comments at awsacmpca.go:L41,L45
(CERTCTL_GOOGLE_CAS_PROJECT / CERTCTL_GOOGLE_CAS_CA_ARN →
CERTCTL_AWS_PCA_REGION / CERTCTL_AWS_PCA_CA_ARN). The actual config
loader at internal/config/config.go:L1556-L1561 already used the
correct env-var names; only the doc-comments were wrong.
- Updates the package doc-comment at awsacmpca.go:L1-L36 to clarify
the synchronous-via-waiter behavior (issuance is asynchronous at
the API level; the waiter inside sdkClient.IssueCertificate hides
the asynchrony).
- Adds TestNew_ProductionPath/ValidConfigBuildsRealClient: calls
production New() (NOT NewWithClient) with a valid config, asserts
err is nil, then calls IssueCertificate with a bogus CSR and asserts
the resulting error is the expected PEM-decode error rather than
the deleted stubClient's "client not initialized" sentinel. This is
the regression-marker test the audit's D11 blocker called out as
missing — if anyone re-introduces a stub-style placeholder from
production New() in the future, this test fails.
- Adds TestNew_ProductionPath/NilConfigDefersClientInit: documents the
lazy-init contract for the New(nil, logger) → ValidateConfig pattern.
- Adds TestNew_ProductionPath/ValidateConfigBuildsClientLazily: verifies
that ValidateConfig wires the SDK client when New was called with
nil config.
- Adds TestNew_ProductionPath/{Revoke,GetCAPEM}BeforeInitFailsFast:
verifies the nil-client guards on the other client-using methods.
- Adds TestNew_ErrorPaths covering AccessDeniedException-shaped errors,
transient 5xx errors, and ctx-cancel propagation via the existing
mockACMPCAClient.
- Updates docs/connectors.md:L490-L555 with: the synchronous-via-waiter
behavior, a complete IAM policy example scoped to the four ACM PCA
actions, a worked POST /api/v1/issuers example, and a troubleshooting
section with three known failure modes (AccessDeniedException,
ResourceNotFoundException, waiter timeout).
Live AWS integration testing is intentionally not added: ACM PCA is a
Pro-tier feature in localstack and the existing interface-mock tests
cover correctness end-to-end. Operators with AWS credentials can
validate by following the worked example in docs/connectors.md.
Audit reference: cowork/issuer-coverage-audit-2026-05-01/RESULTS.md
Top-10 fix#1 (Part 3, narrative section).
EST RFC 7030 hardening master bundle Phase 12 — comprehensive operator-
facing documentation for the Phases 1-11 backend work that shipped on
2026-04-29.
NEW docs/est.md (19 sections, ~810 lines): Concepts (host vs user
enrollment, profile-driven policy, multi-profile dispatch); 5-minute
single-profile Quick start with curl + openssl recipes; Multi-profile
dispatch (CERTCTL_EST_PROFILES=corp,iot,wifi setup with PathID rules
enforced at boot); Authentication modes (mTLS / Basic / both / empty
with cross-check semantics); RFC 9266 channel binding (failure-mode
HTTP mapping table — ErrChannelBindingMissing/Mismatch/NotTLS13 →
400/409/426); WiFi/802.1X recipe with end-to-end FreeRADIUS integration
(EAP-TLS supplicant config, mods-available/eap tls-common block, CRL
distribution endpoint cross-ref, troubleshooting playbook); IoT bootstrap
recipe (factory provisioning, first boot, steady-state renewal,
compromise/decommission via bulk-revoke, recommended cert lifetimes
per master prompt §7.7); serverkeygen for resource-constrained devices
(CMS EnvelopedData wrap, RSA-only at this revision, zeroize discipline,
Phase-1 cross-check refusing _SERVERKEYGEN_ENABLED=true with empty
_PROFILE_ID); HSM-backed CA signing for EST cross-ref (signer interface
seam); Operator GUI tabbed surface tour (/est: Profiles / Recent
Activity / Trust Bundle); CLI + 6 MCP tools; Renewal device-driven
model (RFC 7030 §4.2.2 mandate, renewal-trigger ratios for laptops/IoT,
operator-push via webhook); Troubleshooting matrix (one row per typed
audit-action constant in internal/service/est_audit_actions.go);
TLS 1.2 reverse-proxy runbook cross-ref (channel-binding caveat
explained); Threat model (load-bearing properties: trust-anchor reload
fail-safety, per-profile counter isolation, mTLS cross-profile bleed
defense, source-IP limiter process-locality, server-keygen heap
residency, HTTP Basic in-process-only, legacy-anonymous-default
back-compat carve-out); V3-Pro deferrals; Appendix A (libest sidecar
reproducer + 5 integration test names); Appendix B (Cisco IOS 15.x +
16.x + Apple MDM + OpenWRT + libest <v3.0 wire-format quirks tested
in internal/api/handler/cisco_ios_quirks_test.go).
UPDATED docs/architecture.md: new "EST Server (RFC 7030) — Production
Deployment" section under the existing baseline EST section. Mermaid
diagram of multi-profile dispatch + mTLS sibling route + per-profile
gate ordering + audit + GUI + SIGHUP-equivalent reload. Existing
authentication paragraph updated with forward-ref to the hardening
section. Audit paragraph updated to enumerate the 13 typed est_*
action codes operators grep on. Trust-anchor reload semantics +
libest interop tested in CI both called out.
UPDATED README.md::Enrollment Protocols: replaced the one-line EST
row with the full production-grade surface description matching the
SCEP analog. Cross-references docs/est.md.
UPDATED docs/connectors.md::EST/SCEP Integration: extended the
EST-or-SCEP shared paragraph to point at the per-profile env-var
form for both protocols + linked the new architecture.md section.
NEW "Multi-profile EST dispatch + production hardening" subsection
mirrors the SCEP equivalent: 9-row env-var table, cross-ref to
docs/est.md.
G-3 docs-drift CI guard reproduced locally clean — every CERTCTL_EST_*
mention in docs maps back to internal/config/config.go, and every
defined env var is documented. The `<NAME>` placeholder convention
matches the SCEP idiom so the docs grep doesn't extract per-deploy
profile names as phantom env vars. No new env vars introduced —
this is a pure docs commit.
Closes the eleven gaps identified in the pre-v2.1.0 audit of the SCEP
RFC 8894 + Intune master bundle (cowork/scep-bundle-gap-closure-prompt.md).
Constitutional rule from cowork/CLAUDE.md::Operating Rules — 'Always
take the complete path, not the easy path' — drove this closure: each
gap was a load-bearing wire that crossed multiple layers (config →
validator → service wire-up → tests → docs) and shipping the bundle
without them would have produced lying-field footguns where operator-
visible config options stored values without affecting behavior.
WHAT LANDS:
Phase A — Clock-skew tolerance (master prompt §15 hazard closure)
internal/scep/intune/challenge.go: ValidateChallenge migrated from
positional args to ValidateOptions{} struct; new ClockSkewTolerance
field with default 0 (strict). 24 call sites updated mechanically.
Asymmetric application: now+tolerance >= iat AND now-tolerance < exp.
internal/config/config.go: SCEPIntuneProfileConfig.ClockSkewTolerance
default 60s + Validate() refusal when >= ChallengeValidity.
cmd/server/main.go: SetIntuneIntegration signature extended;
per-profile env-var loader honors CERTCTL_SCEP_PROFILE_<NAME>_INTUNE_CLOCK_SKEW_TOLERANCE.
internal/service/scep.go: intuneClockSkew field + IntuneStatsSnapshot
surfaces clock_skew_tolerance_ns. web/src/api/types.ts mirrors.
4 new tests in challenge_test.go covering accept-within-tolerance,
reject-beyond-tolerance, accept-expired-within-tolerance,
negative-treated-as-zero defensive normalization.
docs/scep-intune.md updated with the new env var + time-bounds rule.
Phase B — unknown-version-rejected golden test
internal/scep/intune/golden_helper_test.go: goldenUnknownVersionPayload
helper + signGoldenChallengeAny generic signer.
challenge_golden_test.go: TestGoldenChallenge_UnknownVersionRejected
uses an in-process ECDSA fixture (the on-disk PEM was generated with
a Go-stdlib version that produces different ecdsa.GenerateKey bytes
from the current call). TestRegenerateGoldenFixtures emits the new
unknown_version fixture file too.
Phase C — Two named Intune e2e tests
internal/api/handler/scep_intune_e2e_test.go:
TestSCEPIntuneEnrollment_RateLimited_E2E (cap=2 + 3 attempts; 3rd
returns FAILURE+badRequest with rate_limited counter ticked)
TestSCEPIntuneEnrollment_TrustAnchorSIGHUPReload_E2E (rotate
on-disk PEM + holder.Reload(); old-key challenge fails with
badMessageCheck; signature_invalid counter ticked)
intuneE2EFixture struct extended with trustHolder + trustPath fields
so tests can rotate.
Phase D — Four new ChromeOS hermetic tests (10 total now)
internal/api/handler/scep_chromeos_test.go:
_RAKeyMismatch — PKIMessage encrypted to wrong RA cert; handler
rejects without reaching service.
_3DESBackwardCompat — RFC 8894 §3.5.2 legacy fallback verified.
_RSACSR + _ECDSACSR — explicit matrix-pair pinning.
buildTestECDSACSR helper for ECDSA P-256 CSR construction;
tripleDESCBCEncrypt mirrors aesCBCEncrypt for 3DES-CBC;
assertChromeOSPositiveCertRep shared assertion.
Phase E — Per-profile counter isolation test
internal/api/handler/scep_profile_counter_isolation_test.go:
TestSCEPHandler_PerProfileIntuneCountersIsolated wires two
SCEPService instances + drives distinct PKIMessages + asserts
counter isolation. Guards against a future cmd/server/main.go
refactor that shares a *intuneCounterTab across profiles.
buildPerProfileIntuneFixture parameterized helper.
Phase F — Server-boot regression tests
cmd/server/preflight_scep_intune_test.go: 3 named tests covering
disabled-backward-compat, broken-config-with-PathID, expired-cert
refusal. preflightSCEPIntuneTrustAnchor signature extended with
pathID arg so error messages carry PathID= for operator log-grep.
Phase G — docs/connectors.md
Four new subsections under §EST/SCEP Integration: multi-profile
dispatch + mTLS sibling route + Intune Connector dispatcher + SCEP
probe in network scanner. Each has a one-paragraph operator
explanation + an env-var or endpoint table.
Phase H — Coverage uplift
internal/service/scep_probe_persist_test.go: 5 unit tests on
persistProbeResult (nil-safe + nil-repo-safe + repo-error swallow +
nil-logger guard) + ListRecentSCEPProbes (empty-slice-not-nil + repo
pass-through) + describeCertAlgorithm (RSA/ECDSA/QF1008-nil-curve
defensive branch/Ed25519/DSA/empty). CI gates (service ≥70, handler
≥75) PASS at 70.9% / 79.3%.
Phase I — deploy/test integration variant
deploy/test/scep_intune_e2e_test.go (//go:build integration):
TestSCEPIntuneEnrollment_Integration + _RateLimited_Integration
against the live docker-compose certctl container. Skip-when-
stack-missing semantics so sandbox + CI both work.
deploy/docker-compose.test.yml: new e2eintune SCEP profile env
vars + bind-mount of deploy/test/fixtures/.
deploy/test/fixtures/README.md: documents the deterministic trust
anchor regeneration recipe.
VERIFICATION (sandbox):
gofmt -d — clean for all changed files
staticcheck — clean for intune + handler + config + service +
cmd/server packages
go vet — clean for the same packages
go test -short — green for intune (95.3% cov), service (70.9%),
handler (79.3%), config (94.0%), cmd/server (boot
path; my preflight tests cover the directly-
testable function), pkcs7 (80.5% informational)
DEFERRED (per closure prompt §7 out-of-scope):
- V3-Pro Conditional Access gating + Microsoft Graph integration
- Standalone certctl-scan CLI binary
- OCSP rate-limiting, OCSP stapling, delta CRLs
Spec preserved at cowork/scep-bundle-gap-closure-prompt.md;
journal at cowork/scep-rfc8894-intune/progress.md (audit-closure
section appended).
SCEP RFC 8894 + Intune master bundle — Phase 6 of 14.
Closes Half 1 of the bundle (Phases 0-6). The certctl SCEP server now
ships full RFC 8894 wire format (EnvelopedData decrypt + signerInfo POPO
verify + CertRep PKIMessage builder), tested against ChromeOS-shape
hermetic E2E requests, with multi-profile dispatch and must-staple
per-profile policy. Half 2 (Phases 7-12) adds the Microsoft Intune
dynamic-challenge layer; Phase 6.5 (mTLS sibling route) is independently
shippable as an opt-in enterprise-procurement feature.
README.md
* Standards & Revocation table SCEP row updated to mention full RFC
8894 wire format (EnvelopedData decryption, signerInfo POPO
verification, CertRep PKIMessage builder), PKCSReq + RenewalReq +
GetCertInitial messageType dispatch, multi-profile dispatch
(/scep/<pathID>), per-profile RA cert + key, MVP fall-through for
lightweight clients.
* Enrollment protocols paragraph extended with the same scope, plus
a link to docs/legacy-est-scep.md for the operator + device-
integration guide.
docs/architecture.md
* SCEP wire format paragraph rewritten to describe the two paths
(RFC 8894 first, MVP fall-through), the messageType dispatch
table, the EnvelopedData decrypt (constant-time PKCS#7 unpad
closing the padding-oracle leg), the SET-OF Attribute
re-serialisation quirk per RFC 5652 §5.4, and the CertRep
PKIMessage shape (cert chain encrypted to req.SignerCert, NOT
the RA cert).
* SCEP service interface updated to show the three new
*WithEnvelope variants alongside the legacy PKCSReq method.
* Added 'Capabilities advertised', 'Multi-profile dispatch', and
'Must-staple per profile' subsections covering the RFC 7633
extension policy.
docs/connectors.md
* EST/SCEP Integration section extended with the per-profile
issuer-binding env-var form (CERTCTL_SCEP_PROFILE_<NAME>_ISSUER_ID).
* New SCEP RA cert + key paragraph pointing operators at the
legacy-est-scep.md openssl recipe + ChromeOS Admin Console
pointer + must-staple per-profile policy.
cowork/CLAUDE.md::Active Focus
* 2026-04-29 SCEP RFC 8894 + Intune master bundle status updated
to 'HALF 1 COMPLETE (Phases 0-5 of 14 SHIPPED)' with the full
chain of commit SHAs (105c307 → fdd424b → a546a1b → b540d44 +
7b40361 → b33b843).
* Unreleased-on-master bullet extended to enumerate the SCEP
bundle deliverables alongside the CRL/OCSP work, plus the new
SCEP env vars (CERTCTL_SCEP_RA_*_PATH, CERTCTL_SCEP_PROFILES,
CERTCTL_SCEP_PROFILE_<NAME>_*).
cowork/CLAUDE.md::Architecture Decisions
* Added a new bullet for 'SCEP RFC 8894 native implementation
(post-2026-04-29)' covering the load-bearing design decisions:
EnvelopedData decrypt with constant-time padding strip, the
SET-OF re-serialisation quirk, the dispatch-on-messageType
pattern, multi-profile dispatch, the MVP fall-through contract,
capability advertisement, ChromeOS-shape E2E test, must-staple
per-profile.
Smoke test against fresh make docker-up SKIPPED in this commit — the
sandbox doesn't have Docker available. The full smoke recipe is in
the Phase 6.3 prompt; CI runs the full integration suite via the
standard docker-compose.test.yml workflow on the next push.
Verification (sandbox):
* gofmt + go vet + staticcheck clean for all touched paths.
* go test -short -count=1 green across api/handler / api/router /
service / pkcs7 / connector/issuer/local / domain / cmd/server.
* Coverage held: handler 79.0% / service 73.2% / pkcs7 80.5% /
config 96.0% / domain 88.6% / router 100%.
Phase 6 of 14 in SCEP RFC 8894 + Intune master bundle.
Half 1 COMPLETE. Half 2 (Phases 7-12, Microsoft Intune dynamic-
challenge layer) ready to begin.
Pre-U-2 the published `ghcr.io/shankar0123/certctl-server` image
shipped with `HEALTHCHECK CMD curl -f http://localhost:8443/health`.
The server has been HTTPS-only since the v2.2 HTTPS-Everywhere milestone
(`cmd/server/main.go::ListenAndServeTLS`, no plaintext fallback, TLS
1.3 pinned), so the probe failed on every interval and Docker marked
the container `unhealthy` indefinitely. Operators inside docker-
compose / Helm / the example stacks were unaffected — compose overrides
the HEALTHCHECK with `--cacert + https://`, Helm uses explicit
`httpGet` probes that ignore Docker's HEALTHCHECK, and every example
compose file overrides with `curl -sfk https://localhost:8443/health`.
But anyone running bare `docker run` / Docker Swarm / Nomad / ECS —
exactly the "I just pulled the published image" path — saw permanent
`unhealthy` status and (depending on orchestrator policy) a restart-
loop. (Audit: cat-u-healthcheck_protocol_mismatch in
coverage-gap-audit-2026-04-24-v5/unified-audit.md.)
Recon for U-2 surfaced two adjacent bugs from the same v2.2 milestone
gap, both bundled into this commit because they share the same root
cause and the same operator surface:
1. Helm chart `server.readinessProbe.httpGet.path` pointed at
`/readyz`, the kube-flavored convention. The certctl server
doesn't register `/readyz` (only `/health` and `/ready` are
wired and bypass the auth middleware — see
internal/api/router/router.go:81 and cmd/server/main.go:920).
K8s readiness probes therefore got 401 (api-key auth rejection)
or 404 (when auth was disabled), pods stayed `NotReady`
indefinitely, and Helm rollouts stalled.
2. The agent image (`Dockerfile.agent`) had no HEALTHCHECK at all,
so bare-`docker run` agents got zero health signal. The
compose override at `deploy/docker-compose.yml:173` called
`pgrep -f certctl-agent` against the agent image, but the
agent image didn't ship `procps` — pgrep was missing too. The
compose probe was a latent always-fail.
We fixed all three with the audit-recommended shape (option (a) — `-k`)
plus three structural backstops:
Files changed:
Phase 1 — Dockerfile fix:
- Dockerfile: HEALTHCHECK switched from `curl -f http://localhost:8443/
health` to `curl -fsk https://localhost:8443/health`. `-k`
(insecure) is acceptable because the probe is localhost-to-localhost:
the same process serving the cert is being probed, no network hop.
Pinning `--cacert` is not viable for the published image because
the bootstrap cert is per-deploy (generated into the `certs` named
volume on first up; operator-supplied via Helm's `existingSecret`
or cert-manager). Long-form docblock cross-references the audit
closure, the compose vs Helm vs examples coverage matrix, and the
CI guardrail.
- Dockerfile.agent: added HEALTHCHECK using `pgrep -f certctl-agent`
matching the compose pattern. Added `procps` to the runtime apk
install — fixes both the new image-level HEALTHCHECK AND the
pre-existing compose probe that was silently failing.
Phase 2 — Helm readiness probe path:
- deploy/helm/certctl/values.yaml: server.readinessProbe.httpGet.path
changed from `/readyz` to `/ready`. Liveness probe path
(`/health`) was correct and is unchanged. Probes block now carries
an explanatory comment naming the registered no-auth probe routes
and the U-2 closure rationale.
Phase 3 — Image-level integration tests:
- deploy/test/healthcheck_test.go (new, //go:build integration):
TestPublishedServerImage_HealthcheckSpecUsesHTTPS builds the server
image, inspects `Config.Healthcheck.Test` via `docker inspect`,
and asserts the array contains `https://localhost:8443/health` and
`-k`, and does NOT contain `http://localhost:8443/health`
(positive + negative regression contracts).
TestPublishedAgentImage_HealthcheckSpecExists builds the agent image
and asserts the HEALTHCHECK uses `pgrep` against `certctl-agent`.
Both tests `t.Skip` cleanly when docker isn't available (sandbox /
CI without docker-in-docker) — verified locally: tests skip with the
diagnostic and the suite returns PASS.
TestPublishedServerImage_HealthcheckTransitionsToHealthy is a
documented `t.Skip` placeholder until the harness wires a sidecar
postgres for image-level smoke; the spec-level tests above cover the
audit-flagged regression.
Phase 4 — CI guardrail:
- .github/workflows/ci.yml: new "Forbidden plaintext HEALTHCHECK
regression guard (U-2)" step. Scoped patterns catch
`HEALTHCHECK.*http://` and `curl -f http://localhost:8443/health`
in any `Dockerfile*`. Comment lines exempt; docs/upgrade-to-tls.md
out of scope (the post-cutover invariant string at line 182 is
intentionally a documented expected-failure assertion). Verified
locally on the real tree (passes) and against synthetic regressions
(each fires the guard).
Phase 5 — Docs sweep:
- docs/connectors.md: 15 stale curl examples updated from
`http://localhost:8443/...` to `https://localhost:8443/...` with
`--cacert "$CA"` injected on every site. Added a one-time
introductory note documenting the `$CA` extraction with
`docker compose ... exec ... cat /etc/certctl/tls/ca.crt`,
matching the pattern in docs/quickstart.md. Pre-U-2 these examples
silently failed against the HTTPS listener.
Phase 6 — Release surface:
- CHANGELOG.md: appended U-2 section to the existing [unreleased]
block (immediately below the G-1 entry). Sections: explanatory
blockquote covering all three bugs (primary + 2 adjacent), Fixed,
Added, Changed.
Verification (all gates pass):
- go build ./... — clean
- go vet ./... — clean
- go vet -tags integration ./deploy/test/ — clean
- go test -short ./... — every package green
- go test -tags integration -v -run TestPublishedServerImage|TestPublishedAgentImage ./deploy/test/ —
three tests SKIP cleanly with "docker not available" diagnostic
- helm lint deploy/helm/certctl/ — clean
- helm template smoke render — succeeds; rendered Deployment carries
`path: /ready` and zero `/readyz` matches
- python3 yaml.safe_load on api/openapi.yaml — parses
- govulncheck ./... — no vulnerabilities in our code
- CI guardrail mirror: clean on real tree, fires on synthetic
regression patterns
Out of scope (intentionally untouched):
- cmd/server/main.go::ListenAndServeTLS — HTTPS-only is correct,
this finding does NOT propose adding back a plaintext listener.
- deploy/docker-compose.yml:126 HEALTHCHECK — already correct.
- deploy/docker-compose.test.yml HEALTHCHECK blocks — already correct.
- All 5 examples/*/docker-compose.yml HEALTHCHECK overrides — already
correct (they ALSO use `-fsk https://localhost:8443/health`).
- Helm server.livenessProbe.httpGet — already uses `scheme: HTTPS` +
`path: /health`, correct.
- docs/upgrade-to-tls.md:182 `curl ... http://localhost:8443/health`
invariant line — that's the expected-failure assertion for the
post-cutover state ("plaintext is gone, expect Connection refused");
intentionally left intact.
- Go production code — this is purely a deploy-image / probe / docs /
Helm-chart fix.
Refs: coverage-gap-audit-2026-04-24-v5/unified-audit.md
§2 P1 cluster, cat-u-healthcheck_protocol_mismatch
Audit recommendation followed verbatim: 'change Dockerfile:80
to CMD curl -kf https://localhost:8443/health'.
Closes the remaining P1 gaps from coverage-gap-audit.md (M-001/M-002/M-003/M-006)
on top of the C-001/C-002 ownership + agent-FK contract fixes landed in
a53a4b8. The work lands as a single commit spanning server, docs, tests,
and the React client.
M-002 — Named API keys with per-key actor propagation
* Migration 000014 adds the 'api_keys' table (id, name, hash,
principal, role, created_at, last_used_at, disabled_at) so every
credential carries an identifiable principal instead of the
opaque 'anonymous'/'api-key' sentinel.
* Auth middleware now rotates through configured keys, performs
constant-time hash comparison, stamps 'last_used_at', and emits
an actor struct via contextWithActor(). The audit middleware,
bulk-revocation handler, approval handlers, and MCP tool layer
now read the principal off the context and persist it on every
audit_events row.
* Regression coverage:
- internal/api/middleware/audit_test.go — actor propagation,
principal redaction for disabled keys, anonymous fallback for
unauthenticated endpoints.
- internal/api/handler/bulk_revocation_handler_test.go,
job_handler_test.go — principal-on-audit assertions.
M-003 — Authorization gates (Phase B)
* Approval handler rejects self-approval / self-rejection with 403
when the actor principal equals the job's requested_by field.
* Bulk revocation is gated behind the 'admin' role; operators and
viewers receive 403.
* Regression coverage:
- internal/service/job_test.go — TestApproveJob_NotSelf,
TestRejectJob_NotSelf.
- internal/api/handler/bulk_revocation_handler_test.go —
TestBulkRevoke_RequiresAdmin, TestBulkRevoke_AdminSucceeds.
M-006 — RFC-compliant CRL/OCSP on the unauthenticated .well-known mux
* Per RFC 8615, relying parties cannot reasonably be asked to
authenticate against the issuing certctl instance to retrieve
revocation material. CRL and OCSP move off the authenticated
'/api/v1/crl*' and '/api/v1/ocsp/*' paths onto:
GET /.well-known/pki/crl/{issuer_id}
Content-Type: application/pkix-crl (RFC 5280 §5)
GET /.well-known/pki/ocsp/{issuer_id}/{serial}
Content-Type: application/ocsp-response (RFC 6960)
* Non-standard JSON CRL shape is removed; only DER is served.
* Short-lived certificate exemption (profile TTL < 1h → skip
CRL/OCSP) is preserved; the response simply omits the serial.
* Routes are registered on the unauthenticated 'finalHandler' mux
in cmd/server/main.go alongside EST ('/.well-known/est/*') and
SCEP ('/scep'). Legacy authenticated paths return 404.
* Regression coverage:
- internal/api/handler/certificate_handler_test.go — content
type, DER parseability, 404 for unknown issuer.
- internal/api/handler/adversarial_path_test.go — unauthenticated
access asserted for CRL, OCSP, EST, SCEP.
- internal/api/router/router_test.go — route-table assertion
that '.well-known/pki/*', '.well-known/est/*', and '/scep' are
mounted on the unauthenticated branch.
M-001 — Auto-closed by M-002
EST and SCEP were already registered on the unauthenticated
'finalHandler' mux; the router comment at
internal/api/router/router.go:247 now matches reality. The
adversarial-path tests above lock the behavior in.
Verification (all gates green):
* go vet ./... — clean
* go build ./... — ok
* go test -short ./... (55+ packages) — all pass
* web/ : npm test (225 Vitest tests) — all pass
* web/ : npx tsc --noEmit — clean
* grep sweep for '/api/v1/(crl|ocsp)' — 13 surviving hits,
all intentional M-006 tombstone/relocation comments.
Documentation:
* coverage-gap-audit.md — status flips M-001/M-002/M-003/M-006 →
Fixed, with per-finding resolution paragraphs citing regression
test IDs. (Audit file lives outside this repo; see cowork root.)
* CLAUDE.md Project Status line updated with the auth-unification
closure note.
* docs/features.md, docs/architecture.md, docs/quickstart.md,
docs/concepts.md, docs/connectors.md, docs/test-env.md,
docs/testing-guide.md, docs/compliance-*.md, docs/demo-advanced.md
— refreshed for the new '.well-known/pki/*' namespace and named
API keys.
* api/openapi.yaml — documents the new unauthenticated endpoints
and removes the legacy '/api/v1/crl*' + '/api/v1/ocsp/*' paths.
.gitignore: adds '/.gocache/' and '/.gomodcache/' for the session-
scoped Go caches so they never enter the tree.
The GlobalSign Atlas HVCA connector previously used InsecureSkipVerify:true
on its mTLS TLS config, disabling server certificate validation and
defeating the purpose of the client-side mTLS handshake. This was a
CWE-295 Improper Certificate Validation vulnerability silently degrading
trust on every production call to GlobalSign's signing API.
Remediation (per H-5 audit finding, Lens 4.4):
- Remove InsecureSkipVerify from all three http.Client construction sites
(ValidateConfig, getHTTPClient, and legacy initialisation path).
- Introduce buildServerTLSConfig() helper that constructs tls.Config with
MinVersion: tls.VersionTLS12 (addresses adjacent L-1 recommendation).
- New optional config field `server_ca_path` (env:
CERTCTL_GLOBALSIGN_SERVER_CA_PATH). When unset the connector trusts the
system root CA bundle (correct default for GlobalSign's publicly-trusted
HVCA endpoints). When set the bundle is loaded via x509.NewCertPool() +
AppendCertsFromPEM, and only those roots are trusted (supports private
HVCA deployments and defence-in-depth root pinning).
- Error wrapping chain: "failed to read server CA bundle at %s" and
"no valid PEM certificates found in server CA bundle at %s" surface
config problems at ValidateConfig time instead of silently failing at
request time.
Docs, config, service env-seed, and GUI issuer type definition updated to
expose the new field. Tests: 9 dead `InsecureSkipVerify: true` client
TLSClientConfig blocks (no-ops against httptest.NewServer plain-HTTP)
replaced with bare http.Client; new TestGlobalSign_ServerTLSConfig covers
pinned-CA trust, untrusted-server rejection, missing-file and invalid-PEM
error paths.
Verification:
- go build ./... clean
- go vet ./... clean
- go test -race ./internal/connector/issuer/globalsign/... ./internal/config/... ./internal/service/... ok
- go test ./... (excluding testcontainers-gated repo layer) ok
- golangci-lint run ./... 0 issues
- govulncheck ./... 0 reachable vulns
- Per-layer coverage: service 68.7% (≥55), handler 83.6% (≥60), domain 82.0% (≥40), middleware 63.8% (≥30)
- globalsign package coverage: 75.9%
- Invariant sweep: 0 InsecureSkipVerify references remain in globalsign
package (only a test-file comment documenting the removal).
Add three new issuer connectors completing commercial and open-source CA
coverage. Entrust uses mTLS client certificate auth with sync/async
issuance. GlobalSign Atlas uses mTLS + API key/secret dual auth with
serial-based tracking. EJBCA supports dual auth (mTLS or OAuth2) for
self-hosted Keyfactor CAs.
Each connector implements the full issuer.Connector interface (9 methods),
includes httptest-based unit tests (~14 each), and follows established
patterns (injectable HTTP clients, RFC 5280 revocation reason mapping,
CRL/OCSP delegated to CA).
Also includes: issuer factory cases, env var seeding, config structs,
domain types, seed data (3 rows, all disabled), OpenAPI enum updates,
frontend issuer catalog entries with config fields, and full docs
(connectors.md, architecture.md, features.md, README).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Enforce certificate profile crypto constraints across all 5 issuance paths
(renewal, agent CSR, EST, SCEP). ValidateCSRAgainstProfile() rejects CSRs
with key algorithm/size that don't match profile rules. MaxTTL enforcement
caps certificate validity per issuer connector (Local CA, Vault, step-ca
enforce directly; ACME/DigiCert/Sectigo pass through). Key algorithm and
size are now persisted in certificate_versions for audit compliance.
16 new tests (12 service-layer + 4 Local CA connector). Removes hardcoded
version number from GUI sidebar. Documentation updated across architecture,
features, connectors, and README.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implements Simple Certificate Enrollment Protocol with single-endpoint
operation-based dispatch (GetCACaps, GetCACert, PKIOperation), PKCS#7
SignedData CSR extraction with fallback for raw/base64 CSR, challenge
password authentication via CSR attributes, and shared internal/pkcs7
package extracted from EST handler to eliminate code duplication.
24 new tests (11 service + 13 handler) plus 5 shared pkcs7 package tests.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Broadened BSL Additional Use Grant from "hosted or managed service" to cover
any commercial offering (embedded, bundled, integrated). Updated README to
promote all shipped connectors from Beta to Implemented, added EST/ARI/S/MIME
highlight, Helm quickstart, and corrected license description. Fixed
connectors.md stale claims (AWS ACM PCA listed as planned, K8s Secrets
listed as coming soon) and updated overview with exact connector counts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The Kubernetes Secrets target connector has config validation, tests, UI,
and Helm RBAC implemented but the realK8sClient is a stub — runtime
deployment will fail. Update README and connectors.md to reflect actual
status instead of misleading 'Beta' label.
Also increase the audit trail GUI default from 50 to 200 events per page
(backend already permits up to 500).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three related ACME ecosystem changes shipped as a single milestone:
1. ACME Certificate Profile Selection: Custom JWS-signed newOrder POST with
`profile` field (e.g., `tlsserver`, `shortlived` for 6-day certs) bypassing
acme.Client.AuthorizeOrder() since golang.org/x/crypto lacks profile support.
ES256 JWS signing with kid mode, nonce management, directory discovery.
Empty profile delegates to standard library path (zero behavior change).
Configurable via CERTCTL_ACME_PROFILE env var. GUI: profile dropdown on
ACME issuer config.
2. ARI RFC 9702 → 9773 Renumber: All 25+ references updated across Go source,
docs, README, and examples. Zero remaining occurrences of RFC 9702.
3. 45-Day / Short-Lived Certificate Positioning: 5 domain tests validating
renewal thresholds against SC-081v3 validity reduction timeline (200→100→47
days) and Let's Encrypt 45-day/6-day profiles. ARI (RFC 9773) is the
expected renewal path for 6-day shortlived certs.
New tests: 13 profile + 5 domain threshold + 1 frontend = 19 new tests.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds a new target connector enabling certificate deployment to any
Linux/Unix server without installing the certctl agent binary. Uses the
proxy agent pattern — a single agent in the same network zone deploys
certs to remote servers over SSH/SFTP.
Key additions:
- SSH/SFTP connector with key auth (file/inline) + password auth
- Injectable SSHClient interface for cross-platform testing (25 tests)
- Shell injection prevention via validation.ValidateShellCommand()
- Configurable cert/key/chain paths with octal permissions
- GUI: 11 SSH config fields in target create wizard
Also fixes pre-existing frontend bug where all target type strings
(nginx, apache, etc.) were sent as lowercase but the backend expects
proper-case (NGINX, Apache, etc.), breaking GUI-created targets.
Adds missing TargetTypeSSH to validTargetTypes service map.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Google Cloud Certificate Authority Service integration via REST API
with OAuth2 service account auth (JWT→access token). Synchronous
issuance model, CA pool selection, mutex-guarded token caching,
revocation with RFC 5280 reason mapping. No Google SDK dependency —
all stdlib. 19 tests with httptest mock OAuth2 + CAS API.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Audit all docs and examples against current codebase state. Fix seed_demo.sql
domain constant casing (IssuerType, TargetType, AgentStatus) that would cause
agent dispatch failures. Fix example docker-compose health endpoints (/health
not /api/v1/health) and env var names (CERTCTL_DATABASE_URL). Update connector
counts, test numbers, and planned→implemented status across docs. Convert 3
ASCII flow diagrams to Mermaid.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Dual-mode TLS connector for mail servers — single package with mode
field selecting Postfix or Dovecot defaults. File-based cert/key
deployment with correct permissions (cert 0644, key 0600), optional
chain append, shell injection prevention, and configurable
reload/validate commands. 18 tests covering config validation,
deployment, and security. GUI wizard fields and OpenAPI enum updated.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
File-based deployment for Envoy service mesh — writes cert/key/chain
to watched directory with optional SDS JSON config for xDS bootstrap.
Path traversal prevention, configurable filenames, 15 tests passing.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete the IIS target connector with dual-mode deployment:
- WinRM proxy agent mode via masterzen/winrm for remote Windows servers
- Base64 PFX transfer with try/finally cleanup on remote host
- GUI wizard updated with 13 IIS config fields including WinRM settings
- TargetDetailPage sensitive field redaction (password/secret/token/key)
- OpenAPI TargetType enum updated (added Traefik, Caddy)
- connectors.md fully documented with WinRM proxy config example
- 38 total IIS tests (10 new WinRM tests), all passing with race detection
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implement full IIS target connector with PEM-to-PFX conversion via
go-pkcs12, PowerShell-based deployment (Import-PfxCertificate, IIS
binding management), SHA-1 thumbprint computation, and SNI support.
Injectable PowerShellExecutor interface enables cross-platform testing.
Regex-validated config fields prevent PowerShell injection. 28 tests.
Restructure README from 563 to 313 lines: outcome-focused feature
descriptions, "Who Is This For" persona section, examples promoted
above the fold, configuration/API/security reference moved to docs.
All numbers verified against repo (25 GUI pages, 97 OpenAPI ops,
CI thresholds service 55%/handler 60%/domain 40%/middleware 30%).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add certificate export in PEM (JSON or file download) and PKCS#12 formats.
Private keys are never included — they stay on agents. Add EKU-aware
issuance threading profile EKUs (serverAuth, clientAuth, codeSigning,
emailProtection, timeStamping) through the full issuance pipeline. Fix
agent CSR SAN splitting for email addresses, adaptive KeyUsage flags for
S/MIME vs TLS, and a pre-existing generateID collision bug in deployment
job creation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
M25: After deploying a certificate, the agent probes the live TLS
endpoint and compares SHA-256 fingerprints to verify the correct cert
is being served. Best-effort — failures don't block deployments.
New endpoints: POST /jobs/{id}/verify, GET /jobs/{id}/verification.
Migration 000008 adds verification columns to jobs table.
M26: Traefik target connector (file provider, auto-reload) and Caddy
target connector (dual-mode: admin API hot-reload or file-based).
Both wired into agent dispatch.
Also: restructured README to highlight supported integrations (issuers,
targets, notifiers) earlier, moved API/CLI/MCP sections lower. Updated
all docs (features, connectors, architecture, testing guide, why-certctl)
and fixed integration tests for 18-param RegisterHandlers signature.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update concepts.md and connectors.md to mention the Discovery and
Network Scans dashboard pages alongside existing API documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EAB credentials (KID + HMAC) were defined in the ACME connector config
but never wired into the acme.Account registration call. This fixes the
dead code and adds automatic EAB credential fetching for ZeroSSL — when
the directory URL is detected as ZeroSSL and no EAB credentials are
provided, certctl calls ZeroSSL's public API to get them automatically.
Changes:
- Wire EABKid/EABHmac into acme.Account.ExternalAccountBinding
- Add isZeroSSL() detection and fetchZeroSSLEAB() auto-fetch
- Add CERTCTL_ACME_EAB_KID/CERTCTL_ACME_EAB_HMAC env vars to main.go
- Add 13 ACME connector tests (config validation, EAB decode, ZeroSSL
auto-EAB with mock servers, URL detection)
- Update docs: README, architecture, connectors, demo-advanced,
testing-guide with EAB/auto-EAB documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Navigation menus for testing guide, architecture, concepts,
connectors, quickstart, advanced demo, and three compliance docs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Standing TXT record at _validation-persist.<domain> eliminates per-renewal
DNS updates. Auto-fallback to dns-01 if CA doesn't offer dns-persist-01.
ScriptDNSSolver extended with PresentPersist method. Configurable via
CERTCTL_ACME_CHALLENGE_TYPE=dns-persist-01 and
CERTCTL_ACME_DNS_PERSIST_ISSUER_DOMAIN env vars.
Also fixes IsExpired edge-case test in discovery_test.go that always failed
due to time.Now() drift between test setup and method invocation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implement Enrollment over Secure Transport protocol with 4 endpoints under
/.well-known/est/ — cacerts (CA chain distribution), simpleenroll (initial
enrollment), simplereenroll (certificate renewal), and csrattrs (CSR
attributes). PKCS#7 certs-only wire format with hand-rolled ASN.1, accepts
both PEM and base64-encoded DER CSRs, configurable issuer and profile
binding, full audit trail. 28 new tests (18 handler + 10 service).
Also includes:
- GetCACertPEM added to issuer connector interface (all 4 issuers updated)
- EST integration tests wired into e2e test suite (13 test cases)
- QA testing guide Part 26 (15 manual EST test cases)
- All docs updated: README, features, architecture, concepts, connectors,
quickstart, demo-advanced (endpoint counts, MCP wording, agent IDs,
issuer interface, resource lists, OpenSSL status)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
CLI syntax corrected across 5 files (concepts, demo-guide, demo-advanced,
architecture, features): list-certs→certs list, get-cert→certs get, etc.
Removed non-existent health/metrics commands, replaced with status.
Subcommand count 10→12 everywhere.
architecture.md: Go 1.22→1.25, endpoint count 91→93, ER diagram expanded
from 15 to 21 tables (added renewal_policies, certificate_revocations,
discovered_certificates, discovery_scans, network_scan_targets).
connectors.md: added GenerateCRL and SignOCSPResponse to issuer interface,
added Email and Webhook rows to notifier config table.
compliance docs: fixed keygen warning messages to match actual log output,
CERTCTL_STEPCA_PROVISIONER_KEY→CERTCTL_STEPCA_KEY_PATH, openssl genrsa→
crypto/ecdsa.GenerateKey, CERTCTL_SERVER_ADDR→CERTCTL_SERVER_HOST+PORT.
README.md: v2.0.0 version bump, solo developer mention, feature list,
table of contents, documentation table moved to top, 7 fact-check fixes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
M21 adds server-side active TLS scanning of CIDR ranges with concurrent
probing, sentinel agent pattern for pipeline reuse, and full CRUD API for
scan targets. M22 adds Prometheus exposition format endpoint alongside
existing JSON metrics. Comprehensive documentation audit updates all docs
to reflect 91 endpoints, 19 tables, 6 scheduler loops, and 900+ tests.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add SOC 2 Type II, PCI-DSS 4.0, and NIST SP 800-57 compliance mapping
guides — the final V2 deliverable. All claims verified against actual
codebase (router.go, config.go, main.go). Also audit and update all
existing docs: fix endpoint/tool/test counts in features.md, expand
demo-guide.md and demo-advanced.md with CLI/MCP/discovery coverage,
update connectors.md F5/IIS status to V3 paid, add compliance reference
to architecture.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add missing V2 concepts (Certificate Profiles, Revocation with CRL/OCSP,
Short-Lived Certificates, CLI, MCP Server, Observability) to concepts guide.
Update quickstart with revocation examples, sorting/filtering, cursor pagination,
sparse fields, stats/metrics, and approval workflows. Align 5-minute demo guide
and advanced demo to full V2 feature set including revocation workflows, bulk ops,
fleet overview, and dashboard charts. Update architecture with MCP server section,
5th scheduler loop, API audit log, and 860+ test count. Add revocation-across-issuers
section to connectors guide.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Backend:
- Embedded OCSP responder: GET /api/v1/ocsp/{issuer_id}/{serial} returns
signed OCSP responses (good/revoked/unknown) using CA key
- DER-encoded X.509 CRL: GET /api/v1/crl/{issuer_id} returns proper DER CRL
signed by issuing CA with 24h validity window
- Short-lived cert exemption: certs with profile TTL < 1 hour skip CRL/OCSP
(expiry is sufficient revocation for ephemeral workloads)
- Extended issuer connector interface with GenerateCRL and SignOCSPResponse
- Local CA implements full CRL/OCSP signing; ACME and step-ca return
appropriate "use native endpoint" errors
- IssuerConnectorAdapter bridges new methods between layers
Frontend:
- Revoke button on certificate detail page with RFC 5280 reason modal
- Revocation banner with reason display and timestamp
- Revocation status indicators in lifecycle section
- "Revoked" filter option in certificates list
- API client: revokeCertificate() function and Certificate type extensions
Tests: ~31 new tests across connector, service, handler, and adapter layers
Docs: milestones renumbered (M13-M14, M16-M18), M15b marked complete
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
