webspresso 0.0.83 → 0.0.85

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 });
@@ -148,6 +156,37 @@ function generateCustomPageComponent() {
   return `
 // Custom Page Component Factory
 function createCustomPage(pageConfig) {
+  if (pageConfig && (pageConfig.url || pageConfig.html)) {
+    var iframeAttrs = {
+      src: pageConfig.url || undefined,
+      srcdoc: pageConfig.html || undefined,
+      style: 'width: 100%; height: ' + (pageConfig.layout === false ? '100vh' : 'calc(100vh - 12rem)') + '; min-height: 600px; border: 0; border-radius: 0.5rem;',
+      allow: 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen',
+      allowfullscreen: true
+    };
+    if (pageConfig.layout === false) {
+      return {
+        view: function() {
+          return m('iframe', iframeAttrs);
+        }
+      };
+    }
+    return {
+      view: function() {
+        return m(Layout, [
+          m(Breadcrumb, { items: [{ label: pageConfig.title, href: pageConfig.path }] }),
+          m('div.mb-4.flex.items-start.justify-between.gap-4', [
+            m('div', [
+              m('h1.text-2xl.font-bold.text-gray-900.dark:text-slate-100', pageConfig.title),
+              pageConfig.description && m('p.text-gray-500.dark:text-slate-400.mt-1', pageConfig.description)
+            ])
+          ]),
+          m('iframe', iframeAttrs)
+        ]);
+      }
+    };
+  }
+
   return {
     oninit(vnode) {
       vnode.state.data = null;

package/plugins/admin-panel/modules/menu.js

@@ -200,9 +200,11 @@ const ThemeToggle = {
 const MenuItem = {
   view(vnode) {
     const { item, active } = vnode.attrs;
+    const adminPath = window.__ADMIN_PATH__ || '/_admin';
+    const href = item.path ? (item.path.startsWith('/') ? adminPath + item.path : adminPath + '/' + item.path) : '#';
     
     return m('a.flex.items-center.gap-3.px-3.py-2.rounded-lg.text-sm.font-medium.transition-colors', {
-      href: item.path,
+      href: href,
       class: active 
         ? 'bg-blue-100 dark:bg-blue-900/40 text-blue-700 dark:text-blue-300' 
         : 'text-gray-700 dark:text-slate-300 hover:bg-gray-100 dark:hover:bg-slate-700',
@@ -210,6 +212,7 @@ const MenuItem = {
         e.preventDefault();
         sidebarOpen = false;
         m.route.set(item.path);
+        setTimeout(() => m.redraw(), 0);
       },
     }, [
       item.icon && m(Icon, { name: item.icon, class: 'w-5 h-5 flex-shrink-0' }),
@@ -336,16 +339,25 @@ const Sidebar = {
         // User section
         state.user && m('div.p-4.border-t.border-gray-200.dark:border-slate-600', [
           m('div.flex.items-center.gap-3', [
-            m('div.w-8.h-8.bg-gray-200 dark:bg-slate-700.rounded-full.flex.items-center.justify-center', [
-              m('span.text-sm.font-medium.text-gray-600.dark:text-slate-300', 
-                (state.user.name || state.user.email || 'A').charAt(0).toUpperCase()
-              ),
-            ]),
-            m('div.flex-1.min-w-0', [
-              m('p.text-sm.font-medium.text-gray-900 dark:text-slate-100.truncate', state.user.name || 'Admin'),
-              m('p.text-xs.text-gray-500 dark:text-slate-400.truncate', state.user.email),
+            m('div.flex-1.flex.items-center.gap-3.min-w-0.cursor-pointer.hover:opacity-80.transition-opacity', {
+              title: 'Edit Profile',
+              onclick: () => { sidebarOpen = false; m.route.set('/profile'); },
+            }, [
+              m('div.w-8.h-8.bg-blue-100.dark:bg-blue-900/50.rounded-full.flex.items-center.justify-center.flex-shrink-0', [
+                m('span.text-sm.font-semibold.text-blue-600.dark:text-blue-300', 
+                  (state.user.name || state.user.email || 'A').charAt(0).toUpperCase()
+                ),
+              ]),
+              m('div.flex-1.min-w-0', [
+                m('p.text-sm.font-medium.text-gray-900.dark:text-slate-100.truncate', state.user.name || 'Admin'),
+                m('p.text-xs.text-gray-500.dark:text-slate-400.truncate', state.user.email),
+              ]),
             ]),
-            m('button.p-1.text-gray-400 dark:text-slate-500.hover:text-gray-600 dark:hover:text-slate-300', {
+            m('button.p-1.text-gray-400.dark:text-slate-500.hover:text-blue-600.dark:hover:text-blue-400.transition-colors', {
+              title: 'My Profile',
+              onclick: () => { sidebarOpen = false; m.route.set('/profile'); },
+            }, m(Icon, { name: 'user', class: 'w-4 h-4' })),
+            m('button.p-1.text-gray-400.dark:text-slate-500.hover:text-red-600.dark:hover:text-red-400.transition-colors', {
               title: 'Logout',
               onclick: async () => {
                 await api.post('/auth/logout');
@@ -354,7 +366,7 @@ const Sidebar = {
                 clearIntendedRoute();
                 m.route.set('/login');
               },
-            }, m(Icon, { name: 'logout', class: 'w-5 h-5' })),
+            }, m(Icon, { name: 'logout', class: 'w-4 h-4' })),
           ]),
         ]),
       ]),

package/plugins/admin-panel/modules/profile.js

@@ -0,0 +1,192 @@
+/**
+ * Profile Page Component
+ * Allows logged-in admin user to view and update name, email, and password
+ * @module plugins/admin-panel/modules/profile
+ */
+
+function generateProfileComponent() {
+  return `
+const ProfilePage = {
+  oninit(vnode) {
+    vnode.state.loading = true;
+    vnode.state.saving = false;
+    vnode.state.name = '';
+    vnode.state.email = '';
+    vnode.state.currentPassword = '';
+    vnode.state.newPassword = '';
+    vnode.state.confirmPassword = '';
+    vnode.state.error = null;
+    vnode.state.success = null;
+
+    api.get('/auth/me')
+      .then(res => {
+        if (res && res.user) {
+          vnode.state.name = res.user.name || '';
+          vnode.state.email = res.user.email || '';
+        }
+        vnode.state.loading = false;
+        m.redraw();
+      })
+      .catch(err => {
+        vnode.state.error = err.message || String(err);
+        vnode.state.loading = false;
+        m.redraw();
+      });
+  },
+
+  view(vnode) {
+    const s = vnode.state;
+
+    const handleSubmit = async (e) => {
+      e.preventDefault();
+      s.saving = true;
+      s.error = null;
+      s.success = null;
+
+      if (s.newPassword) {
+        if (!s.currentPassword) {
+          s.error = 'Current password is required to change your password';
+          s.saving = false;
+          m.redraw();
+          return;
+        }
+        if (s.newPassword.length < 6) {
+          s.error = 'New password must be at least 6 characters';
+          s.saving = false;
+          m.redraw();
+          return;
+        }
+        if (s.newPassword !== s.confirmPassword) {
+          s.error = 'New passwords do not match';
+          s.saving = false;
+          m.redraw();
+          return;
+        }
+      }
+
+      try {
+        const payload = {
+          name: s.name,
+          email: s.email,
+        };
+        if (s.newPassword) {
+          payload.currentPassword = s.currentPassword;
+          payload.newPassword = s.newPassword;
+        }
+
+        const res = await api.put('/auth/profile', payload);
+        s.saving = false;
+        if (res && res.success && res.user) {
+          s.success = 'Profile updated successfully';
+          s.currentPassword = '';
+          s.newPassword = '';
+          s.confirmPassword = '';
+          if (typeof state !== 'undefined' && state) {
+            state.user = res.user;
+          }
+        }
+        m.redraw();
+      } catch (err) {
+        s.saving = false;
+        s.error = err.message || 'Failed to update profile';
+        m.redraw();
+      }
+    };
+
+    return m(Layout, { breadcrumbs: [{ label: 'Profile', href: '/profile' }] }, [
+      m('div.max-w-4xl.mx-auto.space-y-6', [
+        m('div.flex.items-center.justify-between', [
+          m('div', [
+            m('h1.text-2xl.font-bold.text-gray-900.dark:text-slate-100', 'My Profile'),
+            m('p.text-sm.text-gray-500.dark:text-slate-400', 'Manage your personal details and account password'),
+          ]),
+        ]),
+
+        s.loading
+          ? m('div.flex.justify-center.py-12', m(Spinner))
+          : m('form', { onsubmit: handleSubmit }, [
+              s.error && m('div.p-4.mb-4.rounded-lg.bg-red-50.dark:bg-red-900/30.text-red-700.dark:text-red-300.text-sm', s.error),
+              s.success && m('div.p-4.mb-4.rounded-lg.bg-green-50.dark:bg-green-900/30.text-green-700.dark:text-green-300.text-sm', s.success),
+
+              // Personal Information Card
+              m('div.bg-white.dark:bg-slate-800.rounded-xl.border.border-gray-200.dark:border-slate-700.p-6.mb-6.shadow-sm.space-y-4', [
+                m('h2.text-lg.font-semibold.text-gray-900.dark:text-slate-100.border-b.border-gray-100.dark:border-slate-700.pb-3', 'Personal Information'),
+                m('div.grid.grid-cols-1.md:grid-cols-2.gap-4', [
+                  m('div', [
+                    m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', 'Name'),
+                    m('input.w-full.px-3.py-2.border.border-gray-300.dark:border-slate-600.rounded-lg.bg-white.dark:bg-slate-900.text-gray-900.dark:text-slate-100.focus:ring-2.focus:ring-blue-500', {
+                      type: 'text',
+                      required: true,
+                      value: s.name,
+                      oninput: (e) => { s.name = e.target.value; },
+                    }),
+                  ]),
+                  m('div', [
+                    m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', 'Email Address'),
+                    m('input.w-full.px-3.py-2.border.border-gray-300.dark:border-slate-600.rounded-lg.bg-white.dark:bg-slate-900.text-gray-900.dark:text-slate-100.focus:ring-2.focus:ring-blue-500', {
+                      type: 'email',
+                      required: true,
+                      value: s.email,
+                      oninput: (e) => { s.email = e.target.value; },
+                    }),
+                  ]),
+                ]),
+              ]),
+
+              // Password Change Card
+              m('div.bg-white.dark:bg-slate-800.rounded-xl.border.border-gray-200.dark:border-slate-700.p-6.mb-6.shadow-sm.space-y-4', [
+                m('h2.text-lg.font-semibold.text-gray-900.dark:text-slate-100.border-b.border-gray-100.dark:border-slate-700.pb-3', 'Change Password'),
+                m('p.text-xs.text-gray-500.dark:text-slate-400', 'Leave blank if you do not wish to change your password'),
+                m('div.space-y-4', [
+                  m('div', [
+                    m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', 'Current Password'),
+                    m('input.w-full.px-3.py-2.border.border-gray-300.dark:border-slate-600.rounded-lg.bg-white.dark:bg-slate-900.text-gray-900.dark:text-slate-100.focus:ring-2.focus:ring-blue-500', {
+                      type: 'password',
+                      value: s.currentPassword,
+                      oninput: (e) => { s.currentPassword = e.target.value; },
+                      placeholder: '••••••••',
+                    }),
+                  ]),
+                  m('div.grid.grid-cols-1.md:grid-cols-2.gap-4', [
+                    m('div', [
+                      m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', 'New Password'),
+                      m('input.w-full.px-3.py-2.border.border-gray-300.dark:border-slate-600.rounded-lg.bg-white.dark:bg-slate-900.text-gray-900.dark:text-slate-100.focus:ring-2.focus:ring-blue-500', {
+                        type: 'password',
+                        value: s.newPassword,
+                        oninput: (e) => { s.newPassword = e.target.value; },
+                        placeholder: 'Min 6 characters',
+                      }),
+                    ]),
+                    m('div', [
+                      m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', 'Confirm New Password'),
+                      m('input.w-full.px-3.py-2.border.border-gray-300.dark:border-slate-600.rounded-lg.bg-white.dark:bg-slate-900.text-gray-900.dark:text-slate-100.focus:ring-2.focus:ring-blue-500', {
+                        type: 'password',
+                        value: s.confirmPassword,
+                        oninput: (e) => { s.confirmPassword = e.target.value; },
+                        placeholder: 'Repeat new password',
+                      }),
+                    ]),
+                  ]),
+                ]),
+              ]),
+
+              m('div.flex.justify-end', [
+                m('button.px-6.py-2.bg-blue-600.hover:bg-blue-700.text-white.font-medium.rounded-lg.shadow-sm.transition-colors.disabled:opacity-50.flex.items-center.gap-2', {
+                  type: 'submit',
+                  disabled: s.saving,
+                }, [
+                  s.saving && m(Spinner),
+                  s.saving ? 'Saving...' : 'Save Profile',
+                ]),
+              ]),
+            ]),
+      ]),
+    ]);
+  },
+};
+`;
+}
+
+module.exports = {
+  generateProfileComponent,
+};

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**.
 
 ---
 
@@ -195,7 +203,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 | `dashboardPlugin` | Dev route `/_webspresso` — route list |
 | `sitemapPlugin` | `/sitemap.xml`, robots; optional DB-driven URLs |
 | `analyticsPlugin` | GA / GTM / Yandex / Bing / Facebook — `fsy` helpers |
-| `adminPanelPlugin` | SPA admin CRUD — needs **`db`**; optional **`uploadUrl`** (or infer from **`uploadPlugin`**); optional **`userManagement: { enabled, model, fields }`** + **`auth`** (same **`AuthManager`** as **`createApp({ auth })`**) for site-user CRUD + remember-me session UI — see **Session authentication** above |
+| `adminPanelPlugin` | SPA admin CRUD — needs **`db`**; supports custom HTML & external URL pages (`url`, `html`, `htmlFile`, `layout: false`) and SSR script/style imports (`scripts`, `styles`, `registerScript`, `registerStyle`); optional **`uploadUrl`** (or infer from **`uploadPlugin`**); optional **`userManagement: { enabled, model, fields }`** + **`auth`** (same **`AuthManager`** as **`createApp({ auth })`**) for site-user CRUD + remember-me session UI — see **Session authentication** above |
 | `dataExchangePlugin` | Admin-only **Excel export** + **CSV/XLSX import** under `${adminPath}/api/data-exchange/*`; register **after** `adminPanelPlugin` with same `db` / `adminPath`; optional `maxRows`, `maxFileBytes`; adds UI buttons + bulk `export-xlsx` |
 | `redirectPlugin` | Configurable **301–308** redirects in `register()` — runs **before** file-based SSR routes; `rules` (`from` path or `RegExp`, `to`, `status`, `methods`), `preserveQuery`, `allowExternal`, `trailingSlash`, `defaultMethods`; docs **[`doc/index.html#plugins-redirect`](../../../doc/index.html#plugins-redirect)**, README **Redirect plugin** |
 | `uploadPlugin` | `POST` multipart (`multer`), `createLocalFileProvider` or custom `provider`; set **`mimeAllowlist`** / **`maxBytes`** in production; pairs with admin **`zdb.file()`** / **`customFields.file-upload`** when registered before **`adminPanelPlugin`** |