Laravel AT Protocol Client (alpha & unstable)
Clarify that scope attributes are documentation-only with future enforcement planned
+26
-15
+6
-3
docs/extensions.md
+6
-3
docs/extensions.md
···
425
425
426
426
### Documenting Scope Requirements
427
427
428
-
Use the `#[ScopedEndpoint]` attribute to document which OAuth scopes your extension methods require. This helps with documentation and enables scope checking in authenticated mode:
428
+
Use the `#[ScopedEndpoint]` and `#[PublicEndpoint]` attributes to document the authentication requirements of your extension methods:
429
429
430
430
```php
431
+
use SocialDept\AtpClient\Attributes\PublicEndpoint;
431
432
use SocialDept\AtpClient\Attributes\ScopedEndpoint;
432
433
use SocialDept\AtpClient\Client\Requests\Request;
433
434
use SocialDept\AtpClient\Enums\Scope;
···
441
442
// Process and return metrics...
442
443
}
443
444
444
-
// Methods without #[ScopedEndpoint] work in both public and authenticated modes
445
+
#[PublicEndpoint]
445
446
public function getPublicPostMetrics(string $uri): array
446
447
{
447
448
$thread = $this->atp->bsky->feed->getPostThread($uri);
···
450
451
}
451
452
```
452
453
453
-
Methods with `#[ScopedEndpoint]` indicate they require authentication, while methods without it can work in public mode. See [scopes.md](scopes.md) for full documentation on scope handling.
454
+
> **Note:** These attributes currently serve as documentation only. Runtime scope enforcement will be implemented in a future release. Using them correctly now ensures forward compatibility.
455
+
456
+
Methods with `#[ScopedEndpoint]` indicate they require authentication, while methods with `#[PublicEndpoint]` work without authentication. See [scopes.md](scopes.md) for full documentation on scope handling.
454
457
455
458
## Available Domains
456
459
+20
-12
docs/scopes.md
+20
-12
docs/scopes.md
···
1
1
# OAuth Scopes
2
2
3
-
The AT Protocol uses OAuth scopes to control what actions an application can perform on behalf of a user. AtpClient provides tools for documenting, checking, and enforcing scope requirements.
3
+
The AT Protocol uses OAuth scopes to control what actions an application can perform on behalf of a user. AtpClient provides attributes for documenting scope requirements on endpoints.
4
+
5
+
> **Note:** The `#[ScopedEndpoint]` and `#[PublicEndpoint]` attributes currently serve as documentation only. Runtime scope validation and enforcement will be implemented in a future release. Using these attributes correctly now ensures forward compatibility.
4
6
5
7
## Quick Reference
6
8
···
75
77
76
78
## The ScopedEndpoint Attribute
77
79
78
-
The `#[ScopedEndpoint]` attribute documents and optionally enforces scope requirements on methods.
80
+
The `#[ScopedEndpoint]` attribute documents scope requirements on methods that require authentication.
79
81
80
82
### Basic Usage
81
83
···
154
156
}
155
157
```
156
158
157
-
## Scope Enforcement
159
+
## Scope Enforcement (Planned)
160
+
161
+
> **Coming Soon:** Runtime scope enforcement is not yet implemented. The following documentation describes planned functionality for a future release.
158
162
159
163
### Configuration
160
164
···
220
224
$checker->matchesGranular($session, 'repo:*');
221
225
```
222
226
223
-
## Route Middleware
227
+
## Route Middleware (Planned)
228
+
229
+
> **Coming Soon:** Route middleware is not yet implemented. The following documentation describes planned functionality for a future release.
224
230
225
231
Protect Laravel routes based on ATP session scopes:
226
232
···
286
292
287
293
## Public Mode and Scopes
288
294
289
-
When using `Atp::public()`, no scope checking occurs because there's no authenticated session:
295
+
Methods marked with `#[PublicEndpoint]` can be called without authentication using `Atp::public()`:
290
296
291
297
```php
292
-
// Public mode - no authentication, no scopes
298
+
// Public mode - no authentication required
293
299
$client = Atp::public('https://public.api.bsky.app');
294
-
$client->bsky->actor->getProfile('someone.bsky.social'); // Works without scopes
300
+
$client->bsky->actor->getProfile('someone.bsky.social'); // Works without auth
295
301
296
-
// Authenticated mode - scopes are checked
302
+
// Authenticated mode - for endpoints requiring scopes
297
303
$client = Atp::as($did);
298
304
$client->bsky->feed->getTimeline(); // Requires transition:generic scope
299
305
```
300
306
301
-
Methods that work in public mode typically don't have `#[ScopedEndpoint]` attributes, while authenticated-only methods do.
307
+
Methods with `#[PublicEndpoint]` work in both modes, while methods with `#[ScopedEndpoint]` require authentication.
302
308
303
-
## Exception Handling
309
+
## Exception Handling (Planned)
310
+
311
+
> **Coming Soon:** These exceptions will be thrown when scope enforcement is implemented in a future release.
304
312
305
313
### MissingScopeException
306
314
307
-
Thrown when required scopes are missing and enforcement is strict:
315
+
Will be thrown when required scopes are missing and enforcement is strict:
308
316
309
317
```php
310
318
use SocialDept\AtpClient\Exceptions\MissingScopeException;
···
321
329
322
330
### ScopeAuthorizationException
323
331
324
-
Thrown by middleware when route access is denied:
332
+
Will be thrown by middleware when route access is denied:
325
333
326
334
```php
327
335
use SocialDept\AtpClient\Exceptions\ScopeAuthorizationException;