/** * Phase 06 #22 — Tenant-Admin plugins UI. * * Lists installed plugins for the current tenant with capability consent, * enable / disable toggles and a manifest preview. The route is deliberately * scoped (no install dialog, no per-user toggles) — the foundation surfaces * what plugins exist, links manifest-declared settings UIs, and lets tenant * admins approve manifest-declared capabilities before flipping the kill-switch. * * Permission: `app.plugins.use` can view installed plugins and * `app.plugins.manage` can grant or revoke capabilities and enable/disable them. */ import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router"; import { getPluginCapabilityMetadata, isPluginCapabilityName, type PluginCapabilityMetadata, type PluginCapabilityRisk, } from "@toolctrl/plugin-runtime/capabilities"; import { isPluginHookProductionAvailable } from "@toolctrl/plugin-runtime/hooks/registry"; import type { PluginCapability } from "@toolctrl/plugin-runtime/manifest"; import { Form, Link, useActionData, useLoaderData } from "react-router"; import { useTranslation } from "react-i18next"; import { useState } from "react"; import { getTranslations } from "~/locale/i18next.server"; import { useLocaleFormatters } from "~/locale/format"; import { appPath } from "~/utils/app/CanonicalUrlUtils"; import { useRootData } from "~/utils/data/useRootData"; import { getUserPermission, verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService"; import { getTenantIdFromUrl } from "~/utils/services/.server/urlService"; import { getUserInfo, validateCSRFToken } from "~/utils/session.server"; import { getUser } from "~/utils/db/users.db.server"; import { PluginLifecycleError, disablePlugin, enablePlugin, grantPluginCapabilities, isCapabilityGrantScopeSatisfied, listPluginCapabilityGrants, listPluginCapabilityGrantsForPlugins, listPlugins, revokePluginCapabilities, type PluginLifecycleActor, type PluginListItem, } from "~/modules/plugins/services/.server/PluginLifecycleService"; import { getPluginConsentRequirements, isPluginHookConsentName } from "~/modules/plugins/utils/pluginConsentRequirements"; import { parsePluginCapabilityNameArray, readPluginConsentUrlEncodedFormData } from "~/modules/plugins/utils/capabilityConsentPayload.server"; async function createCapabilityReviewDigest(item: Pick, capabilityNames: ReadonlyArray) { const { createCapabilityReviewDigest: createDigest } = await import("~/modules/plugins/utils/capabilityReviewDigest"); return createDigest(item, capabilityNames); } type SerializedPluginCapability = { name: string; scope: PluginCapability["scope"] | null; granted: boolean; grantedAt: string | null; grantedScopeJson: unknown; metadata: SerializedPluginCapabilityMetadata | null; }; type SerializedPluginCapabilityMetadata = Pick; type SerializedPluginItem = { id: string; pluginId: string; version: string; enabled: boolean; capabilities: ReadonlyArray; missingCapabilities: ReadonlyArray; capabilityReviewDigest: string; hasSettingsUi: boolean; manifestJson: string; installedAt: string; }; type LoaderData = { title: string; tenantSlug: string; canManage: boolean; canAudit: boolean; items: ReadonlyArray; }; type ActionData = { ok: boolean; message?: string }; const USE_PERMISSION = "app.plugins.use"; const MANAGE_PERMISSION = "app.plugins.manage"; const AUDIT_PERMISSION = "app.settings.auditTrails.view"; export function formatPluginCapabilityLabel(capability: string, t: (key: string, options?: Record) => string) { if (isPluginHookConsentName(capability)) { return t("settings.plugins.consent.hookLabel", { hook: capability.slice("hook:".length) }); } if (isPluginCapabilityName(capability)) { return t(`settings.plugins.capabilityNames.${capability.replaceAll(".", "_")}`); } return t(`settings.plugins.capabilityNames.${capability.replaceAll(".", "_")}`, { defaultValue: t("settings.plugins.capabilityNames.unknown", { capability }), }); } export const loader = async ({ request, params }: LoaderFunctionArgs) => { const tenantId = await getTenantIdFromUrl(params); await verifyUserHasPermission(request, USE_PERMISSION, tenantId); const [{ t }, info, items] = await Promise.all([getTranslations(request), getUserInfo(request), listPlugins({ tenantId })]); const [managePermission, auditPermission, serializedItems] = await Promise.all([ info.userId ? getUserPermission({ userId: info.userId, permissionName: MANAGE_PERMISSION, tenantId, }) : Promise.resolve(null), info.userId ? getUserPermission({ userId: info.userId, permissionName: AUDIT_PERMISSION, tenantId, }) : Promise.resolve(null), serializePluginItems({ tenantId, items }), ]); const data: LoaderData = { title: `${t("settings.plugins.title")} | ${process.env.APP_NAME}`, tenantSlug: params.tenant ?? "", canManage: Boolean(managePermission?.userPermission), canAudit: Boolean(auditPermission?.userPermission), items: serializedItems, }; return Response.json(data); }; export const action = async ({ request, params }: ActionFunctionArgs) => { const tenantId = await getTenantIdFromUrl(params); await verifyUserHasPermission(request, MANAGE_PERMISSION, tenantId); const { t } = await getTranslations(request); const parsedForm = await readPluginConsentUrlEncodedFormData(request); if (!parsedForm.ok) { return Response.json({ ok: false, message: t("settings.plugins.errors.invalidFormPayload") } satisfies ActionData, { status: 400 }); } const form = parsedForm.formData; await validateCSRFToken(request, { formData: form }); const op = form.get("op"); const pluginRowId = form.get("id"); if (typeof pluginRowId !== "string" || pluginRowId.length === 0) { return Response.json({ ok: false, message: t("settings.plugins.errors.missingPluginId") } satisfies ActionData, { status: 400 }); } const actor = await resolveActor(request); try { if (op === "enable") { await enablePlugin({ tenantId, pluginRowId, actor }); return Response.json({ ok: true } satisfies ActionData); } if (op === "disable") { await disablePlugin({ tenantId, pluginRowId, actor }); return Response.json({ ok: true } satisfies ActionData); } if (op === "revoke") { const submittedPluginId = form.get("pluginId"); const parsedNames = parsePluginCapabilityNameArray(form.getAll("capabilityNames[]")); if (typeof submittedPluginId !== "string" || submittedPluginId.length === 0 || !parsedNames.ok) { return Response.json({ ok: false, message: t("settings.plugins.errors.missingCapabilityRevokeSelection") } satisfies ActionData, { status: 400 }); } const item = (await listPlugins({ tenantId })).find((row) => row.id === pluginRowId); if (!item) { return Response.json({ ok: false, message: t("settings.plugins.errors.pluginNotFound") } satisfies ActionData, { status: 404 }); } if (item.pluginId !== submittedPluginId) { return Response.json({ ok: false, message: t("settings.plugins.errors.staleCapabilityReview") } satisfies ActionData, { status: 409 }); } await revokePluginCapabilities({ tenantId, pluginId: item.pluginId, capabilityNames: parsedNames.capabilityNames, actor }); return Response.json({ ok: true } satisfies ActionData); } if (op === "grant" || op === "grantAndEnable") { const parsedNames = parsePluginCapabilityNameArray(form.getAll("capabilities[]")); if (!parsedNames.ok) { return Response.json({ ok: false, message: t("settings.plugins.errors.missingCapabilitySelection") } satisfies ActionData, { status: 400 }); } const item = (await listPlugins({ tenantId })).find((row) => row.id === pluginRowId); if (!item) { return Response.json({ ok: false, message: t("settings.plugins.errors.pluginNotFound") } satisfies ActionData, { status: 404 }); } if (form.get("capabilitiesReviewed") !== "yes") { return Response.json({ ok: false, message: t("settings.plugins.errors.missingCapabilityReview") } satisfies ActionData, { status: 400 }); } const declaredCapabilities = new Map(getPluginConsentRequirements(item.manifest).map((requirement) => [requirement.name, requirement])); if (parsedNames.capabilityNames.length === 0) { return Response.json({ ok: false, message: t("settings.plugins.errors.missingCapabilitySelection") } satisfies ActionData, { status: 400 }); } const existingGrants = await listPluginCapabilityGrants({ tenantId, pluginId: item.pluginId }); const grantByCapability = new Map(existingGrants.map((grant) => [grant.capabilityName, grant])); const missingCapabilities = getPluginConsentRequirements(item.manifest) .filter((requirement) => { const grant = grantByCapability.get(requirement.name); return !grant || !isCapabilityGrantScopeSatisfied({ declaredScope: requirement.scope ?? null, grantedScopeJson: grant.scopeJson }); }) .map((requirement) => requirement.name); if (!areCapabilityNameSetsEqual(parsedNames.capabilityNames, missingCapabilities)) { return Response.json({ ok: false, message: t("settings.plugins.errors.staleCapabilityReview") } satisfies ActionData, { status: 409 }); } const requestedCapabilities = missingCapabilities; const submittedDigest = form.get("capabilityReviewDigest"); const expectedDigest = await createCapabilityReviewDigest(item, missingCapabilities); if (typeof submittedDigest !== "string" || submittedDigest !== expectedDigest) { return Response.json({ ok: false, message: t("settings.plugins.errors.staleCapabilityReview") } satisfies ActionData, { status: 409 }); } await grantPluginCapabilities({ tenantId, pluginId: item.pluginId, grants: requestedCapabilities.map((name) => ({ capabilityName: name, scopeJson: declaredCapabilities.get(name)?.scope ?? null, })), actor, capabilityReviewDigest: submittedDigest, }); if (op === "grantAndEnable") { await enablePlugin({ tenantId, pluginRowId, actor }); } return Response.json({ ok: true } satisfies ActionData); } return Response.json({ ok: false, message: t("settings.plugins.errors.unknownOperation") } satisfies ActionData, { status: 400 }); } catch (err) { if (err instanceof PluginLifecycleError) { return Response.json( { ok: false, message: t(`settings.plugins.errors.lifecycle.${err.code}`), } satisfies ActionData, { status: getPluginLifecycleErrorStatus(err.code) } ); } throw err; } }; function getPluginLifecycleErrorStatus(code: PluginLifecycleError["code"]): number { if ( code === "signature_key_not_trusted" || code === "signature_key_mismatch" || code === "binary_verification_failed" || code === "capability_unavailable" || code === "production_guard_violation" ) { return 403; } if (code === "not_found" || code === "binary_not_found") { return 404; } if (code === "already_installed" || code === "capability_consent_missing") { return 409; } if (code === "tenant_install_limit_exceeded") { return 429; } return 400; } function areCapabilityNameSetsEqual(left: ReadonlyArray, right: ReadonlyArray): boolean { if (left.length !== right.length) return false; const rightNames = new Set(right); return left.every((name) => rightNames.has(name)); } async function serializePluginItems(args: { tenantId: string; items: ReadonlyArray }): Promise { const { createCapabilityReviewDigest: createDigest } = await import("~/modules/plugins/utils/capabilityReviewDigest"); const grants = await listPluginCapabilityGrantsForPlugins({ tenantId: args.tenantId, pluginIds: args.items.map((row) => row.pluginId), }); const grantsByPluginId = new Map(); for (const grant of grants) { const pluginGrants = grantsByPluginId.get(grant.pluginId) ?? []; pluginGrants.push(grant); grantsByPluginId.set(grant.pluginId, pluginGrants); } return Promise.all( args.items.map(async (row) => { const pluginGrants = grantsByPluginId.get(row.pluginId) ?? []; const grantByCapability = new Map(pluginGrants.map((grant) => [grant.capabilityName, grant])); const capabilities = getPluginConsentRequirements(row.manifest).map((capability) => { const grant = grantByCapability.get(capability.name); const granted = Boolean(grant) && isCapabilityGrantScopeSatisfied({ declaredScope: capability.scope ?? null, grantedScopeJson: grant?.scopeJson }); return { name: capability.name, scope: capability.scope ?? null, granted, grantedAt: grant?.grantedAt.toISOString() ?? null, grantedScopeJson: grant?.scopeJson ?? null, metadata: serializePluginConsentMetadata(capability.name), }; }); const missingCapabilities = capabilities.filter((capability) => !capability.granted).map((capability) => capability.name); return { id: row.id, pluginId: row.pluginId, version: row.version, enabled: row.enabled, capabilities, missingCapabilities, capabilityReviewDigest: createDigest(row, missingCapabilities), hasSettingsUi: Boolean(row.manifest.ui?.settings?.entry), manifestJson: JSON.stringify(row.manifest, null, 2), installedAt: row.installedAt.toISOString(), }; }) ); } function serializePluginConsentMetadata(name: string): SerializedPluginCapabilityMetadata | null { if (isPluginHookConsentName(name)) { const hookName = name.slice("hook:".length); return { risk: "medium", productionAvailable: isPluginHookProductionAvailable(hookName) }; } const metadata = getPluginCapabilityMetadata(name); return metadata ? { risk: metadata.risk, productionAvailable: metadata.productionAvailable } : null; } async function resolveActor(request: Request): Promise { const info = await getUserInfo(request); const user = info.userId ? await getUser(info.userId) : null; const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? null; return { userId: info.userId ?? null, email: user?.email ?? null, ip }; } export default function TenantPluginsRoute() { const data = useLoaderData(); const actionData = useActionData(); const { t } = useTranslation(); const rootData = useRootData(); const formatters = useLocaleFormatters(); const [expanded, setExpanded] = useState(null); const [reviewingCapabilities, setReviewingCapabilities] = useState(null); const [reviewedCapabilities, setReviewedCapabilities] = useState>(() => new Set()); const getCapabilityReviewKey = (item: SerializedPluginItem, capabilityName: string) => `${item.id}:${item.capabilityReviewDigest}:${capabilityName}`; const denyCapabilityReview = (item: SerializedPluginItem) => { setReviewedCapabilities((current) => { const next = new Set(current); for (const capabilityName of item.missingCapabilities) { next.delete(getCapabilityReviewKey(item, capabilityName)); } return next; }); setReviewingCapabilities(null); }; return (

{t("settings.plugins.title")}

{t("settings.plugins.description", { tenantSlug: data.tenantSlug })}

{actionData?.message ? (
{actionData.message}
) : null} {data.items.length === 0 ? (

{t("settings.plugins.empty")}

) : (
    {data.items.map((item) => { const missingCapabilityNames = new Set(item.missingCapabilities); const capabilitiesToReview = item.capabilities.filter((capability) => missingCapabilityNames.has(capability.name)); const unavailableCapabilitiesToReview = capabilitiesToReview.filter((capability) => capability.metadata?.productionAvailable === false); const reviewComplete = unavailableCapabilitiesToReview.length === 0 && item.missingCapabilities.every((capabilityName) => reviewedCapabilities.has(getCapabilityReviewKey(item, capabilityName))); return (
  • {item.pluginId}

    {t("settings.plugins.versionInstalled", { version: item.version, date: formatters.date(item.installedAt, { dateStyle: "medium", timeStyle: "short" }), })}

    {item.enabled ? t("shared.enabled") : t("shared.disabled")} {data.canManage ? ( item.enabled ? (
    {rootData.csrf ? : null}
    ) : item.missingCapabilities.length > 0 ? null : (
    {rootData.csrf ? : null}
    ) ) : null}

    {t("settings.plugins.capabilities")}

    {item.capabilities.length === 0 ? (

    {t("settings.plugins.consent.none")}

    ) : (
      {item.capabilities.map((capability) => (
    • {formatPluginCapabilityLabel(capability.name, t)} {capability.granted ? t("settings.plugins.consent.granted") : t("settings.plugins.consent.missing")}

      {formatPluginCapabilityScope(capability.scope, t)}

      {capability.granted && capability.grantedAt ? (

      {t("settings.plugins.consent.grantedAt", { date: formatters.date(capability.grantedAt, { dateStyle: "medium", timeStyle: "short" }), })}

      ) : null} {data.canManage && capability.granted ? (
      {rootData.csrf ? : null} {t("settings.plugins.consent.revokeDisables")}
      ) : null}
    • ))}
    )} {data.canManage && item.missingCapabilities.length > 0 ? (
    {t("settings.plugins.consent.description")} {reviewingCapabilities === item.id ? (
    {rootData.csrf ? : null}

    {t("settings.plugins.consent.reviewTitle", { pluginId: item.pluginId })}

    {t("settings.plugins.consent.reviewDescription", { version: item.version })}

      {capabilitiesToReview.map((capability) => { const reviewKey = getCapabilityReviewKey(item, capability.name); const label = formatPluginCapabilityLabel(capability.name, t); const unavailable = capability.metadata?.productionAvailable === false; return (
    • {capability.metadata ? (
      {t(`settings.plugins.consent.risk.${capability.metadata.risk}`)} {capability.metadata.productionAvailable ? t("settings.plugins.consent.available") : t("settings.plugins.consent.unavailable")}
      ) : null} {unavailable ? (

      {t("settings.plugins.consent.unavailableDescription")}

      ) : null}

      {formatPluginCapabilityScope(capability.scope, t)}

      {capability.name}
    • ); })}
    ) : null}
    ) : null}
    {item.enabled && item.hasSettingsUi ? ( {t("settings.plugins.openSettings")} ) : null} {data.canAudit ? ( {t("settings.plugins.viewAudit")} ) : null} {expanded === item.id ? (
                        {item.manifestJson}
                      
    ) : null}
  • ); })}
)}
); } function getPluginCapabilityRiskClassName(risk: PluginCapabilityRisk): string { switch (risk) { case "low": return "bg-green-100 text-green-800"; case "medium": return "bg-blue-100 text-blue-800"; case "high": return "bg-amber-100 text-amber-800"; case "critical": return "bg-red-100 text-red-800"; } } function formatPluginCapabilityScope(scope: PluginCapability["scope"] | null, t: (key: string, options?: Record) => string) { if (!scope) { return t("settings.plugins.consent.noScope"); } const parts = [ scope.allowedHosts?.length ? t("settings.plugins.consent.allowedHosts", { hosts: scope.allowedHosts.join(", ") }) : null, scope.keyPattern ? t("settings.plugins.consent.keyPattern", { pattern: scope.keyPattern }) : null, scope.tablePrefix ? t("settings.plugins.consent.tablePrefix", { prefix: scope.tablePrefix }) : null, ].filter(Boolean); return parts.length > 0 ? parts.join(" / ") : t("settings.plugins.consent.noScope"); }