Help us shape the future of Go! Take the 2026 Go Developer Survey

serviceaccess

package
v0.4.26 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EnvPKISource      = "BASEHARBOR_SERVICE_PKI_SOURCE"
	EnvTLSCertFile    = "BASEHARBOR_SERVICE_TLS_CERT_FILE"
	EnvTLSKeyFile     = "BASEHARBOR_SERVICE_TLS_KEY_FILE"
	EnvTrustBundle    = "BASEHARBOR_SERVICE_TLS_TRUST_FILE"
	EnvClientCertFile = "BASEHARBOR_SERVICE_TLS_CLIENT_CERT_FILE"
	EnvClientKeyFile  = "BASEHARBOR_SERVICE_TLS_CLIENT_KEY_FILE"
	EnvIssuerRef      = "BASEHARBOR_SERVICE_PKI_ISSUER_REF"
	EnvServerName     = "BASEHARBOR_SERVICE_TLS_SERVER_NAME"
	EnvAuthentication = "BASEHARBOR_SERVICE_AUTHENTICATION"
	EnvAuthTokenFile  = "BASEHARBOR_SERVICE_AUTH_TOKEN_FILE"
)
View Source 
const GatewayImage = "docker.io/library/caddy:2.11.4-alpine"
View Source 
const TCPGatewayImage = "docker.io/library/haproxy:3.2.23-alpine"

Variables

This section is empty.

Functions

func CheckLocalIssuer added in v0.4.25 

func CheckLocalIssuer(dir string) error

CheckLocalIssuer performs a read-only preflight. Missing authority is a new realization; partial or unprotected authority must be recovered, not replaced.

func HTTPGatewayComposeService 

func HTTPGatewayComposeService(files HTTPGatewayFiles, spec HTTPGatewaySpec) string

func LoopbackHTTPSURL 

func LoopbackHTTPSURL(port int) (string, error)

func NewHTTPClient 

func NewHTTPClient(material TLSMaterial, requireClient bool) (*http.Client, error)

func NewHTTPClientForPolicy 

func NewHTTPClientForPolicy(material TLSMaterial, policy Policy) (*http.Client, error)

func NewHTTPClientWithBasicAuth added in v0.4.17 

func NewHTTPClientWithBasicAuth(material TLSMaterial, username, password string) (*http.Client, error)

func RetireTLSOverlap added in v0.4.21 

func RetireTLSOverlap(ctx context.Context, issuer Issuer, policy Policy, dir string) error

RetireTLSOverlap removes a previous CA only after the provider has verified the newly issued server/client leaves through its stable service endpoint. It is idempotent so a verified retirement can be retried safely.

func TCPGatewayComposeService 

func TCPGatewayComposeService(files TCPGatewayFiles, spec TCPGatewaySpec) string

func ValidateSignedCSR added in v0.4.23 

func ValidateSignedCSR(request CSRSigningRequest, issued IssuedCertificate, trust TrustBundle, now time.Time) error

ValidateSignedCSR verifies public issuance against the authoritative trust, rather than trusting a CA supplied alongside an arbitrary signed leaf.

func VerifyBrowserRoute added in v0.4.18 

func VerifyBrowserRoute(ctx context.Context, client *http.Client, rawURL string) error

VerifyBrowserRoute validates bounded same-authority redirects while preserving route-level reachability semantics for surfaces that intentionally answer with authentication challenges.

func VerifyBrowserRouteWithAllowedAuthorities added in v0.4.18 

func VerifyBrowserRouteWithAllowedAuthorities(ctx context.Context, client *http.Client, rawURL string, allowedURLs ...string) error

func VerifyBrowserSurface added in v0.4.18 

func VerifyBrowserSurface(ctx context.Context, client *http.Client, rawURL string) error

VerifyBrowserSurface validates a user-facing HTTPS URL the way a browser would reach it, while keeping redirect traversal bounded to the same effective authority. A non-default port therefore cannot silently collapse to HTTPS/443 during a redirect.

func VerifyBrowserSurfaceWithAllowedAuthorities added in v0.4.18 

func VerifyBrowserSurfaceWithAllowedAuthorities(ctx context.Context, client *http.Client, rawURL string, allowedURLs ...string) error

VerifyBrowserSurfaceWithAllowedAuthorities permits only the canonical URL plus explicitly listed HTTPS authorities. It is intended for products such as Keycloak where an admin alias may redirect to the canonical identity host.

func WaitHTTPS 

func WaitHTTPS(ctx context.Context, client *http.Client, endpoint, path string) error

Types

type AuthenticationMode 

type AuthenticationMode string
const (
	AuthenticationNone     AuthenticationMode = "none"
	AuthenticationNative   AuthenticationMode = "native"
	AuthenticationMTLS     AuthenticationMode = "mtls"
	AuthenticationToken    AuthenticationMode = "token"
	AuthenticationOIDC     AuthenticationMode = "oidc"
	AuthenticationOAuth2   AuthenticationMode = "oauth2"
	AuthenticationExternal AuthenticationMode = "external"
)

type CSRIssuer added in v0.4.23 

type CSRIssuer interface {
	Issuer
	SignCSR(context.Context, CSRSigningRequest) (IssuedCertificate, error)
}

CSRIssuer signs a client-owned key through the existing protected authority. It must never generate or return a client private key.

type CSRSigningRequest added in v0.4.23 

type CSRSigningRequest struct {
	CSRPEM   []byte
	Identity string
	TTL      time.Duration
	// DNSNames is authorized only by the internal Core server signing boundary.
	// Node enrollment must never grant server-name authority.
	DNSNames []string
}

func (CSRSigningRequest) Validate added in v0.4.23 

func (r CSRSigningRequest) Validate() (*x509.CertificateRequest, error)

func (CSRSigningRequest) ValidateCore added in v0.4.23 

func (r CSRSigningRequest) ValidateCore() (*x509.CertificateRequest, error)

ValidateCore binds DNS SANs to an explicit internal server authorization. The CSR itself is never the source of authority for additional names.

type CertificateRequest 

type CertificateRequest struct {
	CommonName  string
	DNSNames    []string
	IPAddresses []net.IP
	URIs        []*url.URL
	TTL         time.Duration
}

type CoreCSRIssuer added in v0.4.23 

type CoreCSRIssuer interface {
	Issuer
	SignCoreCSR(context.Context, CSRSigningRequest) (IssuedCertificate, error)
}

CoreCSRIssuer is the separate managed server-identity signing boundary. Operator-authorized Core keys cannot be signed through node enrollment.

type HTTPGatewayFiles 

type HTTPGatewayFiles struct {
	Dir                    string
	Caddyfile              string
	Material               TLSMaterial
	AuthToken              string
	HealthAuthorizationEnv string
}

func EnsureHTTPGateway 

func EnsureHTTPGateway(ctx context.Context, issuer Issuer, policy Policy, providerDir string, spec HTTPGatewaySpec) (HTTPGatewayFiles, error)

type HTTPGatewaySpec 

type HTTPGatewaySpec struct {
	ServiceName               string
	Upstream                  string
	Upstreams                 []string
	UpstreamTrustFile         string
	UpstreamServerName        string
	UpstreamClientCertificate string
	UpstreamClientKey         string
	PublishedPortEnv          string
	ContainerPort             int
	Networks                  []string
	NetworkAliases            []string
	CertificateNames          []string
	RequireClient             bool
	DenyPaths                 []string
	BasicAuthUsername         string
	BasicAuthPassword         string
	HealthURI                 string
	HealthStatus              int
	HealthAuthorizationEnv    string
}

type IssuedCertificate 

type IssuedCertificate struct {
	IssuerReference string
	Certificate     []byte
	PrivateKey      []byte
	IssuingCA       []byte
	CAChain         [][]byte
	Serial          string
	ExpiresAt       time.Time
}

type Issuer 

type Issuer interface {
	TrustBundle(ctx context.Context) (TrustBundle, error)
	Issue(ctx context.Context, request CertificateRequest) (IssuedCertificate, error)
	Renew(ctx context.Context, current IssuedCertificate, request CertificateRequest) (IssuedCertificate, error)
	Revoke(ctx context.Context, serial string) error
	Status(ctx context.Context) (IssuerStatus, error)
}

Issuer is the provider-neutral certificate authority boundary used by service access. Implementations own issuer state and lifecycle; callers only receive the leaf material and public trust required for the selected runtime.

type IssuerStatus 

type IssuerStatus struct {
	IssuerReference string
	Ready           bool
}

type LifecycleObservation 

type LifecycleObservation struct {
	Source          PKISource `json:"source"`
	LifecycleOwner  string    `json:"lifecycle_owner"`
	RenewalMode     string    `json:"renewal_mode"`
	IssuerReference string    `json:"issuer_reference,omitempty"`
	ServerExpiresAt time.Time `json:"server_expires_at"`
	ClientExpiresAt time.Time `json:"client_expires_at,omitempty"`
	Health          string    `json:"health"`
	Warning         string    `json:"warning,omitempty"`
}

LifecycleObservation is the secret-safe, provider-neutral certificate lifecycle state exposed to status/doctor/evidence surfaces.

func InspectLifecycle 

func InspectLifecycle(dir string) (LifecycleObservation, error)

InspectLifecycle reads already-materialized lifecycle state. It never issues, renews, revokes or otherwise mutates certificate material.

type LocalIssuer added in v0.4.25 

type LocalIssuer struct{ Dir string }

LocalIssuer is the software realization of the existing service-access issuer contract. It needs no runtime service. Its private authority remains in protected Target state and is never projected into application bindings. Construction is read-only; only EnsureLocalIssuer initializes authority.

func EnsureLocalIssuer added in v0.4.25 

func EnsureLocalIssuer(dir string) (*LocalIssuer, error)

func (*LocalIssuer) Issue added in v0.4.25 

func (i *LocalIssuer) Issue(ctx context.Context, request CertificateRequest) (IssuedCertificate, error)

func (*LocalIssuer) Renew added in v0.4.25 

func (i *LocalIssuer) Renew(ctx context.Context, current IssuedCertificate, request CertificateRequest) (IssuedCertificate, error)

func (*LocalIssuer) Revoke added in v0.4.25 

func (i *LocalIssuer) Revoke(ctx context.Context, serial string) error

func (*LocalIssuer) Status added in v0.4.25 

func (i *LocalIssuer) Status(ctx context.Context) (IssuerStatus, error)

func (*LocalIssuer) TrustBundle added in v0.4.25 

func (i *LocalIssuer) TrustBundle(ctx context.Context) (TrustBundle, error)

type NativeTLSFiles added in v0.4.17 

type NativeTLSFiles struct {
	Dir      string
	Material TLSMaterial
}

func EnsureNativeTLS added in v0.4.17 

func EnsureNativeTLS(ctx context.Context, issuer Issuer, policy Policy, providerDir string, serverNames ...string) (NativeTLSFiles, error)

type PKISource 

type PKISource string
const (
	PKIManagedLocal PKISource = "managed-local"
	PKIExternal     PKISource = "external-pki"
	PKIBYOC         PKISource = "byoc"
)

type Policy 

type Policy struct {
	Environment            string             `json:"environment"`
	Provider               string             `json:"provider"`
	TLSRequired            bool               `json:"tls_required"`
	AuthenticationRequired bool               `json:"authentication_required"`
	Authentication         AuthenticationMode `json:"authentication"`
	PKISource              PKISource          `json:"pki_source"`
	ServerName             string             `json:"server_name,omitempty"`
	ServerCertificate      string             `json:"server_certificate,omitempty"`
	ServerKey              string             `json:"server_key,omitempty"`
	TrustBundle            string             `json:"trust_bundle,omitempty"`
	ClientCertificate      string             `json:"client_certificate,omitempty"`
	ClientKey              string             `json:"client_key,omitempty"`
	IssuerReference        string             `json:"issuer_reference,omitempty"`
	AuthTokenFile          string             `json:"auth_token_file,omitempty"`
}

func Resolve 

func Resolve(environment, provider string, authentication AuthenticationMode) (Policy, error)

type TCPGatewayFiles 

type TCPGatewayFiles struct {
	Dir      string
	Config   string
	PEM      string
	Material TLSMaterial
}

func EnsureTCPGateway 

func EnsureTCPGateway(ctx context.Context, issuer Issuer, policy Policy, providerDir string, spec TCPGatewaySpec) (TCPGatewayFiles, error)

type TCPGatewaySpec 

type TCPGatewaySpec struct {
	ServiceName       string
	UpstreamHost      string
	UpstreamPort      int
	Upstreams         []TCPGatewayUpstream
	PublishedPortEnv  string
	ContainerPort     int
	Network           string
	Environment       map[string]string
	BackendDirectives []string
	ServerDirectives  []string
}

type TCPGatewayUpstream added in v0.4.21 

type TCPGatewayUpstream struct {
	Name string
	Host string
	Port int
}

type TLSMaterial 

type TLSMaterial struct {
	Source            PKISource `json:"source"`
	CA                string    `json:"ca"`
	ServerCertificate string    `json:"server_certificate"`
	ServerKey         string    `json:"server_key"`
	ClientCertificate string    `json:"client_certificate,omitempty"`
	ClientKey         string    `json:"client_key,omitempty"`
	ServerName        string    `json:"server_name"`
}

func EnsureTLSMaterial 

func EnsureTLSMaterial(ctx context.Context, issuer Issuer, policy Policy, dir string, dnsNames ...string) (TLSMaterial, error)

func ExistingTLSMaterial 

func ExistingTLSMaterial(policy Policy, dir string) (TLSMaterial, error)

type TrustBundle 

type TrustBundle struct {
	IssuerReference string
	PEM             []byte
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.