lorentz b81ad3ecc2 docs(24-01): resolve checkpoint — BWS key rename confirmed, DNS egress OK

Checkpoint task 3 resolved: BWS secret keys renamed in Bitwarden
(AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY confirmed present), DNS egress
to public resolvers confirmed OK, credentials confirmed reaching the
Node process. IAM scope left as an open operational item for the
developer to confirm via AWS console.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-08-05 20:16:45 -04:00

9.2 KiB

Raw Blame History

phase

plan

subsystem

Phase 24 Plan 1: Route 53 Foundation Summary

Installed the official AWS Route 53 SDK client, created the dedicated four-table Postgres schema (mirror tables + change-history ledger + audit ledger), defined shared camelCase TypeScript types, and built the route53-factory.ts credential factory following the exact is<Name>Configured() + singleton shape every other Pulse integration uses — TDD RED/GREEN cycle, 7/7 tests passing.

What Was Built

Task 1 — AWS SDK + migration:

npm install @aws-sdk/client-route-53 (official aws/aws-sdk-js-v3 package, confirmed [OK] in 24-RESEARCH.md's package legitimacy audit)
migrations/102_route53_tables.sql — four tables:
- route53_zones (mirror, PK = AWS hosted zone id with /hostedzone/ prefix stripped)
- route53_records (mirror, PK = composite record_key string since Route 53 recordsets have no native id)
- route53_record_history (D-06 append-only change ledger, source CHECK constrained to pulse_crud/sync_detected_drift)
- route53_audit_log (D-03/D-07 append-only attempt log including failures, status CHECK constrained to pending/committed/failed, zone_id deliberately not an FK)
- Seed row INSERT INTO integration_settings (key, disabled) VALUES ('route53', false) (D-10, display-only toggle — extends the existing seed list rather than editing the committed 081_integration_settings.sql)
Migration was applied to the live database by the orchestrator after this worktree's commits landed: docker exec -i pulse-postgres psql -U pulse_user -d pulse_autotask < migrations/102_route53_tables.sql. All four tables confirmed present via \dt route53_*.

Task 2 — Types + factory (TDD):

RED: lib/services/route53-factory.test.ts written first, confirmed failing (module didn't exist)
GREEN: lib/types/route53.ts (camelCase interfaces/unions per the plan's <interfaces> contract) + lib/services/route53-factory.ts (singleton factory, no explicit credentials: option passed to Route53Client — relies on the AWS SDK default credential chain reading AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY from process.env, per 24-RESEARCH.md Pitfall 1)
CLAUDE.md integration table updated with the AWS Route 53 / AWS_* exception row
7/7 test assertions pass; npx tsc --noEmit --pretty exits clean

Deviations from Plan

Auto-fixed Issues

None — plan executed exactly as written for Tasks 1-2.

Environment Note (not a deviation, a pre-condition)

This worktree's branch (worktree-agent-aa690b9b15c5b0f8e) was created before the phase 24 planning commits landed on master — it had zero unique commits and was purely 14 commits behind. Fast-forwarded (git merge --ff-only master) to pick up 24-01-PLAN.md and related planning docs before execution could start. This was a clean fast-forward (no merge, no conflicts, nothing discarded).

Out-of-Scope Discovery (logged, not fixed)

npm test (full suite, run as part of Task 2 verification) surfaced 2 pre-existing failures in lib/services/analyzer/itglue-search.test.ts, unrelated to this plan — neither that file nor itglue-search.ts were touched by Tasks 1-2. Logged to this phase's deferred-items.md per the scope boundary rule rather than fixed.

Checkpoint Status: RESOLVED

Task 3's four verification items, confirmed by the orchestrator against the live pulse-app / pulse-postgres containers with the developer:

BWS secret key names — initially a MISMATCH: the Bitwarden project exposed AWS_ACCESS_KEY / AWS_SECRET_KEY, not the literal AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY the AWS SDK's default credential chain requires. No AWS_REGION key exists (factory defaults to us-east-1, as designed). Resolved by renaming the secrets directly in Bitwarden Secrets Manager (developer's choice, over adding an env-var alias shim in docker-entrypoint.sh) — re-verified via bws secret list inside the container afterward, confirmed AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY now present. No change needed to lib/services/route53-factory.ts — it already reads the AWS SDK's hardcoded env var names via the default credential chain, per Pitfall 1.
Credentials reach the container — confirmed present in the actual Node process environment (/proc/<node-pid>/environ, presence-only check, count=2). Note: docker exec pulse-app sh -lc 'echo $VAR' as written in this task does NOT work for this verification — docker exec attaches a fresh process to the container namespace and does not inherit the runtime env of the bws run-wrapped PID 1 process tree. Verified via the actual node process's /proc/<pid>/environ instead.
Outbound DNS egress — EGRESS-OK: 1.1.1.1/8.8.8.8 UDP/53 reachable from inside the container. Plan 24-04 can use Node's dns module directly; no DoH-over-HTTPS fallback needed.
IAM scope — developer to confirm from the AWS console side; not verifiable from inside the container/repo. Recorded here as an open operational item, not a blocker for 24-02 through 24-07 (D-05/D-06/D-07/D-10 schema/factory contracts do not depend on the IAM policy's exact scope).

Incident: credential value briefly exposed during diagnosis (not part of this plan's code)

While diagnosing item 1's mismatch, the orchestrator ran bws secret list -o json inside the container to enumerate key names — this command prints full secret values by design (unlike the task's own ${VAR:+SET}-style presence checks) and briefly exposed the AWS access key ID/secret value in the session transcript. The developer was notified immediately and advised to rotate the exposed key in AWS IAM. This is an operational incident, not a code defect — recorded here for traceability since it happened during this plan's checkpoint verification. No repository file contains the exposed values.

Additional finding fixed during checkpoint verification (outside this plan's `files_modified`, pre-existing uncommitted work)

Two bugs in already-staged, uncommitted BWS infrastructure files (Dockerfile, docker-compose.yml, docker-entrypoint.sh — not part of this plan's scope, but blocking checkpoint verification) were found and fixed by the orchestrator:

docker-compose.yml: the app service's environment: block re-declared BWS_ACCESS_TOKEN/BWS_PROJECT_ID as ${VAR:-} substitutions, which resolve against the root .env (not .env.local) and silently overrode the real token with an empty string. Fixed by removing the redundant re-declaration.
Dockerfile: the generated bws CLI config only set state_dir, but bws 2.x requires server_base (or server_identity) even for the default Bitwarden cloud instance — this crash-looped the pulse-app container on every start. Fixed by adding server_base = "https://vault.bitwarden.com" to the generated config.

Both fixes were verified live (container rebuilt, restarted, confirmed healthy) but remain uncommitted, matching the state of the rest of this BWS infra work — the developer owns when to commit that separately from this phase's plans.

Self-Check: PASSED

All created files confirmed present:

FOUND: migrations/102_route53_tables.sql
FOUND: lib/types/route53.ts
FOUND: lib/services/route53-factory.ts
FOUND: lib/services/route53-factory.test.ts
FOUND: .planning/phases/24-aws-route-53-dns-sync-track-changes-crud-operations-full-aud/deferred-items.md

All commits confirmed present in git log:

b9df27b feat(24-01): install AWS Route 53 SDK and create dedicated schema migration
4dd9d5d test(24-01): add failing test for Route 53 credential factory
210f84d feat(24-01): implement Route 53 credential factory
fadae68 docs(24-01): log pre-existing itglue-search test failures as out-of-scope

9.2 KiB Raw Blame History