Rework rate limiting

[nemvince]

We need to think about what happens when the whole school accesses Filc on school PCs without logging in. They will all appear as the same UA as the PCs are uniformly imaged and the same IP as they are on the same network.

[coderabbitai]

Coding Plan

Summary

• Introduce an anonymous ID cookie to uniquely identify unauthenticated browser sessions, solving the core problem of many school users colliding into a single rate limit bucket
• Remove User-Agent from the rate limit key since it provides no differentiation on uniformly configured PCs
• Externalize rate limit configuration to environment variables for operational flexibility
• Maintain the existing single-tier rate limiting model while enabling future tiered approaches through the improved architecture

Design Choices

Design Choice 1: Should authenticated and unauthenticated users have different rate limits?

Options Considered:

1. Single global limit for all users (current behavior, just with better key generation)
2. Separate configurable limits for authenticated vs unauthenticated users

Chosen Option: 1

Rationale: Keep a single limit initially but with proper per-client identification. The core problem is key collision, not the limit value itself. Tiered limits can be added later if needed.

Design Choice 2: How should anonymous users be identified to create unique rate limit buckets?

Options Considered:

1. Set a persistent anonymous ID cookie for unauthenticated requests
2. Use additional request headers (Accept-Language, Accept-Encoding) in the key
3. Accept shared buckets but increase the global limit significantly

Chosen Option: 1

Rationale: An anonymous ID cookie provides reliable per-browser differentiation. Header-based approaches fail on uniformly configured school PCs where headers are also identical. Simply increasing limits doesn't solve the fundamental collision problem.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Make Rate Limit Configuration Flexible

Externalize the hardcoded rate limit values (180 requests, 60-second window) into environment variables, enabling operators to tune thresholds without code changes and preparing for future tiered limiting if needed.

Task 1: Add Rate Limit Environment Variables

Define new optional environment variables for rate limiting configuration with sensible defaults matching current behavior.

• Add CHRONOS_RATE_LIMIT_MAX (number, default 180) and CHRONOS_RATE_LIMIT_WINDOW_MS (number, default 60000) to the Zod schema in apps/chronos/src/utils/environment.ts
• Both should be optional with defaults so existing deployments continue working unchanged

Task 2: Update Rate Limiter to Use Environment Config

Replace hardcoded values in the rate limiter configuration with environment-sourced values.

• Modify the rateLimiter() call in apps/chronos/src/index.ts to read limit and windowMs from the env object instead of hardcoded values

🤖 Prompt for AI agents

This phase externalizes the hardcoded rate limit values into environment
variables, ensuring existing deployments continue working with no changes while
allowing operators to tune thresholds.

- In `apps/chronos/src/utils/environment.ts`, add two new optional fields to the
Zod schema:
  - `CHRONOS_RATE_LIMIT_MAX`: a number type with a default of `180`
  - `CHRONOS_RATE_LIMIT_WINDOW_MS`: a number type with a default of `60000`
- In `apps/chronos/src/index.ts`, update the `rateLimiter()` call to replace any
hardcoded `limit` and `windowMs` values by reading them from the `env` object
(e.g., `env.CHRONOS_RATE_LIMIT_MAX` and `env.CHRONOS_RATE_LIMIT_WINDOW_MS`)

Phase 2: Implement Anonymous Client Identification

Create a mechanism to assign unique identifiers to unauthenticated clients, ensuring each browser instance gets its own rate limit bucket regardless of shared IP or User-Agent.

Task 1: Create Anonymous ID Middleware

Build middleware that assigns a persistent anonymous identifier cookie to requests that lack an authenticated session.

• Create a new middleware file apps/chronos/src/middleware/anonymous-id.ts
• Generate a random UUID for clients without a session and without an existing anonymous ID cookie
• Set the cookie with appropriate attributes (HttpOnly, SameSite=Lax, reasonable expiry like 24 hours)
• Store the anonymous ID in the Hono context (e.g., c.set('anonymousId', id)) for downstream use
• If a session exists, skip cookie generation (authenticated users don't need anonymous IDs)
• If the cookie already exists, read and set it in context without regenerating

Task 2: Integrate Anonymous ID Middleware into Chain

Register the middleware in the correct position within the global middleware stack.

• Add the anonymous ID middleware to apps/chronos/src/index.ts after authenticationMiddleware (so session info is available) but before rateLimiter
• The middleware order should be: CORS → Authentication → Anonymous ID → Security → Timing → Rate Limiter

🤖 Prompt for AI agents

This phase creates a new anonymous ID middleware that assigns a unique
persistent cookie to unauthenticated clients, and wires it into the correct
position in the global middleware chain.

**Create `apps/chronos/src/middleware/anonymous-id.ts`:**
- On each request, check whether a session already exists (authenticated user)
  - If a session exists: skip all cookie logic and call `next()`
  - If no session exists:
- Read the anonymous ID cookie from the request (cookie name should reference
`CHRONOS_RATE_LIMIT_COOKIE_NAME` from env, defaulting to `"filc_rl_id"`)
- If the cookie exists: read its value and store it in the Hono context via
`c.set('anonymousId', id)`
- If the cookie does not exist: generate a new random UUID, set it in context
via `c.set('anonymousId', id)`, and set the cookie on the response with the
following attributes: HttpOnly, SameSite=Lax, Max-Age of 24 hours

**Update `apps/chronos/src/index.ts`:**
- Import and register the anonymous ID middleware
- Place it after `authenticationMiddleware` but before `rateLimiter`, following
the order: CORS → Authentication → Anonymous ID → Security → Timing → Rate
Limiter

Phase 3: Update Rate Limit Key Generation

Modify the key generator to leverage the anonymous ID for unauthenticated users, eliminating the collision problem where all unauthenticated users from the same network shared a single bucket.

Task 1: Refactor Key Generator Logic

Update the keyGenerator function to produce unique keys for both authenticated and unauthenticated users.

• Modify the keyGenerator in apps/chronos/src/index.ts to use the following priority for user identification:
  • If session exists: use session.id (current behavior for authenticated users)
  • If no session but anonymous ID exists: use the anonymous ID from context
  • Fallback to "unknown" only if neither exists (edge case)
• Simplify the key format: remove User-Agent from the key since it causes collisions on uniformly imaged PCs and provides no differentiation value
• Keep IP in the key as a secondary factor for defense-in-depth, but the primary identifier should be session ID or anonymous ID
• New key format suggestion: <session-id-or-anonymous-id>|<ip-address>

Task 2: Add Cookie Name Configuration

Make the anonymous ID cookie name configurable to allow customization if needed.

• Add an optional CHRONOS_RATE_LIMIT_COOKIE_NAME environment variable to apps/chronos/src/utils/environment.ts with default value like "filc_rl_id"
• Reference this in the anonymous ID middleware for cookie name consistency

🤖 Prompt for AI agents

This phase updates the `keyGenerator` function in `apps/chronos/src/index.ts` to
use unique per-client identifiers and removes the User-Agent from the key, and
also adds the cookie name environment variable.

**Update `keyGenerator` in `apps/chronos/src/index.ts`:**
- Determine the primary client identifier using the following priority:
  1. If a session exists: use `session.id`
2. Else if an anonymous ID exists in context (set by anonymous ID middleware):
use the anonymous ID
  3. Else: fall back to `"unknown"`
- Remove User-Agent from the key entirely
- Keep the IP address as a secondary factor
- Produce a key in the format: `<session-id-or-anonymous-id>|<ip-address>`

**Update `apps/chronos/src/utils/environment.ts`:**
- Add an optional `CHRONOS_RATE_LIMIT_COOKIE_NAME` string field to the Zod
schema with a default value of `"filc_rl_id"`
- Ensure the anonymous ID middleware references this env variable for cookie
name consistency

Research

Chronos is a Hono-based backend API server running on Bun. Rate limiting is implemented globally using hono-rate-limiter with an in-memory store, configured in apps/chronos/src/index.ts. The current rate limit key combines User-Agent, session ID (or "none" for unauthenticated users), and IP address. Many timetable, substitution, and news endpoints are publicly accessible without authentication. Environment configuration is managed via a Zod schema in apps/chronos/src/utils/environment.ts.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase externalizes the hardcoded rate limit values into environment
variables, ensuring existing deployments continue working with no changes while
allowing operators to tune thresholds.

- In `apps/chronos/src/utils/environment.ts`, add two new optional fields to the
Zod schema:
  - `CHRONOS_RATE_LIMIT_MAX`: a number type with a default of `180`
  - `CHRONOS_RATE_LIMIT_WINDOW_MS`: a number type with a default of `60000`
- In `apps/chronos/src/index.ts`, update the `rateLimiter()` call to replace any
hardcoded `limit` and `windowMs` values by reading them from the `env` object
(e.g., `env.CHRONOS_RATE_LIMIT_MAX` and `env.CHRONOS_RATE_LIMIT_WINDOW_MS`)
===============================================================================

Task: 2

This phase creates a new anonymous ID middleware that assigns a unique
persistent cookie to unauthenticated clients, and wires it into the correct
position in the global middleware chain.

**Create `apps/chronos/src/middleware/anonymous-id.ts`:**
- On each request, check whether a session already exists (authenticated user)
  - If a session exists: skip all cookie logic and call `next()`
  - If no session exists:
- Read the anonymous ID cookie from the request (cookie name should reference
`CHRONOS_RATE_LIMIT_COOKIE_NAME` from env, defaulting to `"filc_rl_id"`)
- If the cookie exists: read its value and store it in the Hono context via
`c.set('anonymousId', id)`
- If the cookie does not exist: generate a new random UUID, set it in context
via `c.set('anonymousId', id)`, and set the cookie on the response with the
following attributes: HttpOnly, SameSite=Lax, Max-Age of 24 hours

**Update `apps/chronos/src/index.ts`:**
- Import and register the anonymous ID middleware
- Place it after `authenticationMiddleware` but before `rateLimiter`, following
the order: CORS → Authentication → Anonymous ID → Security → Timing → Rate
Limiter
===============================================================================

Task: 3

This phase updates the `keyGenerator` function in `apps/chronos/src/index.ts` to
use unique per-client identifiers and removes the User-Agent from the key, and
also adds the cookie name environment variable.

**Update `keyGenerator` in `apps/chronos/src/index.ts`:**
- Determine the primary client identifier using the following priority:
  1. If a session exists: use `session.id`
2. Else if an anonymous ID exists in context (set by anonymous ID middleware):
use the anonymous ID
  3. Else: fall back to `"unknown"`
- Remove User-Agent from the key entirely
- Keep the IP address as a secondary factor
- Produce a key in the format: `<session-id-or-anonymous-id>|<ip-address>`

**Update `apps/chronos/src/utils/environment.ts`:**
- Add an optional `CHRONOS_RATE_LIMIT_COOKIE_NAME` string field to the Zod
schema with a default value of `"filc_rl_id"`
- Ensure the anonymous ID middleware references this env variable for cookie
name consistency

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!