gating

package
v0.0.0-...-af2e488 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package gating composes account and entity requirements with authz ACLs. Providers and mappings are trusted host dependencies, never request payloads.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidRequirements = errors.New("invalid gate requirements document")
View Source
var ErrUnavailable = errors.New("authorization gate unavailable")

Functions

func CanonicalSelection

func CanonicalSelection(input []authz.Entity) ([]authz.Entity, string, error)

CanonicalSelection preserves exact entity strings while sorting and deduplicating typed tuples for provider request binding.

func DecodeActionRequirements

func DecodeActionRequirements(payload []byte) (map[string]Requirements, error)

DecodeActionRequirements validates a versioned requirements document keyed by canonical action. It rejects duplicate keys and unknown nested fields so readers and writers cannot interpret the same stored bytes differently.

func SamePrincipalAuthority

func SamePrincipalAuthority(a, b Principal) bool

SamePrincipalAuthority compares the verified identity and account facts that bind one authorization operation. Leases are checked separately by callers.

func ValidProviderDecision

func ValidProviderDecision(d Decision, r ProviderRequest, now time.Time) bool

ValidProviderDecision verifies every request/identity/resource binding and the live authority lease for an injected provider response.

Types

type ActorRequirementsWriter

type ActorRequirementsWriter interface {
	ReplaceRequirementsAs(context.Context, authz.Resource, string, string, Requirements, string) (RequirementsDocument, error)
}

ActorRequirementsWriter records the subject proven by manageAccess. Hosts with audit-capable stores implement this without changing older writers.

type Administration

type Administration struct {
	ACL     *authz.Service
	Store   RequirementsStore
	Writer  RequirementsWriter
	Choices ChoicesProvider
}

func (*Administration) Context

func (a *Administration) Context(ctx context.Context, resource authz.Resource, action string) (EditorContext, error)

func (*Administration) Get

func (a *Administration) Get(ctx context.Context, resource authz.Resource, action string) (RequirementsDocument, error)

func (*Administration) Replace

func (a *Administration) Replace(ctx context.Context, resource authz.Resource, action, expectedRevision string, requirements Requirements) (RequirementsDocument, error)

type Binding

type Binding struct {
	Resource authz.Resource       `json:"resource"`
	Action   string               `json:"action"`
	Document RequirementsDocument `json:"document"`
}

Binding is a host-owned, versioned requirement mapping for one exact resource/action. It is suitable for existing file-backed windows without a reporting database. Configuration reloads construct a new immutable store.

type Choice

type Choice struct {
	ID    string `json:"id"`
	Label string `json:"label,omitempty"`
}

type ChoiceBinding

type ChoiceBinding struct {
	Resource authz.Resource `json:"resource"`
	Action   string         `json:"action"`
	Choices  EditorChoices  `json:"choices"`
}

type ChoicesProvider

type ChoicesProvider interface {
	ResolveChoices(context.Context, authz.Resource, string) (EditorChoices, error)
}

type Decision

type Decision struct {
	SchemaVersion        int       `json:"schemaVersion"`
	DecisionID           string    `json:"decisionId"`
	RequestID            string    `json:"requestId"`
	Subject              string    `json:"subject"`
	Issuer               string    `json:"issuer"`
	TenantID             string    `json:"tenantId"`
	AccountID            string    `json:"accountId"`
	ResourceKind         string    `json:"resourceKind"`
	ResourceID           string    `json:"resourceId"`
	ResourceVersion      string    `json:"resourceVersion"`
	Action               string    `json:"action"`
	RequirementsRevision string    `json:"requirementsRevision"`
	EntitySelectionHash  string    `json:"entitySelectionHash"`
	Effect               string    `json:"effect"`
	ReasonCode           string    `json:"reasonCode,omitempty"`
	ValidUntil           time.Time `json:"validUntil"`
	ProviderRevision     string    `json:"providerRevision"`
	RequirementKey       string    `json:"requirementKey,omitempty"`
	ProviderRef          string    `json:"providerRef,omitempty"`
}

type EditorChoices

type EditorChoices struct {
	Exposures            []Choice            `json:"exposures,omitempty"`
	Roles                []Choice            `json:"roles,omitempty"`
	EntityTypes          []Choice            `json:"entityTypes,omitempty"`
	EntityPermissions    map[string][]Choice `json:"entityPermissions,omitempty"`
	SelectionParameters  []Choice            `json:"selectionParameters,omitempty"`
	EntitlementProviders []Choice            `json:"entitlementProviders,omitempty"`
	EntitlementKeys      map[string][]Choice `json:"entitlementKeys,omitempty"`
}

type EditorContext

type EditorContext struct {
	CanManage bool          `json:"canManage"`
	Choices   EditorChoices `json:"choices"`
}

type EntitlementProvider

type EntitlementProvider interface {
	CheckEntitlement(context.Context, ProviderRequest) (Decision, error)
}

type EntitlementRequirement

type EntitlementRequirement struct {
	ProviderRef string `json:"providerRef"`
	Key         string `json:"key"`
	Scope       string `json:"scope"` // account or entity
}

type EntityPermissionProvider

type EntityPermissionProvider interface {
	CheckEntityPermission(context.Context, ProviderRequest) (Decision, error)
}

type EntityRequirement

type EntityRequirement struct {
	Type               string `json:"type"`
	Permission         string `json:"permission"`
	SelectionParameter string `json:"selectionParameter,omitempty"`
	SelectionMode      string `json:"selectionMode"` // single or multiple
}

type Evaluator

type Evaluator struct {
	ACL          *authz.Service
	Principals   PrincipalResolver
	Requirements RequirementsStore
	Entities     EntityPermissionProvider
	Entitlements map[string]EntitlementProvider // trusted providerRef registry
	Now          func() time.Time
}

func (*Evaluator) Check

func (e *Evaluator) Check(ctx context.Context, resource authz.Resource, action string, selected []authz.Entity) (bool, string, time.Time, string, string, string, string, error)

Check is the narrow in-process host bridge. Primitive return fields keep a consumer independent of the gating package version while retaining the identity, account, revision and lease bindings it must verify.

func (*Evaluator) CheckRequirementsOnly

func (e *Evaluator) CheckRequirementsOnly(ctx context.Context, resource authz.Resource, action string, selected []authz.Entity) (bool, string, time.Time, string, string, string, string, error)

CheckRequirementsOnly is the narrow host bridge for inherited and public consumption ACL modes. Its allow result must be intersected with a separately established workspace/child grant; it cannot authorize consumption alone.

func (*Evaluator) Evaluate

func (e *Evaluator) Evaluate(ctx context.Context, req Request) (Decision, error)

func (*Evaluator) EvaluateRequirementsOnly

func (e *Evaluator) EvaluateRequirementsOnly(ctx context.Context, req Request) (Decision, error)

EvaluateRequirementsOnly checks mandatory requirements for a child whose ACL is inherited or whose explicit publicConsumption grant was established by a trusted host. Its allow result is never an ACL grant by itself.

type FileStore

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

FileStore is a durable single-process gate registry. The configured binding list is its allowlist; a retired file cannot reactivate a removed binding. Updates replace one complete history file atomically under an in-process CAS lock. Clustered hosts should supply their own transactional writer.

func NewFileStore

func NewFileStore(root string, bindings []Binding) (*FileStore, error)

func (*FileStore) GetRequirements

func (s *FileStore) GetRequirements(ctx context.Context, resource authz.Resource, action string) (RequirementsDocument, error)

func (*FileStore) ReplaceRequirements

func (s *FileStore) ReplaceRequirements(ctx context.Context, resource authz.Resource, action, expected string, requirements Requirements) (RequirementsDocument, error)

func (*FileStore) ReplaceRequirementsAs

func (s *FileStore) ReplaceRequirementsAs(ctx context.Context, resource authz.Resource, action, expected string, requirements Requirements, actor string) (RequirementsDocument, error)

type Principal

type Principal struct {
	Facts            authz.Facts `json:"facts"`
	AccountID        string      `json:"accountId"`
	MembershipGroups []string    `json:"membershipGroups,omitempty"`
	IdentityRevision string      `json:"identityRevision"`
}

type PrincipalResolver

type PrincipalResolver interface {
	ResolvePrincipal(context.Context) (Principal, error)
}

type ProviderRequest

type ProviderRequest struct {
	SchemaVersion        int            `json:"schemaVersion"`
	RequestID            string         `json:"requestId"`
	Subject              string         `json:"subject"`
	Issuer               string         `json:"issuer"`
	TenantID             string         `json:"tenantId"`
	AccountID            string         `json:"accountId"`
	ResourceKind         string         `json:"resourceKind"`
	ResourceID           string         `json:"resourceId"`
	ResourceVersion      string         `json:"resourceVersion"`
	Action               string         `json:"action"`
	RequirementsRevision string         `json:"requirementsRevision"`
	RequirementKey       string         `json:"requirementKey"`
	ProviderRef          string         `json:"providerRef,omitempty"`
	EntitySelection      []authz.Entity `json:"entitySelection,omitempty"`
	EntitySelectionHash  string         `json:"entitySelectionHash"`
}

ProviderRequest contains only server-assembled, verified fields.

type Request

type Request struct {
	RequestID string
	Resource  authz.Resource
	Action    string
	Selected  []authz.Entity
}

type Requirements

type Requirements struct {
	SchemaVersion     int                     `json:"schemaVersion"`
	RequiredExposures []string                `json:"requiredExposures,omitempty"`
	AllowedRoles      []string                `json:"allowedRoles,omitempty"`
	Entity            *EntityRequirement      `json:"entity,omitempty"`
	Entitlement       *EntitlementRequirement `json:"entitlement,omitempty"`
}

type RequirementsDocument

type RequirementsDocument struct {
	Revision     string       `json:"revision"`
	Requirements Requirements `json:"requirements"`
}

type RequirementsStore

type RequirementsStore interface {
	GetRequirements(context.Context, authz.Resource, string) (RequirementsDocument, error)
}

type RequirementsWriter

type RequirementsWriter interface {
	ReplaceRequirements(context.Context, authz.Resource, string, string, Requirements) (RequirementsDocument, error)
}

RequirementsWriter stores a new immutable revision only if expectedRevision still names the current document. The host owns persistence and revision allocation; a caller cannot choose a current revision by writing one.

type StaticChoices

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

StaticChoices is a trusted exact resource/action editor catalog. It carries display options only; it never grants the ability to read or edit a gate.

func NewStaticChoices

func NewStaticChoices(bindings []ChoiceBinding) (*StaticChoices, error)

func (*StaticChoices) ResolveChoices

func (s *StaticChoices) ResolveChoices(ctx context.Context, resource authz.Resource, action string) (EditorChoices, error)

type StaticStore

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

func NewStaticStore

func NewStaticStore(bindings []Binding) (*StaticStore, error)

func (*StaticStore) GetRequirements

func (s *StaticStore) GetRequirements(ctx context.Context, resource authz.Resource, action string) (RequirementsDocument, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL