Each Unix connection carries one four-byte big-endian length and one UTF-8 JSON request/response. Zero-length and frames over 2 MiB are rejected before allocation. Requests deny unknown fields; responses permit additive fields. Clients must reject unsupported major versions and retain operation ID, generation and exact payload across retries. Operation IDs are bounded ASCII identities (96 bytes); generations are positive signed-64-bit-compatible values scoped to a certificate ID. Inspect never advances a mutation fence.
Actions: issue, renew, rotate_key, revoke, inspect, install_bundle.
Every request includes version, operation_id, generation, certificate_id,
names (maximum 64), optional challenge (http01/dns01) and optional bundle.
Responses echo the identity and generation, with accepted, active,
already_applied, failed, invalid or stale_generation, bundle and message.
Revocation's active status indicates completed operation, with no bundle;
subsequent inspect reports no active certificate.
Bundle identity fields: organization_id, project_id, certificate_id,
certificate_version. certificate_chain_pem and private_key_pem are base64
strings (decoded caps 1 MiB and 64 KiB). Hashes are 32-byte JSON arrays. Expiry
must match the verified leaf's actual expiry. install_bundle validates key match,
hashes and validity; ACME-produced bundles additionally verify CA trust and all
requested SANs. The gateway independently validates its installation contract.
SQLite commits intent before effects, keys/CSR before order creation and challenge proofs before publication. Account registration reuses a persisted key; the CA returns the same account identity after lost local acknowledgement. Orders resume from persisted URLs. If order creation was attempted but its URL was lost, certd fails closed rather than creating another order. This intentionally requires a new operator operation/generation and may leave an orphaned CA order. Retry count is eight, phase timeout 45 seconds, order deadline 900 seconds. A durable timer and Notify schedule one reconciler; no idle polling or request threads are used.
Active bundle and managed-renewal intent commit in one transaction. Completed operation IDs return the identical durable result. Immutable old versions remain available for control-plane rollback with a fresh gateway generation. Revocation is retained durably and cancels managed renewal; gateway revocation enforcement requires a separate authorized snapshot change.
DNS effect IDs are length-bounded SHA-256 identities derived from operation, host, proof and action. dnsd v1 is consumed as an external wire contract; certd owns a small client DTO and imports no dnsd crate. Request version is checked; response identity/generation/status are validated. Unix RPCs are bounded to 15 seconds and 256 KiB. DNS verification waits are durable dnsd operations.
Admission: at most 256 connections (default 32), 10,000 retained operation intents, 10,000 lifecycle entries (each at most 2 MiB), 10,000 managed certificates, 64 reconciliation rows per batch and 128 HTTP challenge proofs. Capacity exhaustion fails closed; disk retention/pruning is an operator task. Schema version 1 rejects newer schema versions. Upgrade one owner at a time, preserve state/material, keep v1 clients during rolling deployment, and upgrade the gateway independently.