authorization

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 13 Imported by: 0

README

authorization — 强授权档

YAML 操作目录（闭集校验 + 确定性哈希）+ 阶段化纯函数评估器 （authentication → scope → membership → role → policy → input，deny 携带阶段与 原因码）+ 三值决策（allow / deny / challenge）+ 规则注册表（内置 assurance / recent-auth 两条通用 step-up 规则，产品可注入自有规则与 fact 键）

  • 事务内 Facts Provider。

本包自包含：不 import 框架其他包（含 authz）。

authorization ↔ authz 概念映射（风险 F3 的解）

authz/（简单档）与本包（强档）并列共存，互不依赖：简单档是单层 RBAC 权限点检查，强档是操作目录驱动的闭集评估。不存在迁移压力——同一产品可以只用 简单档，也可以按操作逐个切换到强档。

什么场景用哪档
场景 用哪档
"角色 → 权限点"够用（单层 workspace，owner/admin/member 式角色映射） authz：Authorizer.Can(principal, "tasks:write")，一个中间件 Require 搞定路由保护
需要 step-up（AAL2 / recent-auth / sudo 模式） authorization：challenge 是一等决策，携带目标操作、要求的 assurance、max-age
凭据要绑 scope（细粒度 PAT / 机器凭据，GitHub FG-PAT 形态） authorization：ScopedTokenPrincipal / MachineCredentialPrincipal，scope 精确匹配不可替换
需要 deny 可解释（哪个阶段、什么原因码）供审计/反枚举策略 authorization：Decision{Stage, ReasonCode} 结构化拒绝
操作集要可哈希、可对账（目录 ↔ 路由 ↔ 契约比对） authorization：Catalog.Hash() 确定性哈希是 C4 contractx 的地基
嵌套 scope（workspace → project 两层） 两档都留了形状；强档的 scope 输入类型（WorkspaceScope / ProjectScope）两层原生
词汇对应表
authz（简单档） authorization（强档） 对应关系
Permission（域:动作，如 tasks:write） Operation.OperationID（产品自定义，如 op.task.update） 权限点 ↔ 目录操作条目；强档每个操作是一条显式声明
域:* 通配、*_own 后缀 不存在（目录内禁通配；资源属主判定走产品规则注册表或调用方 facts） 强档闭集确定性优先；两者互斥（重做 §1.7）
RoleOwner/Admin/Member + RoleSet 显式集合 roles.workspace / roles.project 词汇表（产品数据）+ 操作的 allowed_*_roles 两档都无角色继承：owner ⊇ admin 靠显式集合，强档靠"交集非空"判定
Catalog（Go 代码 Register 权限点） Catalog（YAML 文件 + 严格 schema 校验 + 哈希） 简单档词汇在代码里；强档词汇是可对账的数据文件
Authorizer.Can/CanIn(ctx, p, perm) bool Evaluate(Request) Decision / Evaluator.Authorize(ctx, opID, ...) 两值布尔 ↔ 三值决策（含 challenge）
authz.Require(a, perm) 中间件 无中间件入口（刻意） F3 缓解：中间件入口不重复建设。强档消费者直接调 evaluator，传输层路由 resolver（method+path → operation）是产品侧职责
Provider.PermsFor + 30s TTL 缓存 FactsProvider.Facts(ctx, principal, scope)，无缓存 一致性权衡差异：强档约定在调用方事务内取事实（撤销即时一致）；接受读旧可自行包装 provider，那是显式选择
平台管理员旁路 IsPlatformAdmin → true 无旁路（每个操作显式声明，匿名操作用 auth_method: unauthenticated） 强档闭集哲学：没有隐式超级权限
—（无对应） Challenge / DenialError / ErrReauthenticationRequired step-up 通道：challenge 投影为 REAUTH 类稳定错误 + hint 载荷，不降级为权限类

快速上手

// 1. 写 operations.yaml（闭集：角色词汇 + 操作声明，无通配）
// 2. 启动期组装
registry := authorization.NewRegistry()          // 内置 assurance/recent-auth
registry.Register(myLifecycleRule{})             // 产品规则（可选）
registry.RegisterFact("project_lifecycle")       // 产品 fact 键（可选）
catalog, err := authorization.ParseCatalog(raw, registry)
evaluator, err := authorization.NewEvaluator(catalog, registry, myTxProvider)

// 3. 请求路径上（ctx 携带调用方事务）
decision, err := evaluator.Authorize(ctx, "op.task.update", principal,
    authorization.ProjectScope{WorkspaceID: "ws", ProjectID: "pj"}, time.Now())
switch decision.Outcome {
case authorization.OutcomeAllow:    // 放行
case authorization.OutcomeChallenge: // step-up：透出 decision.Challenge（目标操作/assurance/max-age）
    return decision.Err()            // errors.Is(err, ErrReauthenticationRequired)
default:                             // deny：阶段 + 原因码可审计
    return decision.Err()            // errors.Is(err, ErrDenied)
}

护栏（明确不做）

  • 目录内禁 域:* 通配（与简单档互斥）；
  • 无角色继承魔法（显式集合 / 交集非空）；
  • 只做两层 scope 输入形状（workspace → project），不做任意深度；
  • 不做 ReBAC / 策略引擎；不内置 TTL 缓存；
  • 审批编排、Phase0、具名审批不进（组织纪律留产品）。

golden 基准

evaluator_golden_test.go 锁定评估器的确定性语义（阶段顺序/原因码/challenge 投影） （docs/ploykit-m0-golden-subset.md，12 例：G-1..G-7 两值 + CH-1..CH-5 挑战）， 全部在"空产品注册表 + 仅内置规则"下通过——空注册表可过 = 通用。

Documentation

Index

Constants

View Source 
const (
	ReasonAllowed                      = "allowed"
	ReasonUnknownOperationOrScope      = "unknown_operation_or_scope"
	ReasonAuthMethodNotAllowed         = "auth_method_not_allowed"
	ReasonPrincipalRequired            = "principal_required"
	ReasonSessionInactive              = "session_inactive"
	ReasonCredentialInactive           = "credential_inactive"
	ReasonAssuranceRequired            = "assurance_required"
	ReasonRecentAuthRequired           = "recent_auth_required"
	ReasonScopeMismatch                = "scope_mismatch"
	ReasonPrincipalScopeMismatch       = "principal_scope_mismatch"
	ReasonCredentialMembershipInactive = "credential_membership_inactive"
	ReasonWorkspaceMembershipInactive  = "workspace_membership_inactive"
	ReasonProjectMembershipInactive    = "project_membership_inactive"
	ReasonWorkspaceRoleNotAllowed      = "workspace_role_not_allowed"
	ReasonProjectRoleNotAllowed        = "project_role_not_allowed"
	ReasonIdempotencyInvalid           = "idempotency_invalid"
)
View Source 
const (
	DenialCodePermissionDenied = "PERMISSION_DENIED"
	DenialCodeReauthRequired   = "REAUTH_REQUIRED"
)
View Source 
const (
	RuleNameAssurance  = "assurance"
	RuleNameRecentAuth = "recent_auth"
)
View Source 
const CurrentCatalogSchemaVersion = 1
View Source 
const RecentAuthWindow = 600 * time.Second

Variables

View Source 
var (
	ErrDenied = errors.New("authorization: denied")

	ErrReauthenticationRequired = errors.New("authorization: reauthentication required")
)

Functions

This section is empty.

Types

type Assurance 

type Assurance string
const (
	AssuranceNone Assurance = "none"
	AssuranceAAL1 Assurance = "aal1"
	AssuranceAAL2 Assurance = "aal2"
)

type AuthMethod 

type AuthMethod string
const (
	AuthMethodUnauthenticated   AuthMethod = "unauthenticated"
	AuthMethodSession           AuthMethod = "session"
	AuthMethodScopedToken       AuthMethod = "scoped_token"
	AuthMethodMachineCredential AuthMethod = "machine_credential"
)

type Catalog 

type Catalog struct {
	CatalogSchemaVersion int         `yaml:"catalog_schema_version" json:"catalog_schema_version"`
	Roles                RoleVocab   `yaml:"roles" json:"roles"`
	Operations           []Operation `yaml:"operations" json:"operations"`
}

func ParseCatalog 

func ParseCatalog(raw []byte, reg *Registry) (Catalog, error)

func (Catalog) Hash 

func (c Catalog) Hash() (string, error)

func (Catalog) Operation 

func (c Catalog) Operation(operationID string) (Operation, bool)

func (Catalog) Validate 

func (c Catalog) Validate(reg *Registry) error

type Challenge 

type Challenge struct {
	TargetOperationID string
	RequiredAssurance Assurance
	MaxAge            time.Duration
}

type Decision 

type Decision struct {
	Outcome    Outcome
	Stage      Stage
	ReasonCode string
	Challenge  *Challenge
}

func Evaluate 

func Evaluate(request Request) Decision

func NewChallenge 

func NewChallenge(op Operation) Decision

func (Decision) Allowed 

func (d Decision) Allowed() bool

func (Decision) Err 

func (d Decision) Err() error

type DenialError 

type DenialError struct {
	Decision   Decision
	Code       string
	ReauthHint *Challenge
}

func (*DenialError) Error 

func (e *DenialError) Error() string

func (*DenialError) Is 

func (e *DenialError) Is(target error) bool

type Evaluator 

type Evaluator struct {
	// contains filtered or unexported fields
}

func NewEvaluator 

func NewEvaluator(catalog Catalog, registry *Registry, provider FactsProvider) (*Evaluator, error)

func (*Evaluator) Authorize 

func (e *Evaluator) Authorize(ctx context.Context, operationID string, principal Principal, scope Scope, now time.Time) (Decision, error)

func (*Evaluator) Catalog 

func (e *Evaluator) Catalog() Catalog

func (*Evaluator) Registry 

func (e *Evaluator) Registry() *Registry

type Facts 

type Facts struct {
	ActiveUser            bool
	ActiveSession         bool
	CredentialGrantActive bool

	ActiveWorkspaceMembership bool
	ActiveProjectMembership   bool

	WorkspaceRoles []string
	ProjectRoles   []string

	Assurance        Assurance
	RecentPasswordAt time.Time
	RecentMFAAt      time.Time

	IdempotencyValid bool

	Product map[string]any
}

type FactsProvider 

type FactsProvider interface {
	Facts(ctx context.Context, principal Principal, scope Scope) (Facts, error)
}

type IdempotencyRule 

type IdempotencyRule string
const (
	IdempotencyNone     IdempotencyRule = "none"
	IdempotencyRequired IdempotencyRule = "required"
)

type MachineCredentialPrincipal 

type MachineCredentialPrincipal struct {
	CredentialID string
	Scope        ProjectScope
	NotBefore    time.Time
	ExpiresAt    time.Time
}

func (MachineCredentialPrincipal) AuthMethod 

func (MachineCredentialPrincipal) AuthMethod() AuthMethod

func (MachineCredentialPrincipal) Subject 

func (p MachineCredentialPrincipal) Subject() string

type Operation 

type Operation struct {
	OperationID           string          `yaml:"operation_id" json:"operation_id"`
	AuthMethod            AuthMethod      `yaml:"auth_method" json:"auth_method"`
	Scope                 ScopeKind       `yaml:"scope" json:"scope"`
	AllowedWorkspaceRoles []string        `yaml:"allowed_workspace_roles" json:"allowed_workspace_roles,omitempty"`
	AllowedProjectRoles   []string        `yaml:"allowed_project_roles" json:"allowed_project_roles,omitempty"`
	Assurance             Assurance       `yaml:"assurance" json:"assurance"`
	RecentAuth            RecentAuthRule  `yaml:"recent_auth" json:"recent_auth"`
	Idempotency           IdempotencyRule `yaml:"idempotency" json:"idempotency"`

	Rules []string `yaml:"rules" json:"rules,omitempty"`
}

type Outcome 

type Outcome uint8
const (
	OutcomeDeny Outcome = iota
	OutcomeAllow
	OutcomeChallenge
)

type PlatformScope 

type PlatformScope struct{}

func (PlatformScope) Project 

func (PlatformScope) Project() (string, bool)

func (PlatformScope) Workspace 

func (PlatformScope) Workspace() (string, bool)

type Principal 

type Principal interface {
	AuthMethod() AuthMethod

	Subject() string
	// contains filtered or unexported methods
}

type ProjectScope 

type ProjectScope struct {
	WorkspaceID string
	ProjectID   string
}

func (ProjectScope) Project 

func (s ProjectScope) Project() (string, bool)

func (ProjectScope) Workspace 

func (s ProjectScope) Workspace() (string, bool)

type RecentAuthRule 

type RecentAuthRule string
const (
	RecentAuthNone           RecentAuthRule = "none"
	RecentAuthPassword       RecentAuthRule = "password_600s"
	RecentAuthPasswordAndMFA RecentAuthRule = "password_and_mfa_600s"
)

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) FactNames 

func (r *Registry) FactNames() []string

func (*Registry) IsBuiltin 

func (r *Registry) IsBuiltin(name string) bool

func (*Registry) Register 

func (r *Registry) Register(rule Rule) error

func (*Registry) RegisterFact 

func (r *Registry) RegisterFact(name string) error

func (*Registry) Resolve 

func (r *Registry) Resolve(names []string) ([]Rule, error)

func (*Registry) Rule 

func (r *Registry) Rule(name string) (Rule, bool)

func (*Registry) RuleNames 

func (r *Registry) RuleNames() []string

func (*Registry) ValidateFacts 

func (r *Registry) ValidateFacts(facts Facts) error

type Request 

type Request struct {
	Operation Operation

	Principal Principal
	Scope     Scope
	Facts     Facts

	Now time.Time

	Rules []Rule
}

type RoleVocab 

type RoleVocab struct {
	Workspace []string `yaml:"workspace" json:"workspace"`
	Project   []string `yaml:"project" json:"project"`
}

type Rule 

type Rule interface {
	RuleName() string

	Stage() Stage

	Evaluate(Request) (Decision, bool)
}

type Scope 

type Scope interface {
	Workspace() (string, bool)

	Project() (string, bool)
	// contains filtered or unexported methods
}

type ScopeKind 

type ScopeKind string
const (
	ScopeKindPlatform ScopeKind = "platform"

	ScopeKindWorkspacePath ScopeKind = "workspace_path"

	ScopeKindProjectPath ScopeKind = "project_path"

	ScopeKindProjectGovernance ScopeKind = "project_governance"

	ScopeKindProjectCredential ScopeKind = "project_credential"
)

type ScopedTokenPrincipal 

type ScopedTokenPrincipal struct {
	SubjectID string
	TokenID   string
	Scope     ProjectScope
}

func (ScopedTokenPrincipal) AuthMethod 

func (ScopedTokenPrincipal) AuthMethod() AuthMethod

func (ScopedTokenPrincipal) Subject 

func (p ScopedTokenPrincipal) Subject() string

type SessionPrincipal 

type SessionPrincipal struct {
	SubjectID      string
	SessionID      string
	Assurance      Assurance
	AbsoluteExpiry time.Time
	IdleExpiry     time.Time
}

func (SessionPrincipal) AuthMethod 

func (SessionPrincipal) AuthMethod() AuthMethod

func (SessionPrincipal) Subject 

func (p SessionPrincipal) Subject() string

type Stage 

type Stage string
const (
	StageAuthentication Stage = "authentication"
	StageScope          Stage = "scope"
	StageMembership     Stage = "membership"
	StageRole           Stage = "role"
	StagePolicy         Stage = "policy"
	StageInput          Stage = "input"

	StageComplete Stage = "complete"
)

type WorkspaceScope 

type WorkspaceScope struct{ WorkspaceID string }

func (WorkspaceScope) Project 

func (WorkspaceScope) Project() (string, bool)

func (WorkspaceScope) Workspace 

func (s WorkspaceScope) Workspace() (string, bool)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.