feat(kyc): validate provider config at boot and expose readiness (#213)

[driftsorbit]

Summary

Fixes the silent mock-fallback risk described in Liquifact#213.

Changes

• src/config/index.js — Added KYC_PROVIDER_URL, KYC_PROVIDER_API_KEY, and KYC_PROVIDER_SECRET to the central Zod schema. A superRefine rule rejects partial config (URL without key, or key without URL) at boot in non-test environments — consistent with the existing Stellar network validation pattern.

• src/services/kycService.js — getKycProviderConfig() now reads from the validated config module instead of process.env directly, with a safe fallback for tests that don't call validate().

• src/services/health.js — Added checkKycHealth(): returns { status: 'disabled' } when the provider is not configured; otherwise probes the provider URL with a lightweight HEAD request. The API key is sent only in the Authorization header and never appears in the response. performHealthChecks() now runs the KYC check in parallel and factors it into the healthy boolean, so /ready returns 503 when the provider is unreachable.

• .env.example — Documented all three KYC vars with the pairing requirement and /ready behaviour.

• tests/kyc.gating.test.js — 15 tests: valid config, partial-config rejection (URL-only, key-only), test-env bypass, disabled passthrough, healthy probe (200, auth header, HEAD method, 4xx reachable), degraded probe (5xx, network error), and /ready degraded state.

Test output

Test Suites: 38 passed, 38 total
Tests:       485 passed, 485 total

Security notes

• API key is never echoed in health check responses or logs.
• Partial-config check is bypassed only in NODE_ENV=test.
• HEAD probe sends no request body, minimising data exposure.