feat(load-balancer): make the development provider URL configurable

.changeset/dev-provider-url-env-var.md

@@ -0,0 +1,18 @@
+---
+"@prosopo/load-balancer": patch
+"@prosopo/config": patch
+---
+
+Let the development provider URL be set with an environment variable.
+
+In development the widget looked for its provider at a hardcoded
+`https://localhost:9229`. That is right when the page and the provider share a
+machine and wrong as soon as they do not: a phone or an iOS simulator loading
+the demo over the LAN resolves `localhost` to itself, never reaches the
+provider, and reports the site key as unregistered — which is a confusing way
+to be told the request went nowhere.
+
+`PROSOPO_PROVIDER_URL_DEVELOPMENT` now overrides it, so that case can be
+pointed at the host actually running the provider. Unset, it still defaults to
+`https://localhost:9229`, so existing setups are unaffected. Staging and
+production resolve through their DNS-routed endpoints and ignore it.

demos/android-webview/app/src/main/assets/procaptcha.html

@@ -61,7 +61,7 @@
         </div>
         <div class="row">
             <div class="procaptcha w-300 m-auto"
-                 data-sitekey="5GCP69mhanZqJqnTvaaGvJCJZWSahz6xE2c7bTGETqSB5KDK"></div>
+                 data-sitekey="5CQ3QeyY82R8h8VWFKTic3FMB3WsbSJExZgbaUqfVJtAFPnb"></div>
         </div>
         <div class="row text-center">
                 <input type="submit" value="Submit"/>

demos/ios-webview/procaptcha/procaptcha.html

@@ -8,7 +8,7 @@
 <form action="" method="POST">
 <input type="text" name="email" placeholder="Email" />
 <input type="password" name="password" placeholder="Password" />
-<div class="procaptcha" data-sitekey="5GCP69mhanZqJqnTvaaGvJCJZWSahz6xE2c7bTGETqSB5KDK"></div>
+<div class="procaptcha" data-sitekey="5CQ3QeyY82R8h8VWFKTic3FMB3WsbSJExZgbaUqfVJtAFPnb"></div>
 <br />
 <input type="submit" value="Submit" />
 </form>

dev/config/src/vite/vite.frontend.config.ts

@@ -75,6 +75,12 @@ export default async function (
 		"process.env.PROSOPO_SERVER_URL": JSON.stringify(
 			process.env.PROSOPO_SERVER_URL,
 		),
+		// Lets a development widget reach a provider that is not on the machine
+		// serving the page — a phone or simulator testing over the LAN would
+		// otherwise resolve the default `localhost` to itself.
+		"process.env.PROSOPO_PROVIDER_URL_DEVELOPMENT": JSON.stringify(
+			process.env.PROSOPO_PROVIDER_URL_DEVELOPMENT,
+		),
 		"process.env._DEV_ONLY_WATCH_EVENTS": JSON.stringify(
 			process.env._DEV_ONLY_WATCH_EVENTS,
 		),

packages/load-balancer/src/balancer.ts

@@ -14,6 +14,7 @@
 import { ProsopoEnvError } from "@prosopo/common";
 import type { EnvironmentTypes } from "@prosopo/types";
 import { z } from "zod";
+import { getDevelopmentProviderUrl } from "./developmentProviderUrl.js";
 
 const HardcodedProviderSchema = z.object({
 	address: z.string(),
@@ -89,7 +90,7 @@ export const loadBalancer = async (
 		return [
 			{
 				address: "5EjTA28bKSbFPPyMbUjNtArxyqjwq38r1BapVmLZShaqEedV",
-				url: "https://localhost:9229",
+				url: getDevelopmentProviderUrl(),
 				datasetId:
 					"0x7984714b92d61fd92fd6a7bc9b56b729481470bcc771c19c382ec679acf02e67",
 				weight: 1,

packages/load-balancer/src/developmentProviderUrl.ts

@@ -0,0 +1,55 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Where a development widget looks for its provider.
+ *
+ * `localhost` is right when the page and the provider share a machine, and
+ * wrong the moment they do not: a phone or a simulator loading the demo over
+ * the LAN resolves `localhost` to itself, so the widget never reaches the
+ * provider and reports the site key as unregistered. The override exists so
+ * that case can be pointed at the host running the provider.
+ *
+ * Development only — staging and production resolve through their DNS-routed
+ * endpoints and ignore this entirely.
+ */
+export const DEFAULT_DEVELOPMENT_PROVIDER_URL = "https://localhost:9229";
+
+/**
+ * Read the override without assuming a runtime.
+ *
+ * Written as a static `process.env.X` access on purpose: the frontend build
+ * substitutes that exact expression for a literal, which a computed lookup
+ * (`process.env[key]`) would not match. For the same reason there is no
+ * `typeof process` guard — in a browser bundle the whole expression is already
+ * a string by the time it runs, and guarding on a `process` that does not
+ * exist there would discard it. Under plain node with the variable unset it is
+ * simply undefined; where neither applies the access throws and is caught.
+ */
+export const readDevelopmentProviderUrlOverride = (): string | undefined => {
+	try {
+		return process.env.PROSOPO_PROVIDER_URL_DEVELOPMENT;
+	} catch {
+		return undefined;
+	}
+};
+
+export const getDevelopmentProviderUrl = (
+	override: string | undefined = readDevelopmentProviderUrlOverride(),
+): string => {
+	const trimmed = override?.trim();
+	return trimmed
+		? trimmed.replace(/\/$/, "")
+		: DEFAULT_DEVELOPMENT_PROVIDER_URL;
+};

packages/load-balancer/src/index.ts

@@ -13,3 +13,4 @@
 // limitations under the License.
 export * from "./providers.js";
 export * from "./balancer.js";
+export * from "./developmentProviderUrl.js";

packages/load-balancer/src/providers.ts

@@ -18,18 +18,21 @@ import {
 	type IpMode,
 	loadBalancer,
 } from "./balancer.js";
+import { getDevelopmentProviderUrl } from "./developmentProviderUrl.js";
 import { retryWithBackoff } from "./retry.js";
 
 // Base DNS endpoint per env — the `pronode.prosopo.io` family is latency-routed
 // (A/AAAA records across the pronode fleet). Clients hit this URL's `/healthz`
 // once to discover which specific pronodeN the DNS layer picked, then pin
 // subsequent captcha calls to that pronode so session creation and submission
 // land on the same backend.
-const DNS_ENDPOINT: Record<EnvironmentTypes, string> = {
-	development: "https://localhost:9229",
+// Resolved per call rather than once at module load, so a development override
+// set after this module is imported is still picked up.
+const dnsEndpoints = (): Record<EnvironmentTypes, string> => ({
+	development: getDevelopmentProviderUrl(),
 	staging: "https://staging.pronode.prosopo.io",
 	production: "https://pronode.prosopo.io",
-};
+});
 
 // Apply the `ipv4.` / `ipv6.` DNS label to a hostname. The single-stack
 // sub-zones only resolve to A or AAAA records respectively, so this pins the
@@ -93,8 +96,10 @@ const fetchPinnedHostWithRetry = (baseUrl: string): Promise<string> =>
 		maxDelayMs: healthzRetryMaxDelayMs,
 	});
 
-const resolveBaseUrl = (env: EnvironmentTypes): string =>
-	DNS_ENDPOINT[env] ?? DNS_ENDPOINT.development;
+const resolveBaseUrl = (env: EnvironmentTypes): string => {
+	const endpoints = dnsEndpoints();
+	return endpoints[env] ?? endpoints.development;
+};
 
 const resolvePinnedUrl = async (
 	env: EnvironmentTypes,

packages/load-balancer/src/tests/developmentProviderUrl.unit.test.ts

@@ -0,0 +1,76 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	DEFAULT_DEVELOPMENT_PROVIDER_URL,
+	getDevelopmentProviderUrl,
+	readDevelopmentProviderUrlOverride,
+} from "../developmentProviderUrl.js";
+
+const ENV_KEY = "PROSOPO_PROVIDER_URL_DEVELOPMENT";
+const original: string | undefined = process.env[ENV_KEY];
+
+afterEach(() => {
+	if (original === undefined) delete process.env[ENV_KEY];
+	else process.env[ENV_KEY] = original;
+});
+
+describe("the development provider url", () => {
+	it("is localhost when nothing overrides it", () => {
+		expect(getDevelopmentProviderUrl(undefined)).toBe("https://localhost:9229");
+		expect(DEFAULT_DEVELOPMENT_PROVIDER_URL).toBe("https://localhost:9229");
+	});
+
+	it("is the override when one is set", () => {
+		// The case this exists for: a phone loading the demo over the LAN cannot
+		// reach the provider via `localhost`, which resolves to the phone.
+		expect(getDevelopmentProviderUrl("https://192.0.2.10:9229")).toBe(
+			"https://192.0.2.10:9229",
+		);
+	});
+
+	it("drops a trailing slash so the url composes with /healthz", () => {
+		expect(getDevelopmentProviderUrl("https://192.0.2.10:9229/")).toBe(
+			"https://192.0.2.10:9229",
+		);
+	});
+
+	it("falls back rather than yielding an empty url", () => {
+		for (const blank of ["", "   ", undefined]) {
+			expect(getDevelopmentProviderUrl(blank)).toBe(
+				DEFAULT_DEVELOPMENT_PROVIDER_URL,
+			);
+		}
+	});
+});
+
+describe("reading the override", () => {
+	it("reads the environment variable", () => {
+		process.env[ENV_KEY] = "https://198.51.100.7:9229";
+		expect(readDevelopmentProviderUrlOverride()).toBe(
+			"https://198.51.100.7:9229",
+		);
+	});
+
+	it("is undefined when the variable is unset", () => {
+		delete process.env[ENV_KEY];
+		expect(readDevelopmentProviderUrlOverride()).toBeUndefined();
+	});
+
+	it("defaults when the variable is unset", () => {
+		delete process.env[ENV_KEY];
+		expect(getDevelopmentProviderUrl()).toBe(DEFAULT_DEVELOPMENT_PROVIDER_URL);
+	});
+});