gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 12:21:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

cli: promote --force on renew + require --reason on revoke (closes P3-1, P3-2)

Browse Source 
Closes findings P3-1 and P3-2 from the 2026-05-05 CLI/API/MCP↔GUI parity
audit (cowork/cli-gui-parity-audit-2026-05-05/RESULTS.md). Both findings
flagged hidden defaults that the CLI was sending without exposing them
to operators: `force=false` baked into every renew payload, and a silent
fallback to `reason="unspecified"` whenever --reason was omitted.

P3-1 — promote --force on `certs renew` (full end-to-end plumbing)

The pre-2026-05-05 CLI sent `{"force": false}` in the renew body. The
API handler never decoded it — a textbook "lying field" per the
operator's CLAUDE.md "complete path, not the easy path" rule: the body
field stored a value, claimed to do something, and silently did nothing
because the wire never reached the consumer. Adding a --force flag that
also went unread would have created another lying field.

This commit takes the complete path:

  service.CertificateService.TriggerRenewal grew a `force bool` parameter
  (internal/service/certificate.go). When force=true, the
  RenewalInProgress block is overridden so operators can recover stuck
  in-flight renewals where a previous job hung without releasing the
  status flag. Archived and Expired remain terminal blockers regardless
  of force — those are semantic dead-ends that --force should not paper
  over (archived = decommissioned, expired = issue a new cert instead of
  renewing a dead one).

  handler.CertificateHandler.TriggerRenewal parses force from
  ?force=true (or ?force=1) query param, OR {"force": true} JSON body,
  whichever the client picks. Defaults to false. Passes through to the
  service.

  internal/cli/client.go::RenewCertificate(id, force bool) sends
  ?force=true on the URL when --force is set. The historical hardcoded
  `{"force": false}` body is gone — no more lying field.

  cmd/cli/main.go dispatches `certs renew <id> [--force]` (ID-first
  flag-second convention matches the existing `agents retire <id>
  [--force]`).

P3-2 — require --reason on `certs revoke` (Option A: strict refusal)

The pre-2026-05-05 CLI dropped to `--reason unspecified` whenever the
operator omitted the flag. Compliance reporting (RFC 5280 §5.3.1, PCI-
DSS §3.6, HIPAA §164.312) relies on the reason code being meaningful;
silent fallback defeats the audit trail because every revocation looks
identical.

  cmd/cli/main.go dispatch refuses to send when --reason is empty,
  prints the canonical RFC 5280 §5.3.1 reason-code menu, and exits
  non-zero.

  internal/cli/client.go exposes ValidRevokeReasons() returning the
  canonical camelCase list (unspecified, keyCompromise, caCompromise,
  affiliationChanged, superseded, cessationOfOperation, certificateHold,
  removeFromCRL, privilegeWithdrawn, aaCompromise) and
  NormalizeRevokeReason() that accepts both camelCase and snake_case
  inputs and normalises to the canonical wire form. Off-list reasons
  are rejected at dispatch with the menu re-printed.

Test pins:

  internal/cli/client_test.go::TestClient_RenewCertificate_ForceFlag —
  --force=true sends ?force=true with empty body; --force=false sends
  no query and no body.

  internal/cli/client_test.go::TestNormalizeRevokeReason +
  TestValidRevokeReasons — canonical-camelCase + snake_case + reject-
  off-enum behaviour.

  cmd/cli/dispatch_test.go::TestHandleCerts_Revoke_RequiresReason +
  TestHandleCerts_Revoke_RejectsUnknownReason +
  TestHandleCerts_Renew_ForceFlag — dispatch-layer pins for the same
  contracts.

  internal/api/handler/certificate_handler_test.go::TestTriggerRenewal_
  ForceQueryParam — query-param passthrough (no-flag, force=true,
  force=1, force=false) flows through to the service-layer parameter.

  internal/service/certificate_test.go::TestTriggerRenewal_
  ForceOverridesInProgress — force=false preserves the
  RenewalInProgress block; force=true clears it.

  Existing TestTriggerRenewal_Archived extended to assert force=true
  still blocks Archived (terminal-state guarantee).

Docs: docs/reference/cli.md updated with the --force example for renew
and the strict --reason semantics for revoke (including snake_case
input acceptance).

Acceptance gate (verified):
  - go build ./cmd/server/... ./cmd/agent/... ./cmd/cli/...
    ./cmd/mcp-server/... clean.
  - go vet ./... clean.
  - go test -short -count=1 ./... pass repo-wide.
  - bash scripts/ci-guards/openapi-handler-parity.sh clean
    (router 178, OpenAPI 144, exceptions 36 — unchanged; we add
    parameter parsing, not routes).
  - gofmt -l clean.
This commit is contained in:
shankar0123
2026-05-05 19:49:34 +00:00
parent ff75361553
commit 0e06f6c4fc
9 changed files with 456 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cmd/cli/dispatch_test.go
+68 -3
View File
@@ -163,14 +163,79 @@ func TestHandleCerts_Revoke_HitsClientPath(t *testing.T) {
}))
t.Cleanup(srv.Close)
c := newDispatchTestClient(t, srv)
if err := handleCerts(c, []string{"revoke", "mc-x", "--reason", "compromise"}); err != nil {
// 2026-05-05 parity-defaults-cleanup (P3-2): reason must be a canonical
// RFC 5280 §5.3.1 code (camelCase or snake_case both accepted; this
// test asserts the snake_case path normalises to the camelCase wire
// format that the local issuer + ACME server expect).
if err := handleCerts(c, []string{"revoke", "mc-x", "--reason", "key_compromise"}); err != nil {
t.Errorf("handleCerts({revoke ...}): err=%v", err)
}
if lastMethod != "POST" || !strings.Contains(lastPath, "/revoke") {
t.Errorf("expected POST .../revoke, got %s %s", lastMethod, lastPath)
}
if !strings.Contains(lastBody, "compromise") {
t.Errorf("expected reason in body, got %q", lastBody)
if !strings.Contains(lastBody, "keyCompromise") {
t.Errorf("expected normalised reason 'keyCompromise' in body, got %q", lastBody)
}
}
// TestHandleCerts_Revoke_RequiresReason pins the 2026-05-05 parity-defaults-
// cleanup (P3-2, Option A) strict-reason contract: empty --reason is a
// fatal error, not a silent fallback to "unspecified".
func TestHandleCerts_Revoke_RequiresReason(t *testing.T) {
srv := stubServer(t, 200, `{}`)
c := newDispatchTestClient(t, srv)
err := handleCerts(c, []string{"revoke", "mc-x"})
if err == nil {
t.Fatal("expected error when --reason is omitted; got nil (regression on P3-2 strict path)")
}
if !strings.Contains(err.Error(), "reason") {
t.Errorf("expected error to mention 'reason', got %q", err.Error())
}
}
// TestHandleCerts_Revoke_RejectsUnknownReason pins that off-RFC reason
// codes are rejected at the CLI dispatch layer (P3-2 anti-typo guard).
func TestHandleCerts_Revoke_RejectsUnknownReason(t *testing.T) {
srv := stubServer(t, 200, `{}`)
c := newDispatchTestClient(t, srv)
err := handleCerts(c, []string{"revoke", "mc-x", "--reason", "compromise"})
if err == nil {
t.Fatal("expected error for non-canonical reason; got nil")
}
if !strings.Contains(err.Error(), "compromise") {
t.Errorf("expected error to echo bad reason 'compromise', got %q", err.Error())
}
}
// TestHandleCerts_Renew_ForceFlag pins the 2026-05-05 parity-defaults-
// cleanup (P3-1) wire: --force on the renew dispatch sends ?force=true.
// CLI convention: ID is positional and precedes the flags (matches
// `agents retire <id> [--force]`), so the flag MUST come after the ID.
func TestHandleCerts_Renew_ForceFlag(t *testing.T) {
for _, tc := range []struct {
name string
args []string
wantQuery string
}{
{"no-force", []string{"renew", "mc-x"}, ""},
{"force-after-id", []string{"renew", "mc-x", "--force"}, "force=true"},
} {
t.Run(tc.name, func(t *testing.T) {
var lastQuery string
srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
lastQuery = r.URL.RawQuery
w.WriteHeader(200)
_, _ = w.Write([]byte(`{}`))
}))
t.Cleanup(srv.Close)
c := newDispatchTestClient(t, srv)
if err := handleCerts(c, tc.args); err != nil {
t.Fatalf("handleCerts: %v", err)
}
if lastQuery != tc.wantQuery {
t.Errorf("query: got %q want %q", lastQuery, tc.wantQuery)
}
})
}
}
cmd/cli/main.go
+59 -11
View File
@@ -144,22 +144,70 @@ func handleCerts(client *cli.Client, args []string) error {
}
return client.GetCertificate(subArgs[0])
case "renew":
// 2026-05-05 parity-defaults-cleanup (P3-1): expose --force as an
// explicit operator flag instead of the historical hardcoded
// `force=false` body field. force=true overrides the server-side
// RenewalInProgress block — used to recover stuck in-flight
// renewals. Archived/Expired remain terminal regardless.
//
// CLI convention: `certs renew <id> [--force]` — the ID is a
// positional arg that precedes the flags. Mirrors `agents retire
// <id>`'s pattern (Go's flag package stops at the first non-flag
// token, so we pull subArgs[0] as the ID and hand subArgs[1:] to
// the flag parser).
if len(subArgs) == 0 {
fmt.Fprintf(os.Stderr, "usage: certs renew <id>\n")
return nil
}
return client.RenewCertificate(subArgs[0])
case "revoke":
if len(subArgs) == 0 {
fmt.Fprintf(os.Stderr, "usage: certs revoke <id> [--reason <reason>]\n")
fmt.Fprintf(os.Stderr, "usage: certs renew <id> [--force]\n")
return nil
}
id := subArgs[0]
reason := "unspecified"
if len(subArgs) > 2 && subArgs[1] == "--reason" {
reason = subArgs[2]
fs := flag.NewFlagSet("certs renew", flag.ContinueOnError)
force := fs.Bool("force", false, "Force renewal even when the cert is currently in RenewalInProgress (clears stuck in-flight renewals; does NOT override Archived/Expired terminal states)")
if err := fs.Parse(subArgs[1:]); err != nil {
return err
}
return client.RevokeCertificate(id, reason)
return client.RenewCertificate(id, *force)
case "revoke":
// 2026-05-05 parity-defaults-cleanup (P3-2, Option A): --reason is
// strictly required. Empty reason refuses to dispatch and prints
// the RFC 5280 §5.3.1 reason-code menu so operators pick a real
// value. The pre-2026-05-05 silent fallback to "unspecified"
// defeated compliance reporting (PCI-DSS §3.6, HIPAA §164.312)
// because every revocation looked the same in the audit trail.
//
// CLI convention: `certs revoke <id> --reason <reason>` — same
// ID-first ordering as `certs renew`.
if len(subArgs) == 0 {
fmt.Fprintf(os.Stderr, "usage: certs revoke <id> --reason <reason>\n")
fmt.Fprintf(os.Stderr, "\nValid RFC 5280 §5.3.1 reasons:\n")
for _, r := range cli.ValidRevokeReasons() {
fmt.Fprintf(os.Stderr, " %s\n", r)
}
return nil
}
id := subArgs[0]
fs := flag.NewFlagSet("certs revoke", flag.ContinueOnError)
reason := fs.String("reason", "", "RFC 5280 revocation reason (required). Valid values: keyCompromise, caCompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, removeFromCRL, privilegeWithdrawn, aaCompromise, unspecified")
if err := fs.Parse(subArgs[1:]); err != nil {
return err
}
if *reason == "" {
fmt.Fprintf(os.Stderr, "error: --reason is required (no silent fallback to 'unspecified' — pick a real RFC 5280 §5.3.1 code).\n\n")
fmt.Fprintf(os.Stderr, "Valid reasons:\n")
for _, r := range cli.ValidRevokeReasons() {
fmt.Fprintf(os.Stderr, " %s\n", r)
}
return fmt.Errorf("--reason is required")
}
canonical, ok := cli.NormalizeRevokeReason(*reason)
if !ok {
fmt.Fprintf(os.Stderr, "error: %q is not a valid RFC 5280 §5.3.1 reason code.\n\n", *reason)
fmt.Fprintf(os.Stderr, "Valid reasons (camelCase or snake_case both accepted):\n")
for _, r := range cli.ValidRevokeReasons() {
fmt.Fprintf(os.Stderr, " %s\n", r)
}
return fmt.Errorf("invalid --reason: %q", *reason)
}
return client.RevokeCertificate(id, canonical)
case "bulk-revoke":
return client.BulkRevokeCertificates(subArgs)
default: