stewardauthz

package module
v0.0.0-...-85893cb Latest Latest
Warning

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

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

README ΒΆ

steward-authz 🐹

🧭 Access-rule engine and permission catalog shared by Steward services

The Go module every Steward service imports to make access decisions in-process, plus the Rego policy bundles the services' OPA sidecars load.

  • Category rules: ordered rules per category, inherited down the tree. The first rule with an opinion wins, and anything no rule decides is denied.
  • Permission catalog: the permissions, the roles that grant them, and Authorize for one permission on one document.
  • Rego bundles: per-service method gates in policies/, built into one OPA bundle.

πŸ“¦ Install

go get github.com/Steward-GRC/steward-authz

πŸš€ Use

import authz "github.com/Steward-GRC/steward-authz"

ev := authz.Compile(chain) // the target category first, then its ancestors
res := ev.Resolve(ctx, authz.Subject{UserID: "erin", Groups: []string{"All staff"}})
if res.Read.Allowed { /* ... */ }

d := authz.Authorize(subject, authz.PolicyApprove, &authz.Resource{Category: "Finance"})
if err := d.Err(); err != nil { return err } // coded AUTHZ_DENIED

πŸ“š Docs

πŸ›  Develop

task build       # go build ./...
task test        # go test ./...
task lint        # gofmt check + golangci-lint + yamllint
task license     # check Apache-2.0 headers (golic)
task rego:test   # opa fmt, opa check, opa test, and the bundle build's tests
task rego:bundle # build bundle.tar.gz from policies/ (scripts/build-bundle.sh)

πŸ™ Acknowledgements

Steward was originally written by @Bugs5382.

βš–οΈ License

Apache-2.0 (c) 2026 The Steward Authors

Documentation ΒΆ

Overview ΒΆ

Package stewardauthz is Steward's access engine, evaluated in-process by the services that need an access decision. It has two parts.

The permission catalog (Permission, Role, RolePermissions) names every permission and the roles that grant it. Authorize decides one permission for a Subject on a Resource: the capability gate, then category scope for the scoped permissions (a grant on a category covers every category below it), then, for a read, per-document overrides, break glass and sensitivity.

The category rule engine (CategoryRuleset, Compile, Resolve) decides the four governed actions, read, acknowledge, approve and author, from a category's ordered rules and those of its ancestors. The first rule with an opinion on the action wins, and anything no rule decides is denied. Read gates the other actions. Owners and site admins have the fixed rights listed on Compile.

Both parts run on github.com/Bugs5382/go-authz, and the errors the package returns carry go-apperr codes (see Entries). The package does no I/O.

Index ΒΆ

Examples ΒΆ

Constants ΒΆ

View Source
const (
	CodeDenied            = 9001
	CodeInvalidRule       = 9002
	CodeUnknownPermission = 9003
	CodeUnknownRole       = 9004
)

The codes this library attaches to the errors it returns.

View Source
const CodeBand = 9

CodeBand is the leading digit of every code this library emits, so its codes stay apart from the services' own bands.

Variables ΒΆ

View Source
var (
	ErrDenied            = errors.New("authz: access denied")
	ErrInvalidRule       = errors.New("authz: invalid access rule")
	ErrUnknownPermission = errors.New("authz: unknown permission")
	ErrUnknownRole       = errors.New("authz: unknown role")
)

Sentinel errors, matched with errors.Is. Each one reaches a caller wrapped in its code (see Entries).

Functions ΒΆ

func Entries ΒΆ

func Entries() []apperr.Entry

Entries returns the go-apperr entries for this library's codes. A service adds them to the registry it builds at startup, so a coded error from here presents with the right category, symbol and user-safe message.

func HasCapability ΒΆ

func HasCapability(s Subject, p Permission) bool

HasCapability reports whether the subject could be allowed p in at least one scope: through a role, the individual read-sensitive grant, or, for a scoped permission, any scoped grant whose role confers it. It is the coarse check for work that spans categories; Authorize makes the per-resource decision.

Types ΒΆ

type Action ΒΆ

type Action string

Action is one of the four governed actions on a category's documents.

const (
	ActionRead        Action = "read"
	ActionAcknowledge Action = "acknowledge"
	ActionApprove     Action = "approve"
	ActionAuthor      Action = "author"
)

The actions. Read gates the other three.

func Actions ΒΆ

func Actions() []Action

Actions returns the four actions, in display order.

type CategoryRuleset ΒΆ

type CategoryRuleset struct {
	Name string
	// Owners are user IDs. An owner reads, approves and authors in this
	// category and every category below it, ahead of any rule.
	Owners []string
	Rules  []Rule
}

CategoryRuleset is one category's owners and its ordered rules.

func (CategoryRuleset) Validate ΒΆ

func (c CategoryRuleset) Validate() error

Validate checks a ruleset read from outside (storage, the admin editor). The error is coded CodeInvalidRule, matches ErrInvalidRule, and carries the category, the 1-based rule number and the problem as wire metadata.

type Decision ΒΆ

type Decision struct {
	Effect Effect
	Reason Reason
}

Decision is the outcome of Authorize.

func Authorize ΒΆ

func Authorize(s Subject, p Permission, r *Resource) Decision

Authorize decides p for the subject on r. r is nil for an action that is not aimed at one resource. A sensitive document is read only by its assigned authors and approvers and by explicit grants (the individual read-sensitive grant, an override allow, break glass); no role reads it.

Example ΒΆ
package main

import (
	"fmt"

	authz "github.com/Steward-GRC/steward-authz"
)

func main() {
	bob := authz.Subject{
		UserID:       "bob",
		Roles:        []authz.Role{authz.RoleAuthor},
		ScopedGrants: []authz.ScopedGrant{{Role: authz.RoleAuthor, Category: "Workplace"}},
	}
	doc := &authz.Resource{ID: "POL-FACILITIES-000001", Category: "Facilities", CategoryLineage: []string{"Facilities", "Workplace"}}
	fmt.Println(authz.Authorize(bob, authz.PolicySubmit, doc).Effect)
	fmt.Println(authz.Authorize(bob, authz.PolicyApprove, doc).Reason)
}
Output:
allow
missing_capability

func (Decision) Allowed ΒΆ

func (d Decision) Allowed() bool

Allowed reports whether the decision is a plain allow.

func (Decision) Err ΒΆ

func (d Decision) Err() error

Err returns nil for an allow, and otherwise an error coded CodeDenied that matches ErrDenied. The reason stays in the internal cause and is never sent to the client.

type Effect ΒΆ

type Effect string

Effect is the outcome of Authorize.

const (
	EffectDeny      Effect = "deny"
	EffectAllow     Effect = "allow"
	EffectObfuscate Effect = "obfuscate"
)

The effects. Obfuscate means the subject may see that the resource exists, but not its content.

type Evaluator ΒΆ

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

Evaluator is a compiled category chain. It is read-only once built and safe to share between goroutines.

func Compile ΒΆ

func Compile(chain []CategoryRuleset, opts ...Option) *Evaluator

Compile builds an Evaluator for chain: the target category first, then its ancestors up to the root. For each action the order is: site admin and root read; owners anywhere in the chain read, approve and author; then every rule top-down, target category first. The first rule with a non-blank cell for the action decides, and anything left is denied.

Compile is also the access simulator: pass a draft chain to preview unsaved rules.

Example ΒΆ
package main

import (
	"context"
	"fmt"

	authz "github.com/Steward-GRC/steward-authz"
)

func main() {
	chain := []authz.CategoryRuleset{
		{Name: "Facilities", Rules: []authz.Rule{
			{Subject: authz.RuleSubject{Kind: authz.SubjectGroup, Name: "Facilities team"},
				Grants: map[authz.Action]authz.Grant{authz.ActionAuthor: authz.GrantAllow}},
		}},
		{Name: "Workplace", Owners: []string{"dave"}, Rules: []authz.Rule{
			{Subject: authz.RuleSubject{Kind: authz.SubjectEveryone},
				Grants: map[authz.Action]authz.Grant{authz.ActionRead: authz.GrantAllow, authz.ActionAcknowledge: authz.GrantAllow}},
		}},
	}
	ev := authz.Compile(chain)
	erin := authz.Subject{UserID: "erin", Groups: []string{"All staff"}}
	r := ev.Resolve(context.Background(), erin)
	fmt.Println(r.Read.Allowed, r.Read)
	fmt.Println(r.Acknowledge.Allowed, r.Author)
}
Output:
true ↳ Workplace #1 allow everyone
true no rule β†’ default deny

func (*Evaluator) Acknowledgement ΒΆ

func (e *Evaluator) Acknowledgement(ctx context.Context, s Subject) RuleDecision

Acknowledgement is the acknowledge decision without the read gate, for a caller that settles read some other way, such as a per-document override. Owners, site admins and root are never asked to acknowledge automatically.

func (*Evaluator) Resolve ΒΆ

func (e *Evaluator) Resolve(ctx context.Context, s Subject) Result

Resolve decides all four actions. Read gates the others, and an allowed author or approve confers read: no one authors or approves what they can't read. Acknowledge confers nothing.

type Grant ΒΆ

type Grant string

Grant is the three-state value of one action cell in a rule.

const (
	GrantBlank Grant = ""
	GrantAllow Grant = "allow"
	GrantDeny  Grant = "deny"
)

The grants. A blank cell has no opinion, so evaluation falls through to the next rule.

type Option ΒΆ

type Option func(*options)

Option configures Compile.

func WithLogger ΒΆ

func WithLogger(l *slog.Logger) Option

WithLogger logs every decision at debug level through l.

type Override ΒΆ

type Override struct {
	ResourceID string
	Grant      Grant
}

Override pins one resource for one subject: GrantAllow always shows it, GrantDeny excludes it.

type Permission ΒΆ

type Permission string

Permission is one entry of the catalog, written "<resource>.<verb>".

const (
	PolicyRead          Permission = "policy.read"
	PolicyReadSensitive Permission = "policy.read_sensitive"
	PolicyAuthor        Permission = "policy.author"
	PolicySubmit        Permission = "policy.submit"
	PolicyApprove       Permission = "policy.approve"
	TemplateManage      Permission = "template.manage"
	WorkflowManage      Permission = "workflow.manage"
	GroupManage         Permission = "group.manage"
	UserManage          Permission = "user.manage"
	RoleManage          Permission = "role.manage"
	AuditRead           Permission = "audit.read"
	ComplianceManage    Permission = "compliance.manage"
	ComplianceReport    Permission = "compliance.report"
	SettingsManage      Permission = "settings.manage"
	DeliveryManage      Permission = "delivery.manage"
	SessionManage       Permission = "session.manage"
)

The permission catalog.

func ParsePermission ΒΆ

func ParsePermission(s string) (Permission, error)

ParsePermission checks a permission name read from outside (storage, a token, an admin form) against the catalog.

func Permissions ΒΆ

func Permissions() []Permission

Permissions returns the whole catalog, in a stable order.

func RolePermissions ΒΆ

func RolePermissions(rs ...Role) []Permission

RolePermissions returns the catalog permissions the given roles grant together, in catalog order. The reader baseline is always included, and an unknown role adds nothing.

func (Permission) Resource ΒΆ

func (p Permission) Resource() string

Resource is the part before the first dot ("policy" in "policy.read").

func (Permission) Scoped ΒΆ

func (p Permission) Scoped() bool

Scoped reports whether the permission only takes effect inside the categories a subject holds a scoped grant for.

func (Permission) Verb ΒΆ

func (p Permission) Verb() string

Verb is the part after the first dot ("read" in "policy.read").

type Reason ΒΆ

type Reason string

Reason is a stable, machine-readable code for why a decision came out as it did, for decision logs and the access simulator.

const (
	ReasonGranted           Reason = "granted"
	ReasonMissingCapability Reason = "missing_capability"
	ReasonOutOfScope        Reason = "out_of_category_scope"
	ReasonOverrideAllow     Reason = "override_allow"
	ReasonBreakGlass        Reason = "break_glass"
	ReasonExcluded          Reason = "excluded"
	ReasonSensitive         Reason = "sensitive"
	ReasonAssigned          Reason = "assigned"
)

The reasons Authorize returns.

const (
	ReasonSiteAdminRead       Reason = "site_admin_read"
	ReasonOwner               Reason = "owner"
	ReasonRuleAllow           Reason = "rule_allow"
	ReasonRuleDeny            Reason = "rule_deny"
	ReasonDefaultDeny         Reason = "default_deny"
	ReasonAuthorImpliesRead   Reason = "author_implies_read"
	ReasonApproverImpliesRead Reason = "approver_implies_read"
	ReasonRequiresRead        Reason = "requires_read"
)

The reasons the rule engine returns.

type Resource ΒΆ

type Resource struct {
	ID       string
	Category string
	// CategoryLineage is the category names from this resource's category up
	// to the root. When it is empty, Category alone is used.
	CategoryLineage []string
	Sensitive       bool
	// Authors and Approvers are the user IDs assigned to this document. On a
	// sensitive document they are the only subjects, besides explicit grants,
	// who may read it.
	Authors   []string
	Approvers []string
}

Resource is what an action is aimed at.

type Result ΒΆ

type Result struct {
	Read        RuleDecision
	Acknowledge RuleDecision
	Approve     RuleDecision
	Author      RuleDecision
}

Result is the decision for each of the four actions.

func Resolve ΒΆ

func Resolve(ctx context.Context, s Subject, chain []CategoryRuleset) Result

Resolve compiles chain and resolves it for s. Compile once and reuse the Evaluator when deciding for many subjects.

func (Result) Get ΒΆ

func (r Result) Get(a Action) RuleDecision

Get returns the decision for one action.

type Role ΒΆ

type Role string

Role is a named bundle of permissions.

const (
	RoleReader          Role = "reader"
	RoleAuthor          Role = "author"
	RoleApprover        Role = "approver"
	RoleTemplateAdmin   Role = "template-admin"
	RoleComplianceAdmin Role = "compliance-admin"
	RoleSiteAdmin       Role = "site-admin"
)

The roles. Every signed-in subject is a reader implicitly; the role is never stored.

func ParseRole ΒΆ

func ParseRole(s string) (Role, error)

ParseRole checks a role name read from outside against the catalog.

func Roles ΒΆ

func Roles() []Role

Roles returns every role, in a stable order.

type Rule ΒΆ

type Rule struct {
	Subject RuleSubject
	Grants  map[Action]Grant
}

Rule is one ordered row of a category's rule list: a subject with a grant per action. A missing action means GrantBlank.

type RuleDecision ΒΆ

type RuleDecision struct {
	Allowed bool
	Reason  Reason
	Rule    *RuleRef
}

RuleDecision is the outcome for one action. Rule is set when a rule decided, and nil for the built-in outcomes.

func Acknowledgement ΒΆ

func Acknowledgement(ctx context.Context, s Subject, chain []CategoryRuleset) RuleDecision

Acknowledgement compiles chain and returns the ungated acknowledge decision.

func (RuleDecision) String ΒΆ

func (d RuleDecision) String() string

String explains the decision in the words the access simulator shows.

type RuleRef ΒΆ

type RuleRef struct {
	Category string
	Depth    int
	Index    int
	Subject  RuleSubject
}

RuleRef points at the rule that decided: Depth 0 is the target category, 1 its parent, and so on; Index is 0-based within that category.

type RuleSubject ΒΆ

type RuleSubject struct {
	Kind SubjectKind
	Name string
}

RuleSubject is who a rule targets. Name is a group name or a user ID, and empty for SubjectEveryone.

type ScopedGrant ΒΆ

type ScopedGrant struct {
	Role     Role
	Category string
}

ScopedGrant gives a role inside one category and, through the category lineage, every category below it.

type Subject ΒΆ

type Subject struct {
	UserID string
	Roles  []Role
	// Groups are directory group names; rule subjects match them ignoring case.
	Groups        []string
	ScopedGrants  []ScopedGrant
	Overrides     []Override
	ReadSensitive bool
	Root          bool
	// BreakGlass holds the resource IDs the subject has an active break-glass
	// grant for.
	BreakGlass map[string]bool
}

Subject is the signed-in person a decision is made for.

func (Subject) SiteAdmin ΒΆ

func (s Subject) SiteAdmin() bool

SiteAdmin reports whether the subject holds the site-admin role.

type SubjectKind ΒΆ

type SubjectKind string

SubjectKind says what a rule targets.

const (
	SubjectEveryone SubjectKind = "everyone"
	SubjectGroup    SubjectKind = "group"
	SubjectUser     SubjectKind = "user"
)

The subject kinds.

Jump to

Keyboard shortcuts

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