odac 1.1.0 → 1.3.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.3.0",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -21,32 +21,36 @@
     "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.9",
+    "cross-spawn": "7.0.6"
   },
   "devDependencies": {
-    "@eslint/js": "^9.33.0",
+    "@eslint/js": "^9.39.2",
     "@semantic-release/changelog": "^6.0.3",
     "@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/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "conventional-changelog-conventionalcommits": "^9.1.0",
-    "eslint": "^9.33.0",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
-    "globals": "^16.3.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.3.0",
     "husky": "^9.1.7",
-    "jest": "^30.0.5",
-    "lint-staged": "^16.1.5",
-    "prettier": "3.6.2",
-    "semantic-release": "^25.0.2",
+    "jest": "^30.2.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "semantic-release": "^25.0.3",
     "sqlite3": "^5.1.7"
   },
   "scripts": {

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/Database.js

@@ -18,7 +18,7 @@ class DatabaseManager {
       if (db.type === 'postgres' || db.type === 'pg' || db.type === 'postgresql') client = 'pg'
       if (db.type === 'sqlite' || db.type === 'sqlite3') client = 'sqlite3'
 
-      let connectionConfig = {}
+      let connectionConfig
 
       if (client === 'sqlite3') {
         connectionConfig = {

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/Mail.js

@@ -1,6 +1,7 @@
 const net = require('net')
 const nodeCrypto = require('crypto')
 const fs = require('fs')
+const fsPromises = fs.promises
 // const Form = require('./View/Form')
 
 const CACHE_DIR = './storage/.cache'
@@ -155,13 +156,14 @@ class Mail {
   }
 
   async #render(file, data) {
-    const fd = fs.openSync(file, 'r')
     let mtime, content
+    const handle = await fsPromises.open(file, 'r')
     try {
-      mtime = fs.fstatSync(fd).mtimeMs
-      content = fs.readFileSync(fd, 'utf8')
+      const stats = await handle.stat()
+      mtime = stats.mtimeMs
+      content = await handle.readFile('utf8')
     } finally {
-      fs.closeSync(fd)
+      await handle.close()
     }
 
     // Since mail doesn't have a persistent Odac instance access like View cache, we manage a simple cache or just re-compile.
@@ -251,8 +253,8 @@ class Mail {
       }
 
       let cache = `${nodeCrypto.createHash('md5').update(file).digest('hex')}`
-      if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, {recursive: true})
-      fs.writeFileSync(
+      await fsPromises.mkdir(CACHE_DIR, {recursive: true})
+      await fsPromises.writeFile(
         `${CACHE_DIR}/${cache}`,
         `module.exports = async (Odac, data, get, __) => {\n
            // Destructure data keys into local scope variables
@@ -351,7 +353,9 @@ class Mail {
           let textContent = ''
 
           if (this.#template) {
-            if (!fs.existsSync(__dir + '/view/mail/' + this.#template + '.html')) {
+            try {
+              await fsPromises.access(__dir + '/view/mail/' + this.#template + '.html')
+            } catch {
               console.error(`[Mail] Template not found: ${__dir}/view/mail/${this.#template}.html`)
               return resolve(false)
             }
@@ -409,7 +413,7 @@ class Mail {
             ]
           }
 
-          const socketPath = process.env.ODAC_API_SOCKET || '/var/run/odac.sock'
+          const socketPath = process.env.ODAC_API_SOCKET || '/odac/api.sock'
 
           if (Odac.Config.debug) console.log(`[Mail] Connecting to Odac Core via Unix Socket: ${socketPath}...`)
 
@@ -431,7 +435,13 @@ class Mail {
           })
 
           client.on('error', error => {
-            console.error('[Mail] Socket Error:', error)
+            if (error.code === 'ENOENT' && error.address === socketPath) {
+              console.error(
+                '[Mail] Socket Error: If you are using ODAC, you must grant permissions or enter SMTP information in the config.'
+              )
+            } else {
+              console.error('[Mail] Socket Error:', error)
+            }
             resolve(false)
           })