CapaKraken/docs/route-access-matrix.md

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

• broad planning and staffing reads should move from generic protectedProcedure to explicit planning-read or narrower follow-up audiences
• mutations already sit behind manager-write

packages/api/src/router/dashboard.ts

• all current routes are controller-finance

Immediate Follow-Ups

• reclassify allocation read endpoints away from generic protectedProcedure
• introduce a dedicated project-read permission instead of the current interim planning-read composite
• add authorization tests for every route listed above so the matrix is CI-enforced, not just documented