@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/internalapi/route_permission_policies_test.go

@@ -0,0 +1,331 @@
+package internalapi
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	iamdomain "{{module}}/internal/integrations/onex/iam"
+)
+
+func TestInternalRoutePermissionPoliciesCoverage(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+	require.Len(t, policies, 101)
+
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/client-support/resolve", "registry:client-support-decision:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/feature-flags/evaluate", "system:feature-flag-evaluation:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/iam/service-tokens", "iam:service-token:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/iam/service-evaluations/batch", "iam:decision:evaluate")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/iam/evaluations/batch", "iam:decision:evaluate")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/iam/bindings/:binding_ref", "iam:binding:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/iam/policies/:policy_code", "iam:policy:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/iam/principals/:principal_ref", "iam:principal:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/iam/service-credentials/:credential_public_id", "iam:service-credential:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/organizations", "organization:organization:list")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/organizations/:organization_ref", "organization:organization:read")
+	assertPolicy(t, policies, http.MethodPatch, "/internal/v1/organizations/:organization_ref", "organization:organization:update")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/organizations/:organization_ref/suspensions", "organization:organization:suspend")
+	assertPolicy(t, policies, http.MethodDelete, "/internal/v1/organizations/:organization_ref/suspensions/current", "organization:organization:update")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/organizations/:organization_ref/product-enrollments", "organization:product_enrollment:list")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/organizations/:organization_ref/product-enrollments", "organization:product_enrollment:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/organizations/:organization_ref/product-enrollments/:enrollment_ref/suspensions", "organization:product_enrollment:suspend")
+	assertPolicy(t, policies, http.MethodDelete, "/internal/v1/organizations/:organization_ref/product-enrollments/:enrollment_ref/suspensions/current", "organization:product_enrollment:update")
+	assertPolicy(t, policies, http.MethodDelete, "/internal/v1/organizations/:organization_ref/product-enrollments/:enrollment_ref", "organization:product_enrollment:delete")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/identity/wechat-mini-program/login", "identity:wechat-mini-program:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/identity/auth-state/resolve", "identity:auth-state:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/identity/guest-capability-policy", "identity:guest-capability:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/identity/guest-capabilities", "identity:guest-capability:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/identity/auth/guest", "identity:guest-session:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/identity/auth/native-guest", "identity:guest-session:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/identity/auth/guest-merges", "identity:guest-account:merge")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/checkout-sessions", "order:checkout:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/checkout-sessions/:session_no/authorizations/reissue", "order:checkout:update")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/checkout-results/:session_no", "order:checkout:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/quotas/allocations", "user_ops:quota:update")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/quotas/allocations/:allocationNo", "user_ops:quota:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/credits/grant", "user_ops:credit-account:grant")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/product-access/users/:userId/policy", "user_ops:entitlement:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/users/:userId/product-user-runtime-profile", "user_ops:identity-view:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/integration-events/inbound", "ops:integration-event-inbound:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/integration-events/probe", "ops:integration-event-inbound:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/integration-events/required-deliveries", "ops:integration-event-required-delivery:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/inbox-queries", "communication:native-inbox:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/unread-queries", "communication:native-inbox:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/acknowledgements", "communication:native-inbox:update")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/devices", "communication:push-device:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/device-revocations", "communication:push-device:update")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/native-notifications/devices", "communication:push-device:list")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/push-preference-queries", "communication:push-preference:read")
+	assertPolicy(t, policies, http.MethodPut, "/internal/v1/native-notifications/push-preferences", "communication:push-preference:update")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/native-notifications/test-push-sends", "communication:push-test-send:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/notifications/dispatch-command-inputs", "notification:dispatch-command-input:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/notifications/dispatch-command-status-queries", "notification:dispatch-command:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/commerce/subscription-projections/resolve", "trade:subscription-projection:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/newsletter-consents/grants", "communication:consent:create")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/commerce/runtime/products/:merchandise_product_code", "catalog:runtime-catalog:read")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/store-purchases/products", "payment:store-purchase:list")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/store-purchases/verifications", "payment:store-purchase:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/store-purchases/restores", "payment:store-purchase:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/store-purchases/transaction-queries", "payment:store-purchase:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/store-purchases/subscription-queries", "payment:store-purchase:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/store-purchases/ownership-queries", "payment:store-purchase:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/store-purchases/promotional-offer-signatures", "payment:store-purchase:create")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/mediagen/safety-preflights", "ai:generation:create")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/mediagen/safety-preflights/:id", "ai:generation:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/mediagen/safety-preflights/validate", "ai:generation:update")
+	assertPolicy(t, policies, http.MethodGet, "/internal/v1/mediagen/runtime-executions/:id", "ai:generation:read")
+	assertPolicy(t, policies, http.MethodPost, "/internal/v1/mediagen/provider-credentials/leases", "ai:provider-credential:lease")
+	serviceTokenPolicy, ok := policies.Lookup(http.MethodPost, "/internal/v1/iam/service-tokens")
+	require.True(t, ok)
+	require.Equal(t, iamdomain.RiskLevelHigh, serviceTokenPolicy.DecisionLogRisk)
+	serviceEvaluationPolicy, ok := policies.Lookup(http.MethodPost, "/internal/v1/iam/service-evaluations/batch")
+	require.True(t, ok)
+	require.Equal(t, serviceEvaluationResource, serviceEvaluationPolicy.Resource)
+	require.Equal(t, iamdomain.RiskLevelHigh, serviceEvaluationPolicy.DecisionLogRisk)
+	delegatedEvaluationPolicy, ok := policies.Lookup(http.MethodPost, "/internal/v1/iam/evaluations/batch")
+	require.True(t, ok)
+	require.Equal(t, delegatedEvaluationResource, delegatedEvaluationPolicy.Resource)
+	require.Equal(t, iamdomain.RiskLevelHigh, delegatedEvaluationPolicy.DecisionLogRisk)
+	for _, routeName := range []string{
+		"/internal/v1/identity/guest-capabilities",
+		"/internal/v1/identity/auth/guest",
+		"/internal/v1/identity/auth/native-guest",
+		"/internal/v1/identity/auth/guest-merges",
+		"/internal/v1/store-purchases/verifications",
+		"/internal/v1/store-purchases/restores",
+		"/internal/v1/store-purchases/promotional-offer-signatures",
+		"/internal/v1/integration-events/required-deliveries",
+		"/internal/v1/notifications/dispatch-command-inputs",
+		"/internal/v1/notifications/dispatch-command-status-queries",
+	} {
+		policy, ok := policies.Lookup(http.MethodPost, routeName)
+		require.True(t, ok)
+		require.Equal(t, iamdomain.RiskLevelHigh, policy.DecisionLogRisk)
+	}
+}
+
+func TestRoutePermissionPolicySetResolveCapability(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+
+	capability, registered, err := policies.ResolveCapability(
+		http.MethodGet,
+		"/internal/v1/users/:userId/product-user-runtime-profile",
+		"product_alpha",
+	)
+
+	require.NoError(t, err)
+	require.True(t, registered)
+	require.Equal(t, RoutePermissionCapability{
+		Method:    http.MethodGet,
+		RouteName: "users/:userId/product-user-runtime-profile",
+		Action:    "user_ops:identity-view:read",
+		Resource:  "onex:product:product_alpha:user_ops:identity-view/*",
+	}, capability)
+}
+
+func TestRoutePermissionPolicySetResolvesEveryRegisteredCapability(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+
+	for key := range policies {
+		capability, registered, err := policies.ResolveCapability(key.Method, key.RouteName, "product_alpha")
+		require.NoError(t, err, "%s %s", key.Method, key.RouteName)
+		require.True(t, registered, "%s %s", key.Method, key.RouteName)
+		require.Equal(t, key.Method, capability.Method)
+		require.Equal(t, key.RouteName, capability.RouteName)
+		require.NotEmpty(t, capability.Action)
+		require.NotEmpty(t, capability.Resource)
+	}
+}
+
+func TestRoutePermissionPolicySetResolvesDomainGlobstarAsCollection(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+
+	capability, registered, err := policies.ResolveCapability(
+		http.MethodPost,
+		"/internal/v1/mediagen/generations",
+		"product_beta",
+	)
+
+	require.NoError(t, err)
+	require.True(t, registered)
+	require.Equal(t, "onex:product:product_beta:ai:*/*", capability.Resource)
+}
+
+func TestProductADataServiceCapabilityRequirements(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+	requirements := []struct {
+		method   string
+		route    string
+		action   string
+		resource string
+	}{
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/identity/auth-state/resolve",
+			action:   "identity:auth-state:read",
+			resource: "onex:product:product_alpha:identity:auth-state/*",
+		},
+		{
+			method:   http.MethodGet,
+			route:    "/internal/v1/product-access/users/{userId}/policy",
+			action:   "user_ops:entitlement:read",
+			resource: "onex:product:product_alpha:user_ops:entitlement/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/quotas/allocations",
+			action:   "user_ops:quota:update",
+			resource: "onex:product:product_alpha:user_ops:quota/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/quotas/allocations/{allocationNo}/activate",
+			action:   "user_ops:quota:update",
+			resource: "onex:product:product_alpha:user_ops:quota/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/quotas/allocations/{allocationNo}/release",
+			action:   "user_ops:quota:update",
+			resource: "onex:product:product_alpha:user_ops:quota/*",
+		},
+		{
+			method:   http.MethodGet,
+			route:    "/internal/v1/quotas/allocations/{allocationNo}",
+			action:   "user_ops:quota:read",
+			resource: "onex:product:product_alpha:user_ops:quota/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/integration-events/inbound",
+			action:   "ops:integration-event-inbound:create",
+			resource: "onex:product:product_alpha:ops:integration-event-inbound/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/integration-events/probe",
+			action:   "ops:integration-event-inbound:create",
+			resource: "onex:product:product_alpha:ops:integration-event-inbound/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/notifications/dispatch-command-inputs",
+			action:   "notification:dispatch-command-input:create",
+			resource: "onex:product:product_alpha:notification:dispatch-command-input/*",
+		},
+		{
+			method:   http.MethodPost,
+			route:    "/internal/v1/notifications/dispatch-command-status-queries",
+			action:   "notification:dispatch-command:read",
+			resource: "onex:product:product_alpha:notification:dispatch-command/*",
+		},
+	}
+
+	for _, requirement := range requirements {
+		capability, registered, err := policies.ResolveCapability(
+			requirement.method,
+			requirement.route,
+			"product_alpha",
+		)
+		require.NoError(t, err, "%s %s", requirement.method, requirement.route)
+		require.True(t, registered, "%s %s", requirement.method, requirement.route)
+		require.Equal(t, requirement.action, capability.Action)
+		require.Equal(t, requirement.resource, capability.Resource)
+	}
+}
+
+func TestRoutePermissionPolicySetResolveCapabilityFailsClosed(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+
+	capability, registered, err := policies.ResolveCapability(
+		http.MethodGet,
+		"/internal/v1/not-registered",
+		"product_alpha",
+	)
+
+	require.NoError(t, err)
+	require.False(t, registered)
+	require.Equal(t, http.MethodGet, capability.Method)
+	require.Equal(t, "not-registered", capability.RouteName)
+
+	_, registered, err = policies.ResolveCapability(
+		http.MethodGet,
+		"/internal/v1/quotas/capacity",
+		"",
+	)
+	require.True(t, registered)
+	require.Error(t, err)
+}
+
+func TestInternalRoutePermissionPoliciesNativeCommunicationUsesLeastPrivilegeResources(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+	expected := []struct {
+		method   string
+		route    string
+		resource string
+	}{
+		{http.MethodPost, "/internal/v1/native-notifications/inbox-queries", nativeInboxResource},
+		{http.MethodPost, "/internal/v1/native-notifications/unread-queries", nativeInboxResource},
+		{http.MethodPost, "/internal/v1/native-notifications/acknowledgements", nativeInboxResource},
+		{http.MethodPost, "/internal/v1/native-notifications/devices", pushDeviceResource},
+		{http.MethodPost, "/internal/v1/native-notifications/device-revocations", pushDeviceResource},
+		{http.MethodGet, "/internal/v1/native-notifications/devices", pushDeviceResource},
+		{http.MethodPost, "/internal/v1/native-notifications/push-preference-queries", pushPreferenceResource},
+		{http.MethodPut, "/internal/v1/native-notifications/push-preferences", pushPreferenceResource},
+		{http.MethodPost, "/internal/v1/native-notifications/test-push-sends", pushTestSendResource},
+		{http.MethodPost, "/internal/v1/newsletter-consents/grants", communicationConsentResource},
+	}
+	for _, item := range expected {
+		policy, ok := policies.Lookup(item.method, item.route)
+		require.True(t, ok)
+		require.Equal(t, item.resource, policy.Resource)
+		require.NotContains(t, policy.Action, "*")
+	}
+}
+
+func TestRoutePermissionPolicySetLookupNormalizesMethodAndRouteTemplate(t *testing.T) {
+	policies := RoutePermissionPolicySet{
+		route(http.MethodGet, "/internal/v1/tests/:testId"): {
+			Action:   "catalog:runtime-catalog:read",
+			Resource: runtimeCatalogResource,
+		},
+	}
+
+	policy, ok := policies.Lookup(" get ", " /internal/v1/tests/{testId} ")
+	require.True(t, ok)
+	require.Equal(t, "catalog:runtime-catalog:read", policy.Action)
+}
+
+func TestInternalRoutePermissionPoliciesIntegrationEventInboundUsesProductScope(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+
+	for _, routeName := range []string{
+		"/internal/v1/integration-events/inbound",
+		"/internal/v1/integration-events/probe",
+	} {
+		policy, ok := policies.Lookup(http.MethodPost, routeName)
+		require.True(t, ok)
+		require.Equal(t, "ops:integration-event-inbound:create", policy.Action)
+		require.Equal(t, "onex:product:{product_code}:ops:integration-event-inbound/*", policy.Resource)
+	}
+}
+
+func TestInternalRoutePermissionPoliciesRequiredDeliveryUsesProductScope(t *testing.T) {
+	policies := InternalRoutePermissionPolicies()
+
+	policy, ok := policies.Lookup(http.MethodPost, "/internal/v1/integration-events/required-deliveries")
+	require.True(t, ok)
+	require.Equal(t, "ops:integration-event-required-delivery:create", policy.Action)
+	require.Equal(t, "onex:product:{product_code}:ops:integration-event-required-delivery/*", policy.Resource)
+	require.Equal(t, iamdomain.RiskLevelHigh, policy.DecisionLogRisk)
+}
+
+func assertPolicy(t *testing.T, policies RoutePermissionPolicySet, method string, routeName string, action string) {
+	t.Helper()
+
+	policy, ok := policies.Lookup(method, routeName)
+	require.True(t, ok)
+	require.Equal(t, action, policy.Action)
+	require.NotEmpty(t, policy.Resource)
+}

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

@@ -0,0 +1,166 @@
+package internalservice
+
+import (
+	"context"
+	"fmt"
+	"hash/fnv"
+	"sync"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+)
+
+type tokenCacheKey struct {
+	credentialMode             string
+	credentialRef              string
+	productCode                string
+	audience                   string
+	expectedServiceAccountCode string
+}
+
+const (
+	tokenCredentialModeReference = "reference"
+	tokenCredentialModeExact     = "exact"
+)
+
+type cachedServiceToken struct {
+	token     string
+	expiresAt time.Time
+	refreshAt time.Time
+}
+
+// ServiceTokenSource 为每个凭证、产品和 audience 隔离缓存短期服务令牌。
+type ServiceTokenSource struct {
+	exchanger *BootstrapTokenExchanger
+	now       func() time.Time
+
+	mu     sync.RWMutex
+	tokens map[tokenCacheKey]cachedServiceToken
+	group  singleflight.Group
+}
+
+// NewAudienceTokenSource 创建 audience 感知的短期令牌源。
+func NewAudienceTokenSource(exchanger *BootstrapTokenExchanger) (*ServiceTokenSource, error) {
+	if exchanger == nil {
+		return nil, fmt.Errorf("internal service token exchanger is required")
+	}
+	return &ServiceTokenSource{exchanger: exchanger, now: time.Now, tokens: make(map[tokenCacheKey]cachedServiceToken)}, nil
+}
+
+// Token 返回目标策略当前可用的短期服务令牌。
+func (s *ServiceTokenSource) Token(ctx context.Context, policy TokenPolicy) (string, error) {
+	if s == nil || s.exchanger == nil {
+		return "", fmt.Errorf("internal service token source is unavailable")
+	}
+	if err := ValidateTokenPolicy(policy); err != nil {
+		return "", err
+	}
+	key := tokenCacheKey{
+		credentialMode: tokenCredentialModeReference,
+		credentialRef:  policy.CredentialRef, productCode: policy.ProductCode, audience: policy.Audience,
+		expectedServiceAccountCode: policy.ExpectedServiceAccountCode,
+	}
+	return s.tokenForKey(key, func() (serviceTokenExchangeResponse, error) {
+		return s.exchanger.Exchange(ctx, policy)
+	})
+}
+
+// TokenWithCredential 消费并清零精确 SecretVersion 凭证，且不经过当前凭证 resolver。
+func (s *ServiceTokenSource) TokenWithCredential(
+	ctx context.Context,
+	policy TokenPolicy,
+	credential []byte,
+) (string, error) {
+	defer clear(credential)
+	if s == nil || s.exchanger == nil {
+		return "", fmt.Errorf("internal service token source is unavailable")
+	}
+	if err := ValidateExactCredentialTokenPolicy(policy); err != nil {
+		return "", err
+	}
+	key := tokenCacheKey{
+		credentialMode: tokenCredentialModeExact,
+		credentialRef:  policy.CredentialRef, productCode: policy.ProductCode, audience: policy.Audience,
+		expectedServiceAccountCode: policy.ExpectedServiceAccountCode,
+	}
+	return s.tokenForKey(key, func() (serviceTokenExchangeResponse, error) {
+		return s.exchanger.ExchangeWithCredential(ctx, policy, credential)
+	})
+}
+
+func (s *ServiceTokenSource) tokenForKey(
+	key tokenCacheKey,
+	exchange func() (serviceTokenExchangeResponse, error),
+) (string, error) {
+	if token, ok := s.cachedToken(key); ok {
+		return token, nil
+	}
+	value, err, _ := s.group.Do(cacheKeyString(key), func() (any, error) {
+		if token, ok := s.cachedToken(key); ok {
+			return token, nil
+		}
+		result, exchangeErr := exchange()
+		if exchangeErr != nil {
+			return "", exchangeErr
+		}
+		expiresAt := result.ExpiresAt.UTC()
+		refreshAt := expiresAt.Add(-refreshWindow(key, expiresAt.Sub(s.now().UTC())))
+		s.mu.Lock()
+		s.tokens[key] = cachedServiceToken{token: result.AccessToken, expiresAt: expiresAt, refreshAt: refreshAt}
+		s.mu.Unlock()
+		return result.AccessToken, nil
+	})
+	if err != nil {
+		return "", err
+	}
+	token, ok := value.(string)
+	if !ok || token == "" {
+		return "", fmt.Errorf("internal service token source returned an invalid value")
+	}
+	return token, nil
+}
+
+func (s *ServiceTokenSource) cachedToken(key tokenCacheKey) (string, bool) {
+	s.mu.RLock()
+	cached, ok := s.tokens[key]
+	s.mu.RUnlock()
+	if !ok || cached.token == "" {
+		return "", false
+	}
+	now := s.now().UTC()
+	if !now.Before(cached.refreshAt) || !now.Before(cached.expiresAt) {
+		return "", false
+	}
+	return cached.token, true
+}
+
+func refreshWindow(key tokenCacheKey, remaining time.Duration) time.Duration {
+	maximum := remaining / 2
+	if maximum <= 0 {
+		return 0
+	}
+	base := remaining / 10
+	if base < 100*time.Millisecond {
+		base = 100 * time.Millisecond
+	}
+	if base > time.Minute {
+		base = time.Minute
+	}
+	if base > maximum {
+		base = maximum
+	}
+	hasher := fnv.New32a()
+	_, _ = hasher.Write([]byte(cacheKeyString(key)))
+	jitterCapacity := maximum - base
+	if jitterCapacity <= 0 {
+		return base
+	}
+	jitter := time.Duration(uint64(hasher.Sum32()) % uint64(jitterCapacity+1))
+	return base + jitter
+}
+
+func cacheKeyString(key tokenCacheKey) string {
+	return key.credentialMode + "\x00" + key.credentialRef + "\x00" + key.productCode + "\x00" + key.audience + "\x00" + key.expectedServiceAccountCode
+}
+
+var _ ExactCredentialAudienceTokenSource = (*ServiceTokenSource)(nil)

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

@@ -0,0 +1,183 @@
+package internalservice
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"strings"
+	"time"
+
+	"{{module}}/internal/common/iamcredential"
+	"{{module}}/internal/common/types"
+	commonvalidator "{{module}}/internal/common/validator"
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/httpclient"
+	"{{module}}/pkg/apierror"
+)
+
+const (
+	serviceCredentialHeader           = "X-Service-Credential"
+	serviceTokenPrefix                = "iamt_"
+	authorizationHeader               = "Authorization"
+	bearerAuthorizationBase           = "Bearer "
+	maximumTokenExchangeResponseBytes = 8 * 1024
+)
+
+type serviceTokenExchangeRequest struct {
+	Audience string `json:"audience"`
+}
+
+type serviceTokenExchangeResponse struct {
+	AccessToken        string    `json:"access_token"`
+	TokenType          string    `json:"token_type"`
+	ExpiresAt          time.Time `json:"expires_at"`
+	Audience           string    `json:"audience"`
+	ServiceAccountCode string    `json:"service_account_code"`
+}
+
+// BootstrapTokenExchanger 仅使用启动凭证调用 IAM 交换端点。
+type BootstrapTokenExchanger struct {
+	client      *httpclient.Client
+	resolver    SecretResolver
+	exchangeURL string
+	maxTTL      time.Duration
+	now         func() time.Time
+}
+
+// NewBootstrapTokenExchanger 创建无重试的启动凭证交换器。
+func NewBootstrapTokenExchanger(
+	client *httpclient.Client,
+	cfg *config.Config,
+	resolver SecretResolver,
+) (*BootstrapTokenExchanger, error) {
+	if client == nil || cfg == nil || resolver == nil {
+		return nil, apierror.Internal("Internal service token exchanger dependencies are not configured")
+	}
+	retry := httpclient.RetryConfig{MaxRetries: 0, RetryOnNetworkError: false}
+	exchangeClient := client.WithOptions(httpclient.Options{Timeout: cfg.InternalService.RequestTimeout, Retry: &retry})
+	exchangeClient.Resty().SetResponseBodyLimit(maximumTokenExchangeResponseBytes)
+	return &BootstrapTokenExchanger{
+		client:      exchangeClient,
+		resolver:    resolver,
+		exchangeURL: strings.TrimRight(strings.TrimSpace(cfg.InternalService.PlatformBaseURL), "/") + "/iam/service-tokens",
+		maxTTL:      time.Duration(cfg.InternalService.TokenTTLSeconds) * time.Second,
+		now:         time.Now,
+	}, nil
+}
+
+// Exchange 按目标策略交换短期服务令牌。
+func (e *BootstrapTokenExchanger) Exchange(ctx context.Context, policy TokenPolicy) (serviceTokenExchangeResponse, error) {
+	if e == nil || e.client == nil || e.resolver == nil || e.maxTTL <= 0 {
+		return serviceTokenExchangeResponse{}, apierror.Internal("Internal service token exchanger is unavailable")
+	}
+	if err := ValidateTokenPolicy(policy); err != nil {
+		return serviceTokenExchangeResponse{}, err
+	}
+	credential, err := e.resolver.ResolveSecret(ctx, policy.CredentialRef)
+	if err != nil {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("resolve internal service bootstrap credential: %w", err)
+	}
+	credentialBytes := []byte(credential)
+	credential = ""
+	defer clear(credentialBytes)
+	return e.exchangeWithCredential(ctx, policy, credentialBytes)
+}
+
+// ExchangeWithCredential 使用调用方转移所有权的精确版本凭证交换令牌，不解析当前凭证引用。
+func (e *BootstrapTokenExchanger) ExchangeWithCredential(
+	ctx context.Context,
+	policy TokenPolicy,
+	credential []byte,
+) (serviceTokenExchangeResponse, error) {
+	defer clear(credential)
+	if e == nil || e.client == nil || e.maxTTL <= 0 {
+		return serviceTokenExchangeResponse{}, apierror.Internal("Internal service token exchanger is unavailable")
+	}
+	if err := ValidateExactCredentialTokenPolicy(policy); err != nil {
+		return serviceTokenExchangeResponse{}, err
+	}
+	return e.exchangeWithCredential(ctx, policy, credential)
+}
+
+func (e *BootstrapTokenExchanger) exchangeWithCredential(
+	ctx context.Context,
+	policy TokenPolicy,
+	credential []byte,
+) (serviceTokenExchangeResponse, error) {
+	credentialHeader := string(credential)
+	if err := iamcredential.ValidatePlaintext(credentialHeader); err != nil {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("internal service bootstrap credential format is invalid")
+	}
+	headers := map[string]string{
+		serviceCredentialHeader: credentialHeader,
+		types.HeaderProductCode: policy.ProductCode,
+		"Accept":                "application/json",
+	}
+	credentialHeader = ""
+	defer delete(headers, serviceCredentialHeader)
+	response, err := e.client.PostOnceWithHeaders(ctx, e.exchangeURL, serviceTokenExchangeRequest{Audience: policy.Audience}, nil, headers)
+	if err != nil {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("exchange internal service token: %w", err)
+	}
+	mediaType, _, contentTypeErr := mime.ParseMediaType(response.Headers.Get("Content-Type"))
+	if response.StatusCode != http.StatusCreated || contentTypeErr != nil || mediaType != "application/json" ||
+		!hasCacheControlDirective(response.Headers.Values("Cache-Control"), "private") ||
+		!hasCacheControlDirective(response.Headers.Values("Cache-Control"), "no-store") ||
+		response.Headers.Get("Pragma") != "no-cache" {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("exchange internal service token: response metadata is invalid")
+	}
+	result, err := decodeServiceTokenExchangeResponse(response.Body)
+	if err != nil {
+		return serviceTokenExchangeResponse{}, err
+	}
+	if err := e.validateResponse(policy, result); err != nil {
+		return serviceTokenExchangeResponse{}, err
+	}
+	return result, nil
+}
+
+func decodeServiceTokenExchangeResponse(raw []byte) (serviceTokenExchangeResponse, error) {
+	if len(raw) == 0 || len(raw) > maximumTokenExchangeResponseBytes {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("exchange internal service token: response body is invalid")
+	}
+	if err := commonvalidator.RejectDuplicateJSONFields(raw); err != nil {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("exchange internal service token: response contract is invalid: %w", err)
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	var result serviceTokenExchangeResponse
+	if err := decoder.Decode(&result); err != nil {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("exchange internal service token: response contract is invalid: %w", err)
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		return serviceTokenExchangeResponse{}, fmt.Errorf("exchange internal service token: response contract contains trailing data")
+	}
+	return result, nil
+}
+
+func (e *BootstrapTokenExchanger) validateResponse(policy TokenPolicy, result serviceTokenExchangeResponse) error {
+	now := e.now().UTC()
+	remaining := result.ExpiresAt.UTC().Sub(now)
+	if !strings.HasPrefix(result.AccessToken, serviceTokenPrefix) || result.TokenType != "Bearer" ||
+		result.Audience != policy.Audience || result.ServiceAccountCode != policy.ExpectedServiceAccountCode ||
+		remaining <= 0 || remaining > e.maxTTL+time.Second {
+		return fmt.Errorf("exchange internal service token: response contract is invalid")
+	}
+	return nil
+}
+
+func hasCacheControlDirective(values []string, expected string) bool {
+	for _, value := range values {
+		for _, directive := range strings.Split(value, ",") {
+			if strings.EqualFold(strings.TrimSpace(directive), expected) {
+				return true
+			}
+		}
+	}
+	return false
+}