---
phase: 10
slug: pax8-client-auth-foundation
status: verified
nyquist_compliant: true
wave_0_complete: true
created: 2026-07-10
---

# Phase 10 — Validation Strategy

> Per-phase validation contract for feedback sampling during execution.

---

## Test Infrastructure

| Property | Value |
|----------|-------|
| **Framework** | vitest 4.1.5 |
| **Config file** | `vitest.config.ts` (root) — `include: ['lib/**/*.test.ts']`, `globals: false` |
| **Quick run command** | `npx vitest run lib/services/pax8-client.test.ts lib/services/pax8-factory.test.ts` |
| **Full suite command** | `npm test` |
| **Estimated runtime** | ~10 seconds (2 small new test files; full suite already fast per existing CI notes) |

---

## Sampling Rate

- **After every task commit:** Run `npx vitest run lib/services/pax8-client.test.ts lib/services/pax8-factory.test.ts` (once these exist, from Plan 01 Tasks 2/3)
- **After every plan wave:** Run `npm test` (full suite — cheap, this phase adds ~2 small test files, no regressions expected)
- **Before `/gsd:verify-work`:** Full suite must be green, plus the migration idempotency check (Plan 02 Task 2) and the live-credential checkpoint (Plan 03 Task 2)
- **Max feedback latency:** ~10 seconds (vitest quick run); the live auth-proof checkpoint is manual and not part of automated sampling

---

## Per-Task Verification Map

| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
| 10-01-T1 | 01 | 1 | PAX8-01 / PAX8-02 | — | N/A (types-only, no runtime secret handling) | source-assertion | `npx tsc --noEmit --pretty` | ✅ | ✅ green |
| 10-01-T2 | 01 | 1 | PAX8-01 | T-10-01, T-10-02, T-10-03, T-10-04, T-10-05 | Client secret never logged/thrown; audience + JSON body hardcoded; TLS host hardcoded; 60s expiry buffer | unit (mocked fetch) | `npx vitest run lib/services/pax8-client.test.ts` | ✅ | ✅ green (4/4) |
| 10-01-T3 | 01 | 1 | PAX8-02 | T-10-01 | Config-presence check + throw-if-missing never echoes secret value | unit | `npx vitest run lib/services/pax8-factory.test.ts` | ✅ | ✅ green (8/8) |
| 10-02-T1 | 02 | 1 | PAX8-01 / PAX8-02 | T-10-06 | Static DDL, no interpolated/dynamic values — injection not reachable | source-assertion (grep) | `test $(grep -v '^--' migrations/091_pax8_tables.sql \| grep -c "CREATE TABLE IF NOT EXISTS pax8_") -eq 6` | ✅ | ✅ green |
| 10-02-T2 | 02 | 1 | PAX8-01 / PAX8-02 | T-10-07 | `IF NOT EXISTS` only, no DROP/ALTER of existing data; re-apply is a proven no-op | manual/smoke | `docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -tAc "SELECT count(*) FROM information_schema.tables WHERE table_name LIKE 'pax8\_%'"` (falls back to a documented pending-developer-step if the container is unreachable) | ✅ | ✅ green — applied + re-applied idempotently, confirmed again during phase verification |
| 10-03-T1 | 03 | 2 | PAX8-01 | T-10-10 | Verify script logs only counts/status — never access token or client secret | source-assertion (grep) + build | `grep -n "access_token\|accessToken\|clientSecret\|CLIENT_SECRET" scripts/verify-pax8-auth.ts` (expect no match) `&& npx tsc --noEmit --pretty` | ✅ | ✅ green (only match is a doc comment naming the env var, not a logged value) |
| 10-03-T2 | 03 | 2 | PAX8-01 (live proof, ROADMAP SC#2) | T-10-09, T-10-11 | Real credentials only in gitignored `.env.local`; wrong-audience/wrong-encoding failures surface as documented signals, not silent | manual (`checkpoint:human-verify`) | `npx tsx scripts/verify-pax8-auth.ts` (developer-run, requires live `PAX8_CLIENT_ID`/`PAX8_CLIENT_SECRET`) | ✅ | ✅ green — developer ran it live, 118 companies returned, no 403 |

*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*

---

## Wave 0 Requirements

- [x] `lib/services/pax8-client.test.ts` — covers PAX8-01 (token exchange body/headers, expiry-cache reuse, auth-proof call, secret-never-thrown). Written as part of Plan 01 Task 2 (TDD: written before `pax8-client.ts`), not a separate pre-phase scaffold. 4/4 passing.
- [x] `lib/services/pax8-factory.test.ts` — covers PAX8-02 (`isPax8Configured()`, throw-if-missing, singleton + reset). Written as part of Plan 01 Task 3 (TDD: written before `pax8-factory.ts`). 8/8 passing.
- [x] No new test framework/config needed — vitest is already configured project-wide and the `lib/**/*.test.ts` glob already picks up these two new files automatically.

*Both Wave 0 files are created inline by Plan 01's TDD tasks rather than a separate Wave 0 pass — no standalone scaffolding step is needed before Wave 1 starts.*

---

## Manual-Only Verifications

| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| Live OAuth2 token exchange + `/companies` read against the real PAX8 API | PAX8-01 (ROADMAP SC#2) | No existing integration client in this codebase has a "live API" test tier (cost/reliability of hitting real vendor APIs in CI); `PAX8_CLIENT_ID`/`PAX8_CLIENT_SECRET` are not yet present in `.env.local` and must be developer-provisioned | See Plan 10-03 Task 2 checkpoint: add credentials to `.env.local`, run `npx tsx scripts/verify-pax8-auth.ts`, confirm it prints a company count and exits 0 |
| Migration idempotency on the live dev DB | PAX8-01 / PAX8-02 (ROADMAP SC#4) | Postgres applies `migrations/*.sql` on first volume boot only (per CLAUDE.md) — the existing dev DB volume already booted, so this migration must be applied manually, not via container init | See Plan 10-02 Task 2: `bash scripts/apply-migrations.sh 091_pax8_tables.sql` run twice, second run must exit 0 with no error |

---

## Validation Sign-Off

- [x] All tasks have `<automated>` verify or Wave 0 dependencies (2 manual-only exceptions documented above, both with explicit fallback/no-op behavior if infra is unreachable)
- [x] Sampling continuity: no 3 consecutive tasks without automated verify (only the two manual-only rows lack one, and they are not adjacent — 10-02-T2 sits between two automated tasks; 10-03-T2 is the final task in the phase)
- [x] Wave 0 covers all MISSING references (both `❌ W0` test files are covered by Plan 01's own TDD tasks)
- [x] No watch-mode flags (`vitest run`, not `vitest watch`, used throughout)
- [x] Feedback latency < 10s (vitest quick run; manual checkpoints are explicitly out-of-band, not part of the automated feedback loop)
- [x] `nyquist_compliant: true` set in frontmatter

**Approval:** approved 2026-07-10

---

## Validation Audit 2026-07-10

| Metric | Count |
|--------|-------|
| Gaps found | 0 |
| Resolved | 0 |
| Escalated | 0 |

All 7 tasks re-verified post-execution against the actual implementation (not re-read from claims): `tsc` clean, `pax8-client.test.ts` 4/4, `pax8-factory.test.ts` 8/8, migration grep count = 6, migration idempotency re-confirmed live, secret-leak grep clean, live auth-proof checkpoint confirmed (118 companies, no 403). No automated-coverage gaps — this phase is fully Nyquist-compliant with both manual-only rows resolved by the developer during execution.
