Document expiring grants and the prune command

Adds an Expiring grants section to README covering
assignRoleUntil, givePermissionToUntil, the prune command and the
expiry-propagates-from-role rule. Lists the new command in the
Artisan commands block. CHANGELOG.md gains a 1.1.0 entry
inventorying every new surface in this release.

Author: webrek

CHANGELOG.md

@@ -6,6 +6,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-05-18
+
+### Added
+- `HasRoles::assignRoleUntil($role, $expiresAt)` — grant a role
+  with an expiry timestamp.
+- `HasPermissions::givePermissionToUntil($permission, $expiresAt)` —
+  grant a permission with an expiry timestamp.
+- `permission:prune-expired` Artisan command to garbage-collect
+  expired grant subdocs from user documents, with `--dry-run` and
+  `--user-model=` options.
+- `Webrek\MongoPermission\Support\Expiry` helper centralizing
+  expiry normalization between `DateTimeInterface`, BSON
+  `UTCDateTime` and unix timestamps.
+- Composer keywords (`laravel`, `mongodb`, `permissions`, `roles`,
+  `rbac`, `acl`, `authorization`, `multi-tenant`, `wildcard`) and
+  `support.issues` / `support.source` URLs for Packagist surfacing.
+- CHANGELOG.md following Keep-a-Changelog.
+- README section comparing this package with
+  `spatie/laravel-permission`.
+- README section "Expiring grants" documenting the new API and the
+  prune command.
+
+### Changed
+- `PermissionRegistrar` slug cache now stores grant entries with
+  their expiry attached and re-filters expired entries on every
+  read. Slug arrays returned by `getUserPermissionSlugs` and
+  `getUserRoleSlugs` are unchanged in shape.
+- A role assignment's expiry propagates to every permission reached
+  through that role: when the assignment expires, those permissions
+  stop counting in `hasPermissionTo` and `getAllPermissions`.
+
 ## [1.0.0] - 2026-05-18
 
 ### Added
@@ -45,5 +76,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   teams, strict isolation, wildcards, middlewares, Blade, Gate and
   commands.
 
-[Unreleased]: https://github.com/webrek/laravel-mongo-permission/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/webrek/laravel-mongo-permission/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/webrek/laravel-mongo-permission/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/webrek/laravel-mongo-permission/releases/tag/v1.0.0

README.md

@@ -137,6 +137,38 @@ Assignments made while a team is active are scoped to that team. Reads
 honor the active team. Setting `permission.strict_team_isolation = true`
 disables the "team_id = null is global" fallback.
 
+## Expiring grants
+
+Roles and permissions can be granted with an expiry. The grant
+stays on the user document but stops counting toward checks the
+moment `now()` passes the `expires_at` timestamp — even if the
+cache was warmed before the expiry.
+
+```php
+$user->assignRoleUntil('admin', now()->addHours(2));
+$user->givePermissionToUntil('publish posts', now()->addDays(7));
+
+$user->hasRole('admin');                  // true for two hours
+$user->hasPermissionTo('publish posts');  // true for seven days
+
+// After the expiry passes:
+$user->hasRole('admin');                  // false
+```
+
+Expired subdocs are not removed automatically. Run the prune
+command on a schedule (or ad-hoc) to garbage-collect them and free
+space on user documents:
+
+```bash
+php artisan permission:prune-expired
+php artisan permission:prune-expired --dry-run
+php artisan permission:prune-expired --user-model="App\\Models\\User"
+```
+
+A role granted with an expiry propagates that expiry to every
+permission reached through the role — once the role assignment
+expires, those permissions stop counting too.
+
 ## Wildcard permissions
 
 `enable_wildcard_permission` defaults to `true`. Patterns use `.` as the
@@ -219,6 +251,7 @@ php artisan permission:create-role admin [--guard=web] [perm1 perm2 ...]
 php artisan permission:create-permission "edit articles" [--guard=web]
 php artisan permission:show [--guard=web] [--team=...]
 php artisan permission:cache-reset
+php artisan permission:prune-expired [--user-model=...] [--dry-run]
 ```
 
 ## Configuration