laravel-rest-api
use Lomkit\Rest\Text\ScoutEngine;
use Lomkit\Rest\Text\TextSearch;
class PostResource extends Resource
{
public static string $model = Post::class;
public function text(): ?TextSearch
{
return ScoutEngine::make()->withoutPerimeter();
}
}
With laravel-rest-api 3.6 or higher installed, the package registers Lomkit\Access\Integrations\RestApi\AccessControlExtension on its own. It applies to every rest-api resource whose model has a control, and leaves the others alone: nothing to write in the resources, no perimeterQuery() that calls controlled().
The package conflicts with laravel-rest-api before 3.6, which has no extensions. The extension is named access_control.
Rows
The rows of a resource are the rows that controlledFor($user) finds for view, wherever rest-api applies a perimeter:
- searches, includes, relation filters, sorts and aggregates;
- metrics and the keys of their cache;
- the key lookups of
mutate,destroy,restore,forceDestroyand actions, the rows of queued actions and the rows read again after a write.
A guest finds no row, as with controlled(). A user that is not an Eloquent model throws InvalidRestReaderException, which names its class.
php artisan rest:check accepts a controlled resource without perimeterQuery() or #[WithoutPerimeter]: the extension provides its perimeter, shown as perimeter from access_control. It also reports a control that cannot be built. rest-api itself still reports a model without a policy: call Access::registerPolicies() or give the model a policy.
Conditions that are not access rules
Keep the conditions that are not access rules, such as a published flag, in perimeterQuery() for the SQL lists and in the perimeter of ScoutEngine for the text searches. rest-api applies both, and the extension adds its restriction to them:
use Illuminate\Contracts\Database\Eloquent\Builder;
use Lomkit\Rest\Fields\Boolean;
use Lomkit\Rest\Text\Engine\EngineQuery;
use Lomkit\Rest\Text\ScoutEngine;
use Lomkit\Rest\Text\TextSearch;
class PostResource extends Resource
{
public function perimeterQuery(Builder $query): Builder
{
return $query->where('published', true);
}
public function text(): ?TextSearch
{
return ScoutEngine::make()
->perimeter(fn (EngineQuery $query) => $query->where('published', '=', true))
->indexAttributes([Boolean::make('published')]);
}
}
Text search
rest-api builds its own Scout query, so controlled() never runs there: the extension is the access filter of these searches. A resource searched through ScoutEngine declares withoutPerimeter(), or a perimeter for its other conditions, as above.
- On the Scout
databaseandcollectiondrivers, the rows are restricted in the SQL of the search, with an exact total. - On another engine, the model uses
ControlledSearchable, and the extension keeps the documents that share a key with the reader in_accessand_boundary, ascontrolled()does. A guest or a reader that no perimeter reaches gets an empty page without calling the engine. Declare the two attributes in the index settings. - The search throws
UnsupportedRestSearchExceptionwhen the model does not useControlledSearchable, when the engine is not supported or trusted, and when the rest-api profile of the engine matches no list of strings. A boundary without a search form throwsUnsearchableBoundaryException.rest:checkreports the first two cases and the boundary, with the Scout driver of its environment.
The engine is the only barrier: rest-api loads the rows of the page by key, without the SQL restriction, so a row that a stale index still matches is shown until it is indexed again. Keep the keys fresh.
Row checks
Before the policies check rows for an ability, the extension preloads their decisions with Access::preload(), so the gates of a page cost one query per ability, not one per row and ability. It decides nothing itself: the policy still decides each row. The ability goes through abilityFor() of the control, so a business gate such as approve is preloaded too.
rest-api checks create on the class, then on the draft of each row that mutate creates. A draft is judged in memory only: a perimeter with a should() callback or an includes() hook, an unrestricted perimeter, or a ThroughParent that delegates create can grant it. A control whose perimeters are all checked in SQL refuses every creation, and so does a boundary without an in-memory form, such as a boundary class without includes().
Kept decisions
rest-api keeps the decisions of the abilities that a resource lists in authorizationCache(), filed under the updated_at of the row.
- The extension adds a hash of the decision context to their key, so a decision kept for one tenant is never read for another.
- For an ability that a
ThroughParentdelegates, it adds theupdated_atof the parent, and of each parent above it, with one query per level for the rows of a page. When a parent changes, the decisions on its children are made again. A parent withoutupdated_atkeeps no decision on its children. - A parent written with
DB::table()or insideModel::withoutTimestamps()keeps itsupdated_at, and the old decisions stay until the duration runs out. - A perimeter whose
query()reads another table, or a right that holds during a period, changes noupdated_at: leave these abilities out ofauthorizationCache(), shorten their duration, or callRest::forgetAuthorizations()when that table changes.
Columns
rest-api loads the columns of the fields and of alwaysSelect(), and a policy that reads another column throws MissingColumnException. List in alwaysSelect() the columns that the control reads in memory: the column and the read-only columns of the boundary, the columns of the should() callbacks, and updated_at for the kept decisions.
public function alwaysSelect(): array
{
return ['workspace_id', 'archived_at', 'author_id', 'updated_at'];
}
Turning it off
List the extension in disabled_extensions of config/rest.php: rest-api then leaves the rows to perimeterQuery() and the decisions to the policies alone.
'disabled_extensions' => [
\Lomkit\Access\Integrations\RestApi\AccessControlExtension::class,
],
perimeterQuery(). A resource whose perimeterQuery() was removed because the extension applied the control reads every row once the extension is disabled. rest:check then reports again every resource without a perimeter: give each of them a perimeterQuery() before you disable the extension.AccessControlExtension is final, so that no subclass can drop the restriction of the rows, the filter of the search engines or the decision context of the kept decisions. To replace the access rules of rest-api, disable it and register an extension of your own: the package then restricts nothing in rest-api, preloads no row check and adds nothing to the key of the kept decisions.
php artisan about shows whether the extension is enabled: see Cache and about.
Your own search client
Keep the access filter when you query the search engine with your own client, or feed your own index with Access::indexKeysOf() and Access::indexReaderKeys().
Testing
The InteractsWithAccess assertions prove on your test data that the levels nest, the policy and the queries agree, and the search finds what the SQL lists.