@edge-base/server 0.2.9 → 0.3.1

package/src/lib/email-provider.ts

@@ -4,7 +4,7 @@
  * Workers cannot use SMTP directly. Instead, we use HTTP REST API-based
  * external email services via a common interface.
  *
- * Supported: Resend (default), SendGrid, Mailgun, AWS SES
+ * Supported: Resend (default), SendGrid, Mailgun, AWS SES, Cloudflare Email Service
  */
 
 // ─── Interface ───
@@ -26,6 +26,24 @@ export interface EmailProvider {
 
 interface EmailProviderEnv {
   EDGEBASE_EMAIL_API_URL?: string;
+  EDGEBASE_EMAIL_CLOUDFLARE_API_TOKEN?: string;
+  EDGEBASE_EMAIL_CLOUDFLARE_ACCOUNT_ID?: string;
+  EDGEBASE_EMAIL_CLOUDFLARE_BINDING?: string;
+  EMAIL?: CloudflareSendEmailBinding;
+}
+
+interface CloudflareSendEmailBinding {
+  send(message: {
+    to: string;
+    from: string;
+    subject: string;
+    html?: string;
+    text?: string;
+  }): Promise<{ messageId?: string }>;
+}
+
+function isCloudflareSendEmailBinding(value: unknown): value is CloudflareSendEmailBinding {
+  return !!value && typeof value === 'object' && typeof (value as { send?: unknown }).send === 'function';
 }
 
 const encoder = new TextEncoder();
@@ -331,14 +349,83 @@ export class SESProvider implements EmailProvider {
   }
 }
 
+// ─── Cloudflare Email Service Provider ───
+
+export class CloudflareEmailProvider implements EmailProvider {
+  private apiBaseUrl: string;
+
+  constructor(
+    private options: {
+      from: string;
+      apiKey?: string;
+      accountId?: string;
+      binding?: CloudflareSendEmailBinding;
+      apiBaseUrl?: string;
+    },
+  ) {
+    this.apiBaseUrl = options.apiBaseUrl?.replace(/\/$/, '') ?? 'https://api.cloudflare.com/client/v4';
+  }
+
+  async send(options: EmailSendOptions): Promise<EmailSendResult> {
+    if (this.options.binding) {
+      try {
+        const result = await this.options.binding.send({
+          to: options.to,
+          from: this.options.from,
+          subject: options.subject,
+          html: options.html,
+        });
+        return { success: true, messageId: result.messageId };
+      } catch (err) {
+        console.error('[EmailProvider:Cloudflare] Workers binding failed:', err);
+        return { success: false };
+      }
+    }
+
+    if (!this.options.apiKey || !this.options.accountId) {
+      console.error(
+        '[EmailProvider:Cloudflare] accountId and apiKey are required when a Workers send_email binding is not available.',
+      );
+      return { success: false };
+    }
+
+    const resp = await fetch(
+      `${this.apiBaseUrl}/accounts/${encodeURIComponent(this.options.accountId)}/email/sending/send`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.options.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          to: options.to,
+          from: this.options.from,
+          subject: options.subject,
+          html: options.html,
+        }),
+      },
+    );
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.error('[EmailProvider:Cloudflare] Failed:', resp.status, text);
+      return { success: false };
+    }
+
+    return { success: true };
+  }
+}
+
 // ─── Factory ───
 
 export interface EmailConfig {
-  provider: 'resend' | 'sendgrid' | 'mailgun' | 'ses';
-  apiKey: string;    // SES uses accessKeyId:secretAccessKey[:sessionToken]
+  provider: 'resend' | 'sendgrid' | 'mailgun' | 'ses' | 'cloudflare';
+  apiKey?: string;    // SES uses accessKeyId:secretAccessKey[:sessionToken]
   from: string;
   domain?: string;    // Mailgun domain
   region?: string;    // SES region
+  accountId?: string; // Cloudflare REST API account ID
+  binding?: string;   // Cloudflare Workers send_email binding name
 }
 
 /**
@@ -358,22 +445,45 @@ export function createEmailProvider(
     return null;
   }
 
-  if (!config.apiKey || !config.from) {
-    console.warn('[EmailProvider] apiKey and from are required. Email features disabled.');
+  if (!config.from) {
+    console.warn('[EmailProvider] from is required. Email features disabled.');
     return null;
   }
 
   switch (config.provider) {
+    case 'cloudflare': {
+      const bindingName = config.binding
+        ?? env?.EDGEBASE_EMAIL_CLOUDFLARE_BINDING?.trim()
+        ?? 'EMAIL';
+      const envRecord = env as Record<string, unknown> | undefined;
+      const bindingCandidate = envRecord?.[bindingName];
+      const binding = isCloudflareSendEmailBinding(bindingCandidate)
+        ? bindingCandidate
+        : undefined;
+      return new CloudflareEmailProvider({
+        from: config.from,
+        apiKey: config.apiKey ?? env?.EDGEBASE_EMAIL_CLOUDFLARE_API_TOKEN,
+        accountId: config.accountId ?? env?.EDGEBASE_EMAIL_CLOUDFLARE_ACCOUNT_ID,
+        binding,
+      });
+    }
     case 'resend':
+      if (!config.apiKey) break;
       return new ResendProvider(config.apiKey, config.from);
     case 'sendgrid':
+      if (!config.apiKey) break;
       return new SendGridProvider(config.apiKey, config.from);
     case 'mailgun':
+      if (!config.apiKey) break;
       return new MailgunProvider(config.apiKey, config.from, config.domain);
     case 'ses':
+      if (!config.apiKey) break;
       return new SESProvider(config.apiKey, config.from, config.region);
     default:
       console.warn(`[EmailProvider] Unknown provider: ${config.provider}. Email features disabled.`);
       return null;
   }
+
+  console.warn('[EmailProvider] apiKey and from are required. Email features disabled.');
+  return null;
 }

package/src/lib/functions.ts

@@ -41,6 +41,7 @@ import { generateId } from './uuid.js';
 import { DbRef, TableRef, DefaultDbApi, HttpClient, ContextManager } from '@edge-base/core';
 import { InternalHttpTransport } from './internal-transport.js';
 import { executeProviderAwareSql } from './provider-aware-sql.js';
+import { createEmailProvider } from './email-provider.js';
 
 // ─── Function Context Types ───
 
@@ -69,6 +70,15 @@ export interface AdminAuthContext {
   revokeAllSessions(userId: string): Promise<void>;
 }
 
+export interface FunctionEmailProxy {
+  send(options: {
+    to: string;
+    subject: string;
+    html?: string;
+    text?: string;
+  }): Promise<{ success: boolean; messageId?: string }>;
+}
+
 /**
  * AdminEdgeBase-shaped context object injected as context.admin.
  *
@@ -186,6 +196,8 @@ export interface FunctionPushProxy {
 
 /** Storage proxy for App Functions — wraps R2Bucket with convenience methods. */
 export interface FunctionStorageProxy {
+  /** Return a proxy scoped to a named storage bucket. */
+  bucket(bucket: string): FunctionStorageProxy;
   put(
     key: string,
     value: ReadableStream | ArrayBuffer | string,
@@ -199,6 +211,10 @@ export interface FunctionStorageProxy {
   } | null>;
   delete(key: string): Promise<void>;
   getSignedUrl(key: string, options?: { expiresIn?: number }): Promise<string>;
+  getSignedUploadUrl(
+    key: string,
+    options?: { expiresIn?: number; maxBytes?: number | null },
+  ): Promise<{ url: string; expiresAt: string; maxBytes: number | null }>;
   list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{
     keys: Array<{ key: string; size: number; contentType: string }>;
     cursor?: string;
@@ -357,12 +373,29 @@ export interface FunctionContext {
   data?: { before?: Record<string, unknown>; after?: Record<string, unknown> };
   before?: Record<string, unknown>;
   after?: Record<string, unknown>;
+  /** Configured server-side email sender, when an EdgeBase email provider is available. */
+  email?: FunctionEmailProxy;
+  /** Environment variables, secrets, and bindings available to the Worker. */
+  env?: Record<string, unknown>;
   storage?: FunctionStorageProxy; // Available when R2 binding present
   analytics?: unknown; // AnalyticsAdapter when ANALYTICS_APP binding present
   /** Plugin-specific config from edgebase.config.ts plugins section. */
   pluginConfig?: Record<string, unknown>;
 }
 
+function escapeEmailHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function textEmailToHtml(text: string): string {
+  return `<pre style="font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; white-space: pre-wrap;">${escapeEmailHtml(text)}</pre>`;
+}
+
 // ─── Function Registry ───
 
 /**
@@ -693,6 +726,19 @@ export function wrapMethodExport(
   method: string,
   runtimeTrigger?: { path?: string },
 ): FunctionDefinition {
+  if (
+    method === '*' &&
+    handler &&
+    typeof handler === 'object' &&
+    'handler' in handler &&
+    'trigger' in handler &&
+    handler.trigger &&
+    typeof handler.trigger === 'object' &&
+    'type' in handler.trigger
+  ) {
+    return handler as FunctionDefinition;
+  }
+
   // handler can be: raw function, or { handler, captcha? } from defineFunction()
   let fn: (ctx: unknown) => Promise<unknown>;
   let captcha: boolean | undefined;
@@ -1096,6 +1142,19 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
     executionCtx: options.executionCtx,
     preferDirectDo: options.preferDirectDoDb,
   });
+  const emailProvider = createEmailProvider(options.config.email, options.env);
+  const email: FunctionEmailProxy | undefined = emailProvider
+    ? {
+        async send(message) {
+          const to = message.to.trim();
+          const subject = message.subject.trim();
+          if (!to) throw new Error('email.send() requires a recipient.');
+          if (!subject) throw new Error('email.send() requires a subject.');
+          const html = message.html ?? textEmailToHtml(message.text ?? '');
+          return emailProvider.send({ to, subject, html });
+        },
+      }
+    : undefined;
   const sqlProviderAware = (
     namespace: string,
     id: string | undefined,
@@ -1282,6 +1341,8 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
     auth: options.auth,
     db: admin.db,
     admin,
+    ...(options.env ? { env: options.env as unknown as Record<string, unknown> } : {}),
+    ...(email ? { email } : {}),
     params: options.params ?? {},
   };
 
@@ -1826,6 +1887,10 @@ export function buildFunctionStorageProxy(
   const prefix = (key: string) => `${bucket}/${key}`;
 
   return {
+    bucket(name) {
+      return buildFunctionStorageProxy(r2, name, env, workerUrl);
+    },
+
     async put(key, value, options) {
       const httpMeta: R2PutOptions = {};
       if (options?.contentType) httpMeta.httpMetadata = { contentType: options.contentType };
@@ -1853,11 +1918,36 @@ export function buildFunctionStorageProxy(
       if (!secret) throw new Error('Signed URLs require JWT_USER_SECRET to be configured.');
       const expiresIn = options?.expiresIn ?? 3600;
       const expiresAt = Date.now() + expiresIn * 1000;
-      const token = await createSignedToken(key, bucket, expiresAt, secret);
+      const obj = await r2.head(prefix(key));
+      const token = await createSignedToken(key, bucket, expiresAt, secret, obj ? {
+        file: {
+          size: obj.size,
+          contentType: obj.httpMetadata?.contentType || 'application/octet-stream',
+          etag: obj.etag,
+          uploadedAt: obj.uploaded?.toISOString(),
+        },
+      } : undefined);
       const base = workerUrl ?? 'http://localhost:8787';
       return `${base}/api/storage/${encodeURIComponent(bucket)}/${key}?token=${token}`;
     },
 
+    async getSignedUploadUrl(key, options) {
+      const secret = (env as unknown as Record<string, string>).JWT_USER_SECRET;
+      if (!secret) throw new Error('Signed upload URLs require JWT_USER_SECRET to be configured.');
+      const expiresIn = options?.expiresIn ?? 1800;
+      const expiresAt = Date.now() + expiresIn * 1000;
+      const maxBytes = typeof options?.maxBytes === 'number' && Number.isFinite(options.maxBytes)
+        ? Math.max(0, Math.trunc(options.maxBytes))
+        : null;
+      const token = await createSignedToken(key, bucket, expiresAt, secret, maxBytes);
+      const base = workerUrl ?? 'http://localhost:8787';
+      return {
+        url: `${base}/api/storage/${encodeURIComponent(bucket)}/upload?token=${token}&key=${encodeURIComponent(key)}`,
+        expiresAt: new Date(expiresAt).toISOString(),
+        maxBytes,
+      };
+    },
+
     async list(options) {
       const r2Options: R2ListOptions = {};
       if (options?.prefix) r2Options.prefix = prefix(options.prefix);

package/src/lib/internal-transport.ts

@@ -11,6 +11,7 @@ import type { EdgeBaseConfig } from '@edge-base/shared';
 import {
   callDO,
   formatDbTargetValidationIssue,
+  getD1BindingName,
   getDbDoName,
   resolveDbTarget,
   shouldRouteToD1,
@@ -94,6 +95,12 @@ function parsePath(
   return { namespace, instanceId, tableName, directPath };
 }
 
+function hasD1Binding(env: Env | undefined, namespace: string): boolean {
+  if (!env) return false;
+  const bindingName = getD1BindingName(namespace);
+  return Boolean((env as unknown as Record<string, unknown>)[bindingName]);
+}
+
 export class InternalHttpTransport implements HttpTransport {
   private readonly databaseNamespace: DurableObjectNamespace;
   private readonly config: EdgeBaseConfig;
@@ -196,7 +203,14 @@ export class InternalHttpTransport implements HttpTransport {
     const httpMethod = method === 'PUT' ? 'PATCH' : method; // normalize PUT → PATCH
 
     // 1. D1 route
-    if (!this.preferDirectDo && !dynamic && shouldRouteToD1(namespace, this.config) && this.env) {
+    const shouldUseD1 =
+      !this.preferDirectDo
+      && !dynamic
+      && shouldRouteToD1(namespace, this.config)
+      && this.env
+      && (provider === 'd1' || hasD1Binding(this.env, namespace));
+
+    if (shouldUseD1) {
       return this.requestViaD1Handler(httpMethod, namespace, normalizedInstanceId, tableName, directPath, headers, query, body);
     }
 

package/src/lib/jwt.ts

@@ -22,6 +22,7 @@ export interface RefreshTokenPayload {
   sub: string;          // userId
   type: 'refresh';
   jti?: string;         // unique session ID for token uniqueness
+  nonce?: string;       // per-token randomness while preserving session jti
 }
 
 export interface AdminTokenPayload {
@@ -106,6 +107,7 @@ export async function signRefreshToken(
 ): Promise<string> {
   const builder = new SignJWT({
     type: 'refresh',
+    nonce: payload.nonce ?? crypto.randomUUID(),
   })
     .setProtectedHeader({ alg: ALGORITHM })
     .setIssuedAt()

package/src/routes/admin.ts

@@ -1539,7 +1539,14 @@ api.openapi(adminCreateSignedUrl, async (c) => {
 
   const expiresInMs = parseDuration(body.expiresIn || '1h');
   const expiresAt = Date.now() + expiresInMs;
-  const token = await createSignedToken(body.key, bucketName, expiresAt, secret);
+  const token = await createSignedToken(body.key, bucketName, expiresAt, secret, {
+    file: {
+      size: obj.size,
+      contentType: obj.httpMetadata?.contentType || 'application/octet-stream',
+      etag: obj.etag,
+      uploadedAt: obj.uploaded?.toISOString(),
+    },
+  });
 
   // Build signed URL using the public storage endpoint
   const url = new URL(c.req.url);

package/src/routes/auth.ts

@@ -27,6 +27,7 @@ import {
   buildEmailActionUrl,
   parseClientRedirectInput,
 } from '../lib/auth-redirect.js';
+import { hashOtpSecret, verifyOtpSecret } from '../lib/auth-token.js';
 import {
   signAccessToken, signRefreshToken, verifyRefreshTokenWithFallback,
   parseDuration, TokenExpiredError,
@@ -176,7 +177,7 @@ function getMaxActiveSessions(env: Env): number {
 }
 
 function isEmailProviderName(value: unknown): value is EmailConfig['provider'] {
-  return value === 'resend' || value === 'sendgrid' || value === 'mailgun' || value === 'ses';
+  return value === 'resend' || value === 'sendgrid' || value === 'mailgun' || value === 'ses' || value === 'cloudflare';
 }
 
 function getEmailConfig(env: Env): EmailConfig | undefined {
@@ -187,22 +188,29 @@ function getEmailConfig(env: Env): EmailConfig | undefined {
   const provider = configured?.provider
     ?? (isEmailProviderName(runtimeEnv.EDGEBASE_EMAIL_PROVIDER) ? runtimeEnv.EDGEBASE_EMAIL_PROVIDER : undefined);
   const apiKey = configured?.apiKey
-    ?? (typeof runtimeEnv.EDGEBASE_EMAIL_API_KEY === 'string' ? runtimeEnv.EDGEBASE_EMAIL_API_KEY : undefined);
+    ?? (typeof runtimeEnv.EDGEBASE_EMAIL_API_KEY === 'string' ? runtimeEnv.EDGEBASE_EMAIL_API_KEY : undefined)
+    ?? (typeof runtimeEnv.EDGEBASE_EMAIL_CLOUDFLARE_API_TOKEN === 'string' ? runtimeEnv.EDGEBASE_EMAIL_CLOUDFLARE_API_TOKEN : undefined);
   const from = configured?.from
     ?? (typeof runtimeEnv.EDGEBASE_EMAIL_FROM === 'string' ? runtimeEnv.EDGEBASE_EMAIL_FROM : undefined);
+  const cloudflareAccountId = configured?.accountId
+    ?? (typeof runtimeEnv.EDGEBASE_EMAIL_CLOUDFLARE_ACCOUNT_ID === 'string' ? runtimeEnv.EDGEBASE_EMAIL_CLOUDFLARE_ACCOUNT_ID : undefined);
+  const cloudflareBinding = configured?.binding
+    ?? (typeof runtimeEnv.EDGEBASE_EMAIL_CLOUDFLARE_BINDING === 'string' ? runtimeEnv.EDGEBASE_EMAIL_CLOUDFLARE_BINDING : undefined);
 
-  if (!provider || !apiKey || !from) {
+  if (!provider || !from || (provider !== 'cloudflare' && !apiKey)) {
     return configured;
   }
 
   return {
     provider,
-    apiKey,
     from,
+    ...(apiKey ? { apiKey } : {}),
     domain: configured?.domain
       ?? (typeof runtimeEnv.EDGEBASE_EMAIL_MAILGUN_DOMAIN === 'string' ? runtimeEnv.EDGEBASE_EMAIL_MAILGUN_DOMAIN : undefined),
     region: configured?.region
       ?? (typeof runtimeEnv.EDGEBASE_EMAIL_SES_REGION === 'string' ? runtimeEnv.EDGEBASE_EMAIL_SES_REGION : undefined),
+    accountId: cloudflareAccountId,
+    binding: cloudflareBinding,
     appName: configured?.appName ?? 'EdgeBase Local Auth Harness',
     defaultLocale: configured?.defaultLocale,
     verifyUrl: configured?.verifyUrl
@@ -539,7 +547,7 @@ async function rotateRefreshTokenFlow(
   }
 
   const newRefreshToken = await signRefreshToken(
-    { sub: userId, type: 'refresh', jti: generateId() },
+    { sub: userId, type: 'refresh', jti: session.id as string },
     getUserSecret(env),
     getRefreshTokenTTL(env),
   );
@@ -781,7 +789,11 @@ async function sendMailWithHook(
     }
   }
 
-  return provider.send({ to, subject: finalSubject, html: finalHtml });
+  const result = await provider.send({ to, subject: finalSubject, html: finalHtml });
+  if (!result.success) {
+    throw new EdgeBaseError(502, 'Email delivery failed.', undefined, 'email-delivery-failed');
+  }
+  return result;
 }
 
 async function sendSmsWithHook(
@@ -1452,7 +1464,7 @@ authRoute.openapi(signinMagicLink, async (c) => {
         await sendMailWithHook(
           c.env, c.executionCtx, provider, 'magicLink', body.email,
           resolveSubject(c.env, 'magicLink', defaultSubject, locale), html, locale,
-        ).catch(() => {});
+        );
       } else {
         if (!isReleaseMode(c.env)) {
           debugToken = token;
@@ -1627,10 +1639,12 @@ authRoute.openapi(signinPhone, async (c) => {
     const code = generateOTP();
     if (exposeTestSecrets) devCode = code;
 
+    const codeHash = await hashOtpSecret(code, getUserSecret(c.env));
+
     // Store OTP in KV with 5 min TTL
     await c.env.KV.put(
       `phone-otp:${phone}`,
-      JSON.stringify({ code, userId, attempts: 0 }),
+      JSON.stringify({ codeHash, userId, attempts: 0 }),
       { expirationTtl: 300 },
     );
 
@@ -1679,10 +1693,12 @@ authRoute.openapi(signinPhone, async (c) => {
       const code = generateOTP();
       if (exposeTestSecrets) devCode = code;
 
+      const codeHash = await hashOtpSecret(code, getUserSecret(c.env));
+
       // Store OTP in KV
       await c.env.KV.put(
         `phone-otp:${phone}`,
-        JSON.stringify({ code, userId, attempts: 0 }),
+        JSON.stringify({ codeHash, userId, attempts: 0 }),
         { expirationTtl: 300 },
       );
 
@@ -1756,7 +1772,7 @@ authRoute.openapi(verifyPhone, async (c) => {
 
   // Look up phone → userId via KV OTP data
   const otpData = await c.env.KV.get(`phone-otp:${phone}`, 'json') as {
-    code: string; userId: string; attempts: number;
+    codeHash?: string; code?: string; userId: string; attempts: number;
   } | null;
 
   if (!otpData) {
@@ -1769,8 +1785,11 @@ authRoute.openapi(verifyPhone, async (c) => {
     throw new EdgeBaseError(429, 'Too many failed OTP attempts. Please request a new code.', undefined, 'rate-limited');
   }
 
-  // Verify code (timing-safe comparison)
-  if (!timingSafeEqual(otpData.code, body.code)) {
+  const submittedCode = body.code.trim();
+  const otpMatches = otpData.codeHash
+    ? await verifyOtpSecret(submittedCode, otpData.codeHash, getUserSecret(c.env))
+    : timingSafeEqual(otpData.code ?? '', submittedCode);
+  if (!otpMatches) {
     await c.env.KV.put(
       `phone-otp:${phone}`,
       JSON.stringify({ ...otpData, attempts: otpData.attempts + 1 }),
@@ -1895,10 +1914,12 @@ authRoute.openapi(linkPhone, async (c) => {
   const code = generateOTP();
   const exposeTestSecrets = shouldExposeAuthTestSecrets(c.env);
 
+  const codeHash = await hashOtpSecret(code, getUserSecret(c.env));
+
   // Store link OTP in KV (separate key pattern)
   await c.env.KV.put(
     `phone-link-otp:${phone}`,
-    JSON.stringify({ code, userId, attempts: 0 }),
+    JSON.stringify({ codeHash, userId, attempts: 0 }),
     { expirationTtl: 300 },
   );
 
@@ -1964,7 +1985,7 @@ authRoute.openapi(verifyLinkPhone, async (c) => {
 
   // Verify OTP from KV
   const otpData = await c.env.KV.get(`phone-link-otp:${phone}`, 'json') as {
-    code: string; userId: string; attempts: number;
+    codeHash?: string; code?: string; userId: string; attempts: number;
   } | null;
 
   if (!otpData) {
@@ -1980,7 +2001,11 @@ authRoute.openapi(verifyLinkPhone, async (c) => {
     throw new EdgeBaseError(429, 'Too many failed OTP attempts. Please request a new code.', undefined, 'rate-limited');
   }
 
-  if (!timingSafeEqual(otpData.code, body.code)) {
+  const submittedCode = body.code.trim();
+  const otpMatches = otpData.codeHash
+    ? await verifyOtpSecret(submittedCode, otpData.codeHash, getUserSecret(c.env))
+    : timingSafeEqual(otpData.code ?? '', submittedCode);
+  if (!otpMatches) {
     await c.env.KV.put(
       `phone-link-otp:${phone}`,
       JSON.stringify({ ...otpData, attempts: otpData.attempts + 1 }),
@@ -2083,11 +2108,12 @@ authRoute.openapi(signinEmailOtp, async (c) => {
 
     const code = generateOTP();
     if (exposeTestSecrets) devCode = code;
+    const codeHash = await hashOtpSecret(code, getUserSecret(c.env));
 
     // Store OTP in KV with 5 min TTL
     await c.env.KV.put(
       `email-otp:${email}`,
-      JSON.stringify({ code, userId, attempts: 0 }),
+      JSON.stringify({ codeHash, userId, attempts: 0 }),
       { expirationTtl: 300 },
     );
 
@@ -2141,11 +2167,12 @@ authRoute.openapi(signinEmailOtp, async (c) => {
 
       const code = generateOTP();
       if (exposeTestSecrets) devCode = code;
+      const codeHash = await hashOtpSecret(code, getUserSecret(c.env));
 
       // Store OTP in KV
       await c.env.KV.put(
         `email-otp:${email}`,
-        JSON.stringify({ code, userId, attempts: 0 }),
+        JSON.stringify({ codeHash, userId, attempts: 0 }),
         { expirationTtl: 300 },
       );
 
@@ -2218,7 +2245,7 @@ authRoute.openapi(verifyEmailOtp, async (c) => {
 
   // Look up OTP data from KV
   const otpData = await c.env.KV.get(`email-otp:${email}`, 'json') as {
-    code: string; userId: string; attempts: number;
+    codeHash?: string; code?: string; userId: string; attempts: number;
   } | null;
 
   if (!otpData) {
@@ -2230,7 +2257,11 @@ authRoute.openapi(verifyEmailOtp, async (c) => {
     throw new EdgeBaseError(429, 'Too many failed OTP attempts. Please request a new code.', undefined, 'rate-limited');
   }
 
-  if (!timingSafeEqual(otpData.code, body.code)) {
+  const submittedCode = body.code.trim();
+  const otpMatches = otpData.codeHash
+    ? await verifyOtpSecret(submittedCode, otpData.codeHash, getUserSecret(c.env))
+    : timingSafeEqual(otpData.code ?? '', submittedCode);
+  if (!otpMatches) {
     await c.env.KV.put(
       `email-otp:${email}`,
       JSON.stringify({ ...otpData, attempts: otpData.attempts + 1 }),
@@ -2577,6 +2608,67 @@ authRoute.openapi(mfaRecovery, async (c) => {
   });
 });
 
+// POST /mfa/recovery-codes — regenerate recovery codes (authenticated)
+const mfaRecoveryCodesRegenerate = createRoute({
+  operationId: 'authMfaRecoveryCodesRegenerate',
+  method: 'post',
+  path: '/mfa/recovery-codes',
+  tags: ['client'],
+  summary: 'Regenerate MFA recovery codes',
+  request: {
+    body: { content: { 'application/json': { schema: z.object({
+      password: z.string().optional(),
+      code: z.string().optional(),
+    }).passthrough() } }, required: false },
+  },
+  responses: {
+    200: { description: 'Success', content: { 'application/json': { schema: jsonResponseSchema } } },
+    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
+    401: { description: 'Authentication required or verification failed', content: { 'application/json': { schema: errorResponseSchema } } },
+  },
+});
+
+authRoute.openapi(mfaRecoveryCodesRegenerate, async (c) => {
+  const userId = requireAuth(c.get('auth'));
+  const bodyText = await c.req.text();
+  let body: { password?: string; code?: string } = {};
+  try { body = bodyText ? JSON.parse(bodyText) : {}; } catch { throw new EdgeBaseError(400, 'Invalid JSON.', undefined, 'invalid-json'); }
+  await ensureAuthActionAllowed(c, 'mfaRecoveryCodesRegenerate', {
+    userId,
+    passwordProvided: !!body.password,
+    codeProvided: !!body.code,
+  });
+  const db = getAuthDb(c);
+
+  const user = await authService.getUserById(db, userId);
+  if (!user) throw new EdgeBaseError(404, 'User not found.', undefined, 'user-not-found');
+  const factor = await authService.getMfaFactorByUser(db, userId, 'totp');
+  if (!factor || !factor.verified) {
+    throw new EdgeBaseError(400, 'No verified TOTP factor found.', undefined, 'invalid-input');
+  }
+
+  if (body.password) {
+    if (!user.passwordHash) throw new EdgeBaseError(400, 'This account has no password set.', undefined, 'invalid-input');
+    const valid = await verifyPassword(body.password, user.passwordHash as string);
+    if (!valid) throw new EdgeBaseError(401, 'Invalid password.', undefined, 'invalid-password');
+  } else if (body.code) {
+    const secret = await decryptSecret(factor.secret as string, getUserSecret(c.env));
+    const valid = await verifyTOTP(secret, body.code);
+    if (!valid) throw new EdgeBaseError(401, 'Invalid TOTP code.', undefined, 'invalid-totp');
+  } else {
+    throw new EdgeBaseError(400, 'Either password or TOTP code is required to regenerate recovery codes.', undefined, 'invalid-input');
+  }
+
+  const recoveryCodes = generateRecoveryCodes(8);
+  const hashedCodes: { id: string; codeHash: string }[] = [];
+  for (const code of recoveryCodes) {
+    hashedCodes.push({ id: generateId(), codeHash: await hashRecoveryCode(code) });
+  }
+  await authService.replaceRecoveryCodes(db, userId, hashedCodes);
+
+  return c.json({ recoveryCodes });
+});
+
 // DELETE /mfa/totp — disable TOTP (authenticated)
 const mfaTotpDelete = createRoute({
   operationId: 'authMfaTotpDelete',