odac 1.1.0 → 1.2.0

package/docs/backend/07-views/10-styling-and-tailwind.md

@@ -0,0 +1,93 @@
+# 🎨 Styling & Tailwind CSS
+
+Odac comes with built-in, **Zero-Config** support for Tailwind CSS v4. This means you can start building beautiful, modern interfaces right out of the box without messing with configuration files or build pipelines.
+
+## How it Works
+
+The framework adopts a "Convention over Configuration" approach:
+
+1.  **Development (`npm run dev`)**:
+    *   The framework automatically watches your HTML, JS, and View files.
+    *   It compiles your CSS classes using the high-performance Rust-based Tailwind CLI.
+    *   Changes are reflected instantly.
+
+2.  **Production (`npm run build`)**:
+    *   The framework scans your project, builds the final CSS, and minifies it.
+    *   The output is saved to `public/assets/css/app.css`.
+
+3.  **Serving (`npm start`)**:
+    *   The compiled CSS file is served statically. No background processes, no overhead.
+
+## Customizing CSS
+
+By default, Odac manages everything for you internally. However, if you need to add custom CSS, fonts, or Tailwind configuration (like `@theme`), you can do so easily.
+
+### The Source File
+
+Simply create a file at **`view/css/app.css`**.
+
+If this file exists, Odac will use it as the **source** (input) for Tailwind.
+
+**Example `view/css/app.css`:**
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --font-display: "Satoshi", "sans-serif";
+  --color-brand: #ff5733;
+}
+
+/* Your custom CSS rules */
+.hero-gradient {
+  background: linear-gradient(to right, var(--color-brand), #ff0000);
+}
+```
+
+### The Output File
+
+The compiled CSS is always output to:
+**`public/assets/css/app.css`**
+
+> **⚠️ Important:** Never edit `public/assets/css/app.css` manually. It is a generated file and will be overwritten by Odac during build or development. Always edit `view/css/app.css` instead.
+
+## HTML Integration
+
+In your layout files (e.g., `view/head/main.html`), simply link to the compiled asset:
+
+```html
+<link rel="stylesheet" href="/assets/css/app.css" />
+```
+
+This is already set up for you in the default project template.
+
+## Multiple CSS Files
+
+Odac supports multiple CSS entry points. If your application has distinct sections (e.g., a Landing Page, a Dashboard, and an Admin Panel) that require separate stylesheets, you can organize them easily.
+
+### How to use
+
+Any `.css` file you place in the **`view/css/`** directory will be automatically detected, watched, and compiled by Odac.
+
+**Input:**
+*   `view/css/app.css`
+*   `view/css/admin.css`
+*   `view/css/landing.css`
+
+**Output (Compiled):**
+*   `public/assets/css/app.css`
+*   `public/assets/css/admin.css`
+*   `public/assets/css/landing.css`
+
+You can then link each specific stylesheet in its respective layout file:
+
+```html
+<!-- In Admin Layout -->
+<link rel="stylesheet" href="/assets/css/admin.css" />
+```
+
+## Using Tailwind v4
+
+Tailwind v4 is radically simpler. You generally don't need a `tailwind.config.js` file anymore. You can define your theme directly in CSS using the `@theme` block as shown above.
+
+However, Odac respects standard Tailwind behavior. If you absolutely need a config file for plugins or legacy reasons, you can create one, and the Tailwind CLI will detect it. But for 99% of use cases, the Zero-Config approach is cleaner and faster.

package/docs/backend/08-database/01-getting-started.md

@@ -4,7 +4,7 @@ ODAC supports multiple database connections including **MySQL**, **PostgreSQL**
 
 ## Configuration
 
-Add your database credentials to `config.json`.
+Add your database credentials to `odac.json`.
 
 Supported configuration options:
 
@@ -79,7 +79,7 @@ DB_USER=myuser
 DB_PASSWORD=mypassword
 ```
 
-**config.json:**
+**odac.json:**
 ```json
 {
   "database": {

package/docs/backend/10-authentication/03-register.md

@@ -113,7 +113,7 @@ module.exports = async function (Odac) {
 
 ## Configuration
 
-Make sure your `config.json` has the auth configuration:
+Make sure your `odac.json` has the auth configuration:
 
 ```json
 {

package/docs/backend/10-authentication/04-odac-register-forms.md

@@ -4,7 +4,7 @@ The `<odac:register>` component provides a zero-configuration way to create secu
 
 ## Quick Start
 
-### 1. Configure Database (config.json)
+### 1. Configure Database (odac.json)
 
 ```json
 {
@@ -653,7 +653,7 @@ Then handle the response in JavaScript if needed (though not required for basic
 
 ### Form Not Submitting
 
-- Check that `config.json` has auth configuration
+- Check that `odac.json` has auth configuration
 - Verify database table exists
 - Check browser console for JavaScript errors
 

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

@@ -31,7 +31,7 @@ Sessions use a **sliding window** approach (similar to NextAuth.js):
 
 ### Configuration
 
-Configure session behavior in `config.json`:
+Configure session behavior in `odac.json`:
 
 ```json
 {
@@ -127,9 +127,23 @@ const isLoggedIn = await Odac.Auth.check()
 **Get user info:**
 ```javascript
 const user = Odac.Auth.user(null)  // Full user object
+const user = Odac.Auth.user(null)  // Full user object
 const email = Odac.Auth.user('email')  // Specific field
 ```
 
+### Custom Session Data
+
+If you need to store your own data in the session (e.g. shopping cart ID, preferences), use the `Odac.session()` helper:
+
+```javascript
+// Store data
+Odac.session('theme', 'dark')
+
+// Retrieve data
+const theme = Odac.session('theme')
+```
+
+
 ### Best Practices
 
 1. **Choose appropriate timeouts** based on your app's security needs

package/docs/backend/10-authentication/06-odac-login-forms.md

@@ -4,7 +4,7 @@ The `<odac:login>` component provides a zero-configuration way to create secure
 
 ## Quick Start
 
-### 1. Configure Database (config.json)
+### 1. Configure Database (odac.json)
 
 ```json
 {
@@ -559,7 +559,7 @@ The login form supports multiple authentication methods:
 
 ### Form Not Submitting
 
-- Check that `config.json` has MySQL configuration
+- Check that `odac.json` has MySQL configuration
 - Verify database table exists
 - Check browser console for JavaScript errors
 - Ensure CSRF token is valid

package/docs/backend/10-authentication/07-magic-links.md

@@ -79,7 +79,7 @@ Odac handles the verification route automatically at `/_odac/magic-verify`. Howe
 
 ## Configuration
 
-Magic links usage is configured in your `config.json` file under the `auth` object.
+Magic links usage is configured in your `odac.json` file under the `auth` object.
 
 ```json
 {

package/docs/index.json

@@ -14,7 +14,7 @@
         },
         {
           "file": "03-development-server.md",
-          "title": "Development Server"
+          "title": "CLI Commands & Deployment"
         }
       ]
     },
@@ -201,6 +201,10 @@
         {
           "file": "09-comments.md",
           "title": "Comments"
+        },
+        {
+          "file": "10-styling-and-tailwind.md",
+          "title": "Styling & Tailwind CSS"
         }
       ]
     },

package/jest.config.js

@@ -5,7 +5,7 @@ const config = {
   testMatch: ['**/test/**/*.test.js', '**/?(*.)+(spec|test).js'],
   collectCoverage: true,
   coverageDirectory: 'coverage',
-  collectCoverageFrom: ['core/**/*.js', 'server/**/*.js']
+  collectCoverageFrom: ['src/**/*.js', 'client/**/*.js']
   // Coverage thresholds disabled - focus on test pass/fail only
   // Coverage is still collected and reported, but doesn't block commits
   // This allows incremental test development without artificial barriers

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -21,13 +21,17 @@
     "url": "https://github.com/odac-run/odac.js.git"
   },
   "dependencies": {
-    "axios": "^1.7.9",
-    "bcrypt": "^5.1.1",
+    "@tailwindcss/cli": "^4.1.18",
     "knex": "^3.1.0",
     "lmdb": "^3.4.4",
     "mysql2": "^3.16.0",
     "pg": "^8.16.3",
-    "redis": "^5.10.0"
+    "redis": "^5.10.0",
+    "tailwindcss": "^4.1.18"
+  },
+  "overrides": {
+    "tar": "^7.5.7",
+    "undici": "^6.23.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
@@ -35,7 +39,7 @@
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.2",
-    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/npm": "^13.1.2",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "conventional-changelog-conventionalcommits": "^9.1.0",
     "eslint": "^9.33.0",

package/src/Auth.js

@@ -35,29 +35,54 @@ class Auth {
 
       // Knex build queries differently than previous builder
       // Need to chain where clauses
-      for (let key in where) {
-        query = query.orWhere(key, where[key] instanceof Promise ? await where[key] : where[key])
+      // Resolve input promises upfront to avoid side effects and race conditions
+      const criteria = {}
+      const keys = Object.keys(where)
+
+      if (keys.length === 0) return false
+
+      for (const key of keys) {
+        criteria[key] = where[key] instanceof Promise ? await where[key] : where[key]
+      }
+
+      // Chain where clauses
+      for (const key in criteria) {
+        query = query.orWhere(key, criteria[key])
       }
 
       // Execute query
-      let get = await query
-
-      if (!get || get.length === 0) return false
-
-      let equal = false
-      for (var user of get) {
-        equal = Object.keys(where).length > 0
-        for (let key of Object.keys(where)) {
-          if (where[key] instanceof Promise) where[key] = await where[key]
-          if (!user[key]) equal = false
-          if (user[key] === where[key]) equal = equal && true
-          else if (Odac.Var(user[key]).is('bcrypt')) equal = equal && Odac.Var(user[key]).hashCheck(where[key])
-          else if (Odac.Var(user[key]).is('md5')) equal = equal && Odac.Var(where[key]).md5() === user[key]
+      const candidates = await query
+
+      if (!candidates || candidates.length === 0) return false
+
+      // Iterate candidates to find the exact match
+      candidateLoop: for (const user of candidates) {
+        for (const key of keys) {
+          const userValue = user[key]
+          const targetValue = criteria[key]
+
+          if (!userValue) continue candidateLoop
+
+          // Strict equality check
+          if (userValue === targetValue) continue
+
+          // Security: Check hashed fields (Bcrypt/MD5)
+          const valueHandler = Odac.Var(userValue)
+          let hashMatch = false
+
+          if (valueHandler.is('hash')) {
+            hashMatch = valueHandler.hashCheck(targetValue)
+          } else if (valueHandler.is('md5')) {
+            hashMatch = Odac.Var(targetValue).md5() === userValue
+          }
+
+          if (!hashMatch) continue candidateLoop
         }
-        if (equal) break
+
+        return user
       }
-      if (!equal) return false
-      return user
+
+      return false
     } else if (this.#user) {
       return true
     } else {
@@ -126,12 +151,15 @@ class Auth {
 
     this.#cleanupExpiredTokens(token)
 
-    let token_y = Odac.Var(Math.random().toString() + Date.now().toString() + this.#request.id + this.#request.ip).md5()
+    // Generate secure token using generic CSPRNG (Cryptographically Secure Pseudo-Random Number Generator)
+    // Why: Math.random() is predictable and MD5 is a broken hashing algorithm.
+    // We use 32 bytes (256 bits) of entropy which is industry standard.
+    let token_y = nodeCrypto.randomBytes(32).toString('hex')
 
     let cookie = {
       id: Odac.DB.nanoid(),
       user: user[key],
-      token_x: Odac.Var(Math.random().toString() + Date.now().toString()).md5(),
+      token_x: nodeCrypto.randomBytes(32).toString('hex'),
       token_y: Odac.Var(token_y).hash(),
       browser: this.#request.header('user-agent'),
       ip: this.#request.ip
@@ -182,7 +210,7 @@ class Auth {
       return {success: false, error: 'Invalid data provided'}
     }
 
-    if (data[passwordField] && !Odac.Var(data[passwordField]).is('bcrypt')) {
+    if (data[passwordField] && !Odac.Var(data[passwordField]).is('hash')) {
       data[passwordField] = Odac.Var(data[passwordField]).hash()
     }
 
@@ -557,10 +585,17 @@ class Auth {
     })
   }
 
-  user(col) {
+  /**
+   * Retrieves the authenticated user or a specific column.
+   * Why: To provide access to the current user's session data securely.
+   *
+   * @param {string|null} [col=null] - The column to retrieve, or null for the full user object.
+   * @returns {object|string|number|boolean|false} The user object, column value, or false if not logged in.
+   */
+  user(col = null) {
     if (!this.#user) return false
     if (col === null) return this.#user
-    else return this.#user[col]
+    return this.#user[col]
   }
 }
 

package/src/Config.js

@@ -5,13 +5,13 @@ const os = require('os')
 module.exports = {
   auth: {
     key: 'id',
-    token: 'odac_auth'
+    token: 'odac_auth' // This is the TABLE NAME for tokens, not a secret token.
   },
   request: {
     timeout: 10000
   },
   encrypt: {
-    key: 'odac'
+    key: 'odac' // Default encryption key. MUST be overridden in production.
   },
   earlyHints: {
     enabled: true,
@@ -22,7 +22,7 @@ module.exports = {
     driver: 'memory',
     redis: 'default'
   },
-  debug: false,
+  debug: process.env.NODE_ENV !== 'production',
 
   init: function () {
     try {
@@ -31,17 +31,17 @@ module.exports = {
       this.system = {}
     }
 
-    if (fs.existsSync(__dir + '/config.json')) {
+    if (fs.existsSync(__dir + '/odac.json')) {
       let config = {}
       try {
-        config = JSON.parse(fs.readFileSync(__dir + '/config.json'))
+        config = JSON.parse(fs.readFileSync(__dir + '/odac.json'))
         config = this._interpolate(config)
       } catch (err) {
-        console.error('Error reading config file:', __dir + '/config.json', err.message)
+        console.error('Error reading config file:', __dir + '/odac.json', err.message)
       }
       this._deepMerge(this, config)
     }
-    this.encrypt.key = nodeCrypto.createHash('md5').update(this.encrypt.key).digest('hex')
+    this.encrypt.key = nodeCrypto.createHash('sha256').update(this.encrypt.key).digest()
   },
 
   _interpolate: function (obj) {

package/src/Env.js

@@ -20,7 +20,9 @@ module.exports = {
         // Parse quoted values
         value = this._parseValue(value)
 
-        process.env[key] = value
+        if (process.env[key] === undefined) {
+          process.env[key] = value
+        }
       })
     } catch (err) {
       console.error('Error reading .env file:', err.message)

package/src/Ipc.js

@@ -10,6 +10,13 @@ class Ipc extends EventEmitter {
     this._subs = new Map() // For memory driver subscriptions
   }
 
+  /**
+   * ARCHITECTURE NOTE:
+   * This module implements a "Primary-Replica" pattern for the 'memory' driver.
+   * - The Primary process holds the 'Source of Truth' in local Maps.
+   * - Workers communicate via IPC (process.send) to read/write to this central store.
+   * This ensures state consistency across the cluster without needing Redis.
+   */
   async init() {
     if (this.initialized) return
     this.initialized = true

package/src/Lang.js

@@ -43,9 +43,16 @@ class Lang {
 
   set(lang) {
     if (!lang || lang.length !== 2 || !this.#odac.Var(lang).is('alpha')) {
-      if (this.#odac.Request.header('ACCEPT-LANGUAGE') && this.#odac.Request.header('ACCEPT-LANGUAGE').length > 1)
+      if (
+        this.#odac.Request &&
+        this.#odac.Request.header &&
+        this.#odac.Request.header('ACCEPT-LANGUAGE') &&
+        this.#odac.Request.header('ACCEPT-LANGUAGE').length > 1
+      ) {
         lang = this.#odac.Request.header('ACCEPT-LANGUAGE').substr(0, 2)
-      else lang = this.#odac.Config.lang?.default || 'en'
+      } else {
+        lang = this.#odac.Config.lang?.default || 'en'
+      }
     }
     this.#lang = lang
     if (fs.existsSync(__dir + '/storage/language/' + lang + '.json'))

package/src/Odac.js

@@ -64,9 +64,11 @@ module.exports = {
     _odac.Var = (...args) => new (require('./Var.js'))(...args)
 
     if (req) {
-      _odac.Request = new (require('./Request.js'))(id, req, res, _odac)
-      _odac.Auth = new (require('./Auth.js'))(_odac.Request)
-      _odac.Token = new (require('./Token.js'))(_odac.Request)
+      if (typeof req === 'object') {
+        _odac.Request = new (require('./Request.js'))(id, req, res, _odac)
+        _odac.Auth = new (require('./Auth.js'))(_odac.Request)
+        _odac.Token = new (require('./Token.js'))(_odac.Request)
+      }
       _odac.Lang = new (require('./Lang.js'))(_odac)
       if (res) {
         _odac.View = new (require('./View.js'))(_odac)
@@ -110,42 +112,49 @@ module.exports = {
       _odac.__ = function (...args) {
         return _odac.Lang.get(...args)
       }
-      _odac.abort = function (code) {
-        return _odac.Request.abort(code)
-      }
-      _odac.cookie = function (key, value, options) {
-        return _odac.Request.cookie(key, value, options)
-      }
-      _odac.direct = function (url) {
-        return _odac.Request.redirect(url)
+      if (typeof req === 'object') {
+        _odac.abort = function (code) {
+          return _odac.Request.abort(code)
+        }
+        _odac.cookie = function (key, value, options) {
+          return _odac.Request.cookie(key, value, options)
+        }
+        _odac.direct = function (url) {
+          return _odac.Request.redirect(url)
+        }
       }
       _odac.env = function (key, defaultValue) {
         return _odac.Env.get(key, defaultValue)
       }
-      _odac.return = function (data) {
-        return _odac.Request.end(data)
-      }
-      _odac.request = function (key) {
-        return _odac.Request.request(key)
-      }
-      _odac.set = function (key, value) {
-        return _odac.Request.set(key, value)
-      }
-      _odac.share = function (key, value) {
-        return _odac.Request.share(key, value)
-      }
-      _odac.token = function (hash) {
-        return hash ? _odac.Token.check(hash) : _odac.Token.generate()
-      }
-      _odac.validator = function () {
-        return new (require('./Validator.js'))(_odac.Request)
-      }
-      _odac.write = function (value) {
-        return _odac.Request.write(value)
-      }
-      _odac.stream = function (input) {
-        _odac.Request.clearTimeout()
-        return new (require('./Stream'))(_odac.Request.req, _odac.Request.res, input, _odac)
+      if (typeof req === 'object') {
+        _odac.return = function (data) {
+          return _odac.Request.end(data)
+        }
+        _odac.request = function (key) {
+          return _odac.Request.request(key)
+        }
+        _odac.set = function (key, value) {
+          return _odac.Request.set(key, value)
+        }
+        _odac.session = function (key, value) {
+          return _odac.Request.session(key, value)
+        }
+        _odac.share = function (key, value) {
+          return _odac.Request.share(key, value)
+        }
+        _odac.token = function (hash) {
+          return hash ? _odac.Token.check(hash) : _odac.Token.generate()
+        }
+        _odac.validator = function () {
+          return new (require('./Validator.js'))(_odac.Request)
+        }
+        _odac.write = function (value) {
+          return _odac.Request.write(value)
+        }
+        _odac.stream = function (input) {
+          _odac.Request.clearTimeout()
+          return new (require('./Stream'))(_odac.Request.req, _odac.Request.res, input, _odac)
+        }
       }
 
       if (global.Odac?.Route?.class) {

package/src/Request.js

@@ -71,7 +71,7 @@ class OdacRequest {
     if (options.expires === undefined) options.expires = new Date(Date.now() + 1000 * 60 * 60 * 24 * 365).toUTCString()
     if (options.secure === undefined) options.secure = true
     if (options.httpOnly === undefined) options.httpOnly = true
-    if (options.sameSite === undefined) options.sameSite = 'Strict'
+    if (options.sameSite === undefined) options.sameSite = 'Lax'
     if (typeof value === 'object') value = JSON.stringify(value)
     let cookie = `${key}=${value}`
     for (const option of Object.keys(options)) if (options[option]) cookie += `; ${option}=${options[option]}`