github.com/caddyserver/certmagic v0.23.0: Config

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/caddyserver/certmagic.Config in pkg:golang/github.com/caddyserver/certmagic@v0.23.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/caddyserver/certmagic@v0.23.0
Demonstrate these symbols/APIs:
  - github.com/caddyserver/certmagic.Config
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:8fc37914bc17dcd6648c9e9f92e05484ab4ddc5cbb31ae61ce074ca31ea36700","contract":["certmagic.NewDefault initializes a valid Config with default settings and a valid TLSConfig configured with GetCertificate.","certmagic.New initializes a Config using a Cache and custom fields such as RenewalWindowRatio, DefaultServerName, and MustStaple.","Config.CacheUnmanagedCertificatePEMBytes caches an unmanaged TLS certificate in memory and makes it retrievable via Config.GetCertificate for matching SNI.","Config.GetCertificate falls back to the certificate for DefaultServerName when ClientHelloInfo.ServerName is empty."],"goal":"verify github.com/caddyserver/certmagic.Config in pkg:golang/github.com/caddyserver/certmagic@v0.23.0","kind":"HOW","packages":["pkg:golang/github.com/caddyserver/certmagic@v0.23.0"],"schemaVersion":1,"symbols":["github.com/caddyserver/certmagic.Config"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","executionContext":"go","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/caddyserver/certmagic@v0.23.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/caddyserver/certmagic@v0.23.0","symbols":["github.com/caddyserver/certmagic.Config"],"verifierAdapter":"golang@1"}

module example.com/certmagic-config

go 1.26.6

require github.com/caddyserver/certmagic v0.23.0

require (
	github.com/caddyserver/zerossl v0.1.3 // indirect
	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
	github.com/libdns/libdns v1.0.0-beta.1 // indirect
	github.com/mholt/acmez/v3 v3.1.2 // indirect
	github.com/miekg/dns v1.1.63 // indirect
	github.com/zeebo/blake3 v0.2.4 // indirect
	go.uber.org/multierr v1.11.0 // indirect
	go.uber.org/zap v1.27.0 // indirect
	go.uber.org/zap/exp v0.3.0 // indirect
	golang.org/x/crypto v0.36.0 // indirect
	golang.org/x/mod v0.24.0 // indirect
	golang.org/x/net v0.37.0 // indirect
	golang.org/x/sync v0.12.0 // indirect
	golang.org/x/sys v0.31.0 // indirect
	golang.org/x/text v0.23.0 // indirect
	golang.org/x/tools v0.31.0 // indirect
)

github.com/caddyserver/certmagic v0.23.0 h1:CfpZ/50jMfG4+1J/u2LV6piJq4HOfO6ppOnOf7DkFEU=
github.com/caddyserver/certmagic v0.23.0/go.mod h1:9mEZIWqqWoI+Gf+4Trh04MOVPD0tGSxtqsxg87hAIH4=
github.com/caddyserver/zerossl v0.1.3 h1:onS+pxp3M8HnHpN5MMbOMyNjmTheJyWRaZYwn+YTAyA=
github.com/caddyserver/zerossl v0.1.3/go.mod h1:CxA0acn7oEGO6//4rtrRjYgEoa4MFw/XofZnrYwGqG4=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
github.com/libdns/libdns v1.0.0-beta.1 h1:KIf4wLfsrEpXpZ3vmc/poM8zCATXT2klbdPe6hyOBjQ=
github.com/libdns/libdns v1.0.0-beta.1/go.mod h1:4Bj9+5CQiNMVGf87wjX4CY3HQJypUHRuLvlsfsZqLWQ=
github.com/mholt/acmez/v3 v3.1.2 h1:auob8J/0FhmdClQicvJvuDavgd5ezwLBfKuYmynhYzc=
github.com/mholt/acmez/v3 v3.1.2/go.mod h1:L1wOU06KKvq7tswuMDwKdcHeKpFFgkppZy/y0DFxagQ=
github.com/miekg/dns v1.1.63 h1:8M5aAw6OMZfFXTT7K5V0Eu5YiiL8l7nUAkyN6C9YwaY=
github.com/miekg/dns v1.1.63/go.mod h1:6NGHfjhpmr5lt3XPLuyfDJi5AXbNIPM9PY6H6sF1Nfs=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/zeebo/assert v1.1.0 h1:hU1L1vLTHsnO8x8c9KAR5GmM5QscxHg5RNU5z5qbUWY=
github.com/zeebo/assert v1.1.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
github.com/zeebo/blake3 v0.2.4 h1:KYQPkhpRtcqh0ssGYcKLG1JYvddkEA8QwCM/yBqhaZI=
github.com/zeebo/blake3 v0.2.4/go.mod h1:7eeQ6d2iXWRGF6npfaxl2CU+xy2Fjo2gxeyZGCRUjcE=
github.com/zeebo/pcg v1.0.1 h1:lyqfGeWiv4ahac6ttHs+I5hwtH/+1mrhlCtVNQM2kHo=
github.com/zeebo/pcg v1.0.1/go.mod h1:09F0S9iiKrwn9rlI5yjLkmrug154/YRW6KnnXVDM/l4=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
go.uber.org/zap/exp v0.3.0 h1:6JYzdifzYkGmTdRR59oYH+Ng7k49H9qVpWwNSsGJj3U=
go.uber.org/zap/exp v0.3.0/go.mod h1:5I384qq7XGxYyByIhHm6jg5CHkGY0nsTfbDLgDDlgJQ=
golang.org/x/crypto v0.36.0 h1:AnAEvhDddvBdpY+uR+MyHmuZzzNqXSe/GvuDeob5L34=
golang.org/x/crypto v0.36.0/go.mod h1:Y4J0ReaxCR1IMaabaSMugxJES1EpwhBHhv2bDHklZvc=
golang.org/x/mod v0.24.0 h1:ZfthKaKaT4NrhGVZHO1/WDTwGES4De8KtWO0SIbNJMU=
golang.org/x/mod v0.24.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
golang.org/x/net v0.37.0 h1:1zLorHbz+LYj7MQlSf1+2tPIIgibq2eL5xkrGk6f+2c=
golang.org/x/net v0.37.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY=
golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4=
golang.org/x/tools v0.31.0 h1:0EedkvKDbh+qistFTd0Bcwe/YLh4vHwWEkiI0toFIBU=
golang.org/x/tools v0.31.0/go.mod h1:naFTU+Cev749tSJRXJlna0T3WxKvb1kWEx15xA4SdmQ=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package main

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/tls"
	"crypto/x509"
	"crypto/x509/pkix"
	"encoding/pem"
	"fmt"
	"math/big"
	"time"

	"github.com/caddyserver/certmagic"
)

func generateSelfSignedCert(domain string) ([]byte, []byte, error) {
	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		return nil, nil, err
	}

	notBefore := time.Now().Add(-1 * time.Hour)
	notAfter := notBefore.Add(24 * time.Hour)

	serialNumber, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
	if err != nil {
		return nil, nil, err
	}

	template := x509.Certificate{
		SerialNumber: serialNumber,
		Subject: pkix.Name{
			CommonName: domain,
		},
		NotBefore:             notBefore,
		NotAfter:              notAfter,
		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
		BasicConstraintsValid: true,
		DNSNames:              []string{domain},
	}

	derBytes, err := x509.CreateCertificate(rand.Reader, &template, &template, &priv.PublicKey, priv)
	if err != nil {
		return nil, nil, err
	}

	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: derBytes})

	privBytes, err := x509.MarshalECPrivateKey(priv)
	if err != nil {
		return nil, nil, err
	}
	keyPEM := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: privBytes})

	return certPEM, keyPEM, nil
}

func main() {
	// 1. Create a default CertMagic config
	defaultCfg := certmagic.NewDefault()
	tlsCfg := defaultCfg.TLSConfig()
	fmt.Printf("Default TLS MinVersion: %x\n", tlsCfg.MinVersion)

	// 2. Create a custom Cache and Config
	var customCfg *certmagic.Config
	cache := certmagic.NewCache(certmagic.CacheOptions{
		GetConfigForCert: func(cert certmagic.Certificate) (*certmagic.Config, error) {
			return customCfg, nil
		},
	})
	defer cache.Stop()

	customCfg = certmagic.New(cache, certmagic.Config{
		RenewalWindowRatio: 0.5,
		DefaultServerName:  "example.com",
		MustStaple:         false,
	})

	// 3. Generate and cache an in-memory certificate
	domain := "example.com"
	certPEM, keyPEM, err := generateSelfSignedCert(domain)
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	_, err = customCfg.CacheUnmanagedCertificatePEMBytes(ctx, certPEM, keyPEM, []string{"primary-cert"})
	if err != nil {
		panic(err)
	}

	// 4. Retrieve certificate via GetCertificate
	hello := &tls.ClientHelloInfo{ServerName: domain}
	cert, err := customCfg.GetCertificate(hello)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Successfully loaded certificate for %s, leaves: %d\n", domain, len(cert.Certificate))

	// 5. Retrieve certificate via fallback DefaultServerName
	emptyHello := &tls.ClientHelloInfo{ServerName: ""}
	fallbackCert, err := customCfg.GetCertificate(emptyHello)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Fallback certificate loaded: %v\n", fallbackCert != nil)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/caddyserver/certmagic.Config in pkg:golang/github.com/caddyserver/certmagic@v0.23.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/caddyserver/certmagic@v0.23.0"
  ],
  "symbols": [
    "github.com/caddyserver/certmagic.Config"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package test

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/tls"
	"crypto/x509"
	"crypto/x509/pkix"
	"encoding/pem"
	"math/big"
	"testing"
	"time"

	"github.com/caddyserver/certmagic"
)

func generateTestCert(domain string) ([]byte, []byte, error) {
	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		return nil, nil, err
	}

	notBefore := time.Now().Add(-1 * time.Hour)
	notAfter := notBefore.Add(24 * time.Hour)

	serialNumber, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
	if err != nil {
		return nil, nil, err
	}

	template := x509.Certificate{
		SerialNumber: serialNumber,
		Subject: pkix.Name{
			CommonName: domain,
		},
		NotBefore:             notBefore,
		NotAfter:              notAfter,
		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
		BasicConstraintsValid: true,
		DNSNames:              []string{domain},
	}

	derBytes, err := x509.CreateCertificate(rand.Reader, &template, &template, &priv.PublicKey, priv)
	if err != nil {
		return nil, nil, err
	}

	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: derBytes})

	privBytes, err := x509.MarshalECPrivateKey(priv)
	if err != nil {
		return nil, nil, err
	}
	keyPEM := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: privBytes})

	return certPEM, keyPEM, nil
}

func TestNewDefault(t *testing.T) {
	cfg := certmagic.NewDefault()
	if cfg == nil {
		t.Fatal("certmagic.NewDefault() returned nil")
	}

	tlsCfg := cfg.TLSConfig()
	if tlsCfg == nil {
		t.Fatal("cfg.TLSConfig() returned nil")
	}
	if tlsCfg.GetCertificate == nil {
		t.Error("tlsCfg.GetCertificate should not be nil")
	}
}

func TestCustomConfigInitialization(t *testing.T) {
	var cfg *certmagic.Config
	cache := certmagic.NewCache(certmagic.CacheOptions{
		GetConfigForCert: func(cert certmagic.Certificate) (*certmagic.Config, error) {
			return cfg, nil
		},
	})
	defer cache.Stop()

	renewalRatio := 0.45
	defaultSNI := "example.com"
	cfg = certmagic.New(cache, certmagic.Config{
		RenewalWindowRatio: renewalRatio,
		DefaultServerName:  defaultSNI,
		MustStaple:         true,
	})

	if cfg.RenewalWindowRatio != renewalRatio {
		t.Errorf("cfg.RenewalWindowRatio = %v, want %v", cfg.RenewalWindowRatio, renewalRatio)
	}
	if cfg.DefaultServerName != defaultSNI {
		t.Errorf("cfg.DefaultServerName = %v, want %v", cfg.DefaultServerName, defaultSNI)
	}
	if !cfg.MustStaple {
		t.Errorf("cfg.MustStaple = %v, want true", cfg.MustStaple)
	}
}

func TestCacheAndGetCertificate(t *testing.T) {
	var cfg *certmagic.Config
	cache := certmagic.NewCache(certmagic.CacheOptions{
		GetConfigForCert: func(cert certmagic.Certificate) (*certmagic.Config, error) {
			return cfg, nil
		},
	})
	defer cache.Stop()

	domain := "example.com"
	cfg = certmagic.New(cache, certmagic.Config{
		DefaultServerName: domain,
	})

	certPEM, keyPEM, err := generateTestCert(domain)
	if err != nil {
		t.Fatalf("failed to generate test cert: %v", err)
	}

	ctx := context.Background()
	tag, err := cfg.CacheUnmanagedCertificatePEMBytes(ctx, certPEM, keyPEM, []string{"test-tag"})
	if err != nil {
		t.Fatalf("CacheUnmanagedCertificatePEMBytes failed: %v", err)
	}
	if tag == "" {
		t.Error("expected non-empty tag returned from CacheUnmanagedCertificatePEMBytes")
	}

	// 1. Retrieve by matching SNI
	hello := &tls.ClientHelloInfo{ServerName: domain}
	cert, err := cfg.GetCertificate(hello)
	if err != nil {
		t.Fatalf("GetCertificate with SNI %q failed: %v", domain, err)
	}
	if cert == nil || len(cert.Certificate) == 0 {
		t.Fatalf("GetCertificate returned empty certificate for %q", domain)
	}

	// 2. Retrieve by fallback DefaultServerName when ServerName is empty
	emptyHello := &tls.ClientHelloInfo{ServerName: ""}
	fallbackCert, err := cfg.GetCertificate(emptyHello)
	if err != nil {
		t.Fatalf("GetCertificate with empty SNI failed: %v", err)
	}
	if fallbackCert == nil || len(fallbackCert.Certificate) == 0 {
		t.Fatalf("GetCertificate fallback returned empty certificate")
	}
}