rotifex 0.1.6 → 0.1.7

package/README.md

@@ -30,6 +30,16 @@ npx rotifex start
 | ------- | ------------------------------------ |
 | `start` | Start the Rotifex development server |
 
+### `start` flags
+
+| Flag              | Description                                                          |
+| ----------------- | -------------------------------------------------------------------- |
+| `-p, --port <n>`  | TCP port to listen on (overrides `ROTIFEX_PORT` and auto-fallback)  |
+| `--host <host>`   | Bind address (overrides `ROTIFEX_HOST`)                             |
+| `--verbose`       | Enable debug-level logging                                          |
+
+**Port auto-fallback:** If no port is explicitly set, Rotifex tries port `4994`, then `4995`, then `4996`. If all three are occupied it exits with a clear error. Pass `--port` or set `ROTIFEX_PORT` to pin a specific port and skip the fallback.
+
 ## Table of Contents
 
 1. [Application Overview](#1-application-overview)
@@ -116,7 +126,7 @@ Rotifex eliminates boilerplate for backend development. Instead of writing CRUD
 **How it works:**
 
 1. `schema.json` is parsed by `schemaLoader.js` into normalized model definitions.
-2. `tableSync.js` runs `CREATE TABLE IF NOT EXISTS` for each model.
+2. `tableSync.js` runs `CREATE TABLE IF NOT EXISTS` for each model. On subsequent startups it **automatically adds missing columns** via `ALTER TABLE ADD COLUMN` — no manual migrations needed when fields are added to an existing model.
 3. `routeFactory.js` registers generic parametric routes (`/api/:table`) that resolve the model from an in-memory store at request time.
 4. When a model is added/removed via the admin API, the in-memory store is updated and routes resolve immediately.
 
@@ -154,16 +164,20 @@ Rotifex eliminates boilerplate for backend development. Instead of writing CRUD
 
 ### 2.2 JWT Authentication
 
-**Description:** Full authentication system with access tokens, refresh tokens, password hashing, and role-based access control.
+**Description:** Full authentication system with access tokens, refresh tokens, token rotation, logout/revocation, password hashing, and role-based access control.
 
 **Use case:** Secure user registration and login for a Rotifex-backed application. Protect admin routes from regular users.
 
 **How it works:**
 
-1. `POST /auth/register` hashes the password with bcrypt and inserts a user row.
-2. `POST /auth/login` verifies credentials and issues a short-lived access token (1 hour) and long-lived refresh token (30 days).
+1. `POST /auth/register` hashes the password with bcrypt (12 rounds) and inserts a user row.
+2. `POST /auth/login` verifies credentials and issues a short-lived access token and long-lived refresh token.
 3. The JWT middleware runs on every request, verifies the `Authorization: Bearer` header, and injects `x-user-id` / `x-user-role` headers that downstream routes use for authorization.
-4. `POST /auth/refresh` issues a new token pair without requiring the password.
+4. `POST /auth/refresh` issues a new token pair and **revokes the consumed refresh token** (single-use rotation). Each refresh token embeds a unique `jti` (JWT ID) used for targeted revocation.
+5. `POST /auth/logout` invalidates the provided refresh token immediately.
+6. `POST /auth/change-password` lets an authenticated user change their own password.
+
+**Token TTLs are configurable** via env vars (see Section 10). Defaults: access token 60 minutes, refresh token 30 days. The refresh TTL must be at least 2× the access TTL and no shorter than 2 hours.
 
 **Roles:** `user` (default) and `admin`. Admin access is required for all `/admin/api/*` endpoints.
 
@@ -252,7 +266,7 @@ Rotifex eliminates boilerplate for backend development. Instead of writing CRUD
 ### Base URL
 
 ```
-http://localhost:3000
+http://localhost:4994
 ```
 
 All API responses follow the envelope format:
@@ -375,7 +389,7 @@ Authenticate and receive tokens.
 
 #### `POST /auth/refresh`
 
-Exchange a refresh token for a new token pair.
+Exchange a refresh token for a new token pair. The consumed refresh token is immediately revoked (single-use rotation).
 
 **Auth:** None
 
@@ -400,10 +414,61 @@ Exchange a refresh token for a new token pair.
 
 **Errors:**
 
+| Code  | Reason                                       |
+| ----- | -------------------------------------------- |
+| `400` | Missing refreshToken                         |
+| `401` | Invalid, expired, or already-revoked token   |
+
+---
+
+#### `POST /auth/logout`
+
+Revoke a refresh token. After this call the token cannot be used to issue new pairs.
+
+**Auth:** None
+
+**Request Body:**
+
+```json
+{
+  "refreshToken": "<jwt>"
+}
+```
+
+**Response `204`:** No content.
+
+**Errors:**
+
 | Code  | Reason                           |
 | ----- | -------------------------------- |
-| `400` | Missing refreshToken             |
-| `401` | Invalid or expired refresh token |
+| `400` | Missing or invalid refreshToken  |
+
+---
+
+#### `POST /auth/change-password`
+
+Change the authenticated user's own password.
+
+**Auth:** `Authorization: Bearer <accessToken>`
+
+**Request Body:**
+
+```json
+{
+  "currentPassword": "old-password",
+  "newPassword": "new-password123"
+}
+```
+
+**Response `204`:** No content.
+
+**Errors:**
+
+| Code  | Reason                              |
+| ----- | ----------------------------------- |
+| `400` | Missing fields or weak new password |
+| `401` | Wrong current password / bad token  |
+| `404` | User not found                      |
 
 ---
 
@@ -698,7 +763,7 @@ Generate a time-limited signed URL for a private file.
 ```json
 {
   "data": {
-    "url": "http://localhost:3000/files/uuid/download?token=abc123&expires=1741300000",
+    "url": "http://localhost:4994/files/uuid/download?token=abc123&expires=1741300000",
     "expires": 1741300000
   }
 }
@@ -1122,7 +1187,7 @@ Read current environment/config values.
 {
   "data": {
     "JWT_SECRET": "***",
-    "ROTIFEX_PORT": "3000",
+    "ROTIFEX_PORT": "4994",
     "ROTIFEX_CORS_ORIGIN": "*"
   }
 }
@@ -1290,10 +1355,14 @@ Client                          Rotifex Server
 
 ### Token Details
 
-| Token         | Algorithm | TTL     | Secret Env Var       |
-| ------------- | --------- | ------- | -------------------- |
-| Access Token  | HS256     | 1 hour  | `JWT_SECRET`         |
-| Refresh Token | HS256     | 30 days | `JWT_REFRESH_SECRET` |
+| Token         | Algorithm | Default TTL | TTL Env Var                   | Secret Env Var       |
+| ------------- | --------- | ----------- | ----------------------------- | -------------------- |
+| Access Token  | HS256     | 60 min      | `ROTIFEX_ACCESS_TOKEN_TTL`    | `JWT_SECRET`         |
+| Refresh Token | HS256     | 30 days     | `ROTIFEX_REFRESH_TOKEN_TTL`   | `JWT_REFRESH_SECRET` |
+
+TTLs are in **minutes**. The refresh TTL must be ≥ 2× the access TTL and ≥ 120 minutes. Both can be tuned in the admin **Settings** page or via `.env`.
+
+Refresh tokens embed a unique `jti` (JWT ID) enabling individual revocation. Token rotation is enforced — each refresh token is single-use.
 
 Secrets are auto-generated and saved to `.env` on first startup if not explicitly set.
 
@@ -1569,7 +1638,9 @@ Signed URLs are generated via `GET /files/:id/signed-url`. The default TTL is 1
 ### User Management
 
 - List all registered users: email, display name, role, creation date
-- Admin actions on user accounts
+- **Create user** — "New User" modal with email, password, display name, and role
+- **Reset password** — inline "Reset Password" section inside the edit modal (admin force-sets any user's password)
+- Password validation enforced: minimum 8 characters, at least one letter and one number
 
 ### File Browser
 
@@ -1607,17 +1678,21 @@ Signed URLs are generated via `GET /files/:id/signed-url`. The default TTL is 1
 
 Editable via admin panel — writes to `.env`:
 
-| Variable                            | Description                  |
-| ----------------------------------- | ---------------------------- |
-| `JWT_SECRET`                        | Access token signing secret  |
-| `JWT_REFRESH_SECRET`                | Refresh token signing secret |
-| `ROTIFEX_PORT`                      | Server port                  |
-| `ROTIFEX_HOST`                      | Server bind host             |
-| `ROTIFEX_CORS_ORIGIN`               | Allowed CORS origin(s)       |
-| `ROTIFEX_RATE_LIMIT_MAX`            | Max requests per time window |
-| `ROTIFEX_LOG_LEVEL`                 | Log verbosity                |
-| `ROTIFEX_STORAGE_MAX_FILE_SIZE_MB`  | Max upload size in MB        |
-| `ROTIFEX_STORAGE_SIGNED_URL_SECRET` | HMAC secret for signed URLs  |
+| Variable                            | Description                                                     |
+| ----------------------------------- | --------------------------------------------------------------- |
+| `ROTIFEX_ACCESS_TOKEN_TTL`          | Access token lifetime in minutes (min 5, default 60)           |
+| `ROTIFEX_REFRESH_TOKEN_TTL`         | Refresh token lifetime in minutes (min 120 and ≥ 2×access, default 43200) |
+| `JWT_SECRET`                        | Access token signing secret                                     |
+| `JWT_REFRESH_SECRET`                | Refresh token signing secret                                    |
+| `ROTIFEX_PORT`                      | Server port                                                     |
+| `ROTIFEX_HOST`                      | Server bind host                                                |
+| `ROTIFEX_CORS_ORIGIN`               | Allowed CORS origin(s)                                          |
+| `ROTIFEX_RATE_LIMIT_MAX`            | Max requests per time window                                    |
+| `ROTIFEX_LOG_LEVEL`                 | Log verbosity                                                   |
+| `ROTIFEX_STORAGE_MAX_FILE_SIZE_MB`  | Max upload size in MB                                           |
+| `ROTIFEX_STORAGE_SIGNED_URL_SECRET` | HMAC secret for signed URLs                                     |
+
+The **Token Timing** card validates constraints live: refresh TTL must be ≥ 2× access TTL and ≥ 120 minutes. The Save button is disabled until all errors are resolved.
 
 ---
 
@@ -1669,29 +1744,33 @@ Validation errors may return an array for `message`:
 
 ### Environment Variables Reference
 
-| Variable                            | Default   | Description                                  |
-| ----------------------------------- | --------- | -------------------------------------------- |
-| `ROTIFEX_PORT`                      | `3000`    | TCP port                                     |
-| `ROTIFEX_HOST`                      | `0.0.0.0` | Bind address                                 |
-| `ROTIFEX_CORS_ORIGIN`               | `*`       | Allowed CORS origin                          |
-| `ROTIFEX_RATE_LIMIT_MAX`            | `100`     | Max requests per rate-limit window           |
-| `ROTIFEX_LOG_LEVEL`                 | `info`    | Log level (`info`, `debug`, `warn`, `error`) |
-| `ROTIFEX_STORAGE_MAX_FILE_SIZE_MB`  | `10`      | Max upload size in MB                        |
-| `ROTIFEX_STORAGE_SIGNED_URL_SECRET` | auto      | HMAC secret for signed file URLs             |
-| `JWT_SECRET`                        | auto      | Access token signing secret                  |
-| `JWT_REFRESH_SECRET`                | auto      | Refresh token signing secret                 |
+| Variable                            | Default   | Description                                                        |
+| ----------------------------------- | --------- | ------------------------------------------------------------------ |
+| `ROTIFEX_PORT`                      | `4994`    | TCP port (auto-tries 4994 → 4995 → 4996 if unset)                |
+| `ROTIFEX_HOST`                      | `0.0.0.0` | Bind address                                                       |
+| `ROTIFEX_CORS_ORIGIN`               | `*`       | Allowed CORS origin                                                |
+| `ROTIFEX_RATE_LIMIT_MAX`            | `100`     | Max requests per rate-limit window                                 |
+| `ROTIFEX_LOG_LEVEL`                 | `info`    | Log level (`info`, `debug`, `warn`, `error`)                      |
+| `ROTIFEX_STORAGE_MAX_FILE_SIZE_MB`  | `10`      | Max upload size in MB                                              |
+| `ROTIFEX_STORAGE_SIGNED_URL_SECRET` | auto      | HMAC secret for signed file URLs                                   |
+| `ROTIFEX_ACCESS_TOKEN_TTL`          | `60`      | Access token TTL in minutes (min 5)                               |
+| `ROTIFEX_REFRESH_TOKEN_TTL`         | `43200`   | Refresh token TTL in minutes (min 120, must be ≥ 2× access TTL)  |
+| `JWT_SECRET`                        | auto      | Access token signing secret                                        |
+| `JWT_REFRESH_SECRET`                | auto      | Refresh token signing secret                                       |
 
 > `JWT_SECRET`, `JWT_REFRESH_SECRET`, and `ROTIFEX_STORAGE_SIGNED_URL_SECRET` are auto-generated on first startup if absent and saved to `.env`.
 
 ### Example `.env`
 
 ```env
-ROTIFEX_PORT=3000
+ROTIFEX_PORT=4994
 ROTIFEX_HOST=0.0.0.0
 ROTIFEX_CORS_ORIGIN=https://myapp.com
 ROTIFEX_RATE_LIMIT_MAX=200
 ROTIFEX_LOG_LEVEL=info
 ROTIFEX_STORAGE_MAX_FILE_SIZE_MB=25
+ROTIFEX_ACCESS_TOKEN_TTL=60
+ROTIFEX_REFRESH_TOKEN_TTL=43200
 JWT_SECRET=replace-with-a-long-random-string
 JWT_REFRESH_SECRET=replace-with-another-long-random-string
 ROTIFEX_STORAGE_SIGNED_URL_SECRET=replace-with-yet-another-secret
@@ -1717,10 +1796,10 @@ npm install
 ### Running in Development
 
 ```bash
-# Default port 3000
+# Default port 4994 (falls back to 4995, 4996 if in use)
 npx rotifex start
 
-# Custom port
+# Pin a specific port (skips auto-fallback)
 npx rotifex start --port 4000
 
 # Custom host
@@ -1772,7 +1851,7 @@ server {
   server_name api.yourapp.com;
 
   location / {
-    proxy_pass http://127.0.0.1:3000;
+    proxy_pass http://127.0.0.1:4994;
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-Proto $scheme;
@@ -1795,12 +1874,12 @@ cp rotifex.db rotifex.db.backup
 
 ```bash
 # Register
-curl -X POST http://localhost:3000/auth/register \
+curl -X POST http://localhost:4994/auth/register \
   -H "Content-Type: application/json" \
   -d '{"email":"jane@example.com","password":"secure123","display_name":"Jane"}'
 
 # Login — save the returned accessToken
-curl -X POST http://localhost:3000/auth/login \
+curl -X POST http://localhost:4994/auth/login \
   -H "Content-Type: application/json" \
   -d '{"email":"jane@example.com","password":"secure123"}'
 
@@ -1814,7 +1893,7 @@ export TOKEN="<accessToken from response>"
 
 ```bash
 # 1. Create model (admin role required)
-curl -X POST http://localhost:3000/admin/api/schema \
+curl -X POST http://localhost:4994/admin/api/schema \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{
@@ -1827,23 +1906,23 @@ curl -X POST http://localhost:3000/admin/api/schema \
   }'
 
 # 2. Create a record
-curl -X POST http://localhost:3000/api/products \
+curl -X POST http://localhost:4994/api/products \
   -H "Content-Type: application/json" \
   -d '{"name":"Widget","price":9.99,"in_stock":true}'
 
 # 3. List with sort and filter
-curl "http://localhost:3000/api/products?sort=price&order=ASC&in_stock=1"
+curl "http://localhost:4994/api/products?sort=price&order=ASC&in_stock=1"
 
 # 4. Get one
-curl http://localhost:3000/api/products/<id>
+curl http://localhost:4994/api/products/<id>
 
 # 5. Update
-curl -X PUT http://localhost:3000/api/products/<id> \
+curl -X PUT http://localhost:4994/api/products/<id> \
   -H "Content-Type: application/json" \
   -d '{"price":14.99}'
 
 # 6. Delete
-curl -X DELETE http://localhost:3000/api/products/<id>
+curl -X DELETE http://localhost:4994/api/products/<id>
 ```
 
 ---
@@ -1852,22 +1931,22 @@ curl -X DELETE http://localhost:3000/api/products/<id>
 
 ```bash
 # Upload a public file
-curl -X POST http://localhost:3000/files/upload \
+curl -X POST http://localhost:4994/files/upload \
   -H "Authorization: Bearer $TOKEN" \
   -F "file=@/path/to/photo.jpg" \
   -F "visibility=public"
 
 # Download public file (no auth needed)
-curl http://localhost:3000/files/<id>/download -o photo.jpg
+curl http://localhost:4994/files/<id>/download -o photo.jpg
 
 # Upload a private file
-curl -X POST http://localhost:3000/files/upload \
+curl -X POST http://localhost:4994/files/upload \
   -H "Authorization: Bearer $TOKEN" \
   -F "file=@/path/to/document.pdf" \
   -F "visibility=private"
 
 # Get a signed URL for the private file
-curl http://localhost:3000/files/<id>/signed-url \
+curl http://localhost:4994/files/<id>/signed-url \
   -H "Authorization: Bearer $TOKEN"
 
 # Download using the signed URL
@@ -1880,7 +1959,7 @@ curl "<signed-url>" -o document.pdf
 
 ```bash
 # Generate a completion
-curl -X POST http://localhost:3000/api/ai/generate \
+curl -X POST http://localhost:4994/api/ai/generate \
   -H "Content-Type: application/json" \
   -d '{
     "provider": "openai",
@@ -1890,7 +1969,7 @@ curl -X POST http://localhost:3000/api/ai/generate \
   }'
 
 # Multi-turn chat
-curl -X POST http://localhost:3000/api/ai/chat \
+curl -X POST http://localhost:4994/api/ai/chat \
   -H "Content-Type: application/json" \
   -d '{
     "provider": "anthropic",
@@ -1907,7 +1986,7 @@ curl -X POST http://localhost:3000/api/ai/chat \
 
 ```bash
 # 1. Create an agent (admin required)
-curl -X POST http://localhost:3000/admin/api/agents \
+curl -X POST http://localhost:4994/admin/api/agents \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{
@@ -1921,7 +2000,7 @@ curl -X POST http://localhost:3000/admin/api/agents \
   }'
 
 # 2. Run the agent
-curl -X POST http://localhost:3000/api/agents/<id>/run \
+curl -X POST http://localhost:4994/api/agents/<id>/run \
   -H "Content-Type: application/json" \
   -d '{"input": "What is (144 / 12) * 7.5 plus 33?"}'
 ```
@@ -1931,7 +2010,7 @@ curl -X POST http://localhost:3000/api/agents/<id>/run \
 ### Refreshing an Expired Token
 
 ```bash
-curl -X POST http://localhost:3000/auth/refresh \
+curl -X POST http://localhost:4994/auth/refresh \
   -H "Content-Type: application/json" \
   -d '{"refreshToken":"<your-refresh-token>"}'
 ```

package/config.default.json

@@ -1,7 +1,7 @@
 {
   "server": {
     "host": "0.0.0.0",
-    "port": 3000
+    "port": 4994
   },
   "cors": {
     "origin": "*"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rotifex",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Rotifex — a modern CLI toolkit for project scaffolding, development, and migrations.",
   "type": "module",
   "bin": {
@@ -21,10 +21,29 @@
     "postinstall": "npm rebuild better-sqlite3"
   },
   "keywords": [
-    "cli",
     "rotifex",
-    "scaffold",
-    "migrate"
+    "backend-as-a-service",
+    "baas",
+    "self-hosted-backend",
+    "api-generator",
+    "rest-api-generator",
+    "dynamic-api",
+    "schema-driven-api",
+    "fastify",
+    "nodejs-backend",
+    "low-code-backend",
+    "no-code-backend",
+    "sqlite-backend",
+    "admin-dashboard",
+    "jwt-authentication",
+    "file-storage",
+    "ai-platform",
+    "llm-platform",
+    "ai-agents",
+    "developer-tools",
+    "supabase-alternative",
+    "firebase-alternative",
+    "backend-framework"
   ],
   "author": "",
   "license": "MIT",

package/src/auth/auth.controller.js

@@ -1,4 +1,4 @@
-import { registerUser, loginUser, refreshTokens, getCurrentUser, validateRegistrationInput, verifyAccessToken } from './auth.service.js';
+import { registerUser, loginUser, refreshTokens, logout, changePassword, getCurrentUser, validateRegistrationInput, verifyAccessToken } from './auth.service.js';
 
 /**
  * Returns request handlers bound to the given `db` instance.
@@ -79,6 +79,55 @@ export function makeAuthController(db) {
       }
     },
 
+    async logout(request, reply) {
+      const { refreshToken } = request.body ?? {};
+      await logout(db, refreshToken);
+      return reply.status(204).send();
+    },
+
+    async changePassword(request, reply) {
+      // /auth/* is skipped by the JWT middleware — verify the token manually.
+      const header = request.headers['authorization'] ?? '';
+      if (!header.startsWith('Bearer ')) {
+        return reply.status(401).send({
+          error: 'Unauthorized',
+          message: 'Authorization: Bearer <token> header is required',
+          statusCode: 401,
+        });
+      }
+
+      let payload;
+      try {
+        payload = verifyAccessToken(header.slice(7));
+      } catch {
+        return reply.status(401).send({
+          error: 'Unauthorized',
+          message: 'Invalid or expired token',
+          statusCode: 401,
+        });
+      }
+
+      const { currentPassword, newPassword } = request.body ?? {};
+      if (!currentPassword || !newPassword) {
+        return reply.status(400).send({
+          error: 'Bad Request',
+          message: 'currentPassword and newPassword are required',
+          statusCode: 400,
+        });
+      }
+
+      try {
+        await changePassword(db, payload.userId, { currentPassword, newPassword });
+        return reply.status(204).send();
+      } catch (e) {
+        return reply.status(e.statusCode ?? 500).send({
+          error: 'Password change failed',
+          message: e.message,
+          statusCode: e.statusCode ?? 500,
+        });
+      }
+    },
+
     async me(request, reply) {
       // /auth/me is inside the /auth/* skip zone of the JWT middleware,
       // so we verify the token manually here.

package/src/auth/auth.routes.js

@@ -16,8 +16,10 @@ import { makeAuthController } from './auth.controller.js';
 export async function authRoutes(app, { db }) {
   const ctrl = makeAuthController(db);
 
-  app.post('/auth/register', (req, reply) => ctrl.register(req, reply));
-  app.post('/auth/login',    (req, reply) => ctrl.login(req, reply));
-  app.post('/auth/refresh',  (req, reply) => ctrl.refresh(req, reply));
-  app.get('/auth/me',        (req, reply) => ctrl.me(req, reply));
+  app.post('/auth/register',         (req, reply) => ctrl.register(req, reply));
+  app.post('/auth/login',            (req, reply) => ctrl.login(req, reply));
+  app.post('/auth/refresh',          (req, reply) => ctrl.refresh(req, reply));
+  app.post('/auth/logout',           (req, reply) => ctrl.logout(req, reply));
+  app.post('/auth/change-password',  (req, reply) => ctrl.changePassword(req, reply));
+  app.get('/auth/me',                (req, reply) => ctrl.me(req, reply));
 }

package/src/auth/auth.service.js

@@ -41,15 +41,31 @@ const jwtRefreshSecret = () => (_jwtRefreshSecret ??= resolveSecret('JWT_REFRESH
 
 // ── Token helpers ─────────────────────────────────────────────────────────────
 
-const ACCESS_TTL  = '1h';
-const REFRESH_TTL = '30d';
+// Thresholds enforced by both the server and the settings UI.
+export const ACCESS_TTL_MIN_MINUTES  = 5;
+export const REFRESH_TTL_MIN_MINUTES = 120; // 2 h
+export const REFRESH_TTL_MULTIPLIER  = 2;   // refresh must be >= 2× access
+
+function getAccessTTL() {
+  const minutes = Number(process.env.ROTIFEX_ACCESS_TOKEN_TTL) || 60;
+  return `${Math.max(minutes, ACCESS_TTL_MIN_MINUTES)}m`;
+}
+
+function getRefreshTTL() {
+  const accessMinutes  = Number(process.env.ROTIFEX_ACCESS_TOKEN_TTL)  || 60;
+  const refreshMinutes = Number(process.env.ROTIFEX_REFRESH_TOKEN_TTL) || 43200;
+  const minRefresh = Math.max(REFRESH_TTL_MIN_MINUTES, accessMinutes * REFRESH_TTL_MULTIPLIER);
+  return `${Math.max(refreshMinutes, minRefresh)}m`;
+}
 
 export function signAccessToken(payload) {
-  return jwt.sign(payload, jwtSecret(), { expiresIn: ACCESS_TTL });
+  return jwt.sign(payload, jwtSecret(), { expiresIn: getAccessTTL() });
 }
 
 export function signRefreshToken(payload) {
-  return jwt.sign(payload, jwtRefreshSecret(), { expiresIn: REFRESH_TTL });
+  // jti (JWT ID) uniquely identifies this token so it can be individually revoked.
+  const jti = crypto.randomUUID();
+  return jwt.sign({ ...payload, jti }, jwtRefreshSecret(), { expiresIn: getRefreshTTL() });
 }
 
 export function verifyAccessToken(token) {
@@ -74,6 +90,32 @@ export function ensureAuthSchema(db) {
   }
 }
 
+/**
+ * Ensure the `_revoked_tokens` table exists for refresh token revocation.
+ */
+export function ensureTokenBlacklist(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _revoked_tokens (
+      jti        TEXT PRIMARY KEY,
+      expires_at TEXT NOT NULL
+    );
+  `);
+}
+
+function revokeToken(db, jti, expiresAt) {
+  try {
+    db.run('INSERT OR IGNORE INTO _revoked_tokens (jti, expires_at) VALUES (?, ?)', [jti, expiresAt]);
+  } catch {
+    // ignore
+  }
+}
+
+function isTokenRevoked(db, jti) {
+  if (!jti) return false;
+  const row = db.get('SELECT jti FROM _revoked_tokens WHERE jti = ?', [jti]);
+  return !!row;
+}
+
 // ── Input validation ──────────────────────────────────────────────────────────
 
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -167,6 +209,13 @@ export async function refreshTokens(db, refreshToken) {
     throw err;
   }
 
+  // Reject if this specific token has been revoked (logout / rotation).
+  if (payload.jti && isTokenRevoked(db, payload.jti)) {
+    const err = new Error('Refresh token has been revoked');
+    err.statusCode = 401;
+    throw err;
+  }
+
   // Re-fetch user so role changes are reflected in the new access token.
   const user = db.get('SELECT id, role FROM users WHERE id = ?', [payload.userId]);
   if (!user) {
@@ -175,8 +224,67 @@ export async function refreshTokens(db, refreshToken) {
     throw err;
   }
 
+  // Revoke the consumed refresh token (token rotation — each token is one-use).
+  if (payload.jti) {
+    revokeToken(db, payload.jti, new Date(payload.exp * 1000).toISOString());
+  }
+
   const newAccessToken  = signAccessToken({ userId: user.id, role: user.role });
   const newRefreshToken = signRefreshToken({ userId: user.id, role: user.role });
 
   return { accessToken: newAccessToken, refreshToken: newRefreshToken };
 }
+
+export async function logout(db, refreshToken) {
+  if (!refreshToken) return;
+  try {
+    const payload = verifyRefreshToken(refreshToken);
+    if (payload.jti) {
+      revokeToken(db, payload.jti, new Date(payload.exp * 1000).toISOString());
+    }
+  } catch {
+    // Token already invalid/expired — nothing to revoke, treat as success.
+  }
+}
+
+export async function changePassword(db, userId, { currentPassword, newPassword }) {
+  const user = db.get('SELECT * FROM users WHERE id = ?', [userId]);
+  if (!user) {
+    const err = new Error('User not found');
+    err.statusCode = 404;
+    throw err;
+  }
+
+  if (!user.password_hash) {
+    const err = new Error('No password set for this account');
+    err.statusCode = 400;
+    throw err;
+  }
+
+  const valid = await verifyPassword(currentPassword, user.password_hash);
+  if (!valid) {
+    const err = new Error('Current password is incorrect');
+    err.statusCode = 401;
+    throw err;
+  }
+
+  if (!newPassword || newPassword.length < 8) {
+    const err = new Error('New password must be at least 8 characters');
+    err.statusCode = 400;
+    throw err;
+  }
+  if (!/[a-zA-Z]/.test(newPassword)) {
+    const err = new Error('New password must contain at least one letter');
+    err.statusCode = 400;
+    throw err;
+  }
+  if (!/[0-9]/.test(newPassword)) {
+    const err = new Error('New password must contain at least one number');
+    err.statusCode = 400;
+    throw err;
+  }
+
+  const password_hash = await hashPassword(newPassword);
+  const now = new Date().toISOString();
+  db.run('UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?', [password_hash, now, userId]);
+}

package/src/commands/start.js

@@ -1,8 +1,39 @@
 import { execSync, spawnSync } from 'node:child_process';
+import { createServer as createNetServer } from 'node:net';
 import { logger } from '../lib/logger.js';
 import { loadConfig } from '../lib/config.js';
 import { createServer } from '../server/index.js';
 
+/**
+ * Check whether a TCP port is available on the given host.
+ * Resolves true if the port can be bound, false if it's already in use.
+ */
+function isPortAvailable(port, host) {
+  return new Promise((resolve) => {
+    const probe = createNetServer();
+    probe.once('error', () => resolve(false));
+    probe.once('listening', () => { probe.close(); resolve(true); });
+    probe.listen(port, host);
+  });
+}
+
+/**
+ * Starting from `basePort`, find the first available port within `maxTries`.
+ * Logs a warning for each skipped port.
+ * Throws if no port is found within the range.
+ */
+async function findAvailablePort(basePort, host, maxTries = 3) {
+  for (let i = 0; i < maxTries; i++) {
+    const port = basePort + i;
+    if (await isPortAvailable(port, host)) return port;
+    logger.warn(`Port ${port} is already in use${i < maxTries - 1 ? `, trying ${port + 1}…` : '.'}`);
+  }
+  throw new Error(
+    `All ports ${basePort}–${basePort + maxTries - 1} are in use. ` +
+    `Free one up or set a custom port with --port or ROTIFEX_PORT.`,
+  );
+}
+
 /**
  * Try to load better-sqlite3. If the native addon is stale or compiled for
  * a different platform/Node version, rebuild it and re-exec this process.
@@ -66,6 +97,15 @@ export function registerStartCommand(program) {
 
         const config = loadConfig({ cliOverrides });
 
+        // ── Port resolution ───────────────────────────────────────────
+        // If the user explicitly set a port (--port flag or ROTIFEX_PORT env var)
+        // respect it exactly and let Fastify fail naturally if it's taken.
+        // Otherwise try the base port then fall through 4994 → 4995 → 4996.
+        const portExplicit = !!options.port || !!process.env.ROTIFEX_PORT;
+        if (!portExplicit) {
+          config.server.port = await findAvailablePort(config.server.port, config.server.host);
+        }
+
         // ── Create & start server ─────────────────────────────────────
         const app = await createServer(config);
 

package/src/engine/tableSync.js

@@ -3,7 +3,9 @@ import { createTable } from '../db/index.js';
 /**
  * Synchronise DB tables with the loaded schema.
  *
- * Uses `CREATE TABLE IF NOT EXISTS`, so it's safe to call on every startup.
+ * Uses `CREATE TABLE IF NOT EXISTS` for initial creation, then adds any
+ * columns that are present in the schema but missing from the existing table
+ * (safe schema evolution without data loss).
  *
  * @param {import('../db/adapters/base.js').DatabaseAdapter} db
  * @param {Map<string, { tableName: string, fields: object[] }>} models
@@ -24,5 +26,36 @@ export function syncTables(db, models) {
     });
 
     createTable(db, model.tableName, columns);
+    addMissingColumns(db, model.tableName, model.fields);
+  }
+}
+
+/**
+ * For an already-existing table, ALTER TABLE to add any columns that are in
+ * the schema definition but not yet in the DB.
+ *
+ * SQLite does not allow adding NOT NULL columns without a DEFAULT to existing
+ * tables (existing rows would violate the constraint), so we omit NOT NULL
+ * for added columns. The application layer handles required-field validation.
+ */
+function addMissingColumns(db, tableName, fields) {
+  const existing = new Set(
+    db.all(`PRAGMA table_info(${tableName})`).map(r => r.name),
+  );
+
+  for (const f of fields) {
+    if (existing.has(f.name)) continue;
+
+    let colDef = `${f.name} ${f.sqlType}`;
+    if (f.default !== undefined) {
+      const val = typeof f.default === 'string' ? `'${f.default}'` : f.default;
+      colDef += ` DEFAULT ${val}`;
+    }
+
+    try {
+      db.exec(`ALTER TABLE ${tableName} ADD COLUMN ${colDef}`);
+    } catch {
+      // Column added by a concurrent call — safe to ignore.
+    }
   }
 }

package/src/lib/config.js

@@ -90,10 +90,12 @@ function applyEnvOverrides(config) {
     config.storage.signedUrlSecret = env.ROTIFEX_STORAGE_SIGNED_URL_SECRET;
   }
 
-  // JWT auth secrets — read directly by auth.service.js via process.env,
-  // exposed here only so config introspection tools can see them.
-  if (env.JWT_SECRET)         { config.auth = config.auth || {}; config.auth.jwtSecret        = env.JWT_SECRET; }
-  if (env.JWT_REFRESH_SECRET) { config.auth = config.auth || {}; config.auth.jwtRefreshSecret = env.JWT_REFRESH_SECRET; }
+  // JWT auth secrets and token TTLs — read directly by auth.service.js via
+  // process.env, exposed here only so config introspection tools can see them.
+  if (env.JWT_SECRET)                  { config.auth = config.auth || {}; config.auth.jwtSecret         = env.JWT_SECRET; }
+  if (env.JWT_REFRESH_SECRET)          { config.auth = config.auth || {}; config.auth.jwtRefreshSecret  = env.JWT_REFRESH_SECRET; }
+  if (env.ROTIFEX_ACCESS_TOKEN_TTL)    { config.auth = config.auth || {}; config.auth.accessTokenTTL    = Number(env.ROTIFEX_ACCESS_TOKEN_TTL); }
+  if (env.ROTIFEX_REFRESH_TOKEN_TTL)   { config.auth = config.auth || {}; config.auth.refreshTokenTTL   = Number(env.ROTIFEX_REFRESH_TOKEN_TTL); }
 
   return config;
 }

package/src/server/routes/admin.js

@@ -7,6 +7,8 @@ import { getUsageSummary } from '../../ai/ai.usage.js';
 import { upsertModel, removeModel } from '../../engine/schemaStore.js';
 import { syncTables } from '../../engine/tableSync.js';
 import { getLogs } from '../../lib/logBuffer.js';
+import { registerUser, validateRegistrationInput } from '../../auth/auth.service.js';
+import { hashPassword } from '../../auth/password.util.js';
 
 // ── .env file helpers ─────────────────────────────────────────────────────────
 
@@ -226,6 +228,52 @@ export async function adminRoutes(app, { db }) {
     return reply.status(204).send();
   });
 
+  // ── POST /admin/api/users — create user with hashed password ──────
+  app.post('/admin/api/users', async (request, reply) => {
+    const { email, password, display_name, role } = request.body || {};
+
+    const errors = validateRegistrationInput({ email: email ?? '', password: password ?? '' });
+    if (errors.length) {
+      return reply.status(400).send({ error: 'Validation Error', message: errors, statusCode: 400 });
+    }
+
+    try {
+      const user = await registerUser(db, { email, password, display_name, role: role || 'user' });
+      return reply.status(201).send({ data: user, message: 'User created successfully' });
+    } catch (e) {
+      return reply.status(e.statusCode ?? 500).send({
+        error: 'User creation failed',
+        message: e.message,
+        statusCode: e.statusCode ?? 500,
+      });
+    }
+  });
+
+  // ── PUT /admin/api/users/:id/password — admin reset a user's password ─
+  app.put('/admin/api/users/:id/password', async (request, reply) => {
+    const { id } = request.params;
+    const { password } = request.body || {};
+
+    if (!password || password.length < 8) {
+      return reply.status(400).send({
+        error: 'Bad Request',
+        message: 'Password must be at least 8 characters',
+        statusCode: 400,
+      });
+    }
+
+    const user = db.get('SELECT id FROM users WHERE id = ?', [id]);
+    if (!user) {
+      return reply.status(404).send({ error: 'Not Found', message: 'User not found', statusCode: 404 });
+    }
+
+    const password_hash = await hashPassword(password);
+    const now = new Date().toISOString();
+    db.run('UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?', [password_hash, now, id]);
+
+    return reply.status(204).send();
+  });
+
   // ── GET /admin/api/env — read current .env values ─────────────────
   app.get('/admin/api/env', () => {
     const fileVars = readEnvFile();
@@ -266,6 +314,8 @@ export async function adminRoutes(app, { db }) {
 const ENV_KEYS = [
   'JWT_SECRET',
   'JWT_REFRESH_SECRET',
+  'ROTIFEX_ACCESS_TOKEN_TTL',
+  'ROTIFEX_REFRESH_TOKEN_TTL',
   'ROTIFEX_PORT',
   'ROTIFEX_HOST',
   'ROTIFEX_CORS_ORIGIN',

package/src/server/server.js

@@ -10,7 +10,7 @@ import { healthRoutes } from './routes/health.js';
 import { fileRoutes } from './routes/files.js';
 import { adminRoutes } from './routes/admin.js';
 import { authRoutes } from '../auth/auth.routes.js';
-import { ensureAuthSchema } from '../auth/auth.service.js';
+import { ensureAuthSchema, ensureTokenBlacklist } from '../auth/auth.service.js';
 import { aiRoutes } from '../ai/ai.routes.js';
 import { agentRoutes } from '../ai/agent.routes.js';
 import { registerJwtMiddleware } from '../auth/jwt.middleware.js';
@@ -73,6 +73,8 @@ export async function createServer(config) {
 
   // Ensure password_hash column exists on the users table now that it's created.
   ensureAuthSchema(db);
+  // Ensure the refresh token blacklist table exists.
+  ensureTokenBlacklist(db);
 
   // ── File Storage ────────────────────────────────────────────────────
   const storage = new StorageManager(db, config.storage);