Skip to content

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.

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.

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.

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.

Two project operations show why permission and resource scope are separate:

  • GET /api/projects/{pk_project}/completion-readiness requires projects:read.
  • POST /api/projects/{pk_project}/complete requires projects: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]
The project API checks operation permission and record ownership before reading evidence or changing 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.

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 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.

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.