fix(rate-limit): key IPv6 rate buckets by /64 instead of /128 (#205)

[dcccrypto]

Addresses the rate limiter portion of #205. WS counters and the IP blocklist are deliberately left as follow-ups — reasoning at the bottom.

The bug

normalizeIp() only unwrapped ::ffff:-mapped addresses, so real IPv6 clients were bucketed on the full 128-bit address. A host controlling a /64 — the standard cloud and residential allocation — rotates source addresses and mints a fresh quota per request.

Measured directly against the pre-fix implementation:

4 addresses inside ONE /64
  OLD: 4 distinct buckets -> 400 req/min   (bypass)
  NEW: 1 distinct bucket  -> 100 req/min
  new key: read:2001:db8:0:0::/64

This is the enabler for the expensive endpoints /candles, /chart and WS subscribe storms.

The fix

New src/utils/ip-key.ts exporting rateLimitKey(), used for the read: and write: buckets. ip itself is untouched, so logs and the could-not-determine-IP path keep full address fidelity. IPv4 behaviour is unchanged, including ::ffff: unwrapping.

No new dependency — and why

#205 recommends a vetted IP library rather than a hand-rolled parser. That is good advice I chose not to take here, for a concrete reason: adding a dependency means regenerating pnpm-lock.yaml — the exact file broken by #232, which pins @percolatorct/sdk to a local filesystem path. Regenerating it on a developer machine re-bakes that path and would deepen the blocker my PR #233 is trying to clear.

Instead the hand-written expansion is cross-checked against Node's built-in net.BlockList. BlockList.addSubnet(a, 64) masks host bits itself, so check(b) is an independent answer to "are a and b in the same /64?" that never consults our implementation:

361 address pairs compared, 0 mismatches.

That covers compressed forms (2001:db8::1), fully expanded forms, embedded IPv4 tails (2001:db8::1.2.3.4), zone ids (fe80::2%eth0), ::, and ::1.

If a reviewer would still rather take the library, I am happy to swap it in once #233 lands and the lockfile is safe to regenerate.

How to test

tests/utils/ip-key.test.ts — 8 tests:

test	asserts
agrees with net.BlockList on every pair	361 pairs, 0 mismatches
collapses rotation within one /64	4 addresses → 1 bucket
keeps distinct /64s distinct	no over-collapsing
leaves IPv4 exactly as-is	4 addresses unchanged
unwraps ::ffff:1.2.3.4	→ 1.2.3.4
two IPv4s stay separate	no over-collapsing
ignores zone id	fe80::2%eth0 ≡ fe80::2
unparseable input	falls back to verbatim

Unparseable input keeps a per-value bucket (the pre-#205 behaviour) rather than collapsing into one shared key — otherwise a malformed value could throttle unrelated clients.

	baseline origin/main	with fix
tests passed	255	263 (+8)
test failures	0	0
tsc errors	26	26 — none in the files touched here

The one failing file (tests/sdk-smoke.test.ts) fails identically on clean origin/main. CI will also still be red at install until #233 lands.

Why WS counters and the blocklist are NOT here

#205 says all three normalizeIp copies "must be fixed together". I looked at doing that and think it should be sequenced instead:

1. The WS per-IP counters are 9 call sites (ws.ts:654–1144) split across two variables (clientIp at upgrade, client.ip afterwards), with increment/decrement pairs spanning both. Changing them piecemeal causes permanent counter drift — a decrement under a different key than its increment leaks the slot forever. That needs to be one atomic change (most likely a client.ipKey field), not a find-and-replace bolted onto this PR.

2. ws.ts is already modified by my unreviewed fix(ws): fail closed when WS_AUTH_SECRET is unset (#212) #236. Landing a second 9-site change to the same file before that is reviewed just creates conflicts for the reviewer.

3. The blocklist is a different question, not a bucketing one. ip-blocklist.ts uses normalizeIp for exact matching, so switching it to a /64 key would silently widen every configured block from one address to an entire allocation. That is IPv6 addresses cannot be blocklisted or auth-banned — no fail-closed behaviour #208's call to make (it asks for either real IPv6 CIDR support or fail-closed), and it is a policy decision rather than a key change. net.BlockList — already proven correct here as the test oracle — is a strong candidate for implementing it with no dependency either.

rateLimitKey() is exported and ready for both follow-ups.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
percolator-api	Error		Jul 20, 2026 8:04pm

[coderabbitai]

Warning

Review limit reached

@dcccrypto, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 5 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c0f6e4ba-c592-43db-84b3-b21695393504

📥 Commits

Reviewing files that changed from the base of the PR and between b2751f4 and b8ec9c2.

📒 Files selected for processing (3)

• src/middleware/rate-limit.ts
• src/utils/ip-key.ts
• tests/utils/ip-key.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/api-205-ipv6-rate-limit-key

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dcccrypto]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.