fix(migrations): validate source endpoints - #14036

What

GET /v1/migrations/appwrite/report and POST /v1/migrations/appwrite checked the source endpoint only with Utopia\Validator\URL. They now use a migrations Endpoint validator built on a new PublicURL validator (ported from main): http or https only, a known public domain or public IP, and every resolved address public.

The migrations worker validates a stored Appwrite-source endpoint again before it builds the source, so migrations queued earlier or retried follow the same rule. The internal endpoint the worker writes itself (http://{_APP_MIGRATION_HOST}/v1) is exempt.

Pinning source requests to the validated addresses

Validating the endpoint once still left a DNS rebinding window: the source resolved the host again for every request, and the Appwrite SDK client followed redirects.

• PublicHostname::getResolve(int $port) and PublicURL::getResolve() are ported from main. They return CURLOPT_RESOLVE entries (host:port:address[,address]) for the addresses the last successful check approved; IP literals and allowlisted hostnames return none.
• Endpoint::resolve(string $url) validates a URL and returns those entries, throwing general_argument_invalid with Invalid `endpoint`: ... when it fails.
• The migrations worker calls $source->setResolver((new Endpoint())->resolve(...)) in processSource(), before report(), unless the endpoint is the internal http://{_APP_MIGRATION_HOST}/v1. The internal endpoint is built by one helper shared with processMigration() and authenticateSource(); the early validation in processMigration() stays.
• GET /v1/migrations/appwrite/report sets the same resolver on the source it builds, before report().
• Every source request, through Target::call() or the SDK client, now validates its URL and connects only to the checked addresses.
• PublicHostname::resolve() uses Swoole's native getaddrinfo() inside hooked coroutines, ported from main (c2c72a1). The 1.9.x image (appwrite/base:1.4.3) runs Swoole 6.2.0, where the hooked dns_get_record() keeps ~140 KiB per lookup, and the resolver now looks up the host on every source request (see below for the unhooked case).

Dependency: utopia-php/migration is required as dev-feat/source-request-controls-1.14.x as 1.14.2, the 1.14.x backport of utopia-php/migration#229 (utopia-php/migration#231): setResolver() on sources, http/https only, and no redirect following, including an SDK 26 Client::call() override for the Appwrite source. Only that package changes in composer.lock. Switch it to 1.14.* once 1.14.2 is tagged.

Validator corrections this relies on

• PublicHostname treats IPv4-compatible IPv6 (::/96, e.g. ::7f00:1) and site-local (fec0::/10) addresses as reserved.
• PublicURL refuses URLs with userinfo or backslashes, where URL parsers and curl can disagree on the host.
• Numeric IPv4 spellings (2130706433, 0x7f.1, 127.1) are never treated as allowed hostnames.
• Endpoint reports one fixed description, so a rejection does not reveal whether a host exists or what it resolves to.

Opt-in allowlist

_APP_MIGRATIONS_ALLOWED_HOSTS takes comma-separated hostnames and IPv4/IPv6 CIDR ranges for sources that are deliberately private, such as another instance on the same network. A listed hostname, an IP in a listed range, or a hostname whose resolved addresses are all public or listed is accepted. Hostnames match exactly: example.com does not allow evil-example.com or db.example.com. The default is empty, which allows public sources only. The development .env lists appwrite and the compose network 172.16.238.0/24 so the local stack can migrate from itself.

Effect on other callers

PublicHostname takes an optional Allowlist that defaults to empty, and its lookup is late-static-bound so tests can substitute it. Its other callers (avatars favicon/image/screenshot, webhooks worker) now also reject ::/96 and fec0::/10 addresses. PublicURL is new on this branch and is used only by the migrations Endpoint validator.

This is the backport of #14034. It stays compatible with PHP 8.3 (no array_all), and the changed files pass php -l and the network unit tests under php:8.3-cli.

Lookups in unhooked coroutines

PublicHostname::resolve() uses Swoole\Coroutine\System::getaddrinfo() only when the coroutine hooks network functions (SWOOLE_HOOK_NET_FUNCTION), the only case where Swoole 6.2's dns_get_record() retains ~140 KiB per lookup. Elsewhere it keeps the blocking dns_get_record(). getaddrinfo() always yields, and the 1.9.x and 2.0.x HTTP servers set no hook_flags, so GraphQL's Promise::then(), which waits in an unhooked usleep() loop, never let a yielded avatars lookup resume: every GraphQL avatar request that fetches a URL hung (seven 120 s timeouts in the GraphQL E2E job). Main's HTTP server and the workers enable SWOOLE_HOOK_ALL and keep the native lookup.

Tests

• Unit: AllowlistTest, SubnetTest, PublicHostnameTest, PublicURLTest (exact host, IPv4 CIDR, IPv6 CIDR, non-match, lookalike hosts, numeric spellings, IPv6 forms, userinfo, backslashes), EndpointTest. All the new cases fail without the change.
• Unit (pinning): PublicHostnameTest checks the getResolve() format, that a curl request with the entries reaches the checked IPv4, IPv6 and trailing-dot hosts, that IP literals and allowlisted hostnames return none, and that entries reset after a rejection. PublicURLTest checks the port (explicit, 80, 443) inside a hooked coroutine, where the lookup reads /etc/hosts; outside one, dns_get_record() depends on the resolver answering for localhost, which failed Tests / Unit in CI. EndpointTest covers resolve() returning entries and throwing for every rejected endpoint. The coroutine cases check resolution under SWOOLE_HOOK_ALL and that a lookup retains under 4 KiB (the memory case fails without the getaddrinfo() change on Swoole 6.2). All fail without the change.
• E2E: testGetAppwriteReportWithSubnetEndpoint and testCreateAppwriteMigrationWithSubnetEndpoint report and migrate from http://appwrite.test/v1. The development .env no longer lists appwrite.test by name, so the validator resolves it to traefik's address, admits it because .env lists the compose network 172.16.238.0/24, and the source connects to that address through the CURLOPT_RESOLVE entry. appwrite.test is _APP_DOMAIN, so CI's router protection accepts it, and every other Appwrite migration E2E test takes the same pinned path. Each uses its own source project, so the user counts are exact. testGetAppwriteReport reports from the shared source project, and the rejection test now also refuses http://localhost/v1.
• Unit: PublicHostnameTest::testResolvesWithoutYieldingInsideUnhookedCoroutine fails if a lookup in an unhooked coroutine yields.
• E2E: testAppwriteMigrationRejectsPrivateEndpoints checks that report and create return general_argument_invalid for link-local, loopback, IPv6 loopback and non-http endpoints.

Locally: lint, PHPStan and the network and migrations-validator unit tests pass. For the pinning commits, pint, PHPStan and rector on the changed files pass, and tests/unit/Network and the migrations validator tests pass under PHP 8.3 (php:8.3-cli with Swoole 6.2.3) and in appwrite/base:1.4.3.

🤖 Generated with Claude Code