# Route Access Matrix

**Date:** 2026-03-30
**Purpose:** Make high-sensitivity API audiences explicit and reduce ambiguous `protectedProcedure` usage on broad read routes.

## Audience Classes

- `self-service`: authenticated users can only read or mutate data that belongs to their linked resource or account
- `authenticated-safe-lookup`: authenticated users can access a deliberately narrow, identity-safe lookup surface
- `resource-overview`: users with `viewAllResources` or `manageResources`
- `planning-read`: users with at least one of `viewCosts`, `manageProjects`, or `manageAllocations`
- `controller-finance`: controller, manager, or admin through `controllerProcedure`
- `manager-write`: manager or admin through `managerProcedure`
- `admin-only`: admin through `adminProcedure`

## Current Classification

### `packages/api/src/router/resource.ts`

- `getMyResource`: `self-service`
- `getById`, `getByEid`, `getHoverCard`, `getByIdentifier`, `getByIdentifierDetail`, `resolveByIdentifier`, `getChargeabilitySummary`: `self-service` unless the caller also has `resource-overview`
- `directory`: `authenticated-safe-lookup`
- `listSummaries`, `listSummariesDetail`, `listStaff`, `resolveResponsiblePersonName`: `resource-overview`
- `getSkillsAnalytics`, `searchBySkills`, `listWithUtilization`, `getChargeabilityStats`, `getSkillMarketplace`: `controller-finance`
- create, update, deactivate, batch update, imports for other users: `manager-write` or `admin-only`

### `packages/api/src/router/project.ts`

- `resolveByIdentifier`, `searchSummaries`, `getByIdentifier`: `planning-read`
- `searchSummariesDetail`, `list`, `getById`, `getByIdentifierDetail`, `getShoringRatio`, `listWithCosts`: `controller-finance`
- create, update, status changes, cover mutations: `manager-write`
- delete and batch delete: `admin-only`
- `isImageGenConfigured`, `isDalleConfigured`: authenticated low-risk configuration checks

### `packages/api/src/router/timeline.ts`

- `getMyEntriesView`, `getMyHolidayOverlays`: `self-service`
- timeline-wide planning reads and shift previews: `controller-finance`
- allocation updates, quick-assign, project shifts: `manager-write`

### `packages/api/src/router/allocation.ts`

- `list`, `listView`, `listDemands`, `listAssignments`, `getAssignmentById`, `resolveAssignment`, `getDemandRequirementById`, `checkResourceAvailability`, `getResourceAvailabilityView`, `getResourceAvailabilitySummary`: `planning-read`
- mutations already sit behind `manager-write`

### `packages/api/src/router/dashboard.ts`

- all current routes are `controller-finance`

## Immediate Follow-Ups

- introduce a dedicated project-read permission instead of the current interim `planning-read` composite
- split `allocation` further into narrower future audiences where resource-capacity and staffing-demand reads diverge
- add authorization tests for every route listed above so the matrix is CI-enforced, not just documented