@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/internalservice/bound_service_token_signer.go

@@ -0,0 +1,52 @@
+package internalservice
+
+import (
+	"context"
+	"net/http"
+
+	"{{module}}/pkg/apierror"
+)
+
+// BoundServiceTokenSigner 只为构造时绑定的目标资源写入短期服务令牌。
+type BoundServiceTokenSigner struct {
+	source AudienceTokenSource
+	policy TokenPolicy
+}
+
+// NewBoundServiceTokenSigner 从 owner 提供的显式策略构建固定目标签名器。
+func NewBoundServiceTokenSigner(source AudienceTokenSource, policy TokenPolicy) (*BoundServiceTokenSigner, error) {
+	if source == nil {
+		return nil, apierror.Internal("Internal service token signer dependencies are not configured")
+	}
+	if err := ValidateTokenPolicy(policy); err != nil {
+		return nil, err
+	}
+	return &BoundServiceTokenSigner{source: source, policy: policy}, nil
+}
+
+// AuthHeaders 返回固定目标当前有效的服务令牌认证头。
+func (s *BoundServiceTokenSigner) AuthHeaders(ctx context.Context) (map[string]string, error) {
+	token, err := s.source.Token(ctx, s.policy)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]string{authorizationHeader: bearerAuthorizationBase + token}, nil
+}
+
+// AuthorizeRequest 将固定目标服务令牌写入请求。
+func (s *BoundServiceTokenSigner) AuthorizeRequest(ctx context.Context, request *http.Request) error {
+	if request == nil {
+		return apierror.Internal("Internal service request is not initialized")
+	}
+	if request.Header == nil {
+		request.Header = make(http.Header)
+	}
+	headers, err := s.AuthHeaders(ctx)
+	if err != nil {
+		return err
+	}
+	for key, value := range headers {
+		request.Header.Set(key, value)
+	}
+	return nil
+}

package/dist/resources/templates/go-backend/internal/common/internalservice/delegated_access_token_exchanger.go

@@ -0,0 +1,189 @@
+package internalservice
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"{{module}}/internal/common/serviceidentity"
+	"{{module}}/internal/common/types"
+	commonvalidator "{{module}}/internal/common/validator"
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/httpclient"
+	"{{module}}/pkg/apierror"
+)
+
+const (
+	delegatedTokenGrantType            = "urn:ietf:params:oauth:grant-type:token-exchange"
+	delegatedAccessTokenType           = "urn:ietf:params:oauth:token-type:access_token"
+	maximumDelegatedTokenResponseBytes = 16 * 1024
+)
+
+type delegatedTokenExchangeResponse struct {
+	AccessToken     string `json:"access_token"`
+	IssuedTokenType string `json:"issued_token_type"`
+	TokenType       string `json:"token_type"`
+	ExpiresIn       int    `json:"expires_in"`
+	Scope           string `json:"scope"`
+}
+
+// DelegatedAccessTokenPolicy 固定委托交换使用的 actor 身份、产品集合与目标资源。
+type DelegatedAccessTokenPolicy struct {
+	CredentialRef              string
+	AllowedProductCodes        []string
+	ExpectedServiceAccountCode string
+	ResourceIdentifier         string
+}
+
+// DelegatedAccessTokenExchanger 使用独立 actor 服务令牌将产品用户令牌交换为平台委托令牌。
+type DelegatedAccessTokenExchanger struct {
+	client                 *httpclient.Client
+	source                 AudienceTokenSource
+	credentialRef          string
+	expectedServiceAccount string
+	allowedProducts        map[string]struct{}
+	tokenEndpoint          string
+	resourceIdentifier     string
+	maxTTL                 time.Duration
+}
+
+// NewDelegatedAccessTokenExchanger 构建固定 actor、固定授权服务器受众的 RFC 8693 客户端。
+func NewDelegatedAccessTokenExchanger(
+	client *httpclient.Client,
+	cfg *config.Config,
+	source AudienceTokenSource,
+	policy DelegatedAccessTokenPolicy,
+) (*DelegatedAccessTokenExchanger, error) {
+	if client == nil || cfg == nil || source == nil {
+		return nil, apierror.Internal("Delegated token exchanger dependencies are not configured")
+	}
+	if err := serviceidentity.ValidateResourceIdentifier(policy.ResourceIdentifier); err != nil {
+		return nil, apierror.Internal("Delegated token exchanger resource identifier is invalid")
+	}
+	allowedProducts := make(map[string]struct{}, len(policy.AllowedProductCodes))
+	for _, productCode := range policy.AllowedProductCodes {
+		if err := ValidateTokenPolicy(TokenPolicy{
+			CredentialRef:              policy.CredentialRef,
+			ProductCode:                productCode,
+			Audience:                   serviceidentity.AudienceIdentityTokenService,
+			ExpectedServiceAccountCode: policy.ExpectedServiceAccountCode,
+		}); err != nil {
+			return nil, err
+		}
+		if _, duplicate := allowedProducts[productCode]; duplicate {
+			return nil, apierror.Internal("Delegated token exchanger product policy contains duplicates")
+		}
+		allowedProducts[productCode] = struct{}{}
+	}
+	if len(allowedProducts) == 0 {
+		return nil, apierror.Internal("Delegated token exchanger product policy is empty")
+	}
+	retry := httpclient.RetryConfig{MaxRetries: 0, RetryOnNetworkError: false}
+	exchangeClient := client.WithOptions(httpclient.Options{
+		Timeout:        cfg.InternalService.RequestTimeout,
+		Retry:          &retry,
+		RedirectPolicy: httpclient.PreserveRedirectResponsePolicy(),
+	})
+	exchangeClient.Resty().SetResponseBodyLimit(maximumDelegatedTokenResponseBytes)
+	return &DelegatedAccessTokenExchanger{
+		client:                 exchangeClient,
+		source:                 source,
+		credentialRef:          policy.CredentialRef,
+		expectedServiceAccount: policy.ExpectedServiceAccountCode,
+		allowedProducts:        allowedProducts,
+		tokenEndpoint:          strings.TrimRight(strings.TrimSpace(cfg.Identity.AccessToken.Issuer), "/") + "/oauth2/token",
+		resourceIdentifier:     policy.ResourceIdentifier,
+		maxTTL:                 cfg.Identity.AccessToken.DelegatedTokenTTL,
+	}, nil
+}
+
+// Exchange 返回只能访问平台内部资源的短期委托 Bearer token。
+func (e *DelegatedAccessTokenExchanger) Exchange(
+	ctx context.Context,
+	subjectToken string,
+	productCode string,
+) (string, error) {
+	subjectToken = strings.TrimSpace(subjectToken)
+	productCode = strings.TrimSpace(productCode)
+	if e == nil || e.client == nil || e.source == nil || subjectToken == "" || e.maxTTL <= 0 {
+		return "", apierror.Internal("Delegated token exchanger is unavailable")
+	}
+	if _, allowed := e.allowedProducts[productCode]; !allowed {
+		return "", apierror.Forbidden("Product is outside the delegated token exchanger policy")
+	}
+	actorToken, err := e.source.Token(ctx, TokenPolicy{
+		CredentialRef:              e.credentialRef,
+		ProductCode:                productCode,
+		Audience:                   serviceidentity.AudienceIdentityTokenService,
+		ExpectedServiceAccountCode: e.expectedServiceAccount,
+	})
+	if err != nil {
+		return "", fmt.Errorf("authorize delegated token exchange: %w", err)
+	}
+	form := url.Values{
+		"grant_type":           {delegatedTokenGrantType},
+		"subject_token":        {subjectToken},
+		"subject_token_type":   {delegatedAccessTokenType},
+		"requested_token_type": {delegatedAccessTokenType},
+		"resource":             {e.resourceIdentifier},
+	}
+	headers := map[string]string{
+		authorizationHeader:     bearerAuthorizationBase + actorToken,
+		types.HeaderProductCode: productCode,
+		"Accept":                "application/json",
+		"Content-Type":          "application/x-www-form-urlencoded",
+	}
+	response, err := e.client.DoOnceWithHeaders(
+		ctx,
+		http.MethodPost,
+		e.tokenEndpoint,
+		strings.NewReader(form.Encode()),
+		nil,
+		headers,
+	)
+	if err != nil {
+		return "", fmt.Errorf("exchange delegated access token: %w", err)
+	}
+	mediaType, _, contentTypeErr := mime.ParseMediaType(response.Headers.Get("Content-Type"))
+	if response.StatusCode != http.StatusOK || contentTypeErr != nil || mediaType != "application/json" ||
+		!hasCacheControlDirective(response.Headers.Values("Cache-Control"), "no-store") || response.Headers.Get("Pragma") != "no-cache" {
+		return "", fmt.Errorf("exchange delegated access token: response metadata is invalid")
+	}
+	result, err := decodeDelegatedTokenExchangeResponse(response.Body)
+	if err != nil {
+		return "", err
+	}
+	if result.TokenType != "Bearer" || result.IssuedTokenType != delegatedAccessTokenType || result.ExpiresIn <= 0 ||
+		time.Duration(result.ExpiresIn)*time.Second > e.maxTTL || strings.TrimSpace(result.AccessToken) == "" ||
+		strings.HasPrefix(result.AccessToken, "iamt_") || strings.HasPrefix(result.AccessToken, "iamd_") || strings.TrimSpace(result.Scope) == "" {
+		return "", fmt.Errorf("exchange delegated access token: response contract is invalid")
+	}
+	return result.AccessToken, nil
+}
+
+func decodeDelegatedTokenExchangeResponse(raw []byte) (delegatedTokenExchangeResponse, error) {
+	if len(raw) == 0 || len(raw) > maximumDelegatedTokenResponseBytes {
+		return delegatedTokenExchangeResponse{}, fmt.Errorf("exchange delegated access token: response body is invalid")
+	}
+	if err := commonvalidator.RejectDuplicateJSONFields(raw); err != nil {
+		return delegatedTokenExchangeResponse{}, fmt.Errorf("exchange delegated access token: response contract is invalid: %w", err)
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	var result delegatedTokenExchangeResponse
+	if err := decoder.Decode(&result); err != nil {
+		return delegatedTokenExchangeResponse{}, fmt.Errorf("exchange delegated access token: response contract is invalid: %w", err)
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		return delegatedTokenExchangeResponse{}, fmt.Errorf("exchange delegated access token: response contract contains trailing data")
+	}
+	return result, nil
+}

package/dist/resources/templates/go-backend/internal/common/internalservice/delegated_access_token_exchanger_test.go

@@ -0,0 +1,159 @@
+package internalservice
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/serviceidentity"
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/httpclient"
+)
+
+func TestDelegatedAccessTokenExchangerUsesExactActorAndResourceContract(t *testing.T) {
+	var received url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		require.Equal(t, http.MethodPost, request.Method)
+		require.Equal(t, "/oauth2/token", request.URL.Path)
+		require.Equal(t, "Bearer iamt_actor", request.Header.Get(authorizationHeader))
+		require.Empty(t, request.Header.Get(serviceCredentialHeader))
+		require.Equal(t, "customer_operations_os", request.Header.Get(types.HeaderProductCode))
+		require.Equal(t, "application/x-www-form-urlencoded", request.Header.Get("Content-Type"))
+		require.NoError(t, request.ParseForm())
+		received = request.PostForm
+		writer.Header().Set("Content-Type", "application/json")
+		writer.Header().Set("Cache-Control", "private, no-store")
+		writer.Header().Set("Pragma", "no-cache")
+		require.NoError(t, json.NewEncoder(writer).Encode(delegatedTokenExchangeResponse{
+			AccessToken:     "eyJhbGciOiJSUzI1NiJ9.delegated.signature",
+			IssuedTokenType: delegatedAccessTokenType,
+			TokenType:       "Bearer",
+			ExpiresIn:       300,
+			Scope:           "openid profile",
+		}))
+	}))
+	t.Cleanup(server.Close)
+
+	policy := DelegatedAccessTokenPolicy{
+		CredentialRef:              "env://CUSTOMER_OPERATIONS_BFF_CREDENTIAL",
+		AllowedProductCodes:        []string{"customer_operations_os"},
+		ExpectedServiceAccountCode: "svc_customer_operations_bff_prod",
+		ResourceIdentifier:         "https://api.example.com",
+	}
+	actorPolicy := TokenPolicy{
+		CredentialRef:              policy.CredentialRef,
+		ProductCode:                "customer_operations_os",
+		Audience:                   serviceidentity.AudienceIdentityTokenService,
+		ExpectedServiceAccountCode: policy.ExpectedServiceAccountCode,
+	}
+	source := &staticAudienceTokenSource{tokens: map[TokenPolicy]string{actorPolicy: "iamt_actor"}}
+	exchanger, err := NewDelegatedAccessTokenExchanger(
+		httpclient.New(zap.NewNop()),
+		delegatedAccessTokenExchangerConfigForTest(server.URL),
+		source,
+		policy,
+	)
+	require.NoError(t, err)
+
+	accessToken, err := exchanger.Exchange(context.Background(), "product-user-access-token", "customer_operations_os")
+	require.NoError(t, err)
+	require.Equal(t, "eyJhbGciOiJSUzI1NiJ9.delegated.signature", accessToken)
+	require.Equal(t, []TokenPolicy{actorPolicy}, source.calls)
+	require.Equal(t, delegatedTokenGrantType, received.Get("grant_type"))
+	require.Equal(t, "product-user-access-token", received.Get("subject_token"))
+	require.Equal(t, delegatedAccessTokenType, received.Get("subject_token_type"))
+	require.Equal(t, delegatedAccessTokenType, received.Get("requested_token_type"))
+	require.Equal(t, "https://api.example.com", received.Get("resource"))
+	require.Len(t, received, 5)
+}
+
+func TestDelegatedAccessTokenExchangerRejectsCrossProductAndInvalidResponses(t *testing.T) {
+	validBody := fmt.Sprintf(
+		`{"access_token":"eyJhbGciOiJSUzI1NiJ9.delegated.signature","issued_token_type":%q,"token_type":"Bearer","expires_in":300,"scope":"openid profile"}`,
+		delegatedAccessTokenType,
+	)
+	tests := []struct {
+		name         string
+		status       int
+		contentType  string
+		cacheControl string
+		pragma       string
+		body         string
+	}{
+		{name: "wrong status", status: http.StatusCreated, contentType: "application/json", cacheControl: "no-store", pragma: "no-cache", body: validBody},
+		{name: "missing no-store", status: http.StatusOK, contentType: "application/json", pragma: "no-cache", body: validBody},
+		{name: "wrong content type", status: http.StatusOK, contentType: "text/plain", cacheControl: "no-store", pragma: "no-cache", body: validBody},
+		{name: "unknown field", status: http.StatusOK, contentType: "application/json", cacheControl: "no-store", pragma: "no-cache", body: strings.TrimSuffix(validBody, "}") + `,"actor":"caller"}`},
+		{name: "bootstrap token returned", status: http.StatusOK, contentType: "application/json", cacheControl: "no-store", pragma: "no-cache", body: strings.Replace(validBody, "eyJhbGciOiJSUzI1NiJ9.delegated.signature", "iamt_actor", 1)},
+		{name: "ttl exceeds policy", status: http.StatusOK, contentType: "application/json", cacheControl: "no-store", pragma: "no-cache", body: strings.Replace(validBody, `"expires_in":300`, `"expires_in":301`, 1)},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+				if test.contentType != "" {
+					writer.Header().Set("Content-Type", test.contentType)
+				}
+				if test.cacheControl != "" {
+					writer.Header().Set("Cache-Control", test.cacheControl)
+				}
+				if test.pragma != "" {
+					writer.Header().Set("Pragma", test.pragma)
+				}
+				writer.WriteHeader(test.status)
+				_, _ = writer.Write([]byte(test.body))
+			}))
+			t.Cleanup(server.Close)
+			policy := DelegatedAccessTokenPolicy{
+				CredentialRef:              "env://CUSTOMER_OPERATIONS_BFF_CREDENTIAL",
+				AllowedProductCodes:        []string{"customer_operations_os"},
+				ExpectedServiceAccountCode: "svc_customer_operations_bff_prod",
+				ResourceIdentifier:         "https://api.example.com",
+			}
+			source := &staticAudienceTokenSource{tokens: map[TokenPolicy]string{{
+				CredentialRef: policy.CredentialRef, ProductCode: "customer_operations_os",
+				Audience:                   serviceidentity.AudienceIdentityTokenService,
+				ExpectedServiceAccountCode: policy.ExpectedServiceAccountCode,
+			}: "iamt_actor"}}
+			exchanger, err := NewDelegatedAccessTokenExchanger(
+				httpclient.New(zap.NewNop()), delegatedAccessTokenExchangerConfigForTest(server.URL), source, policy,
+			)
+			require.NoError(t, err)
+			_, err = exchanger.Exchange(context.Background(), "product-user-access-token", "customer_operations_os")
+			require.Error(t, err)
+		})
+	}
+
+	policy := DelegatedAccessTokenPolicy{
+		CredentialRef:              "env://CUSTOMER_OPERATIONS_BFF_CREDENTIAL",
+		AllowedProductCodes:        []string{"customer_operations_os"},
+		ExpectedServiceAccountCode: "svc_customer_operations_bff_prod",
+		ResourceIdentifier:         "https://api.example.com",
+	}
+	source := &staticAudienceTokenSource{}
+	exchanger, err := NewDelegatedAccessTokenExchanger(
+		httpclient.New(zap.NewNop()), delegatedAccessTokenExchangerConfigForTest("https://identity.example.com"), source, policy,
+	)
+	require.NoError(t, err)
+	_, err = exchanger.Exchange(context.Background(), "product-user-access-token", "another_product")
+	require.ErrorContains(t, err, "outside the delegated token exchanger policy")
+	require.Empty(t, source.calls)
+}
+
+func delegatedAccessTokenExchangerConfigForTest(issuer string) *config.Config {
+	return &config.Config{
+		Identity: config.IdentityConfig{AccessToken: config.IdentityAccessTokenConfig{
+			Issuer: issuer, DelegatedTokenTTL: 5 * time.Minute,
+		}},
+		InternalService: config.InternalServiceConfig{RequestTimeout: 2 * time.Second},
+	}
+}

package/dist/resources/templates/go-backend/internal/common/internalservice/product_scoped_service_token_signer.go

@@ -0,0 +1,92 @@
+package internalservice
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+)
+
+// ProductTokenPolicy 将一个发送身份绑定到明确的产品 allowlist 与目标资源。
+type ProductTokenPolicy struct {
+	CredentialRef              string
+	AllowedProductCodes        []string
+	Audience                   string
+	ExpectedServiceAccountCode string
+}
+
+// ProductScopedServiceTokenSigner 仅为 owner 配置 allowlist 内的产品签发目标令牌。
+type ProductScopedServiceTokenSigner struct {
+	source                 AudienceTokenSource
+	credentialRef          string
+	audience               string
+	expectedServiceAccount string
+	allowedProductCodeSet  map[string]struct{}
+}
+
+// NewProductScopedServiceTokenSigner 构建显式多产品发送身份签名器。
+func NewProductScopedServiceTokenSigner(
+	source AudienceTokenSource,
+	policy ProductTokenPolicy,
+) (*ProductScopedServiceTokenSigner, error) {
+	if source == nil || len(policy.AllowedProductCodes) == 0 {
+		return nil, fmt.Errorf("product-scoped service token signer policy is invalid")
+	}
+	allowed := make(map[string]struct{}, len(policy.AllowedProductCodes))
+	for _, productCode := range policy.AllowedProductCodes {
+		tokenPolicy := TokenPolicy{
+			CredentialRef: policy.CredentialRef, ProductCode: productCode, Audience: policy.Audience,
+			ExpectedServiceAccountCode: policy.ExpectedServiceAccountCode,
+		}
+		if err := ValidateTokenPolicy(tokenPolicy); err != nil {
+			return nil, err
+		}
+		if _, duplicate := allowed[productCode]; duplicate {
+			return nil, fmt.Errorf("product-scoped service token signer contains duplicate product")
+		}
+		allowed[productCode] = struct{}{}
+	}
+	return &ProductScopedServiceTokenSigner{
+		source: source, credentialRef: policy.CredentialRef, audience: policy.Audience,
+		expectedServiceAccount: policy.ExpectedServiceAccountCode, allowedProductCodeSet: allowed,
+	}, nil
+}
+
+// AuthHeadersForProduct 返回 allowlist 内产品的短期服务令牌认证头。
+func (s *ProductScopedServiceTokenSigner) AuthHeadersForProduct(ctx context.Context, productCode string) (map[string]string, error) {
+	if s == nil || s.source == nil {
+		return nil, fmt.Errorf("product-scoped service token signer is unavailable")
+	}
+	if _, allowed := s.allowedProductCodeSet[productCode]; !allowed {
+		return nil, fmt.Errorf("internal service product is outside the configured allowlist")
+	}
+	token, err := s.source.Token(ctx, TokenPolicy{
+		CredentialRef: s.credentialRef, ProductCode: productCode, Audience: s.audience,
+		ExpectedServiceAccountCode: s.expectedServiceAccount,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return map[string]string{authorizationHeader: bearerAuthorizationBase + token}, nil
+}
+
+// AuthorizeRequestForProduct 将 allowlist 内产品的服务令牌写入请求。
+func (s *ProductScopedServiceTokenSigner) AuthorizeRequestForProduct(
+	ctx context.Context,
+	request *http.Request,
+	productCode string,
+) error {
+	if request == nil {
+		return fmt.Errorf("internal service request is not initialized")
+	}
+	if request.Header == nil {
+		request.Header = make(http.Header)
+	}
+	headers, err := s.AuthHeadersForProduct(ctx, productCode)
+	if err != nil {
+		return err
+	}
+	for key, value := range headers {
+		request.Header.Set(key, value)
+	}
+	return nil
+}

package/dist/resources/templates/go-backend/internal/common/internalservice/provider.go

@@ -0,0 +1,25 @@
+package internalservice
+
+import "github.com/google/wire"
+
+// ServiceTokenSourceProviderSet 启动凭证交换型内部服务令牌源依赖集合。
+var ServiceTokenSourceProviderSet = wire.NewSet(
+	ProvideReferenceSecretResolver,
+	NewBootstrapTokenExchanger,
+	NewAudienceTokenSource,
+	wire.Bind(new(AudienceTokenSource), new(*ServiceTokenSource)),
+	wire.Bind(new(ExactCredentialAudienceTokenSource), new(*ServiceTokenSource)),
+)
+
+// ServiceTokenSourceWithResolverProviderSet 复用调用进程已有 SecretResolver 装配短期令牌源。
+var ServiceTokenSourceWithResolverProviderSet = wire.NewSet(
+	NewBootstrapTokenExchanger,
+	NewAudienceTokenSource,
+	wire.Bind(new(AudienceTokenSource), new(*ServiceTokenSource)),
+	wire.Bind(new(ExactCredentialAudienceTokenSource), new(*ServiceTokenSource)),
+)
+
+// ProvideReferenceSecretResolver 以统一引用适配器提供内部服务密钥解析端口。
+func ProvideReferenceSecretResolver() SecretResolver {
+	return NewReferenceResolver()
+}

package/dist/resources/templates/go-backend/internal/common/internalservice/request_signer.go

@@ -0,0 +1,86 @@
+package internalservice
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"regexp"
+	"strings"
+
+	"{{module}}/internal/common/serviceidentity"
+)
+
+var (
+	tokenPolicyProductCodePattern = regexp.MustCompile(`^[a-z][a-z0-9_]{1,49}$`)
+	serviceAccountCodePattern     = regexp.MustCompile(`^svc_[a-z0-9_]{3,95}$`)
+	secretVersionReferencePattern = regexp.MustCompile(`^scv_[0-9a-z]{20,59}$`)
+)
+
+// TokenPolicy 将启动凭证、产品与目标资源绑定为不可变交换策略。
+type TokenPolicy struct {
+	CredentialRef              string
+	ProductCode                string
+	Audience                   string
+	ExpectedServiceAccountCode string
+}
+
+// AudienceTokenSource 按目标策略交换并缓存短期 IAM 服务令牌。
+type AudienceTokenSource interface {
+	Token(ctx context.Context, policy TokenPolicy) (string, error)
+}
+
+// ExactCredentialAudienceTokenSource 使用调用方持有的一次性精确版本凭证交换并缓存服务令牌。
+type ExactCredentialAudienceTokenSource interface {
+	TokenWithCredential(context.Context, TokenPolicy, []byte) (string, error)
+}
+
+// ValidateTokenPolicy 在交换边界统一校验目标资源策略。
+func ValidateTokenPolicy(policy TokenPolicy) error {
+	credentialRef := strings.TrimSpace(policy.CredentialRef)
+	if credentialRef == "" || credentialRef != policy.CredentialRef {
+		return fmt.Errorf("internal service bootstrap credential reference is required")
+	}
+	return validateTokenTarget(policy)
+}
+
+// ValidateExactCredentialTokenPolicy 要求凭证引用是执行快照冻结的精确 SecretVersion。
+func ValidateExactCredentialTokenPolicy(policy TokenPolicy) error {
+	if !secretVersionReferencePattern.MatchString(policy.CredentialRef) {
+		return fmt.Errorf("internal service exact credential version reference is invalid")
+	}
+	return validateTokenTarget(policy)
+}
+
+func validateTokenTarget(policy TokenPolicy) error {
+	if !tokenPolicyProductCodePattern.MatchString(policy.ProductCode) {
+		return fmt.Errorf("internal service product code is invalid")
+	}
+	if err := serviceidentity.ValidateAudience(policy.Audience); err != nil {
+		return err
+	}
+	if err := ValidateServiceAccountCode(policy.ExpectedServiceAccountCode); err != nil {
+		return err
+	}
+	return nil
+}
+
+// ValidateServiceAccountCode 校验服务身份协议使用的稳定账号编码。
+func ValidateServiceAccountCode(value string) error {
+	code := strings.TrimSpace(value)
+	if code != value || !serviceAccountCodePattern.MatchString(code) {
+		return fmt.Errorf("internal service expected service account code is invalid")
+	}
+	return nil
+}
+
+// Signer 为固定目标的内部服务请求生成短期服务令牌认证信息。
+type Signer interface {
+	AuthHeaders(ctx context.Context) (map[string]string, error)
+	AuthorizeRequest(ctx context.Context, request *http.Request) error
+}
+
+// ProductSigner 为同一目标资源按产品隔离签发短期服务令牌。
+type ProductSigner interface {
+	AuthHeadersForProduct(ctx context.Context, productCode string) (map[string]string, error)
+	AuthorizeRequestForProduct(ctx context.Context, request *http.Request, productCode string) error
+}

package/dist/resources/templates/go-backend/internal/common/internalservice/resolver.go

@@ -0,0 +1,69 @@
+package internalservice
+
+import (
+	"context"
+	"os"
+	"strings"
+
+	"{{module}}/pkg/apierror"
+)
+
+const (
+	envReferencePrefix  = "env://"
+	fileReferencePrefix = "file://"
+)
+
+// SecretResolver 解析内部服务凭证引用。
+type SecretResolver interface {
+	ResolveSecret(ctx context.Context, ref string) (string, error)
+}
+
+// ReferenceResolver 解析启动凭证引用，凭证值不会写入配置结构。
+type ReferenceResolver struct{}
+
+// NewReferenceResolver 创建内部服务凭证引用解析器。
+func NewReferenceResolver() *ReferenceResolver {
+	return &ReferenceResolver{}
+}
+
+// ResolveSecret 从受支持的引用源读取凭证明文。
+func (r *ReferenceResolver) ResolveSecret(ctx context.Context, ref string) (string, error) {
+	select {
+	case <-ctx.Done():
+		return "", ctx.Err()
+	default:
+	}
+
+	normalized := strings.TrimSpace(ref)
+	switch {
+	case strings.HasPrefix(normalized, envReferencePrefix):
+		return resolveEnvSecret(normalized)
+	case strings.HasPrefix(normalized, fileReferencePrefix):
+		return resolveFileSecret(normalized)
+	default:
+		return "", apierror.Internal("Internal service credential reference scheme is not supported")
+	}
+}
+
+func resolveEnvSecret(ref string) (string, error) {
+	name := strings.TrimSpace(strings.TrimPrefix(ref, envReferencePrefix))
+	if name == "" || strings.Contains(name, "/") {
+		return "", apierror.Internal("Internal service environment credential reference is invalid")
+	}
+	return strings.TrimSpace(os.Getenv(name)), nil
+}
+
+func resolveFileSecret(ref string) (string, error) {
+	path := strings.TrimSpace(strings.TrimPrefix(ref, fileReferencePrefix))
+	if path == "" {
+		return "", apierror.Internal("Internal service file credential reference is invalid")
+	}
+	if !strings.HasPrefix(path, "/") {
+		path = "/" + path
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return "", apierror.Internal("Internal service credential file could not be read")
+	}
+	return strings.TrimSpace(string(raw)), nil
+}