docs: document certificate admin controls

README.md

@@ -100,6 +100,25 @@ contains a revoked certificate.
 - `loadVerified` is a raw cache read by verification cache key; returned metadata does not imply
   the certificate is currently trusted.
 
+### Production admin controls
+
+`owner` and `revoker` are production security roles for the shared certificate cache and must be
+operated as hardened admin keys.
+
+- Hold both roles in production-controlled multisigs, not temporary deployer EOAs. If deploying a
+  version with `initialOwner` / `initialRevoker` constructor arguments, pass those multisigs at
+  deployment; otherwise rotate both roles before accepting verification traffic.
+- Treat owner actions as high-risk because ownership transfer, revoker rotation, `unrevokeCert`,
+  and root revocation/unrevocation can affect all consumers. Use a timelock or equivalent
+  change-management process where operationally feasible.
+- Monitor and alert on `OwnershipTransferred`, `RevokerUpdated`, `CertRevoked`, and
+  `CertUnrevoked`, with high-severity alerts for root revocation/unrevocation, unexpected role
+  changes, and unusual revocation batches.
+- Maintain a key-rotation and incident-response runbook covering compromised owner, compromised
+  revoker, lost keys, accidental revocation/unrevocation, and AWS CRL-driven revocation events.
+- A two-step ownership transfer or timelocked admin contract is intentionally left to a separate
+  admin-model change because it alters the operational flow and adds bytecode.
+
 ### Example consumer
 
 ```solidity

docs/hinted-p384-nitro-attestation.md

@@ -437,6 +437,33 @@ its X.509 validity period has not expired.
 return value means the cert metadata was cached previously; it does not imply the cert is
 currently trusted, unexpired, or unrevoked.
 
+### Production admin controls
+
+The `owner` and `revoker` roles are centralized operational controls over the shared certificate
+cache. They should be configured and monitored before any production consumer relies on cached
+certificate state.
+
+- Hold both roles in hardened production-controlled multisigs, not temporary deployer EOAs. If the
+  deployed version accepts `initialOwner` and `initialRevoker`, set those addresses atomically in
+  the constructor; otherwise transfer ownership and set the revoker before accepting verification
+  traffic.
+- Treat owner transactions as high-risk changes. The owner can transfer ownership, rotate the
+  revoker, undo revocations with `unrevokeCert`, and revoke or unrevoke `ROOT_CA_CERT_HASH` as a
+  global halt or resume action.
+- Treat revoker transactions as availability-sensitive changes. The revoker can revoke any
+  non-root certificate identity key, and a mistaken or compromised revoker can deny service to
+  consumers relying on the affected cached chain.
+- Monitor and alert on `OwnershipTransferred`, `RevokerUpdated`, `CertRevoked`, and
+  `CertUnrevoked`. Root revocation/unrevocation, unexpected role changes, and unusually large or
+  bursty revocation batches should page production operators.
+- Maintain a key-rotation and incident-response runbook for compromised owner, compromised
+  revoker, lost role keys, accidental revocation/unrevocation, and AWS CRL-driven revocation
+  events. The runbook should identify approvers, transaction signers, monitoring checks, and
+  consumer communications for each scenario.
+- A two-step ownership transfer or timelocked admin contract should be evaluated as a separate
+  admin-model change. It is not included in this short-term remediation because it changes the
+  operational flow and consumes additional contract bytecode.
+
 **First-verified parent pinning.** A cached cert is pinned to the parent it was first
 verified under: cold verification records `verifiedParent[certHash]` once, where
 `certHash` is the canonical cache key, and every later warm reuse requires the caller to