# IAM RBAC Foundation

## Purpose

This increment introduces the first role-based authorization foundation for the platform.

## Core rules

- Membership establishes whether an authenticated identity belongs to a tenant.
- Roles are tenant-owned.
- Permissions are platform-defined capability codes.
- Role permission effects are explicit: `allow` or `deny`.
- When multiple roles apply, `deny` takes precedence over `allow`.
- If no applicable rule exists, the decision is `abstain` and must not be treated as an implicit allow.
- Role assignments can currently be scoped to:
  - tenant
  - company
  - branch
- Cost visibility is represented by a separate permission (`finance.cost.view`) rather than being inferred from unrelated management permissions.

## Current authorization pipeline

Authentication -> Tenant Resolution -> Active Membership -> Permission Evaluation -> Domain Action

## Not yet included

The following are intentionally deferred to the next IAM increment:

- HTTP permission middleware / route enforcement
- permission administration APIs
- role administration APIs
- assignment APIs
- approval engine integration
- permission caching
- field-level masking based on cost visibility
- audit events for role/permission mutations

## Security position

A missing permission decision is not an allow.
`DENY > ALLOW > ABSTAIN`.