From e839704b68efc54f9743ceb8687324d411775e3c Mon Sep 17 00:00:00 2001 From: Levi Durfee Date: Sun, 1 Nov 2026 23:08:17 +0000 Subject: [PATCH] Refuse plain http to the name localhost WithBaseURL allowed plain http for localhost, 127.0.0.1 and ::1. 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 nsswitch. The resolver then asks for localhost. first, so whoever controls that zone can answer with another machine, which receives the token in clear text. A review reproduced this with the old code in a network namespace. Plain http is now allowed only when the host is exactly 127.0.0.1 or ::1. IP literals are never looked up, and net/http never proxies them. The host no longer needs lowercasing, which existed only so that net/http's proxy bypass matched "LOCALHOST". This breaks callers that pass http://localhost; they can use http://127.0.0.1, http://[::1] or https://localhost. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01NYjhaGCRVp9GXLUuUZv8g1 --- .claude/claude-security-guidance.md | 2 +- CHANGELOG.md | 11 +++++++++ client.go | 36 +++++++++++++++-------------- client_test.go | 24 ++++++++++++++++--- doc.go | 4 ++-- example_test.go | 2 +- 6 files changed, 55 insertions(+), 24 deletions(-) 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..59eb372 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,17 @@ follows [semantic versioning](https://semver.org). ## Unreleased +### 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)