Purpose and status
This is the permission target for code review and runtime testing. It is not a claim that every route has completed a formal security review.
The current app enables three school staff roles. In the database they are owner, teacher and read-only; the UI displays owner as Administrator. The future database role Student uses the product label Player Account; these are one intended role, not two. Student (Player) and Parent/Carer accounts must remain closed.
The repository and prototype use fictional demonstration data only. A role assignment or school readiness record does not authorise real student data.
Role definitions
| Role/boundary | Current status | Intended purpose |
|---|---|---|
| Administrator (owner) | Enabled | School setup, staff accounts, approval/readiness, support/correction, backups and all Teacher work for assigned schools |
| Teacher (teacher) | Enabled | Day-to-day teaching records and schedules for assigned schools |
| Read-only (read-only) | Enabled | View approved data for assigned schools; no mutation |
| Student (Player Account) | Not enabled | Future own-profile/practice access only after separate approval and implementation |
| Parent/Carer | Not enabled | Future linked-child approved information only after separate approval and implementation |
| QR profile session | Narrow public boundary, not a role | Expiring access to one scanned student's approved profile |
| Pilot email fallback | Transitional exception | Administrator-equivalent access without a secure account; must be disabled before account beta |
| Host Operator | Operating-system responsibility, not a role | Can operate SQLite, backups and service processes; must be treated as privileged |
Enforcement model
The app uses three minimum access levels:
- read — Read-only, Teacher or Administrator;
- teacher — Teacher or Administrator;
- admin — Administrator only.
Roles are active, school-specific entries in user_school_roles. The selected school is a convenience state, not authority. A server action or route must validate both the authenticated session and the target object's school.
An account can have different roles at different schools. The highest role at one school must never grant access to another school.
Current staff permission matrix
Legend: Manage = create/change/delete or approve; Use = day-to-day write; View = read only; Self = current account only; No = deny.
| Area | Administrator | Teacher | Read-only |
|---|---|---|---|
| Switch among assigned schools | View/use | View/use | View/use |
| Access an unassigned school | No | No | No |
| Global settings and readiness | Manage | No | No |
| School profile, active status and order | Manage | No | No |
| School teaching settings | Manage | View only where shown | View only where shown |
| School Release Approval | Manage | No | No |
| School Onboarding Readiness | Manage globally | No | No |
| Teacher account invitations | Manage | No | No |
| Account unlock/disable/enable and school role | Manage | No | No |
| Verification/reset link creation | Manage; copied manually | No | No |
| Support and Correction Log | Manage | No | No |
| Account deletion review queue | Manage | No | No |
| Own deletion-review request | Self | Self | Self |
| Own device sessions/sign-out | Self | Self | Self |
| Student roster/profile | Manage | Use | View |
| Current/Discontinued student status | Manage | Use | View |
| Student and historical-attendance imports | Manage | Use for the selected school | No |
| Student exports/reports | Manage if school-approved | Use if school-approved | View/download only if deliberately approved |
| Rehearsal scheduling | Manage | Use | View |
| Lesson scheduling/groups/exclusions | Manage | Use | View |
| Rehearsal and lesson check-in | Manage | Use | View |
| Historical attendance and corrections | Manage | Use | View |
| Daily Review and sign-off | Manage | Use | View |
| Cards and QR/profile-token controls | Manage | Use | View only if school-approved |
| Licence requirement setup | Manage | Use only where deliberately permitted | View |
| Student Licence progress/award | Manage | Use | View |
| Method Book global library/create/edit/import | Manage | No | View |
| School Default Method Book | Manage | Use for an authorised school | View |
| Student Method Book assignments/progress | Manage | Add existing books and mark/unmark for writable students | View |
| Own Player Profile Method Books/progress | Self | Self | Self |
| Pass-off attempts/overrides | Manage | Use within rules | View |
| Practice logs/timers/results | Manage | Use | View |
| Custom statistics | Manage | Use for approved non-sensitive data | View |
| Typed Lesson Note preparation/edit/sign-off | Manage for authorised school | Use for authorised school | Signed-off notes only |
| Backup status/create-and-verify in UI | Manage | No | No |
| Database migration/restore command | Host responsibility plus approval | No | No |
| Audit logs | View/review | View only where exposed | No unless deliberately approved |
| Subscription readiness/entitlement | Manage readiness only | View only if school allows | No |
Where the UI and server differ, the server-side minimum access requirement controls. A hidden or disabled UI control is not authorisation.
Administrator-only control plane
The following must remain Administrator-only:
- global settings and the nine-point Operations/Role Access reviews;
- school profile and release-approval decisions;
- invitations, replacement links and account access changes;
- account unlock, disable and enable;
- password-reset and email-verification link creation;
- Support and Correction Log creation/status changes;
- account deletion request resolution;
- backup status and in-app backup actions;
- global Method Book creation, editing and import;
- subscription and store/readiness governance.
Use a Teacher account for ordinary teaching where practical. Administrator should not be the default simply because it is convenient.
Teacher data plane
Teacher/Administrator may perform school-scoped daily work:
- student records within the approved field set;
- rehearsal and lesson scheduling;
- check-in, attendance and Daily Review;
- Licence progress;
- the school Default Method Book and existing global Method Book assignments/progress for students in writable schools;
- pass-off and practice records;
- cards, approved reports and exports;
- custom non-sensitive statistics;
- signed-off, name-minimised Lesson Notes.
Every write must derive or verify the target school. Student, rehearsal, lesson, attendance, schedule and support identifiers from the browser must not be accepted without a school-scoped lookup.
Read-only boundary
Read-only may view assigned-school data but must not:
- submit any data-changing server action or API request;
- create exports unless the school has deliberately approved download access;
- create invitations or copied recovery links;
- change school/global settings or readiness evidence;
- check students in, change schedules, correct attendance or award progress;
- create support/correction or resolve deletion requests;
- generate/regenerate profile access tokens;
- trigger backup, restore or migration operations.
Direct POST/PUT/PATCH/DELETE tests are required because UI hiding alone is insufficient.
Self-service account boundary
An authenticated staff account may:
- view its account and active device sessions;
- revoke its own sessions;
- sign out;
- submit one open account-deletion review request.
The current deletion request can be account-only or account-and-school-review and is audited. It does not delete data automatically. Administrators review the queue.
Invitation acceptance, sign-in, verification/reset and native handoff are narrowly scoped account flows. Their existence does not create public self-registration.
Public and special-route matrix
| Boundary | Authentication/guard target | Permitted output/action | Prohibited |
|---|---|---|---|
| /api/health | Public | Non-sensitive database/backup/deployment health only | Student, account, path, key or secret data |
| Native client config | Public | Non-sensitive client contract | Credentials or student data |
| Native auth exchange | Public-auth, rate-limited, verified-link and PKCE gates | Single account-session exchange | Role selection, replay, wrong client/verifier |
| Native current session | Account-self, no-store | Current account and assigned roles | Another account or school data |
| QR profile token exchange | Public-profile, rate-limited | Narrow expiring profile session | Teacher session or broad student lookup |
| QR security-code setup/check | Pending token-bound profile session, rate-limited | Establish or verify the current student's four-digit code and unlock that session | Another student's code/state, bypass, broad account session |
| QR student profile | One unlocked profile session | Intended student's approved profile and student-view links; signed, active, scheduled lesson/rehearsal summaries linked to that student's schedule, attendance or current group/ensemble | Other students, staff pages, unsigned/inactive/manual/unlinked summaries, teacher identifiers, raw audio or sensitive fields |
| QR practice timer/tracking | One unlocked profile session | Start/pause/complete the current student's timer; toggle the current student's tracking preference; save timer minutes as unverified | Target student supplied by client, audio detection, verified-practice claim, other practice mutation |
| QR Key Practice | One unlocked profile session | Generate notation/play-along locally and keep a profile/device-scoped tracker in localStorage | Server result write, microphone capture, claimed live tuning score, another profile's tracker |
| QR mission result | One unlocked profile session | Save a current-catalogue result bound by the server to the current student and school | Client-selected student/school, mission-order bypass, teacher-controlled progress award |
| QR sight-reading result | One unlocked profile session | Save a result bound by the server to the current student and school | Teacher profile result, client-selected student/school, assessment/licence award |
| QR avatar studio | One unlocked profile session | Read, unlock and equip fixed local music-mascot items for the current student | Photos, uploads, free text, client-selected owner/school, another inventory or negative balance |
| QR theory challenge and bonus | One unlocked profile session | Issue and server-score one expiring challenge; apply transparent daily chance/pity rules to the current student | Client-supplied score, answer key, paid chance, reroll, another profile or arbitrary prize |
| QR Tuning Darts challenge/result | One unlocked profile session | Issue one short-lived, single-use instrument-range target set and save one idempotent challenge-bound result for the current student; recompute its score from bounded device-reported pitch metadata | Client-selected target/student/school, reused or reordered challenge, duplicate submission, audio upload, teacher-controlled progress award |
| QR assessment | One unlocked profile session | View an assigned school task, save/submit own text and bounded safe-type files, download own/teacher assignment files, view marks only after release | Another assignment/student/school, raw path, unbounded/unsupported upload, pre-release mark or feedback |
| QR reward redemption | One unlocked profile session | Request today-to-one-year-ahead use of one owned available reward | Another reward/student/school, duplicate active request, direct or early redemption |
| QR linked session | One unlocked profile session | Join an active same-school teacher code, poll own participant state, receive bounded shared exercise settings, invite an accepted same-school friend | Cross-school/nonparticipant config, expired join/invite, chat/media/public directory, client-owned exercise seed |
| QR Contact request | One unlocked profile session, rate-limited | Store one bounded student-authored subject/message as a current-school support/correction request | Another school/student, private or emergency messaging claim, unbounded content, automatic external delivery; real-data use before privacy/moderation/support/retention approval |
| QR friend choice | One unlocked profile session | Add by scanned active profile token or remove only the current student's friendship row | Edit the other student's choices/profile; message another student; expose an other-school full name |
| Public-profile-only host | Environment gate | QR/profile routes only | Teacher/admin app routes |
| Lesson-note Draft preparation and edit | Teacher/Administrator for the selected school | Timetable-prepared typed Draft, teacher edit and sign-off | Microphone/audio/transcription/AI; cross-school access; unsigned Drafts for Read-only accounts |
| Lesson Note microphone/transcription routes | Guarded opt-in | Administrator/Teacher for an accessible school, only after every approval/access/environment gate and one deliberate arm for the selected teaching date | Read-only, Student, Parent/Carer, QR/public profile, wrong-school, normal-startup or unarmed requests |
Every route still needs method-by-method review. A static scanner finding a read guard does not approve a route that mutates data.
The permitted QR writes above are an allow-list, not examples. Attendance, teacher-controlled progress, Licence awards, method-book progress, schedules, notes, cards, roles, student details and every other mutation must fail from a QR profile session.
Approved group and rehearsal summary history currently derives partly from the student's current active group/ensemble membership. Membership rows do not yet record join/leave dates, so a current member can see an older signed, name-minimised summary for that same group or ensemble even if it predates their membership. Individual schedule and explicit attendance links remain precise; historical group/ensemble scoping needs join-date data and a retention decision before making a stronger claim.
School and object scoping
The following guardrails are mandatory:
- notifications are filtered to accessible schools;
- profile-scan lookups require an accessible school;
- undoing rehearsal check-in verifies the rehearsal belongs to the selected school;
- manual Student Method Book progress matches a book enabled for that student and the acting Teacher has writable access to the student's school;
- Player Method Book assignments and completion changes are derived from the authenticated account's own Player Profile rather than a browser-supplied profile identifier;
- Student profile sessions can switch between their enabled Method Books only for read-only progress viewing;
- support/correction requests are created and updated only for the selected authorised school;
- public profile sessions are tied to both student and school;
- a QR token never encodes student identity;
- Method Books remain the only intentional shared/global teaching setup area.
Cross-school denial must be tested with real route/object identifiers from a separate fictional school.
Future Student role
If implemented later, Student access should be limited to the authenticated student's:
- approved profile;
- practice tools and own approved practice entries;
- own progress summaries;
- student-view leaderboards under privacy rules;
- approved, name-minimised Lesson Note summaries.
It must not include staff records, other student profiles, teacher notes, attendance editing, scheduling changes, exports, account administration or student-to-student messaging.
Do not implement this by expanding a QR profile session into a general account.
Future Parent/Carer role
If implemented later, Parent/Carer access must require an approved, verified link to a child and should expose only approved linked-child information. It must not include:
- another student's data;
- teacher-only notes or support records;
- raw Lesson Note material;
- staff, school setup or audit data;
- timetable editing;
- broad leaderboards beyond the approved student view.
Parent/Carer access remains blocked until school approval, privacy notices, correction/deletion, support, verified accounts and safeguarding review are complete.
Least-privilege and lifecycle rules
- Assign Read-only by default when viewing is sufficient.
- Assign Teacher for active day-to-day teaching duties.
- Assign Administrator only for named setup/account/governance duties.
- Review active roles quarterly and after duty/staff changes.
- Disable access promptly; do not share accounts.
- Replace missed invitation links instead of revealing a stored token.
- Revoke sessions after suspected compromise or sensitive role changes.
- Review Host Operator, database, backup and encryption-key access separately.
- Disable the pilot email fallback before account beta after secure recovery is ready.
- Preserve access-change evidence in account_audit_logs.
The ACSC Essential Eight assessment guidance emphasises least privilege and separation of duties for backup and privileged accounts. Apply the same principle to app Administrators and Host Operators.
Audit expectations
| Change | Minimum evidence |
|---|---|
| Invitation create/cancel/accept | Actor, email, school, invitation ID, success and timestamp |
| Role/enable/disable/unlock | Actor, affected account, school, previous/new state and timestamp |
| Readiness/approval | Actor, scope, checklist/decision and timestamp |
| Support/correction | Request ID, school, type, status, resolver and timestamp |
| Deletion review | Request ID, requester, type, status, resolver and actual outcome reference |
| Attendance/progress correction | Actor, student/rehearsal where needed, previous/new value and reason |
| Backup/migration/restore | Operator, database/backup labels, verification, measured result and approval |
Audit notes must be useful but minimal and must never contain secrets or prohibited personal data.
Review and release gate
Run:
pnpm access:reviewThen complete the Access Review Checklist with separate role accounts and direct-route negative tests. Save the nine-point Role Access Review only after all Critical/High findings are closed. Re-run pnpm account-beta:check as a readiness summary.
No account beta, Student/Parent access or public registration while:
- the fallback bypass remains part of the intended access model;
- any Read-only mutation or cross-school access is possible;
- Host Operator access is unowned;
- public/QR/native boundaries have not been exercised;
- privileged changes lack adequate audit evidence;
- open Critical/High access findings remain.