playbooks

home / skills / velcrafting / codex-skills / authz-policy

authz-policy skill

/skills/backend/authz-policy

This skill defines and enforces authorization rules for protected actions, ensuring explicit allows/denies, boundary enforcement, testing, and auditable

npx playbooks add skill velcrafting/codex-skills --skill authz-policy

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.8 KB
---
name: authz-policy
description: Define and enforce authorization rules for protected actions, with tests and audit considerations.
metadata:
  short-description: Authz policy + enforcement
  layer: backend
  mode: write
  idempotent: false
---

# 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`

Overview

This skill defines and enforces authorization policy so protected actions are explicitly allowed or denied, consistently enforced at boundaries, tested, and auditable. It focuses strictly on authorization (who may do what) rather than authentication. The goal is deterministic, centralized rules with clear error behavior and coverage by automated tests.

How this skill works

You express rules as explicit policy functions (for example can(actor, action, resource) -> bool) or the convention used in the codebase. The policy module is applied at enforcement boundaries (endpoints, job entry points, command handlers) via middleware, guards, or decorators. Tests verify allow, deny, and edge conditions, and sensitive actions include audit hooks or observability notes.

When to use it

  • Protect any action that changes state or accesses sensitive data
  • When multiple handlers or services must follow the same authorization decision
  • Before shipping new APIs or job entry points that perform protected operations
  • When tenant, ownership, or admin-override constraints are required
  • When auditability or regulatory traceability is needed

Best practices

  • Fail closed by default; deny unless explicitly allowed
  • Centralize rules in a single policy module to avoid duplication
  • Map deny errors to a shared error taxonomy and keep responses free of sensitive data
  • Add tests for allow, deny, and at least one edge case (missing role, wrong tenant)
  • Annotate sensitive actions with audit hooks or references to observability procedures

Example use cases

  • Granting resource modifications only to owners or tenant admins with a can(actor, 'modify', resource) rule
  • Blocking cross-tenant reads by enforcing tenant boundary checks in middleware
  • Adding a deny-path test that verifies job handlers cannot be triggered by unauthorized actors
  • Implementing an admin-override rule with explicit audit logging for escalation
  • Centralizing role checks previously repeated across multiple endpoints into one policy module

FAQ

How do I handle multi-step approval flows or escalations?

Model multi-step flows outside primitive can() checks using a state-machine mapper or explicit staged rules; keep the authorization decision explicit for each stage and record decisions for audit.

What if existing checks are inconsistent across handlers?

Consolidate into a single policy module, replace ad-hoc checks with guard middleware, add tests proving deny cannot be bypassed, and treat any tenant leakage as high severity.