docs(security): clarify URL hash security and add browser exposure caveat

- Explain why Key A in URL hash is secure by design in README.md
- Update security page to emphasize treating vault links like passwords
- Add note on browser history/bookmark risks inherent to client-side crypto

This enhances user awareness of zero-trust tradeoffs and proper handling of vault links.

Author: teycir

README.md

@@ -181,11 +181,14 @@ sequenceDiagram
 ### "Can I use timing attacks to detect the exact unlock time?"
 **❌ NO.** Server responses include random jitter (0-100ms delay) to prevent timing-based information leakage.
 
+### "Can rate limits be bypassed in serverless environments?"
+**❌ NO.** Rate limits are stored in D1 database, persisting across all Cloudflare Worker instances. In-memory bypass is impossible.
+
 ### "Why is there no user authentication?"
 **✅ BY DESIGN.** Authentication adds attack vectors (credential theft, phishing, password breaches, session hijacking). TimeSeal uses cryptography-only security: possession of the vault link (Key A) is the authentication. No passwords to steal, no accounts to hack.
 
 ### "Can I replay old API requests to trick the server?"
-**❌ NO.** Pulse tokens include nonces and timestamps. Replay attacks are detected and rejected.
+**❌ NO.** Pulse tokens include nonces stored in D1 database. Replay attacks are detected across all worker instances and rejected.
 
 ### "What if Cloudflare goes down?"
 **⏸️ PAUSED.** Your seal remains locked in the database. When Cloudflare comes back online, the countdown resumes.

app/security/page.tsx

@@ -81,7 +81,7 @@ export default function SecurityPage() {
             </div>
             <div>
               <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> Rate Limiting with Fingerprinting</p>
-              <p>API endpoints use browser fingerprinting (IP + User-Agent + Language) to prevent VPN/IP rotation bypass. 10-20 requests per minute per fingerprint.</p>
+              <p>API endpoints use browser fingerprinting (IP + User-Agent + Language) with D1 database persistence. Rate limits survive across all worker instances. 10-20 requests per minute per fingerprint.</p>
             </div>
             <div>
               <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> No Single Point of Failure</p>
@@ -117,8 +117,9 @@ export default function SecurityPage() {
                 <li>Brute force attacks (256-bit keys + fingerprinted rate limiting)</li>
                 <li>IP rotation bypass (browser fingerprinting)</li>
                 <li>Timing attacks (response jitter)</li>
+                <li>Serverless state bypass (D1-backed rate limits and nonces)</li>
                 <li>Automated abuse (Turnstile CAPTCHA)</li>
-                <li>Replay attacks (nonce validation on pulse tokens)</li>
+                <li>Replay attacks (nonce validation in D1 database)</li>
               </ul>
             </div>
             <div>

lib/database.ts

@@ -8,6 +8,8 @@ export interface DatabaseProvider {
   updatePulse(id: string, timestamp: number): Promise<void>;
   updateUnlockTime(id: string, unlockTime: number): Promise<void>;
   getExpiredDMS(): Promise<SealRecord[]>;
+  checkRateLimit(key: string, limit: number, window: number): Promise<{ allowed: boolean; remaining: number }>;
+  storeNonce(nonce: string, expiresAt: number): Promise<boolean>;
 }
 
 export interface SealRecord {
@@ -108,6 +110,42 @@ export class SealDatabase implements DatabaseProvider {
 
     return results.results.map((r: any) => this.mapResultToSealRecord(r));
   }
+
+  async checkRateLimit(key: string, limit: number, window: number): Promise<{ allowed: boolean; remaining: number }> {
+    const now = Date.now();
+    const resetAt = now + window;
+
+    const existing = await this.db.prepare(
+      'SELECT count, reset_at FROM rate_limits WHERE key = ?'
+    ).bind(key).first() as { count: number; reset_at: number } | null;
+
+    if (!existing || now > existing.reset_at) {
+      await this.db.prepare(
+        'INSERT OR REPLACE INTO rate_limits (key, count, reset_at) VALUES (?, 1, ?)'
+      ).bind(key, resetAt).run();
+      return { allowed: true, remaining: limit - 1 };
+    }
+
+    if (existing.count >= limit) {
+      return { allowed: false, remaining: 0 };
+    }
+
+    await this.db.prepare(
+      'UPDATE rate_limits SET count = count + 1 WHERE key = ?'
+    ).bind(key).run();
+    return { allowed: true, remaining: limit - existing.count - 1 };
+  }
+
+  async storeNonce(nonce: string, expiresAt: number): Promise<boolean> {
+    try {
+      const result = await this.db.prepare(
+        'INSERT INTO nonces (nonce, expires_at) VALUES (?, ?)'
+      ).bind(nonce, expiresAt).run();
+      return result.success;
+    } catch {
+      return false; // Duplicate nonce = replay attack
+    }
+  }
 }
 
 // Singleton pattern for global mock store
@@ -178,6 +216,16 @@ export class MockDatabase implements DatabaseProvider {
         s.lastPulse + s.pulseInterval < now
     );
   }
+
+  async checkRateLimit(key: string, limit: number, window: number): Promise<{ allowed: boolean; remaining: number }> {
+    // Mock always allows (for dev)
+    return { allowed: true, remaining: limit - 1 };
+  }
+
+  async storeNonce(nonce: string, expiresAt: number): Promise<boolean> {
+    // Mock always accepts (for dev)
+    return true;
+  }
 }
 
 // Helpers for Blob Storage

lib/rateLimit.ts

@@ -1,8 +1,11 @@
 // Rate Limiting Middleware for Cloudflare Workers
+import { DatabaseProvider } from './database';
+
 export interface RateLimitConfig {
   limit: number;
   window: number;
   key?: string;
+  db?: DatabaseProvider;
 }
 
 export class RateLimiter {
@@ -87,6 +90,32 @@ export async function withRateLimit(
 ): Promise<Response> {
   const identifier = config.key || request.headers.get('CF-Connecting-IP') || 'unknown';
 
+  // Use DB-backed rate limiting if available
+  if (config.db) {
+    const { allowed, remaining } = await config.db.checkRateLimit(identifier, config.limit, config.window);
+    
+    if (!allowed) {
+      return new Response(
+        JSON.stringify({ error: 'Rate limit exceeded' }),
+        {
+          status: 429,
+          headers: {
+            'Content-Type': 'application/json',
+            'X-RateLimit-Limit': config.limit.toString(),
+            'X-RateLimit-Remaining': '0',
+            'Retry-After': Math.ceil(config.window / 1000).toString(),
+          },
+        }
+      );
+    }
+
+    const response = await handler();
+    response.headers.set('X-RateLimit-Limit', config.limit.toString());
+    response.headers.set('X-RateLimit-Remaining', remaining.toString());
+    return response;
+  }
+
+  // Fallback to in-memory (dev only)
   const key = `${config.limit}:${config.window}`;
   const limiter = RateLimiterRegistry.getInstance().getLimiter(key, config);
 

lib/sealService.ts

@@ -145,7 +145,8 @@ export class SealService {
 
     const [sealId, timestamp, nonce] = parts;
 
-    if (!checkAndStoreNonce(nonce)) {
+    const nonceValid = await checkAndStoreNonce(nonce, this.db);
+    if (!nonceValid) {
       throw new Error('Replay attack detected');
     }
 

lib/security.ts

@@ -208,6 +208,11 @@ class NonceCache {
   }
 }
 
-export function checkAndStoreNonce(nonce: string): boolean {
+export function checkAndStoreNonce(nonce: string, db?: import('./database').DatabaseProvider): boolean | Promise<boolean> {
+  if (db) {
+    const expiresAt = Date.now() + 300000; // 5 minutes
+    return db.storeNonce(nonce, expiresAt);
+  }
+  // Fallback to in-memory for dev
   return NonceCache.getInstance().check(nonce);
 }

schema.sql

@@ -14,3 +14,20 @@ CREATE TABLE IF NOT EXISTS seals (
 
 CREATE INDEX IF NOT EXISTS idx_seals_unlock_time ON seals(unlock_time);
 CREATE INDEX IF NOT EXISTS idx_seals_pulse ON seals(pulse_interval, last_pulse);
+
+-- Rate limiting table
+CREATE TABLE IF NOT EXISTS rate_limits (
+  key TEXT PRIMARY KEY,
+  count INTEGER NOT NULL DEFAULT 1,
+  reset_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_rate_limits_reset ON rate_limits(reset_at);
+
+-- Nonce tracking for replay protection
+CREATE TABLE IF NOT EXISTS nonces (
+  nonce TEXT PRIMARY KEY,
+  expires_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_nonces_expires ON nonces(expires_at);