v0.28.1

docs/API.md

@@ -389,7 +389,7 @@ previous snapshot stays active. The response contains `reloaded`, `revision`, `p
 handshakes use the refreshed certificates; established connections are not renegotiated.
 Administration TLS is startup-fixed and therefore reports when a process restart is needed.
 
-`POST /api/certificates/{certificate_id}/reload` is the targeted variant for a manual/file-backed certificate (`issuer == null`). It validates the requested configured ID and atomically republishes the immutable TLS snapshot at the same configuration revision. It is intended for external renewers that replace the files already referenced by RustProxy. Application-managed ACME certificate IDs are rejected with `409` because their renewal pipeline owns those files. The endpoint accepts either the normal administrator session + CSRF flow or a scoped Certificate API token.
+`POST /api/certificates/{certificate_id}/reload` is the targeted variant for a manual/file-backed certificate (`issuer == null`). It validates the requested configured ID and atomically republishes the immutable TLS snapshot at the same configuration revision. It is intended for external renewers that replace the files already referenced by RustProxy. A manual entry may use simple filenames from `<data-dir>/certs` or two absolute external paths such as `/etc/letsencrypt/live/example/fullchain.pem` and `/etc/letsencrypt/live/example/privkey.pem`. Absolute paths are resolved again on every reload, so Certbot's `live/` symlinks follow the newly renewed generation. Application-managed ACME certificate IDs are rejected with `409` because their renewal pipeline owns those files. The endpoint accepts either the normal administrator session + CSRF flow or a scoped Certificate API token.
 
 `POST /api/certificates/deploy` accepts
 `{"certificate_id":"shared-cert","cert_pem":"...","key_pem":"..."}` under the same
@@ -414,8 +414,9 @@ CLI deploy hook, which calls that loopback API after bounded local file checks:
 The command resolves Certbot's local `live/` symlinks, checks bounded regular files/private-key permissions, then sends the pair to `POST /api/certificates/deploy`. The running service validates the certificate/key and DNS SANs, stages generation-specific files inside RustProxy's private certificate directory, and creates or switches the **manual** certificate id through the normal revision-CAS configuration path. A single id may already be selected by multiple vhosts, so those vhosts switch together
 without individual edits. RustProxy-managed ACME entries (`issuer != null`) are rejected to
 avoid two renewal owners for the same lineage. The existing `/api/certificates/upload` remains
-the generic PEM staging endpoint; private certificate paths are never accepted from a remote
-request.
+the generic PEM staging endpoint; deploy/upload request bodies never accept host filesystem
+paths. Absolute paths may only be saved explicitly in administrator TLS configuration as a
+manual certificate source, where they are validated and never returned as PEM contents.
 
 ## 0.23.0 scoped Certificate API credentials
 
@@ -428,6 +429,17 @@ Authorization: Bearer <token>
 X-RustProxy-Certificate-Key: <key-id>
 ```
 
+Example Certbot/acme.sh post-renew reload for an external-path certificate:
+
+```bash
+curl --fail --show-error -X POST \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'X-RustProxy-Certificate-Key: certbot-main' \
+  -H 'Content-Type: application/json' \
+  --data '{}' \
+  https://proxy-admin.example/api/certificates/shared-cert/reload
+```
+
 A Certificate API credential is accepted only by `POST /api/certificates/deploy`, `POST /api/certificates/reload`, and `POST /api/certificates/{certificate_id}/reload`; it cannot read configuration, logs, metrics or any other administration endpoint. Non-loopback use requires the configured HTTPS administration surface. The normal administrator session + Origin/request-marker + CSRF path remains valid for the same operations. Credential management remains administrator-only: `GET /api/certificate-api` lists metadata, `PUT /api/certificate-api` creates/rotates one Key ID, `DELETE /api/certificate-api/{key_id}` revokes one token, and `DELETE /api/certificate-api` revokes all tokens.
 
 Example external deploy: