webspresso 0.0.84 → 0.0.85

package/README.md

@@ -1316,6 +1316,86 @@ createApp({
 });
 ```
 
+### Authentication & JWT Support (`quickAuth`)
+
+Webspresso provides a zero-dependency **Dual Authentication** system (`webspresso/core/auth`):
+- **Session + Cookie**: Stateful auth for browser SSR routes and Admin Panel (`/`, `/_admin`).
+- **JWT + Refresh Token**: Stateless HS256 auth for REST APIs, Mobile Apps, and SPAs (`/api/*`).
+
+```javascript
+// createApp setup with quickAuth
+const { quickAuth } = require('webspresso/core/auth');
+
+const auth = quickAuth({
+  db,
+  userModel: 'User',
+  jwt: {
+    expiresIn: '15m',        // Access token duration (default: 24h)
+    refreshExpiresIn: '30d', // Refresh token duration (default: 30d)
+  },
+});
+
+createApp({
+  pagesDir: './pages',
+  db,
+  auth,
+});
+```
+
+**File-Based API Route Examples (`pages/api/*`):**
+
+```javascript
+// 1. pages/api/auth/login.post.js (Login & Token Generation)
+module.exports = {
+  schema: ({ z }) => ({
+    body: z.object({
+      email: z.string().email(),
+      password: z.string().min(1),
+    }),
+  }),
+  async handler(req, res) {
+    const { email, password } = req.input.body;
+    const user = await req.auth.attempt(email, password);
+    if (!user) return res.status(401).json({ error: 'Invalid credentials' });
+
+    const accessToken = req.auth.generateUserToken(user);
+    const refreshToken = req.auth.generateRefreshToken(user);
+
+    return res.json({ accessToken, refreshToken, user: { id: user.id, email: user.email } });
+  },
+};
+```
+
+```javascript
+// 2. pages/api/auth/refresh.post.js (Token Rotation Endpoint)
+module.exports = {
+  schema: ({ z }) => ({
+    body: z.object({
+      refreshToken: z.string(),
+    }),
+  }),
+  async handler(req, res) {
+    const { refreshToken } = req.input.body;
+    try {
+      const result = await req.auth.refreshAccessToken(refreshToken, { rotate: true });
+      return res.json({ accessToken: result.accessToken, refreshToken: result.refreshToken });
+    } catch (err) {
+      return res.status(401).json({ error: err.message });
+    }
+  },
+};
+```
+
+```javascript
+// 3. pages/api/profile.get.js (Protected REST API Route)
+module.exports = {
+  middleware: ['jwt'],
+  async handler(req, res) {
+    return res.json({ user: req.user, token: req.token });
+  },
+};
+```
+
 **With Schema Validation (same object shape):**
 
 ```javascript

package/bin/commands/orm-map.js

@@ -54,7 +54,7 @@ function openFile(filePath, cwd) {
   if (process.platform === 'darwin') {
     execFileSync('open', [fp], { stdio: 'ignore' });
   } else if (process.platform === 'win32') {
-    execFileSync('cmd', ['/c', 'start', '', fp], { stdio: 'ignore' });
+    execFileSync('explorer.exe', [fp.replace(/\//g, '\\')], { stdio: 'ignore' });
   } else {
     execFileSync('xdg-open', [fp], { stdio: 'ignore' });
   }

package/core/auth/index.js

@@ -8,6 +8,7 @@ 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 { signJwt, verifyJwt, decodeJwt } = require('./jwt');
 const {
   TOKEN_TYPES,
   createAuthTokensTable,
@@ -23,50 +24,9 @@ const {
  * @param {Object} [config.rememberTokens] - Remember token adapter
  * @param {Object} [config.session] - Session configuration
  * @param {Object} [config.rememberMe] - Remember me configuration
+ * @param {Object|boolean} [config.jwt] - JWT configuration
  * @param {Object} [config.routes] - Route configuration
  * @returns {AuthManager}
- * 
- * @example
- * const auth = createAuth({
- *   findUserById: async (id) => {
- *     return await UserRepo.findById(id);
- *   },
- *   
- *   findUserByCredentials: async (email, password) => {
- *     const user = await UserRepo.findOne({ email });
- *     if (user && await verify(password, user.password)) {
- *       return user;
- *     }
- *     return null;
- *   },
- *   
- *   // Optional: Remember me tokens
- *   rememberTokens: {
- *     create: async (userId, token, expiresAt) => {
- *       await db.knex('remember_tokens').insert({
- *         user_id: userId,
- *         token,
- *         expires_at: expiresAt,
- *       });
- *     },
- *     find: async (token) => {
- *       return await db.knex('remember_tokens').where({ token }).first();
- *     },
- *     delete: async (token) => {
- *       await db.knex('remember_tokens').where({ token }).delete();
- *     },
- *     deleteAllForUser: async (userId) => {
- *       await db.knex('remember_tokens').where({ user_id: userId }).delete();
- *     },
- *   },
- *   
- *   session: {
- *     secret: process.env.SESSION_SECRET,
- *     cookie: {
- *       maxAge: 24 * 60 * 60 * 1000, // 1 day
- *     },
- *   },
- * });
  */
 function createAuth(config) {
   return new AuthManager(config);
@@ -82,6 +42,7 @@ function createAuth(config) {
  * @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 {Object|boolean} [options.jwt=false] - Enable JWT support or JWT config
  * @param {string} [options.verifiedField='email_verified_at'] - Verified timestamp column
  * @returns {AuthManager}
  */
@@ -94,6 +55,7 @@ function quickAuth(options) {
     session = {},
     rememberMe = true,
     authTokens: enableAuthTokens = false,
+    jwt = false,
     verifiedField = 'email_verified_at',
   } = options;
 
@@ -127,6 +89,7 @@ function quickAuth(options) {
     identifierField,
     passwordField,
     verifiedField,
+    jwt,
 
     session: {
       secret: process.env.SESSION_SECRET || session.secret,
@@ -218,6 +181,11 @@ module.exports = {
   needsRehash,
   generateToken,
   hashToken,
+
+  // JWT utilities
+  signJwt,
+  verifyJwt,
+  decodeJwt,
   
   // Migration helpers
   createRememberTokensTable,

package/core/auth/jwt.js

@@ -0,0 +1,235 @@
+/**
+ * Webspresso Auth - Zero-dependency JWT implementation
+ * Uses Node.js native crypto module for HS256 HMAC-SHA256 signatures
+ * @module core/auth/jwt
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Base64URL encode string or Buffer
+ * @param {string|Buffer} input
+ * @returns {string}
+ */
+function base64UrlEncode(input) {
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input, 'utf8');
+  return buf
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+}
+
+/**
+ * Base64URL decode string
+ * @param {string} input
+ * @returns {string}
+ */
+function base64UrlDecode(input) {
+  let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+  while (base64.length % 4 !== 0) {
+    base64 += '=';
+  }
+  return Buffer.from(base64, 'base64').toString('utf8');
+}
+
+/**
+ * Parse duration string (e.g. '1h', '7d', '15m', '3600') into seconds
+ * @param {string|number} duration
+ * @returns {number} Seconds
+ */
+function parseDuration(duration) {
+  if (typeof duration === 'number') {
+    return duration;
+  }
+  if (typeof duration !== 'string') {
+    return 3600; // Default 1 hour
+  }
+
+  const match = duration.trim().match(/^(\d+)\s*([smhd])?$/i);
+  if (!match) {
+    const parsed = parseInt(duration, 10);
+    return isNaN(parsed) ? 3600 : parsed;
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = (match[2] || 's').toLowerCase();
+
+  switch (unit) {
+    case 's': return value;
+    case 'm': return value * 60;
+    case 'h': return value * 3600;
+    case 'd': return value * 86400;
+    default: return value;
+  }
+}
+
+/**
+ * Sign payload to create HS256 JWT string
+ * @param {Object} payload - Payload object
+ * @param {string} secret - Secret key for signing
+ * @param {Object} [options] - Signing options
+ * @param {string|number} [options.expiresIn='24h'] - Expiration time (seconds or '1h', '7d', etc.)
+ * @param {string} [options.algorithm='HS256'] - Signature algorithm (HS256 supported)
+ * @param {string} [options.issuer] - Token issuer (iss)
+ * @param {string} [options.subject] - Token subject (sub)
+ * @param {string} [options.audience] - Token audience (aud)
+ * @returns {string} JWT string
+ */
+function signJwt(payload, secret, options = {}) {
+  if (!secret) {
+    throw new Error('Secret is required to sign JWT');
+  }
+
+  const algorithm = options.algorithm || 'HS256';
+  if (algorithm !== 'HS256') {
+    throw new Error(`Unsupported algorithm '${algorithm}'. Only HS256 is supported.`);
+  }
+
+  const header = {
+    alg: algorithm,
+    typ: 'JWT',
+  };
+
+  const nowSec = Math.floor(Date.now() / 1000);
+  const claims = {
+    iat: nowSec,
+  };
+
+  if (options.expiresIn !== false) {
+    const ttlSec = parseDuration(options.expiresIn ?? '24h');
+    claims.exp = nowSec + ttlSec;
+  }
+
+  if (options.issuer) claims.iss = options.issuer;
+  if (options.subject) claims.sub = options.subject;
+  if (options.audience) claims.aud = options.audience;
+
+  const fullPayload = {
+    ...claims,
+    ...payload,
+  };
+
+  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedPayload = base64UrlEncode(JSON.stringify(fullPayload));
+
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const signature = crypto
+    .createHmac('sha256', secret)
+    .update(signingInput)
+    .digest();
+
+  const encodedSignature = base64UrlEncode(signature);
+
+  return `${signingInput}.${encodedSignature}`;
+}
+
+/**
+ * Verify and decode HS256 JWT string
+ * @param {string} token - JWT string
+ * @param {string} secret - Secret key
+ * @param {Object} [options] - Verification options
+ * @param {boolean} [options.ignoreExpiration=false] - Ignore token expiration
+ * @param {string} [options.issuer] - Expected issuer
+ * @param {string} [options.audience] - Expected audience
+ * @returns {Object} Decoded payload
+ * @throws {Error} If token is invalid or expired
+ */
+function verifyJwt(token, secret, options = {}) {
+  if (!secret) {
+    throw new Error('Secret is required to verify JWT');
+  }
+
+  if (!token || typeof token !== 'string') {
+    throw new Error('JWT token must be a non-empty string');
+  }
+
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    throw new Error('Invalid JWT format');
+  }
+
+  const [encodedHeader, encodedPayload, encodedSignature] = parts;
+
+  let header;
+  let payload;
+
+  try {
+    header = JSON.parse(base64UrlDecode(encodedHeader));
+  } catch (e) {
+    throw new Error('Invalid JWT header JSON');
+  }
+
+  try {
+    payload = JSON.parse(base64UrlDecode(encodedPayload));
+  } catch (e) {
+    throw new Error('Invalid JWT payload JSON');
+  }
+
+  if (header.alg !== 'HS256') {
+    throw new Error(`Unsupported algorithm '${header.alg}' in JWT header`);
+  }
+
+  // Re-compute signature
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const expectedSignatureBuf = crypto
+    .createHmac('sha256', secret)
+    .update(signingInput)
+    .digest();
+
+  const actualSignatureBuf = Buffer.from(encodedSignature.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+
+  if (
+    expectedSignatureBuf.length !== actualSignatureBuf.length ||
+    !crypto.timingSafeEqual(expectedSignatureBuf, actualSignatureBuf)
+  ) {
+    throw new Error('Invalid JWT signature');
+  }
+
+  // Check claims
+  const nowSec = Math.floor(Date.now() / 1000);
+
+  if (!options.ignoreExpiration && typeof payload.exp === 'number') {
+    if (nowSec >= payload.exp) {
+      throw new Error('JWT token has expired');
+    }
+  }
+
+  if (options.issuer && payload.iss !== options.issuer) {
+    throw new Error(`Invalid JWT issuer (expected ${options.issuer}, got ${payload.iss})`);
+  }
+
+  if (options.audience && payload.aud !== options.audience) {
+    throw new Error(`Invalid JWT audience (expected ${options.audience}, got ${payload.aud})`);
+  }
+
+  return payload;
+}
+
+/**
+ * Decode JWT without verifying signature
+ * @param {string} token
+ * @returns {{ header: Object, payload: Object }|null}
+ */
+function decodeJwt(token) {
+  if (!token || typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+
+  try {
+    const header = JSON.parse(base64UrlDecode(parts[0]));
+    const payload = JSON.parse(base64UrlDecode(parts[1]));
+    return { header, payload };
+  } catch (e) {
+    return null;
+  }
+}
+
+module.exports = {
+  signJwt,
+  verifyJwt,
+  decodeJwt,
+  base64UrlEncode,
+  base64UrlDecode,
+  parseDuration,
+};

package/core/auth/manager.js

@@ -6,6 +6,7 @@
 
 const { generateToken, hashToken } = require('./hash');
 const { PolicyManager } = require('./policy');
+const { signJwt, verifyJwt, decodeJwt } = require('./jwt');
 const {
   TOKEN_TYPES,
   createAuthToken,
@@ -47,6 +48,13 @@ const DEFAULT_CONFIG = {
     cookieName: 'remember_token',
     maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
   },
+  jwt: {
+    enabled: false,
+    secret: null,
+    refreshSecret: null,
+    expiresIn: '24h',
+    refreshExpiresIn: '30d',
+  },
   routes: {
     login: '/login',
     logout: '/logout',
@@ -98,6 +106,30 @@ class AuthManager {
       emailVerification: config.notifications?.emailVerification || null,
       welcome: config.notifications?.welcome || null,
     };
+
+    if (config.jwt) {
+      const jwtSecret = typeof config.jwt === 'object' && config.jwt.secret
+        ? config.jwt.secret
+        : (config.session?.secret || process.env.JWT_SECRET || process.env.AUTH_SESSION_SECRET || 'webspresso-jwt-secret');
+      const refreshSecret = typeof config.jwt === 'object' && config.jwt.refreshSecret
+        ? config.jwt.refreshSecret
+        : (process.env.JWT_REFRESH_SECRET || jwtSecret);
+      const expiresIn = typeof config.jwt === 'object' && config.jwt.expiresIn
+        ? config.jwt.expiresIn
+        : '24h';
+      const refreshExpiresIn = typeof config.jwt === 'object' && config.jwt.refreshExpiresIn
+        ? config.jwt.refreshExpiresIn
+        : '30d';
+      this.jwt = {
+        enabled: true,
+        secret: jwtSecret,
+        refreshSecret,
+        expiresIn,
+        refreshExpiresIn,
+      };
+    } else {
+      this.jwt = null;
+    }
     
     // Policy manager instance
     this.policies = new PolicyManager();
@@ -144,6 +176,8 @@ class AuthManager {
     }
 
     const mergedCookie = {
+      httpOnly: true,
+      sameSite: 'lax',
       ...DEFAULT_CONFIG.session.cookie,
       ...(config.cookie || {}),
     };
@@ -170,6 +204,42 @@ class AuthManager {
     const self = this;
     
     return {
+      manager: self,
+
+      /**
+       * Generate JWT access token for user
+       */
+      generateUserToken(user, options) {
+        return self.generateUserToken(user, options);
+      },
+
+      /**
+       * Generate JWT refresh token for user
+       */
+      generateRefreshToken(user, options) {
+        return self.generateRefreshToken(user, options);
+      },
+
+      /**
+       * Refresh access token using refresh token
+       */
+      async refreshAccessToken(refreshToken, options) {
+        return await self.refreshAccessToken(refreshToken, options);
+      },
+
+      /**
+       * Create JWT payload
+       */
+      createJwt(payload, options) {
+        return self.createJwt(payload, options);
+      },
+
+      /**
+       * Verify JWT token
+       */
+      verifyJwt(token, options) {
+        return self.verifyJwt(token, options);
+      },
       /**
        * Attempt login with credentials
        * @param {string} identifier - Email or username
@@ -598,6 +668,129 @@ class AuthManager {
       await this.notifications.welcome(user, {});
     }
   }
+
+  /**
+   * Create JWT token
+   * @param {Object} payload
+   * @param {Object} [options]
+   * @returns {string} JWT string
+   */
+  createJwt(payload, options = {}) {
+    const secret = options.secret || this.jwt?.secret || this.config.session?.secret || process.env.JWT_SECRET;
+    if (!secret) {
+      throw new Error('JWT secret is missing');
+    }
+    const expiresIn = options.expiresIn || this.jwt?.expiresIn || '24h';
+    return signJwt(payload, secret, { expiresIn, ...options });
+  }
+
+  /**
+   * Verify JWT token
+   * @param {string} token
+   * @param {Object} [options]
+   * @returns {Object} Decoded payload
+   */
+  verifyJwt(token, options = {}) {
+    const secret = options.secret || this.jwt?.secret || this.config.session?.secret || process.env.JWT_SECRET;
+    if (!secret) {
+      throw new Error('JWT secret is missing');
+    }
+    const payload = verifyJwt(token, secret, options);
+    if (options.isAccess !== false && payload.type === 'refresh') {
+      throw new Error('Refresh token cannot be used as an access token');
+    }
+    return payload;
+  }
+
+  /**
+   * Generate JWT token for user
+   * @param {Object} user
+   * @param {Object} [options]
+   * @returns {string} JWT string
+   */
+  generateUserToken(user, options = {}) {
+    if (!user || !user.id) {
+      throw new Error('User object with id is required');
+    }
+    const payload = {
+      id: user.id,
+      type: 'access',
+      [this.identifierField]: user[this.identifierField],
+      ...options.payload,
+    };
+    return this.createJwt(payload, options);
+  }
+
+  /**
+   * Generate JWT Refresh token for user
+   * @param {Object} user
+   * @param {Object} [options]
+   * @returns {string} Refresh token string
+   */
+  generateRefreshToken(user, options = {}) {
+    if (!user || !user.id) {
+      throw new Error('User object with id is required');
+    }
+    const secret = options.secret || this.jwt?.refreshSecret || this.jwt?.secret || this.config.session?.secret || process.env.JWT_REFRESH_SECRET || process.env.JWT_SECRET;
+    if (!secret) {
+      throw new Error('JWT refresh secret is missing');
+    }
+    const expiresIn = options.expiresIn || this.jwt?.refreshExpiresIn || '30d';
+    const payload = {
+      id: user.id,
+      type: 'refresh',
+      jti: generateToken(16),
+      [this.identifierField]: user[this.identifierField],
+      ...options.payload,
+    };
+    return signJwt(payload, secret, { expiresIn, ...options });
+  }
+
+  /**
+   * Refresh access token using valid refresh token
+   * @param {string} refreshToken
+   * @param {Object} [options]
+   * @returns {Promise<{ accessToken: string, refreshToken: string, user: Object }>}
+   */
+  async refreshAccessToken(refreshToken, options = {}) {
+    const secret = options.secret || this.jwt?.refreshSecret || this.jwt?.secret || this.config.session?.secret || process.env.JWT_REFRESH_SECRET || process.env.JWT_SECRET;
+    if (!secret) {
+      throw new Error('JWT refresh secret is missing');
+    }
+
+    const payload = verifyJwt(refreshToken, secret, options);
+    if (payload.type !== 'refresh') {
+      throw new AuthenticationError('Invalid refresh token type', 'INVALID_REFRESH_TOKEN');
+    }
+
+    const user = await this.findUserById(payload.id);
+    if (!user) {
+      throw new AuthenticationError('User not found for refresh token', 'USER_NOT_FOUND');
+    }
+
+    const accessToken = this.generateUserToken(user, options.accessOptions);
+    const rotate = options.rotate ?? true;
+    const newRefreshToken = rotate ? this.generateRefreshToken(user, options.refreshOptions) : refreshToken;
+
+    return {
+      accessToken,
+      refreshToken: newRefreshToken,
+      user,
+    };
+  }
+
+  /**
+   * Get requireJwt guard middleware for Express routes
+   * @param {Object} [options]
+   * @returns {Function} Express middleware
+   */
+  requireJwt(options = {}) {
+    if (!this._authMiddleware) {
+      const { createAuthMiddleware } = require('./middleware');
+      this._authMiddleware = createAuthMiddleware(this);
+    }
+    return this._authMiddleware.requireJwt(options);
+  }
 }
 
 module.exports = {

package/core/auth/middleware.js

@@ -28,7 +28,7 @@ function createAuthMiddleware(authManager) {
 
   /**
    * Authenticate middleware
-   * Loads user from session or remember me token
+   * Loads user from Bearer JWT header, session, or remember me token
    * Should run on every request
    */
   async function authenticate(req, res, next) {
@@ -39,8 +39,27 @@ function createAuthMiddleware(authManager) {
       // Create request-bound auth helper
       req.auth = authManager.createRequestAuth(req, res);
 
-      // Try to load user from session
-      if (req.session?.userId) {
+      // Check Bearer JWT token header first
+      const authHeader = req.headers?.authorization || req.headers?.Authorization;
+      if (authHeader && authHeader.startsWith('Bearer ')) {
+        const token = authHeader.substring(7).trim();
+        try {
+          const payload = authManager.verifyJwt(token);
+          req.token = token;
+          req.jwtPayload = payload;
+          if (payload.id) {
+            const user = await authManager.findUserById(payload.id);
+            req.user = user || payload;
+          } else {
+            req.user = payload;
+          }
+        } catch (jwtErr) {
+          // Invalid or expired JWT token header
+        }
+      }
+
+      // Try to load user from session if not authenticated by JWT
+      if (!req.user && req.session?.userId) {
         const user = await authManager.findUserById(req.session.userId);
         if (user) {
           req.user = user;
@@ -50,7 +69,7 @@ function createAuthMiddleware(authManager) {
         }
       }
 
-      // If no user in session, try remember me token
+      // If no user in session or JWT, try remember me token
       if (!req.user && authManager.rememberTokens) {
         const user = await authManager.verifyRememberToken(req, res);
         if (user) {
@@ -96,6 +115,44 @@ function createAuthMiddleware(authManager) {
     };
   }
 
+  /**
+   * Require JWT middleware
+   * Enforces valid Bearer JWT token in Authorization header
+   * @param {Object} [options] - Verification options
+   */
+  function requireJwt(options = {}) {
+    return async (req, res, next) => {
+      const authHeader = req.headers?.authorization || req.headers?.Authorization;
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Bearer token required',
+        });
+      }
+
+      const token = authHeader.substring(7).trim();
+      try {
+        const payload = authManager.verifyJwt(token, options);
+        req.token = token;
+        req.jwtPayload = payload;
+
+        if (payload.id) {
+          const user = await authManager.findUserById(payload.id);
+          req.user = user || payload;
+        } else {
+          req.user = payload;
+        }
+
+        next();
+      } catch (err) {
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: err.message || 'Invalid JWT token',
+        });
+      }
+    };
+  }
+
   /**
    * Require guest middleware
    * Redirects authenticated users away
@@ -192,6 +249,9 @@ function createAuthMiddleware(authManager) {
       case 'auth':
         return requireAuth({ api: args.includes('api') });
       
+      case 'jwt':
+        return requireJwt();
+      
       case 'guest':
         return requireGuest();
       
@@ -216,6 +276,7 @@ function createAuthMiddleware(authManager) {
     
     // Guard middleware
     requireAuth,
+    requireJwt,
     requireGuest,
     requireCan,
     requireVerified,
@@ -225,6 +286,7 @@ function createAuthMiddleware(authManager) {
     
     // Aliases for route config (factories — file-router calls requireAuth(opts) / requireGuest(opts))
     auth: requireAuth,
+    jwt: requireJwt,
     guest: requireGuest,
   };
 }

package/index.d.ts

@@ -567,6 +567,28 @@ export function swaggerPlugin(options?: Record<string, unknown>): WebspressoPlug
 
 export function healthCheckPlugin(options?: Record<string, unknown>): WebspressoPlugin;
 
+export interface CorsPluginOptions {
+  origin?:
+    | string
+    | string[]
+    | RegExp
+    | ((
+        origin: string,
+        callback: (err: Error | null, allow?: boolean | string) => void
+      ) => void);
+  methods?: string | string[];
+  allowedHeaders?: string | string[];
+  exposedHeaders?: string | string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+  optionsSuccessStatus?: number;
+  routes?: string | string[] | boolean;
+  global?: boolean;
+}
+
+export function corsPlugin(options?: CorsPluginOptions): WebspressoPlugin;
+
 export interface RedirectRule {
   from: string | RegExp;
   to: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.84",
+  "version": "0.0.85",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",
@@ -72,7 +72,7 @@
     "nodemailer": "^9.0.3",
     "nunjucks": "^3.2.4",
     "sanitize-html": "^2.17.3",
-    "sharp": "^0.33.5",
+    "sharp": "^0.35.3",
     "swup": "^4.8.3",
     "yaml": "^2.8.3",
     "zod": "^3.23.0",
@@ -116,7 +116,7 @@
     "chokidar": "^3.5.3",
     "dotenv": "^16.3.1",
     "express-rate-limit": "^8.4.1",
-    "release-it": "^19.0.0",
+    "release-it": "^20.2.1",
     "supertest": "^6.3.4",
     "typescript": "~5.6.3",
     "vitest": "^3.0.0"

package/plugins/admin-panel/index.js

@@ -71,10 +71,15 @@ function adminPanelPlugin(options = {}) {
     version: '2.0.0',
     description: 'Modular admin panel for Webspresso with extensions support',
     
-    // CSP requirements for admin panel scripts
+    // CSP requirements for admin panel scripts, styles, and custom page iframe sources
     // Note: cdn.quilljs.com 301-redirects to cdn.jsdelivr.net; CSP is enforced on the final URL.
     csp: {
-      styleSrc: ['https://cdn.quilljs.com', 'https://cdn.jsdelivr.net'],
+      styleSrc: [
+        'https://cdn.quilljs.com',
+        'https://cdn.jsdelivr.net',
+        'https://unpkg.com',
+        'https://cdn.tailwindcss.com',
+      ],
       scriptSrc: [
         'https://cdn.quilljs.com',
         'https://cdn.jsdelivr.net',
@@ -82,6 +87,7 @@ function adminPanelPlugin(options = {}) {
         'https://cdn.tailwindcss.com',
       ],
       connectSrc: ['https://unpkg.com', 'https://cdn.tailwindcss.com', 'https://cdn.jsdelivr.net'],
+      frameSrc: ["'self'", 'data:', 'blob:', 'https:'],
     },
     enabled,
     registry, // Expose registry for external configuration
@@ -281,7 +287,7 @@ function adminPanelPlugin(options = {}) {
 
       // Custom pages API routes
       ctx.addRoute('get', `${adminPath}/api/extensions/pages/:pageId/data`, requireAuth, pageHandlers.getPageData);
-      ctx.addRoute('post', `${adminPath}/api/extensions/pages/:pageId/actions/:actionId`, requireAuth, pageHandlers.executePageAction);
+      ctx.addRoute('all', `${adminPath}/api/extensions/pages/:pageId/actions/:actionId`, requireAuth, pageHandlers.executePageAction);
 
       // User management API routes
       if (userHandlers) {

package/plugins/admin-panel/modules/custom-pages.js

@@ -128,7 +128,15 @@ function createCustomPageApiHandlers(options) {
         return res.status(404).json({ error: 'Action not found' });
       }
 
-      const result = await action({ db, req, body: req.body, user: req.session?.adminUser });
+      const payload = { ...(req.query || {}), ...(req.body || {}) };
+      const result = await action({
+        db,
+        req,
+        body: payload,
+        payload,
+        query: req.query || {},
+        user: req.session?.adminUser,
+      });
       res.json({ success: true, result });
     } catch (error) {
       res.status(500).json({ error: error.message });

package/plugins/content/client/inline-edit.js

@@ -243,6 +243,38 @@
       });
   }
 
+  function sanitizeClientHtml(htmlStr) {
+    if (!htmlStr) return '';
+    try {
+      var parser = new DOMParser();
+      var doc = parser.parseFromString(htmlStr, 'text/html');
+      var forbiddenTags = ['script', 'iframe', 'object', 'embed', 'applet', 'base'];
+      forbiddenTags.forEach(function (tag) {
+        var nodes = doc.querySelectorAll(tag);
+        for (var i = 0; i < nodes.length; i++) {
+          nodes[i].parentNode.removeChild(nodes[i]);
+        }
+      });
+      var allNodes = doc.querySelectorAll('*');
+      for (var i = 0; i < allNodes.length; i++) {
+        var node = allNodes[i];
+        var attrs = Array.prototype.slice.call(node.attributes);
+        for (var j = 0; j < attrs.length; j++) {
+          var attrName = attrs[j].name.toLowerCase();
+          var attrVal = attrs[j].value.toLowerCase().trim();
+          if (attrName.indexOf('on') === 0) {
+            node.removeAttribute(attrs[j].name);
+          } else if ((attrName === 'href' || attrName === 'src') && attrVal.indexOf('javascript:') === 0) {
+            node.removeAttribute(attrs[j].name);
+          }
+        }
+      }
+      return doc.body.innerHTML;
+    } catch (e) {
+      return '';
+    }
+  }
+
   function updateDomFields(entryId, data) {
     qsa('[data-ws-content-entry="' + entryId + '"][data-ws-content-field]').forEach(function (el) {
       var field = el.getAttribute('data-ws-content-field');
@@ -250,7 +282,7 @@
       var val = data[field];
       var isHtml = el.getAttribute('data-ws-content-html') === 'true';
       if (isHtml) {
-        el.innerHTML = val || '';
+        el.innerHTML = sanitizeClientHtml(val);
       } else {
         el.textContent = val != null ? val : '';
       }

package/plugins/cors.js

@@ -0,0 +1,171 @@
+/**
+ * Webspresso CORS Plugin
+ * Zero-dependency CORS middleware & preflight handler
+ * @module plugins/cors
+ */
+
+/**
+ * Configure CORS middleware
+ * @param {Object} [options] - CORS configuration
+ * @param {string|string[]|RegExp|Function} [options.origin='*'] - Allowed origin(s)
+ * @param {string|string[]} [options.methods] - Allowed HTTP methods
+ * @param {string|string[]} [options.allowedHeaders] - Allowed request headers
+ * @param {string|string[]} [options.exposedHeaders] - Headers exposed to response
+ * @param {boolean} [options.credentials=false] - Allow credentials (cookies/authorization headers)
+ * @param {number} [options.maxAge=86400] - Access-Control-Max-Age header in seconds
+ * @param {boolean} [options.preflightContinue=false] - Pass OPTIONS to next handler
+ * @param {number} [options.optionsSuccessStatus=204] - OPTIONS preflight success status
+ * @param {string|string[]|boolean} [options.routes=true] - Route prefixes or true for all
+ * @returns {Function} Express middleware handler
+ */
+function createCorsMiddleware(options = {}) {
+  const defaults = {
+    origin: '*',
+    methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept'],
+    exposedHeaders: [],
+    credentials: false,
+    maxAge: 86400,
+    preflightContinue: false,
+    optionsSuccessStatus: 204,
+    routes: true,
+  };
+
+  const config = { ...defaults, ...options };
+
+  const methodsStr = Array.isArray(config.methods)
+    ? config.methods.join(',')
+    : String(config.methods);
+
+  const allowedHeadersStr = Array.isArray(config.allowedHeaders)
+    ? config.allowedHeaders.join(',')
+    : String(config.allowedHeaders);
+
+  const exposedHeadersStr = Array.isArray(config.exposedHeaders)
+    ? config.exposedHeaders.join(',')
+    : String(config.exposedHeaders);
+
+  function isOriginAllowed(reqOrigin, callback) {
+    if (!config.origin || config.origin === '*') {
+      return callback(null, config.origin);
+    }
+    if (!reqOrigin) {
+      return callback(null, false);
+    }
+    if (typeof config.origin === 'string') {
+      return callback(null, config.origin === reqOrigin ? reqOrigin : false);
+    }
+    if (Array.isArray(config.origin)) {
+      for (const item of config.origin) {
+        if (typeof item === 'string' && item === reqOrigin) {
+          return callback(null, reqOrigin);
+        }
+        if (item instanceof RegExp && item.test(reqOrigin)) {
+          return callback(null, reqOrigin);
+        }
+      }
+      return callback(null, false);
+    }
+    if (config.origin instanceof RegExp) {
+      return callback(null, config.origin.test(reqOrigin) ? reqOrigin : false);
+    }
+    if (typeof config.origin === 'function') {
+      return config.origin(reqOrigin, callback);
+    }
+    return callback(null, false);
+  }
+
+  function shouldApplyToRoute(reqPath) {
+    if (config.routes === true || !config.routes) return true;
+    const routesList = Array.isArray(config.routes) ? config.routes : [config.routes];
+    return routesList.some((prefix) => reqPath.startsWith(prefix));
+  }
+
+  return (req, res, next) => {
+    const reqPath = req.path || req.url || '/';
+
+    if (!shouldApplyToRoute(reqPath)) {
+      return next();
+    }
+
+    const reqOrigin = req.headers.origin;
+
+    isOriginAllowed(reqOrigin, (err, allowedOrigin) => {
+      if (err) {
+        return next(err);
+      }
+
+      if (allowedOrigin) {
+        if (allowedOrigin === '*' && config.credentials) {
+          res.setHeader('Access-Control-Allow-Origin', reqOrigin || '*');
+        } else {
+          res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+        }
+        res.setHeader('Vary', 'Origin');
+      }
+
+      if (config.credentials) {
+        res.setHeader('Access-Control-Allow-Credentials', 'true');
+      }
+
+      if (exposedHeadersStr) {
+        res.setHeader('Access-Control-Expose-Headers', exposedHeadersStr);
+      }
+
+      // Preflight OPTIONS request
+      if (req.method === 'OPTIONS') {
+        if (allowedOrigin) {
+          if (methodsStr) {
+            res.setHeader('Access-Control-Allow-Methods', methodsStr);
+          }
+          if (allowedHeadersStr) {
+            res.setHeader('Access-Control-Allow-Headers', allowedHeadersStr);
+          } else if (req.headers['access-control-request-headers']) {
+            res.setHeader('Access-Control-Allow-Headers', req.headers['access-control-request-headers']);
+          }
+          if (config.maxAge) {
+            res.setHeader('Access-Control-Max-Age', String(config.maxAge));
+          }
+        }
+
+        if (config.preflightContinue) {
+          return next();
+        }
+
+        res.statusCode = config.optionsSuccessStatus;
+        res.setHeader('Content-Length', '0');
+        return res.end();
+      }
+
+      next();
+    });
+  };
+}
+
+/**
+ * Webspresso CORS Plugin Factory
+ * @param {Object} [options] - CORS options
+ * @returns {Object} Plugin definition
+ */
+function corsPlugin(options = {}) {
+  return {
+    name: 'cors',
+    version: '1.0.0',
+    options,
+    register(ctx) {
+      const corsMiddleware = createCorsMiddleware(options);
+
+      if (ctx.middlewares) {
+        ctx.middlewares.cors = corsMiddleware;
+      }
+
+      if (ctx.app && options.global !== false) {
+        ctx.app.use(corsMiddleware);
+      }
+    },
+  };
+}
+
+corsPlugin.createCorsMiddleware = createCorsMiddleware;
+
+module.exports = corsPlugin;

package/plugins/csrf/index.js

@@ -150,7 +150,14 @@ function csrfPlugin(options = {}) {
         secret = cookieOptions.signed ? req.signedCookies[cookieKey] : req.cookies[cookieKey];
         if (!secret) {
           secret = crypto.randomBytes(32).toString('hex');
-          res.cookie(cookieKey, secret, cookieOptions);
+          const isHttps = req.secure || req.headers?.['x-forwarded-proto'] === 'https' || process.env.NODE_ENV === 'production' || process.env.COOKIE_SECURE === 'true';
+          const effectiveCookieOptions = {
+            httpOnly: true,
+            sameSite: 'lax',
+            ...cookieOptions,
+            secure: cookieOpts.secure !== undefined ? cookieOpts.secure : isHttps,
+          };
+          res.cookie(cookieKey, secret, effectiveCookieOptions);
         }
       } else {
         // Session based

package/plugins/index.js

@@ -24,6 +24,7 @@ const { rateLimitPlugin } = require('./rate-limit');
 const emailPlugin = require('./email');
 const contentPlugin = require('./content');
 const csrfPlugin = require('./csrf');
+const corsPlugin = require('./cors');
 
 module.exports = {
   sitemapPlugin,
@@ -47,5 +48,6 @@ module.exports = {
   emailPlugin,
   contentPlugin,
   csrfPlugin,
+  corsPlugin,
 };
 

package/src/server.js

@@ -349,8 +349,9 @@ function createApp(options = {}) {
       if (finalConfig.contentSecurityPolicy && finalConfig.contentSecurityPolicy.directives) {
         const directives = finalConfig.contentSecurityPolicy.directives;
         for (const [directive, sources] of Object.entries(pluginCspSources)) {
-          if (sources.size > 0 && directives[directive]) {
-            directives[directive] = [...directives[directive], ...Array.from(sources)];
+          if (sources.size > 0) {
+            const existing = (directives[directive] || []).filter(s => s !== "'none'");
+            directives[directive] = [...existing, ...Array.from(sources)];
           }
         }
       }
@@ -385,6 +386,7 @@ function createApp(options = {}) {
     // Add auth middleware to named middlewares for route config
     middlewares.auth = authMiddleware.auth;
     middlewares.guest = authMiddleware.guest;
+    middlewares.jwt = authMiddleware.jwt;
   }
 
   // Under Vitest, shared API fixtures use `fixtureRequireAuth`; default no-op unless overridden.

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -72,19 +72,27 @@ project/
 - **CSP / Helmet:** production **`script-src 'self'`** works for **`/__webspresso/client-runtime/`**; some Alpine builds may need **`unsafe-eval`** — validate for your version or use a stricter build.
 - **Longer doc:** **[`doc/index.html#client-runtime`](../../../doc/index.html#client-runtime)** · README **Client runtime**.
 
-### Session authentication — essentials
-
-- **Import:** `const { createAuth, quickAuth, hash, verify, createRememberTokensTable } = require('webspresso/core/auth')` (published `core/` tree on npm; **not** re-exported from package root).
-- **`createAuth({ findUserById, findUserByCredentials, session: { secret }, rememberTokens?, ... })`** — adapter pattern; optional **remember-me** via `rememberTokens: { create, find, delete, deleteAllForUser }` + **`createRememberTokensTable(knex)`** for the default table shape.
-- **`quickAuth({ db, userModel, identifierField, passwordField, rememberMe })`** — wires **`getRepository`** + bcrypt **`verify`**; optional Knex **`remember_tokens`** when `rememberMe: true`.
+### Dual authentication (Session + JWT & Refresh Tokens) — essentials
+
+- **Import:** `const { createAuth, quickAuth, hash, verify, signJwt, verifyJwt, decodeJwt, createRememberTokensTable } = require('webspresso/core/auth')` (published `core/` tree on npm; **not** re-exported from package root).
+- **Dual Architecture:**
+  - **Session + Cookie (Stateful):** Primary for browser SSR routes and Admin Panel (`/`, `/_admin`). Uses `httpOnly` secure cookies.
+  - **JWT + Refresh Token (Stateless):** Built-in zero-dependency HS256 auth for REST APIs, Mobile Apps, and SPAs (`/api/*`). Uses `Authorization: Bearer <token>` for access tokens and rotatable Refresh Tokens.
+- **`createAuth({ findUserById, findUserByCredentials, session: { secret }, jwt: { secret, refreshSecret, expiresIn, refreshExpiresIn }, rememberTokens?, ... })`** — adapter pattern; optional **remember-me** via `rememberTokens` and opt-in **JWT / Refresh Tokens**.
+- **`quickAuth({ db, userModel, identifierField, passwordField, rememberMe, jwt })`** — wires **`getRepository`** + bcrypt **`verify`**; optional Knex **`remember_tokens`** and **JWT / Refresh Token** manager (`jwt: true` or `jwt: { expiresIn: '15m', refreshExpiresIn: '30d' }`).
+- **JWT Helper Methods:**
+  - **`auth.generateUserToken(user, options)`** — generates short-lived access JWT (`type: 'access'`).
+  - **`auth.generateRefreshToken(user, options)`** — generates long-lived refresh JWT (`type: 'refresh'`).
+  - **`auth.refreshAccessToken(refreshToken, options)`** — verifies refresh token and issues new access token + rotated refresh token.
+  - **`auth.requireJwt()`** — guard middleware enforcing valid `Bearer` access token.
 - **Request API** (after global authenticate): **`req.auth.attempt(id, password, { remember })`**, **`login`**, **`logout`**, **`check`**, **`guest`**, **`user`**, **`id`**, **`can` / `cannot` / `authorize`** (policies: **`auth.definePolicy`**, **`defineGate`**, **`beforePolicy`**).
-- **Route config:** `middleware: ['auth']` (must be logged in) or `['guest']` (logged-out only). For JSON APIs mounted in **`setupRoutes`**, use **`ctx.authMiddleware.requireAuth({ api: true })`** for 401 JSON instead of redirect.
+- **Route config:** `middleware: ['auth']` (SSR logged in), `middleware: ['jwt']` (API Bearer token), or `['guest']` (logged-out only). For JSON APIs mounted in **`setupRoutes`**, use **`ctx.authMiddleware.requireJwt()`** or **`requireAuth({ api: true })`**.
 - **Login page pitfall:** a **`pages/login.njk`** can register **before** `setupRoutes` and bypass **`requireGuest`**. Prefer login GET/POST in **`setupRoutes`** with templates under **`views/`** only, or omit **`pages/login.njk`** — see [`tests/e2e/auth.spec.js`](../../../tests/e2e/auth.spec.js).
 - **Admin panel** uses a **separate** session (`req.session.adminUser`, `/_admin/api/auth/*`); it does **not** replace **`createApp({ auth })`** for site users.
 - **Site users in the admin UI (`userManagement`):** Opt-in on **`adminPanelPlugin`**. Set **`userManagement: { enabled: true, model: 'User', fields?: { ... } }`** so the SPA shows **Users**: sidebar **All Users** / **Add User** link to **`/_admin/models/{model}`** and **`/_admin/models/{model}/new`** (same RecordList/RecordForm as other models). **`/_admin/users`**, **`/_admin/users/new`**, **`/_admin/users/:id/edit`** remain SPA aliases that redirect there; **`/_admin/users/sessions`** is **Active Sessions**. The **`model`** must match site auth (e.g. **`quickAuth({ userModel: 'User', ... })`** / **`createAuth`**) and must have **`admin: { enabled: true, ... }`** on **`defineModel`** so admin CRUD metadata loads; otherwise Users screens look empty. Pass **`auth: authManager`** with the **same** **`AuthManager`** as **`createApp({ auth: authManager })`** for **Active Sessions** / revoke (**`rememberTokens`** / **`remember_me`**); without **`auth`**, user CRUD still works via **`db.getRepository(model)`**, but session endpoints return empty or “not enabled”.
 - **Wiring:** `plugins: [ adminPanelPlugin({ db, auth: authManager, userManagement: { enabled: true, model: 'User' } }) ]` alongside `createApp({ ..., auth: authManager })`. Admin staff log in at **`/_admin`**; end users use your normal site login — two different cookies/sessions.
 
-Longer narrative: **[`doc/index.html#authentication`](../../../doc/index.html#authentication)** · **[`#admin-user-management`](../../../doc/index.html#admin-user-management)** · README **Authentication (session)** and **Admin Panel Plugin**.
+Longer narrative: **[`doc/index.html#authentication`](../../../doc/index.html#authentication)** · **[`#admin-user-management`](../../../doc/index.html#admin-user-management)** · README **Authentication (session & JWT)** and **Admin Panel Plugin**.
 
 ---