IAM: what exists and what the authoring tools add

This page records how IAM policies work today and what the policy builder, simulator and analyzer layer on top. The evaluator itself is unchanged.

What exists

• A policy is a JSON document of statements: Effect (Allow or Deny), Action (ability strings or *), Resource (identifiers or *). Policies live in iam_policies; attachments link a policy to a user or token principal in iam_policy_attachments.
• Abilities are a flat list on every user and token: read, read:sensitive, write, write:sensitive, deploy, root. root implies all of them.
• Resources are app:NAME, database:NAME, environment:ID and environment-kind:KIND. A trailing * is a prefix match. An app or database also carries the environment resources of the environment it is tagged with.
• Evaluation (authorizeResource in internal/api/iam.go): an explicit Deny in any attached policy always wins; otherwise the principal's flat abilities decide; otherwise an explicit Allow can grant the ability on that resource. A malformed stored document is inert. A principal with no policies behaves exactly like its flat abilities.
• Route gates that name a resource (requireAbilityForResource) call the evaluator. Routes gated by requireAbility consult flat abilities only.
• Every route above read is audit logged by the shared gate, which covers policy create, update, delete, attach and detach.
• Statements carry no conditions today. Environment kind is the one condition-like check, and it is expressed as a resource.

What the authoring tools add

• A catalog of abilities (group, plain description, risk) and a resource picker with live match counts, both read only.
• A simulator that runs the real authorizeResource path (including environment visibility) and lists every statement that matched, plus a grouped effective permissions view.
• An analyzer: static checks over stored documents, attachments and principals, each with a severity and a one line fix.
• Preview before change (attach, detach, update) as a before and after effective permission diff, a version history for policy documents, and a guard that refuses a change that would leave no operational root principal.
• Parameterized templates and field level validation errors.

Guarantees and limits

• No evaluation result changes. internal/api/iam_evaluator_pin_test.go pins the existing behavior; the simulator is tested to agree with authorizeResource on every case.
• Source IP, time window and MFA conditions are not supported by the evaluator, so the builder does not offer them. A Condition key written by hand is ignored by the evaluator and the analyzer flags it.
• There is no project or tag resource in the evaluator. The builder expands a project into its environments when a policy is saved.
• Usage data is per token (last_used_at), not per policy, so previews state that and do not claim a policy was used.