authz

type AttrKind ¶

type AttrKind uint8

AttrKind names the type an AttrValue carries. The kind is part of the attribute's identity, not a hint: a rule comparing strings and an attribute holding an integer do not compare — they MISMATCH, and the SDK says so rather than quietly answering false (see AttributeKindMismatch).

const (
	// KindInvalid is the zero AttrKind — FIRST in the iota run for exactly
	// that reason. It belongs to the zero [AttrValue] and to nothing else:
	// [NewRequestValue] drops an attribute carrying it, so a kind-less
	// attribute is ABSENT rather than present and unusable.
	KindInvalid AttrKind = iota
	// KindString is a single text value — a department, a tenant, a region.
	KindString
	// KindInt64 is a whole number — an age, a level, a Unix timestamp.
	KindInt64
	// KindBool is a flag — mfa_satisfied, account_locked, is_internal.
	KindBool
	// KindStrings is an unordered set of text values — the roles a subject
	// holds, the groups it belongs to, the scopes a token carries.
	KindStrings
)

type AttrValue ¶

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

AttrValue is one typed, named fact the caller attaches to a RequestValue: the subject's department, whether MFA was satisfied, the owner recorded on the resource. It is immutable once built, and its accessors report the kind mismatch rather than a zero value.

Why it is typed ¶

The obvious shape for an attribute bag is map[string]string, and it has two defects that this domain cannot afford. It cannot express a flag that is present and FALSE — "mfa_satisfied=false" and "mfa_satisfied absent" become the same empty string — and it makes every numeric comparison a string comparison, in which "9" is greater than "10". Both failures resolve toward permission often enough to be worth four kinds and an explicit accessor.

func AttrBool(key string, value bool) AttrValue

func AttrInt64(key string, value int64) AttrValue

func AttrString(key, value string) AttrValue

func AttrStrings(key string, values ...string) AttrValue

func (a AttrValue) BoolValue() (value, ok bool)

func (a AttrValue) Contains(want string) (found, ok bool)

func (a AttrValue) Int64Value() (value int64, ok bool)

func (a AttrValue) Key() string

func (a AttrValue) Kind() AttrKind

func (a AttrValue) StringValue() (value string, ok bool)

func (a AttrValue) StringsValue() (values []string, ok bool)

type Condition ¶

type Condition func(request RequestValue) (bool, error)

Condition reports whether an attribute rule holds for request. It is the unit an ABAC rule is written in, and it is an ordinary Go predicate rather than a sentence in a policy language: the caller already has a language, and a second one would have to grow comparison, negation, arithmetic and short circuits before it could express what an `if` expresses today.

Implementations MUST be pure and safe for concurrent use, and MUST NOT perform I/O — a Condition is evaluated on the request path, possibly several times per request, with no context to cancel it. A rule that needs a lookup is a Policy, which has one.

false and "cannot tell" are different answers ¶

Returning (false, nil) means the condition was evaluated and does not hold; the rule carrying it declines to fire, and the decision is left to the other policies. Returning a non-nil error means the condition could NOT be evaluated — most often because the request does not carry the attribute the rule names (AttributeMissing), or carries it as another kind (AttributeKindMismatch).

Those two MUST NOT be collapsed. An absent attribute compared to a wanted value is not a comparison that failed: it is a comparison that never happened, and reporting it as false would let a request carrying no attributes at all slip past every "deny if X" rule in the system. The built-in conditions in internal/service/security/authz report absence as an error, and every combinator over them treats an unevaluable branch as absorbing.

type Decision ¶

type Decision uint8

Decision is what a Policy answers: it permits, it refuses, or it has no opinion. Three states, not two.

Why the third state exists ¶

Most policies only know about part of the system. A policy that grants "orders:write" to a role has nothing to say about a request to read a profile — and it must be able to SAY that. Folding "no opinion" into either of the other two breaks something:

• Folded into Allow, a policy authorizes every request it does not recognise. That is the hole.
• Folded into Deny, a policy vetoes every request the OTHER policies were meant to grant, because refusal is absorbing (see ADR 0057 §D2). That is the outage, and the usual repair for it is to make the combiner permissive — which reintroduces the hole one layer up.

Abstain costs one enum value and removes both.

The zero value ¶

The zero Decision is Abstain, never Allow. A Policy that forgets to set its result therefore says "I have no opinion", and the request is refused by the closure in internal/service/security/authz.Check — not permitted (which would be a vulnerability) and not made to veto every other policy (which would be an outage from a forgotten assignment). This is ADR 0031 applied to a FUNC port: a func type has no constructor to refuse in, so the safe value has to be the zero one.

A Decision outside the three named constants is a defect in whoever produced it. The SDK treats it as Deny and reports PolicyMisconfigured; it is never treated as permission. Use Decision.Valid to check, and Decision.Granted — never `!= Deny` — to read a verdict.

const (
	// Abstain means this policy has no opinion about this request. It is the
	// zero value — FIRST in the iota run for exactly that reason — and it
	// grants nothing: composition preserves it, and the closure refuses it.
	Abstain Decision = iota
	// Allow means this policy permits the request. It is the ONLY value that
	// grants, and under deny-overrides it can still be defeated by a [Deny]
	// from any other policy in the composition.
	Allow
	// Deny means this policy refuses the request. It is absorbing: no [Allow]
	// anywhere in a composition can outvote it (ADR 0057 §D2).
	Deny
)

func (d Decision) Granted() bool

func (d Decision) String() string

func (d Decision) Valid() bool

type Policy ¶

type Policy func(ctx context.Context, request RequestValue) (Decision, error)

Policy answers whether request is permitted. Implementations MUST be pure with respect to the decision — the same request yields the same decision — and safe for concurrent use, because one compiled Policy is shared by every goroutine serving a request.

A Policy returns Abstain when it has nothing to say about this request. That is the common case for a policy that only knows about one action or one resource, and it is NOT a refusal: refusing is Deny, and a policy that conflates the two silently vetoes every policy it is composed with.

A returned error is never an authorization ¶

The error return means "this policy could not be evaluated" — a required attribute was absent, an attribute was not the kind the rule compares, a backing store was unreachable. A caller MUST treat that as a refusal. The SDK's own combiner and closure do exactly that: an error is folded to Deny and the decision returned alongside it is ignored. A Policy that cannot decide has not permitted anything.

Implementations SHOULD return Deny alongside a non-nil error rather than the zero Abstain, so that a caller who reads only the decision — a mistake this contract cannot prevent — still fails closed.

type RequestValue ¶

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

RequestValue is the question: may Subject perform Action on Resource, given these attributes. It is immutable once built, so one request value can be handed to every policy in a composition without any of them being able to edit what the next one sees.

The three strings are the caller's vocabulary ¶

The SDK attaches no meaning to them. "orders" and "urn:acme:orders" are equally valid resources, "write" and "POST" equally valid actions; nothing here parses, splits or pattern-matches them, and there is no wildcard — matching is byte equality, so a resource literally named "*" is a resource named "*" and nothing more. A hierarchy, if the application has one, is expressed by the strings it chooses and the rules it writes.

Resource is the type, not the row ¶

A grant table answers about a KIND of thing — "an editor may publish an article" — and an instance rule answers about one of them — "…if they wrote it". Put the type in Resource and the instance's facts in the attributes (owner, tenant, classification), then let RBAC answer the first question and an ABAC condition answer the second. That split is why this domain ships no wildcard and needs none; see ADR 0057 §D5.

func NewRequestValue(subject, action, resource string, attrs ...AttrValue) RequestValue

func (r RequestValue) Action() string

func (r RequestValue) Attr(key string) (attr AttrValue, ok bool)

func (r RequestValue) AttrCount() int

func (r RequestValue) Resource() string

func (r RequestValue) Subject() string