fix: kv ttl min 60sec

README.md

@@ -225,6 +225,19 @@ function createAuth(env?: CloudflareBindings, cf?: IncomingRequestCfProperties)
                 },
                 rateLimit: {
                     enabled: true,
+                    window: 60, // Minimum KV TTL is 60s
+                    max: 100, // reqs/window
+                    customRules: {
+                        // https://github.com/better-auth/better-auth/issues/5452
+                        "/sign-in/email": {
+                            window: 60,
+                            max: 100,
+                        },
+                        "/sign-in/social": {
+                            window: 60,
+                            max: 100,
+                        },
+                    },
                 },
             }
         ),
@@ -341,6 +354,31 @@ If you provide a KV namespace in the `withCloudflare` configuration (as shown in
 
 Ensure your KV namespace (e.g., `USER_SESSIONS`) is correctly bound in your `wrangler.toml` file.
 
+#### Important: KV TTL Limitation
+
+Cloudflare KV has a minimum TTL (Time To Live) requirement of **60 seconds**. If you're using KV for secondary storage with rate limiting enabled, you **must** configure your rate limit windows to be at least 60 seconds to prevent crashes:
+
+```typescript
+rateLimit: {
+    enabled: true,
+    window: 60, // Minimum KV TTL is 60s
+    max: 100, // reqs/window
+    customRules: {
+        // https://github.com/better-auth/better-auth/issues/5452
+        "/sign-in/email": {
+            window: 60,
+            max: 100,
+        },
+        "/sign-in/social": {
+            window: 60,
+            max: 100,
+        },
+    },
+},
+```
+
+The library automatically enforces this minimum and will log a warning if a TTL less than 60 seconds is attempted, but it's better to configure your rate limits correctly from the start.
+
 ### 6. Set Up API Routes
 
 Create API routes to handle authentication requests. Better Auth provides a handler that can be used for various HTTP methods.

examples/hono/README.md

@@ -195,8 +195,20 @@ function createAuth(env?: CloudflareBindings, cf?: IncomingRequestCfProperties)
             {
                 plugins: [anonymous()], // Enable anonymous authentication
                 rateLimit: {
-                    // Enable rate limiting
                     enabled: true,
+                    window: 60, // Minimum KV TTL is 60s
+                    max: 100, // reqs/window
+                    customRules: {
+                        // https://github.com/better-auth/better-auth/issues/5452
+                        "/sign-in/email": {
+                            window: 60,
+                            max: 100,
+                        },
+                        "/sign-in/social": {
+                            window: 60,
+                            max: 100,
+                        },
+                    },
                 },
             }
         ),

examples/hono/src/auth/index.ts

@@ -36,6 +36,19 @@ function createAuth(env?: CloudflareBindings, cf?: IncomingRequestCfProperties)
                 plugins: [anonymous()],
                 rateLimit: {
                     enabled: true,
+                    window: 60, // Minimum KV TTL is 60s
+                    max: 100, // reqs/window
+                    customRules: {
+                        // https://github.com/better-auth/better-auth/issues/5452
+                        "/sign-in/email": {
+                            window: 60,
+                            max: 100,
+                        },
+                        "/sign-in/social": {
+                            window: 60,
+                            max: 100,
+                        },
+                    },
                 },
             }
         ),

examples/opennextjs/README.md

@@ -105,6 +105,19 @@ async function authBuilder() {
                 },
                 rateLimit: {
                     enabled: true,
+                    window: 60, // Minimum KV TTL is 60s
+                    max: 100, // reqs/window
+                    customRules: {
+                        // https://github.com/better-auth/better-auth/issues/5452
+                        "/sign-in/email": {
+                            window: 60,
+                            max: 100,
+                        },
+                        "/sign-in/social": {
+                            window: 60,
+                            max: 100,
+                        },
+                    },
                 },
                 plugins: [openAPI()],
             }

examples/opennextjs/src/auth/index.ts

@@ -71,7 +71,19 @@ async function authBuilder() {
             {
                 rateLimit: {
                     enabled: true,
-                    // ... other rate limiting options
+                    window: 60, // Minimum KV TTL is 60s
+                    max: 100, // reqs/window
+                    customRules: {
+                        // https://github.com/better-auth/better-auth/issues/5452
+                        "/sign-in/email": {
+                            window: 60,
+                            max: 100,
+                        },
+                        "/sign-in/social": {
+                            window: 60,
+                            max: 100,
+                        },
+                    },
                 },
                 plugins: [openAPI(), anonymous()],
                 // ... other Better Auth options

src/index.ts

@@ -1,5 +1,6 @@
 import type { KVNamespace } from "@cloudflare/workers-types";
-import { type BetterAuthOptions, type BetterAuthPlugin, type SecondaryStorage, type Session } from "better-auth";
+import { type BetterAuthOptions, type BetterAuthPlugin, type Session } from "better-auth";
+import { type SecondaryStorage } from "better-auth/db";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { createAuthEndpoint, getSessionFromCtx } from "better-auth/api";
 import { schema } from "./schema";
@@ -122,7 +123,16 @@ export const createKVStorage = (kv: KVNamespace<string>): SecondaryStorage => {
             return kv.get(key);
         },
         set: async (key: string, value: string, ttl?: number) => {
-            return kv.put(key, value, ttl ? { expirationTtl: ttl } : undefined);
+            if (ttl !== undefined) {
+                // Cloudflare KV requires TTL >= 60 seconds
+                const minTtl = 60;
+                if (ttl < minTtl) {
+                    console.warn(`[BetterAuthCloudflare] TTL ${ttl}s is less than KV minimum of ${minTtl}s. Using ${minTtl}s instead.`);
+                    ttl = minTtl;
+                }
+                return kv.put(key, value, { expirationTtl: ttl });
+            }
+            return kv.put(key, value);
         },
         delete: async (key: string) => {
             return kv.delete(key);

src/schema.ts

@@ -1,4 +1,4 @@
-import type { AuthPluginSchema } from "better-auth";
+import type { AuthPluginSchema } from "better-auth/db";
 import type { FieldAttribute } from "better-auth/db";
 import type { CloudflarePluginOptions } from "./types";