Charon/docs/plans/current_spec.md

Certificate Deletion Feature — Spec

Date: 2026-03-22 Priority: Medium Type: User Requested Feature Status: Approved — Supervisor Reviewed 2026-03-22

---

1. Introduction

Overview

Users accumulate expired and orphaned certificates in the Certificates UI over time. Currently, the delete button is only shown for custom (manually uploaded) and staging certificates. Expired production Let's Encrypt certificates that are no longer attached to any proxy host cannot be removed, creating UI clutter and user confusion.

Objectives

1. Allow deletion of expired certificates that are not attached to any proxy host.
2. Allow deletion of custom (manually uploaded) certificates that are not attached to any proxy host, regardless of expiry status (already partially implemented).
3. Allow deletion of staging certificates that are not attached to any proxy host (already partially implemented).
4. Prevent deletion of any certificate currently attached to a proxy host.
5. Replace the native confirm() dialog with an accessible, themed confirmation dialog.
6. Provide clear visual feedback on why a certificate can or cannot be deleted.

Non-Goals

• Bulk certificate deletion (separate feature).
• Auto-cleanup / scheduled pruning of expired certificates.
• Changes to certificate auto-renewal logic.

---

2. Research Findings

2.1 Existing Backend Infrastructure

The backend already has complete delete support:

Component	File	Status
Model	backend/internal/models/ssl_certificate.go	SSLCertificate struct with Provider ("letsencrypt", "letsencrypt-staging", "custom"), ExpiresAt fields
Service	backend/internal/services/certificate_service.go	DeleteCertificate(id), IsCertificateInUse(id) — fully implemented
Handler	backend/internal/api/handlers/certificate_handler.go	Delete() — validates in-use, creates backup, deletes, sends notification
Route	backend/internal/api/routes/routes.go:673	DELETE /api/v1/certificates/:id — already registered
Error	backend/internal/services/certificate_service.go:23	ErrCertInUse sentinel error defined
Tests	backend/internal/api/handlers/certificate_handler_test.go	Tests for in-use, backup, backup failure, auth, invalid ID, not found

Key finding: The backend imposes NO provider or expiry restrictions on deletion. Any certificate can be deleted as long as it is not referenced by a proxy host (certificate_id FK). The backend is already correct for the requested feature.

2.2 Existing Frontend Infrastructure

Component	File	Status
API client	frontend/src/api/certificates.ts	deleteCertificate(id) — exists
Hook	frontend/src/hooks/useCertificates.ts	useCertificates() — react-query based
List component	frontend/src/components/CertificateList.tsx	Delete button and mutation — exists but gated incorrectly
Page	frontend/src/pages/Certificates.tsx	Upload dialog only
Cleanup dialog	frontend/src/components/dialogs/CertificateCleanupDialog.tsx	Used for proxy host deletion cleanup — not for standalone cert deletion
i18n	frontend/src/locales/en/translation.json:168-185	Certificate strings — needs new deletion strings

2.3 Current Delete Button Visibility Logic (The Problem)

In frontend/src/components/CertificateList.tsx:145:

{cert.id && (cert.provider === 'custom' || cert.issuer?.toLowerCase().includes('staging')) && (

This condition excludes expired production Let's Encrypt certificates, which is the core issue. An expired LE cert not attached to any host should be deletable.

2.4 Certificate-to-ProxyHost Relationship

• ProxyHost.CertificateID (*uint, nullable FK) → SSLCertificate.ID
• Defined in backend/internal/models/proxy_host.go:24-25
• GORM foreign key: gorm:"foreignKey:CertificateID"
• No cascade delete on the FK — deletion is manually guarded by IsCertificateInUse()
• Frontend checks in-use client-side via hosts.some(h => h.certificate_id === cert.id)

2.5 Provider Values

Provider Value	Source	Deletable?
letsencrypt	Auto-provisioned by Caddy ACME	Only when expired AND not in use
letsencrypt-staging	Staging ACME	When not in use (any status)
custom	User-uploaded via UI	When not in use (any status)

Note

: The model comment in ssl_certificate.go lists "self-signed" as a possible provider, but no code path ever writes that value. The actual provider universe is letsencrypt, letsencrypt-staging, custom. The stale comment should be corrected as part of this PR.

Edge Case: expiring LE Cert Not In Use

An expiring Let's Encrypt certificate that is not attached to any proxy host is in limbo — not expired yet, but no proxy host references it, so no renewal will be triggered. Decision: accept this as intended behavior. The cert will eventually expire and become deletable. We do not add expiring to the deletable set because Caddy may still auto-renew certificates that were previously provisioned, even if no host currently references them.

2.6 Existing UX Issues

1. Delete uses native confirm() — not accessible, not themed.
2. No tooltip or visual indicator explaining why a cert cannot be deleted.
3. The in-use check is duplicated: once client-side before confirm(), once server-side in the handler. This is fine (defense in depth) but the server is the source of truth.

---

3. Technical Specifications

3.1 Backend Changes

No backend code changes required. The existing DELETE /api/v1/certificates/:id endpoint already:

• Validates the certificate exists
• Checks IsCertificateInUse() and returns 409 Conflict if in use
• Creates a backup before deletion
• Deletes the DB record (and ACME files for LE certs)
• Invalidates the cert cache
• Sends a notification
• Returns 200 OK on success

The backend does not restrict by provider or expiry — all deletion policy is enforced by the frontend's visibility of the delete button and confirmed server-side by the in-use check.

3.2 Frontend Changes

3.2.1 Delete Button Visibility — CertificateList.tsx

Replace the current delete button condition with new business logic:

isDeletable(cert, hosts) =
  cert.id exists
  AND NOT isInUse(cert, hosts)
  AND (
    cert.provider === 'custom'
    OR cert.provider === 'letsencrypt-staging'
    OR cert.status === 'expired'
  )

Where isInUse(cert, hosts) checks:

hosts.some(h => (h.certificate_id ?? h.certificate?.id) === cert.id)

In plain terms:

• Custom / staging certs: deletable if not in use (any expiry status).
• Production LE certs: deletable only if expired AND not in use.
• Any cert in use by a proxy host: NOT deletable, regardless of status.

Important

: Use cert.provider === 'letsencrypt-staging' for staging detection — not cert.issuer?.toLowerCase().includes('staging'). The provider field is the canonical, authoritative classification. Issuer-based checks are fragile and may break if the ACME issuer string changes.

3.2.2 Confirmation Dialog — New DeleteCertificateDialog.tsx

Create frontend/src/components/dialogs/DeleteCertificateDialog.tsx:

• Reuse the existing Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter, Button UI components from frontend/src/components/ui.
• Show certificate name, domain, status, and provider.
• Warning text varies by cert type:
  • Custom: "This will permanently delete this certificate. A backup will be created first."
  • Staging: "This staging certificate will be removed. It will be regenerated on next request."
  • Expired LE: "This expired certificate is no longer active and will be permanently removed."
• Two buttons: Cancel (secondary) and Delete (destructive).
• Props: certificate: Certificate | null, onConfirm: () => void, onCancel: () => void, open: boolean, isDeleting: boolean.
• Keyboard accessible: focus trap, Escape to close, Enter on Delete button.

3.2.3 Disabled Delete Button with Tooltip

When a certificate is in use by a proxy host, render the delete button as aria-disabled="true" (not HTML disabled) with a Radix Tooltip explaining why. Using aria-disabled keeps the button focusable, which is required for the tooltip to appear on hover/focus.

Use the existing Radix-based Tooltip component from frontend/src/components/ui/Tooltip.tsx (Tooltip, TooltipTrigger, TooltipContent exports).

Tooltip text: "Cannot delete — certificate is attached to a proxy host".

When a production LE cert is valid/expiring (not expired) and not in use, do not show the delete button at all. Production LE certs in active use are auto-managed.

3.2.4 i18n Translation Keys

Add to frontend/src/locales/en/translation.json under "certificates":

"deleteTitle": "Delete Certificate",
"deleteConfirmCustom": "This will permanently delete this certificate. A backup will be created first.",
"deleteConfirmStaging": "This staging certificate will be removed. It will be regenerated on next request.",
"deleteConfirmExpired": "This expired certificate is no longer active and will be permanently removed.",
"deleteSuccess": "Certificate deleted",
"deleteFailed": "Failed to delete certificate",
"deleteInUse": "Cannot delete — certificate is attached to a proxy host",
"deleteButton": "Delete"

A shared "common.cancel" key already exists — use t('common.cancel') for the Cancel button instead of a certificate-specific key.

The same keys should be added to all other locale files (de, es, fr, pt) with placeholder English values (to be translated later).

3.2.5 Data Flow

User clicks delete icon → isDeletable check (client) → open DeleteCertificateDialog
  → User confirms → deleteMutation fires:
    1. deleteCertificate(id) → DELETE /api/v1/certificates/:id
       → Handler: IsCertificateInUse check (server)
       → Handler: createBackup (server)
       → Handler: DeleteCertificate (service)
       → Handler: notification
    2. Invalidate react-query cache → UI refreshes

Note: Remove the duplicate client-side createBackup() call from the mutation — the server already creates a backup. Keeping the client-side call creates two backups per deletion.

3.3 Database Considerations

• No schema changes needed. The ssl_certificates table and proxy_hosts.certificate_id FK are already correct.
• No cascade behavior changes. Deletion is guarded by the in-use check, not by DB cascades.
• The existing backup-before-delete behavior in the handler is sufficient for data safety.

3.4 Security Considerations

• Authorization: The DELETE /api/v1/certificates/:id route is under the management group which requires authentication middleware. No changes needed.
• Server-side validation: IsCertificateInUse() is checked server-side as defense-in-depth, preventing deletion even if the frontend check is bypassed.
• ID parameter: The handler uses numeric ID from URL param, validated with strconv.ParseUint. This prevents injection.
• Backup safety: A backup is created before every deletion. Low disk space is checked first (100MB minimum).

3.5 Accessibility Considerations

• New DeleteCertificateDialog must use the existing Dialog component which already provides focus trap, role="dialog", and aria-modal.
• Disabled delete buttons must use aria-disabled="true" (not HTML disabled) to remain focusable. Wrap in the Radix Tooltip / TooltipTrigger / TooltipContent from frontend/src/components/ui/Tooltip.tsx for an accessible visible tooltip (not just title attribute).
• The delete icon button needs aria-label for screen readers.

Known inconsistency: The existing CertificateCleanupDialog uses a hand-rolled overlay (<div className="fixed inset-0 bg-black/50 ...">) instead of the Radix Dialog component. This is a pre-existing issue — not in scope for this PR. Flagged as a future chore to migrate CertificateCleanupDialog to Radix Dialog for consistency.

3.6 Config/Build File Review

File	Change Needed?	Notes
.gitignore	No	No new artifacts to ignore
codecov.yml	No	New dialog component will be covered by existing frontend test config
.dockerignore	No	No new build inputs
Dockerfile	No	Frontend is built into dist/ as part of existing build stage

---

4. Implementation Plan

Phase 1: Playwright E2E Tests (Test-First)

File: tests/certificate-delete.spec.ts

Write E2E tests that define expected behavior:

1. Test: Delete button visible for expired cert not in use

   • Seed an expired custom cert with no proxy host attachment.
   • Navigate to Certificates page.
   • Verify delete button is visible for the expired cert row.

2. Test: Delete button visible for custom cert not in use

   • Seed a custom cert not attached to any proxy host.
   • Verify delete button is visible.

3. Test: Delete button disabled for cert in use

   • Seed a cert attached to a proxy host.
   • Verify delete button is aria-disabled="true" with tooltip text.

4. Test: Delete button NOT visible for valid production LE cert

   • Seed a valid LE cert not in use.
   • Verify no delete button (auto-managed, not expired).

5. Test: Confirmation dialog appears on delete click

   • Click delete on a deletable cert.
   • Verify dialog opens with cert details and Cancel/Delete buttons.
   • Click Cancel, verify dialog closes, cert still exists.

6. Test: Successful deletion flow

   • Click delete on a deletable cert.
   • Confirm in dialog.
   • Verify cert disappears from list.
   • Verify success toast appears.

7. Test: In-use cert shows disabled button with tooltip

   • Seed a cert in use.
   • Verify delete button has aria-disabled="true" and tooltip is shown on hover.

E2E Seeding Strategy

Certificates are scanned from Caddy's certificate storage, not manually inserted. Tests should seed data by:

1. Using the existing API to create proxy hosts with different SSL modes (which triggers cert provisioning by Caddy).
2. For expired/custom certs, use the certificate upload API (POST /api/v1/certificates) with pre-generated test certificates.
3. For in-use vs. not-in-use states, create/delete proxy host associations via the proxy host API.
4. Direct database manipulation is a last resort and should be avoided to keep tests realistic.

Complexity: Low — straightforward UI interaction tests.

Phase 2: Frontend Implementation

Estimated changes: ~3 files modified, 1 file created.

Step 1: Create DeleteCertificateDialog

File: frontend/src/components/dialogs/DeleteCertificateDialog.tsx

Props:
  - certificate: Certificate | null (from api/certificates.ts)
  - open: boolean
  - onConfirm: () => void
  - onCancel: () => void
  - isDeleting: boolean

Structure:
  - Dialog (open, onOpenChange=onCancel)
    - DialogContent
      - DialogHeader
        - DialogTitle: t('certificates.deleteTitle')
      - Certificate info: name, domain, status badge, provider
      - Warning text (varies by provider/status)
      - DialogFooter
        - Button (secondary): t('common.cancel')
        - Button (destructive, loading=isDeleting): Delete

Step 2: Update CertificateList.tsx

1. Extract isDeletable(cert, hosts) helper function.
2. Extract isInUse(cert, hosts) helper function.
3. Replace the inline delete button condition with isDeletable().
4. Add disabled delete button with tooltip for in-use certs.
5. Replace confirm() with DeleteCertificateDialog state management:
   • const [certToDelete, setCertToDelete] = useState<Certificate | null>(null)
   • Open dialog: setCertToDelete(cert)
   • Confirm: deleteMutation.mutate(certToDelete.id)
   • Cancel/success: setCertToDelete(null)
6. Remove the duplicate client-side createBackup() call from the mutation — the server already creates a backup. Keeping the client-side call creates two backups per deletion.

Step 3: Add i18n keys

Files: All locale files under frontend/src/locales/*/translation.json

Add the keys from §3.2.4.

Complexity: Low — mostly UI wiring, no new APIs.

Phase 3: Backend Unit Tests (Gap Coverage)

While the backend code needs no changes, add tests for the newly-important scenarios:

File: backend/internal/api/handlers/certificate_handler_test.go

1. Test: Delete expired LE cert not in use succeeds — ensures the backend does not block expired LE certs from deletion.
2. Test: Delete valid LE cert not in use succeeds — confirms the backend has no provider-based restrictions (policy is frontend-only).

The IsCertificateInUse service-level tests already exist in certificate_service_test.go. Do not duplicate them. Keep only the handler-level tests above that verify the HTTP layer behavior for expired LE cert deletion.

Complexity: Low — standard Go table-driven tests.

Phase 4: Frontend Unit Tests

File: frontend/src/components/__tests__/CertificateList.test.tsx

1. Test isDeletable() helper with all provider/status/in-use combinations.
2. Test that delete button renders for deletable certs.
3. Test that delete button is disabled for in-use certs.
4. Test that delete button is hidden for valid production LE certs.

File: frontend/src/components/dialogs/__tests__/DeleteCertificateDialog.test.tsx

5. Test dialog renders with correct warning text per provider.
6. Test Cancel closes dialog.
7. Test Delete calls onConfirm.

Complexity: Low.

Phase 5: Documentation

Update frontend/src/locales/en/translation.json key "noteText" to reflect the expanded deletion policy:

"You can delete custom certificates, staging certificates, and expired production certificates that are not attached to any proxy host. Active production certificates are automatically renewed by Caddy."

No other documentation changes needed — the feature is self-explanatory in the UI.

---

5. Acceptance Criteria

• Expired certificates not attached to any proxy host show a delete button.
• Custom certificates not attached to any proxy host show a delete button.
• Staging certificates not attached to any proxy host show a delete button.
• Certificates attached to a proxy host show a disabled delete button with tooltip.
• Valid production LE certificates not in use do NOT show a delete button.
• Clicking delete opens an accessible confirmation dialog (not native confirm()).
• Dialog shows certificate details and appropriate warning text.
• Confirming deletion removes the certificate and shows a success toast.
• Canceling the dialog does not delete anything.
• Server returns 409 Conflict if the certificate becomes attached between client check and server delete (race condition safety).
• A backup is created before each deletion (server-side).
• All new UI elements are keyboard navigable and screen-reader accessible.
• All Playwright E2E tests pass on Firefox, Chromium, and WebKit.
• All new backend unit tests pass.
• All new frontend unit tests pass.
• No regressions in existing certificate or proxy host tests.

---

6. Commit Slicing Strategy

Decision: Single PR

Rationale: The scope is small (1 new component, 2 modified files, i18n additions, and tests). All changes are tightly coupled — the new dialog component is only meaningful together with the updated delete button logic. Splitting this into multiple PRs would add review overhead without reducing risk.

PR-1: Certificate Deletion UX Enhancement

Scope: All phases (E2E tests, frontend implementation, backend test gaps, frontend unit tests, docs update).

Files:

File	Action
tests/certificate-delete.spec.ts	Create
frontend/src/components/dialogs/DeleteCertificateDialog.tsx	Create
frontend/src/components/dialogs/__tests__/DeleteCertificateDialog.test.tsx	Create
frontend/src/components/CertificateList.tsx	Modify
frontend/src/components/__tests__/CertificateList.test.tsx	Modify
frontend/src/locales/en/translation.json	Modify
frontend/src/locales/de/translation.json	Modify
frontend/src/locales/es/translation.json	Modify
frontend/src/locales/fr/translation.json	Modify
frontend/src/locales/pt/translation.json	Modify
backend/internal/api/handlers/certificate_handler_test.go	Modify

Dependencies: None — the backend API is already complete.

Validation Gates:

• go test ./backend/... — all pass
• npx vitest run — all pass
• Playwright E2E on Firefox, Chromium, WebKit — all pass
• make lint-fast — no new warnings

Rollback: Revert the single PR. No database migrations to undo. No backend API changes.

Contingency: If E2E tests are flaky due to certificate seed data timing, add explicit waitFor on the certificate list load state before asserting button visibility.