fusion-framework 1.2.6 → 2.0.0

package/index.js

@@ -1,5 +1,6 @@
 const path = require('path')
 const fs = require('fs')
+const { spawn } = require('child_process')
 const { platform, arch } = process
 
 function napiTriple() {
@@ -134,7 +135,7 @@ header.fingerprint = () =>
     : {
         'X-Powered-By': 'Fusion Framework',
         'X-Framework': 'Fusion',
-        ['X-Fusion-Version']: '1.2.6',
+        ['X-Fusion-Version']: '2.0.0',
       }
 
 function isThenable(value) {
@@ -168,6 +169,221 @@ function frameworkHeaders() {
   }
 }
 
+function getHeader(request, name) {
+  const headers = request.headers || {}
+  const target = String(name).toLowerCase()
+  for (const [key, value] of Object.entries(headers)) {
+    if (String(key).toLowerCase() === target) return String(value)
+  }
+  return null
+}
+
+function headerMiddleware(extra) {
+  return async (request, callNext) => {
+    const result = await awaitMaybe(callNext(request))
+    return mergeResponseHeaders(result, extra)
+  }
+}
+
+function securityHeaders(options = {}) {
+  const extra = {
+    'X-Content-Type-Options': options.contentTypeOptions ?? 'nosniff',
+    'X-Frame-Options': options.frameOptions ?? 'DENY',
+    'Referrer-Policy': options.referrerPolicy ?? 'strict-origin-when-cross-origin',
+    'Permissions-Policy':
+      options.permissionsPolicy ?? 'camera=(), microphone=(), geolocation=(), payment=()',
+    'Cross-Origin-Opener-Policy': options.coop ?? 'same-origin',
+    'Cross-Origin-Resource-Policy': options.corp ?? 'same-origin',
+  }
+  if (options.csp) extra['Content-Security-Policy'] = String(options.csp)
+  if (options.hsts) extra['Strict-Transport-Security'] = String(options.hsts)
+  return headerMiddleware(extra)
+}
+
+function cacheHeaders(options = {}) {
+  return headerMiddleware({
+    'Cache-Control': options.default ?? options.value ?? 'no-store',
+  })
+}
+
+function requestId(options = {}) {
+  const headerName = options.header ?? 'X-Request-Id'
+  const incoming = options.incoming !== false
+  return async (request, callNext) => {
+    const state = ensureState(request)
+    let rid = incoming ? getHeader(request, headerName) : null
+    if (!rid) {
+      rid =
+        typeof crypto !== 'undefined' && crypto.randomUUID
+          ? crypto.randomUUID()
+          : `${Date.now()}-${Math.random().toString(16).slice(2)}`
+    }
+    state.request_id = rid
+    const result = await awaitMaybe(callNext(request))
+    return mergeResponseHeaders(result, { [headerName]: rid })
+  }
+}
+
+function cors(options = {}) {
+  const origins = Array.isArray(options.allowOrigins)
+    ? options.allowOrigins.map(String)
+    : [String(options.allowOrigins ?? '*')]
+  const methods = (
+    options.allowMethods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
+  ).map((m) => String(m).toUpperCase())
+  const allowHeaders = (
+    options.allowHeaders ?? ['Authorization', 'Content-Type', 'Accept', 'Origin', 'X-Request-Id']
+  ).map(String)
+  const exposeHeaders = (options.exposeHeaders ?? ['X-Request-Id']).map(String)
+  const allowCredentials = !!options.allowCredentials
+  const maxAge = Number(options.maxAge ?? 600)
+  const allowAll = origins.includes('*')
+
+  function corsHeaders(origin) {
+    let chosen = '*'
+    if (!allowAll) {
+      if (origin && origins.includes(origin)) chosen = origin
+      else if (origins.length) chosen = origins[0]
+    }
+    const out = {
+      'Access-Control-Allow-Origin': chosen,
+      'Access-Control-Allow-Methods': methods.join(', '),
+      'Access-Control-Allow-Headers': allowHeaders.join(', '),
+      'Access-Control-Expose-Headers': exposeHeaders.join(', '),
+      'Access-Control-Max-Age': String(maxAge),
+      Vary: 'Origin',
+    }
+    if (allowCredentials && chosen !== '*') out['Access-Control-Allow-Credentials'] = 'true'
+    return out
+  }
+
+  return async (request, callNext) => {
+    const origin = getHeader(request, 'Origin')
+    const extra = corsHeaders(origin)
+    if (String(request.method || 'GET').toUpperCase() === 'OPTIONS') {
+      return { status: 204, body: '', headers: extra }
+    }
+    const result = await awaitMaybe(callNext(request))
+    return mergeResponseHeaders(result, extra)
+  }
+}
+
+const STATIC_MIME_TYPES = {
+  '.css': 'text/css; charset=utf-8',
+  '.gif': 'image/gif',
+  '.htm': 'text/html; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.map': 'application/json',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+}
+
+/** Guess Content-Type from a file path extension. */
+function guessStaticContentType(filePath) {
+  const ext = path.extname(String(filePath)).toLowerCase()
+  return STATIC_MIME_TYPES[ext] || 'application/octet-stream'
+}
+
+/**
+ * Serve files from `root` for URLs under `prefix` (WhiteNoise-style).
+ *
+ * - root: folder on disk (e.g. 'static')
+ * - prefix: URL prefix (e.g. '/static' → static/logo.png at /static/logo.png)
+ *
+ * Files are also mounted as real GET/HEAD routes on FusionApp.mount()/listen().
+ */
+function staticFiles(options = {}) {
+  const rootDir = path.resolve(String(options.root ?? 'static'))
+  const rawPrefix = String(options.prefix ?? '/static').trim()
+  const normalized = rawPrefix.replace(/\/+$/, '') === '' ? '/' : `/${rawPrefix.replace(/^\/+|\/+$/g, '')}`
+  const maxAge = options.maxAge === undefined ? 3600 : options.maxAge
+  const allowFallthrough =
+    options.fallthrough === undefined ? normalized === '/' : !!options.fallthrough
+  const cfg = { root: rootDir, prefix: normalized, maxAge, fallthrough: allowFallthrough }
+
+  const middleware = (request, callNext) => serveStaticOrNext(cfg, request, callNext)
+  middleware.__fusionStatic = cfg
+  return middleware
+}
+
+/** Build a 200 file response envelope. */
+function staticFileResponse(filePath, method, maxAge) {
+  const size = fs.statSync(filePath).size
+  const headers = {
+    'content-type': guessStaticContentType(filePath),
+    'content-length': String(size),
+  }
+  if (maxAge !== null && maxAge !== undefined) {
+    headers['cache-control'] = `public, max-age=${Number(maxAge)}`
+  }
+  const body = String(method).toUpperCase() === 'HEAD' ? Buffer.alloc(0) : fs.readFileSync(filePath)
+  return { status: 200, body, headers }
+}
+
+/** Try to serve a static file; otherwise callNext. */
+function serveStaticOrNext(cfg, request, callNext) {
+  const method = String(request.method || 'GET').toUpperCase()
+  if (method !== 'GET' && method !== 'HEAD') return callNext(request)
+
+  const reqPath = String(request.path || '/')
+  const normalized = cfg.prefix
+  let relative = ''
+  if (normalized === '/') {
+    relative = reqPath.replace(/^\/+/, '')
+    if (!relative || relative.endsWith('/')) return callNext(request)
+  } else {
+    if (!(reqPath === normalized || reqPath.startsWith(`${normalized}/`))) {
+      return callNext(request)
+    }
+    relative = reqPath.slice(normalized.length).replace(/^\/+/, '')
+    if (!relative) return callNext(request)
+  }
+
+  const candidate = path.resolve(cfg.root, relative)
+  const relToRoot = path.relative(cfg.root, candidate)
+  if (relToRoot.startsWith('..') || path.isAbsolute(relToRoot)) {
+    return { status: 403, body: { detail: 'Forbidden' } }
+  }
+  if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+    if (cfg.fallthrough) return callNext(request)
+    return { status: 404, body: { detail: 'Not found' } }
+  }
+  return staticFileResponse(candidate, method, cfg.maxAge)
+}
+
+/** Register GET/HEAD routes for files under each staticFiles() mount. */
+function mountStaticFiles(engine, middlewares) {
+  for (const mw of middlewares || []) {
+    const cfg = mw && mw.__fusionStatic
+    if (!cfg || !fs.existsSync(cfg.root) || !fs.statSync(cfg.root).isDirectory()) continue
+    const walk = (dir) => {
+      for (const name of fs.readdirSync(dir)) {
+        const full = path.join(dir, name)
+        const st = fs.statSync(full)
+        if (st.isDirectory()) {
+          walk(full)
+          continue
+        }
+        if (!st.isFile()) continue
+        const rel = path.relative(cfg.root, full).split(path.sep).join('/')
+        const url = cfg.prefix === '/' ? `/${rel}` : `${cfg.prefix}/${rel}`
+        engine.route('GET', url, () => staticFileResponse(full, 'GET', cfg.maxAge))
+        engine.route('HEAD', url, () => staticFileResponse(full, 'HEAD', cfg.maxAge))
+      }
+    }
+    walk(cfg.root)
+  }
+}
+
 class FusionBaseApi {
   constructor(request) {
     this.request = request && typeof request === 'object' ? request : emptyRequest()
@@ -228,6 +444,213 @@ class FusionBaseApi {
     const body = paginatedBody(items, total, p)
     return this.response(body, status, headers || {})
   }
+
+  wantsJson() {
+    let accept = null
+    for (const [key, value] of Object.entries(this.headers || {})) {
+      if (key.toLowerCase() === 'accept') {
+        accept = String(value)
+        break
+      }
+    }
+    const format = this.query?.format != null ? String(this.query.format) : null
+    return typeof native.prefersJsonJs === 'function'
+      ? native.prefersJsonJs(accept, format)
+      : prefersJsonFallback(accept, format)
+  }
+}
+
+function prefersJsonFallback(accept, formatQuery) {
+  if (formatQuery && String(formatQuery).toLowerCase() === 'json') return true
+  const value = String(accept || '').trim().toLowerCase()
+  if (!value) return false
+  let bestJson = -1
+  let bestHtml = -1
+  for (const part of value.split(',')) {
+    const tokens = part.trim().split(';').map((t) => t.trim())
+    const media = tokens[0] || ''
+    let q = 1
+    for (const token of tokens.slice(1)) {
+      if (token.startsWith('q=')) {
+        const parsed = Number.parseFloat(token.slice(2))
+        if (!Number.isNaN(parsed)) q = parsed
+      }
+    }
+    if (media === 'application/json' || media === 'text/json') bestJson = Math.max(bestJson, q)
+    else if (media === 'text/html' || media === 'application/xhtml+xml') bestHtml = Math.max(bestHtml, q)
+  }
+  return bestJson > 0 && bestJson >= bestHtml
+}
+
+function parseFormBody(body, contentType) {
+  const raw = body == null ? '' : String(body)
+  const ct = String(contentType || '').toLowerCase()
+  if (ct.includes('application/json') || (raw.trim().startsWith('{') && !ct.includes('urlencoded'))) {
+    try {
+      const data = raw.trim() ? JSON.parse(raw) : {}
+      if (data && typeof data === 'object' && !Array.isArray(data)) {
+        const out = {}
+        for (const [k, v] of Object.entries(data)) out[k] = v == null ? '' : String(v)
+        return out
+      }
+    } catch {
+      return {}
+    }
+    return {}
+  }
+  const params = new URLSearchParams(raw)
+  const out = {}
+  for (const key of params.keys()) {
+    out[key] = params.get(key) ?? ''
+  }
+  return out
+}
+
+class FusionBaseTemplate extends FusionBaseApi {
+  static __fusion_template__ = true
+  static template = ''
+  static templateAddress = ''
+  static templatesDir = ''
+
+  /**
+   * Template variables (not an HTTP verb). May return a Promise.
+   * get() renders this as HTML; post() should use form / ok / fail.
+   */
+  context() {
+    return {}
+  }
+
+  /** Parsed POST body (urlencoded or JSON) as flat string fields. */
+  get form() {
+    let contentType = null
+    for (const [key, value] of Object.entries(this.headers || {})) {
+      if (String(key).toLowerCase() === 'content-type') {
+        contentType = String(value)
+        break
+      }
+    }
+    return parseFormBody(this.body, contentType)
+  }
+
+  get() {
+    const raw = this.context()
+    if (raw && typeof raw.then === 'function') {
+      return this._getAsync(raw)
+    }
+    return this._finishGet(raw)
+  }
+
+  async _getAsync(raw) {
+    const ctx = await raw
+    return this._finishGet(ctx)
+  }
+
+  _finishGet(ctx) {
+    const data = { ...(ctx || {}) }
+    if (this.wantsJson()) return data
+    return this._htmlResponse(data)
+  }
+
+  /**
+   * Validation failure — JSON for SPA fetch, else same template with errors.
+   * fail({ phone: 'required' }, { message: 'خطا', ...formFields })
+   */
+  fail(errors = {}, extras = {}) {
+    const bag = typeof extras === 'string' ? { message: extras } : { ...(extras || {}) }
+    const message = bag.message != null ? String(bag.message) : 'Validation failed'
+    delete bag.message
+    const err = {}
+    for (const [k, v] of Object.entries(errors || {})) err[k] = String(v)
+    const flat = {}
+    for (const [k, v] of Object.entries(bag)) flat[k] = v == null ? '' : String(v)
+
+    if (this.wantsJson()) {
+      return this.response({ ok: false, message, errors: err, fields: flat }, 400)
+    }
+    return this._formHtmlResult({ ok: false, message, errors: err, fields: flat, status: 400 })
+  }
+
+  /** Success — JSON for SPA fetch, else same template with ok=true. */
+  ok(extras = {}) {
+    const bag = typeof extras === 'string' ? { message: extras } : { ...(extras || {}) }
+    const message = bag.message != null ? String(bag.message) : 'OK'
+    delete bag.message
+    const flat = {}
+    for (const [k, v] of Object.entries(bag)) flat[k] = v == null ? '' : String(v)
+
+    if (this.wantsJson()) {
+      return this.response({ ok: true, message, errors: {}, fields: flat }, 200)
+    }
+    return this._formHtmlResult({ ok: true, message, errors: {}, fields: flat, status: 200 })
+  }
+
+  _formHtmlResult({ ok, message, errors, fields, status }) {
+    const raw = this.context()
+    if (raw && typeof raw.then === 'function') {
+      return this._formHtmlResultAsync(raw, { ok, message, errors, fields, status })
+    }
+    return this._finishFormHtml(raw, { ok, message, errors, fields, status })
+  }
+
+  async _formHtmlResultAsync(raw, opts) {
+    const ctx = await raw
+    return this._finishFormHtml(ctx, opts)
+  }
+
+  _finishFormHtml(ctx, { ok, message, errors, fields, status }) {
+    const data = { ...(ctx || {}), ...fields, ok, message, errors: { ...errors }, fields: { ...fields } }
+    return this._htmlResponse(data, { status })
+  }
+
+  templateName() {
+    const name = this.constructor.template || this.constructor.templateAddress
+    if (!name) {
+      throw new Error(`${this.constructor.name} must set static template or templateAddress`)
+    }
+    return name
+  }
+
+  templatesRoot() {
+    if (this.constructor.templatesDir) return this.constructor.templatesDir
+    return String(settings.get('templates.dir', 'templates'))
+  }
+
+  render({
+    status = 200,
+    headers = {},
+    context = null,
+    templateName = null,
+  } = {}) {
+    const raw = this.context()
+    if (raw && typeof raw.then === 'function') {
+      return this._renderAsync(raw, { status, headers, context, templateName })
+    }
+    const ctx = { ...(raw || {}), ...(context || {}) }
+    return this._htmlResponse(ctx, { status, headers, templateName })
+  }
+
+  async _renderAsync(raw, { status = 200, headers = {}, context = null, templateName = null } = {}) {
+    const base = await raw
+    const ctx = { ...(base || {}), ...(context || {}) }
+    return this._htmlResponse(ctx, { status, headers, templateName })
+  }
+
+  _htmlResponse(ctx, { status = 200, headers = {}, templateName = null } = {}) {
+    const html = renderTemplate(
+      templateName || this.templateName(),
+      ctx,
+      this.templatesRoot(),
+    )
+    return this.response(html, status, {
+      'content-type': 'text/html; charset=utf-8',
+      ...headers,
+    })
+  }
+}
+
+function renderTemplate(templateName, context = {}, templatesRoot = null) {
+  const root = templatesRoot ?? String(settings.get('templates.dir', 'templates'))
+  return native.renderTemplateJs(templateName, context || {}, root)
 }
 
 function apiResourceName(cls) {
@@ -421,6 +844,17 @@ async function runMiddlewareChain(request, middlewares, handler) {
   return dispatch(0, request)
 }
 
+function requirePermissions(...checks) {
+  return (request, callNext) => {
+    for (const check of checks) {
+      if (!check(request)) {
+        return { status: 403, body: { detail: 'Forbidden' } }
+      }
+    }
+    return callNext(request)
+  }
+}
+
 function requireRoles(...rolesOrOptions) {
   let roles = rolesOrOptions
   let claim = 'roles'
@@ -504,14 +938,9 @@ function router(routePath, options = {}) {
     ApiClass.__fusion_path_template__ = routePath
 
     const routeMiddleware = Array.isArray(options.middleware) ? [...options.middleware] : []
-    if (Array.isArray(options.roles) && options.roles.length) {
-      routeMiddleware.push(
-        requireRoles({
-          roles: options.roles,
-          claim: options.roleClaim || 'roles',
-          stateKey: options.roleStateKey || 'jwt',
-        }),
-      )
+    const permissionChecks = Array.isArray(options.permissions) ? options.permissions : []
+    if (permissionChecks.length) {
+      routeMiddleware.push(requirePermissions(...permissionChecks))
     }
 
     const classSwagger = {
@@ -528,6 +957,7 @@ function router(routePath, options = {}) {
       middleware: routeMiddleware,
       swagger: classSwagger,
       version_prefix: v,
+      requiresPermissions: permissionChecks.length > 0,
       slots: collectRouteSlots(ApiClass, resolved, classSwagger),
     })
     return ApiClass
@@ -653,7 +1083,7 @@ function readSwaggerSettings() {
     showCommonExtensions: false,
     syntaxHighlight: { activated: true, theme: 'agate' },
     withCredentials: false,
-    validatorUrl: 'https://validator.swagger.io/validator',
+    validatorUrl: null,
     ...asObject(settings.get('swagger.ui', {})),
   }
   if (Object.prototype.hasOwnProperty.call(authRaw, 'persistAuthorization')) {
@@ -682,6 +1112,102 @@ function readSwaggerSettings() {
 
 const UNVERSIONED_SWAGGER_NAME = 'default'
 
+const SWAGGER_ASSETS_DIR = path.join(__dirname, 'static', 'swagger-ui')
+const SWAGGER_ASSET_TYPES = {
+  'swagger-ui-bundle.js': 'application/javascript; charset=utf-8',
+  'swagger-ui-standalone-preset.js': 'application/javascript; charset=utf-8',
+  'swagger-ui.css': 'text/css; charset=utf-8',
+}
+
+function loadSwaggerAssets() {
+  const out = {}
+  for (const [name, contentType] of Object.entries(SWAGGER_ASSET_TYPES)) {
+    const filePath = path.join(SWAGGER_ASSETS_DIR, name)
+    if (!fs.existsSync(filePath)) continue
+    out[name] = { contentType, body: fs.readFileSync(filePath, 'utf8') }
+  }
+  return out
+}
+
+const SWAGGER_ASSETS = loadSwaggerAssets()
+
+function swaggerAssetUrl(prefix, name) {
+  return `${prefix}/assets/${name}`
+}
+
+
+/** Normalize monitor.path from settings (default /__fusion/monitor). */
+function normalizeMonitorPath(raw) {
+  let path = String(raw == null || raw === '' ? '/__fusion/monitor' : raw).trim() || '/__fusion/monitor'
+  if (!path.startsWith('/')) path = `/${path}`
+  return path.replace(/\/+$/, '') || '/__fusion/monitor'
+}
+
+function resolveMonitorEnabled(settingsInstance) {
+  const s = settingsInstance || settings
+  const top = s.get('monitor.enabled', null)
+  if (top !== null && top !== undefined) {
+    return truthyEnabled(top, false)
+  }
+  return truthyEnabled(s.get('cache.monitor.enabled', false), false)
+}
+
+function resolveMonitorPath(settingsInstance) {
+  const s = settingsInstance || settings
+  const top = s.get('monitor.path', null)
+  if (top !== null && top !== undefined && String(top).trim() !== '') {
+    return normalizeMonitorPath(top)
+  }
+  return normalizeMonitorPath(s.get('cache.monitor.path', '/__fusion/monitor'))
+}
+
+/**
+ * Built-in Fusion monitor (cache + background tasks).
+ * When monitor.enabled is false, no routes are registered.
+ */
+function mountMonitor(engine, settingsInstance) {
+  const s = settingsInstance || settings
+  if (!resolveMonitorEnabled(s)) {
+    return false
+  }
+  cache.configure(s)
+  const path = resolveMonitorPath(s)
+
+  class MonitorPanel extends FusionBaseTemplate {
+    static template = 'fusion/monitor.html'
+    context() {
+      return cache.panelContext()
+    }
+  }
+
+  const htmlHandler = (errOrRequest, maybeRequest) => {
+    const request = nativeRequestArg(errOrRequest, maybeRequest)
+    return new MonitorPanel(request || emptyRequest()).get()
+  }
+  const jsonHandler = () => cache.snapshot()
+
+  engine.route('GET', path, htmlHandler)
+  if (path !== '/') {
+    engine.route('GET', `${path}/`, htmlHandler)
+  }
+  engine.route('GET', `${path}/json`, jsonHandler)
+  return true
+}
+
+/** @deprecated Use mountMonitor */
+const mountCacheMonitor = mountMonitor
+
+function mountSwaggerAssets(engine, prefix) {
+  const assetsPrefix = `${prefix}/assets`
+  for (const [name, { contentType, body }] of Object.entries(SWAGGER_ASSETS)) {
+    engine.route('GET', `${assetsPrefix}/${name}`, () => ({
+      status: 200,
+      body,
+      headers: { 'content-type': contentType },
+    }))
+  }
+}
+
 function normalizeVersionLabel(value) {
   return String(value || '')
     .trim()
@@ -702,6 +1228,40 @@ function collectRouteVersions() {
   return { versions, hasUnversioned }
 }
 
+function clearRouteRegistry() {
+  registry.length = 0
+}
+
+function testSwaggerConfig() {
+  return {
+    path: '/swagger',
+    info: { title: 'fusion-framework', version: '1.0.0' },
+    servers: [],
+    auth: { schemes: {}, global: [], oauth: {} },
+    navbar: {
+      enabled: true,
+      showUrlInput: false,
+      showUrlInputSet: true,
+      urlsSet: false,
+      urls: [],
+    },
+    ui: {},
+    pageTitle: 'Fusion API Docs',
+  }
+}
+
+function openapiSpec(version = null) {
+  return buildOpenApi(testSwaggerConfig(), version)
+}
+
+function routeVersions() {
+  return collectRouteVersions().versions
+}
+
+function hasUnversionedRoutes() {
+  return collectRouteVersions().hasUnversioned
+}
+
 function swaggerVersionUrls(prefix) {
   const { versions, hasUnversioned } = collectRouteVersions()
   const urls = versions.map((label) => ({
@@ -748,6 +1308,17 @@ function applySwaggerOpenApi(openapi, swagger) {
   return openapi
 }
 
+const OPENAPI_PERMISSIONS_SCHEME = 'FusionPermissions'
+
+function isTemplateClass(ApiClass) {
+  let current = ApiClass
+  while (current && current !== Function.prototype) {
+    if (current === FusionBaseTemplate || current.__fusion_template__) return true
+    current = Object.getPrototypeOf(current)
+  }
+  return false
+}
+
 function fillOpenApiPaths(openapi, versionFilter = null) {
   const parsePathParams = (pattern) => {
     return String(pattern)
@@ -756,9 +1327,13 @@ function fillOpenApiPaths(openapi, versionFilter = null) {
       .map((seg) => seg.slice(1, -1))
   }
 
+  let anyPermissions = false
+
   for (const item of registry) {
     if (!routeMatchesVersion(item, versionFilter)) continue
-    const { ApiClass, swagger: routeSwagger } = item
+    const { ApiClass, swagger: routeSwagger, requiresPermissions } = item
+    if (isTemplateClass(ApiClass)) continue
+    if (requiresPermissions) anyPermissions = true
     const slots = item.slots || []
 
     for (const slot of slots) {
@@ -784,10 +1359,27 @@ function fillOpenApiPaths(openapi, versionFilter = null) {
         deprecated: !!routeSwaggerEntry?.deprecated,
         operationId: `${ApiClass.name}_${slot.handlerMethod}`,
         parameters: params,
-        responses: { 200: { description: 'OK' } },
+        responses: {
+          200: { description: 'OK' },
+          ...(requiresPermissions ? { 403: { description: 'Forbidden — permission check failed' } } : {}),
+        },
+        ...(requiresPermissions ? { security: [{ [OPENAPI_PERMISSIONS_SCHEME]: [] }] } : {}),
       }
     }
   }
+
+  if (anyPermissions) {
+    openapi.components = asObject(openapi.components)
+    openapi.components.securitySchemes = {
+      ...asObject(openapi.components.securitySchemes),
+      [OPENAPI_PERMISSIONS_SCHEME]: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'Authorization',
+        description: 'Route requires custom permission checks to pass',
+      },
+    }
+  }
   return openapi
 }
 
@@ -835,6 +1427,8 @@ function swaggerUiHtml(swagger, openapiUrl, primaryName = null) {
 
   const navbarEnabled = !!swagger.navbar?.enabled
   const showUrlInput = swagger.navbar?.showUrlInput !== false
+  const versionUrls = swagger.navbar?.urls?.length > 0
+  const needsStandalone = navbarEnabled || versionUrls
   const hideUrlCss =
     navbarEnabled && !showUrlInput
       ? `<style>
@@ -844,9 +1438,10 @@ function swaggerUiHtml(swagger, openapiUrl, primaryName = null) {
       }
     </style>`
       : ''
-  const standaloneScript = navbarEnabled
-    ? `<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>`
-    : ''
+  const standaloneScript =
+    needsStandalone && SWAGGER_ASSETS['swagger-ui-standalone-preset.js']
+      ? `<script src="${swaggerAssetUrl(swagger.path, 'swagger-ui-standalone-preset.js')}"></script>`
+      : ''
 
   return `<!doctype html>
 <html>
@@ -854,19 +1449,19 @@ function swaggerUiHtml(swagger, openapiUrl, primaryName = null) {
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>${title}</title>
-    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
+    <link rel="stylesheet" href="${swaggerAssetUrl(swagger.path, 'swagger-ui.css')}" />
     ${hideUrlCss}
   </head>
   <body>
     <div id="swagger-ui"></div>
-    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
+    <script src="${swaggerAssetUrl(swagger.path, 'swagger-ui-bundle.js')}"></script>
     ${standaloneScript}
     <script>
       window.onload = function() {
         var opts = ${uiJson};
         opts.presets = [SwaggerUIBundle.presets.apis];
         opts.plugins = [SwaggerUIBundle.plugins.DownloadUrl];
-        if (${navbarEnabled ? 'true' : 'false'} && typeof SwaggerUIStandalonePreset !== 'undefined') {
+        if (${needsStandalone ? 'true' : 'false'} && typeof SwaggerUIStandalonePreset !== 'undefined') {
           opts.presets.push(SwaggerUIStandalonePreset);
           opts.layout = 'StandaloneLayout';
         } else {
@@ -890,8 +1485,7 @@ class FusionApp {
     this.settings = getSettings()
     this.engine = new NativeApp()
     this.mounted = false
-    // Default: advertise Fusion to clients / Wappalyzer-style detectors.
-    this._middleware = [frameworkHeaders()]
+    this._middleware = []
   }
 
   use(middleware) {
@@ -923,9 +1517,12 @@ class FusionApp {
       }
     }
 
+    mountStaticFiles(this.engine, this._middleware)
+
     const swagger = readSwaggerSettings()
     if (swagger.enabled) {
       const prefix = swagger.path
+      mountSwaggerAssets(this.engine, prefix)
       const labels = applyVersionNavbar(swagger)
       const combined = buildOpenApi(swagger)
 
@@ -949,21 +1546,210 @@ class FusionApp {
       }
     }
 
+    mountMonitor(this.engine, settings)
+
     this.mounted = true
   }
 
-  async listen(host, port) {
-    this.mount()
+  async listen(host, port, options = {}) {
+    const reloadOpt =
+      options && Object.prototype.hasOwnProperty.call(options, 'reload')
+        ? options.reload
+        : host && typeof host === 'object'
+          ? host.reload
+          : undefined
+    // Support listen({ host, port, reload }) as well as listen(host, port, { reload })
+    let h = host
+    let p = port
+    let reloadArg = reloadOpt
+    let watchDirs = options?.watchDirs
+    if (host && typeof host === 'object' && !Array.isArray(host)) {
+      h = host.host
+      p = host.port
+      reloadArg = host.reload
+      watchDirs = host.watchDirs
+    }
+
     const snapshot = getSettings()
-    const h = host ?? snapshot.host
-    const p = port ?? snapshot.port
-    if (snapshot.debug) {
-      console.log(`fusion listening on http://${h}:${p}`)
+    // getSettings() returns a plain {host,port,debug,env}; reload lives on the Settings handle.
+    const settingsReload = Boolean(
+      typeof snapshot.get === 'function'
+        ? snapshot.get('reload', false)
+        : settings.get('reload', false),
+    )
+    const shouldReload =
+      reloadArg === undefined || reloadArg === null ? settingsReload : Boolean(reloadArg)
+
+    if (shouldReload && process.env.FUSION_RELOAD_CHILD !== '1') {
+      await runWithReloader({ watchDirs })
+      return
+    }
+
+    this.mount()
+    h = h ?? snapshot.host
+    p = p ?? snapshot.port
+    if (snapshot.debug || shouldReload) {
+      const mode = shouldReload ? ' (reload)' : ''
+      console.log(`fusion listening on http://${h}:${p}${mode}`)
     }
     await this.engine.listen(h, Number(p))
   }
 }
 
+const RELOAD_SKIP_DIRS = new Set([
+  '.git',
+  '.hg',
+  'node_modules',
+  'target',
+  '.venv',
+  'venv',
+  '__pycache__',
+  'bin',
+  'obj',
+  'dist',
+  'build',
+])
+
+const RELOAD_EXTENSIONS = new Set([
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.json',
+  '.html',
+  '.tera',
+  '.py',
+  '.cs',
+])
+
+function collectWatchedFiles(roots) {
+  const files = []
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && entry.name !== '.') continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (RELOAD_SKIP_DIRS.has(entry.name)) continue
+        walk(full)
+      } else if (RELOAD_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        files.push(full)
+      }
+    }
+  }
+  for (const root of roots) {
+    const resolved = path.resolve(root)
+    try {
+      const st = fs.statSync(resolved)
+      if (st.isFile()) files.push(resolved)
+      else if (st.isDirectory()) walk(resolved)
+    } catch {
+      /* missing root */
+    }
+  }
+  return files
+}
+
+function snapshotMtimes(files) {
+  const map = new Map()
+  for (const file of files) {
+    try {
+      map.set(file, fs.statSync(file).mtimeMs)
+    } catch {
+      /* ignore */
+    }
+  }
+  return map
+}
+
+async function runWithReloader({ watchDirs } = {}) {
+  const roots = watchDirs?.length ? watchDirs : [process.cwd()]
+  console.log(`fusion: reload enabled (watching ${roots.join(', ')})`)
+
+  let child = null
+  const spawnChild = () => {
+    const env = { ...process.env, FUSION_RELOAD_CHILD: '1' }
+    child = spawn(process.execPath, process.argv.slice(1), {
+      env,
+      stdio: 'inherit',
+    })
+    return child
+  }
+
+  const stopChild = () =>
+    new Promise((resolve) => {
+      if (!child || child.exitCode !== null) {
+        child = null
+        resolve()
+        return
+      }
+      child.once('exit', () => {
+        child = null
+        resolve()
+      })
+      child.kill('SIGTERM')
+      setTimeout(() => {
+        if (child) child.kill('SIGKILL')
+      }, 5000)
+    })
+
+  const shutdown = async () => {
+    await stopChild()
+    process.exit(0)
+  }
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+
+  let mtimes = snapshotMtimes(collectWatchedFiles(roots))
+  spawnChild()
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    await new Promise((r) => setTimeout(r, 500))
+    if (child && child.exitCode !== null) {
+      console.log(`fusion: child exited (${child.exitCode}); restarting…`)
+      await new Promise((r) => setTimeout(r, 300))
+      spawnChild()
+      mtimes = snapshotMtimes(collectWatchedFiles(roots))
+      continue
+    }
+    const files = collectWatchedFiles(roots)
+    const next = snapshotMtimes(files)
+    let changed = null
+    for (const [file, mtime] of next) {
+      const prev = mtimes.get(file)
+      if (prev === undefined || mtime > prev) {
+        changed = file
+        break
+      }
+    }
+    if (!changed) {
+      for (const file of mtimes.keys()) {
+        if (!next.has(file)) {
+          changed = file
+          break
+        }
+      }
+    }
+    if (!changed) continue
+    let label = changed
+    try {
+      label = path.relative(process.cwd(), changed) || changed
+    } catch {
+      /* keep absolute */
+    }
+    console.log(`fusion: change detected (${label}); reloading…`)
+    await stopChild()
+    spawnChild()
+    mtimes = snapshotMtimes(collectWatchedFiles(roots))
+  }
+}
+
 async function run(options = {}) {
   const settingsModulePath =
     typeof options === 'string' ? options : options && options.settingsModule
@@ -980,7 +1766,12 @@ async function run(options = {}) {
   }
   const app = new FusionApp()
   for (const mw of middleware) app.use(mw)
-  await app.listen()
+  await app.listen({
+    reload: options && Object.prototype.hasOwnProperty.call(options, 'reload')
+      ? options.reload
+      : undefined,
+    watchDirs: options?.watchDirs,
+  })
   return app
 }
 
@@ -1005,6 +1796,147 @@ function paginatedBody(items, total, params) {
   return native.paginatedBody(items, total, params)
 }
 
+/** Process-wide application cache (default driver: moka). */
+const cache = {
+  _ready: false,
+  _ensure() {
+    if (this._ready) return
+    try {
+      // Use the native Settings singleton (not getSettings()'s plain object).
+      settings.ensureLoaded([process.cwd()])
+      native.cacheConfigure(settings)
+      this._ready = true
+    } catch {
+      native.cacheConfigureDriver('moka', null, null)
+      this._ready = true
+    }
+  },
+  configure(settingsInstance) {
+    const s = settingsInstance || settings
+    if (s && typeof s.ensureLoaded === 'function') {
+      s.ensureLoaded([process.cwd()])
+    }
+    native.cacheConfigure(s)
+    this._ready = true
+  },
+  configureDriver(driver = 'moka', { maxCapacity, defaultTtl } = {}) {
+    native.cacheConfigureDriver(driver, maxCapacity ?? null, defaultTtl ?? null)
+    this._ready = true
+  },
+  set(key, value, ttl = null) {
+    this._ensure()
+    native.cacheSet(key, value, ttl)
+  },
+  get(key) {
+    this._ensure()
+    return native.cacheGet(key)
+  },
+  delete(key) {
+    this._ensure()
+    return native.cacheDelete(key)
+  },
+  exists(key) {
+    this._ensure()
+    return native.cacheExists(key)
+  },
+  getOrSet(key, defaultValue, ttl = null) {
+    this._ensure()
+    if (native.cacheExists(key)) return native.cacheGet(key)
+    const value = typeof defaultValue === 'function' ? defaultValue() : defaultValue
+    return native.cacheGetOrSet(key, value, ttl)
+  },
+  deleteOrSet(key, value, ttl = null) {
+    this._ensure()
+    return native.cacheDeleteOrSet(key, value, ttl)
+  },
+  existsOrSet(key, value, ttl = null) {
+    this._ensure()
+    return native.cacheExistsOrSet(key, value, ttl)
+  },
+  clear() {
+    this._ensure()
+    native.cacheClear()
+  },
+  driver() {
+    this._ensure()
+    return native.cacheDriver()
+  },
+  /** Live entries + recent mutations (monitor JSON). */
+  snapshot() {
+    this._ensure()
+    return native.cacheSnapshot()
+  },
+  /** Template context for fusion/cache_monitor.html. */
+  panelContext() {
+    this._ensure()
+    return native.cachePanelContext()
+  },
+  reset() {
+    native.cacheReset()
+    this._ready = false
+  },
+
+  /** Async set (Promise). */
+  async aset(key, value, ttl = null) {
+    this.set(key, value, ttl)
+  },
+  async aget(key) {
+    return this.get(key)
+  },
+  async adelete(key) {
+    return this.delete(key)
+  },
+  async aexists(key) {
+    return this.exists(key)
+  },
+  async agetOrSet(key, defaultValue, ttl = null) {
+    this._ensure()
+    if (native.cacheExists(key)) return native.cacheGet(key)
+    let value = typeof defaultValue === 'function' ? defaultValue() : defaultValue
+    if (value && typeof value.then === 'function') value = await value
+    return native.cacheGetOrSet(key, value, ttl)
+  },
+  async adeleteOrSet(key, value, ttl = null) {
+    return this.deleteOrSet(key, value, ttl)
+  },
+  async aexistsOrSet(key, value, ttl = null) {
+    return this.existsOrSet(key, value, ttl)
+  },
+  async aclear() {
+    this.clear()
+  },
+}
+
+/** Process-wide Tokio background tasks. */
+const tasks = {
+  /** Run `fn` on the Tokio background runtime. Returns task id. */
+  spawn(fn) {
+    if (typeof fn !== 'function') throw new TypeError('callback must be a function')
+    return native.taskSpawn(fn)
+  },
+  /** Run `fn` after `delayMs` milliseconds. Returns task id. */
+  spawnAfter(delayMs, fn) {
+    if (typeof fn !== 'function') throw new TypeError('callback must be a function')
+    return native.taskSpawnAfter(Number(delayMs) || 0, fn)
+  },
+  /** Cancel a pending/running task. */
+  cancel(taskId) {
+    return native.taskCancel(String(taskId))
+  },
+  /** Status string, or null if unknown. */
+  status(taskId) {
+    return native.taskStatus(String(taskId))
+  },
+  /** JSON snapshot of tracked tasks (also under cache.snapshot().tasks). */
+  snapshot() {
+    return native.taskSnapshot()
+  },
+  /** Abort and clear all tracked tasks (tests). */
+  reset() {
+    native.taskReset()
+  },
+}
+
 const route = router
 
 module.exports = {
@@ -1012,6 +1944,8 @@ module.exports = {
   Settings: NativeSettings,
   FusionApp,
   FusionBaseApi,
+  FusionBaseTemplate,
+  parseFormBody,
   HTTPException,
   router,
   route,
@@ -1035,11 +1969,26 @@ module.exports = {
   run,
   bearerJwt,
   requireRoles,
+  requirePermissions,
   frameworkHeaders,
+  securityHeaders,
+  cors,
+  cacheHeaders,
+  requestId,
+  staticFiles,
   runMiddlewareChain,
   coerceParam,
   parsePagination,
   paginatedBody,
+  cache,
+  tasks,
+  mountMonitor,
+  mountCacheMonitor,
+  renderTemplate,
+  clearRouteRegistry,
+  openapiSpec,
+  routeVersions,
+  hasUnversionedRoutes,
   getHttpMethods: () => HTTP_METHODS,
   apiResourceNameJs: native.apiResourceNameJs,
   resolveRoutePathJs: native.resolveRoutePathJs,