Merge pull request #665 from hypervel/feature/passport

Add Passport OAuth 2.0 server

Author: binaryfire

composer.json

@@ -47,6 +47,7 @@
         "aws/aws-sdk-php": "^3.322.9",
         "brick/math": "^1.0",
         "chillerlan/php-qrcode": "^6.0",
+        "defuse/php-encryption": "^2.4",
         "doctrine/inflector": "^2.0.5",
         "dragonmantank/cron-expression": "^3.4",
         "egulias/email-validator": "^4.0",
@@ -59,12 +60,13 @@
         "guzzlehttp/psr7": "^2.13 || ^3.1",
         "guzzlehttp/uri-template": "^1.0 || ^2.0",
         "laravel/serializable-closure": "^2.0.11",
-        "lcobucci/jwt": "^5.0",
+        "lcobucci/jwt": "^5.6",
         "league/commonmark": "^2.10.3",
         "league/flysystem": "^3.25.1",
         "league/flysystem-aws-s3-v3": "^3.25.1",
         "league/flysystem-path-prefixing": "^3.25.1",
         "league/flysystem-read-only": "^3.25.1",
+        "league/oauth2-server": "^9.4",
         "league/uri": "^7.5.1",
         "monolog/monolog": "^3.10",
         "nesbot/carbon": "^3.13.1",
@@ -189,6 +191,7 @@
         "hypervel/opentelemetry": "self.version",
         "hypervel/pagination": "self.version",
         "hypervel/passkeys": "self.version",
+        "hypervel/passport": "self.version",
         "hypervel/permission": "self.version",
         "hypervel/pipeline": "self.version",
         "hypervel/process": "self.version",
@@ -274,6 +277,8 @@
             "Hypervel\\OpenTelemetry\\": "src/opentelemetry/src/",
             "Hypervel\\Pagination\\": "src/pagination/src/",
             "Hypervel\\Passkeys\\": "src/passkeys/src/",
+            "Hypervel\\Passport\\": "src/passport/src/",
+            "Hypervel\\Passport\\Database\\Factories\\": "src/passport/database/factories/",
             "Hypervel\\Permission\\": "src/permission/src/",
             "Hypervel\\Pipeline\\": "src/pipeline/src/",
             "Hypervel\\Process\\": "src/process/src/",
@@ -398,6 +403,7 @@
                 "Hypervel\\Passkeys\\PasskeysServiceProvider",
                 "Hypervel\\Fortify\\FortifyServiceProvider",
                 "Hypervel\\Grpc\\GrpcServiceProvider",
+                "Hypervel\\Passport\\PassportServiceProvider",
                 "Hypervel\\Permission\\PermissionServiceProvider",
                 "Hypervel\\Pipeline\\PipelineServiceProvider",
                 "Hypervel\\Queue\\QueueServiceProvider",

docs/plans/2026-10-12-0000-hypervel-passport.md

@@ -3,8 +3,6 @@
 ## Authentication
 
 - Create hypervel/react-starter-kit. Include the standard skeleton pieces that currently only exist as follow-ups: a `composer dev` script for running the Hypervel development server and frontend asset watcher together, plus explicit Hypervel Vite refresh paths instead of the Laravel plugin's `refresh: true` shortcut.
-- Port Passport package
-- Replace permission package fake Passport client-credentials coverage with real Passport tests once Passport is ported. The current tests use a local fake guard/client so the permission package can keep Passport middleware parity without depending on a package that does not exist yet.
 
 ## Artisan
 

docs/todo.md

@@ -71,6 +71,32 @@ laravel/sanctum:
   last_reviewed_pr: 620
   sync_date: '2026-10-02'
 
+laravel/passport:
+  branch: 13.x
+  checked_through: f5f5e9f64559dd52339daa0d6102cb1c30e4a0d7
+  last_reviewed_pr: null
+  sync_date: '2026-10-14'
+  notes: >-
+    PassportServiceProvider's server and grant construction maps to ServerFactory;
+    KeysCommand's phpseclib key generation maps to the OpenSSL-based KeyGenerator.
+    Token issuance changes also affect Bridge/AuthorizationServer, Bridge/TokenIssuance
+    and the bridge grants and repositories; credential lookup and mutation changes
+    also affect PassportCache, TokenRelation and ClientRelation. Bridge/BearerTokenValidator
+    adapts League's AuthorizationValidators/BearerTokenValidator, and
+    Bridge/AccessToken::convertToJWT() replaces League's AccessTokenTrait method;
+    compare these with league/oauth2-server when its dependency version changes.
+    Also recheck League's grant-to-repository call order against TokenIssuance's
+    validation, claim and commit boundaries, and its public request entry points
+    against Bridge/AuthorizationServer and Bridge/ResourceServer's delegation to
+    the current settings. Compare Bridge/ParsedKey and RsaSigner with lcobucci/jwt's
+    key checks and signing behavior when that dependency changes.
+    Upstream tests retain their Feature and Unit paths under tests/Passport;
+    jasonmccreary/double test doubles use Mockery here. Workbench user models and
+    factories map to tests/Passport/Fixtures. Test keys
+    are generated in per-process temporary directories by PassportTestCase, using
+    SigningKeyFactory's shared test key, rather than upstream's tests/keys directory.
+    User documentation maps to src/docs/passport.md through the laravel/docs entry.
+
 laravel/socialite:
   branch: 5.x
   checked_through: fa0181ee6204ca28a55cd67145fadd631ac209cf
@@ -164,7 +190,7 @@ spatie/laravel-permission:
   checked_through: 6615eefac655efcd652fe394a20cbdf4f72c609f
   last_reviewed_pr: null
   sync_date: '2026-10-05'
-  notes: Upstream Pest files map to PHPUnit classes at the same paths under tests/Permission, with each it()/test() description as the method name. Upstream's permission.testing migration flag, which adds the roles team column while teams are off so cases can enable teams mid-test, is not ported; those cases enable teams before migrating through the DefineEnvironment attribute's usesTeams method. The CACHE_DRIVER cache-driver test runs map to CACHE_STORE. Passport::actingAsClient() maps to TestCase::actingAsClient() with the PassportGuard fixture because Hypervel has no Passport package. Upstream's single cached permission collection maps to PermissionRegistrar's catalog payload (getSerializedPermissionsForCache() stores role keys per permission; permissionCatalog() and modelClassCatalog() hydrate it) plus the per-model assignment caches (rememberModel*()), which are filled through Cache\ModelCacheCoordinator and invalidated after commit; apply upstream cache or loading changes to both. Upstream relation definitions map to the Role and Permission relation methods built through BuildsPermissionRelations, whose Partitioned* relations add partition and team constraints and loaded-relation tracking. Upstream's detach-then-attach syncs map to HasRoles::syncRoles() and HasPermissions::synchronizePermissionAssignments(), which read the current pivots and write only the differences, keeping each permission's is_denied effect. Upstream docs map to sections of src/docs/permission.md; the example app, PhpStorm, UI options, schema diagram, upgrade and project pages are not ported. Upstream's ide.json code-generation metadata for the Laravel Idea PhpStorm plugin is not ported either.
+  notes: Upstream Pest files map to PHPUnit classes at the same paths under tests/Permission, with each it()/test() description as the method name. Upstream's permission.testing migration flag, which adds the roles team column while teams are off so cases can enable teams mid-test, is not ported; those cases enable teams before migrating through the DefineEnvironment attribute's usesTeams method. The CACHE_DRIVER cache-driver test runs map to CACHE_STORE. Upstream's single cached permission collection maps to PermissionRegistrar's catalog payload (getSerializedPermissionsForCache() stores role keys per permission; permissionCatalog() and modelClassCatalog() hydrate it) plus the per-model assignment caches (rememberModel*()), which are filled through Cache\ModelCacheCoordinator and invalidated after commit; apply upstream cache or loading changes to both. Upstream relation definitions map to the Role and Permission relation methods built through BuildsPermissionRelations, whose Partitioned* relations add partition and team constraints and loaded-relation tracking. Upstream's detach-then-attach syncs map to HasRoles::syncRoles() and HasPermissions::synchronizePermissionAssignments(), which read the current pivots and write only the differences, keeping each permission's is_denied effect. Upstream docs map to sections of src/docs/permission.md; the example app, PhpStorm, UI options, schema diagram, upgrade and project pages are not ported. Upstream's ide.json code-generation metadata for the Laravel Idea PhpStorm plugin is not ported either.
 
 aimeos/laravel-nestedset:
   branch: master

docs/upstream-sync/sync.yaml

@@ -131,6 +131,7 @@ public function retrieveById(mixed $identifier): ?UserContract
 
         return $this->cacheCoordinator->fill(
             $this->cache,
+            fn (): Model => $this->createModel(),
             $this->buildCacheKey($identifier),
             $this->cacheTtl,
             fn () => $this->fetchUserByIdForCache($identifier),

src/auth/src/EloquentUserProvider.php

@@ -14,13 +14,17 @@
  * so per-request user state cannot be stored as instance properties. Each guard must
  * implement its own coroutine-safe user(), setUser(), and hasUser() using Context.
  * This trait provides only the methods that are truly universal across all guards.
+ *
+ * @template TProvider of UserProvider = UserProvider
  */
 trait GuardHelpers
 {
     /**
      * The user provider implementation.
      *
      * Nullable because some guards (e.g. RequestGuard) may not require a provider.
+     *
+     * @var null|TProvider
      */
     protected ?UserProvider $provider = null;
 
@@ -60,6 +64,8 @@ public function id(): int|string|null
 
     /**
      * Get the user provider used by the guard.
+     *
+     * @return null|TProvider
      */
     public function getProvider(): ?UserProvider
     {
@@ -71,6 +77,8 @@ public function getProvider(): ?UserProvider
      *
      * Boot or tests only. The provider is stored on the worker-lifetime guard
      * and affects every subsequent request.
+     *
+     * @param TProvider $provider
      */
     public function setProvider(UserProvider $provider): void
     {

src/auth/src/GuardHelpers.php

@@ -5,6 +5,7 @@
 namespace Hypervel\Auth;
 
 use Hypervel\Context\CoroutineContext;
+use Hypervel\Context\RequestContext;
 use Hypervel\Contracts\Auth\Authenticatable as AuthenticatableContract;
 use Hypervel\Contracts\Auth\Guard;
 use Hypervel\Contracts\Auth\UserProvider;
@@ -50,10 +51,9 @@ public function __construct(
     /**
      * Get the currently authenticated user.
      *
-     * Uses coroutine Context to cache the resolved user per-request,
-     * since this guard is a process-global singleton. A sentinel value
-     * is used to cache "no user found" so repeated calls don't trigger
-     * redundant provider lookups.
+     * RequestContext keeps resolved users local to the coroutine and clears them
+     * when its request changes. A sentinel caches "no user found" so repeated
+     * calls don't trigger redundant provider lookups.
      */
     public function user(): ?AuthenticatableContract
     {
@@ -67,7 +67,7 @@ public function user(): ?AuthenticatableContract
         }
 
         $contextKey = $this->getResolvedUserContextKey();
-        $cached = CoroutineContext::get($contextKey);
+        $cached = RequestContext::getValue($contextKey);
 
         if ($cached === self::$nullUserSentinel) {
             return null;
@@ -82,7 +82,7 @@ public function user(): ?AuthenticatableContract
             $this->getProvider()
         );
 
-        CoroutineContext::set($contextKey, $user ?? self::$nullUserSentinel);
+        RequestContext::setValue($contextKey, $user ?? self::$nullUserSentinel);
 
         return $user;
     }
@@ -109,7 +109,7 @@ public function hasUser(): bool
             return true;
         }
 
-        $cached = CoroutineContext::get($this->getResolvedUserContextKey());
+        $cached = RequestContext::getValue($this->getResolvedUserContextKey());
 
         return $cached !== null && $cached !== self::$nullUserSentinel;
     }
@@ -130,7 +130,7 @@ public function setUser(AuthenticatableContract $user): static
     public function forgetUser(): static
     {
         CoroutineContext::forget($this->getExplicitUserContextKey());
-        CoroutineContext::forget($this->getResolvedUserContextKey());
+        RequestContext::forgetValue($this->getResolvedUserContextKey());
 
         return $this;
     }

src/auth/src/RequestGuard.php

@@ -5,6 +5,7 @@
 namespace Hypervel\Auth;
 
 use Hypervel\Context\CoroutineContext;
+use Hypervel\Context\RequestContext;
 use Hypervel\Contracts\Auth\Authenticatable as AuthenticatableContract;
 use Hypervel\Contracts\Auth\Guard;
 use Hypervel\Contracts\Auth\UserProvider;
@@ -45,10 +46,9 @@ public function __construct(
     /**
      * Get the currently authenticated user.
      *
-     * Uses coroutine Context to cache the resolved user per-request,
-     * keyed by token fingerprint so different tokens don't collide.
-     * A sentinel value caches "no user found" so repeated calls
-     * don't trigger redundant provider lookups.
+     * RequestContext keeps resolved users local to the coroutine and clears them
+     * when its request changes. Token fingerprints separate credentials, and a
+     * sentinel caches "no user found" to avoid redundant provider lookups.
      */
     public function user(): ?AuthenticatableContract
     {
@@ -63,7 +63,7 @@ public function user(): ?AuthenticatableContract
 
         $token = $this->getTokenForRequest();
         $contextKey = $this->getContextKeyForToken($token);
-        $cached = CoroutineContext::get($contextKey);
+        $cached = RequestContext::getValue($contextKey);
 
         if ($cached === self::$nullUserSentinel) {
             return null;
@@ -81,7 +81,7 @@ public function user(): ?AuthenticatableContract
             ]);
         }
 
-        CoroutineContext::set($contextKey, $user ?? self::$nullUserSentinel);
+        RequestContext::setValue($contextKey, $user ?? self::$nullUserSentinel);
 
         return $user;
     }
@@ -143,7 +143,7 @@ public function hasUser(): bool
             return true;
         }
 
-        $cached = CoroutineContext::get($this->getContextKeyForToken($this->getTokenForRequest()));
+        $cached = RequestContext::getValue($this->getContextKeyForToken($this->getTokenForRequest()));
 
         return $cached !== null && $cached !== self::$nullUserSentinel;
     }
@@ -164,7 +164,7 @@ public function setUser(AuthenticatableContract $user): static
     public function forgetUser(): static
     {
         CoroutineContext::forget($this->getExplicitUserContextKey());
-        CoroutineContext::forget($this->getContextKeyForToken($this->getTokenForRequest()));
+        RequestContext::forgetValue($this->getContextKeyForToken($this->getTokenForRequest()));
 
         return $this;
     }

src/auth/src/TokenGuard.php

@@ -11,6 +11,11 @@
 use Hypervel\Contracts\Cache\RefreshableLock;
 use Hypervel\Contracts\Cache\Repository as CacheRepository;
 use Hypervel\Contracts\Cache\Store;
+use Hypervel\Contracts\Container\Container;
+use Hypervel\Database\DatabaseTransactionsManager;
+use Hypervel\Database\Eloquent\Builder;
+use Hypervel\Database\Eloquent\Model;
+use Hypervel\Support\Collection;
 
 /**
  * Coordinate shared model cache fills and exact invalidations.
@@ -32,6 +37,11 @@ class ModelCacheCoordinator
      */
     private const int INVALIDATION_RETRY_MILLISECONDS = 25;
 
+    /**
+     * The maximum number of models written and invalidated per batch.
+     */
+    private const int MUTATION_BATCH_SIZE = 1000;
+
     /**
      * The envelope marker key.
      */
@@ -47,20 +57,47 @@ class ModelCacheCoordinator
      */
     private const string ENVELOPE_VALUE_KEY = 'value';
 
+    /**
+     * Create a model cache coordinator.
+     */
+    public function __construct(protected Container $container)
+    {
+    }
+
+    /**
+     * Determine whether the source has a transaction that prevents shared caching.
+     *
+     * @param Closure(): Model $source
+     */
+    public function hasApplicableTransaction(Closure $source): bool
+    {
+        /** @var DatabaseTransactionsManager $transactions */
+        $transactions = $this->container->make('db.transactions');
+
+        // Check the manager first so ordinary cache hits do not construct a source model.
+        return $transactions->hasApplicableTransaction() && $source()->hasApplicableTransaction();
+    }
+
     /**
      * Retrieve or fill a shared model cache entry.
      *
+     * @param Closure(): Model $source
      * @param Closure(): mixed $read
      * @param null|(Closure(): CacheRepository) $writeCache
      */
     public function fill(
         CacheRepository $cache,
+        Closure $source,
         string $key,
         int $ttl,
         Closure $read,
         bool $cacheNull = true,
         ?Closure $writeCache = null,
     ): mixed {
+        if ($this->hasApplicableTransaction($source)) {
+            return $read();
+        }
+
         $cached = $cache->get($key);
 
         if ($this->isEnvelope($cached)) {
@@ -112,6 +149,57 @@ public function fill(
         return $acquired ? $result : $read();
     }
 
+    /**
+     * Mutate selected models atomically and invalidate each written batch.
+     *
+     * @template TModel of Model
+     * @param Builder<TModel> $query
+     * @param Closure(Builder<TModel>): int $write
+     * @param Closure(array<int, int|string>): void $invalidate
+     */
+    public function mutate(Builder $query, Closure $write, Closure $invalidate): int
+    {
+        $query = clone $query;
+        $base = $query->getQuery();
+
+        // Original OR predicates must not escape the batch's key or pagination constraints.
+        $query->setQuery($base->cloneWithout(['wheres'])->cloneWithoutBindings(['where'])->addNestedWhereQuery($base));
+
+        $model = $query->getModel();
+        $key = $model->getKeyName();
+        $qualifiedKey = $model->getQualifiedKeyName();
+
+        // Batching must preserve the atomicity of the uncached, single-statement write.
+        return $model->getConnection()->transaction(function () use ($query, $write, $invalidate, $key, $qualifiedKey): int {
+            $affected = 0;
+
+            $selection = (clone $query)->select($qualifiedKey)->useWritePdo()->toBase();
+            $writeBatch = function (array $ids) use ($query, $write, $invalidate, &$affected): void {
+                $affected += $write((clone $query)->whereKey($ids)->reorder()->limit(null)->offset(null));
+                $invalidate($ids);
+            };
+
+            if ($selection->getLimit() !== null || $selection->getOffset() > 0) {
+                // Writes may change the filter or sort columns, so preserve the selected set first.
+                $ids = array_unique($selection->pluck($qualifiedKey)->all());
+
+                foreach (array_chunk($ids, self::MUTATION_BATCH_SIZE) as $batch) {
+                    $writeBatch($batch);
+                }
+            } else {
+                // Other sort columns would make chunkById skip records between batches.
+                $selection->reorder()->chunkById(
+                    self::MUTATION_BATCH_SIZE,
+                    static fn (Collection $rows) => $writeBatch($rows->pluck($key)->all()),
+                    $qualifiedKey,
+                    $key,
+                );
+            }
+
+            return $affected;
+        });
+    }
+
     /**
      * Invalidate an exact shared model cache entry.
      */