Document what the proxy and cert collectors guarantee

2026-08-25 16:37:25 -04:00
parent 6b9fda76db
commit 68c835f33b
3 changed files with 103 additions and 0 deletions
@@ -25,6 +25,40 @@
 # own created_on, which is a real date; nothing else is back-filled.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# History is accumulated, never reconstructed.
+#   NPM holds only the present, so every past state this file knows about is one it observed at
+#   the time. Counts start at zero on first run and nothing is back-filled — first_seen is the
+#   single exception, seeded from NPM's own created_on because that is a real recorded date
+#   rather than an inference.
+#
+# A domain is retired on strikes, not on a single bad pass.
+#   A pass fails for a domain when it is absent from NPM's list or its expiry is already in the
+#   past — and NPM's list can come back short for reasons that have nothing to do with the
+#   certificate, such as an API hiccup or a restart mid-pass. CERT_HISTORY_STRIKES consecutive
+#   failures are required before a domain is retired, and it stays in the store afterwards, so
+#   one bad read can neither erase months of history nor hide a genuine expiry.
+#
+# The wrapper holds no logic.
+#   The work sits next to the NPM client it needs, because token handling lives in
+#   include/auth.php and a bash reimplementation would be a second copy of the thing most worth
+#   having only one of. Flags are forwarded verbatim.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# The store is replaced atomically: temp file, verified, then renamed over the original. A pass
+# that fails partway leaves the previous history intact rather than a truncated file — this is
+# the only record of what these certificates did, and there is no second copy to restore from.
+#
+# --dry-run reports every change it would make and writes nothing. --status only reads.
+#
+# Read-only against NPM. Certificates are observed; nothing here renews, deletes or edits one.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #