Boundaries
A condition on every row
A tenant, a workspace or a company is not one more perimeter: it is a condition that every row must meet, whatever the perimeter that grants it. Declare it once in the boundary() method of the control:
use Lomkit\Access\Boundaries\Boundary;
protected function boundary(): Boundary
{
return Boundary::where('workspace_id', fn (User $user) => $user->current_workspace_id);
}
The boundary applies as an AND around the perimeters:
- in the controlled queries and in the policy alike, for every ability;
- before the levels: a user reaches the level of their perimeters, inside their workspace;
- even for an unrestricted perimeter: an administrator who sees every post sees every post of their workspace.
So the perimeters never repeat the condition, and none of them can forget it. Without boundary(), a control has no boundary, as with Boundary::none().
Boundary::where()
Boundary::where($column, $readerValue) keeps the rows whose column equals the value that the closure reads from the reader, an int or a string. The same declaration gives the SQL of the controlled queries and the check of the policy, in memory, without a query.
The boundary fails closed:
- A reader value of
null, such as a user without a current workspace, closes the boundary: the user reads no row, and the policy refuses every ability,createincluded. The SQL never compares withIS NULL. - A reader whose type the closure does not accept, such as an API client for
fn (User $user), is refused the same way. - Any other value than an int, a string or
nullthrowsInvalidBoundaryValueException.
Read-only rows
Boundary::where(...)->readOnlyWhenNotNull($column) keeps a row readable while the column is not null, and refuses it to every other ability. The method exists only on the boundary that Boundary::where() returns: for another boundary, write a boundary class whose scope() and includes() refuse the abilities other than view on such rows.
protected function boundary(): Boundary
{
return Boundary::where('workspace_id', fn (User $user) => $user->current_workspace_id)
->readOnlyWhenNotNull('archived_at');
}
An archived post stays in controlled() and its view is granted, but update, delete and business abilities such as approve are refused, and controlled('update') leaves it out.
Refusals
The policy tells two refusals of the boundary apart:
| Code | When | Status |
|---|---|---|
outside_boundary | The row is outside the boundary for this ability, but the user may still view it, such as an archived post | 403 |
not_found | The boundary also refuses view, such as a post of another workspace | 404 |
A row of another workspace answers like a row that does not exist, so its existence is never revealed. See Policies.
Boundary classes
A condition that one column cannot express is a class that extends Lomkit\Access\Boundaries\Boundary:
namespace App\Access\Boundaries;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use Lomkit\Access\AccessContext;
use Lomkit\Access\Boundaries\Boundary;
class TeamBoundary extends Boundary
{
protected function scope(Builder $query, AccessContext $context): void
{
$reader = $context->reader();
$query->whereIn('team_id', $reader instanceof User ? $reader->teams()->select('teams.id') : []);
if (! $context->ability()->is('view')) {
$query->where('locked', false);
}
}
}
protected function boundary(): Boundary
{
return new TeamBoundary;
}
scope()is required: the condition in SQL, for the controlled queries. It receives theAccessContext, with the reader and the ability. A join throwsJoinInPerimeterException: usewhereHas()or anexistssubquery.includes(Model $row, AccessContext $context): bool, optional, checks a row in memory. Without it, the policy checks the boundary with oneexistsquery on the row, even for an unrestricted perimeter, and refuses every draft, since a row about to be created is not in the database.admits(AccessContext $context): bool, optional, is the boundary without a row. When it returnsfalse, the reader reaches nothing for that ability:controlled()lists no row, and the policy refuses withno_perimeter,viewAnyandcreateincluded.
boundary() follows the rule of perimeters(): it is built once per process, so it never reads the user, the request or the tenant while it builds the boundary. Read them in scope() and includes(), from the context. See Controls.
Good to know
- A controlled search applies the boundary too:
Boundary::where()gives its search keys, and a boundary class declares them in asearchKeys()method. See Search overview. - A
Gate::before()callback that returnstruegrants before any policy runs, so it bypasses the boundary too, as it bypasses every policy in Laravel. - The boundary holds one value per reader. When one list spans several brands or companies, the brand belongs to the perimeters, not to the boundary: see Several brands.
Levels
Levels::of() declares a hierarchy of perimeters, widest first, where only the highest level a user reaches applies. Perimeters outside a group add up.
Parents
ThroughParent gives a child row the access of its parent, such as a comment that whoever may view its post may view, through the control of the parent.