@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/crypto/aes_gcm_test.go

@@ -0,0 +1,364 @@
+package crypto
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// validKey 是合法的 64 字符 hex 字符串（32 字节 AES-256 密钥）
+const validKey = "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
+
+// --------------------------------------------------------
+// NewAesGcmEncryptor
+// --------------------------------------------------------
+
+func TestNewAesGcmEncryptor(t *testing.T) {
+	tests := []struct {
+		name    string
+		key     string
+		wantErr bool
+		errMsg  string
+	}{
+		{
+			name:    "合法 64 字符 hex 密钥",
+			key:     validKey,
+			wantErr: false,
+		},
+		{
+			name:    "空密钥",
+			key:     "",
+			wantErr: true,
+		},
+		{
+			name:    "密钥太短（32 字符 = 16 字节）",
+			key:     "0102030405060708090a0b0c0d0e0f10",
+			wantErr: true,
+			errMsg:  "32 bytes",
+		},
+		{
+			name:    "密钥太长（96 字符 = 48 字节）",
+			key:     "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f200102030405060708090a0b0c0d0e0f10",
+			wantErr: true,
+			errMsg:  "32 bytes",
+		},
+		{
+			name:    "非法 hex 字符",
+			key:     "gggggggggggggggggggggggggggggggggggggggggggggggggggggggggggggggg",
+			wantErr: true,
+			errMsg:  "invalid encryption key format",
+		},
+		{
+			name:    "奇数长度 hex（无法 decode）",
+			key:     "abc",
+			wantErr: true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			enc, err := NewAesGcmEncryptor(tc.key)
+			if tc.wantErr {
+				require.Error(t, err)
+				if tc.errMsg != "" {
+					assert.Contains(t, err.Error(), tc.errMsg)
+				}
+				assert.Nil(t, enc)
+			} else {
+				require.NoError(t, err)
+				assert.NotNil(t, enc)
+			}
+		})
+	}
+}
+
+// --------------------------------------------------------
+// Encrypt + Decrypt 往返
+// --------------------------------------------------------
+
+func TestAesGcmEncryptor_RoundTrip(t *testing.T) {
+	enc, err := NewAesGcmEncryptor(validKey)
+	require.NoError(t, err)
+
+	tests := []struct {
+		name      string
+		plaintext string
+	}{
+		{
+			name:      "普通 ASCII 字符串",
+			plaintext: "hello, world",
+		},
+		{
+			name:      "空字符串",
+			plaintext: "",
+		},
+		{
+			name:      "Unicode / 多字节字符串",
+			plaintext: "你好，世界 🌍 こんにちは مرحبا",
+		},
+		{
+			name:      "包含特殊字符",
+			plaintext: "!@#$%^&*()_+-=[]{}|;':\",./<>?",
+		},
+		{
+			name:      "超长字符串（10 KB+）",
+			plaintext: strings.Repeat("abcdefghij", 1024), // 10240 字节
+		},
+		{
+			name:      "换行与制表符",
+			plaintext: "line1\nline2\ttabbed",
+		},
+		{
+			name:      "JSON 格式字符串",
+			plaintext: `{"user_id":42,"token":"secret-token-value","scope":["read","write"]}`,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			ciphertext, err := enc.Encrypt(tc.plaintext)
+			require.NoError(t, err)
+			assert.NotEmpty(t, ciphertext)
+
+			decrypted, err := enc.Decrypt(ciphertext)
+			require.NoError(t, err)
+			assert.Equal(t, tc.plaintext, decrypted)
+		})
+	}
+}
+
+// --------------------------------------------------------
+// 不同明文产生不同密文
+// --------------------------------------------------------
+
+func TestAesGcmEncryptor_DifferentPlaintextsProduceDifferentCiphertexts(t *testing.T) {
+	enc, err := NewAesGcmEncryptor(validKey)
+	require.NoError(t, err)
+
+	plaintexts := []string{
+		"message one",
+		"message two",
+		"message three",
+	}
+
+	ciphertexts := make([]string, len(plaintexts))
+	for i, pt := range plaintexts {
+		ct, err := enc.Encrypt(pt)
+		require.NoError(t, err)
+		ciphertexts[i] = ct
+	}
+
+	// 所有密文互不相同
+	for i := 0; i < len(ciphertexts); i++ {
+		for j := i + 1; j < len(ciphertexts); j++ {
+			assert.NotEqual(t, ciphertexts[i], ciphertexts[j],
+				"plaintext[%d] 和 plaintext[%d] 不同，密文也应不同", i, j)
+		}
+	}
+}
+
+// --------------------------------------------------------
+// 相同明文两次加密产生不同密文（随机 nonce）
+// --------------------------------------------------------
+
+func TestAesGcmEncryptor_SamePlaintextProducesDifferentCiphertexts(t *testing.T) {
+	enc, err := NewAesGcmEncryptor(validKey)
+	require.NoError(t, err)
+
+	plaintext := "same input"
+	const iterations = 5
+
+	ciphertexts := make([]string, iterations)
+	for i := range ciphertexts {
+		ct, err := enc.Encrypt(plaintext)
+		require.NoError(t, err)
+		ciphertexts[i] = ct
+	}
+
+	// 每次加密结果互不相同（随机 nonce 保证）
+	seen := make(map[string]bool)
+	for _, ct := range ciphertexts {
+		assert.False(t, seen[ct], "发现重复密文，随机 nonce 失效: %s", ct)
+		seen[ct] = true
+	}
+}
+
+// --------------------------------------------------------
+// Decrypt 异常场景
+// --------------------------------------------------------
+
+func TestAesGcmEncryptor_DecryptFailures(t *testing.T) {
+	enc, err := NewAesGcmEncryptor(validKey)
+	require.NoError(t, err)
+
+	tests := []struct {
+		name       string
+		ciphertext string
+	}{
+		{
+			name:       "非法 base64 字符串",
+			ciphertext: "!!!not-base64!!!",
+		},
+		{
+			name:       "base64 但数据太短（短于 nonce）",
+			ciphertext: "dG9vc2hvcnQ=", // "tooshort" in base64，< 12 字节 nonce
+		},
+		{
+			name: "正确格式但 auth tag 被篡改",
+			ciphertext: func() string {
+				ct, _ := enc.Encrypt("original plaintext")
+				// 将最后一个字符替换掉，破坏 auth tag
+				if ct[len(ct)-1] == 'A' {
+					return ct[:len(ct)-1] + "B"
+				}
+				return ct[:len(ct)-1] + "A"
+			}(),
+		},
+		{
+			name:       "空字符串",
+			ciphertext: "",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result, err := enc.Decrypt(tc.ciphertext)
+			require.Error(t, err)
+			assert.Empty(t, result)
+		})
+	}
+}
+
+// --------------------------------------------------------
+// 密文被整体篡改（nonce 区域修改）
+// --------------------------------------------------------
+
+func TestAesGcmEncryptor_TamperedNonce(t *testing.T) {
+	enc, err := NewAesGcmEncryptor(validKey)
+	require.NoError(t, err)
+
+	plaintext := "tamper test"
+	ciphertext, err := enc.Encrypt(plaintext)
+	require.NoError(t, err)
+
+	// 将 base64 字符串首字节改掉，破坏 nonce 区域
+	tampered := []byte(ciphertext)
+	if tampered[0] == 'A' {
+		tampered[0] = 'B'
+	} else {
+		tampered[0] = 'A'
+	}
+
+	_, err = enc.Decrypt(string(tampered))
+	assert.Error(t, err)
+}
+
+// --------------------------------------------------------
+// 不同密钥无法互解
+// --------------------------------------------------------
+
+func TestAesGcmEncryptor_WrongKeyCannotDecrypt(t *testing.T) {
+	key1 := "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
+	key2 := "aabbccddeeff00112233445566778899aabbccddeeff001122334455667788aa"
+
+	enc1, err := NewAesGcmEncryptor(key1)
+	require.NoError(t, err)
+
+	enc2, err := NewAesGcmEncryptor(key2)
+	require.NoError(t, err)
+
+	ciphertext, err := enc1.Encrypt("secret message")
+	require.NoError(t, err)
+
+	_, err = enc2.Decrypt(ciphertext)
+	assert.Error(t, err, "用错误密钥解密应返回错误")
+}
+
+// --------------------------------------------------------
+// NoopEncryptor
+// --------------------------------------------------------
+
+func TestNoopEncryptor(t *testing.T) {
+	noop := &NoopEncryptor{}
+
+	tests := []struct {
+		name  string
+		input string
+	}{
+		{name: "普通字符串", input: "hello"},
+		{name: "空字符串", input: ""},
+		{name: "Unicode 字符串", input: "你好 🌍"},
+		{name: "含特殊字符", input: "!@#$%^&*"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			encrypted, err := noop.Encrypt(tc.input)
+			require.NoError(t, err)
+			assert.Equal(t, tc.input, encrypted, "NoopEncryptor.Encrypt 应原样返回输入")
+
+			decrypted, err := noop.Decrypt(tc.input)
+			require.NoError(t, err)
+			assert.Equal(t, tc.input, decrypted, "NoopEncryptor.Decrypt 应原样返回输入")
+		})
+	}
+}
+
+// --------------------------------------------------------
+// ProvideEncryptor
+// --------------------------------------------------------
+
+func TestProvideEncryptor(t *testing.T) {
+	logger, err := zap.NewDevelopment()
+	require.NoError(t, err)
+
+	t.Run("有效密钥返回 AesGcmEncryptor", func(t *testing.T) {
+		cfg := &config.Config{EncryptionKey: validKey}
+		enc, err := ProvideEncryptor(cfg, logger)
+		require.NoError(t, err)
+		require.NotNil(t, enc)
+
+		// 验证返回的是真正的 AES-GCM 加密器（加密后密文与明文不同）
+		plaintext := "probe text"
+		ciphertext, err := enc.Encrypt(plaintext)
+		require.NoError(t, err)
+		assert.NotEqual(t, plaintext, ciphertext)
+
+		// 可往返解密
+		decrypted, err := enc.Decrypt(ciphertext)
+		require.NoError(t, err)
+		assert.Equal(t, plaintext, decrypted)
+	})
+
+	t.Run("空密钥返回 NoopEncryptor", func(t *testing.T) {
+		cfg := &config.Config{EncryptionKey: ""}
+		enc, err := ProvideEncryptor(cfg, logger)
+		require.NoError(t, err)
+		require.NotNil(t, enc)
+
+		// NoopEncryptor 加密后与明文相同
+		plaintext := "noop test"
+		ciphertext, err := enc.Encrypt(plaintext)
+		require.NoError(t, err)
+		assert.Equal(t, plaintext, ciphertext)
+	})
+
+	t.Run("生产环境空密钥返回错误", func(t *testing.T) {
+		cfg := &config.Config{App: config.AppConfig{Env: "production"}}
+		enc, err := ProvideEncryptor(cfg, logger)
+		require.Error(t, err)
+		assert.Nil(t, enc)
+	})
+
+	t.Run("非法密钥返回错误", func(t *testing.T) {
+		cfg := &config.Config{EncryptionKey: "not-a-valid-hex-key"}
+		enc, err := ProvideEncryptor(cfg, logger)
+		require.Error(t, err)
+		assert.Nil(t, enc)
+	})
+}

package/dist/resources/templates/go-backend/internal/core/crypto/encryptor.go

@@ -0,0 +1,12 @@
+package crypto
+
+// Encryptor 加解密接口
+//
+// 所有需要加解密的模块（Identity OAuth token、Tenant 凭证、Storage 凭证、
+// Payment 网关密钥等）统一通过此接口注入。
+type Encryptor interface {
+	// Encrypt 加密明文，返回密文字符串
+	Encrypt(plaintext string) (string, error)
+	// Decrypt 解密密文，返回明文字符串
+	Decrypt(ciphertext string) (string, error)
+}

package/dist/resources/templates/go-backend/internal/core/crypto/envelope_encryptor.go

@@ -0,0 +1,134 @@
+package crypto
+
+import (
+	"crypto/subtle"
+	"encoding/base64"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+const envelopeCiphertextVersion = "v1"
+
+var envelopeKeyIDPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)
+
+// EnvelopeEncryptor 定义带关联数据的版本化信封加解密能力。
+type EnvelopeEncryptor interface {
+	EncryptWithAssociatedData(plaintext string, associatedData []byte) (EnvelopeCiphertext, error)
+	DecryptWithAssociatedData(ciphertext string, associatedData []byte) (EnvelopePlaintext, error)
+}
+
+// EnvelopeCiphertext 包含密文和值所用密钥版本。
+type EnvelopeCiphertext struct {
+	// Value 是自描述的版本化密文。
+	Value string
+	// KeyID 是加密所用密钥版本。
+	KeyID string
+}
+
+// EnvelopePlaintext 包含明文和成功解密的密钥版本。
+type EnvelopePlaintext struct {
+	// Value 是解密后的明文。
+	Value string
+	// KeyID 是成功解密的密钥版本。
+	KeyID string
+}
+
+// AESGCMEnvelopeKeyring 使用单一活动写密钥与有限只读历史密钥提供版本化 AEAD。
+type AESGCMEnvelopeKeyring struct {
+	activeKeyID string
+	keys        map[string][]byte
+}
+
+// NewAESGCMEnvelopeKeyring 构造只向活动版本写入的 AES-256-GCM 密钥环。
+func NewAESGCMEnvelopeKeyring(
+	activeKeyID string,
+	activeKey string,
+	readKeys map[string]string,
+) (*AESGCMEnvelopeKeyring, error) {
+	if err := validateEnvelopeKeyID(activeKeyID); err != nil {
+		return nil, fmt.Errorf("validate active envelope key ID: %w", err)
+	}
+	activeMaterial, err := decodeAES256Key(activeKey)
+	if err != nil {
+		return nil, fmt.Errorf("decode active envelope key: %w", err)
+	}
+
+	keys := make(map[string][]byte, len(readKeys)+1)
+	for keyID, encodedKey := range readKeys {
+		if err := validateEnvelopeKeyID(keyID); err != nil {
+			return nil, fmt.Errorf("validate envelope read key ID %q: %w", keyID, err)
+		}
+		keyMaterial, err := decodeAES256Key(encodedKey)
+		if err != nil {
+			return nil, fmt.Errorf("decode envelope read key %q: %w", keyID, err)
+		}
+		keys[keyID] = append([]byte(nil), keyMaterial...)
+	}
+
+	if existing, ok := keys[activeKeyID]; ok && !equalKeyMaterial(existing, activeMaterial) {
+		return nil, fmt.Errorf("active envelope key %q conflicts with read key material", activeKeyID)
+	}
+	keys[activeKeyID] = append([]byte(nil), activeMaterial...)
+
+	return &AESGCMEnvelopeKeyring{
+		activeKeyID: activeKeyID,
+		keys:        keys,
+	}, nil
+}
+
+// EncryptWithAssociatedData 使用活动密钥和调用方不可变语义生成密文。
+func (keyring *AESGCMEnvelopeKeyring) EncryptWithAssociatedData(
+	plaintext string,
+	associatedData []byte,
+) (EnvelopeCiphertext, error) {
+	sealed, err := sealAESGCM(keyring.keys[keyring.activeKeyID], []byte(plaintext), associatedData)
+	if err != nil {
+		return EnvelopeCiphertext{}, fmt.Errorf("encrypt envelope: %w", err)
+	}
+	encoded := base64.RawURLEncoding.EncodeToString(sealed)
+	return EnvelopeCiphertext{
+		Value: strings.Join([]string{envelopeCiphertextVersion, keyring.activeKeyID, encoded}, "."),
+		KeyID: keyring.activeKeyID,
+	}, nil
+}
+
+// DecryptWithAssociatedData 仅用密文声明的精确密钥版本解密。
+func (keyring *AESGCMEnvelopeKeyring) DecryptWithAssociatedData(
+	ciphertext string,
+	associatedData []byte,
+) (EnvelopePlaintext, error) {
+	prefix := envelopeCiphertextVersion + "."
+	lastSeparator := strings.LastIndex(ciphertext, ".")
+	if !strings.HasPrefix(ciphertext, prefix) || lastSeparator <= len(prefix) || lastSeparator == len(ciphertext)-1 {
+		return EnvelopePlaintext{}, fmt.Errorf("invalid envelope ciphertext format")
+	}
+	keyID := ciphertext[len(prefix):lastSeparator]
+	if err := validateEnvelopeKeyID(keyID); err != nil {
+		return EnvelopePlaintext{}, fmt.Errorf("invalid envelope ciphertext key ID: %w", err)
+	}
+	key, ok := keyring.keys[keyID]
+	if !ok {
+		return EnvelopePlaintext{}, fmt.Errorf("envelope key %q is not available", keyID)
+	}
+	sealed, err := base64.RawURLEncoding.DecodeString(ciphertext[lastSeparator+1:])
+	if err != nil {
+		return EnvelopePlaintext{}, fmt.Errorf("decode envelope ciphertext: %w", err)
+	}
+	plaintext, err := openAESGCM(key, sealed, associatedData)
+	if err != nil {
+		return EnvelopePlaintext{}, fmt.Errorf("decrypt envelope with key %q: %w", keyID, err)
+	}
+	return EnvelopePlaintext{Value: string(plaintext), KeyID: keyID}, nil
+}
+
+func validateEnvelopeKeyID(keyID string) error {
+	if !envelopeKeyIDPattern.MatchString(keyID) {
+		return fmt.Errorf("key ID must match %s", envelopeKeyIDPattern.String())
+	}
+	return nil
+}
+
+func equalKeyMaterial(left, right []byte) bool {
+	return subtle.ConstantTimeCompare(left, right) == 1
+}

package/dist/resources/templates/go-backend/internal/core/crypto/envelope_encryptor_test.go

@@ -0,0 +1,118 @@
+package crypto
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	envelopeKeyV1 = "1111111111111111111111111111111111111111111111111111111111111111"
+	envelopeKeyV2 = "2222222222222222222222222222222222222222222222222222222222222222"
+)
+
+func TestAESGCMEnvelopeKeyringRoundTrip(t *testing.T) {
+	keyring, err := NewAESGCMEnvelopeKeyring("key-v2", envelopeKeyV2, map[string]string{
+		"key-v1": envelopeKeyV1,
+	})
+	require.NoError(t, err)
+
+	ciphertext, err := keyring.EncryptWithAssociatedData("provider request", []byte("operation:v1"))
+	require.NoError(t, err)
+	assert.Equal(t, "key-v2", ciphertext.KeyID)
+	assert.True(t, strings.HasPrefix(ciphertext.Value, "v1.key-v2."))
+
+	plaintext, err := keyring.DecryptWithAssociatedData(ciphertext.Value, []byte("operation:v1"))
+	require.NoError(t, err)
+	assert.Equal(t, EnvelopePlaintext{Value: "provider request", KeyID: "key-v2"}, plaintext)
+}
+
+func TestAESGCMEnvelopeKeyringReadsPriorVersion(t *testing.T) {
+	prior, err := NewAESGCMEnvelopeKeyring("key-v1", envelopeKeyV1, nil)
+	require.NoError(t, err)
+	ciphertext, err := prior.EncryptWithAssociatedData("recoverable", []byte("immutable-aad"))
+	require.NoError(t, err)
+
+	current, err := NewAESGCMEnvelopeKeyring("key-v2", envelopeKeyV2, map[string]string{
+		"key-v1": envelopeKeyV1,
+	})
+	require.NoError(t, err)
+	plaintext, err := current.DecryptWithAssociatedData(ciphertext.Value, []byte("immutable-aad"))
+	require.NoError(t, err)
+	assert.Equal(t, "recoverable", plaintext.Value)
+	assert.Equal(t, "key-v1", plaintext.KeyID)
+}
+
+func TestAESGCMEnvelopeKeyringRejectsTampering(t *testing.T) {
+	keyring, err := NewAESGCMEnvelopeKeyring("key-v2", envelopeKeyV2, nil)
+	require.NoError(t, err)
+	ciphertext, err := keyring.EncryptWithAssociatedData("secret", []byte("expected-aad"))
+	require.NoError(t, err)
+
+	tamperedCiphertext := []byte(ciphertext.Value)
+	payloadStart := strings.LastIndex(ciphertext.Value, ".") + 1
+	if tamperedCiphertext[payloadStart] == 'A' {
+		tamperedCiphertext[payloadStart] = 'B'
+	} else {
+		tamperedCiphertext[payloadStart] = 'A'
+	}
+
+	tests := []struct {
+		name       string
+		ciphertext string
+		aad        []byte
+	}{
+		{name: "关联数据变化", ciphertext: ciphertext.Value, aad: []byte("different-aad")},
+		{name: "未知密钥", ciphertext: strings.Replace(ciphertext.Value, "key-v2", "key-v3", 1), aad: []byte("expected-aad")},
+		{name: "版本变化", ciphertext: strings.Replace(ciphertext.Value, "v1.", "v2.", 1), aad: []byte("expected-aad")},
+		{name: "密文变化", ciphertext: string(tamperedCiphertext), aad: []byte("expected-aad")},
+		{name: "缺少字段", ciphertext: "v1.key-v2", aad: []byte("expected-aad")},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			plaintext, err := keyring.DecryptWithAssociatedData(test.ciphertext, test.aad)
+			require.Error(t, err)
+			assert.Equal(t, EnvelopePlaintext{}, plaintext)
+		})
+	}
+}
+
+func TestNewAESGCMEnvelopeKeyringValidation(t *testing.T) {
+	tests := []struct {
+		name      string
+		activeID  string
+		activeKey string
+		readKeys  map[string]string
+	}{
+		{name: "空活动版本", activeKey: envelopeKeyV2},
+		{name: "活动版本包含冒号", activeID: "key:v2", activeKey: envelopeKeyV2},
+		{name: "活动密钥长度错误", activeID: "key-v2", activeKey: "abcd"},
+		{name: "历史版本非法", activeID: "key-v2", activeKey: envelopeKeyV2, readKeys: map[string]string{"bad:key": envelopeKeyV1}},
+		{name: "历史密钥格式错误", activeID: "key-v2", activeKey: envelopeKeyV2, readKeys: map[string]string{"key-v1": "abcd"}},
+		{name: "活动版本材料冲突", activeID: "key-v2", activeKey: envelopeKeyV2, readKeys: map[string]string{"key-v2": envelopeKeyV1}},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			keyring, err := NewAESGCMEnvelopeKeyring(test.activeID, test.activeKey, test.readKeys)
+			require.Error(t, err)
+			assert.Nil(t, keyring)
+		})
+	}
+}
+
+func TestNewAESGCMEnvelopeKeyringAcceptsMatchingActiveReadEntry(t *testing.T) {
+	readKeys := map[string]string{"key-v2": envelopeKeyV2}
+	keyring, err := NewAESGCMEnvelopeKeyring("key-v2", envelopeKeyV2, readKeys)
+	require.NoError(t, err)
+
+	readKeys["key-v2"] = envelopeKeyV1
+	ciphertext, err := keyring.EncryptWithAssociatedData("immutable", nil)
+	require.NoError(t, err)
+	plaintext, err := keyring.DecryptWithAssociatedData(ciphertext.Value, nil)
+	require.NoError(t, err)
+	assert.Equal(t, "immutable", plaintext.Value)
+}