4dist.com Access Control Manual

Role hierarchy, registration flow, and Site management for the 4dist.com platform. This document is the source of truth for who can do what.

Version 1.0 · Last updated 2026-05-27 · Single-Site membership implementation; multi-Site migration targeted ~late June 2026.

1. Overview

The 4dist.com platform serves two primary user-facing products:

• Webplayer (us.4dist.com) — HLS-based sample player with multi-channel switching, zoom, drawing, downloads, etc.
• V5 Dashboard — operational control surface (OMS, DMS, system configuration, live view, recording control).

Access is governed by a five-tier role hierarchy, scoped per Site (a logical grouping representing a physical office or venue, e.g. us-office, tokyo-gym). A user is always either system-wide (Admin) or attached to exactly one Site.

2. Role Hierarchy

Each role inherits the conceptual trust level of those below it, but inheritance of capabilities is selective — for example, Admin can do everything, but Operator explicitly cannot use Member-only Webplayer features (downloads), and Member explicitly cannot access the V5 Dashboard. Permissions are defined by role, not strictly inherited.

Admin

• System-wide superuser. No Site attachment required (but may also act as Site Manager of one Site).
• Can create / rename / delete Sites.
• Can promote any approved user to any role, including other Admins or Site Managers.
• Can view and manage every Site Management Page.
• Has access to V5 Dashboard, full Webplayer, and all internal admin tools.

Site Manager

• Manages exactly one Site (attached via site_id).
• Approves new sign-ups that requested this Site, assigning each one a role of Operator, Member, or Guest.
• Cannot create Admins or other Site Managers (only Admin can promote to these roles).
• Cannot manage Sites other than their own.
• Has the same product-level access as Operator within their Site (V5 Dashboard + full Webplayer).

Operator

• Attached to one or more Sites.
• Has full access to every V5 screen for their Site(s) — Dashboard, Liveview, Recording, DMS-System, DMS-Config, OMS, System, etc. The V5 Dashboard is the operational hub used to manage all on-site equipment.
• Can change Webplayer settings for their Site (settings configuration is Operator-only — Member cannot modify settings).
• Has full Webplayer feature access (view, multi-channel switch, zoom, drawing, stopwatch, interactive overlay, download).
• Cannot approve other users or change anyone's role.

Member

• Attached to one or more Sites.
• Can use all Webplayer features for their Site's samples: view, multi-channel switch, zoom, drawing mode, stopwatch, interactive overlay, download, etc.
• Cannot change Webplayer settings — that is reserved for Operator and above.
• Cannot access the V5 Dashboard.
• Cannot approve other users.

Guest

• Attached to one or more Sites.
• Currently can view all Webplayer samples available to their Site.
• Download, drawing toolbar, stopwatch, settings, and other action buttons are disabled in the UI for Guest accounts.
• Cannot access the V5 Dashboard.
• Cannot approve other users.
• Planned future restriction: Guest will only see videos belonging to their assigned Group or videos owned by themselves (the Group concept is to be introduced — see Section 9).

3. Permissions by Role

4. Sites

A Site is a logical grouping of users tied to a physical location, team, or operational context. Examples: us-office, tokyo-gym, seoul-studio.

• Each non-Admin user belongs to one or more Sites simultaneously. A single person may, for example, be an Operator at us-office and a Member at tokyo-gym at the same time.
• Each Site may have one or more Site Managers. Multiple Site Managers can co-manage the same Site, and Site Manager role can be transferred between them (see Section 7.6).
• Webplayer samples and V5 Dashboard scope are partitioned by Site — a Member of tokyo-gym cannot see us-office samples unless they are also a member of us-office.
• Site names are lowercase, hyphen-separated, 2–40 characters (regex: ^[a-z0-9-]{2,40}$).
• Sites can be created, renamed, and deleted only by Admin.
• When a Site is deleted, any users attached to it lose only their Site assignment and role for that Site — the user account itself is preserved. If the user has no other Site assignments, they revert to a state with no Site / no role and would need to be reassigned before regaining access.

5. Registration & Approval Flow

5.0 Sign-up form requirements

The sign-up form captures the following from the user:

• Site name (required) — the Site they wish to join. Without a Site name, the system cannot route the approval to the correct Site Manager.
• Sign-up note (optional) — a short free-text message providing context (e.g. "New ops engineer for the Tokyo venue, joining May 28th"). The Site Manager reviews this note when deciding which role to grant. Users may leave this empty if they prefer.
• Sign-in via Google, Apple, Kakao, LINE, or (in development) Email mock. This authenticates the email/identity.

5.1 First sign-in for a new Site (Site Manager origin story)

1. A prospective Site Manager visits https://4dist.com/login.html.
2. They enter:
   • A new Site name (e.g. tokyo-gym),
   • A sign-up note stating their role and intent (e.g. "Branch manager for the new Tokyo gym, requesting Site Manager privileges"),
   and signs in with their preferred provider.
3. Their account is created with status=pending, requested_site_name="tokyo-gym", and the sign-up note stored. They land on /pending.html.
4. Notification:
   • The Admin is notified via Teams + email, with the sign-up note included. (The Site does not yet have any Site Manager, so the Admin handles this case directly.)
5. On /admin.html, the Admin reviews the pending sign-up and:
   • (optionally) renames the requested Site to a standardized name, OR creates a new Site with that name, OR uses an existing Site;
   • assigns the role Site Manager + the chosen Site;
   • clicks Approve.
6. The Site now exists and has a designated Site Manager. A Site Management Page is automatically available at /site.html?id=<site-id> for both this Site Manager and any Admin.

5.2 Subsequent sign-ups for an existing Site (employees / users)

1. A new user visits https://4dist.com/login.html.
2. They enter the existing Site name (e.g. tokyo-gym) + a sign-up note ("Camera operator joining the team") and sign in with their provider.
3. Account created with status=pending, requested_site_name="tokyo-gym", and sign-up note stored. They land on /pending.html.
4. Notification policy:
   • Primary recipient: the Site Manager(s) of tokyo-gym receive an email with the sign-up note and a link to their Site Management Page.
   • Secondary recipient: Admin receives a Teams notification for cross-Site oversight of all pending sign-ups, regardless of Site. (Admin email is opt-in via APPROVAL_NOTIFY_EMAIL.)
   • Future: in-app messaging channel as an alternative to email (planned).
5. A Site Manager of tokyo-gym opens their Site Management Page, sees the pending user (with their sign-up note visible) in the Pending approvals section, and clicks Approve.
6. Based on the sign-up note, the Site Manager selects:
   • Operator — for staff who manage V5 Dashboard / on-site equipment,
   • Member — for general staff who need full Webplayer features,
   • Guest — for external observers who only need to view samples.
   The user is now approved with the chosen role and that Site.
7. The approved user can now sign in and access their permitted areas.

5.3 Account linking (same person, multiple providers)

If a user signs in with a different provider but uses the same verified email as an existing approved account, the new sign-in is auto-linked: the new record inherits the existing user's Site and role and is immediately approved. No re-approval is needed.

Exceptions (these do not auto-link, because the email is not a real verified identity):

• LINE placeholder emails (<userId>@line.local) when LINE Email Permission has not been granted.
• Apple "Hide My Email" relay addresses (*@privaterelay.appleid.com).

6. Site Management Page

Each Site has a dedicated management page at https://4dist.com/site.html?id=<site-id>.

6.1 Who can access

• Admin — every Site Management Page.
• Site Manager — only their own Site's page.
• All other roles — no access (redirected away).

6.2 What it shows

The page is organized into sections, ordered by role tier:

• Pending approvals — users who requested this Site and are awaiting decision.
• Site Managers — current managers of this Site.
• Operators — operational staff.
• Members — general users with download privileges.
• Guests — view-only users.

6.3 Actions available on the page

7. Common Scenarios

7.1 Onboarding a new venue (new Site from scratch)

1. The venue lead signs in with their Google account, choosing site name seoul-studio.
2. Admin receives the notification and decides this should be a new Site.
3. Admin opens admin dashboard → reviews → approves the lead as Site Manager, assigning the new Site seoul-studio.
4. The new Site Manager receives access to their Site Management Page.
5. Venue staff sign up one by one with seoul-studio as the site to join.
6. The Site Manager approves each one as Operator, Member, or Guest as appropriate.

7.2 Promoting a Member to Operator

1. A current Member of tokyo-gym needs to start running V5 Dashboard.
2. The Site Manager of tokyo-gym opens their Site Management Page.
3. In the Members section, they click Modify… next to the user.
4. They change the role from Member to Operator and save.
5. The user can now sign in to the V5 Dashboard with no additional action needed.

7.3 Downgrading an Operator to Guest

1. An Operator has changed roles internally and now only needs to view samples.
2. Site Manager opens Site Management Page → finds them in Operators.
3. Clicks Modify… → changes role to Guest → saves.
4. On their next page load, the user will find that download/drawing/etc. buttons in the Webplayer are disabled, and V5 Dashboard access is denied.

7.4 Admin reviewing another Site

1. Admin opens /admin.html.
2. In the Sites section, clicks the Site name (e.g. tokyo-gym).
3. Lands on /site.html?id=<n> for that Site.
4. Can perform any action (approve, modify, delete, including elevating to Site Manager).

7.5 Site Manager attempting cross-Site access

1. A Site Manager of tokyo-gym manually edits the URL to /site.html?id=<us-office-id>.
2. The backend rejects the request with a 403 forbidden response.
3. The page shows an error and redirects back to their own Site Management Page.

7.6 Transferring Site Manager role to a successor

1. The current Site Manager of tokyo-gym is leaving the company.
2. They first promote their successor (currently a Member) to Site Manager: open Site Management Page → find the successor in the Members section → Modify… → choose Site Manager.
3. The successor now has Site Manager privileges for tokyo-gym (co-management state).
4. The outgoing Site Manager can either remain as Site Manager (for a handover period) or be modified by the successor (or by Admin) down to Operator / Member / Guest.
5. The outgoing Site Manager cannot demote themselves — that must be done by the successor or by Admin (self-modification is blocked).

7.7 One person joining two Sites

1. A staff member currently a Member of us-office begins assisting at tokyo-gym.
2. They sign in again at https://4dist.com/login.html with their existing provider, entering tokyo-gym as the Site to join and a sign-up note ("Cross-team assist for two months").
3. A separate pending entry is created for the tokyo-gym Site.
4. The Site Manager of tokyo-gym approves them as Operator (or Member / Guest).
5. The user can now access samples and (if Operator) the V5 Dashboard for both Sites, with the role being independent per Site.

8. Edge Cases & Rules

8.1 Self-modification is blocked

No user — not even an Admin — can change their own role or delete their own account via the dashboard. This is a deliberate lockout-prevention rule. To change Admin assignment, another Admin must perform the action (or, for the initial Admin, modify the database directly).

8.2 INITIAL_SUPERVISOR_EMAIL bootstrap

The environment variable INITIAL_SUPERVISOR_EMAIL defines the email address whose first sign-in (via any provider) is automatically granted Admin role, approved status, and assignment to us-office. This is how the very first Admin enters the system. The current designated initial Admin is hongsu@4dreplay.com.

8.3 Permanent Admin (hongsu@4dreplay.com)

The account hongsu@4dreplay.com is designated as the permanent root Admin and is protected from deletion or demotion. Specifically:

• No user (including another Admin) may delete this account.
• No user may change this account's role from Admin.
• This is a safety net: even in the worst case where every other Admin has been removed or compromised, hongsu@4dreplay.com remains and can re-establish control.

The permanent-admin email is currently hard-coded in the application logic (not configurable via environment variable). A future change may introduce a PERMANENT_ADMIN_EMAIL environment variable to make this configurable per deployment.

8.4 Last-Admin protection

The system must always have at least one active Admin. The application enforces this:

• The very last Admin cannot be deleted (the delete action returns an error).
• The very last Admin cannot have their role changed to anything other than Admin (the modify action returns an error).
• Combined with rule 8.3, hongsu@4dreplay.com ensures this invariant is always met.

8.5 Site deletion behavior

Only Admin can create, rename, or delete Sites. When a Site is deleted:

• The user accounts attached to that Site are preserved.
• Their Site assignment for the deleted Site is removed.
• Their role for that deleted Site is also removed.
• Users who had no other Site assignments revert to a no-Site / no-role state (effectively non-functional until reassigned).
• Users with other Site assignments continue to function normally for those other Sites.

8.6 Rejected users can re-apply freely

A user whose status is rejected cannot access Webplayer, V5 Dashboard, or any management page. However, rejection is intentionally forgiving:

• Rejected users are not notified of the rejection (no rejection email is sent).
• The user can simply attempt to sign in again with the same provider. On re-attempt, the existing rejected record is reset to pending and re-enters the Site Manager's approval queue.
• This design ensures that an accidental rejection (mis-click) does not permanently block a legitimate user — they can retry without involvement from anyone.
• An Admin or Site Manager can also manually change a rejected user back to approved with any role via the dashboard.

8.7 User profile is managed by Site Manager

Users cannot edit their own profile information (display name, picture, role, Site, Group, etc.) directly through 4dist.com. All profile management is performed by the Site Manager (or Admin) on the Site Management Page. This keeps administrative control with the Site Manager and avoids inconsistencies. The original OAuth-provided name / picture is shown by default; if Site Manager overrides are needed, those will be managed via the dashboard (future feature).

8.8 Role enforcement layers

Role checks are enforced at multiple layers:

• nginx auth_request — gates the entire us.4dist.com subdomain and the /mail-reports path at the network level.
• Backend route middleware — requireApproved, requireRole(...) reject requests that don't match.
• Frontend UI — buttons/sections are hidden or disabled when the user lacks the role, but this is cosmetic only; the backend always re-checks.

Front-end role hiding (e.g., disabling the Download button for Guest) is a UX concern. The actual access decision is always enforced server-side.

8.9 Provider-identity vs Email-identity

Each (provider, provider_user_id) pair is a distinct user record in the database. Account linking by verified email is applied at sign-up time only — the records remain separate but share the same effective role/Site assignment. Future feature work may consolidate these into a single user with multiple linked providers.

9. Planned Future Changes

The following items are part of the documented end-state but are not yet (or only partially) implemented. They are recorded here so that current implementation work can be aligned with the long-term direction.

9.1 Multi-Site membership (schema migration)

Target timeline: approximately one month after the current single-Site implementation work is complete (target: late June 2026).

Current: the users table stores a single site_id and single role. A user can belong to only one Site at a time.

Planned: introduce a user_sites join table:

• user_id + site_id + role (one row per assignment)
• UNIQUE(user_id, site_id) — one role per user-Site pair
• Migration: each existing user becomes one row in user_sites; the site_id and role columns on users are then dropped.

All read/write code paths (admin/coach/site routes, /api/access/* gates, mailer notifications) need to switch to the join table after migration. Pages displaying a single "current Site context" will need a Site switcher in the navigation.

9.2 Group concept within a Site

Planned: a Site may contain multiple Groups. A Group is a sub-partition of users and videos within a Site.

• Each user assigned to a Site may belong to one or more Groups (multiple Group membership allowed within a single Site).
• Each video can be assigned to one or more Groups (and/or owned by a specific user).
• Guest role will be restricted to seeing only videos in any of their assigned Groups (or videos they own) — not all videos in the Site.
• Site Manager manages Group creation, naming, deletion, and user/video assignment within their own Site. Operator / Member / Guest themselves cannot reassign Groups.
• Group does not have its own dedicated "Group Manager" role — Site Manager is the single owner of Group operations for the Site.

9.3 In-app messaging for notifications

Current: notifications go via email (SMTP) and Teams (Workflows webhook).

Planned: in-app messaging channel — users will receive notifications directly in 4dist.com (e.g. a bell icon in the nav) for events like pending-approval status changes, role changes, Site invitations, etc. This complements (not replaces) email + Teams.

9.4 Self-service profile editing (deferred)

Currently all profile management is by Site Manager / Admin. A future enhancement may allow users to edit their own display name and profile picture, while keeping role, Site, and Group strictly under Site Manager control.

9.5 Audit log

Current: only approved_by + approved_at are stored.

Planned: a dedicated audit_log table recording every role / Site / Group / deletion action with timestamp, actor, target, before/after values. Viewable by Admin in a dedicated tab.

9.6 Apple Sign-In activation

Backend code already implements Apple Sign-In (ES256-signed client secret, form_post callback). Activation is pending Apple Developer Program organization-account approval. Once approved, set APPLE_* env values and Apple sign-in will become available with no additional code change.