diff --git a/.claude/claude-security-guidance.md b/.claude/claude-security-guidance.md index 11d0703..e165a11 100644 --- a/.claude/claude-security-guidance.md +++ b/.claude/claude-security-guidance.md @@ -20,7 +20,7 @@ - Every external input is validated before use in SQL, shell, file paths, or templates. - Cryptography uses the standard library or a vetted library; no custom primitives. - Errors returned to clients never include stack traces, SQL, or secrets. -- The token is sent only to the configured base URL over https (plain http only to a loopback host), and redirects are never followed. +- The token is sent only to the configured base URL over https (plain http only to the addresses 127.0.0.1 and ::1, never to a name such as localhost), and redirects are never followed. - Server-supplied text in an error has control and format characters removed and any copy of the token redacted before it is kept. - Plaintexts, data keys and request/response bodies that carry them stay byte slices, and the client clears its own copies when a call ends. diff --git a/CHANGELOG.md b/CHANGELOG.md index d50ee81..7c65d3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,24 @@ follows [semantic versioning](https://semver.org). ## Unreleased +## v0.2.0 + +### Added + +- Each GitHub release has a CycloneDX SBOM of the module and its + requirements attached, as `rypt-.cdx.json`. + +### Changed + +- **Breaking:** `WithBaseURL` allows plain `http` only for the addresses + `127.0.0.1` and `::1`, and no longer for the name `localhost`. A name is + looked up, and the lookup can reach DNS when the hosts file does not list + `localhost`, or when DNS comes first in the lookup order. The resolver + then asks for `localhost.` first, so whoever controls that + zone can answer with another machine, which would receive the token in + clear text. Use `http://127.0.0.1` or `http://[::1]` for a local server, + or `https://localhost`. + ## v0.1.0 The first release, written against version 0.15.0 of the rypt API. diff --git a/client.go b/client.go index 5897aa5..1b64e15 100644 --- a/client.go +++ b/client.go @@ -53,9 +53,15 @@ type options struct { // WithBaseURL sets the API base URL. The default is [DefaultBaseURL]. // // The URL must use https, except that http is allowed when the host is -// localhost, 127.0.0.1 or ::1, for a server under development. It must have -// a host and no user info, query or fragment. It may have a path, which -// then prefixes every API path. +// 127.0.0.1 or ::1 (written [::1] in a URL), for a server under development. +// The name localhost needs https, because a name is looked up. The lookup +// can reach DNS when the hosts file does not list the name, or when DNS +// comes first in the lookup order. The resolver then asks for +// localhost. first, so whoever controls that zone can answer +// with another machine, which would receive the token in clear text. +// +// The URL must have a host and no user info, query or fragment. It may have +// a path, which then prefixes every API path. func WithBaseURL(baseURL string) Option { return func(o *options) { o.baseURL = baseURL } } @@ -167,33 +173,29 @@ func parseBaseURL(raw string) (*url.URL, error) { case u.Hostname() == "": return nil, errors.New("rypt: the base URL must have a host") } - host := u.Host switch u.Scheme { case "https": case "http": - if !isLoopbackName(u.Hostname()) { - return nil, errors.New("rypt: the base URL must use https unless the host is localhost, 127.0.0.1 or ::1") + if !isLoopbackAddress(u.Hostname()) { + return nil, errors.New("rypt: the base URL must use https unless the host is 127.0.0.1 or ::1") } - // net/http bypasses a proxy only for the exact name "localhost", so - // "LOCALHOST" would send the token through HTTP_PROXY in clear text. - host = strings.ToLower(host) default: return nil, errors.New("rypt: the base URL must use https") } return &url.URL{ Scheme: u.Scheme, - Host: host, + Host: u.Host, Path: strings.TrimRight(u.Path, "/"), RawPath: strings.TrimRight(u.RawPath, "/"), }, nil } -// isLoopbackName reports whether host is one of the names for which plain -// http is allowed. It deliberately matches names, not address ranges. The -// comparison ignores ASCII case only: strings.EqualFold would also accept -// non-ASCII look-alikes such as "localhoſt". -func isLoopbackName(host string) bool { - return strings.ToLower(host) == "localhost" || host == "127.0.0.1" || host == "::1" +// isLoopbackAddress reports whether host is one of the two addresses to +// which plain http is allowed. It deliberately matches these exact +// strings: not names, which are looked up and could resolve to another +// machine, and not other spellings or address ranges. +func isLoopbackAddress(host string) bool { + return host == "127.0.0.1" || host == "::1" } // refuseRedirect makes an http.Client return a redirect response as it is, @@ -220,7 +222,7 @@ func defaultHTTPClient() *http.Client { } // httpsOnlyProxy returns a proxy function that uses next for https requests -// only. Plain http is only ever allowed to a loopback host, and through a +// only. Plain http is only ever allowed to 127.0.0.1 or ::1, and through a // proxy the token would travel in clear text. https requests still use // HTTPS_PROXY, through a CONNECT tunnel that carries the TLS session. func httpsOnlyProxy(next func(*http.Request) (*url.URL, error)) func(*http.Request) (*url.URL, error) { diff --git a/client_test.go b/client_test.go index 26627c4..bcb8c5f 100644 --- a/client_test.go +++ b/client_test.go @@ -41,14 +41,27 @@ func TestBaseURL(t *testing.T) { {"https://api.rypt.dev/", "https://api.rypt.dev"}, {"https://example.com/rypt/", "https://example.com/rypt"}, {"https://example.com:8443", "https://example.com:8443"}, - {"http://localhost:8080", "http://localhost:8080"}, - {"http://LocalHost:8080", "http://localhost:8080"}, + {"https://localhost:8443", "https://localhost:8443"}, {"http://127.0.0.1:8080", "http://127.0.0.1:8080"}, + {"http://127.0.0.1", "http://127.0.0.1"}, + {"HTTP://127.0.0.1:8080", "http://127.0.0.1:8080"}, {"http://[::1]:8080", "http://[::1]:8080"}, + {"http://[::1]", "http://[::1]"}, {"http://api.rypt.dev", ""}, - {"http://127.0.0.2", ""}, + // A name is looked up, so plain http to it could go anywhere. + {"http://localhost", ""}, + {"http://localhost:8080", ""}, + {"http://LocalHost:8080", ""}, + {"http://localhost.:8080", ""}, {"http://localhoſt", ""}, {"http://localhost.example.com", ""}, + // Other spellings of loopback addresses, and other loopback addresses. + {"http://127.0.0.2", ""}, + {"http://127.1", ""}, + {"http://2130706433", ""}, + {"http://[::ffff:127.0.0.1]", ""}, + {"http://[0:0:0:0:0:0:0:1]", ""}, + {"http://[::1%25lo]:8080", ""}, {"ftp://api.rypt.dev", ""}, {"api.rypt.dev", ""}, {"https://", ""}, @@ -73,6 +86,11 @@ func TestBaseURL(t *testing.T) { t.Errorf("the error quotes the URL: %v", err) } } + // The error for http://localhost says what is allowed instead. + const want = "rypt: the base URL must use https unless the host is 127.0.0.1 or ::1" + if _, err := parseBaseURL("http://localhost:8080"); err == nil || err.Error() != want { + t.Errorf("parseBaseURL(http://localhost:8080): error %v, want %q", err, want) + } } func TestBaseURLPath(t *testing.T) { diff --git a/doc.go b/doc.go index 0a57b92..97fc037 100644 --- a/doc.go +++ b/doc.go @@ -70,8 +70,8 @@ // than preventing it. // // The client refuses to follow redirects, so the token and request bodies -// are never sent to another URL, and it only talks plain HTTP to a loopback -// host. See [NewClient] and [WithHTTPClient]. +// are never sent to another URL, and it talks plain HTTP only to 127.0.0.1 +// and ::1. See [WithBaseURL] and [WithHTTPClient]. // // # API version // diff --git a/example_test.go b/example_test.go index c334750..cd8dce6 100644 --- a/example_test.go +++ b/example_test.go @@ -81,7 +81,7 @@ func ExampleNewClient() { } func ExampleNewClient_localServer() { - // Plain http is allowed only to a loopback host. + // Plain http is allowed only to 127.0.0.1 and [::1]. client, err := rypt.NewClient(os.Getenv("RYPT_TOKEN"), rypt.WithBaseURL("http://127.0.0.1:8080")) if err != nil { log.Fatal(err)