Check Provider Readiness

Provider Preflight is an automatable readiness check under examples/providerPreflight. Use it after creating a provider-backed resource, before cutting traffic over, and from CI before each deploy. It walks the same chain a real Gateway request depends on — control plane, Gateway dependencies, application identity, provider binding and configuration, network paths, and the active policy decision — and reports exactly which link is broken and how to fix it.

What it checks

Checks run in five phases:

Phase	Check	What it confirms
readiness	Admin API readiness	The control plane responds ready on GET /ready.
readiness	Gateway readiness	The Gateway responds ready, which verifies its bindings, Postgres, Redis, revocation freshness, audit replay, and STS.
dependencies	Resource binding	The resource resolves to exactly one credential provider and a Gateway application.
dependencies	Application	The application exists, is not expired, and matches the resource’s routing binding.
configuration	Provider configuration	Kind-required fields are present and allowed_token_hosts covers the token endpoint.
configuration	Scope coverage	Every requested scope is declared on the resource.
configuration	Runtime injection	Runtime-injection eligibility is enabled when required.
connectivity	Token endpoint host	OAuth token endpoints are HTTPS and publicly routable.
connectivity	Callback reachability	Authorization-code callback origins are HTTPS and reachable.
connectivity	Upstream reachability	The protected upstream is reachable, with a warning when it resolves to a private address.
authorization	Policy authorization	Simulating the active policy set with the input shape STS uses for real token exchanges returns allow.

The preflight fails closed. Any failed check exits non-zero, and every failure or warning prints a fix: line with the concrete remediation.

Run the preflight

cd examples/providerPreflight
CARACAL_API_URL=http://127.0.0.1:3000 \
CARACAL_ADMIN_TOKEN=<admin-token> \
PREFLIGHT_ZONE_ID=<zone-id> \
PREFLIGHT_RESOURCE_ID=<resource-id> \
PREFLIGHT_APPLICATION_ID=<app-id> \
PREFLIGHT_SCOPES=pipernet:read,pipernet:write \
npm run preflight

Optional settings:

Variable	Purpose
PREFLIGHT_GATEWAY_URL	Probes the Gateway’s /ready endpoint; without it the Gateway phase reports a warning instead of validating.
PREFLIGHT_REQUIRE_RUNTIME_INJECTION=true	Requires providers to allow runtime injection.
PREFLIGHT_OUTPUT=json	Emits the full report as JSON for CI pipelines and dashboards.

Exit codes: 0 when all checks pass, 1 when any check fails, 2 when the preflight itself cannot run.

Network position

Upstream reachability and Callback reachability run from the host executing the script. Run it from a network position comparable to Gateway, or inside the cluster, when you need the reachability result to match production routing.

Test

cd examples/providerPreflight
npm test

The tests inject network, DNS, and policy responses and do not call live systems.

Next step

Continue to Iterate Policy Safely when a denied request needs to become a tested policy change.