@n8n/frontend-module-type-availability-policies 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ The descriptor `id` must match the backend module id
 (`packages/cli/src/modules/type-availability-policies`). Both `settings.activeModules` and
 `/rest/module-settings` are keyed by that string, and a mismatch fails silently.
 
-The module is license-gated on `feat:nodeTypePolicies` and is not a default module. Enable it
+The module is license-gated on `feat:typeAvailabilityPolicies` and is not a default module. Enable it
 in a dev instance with `N8N_ENABLED_MODULES=type-availability-policies`.
 
 `useTypeAvailabilityPoliciesStore` answers whether a project may use a node type. The store is
@@ -27,10 +27,18 @@ and on a cold tree turbo builds them first.
 for one node type. `isNodeTypeRestricted(type)` is the plain predicate for a list of nodes. The
 shell reads restriction through these and never through the store directly.
 
-`ContactInstanceAdminModal` lists the instance owners with a mail link. `RestrictedNodePopover` is the
-explanation for a row in a list: the lock trigger, the hover-opened popover and the dialog. The caller
-passes the row element and whether the row is keyboard-active. The shell renders both where a
-restricted node appears; the module owns their copy and behaviour.
+`ContactInstanceAdminModal` lists the instance owners with a mail link. The surfaces below render it
+as a sibling of their own content, so a popover that closes never unmounts the open dialog.
+`RestrictedNodePopover` is the explanation for a row in a list: the lock trigger, the hover-opened
+popover and the dialog. The caller passes the row element and whether the row is keyboard-active.
+`RestrictedNodePanel` is the builder-facing explanation of a blocked node in the NDV, with the
+contact and replace actions. The shell renders the popover and the panel where a restricted node
+appears; the module owns their copy and behaviour.
+
+`getPolicyViolations(error)` reads the structured violations off a refused save, publish or run,
+and `PolicyViolationList` groups them by scope and lists each blocked node or credential type,
+with an optional jump. The shell resolves display names and the nodes to jump to, because only
+it holds the open workflow.
 
 `packages/@n8n/module-cli/frontend-module-guide.md` holds the descriptor contract, the
 registration points, the import boundaries and the setup a module needs to render UI.

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@n8n/frontend-module-type-availability-policies",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@n8n/api-types": "1.41.0",
-    "@n8n/design-system": "2.40.0",
-    "@n8n/frontend-module-sdk": "0.11.0",
-    "@n8n/i18n": "2.41.0",
-    "@n8n/rest-api-client": "2.41.0",
-    "@n8n/stores": "2.41.0",
+    "@n8n/api-types": "1.42.0",
+    "@n8n/design-system": "2.41.0",
+    "@n8n/frontend-module-sdk": "0.12.0",
+    "@n8n/i18n": "2.42.0",
+    "@n8n/rest-api-client": "2.42.0",
+    "@n8n/stores": "2.42.0",
+    "@n8n/utils": "1.49.0",
     "@vueuse/core": "^14.3.0",
     "pinia": "^2.2.4",
     "vue": "^3.5.13"
@@ -24,7 +25,7 @@
     "@n8n/frontend-vite-config": "0.1.0",
     "@n8n/playwright-janitor": "0.1.0",
     "@n8n/typescript-config": "1.12.0",
-    "@n8n/vitest-config": "1.22.0",
+    "@n8n/vitest-config": "1.23.0",
     "@pinia/testing": "^0.1.6",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/user-event": "^14.6.1",
@@ -35,7 +36,7 @@
     "unplugin-icons": "^23.0.1",
     "vite": "^8.0.2",
     "vite-svg-loader": "5.1.0",
-    "vitest": "^4.1.9",
+    "vitest": "5.0.1",
     "vue-tsc": "^2.2.8"
   },
   "license": "SEE LICENSE IN LICENSE.md",

package/src/components/ContactInstanceAdminModal.test.ts

@@ -33,7 +33,7 @@ const owner = {
 const member = { ...owner, id: 'member-1', fullName: 'Bob Builder', role: ROLE.Member } as IUser;
 
 const renderComponent = createComponentRenderer(ContactInstanceAdminModal, {
-	props: { open: true, description: 'Ask for the Slack node.', mailSubject: 'Access request' },
+	props: { open: true, nodeTypeName: 'Slack' },
 });
 
 function setup(allUsers: IUser[], fetchUsers = vi.fn().mockResolvedValue(undefined)) {
@@ -45,7 +45,7 @@ function setup(allUsers: IUser[], fetchUsers = vi.fn().mockResolvedValue(undefin
 }
 
 describe('ContactInstanceAdminModal', () => {
-	it('lists the owners with a mailto link and shows the description', async () => {
+	it('lists the owners with a mailto link and builds the copy from the node type name', async () => {
 		const usersStore = setup([owner, member]);
 		const { findByTestId, getByText } = renderComponent();
 
@@ -56,9 +56,9 @@ describe('ContactInstanceAdminModal', () => {
 		expect(list).not.toHaveTextContent('Bob Builder');
 		expect(getByText('ada@example.com').closest('a')).toHaveAttribute(
 			'href',
-			'mailto:ada@example.com?subject=Access%20request',
+			'mailto:ada@example.com?subject=Access%20request%20for%20the%20Slack%20node',
 		);
-		expect(getByText('Ask for the Slack node.')).toBeInTheDocument();
+		expect(getByText(/request access to 'Slack'/)).toBeInTheDocument();
 	});
 
 	it('keeps loading until the latest owner lookup resolves after a reopen', async () => {

package/src/components/ContactInstanceAdminModal.vue

@@ -5,9 +5,8 @@ import { useI18n } from '@n8n/i18n';
 import { useUsersStore } from '@n8n/stores/users.store';
 import { computed, ref, watch } from 'vue';
 
-const props = defineProps<{
-	description: string;
-	mailSubject?: string;
+const { nodeTypeName } = defineProps<{
+	nodeTypeName: string;
 }>();
 
 const open = defineModel<boolean>('open', { default: false });
@@ -18,6 +17,17 @@ const usersStore = useUsersStore();
 const isLoading = ref(false);
 let lookupId = 0;
 
+const description = computed(() =>
+	i18n.baseText('typeAvailabilityPolicies.contactAdmin.description', {
+		interpolate: { nodeType: nodeTypeName },
+	}),
+);
+const mailSubject = computed(() =>
+	i18n.baseText('typeAvailabilityPolicies.contactAdmin.mailSubject', {
+		interpolate: { nodeType: nodeTypeName },
+	}),
+);
+
 const owners = computed(() =>
 	usersStore.allUsers.filter(
 		(user) => user.role === ROLE.Owner && !user.isPendingUser && Boolean(user.email),
@@ -39,8 +49,7 @@ watch(
 );
 
 function mailtoHref(email: string): string {
-	const subject = props.mailSubject ? `?subject=${encodeURIComponent(props.mailSubject)}` : '';
-	return `mailto:${email}${subject}`;
+	return `mailto:${email}?subject=${encodeURIComponent(mailSubject.value)}`;
 }
 </script>
 

package/src/components/RestrictedNodePanel.test.ts

@@ -0,0 +1,68 @@
+import { createComponentRenderer } from '@n8n/frontend-test-utils';
+import { createTestingPinia } from '@pinia/testing';
+import { fireEvent } from '@testing-library/vue';
+import { setActivePinia } from 'pinia';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import RestrictedNodePanel from './RestrictedNodePanel.vue';
+
+const renderComponent = createComponentRenderer(RestrictedNodePanel, {
+	props: { nodeTypeName: 'Slack' },
+	global: {
+		stubs: {
+			ContactInstanceAdminModal: {
+				props: ['open', 'nodeTypeName'],
+				template:
+					'<div v-if="open" data-test-id="contact-instance-admin-modal">{{ nodeTypeName }}</div>',
+			},
+		},
+	},
+});
+
+describe('RestrictedNodePanel', () => {
+	beforeEach(() => {
+		setActivePinia(createTestingPinia());
+	});
+
+	it('names the node type and the blocking scope', () => {
+		const { getByTestId } = renderComponent({ props: { scope: 'instance' } });
+
+		expect(getByTestId('node-restricted-panel')).toHaveTextContent(
+			"An administrator blocked 'Slack' on this instance. Contact an instance admin or replace the node to continue.",
+		);
+	});
+
+	it('renders a missing scope generically', () => {
+		const { getByTestId } = renderComponent();
+
+		expect(getByTestId('node-restricted-panel')).toHaveTextContent(
+			"An administrator blocked 'Slack'. Contact an instance admin or replace the node to continue.",
+		);
+	});
+
+	it('hides the replace action and drops it from the copy', () => {
+		const { getByTestId, queryByTestId } = renderComponent({ props: { showReplace: false } });
+
+		expect(queryByTestId('node-restricted-replace')).not.toBeInTheDocument();
+		expect(getByTestId('node-restricted-panel')).toHaveTextContent(
+			"An administrator blocked 'Slack'. Contact an instance admin to continue.",
+		);
+	});
+
+	it('opens the contact-admin dialog for this node type', async () => {
+		const { getByTestId, queryByTestId } = renderComponent();
+
+		expect(queryByTestId('contact-instance-admin-modal')).not.toBeInTheDocument();
+		await fireEvent.click(getByTestId('node-restricted-contact-admin'));
+
+		expect(getByTestId('contact-instance-admin-modal')).toHaveTextContent('Slack');
+	});
+
+	it('emits replaceNode from the replace action', async () => {
+		const { getByTestId, emitted } = renderComponent();
+
+		await fireEvent.click(getByTestId('node-restricted-replace'));
+
+		expect(emitted('replaceNode')).toHaveLength(1);
+	});
+});

package/src/components/RestrictedNodePanel.vue

@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import type { NodeTypeAvailabilityScope } from '@n8n/api-types';
+import { N8nButton, N8nIcon, N8nText } from '@n8n/design-system';
+import { useI18n, type BaseTextKey } from '@n8n/i18n';
+import { computed, ref } from 'vue';
+
+import ContactInstanceAdminModal from './ContactInstanceAdminModal.vue';
+
+const {
+	nodeTypeName,
+	scope,
+	showReplace = true,
+} = defineProps<{
+	nodeTypeName: string;
+	scope?: NodeTypeAvailabilityScope;
+	showReplace?: boolean;
+}>();
+
+const emit = defineEmits<{ replaceNode: [] }>();
+
+const DESCRIPTION_KEY: Record<NodeTypeAvailabilityScope, BaseTextKey> = {
+	instance: 'typeAvailabilityPolicies.restrictedNode.description.instance',
+	project: 'typeAvailabilityPolicies.restrictedNode.description.project',
+};
+
+const i18n = useI18n();
+
+const isContactAdminOpen = ref(false);
+
+// The next step is interpolated into the description, so each locale controls the sentence order.
+const description = computed(() => {
+	const nextStep = i18n.baseText(
+		showReplace
+			? 'typeAvailabilityPolicies.restrictedNode.nextStep.replace'
+			: 'typeAvailabilityPolicies.restrictedNode.nextStep.contact',
+	);
+	return i18n.baseText(
+		scope ? DESCRIPTION_KEY[scope] : 'typeAvailabilityPolicies.restrictedNode.description.generic',
+		{ interpolate: { nodeType: nodeTypeName, nextStep } },
+	);
+});
+</script>
+
+<template>
+	<div :class="$style.panel" data-test-id="node-restricted-panel">
+		<N8nIcon icon="lock" :class="$style.icon" />
+		<N8nText size="large" color="text-dark" bold :class="$style.title">
+			{{ i18n.baseText('typeAvailabilityPolicies.restrictedNode.title') }}
+		</N8nText>
+		<N8nText :class="$style.description">{{ description }}</N8nText>
+		<div :class="$style.actions">
+			<N8nButton
+				variant="solid"
+				size="small"
+				icon="mail"
+				data-test-id="node-restricted-contact-admin"
+				@click="isContactAdminOpen = true"
+			>
+				{{ i18n.baseText('typeAvailabilityPolicies.restrictedNode.contactAdmin') }}
+			</N8nButton>
+			<N8nButton
+				v-if="showReplace"
+				variant="subtle"
+				size="small"
+				icon="arrow-left-right"
+				data-test-id="node-restricted-replace"
+				@click="emit('replaceNode')"
+			>
+				{{ i18n.baseText('typeAvailabilityPolicies.restrictedNode.replaceNode') }}
+			</N8nButton>
+		</div>
+		<ContactInstanceAdminModal v-model:open="isContactAdminOpen" :node-type-name="nodeTypeName" />
+	</div>
+</template>
+
+<style lang="scss" module>
+.panel {
+	height: 75%;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	justify-content: center;
+	padding: var(--spacing--2xs);
+	text-align: center;
+	line-height: var(--line-height--md);
+}
+
+.icon {
+	color: var(--color--text--tint-2);
+	font-size: var(--font-size--2xl);
+}
+
+.title {
+	margin-top: var(--spacing--sm);
+	margin-bottom: var(--spacing--xs);
+}
+
+.description {
+	margin-bottom: var(--spacing--2xs);
+}
+
+.actions {
+	display: flex;
+	gap: var(--spacing--2xs);
+}
+</style>

package/src/components/RestrictedNodePopover.test.ts

@@ -1,7 +1,7 @@
 import { createComponentRenderer } from '@n8n/frontend-test-utils';
-import { screen } from '@testing-library/vue';
+import { screen, waitFor } from '@testing-library/vue';
 import userEvent from '@testing-library/user-event';
-import { describe, it, expect } from 'vitest';
+import { afterEach, beforeEach, describe, it, expect } from 'vitest';
 
 import RestrictedNodePopover from './RestrictedNodePopover.vue';
 
@@ -13,9 +13,9 @@ const renderComponent = createComponentRenderer(RestrictedNodePopover, {
 	global: {
 		stubs: {
 			ContactInstanceAdminModal: {
-				props: ['open', 'description'],
+				props: ['open', 'nodeTypeName'],
 				template:
-					'<div v-if="open" data-test-id="contact-instance-admin-modal">{{ description }}</div>',
+					'<div v-if="open" data-test-id="contact-instance-admin-modal">{{ nodeTypeName }}</div>',
 			},
 		},
 	},
@@ -24,6 +24,18 @@ const renderComponent = createComponentRenderer(RestrictedNodePopover, {
 const renderPopover = (props: Record<string, unknown>) => renderComponent({ props });
 
 describe('RestrictedNodePopover', () => {
+	/** The list row the popover anchors to. It lives outside the rendered component. */
+	let anchor: HTMLDivElement;
+
+	beforeEach(() => {
+		anchor = document.createElement('div');
+		document.body.appendChild(anchor);
+	});
+
+	afterEach(() => {
+		anchor.remove();
+	});
+
 	it('renders only the lock while the row is neither hovered nor active', () => {
 		renderPopover({ active: false });
 
@@ -53,8 +65,6 @@ describe('RestrictedNodePopover', () => {
 	});
 
 	it('opens when the anchor row is hovered and stays open while the pointer is on the popover', async () => {
-		const anchor = document.createElement('div');
-		document.body.appendChild(anchor);
 		renderPopover({ anchor });
 
 		await userEvent.hover(anchor);
@@ -63,7 +73,6 @@ describe('RestrictedNodePopover', () => {
 		await userEvent.unhover(anchor);
 
 		expect(screen.getByTestId('node-restricted-popover')).toBeInTheDocument();
-		anchor.remove();
 	});
 
 	it('opens the contact-admin dialog for this node type', async () => {
@@ -74,4 +83,19 @@ describe('RestrictedNodePopover', () => {
 
 		expect(screen.getByTestId('contact-instance-admin-modal')).toHaveTextContent('Gmail');
 	});
+
+	it('keeps the dialog open after the pointer leaves the row and the popover', async () => {
+		renderPopover({ anchor });
+
+		await userEvent.hover(anchor);
+		const popover = await screen.findByTestId('node-restricted-popover');
+		await userEvent.click(screen.getByTestId('node-restricted-contact-admin'));
+		await userEvent.unhover(popover);
+		await userEvent.unhover(anchor);
+		await waitFor(() =>
+			expect(screen.queryByTestId('node-restricted-popover')).not.toBeInTheDocument(),
+		);
+
+		expect(screen.getByTestId('contact-instance-admin-modal')).toHaveTextContent('Gmail');
+	});
 });

package/src/components/RestrictedNodePopover.vue

@@ -5,6 +5,7 @@ import { useI18n, type BaseTextKey } from '@n8n/i18n';
 import { unrefElement, useElementHover, type MaybeElement } from '@vueuse/core';
 import { computed, ref } from 'vue';
 
+import { SCOPE_LABEL_KEY } from '../type-availability-policies.constants';
 import ContactInstanceAdminModal from './ContactInstanceAdminModal.vue';
 
 const props = defineProps<{
@@ -19,11 +20,6 @@ const props = defineProps<{
 /** Leaving waits this long before closing, so the pointer can cross the gap to the popover. */
 const HOVER_GRACE_MS = 200;
 
-const SCOPE_TITLE_KEY: Record<NodeTypeAvailabilityScope, BaseTextKey> = {
-	instance: 'typeAvailabilityPolicies.restrictedNode.scope.instance',
-	project: 'typeAvailabilityPolicies.restrictedNode.scope.project',
-};
-
 const i18n = useI18n();
 
 const anchorElement = computed(() => unrefElement(props.anchor) ?? undefined);
@@ -36,11 +32,9 @@ const isContactAdminOpen = ref(false);
 
 const scopeKey = computed<BaseTextKey>(
 	() =>
-		(props.scope && SCOPE_TITLE_KEY[props.scope]) ??
+		(props.scope && SCOPE_LABEL_KEY[props.scope]) ??
 		'typeAvailabilityPolicies.restrictedNode.title',
 );
-
-const interpolate = computed(() => ({ nodeType: props.nodeTypeName }));
 </script>
 
 <template>
@@ -83,19 +77,8 @@ const interpolate = computed(() => ({ nodeType: props.nodeTypeName }));
 				</div>
 			</template>
 		</N8nPopover>
-		<ContactInstanceAdminModal
-			v-model:open="isContactAdminOpen"
-			:description="
-				i18n.baseText('typeAvailabilityPolicies.restrictedNode.contactAdmin.description', {
-					interpolate,
-				})
-			"
-			:mail-subject="
-				i18n.baseText('typeAvailabilityPolicies.restrictedNode.contactAdmin.mailSubject', {
-					interpolate,
-				})
-			"
-		/>
+		<!-- A sibling of the popover: its content unmounts on close and must not take the dialog with it. -->
+		<ContactInstanceAdminModal v-model:open="isContactAdminOpen" :node-type-name="nodeTypeName" />
 	</span>
 </template>
 

package/src/index.ts

@@ -5,5 +5,7 @@ export {
 	isNodeTypeRestricted,
 	useNodeTypeRestriction,
 } from './composables/useNodeTypeRestriction';
-export { default as ContactInstanceAdminModal } from './components/ContactInstanceAdminModal.vue';
 export { default as RestrictedNodePopover } from './components/RestrictedNodePopover.vue';
+export { default as RestrictedNodePanel } from './components/RestrictedNodePanel.vue';
+export { getPolicyViolations } from './policy-violations/policyViolations';
+export { default as PolicyViolationList } from './policy-violations/PolicyViolationList.vue';

package/src/policy-violations/PolicyViolationList.test.ts

@@ -0,0 +1,124 @@
+import type { PolicyViolation } from '@n8n/api-types';
+import { createComponentRenderer } from '@n8n/frontend-test-utils';
+import userEvent from '@testing-library/user-event';
+import { within } from '@testing-library/vue';
+import { describe, expect, it } from 'vitest';
+
+import PolicyViolationList from './PolicyViolationList.vue';
+
+const SLACK_NODE_TYPE = 'n8n-nodes-base.slack';
+const TELEGRAM_NODE_TYPE = 'n8n-nodes-base.telegram';
+const GITHUB_CREDENTIAL_TYPE = 'githubApi';
+
+function nodeTypeViolation(subject: string, scope: string): PolicyViolation {
+	return {
+		kind: 'node-type-unavailable',
+		checkId: 'node-type-availability',
+		message: `Node type "${subject}" is blocked`,
+		subject,
+		subjectType: 'nodeType',
+		scope,
+	};
+}
+
+const slackOnInstance = nodeTypeViolation(SLACK_NODE_TYPE, 'instance');
+const telegramInProject = nodeTypeViolation(TELEGRAM_NODE_TYPE, 'project');
+
+const githubCredentialOnInstance: PolicyViolation = {
+	kind: 'credential-type-unavailable',
+	checkId: 'credential-type-availability',
+	message: `Credential type "${GITHUB_CREDENTIAL_TYPE}" is blocked by an instance policy`,
+	subject: GITHUB_CREDENTIAL_TYPE,
+	subjectType: 'credentialType',
+	scope: 'instance',
+};
+
+const renderComponent = createComponentRenderer(PolicyViolationList, {
+	props: { violations: [slackOnInstance] },
+});
+
+function groupTexts(groups: HTMLElement[]) {
+	return groups.map((group) =>
+		within(group)
+			.getAllByTestId('policy-violation')
+			.map((line) => line.textContent?.trim()),
+	);
+}
+
+describe('PolicyViolationList', () => {
+	it('groups the violations under one heading for each scope, instance first', () => {
+		const { getAllByTestId } = renderComponent({
+			props: {
+				violations: [telegramInProject, slackOnInstance, githubCredentialOnInstance],
+			},
+		});
+
+		expect(getAllByTestId('policy-violation-scope').map((heading) => heading.textContent)).toEqual([
+			'Restricted on this instance',
+			'Restricted in this project',
+		]);
+		expect(groupTexts(getAllByTestId('policy-violation-group'))).toEqual([
+			[`${SLACK_NODE_TYPE} node`, `${GITHUB_CREDENTIAL_TYPE} credential`],
+			[`${TELEGRAM_NODE_TYPE} node`],
+		]);
+	});
+
+	it('names each type by the display name the host resolved', () => {
+		const labels: Record<string, string> = { [SLACK_NODE_TYPE]: 'Slack', githubApi: 'GitHub API' };
+		const { getAllByTestId } = renderComponent({
+			props: {
+				violations: [slackOnInstance, githubCredentialOnInstance],
+				labelOf: ({ subject }: PolicyViolation) => (subject ? labels[subject] : undefined),
+			},
+		});
+
+		expect(getAllByTestId('policy-violation').map((line) => line.textContent?.trim())).toEqual([
+			'Slack node',
+			'GitHub API credential',
+		]);
+	});
+
+	it('shows the backend message for an unknown kind, and the raw heading for an unknown scope', () => {
+		const deprecated = { ...slackOnInstance, kind: 'node-type-deprecated', scope: 'team' };
+		const withoutScope: PolicyViolation = {
+			kind: 'workflow-start-denied',
+			checkId: 'workflow-start',
+			message: 'This project cannot start workflows',
+		};
+		const { getAllByTestId } = renderComponent({
+			props: { violations: [withoutScope, deprecated] },
+		});
+
+		expect(getAllByTestId('policy-violation-scope').map((heading) => heading.textContent)).toEqual([
+			'team',
+		]);
+		expect(groupTexts(getAllByTestId('policy-violation-group'))).toEqual([
+			[deprecated.message],
+			['This project cannot start workflows'],
+		]);
+	});
+
+	it('lists a repeated violation once', () => {
+		const { getAllByTestId } = renderComponent({
+			props: { violations: [slackOnInstance, { ...slackOnInstance }] },
+		});
+
+		expect(getAllByTestId('policy-violation')).toHaveLength(1);
+	});
+
+	it('makes only a jumpable type a link and emits its violation', async () => {
+		const { getAllByTestId, emitted } = renderComponent({
+			props: {
+				violations: [slackOnInstance, githubCredentialOnInstance, telegramInProject],
+				isJumpable: ({ subject }: PolicyViolation) => subject !== TELEGRAM_NODE_TYPE,
+			},
+		});
+
+		const jumps = getAllByTestId('policy-violation-jump');
+		expect(jumps).toHaveLength(2);
+
+		await userEvent.click(jumps[1]);
+
+		expect(emitted().jump).toEqual([[githubCredentialOnInstance]]);
+	});
+});

package/src/policy-violations/PolicyViolationList.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { PolicyViolation } from '@n8n/api-types';
+import { N8nText } from '@n8n/design-system';
+import { useI18n, type BaseTextKey } from '@n8n/i18n';
+
+import { isRestrictionScope, SCOPE_LABEL_KEY } from '../type-availability-policies.constants';
+
+const props = withDefaults(
+	defineProps<{
+		violations: PolicyViolation[];
+		isJumpable?: (violation: PolicyViolation) => boolean;
+		labelOf?: (violation: PolicyViolation) => string | undefined;
+	}>(),
+	{ isJumpable: () => false, labelOf: () => undefined },
+);
+
+const emit = defineEmits<{ jump: [violation: PolicyViolation] }>();
+
+const i18n = useI18n();
+
+const NAME_KEY_BY_KIND: Record<string, BaseTextKey | undefined> = {
+	'node-type-unavailable': 'typeAvailabilityPolicies.violations.nodeType',
+	'credential-type-unavailable': 'typeAvailabilityPolicies.violations.credentialType',
+};
+
+const SCOPE_ORDER = ['instance', 'project'];
+
+type Item = { key: string; text: string; violation: PolicyViolation; jumpable: boolean };
+type Group = { scope: string | undefined; heading: string | undefined; items: Item[] };
+
+function itemText(violation: PolicyViolation): string {
+	const { kind, subject, message } = violation;
+	const key = NAME_KEY_BY_KIND[kind];
+	if (!subject || !key) return message;
+
+	return i18n.baseText(key, { interpolate: { name: props.labelOf(violation) ?? subject } });
+}
+
+function scopeHeading(scope: string | undefined): string | undefined {
+	if (!scope) return undefined;
+
+	return isRestrictionScope(scope) ? i18n.baseText(SCOPE_LABEL_KEY[scope]) : scope;
+}
+
+function scopeRank(scope: string | undefined): number {
+	if (!scope) return SCOPE_ORDER.length + 1;
+
+	const index = SCOPE_ORDER.indexOf(scope);
+	return index === -1 ? SCOPE_ORDER.length : index;
+}
+
+const groups = computed(() => {
+	const byScope = new Map<string | undefined, Group>();
+
+	for (const violation of props.violations) {
+		const text = itemText(violation);
+		const key = `${violation.subjectType ?? ''}:${violation.subject ?? ''}:${text}`;
+
+		let group = byScope.get(violation.scope);
+		if (!group) {
+			group = { scope: violation.scope, heading: scopeHeading(violation.scope), items: [] };
+			byScope.set(violation.scope, group);
+		}
+
+		if (group.items.some((item) => item.key === key)) continue;
+		group.items.push({ key, text, violation, jumpable: props.isJumpable(violation) });
+	}
+
+	return [...byScope.values()].sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope));
+});
+</script>
+
+<template>
+	<div :class="$style.list">
+		<section
+			v-for="group in groups"
+			:key="group.scope ?? ''"
+			:class="$style.group"
+			data-test-id="policy-violation-group"
+		>
+			<N8nText
+				v-if="group.heading"
+				tag="p"
+				size="small"
+				color="text-light"
+				data-test-id="policy-violation-scope"
+			>
+				{{ group.heading }}
+			</N8nText>
+			<ul :class="$style.items">
+				<li
+					v-for="item in group.items"
+					:key="item.key"
+					:class="$style.item"
+					data-test-id="policy-violation"
+				>
+					<button
+						v-if="item.jumpable"
+						type="button"
+						:class="$style.jump"
+						:title="i18n.baseText('typeAvailabilityPolicies.violations.jump')"
+						data-test-id="policy-violation-jump"
+						@click="emit('jump', item.violation)"
+					>
+						<N8nText size="small" color="primary">{{ item.text }}</N8nText>
+					</button>
+					<N8nText v-else size="small" color="text-dark">{{ item.text }}</N8nText>
+				</li>
+			</ul>
+		</section>
+	</div>
+</template>
+
+<style lang="scss" module>
+.list {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing--xs);
+}
+
+.group {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing--4xs);
+}
+
+.items {
+	margin: 0;
+	padding-left: var(--spacing--sm);
+	list-style: disc;
+}
+
+.item + .item {
+	margin-top: var(--spacing--5xs);
+}
+
+.jump {
+	padding: 0;
+	border: 0;
+	background: none;
+	cursor: pointer;
+	text-align: left;
+
+	&:hover,
+	&:focus-visible {
+		text-decoration: underline;
+	}
+}
+</style>

package/src/policy-violations/policyViolations.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPolicyViolations } from './policyViolations';
+
+const saveRefused403 = {
+	message: 'Node type "n8n-nodes-base.slack" is blocked by an instance policy',
+	meta: {
+		violations: [
+			{
+				kind: 'node-type-unavailable',
+				checkId: 'node-type-availability',
+				message: 'Node type "n8n-nodes-base.slack" is blocked by an instance policy',
+				subject: 'n8n-nodes-base.slack',
+				subjectType: 'nodeType',
+				scope: 'instance',
+				matchedRuleId: 'deny-n8n-nodes-base.slack',
+			},
+		],
+	},
+};
+
+const storedExecutionError = {
+	message: 'Workflow start is blocked by a project policy',
+	stack: 'Error: Workflow start is blocked by a project policy\n    at deny',
+	violations: [
+		{
+			kind: 'workflow-start-denied',
+			checkId: 'workflow-start',
+			message: 'Workflow start is blocked by a project policy',
+			subject: 'wf-1',
+			subjectType: 'workflow',
+			scope: 'project',
+		},
+	],
+};
+
+describe('getPolicyViolations', () => {
+	it('reads the violations a refused request carries under meta', () => {
+		const error = Object.assign(new Error(saveRefused403.message), {
+			httpStatusCode: 403,
+			meta: saveRefused403.meta,
+		});
+
+		expect(getPolicyViolations(error)).toEqual(saveRefused403.meta.violations);
+	});
+
+	it('reads the violations a refused run stores on the execution error', () => {
+		expect(getPolicyViolations(storedExecutionError)).toEqual(storedExecutionError.violations);
+	});
+
+	it.each([
+		['an error without violations', new Error('Request failed with status code 500')],
+		['an empty violation list', { meta: { violations: [] } }],
+		[
+			'a violation without the required fields',
+			{ violations: [{ kind: 'node-type-unavailable' }] },
+		],
+		['a violation list that is not an array', { meta: { violations: 'blocked' } }],
+		['a value that is not an object', 'blocked'],
+		['no error at all', undefined],
+	])('returns undefined for %s', (_label, error) => {
+		expect(getPolicyViolations(error)).toBeUndefined();
+	});
+});

package/src/policy-violations/policyViolations.ts

@@ -0,0 +1,19 @@
+import { policyViolationSchema, type PolicyViolation } from '@n8n/api-types';
+import { isRecord } from '@n8n/utils/is-record';
+
+const violationsSchema = policyViolationSchema.array().nonempty();
+
+/**
+ * A refused request carries the violations under `meta`, but a refused manual run is stored on
+ * the execution error, where only the own properties of the error survive.
+ */
+function readViolations(error: unknown): unknown {
+	if (!isRecord(error)) return undefined;
+	if (isRecord(error.meta) && error.meta.violations !== undefined) return error.meta.violations;
+	return error.violations;
+}
+
+export function getPolicyViolations(error: unknown): PolicyViolation[] | undefined {
+	const parsed = violationsSchema.safeParse(readViolations(error));
+	return parsed.success ? parsed.data : undefined;
+}

package/src/type-availability-policies.constants.ts

@@ -1,4 +1,16 @@
+import type { NodeTypeAvailabilityScope } from '@n8n/api-types';
+import type { BaseTextKey } from '@n8n/i18n';
+
 /** Must stay the same as the backend module id: `settings.activeModules` is keyed by it. */
 export const TYPE_AVAILABILITY_POLICIES_MODULE_ID = 'type-availability-policies';
 
 export const TYPE_AVAILABILITY_POLICIES_STORE_ID = 'typeAvailabilityPolicies';
+
+export const SCOPE_LABEL_KEY: Record<NodeTypeAvailabilityScope, BaseTextKey> = {
+	instance: 'typeAvailabilityPolicies.restrictedNode.scope.instance',
+	project: 'typeAvailabilityPolicies.restrictedNode.scope.project',
+};
+
+export function isRestrictionScope(scope: string): scope is NodeTypeAvailabilityScope {
+	return Object.hasOwn(SCOPE_LABEL_KEY, scope);
+}