@velora-cms/server 0.11.0

package/dist/plugins/uninstall-bundle.d.ts

@@ -0,0 +1,29 @@
+import type { PrismaClient } from "@prisma/client";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import { type PluginRegistryService } from "./plugin-registry-service.js";
+export declare class BundleMemberBlockedError extends Error {
+    constructor(memberPluginId: string, dependentPluginId: string);
+}
+export declare class BundleUninstallRequiresConfirmationError extends Error {
+    readonly memberSnapshots: Array<{
+        pluginId: string;
+        snapshotGroupId: string;
+    }>;
+    constructor(bundlePluginId: string, memberSnapshots: Array<{
+        pluginId: string;
+        snapshotGroupId: string;
+    }>);
+}
+export interface UninstallBundleDeps {
+    prisma: PrismaClient;
+    registry: PluginRegistryService;
+    adapter: DatabaseAdapter;
+}
+export declare function uninstallBundle(deps: UninstallBundleDeps, bundlePluginId: string, options: {
+    confirmStructuredDataCleanup: boolean;
+}): Promise<{
+    memberSnapshots: Array<{
+        pluginId: string;
+        snapshotGroupId: string;
+    }>;
+}>;

package/dist/plugins/uninstall-bundle.js

@@ -0,0 +1,150 @@
+import { DocumentTypeService } from "@velora-cms/content-service";
+import { removePluginPackages } from "./plugin-package-store.js";
+import { StructuredDataCleanupRequiresConfirmationError, } from "./plugin-registry-service.js";
+// S152's bundle-uninstall cascade. Lives ABOVE PluginRegistryService —
+// uninstall() stays single-plugin — at the same layer the DELETE route
+// already orchestrates its per-plugin cross-cutting cleanup (package
+// store, manifest detach, license rows), because the cascade is exactly
+// that orchestration repeated per owned member.
+//
+// Order (the S88 check-first discipline, cross-plugin):
+//   1. preflight EVERYTHING (doc-type deletability, outside dependents)
+//   2. aggregate the structured-data confirmation gate (snapshots taken,
+//      nothing destroyed — the S87 safe-retry property, kept)
+//   3. only then cascade: owned members in reverse install order, bundle
+//      row last.
+export class BundleMemberBlockedError extends Error {
+    constructor(memberPluginId, dependentPluginId) {
+        super(`Cannot uninstall this bundle: its member "${memberPluginId}" is a dependency of "${dependentPluginId}", which is not part of the bundle — uninstall "${dependentPluginId}" first`);
+        this.name = "BundleMemberBlockedError";
+    }
+}
+export class BundleUninstallRequiresConfirmationError extends Error {
+    memberSnapshots;
+    constructor(bundlePluginId, memberSnapshots) {
+        super(`Uninstalling bundle "${bundlePluginId}" will drop structured data for: ${memberSnapshots
+            .map((s) => `"${s.pluginId}"`)
+            .join(", ")}. Snapshots have been taken; retry with confirmStructuredDataCleanup: true to proceed`);
+        this.memberSnapshots = memberSnapshots;
+        this.name = "BundleUninstallRequiresConfirmationError";
+    }
+}
+export async function uninstallBundle(deps, bundlePluginId, options) {
+    const { prisma, registry, adapter } = deps;
+    // Owned members, in install order. Rows whose member registry row is
+    // gone (individually uninstalled since the bundle install — the
+    // recorded tolerated case) contribute no work; their stale ownership
+    // rows are swept at the end.
+    const ownershipRows = await prisma.pluginBundleMember.findMany({
+        where: { bundlePluginId },
+        orderBy: { position: "asc" },
+    });
+    const ownedIds = ownershipRows.map((row) => row.memberPluginId);
+    const memberRows = await prisma.pluginRegistry.findMany({ where: { pluginId: { in: ownedIds } } });
+    const existingMemberIds = new Set(memberRows.map((row) => row.pluginId));
+    const removalIds = new Set([bundlePluginId, ...existingMemberIds]);
+    // Preflight 1: every tracked document type of every plugin in the
+    // removal set must be deletable BEFORE anything is removed — the same
+    // guard uninstall() runs per plugin, hoisted so a blocked member is
+    // found while the whole set is still intact. Throws
+    // DocumentTypeInUseError (the route already maps it to 409).
+    const documentTypeService = new DocumentTypeService(adapter);
+    const trackedDocTypes = await prisma.pluginDocumentType.findMany({
+        where: { pluginId: { in: [...removalIds] } },
+    });
+    for (const tracked of trackedDocTypes) {
+        await documentTypeService.assertDocumentTypeDeletable(tracked.documentTypeId);
+    }
+    // Preflight 2: no plugin OUTSIDE the removal set may depend on an owned
+    // member (uninstall() itself has no dependents guard — without this, a
+    // cascade would silently break a dependent that had every right to rely
+    // on the "installed AND enabled" check that admitted it). Attached
+    // manifests are the source (complete on a booted server since S122); a
+    // row with no attached manifest cannot be checked and is skipped —
+    // consistent with uninstall()'s own missing-manifest tolerance.
+    const allRows = await prisma.pluginRegistry.findMany();
+    for (const row of allRows) {
+        if (removalIds.has(row.pluginId))
+            continue;
+        const manifest = registry.getManifest(row.pluginId);
+        const dependencies = manifest?.pluginDependencies ?? [];
+        const blocked = dependencies.find((dependency) => existingMemberIds.has(dependency));
+        if (blocked) {
+            throw new BundleMemberBlockedError(blocked, row.pluginId);
+        }
+    }
+    // Preflight 3: the aggregated structured-data gate. Calling uninstall()
+    // UNCONFIRMED on a structured plugin snapshots it and then throws
+    // having changed nothing else (S87's ordering) — so harvesting each
+    // structured plugin's snapshotGroupId this way is non-destructive by
+    // construction. Simple-storage plugins are never dry-run (an
+    // unconfirmed uninstall() would really uninstall them).
+    if (!options.confirmStructuredDataCleanup) {
+        const structuredIds = [
+            ...memberRows.filter((row) => row.storageType === "structured").map((row) => row.pluginId),
+        ];
+        const bundleRow = await prisma.pluginRegistry.findUnique({ where: { pluginId: bundlePluginId } });
+        if (bundleRow?.storageType === "structured") {
+            structuredIds.push(bundlePluginId);
+        }
+        if (structuredIds.length > 0) {
+            const memberSnapshots = [];
+            for (const structuredId of structuredIds) {
+                try {
+                    await registry.uninstall(structuredId, { confirmStructuredDataCleanup: false });
+                    throw new Error(`uninstall("${structuredId}") completed without the structured-data confirmation gate firing — refusing to continue a bundle cascade on inconsistent state`);
+                }
+                catch (error) {
+                    if (error instanceof StructuredDataCleanupRequiresConfirmationError) {
+                        memberSnapshots.push({ pluginId: structuredId, snapshotGroupId: error.snapshotGroupId });
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+            throw new BundleUninstallRequiresConfirmationError(bundlePluginId, memberSnapshots);
+        }
+    }
+    // Cascade: owned members in REVERSE install order, each with the same
+    // route-level cleanup a single-plugin uninstall gets, deleting its
+    // ownership row as it completes so a mid-cascade failure leaves an
+    // honest picture for a retry. Bundle row last.
+    //
+    // Task 6: each confirmed uninstall() call now hands back the fresh
+    // snapshotGroupId it minted (null for a simple-storage member) — collect
+    // only the non-null ones here, same shape as the aggregated 409 above,
+    // so a confirmed bundle uninstall can report exactly which structured
+    // members got a fresh snapshot.
+    const memberSnapshots = [];
+    const orderedForRemoval = [...ownershipRows].reverse();
+    for (const ownership of orderedForRemoval) {
+        if (existingMemberIds.has(ownership.memberPluginId)) {
+            const { snapshotGroupId } = await registry.uninstall(ownership.memberPluginId, {
+                confirmStructuredDataCleanup: options.confirmStructuredDataCleanup,
+            });
+            if (snapshotGroupId) {
+                memberSnapshots.push({ pluginId: ownership.memberPluginId, snapshotGroupId });
+            }
+            removePluginPackages(ownership.memberPluginId);
+            registry.detachManifest(ownership.memberPluginId);
+            await prisma.pluginLicense.deleteMany({ where: { pluginId: ownership.memberPluginId } });
+        }
+        await prisma.pluginBundleMember.deleteMany({
+            where: { bundlePluginId, memberPluginId: ownership.memberPluginId },
+        });
+    }
+    const { snapshotGroupId: bundleSnapshotGroupId } = await registry.uninstall(bundlePluginId, {
+        confirmStructuredDataCleanup: options.confirmStructuredDataCleanup,
+    });
+    if (bundleSnapshotGroupId) {
+        memberSnapshots.push({ pluginId: bundlePluginId, snapshotGroupId: bundleSnapshotGroupId });
+    }
+    removePluginPackages(bundlePluginId);
+    registry.detachManifest(bundlePluginId);
+    await prisma.pluginLicense.deleteMany({ where: { pluginId: bundlePluginId } });
+    // Belt-and-braces: no rows should remain, but a row for a member that
+    // vanished mid-flight must not survive the bundle.
+    await prisma.pluginBundleMember.deleteMany({ where: { bundlePluginId } });
+    return { memberSnapshots };
+}

package/dist/plugins/verify-package.d.ts

@@ -0,0 +1,36 @@
+import type { TrustedKey, VerifyResult } from "@velora-cms/plugin-package";
+/** The detached sidecar convention: <artifact>.tar.gz.sig beside the
+ * artifact. Detached rather than embedded because the signature is over the
+ * tarball's own hash and therefore cannot live inside it. */
+export declare function resolveSidecarPath(tarballPath: string): string;
+export declare function verifyPackage(tarballPath: string, sidecarPath: string | null, trustedKeys: TrustedKey[]): Promise<VerifyResult>;
+/**
+ * The post-extraction half of verification. The envelope's pluginId and
+ * version can only be compared against the package's own manifest.json
+ * AFTER extraction, so this runs separately from verifyPackage and can
+ * DOWNGRADE a verified result.
+ *
+ * The envelope comes off the `verified` result itself (the one
+ * `verifyEnvelope` already authenticated), never from a second,
+ * unauthenticated read of the sidecar file — that would let a mismatched
+ * re-read silently replace the identity that was actually verified. If a
+ * `verified` result somehow carries no envelope, this DOWNGRADES rather
+ * than passing it through: a trust decision must never fail open by
+ * skipping the one check it exists to make.
+ *
+ * A cryptographically valid signature over the wrong package's identity
+ * must never yield "verified" — that is precisely the mistake a half-built
+ * approval flow could introduce.
+ */
+export declare function checkPackageIdentity(result: VerifyResult, pluginId: string, version: string): VerifyResult;
+/** One place that decides how each outcome is surfaced. An unsigned package
+ * is silent — velora-dev and private agency plugins are unsigned by design
+ * and must not nag. A package that CLAIMS a signature and fails is loud and
+ * names the reason. */
+export declare function describeVerifyResult(result: VerifyResult, tarballPath: string): void;
+/** The two trust tiers a registry row can carry. Narrower than `string` so
+ * `PluginRegistryService.install`, `registerLocalPlugin`, and
+ * `installBuiltPackage` can't silently accept an arbitrary tier value. */
+export type TrustTier = "verified" | "unverified";
+/** The tier a verdict maps to. Only a clean "verified" earns the tier. */
+export declare function trustTierFor(result: VerifyResult): TrustTier;

package/dist/plugins/verify-package.js

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hashTarball, verifyEnvelope } from "@velora-cms/plugin-package";
+// Install-time signature verification (Session 127).
+//
+// NEVER throws, and NEVER blocks an install. Per the Trust model,
+// sideloading is a requirement rather than a loophole: an unverifiable
+// package still installs, as "unverified", with a loud warning. Only
+// extraction can fail an install, because an archive that violates a
+// hardening rule is not a package at all.
+const LOG_PREFIX = "[plugin-verify]";
+/** A generous ceiling for an envelope plus a base64 Ed25519 signature — a
+ * few KB at most. The tarball itself is streamed rather than buffered (see
+ * hashTarball), with its own size bound arriving later from the extractor's
+ * MAX_TOTAL_BYTES; the sidecar, by contrast, is read fully into memory
+ * below, so an attacker-supplied sidecar needs its own ceiling — one that
+ * had none before this, so an oversized file is rejected before it is ever
+ * read into memory. */
+const MAX_SIDECAR_BYTES = 8192;
+/** The detached sidecar convention: <artifact>.tar.gz.sig beside the
+ * artifact. Detached rather than embedded because the signature is over the
+ * tarball's own hash and therefore cannot live inside it. */
+export function resolveSidecarPath(tarballPath) {
+    return `${tarballPath}.sig`;
+}
+export async function verifyPackage(tarballPath, sidecarPath, trustedKeys) {
+    if (!sidecarPath || !existsSync(sidecarPath)) {
+        return { status: "unsigned" };
+    }
+    let sidecar;
+    try {
+        // statSync lives inside this try, not before it, even though it only
+        // "checks a size": this module never throws, and a file that passed
+        // existsSync a moment ago can still fail to stat — deleted or replaced
+        // in the gap, or (on Windows) held open exclusively by whatever wrote
+        // it (EBUSY/EPERM). Hoisting it back above this try would let that race
+        // escape verifyPackage and abort an install that should instead proceed
+        // as "unverified".
+        if (statSync(sidecarPath).size > MAX_SIDECAR_BYTES) {
+            return {
+                status: "failed",
+                reason: "malformed-sidecar",
+                message: `${sidecarPath} exceeds the ${MAX_SIDECAR_BYTES}-byte sidecar size ceiling`,
+            };
+        }
+        sidecar = JSON.parse(readFileSync(sidecarPath, "utf8"));
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            reason: "malformed-sidecar",
+            message: `${sidecarPath} could not be read as a signature sidecar: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    let sha256;
+    try {
+        sha256 = await hashTarball(tarballPath);
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            reason: "artifact-unreadable",
+            message: `${tarballPath} could not be read: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return verifyEnvelope(sidecar, sha256, trustedKeys);
+}
+/**
+ * The post-extraction half of verification. The envelope's pluginId and
+ * version can only be compared against the package's own manifest.json
+ * AFTER extraction, so this runs separately from verifyPackage and can
+ * DOWNGRADE a verified result.
+ *
+ * The envelope comes off the `verified` result itself (the one
+ * `verifyEnvelope` already authenticated), never from a second,
+ * unauthenticated read of the sidecar file — that would let a mismatched
+ * re-read silently replace the identity that was actually verified. If a
+ * `verified` result somehow carries no envelope, this DOWNGRADES rather
+ * than passing it through: a trust decision must never fail open by
+ * skipping the one check it exists to make.
+ *
+ * A cryptographically valid signature over the wrong package's identity
+ * must never yield "verified" — that is precisely the mistake a half-built
+ * approval flow could introduce.
+ */
+export function checkPackageIdentity(result, pluginId, version) {
+    if (result.status !== "verified")
+        return result;
+    const { envelope } = result;
+    if (!envelope) {
+        return {
+            status: "failed",
+            reason: "identity-mismatch",
+            message: "verified result carried no envelope to check identity against — refusing to trust it",
+        };
+    }
+    if (envelope.pluginId === pluginId && envelope.version === version)
+        return result;
+    return {
+        status: "failed",
+        reason: "identity-mismatch",
+        message: `signature covers ${envelope.pluginId}@${envelope.version} but the package contains ${pluginId}@${version}`,
+    };
+}
+/** One place that decides how each outcome is surfaced. An unsigned package
+ * is silent — velora-dev and private agency plugins are unsigned by design
+ * and must not nag. A package that CLAIMS a signature and fails is loud and
+ * names the reason. */
+export function describeVerifyResult(result, tarballPath) {
+    if (result.status === "verified") {
+        console.log(`${LOG_PREFIX} verified ${tarballPath} against trusted key ${result.keyId}`);
+        return;
+    }
+    if (result.status === "failed") {
+        console.warn(`${LOG_PREFIX} SIGNATURE VERIFICATION FAILED for ${tarballPath} (${result.reason}): ${result.message}`);
+        console.warn(`${LOG_PREFIX} installing as "unverified" — the package is NOT blocked, but it is NOT trusted`);
+    }
+}
+/** The tier a verdict maps to. Only a clean "verified" earns the tier. */
+export function trustTierFor(result) {
+    return result.status === "verified" ? "verified" : "unverified";
+}

package/dist/routes/admin-static.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyInstance } from "fastify";
+interface AdminDirResolution {
+    dir: string | null;
+    invalidOverride: string | undefined;
+}
+export declare function resolveAdminDir(): AdminDirResolution;
+export declare function adminStaticRoutes(app: FastifyInstance): Promise<void>;
+export {};

package/dist/routes/admin-static.js

@@ -0,0 +1,196 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import fastifyStatic from "@fastify/static";
+import { ADMIN_RATE_LIMIT, ipOnlyRateLimitConfig } from "../auth/route-rate-limits.js";
+import { isAdminUiEnabled } from "../config/admin-ui.js";
+// A usable admin directory: it must actually be a directory (not a file —
+// @fastify/static@10.1.3 throws "root must be a directory" at registration
+// otherwise, crashing buildApp()) and it must contain the SPA's index.html
+// — an empty directory would otherwise resolve successfully and then serve
+// bare per-route 404s instead of the clear 404-with-cause. index.html is
+// also what the fallback route below reads on every deep link, so its
+// presence is a hard precondition for this module, not a heuristic.
+function isUsableAdminDir(candidate) {
+    try {
+        return statSync(candidate).isDirectory() && existsSync(join(candidate, "index.html"));
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveAdminDir() {
+    const override = process.env.VELORA_ADMIN_DIR;
+    if (override) {
+        // path.resolve() before anything else: @fastify/static@10.1.3 also
+        // throws ("root must be an absolute path") at registration when root
+        // is relative. Resolving against cwd up front means a relative
+        // override behaves the same as an absolute one instead of crashing
+        // boot.
+        const resolved = resolve(override);
+        if (isUsableAdminDir(resolved))
+            return { dir: resolved, invalidOverride: undefined };
+        return { dir: null, invalidOverride: override };
+    }
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/routes or src/routes
+    const candidates = [
+        join(here, "..", "admin-bundle"),
+        join(here, "..", "..", "..", "..", "apps", "admin-ui", "dist-bundle"),
+    ];
+    const dir = candidates.find((c) => isUsableAdminDir(c)) ?? null;
+    return { dir, invalidOverride: undefined };
+}
+// Local copies of docs-static.ts's private helpers rather than a shared
+// export: that module deliberately keeps them private, and duplicating
+// three tiny functions is cheaper than inventing a shared "degraded static
+// response" abstraction for two callers.
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+// /velora is opened directly in a browser tab (it IS the browser surface),
+// so a degraded response there should be readable HTML, not raw JSON.
+// Anything else (curl, tests, uptime probes) keeps the JSON shape.
+function wantsHtml(req) {
+    return (req.headers.accept ?? "").includes("text/html");
+}
+function sendDegraded(req, reply, message) {
+    if (wantsHtml(req)) {
+        return reply
+            .code(404)
+            .type("text/html")
+            .send(`<!doctype html><html><head><meta charset="utf-8"><title>Admin unavailable</title></head>` +
+            `<body><h1>Admin unavailable</h1><p>${escapeHtml(message)}</p></body></html>`);
+    }
+    return reply.code(404).send({ message });
+}
+export async function adminStaticRoutes(app) {
+    // S162 precedent: static-ish reads, but not unbounded. Registered
+    // per-scope, matching auth.ts/docs-static.ts/plugin-api-routes.ts/
+    // public-api.ts — @fastify/rate-limit decorates the instance, so it is
+    // registered in child scopes OR at the root, never both.
+    //
+    // ipOnlyRateLimitConfig(), NOT the shared three-lane rateLimitConfig
+    // docs-static.ts uses. That is the one place this module cannot copy
+    // docs-static, and it is the S162-I6 constraint verbatim: auth/
+    // rate-limit.ts imports auth/api-keys.ts, which imports db/prisma.ts —
+    // a module with a top-level `await loadPrismaClient(...)`. This module is
+    // registered in buildSetupOnlyApp() too, the boot path documented as
+    // never touching Prisma and which runs precisely when nothing is
+    // configured yet, so importing the three-lane config here would drag
+    // Prisma into it and could fail that boot outright. setup.ts made the
+    // same swap for the same reason.
+    //
+    // The scope's ceiling is the ADMIN lane rather than the generic IP one,
+    // and this is where ADMIN_RATE_LIMIT actually earns its keep: with
+    // wildcard:false below, @fastify/static declares ~100 hashed asset
+    // routes in this scope and gives this plugin no way to attach per-route
+    // config to them (its internal routeOpts carries no `config` key), so
+    // the plugin-level default is the ONLY lever that reaches them. Leaving
+    // it at the generic 60/IP/minute would mean a cold load of the SPA plus
+    // one hard refresh could 429 the login screen.
+    await app.register(import("@fastify/rate-limit"), {
+        ...ipOnlyRateLimitConfig(),
+        max: ADMIN_RATE_LIMIT.max(),
+        timeWindow: ADMIN_RATE_LIMIT.timeWindow(),
+    });
+    // This module's routes serve static HTML/asset infra, not Zod-validated
+    // JSON — api-design.md's "every route needs a request/response schema"
+    // rule governs the Zod→OpenAPI chain, which these deliberately sit
+    // outside of. Hidden from Swagger up front, same treatment docs-static.ts
+    // gives /docs. (@fastify/static hides its own generated routes already;
+    // this covers the ones declared below.) The hook is registered before any
+    // route in this scope so it sees all of them, and it is scoped to this
+    // encapsulated child, so `url === "/"` can only ever match the root
+    // redirect declared here.
+    app.addHook("onRoute", (routeOptions) => {
+        if (routeOptions.url.startsWith("/velora") || routeOptions.url === "/") {
+            routeOptions.schema = { ...routeOptions.schema, hide: true };
+        }
+    });
+    // Every route below already sits on the ADMIN lane by way of the
+    // plugin-level default registered above, so no per-route `config` is
+    // attached: repeating the same numbers on each route would suggest the
+    // asset routes (which cannot carry it) are on a different lane than they
+    // are.
+    // VELORA_ADMIN=off (the hosted demo's setting): the SPA is not served,
+    // but /velora/* still answers a 404 that NAMES the flag rather than the
+    // app-wide "route not found" — an operator who set the flag on one host
+    // and forgot it on another gets told why, which is the same
+    // 404-with-cause contract the missing-bundle branch honours. `/` is
+    // deliberately NOT registered in this branch, so the root keeps today's
+    // headless-bridge behaviour exactly.
+    if (!isAdminUiEnabled()) {
+        const message = "The admin UI is disabled on this instance (VELORA_ADMIN=off). The API is unaffected; " +
+            "unset VELORA_ADMIN (or set it to anything other than `off`) to serve the admin at /velora/.";
+        app.get("/velora", async (req, reply) => sendDegraded(req, reply, message));
+        app.get("/velora/", async (req, reply) => sendDegraded(req, reply, message));
+        app.get("/velora/*", async (req, reply) => sendDegraded(req, reply, message));
+        app.log.info("[admin-static] VELORA_ADMIN=off — the admin SPA is not served");
+        return;
+    }
+    const { dir: adminDir, invalidOverride } = resolveAdminDir();
+    // Exact-path redirects. Fastify 5's Reply#redirect signature is
+    // (url, code), not (code, url) — verified against this repo's installed
+    // fastify@5.8.5 source (lib/reply.js), which differs from older majors.
+    // Both are registered before the missing-bundle branch returns: a
+    // degraded instance should still send you to the URL that explains
+    // itself, rather than silently keeping the pre-S184 root behaviour.
+    app.get("/velora", async (_req, reply) => reply.redirect("/velora/", 302));
+    app.get("/", async (_req, reply) => reply.redirect("/velora/", 302));
+    if (!adminDir) {
+        const message = invalidOverride
+            ? `VELORA_ADMIN_DIR is set to "${invalidOverride}" but it is not usable (it must resolve to a ` +
+                "directory containing index.html). Fix the override or unset VELORA_ADMIN_DIR to fall back " +
+                "to the built-in bundle location."
+            : "The admin bundle is not installed. Expected it inside the server build " +
+                "(dist/admin-bundle) or at VELORA_ADMIN_DIR. Build with `turbo run build` to produce it.";
+        app.get("/velora/", async (req, reply) => sendDegraded(req, reply, message));
+        app.get("/velora/*", async (req, reply) => sendDegraded(req, reply, message));
+        app.log.warn("[admin-static] no admin bundle found — /velora/* will answer 404-with-cause");
+        return;
+    }
+    // Registered directly on this scope (not in a further encapsulated
+    // child): unlike docs-static.ts, this module needs no setNotFoundHandler
+    // at all — every path under /velora/ is owned by a real route, so nothing
+    // here can leak a 404 shape onto /api/*.
+    //
+    // wildcard: false makes @fastify/static enumerate the bundle at
+    // registration and declare one route per file (plus HEAD), leaving deep
+    // links unmatched so the SPA fallback below owns them. The bundle is
+    // immutable and hashed, so a boot-time enumeration is exactly right.
+    //
+    // index: false is load-bearing, not cosmetic. With the default
+    // (index.html), the wildcard:false branch ALSO declares a route for each
+    // index directory — here "/velora/" — which collides head-on with the
+    // explicit "/velora/" route below (FST_ERR_DUPLICATED_ROUTE at boot).
+    // Turning it off keeps this module's own routes as the single owner of
+    // the SPA entry point, so the index is served through one code path
+    // whether it was requested at /velora/ or reached by fallback.
+    //
+    // decorateReply: false, as in docs-static.ts — nothing here needs
+    // reply.sendFile, and not decorating keeps this registration from ever
+    // colliding with another @fastify/static mount on the same instance.
+    await app.register(fastifyStatic, {
+        root: adminDir,
+        prefix: "/velora/",
+        wildcard: false,
+        index: false,
+        decorateReply: false,
+    });
+    // The SPA entry point, and the fallback that makes client-side routing
+    // survive a refresh or a pasted deep link. decorateReply: false means
+    // reply.sendFile isn't available here (docs-static.ts reads its 404.html
+    // the same way) — read index.html and send it per request (a single
+    // small file behind a rate limit). NOTE: unlike the docs bundle, a
+    // bundle swapped underneath a RUNNING server needs a restart — with
+    // wildcard: false the asset routes are enumerated once at registration,
+    // so a new build's hashed assets would have no routes.
+    const indexHtml = join(adminDir, "index.html");
+    const sendIndex = (reply) => reply.type("text/html").send(readFileSync(indexHtml));
+    app.get("/velora/", async (_req, reply) => sendIndex(reply));
+    app.get("/velora/*", async (_req, reply) => sendIndex(reply));
+}

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

@@ -0,0 +1,2 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+export declare const apiKeyRoutes: FastifyPluginAsyncZod;

package/dist/routes/api-keys.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { ApiErrorSchema, ApiKeyListQuerySchema, ApiKeyListResponseSchema, CreateApiKeyRequestSchema, CreateApiKeyResponseSchema, RevokeApiKeyResponseSchema, } from "@velora-cms/api-schemas";
+import { prisma } from "../db/prisma.js";
+import { generateApiKey, hashApiKey } from "../auth/api-keys.js";
+import { requireAdmin } from "../auth/require-auth.js";
+const ApiKeyParamsSchema = z.object({ id: z.string().uuid() });
+// Deliberately reconstructed field by field — keyHash must never ride
+// along by spread (users.ts's toSummary precedent).
+function toSummary(key) {
+    return {
+        id: key.id,
+        name: key.name,
+        scope: key.scope,
+        createdAt: key.createdAt.toISOString(),
+        lastUsedAt: key.lastUsedAt?.toISOString() ?? null,
+        revokedAt: key.revokedAt?.toISOString() ?? null,
+    };
+}
+// Every route here is admin-only, like /api/users — key management is
+// backoffice surface, JWT-gated; the public API these keys unlock is the
+// separate /api/v1 namespace, and a key can never manage keys.
+export const apiKeyRoutes = async (app) => {
+    app.get("/api/api-keys", {
+        onRequest: requireAdmin,
+        schema: {
+            querystring: ApiKeyListQuerySchema,
+            response: {
+                200: ApiKeyListResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+            },
+        },
+    }, async (request) => {
+        const { cursor, limit } = request.query;
+        const rows = await prisma.apiKey.findMany({
+            orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+            take: limit,
+            ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+        });
+        const nextCursor = rows.length === limit ? (rows[rows.length - 1]?.id ?? null) : null;
+        return { items: rows.map(toSummary), nextCursor };
+    });
+    app.post("/api/api-keys", {
+        onRequest: requireAdmin,
+        schema: {
+            body: CreateApiKeyRequestSchema,
+            response: {
+                201: CreateApiKeyResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        // The plaintext exists only in this scope and this response — only
+        // its hash is persisted, so it can never be shown again.
+        const secret = generateApiKey();
+        const row = await prisma.apiKey.create({
+            data: {
+                name: request.body.name,
+                // Zod defaults an omitted scope to "read" — a key can never
+                // become a write key by accident.
+                scope: request.body.scope,
+                keyHash: hashApiKey(secret),
+            },
+        });
+        return reply.code(201).send({ apiKey: toSummary(row), secret });
+    });
+    app.post("/api/api-keys/:id/revoke", {
+        onRequest: requireAdmin,
+        schema: {
+            params: ApiKeyParamsSchema,
+            response: {
+                200: RevokeApiKeyResponseSchema,
+                401: ApiErrorSchema,
+                403: ApiErrorSchema,
+                404: ApiErrorSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const existing = await prisma.apiKey.findUnique({ where: { id: request.params.id } });
+        if (!existing) {
+            return reply.code(404).send({ message: `No API key found for id ${request.params.id}` });
+        }
+        // Idempotent: revoking an already-revoked key returns it unchanged —
+        // the caller's goal (key unusable) is already true, and keeping the
+        // original revokedAt preserves the audit trail.
+        const row = existing.revokedAt
+            ? existing
+            : await prisma.apiKey.update({
+                where: { id: existing.id },
+                data: { revokedAt: new Date() },
+            });
+        return { apiKey: toSummary(row) };
+    });
+};

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

@@ -0,0 +1,2 @@
+import type { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+export declare const apiPlaygroundRoutes: FastifyPluginAsyncZod;