test: property-check the auth rate limiter against a sliding-window oracle - #593

Summary

• Adds a fast-check property suite for lib/auth-rate-limit.ts — the sliding-window limiter that gates OAuth attempts per account. The natural companion to test: property-check the circuit breaker's availability contract #592's circuit-breaker suite: this module is the L3 convention's canonical module-state example, and its oracle (timestamps-in-window) is trivial enough for a clean model-based test.

What Changed

New test/property/auth-rate-limit.property.test.ts (3 properties, real module under vi.useFakeTimers() with a 3-attempt / 1-second config so sequences cross the expiry boundary):

1. Model-based equivalence — for any interleaving of record/reset/advance events across three accounts, with every call going through a decorated id spelling (uppercase, leading/trailing whitespace, tabs), getAttemptsRemaining and canAttemptAuth match a trivial timestamps-in-window oracle keyed by canonical id. One property pins both the sliding window arithmetic and the trim+lowercase bucket mapping.
2. Gate fidelity — checkAuthRateLimit throws AuthRateLimitError exactly when canAttemptAuth is false, and the error's payload is live: the canonical accountId, attemptsRemaining === 0, and resetAfterMs agreeing with getTimeUntilReset (and strictly positive).
3. No wedged buckets — recordAuthAttempt doesn't cap at maxAttempts, so a burst can stack more timestamps than the limit; the property proves any burst (up to 4× the limit, arbitrary intra-burst gaps) still unblocks completely after one quiet window, with getTimeUntilReset bounded by windowMs throughout.

Validation

• npm test -- test/property/auth-rate-limit.property.test.ts test/auth-rate-limit.test.ts — 25/25 (new 3 + existing 22 untouched)
• npm run typecheck (also via pre-commit hook)
• npx eslint test/property/auth-rate-limit.property.test.ts --max-warnings=0
• Module-state hygiene: config restored to the documented defaults and buckets cleared in afterEach; ids namespaced per fc iteration so no run can observe another's buckets

Docs and Governance Checklist

• Test-only; no behavior or docs surface changed

Risk and Rollback

• Risk level: minimal — additive test file; conventions match the existing test/property/ suites (explicit vitest imports, plain fc.assert, fake timers scoped with try/finally).
• Rollback plan: revert the single commit.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

adds test/property/auth-rate-limit.property.test.ts, a three-property fast-check suite for the sliding-window oauth rate limiter, covering model-based oracle equivalence, gate-throw fidelity, and burst-then-expiry unblocking.

• property 1 runs record/reset/advance interleavings across three accounts with five decorated id spellings and checks getAttemptsRemaining/canAttemptAuth against a timestamp-filter oracle after every step.
• property 2 asserts checkAuthRateLimit throws AuthRateLimitError exactly when canAttemptAuth is false and that the error fields match live module state — but only exercises a pre-canonical id, leaving gateError.accountId unverified for decorated inputs.
• property 3 proves any over-burst (up to 4× MAX_ATTEMPTS) unblocks completely after one quiet window, with getTimeUntilReset bounded throughout.

Confidence Score: 4/5

safe to merge as-is, but property 2 contains a coverage gap that lets a real module behaviour (raw accountId echoed in AuthRateLimitError) go undetected

the suite is additive and the first and third properties are logically sound. the second property's gateError.accountId assertion uses a pre-canonical id, so it cannot catch the module storing the raw caller-supplied string in the error. this is a live gap between what the PR description claims is tested and what is actually exercised — downstream consumers of AuthRateLimitError.accountId who expect the canonical form could receive a decorated string in production

test/property/auth-rate-limit.property.test.ts — property 2 needs a decorated-spelling path through checkAuthRateLimit to validate gateError.accountId

Important Files Changed

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
test/property/auth-rate-limit.property.test.ts:145
**`gateError.accountId` assertion is vacuously canonical**

`id` is already lowercase and trimmed (`gate-${runCounter++}@example.com`), so `expect(gateError.accountId).toBe(id)` passes regardless of whether the module canonicalizes the id or echoes the raw input. `checkAuthRateLimit` stores the raw caller-supplied string directly in the error (`throw new AuthRateLimitError(accountId, ...)`) — calling it with a decorated spelling like `" [email protected] "` would produce `gateError.accountId === " [email protected] "`, not the canonical `"[email protected]"`. Property 1 applies `arbDecoration` to every module call except `checkAuthRateLimit`, leaving this path uncovered and the PR description's claim of "the canonical accountId" unverified.

### Issue 2 of 2
test/property/auth-rate-limit.property.test.ts:178-184
**`recordAuthAttempt` is misindented inside the burst loop**

`recordAuthAttempt(id)` sits at the same tab depth as the `for` statement itself rather than one level deeper, making it look like it lives outside the loop. The closing `}` is also at the for-statement level, so the braces confirm it is inside — but a reader scanning the indentation could easily conclude the record call runs only once (after the loop), which would invalidate the burst-count premise of the property. since this is a rate-limit test where the recorded-count is the invariant under test, the misleading indentation is worth fixing for future maintainers.

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into claude/audit-74..." | Re-trigger Greptile}