@volcanicminds/backend 3.4.0 → 3.6.1

package/lib/config/general.ts

@@ -2,8 +2,10 @@ export default {
   name: 'general',
   options: {
     allow_multiple_admin: false,
-    admin_can_change_passwords: false,
     allow_admin_change_password_users: false,
+    // opt-in: users created by an admin (POST /users) start confirmed and can log in
+    // immediately, unless the payload explicitly sends confirmed:false.
+    allow_admin_create_confirmed_users: false,
     reset_external_id_on_login: false,
     scheduler: false,
     embedded_auth: true,
@@ -17,7 +19,13 @@ export default {
       query_key: 'tid'
     },
     manifest: {
-      enabled: false // opt-in: exposes GET /admin/manifest (admin-only) for the backoffice engine
+      // opt-in: exposes GET /admin/manifest (admin-only) for the backoffice engine
+      enabled: false
+    },
+    cache: {
+      // opt-in: in-memory LRU+TTL cache for routes that declare `cache:`.
+      // When enabled, ttl (default 3600s) and maxEntries (default 1000) can be set here.
+      enabled: false
     }
   }
 }

package/lib/hooks/onError.ts

@@ -2,32 +2,37 @@
 import { FastifyRequest, FastifyReply } from 'fastify'
 
 export default async (_req: FastifyRequest, reply: FastifyReply, error: any) => {
-  if (log.e) log.error(`${error?.message || error}`)
+  // Normalize the message up-front: `error` may be a string, or an object without
+  // a `message` — reading `.includes` on an undefined message would crash the
+  // error handler itself (and mask the real error as an unhandled 500).
+  const message = typeof error?.message === 'string' ? error.message : String(error?.message ?? error ?? '')
+
+  if (log.e) log.error(message || `${error}`)
   if (log.t) log.trace(error)
 
-  if (error.statusCode && error.statusCode >= 400) {
+  if (error?.statusCode && error.statusCode >= 400) {
     return reply.code(error.statusCode).send(error)
   }
 
-  if (error.message === 'Wrong credentials' || error.message === 'Unauthorized') {
+  if (message === 'Wrong credentials' || message === 'Unauthorized') {
     return reply.code(403).send({
       statusCode: 403,
       error: 'Forbidden',
-      message: error.message
+      message
     })
   }
 
-  if (error.message.includes('not found')) {
+  if (message.includes('not found')) {
     return reply.code(404).send({
       statusCode: 404,
       error: 'Not Found',
-      message: error.message
+      message
     })
   }
 
   return reply.code(500).send({
     statusCode: 500,
     error: 'Internal Server Error',
-    message: error.message
+    message
   })
 }

package/lib/hooks/onRequest.ts

@@ -147,7 +147,13 @@ export default async (req, reply) => {
     if (cfg.requiredRoles?.length > 0) {
       const { method = '', url = '', requiredRoles } = cfg
       const authorizedRoles: string[] = req.roles()
-      const hasPermission = requiredRoles.some((r) => authorizedRoles.includes(r.code))
+      // A route open to `public` is open to EVERY caller: anonymous requests already
+      // pass (they carry the `public` role), and an authenticated subject must never
+      // rank below anonymous — without this, a user whose roles don't include
+      // `public` (e.g. only `backoffice`) would get 403 on public routes such as
+      // /users/me or /auth/change-password.
+      const isPublicRoute = requiredRoles.some((r) => r.code === roles.public.code)
+      const hasPermission = isPublicRoute || requiredRoles.some((r) => authorizedRoles.includes(r.code))
 
       if (!hasPermission) {
         // 401 when there is no authenticated subject (must log in first); 403 when

package/lib/loader/general.ts

@@ -7,7 +7,6 @@ export async function load() {
     name: 'general',
     options: {
       allow_multiple_admin: false,
-      admin_can_change_passwords: false,
       allow_admin_change_password_users: false,
       reset_external_id_on_login: false,
       scheduler: false,
@@ -20,6 +19,9 @@ export async function load() {
       },
       manifest: {
         enabled: false
+      },
+      cache: {
+        enabled: false
       }
     }
   }

package/lib/loader/router.ts

@@ -3,6 +3,7 @@ import yn from '../util/yn.js'
 import type { Role, Route, ConfiguredRoute, RouteConfig } from '../../types/global.js'
 import { FastifyReply, FastifyRequest } from 'fastify'
 import { normalizePatterns } from '../util/path.js'
+import { normalizeRouteCache, buildCacheHooks, cacheEnabled } from '../util/cache.js'
 import { globSync } from 'glob'
 import path from 'path'
 import { fileURLToPath } from 'url'
@@ -83,7 +84,8 @@ export function processRoute(
     roles: rs = [],
     config = {} as RouteConfig,
     middlewares = [],
-    rateLimit
+    rateLimit,
+    cache: cacheInput
   } = route
 
   const rsp = !rs.length ? [roles.public] : rs
@@ -186,6 +188,9 @@ export function processRoute(
       tenantContext,
       rawBody,
       rateLimit,
+      // Per-route cache (falls back to the file-level `config.cache`); the default
+      // key-group is the api folder (`dir`), overridable.
+      cache: normalizeRouteCache(cacheInput ?? defaultConfig?.cache, dir),
       base,
       file: path.join(base, defaultConfig.controller || 'controller', handlerParts[0]),
       func: handlerParts[1],
@@ -245,13 +250,33 @@ async function applyRoutes(server: any, routes: ConfiguredRoute[]): Promise<void
   let countRoutes = 0
   for (const route of routes) {
     if (route?.enable) {
-      const { handler, method, path, middlewares, roles, rawBody, rateLimit, base, file, func, doc, tenantContext } =
+      const { handler, method, path, middlewares, roles, rawBody, rateLimit, base, file, func, doc, tenantContext, cache } =
         route
 
       if (log.d) log.debug(`* Add path ${method} ${path} on handle ${handler}`)
       const midds = await loadMiddlewares(base, middlewares)
 
-      server.route({
+      // Attach the cache read (preHandler, runs after auth) and write (onSend)
+      // hooks only when the route opts in — no overhead on uncached routes.
+      const cacheHooks = cache && (cache.enabled || cache.invalidates?.length) ? buildCacheHooks(cache) : null
+
+      // Courtesy log at wiring time: describe each cache-declaring route, and warn
+      // when a route opts in while the global master switch is off (hooks are inert).
+      if (cacheHooks) {
+        if (!cacheEnabled()) {
+          if (log.w)
+            log.warn(
+              `Cache 🧊 route ${method} ${path} declares cache/invalidation but global cache is disabled (options.cache.enabled) — inert`
+            )
+        } else if (log.d) {
+          const parts: string[] = []
+          if (cache?.enabled) parts.push(`read+write ttl ${cache.ttl ?? 'default'}s keyGroup '${cache.keyGroup}'`)
+          if (cache?.invalidates?.length) parts.push(`invalidates [${cache.invalidates.join(', ')}]`)
+          log.debug(`Cache 🧊 route ${method} ${path} — ${parts.join(', ')}`)
+        }
+      }
+
+      const routeDef: any = {
         method: method,
         path: path,
         schema: doc,
@@ -260,7 +285,8 @@ async function applyRoutes(server: any, routes: ConfiguredRoute[]): Promise<void
           requiredRoles: roles || [],
           rawBody: rawBody || false,
           rateLimit: rateLimit || undefined,
-          tenantContext: tenantContext
+          tenantContext: tenantContext,
+          cache: cache || undefined
         },
         handler: async function (req: FastifyRequest, reply: FastifyReply) {
           let module
@@ -286,7 +312,16 @@ async function applyRoutes(server: any, routes: ConfiguredRoute[]): Promise<void
 
           return await module[func](req, reply)
         }
-      })
+      }
+
+      if (cacheHooks?.preHandler) {
+        // Cache read runs before the route middlewares; auth/roles are already
+        // enforced in the global onRequest hook, so this is safe.
+        routeDef.preHandler = [cacheHooks.preHandler, ...((midds as any).preHandler || [])]
+      }
+      if (cacheHooks?.onSend) routeDef.onSend = cacheHooks.onSend
+
+      server.route(routeDef)
 
       countRoutes++
     }

package/lib/manifest/generator.ts

@@ -313,7 +313,7 @@ function collectFields(
     const kind = crudKind(r.method, rest)
     // Write side: create/update bodies, plus a PUT/PATCH on the BASE path — the singleton
     // update (e.g. PUT /company), which crudKind classifies as 'action'. Restricted to the
-    // base path so sub-route action payloads (e.g. /vehicles/:id/images/reorder) don't leak in.
+    // base path so sub-route action payloads (e.g. /posts/:id/attachments/reorder) don't leak in.
     const isSingletonWrite = rest.length === 0 && (r.method === 'PUT' || r.method === 'PATCH')
     if (kind === 'create' || kind === 'update' || isSingletonWrite) addSide(r.doc?.body, 'write')
     if (kind === 'read' || kind === 'list') {

package/lib/util/cache.ts

@@ -0,0 +1,258 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * In-memory LRU + TTL cache backing the per-route `cache` capability.
+ *
+ * No external dependency: a JS `Map` preserves insertion order, so LRU is
+ * "delete + reinsert on read" (marks most-recently-used) and "evict the first key
+ * on overflow" (the least-recently-used). TTL is enforced lazily on read plus a
+ * periodic background sweep. Entries are keyed as `keyGroup :: scope :: method url`
+ * where `scope` isolates by tenant / authenticated subject / role set so a cached
+ * response is never served across tenants, users or privilege levels.
+ *
+ * The store is configured once at boot from `global.config.options.cache`
+ * (see index.ts) and exposed both as `global.cache` and via the package root
+ * exports `invalidateCache` / `cache`.
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import type { NormalizedRouteCache, RouteCache } from '../../types/global.js'
+
+interface Entry {
+  value: any
+  expires: number // epoch ms; Infinity when no TTL
+}
+
+interface CacheSettings {
+  enabled: boolean
+  ttl: number // default TTL (seconds) for routes without an explicit ttl
+  maxEntries: number // LRU cap
+}
+
+// Single source of truth for the cache defaults. `enabled` is opt-in (off by
+// default, consistent with the other optional features like `manifest` /
+// `multi_tenant`); `ttl`/`maxEntries` are the numeric fallbacks applied per-field
+// by configureCache, so no other module needs to restate them.
+const DEFAULTS: CacheSettings = { enabled: false, ttl: 3600, maxEntries: 1000 }
+
+let settings: CacheSettings = { ...DEFAULTS }
+const store = new Map<string, Entry>()
+let hits = 0
+let misses = 0
+let sweepTimer: ReturnType<typeof setInterval> | null = null
+
+const nowMs = () => Date.now()
+
+function startSweep(intervalMs = 60_000) {
+  if (sweepTimer) clearInterval(sweepTimer)
+  sweepTimer = setInterval(() => {
+    const t = nowMs()
+    for (const [k, e] of store) if (e.expires <= t) store.delete(k)
+  }, intervalMs)
+  // Never keep the event loop alive just for the sweep.
+  sweepTimer.unref?.()
+}
+
+/** (Re)configure the cache from global options and log the effective config. */
+export function configureCache(opts?: CacheSettings | Partial<CacheSettings>): CacheSettings {
+  settings = {
+    // Opt-in master switch: enabled only when explicitly set to true.
+    enabled: opts?.enabled === true,
+    ttl: Number(opts?.ttl) > 0 ? Number(opts?.ttl) : DEFAULTS.ttl,
+    maxEntries: Number(opts?.maxEntries) > 0 ? Number(opts?.maxEntries) : DEFAULTS.maxEntries
+  }
+  store.clear()
+  hits = 0
+  misses = 0
+  if (settings.enabled) {
+    startSweep()
+    if (log?.i)
+      log.info(
+        `Cache 🧊 enabled — ttl ${settings.ttl}s, maxEntries ${settings.maxEntries}, strategy LRU+TTL`
+      )
+  } else {
+    if (sweepTimer) {
+      clearInterval(sweepTimer)
+      sweepTimer = null
+    }
+    if (log?.i) log.info('Cache 🧊 disabled')
+  }
+  return settings
+}
+
+export const cacheEnabled = () => settings.enabled
+export const defaultTtl = () => settings.ttl
+
+export function cacheGet(key: string): any {
+  const e = store.get(key)
+  if (!e) {
+    misses++
+    return undefined
+  }
+  if (e.expires <= nowMs()) {
+    store.delete(key)
+    misses++
+    return undefined
+  }
+  // LRU touch: re-insert to mark as most-recently used.
+  store.delete(key)
+  store.set(key, e)
+  hits++
+  return e.value
+}
+
+export function cacheSet(key: string, value: any, ttlSec?: number): void {
+  const ttl = Number(ttlSec) > 0 ? Number(ttlSec) : settings.ttl
+  if (store.has(key)) store.delete(key)
+  store.set(key, { value, expires: ttl > 0 ? nowMs() + ttl * 1000 : Infinity })
+  // Evict least-recently-used entries beyond the cap.
+  while (store.size > settings.maxEntries) {
+    const oldest = store.keys().next().value
+    if (oldest === undefined) break
+    store.delete(oldest)
+  }
+}
+
+/**
+ * Invalidate cached entries. With no argument clears everything; otherwise removes
+ * every entry belonging to the given key-group(s). Returns the number removed.
+ */
+export function invalidateCache(keyGroups?: string | string[]): number {
+  if (keyGroups == null) {
+    const n = store.size
+    store.clear()
+    if (log?.d) log.debug(`Cache 🧊 flushAll — ${n} entries removed`)
+    return n
+  }
+  const list = Array.isArray(keyGroups) ? keyGroups : [keyGroups]
+  const prefixes = list.map((g) => `${g}::`)
+  let n = 0
+  for (const k of [...store.keys()]) {
+    if (prefixes.some((p) => k.startsWith(p))) {
+      store.delete(k)
+      n++
+    }
+  }
+  if (log?.d) log.debug(`Cache 🧊 invalidate [${list.join(', ')}] — ${n} entries removed`)
+  return n
+}
+
+export function cacheStats() {
+  return { size: store.size, hits, misses, ...settings }
+}
+
+/** Facade exposed as `global.cache` and re-exported from the package root. */
+export const cache = {
+  get: cacheGet,
+  set: cacheSet,
+  del: (key: string) => store.delete(key),
+  invalidate: invalidateCache,
+  flushAll: () => invalidateCache(),
+  stats: cacheStats,
+  enabled: cacheEnabled
+}
+
+// ---------------------------------------------------------------------------
+// Route-config normalization + request scoping + Fastify hook factory
+// ---------------------------------------------------------------------------
+
+/** Normalize the authored `cache` prop (`true` | number | object) into the stored
+ *  form, resolving the key-group to the api folder (area) when omitted. Returns
+ *  undefined when there is nothing to do (absent/false and no invalidation). */
+export function normalizeRouteCache(
+  input: boolean | number | RouteCache | undefined,
+  defaultKeyGroup: string
+): NormalizedRouteCache | undefined {
+  if (input == null || input === false) return undefined
+  const obj: RouteCache = input === true ? {} : typeof input === 'number' ? { ttl: input } : input
+  const enabled = obj.enabled !== false
+  const invalidates =
+    obj.invalidates == null ? undefined : Array.isArray(obj.invalidates) ? obj.invalidates : [obj.invalidates]
+  if (!enabled && !invalidates?.length) return undefined
+  return {
+    enabled,
+    ttl: typeof obj.ttl === 'number' && obj.ttl > 0 ? obj.ttl : undefined,
+    keyGroup: obj.keyGroup || defaultKeyGroup,
+    invalidates
+  }
+}
+
+const HIT = Symbol('volcanic.cacheHit')
+const HEADER_ALLOW = /^(content-type|v-)/i
+
+/** Scope segment: isolates cached data by tenant, authenticated subject and roles. */
+function scope(req: any): string {
+  const tenant = req.tenant?.id ?? ''
+  const subject = req.user?.externalId ?? req.token?.getId?.() ?? 'anon'
+  const rolesList = typeof req.roles === 'function' ? req.roles() : []
+  const rolesKey = [...(rolesList || [])].sort().join(',')
+  return `${tenant}|${subject}|${rolesKey}`
+}
+
+function keyFor(req: any, keyGroup: string): string {
+  return `${keyGroup}::${scope(req)}::${req.method} ${req.url}`
+}
+
+/** Skip caching when a tenant is expected (multi-tenant + tenantContext) but missing,
+ *  to avoid ever leaking data across tenants. */
+function tenantMissing(req: any): boolean {
+  const mt = global.config?.options?.multi_tenant?.enabled
+  const tenantCtx = req.routeOptions?.config?.tenantContext
+  return Boolean(mt && tenantCtx !== false && !req.tenant)
+}
+
+/** Build the per-route read (preHandler) and write (onSend) hooks for a cached route. */
+export function buildCacheHooks(routeCache: NormalizedRouteCache) {
+  const cacheable = routeCache.enabled === true
+  const keyGroup = routeCache.keyGroup
+  const ttl = routeCache.ttl
+  const invalidates = routeCache.invalidates
+
+  const preHandler = cacheable
+    ? async (req: FastifyRequest, reply: FastifyReply) => {
+        if (!cacheEnabled() || (req as any).method !== 'GET' || tenantMissing(req)) return
+        const hit = cacheGet(keyFor(req, keyGroup))
+        if (hit) {
+          for (const [h, v] of Object.entries(hit.headers as Record<string, any>)) reply.header(h, v as any)
+          ;(req as any)[HIT] = true
+          reply.code(hit.statusCode)
+          if (log?.d) log.debug(`Cache 🧊 hit ${keyGroup} ${(req as any).method} ${(req as any).url}`)
+          return reply.send(hit.payload)
+        }
+        if (log?.d) log.debug(`Cache 🧊 miss ${keyGroup} ${(req as any).method} ${(req as any).url}`)
+      }
+    : undefined
+
+  const onSend = async (req: FastifyRequest, reply: FastifyReply, payload: any) => {
+    // Master switch off: nothing to store and — on a volatile in-memory cache — nothing
+    // to invalidate (the store is already empty), so skip the whole hook. Also avoids
+    // scanning the store on every mutation when caching is globally disabled.
+    if (!cacheEnabled()) return payload
+    // Store fresh GET 2xx responses (skip replays and anything with Set-Cookie).
+    if (
+      cacheable &&
+      !(req as any)[HIT] &&
+      (req as any).method === 'GET' &&
+      reply.statusCode >= 200 &&
+      reply.statusCode < 300 &&
+      typeof payload === 'string' &&
+      !tenantMissing(req) &&
+      !reply.getHeader('set-cookie')
+    ) {
+      const headers: Record<string, any> = {}
+      const all = reply.getHeaders()
+      for (const h of Object.keys(all)) if (HEADER_ALLOW.test(h)) headers[h] = all[h]
+      cacheSet(keyFor(req, keyGroup), { payload, headers, statusCode: reply.statusCode }, ttl)
+    }
+    // Invalidate declared key-groups after a successful mutation.
+    if (
+      invalidates?.length &&
+      (req as any).method !== 'GET' &&
+      reply.statusCode >= 200 &&
+      reply.statusCode < 300
+    ) {
+      invalidateCache(invalidates)
+    }
+    return payload
+  }
+
+  return { preHandler, onSend }
+}

package/lib/util/tracker.ts

@@ -88,21 +88,23 @@ function getTrackingConfigIfEnabled(req) {
   }
 }
 
-function isFieldChanged(oldValue, newValue) {
+export function isFieldChanged(oldValue, newValue) {
   if ((oldValue instanceof Date || newValue instanceof Date) && oldValue != null && newValue != undefined) {
     return !dayjs(oldValue).isSame(dayjs(newValue))
   }
 
   if ((oldValue instanceof Object || newValue instanceof Object) && oldValue != null && newValue != undefined) {
     const primaryKey = global.trackingConfig?.primaryKey
+    // Guard the `in` operator with an object check: `'id' in 'someString'` throws
+    // on a string primitive, so reach the string fallback instead of crashing.
     const oldId =
-      oldValue != null && primaryKey in oldValue
+      oldValue != null && typeof oldValue === 'object' && primaryKey in oldValue
         ? oldValue[primaryKey]
         : typeof oldValue === 'string'
         ? oldValue
         : undefined
     const newId =
-      newValue != null && primaryKey in newValue
+      newValue != null && typeof newValue === 'object' && primaryKey in newValue
         ? newValue[primaryKey]
         : typeof newValue === 'string'
         ? newValue

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@volcanicminds/backend",
-  "version": "3.4.0",
+  "version": "3.6.1",
   "type": "module",
   "codename": "rome",
   "license": "MIT",
-  "description": "The volcanic (minds) backend",
+  "description": "Volcanic (minds) backend",
   "keywords": [
     "volcanic",
     "open source",
@@ -58,7 +58,8 @@
     "prod": "cd dist && node server.js",
     "start": "tsx --env-file .env server.ts",
     "dev": "tsx watch --env-file .env server.ts",
-    "test": "npm run test:core && npm run test:typeorm",
+    "pretest": "npm run build",
+    "test": "node scripts/run-tests.mjs",
     "test:core": "cross-env AUTH_RATELIMIT_MAX=100000 PORT=2231 NODE_ENV=memory BROWSER=false JWT_SECRET=tEst0nly_k7Qx2mNp9vLrT4wYbE6sH1jD8fG3aZ5c JWT_REFRESH_SECRET=tEst0nly_R3frsh9vLrT4wYbE6sH1jD8fG3aZ5cK7 mocha --import=tsx ./test/index.spec.ts -t 100000 --exit",
     "test:typeorm": "cross-env NODE_ENV=memory MFA_DB_SECRET=unit-test-secret-please-change-32xyz mocha --import=tsx ./test/typeorm/**/*.spec.ts -t 20000 --exit",
     "test:pglite": "cross-env NODE_ENV=memory MFA_DB_SECRET=unit-test-secret-please-change-32xyz mocha --import=tsx ./test/pglite/**/*.spec.ts -t 60000 --exit",