win-guid

A module for encoding and decoding Windows legacy GUIDs using the Windows GUID byte layout, a mixed-endianness format used by several long-standing Microsoft and firmware standards, including:

• Component Object Model (COM)
• Object Linking and Embedding (OLE)
• Compound File Binary Format (CFBF, Structured Storage)
• GUID Partition Table (GPT)
• Unified Extensible Firmware Interface (UEFI)
• Windows Registry binary GUID values
• Active Directory objectGUID values

This is commonly needed when working with Microsoft file and storage formats, such as .asf, .doc, .xls, .ppt, and other binary formats based on OLE/COM Structured Storage (CFBF), where GUIDs are stored in Windows byte order rather than RFC 9562-style UUID order.

Windows legacy GUID byte layout vs RFC 9562 UUID byte layout

The table below shows how GUID 00112233-4455-6677-8899-AABBCCDDEEFF is serialized as an RFC 9562 UUID versus a Windows GUID:

| UUID / GUID type | Serialized byte layout (hexadecimal) | |-------------------------|---------------------------------------------------| | RFC 9562 UUID layout | 00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF | | Windows GUID layout | 33 22 11 00 55 44 77 66 88 99 AA BB CC DD EE FF |

Windows legacy GUID layout reorders only the first three fields (32-bit, 16-bit, 16-bit). The remaining 8 bytes are stored as-is.

For RFC 9562 compliant UUIDs (network byte order), use uuid instead.

Installation

npm install win-guid

Usage

Parse a GUID string

Parses a canonical GUID string:

import { parseWindowsGuid } from "win-guid";

const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");

into a 16-byte Uint8Array using Windows GUID byte order.

• Input is validated strictly
• Case-insensitive
• Throws an error on invalid input

Use the Guid helper class

Creates a GUID from a canonical GUID string.

import { Guid } from "win-guid";

const guid = Guid.fromString("00020906-0000-0000-C000-000000000046");

API

parseWindowsGuid(guid: string): Uint8Array

Parses a canonical GUID string:

const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");

into a 16-byte Uint8Array using Windows GUID byte order.

• Input is validated strictly
• Case-insensitive
• Throws Error on invalid input

class Guid

Creates a GUID from a canonical GUID string.

const guid = Guid.fromString("00020906-0000-0000-C000-000000000046");

guid.toString(): string

Converts the GUID back into the canonical string form.

• Always uppercase
• Round-trips cleanly with fromString

guid.toString();

Outputs something like:

00020906-0000-0000-C000-000000000046`

guid.bytes: Uint8Array

Provides access to the raw 16-byte GUID in Windows legacy GUID byte order.

const bytes = guid.bytes;

Licence

This project is licensed under the MIT License. Feel free to use, modify, and distribute as needed.