net.mac-address

export function validateMacAddress(text: string): MacValidation

/** Whether the text is an EUI-48 address, and what it says about itself. */
export interface MacValidation {
  readonly valid: boolean;
  /** lower-case, colon-separated */
  readonly canonical: string | null;
  /** why it is not valid */
  readonly reason: string | null;
  /** the I/G bit: a group address rather than one interface */
  readonly multicast: boolean | null;
  /** the U/L bit: set by software, not burned in by the maker */
  readonly locallyAdministered: boolean | null;
  /** the first three octets, AA-BB-CC as the IEEE registry writes them */
  readonly oui: string | null;
}

import { validateMacAddress } from "#fune/net.mac-address@^1";

import { type MacValidation } from "./net_mac_address_types.ts";

const HEX = "0123456789abcdefABCDEF";

function invalid(reason: string): MacValidation {
  return { valid: false, canonical: null, reason, multicast: null, locallyAdministered: null, oui: null };
}

/**
 * Check a MAC (EUI-48) address written in any of the four common forms and
 * normalise it to lower-case colon form.
 *
 * Exactly four shapes are accepted: aa:bb:cc:dd:ee:ff, aa-bb-cc-dd-ee-ff,
 * aabb.ccdd.eeff (Cisco) and aabbccddeeff. Nothing is trimmed and single-digit
 * octets are refused, because "a:b:c:d:e:f" is more often a typo than a MAC.
 */
export function validateMacAddress(text: string): MacValidation {
  if (typeof text !== "string") return invalid("not text");
  if (text.length === 0) return invalid("empty");

  const seps = [":", "-", "."].filter((s) => text.includes(s));
  if (seps.length > 1) return invalid("mixed separators");

  // Count characters, not UTF-16 units or bytes, so every language agrees.
  const chars = (s: string) => Array.from(s).length;
  const sep = seps[0];
  const parts = sep === undefined ? [text] : text.split(sep);
  const shapeOk =
    sep === undefined
      ? chars(text) === 12
      : sep === "."
        ? parts.length === 3 && parts.every((p) => chars(p) === 4)
        : parts.length === 6 && parts.every((p) => chars(p) === 2);
  if (!shapeOk) return invalid("not a recognised MAC address format");

  const hex = parts.join("");
  for (const ch of hex) {
    if (!HEX.includes(ch)) return invalid("not a hex digit");
  }

  const lower = hex.toLowerCase();
  const octets: string[] = [];
  for (let i = 0; i < 12; i += 2) octets.push(lower.slice(i, i + 2));
  const first = parseInt(octets[0], 16);
  return {
    valid: true,
    canonical: octets.join(":"),
    reason: null,
    // The I/G bit is the least significant bit of the first octet, the U/L bit the next.
    multicast: (first & 1) === 1,
    locallyAdministered: (first & 2) === 2,
    oui: octets.slice(0, 3).join("-").toUpperCase(),
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add net.mac-address

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./net.mac-address-1.0.0-typescript.fune, or fetch it from a terminal with fune pull net.mac-address@1.0.0:typescript.

The whole function, every language, is one file too: net.mac-address-1.0.0.fune, 17,508 bytes, sha256 8645bd19c80f220684b55b51b8ce0a839c37ee15c4a4b860ad78c9fae11e03af. It installs into a project of any language.

// fune: before net.mac-address

// fune: after net.mac-address

// fune: step net.mac-address after <n|label>

More from the author

Exactly four, in either case:

| form | example | where you see it | |------|---------|------------------| | colon | `00:1b:63:84:45:e6` | Linux, macOS, IEEE 802 | | hyphen | `00-1B-63-84-45-E6` | Windows | | Cisco dotted | `001b.6384.45e6` | Cisco IOS | | bare | `001b638445e6` | databases, DHCP exports |

Refused, deliberately:

- mixed separators (`00:1b-63:...`): `mixed separators`; - single-digit octets (`0:1b:63:84:45:e6`), which some tools print but which are more often a typo than an address; EUI-64 and short forms: `not a recognised MAC address format`; - surrounding whitespace, including a trailing newline: nothing is trimmed, so trim input yourself if you mean to; - anything that is not an ASCII hex digit, including non-ASCII digits and fullwidth letters: `not a hex digit`. Lengths are counted in characters in every language, so they fail the same way everywhere.

## What the bits say

- `multicast` is the I/G bit, the least significant bit of the first octet: a group address (`01:00:5e:...` for IPv4 multicast, `ff:ff:ff:ff:ff:ff` broadcast) rather than one interface. - `locallyAdministered` is the U/L bit, the next bit up: the address was set by software (Docker's `02:42:...`, VMs, randomised Wi-Fi MACs) rather than assigned by the maker. - `oui` is the first three octets as the IEEE registry writes them, `00-1B-63`. For a locally administered address it is not a real maker's OUI.

Source: IEEE 802-2014 section 8.2 (MAC address format, I/G and U/L bits), and the IEEE "Guidelines for Use of Extended Unique Identifier (EUI)".

Files