# User access

Named account access requires `AUTH_MODE=users`. The legacy shared PIN mode
does not provide individual account restrictions.

| Account type | App access | Site scope | User settings |
| --- | --- | --- | --- |
| Admin | Dashboard, Ask, Clock | All sites | Manage users |
| Site manager | Operational dashboard and Clock | Assigned sites | Create and list clock accounts within assigned sites |
| Clock user | Clock only: worker/fleet scans and document uploads | Assigned sites | None |
| Office user | Selected dashboard sections with full actions | Assigned sites or All sites | None |

## Office setup

In Settings · Users, choose Office user, then an access preset (Workforce,
Financial, or Plant) or select sections individually. At least one section is
required. Each section includes its overview, details, imports, corrections,
and future pages under the same section. Selecting several sections gives the
user all of those sections. Overview is the company dashboard overview;
Workforce's own overview is included with Workforce.

Choose All sites for head-office work spanning the company. This includes new
sites automatically. Turn it off to select specific sites. Site lookup names
and the site selector still work within enabled sections; this does not grant
access to the Sites management section. Ask and user administration remain
unavailable to Office users.

For Julius, after deploying this version, edit his existing account:

- Account type: Office user.
- Preset: Workforce (only Workforce selected).
- Site scope: All sites if his remit covers the company; otherwise select his sites.

He starts on Workforce overview and sees Workers, Timesheets, and On site now.
Worker details, rates, sick notes, calendars, timesheet imports/upload status,
and missed-clock-out corrections inherit Workforce access. Other section URLs
redirect him to his first enabled section, and other section APIs return 403.

## Schema rollout

Existing account roles, passwords, and sites are preserved. The additive
migration adds `office_user` to `users.role`, multi-select `users.modules`
(`overview`, `sites`, `workforce`, `plant`, `financial`), and Boolean
`users.all_sites`. Existing non-office accounts retain their role defaults;
office fields do not grant extra access to clock or site-manager accounts.

Run the dry run against the configured PocketBase environment:

```bash
python3 scripts/migrations/2026-10-07-office-access.py --env-file .env.local
```

Apply before deploying Office user settings, passing the exact URL printed by
the dry run as `--confirm-host`:

```bash
python3 scripts/migrations/2026-10-07-office-access.py --env-file .env.local --apply --confirm-host "$POCKETBASE_URL"
```

This changes only the users collection fields. It does not convert Julius or
any other existing account. Convert accounts after deploying, because the old
app rejects the new Office user role.

## Extending sections

`src/lib/auth/path-access.ts` is the shared page/API policy used by the proxy,
navigation, and operation guard. New nested pages inherit their section root.
Workforce employee and `/api/workforce/` routes inherit Workforce access.
Unknown API routes remain admin-only until assigned an explicit category.

Use `getSiteScope(searchParams, "workforce")` (or the relevant section) before
loading page data, and `requireApiUser("workforce")` in its handlers. Shared
operation routes use `authorizeOperation(request)` plus record/site checks.
The only Financial handlers permitting clock accounts are document uploads
and purchase-order upload status/retry; new dashboard operations must not use
`allowClock: true`.