Capabilities and resource access
A capability permits a class of operation, such as reading projects or completing a project. It does not identify which records the caller may use. Toolora combines verified identity, company context and the operation’s resource checks before privileged business work. A caller who can complete projects in company A does not thereby gain authority over a project owned by company B.
Authorization layers
Section titled “Authorization layers”| Layer | Reviewed mechanism | What it establishes |
|---|---|---|
| Browser presentation | Route guards and controls use the verified application’s memberships and capabilities | Which interface the application renders |
| API operation permission | FastAPI dependencies check active company and required capabilities | Whether the handler may start business work |
| API resource scope | Handler queries identify the requested record and its company or authorized relationship | Whether that operation may use this record |
| Direct database access | Caller-context views, table privileges and row-level security (RLS) | Which rows a database operation can read or change |
Browser checks do not constrain a separately constructed HTTP or database request. Service-role queries bypass RLS. Their handlers must therefore establish scope explicitly. API policy and database policy protect their respective paths.
Capability sources and role changes
Section titled “Capability sources and role changes”The API reconstructs memberships from current records. A person receives a role
through person_tenant_roles; tenant_roles, role_capabilities and capabilities
connect that role to capability codes. Capability authority belongs to the
company membership, not to a role name displayed in the browser.
caller_has_capability calls the service-only actor_has_capability RPC, whose
live projection binds person, company and role grant. It excludes inactive or
deleted people/companies, revoked grants and inactive roles/capabilities.
require_capability returns 403 when the code is absent, subject to the selected
platform exception below. Browser-supplied capability lists are not authoritative.
Current grants can affect the next check before the browser refreshes its display.
The SQL helper uses that same actor projection. Both paths still require the operation’s own resource checks; see API and SQL differences.
Browser and API guards
Section titled “Browser and API guards”RequireCapability renders its children when the active membership includes the
code or the verified identity is a platform administrator. Otherwise it redirects
to /. Project list/detail routes sit inside RequirePrincipalStaff and require
projects:read. That outer guard excludes subcontractor-company staff even when
they are staff in their own company. These presentation rules do not add a staff
check to every API operation.
capability_guard(code, ...) is an enforcing API dependency. It requires an active
company, then checks all supplied codes before entering the handler.
staff_capability_guard additionally requires principal staff, unless the caller
has the platform-administrator exception. An ordinary staff flag alone does not
supply every capability. Missing company context produces 400, including for a
platform administrator using these guards.
route_security is different: it attaches metadata for route-policy tooling.
It does not authenticate or authorize a request. The checker compares the route
graph with endpoint-security.json, validates classifications and capability
catalogue references, and checks that named test files exist. That structural
check does not establish that each record-level deny case has been executed.
Project read and completion
Section titled “Project read and completion”Two project operations show why permission and resource scope are separate:
GET /api/projects/{pk_project}/completion-readinessrequiresprojects:read.POST /api/projects/{pk_project}/completerequiresprojects:write.
Both use _request_tenant, which takes the verified caller’s active company.
An optional X-Tenant-Id header may assert the same value; a different value is
403. The header cannot select another company. _get_project then uses
get_or_404 to query by project ID and company, excluding deleted projects.
An absent or foreign-company project returns 404 before evidence reads or updates.
These two routes use the capability guard, not the additional principal-staff guard.
After that lookup, the read operation loads operational evidence filtered by project and owning company and returns readiness plus blockers. The write operation rechecks the evidence. Open work or unsettled review can produce 409 even for an authorized caller. Completion changes status and supplies an actual end date when absent. Its update repeats the company/project filters and matches the previous status; no matching row produces a conflict. An already-completed project returns an acknowledgement without a new transition.
flowchart TD
Caller[Verified API caller] --> Cap{Required capability}
Cap -->|Missing| Deny[403]
Cap -->|Present or administrator exception| Project{Project in active company}
Project -->|Absent or foreign| Missing[404]
Project -->|Found and not deleted| Operation{Requested operation}
Operation -->|Read| Read[Load scoped evidence and return readiness]
Operation -->|Complete| Ready{Operational evidence settled}
Ready -->|No| Conflict[409]
Ready -->|Yes| Update[Conditional project status update]
Update --> Result[200 on success or 409 on changed status]
For a synthetic caller in company A, the reviewed decisions are:
| Request and condition | Result |
|---|---|
Read A’s project with projects:read |
200 with readiness and blockers, even when completion is blocked |
Complete A’s ready project with projects:write |
200 and the scoped status change |
| Complete without the required code | 403 before handler work |
| Complete B’s project with A’s write permission | 404; B’s status is unchanged |
| Complete A’s project with open work | 409; the status is unchanged |
The business checks are distinct from authorization. This sequence does not claim one transaction covering every evidence read or every concurrent child change. Planning, execution and review owns the wider workflow.
Direct project access under RLS
Section titled “Direct project access under RLS”useProject queries v_project_with_customer using the project ID, active company
and non-deleted filter. The current view declares security_invoker=true, so
underlying access uses the caller’s privileges and policies. The hook’s filters
and company-scoped query key
do not replace those policies.
Selected projects policies illustrate this separate path:
| Policy | Reviewed condition |
|---|---|
projects_read_tenant |
Active-company match and projects:read, or SQL platform-administrator status |
projects_insert |
New row belongs to the active company and caller has projects:write |
projects_update |
Existing row belongs to the active company and caller has projects:write; the resulting row must still belong to that company |
UPDATE also needs SELECT access. Other permissive read policies allow specific
customer/contact paths and a published-worker-project path. A failure of
projects_read_tenant alone therefore does not prove a row is invisible. The
worker policy was replaced by the publication migration; reading only the baseline
would miss that condition. The complete
customer and
assignment rules remain separate topics.
A filtered-out read/update can return no rows, while an insert or check failure can raise a database error. These are not the API’s universal 403/404 contract. Supabase’s RLS reference explains the underlying policy model.
API and SQL differences
Section titled “API and SQL differences”API identity, capability RPCs, token issuance and SQL helpers now share the live
actor rules. Both API and SQL require a live person/company and current eligible
role grants. Their platform-admin predicate uses the selected trusted platform
company, a current platform:admin grant and no impersonation. An administrator
membership in a different, unselected company is insufficient; editable company
type does not grant platform authority.
That alignment does not merge resource policy. The API’s service-role client needs explicit route scope checks. Direct SQL combines command-specific policies, including explicit administrator branches where present. The project handlers above still filter their resource to the selected company. SQL project INSERT and UPDATE also retain their row-company predicates; the capability exception does not erase them. A current actor is not permission to read an arbitrary project, message or attachment.
The November 17 actor release replaces the former activation/admin inconsistency. Portal admission, inbox participants, effective assignment and message/Storage policies still have path-specific conditions. See conversation audiences for a concrete comparison. Neither path guarantees cancellation of an in-flight request or recall of an issued file URL after authority changes.
Verification scope
Section titled “Verification scope”Current actor rules are source-reviewed against the November 17 release. Executed results below refer to the earlier named documentation checks; the current delivery PR records newly executed checks and reused release evidence.
| Existing evidence | What this delivery establishes |
|---|---|
test_capability_guard.py |
Executed: permission refusal before handler effects, allowed calls, administrator exception and principal-staff restrictions |
test_invite_capability_honours_revocation.py |
Executed: live versus revoked/inactive role/person records through a filtering synthetic client |
test_project_completion_route.py |
Executed: scoped completion, business refusal and foreign-company 404 with unchanged status; its harness bypasses the capability lookup |
test_route_security_policy.py |
Executed: selected dependency/metadata boundaries and retired-route containment; not a complete resource audit |
test_inter_tenant.py |
Executed: a declared inter-company grant can allow/refuse its named operation; this is separate from ordinary company capability scope |
RouteGuards.test.tsx |
Executed: browser rendering and redirects with mocked identity |
test_cross_tenant_isolation.py, test_capability_policy_contract.py |
Inspected only: database isolation/revocation cases and policy-to-capability catalogue checks |
The project harness tests resource scope while the guard tests permission ordering separately. They do not constitute one end-to-end Auth/API/database run. The executed commands and results are recorded in PR #648. Live RLS execution, concurrent permission changes and the full portal/MCP permission matrices remain outside this article’s review scope.