Track what happens to every certificate, and show it on the Certs tab

NPM knows what a certificate is today and nothing about what it was, so ten of them could fail renewal for months — 1001 certbot runs, zero successes — without anything on any page saying so. Counts start at zero and are only ever observed; only first_seen is seeded, from NPM's own date.
2026-08-15 18:51:38 -04:00
parent 13de1dab82
commit 71ba0a239f
6 changed files with 554 additions and 0 deletions
@@ -0,0 +1,45 @@
+#!/bin/bash
+# ==============================================================================================
+# ================================ Certificate History =========================================
+# ==============================================================================================
+#
+# PURPOSE
+# ─────────────────────────────────────────────────────────────────────────────
+# Records what happens to every certificate NPM holds — first seen, renewals, failures, and how
+# long each domain has been tracked — into DB_DIR/cert_history.json. The Certs tab reads it.
+#
+# NPM knows what a certificate is today and nothing about what it was, and cert_monitor.sh writes
+# a snapshot the next run overwrites. Ten certificates on this host had been failing renewal for
+# months without anything on any page being able to say so.
+#
+# ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# A wrapper. The work is in cert_history.php, next to the NPM client it needs — the API token
+# handling lives in include/auth.php and reimplementing it in bash to avoid a php call would be a
+# second copy of the thing most worth having only one of. Same split as api_cache_writer and
+# ai_repair_sweep.
+#
+# Counts start from zero on first run and are only ever observed. first_seen is seeded from NPM's
+# own created_on, which is a real date; nothing else is back-filled.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# cert_history.sh              one pass, updates the store
+# cert_history.sh --dry-run    reports what it would change, writes nothing
+# cert_history.sh --status     prints the store as a table
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# CERT_HISTORY_STRIKES   consecutive failed passes before a domain is retired (default 5)
+# DB_DIR                 cert_history.json is written here
+#
+# ==============================================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+php "$SCRIPT_DIR/cert_history.php" "$@"