# Permissions Backend

## Purpose

`permissions` is the catalog of named permission strings that authorize API access. Each
permission is a single `name` (e.g. `CREATE_USERS`, `READ_DOCUMENTS`). Permissions are attached to
roles (a role's `permissions`) and to individual users (a user's `custom_permissions`); the
authorization middleware checks them per request. This slice manages the permission catalog itself
(CRUD); the consumption of permission names happens in `middlewares/check-permissions.ts`.

## Slice Files (by layer)

- Route: `src/routes/permissions.ts` (CRUD plus `bulk-import`, `count`, `autocomplete`,
  `deleteByIds`; applies `checkCrudPermissions('permissions')` to every route).
- Controller: `src/api/controllers/permissions.controller.ts` (CSV export, file upload for bulk
  import).
- Service (BLL): `src/services/permissions.ts` (transactional writes; CSV buffer parsing).
- Repository (DAL): `src/db/api/permissions.ts`.
- Model: `src/db/models/permissions.ts`.
- Consumer middleware: `src/middlewares/check-permissions.ts` (how permission names are read and
  enforced).
- Shared used: `db/api/shared/repository.ts` (`removeRecord`, `deleteRecordsByIds`), `db/utils.ts`
  (`Utils.uuid`, `Utils.ilike`), `shared/constants/pagination.ts` (`resolvePagination`),
  `shared/constants/database.ts` (`BULK_IMPORT_TIMESTAMP_STEP_MS`),
  `shared/constants/roles.ts` (`ROLE_NAMES`), `shared/csv.ts` (`toCsv`),
  `middlewares/upload.ts` (`processFile`), `db/api/roles.ts` (`RolesDBApi`, used by the
  middleware), `shared/object.ts` (`isRecord`), `shared/logger.ts`,
  `shared/errors/validation.ts`.

## API

All routes are mounted under `/api/permissions` and require JWT authentication (`src/index.ts`).
Every route passes `checkCrudPermissions('permissions')`, requiring `${METHOD}_PERMISSIONS`.

- `POST /api/permissions` -> `200` `true`. Request body: `{ data: <PermissionInput> }`.
- `POST /api/permissions/bulk-import` -> `200` `true`. Multipart CSV upload. Missing file raises
  `ValidationError('importer.errors.invalidFileEmpty')`.
- `PUT /api/permissions/:id` -> `200` `true`. The controller calls
  `Service.update(req.body.data, req.body.id, ...)` (reads `req.body.id`, not `req.params.id`).
- `DELETE /api/permissions/:id` -> `200` `true`.
- `POST /api/permissions/deleteByIds` -> `200` `true`. Request body: `{ data: string[] }`.
- `GET /api/permissions` -> `200` `{ rows, count }`. When `?filetype=csv`, responds with a CSV
  attachment of fields `id, name`.
- `GET /api/permissions/count` -> `200` `{ rows: [], count }`.
- `GET /api/permissions/autocomplete` -> `200` array of `{ id, label }` (label is the permission
  `name`, ordered by `name ASC`).
- `GET /api/permissions/:id` -> `200`, a single plain record.

## Access Rules

CRUD on the permissions catalog is gated solely by `checkCrudPermissions('permissions')`
(`${METHOD}_PERMISSIONS`). There is no tenant scope or additional role-name gate inside the
service or repository.

## How permission names are consumed (`check-permissions.ts`)

`checkCrudPermissions(name)` derives a permission string from the HTTP method and entity name:
`${METHOD_MAP[req.method]}_${name.toUpperCase()}` where `METHOD_MAP` is
`POST→CREATE`, `GET→READ`, `PUT→UPDATE`, `PATCH→UPDATE`, `DELETE→DELETE`. For example a `GET` on
the `users` router requires `READ_USERS`; a `POST` on `assessments` requires `CREATE_ASSESSMENTS`. It
then delegates to `checkPermissions(permissionName)`.

`checkPermissions(permission)` allows the request when any of the following holds, in order:

1. Self-access bypass: read-only — a `GET` whose `currentUser.id === req.params.id` (the
   `req.body.id` bypass was removed; profile self-edits go through `/api/auth/profile`).
2. Custom (per-user) permissions: the current user's `custom_permissions` contains a record whose
   `name` equals the required permission.
3. Effective-role permissions: the effective role is the user's `app_role` if present, otherwise
   the `guest` role (`ROLE_NAMES.GUEST`), which is fetched once at module load via
   `RolesDBApi.findBy` and cached (`publicRoleCache`); if the cache is empty it is fetched
   synchronously as a fallback. `resolveRolePermissions` reads the role's permission names from an
   eager-loaded `permissions` array when present, otherwise calls `getPermissions()`. Access is
   granted when that list `includes(permission)`.

On denial the middleware logs the role name and the denied permission and calls
`next(new ValidationError('auth.forbidden'))`. A role object lacking both a `permissions` array and
a `getPermissions()` method, or a missing/unfetchable `Public` role, surfaces an Internal Server
Error via `next(new Error(...))`.

## Product-feature permissions (§3.2)

Besides the `${METHOD}_${ENTITY}` CRUD permissions, the catalog includes product-feature
permissions defined once in `shared/constants/product-permissions.ts`: a `READ_<MODULE>` per
product page and the three action permissions `FILL_ATTENDANCE` / `TAKE_QUIZ` / `ACK_READ_RECEIPT`.
The role seeder grants them per role (full-access roles get all; campus staff get their page set;
external roles get the external pages). The feature routes enforce them with the **same**
`checkPermissions(name)` middleware: page reads and the special actions call it directly
(e.g. `GET /api/frame_entries` → `READ_FRAME`, `PUT /api/campus_attendance/summaries/...` →
`FILL_ATTENDANCE`, `POST /api/safety_quiz_results` → `TAKE_QUIZ`). Because that middleware honors
`custom_permissions` (step 2 above), a director can extend a single user's feature access by
granting one of these names. Manager-only writes (FRAME/walkthrough/communications/content-catalog
editing, the staff/attendance reports) remain gated by role inside their services until dedicated
`MANAGE_*` permissions are introduced.

## Tenant Scope

None. The permission catalog is global; `findAll` applies no organization filter.

## Data Contract

Model columns (`src/db/models/permissions.ts`): `id` (UUID PK), `name` (text), `importHash`
(unique), `createdAt`, `updatedAt`, `deletedAt` (paranoid soft-delete), `createdById`,
`updatedById`. Associations: `belongsTo users` as `createdBy`/`updatedBy` only. The model itself
declares no association to roles or users for the permission grants; those join tables are declared
on the `roles` and `users` models (e.g. `users.belongsToMany(permissions)` through
`usersCustom_permissionsPermissions`).

List filters (`findAll`): `id` (uuid), `name` (ILIKE), `active`, `createdAtRange`, plus
`field`/`sort` (default `createdAt desc`) and `limit`/`page` pagination.

## Behavior / Notes

- All mutations run inside a manual Sequelize transaction (commit on success, rollback on error).
- `update` raises `ValidationError('permissionsNotFound')` when the record does not exist.
- Bulk import parses the uploaded CSV (`csv-parser`), then `bulkCreate`s with
  `ignoreDuplicates: true` and staggered `createdAt` (`BULK_IMPORT_TIMESTAMP_STEP_MS`).
- The `Public` role permission cache in `check-permissions.ts` is loaded at application startup;
  a startup failure to load it is logged but does not stop boot (the synchronous fallback covers
  per-request misses).

## Tests

None yet (no `permissions` unit/e2e test under `src/`).

## Related

- Backend slices: the `roles` entity (a role's `permissions` provide the effective-role grants)
  and `users.md` (a user's `custom_permissions` and assigned `app_role`, eager-loaded in
  `UsersDBApi.findBy` for per-request authorization).
- `auth-profile.md` (the profile DTO carries `app_role_permissions` and `custom_permissions`, the
  same permission names enforced here).