chadstart 1.0.0

package/core/auth.js

@@ -0,0 +1,298 @@
+'use strict';
+
+/**
+ * JWT-based authentication for authenticable entities.
+ *
+ * Endpoints per authenticable entity:
+ *   POST /api/auth/:slug/signup
+ *   POST /api/auth/:slug/login
+ *   GET  /api/auth/:slug/me
+ *   GET  /api/auth/:slug/api-keys
+ *   POST /api/auth/:slug/api-keys
+ *   DELETE /api/auth/:slug/api-keys/:id
+ */
+
+const crypto = require('crypto');
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcryptjs');
+const db = require('./db');
+const logger = require('../utils/logger');
+
+const API_KEY_PREFIX = 'cs_';
+
+const JWT_SECRET = process.env.JWT_SECRET || process.env.TOKEN_SECRET_KEY || (() => {
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('JWT_SECRET must be set in production (e.g. `openssl rand -hex 64`).');
+  }
+  return 'chadstart-dev-secret-change-in-production';
+})();
+const JWT_EXPIRES = process.env.JWT_EXPIRES || '7d';
+const BCRYPT_ROUNDS = 10;
+
+function signToken(payload, expiresIn) {
+  return jwt.sign(payload, JWT_SECRET, { expiresIn: expiresIn !== undefined ? expiresIn : JWT_EXPIRES });
+}
+function verifyToken(token) { return jwt.verify(token, JWT_SECRET); }
+
+// ─── API Keys ─────────────────────────────────────────────────────────────────
+
+/**
+ * Initialize the _cs_api_keys system table.
+ * Must be called after initDb().
+ */
+function initApiKeys() {
+  db.getDb().exec(`
+    CREATE TABLE IF NOT EXISTS "_cs_api_keys" (
+      "id"          TEXT PRIMARY KEY,
+      "name"        TEXT NOT NULL,
+      "keyHash"     TEXT NOT NULL UNIQUE,
+      "userId"      TEXT NOT NULL,
+      "userEntity"  TEXT NOT NULL,
+      "permissions" TEXT NOT NULL DEFAULT '[]',
+      "entities"    TEXT NOT NULL DEFAULT '[]',
+      "expiresAt"   TEXT,
+      "createdAt"   TEXT NOT NULL,
+      "updatedAt"   TEXT NOT NULL,
+      "lastUsedAt"  TEXT
+    )
+  `);
+}
+
+function _hashApiKey(key) {
+  return crypto.createHash('sha256').update(key).digest('hex');
+}
+
+/**
+ * Create a new API key for a user.
+ * @param {string} userId
+ * @param {string} userEntity  Entity name (e.g. 'Admin')
+ * @param {object} opts        { name, permissions, entities, expiresAt }
+ * @returns {{ key: string, record: object }}  key is the plaintext — returned once only.
+ */
+function createApiKey(userId, userEntity, opts = {}) {
+  const { name = 'API Key', permissions = [], entities = [], expiresAt = null } = opts;
+  const key = API_KEY_PREFIX + crypto.randomBytes(32).toString('hex');
+  const keyHash = _hashApiKey(key);
+  const now = new Date().toISOString();
+  const id = crypto.randomUUID();
+
+  db.getDb().prepare(
+    `INSERT INTO "_cs_api_keys" ("id","name","keyHash","userId","userEntity","permissions","entities","expiresAt","createdAt","updatedAt")
+     VALUES (?,?,?,?,?,?,?,?,?,?)`
+  ).run(
+    id, name, keyHash, userId, userEntity,
+    JSON.stringify(permissions), JSON.stringify(entities),
+    expiresAt || null, now, now
+  );
+
+  const record = db.getDb().prepare('SELECT * FROM "_cs_api_keys" WHERE "id" = ?').get(id);
+  const safe = _safeApiKeyRecord(record);
+  return { key, record: safe };
+}
+
+/**
+ * Verify an API key string. Returns the DB record (without keyHash) or null.
+ */
+function verifyApiKeyStr(key) {
+  if (!key || !key.startsWith(API_KEY_PREFIX)) return null;
+  const hash = _hashApiKey(key);
+  const record = db.getDb().prepare('SELECT * FROM "_cs_api_keys" WHERE "keyHash" = ?').get(hash);
+  if (!record) return null;
+  if (record.expiresAt && new Date(record.expiresAt) < new Date()) return null;
+  // Update lastUsedAt asynchronously (best effort)
+  try {
+    db.getDb().prepare('UPDATE "_cs_api_keys" SET "lastUsedAt" = ? WHERE "id" = ?').run(new Date().toISOString(), record.id);
+  } catch { /* ignore */ }
+  return _safeApiKeyRecord(record);
+}
+
+/** List API keys for a specific user (without key hashes). */
+function listApiKeys(userId, userEntity) {
+  return db.getDb()
+    .prepare('SELECT * FROM "_cs_api_keys" WHERE "userId" = ? AND "userEntity" = ? ORDER BY "createdAt" DESC')
+    .all(userId, userEntity)
+    .map(_safeApiKeyRecord);
+}
+
+/** List all API keys — admin view (without key hashes). */
+function listAllApiKeys() {
+  return db.getDb()
+    .prepare('SELECT * FROM "_cs_api_keys" ORDER BY "createdAt" DESC')
+    .all()
+    .map(_safeApiKeyRecord);
+}
+
+/** Delete an API key by ID. */
+function deleteApiKey(id) {
+  db.getDb().prepare('DELETE FROM "_cs_api_keys" WHERE "id" = ?').run(id);
+}
+
+/** Strip the keyHash before returning to clients. */
+function _safeApiKeyRecord(record) {
+  if (!record) return null;
+  const { keyHash: _, ...safe } = record;
+  // Parse JSON arrays
+  if (typeof safe.permissions === 'string') {
+    try { safe.permissions = JSON.parse(safe.permissions); } catch { safe.permissions = []; }
+  }
+  if (typeof safe.entities === 'string') {
+    try { safe.entities = JSON.parse(safe.entities); } catch { safe.entities = []; }
+  }
+  return safe;
+}
+
+/**
+ * Resolve an Authorization header to a user payload.
+ * Supports both JWT Bearer tokens and API key strings (cs_ prefix).
+ * Returns { user, apiKeyPermissions, error }.
+ */
+function resolveAuthHeader(header) {
+  if (!header || !header.startsWith('Bearer ')) {
+    return { user: null, apiKeyPermissions: null, error: 'no_header' };
+  }
+  const token = header.slice(7);
+
+  // API key
+  if (token.startsWith(API_KEY_PREFIX)) {
+    const record = verifyApiKeyStr(token);
+    if (!record) return { user: null, apiKeyPermissions: null, error: 'invalid_token' };
+    return {
+      user: { id: record.userId, entity: record.userEntity },
+      apiKeyPermissions: { operations: record.permissions, entities: record.entities },
+      error: null,
+    };
+  }
+
+  // JWT
+  try {
+    const payload = verifyToken(token);
+    return { user: payload, apiKeyPermissions: null, error: null };
+  } catch {
+    return { user: null, apiKeyPermissions: null, error: 'invalid_token' };
+  }
+}
+
+/**
+ * Register API key management routes for each authenticable entity.
+ *   GET    /api/auth/:slug/api-keys       — list caller's keys
+ *   POST   /api/auth/:slug/api-keys       — create a new key
+ *   DELETE /api/auth/:slug/api-keys/:id   — delete a key
+ */
+function registerApiKeyRoutes(app, core) {
+  for (const entity of Object.values(core.authenticableEntities || {})) {
+    const slug = entity.slug;
+
+    // List caller's API keys
+    app.get(`/api/auth/${slug}/api-keys`, requireAuth(entity.name), (req, res) => {
+      try {
+        const keys = listApiKeys(req.user.id, entity.name);
+        res.json(keys);
+      } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // Create a new API key
+    app.post(`/api/auth/${slug}/api-keys`, requireAuth(entity.name), (req, res) => {
+      try {
+        const { name, permissions, entities: keyEntities, expiresAt } = req.body || {};
+        const { key, record } = createApiKey(req.user.id, entity.name, {
+          name: name || 'API Key',
+          permissions: Array.isArray(permissions) ? permissions : [],
+          entities: Array.isArray(keyEntities) ? keyEntities : [],
+          expiresAt: expiresAt || null,
+        });
+        res.status(201).json({ key, record });
+      } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+
+    // Delete one of the caller's API keys
+    app.delete(`/api/auth/${slug}/api-keys/:id`, requireAuth(entity.name), (req, res) => {
+      try {
+        const record = db.getDb().prepare('SELECT * FROM "_cs_api_keys" WHERE "id" = ?').get(req.params.id);
+        if (!record) return res.status(404).json({ error: 'API key not found' });
+        if (record.userId !== req.user.id || record.userEntity !== entity.name) {
+          return res.status(403).json({ error: 'Access denied' });
+        }
+        deleteApiKey(req.params.id);
+        res.json({ success: true });
+      } catch (e) { res.status(500).json({ error: e.message }); }
+    });
+  }
+}
+
+function registerAuthRoutes(app, core, emit) {
+  const _emit = typeof emit === 'function' ? emit : () => {};
+  for (const entity of Object.values(core.authenticableEntities || {})) {
+    const slug = entity.slug;
+    const table = entity.tableName;
+    const allowed = new Set(entity.properties.map((p) => p.name));
+    const sanitize = (body) => Object.fromEntries(Object.entries(body).filter(([k]) => allowed.has(k)));
+
+    // Check signup policy: forbidden => block, other values => allow
+    const signupPolicies = (entity.policies || {}).signup;
+    const signupForbidden = signupPolicies && signupPolicies.length > 0 && signupPolicies[0].access === 'forbidden';
+
+    app.post(`/api/auth/${slug}/signup`, async (req, res) => {
+      try {
+        if (signupForbidden) return res.status(403).json({ error: 'Signup is forbidden for this entity' });
+
+        const { email, password, ...rest } = req.body || {};
+        if (!email || !password) return res.status(400).json({ error: 'email and password are required' });
+        if (db.findAllSimple(table, { email }).length) return res.status(409).json({ error: 'Email already registered' });
+        const user = db.create(table, { email, password: await bcrypt.hash(password, BCRYPT_ROUNDS), ...sanitize(rest) });
+        _emit(`${entity.name}.created`, omitPassword(user));
+        res.status(201).json({ token: signToken({ id: user.id, entity: entity.name }), user: omitPassword(user) });
+      } catch (e) { logger.error('signup error', e.message); res.status(500).json({ error: e.message }); }
+    });
+
+    app.post(`/api/auth/${slug}/login`, async (req, res) => {
+      try {
+        const { email, password } = req.body || {};
+        if (!email || !password) return res.status(400).json({ error: 'email and password are required' });
+        const user = db.findAllSimple(table, { email })[0];
+        if (!user || !(await bcrypt.compare(password, user.password))) return res.status(401).json({ error: 'Invalid credentials' });
+        res.json({ token: signToken({ id: user.id, entity: entity.name }), user: omitPassword(user) });
+      } catch (e) { logger.error('login error', e.message); res.status(500).json({ error: e.message }); }
+    });
+
+    app.get(`/api/auth/${slug}/me`, requireAuth(entity.name), (req, res) => {
+      const user = db.findById(table, req.user.id);
+      if (!user) return res.status(404).json({ error: 'User not found' });
+      res.json(omitPassword(user));
+    });
+
+    logger.info(`  Registered auth routes at /api/auth/${slug}/`);
+  }
+}
+
+function requireAuth(entityName) {
+  return (req, res, next) => {
+    const { user, apiKeyPermissions, error } = resolveAuthHeader(req.headers.authorization);
+    if (!user) return res.status(401).json({ error: 'Authorization header required (Bearer <token>)' });
+    if (error === 'invalid_token') return res.status(401).json({ error: 'Invalid or expired token' });
+    if (entityName && user.entity !== entityName) return res.status(403).json({ error: 'Token does not belong to this collection' });
+    req.user = user;
+    if (apiKeyPermissions) req._apiKeyPermissions = apiKeyPermissions;
+    next();
+  };
+}
+
+function optionalAuth(req, _res, next) {
+  const { user, apiKeyPermissions } = resolveAuthHeader(req.headers.authorization);
+  if (user) {
+    req.user = user;
+    if (apiKeyPermissions) req._apiKeyPermissions = apiKeyPermissions;
+  }
+  next();
+}
+
+function omitPassword(user) {
+  const { password: _, ...rest } = user;
+  return rest;
+}
+
+module.exports = {
+  registerAuthRoutes, registerApiKeyRoutes, initApiKeys,
+  requireAuth, optionalAuth, resolveAuthHeader,
+  signToken, verifyToken, omitPassword, JWT_SECRET,
+  createApiKey, listApiKeys, listAllApiKeys, deleteApiKey, verifyApiKeyStr,
+};

package/core/db.js

@@ -0,0 +1,384 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const Database = require('better-sqlite3');
+const path = require('path');
+const logger = require('../utils/logger');
+
+let db = null;
+// Cached entity metadata for relation queries. Set by initDb.
+let _core = null;
+
+const SQL_TYPE = {
+  text: 'TEXT', string: 'TEXT', richText: 'TEXT',
+  integer: 'INTEGER', int: 'INTEGER',
+  number: 'REAL', float: 'REAL', real: 'REAL', money: 'REAL',
+  boolean: 'INTEGER', bool: 'INTEGER',
+  date: 'TEXT', timestamp: 'TEXT', email: 'TEXT', link: 'TEXT',
+  password: 'TEXT', choice: 'TEXT', location: 'TEXT',
+  file: 'TEXT', image: 'TEXT', group: 'TEXT', json: 'TEXT',
+};
+
+function generateUUID() {
+  return crypto.randomUUID();
+}
+
+function initDb(core, dbPath) {
+  const resolved = dbPath ? path.resolve(dbPath) : path.resolve(process.env.DB_PATH || 'data/chadstart.db');
+  try {
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  } catch (err) {
+    throw new Error(`Failed to create database directory "${path.dirname(resolved)}": ${err.message}`);
+  }
+  try {
+    db = new Database(resolved);
+  } catch (err) {
+    throw new Error(
+      `Failed to open database at "${resolved}": ${err.message}\n` +
+      `  Make sure the directory exists and is writable, and that no other process has an exclusive lock on the file.`
+    );
+  }
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  _core = core;
+  logger.info(`Database initialized at ${resolved}`);
+  syncSchema(core);
+  return db;
+}
+
+function syncSchema(core) {
+  for (const entity of Object.values(core.entities)) {
+    const cols = buildColumnDefs(entity, core.entities);
+    const existing = getExistingColumns(entity.tableName);
+
+    if (!existing) {
+      const defs = ['"id" TEXT PRIMARY KEY', '"createdAt" TEXT', '"updatedAt" TEXT', ...cols.map((c) => c.def)];
+      db.exec(`CREATE TABLE "${entity.tableName}" (${defs.join(', ')})`);
+    } else {
+      // Add createdAt/updatedAt if missing (migration)
+      if (!existing.has('createdAt')) {
+        db.exec(`ALTER TABLE "${entity.tableName}" ADD COLUMN "createdAt" TEXT`);
+      }
+      if (!existing.has('updatedAt')) {
+        db.exec(`ALTER TABLE "${entity.tableName}" ADD COLUMN "updatedAt" TEXT`);
+      }
+      for (const col of cols) {
+        if (!existing.has(col.name)) {
+          db.exec(`ALTER TABLE "${entity.tableName}" ADD COLUMN ${stripConstraints(col.def)}`);
+        }
+      }
+    }
+  }
+
+  // belongsToMany junction tables
+  for (const entity of Object.values(core.entities)) {
+    for (const rel of entity.belongsToMany || []) {
+      const relName = typeof rel === 'string' ? rel : (rel.entity || rel.name);
+      const relEntity = core.entities[relName];
+      if (!relEntity) continue;
+      const [a, b] = [entity.tableName, relEntity.tableName].sort();
+      const jt = `${a}_${b}`;
+      if (!getExistingColumns(jt)) {
+        db.exec(
+          `CREATE TABLE "${jt}" ("${a}_id" TEXT REFERENCES "${a}"(id), "${b}_id" TEXT REFERENCES "${b}"(id), PRIMARY KEY ("${a}_id", "${b}_id"))`
+        );
+      }
+    }
+  }
+}
+
+function getExistingColumns(table) {
+  try {
+    const rows = db.pragma(`table_info("${table}")`);
+    return rows && rows.length ? new Set(rows.map((r) => r.name)) : null;
+  } catch { return null; }
+}
+
+function stripConstraints(def) {
+  return def.replace(/\bNOT\s+NULL\b/gi, '').replace(/\bUNIQUE\b/gi, '')
+    .replace(/\bREFERENCES\s+"[^"]+"\([^)]+\)/gi, '').replace(/\s{2,}/g, ' ').trim();
+}
+
+function buildColumnDefs(entity, allEntities) {
+  const cols = [];
+
+  if (entity.authenticable) {
+    cols.push({ name: 'email', def: '"email" TEXT NOT NULL UNIQUE' });
+    cols.push({ name: 'password', def: '"password" TEXT NOT NULL' });
+  }
+
+  for (const p of entity.properties) {
+    // Skip email/password for authenticable entities — they are already added above
+    if (entity.authenticable && (p.name === 'email' || p.name === 'password')) continue;
+    cols.push({ name: p.name, def: `"${p.name}" ${SQL_TYPE[p.type] || 'TEXT'}` });
+  }
+
+  for (const rel of entity.belongsTo || []) {
+    const relName = typeof rel === 'string' ? rel : (rel.entity || rel.name);
+    const ref = allEntities[relName];
+    if (ref) {
+      const fk = `${ref.tableName}_id`;
+      cols.push({ name: fk, def: `"${fk}" TEXT REFERENCES "${ref.tableName}"(id)` });
+    }
+  }
+
+  return cols;
+}
+
+function getDb() {
+  if (!db) throw new Error('Database not initialized. Call initDb() first.');
+  return db;
+}
+
+// ─── Filter parsing ──────────────────────────────────────────────────────────
+
+const FILTER_SUFFIXES = {
+  _eq:   (col, val) => ({ sql: `"${col}" = ?`, val }),
+  _neq:  (col, val) => ({ sql: `"${col}" != ?`, val }),
+  _gt:   (col, val) => ({ sql: `"${col}" > ?`, val }),
+  _gte:  (col, val) => ({ sql: `"${col}" >= ?`, val }),
+  _lt:   (col, val) => ({ sql: `"${col}" < ?`, val }),
+  _lte:  (col, val) => ({ sql: `"${col}" <= ?`, val }),
+  _like: (col, val) => ({ sql: `"${col}" LIKE ?`, val }),
+  _in:   (col, val) => {
+    const items = String(val).split(',');
+    return { sql: `"${col}" IN (${items.map(() => '?').join(',')})`, val: items };
+  },
+};
+
+/**
+ * Parse query string params into filter clauses.
+ * Supports: prop=val (exact match), prop_eq=val, prop_gt=val, etc.
+ */
+function parseFilters(query, validColumns) {
+  const clauses = [];
+  const values = [];
+  const reserved = new Set(['page', 'perPage', 'orderBy', 'order', 'relations']);
+
+  for (const [key, val] of Object.entries(query)) {
+    if (reserved.has(key)) continue;
+
+    let matched = false;
+    for (const [suffix, builder] of Object.entries(FILTER_SUFFIXES)) {
+      if (key.endsWith(suffix)) {
+        const col = key.slice(0, -suffix.length);
+        if (validColumns.has(col)) {
+          const result = builder(col, val);
+          clauses.push(result.sql);
+          if (Array.isArray(result.val)) values.push(...result.val);
+          else values.push(result.val);
+        }
+        matched = true;
+        break;
+      }
+    }
+
+    // Exact match (no suffix)
+    if (!matched && validColumns.has(key)) {
+      clauses.push(`"${key}" = ?`);
+      values.push(val);
+    }
+  }
+
+  return { clauses, values };
+}
+
+// ─── CRUD ────────────────────────────────────────────────────────────────────
+
+/**
+ * Query rows with filter suffixes, ordering, and pagination.
+ * opts: { page, perPage, orderBy, order, relations }
+ */
+function findAll(table, query = {}, opts = {}) {
+  const d = getDb();
+  const validCols = new Set(d.pragma(`table_info("${table}")`).map((r) => r.name));
+  const { clauses, values } = parseFilters(query, validCols);
+
+  let sql = `SELECT * FROM "${table}"`;
+  if (clauses.length) sql += ` WHERE ${clauses.join(' AND ')}`;
+
+  // Ordering — only allow column names that exist and match safe pattern
+  const SAFE_COL = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+  const orderBy = opts.orderBy || 'createdAt';
+  const orderDir = (opts.order || 'DESC').toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
+  if (validCols.has(orderBy) && SAFE_COL.test(orderBy)) {
+    sql += ` ORDER BY "${orderBy}" ${orderDir}`;
+  }
+
+  // Count total before pagination
+  const countSql = sql.replace(/^SELECT \*/, 'SELECT COUNT(*) as total');
+  const total = d.prepare(countSql).get(...values).total;
+
+  // Pagination
+  const page = Math.max(1, parseInt(opts.page, 10) || 1);
+  const perPage = Math.min(1000, Math.max(1, parseInt(opts.perPage, 10) || 10));
+  const offset = (page - 1) * perPage;
+  sql += ` LIMIT ? OFFSET ?`;
+
+  const data = d.prepare(sql).all(...values, perPage, offset);
+  const lastPage = Math.max(1, Math.ceil(total / perPage));
+
+  return {
+    data,
+    currentPage: page,
+    lastPage,
+    from: total > 0 ? offset + 1 : 0,
+    to: Math.min(offset + perPage, total),
+    total,
+    perPage,
+  };
+}
+
+/**
+ * Simple findAll without pagination for internal use (e.g., auth lookups).
+ */
+function findAllSimple(table, filters = {}) {
+  const d = getDb();
+  const keys = Object.keys(filters);
+  if (!keys.length) return d.prepare(`SELECT * FROM "${table}"`).all();
+  const valid = new Set(d.pragma(`table_info("${table}")`).map((r) => r.name));
+  const safe = Object.fromEntries(keys.filter((k) => valid.has(k)).map((k) => [k, filters[k]]));
+  if (!Object.keys(safe).length) return d.prepare(`SELECT * FROM "${table}"`).all();
+  const where = Object.keys(safe).map((k) => `"${k}" = ?`).join(' AND ');
+  return d.prepare(`SELECT * FROM "${table}" WHERE ${where}`).all(...Object.values(safe));
+}
+
+function findById(table, id) {
+  return getDb().prepare(`SELECT * FROM "${table}" WHERE id = ?`).get(id) || null;
+}
+
+function create(table, data) {
+  const d = getDb();
+  const now = new Date().toISOString();
+  const id = generateUUID();
+  const full = { id, createdAt: now, updatedAt: now, ...data };
+  const keys = Object.keys(full);
+  const cols = keys.map((k) => `"${k}"`).join(', ');
+  const ph = keys.map(() => '?').join(', ');
+  d.prepare(`INSERT INTO "${table}" (${cols}) VALUES (${ph})`).run(...Object.values(full));
+  return findById(table, id);
+}
+
+function update(table, id, data) {
+  const now = new Date().toISOString();
+  const full = { ...data, updatedAt: now };
+  const keys = Object.keys(full);
+  if (!keys.length) return findById(table, id);
+  const set = keys.map((k) => `"${k}" = ?`).join(', ');
+  getDb().prepare(`UPDATE "${table}" SET ${set} WHERE id = ?`).run(...Object.values(full), id);
+  return findById(table, id);
+}
+
+function remove(table, id) {
+  const existing = findById(table, id);
+  if (!existing) return null;
+  getDb().prepare(`DELETE FROM "${table}" WHERE id = ?`).run(id);
+  return existing;
+}
+
+// ─── Relation helpers ────────────────────────────────────────────────────────
+
+/**
+ * Load relations for a single row. Mutates the row in-place.
+ * relationNames: comma-separated string or array.
+ */
+function loadRelations(row, entity, relationNames) {
+  if (!row || !entity || !relationNames || !_core) return row;
+  const names = Array.isArray(relationNames) ? relationNames : relationNames.split(',').map((s) => s.trim());
+
+  for (const relName of names) {
+    // belongsTo: look up the FK column
+    const btRel = (entity.belongsTo || []).find((r) => {
+      const rName = typeof r === 'string' ? r : (r.name || r.entity);
+      return rName.toLowerCase() === relName.toLowerCase();
+    });
+    if (btRel) {
+      const relEntityName = typeof btRel === 'string' ? btRel : (btRel.entity || btRel.name);
+      const relEntity = _core.entities[relEntityName];
+      if (relEntity) {
+        const fk = `${relEntity.tableName}_id`;
+        if (row[fk]) {
+          row[relName] = findById(relEntity.tableName, row[fk]);
+        } else {
+          row[relName] = null;
+        }
+      }
+      continue;
+    }
+
+    // belongsToMany: look up junction table
+    const btmRel = (entity.belongsToMany || []).find((r) => {
+      const rName = typeof r === 'string' ? r : (r.name || r.entity);
+      return rName.toLowerCase() === relName.toLowerCase();
+    });
+    if (btmRel) {
+      const relEntityName = typeof btmRel === 'string' ? btmRel : (btmRel.entity || btmRel.name);
+      const relEntity = _core.entities[relEntityName];
+      if (relEntity) {
+        const [a, b] = [entity.tableName, relEntity.tableName].sort();
+        const jt = `${a}_${b}`;
+        const myCol = `${entity.tableName}_id`;
+        const otherCol = `${relEntity.tableName}_id`;
+        const related = getDb()
+          .prepare(`SELECT t.* FROM "${relEntity.tableName}" t JOIN "${jt}" j ON j."${otherCol}" = t.id WHERE j."${myCol}" = ?`)
+          .all(row.id);
+        row[relName] = related;
+      }
+      continue;
+    }
+
+    // hasMany (reverse belongsTo): another entity belongsTo this entity
+    for (const otherEntity of Object.values(_core.entities)) {
+      const reverseRel = (otherEntity.belongsTo || []).find((r) => {
+        const rEntity = typeof r === 'string' ? r : (r.entity || r.name);
+        return rEntity === entity.name;
+      });
+      if (reverseRel && otherEntity.slug.toLowerCase() === relName.toLowerCase()) {
+        const fk = `${entity.tableName}_id`;
+        row[relName] = getDb()
+          .prepare(`SELECT * FROM "${otherEntity.tableName}" WHERE "${fk}" = ?`)
+          .all(row.id);
+        break;
+      }
+    }
+  }
+
+  return row;
+}
+
+/**
+ * Store belongsToMany relations for a record.
+ * body may contain keys like `skillIds: [id1, id2]`.
+ */
+function saveBelongsToMany(entity, recordId, body) {
+  if (!_core) return;
+  for (const rel of entity.belongsToMany || []) {
+    const relEntityName = typeof rel === 'string' ? rel : (rel.entity || rel.name);
+    const relEntity = _core.entities[relEntityName];
+    if (!relEntity) continue;
+
+    // Convention: entityIds (camelCase plural)
+    const idsKey = `${relEntityName.charAt(0).toLowerCase() + relEntityName.slice(1)}Ids`;
+    const ids = body[idsKey];
+    if (!Array.isArray(ids)) continue;
+
+    const [a, b] = [entity.tableName, relEntity.tableName].sort();
+    const jt = `${a}_${b}`;
+    const myCol = `${entity.tableName}_id`;
+    const otherCol = `${relEntity.tableName}_id`;
+
+    // Clear existing
+    getDb().prepare(`DELETE FROM "${jt}" WHERE "${myCol}" = ?`).run(recordId);
+
+    // Insert new
+    const ins = getDb().prepare(`INSERT OR IGNORE INTO "${jt}" ("${myCol}", "${otherCol}") VALUES (?, ?)`);
+    for (const otherId of ids) ins.run(recordId, otherId);
+  }
+}
+
+module.exports = {
+  initDb, syncSchema, getDb, generateUUID,
+  findAll, findAllSimple, findById, create, update, remove,
+  loadRelations, saveBelongsToMany,
+};