n8n-nodes-resolve-mac-address 0.1.0

package/README.md

@@ -0,0 +1,12 @@
+# n8n-nodes-resolve-mac-address
+
+Resolve a local-network hostname or IPv4 address to a MAC address from n8n.
+
+## Parameters
+
+- **Host**: Hostname or IPv4 address to resolve.
+- **Probe Host**: Sends one ping before reading the neighbor table. This can populate the ARP cache.
+- **Probe Timeout**: Milliseconds to wait for the probe command.
+- **Not Found Behavior**: Choose whether missing MAC addresses throw an error or return a `notFound` status.
+
+This node depends on the operating system neighbor table. It works for hosts visible on the same local network segment and doesn't resolve MAC addresses across routers.

package/dist/nodes/ResolveMacAddress/ResolveMacAddress.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class ResolveMacAddress implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/ResolveMacAddress/ResolveMacAddress.node.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolveMacAddress = void 0;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:dns/promises");
+const node_net_1 = require("node:net");
+const n8n_workflow_1 = require("n8n-workflow");
+const macAddressPattern = /\b(?:[0-9a-f]{2}[:-]){5}[0-9a-f]{2}\b/i;
+function normalizeMacAddress(macAddress) {
+    return macAddress.replace(/-/g, ':').toUpperCase();
+}
+function parseMacAddress(output) {
+    const match = output.match(macAddressPattern);
+    return match ? normalizeMacAddress(match[0]) : undefined;
+}
+function runCommand(command, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        (0, node_child_process_1.execFile)(command, args, {
+            timeout: timeoutMs,
+            windowsHide: true,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+async function resolveIpv4Address(host) {
+    const trimmedHost = host.trim();
+    if ((0, node_net_1.isIP)(trimmedHost) === 4) {
+        return trimmedHost;
+    }
+    const result = await (0, promises_1.lookup)(trimmedHost, { family: 4 });
+    return result.address;
+}
+async function probeHost(ipAddress, timeoutMs) {
+    const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+    if (process.platform === 'win32') {
+        await runCommand('ping', ['-n', '1', '-w', String(timeoutMs), ipAddress], timeoutMs + 1000);
+        return;
+    }
+    await runCommand('ping', ['-c', '1', '-W', String(timeoutSeconds), ipAddress], timeoutMs + 1000);
+}
+async function readNeighborTable(ipAddress, timeoutMs) {
+    const outputs = [];
+    if (process.platform === 'win32') {
+        const result = await runCommand('arp', ['-a', ipAddress], timeoutMs);
+        return `${result.stdout}\n${result.stderr}`;
+    }
+    if (process.platform === 'linux') {
+        try {
+            const result = await runCommand('ip', ['neigh', 'show', ipAddress], timeoutMs);
+            outputs.push(result.stdout, result.stderr);
+        }
+        catch {
+            // Fall back to arp below.
+        }
+    }
+    try {
+        const result = await runCommand('arp', ['-n', ipAddress], timeoutMs);
+        outputs.push(result.stdout, result.stderr);
+    }
+    catch {
+        if (outputs.length === 0) {
+            throw new Error('Unable to read the OS neighbor table with ip neigh or arp.');
+        }
+    }
+    return outputs.join('\n');
+}
+class ResolveMacAddress {
+    description = {
+        displayName: 'Resolve MAC Address',
+        name: 'resolveMacAddress',
+        icon: 'file:resolveMacAddress.svg',
+        group: ['transform'],
+        version: 1,
+        subtitle: '={{$parameter["host"]}}',
+        description: 'Resolve a local-network hostname or IPv4 address to a MAC address',
+        defaults: {
+            name: 'Resolve MAC Address',
+        },
+        inputs: [n8n_workflow_1.NodeConnectionTypes.Main],
+        outputs: [n8n_workflow_1.NodeConnectionTypes.Main],
+        usableAsTool: true,
+        properties: [
+            {
+                displayName: 'Host',
+                name: 'host',
+                type: 'string',
+                default: '',
+                placeholder: 'server.local or 192.168.1.20',
+                required: true,
+                description: 'Hostname or IPv4 address to resolve',
+            },
+            {
+                displayName: 'Probe Host',
+                name: 'probeHost',
+                type: 'boolean',
+                default: true,
+                description: 'Whether to send one ping before reading the neighbor table',
+            },
+            {
+                displayName: 'Probe Timeout',
+                name: 'probeTimeoutMs',
+                type: 'number',
+                default: 1000,
+                typeOptions: {
+                    minValue: 100,
+                    maxValue: 60000,
+                },
+                description: 'Milliseconds to wait for the probe command',
+            },
+            {
+                displayName: 'Not Found Behavior',
+                name: 'notFoundBehavior',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Throw Error',
+                        value: 'throw',
+                    },
+                    {
+                        name: 'Return Not Found Status',
+                        value: 'returnStatus',
+                    },
+                ],
+                default: 'throw',
+                description: 'What to do when the MAC address is not found in the neighbor table',
+            },
+        ],
+    };
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        for (let itemIndex = 0; itemIndex < items.length; itemIndex += 1) {
+            const host = this.getNodeParameter('host', itemIndex);
+            const shouldProbeHost = this.getNodeParameter('probeHost', itemIndex);
+            const probeTimeoutMs = this.getNodeParameter('probeTimeoutMs', itemIndex);
+            const notFoundBehavior = this.getNodeParameter('notFoundBehavior', itemIndex);
+            try {
+                const ipAddress = await resolveIpv4Address(host);
+                let probeError;
+                if (shouldProbeHost) {
+                    try {
+                        await probeHost(ipAddress, probeTimeoutMs);
+                    }
+                    catch (error) {
+                        probeError = error instanceof Error ? error.message : String(error);
+                    }
+                }
+                const neighborTable = await readNeighborTable(ipAddress, probeTimeoutMs);
+                const macAddress = parseMacAddress(neighborTable);
+                if (!macAddress && notFoundBehavior === 'throw') {
+                    throw new Error(`No MAC address found for ${host} (${ipAddress}). The host must be visible on the same local network.`);
+                }
+                returnData.push({
+                    json: {
+                        ...items[itemIndex].json,
+                        resolveMacAddress: {
+                            host,
+                            ipAddress,
+                            macAddress,
+                            status: macAddress ? 'resolved' : 'notFound',
+                            probeError,
+                        },
+                    },
+                    pairedItem: {
+                        item: itemIndex,
+                    },
+                });
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: {
+                            ...items[itemIndex].json,
+                            error: error instanceof Error ? error.message : String(error),
+                        },
+                        pairedItem: {
+                            item: itemIndex,
+                        },
+                    });
+                    continue;
+                }
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), error, { itemIndex });
+            }
+        }
+        return [returnData];
+    }
+}
+exports.ResolveMacAddress = ResolveMacAddress;
+//# sourceMappingURL=ResolveMacAddress.node.js.map

package/dist/nodes/ResolveMacAddress/ResolveMacAddress.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolveMacAddress.node.js","sourceRoot":"","sources":["../../../nodes/ResolveMacAddress/ResolveMacAddress.node.ts"],"names":[],"mappings":"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"}

package/dist/nodes/ResolveMacAddress/ResolveMacAddress.node.json

@@ -0,0 +1,15 @@
+{
+  "node": "n8n-nodes-base.resolveMacAddress",
+  "nodeVersion": "1.0",
+  "codexVersion": "1.0",
+  "categories": [
+    "Utility"
+  ],
+  "resources": {
+    "primaryDocumentation": [
+      {
+        "url": "https://github.com/Sygmei/n8n-nodes/tree/main/packages/resolve-mac-address"
+      }
+    ]
+  }
+}

package/dist/nodes/ResolveMacAddress/resolveMacAddress.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="img" aria-labelledby="title">
+  <title id="title">Resolve MAC Address</title>
+  <rect width="100" height="100" rx="18" fill="#1f6feb"/>
+  <path
+    d="M18 24h64a6 6 0 0 1 6 6v29a6 6 0 0 1-6 6H59v10H41V65H18a6 6 0 0 1-6-6V30a6 6 0 0 1 6-6z"
+    fill="#ffffff"
+  />
+  <path
+    d="M27 39h7M43 39h7M59 39h7M35 50h7M51 50h7M67 50h7"
+    fill="none"
+    stroke="#1f6feb"
+    stroke-width="5"
+    stroke-linecap="round"
+  />
+  <path
+    d="M33 82h34"
+    fill="none"
+    stroke="#ffffff"
+    stroke-width="7"
+    stroke-linecap="round"
+  />
+  <path
+    d="M72 20v-8M78 20v-8M84 20v-8"
+    fill="none"
+    stroke="#ffffff"
+    stroke-width="4"
+    stroke-linecap="square"
+  />
+</svg>

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "n8n-nodes-resolve-mac-address",
+  "version": "0.1.0",
+  "description": "n8n community node to resolve local-network hosts to MAC addresses.",
+  "license": "MIT",
+  "author": {
+    "name": "Sygmei"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Sygmei/n8n-nodes.git",
+    "directory": "packages/resolve-mac-address"
+  },
+  "homepage": "https://github.com/Sygmei/n8n-nodes/tree/main/packages/resolve-mac-address",
+  "bugs": {
+    "url": "https://github.com/Sygmei/n8n-nodes/issues"
+  },
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "arp",
+    "mac-address",
+    "network"
+  ],
+  "main": "dist/nodes/ResolveMacAddress/ResolveMacAddress.node.js",
+  "types": "dist/nodes/ResolveMacAddress/ResolveMacAddress.node.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.json && node ../../scripts/copy-node-assets.mjs",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [],
+    "nodes": [
+      "dist/nodes/ResolveMacAddress/ResolveMacAddress.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "n8n-workflow": "^1.101.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "^1.101.0"
+  }
+}