@edge-base/server 0.1.1

package/src/lib/email-provider.ts

@@ -0,0 +1,379 @@
+/**
+ * EmailProvider — Adapter pattern for external email services
+ *
+ * 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
+ */
+
+// ─── Interface ───
+
+export interface EmailSendOptions {
+  to: string;
+  subject: string;
+  html: string;
+}
+
+export interface EmailSendResult {
+  success: boolean;
+  messageId?: string;
+}
+
+export interface EmailProvider {
+  send(options: EmailSendOptions): Promise<EmailSendResult>;
+}
+
+interface EmailProviderEnv {
+  EDGEBASE_EMAIL_API_URL?: string;
+}
+
+const encoder = new TextEncoder();
+
+function toUint8Array(value: ArrayBuffer | Uint8Array): Uint8Array {
+  return value instanceof Uint8Array ? value : new Uint8Array(value);
+}
+
+function toArrayBuffer(value: Uint8Array): ArrayBuffer {
+  return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) as ArrayBuffer;
+}
+
+function toHex(value: ArrayBuffer | Uint8Array): string {
+  return Array.from(toUint8Array(value))
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', encoder.encode(input));
+  return toHex(digest);
+}
+
+async function hmacSha256(
+  key: string | Uint8Array,
+  value: string,
+): Promise<Uint8Array> {
+  const keyData = typeof key === 'string' ? encoder.encode(key) : key;
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    toArrayBuffer(keyData),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const signature = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(value));
+  return new Uint8Array(signature);
+}
+
+type SESCredentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+};
+
+function parseSesCredentials(apiKey: string): SESCredentials | null {
+  const [accessKeyId, secretAccessKey, ...rest] = apiKey.split(':');
+  if (!accessKeyId || !secretAccessKey) {
+    return null;
+  }
+  const sessionToken = rest.length > 0 ? rest.join(':') : undefined;
+  return { accessKeyId, secretAccessKey, sessionToken };
+}
+
+// ─── Resend Provider (Recommended, 3,000/month free) ───
+
+export class ResendProvider implements EmailProvider {
+  constructor(
+    private apiKey: string,
+    private from: string,
+  ) {}
+
+  async send(options: EmailSendOptions): Promise<EmailSendResult> {
+    const resp = await fetch('https://api.resend.com/emails', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        from: this.from,
+        to: options.to,
+        subject: options.subject,
+        html: options.html,
+      }),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.error('[EmailProvider:Resend] Failed:', resp.status, text);
+      return { success: false };
+    }
+
+    const data = (await resp.json()) as { id?: string };
+    return { success: true, messageId: data.id };
+  }
+}
+
+export class MockEmailProvider implements EmailProvider {
+  private endpoint: string;
+
+  constructor(
+    endpoint: string,
+    private from: string,
+  ) {
+    this.endpoint = endpoint.replace(/\/$/, '');
+  }
+
+  async send(options: EmailSendOptions): Promise<EmailSendResult> {
+    const resp = await fetch(`${this.endpoint}/send`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        from: this.from,
+        to: options.to,
+        subject: options.subject,
+        html: options.html,
+      }),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.error('[EmailProvider:Mock] Failed:', resp.status, text);
+      return { success: false };
+    }
+
+    const data = await resp.json().catch(() => ({})) as { id?: string; messageId?: string };
+    return { success: true, messageId: data.messageId ?? data.id };
+  }
+}
+
+// ─── SendGrid Provider (100/day free) ───
+
+export class SendGridProvider implements EmailProvider {
+  constructor(
+    private apiKey: string,
+    private from: string,
+  ) {}
+
+  async send(options: EmailSendOptions): Promise<EmailSendResult> {
+    const resp = await fetch('https://api.sendgrid.com/v3/mail/send', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        personalizations: [{ to: [{ email: options.to }] }],
+        from: { email: this.from },
+        subject: options.subject,
+        content: [{ type: 'text/html', value: options.html }],
+      }),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.error('[EmailProvider:SendGrid] Failed:', resp.status, text);
+      return { success: false };
+    }
+
+    // SendGrid returns 202 with x-message-id header
+    return {
+      success: true,
+      messageId: resp.headers.get('x-message-id') ?? undefined,
+    };
+  }
+}
+
+// ─── Mailgun Provider (1,000/month free for 3 months) ───
+
+export class MailgunProvider implements EmailProvider {
+  private domain: string;
+
+  constructor(
+    private apiKey: string,
+    private from: string,
+    domain?: string,
+  ) {
+    // Extract domain from "from" address if not explicitly provided
+    this.domain = domain ?? from.split('@')[1] ?? 'example.com';
+  }
+
+  async send(options: EmailSendOptions): Promise<EmailSendResult> {
+    const formData = new FormData();
+    formData.append('from', this.from);
+    formData.append('to', options.to);
+    formData.append('subject', options.subject);
+    formData.append('html', options.html);
+
+    const resp = await fetch(
+      `https://api.mailgun.net/v3/${this.domain}/messages`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Basic ${btoa(`api:${this.apiKey}`)}`,
+        },
+        body: formData,
+      },
+    );
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.error('[EmailProvider:Mailgun] Failed:', resp.status, text);
+      return { success: false };
+    }
+
+    const data = (await resp.json()) as { id?: string };
+    return { success: true, messageId: data.id };
+  }
+}
+
+// ─── AWS SES Provider ($0.10/1,000 emails) ───
+
+export class SESProvider implements EmailProvider {
+  constructor(
+    private apiKey: string,
+    private from: string,
+    private region: string = 'us-east-1',
+  ) {}
+
+  async send(options: EmailSendOptions): Promise<EmailSendResult> {
+    const credentials = parseSesCredentials(this.apiKey);
+    if (!credentials) {
+      console.error(
+        '[EmailProvider:SES] Invalid apiKey format. Expected accessKeyId:secretAccessKey[:sessionToken].',
+      );
+      return { success: false };
+    }
+
+    const host = `email.${this.region}.amazonaws.com`;
+    const path = '/v2/email/outbound-emails';
+    const endpoint = `https://${host}${path}`;
+    const payload = JSON.stringify({
+      FromEmailAddress: this.from,
+      Destination: { ToAddresses: [options.to] },
+      Content: {
+        Simple: {
+          Subject: { Data: options.subject, Charset: 'UTF-8' },
+          Body: {
+            Html: { Data: options.html, Charset: 'UTF-8' },
+          },
+        },
+      },
+    });
+
+    const now = new Date();
+    const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
+    const dateStamp = amzDate.slice(0, 8);
+    const payloadHash = await sha256Hex(payload);
+    const credentialScope = `${dateStamp}/${this.region}/ses/aws4_request`;
+    const canonicalHeadersEntries = [
+      ['host', host],
+      ['x-amz-content-sha256', payloadHash],
+      ['x-amz-date', amzDate],
+      ...(credentials.sessionToken
+        ? [['x-amz-security-token', credentials.sessionToken] as const]
+        : []),
+    ];
+    const canonicalHeaders = canonicalHeadersEntries
+      .map(([name, value]) => `${name}:${value}\n`)
+      .join('');
+    const signedHeaders = canonicalHeadersEntries.map(([name]) => name).join(';');
+    const canonicalRequest = [
+      'POST',
+      path,
+      '',
+      canonicalHeaders,
+      signedHeaders,
+      payloadHash,
+    ].join('\n');
+    const stringToSign = [
+      'AWS4-HMAC-SHA256',
+      amzDate,
+      credentialScope,
+      await sha256Hex(canonicalRequest),
+    ].join('\n');
+
+    const dateKey = await hmacSha256(`AWS4${credentials.secretAccessKey}`, dateStamp);
+    const regionKey = await hmacSha256(dateKey, this.region);
+    const serviceKey = await hmacSha256(regionKey, 'ses');
+    const signingKey = await hmacSha256(serviceKey, 'aws4_request');
+    const signature = toHex(await hmacSha256(signingKey, stringToSign));
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Host: host,
+      'X-Amz-Date': amzDate,
+      'X-Amz-Content-Sha256': payloadHash,
+      Authorization:
+        `AWS4-HMAC-SHA256 Credential=${credentials.accessKeyId}/${credentialScope}, `
+        + `SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    };
+
+    if (credentials.sessionToken) {
+      headers['X-Amz-Security-Token'] = credentials.sessionToken;
+    }
+
+    const resp = await fetch(endpoint, {
+      method: 'POST',
+      headers,
+      body: payload,
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      console.error('[EmailProvider:SES] Failed:', resp.status, text);
+      return { success: false };
+    }
+
+    const data = (await resp.json()) as { MessageId?: string };
+    return { success: true, messageId: data.MessageId };
+  }
+}
+
+// ─── Factory ───
+
+export interface EmailConfig {
+  provider: 'resend' | 'sendgrid' | 'mailgun' | 'ses';
+  apiKey: string;    // SES uses accessKeyId:secretAccessKey[:sessionToken]
+  from: string;
+  domain?: string;    // Mailgun domain
+  region?: string;    // SES region
+}
+
+/**
+ * Create an EmailProvider instance from config.
+ * Returns null if config is missing (email features disabled).
+ */
+export function createEmailProvider(
+  config?: EmailConfig,
+  env?: EmailProviderEnv,
+): EmailProvider | null {
+  const mockEndpoint = env?.EDGEBASE_EMAIL_API_URL?.trim()?.replace(/\/$/, '');
+  if (mockEndpoint) {
+    return new MockEmailProvider(mockEndpoint, config?.from ?? 'noreply@example.com');
+  }
+
+  if (!config) {
+    return null;
+  }
+
+  if (!config.apiKey || !config.from) {
+    console.warn('[EmailProvider] apiKey and from are required. Email features disabled.');
+    return null;
+  }
+
+  switch (config.provider) {
+    case 'resend':
+      return new ResendProvider(config.apiKey, config.from);
+    case 'sendgrid':
+      return new SendGridProvider(config.apiKey, config.from);
+    case 'mailgun':
+      return new MailgunProvider(config.apiKey, config.from, config.domain);
+    case 'ses':
+      return new SESProvider(config.apiKey, config.from, config.region);
+    default:
+      console.warn(`[EmailProvider] Unknown provider: ${config.provider}. Email features disabled.`);
+      return null;
+  }
+}

package/src/lib/email-templates.ts

@@ -0,0 +1,285 @@
+/**
+ * Email HTML templates for authentication flows.
+ *
+ * All 5 render functions accept an optional `locale` parameter (3rd argument)
+ * for i18n support. When locale is provided (and no custom template override),
+ * the built-in translated strings from email-translations.ts are used.
+ *
+ * Priority: custom template → built-in translation for locale → English default
+ *
+ * Users can override any template by providing custom HTML in `email.templates`
+ * config with {{variable}} placeholders for dynamic values.
+ */
+
+import { getStrings } from './email-translations.js';
+
+// ─── Shared Styles ───
+
+const SHARED_STYLES = `
+  body { margin: 0; padding: 0; background: #f4f4f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; }
+  .container { max-width: 560px; margin: 40px auto; background: #ffffff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.06); overflow: hidden; }
+  .header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 32px 40px; }
+  .header h1 { margin: 0; color: #ffffff; font-size: 24px; font-weight: 600; }
+  .body { padding: 40px; color: #333; line-height: 1.6; }
+  .body p { margin: 0 0 16px; }
+  .btn { display: inline-block; background: #667eea; color: #ffffff !important; text-decoration: none; padding: 14px 32px; border-radius: 6px; font-weight: 600; font-size: 16px; margin: 8px 0 24px; }
+  .code { background: #f0f0f5; border: 1px solid #e0e0e8; border-radius: 6px; padding: 16px; text-align: center; font-size: 28px; font-weight: 700; letter-spacing: 4px; color: #333; margin: 8px 0 24px; }
+  .footer { padding: 24px 40px; background: #f9f9fb; color: #888; font-size: 12px; text-align: center; border-top: 1px solid #eee; }
+  .muted { color: #888; font-size: 13px; }
+`;
+
+// ─── Custom Template Renderer ───
+
+/**
+ * Replace {{varName}} placeholders with HTML-escaped values.
+ * Unknown placeholders are left as-is.
+ */
+function renderCustomTemplate(
+  template: string,
+  vars: Record<string, string | number>,
+): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    const val = vars[key as string];
+    return val !== undefined ? escapeHtml(String(val)) : match;
+  });
+}
+
+/**
+ * Replace {{varName}} placeholders in a translation string.
+ * Same as renderCustomTemplate but returns raw (not HTML-escaped) for use
+ * inside already-safe template contexts. Values ARE escaped.
+ */
+function renderTranslationString(
+  str: string,
+  vars: Record<string, string | number>,
+): string {
+  return str.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    const val = vars[key as string];
+    return val !== undefined ? escapeHtml(String(val)) : match;
+  });
+}
+
+// ─── Verify Email ───
+
+export interface VerifyEmailVars {
+  appName: string;
+  verifyUrl: string;
+  token: string;
+  expiresInHours: number;
+}
+
+export function renderVerifyEmail(vars: VerifyEmailVars, customTemplate?: string, locale?: string): string {
+  if (customTemplate) {
+    return renderCustomTemplate(customTemplate, {
+      appName: vars.appName,
+      verifyUrl: vars.verifyUrl,
+      token: vars.token,
+      expiresInHours: vars.expiresInHours,
+    });
+  }
+
+  const lang = locale || 'en';
+  const s = getStrings(lang, 'verification');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><style>${SHARED_STYLES}</style></head>
+<body>
+  <div class="container">
+    <div class="header"><h1>${escapeHtml(vars.appName)}</h1></div>
+    <div class="body">
+      <p>${escapeHtml(s.heading)}</p>
+      <p>${escapeHtml(s.subheading ?? '')}</p>
+      <p style="text-align:center"><a class="btn" href="${escapeHtml(vars.verifyUrl)}">${escapeHtml(s.cta ?? 'Verify Email')}</a></p>
+      <p>${escapeHtml(s.tokenLabel ?? '')}</p>
+      <div class="code">${escapeHtml(vars.token)}</div>
+      <p class="muted">${renderTranslationString(s.expires, { expiresInHours: vars.expiresInHours })}</p>
+      <p class="muted">${escapeHtml(s.ignore)}</p>
+    </div>
+    <div class="footer">&copy; ${escapeHtml(vars.appName)}</div>
+  </div>
+</body>
+</html>`;
+}
+
+// ─── Password Reset ───
+
+export interface PasswordResetVars {
+  appName: string;
+  resetUrl: string;
+  token: string;
+  expiresInMinutes: number;
+}
+
+export function renderPasswordReset(vars: PasswordResetVars, customTemplate?: string, locale?: string): string {
+  if (customTemplate) {
+    return renderCustomTemplate(customTemplate, {
+      appName: vars.appName,
+      resetUrl: vars.resetUrl,
+      token: vars.token,
+      expiresInMinutes: vars.expiresInMinutes,
+    });
+  }
+
+  const lang = locale || 'en';
+  const s = getStrings(lang, 'passwordReset');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><style>${SHARED_STYLES}</style></head>
+<body>
+  <div class="container">
+    <div class="header"><h1>${escapeHtml(vars.appName)}</h1></div>
+    <div class="body">
+      <p>${escapeHtml(s.heading)}</p>
+      <p>${escapeHtml(s.subheading ?? '')}</p>
+      <p style="text-align:center"><a class="btn" href="${escapeHtml(vars.resetUrl)}">${escapeHtml(s.cta ?? 'Reset Password')}</a></p>
+      <p>${escapeHtml(s.tokenLabel ?? '')}</p>
+      <div class="code">${escapeHtml(vars.token)}</div>
+      <p class="muted">${renderTranslationString(s.expires, { expiresInMinutes: vars.expiresInMinutes })}</p>
+      <p class="muted">${escapeHtml(s.ignore)}</p>
+    </div>
+    <div class="footer">&copy; ${escapeHtml(vars.appName)}</div>
+  </div>
+</body>
+</html>`;
+}
+
+// ─── Magic Link ───
+
+export interface MagicLinkVars {
+  appName: string;
+  magicLinkUrl: string;
+  expiresInMinutes: number;
+}
+
+export function renderMagicLink(vars: MagicLinkVars, customTemplate?: string, locale?: string): string {
+  if (customTemplate) {
+    return renderCustomTemplate(customTemplate, {
+      appName: vars.appName,
+      magicLinkUrl: vars.magicLinkUrl,
+      expiresInMinutes: vars.expiresInMinutes,
+    });
+  }
+
+  const lang = locale || 'en';
+  const s = getStrings(lang, 'magicLink');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><style>${SHARED_STYLES}</style></head>
+<body>
+  <div class="container">
+    <div class="header"><h1>${escapeHtml(vars.appName)}</h1></div>
+    <div class="body">
+      <p>${escapeHtml(s.heading)}</p>
+      <p>${escapeHtml(s.subheading ?? '')}</p>
+      <p style="text-align:center"><a class="btn" href="${escapeHtml(vars.magicLinkUrl)}">${escapeHtml(s.cta ?? 'Sign In')}</a></p>
+      <p class="muted">${renderTranslationString(s.expires, { expiresInMinutes: vars.expiresInMinutes })}</p>
+      <p class="muted">${escapeHtml(s.ignore)}</p>
+    </div>
+    <div class="footer">&copy; ${escapeHtml(vars.appName)}</div>
+  </div>
+</body>
+</html>`;
+}
+
+// ─── Email OTP ───
+
+export interface EmailOtpVars {
+  appName: string;
+  code: string;
+  expiresInMinutes: number;
+}
+
+export function renderEmailOtp(vars: EmailOtpVars, customTemplate?: string, locale?: string): string {
+  if (customTemplate) {
+    return renderCustomTemplate(customTemplate, {
+      appName: vars.appName,
+      code: vars.code,
+      expiresInMinutes: vars.expiresInMinutes,
+    });
+  }
+
+  const lang = locale || 'en';
+  const s = getStrings(lang, 'emailOtp');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><style>${SHARED_STYLES}</style></head>
+<body>
+  <div class="container">
+    <div class="header"><h1>${escapeHtml(vars.appName)}</h1></div>
+    <div class="body">
+      <p>${escapeHtml(s.heading)}</p>
+      <p>${escapeHtml(s.instruction ?? '')}</p>
+      <div class="code">${escapeHtml(vars.code)}</div>
+      <p class="muted">${renderTranslationString(s.expires, { expiresInMinutes: vars.expiresInMinutes })}</p>
+      <p class="muted">${escapeHtml(s.ignore)}</p>
+    </div>
+    <div class="footer">&copy; ${escapeHtml(vars.appName)}</div>
+  </div>
+</body>
+</html>`;
+}
+
+// ─── Email Change Verification ───
+
+export interface EmailChangeVars {
+  appName: string;
+  verifyUrl: string;
+  token: string;
+  newEmail: string;
+  expiresInHours: number;
+}
+
+export function renderEmailChange(vars: EmailChangeVars, customTemplate?: string, locale?: string): string {
+  if (customTemplate) {
+    return renderCustomTemplate(customTemplate, {
+      appName: vars.appName,
+      verifyUrl: vars.verifyUrl,
+      token: vars.token,
+      newEmail: vars.newEmail,
+      expiresInHours: vars.expiresInHours,
+    });
+  }
+
+  const lang = locale || 'en';
+  const s = getStrings(lang, 'emailChange');
+
+  // instruction contains <strong>{{newEmail}}</strong> — render with variable substitution (not full escape)
+  const instructionHtml = s.instruction
+    ? renderTranslationString(s.instruction, { newEmail: vars.newEmail })
+    : `To change your email to <strong>${escapeHtml(vars.newEmail)}</strong>, click the button below:`;
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><style>${SHARED_STYLES}</style></head>
+<body>
+  <div class="container">
+    <div class="header"><h1>${escapeHtml(vars.appName)}</h1></div>
+    <div class="body">
+      <p>${escapeHtml(s.heading)}</p>
+      <p>${instructionHtml}</p>
+      <p style="text-align:center"><a class="btn" href="${escapeHtml(vars.verifyUrl)}">${escapeHtml(s.cta ?? 'Confirm Email Change')}</a></p>
+      <p>${escapeHtml(s.tokenLabel ?? '')}</p>
+      <div class="code">${escapeHtml(vars.token)}</div>
+      <p class="muted">${renderTranslationString(s.expires, { expiresInHours: vars.expiresInHours })}</p>
+      <p class="muted">${escapeHtml(s.ignore)}</p>
+    </div>
+    <div class="footer">&copy; ${escapeHtml(vars.appName)}</div>
+  </div>
+</body>
+</html>`;
+}
+
+// ─── Helpers ───
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}