Documentation
¶
Overview ¶
Package vcshost parses and normalises hosted VCS hostnames and matches them against an administrator supplied allowlist.
It deliberately has no Pipelines-as-Code dependency, which is why it sits outside pkg/provider: the settings package, the secrets package and the provider packages all share the exact same parsing rules without any of them creating an import cycle.
Normalisation maps a hostname exactly the way a resolver would, by running the IDNA lookup profile over the raw input before anything else. A hostname that looks like github.com to a human but resolves elsewhere therefore normalises to the name that would really be dialled, and is refused. Callers must still build every URL from the value Parse returns rather than from the raw input, so that policy and DNS can never disagree. See Canonical.
Index ¶
- Constants
- Variables
- func Allowed(allowlist []string, host string) bool
- func Canonical(host string) string
- func IsPrivate(host string) bool
- func IsPublic(host string) bool
- func Join(allowlist []string) string
- func Parse(rawHost string) (string, error)
- func ParseAllowlist(raw string) ([]string, error)
- func SplitURL(rawURL string) (*url.URL, error)
Constants ¶
const ( // PublicGitHub is the canonical hostname of the public github.com instance. PublicGitHub = "github.com" // PublicGitLab is the canonical hostname of the public gitlab.com instance. PublicGitLab = "gitlab.com" // PublicBitbucket is the canonical hostname of the public bitbucket.org instance. PublicBitbucket = "bitbucket.org" // PublicGitea is the canonical hostname of the public gitea.com instance. PublicGitea = "gitea.com" // PublicCodeberg is the canonical hostname of the public codeberg.org instance. PublicCodeberg = "codeberg.org" )
Variables ¶
var ErrURLUnsafeComponents = errors.New("provider URL must not contain credentials, a query or a fragment")
ErrURLUnsafeComponents is returned by SplitURL for a URL carrying credentials, a query or a fragment. Callers that speak of a hostname rather than of a URL match on it to word the refusal in their own terms.
Functions ¶
func Allowed ¶
Allowed reports whether host appears in the allowlist. Both sides are canonicalised so that github.com and api.github.com match each other.
func Canonical ¶
Canonical returns the canonical hostname for a public SaaS instance, so that api.github.com and github.com are treated as the same instance.
Callers must build every URL from this value and never from the hostname they were given: this normalisation is what makes a lookalike hostname collapse onto the host it imitates instead of being dialled as written.
func IsPrivate ¶
IsPrivate reports whether host designates something that is not reachable on the public internet: loopback, link local (which includes the cloud metadata endpoint), a private range, an unqualified name or an in cluster Kubernetes service name. Such a host may well be legitimate, but it must only ever be trusted because an administrator listed it explicitly, never because a webhook payload mentioned it.
func IsPublic ¶
IsPublic reports whether host is a well known public SaaS instance. The host is expected to have been normalised by Parse first.
func Parse ¶
Parse validates a hostname and returns it normalised. The value may be given bare (ghe.example.com) or as an https URL (https://ghe.example.com). Anything carrying a path, a query, a fragment, credentials or a non https scheme is rejected: those are signs the value did not come from a trusted source.
func ParseAllowlist ¶
ParseAllowlist splits a comma separated list of hostnames into normalised canonical hostnames. An empty value yields an empty list, which means the allowlist has not been configured.
func SplitURL ¶
SplitURL parses a provider URL the way an administrator is allowed to write it: bare (ghe.example.com), or with a scheme (https://ghe.example.com/gitlab). A value without a scheme is read as https, which is what every caller wants for a hostname typed by hand.
It only parses and rejects a URL that names no host or carries credentials, a query or a fragment, all of which are signs the value was not meant to be a provider endpoint. Deciding which schemes are acceptable is left to the caller: a self hosted instance reachable over plain http is legitimate on the paths that build a client, and refused on the paths that only take a hostname.
Types ¶
This section is empty.
Source Files