authz

type AuthZen ¶

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

AuthZen is a PDP that delegates decisions to a remote AuthZen Authorization API. It supplies facts only (the PEP and handlers build the tuple) and holds no policy logic. It is safe for concurrent use (the underlying http.Client is).

func NewAuthZen(endpoint string, logger *zap.SugaredLogger) (*AuthZen, error)

func (a *AuthZen) Evaluate(ctx context.Context, s Subject, action string, r Resource, reqCtx map[string]any) (Decision, error)

func (a *AuthZen) Evaluations(ctx context.Context, reqs []EvalRequest) ([]Decision, error)

func (a *AuthZen) Health(ctx context.Context) error

type Builtin ¶

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

Builtin is the default, in-process PDP. It reproduces CCF's pre-authz access rules with zero behavior change: admin resources require SSO admin-group membership (password users are treated as super admins), and every other resource is allowed once the request is authenticated — the authn middleware having already enforced authentication and any public-endpoint policy before the PEP runs.

In Phase 1 the builtin driver resolves SSO facts itself (it holds db + config), acting as its own PIP, so behavior matches the prior admin-group middleware exactly. The "PEP supplies all facts" model the design describes is for the remote drivers and the manifest attribute surface designed in BCH-1319. Because it runs in-process it never returns ErrUnavailable, so the configured fail mode never changes its behavior.

func NewBuiltin(db *gorm.DB, cfg *config.Config, logger *zap.SugaredLogger) *Builtin

func (b *Builtin) Evaluate(ctx context.Context, s Subject, _ string, r Resource, _ map[string]any) (Decision, error)

func (b *Builtin) Evaluations(ctx context.Context, reqs []EvalRequest) ([]Decision, error)

type Cedar ¶

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

Cedar is the embedded Cedar PDP. It evaluates the bundled role policies (compiled from the manifest) plus any operator .cedar files against an in-process entity store it builds per request from the subject's resolved roles. The policy set is read-only after construction and each Evaluate builds its own entity store, so it is safe for concurrent use. Roles come from a RoleResolver: the DB-backed resolver (the persisted ccf_role_assignments source of truth, BCH-1333) reads CCF's database, so unlike Phase 1 the engine can now return an error when the role source is unreachable — the PEP's fail mode decides what that means.

func NewCedar(policies *cedar.PolicySet, roles RoleResolver, logger *zap.SugaredLogger) *Cedar

func (c *Cedar) Evaluate(ctx context.Context, s Subject, action string, r Resource, _ map[string]any) (Decision, error)

func (c *Cedar) Evaluations(ctx context.Context, reqs []EvalRequest) ([]Decision, error)

type ContextAttr ¶

type ContextAttr struct {
	Type         string `yaml:"type" json:"type"`
	Relationship string `yaml:"relationship,omitempty" json:"relationship,omitempty"`
	Status       string `yaml:"status,omitempty" json:"status,omitempty"`
	Note         string `yaml:"note,omitempty" json:"note,omitempty"`
}

ContextAttr declares a relationship attribute exposed in the evaluation tuple's context rather than as a static subject or resource prop. These are (subject × resource) relationship attributes (e.g. oscal_roles, assigned_to) the PEP cannot read from a single row; a PIP resolves them lazily when a policy references them (BCH-1319 §7.1, §8). They are declared in the public contract now but reserved — no resolver or policy consumes them yet — so they are kept out of the static Attributes map until then.

type Decision ¶

type Decision struct {
	Allow  bool
	Reason string
}

Decision is the PDP's verdict. Reason is for logging only and is never echoed to clients (see the PEP).

type Deps ¶

type Deps struct {
	DB     *gorm.DB
	Config *config.Config
	Logger *zap.SugaredLogger
}

Deps are the runtime dependencies handed to a driver factory. The builtin driver uses all three; remote drivers (later phases) may ignore the DB.

type EvalRequest ¶

type EvalRequest struct {
	Subject  Subject
	Action   string
	Resource Resource
	Context  map[string]any
}

EvalRequest is one entry in a batch evaluation (AuthZen "evaluations"), used for list filtering and UI permission hints.

type ExportFormat ¶

type ExportFormat string

ExportFormat is a target the manifest vocabulary can be rendered into for GitOps pipelines and engines without an admin API (parent design §3.4). All formats export the VOCABULARY (subjects, resources, actions, attributes, roles) — not operator policies.

const (
	// ExportJSON renders the manifest as indented JSON.
	ExportJSON ExportFormat = "json"
	// ExportYAML renders the manifest as YAML (a normalized round-trip of the source).
	ExportYAML ExportFormat = "yaml"
	// ExportCedar renders a Cedar schema (entity + action shapes) for the embedded/external
	// Cedar engines. uuid maps to String and map<string,string> to Set<String>, since Cedar
	// has no native equivalents.
	ExportCedar ExportFormat = "cedar"
	// ExportOpenFGA renders an OpenFGA authorization model (a type per resource with a
	// relation per action, directly assignable to the subject types).
	ExportOpenFGA ExportFormat = "openfga"
)

func ParseExportFormat(s string) (ExportFormat, error)

type Factory ¶

type Factory func(opts Options, deps Deps) (PDP, error)

Factory constructs a PDP for a registered driver.

type FailMode ¶

type FailMode string

FailMode controls what the PEP does when the PDP is unavailable.

const (
	// FailClosed denies the request on PDP error/timeout. This is the default.
	FailClosed FailMode = "closed"
	// FailOpen allows the request on PDP error/timeout.
	FailOpen FailMode = "open"
)

func ParseFailMode(s string) FailMode

type GroupResolver ¶

type GroupResolver interface {
	// ResolveGroups returns the native CCF group names the subject belongs to. SSO IdP groups are
	// NOT read here: they enter authz only once the login sync has materialized them as native
	// memberships through an SSOGroupMapping (BCH-1331). Non-user subjects resolve to no groups.
	ResolveGroups(ctx context.Context, s Subject) ([]string, error)
}

GroupResolver is the in-process Policy Information Point (PIP) for the subject.groups attribute. It is OSS and reads CCF's database directly — an external PDP cannot, so it only ever receives already-resolved values (BCH-1319 §8, §11.5). Implementations must be safe for concurrent use.

func NewDBGroupResolver(db *gorm.DB, logger *zap.SugaredLogger) GroupResolver

type Healther ¶

type Healther interface {
	Health(ctx context.Context) error
}

Healther is an optional capability a PDP may implement to report whether its decision engine is reachable. The readiness check surfaces it; in-process drivers that cannot fail (builtin) simply don't implement it and are treated as healthy.

type Manifest ¶

type Manifest struct {
	SchemaVersion int                            `yaml:"schemaVersion" json:"schemaVersion"`
	Subjects      map[string]SubjectDef          `yaml:"subjects" json:"subjects,omitempty"`
	Resources     map[string]ResourceDef         `yaml:"resources" json:"resources"`
	Roles         map[string]map[string][]string `yaml:"roles" json:"roles,omitempty"`
}

Manifest is CCF's engine-neutral authorization vocabulary: the subjects, resources, actions and suggested default roles that operator policies are written against. It is treated as a public contract — renaming an action or removing an attribute is a breaking change for every customer policy set.

func DefaultManifest() (*Manifest, error)

func LoadManifest(path string) (*Manifest, error)

func ParseManifest(data []byte) (*Manifest, error)

func (m *Manifest) Export(format ExportFormat) ([]byte, error)

func (m *Manifest) HasAction(resource, action string) bool

type Options ¶

type Options struct {
	Driver   string
	Endpoint string
	CacheTTL time.Duration
}

Options selects and configures the driver to open. Endpoint is the remote PDP URL used by HTTP drivers (authzen); CacheTTL, when > 0, wraps the constructed PDP in a short-TTL decision cache to absorb the network hop. Both are ignored by the in-process builtin.

type PDP ¶

type PDP interface {
	// Evaluate returns the decision for a single (subject, action, resource) tuple.
	Evaluate(ctx context.Context, s Subject, action string, r Resource, reqCtx map[string]any) (Decision, error)
	// Evaluations returns decisions for a batch of requests, in the same order.
	Evaluations(ctx context.Context, reqs []EvalRequest) ([]Decision, error)
}

PDP is the pluggable decision engine. Implementations must be safe for concurrent use.

func Open(opts Options, deps Deps) (PDP, error)

type Resource ¶

type Resource struct {
	Type  string
	ID    string
	Props map[string]any
}

Resource is the thing being acted upon.

type ResourceDef ¶

type ResourceDef struct {
	Actions    []string               `yaml:"actions" json:"actions"`
	Attributes map[string]string      `yaml:"attributes,omitempty" json:"attributes,omitempty"`
	Context    map[string]ContextAttr `yaml:"context,omitempty" json:"context,omitempty"`
}

ResourceDef declares a resource's actions and the attributes it exports. Attributes are the C0/C1/C2 static props the PEP supplies directly (a request param or one resource-row load); Context holds relationship attributes that don't fit a static prop and are resolved lazily by a PIP (BCH-1319 §7.1, §8).

type RoleAssignments ¶

type RoleAssignments struct {
	Users     map[string]string `yaml:"users"`
	Groups    map[string]string `yaml:"groups"`
	Agents    string            `yaml:"agents"`
	Anonymous string            `yaml:"anonymous"`
}

RoleAssignments is the OSS static role-assignment configuration (BCH-1319 §11.3): a GitOps-friendly mapping of principals to one of the bundled roles, with no UI and no DB. A subject's effective roles are the union of its direct user grant and a grant for each group it belongs to (plus the agent default for agent subjects), so a subject can hold several roles even though each principal/group maps to a single role.

• Users — by user: `alice@example.com → auditor`. Keyed by the subject's email (subject.id), matched case-insensitively. Works for every user today.
• Groups — by group: `sec-team → admin`. Keyed by group name. Live only once the subject carries a groups attribute (native CCF groups ∪ SSO groups), which is BCH-1328's surface; until then this map is inert (no subject has groups), exactly the documented "group-based assignment requires BCH-1328" dependency. Structurally ready so it goes live additively when BCH-1328 lands — no change here.
• Agents — the role granted to authenticated agents (default DefaultAgentRole).
• Anonymous — the role granted to unauthenticated requests (no default; empty = deny). Use with care: `anonymous: viewer` makes all read routes open without a login. This is an explicit opt-in; omitting the field keeps the deny-by-default behaviour.

func LoadRoleAssignments(path string) (*RoleAssignments, error)

func (ra *RoleAssignments) RolesFor(_ context.Context, s Subject) ([]string, error)

type RoleResolver ¶

type RoleResolver interface {
	// RolesFor returns the subject's effective roles: the union of its direct grant and a grant
	// for each group it belongs to (plus the agent/anonymous defaults for non-user subjects).
	// The result is sorted and de-duplicated; an empty result is deny-by-default. An error means
	// the source could not be read — the caller (PDP) surfaces it so the PEP fail mode decides.
	RolesFor(ctx context.Context, s Subject) ([]string, error)
}

RoleResolver resolves a subject to its effective manifest roles. It is the engine-neutral seam the PDP reads roles through, so the source can be the persisted ccf_role_assignments table (the BCH-1333 source of truth) without the engine knowing. Implementations must be safe for concurrent use.

func NewDBRoleResolver(db *gorm.DB, defaults *RoleAssignments, ttl time.Duration, logger *zap.SugaredLogger) RoleResolver

type Subject ¶

type Subject struct {
	Type  string
	ID    string
	Props map[string]any
}

Subject is the actor a decision is made about — an authenticated user or agent (or an anonymous subject on public-allowed routes). Props carries provisional, minimal attributes in Phase 1; the authoritative per-resource attribute surface is designed separately in BCH-1319 and must not be grown ad hoc here.

type SubjectDef ¶

type SubjectDef struct {
	Attributes map[string]string `yaml:"attributes" json:"attributes,omitempty"`
}

SubjectDef declares the attributes a subject type exports into the evaluation tuple.