From e05a933b01207d815ea7d5e8ea9fecdce37f927b Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Tue, 23 Jun 2026 18:55:57 +0200 Subject: [PATCH 1/3] feat(share): add ShareReviewAccessCheckEvent to OCP public API Introduces OCP\Share\Events\ShareReviewAccessCheckEvent as the canonical authorization gate event for ShareReview sources. The event carries the source name and share ID for listener context, implements deny-wins semantics, and stops propagation immediately on denial. Assisted-by: ClaudeCode:claude-sonnet-4-6 Signed-off-by: Andy Scherzinger --- lib/composer/composer/autoload_classmap.php | 1 + lib/composer/composer/autoload_static.php | 1 + .../Events/ShareReviewAccessCheckEvent.php | 130 ++++++++++++++++++ .../ShareReviewAccessCheckEventTest.php | 96 +++++++++++++ 4 files changed, 228 insertions(+) create mode 100644 lib/public/Share/Events/ShareReviewAccessCheckEvent.php create mode 100644 tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php index 83b5dbeb66a9e..cd443d37a6798 100644 --- a/lib/composer/composer/autoload_classmap.php +++ b/lib/composer/composer/autoload_classmap.php @@ -854,6 +854,7 @@ 'OCP\\Share\\Events\\ShareDeletedEvent' => $baseDir . '/lib/public/Share/Events/ShareDeletedEvent.php', 'OCP\\Share\\Events\\ShareDeletedFromSelfEvent' => $baseDir . '/lib/public/Share/Events/ShareDeletedFromSelfEvent.php', 'OCP\\Share\\Events\\ShareMovedEvent' => $baseDir . '/lib/public/Share/Events/ShareMovedEvent.php', + 'OCP\\Share\\Events\\ShareReviewAccessCheckEvent' => $baseDir . '/lib/public/Share/Events/ShareReviewAccessCheckEvent.php', 'OCP\\Share\\Events\\ShareTransferredEvent' => $baseDir . '/lib/public/Share/Events/ShareTransferredEvent.php', 'OCP\\Share\\Events\\VerifyMountPointEvent' => $baseDir . '/lib/public/Share/Events/VerifyMountPointEvent.php', 'OCP\\Share\\Exceptions\\AlreadySharedException' => $baseDir . '/lib/public/Share/Exceptions/AlreadySharedException.php', diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php index 1b0383a23142e..006dcf3dbe076 100644 --- a/lib/composer/composer/autoload_static.php +++ b/lib/composer/composer/autoload_static.php @@ -895,6 +895,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 'OCP\\Share\\Events\\ShareDeletedEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareDeletedEvent.php', 'OCP\\Share\\Events\\ShareDeletedFromSelfEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareDeletedFromSelfEvent.php', 'OCP\\Share\\Events\\ShareMovedEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareMovedEvent.php', + 'OCP\\Share\\Events\\ShareReviewAccessCheckEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareReviewAccessCheckEvent.php', 'OCP\\Share\\Events\\ShareTransferredEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareTransferredEvent.php', 'OCP\\Share\\Events\\VerifyMountPointEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/VerifyMountPointEvent.php', 'OCP\\Share\\Exceptions\\AlreadySharedException' => __DIR__ . '/../../..' . '/lib/public/Share/Exceptions/AlreadySharedException.php', diff --git a/lib/public/Share/Events/ShareReviewAccessCheckEvent.php b/lib/public/Share/Events/ShareReviewAccessCheckEvent.php new file mode 100644 index 0000000000000..8689d1ecc2316 --- /dev/null +++ b/lib/public/Share/Events/ShareReviewAccessCheckEvent.php @@ -0,0 +1,130 @@ +dispatchTyped($event); + * if (!$event->isHandled() || !$event->isGranted()) { + * return false; // default-deny: no listener means no access + * } + * + * Semantics: + * - Default-deny: an unhandled event blocks the deletion. + * - Deny wins: once denyAccess() is called, further grantAccess() calls are + * ignored and propagation is stopped immediately. + * - Multiple grants are harmless; the last listener to deny is authoritative. + * + * @since 34.0.2 + */ +#[Consumable(since: '34.0.2')] +class ShareReviewAccessCheckEvent extends Event { + + private bool $handled = false; + private bool $granted = false; + private ?string $reason = null; + + /** + * @param string $sourceName Stable, non-translated identifier for the app + * registering the share source (e.g. 'Deck', 'Tables'). + * @param string $shareId App-internal identifier of the share being deleted. + * + * @since 34.0.2 + */ + public function __construct( + private readonly string $sourceName, + private readonly string $shareId, + ) { + parent::__construct(); + } + + /** + * Stable, non-translated identifier of the app that owns this share source. + * + * @since 34.0.2 + */ + public function getSourceName(): string { + return $this->sourceName; + } + + /** + * App-internal identifier of the share being deleted. + * + * @since 34.0.2 + */ + public function getShareId(): string { + return $this->shareId; + } + + /** + * Grant access to delete the share. + * + * Has no effect if denyAccess() was already called on this event — deny wins. + * + * @since 34.0.2 + */ + public function grantAccess(): void { + if ($this->handled && !$this->granted) { + return; // deny wins — a prior denyAccess() cannot be escalated to a grant + } + $this->handled = true; + $this->granted = true; + } + + /** + * Deny access and provide a human-readable reason. + * + * Stops event propagation immediately — no further listeners will run. + * + * @since 34.0.2 + */ + public function denyAccess(string $reason): void { + $this->handled = true; + $this->granted = false; + $this->reason = $reason; + $this->stopPropagation(); + } + + /** + * Whether any listener has responded to this event. + * + * @since 34.0.2 + */ + public function isHandled(): bool { + return $this->handled; + } + + /** + * Whether access was granted. + * + * @since 34.0.2 + */ + public function isGranted(): bool { + return $this->granted; + } + + /** + * Human-readable denial reason, or null if access was granted or the event + * has not been handled yet. + * + * @since 34.0.2 + */ + public function getReason(): ?string { + return $this->reason; + } +} diff --git a/tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php b/tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php new file mode 100644 index 0000000000000..fad7dbae01401 --- /dev/null +++ b/tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php @@ -0,0 +1,96 @@ +makeEvent(); + + $this->assertFalse($event->isHandled()); + $this->assertFalse($event->isGranted()); + $this->assertNull($event->getReason()); + } + + public function testConstructorPayload(): void { + $event = new ShareReviewAccessCheckEvent('Deck', '99'); + + $this->assertSame('Deck', $event->getSourceName()); + $this->assertSame('99', $event->getShareId()); + } + + public function testGrantAccess(): void { + $event = $this->makeEvent(); + $event->grantAccess(); + + $this->assertTrue($event->isHandled()); + $this->assertTrue($event->isGranted()); + $this->assertNull($event->getReason()); + $this->assertFalse($event->isPropagationStopped()); + } + + public function testDenyAccess(): void { + $event = $this->makeEvent(); + $event->denyAccess('not in group'); + + $this->assertTrue($event->isHandled()); + $this->assertFalse($event->isGranted()); + $this->assertSame('not in group', $event->getReason()); + } + + public function testDenyStopsPropagation(): void { + $event = $this->makeEvent(); + $event->denyAccess('no access'); + + $this->assertTrue($event->isPropagationStopped()); + } + + public function testGrantDoesNotStopPropagation(): void { + $event = $this->makeEvent(); + $event->grantAccess(); + + $this->assertFalse($event->isPropagationStopped()); + } + + public function testGrantThenDenyIsDenied(): void { + $event = $this->makeEvent(); + $event->grantAccess(); + $event->denyAccess('revoked'); + + $this->assertFalse($event->isGranted()); + $this->assertSame('revoked', $event->getReason()); + $this->assertTrue($event->isPropagationStopped()); + } + + public function testDenyThenGrantRemainesDenied(): void { + $event = $this->makeEvent(); + $event->denyAccess('not allowed'); + $event->grantAccess(); // must be ignored — deny wins + + $this->assertFalse($event->isGranted()); + $this->assertSame('not allowed', $event->getReason()); + } + + public function testMultipleGrantsAreIdempotent(): void { + $event = $this->makeEvent(); + $event->grantAccess(); + $event->grantAccess(); + + $this->assertTrue($event->isGranted()); + $this->assertFalse($event->isPropagationStopped()); + } +} From fc10be24d455cb366ba6fce33a06ba9e38e43ebb Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Thu, 2 Jul 2026 22:11:59 +0200 Subject: [PATCH 2/3] feat(share): move share-review source interface and events to OCP\Share\ShareReview Assisted-by: Claude Code:claude-fable-5 Signed-off-by: Andy Scherzinger --- lib/composer/composer/autoload_classmap.php | 4 +- lib/composer/composer/autoload_static.php | 4 +- .../Events/ShareReviewAccessCheckEvent.php | 2 +- .../Share/ShareReview/IShareReviewSource.php | 71 +++++++++++++++++++ .../RegisterShareReviewSourceEvent.php | 46 ++++++++++++ .../ShareReviewAccessCheckEventTest.php | 4 +- .../RegisterShareReviewSourceEventTest.php | 65 +++++++++++++++++ 7 files changed, 191 insertions(+), 5 deletions(-) rename lib/public/Share/{ => ShareReview}/Events/ShareReviewAccessCheckEvent.php (98%) create mode 100644 lib/public/Share/ShareReview/IShareReviewSource.php create mode 100644 lib/public/Share/ShareReview/RegisterShareReviewSourceEvent.php rename tests/lib/Share20/{ => ShareReview}/Events/ShareReviewAccessCheckEventTest.php (96%) create mode 100644 tests/lib/Share20/ShareReview/RegisterShareReviewSourceEventTest.php diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php index cd443d37a6798..33c6e2254bd44 100644 --- a/lib/composer/composer/autoload_classmap.php +++ b/lib/composer/composer/autoload_classmap.php @@ -854,7 +854,6 @@ 'OCP\\Share\\Events\\ShareDeletedEvent' => $baseDir . '/lib/public/Share/Events/ShareDeletedEvent.php', 'OCP\\Share\\Events\\ShareDeletedFromSelfEvent' => $baseDir . '/lib/public/Share/Events/ShareDeletedFromSelfEvent.php', 'OCP\\Share\\Events\\ShareMovedEvent' => $baseDir . '/lib/public/Share/Events/ShareMovedEvent.php', - 'OCP\\Share\\Events\\ShareReviewAccessCheckEvent' => $baseDir . '/lib/public/Share/Events/ShareReviewAccessCheckEvent.php', 'OCP\\Share\\Events\\ShareTransferredEvent' => $baseDir . '/lib/public/Share/Events/ShareTransferredEvent.php', 'OCP\\Share\\Events\\VerifyMountPointEvent' => $baseDir . '/lib/public/Share/Events/VerifyMountPointEvent.php', 'OCP\\Share\\Exceptions\\AlreadySharedException' => $baseDir . '/lib/public/Share/Exceptions/AlreadySharedException.php', @@ -876,6 +875,9 @@ 'OCP\\Share\\IShareProviderSupportsAccept' => $baseDir . '/lib/public/Share/IShareProviderSupportsAccept.php', 'OCP\\Share\\IShareProviderSupportsAllSharesInFolder' => $baseDir . '/lib/public/Share/IShareProviderSupportsAllSharesInFolder.php', 'OCP\\Share\\IShareProviderWithNotification' => $baseDir . '/lib/public/Share/IShareProviderWithNotification.php', + 'OCP\\Share\\ShareReview\\Events\\ShareReviewAccessCheckEvent' => $baseDir . '/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php', + 'OCP\\Share\\ShareReview\\IShareReviewSource' => $baseDir . '/lib/public/Share/ShareReview/IShareReviewSource.php', + 'OCP\\Share\\ShareReview\\RegisterShareReviewSourceEvent' => $baseDir . '/lib/public/Share/ShareReview/RegisterShareReviewSourceEvent.php', 'OCP\\Snowflake\\ISnowflakeDecoder' => $baseDir . '/lib/public/Snowflake/ISnowflakeDecoder.php', 'OCP\\Snowflake\\ISnowflakeGenerator' => $baseDir . '/lib/public/Snowflake/ISnowflakeGenerator.php', 'OCP\\Snowflake\\Snowflake' => $baseDir . '/lib/public/Snowflake/Snowflake.php', diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php index 006dcf3dbe076..f311c68dc8668 100644 --- a/lib/composer/composer/autoload_static.php +++ b/lib/composer/composer/autoload_static.php @@ -895,7 +895,6 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 'OCP\\Share\\Events\\ShareDeletedEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareDeletedEvent.php', 'OCP\\Share\\Events\\ShareDeletedFromSelfEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareDeletedFromSelfEvent.php', 'OCP\\Share\\Events\\ShareMovedEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareMovedEvent.php', - 'OCP\\Share\\Events\\ShareReviewAccessCheckEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareReviewAccessCheckEvent.php', 'OCP\\Share\\Events\\ShareTransferredEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareTransferredEvent.php', 'OCP\\Share\\Events\\VerifyMountPointEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/VerifyMountPointEvent.php', 'OCP\\Share\\Exceptions\\AlreadySharedException' => __DIR__ . '/../../..' . '/lib/public/Share/Exceptions/AlreadySharedException.php', @@ -917,6 +916,9 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 'OCP\\Share\\IShareProviderSupportsAccept' => __DIR__ . '/../../..' . '/lib/public/Share/IShareProviderSupportsAccept.php', 'OCP\\Share\\IShareProviderSupportsAllSharesInFolder' => __DIR__ . '/../../..' . '/lib/public/Share/IShareProviderSupportsAllSharesInFolder.php', 'OCP\\Share\\IShareProviderWithNotification' => __DIR__ . '/../../..' . '/lib/public/Share/IShareProviderWithNotification.php', + 'OCP\\Share\\ShareReview\\Events\\ShareReviewAccessCheckEvent' => __DIR__ . '/../../..' . '/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php', + 'OCP\\Share\\ShareReview\\IShareReviewSource' => __DIR__ . '/../../..' . '/lib/public/Share/ShareReview/IShareReviewSource.php', + 'OCP\\Share\\ShareReview\\RegisterShareReviewSourceEvent' => __DIR__ . '/../../..' . '/lib/public/Share/ShareReview/RegisterShareReviewSourceEvent.php', 'OCP\\Snowflake\\ISnowflakeDecoder' => __DIR__ . '/../../..' . '/lib/public/Snowflake/ISnowflakeDecoder.php', 'OCP\\Snowflake\\ISnowflakeGenerator' => __DIR__ . '/../../..' . '/lib/public/Snowflake/ISnowflakeGenerator.php', 'OCP\\Snowflake\\Snowflake' => __DIR__ . '/../../..' . '/lib/public/Snowflake/Snowflake.php', diff --git a/lib/public/Share/Events/ShareReviewAccessCheckEvent.php b/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php similarity index 98% rename from lib/public/Share/Events/ShareReviewAccessCheckEvent.php rename to lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php index 8689d1ecc2316..2e37c8b0aa091 100644 --- a/lib/public/Share/Events/ShareReviewAccessCheckEvent.php +++ b/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php @@ -7,7 +7,7 @@ * SPDX-License-Identifier: AGPL-3.0-or-later */ -namespace OCP\Share\Events; +namespace OCP\Share\ShareReview\Events; use OCP\AppFramework\Attribute\Consumable; use OCP\EventDispatcher\Event; diff --git a/lib/public/Share/ShareReview/IShareReviewSource.php b/lib/public/Share/ShareReview/IShareReviewSource.php new file mode 100644 index 0000000000000..218e4bf28943e --- /dev/null +++ b/lib/public/Share/ShareReview/IShareReviewSource.php @@ -0,0 +1,71 @@ + Each share contains: + * id: The unique app-specific identifier for the share, passed to deleteShare(). + * object: The name or title of the object, such as a file path or report name. + * initiator: The user ID of the initiator. + * type: The OCP\Share\IShare type of the share. + * recipient: The user ID of the owner or the token of a link. + * permissions: The permissions level. Use 1 as the default if not set. + * time: The creation time. Use '1970-01-01 01:00:00' as the default if null. + * action: Optional deletion identifier override. Use an empty string to use id. + * password: Whether the share is password protected. Do not return the password itself. + * expiration: Optional expiration date displayed for the share. + * + * @since 34.0.2 + */ + public function getShares(): array; + + /** + * Delete an app-specific share. + * + * @since 34.0.2 + */ + public function deleteShare(string $shareId): bool; +} diff --git a/lib/public/Share/ShareReview/RegisterShareReviewSourceEvent.php b/lib/public/Share/ShareReview/RegisterShareReviewSourceEvent.php new file mode 100644 index 0000000000000..929277de64bc1 --- /dev/null +++ b/lib/public/Share/ShareReview/RegisterShareReviewSourceEvent.php @@ -0,0 +1,46 @@ +> */ + private array $sources = []; + + /** + * @param class-string $source + * @since 34.0.2 + */ + public function registerSource(string $source): void { + $this->sources[] = $source; + } + + /** + * @return array> + * @since 34.0.2 + */ + public function getSources(): array { + return $this->sources; + } +} diff --git a/tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php b/tests/lib/Share20/ShareReview/Events/ShareReviewAccessCheckEventTest.php similarity index 96% rename from tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php rename to tests/lib/Share20/ShareReview/Events/ShareReviewAccessCheckEventTest.php index fad7dbae01401..61e049f16c5ab 100644 --- a/tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php +++ b/tests/lib/Share20/ShareReview/Events/ShareReviewAccessCheckEventTest.php @@ -7,9 +7,9 @@ * SPDX-License-Identifier: AGPL-3.0-or-later */ -namespace lib\Share20\Events; +namespace lib\Share20\ShareReview\Events; -use OCP\Share\Events\ShareReviewAccessCheckEvent; +use OCP\Share\ShareReview\Events\ShareReviewAccessCheckEvent; use PHPUnit\Framework\TestCase; final class ShareReviewAccessCheckEventTest extends TestCase { diff --git a/tests/lib/Share20/ShareReview/RegisterShareReviewSourceEventTest.php b/tests/lib/Share20/ShareReview/RegisterShareReviewSourceEventTest.php new file mode 100644 index 0000000000000..a50f63cef281c --- /dev/null +++ b/tests/lib/Share20/ShareReview/RegisterShareReviewSourceEventTest.php @@ -0,0 +1,65 @@ + */ + private function makeSourceClass(string $name): string { + $source = new class($name) implements IShareReviewSource { + public function __construct( + private readonly string $name = '', + ) { + } + + public function getName(): string { + return $this->name; + } + + public function getShares(): array { + return []; + } + + public function deleteShare(string $shareId): bool { + return false; + } + }; + return $source::class; + } + + public function testNoSourcesRegistered(): void { + $event = new RegisterShareReviewSourceEvent(); + + $this->assertSame([], $event->getSources()); + } + + public function testRegisterSource(): void { + $sourceClass = $this->makeSourceClass('MyApp'); + + $event = new RegisterShareReviewSourceEvent(); + $event->registerSource($sourceClass); + + $this->assertSame([$sourceClass], $event->getSources()); + } + + public function testRegisterSourceKeepsDuplicates(): void { + $sourceClass = $this->makeSourceClass('MyApp'); + + $event = new RegisterShareReviewSourceEvent(); + $event->registerSource($sourceClass); + $event->registerSource($sourceClass); + + $this->assertSame([$sourceClass, $sourceClass], $event->getSources()); + } +} From e46b015e22a0bcef9b3bd9c1252228ad0ae8b860 Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Thu, 2 Jul 2026 23:41:17 +0200 Subject: [PATCH 3/3] docs(share): explain dispatcher and listener roles of ShareReviewAccessCheckEvent Assisted-by: Claude Code:claude-fable-5 Signed-off-by: Andy Scherzinger --- .../Events/ShareReviewAccessCheckEvent.php | 51 ++++++++++++++++--- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php b/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php index 2e37c8b0aa091..38f998ab156bb 100644 --- a/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php +++ b/lib/public/Share/ShareReview/Events/ShareReviewAccessCheckEvent.php @@ -13,19 +13,54 @@ use OCP\EventDispatcher\Event; /** - * Authorization gate event dispatched by a ShareReview source before deleting - * an app-managed share on behalf of a ShareReview operator. + * Authorization gate for deleting an app-managed share through a share-review app. * - * Usage — dispatch and check: + * Background: Apps such as Deck or Tables manage their own shares outside of + * the regular sharing backend ({@see \OCP\Share\IManager}). They can expose + * those shares to a share-review app — a compliance tool that lets designated + * operators audit and revoke shares across all apps — by implementing + * {@see \OCP\Share\ShareReview\IShareReviewSource}. When a share-review + * operator requests the deletion of such a share, the deletion is executed by + * the app that owns the share, not by the share-review app. The owning app + * has no way of knowing whether the acting user is actually authorized to + * perform share reviews — only the share-review app knows that. This event + * closes that gap: it lets the owning app ask "may the current user delete + * this share on behalf of a share review?" before deleting anything. * - * $event = new ShareReviewAccessCheckEvent('MyApp', $shareId); - * $dispatcher->dispatchTyped($event); - * if (!$event->isHandled() || !$event->isGranted()) { - * return false; // default-deny: no listener means no access + * Dispatched by: the app that owns the share, i.e. the + * {@see \OCP\Share\ShareReview\IShareReviewSource} implementation, at the + * beginning of its deleteShare() method: + * + * public function deleteShare(string $shareId): bool { + * $event = new ShareReviewAccessCheckEvent('MyApp', $shareId); + * $this->dispatcher->dispatchTyped($event); + * if (!$event->isHandled() || !$event->isGranted()) { + * return false; // default-deny: no listener means no access + * } + * // ... actually delete the share ... * } * + * Listened to by: the share-review app. Its listener decides whether the + * current user is an authorized share-review operator (e.g. the app is + * enabled for the user) and answers with grantAccess() or denyAccess(): + * + * public function handle(Event $event): void { + * if (!$event instanceof ShareReviewAccessCheckEvent) { + * return; + * } + * if ($this->isShareReviewOperator()) { + * $event->grantAccess(); + * } else { + * $event->denyAccess('User is not a share-review operator.'); + * } + * } + * + * Apps that merely expose shares must not listen to this event; answering it + * is the responsibility of the share-review app that triggered the deletion. + * * Semantics: - * - Default-deny: an unhandled event blocks the deletion. + * - Default-deny: if no listener responds (isHandled() is false, e.g. no + * share-review app is installed), the dispatcher must not delete the share. * - Deny wins: once denyAccess() is called, further grantAccess() calls are * ignored and propagation is stopped immediately. * - Multiple grants are harmless; the last listener to deny is authoritative.