webspresso 0.0.80 → 0.0.82

package/README.md

@@ -245,9 +245,10 @@ webspresso doctor --strict
 
 ### `webspresso skill`
 
-Scaffold a **Cursor Agent Skill**: creates `.cursor/skills/<name>/SKILL.md` with valid YAML frontmatter (`name`, `description`) and a short markdown template for AI tooling. Use `--global` to write under `~/.cursor/skills/` instead of the current project.
+Scaffold an **Agent Skill**: creates `.agents/skills/<name>/SKILL.md` with valid YAML frontmatter (`name`, `description`) and a short markdown template for AI tooling. Use `--global` to write under `~/.agents/skills/` instead of the current project.
+
+**Bundled preset:** `--preset webspresso` copies **`SKILL.md`** (short index), **`REFERENCE-framework.md`** (SSR `createApp`, routes, ORM, auth, plugins, CLI), and **`REFERENCE-kernel.md`** (`kernel` event bus / flows) into **`.agents/skills/webspresso-usage/`** — no prompts.
 
-**Bundled preset:** `--preset webspresso` copies **`SKILL.md`** (short index), **`REFERENCE-framework.md`** (SSR `createApp`, routes, ORM, auth, plugins, CLI), and **`REFERENCE-kernel.md`** (`kernel` event bus / flows) into **`.cursor/skills/webspresso-usage/`** — no prompts.
 
 ```bash
 webspresso skill my-workflow
@@ -805,16 +806,18 @@ Options:
 - `userManagement` - Site-user admin UI (`enabled`, `model` matching ORM user table, optional `fields` map). SPA routes: `/_admin/users`, `/_admin/users/new`, …; APIs: `/_admin/api/users*`. Admin staff still use **`admin_users`** / `/_admin` login; this is separate from **`req.user`** on the public site
 - `configure` - Callback `(registry) => void` for manual setup
 
-See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.cursor/skills/webspresso-usage/REFERENCE-framework.md`** for the split between **`adminUser`** and **`createApp({ auth })`**.
+See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.agents/skills/webspresso-usage/REFERENCE-framework.md`** for the split between **`adminUser`** and **`createApp({ auth })`**.
+
 
 **Custom Admin Pages (registerModule):**
 
-Plugins can add custom admin pages using `registerModule` in `onRoutesReady`:
+Plugins can add custom admin pages using `registerModule` (or `registerPageDir`) in `onRoutesReady`:
 
 ```javascript
 // In your plugin's onRoutesReady(ctx)
 const adminApi = ctx.usePlugin('admin-panel');
 if (adminApi) {
+  // Option 1: File-based registration with auto Layout wrapping
   adminApi.registerModule({
     id: 'my-module',
 
@@ -824,7 +827,8 @@ if (adminApi) {
       path: '/reports',
       icon: 'chart',
       description: 'View reports',
-      component: `window.__customPages["reports"] = { view: () => m("div", "My Report") };`,  // Mithril.js
+      componentFile: path.join(__dirname, 'admin/reports.js'), // JS component file
+      layout: true, // Auto-wraps view in Admin Layout (default: true)
     }],
 
     menu: [{ id: 'reports', label: 'Reports', path: '/reports', icon: 'chart', order: 5 }],
@@ -835,15 +839,10 @@ if (adminApi) {
         { method: 'get', path: '/summary', handler: getSummaryHandler, auth: true },
       ],
     },
-
-    widgets: [{
-      id: 'reports-widget',
-      title: 'Quick Stats',
-      dataLoader: async () => ({ count: 42 }),
-    }],
-
-    menuGroups: [{ id: 'analytics', label: 'Analytics', order: 2 }],
   });
+
+  // Option 2: Folder-based auto registration (dir containing page.json + component.js)
+  adminApi.registerPageDir(path.join(__dirname, 'admin/pages'));
 }
 ```
 
@@ -851,13 +850,41 @@ if (adminApi) {
 | Field | Description |
 |-------|-------------|
 | `id` | Unique module identifier (required) |
-| `pages` | Custom admin pages (each: `id`, `title`, `path`, `icon`, `description`, optional `component`) |
+| `pages` | Custom admin pages (`id`, `title`, `path`, `icon`, `description`, `componentFile`, `component`, `layout`) |
+| `pagesDir` | Path to directory containing page folders/configs for automatic discovery |
 | `menu` | Sidebar menu items (`id`, `label`, `path`, `icon`, `order`) |
 | `menuGroups` | Collapsible menu groups (`id`, `label`, `order`) |
 | `api` | API routes (`prefix`, `routes`: `method`, `path`, `handler`, `auth`) |
 | `widgets` | Dashboard widgets (`id`, `title`, `dataLoader`) |
 
-For pages with `component`: provide Mithril.js code that assigns to `window.__customPages[pageId]`. Without `component`, the page shows a static placeholder.
+Pages support `componentFile` (path to a `.js` file exporting/returning a Mithril component), `pagesDir` (directory auto-discovery), or `component` (code string). By default (`layout: true`), page views are automatically wrapped in the Admin Layout with Breadcrumbs. Set `layout: false` for full-screen / custom canvas pages.
+
+**Example component file (`admin/reports.js`):**
+
+```javascript
+// Clean Mithril.js component object (no manual m(Layout, ...) needed!)
+({
+  oninit: async (vnode) => {
+    vnode.state.data = [];
+    try {
+      const res = await api.get('/reports/summary');
+      vnode.state.data = res.data || [];
+      m.redraw();
+    } catch (err) {
+      console.error('Failed to load report data:', err);
+    }
+  },
+  view: (vnode) => {
+    const data = vnode.state.data || [];
+    return m('div.space-y-4', [
+      m('h1.text-2xl.font-bold.text-gray-900.dark:text-slate-100', 'Report Summary'),
+      m('p.text-gray-600.dark:text-slate-400', `Total records: ${data.length}`),
+    ]);
+  }
+})
+```
+
+
 
 **Manual registry API** (alternative to registerModule):
 
@@ -982,6 +1009,57 @@ const { app } = createApp({
 
 Programmatic API (other plugins): `ctx.usePlugin('audit-log')` exposes `queryLogs`, `purgeAuditLogs`, and `getMigrationTemplate()`.
 
+**Email plugin:**
+- Sends email via **Nodemailer** with **MJML** templates (`{{variable}}` interpolation)
+- Template sources: `templatesDir` (`*.mjml`, **Node.js only** — skipped on edge/workers), `templates` map with inline `{ mjml }`, runtime `registerTemplate`, or inline `send({ mjml, html, data })`
+- Transport: `transport`, `smtp`, or env (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_SECURE`, `MAIL_FROM`)
+- Optional DB logging to `email_logs` when `db` is passed; prune with `webspresso email:prune --days 90`
+- **Build:** `webspresso build` embeds `emails/*.mjml` (config `emailDir`) + bundled auth templates into `manifest.emailTemplates` and `email-templates.mjs` (Cloudflare). Use `emailPlugin({ manifest })` or `emailPlugin({ emailTemplates: manifest.emailTemplates })` on edge.
+- Admin page at `/_admin/email` (test send, preview, SMTP verify, logs) when `adminPanelPlugin` is loaded
+- Optional **auth bridge**: `authEmails: { enabled: true }` sends password-reset / email-verification mails and can register `POST /api/auth/forgot-password`, `/reset-password`, `/verify-email`, `/resend-verification`
+
+```javascript
+const { quickAuth, createAuthTokensTable } = require('webspresso/core/auth');
+const { adminPanelPlugin, emailPlugin } = require('webspresso/plugins');
+
+const auth = quickAuth({ db, authTokens: true });
+await createAuthTokensTable(db.knex);
+
+const { app, pluginManager } = createApp({
+  pagesDir: './pages',
+  db,
+  auth,
+  plugins: [
+    emailPlugin({
+      db,
+      auth,
+      templatesDir: './emails',
+      smtp: {
+        host: process.env.SMTP_HOST,
+        port: 587,
+        auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
+      },
+      defaults: { from: process.env.MAIL_FROM },
+      authEmails: {
+        enabled: true,
+        baseUrl: process.env.BASE_URL,
+        registerRoutes: true,
+      },
+    }),
+    adminPanelPlugin({ db }),
+  ],
+});
+
+// From a route handler or another plugin:
+await pluginManager.getPluginAPI('email').sendTemplate('welcome', {
+  to: 'user@example.com',
+  subject: 'Welcome',
+  data: { name: 'Ali' },
+});
+```
+
+Programmatic API: `ctx.usePlugin('email')` exposes `send`, `sendTemplate`, `preview`, `registerTemplate`, `listTemplates`, `verifyConnection`, `queryLogs`, `purgeLogs`, `getMigrationTemplate()`.
+
 **ORM cache admin plugin:**
 - Depends on **`adminPanelPlugin`** and a database instance created with **`createDatabase({ cache: true | { … } })`** so **`db.cache`** is non-null
 - Registers an **ORM Cache** admin page (metrics, full purge, per-model invalidation, reset counters) backed by **`db.cache`**
@@ -2263,6 +2341,46 @@ const app = createApp({
 
 In production, keep the plugin disabled or protect it with `authorize` / your own middleware.
 
+### CSRF protection plugin
+
+Protects mutating requests against Cross-Site Request Forgery (CSRF) using the double-submit token pattern. Supports session storage (when `req.session` is available) and automatically falls back to cookie-based storage.
+
+**Setup:**
+
+```javascript
+const { createApp, csrfPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    csrfPlugin({
+      global: true,                 // Enable globally for all routes
+      cookie: true,                 // Use cookie-based storage (default uses session if present)
+      ignorePaths: ['/api/webhook'], // Skip CSRF verification for specific routes
+    }),
+  ],
+});
+```
+
+**Route-Specific Middleware:**
+
+If `global: false` (default), you can protect specific routes by applying the named route middleware `csrf` in your route configuration:
+
+```javascript
+// pages/submit.js
+module.exports = {
+  middleware: ['csrf'],
+  post(req, res) {
+    res.send('Success!');
+  }
+};
+```
+
+**Template Helpers:**
+
+The plugin registers two Nunjucks template helpers:
+- `{{ fsy.csrfToken() }}`: Returns the raw token string (useful for API fetch/headers).
+- `{{ fsy.csrfInput() }}`: Renders a hidden input field: `<input type="hidden" name="_csrf" value="...">`.
+
 ## Development
 
 Native addons (**better-sqlite3**, **bcrypt**, **sharp**) are compiled for your current Node ABI. After switching Node major versions (e.g. nvm, fnm, Volta), run **`npm run rebuild:native`** or a clean install: `rm -rf node_modules && npm ci`. **chokidar** is not ABI-tied like those drivers; if file watching misbehaves, reinstall dependencies. The repo includes [`.nvmrc`](.nvmrc) (Node 20 LTS) as a known-good default for this project.

package/bin/commands/doctor.js

@@ -102,6 +102,89 @@ function registerCommand(program) {
       const pagesPath = path.join(cwd, 'pages');
       if (fs.existsSync(pagesPath) && fs.statSync(pagesPath).isDirectory()) {
         line('✓', 'pages/ directory present');
+
+        console.log('\nRouting and file-system checks');
+        console.log('------------------------------');
+
+        let routingChecksPassed = true;
+
+        function getGenericSegment(name) {
+          if (name.startsWith('[') && name.endsWith(']')) {
+            const inner = name.slice(1, -1);
+            if (inner.startsWith('...')) {
+              return '*';
+            }
+            return ':param';
+          }
+          return name;
+        }
+
+        function scanRoutes(dirPath, relativeDir = '', isApi = false) {
+          const children = fs.readdirSync(dirPath);
+          const kept = [];
+
+          for (const child of children) {
+            const fullPath = path.join(dirPath, child);
+            const relPath = relativeDir ? path.join(relativeDir, child) : child;
+            const stats = fs.statSync(fullPath);
+
+            // 1. Check case-sensitivity issues
+            if (child !== child.toLowerCase()) {
+              line('⚠', `Path "pages/${relPath}" contains uppercase letters. Use lowercase to avoid routing issues on case-sensitive filesystems.`);
+              warnings += 1;
+              routingChecksPassed = false;
+            }
+
+            if (stats.isDirectory()) {
+              if (child === 'api' && relativeDir === '') {
+                scanRoutes(fullPath, relPath, true);
+              } else {
+                scanRoutes(fullPath, relPath, isApi);
+                if (!isApi) {
+                  kept.push({ name: child, isDir: true, original: child });
+                }
+              }
+            } else {
+              const ext = path.extname(child);
+              if (isApi) {
+                if (ext === '.js') {
+                  const base = path.basename(child, ext);
+                  kept.push({ name: base, isDir: false, original: child });
+                }
+              } else {
+                if (ext === '.njk') {
+                  const base = path.basename(child, ext);
+                  kept.push({ name: base, isDir: false, original: child });
+                }
+              }
+            }
+          }
+
+          // 2. Check dynamic route collisions
+          const groups = new Map();
+          for (const item of kept) {
+            const normalized = getGenericSegment(item.name);
+            if (!groups.has(normalized)) {
+              groups.set(normalized, []);
+            }
+            groups.get(normalized).push(item);
+          }
+
+          for (const [norm, items] of groups.entries()) {
+            if (items.length > 1) {
+              const namesList = items.map(item => `"${item.original}"`).join(' and ');
+              line('⚠', `Dynamic route collision in "pages/${relativeDir}": ${namesList} resolve to the same segment "${norm}" and will conflict at runtime.`);
+              warnings += 1;
+              routingChecksPassed = false;
+            }
+          }
+        }
+
+        scanRoutes(pagesPath, '');
+
+        if (routingChecksPassed) {
+          line('✓', 'All route paths are lowercase and free of dynamic collisions');
+        }
       } else {
         line('⚠', 'pages/ not found (file-based routes may be missing)');
         warnings += 1;

package/bin/commands/favicon-generate.js

@@ -5,7 +5,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const sharp = require('sharp');
+const sharp = process.env.NODE_ENV === 'test'
+  ? require('../../tests/mocks/sharp')
+  : require('sharp');
 
 const APPLE_SIZES = [57, 60, 72, 76, 114, 120, 144, 152, 180];
 const ANDROID_SIZE = 192;

package/bin/commands/skill.js

@@ -20,9 +20,10 @@ function validateSkillName(name) {
 }
 
 function skillDir(base, skillName) {
-  return path.join(base, '.cursor', 'skills', skillName);
+  return path.join(base, '.agents', 'skills', skillName);
 }
 
+
 function defaultDescription(skillName) {
   const label = skillName.replace(/-/g, ' ');
   return `Guides the agent through tasks for ${label}. Use when the user works on ${label} or asks about related workflows.`;
@@ -72,14 +73,15 @@ Example prompt or command
 function registerCommand(program) {
   program
     .command('skill [name]')
-    .description('Create an Agent Skill folder with SKILL.md (Cursor / AI tools)')
-    .option('-g, --global', 'Write to ~/.cursor/skills/ instead of ./.cursor/skills/')
+    .description('Create an Agent Skill folder with SKILL.md')
+    .option('-g, --global', 'Write to ~/.agents/skills/ instead of ./.agents/skills/')
     .option('-d, --description <text>', 'Skill description (for YAML frontmatter)')
     .option('-f, --force', 'Overwrite existing SKILL.md')
     .option(
       '-p, --preset <name>',
-      'Install bundled skill: webspresso → agent reference (SKILL.md + REFERENCE-*.md in .cursor/skills/webspresso-usage/)',
+      'Install bundled skill: webspresso → agent reference (SKILL.md + REFERENCE-*.md in .agents/skills/webspresso-usage/)',
     )
+
     .action(async (nameArg, options) => {
       const presetKey = options.preset ? String(options.preset).trim().toLowerCase() : '';
 

package/core/auth/hash.js

@@ -16,7 +16,7 @@ try {
  * Default bcrypt cost factor
  * Higher = more secure but slower
  */
-const DEFAULT_ROUNDS = 12;
+const DEFAULT_ROUNDS = process.env.NODE_ENV === 'test' ? 1 : 12;
 
 /**
  * Hash a password using bcrypt

package/core/auth/index.js

@@ -8,6 +8,12 @@ const { AuthManager, AuthenticationError, DEFAULT_CONFIG } = require('./manager'
 const { PolicyManager, AuthorizationError } = require('./policy');
 const { createAuthMiddleware, setupAuthMiddleware } = require('./middleware');
 const { hash, verify, needsRehash, generateToken, hashToken } = require('./hash');
+const {
+  TOKEN_TYPES,
+  createAuthTokensTable,
+  dropAuthTokensTable,
+  createKnexAuthTokensAdapter,
+} = require('./tokens');
 
 /**
  * Create authentication instance
@@ -75,6 +81,8 @@ function createAuth(config) {
  * @param {string} [options.passwordField='password'] - Password field
  * @param {Object} [options.session] - Session config
  * @param {boolean} [options.rememberMe=true] - Enable remember me
+ * @param {boolean} [options.authTokens=false] - Enable auth_tokens adapter (password reset / email verify)
+ * @param {string} [options.verifiedField='email_verified_at'] - Verified timestamp column
  * @returns {AuthManager}
  */
 function quickAuth(options) {
@@ -85,6 +93,8 @@ function quickAuth(options) {
     passwordField = 'password',
     session = {},
     rememberMe = true,
+    authTokens: enableAuthTokens = false,
+    verifiedField = 'email_verified_at',
   } = options;
 
   if (!db || typeof db.getRepository !== 'function') {
@@ -106,6 +116,18 @@ function quickAuth(options) {
       return null;
     },
 
+    findUserByIdentifier: async (identifier) => {
+      return await UserRepo.findOne({ [identifierField]: identifier });
+    },
+
+    updateUser: async (userId, data) => {
+      return await UserRepo.update(userId, data);
+    },
+
+    identifierField,
+    passwordField,
+    verifiedField,
+
     session: {
       secret: process.env.SESSION_SECRET || session.secret,
       ...session,
@@ -135,6 +157,10 @@ function quickAuth(options) {
     };
   }
 
+  if (enableAuthTokens) {
+    config.authTokens = createKnexAuthTokensAdapter(db);
+  }
+
   return createAuth(config);
 }
 
@@ -196,6 +222,10 @@ module.exports = {
   // Migration helpers
   createRememberTokensTable,
   dropRememberTokensTable,
+  createAuthTokensTable,
+  dropAuthTokensTable,
+  createKnexAuthTokensAdapter,
+  TOKEN_TYPES,
   
   // Config
   DEFAULT_CONFIG,

package/core/auth/manager.js

@@ -6,6 +6,13 @@
 
 const { generateToken, hashToken } = require('./hash');
 const { PolicyManager } = require('./policy');
+const {
+  TOKEN_TYPES,
+  createAuthToken,
+  verifyAuthToken,
+  consumeAuthToken,
+  hash: hashPassword,
+} = require('./tokens');
 
 /**
  * Authentication error
@@ -79,7 +86,18 @@ class AuthManager {
     
     this.findUserById = config.findUserById;
     this.findUserByCredentials = config.findUserByCredentials;
+    this.findUserByIdentifier = config.findUserByIdentifier || null;
     this.rememberTokens = config.rememberTokens || null;
+    this.authTokens = config.authTokens || null;
+    this.updateUser = config.updateUser || null;
+    this.identifierField = config.identifierField || 'email';
+    this.verifiedField = config.verifiedField || 'email_verified_at';
+    this.passwordField = config.passwordField || 'password';
+    this.notifications = {
+      passwordReset: config.notifications?.passwordReset || null,
+      emailVerification: config.notifications?.emailVerification || null,
+      welcome: config.notifications?.welcome || null,
+    };
     
     // Policy manager instance
     this.policies = new PolicyManager();
@@ -104,6 +122,14 @@ class AuthManager {
         }
       }
     }
+    if (config.authTokens) {
+      const required = ['create', 'find', 'delete', 'deleteAllForUser'];
+      for (const method of required) {
+        if (typeof config.authTokens[method] !== 'function') {
+          throw new Error(`authTokens.${method} function is required`);
+        }
+      }
+    }
   }
 
   /**
@@ -408,6 +434,170 @@ class AuthManager {
   beforePolicy(callback) {
     this.policies.before(callback);
   }
+
+  /**
+   * Find user by login identifier (email, username, …)
+   * @param {string} identifier
+   * @returns {Promise<Object|null>}
+   */
+  async resolveUserByIdentifier(identifier) {
+    if (typeof this.findUserByIdentifier === 'function') {
+      return this.findUserByIdentifier(identifier);
+    }
+    return null;
+  }
+
+  /**
+   * Request password reset — always resolves (no user enumeration)
+   * @param {string} identifier
+   * @param {Object} [options]
+   * @param {number} [options.tokenTtlMs=3600000]
+   * @param {Function} [options.buildResetUrl] - (rawToken) => string
+   * @returns {Promise<{ sent: boolean }>}
+   */
+  async requestPasswordReset(identifier, options = {}) {
+    if (!this.authTokens) {
+      throw new Error('authTokens adapter is required for password reset');
+    }
+
+    const user = await this.resolveUserByIdentifier(identifier);
+    if (!user) {
+      return { sent: false };
+    }
+
+    const tokenTtlMs = options.tokenTtlMs ?? 60 * 60 * 1000;
+    const { rawToken, expiresAt } = await createAuthToken(
+      this.authTokens,
+      TOKEN_TYPES.PASSWORD_RESET,
+      user.id,
+      tokenTtlMs
+    );
+
+    const resetUrl = typeof options.buildResetUrl === 'function'
+      ? options.buildResetUrl(rawToken)
+      : null;
+
+    if (typeof this.notifications.passwordReset === 'function') {
+      await this.notifications.passwordReset(user, {
+        token: rawToken,
+        expiresAt,
+        resetUrl,
+      });
+    }
+
+    return { sent: true };
+  }
+
+  /**
+   * Complete password reset with token
+   * @param {string} rawToken
+   * @param {string} newPassword
+   * @returns {Promise<{ ok: true }>}
+   */
+  async completePasswordReset(rawToken, newPassword) {
+    if (!this.authTokens) {
+      throw new Error('authTokens adapter is required for password reset');
+    }
+    if (!this.updateUser) {
+      throw new Error('updateUser function is required for password reset');
+    }
+
+    const verified = await verifyAuthToken(
+      this.authTokens,
+      TOKEN_TYPES.PASSWORD_RESET,
+      rawToken
+    );
+    if (!verified) {
+      throw new AuthenticationError('Invalid or expired reset token', 'INVALID_TOKEN');
+    }
+
+    const hashed = await hashPassword(newPassword);
+    await this.updateUser(verified.userId, { [this.passwordField]: hashed });
+    await consumeAuthToken(this.authTokens, verified.tokenHash);
+    await this.authTokens.deleteAllForUser(verified.userId, TOKEN_TYPES.PASSWORD_RESET);
+
+    return { ok: true };
+  }
+
+  /**
+   * Send email verification token
+   * @param {*} userId
+   * @param {Object} [options]
+   * @param {number} [options.tokenTtlMs=86400000]
+   * @param {Function} [options.buildVerifyUrl] - (rawToken) => string
+   * @returns {Promise<{ sent: boolean }>}
+   */
+  async requestEmailVerification(userId, options = {}) {
+    if (!this.authTokens) {
+      throw new Error('authTokens adapter is required for email verification');
+    }
+
+    const user = await this.findUserById(userId);
+    if (!user) {
+      return { sent: false };
+    }
+
+    const tokenTtlMs = options.tokenTtlMs ?? 24 * 60 * 60 * 1000;
+    const { rawToken, expiresAt } = await createAuthToken(
+      this.authTokens,
+      TOKEN_TYPES.EMAIL_VERIFY,
+      user.id,
+      tokenTtlMs
+    );
+
+    const verifyUrl = typeof options.buildVerifyUrl === 'function'
+      ? options.buildVerifyUrl(rawToken)
+      : null;
+
+    if (typeof this.notifications.emailVerification === 'function') {
+      await this.notifications.emailVerification(user, {
+        token: rawToken,
+        expiresAt,
+        verifyUrl,
+      });
+    }
+
+    return { sent: true };
+  }
+
+  /**
+   * Verify email with token
+   * @param {string} rawToken
+   * @returns {Promise<{ ok: true, userId: * }>}
+   */
+  async verifyEmail(rawToken) {
+    if (!this.authTokens) {
+      throw new Error('authTokens adapter is required for email verification');
+    }
+    if (!this.updateUser) {
+      throw new Error('updateUser function is required for email verification');
+    }
+
+    const verified = await verifyAuthToken(
+      this.authTokens,
+      TOKEN_TYPES.EMAIL_VERIFY,
+      rawToken
+    );
+    if (!verified) {
+      throw new AuthenticationError('Invalid or expired verification token', 'INVALID_TOKEN');
+    }
+
+    await this.updateUser(verified.userId, { [this.verifiedField]: new Date() });
+    await consumeAuthToken(this.authTokens, verified.tokenHash);
+
+    return { ok: true, userId: verified.userId };
+  }
+
+  /**
+   * Send welcome notification if configured
+   * @param {Object} user
+   * @returns {Promise<void>}
+   */
+  async sendWelcomeNotification(user) {
+    if (typeof this.notifications.welcome === 'function') {
+      await this.notifications.welcome(user, {});
+    }
+  }
 }
 
 module.exports = {