diff --git a/.planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/24-04-SUMMARY.md b/.planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/24-04-SUMMARY.md new file mode 100644 index 0000000..fe48c5f --- /dev/null +++ b/.planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/24-04-SUMMARY.md @@ -0,0 +1,182 @@ +--- +phase: 24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud +plan: 04 +subsystem: aws-route53 +tags: [route53, integration-health, dns, node-dns, delegation-check] +dependency-graph: + requires: + - "lib/services/route53-factory.ts (isRoute53Configured / getRoute53Client, plan 24-01)" + - "lib/types/route53.ts (plan 24-01)" + - "migrations/102_route53_tables.sql (route53_zones, plan 24-01)" + provides: + - "lib/services/route53-dns-delegation.ts (normalizeNsList / compareNsDelegation / resolveLiveNs / checkAllZoneDelegations)" + - "checkRoute53() registered in lib/services/integration-health.ts" + - "HealthStatus union gained 'degraded' member" + - "IntegrationHealth gained nsDelegationMismatches? / nsDelegationErrors? fields" + affects: + - "app/api/dashboard/integration-health/route.ts (now returns a route53 entry)" + - "/admin/integrations and /status pages (consume the health list; both already fall back safely on an unrecognized status string)" +tech-stack: + added: [] + patterns: + - "dedicated dns.Resolver() instance pinned to public resolvers, never the process-global dns module (D-12, T-24-13)" + - "bounded-concurrency worker-pool batch check (checkAllZoneDelegations, T-24-14)" +key-files: + created: + - lib/services/route53-dns-delegation.ts + - lib/services/route53-dns-delegation.test.ts + modified: + - lib/services/integration-health.ts +decisions: + - "Used Node's dns module directly (Resolver + setServers(['1.1.1.1','8.8.8.8'])), not the DoH-over-HTTPS fallback — plan 24-01's checkpoint confirmed EGRESS-OK from inside the pulse-app container." + - "Chosen degraded-state HealthStatus member: added a new 'degraded' member to the union (no existing member represented 'reachable, authenticated, but a secondary check found a problem') — every existing member was either a full pass ('ok'/'unknown'), a hard failure ('auth_failed'/'unreachable'/'not_configured'), or operator-suppressed ('disabled')." + - "Implemented a local, private sanitizeAwsError()/isAwsAuthError() inside integration-health.ts instead of importing from lib/services/route53-record-validation.ts — that file is scoped to plan 24-03, which runs in a sibling parallel worktree and was not available in this isolated worktree (24-04's depends_on only lists 24-01). See Deviations below." +metrics: + duration: "~45 min, 2 tasks, TDD RED/GREEN on Task 1" + completed: "2026-08-05" +--- + +# Phase 24 Plan 4: Route 53 Integration Health + D-12 DNS Delegation Check Summary + +Added `checkRoute53()` to the existing integration-health aggregator (auth probe via +`ListHostedZonesCommand`) plus a D-12-specific extension: every synced hosted zone's +Route-53-authoritative name servers are compared against a **live public DNS lookup** +(dedicated `dns.Resolver()` pinned to `1.1.1.1`/`8.8.8.8`, never the process-global +resolver) and a mismatch degrades the reported health to a new `'degraded'` +`HealthStatus` member — no manually-maintained "expected NS" field anywhere. + +## What Was Built + +**Task 1 — `lib/services/route53-dns-delegation.ts` (TDD RED/GREEN):** +- Pure half, fully unit-tested (13/13 assertions, no network I/O in tests): + - `normalizeNsList(input: unknown): string[]` — lowercase, strip trailing dot, + de-dupe, sort; `[]` for `null`/`undefined`/non-array input. + - `compareNsDelegation(authoritative, live)` — set-diff mismatch detection. + Empty authoritative list is treated as unjudgeable (`mismatch: false`, no false + alarm); a non-empty authoritative list with an empty live answer is a real + delegation problem (`mismatch: true`). +- I/O half (not unit-tested per plan instruction — network calls are flaky in CI; + covered by manual verification in 24-VALIDATION.md): + - `resolveLiveNs(domain, timeoutMs=5000)` — constructs `new Resolver()` (callback + API from `'dns'`) and calls `.setServers(['1.1.1.1','8.8.8.8'])` **on that + instance only**. The process-global `dns.setServers()` is never called anywhere + in this file (T-24-13) — verified by grep in the acceptance criteria. + - `checkAllZoneDelegations(zones, opts?)` — bounded-concurrency (default 5) worker + pool over the zone list; a lookup error yields `{ mismatch: false, error }` (an + unreachable resolver is an infra problem, not delegation drift — T-24-14); zones + whose `authoritativeNameServers` normalizes to `[]` are skipped. + +**Task 2 — `checkRoute53()` registered in `lib/services/integration-health.ts`:** +- `IntegrationHealth` gained two optional fields: `nsDelegationMismatches?: string[] | null` + and `nsDelegationErrors?: string[] | null` (kept separate from `error`, per 24-PATTERNS.md). +- `checkRoute53()` placed next to `checkDattoRmm()`: config gate via `isRoute53Configured()` + → `getRoute53Client().send(new ListHostedZonesCommand({ MaxItems: 1 }))` auth probe, + timed for `latencyMs`. Auth errors (`InvalidClientTokenId`, `SignatureDoesNotMatch`, + `AccessDenied`, `UnrecognizedClientException`, or HTTP 401/403 via `$metadata.httpStatusCode`) + map to `status: 'auth_failed'`; any other error maps to `'unreachable'`. Both branches + redact the error through a local `sanitizeAwsError()` before it reaches `IntegrationHealth.error`. +- D-12 delegation step: `SELECT id, name, authoritative_name_servers FROM route53_zones + WHERE is_deleted = false ORDER BY name LIMIT 50`, fed to `checkAllZoneDelegations()`. + A non-empty mismatch list downgrades `status` from `'ok'` to the new `'degraded'` + member and sets a summary `error` string (`'NS delegation mismatch for N zone(s): ...'`, + noting truncation if the 50-zone cap was hit). The entire delegation step is wrapped + in its own try/catch — a Postgres failure or blocked resolver degrades to + `nsDelegationErrors` and leaves the auth-probe status untouched, never throwing out + of `checkIntegrationHealth()`'s `Promise.all` (T-24-16). +- Registered `checkRoute53(),` as a bare (unwrapped) entry in the `Promise.all` array + alongside `checkAutotask()` / `checkDattoRmm()` / `checkItglue()` / `checkS1()`. +- No changes to `applyDisableOverlay()` — it already keys off `item.key` generically, + so `'route53'` is covered automatically (D-10, display-only; `integration_settings` + grep count unchanged from before this task). +- **Bug fix (Rule 1):** `summarize()`'s status-bucketing `if/else if` chain didn't + account for the new `'degraded'` status — it would have silently fallen through + uncounted (not `ok`, not `failed`, not `notConfigured`), breaking the invariant that + bucket counts sum to `total`. Added `'degraded'` to the `failed` bucket (and thus + `hasIssues`) alongside `'auth_failed'`/`'unreachable'`. +- **Type fix (Rule 3):** the plan's example passed `MaxItems: '1'` (string) to + `ListHostedZonesCommand`; this SDK version (`@aws-sdk/client-route-53` ^3.1104.0) + types `MaxItems` as `number`. Changed to `MaxItems: 1`. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] `summarize()` didn't bucket the new `'degraded'` status** +- Found during: Task 2, after adding `'degraded'` to `HealthStatus`. +- Fix: added `'degraded'` to the existing `failed`-bucket branch. +- Files modified: `lib/services/integration-health.ts` +- Commit: ea04672 + +**2. [Rule 3 - Blocking issue] `ListHostedZonesCommand({ MaxItems: '1' })` failed `tsc`** +- Found during: Task 2 verification (`npx tsc --noEmit`). +- Issue: this SDK version types `MaxItems` as `number`, not `string` as the plan's + action text described. +- Fix: `MaxItems: 1`. +- Files modified: `lib/services/integration-health.ts` +- Commit: ea04672 + +**3. [Rule 3 - Blocking issue] `lib/services/route53-record-validation.ts` (plan 24-03) + does not exist in this worktree** +- Found during: Task 2, reading `` / `` which reference + `sanitizeAwsError` from that file. +- Why: this plan's `depends_on` frontmatter lists only `24-01`; plan 24-03 (which owns + `sanitizeAwsError`) runs concurrently in a sibling parallel worktree in this same wave + and is not merged into this worktree's history. +- Fix: implemented a local, private `sanitizeAwsError()` + `isAwsAuthError()` pair + inside `lib/services/integration-health.ts`, using the **identical redaction rules** + spec'd in 24-03-PLAN.md (`AKIA[0-9A-Z]{16}` → `[redacted-key-id]`, `arn:aws:[^\s"']+` + → `[redacted-arn]`, 12-digit account ids → `[redacted-account-id]`, truncate to 500 + chars) so behavior is consistent regardless of which implementation ships. Documented + inline with a NOTE comment pointing at this deviation. +- **Follow-up for a human/future plan:** once 24-03 lands on `master`, the local copy in + `integration-health.ts` should be replaced with an import from + `@/lib/services/route53-record-validation` to keep a single source of truth — flagging + this explicitly since it is a cross-plan duplication introduced by parallel worktree + execution, not by design. +- Files modified: `lib/services/integration-health.ts` +- Commit: ea04672 + +### Verification Note (not a deviation) + +The plan's Task 2 acceptance criteria includes an optional curl check against the running +`pulse-app` container's `/api/dashboard/integration-health` route. That container +(confirmed via `docker inspect`) has no source-code volume mount — it runs a pre-built +standalone image from before this plan's commits, and the route additionally redirects +unauthenticated requests (307) per `middleware.ts`. Live end-to-end verification against +the running container was therefore not performed in this worktree; `npx tsc --noEmit`, +`npx vitest run lib/services/route53-dns-delegation.test.ts` (13/13 passing), and the full +`npm test` suite (480/482 passing — the 2 failures are pre-existing/unrelated, see below) +are the verifications actually run. A container rebuild + authenticated curl is left to +the orchestrator/human at merge time if desired. + +### Out-of-Scope Discovery (logged, not fixed) + +`npm test` (full suite) surfaced the same 2 pre-existing failures in +`lib/services/analyzer/itglue-search.test.ts` already logged in this phase's +`deferred-items.md` by plan 24-01. Neither that file nor `itglue-search.ts` were touched +by this plan. + +## Self-Check: PASSED + +All created/modified files confirmed present: +- FOUND: lib/services/route53-dns-delegation.ts +- FOUND: lib/services/route53-dns-delegation.test.ts +- FOUND: lib/services/integration-health.ts (modified) + +All commits confirmed present in `git log`: +- 7396f07 test(24-04): add failing test for NS normalization and delegation comparison +- 06ebae5 feat(24-04): implement NS normalization and delegation-comparison module +- ea04672 feat(24-04): register checkRoute53() in the integration health aggregator + +## TDD Gate Compliance + +Task 1 followed RED → GREEN: `test(24-04)` commit (7396f07) precedes the `feat(24-04)` +implementation commit (06ebae5); no REFACTOR commit was needed (implementation matched +the test contract on first pass). Task 2 is `type="auto"` without `tdd="true"` per the +plan, so no RED/GREEN gate applied there — verified with `tsc` + full `npm test` instead. + +## Threat Flags + +None beyond what's already covered by this plan's own `` (T-24-13, T-24-14, +T-24-03, T-24-15, T-24-16 — all addressed as designed, see "What Was Built" above). No new +network endpoints, auth paths, or schema changes were introduced outside that register.