npm-acme-authority/README.md

NPM ACME Authority

Runtime ACME write fencing for Nginx Proxy Manager.

The project patches NPM certificate handling at container startup so that selected Let's Encrypt mutation paths require a Pacemaker-controlled authority token.

Gate configuration

• ACME_GATE_REQUEST=true
• ACME_GATE_RENEW=true
• ACME_GATE_REVOKE=true

These variables determine which ACME operations require authority.

They do not grant authority.

Runtime authority

Authority is represented by:

/acme_authority/state/acme-authority

The intended production mapping is:

/etc/npm-acme-authority  -> /acme_authority
/run/npm-acme-authority -> /acme_authority/state

The persistent code mount is read-only.

The runtime state mount is read-only from the container's perspective and is controlled by Pacemaker on the host.

Intended policy

REQUEST:

• Gate Let's Encrypt creation before database insertion.

RENEW:

• Gate automatic and manual renewal before Certbot execution.

REVOKE:

• Gate certificate deletion before the database row is marked deleted.
• Gate Certbot revocation again as defense in depth.

Safety

Requested mutations must fail closed.

If an expected NPM source anchor cannot be identified or verification fails, the patcher must exit non-zero rather than start an ungated NPM backend.

Cluster-managed certificates

Optional cluster-managed custom certificate support is enabled with:

ACME_CLUSTER_CERT=true

This does not grant ACME authority and does not currently perform renewal.

When enabled it:

• adds meta.cluster_managed as an explicit boolean certificate property;
• adds meta.acme_renew as an explicit boolean certificate property;
• preserves the logical domain_names already stored on a custom certificate when new certificate material is uploaded.

Cluster-managed certificates remain provider=other.

The serving certificate therefore remains under:

/data/custom_ssl/npm-<id>

and is independent from any Certbot lineage under /etc/letsencrypt.