feat(hosts): add instance-wide predefined tag suggestions (#1548)

* feat(hosts): add shared predefined tag suggestions

* style(hosts): format tag catalog routes

src/backend/database/routes/host-tag-routes.ts

@@ -0,0 +1,40 @@
+import type { RequestHandler, Router } from "express";
+import { createCurrentSettingsRepository } from "../repositories/factory.js";
+
+const CATALOG_KEY = "host_tag_catalog";
+
+export function registerHostTagRoutes(
+  router: Router,
+  authenticate: RequestHandler,
+  requireAdmin: RequestHandler,
+): void {
+  router.get("/tags", authenticate, async (_req, res) => {
+    const value = await createCurrentSettingsRepository().get(CATALOG_KEY);
+    res.json({ tags: value ? JSON.parse(value) : [] });
+  });
+
+  router.put("/tags", authenticate, requireAdmin, async (req, res) => {
+    const tags: unknown = req.body?.tags;
+    if (
+      !Array.isArray(tags) ||
+      tags.length > 500 ||
+      tags.some(
+        (tag) =>
+          typeof tag !== "string" || !tag.trim() || tag.trim().length > 100,
+      )
+    ) {
+      res.status(400).json({
+        error: "Expected up to 500 non-empty tags of at most 100 characters",
+      });
+      return;
+    }
+    const normalized = [
+      ...new Set((tags as string[]).map((tag) => tag.trim())),
+    ];
+    await createCurrentSettingsRepository().set(
+      CATALOG_KEY,
+      JSON.stringify(normalized),
+    );
+    res.json({ tags: normalized });
+  });
+}

src/backend/database/routes/host.ts

@@ -53,6 +53,7 @@ import { registerHostFolderRoutes } from "./host-folder-routes.js";
 import { registerHostNetworkRoutes } from "./host-network-routes.js";
 import { registerHostBulkRoutes } from "./host-bulk-routes.js";
 import { registerHostDefaultsRoutes } from "./host-defaults-routes.js";
+import { registerHostTagRoutes } from "./host-tag-routes.js";
 import { registerHostStatusRoutes } from "./host-status-routes.js";
 import {
   applyHostEnrollmentDefaults,
@@ -136,6 +137,12 @@ const permissionManager = PermissionManager.getInstance();
 const authenticateJWT = authManager.createAuthMiddleware();
 const requireDataAccess = authManager.createDataAccessMiddleware();
 
+registerHostTagRoutes(
+  router,
+  authenticateJWT,
+  permissionManager.requirePermission("admin.settings.manage"),
+);
+
 registerHostStatusRoutes(router, {
   authenticateJWT,
   requireAdmin: authManager.createAdminMiddleware(),

src/backend/tests/database/routes/host-tag-routes.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import express from "express";
+import request from "supertest";
+
+const settings = vi.hoisted(() => new Map<string, string>());
+vi.mock("../../../database/repositories/factory.js", () => ({
+  createCurrentSettingsRepository: () => ({
+    get: async (key: string) => settings.get(key) ?? null,
+    set: async (key: string, value: string) => {
+      settings.set(key, value);
+    },
+  }),
+}));
+import { registerHostTagRoutes } from "../../../database/routes/host-tag-routes.js";
+
+function app() {
+  const server = express();
+  server.use(express.json());
+  registerHostTagRoutes(
+    server,
+    (req, res, next) =>
+      req.headers.authorization ? next() : void res.sendStatus(401),
+    (req, res, next) =>
+      req.headers.authorization === "admin" ? next() : void res.sendStatus(403),
+  );
+  return server;
+}
+
+beforeEach(() => settings.clear());
+describe("instance host tag catalog", () => {
+  it("allows authenticated users to read the same admin-managed catalog", async () => {
+    const server = app();
+    await request(server)
+      .put("/tags")
+      .set("Authorization", "admin")
+      .send({ tags: [" Linux ", "Domain Controller", "Linux"] })
+      .expect(200, { tags: ["Linux", "Domain Controller"] });
+    await request(server)
+      .get("/tags")
+      .set("Authorization", "member")
+      .expect(200, { tags: ["Linux", "Domain Controller"] });
+  });
+  it("rejects anonymous reads and non-admin writes", async () => {
+    await request(app()).get("/tags").expect(401);
+    await request(app())
+      .put("/tags")
+      .set("Authorization", "member")
+      .send({ tags: ["test"] })
+      .expect(403);
+    expect(settings.size).toBe(0);
+  });
+  it.each([null, [42], [" "], ["x".repeat(101)], Array(501).fill("tag")])(
+    "rejects invalid catalogs",
+    async (tags) => {
+      await request(app())
+        .put("/tags")
+        .set("Authorization", "admin")
+        .send({ tags })
+        .expect(400);
+      expect(settings.size).toBe(0);
+    },
+  );
+  it("allows clearing suggestions without modifying hosts", async () => {
+    settings.set("host_tag_catalog", '["Linux"]');
+    await request(app())
+      .put("/tags")
+      .set("Authorization", "admin")
+      .send({ tags: [] })
+      .expect(200, { tags: [] });
+  });
+});