Skip to content

Migration: pkg/tls core → go/tls

The hardened TLS plumbing has been extracted out of go-tool-base into the standalone module gitlab.com/phpboyscout/go/tls (v0.1.0). It is framework-free (its only dependency is cockroachdb/errors), so any project can adopt GTB's TLS posture without pulling in the framework.

Unlike the pure-repoint extractions (redact, regexutil, browser), pkg/tls still exists — as a thin facade. This is a non-breaking change.

What changed

  • The reusable core now lives in gitlab.com/phpboyscout/go/tls: DefaultConfig, the typed Pair (with PairOverrides and the pure ResolvePair merge), Pair.ServerConfig/Certificate/Valid, CertPool, and ClientConfig.
  • gitlab.com/phpboyscout/go-tool-base/pkg/tls remains as a facade that re-exports that core (Pair and PairOverrides are type aliases; DefaultConfig, ClientConfig, CertPool, ResolvePair are re-exported) and retains the GTB-specific config-key adapter Resolve(cfg config.Containable, prefix string) and the SharedPrefix constant. Those read GTB configuration, so they stay in the framework.
  • No GTB call site changes. Every gtbtls.Pair, gtbtls.Resolve, gtbtls.DefaultConfig, gtbtls.ClientConfig reference compiles unchanged.

How to migrate

If you consume go-tool-base/pkg/tls: nothing is required — the facade keeps the existing API. Continue importing gitlab.com/phpboyscout/go-tool-base/pkg/tls as before.

If you want the hardened TLS core without go-tool-base (a client, a service that does not use GTB config): depend on the standalone module instead, and drop the framework from your graph:

import "gitlab.com/phpboyscout/go/tls"

cfg, err := (tls.Pair{Enabled: true, Cert: certPath, Key: keyPath}).ServerConfig("h2")

go get gitlab.com/phpboyscout/go/[email protected]
go mod tidy

The one piece the standalone module does not provide is Resolve — the config-key cascade (server.tls → server.{grpc,http,gateway}.tls) is a GTB convention and stays in go-tool-base/pkg/tls. Outside GTB, materialise your own Pair values (from flags, env, or your own config) and call tls.ResolvePair directly if you need the shared/per-transport merge.

Notes

  • go-tool-base itself now consumes go/tls through the facade; pkg/tls remains the single entry point GTB's HTTP, gRPC and gateway transports use.
  • Full documentation and the security threat model live at tls.go.phpboyscout.uk; the API reference is on pkg.go.dev.