odac 1.3.0 → 1.4.1

package/docs/backend/08-database/04-migrations.md

@@ -1,48 +1,269 @@
-# Code-First Migrations
+# Schema-First Migrations
 
-Migration files are great, but sometimes (especially in rapid development or zero-config apps) you want dependencies to define their own table structures automatically.
+ODAC uses a **declarative, schema-first** approach to database migrations. Instead of writing sequential migration files, you define the **desired final state** of each table in a schema file. The engine automatically diffs the schema against your database and applies the necessary changes.
 
-ODAC uses the `.schema()` helper for this logic.
+> **AI Agent Friendly:** A single schema file per table = instant understanding of the final database state. No need to scan hundreds of migration files.
 
-## Ensuring Tables Exist
+---
 
-The `.schema()` method checks if a table exists. If it **does not exist**, it runs the provided callback to create it. If it **already exists**, it does nothing.
+## Quick Start
+
+### 1. Define Your Schema
+
+Create a file in the `schema/` directory for each table:
+
+```javascript
+// schema/users.js
+'use strict'
+
+module.exports = {
+  columns: {
+    id:         {type: 'increments'},
+    name:       {type: 'string', length: 255, nullable: false},
+    email:      {type: 'string', length: 255, nullable: false},
+    role:       {type: 'enum', values: ['admin', 'user'], default: 'user'},
+    is_active:  {type: 'boolean', default: true},
+    timestamps: {type: 'timestamps'}
+  },
+
+  indexes: [
+    {columns: ['email'], unique: true},
+    {columns: ['role', 'is_active']}
+  ]
+}
+```
+
+### 2. Start Your App
+
+Migrations run **automatically** when the application starts. No manual commands needed:
+
+```bash
+npx odac dev    # Development
+npx odac start  # Production
+```
+
+On startup, the engine detects `schema/users.js`, creates the table, and applies indexes — all before the server accepts traffic.
+
+> **Zero-Config:** Just define the schema file and deploy. The framework handles the rest.
+
+You can also run migrations manually via CLI for inspection or rollback:
+
+### 3. Modify Your Schema
+
+Simply edit the schema file. Add a column, remove a column, add an index — the engine handles the rest:
+
+```javascript
+// schema/users.js — added 'bio' column, removed 'is_active'
+module.exports = {
+  columns: {
+    id:         {type: 'increments'},
+    name:       {type: 'string', length: 255, nullable: false},
+    email:      {type: 'string', length: 255, nullable: false},
+    role:       {type: 'enum', values: ['admin', 'user'], default: 'user'},
+    bio:        {type: 'text', nullable: true},
+    timestamps: {type: 'timestamps'}
+  },
+
+  indexes: [
+    {columns: ['email'], unique: true}
+  ]
+}
+```
+
+```bash
+npx odac migrate
+```
+
+```
+  [default]
+    + ADD COLUMN users.bio
+    - DROP COLUMN users.is_active
+    - DROP INDEX users (role, is_active)
+
+✅ 3 operation(s) completed.
+```
+
+---
+
+## Column Types
+
+| Type | Usage | Options |
+|------|-------|---------|
+| `increments` | Auto-increment primary key | — |
+| `bigIncrements` | Big auto-increment | — |
+| `integer` | Integer | `unsigned` |
+| `bigInteger` | Big integer | `unsigned` |
+| `float` | Floating point | `precision`, `scale` |
+| `decimal` | Exact decimal | `precision`, `scale` |
+| `string` | Varchar | `length` (default: 255) |
+| `text` | Text blob | `textType` ('text', 'mediumtext', 'longtext') |
+| `boolean` | Boolean | — |
+| `date` | Date only | — |
+| `datetime` | Date and time | — |
+| `timestamp` | Timestamp | — |
+| `timestamps` | Virtual: creates `created_at` + `updated_at` | — |
+| `time` | Time only | — |
+| `binary` | Binary data | `length` |
+| `json` | JSON | — |
+| `jsonb` | Binary JSON (PostgreSQL) | — |
+| `uuid` | UUID | — |
+| `enum` | Enumeration | `values` (array) |
+
+## Column Modifiers
+
+```javascript
+{
+  type: 'string',
+  length: 100,
+  nullable: false,        // NOT NULL constraint
+  default: 'untitled',    // Default value
+  unsigned: true,         // Unsigned integer
+  unique: true,           // Unique constraint (inline)
+  primary: true,          // Primary key
+  comment: 'The title',   // Column comment
+  references: {           // Foreign key
+    table: 'categories',
+    column: 'id'
+  },
+  onDelete: 'CASCADE',
+  onUpdate: 'CASCADE'
+}
+```
+
+---
+
+## Seed Data
+
+Schema files can include declarative seed data that is applied idempotently on every migration:
 
 ```javascript
-// Ensure 'products' table exists on the fly
-await Odac.DB.products.schema(t => {
-   t.increments('id');
-   t.string('name').notNullable();
-   t.decimal('price', 10, 2);
-   t.boolean('is_active').defaultTo(true);
-   
-   // Automatic timestamps (created_at, updated_at)
-   t.timestamps(true, true);
-});
-```
-
-The `t` argument is a Schema Builder. You can define columns using standard types like:
-- `t.string()`
-- `t.integer()`
-- `t.boolean()`
-- `t.text()`
-- `t.date()`
-- `t.json()`
-
-## Usage Example
-
-A typical pattern is to define schemas in your module's initialization or before the first insert.
+// schema/roles.js
+module.exports = {
+  columns: {
+    id:    {type: 'increments'},
+    name:  {type: 'string', length: 50},
+    level: {type: 'integer', default: 0}
+  },
+
+  indexes: [],
+
+  seed: [
+    {name: 'admin', level: 100},
+    {name: 'editor', level: 50},
+    {name: 'user', level: 1}
+  ],
+  seedKey: 'name'
+}
+```
+
+- **`seed`** — Array of rows to ensure exist
+- **`seedKey`** — Column used for uniqueness check (required when `seed` is present)
+
+**Behavior:** If the row exists (matched by `seedKey`), it updates if values differ. If not, it inserts. Safe to run repeatedly.
+
+---
+
+## Data Migrations
+
+For **one-time data transformations** (splitting columns, backfilling, etc.), use imperative migration files:
+
+```
+migration/
+  20260225_001_split_names.js
+```
 
 ```javascript
-// In your controller or module
-async function init() {
-    await Odac.DB.logs.schema(t => {
-        t.string('level');
-        t.text('message');
-        t.timestamps();
-    });
+// migration/20260225_001_split_names.js
+module.exports = {
+  async up(db) {
+    const users = await db('users').select('id', 'full_name')
+    for (const user of users) {
+      const [first, ...rest] = user.full_name.split(' ')
+      await db('users').where('id', user.id).update({
+        first_name: first,
+        last_name: rest.join(' ')
+      })
+    }
+  },
+
+  async down(db) {
+    const users = await db('users').select('id', 'first_name', 'last_name')
+    for (const user of users) {
+      await db('users').where('id', user.id).update({
+        full_name: `${user.first_name} ${user.last_name}`
+      })
+    }
+  }
+}
+```
+
+Migration files run **once** and are tracked in the `_odac_migrations` table.
+
+---
+
+## Multiple Databases
+
+If your project has multiple database connections, organize schemas by connection:
+
+```
+schema/
+  users.js              ← default connection
+  posts.js              ← default connection
+  analytics/            ← 'analytics' connection
+    events.js
+    pageviews.js
+```
+
+The folder name matches the connection key in your `odac.json`:
+
+```json
+{
+  "database": {
+    "default": {"type": "mysql", "database": "main_db"},
+    "analytics": {"type": "postgres", "database": "analytics_db"}
+  }
 }
+```
+
+Migration files follow the same convention:
+
+```
+migration/
+  20260225_001_auto.js          ← default connection
+  analytics/
+    20260225_001_backfill.js    ← analytics connection
+```
+
+---
+
+## CLI Commands
 
-// Later...
-await Odac.DB.logs.insert({ level: 'info', message: 'App started' });
+```bash
+# Run all pending migrations (schema diff + files + seeds)
+npx odac migrate
+
+# Target a specific database connection
+npx odac migrate --db=analytics
+
+# Show pending changes without applying (dry-run)
+npx odac migrate:status
+
+# Rollback the last batch of migration files
+npx odac migrate:rollback
+
+# Reverse-engineer current database into schema/ files
+npx odac migrate:snapshot
+npx odac migrate:snapshot --db=analytics
+```
+
+---
+
+## Snapshot — Importing Existing Databases
+
+For existing projects, use `migrate:snapshot` to generate schema files from your current database:
+
+```bash
+npx odac migrate:snapshot
 ```
+
+This creates a schema file for each table. Review and adjust the generated files, then use them as your source of truth going forward.

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.1",
   "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,89 @@ 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(() => {})
+      let triggerRotation = false
+      let isRecoveryRotation = false
+
+      if (!isRotated) {
+        if (shouldRotate && tokenAge > rotationAge) {
+          triggerRotation = true
+        } 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(() => {})
+        }
+      } else {
+        // Client still presenting a rotated (grace period) token.
+        // This means the previous rotation response was lost (network hiccup, page navigation, etc.)
+        // Give the client one more chance by re-issuing new credentials.
+        const timeSinceRotation = inactiveAge - maxAge + TOKEN_ROTATION_GRACE_PERIOD_MS
+        if (timeSinceRotation > 5000) {
+          triggerRotation = true
+          isRecoveryRotation = true
+        }
+      }
+
+      if (triggerRotation) {
+        // --- 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) {
+          if (!isRecoveryRotation) {
+            // 2a. Normal rotation: Mark old token as rotated with 60s 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(() => {})
+          } else {
+            // 2b. Recovery rotation: Delete old rotated token immediately.
+            // Why: Prevents unbounded token multiplication. The old token already
+            // had its grace period; one recovery attempt is the maximum.
+            Odac.DB[tokenTable]
+              .where('id', sql_token[0].id)
+              .delete()
+              .catch(() => {})
+          }
+
+          // 3. Issue new cookies immediately
+          this.#request.cookie('odac_x', newTokenX, {
+            httpOnly: true,
+            secure: true,
+            sameSite: 'Lax',
+            'max-age': Math.floor(maxAge / 1000)
+          })
+          this.#request.cookie('odac_y', newTokenY, {
+            httpOnly: true,
+            secure: true,
+            sameSite: 'Lax',
+            'max-age': Math.floor(maxAge / 1000)
+          })
+        }
       }
 
       return true
@@ -143,11 +234,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 +258,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',
+      'max-age': Math.floor(maxAge / 1000)
+    })
+    this.#request.cookie('odac_y', token_y, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'Lax',
+      'max-age': Math.floor(maxAge / 1000)
     })
-    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 +300,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,16 +406,20 @@ 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})
-    this.#request.cookie('odac_y', '', {maxAge: -1})
+    this.#request.cookie('odac_x', '', {'max-age': -1})
+    this.#request.cookie('odac_y', '', {'max-age': -1})
 
     this.#user = null
     return true
@@ -326,7 +434,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/Config.js

@@ -46,7 +46,7 @@ module.exports = {
 
   _interpolate: function (obj) {
     if (typeof obj === 'string') {
-      return obj.replace(/\$\{(\w+)\}/g, (_, key) => {
+      return obj.replace(/\$\{([^{}]+)\}/g, (_, key) => {
         // Special variables
         if (key === 'odac') {
           return __dirname.replace(/\/src$/, '/client')

package/src/Database/ConnectionFactory.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const knex = require('knex')
+
+/**
+ * Resolves knex client driver from ODAC database type.
+ * Why: Keeps connection driver mapping consistent across runtime and CLI migration paths.
+ * @param {string} type Database type from config.
+ * @returns {string} Knex client name.
+ */
+function resolveClient(type) {
+  if (type === 'postgres' || type === 'pg' || type === 'postgresql') return 'pg'
+  if (type === 'sqlite' || type === 'sqlite3') return 'sqlite3'
+  return 'mysql2'
+}
+
+/**
+ * Builds knex connection config from ODAC database node.
+ * Why: Normalizes connection options for all call sites and avoids drift.
+ * @param {object} db Single database config node.
+ * @param {string} client Knex client name.
+ * @returns {object} Knex connection object.
+ */
+function buildConnectionConfig(db, client) {
+  if (client === 'sqlite3') {
+    return {filename: db.filename || db.database || './dev.sqlite3'}
+  }
+
+  return {
+    host: db.host || '127.0.0.1',
+    user: db.user,
+    password: db.password,
+    database: db.database,
+    port: db.port
+  }
+}
+
+/**
+ * Creates knex connections map from ODAC database config.
+ * Why: Centralizes zero-config connection bootstrap used by runtime and migration CLI.
+ * @param {object} databaseConfig ODAC database config (single or multiple).
+ * @returns {Record<string, any>} Knex connections by key.
+ */
+function buildConnections(databaseConfig) {
+  const isMultiple = typeof databaseConfig[Object.keys(databaseConfig)[0]] === 'object'
+  const dbs = isMultiple ? databaseConfig : {default: databaseConfig}
+  const connections = {}
+
+  for (const key of Object.keys(dbs)) {
+    const db = dbs[key]
+    const client = resolveClient(db.type)
+    const connection = buildConnectionConfig(db, client)
+
+    connections[key] = knex({
+      client,
+      connection,
+      pool: {min: 0, max: db.connectionLimit || 10},
+      useNullAsDefault: true
+    })
+  }
+
+  return connections
+}
+
+module.exports = {
+  buildConnections,
+  buildConnectionConfig,
+  resolveClient
+}