Merge branch 'refs/heads/dev'

README.md

···
 Sessions automatically refresh when tokens are about to expire (default: 5 minutes before expiration). Listen to events if you need to persist refreshed tokens:
 
 ```php
-use SocialDept\AtpClient\Events\OAuthTokenRefreshed;
+use SocialDept\AtpClient\Events\TokenRefreshed;
 
-Event::listen(OAuthTokenRefreshed::class, function ($event) {
-    // $event->did - the user's DID (e.g., did:plc:abc123...)
+Event::listen(TokenRefreshed::class, function ($event) {
+    // $event->session - the Session being refreshed
     // $event->token - the new AccessToken
     // Update your credential storage here
+
+    // Check auth type if needed
+    if ($event->session->isLegacy()) {
+        // App password session
+    }
 });
 ```
 
···
 }
 ```
 
+### Built-in Credential Providers
+
+The package includes several credential providers for different use cases:
+
+| Provider | Persistence | Setup | Best For |
+|----------|-------------|-------|----------|
+| `ArrayCredentialProvider` | None (memory) | None | Testing, single requests |
+| `CacheCredentialProvider` | Cache driver | None | Quick prototyping, APIs |
+| `SessionCredentialProvider` | Session lifetime | None | Web apps with user sessions |
+| `FileCredentialProvider` | Permanent (disk) | None | CLI tools, bots |
+
+**CacheCredentialProvider** - Uses Laravel's cache system (file cache by default):
+```php
+// config/client.php
+'credential_provider' => \SocialDept\AtpClient\Providers\CacheCredentialProvider::class,
+```
+
+**SessionCredentialProvider** - Credentials cleared when session expires or user logs out:
+```php
+// config/client.php
+'credential_provider' => \SocialDept\AtpClient\Providers\SessionCredentialProvider::class,
+```
+
+**FileCredentialProvider** - Stores credentials in `storage/app/atp-credentials/`:
+```php
+// config/client.php
+'credential_provider' => \SocialDept\AtpClient\Providers\FileCredentialProvider::class,
+```
+
+For production applications with multiple users, implement a database-backed provider as shown below.
+
 ### Database Migration
 
 Create a migration for storing credentials:
···
     $table->text('refresh_token');           // Single-use refresh token
     $table->timestamp('expires_at');         // Token expiration time
     $table->json('scope')->nullable();       // Granted OAuth scopes
+    $table->string('auth_type')->default('oauth'); // 'oauth' or 'legacy'
     $table->timestamps();
 });
 ```
···
 use SocialDept\AtpClient\Contracts\CredentialProvider;
 use SocialDept\AtpClient\Data\AccessToken;
 use SocialDept\AtpClient\Data\Credentials;
+use SocialDept\AtpClient\Enums\AuthType;
 
 class DatabaseCredentialProvider implements CredentialProvider
 {
···
             handle: $record->handle,
             issuer: $record->issuer,
             scope: $record->scope ?? [],
+            authType: AuthType::from($record->auth_type),
         );
     }
 
···
                 'refresh_token' => $token->refreshJwt,
                 'expires_at' => $token->expiresAt,
                 'scope' => $token->scope,
+                'auth_type' => $token->authType->value,
             ]
         );
     }
···
             'handle' => $token->handle,
             'issuer' => $token->issuer,
             'scope' => $token->scope,
+            'auth_type' => $token->authType->value,
         ]);
     }
 
···
         'refresh_token',
         'expires_at',
         'scope',
+        'auth_type',
     ];
 
     protected $casts = [
···
 | `refreshToken` | Token to get new access tokens (single-use!) |
 | `expiresAt` | When the access token expires |
 | `scope` | Array of granted scopes (e.g., `['atproto', 'transition:generic']`) |
+| `authType` | Authentication method: `AuthType::OAuth` or `AuthType::Legacy` |
 
 ### Handling Token Refresh Events
 
 When tokens are automatically refreshed, you can listen for events:
 
 ```php
-use SocialDept\AtpClient\Events\OAuthTokenRefreshed;
+use SocialDept\AtpClient\Events\TokenRefreshed;
 
 // In EventServiceProvider or via Event::listen()
-Event::listen(OAuthTokenRefreshed::class, function (OAuthTokenRefreshed $event) {
+Event::listen(TokenRefreshed::class, function (TokenRefreshed $event) {
     // The CredentialProvider.updateCredentials() is already called,
     // but you can do additional logging or notifications here
     Log::info("Token refreshed for: {$event->session->did()}");
+
+    // Check if this is a legacy (app password) session
+    if ($event->session->isLegacy()) {
+        // Handle legacy sessions differently if needed
+    }
 });
 ```
 
···
 });
 ```
 
-### OAuthTokenRefreshing / OAuthTokenRefreshed
+### TokenRefreshing / TokenRefreshed
 
-Fired before and after automatic token refresh. Use `OAuthTokenRefreshing` to invalidate your stored refresh token before it's used (refresh tokens are single-use):
+Fired before and after automatic token refresh for both OAuth and legacy sessions. Use `TokenRefreshing` to invalidate your stored refresh token before it's used (refresh tokens are single-use):
 
 ```php
-use SocialDept\AtpClient\Events\OAuthTokenRefreshing;
-use SocialDept\AtpClient\Events\OAuthTokenRefreshed;
+use SocialDept\AtpClient\Events\TokenRefreshing;
+use SocialDept\AtpClient\Events\TokenRefreshed;
 
 // Before token refresh - invalidate old refresh token
-Event::listen(OAuthTokenRefreshing::class, function (OAuthTokenRefreshing $event) {
-    // $event->session gives access to did(), handle(), etc.
+Event::listen(TokenRefreshing::class, function (TokenRefreshing $event) {
+    // $event->session gives access to did(), handle(), authType(), isLegacy(), etc.
     Log::info('Refreshing token for: ' . $event->session->did());
 });
 
 // After token refresh - new tokens available
-Event::listen(OAuthTokenRefreshed::class, function (OAuthTokenRefreshed $event) {
+Event::listen(TokenRefreshed::class, function (TokenRefreshed $event) {
     // $event->session - the session being refreshed
     // $event->token - the new AccessToken with fresh tokens
     // CredentialProvider.updateCredentials() is already called automatically
     Log::info('Token refreshed for: ' . $event->session->did());
+
+    // Check auth type if needed
+    if ($event->session->isLegacy()) {
+        // Legacy (app password) session
+    }
 });
+```
+
+## Scope Authorization
+
+The package provides Laravel-native authorization features for checking ATP OAuth scopes, similar to Laravel's Gate/Policy system.
+
+### Setup
+
+Have your User model implement the `HasAtpSession` interface:
+
+```php
+use SocialDept\AtpClient\Contracts\HasAtpSession;
+
+class User extends Authenticatable implements HasAtpSession
+{
+    public function getAtpDid(): ?string
+    {
+        return $this->atp_did; // or however you store the DID
+    }
+}
+```
+
+### Route Middleware
+
+Protect routes by requiring specific scopes. Uses AND logic (all listed scopes required):
+
+```php
+use Illuminate\Support\Facades\Route;
+
+// Requires transition:generic scope
+Route::post('/posts', [PostController::class, 'store'])
+    ->middleware('atp.scope:transition:generic');
+
+// Requires BOTH scopes
+Route::post('/dm', [MessageController::class, 'store'])
+    ->middleware('atp.scope:transition:generic,transition:chat.bsky');
+```
+
+### AtpScope Facade
+
+Use the `AtpScope` facade for programmatic scope checks:
+
+```php
+use SocialDept\AtpClient\Facades\AtpScope;
+
+// Check if user has a scope
+if (AtpScope::can('transition:generic')) {
+    // ...
+}
+
+// Check if user has any of the scopes
+if (AtpScope::canAny(['transition:generic', 'transition:chat.bsky'])) {
+    // ...
+}
+
+// Check if user has all scopes
+if (AtpScope::canAll(['atproto', 'transition:generic'])) {
+    // ...
+}
+
+// Authorize or fail (throws/aborts based on config)
+AtpScope::authorize('transition:generic');
+
+// Check for a specific user
+AtpScope::forUser($did)->authorize('transition:generic');
+
+// Get all granted scopes
+$scopes = AtpScope::granted();
+```
+
+### Session Helper Methods
+
+The Session class also has convenience methods:
+
+```php
+$session = Atp::as($did)->session();
+
+$session->can('transition:generic');
+$session->canAny(['transition:generic', 'transition:chat.bsky']);
+$session->canAll(['atproto', 'transition:generic']);
+$session->cannot('transition:chat.bsky');
+```
+
+### Configuration
+
+Configure authorization failure behavior in `config/client.php`:
+
+```php
+'scope_authorization' => [
+    // What happens when scope check fails: 'abort', 'redirect', or 'exception'
+    'failure_action' => ScopeAuthorizationFailure::Abort,
+
+    // Redirect URL when failure_action is 'redirect'
+    'redirect_to' => '/login',
+],
+```
+
+Or via environment variables:
+
+```env
+ATP_SCOPE_FAILURE_ACTION=abort
+ATP_SCOPE_REDIRECT=/login
 ```
 
 ## Available Commands

config/client.php

···
 <?php
 
+use SocialDept\AtpClient\Enums\ScopeAuthorizationFailure;
+use SocialDept\AtpClient\Enums\ScopeEnforcementLevel;
+
 return [
     /*
     |--------------------------------------------------------------------------
···
             'times' => env('ATP_HTTP_RETRY_TIMES', 3),
             'sleep' => env('ATP_HTTP_RETRY_SLEEP', 100),
         ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Scope Enforcement
+    |--------------------------------------------------------------------------
+    |
+    | Configure how scope requirements are enforced. Options:
+    | - 'strict': Throws MissingScopeException if required scopes are missing
+    | - 'permissive': Logs a warning but attempts the request anyway
+    |
+    */
+    'scope_enforcement' => ScopeEnforcementLevel::tryFrom(
+        env('ATP_SCOPE_ENFORCEMENT', 'permissive')
+    ) ?? ScopeEnforcementLevel::Permissive,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Scope Authorization
+    |--------------------------------------------------------------------------
+    |
+    | Configure behavior for the AtpScope facade and atp.scope middleware.
+    |
+    | failure_action: What happens when a scope check fails
+    | - 'abort': Return a 403 HTTP response
+    | - 'redirect': Redirect to the configured URL
+    | - 'exception': Throw ScopeAuthorizationException
+    |
+    | redirect_to: URL to redirect to when failure_action is 'redirect'
+    |
+    */
+    'scope_authorization' => [
+        'failure_action' => ScopeAuthorizationFailure::tryFrom(
+            env('ATP_SCOPE_FAILURE_ACTION', 'abort')
+        ) ?? ScopeAuthorizationFailure::Abort,
+
+        'redirect_to' => env('ATP_SCOPE_REDIRECT', '/login'),
     ],
 ];

src/AtpClientServiceProvider.php

···
 
 namespace SocialDept\AtpClient;
 
+use Illuminate\Routing\Router;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\ServiceProvider;
 use SocialDept\AtpClient\Auth\ClientMetadataManager;
 use SocialDept\AtpClient\Auth\DPoPKeyManager;
 use SocialDept\AtpClient\Auth\DPoPNonceManager;
 use SocialDept\AtpClient\Auth\OAuthEngine;
+use SocialDept\AtpClient\Auth\ScopeChecker;
+use SocialDept\AtpClient\Auth\ScopeGate;
 use SocialDept\AtpClient\Auth\TokenRefresher;
+use SocialDept\AtpClient\Enums\ScopeEnforcementLevel;
+use SocialDept\AtpClient\Http\Middleware\RequiresScopeMiddleware;
 use SocialDept\AtpClient\Console\GenerateOAuthKeyCommand;
 use SocialDept\AtpClient\Contracts\CredentialProvider;
 use SocialDept\AtpClient\Contracts\KeyStore;
···
             );
         });
         $this->app->singleton(OAuthEngine::class);
+        $this->app->singleton(ScopeChecker::class, function ($app) {
+            return new ScopeChecker(
+                config('atp-client.scope_enforcement', ScopeEnforcementLevel::Permissive)
+            );
+        });
+
+        // Register ScopeGate for AtpScope facade
+        $this->app->singleton('atp-scope', function ($app) {
+            return new ScopeGate(
+                $app->make(SessionManager::class),
+                $app->make(ScopeChecker::class),
+            );
+        });
 
         // Register main client facade accessor
         $this->app->bind('atp-client', function ($app) {
···
                     $this->app = $app;
                 }
 
-                public function as(string $handleOrDid): AtpClient
+                public function as(string $actor): AtpClient
                 {
                     return new AtpClient(
                         $this->app->make(SessionManager::class),
-                        $handleOrDid
+                        $actor
                     );
                 }
 
-                public function login(string $handleOrDid, string $password): AtpClient
+                public function login(string $actor, string $password): AtpClient
                 {
                     $this->app->make(SessionManager::class)
-                        ->fromAppPassword($handleOrDid, $password);
+                        ->fromAppPassword($actor, $password);
 
-                    return $this->as($handleOrDid);
+                    return $this->as($actor);
                 }
 
                 public function oauth(): OAuthEngine
···
         }
 
         $this->registerRoutes();
+        $this->registerMiddleware();
+    }
+
+    /**
+     * Register middleware aliases
+     */
+    protected function registerMiddleware(): void
+    {
+        /** @var Router $router */
+        $router = $this->app->make(Router::class);
+        $router->aliasMiddleware('atp.scope', RequiresScopeMiddleware::class);
     }
 
     /**
···
                 ->name('atp.oauth.jwks');
         });
 
-        // Register standard .well-known endpoint
-        Route::get('.well-known/oauth-client-metadata', ClientMetadataController::class)
-            ->name('atp.oauth.well-known');
+        // Register recommended client id convention (see: https://atproto.com/guides/oauth#clients)
+        Route::get('oauth-client-metadata.json', ClientMetadataController::class)
+            ->name('atp.oauth.json');
     }
 
     /**
···
      */
     public function provides(): array
     {
-        return ['atp-client'];
+        return ['atp-client', 'atp-scope'];
     }
 }

src/Attributes/RequiresScope.php

···
+<?php
+
+namespace SocialDept\AtpClient\Attributes;
+
+use Attribute;
+use SocialDept\AtpClient\Enums\Scope;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class RequiresScope
+{
+    public array $scopes;
+
+    /**
+     * @param  string|Scope|array<string|Scope>  $scopes  Required scope(s) for this method
+     * @param  string|null  $granular  Future granular scope equivalent
+     * @param  string  $description  Human-readable description of scope requirement
+     */
+    public function __construct(
+        string|Scope|array $scopes,
+        public readonly ?string $granular = null,
+        public readonly string $description = '',
+    ) {
+        $this->scopes = $this->normalizeScopes($scopes);
+    }
+
+    protected function normalizeScopes(string|Scope|array $scopes): array
+    {
+        if (! is_array($scopes)) {
+            $scopes = [$scopes];
+        }
+
+        return array_map(
+            fn ($scope) => $scope instanceof Scope ? $scope->value : $scope,
+            $scopes
+        );
+    }
+}

src/Auth/ScopeChecker.php

···
+<?php
+
+namespace SocialDept\AtpClient\Auth;
+
+use Illuminate\Support\Facades\Log;
+use SocialDept\AtpClient\Enums\Scope;
+use SocialDept\AtpClient\Enums\ScopeEnforcementLevel;
+use SocialDept\AtpClient\Exceptions\MissingScopeException;
+use SocialDept\AtpClient\Session\Session;
+
+class ScopeChecker
+{
+    public function __construct(
+        protected ScopeEnforcementLevel $enforcement = ScopeEnforcementLevel::Permissive
+    ) {}
+
+    /**
+     * Check if the session has all required scopes.
+     *
+     * @param  array<string|Scope>  $requiredScopes
+     */
+    public function check(Session $session, array $requiredScopes): bool
+    {
+        $required = $this->normalizeScopes($requiredScopes);
+        $granted = $session->scopes();
+
+        foreach ($required as $scope) {
+            if (! $this->sessionHasScope($session, $scope)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Check scopes and handle enforcement based on configuration.
+     *
+     * @param  array<string|Scope>  $requiredScopes
+     *
+     * @throws MissingScopeException
+     */
+    public function checkOrFail(Session $session, array $requiredScopes): void
+    {
+        if ($this->check($session, $requiredScopes)) {
+            return;
+        }
+
+        $required = $this->normalizeScopes($requiredScopes);
+        $granted = $session->scopes();
+        $missing = array_diff($required, $granted);
+
+        if ($this->enforcement === ScopeEnforcementLevel::Strict) {
+            throw new MissingScopeException($missing, $granted);
+        }
+
+        Log::warning('ATP Client: Missing required scope(s)', [
+            'required' => $required,
+            'granted' => $granted,
+            'missing' => $missing,
+            'did' => $session->did(),
+        ]);
+    }
+
+    /**
+     * Check if the session has a specific scope.
+     */
+    public function hasScope(Session $session, string|Scope $scope): bool
+    {
+        $scope = $scope instanceof Scope ? $scope->value : $scope;
+
+        return $this->sessionHasScope($session, $scope);
+    }
+
+    /**
+     * Check if the session matches a granular scope pattern.
+     *
+     * Supports patterns like:
+     * - repo:app.bsky.feed.post?action=create
+     * - repo:app.bsky.feed.*
+     * - rpc:app.bsky.feed.*
+     * - blob:image/*
+     */
+    public function matchesGranular(Session $session, string $pattern): bool
+    {
+        $granted = $session->scopes();
+
+        // Check for exact match first
+        if (in_array($pattern, $granted, true)) {
+            return true;
+        }
+
+        // Handle repo: scopes with action semantics
+        if (str_starts_with($pattern, 'repo:')) {
+            foreach ($granted as $scope) {
+                if (str_starts_with($scope, 'repo:') && $this->matchesRepoScope($pattern, $scope)) {
+                    return true;
+                }
+            }
+        }
+
+        // Check for wildcard matches
+        $patternRegex = $this->patternToRegex($pattern);
+
+        foreach ($granted as $scope) {
+            if (preg_match($patternRegex, $scope)) {
+                return true;
+            }
+        }
+
+        // Check if granted scope is a superset (wildcard in granted scope)
+        foreach ($granted as $scope) {
+            $grantedRegex = $this->patternToRegex($scope);
+            if (preg_match($grantedRegex, $pattern)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Check if a required repo scope is satisfied by a granted repo scope.
+     *
+     * Per AT Protocol spec: "If not defined, all operations are allowed."
+     * - repo:collection (no action) grants ALL actions
+     * - repo:collection?action=create grants only create
+     * - repo:* grants all collections with all actions
+     */
+    protected function matchesRepoScope(string $required, string $granted): bool
+    {
+        $requiredParsed = $this->parseRepoScope($required);
+        $grantedParsed = $this->parseRepoScope($granted);
+
+        // Check collection match (with wildcard support)
+        if (! $this->collectionsMatch($requiredParsed['collection'], $grantedParsed['collection'])) {
+            return false;
+        }
+
+        // If granted has no actions, it grants ALL actions
+        if (empty($grantedParsed['actions'])) {
+            return true;
+        }
+
+        // If required has no actions, we need all actions granted
+        if (empty($requiredParsed['actions'])) {
+            // Required needs all actions, but granted is restricted
+            return false;
+        }
+
+        // Check if all required actions are in granted actions
+        return empty(array_diff($requiredParsed['actions'], $grantedParsed['actions']));
+    }
+
+    /**
+     * Parse a repo scope into collection and actions.
+     *
+     * Handles formats like:
+     * - repo:app.bsky.feed.post
+     * - repo:app.bsky.feed.post?action=create
+     * - repo:app.bsky.feed.post?action=create&action=update&action=delete
+     * - repo:*
+     * - repo:*?action=delete
+     *
+     * @return array{collection: string, actions: array<string>}
+     */
+    protected function parseRepoScope(string $scope): array
+    {
+        $parts = explode('?', $scope, 2);
+        $collection = substr($parts[0], 5); // Remove 'repo:'
+
+        $actions = [];
+        if (isset($parts[1])) {
+            // Parse action=create&action=update&action=delete format
+            // PHP's parse_str doesn't handle repeated params well
+            preg_match_all('/action=([^&]+)/', $parts[1], $matches);
+            if (! empty($matches[1])) {
+                $actions = array_map('urldecode', $matches[1]);
+            }
+        }
+
+        return ['collection' => $collection, 'actions' => $actions];
+    }
+
+    /**
+     * Check if a required collection matches a granted collection.
+     */
+    protected function collectionsMatch(string $required, string $granted): bool
+    {
+        if ($granted === '*') {
+            return true;
+        }
+
+        return $required === $granted;
+    }
+
+    /**
+     * Check if the session has repo access for a specific collection and action.
+     */
+    public function checkRepoScope(Session $session, string $collection, string $action): bool
+    {
+        $required = "repo:{$collection}?action={$action}";
+
+        return $this->sessionHasScope($session, $required);
+    }
+
+    /**
+     * Check repo scope and handle enforcement based on configuration.
+     *
+     * @throws MissingScopeException
+     */
+    public function checkRepoScopeOrFail(Session $session, string $collection, string $action): void
+    {
+        $required = "repo:{$collection}?action={$action}";
+
+        $this->checkOrFail($session, [$required]);
+    }
+
+    /**
+     * Get the current enforcement level.
+     */
+    public function enforcement(): ScopeEnforcementLevel
+    {
+        return $this->enforcement;
+    }
+
+    /**
+     * Create a new instance with a different enforcement level.
+     */
+    public function withEnforcement(ScopeEnforcementLevel $enforcement): self
+    {
+        return new self($enforcement);
+    }
+
+    /**
+     * @param  array<string|Scope>  $scopes
+     * @return array<string>
+     */
+    protected function normalizeScopes(array $scopes): array
+    {
+        return array_map(
+            fn ($scope) => $scope instanceof Scope ? $scope->value : $scope,
+            $scopes
+        );
+    }
+
+    protected function sessionHasScope(Session $session, string $scope): bool
+    {
+        // Direct match
+        if ($session->hasScope($scope)) {
+            return true;
+        }
+
+        // Check granular pattern matching
+        return $this->matchesGranular($session, $scope);
+    }
+
+    protected function patternToRegex(string $pattern): string
+    {
+        // Escape regex special characters except *
+        $escaped = preg_quote($pattern, '/');
+
+        // Replace \* with .* for wildcard matching
+        $regex = str_replace('\*', '.*', $escaped);
+
+        return '/^'.$regex.'$/';
+    }
+}

src/Auth/ScopeGate.php

···
+<?php
+
+namespace SocialDept\AtpClient\Auth;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+use SocialDept\AtpClient\Contracts\HasAtpSession;
+use SocialDept\AtpClient\Enums\Scope;
+use SocialDept\AtpClient\Enums\ScopeAuthorizationFailure;
+use SocialDept\AtpClient\Exceptions\ScopeAuthorizationException;
+use SocialDept\AtpClient\Session\Session;
+use SocialDept\AtpClient\Session\SessionManager;
+
+class ScopeGate
+{
+    protected ?Session $session = null;
+
+    public function __construct(
+        protected SessionManager $sessions,
+        protected ScopeChecker $checker,
+    ) {}
+
+    /**
+     * Set the session context directly.
+     */
+    public function forSession(Session $session): self
+    {
+        $instance = new self($this->sessions, $this->checker);
+        $instance->session = $session;
+
+        return $instance;
+    }
+
+    /**
+     * Set the session context via actor (handle or DID).
+     */
+    public function forUser(string $actor): self
+    {
+        $instance = new self($this->sessions, $this->checker);
+        $instance->session = $this->sessions->session($actor);
+
+        return $instance;
+    }
+
+    /**
+     * Check if the session has the given scope.
+     */
+    public function can(string|Scope $scope): bool
+    {
+        $session = $this->resolveSession();
+
+        if (! $session) {
+            return false;
+        }
+
+        return $this->checker->hasScope($session, $scope);
+    }
+
+    /**
+     * Check if the session has any of the given scopes.
+     *
+     * @param  array<string|Scope>  $scopes
+     */
+    public function canAny(array $scopes): bool
+    {
+        $session = $this->resolveSession();
+
+        if (! $session) {
+            return false;
+        }
+
+        foreach ($scopes as $scope) {
+            if ($this->checker->hasScope($session, $scope)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Check if the session has all of the given scopes.
+     *
+     * @param  array<string|Scope>  $scopes
+     */
+    public function canAll(array $scopes): bool
+    {
+        $session = $this->resolveSession();
+
+        if (! $session) {
+            return false;
+        }
+
+        return $this->checker->check($session, $scopes);
+    }
+
+    /**
+     * Check if the session does NOT have the given scope.
+     */
+    public function cannot(string|Scope $scope): bool
+    {
+        return ! $this->can($scope);
+    }
+
+    /**
+     * Authorize the session has all given scopes, or handle failure.
+     *
+     * @param  string|Scope  ...$scopes
+     *
+     * @throws ScopeAuthorizationException
+     */
+    public function authorize(string|Scope ...$scopes): void
+    {
+        if ($this->canAll($scopes)) {
+            return;
+        }
+
+        $session = $this->resolveSession();
+        $granted = $session ? $session->scopes() : [];
+        $required = array_map(
+            fn ($scope) => $scope instanceof Scope ? $scope->value : $scope,
+            $scopes
+        );
+        $missing = array_diff($required, $granted);
+
+        $exception = new ScopeAuthorizationException($missing, $granted);
+
+        $action = config('atp-client.scope_authorization.failure_action', ScopeAuthorizationFailure::Abort);
+
+        if ($action === ScopeAuthorizationFailure::Exception) {
+            throw $exception;
+        }
+
+        // For Abort and Redirect, let the exception render itself
+        throw $exception;
+    }
+
+    /**
+     * Get the granted scopes for the current session.
+     */
+    public function granted(): array
+    {
+        $session = $this->resolveSession();
+
+        return $session ? $session->scopes() : [];
+    }
+
+    /**
+     * Resolve the session from context.
+     */
+    protected function resolveSession(): ?Session
+    {
+        // If session was explicitly set, use it
+        if ($this->session) {
+            return $this->session;
+        }
+
+        // Try to resolve from authenticated user
+        $user = auth()->user();
+
+        if (! $user instanceof HasAtpSession) {
+            return null;
+        }
+
+        $did = $user->getAtpDid();
+
+        if (! $did) {
+            return null;
+        }
+
+        try {
+            return $this->sessions->session($did);
+        } catch (\Exception) {
+            return null;
+        }
+    }
+}

src/Auth/TokenRefresher.php

···
 
 namespace SocialDept\AtpClient\Auth;
 
+use Illuminate\Support\Facades\Http;
 use SocialDept\AtpClient\Data\AccessToken;
 use SocialDept\AtpClient\Data\DPoPKey;
+use SocialDept\AtpClient\Enums\AuthType;
 use SocialDept\AtpClient\Exceptions\AuthenticationException;
 use SocialDept\AtpClient\Http\DPoPClient;
 
···
     ) {}
 
     /**
-     * Refresh access token using refresh token
+     * Refresh access token using refresh token.
      * NOTE: Refresh tokens are single-use!
      */
     public function refresh(
         string $refreshToken,
         string $pdsEndpoint,
         DPoPKey $dpopKey,
-        ?string $handle = null
+        ?string $handle = null,
+        AuthType $authType = AuthType::OAuth,
+    ): AccessToken {
+        return $authType === AuthType::Legacy
+            ? $this->refreshLegacy($refreshToken, $pdsEndpoint, $handle)
+            : $this->refreshOAuth($refreshToken, $pdsEndpoint, $dpopKey, $handle);
+    }
+
+    /**
+     * Refresh OAuth session using /oauth/token endpoint with DPoP.
+     */
+    protected function refreshOAuth(
+        string $refreshToken,
+        string $pdsEndpoint,
+        DPoPKey $dpopKey,
+        ?string $handle,
     ): AccessToken {
         $tokenUrl = $pdsEndpoint.'/oauth/token';
 
···
                 'grant_type' => 'refresh_token',
                 'refresh_token' => $refreshToken,
             ]);
+
+        if ($response->failed()) {
+            throw new AuthenticationException('Token refresh failed: '.$response->body());
+        }
+
+        return AccessToken::fromResponse($response->json(), $handle, $pdsEndpoint);
+    }
+
+    /**
+     * Refresh legacy session using /xrpc/com.atproto.server.refreshSession endpoint.
+     */
+    protected function refreshLegacy(
+        string $refreshToken,
+        string $pdsEndpoint,
+        ?string $handle,
+    ): AccessToken {
+        $response = Http::withHeader('Authorization', 'Bearer '.$refreshToken)
+            ->post($pdsEndpoint.'/xrpc/com.atproto.server.refreshSession');
 
         if ($response->failed()) {
             throw new AuthenticationException('Token refresh failed: '.$response->body());

src/Client/Client.php

···
 use SocialDept\AtpClient\AtpClient;
 use SocialDept\AtpClient\Http\DPoPClient;
 use SocialDept\AtpClient\Http\HasHttp;
+use SocialDept\AtpClient\Session\Session;
 use SocialDept\AtpClient\Session\SessionManager;
 
 class Client
···
         $this->sessions = $sessions;
         $this->did = $did;
         $this->dpopClient = app(DPoPClient::class);
+    }
+
+    /**
+     * Get the current session.
+     */
+    public function session(): Session
+    {
+        return $this->sessions->session($this->did);
     }
 }

src/Client/Records/FollowRecordClient.php

···
 namespace SocialDept\AtpClient\Client\Records;
 
 use DateTimeInterface;
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
 use SocialDept\AtpClient\Data\StrongRef;
+use SocialDept\AtpClient\Enums\Scope;
 
 class FollowRecordClient extends Request
 {
     /**
      * Follow a user
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.graph.follow?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.graph.follow?action=create')]
     public function create(
         string $subject,
         ?DateTimeInterface $createdAt = null
···
             'createdAt' => ($createdAt ?? now())->format('c'),
         ];
 
-        $response = $this->atp->client->post(
-            endpoint: 'com.atproto.repo.createRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.graph.follow',
-                'record' => $record,
-            ]
+        $response = $this->atp->atproto->repo->createRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.graph.follow',
+            record: $record
         );
 
         return StrongRef::fromResponse($response->json());
···
 
     /**
      * Unfollow a user (delete follow record)
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.deleteRecord AND repo:app.bsky.graph.follow?action=delete)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.deleteRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.graph.follow?action=delete')]
     public function delete(string $rkey): void
     {
-        $this->atp->client->post(
-            endpoint: 'com.atproto.repo.deleteRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.graph.follow',
-                'rkey' => $rkey,
-            ]
+        $this->atp->atproto->repo->deleteRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.graph.follow',
+            rkey: $rkey
         );
     }
 
     /**
      * Get a follow record
+     *
+     * @requires transition:generic (rpc:com.atproto.repo.getRecord)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.getRecord')]
     public function get(string $rkey, ?string $cid = null): array
     {
-        $response = $this->atp->client->get(
-            endpoint: 'com.atproto.repo.getRecord',
-            params: array_filter([
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.graph.follow',
-                'rkey' => $rkey,
-                'cid' => $cid,
-            ])
+        $response = $this->atp->atproto->repo->getRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.graph.follow',
+            rkey: $rkey,
+            cid: $cid
         );
 
         return $response->json('value');

src/Client/Records/LikeRecordClient.php

···
 namespace SocialDept\AtpClient\Client\Records;
 
 use DateTimeInterface;
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
 use SocialDept\AtpClient\Data\StrongRef;
+use SocialDept\AtpClient\Enums\Scope;
 
 class LikeRecordClient extends Request
 {
     /**
      * Like a post
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.feed.like?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.like?action=create')]
     public function create(
         StrongRef $subject,
         ?DateTimeInterface $createdAt = null
···
             'createdAt' => ($createdAt ?? now())->format('c'),
         ];
 
-        $response = $this->atp->client->post(
-            endpoint: 'com.atproto.repo.createRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.like',
-                'record' => $record,
-            ]
+        $response = $this->atp->atproto->repo->createRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.like',
+            record: $record
         );
 
         return StrongRef::fromResponse($response->json());
···
 
     /**
      * Unlike a post (delete like record)
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.deleteRecord AND repo:app.bsky.feed.like?action=delete)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.deleteRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.like?action=delete')]
     public function delete(string $rkey): void
     {
-        $this->atp->client->post(
-            endpoint: 'com.atproto.repo.deleteRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.like',
-                'rkey' => $rkey,
-            ]
+        $this->atp->atproto->repo->deleteRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.like',
+            rkey: $rkey
         );
     }
 
     /**
      * Get a like record
+     *
+     * @requires transition:generic (rpc:com.atproto.repo.getRecord)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.getRecord')]
     public function get(string $rkey, ?string $cid = null): array
     {
-        $response = $this->atp->client->get(
-            endpoint: 'com.atproto.repo.getRecord',
-            params: array_filter([
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.like',
-                'rkey' => $rkey,
-                'cid' => $cid,
-            ])
+        $response = $this->atp->atproto->repo->getRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.like',
+            rkey: $rkey,
+            cid: $cid
         );
 
         return $response->json('value');

src/Client/Records/PostRecordClient.php

···
 namespace SocialDept\AtpClient\Client\Records;
 
 use DateTimeInterface;
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
 use SocialDept\AtpClient\Contracts\Recordable;
 use SocialDept\AtpClient\Data\StrongRef;
-use SocialDept\AtpClient\Http\Response;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\RichText\TextBuilder;
 
 class PostRecordClient extends Request
 {
     /**
      * Create a post
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.feed.post?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=create')]
     public function create(
         string|array|Recordable $content,
         ?array $facets = null,
···
             $record['$type'] = 'app.bsky.feed.post';
         }
 
-        // Create record via XRPC
-        $response = $this->atp->client->post(
-            endpoint: 'com.atproto.repo.createRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.post',
-                'record' => $record,
-            ]
+        $response = $this->atp->atproto->repo->createRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.post',
+            record: $record
         );
 
         return StrongRef::fromResponse($response->json());
···
 
     /**
      * Update a post
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.putRecord AND repo:app.bsky.feed.post?action=update)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.putRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=update')]
     public function update(string $rkey, array $record): StrongRef
     {
         // Ensure $type is set
···
             $record['$type'] = 'app.bsky.feed.post';
         }
 
-        $response = $this->atp->client->post(
-            endpoint: 'com.atproto.repo.putRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.post',
-                'rkey' => $rkey,
-                'record' => $record,
-            ]
+        $response = $this->atp->atproto->repo->putRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.post',
+            rkey: $rkey,
+            record: $record
         );
 
         return StrongRef::fromResponse($response->json());
···
 
     /**
      * Delete a post
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.deleteRecord AND repo:app.bsky.feed.post?action=delete)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.deleteRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=delete')]
     public function delete(string $rkey): void
     {
-        $this->atp->client->post(
-            endpoint: 'com.atproto.repo.deleteRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.post',
-                'rkey' => $rkey,
-            ]
+        $this->atp->atproto->repo->deleteRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.post',
+            rkey: $rkey
         );
     }
 
     /**
      * Get a post
+     *
+     * @requires transition:generic (rpc:com.atproto.repo.getRecord)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.getRecord')]
     public function get(string $rkey, ?string $cid = null): array
     {
-        $response = $this->atp->client->get(
-            endpoint: 'com.atproto.repo.getRecord',
-            params: array_filter([
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.feed.post',
-                'rkey' => $rkey,
-                'cid' => $cid,
-            ])
+        $response = $this->atp->atproto->repo->getRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.feed.post',
+            rkey: $rkey,
+            cid: $cid
         );
 
         return $response->json('value');
···
 
     /**
      * Create a reply to another post
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.feed.post?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=create')]
     public function reply(
         StrongRef $parent,
         StrongRef $root,
···
 
     /**
      * Create a quote post (post with embedded post)
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.feed.post?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=create')]
     public function quote(
         StrongRef $quotedPost,
         string|array|Recordable $content,
···
 
     /**
      * Create a post with images
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.feed.post?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=create')]
     public function withImages(
         string|array|Recordable $content,
         array $images,
···
 
     /**
      * Create a post with external link embed
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.createRecord AND repo:app.bsky.feed.post?action=create)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.createRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.feed.post?action=create')]
     public function withLink(
         string|array|Recordable $content,
         string $uri,

src/Client/Records/ProfileRecordClient.php

···
 
 namespace SocialDept\AtpClient\Client\Records;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
 use SocialDept\AtpClient\Data\StrongRef;
+use SocialDept\AtpClient\Enums\Scope;
 
 class ProfileRecordClient extends Request
 {
     /**
      * Update profile
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.putRecord AND repo:app.bsky.actor.profile?action=update)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.putRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.actor.profile?action=update')]
     public function update(array $profile): StrongRef
     {
         // Ensure $type is set
···
             $profile['$type'] = 'app.bsky.actor.profile';
         }
 
-        $response = $this->atp->client->post(
-            endpoint: 'com.atproto.repo.putRecord',
-            body: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.actor.profile',
-                'rkey' => 'self', // Profile records always use 'self' as rkey
-                'record' => $profile,
-            ]
+        $response = $this->atp->atproto->repo->putRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.actor.profile',
+            rkey: 'self', // Profile records always use 'self' as rkey
+            record: $profile
         );
 
         return StrongRef::fromResponse($response->json());
···
 
     /**
      * Get current profile
+     *
+     * @requires transition:generic (rpc:com.atproto.repo.getRecord)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.getRecord')]
     public function get(): array
     {
-        $response = $this->atp->client->get(
-            endpoint: 'com.atproto.repo.getRecord',
-            params: [
-                'repo' => $this->atp->client->sessions->session($this->atp->client->identifier)->did(),
-                'collection' => 'app.bsky.actor.profile',
-                'rkey' => 'self',
-            ]
+        $response = $this->atp->atproto->repo->getRecord(
+            repo: $this->atp->client->session()->did(),
+            collection: 'app.bsky.actor.profile',
+            rkey: 'self'
         );
 
         return $response->json('value');
···
 
     /**
      * Update display name
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.putRecord AND repo:app.bsky.actor.profile?action=update)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.putRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.actor.profile?action=update')]
     public function updateDisplayName(string $displayName): StrongRef
     {
         $profile = $this->getOrCreateProfile();
···
 
     /**
      * Update description/bio
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.putRecord AND repo:app.bsky.actor.profile?action=update)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.putRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.actor.profile?action=update')]
     public function updateDescription(string $description): StrongRef
     {
         $profile = $this->getOrCreateProfile();
···
 
     /**
      * Update avatar
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.putRecord AND repo:app.bsky.actor.profile?action=update)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.putRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.actor.profile?action=update')]
     public function updateAvatar(array $avatarBlob): StrongRef
     {
         $profile = $this->getOrCreateProfile();
···
 
     /**
      * Update banner
+     *
+     * @requires transition:generic OR (rpc:com.atproto.repo.putRecord AND repo:app.bsky.actor.profile?action=update)
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.putRecord')]
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'repo:app.bsky.actor.profile?action=update')]
     public function updateBanner(array $bannerBlob): StrongRef
     {
         $profile = $this->getOrCreateProfile();

src/Client/Requests/Atproto/IdentityRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Atproto;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class IdentityRequestClient extends Request
 {
     /**
      * Resolve handle to DID
+     *
+     * @requires transition:generic (rpc:com.atproto.identity.resolveHandle)
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-identity-resolve-handle
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.identity.resolveHandle')]
     public function resolveHandle(string $handle): Response
     {
         return $this->atp->client->get(
···
     /**
      * Update handle
      *
+     * @requires atproto (identity:handle)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-identity-update-handle
      */
+    #[RequiresScope(Scope::Atproto, granular: 'identity:handle')]
     public function updateHandle(string $handle): Response
     {
         return $this->atp->client->post(

src/Client/Requests/Atproto/RepoRequestClient.php

···
 
 use Illuminate\Http\UploadedFile;
 use InvalidArgumentException;
+use SocialDept\AtpClient\Attributes\RequiresScope;
+use SocialDept\AtpClient\Auth\ScopeChecker;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 use SplFileInfo;
 use Throwable;
···
     /**
      * Create a record
      *
+     * @requires transition:generic OR repo:[collection]?action=create
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-create-record
      */
+    #[RequiresScope(Scope::TransitionGeneric, description: 'Create records in repository')]
     public function createRecord(
         string $repo,
         string $collection,
···
         bool $validate = true,
         ?string $swapCommit = null
     ): Response {
+        $this->checkCollectionScope($collection, 'create');
+
         return $this->atp->client->post(
             endpoint: 'com.atproto.repo.createRecord',
             body: array_filter(
···
 
     /**
      * Delete a record
+     *
+     * @requires transition:generic OR repo:[collection]?action=delete
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-delete-record
      */
+    #[RequiresScope(Scope::TransitionGeneric, description: 'Delete records from repository')]
     public function deleteRecord(
         string $repo,
         string $collection,
···
         ?string $swapRecord = null,
         ?string $swapCommit = null
     ): Response {
+        $this->checkCollectionScope($collection, 'delete');
+
         return $this->atp->client->post(
             endpoint: 'com.atproto.repo.deleteRecord',
             body: array_filter(
···
     /**
      * Put (upsert) a record
      *
+     * @requires transition:generic OR repo:[collection]?action=update
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-put-record
      */
+    #[RequiresScope(Scope::TransitionGeneric, description: 'Update records in repository')]
     public function putRecord(
         string $repo,
         string $collection,
···
         ?string $swapRecord = null,
         ?string $swapCommit = null
     ): Response {
+        $this->checkCollectionScope($collection, 'update');
+
         return $this->atp->client->post(
             endpoint: 'com.atproto.repo.putRecord',
             body: array_filter(
···
     /**
      * Get a record
      *
+     * @requires transition:generic (rpc:com.atproto.repo.getRecord)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-get-record
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.getRecord')]
     public function getRecord(
         string $repo,
         string $collection,
···
     /**
      * List records in a collection
      *
+     * @requires transition:generic (rpc:com.atproto.repo.listRecords)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-list-records
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.listRecords')]
     public function listRecords(
         string $repo,
         string $collection,
···
      *
      * The blob will be deleted if it is not referenced within a time window.
      *
+     * @requires transition:generic (blob:*\/*\)
+     *
      * @param  UploadedFile|SplFileInfo|string  $file  The file to upload
      * @param  string|null  $mimeType  MIME type (required for string input, auto-detected for file objects)
      *
···
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-upload-blob
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'blob:*/*')]
     public function uploadBlob(UploadedFile|SplFileInfo|string $file, ?string $mimeType = null): Response
     {
         // Handle different input types
···
     /**
      * Describe the repository
      *
+     * @requires transition:generic (rpc:com.atproto.repo.describeRepo)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-repo-describe-repo
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:com.atproto.repo.describeRepo')]
     public function describeRepo(string $repo): Response
     {
         return $this->atp->client->get(
             endpoint: 'com.atproto.repo.describeRepo',
             params: compact('repo')
         );
+    }
+
+    /**
+     * Check if the session has repo access for a specific collection and action.
+     *
+     * This check is in addition to the transition:generic scope check.
+     * Users need either transition:generic OR the specific repo scope.
+     */
+    protected function checkCollectionScope(string $collection, string $action): void
+    {
+        $session = $this->atp->client->session();
+        $checker = app(ScopeChecker::class);
+
+        // If user has transition:generic, they have broad access
+        if ($checker->hasScope($session, Scope::TransitionGeneric)) {
+            return;
+        }
+
+        // Otherwise, check for specific repo scope
+        $checker->checkRepoScopeOrFail($session, $collection, $action);
     }
 }

src/Client/Requests/Atproto/ServerRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Atproto;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class ServerRequestClient extends Request
 {
     /**
      * Get current session
+     *
+     * @requires atproto (rpc:com.atproto.server.getSession)
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-server-get-session
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.server.getSession')]
     public function getSession(): Response
     {
         return $this->atp->client->get(
···
     /**
      * Describe server
      *
+     * @requires atproto (rpc:com.atproto.server.describeServer)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-server-describe-server
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.server.describeServer')]
     public function describeServer(): Response
     {
         return $this->atp->client->get(

src/Client/Requests/Atproto/SyncRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Atproto;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class SyncRequestClient extends Request
 {
     /**
      * Get a blob associated with a given account
+     *
+     * @requires atproto (rpc:com.atproto.sync.getBlob)
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-get-blob
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.getBlob')]
     public function getBlob(string $did, string $cid): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Download a repository export as CAR file
+     *
+     * @requires atproto (rpc:com.atproto.sync.getRepo)
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-get-repo
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.getRepo')]
     public function getRepo(string $did, ?string $since = null): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Enumerates all the DID, rev, and commit CID for all repos hosted by this service
+     *
+     * @requires atproto (rpc:com.atproto.sync.listRepos)
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-list-repos
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.listRepos')]
     public function listRepos(int $limit = 500, ?string $cursor = null): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Get the current commit CID & revision of the specified repo
+     *
+     * @requires atproto (rpc:com.atproto.sync.getLatestCommit)
      *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-get-latest-commit
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.getLatestCommit')]
     public function getLatestCommit(string $did): Response
     {
         return $this->atp->client->get(
···
     /**
      * Get data blocks needed to prove the existence or non-existence of record
      *
+     * @requires atproto (rpc:com.atproto.sync.getRecord)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-get-record
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.getRecord')]
     public function getRecord(string $did, string $collection, string $rkey): Response
     {
         return $this->atp->client->get(
···
     /**
      * List blob CIDs for an account, since some repo revision
      *
+     * @requires atproto (rpc:com.atproto.sync.listBlobs)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-list-blobs
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.listBlobs')]
     public function listBlobs(
         string $did,
         ?string $since = null,
···
     /**
      * Get data blocks from a given repo, by CID
      *
+     * @requires atproto (rpc:com.atproto.sync.getBlocks)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-get-blocks
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.getBlocks')]
     public function getBlocks(string $did, array $cids): Response
     {
         return $this->atp->client->get(
···
     /**
      * Get the hosting status for a repository, on this server
      *
+     * @requires atproto (rpc:com.atproto.sync.getRepoStatus)
+     *
      * @see https://docs.bsky.app/docs/api/com-atproto-sync-get-repo-status
      */
+    #[RequiresScope(Scope::Atproto, granular: 'rpc:com.atproto.sync.getRepoStatus')]
     public function getRepoStatus(string $did): Response
     {
         return $this->atp->client->get(

src/Client/Requests/Bsky/ActorRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Bsky;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class ActorRequestClient extends Request
···
     /**
      * Get actor profile
      *
+     * @requires transition:generic (rpc:app.bsky.actor.getProfile)
+     *
      * @see https://docs.bsky.app/docs/api/app-bsky-actor-get-profile
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.actor.getProfile')]
     public function getProfile(string $actor): Response
     {
         return $this->atp->client->get(

src/Client/Requests/Bsky/FeedRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Bsky;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class FeedRequestClient extends Request
···
     /**
      * Get timeline feed
      *
+     * @requires transition:generic (rpc:app.bsky.feed.getTimeline)
+     *
      * @see https://docs.bsky.app/docs/api/app-bsky-feed-get-timeline
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.getTimeline')]
     public function getTimeline(int $limit = 50, ?string $cursor = null): Response
     {
         return $this->atp->client->get(
···
     /**
      * Get author feed
      *
+     * @requires transition:generic (rpc:app.bsky.feed.getAuthorFeed)
+     *
      * @see https://docs.bsky.app/docs/api/app-bsky-feed-get-author-feed
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.getAuthorFeed')]
     public function getAuthorFeed(
         string $actor,
         int $limit = 50,
···
 
     /**
      * Get post thread
+     *
+     * @requires transition:generic (rpc:app.bsky.feed.getPostThread)
      *
      * @see https://docs.bsky.app/docs/api/app-bsky-feed-get-post-thread
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.getPostThread')]
     public function getPostThread(string $uri, int $depth = 6): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Search posts
+     *
+     * @requires transition:generic (rpc:app.bsky.feed.searchPosts)
      *
      * @see https://docs.bsky.app/docs/api/app-bsky-feed-search-posts
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.searchPosts')]
     public function searchPosts(
         string $q,
         int $limit = 25,
···
     /**
      * Get likes for a post
      *
+     * @requires transition:generic (rpc:app.bsky.feed.getLikes)
+     *
      * @see https://docs.bsky.app/docs/api/app-bsky-feed-get-likes
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.getLikes')]
     public function getLikes(
         string $uri,
         int $limit = 50,
···
     /**
      * Get reposts for a post
      *
+     * @requires transition:generic (rpc:app.bsky.feed.getRepostedBy)
+     *
      * @see https://docs.bsky.app/docs/api/app-bsky-feed-get-reposted-by
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.getRepostedBy')]
     public function getRepostedBy(
         string $uri,
         int $limit = 50,

src/Client/Requests/Chat/ActorRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Chat;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class ActorRequestClient extends Request
···
     /**
      * Get actor metadata
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.actor.getActorMetadata)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-actor-export-account-data
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.actor.getActorMetadata')]
     public function getActorMetadata(): Response
     {
         return $this->atp->client->get(
···
     /**
      * Export account data
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.actor.exportAccountData)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-actor-export-account-data
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.actor.exportAccountData')]
     public function exportAccountData(): Response
     {
         return $this->atp->client->get(
···
     /**
      * Delete account
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.actor.deleteAccount)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-actor-delete-account
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.actor.deleteAccount')]
     public function deleteAccount(): Response
     {
         return $this->atp->client->post(

src/Client/Requests/Chat/ConvoRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Chat;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class ConvoRequestClient extends Request
···
     /**
      * Get conversation
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.getConvo)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-get-convo
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.getConvo')]
     public function getConvo(string $convoId): Response
     {
         return $this->atp->client->get(
···
     /**
      * Get conversation for members
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.getConvoForMembers)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-get-convo-for-members
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.getConvoForMembers')]
     public function getConvoForMembers(array $members): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * List conversations
+     *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.listConvos)
      *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-list-convos
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.listConvos')]
     public function listConvos(int $limit = 50, ?string $cursor = null): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Get messages
+     *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.getMessages)
      *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-get-messages
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.getMessages')]
     public function getMessages(
         string $convoId,
         int $limit = 50,
···
     /**
      * Send message
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.sendMessage)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-send-message
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.sendMessage')]
     public function sendMessage(string $convoId, array $message): Response
     {
         return $this->atp->client->post(
···
 
     /**
      * Send message batch
+     *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.sendMessageBatch)
      *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-send-message-batch
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.sendMessageBatch')]
     public function sendMessageBatch(array $items): Response
     {
         return $this->atp->client->post(
···
 
     /**
      * Delete message for self
+     *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.deleteMessageForSelf)
      *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-delete-message-for-self
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.deleteMessageForSelf')]
     public function deleteMessageForSelf(string $convoId, string $messageId): Response
     {
         return $this->atp->client->post(
···
     /**
      * Update read status
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.updateRead)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-update-read
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.updateRead')]
     public function updateRead(string $convoId, ?string $messageId = null): Response
     {
         return $this->atp->client->post(
···
     /**
      * Mute conversation
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.muteConvo)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-mute-convo
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.muteConvo')]
     public function muteConvo(string $convoId): Response
     {
         return $this->atp->client->post(
···
     /**
      * Unmute conversation
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.unmuteConvo)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-unmute-convo
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.unmuteConvo')]
     public function unmuteConvo(string $convoId): Response
     {
         return $this->atp->client->post(
···
 
     /**
      * Leave conversation
+     *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.leaveConvo)
      *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-leave-convo
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.leaveConvo')]
     public function leaveConvo(string $convoId): Response
     {
         return $this->atp->client->post(
···
     /**
      * Get log
      *
+     * @requires transition:chat.bsky (rpc:chat.bsky.convo.getLog)
+     *
      * @see https://docs.bsky.app/docs/api/chat-bsky-convo-get-log
      */
+    #[RequiresScope(Scope::TransitionChat, granular: 'rpc:chat.bsky.convo.getLog')]
     public function getLog(?string $cursor = null): Response
     {
         return $this->atp->client->get(

src/Client/Requests/Ozone/ModerationRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Ozone;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class ModerationRequestClient extends Request
 {
     /**
      * Get moderation event
+     *
+     * @requires transition:generic (rpc:tools.ozone.moderation.getEvent)
      *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-get-event
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.getEvent')]
     public function getModerationEvent(int $id): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Get moderation events
+     *
+     * @requires transition:generic (rpc:tools.ozone.moderation.getEvents)
      *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-query-events
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.getEvents')]
     public function getModerationEvents(
         ?string $subject = null,
         ?array $types = null,
···
     /**
      * Get record
      *
+     * @requires transition:generic (rpc:tools.ozone.moderation.getRecord)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-get-record
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.getRecord')]
     public function getRecord(string $uri, ?string $cid = null): Response
     {
         return $this->atp->client->get(
···
 
     /**
      * Get repo
+     *
+     * @requires transition:generic (rpc:tools.ozone.moderation.getRepo)
      *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-get-repo
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.getRepo')]
     public function getRepo(string $did): Response
     {
         return $this->atp->client->get(
···
     /**
      * Query events
      *
+     * @requires transition:generic (rpc:tools.ozone.moderation.queryEvents)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-query-events
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.queryEvents')]
     public function queryEvents(
         ?array $types = null,
         ?string $createdBy = null,
···
     /**
      * Query statuses
      *
+     * @requires transition:generic (rpc:tools.ozone.moderation.queryStatuses)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-query-statuses
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.queryStatuses')]
     public function queryStatuses(
         ?string $subject = null,
         ?array $tags = null,
···
     /**
      * Search repos
      *
+     * @requires transition:generic (rpc:tools.ozone.moderation.searchRepos)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-search-repos
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.searchRepos')]
     public function searchRepos(
         ?string $term = null,
         ?string $invitedBy = null,
···
     /**
      * Emit moderation event
      *
+     * @requires transition:generic (rpc:tools.ozone.moderation.emitEvent)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-moderation-emit-event
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.moderation.emitEvent')]
     public function emitEvent(
         array $event,
         string $subject,

src/Client/Requests/Ozone/ServerRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Ozone;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class ServerRequestClient extends Request
 {
     /**
      * Get blob
+     *
+     * @requires transition:generic (rpc:tools.ozone.server.getBlob)
      *
      * @see https://docs.bsky.app/docs/api/tools-ozone-server-get-config
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.server.getBlob')]
     public function getBlob(string $did, string $cid): Response
     {
         return $this->atp->client->get(
···
     /**
      * Get config
      *
+     * @requires transition:generic (rpc:tools.ozone.server.getConfig)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-server-get-config
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.server.getConfig')]
     public function getConfig(): Response
     {
         return $this->atp->client->get(

src/Client/Requests/Ozone/TeamRequestClient.php

···
 
 namespace SocialDept\AtpClient\Client\Requests\Ozone;
 
+use SocialDept\AtpClient\Attributes\RequiresScope;
 use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Http\Response;
 
 class TeamRequestClient extends Request
···
     /**
      * Get team member
      *
+     * @requires transition:generic (rpc:tools.ozone.team.getMember)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-team-list-members
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.team.getMember')]
     public function getTeamMember(string $did): Response
     {
         return $this->atp->client->get(
···
     /**
      * List team members
      *
+     * @requires transition:generic (rpc:tools.ozone.team.listMembers)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-team-list-members
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.team.listMembers')]
     public function listTeamMembers(int $limit = 50, ?string $cursor = null): Response
     {
         return $this->atp->client->get(
···
     /**
      * Add team member
      *
+     * @requires transition:generic (rpc:tools.ozone.team.addMember)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-team-add-member
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.team.addMember')]
     public function addTeamMember(string $did, string $role): Response
     {
         return $this->atp->client->post(
···
 
     /**
      * Update team member
+     *
+     * @requires transition:generic (rpc:tools.ozone.team.updateMember)
      *
      * @see https://docs.bsky.app/docs/api/tools-ozone-team-update-member
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.team.updateMember')]
     public function updateTeamMember(
         string $did,
         ?bool $disabled = null,
···
     /**
      * Delete team member
      *
+     * @requires transition:generic (rpc:tools.ozone.team.deleteMember)
+     *
      * @see https://docs.bsky.app/docs/api/tools-ozone-team-delete-member
      */
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:tools.ozone.team.deleteMember')]
     public function deleteTeamMember(string $did): Response
     {
         return $this->atp->client->post(

src/Contracts/HasAtpSession.php

···
+<?php
+
+namespace SocialDept\AtpClient\Contracts;
+
+interface HasAtpSession
+{
+    /**
+     * Get the ATP DID associated with this model.
+     */
+    public function getAtpDid(): ?string;
+}

src/Data/AccessToken.php

···
 
 namespace SocialDept\AtpClient\Data;
 
+use SocialDept\AtpClient\Enums\AuthType;
+
 class AccessToken
 {
     public function __construct(
···
         public readonly ?string $handle = null,
         public readonly ?string $issuer = null,
         public readonly array $scope = [],
+        public readonly AuthType $authType = AuthType::OAuth,
     ) {}
 
     /**
···
                 handle: $handle,
                 issuer: $issuer,
                 scope: isset($data['scope']) ? explode(' ', $data['scope']) : [],
+                authType: AuthType::OAuth,
             );
         }
 
···
             handle: $data['handle'] ?? $handle,
             issuer: $issuer,
             scope: ['atproto', 'transition:generic', 'transition:email'],
+            authType: AuthType::Legacy,
         );
     }
 }

src/Data/Credentials.php

···
 
 namespace SocialDept\AtpClient\Data;
 
+use SocialDept\AtpClient\Enums\AuthType;
+
 class Credentials
 {
     public function __construct(
···
         public readonly ?string $handle = null,
         public readonly ?string $issuer = null,
         public readonly array $scope = [],
+        public readonly AuthType $authType = AuthType::OAuth,
     ) {}
 
     public function isExpired(): bool

src/Enums/AuthType.php

···
+<?php
+
+namespace SocialDept\AtpClient\Enums;
+
+enum AuthType: string
+{
+    case OAuth = 'oauth';
+    case Legacy = 'legacy';
+}

src/Enums/Scope.php

···
+<?php
+
+namespace SocialDept\AtpClient\Enums;
+
+enum Scope: string
+{
+    // Transition scopes (current)
+    case Atproto = 'atproto';
+    case TransitionGeneric = 'transition:generic';
+    case TransitionEmail = 'transition:email';
+    case TransitionChat = 'transition:chat.bsky';
+
+    /**
+     * Build a repo scope string for record operations.
+     *
+     * @param  string  $collection  The collection NSID (e.g., 'app.bsky.feed.post')
+     * @param  string|null  $action  The action (create, update, delete)
+     */
+    public static function repo(string $collection, ?string $action = null): string
+    {
+        $scope = "repo:{$collection}";
+
+        if ($action !== null) {
+            $scope .= "?action={$action}";
+        }
+
+        return $scope;
+    }
+
+    /**
+     * Build an RPC scope string for endpoint access.
+     *
+     * @param  string  $lxm  The lexicon method ID (e.g., 'app.bsky.feed.getTimeline')
+     */
+    public static function rpc(string $lxm): string
+    {
+        return "rpc:{$lxm}";
+    }
+
+    /**
+     * Build a blob scope string for uploads.
+     *
+     * @param  string|null  $mimeType  The mime type pattern (e.g., 'image/*', '*\/*')
+     */
+    public static function blob(?string $mimeType = null): string
+    {
+        return 'blob:'.($mimeType ?? '*/*');
+    }
+
+    /**
+     * Build an account scope string.
+     *
+     * @param  string  $attr  The account attribute (e.g., 'email', 'status')
+     */
+    public static function account(string $attr): string
+    {
+        return "account:{$attr}";
+    }
+
+    /**
+     * Build an identity scope string.
+     *
+     * @param  string  $attr  The identity attribute (e.g., 'handle')
+     */
+    public static function identity(string $attr): string
+    {
+        return "identity:{$attr}";
+    }
+}

src/Enums/ScopeAuthorizationFailure.php

···
+<?php
+
+namespace SocialDept\AtpClient\Enums;
+
+enum ScopeAuthorizationFailure: string
+{
+    case Abort = 'abort';
+    case Redirect = 'redirect';
+    case Exception = 'exception';
+}

src/Enums/ScopeEnforcementLevel.php

···
+<?php
+
+namespace SocialDept\AtpClient\Enums;
+
+enum ScopeEnforcementLevel: string
+{
+    case Strict = 'strict';
+    case Permissive = 'permissive';
+}

src/Events/OAuthTokenRefreshed.php src/Events/TokenRefreshed.php

···
 use SocialDept\AtpClient\Data\AccessToken;
 use SocialDept\AtpClient\Session\Session;
 
-class OAuthTokenRefreshed
+class TokenRefreshed
 {
     use Dispatchable, SerializesModels;
 

src/Events/OAuthTokenRefreshing.php src/Events/TokenRefreshing.php

···
 use Illuminate\Queue\SerializesModels;
 use SocialDept\AtpClient\Session\Session;
 
-class OAuthTokenRefreshing
+class TokenRefreshing
 {
     use Dispatchable, SerializesModels;
 

src/Exceptions/MissingScopeException.php

···
+<?php
+
+namespace SocialDept\AtpClient\Exceptions;
+
+class MissingScopeException extends \Exception
+{
+    public function __construct(
+        public readonly array $required,
+        public readonly array $granted,
+        ?string $message = null,
+    ) {
+        parent::__construct($message ?? $this->buildMessage());
+    }
+
+    protected function buildMessage(): string
+    {
+        $required = implode(', ', $this->required);
+        $granted = empty($this->granted) ? 'none' : implode(', ', $this->granted);
+
+        return "Missing required scope(s): {$required}. Granted: {$granted}.";
+    }
+}

src/Exceptions/ScopeAuthorizationException.php

···
+<?php
+
+namespace SocialDept\AtpClient\Exceptions;
+
+use Illuminate\Http\Request;
+use SocialDept\AtpClient\Enums\ScopeAuthorizationFailure;
+use Symfony\Component\HttpFoundation\Response;
+
+class ScopeAuthorizationException extends MissingScopeException
+{
+    /**
+     * Render the exception as an HTTP response.
+     */
+    public function render(Request $request): Response
+    {
+        $action = config('atp-client.scope_authorization.failure_action', ScopeAuthorizationFailure::Abort);
+
+        return match ($action) {
+            ScopeAuthorizationFailure::Redirect => redirect(
+                config('atp-client.scope_authorization.redirect_to', '/login')
+            ),
+            ScopeAuthorizationFailure::Exception => throw $this,
+            default => abort(403, $this->getMessage()),
+        };
+    }
+}

src/Facades/Atp.php

···
 use SocialDept\AtpClient\Contracts\CredentialProvider;
 
 /**
- * @method static AtpClient as(string $handleOrDid)
- * @method static AtpClient login(string $handleOrDid, string $password)
+ * @method static AtpClient as(string $actor)
+ * @method static AtpClient login(string $actor, string $password)
  * @method static OAuthEngine oauth()
  * @method static void setDefaultProvider(CredentialProvider $provider)
  *

src/Facades/AtpScope.php

···
+<?php
+
+namespace SocialDept\AtpClient\Facades;
+
+use Illuminate\Support\Facades\Facade;
+use SocialDept\AtpClient\Auth\ScopeGate;
+use SocialDept\AtpClient\Enums\Scope;
+use SocialDept\AtpClient\Session\Session;
+
+/**
+ * @method static ScopeGate forSession(Session $session)
+ * @method static ScopeGate forUser(string $actor)
+ * @method static bool can(string|Scope $scope)
+ * @method static bool canAny(array $scopes)
+ * @method static bool canAll(array $scopes)
+ * @method static bool cannot(string|Scope $scope)
+ * @method static void authorize(string|Scope ...$scopes)
+ * @method static array granted()
+ *
+ * @see \SocialDept\AtpClient\Auth\ScopeGate
+ */
+class AtpScope extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return 'atp-scope';
+    }
+}

src/Http/HasHttp.php

···
 namespace SocialDept\AtpClient\Http;
 
 use Illuminate\Http\Client\Response as LaravelResponse;
+use Illuminate\Support\Facades\Http;
 use InvalidArgumentException;
+use SocialDept\AtpClient\Auth\ScopeChecker;
+use SocialDept\AtpClient\Enums\Scope;
 use SocialDept\AtpClient\Exceptions\ValidationException;
 use SocialDept\AtpClient\Session\Session;
 use SocialDept\AtpClient\Session\SessionManager;
···
     protected string $did;
 
     protected DPoPClient $dpopClient;
+
+    protected ?ScopeChecker $scopeChecker = null;
 
     /**
      * Make XRPC call
···
     }
 
     /**
-     * Build authenticated request with DPoP proof and automatic nonce retry
+     * Build authenticated request.
+     *
+     * OAuth sessions use DPoP proof with Bearer token.
+     * Legacy sessions use plain Bearer token.
      */
     protected function buildAuthenticatedRequest(
         Session $session,
         string $url,
         string $method
     ): \Illuminate\Http\Client\PendingRequest {
+        if ($session->isLegacy()) {
+            return Http::withHeader('Authorization', 'Bearer '.$session->accessToken());
+        }
+
         return $this->dpopClient->request(
             pdsEndpoint: $session->pdsEndpoint(),
             url: $url,
···
             ->post($url);
 
         return new Response($response);
+    }
+
+    /**
+     * Require specific scopes before making a request.
+     *
+     * Checks if the session has the required scopes. In strict mode, throws
+     * MissingScopeException if scopes are missing. In permissive mode, logs
+     * a warning but allows the request to proceed.
+     *
+     * @param  string|Scope  ...$scopes  The required scopes
+     *
+     * @throws \SocialDept\AtpClient\Exceptions\MissingScopeException
+     */
+    protected function requireScopes(string|Scope ...$scopes): void
+    {
+        $session = $this->sessions->session($this->did);
+
+        $this->getScopeChecker()->checkOrFail($session, $scopes);
+    }
+
+    /**
+     * Check if the session has a specific scope.
+     */
+    protected function hasScope(string|Scope $scope): bool
+    {
+        $session = $this->sessions->session($this->did);
+
+        return $this->getScopeChecker()->hasScope($session, $scope);
+    }
+
+    /**
+     * Get the scope checker instance.
+     */
+    protected function getScopeChecker(): ScopeChecker
+    {
+        if ($this->scopeChecker === null) {
+            $this->scopeChecker = app(ScopeChecker::class);
+        }
+
+        return $this->scopeChecker;
     }
 }

src/Http/Middleware/RequiresScopeMiddleware.php

···
+<?php
+
+namespace SocialDept\AtpClient\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use SocialDept\AtpClient\Auth\ScopeChecker;
+use SocialDept\AtpClient\Contracts\HasAtpSession;
+use SocialDept\AtpClient\Enums\ScopeAuthorizationFailure;
+use SocialDept\AtpClient\Exceptions\ScopeAuthorizationException;
+use SocialDept\AtpClient\Session\SessionManager;
+use Symfony\Component\HttpFoundation\Response;
+
+class RequiresScopeMiddleware
+{
+    public function __construct(
+        protected SessionManager $sessions,
+        protected ScopeChecker $checker,
+    ) {}
+
+    /**
+     * Handle an incoming request.
+     *
+     * @param  string  ...$scopes
+     */
+    public function handle(Request $request, Closure $next, string ...$scopes): Response
+    {
+        $user = $request->user();
+
+        // Ensure user is authenticated
+        if (! $user) {
+            return $this->handleFailure(
+                new ScopeAuthorizationException($scopes, [], 'User not authenticated.')
+            );
+        }
+
+        // Ensure user implements HasAtpSession
+        if (! $user instanceof HasAtpSession) {
+            return $this->handleFailure(
+                new ScopeAuthorizationException($scopes, [], 'User model must implement HasAtpSession interface.')
+            );
+        }
+
+        $did = $user->getAtpDid();
+
+        if (! $did) {
+            return $this->handleFailure(
+                new ScopeAuthorizationException($scopes, [], 'User has no ATP session.')
+            );
+        }
+
+        try {
+            $session = $this->sessions->session($did);
+        } catch (\Exception $e) {
+            return $this->handleFailure(
+                new ScopeAuthorizationException($scopes, [], 'Could not retrieve ATP session: '.$e->getMessage())
+            );
+        }
+
+        // Check ALL scopes (AND logic)
+        if (! $this->checker->check($session, $scopes)) {
+            $granted = $session->scopes();
+            $missing = array_diff($scopes, $granted);
+
+            return $this->handleFailure(
+                new ScopeAuthorizationException($missing, $granted)
+            );
+        }
+
+        return $next($request);
+    }
+
+    protected function handleFailure(ScopeAuthorizationException $exception): Response
+    {
+        $action = config('atp-client.scope_authorization.failure_action', ScopeAuthorizationFailure::Abort);
+
+        return match ($action) {
+            ScopeAuthorizationFailure::Redirect => redirect(
+                config('atp-client.scope_authorization.redirect_to', '/login')
+            ),
+            ScopeAuthorizationFailure::Exception => throw $exception,
+            default => abort(403, $exception->getMessage()),
+        };
+    }
+}

src/Providers/ArrayCredentialProvider.php

···
             handle: $token->handle,
             issuer: $token->issuer,
             scope: $token->scope,
+            authType: $token->authType,
         );
     }
 

src/Providers/CacheCredentialProvider.php

···
+<?php
+
+namespace SocialDept\AtpClient\Providers;
+
+use Illuminate\Support\Facades\Cache;
+use SocialDept\AtpClient\Contracts\CredentialProvider;
+use SocialDept\AtpClient\Data\AccessToken;
+use SocialDept\AtpClient\Data\Credentials;
+
+class CacheCredentialProvider implements CredentialProvider
+{
+    protected string $prefix = 'atp:credentials:';
+
+    public function getCredentials(string $did): ?Credentials
+    {
+        return Cache::get($this->key($did));
+    }
+
+    public function storeCredentials(string $did, AccessToken $token): void
+    {
+        Cache::put($this->key($did), $this->toCredentials($token));
+    }
+
+    public function updateCredentials(string $did, AccessToken $token): void
+    {
+        $this->storeCredentials($did, $token);
+    }
+
+    public function removeCredentials(string $did): void
+    {
+        Cache::forget($this->key($did));
+    }
+
+    protected function key(string $did): string
+    {
+        return $this->prefix.$did;
+    }
+
+    protected function toCredentials(AccessToken $token): Credentials
+    {
+        return new Credentials(
+            did: $token->did,
+            accessToken: $token->accessJwt,
+            refreshToken: $token->refreshJwt,
+            expiresAt: $token->expiresAt,
+            handle: $token->handle,
+            issuer: $token->issuer,
+            scope: $token->scope,
+            authType: $token->authType,
+        );
+    }
+}

src/Providers/FileCredentialProvider.php

···
+<?php
+
+namespace SocialDept\AtpClient\Providers;
+
+use SocialDept\AtpClient\Contracts\CredentialProvider;
+use SocialDept\AtpClient\Data\AccessToken;
+use SocialDept\AtpClient\Data\Credentials;
+
+class FileCredentialProvider implements CredentialProvider
+{
+    protected string $storagePath;
+
+    public function __construct(?string $storagePath = null)
+    {
+        $this->storagePath = $storagePath ?? storage_path('app/atp-credentials');
+
+        if (! is_dir($this->storagePath)) {
+            mkdir($this->storagePath, 0755, true);
+        }
+    }
+
+    public function getCredentials(string $did): ?Credentials
+    {
+        $path = $this->path($did);
+
+        if (! file_exists($path)) {
+            return null;
+        }
+
+        return unserialize(file_get_contents($path));
+    }
+
+    public function storeCredentials(string $did, AccessToken $token): void
+    {
+        file_put_contents($this->path($did), serialize($this->toCredentials($token)));
+    }
+
+    public function updateCredentials(string $did, AccessToken $token): void
+    {
+        $this->storeCredentials($did, $token);
+    }
+
+    public function removeCredentials(string $did): void
+    {
+        $path = $this->path($did);
+
+        if (file_exists($path)) {
+            unlink($path);
+        }
+    }
+
+    protected function path(string $did): string
+    {
+        return $this->storagePath.'/'.hash('sha256', $did).'.cred';
+    }
+
+    protected function toCredentials(AccessToken $token): Credentials
+    {
+        return new Credentials(
+            did: $token->did,
+            accessToken: $token->accessJwt,
+            refreshToken: $token->refreshJwt,
+            expiresAt: $token->expiresAt,
+            handle: $token->handle,
+            issuer: $token->issuer,
+            scope: $token->scope,
+            authType: $token->authType,
+        );
+    }
+}

src/Providers/SessionCredentialProvider.php

···
+<?php
+
+namespace SocialDept\AtpClient\Providers;
+
+use Illuminate\Support\Facades\Session;
+use SocialDept\AtpClient\Contracts\CredentialProvider;
+use SocialDept\AtpClient\Data\AccessToken;
+use SocialDept\AtpClient\Data\Credentials;
+
+class SessionCredentialProvider implements CredentialProvider
+{
+    protected string $prefix = 'atp.credentials.';
+
+    public function getCredentials(string $did): ?Credentials
+    {
+        return Session::get($this->key($did));
+    }
+
+    public function storeCredentials(string $did, AccessToken $token): void
+    {
+        Session::put($this->key($did), $this->toCredentials($token));
+    }
+
+    public function updateCredentials(string $did, AccessToken $token): void
+    {
+        $this->storeCredentials($did, $token);
+    }
+
+    public function removeCredentials(string $did): void
+    {
+        Session::forget($this->key($did));
+    }
+
+    protected function key(string $did): string
+    {
+        return $this->prefix.$did;
+    }
+
+    protected function toCredentials(AccessToken $token): Credentials
+    {
+        return new Credentials(
+            did: $token->did,
+            accessToken: $token->accessJwt,
+            refreshToken: $token->refreshJwt,
+            expiresAt: $token->expiresAt,
+            handle: $token->handle,
+            issuer: $token->issuer,
+            scope: $token->scope,
+            authType: $token->authType,
+        );
+    }
+}

src/Session/Session.php

···
 
 use SocialDept\AtpClient\Data\Credentials;
 use SocialDept\AtpClient\Data\DPoPKey;
+use SocialDept\AtpClient\Enums\AuthType;
+use SocialDept\AtpClient\Enums\Scope;
 
 class Session
 {
···
     public function hasScope(string $scope): bool
     {
         return in_array($scope, $this->credentials->scope, true);
+    }
+
+    /**
+     * Check if the session has the given scope (alias for hasScope with Scope enum support).
+     */
+    public function can(string|Scope $scope): bool
+    {
+        $scopeValue = $scope instanceof Scope ? $scope->value : $scope;
+
+        return $this->hasScope($scopeValue);
+    }
+
+    /**
+     * Check if the session has any of the given scopes.
+     *
+     * @param  array<string|Scope>  $scopes
+     */
+    public function canAny(array $scopes): bool
+    {
+        foreach ($scopes as $scope) {
+            if ($this->can($scope)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Check if the session has all of the given scopes.
+     *
+     * @param  array<string|Scope>  $scopes
+     */
+    public function canAll(array $scopes): bool
+    {
+        foreach ($scopes as $scope) {
+            if (! $this->can($scope)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Check if the session does NOT have the given scope.
+     */
+    public function cannot(string|Scope $scope): bool
+    {
+        return ! $this->can($scope);
+    }
+
+    public function authType(): AuthType
+    {
+        return $this->credentials->authType;
+    }
+
+    public function isLegacy(): bool
+    {
+        return $this->credentials->authType === AuthType::Legacy;
     }
 
     public function withCredentials(Credentials $credentials): self

src/Session/SessionManager.php

···
 use SocialDept\AtpClient\Contracts\CredentialProvider;
 use SocialDept\AtpClient\Contracts\KeyStore;
 use SocialDept\AtpClient\Data\AccessToken;
-use SocialDept\AtpClient\Events\OAuthTokenRefreshed;
-use SocialDept\AtpClient\Events\OAuthTokenRefreshing;
+use SocialDept\AtpClient\Events\TokenRefreshed;
+use SocialDept\AtpClient\Events\TokenRefreshing;
 use SocialDept\AtpClient\Exceptions\AuthenticationException;
 use SocialDept\AtpClient\Exceptions\HandleResolutionException;
 use SocialDept\AtpClient\Exceptions\SessionExpiredException;
 use SocialDept\AtpResolver\Facades\Resolver;
+use SocialDept\Resolver\Support\Identity;
 
 class SessionManager
 {
···
     ) {}
 
     /**
-     * Resolve a handle or DID to a DID.
+     * Resolve an actor (handle or DID) to a DID.
      *
      * @throws HandleResolutionException
      */
-    protected function resolveToDid(string $handleOrDid): string
+    protected function resolveToDid(string $actor): string
     {
         // If already a DID, return as-is
-        if (str_starts_with($handleOrDid, 'did:')) {
-            return $handleOrDid;
+        if (Identity::isDid($actor)) {
+            return $actor;
         }
 
         // Resolve handle to DID
-        $did = Resolver::handleToDid($handleOrDid);
+        $did = Resolver::handleToDid($actor);
 
         if (! $did) {
-            throw new HandleResolutionException($handleOrDid);
+            throw new HandleResolutionException($actor);
         }
 
         return $did;
     }
 
     /**
-     * Get or create session for handle or DID
+     * Get or create session for an actor.
      */
-    public function session(string $handleOrDid): Session
+    public function session(string $actor): Session
     {
-        $did = $this->resolveToDid($handleOrDid);
+        $did = $this->resolveToDid($actor);
 
         if (! isset($this->sessions[$did])) {
             $this->sessions[$did] = $this->createSession($did);
···
     }
 
     /**
-     * Ensure session is valid, refresh if needed
+     * Ensure session is valid, refresh if needed.
      */
-    public function ensureValid(string $handleOrDid): Session
+    public function ensureValid(string $actor): Session
     {
-        $session = $this->session($handleOrDid);
+        $session = $this->session($actor);
 
         // Check if token needs refresh
         if ($session->expiresIn() < $this->refreshThreshold) {
···
     }
 
     /**
-     * Create session from app password
+     * Create session from app password.
      */
     public function fromAppPassword(
-        string $handleOrDid,
+        string $actor,
         string $password
     ): Session {
-        $did = $this->resolveToDid($handleOrDid);
+        $did = $this->resolveToDid($actor);
         $pdsEndpoint = Resolver::resolvePds($did);
 
         $response = Http::post($pdsEndpoint.'/xrpc/com.atproto.server.createSession', [
-            'identifier' => $handleOrDid,
+            'identifier' => $actor,
             'password' => $password,
         ]);
 
···
             throw new AuthenticationException('Login failed');
         }
 
-        $token = AccessToken::fromResponse($response->json(), $handleOrDid, $pdsEndpoint);
+        $token = AccessToken::fromResponse($response->json(), $actor, $pdsEndpoint);
 
         // Store credentials using DID as key
         $this->credentials->storeCredentials($did, $token);
···
         $did = $session->did();
 
         // Fire event before refresh (allows developers to invalidate old token)
-        event(new OAuthTokenRefreshing($session));
+        event(new TokenRefreshing($session));
 
         $newToken = $this->refresher->refresh(
             refreshToken: $session->refreshToken(),
             pdsEndpoint: $session->pdsEndpoint(),
             dpopKey: $session->dpopKey(),
             handle: $session->handle(),
+            authType: $session->authType(),
         );
 
         // Update credentials (CRITICAL: refresh tokens are single-use)
         $this->credentials->updateCredentials($did, $newToken);
 
         // Fire event after successful refresh
-        event(new OAuthTokenRefreshed($session, $newToken));
+        event(new TokenRefreshed($session, $newToken));
 
         // Update session
         $newCreds = $this->credentials->getCredentials($did);