Access Control & Permissions Model
ProSurvey Apps Limited (company no. 17118570) · Trust & Security Handbook
Audience: security reviewers, IT admins, procurement. Describes how identity, roles and permissions work in HousingSurvey Pro. This page also serves as the operating reference for the granular permissions model. Remaining gaps are marked planned / in progress.
Identity
Users authenticate through Firebase Auth / Identity Platform. Three sign-in paths, one identity model underneath:
- Email + password — office staff, managers, contractors with email.
- SSO (Microsoft Entra ID) — self-service OIDC or SAML federation, with SCIM 2.0 joiner/leaver provisioning for Enterprise organisations.
- Tenant username/code + passcode — field surveyors and third parties without email. These are provisioned by a tenant admin in the management dashboard; each maps to a Firebase identity under an internal alias so the same rules, claims and audit apply. Passwords are held by the identity platform, never by the application.
Multiple profiles / multi-tenancy: one person may hold accounts in several tenants (e.g. a surveyor working for two housing associations). The mobile app stores multiple tenant-scoped profiles and lets the user switch between them; email accounts can span tenants as multiple memberships. Each session is scoped to exactly one tenant at a time.
Authorisation model
Custom token claims identify the organisation context presented by a signed-in user, but they are not the sole authority for a privileged action. Firestore and Storage rules require an active membership whose current role still matches the claim. Callable functions load the active member document and current role for each request, so archiving a member or changing their role is not deferred until an old token expires.
The same checks load the member's server-written memberPermissions/{uid} document. The UI mirrors the resulting access for usable feedback; Firestore rules, Storage rules and callable checks are the enforcement boundaries and deny independently of the UI.
Role baselines
Each organisation role supplies a backwards-compatible default for every permission module. A sparse per-member override may raise or lower that default; removing an override restores the role baseline. The shared evaluator has a parity-tested server copy, and the rules and callable checks evaluate the same levels from live documents.
| Role | Scope |
|---|---|
| System admin (superadmin) | Platform operations; current TOTP/passkey proof required; cannot be created by an organisation role or module grant and cannot alter sealed evidence |
| Owner | Everything an org admin can, plus the two irreversible actions: ownership transfer and organisation deletion |
| Org admin | Full control within one organisation (settings, members, billing) except ownership transfer and org deletion |
| Manager | Day-to-day operations: work orders, scheduling, properties, evidence read/export, case notes, member list |
| Coordinator | Office staff: raises work orders, schedules visits, keeps case notes; reads evidence and dashboards — no exports, deletions, settings or member changes |
| Finance | Billing and invoices only, plus dashboards |
| Viewer | Read-only evidence and dashboards |
| Surveyor | Field-capture baseline. Evidence, properties, work orders and scheduling remain assignment-scoped even when explicitly upgraded |
| Operative | Works-only baseline for assigned remediation and photo capture. Record-bearing modules remain assignment-scoped. Free seat class; may be contractor, subcontractor or landlord staff |
Contractor is an organisation relationship, not an extra member role. A contractor organisation reaches a landlord's records only through its active grant and the relevant work-order/record scope.
Granular permissions (implemented)
An authorised administrator can tune a non-owner member from None through Module admin for each product area. Module admin is not platform system admin and cannot create owner-only or superadmin authority:
- Modules — each dashboard area and app capability is a permissionable unit (Evidence, Properties, Work orders, SOR/rates, Scheduling, Settings, Billing, Reports, etc.).
- Levels per module — e.g.
none→view→edit→admin. - Assignment — a member gets a role baseline plus optional sparse, per-module overrides. Inherit role removes the stored override.
- Scope — surveyor/operative evidence, properties, work orders and scheduling remain limited to assigned records. An explicit grant to an administrative or other non-record module can be organisation-scoped.
- Enforcement — the portal and capture app load the effective level only after the live permission document resolves. Firestore rules, Storage rules and callable functions evaluate the live role, override and required scope.
- Immediate effect — changes do not wait for a custom-claim refresh. Missing documents inherit the role baseline; malformed documents or read failures fail closed.
- Governance — owner permissions are fixed; members cannot change their own permissions; the caller cannot grant above their own effective level; every successful replacement is audit-logged.
Storage evidence paths include their survey or work-order id. Rules resolve the linked record before allowing a read or append-only image create, retain the assignment check for field identities, deny direct bundle access, and deny new writes to legacy property-keyed paths that cannot prove assignment.
Server-only surfaces
Some data is never client-writable, even by an org admin — writes happen only through audited server logic:
- organisation members / roles / permission overrides, audit events, API keys, billing;
- organisation private secrets (webhook secrets, provider config);
- evidence finalisation fields (hashes, chain sequence) — set server-side at sealing, never by a client.
Session & credential lifecycle
- Provisioning: tenant admins mint field logins and invite email users.
- Suspension / offboarding: accounts can be suspended or removed with audit.
- Remote logout: an admin can revoke a member's refresh tokens; users can revoke all their own sessions. Both server paths are audited.
- MFA: TOTP and passkeys are available. Manager+, org-admin and owner roles are gated in the apps, and platform-superadmin rules/callables require a current TOTP/passkey proof. Universal server-side step-up enforcement for ordinary manager/org-admin operations remains in progress.
Auditing
Privileged and destructive actions (member/role changes, deletions, billing, integrity events) are written as immutable audit events, queryable by org admins and retained as evidence.
Status: the identity model, role baselines, live per-member module overrides, assignment-aware Firestore/Storage/callable enforcement, remote revocation, SSO and SCIM are implemented and deployed in production and nonproduction. Ordinary manager/org-admin server-side MFA step-up remains the scoped gap described above.