@volcanicminds/backend 3.6.2 → 4.0.0

package/lib/api/users/routes.ts

@@ -14,7 +14,7 @@ export default {
     {
       method: 'GET',
       path: '/',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.find',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -33,7 +33,7 @@ export default {
     {
       method: 'GET',
       path: '/count',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.count',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -71,7 +71,7 @@ export default {
     {
       method: 'GET',
       path: '/:id',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.findOne',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -89,7 +89,7 @@ export default {
     {
       method: 'PUT',
       path: '/:id',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.update',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -108,7 +108,7 @@ export default {
     {
       method: 'POST',
       path: '/',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.create',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -126,7 +126,7 @@ export default {
     {
       method: 'DELETE',
       path: '/:id',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.remove',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -190,7 +190,7 @@ export default {
     {
       method: 'POST',
       path: '/:id/block',
-      roles: [roles.admin, roles.backoffice],
+      requireCapability: 'users',
       handler: 'user.block',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -206,7 +206,7 @@ export default {
     {
       method: 'POST',
       path: '/:id/unblock',
-      roles: [roles.admin, roles.backoffice],
+      requireCapability: 'users',
       handler: 'user.unblock',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -221,7 +221,7 @@ export default {
     {
       method: 'POST',
       path: '/:id/mfa/reset',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.resetMfaByAdmin',
       middlewares: ['global.isAuthenticated'],
       config: {
@@ -236,7 +236,7 @@ export default {
     {
       method: 'POST',
       path: '/:id/password/reset',
-      roles: [roles.admin],
+      requireCapability: 'users',
       handler: 'user.resetPasswordByAdmin',
       middlewares: ['global.isAuthenticated'],
       config: {

package/lib/config/general.ts

@@ -19,7 +19,7 @@ export default {
       query_key: 'tid'
     },
     manifest: {
-      // opt-in: exposes GET /admin/manifest (admin-only) for the backoffice engine
+      // opt-in: exposes GET /admin/manifest (gated by the `manifest` capability) for the admin console
       enabled: false
     },
     cache: {

package/lib/config/roles.ts

@@ -8,10 +8,5 @@ export default [
     code: 'admin',
     name: 'Admin',
     description: 'Admin role'
-  },
-  {
-    code: 'backoffice',
-    name: 'Backoffice',
-    description: 'Backoffice role'
   }
 ]

package/lib/hooks/onRequest.ts

@@ -150,8 +150,8 @@ export default async (req, reply) => {
       // 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.
+      // `public` (e.g. only a custom consumer role) 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))
 

package/lib/loader/genesis.ts

@@ -0,0 +1,76 @@
+import type { FastifyInstance } from 'fastify'
+import crypto from 'crypto'
+import { includesRole } from '../util/authz.js'
+
+// Random credential for a generated founder. base64url is alphanumeric; the suffix
+// satisfies any upper/lower/digit/symbol policy. Printed once; rotate after first login.
+function generatePassword(): string {
+  return crypto.randomBytes(24).toString('base64url') + 'aA1!'
+}
+
+export interface GenesisOptions {
+  // Called instead of process.exit(1) on the fail-fast path (injected by tests).
+  onFatal?: (message: string) => void
+}
+
+/**
+ * Ensure the instance never boots with zero admins (single-tenant only; multi-tenant
+ * tenant admins come from provisioning and the system founder is seeded out-of-band).
+ * Runs against the default connection (public schema) via the injected userManager.
+ *
+ * - `ADMIN_EMAIL` set → create it (as the sovereign founder) if missing, or promote it
+ *   to admin if it exists without the role; no-op if it is already an admin.
+ * - `ADMIN_EMAIL` unset → allowed only when an admin already exists, otherwise fail-fast.
+ */
+export async function ensureGenesisAdmin(server: FastifyInstance, opts: GenesisOptions = {}): Promise<void> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const um = (server as any)?.['userManager']
+  if (!um?.isImplemented?.()) return
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if (!(global as any).connection) return // no live data layer (e.g. core-only boot)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if ((global as any).config?.options?.multi_tenant?.enabled) return
+
+  const onFatal =
+    opts.onFatal ||
+    ((message: string) => {
+      if (log?.f) log.fatal(message)
+      process.exit(1)
+    })
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const adminCode = (global as any).roles?.admin?.code || 'admin'
+  const email = process.env.ADMIN_EMAIL?.trim()
+
+  if (!email) {
+    const count = Number(await um.countQuery({ 'roles:in': adminCode }))
+    if (count === 0) {
+      onFatal('Startup: no admin exists and ADMIN_EMAIL is not set to bootstrap one. Set ADMIN_EMAIL.')
+    }
+    return
+  }
+
+  const existing = await um.retrieveUserByEmail(email)
+  if (existing) {
+    if (!includesRole(existing.roles, adminCode)) {
+      await um.updateUserById(existing.getId(), { roles: [...(existing.roles || []), adminCode] })
+      if (log?.i) log.info(`Startup: promoted ${email} to admin (sovereign founder).`)
+    }
+    return
+  }
+
+  const envPassword = process.env.ADMIN_PASSWORD
+  const password = envPassword || generatePassword()
+  const created = await um.createUser({ email, username: email, password, roles: [adminCode] })
+  await um.userConfirmation(created)
+  if (!envPassword) {
+    // The generated secret goes to stdout only — never through the structured logger,
+    // which may be shipped, retained, or indexed. Set ADMIN_PASSWORD to avoid disclosure.
+    process.stdout.write(
+      `\n[genesis] Created sovereign founder ${email} with a generated password: ${password}\n[genesis] Rotate it after first login.\n\n`
+    )
+    if (log?.w) log.warn(`Startup: created sovereign founder ${email} with a generated password (printed to stdout).`)
+  } else if (log?.i) {
+    log.info(`Startup: created sovereign founder ${email}.`)
+  }
+}

package/lib/loader/roles.ts

@@ -2,6 +2,39 @@ import type { Role, Roles } from '../../types/global.js'
 import { normalizePatterns } from '../util/path.js'
 import { globSync } from 'glob'
 
+// `admin` and `public` are protected built-ins: a consumer's config/roles.ts may
+// override only their labels (name/description); their `code` and `capabilities`
+// are locked. Every other role code is added/overridden in full. Framework defaults
+// are loaded first, so by the time a consumer's roles are applied the protected
+// codes already exist. See docs/AUTHORIZATION_MODEL.md §2.3.
+export const PROTECTED_ROLE_CODES = ['admin', 'public']
+
+/**
+ * Merge one config file's roles into the accumulator with the protected-merge rule.
+ * Pure (its only effect is on the passed `roles` map) so it is unit-tested directly.
+ */
+export function mergeRoles(roles: Roles, configRoles: Role[]): Roles {
+  const protectedCodes = new Set(PROTECTED_ROLE_CODES)
+
+  for (const role of configRoles || []) {
+    if (!role?.code) continue
+
+    const existing = roles[role.code]
+    if (existing && protectedCodes.has(role.code)) {
+      // Protected built-in: only labels are overridable; code + capabilities locked.
+      if (typeof role.name === 'string') existing.name = role.name
+      if (typeof role.description === 'string') existing.description = role.description
+      if (role.capabilities?.length && log?.w) {
+        log.warn(`Roles: capabilities on protected role '${role.code}' are ignored`)
+      }
+    } else {
+      roles[role.code] = role
+    }
+  }
+
+  return roles
+}
+
 export async function load() {
   const roles: Roles = {}
 
@@ -13,11 +46,7 @@ export async function load() {
 
     for (const f of files) {
       const module = await import(f)
-      const configRoles = module.default || module
-
-      configRoles.forEach((role: Role) => {
-        roles[role.code] = role
-      })
+      mergeRoles(roles, (module.default || module) as Role[])
     }
   }
 

package/lib/loader/router.ts

@@ -66,6 +66,52 @@ async function loadMiddlewares(base: string, middlewares: string[] = []) {
 }
 
 
+// Resolve a route's declared roles (Role objects or string codes) plus its optional
+// capability into the final allowed-role set. Object refs are trusted; string codes and
+// undefined entries that don't resolve against the `roles` catalog are collected in
+// `roleErrors` for the fail-fast at load. admin is always appended (universal superuser);
+// a route with neither roles nor a capability defaults to public.
+function resolveRequiredRoles(
+  rs: (Role | string)[],
+  capability: string | undefined,
+  where: string,
+  roleErrors: string[]
+): Role[] {
+  const declared: Role[] = []
+  for (const ref of rs) {
+    if (ref == null) {
+      roleErrors.push(`${where} → references an undefined role`)
+    } else if (typeof ref === 'string') {
+      const resolved = roles[ref]
+      if (resolved) declared.push(resolved)
+      else roleErrors.push(`${where} → unknown role '${ref}' (not declared in config/roles.ts)`)
+    } else if (ref.code) {
+      declared.push(ref)
+    } else {
+      roleErrors.push(`${where} → a declared role has no code`)
+    }
+  }
+
+  const capRoles: Role[] = capability
+    ? Object.values(roles).filter((r) => Array.isArray(r.capabilities) && r.capabilities.includes(capability))
+    : []
+  if (capability && capRoles.length === 0 && log?.w) {
+    log.warn(`Route ${where} requires capability '${capability}' held by no role — admin-only`)
+  }
+
+  const seen = new Set<string>()
+  const out: Role[] = []
+  for (const r of [...declared, ...capRoles]) {
+    if (r?.code && !seen.has(r.code)) {
+      seen.add(r.code)
+      out.push(r)
+    }
+  }
+  if (out.length === 0 && !capability) out.push(roles.public)
+  if (!out.some((r) => r.code === roles.admin.code)) out.push(roles.admin)
+  return out
+}
+
 export function processRoute(
   route: Route,
   index: number,
@@ -74,7 +120,8 @@ export function processRoute(
   base: string,
   defaultConfig: any,
   authMiddlewares: string[],
-  validRoutes: ConfiguredRoute[]
+  validRoutes: ConfiguredRoute[],
+  roleErrors: string[] = []
 ): ConfiguredRoute | null {
   const errors: string[] = []
   const {
@@ -82,25 +129,19 @@ export function processRoute(
     path: pathName = '/',
     handler,
     roles: rs = [],
+    requireCapability,
     config = {} as RouteConfig,
     middlewares = [],
     rateLimit,
     cache: cacheInput
   } = route
 
-  const rsp = !rs.length ? [roles.public] : rs
-  let requiredRoles: Role[] = []
-
-  try {
-    // `admin` is a global superuser: it is appended to EVERY route's allowed roles,
-    // so an admin can access any endpoint (even ones restricted to e.g. backoffice).
-    // This is intentional. Remove this append if admin should NOT be a universal role.
-    requiredRoles = rsp.some((r) => r.code === roles.admin.code) ? rsp : [...rsp, roles.admin]
-  } catch (err) {
-    if (log.e) log.error(`Error in loading roles for ${methodCase} ${pathName} (${handler})`)
-    if (log.t) log.trace(err)
-    config.enable = false
-  }
+  const requiredRoles = resolveRequiredRoles(
+    rs,
+    requireCapability,
+    `${methodCase} ${pathName} (${handler})`,
+    roleErrors
+  )
 
   const reqAuth: boolean =
     middlewares.some((m) => authMiddlewares.includes(m)) ||
@@ -207,6 +248,7 @@ export function processRoute(
 
 async function load(): Promise<ConfiguredRoute[]> {
   const validRoutes: ConfiguredRoute[] = []
+  const roleErrors: string[] = []
   const patterns = normalizePatterns(['..', 'api', '**', 'routes.{ts,js}'], ['src', 'api', '**', 'routes.{ts,js}'])
   const authMiddlewares = ['global.isAuthenticated', 'global.isAdmin']
 
@@ -228,7 +270,17 @@ async function load(): Promise<ConfiguredRoute[]> {
       if (log.t) log.trace(`* Add ${routes.length} routes from ${file}`)
 
       routes.forEach((route: Route, index: number) => {
-        const configuredRoute = processRoute(route, index, file, dir, base, defaultConfig, authMiddlewares, validRoutes)
+        const configuredRoute = processRoute(
+          route,
+          index,
+          file,
+          dir,
+          base,
+          defaultConfig,
+          authMiddlewares,
+          validRoutes,
+          roleErrors
+        )
         if (configuredRoute) {
           validRoutes.push(configuredRoute)
         }
@@ -236,6 +288,14 @@ async function load(): Promise<ConfiguredRoute[]> {
     }
   }
 
+  if (roleErrors.length) {
+    const message = `Route/role integrity check failed — every route role must be declared in config/roles.ts:\n  - ${roleErrors.join(
+      '\n  - '
+    )}`
+    if (log?.f) log.fatal(message)
+    throw new Error(message)
+  }
+
   return validRoutes
 }
 

package/lib/util/authz.ts

@@ -0,0 +1,26 @@
+// Helpers for the admin-apex guards in the users and token controllers. Pure, so they
+// unit-test without a request context. Role values may arrive as string codes
+// (`['admin']`) or as `{ code }` objects; both are normalized here.
+
+/** De-duped list of role codes from a roles value (accepts strings or `{ code }`). */
+export function roleCodes(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  const codes = value
+    .map((r) => (typeof r === 'string' ? r : (r as { code?: string } | null)?.code))
+    .filter((c): c is string => !!c)
+  return [...new Set(codes)]
+}
+
+/** Whether a roles value grants the given role code. */
+export function includesRole(value: unknown, code: string): boolean {
+  return roleCodes(value).includes(code)
+}
+
+/**
+ * Whether an email identifies the sovereign founder (env `ADMIN_EMAIL`, case-insensitive).
+ * Returns false when `ADMIN_EMAIL` is unset, so founder guards stay inert without it.
+ */
+export function isFounderEmail(email: unknown): boolean {
+  const founder = process.env.ADMIN_EMAIL?.trim().toLowerCase()
+  return !!founder && typeof email === 'string' && email.trim().toLowerCase() === founder
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanicminds/backend",
-  "version": "3.6.2",
+  "version": "4.0.0",
   "type": "module",
   "codename": "rome",
   "license": "MIT",