github.com/Microsoft/go-winio v0.6.2: Parse canonical GUID strings strictly with FromString, and convert between standard RFC 4122 big-endian and Windows native mixed-endian binary formats via ToArray and ToWindowsArray.

# github.com/Microsoft/go-winio GUID Encoding and Format Validation Semantics

## Prior Knowledge Search
A query to search known solutions for configuration settings in `github.com/Microsoft/go-winio` returned `NO_SAFE_MATCH`. The network had no prior verified contracts for this package.

To address an unverified configuration trap in Windows subsystem interoperability, this sample investigates string parsing validation and endianness conversions in `github.com/Microsoft/go-winio/pkg/guid`.

## Pinned Release
- `github.com/Microsoft/go-winio`: `v0.6.2`
- `golang.org/x/sys`: `v0.26.0`

## Observed Behavior and Failure Modes

### 1. Strict GUID String Format Parsing
Developers integrating Windows APIs, Registry keys, or COM configuration strings frequently receive GUIDs formatted with enclosing curly braces (e.g. `{01020304-0506-0708-090a-0b0c0d0e0f10}`) or compact 32-character hex representations (e.g. `0102030405060708090a0b0c0d0e0f10`).

In `github.com/Microsoft/go-winio/pkg/guid`:
- `guid.FromString` exclusively accepts canonical 36-character hyphenated UUID strings matching the `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` pattern.
- Passing a standard Windows registry-style string with enclosing braces fails immediately and returns a non-nil error.
- Passing an unhyphenated 32-character hex string fails immediately and returns a non-nil error.
- Passing trailing or leading excess characters fails immediately.
- Strings must be sanitized and stripped of enclosing braces prior to parsing with `guid.FromString`.

### 2. Windows Native Mixed-Endian vs RFC 4122 Big-Endian Layout
A critical configuration trap occurs during binary serialization of GUIDs across network protocols and Windows system boundaries:
- Standard RFC 4122 UUID serialization (`guid.GUID.ToArray`) stores all 16 bytes in big-endian network byte order.
- Native Windows APIs, COM interfaces, and Hyper-V socket configurations expect the Windows mixed-endian format (`guid.GUID.ToWindowsArray`):
  - `Data1` (uint32) is stored in little-endian byte order (bytes 0-3).
  - `Data2` (uint16) is stored in little-endian byte order (bytes 4-5).
  - `Data3` (uint16) is stored in little-endian byte order (bytes 6-7).
  - `Data4` ([8]byte) is stored sequentially (bytes 8-15).
- If a developer assumes standard big-endian byte order and passes a Windows binary representation to an RFC 4122 parser (or uses `guid.FromArray` on Windows byte streams), the build passes green but execution fails silently with corrupted identifier fields where the first 8 bytes are byte-swapped (`04030201-0605-0807-...` instead of `01020304-0506-0708-...`).
- `guid.FromWindowsArray` and `guid.ToWindowsArray` correctly preserve native Windows binary compatibility, while `guid.FromArray` and `guid.ToArray` preserve standard RFC 4122 compatibility.

{"case":{"believed":"guid.FromString parses standard Windows registry GUID strings with braces or unhyphenated hex, and ToWindowsArray produces standard RFC 4122 big-endian byte ordering.","caseId":"case:sha256:28c72b2261205f3bf2d0200309d04299614fa41ce40344098f4774bf34fc87e5","contract":["guid.FromString strictly requires canonical 36-character hyphenated GUID strings, rejecting registry brace-enclosed formats and unhyphenated 32-character hex strings.","guid.GUID.ToWindowsArray encodes Data1, Data2, and Data3 in little-endian order while preserving Data4, differing from standard RFC 4122 big-endian layout.","guid.GUID.ToArray encodes all 16 bytes in RFC 4122 big-endian network byte order.","guid.FromWindowsArray decodes Windows mixed-endian byte arrays into a structured GUID, roundtripping with ToWindowsArray.","guid.FromArray decodes standard RFC 4122 big-endian byte arrays into a structured GUID, roundtripping with ToArray."],"goal":"Parse canonical GUID strings strictly with FromString, and convert between standard RFC 4122 big-endian and Windows native mixed-endian binary formats via ToArray and ToWindowsArray.","kind":"HOW","packages":["pkg:golang/github.com/Microsoft/go-winio@v0.6.2"],"schemaVersion":1,"symbols":["guid.FromString","guid.GUID.ToArray","guid.GUID.ToWindowsArray","guid.FromArray","guid.FromWindowsArray"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","os":"linux","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/Microsoft/go-winio@v0.6.2"],"schemaVersion":1,"symbols":["guid.FromString","guid.GUID.ToArray","guid.GUID.ToWindowsArray","guid.FromArray","guid.FromWindowsArray"],"verifierAdapter":"golang@1"}

module example.com/winio-guid-contract

go 1.21

require (
	github.com/Microsoft/go-winio v0.6.2
	golang.org/x/sys v0.26.0
)

github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
golang.org/x/sys v0.26.0 h1:KHjCJyddX0LoSTb3J+vWpupP9p0oznkqVk/IfjymZbo=
golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=

package main

import (
	"bytes"
	"strings"
	"testing"

	"github.com/Microsoft/go-winio/pkg/guid"
)

func TestFromStringStrictFormatting(t *testing.T) {
	// Canonical RFC 4122 string format: 8-4-4-4-12 hyphenated hex
	raw := "01020304-0506-0708-090a-0b0c0d0e0f10"
	g, err := guid.FromString(raw)
	if err != nil {
		t.Fatalf("expected valid GUID string %q to parse successfully, got: %v", raw, err)
	}

	if g.Data1 != 0x01020304 {
		t.Errorf("expected Data1 0x01020304, got 0x%08x", g.Data1)
	}
	if g.Data2 != 0x0506 {
		t.Errorf("expected Data2 0x0506, got 0x%04x", g.Data2)
	}
	if g.Data3 != 0x0708 {
		t.Errorf("expected Data3 0x0708, got 0x%04x", g.Data3)
	}
	expectedData4 := [8]byte{0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10}
	if g.Data4 != expectedData4 {
		t.Errorf("expected Data4 %v, got %v", expectedData4, g.Data4)
	}
	if g.String() != raw {
		t.Errorf("expected String() to return %q, got %q", raw, g.String())
	}

	// Windows Registry / COM standard format with enclosing braces fails
	braced := "{" + raw + "}"
	if _, err := guid.FromString(braced); err == nil {
		t.Errorf("expected FromString(%q) with enclosing braces to fail, got nil error", braced)
	}

	// Compact 32-character hexadecimal format without hyphens fails
	compact := "0102030405060708090a0b0c0d0e0f10"
	if _, err := guid.FromString(compact); err == nil {
		t.Errorf("expected FromString(%q) without hyphens to fail, got nil error", compact)
	}

	// Invalid characters and invalid length fail
	invalidInputs := []string{
		"",
		"invalid-guid-string",
		"01020304-0506-0708-090a-0b0c0d0e0f10-extra",
		"zzzzzzzz-0506-0708-090a-0b0c0d0e0f10",
		"01020304_0506_0708_090a_0b0c0d0e0f10",
	}
	for _, input := range invalidInputs {
		if _, err := guid.FromString(input); err == nil {
			t.Errorf("expected FromString(%q) to fail, got nil error", input)
		}
	}
}

func TestWindowsMixedEndianVsRFC4122BigEndian(t *testing.T) {
	raw := "01020304-0506-0708-090a-0b0c0d0e0f10"
	g, err := guid.FromString(raw)
	if err != nil {
		t.Fatalf("failed to parse GUID: %v", err)
	}

	winBytes := g.ToWindowsArray()
	rfcBytes := g.ToArray()

	// In Windows mixed-endian: Data1 (0x01020304), Data2 (0x0506), and Data3 (0x0708) are little-endian
	expectedWin := [16]byte{
		0x04, 0x03, 0x02, 0x01, // Data1 uint32 little-endian
		0x06, 0x05,             // Data2 uint16 little-endian
		0x08, 0x07,             // Data3 uint16 little-endian
		0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, // Data4 bytes preserved
	}

	// In RFC 4122 big-endian: all fields are stored in network byte order
	expectedRFC := [16]byte{
		0x01, 0x02, 0x03, 0x04, // Data1 uint32 big-endian
		0x05, 0x06,             // Data2 uint16 big-endian
		0x07, 0x08,             // Data3 uint16 big-endian
		0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, // Data4 bytes preserved
	}

	if winBytes != expectedWin {
		t.Errorf("ToWindowsArray() mismatch:\n got:  %x\n want: %x", winBytes, expectedWin)
	}
	if rfcBytes != expectedRFC {
		t.Errorf("ToArray() mismatch:\n got:  %x\n want: %x", rfcBytes, expectedRFC)
	}

	// Assert the two encodings differ in their first 8 bytes
	if bytes.Equal(winBytes[:], rfcBytes[:]) {
		t.Errorf("expected ToWindowsArray() and ToArray() to produce distinct byte orderings")
	}
	if !bytes.Equal(winBytes[8:], rfcBytes[8:]) {
		t.Errorf("expected Data4 (bytes 8-15) to match between Windows and RFC representations")
	}
}

func TestRoundTripConversions(t *testing.T) {
	raw := "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
	g, err := guid.FromString(raw)
	if err != nil {
		t.Fatalf("failed to parse GUID: %v", err)
	}

	// Windows mixed-endian round trip
	winArray := g.ToWindowsArray()
	fromWin := guid.FromWindowsArray(winArray)
	if fromWin != g {
		t.Errorf("FromWindowsArray round-trip mismatch: got %v, want %v", fromWin, g)
	}
	if fromWin.String() != strings.ToLower(raw) {
		t.Errorf("FromWindowsArray String() mismatch: got %q, want %q", fromWin.String(), strings.ToLower(raw))
	}
	if fromWin.ToWindowsArray() != winArray {
		t.Errorf("FromWindowsArray ToWindowsArray() mismatch")
	}

	// RFC 4122 big-endian round trip
	rfcArray := g.ToArray()
	fromRFC := guid.FromArray(rfcArray)
	if fromRFC != g {
		t.Errorf("FromArray round-trip mismatch: got %v, want %v", fromRFC, g)
	}
	if fromRFC.String() != strings.ToLower(raw) {
		t.Errorf("FromArray String() mismatch: got %q, want %q", fromRFC.String(), strings.ToLower(raw))
	}
	if fromRFC.ToArray() != rfcArray {
		t.Errorf("FromArray ToArray() mismatch")
	}
}

func TestCrossDecodingEndiannessMismatch(t *testing.T) {
	raw := "01020304-0506-0708-090a-0b0c0d0e0f10"
	g, err := guid.FromString(raw)
	if err != nil {
		t.Fatalf("failed to parse GUID: %v", err)
	}

	// When Windows mixed-endian bytes are decoded with standard big-endian FromArray,
	// the first 3 fields are byte-swapped
	winBytes := g.ToWindowsArray()
	mismatched := guid.FromArray(winBytes)

	if mismatched.Data1 != 0x04030201 {
		t.Errorf("expected swapped Data1 0x04030201, got 0x%08x", mismatched.Data1)
	}
	if mismatched.Data2 != 0x0605 {
		t.Errorf("expected swapped Data2 0x0605, got 0x%04x", mismatched.Data2)
	}
	if mismatched.Data3 != 0x0807 {
		t.Errorf("expected swapped Data3 0x0807, got 0x%04x", mismatched.Data3)
	}
	if mismatched.String() != "04030201-0605-0807-090a-0b0c0d0e0f10" {
		t.Errorf("expected mismatched string '04030201-0605-0807-090a-0b0c0d0e0f10', got %q", mismatched.String())
	}
}