feat(oauth): surface device-code prompt in Google Colab

In a Colab notebook, OAuth login appeared to hang: the device-code prompt
(verification URL + user code) was only emitted via DUCKDB_LOG_WARNING, which
the DuckDB Python client never surfaces, so the user never saw the code.

Colab captures the kernel's C-level stderr into the cell, so:
- Add IsColabEnvironment() (COLAB_RELEASE_TAG / COLAB_GPU / COLAB_JUPYTER_IP)
  and PrintPromptIfColab(): write the device-code prompt, "still waiting", and
  "success" messages (plus the PKCE visit-URL fallback) to stderr+fflush there.
- PerformAuthFlow auto-mode also routes Colab to the device flow, so it never
  falls into the unusable server-side PKCE/localhost path.

Also harden EnforceHttpsUrl: the loopback allowance used a prefix match with no
host boundary, so http://127.0.0.1.evil.com / http://localhost.evil.com slipped
past the HTTPS requirement (plaintext-downgrade on discovered token endpoints).
Replaced with IsLoopbackHttpUrl(), which requires a ':'/'/'/end boundary after
the loopback host and adds http://[::1].

The two pure helpers live in a dependency-free src/vgi_oauth_env.cpp so the
Catch2 unit-test binary can exercise them without the OAuth/HTTP/Arrow link
surface; test/cpp/test_oauth.cpp covers Colab detection and the loopback
allow-list (incl. look-alike rejections).

Scope is intentionally Colab-only; the broader Jupyter/JupyterLab non-blocking
retry redesign is deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

CMakeLists.txt

@@ -93,6 +93,7 @@ src/vgi_http_client.cpp
 src/vgi_http_function_connection.cpp
 src/vgi_cookie_jar.cpp
 src/vgi_oauth.cpp
+src/vgi_oauth_env.cpp
 src/vgi_catalogs.cpp
 src/vgi_table_function.cpp
 src/vgi_table_function_impl.cpp
@@ -163,6 +164,8 @@ if((BUILD_VGI_UNIT_TESTS OR DEFINED ENV{BUILD_VGI_UNIT_TESTS}) AND NOT WIN32)
     test/cpp/test_launcher_e2e.cpp
     test/cpp/test_launcher_flock_parity.cpp
     test/cpp/test_transport_detection.cpp
+    test/cpp/test_oauth.cpp
+    src/vgi_oauth_env.cpp
     src/vgi_launcher_internal.cpp
     src/vgi_unix_socket.cpp
     src/vgi_launcher.cpp

src/include/vgi_oauth.hpp

@@ -203,6 +203,18 @@ OAuthTokenSet PerformAuthFlow(const OAuthChallenge &challenge, ClientContext &co
 // Environment detection
 bool IsHeadlessEnvironment();
 
+// True when running inside a Google Colab kernel. Colab captures the kernel's
+// C-level stderr into the notebook cell, so the device-code prompt (URL + user
+// code) is written to stderr there — otherwise it only reaches DUCKDB_LOG_WARNING,
+// which the Python client never surfaces, and login appears to hang.
+bool IsColabEnvironment();
+
+// True iff url is a plain-http loopback URL (127.0.0.1 / localhost / [::1]) with a
+// proper host boundary after the host (':' port, '/' path, or end-of-string). Used
+// to allow http only for genuine loopback while rejecting look-alikes such as
+// http://127.0.0.1.evil.com that a prefix match would wrongly accept.
+bool IsLoopbackHttpUrl(const std::string &url);
+
 // Utility functions
 std::optional<OAuthChallenge> ParseWWWAuthenticate(const std::string &header);
 std::string GenerateCodeVerifier();

src/vgi_oauth.cpp

@@ -419,8 +419,7 @@ static void EnforceHttpsUrl(const std::string &url, const std::string &context_n
 	if (url.empty()) {
 		throw IOException("VGI OAuth: %s URL is empty (no OAuth challenge from server)", context_name);
 	}
-	if (url.substr(0, 8) != "https://" && url.substr(0, 16) != "http://127.0.0.1" &&
-	    url.substr(0, 16) != "http://localhost") {
+	if (url.substr(0, 8) != "https://" && !IsLoopbackHttpUrl(url)) {
 		throw IOException("VGI OAuth: %s URL must use HTTPS: %s", context_name, url);
 	}
 }
@@ -846,6 +845,17 @@ bool IsHeadlessEnvironment() {
 	return false;
 }
 
+// Surface an auth-flow message on stderr when running in Colab. The flow already
+// logs via DUCKDB_LOG_WARNING, but the Python client never displays those; Colab
+// captures C-level stderr into the cell, so this is what the user actually sees.
+// fflush is required — Colab's fd capture won't reliably show buffered output.
+static void PrintPromptIfColab(const std::string &msg) {
+	if (IsColabEnvironment()) {
+		fprintf(stderr, "[VGI] %s\n", msg.c_str());
+		fflush(stderr);
+	}
+}
+
 //===--------------------------------------------------------------------===//
 // Device Code Flow (RFC 8628)
 //===--------------------------------------------------------------------===//
@@ -959,6 +969,7 @@ static OAuthTokenSet PerformDeviceCodeFlowImpl(const OAuthChallenge &challenge,
 		auth_msg += "\nOr visit: " + verification_uri_complete;
 	}
 	DUCKDB_LOG_WARNING(context, auth_msg);
+	PrintPromptIfColab(auth_msg);
 	// Note: in WASM, EM_ASM can't be used from side modules (extensions).
 	// The auth message is logged via DUCKDB_LOG_WARNING. The terminal UI
 	// should display DuckDB warning-level logs to show the user code.
@@ -1007,6 +1018,7 @@ static OAuthTokenSet PerformDeviceCodeFlowImpl(const OAuthChallenge &challenge,
 		auto since_last = std::chrono::duration_cast<std::chrono::seconds>(now - last_status_print).count();
 		if (since_last >= 30) {
 			DUCKDB_LOG_WARNING(context, "Still waiting for authentication...");
+			PrintPromptIfColab("Still waiting for authentication...");
 			last_status_print = now;
 		}
 
@@ -1030,6 +1042,7 @@ static OAuthTokenSet PerformDeviceCodeFlowImpl(const OAuthChallenge &challenge,
 			auto tokens = ParseTokenResponse(resp.body, "device code token response");
 			tokens.use_id_token = resource_meta.use_id_token_as_bearer;
 			DUCKDB_LOG_WARNING(context, "Authentication successful.");
+			PrintPromptIfColab("Authentication successful.");
 			return tokens;
 		}
 
@@ -1173,8 +1186,10 @@ OAuthTokenSet PerformAuthFlow(const OAuthChallenge &challenge,
 		return PerformDeviceCodeFlowImpl(challenge, resource_meta, server_meta, context);
 	}
 
-	// Headless environment
-	if (has_device_ep && IsHeadlessEnvironment()) {
+	// Headless / notebook environment. Colab is checked explicitly: it doesn't
+	// always trip the generic headless heuristics, and routing it to the
+	// server-side PKCE/localhost path would open an invisible browser and hang.
+	if (has_device_ep && (IsHeadlessEnvironment() || IsColabEnvironment())) {
 		VGI_STDERR_DEBUG("[VGI] oauth.auto_flow chose=device_code reason=headless_environment\n");
 		return PerformDeviceCodeFlowImpl(challenge, resource_meta, server_meta, context);
 	}
@@ -1596,8 +1611,10 @@ static OAuthTokenSet PerformPKCEFlowImpl(const OAuthChallenge &challenge,
 	}
 
 	// Always print the URL so user can manually navigate if browser fails
-	DUCKDB_LOG_WARNING(context, "Authentication required for " + GetResourceDisplayName(resource_meta) +
-	    ". Opening browser...\nIf the browser doesn't open, visit this URL:\n" + auth_url);
+	std::string pkce_msg = "Authentication required for " + GetResourceDisplayName(resource_meta) +
+	    ". Opening browser...\nIf the browser doesn't open, visit this URL:\n" + auth_url;
+	DUCKDB_LOG_WARNING(context, pkce_msg);
+	PrintPromptIfColab(pkce_msg);
 
 	OpenBrowser(auth_url);
 

src/vgi_oauth_env.cpp

@@ -0,0 +1,45 @@
+// © Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+//
+// Dependency-free OAuth environment/URL helpers split out of vgi_oauth.cpp so the
+// C++ unit-test binary can exercise them without linking the full OAuth/HTTP/Arrow
+// surface. These touch only <cstdlib> / std::string.
+
+#include "vgi_oauth.hpp"
+
+#include <cstdlib>
+#include <string>
+
+namespace duckdb {
+namespace vgi {
+
+bool IsColabEnvironment() {
+	// Colab runtimes export these; any one is a reliable Colab signal.
+	return std::getenv("COLAB_RELEASE_TAG") || std::getenv("COLAB_GPU") ||
+	       std::getenv("COLAB_JUPYTER_IP");
+}
+
+bool IsLoopbackHttpUrl(const std::string &url) {
+	// Allow http only for genuine loopback hosts. A prefix match alone is unsafe:
+	// "http://127.0.0.1.evil.com" starts with "http://127.0.0.1" but resolves to a
+	// remote attacker host, which would let a malicious metadata document downgrade
+	// the token exchange to plaintext. Require a host boundary (':' port, '/' path,
+	// or end-of-string) immediately after the loopback host.
+	static const char *kLoopbackHosts[] = {"http://127.0.0.1", "http://localhost", "http://[::1]"};
+	for (const char *host : kLoopbackHosts) {
+		const std::string prefix = host;
+		if (url.compare(0, prefix.size(), prefix) == 0) {
+			if (url.size() == prefix.size()) {
+				return true; // exact host, no port/path
+			}
+			const char c = url[prefix.size()];
+			if (c == ':' || c == '/') {
+				return true; // port or path delimiter
+			}
+		}
+	}
+	return false;
+}
+
+} // namespace vgi
+} // namespace duckdb

test/cpp/test_oauth.cpp

@@ -0,0 +1,89 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+//
+// Layer-1 unit tests for the dependency-free OAuth env/URL helpers in
+// vgi_oauth_env.cpp: Colab detection and the loopback-http allow-list used by
+// EnforceHttpsUrl. Pure functions — no network, no DuckDB context.
+
+#include "catch.hpp"
+
+#include "vgi_oauth.hpp"
+
+#include <cstdlib>
+#include <string>
+
+using duckdb::vgi::IsColabEnvironment;
+using duckdb::vgi::IsLoopbackHttpUrl;
+
+namespace {
+
+// RAII guard: save the three Colab env vars on construction, clear them, and
+// restore the originals on destruction so the test never leaks env state.
+struct ColabEnvGuard {
+	const char *vars[3] = {"COLAB_RELEASE_TAG", "COLAB_GPU", "COLAB_JUPYTER_IP"};
+	std::string saved[3];
+	bool had[3] = {false, false, false};
+
+	ColabEnvGuard() {
+		for (int i = 0; i < 3; i++) {
+			if (const char *v = std::getenv(vars[i])) {
+				saved[i] = v;
+				had[i] = true;
+			}
+			unsetenv(vars[i]);
+		}
+	}
+	~ColabEnvGuard() {
+		for (int i = 0; i < 3; i++) {
+			if (had[i]) {
+				setenv(vars[i], saved[i].c_str(), 1);
+			} else {
+				unsetenv(vars[i]);
+			}
+		}
+	}
+};
+
+} // namespace
+
+TEST_CASE("IsColabEnvironment detects Colab signals", "[oauth]") {
+	ColabEnvGuard guard;
+
+	CHECK_FALSE(IsColabEnvironment()); // all cleared by the guard
+
+	setenv("COLAB_RELEASE_TAG", "release-2026", 1);
+	CHECK(IsColabEnvironment());
+	unsetenv("COLAB_RELEASE_TAG");
+	CHECK_FALSE(IsColabEnvironment());
+
+	setenv("COLAB_GPU", "0", 1);
+	CHECK(IsColabEnvironment());
+	unsetenv("COLAB_GPU");
+
+	setenv("COLAB_JUPYTER_IP", "172.28.0.1", 1);
+	CHECK(IsColabEnvironment());
+	unsetenv("COLAB_JUPYTER_IP");
+	CHECK_FALSE(IsColabEnvironment());
+}
+
+TEST_CASE("IsLoopbackHttpUrl accepts genuine loopback hosts", "[oauth]") {
+	CHECK(IsLoopbackHttpUrl("http://127.0.0.1"));
+	CHECK(IsLoopbackHttpUrl("http://127.0.0.1:8080"));
+	CHECK(IsLoopbackHttpUrl("http://127.0.0.1/callback"));
+	CHECK(IsLoopbackHttpUrl("http://localhost"));
+	CHECK(IsLoopbackHttpUrl("http://localhost:9000/cb"));
+	CHECK(IsLoopbackHttpUrl("http://[::1]"));
+	CHECK(IsLoopbackHttpUrl("http://[::1]:9000"));
+}
+
+TEST_CASE("IsLoopbackHttpUrl rejects look-alike and remote hosts", "[oauth]") {
+	// Host-boundary attacks that a naive prefix match would wrongly accept.
+	CHECK_FALSE(IsLoopbackHttpUrl("http://127.0.0.1.evil.com"));
+	CHECK_FALSE(IsLoopbackHttpUrl("http://127.0.0.1.evil.com/token"));
+	CHECK_FALSE(IsLoopbackHttpUrl("http://localhost.evil.com"));
+	CHECK_FALSE(IsLoopbackHttpUrl("http://localhostx"));
+	// Plain remote / non-loopback.
+	CHECK_FALSE(IsLoopbackHttpUrl("http://evil.com"));
+	CHECK_FALSE(IsLoopbackHttpUrl("https://127.0.0.1")); // https handled separately
+	CHECK_FALSE(IsLoopbackHttpUrl(""));
+}