fix(api): make the enrollment-key "Hide expired" filter agree with the status badge (#3191)

[ToddHebebrand]

The bug

PR #3045 taught the Enrollment Keys row badge (getKeyStatus) that once a parent key is dead the row is judged by its installer tokens — the things that actually enroll. So an Add-Device key whose 60-minute parent aged out while its 30-day installer link keeps working correctly renders Active.

The list route's expired filter never got the same treatment: it tested enrollment_keys.expires_at alone. Turning on Hide expired therefore hid rows the very same page was rendering as Active — the key was both Active and invisible, with no way for the operator to reach a credential that still genuinely works.

The fix

The carve-out reuses the predicate that already spares such a key from POST /enrollment-keys/purge-expired. services/enrollmentKeyPurgeGuards.ts now exposes both wrappers over one correlated subquery:

• hasNoLiveUnexhaustedBootstrapToken() (existing, notExists) — unchanged emitted SQL for both purge consumers.
• hasLiveUnexhaustedBootstrapToken() (new, exists) — used by the list filter.

That is the exact SQL counterpart of the badge's liveConsumed < liveMax test. Sharing one definition means "Hide expired" can no longer hide a key that "Delete expired" deliberately refuses to delete, and a future change to the predicate cannot land on one path and skip the others.

Invariant pinned: no key the badge renders Active is hidden by ?expired=false.

Scope — deliberately narrow

• Gated on short_code IS NULL to mirror reportsInstallerCapacity: the API suppresses installerTokens for a short-link child (Installer capacity is suppressed when an installer is built from a short-link child key #3034), so its badge is parent-only and the filter must be too. That gate itself is untouched — Installer capacity is suppressed when an installer is built from a short-link child key #3034 remains its own accepted trade-off. The purge guard applies no such gate and shouldn't: suppressing a confusing capacity number is cosmetic, deleting a key out from under a live token is irreversible.
• The exhaustion axis is not touched. usage_count >= max_usage ("Exhausted", amber) has never been part of ?expired= and still isn't; an exhausted-but-unexpired key lists exactly as before. Correcting the expiry axis alone is sufficient for the invariant above.
• Both branches stay exact complements, so no key becomes unreachable from both toggle positions.
• Both guards are built inside their branch — an unfiltered list request (the toggle is off by default) issues no extra db.select.

Verification

New real-Postgres suite apps/api/src/routes/enrollmentKeysExpiredFilter.integration.test.ts, registered in both vitest.integration.config.ts (include) and vitest.config.ts (exclude). The mocked-db list suite returns whatever rows it is handed regardless of the predicate, so it cannot prove Postgres evaluates the correlated EXISTS per row — which is the entire fix.

Matrix covered: live unexhausted token (the regression), token itself expired, token fully consumed, no tokens, unexpired parent, never-expiring parent, short-link child, and expired=true/expired=false complementarity including pagination.total.

Check	Result
New integration suite	2 passed — and confirmed red against the unpatched route (not vacuous)
enrollmentKeysPurgeExpired + enrollmentKeyCleanup integration	16 passed total across the three guard-sharing suites
Affected API unit suites (4 files, serial)	128 passed
apps/web EnrollmentKeyManager	19 passed (no web change; badge untouched)
tsc --noEmit -p apps/api	clean
eslint on changed files	clean

Closes #3191

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying breeze with    Cloudflare Pages

Latest commit:	8c016db
Status:	✅  Deploy successful!
Preview URL:	https://67a913b8.breeze-9te.pages.dev
Branch Preview URL:	https://fix-3191-expired-filter-live.breeze-9te.pages.dev

View logs

[ToddHebebrand]

Review run: /pr-review-toolkit:review-pr — code-reviewer, pr-test-analyzer, comment-analyzer, silent-failure-hunter (4 agents, parallel).

Findings: 11 raised → 10 addressed in 826e4a6, 1 deferred (below); 0 outstanding blockers.

All four reviewers independently converged on the same top finding, and it was a real one:

• Clock split (all 4 agents). expired=true bound a JS new Date() while expired=false used SQL NOW(). Under API↔DB skew a key expiring in that window matched both branches or neither — exactly the "reachable from neither toggle" failure the new partition test claims to rule out, and the comment asserting "exact complements" was therefore false. Both branches now read one NOW().
• #3034 was miscited as the origin of the reportsInstallerCapacity suppression. It is an open issue arguing that suppression is wrong; the origin is Download Installer shows enrollment-key usage 0/1 instead of 0/X until installer is first run #2992 / PR fix(api,web): show real installer capacity on Enrollment Keys (#2992) #2993. Corrected, plus the coupling note that actually matters: if Installer capacity is suppressed when an installer is built from a short-link child key #3034 is ever fixed, the short_code IS NULL gate must move with it or [UI][API] Enrollment Keys "Hide expired" filter is parent-only — hides rows the badge correctly shows as Active #3191 comes straight back for those rows.
• #3045 → #3039 — the badge and route annotate that change by issue everywhere else, so grepping #3045 in EnrollmentKeyManager.tsx returned nothing.
• "iff" was false (the next paragraph was its own counterexample) → "only if". "exact SQL counterpart" now names its two seams: the JS-vs-Postgres clock, and that consumed_count <= max_usage has no DB CHECK — it is upheld only by the conditional UPDATE in routes/installer.ts.
• The invariant is now qualified. fetchInstallerTokenUsage degrades to an empty Map on failure, dropping every badge back to parent expiry while this WHERE clause cannot degrade — so in that window the page can render an "Expired" row under "Hide expired". Documented rather than papered over; it is loud in Sentry, and degrading the row set would be strictly worse.
• A comment justified the in-branch build with a query cost that doesn't exist (db.select() is a lazy builder). Replaced with the real reasons — the per-call new Date() (hoisting would freeze "now" for the process lifetime, a genuine correctness bug) and the mocked suites' schema stub.

Tests: 2 → 5 cases, from the test-analyzer's two rated-8 gaps:

• installerTokens is now asserted from the same response the filter produced, so the badge half of the invariant is checked instead of trusted. Without it, relaxing reportsInstallerCapacity flips a badge to Active while the filter keeps hiding the row — [UI][API] Enrollment Keys "Hide expired" filter is parent-only — hides rows the badge correctly shows as Active #3191 reintroduced with the suite fully green.
• Partner scope (correlated EXISTS over a second RLS-forced table; a blind subquery would silently no-op for every MSP-scoped tech). System scope is documented as unreachable through this harness — no membership row, so it 403s on requirePermission before reaching the route.
• Foreign-org token, since the subquery correlates only on parent_enrollment_key_id and leans entirely on RLS for tenant safety.
• Multi-token keys — the badge SUMs and the filter does a per-row EXISTS; a single-token fixture cannot exercise that equivalence at all.

Deferred (not this PR): silent-failure-hunter flagged that "Delete expired" can return { success: true, deletedCount: 0 } and silently no-op on rows the list presents as expired, with a toast that reads like success. Pre-existing, on the delete path, and needs a wire field (skippedLiveInstallerCount) plus UI — worth its own issue rather than widening this one.

Tests: new suite 5 passed, and 4 of the 5 re-confirmed red against the pre-fix route (the 5th is the RLS case, correctly green either way); enrollmentKeysPurgeExpired + enrollmentKeyCleanup integration 19 passed total across the three guard-sharing suites; 4 affected API unit files 128 passed; apps/web EnrollmentKeyManager 19 passed; tsc --noEmit -p apps/api clean; eslint clean.

CI condition: the pull_request trigger dropped for this branch — gh run list showed zero Actions runs and gh pr checks showed only a Cloudflare Pages entry, which reads deceptively like a green board. Dispatched run 31127345406 by hand via workflow_dispatch; it was queued at hand-off. Confirm that run is green before merging — the check list on the PR is not evidence on its own here.

Status: review-clean, awaiting maintainer merge.