MEGAINFRA-WEBAPP/docs/setup/user-access.md

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:

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:

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.