odac 1.4.2 → 1.4.3

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+### ⚙️ Engine Tuning
+
+- **client:** extract ws connection logic and fix recursive sharedworker reconnects reconnect bug
+- **client:** remove redundant truthy check for websocket token
+- **route:** remove useless variable assignment for decodedUrl
+
+### ⚡️ Performance Upgrades
+
+- **client:** remove redundant token consumption during websocket initialization
+
+### 📚 Documentation
+
+- **README:** enhance security section with detailed CSRF protection features
+
+### 🛠️ Fixes & Improvements
+
+- **client:** enhance websocket reconnection logic with attempt tracking and timer management
+- **client:** preserve existing websocket subprotocols & add try/catch layer to token provider
+- **route:** improve URL decoding and public path handling for file requests
+- **route:** sanitize decoded URL and improve public path validation
+- **route:** use robust path.extname instead of string splitting for mime type resolution
+- **websocket:** implement token provider for dynamic token handling on reconnect
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### doc
 
 - **forms:** update backend and frontend forms documentation with practical usage patterns and improved descriptions

package/README.md

@@ -9,7 +9,7 @@
 *   🎨 **Built-in Tailwind CSS:** Zero-config integration with Tailwind CSS v4. Automatic compilation and optimization out of the box.
 *   🔗 **Powerful Routing:** Create clean, custom URLs and manage infinite pages with a flexible routing system.
 *   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions eliminates the need for complex client-side code.
-*   🛡️ **Built-in Security:** Automatic CSRF protection and secure default headers keep your application safe.
+*   🛡️ **Built-in Security:** Enterprise-grade security out of the box. Includes secure default headers and a **Multi-tab Safe, Single-Use CSRF Protection (Nonce)**. Tokens self-replenish in the background, ensuring maximum defense without ever interrupting the user experience.
 *   🔐 **Authentication:** Ready-to-use session management with enterprise-grade **Refresh Token Rotation**, secure password hashing, and authentication helpers.
 *   🗄️ **Database Agnostic:** Integrated support for major databases (PostgreSQL, MySQL, SQLite) and Redis via Knex.js.
 *   🌍 **i18n Support:** Native multi-language support to help you reach a global audience.

package/client/odac.js

@@ -7,10 +7,12 @@ class OdacWebSocket {
   #reconnectAttempts = 0
   #handlers = {}
   #isClosed = false
+  #tokenProvider = null
 
   constructor(url, protocols = [], options = {}) {
     this.#url = url
     this.#protocols = protocols
+    this.#tokenProvider = options.tokenProvider || null
     this.#options = {
       autoReconnect: true,
       reconnectDelay: 3000,
@@ -23,6 +25,19 @@ class OdacWebSocket {
   connect() {
     if (this.#isClosed) return
 
+    if (this.#tokenProvider) {
+      try {
+        const freshToken = this.#tokenProvider()
+        if (freshToken) {
+          let current = Array.isArray(this.#protocols) ? this.#protocols : this.#protocols ? [this.#protocols] : []
+          this.#protocols = current.filter(p => !p.startsWith('odac-token-'))
+          this.#protocols.push(`odac-token-${freshToken}`)
+        }
+      } catch (e) {
+        console.error('Odac WebSocket tokenProvider error:', e)
+      }
+    }
+
     this.#socket = this.#protocols.length > 0 ? new WebSocket(this.#url, this.#protocols) : new WebSocket(this.#url)
 
     this.#socket.onopen = () => {
@@ -924,12 +939,9 @@ if (typeof window !== 'undefined') {
       const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
       const wsUrl = `${protocol}//${window.location.host}${path}`
       const protocols = []
-      if (token) {
-        const csrfToken = this.token()
-        if (csrfToken) protocols.push(`odac-token-${csrfToken}`)
-      }
+      const tokenProvider = token ? () => this.token() : null
 
-      return new OdacWebSocket(wsUrl, protocols, options)
+      return new OdacWebSocket(wsUrl, protocols, {...options, tokenProvider})
     }
 
     #createSharedWebSocket(path, options) {
@@ -966,6 +978,9 @@ if (typeof window !== 'undefined') {
           case 'error':
             emit('error', data)
             break
+          case 'requestToken':
+            worker.port.postMessage({type: 'provideToken', token: this.token()})
+            break
         }
       }
 
@@ -1031,6 +1046,67 @@ if (typeof window !== 'undefined') {
 
   const broadcast = (type, data) => ports.forEach(port => port.postMessage({type, data}))
 
+  let wsConfig = null
+  let reconnectAttempts = 0
+  let reconnectTimer = null
+
+  const requestTokenFromPort = () => {
+    return new Promise(resolve => {
+      const firstPort = ports.values().next().value
+      if (!firstPort) return resolve(null)
+
+      let timeoutTimer = null
+
+      const handler = event => {
+        if (event.data.type === 'provideToken') {
+          clearTimeout(timeoutTimer)
+          firstPort.removeEventListener('message', handler)
+          resolve(event.data.token)
+        }
+      }
+
+      timeoutTimer = setTimeout(() => {
+        firstPort.removeEventListener('message', handler)
+        resolve(null)
+      }, 5000)
+
+      firstPort.addEventListener('message', handler)
+      firstPort.postMessage({type: 'requestToken'})
+    })
+  }
+
+  const connectSocket = protocols => {
+    if (!wsConfig || ports.size === 0) return
+    const wsUrl = wsConfig.protocol + '//' + wsConfig.host + wsConfig.path
+    socket = new OdacWebSocket(wsUrl, protocols, {
+      ...wsConfig.options,
+      tokenProvider: null
+    })
+    socket.on('open', () => {
+      reconnectAttempts = 0
+      broadcast('open')
+    })
+    socket.on('message', data => broadcast('message', data))
+    socket.on('close', e => {
+      broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean})
+      const maxAttempts = wsConfig.options.maxReconnectAttempts || 10
+      if (wsConfig && wsConfig.options.autoReconnect !== false && ports.size > 0 && reconnectAttempts < maxAttempts) {
+        if (socket) {
+          socket.close()
+          socket = null
+        }
+        reconnectAttempts++
+        reconnectTimer = setTimeout(() => {
+          requestTokenFromPort().then(freshToken => {
+            if (!freshToken || ports.size === 0) return
+            connectSocket(['odac-token-' + freshToken])
+          })
+        }, wsConfig.options.reconnectDelay || 1000)
+      }
+    })
+    socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
+  }
+
   self.onconnect = e => {
     const port = e.ports[0]
     ports.add(port)
@@ -1041,15 +1117,10 @@ if (typeof window !== 'undefined') {
       switch (type) {
         case 'connect':
           if (!socket) {
-            const wsUrl = protocol + '//' + host + path
+            wsConfig = {host, path, protocol, options}
             const protocols = token ? ['odac-token-' + token] : []
-            socket = new OdacWebSocket(wsUrl, protocols, options)
-            socket.on('open', () => broadcast('open'))
-            socket.on('message', data => broadcast('message', data))
-            socket.on('close', e => broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean}))
-            socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
+            connectSocket(protocols)
           } else if (socket.connected) {
-            // If already connected, notify the new port immediately
             port.postMessage({type: 'open'})
           }
           break
@@ -1058,9 +1129,15 @@ if (typeof window !== 'undefined') {
           break
         case 'close':
           ports.delete(port)
-          if (ports.size === 0 && socket) {
-            socket.close()
-            socket = null
+          if (ports.size === 0) {
+            if (reconnectTimer) {
+              clearTimeout(reconnectTimer)
+              reconnectTimer = null
+            }
+            if (socket) {
+              socket.close()
+              socket = null
+            }
           }
           break
       }

package/package.json

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

package/src/Route.js

@@ -1,5 +1,6 @@
 const fs = require('fs')
 const fsPromises = fs.promises
+const path = require('path')
 
 const Cron = require('./Route/Cron.js')
 const Internal = require('./Route/Internal.js')
@@ -219,42 +220,52 @@ class Route {
       if (typeof page === 'string') Odac.Request.page = page
       return await this.#executeController(Odac, pageController)
     }
-    if (url && !url.includes('/../')) {
-      const publicPath = `${__dir}/public${url}`
 
-      // PROD CACHE HIT (Metadata)
-      if (!Odac.Config.debug && this.#publicCache[publicPath]) {
-        const cached = this.#publicCache[publicPath]
-        Odac.Request.header('Content-Type', cached.type)
-        Odac.Request.header('Cache-Control', 'public, max-age=31536000')
-        Odac.Request.header('Content-Length', cached.size)
-        return fs.createReadStream(publicPath)
-      }
+    let decodedUrl
+    try {
+      decodedUrl = decodeURIComponent(url)
+    } catch {
+      decodedUrl = null // Invalid URI encoding
+    }
 
-      try {
-        const stat = await fsPromises.stat(publicPath)
-        if (stat.isFile()) {
-          let type = 'text/html'
-          if (url.includes('.')) {
-            let arr = url.split('.')
-            type = mime[arr[arr.length - 1]]
-          }
+    if (decodedUrl && !decodedUrl.includes('\0')) {
+      const publicDir = path.normalize(`${__dir}/public`)
+      const safeUrl = decodedUrl.replace(/^[/\\]+/, '')
+      const publicPath = path.normalize(path.join(publicDir, safeUrl))
+      const relativePath = path.relative(publicDir, publicPath)
 
-          // PROD CACHE SET (Metadata Only)
-          if (!Odac.Config.debug) {
-            this.#publicCache[publicPath] = {
-              type,
-              size: stat.size
-            }
-          }
-
-          Odac.Request.header('Content-Type', type)
+      if (relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath))) {
+        // PROD CACHE HIT (Metadata)
+        if (!Odac.Config.debug && this.#publicCache[publicPath]) {
+          const cached = this.#publicCache[publicPath]
+          Odac.Request.header('Content-Type', cached.type)
           Odac.Request.header('Cache-Control', 'public, max-age=31536000')
-          Odac.Request.header('Content-Length', stat.size)
+          Odac.Request.header('Content-Length', cached.size)
           return fs.createReadStream(publicPath)
         }
-      } catch {
-        // File not found in public
+
+        try {
+          const stat = await fsPromises.stat(publicPath)
+          if (stat.isFile()) {
+            const extension = path.extname(publicPath).slice(1)
+            const type = mime[extension] || 'text/html'
+
+            // PROD CACHE SET (Metadata Only)
+            if (!Odac.Config.debug) {
+              this.#publicCache[publicPath] = {
+                type,
+                size: stat.size
+              }
+            }
+
+            Odac.Request.header('Content-Type', type)
+            Odac.Request.header('Cache-Control', 'public, max-age=31536000')
+            Odac.Request.header('Content-Length', stat.size)
+            return fs.createReadStream(publicPath)
+          }
+        } catch {
+          // File not found in public
+        }
       }
     }
 

package/test/Client/ws.test.js

@@ -83,4 +83,36 @@ describe('Odac.ws()', () => {
     socketInstance.onopen()
     expect(openHandler).toHaveBeenCalled()
   })
+
+  test('should use fresh token on reconnect', () => {
+    let tokenCounter = 0
+    mockXhr.response = JSON.stringify({token: 'initial-token'})
+    mockXhr.responseText = JSON.stringify({token: 'initial-token'})
+    mockXhr.onload = null
+    mockXhr.send = jest.fn(function () {
+      tokenCounter++
+      this.response = JSON.stringify({token: `token-${tokenCounter}`})
+      this.responseText = this.response
+      if (this.onload) this.onload()
+    })
+    mockDocument.cookie = 'odac_client=test-client'
+
+    window.Odac.ws('/test-ws', {token: true, autoReconnect: true, reconnectDelay: 100})
+    const firstCall = WebSocket.mock.calls[0]
+    expect(firstCall[1]).toEqual(expect.arrayContaining([expect.stringMatching(/^odac-token-/)]))
+    const firstToken = firstCall[1][0]
+
+    const socketInstance = WebSocket.mock.results[0].value
+    socketInstance.onopen()
+
+    global.setTimeout = jest.fn(fn => fn())
+    socketInstance.readyState = 3
+    socketInstance.onclose({code: 1006})
+
+    expect(WebSocket.mock.calls.length).toBeGreaterThan(1)
+    const secondCall = WebSocket.mock.calls[1]
+    expect(secondCall[1]).toEqual(expect.arrayContaining([expect.stringMatching(/^odac-token-/)]))
+    const secondToken = secondCall[1][0]
+    expect(secondToken).not.toBe(firstToken)
+  })
 })

package/test/Route/check.test.js

@@ -308,4 +308,105 @@ describe('Route.check()', () => {
       expect(paramHandler).not.toHaveBeenCalled()
     })
   })
+
+  describe('public static file serving', () => {
+    const fs = require('fs')
+    const path = require('path')
+
+    const createMockOdac = url => ({
+      Auth: {check: jest.fn().mockResolvedValue(true)},
+      Config: {debug: true},
+      Request: {
+        url,
+        method: 'get',
+        route: 'test_route',
+        header: jest.fn(),
+        cookie: jest.fn(() => null),
+        abort: jest.fn(),
+        setSession: jest.fn(),
+        data: {url: {}}
+      },
+      request: jest.fn().mockResolvedValue(null)
+    })
+
+    beforeEach(() => {
+      global.__dir = '/app'
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    it('should serve a public static file successfully', async () => {
+      const mockStat = jest.spyOn(fs.promises, 'stat').mockResolvedValue({isFile: () => true, size: 1024})
+      const mockStream = {pipe: jest.fn()}
+      const mockCreateReadStream = jest.spyOn(fs, 'createReadStream').mockReturnValue(mockStream)
+      const expectedPath = path.normalize('/app/public/style.css')
+
+      const mockOdac = createMockOdac('/style.css')
+      const result = await route.check(mockOdac)
+
+      expect(mockStat).toHaveBeenCalledWith(expectedPath)
+      expect(mockOdac.Request.header).toHaveBeenCalledWith('Content-Type', 'text/css')
+      expect(mockOdac.Request.header).toHaveBeenCalledWith('Content-Length', 1024)
+      expect(mockCreateReadStream).toHaveBeenCalledWith(expectedPath)
+      expect(result).toBe(mockStream)
+    })
+
+    it('should prevent path traversal attacks', async () => {
+      const mockStat = jest.spyOn(fs.promises, 'stat')
+
+      const mockOdac = createMockOdac('/../secrets.txt')
+      const result = await route.check(mockOdac)
+
+      expect(mockStat).not.toHaveBeenCalled()
+      expect(result).toBeUndefined() // Falls through if blocked
+    })
+
+    it('should prevent null byte injection attacks', async () => {
+      const mockStat = jest.spyOn(fs.promises, 'stat')
+
+      const mockOdac = createMockOdac('/style%00.css')
+      const result = await route.check(mockOdac)
+
+      expect(mockStat).not.toHaveBeenCalled()
+      expect(result).toBeUndefined()
+    })
+
+    it('should handle invalid URI encoding gracefully', async () => {
+      const mockStat = jest.spyOn(fs.promises, 'stat')
+
+      const mockOdac = createMockOdac('/%E0%A4%A') // Invalid URL encoded string
+      const result = await route.check(mockOdac)
+
+      expect(mockStat).not.toHaveBeenCalled()
+      expect(result).toBeUndefined()
+    })
+
+    it('should cache metadata in production mode', async () => {
+      jest.spyOn(fs.promises, 'stat').mockResolvedValue({isFile: () => true, size: 2048})
+      const mockCreateReadStream = jest.spyOn(fs, 'createReadStream').mockReturnValue('mock_stream')
+
+      const mockOdac = createMockOdac('/script.js')
+      mockOdac.Config.debug = false // prod mode
+
+      // first call (cache miss -> set cache)
+      await route.check(mockOdac)
+      expect(fs.promises.stat).toHaveBeenCalledTimes(1)
+      expect(mockOdac.Request.header).toHaveBeenCalledWith('Content-Type', 'text/javascript')
+
+      // reset mock tracking (cache hit -> no stat)
+      jest.clearAllMocks()
+      jest.spyOn(fs, 'createReadStream').mockReturnValue('mock_stream_2')
+
+      // second call
+      const result2 = await route.check(mockOdac)
+
+      expect(fs.promises.stat).not.toHaveBeenCalled() // Not called because metadata is cached
+      expect(mockOdac.Request.header).toHaveBeenCalledWith('Content-Type', 'text/javascript')
+      expect(mockOdac.Request.header).toHaveBeenCalledWith('Content-Length', 2048)
+      expect(mockCreateReadStream).toHaveBeenCalledWith(path.normalize('/app/public/script.js'))
+      expect(result2).toBe('mock_stream_2')
+    })
+  })
 })