@velora-cms/server 0.11.0

package/dist/routes/marketplace-proxy.js

@@ -0,0 +1,135 @@
+import { ApiErrorSchema, MarketplaceInstallBodySchema, MarketplaceInstallResponseSchema, MarketplaceListQuerySchema, MarketplaceListResponseSchema, MarketplaceListingDetailSchema, MarketplacePluginIdParamsSchema, } from "@velora-cms/api-schemas";
+import { requireAdmin } from "../auth/require-auth.js";
+import { prisma } from "../db/prisma.js";
+import { installFromMarketplace } from "../marketplace/install-from-marketplace.js";
+import { MarketplaceNotFoundError, MarketplaceUnavailableError, fetchListing, fetchListings, } from "../marketplace/marketplace-client.js";
+/** Compatibility is decided HERE, against this CMS's own dialect: the
+ * registry would refuse an incompatible install anyway (S64), so the
+ * browse screen says so up front rather than letting a user try. */
+function annotate(listing, activeDialect) {
+    const dialects = listing.latestVersion?.supportedDialects ?? [];
+    return { ...listing, compatible: dialects.includes(activeDialect) };
+}
+export const marketplaceProxyRoutes = async (app, opts) => {
+    const { marketplaceBaseUrl, activeDialect, adapter } = opts;
+    app.get("/api/plugin-management/marketplace/listings", {
+        onRequest: requireAdmin,
+        schema: {
+            querystring: MarketplaceListQuerySchema,
+            response: { 200: MarketplaceListResponseSchema, 401: ApiErrorSchema, 403: ApiErrorSchema, 503: ApiErrorSchema },
+        },
+    }, async (request, reply) => {
+        try {
+            const body = (await fetchListings(marketplaceBaseUrl, request.query));
+            return {
+                items: body.items.map((item) => annotate(item, activeDialect)),
+                nextCursor: body.nextCursor ?? null,
+                activeDialect,
+                marketplaceBaseUrl,
+            };
+        }
+        catch (error) {
+            if (error instanceof MarketplaceUnavailableError) {
+                return reply.code(503).send({ message: error.message });
+            }
+            throw error;
+        }
+    });
+    app.get("/api/plugin-management/marketplace/listings/:pluginId", {
+        onRequest: requireAdmin,
+        schema: {
+            params: MarketplacePluginIdParamsSchema,
+            response: {
+                200: MarketplaceListingDetailSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+                503: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        try {
+            const listing = (await fetchListing(marketplaceBaseUrl, request.params.pluginId));
+            return {
+                ...annotate(listing, activeDialect),
+                versions: listing.versions ?? [],
+                activeDialect,
+                marketplaceBaseUrl,
+            };
+        }
+        catch (error) {
+            if (error instanceof MarketplaceNotFoundError) {
+                return reply.code(404).send({ message: error.message });
+            }
+            if (error instanceof MarketplaceUnavailableError) {
+                return reply.code(503).send({ message: error.message });
+            }
+            throw error;
+        }
+    });
+    // In-CMS marketplace install (Session 138) — the ordered
+    // already-installed -> listing/version -> (paid) license -> download ->
+    // verify -> register spine lives in installFromMarketplace so it stays
+    // reviewable in one place; this handler just maps its outcome to a
+    // status code.
+    app.post("/api/plugin-management/marketplace/install", {
+        onRequest: requireAdmin,
+        schema: {
+            body: MarketplaceInstallBodySchema,
+            response: {
+                201: MarketplaceInstallResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+                409: ApiErrorSchema,
+                422: ApiErrorSchema,
+                503: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        try {
+            const outcome = await installFromMarketplace({ prisma, registry: app.pluginRegistry, marketplaceBaseUrl, adapter }, 
+            // installedBy is server-derived from the verified JWT (requireAdmin
+            // already ran via onRequest), never taken from the request body —
+            // D2's createdBy rule for any sample content this install seeds.
+            { ...request.body, installedBy: request.user.sub });
+            if (outcome.ok) {
+                return reply.code(201).send({
+                    pluginId: outcome.pluginId,
+                    version: outcome.version,
+                    trustTier: outcome.trustTier,
+                    licensed: outcome.licensed,
+                    ...(outcome.members ? { members: outcome.members } : {}),
+                });
+            }
+            const status = {
+                "already-installed": 409,
+                "not-found": 404,
+                "license-required": 400,
+                "site-domain-missing": 409,
+                "license-rejected": 403,
+                "verification-failed": 422,
+                // M2 (S138 hardening review) — see InstallFailure's own comment in
+                // install-from-marketplace.ts for why 422 vs 409 was chosen for
+                // each of these three.
+                incompatible: 422,
+                "dependency-missing": 409,
+                "install-refused": 422,
+                // S152: a member of the requested bundle failed — the bundle
+                // package itself may be fine, but the SET it names can't be
+                // processed on this server right now. Same 422 family as
+                // verification-failed/install-refused; the message names the
+                // offending member and its underlying reason.
+                "bundle-member-failed": 422,
+            };
+            return reply.code(status[outcome.failure.code]).send({ message: outcome.failure.message });
+        }
+        catch (error) {
+            if (error instanceof MarketplaceUnavailableError) {
+                return reply.code(503).send({ message: error.message });
+            }
+            throw error;
+        }
+    });
+};

package/dist/routes/media.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { MediaService } from "../media/media-service.js";
+export interface MediaRoutesOptions {
+    mediaService: MediaService;
+}
+export declare const mediaRoutes: FastifyPluginAsyncZod<MediaRoutesOptions>;

package/dist/routes/media.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { ApiErrorSchema, MediaDeleteResponseSchema, MediaFileResponseSchema, MediaListQuerySchema, MediaListResponseSchema, } from "@velora-cms/api-schemas";
+import { requireAuth } from "../auth/require-auth.js";
+const MediaParamsSchema = z.object({ id: z.string().uuid() });
+export const mediaRoutes = async (app, opts) => {
+    const { mediaService } = opts;
+    async function toResponse(media) {
+        return { ...media, downloadUrl: await mediaService.getDownloadUrl(media.id) };
+    }
+    app.post("/api/media", {
+        onRequest: requireAuth,
+        schema: {
+            // Multipart body — file part validated by hand below; Zod can't
+            // describe a multipart stream, so validation here is response-side
+            // plus the explicit 400s.
+            consumes: ["multipart/form-data"],
+            response: {
+                201: MediaFileResponseSchema,
+                400: ApiErrorSchema,
+                401: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const file = await request.file();
+        if (!file || !file.filename) {
+            return reply.code(400).send({ message: "A multipart file field is required" });
+        }
+        const data = await file.toBuffer();
+        const media = await mediaService.upload({
+            filename: file.filename,
+            mimeType: file.mimetype,
+            data,
+            uploadedBy: request.user.sub,
+        });
+        return reply.code(201).send(await toResponse(media));
+    });
+    // Media library listing — admin-authed (SEC-6, S175 audit). This lists
+    // EVERY uploaded asset regardless of publish state, each with a working
+    // presigned downloadUrl, so it must not be anonymously enumerable;
+    // published/headless media has its own API-key-gated /api/v1/media
+    // surface. The admin UI reaches this through authFetch.
+    app.get("/api/media", {
+        onRequest: requireAuth,
+        schema: {
+            querystring: MediaListQuerySchema,
+            response: {
+                200: MediaListResponseSchema,
+                401: ApiErrorSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit, search } = request.query;
+        const files = await mediaService.list({ cursor, limit, search });
+        const items = await Promise.all(files.map(toResponse));
+        const nextCursor = files.length === limit ? (files[files.length - 1]?.id ?? null) : null;
+        return { items, nextCursor };
+    });
+    app.get("/api/media/:id", {
+        onRequest: requireAuth,
+        schema: {
+            params: MediaParamsSchema,
+            response: {
+                200: MediaFileResponseSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const media = await mediaService.getById(request.params.id);
+        if (!media) {
+            return reply.code(404).send({ message: `No media file found for id ${request.params.id}` });
+        }
+        return toResponse(media);
+    });
+    app.delete("/api/media/:id", {
+        onRequest: requireAuth,
+        schema: {
+            params: MediaParamsSchema,
+            response: {
+                200: MediaDeleteResponseSchema,
+                401: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const media = await mediaService.getById(request.params.id);
+        if (!media) {
+            return reply.code(404).send({ message: `No media file found for id ${request.params.id}` });
+        }
+        await mediaService.delete(media.id);
+        return { success: true };
+    });
+};

package/dist/routes/plugin-api-routes.d.ts

@@ -0,0 +1,12 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { ContentService } from "@velora-cms/content-service";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { PluginRegistryService } from "../plugins/plugin-registry-service.js";
+import type { StructuredStorageAPI } from "../plugins/structured-storage-api.js";
+export interface PluginApiRouteOptions {
+    registry: PluginRegistryService;
+    structuredStorageAPI: StructuredStorageAPI;
+    contentService: ContentService;
+    adapter: DatabaseAdapter;
+}
+export declare const pluginApiRoutes: FastifyPluginAsyncZod<PluginApiRouteOptions>;

package/dist/routes/plugin-api-routes.js

@@ -0,0 +1,224 @@
+import { ApiErrorSchema } from "@velora-cms/api-schemas";
+import { PluginNotActiveError, PluginNotInstalledError } from "../plugins/plugin-registry-service.js";
+import { buildContext } from "../plugins/plugin-context.js";
+import { requireApiKey } from "../auth/api-keys.js";
+import { rateLimitConfig } from "../auth/rate-limit.js";
+import { requireAdmin } from "../auth/require-auth.js";
+import { corsOptionsFromEnv } from "../config/cors.js";
+function findDeclaredRoute(manifest, method, path) {
+    const declared = manifest.type === "section" ? (manifest.contributions.apiRoutes ?? []) : [];
+    return declared.find((route) => route.method === method && route.path === path);
+}
+// Real runtime mounting of the apiRoutes contribution (Month 8, Session
+// 89) — previously manifest-validated only, never mounted anywhere.
+// Fastify 5's router is sealed once the server starts listening, so a
+// plugin's routes (only known once its manifest is installed/activated,
+// possibly long after boot) can't be registered as literal Fastify
+// routes. Instead, exactly 5 routes are registered here at boot — one
+// per HTTP method contributions.apiRoutes supports — each a wildcard
+// catch-all under /api/plugins/:pluginId/*, dispatching at request time
+// to whichever route the target plugin's manifest actually declares.
+// Mirrors plugin-storage.ts's exact same shape of problem (one fixed
+// route, request-time dispatch via requireActivePlugin) generalized
+// from a single fixed sub-path to an arbitrary plugin-declared set.
+//
+// Auth is enforced per-route as of Session 108: each declared route's
+// `access` (Task 1's ApiRouteContribution.access) gates the dispatch,
+// defaulting to "admin" when the manifest omits it — with "apiKey" as an
+// explicit opt-in for headless consumers (e.g. Commerce's checkout).
+// Session 160 adds a third tier, "public" — genuinely un-credentialed,
+// for anonymous browser traffic like a contact-form submission, deferred
+// back in Session 108 until a real consumer showed up. So a route CAN
+// now be called with zero credentials, but only when its manifest opts
+// in explicitly; every other value (including unrecognized ones) still
+// falls back to "admin". Rate limiting for apiKey and public routes
+// lands in this same session, as a separate, orthogonal concern (who may
+// call vs. how often).
+export const pluginApiRoutes = async (app, opts) => {
+    // Applies to every dispatch route registered in the prefixed child
+    // scope below — a parent context's hooks cascade to its children, so
+    // this doesn't need to move inside that scope to keep covering them.
+    await app.register(import("@fastify/rate-limit"), rateLimitConfig);
+    const { registry, structuredStorageAPI, contentService, adapter } = opts;
+    function dispatch(method) {
+        return async (request, reply) => {
+            const { pluginId } = request.params;
+            const wildcard = request.params["*"] ?? "";
+            const path = `/${wildcard}`;
+            try {
+                await registry.requireActivePlugin(pluginId);
+            }
+            catch (err) {
+                if (err instanceof PluginNotInstalledError) {
+                    return reply.code(404).send({ message: err.message });
+                }
+                if (err instanceof PluginNotActiveError) {
+                    return reply.code(403).send({ message: err.message });
+                }
+                throw err;
+            }
+            const attached = registry.getManifest(pluginId);
+            if (!attached) {
+                // Transient, not permanent: the plugin IS installed and active
+                // (requireActivePlugin above already confirmed the DB row) — its
+                // manifest just isn't attached in THIS process (no boot-time
+                // plugin loader re-attaches every active plugin's manifest on
+                // restart yet). A 503, not a 404, so a headless consumer knows
+                // this is retryable rather than "this route doesn't exist."
+                return reply.code(503).send({
+                    message: `Plugin "${pluginId}" is active but its manifest is not loaded in this process`,
+                });
+            }
+            const route = findDeclaredRoute(attached, method, path);
+            if (!route) {
+                return reply.code(404).send({ message: `No route ${method} ${path} declared by plugin "${pluginId}"` });
+            }
+            // Enforce the route's declared access. Default (and any
+            // unrecognized value) is "admin" — secure by default, by
+            // construction. "public" is S160's genuinely un-credentialed tier
+            // for anonymous browser traffic (form submissions); such a route
+            // owns its own abuse controls, and the platform's contribution is
+            // the IP rate ceiling in rate-limit.ts plus the CORS allowlist.
+            // Runs here (not as a route-level onRequest hook) because the
+            // access level is only known once the declared route is resolved.
+            // requireApiKey/requireAdmin send their own 401/403 and we bail if
+            // they did.
+            const access = route.access ?? "admin";
+            if (access === "public") {
+                // No credential check by design.
+            }
+            else if (access === "apiKey") {
+                await requireApiKey(request, reply);
+            }
+            else {
+                await requireAdmin(request, reply);
+            }
+            if (reply.sent)
+                return reply;
+            // Re-bind to each schema's parsed output (not just validate-then-
+            // discard) — same behavior a normally-registered Fastify route gets
+            // from fastify-type-provider-zod, so a plugin's z.coerce/.default()/
+            // .transform() actually take effect for its handler, not just the
+            // raw wire value.
+            if (route.schema?.body) {
+                const result = route.schema.body.safeParse(request.body);
+                if (!result.success) {
+                    return reply.code(400).send({ message: `Invalid request body: ${result.error.message}` });
+                }
+                request.body = result.data;
+            }
+            if (route.schema?.querystring) {
+                const result = route.schema.querystring.safeParse(request.query);
+                if (!result.success) {
+                    return reply.code(400).send({ message: `Invalid query string: ${result.error.message}` });
+                }
+                request.query = result.data;
+            }
+            if (route.schema?.params) {
+                const result = route.schema.params.safeParse(request.params);
+                if (!result.success) {
+                    return reply.code(400).send({ message: `Invalid params: ${result.error.message}` });
+                }
+                request.params = result.data;
+            }
+            try {
+                // route.handler's return is deliberately `unknown` at the SDK
+                // boundary (manifest.ts: "the handler's response is NOT
+                // schema-validated — trusted, same as SimpleStorageAPI's
+                // handlers today"). The response schema below only documents
+                // the error shapes (400/403/404/500), so fastify-type-provider-
+                // zod infers a strict `void | ApiError` return type for this
+                // handler — this cast is a compile-time-only acknowledgment of
+                // that intentionally-untyped success path, not a runtime lie:
+                // Fastify serializes whatever is returned regardless.
+                const context = buildContext(pluginId, structuredStorageAPI, contentService, adapter);
+                return (await route.handler(request, reply, context));
+            }
+            catch (cause) {
+                request.log.error({ err: cause, pluginId, path }, "plugin apiRoute handler threw");
+                return reply.code(500).send({ message: "Internal server error" });
+            }
+        };
+    }
+    const responseSchema = {
+        400: ApiErrorSchema,
+        401: ApiErrorSchema,
+        403: ApiErrorSchema,
+        404: ApiErrorSchema,
+        500: ApiErrorSchema,
+        503: ApiErrorSchema,
+    };
+    // CORS and the dispatch routes are registered inside a PREFIXED child
+    // scope, not directly on `app`, and that prefix is what actually
+    // confines this to plugin routes. @fastify/cors is fastify-plugin-
+    // wrapped, so its onRequest HOOK is properly encapsulated (same as
+    // rate-limit above) — but it also registers a real ROUTE
+    // (`fastify.options('*')`), and Fastify's route table is server-wide:
+    // encapsulation confines hooks and decorators, it does NOT confine
+    // where a route's path matches. Registered directly on `app` (whose
+    // own routes below already carried full literal paths, i.e. no
+    // prefix), that `*` would have matched EVERY path on the server, not
+    // just this plugin's dispatch routes — a browser on an allowlisted
+    // origin could preflight and then send a non-simple cross-origin
+    // request (JSON body, Authorization header) to any core endpoint, not
+    // just a plugin's. Reads stayed blocked (the response hook is scoped,
+    // so no Access-Control-Allow-Origin ever came back on those), but
+    // blind cross-origin writes to core endpoints were live. Wrapping both
+    // in a `{ prefix: "/api/plugins" }` child scope confines the ROUTE to
+    // `/api/plugins/*` — routes below are written relative to that prefix
+    // accordingly. The child scope still inherits the rate-limit hook
+    // registered on `app` above.
+    //
+    // That confines the route, but not the blast radius to just THIS
+    // scope's own dispatch routes: `OPTIONS /api/plugins/*` also matches
+    // GET /api/plugins (routes/plugins.ts), plugin-storage.ts's GET/PUT, and
+    // plugin-management.ts's routes — none of which are registered in this
+    // scope, so none of them get the CORS response hook, so none of them
+    // ever return Access-Control-Allow-Origin on the actual (non-preflight)
+    // request. That gap is NOT exploitable, and is not being restructured
+    // here — two things contain it: corsOptionsFromEnv's `methods` allowlist
+    // (GET/POST/OPTIONS only) means a preflight for plugin-management's
+    // DELETE or plugin-storage's PUT is refused before any cross-origin
+    // write can be attempted, and `credentials: false` plus app.ts
+    // registering fastifyJwt with no `cookie` option means jwtVerify() only
+    // ever reads the Authorization header — never a cookie a browser would
+    // attach ambiently — so there is no ambient-credential CSRF surface for
+    // the wildcard preflight to ride in on.
+    //
+    // One real, harmless behaviour change this DOES cause: with
+    // strictPreflight left at its default (true), `OPTIONS
+    // /api/plugins/anything` now 400s (missing Origin or
+    // Access-Control-Request-Method) instead of 404ing as it did before this
+    // scope existed — including when VELORA_CORS_ORIGINS is unset, since
+    // @fastify/cors is registered unconditionally and only the response
+    // headers it adds are gated on that var, not the OPTIONS route/hook
+    // themselves.
+    await app.register(async (scope) => {
+        // strictPreflight (the plugin's default: true) is left as-is: an
+        // OPTIONS request that's missing Origin or Access-Control-Request-
+        // Method now 400s only under this prefix, not server-wide, and
+        // nothing in the dispatch verbs below is OPTIONS — a bare OPTIONS
+        // hitting a plugin route is either a real preflight (always sends
+        // both headers) or a malformed one worth rejecting, not a generic
+        // uptime probe (those target /api/health, not a plugin path).
+        await scope.register(import("@fastify/cors"), corsOptionsFromEnv((msg) => scope.log.warn(msg)));
+        // bodyLimit (S160 final-fix, finding 3): app.ts sets no bodyLimit, so
+        // Fastify's 1 MB default would otherwise apply here too — including
+        // to the "public" (zero-credential) tier, where the body is parsed,
+        // and for forms's /submit route re-serialized and hashed, BEFORE any
+        // plugin-level size check (e.g. forms-api.ts's MAX_SUBMISSION_BYTES,
+        // 20 KB) or rate-bucket slot is ever spent. 64 KB is comfortably
+        // above every real admin payload these dispatch routes carry today
+        // (form/redirect-rule/webhook-endpoint definitions, a Commerce
+        // checkout body) while cutting the untrusted-parse ceiling by ~16x
+        // for the public route. Checked before verified above: reviewed
+        // every current plugins/* POST/PUT/PATCH route to confirm none sends
+        // a body anywhere near this size.
+        const bodyLimit = 65536;
+        scope.get("/:pluginId/*", { schema: { response: responseSchema } }, dispatch("GET"));
+        scope.post("/:pluginId/*", { bodyLimit, schema: { response: responseSchema } }, dispatch("POST"));
+        scope.put("/:pluginId/*", { bodyLimit, schema: { response: responseSchema } }, dispatch("PUT"));
+        scope.patch("/:pluginId/*", { bodyLimit, schema: { response: responseSchema } }, dispatch("PATCH"));
+        scope.delete("/:pluginId/*", { bodyLimit, schema: { response: responseSchema } }, dispatch("DELETE"));
+    }, { prefix: "/api/plugins" });
+};

package/dist/routes/plugin-assets.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyInstance } from "fastify";
+export declare const PLUGIN_ASSETS_PREFIX = "/plugin-assets";
+/** The server-relative remoteUrl a marketplace install stores (Task 2).
+ * Server-relative rather than absolute so a host/port/domain change never
+ * invalidates installed rows; the admin absolutizes against its own
+ * origin, which fronts this server for /api and /docs already. */
+export declare function pluginAssetsRemoteUrl(pluginId: string, version: string): string;
+export declare function pluginAssetsRoutes(app: FastifyInstance): Promise<void>;

package/dist/routes/plugin-assets.js

@@ -0,0 +1,51 @@
+import { mkdirSync } from "node:fs";
+import fastifyStatic from "@fastify/static";
+import { resolvePluginsDir } from "../plugins/plugin-package-store.js";
+// S143: serves the managed plugin package store (plugin-package-store.ts,
+// .velora/plugins/<pluginId>/<version>/) over HTTP so the admin's Module
+// Federation loader can fetch a marketplace-installed plugin's
+// remoteEntry.js — closing the S142 documented gap that left
+// marketplace-installed plugins silently skipped by boot-remote-plugins
+// (empty remoteUrl). The URL path IS the store path: no indirection.
+//
+// Unauthenticated by design, the same posture as GET /api/plugins (this is
+// the same package bytes anyone can download from the public marketplace).
+// Rate limiting joins the Month 14 pre-deploy backlog with the rest of the
+// public surface. Serving server/plugin.js alongside the client assets is
+// accepted: identical bytes ship in the public package artifact.
+// Stored VERBATIM in pluginRegistry.remoteUrl rows at install time —
+// changing this prefix strands every already-installed row on the old
+// literal path (plugins silently stop loading) until a backfill or
+// reinstall. Treat it as frozen, not a config knob.
+export const PLUGIN_ASSETS_PREFIX = "/plugin-assets";
+/** The server-relative remoteUrl a marketplace install stores (Task 2).
+ * Server-relative rather than absolute so a host/port/domain change never
+ * invalidates installed rows; the admin absolutizes against its own
+ * origin, which fronts this server for /api and /docs already. */
+export function pluginAssetsRemoteUrl(pluginId, version) {
+    return `${PLUGIN_ASSETS_PREFIX}/${pluginId}/${version}/remoteEntry.js`;
+}
+export async function pluginAssetsRoutes(app) {
+    const root = resolvePluginsDir();
+    // @fastify/static@10 throws "root must be a directory" at registration
+    // (the docs-static.ts lesson) — on a fresh instance nothing is installed
+    // yet, so create the store empty. It is server-owned, so this is safe.
+    mkdirSync(root, { recursive: true });
+    // Static infra, not Zod-validated JSON — hidden from Swagger up front
+    // (the docs-static.ts treatment) rather than leaking bare path entries.
+    app.addHook("onRoute", (routeOptions) => {
+        if (routeOptions.url.startsWith(PLUGIN_ASSETS_PREFIX)) {
+            routeOptions.schema = { ...routeOptions.schema, hide: true };
+        }
+    });
+    // Encapsulated child context with a trailing-slash prefix: confines
+    // setNotFoundHandler to this mount (docs-static.ts documents why — a
+    // bare prefix would hijack the app-wide 404, including /api/*).
+    await app.register(async (assetsApp) => {
+        await assetsApp.register(fastifyStatic, {
+            root,
+            decorateReply: false,
+        });
+        assetsApp.setNotFoundHandler((_req, reply) => reply.code(404).send({ message: "not found" }));
+    }, { prefix: `${PLUGIN_ASSETS_PREFIX}/` });
+}

package/dist/routes/plugin-management.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { StructuredSnapshotService } from "../plugins/structured-snapshot-service.js";
+export declare const pluginManagementRoutes: FastifyPluginAsyncZod<{
+    adapter: DatabaseAdapter;
+    structuredSnapshotService: StructuredSnapshotService;
+}>;