feat: harden ABAC defaults and improve empty-read/cache-write behavior

Fix collection READ authorization to allow empty result sets for list endpoints while keeping single-resource checks strict, and add a configurable cache write-flush toggle to prevent log/flush storms during bulk operations. Default missing-policy fallback to deny, validate configured actor attribute model classes, and add warnings/tests/docs for safer policy/attribute observability.

Author: somethim

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "zennit/abac",
     "description": "Attribute-Based Access Control (ABAC) for Laravel",
-    "version": "1.0.4",
+    "version": "1.0.5",
     "type": "library",
     "license": "MIT",
     "keywords": [

config/abac.php

@@ -21,6 +21,7 @@
         'ttl' => env('ABAC_CACHE_TTL', AbacDefaults::CACHE_TTL),
         'prefix' => env('ABAC_CACHE_PREFIX', AbacDefaults::CACHE_PREFIX),
         'include_context' => env('ABAC_CACHE_INCLUDE_CONTEXT', AbacDefaults::CACHE_INCLUDE_CONTEXT),
+        'flush_on_write' => env('ABAC_CACHE_FLUSH_ON_WRITE', AbacDefaults::CACHE_FLUSH_ON_WRITE),
     ],
 
     /*
@@ -63,6 +64,7 @@
     ],
 
     'policy' => [
+        // Valid values: allow|deny
         'default_policy_behavior' => env('ABAC_DEFAULT_POLICY_BEHAVIOR', AbacDefaults::DEFAULT_POLICY_BEHAVIOR),
     ],
 

docs/CONSUMER_SETUP.md

@@ -43,10 +43,18 @@ If your models use UUID/custom PKs:
 ```dotenv
 ABAC_PRIMARY_KEY=id
 ABAC_FALLBACK_PRIMARY_KEY=_id
+ABAC_DEFAULT_POLICY_BEHAVIOR=deny
+ABAC_CACHE_FLUSH_ON_WRITE=true
 ```
 
 Set the model PK normally (`$primaryKey`, `$incrementing`, `$keyType`).
 
+`ABAC_CACHE_FLUSH_ON_WRITE` controls automatic ABAC cache invalidation on policy/check/chain writes.
+Keep it `true` for standard behavior, or set it to `false` during large bulk imports and flush cache manually after the batch.
+
+`ABAC_DEFAULT_POLICY_BEHAVIOR` controls fallback when a route is mapped to a resource but no policy matches.
+Use `deny` for fail-safe behavior (recommended), and only use `allow` when you explicitly accept permissive fallback.
+
 ## 4) Add middleware to protected routes
 
 ```php

docs/OPERATIONS.md

@@ -33,6 +33,14 @@ For strict environments, use:
 - `ABAC_CACHE_INCLUDE_CONTEXT=true`
 - `ABAC_CACHE_STORE=redis` (or `database` when Redis is unavailable)
 
+## Bulk writes and cache invalidation
+
+During large seed/import operations, frequent ABAC model writes can trigger repeated cache flushes.
+
+- Default behavior: `ABAC_CACHE_FLUSH_ON_WRITE=true` (flush after create/update/delete on ABAC models).
+- Bulk mode: set `ABAC_CACHE_FLUSH_ON_WRITE=false` for the batch window to avoid flush storms.
+- After bulk updates: re-enable write flushes and perform a single cache flush through your app service container.
+
 ## Optional metrics hooks
 
 For custom telemetry (evaluation count/latency/cache hit ratio), bind your own

docs/SECURITY_MODEL.md

@@ -21,8 +21,12 @@ This package evaluates authorization decisions (ABAC). It does not replace authe
 
 Use the hardened defaults from [Operations Guide](OPERATIONS.md).
 
+- Set `ABAC_DEFAULT_POLICY_BEHAVIOR=deny` to avoid permissive fallback when no policy matches.
+- Treat `allow` fallback as an explicit migration/rollout choice, not a long-term default.
+
 ## Operational controls
 
 - Monitor logs for `abac.policy_miss` and denied chain outcomes.
+- Monitor logs for `abac.actor_attributes_empty` to catch missing actor attribute seed/data issues.
 - Review route-to-model mappings whenever new endpoints are added.
 - Keep middleware attached only to routes with explicit auth requirements.

docs/index.md

@@ -19,7 +19,7 @@ A flexible Attribute-Based Access Control (ABAC) implementation for Laravel 12+.
 - **Widening Behavior** — Each grant adds an OR branch for additive access
 - **Idempotent Operations** — Duplicate constraints are automatically deduplicated
 - **Middleware Protection** — Route protection via `abac` middleware
-- **Cache Invalidation** — Automatic cache clearing on policy updates
+- **Cache Invalidation** — Automatic cache clearing on policy updates with optional write-flush toggle for bulk operations
 
 ## Installation
 

src/Models/Concerns/FlushesAbacCache.php

@@ -11,6 +11,10 @@ protected static function registerAbacCacheFlushHooks(): void
     {
         $flushCache = static function (): void {
             try {
+                if (! config('abac.cache.flush_on_write', true)) {
+                    return;
+                }
+
                 if (app()->bound(AbacCacheManager::class)) {
                     app(AbacCacheManager::class)->flush();
                 }

src/Services/AbacAttributeLoader.php

@@ -4,6 +4,7 @@
 
 use Exception;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Log;
 use zennit\ABAC\Models\AbacActorAdditionalAttribute;
 use zennit\ABAC\Traits\AccessesAbacConfiguration;
 
@@ -24,6 +25,8 @@
      */
     public function loadAllActorAttributes(Model $actor): Model
     {
+        $this->validateConfiguredActorModelClass();
+
         $actorId = $actor->getKey();
 
         if (is_null($actorId)) {
@@ -45,11 +48,40 @@ private function loadAdditionalActorAttributes(string|int $id): array
     {
         $attributes = AbacActorAdditionalAttribute::where('_id', $id)->get();
 
+        if ($attributes->isEmpty() && ! AbacActorAdditionalAttribute::query()->exists()) {
+            Log::warning('ABAC actor additional attributes table is empty.', [
+                'event' => 'abac.actor_attributes_empty',
+            ]);
+        }
+
         $resolved = [];
         foreach ($attributes as $attribute) {
             $resolved[$attribute->key] = $attribute->value;
         }
 
         return $resolved;
     }
+
+    /**
+     * @throws Exception
+     */
+    private function validateConfiguredActorModelClass(): void
+    {
+        $actorModelClass = $this->getActorAdditionalAttributes();
+
+        if (! class_exists($actorModelClass)) {
+            throw new Exception(sprintf(
+                'Configured ABAC actor model class "%s" does not exist.',
+                $actorModelClass
+            ));
+        }
+
+        if (! is_subclass_of($actorModelClass, Model::class)) {
+            throw new Exception(sprintf(
+                'Configured ABAC actor model class "%s" must extend %s.',
+                $actorModelClass,
+                Model::class
+            ));
+        }
+    }
 }

src/Services/AbacService.php

@@ -13,6 +13,7 @@
 use zennit\ABAC\DTO\AccessContext;
 use zennit\ABAC\DTO\AccessResult;
 use zennit\ABAC\DTO\PermissionGrant;
+use zennit\ABAC\Enums\PolicyMethod;
 use zennit\ABAC\Logging\AbacAuditLogger;
 use zennit\ABAC\Models\AbacChain;
 use zennit\ABAC\Services\Evaluators\AbacChainEvaluator;
@@ -233,6 +234,10 @@ private function _evaluate(AccessContext $context): AccessResult
         $resourceQuery = $this->evaluator->apply($context->resource, $chain, $context);
         $allowed = $resourceQuery->exists();
 
+        if (! $allowed && $this->isCollectionReadRequest($context)) {
+            $allowed = true;
+        }
+
         $this->logger->logChainOutcome($context, $allowed, $policy->id, $chain->id);
 
         return new AccessResult(
@@ -243,6 +248,60 @@ private function _evaluate(AccessContext $context): AccessResult
         );
     }
 
+    private function isCollectionReadRequest(AccessContext $context): bool
+    {
+        if ($context->method !== PolicyMethod::READ) {
+            return false;
+        }
+
+        $model = $context->resource->getModel();
+        $primaryKeyCandidates = $this->getPrimaryKeyCandidates($model);
+        $primaryKeyColumns = array_values(array_unique(array_merge(
+            $primaryKeyCandidates,
+            array_map(
+                static fn (string $key): string => $model->qualifyColumn($key),
+                $primaryKeyCandidates,
+            ),
+        )));
+
+        return ! $this->queryHasPrimaryKeyConstraint($context->resource->getQuery()->wheres, $primaryKeyColumns);
+    }
+
+    /**
+     * @param  array<int, mixed>  $wheres
+     * @param  array<int, string>  $primaryKeyColumns
+     */
+    private function queryHasPrimaryKeyConstraint(array $wheres, array $primaryKeyColumns): bool
+    {
+        foreach ($wheres as $where) {
+            if (! is_array($where)) {
+                continue;
+            }
+
+            $column = $where['column'] ?? null;
+
+            if (is_string($column) && in_array($column, $primaryKeyColumns, true)) {
+                return true;
+            }
+
+            if (($where['type'] ?? null) !== 'Nested') {
+                continue;
+            }
+
+            $nested = $where['query'] ?? null;
+
+            $nestedWheres = is_object($nested) && property_exists($nested, 'wheres')
+                ? ($nested->wheres ?? [])
+                : [];
+
+            if ($this->queryHasPrimaryKeyConstraint($nestedWheres, $primaryKeyColumns)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private function makeCacheKey(AccessContext $context): string
     {
         return $this->cacheKeyStrategy->make($context, $this->getCacheIncludeContext());

src/Support/AbacDefaults.php

@@ -14,6 +14,8 @@ final class AbacDefaults
 
     public const true CACHE_INCLUDE_CONTEXT = true;
 
+    public const true CACHE_FLUSH_ON_WRITE = true;
+
     public const true LOGGING_ENABLED = true;
 
     public const string LOG_CHANNEL = 'stack';
@@ -30,7 +32,7 @@ final class AbacDefaults
 
     public const string FALLBACK_PRIMARY_KEY = '_id';
 
-    public const string DEFAULT_POLICY_BEHAVIOR = 'allow';
+    public const string DEFAULT_POLICY_BEHAVIOR = 'deny';
 
     public const false ALLOW_IF_UNMATCHED_ROUTE = false;
 
@@ -47,6 +49,7 @@ public static function envVariables(): array
             'ABAC_CACHE_TTL' => self::CACHE_TTL,
             'ABAC_CACHE_PREFIX' => self::CACHE_PREFIX,
             'ABAC_CACHE_INCLUDE_CONTEXT' => self::CACHE_INCLUDE_CONTEXT,
+            'ABAC_CACHE_FLUSH_ON_WRITE' => self::CACHE_FLUSH_ON_WRITE,
             'ABAC_LOGGING_ENABLED' => self::LOGGING_ENABLED,
             'ABAC_LOG_CHANNEL' => self::LOG_CHANNEL,
             'ABAC_DETAILED_LOGGING' => self::DETAILED_LOGGING,