webspresso 0.0.80 → 0.0.81

package/README.md

@@ -982,6 +982,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 +2314,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/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 = {

package/core/auth/tokens.js

@@ -0,0 +1,135 @@
+/**
+ * Auth token types and helpers (password reset, email verification)
+ * @module core/auth/tokens
+ */
+
+const { generateToken, hashToken, hash } = require('./hash');
+
+const TOKEN_TYPES = {
+  PASSWORD_RESET: 'password_reset',
+  EMAIL_VERIFY: 'email_verify',
+};
+
+/**
+ * @param {import('knex').Knex} knex
+ * @returns {Promise<void>}
+ */
+async function createAuthTokensTable(knex) {
+  const exists = await knex.schema.hasTable('auth_tokens');
+  if (exists) return;
+
+  await knex.schema.createTable('auth_tokens', (table) => {
+    table.bigIncrements('id').primary();
+    table.bigInteger('user_id').unsigned().notNullable();
+    table.string('token', 64).notNullable().unique();
+    table.string('type', 32).notNullable();
+    table.timestamp('expires_at').notNullable();
+    table.timestamp('created_at').defaultTo(knex.fn.now());
+
+    table.index(['user_id', 'type']);
+    table.index('token');
+    table.index('expires_at');
+  });
+}
+
+/**
+ * @param {import('knex').Knex} knex
+ * @returns {Promise<void>}
+ */
+async function dropAuthTokensTable(knex) {
+  await knex.schema.dropTableIfExists('auth_tokens');
+}
+
+/**
+ * Create Knex auth_tokens adapter
+ * @param {Object} db - Database with knex
+ * @returns {Object}
+ */
+function createKnexAuthTokensAdapter(db) {
+  const knex = db.knex || db;
+
+  return {
+    create: async (userId, tokenHash, type, expiresAt) => {
+      await knex('auth_tokens').insert({
+        user_id: userId,
+        token: tokenHash,
+        type,
+        expires_at: expiresAt,
+        created_at: new Date(),
+      });
+    },
+    find: async (tokenHash, type) => {
+      return knex('auth_tokens').where({ token: tokenHash, type }).first();
+    },
+    delete: async (tokenHash) => {
+      await knex('auth_tokens').where({ token: tokenHash }).delete();
+    },
+    deleteAllForUser: async (userId, type) => {
+      const q = knex('auth_tokens').where({ user_id: userId });
+      if (type) q.where({ type });
+      await q.delete();
+    },
+  };
+}
+
+/**
+ * @param {Object} authTokensAdapter
+ * @param {string} type
+ * @param {*} userId
+ * @param {number} ttlMs
+ * @returns {Promise<{ rawToken: string, expiresAt: Date }>}
+ */
+async function createAuthToken(authTokensAdapter, type, userId, ttlMs) {
+  const rawToken = generateToken(32);
+  const tokenHash = hashToken(rawToken);
+  const expiresAt = new Date(Date.now() + ttlMs);
+
+  await authTokensAdapter.deleteAllForUser(userId, type);
+  await authTokensAdapter.create(userId, tokenHash, type, expiresAt);
+
+  return { rawToken, expiresAt };
+}
+
+/**
+ * @param {Object} authTokensAdapter
+ * @param {string} type
+ * @param {string} rawToken
+ * @returns {Promise<{ userId: *, expiresAt: Date }|null>}
+ */
+async function verifyAuthToken(authTokensAdapter, type, rawToken) {
+  if (!rawToken) return null;
+
+  const tokenHash = hashToken(rawToken);
+  const record = await authTokensAdapter.find(tokenHash, type);
+  if (!record) return null;
+
+  if (new Date(record.expires_at) < new Date()) {
+    await authTokensAdapter.delete(tokenHash);
+    return null;
+  }
+
+  return {
+    userId: record.user_id,
+    expiresAt: new Date(record.expires_at),
+    tokenHash,
+  };
+}
+
+/**
+ * @param {Object} authTokensAdapter
+ * @param {string} tokenHash
+ */
+async function consumeAuthToken(authTokensAdapter, tokenHash) {
+  await authTokensAdapter.delete(tokenHash);
+}
+
+module.exports = {
+  TOKEN_TYPES,
+  createAuthTokensTable,
+  dropAuthTokensTable,
+  createKnexAuthTokensAdapter,
+  createAuthToken,
+  verifyAuthToken,
+  consumeAuthToken,
+  hash,
+};

package/core/kernel/app.js

@@ -50,7 +50,13 @@ function createApp(options = {}) {
       }
     };
     events.on(flowDef.trigger, handler);
-    const unregister = () => events.off(flowDef.trigger, handler);
+    const unregister = () => {
+      events.off(flowDef.trigger, handler);
+      const idx = flowHandles.findIndex((h) => h.unregister === unregister);
+      if (idx !== -1) {
+        flowHandles.splice(idx, 1);
+      }
+    };
     flowHandles.push({
       id,
       trigger: flowDef.trigger,

package/index.d.ts

@@ -74,6 +74,15 @@ export interface CreateAppResult {
 
 export function createApp(options?: CreateAppOptions): CreateAppResult;
 
+export function resolveClientRuntime(options?: {
+  clientRuntime?: {
+    alpine?: boolean | Record<string, unknown>;
+    swup?: boolean | Record<string, unknown>;
+  };
+}): { alpine: boolean; swup: boolean };
+
+export const CLIENT_RUNTIME_BASE: string;
+
 // --- App context ---
 
 export function attachDbMiddleware(req: Request, res: Response, next: NextFunction): void;
@@ -595,6 +604,29 @@ export interface RateLimitPluginOptions {
 
 export function rateLimitPlugin(options?: RateLimitPluginOptions): WebspressoPlugin;
 
+export interface CsrfCookieOptions {
+  key?: string;
+  signed?: boolean;
+  path?: string;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'lax' | 'strict' | 'none';
+  maxAge?: number;
+  [key: string]: unknown;
+}
+
+export interface CsrfPluginOptions {
+  cookie?: boolean | CsrfCookieOptions;
+  sessionKey?: string;
+  methods?: string[];
+  ignorePaths?: Array<string | RegExp | ((req: Request) => boolean)>;
+  global?: boolean;
+  errorMessage?: string;
+  errorStatus?: number;
+}
+
+export function csrfPlugin(options?: CsrfPluginOptions): WebspressoPlugin;
+
 export interface ContentPluginOptions {
   db: import('./index').Database;
   adminPath?: string;