@acms-subir/core 0.1.0 → 0.3.0

package/src/lib/documents/extract.ts

@@ -0,0 +1,154 @@
+/// <reference types="vite/client" />
+
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+export const MAX_SOURCE_CHARS = 50_000;
+const MAX_PDF_PAGES = 100;
+export interface ExtractedDocument { source: string; title: string; filename: string; warnings: string[] }
+
+// Extraction is browser-local. Neither file bytes nor embedded media are
+// uploaded. Conversion libraries are loaded only for the selected format.
+export async function extractDocument(file: File): Promise<ExtractedDocument> {
+  if (!file.size) throw new Error('This document is empty. Choose a file with readable text.');
+  if (file.size > MAX_FILE_BYTES) throw new Error('Choose a document smaller than 10 MB.');
+  const extension = file.name.split('.').pop()?.toLowerCase();
+  if (!['docx', 'pdf', 'txt', 'md'].includes(extension ?? '')) throw new Error('Use a DOCX, text-based PDF, TXT, or Markdown file.');
+  const bytes = await file.arrayBuffer();
+  let source: string;
+  const warnings: string[] = [];
+  if (extension === 'docx') {
+    validateDocxArchive(bytes);
+    const [{ default: mammoth }, { default: Turndown }] = await Promise.all([
+      import('mammoth/mammoth.browser.js'), import('turndown'),
+    ]);
+    let result;
+    try {
+      result = await mammoth.convertToHtml({ arrayBuffer: bytes }, {
+        externalFileAccess: false,
+        includeEmbeddedStyleMap: false,
+        convertImage: mammoth.images.imgElement(async () => {
+          warnings.push('An embedded image was omitted. Add it in the post or page editor after import.');
+          return { src: '' };
+        }),
+      });
+    } catch { throw new Error('This DOCX could not be read. Export it again as DOCX or UTF-8 text.'); }
+    if (result.messages.some((message) => message.type === 'error')) throw new Error('The DOCX contains content that could not be extracted. Export it as text and review it before importing.');
+    warnings.push(...result.messages.map((message) => message.message));
+    const converter = new Turndown({ headingStyle: 'atx', bulletListMarker: '-', codeBlockStyle: 'fenced' });
+    converter.remove(['img', 'script', 'style']);
+    converter.addRule('documentTables', {
+      filter: 'table',
+      replacement: (_content, node) => {
+        warnings.push('Tables were converted to Markdown. Review the column headings and cell layout.');
+        const rows = Array.from(node.querySelectorAll('tr')).map((row) => Array.from(row.querySelectorAll('th,td')).map((cell) =>
+          converter.turndown(cell.innerHTML).replace(/\|/g, '\\|').replace(/\n/g, ' ')));
+        if (!rows.length) return '';
+        const width = Math.max(...rows.map((row) => row.length));
+        const line = (row: string[]) => `| ${Array.from({ length: width }, (_, i) => row[i] ?? '').join(' | ')} |`;
+        return `\n\n${[line(rows[0]), line(Array(width).fill('---')), ...rows.slice(1).map(line)].join('\n')}\n\n`;
+      },
+    });
+    source = converter.turndown(result.value);
+    warnings.push('Text, headings, and lists were imported. Word page layout, headers, footers, and text boxes may differ or be omitted; check the original document.');
+  } else if (extension === 'pdf') {
+    if (!new TextDecoder().decode(bytes.slice(0, 1024)).includes('%PDF-')) throw new Error('This file does not appear to be a PDF.');
+    source = await extractPdf(bytes);
+    warnings.push('PDF import extracts text only. Images and page layout are not imported; check reading order, tables, and paragraph breaks against the original.');
+  } else {
+    source = decodeText(bytes);
+  }
+  source = source.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n').trim();
+  if (!source) throw new Error('No readable text was found. Scanned documents need OCR before import.');
+  if (source.length > MAX_SOURCE_CHARS) throw new Error('This document exceeds 50,000 characters. Split it into smaller documents before importing. Nothing was truncated.');
+  return { source, title: documentTitle(source, file.name), filename: file.name, warnings: [...new Set(warnings)].slice(0, 30) };
+}
+
+export function documentTitle(source: string, filename: string): string {
+  const heading = source.match(/^#{1,6}\s+(.+)$/m)?.[1]?.replace(/\s+#+$/, '').trim();
+  return (heading || filename.replace(/\.[^.]+$/, '').replace(/[_-]+/g, ' ').trim()).slice(0, 300);
+}
+export function decodeText(bytes: ArrayBuffer): string {
+  const prefix = new Uint8Array(bytes, 0, Math.min(3, bytes.byteLength));
+  const encoding = prefix[0] === 0xff && prefix[1] === 0xfe ? 'utf-16le' : prefix[0] === 0xfe && prefix[1] === 0xff ? 'utf-16be' : 'utf-8';
+  let text: string;
+  try { text = new TextDecoder(encoding, { fatal: true }).decode(bytes); }
+  catch { throw new Error('The text encoding could not be read. Save the document as UTF-8 text and try again.'); }
+  if (/[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(text)) throw new Error('This appears to be a binary file, not a text document.');
+  return text;
+}
+
+// Check the ZIP directory before asking Mammoth to inflate a DOCX. Reject
+// oversized archives, encrypted entries, ZIP64, and malformed directories.
+export function validateDocxArchive(buffer: ArrayBuffer): void {
+  const view = new DataView(buffer);
+  const invalid = () => new Error('This DOCX is invalid, encrypted, or too complex to import. Export a smaller DOCX or text file.');
+  if (view.byteLength < 22) throw invalid();
+  let end = -1;
+  for (let i = view.byteLength - 22; i >= Math.max(0, view.byteLength - 65557); i--) {
+    if (view.getUint32(i, true) === 0x06054b50 && i + 22 + view.getUint16(i + 20, true) === view.byteLength) { end = i; break; }
+  }
+  if (end < 0 || view.getUint16(end + 4, true) || view.getUint16(end + 6, true)) throw invalid();
+  const count = view.getUint16(end + 10, true);
+  const size = view.getUint32(end + 12, true);
+  let position = view.getUint32(end + 16, true);
+  const directoryEnd = position + size;
+  if (!count || count > 4096 || count !== view.getUint16(end + 8, true) || directoryEnd > end) throw invalid();
+  let unpacked = 0;
+  let hasDocument = false;
+  for (let entry = 0; entry < count; entry++) {
+    if (position + 46 > directoryEnd || view.getUint32(position, true) !== 0x02014b50 || (view.getUint16(position + 8, true) & 1)) throw invalid();
+    unpacked += view.getUint32(position + 24, true);
+    if (unpacked > 40 * 1024 * 1024) throw invalid();
+    const nameLength = view.getUint16(position + 28, true);
+    const next = position + 46 + nameLength + view.getUint16(position + 30, true) + view.getUint16(position + 32, true);
+    if (next > directoryEnd) throw invalid();
+    const name = new TextDecoder().decode(new Uint8Array(buffer, position + 46, nameLength));
+    if (name === 'word/document.xml') hasDocument = true;
+    position = next;
+  }
+  if (!hasDocument || position !== directoryEnd) throw invalid();
+}
+
+export interface PdfTextItem { str: string; hasEOL?: boolean; transform?: number[]; width?: number }
+export function pdfItemsToText(items: PdfTextItem[]): string {
+  let text = '';
+  let previous: PdfTextItem | undefined;
+  for (const item of items) {
+    if (previous && item.str && !/\s$/.test(text)) {
+      const sameLine = item.transform && previous.transform && Math.abs(item.transform[5] - previous.transform[5]) < 2;
+      const gap = item.transform && previous.transform ? item.transform[4] - (previous.transform[4] + (previous.width ?? 0)) : 1;
+      text += sameLine === false ? '\n' : gap > 0.5 ? ' ' : '';
+    }
+    text += item.str;
+    if (item.hasEOL) text += '\n';
+    previous = item;
+  }
+  return text.trim();
+}
+async function extractPdf(buffer: ArrayBuffer): Promise<string> {
+  const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+  const { default: workerUrl } = await import('pdfjs-dist/legacy/build/pdf.worker.min.mjs?url');
+  pdfjs.GlobalWorkerOptions.workerSrc = workerUrl;
+  const task = pdfjs.getDocument({ data: new Uint8Array(buffer), useSystemFonts: true, disableFontFace: true, useWasm: false });
+  // With no password callback PDF.js rejects encrypted files immediately.
+  try {
+    const pdf = await task.promise;
+    if (pdf.numPages > MAX_PDF_PAGES) throw new Error('PDFs are limited to 100 pages. Split this document before importing.');
+    const pages: string[] = [];
+    let length = 0;
+    for (let i = 1; i <= pdf.numPages; i++) {
+      const page = await pdf.getPage(i);
+      const content = await page.getTextContent();
+      const text = pdfItemsToText(content.items.filter((item): item is import('pdfjs-dist/types/src/display/api').TextItem => 'str' in item));
+      page.cleanup();
+      if (!text) throw new Error(`Page ${i} has no readable text. Remove blank pages or use OCR for scanned pages before importing. No pages were silently skipped.`);
+      length += text.length + 2;
+      if (length > MAX_SOURCE_CHARS) throw new Error('This document exceeds 50,000 characters. Split it into smaller documents before importing. Nothing was truncated.');
+      pages.push(text);
+    }
+    return pages.join('\n\n');
+  } catch (error) {
+    if (error instanceof Error && error.name === 'PasswordException') throw new Error('Password-protected PDFs are not supported. Upload an unlocked copy.');
+    if (error instanceof Error && /^(Page \d|PDFs are limited|This document exceeds)/.test(error.message)) throw error;
+    throw new Error('This PDF could not be read. Try exporting it as DOCX or text.');
+  } finally { await task.destroy(); }
+}

package/src/lib/documents/vendor.d.ts

@@ -0,0 +1,4 @@
+declare module 'mammoth/mammoth.browser.js' {
+  import mammoth = require('mammoth');
+  export default mammoth;
+}

package/src/lib/drafts.ts

@@ -0,0 +1,131 @@
+import type { CalEvent, NavItem, Page, Post, Settings } from './schema';
+
+// Pending-edit ("draft") snapshots for live documents. A published or
+// scheduled post/page never receives content edits directly: they accumulate
+// in the row's `draft` JSON column and only reach the live columns when the
+// user hits Update (repo.applyPostDraft / applyPageDraft).
+//
+// The snapshot stores the same camelCase field names the save actions accept,
+// plus `savedAt`. Status transitions, schedule times and the publish sweep
+// never live in a snapshot — those stay deliberate, immediate actions.
+
+export const POST_DRAFT_KEYS = [
+  'title', 'slug', 'collection', 'body', 'bodyJson', 'bodyHtml', 'excerpt',
+  'tags', 'cover', 'coverAlt', 'seoTitle', 'seoDesc', 'featured',
+  'authorIds', 'template', 'publishedAt',
+] as const;
+
+export const PAGE_DRAFT_KEYS = [
+  'title', 'slug', 'locale', 'isHome', 'seoTitle', 'seoDesc', 'template',
+  'bodyJson', 'bodyHtml', 'blocks',
+] as const;
+
+// events stage everything the editor can change, times and recurrence
+// included — a published event's date only moves when the user hits Update
+export const EVENT_DRAFT_KEYS = [
+  'title', 'slug', 'bodyJson', 'bodyHtml', 'excerpt', 'tags', 'cover', 'coverAlt',
+  'seoTitle', 'seoDesc', 'featured', 'template', 'start', 'end', 'allDay',
+  'timezone', 'rrule', 'exdates', 'cancelled', 'location', 'cta', 'calendarIds', 'fields', 'rsvp',
+] as const;
+
+type PostDraftKey = (typeof POST_DRAFT_KEYS)[number];
+type EventDraftKey = (typeof EVENT_DRAFT_KEYS)[number];
+type PageDraftKey = (typeof PAGE_DRAFT_KEYS)[number];
+
+function pick(draft: Record<string, unknown>, keys: readonly string[]) {
+  const out: Record<string, unknown> = {};
+  for (const k of keys) if (draft[k] !== undefined) out[k] = draft[k];
+  return out;
+}
+
+// Only known editable fields survive the pick — a hand-edited or legacy
+// snapshot can never smuggle status/id/timestamps into an UPDATE.
+export function pickPostDraft(draft: Record<string, unknown>): Partial<Pick<Post, PostDraftKey>> {
+  return pick(draft, POST_DRAFT_KEYS) as Partial<Pick<Post, PostDraftKey>>;
+}
+export function pickEventDraft(draft: Record<string, unknown>): Partial<Pick<CalEvent, EventDraftKey>> {
+  return pick(draft, EVENT_DRAFT_KEYS) as Partial<Pick<CalEvent, EventDraftKey>>;
+}
+export function pickPageDraft(draft: Record<string, unknown>): Partial<Pick<Page, PageDraftKey>> {
+  return pick(draft, PAGE_DRAFT_KEYS) as Partial<Pick<Page, PageDraftKey>>;
+}
+
+// The document as it will look after Update — what the editor hydrates from
+// and what /preview renders. Live rows pass through untouched.
+export function mergePostDraft(post: Post): Post {
+  if (!post.draft) return post;
+  const staged = pickPostDraft(post.draft);
+  const merged = { ...post, ...staged };
+  if (staged.authorIds) merged.authorId = staged.authorIds[0] ?? null;
+  return merged;
+}
+export function mergePageDraft(page: Page): Page {
+  if (!page.draft) return page;
+  return { ...page, ...pickPageDraft(page.draft) };
+}
+
+export function mergeEventDraft(event: CalEvent): CalEvent {
+  if (!event.draft) return event;
+  return { ...event, ...pickEventDraft(event.draft) };
+}
+
+export function draftSavedAt(doc: Pick<Post | Page | CalEvent, 'draft'>): number | null {
+  const ts = doc.draft?.savedAt;
+  return typeof ts === 'number' ? ts : null;
+}
+
+// Design-screen staging: the same shape, stored in settings.draftDesign and
+// applied by the "Publish design" button. The draft may also carry the full
+// ordered navigation list (navItems) — menus stage with the design so one
+// Publish changes the whole look at once — and the share-link epoch.
+export const DESIGN_DRAFT_KEYS = [
+  'activeTheme', 'designOverrides', 'siteLogo', 'siteFavicon', 'siteCover', 'sectionPages',
+] as const;
+
+type DesignDraftKey = (typeof DESIGN_DRAFT_KEYS)[number];
+
+export function pickDesignDraft(draft: Record<string, unknown>): Partial<Pick<Settings, DesignDraftKey>> {
+  return pick(draft, DESIGN_DRAFT_KEYS) as Partial<Pick<Settings, DesignDraftKey>>;
+}
+
+// Settings as they will look after Publish design — what preview mode
+// renders for admins (and share-link reviewers) while visitors keep the live one.
+export function mergeDesignDraft(settings: Settings): Settings {
+  if (!settings.draftDesign) return settings;
+  return { ...settings, ...pickDesignDraft(settings.draftDesign) };
+}
+
+export interface StagedNavItem { id: string; label: string; url: string; area: NavItem['area'] }
+
+// the staged menu list, or null when navigation isn't part of the draft
+export function draftNavItems(draft: Record<string, unknown> | null | undefined): StagedNavItem[] | null {
+  const list = draft?.navItems;
+  if (!Array.isArray(list)) return null;
+  return list
+    .filter((n): n is StagedNavItem =>
+      Boolean(n) && typeof n.id === 'string' && typeof n.label === 'string' && typeof n.url === 'string' &&
+      (n.area === 'header' || n.area === 'footer' || n.area === 'social'))
+    .map(({ id, label, url, area }) => ({ id, label, url, area }));
+}
+
+// staged list → NavItem[] in display order (what Site.astro renders)
+export function toNavItems(list: StagedNavItem[]): NavItem[] {
+  return list.map((n, i) => ({ ...n, order: i }));
+}
+
+export const shareEpoch = (draft: Record<string, unknown> | null | undefined): string =>
+  typeof draft?.shareEpoch === 'string' ? draft.shareEpoch : 'legacy-disabled';
+
+// A published-design snapshot (design_versions rows) — the draft shape
+// minus bookkeeping, so restoring one is just "load it as the draft".
+export function designSnapshot(settings: Settings, navItems: NavItem[]): Record<string, unknown> {
+  return {
+    activeTheme: settings.activeTheme,
+    designOverrides: settings.designOverrides,
+    sectionPages: settings.sectionPages,
+    siteLogo: settings.siteLogo,
+    siteFavicon: settings.siteFavicon,
+    siteCover: settings.siteCover,
+    navItems: navItems.map(({ id, label, url, area }) => ({ id, label, url, area })),
+  };
+}

package/src/lib/dynamicBlocks.ts

@@ -3,7 +3,8 @@ import type { Post, Settings } from './schema';
 import { slugify } from './schema';
 import { formatDate } from './dates';
 import { CONTENT, collectionUrl } from './content';
-import { renderCalendarBlock } from './calendar/render';
+import { renderCalendarBlock, isNativeSource } from './calendar/render';
+import { renderEventCards, type EventCardAttrs } from './calendar/cards';
 
 // Dynamic blocks: bodyHtml is a save-time cache, so cards whose content must
 // stay fresh (post lists, calendars) serialize as placeholder divs and get
@@ -14,8 +15,11 @@ import { renderCalendarBlock } from './calendar/render';
 //        data-layout="grid" data-limit="3" data-show-image="1" data-show-excerpt="1"></div>
 //   <div data-dyn="calendar" data-sources="[…ics urls]" data-view="month"
 //        data-title="…" data-subtitle="…" data-limit="6" data-open-link="1"></div>
+//   <div data-dyn="toc" data-title="In this article"></div>
+//   <div data-dyn="events" data-mode="upcoming" data-calendar="youth"
+//        data-event="" data-limit="3" data-layout="grid" data-show-image="1"></div>
 
-const PLACEHOLDER = /<div[^>]*data-dyn="(?:post-list|calendar)"[^>]*>\s*<\/div>/g;
+const PLACEHOLDER = /<div[^>]*data-dyn="(?:post-list|calendar|toc|events)"[^>]*>\s*<\/div>/g;
 
 const esc = (s: string) =>
   s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -51,11 +55,57 @@ function renderList(posts: Post[], layout: string, showImage: boolean, showExcer
   return `<section class="dyn-postlist" data-layout="${esc(layout)}">${items}</section>`;
 }
 
+// Heading anchors: body h1–h3 get stable slugified ids so sections are
+// deep-linkable and the TOC block has targets. Headings that already carry an
+// id (e.g. hand-written in an HTML card) are left alone.
+export function stampHeadingAnchors(html: string): string {
+  const seen = new Map<string, number>();
+  return html.replace(/<h([1-3])(\s[^>]*)?>([\s\S]*?)<\/h\1>/g, (m, lvl: string, attrs: string | undefined, inner: string) => {
+    if (attrs && /\bid=/.test(attrs)) return m;
+    const text = inner.replace(/<[^>]+>/g, '').replace(/&amp;/g, '&').replace(/&#0?39;|&apos;/g, "'");
+    const base = slugify(text);
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    const id = n > 1 ? `${base}-${n}` : base;
+    return `<h${lvl}${attrs ?? ''} id="${id}">${inner}</h${lvl}>`;
+  });
+}
+
+// Table of contents: rebuilt from the body's (already anchored) headings on
+// every request, so it can never go stale. Depth is relative to the shallowest
+// heading present.
+export interface TocItem { level: number; id: string; text: string }
+
+// the body's anchored h1–h3 headings, in order — feeds the TOC card and the
+// post page's "On this page" rail
+export function extractToc(html: string): TocItem[] {
+  const items: TocItem[] = [];
+  const re = /<h([1-3])[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/h\1>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html))) {
+    const text = m[3].replace(/<[^>]+>/g, '').trim();
+    if (text) items.push({ level: Number(m[1]), id: m[2], text });
+  }
+  return items;
+}
+
+function renderToc(html: string, title: string): string {
+  const items = extractToc(html);
+  if (!items.length) return '';
+  const min = Math.min(...items.map((i) => i.level));
+  const links = items
+    .map((i) => `<a class="pc-toc-link" data-depth="${i.level - min}" href="#${esc(i.id)}">${i.text}</a>`)
+    .join('');
+  return `<nav class="pc-toc">${title ? `<span class="pc-toc-title">${esc(title)}</span>` : ''}${links}</nav>`;
+}
+
 function calendarAttrs(tag: string) {
   let sources: string[] = [];
   try {
     const parsed = JSON.parse(attr(tag, 'sources') || '[]');
-    if (Array.isArray(parsed)) sources = parsed.filter((s): s is string => typeof s === 'string' && s.startsWith('http'));
+    if (Array.isArray(parsed)) {
+      sources = parsed.filter((s): s is string => typeof s === 'string' && (s.startsWith('http') || isNativeSource(s)));
+    }
   } catch {
     /* malformed attr: render the empty state rather than break the page */
   }
@@ -70,10 +120,24 @@ function calendarAttrs(tag: string) {
   };
 }
 
+function eventCardAttrs(tag: string): EventCardAttrs {
+  return {
+    mode: attr(tag, 'mode') === 'single' ? 'single' : 'upcoming',
+    eventId: attr(tag, 'event'),
+    calendar: attr(tag, 'calendar'),
+    limit: Math.min(12, Math.max(1, Number(attr(tag, 'limit')) || 3)),
+    layout: attr(tag, 'layout') === 'list' ? 'list' : 'grid',
+    showImage: attr(tag, 'show-image') !== '0',
+  };
+}
+
 export async function expandDynamicBlocks(html: string, repo: ContentRepository): Promise<string> {
+  html = stampHeadingAnchors(html);
   const hasPostList = html.includes('data-dyn="post-list"');
   const hasCalendar = html.includes('data-dyn="calendar"');
-  if (!hasPostList && !hasCalendar) return html;
+  const hasToc = html.includes('data-dyn="toc"');
+  const hasEvents = html.includes('data-dyn="events"');
+  if (!hasPostList && !hasCalendar && !hasToc && !hasEvents) return html;
   const [posts, settings] = await Promise.all([
     hasPostList ? repo.listPublishedPosts() : Promise.resolve([] as Post[]), // newest first; shared by all blocks on the page
     repo.getSettings(),
@@ -83,15 +147,23 @@ export async function expandDynamicBlocks(html: string, repo: ContentRepository)
   // rendered up front, then spliced in during the synchronous pass.
   const calendarHtml = new Map<string, string>();
   if (hasCalendar) {
-    const tags = [...new Set((html.match(PLACEHOLDER) ?? []).filter((t) => t.includes('data-dyn="calendar"')))];
+    const tags = [...new Set((html.match(PLACEHOLDER) ?? ([] as string[])).filter((t) => t.includes('data-dyn="calendar"')))];
     const now = Date.now();
     await Promise.all(
-      tags.map(async (tag) => calendarHtml.set(tag, await renderCalendarBlock(calendarAttrs(tag), settings, now)))
+      tags.map(async (tag) => calendarHtml.set(tag, await renderCalendarBlock(calendarAttrs(tag), settings, now, repo)))
     );
   }
+  // event cards read the DB, so they're rendered up front the same way
+  if (hasEvents) {
+    const tags = [...new Set((html.match(PLACEHOLDER) ?? ([] as string[])).filter((t) => t.includes('data-dyn="events"')))];
+    const now = Date.now();
+    await Promise.all(tags.map(async (tag) => calendarHtml.set(tag, await renderEventCards(eventCardAttrs(tag), repo, settings, now))));
+  }
 
+  const anchored = html;
   return html.replace(PLACEHOLDER, (tag) => {
-    if (tag.includes('data-dyn="calendar"')) return calendarHtml.get(tag) ?? '';
+    if (tag.includes('data-dyn="calendar"') || tag.includes('data-dyn="events"')) return calendarHtml.get(tag) ?? '';
+    if (tag.includes('data-dyn="toc"')) return renderToc(anchored, attr(tag, 'title'));
     const source = attr(tag, 'source') || 'latest';
     const tagName = attr(tag, 'tag');
     // which collection the block draws from; 'posts' unless the card says otherwise

package/src/lib/email/accounts.ts

@@ -0,0 +1,55 @@
+import { randomBytes } from 'node:crypto';
+import type { ContentRepository } from '../repo/types';
+import { hashPassword, verifyPassword, checkPassword, OWNER_ENV } from '../auth';
+import { encrypt, encryptionAvailable, sha256, resolveConfig, validAddress } from './config';
+import { canonicalOrigin } from './templates';
+import type { NewEmailJob } from './types';
+
+export async function accountForm(request: Request): Promise<URLSearchParams> {
+  if (!request.headers.get('content-type')?.startsWith('application/x-www-form-urlencoded')) throw new Error('Unsupported form format.');
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error('Form is required.');
+  const chunks: Uint8Array[] = []; let size = 0;
+  try {
+    while (true) {
+      const {done,value} = await reader.read(); if (done) break;
+      size += value.byteLength;
+      if (size > 10000) { await reader.cancel(); throw new Error('Form too large.'); }
+      chunks.push(value);
+    }
+  } finally { reader.releaseLock(); }
+  return new URLSearchParams(Buffer.concat(chunks).toString('utf8'));
+}
+
+export async function reauthenticate(repo:ContentRepository, userId:string, password:string) {
+  if (!password || password.length>1024) return false;
+  if (userId===OWNER_ENV) return checkPassword(password);
+  const user=await repo.getUser(userId); if(!user)return false;
+  const auth=await repo.getUserAuth(user.email);return !!auth && verifyPassword(password,auth.passHash);
+}
+export async function issueAccountToken(repo:ContentRepository, data:{purpose:'invite'|'reset';email:string;name?:string;role?:'owner'|'editor';expiresDays?:number}, locals?:unknown) {
+  const email=data.email.trim().toLowerCase();
+  if(!validAddress(email))throw new Error('Enter a valid email address.');
+  const auth=await repo.getUserAuth(email);
+  if(data.purpose==='reset'&&!auth)return;
+  if(data.purpose==='invite'&&auth)throw new Error('This address already has an account. Manage its role in Users.');
+  const c=resolveConfig(await repo.email.config(),locals);
+  if(c.error||c.provider==='none'||!c.config.enabled)throw new Error(c.error||'Configure email before sending account links.');
+  if(!encryptionAvailable(locals))throw new Error('Configure EMAIL_ENCRYPTION_KEY before sending account links.');
+  canonicalOrigin((await repo.getSettings()).siteUrl);
+  const id=crypto.randomUUID(),raw=randomBytes(32).toString('base64url');
+  const expiresAt=Date.now()+(data.purpose==='reset'?30*60000:(data.expiresDays||7)*86400000);
+  const token={id,hash:sha256(raw),encrypted:encrypt(raw,`token:${id}`,locals),purpose:data.purpose,email,name:data.name?.trim().slice(0,120)||email.split('@')[0],role:data.role||'editor',userId:auth?.user.id||'',expiresAt};
+  const job:NewEmailJob={dedupe:`${data.purpose}:${id}`,kind:'auth',recipient:email,payload:JSON.stringify({tokenId:id,purpose:data.purpose}),configVersion:c.version,expiresAt};
+  await repo.email.saveToken(token,job);
+}
+export async function redeemAccountToken(repo:ContentRepository,raw:string,password:string,purpose:'invite'|'reset'):Promise<boolean> {
+  if(!/^[a-zA-Z0-9_-]{43}$/.test(raw))return false;
+  if(password.length<12||password.length>128)throw new Error('Use a password between 12 and 128 characters.');
+  const token=await repo.email.tokenByHash(sha256(raw));
+  if(!token||token.purpose!==purpose)return false;
+  const config=await repo.email.config();
+  return repo.email.consume(sha256(raw),await hashPassword(password),crypto.randomUUID(),{
+    dedupe:`notice:${token.id}`,kind:purpose==='invite'?'welcome':'password-changed',recipient:String(token.email),payload:'{}',configVersion:config?.version||0,
+  });
+}

package/src/lib/email/config.ts

@@ -0,0 +1,86 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { env } from '../env';
+import type { SendEmail } from '@cloudflare/workers-types';
+import { DEFAULT_EMAIL_CONFIG, type ConfigRecord, type Credentials, type EmailConfig, type Provider, type ResolvedConfig } from './types';
+
+export function runtimeValue(key: string, locals?: unknown): string {
+  const value = (locals as { runtime?: { env?: Record<string, unknown> } } | undefined)?.runtime?.env?.[key];
+  return typeof value === 'string' ? value : env(key);
+}
+export function emailBinding(locals?: unknown): SendEmail | null {
+  const value = (locals as { runtime?: { env?: { EMAIL?: SendEmail } } } | undefined)?.runtime?.env?.EMAIL;
+  return value && typeof value.send === 'function' ? value : null;
+}
+export const validAddress = (s: string) => s.length <= 254 && /^[^\s<>@,;\r\n]+@[^\s<>@,;\r\n]+\.[^\s<>@,;\r\n]+$/.test(s);
+export function parseFrom(raw: string): { email: string; name?: string } | null {
+  if (/[\r\n]/.test(raw)) return null;
+  const match = /^\s*(?:"?([^"<>]*?)"?\s*)?<([^<>]+)>\s*$/.exec(raw);
+  const email = (match ? match[2] : raw).trim();
+  return validAddress(email) ? { email, ...(match?.[1]?.trim() ? { name: match[1].trim() } : {}) } : null;
+}
+export const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
+function keys(locals?: unknown): Record<string, string> {
+  const raw = runtimeValue('EMAIL_ENCRYPTION_KEYS', locals);
+  if (raw) { try { return JSON.parse(raw); } catch { throw new Error('EMAIL_ENCRYPTION_KEYS must be a JSON key map.'); } }
+  const key = runtimeValue('EMAIL_ENCRYPTION_KEY', locals);
+  return key ? { v1: key } : {};
+}
+function encryptionKey(id: string, locals?: unknown): Buffer {
+  const key = Buffer.from(keys(locals)[id] || '', 'base64');
+  if (key.length !== 32) throw new Error('Configure a dedicated 32-byte base64 EMAIL_ENCRYPTION_KEY before storing credentials or sending account links.');
+  return key;
+}
+export function encryptionAvailable(locals?: unknown): boolean {
+  try { encryptionKey(runtimeValue('EMAIL_ENCRYPTION_KEY_ID', locals) || 'v1', locals); return true; } catch { return false; }
+}
+export function encrypt(value: unknown, purpose: string, locals?: unknown): string {
+  const id = runtimeValue('EMAIL_ENCRYPTION_KEY_ID', locals) || 'v1';
+  if (!/^[a-zA-Z0-9_-]{1,40}$/.test(id)) throw new Error('Invalid email encryption key ID.');
+  const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', encryptionKey(id, locals), iv);
+  cipher.setAAD(Buffer.from(`acms-email:${purpose}:${id}`));
+  const data = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()]);
+  return [id, iv.toString('base64url'), cipher.getAuthTag().toString('base64url'), data.toString('base64url')].join('.');
+}
+export function decrypt<T>(raw: string, purpose: string, locals?: unknown): T {
+  try {
+    const parts = raw.split('.');
+    if (parts.length !== 4) throw new Error();
+    const [id, iv, tag, data] = parts;
+    const decipher = createDecipheriv('aes-256-gcm', encryptionKey(id, locals), Buffer.from(iv, 'base64url'));
+    decipher.setAAD(Buffer.from(`acms-email:${purpose}:${id}`)); decipher.setAuthTag(Buffer.from(tag, 'base64url'));
+    return JSON.parse(Buffer.concat([decipher.update(Buffer.from(data, 'base64url')), decipher.final()]).toString('utf8')) as T;
+  } catch { throw new Error('Saved email data cannot be decrypted. Restore its encryption key or reconnect the provider.'); }
+}
+export function resolveConfig(record: ConfigRecord | null, locals?: unknown): ResolvedConfig {
+  const config = { ...DEFAULT_EMAIL_CONFIG, ...record?.config };
+  const read = (key: string) => runtimeValue(key, locals).trim();
+  const override = read('EMAIL_PROVIDER');
+  if (override) { config.provider = override as EmailConfig['provider']; config.source = 'env'; }
+  let credentials: Credentials = {};
+  if (config.source === 'env') {
+    config.from = read('EMAIL_FROM') || config.from; config.replyTo = read('EMAIL_REPLY_TO') || config.replyTo;
+    config.domain = read('MAILGUN_DOMAIN') || config.domain;
+    config.configurationSet = read('SES_CONFIGURATION_SET') || config.configurationSet;
+    config.snsTopicArn = read('SES_SNS_TOPIC_ARN') || config.snsTopicArn;
+  }
+  let provider: Provider | 'none' = 'none', error = '';
+  if (!['none', 'auto', 'resend', 'mailgun', 'ses', 'cloudflare'].includes(config.provider)) error = 'Invalid EMAIL_PROVIDER.';
+  else if (config.enabled && config.provider !== 'none') {
+    provider = config.provider === 'auto' ? emailBinding(locals) ? 'cloudflare' : read('RESEND_API_KEY') ? 'resend' : 'none' : config.provider;
+    if (config.source === 'encrypted' && record?.encrypted) {
+      try { credentials = decrypt<Credentials>(record.encrypted, 'credentials', locals); } catch (e) { error = (e as Error).message; }
+    } else if (config.source === 'env') {
+      credentials = { apiKey: read(provider === 'mailgun' ? 'MAILGUN_API_KEY' : 'RESEND_API_KEY'), webhookSecret: read(provider === 'mailgun' ? 'MAILGUN_WEBHOOK_SIGNING_KEY' : 'RESEND_WEBHOOK_SECRET'), accessKeyId: read('AWS_ACCESS_KEY_ID'), secretAccessKey: read('AWS_SECRET_ACCESS_KEY'), sessionToken: read('AWS_SESSION_TOKEN') };
+      config.region = read(provider === 'mailgun' ? 'MAILGUN_REGION' : 'AWS_REGION') || config.region;
+    }
+    if (!parseFrom(config.from)) error ||= 'Set a valid sending address (EMAIL_FROM).';
+    if (config.replyTo && !parseFrom(config.replyTo)) error ||= 'Set a valid reply-to address.';
+    if ((provider === 'resend' || provider === 'mailgun') && !credentials.apiKey) error ||= 'The selected provider needs an API key.';
+    if (provider === 'mailgun' && (!/^[a-z0-9.-]+$/i.test(config.domain) || !['us', 'eu'].includes(config.region))) error ||= 'Mailgun needs a sending domain and region (us or eu).';
+    if (provider === 'ses' && (!credentials.accessKeyId || !credentials.secretAccessKey || !/^[a-z]{2}(?:-gov)?-[a-z]+-\d$/.test(config.region))) error ||= 'SES needs AWS credentials and a valid AWS region.';
+    if (provider === 'cloudflare' && !emailBinding(locals)) error ||= 'The Cloudflare EMAIL binding is not available in this runtime.';
+    if (provider === 'none') error ||= 'No email provider is configured.';
+  }
+  const fingerprint = sha256(JSON.stringify({ config, credentials }));
+  return { version: record?.version || 0, config, provider, credentials, error: error || undefined, fingerprint };
+}

package/src/lib/email/migration.ts

@@ -0,0 +1,24 @@
+// No secrets or outbox payloads are part of the content backup format.
+export const EMAIL_MIGRATION = {
+  version: 29,
+  statements: [
+    `ALTER TABLE users ADD COLUMN session_version INTEGER NOT NULL DEFAULT 0`,
+    `ALTER TABLE bookings ADD COLUMN notification_version INTEGER NOT NULL DEFAULT 0`,
+    `ALTER TABLE bookings ADD COLUMN email_mutation TEXT NOT NULL DEFAULT ''`,
+    `CREATE TABLE email_configs (version INTEGER PRIMARY KEY AUTOINCREMENT,config TEXT NOT NULL,encrypted TEXT NOT NULL DEFAULT '',created_at INTEGER NOT NULL)`,
+    `CREATE TABLE email_jobs (id TEXT PRIMARY KEY,dedupe TEXT NOT NULL UNIQUE,kind TEXT NOT NULL,recipient TEXT NOT NULL,payload TEXT NOT NULL,
+      config_version INTEGER NOT NULL DEFAULT 0,state TEXT NOT NULL DEFAULT 'queued',attempts INTEGER NOT NULL DEFAULT 0,next_at INTEGER NOT NULL,
+      expires_at INTEGER,created_at INTEGER NOT NULL,updated_at INTEGER NOT NULL,lease TEXT NOT NULL DEFAULT '',lease_until INTEGER,
+      provider TEXT NOT NULL DEFAULT '',provider_id TEXT NOT NULL DEFAULT '',error TEXT NOT NULL DEFAULT '',accepted_at INTEGER,fingerprint TEXT NOT NULL DEFAULT '',rendered TEXT NOT NULL DEFAULT '')`,
+    `CREATE INDEX email_jobs_due ON email_jobs(state,next_at)`,
+    `CREATE INDEX email_jobs_provider ON email_jobs(provider,provider_id)`,
+    `CREATE TABLE email_attempts (id INTEGER PRIMARY KEY AUTOINCREMENT,job_id TEXT NOT NULL,attempt INTEGER NOT NULL,state TEXT NOT NULL,error TEXT NOT NULL,created_at INTEGER NOT NULL)`,
+    `CREATE TABLE email_delivery_events (id TEXT PRIMARY KEY,provider TEXT NOT NULL,provider_id TEXT NOT NULL,job_id TEXT NOT NULL DEFAULT '',recipient TEXT NOT NULL,state TEXT NOT NULL,created_at INTEGER NOT NULL,config_version INTEGER NOT NULL)`,
+    `CREATE INDEX email_events_message ON email_delivery_events(provider,provider_id)`,
+    `CREATE TABLE email_suppressions (address TEXT PRIMARY KEY,reason TEXT NOT NULL,created_at INTEGER NOT NULL)`,
+    `CREATE TABLE email_tokens (id TEXT PRIMARY KEY,token_hash TEXT NOT NULL UNIQUE,encrypted TEXT NOT NULL,purpose TEXT NOT NULL,email TEXT NOT NULL,name TEXT NOT NULL,role TEXT NOT NULL,user_id TEXT NOT NULL,expires_at INTEGER NOT NULL,created_at INTEGER NOT NULL,used_by TEXT NOT NULL DEFAULT '',revoked INTEGER NOT NULL DEFAULT 0)`,
+    `CREATE INDEX email_tokens_email ON email_tokens(email,purpose)`,
+    `CREATE TABLE email_rate_limits (key TEXT PRIMARY KEY,count INTEGER NOT NULL,expires_at INTEGER NOT NULL)`,
+    `CREATE TABLE email_meta (key TEXT PRIMARY KEY,value TEXT NOT NULL)`,
+  ],
+};