diff --git a/.cursor/environment.json b/.cursor/environment.json new file mode 100644 index 0000000..9fc73f2 --- /dev/null +++ b/.cursor/environment.json @@ -0,0 +1,16 @@ +{ + "name": "macaddy", + "install": "npm ci", + "terminals": [ + { + "name": "dev-server", + "command": "npm run dev" + } + ], + "ports": [ + { + "name": "web", + "port": 3000 + } + ] +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3543a00 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +npm-debug.log* +.DS_Store +*.log +.env diff --git a/README.md b/README.md index 2e67c71..bb11628 100644 --- a/README.md +++ b/README.md @@ -1 +1,66 @@ -# macaddy \ No newline at end of file +# macaddy + +A small MAC address toolkit. `macaddy` validates, normalizes, inspects, and +generates 48-bit MAC addresses through a tiny HTTP API and a single-page web UI. +It ships with an offline subset of the IEEE OUI registry so vendor lookups work +without network access. + +## Features + +- Validate MAC addresses in colon, hyphen, Cisco-dot, or bare notation. +- Normalize a MAC into any of those notations (upper/lowercase). +- Inspect bit-level facts: OUI/NIC split, unicast vs multicast, + universal vs locally-administered, and broadcast detection. +- Look up the vendor from a MAC's OUI (offline table). +- Generate random, locally-administered unicast MAC addresses. + +## Requirements + +- Node.js >= 20 (developed against Node 22) + +## Getting started + +```bash +npm install # install dependencies +npm test # run the unit and API tests +npm start # start the server on http://localhost:3000 +npm run dev # start with auto-reload (node --watch) +``` + +Set `PORT` to change the listening port (defaults to `3000`). + +## HTTP API + +| Method | Path | Description | +| --- | --- | --- | +| GET | `/api/health` | Liveness check. | +| GET | `/api/lookup?mac=` | Validate + analyze a MAC address. | +| GET | `/api/generate?format=&upper=` | Generate a random MAC. | + +`format` may be `colon` (default), `hyphen`, `dot`, or `bare`. + +### Examples + +```bash +curl 'http://localhost:3000/api/health' +curl 'http://localhost:3000/api/lookup?mac=00:1b:63:84:45:e6' +curl 'http://localhost:3000/api/generate?format=hyphen' +``` + +## Project layout + +``` +src/ + mac.js # pure MAC utilities (validate/normalize/analyze/generate) + oui.js # offline OUI -> vendor table + server.js # Express app + JSON API + static frontend +public/ # single-page web UI +test/ # node:test unit + API tests +``` + +## Cloud Agent environment + +This repository is configured for Cursor Cloud Agents via +[`.cursor/environment.json`](.cursor/environment.json): dependencies are +installed with `npm ci` and the dev server runs in a `terminals` entry on +port 3000. diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..ade869e --- /dev/null +++ b/package-lock.json @@ -0,0 +1,832 @@ +{ + "name": "macaddy", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "macaddy", + "version": "0.1.0", + "license": "MIT", + "dependencies": { + "express": "^4.19.2" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/accepts": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz", + "integrity": "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==", + "license": "MIT", + "dependencies": { + "mime-types": "~2.1.34", + "negotiator": "0.6.3" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/array-flatten": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz", + "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==", + "license": "MIT" + }, + "node_modules/body-parser": { + "version": "1.20.6", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.6.tgz", + "integrity": "sha512-p5tAzS57i5MV9fZFDj9LeIiTZEufbSe2eDozP+ElheSUq1m74CRq1jI4mYNDdVs9vQztXFLuk/Gd6BWTdwRJ5g==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "content-type": "~1.0.5", + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "~1.2.0", + "http-errors": "~2.0.1", + "iconv-lite": "~0.4.24", + "on-finished": "~2.4.1", + "qs": "~6.15.1", + "raw-body": "~2.5.3", + "type-is": "~1.6.18", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/call-bound": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", + "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "get-intrinsic": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/content-disposition": { + "version": "0.5.4", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz", + "integrity": "sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==", + "license": "MIT", + "dependencies": { + "safe-buffer": "5.2.1" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", + "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie-signature": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.7.tgz", + "integrity": "sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==", + "license": "MIT" + }, + "node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/destroy": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz", + "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==", + "license": "MIT", + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "license": "MIT" + }, + "node_modules/encodeurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz", + "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/es-define-property": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-errors": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz", + "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-object-atoms": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz", + "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "license": "MIT" + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/express": { + "version": "4.22.2", + "resolved": "https://registry.npmjs.org/express/-/express-4.22.2.tgz", + "integrity": "sha512-IuL+Elrou2ZvCFHs18/CIzy2Nzvo25nZ1/D2eIZlz7c+QUayAcYoiM2BthCjs+EBHVpjYjcuLDAiCWgeIX3X1Q==", + "license": "MIT", + "dependencies": { + "accepts": "~1.3.8", + "array-flatten": "1.1.1", + "body-parser": "~1.20.5", + "content-disposition": "~0.5.4", + "content-type": "~1.0.4", + "cookie": "~0.7.1", + "cookie-signature": "~1.0.6", + "debug": "2.6.9", + "depd": "2.0.0", + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "finalhandler": "~1.3.1", + "fresh": "~0.5.2", + "http-errors": "~2.0.0", + "merge-descriptors": "1.0.3", + "methods": "~1.1.2", + "on-finished": "~2.4.1", + "parseurl": "~1.3.3", + "path-to-regexp": "~0.1.12", + "proxy-addr": "~2.0.7", + "qs": "~6.15.1", + "range-parser": "~1.2.1", + "safe-buffer": "5.2.1", + "send": "~0.19.0", + "serve-static": "~1.16.2", + "setprototypeof": "1.2.0", + "statuses": "~2.0.1", + "type-is": "~1.6.18", + "utils-merge": "1.0.1", + "vary": "~1.1.2" + }, + "engines": { + "node": ">= 0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/finalhandler": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.2.tgz", + "integrity": "sha512-aA4RyPcd3badbdABGDuTXCMTtOneUCAYH/gxoYRTZlIJdF0YPWuGqiAsIrhNnnqdXGswYk6dGujem4w80UJFhg==", + "license": "MIT", + "dependencies": { + "debug": "2.6.9", + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "on-finished": "~2.4.1", + "parseurl": "~1.3.3", + "statuses": "~2.0.2", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fresh": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", + "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-intrinsic": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", + "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", + "function-bind": "^1.1.2", + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "license": "MIT", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/gopd": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/hasown": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz", + "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==", + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/http-errors": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", + "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", + "license": "MIT", + "dependencies": { + "depd": "~2.0.0", + "inherits": "~2.0.4", + "setprototypeof": "~1.2.0", + "statuses": "~2.0.2", + "toidentifier": "~1.0.1" + }, + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/iconv-lite": { + "version": "0.4.24", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz", + "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==", + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/media-typer": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", + "integrity": "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/merge-descriptors": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-1.0.3.tgz", + "integrity": "sha512-gaNvAS7TZ897/rVaZ0nMtAyxNyi/pdbjbAwUpFQpN70GqnVfOiXpeUUMKRBmzXaSQ8DdTX4/0ms62r2K+hE6mQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/methods": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz", + "integrity": "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz", + "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==", + "license": "MIT", + "bin": { + "mime": "cli.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/mime-db": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", + "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "2.1.35", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", + "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", + "license": "MIT", + "dependencies": { + "mime-db": "1.52.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT" + }, + "node_modules/negotiator": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz", + "integrity": "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/object-inspect": { + "version": "1.13.4", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", + "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "license": "MIT", + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/path-to-regexp": { + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz", + "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==", + "license": "MIT" + }, + "node_modules/proxy-addr": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", + "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==", + "license": "MIT", + "dependencies": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/qs": { + "version": "6.15.3", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz", + "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==", + "license": "BSD-3-Clause", + "dependencies": { + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/range-parser": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", + "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/raw-body": { + "version": "2.5.3", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.3.tgz", + "integrity": "sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "http-errors": "~2.0.1", + "iconv-lite": "~0.4.24", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "license": "MIT" + }, + "node_modules/send": { + "version": "0.19.2", + "resolved": "https://registry.npmjs.org/send/-/send-0.19.2.tgz", + "integrity": "sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==", + "license": "MIT", + "dependencies": { + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "fresh": "~0.5.2", + "http-errors": "~2.0.1", + "mime": "1.6.0", + "ms": "2.1.3", + "on-finished": "~2.4.1", + "range-parser": "~1.2.1", + "statuses": "~2.0.2" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/send/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/serve-static": { + "version": "1.16.3", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.16.3.tgz", + "integrity": "sha512-x0RTqQel6g5SY7Lg6ZreMmsOzncHFU7nhnRWkKgWuMTu5NN0DR5oruckMqRvacAN9d5w6ARnRBXl9xhDCgfMeA==", + "license": "MIT", + "dependencies": { + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "parseurl": "~1.3.3", + "send": "~0.19.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "license": "ISC" + }, + "node_modules/side-channel": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz", + "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4", + "side-channel-list": "^1.0.1", + "side-channel-map": "^1.0.1", + "side-channel-weakmap": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-list": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz", + "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-map": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", + "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-weakmap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", + "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3", + "side-channel-map": "^1.0.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/statuses": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", + "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "license": "MIT", + "engines": { + "node": ">=0.6" + } + }, + "node_modules/type-is": { + "version": "1.6.18", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz", + "integrity": "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==", + "license": "MIT", + "dependencies": { + "media-typer": "0.3.0", + "mime-types": "~2.1.24" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/utils-merge": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", + "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==", + "license": "MIT", + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..cad0cfb --- /dev/null +++ b/package.json @@ -0,0 +1,18 @@ +{ + "name": "macaddy", + "version": "0.1.0", + "description": "A small MAC address toolkit: validate, normalize, generate, and look up vendors.", + "type": "module", + "engines": { + "node": ">=20" + }, + "scripts": { + "start": "node src/server.js", + "dev": "node --watch src/server.js", + "test": "node --test" + }, + "dependencies": { + "express": "^4.19.2" + }, + "license": "MIT" +} diff --git a/public/app.js b/public/app.js new file mode 100644 index 0000000..7eeb505 --- /dev/null +++ b/public/app.js @@ -0,0 +1,71 @@ +const input = document.getElementById("mac-input"); +const lookupBtn = document.getElementById("lookup-btn"); +const generateBtn = document.getElementById("generate-btn"); +const statusEl = document.getElementById("status"); +const resultEl = document.getElementById("result"); +const resultList = document.getElementById("result-list"); + +function setStatus(message, kind = "") { + statusEl.textContent = message; + statusEl.className = `status ${kind}`.trim(); +} + +function renderResult(data) { + const rows = [ + ["Vendor", data.vendor ?? "Unknown"], + ["Colon", data.formats.colon], + ["Hyphen", data.formats.hyphen], + ["Cisco dot", data.formats.dot], + ["Bare", data.formats.bare], + ["Uppercase", data.formats.upper], + ["OUI", data.oui], + ["NIC", data.nic], + ["Cast", data.cast], + ["Administration", data.administration], + ["Broadcast", String(data.broadcast)], + ]; + resultList.innerHTML = rows + .map(([k, v]) => `
${k}
${v}
`) + .join(""); + resultEl.classList.remove("hidden"); +} + +async function lookup() { + const mac = input.value.trim(); + if (!mac) { + setStatus("Enter a MAC address to inspect.", "error"); + return; + } + setStatus("Looking up…"); + try { + const res = await fetch(`/api/lookup?mac=${encodeURIComponent(mac)}`); + const data = await res.json(); + if (!res.ok || !data.valid) { + resultEl.classList.add("hidden"); + setStatus(data.error ?? "Invalid MAC address", "error"); + return; + } + setStatus("Valid MAC address.", "ok"); + renderResult(data); + } catch (err) { + setStatus(`Request failed: ${err.message}`, "error"); + } +} + +async function generateRandom() { + setStatus("Generating…"); + try { + const res = await fetch("/api/generate"); + const data = await res.json(); + input.value = data.mac; + await lookup(); + } catch (err) { + setStatus(`Request failed: ${err.message}`, "error"); + } +} + +lookupBtn.addEventListener("click", lookup); +generateBtn.addEventListener("click", generateRandom); +input.addEventListener("keydown", (e) => { + if (e.key === "Enter") lookup(); +}); diff --git a/public/index.html b/public/index.html new file mode 100644 index 0000000..079cd46 --- /dev/null +++ b/public/index.html @@ -0,0 +1,39 @@ + + + + + + macaddy — MAC address toolkit + + + +
+
+

macaddy

+

Validate, normalize, and inspect MAC addresses.

+
+ +
+ +
+ + + +
+

+
+ + +
+ + + diff --git a/public/styles.css b/public/styles.css new file mode 100644 index 0000000..4faf1bd --- /dev/null +++ b/public/styles.css @@ -0,0 +1,155 @@ +:root { + --bg: #0f172a; + --card: #1e293b; + --card-border: #334155; + --accent: #38bdf8; + --accent-strong: #0ea5e9; + --text: #e2e8f0; + --muted: #94a3b8; + --danger: #f87171; + --ok: #4ade80; +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; + min-height: 100vh; + background: radial-gradient(1200px 600px at 50% -10%, #1e293b, var(--bg)); + color: var(--text); + font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, + Helvetica, Arial, sans-serif; + display: flex; + justify-content: center; + padding: 3rem 1rem; +} + +.app { + width: 100%; + max-width: 640px; +} + +.hero { + text-align: center; + margin-bottom: 2rem; +} + +.hero h1 { + font-size: 2.75rem; + margin: 0; + letter-spacing: -0.02em; + background: linear-gradient(90deg, var(--accent), #a78bfa); + -webkit-background-clip: text; + background-clip: text; + color: transparent; +} + +.tagline { + color: var(--muted); + margin: 0.25rem 0 0; +} + +.card { + background: var(--card); + border: 1px solid var(--card-border); + border-radius: 14px; + padding: 1.5rem; + margin-bottom: 1.25rem; + box-shadow: 0 10px 30px rgba(0, 0, 0, 0.25); +} + +label { + display: block; + font-size: 0.85rem; + color: var(--muted); + margin-bottom: 0.5rem; + text-transform: uppercase; + letter-spacing: 0.06em; +} + +.row { + display: flex; + gap: 0.5rem; + flex-wrap: wrap; +} + +input { + flex: 1 1 240px; + padding: 0.75rem 0.9rem; + border-radius: 10px; + border: 1px solid var(--card-border); + background: #0b1220; + color: var(--text); + font-size: 1rem; + font-family: ui-monospace, "SFMono-Regular", Menlo, monospace; +} + +input:focus { + outline: none; + border-color: var(--accent); + box-shadow: 0 0 0 3px rgba(56, 189, 248, 0.2); +} + +button { + padding: 0.75rem 1.1rem; + border-radius: 10px; + border: none; + background: var(--accent-strong); + color: #06121c; + font-weight: 600; + cursor: pointer; + font-size: 0.95rem; +} + +button:hover { + filter: brightness(1.08); +} + +button.secondary { + background: transparent; + color: var(--accent); + border: 1px solid var(--card-border); +} + +.status { + min-height: 1.2rem; + margin: 0.75rem 0 0; + font-size: 0.9rem; +} + +.status.error { + color: var(--danger); +} + +.status.ok { + color: var(--ok); +} + +.result h2 { + margin-top: 0; + font-size: 1.1rem; +} + +dl { + display: grid; + grid-template-columns: minmax(120px, auto) 1fr; + gap: 0.5rem 1rem; + margin: 0; +} + +dt { + color: var(--muted); + font-size: 0.85rem; +} + +dd { + margin: 0; + font-family: ui-monospace, "SFMono-Regular", Menlo, monospace; + word-break: break-all; +} + +.hidden { + display: none; +} diff --git a/src/mac.js b/src/mac.js new file mode 100644 index 0000000..9b61074 --- /dev/null +++ b/src/mac.js @@ -0,0 +1,102 @@ +// Core MAC address utilities: validate, normalize, format, generate, and +// vendor lookup. Pure functions with no I/O so they are easy to unit test. + +import { OUI_TABLE } from "./oui.js"; + +const HEX_PAIR = /^[0-9a-fA-F]{2}$/; + +/** + * Extract the 12 hex digits from a MAC address written in any common + * notation (colon, hyphen, dot/Cisco, or bare). Returns the lowercase hex + * string, or null if the input is not a valid 48-bit MAC address. + */ +export function toHex(input) { + if (typeof input !== "string") return null; + const stripped = input.trim().replace(/[.:-]/g, ""); + if (!/^[0-9a-fA-F]{12}$/.test(stripped)) return null; + return stripped.toLowerCase(); +} + +export function isValid(input) { + return toHex(input) !== null; +} + +/** + * Normalize a MAC address into a chosen notation. + * format: "colon" (default), "hyphen", "dot", or "bare". + * upper: uppercase the hex digits when true. + */ +export function normalize(input, { format = "colon", upper = false } = {}) { + const hex = toHex(input); + if (hex === null) return null; + const pairs = hex.match(/.{2}/g); + const cased = upper ? hex.toUpperCase() : hex; + const casedPairs = cased.match(/.{2}/g); + + switch (format) { + case "bare": + return cased; + case "hyphen": + return casedPairs.join("-"); + case "dot": { + const quads = cased.match(/.{4}/g); + return quads.join("."); + } + case "colon": + default: + return casedPairs.join(":"); + } +} + +/** The OUI (first 3 octets) as a lowercase bare hex string, or null. */ +export function ouiOf(input) { + const hex = toHex(input); + if (hex === null) return null; + return hex.slice(0, 6); +} + +/** Look up the vendor for a MAC's OUI. Returns a string or null. */ +export function vendorOf(input) { + const oui = ouiOf(input); + if (oui === null) return null; + return OUI_TABLE[oui] ?? null; +} + +/** + * Bit-level facts about a MAC address, derived from the first octet. + * - unicast vs multicast (least significant bit of the first octet) + * - universally vs locally administered (second least significant bit) + */ +export function analyze(input) { + const hex = toHex(input); + if (hex === null) return null; + const firstOctet = parseInt(hex.slice(0, 2), 16); + const multicast = (firstOctet & 0b1) === 1; + const locallyAdministered = (firstOctet & 0b10) === 2; + return { + hex, + oui: hex.slice(0, 6), + nic: hex.slice(6), + vendor: vendorOf(hex), + cast: multicast ? "multicast" : "unicast", + administration: locallyAdministered ? "local" : "universal", + broadcast: hex === "ffffffffffff", + }; +} + +/** + * Generate a random, locally-administered unicast MAC address. + * The first octet has the local bit set and the multicast bit cleared. + */ +export function generate({ format = "colon", upper = false } = {}) { + const bytes = new Array(6); + for (let i = 0; i < 6; i++) { + bytes[i] = Math.floor(Math.random() * 256); + } + // Set locally-administered (bit 1), clear multicast (bit 0). + bytes[0] = (bytes[0] & 0b11111100) | 0b10; + const hex = bytes.map((b) => b.toString(16).padStart(2, "0")).join(""); + return normalize(hex, { format, upper }); +} + +export { HEX_PAIR }; diff --git a/src/oui.js b/src/oui.js new file mode 100644 index 0000000..243aefa --- /dev/null +++ b/src/oui.js @@ -0,0 +1,33 @@ +// A small, offline subset of the IEEE OUI (Organizationally Unique +// Identifier) registry. Keys are the lowercase first three octets of a MAC +// address (bare hex). This is intentionally a curated sample rather than the +// full ~30k-entry registry, so the toolkit works with no network access. + +export const OUI_TABLE = { + "001b63": "Apple, Inc.", + "0017f2": "Apple, Inc.", + "3c0754": "Apple, Inc.", + "f0189e": "Apple, Inc.", + "001a11": "Google, Inc.", + "3c5ab4": "Google, Inc.", + "d83134": "Google, Inc.", + "001dd8": "Microsoft Corporation", + "0050f2": "Microsoft Corporation", + "b8317f": "Cisco Systems, Inc", + "00000c": "Cisco Systems, Inc", + "005056": "VMware, Inc.", + "000c29": "VMware, Inc.", + "080027": "PCS Systemtechnik GmbH (VirtualBox)", + "525400": "QEMU / KVM Virtual NIC", + "b827eb": "Raspberry Pi Foundation", + "dca632": "Raspberry Pi Trading Ltd", + "001c42": "Parallels, Inc.", + "0003ff": "Microsoft Corporation (Hyper-V)", + "fcfbfb": "Cisco Systems, Inc", + "ac220b": "ASUSTek COMPUTER INC.", + "001966": "Samsung Electronics Co.,Ltd", + "e8508b": "Samsung Electronics Co.,Ltd", + "00248c": "ASUSTek COMPUTER INC.", + "d8a25e": "Amazon Technologies Inc.", + "44650d": "Amazon Technologies Inc.", +}; diff --git a/src/server.js b/src/server.js new file mode 100644 index 0000000..25fb7c9 --- /dev/null +++ b/src/server.js @@ -0,0 +1,56 @@ +import express from "express"; +import { fileURLToPath } from "node:url"; +import { dirname, join } from "node:path"; +import { analyze, normalize, generate, isValid } from "./mac.js"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +export function createApp() { + const app = express(); + app.use(express.json()); + app.use(express.static(join(__dirname, "..", "public"))); + + app.get("/api/health", (_req, res) => { + res.json({ status: "ok" }); + }); + + // Inspect a MAC address: validity, notations, and bit-level analysis. + app.get("/api/lookup", (req, res) => { + const value = String(req.query.mac ?? ""); + const details = analyze(value); + if (details === null) { + return res.status(400).json({ valid: false, error: "Invalid MAC address" }); + } + res.json({ + valid: true, + input: value, + formats: { + colon: normalize(value, { format: "colon" }), + hyphen: normalize(value, { format: "hyphen" }), + dot: normalize(value, { format: "dot" }), + bare: normalize(value, { format: "bare" }), + upper: normalize(value, { format: "colon", upper: true }), + }, + ...details, + }); + }); + + // Generate a random, locally-administered unicast MAC address. + app.get("/api/generate", (req, res) => { + const format = String(req.query.format ?? "colon"); + const upper = String(req.query.upper ?? "false") === "true"; + const mac = generate({ format, upper }); + res.json({ mac, valid: isValid(mac) }); + }); + + return app; +} + +const isMain = process.argv[1] === fileURLToPath(import.meta.url); +if (isMain) { + const port = Number(process.env.PORT ?? 3000); + const app = createApp(); + app.listen(port, () => { + console.log(`macaddy listening on http://localhost:${port}`); + }); +} diff --git a/test/mac.test.js b/test/mac.test.js new file mode 100644 index 0000000..31a7f71 --- /dev/null +++ b/test/mac.test.js @@ -0,0 +1,75 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { + toHex, + isValid, + normalize, + ouiOf, + vendorOf, + analyze, + generate, +} from "../src/mac.js"; + +test("toHex accepts common notations", () => { + assert.equal(toHex("00:1b:63:84:45:e6"), "001b638445e6"); + assert.equal(toHex("00-1b-63-84-45-e6"), "001b638445e6"); + assert.equal(toHex("001b.6384.45e6"), "001b638445e6"); + assert.equal(toHex("001B638445E6"), "001b638445e6"); +}); + +test("toHex rejects invalid input", () => { + assert.equal(toHex("not a mac"), null); + assert.equal(toHex("00:1b:63:84:45"), null); + assert.equal(toHex("00:1b:63:84:45:zz"), null); + assert.equal(toHex(1234), null); +}); + +test("isValid mirrors toHex", () => { + assert.equal(isValid("00:1b:63:84:45:e6"), true); + assert.equal(isValid("xyz"), false); +}); + +test("normalize renders every format", () => { + const mac = "001b638445e6"; + assert.equal(normalize(mac, { format: "colon" }), "00:1b:63:84:45:e6"); + assert.equal(normalize(mac, { format: "hyphen" }), "00-1b-63-84-45-e6"); + assert.equal(normalize(mac, { format: "dot" }), "001b.6384.45e6"); + assert.equal(normalize(mac, { format: "bare" }), "001b638445e6"); + assert.equal( + normalize(mac, { format: "colon", upper: true }), + "00:1B:63:84:45:E6", + ); +}); + +test("ouiOf and vendorOf resolve a known vendor", () => { + assert.equal(ouiOf("00:1b:63:84:45:e6"), "001b63"); + assert.equal(vendorOf("00:1b:63:84:45:e6"), "Apple, Inc."); + assert.equal(vendorOf("02:00:00:00:00:00"), null); +}); + +test("analyze reports cast and administration bits", () => { + const universalUnicast = analyze("00:1b:63:84:45:e6"); + assert.equal(universalUnicast.cast, "unicast"); + assert.equal(universalUnicast.administration, "universal"); + + const localUnicast = analyze("02:00:00:00:00:00"); + assert.equal(localUnicast.cast, "unicast"); + assert.equal(localUnicast.administration, "local"); + + const multicast = analyze("01:00:5e:00:00:fb"); + assert.equal(multicast.cast, "multicast"); + + const broadcast = analyze("ff:ff:ff:ff:ff:ff"); + assert.equal(broadcast.broadcast, true); + assert.equal(broadcast.cast, "multicast"); +}); + +test("generate produces valid, locally-administered unicast MACs", () => { + for (let i = 0; i < 200; i++) { + const mac = generate(); + assert.equal(isValid(mac), true, `invalid: ${mac}`); + const info = analyze(mac); + assert.equal(info.cast, "unicast"); + assert.equal(info.administration, "local"); + } +}); diff --git a/test/server.test.js b/test/server.test.js new file mode 100644 index 0000000..c5dfcb9 --- /dev/null +++ b/test/server.test.js @@ -0,0 +1,52 @@ +import { test, before, after } from "node:test"; +import assert from "node:assert/strict"; +import { createApp } from "../src/server.js"; + +let server; +let baseUrl; + +before(async () => { + const app = createApp(); + await new Promise((resolve) => { + server = app.listen(0, () => { + const { port } = server.address(); + baseUrl = `http://127.0.0.1:${port}`; + resolve(); + }); + }); +}); + +after(() => { + server?.close(); +}); + +test("GET /api/health returns ok", async () => { + const res = await fetch(`${baseUrl}/api/health`); + assert.equal(res.status, 200); + assert.deepEqual(await res.json(), { status: "ok" }); +}); + +test("GET /api/lookup returns analysis for a valid MAC", async () => { + const res = await fetch(`${baseUrl}/api/lookup?mac=00:1b:63:84:45:e6`); + assert.equal(res.status, 200); + const data = await res.json(); + assert.equal(data.valid, true); + assert.equal(data.vendor, "Apple, Inc."); + assert.equal(data.formats.hyphen, "00-1b-63-84-45-e6"); + assert.equal(data.cast, "unicast"); +}); + +test("GET /api/lookup rejects an invalid MAC", async () => { + const res = await fetch(`${baseUrl}/api/lookup?mac=nope`); + assert.equal(res.status, 400); + const data = await res.json(); + assert.equal(data.valid, false); +}); + +test("GET /api/generate returns a valid MAC", async () => { + const res = await fetch(`${baseUrl}/api/generate?format=hyphen`); + assert.equal(res.status, 200); + const data = await res.json(); + assert.equal(data.valid, true); + assert.match(data.mac, /^[0-9a-f]{2}(-[0-9a-f]{2}){5}$/); +});