feat: add lifecycle.use-latest so certificate-id follows server-side renewals

[carlosmonastyrski]

Description 📣

Extends the certificate agent's existing certificate-id distribution mode with lifecycle.use-latest, so a fleet of hosts sharing one centrally managed certificate automatically picks up renewals made in Infisical without a config change or a restart. The agent resolves the current certificate from the server in one call regardless of how far the chain has moved on, rewrites files and runs on-renewal only when the certificate it resolves to actually changes (including across a restart, where it compares against what is on disk rather than in memory), reports revoked and expired certificates through on-failure while continuing to serve the last good certificate, and refuses to overwrite a certificate when it cannot also replace the matching private key. renew-before-expiry warns and is ignored in this mode.

Type ✨

• Bug fix
• New feature
• Improvement
• Breaking change
• Documentation

Tests 🛠️

# Here's some code block to paste some code snippets

---

• I have read the contributing guide, agreed and acknowledged the code of conduct. 📝

[linear]

PKI-372

[infisical-review-police]

💬 Discussion in Slack: #pr-review-cli-374-feat-add-lifecycle-use-latest-so-certificate-id-follows-server

Posted by Review Police — reviews, comments, new commits, and CI failures will stream into this channel.

[greptile-apps]

Greptile Summary

The PR adds lifecycle.use-latest to certificate-ID distribution, allowing the agent to follow server-side certificate renewals while preserving the last delivered certificate when a newer result is unusable.

• Extends certificate API models with renewal-chain identifiers.
• Resolves and installs the latest renewal, classifies issuance versus renewal across restarts, and invokes the corresponding hooks.
• Adds status reporting, retry cooldown behavior, disk-state comparisons, and protection against replacing a certificate without its matching private key.
• Adds focused unit and end-to-end coverage plus sample configuration documentation.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code failure or SSRF path identified.

Renewal resolution remains constrained to the configured Infisical API origin, certificate and key replacement is guarded before mutation in the new distribution path, and the monitoring state transitions preserve periodic checks while deduplicating terminal-status hooks.

Important Files Changed

Filename	Overview
packages/cmd/agent.go	Implements latest-renewal resolution, certificate synchronization, disk-state comparison, hook selection, status handling, retry scheduling, and key-pair replacement safeguards; no actionable changed-code defect was established.
packages/api/model.go	Adds the server response fields needed to identify the immediate and latest renewal certificates with JSON names aligned to their callers.
packages/cmd/agent_cert_latest_renewal_test.go	Adds focused coverage for renewal resolution, fallback behavior, configuration validation, and keyless replacement safeguards.
e2e/agent/certificate_test.go	Adds end-to-end scenarios for pinned and latest distribution, restarts, hooks, and revoked-certificate handling.
e2e/agent/agent_helpers.go	Extends certificate-agent fixtures to configure certificate-ID distribution and directly issue, renew, revoke, and inspect test certificates.
certificate-agent-config.yaml	Documents shared certificate distribution and the new use-latest lifecycle option.

_{Reviews (1): Last reviewed commit: "feat(agent): add lifecycle.use-latest so..." | Re-trigger Greptile}