@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/common/middleware/resource_permission.go

@@ -0,0 +1,790 @@
+package middleware
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/common/iamscope"
+	"{{module}}/internal/common/ruleexpression"
+	"{{module}}/internal/common/types"
+	iamdomain "{{module}}/internal/integrations/onex/iam"
+	"{{module}}/pkg/apierror"
+)
+
+// scopeConstraintKey 在 gin.Context 传递数据范围约束的私有 key。
+//
+// 采用本 package 既有的 "__xxx" 命名（见 apikey_auth.go），避免与业务键冲突；
+// 仅通过 SetScopeConstraint / GetScopeConstraint 读写，不直接暴露字符串。
+const scopeConstraintKey = "__iamScopeConstraint"
+
+// scopePrincipalIDKey 在 gin.Context 传递已解析 IAM 主体主键的私有 key。
+//
+// 数据范围的 self 维度（assigned_to_self 等）需用主体主键填充列谓词；该主键由
+// RequireResourcePermission 在请求期解析（主键 != identity_id，SH-I1），故由中间件
+// 与 scope 约束一并注入，供查询层透传给 applier。仅通过 SetScopePrincipalID /
+// GetScopePrincipalID 读写。
+const scopePrincipalIDKey = "__iamScopePrincipalID"
+
+// resourcePermissionDecisionKey 在 gin.Context 传递本次资源授权裁决证据的私有 key。
+const resourcePermissionDecisionKey = "__iamResourcePermissionDecision"
+
+const (
+	requiredCapabilityMissingReason               = "required_capability_missing"
+	requiredProductRequirementNotSatisfiedReason  = "required_product_requirement_not_satisfied"
+	requiredProductRequirementIndeterminateReason = "required_product_requirement_indeterminate"
+)
+
+type adminAccessContextKey struct{}
+
+type resourcePermissionConfig struct {
+	decisionRisk        iamdomain.RiskLevel
+	productRequirements []productAdmissionRequirement
+	requirementErr      error
+}
+
+// ProductRequirement 声明路由的版本化产品准入表达式。
+type ProductRequirement struct {
+	// Expression 是 common/ruleexpression V1 信封。
+	Expression json.RawMessage
+	// ExpressionHash 是表达式 canonical JSON 的 SHA-256。
+	ExpressionHash string
+}
+
+type productAdmissionRequirement struct {
+	expression   ruleexpression.ExpressionV1
+	deniedReason string
+	explanation  string
+}
+
+type productAdmissionDecision struct {
+	Allowed     bool
+	ReasonCode  string
+	Explanation string
+	Failure     *apierror.APIError
+}
+
+// ResourcePermissionDecision 记录一次资源授权裁决的审计证据。
+type ResourcePermissionDecision struct {
+	// 被求值动作
+	Action string
+	// 被求值资源
+	Resource string
+	// 是否允许
+	Allowed bool
+	// 决策原因码
+	ReasonCode string
+	// 决策原因类别
+	ReasonKind string
+	// IAM 主体主键
+	PrincipalID int64
+	// 数据范围摘要
+	ScopeConstraintSummary string
+}
+
+// ResourcePermissionOption 配置资源动作级授权中间件的可选行为。
+type ResourcePermissionOption func(*resourcePermissionConfig)
+
+// WithDecisionLogRisk 声明当前路由求值需要按指定风险等级写访问决策日志。
+func WithDecisionLogRisk(risk iamdomain.RiskLevel) ResourcePermissionOption {
+	return func(cfg *resourcePermissionConfig) {
+		cfg.decisionRisk = risk
+	}
+}
+
+// WithRequiredCapability 声明路由只在当前产品能力生效时进入 IAM 求值。
+func WithRequiredCapability(capabilityCode string) ResourcePermissionOption {
+	requirement, err := capabilityAdmissionRequirement(capabilityCode)
+	return func(cfg *resourcePermissionConfig) {
+		appendProductAdmissionRequirement(cfg, requirement, err)
+	}
+}
+
+// WithRequiredProductRequirement 声明路由的产品上下文与能力组合需求。
+func WithRequiredProductRequirement(requirement ProductRequirement) ResourcePermissionOption {
+	normalized, err := normalizeProductAdmissionRequirement(requirement)
+	return func(cfg *resourcePermissionConfig) {
+		appendProductAdmissionRequirement(cfg, normalized, err)
+	}
+}
+
+func appendProductAdmissionRequirement(
+	cfg *resourcePermissionConfig,
+	requirement productAdmissionRequirement,
+	err error,
+) {
+	if cfg.requirementErr != nil {
+		return
+	}
+	if err != nil {
+		cfg.requirementErr = err
+		return
+	}
+	cfg.productRequirements = append(cfg.productRequirements, requirement)
+}
+
+func capabilityAdmissionRequirement(capabilityCode string) (productAdmissionRequirement, error) {
+	expression := ruleexpression.ExpressionV1{
+		SchemaVersion: ruleexpression.SchemaVersionV1,
+		Root: &ruleexpression.PredicateNode{
+			Subject:  ruleexpression.SubjectCapability,
+			Key:      strings.TrimSpace(capabilityCode),
+			Operator: ruleexpression.OperatorActive,
+		},
+	}
+	if _, err := ruleexpression.CanonicalJSON(expression); err != nil {
+		return productAdmissionRequirement{}, fmt.Errorf("required capability expression is invalid: %w", err)
+	}
+	return productAdmissionRequirement{
+		expression:   expression,
+		deniedReason: requiredCapabilityMissingReason,
+		explanation:  "required product capability is not active",
+	}, nil
+}
+
+func normalizeProductAdmissionRequirement(requirement ProductRequirement) (productAdmissionRequirement, error) {
+	expression, err := ruleexpression.Decode(bytes.TrimSpace(requirement.Expression))
+	if err != nil {
+		return productAdmissionRequirement{}, fmt.Errorf("decode product admission requirement: %w", err)
+	}
+	if err := validateProductAdmissionSubjects(expression.Root); err != nil {
+		return productAdmissionRequirement{}, err
+	}
+	hash, err := ruleexpression.CanonicalHash(expression)
+	if err != nil {
+		return productAdmissionRequirement{}, fmt.Errorf("hash product admission requirement: %w", err)
+	}
+	expectedHash := strings.TrimSpace(requirement.ExpressionHash)
+	if expectedHash == "" || expectedHash != hash {
+		return productAdmissionRequirement{}, fmt.Errorf("product admission requirement hash does not match canonical expression")
+	}
+	return productAdmissionRequirement{
+		expression:   expression,
+		deniedReason: requiredProductRequirementNotSatisfiedReason,
+		explanation:  "required product condition is not satisfied",
+	}, nil
+}
+
+func validateProductAdmissionSubjects(node ruleexpression.Node) error {
+	switch current := node.(type) {
+	case *ruleexpression.AllNode:
+		for i := range current.Children {
+			if err := validateProductAdmissionSubjects(current.Children[i]); err != nil {
+				return err
+			}
+		}
+	case *ruleexpression.AnyNode:
+		for i := range current.Children {
+			if err := validateProductAdmissionSubjects(current.Children[i]); err != nil {
+				return err
+			}
+		}
+	case *ruleexpression.NotNode:
+		return validateProductAdmissionSubjects(current.Child)
+	case *ruleexpression.PredicateNode:
+		switch current.Subject {
+		case ruleexpression.SubjectProduct, ruleexpression.SubjectAttribute, ruleexpression.SubjectCapability:
+			return nil
+		default:
+			return fmt.Errorf("subject %q is not allowed in a product admission requirement", current.Subject)
+		}
+	default:
+		return fmt.Errorf("product admission requirement contains unsupported node %T", node)
+	}
+	return nil
+}
+
+func evaluateProductAdmissionRequirements(
+	cfg resourcePermissionConfig,
+	product iamdomain.ProductContext,
+) (productAdmissionDecision, error) {
+	if cfg.requirementErr != nil {
+		return productAdmissionDecision{}, cfg.requirementErr
+	}
+	if len(cfg.productRequirements) == 0 {
+		return productAdmissionDecision{Allowed: true}, nil
+	}
+	if product.ProductCode == "" {
+		return productAdmissionDecision{Failure: apierror.BadRequest(
+			apierror.CodeInvalidOperation,
+			"X-Product-Code header is required. Select a product first",
+		)}, nil
+	}
+
+	for i := range cfg.productRequirements {
+		requirement := cfg.productRequirements[i]
+		result, err := ruleexpression.Evaluate(requirement.expression, productAdmissionPredicateResolver(product))
+		if err != nil {
+			return productAdmissionDecision{}, fmt.Errorf("evaluate product admission requirement: %w", err)
+		}
+		switch result {
+		case ruleexpression.ResultTrue:
+			continue
+		case ruleexpression.ResultFalse:
+			return productAdmissionDecision{
+				ReasonCode:  requirement.deniedReason,
+				Explanation: requirement.explanation,
+			}, nil
+		default:
+			return productAdmissionDecision{
+				ReasonCode:  requiredProductRequirementIndeterminateReason,
+				Explanation: "required product condition could not be evaluated",
+			}, nil
+		}
+	}
+	return productAdmissionDecision{Allowed: true}, nil
+}
+
+func productAdmissionPredicateResolver(product iamdomain.ProductContext) ruleexpression.PredicateResolver {
+	return func(predicate *ruleexpression.PredicateNode) (ruleexpression.Result, error) {
+		switch predicate.Subject {
+		case ruleexpression.SubjectProduct:
+			actual := ""
+			switch predicate.Key {
+			case "code":
+				actual = product.ProductCode
+			case "lifecycle_status":
+				actual = product.LifecycleStatus
+			default:
+				return ruleexpression.ResultIndeterminate, nil
+			}
+			return compareProductRequirementString(actual, predicate.Operator, predicate.Value), nil
+		case ruleexpression.SubjectAttribute:
+			actual, known, present := product.AttributeFact(predicate.Key)
+			if !known {
+				return ruleexpression.ResultIndeterminate, nil
+			}
+			if predicate.Operator == ruleexpression.OperatorExists {
+				return productRequirementBooleanResult(present), nil
+			}
+			if !present {
+				return ruleexpression.ResultIndeterminate, nil
+			}
+			return compareProductRequirementJSON(actual, predicate.Operator, predicate.Value), nil
+		case ruleexpression.SubjectCapability:
+			active, known := product.CapabilityState(predicate.Key)
+			if !known {
+				return ruleexpression.ResultIndeterminate, nil
+			}
+			switch predicate.Operator {
+			case ruleexpression.OperatorActive:
+				return productRequirementBooleanResult(active), nil
+			case ruleexpression.OperatorInactive:
+				return productRequirementBooleanResult(!active), nil
+			default:
+				return ruleexpression.ResultIndeterminate, nil
+			}
+		default:
+			return ruleexpression.ResultIndeterminate, nil
+		}
+	}
+}
+
+func compareProductRequirementString(
+	actual string,
+	operator ruleexpression.Operator,
+	expected ruleexpression.Value,
+) ruleexpression.Result {
+	switch operator {
+	case ruleexpression.OperatorEqual, ruleexpression.OperatorNotEqual:
+		value, ok := expected.(*ruleexpression.StringValue)
+		if !ok {
+			return ruleexpression.ResultIndeterminate
+		}
+		equal := actual == value.Value
+		if operator == ruleexpression.OperatorNotEqual {
+			equal = !equal
+		}
+		return productRequirementBooleanResult(equal)
+	case ruleexpression.OperatorIn, ruleexpression.OperatorNotIn:
+		value, ok := expected.(*ruleexpression.StringArrayValue)
+		if !ok {
+			return ruleexpression.ResultIndeterminate
+		}
+		contains := false
+		for i := range value.Values {
+			if value.Values[i] == actual {
+				contains = true
+				break
+			}
+		}
+		if operator == ruleexpression.OperatorNotIn {
+			contains = !contains
+		}
+		return productRequirementBooleanResult(contains)
+	default:
+		return ruleexpression.ResultIndeterminate
+	}
+}
+
+func compareProductRequirementJSON(
+	actual json.RawMessage,
+	operator ruleexpression.Operator,
+	expected ruleexpression.Value,
+) ruleexpression.Result {
+	decoder := json.NewDecoder(bytes.NewReader(actual))
+	decoder.UseNumber()
+	var decoded any
+	if err := decoder.Decode(&decoded); err != nil {
+		return ruleexpression.ResultIndeterminate
+	}
+	if err := ensureProductRequirementJSONEOF(decoder); err != nil {
+		return ruleexpression.ResultIndeterminate
+	}
+
+	switch operator {
+	case ruleexpression.OperatorEqual, ruleexpression.OperatorNotEqual:
+		equal, comparable := productRequirementValueEqualsJSON(expected, decoded)
+		if !comparable {
+			return ruleexpression.ResultIndeterminate
+		}
+		if operator == ruleexpression.OperatorNotEqual {
+			equal = !equal
+		}
+		return productRequirementBooleanResult(equal)
+	case ruleexpression.OperatorIn, ruleexpression.OperatorNotIn:
+		values, ok := expected.(*ruleexpression.StringArrayValue)
+		actualString, stringOK := decoded.(string)
+		if !ok || !stringOK {
+			return ruleexpression.ResultIndeterminate
+		}
+		contains := false
+		for i := range values.Values {
+			if values.Values[i] == actualString {
+				contains = true
+				break
+			}
+		}
+		if operator == ruleexpression.OperatorNotIn {
+			contains = !contains
+		}
+		return productRequirementBooleanResult(contains)
+	default:
+		return ruleexpression.ResultIndeterminate
+	}
+}
+
+func productRequirementValueEqualsJSON(expected ruleexpression.Value, actual any) (bool, bool) { //nolint:T1 // any 是 JSON decoder 的封闭输出。
+	switch value := expected.(type) {
+	case *ruleexpression.BooleanValue:
+		actualValue, ok := actual.(bool)
+		return ok && actualValue == value.Value, ok
+	case *ruleexpression.NumberValue:
+		actualValue, ok := actual.(json.Number)
+		if !ok {
+			return false, false
+		}
+		parsed, err := actualValue.Float64()
+		return err == nil && parsed == value.Value, err == nil
+	case *ruleexpression.StringValue:
+		actualValue, ok := actual.(string)
+		return ok && actualValue == value.Value, ok
+	default:
+		return false, false
+	}
+}
+
+func ensureProductRequirementJSONEOF(decoder *json.Decoder) error {
+	var extra json.RawMessage
+	err := decoder.Decode(&extra)
+	if err == io.EOF {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	return fmt.Errorf("attribute value contains trailing JSON")
+}
+
+func productRequirementBooleanResult(value bool) ruleexpression.Result {
+	if value {
+		return ruleexpression.ResultTrue
+	}
+	return ruleexpression.ResultFalse
+}
+
+// ResourceAuthorizer IAM 授权能力（由 iam.Module 满足）。
+//
+// 接口由消费方（middleware）定义（Go 惯例 + 项目 A3：接口由使用者定义），
+// middleware → iam/domain 为单向依赖（iam/domain 不反向 import middleware，无环）。
+type ResourceAuthorizer interface {
+	// ResolvePrincipalByIdentity 按认证身份 ID 解析其活跃 IAM 主体（主键 != identity_id）。
+	ResolvePrincipalByIdentity(ctx context.Context, identityID int64) (*iamdomain.PrincipalRecord, error)
+	// AssembleAdminAccessContext 通过 IAM 唯一工厂装配请求授权上下文与产品事实。
+	AssembleAdminAccessContext(
+		ctx context.Context,
+		principal *iamdomain.PrincipalRecord,
+		input iamdomain.AdminAccessContextInput,
+	) (iamdomain.AdminAccessContext, error)
+	// Evaluate 单资源动作级求值：principal 对 (action, resource 模式) 是否有 Allow。
+	Evaluate(ctx context.Context, req iamdomain.EvaluateRequest) (iamdomain.Decision, error)
+	// EvaluateMany 批量求值：按 principal 分组装配语句集，N 个请求仅装配 distinct principal 次。
+	//
+	// 供菜单 IAM 投影按 sys_menus.iam_action 对当前主体一次性求值全部节点（避免逐节点重复装配语句）。
+	// 返回顺序与入参一一对应（与单资源 Evaluate 同源裁决，保证菜单可见性与路由守卫一致）。
+	EvaluateMany(ctx context.Context, reqs []iamdomain.EvaluateRequest) ([]iamdomain.Decision, error)
+	// ResolveScope 解析主体在 action 上的数据范围约束，供查询层注入 WHERE 过滤。
+	ResolveScope(ctx context.Context, principalID int64, action string, workspace iamdomain.WorkspaceContext) (iamscope.ScopeConstraint, error)
+	// ResolveProductScopes 解析主体在指定 action 上可见的产品集合。
+	//
+	// 供 global 域 handler（如产品注册表 / mediagen 列表）按操作员产品范围过滤结果集：
+	// unbounded=true 表示全产品访问（不过滤）；否则仅展示 products 集合内产品的数据。
+	// 该方法必须使用已解析 IAM 主体主键与动作名，避免认证身份 ID 或无关 global 授权扩大产品范围。
+	ResolveProductScopes(ctx context.Context, principalID int64, action string) (products []string, unbounded bool, err error)
+}
+
+// ResourceDecisionLogger 由授权模块实现，用于高风险动作写入访问决策日志。
+type ResourceDecisionLogger interface {
+	LogDecision(ctx context.Context, req iamdomain.EvaluateRequest, decision iamdomain.Decision, risk iamdomain.RiskLevel)
+}
+
+// RequireResourcePermission 资源动作级授权中间件（两阶段授权第一阶段，设计 §6.4）。
+//
+// 职责边界：
+//   - 做「动作级」检查——principal 对 (action, resource 模式) 是否有 Allow（含 time/ip
+//     等非资源条件）。不在请求期校验具体资源实例归属（业务对象此时尚未加载）。
+//   - 放行后将 ResolveScope 产出的 ScopeConstraint 注入 gin ctx，供下游查询层作为
+//     WHERE 过滤统一执行资源归属收敛（单资源 get 不属于自己 scope → 查询返回
+//     not-found，而非中间件 403）。
+//
+// resourceTemplate 为 ARN 形态模板，占位符在请求期替换：
+//   - {product_code} ← 中间件已 resolve 的产品上下文（GetProductCode）。
+//   - 其余 {name}     ← 同名路径参数 c.Param("name")（如 {id}、{store_id}）。
+//
+// list 端点模板无 {id} 时保留集合 / 通配模式（如以 ** 收尾），由 Evaluate 做模式匹配。
+func RequireResourcePermission(authz ResourceAuthorizer, action string, resourceTemplate string, opts ...ResourcePermissionOption) gin.HandlerFunc {
+	cfg := resourcePermissionConfig{}
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return func(c *gin.Context) {
+		principal, sourceIP, apiErr := resolveRequestPrincipal(c, authz)
+		if apiErr != nil {
+			abortWithAPIError(c, apiErr)
+			return
+		}
+
+		resourceARN := resolveResourceTemplate(c, resourceTemplate)
+		accessCtx, err := authz.AssembleAdminAccessContext(c.Request.Context(), principal, iamdomain.AdminAccessContextInput{
+			Principal: iamdomain.PrincipalContext{
+				SourceIP: sourceIP,
+			},
+			Workspace: iamdomain.WorkspaceContext{
+				ProductCode: string(GetProductCode(c)),
+			},
+			Request: iamdomain.RequestContext{
+				RequestID:      GetRequestID(c),
+				IdempotencyKey: c.GetHeader(types.HeaderIdempotencyKey),
+				UserAgent:      c.Request.UserAgent(),
+				Method:         c.Request.Method,
+				Action:         action,
+				SourceIP:       sourceIP,
+				RouteName:      c.FullPath(),
+			},
+			Resource: iamdomain.ResourceContext{
+				ARN: resourceARN,
+			},
+		})
+		if err != nil {
+			abortWithAPIError(c, productContextAPIError(string(GetProductCode(c)), err))
+			return
+		}
+		c.Request = c.Request.WithContext(withAdminAccessContext(c.Request.Context(), accessCtx))
+
+		evalReq := iamdomain.EvaluateRequest{
+			PrincipalID: principal.ID,
+			Action:      action,
+			Resource:    resourceARN,
+			Context:     accessCtx,
+		}
+		admission, err := evaluateProductAdmissionRequirements(cfg, accessCtx.Product)
+		if err != nil {
+			abortWithAPIError(c, apierror.Internal("Product admission requirement is invalid"))
+			return
+		}
+		if admission.Failure != nil {
+			abortWithAPIError(c, admission.Failure)
+			return
+		}
+		if !admission.Allowed {
+			decision := iamdomain.NewDeniedDecision(
+				action,
+				resourceARN,
+				admission.ReasonCode,
+				nil,
+				admission.Explanation,
+			)
+			SetResourcePermissionDecision(c, ResourcePermissionDecision{
+				Action:      action,
+				Resource:    resourceARN,
+				Allowed:     false,
+				ReasonCode:  decision.ReasonCode,
+				ReasonKind:  string(decision.ReasonKind),
+				PrincipalID: principal.ID,
+			})
+			logAccessDecision(c.Request.Context(), authz, evalReq, decision, cfg.decisionRisk)
+			abortWithAPIError(c, apierror.Forbidden("Forbidden: "+decision.ReasonCode))
+			return
+		}
+
+		decision, err := authz.Evaluate(c.Request.Context(), evalReq)
+		if err != nil {
+			abortWithAPIError(c, apierror.Internal("Authorization check failed"))
+			return
+		}
+		permissionDecision := ResourcePermissionDecision{
+			Action:      evalReq.Action,
+			Resource:    evalReq.Resource,
+			Allowed:     decision.Allowed,
+			ReasonCode:  decision.ReasonCode,
+			ReasonKind:  string(decision.ReasonKind),
+			PrincipalID: principal.ID,
+		}
+		SetResourcePermissionDecision(c, permissionDecision)
+		logAccessDecision(c.Request.Context(), authz, evalReq, decision, cfg.decisionRisk)
+		if !decision.Allowed {
+			// 携带决策原因码，便于客户端与审计区分拒绝来源（仿 RequirePermission 的 403 写法）。
+			abortWithAPIError(c, apierror.Forbidden("Forbidden: "+decision.ReasonCode))
+			return
+		}
+
+		// 动作级放行 → 以主体主键解析数据范围约束注入 ctx，交给查询层做 WHERE 过滤。
+		scope, err := authz.ResolveScope(c.Request.Context(), principal.ID, action, accessCtx.Workspace)
+		if err != nil {
+			abortWithAPIError(c, apierror.Internal("Scope resolution failed"))
+			return
+		}
+		permissionDecision.ScopeConstraintSummary = summarizeScopeConstraint(scope)
+		SetResourcePermissionDecision(c, permissionDecision)
+		SetScopeConstraint(c, scope)
+		// 主体主键随约束一并注入：self 维度（assigned_to_self 等）下推时需用它填充列谓词。
+		SetScopePrincipalID(c, principal.ID)
+
+		c.Next()
+	}
+}
+
+// GetAdminAccessContext 读取路由授权阶段装配的完整 IAM 求值上下文。
+func GetAdminAccessContext(ctx context.Context) (iamdomain.AdminAccessContext, bool) {
+	v := ctx.Value(adminAccessContextKey{})
+	accessCtx, ok := v.(iamdomain.AdminAccessContext)
+	return accessCtx, ok
+}
+
+func withAdminAccessContext(ctx context.Context, accessCtx iamdomain.AdminAccessContext) context.Context {
+	return context.WithValue(ctx, adminAccessContextKey{}, accessCtx)
+}
+
+func logAccessDecision(
+	ctx context.Context,
+	authz ResourceAuthorizer,
+	req iamdomain.EvaluateRequest,
+	decision iamdomain.Decision,
+	risk iamdomain.RiskLevel,
+) {
+	if !risk.RequiresDecisionLog() {
+		return
+	}
+	logger, ok := authz.(ResourceDecisionLogger)
+	if !ok {
+		return
+	}
+	logger.LogDecision(ctx, req, decision, risk)
+}
+
+func resolveRequestPrincipal(
+	c *gin.Context,
+	authz ResourceAuthorizer,
+) (*iamdomain.PrincipalRecord, string, *apierror.APIError) {
+	sourceIP := ResolveTrustedClientIP(c)
+	if iamPrincipal := GetAuthenticatedIAMPrincipal(c); iamPrincipal != nil {
+		if iamPrincipal.SourceIP != "" {
+			sourceIP = iamPrincipal.SourceIP
+		}
+		return &iamdomain.PrincipalRecord{
+			ID:            iamPrincipal.PrincipalID,
+			PrincipalNo:   iamPrincipal.PrincipalNo,
+			PrincipalType: iamPrincipal.PrincipalType,
+			IdentityID:    iamPrincipal.IdentityID,
+			IsActive:      true,
+			Version:       iamPrincipal.PrincipalVersion,
+		}, sourceIP, nil
+	}
+
+	identity := GetUserIdentity(c)
+	if identity == nil {
+		return nil, sourceIP, apierror.Unauthorized()
+	}
+
+	// 把认证身份 ID 解析为真实 IAM 主体：主体主键（binding 的 principal_id 指向它）
+	// 与 identity_id 是两个语义不同的标识（SH-I1），不可混用。授权全程以主体主键展开。
+	principal, err := authz.ResolvePrincipalByIdentity(c.Request.Context(), identity.IdentityID.Int64())
+	if err != nil {
+		// 身份未映射到活跃主体 → 无任何授权可言，拒绝（403）；其余为查询故障（500）。
+		if errors.Is(err, iamdomain.ErrPrincipalNotFound) {
+			return nil, sourceIP, apierror.Forbidden("Forbidden: no active principal")
+		}
+		return nil, sourceIP, apierror.Internal("Principal resolution failed")
+	}
+	return principal, sourceIP, nil
+}
+
+// ResolveRequestPrincipal 解析当前请求中的 IAM 授权主体与来源 IP。
+//
+// 非守卫型 handler 需要做产品范围过滤时复用该入口，保证人类身份和服务账号凭证都解析为同一种
+// IAM 主体主键，避免自行读取 identity_id 后误用为 principal_id。
+func ResolveRequestPrincipal(
+	c *gin.Context,
+	authz ResourceAuthorizer,
+) (*iamdomain.PrincipalRecord, string, *apierror.APIError) {
+	return resolveRequestPrincipal(c, authz)
+}
+
+// resolveResourceTemplate 把 ARN 模板的占位符替换为请求期实际值。
+//
+// {product_code} ← GetProductCode(c)；其余 {name} ← c.Param("name")。
+// 无对应来源的占位符替换为空串（让模板段缺值，由 Evaluate 的 ARN 模式匹配兜底）。
+func resolveResourceTemplate(c *gin.Context, template string) string {
+	if !strings.ContainsRune(template, '{') {
+		return template
+	}
+	var b strings.Builder
+	b.Grow(len(template))
+	rest := template
+	for {
+		open := strings.IndexByte(rest, '{')
+		if open < 0 {
+			b.WriteString(rest)
+			break
+		}
+		closeIdx := strings.IndexByte(rest[open:], '}')
+		if closeIdx < 0 {
+			// 无闭合括号 → 原样输出剩余串（不臆造截断）。
+			b.WriteString(rest)
+			break
+		}
+		closeIdx += open
+		b.WriteString(rest[:open])
+		name := rest[open+1 : closeIdx]
+		b.WriteString(resolveTemplateToken(c, name))
+		rest = rest[closeIdx+1:]
+	}
+	return b.String()
+}
+
+// resolveTemplateToken 解析单个占位符 token 的实际值。
+func resolveTemplateToken(c *gin.Context, name string) string {
+	if name == "product_code" {
+		return string(GetProductCode(c))
+	}
+	if name == "organization_ref" {
+		if access := GetIAMDelegatedAccessContext(c); access != nil {
+			return access.OrganizationRef
+		}
+	}
+	return c.Param(name)
+}
+
+// SetScopeConstraint 在 gin.Context 写入数据范围约束，供下游查询层注入 WHERE。
+func SetScopeConstraint(c *gin.Context, sc iamscope.ScopeConstraint) {
+	c.Set(scopeConstraintKey, sc)
+}
+
+// GetScopeConstraint 读取由 RequireResourcePermission 注入的数据范围约束。
+//
+// 返回 ok=false 表示当前路由未经过资源授权中间件（下游查询层应据此 fail-safe 处理）。
+func GetScopeConstraint(c *gin.Context) (iamscope.ScopeConstraint, bool) {
+	v, ok := c.Get(scopeConstraintKey)
+	if !ok {
+		return iamscope.ScopeConstraint{}, false
+	}
+	sc, ok := v.(iamscope.ScopeConstraint)
+	if !ok {
+		return iamscope.ScopeConstraint{}, false
+	}
+	return sc, true
+}
+
+// SetScopePrincipalID 在 gin.Context 写入已解析的 IAM 主体主键，供查询层填充 self 维度谓词。
+func SetScopePrincipalID(c *gin.Context, principalID int64) {
+	c.Set(scopePrincipalIDKey, principalID)
+}
+
+// GetScopePrincipalID 读取由 RequireResourcePermission 注入的 IAM 主体主键。
+//
+// 返回 ok=false 表示当前路由未经过资源授权中间件（查询层应据此 fail-safe 处理，
+// 与 GetScopeConstraint 的 ok 语义一致）。
+func GetScopePrincipalID(c *gin.Context) (int64, bool) {
+	v, ok := c.Get(scopePrincipalIDKey)
+	if !ok {
+		return 0, false
+	}
+	principalID, ok := v.(int64)
+	if !ok {
+		return 0, false
+	}
+	return principalID, true
+}
+
+// SetResourcePermissionDecision 在 gin.Context 写入资源授权裁决证据，供操作日志读取。
+func SetResourcePermissionDecision(c *gin.Context, decision ResourcePermissionDecision) {
+	c.Set(resourcePermissionDecisionKey, decision)
+}
+
+// GetResourcePermissionDecision 读取由 RequireResourcePermission 写入的资源授权裁决证据。
+func GetResourcePermissionDecision(c *gin.Context) (ResourcePermissionDecision, bool) {
+	v, ok := c.Get(resourcePermissionDecisionKey)
+	if !ok {
+		return ResourcePermissionDecision{}, false
+	}
+	decision, ok := v.(ResourcePermissionDecision)
+	if !ok {
+		return ResourcePermissionDecision{}, false
+	}
+	return decision, true
+}
+
+func summarizeScopeConstraint(scope iamscope.ScopeConstraint) string {
+	switch {
+	case scope.IsUnbounded():
+		return "unbounded"
+	case scope.IsEmpty():
+		return "empty"
+	default:
+		dimensions := scopeConstraintDimensions(scope)
+		if len(dimensions) == 0 {
+			return "bounded"
+		}
+		return "allow_groups=" + strconv.Itoa(len(scope.AllowGroups)) +
+			";deny_groups=" + strconv.Itoa(len(scope.DenyGroups)) +
+			";dimensions=" + strings.Join(dimensions, ",")
+	}
+}
+
+func scopeConstraintDimensions(scope iamscope.ScopeConstraint) []string {
+	seen := make(map[string]struct{})
+	for _, group := range scope.AllowGroups {
+		for _, predicate := range group {
+			seen[string(predicate.Dimension)] = struct{}{}
+		}
+	}
+	for _, group := range scope.DenyGroups {
+		for _, predicate := range group {
+			seen[string(predicate.Dimension)] = struct{}{}
+		}
+	}
+	dimensions := make([]string, 0, len(seen))
+	for dimension := range seen {
+		dimensions = append(dimensions, dimension)
+	}
+	sort.Strings(dimensions)
+	return dimensions
+}