webspresso 0.0.84 → 0.0.86

package/README.md

@@ -808,6 +808,33 @@ Options:
 
 See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.agents/skills/webspresso-usage/REFERENCE-framework.md`** for the split between **`adminUser`** and **`createApp({ auth })`**.
 
+**3-State Table Column Sorting & Configuration:**
+
+Admin Panel table headers support interactive 3-state column sorting:
+- **State 1 (`Unsorted`)**: Default state (`↕` icon).
+- **State 2 (`ASC`)**: 1st click sorts ascending (`▲` icon, `?sort=col&order=asc`).
+- **State 3 (`DESC`)**: 2nd click sorts descending (`▼` icon, `?sort=col&order=desc`).
+- **State 4 (`Unsorted`)**: 3rd click clears sorting and reverts to default primary key ordering.
+
+Configuration options:
+- **Column-level**: Standard scalar columns (`string`, `number`, `boolean`, `timestamp`) are sortable by default. Disable or enable per column:
+  ```javascript
+  schema: zdb.schema({
+    name: zdb.string({ sortable: true }),
+    secret_notes: zdb.text().config({ sortable: false }), // or zdb.text({ sortable: false })
+  })
+  ```
+- **Model-level**: Restrict sortable columns or disable sorting completely on a model in `defineModel`:
+  ```javascript
+  admin: {
+    enabled: true,
+    sortableColumns: ['name', 'price'], // Only name and price are sortable
+    // Or disable all sorting:
+    // sortable: false,
+  }
+  ```
+
+
 
 **Custom Admin Pages (registerModule):**
 
@@ -1316,6 +1343,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 = {