gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-08 17:49:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
d2ebe1bc0071a03a4146d23768710f226034cfdf
certctl/internal/mcp/types.go
T
Shankar Reddy fb4362e534 fix(api,web,mcp): add bulk-renew + bulk-reassign endpoints, drop client-side N×HTTP loops (L-1 master) 
Two audit findings, both category cat-l, both rooted in
web/src/pages/CertificatesPage.tsx. Pre-L-1 the GUI looped per-cert
HTTP calls — 100 selected certs = 100 sequential round-trips × ~50–200
ms each = a 5–20-second wedge during which the operator stared at a
progress bar. Post-L-1 each workflow is a single POST.

  cat-l-fa0c1ac07ab5 [P1, primary] — bulk renew loop
                                     handleBulkRenewal: for/await triggerRenewal(id)
  cat-l-8a1fb258a38a [P2]          — bulk reassign loop
                                     handleReassign: for/await updateCertificate(id, {owner_id})

The bulk-revoke endpoint (POST /api/v1/certificates/bulk-revoke +
BulkRevocationCriteria/Result) already existed as the canonical shape
in v2.0.x — L-1 ports that pattern to renew + reassign with per-action
twists.

Backend (Go)
- internal/domain/bulk_renewal.go: BulkRenewalCriteria mirrors
  BulkRevocationCriteria (criteria + IDs modes); BulkRenewalResult
  envelope adds EnqueuedJobs[] for per-cert {certificate_id, job_id};
  shared BulkOperationError type for all bulk paths.
- internal/domain/bulk_reassignment.go: narrower shape — IDs-only,
  owner_id required, team_id optional.
- internal/service/bulk_renewal.go::BulkRenewalService.BulkRenew:
  resolves criteria → status filter (Archived/Revoked/Expired/
  RenewalInProgress all silent-skip) → per-cert status flip + job
  create. Keygen-mode-aware so jobs land in the same initial status
  as single-cert TriggerRenewal. Single bulk audit event per call,
  not N.
- internal/service/bulk_reassignment.go::BulkReassignmentService.
  BulkReassign: validates owner_id upfront via the
  ErrBulkReassignOwnerNotFound typed sentinel — non-existent owner
  returns 400 before any cert is touched. Already-owned-by-target
  is silent-skip. Single bulk audit event.
- internal/api/handler/{bulk_renewal,bulk_reassignment}.go: HTTP
  shape mirrors bulk_revocation.go. NOT admin-gated (renew is non-
  destructive; reassign is a common-case workflow). Sentinel-error
  → 400 mapping for OwnerNotFound.
- internal/api/router/router.go: three bulk-* routes registered as a
  block before the {id} routes. HandlerRegistry gains BulkRenewal +
  BulkReassignment fields.
- cmd/server/main.go: NewBulkRenewalService threads cfg.Keygen.Mode
  so bulk-renew jobs land in same initial state as single-cert path.

Frontend
- web/src/api/client.ts: bulkRenewCertificates(criteria) +
  bulkReassignCertificates(request) functions with full TS types.
- web/src/pages/CertificatesPage.tsx: handleBulkRenewal + handleReassign
  rewritten from N-call loops to single calls. Result envelope drives
  progress UI; first-error message surfaced when total_failed > 0.
  Stale triggerRenewal + updateCertificate imports removed.

MCP
- internal/mcp/types.go: BulkRenewCertificatesInput +
  BulkReassignCertificatesInput.
- internal/mcp/tools.go: certctl_bulk_renew_certificates +
  certctl_bulk_reassign_certificates tools mirroring the existing
  certctl_bulk_revoke_certificates pattern.

OpenAPI
- api/openapi.yaml: two new operations (bulkRenewCertificates,
  bulkReassignCertificates) under Certificates tag. Four new schemas
  (BulkRenewRequest, BulkRenewResult, BulkEnqueuedJob,
  BulkReassignRequest, BulkReassignResult).

Tests
- Domain: BulkRenewalCriteria.IsEmpty + BulkReassignmentRequest.IsEmpty
  IsEmpty contracts; JSON round-trip shape pinning.
- Service: 7 BulkRenew tests (happy/criteria-mode/skips-RenewalInProgress/
  skips-revoked-archived/empty-criteria-error/partial-failure/
  audit-event-emitted) + 8 BulkReassign tests (happy/skips-already-
  owned/owner-required/empty-IDs/owner-not-found-sentinel/team-id-
  optional/team-id-provided/partial-failure/audit-event-emitted).
- Handler: 5 BulkRenew handler tests (happy/empty-body-400/wrong-
  method-405/actor-attribution/service-error-500) + 6 BulkReassign
  handler tests (happy/empty-IDs-400/missing-owner-400/owner-not-
  found-400-via-sentinel/wrong-method-405/generic-error-500).

CI guardrail
- .github/workflows/ci.yml: 'Forbidden client-side bulk-action loop
  regression guard (L-1)'. Greps web/src/pages/CertificatesPage.tsx
  for 'for(...) await triggerRenewal(...)' and 'for(...) await
  updateCertificate(...)' patterns; comment lines exempt; test files
  exempt. Verified locally (passes against post-fix tree, fires
  against synthetic regression).

Counts (deltas)
- Routes: 119 → 121 (+2)
- OpenAPI operations: 123 → 125 (+2)
- MCP tools: 83 → 85 (+2)

Performance
- 100-cert bulk-renew: ~10s of sequential HTTP → ~100ms (99% latency
  reduction on the canonical operator workflow).
- Audit event volume: 1 + N per operation → 1.

Out of scope (deferred follow-ups)
- cat-b-31ceb6aaa9f1: updateOwner/updateTeam/updateAgentGroup orphan
  (different shape — wire existing PUT to GUI, not new bulk endpoint).
- cat-k-e85d1099b2d7: CertificatesPage no pagination UI.
- cat-i-b0924b6675f8: MCP missing claim/dismiss/acknowledge (L-1 added
  2 new tools but does not close that finding).

Verification
- go build / vet / test -short / test -short -race all clean.
- web tsc --noEmit + vitest run all clean (296 tests passing).
- OpenAPI YAML parses (89 paths, 125 ops).
- L-1 CI guardrail passes against post-fix tree, fires against
  synthetic regression.

No push.
2026-04-25 14:33:02 +00:00

328 lines
19 KiB
Go
Raw Blame History

package mcp
// Input types for MCP tool arguments.
// The jsonschema struct tags provide descriptions for LLM tool discovery.
// ── Pagination ──────────────────────────────────────────────────────
type ListParams struct {
Page int `json:"page,omitempty" jsonschema:"Page number (default 1)"`
PerPage int `json:"per_page,omitempty" jsonschema:"Results per page (default 50, max 500)"`
}
// ── Certificates ────────────────────────────────────────────────────
type ListCertificatesInput struct {
ListParams
Status string `json:"status,omitempty" jsonschema:"Filter by status: Pending, Active, Expiring, Expired, RenewalInProgress, Failed, Revoked, Archived"`
Environment string `json:"environment,omitempty" jsonschema:"Filter by environment"`
OwnerID string `json:"owner_id,omitempty" jsonschema:"Filter by owner ID"`
TeamID string `json:"team_id,omitempty" jsonschema:"Filter by team ID"`
IssuerID string `json:"issuer_id,omitempty" jsonschema:"Filter by issuer ID"`
}
type GetByIDInput struct {
ID string `json:"id" jsonschema:"Resource ID (e.g. mc-api-prod, t-platform)"`
}
type CreateCertificateInput struct {
ID string `json:"id,omitempty" jsonschema:"Certificate ID (auto-generated if empty)"`
Name string `json:"name" jsonschema:"Display name"`
CommonName string `json:"common_name" jsonschema:"Certificate common name (e.g. api.example.com)"`
SANs []string `json:"sans,omitempty" jsonschema:"Subject Alternative Names"`
Environment string `json:"environment,omitempty" jsonschema:"Environment (e.g. production, staging)"`
OwnerID string `json:"owner_id" jsonschema:"Owner ID (required)"`
TeamID string `json:"team_id" jsonschema:"Team ID (required)"`
IssuerID string `json:"issuer_id" jsonschema:"Issuer connector ID"`
TargetIDs []string `json:"target_ids,omitempty" jsonschema:"Deployment target IDs"`
RenewalPolicyID string `json:"renewal_policy_id" jsonschema:"Renewal policy ID (required)"`
ProfileID string `json:"certificate_profile_id,omitempty" jsonschema:"Certificate profile ID"`
Tags map[string]string `json:"tags,omitempty" jsonschema:"Key-value tags"`
}
type UpdateCertificateInput struct {
ID string `json:"id" jsonschema:"Certificate ID to update"`
Name string `json:"name,omitempty" jsonschema:"Display name"`
Environment string `json:"environment,omitempty" jsonschema:"Environment"`
OwnerID string `json:"owner_id,omitempty" jsonschema:"Owner ID"`
TeamID string `json:"team_id,omitempty" jsonschema:"Team ID"`
TargetIDs []string `json:"target_ids,omitempty" jsonschema:"Deployment target IDs"`
RenewalPolicyID string `json:"renewal_policy_id,omitempty" jsonschema:"Renewal policy ID"`
ProfileID string `json:"certificate_profile_id,omitempty" jsonschema:"Certificate profile ID"`
Tags map[string]string `json:"tags,omitempty" jsonschema:"Key-value tags"`
}
type TriggerDeploymentInput struct {
ID string `json:"id" jsonschema:"Certificate ID"`
TargetID string `json:"target_id,omitempty" jsonschema:"Optional specific target ID"`
}
type RevokeCertificateInput struct {
ID string `json:"id" jsonschema:"Certificate ID to revoke"`
Reason string `json:"reason,omitempty" jsonschema:"RFC 5280 reason: unspecified, keyCompromise, caCompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn"`
}
type BulkRevokeCertificatesInput struct {
Reason string `json:"reason" jsonschema:"RFC 5280 reason: unspecified, keyCompromise, caCompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn"`
ProfileID string `json:"profile_id,omitempty" jsonschema:"Revoke all certs matching this profile ID"`
OwnerID string `json:"owner_id,omitempty" jsonschema:"Revoke all certs owned by this owner"`
AgentID string `json:"agent_id,omitempty" jsonschema:"Revoke all certs deployed via this agent"`
IssuerID string `json:"issuer_id,omitempty" jsonschema:"Revoke all certs issued by this issuer"`
TeamID string `json:"team_id,omitempty" jsonschema:"Revoke all certs owned by members of this team"`
CertificateIDs []string `json:"certificate_ids,omitempty" jsonschema:"Explicit list of certificate IDs to revoke"`
}
// L-1 master closure (cat-l-fa0c1ac07ab5): bulk-renew MCP tool input.
// Mirrors BulkRevokeCertificatesInput field-for-field minus Reason.
type BulkRenewCertificatesInput struct {
ProfileID string `json:"profile_id,omitempty" jsonschema:"Renew all certs matching this profile ID"`
OwnerID string `json:"owner_id,omitempty" jsonschema:"Renew all certs owned by this owner"`
AgentID string `json:"agent_id,omitempty" jsonschema:"Renew all certs deployed via this agent"`
IssuerID string `json:"issuer_id,omitempty" jsonschema:"Renew all certs issued by this issuer"`
TeamID string `json:"team_id,omitempty" jsonschema:"Renew all certs owned by members of this team"`
CertificateIDs []string `json:"certificate_ids,omitempty" jsonschema:"Explicit list of certificate IDs to renew"`
}
// L-2 closure (cat-l-8a1fb258a38a): bulk-reassign MCP tool input.
// IDs-only — no criteria-mode.
type BulkReassignCertificatesInput struct {
CertificateIDs []string `json:"certificate_ids" jsonschema:"Explicit list of certificate IDs to reassign"`
OwnerID string `json:"owner_id" jsonschema:"Required. New owner_id for every cert in certificate_ids"`
TeamID string `json:"team_id,omitempty" jsonschema:"Optional. When non-empty, also updates team_id on every cert"`
}
type ListVersionsInput struct {
ID string `json:"id" jsonschema:"Certificate ID"`
ListParams
}
// ── CRL & OCSP ──────────────────────────────────────────────────────
type GetDERCRLInput struct {
IssuerID string `json:"issuer_id" jsonschema:"Issuer ID for DER-encoded CRL"`
}
type OCSPInput struct {
IssuerID string `json:"issuer_id" jsonschema:"Issuer ID"`
Serial string `json:"serial" jsonschema:"Hex-encoded certificate serial number"`
}
// ── Issuers ─────────────────────────────────────────────────────────
type CreateIssuerInput struct {
ID string `json:"id,omitempty" jsonschema:"Issuer ID"`
Name string `json:"name" jsonschema:"Issuer display name"`
Type string `json:"type" jsonschema:"Issuer type: ACME, GenericCA, StepCA"`
Config interface{} `json:"config,omitempty" jsonschema:"Issuer-specific configuration"`
Enabled bool `json:"enabled,omitempty" jsonschema:"Whether the issuer is enabled"`
}
type UpdateIssuerInput struct {
ID string `json:"id" jsonschema:"Issuer ID to update"`
Name string `json:"name,omitempty" jsonschema:"Issuer display name"`
Type string `json:"type,omitempty" jsonschema:"Issuer type"`
Config interface{} `json:"config,omitempty" jsonschema:"Issuer-specific configuration"`
Enabled *bool `json:"enabled,omitempty" jsonschema:"Whether the issuer is enabled"`
}
// ── Targets ─────────────────────────────────────────────────────────
type CreateTargetInput struct {
ID string `json:"id,omitempty" jsonschema:"Target ID"`
Name string `json:"name" jsonschema:"Target display name"`
Type string `json:"type" jsonschema:"Target type: NGINX, Apache, HAProxy, F5, IIS"`
AgentID string `json:"agent_id" jsonschema:"Agent ID that manages this target (required)"`
Config interface{} `json:"config,omitempty" jsonschema:"Target-specific configuration"`
Enabled bool `json:"enabled,omitempty" jsonschema:"Whether the target is enabled"`
}
type UpdateTargetInput struct {
ID string `json:"id" jsonschema:"Target ID to update"`
Name string `json:"name,omitempty" jsonschema:"Target display name"`
Type string `json:"type,omitempty" jsonschema:"Target type"`
AgentID string `json:"agent_id,omitempty" jsonschema:"Agent ID"`
Config interface{} `json:"config,omitempty" jsonschema:"Target-specific configuration"`
Enabled *bool `json:"enabled,omitempty" jsonschema:"Whether the target is enabled"`
}
// ── Agents ──────────────────────────────────────────────────────────
type RegisterAgentInput struct {
ID string `json:"id,omitempty" jsonschema:"Agent ID"`
Name string `json:"name" jsonschema:"Agent display name"`
Hostname string `json:"hostname" jsonschema:"Agent hostname"`
}
type AgentCSRInput struct {
AgentID string `json:"agent_id" jsonschema:"Agent ID"`
CSRPEM string `json:"csr_pem" jsonschema:"PEM-encoded certificate signing request"`
CertificateID string `json:"certificate_id,omitempty" jsonschema:"Certificate ID for the CSR"`
}
type AgentPickupInput struct {
AgentID string `json:"agent_id" jsonschema:"Agent ID"`
CertID string `json:"cert_id" jsonschema:"Certificate ID to pick up"`
}
type AgentJobStatusInput struct {
AgentID string `json:"agent_id" jsonschema:"Agent ID"`
JobID string `json:"job_id" jsonschema:"Job ID"`
Status string `json:"status" jsonschema:"Job status to report"`
Error string `json:"error,omitempty" jsonschema:"Error message if job failed"`
}
// RetireAgentInput pins the MCP tool surface for certctl_retire_agent. I-004
// introduces a soft-retirement flow that the handler exposes on DELETE
// /api/v1/agents/{id} with two optional query flags: force=true cascades
// through dependent active targets/certs/jobs, and reason is the human-readable
// string captured in the audit trail. The handler enforces
// ErrForceReasonRequired when force=true is sent without a reason; we surface
// both as separate fields so the LLM can populate them independently and so
// the retire_agent_test shape assertion stays aligned with the JSON-wire
// contract. ID is always emitted (no omitempty) because a retire call without
// a target agent is meaningless; Force and Reason are omitempty so the default
// soft-retire path sends no query suffix at all.
type RetireAgentInput struct {
ID string `json:"id" jsonschema:"Agent ID to soft-retire"`
Force bool `json:"force,omitempty" jsonschema:"Cascade-retire downstream active targets, certs, and jobs (requires reason)"`
Reason string `json:"reason,omitempty" jsonschema:"Human-readable reason (required when force=true)"`
}
// ── Jobs ────────────────────────────────────────────────────────────
type ListJobsInput struct {
ListParams
Status string `json:"status,omitempty" jsonschema:"Filter by status: Pending, AwaitingCSR, AwaitingApproval, Running, Completed, Failed, Cancelled"`
Type string `json:"type,omitempty" jsonschema:"Filter by type: Issuance, Renewal, Deployment, Validation"`
}
type RejectJobInput struct {
ID string `json:"id" jsonschema:"Job ID to reject"`
Reason string `json:"reason,omitempty" jsonschema:"Reason for rejection"`
}
// ── Notifications ───────────────────────────────────────────────────
// ListNotificationsInput adds the I-005 status filter on top of the standard
// pagination params. Status="dead" drives the Dead letter tab use case;
// empty status preserves the pre-I-005 list-all behavior.
type ListNotificationsInput struct {
ListParams
Status string `json:"status,omitempty" jsonschema:"Filter by status: pending, sent, failed, dead, read"`
}
// ── Policies ────────────────────────────────────────────────────────
type CreatePolicyInput struct {
ID string `json:"id,omitempty" jsonschema:"Policy ID"`
Name string `json:"name" jsonschema:"Policy display name"`
Type string `json:"type" jsonschema:"Policy type: AllowedIssuers, AllowedDomains, RequiredMetadata, AllowedEnvironments, RenewalLeadTime"`
Config interface{} `json:"config,omitempty" jsonschema:"Policy-specific configuration"`
Enabled bool `json:"enabled,omitempty" jsonschema:"Whether the policy is enabled"`
Severity string `json:"severity,omitempty" jsonschema:"Violation severity: Warning, Error, or Critical (default: Warning)"`
}
type UpdatePolicyInput struct {
ID string `json:"id" jsonschema:"Policy ID to update"`
Name string `json:"name,omitempty" jsonschema:"Policy display name"`
Type string `json:"type,omitempty" jsonschema:"Policy type"`
Config interface{} `json:"config,omitempty" jsonschema:"Policy-specific configuration"`
Enabled *bool `json:"enabled,omitempty" jsonschema:"Whether the policy is enabled"`
Severity string `json:"severity,omitempty" jsonschema:"Violation severity: Warning, Error, or Critical"`
}
type ListViolationsInput struct {
ID string `json:"id" jsonschema:"Policy ID"`
ListParams
}
// ── Profiles ────────────────────────────────────────────────────────
type CreateProfileInput struct {
ID string `json:"id,omitempty" jsonschema:"Profile ID"`
Name string `json:"name" jsonschema:"Profile display name"`
Description string `json:"description,omitempty" jsonschema:"Profile description"`
AllowedKeyAlgorithms interface{} `json:"allowed_key_algorithms,omitempty" jsonschema:"Allowed key algorithms and minimum sizes"`
MaxTTLSeconds int `json:"max_ttl_seconds,omitempty" jsonschema:"Maximum certificate TTL in seconds"`
AllowedEKUs []string `json:"allowed_ekus,omitempty" jsonschema:"Allowed Extended Key Usages"`
RequiredSANPatterns []string `json:"required_san_patterns,omitempty" jsonschema:"Required SAN patterns"`
AllowShortLived bool `json:"allow_short_lived,omitempty" jsonschema:"Allow short-lived certificates (TTL < 1 hour)"`
Enabled bool `json:"enabled,omitempty" jsonschema:"Whether the profile is enabled"`
}
type UpdateProfileInput struct {
ID string `json:"id" jsonschema:"Profile ID to update"`
Name string `json:"name,omitempty" jsonschema:"Profile display name"`
Description string `json:"description,omitempty" jsonschema:"Profile description"`
AllowedKeyAlgorithms interface{} `json:"allowed_key_algorithms,omitempty" jsonschema:"Allowed key algorithms and minimum sizes"`
MaxTTLSeconds *int `json:"max_ttl_seconds,omitempty" jsonschema:"Maximum certificate TTL in seconds"`
AllowedEKUs []string `json:"allowed_ekus,omitempty" jsonschema:"Allowed Extended Key Usages"`
RequiredSANPatterns []string `json:"required_san_patterns,omitempty" jsonschema:"Required SAN patterns"`
AllowShortLived *bool `json:"allow_short_lived,omitempty" jsonschema:"Allow short-lived certificates"`
Enabled *bool `json:"enabled,omitempty" jsonschema:"Whether the profile is enabled"`
}
// ── Teams ───────────────────────────────────────────────────────────
type CreateTeamInput struct {
ID string `json:"id,omitempty" jsonschema:"Team ID"`
Name string `json:"name" jsonschema:"Team name"`
Description string `json:"description,omitempty" jsonschema:"Team description"`
}
type UpdateTeamInput struct {
ID string `json:"id" jsonschema:"Team ID to update"`
Name string `json:"name,omitempty" jsonschema:"Team name"`
Description string `json:"description,omitempty" jsonschema:"Team description"`
}
// ── Owners ──────────────────────────────────────────────────────────
type CreateOwnerInput struct {
ID string `json:"id,omitempty" jsonschema:"Owner ID"`
Name string `json:"name" jsonschema:"Owner display name"`
Email string `json:"email,omitempty" jsonschema:"Owner email for notifications"`
TeamID string `json:"team_id,omitempty" jsonschema:"Team ID the owner belongs to"`
}
type UpdateOwnerInput struct {
ID string `json:"id" jsonschema:"Owner ID to update"`
Name string `json:"name,omitempty" jsonschema:"Owner display name"`
Email string `json:"email,omitempty" jsonschema:"Owner email"`
TeamID string `json:"team_id,omitempty" jsonschema:"Team ID"`
}
// ── Agent Groups ────────────────────────────────────────────────────
type CreateAgentGroupInput struct {
ID string `json:"id,omitempty" jsonschema:"Agent group ID"`
Name string `json:"name" jsonschema:"Group display name"`
Description string `json:"description,omitempty" jsonschema:"Group description"`
MatchOS string `json:"match_os,omitempty" jsonschema:"Match agents by OS (e.g. linux, darwin, windows)"`
MatchArchitecture string `json:"match_architecture,omitempty" jsonschema:"Match agents by architecture (e.g. amd64, arm64)"`
MatchIPCIDR string `json:"match_ip_cidr,omitempty" jsonschema:"Match agents by IP CIDR range"`
MatchVersion string `json:"match_version,omitempty" jsonschema:"Match agents by version"`
Enabled bool `json:"enabled,omitempty" jsonschema:"Whether the group is enabled"`
}
type UpdateAgentGroupInput struct {
ID string `json:"id" jsonschema:"Agent group ID to update"`
Name string `json:"name,omitempty" jsonschema:"Group display name"`
Description string `json:"description,omitempty" jsonschema:"Group description"`
MatchOS string `json:"match_os,omitempty" jsonschema:"Match agents by OS"`
MatchArchitecture string `json:"match_architecture,omitempty" jsonschema:"Match agents by architecture"`
MatchIPCIDR string `json:"match_ip_cidr,omitempty" jsonschema:"Match agents by IP CIDR range"`
MatchVersion string `json:"match_version,omitempty" jsonschema:"Match agents by version"`
Enabled *bool `json:"enabled,omitempty" jsonschema:"Whether the group is enabled"`
}
// ── Stats ───────────────────────────────────────────────────────────
type TimelineInput struct {
Days int `json:"days,omitempty" jsonschema:"Number of days to look back (default 30, max 365)"`
}
// ── Empty ───────────────────────────────────────────────────────────
type EmptyInput struct{}
Reference in New Issue View Git Blame Copy Permalink