Layers JWS-authenticated POST machinery onto the Phase 1a foundation
(commit ec88a61). After this commit, an ACME client can run
POST /acme/profile/<id>/new-account
against certctl and successfully register an account. Account update
+ deactivation via POST /acme/profile/<id>/account/<acc-id> work.
Orders + challenges remain Phase 2 / 3.
Background:
Two prior dispatch attempts at the original Phase 1 ("skeleton +
directory + new-nonce + new-account" as a single commit) failed on
go-jose v4 API speculation (jws.GetPayload, sig.Algorithm,
jose.SHA256, etc. — none of those exist in v4). Splitting Phase 1
into 1a (foundation, no go-jose) and 1b (this commit, all go-jose
in one place) concentrated the JWS work where attention pays off.
The verifier reads the actual go-jose v4 surface — ParseSigned with
closed alg allow-list, Header struct fields (Algorithm, KeyID,
JSONWebKey, Nonce, ExtraHeaders[HeaderKey]), JWK.Thumbprint with
stdlib crypto.SHA256.
What ships:
- internal/api/acme/jws.go: 487-line verifier + sentinel error
family. Enforces RFC 8555 §6.2 + §6.4 + §6.5 invariants:
- alg in {RS256, ES256, EdDSA} (closed allow-list passed to
jose.ParseSigned — HS256 / none / etc. rejected at parse time)
- exactly one of `kid` / `jwk` in protected header (per
endpoint policy — new-account demands jwk, others demand kid)
- protected `url` matches request URL exactly
- protected `nonce` consumed against acme_nonces (badNonce on
miss/replay/expiry per RFC 8555 §6.5.1)
- kid round-trips against canonical AccountKID(accountID) URL
(catches cross-profile / cross-host replay)
- kid path: account exists + status=valid (deactivated /
revoked accounts cannot authenticate)
- signature verifies; post-Verify payload bytes equal
UnsafePayloadWithoutVerification (defense in depth)
+ JWK persistence helpers (JWKToPEM / ParseJWKFromPEM round-
trip a public-only JWK as a PEM-wrapped JSON envelope; stored
as TEXT in acme_accounts.jwk_pem for diff-friendliness) +
JWKThumbprint per RFC 7638.
- internal/api/acme/jws_test.go: 16 cases covering happy paths
(RS256 kid, ES256 jwk, EdDSA kid) + every named failure mode
(alg-not-allowed, bad-sig, missing-nonce, unknown-nonce,
replay, url-mismatch, mixed kid+jwk, deactivated-account,
cross-host kid). Uses real keypairs + real go-jose Signer to
build JWS objects.
- internal/api/acme/account.go: NewAccountRequest /
AccountUpdateRequest payload shapes (RFC 8555 §7.3 + §7.3.2 +
§7.3.6) + AccountResponseJSON wire shape + MarshalAccount
helper.
- internal/domain/acme.go: ACMEAccount struct + ACMEAccountStatus
closed enum (valid / deactivated / revoked).
- internal/repository/postgres/acme.go: full account CRUD path
(CreateAccountWithTx with 23505-unique-violation sentinel
translation, GetAccountByID, GetAccountByThumbprint,
UpdateAccountContactWithTx, UpdateAccountStatusWithTx) +
sql.ErrNoRows-wrapped repository.ErrNotFound on lookup misses.
- internal/service/acme.go: ACMERepo interface extended;
SetTransactor + SetAuditService wires; NewAccount (idempotent
re-registration per RFC 8555 §7.3.1 — same JWK returns existing
row without an update or new audit event); LookupAccount;
UpdateAccount; DeactivateAccount; VerifyJWS adapter that bridges
api/acme.VerifierConfig to the service-layer ACMERepo; per-op
metrics extended (new_account_total + _failures_total +
_idempotent_total + update_account_total + _failures_total +
deactivate_account_total).
- internal/service/acme_test.go: 8 new tests covering
new-account happy path / idempotent re-registration / only-
return-existing match + no-match / contact update / deactivate
/ lookup-not-found / requires-transactor.
- internal/api/handler/acme.go: NewAccount + Account handlers.
Account dispatches POST-as-GET (RFC 8555 §6.3 — empty body or
{} payload returns the account row), contact update, and
deactivation from the same endpoint. Defense-in-depth check
that the kid path-segment matches the URL path-segment (the
verifier already round-tripped the kid against canonical URL,
but the handler re-asserts to catch any future verifier
refactor).
- internal/api/handler/acme_handler_test.go: 7 new cases
covering happy-create, idempotent-200, only-return-existing-
no-match-400, malformed-JWS-400, kid-URL-mismatch-401,
deactivate, contact-update, POST-as-GET.
- internal/api/router/router.go: 4 new Register calls (per-
profile + shorthand for new-account and account/{acc_id}).
- internal/api/router/openapi_parity_test.go: SpecParityExceptions
extended with the 4 new routes (RFC 8555 wire-protocol surface,
not OpenAPI-shaped — same precedent as Phase 1a).
- cmd/server/main.go: SetTransactor + SetAuditService on
acmeService at startup so the WithinTx-based new-account /
update / deactivate paths run with the same transactor instance
shared across CertificateService / RevocationSvc / RenewalService.
- docs/acme-server.md: Phase status updated; endpoints table grows
new-account + account/<acc_id> rows; new "JWS verification
(Phase 1b)" section enumerates the 7 invariants the verifier
enforces; phases-cross-reference table marks 1b live.
- go.mod / go.sum: github.com/go-jose/go-jose/v4 v4.0.4 added.
Atomicity: every account-state mutation writes its acme_accounts row
+ its audit_events row inside one repository.Transactor.WithinTx
call — the canonical certctl atomicity contract (matches
CertificateService.Create at internal/service/certificate.go:131).
Idempotent re-registration explicitly does NOT write an audit row
(RFC 8555 §7.3.1 returns the existing row unmodified).
Tests: 16 jws_test.go cases + 11 service tests + 11 handler tests
all pass under -short. Bad-signature test uses a real registered
account whose stored JWK is a different keypair from the signer's,
so the JWS parses cleanly but jose.Verify rejects — exercises the
ErrJWSSignatureInvalid path directly.
Engineering history: cowork/WORKSPACE-CHANGELOG.md "ACME-Server-1b".
First slice of the RFC 8555 ACME server endpoint (master plan at
cowork/acme-server-endpoint-prompt.md, per-phase prompts at
cowork/acme-server-prompts/). This commit lands the smallest viable
end-to-end deployable slice: an ACME client running
curl -sk https://certctl/acme/profile/<id>/directory
curl -sk -I https://certctl/acme/profile/<id>/new-nonce
successfully fetches the directory document and a Replay-Nonce.
Account creation, JWS verification, orders, challenges, and
revocation are all out of scope for this phase and arrive in Phases
1b–4.
Closes the Rank 1 LHF from the 2026-05-03 Infisical deep-research
(cowork/infisical-deep-research-results.md). Pre-fix, certctl was an
ACME consumer only — no /acme/directory endpoint, no JWS verifier,
no challenge validators. K8s customers running cert-manager could
not point at certctl as an ACME issuer; they had to deploy a certctl
agent on every node.
What ships:
- internal/api/acme/{directory,nonce,errors}.go (+ tests).
- internal/api/handler/acme.go + acme_handler_test.go.
- internal/repository/postgres/acme.go (nonce ops only — Phase 1b
extends with account CRUD; Phases 2-4 extend with order / authz /
challenge CRUD).
- internal/service/acme.go (BuildDirectory + IssueNonce stubs;
Phase 1b adds VerifyJWS / NewAccount / etc.).
- migrations/000025_acme_server.{up,down}.sql ships the full 5-table
ACME schema (acme_accounts / acme_orders / acme_authorizations /
acme_challenges / acme_nonces) PLUS the per-profile
certificate_profiles.acme_auth_mode column. Phase 1a actively
uses only acme_nonces; remaining tables are empty until Phases
1b-4 plug in.
- internal/config/config.go: ACMEServerConfig struct + ACMEServer
field on Config. Env vars use CERTCTL_ACME_SERVER_* prefix to
avoid colliding with the existing consumer-side ACMEConfig at
config.go:1746 (CERTCTL_ACME_DIRECTORY_URL / PROFILE /
CHALLENGE_TYPE etc.). Phase 1a wires Enabled +
DefaultAuthMode + DefaultProfileID + NonceTTL + DirectoryMeta;
Order/Authz TTLs + per-challenge-type concurrency caps + DNS01
resolver are reserved fields parsed in 1a so operators can set
them ahead of Phases 2/3.
- cmd/server/main.go: wire ACMEHandler into the HandlerRegistry
literal alongside the existing certificate / EST / SCEP / etc.
handlers.
- internal/api/router/router.go: HandlerRegistry.ACME field + 6
Register calls (3 per-profile + 3 shorthand).
- internal/api/router/openapi_parity_test.go: 6 new entries in
SpecParityExceptions. ACME is a wire-protocol surface (JWS-signed
JSON over HTTPS per RFC 7515) whose semantics are dictated by
RFC 8555 + RFC 9773 rather than by an OpenAPI document, same
precedent as SCEP/EST. The canonical reference is
docs/acme-server.md.
- docs/acme-server.md: Phase-1a-shaped reference. Configuration
table for every CERTCTL_ACME_SERVER_* env var. Per-profile
auth-mode decision tree skeleton. TLS trust bootstrap section
flagging cert-manager's ClusterIssuer.spec.acme.caBundle
requirement (the single biggest first-time-deploy footgun;
the full cert-manager walkthrough lands in Phase 6 but the
requirement is documented up front).
Architecture decisions baked in:
- URL family is /acme/profile/<id>/* (per-profile, canonical) with
/acme/* shorthand active when CERTCTL_ACME_SERVER_DEFAULT_PROFILE_ID
is set. Path matches existing per-profile precedent in EST + SCEP.
- Auth mode is per-profile (acme_auth_mode column on
certificate_profiles), NOT server-wide. One certctl-server can
serve trust_authenticated for an internal-PKI profile and
challenge for a public-trust-style profile simultaneously. The
column is read at request time, not cached at server start —
operators flipping a profile's mode via SQL take effect on the
next order without restart.
- Nonces are DB-backed (acme_nonces table). Survive server restart.
The RFC 8555 §6.5 replay defense requires the store to outlast
the client's nonce caching window; an in-memory-only nonce
store would lose every in-flight order on restart.
- Per-op atomic counters on service.ACMEService.Metrics() —
certctl_acme_directory_total, certctl_acme_directory_failures_total,
certctl_acme_new_nonce_total, certctl_acme_new_nonce_failures_total.
Naming follows certctl frozen decision 0.10 cardinality discipline.
Phase 1b will extend with new_account counters; Phase 2 with
order / finalize / cert; Phase 3 with per-challenge-type counters.
Audit fixes#11 + #12 (cowork/acme-server-prompts/audit-additions.md)
applied:
- #11: CERTCTL_ACME_SERVER_* prefix avoids the consumer-side
CERTCTL_ACME_* namespace collision.
- #12: prior-attempt WIP from two failed Phase-1 dispatches was
discarded at phase start; this commit starts from a clean tree.
Tests:
- 14 unit tests in internal/api/acme/ (directory, nonce, errors).
- 7 handler-level tests via httptest.NewServer + mockACMEService
(mirrors the mockSCEPService pattern at scep_handler_test.go).
- 7 service-layer tests with mocked repo + injected profileLookup.
- All pass under -race -count=1 -short.
Deferred to Phase 1b:
- JWS verification (go-jose v4 — see master-prompt §8a for the API
surface and audit doc for the speculation pitfalls).
- new-account / account/<id> endpoints + AccountService.
- Nonce *consumption* path (issue path is in this commit; consume
is only invoked by JWS-verified POSTs which Phase 1b adds).
Engineering history: cowork/WORKSPACE-CHANGELOG.md "ACME-Server-1a".
Per-phase implementation plan: cowork/acme-server-prompts/.
Master plan + audit fixes: cowork/acme-server-endpoint-prompt.md +
cowork/acme-server-prompt-audit.md +
cowork/acme-server-prompts/audit-additions.md.
shankar0123