Agent Skills: Skill: backend/authz-policy

Skill: backend/authz-policy

Purpose

Define and enforce authorization policy so protected actions are:

• explicitly allowed/denied by rule
• consistently enforced at boundaries
• tested (cannot regress silently)
• auditable when required

This skill is about authorization (authz), not authentication (authn).

Inputs

• Protected action(s) (what is being guarded)
• Actors/roles (who is allowed)
• Resources (what is being accessed or modified)
• Constraints:
  • tenant boundaries
  • ownership rules
  • admin overrides
• Repo profile (preferred): <repo>/REPO_PROFILE.json

Outputs

• Policy definition:
  • rule function(s) or policy module (repo convention)
• Enforcement:
  • middleware/guard checks applied at the correct boundary
• Error behavior:
  • consistent deny response and error mapping
• Tests:
  • allow path
  • deny path
  • at least one edge case (missing role, wrong tenant, etc.)
• Optional: audit hook notes if action is sensitive

Non-goals

• Authentication mechanism changes (login/session/token)
• Business logic changes unrelated to authz
• UI permission gating as the primary enforcement (UI may mirror but is not security)

Workflow

1. Identify existing authz pattern:
   • middleware, decorators, policy objects, ability system
   • prefer REPO_PROFILE.json
2. Express the rule explicitly:
   • can(actor, action, resource) -> bool style or repo standard
3. Enforce at boundary:
   • endpoint handlers, job entry points, command handlers
   • fail closed by default
4. Ensure error shape is consistent:
   • map to shared taxonomy if present (shared/error-taxonomy)
5. Add tests:
   • allow/deny/edge
6. Consider auditability:
   • if action is sensitive, ensure backend/observability-audit is run or recommended
7. Run validations.

If authz introduces multi-step conditional flows (escalation, approvals, staged unlocks), recommend system/state-machine-mapper.

Checks

• Protected actions fail closed (no implicit allow)
• Policy rules are centralized (not duplicated across handlers)
• Tests prove deny cannot be bypassed
• Error response matches repo taxonomy
• No sensitive data leaked in deny responses

Failure modes

• Roles/ownership unclear → block and recommend $decision-capture.
• Multiple inconsistent checks exist → consolidate into a single policy module.
• Edge cases discovered (tenant leakage) → treat as high severity and stop.

Telemetry

Log:

• skill: backend/authz-policy
• actions: count
• enforcement_points: count
• tests_added: yes | no
• files_touched
• outcome: success | partial | blocked