Merge pull request #5142 from Dokploy/feat/add-terminal-permission

feat(permissions): add server.terminal to decouple server access from root SSH

apps/dokploy/__test__/permissions/check-permission.test.ts

@@ -126,6 +126,13 @@ describe("member is denied org-level enterprise resources (CVE: bypass via stati
 		await expect(checkPermission(ctx, { server: ["read"] })).rejects.toThrow();
 	});
 
+	it("member is denied server.terminal", async () => {
+		memberToReturn = mockMemberData("member");
+		await expect(
+			checkPermission(ctx, { server: ["terminal"] }),
+		).rejects.toThrow();
+	});
+
 	it("member is denied registry.create", async () => {
 		memberToReturn = mockMemberData("member");
 		await expect(

apps/dokploy/__test__/permissions/resolve-permissions.test.ts

@@ -105,6 +105,7 @@ describe("enterprise resources for static roles", () => {
 		const perms = await resolvePermissions(ctx);
 
 		expect(perms.server.read).toBe(false);
+		expect(perms.server.terminal).toBe(false);
 		expect(perms.registry.read).toBe(false);
 		expect(perms.certificate.read).toBe(false);
 		expect(perms.destination.read).toBe(false);

apps/dokploy/__test__/permissions/server-terminal.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockMemberData = (role: string) => ({
+	id: "member-1",
+	role,
+	userId: "user-1",
+	organizationId: "org-1",
+	accessedProjects: [] as string[],
+	accessedServices: [] as string[],
+	accessedEnvironments: [] as string[],
+	accessedServers: [] as string[],
+	canCreateProjects: false,
+	canDeleteProjects: false,
+	canCreateServices: false,
+	canDeleteServices: false,
+	canCreateEnvironments: false,
+	canDeleteEnvironments: false,
+	canAccessToTraefikFiles: false,
+	canAccessToDocker: false,
+	canAccessToAPI: false,
+	canAccessToSSHKeys: false,
+	canAccessToGitProviders: false,
+	user: { id: "user-1", email: "test@test.com" },
+});
+
+let memberToReturn = mockMemberData("deployer");
+let rolesToReturn: { permission: string }[] = [];
+
+vi.mock("@dokploy/server/db", () => ({
+	db: {
+		query: {
+			member: {
+				findFirst: vi.fn(() => Promise.resolve(memberToReturn)),
+				findMany: vi.fn(() => Promise.resolve([])),
+			},
+			organizationRole: {
+				findFirst: vi.fn(),
+				findMany: vi.fn(() => Promise.resolve(rolesToReturn)),
+			},
+		},
+	},
+}));
+
+vi.mock("@dokploy/server/services/proprietary/license-key", () => ({
+	hasValidLicense: vi.fn(() => Promise.resolve(true)),
+}));
+
+const { checkPermission, resolvePermissions } = await import(
+	"@dokploy/server/services/permission"
+);
+
+const ctx = {
+	user: { id: "user-1" },
+	session: { activeOrganizationId: "org-1" },
+};
+
+const withPermissions = (permissions: Record<string, string[]>) => {
+	rolesToReturn = [{ permission: JSON.stringify(permissions) }];
+};
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	memberToReturn = mockMemberData("deployer");
+	rolesToReturn = [];
+});
+
+describe("server.terminal on custom roles", () => {
+	it("a role with server.read alone cannot open a terminal", async () => {
+		withPermissions({ server: ["read"] });
+
+		await expect(
+			checkPermission(ctx, { server: ["read"] }),
+		).resolves.toBeUndefined();
+		await expect(
+			checkPermission(ctx, { server: ["terminal"] }),
+		).rejects.toThrow();
+
+		const perms = await resolvePermissions(ctx);
+		expect(perms.server.read).toBe(true);
+		expect(perms.server.terminal).toBe(false);
+	});
+
+	it("a role with server.terminal can open a terminal", async () => {
+		withPermissions({ server: ["read", "terminal"] });
+
+		await expect(
+			checkPermission(ctx, { server: ["terminal"] }),
+		).resolves.toBeUndefined();
+
+		const perms = await resolvePermissions(ctx);
+		expect(perms.server.terminal).toBe(true);
+	});
+
+	it("owner and admin keep terminal access", async () => {
+		for (const role of ["owner", "admin"]) {
+			memberToReturn = mockMemberData(role);
+			await expect(
+				checkPermission(ctx, { server: ["terminal"] }),
+			).resolves.toBeUndefined();
+
+			const perms = await resolvePermissions(ctx);
+			expect(perms.server.terminal).toBe(true);
+		}
+	});
+});

apps/dokploy/__test__/wss/authorize.test.ts

@@ -95,10 +95,35 @@ describe("canAccessTerminalOverWss", () => {
 	});
 
 	it("gates a remote server terminal on server access", async () => {
+		mockHasPermission.mockResolvedValue(true);
 		mockGetAccessibleServerIds.mockResolvedValue(new Set(["srv-1"]));
 		expect(await canAccessTerminalOverWss(USER, SESSION, "srv-1")).toBe(true);
 		expect(await canAccessTerminalOverWss(USER, SESSION, "srv-2")).toBe(false);
-		// role lookup must not be needed for the remote path
+		// the remote path must never fall through to the owner/admin local branch
 		expect(mockFindMember).not.toHaveBeenCalled();
 	});
+
+	it("denies a remote server terminal without the server.terminal permission", async () => {
+		// Reaching a server (to deploy on it) must not imply a root shell on it.
+		mockGetAccessibleServerIds.mockResolvedValue(new Set(["srv-1"]));
+		mockHasPermission.mockResolvedValue(false);
+		expect(await canAccessTerminalOverWss(USER, SESSION, "srv-1")).toBe(false);
+		expect(mockHasPermission).toHaveBeenCalledWith(
+			{ user: { id: USER.id }, session: { activeOrganizationId: "org-1" } },
+			{ server: ["terminal"] },
+		);
+	});
+
+	it("allows a remote server terminal with the server.terminal permission", async () => {
+		mockGetAccessibleServerIds.mockResolvedValue(new Set(["srv-1"]));
+		mockHasPermission.mockResolvedValue(true);
+		expect(await canAccessTerminalOverWss(USER, SESSION, "srv-1")).toBe(true);
+	});
+
+	it("does not check permissions for a server the caller cannot access", async () => {
+		mockGetAccessibleServerIds.mockResolvedValue(new Set(["srv-1"]));
+		mockHasPermission.mockResolvedValue(true);
+		expect(await canAccessTerminalOverWss(USER, SESSION, "srv-2")).toBe(false);
+		expect(mockHasPermission).not.toHaveBeenCalled();
+	});
 });

apps/dokploy/components/dashboard/settings/servers/show-servers.tsx

@@ -250,29 +250,30 @@ export const ShowServers = () => {
 																			</div>
 
 																			<TooltipProvider>
-																				{server.sshKeyId && (
-																					<Tooltip>
-																						<TooltipTrigger asChild>
-																							<div>
-																								<TerminalModal
-																									serverId={server.serverId}
-																									asButton={true}
-																								>
-																									<Button
-																										variant="outline"
-																										size="icon"
-																										className="h-9 w-9"
+																				{server.sshKeyId &&
+																					permissions?.server.terminal && (
+																						<Tooltip>
+																							<TooltipTrigger asChild>
+																								<div>
+																									<TerminalModal
+																										serverId={server.serverId}
+																										asButton={true}
 																									>
-																										<Terminal className="h-4 w-4" />
-																									</Button>
-																								</TerminalModal>
-																							</div>
-																						</TooltipTrigger>
-																						<TooltipContent>
-																							<p>Terminal</p>
-																						</TooltipContent>
-																					</Tooltip>
-																				)}
+																										<Button
+																											variant="outline"
+																											size="icon"
+																											className="h-9 w-9"
+																										>
+																											<Terminal className="h-4 w-4" />
+																										</Button>
+																									</TerminalModal>
+																								</div>
+																							</TooltipTrigger>
+																							<TooltipContent>
+																								<p>Terminal</p>
+																							</TooltipContent>
+																						</Tooltip>
+																					)}
 
 																				<Tooltip>
 																					<TooltipTrigger asChild>

apps/dokploy/components/proprietary/roles/manage-custom-roles.tsx

@@ -328,6 +328,10 @@ const ACTION_META: Record<
 			label: "Delete",
 			description: "Remove servers from the organization",
 		},
+		terminal: {
+			label: "Terminal",
+			description: "Open an SSH root shell on remote servers",
+		},
 	},
 	registry: {
 		read: { label: "Read", description: "View configured Docker registries" },
@@ -569,7 +573,7 @@ const ROLE_PRESETS: {
 			envVars: ["read", "write"],
 			projectEnvVars: ["read", "write"],
 			environmentEnvVars: ["read", "write"],
-			server: ["read", "create", "delete"],
+			server: ["read", "create", "delete", "terminal"],
 			registry: ["read", "create", "delete"],
 			certificate: ["read", "create", "delete"],
 			backup: ["read", "create", "delete", "restore"],

apps/dokploy/drizzle/0187_grant_terminal_permission_to_read_roles.sql

@@ -0,0 +1,13 @@
+-- Grant the new "server.terminal" permission to existing custom roles that already have
+-- "server.read", which is the permission that surfaces the terminal in the UI today.
+-- Roles without a "server" entry are deliberately left alone: they never saw the terminal in the
+-- UI, so from now on they are denied at the websocket too.
+UPDATE "organization_role" AS r
+SET "permission" = jsonb_set(
+	r."permission"::jsonb,
+	'{server}',
+	(r."permission"::jsonb->'server') || '["terminal"]'::jsonb
+)::text
+WHERE jsonb_typeof(r."permission"::jsonb->'server') = 'array'
+AND r."permission"::jsonb->'server' @> '["read"]'::jsonb
+AND NOT r."permission"::jsonb->'server' @> '["terminal"]'::jsonb;

apps/dokploy/drizzle/meta/_journal.json

@@ -1310,6 +1310,13 @@
       "when": 1787813846067,
       "tag": "0186_tearful_dragon_man",
       "breakpoints": true
+    },
+    {
+      "idx": 187,
+      "version": "7",
+      "when": 1787937580323,
+      "tag": "0187_grant_terminal_permission_to_read_roles",
+      "breakpoints": true
     }
   ]
 }

apps/dokploy/server/wss/authorize.ts

@@ -62,7 +62,8 @@ export const canAccessDockerOverWss = async (
 
 // Authorizes the host/server SSH terminal opened over a WebSocket. The local
 // host terminal is a root shell on the control-plane host, so it is restricted
-// to owner/admin. A remote server terminal is gated on server access.
+// to owner/admin. A remote server terminal needs server access plus
+// server.terminal.
 export const canAccessTerminalOverWss = async (
 	user: WssUser,
 	session: WssSession,
@@ -75,7 +76,11 @@ export const canAccessTerminalOverWss = async (
 			userId: user.id,
 			activeOrganizationId: session.activeOrganizationId,
 		});
-		return accessible.has(serverId);
+		if (!accessible.has(serverId)) return false;
+
+		return await hasPermission(buildCtx(user, session.activeOrganizationId), {
+			server: ["terminal"],
+		});
 	}
 
 	try {

packages/server/src/lib/access-control.ts

@@ -35,7 +35,7 @@ export const statements = {
 	envVars: ["read", "write"],
 	projectEnvVars: ["read", "write"],
 	environmentEnvVars: ["read", "write"],
-	server: ["read", "create", "delete"],
+	server: ["read", "create", "delete", "terminal"],
 	registry: ["read", "create", "delete"],
 	certificate: ["read", "create", "update", "delete"],
 	backup: ["read", "create", "update", "delete", "restore"],
@@ -104,7 +104,7 @@ export const ownerRole = ac.newRole({
 	envVars: ["read", "write"],
 	projectEnvVars: ["read", "write"],
 	environmentEnvVars: ["read", "write"],
-	server: ["read", "create", "delete"],
+	server: ["read", "create", "delete", "terminal"],
 	registry: ["read", "create", "delete"],
 	certificate: ["read", "create", "update", "delete"],
 	backup: ["read", "create", "update", "delete", "restore"],
@@ -143,7 +143,7 @@ export const adminRole = ac.newRole({
 	envVars: ["read", "write"],
 	projectEnvVars: ["read", "write"],
 	environmentEnvVars: ["read", "write"],
-	server: ["read", "create", "delete"],
+	server: ["read", "create", "delete", "terminal"],
 	registry: ["read", "create", "delete"],
 	certificate: ["read", "create", "update", "delete"],
 	backup: ["read", "create", "update", "delete", "restore"],