Module groups

Expand description

Static group-to-capability configuration (issue #670).

A GroupConfig names a small set of built-in groups (BUILTIN_ADMIN, BUILTIN_AGENT, BUILTIN_RESTRICTED) and optionally merges operator-defined custom groups from $ASTRID_HOME/etc/groups.toml. Each group confers a set of capability patterns, evaluated left-to-right against the colon-delimited grammar in crate::capability_grammar.

§Design contract

Built-in groups are baked in. Attempting to redefine them in groups.toml is a hard error at load time.
Custom groups go through validate_capability for every entry.
The universal * pattern is reserved for the built-in admin group. Custom groups may grant it only by explicitly opting in via unsafe_admin = true on that group; otherwise it’s rejected at load.
Missing groups.toml → built-ins only (the single-tenant default).
Malformed TOML, unknown fields, or duplicate group names are hard errors — this fails the kernel boot, which is intentional.
GroupConfig::get returning None for a name referenced by a principal profile is not an error here; the caller (CapabilityCheck) treats it as fail-closed and logs a warn!.

Group: A named set of capability patterns.
GroupConfig: The frozen group-to-capability map consumed by CapabilityCheck.

BUILTIN_ADMIN: Canonical name of the built-in administrator group.
BUILTIN_AGENT: Canonical name of the built-in agent group (self-scoped capabilities).
BUILTIN_RESTRICTED: Canonical name of the built-in restricted group (no capabilities).