Skip to content

Commit af59b39

Browse files
AndyScherzingerAndyScherzinger
committed
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 <info@andy-scherzinger.de>
1 parent 9d6c041 commit af59b39

4 files changed

Lines changed: 228 additions & 0 deletions

File tree

‎lib/composer/composer/autoload_classmap.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -854,6 +854,7 @@
854854
'OCP\\Share\\Events\\ShareDeletedEvent' => $baseDir . '/lib/public/Share/Events/ShareDeletedEvent.php',
855855
'OCP\\Share\\Events\\ShareDeletedFromSelfEvent' => $baseDir . '/lib/public/Share/Events/ShareDeletedFromSelfEvent.php',
856856
'OCP\\Share\\Events\\ShareMovedEvent' => $baseDir . '/lib/public/Share/Events/ShareMovedEvent.php',
857+
'OCP\\Share\\Events\\ShareReviewAccessCheckEvent' => $baseDir . '/lib/public/Share/Events/ShareReviewAccessCheckEvent.php',
857858
'OCP\\Share\\Events\\ShareTransferredEvent' => $baseDir . '/lib/public/Share/Events/ShareTransferredEvent.php',
858859
'OCP\\Share\\Events\\VerifyMountPointEvent' => $baseDir . '/lib/public/Share/Events/VerifyMountPointEvent.php',
859860
'OCP\\Share\\Exceptions\\AlreadySharedException' => $baseDir . '/lib/public/Share/Exceptions/AlreadySharedException.php',

‎lib/composer/composer/autoload_static.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -895,6 +895,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
895895
'OCP\\Share\\Events\\ShareDeletedEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareDeletedEvent.php',
896896
'OCP\\Share\\Events\\ShareDeletedFromSelfEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareDeletedFromSelfEvent.php',
897897
'OCP\\Share\\Events\\ShareMovedEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareMovedEvent.php',
898+
'OCP\\Share\\Events\\ShareReviewAccessCheckEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareReviewAccessCheckEvent.php',
898899
'OCP\\Share\\Events\\ShareTransferredEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/ShareTransferredEvent.php',
899900
'OCP\\Share\\Events\\VerifyMountPointEvent' => __DIR__ . '/../../..' . '/lib/public/Share/Events/VerifyMountPointEvent.php',
900901
'OCP\\Share\\Exceptions\\AlreadySharedException' => __DIR__ . '/../../..' . '/lib/public/Share/Exceptions/AlreadySharedException.php',

‎lib/public/Share/Events/ShareReviewAccessCheckEvent.php‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
7+
* SPDX-License-Identifier: AGPL-3.0-or-later
8+
*/
9+
10+
namespace OCP\Share\Events;
11+
12+
use OCP\AppFramework\Attribute\Consumable;
13+
use OCP\EventDispatcher\Event;
14+
15+
/**
16+
* Authorization gate event dispatched by a ShareReview source before deleting
17+
* an app-managed share on behalf of a ShareReview operator.
18+
*
19+
* Usage — dispatch and check:
20+
*
21+
* $event = new ShareReviewAccessCheckEvent('MyApp', $shareId);
22+
* $dispatcher->dispatchTyped($event);
23+
* if (!$event->isHandled() || !$event->isGranted()) {
24+
* return false; // default-deny: no listener means no access
25+
* }
26+
*
27+
* Semantics:
28+
* - Default-deny: an unhandled event blocks the deletion.
29+
* - Deny wins: once denyAccess() is called, further grantAccess() calls are
30+
* ignored and propagation is stopped immediately.
31+
* - Multiple grants are harmless; the last listener to deny is authoritative.
32+
*
33+
* @since 34.0.2
34+
*/
35+
#[Consumable(since: '34.0.2')]
36+
class ShareReviewAccessCheckEvent extends Event {
37+
38+
private bool $handled = false;
39+
private bool $granted = false;
40+
private ?string $reason = null;
41+
42+
/**
43+
* @param string $sourceName Stable, non-translated identifier for the app
44+
* registering the share source (e.g. 'Deck', 'Tables').
45+
* @param string $shareId App-internal identifier of the share being deleted.
46+
*
47+
* @since 34.0.2
48+
*/
49+
public function __construct(
50+
private readonly string $sourceName,
51+
private readonly string $shareId,
52+
) {
53+
parent::__construct();
54+
}
55+
56+
/**
57+
* Stable, non-translated identifier of the app that owns this share source.
58+
*
59+
* @since 34.0.2
60+
*/
61+
public function getSourceName(): string {
62+
return $this->sourceName;
63+
}
64+
65+
/**
66+
* App-internal identifier of the share being deleted.
67+
*
68+
* @since 34.0.2
69+
*/
70+
public function getShareId(): string {
71+
return $this->shareId;
72+
}
73+
74+
/**
75+
* Grant access to delete the share.
76+
*
77+
* Has no effect if denyAccess() was already called on this event — deny wins.
78+
*
79+
* @since 34.0.2
80+
*/
81+
public function grantAccess(): void {
82+
if ($this->handled && !$this->granted) {
83+
return; // deny wins — a prior denyAccess() cannot be escalated to a grant
84+
}
85+
$this->handled = true;
86+
$this->granted = true;
87+
}
88+
89+
/**
90+
* Deny access and provide a human-readable reason.
91+
*
92+
* Stops event propagation immediately — no further listeners will run.
93+
*
94+
* @since 34.0.2
95+
*/
96+
public function denyAccess(string $reason): void {
97+
$this->handled = true;
98+
$this->granted = false;
99+
$this->reason = $reason;
100+
$this->stopPropagation();
101+
}
102+
103+
/**
104+
* Whether any listener has responded to this event.
105+
*
106+
* @since 34.0.2
107+
*/
108+
public function isHandled(): bool {
109+
return $this->handled;
110+
}
111+
112+
/**
113+
* Whether access was granted.
114+
*
115+
* @since 34.0.2
116+
*/
117+
public function isGranted(): bool {
118+
return $this->granted;
119+
}
120+
121+
/**
122+
* Human-readable denial reason, or null if access was granted or the event
123+
* has not been handled yet.
124+
*
125+
* @since 34.0.2
126+
*/
127+
public function getReason(): ?string {
128+
return $this->reason;
129+
}
130+
}

‎tests/lib/Share20/Events/ShareReviewAccessCheckEventTest.php‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
7+
* SPDX-License-Identifier: AGPL-3.0-or-later
8+
*/
9+
10+
namespace lib\Share20\Events;
11+
12+
use OCP\Share\Events\ShareReviewAccessCheckEvent;
13+
use PHPUnit\Framework\TestCase;
14+
15+
final class ShareReviewAccessCheckEventTest extends TestCase {
16+
17+
private function makeEvent(): ShareReviewAccessCheckEvent {
18+
return new ShareReviewAccessCheckEvent('MyApp', '42');
19+
}
20+
21+
public function testInitialState(): void {
22+
$event = $this->makeEvent();
23+
24+
$this->assertFalse($event->isHandled());
25+
$this->assertFalse($event->isGranted());
26+
$this->assertNull($event->getReason());
27+
}
28+
29+
public function testConstructorPayload(): void {
30+
$event = new ShareReviewAccessCheckEvent('Deck', '99');
31+
32+
$this->assertSame('Deck', $event->getSourceName());
33+
$this->assertSame('99', $event->getShareId());
34+
}
35+
36+
public function testGrantAccess(): void {
37+
$event = $this->makeEvent();
38+
$event->grantAccess();
39+
40+
$this->assertTrue($event->isHandled());
41+
$this->assertTrue($event->isGranted());
42+
$this->assertNull($event->getReason());
43+
$this->assertFalse($event->isPropagationStopped());
44+
}
45+
46+
public function testDenyAccess(): void {
47+
$event = $this->makeEvent();
48+
$event->denyAccess('not in group');
49+
50+
$this->assertTrue($event->isHandled());
51+
$this->assertFalse($event->isGranted());
52+
$this->assertSame('not in group', $event->getReason());
53+
}
54+
55+
public function testDenyStopsPropagation(): void {
56+
$event = $this->makeEvent();
57+
$event->denyAccess('no access');
58+
59+
$this->assertTrue($event->isPropagationStopped());
60+
}
61+
62+
public function testGrantDoesNotStopPropagation(): void {
63+
$event = $this->makeEvent();
64+
$event->grantAccess();
65+
66+
$this->assertFalse($event->isPropagationStopped());
67+
}
68+
69+
public function testGrantThenDenyIsDenied(): void {
70+
$event = $this->makeEvent();
71+
$event->grantAccess();
72+
$event->denyAccess('revoked');
73+
74+
$this->assertFalse($event->isGranted());
75+
$this->assertSame('revoked', $event->getReason());
76+
$this->assertTrue($event->isPropagationStopped());
77+
}
78+
79+
public function testDenyThenGrantRemainesDenied(): void {
80+
$event = $this->makeEvent();
81+
$event->denyAccess('not allowed');
82+
$event->grantAccess(); // must be ignored — deny wins
83+
84+
$this->assertFalse($event->isGranted());
85+
$this->assertSame('not allowed', $event->getReason());
86+
}
87+
88+
public function testMultipleGrantsAreIdempotent(): void {
89+
$event = $this->makeEvent();
90+
$event->grantAccess();
91+
$event->grantAccess();
92+
93+
$this->assertTrue($event->isGranted());
94+
$this->assertFalse($event->isPropagationStopped());
95+
}
96+
}

0 commit comments

Comments
 (0)