feat(acp-adapter): expose SPHERE_AGGREGATOR_URL + SPHERE_TRUSTBASE_URL env overrides

[vrogojin]

Summary

The faucet's network preset hardcodes the testnet aggregator and trust base. When running against a self-hosted aggregator (e.g. sphere-sdk's tests/e2e/local-infra deployment, or a private wallet's local stack), the operator needs to redirect both without forking the SDK to add a custom network preset.

This patch wires through the SDK's existing oracle.url + oracle.skipVerification fields and adds three pass-through env vars:

env var	effect
SPHERE_AGGREGATOR_URL	overrides the network preset's aggregator URL
SPHERE_TRUSTBASE_URL	overrides the hardcoded testnet trust-base GitHub URL
SPHERE_AGGREGATOR_SKIP_VERIFICATION	bypass client-side trust-base verification (defaults ON when AGGREGATOR_URL is set; override with =false)

All three are optional. Without any new vars set, faucet behavior is byte-for-byte identical to today.

Logs a new aggregator_override_active line when the URL is set so operators can confirm the redirect took effect.

Companion

sphere-sdk PR #324 adds matching --aggregator-url, --trustbase-url, --nametag, --skip-verification flags to run-faucet.sh (the SSL-wrapped wrapper) which forward these env vars into the container.

Test plan

• Without env vars set: faucet boots identically (verified — uses testnet aggregator)
• With SPHERE_AGGREGATOR_URL=https://aggregator-unicity-dev.dyndns.org: aggregator_override_active logged, faucet's oracle hits our self-hosted aggregator instead of the testnet one (verified)
• With SPHERE_NAMETAG=xaleava: NAMETAG_BINDING (kind 30078) event verified on relay
• Type-check: tsc --noEmit passes (verified locally)

Known limitation

Even with the overrides, Sphere.init's nametag mint silently no-ops when skipVerification is on — the relay event publishes but no L3 commitment lands on the aggregator, so identity.nametag returns null. This is an SDK-level concern (Sphere.init swallowing the mint step) and isn't introduced by this PR.

[gemini-code-assist]

Code Review

This pull request introduces configuration overrides via environment variables in src/acp-adapter/main.ts. Specifically, it allows overriding the trustbase URL using SPHERE_TRUSTBASE_URL, the aggregator URL using SPHERE_AGGREGATOR_URL, and the verification skip behavior using SPHERE_AGGREGATOR_SKIP_VERIFICATION. The review feedback recommends robustly parsing these environment variables by trimming whitespace and handling empty strings to prevent runtime errors and ensure correct fallback behavior.

[gemini-code-assist]

If the SPHERE_TRUSTBASE_URL environment variable is set to an empty string (e.g., in a Docker or Kubernetes configuration), the nullish coalescing operator (??) will not fall back to DEFAULT_TRUSTBASE_URL. This results in trustbaseUrl being "", causing fetch to throw a runtime error on startup. Trimming the value and using a logical OR (||) fallback prevents this issue.

Suggested change

	const trustbaseUrl = process.env['SPHERE_TRUSTBASE_URL'] ?? DEFAULT_TRUSTBASE_URL;
	const trustbaseUrl = process.env['SPHERE_TRUSTBASE_URL']?.trim() || DEFAULT_TRUSTBASE_URL;

[gemini-code-assist]

Environment variables can sometimes contain accidental leading/trailing whitespace or be defined as empty strings in containerized environments. Trimming SPHERE_AGGREGATOR_URL and SPHERE_AGGREGATOR_SKIP_VERIFICATION ensures robust parsing. Additionally, treating an empty string for SPHERE_AGGREGATOR_SKIP_VERIFICATION as undefined allows it to correctly fall back to the default behavior.

Suggested change

	const aggregatorUrl = process.env['SPHERE_AGGREGATOR_URL'];
	if (aggregatorUrl) {
	log.info({ url: aggregatorUrl }, 'aggregator_override_active');
	}
	const skipVerification = (() => {
	const v = process.env['SPHERE_AGGREGATOR_SKIP_VERIFICATION'];
	if (v === undefined) return aggregatorUrl ? true : undefined;
	return v === '1' || v.toLowerCase() === 'true';
	})();
	const aggregatorUrl = process.env['SPHERE_AGGREGATOR_URL']?.trim() || undefined;
	if (aggregatorUrl) {
	log.info({ url: aggregatorUrl }, 'aggregator_override_active');
	}
	const skipVerification = (() => {
	const v = process.env['SPHERE_AGGREGATOR_SKIP_VERIFICATION']?.trim();
	if (v === undefined || v === '') return aggregatorUrl ? true : undefined;
	return v === '1' || v.toLowerCase() === 'true';
	})();