webspresso 0.0.98 → 0.0.99

package/.agents/ROUTING.md

@@ -53,7 +53,10 @@ All routes are automatically discovered and registered from the `pages/` directo
 | `pages/index.njk` | `GET` | `/` | Home page (SSR Nunjucks) |
 | `pages/about.njk` | `GET` | `/about` | Static SSR page |
 | `pages/notes/[id].njk` | `GET` | `/notes/:id` | Dynamic SSR route with param |
+| `pages/(marketing)/about.njk` | `GET` | `/about` | Route Group page (omits `(marketing)`) |
+| `pages/(auth)/login.njk` | `GET` | `/login` | Route Group with isolated layout & middleware |
 | `pages/api/notes.get.js` | `GET` | `/api/notes` | List notes API endpoint |
+| `pages/api/(v1)/notes.get.js` | `GET` | `/api/notes` | API route inside Route Group |
 | `pages/api/notes.post.js` | `POST` | `/api/notes` | Create note API endpoint |
 | `pages/api/notes/[id].get.js` | `GET` | `/api/notes/:id` | Get single note API endpoint |
 | `pages/api/notes/[id].put.js` | `PUT` | `/api/notes/:id` | Update note API endpoint |
@@ -148,7 +151,50 @@ module.exports = {
 
 ---
 
-## 4. SSR Page Routes (`load()` Loader)
+## 4. Route Groups `(group)` Syntax & Layout Isolation
+
+Webspresso supports Next.js / Nuxt-style **Route Groups**. Any directory name wrapped in parentheses `(groupName)` is treated as an organizational group:
+- **Clean Public URLs**: The parenthesized directory name is completely omitted from the generated URL path.
+- **Layout & Middleware Isolation**: The directory hierarchy is preserved for cascading middleware (`_middleware.js`) and nested layouts (`_layout.njk`), allowing distinct shells and security guards without polluting public route URLs.
+- **Nesting & Dynamic Route Support**: Route groups can be nested (e.g. `(shop)/(checkout)/cart.njk` → `/cart`), combined with dynamic segments (e.g. `(app)/users/[id].njk` → `/users/:id`), and applied to API routes (`pages/api/(v1)/items.get.js` → `/api/items` or `pages/(marketing)/api/newsletter.post.js` → `/api/newsletter`).
+
+### 4.1 Route Group Structure Example
+
+```
+pages/
+├── (marketing)/
+│   ├── _layout.njk          # Marketing layout (Hero header, footer)
+│   ├── _middleware.js       # Track analytics / marketing headers
+│   ├── index.njk            -> GET /
+│   ├── about.njk            -> GET /about
+│   └── api/
+│       └── newsletter.post.js -> POST /api/newsletter
+├── (auth)/
+│   ├── _layout.njk          # Centered card layout (no nav/footer)
+│   ├── _middleware.js       # Guest-only guard (redirects authenticated users)
+│   ├── login.njk            -> GET /login
+│   └── register.njk         -> GET /register
+└── (app)/
+    ├── _layout.njk          # App shell layout with sidebar
+    ├── _middleware.js       # Strict session auth guard
+    └── dashboard.njk        -> GET /dashboard
+```
+
+### 4.2 Programmatic Utilities
+Webspresso exports core helpers to inspect and transform route group paths:
+```javascript
+const { isRouteGroupSegment, stripRouteGroups } = require('webspresso');
+
+isRouteGroupSegment('(marketing)'); // true
+isRouteGroupSegment('about');       // false
+
+stripRouteGroups('/(marketing)/about'); // '/about'
+stripRouteGroups('/(shop)/(checkout)/cart'); // '/cart'
+```
+
+---
+
+## 5. SSR Page Routes (`load()` Loader)
 
 For server-rendered Nunjucks HTML pages, use `.njk` templates and companion `.js` loader files (or inline `async function load` in a `.js` file):
 
@@ -174,7 +220,7 @@ module.exports = {
 
 ---
 
-## 5. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
+## 6. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
 
 Webspresso supports clean, domain-driven module discovery alongside root-level pages and APIs:
 
@@ -204,7 +250,7 @@ src/
         auth-guard.js   -> module-local named middleware 'authGuard'
 ```
 
-### 5.1 `definePage()` Contract
+### 6.1 `definePage()` Contract
 ```javascript
 const { definePage } = require('webspresso');
 
@@ -230,7 +276,7 @@ module.exports = definePage({
 });
 ```
 
-### 5.2 `defineApi()` Contract
+### 6.2 `defineApi()` Contract
 ```javascript
 const { defineApi, z } = require('webspresso');
 
@@ -252,7 +298,7 @@ module.exports = defineApi({
 });
 ```
 
-### 5.3 `defineModule()` Contract
+### 6.3 `defineModule()` Contract
 ```javascript
 const { defineModule } = require('webspresso');
 
@@ -270,7 +316,7 @@ module.exports = defineModule({
 });
 ```
 
-### 5.4 Route Introspection (`app.routes.list()`)
+### 6.4 Route Introspection (`app.routes.list()`)
 Compiled routes are accessible at runtime for tooling, CLI inspection, and documentation:
 ```javascript
 const routeList = app.routes.list();
@@ -280,9 +326,83 @@ const routeList = app.routes.list();
 // ]
 ```
 
+### 6.5 Server-Sent Events (SSE) Streaming (`res.sse`)
+For real-time event streaming and LLM token outputs, use the native `res.sse()` helper (or `{ sse }` from `ctx`):
+
+```javascript
+// File: pages/api/ai/chat.post.js
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  handler: async (req, res, { sse }) => {
+    // 1. Controller mode with automatic keepalive & reconnection directives
+    const stream = sse({ heartbeat: 15000, retry: 3000 });
+
+    await stream.send({ delta: 'Hello ' });
+    await stream.send({ event: 'delta', data: { text: 'world!' }, id: '1' });
+    stream.close();
+
+    // 2. OR stream an async generator / LLM stream directly:
+    // return res.sse(async function*() {
+    //   for await (const chunk of llmStream) {
+    //     yield { token: chunk.text };
+    //   }
+    // });
+  },
+});
+```
+
+### 6.6 Cascading Middleware (`_middleware.js`) & Nested Layouts (`_layout.njk`)
+
+Webspresso supports folder-level cascading middleware inheritance and nested layouts across directory trees:
+
+#### 1. Cascading Middleware (`_middleware.js`)
+Any directory under `pages/` can declare a `_middleware.js` file:
+- **Execution Order**: Middlewares execute in top-down ancestral order (from root down to route leaf) before route handlers and route-specific middleware.
+- **Early Termination**: If any middleware sends headers (e.g. `res.status(401).json(...)` or `res.redirect('/login')`), execution halts immediately and downstream middlewares/handlers are skipped.
+- **Export Formats**: Standard Express middleware function `(req, res, next)`, async function, named middleware string/array `['auth', 'cors']`, or middleware tuples with options `[['rateLimit', { max: 100 }]]`.
+
+```
+pages/
+├── _middleware.js            # Runs for ALL routes (adds global headers / request ID)
+├── api/
+│   └── admin/
+│       ├── _middleware.js    # Protects all /api/admin/* endpoints
+│       └── metrics.get.js    # Inherits root + admin middleware
+└── dashboard/
+    ├── _middleware.js        # Auth guard for /dashboard/* pages
+    └── settings.njk
+```
+
+#### 2. Nested Layouts (`_layout.njk` & `_layout.js`)
+Pages under `pages/` automatically inherit ancestor layouts:
+- **Wrapping Order**: Child template is rendered first, then wrapped by layouts from innermost to outermost using `{{ content | safe }}`.
+- **Layout Loaders (`_layout.js`)**: Companion `_layout.js` files can export `async function load(req, ctx)` to supply shared data (e.g., site title, navigation, breadcrumbs) in top-down order before the page loader runs.
+- **Opt-Out**: A page can opt out of automatic layout wrapping by setting `layout: false` in its companion `.js` config/loader, or by explicitly using `{% extends "..." %}` in its Nunjucks template.
+
+```html
+{# pages/_layout.njk #}
+<!DOCTYPE html>
+<html>
+<head><title>{{ siteTitle }}</title></head>
+<body>
+  <header>Global Nav</header>
+  {{ content | safe }}
+</body>
+</html>
+```
+
+```html
+{# pages/dashboard/_layout.njk #}
+<div class="dashboard-shell">
+  <aside>Dashboard Sidebar</aside>
+  <main>{{ content | safe }}</main>
+</div>
+```
+
 ---
 
-## 6. Summary Checklist for Agents
+## 7. Summary Checklist for Agents
 
 When a user asks to add or modify endpoints:
 1. Identify the URL and method (e.g. `POST /api/auth/register` or `POST /auth/login`).

package/AGENTS.md

@@ -142,6 +142,7 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 - `restResourcePlugin`: Zero-boilerplate RESTful CRUD API generator directly from ORM models with eager loading, sanitization, filtering, pagination, and soft-delete scoping.
 - `xlsxPlugin`: Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and built-in services (`xlsx.generate`, `xlsx.parse`, `xlsx.exportModel`).
 - `csvPlugin`: RFC 4180 CSV generator, parser, Excel UTF-8 BOM compatibility, formula sanitization, streaming writer (`res.csv`), and built-in services (`csv.generate`, `csv.parse`, `csv.exportModel`).
+- `apiKeyPlugin`: Zero-dependency B2B & Developer API Key Management with SHA-256 secure storage, constant-time verification, granular wildcard scopes, named route middleware (`ctx.middlewares.apiKey`), and non-blocking usage tracking.
 
 ---
 

package/core/auth/index.js

@@ -15,6 +15,37 @@ const {
   dropAuthTokensTable,
   createKnexAuthTokensAdapter,
 } = require('./tokens');
+const {
+  OAuthClient,
+  OAuthError,
+  createOAuthClient,
+  generatePKCE,
+  createSignedState,
+  verifySignedState,
+  DEFAULT_PROVIDERS,
+} = require('./oauth');
+const totp = require('./totp');
+const {
+  base32Encode,
+  base32Decode,
+  generateTotpSecret,
+  generateHotp,
+  verifyHotp,
+  generateTotp,
+  verifyTotp,
+  generateTotpUri,
+  generateTotpQrSvg,
+  generateTotpQrDataUri,
+  generateRecoveryCodes,
+  hashRecoveryCode,
+  verifyRecoveryCode,
+  createTotpSetup,
+} = totp;
+const {
+  createQrMatrix,
+  generateQrSvg,
+  generateQrDataUri,
+} = require('./qrcode');
 
 /**
  * Create authentication instance
@@ -195,6 +226,35 @@ module.exports = {
   createKnexAuthTokensAdapter,
   TOKEN_TYPES,
   
+  // OAuth 2.0 & Social Login
+  OAuthClient,
+  OAuthError,
+  createOAuthClient,
+  generatePKCE,
+  createSignedState,
+  verifySignedState,
+  DEFAULT_PROVIDERS,
+
+  // 2FA / TOTP (RFC 6238, RFC 4226, RFC 4648)
+  totp,
+  base32Encode,
+  base32Decode,
+  generateTotpSecret,
+  generateHotp,
+  verifyHotp,
+  generateTotp,
+  verifyTotp,
+  generateTotpUri,
+  generateTotpQrSvg,
+  generateTotpQrDataUri,
+  generateRecoveryCodes,
+  hashRecoveryCode,
+  verifyRecoveryCode,
+  createTotpSetup,
+  createQrMatrix,
+  generateQrSvg,
+  generateQrDataUri,
+
   // Config
   DEFAULT_CONFIG,
 };

package/core/auth/manager.js

@@ -60,6 +60,7 @@ const DEFAULT_CONFIG = {
     logout: '/logout',
     home: '/',
     redirectAfterLogin: '/dashboard',
+    twoFactor: '/2fa',
   },
 };
 
@@ -107,6 +108,10 @@ class AuthManager {
       welcome: config.notifications?.welcome || null,
     };
 
+    // TOTP & 2FA initialization
+    this.totp = require('./totp');
+    this.twoFactor = config.twoFactor || { enabled: false };
+
     if (config.jwt) {
       const jwtSecret = typeof config.jwt === 'object' && config.jwt.secret
         ? config.jwt.secret
@@ -329,6 +334,9 @@ class AuthManager {
           }
         }
         
+        // Clear 2FA session state
+        this.clear2Fa();
+
         // Clear user
         req.user = null;
         
@@ -377,6 +385,119 @@ class AuthManager {
         return req.user?.id || null;
       },
 
+      /**
+       * TOTP helper utilities (RFC 6238 / RFC 4226)
+       */
+      totp: self.totp,
+
+      /**
+       * Check if two-factor authentication has been verified in current session/request
+       * @returns {boolean}
+       */
+      is2FaVerified() {
+        if (req.session?.twoFactorVerified) return true;
+        if (req.jwtPayload?.twoFactorVerified) return true;
+        return false;
+      },
+
+      /**
+       * Check if two-factor authentication is pending verification
+       * @returns {boolean}
+       */
+      is2FaPending() {
+        return Boolean(req.session?.twoFactorPending);
+      },
+
+      /**
+       * Mark two-factor authentication as verified
+       * @param {boolean} [verified=true]
+       */
+      set2FaVerified(verified = true) {
+        if (req.session) {
+          req.session.twoFactorVerified = Boolean(verified);
+          if (verified) {
+            delete req.session.twoFactorPending;
+            delete req.session.twoFactorUserId;
+          }
+        }
+      },
+
+      /**
+       * Mark two-factor authentication as pending verification for a user
+       * @param {Object} [user] - User object or user ID
+       */
+      set2FaPending(user) {
+        if (req.session) {
+          req.session.twoFactorPending = true;
+          req.session.twoFactorVerified = false;
+          if (user?.id) {
+            req.session.twoFactorUserId = user.id;
+          } else if (typeof user === 'string' || typeof user === 'number') {
+            req.session.twoFactorUserId = user;
+          }
+        }
+      },
+
+      /**
+       * Clear two-factor authentication status from session
+       */
+      clear2Fa() {
+        if (req.session) {
+          delete req.session.twoFactorVerified;
+          delete req.session.twoFactorPending;
+          delete req.session.twoFactorUserId;
+        }
+      },
+
+      /**
+       * Verify submitted TOTP token or recovery code
+       * Automatically marks 2FA as verified upon success
+       * @param {string} tokenOrCode - Submitted 6-digit TOTP code or recovery code
+       * @param {Object|string} secretOrUser - Secret string or user object with totp_secret / recovery_codes
+       * @param {Object} [options]
+       * @returns {{ success: boolean, type?: 'totp'|'recovery_code', delta?: number, remainingHashedCodes?: string[], matchedIndex?: number }}
+       */
+      verify2Fa(tokenOrCode, secretOrUser, options = {}) {
+        if (!tokenOrCode) {
+          return { success: false };
+        }
+
+        let secret = null;
+        let recoveryCodes = null;
+
+        if (typeof secretOrUser === 'string') {
+          secret = secretOrUser;
+        } else if (secretOrUser && typeof secretOrUser === 'object') {
+          secret = secretOrUser.totp_secret || secretOrUser.totpSecret || secretOrUser.two_factor_secret || secretOrUser.twoFactorSecret;
+          recoveryCodes = secretOrUser.recovery_codes || secretOrUser.recoveryCodes || secretOrUser.two_factor_recovery_codes;
+        }
+
+        // Try TOTP code first
+        if (secret) {
+          const totpResult = self.totp.verifyTotp(tokenOrCode, secret, { ...options, detailed: true });
+          if (totpResult.valid) {
+            this.set2FaVerified(true);
+            return { success: true, type: 'totp', delta: totpResult.delta };
+          }
+        }
+
+        // Try recovery codes if provided
+        if (recoveryCodes && Array.isArray(recoveryCodes) && recoveryCodes.length > 0) {
+          const recResult = self.totp.verifyRecoveryCode(tokenOrCode, recoveryCodes);
+          if (recResult.valid) {
+            this.set2FaVerified(true);
+            return {
+              success: true,
+              type: 'recovery_code',
+              matchedIndex: recResult.matchedIndex,
+              remainingHashedCodes: recResult.remainingHashedCodes,
+            };
+          }
+        }
+
+        return { success: false };
+      },
+
       /**
        * Check if user can perform action (policy check)
        * @param {string} action - Action name
@@ -801,6 +922,19 @@ class AuthManager {
     }
     return this._authMiddleware.requireJwt(options);
   }
+
+  /**
+   * Get require2Fa guard middleware for Express routes
+   * @param {Object} [options]
+   * @returns {Function} Express middleware
+   */
+  require2Fa(options = {}) {
+    if (!this._authMiddleware) {
+      const { createAuthMiddleware } = require('./middleware');
+      this._authMiddleware = createAuthMiddleware(this);
+    }
+    return this._authMiddleware.require2Fa(options);
+  }
 }
 
 module.exports = {

package/core/auth/middleware.js

@@ -255,6 +255,83 @@ function createAuthMiddleware(authManager) {
     };
   }
 
+  /**
+   * Require Two-Factor Authentication (2FA / TOTP) middleware
+   * Checks if user has completed 2FA step if 2FA is required or enabled for the user
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.always=false] - Always enforce 2FA verification regardless of user flag
+   * @param {boolean} [options.api=false] - Return JSON error instead of redirect
+   * @param {string} [options.redirectTo] - Redirect URL (default: config.routes.twoFactor || '/2fa')
+   * @param {string} [options.redirectToLogin] - Redirect URL if unauthenticated (default: config.routes.login)
+   * @param {Function} [options.isUser2FaEnabled] - Custom predicate (user) => boolean
+   */
+  function require2Fa(options = {}) {
+    return (req, res, next) => {
+      // 1. Must be logged in or have a pending 2FA authentication session
+      if (!req.user && !req.session?.twoFactorPending) {
+        if (options.api || req.xhr || req.headers?.accept?.includes('application/json')) {
+          return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Authentication required',
+          });
+        }
+        if (req.session) {
+          req.session.intendedUrl = req.originalUrl;
+        }
+        const loginUrl = options.redirectToLogin || config.routes.login;
+        return res.redirect(loginUrl);
+      }
+
+      // 2. Check if 2FA is required for this user or route
+      let userRequires2Fa = options.always === true;
+      if (!userRequires2Fa) {
+        if (typeof options.isUser2FaEnabled === 'function') {
+          userRequires2Fa = options.isUser2FaEnabled(req.user);
+        } else if (req.user) {
+          userRequires2Fa = Boolean(
+            req.user.two_factor_enabled ||
+            req.user.twoFactorEnabled ||
+            req.user.totp_enabled ||
+            req.user.totpEnabled
+          );
+        } else if (req.session?.twoFactorPending) {
+          userRequires2Fa = true;
+        }
+      }
+
+      // If user does not have 2FA enabled and route does not enforce it unconditionally, pass
+      if (!userRequires2Fa) {
+        return next();
+      }
+
+      // 3. Check if 2FA is already verified in this session
+      const isVerified = Boolean(
+        req.auth?.is2FaVerified?.() ||
+        req.session?.twoFactorVerified ||
+        req.jwtPayload?.twoFactorVerified
+      );
+
+      if (isVerified) {
+        return next();
+      }
+
+      // 4. Not verified -> reject with 403 or redirect to 2FA verification page
+      if (options.api || req.xhr || req.headers?.accept?.includes('application/json')) {
+        return res.status(403).json({
+          error: 'TwoFactorRequired',
+          message: 'Two-factor authentication required',
+        });
+      }
+
+      if (req.session) {
+        req.session.intendedUrl = req.originalUrl;
+      }
+
+      const redirectTo = options.redirectTo || config.routes.twoFactor || '/2fa';
+      return res.redirect(redirectTo);
+    };
+  }
+
   /**
    * Parse middleware string like 'can:edit,post' into middleware function
    * @param {string} middlewareString - Middleware string
@@ -273,6 +350,13 @@ function createAuthMiddleware(authManager) {
       
       case 'guest':
         return requireGuest();
+
+      case '2fa':
+      case 'totp':
+        return require2Fa({
+          api: args.includes('api'),
+          always: args.includes('always'),
+        });
       
       case 'can':
         // can:action,policy
@@ -297,6 +381,8 @@ function createAuthMiddleware(authManager) {
     requireAuth,
     requireJwt,
     requireGuest,
+    require2Fa,
+    requireTotp: require2Fa,
     requireCan,
     requireVerified,
     
@@ -307,6 +393,8 @@ function createAuthMiddleware(authManager) {
     auth: requireAuth,
     jwt: requireJwt,
     guest: requireGuest,
+    twoFactor: require2Fa,
+    totp: require2Fa,
   };
 }