189 lines
9.5 KiB
Markdown
189 lines
9.5 KiB
Markdown
# Auth Profile
|
|
|
|
## Purpose
|
|
|
|
The auth subsystem owns sign-in, signup, the current-user profile contract
|
|
(`GET /api/auth/me`), password reset / email verification, OAuth (Google)
|
|
sign-in, and the permission enforcement model. This document covers
|
|
the profile and permission concerns; the HttpOnly cookie session transport
|
|
(access/refresh tokens, rotation, CSRF/origin, sign-out) is documented in
|
|
`backend/docs/cookie-auth.md`.
|
|
|
|
The profile response must not expose passwords, verification tokens, reset
|
|
tokens, or raw Sequelize model objects.
|
|
|
|
## Slice Files (by layer)
|
|
|
|
- Route: `src/routes/auth.ts` (thin wiring; mounted at `/api/auth` in
|
|
`src/index.ts`). `/me`, `/password-update`, `/send-email-address-verification-email`,
|
|
and `/profile` are guarded by `passport.authenticate('jwt', { session: false })`.
|
|
- Controller: `src/api/controllers/auth.controller.ts` (custom — not the CRUD
|
|
factory).
|
|
- Service (BLL): `src/services/auth.ts` (class `Auth`, default export
|
|
`AuthService`) with DTO shapes in `src/services/auth.types.ts`.
|
|
- Passport strategies: `src/auth/auth.ts` (JWT via `passport-jwt`; Google via
|
|
the maintained, typed **`passport-google-oauth20`**). OAuth is wired for future
|
|
use and is not surfaced in the current UI.
|
|
- Cookie helpers: `src/auth/cookies.ts` (used for the session transport;
|
|
see `cookie-auth.md`).
|
|
- Permission middleware: `src/middlewares/check-permissions.ts`
|
|
(`checkPermissions`, `checkCrudPermissions`).
|
|
- Origin middleware: `src/middlewares/csrf-origin.ts` (see `cookie-auth.md`).
|
|
- Repositories (DAL): `src/db/api/users.ts` (`UsersDBApi`),
|
|
`src/db/api/auth_refresh_tokens.ts` (`AuthRefreshTokensDBApi`),
|
|
`src/db/api/roles.ts` (`RolesDBApi`, used by the permission middleware).
|
|
- Models: `src/db/models/users.ts`, `src/db/models/auth_refresh_tokens.ts`,
|
|
plus the `roles`, `permissions`, `organizations`, `staff`, and `campuses`
|
|
models joined for the profile.
|
|
- Shared used: `shared/config` (auth/cookie/OAuth config), `shared/jwt`
|
|
(`jwtSign`), `shared/constants/auth.ts`, `shared/constants/roles.ts`
|
|
(role definitions, scopes, names), `shared/errors/*` (`ForbiddenError`,
|
|
`ValidationError`), `services/email/*` (verification / reset / invitation
|
|
emails).
|
|
|
|
## API
|
|
|
|
Base path `/api/auth` (mounted in `src/index.ts`).
|
|
|
|
Profile / account endpoints:
|
|
|
|
- `GET /api/auth/me` (JWT-authenticated) -> `200` the current user profile
|
|
payload (see Data Contract). Returns `ForbiddenError` when there is no
|
|
current user.
|
|
- `POST /api/auth/signup` -> `200` the current user profile. Body:
|
|
`{ email, password, organizationId }`. Creates a session and sets cookies.
|
|
- `PUT /api/auth/profile` (JWT-authenticated) -> `200` `true`. Body:
|
|
`{ profile }` (passed to `UsersDBApi.update`).
|
|
- `PUT /api/auth/password-update` (JWT-authenticated) -> `200` the updated
|
|
user. Body: `{ currentPassword, newPassword }`.
|
|
- `PUT /api/auth/password-reset` -> `200` the updated user. Body:
|
|
`{ token, password }`.
|
|
- `PUT /api/auth/verify-email` -> `200` result of marking the email verified.
|
|
Body: `{ token }`.
|
|
- `POST /api/auth/send-password-reset-email` -> `200` `true`. Body: `{ email }`.
|
|
The reset link host is derived from the request referer.
|
|
- `POST /api/auth/send-email-address-verification-email` (JWT-authenticated)
|
|
-> `200` `true`. Sends a verification email to the current user's address.
|
|
- `GET /api/auth/email-configured` -> `200` boolean (`EmailSender.isConfigured`).
|
|
|
|
Sign-in (covered in detail in `cookie-auth.md`):
|
|
|
|
- `POST /api/auth/signin/local` -> `200` the current user profile.
|
|
|
|
OAuth endpoints:
|
|
|
|
- `GET /api/auth/signin/google` -> redirects to Google
|
|
(`passport.authenticate('google', { scope: ['profile', 'email'], state })`).
|
|
- `GET /api/auth/signin/google/callback` (Passport `google`,
|
|
`failureRedirect: '/login'`) -> sets session cookies and redirects to
|
|
`config.uiUrl` (no token query parameters).
|
|
|
|
OAuth users are resolved by `db.users.findOrCreate({ where: { email, provider } })`
|
|
in `src/auth/auth.ts`; the Google email comes from the typed
|
|
`profile.emails[0].value`.
|
|
|
|
## Access Rules
|
|
|
|
- JWT routes are protected by `passport.authenticate('jwt', { session: false })`,
|
|
which extracts the access token from the HttpOnly access cookie
|
|
(`cookies.extractAccessCookie`) and loads the user by email. A disabled user
|
|
is rejected by the strategy (`done(new Error(...))`).
|
|
- Permission enforcement (`src/middlewares/check-permissions.ts`):
|
|
- `checkPermissions(permission)` allows the request if any of:
|
|
1. self-access bypass — `currentUser.id` equals `req.params.id` or
|
|
`req.body.id`;
|
|
2. global-access bypass — the user's `app_role.globalAccess` is `true`
|
|
(the system-scope roles `super_admin` / `system_admin`), which pass any
|
|
permission;
|
|
3. the user's `custom_permissions` include `permission`;
|
|
4. the effective role's permissions include `permission`. The effective
|
|
role is the user's `app_role`, or the cached seeded `guest` role
|
|
(`ROLE_NAMES.GUEST`) when there is no assigned role. The `guest` role is
|
|
fetched once at module load and cached.
|
|
- A denied request is passed `new ValidationError('auth.forbidden')`.
|
|
- `checkCrudPermissions(name)` derives the permission as
|
|
`${METHOD}_${ENTITY}` from the HTTP method and entity name, where the
|
|
method maps `POST->CREATE`, `GET->READ`, `PUT->UPDATE`, `PATCH->UPDATE`,
|
|
`DELETE->DELETE` and `ENTITY` is `name.toUpperCase()`. It then delegates to
|
|
`checkPermissions`. This middleware is applied per generic-CRUD router via
|
|
`router.use(permissions.checkCrudPermissions(permission))` in
|
|
`src/api/http/crud-router.ts`; the auth routes themselves do not use it.
|
|
|
|
## Tenant Scope
|
|
|
|
- The profile is loaded for the authenticated user only
|
|
(`UsersDBApi.findProfileById(currentUser.id)`), so it reflects that user's
|
|
own organization, role, staff profile, and campus.
|
|
- `signup` accepts an `organizationId` and assigns it to the created user.
|
|
- Tenant filtering for other entities is enforced elsewhere (CRUD repositories
|
|
scope by `currentUser.organizationId`); the auth profile endpoints do not
|
|
add tenant filtering beyond loading the current user.
|
|
|
|
## Data Contract
|
|
|
|
`AuthService.currentUserProfile` returns (built from `findProfileById`):
|
|
|
|
- `id`, `email`, `name_prefix` (honorific title — `mr`/`ms`/`mrs`/`mx`/`dr`/`prof`, or `null`), `firstName`, `lastName`
|
|
- `organizationId`
|
|
- `organizations` — `OrganizationDto` `{ id, name }` or `null`
|
|
- `app_role` — `RoleDto` `{ id, name, scope, globalAccess }` or `null`. `name`
|
|
is one of the 11 first-class role names and `scope` is its scope
|
|
(`system` | `organization` | `campus` | `external` | `guest`); the frontend
|
|
derives the UI role from `app_role.name`. There is no separate `productRole`.
|
|
- `staffProfile` — `StaffProfileDto`
|
|
`{ id, employee_number, job_title, staff_type, status, organizationId,
|
|
campusId, userId }` or `null` (first row of `staff_user`)
|
|
- `campus` — `CampusDto` `{ id, name, code }` or `null`
|
|
- `campusId` — the campus DTO id, else the staff profile `campusId`, else `null`
|
|
- `permissions` — de-duplicated string names from the role's permissions plus
|
|
the user's `custom_permissions`
|
|
|
|
Note: the profile payload does not include a `phoneNumber` field
|
|
(`findProfileById` does not select it and `currentUserProfile` does not return
|
|
it).
|
|
|
|
Role model: roles are first-class persisted rows (`src/shared/constants/roles.ts`
|
|
`ROLE_DEFINITIONS` / `ROLE_NAMES`, seeded by
|
|
`db/seeders/20200430130760-user-roles.ts`). Each role has a `scope` and, for the
|
|
two system roles, `globalAccess: true`. The preset permission matrix grants
|
|
`owner` / `superintendent` / `director` every permission, `office_manager` /
|
|
`teacher` / `support_staff` read-only entity permissions, and `student` /
|
|
`guardian` / `guest` none; `super_admin` / `system_admin` need no rows (they
|
|
bypass via `globalAccess`). Per-user `custom_permissions` extend a user's grants.
|
|
|
|
Signup / signin behavior (`src/services/auth.ts`):
|
|
|
|
- `signin` throws `ValidationError` for `auth.userNotFound`, `auth.userDisabled`,
|
|
`auth.wrongPassword`, or `auth.userNotVerified`. When email is not configured
|
|
(`EmailSender.isConfigured` is false), `emailVerified` is treated as true.
|
|
- `signup` rehashes the password with `bcrypt` (`config.bcrypt.saltRounds`).
|
|
An existing disabled user raises `auth.userDisabled`; an existing enabled user
|
|
has its password updated; a new user is created via `UsersDBApi.createFromAuth`
|
|
(first name defaults to the email local-part, default role from
|
|
`config.roles.user`). A verification email is sent when email is configured.
|
|
- `passwordUpdate` requires a logged-in user, verifies the current password,
|
|
rejects reuse of the same password (`auth.passwordUpdate.samePassword`), and
|
|
stores the new bcrypt hash.
|
|
- `passwordReset` / `verifyEmail` look up the user by a non-expired
|
|
`passwordResetToken` / `emailVerificationToken` and raise the matching
|
|
`ValidationError` on an invalid token. Tokens are random hex of
|
|
`EMAIL_ACTION_TOKEN_BYTES` with TTL `EMAIL_ACTION_TOKEN_TTL_MS`.
|
|
|
|
## Behavior / Notes
|
|
|
|
- Profile loads use a single trimmed eager query (`UsersDBApi.findProfileById`)
|
|
selecting only the columns and relations the DTO reads.
|
|
- Auth tokens are never returned in response bodies or redirect URLs; OAuth
|
|
callbacks redirect to `config.uiUrl` with cookies only.
|
|
- `updateProfile` runs inside a Sequelize transaction.
|
|
|
|
## Tests
|
|
|
|
None yet (no auth unit/e2e test under `backend/src`).
|
|
|
|
## Related
|
|
|
|
- Cookie session transport: `backend/docs/cookie-auth.md`.
|
|
- Frontend: `frontend/docs/auth-integration.md`.
|
|
- Role constants (definitions, scopes, names): `src/shared/constants/roles.ts`.
|