@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,184 @@
+package ruleexpression
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"unicode/utf8"
+)
+
+const canonicalHexDigits = "0123456789abcdef"
+
+// CanonicalJSON 按 RFC 8785 生成 Expression V1 的 canonical UTF-8 JSON。
+func CanonicalJSON(expression ExpressionV1) ([]byte, error) {
+	if err := validateExpression(expression); err != nil {
+		return nil, err
+	}
+	output := make([]byte, 0, 512)
+	output = append(output, `{"root":`...)
+	var err error
+	output, err = appendCanonicalNode(output, expression.Root, "$.root")
+	if err != nil {
+		return nil, err
+	}
+	output = append(output, `,"schema_version":1}`...)
+	if len(output) > MaxJSONBytes {
+		return nil, newError(ErrorCodeLimitExceeded, "$", fmt.Sprintf("canonical JSON size must not exceed %d bytes", MaxJSONBytes))
+	}
+	return output, nil
+}
+
+// CanonicalHash 返回 canonical JSON 的 64 位小写十六进制 SHA-256。
+func CanonicalHash(expression ExpressionV1) (string, error) {
+	canonical, err := CanonicalJSON(expression)
+	if err != nil {
+		return "", err
+	}
+	digest := sha256.Sum256(canonical)
+	return hex.EncodeToString(digest[:]), nil
+}
+
+// MarshalJSON 始终输出 canonical JSON，避免持久化路径产生第二种编码。
+func (e ExpressionV1) MarshalJSON() ([]byte, error) {
+	return CanonicalJSON(e)
+}
+
+func appendCanonicalNode(output []byte, node Node, path string) ([]byte, error) {
+	switch current := node.(type) {
+	case *AllNode:
+		output = append(output, `{"children":[`...)
+		for i := range current.Children {
+			if i > 0 {
+				output = append(output, ',')
+			}
+			var err error
+			output, err = appendCanonicalNode(output, current.Children[i], fmt.Sprintf("%s.children[%d]", path, i))
+			if err != nil {
+				return nil, err
+			}
+		}
+		return append(output, `],"kind":"all"}`...), nil
+	case *AnyNode:
+		output = append(output, `{"children":[`...)
+		for i := range current.Children {
+			if i > 0 {
+				output = append(output, ',')
+			}
+			var err error
+			output, err = appendCanonicalNode(output, current.Children[i], fmt.Sprintf("%s.children[%d]", path, i))
+			if err != nil {
+				return nil, err
+			}
+		}
+		return append(output, `],"kind":"any"}`...), nil
+	case *NotNode:
+		output = append(output, `{"child":`...)
+		var err error
+		output, err = appendCanonicalNode(output, current.Child, path+".child")
+		if err != nil {
+			return nil, err
+		}
+		return append(output, `,"kind":"not"}`...), nil
+	case *PredicateNode:
+		output = append(output, `{"key":`...)
+		var err error
+		output, err = appendCanonicalString(output, current.Key, path+".key")
+		if err != nil {
+			return nil, err
+		}
+		output = append(output, `,"kind":"predicate","operator":`...)
+		output, err = appendCanonicalString(output, string(current.Operator), path+".operator")
+		if err != nil {
+			return nil, err
+		}
+		output = append(output, `,"subject":`...)
+		output, err = appendCanonicalString(output, string(current.Subject), path+".subject")
+		if err != nil {
+			return nil, err
+		}
+		if current.Value != nil {
+			output = append(output, `,"value":`...)
+			output, err = appendCanonicalValue(output, current.Value, path+".value")
+			if err != nil {
+				return nil, err
+			}
+		}
+		return append(output, '}'), nil
+	default:
+		return nil, newError(ErrorCodeInvalidNode, path, "node kind is not supported")
+	}
+}
+
+func appendCanonicalValue(output []byte, value Value, path string) ([]byte, error) {
+	switch current := value.(type) {
+	case *BooleanValue:
+		if current.Value {
+			return append(output, "true"...), nil
+		}
+		return append(output, "false"...), nil
+	case *NumberValue:
+		if current.Value == 0 {
+			return append(output, '0'), nil
+		}
+		encoded, err := json.Marshal(current.Value)
+		if err != nil {
+			return nil, wrapError(ErrorCodeInvalidNumber, path, "number cannot be canonically encoded", err)
+		}
+		return append(output, encoded...), nil
+	case *StringValue:
+		return appendCanonicalString(output, current.Value, path)
+	case *StringArrayValue:
+		output = append(output, '[')
+		for i := range current.Values {
+			if i > 0 {
+				output = append(output, ',')
+			}
+			var err error
+			output, err = appendCanonicalString(output, current.Values[i], fmt.Sprintf("%s[%d]", path, i))
+			if err != nil {
+				return nil, err
+			}
+		}
+		return append(output, ']'), nil
+	default:
+		return nil, newError(ErrorCodeInvalidPredicate, path, "value type is not supported")
+	}
+}
+
+func appendCanonicalString(output []byte, value string, path string) ([]byte, error) {
+	if !utf8.ValidString(value) {
+		return nil, newError(ErrorCodeInvalidUnicode, path, "string must contain valid Unicode")
+	}
+	output = append(output, '"')
+	for _, character := range value {
+		switch character {
+		case '"':
+			output = append(output, '\\', '"')
+		case '\\':
+			output = append(output, '\\', '\\')
+		case '\b':
+			output = append(output, '\\', 'b')
+		case '\t':
+			output = append(output, '\\', 't')
+		case '\n':
+			output = append(output, '\\', 'n')
+		case '\f':
+			output = append(output, '\\', 'f')
+		case '\r':
+			output = append(output, '\\', 'r')
+		default:
+			if character < 0x20 {
+				output = append(
+					output,
+					'\\', 'u', '0', '0',
+					canonicalHexDigits[byte(character)>>4],
+					canonicalHexDigits[byte(character)&0x0f],
+				)
+				continue
+			}
+			output = utf8.AppendRune(output, character)
+		}
+	}
+	return append(output, '"'), nil
+}

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

@@ -0,0 +1,319 @@
+package ruleexpression
+
+import (
+	"bytes"
+	"encoding/json"
+	"math"
+	"strings"
+	"testing"
+
+	"{{module}}/internal/common/canonicaljson"
+)
+
+func TestCanonicalJSONIsDeterministicAcrossInputRepresentations(t *testing.T) {
+	t.Parallel()
+
+	inputs := [][]byte{
+		[]byte(`{"root":{"value":4.50,"operator":"eq","key":"score","subject":"attribute","kind":"predicate"},"schema_version":1}`),
+		[]byte(" { \n \t\"schema_version\" : 1 , \"root\" : { \"kind\" : \"predicate\", \"subject\" : \"attribute\", \"key\" : \"score\", \"operator\" : \"eq\", \"value\" : 4.5 } } "),
+	}
+	want := []byte(`{"root":{"key":"score","kind":"predicate","operator":"eq","subject":"attribute","value":4.5},"schema_version":1}`)
+	var firstHash string
+	for i := range inputs {
+		expression, err := Decode(inputs[i])
+		if err != nil {
+			t.Fatalf("Decode(%d) error = %v", i, err)
+		}
+		canonical, err := CanonicalJSON(expression)
+		if err != nil {
+			t.Fatalf("CanonicalJSON(%d) error = %v", i, err)
+		}
+		if !bytes.Equal(canonical, want) {
+			t.Fatalf("CanonicalJSON(%d) = %s, want %s", i, canonical, want)
+		}
+		hash, err := CanonicalHash(expression)
+		if err != nil {
+			t.Fatalf("CanonicalHash(%d) error = %v", i, err)
+		}
+		if len(hash) != 64 {
+			t.Fatalf("CanonicalHash(%d) length = %d, want 64", i, len(hash))
+		}
+		if i == 0 {
+			firstHash = hash
+		} else if hash != firstHash {
+			t.Fatalf("CanonicalHash(%d) = %s, want %s", i, hash, firstHash)
+		}
+	}
+	if firstHash != "bf2977ca6b197af78d7c1e6611ed92d4483d85b1904b4e0e6864da9144b36494" {
+		t.Fatalf("CanonicalHash() = %s, want golden hash", firstHash)
+	}
+}
+
+func TestCanonicalJSONOrdersFieldsForEveryNodeKind(t *testing.T) {
+	t.Parallel()
+
+	expression := expressionWithRoot(&AllNode{Children: []Node{
+		&AnyNode{Children: []Node{
+			&PredicateNode{Subject: SubjectCapability, Key: "billing", Operator: OperatorActive},
+		}},
+		&NotNode{Child: &PredicateNode{
+			Subject: SubjectAttribute, Key: "region", Operator: OperatorEqual,
+			Value: &StringValue{Value: "west"},
+		}},
+	}})
+	canonical, err := CanonicalJSON(expression)
+	if err != nil {
+		t.Fatalf("CanonicalJSON() error = %v", err)
+	}
+	want := []byte(`{"root":{"children":[{"children":[{"key":"billing","kind":"predicate","operator":"active","subject":"capability"}],"kind":"any"},{"child":{"key":"region","kind":"predicate","operator":"eq","subject":"attribute","value":"west"},"kind":"not"}],"kind":"all"},"schema_version":1}`)
+	if !bytes.Equal(canonical, want) {
+		t.Fatalf("CanonicalJSON() = %s, want %s", canonical, want)
+	}
+}
+
+func TestCanonicalJSONMatchesRFC8785PrimitiveSerialization(t *testing.T) {
+	t.Parallel()
+
+	numberTests := []struct {
+		input string
+		want  string
+	}{
+		{input: "333333333.33333329", want: "333333333.3333333"},
+		{input: "1E30", want: "1e+30"},
+		{input: "4.50", want: "4.5"},
+		{input: "2e-3", want: "0.002"},
+		{input: "1e-27", want: "1e-27"},
+		{input: "-0", want: "0"},
+	}
+	for _, test := range numberTests {
+		t.Run(test.input, func(t *testing.T) {
+			t.Parallel()
+			raw := []byte(`{"schema_version":1,"root":{"kind":"predicate","subject":"attribute","key":"number","operator":"eq","value":` + test.input + `}}`)
+			expression, err := Decode(raw)
+			if err != nil {
+				t.Fatalf("Decode() error = %v", err)
+			}
+			canonical, err := CanonicalJSON(expression)
+			if err != nil {
+				t.Fatalf("CanonicalJSON() error = %v", err)
+			}
+			want := []byte(`{"root":{"key":"number","kind":"predicate","operator":"eq","subject":"attribute","value":` + test.want + `},"schema_version":1}`)
+			if !bytes.Equal(canonical, want) {
+				t.Fatalf("CanonicalJSON() = %s, want %s", canonical, want)
+			}
+		})
+	}
+
+	value := "€$\x0f\nA'B\"\\/<>&\u2028"
+	expression := expressionWithRoot(&PredicateNode{
+		Subject:  SubjectAttribute,
+		Key:      "label",
+		Operator: OperatorEqual,
+		Value:    &StringValue{Value: value},
+	})
+	canonical, err := CanonicalJSON(expression)
+	if err != nil {
+		t.Fatalf("CanonicalJSON() string error = %v", err)
+	}
+	if !bytes.Contains(canonical, []byte(`"value":"€$\u000f\nA'B\"\\/<>&`)) {
+		t.Fatalf("CanonicalJSON() string encoding = %s", canonical)
+	}
+	for _, forbidden := range [][]byte{[]byte(`\u003c`), []byte(`\u003e`), []byte(`\u0026`), []byte(`\u2028`)} {
+		if bytes.Contains(canonical, forbidden) {
+			t.Fatalf("CanonicalJSON() contains non-canonical escape %s: %s", forbidden, canonical)
+		}
+	}
+}
+
+func TestCanonicalJSONMatchesCommonCanonicalOwner(t *testing.T) {
+	t.Parallel()
+
+	expression := expressionWithRoot(&PredicateNode{
+		Subject:  SubjectAttribute,
+		Key:      "score",
+		Operator: OperatorEqual,
+		Value:    &NumberValue{Value: 333333333.33333329},
+	})
+	typedCanonical, err := CanonicalJSON(expression)
+	if err != nil {
+		t.Fatalf("CanonicalJSON() error = %v", err)
+	}
+	commonCanonical, err := canonicaljson.Canonicalize(typedCanonical)
+	if err != nil {
+		t.Fatalf("canonicaljson.Canonicalize() error = %v", err)
+	}
+	if !bytes.Equal(typedCanonical, commonCanonical) {
+		t.Fatalf("canonical encoders differ: %s != %s", typedCanonical, commonCanonical)
+	}
+
+	typedHash, err := CanonicalHash(expression)
+	if err != nil {
+		t.Fatalf("CanonicalHash() error = %v", err)
+	}
+	commonHash, err := canonicaljson.Hash(typedCanonical)
+	if err != nil {
+		t.Fatalf("canonicaljson.Hash() error = %v", err)
+	}
+	if typedHash != commonHash {
+		t.Fatalf("canonical hashes differ: %s != %s", typedHash, commonHash)
+	}
+}
+
+func TestCanonicalJSONMatchesRFC8785NumberVectors(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		bits uint64
+		want string
+	}{
+		{0x0000000000000000, "0"},
+		{0x8000000000000000, "0"},
+		{0x0000000000000001, "5e-324"},
+		{0x8000000000000001, "-5e-324"},
+		{0x7fefffffffffffff, "1.7976931348623157e+308"},
+		{0xffefffffffffffff, "-1.7976931348623157e+308"},
+		{0x4340000000000000, "9007199254740992"},
+		{0xc340000000000000, "-9007199254740992"},
+		{0x4430000000000000, "295147905179352830000"},
+		{0x44b52d02c7e14af5, "9.999999999999997e+22"},
+		{0x44b52d02c7e14af6, "1e+23"},
+		{0x44b52d02c7e14af7, "1.0000000000000001e+23"},
+		{0x444b1ae4d6e2ef4e, "999999999999999700000"},
+		{0x444b1ae4d6e2ef4f, "999999999999999900000"},
+		{0x444b1ae4d6e2ef50, "1e+21"},
+		{0x3eb0c6f7a0b5ed8c, "9.999999999999997e-7"},
+		{0x3eb0c6f7a0b5ed8d, "0.000001"},
+		{0x41b3de4355555553, "333333333.3333332"},
+		{0x41b3de4355555554, "333333333.33333325"},
+		{0x41b3de4355555555, "333333333.3333333"},
+		{0x41b3de4355555556, "333333333.3333334"},
+		{0x41b3de4355555557, "333333333.33333343"},
+		{0xbecbf647612f3696, "-0.0000033333333333333333"},
+		{0x43143ff3c1cb0959, "1424953923781206.2"},
+	}
+	for _, test := range tests {
+		expression := expressionWithRoot(&PredicateNode{
+			Subject:  SubjectAttribute,
+			Key:      "number",
+			Operator: OperatorEqual,
+			Value:    &NumberValue{Value: math.Float64frombits(test.bits)},
+		})
+		canonical, err := CanonicalJSON(expression)
+		if err != nil {
+			t.Fatalf("CanonicalJSON(%016x) error = %v", test.bits, err)
+		}
+		want := []byte(`"value":` + test.want + `}`)
+		if !bytes.Contains(canonical, want) {
+			t.Fatalf("CanonicalJSON(%016x) = %s, want suffix %s", test.bits, canonical, want)
+		}
+	}
+}
+
+func TestCanonicalJSONPreservesArrayOrderAndRoundTrips(t *testing.T) {
+	t.Parallel()
+
+	expression := expressionWithRoot(&PredicateNode{
+		Subject:  SubjectAttribute,
+		Key:      "commerce_model",
+		Operator: OperatorIn,
+		Value:    &StringArrayValue{Values: []string{"saas", "physical_goods"}},
+	})
+	canonical, err := CanonicalJSON(expression)
+	if err != nil {
+		t.Fatalf("CanonicalJSON() error = %v", err)
+	}
+	if !bytes.Contains(canonical, []byte(`"value":["saas","physical_goods"]`)) {
+		t.Fatalf("CanonicalJSON() changed array order: %s", canonical)
+	}
+
+	marshaled, err := json.Marshal(expression)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	if !bytes.Equal(marshaled, canonical) {
+		t.Fatalf("json.Marshal() = %s, want %s", marshaled, canonical)
+	}
+	decoded, err := Decode(canonical)
+	if err != nil {
+		t.Fatalf("Decode(canonical) error = %v", err)
+	}
+	roundTrip, err := CanonicalJSON(decoded)
+	if err != nil {
+		t.Fatalf("CanonicalJSON(round trip) error = %v", err)
+	}
+	if !bytes.Equal(roundTrip, canonical) {
+		t.Fatalf("round trip = %s, want %s", roundTrip, canonical)
+	}
+}
+
+func TestCanonicalHashChangesWithSemantics(t *testing.T) {
+	t.Parallel()
+
+	left := expressionWithRoot(&PredicateNode{Subject: SubjectCapability, Key: "billing", Operator: OperatorActive})
+	right := expressionWithRoot(&PredicateNode{Subject: SubjectCapability, Key: "billing", Operator: OperatorInactive})
+	leftHash, err := CanonicalHash(left)
+	if err != nil {
+		t.Fatalf("CanonicalHash(left) error = %v", err)
+	}
+	rightHash, err := CanonicalHash(right)
+	if err != nil {
+		t.Fatalf("CanonicalHash(right) error = %v", err)
+	}
+	if leftHash == rightHash {
+		t.Fatalf("semantic change retained hash %s", leftHash)
+	}
+}
+
+func TestCanonicalJSONRejectsInvalidProgrammaticAST(t *testing.T) {
+	t.Parallel()
+
+	notANumber := expressionWithRoot(&PredicateNode{
+		Subject:  SubjectAttribute,
+		Key:      "number",
+		Operator: OperatorEqual,
+		Value:    &NumberValue{Value: math.NaN()},
+	})
+	_, err := CanonicalJSON(notANumber)
+	assertErrorCode(t, err, ErrorCodeInvalidNumber)
+
+	cycle := &NotNode{}
+	cycle.Child = cycle
+	_, err = CanonicalJSON(expressionWithRoot(cycle))
+	assertErrorCode(t, err, ErrorCodeInvalidNode)
+
+	for _, value := range []float64{math.Inf(1), math.Inf(-1)} {
+		invalid := expressionWithRoot(&PredicateNode{
+			Subject: SubjectAttribute, Key: "number", Operator: OperatorEqual,
+			Value: &NumberValue{Value: value},
+		})
+		_, err = CanonicalJSON(invalid)
+		assertErrorCode(t, err, ErrorCodeInvalidNumber)
+	}
+
+	noncharacter := expressionWithRoot(&PredicateNode{
+		Subject: SubjectAttribute, Key: "label", Operator: OperatorEqual,
+		Value: &StringValue{Value: "\ufdd0"},
+	})
+	_, err = CanonicalJSON(noncharacter)
+	assertErrorCode(t, err, ErrorCodeInvalidUnicode)
+}
+
+func TestCanonicalJSONEnforcesEncodedSizeLimit(t *testing.T) {
+	t.Parallel()
+
+	item := strings.Repeat("x", MaxStringLength)
+	values := make([]string, MaxStringArrayItems)
+	for i := range values {
+		values[i] = item
+	}
+	children := make([]Node, 4)
+	for i := range children {
+		children[i] = &PredicateNode{
+			Subject: SubjectAttribute, Key: "attribute_" + string(rune('a'+i)), Operator: OperatorIn,
+			Value: &StringArrayValue{Values: values},
+		}
+	}
+
+	_, err := CanonicalJSON(expressionWithRoot(&AllNode{Children: children}))
+	assertErrorCode(t, err, ErrorCodeLimitExceeded)
+}