Documentation
¶
Overview ¶
Package semantics implements the CLC-v1 capability language core authorization semantics. It provides deterministic, fail-closed entailment, intersection, and decision functions.
Index ¶
- Constants
- Variables
- func CanonicalJSON(v any) ([]byte, error)
- func CheckConstraint(c string, op Operation) error
- func RevisionCompatible(inputRevision string) bool
- func ValidateCapabilityID(id string) error
- func ValidateConstraint(c string) error
- func ValidateGrantParams(params map[string]any) error
- func ValidateOperationParams(params map[string]any) error
- func ValidateRawParams(raw string) error
- type Decision
- type Grant
- type MatchResult
- type Operation
Constants ¶
const ( VerdictAllow = "allow" VerdictDeny = "deny" VerdictAllowUR = "allow_unresolved" )
const CLCRevision = "CLC-1.3"
CLCRevision is the language revision this implementation declares and evaluates. Compatible reading (§12.1): same major, minor ≤ ours. (rev CLC-1.3 · 2026-09-12: CLC-1.3 is additive — `allow_unresolved` verdict + §9.3 identity/aggregation clarifications — so CLC-1.2/1.1 inputs still read fine.)
Variables ¶
var ( ErrUnsupportedWildcard = errors.New("unsupported_wildcard") ErrInvalidCapabilityID = errors.New("invalid_capability_id") ErrMissingCapabilityID = errors.New("missing_capability_id") ErrInvalidConstraint = errors.New("invalid_constraint") ErrInvalidParamsNull = errors.New("invalid_params_null") ErrParamsMissing = errors.New("params_missing") ErrParamsUndeclared = errors.New("undeclared_param") ErrCapabilityNotAuth = errors.New("capability_not_authorized") ErrUnknownConstraint = errors.New("unknown_constraint") ErrDifferentNamespace = errors.New("different_namespace") ErrLiteralMismatch = errors.New("literal_mismatch") ErrWildcardNoTrailing = errors.New("wildcard_requires_trailing_segment") ErrParamsExceedGrant = errors.New("params_exceed_grant") ErrEmptyBoundDenies = errors.New("empty_bound_denies_class") ErrNotInEnum = errors.New("not_in_enum") ErrNoOverlap = errors.New("no_overlap") ErrAbsentSource = errors.New("absent_source") ErrInvalidParamsDupKey = errors.New("invalid_params_duplicate_key") ErrInvalidParamsNumber = errors.New("invalid_params_number") ErrInvalidParamsSize = errors.New("invalid_params_size") ErrUnsupportedLangRev = errors.New("unsupported_language_revision") )
var ValidateIDRegex = regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9-]*/[a-zA-Z][a-zA-Z0-9-]*-v[0-9]+:[a-zA-Z][a-zA-Z0-9_:.-]*$`)
ValidateIDRegex is used for syntax validation in vectors.
Functions ¶
func CanonicalJSON ¶
CanonicalJSON returns RFC 8785 (JCS) canonical JSON. This is a simplified implementation; production use should use a proper JCS library.
func CheckConstraint ¶
CheckConstraint evaluates a constraint against an operation (§8.1). Rev CLC-1.2: max_rows uses a strict integer and fails closed when the op carries no max_rows value (previously the sloppy %f scan silently skipped both malformed values and missing op params).
func RevisionCompatible ¶
RevisionCompatible reports whether an input declaring the given CLC revision may be evaluated by this implementation (§12.1). A mismatch is resolved before any §9.3 layer and fails closed with unsupported_language_revision — never a silent downgrade.
func ValidateCapabilityID ¶
ValidateCapabilityID checks whether an ID conforms to CLC-v1 §2 grammar. v1 allows: literal segments and trailing * as a complete segment.
func ValidateConstraint ¶
ValidateConstraint checks a constraint against §8.1's identity × value grammar (rev CLC-1.2/1.3): an unrecognized (scheme,type) → unknown_constraint; a recognized type whose value is out of grammar → invalid_constraint.
func ValidateGrantParams ¶
ValidateGrantParams checks for null values in params (CLC-v1 §5.2) and applies the §6.2 step 4 caps to the decoded-object path (§6.2 step 6).
func ValidateOperationParams ¶
ValidateOperationParams checks for null values in operation params and applies the §6.2 step 4 caps to the decoded-object path (§6.2 step 6).
func ValidateRawParams ¶
ValidateRawParams validates the raw JSON text of an operation's params object at the input boundary (§6.2, §9.3 layer 2), before any layer runs. Unlike a decoded map, the raw text preserves duplicate keys, number literals, nesting depth and serialized size — none of which survive a map-based decode (maps drop duplicate keys, and JSON cannot carry non-finite numbers). Rejections follow §6.2 order: size/depth, then duplicate keys, then number shape. Malformed input and a non-object params value fall into invalid_params_number.
Types ¶
type Decision ¶
type Decision struct {
Verdict string `json:"verdict"` // "allow", "deny" or "allow_unresolved" (rev CLC-1.3)
Reason string `json:"reason,omitempty"`
// Unresolved lists recognized-but-unevaluated constraints carried on an
// allow_unresolved verdict (§8.4 residual-obligation channel): non-empty
// means the consumer must evaluate/confirm each constraint before acting,
// else deny (AAC §6.6). Empty on deny and on a fully-evaluated allow.
// Ordered deterministically (sorted, deduped).
Unresolved []string `json:"unresolved,omitempty"`
}
Decision is the output of the authorization function.
func Authorize ¶
Authorize evaluates the decision function per CLC-v1 §8 with a single effective grant (§9.3 single-grant path).
func AuthorizeSet ¶
AuthorizeSet evaluates the §9.3 multi-grant aggregation (rev CLC-1.3):
- grants all absent/empty → deny capability_not_authorized (resolved before any layer check, per §9.3 pre-check);
- otherwise operation layer-1 validation runs first, exactly as the single-grant path;
- each grant with a matching operation ID is a covering grant; its params are checked (paramsSubset) then its constraints (ValidateConstraint → CheckConstraint);
- ANY covering grant whose params+constraints fully allow authorizes the operation (union semantics);
- residual obligations (recognized-but-unevaluated constraints) are unioned across the covering-and-allowing grants → allow_unresolved;
- if no covering grant allows: params/constraint-level denials from covering grants surface as the first covering grant's reason in canonical (input) order; grants that did not cover collapse to capability_not_authorized.
type Grant ¶
type Grant struct {
ID string `json:"id"`
Params map[string]any `json:"params,omitempty"`
Constraints []string `json:"constraints,omitempty"`
}
Grant represents a principal's authorization of a capability.
type MatchResult ¶
MatchResult captures the result of an entailment check.
func Entails ¶
func Entails(grant Grant, op Operation) MatchResult
Entails checks if a grant covers an operation per CLC-v1 §5.
Source Files