diff --git a/src/lib/ai/rate-limit-message.ts b/src/lib/ai/rate-limit-message.ts
new file mode 100644
index 000000000..a8c2dfa76
--- /dev/null
+++ b/src/lib/ai/rate-limit-message.ts
@@ -0,0 +1,49 @@
+export const RATE_LIMIT_ERROR_PREFIX = "AI_RATE_LIMIT";
+
+export type RateLimitWindow = "hour" | "day";
+
+export interface RateLimitMessagePayload {
+ window: RateLimitWindow;
+ retryAfterSeconds: number;
+ limit: number;
+}
+
+export const buildRateLimitMessage = (
+ payload: RateLimitMessagePayload,
+): string => {
+ return [
+ RATE_LIMIT_ERROR_PREFIX,
+ payload.window,
+ Math.max(0, Math.ceil(payload.retryAfterSeconds)),
+ payload.limit,
+ ].join("|");
+};
+
+export const parseRateLimitMessage = (
+ message?: string,
+): RateLimitMessagePayload | null => {
+ if (!message) return null;
+ const parts = message.split("|");
+ if (parts[0] !== RATE_LIMIT_ERROR_PREFIX) return null;
+ if (parts.length < 4) return null;
+
+ const window = parts[1] as RateLimitWindow;
+ const retryAfterSeconds = Number(parts[2]);
+ const limit = Number(parts[3]);
+
+ if (!Number.isFinite(retryAfterSeconds) || retryAfterSeconds < 0) {
+ return null;
+ }
+ if (!Number.isFinite(limit) || limit <= 0) {
+ return null;
+ }
+ if (window !== "hour" && window !== "day") {
+ return null;
+ }
+
+ return {
+ window,
+ retryAfterSeconds,
+ limit,
+ };
+};
diff --git a/src/lib/ai/rate-limit.test.ts b/src/lib/ai/rate-limit.test.ts
new file mode 100644
index 000000000..30b640a2d
--- /dev/null
+++ b/src/lib/ai/rate-limit.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from "vitest";
+import { AiRateLimiter, MemoryRateLimitStore } from "./rate-limit";
+
+const createLimiter = (options: {
+ perHour?: number;
+ perDay?: number;
+ role?: string;
+ defaultPerDay?: number;
+}) => {
+ return new AiRateLimiter({
+ redisUrl: "redis://example.com",
+ limitsByRole: options.role
+ ? { [options.role]: { perHour: options.perHour, perDay: options.perDay } }
+ : {},
+ defaultLimits: options.defaultPerDay
+ ? { perDay: options.defaultPerDay, perHour: options.perHour }
+ : { perHour: options.perHour, perDay: options.perDay },
+ store: new MemoryRateLimitStore(),
+ });
+};
+
+describe("AiRateLimiter", () => {
+ it("allows requests under the limit", async () => {
+ const limiter = createLimiter({ perHour: 2, role: "user" });
+ const userId = "user-1";
+
+ const first = await limiter.check(userId, "user");
+ const second = await limiter.check(userId, "user");
+
+ expect(first.ok).toBe(true);
+ expect(second.ok).toBe(true);
+ });
+
+ it("blocks when hourly limit exceeded", async () => {
+ const limiter = createLimiter({ perHour: 1, role: "user" });
+ const userId = "user-2";
+
+ await limiter.check(userId, "user");
+ const blocked = await limiter.check(userId, "user");
+
+ expect(blocked.ok).toBe(false);
+ if (!blocked.ok) {
+ expect(blocked.window).toBe("hour");
+ expect(blocked.limit).toBe(1);
+ expect(blocked.retryAfterSeconds).toBeGreaterThan(0);
+ }
+ });
+
+ it("resets after window expires", async () => {
+ const realNow = Date.now;
+ let now = realNow();
+ // Override Date.now to simulate time passing without timers API
+ Date.now = () => now;
+
+ try {
+ const limiter = createLimiter({ perHour: 1, role: "user" });
+ const userId = "user-3";
+
+ await limiter.check(userId, "user");
+ const blocked = await limiter.check(userId, "user");
+ expect(blocked.ok).toBe(false);
+
+ // Advance just over one hour
+ now = now + 60 * 60 * 1000 + 10;
+
+ const allowedAgain = await limiter.check(userId, "user");
+ expect(allowedAgain.ok).toBe(true);
+ } finally {
+ Date.now = realNow;
+ }
+ });
+
+ it("applies daily limit when configured", async () => {
+ const limiter = createLimiter({ perHour: 0, perDay: 2, role: "editor" });
+ const userId = "user-4";
+
+ await limiter.check(userId, "editor");
+ await limiter.check(userId, "editor");
+ const blocked = await limiter.check(userId, "editor");
+
+ expect(blocked.ok).toBe(false);
+ if (!blocked.ok) {
+ expect(blocked.window).toBe("day");
+ expect(blocked.limit).toBe(2);
+ }
+ });
+
+ it("uses default limits when role not configured", async () => {
+ const limiter = createLimiter({ perHour: 0, defaultPerDay: 1 });
+ const userId = "user-5";
+
+ await limiter.check(userId, "unknown");
+ const blocked = await limiter.check(userId, "unknown");
+
+ expect(blocked.ok).toBe(false);
+ if (!blocked.ok) {
+ expect(blocked.window).toBe("day");
+ expect(blocked.limit).toBe(1);
+ }
+ });
+});
diff --git a/src/lib/ai/rate-limit.ts b/src/lib/ai/rate-limit.ts
new file mode 100644
index 000000000..095f46067
--- /dev/null
+++ b/src/lib/ai/rate-limit.ts
@@ -0,0 +1,195 @@
+import Redis from "ioredis";
+import logger from "logger";
+import { RateLimitMessagePayload } from "./rate-limit-message";
+
+export type RateLimitCheckResult =
+ | { ok: true }
+ | ({ ok: false } & RateLimitMessagePayload);
+
+export interface RateLimitConfig {
+ perHour?: number;
+ perDay?: number;
+}
+
+export interface RateLimitOptions {
+ redisUrl: string;
+ limitsByRole?: Record;
+ defaultLimits?: RateLimitConfig;
+}
+
+interface RateLimitStore {
+ increment(
+ key: string,
+ windowMs: number,
+ ): Promise<{ count: number; ttlMs: number }>;
+}
+
+class RedisRateLimitStore implements RateLimitStore {
+ private redis: Redis;
+
+ constructor(redisUrl: string) {
+ this.redis = new Redis(redisUrl, {
+ // Allow brief disconnects without throwing "stream isn't writeable"
+ enableOfflineQueue: true,
+ maxRetriesPerRequest: 2,
+ connectTimeout: 5000,
+ commandTimeout: 5000,
+ });
+ }
+
+ async increment(key: string, windowMs: number) {
+ const count = await this.redis.incr(key);
+ if (count === 1) {
+ await this.redis.pexpire(key, windowMs);
+ }
+ const ttlMs = await this.redis.pttl(key);
+ return { count, ttlMs };
+ }
+}
+
+export class AiRateLimiter {
+ private store: RateLimitStore;
+ private limitsByRole: Record;
+ private defaultLimits?: RateLimitConfig;
+
+ constructor(options: RateLimitOptions & { store?: RateLimitStore }) {
+ if (!options.redisUrl) {
+ throw new Error("Redis URL is required for AI rate limiting");
+ }
+ this.limitsByRole = this.sanitizeLimits(options.limitsByRole ?? {});
+ this.defaultLimits = this.sanitizeLimits({
+ default: options.defaultLimits ?? {},
+ }).default;
+ this.store = options.store ?? new RedisRateLimitStore(options.redisUrl);
+ }
+
+ private safeLimit(limit?: number) {
+ if (!limit || limit <= 0 || !Number.isFinite(limit)) return undefined;
+ return Math.floor(limit);
+ }
+
+ private sanitizeLimits(limits: Record) {
+ return Object.entries(limits).reduce>(
+ (acc, [role, config]) => {
+ const perHour = this.safeLimit(config.perHour);
+ const perDay = this.safeLimit(config.perDay);
+ if (perHour || perDay) {
+ acc[role.toLowerCase()] = { perHour, perDay };
+ }
+ return acc;
+ },
+ {},
+ );
+ }
+
+ private async checkWindow(
+ userId: string,
+ window: "hour" | "day",
+ limit: number,
+ ): Promise {
+ const windowMs = window === "hour" ? 60 * 60 * 1000 : 24 * 60 * 60 * 1000;
+ const key = `ai:rate:${window}:${userId}`;
+ const { count, ttlMs } = await this.store.increment(key, windowMs);
+
+ if (count > limit) {
+ const retryAfterSeconds = Math.max(1, Math.ceil(ttlMs / 1000));
+ logger.warn(
+ `AI rate limit exceeded: user=${userId} window=${window} limit=${limit} count=${count}`,
+ );
+ return {
+ ok: false,
+ window,
+ retryAfterSeconds,
+ limit,
+ };
+ }
+
+ return { ok: true } as const;
+ }
+
+ async check(userId: string, role?: string): Promise {
+ const roleKey = (role ?? "").toLowerCase();
+ const limits = this.limitsByRole[roleKey] || this.defaultLimits;
+
+ if (!limits || (!limits.perHour && !limits.perDay)) {
+ return { ok: true } as const;
+ }
+
+ if (limits.perHour) {
+ const result = await this.checkWindow(userId, "hour", limits.perHour);
+ if (!result.ok) return result;
+ }
+
+ if (limits.perDay) {
+ const result = await this.checkWindow(userId, "day", limits.perDay);
+ if (!result.ok) return result;
+ }
+
+ return { ok: true } as const;
+ }
+}
+
+let limiter: AiRateLimiter | null = null;
+
+export const getAiRateLimiter = () => {
+ if (limiter) return limiter;
+
+ const redisUrl = process.env.REDIS_URL;
+ const roles = ["USER", "EDITOR", "ADMIN"] as const;
+
+ const readLimit = (role: string, window: "HOUR" | "DAY") => {
+ const value = process.env[`AI_RATE_LIMIT_${role}_PER_${window}`];
+ const num = Number(value);
+ return Number.isFinite(num) && num > 0 ? num : undefined;
+ };
+
+ const limitsByRole = roles.reduce>(
+ (acc, role) => {
+ const perHour = readLimit(role, "HOUR");
+ const perDay = readLimit(role, "DAY");
+ if (perHour || perDay) {
+ acc[role.toLowerCase()] = { perHour, perDay };
+ }
+ return acc;
+ },
+ {},
+ );
+
+ const defaultPerHour = Number(process.env.AI_RATE_LIMIT_PER_HOUR ?? "0");
+ const defaultPerDay = Number(process.env.AI_RATE_LIMIT_PER_DAY ?? "0");
+
+ const isEnabled = Boolean(
+ redisUrl &&
+ (Object.keys(limitsByRole).length > 0 ||
+ defaultPerHour > 0 ||
+ defaultPerDay > 0),
+ );
+ if (!isEnabled) return null;
+
+ limiter = new AiRateLimiter({
+ redisUrl: redisUrl!,
+ limitsByRole,
+ defaultLimits: {
+ perHour: defaultPerHour,
+ perDay: defaultPerDay,
+ },
+ });
+ return limiter;
+};
+
+// Exported for testing
+export class MemoryRateLimitStore implements RateLimitStore {
+ private store = new Map();
+
+ async increment(key: string, windowMs: number) {
+ const now = Date.now();
+ const existing = this.store.get(key);
+ if (!existing || existing.expiresAt <= now) {
+ this.store.set(key, { count: 1, expiresAt: now + windowMs });
+ return { count: 1, ttlMs: windowMs };
+ }
+ const next = { count: existing.count + 1, expiresAt: existing.expiresAt };
+ this.store.set(key, next);
+ return { count: next.count, ttlMs: next.expiresAt - now };
+ }
+}