Imported from bedkillerspacex-boop/codex-skill-library (javascript-rate-keys/SKILL.md). Install upstream with npx skills add bedkillerspacex-boop/codex-skill-library --skill javascript-rate-keys. Copyright stays with the author.

Javascript Rate Keys

Scope And Authorization

• In scope: Key construction for limiters on APIs you own (Express, Fastify, Nest, API Gateway + Node, edge workers).
• Out of scope: Bypassing someone else’s rate limits; credential stuffing tooling.
• Test key isolation in staging with multiple synthetic identities.
• Redact real API keys from logs when debugging counters.
• Pair with javascript-quota-design for plan math; code-quality-standards for code.

When To Use

• Choosing what goes into the rate-limit key so fair use and abuse controls work.
• Fixing NAT/proxy pain (enterprise users share one IP) or multi-key abuse (one user many tokens).
• Preventing Redis key explosion (unbounded path/query in key).
• Dual limits: per-user and per-IP on login; per-tenant and global safety cap.

Do Not Use As Primary

Key design principles

Identity matrix

Workflow

1. Confirm scope and success criteria

1. List endpoints and whether they are authenticated.
2. Success: no cross-tenant counter sharing; cardinality under budget; dual-key login limits documented; bypass paths ticketed.
3. Note trusted proxy config (X-Forwarded-For hop count).

2. Inventory current keys

rg -n "rateLimit|RateLimiter|incr\(|rl:|quota:" -g '!node_modules' -g '*.{js,ts}'
rg -n "X-Forwarded-For|req\.ip|request\.ip" -g '!node_modules'

3. Define route classes (not raw paths)

// Map concrete paths to stable classes — avoids /users/1 vs /users/2 key explosion
export function routeClass(method, pathTemplate) {
  return `${method.toUpperCase()}:${pathTemplate}`; // e.g. GET:/v1/items/:id
}

// Express: use route path from layer when available, not req.url with query
export function clientIp(req, { trustedHops = 1 } = {}) {
  // Only after correct proxy trust — misconfig = client spoof
  return req.ip; // set app.set('trust proxy', trustedHops)
}

4. Build composite keys

/**
 * Dual-key example for authenticated API
 * Returns ordered keys to check (all must allow)
 */
export function rateKeys(ctx) {
  const v = "rl:v1";
  const keys = [];
  keys.push(`${v}:global:${ctx.routeClass}`);
  if (ctx.tenantId) keys.push(`${v}:tenant:${ctx.tenantId}:${ctx.routeClass}`);
  if (ctx.apiKeyId) keys.push(`${v}:key:${ctx.apiKeyId}`);
  else if (ctx.userId) keys.push(`${v}:user:${ctx.userId}:${ctx.routeClass}`);
  else keys.push(`${v}:ip:${ctx.ip}:${ctx.routeClass}`);
  return keys;
}

// Login: always dual IP + account fingerprint
export function loginKeys({ ip, usernameNorm }) {
  const v = "rl:v1:login";
  return [`${v}:ip:${ip}`, `${v}:user:${usernameNorm}`];
}

5. Anti-bypass and privacy

6. Verify isolation and cardinality

npm run test:unit -- --grep rateKeys
# Staging: two API keys same tenant — confirm per-key and tenant caps
# Redis: SCAN rl:v1:* — watch unique key count under load test

Assertions:

• User A load does not decrement User B remaining.
• Unauthenticated flood hits IP keys; authenticated uses user keys.
• Query strings do not create unique keys per request.

7. Hand off

1. Document key format in runbook for support (how to reset a bucket).
2. TTL on every key; no immortal counters.
3. Metrics: rate_limit_keys_cardinality, denies by key tier.

Good / Bad

Output Checklist

• Identity primary/secondary chosen per surface
• Route classes defined (no high-cardinality paths)
• Dual-key rules for login and global safety
• Trusted proxy / IP derivation correct
• Key version prefix and TTL policy
• Isolation tests for two tenants/keys
• Cardinality checked under load
• Privacy hashing if usernames in keys
• Support reset runbook
• code-quality-standards applied

Rules

• Do not help evade third-party rate limits.
• Never trust client-supplied identity headers without authentication.
• Prefer authenticated stable IDs; use IP as secondary or anonymous primary only.
• Keep focus on key design; quota numbers live in javascript-quota-design.