Permissions

A permission is an action your code checks. It is always written resource:action, such as loan:approve. A name without a :, such as approve, is rejected. See the naming rules.

wardn.yaml

permissions:
  customer:view:    View customer profiles
  customer:edit:    Edit customer details
  loan:create:      Create loan applications
  loan:approve:     Approve loans
  loan:approve:own: Approve a loan you created
  report:export:    Export reports

Together these form the catalog: every permission your code can check.

Permissions are code

Developers declare permissions, because the code checks them. Administrators can combine permissions into roles, but they can never invent one. A permission nobody checks would do nothing, and one that’s misspelled would silently do nothing.

Every permission needs a description. Admin screens show it (“Approve loans”) to people choosing permissions for a role.

Naming rules

• Two or more segments separated by :, such as loan:approve or loan:approve:own. A single word such as approve is not a permission.
• Each segment uses only lowercase ASCII letters (a–z), digits and _, and starts with a letter.
• A . may join words inside a segment (roles.manage). Each word starts with a letter too, so roles. and .manage are rejected.
• Nothing else: no capitals, -, spaces or other characters.
• At most 128 characters.

Valid	Rejected
loan:approve	approve (no :)
loan:approve:own	Loan:Approve (capitals)
wardn:roles.manage	loan:approve-own (-)
report:export_csv	loan:2fa (segment starts with a digit)

Anything else is rejected when wardn starts, with the file, the line, what is wrong and, when there is an obvious fix, the corrected name:

wardn.yaml:3: permissions.organization.read: invalid permission "organization.read": it has no ':' between the resource and the action; did you mean "organization:read"? (permissions are resource:action, e.g. loan:approve)

Wildcards

Roles (never checks) may use wildcards:

Pattern	Matches
*	every permission
loan:*	every loan: permission, such as loan:create and loan:approve:own, but not loans:…
loan:approve:*	every permission starting loan:approve:

A wildcard must match at least one permission in the catalog, which catches typos like laon:*.

Caution

A wildcard grants permissions added to the catalog later, too. loan:* written today also grants loan:write_off the day someone adds it. Prefer explicit lists for roles that should not grow automatically.

Built-in permissions

Two permissions control role management and are always in the catalog:

Permission	Allows
wardn:roles.assign	Assigning and revoking roles
wardn:roles.manage	Creating, editing and deleting custom roles

Grant them to roles like any other permission. * includes them. Don’t declare them in permissions:; the wardn: prefix is reserved.

Checking an undefined permission

Checking a permission that isn’t in the catalog is an error, never a silent “no”:

wardn: permission "loan:aprove" is not defined; did you mean "loan:approve"?

Require goes further and panics when the route is registered, so the mistake stops the application at startup. For compile-time protection, see Typo-proof names.