@raclettejs/core 0.1.23 → 0.1.25

package/services/backend/dist/domains/system/routes/index.js

@@ -0,0 +1,17 @@
+import { getBlockedLogins, resetLoginBlock, resetAllLoginBlocks, } from "./route.admin.cache";
+import deploy from "./route.deploy";
+import login from "./route.user.login";
+import checkToken from "./route.user.checkToken";
+import getAllCollections from "./route.collection.getAll";
+import deleteCollections from "./route.collection.remove";
+const registerRoutes = async (fastify) => {
+    await fastify.get("/system/deploy", deploy(fastify));
+    await fastify.post("/user/login", login(fastify));
+    await fastify.get("/user/check-token", checkToken(fastify));
+    await fastify.get("/admin/cache/blocks", getBlockedLogins(fastify));
+    await fastify.delete("/admin/cache/blocks/:key", resetLoginBlock(fastify));
+    await fastify.delete("/admin/cache/blocks", resetAllLoginBlocks(fastify));
+    await fastify.get("/admin/collections/all", getAllCollections(fastify));
+    await fastify.delete("/admin/collections", deleteCollections(fastify));
+};
+export default registerRoutes;

package/services/backend/dist/helpers/index.js

@@ -0,0 +1,14 @@
+import { customAlphabet } from "nanoid";
+export * from "./cors";
+const customCyperAlphabet = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+ * Random ID generator
+ *
+ * @param length - Required length for the output
+ * @returns Function that generates random IDs
+ * @example
+ * const generateId = randomIdGenerator(12);
+ * const id = generateId(); // => 'gdh6326GDJh0'
+ */
+const randomIdGenerator = (length = 16) => customAlphabet(customCyperAlphabet, length);
+export { randomIdGenerator };

package/services/backend/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./utils";
+export * from "./core/contracting/contractRegistrar";

package/services/backend/dist/modules/authentication/index.js

@@ -0,0 +1,253 @@
+import jwt from "@fastify/jwt";
+import fastifyPlugin from "fastify-plugin";
+import configService from "@c/config/configService";
+import { ForbiddenError } from "@/utils/errors";
+const WORK_SESSION_COLLECTION = "raclette__core-worksession";
+const WORK_SESSION_HEADER = "x-work-session-id";
+/**
+ * Middleware: allow either authenticated user (JWT) or valid work session (X-Work-Session-Id).
+ * When using this, the route states that it handles permission checks itself (e.g. compare req.workSession with query).
+ * - If JWT present and valid: sets req.user (normal auth).
+ * - If no/invalid JWT but X-Work-Session-Id present: loads work session, validates (active, not expired),
+ *   optionally checks that workSession.pluginData includes the given pluginKey, then sets req.workSession and req.isWorkSession.
+ */
+export const authenticatedOrWorksession = async (req, res, fastify, pluginKey) => {
+    fastify.log.debug(`[Auth] authenticatedOrWorksession: ${pluginKey} ${req.method} ${req.url}`);
+    const { requireAuthentication } = configService.getConfig()?.global ?? {
+        requireAuthentication: true,
+    };
+    const isAdminTagRequired = configService.isAdminTagRequired();
+    if (!requireAuthentication) {
+        const mockUser = { _id: "SYSTEM" };
+        req.user = mockUser;
+        return;
+    }
+    // 1) Try JWT first
+    try {
+        await req.jwtVerify();
+        const payload = req.user;
+        fastify.log.debug(`[Auth] JWT verified, payload type: ${payload.type || "user"}, sessionId: ${payload.sessionId || "none"}, _id: ${payload._id || "none"}`);
+        if (payload.type === "workSession" && payload.sessionId) {
+            fastify.log.info(`[Auth] Work session JWT detected, sessionId: ${payload.sessionId}, pluginKey: ${pluginKey}`);
+            // Work session JWT: load session and validate
+            const workSession = await loadAndValidateWorkSession(fastify, payload.sessionId, pluginKey);
+            if (!workSession) {
+                fastify.log.warn(`[Auth] Work session validation failed for sessionId: ${payload.sessionId}`);
+                return res
+                    .status(401)
+                    .send({ message: "Invalid or expired work session" });
+            }
+            fastify.log.info(`[Auth] Work session authenticated: sessionId=${payload.sessionId}, pluginKey=${pluginKey}`);
+            req.workSession = workSession;
+            req.isWorkSession = true;
+            // Set projectId from workSession.project if available
+            if (workSession.project) {
+                req.projectId = workSession.project;
+                fastify.log.debug(`[Auth] Work session projectId: ${req.projectId}`);
+            }
+            return;
+        }
+        // Normal user JWT: fetch user and set req.user
+        fastify.log.debug(`[Auth] Normal user JWT, fetching user: ${req.user?._id}`);
+        const { _id } = req.user;
+        const adminTag = await fastify.database
+            .collection("raclette__core-tag")
+            .findOne({ title: "ADMIN", locked: true, type: "system" });
+        let isAdmin = false;
+        const user = await fastify.database
+            .collection("raclette__core-user")
+            .findOne({ _id }, { projection: { password: 0, resetKey: 0 } });
+        if (user && user.tags && adminTag) {
+            user.tags.forEach((tag) => {
+                if (adminTag._id === tag)
+                    isAdmin = true;
+            });
+        }
+        if (isAdminTagRequired && !isAdmin) {
+            fastify.log.error("User not allowed in workbench");
+            return res.status(403).send({ message: "User not allowed in workbench" });
+        }
+        if (isAdmin)
+            user.isAdmin = true;
+        if (!user) {
+            fastify.log.error("User not found");
+            return res.status(401).send({ message: "User not found" });
+        }
+        const account = await fastify.database
+            .collection("raclette__core-account")
+            .findOne({ _id: user.account });
+        user.account = account;
+        req.user = user;
+        // Set projectId from user's lastProjectId (for requestData.project in payload wrappers)
+        if (user.ux?.lastProjectId) {
+            req.projectId = user.ux.lastProjectId;
+            fastify.log.debug(`[Auth] User projectId: ${req.projectId}`);
+        }
+        return;
+    }
+    catch (error) {
+        // JWT missing or invalid: try work session via header
+        fastify.log.debug(`[Auth] JWT verification failed: ${error.message}, trying work session header`);
+    }
+    // 2) Try X-Work-Session-Id header
+    const sessionId = req.headers[WORK_SESSION_HEADER];
+    if (sessionId) {
+        const workSession = await loadAndValidateWorkSession(fastify, sessionId, pluginKey);
+        if (workSession) {
+            req.workSession = workSession;
+            req.isWorkSession = true;
+            // Set projectId from workSession.project if available
+            // workaround for how projects/spaces are currently handled - tbd
+            if (workSession.project) {
+                req.projectId = workSession.project;
+            }
+            return;
+        }
+        else {
+            fastify.log.warn(`[Auth] Work session validation failed for header sessionId: ${sessionId}`);
+        }
+    }
+    return res.status(401).send({ message: "Authentication required" });
+};
+async function loadAndValidateWorkSession(fastify, sessionId, pluginKey) {
+    fastify.log.debug(`[WorkSession Auth] Loading and validating work session: sessionId=${sessionId}, pluginKey=${pluginKey}`);
+    if (!sessionId || typeof sessionId !== "string") {
+        fastify.log.warn(`[WorkSession Auth] Invalid sessionId: ${sessionId}`);
+        return null;
+    }
+    fastify.log.debug(`[WorkSession Auth] Querying database for work session`);
+    const doc = await fastify.database
+        .collection(WORK_SESSION_COLLECTION)
+        .findOne({ _id: sessionId });
+    if (!doc) {
+        fastify.log.warn(`[WorkSession Auth] Work session not found: ${sessionId}`);
+        return null;
+    }
+    if (!doc.isActive) {
+        fastify.log.warn(`[WorkSession Auth] Work session is not active: ${sessionId}`);
+        return null;
+    }
+    const expiry = doc.expiryDate ? new Date(doc.expiryDate) : null;
+    if (expiry && expiry.getTime() < Date.now()) {
+        fastify.log.warn(`[WorkSession Auth] Work session expired: ${sessionId}, expiryDate: ${expiry.toISOString()}`);
+        return null;
+    }
+    // Check that this plugin is part of the work session (pluginData keys are "pluginKey:widgetName")
+    const pluginData = doc.pluginData || {};
+    const pluginKeys = Object.keys(pluginData);
+    const hasPlugin = pluginKeys.some((k) => k.startsWith(pluginKey + ":")) ||
+        Object.prototype.hasOwnProperty.call(pluginData, pluginKey);
+    if (!hasPlugin) {
+        fastify.log.warn(`[WorkSession Auth] Plugin ${pluginKey} not found in work session pluginData: ${pluginKeys.join(", ")}`);
+        return null;
+    }
+    fastify.log.info(`[WorkSession Auth] Work session validated successfully: sessionId=${sessionId}, pluginKey=${pluginKey}`);
+    return doc;
+}
+export const authenticate = async (req, res, fastify) => {
+    {
+        const { requireAuthentication } = configService.getConfig()?.global ?? {
+            requireAuthentication: true,
+        };
+        const isAdminTagRequired = configService.isAdminTagRequired();
+        // Skip JWT verification and database queries, if global.requireAuthentication is configured to false
+        if (!requireAuthentication) {
+            const mockUser = {
+                _id: "SYSTEM",
+            };
+            req.user = mockUser;
+            return;
+        }
+        try {
+            await req.jwtVerify();
+            const payload = req.user;
+            if (payload.type === "workSession") {
+                return res
+                    .status(401)
+                    .send({ message: "Work session token not allowed on this route" });
+            }
+            // fetch current user data from the db
+            const { _id } = req.user;
+            const adminTag = await fastify.database
+                .collection("raclette__core-tag")
+                .findOne({ title: "ADMIN", locked: true, type: "system" });
+            // IMPORTANT
+            // due to some very weird behaviour, mongoose always returns empty results
+            // so we are using mongodb directly until we fix this
+            let isAdmin = false;
+            const user = await fastify.database
+                .collection("raclette__core-user")
+                .findOne({ _id }, { projection: { password: 0, resetKey: 0 } });
+            if (user && user.tags && adminTag) {
+                user.tags.forEach((tag) => {
+                    if (adminTag._id === tag) {
+                        isAdmin = true;
+                    }
+                });
+            }
+            if (isAdminTagRequired && !isAdmin) {
+                fastify.log.error("User not allowed in workbench");
+                throw new Error("User not allowed in workbench");
+            }
+            if (isAdmin) {
+                user.isAdmin = true;
+            }
+            if (!user) {
+                fastify.log.error("User not found");
+                throw new Error("User not found");
+            }
+            const account = await fastify.database
+                .collection("raclette__core-account")
+                .findOne({ _id: user.account });
+            user.account = account;
+            req.user = user;
+        }
+        catch (error) {
+            return res.send(error);
+        }
+    }
+};
+export const checkPermissions = async (req, res, fastify, permissions) => {
+    {
+        try {
+            if (!permissions.length) {
+                fastify.log.error("No permissions given for permission check");
+                throw new Error("No Permissions");
+            }
+            // TODO implement proper Permission lookup here
+            permissions.forEach((permissionStr) => {
+                if (permissionStr === "user.isAdmin") {
+                    if (!req.user.isAdmin) {
+                        throw new ForbiddenError("User not permitted to action");
+                    }
+                }
+            });
+        }
+        catch (error) {
+            fastify.log.error(error.message);
+            return res.send(error.message);
+        }
+    }
+};
+export default fastifyPlugin(async (fastify, opts = {}) => {
+    // provide some sensible options
+    const defaults = {
+        secret: false,
+        decode: { complete: true },
+        sign: {
+            iss: "api.raclettejs.info",
+            expiresIn: "30d",
+        },
+        verify: { allowedIss: "api.raclettejs.info" },
+    };
+    // merge proved opts with defaults
+    const mergedOptions = { ...defaults, ...opts };
+    /* register the plugin */
+    fastify.register(jwt, mergedOptions);
+    // decorate the fastify instance, so we can call it anywhere
+    fastify.decorate("authenticate", (req, res) => {
+        return authenticate(req, res, fastify);
+    });
+    fastify.decorate("authenticatedOrWorksession", (pluginKey) => (req, res) => authenticatedOrWorksession(req, res, fastify, pluginKey));
+    fastify.decorate("checkPermissions", (permissionsArr) => (req, res) => checkPermissions(req, res, fastify, permissionsArr));
+});

package/services/backend/dist/shared/types/core/index.js

@@ -0,0 +1,8 @@
+/**
+ * ⚠️ WARNING: THIS FILE IS AUTO-GENERATED ⚠️
+ *
+ * This file is generated by the type generation system.
+ * Any manual changes will be overwritten on next server start and should always be committed.
+ *
+ */
+export {};

package/services/backend/dist/shared/types/dataTypes/index.js

@@ -0,0 +1,6 @@
+export * from "./tags";
+// TODO make the mongoDataTypes dynamic
+export const systemDataTypes = ["account", "projectConfig", "userConfig"];
+export const userContents = ["tag", "user", "project"];
+export const mongoDataTypes = systemDataTypes.concat(userContents);
+export const syncableDatatypes = ["tag", "user", "searchResult"];

package/services/backend/dist/shared/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * ⚠️ WARNING: THIS FILE IS AUTO-GENERATED ⚠️
+ *
+ * This file is generated by the type generation system.
+ * Any manual changes will be overwritten on next server start and should always be committed.
+ *
+ */
+export {};

package/services/backend/dist/shared/types/plugins/index.js

@@ -0,0 +1,8 @@
+/**
+ * ⚠️ WARNING: THIS FILE IS AUTO-GENERATED ⚠️
+ *
+ * This file is generated by the type generation system.
+ * Any manual changes will be overwritten on next server start and should always be committed.
+ *
+ */
+export {};

package/services/backend/dist/types/index.js

@@ -0,0 +1,12 @@
+export * from "../core/backgroundTasks/taskManagerTypes";
+export * from "../core/config/configTypes";
+export * from "../core/crud/crudTypes";
+export * from "../core/http/httpTypes";
+export * from "../core/http/httpTypes";
+export * from "../core/payload/payloadTypes";
+export * from "../core/pluginSystem/pluginTypes";
+export * from "../core/sockets/socketTypes";
+export * from "../core/validation/schemaTypes";
+export * from "../modules/cache/cacheTypes";
+export * from "../core/validation/schemaTypes";
+export * from "../core/pluginSystem/configGenerator/generatorTypes";

package/services/backend/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from "./errors";
+export * from "./request.utils";

package/services/backend/package.json

@@ -16,6 +16,7 @@
     "build:assets:src": "copyfiles -u 1 'src/**/*.{json,js,yml,yaml,env*}' dist",
     "build:assets:root": "copyfiles -u 0 'raclette.config.js' dist",
     "build:assets": "npm run build:assets:src && npm run build:assets:root",
+    "lint": "eslint .",
     "migrate:create": "npx migrate-mongo create -f './mongo-migrations/migrate-mongo-config.js'",
     "migrate:up": "migrate-mongo up -f './mongo-migrations/migrate-mongo-config.js'",
     "migrate:down": "migrate-mongo down -f './mongo-migrations/migrate-mongo-config.js'",
@@ -24,28 +25,29 @@
     "typecheck:watch": "tsc --noEmit --watch"
   },
   "dependencies": {
-    "@fastify/cors": "11.1.0",
+    "@fastify/cors": "11.2.0",
     "@fastify/jwt": "10.0.0",
     "@fastify/rate-limit": "10.3.0",
     "@fastify/schedule": "6.0.0",
-    "@fastify/sensible": "6.0.3",
-    "@sinclair/typebox": "0.34.41",
+    "@fastify/sensible": "6.0.4",
+    "@sinclair/typebox": "0.34.48",
     "@types/vary": "1.1.3",
-    "axios": "1.13.2",
+    "axios": "1.13.6",
     "bcrypt": "6.0.0",
     "copyfiles": "2.4.1",
-    "fastify": "5.6.0",
+    "fastify": "5.8.2",
     "fastify-custom-healthcheck": "4.0.0",
-    "glob": "11.0.3",
+    "fs-extra": "11.3.4",
+    "glob": "13.0.6",
     "iovalkey": "0.3.3",
-    "migrate-mongo": "12.1.3",
-    "mongodb": "^6.20.0",
-    "mongoose": "8.18.1",
-    "nanoid": "5.1.5",
-    "pino": "9.9.5",
-    "pino-pretty": "13.1.1",
-    "ramda": "0.31.3",
-    "socket.io": "4.8.1",
+    "migrate-mongo": "14.0.7",
+    "mongodb": "6.21.0",
+    "mongoose": "8.18.3",
+    "nanoid": "5.1.7",
+    "pino": "10.3.1",
+    "pino-pretty": "13.1.3",
+    "ramda": "0.32.0",
+    "socket.io": "4.8.3",
     "toad-scheduler": "3.1.0",
     "tsc-alias": "1.8.16",
     "uuid": "13.0.0"
@@ -58,9 +60,9 @@
     "@types/uuid": "11.0.0",
     "eslint": "9.35.0",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-prefer-arrow-functions": "3.8.1",
-    "tsx": "4.20.5",
-    "typescript": "5.9.2",
-    "typescript-eslint": "8.44.0"
+    "eslint-plugin-prefer-arrow-functions": "3.9.1",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.57.1"
   }
 }

package/services/backend/src/core/contracting/contractRegistrar.ts

@@ -12,7 +12,7 @@ export const registerPluginContract = (
   contract: PluginContract,
 ): void => {
   if (contracts[pluginKey]) {
-    throw new Error(`Plugin contract for "${pluginKey}" is already registered`)
+    throw new Error(`Plugin contract for "${pluginKey}" is already registered. Make sure that each plugin is calling fastify.generatePluginContract only once! Multiple calls are not allowed.`)
   }
 
   contracts[pluginKey] = contract

package/services/backend/src/core/pluginSystem/configGenerator/generatorTypes.ts

@@ -13,6 +13,7 @@ export type PluginRegistration = {
   author: string
   pluginKey: string
   pluginPath: string
+  frontendPath: string
   routePrefix: string
   entityMapping?: Record<string, string>
   customConfig?: {

package/services/backend/src/core/pluginSystem/configGenerator/index.ts

@@ -42,6 +42,7 @@ class FrontendConfigRegistry {
       author: pluginData.author,
       pluginKey: pluginData.key,
       pluginPath: pluginData.absolutePath,
+      frontendPath: pluginData.frontendAbsolutePath,
       routePrefix: pluginData.routePrefix,
       entityMapping: options?.entityMapping || {},
       customConfig: options?.customConfig,
@@ -451,8 +452,7 @@ const writePluginConfigFile = async (
 
   const configContent = generatePluginConfigFile(dataTypes, registration)
   const outputPath = path.join(
-    registration.pluginPath,
-    "frontend",
+    registration.frontendPath,
     "generated-config.ts",
   )
 

package/services/backend/src/core/pluginSystem/pluginLoader.ts

@@ -30,6 +30,7 @@ interface PluginInfo {
   pluginName: string
   modulePath: string
   pluginPath: string
+  frontendPath: string
   type: PluginType
   metadata: PluginMetadata
 }
@@ -75,6 +76,74 @@ const logPluginError = (
   fastify.log.debug(`${createLogPrefix(type)} ${identifier}: ERROR - ${error}`)
 }
 
+const normalizeRelativeDir = (dir?: string): string | undefined =>
+  dir?.replace(/^\.\//, "")
+
+const resolveExistingServicePath = async (
+  pluginPath: string,
+  candidates: string[],
+): Promise<{ relativePath: string; absolutePath: string } | undefined> => {
+  for (const candidatePath of candidates) {
+    const normalizedCandidatePath = normalizeRelativeDir(candidatePath)
+    if (!normalizedCandidatePath) continue
+
+    const candidateAbsolutePath = path.join(pluginPath, normalizedCandidatePath)
+    try {
+      const stat = await fs.promises.stat(candidateAbsolutePath)
+      if (stat.isDirectory()) {
+        return {
+          relativePath: normalizedCandidatePath,
+          absolutePath: candidateAbsolutePath,
+        }
+      }
+    } catch {
+      // path missing or not accessible
+    }
+  }
+}
+
+const resolveBackendPath = async (
+  pluginPath: string,
+  metadata: PluginMetadata,
+): Promise<{ relativePath: string; absolutePath: string } | undefined> => {
+  const backendPathCandidates = getBackendPathCandidates(metadata)
+
+  return resolveExistingServicePath(pluginPath, backendPathCandidates)
+}
+
+const getBackendPathCandidates = (metadata: PluginMetadata): string[] => {
+  const explicitBackendDir = normalizeRelativeDir(metadata.backendDir)
+  if (explicitBackendDir) {
+    return [explicitBackendDir]
+  }
+
+  return ["backend", "src/backend"]
+}
+
+const resolveFrontendPath = async (
+  pluginPath: string,
+  metadata: PluginMetadata,
+  backendRelativePath?: string,
+): Promise<string> => {
+  const explicitFrontendDir = normalizeRelativeDir(metadata.frontendDir)
+  if (explicitFrontendDir) {
+    return path.join(pluginPath, explicitFrontendDir)
+  }
+
+  const resolvedFrontendPath = await resolveExistingServicePath(pluginPath, [
+    "frontend",
+    "src/frontend",
+  ])
+  if (resolvedFrontendPath) {
+    return resolvedFrontendPath.absolutePath
+  }
+
+  // Fall back to src/frontend when backend is under src, otherwise frontend.
+  const fallbackRelativePath =
+    backendRelativePath?.startsWith("src/") ? "src/frontend" : "frontend"
+  return path.join(pluginPath, fallbackRelativePath)
+}
+
 /**
  * Get app plugin paths for current environment
  */
@@ -254,16 +323,18 @@ const collectLocalPluginsFromPath = async (
         continue
       }
 
-      // Get backend path from metadata or use default
-      const backendRelativePath = metadata.backendDir || "backend"
-      const backendPath = path.join(pluginPath, backendRelativePath)
+      // Get backend path from metadata or try supported defaults.
+      const resolvedBackendPath = await resolveBackendPath(pluginPath, metadata)
+      const backendRelativePath = resolvedBackendPath?.relativePath
+      const backendPath = resolvedBackendPath?.absolutePath
 
-      if (!fs.existsSync(backendPath)) {
+      if (!backendRelativePath || !backendPath) {
+        const backendPathCandidates = getBackendPathCandidates(metadata)
         logPluginSkipped(
           fastify,
           pluginType,
           pluginIdentifier,
-          `backend directory not found: ${backendRelativePath}`,
+          `backend directory not found: ${backendPathCandidates.join(" or ")}`,
         )
         if (metadata.backendDir) {
           // we only cancel when the dir was explicitly set
@@ -277,24 +348,6 @@ const collectLocalPluginsFromPath = async (
         continue
       }
 
-      if (!fs.statSync(backendPath).isDirectory()) {
-        logPluginSkipped(
-          fastify,
-          pluginType,
-          pluginIdentifier,
-          `backend path is not a directory: ${backendRelativePath}`,
-        )
-        if (metadata.backendDir) {
-          handlePluginError(
-            fastify,
-            `Server directory not found for plugin: ${configPath}`,
-            pluginType,
-            errorFlags,
-          )
-        }
-        continue
-      }
-
       // Find the main module file
       const modulePath = getFilePathWithExtension(backendPath, "index")
       if (!modulePath) {
@@ -315,12 +368,18 @@ const collectLocalPluginsFromPath = async (
 
       const author = slugify(metadata.author)
       const pluginName = slugify(metadata.name)
+      const frontendPath = await resolveFrontendPath(
+        pluginPath,
+        metadata,
+        backendRelativePath,
+      )
 
       plugins.push({
         author,
         pluginName,
         modulePath,
         pluginPath,
+        frontendPath,
         type: pluginType,
         metadata,
       })
@@ -462,32 +521,21 @@ const collectNpmPlugins = async (
         continue
       }
 
-      // Get backend path from metadata or use default
-      const backendRelativePath = pluginMetadata.backendDir || "src/backend"
-      const backendPath = path.join(pluginPath, backendRelativePath)
-
-      if (!fs.existsSync(backendPath)) {
-        logPluginSkipped(
-          fastify,
-          PluginType.NPM,
-          pluginPackage,
-          `backend directory not found: ${backendRelativePath}`,
-        )
-        handlePluginError(
-          fastify,
-          `Server directory not found for npm plugin: ${pluginPackage}`,
-          PluginType.NPM,
-          errorFlags,
-        )
-        continue
-      }
+      // Get backend path from metadata or try supported defaults.
+      const resolvedBackendPath = await resolveBackendPath(
+        pluginPath,
+        pluginMetadata,
+      )
+      const backendRelativePath = resolvedBackendPath?.relativePath
+      const backendPath = resolvedBackendPath?.absolutePath
 
-      if (!fs.statSync(backendPath).isDirectory()) {
+      if (!backendRelativePath || !backendPath) {
+        const backendPathCandidates = getBackendPathCandidates(pluginMetadata)
         logPluginSkipped(
           fastify,
           PluginType.NPM,
           pluginPackage,
-          `backend path is not a directory: ${backendRelativePath}`,
+          `backend directory not found: ${backendPathCandidates.join(" or ")}`,
         )
         handlePluginError(
           fastify,
@@ -518,12 +566,18 @@ const collectNpmPlugins = async (
 
       const author = slugify(pluginMetadata.author)
       const pluginName = slugify(pluginMetadata.name)
+      const frontendPath = await resolveFrontendPath(
+        pluginPath,
+        pluginMetadata,
+        backendRelativePath,
+      )
 
       plugins.push({
         author,
         pluginName,
         modulePath,
         pluginPath,
+        frontendPath,
         type: PluginType.NPM,
         metadata: pluginMetadata,
       })
@@ -704,6 +758,7 @@ const registerCollectedPlugins = async (
         collectionPrefix,
         routePrefix,
         absolutePath: plugin.pluginPath,
+        frontendAbsolutePath: plugin.frontendPath,
       }
 
       // Dynamically import the plugin module