Integrations

laravel-rest-api

With laravel-rest-api 3.6+, AccessControlExtension applies your controls to every resource of a controlled model, its text searches and row checks included.
app/Rest/Resources/PostResource.php
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, forceDestroy and 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')]);
    }
}

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 database and collection drivers, 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 _access and _boundary, as controlled() 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 UnsupportedRestSearchException when the model does not use ControlledSearchable, 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 throws UnsearchableBoundaryException. rest:check reports 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 ThroughParent delegates, it adds the updated_at of 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 without updated_at keeps no decision on its children.
  • A parent written with DB::table() or inside Model::withoutTimestamps() keeps its updated_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 no updated_at: leave these abilities out of authorizationCache(), shorten their duration, or call Rest::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.

config/rest.php
'disabled_extensions' => [
    \Lomkit\Access\Integrations\RestApi\AccessControlExtension::class,
],
Without the extension, nothing restricts the rows of a controlled resource but its own 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.