webspresso 0.0.84 → 0.0.86

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**.
 
 ---