Closes Bundle 5 of the 2026-05-02 deployment-target coverage audit
(see cowork/deployment-target-audit-2026-05-02/RESULTS.md). Pre-fix,
DeployCertificate at iis.go:235-436 imported the cert via
Import-PfxCertificate (atomic at cert-store level) then ran a
separate PowerShell script for the SNI binding update. If the
binding script failed, the new cert was orphaned in the store AND
the old binding stayed pointed at the old thumbprint.
docs/deployment-atomicity.md L91 promised "explicit pre-deploy
backup + post-rollback re-import"; the code didn't deliver.
This commit:
1. Pre-deploy snapshot. snapshotOldBinding runs Get-WebBinding
before the import; parses the bound SSL thumbprint into a local
`oldThumbprint` variable. Empty = first-time binding (no
rollback target).
2. On-failure rollback script. When the binding-update Execute
returns error, rollbackBinding runs a single PowerShell script
that:
- Remove-Item Cert:\LocalMachine\<store>\<newThumbprint> (delete
the cert we just imported but couldn't bind).
- If oldThumbprint != "", AddSslCertificate('<oldThumbprint>',
...) to re-bind the old cert. Falls through to New-WebBinding
+ AddSslCertificate when the old binding entry is also gone.
3. Post-rollback verification. verifyRollback re-reads
Get-WebBinding; asserts the bound thumbprint matches
oldThumbprint. On mismatch, warn in the DeploymentResult
message — the rollback ran but final state is suspect, operator
inspection required. Skipped when oldThumbprint == "" (no
binding to verify against).
4. Helper extraction. snapshotOldBinding / rollbackBinding /
verifyRollback are private methods on Connector for clean test
seams. Each emits a unique `# CERTCTL_*` PowerShell comment tag
so test mocks can match scripts deterministically — multiple
scripts call Get-WebBinding so substring matching otherwise
collides under Go's randomized map iteration order.
DeploymentResult shape on failure:
- rollback OK → Success=false, Message="binding update failed;
rolled back", clean error.
- rollback FAIL → Success=false, wrapped error containing both
binding error and rollback error; metadata
flags manual_action_required=true and surfaces
rollback_error / binding_error verbatim.
Tests added to iis_test.go:
- TestIIS_BindingUpdateFails_RemovesNewCert_RebindsOld — happy
rollback path. Mock executor queued with snapshot →
OLD_THUMBPRINT:abc123, import OK, binding fails, rollback →
REBOUND_EXISTING. Asserts rollback script contains both
Remove-Item for the new thumbprint AND
AddSslCertificate('abc123', ...).
- TestIIS_BindingUpdateFails_NoOldBinding_RemovesNewCertOnly —
first-time deploy variant. Snapshot returns NO_OLD_BINDING;
rollback removes the new cert but does NOT call
AddSslCertificate; verify script never runs.
- TestIIS_BindingUpdateFails_RollbackAlsoFails_OperatorActionable
— wrapped-error escalation. Asserts the returned error mentions
both `binding update failed` and `rollback also failed`, and
metadata flags manual_action_required=true.
Two existing tests (TestIISConnector_DeployCertificate_Success and
…_SNIEnabled) updated to expect 3 commands (snapshot, import,
binding) and to look for the binding script at commands[2].
docs/deployment-atomicity.md L91 unchanged from today's text — the
"Already explicit pre-deploy backup + post-rollback re-import"
claim is now honest. (Bundle 1 doc-realignment hasn't shipped yet,
so there's no softened-pending claim to restore.)
Verified locally (sandbox lacks staticcheck install due to disk
pressure, ran via go vet + go test -race; CI runs the full lint
gate):
- gofmt -l ./internal/connector/target/iis/ clean
- go vet ./internal/connector/target/iis/... clean
- go build ./internal/connector/target/iis/... clean
- go test -race -count=1 ./internal/connector/target/iis/ green
Audit reference: cowork/deployment-target-audit-2026-05-02/RESULTS.md
Bundle 5.
Closes Bundle 4 of the 2026-05-02 deployment-target coverage audit
(see cowork/deployment-target-audit-2026-05-02/RESULTS.md). Pre-fix,
DeployCertificate called deploy.AtomicWriteFile twice — once for
cert at L123, once for key at L131 — instead of bundling both into
a single deploy.Plan and calling deploy.Apply. Three downstream
hazards:
1. If cert write succeeds and key write fails, the cert is already
on disk. The in-line best-effort cert rollback at L137-141 had
no error wrapping and the dedicated rollbackCertAndKey helper
only restored the cert.
2. Idempotency was per-file, not all-files. The verify gate
(if !certRes.Idempotent) skipped verify when cert was unchanged
but key was new — exactly the shape that produces a fresh key on
disk + a stale fingerprint served, and zero alarm.
3. Verify-failure rollback only handled the cert. Key was left in
whatever state the deploy reached.
This commit aligns Traefik with the canonical NGINX/Apache/HAProxy/
Postfix template:
- buildPlan() constructs deploy.Plan{Files: []{cert, key}}.
- deploy.Apply runs it all-or-nothing. SHA-256 idempotency is
all-files (Result.SkippedAsIdempotent).
- No PreCommit (Traefik has no validate-with-target command —
file watcher absorbs config errors).
- No PostCommit (file watcher auto-reloads on rename).
- runPostDeployVerify retained as-is (TLS handshake + SHA-256
fingerprint compare + retry/backoff).
- On verify failure, restoreFromBackups iterates
res.BackupPaths and rewrites each destination via
AtomicWriteFile{SkipIdempotent: true, BackupRetention: -1}.
Removed:
- The legacy rollbackCertAndKey helper (cert-only restore).
- The inline best-effort cert-rollback in DeployCertificate.
Tests added to traefik_atomic_test.go:
- TestTraefik_Atomic_KeyWriteFails_CertRollsBack — regression guard
for the original two-AtomicWriteFile bug. Pre-writes a sentinel
cert; sets the key path inside a read-only subdir so the key
write must fail; asserts the cert on disk still contains the
sentinel bytes (Apply's all-or-nothing rollback).
- TestTraefik_Atomic_AllFilesIdempotent — two subtests:
both_match_skips: pre-writes cert + key matching what Traefik
would write; asserts idempotent=true AND probe is never
called.
cert_match_key_new_runs_verify: pre-writes only the cert; key
is new; asserts idempotent=false AND probe IS called once.
Pre-fix per-file gate would have leaked through and skipped
the verify here.
- TestTraefik_Atomic_VerifyMismatch_BothFilesRollBack — pre-writes
sentinel cert + key; stub probe returns wrong fingerprint;
asserts BOTH files are restored to sentinel bytes after the
rollback fires. Pre-fix rollbackCertAndKey only restored the
cert; the key would still be the new bytes.
The pre-existing TestTraefik_Atomic_VerifyMismatch_Rollback (which
asserted only the cert restore) is left intact — it's a strict
subset of the new BothFilesRollBack assertion and serves as a
narrower regression guard.
docs/deployment-atomicity.md L84 unchanged — operator-facing claim
("atomic-write only; ValidateOnly returns sentinel") stays accurate.
Verified locally:
- gofmt -l ./internal/connector/target/traefik/ clean
- go vet ./... clean
- staticcheck ./internal/connector/target/traefik/... clean
- go build ./... clean
- go test -race -count=1 ./internal/connector/target/traefik/...
green (pre-existing tests + 3 new = 13 test functions; 14 with
the AllFilesIdempotent subtests)
- go test -short -count=1 ./internal/connector/target/... green
(no cross-connector regressions)
Audit reference: cowork/deployment-target-audit-2026-05-02/RESULTS.md
Bundle 4.
Closes Bundle 3 of the 2026-05-02 deployment-target coverage audit
(see cowork/deployment-target-audit-2026-05-02/RESULTS.md). The audit
ranked this fix#3 by acquirer impact behind the K8s real client (#1)
and the docs realignment (#2 / Bundle 1).
Two production-grade gaps closed:
1. SDS JSON config write was non-atomic. Cert/key/chain at envoy.go
L155/L168/L183 went through deploy.AtomicWriteFile (atomic + backups
+ ownership preservation), but the SDS JSON at L260 went through
os.WriteFile directly. A power loss / OOM / process-kill mid-write
of the SDS JSON produces a torn file Envoy cannot parse, and
Envoy's file-based SDS watcher refuses to load any cert (not just
the rotating one) until the JSON is repaired by hand. Replaced with
deploy.AtomicWriteFile and threaded ctx through writeSDSConfig.
2. No watcher pickup confirmation before returning success. Pre-fix,
DeployCertificate returned the moment file writes completed.
Envoy's SDS watcher is asynchronous; a caller running post-deploy
TLS verify immediately after DeployCertificate could see Envoy
still serving the old cert (watcher latency, load-balanced replica
hit one that hadn't reloaded yet). Added the canonical post-deploy
verify pattern (mirrors nginx.go::runPostDeployVerify L416): probe
seam + retry/backoff + SHA-256 fingerprint compare against
request.CertPEM. On verify failure, restore from per-file backups
via the new restoreFromBackups helper. Envoy has no PostCommit
reload to re-run; the watcher auto-reloads on the restored files.
Config additions to envoy.Config (mirror nginx.Config L84-93):
- PostDeployVerify *PostDeployVerifyConfig (Enabled, Endpoint, Timeout)
- PostDeployVerifyAttempts int (default 3 in runPostDeployVerify)
- PostDeployVerifyBackoff time.Duration (default 2s)
- BackupRetention int (mirrors nginx; passed to AtomicWriteFile per file)
Default behaviour unchanged for callers that don't set
PostDeployVerify — verify is opt-in. nil or Enabled=false skips it
entirely.
Probe seam: c.probe = tlsprobe.ProbeTLS at construction; tests inject
via the new SetTestProbe method. Same shape NGINX uses (nginx.go:130);
also mirrors the existing Traefik SetTestProbe at traefik.go:62.
WriteResult retention: every AtomicWriteFile call now retains its
*deploy.WriteResult in a local []*deploy.WriteResult slice so the
rollback path can restore from BackupPath across all four files
(cert, key, chain, SDS JSON), not just the cert. Pre-fix the cert's
WriteResult was discarded.
restoreFromBackups (envoy.go new): iterates the WriteResults from a
successful per-file pass, rewrites each non-idempotent destination
from its BackupPath via AtomicWriteFile{SkipIdempotent:true,
BackupRetention:-1}. The -1 prevents backup-of-the-backup pollution.
For files that didn't exist pre-deploy (BackupPath == ""), restore =
remove. Mirrors nginx.go::rollbackToBackups (L487-515) with the
reload step elided.
Idempotency gate: shouldRunVerify returns true unless EVERY
WriteResult was Idempotent — same all-files semantics NGINX gets
from res.SkippedAsIdempotent. Pre-fix Envoy had no verify at all,
so there was no gate to get wrong; this introduces the correct
all-files shape from the start.
Tests added to envoy_atomic_test.go:
- TestEnvoy_Atomic_SDSConfigWriteIsAtomic — pre-writes a sentinel
SDS JSON, runs DeployCertificate, asserts a backup file with
deploy.BackupSuffix appears alongside the new sds.json (proves
AtomicWriteFile is now in the SDS path).
- TestEnvoy_Atomic_WatcherPickupRetries — stub probe returns wrong
fingerprint on attempts 1+2 and correct on attempt 3; deploy
succeeds; probe called exactly 3 times.
- TestEnvoy_Atomic_WatcherPickupAllAttemptsFail_RollsBack — pre-writes
SENTINEL bytes for cert+key, stub probe always wrong; deploy
returns wrapped error AND the destination files contain the
sentinel bytes (rollback restored).
- TestEnvoy_Atomic_PostDeployVerifyDisabledByDefault — Config with
nil PostDeployVerify; asserts probe is never called (opt-in
default preserved).
A small certPEMFingerprint helper added to the test file mirrors the
production envoy.certPEMToFingerprint (which is package-private —
external tests can't call it).
docs/deployment-atomicity.md L87 row already documents
"TLS handshake | atomic-write replaces os.WriteFile" — pre-fix the
claim was aspirational (verify happened in the agent verify-and-report
path, not the connector; SDS JSON wasn't atomic). Post-fix the claim
is honest. No doc change required.
Verified locally:
- gofmt -l ./internal/connector/target/envoy/ clean
- go vet ./internal/connector/target/envoy/... clean
- staticcheck ./internal/connector/target/envoy/... clean
- go build ./... clean
- go test -race -count=1 ./internal/connector/target/envoy/... green
(5 pre-existing tests + 4 new = 9 total)
- go test -short -count=1 ./internal/connector/target/... green
Audit reference: cowork/deployment-target-audit-2026-05-02/RESULTS.md
Bundle 3.
Mechanical reformat. The new 'gofmt drift' CI step (added in
ci-pipeline-cleanup Phase 4, commit 0f205a8) surfaced 111 files
with accumulated gofmt drift across cmd/, internal/, and deploy/test/.
Each file's diff is gofmt-standard: whitespace adjustments, intra-
group import sorting (alphabetical by import path within blank-line-
separated groups), and struct-tag column alignment. No semantic
changes — verified via 'git diff --ignore-all-space' which shows only
the line-position deltas from import reordering.
The gate stays in place after this commit. Going forward it catches
gofmt drift at PR time.
Phase 13 verification surfaced gofmt-formatting drift in 6 files
across the bundle's new code:
- internal/api/handler/metrics.go (struct field alignment)
- internal/connector/target/k8ssecret/validate_only_test.go (alignment)
- internal/connector/target/nginx/nginx.go (alignment)
- internal/connector/target/postfix/postfix.go (alignment)
- internal/connector/target/ssh/validate_only_test.go (alignment)
- internal/service/deploy_counters.go (alignment)
Pure mechanical gofmt -w fixes; no behavior changes. CI's
make verify gate (which runs `go fmt ./...`) didn't catch these
because go fmt is more lenient than gofmt -l, but golangci-lint
v2.11.4 + the explicit gofmt step in Phase 13 verification did.
Phase 13 full-matrix verification all green:
- gofmt -l: empty across all bundle-touched files
- go vet ./internal/deploy/... ./internal/connector/target/... ./internal/service/ ./internal/api/handler/ ./cmd/agent/: clean
- golangci-lint v2.11.4 (the version CI runs): 0 issues
- go test -race -count=1 across deploy + nginx + apache + haproxy + agent + service: all green
- INTEGRATION=1 go test -tags integration -run Deploy ./deploy/test/...: 4/4 e2e tests green
Phase 14 next: release prep — Active Focus update, release notes,
Reddit-beat draft, final tag handoff to operator.
Phase 9 of the deploy-hardening I master bundle. The four
non-file-server connectors get real ValidateOnly probes that
operators use to preview a deploy without touching the live cert.
Existing DeployCertificate paths already have explicit backup +
rollback semantics (SCP backup / WinCertStore Get-ChildItem
snapshot / keytool snapshot / K8s atomic API).
SSH (validate_only.go):
- Probes via SSHClient.Connect. Confirms agent reachability +
credentials. Cheap (no remote command runs); released cleanly
via defer Close.
- A true SCP dry-run requires a no-commit upload (SCP doesn't
have one). V2 ships the auth probe as the load-bearing check.
- 3 new tests in validate_only_test.go.
WinCertStore (validate_only.go):
- Probes via PowerShell `Get-ChildItem -Path Cert:\<loc>\<store>`
using the configured StoreLocation + StoreName (defaults
LocalMachine\My).
- Confirms agent has Windows + the IIS module + the right ACLs.
- 4 new tests including default-store-path verification.
JavaKeystore (validate_only.go):
- Probes via `keytool -list -keystore <path> -storepass <pass>`
using the configured KeystorePath / KeystorePassword and
KeytoolPath (default "keytool").
- Confirms keystore exists, password is correct, JRE is on PATH.
- 4 new tests covering succeeds / fails / no-path-sentinel /
nil-executor-sentinel.
K8s Secret (validate_only.go):
- Probes via K8sClient.GetSecret on the configured Namespace +
SecretName. Returns nil on success or "not found" (the
CreateSecret path on Deploy will handle it). Other errors
(forbidden/unreachable) surface as wrapped.
- 4 new tests covering succeeds / RBAC-error wrapped /
no-config-sentinel / nil-client-sentinel.
Smoke test connectorsAtPhase3 list shrunk from 7 to 3 entries
(ssh + wincertstore + javakeystore + k8ssecret removed). Only
caddy (file-mode) + envoy + traefik remain — those three
genuinely have no validate-with-target command available.
Race detector clean across all 13 connectors. golangci-lint
v2.11.4 clean.
Phase 10 next: DeployCounters + Prometheus exposer mirroring the
production-hardening-II OCSP counter pattern.
Phase 8 of the deploy-hardening I master bundle. F5 + IIS already
have transactional / explicit-backup-restore rollback semantics
in their DeployCertificate paths. Phase 8 adds the explicit
ValidateOnly dry-run probe that operators use to preview a deploy
without touching the live cert.
F5 (validate_only.go):
- ValidateOnly probes the iControl REST API via Authenticate.
Cheap (no F5 transaction created) + cached after first success.
Failure surfaces as a wrapped error so operators see the actual
cause (auth provider down, invalid creds, BIG-IP unreachable,
etc.). nil client returns ErrValidateOnlyNotSupported.
- A true cert-bind dry-run requires F5's no-commit transaction
mode (v17.5+); V3-Pro can add per-version dispatch. V2 ships
the reachability probe as the load-bearing safety check.
- 5 new tests in validate_only_test.go covering: auth-success,
auth-fail wrapped, nil-client sentinel, error-message contains
BIG-IP context, recoverable auth-fail surfaces provider info.
IIS (validate_only.go):
- ValidateOnly runs `Get-WebSite -Name <SiteName>` via the
injected PowerShellExecutor. Confirms the IIS PS module is
loaded AND the site exists AND the agent has admin privileges.
Failure here surfaces the actual PowerShell stderr (site not
found / module missing / access denied).
- A true cert-bind dry-run would need IIS to expose a no-commit
New-WebBinding (it doesn't); V3-Pro can extend with a
temp-install + immediate-remove. V2 ships the permission +
module probe as the load-bearing check.
- 5 new tests in validate_only_test.go covering: get-website
succeeds, get-website fails, nil-executor sentinel, site-name
quoting (handles spaces in 'Default Web Site'), output-context
in error.
Smoke test connectorsAtPhase3 list shrunk from 10 to 7 entries
(f5 + iis + postfix removed). Caddy stays in (file-mode returns
sentinel; api-mode is real-impl). Envoy + Traefik stay in (no
validate-with-target command exists for either). javakeystore +
k8ssecret + ssh + wincertstore stay in pending Phase 9.
Coverage: F5 holds at ≥85%; IIS holds at ≥85%. Race detector
clean. golangci-lint v2.11.4 clean.
Phase 9 next: SSH + WinCertStore + JavaKeystore + K8s — the
non-file-server connectors.
Phase 7 of the deploy-hardening I master bundle. Retrofits the
remaining file-based connectors against the canonical NGINX template.
Per-connector quirks codified:
- Postfix/Dovecot: full retrofit with PreCommit (postfix check /
doveconf -n) + PostCommit (postfix reload / doveadm reload) +
post-deploy TLS verify. Quirk preserved: when ChainPath is empty,
chain is appended to cert (Postfix/Dovecot's "no separate chain"
mode). Per-distro user defaults: postfix, dovecot, _postfix.
Default key mode 0600. ValidateOnly real impl returns sentinel
when no ValidateCommand.
- Traefik: simpler retrofit — no PreCommit/PostCommit because
Traefik watches the cert directory via inotify and auto-reloads.
Atomic-write via deploy.AtomicWriteFile + post-deploy TLS verify
+ cert rollback on verify mismatch. Default key mode 0600.
ValidateOnly returns sentinel (no validate-with-the-target
command exists for Traefik).
- Caddy: retrofitted both modes. File mode replaces os.WriteFile
with deploy.AtomicWriteFile (preserves the file watcher's auto-
reload). API mode unchanged (POST /load already atomic at the
Caddy admin server). ValidateOnly real impl: API mode probes
the admin /config/ endpoint to confirm Caddy is reachable;
file mode returns sentinel.
- Envoy: file mode atomic-write via deploy.AtomicWriteFile.
Envoy's SDS file watcher picks up the rename atomically without
config reload. ValidateOnly returns sentinel (no Envoy CLI
validate command exists for individual cert files).
Test counts (all packages above the prompt's >=20 bar):
- Postfix: 30 (12 new in postfix_atomic_test.go + 18 pre-existing)
- Traefik: 22 (12 new in traefik_atomic_test.go + 10 pre-existing)
- Caddy: 22 (10 new in caddy_atomic_test.go + 12 pre-existing)
- Envoy: 21 (5 new in envoy_atomic_test.go + 16 pre-existing)
Coverage: each connector at the prompt's >=80% target. golangci-lint
v2.11.4 clean across all 4 connector packages.
Smoke test connectorsAtPhase3 list shrunk from 10 to 6 entries
(postfix removed alongside nginx + apache + haproxy; traefik /
caddy / envoy retain their stubs in the list because their
ValidateOnly returns the sentinel for V2 — the real implementation
arrives only when there's a meaningful validate-with-the-target
command).
Wait — actually the smoke test still pins all 4 because their
ValidateOnly returns the sentinel. Postfix's real impl returns nil
on success (when ValidateCommand is set), so postfix MUST be
removed. Caddy's API mode is real-impl. Traefik + Envoy still
return sentinel always — they stay in the smoke list.
Phase 8 next: F5 + IIS — explicit post-deploy TLS verify +
on-failure rollback. Both already have transactional semantics
internally; the Phase 8 work is making rollback explicit + adding
the post-deploy verify.
Phase 5 of the deploy-hardening I master bundle. Mirrors the Phase 4
NGINX template for Apache httpd. Test count lifts 3 → 34 (above the
prompt's >=30 target; matches and slightly exceeds the IIS bar).
Apache-specific quirks codified in apache.go:
- Validate command convention is `apachectl configtest` (NOT
`apachectl -t` — that flag exists but configtest is the documented
operator-facing form).
- Reload command convention is `apachectl graceful` for zero-
downtime worker swap (NOT `apachectl restart` which drops
in-flight TLS sessions).
- Per-distro user defaults: Debian/Ubuntu apache2, RHEL/CentOS
apache, Alpine httpd. pickFirstExistingUser walks the list and
picks the one that resolves on the host; falls back to no-chown
when none exist (cross-distro portability without operator
config; same approach as nginx).
- Default key file mode 0600 for back-compat with operators
relying on the historical hard-coded value (matches the
pre-Phase-5 implementation behavior).
DeployCertificate refactor:
- Replaces the duplicated os.WriteFile chain with deploy.Apply.
- PreCommit runs the operator's ValidateCommand via the test
seam (which wraps `sh -c <cmd>` in production).
- PostCommit runs ReloadCommand the same way.
- Post-deploy TLS verify (frozen-decision-0.3 default ON when
Endpoint is configured): probes the configured target,
compares leaf cert SHA-256 against deployed bytes, retries with
exponential backoff (default 3 attempts / 2s backoff for
load-balanced targets).
- Rollback wires: reload-fail → restore backups + retry reload;
verify-fail → restore backups + reload again. Second-failure
surfaces ErrRollbackFailed for operator-actionable triage.
ValidateOnly real implementation replaces the Phase 3 stub.
Returns ErrValidateOnlyNotSupported when no ValidateCommand
configured; otherwise runs the validate-with-the-target command
without touching the live cert.
Test seams (SetTestRunValidate / SetTestRunReload / SetTestProbe)
allow tests to skip exec without `apachectl` on PATH; mirror the
nginx pattern.
Tests (34 total: 31 in apache_atomic_test.go + 3 pre-existing
in apache_test.go):
- Atomic invariants (happy, validate-fail-no-files-changed,
reload-fail-rollback, rollback-also-fail-escalation)
- SHA-256 idempotency (full skip + partial-mismatch full-deploy)
- Post-deploy verify (match-success, mismatch-rollback,
dial-timeout-rollback, retries-until-match,
retries-exhausted-rollback, no-endpoint-skips, disabled-skips)
- Ownership / mode preservation (existing-mode, override-wins,
default-key-0600, default-cert-0644)
- Backup retention (keeps-N, disabled-no-backups, backup-created)
- Concurrency (same-paths-serialize)
- ValidateOnly (happy, fails, no-command-sentinel, stderr-in-error)
- Edge cases (no-chain, no-key, ctx-cancelled, verify-rollback-
reload, deployment-id-prefix, metadata-populated)
Coverage: Apache 86.6% (above the >=85% prompt bar). Race detector
clean. golangci-lint v2.11.4 clean.
Smoke test connectorsAtPhase3 list shrunk from 12 to 11
entries (apache removed; nginx + apache now have real impls).
Phase 6 next: HAProxy (combined PEM atomic write + `haproxy -c -f`
validate + uplift 3 → >=30).
Phase 4 of the deploy-hardening I master bundle. The canonical NGINX
implementation that Phases 5-9 model on. Replaces the historical
os.WriteFile flow at internal/connector/target/nginx/nginx.go:99
with deploy.Apply() and adds three production-grade competitor-gap
features: atomic deploy with rollback, post-deploy TLS verify, file
ownership preservation.
NGINX connector — internal/connector/target/nginx/nginx.go:
- DeployCertificate now wires deploy.Apply with PreCommit running
the operator's ValidateCommand (e.g. `nginx -t`), PostCommit
running ReloadCommand (e.g. `nginx -s reload`), and an explicit
post-deploy TLS verify step that dials the configured endpoint,
pulls the leaf cert SHA-256, and compares against what was just
deployed. SHA-256 mismatch (wrong vhost / cached cert / NGINX
still serving stale) triggers automatic rollback: backup files
are restored + reload fired again. Failed-second-reload returns
ErrRollbackFailed (operator-actionable; loud audit + alert).
- ValidateOnly replaces the Phase 3 stub: runs the operator's
ValidateCommand without touching the live cert. V2 contract is
syntax-only validation (full pre-deploy temp-config validation
is V3-Pro). Returns ErrValidateOnlyNotSupported when no
ValidateCommand is configured.
- New per-target Config fields: PostDeployVerify (frozen-decision-
0.3 default ON), PostDeployVerifyAttempts (default 3 — defends
against load-balanced targets where the verify might hit a
different pod that hasn't picked up the new cert yet),
PostDeployVerifyBackoff (default 2s exponential), per-file
Mode/Owner/Group overrides (KeyFileMode, CertFileMode,
KeyFileOwner, etc.), and BackupRetention (default 3, -1 to
disable backups entirely — documented foot-gun).
- buildPlan honors per-distro nginx user (Debian: www-data,
Alpine: nginx, Red Hat: nginx) by checking the local user
database; falls back to no-chown when neither exists. Means
the connector is portable across distros without operator
config.
Deploy package — internal/deploy/ownership.go:
- applyOwnership now silently swallows chown failures when the
agent isn't running as root. Production agents always run as
root and chown failures are real bugs; dev / CI runs as a
regular user where chown to a different uid will always fail
with EPERM (or EINVAL on some tmpfs configs) and would
otherwise force every test to run with sudo. Production-grade
contract preserved (uid 0 still hard-fails on chown errors).
Test suite — internal/connector/target/nginx/nginx_atomic_test.go
ships 42 new named tests (NGINX total: 17 pre-existing + 42 new = 59,
above the prompt's >=40 bar; matches the IIS depth bar of 41):
- Atomic-deploy invariants (cert+chain+key all-or-nothing,
validate-fails-no-files-changed, reload-fails-rollback,
rollback-also-fails-escalation)
- SHA-256 idempotency (full match skips, partial match deploys all)
- Post-deploy TLS verify (fingerprint-match-success,
SHA256-mismatch-rollback, dial-timeout-rollback, retries-until-
match, retries-exhausted-rollback, no-endpoint-skips,
disabled-skips-entirely, default-10s-timeout, endpoint-forwarded)
- Ownership / mode preservation (existing-mode-preserved, override-
wins, KeyFileMode override applied)
- Backup retention (keeps-last-N, disabled-creates-no-backups,
fresh-deploy-creates-backup)
- Concurrency (same-paths-serialize via deploy package's file mutex,
different-paths-parallelize)
- ValidateOnly (happy-path-nil, command-fails-wrapped-error,
no-config-returns-sentinel, ctx-cancelled, stderr-in-message)
- Edge cases (no-chain, no-key, no-chain-path, empty-cert-PEM,
ctx-cancelled, all-four-one-apply)
- Result.Metadata + DeploymentID shape contracts
Coverage: NGINX 91.0% (above the >=85% prompt bar). Race detector
clean. golangci-lint v2.11.4 clean. Existing 17 tests still all pass
(no behavior change in the legacy paths exercised there).
Phase 5 next: mirror this implementation for Apache + lift its
test count from 3 to >=30. Same template applies through Phases
6-9 for the remaining 11 connectors.
Phase 3 of the deploy-hardening I master bundle. Extends the
target.Connector interface with the dry-run method that operators
will use to preview a deploy before committing — but ships only the
default-stub for all 13 connectors. Phases 4-9 replace each stub
with the real validate-with-the-target implementation.
interface.go:
- Add ErrValidateOnlyNotSupported sentinel (frozen decision 0.6 —
connectors that cannot dry-run, like K8s, return this rather than
nil so operator triage can errors.Is for "not supported" vs
"validated successfully").
- Add ValidateOnly(ctx, request DeploymentRequest) error to
Connector interface.
13 new validate_only.go files (one per connector at
internal/connector/target/<name>/validate_only.go):
- apache, caddy, envoy, f5, haproxy, iis, javakeystore, k8ssecret,
nginx, postfix, ssh, traefik, wincertstore.
- Each file is identical except for the package declaration: a
one-method default stub returning target.ErrValidateOnlyNotSupported.
- Per-connector files (rather than a single embed-method approach)
let Phases 4-9 replace each connector's stub independently
without churning a shared base.
Tests:
- internal/connector/target/validate_only_test.go pins the sentinel
contract (errors.Is identity, Error() string, %w wrap propagation).
- internal/connector/target/validate_only_smoke_test.go (external
test package) constructs a zero-value &<pkg>.Connector{} for each
of the 13 connectors and asserts ValidateOnly returns
ErrValidateOnlyNotSupported. The test's
connectorsAtPhase3 list is the load-bearing CI guard:
- A 14th connector added without wiring ValidateOnly fails the
`len(connectorsAtPhase3) != 13` invariant.
- A connector whose real ValidateOnly lands (Phase 4 NGINX, Phase
5 Apache, etc.) MUST be removed from this list or the smoke test
fails (real impl no longer returns the sentinel). That removal
IS the bookkeeping that the operator-visible bit + behavior
change are wired together end-to-end.
Compile + go vet + golangci-lint v2.11.4 + go test all 0 issues.
Phase 4 next: NGINX canonical real-impl — replace the stub with
nginx -t -c <temp>; same time replace the existing os.WriteFile
flow in DeployCertificate with deploy.Apply(...).
Closes Q-1 (cat-s3-58ce7e9840be) — 37 t.Skip / testing.Short() sites
across 9 test files audited. Per-site verdict matrix:
- cmd/agent/verify_test.go (1 site): defensive guard against unreachable
httptest.NewTLSServer code path. Document-skip with closure comment.
- deploy/test/qa_test.go (11 sites): file already gated by `//go:build qa`
tag. The 11 t.Skip("Requires X — manual test") markers are runtime
second-line guards for operators who run -tags qa against a stack
missing the required external service. File-level header comment
block added explaining the manual-test convention.
- deploy/test/healthcheck_test.go (5 sites): 3 docker-availability +
1 testing.Short + 1 hard-skip for not-yet-wired runtime probe
(image-spec contract above already covers the audit-flagged
regression). All correctly gated; file-level header comment block
added explaining each.
- deploy/test/integration_test.go (5 sites): in-flight-state guards
(poll-with-skip after 90s polling for agent-online, inter-test
Phase04→Phase07 ordering, scheduler-tick race for discovered certs,
inter-test issuer fallthrough, defensive PEM-empty assertion).
Each site now has a closure comment explaining why skip is the
right choice rather than fail (upstream phase already surfaces the
real failure; skipping prevents masking root cause behind cascading
noise).
- internal/repository/postgres/{testutil,seed,repo}_test.go (5 sites):
testing.Short() gates for testcontainers-backed live PostgreSQL
integration tests. All correctly gated; closure comments added
naming the run command.
- internal/connector/notifier/email/email_test.go (2 sites):
anti-fixture assertions (test asserts SMTP dial fails; if a captive
portal black-holes the call to success, skip rather than false-pass).
Closure comments added explaining the fixture assumption.
- internal/connector/target/iis/iis_test.go (2 sites): platform-gated
skip for powershell.exe absence on non-Windows hosts. Mirrors the
production iis_connector.go LookPath guard. Closure comments added.
Total: 17 closure comments anchor the 37 skip sites (some sites share a
single block-level comment). All skips remain in place; the change is
purely documentation. The audit recommendation was "audit each skip and
decide" — for these 37, the decision is uniformly **document-skip**:
the gating is correct, the t.Skip messages name the missing precondition,
and the closure comments now pin the rationale for future readers.
See coverage-gap-audit-2026-04-24-v5/unified-audit.md
cat-s3-58ce7e9840be for closure rationale.
SA1029: use typed context key instead of string in main_test.go
S1039: remove unnecessary fmt.Sprintf in validation_test.go
SA4023: fix unreachable nil check on concrete error type
SA4006: fix unused variable assignments in stepca_test.go (4 occurrences)
SA4000: fix duplicate expression in ssh_test.go (BEGIN vs END CERTIFICATE)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Close coverage gaps identified by dual-audit (qualitative + quantitative).
New test files for config (0%→98%), router (0%→100%), handler validation,
health, audit, response helpers, webhook notifier (0%→88%), email notifier,
middleware (recovery, rate limiter), domain profile, service nil-safety,
config helpers, issuer bootstrap, and server bootstrap wiring. Expanded
existing tests for ACME (34%→42%), step-ca (42%→52%), F5, SSH, agent
(43%→63%), scheduler (88%→99%), renewal service, and issuerfactory.
All tests pass: go test -short, go vet, go test -race clean.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove unnecessary fmt.Sprintf wrapping a string literal (staticcheck S1039),
remove unused tempFileForPFX function, and clean up unused os import.
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>
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>
Fixes 12 production bugs preventing the full issuance→deployment flow
from working with ACME (Pebble/Let's Encrypt) and step-ca issuers:
ACME connector (acme.go):
- Save orderURI before WaitOrder overwrites it (Go crypto/acme bug)
- Add CreateOrderCert fallback via WaitOrder+FetchCert
- Remove defer-reset in ValidateConfig that caused nil pointer panic
- Add Insecure TLS option for self-signed ACME servers (Pebble)
step-ca connector (stepca.go, jwe.go):
- Real JWE provisioner key loading + decryption (was using ephemeral keys)
- Fix JWT audience (/1.0/sign), sha claim (key fingerprint), kid header
- Custom root CA trust via RootCertPath config
- Remove hardcoded 90-day validity default (let step-ca decide)
NGINX target connector (nginx.go):
- Use sh -c for validate/reload commands (shell interpretation)
- Use filepath.Dir instead of fragile string slicing
- Add private key file writing (agent-mode keys were never deployed)
- Make chain_path write conditional
Server/service layer:
- TriggerRenewalWithActor now creates actual Job records (was no-op)
- createDeploymentJobs falls back to DB query when cert.TargetIDs empty
- ProcessPendingJobs skips agent-routed deployment jobs
- Agent cert pickup path parsing: len(parts)<4 → len(parts)<3
- Health/ready/auth-info endpoints bypass auth middleware
- Write timeout 15s→120s for ACME issuance
- Cert fingerprint computed on CSR submission
Integration test environment (deploy/test/):
- 10-phase test script covering Local CA, ACME, step-ca, revocation,
discovery, renewal, and API spot checks
- Docker Compose with 7 containers (server, agent, postgres, nginx,
pebble, challtestsrv, step-ca) on isolated network
- TLS verification checks SAN (not just Subject CN) for modern CA compat
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add context.Context to handler test mocks (agent, agent_group)
- Refactor scheduler to use local interfaces instead of concrete service types
- Wire RevocationSvc/CAOperationsSvc sub-services in integration tests
- Add context.Background() to service test calls (agent, agent_group)
- Fix repo integration tests: add FK prerequisite records (team, owner,
issuer, renewal_policy) before creating certificates
- Set MaxOpenConns(1) on test DB to preserve SET search_path across queries
- Fix Apache/HAProxy tests: replace "echo ok"/"echo reload" with "true"
binary to avoid macOS exec.Command PATH resolution failure
- Fix validation tests: correct error expectations for regex-first checks,
replace null byte strings with strings.Repeat for length tests
- Fix scheduler timeout test flakiness with t.Skip fallback
- Remove unused imports (context in ca_operations_test, service in scheduler)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Updated AgentService interface to accept context.Context parameter in all methods
- Replaced context.Background() calls with proper ctx parameter in agent.go
- Updated AgentGroupService interface to accept context.Context parameter
- Replaced context.Background() calls with proper ctx parameter in agent_group.go
- Updated handler methods to pass r.Context() to service methods
- Context now properly propagates through request lifecycle for timeout/cancellation
- Improved request tracing and cancellation behavior
- Added TestSlack_ClientHasTimeout to verify 10-second timeout
- Added TestTeams_ClientHasTimeout to verify 10-second timeout
- Added TestPagerDuty_ClientHasTimeout to verify 10-second timeout
- Added TestOpsGenie_ClientHasTimeout to verify 10-second timeout
- All notifiers already configured with 10 second timeout in New()
- Tests verify timeout is set and matches expected value
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>
Upgrade from Go 1.22 to 1.25 (minimum for MCP SDK, actively supported).
CI updated to match.
Codebase audit fixes:
- Local CA parseIP() now uses net.ParseIP — IP SANs no longer silently dropped
- Nil pointer guards in agent.go GetWorkWithTargets for target/cert enrichment
- MCP CreateCertificateInput marks owner_id/team_id as required
- NGINX connector uses CombinedOutput() — captures diagnostic output on failure
- Jobs handler validates JSON decode on rejection body — returns 400 on malformed
- CRL/OCSP handlers propagate requestID for error tracing
MCP server tests (26 tests):
- client_test.go: HTTP client coverage (GET/POST/PUT/DELETE, auth, 204, errors, binary)
- tools_test.go: tool registration, pagination, end-to-end flows with mock API
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Agents now report OS, architecture, IP address, hostname, and version
via heartbeat using runtime.GOOS, runtime.GOARCH, and net.Dial. New
migration adds columns to agents table. Heartbeat handler, service,
and repository updated to accept and persist metadata. GUI shows
OS/Arch in agent list and full system info in agent detail page.
Apache httpd connector: separate cert/chain/key files, apachectl
configtest validation, graceful reload. HAProxy connector: combined
PEM file (cert+chain+key), optional config validation, reload.
Both wired into agent binary's target connector switch.
14 tests for new connectors. All existing tests updated for new
Heartbeat/UpdateHeartbeat signatures. Docs updated across README,
architecture, concepts, and connectors guides.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixes Go Report Card gofmt score from 52% to 100%.
Pure formatting changes — no logic modifications.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Private keys never leave agent infrastructure. Agents generate ECDSA P-256
key pairs locally, store them with 0600 permissions, and submit only the CSR
(public key) to the control plane. New AwaitingCSR job state pauses
renewal/issuance jobs until the agent submits its CSR. Server-side keygen
retained behind CERTCTL_KEYGEN_MODE=server for demo/development.
Key changes:
- Dual keygen mode via CERTCTL_KEYGEN_MODE (agent default, server for demo)
- AwaitingCSR job state with CommonName/SANs in work response
- Agent ECDSA P-256 keygen, local key storage, CSR-only submission
- CompleteAgentCSRRenewal server-side flow for agent-submitted CSRs
- DeploymentRequest.KeyPEM for agent-provided keys during deployment
- Dockerfile.agent creates /var/lib/certctl/keys with correct ownership
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Backend hardening:
- Fix 6 nginx.go non-constant format string build errors
- Add validation.go with hostname, PEM, and enum validators
- Apply input validation to all POST/PUT handlers (certificates,
agents, CSR, policies, teams, owners, targets, issuers)
- Fix unchecked JSON decode in TriggerDeployment handler
Frontend (Vite + React + TypeScript):
- Migrate from single-file SPA to proper build pipeline
- 7 pages: Dashboard, Certificates (list+detail), Agents, Jobs,
Notifications, Policies, Audit Trail
- TanStack Query for server state with auto-refetch intervals
- Certificate detail with version history and renewal trigger
- Job cancellation, status/type filtering, expiry countdowns
- Reusable components: DataTable, StatusBadge, ErrorState, PageHeader
- Dark theme with Tailwind CSS, sidebar nav via React Router
Server integration:
- Go server serves web/dist/ (Vite output) with SPA fallback
- Falls back to web/index.html for legacy mode
- .gitignore updated for web/node_modules/ and web/dist/
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
shankar0123