docs: PKI-MINT-BACKLOG for live device-cert not shipped

docs/PKI-MINT-BACKLOG.md

@@ -0,0 +1,56 @@
+# PKI mint backlog (device certificates)
+
+**Status: not shipped.** Live device-certificate **mint** and **renew** are **out of scope** for `verae-staff-iam` today. This service does not run a CA, accept CSRs, issue PKCS#12/PEM client certs, renew expiry, or perform any local cert crypto. There is **no fake PKI** and no placeholder mint API.
+
+What *is* shipped is **proxy-only enroll/status**: IAM stores an admin flag, reads reverse-proxy mTLS headers, and optionally enforces that pair at login. Certificate lifecycle stays at the edge PKI / reverse proxy.
+
+Canonical behavior and header contract: [ENROLL.md](../ENROLL.md). Service overview and security gates: [README.md](../README.md).
+
+## Shipped today (proxy-only)
+
+| Surface | What it does | What it does not do |
+|---------|----------------|---------------------|
+| `GET /enroll/status` | Returns `state`, `stateLabel`, `note`, `updatedAt`, `nextSteps[]`, `proxyHeadersSeen`, `proxy` probe, `mtlsEnrolled` / `mtlsPresent` / `mtlsEnforce`, plus orthogonal TOTP flags | No CSR, no cert body, no PEM parse, no expiry check, no CN↔user bind |
+| `mint` / `renew` fields on status | **Copy only** — tell operators mint/renew happen at proxy/PKI | Not endpoints; not crypto |
+| `PUT /users/:username` `{ mtlsEnrolled }` | Admin enrollment flag in the IAM store | Does not issue or revoke a cert |
+| `STAFF_MTLS_ENFORCE=1` | Login requires proxy cert headers when the user is enrolled | Does not verify TLS itself |
+| Login + My security UI | Banner/chips/checklist from `/enroll/status` | No “download cert” or mint button |
+
+`state` values remain: `not_enrolled` → `pending_proxy` → `enrolled` → `enforce_on`. Full matrix and `nextSteps` by state: [ENROLL.md](../ENROLL.md).
+
+### Operator path (current)
+
+1. Issue workstation client certs in your **external** reverse-proxy / internal PKI (not this app).
+2. Terminate mTLS at the proxy; forward verify/DN (and optional PEM presence) headers per [ENROLL.md](../ENROLL.md).
+3. Confirm `GET /enroll/status` shows `proxyHeadersSeen.any` / `mtlsPresent` when the browser presents the cert.
+4. Admin sets `mtlsEnrolled: true`.
+5. Only then consider `STAFF_MTLS_ENFORCE=1`.
+
+Renewal before expiry is the same external PKI/proxy path. staff-iam never sees private keys or issued cert material beyond optional header presence flags.
+
+## Not shipped (backlog — live mint/renew)
+
+The following are **explicitly not implemented** and must not be faked in UI or API:
+
+- CSR intake (`POST` anything that accepts a CSR or public key for signing)
+- Certificate issuance (PEM, DER, PKCS#12 download)
+- Automated or on-demand **renew** / re-key
+- Local CA, intermediate, or self-signed device-cert generation inside this process
+- Parsing forwarded PEM for expiry, SAN, or username binding
+- Revocation lists or OCSP from staff-iam
+- Any “demo” or stub cert that pretends to be a real device credential
+
+If product later needs in-app mint/renew, that is a **new** design (real CA integration or delegated signer), not an extension of the current status strings. Until then, keep mint/renew copy pointing at the proxy/PKI and keep `/enroll/status` read-only with respect to crypto.
+
+## Hard rules
+
+1. **No fake crypto** — do not add endpoints, fixtures, or UI that return made-up certs, keys, or CSRs.
+2. **Proxy is source of truth** for “cert present on this request”; IAM flag is source of truth for “user is enrolled for enforce.”
+3. Do not turn on `STAFF_MTLS_ENFORCE` until the proxy actually verifies clients (see [ENROLL.md](../ENROLL.md) “Do not”).
+4. TOTP remains orthogonal ([TOTP.md](../TOTP.md)); authenticator enroll is real crypto (RFC 6238) and is unrelated to device-cert mint.
+
+## Related docs
+
+- [ENROLL.md](../ENROLL.md) — mTLS states, `nextSteps`, `proxyHeadersSeen`, proxy header contract, admin workflow
+- [README.md](../README.md) — install, usage, staff security gates (mTLS row: proxy headers only, no device-cert mint)
+- [TOTP.md](../TOTP.md) — authenticator 2FA (orthogonal gate)