feat: integrate rate limiting by default in the manager (opt-in)

Author: max-programming

README.md

@@ -11,7 +11,7 @@ A TypeScript library for secure API key management with cryptographic hashing, e
 - **Secure by Default**: SHA-256/SHA-512 hashing with optional salt and timing-safe comparison
 - **Smart Key Detection**: Automatically extracts keys from `Authorization`, `x-api-key`, or custom headers
 - **Built-in Caching**: Optional in-memory or Redis caching for validated keys
-- **Rate Limiting**: Built-in rate limiting with fixed window algorithm
+- **Rate Limiting**: Optional automatic rate limiting on verify calls with atomic counters
 - **Flexible Storage**: Memory, Redis, and Drizzle ORM adapters included
 - **Scope-based Permissions**: Fine-grained access control
 - **Key Management**: Enable/disable, rotate, and soft-revoke keys with audit trails
@@ -81,6 +81,12 @@ const keys = createKeys({
   // Usage tracking
   autoTrackUsage: true, // Automatically update lastUsedAt on verify
 
+  // Rate limiting (opt-in, requires cache)
+  rateLimit: {
+    maxRequests: 100,
+    windowMs: 60_000, // 1 minute window
+  },
+  
   // Header detection
   headerNames: ['x-api-key', 'authorization'],
   extractBearer: true,
@@ -142,8 +148,13 @@ const result = await keys.verify(headers, {
 // Check result
 if (result.valid) {
   console.log(result.record)
+  // If rate limiting is enabled, result.rateLimit will include rate limit info
+  if (result.rateLimit) {
+    console.log(`${result.rateLimit.remaining} requests remaining`)
+  }
 } else {
-  console.log(result.error) // 'Missing API key' | 'Invalid API key' | 'API key has expired' | 'API key is disabled' | 'API key has been revoked'
+  console.log(result.error) // 'Missing API key' | 'Invalid API key' | 'API key has expired' | 'API key is disabled' | 'API key has been revoked' | 'Rate limit exceeded'
+  console.log(result.errorCode) // 'MISSING_KEY' | 'INVALID_KEY' | 'EXPIRED' | 'DISABLED' | 'REVOKED' | 'RATE_LIMIT_EXCEEDED'
 }
 ```
 
@@ -177,98 +188,80 @@ Protect your API from abuse with built-in rate limiting. Uses the same cache inf
 
 **Note:** Cache must be enabled to use rate limiting.
 
+#### Automatic Rate Limiting
+
+Enable rate limiting globally on all verify calls by adding the `rateLimit` config option:
+
 ```typescript
 const keys = createKeys({
   cache: true, // Required for rate limiting
-  cacheTtl: 60,
-})
-
-// Create a rate limiter
-const rateLimiter = keys.createRateLimiter({
-  maxRequests: 100,
-  windowMs: 60_000, // 1 minute window
-  keyPrefix: 'ratelimit', // optional, defaults to 'ratelimit'
+  rateLimit: {
+    maxRequests: 100,
+    windowMs: 60_000, // 1 minute window
+  },
 })
 
-// Check rate limit
+// Rate limiting happens automatically on verify()
 const result = await keys.verify(headers)
-if (!result.valid) {
-  return { error: result.error, status: 401 }
-}
 
-const rateLimit = await rateLimiter.check(result.record)
-if (!rateLimit.allowed) {
-  return {
-    error: 'Rate limit exceeded',
-    status: 429,
-    resetAt: rateLimit.resetAt,
-    resetMs: rateLimit.resetMs,
+if (!result.valid) {
+  if (result.errorCode === 'RATE_LIMIT_EXCEEDED') {
+    return {
+      error: 'Too many requests',
+      status: 429,
+      resetAt: result.rateLimit.resetAt,
+      resetMs: result.rateLimit.resetMs,
+    }
   }
+  return { error: result.error, status: 401 }
 }
 
-// Access rate limit info
+// Rate limit info is included in successful responses
 console.log({
-  current: rateLimit.current,      // Current request count
-  limit: rateLimit.limit,          // Max requests allowed
-  remaining: rateLimit.remaining,  // Remaining requests
-  resetMs: rateLimit.resetMs,      // Time until reset (ms)
-  resetAt: rateLimit.resetAt,      // ISO timestamp when window resets
+  current: result.rateLimit.current,      // Current request count
+  limit: result.rateLimit.limit,          // Max requests allowed
+  remaining: result.rateLimit.remaining,  // Remaining requests
+  resetMs: result.rateLimit.resetMs,      // Time until reset (ms)
+  resetAt: result.rateLimit.resetAt,      // ISO timestamp when window resets
 })
 ```
 
-**Dry-run checks** (check without incrementing):
-```typescript
-const rateLimit = await rateLimiter.check(record, { increment: false })
-```
-
-**Custom identifiers** (e.g., per-owner limits instead of per-key):
-```typescript
-const rateLimit = await rateLimiter.check(record, {
-  identifier: record.metadata.ownerId, // Rate limit by user, not by key
-})
-```
-
-**Manual reset**:
-```typescript
-await rateLimiter.reset(record)
-```
-
-**Get current count without incrementing**:
-```typescript
-const count = await rateLimiter.getCurrentCount(record)
-```
-
 **Complete middleware example with rate limit headers**:
 ```typescript
 app.use('/api/*', async (c, next) => {
   const result = await keys.verify(c.req.raw.headers)
 
   if (!result.valid) {
+    if (result.errorCode === 'RATE_LIMIT_EXCEEDED') {
+      c.header('Retry-After', Math.ceil(result.rateLimit.resetMs / 1000).toString())
+      c.header('X-RateLimit-Limit', result.rateLimit.limit.toString())
+      c.header('X-RateLimit-Remaining', '0')
+      c.header('X-RateLimit-Reset', result.rateLimit.resetAt)
+      return c.json({ error: 'Too many requests' }, 429)
+    }
     return c.json({ error: result.error }, 401)
   }
 
-  const rateLimit = await rateLimiter.check(result.record)
-  
-  // Set rate limit headers (standard practice)
-  c.header('X-RateLimit-Limit', rateLimit.limit.toString())
-  c.header('X-RateLimit-Remaining', rateLimit.remaining.toString())
-  c.header('X-RateLimit-Reset', rateLimit.resetAt)
-  
-  if (!rateLimit.allowed) {
-    c.header('Retry-After', Math.ceil(rateLimit.resetMs / 1000).toString())
-    return c.json({
-      error: 'Too many requests',
-      resetAt: rateLimit.resetAt,
-    }, 429)
-  }
+  // Set rate limit headers on successful requests
+  c.header('X-RateLimit-Limit', result.rateLimit.limit.toString())
+  c.header('X-RateLimit-Remaining', result.rateLimit.remaining.toString())
+  c.header('X-RateLimit-Reset', result.rateLimit.resetAt)
 
   c.set('apiKey', result.record)
   await next()
 })
 ```
 
-**Different limits for different endpoints**:
+#### Manual Rate Limiting (Advanced)
+
+For custom rate limiting scenarios (e.g., different limits per endpoint), create rate limiters manually:
+
 ```typescript
+const keys = createKeys({
+  cache: true, // Required for rate limiting
+})
+
+// Create custom rate limiters
 const strictLimiter = keys.createRateLimiter({
   maxRequests: 10,
   windowMs: 60_000, // 10 requests per minute
@@ -281,17 +274,55 @@ const normalLimiter = keys.createRateLimiter({
 
 // Use strict limiter for sensitive endpoints
 app.post('/api/sensitive', async (c) => {
-  const rateLimit = await strictLimiter.check(c.get('apiKey'))
+  const result = await keys.verify(c.req.raw.headers)
+  if (!result.valid) {
+    return c.json({ error: result.error }, 401)
+  }
+
+  const rateLimit = await strictLimiter.check(result.record)
+  if (!rateLimit.allowed) {
+    return c.json({ error: 'Too many requests' }, 429)
+  }
   // ...
 })
 
 // Use normal limiter for regular endpoints
 app.get('/api/data', async (c) => {
-  const rateLimit = await normalLimiter.check(c.get('apiKey'))
+  const result = await keys.verify(c.req.raw.headers)
+  if (!result.valid) {
+    return c.json({ error: result.error }, 401)
+  }
+
+  const rateLimit = await normalLimiter.check(result.record)
+  if (!rateLimit.allowed) {
+    return c.json({ error: 'Too many requests' }, 429)
+  }
   // ...
 })
 ```
 
+**Dry-run checks** (check without incrementing):
+```typescript
+const rateLimit = await rateLimiter.check(record, { increment: false })
+```
+
+**Custom identifiers** (e.g., per-owner limits instead of per-key):
+```typescript
+const rateLimit = await rateLimiter.check(record, {
+  identifier: record.metadata.ownerId, // Rate limit by user, not by key
+})
+```
+
+**Manual reset**:
+```typescript
+await rateLimiter.reset(record)
+```
+
+**Get current count without incrementing**:
+```typescript
+const count = await rateLimiter.getCurrentCount(record)
+```
+
 ### Helper Methods
 
 ```typescript
@@ -501,6 +532,14 @@ interface VerifyResult {
   valid: boolean
   record?: ApiKeyRecord
   error?: string
+  errorCode?: ApiKeyErrorCode
+  rateLimit?: {
+    current: number
+    limit: number
+    remaining: number
+    resetMs: number
+    resetAt: string
+  }
 }
 
 interface RateLimitConfig {

src/manager.test.ts

@@ -1105,4 +1105,145 @@ describe("ApiKeyManager - Additional Operations", () => {
 			expect(cached).toBeNull();
 		});
 	});
+
+	describe("rate limiting", () => {
+		it("should enforce rate limits on verify calls", async () => {
+			const keysWithRateLimit = createKeys({
+				prefix: "sk_",
+				cache: true,
+				rateLimit: {
+					maxRequests: 3,
+					windowMs: 60_000,
+				},
+			});
+
+			const { key } = await keysWithRateLimit.create({ ownerId: "user_1" });
+
+			// First 3 requests should succeed
+			const ALLOWED_REQUESTS = 3;
+			for (let i = 0; i < ALLOWED_REQUESTS; i++) {
+				const result = await keysWithRateLimit.verify(key);
+				expect(result.valid).toBe(true);
+				expect(result.rateLimit).toBeDefined();
+				expect(result.rateLimit?.limit).toBe(ALLOWED_REQUESTS);
+				expect(result.rateLimit?.remaining).toBe(ALLOWED_REQUESTS - (i + 1));
+			}
+
+			// 4th request should be rate limited
+			const blockedResult = await keysWithRateLimit.verify(key);
+			expect(blockedResult.valid).toBe(false);
+			expect(blockedResult.errorCode).toBe("RATE_LIMIT_EXCEEDED");
+			expect(blockedResult.error).toBe("Rate limit exceeded");
+			expect(blockedResult.rateLimit).toBeDefined();
+			// biome-ignore lint/style/noMagicNumbers: 4 is the blocked request count
+			expect(blockedResult.rateLimit?.current).toBe(4);
+			expect(blockedResult.rateLimit?.remaining).toBe(0);
+		});
+
+		it("should not include rate limit info when rate limiting is disabled", async () => {
+			const keysWithoutRateLimit = createKeys({
+				prefix: "sk_",
+				cache: true,
+			});
+
+			const { key } = await keysWithoutRateLimit.create({ ownerId: "user_1" });
+			const result = await keysWithoutRateLimit.verify(key);
+
+			expect(result.valid).toBe(true);
+			expect(result.rateLimit).toBeUndefined();
+		});
+
+		it("should throw error when rate limiting is configured without cache", () => {
+			expect(() =>
+				createKeys({
+					prefix: "sk_",
+					rateLimit: {
+						maxRequests: 100,
+						windowMs: 60_000,
+					},
+				})
+			).toThrow("Cache is required for rate limiting");
+		});
+
+		it("should rate limit per API key", async () => {
+			const keysWithRateLimit = createKeys({
+				prefix: "sk_",
+				cache: true,
+				rateLimit: {
+					maxRequests: 2,
+					windowMs: 60_000,
+				},
+			});
+
+			const { key: key1 } = await keysWithRateLimit.create({
+				ownerId: "user_1",
+			});
+			const { key: key2 } = await keysWithRateLimit.create({
+				ownerId: "user_2",
+			});
+
+			// Use key1 twice (hit limit)
+			await keysWithRateLimit.verify(key1);
+			await keysWithRateLimit.verify(key1);
+
+			// Third request for key1 should be blocked
+			const key1Result = await keysWithRateLimit.verify(key1);
+			expect(key1Result.valid).toBe(false);
+			expect(key1Result.errorCode).toBe("RATE_LIMIT_EXCEEDED");
+
+			// key2 should still work (separate rate limit)
+			const key2Result = await keysWithRateLimit.verify(key2);
+			expect(key2Result.valid).toBe(true);
+			expect(key2Result.rateLimit?.remaining).toBe(1);
+		});
+
+		it("should include rate limit info in successful responses", async () => {
+			const keysWithRateLimit = createKeys({
+				prefix: "sk_",
+				cache: true,
+				rateLimit: {
+					maxRequests: 10,
+					windowMs: 60_000,
+				},
+			});
+
+			const { key } = await keysWithRateLimit.create({ ownerId: "user_1" });
+			const result = await keysWithRateLimit.verify(key);
+
+			expect(result.valid).toBe(true);
+			expect(result.rateLimit).toBeDefined();
+			expect(result.rateLimit?.current).toBe(1);
+			expect(result.rateLimit?.limit).toBe(10);
+			// biome-ignore lint/style/noMagicNumbers: 9 is the remaining requests
+			expect(result.rateLimit?.remaining).toBe(9);
+			expect(result.rateLimit?.resetMs).toBeGreaterThan(0);
+			expect(result.rateLimit?.resetAt).toMatch(ISO_DATE_REGEX);
+		});
+
+		it("should rate limit from cache path", async () => {
+			const keysWithRateLimit = createKeys({
+				prefix: "sk_",
+				cache: true,
+				rateLimit: {
+					maxRequests: 2,
+					windowMs: 60_000,
+				},
+			});
+
+			const { key } = await keysWithRateLimit.create({ ownerId: "user_1" });
+
+			// First verify (cache miss)
+			const result1 = await keysWithRateLimit.verify(key);
+			expect(result1.valid).toBe(true);
+
+			// Second verify (cache hit)
+			const result2 = await keysWithRateLimit.verify(key);
+			expect(result2.valid).toBe(true);
+
+			// Third verify should be rate limited (cache hit)
+			const result3 = await keysWithRateLimit.verify(key);
+			expect(result3.valid).toBe(false);
+			expect(result3.errorCode).toBe("RATE_LIMIT_EXCEEDED");
+		});
+	});
 });