odac 1.3.0 → 1.4.0

package/docs/ai/skills/frontend/navigation.md

@@ -0,0 +1,20 @@
+# Frontend Navigation & SPA Skill
+
+Smooth transitions and single-page application behavior using `odac.js`.
+
+## Rules
+1.  **Selection**: Enable via `Odac.action({ navigate: 'main' })`.
+2.  **Exclusion**: Use `data-navigate="false"` or `.no-navigate` class for full reloads.
+3.  **Lifecycle**: Use `load` and `page` events to run code after navigation.
+
+## Patterns
+```javascript
+Odac.action({
+  navigate: {
+    update: 'main',
+    on: function(page, vars) {
+      console.log('Navigated to:', page);
+    }
+  }
+});
+```

package/docs/ai/skills/frontend/realtime.md

@@ -0,0 +1,47 @@
+# Frontend Realtime & WebSocket Skill
+
+Real-time bidirectional communication and server-sent events with high efficiency.
+
+## Architectural Approach
+ODAC prioritizes connection efficiency. `Odac.ws()` provides shared WebSocket connections across multiple browser tabs using `SharedWorker`, significantly reducing server load.
+
+## Core Rules
+1.  **Shared Connections**: Always prefer `Odac.ws(url, { shared: true })` for scalable real-time apps.
+2.  **Auto-Reconnect**: Enabled by default; the client handles network drops automatically.
+3.  **SSE (Streaming)**: Use `new EventSource(url)` for one-way streams (e.g., live logs, notifications).
+4.  **JSON Native**: Messages sent and received via `Odac.ws` are automatically parsed/stringified.
+
+## Reference Patterns
+
+### 1. Shared WebSocket (Cross-Tab)
+```javascript
+// One connection shared across all open tabs
+const ws = Odac.ws('/chat', { shared: true });
+
+ws.on('message', (data) => {
+  console.log('Update received in all tabs:', data);
+});
+
+// Sends message from current tab; others will receive the response
+ws.send({ type: 'chat', text: 'Hello World' });
+```
+
+### 2. Standard WebSocket (Per-Tab)
+```javascript
+const ws = Odac.ws('/game', { shared: false });
+ws.on('open', () => console.log('Game connected'));
+```
+
+### 3. Server-Sent Events (SSE)
+```javascript
+const source = new EventSource('/api/events');
+source.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  updateUI(data);
+};
+```
+
+## Best Practices
+-   **Resource Management**: Shared WebSocket automatically closes when the last tab using it is closed.
+-   **Fallback**: If `SharedWorker` is not supported (e.g., Safari), `Odac.ws` automatically falls back to a standard WebSocket.
+-   **Server-Side Hubs**: Ensure the backend uses `Odac.Hub` to send messages to the correct rooms or users.

package/docs/backend/10-authentication/01-user-logins-with-authjs.md

@@ -11,6 +11,8 @@ The `Odac.Auth` service is your bouncer, managing who gets in and who stays out.
 
 When you call this, `Auth` creates a secure session for the user.
 
+> **💡 Enterprise Security:** ODAC automatically handles **Token Rotation** every 15 minutes (configurable) and includes built-in **CSRF protection** for all forms. Sessions are persistent across browser restarts by default.
+
 #### Checking the Guest List
 
 *   `Odac.Auth.isLogin()`: Is the current user logged in? Returns `true` or `false`.

package/docs/backend/10-authentication/05-session-management.md

@@ -29,6 +29,20 @@ Sessions use a **sliding window** approach (similar to NextAuth.js):
 3. User inactive for 30 days, session expires
 4. Active users stay logged in indefinitely (up to 30 days of inactivity)
 
+### Token Rotation (Enterprise Grade)
+
+Odac implements a non-blocking **Refresh Token Rotation** mechanism to enhance security:
+
+- **rotationAge**: How often to rotate tokens (default: 15 minutes)
+- **Grace Period**: When a token is rotated, the old token remains valid for **60 seconds** to prevent race conditions in Single Page Applications (SPAs) making concurrent requests.
+
+**How it works:**
+1. A request is made with an active token older than `rotationAge`.
+2. Odac issues a brand new token set and sends them as cookies.
+3. The old token is marked as "rotated" and assigned a 60-second lütuf (grace) period.
+4. Subsequent concurrent requests using the old token still pass within those 60 seconds.
+5. After 60 seconds, the old token is naturally expired.
+
 ### Configuration
 
 Configure session behavior in `odac.json`:
@@ -39,21 +53,29 @@ Configure session behavior in `odac.json`:
     "table": "users",
     "token": "user_tokens",
     "maxAge": 2592000000,
-    "updateAge": 86400000
+    "updateAge": 86400000,
+    "rotationAge": 900000,
+    "rotation": true
   }
 }
 ```
 
 **Options:**
 
-- `maxAge` (milliseconds): Maximum inactivity period before session expires
+- `maxAge` (milliseconds): Maximum inactivity period before session expires. **Note:** Cookies also use this value for persistence.
   - Default: `2592000000` (30 days)
   - Example: `604800000` (7 days)
 
-- `updateAge` (milliseconds): How often to update the session timestamp
+- `updateAge` (milliseconds): How often to update the session timestamp (heartbeat)
   - Default: `86400000` (1 day)
   - Example: `3600000` (1 hour)
 
+- `rotationAge` (milliseconds): How often to rotate the session tokens
+  - Default: `900000` (15 minutes)
+
+- `rotation` (boolean): Enable or disable token rotation
+  - Default: `true`
+
 ### Common Configurations
 
 **Short sessions (banking apps):**

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/Auth.js

@@ -1,8 +1,11 @@
 const nodeCrypto = require('crypto')
+const ROTATED_TOKEN_EPOCH_THRESHOLD_MS = 31536000000
+const TOKEN_ROTATION_GRACE_PERIOD_MS = 60 * 1000
 class Auth {
   #request = null
   #table = null
   #user = null
+  static #migrationCache = new Set()
 
   constructor(request) {
     this.#request = request
@@ -98,7 +101,10 @@ class Auth {
 
       // Code First Migration: Ensure token table exists and clean up old tokens
       try {
-        await this.#ensureTokenTableV2(tokenTable)
+        if (!Auth.#migrationCache.has(tokenTable)) {
+          await this.#ensureTokenTableV2(tokenTable)
+          Auth.#migrationCache.add(tokenTable)
+        }
       } catch (e) {
         console.error('Odac Auth Error: Failed to ensure token table exists:', e.message)
       }
@@ -112,13 +118,21 @@ class Auth {
 
       const maxAge = Odac.Config.auth?.maxAge || 30 * 24 * 60 * 60 * 1000
       const updateAge = Odac.Config.auth?.updateAge || 24 * 60 * 60 * 1000
+      const rotationAge = Odac.Config.auth?.rotationAge || 15 * 60 * 1000 // Default 15 mins for rotation
+      const shouldRotate = Odac.Config.auth?.rotation !== false // Allow disabling rotation
       const now = Date.now()
 
       // Active comes as Date object usually from drivers
       const lastActive = new Date(sql_token[0].active).getTime()
+      const tokenDate = new Date(sql_token[0].date).getTime()
       const inactiveAge = now - lastActive
+      const tokenAge = now - tokenDate
+
+      // If date is before 1971, it's a marker for a rotated (grace period) token
+      const isRotated = tokenDate < ROTATED_TOKEN_EPOCH_THRESHOLD_MS
 
       if (inactiveAge > maxAge) {
+        // Naturally cleans up expired tokens and rotated tokens after grace period
         await Odac.DB[tokenTable].where('id', sql_token[0].id).delete()
         return false
       }
@@ -126,12 +140,63 @@ class Auth {
       this.#user = await Odac.DB[this.#table].where(primaryKey, sql_token[0].user).first()
       if (!this.#user) return false
 
-      if (inactiveAge > updateAge) {
-        // Use update instead of set for Knex
-        Odac.DB[tokenTable]
-          .where('id', sql_token[0].id)
-          .update({active: new Date()}) // knex uses .update
-          .catch(() => {})
+      if (!isRotated) {
+        if (shouldRotate && tokenAge > rotationAge) {
+          // --- Token Rotation ---
+          const newTokenX = nodeCrypto.randomBytes(32).toString('hex')
+          const newTokenY = nodeCrypto.randomBytes(32).toString('hex')
+          const newToken = {
+            id: Odac.DB.nanoid(),
+            user: sql_token[0].user,
+            token_x: newTokenX,
+            token_y: Odac.Var(newTokenY).hash(),
+            browser: sql_token[0].browser,
+            ip: this.#request.ip,
+            date: new Date(),
+            active: new Date()
+          }
+
+          // 1. Persist new token (await to ensure it exists before client uses new cookies)
+          const insertOk = await Odac.DB[tokenTable].insert(newToken).catch(e => {
+            console.error('Odac Auth Error: Token rotation failed', e.message)
+            return false
+          })
+
+          if (insertOk !== false) {
+            // 2. Mark old token as rotated and set exactly 60 seconds grace period
+            // Non-blocking I/O (Fire & Forget) -> High Throughput
+            const rotatedActiveDate = new Date(now - maxAge + TOKEN_ROTATION_GRACE_PERIOD_MS)
+            const epochDate = new Date(0)
+
+            Odac.DB[tokenTable]
+              .where('id', sql_token[0].id)
+              .update({
+                active: rotatedActiveDate,
+                date: epochDate
+              })
+              .catch(() => {})
+
+            // 3. Issue new cookies immediately
+            this.#request.cookie('odac_x', newTokenX, {
+              httpOnly: true,
+              secure: true,
+              sameSite: 'Lax',
+              maxAge: maxAge
+            })
+            this.#request.cookie('odac_y', newTokenY, {
+              httpOnly: true,
+              secure: true,
+              sameSite: 'Lax',
+              maxAge: maxAge
+            })
+          }
+        } else if (inactiveAge > updateAge) {
+          // Fallback simple active update if rotation is not triggered
+          Odac.DB[tokenTable]
+            .where('id', sql_token[0].id)
+            .update({active: new Date()})
+            .catch(() => {})
+        }
       }
 
       return true
@@ -143,11 +208,13 @@ class Auth {
     let user = await this.check(where)
     if (!user) return false
 
-    if (!Odac.Config.auth) Odac.Config.auth = {}
     let key = Odac.Config.auth.key || 'id'
     let token = Odac.Config.auth.token || 'odac_auth'
 
-    await this.#ensureTokenTableV2(token)
+    if (!Auth.#migrationCache.has(token)) {
+      await this.#ensureTokenTableV2(token)
+      Auth.#migrationCache.add(token)
+    }
 
     this.#cleanupExpiredTokens(token)
 
@@ -165,12 +232,20 @@ class Auth {
       ip: this.#request.ip
     }
 
+    const maxAge = Odac.Config.auth?.maxAge || 30 * 24 * 60 * 60 * 1000
+
     this.#request.cookie('odac_x', cookie.token_x, {
       httpOnly: true,
       secure: true,
-      sameSite: 'Lax'
+      sameSite: 'Lax',
+      maxAge: maxAge
+    })
+    this.#request.cookie('odac_y', token_y, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'Lax',
+      maxAge: maxAge
     })
-    this.#request.cookie('odac_y', token_y, {httpOnly: true, secure: true, sameSite: 'Lax'})
 
     // Knex insert returns ids on some dbs, promise resolves to result
     const result = await Odac.DB[token].insert(cookie)
@@ -199,7 +274,10 @@ class Auth {
     const uniqueFields = options.uniqueFields || ['email']
 
     try {
-      await this.#ensureUserTableV2(this.#table, primaryKey, passwordField, uniqueFields, data)
+      if (!Auth.#migrationCache.has(this.#table)) {
+        await this.#ensureUserTableV2(this.#table, primaryKey, passwordField, uniqueFields, data)
+        Auth.#migrationCache.add(this.#table)
+      }
     } catch (e) {
       // If DB not configured or connection failed
       console.error('Odac Auth Error:', e.message)
@@ -302,12 +380,16 @@ class Auth {
     if (!this.#user) return false
 
     if (!Odac.Config.auth) Odac.Config.auth = {}
-    const token = Odac.Config.auth.token || 'user_tokens'
+    const tokenTable = Odac.Config.auth.token || 'user_tokens'
+    const primaryKey = Odac.Config.auth.key || 'id'
     const odacX = this.#request.cookie('odac_x')
     const browser = this.#request.header('user-agent')
 
     if (odacX && browser) {
-      await Odac.DB[token].where('token_x', odacX).where('browser', browser).delete()
+      // Delete current token AND any rotated grace-period tokens for this user+browser
+      // Why: After rotation, the old token stays alive for ~60s. Explicit logout must kill it too.
+      const userId = this.#user[primaryKey]
+      await Odac.DB[tokenTable].where('user', userId).where('browser', browser).delete()
     }
 
     this.#request.cookie('odac_x', '', {maxAge: -1})
@@ -326,7 +408,10 @@ class Auth {
 
     // Ensure magic table exists
     try {
-      await this.#ensureMagicLinkTable(magicTable)
+      if (!Auth.#migrationCache.has(magicTable)) {
+        await this.#ensureMagicLinkTable(magicTable)
+        Auth.#migrationCache.add(magicTable)
+      }
     } catch (e) {
       console.error('Failed to ensure magic link table exists:', e)
       // Consider returning an error here to prevent further execution.

package/src/Route/Internal.js

@@ -541,23 +541,13 @@ class Internal {
 
     if (Odac.formConfig.action) {
       const actionParts = Odac.formConfig.action.split('.')
-      if (actionParts.length === 2) {
+      if (actionParts.length >= 2) {
         const controllerName = actionParts[0]
-        const methodName = actionParts[1]
-
-        // Dynamically load controller
-        // We need to access Odac.Route.class to find the controller path/module
-        // Or use require directly if we know the path structure.
-        // Since we are in framework/src/Route/Internal.js, controllers are in framework/controller/ OR app/controller/
-        // Ideally Odac.Route.class has the loaded controllers.
 
         let controllerModule = null
 
         if (Odac.Route && Odac.Route.class && Odac.Route.class[controllerName]) {
           controllerModule = Odac.Route.class[controllerName].module
-        } else {
-          // Try to require it if not loaded (though Route.js should have loaded it)
-          // This fallback might be tricky with absolute paths, relying on Route.class is safer.
         }
 
         if (controllerModule) {
@@ -605,16 +595,29 @@ class Internal {
               }
             }
 
-            // Handle Class-based Controller
+            let method = controllerModule
+            let context = null
+            let isClass = false
+
             if (typeof controllerModule === 'function' && controllerModule.prototype) {
-              const instance = new controllerModule(Odac)
-              if (typeof instance[methodName] === 'function') {
-                return await instance[methodName](formHelper)
+              isClass = true
+              context = new controllerModule(Odac)
+              method = context
+            }
+
+            for (let i = 1; i < actionParts.length; i++) {
+              if (method) {
+                context = method
+                method = method[actionParts[i]]
               }
             }
-            // Handle Object-based Controller (Backwards Compatibility)
-            else if (typeof controllerModule[methodName] === 'function') {
-              return await controllerModule[methodName](Odac, formHelper)
+
+            if (typeof method === 'function') {
+              if (isClass) {
+                return await method.call(context, formHelper)
+              } else {
+                return await method.call(context, Odac, formHelper)
+              }
             }
           } catch (e) {
             console.error(e)

package/src/Route/MimeTypes.js

@@ -0,0 +1,56 @@
+module.exports = {
+  html: 'text/html',
+  css: 'text/css',
+  js: 'text/javascript',
+  json: 'application/json',
+  png: 'image/png',
+  jpg: 'image/jpg',
+  jpeg: 'image/jpeg',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  mp3: 'audio/mpeg',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  eot: 'font/eot',
+  pdf: 'application/pdf',
+  zip: 'application/zip',
+  tar: 'application/x-tar',
+  gz: 'application/gzip',
+  rar: 'application/x-rar-compressed',
+  '7z': 'application/x-7z-compressed',
+  txt: 'text/plain',
+  log: 'text/plain',
+  csv: 'text/csv',
+  xml: 'text/xml',
+  rss: 'application/rss+xml',
+  atom: 'application/atom+xml',
+  yaml: 'application/x-yaml',
+  sh: 'application/x-sh',
+  bat: 'application/x-bat',
+  exe: 'application/x-exe',
+  bin: 'application/x-binary',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  avi: 'video/x-msvideo',
+  wmv: 'video/x-ms-wmv',
+  flv: 'video/x-flv',
+  webp: 'image/webp',
+  gif: 'image/gif',
+  bmp: 'image/bmp',
+  tiff: 'image/tiff',
+  tif: 'image/tiff',
+  weba: 'audio/webm',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  flac: 'audio/flac',
+  aac: 'audio/aac',
+  midi: 'audio/midi'
+}

package/src/Route.js

@@ -7,62 +7,7 @@ const MiddlewareChain = require('./Route/Middleware.js')
 const {WebSocketServer} = require('./WebSocket.js')
 
 var routes2 = {}
-const mime = {
-  html: 'text/html',
-  css: 'text/css',
-  js: 'text/javascript',
-  json: 'application/json',
-  png: 'image/png',
-  jpg: 'image/jpg',
-  jpeg: 'image/jpeg',
-  svg: 'image/svg+xml',
-  ico: 'image/x-icon',
-  mp3: 'audio/mpeg',
-  mp4: 'video/mp4',
-  webm: 'video/webm',
-  woff: 'font/woff',
-  woff2: 'font/woff2',
-  ttf: 'font/ttf',
-  otf: 'font/otf',
-  eot: 'font/eot',
-  pdf: 'application/pdf',
-  zip: 'application/zip',
-  tar: 'application/x-tar',
-  gz: 'application/gzip',
-  rar: 'application/x-rar-compressed',
-  '7z': 'application/x-7z-compressed',
-  txt: 'text/plain',
-  log: 'text/plain',
-  csv: 'text/csv',
-  xml: 'text/xml',
-  rss: 'application/rss+xml',
-  atom: 'application/atom+xml',
-  yaml: 'application/x-yaml',
-  sh: 'application/x-sh',
-  bat: 'application/x-bat',
-  exe: 'application/x-exe',
-  bin: 'application/x-binary',
-  doc: 'application/msword',
-  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-  xls: 'application/vnd.ms-excel',
-  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-  ppt: 'application/vnd.ms-powerpoint',
-  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-  avi: 'video/x-msvideo',
-  wmv: 'video/x-ms-wmv',
-  flv: 'video/x-flv',
-  webp: 'image/webp',
-  gif: 'image/gif',
-  bmp: 'image/bmp',
-  tiff: 'image/tiff',
-  tif: 'image/tiff',
-  weba: 'audio/webm',
-  wav: 'audio/wav',
-  ogg: 'audio/ogg',
-  flac: 'audio/flac',
-  aac: 'audio/aac',
-  midi: 'audio/midi'
-}
+const mime = require('./Route/MimeTypes.js')
 
 class Route {
   loading = false
@@ -122,15 +67,37 @@ class Route {
     if (middlewareResult !== undefined) return middlewareResult
 
     if (controller.action) {
-      const ControllerClass = controller.cache
+      const ControllerModule = controller.cache
+      const actionParts = controller.action.split('.')
+
       try {
-        const instance = new ControllerClass(Odac)
-        if (typeof instance[controller.action] === 'function') {
-          return instance[controller.action](Odac)
+        const instance = new ControllerModule(Odac)
+        let method = instance
+        let context = instance
+
+        for (const segment of actionParts) {
+          if (method) {
+            context = method
+            method = method[segment]
+          }
+        }
+
+        if (typeof method === 'function') {
+          return method.call(context, Odac)
         }
       } catch {
-        if (typeof ControllerClass[controller.action] === 'function') {
-          return ControllerClass[controller.action](Odac)
+        let method = ControllerModule
+        let context = ControllerModule
+
+        for (const segment of actionParts) {
+          if (method) {
+            context = method
+            method = method[segment]
+          }
+        }
+
+        if (typeof method === 'function') {
+          return method.call(context, Odac)
         }
       }
       return Odac.Request.abort(500)
@@ -144,6 +111,9 @@ class Route {
   async check(Odac) {
     let url = Odac.Request.url.split('?')[0]
     if (url.endsWith('/')) url = url.slice(0, -1)
+    // Global Auth Check: Load user if valid tokens exist to simplify DX
+    // This allows calling Odac.Auth.user() anywhere without manual await Odac.Auth.check()
+    if (Odac.Auth) await Odac.Auth.check()
 
     if (url.startsWith('/_odac/')) {
       Odac.Request.route = '_odac_internal'
@@ -882,8 +852,15 @@ class Route {
         }
       })
 
+      // Global Auth Check: Load user if valid tokens exist to simplify DX
+      // This allows calling Odac.Auth.user() anywhere without manual await Odac.Auth.check()
+      if (Odac.Auth) await Odac.Auth.check()
+
       if (requireAuth) {
-        const isAuthenticated = await Odac.Auth.check()
+        let isAuthenticated = false
+        if (Odac.Auth) {
+          isAuthenticated = await Odac.Auth.check()
+        }
         if (!isAuthenticated) {
           ws.close(4001, 'Unauthorized')
           return