diff --git a/docs/archive/upgrades/to-tls-v2.2.md b/docs/archive/upgrades/to-tls-v2.2.md index 02b0c7a..dc57dfa 100644 --- a/docs/archive/upgrades/to-tls-v2.2.md +++ b/docs/archive/upgrades/to-tls-v2.2.md @@ -1,5 +1,7 @@ # Upgrading to HTTPS-Everywhere (v2.2) +> Last reviewed: 2026-05-05 + > **Archived 2026-05-05.** This upgrade guide applies to certctl < v2.2. > Current operators on v2.2+ already have HTTPS-only control planes and > don't need this procedure. For the steady-state TLS reference, see diff --git a/docs/archive/upgrades/to-v2-jwt-removal.md b/docs/archive/upgrades/to-v2-jwt-removal.md index 75a3f36..8c03922 100644 --- a/docs/archive/upgrades/to-v2-jwt-removal.md +++ b/docs/archive/upgrades/to-v2-jwt-removal.md @@ -1,5 +1,7 @@ # Upgrading past G-1 — `CERTCTL_AUTH_TYPE=jwt` removal +> Last reviewed: 2026-05-05 + > **Archived 2026-05-05.** This upgrade guide applies to operators > upgrading past the G-1 milestone (the `CERTCTL_AUTH_TYPE=jwt` removal). > Current operators on post-G-1 releases don't need this. For the diff --git a/docs/compliance/index.md b/docs/compliance/index.md index ec7e010..6942f40 100644 --- a/docs/compliance/index.md +++ b/docs/compliance/index.md @@ -1,5 +1,7 @@ # Compliance Mapping Guides +> Last reviewed: 2026-05-05 + certctl is a certificate lifecycle management tool, not a compliance product. It doesn't make you compliant — your organization, policies, and processes do that. What certctl provides is tooling that supports the technical controls auditors and evaluators look for when assessing certificate and key management practices. These guides map certctl's features to three widely referenced compliance frameworks. They're designed for security engineers, IT auditors, and procurement teams evaluating certctl for environments with regulatory requirements. diff --git a/docs/compliance/nist-sp-800-57.md b/docs/compliance/nist-sp-800-57.md index 40580a6..68038eb 100644 --- a/docs/compliance/nist-sp-800-57.md +++ b/docs/compliance/nist-sp-800-57.md @@ -1,5 +1,7 @@ # NIST SP 800-57 Key Management Alignment +> Last reviewed: 2026-05-05 + NIST SP 800-57 Part 1 Rev 5 (May 2020) is the authoritative US government guidance on cryptographic key management. This document maps certctl's implementation to its recommendations. certctl follows NIST guidance where applicable; this guide documents the alignment and identifies gaps for future roadmap planning. ## Contents diff --git a/docs/compliance/pci-dss.md b/docs/compliance/pci-dss.md index 18308b2..436d8b8 100644 --- a/docs/compliance/pci-dss.md +++ b/docs/compliance/pci-dss.md @@ -1,5 +1,7 @@ # PCI-DSS 4.0 Compliance Mapping +> Last reviewed: 2026-05-05 + This guide maps certctl's existing capabilities to PCI-DSS 4.0 requirements relevant to TLS certificate and cryptographic key management. It is **not a compliance attestation** — a qualified security assessor (QSA) must evaluate your organization's complete control environment. Rather, this document helps you understand which PCI-DSS control objectives certctl supports and where operator responsibility lies. Organizations subject to PCI-DSS typically need to demonstrate control over certificate issuance, renewal, rotation, revocation, and key management. Certctl automates the technical controls for certificate lifecycle; compliance depends on how you deploy, monitor, and audit it. diff --git a/docs/compliance/soc2.md b/docs/compliance/soc2.md index c63e4e8..37a5710 100644 --- a/docs/compliance/soc2.md +++ b/docs/compliance/soc2.md @@ -1,5 +1,7 @@ # SOC 2 Type II Compliance Mapping +> Last reviewed: 2026-05-05 + This guide maps certctl's implemented features to AICPA SOC 2 Trust Service Criteria (TSC). It is **not a SOC 2 certification claim** — rather, it helps security engineers, auditors, and evaluators understand how certctl supports your organization's SOC 2 compliance posture. Use this as evidence input for your own control assessment during SOC 2 audits. ## How to Use This Guide diff --git a/docs/contributor/ci-pipeline.md b/docs/contributor/ci-pipeline.md index ca3dcaf..41da088 100644 --- a/docs/contributor/ci-pipeline.md +++ b/docs/contributor/ci-pipeline.md @@ -1,5 +1,7 @@ # CI Pipeline — Operator Guide +> Last reviewed: 2026-05-05 + > Authoritative guide to certctl's CI pipeline shape. > Per `cowork/ci-pipeline-cleanup-prompt.md` Phase 12. diff --git a/docs/contributor/qa-test-suite.md b/docs/contributor/qa-test-suite.md index 416aef1..9ea1ceb 100644 --- a/docs/contributor/qa-test-suite.md +++ b/docs/contributor/qa-test-suite.md @@ -1,5 +1,7 @@ # QA Test Suite Guide (`qa_test.go`) +> Last reviewed: 2026-05-05 + > **Audience:** Anyone running release QA for certctl — whether you're a first-time contributor or the maintainer cutting a release tag. > > **Companion to:** `docs/testing-guide.md` (the *what* to test). This document explains the *how* — the automated test file, what it covers, what it skips, and how to fill the gaps manually. diff --git a/docs/contributor/test-environment.md b/docs/contributor/test-environment.md index 52c337c..0d96b8a 100644 --- a/docs/contributor/test-environment.md +++ b/docs/contributor/test-environment.md @@ -1,5 +1,7 @@ # certctl Testing Environment +> Last reviewed: 2026-05-05 + A step-by-step guide to running certctl locally with real certificate authorities. Every command is spelled out. Every expected output is shown. If something goes wrong, the troubleshooting section tells you exactly what to check. --- diff --git a/docs/contributor/testing-strategy.md b/docs/contributor/testing-strategy.md index 4164277..f738c99 100644 --- a/docs/contributor/testing-strategy.md +++ b/docs/contributor/testing-strategy.md @@ -1,5 +1,7 @@ # certctl Testing Strategy & Deep-Scan Operator Runbook +> Last reviewed: 2026-05-05 + This doc covers the **testing topology** (per-PR fast gates vs. daily deep-scan gates), and the **operator runbook** for re-running each deep-scan tool locally when the CI receipt is ambiguous or when an operator wants to validate a fix diff --git a/docs/getting-started/advanced-demo.md b/docs/getting-started/advanced-demo.md index 24f8b51..f3cecfb 100644 --- a/docs/getting-started/advanced-demo.md +++ b/docs/getting-started/advanced-demo.md @@ -1,5 +1,7 @@ # Advanced Demo: Certificate Lifecycle End-to-End +> Last reviewed: 2026-05-05 + This demo goes beyond browsing pre-loaded data. You'll create a team, register an owner, set up an issuer, create a certificate, trigger renewal, and watch everything appear in the dashboard in real time. Each step includes a technical explanation of what's happening inside certctl and why the system is designed that way. **Time**: 15-20 minutes diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md index a6ef9da..b03d0f5 100644 --- a/docs/getting-started/concepts.md +++ b/docs/getting-started/concepts.md @@ -1,5 +1,7 @@ # Understanding Certificates: A Beginner's Guide +> Last reviewed: 2026-05-05 + If you've never worked with TLS certificates before, this guide will get you up to speed. By the end, you'll understand what certificates are, why they matter, and why the industry's move toward shorter certificate lifespans — down to 47 days by 2029 — makes automated lifecycle management essential. ## Contents diff --git a/docs/getting-started/examples.md b/docs/getting-started/examples.md index a19cc9f..9774c49 100644 --- a/docs/getting-started/examples.md +++ b/docs/getting-started/examples.md @@ -1,5 +1,7 @@ # Deployment Examples +> Last reviewed: 2026-05-05 + Five turnkey docker-compose scenarios, each runnable in under 5 minutes. Pick the one closest to your setup. ## Which Example Should I Use? diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 237fe5c..99e59d3 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -1,5 +1,7 @@ # Quick Start Guide +> Last reviewed: 2026-05-05 + Certificate lifespans are dropping to **47 days by 2029**. At that cadence, a team managing 100 certificates is processing 7+ renewals per week — every week, forever. Manual processes break. certctl automates the entire lifecycle: issuance, renewal, deployment, revocation, and audit — with zero human intervention. This guide gets you running in 5 minutes and walks you through everything certctl does. diff --git a/docs/getting-started/why-certctl.md b/docs/getting-started/why-certctl.md index aa8c33e..59696b3 100644 --- a/docs/getting-started/why-certctl.md +++ b/docs/getting-started/why-certctl.md @@ -1,5 +1,7 @@ # Why certctl? +> Last reviewed: 2026-05-05 + Certificate management is broken at every scale between "one domain on Let's Encrypt" and "Fortune 500 budget for Venafi." certctl fills that gap: a self-hosted platform that automates the entire certificate lifecycle, works with any CA, deploys to any server, and keeps private keys on your infrastructure. It's free, source-available, and you own everything. ## The Math That Forces the Decision diff --git a/docs/migration/acme-from-caddy.md b/docs/migration/acme-from-caddy.md index 98a8b68..61c4e2a 100644 --- a/docs/migration/acme-from-caddy.md +++ b/docs/migration/acme-from-caddy.md @@ -1,5 +1,7 @@ # Caddy Integration Walkthrough +> Last reviewed: 2026-05-05 + > **Use this walkthrough when** you're already running Caddy 2.7+ and > want it to ACME-issue from certctl (your internal CA, your private > PKI, or a local sub-CA chained under an enterprise root) instead of diff --git a/docs/migration/acme-from-cert-manager.md b/docs/migration/acme-from-cert-manager.md index d9a63c1..c41a19d 100644 --- a/docs/migration/acme-from-cert-manager.md +++ b/docs/migration/acme-from-cert-manager.md @@ -1,5 +1,7 @@ # cert-manager Integration Walkthrough +> Last reviewed: 2026-05-05 + > **Use this walkthrough when** you're already running cert-manager > 1.15+ in Kubernetes and want it to issue certs from certctl (your > internal CA, your private PKI, or a local sub-CA chained under an diff --git a/docs/migration/acme-from-traefik.md b/docs/migration/acme-from-traefik.md index e703eec..f269edc 100644 --- a/docs/migration/acme-from-traefik.md +++ b/docs/migration/acme-from-traefik.md @@ -1,5 +1,7 @@ # Traefik Integration Walkthrough +> Last reviewed: 2026-05-05 + > **Use this walkthrough when** you're already running Traefik 3.0+ > (Kubernetes or VM) and want it to ACME-issue from certctl (your > internal CA, your private PKI, or a local sub-CA chained under an diff --git a/docs/migration/cert-manager-coexistence.md b/docs/migration/cert-manager-coexistence.md index f939c3a..d12ea74 100644 --- a/docs/migration/cert-manager-coexistence.md +++ b/docs/migration/cert-manager-coexistence.md @@ -1,5 +1,7 @@ # certctl for cert-manager Users +> Last reviewed: 2026-05-05 + You run cert-manager inside Kubernetes and it works well for in-cluster certificates. But you also have VMs, bare-metal servers, network appliances, and legacy systems outside the cluster. cert-manager can't reach those. This guide shows how certctl complements cert-manager to give you unified certificate visibility and automation across your entire infrastructure. ## Not a Replacement diff --git a/docs/migration/from-acmesh.md b/docs/migration/from-acmesh.md index 2f3a760..3d9fe04 100644 --- a/docs/migration/from-acmesh.md +++ b/docs/migration/from-acmesh.md @@ -1,5 +1,7 @@ # Migrate from acme.sh to certctl +> Last reviewed: 2026-05-05 + You use acme.sh to automate Let's Encrypt renewal across multiple servers. It works — but without centralized visibility, deployment verification, or policy enforcement. This guide walks through moving your acme.sh workload to certctl while keeping your existing DNS provider setup. diff --git a/docs/migration/from-certbot.md b/docs/migration/from-certbot.md index 50c667d..45bde2c 100644 --- a/docs/migration/from-certbot.md +++ b/docs/migration/from-certbot.md @@ -1,5 +1,7 @@ # Migrating from Certbot to certctl +> Last reviewed: 2026-05-05 + You have 50 Let's Encrypt certificates across 10 servers, managed by a mix of Certbot cron jobs and manual renewals. Certbot handles issuance, but you lack inventory visibility, centralized alerting, and audit trails. This guide walks you through moving to certctl while keeping your existing certificates and ACME account. ## Why Migrate diff --git a/docs/operator/approval-workflow.md b/docs/operator/approval-workflow.md index e11eb3c..afdb9dc 100644 --- a/docs/operator/approval-workflow.md +++ b/docs/operator/approval-workflow.md @@ -1,5 +1,7 @@ # Issuance approval workflow +> Last reviewed: 2026-05-05 + certctl can gate certificate issuance + renewal on a per-profile, two-person-integrity check. Compliance customers (PCI-DSS Level 1, FedRAMP Moderate / High, SOC 2 Type II, HIPAA) configure this on production-tier `CertificateProfile` rows so every renewal-loop tick or manual `POST /api/v1/certificates/{id}/renew` blocks at `JobStatusAwaitingApproval` until a different actor approves. Closes the procurement-checklist question "How do you enforce two-person integrity on cert issuance?" — without this surface the answer is "we don't"; with `requires_approval=true` on the profile, the answer is "here's the RBAC contract + here's the audit query that proves bypass mode is off in production." diff --git a/docs/operator/database-tls.md b/docs/operator/database-tls.md index afff50c..f527b59 100644 --- a/docs/operator/database-tls.md +++ b/docs/operator/database-tls.md @@ -1,5 +1,7 @@ # Database TLS — Postgres Transport Encryption +> Last reviewed: 2026-05-05 + **Audit reference:** Bundle B / M-018. PCI-DSS v4.0 Req 4 §2.2.5; CWE-319. certctl talks to Postgres over a single connection-string URL controlled by the diff --git a/docs/operator/runbooks/cloud-targets.md b/docs/operator/runbooks/cloud-targets.md index 7391792..2cbc88f 100644 --- a/docs/operator/runbooks/cloud-targets.md +++ b/docs/operator/runbooks/cloud-targets.md @@ -1,5 +1,7 @@ # Runbook: cloud-target deployment connectors (AWS ACM + Azure Key Vault) +> Last reviewed: 2026-05-05 + This runbook covers the SDK-driven cloud target connectors that ship in certctl post-2026-05-03 (Rank 5 of the Infisical deep-research deliverable). It complements the operator-facing diff --git a/docs/operator/runbooks/disaster-recovery.md b/docs/operator/runbooks/disaster-recovery.md index 8957fd0..b7c217f 100644 --- a/docs/operator/runbooks/disaster-recovery.md +++ b/docs/operator/runbooks/disaster-recovery.md @@ -1,5 +1,7 @@ # Disaster recovery runbook +> Last reviewed: 2026-05-05 + > **Status (this document):** Production hardening II Phase 10 > deliverable. Codifies the fail-safe behaviors that already exist in > the codebase and the operator procedures for recovering from diff --git a/docs/operator/runbooks/expiry-alerts.md b/docs/operator/runbooks/expiry-alerts.md index a493531..33fabf8 100644 --- a/docs/operator/runbooks/expiry-alerts.md +++ b/docs/operator/runbooks/expiry-alerts.md @@ -1,5 +1,7 @@ # Runbook: certificate-expiry alerts (multi-channel) +> Last reviewed: 2026-05-05 + This runbook covers the per-policy multi-channel expiry-alert dispatch path that ships in certctl post-2026-05-03 (Rank 4 of the Infisical deep-research deliverable). It complements the operator-facing diff --git a/docs/operator/security.md b/docs/operator/security.md index f3337bc..f423dc5 100644 --- a/docs/operator/security.md +++ b/docs/operator/security.md @@ -1,5 +1,7 @@ # certctl Security Posture & Operator Guidance +> Last reviewed: 2026-05-05 + This document collects the operator-facing security guidance that the source code's per-finding comment blocks reference. Each section names the audit finding it closes, the threat model, and the operator action required (if diff --git a/docs/operator/tls.md b/docs/operator/tls.md index 9bd4041..cec76ad 100644 --- a/docs/operator/tls.md +++ b/docs/operator/tls.md @@ -1,5 +1,7 @@ # TLS on the Control Plane +> Last reviewed: 2026-05-05 + certctl's control plane is HTTPS-only as of v2.2. There is no plaintext `http://` listener, no `auto` mode, no dual-listener bridge, no TLS 1.2 escape hatch. The server refuses to start without a cert+key pair, the agent/CLI/MCP clients reject `http://` URLs at startup, and the Helm chart refuses to render without either an operator-supplied Secret or a cert-manager Certificate CR. This doc covers four cert provisioning patterns, SIGHUP-based cert rotation, and the client-side CA-trust configuration agents and the CLI need to talk to the server. If you are upgrading from a pre-HTTPS release and want the step-by-step cutover procedure, read [`upgrade-to-tls.md`](upgrade-to-tls.md) first and come back here for reference. diff --git a/docs/reference/api.md b/docs/reference/api.md index 9eb3a59..b0d41d9 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -1,5 +1,7 @@ # OpenAPI Specification Guide +> Last reviewed: 2026-05-05 + certctl ships with a complete OpenAPI 3.1 specification at `api/openapi.yaml`. This spec documents all 78 API operations currently specified, every request/response schema, pagination conventions, authentication requirements, and error formats. It's the single source of truth for the documented REST API. (Note: The spec will be updated to include 7 additional certificate discovery endpoints from M18b.) This guide covers how to use the spec for API exploration, client SDK generation, and integration testing. diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 0bf0b6d..3780574 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -1,5 +1,7 @@ # Architecture Guide +> Last reviewed: 2026-05-05 + ## Contents 1. [Overview](#overview) diff --git a/docs/reference/deployment-model.md b/docs/reference/deployment-model.md index 7ec2054..c3f1219 100644 --- a/docs/reference/deployment-model.md +++ b/docs/reference/deployment-model.md @@ -1,5 +1,7 @@ # Deployment Atomicity, Post-Deploy Verification, and Rollback +> Last reviewed: 2026-05-05 + > Deploy-hardening I master bundle (v2.X.0). Operator + integrator > reference for the atomic-write + post-deploy TLS verify + > rollback pipeline that closes the procurement-checklist gap with diff --git a/docs/reference/intermediate-ca-hierarchy.md b/docs/reference/intermediate-ca-hierarchy.md index 7fa7689..654a06d 100644 --- a/docs/reference/intermediate-ca-hierarchy.md +++ b/docs/reference/intermediate-ca-hierarchy.md @@ -1,5 +1,7 @@ # Intermediate CA hierarchy — operator runbook +> Last reviewed: 2026-05-05 + Rank 8 of the 2026-05-03 deep-research deliverable. This page is the canonical reference for operators running certctl as a multi-level internal PKI. diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md index bda5080..ee81305 100644 --- a/docs/reference/mcp.md +++ b/docs/reference/mcp.md @@ -1,5 +1,7 @@ # MCP Server Guide +> Last reviewed: 2026-05-05 + certctl ships with an MCP (Model Context Protocol) server that lets AI assistants manage your certificate infrastructure through natural language. Ask Claude to "show me all expiring certificates," "revoke the VPN cert," or "what agents are offline?" and the MCP server translates that into API calls against your certctl instance. This guide covers setup, configuration, and usage with Claude, Cursor, and other MCP-compatible tools. diff --git a/docs/reference/protocols/acme-server-threat-model.md b/docs/reference/protocols/acme-server-threat-model.md index 05b570b..c09960a 100644 --- a/docs/reference/protocols/acme-server-threat-model.md +++ b/docs/reference/protocols/acme-server-threat-model.md @@ -1,5 +1,7 @@ # ACME Server — Threat Model +> Last reviewed: 2026-05-05 + Security posture for the certctl ACME server endpoint (`/acme/profile//*`). Read this before opening a PR that changes the JWS verifier, the challenge validators, the rate limiter, or the diff --git a/docs/reference/protocols/acme-server.md b/docs/reference/protocols/acme-server.md index 3f3d363..4c7857d 100644 --- a/docs/reference/protocols/acme-server.md +++ b/docs/reference/protocols/acme-server.md @@ -1,5 +1,7 @@ # certctl ACME Server (Built-in) +> Last reviewed: 2026-05-05 + certctl ships an RFC 8555 + RFC 9773 ARI ACME server endpoint at `/acme/profile//*`. Any RFC 8555 client (cert-manager 1.15+, Caddy, Traefik, win-acme, certbot, Posh-ACME) can integrate with certctl diff --git a/docs/reference/protocols/async-ca-polling.md b/docs/reference/protocols/async-ca-polling.md index c3b058a..308fdd2 100644 --- a/docs/reference/protocols/async-ca-polling.md +++ b/docs/reference/protocols/async-ca-polling.md @@ -1,5 +1,7 @@ # Async-CA Polling — Operator Reference +> Last reviewed: 2026-05-05 + Closes audit fix #5 from the 2026-05-01 issuer-coverage acquisition-readiness audit. ## What this is diff --git a/docs/reference/protocols/crl-ocsp.md b/docs/reference/protocols/crl-ocsp.md index c79c44d..f6bdc71 100644 --- a/docs/reference/protocols/crl-ocsp.md +++ b/docs/reference/protocols/crl-ocsp.md @@ -1,5 +1,7 @@ # CRL & OCSP — Revocation Status for Relying Parties +> Last reviewed: 2026-05-05 + This guide is the operator + relying-party reference for certctl's revocation status surfaces. It covers the wire format, endpoint URLs, configuration knobs, the OCSP responder cert lifecycle, and how to point common consumers diff --git a/docs/reference/protocols/est.md b/docs/reference/protocols/est.md index a20fb24..3f938c1 100644 --- a/docs/reference/protocols/est.md +++ b/docs/reference/protocols/est.md @@ -1,5 +1,7 @@ # EST (RFC 7030) — Operator Guide +> Last reviewed: 2026-05-05 + > **Status (this document):** EST RFC 7030 hardening master bundle Phases > 1–11 shipped on `master`; this guide is the Phase-12 deliverable > against the bundle. Every behavior described here is exercised by the diff --git a/docs/reference/protocols/scep-intune.md b/docs/reference/protocols/scep-intune.md index 3812053..4a5e239 100644 --- a/docs/reference/protocols/scep-intune.md +++ b/docs/reference/protocols/scep-intune.md @@ -1,5 +1,7 @@ # Microsoft Intune SCEP enrollment via certctl +> Last reviewed: 2026-05-05 + > **Status (this document):** Phase 11 of the SCEP RFC 8894 + Intune master > bundle. The behavior described here is shipped on `master` and exercised > end-to-end by `internal/api/handler/scep_intune_e2e_test.go`. The diff --git a/docs/reference/vendor-matrix.md b/docs/reference/vendor-matrix.md index 4bd3668..b1ddb59 100644 --- a/docs/reference/vendor-matrix.md +++ b/docs/reference/vendor-matrix.md @@ -1,5 +1,7 @@ # Deployment Vendor Compatibility Matrix +> Last reviewed: 2026-05-05 + > Deploy-hardening II master bundle deliverable. The procurement-team > headline doc — SOC 2 / PCI auditors paste this into evidence packs. > Per frozen decision 0.14: a (connector × vendor-version) cell is diff --git a/docs/testing-guide.md b/docs/testing-guide.md index a425923..29925bc 100644 --- a/docs/testing-guide.md +++ b/docs/testing-guide.md @@ -1,5 +1,7 @@ # certctl V2.1 Release QA Guide +> Last reviewed: 2026-05-05 + Comprehensive manual testing playbook. Every test has a concrete command, an explanation of what it validates and why it matters, exact expected output, and an unambiguous pass/fail criterion. ## Contents