Privileged route policy
A privileged route must establish the caller, the operation’s authority and the target resource scope before business reads, changes or external effects. Service-role database access bypasses browser RLS, so the route cannot rely on the originating page, supplied IDs or a capability alone.
Trust boundaries connects these ordered checks to SQL, portal audiences and provider effects.
The API also has dedicated public-token, webhook and inter-company flows. Those use their own explicit admission policy. They are not exceptions that make an unclassified endpoint safe. Caller authority explains the shared verified identity foundation. Application data paths compares this boundary with direct browser operations.
Ordered checks
Section titled “Ordered checks”flowchart TD Input[Request and declared input] --> Identity[Accepted caller or dedicated token policy] Identity --> Context[Selected company or admitted resource context] Context --> Capability[Required capability and actor condition] Capability --> Resource[Company ownership and relationship] Resource --> Domain[Version, publication and domain constraints] Domain --> Work[Privileged read, RPC or provider action]
require_authenticated verifies the bearer and resolves live memberships. active_tenant refuses a missing internal selection. capability_guard requires every listed capability before the handler body. staff_capability_guard additionally checks principal-staff context, excluding subcontractor companies. Authorization reads themselves may use the service-role client; the ordering requirement concerns admitted business work.
A handler must then establish the target. get_or_404 filters by the requested primary key and company, optionally excluding soft-deleted rows. Dedicated portal helpers can establish a different resource-specific company/person context. The resource check must precede provider calls, storage retrieval and other privileged business work.
Metadata and enforcement
Section titled “Metadata and enforcement”| Mechanism | What it provides | What the reviewer still must trace |
|---|---|---|
| Capability dependency | Runtime permission check and metadata | Exact resource admission and domain conditions |
route_security decorator |
Declarative category/capability metadata | The decorator itself only sets attributes; it performs no authorization |
| Endpoint-security catalogue | Method/path and declared policy inventory | Actual dependency/handler/service behaviour |
| Self/resource-scoped marker | Classification for a dedicated flow | Fail-closed authentication and exact target relationship |
| Public retired route | Explicit 410 containment | No database or effect before refusal |
| Platform policy | Explicit platform operation authority | Selected resource/company scope and restrictions outside capability bypass |
The route-policy tooling and structural tests make missing or inconsistent declarations visible. A route list or metadata pass is not proof of row-level scope for every endpoint. Capabilities and resource permission must both be tested. A useful behavioural test gives the caller a valid capability in A, requests B’s resource and asserts that the RPC/provider effect did not occur.
Customer and staff examples
Section titled “Customer and staff examples”For a synthetic purchase-cost save, the dependency requires principal staff with invoices:read and invoices:update. The handler fetches the invoice in the active company and resolves its staff actor before calling the allocation RPC with revision and source fingerprint. A foreign invoice is refused before allocation work.
A customer project operation uses require_customer_project, backed by the shared SQL admission projection. The admitted pair may differ from the office workspace. Direct-project contact permits that project but does not grant customer-wide recipient edits. A generic active-company helper must not replace this resource policy. Customer access owns the stronger conditions.
Failure and evidence limits
Section titled “Failure and evidence limits”Missing/invalid identity, missing company, insufficient authority, absent-in-scope resource and stale review produce different responses. Do not turn a refusal into an empty success or retry with a privileged credential. Error diagnosis describes the caller’s next action.
The sources and deterministic tests establish named checks with substituted dependencies. Actual token/RLS suites and operation-specific shared receipts remain separate. This article defines review obligations and inspected examples without certifying every endpoint or all external outcomes.