@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/canonicaljson/canonical.go

@@ -0,0 +1,370 @@
+package canonicaljson
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"sort"
+	"strconv"
+	"unicode/utf16"
+	"unicode/utf8"
+)
+
+// Canonicalize 按 RFC 8785 与 I-JSON 约束生成稳定 JSON 字节。
+func Canonicalize(raw json.RawMessage) (json.RawMessage, error) {
+	if len(raw) == 0 || !utf8.Valid(raw) {
+		return nil, fmt.Errorf("JSON must contain valid UTF-8 data")
+	}
+	if err := validateStringTokens(raw); err != nil {
+		return nil, err
+	}
+
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.UseNumber()
+	value, err := decodeValue(decoder, "$")
+	if err != nil {
+		return nil, fmt.Errorf("decode JSON: %w", err)
+	}
+	if err := requireEOF(decoder); err != nil {
+		return nil, err
+	}
+
+	canonical, err := appendValue(nil, value)
+	if err != nil {
+		return nil, err
+	}
+	return json.RawMessage(canonical), nil
+}
+
+// Hash 返回 canonical JSON 的 SHA-256 小写十六进制摘要。
+func Hash(raw json.RawMessage) (string, error) {
+	canonical, err := Canonicalize(raw)
+	if err != nil {
+		return "", err
+	}
+	digest := sha256.Sum256(canonical)
+	return hex.EncodeToString(digest[:]), nil
+}
+
+// HashValue 将可 JSON 序列化的语义值转换为 canonical JSON 后计算摘要。
+func HashValue(value any) (string, error) { //nolint:T1 // any 仅作为标准 JSON 序列化边界。
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return "", fmt.Errorf("marshal canonical value: %w", err)
+	}
+	return Hash(raw)
+}
+
+// Equal 按 canonical JSON 字节比较两个 JSON 值的语义是否相同。
+func Equal(left json.RawMessage, right json.RawMessage) (bool, error) {
+	canonicalLeft, err := Canonicalize(left)
+	if err != nil {
+		return false, fmt.Errorf("canonicalize left JSON: %w", err)
+	}
+	canonicalRight, err := Canonicalize(right)
+	if err != nil {
+		return false, fmt.Errorf("canonicalize right JSON: %w", err)
+	}
+	return bytes.Equal(canonicalLeft, canonicalRight), nil
+}
+
+// IsHash 判断字符串是否为 Hash 生成的 64 位小写十六进制摘要。
+func IsHash(value string) bool {
+	if len(value) != sha256.Size*2 {
+		return false
+	}
+	for index := range value {
+		character := value[index]
+		if (character < '0' || character > '9') && (character < 'a' || character > 'f') {
+			return false
+		}
+	}
+	return true
+}
+
+func validateStringTokens(raw []byte) error {
+	for index := 0; index < len(raw); {
+		if raw[index] != '"' {
+			index++
+			continue
+		}
+		start := index
+		index++
+		closed := false
+		for index < len(raw) {
+			switch raw[index] {
+			case '\\':
+				index += 2
+			case '"':
+				if err := validateStringToken(raw[start : index+1]); err != nil {
+					return err
+				}
+				index++
+				closed = true
+			default:
+				index++
+			}
+			if closed {
+				break
+			}
+		}
+		if !closed {
+			return fmt.Errorf("JSON string is not terminated")
+		}
+	}
+	return nil
+}
+
+func validateStringToken(raw []byte) error {
+	end := len(raw) - 1
+	for index := 1; index < end; {
+		if raw[index] != '\\' {
+			index++
+			continue
+		}
+		if index+1 >= end {
+			return fmt.Errorf("JSON string escape is incomplete")
+		}
+		if raw[index+1] != 'u' {
+			index += 2
+			continue
+		}
+		if index+6 > end {
+			return fmt.Errorf("JSON Unicode escape is incomplete")
+		}
+		codeUnit, err := strconv.ParseUint(string(raw[index+2:index+6]), 16, 16)
+		if err != nil {
+			return fmt.Errorf("JSON Unicode escape is invalid")
+		}
+		switch {
+		case codeUnit >= 0xd800 && codeUnit <= 0xdbff:
+			if index+12 > end || raw[index+6] != '\\' || raw[index+7] != 'u' {
+				return fmt.Errorf("JSON high surrogate must be followed by a low surrogate")
+			}
+			low, lowErr := strconv.ParseUint(string(raw[index+8:index+12]), 16, 16)
+			if lowErr != nil || low < 0xdc00 || low > 0xdfff {
+				return fmt.Errorf("JSON high surrogate must be followed by a low surrogate")
+			}
+			index += 12
+		case codeUnit >= 0xdc00 && codeUnit <= 0xdfff:
+			return fmt.Errorf("JSON low surrogate must follow a high surrogate")
+		default:
+			index += 6
+		}
+	}
+
+	var value string
+	if err := json.Unmarshal(raw, &value); err != nil {
+		return fmt.Errorf("JSON string is invalid: %w", err)
+	}
+	for _, character := range value {
+		if isNoncharacter(character) {
+			return fmt.Errorf("JSON string contains a Unicode noncharacter")
+		}
+	}
+	return nil
+}
+
+func isNoncharacter(character rune) bool {
+	return (character >= 0xfdd0 && character <= 0xfdef) || character&0xfffe == 0xfffe
+}
+
+func decodeValue(decoder *json.Decoder, path string) (any, error) { //nolint:T1 // any 承载封闭 JSON 代数类型。
+	token, err := decoder.Token()
+	if err != nil {
+		return nil, err
+	}
+	delimiter, isDelimiter := token.(json.Delim)
+	if !isDelimiter {
+		switch token.(type) {
+		case nil, bool, string, json.Number:
+			return token, nil
+		default:
+			return nil, fmt.Errorf("unsupported JSON token %T at %s", token, path)
+		}
+	}
+
+	switch delimiter {
+	case '{':
+		object := make(map[string]any)
+		for decoder.More() {
+			keyToken, keyErr := decoder.Token()
+			if keyErr != nil {
+				return nil, keyErr
+			}
+			key, ok := keyToken.(string)
+			if !ok {
+				return nil, fmt.Errorf("object key must be a string at %s", path)
+			}
+			if _, duplicate := object[key]; duplicate {
+				return nil, fmt.Errorf("duplicate object key %q at %s", key, path)
+			}
+			item, itemErr := decodeValue(decoder, path+"."+key)
+			if itemErr != nil {
+				return nil, itemErr
+			}
+			object[key] = item
+		}
+		closing, closingErr := decoder.Token()
+		if closingErr != nil {
+			return nil, closingErr
+		}
+		if closing != json.Delim('}') {
+			return nil, fmt.Errorf("object is not closed at %s", path)
+		}
+		return object, nil
+	case '[':
+		array := make([]any, 0)
+		for index := 0; decoder.More(); index++ {
+			item, itemErr := decodeValue(decoder, fmt.Sprintf("%s[%d]", path, index))
+			if itemErr != nil {
+				return nil, itemErr
+			}
+			array = append(array, item)
+		}
+		closing, closingErr := decoder.Token()
+		if closingErr != nil {
+			return nil, closingErr
+		}
+		if closing != json.Delim(']') {
+			return nil, fmt.Errorf("array is not closed at %s", path)
+		}
+		return array, nil
+	default:
+		return nil, fmt.Errorf("unexpected JSON delimiter %q at %s", delimiter, path)
+	}
+}
+
+func requireEOF(decoder *json.Decoder) error {
+	var trailing json.RawMessage
+	err := decoder.Decode(&trailing)
+	if err == io.EOF {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("decode trailing JSON: %w", err)
+	}
+	return fmt.Errorf("JSON must contain exactly one value")
+}
+
+func appendValue(destination []byte, value any) ([]byte, error) { //nolint:T1 // any 承载封闭 JSON 代数类型。
+	switch typed := value.(type) {
+	case nil:
+		return append(destination, "null"...), nil
+	case bool:
+		return strconv.AppendBool(destination, typed), nil
+	case string:
+		return appendString(destination, typed), nil
+	case json.Number:
+		return appendNumber(destination, typed)
+	case []any:
+		destination = append(destination, '[')
+		for index := range typed {
+			if index > 0 {
+				destination = append(destination, ',')
+			}
+			var err error
+			destination, err = appendValue(destination, typed[index])
+			if err != nil {
+				return nil, err
+			}
+		}
+		return append(destination, ']'), nil
+	case map[string]any:
+		keys := make([]objectKey, 0, len(typed))
+		for key := range typed {
+			keys = append(keys, objectKey{value: key, units: utf16.Encode([]rune(key))})
+		}
+		sort.Slice(keys, func(left int, right int) bool {
+			return lessUTF16(keys[left].units, keys[right].units)
+		})
+		destination = append(destination, '{')
+		for index := range keys {
+			if index > 0 {
+				destination = append(destination, ',')
+			}
+			destination = appendString(destination, keys[index].value)
+			destination = append(destination, ':')
+			var err error
+			destination, err = appendValue(destination, typed[keys[index].value])
+			if err != nil {
+				return nil, err
+			}
+		}
+		return append(destination, '}'), nil
+	default:
+		return nil, fmt.Errorf("unsupported canonical JSON type %T", value)
+	}
+}
+
+type objectKey struct {
+	value string
+	units []uint16
+}
+
+func lessUTF16(left []uint16, right []uint16) bool {
+	limit := min(len(left), len(right))
+	for index := 0; index < limit; index++ {
+		if left[index] != right[index] {
+			return left[index] < right[index]
+		}
+	}
+	return len(left) < len(right)
+}
+
+func appendNumber(destination []byte, number json.Number) ([]byte, error) {
+	value, err := strconv.ParseFloat(number.String(), 64)
+	if err != nil || math.IsInf(value, 0) || math.IsNaN(value) {
+		return nil, fmt.Errorf("number %q is outside the interoperable JSON range", number.String())
+	}
+	if value == 0 {
+		return append(destination, '0'), nil
+	}
+	format := byte('f')
+	absolute := math.Abs(value)
+	if absolute < 1e-6 || absolute >= 1e21 {
+		format = 'e'
+	}
+	start := len(destination)
+	destination = strconv.AppendFloat(destination, value, format, -1, 64)
+	if format == 'e' {
+		exponent := bytes.LastIndexByte(destination[start:], 'e') + start
+		if exponent >= start && exponent+2 < len(destination) && destination[exponent+2] == '0' {
+			copy(destination[exponent+2:], destination[exponent+3:])
+			destination = destination[:len(destination)-1]
+		}
+	}
+	return destination, nil
+}
+
+func appendString(destination []byte, value string) []byte {
+	destination = append(destination, '"')
+	for _, character := range value {
+		switch character {
+		case '"', '\\':
+			destination = append(destination, '\\', byte(character))
+		case '\b':
+			destination = append(destination, `\b`...)
+		case '\t':
+			destination = append(destination, `\t`...)
+		case '\n':
+			destination = append(destination, `\n`...)
+		case '\f':
+			destination = append(destination, `\f`...)
+		case '\r':
+			destination = append(destination, `\r`...)
+		default:
+			if character < 0x20 {
+				destination = append(destination, `\u00`...)
+				destination = append(destination, "0123456789abcdef"[byte(character)>>4], "0123456789abcdef"[byte(character)&0x0f])
+				continue
+			}
+			destination = utf8.AppendRune(destination, character)
+		}
+	}
+	return append(destination, '"')
+}

package/dist/resources/templates/go-backend/internal/common/canonicaljson/canonical_test.go

@@ -0,0 +1,223 @@
+package canonicaljson
+
+import (
+	"bytes"
+	"encoding/json"
+	"math"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+func TestCanonicalizeMatchesRFC8785PrimitiveSerialization(t *testing.T) {
+	t.Parallel()
+
+	raw := json.RawMessage(`{"numbers":[333333333.33333329,1E30,4.50,2e-3,0.000000000000000000000000001,-0],"string":"€$\u000f\nA'B\"\\\\/","literals":[null,true,false]}`)
+	want := `{"literals":[null,true,false],"numbers":[333333333.3333333,1e+30,4.5,0.002,1e-27,0],"string":"€$\u000f\nA'B\"\\\\/"}`
+
+	got, err := Canonicalize(raw)
+	if err != nil {
+		t.Fatalf("Canonicalize() error = %v", err)
+	}
+	if string(got) != want {
+		t.Fatalf("Canonicalize() = %s, want %s", got, want)
+	}
+}
+
+func TestCanonicalizeUsesRFC8785UTF16PropertyOrder(t *testing.T) {
+	t.Parallel()
+
+	raw := json.RawMessage(`{"\u20ac":"Euro Sign","\r":"Carriage Return","\ufb33":"Hebrew Letter Dalet With Dagesh","1":"One","\ud83d\ude00":"Emoji: Grinning Face","\u0080":"Control","\u00f6":"Latin Small Letter O With Diaeresis"}`)
+	want := "{\"\\r\":\"Carriage Return\",\"1\":\"One\",\"\u0080\":\"Control\",\"ö\":\"Latin Small Letter O With Diaeresis\",\"€\":\"Euro Sign\",\"😀\":\"Emoji: Grinning Face\",\"דּ\":\"Hebrew Letter Dalet With Dagesh\"}"
+
+	got, err := Canonicalize(raw)
+	if err != nil {
+		t.Fatalf("Canonicalize() error = %v", err)
+	}
+	if string(got) != want {
+		t.Fatalf("Canonicalize() = %q, want %q", got, want)
+	}
+}
+
+func TestAppendNumberMatchesRFC8785IEEE754Vectors(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		bits uint64
+		want string
+	}{
+		{bits: 0x0000000000000000, want: "0"},
+		{bits: 0x8000000000000000, want: "0"},
+		{bits: 0x0000000000000001, want: "5e-324"},
+		{bits: 0x8000000000000001, want: "-5e-324"},
+		{bits: 0x7fefffffffffffff, want: "1.7976931348623157e+308"},
+		{bits: 0xffefffffffffffff, want: "-1.7976931348623157e+308"},
+		{bits: 0x4340000000000000, want: "9007199254740992"},
+		{bits: 0xc340000000000000, want: "-9007199254740992"},
+		{bits: 0x4430000000000000, want: "295147905179352830000"},
+		{bits: 0x44b52d02c7e14af5, want: "9.999999999999997e+22"},
+		{bits: 0x44b52d02c7e14af6, want: "1e+23"},
+		{bits: 0x44b52d02c7e14af7, want: "1.0000000000000001e+23"},
+		{bits: 0x444b1ae4d6e2ef4e, want: "999999999999999700000"},
+		{bits: 0x444b1ae4d6e2ef4f, want: "999999999999999900000"},
+		{bits: 0x444b1ae4d6e2ef50, want: "1e+21"},
+		{bits: 0x3eb0c6f7a0b5ed8c, want: "9.999999999999997e-7"},
+		{bits: 0x3eb0c6f7a0b5ed8d, want: "0.000001"},
+		{bits: 0x41b3de4355555553, want: "333333333.3333332"},
+		{bits: 0x41b3de4355555554, want: "333333333.33333325"},
+		{bits: 0x41b3de4355555555, want: "333333333.3333333"},
+		{bits: 0x41b3de4355555556, want: "333333333.3333334"},
+		{bits: 0x41b3de4355555557, want: "333333333.33333343"},
+		{bits: 0xbecbf647612f3696, want: "-0.0000033333333333333333"},
+		{bits: 0x43143ff3c1cb0959, want: "1424953923781206.2"},
+	}
+	for _, test := range tests {
+		value := math.Float64frombits(test.bits)
+		number := json.Number(strconv.FormatFloat(value, 'g', -1, 64))
+		got, err := appendNumber(nil, number)
+		if err != nil {
+			t.Fatalf("appendNumber(%016x) error = %v", test.bits, err)
+		}
+		if string(got) != test.want {
+			t.Fatalf("appendNumber(%016x) = %s, want %s", test.bits, got, test.want)
+		}
+	}
+}
+
+func TestCanonicalizeRejectsNonIJSONInputs(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		raw  json.RawMessage
+	}{
+		{name: "empty", raw: nil},
+		{name: "invalid UTF-8", raw: json.RawMessage{'"', 0xff, '"'}},
+		{name: "duplicate decoded key", raw: json.RawMessage(`{"key":1,"\u006bey":2}`)},
+		{name: "high surrogate", raw: json.RawMessage(`{"value":"\ud800"}`)},
+		{name: "low surrogate", raw: json.RawMessage(`{"value":"\udc00"}`)},
+		{name: "BMP noncharacter", raw: json.RawMessage(`{"value":"\ufdd0"}`)},
+		{name: "supplementary noncharacter", raw: json.RawMessage(`{"value":"\ud83f\udffe"}`)},
+		{name: "number outside binary64", raw: json.RawMessage(`{"value":1e400}`)},
+		{name: "trailing value", raw: json.RawMessage(`{} []`)},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			if _, err := Canonicalize(test.raw); err == nil {
+				t.Fatalf("Canonicalize(%q) error = nil", test.raw)
+			}
+		})
+	}
+}
+
+func TestCanonicalizeEquivalentInputsShareBytesAndHashes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		left     json.RawMessage
+		right    json.RawMessage
+		want     string
+		wantHash string
+	}{
+		{
+			name:     "nested object and numeric forms",
+			left:     json.RawMessage(`{"z":1.0,"small":0.000001,"n":1e21,"a":{"b":true,"a":"x"}}`),
+			right:    json.RawMessage(`{"a":{"a":"x","b":true},"n":1e+21,"small":0.000001,"z":1}`),
+			want:     `{"a":{"a":"x","b":true},"n":1e+21,"small":0.000001,"z":1}`,
+			wantHash: "8b59d78b6f9cd132fea29903ef7ac593453222c35f6d595923135cd15422108f",
+		},
+		{
+			name:     "unicode key and escaping forms",
+			left:     json.RawMessage(`{"\ue000":2,"\ud800\udc00":1,"text":"<>&\u2028\u2029/"}`),
+			right:    json.RawMessage("{\"text\":\"<>&\u2028\u2029/\",\"𐀀\":1,\"\":2}"),
+			want:     "{\"text\":\"<>&\u2028\u2029/\",\"𐀀\":1,\"\":2}",
+			wantHash: "e88ff65eea77a6831a89c548276e9c8b22e07d3a0b7b05b29e40f35c8ec715d2",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			left, err := Canonicalize(test.left)
+			if err != nil {
+				t.Fatalf("Canonicalize(left) error = %v", err)
+			}
+			right, err := Canonicalize(test.right)
+			if err != nil {
+				t.Fatalf("Canonicalize(right) error = %v", err)
+			}
+			if !bytes.Equal(left, right) || string(left) != test.want {
+				t.Fatalf("canonical bytes = %q / %q, want %q", left, right, test.want)
+			}
+			leftHash, err := Hash(test.left)
+			if err != nil {
+				t.Fatalf("Hash(left) error = %v", err)
+			}
+			rightHash, err := Hash(test.right)
+			if err != nil {
+				t.Fatalf("Hash(right) error = %v", err)
+			}
+			if leftHash != rightHash {
+				t.Fatalf("hashes differ: %s != %s", leftHash, rightHash)
+			}
+			if test.wantHash != "" && leftHash != test.wantHash {
+				t.Fatalf("Hash() = %s, want %s", leftHash, test.wantHash)
+			}
+		})
+	}
+}
+
+func TestHashValueEqualAndIsHash(t *testing.T) {
+	t.Parallel()
+
+	valueHash, err := HashValue(struct {
+		Enabled bool            `json:"enabled"`
+		Config  json.RawMessage `json:"config"`
+	}{Enabled: true, Config: json.RawMessage(`{"b":2,"a":1}`)})
+	if err != nil {
+		t.Fatalf("HashValue() error = %v", err)
+	}
+	rawHash, err := Hash(json.RawMessage(`{"config":{"a":1,"b":2},"enabled":true}`))
+	if err != nil {
+		t.Fatalf("Hash() error = %v", err)
+	}
+	if valueHash != rawHash || !IsHash(valueHash) {
+		t.Fatalf("hashes = %s / %s", valueHash, rawHash)
+	}
+	if IsHash(strings.ToUpper(valueHash)) || IsHash(valueHash[:len(valueHash)-1]) {
+		t.Fatal("IsHash() accepted a non-canonical hash")
+	}
+
+	equal, err := Equal(json.RawMessage(`{"b":2,"a":1}`), json.RawMessage(`{"a":1,"b":2}`))
+	if err != nil || !equal {
+		t.Fatalf("Equal() = %v, %v", equal, err)
+	}
+	if _, err := Equal(json.RawMessage(`{"a":1}`), json.RawMessage(`{"a":`)); err == nil {
+		t.Fatal("Equal() error = nil for invalid right JSON")
+	}
+}
+
+func FuzzCanonicalize(f *testing.F) {
+	for _, seed := range [][]byte{
+		[]byte(`null`),
+		[]byte(`{"a":[1,true,"value"]}`),
+		[]byte(`{"key":1,"\u006bey":2}`),
+		[]byte(`{"value":"\ud800"}`),
+	} {
+		f.Add(seed)
+	}
+	f.Fuzz(func(t *testing.T, raw []byte) {
+		first, err := Canonicalize(raw)
+		if err != nil {
+			return
+		}
+		second, err := Canonicalize(first)
+		if err != nil {
+			t.Fatalf("Canonicalize(canonical) error = %v", err)
+		}
+		if !bytes.Equal(first, second) {
+			t.Fatalf("canonicalization is not idempotent: %q != %q", first, second)
+		}
+	})
+}