le-app/directus/auth-contract.md

# Authentication and account contract

Status labels mean:

- **Verified**: directly supported by application source plus the sanitized production exports.
- **Inferred**: the source intends the behavior, but a runtime binding, omitted value, or live test is missing.
- **Unresolved**: the required implementation or evidence is absent.

The app uses a Directus access token as a user bearer, normally stored in the HTTP-only `ma_at` cookie. It stores a refresh token in HTTP-only `ma_rt` and a five-minute recent-authentication marker in HTTP-only `ma_ra`. In production these cookies are `Secure`, `SameSite=Lax`, and path `/` where set by the current auth routes.

## Operation matrix

| Operation | Application route/module | Directus endpoint | Credential and required permission | Success and important failures | Status |
| --- | --- | --- | --- | --- | --- |
| Signup | `POST /api/auth/register`; `app/app/api/auth/register/route.ts` | `GET /users` duplicate lookup; `GET /roles` Users-role lookup; `POST /users`; then `POST /auth/login` | The canonical static server credential is `DIRECTUS_TOKEN_ADMIN_REGISTER`, with legacy service/admin names as fallbacks. It must represent the Registration Bot role/policy or an equivalent identity. Registration policy grants the required role read and user read/create permissions. | Validates all fields, email shape, password length >=8, and confirmation. Resolves the `Users` role, creates an active account with email/username/password, and performs email-based auto-login. Successful login sets `ma_at` and possibly `ma_rt`. Permission/configuration failures are logged server-side and returned as generic temporary-unavailable responses. | Application flow, build, mocked request contract, and policy are **verified**; production static credential-to-role binding still requires deployment verification because users/values were omitted. |
| Duplicate-user check | Same route | `GET /users?filter[...]&fields=id&limit=1` | Registration policy requires `directus_users.read` for `id`, which is exported. | A returned row or create-time uniqueness conflict produces the same generic email-or-username 409. A failed lookup stops signup with a generic 503 instead of continuing with uncertain permissions. | **Verified** source and mocked request behavior; production credential capability requires a live test. |
| Email login | `POST /api/auth/login`; `app/app/api/auth/login/route.ts` | `POST /auth/login` | No bearer is supplied; local email/password credentials are sent to Directus. No collection permission is used for the auth endpoint itself. | On success sets one-hour `ma_at`, optional 30-day `ma_rt`, and optionally five-minute `ma_ra` for a reauth request. Authentication failures are deliberately collapsed to a generic 401. App IP limiter allows 20 attempts/minute per process. | **Verified** implementation; live Directus local-auth behavior is **inferred** pending integration tests. |
| Username login | Same login route; `emailForUsername()` in `app/lib/directus.ts` | Static-token `GET /users` lookup, then `POST /auth/login` with resolved email | The same registration credential used by signup must read `directus_users.username,email`; Registration policy exports those fields. | Missing username gives generic 401. Lookup errors give 503. Resolved email follows email-login behavior. The shared helper accepts `DIRECTUS_URL` with `NEXT_PUBLIC_API_BASE_URL` fallback. | Source, build, required policy, and mocked request contract are **verified**; credential binding and end-to-end production success require a deployment test. |
| Current user | `GET /api/account`, `GET /api/me`, proxy `/api/dx/users/me`, middleware; relevant modules under `app/app/api/` and `app/middleware.ts` | `GET /users/me` with varying field lists | Current user's access token. Users Self Access policy permits own-row read of `id,username,first_name,last_name,email,password,avatar,location,title,description,tags,language,tfa_secret,email_notifications`; Users policy additionally permits public-like `id,username,first_name,avatar,location`. | Returns requested profile fields if field permissions allow. Middleware checks `id` at most once per minute and redirects to reauth on failure. `/api/me` requests `display_name`, which is not present in the exported custom user-field metadata or allowed-field lists, so that field's behavior is unresolved. | Own-row permissions and route calls are **verified**. |
| Token refresh | Token storage occurs in register/login and `app/lib/auth-cookies.ts` | Expected Directus endpoint would be `/auth/refresh`, but no call exists | `ma_rt` is stored, but no application route consumes it. | There is no implemented refresh behavior. Expired/invalid `ma_at` causes middleware to clear `ma_at`/`ma_v` and redirect to sign-in. | **Verified missing implementation**. |
| Logout | `POST` or `GET /api/auth/logout`; `app/app/api/auth/logout/route.ts` | None | No Directus call and no credential required by the handler. | Expires only `ma_at`. It does not revoke the Directus session and does not clear `ma_rt`, `ma_ra`, or `ma_v`. | **Verified**. |
| Password change | `POST`/`PATCH /api/account/password`; `app/app/api/account/password/route.ts` | `GET /users/me`; optionally static-token `GET /users`; `POST /auth/login`; `PATCH /users/me` | Current user token needs own-row read and `directus_users.update` for `password`; Users Self Access grants both. Username verification additionally needs Registration read permission. | Requires current/new values and an eight-character new password. Verifies the current password through local login, then patches only `password`. External-provider rejection depends on reading `provider`, but `provider` is not in the Users Self Access read fields, so this guard may not receive the field. Successful change does not rotate or clear existing app tokens. | Main path and permissions **verified**; provider guard and session effects **unresolved**. |
| Profile changes | `PATCH /api/account` and `PATCH /api/account/profile`; UI primarily uses the latter | `PATCH /users/me` | Current user token. Users Self Access update permits `first_name,last_name,email,avatar,location,password`; it does not permit `username`. | First/last name and location update directly. Email requires `ma_ra=1`; the marker is cleared after a successful sensitive update. UI always includes email in its payload, so its normal save path requests reauthentication even when email is unchanged. Username is classified sensitive but is never added to the patch payload and is not update-permitted. | **Verified**. |
| Avatar change | `POST /api/account/avatar`; `app/app/api/account/avatar/route.ts` | `POST /files`, then `PATCH /users/me` | Current user token. Users policy permits `directus_files.create` on all fields; Users Self Access permits own `avatar` update. | Requires a configured avatar folder, <=10 MB JPEG/PNG/WebP/GIF, and recognized signature. Uploads file then links its ID. If linking fails, the uploaded file is not cleaned up. | **Verified** except folder value and folder-specific enforcement, which are **unresolved**. |
| Reauthentication | `POST /api/auth/reconfirm`; `app/app/api/auth/reconfirm/route.ts`, or login with `reauth=true` | Optional static-token `GET /users`, then `POST /auth/login` | Local credentials; username form also requires Registration `directus_users.read`. | Successful reconfirm replaces `ma_at` and sets `ma_ra` for five minutes. It does not set/replace `ma_rt`. Login's reauth path sets `ma_ra` alongside normal token cookies. Failures are generic 401. | **Verified** implementation; end-to-end username path remains unresolved. |

## Permission identity model

The export verifies these role-to-policy assignments:

- Registration Bot role -> Registration policy.
- Users role -> Users Self Access policy and Users policy, in that sort order.
- Administrator role -> Administrator policy.
- Supporter Bot role -> Supporter policy.
- Public policy has a role-less access assignment.

Because user rows and user-specific access assignments were intentionally omitted, the evidence cannot prove which identity owns any configured static credential. A deployment test must verify each credential's effective policy rather than relying on its environment-variable name.