mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 20:41:30 +00:00
0725713e19
Operator decision answered as full soft-delete with optional forced
cascade — hard-delete is not reachable from any public surface. Prior
to this commit, DELETE /agents/{id} ran a plain `DELETE FROM agents`
whose schema-level `ON DELETE CASCADE` on deployment_targets.agent_id
silently wiped every target, orphaning certs and aborting in-flight
jobs. The finding closure reshapes the agent-removal contract around
soft retirement with explicit preflight counts, an opt-in cascade
gated by a mandatory reason, and unconditional protection for the
four reserved sentinel agents used by discovery sources.
Schema — migration 000015:
migrations/000015_agent_retire.up.sql flips
deployment_targets_agent_id_fkey from ON DELETE CASCADE to ON DELETE
RESTRICT, so a stray `DELETE FROM agents` now errors at the DB
boundary instead of quietly destroying targets. Both `agents` and
`deployment_targets` grow a retired_at TIMESTAMPTZ + retired_reason
TEXT pair (TEXT not VARCHAR so operator comments are never
truncated), indexed via partial indexes WHERE retired_at IS NOT
NULL. The migration is self-healing (ADD COLUMN IF NOT EXISTS, DROP
CONSTRAINT IF EXISTS then ADD CONSTRAINT, CREATE INDEX IF NOT
EXISTS) so repeated runs against partially-migrated databases
converge. migrations/000015_agent_retire.down.sql restores CASCADE
and drops the new columns for clean rollback. A dedicated
repository-layer testcontainers test
(internal/repository/postgres/migration_000015_test.go) asserts the
before/after FK action, column presence, index presence, and
round-trip idempotency under up→down→up.
Domain — sentinel guard + dependency counts:
internal/domain/connector.go gains IsRetired() on Agent, the
exported SentinelAgentIDs slice listing server-scanner,
cloud-aws-sm, cloud-azure-kv, cloud-gcp-sm verbatim (matching the
four reserved IDs documented in CLAUDE.md and created at startup in
cmd/server/main.go), IsSentinelAgent(id string) predicate,
AgentDependencyCounts{ActiveTargets, ActiveCertificates,
PendingJobs} with a HasDependencies() method, and ActorTypeAgent /
ActorTypeSystem enum values used by audit emission downstream.
Coverage locked down by internal/domain/connector_test.go.
Service — 8-step ordered contract:
internal/service/agent_retire.go:RetireAgent(ctx, id, actor,
opts{Force, Reason}) enforces a fixed execution order:
(1) sentinel guard — IsSentinelAgent(id) returns ErrAgentIsSentinel
unconditionally; force=true does NOT bypass it.
(2) fetch — ErrAgentNotFound on miss.
(3) idempotency — if IsRetired() already, return
AgentRetirementResult{AlreadyRetired: true} with no new audit
event and no state change (safe to replay from flaky clients).
(4) preflight counts — collectAgentDependencyCounts runs
ActiveTargets, ActiveCertificates, PendingJobs sequentially
(not in parallel; keeps the per-query timeout predictable and
matches the repo's existing call-chain shape).
(5) force-reason guard — opts.Force=true with empty Reason returns
ErrForceReasonRequired (wired into the 400 status surface).
(6) dependency guard — HasDependencies() with opts.Force=false
returns BlockedByDependenciesError{Counts} (wired into the 409
body with per-bucket counts).
(7) mutation — single pinned retiredAt := time.Now(); agent
retirement first, then cascade target retirement if opts.Force,
all under the repo's single transaction so the two retired_at
stamps match to the second.
(8) best-effort audit — agent_retired always; agent_retirement_
cascaded additionally on the force path. Actor is whatever the
handler resolves from the request; actor type is mapped by
resolveActorType (system/agent-prefix→Agent/else→User). Audit
emission failures are logged via slog.Error but do not abort
the retirement (matches the house convention used by every
other scheduler-emitted event).
BlockedByDependenciesError implements Error() as
"active_targets=%d, active_certificates=%d, pending_jobs=%d" and
Unwrap() → ErrBlockedByDependencies. The single struct satisfies
errors.Is via Unwrap (used by scheduler-level tests) and errors.As
via the concrete type (used by the handler to fish out Counts for
the 409 body). ListRetiredAgents(page, perPage) adds a separate
paginated accessor with page<1→1 and perPage<1→50 normalization so
retired rows are queryable without polluting the default agent
listing.
Sentinel guard coverage is asymmetric by design: all four reserved
IDs are protected, and force=true cannot override. Regression tests
in internal/service/agent_retire_test.go assert each of the eight
steps in order, plus sentinel bypass attempts and idempotency
replay.
Handler + router — status-code surface:
internal/api/handler/agents.go:RetireAgent exposes seven status
codes on DELETE /agents/{id}:
200 on a fresh retirement (body echoes AgentRetirementResult).
204 on idempotent replay (AlreadyRetired=true; no new audit).
400 on ErrForceReasonRequired.
403 on ErrAgentIsSentinel.
404 on ErrAgentNotFound.
409 on BlockedByDependenciesError, with a custom body shape
{error, counts{active_targets, active_certificates,
pending_jobs}} that bypasses the default ErrorWithRequestID
envelope so callers get the per-bucket numbers directly.
500 on any other error.
Heartbeat HandleHeartbeat returns 410 Gone when the agent is
retired (ErrAgentRetired), signalling the agent to shut down.
Query params `force=true` and `reason=<text>` drive the cascade
path; both are forwarded as url.Values through the new MCP
transport.
internal/api/router/router.go registers GET /api/v1/agents/retired
literal-path BEFORE /api/v1/agents/{id} — Go 1.22 ServeMux's
literal-beats-pattern-var precedence routes "retired" to the
paginated retired-agents listing instead of fetching a hypothetical
agent named "retired".
Agent binary — clean shutdown on 410:
cmd/agent/main.go gains the ErrAgentRetired sentinel, a
retiredOnce sync.Once, and a retiredSignal chan struct{}. A
markRetired(source, statusCode, body) helper closes the channel
exactly once; the Run() select loop observes the close and returns
ErrAgentRetired; main() matches via errors.Is(err, ErrAgentRetired)
and exits cleanly instead of spinning in the heartbeat retry loop.
The 410 Gone surface is therefore terminal for the agent process.
MCP transport:
internal/mcp/client.go adds Client.DeleteWithQuery(path, query),
a new additive transport method. Client.Delete is path-only; without
this method the retire tool would silently drop `force` and `reason`,
turning every cascade retire into a default soft-retire. The new
method shares do()'s 204 normalization and 4xx/5xx error
propagation so tool authors get one contract.
internal/mcp/tools.go + internal/mcp/types.go expose the
retire_agent tool with Force+Reason inputs wired through
DeleteWithQuery.
CLI:
cmd/cli/main.go + internal/cli/client.go add two CLI surfaces:
`agents list --retired` (client-side strip of --retired then
delegation to ListRetiredAgents, sharing --page/--per-page parsing
with the default listing) and `agents retire <id> [--force --reason
"…"]` (mirrors ErrForceReasonRequired — force without reason is
rejected client-side before the request is sent). JSON + table
output modes both honor the new columns.
Frontend:
web/src/pages/AgentsPage.tsx surfaces retired/retire affordances.
web/src/api/client.ts + web/src/api/types.ts expose the retire
endpoint and the retired-listing. 4 new Vitest regression cases.
OpenAPI:
api/openapi.yaml documents DELETE /agents/{id} with all seven
status codes, 410 on heartbeat, and the 409 per-bucket body shape.
Regression coverage (six new test files, all green):
internal/service/agent_retire_test.go — 8-step contract + sentinel guards
internal/api/handler/agent_retire_handler_test.go — 7-status-code surface + 410 heartbeat
internal/mcp/retire_agent_test.go — DeleteWithQuery wire-through
internal/cli/agent_retire_test.go — --retired listing + --force/--reason pairing
internal/repository/postgres/migration_000015_test.go — FK flip + columns + indexes + up↔down
internal/domain/connector_test.go — IsRetired, IsSentinelAgent, SentinelAgentIDs, HasDependencies
Files:
api/openapi.yaml — DELETE + 410 + 409 body shape
cmd/agent/main.go — ErrAgentRetired, markRetired, retiredSignal
cmd/cli/main.go — handleAgents list/get/retire dispatch
docs/architecture.md, docs/concepts.md,
docs/testing-guide.md — retirement contract narrative
internal/api/handler/agents.go — RetireAgent, status surface, 410 on heartbeat
internal/api/handler/agent_handler_test.go — extended coverage
internal/api/handler/agent_retire_handler_test.go — new
internal/api/router/router.go — /agents/retired before /agents/{id}
internal/cli/agent_retire_test.go — new
internal/cli/client.go — ListRetiredAgents + RetireAgent
internal/domain/connector.go — IsRetired, SentinelAgentIDs,
IsSentinelAgent, AgentDependencyCounts,
ActorTypeAgent/System
internal/domain/connector_test.go — new
internal/integration/lifecycle_test.go — retirement fixture
internal/mcp/client.go — DeleteWithQuery additive transport
internal/mcp/retire_agent_test.go — new
internal/mcp/tools.go, internal/mcp/types.go — retire_agent tool + Force/Reason inputs
internal/repository/interfaces.go — AgentRepository retirement methods
internal/repository/postgres/agent.go — retire + cascade target retire + counts
internal/repository/postgres/migration_000015_test.go — new
internal/service/agent.go — wire into AgentService surface
internal/service/agent_retire.go — new 8-step contract
internal/service/agent_retire_test.go — new
internal/service/deployment.go — skip retired agents
internal/service/target.go — skip retired agents
internal/service/testutil_test.go — shared mocks extended
migrations/000015_agent_retire.up.sql — new
migrations/000015_agent_retire.down.sql — new
web/src/api/client.ts, types.ts + tests — retire endpoint wiring
web/src/pages/AgentsPage.tsx — retire UI
240 lines
6.1 KiB
Go
240 lines
6.1 KiB
Go
package main
|
|
|
|
import (
|
|
"flag"
|
|
"fmt"
|
|
"os"
|
|
|
|
"github.com/shankar0123/certctl/internal/cli"
|
|
)
|
|
|
|
func main() {
|
|
// Parse global flags
|
|
fs := flag.NewFlagSet("certctl-cli", flag.ExitOnError)
|
|
fs.Usage = func() {
|
|
fmt.Fprintf(os.Stderr, `certctl-cli — CLI for certificate lifecycle management
|
|
|
|
Usage:
|
|
certctl-cli [global flags] <command> [command flags]
|
|
|
|
Global flags:
|
|
`)
|
|
fs.PrintDefaults()
|
|
fmt.Fprintf(os.Stderr, `
|
|
Commands:
|
|
certs list List certificates
|
|
certs get ID Get certificate details
|
|
certs renew ID Trigger certificate renewal
|
|
certs revoke ID Revoke a certificate
|
|
|
|
agents list List agents (add --retired to list soft-retired agents)
|
|
agents get ID Get agent details
|
|
agents retire ID Soft-retire an agent (add --force --reason "…" to cascade)
|
|
|
|
jobs list List jobs
|
|
jobs get ID Get job details
|
|
jobs cancel ID Cancel a pending job
|
|
|
|
import FILE Bulk import certificates from PEM file(s)
|
|
Required: --owner-id, --team-id, --renewal-policy-id, --issuer-id
|
|
Optional: --name-template (default {cn}), --environment (default imported)
|
|
|
|
status Show server health + summary stats
|
|
version Show CLI version
|
|
|
|
Examples:
|
|
certctl-cli --server http://localhost:8443 --api-key mykey certs list
|
|
certctl-cli certs renew mc-prod --format json
|
|
certctl-cli import certs.pem
|
|
`)
|
|
}
|
|
|
|
serverURL := fs.String("server", os.Getenv("CERTCTL_SERVER_URL"), "certctl server URL (env: CERTCTL_SERVER_URL)")
|
|
if *serverURL == "" {
|
|
*serverURL = "http://localhost:8443"
|
|
}
|
|
|
|
apiKey := fs.String("api-key", os.Getenv("CERTCTL_API_KEY"), "API key for authentication (env: CERTCTL_API_KEY)")
|
|
format := fs.String("format", "table", "Output format: table, json")
|
|
|
|
fs.Parse(os.Args[1:])
|
|
|
|
args := fs.Args()
|
|
if len(args) == 0 {
|
|
fs.Usage()
|
|
os.Exit(1)
|
|
}
|
|
|
|
// Create client
|
|
client := cli.NewClient(*serverURL, *apiKey, *format)
|
|
|
|
// Dispatch to appropriate command
|
|
command := args[0]
|
|
cmdArgs := args[1:]
|
|
|
|
var err error
|
|
switch command {
|
|
case "certs":
|
|
err = handleCerts(client, cmdArgs)
|
|
case "agents":
|
|
err = handleAgents(client, cmdArgs)
|
|
case "jobs":
|
|
err = handleJobs(client, cmdArgs)
|
|
case "import":
|
|
err = handleImport(client, cmdArgs)
|
|
case "status":
|
|
err = handleStatus(client)
|
|
case "version":
|
|
fmt.Println("certctl-cli version 0.1.0")
|
|
default:
|
|
fmt.Fprintf(os.Stderr, "unknown command: %s\n", command)
|
|
fs.Usage()
|
|
os.Exit(1)
|
|
}
|
|
|
|
if err != nil {
|
|
fmt.Fprintf(os.Stderr, "error: %v\n", err)
|
|
os.Exit(1)
|
|
}
|
|
}
|
|
|
|
func handleCerts(client *cli.Client, args []string) error {
|
|
if len(args) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: certs <list|get|renew|revoke> [options]\n")
|
|
return nil
|
|
}
|
|
|
|
subcommand := args[0]
|
|
subArgs := args[1:]
|
|
|
|
switch subcommand {
|
|
case "list":
|
|
return client.ListCertificates(subArgs)
|
|
case "get":
|
|
if len(subArgs) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: certs get <id>\n")
|
|
return nil
|
|
}
|
|
return client.GetCertificate(subArgs[0])
|
|
case "renew":
|
|
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")
|
|
return nil
|
|
}
|
|
id := subArgs[0]
|
|
reason := "unspecified"
|
|
if len(subArgs) > 2 && subArgs[1] == "--reason" {
|
|
reason = subArgs[2]
|
|
}
|
|
return client.RevokeCertificate(id, reason)
|
|
case "bulk-revoke":
|
|
return client.BulkRevokeCertificates(subArgs)
|
|
default:
|
|
fmt.Fprintf(os.Stderr, "unknown subcommand: certs %s\n", subcommand)
|
|
return nil
|
|
}
|
|
}
|
|
|
|
// handleAgents dispatches the `agents` subcommands.
|
|
//
|
|
// I-004 additions:
|
|
//
|
|
// agents list --retired — hit the opt-in /agents/retired endpoint
|
|
// instead of the default listing (which
|
|
// filters retired rows out).
|
|
// agents retire <id> — soft-retire an agent (DELETE /agents/{id}).
|
|
// --force cascades; --reason is required with
|
|
// --force (mirrors ErrForceReasonRequired).
|
|
func handleAgents(client *cli.Client, args []string) error {
|
|
if len(args) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: agents <list|get|retire> [options]\n")
|
|
return nil
|
|
}
|
|
|
|
subcommand := args[0]
|
|
subArgs := args[1:]
|
|
|
|
switch subcommand {
|
|
case "list":
|
|
// --retired flag splits to a separate endpoint. We intercept it
|
|
// client-side and strip it before delegating, so both code paths
|
|
// share the --page/--per-page flag parsing inside the client.
|
|
retired := false
|
|
rest := make([]string, 0, len(subArgs))
|
|
for _, a := range subArgs {
|
|
if a == "--retired" {
|
|
retired = true
|
|
continue
|
|
}
|
|
rest = append(rest, a)
|
|
}
|
|
if retired {
|
|
return client.ListRetiredAgents(rest)
|
|
}
|
|
return client.ListAgents(rest)
|
|
case "get":
|
|
if len(subArgs) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: agents get <id>\n")
|
|
return nil
|
|
}
|
|
return client.GetAgent(subArgs[0])
|
|
case "retire":
|
|
if len(subArgs) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: agents retire <id> [--force] [--reason <reason>]\n")
|
|
return nil
|
|
}
|
|
return client.RetireAgent(subArgs)
|
|
default:
|
|
fmt.Fprintf(os.Stderr, "unknown subcommand: agents %s\n", subcommand)
|
|
return nil
|
|
}
|
|
}
|
|
|
|
func handleJobs(client *cli.Client, args []string) error {
|
|
if len(args) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: jobs <list|get|cancel> [options]\n")
|
|
return nil
|
|
}
|
|
|
|
subcommand := args[0]
|
|
subArgs := args[1:]
|
|
|
|
switch subcommand {
|
|
case "list":
|
|
return client.ListJobs(subArgs)
|
|
case "get":
|
|
if len(subArgs) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: jobs get <id>\n")
|
|
return nil
|
|
}
|
|
return client.GetJob(subArgs[0])
|
|
case "cancel":
|
|
if len(subArgs) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: jobs cancel <id>\n")
|
|
return nil
|
|
}
|
|
return client.CancelJob(subArgs[0])
|
|
default:
|
|
fmt.Fprintf(os.Stderr, "unknown subcommand: jobs %s\n", subcommand)
|
|
return nil
|
|
}
|
|
}
|
|
|
|
func handleImport(client *cli.Client, args []string) error {
|
|
if len(args) == 0 {
|
|
fmt.Fprintf(os.Stderr, "usage: import <file> [file2 ...]\n")
|
|
return nil
|
|
}
|
|
return client.ImportCertificates(args)
|
|
}
|
|
|
|
func handleStatus(client *cli.Client) error {
|
|
return client.GetStatus()
|
|
}
|