From 652486b7411527cb254a578aaee46cfca1c9890f Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 11:39:33 +0200
Subject: [PATCH 1/9] Add opt-in personal access token authentication

Opt-in "personal_access_token" config section (disabled by default): sha256
hashed bearer tokens bound to a user with expiration, revocation, versioned
auth cache, throttled last-used tracking, ownership voter, management
controller and console commands for creation and expiry notifications
(pluggable notifier interface with a no-op default). The entity ships as a
mapped superclass targeting the contracts AnzuUser via resolve_target_entities;
the host subclasses it and owns the table, indexes and migration.
---
 README.md                                     |  66 ++++++++
 composer.json                                 |  12 +-
 .../CreatePersonalAccessTokenCommand.php      | 129 +++++++++++++++
 ...ifyExpiringPersonalAccessTokensCommand.php |  70 ++++++++
 .../Api/PersonalAccessTokenController.php     |  95 +++++++++++
 .../AnzuSystemsAuthExtension.php              |  88 ++++++++++
 src/DependencyInjection/Configuration.php     |  28 ++++
 .../Cache/PersonalAccessTokenAuthCache.php    |  88 ++++++++++
 .../Facade/PersonalAccessTokenFacade.php      |  68 ++++++++
 .../Manager/PersonalAccessTokenManager.php    |  38 +++++
 .../Model/PersonalAccessTokenCreateDto.php    |  41 +++++
 .../Model/PersonalAccessTokenCreateResult.php |  19 +++
 .../NoopPersonalAccessTokenExpiryNotifier.php |  15 ++
 ...onalAccessTokenExpiryNotifierInterface.php |  16 ++
 .../PersonalAccessTokenRepository.php         |  84 ++++++++++
 src/Entity/AbstractPersonalAccessToken.php    | 150 +++++++++++++++++
 .../PersonalAccessTokenAuthenticator.php      | 154 ++++++++++++++++++
 .../PersonalAccessTokenPermission.php         |  14 ++
 .../Voter/PersonalAccessTokenVoter.php        |  54 ++++++
 tests/Data/Entity/PersonalAccessToken.php     |  11 ++
 .../AnzuSystemsAuthExtensionTest.php          |  50 ++++++
 .../PersonalAccessTokenAuthCacheTest.php      |  75 +++++++++
 .../Facade/PersonalAccessTokenFacadeTest.php  | 120 ++++++++++++++
 .../AbstractPersonalAccessTokenTest.php       |  40 +++++
 .../PersonalAccessTokenAuthenticatorTest.php  | 137 ++++++++++++++++
 .../Voter/PersonalAccessTokenVoterTest.php    | 134 +++++++++++++++
 26 files changed, 1793 insertions(+), 3 deletions(-)
 create mode 100644 src/Command/CreatePersonalAccessTokenCommand.php
 create mode 100644 src/Command/NotifyExpiringPersonalAccessTokensCommand.php
 create mode 100644 src/Controller/Api/PersonalAccessTokenController.php
 create mode 100644 src/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCache.php
 create mode 100644 src/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacade.php
 create mode 100644 src/Domain/PersonalAccessToken/Manager/PersonalAccessTokenManager.php
 create mode 100644 src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateDto.php
 create mode 100644 src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateResult.php
 create mode 100644 src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php
 create mode 100644 src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php
 create mode 100644 src/Domain/PersonalAccessToken/Repository/PersonalAccessTokenRepository.php
 create mode 100644 src/Entity/AbstractPersonalAccessToken.php
 create mode 100644 src/Security/Authentication/PersonalAccessTokenAuthenticator.php
 create mode 100644 src/Security/PersonalAccessTokenPermission.php
 create mode 100644 src/Security/Voter/PersonalAccessTokenVoter.php
 create mode 100644 tests/Data/Entity/PersonalAccessToken.php
 create mode 100644 tests/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCacheTest.php
 create mode 100644 tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php
 create mode 100644 tests/Entity/AbstractPersonalAccessTokenTest.php
 create mode 100644 tests/Security/Authentication/PersonalAccessTokenAuthenticatorTest.php
 create mode 100644 tests/Security/Voter/PersonalAccessTokenVoterTest.php

diff --git a/README.md b/README.md
index 8962115..c82423a 100644
--- a/README.md
+++ b/README.md
@@ -68,3 +68,69 @@ $routes
     ->import('@AnzuSystemsAuthBundle/Controller/Api/JsonCredentialsAuthController.php', type: 'attribute')
     ->prefix('/api/auth/');
 ```
+
+## Personal access tokens
+
+Opt-in personal access token (PAT) authentication: an sha256-hashed bearer token bound to a user, with expiration,
+revocation, cached authentication, expiry notifications and management API. Disabled by default — a project that does
+not enable it needs no schema or configuration changes after a bundle upgrade.
+
+Enable it by subclassing the mapped superclass and pointing the config to it:
+
+```php
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity(repositoryClass: PersonalAccessTokenRepository::class)]
+#[ORM\Table(name: 'personal_access_token')]
+#[ORM\Index(name: 'IDX_revokedAt_expiresAt', fields: ['revokedAt', 'expiresAt'])]
+#[ORM\UniqueConstraint(name: 'UNIQ_tokenHash', fields: ['tokenHash'])]
+class PersonalAccessToken extends AbstractPersonalAccessToken
+{
+}
+```
+
+```yaml
+anzu_systems_auth:
+  personal_access_token:
+    enabled: true
+    entity_class: App\Domain\PersonalAccessToken\Entity\PersonalAccessToken
+    user_entity_class: App\Domain\User\Entity\User
+    auth_cache_pool: 'some_redis.cache'
+```
+
+The `user` relation targets `AnzuSystems\Contracts\Entity\AnzuUser` — make sure doctrine
+`resolve_target_entities` maps it to the project user class. Add the doctrine mapping for the bundle's `Entity`
+namespace and generate the migration with `doctrine:migrations:diff`.
+
+Wire the authenticator into a firewall protecting the API that accepts the tokens:
+
+```yaml
+security:
+  firewalls:
+    mcp:
+      pattern: ^/api/mcp
+      stateless: true
+      provider: app_user_provider_id
+      entry_point: AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator
+      custom_authenticators:
+        - AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator
+```
+
+Management API routes (list/create/revoke) are provided by
+`AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController` — add routes pointing at its
+`getList`/`create`/`revoke` methods. Authorization uses the `auth_personalAccessToken_(create|read|revoke)`
+permissions (see `AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission`); creation additionally requires
+the `ROLE_MCP` role.
+
+Console commands:
+
+* `anzu:personal-access-token:create <userId> --name=<label> [--expires-at=...]` — prints the plaintext token once.
+* `anzu:personal-access-token:notify-expiring` — daily cron; notifies owners of tokens expiring in 7 days or 1 day
+  through `PersonalAccessTokenExpiryNotifierInterface` (no-op by default — alias your own implementation). The
+  final-notice windows of consecutive runs overlap, so the implementation must be idempotent per
+  (token, daysRemaining) pair — e.g. dispatch under an event name containing both.
+
+When migrating from an app-level PAT implementation, rename existing permission grants to the
+`auth_personalAccessToken_*` keys — grants stored under the old keys stop matching silently.
diff --git a/composer.json b/composer.json
index 589d17c..3a6ff0c 100644
--- a/composer.json
+++ b/composer.json
@@ -2,7 +2,11 @@
     "name": "anzusystems/auth-bundle",
     "description": "Anzu authorization services",
     "type": "symfony-bundle",
-    "keywords": ["symfony", "anzusystems", "authorization"],
+    "keywords": [
+        "symfony",
+        "anzusystems",
+        "authorization"
+    ],
     "license": "Apache-2.0",
     "authors": [
         {
@@ -14,12 +18,14 @@
         "php": ">=8.4",
         "ext-json": "*",
         "ext-redis": "*",
-        "anzusystems/common-bundle": "^9.0|^10.0|^11.0",
+        "anzusystems/common-bundle": "^9.4|^10.0|^11.0|^12.0",
         "doctrine/common": "^3.3",
         "lcobucci/clock": "^3.0",
-        "lcobucci/jwt": "^5.5"
+        "lcobucci/jwt": "^5.5",
+        "symfony/console": "^7.3|^8.0"
     },
     "require-dev": {
+        "doctrine/doctrine-bundle": "^2.11|^3.0",
         "doctrine/orm": "^2.13|^3.0",
         "nelmio/api-doc-bundle": "^5.9",
         "slevomat/coding-standard": "8.20.0",
diff --git a/src/Command/CreatePersonalAccessTokenCommand.php b/src/Command/CreatePersonalAccessTokenCommand.php
new file mode 100644
index 0000000..61c338e
--- /dev/null
+++ b/src/Command/CreatePersonalAccessTokenCommand.php
@@ -0,0 +1,129 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Command;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\CommonBundle\Exception\ValidationException;
+use AnzuSystems\CommonBundle\Helper\StringHelper;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use AnzuSystems\Contracts\Exception\AppReadOnlyModeException;
+use DateTimeImmutable;
+use Doctrine\ORM\EntityManagerInterface;
+use Exception;
+use Random\RandomException;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand(
+    name: 'anzu:personal-access-token:create',
+    description: 'Create a personal access token for a user and print the plaintext token (shown only once)'
+)]
+final class CreatePersonalAccessTokenCommand extends Command
+{
+    private const string ARG_USER_ID = 'userId';
+    private const string OPTION_NAME = 'name';
+    private const string OPTION_EXPIRES_AT = 'expires-at';
+    private const string DATETIME_FORMAT = 'Y-m-d H:i:s';
+
+    /**
+     * @param class-string<AnzuUser> $userEntityClass
+     */
+    public function __construct(
+        private readonly EntityManagerInterface $entityManager,
+        private readonly PersonalAccessTokenFacade $personalAccessTokenFacade,
+        private readonly string $userEntityClass,
+    ) {
+        parent::__construct();
+    }
+
+    protected function configure(): void
+    {
+        $this
+            ->addArgument(self::ARG_USER_ID, InputArgument::REQUIRED, 'Id of the user owning the token.')
+            ->addOption(self::OPTION_NAME, null, InputOption::VALUE_REQUIRED, 'Token label, e.g. "mcp-agent".')
+            ->addOption(self::OPTION_EXPIRES_AT, null, InputOption::VALUE_REQUIRED, sprintf(
+                'Expiration date time, e.g. "2026-09-21 12:00:00". Defaults to %s, at most %s.',
+                AbstractPersonalAccessToken::DEFAULT_EXPIRES_AT_DATE,
+                AbstractPersonalAccessToken::MAX_EXPIRES_AT_DATE,
+            ))
+        ;
+    }
+
+    /**
+     * @throws AppReadOnlyModeException
+     * @throws RandomException
+     */
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        AnzuApp::throwOnReadOnlyMode();
+
+        $userId = (int) $input->getArgument(self::ARG_USER_ID);
+        $user = $this->entityManager->find($this->userEntityClass, $userId);
+        if (false === ($user instanceof AnzuUser)) {
+            $output->writeln(sprintf('<error>User (%d) not found.</error>', $userId));
+
+            return self::FAILURE;
+        }
+
+        $name = (string) $input->getOption(self::OPTION_NAME);
+        if (StringHelper::isEmpty($name)) {
+            $output->writeln(sprintf('<error>Option --%s is required.</error>', self::OPTION_NAME));
+
+            return self::FAILURE;
+        }
+
+        try {
+            $expiresAt = $this->resolveExpiresAtOption($input);
+        } catch (Exception) {
+            $output->writeln(sprintf(
+                '<error>Invalid --%s value "%s", provide a date time, e.g. "2027-07-09 12:00:00".</error>',
+                self::OPTION_EXPIRES_AT,
+                (string) $input->getOption(self::OPTION_EXPIRES_AT),
+            ));
+
+            return self::FAILURE;
+        }
+
+        try {
+            $result = $this->personalAccessTokenFacade->create(
+                user: $user,
+                name: $name,
+                expiresAt: $expiresAt,
+            );
+        } catch (ValidationException $exception) {
+            $output->writeln(sprintf(
+                '<error>Validation failed: %s</error>',
+                (string) json_encode($exception->getFormattedErrors()),
+            ));
+
+            return self::FAILURE;
+        }
+
+        $output->writeln(sprintf('Token (shown only once): <info>%s</info>', $result->token));
+        $output->writeln(sprintf(
+            'Expires at: %s',
+            $result->personalAccessToken->getExpiresAt()
+                ->format(self::DATETIME_FORMAT)
+        ));
+
+        return self::SUCCESS;
+    }
+
+    private function resolveExpiresAtOption(InputInterface $input): ?DateTimeImmutable
+    {
+        $expiresAtOption = $input->getOption(self::OPTION_EXPIRES_AT);
+        if (null === $expiresAtOption) {
+            return null;
+        }
+
+        return new DateTimeImmutable((string) $expiresAtOption);
+    }
+}
diff --git a/src/Command/NotifyExpiringPersonalAccessTokensCommand.php b/src/Command/NotifyExpiringPersonalAccessTokensCommand.php
new file mode 100644
index 0000000..cdfdc2d
--- /dev/null
+++ b/src/Command/NotifyExpiringPersonalAccessTokensCommand.php
@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Command;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\PersonalAccessTokenExpiryNotifierInterface;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Exception\AppReadOnlyModeException;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+#[AsCommand(
+    'anzu:personal-access-token:notify-expiring',
+    'Notify owners of personal access tokens expiring in 7 days or in 1 day.'
+)]
+final class NotifyExpiringPersonalAccessTokensCommand extends Command
+{
+    private const int EARLY_NOTICE_DAYS = 7;
+    private const int FINAL_NOTICE_DAYS = 1;
+    private const array NOTIFY_DAYS_REMAINING = [self::EARLY_NOTICE_DAYS, self::FINAL_NOTICE_DAYS];
+    private const string WINDOW_LENGTH = '+1 day';
+
+    public function __construct(
+        private readonly PersonalAccessTokenRepository $personalAccessTokenRepo,
+        private readonly PersonalAccessTokenExpiryNotifierInterface $expiryNotifier,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * @throws AppReadOnlyModeException
+     */
+    public function __invoke(SymfonyStyle $io): int
+    {
+        AnzuApp::throwOnReadOnlyMode();
+
+        $notifiedCount = 0;
+        foreach (self::NOTIFY_DAYS_REMAINING as $daysRemaining) {
+            $notifiedCount += $this->notifyWindow($daysRemaining);
+        }
+
+        $io->writeln(sprintf('Dispatched %d expiry notification(s).', $notifiedCount));
+
+        return Command::SUCCESS;
+    }
+
+    private function notifyWindow(int $daysRemaining): int
+    {
+        $dayStart = AnzuApp::date(sprintf('+%d days', $daysRemaining))->setTime(0, 0);
+        $from = $dayStart;
+        if (self::FINAL_NOTICE_DAYS === $daysRemaining) {
+            $from = AnzuApp::date();
+        }
+        $tokens = $this->personalAccessTokenRepo->findAllActiveExpiringBetween(
+            from: $from,
+            until: $dayStart->modify(self::WINDOW_LENGTH),
+        );
+        $notifiedCount = 0;
+        foreach ($tokens as $personalAccessToken) {
+            if ($this->expiryNotifier->notifyExpiring($personalAccessToken, $daysRemaining)) {
+                ++$notifiedCount;
+            }
+        }
+
+        return $notifiedCount;
+    }
+}
diff --git a/src/Controller/Api/PersonalAccessTokenController.php b/src/Controller/Api/PersonalAccessTokenController.php
new file mode 100644
index 0000000..3cbdd85
--- /dev/null
+++ b/src/Controller/Api/PersonalAccessTokenController.php
@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Controller\Api;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Model\PersonalAccessTokenCreateDto;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Model\PersonalAccessTokenCreateResult;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission;
+use AnzuSystems\CommonBundle\Controller\AbstractAnzuApiController;
+use AnzuSystems\CommonBundle\Exception\ValidationException;
+use AnzuSystems\CommonBundle\Log\Helper\AuditLogResourceHelper;
+use AnzuSystems\CommonBundle\Model\OpenApi\Parameter\OAParameterPath;
+use AnzuSystems\CommonBundle\Model\OpenApi\Request\OARequest;
+use AnzuSystems\CommonBundle\Model\OpenApi\Response\OAResponse;
+use AnzuSystems\CommonBundle\Model\OpenApi\Response\OAResponseCreated;
+use AnzuSystems\CommonBundle\Model\OpenApi\Response\OAResponseForbidden;
+use AnzuSystems\CommonBundle\Model\OpenApi\Response\OAResponseNotFound;
+use AnzuSystems\CommonBundle\Model\OpenApi\Response\OAResponseUnauthorized;
+use AnzuSystems\CommonBundle\Model\OpenApi\Response\OAResponseValidation;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Exception\AppReadOnlyModeException;
+use AnzuSystems\SerializerBundle\Attributes\SerializeParam;
+use OpenApi\Attributes as OA;
+use Psr\Log\LoggerInterface;
+use Random\RandomException;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Request;
+
+#[OA\Tag('PersonalAccessToken')]
+final class PersonalAccessTokenController extends AbstractAnzuApiController
+{
+    public function __construct(
+        private readonly PersonalAccessTokenFacade $personalAccessTokenFacade,
+        private readonly PersonalAccessTokenRepository $personalAccessTokenRepo,
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    #[OAResponse([AbstractPersonalAccessToken::class]), OAResponseUnauthorized, OAResponseForbidden]
+    public function getList(): JsonResponse
+    {
+        $this->denyAccessUnlessGranted(PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_READ);
+
+        return $this->okResponse(
+            $this->personalAccessTokenRepo->findByUser($this->getUser())
+        );
+    }
+
+    /**
+     * @throws ValidationException|AppReadOnlyModeException|RandomException
+     */
+    #[OARequest(PersonalAccessTokenCreateDto::class), OAResponseCreated(PersonalAccessTokenCreateResult::class), OAResponseValidation, OAResponseUnauthorized, OAResponseForbidden]
+    public function create(Request $request, #[SerializeParam] PersonalAccessTokenCreateDto $dto): JsonResponse
+    {
+        AnzuApp::throwOnReadOnlyMode();
+        $this->denyAccessUnlessGranted(PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE);
+        AuditLogResourceHelper::excludeFromAuditLogs($request);
+        $result = $this->personalAccessTokenFacade->create(
+            user: $this->getUser(),
+            name: $dto->getName(),
+            expiresAt: $dto->getExpiresAt(),
+        );
+        $this->logger->info('Personal access token created.', [
+            'resource' => $result->personalAccessToken::getResourceName(),
+            'personalAccessTokenId' => $result->personalAccessToken->getId(),
+            'userId' => $this->getUser()
+                ->getId(),
+        ]);
+
+        return $this->createdResponse($result);
+    }
+
+    /**
+     * @throws AppReadOnlyModeException
+     */
+    #[OAParameterPath('id'), OAResponse(AbstractPersonalAccessToken::class), OAResponseNotFound, OAResponseUnauthorized, OAResponseForbidden]
+    public function revoke(Request $request, int $id): JsonResponse
+    {
+        AnzuApp::throwOnReadOnlyMode();
+        $personalAccessToken = $this->personalAccessTokenRepo->find($id);
+        if (false === ($personalAccessToken instanceof AbstractPersonalAccessToken)) {
+            throw $this->createNotFoundException();
+        }
+        $this->denyAccessUnlessGranted(PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_REVOKE, $personalAccessToken);
+        AuditLogResourceHelper::setResourceByEntity(request: $request, entity: $personalAccessToken);
+
+        return $this->okResponse(
+            $this->personalAccessTokenFacade->revoke($personalAccessToken)
+        );
+    }
+}
diff --git a/src/DependencyInjection/AnzuSystemsAuthExtension.php b/src/DependencyInjection/AnzuSystemsAuthExtension.php
index cb3dde9..7356cce 100644
--- a/src/DependencyInjection/AnzuSystemsAuthExtension.php
+++ b/src/DependencyInjection/AnzuSystemsAuthExtension.php
@@ -5,16 +5,27 @@
 namespace AnzuSystems\AuthBundle\DependencyInjection;
 
 use AnzuSystems\AuthBundle\Command\ChangeApiTokenCommand;
+use AnzuSystems\AuthBundle\Command\CreatePersonalAccessTokenCommand;
+use AnzuSystems\AuthBundle\Command\NotifyExpiringPersonalAccessTokensCommand;
 use AnzuSystems\AuthBundle\Configuration\OAuth2Configuration;
 use AnzuSystems\AuthBundle\Contracts\OAuth2AuthUserRepositoryInterface;
 use AnzuSystems\AuthBundle\Contracts\RefreshTokenStorageInterface;
 use AnzuSystems\AuthBundle\Controller\Api\JsonCredentialsAuthController;
 use AnzuSystems\AuthBundle\Controller\Api\OAuth2AuthController;
+use AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\NoopPersonalAccessTokenExpiryNotifier;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\PersonalAccessTokenExpiryNotifierInterface;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\GrantAccessByOAuth2TokenProcess;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\ValidateOAuth2AccessTokenProcess;
 use AnzuSystems\AuthBundle\HttpClient\OAuth2HttpClient;
 use AnzuSystems\AuthBundle\Model\Enum\AuthType;
 use AnzuSystems\AuthBundle\RefreshTokenStorage\RedisRefreshTokenStorage;
+use AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator;
+use AnzuSystems\AuthBundle\Security\Voter\PersonalAccessTokenVoter;
 use AnzuSystems\AuthBundle\Serializer\Handler\Handlers\JwtHandler;
 use AnzuSystems\AuthBundle\Util\HttpUtil;
 use AnzuSystems\AuthBundle\Util\StatelessTokenUtil;
@@ -162,5 +173,82 @@ public function load(array $configs, ContainerBuilder $container): void
                 ->setAutoconfigured(true)
             ;
         }
+
+        $this->loadPersonalAccessToken($container, $processedConfig['personal_access_token']);
+    }
+
+    private function loadPersonalAccessToken(ContainerBuilder $container, array $config): void
+    {
+        if (false === $config['enabled']) {
+            return;
+        }
+        if (false === class_exists(EntityManagerInterface::class)) {
+            throw new InvalidArgumentException('The "personal_access_token" config section requires the "doctrine/orm" package.');
+        }
+        $entityClass = $config['entity_class'];
+        if (false === is_string($entityClass)) {
+            throw new InvalidArgumentException('Required entity_class at path "anzu_systems_auth.personal_access_token.entity_class".');
+        }
+
+        $container
+            ->register(PersonalAccessTokenRepository::class)
+            ->setAutowired(true)
+            ->setAutoconfigured(true)
+            ->setArgument('$entityClass', $entityClass)
+        ;
+
+        $container
+            ->register(PersonalAccessTokenManager::class)
+            ->setAutowired(true)
+            ->setAutoconfigured(true)
+        ;
+
+        $container
+            ->register(PersonalAccessTokenAuthCache::class)
+            ->setAutowired(true)
+            ->setArgument('$patAuthCache', new Reference($config['auth_cache_pool']))
+        ;
+
+        $container
+            ->register(PersonalAccessTokenFacade::class)
+            ->setAutowired(true)
+            ->setArgument('$entityClass', $entityClass)
+        ;
+
+        $container
+            ->register(NoopPersonalAccessTokenExpiryNotifier::class)
+        ;
+        $container->setAlias(PersonalAccessTokenExpiryNotifierInterface::class, NoopPersonalAccessTokenExpiryNotifier::class);
+
+        $container
+            ->register(PersonalAccessTokenAuthenticator::class)
+            ->setAutowired(true)
+            ->setArgument('$userEntityClass', $config['user_entity_class'])
+        ;
+
+        $container
+            ->register(PersonalAccessTokenVoter::class)
+            ->setAutowired(true)
+            ->setAutoconfigured(true)
+        ;
+
+        $container
+            ->register(CreatePersonalAccessTokenCommand::class)
+            ->setAutowired(true)
+            ->setAutoconfigured(true)
+            ->setArgument('$userEntityClass', $config['user_entity_class'])
+        ;
+
+        $container
+            ->register(NotifyExpiringPersonalAccessTokensCommand::class)
+            ->setAutowired(true)
+            ->setAutoconfigured(true)
+        ;
+
+        $container
+            ->register(PersonalAccessTokenController::class)
+            ->setAutowired(true)
+            ->setAutoconfigured(true)
+        ;
     }
 }
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index 643cf5a..6272018 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -6,7 +6,9 @@
 
 use AnzuSystems\AuthBundle\Configuration\OAuth2Configuration;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\GrantAccessByOAuth2TokenProcess;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
 use AnzuSystems\AuthBundle\Model\Enum\AuthType;
+use AnzuSystems\Contracts\Entity\AnzuUser;
 use AnzuSystems\AuthBundle\Model\Enum\JwtAlgorithm;
 use AnzuSystems\AuthBundle\Model\SsoUserDto;
 use Exception;
@@ -29,12 +31,38 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->append($this->addCookieSection())
                 ->append($this->addJwtSection())
                 ->append($this->addAuthorizationSection())
+                ->append($this->addPersonalAccessTokenSection())
             ->end()
         ;
 
         return $treeBuilder;
     }
 
+    private function addPersonalAccessTokenSection(): NodeDefinition
+    {
+        return (new TreeBuilder('personal_access_token'))->getRootNode()
+            ->addDefaultsIfNotSet()
+            ->canBeEnabled()
+            ->children()
+                ->scalarNode('entity_class')
+                    ->defaultNull()
+                    ->validate()
+                        ->ifTrue(static fn (?string $entityClass): bool => is_string($entityClass) && false === is_a($entityClass, AbstractPersonalAccessToken::class, true))
+                        ->thenInvalid('Invalid personal_access_token entity_class "%s".')
+                    ->end()
+                ->end()
+                ->scalarNode('user_entity_class')
+                    ->defaultValue('App\\Entity\\User')
+                    ->validate()
+                        ->ifTrue(static fn (string $userEntityClass): bool => false === is_a($userEntityClass, AnzuUser::class, true))
+                        ->thenInvalid('Invalid personal_access_token user_entity_class "%s".')
+                    ->end()
+                ->end()
+                ->scalarNode('auth_cache_pool')->defaultValue('cache.app')->end()
+            ->end()
+        ;
+    }
+
     private function addCookieSection(): NodeDefinition
     {
         return (new TreeBuilder('cookie'))->getRootNode()
diff --git a/src/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCache.php b/src/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCache.php
new file mode 100644
index 0000000..d1eb7e3
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCache.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache;
+
+use AnzuSystems\Contracts\AnzuApp;
+use DateTimeImmutable;
+use Psr\Cache\CacheItemInterface;
+use Psr\Cache\CacheItemPoolInterface;
+
+final readonly class PersonalAccessTokenAuthCache
+{
+    public const int USER_ID_EXPIRE_TIME = 300;
+
+    private const string CACHE_KEY_PREFIX = 'pat_auth_user_id';
+    private const string VERSION_KEY_PREFIX = 'pat_auth_version';
+    private const int VERSION_INITIAL = 1;
+    private const int VERSION_INCREMENT = 1;
+    private const int VERSION_EXPIRE_TIME = 2 * self::USER_ID_EXPIRE_TIME;
+
+    public function __construct(
+        private CacheItemPoolInterface $patAuthCache,
+    ) {
+    }
+
+    public function getInvalidationVersion(string $tokenHash): int
+    {
+        return $this->readVersion($this->patAuthCache->getItem($this->getVersionKey($tokenHash)));
+    }
+
+    public function getUserId(string $tokenHash, int $version): ?int
+    {
+        $cacheItem = $this->patAuthCache->getItem($this->getCacheKey($tokenHash, $version));
+        if (false === $cacheItem->isHit()) {
+            return null;
+        }
+        $userId = $cacheItem->get();
+        if (is_int($userId)) {
+            return $userId;
+        }
+
+        return null;
+    }
+
+    public function storeUserId(string $tokenHash, int $version, int $userId, DateTimeImmutable $expiresAt): void
+    {
+        $secondsToExpiry = $expiresAt->getTimestamp() - AnzuApp::date()->getTimestamp();
+        if ($secondsToExpiry <= 0) {
+            return;
+        }
+        $cacheItem = $this->patAuthCache->getItem($this->getCacheKey($tokenHash, $version));
+        $cacheItem->set($userId);
+        $cacheItem->expiresAfter(min(self::USER_ID_EXPIRE_TIME, $secondsToExpiry));
+        $this->patAuthCache->save($cacheItem);
+    }
+
+    public function invalidate(string $tokenHash): void
+    {
+        $cacheItem = $this->patAuthCache->getItem($this->getVersionKey($tokenHash));
+        $cacheItem->set($this->readVersion($cacheItem) + self::VERSION_INCREMENT);
+        $cacheItem->expiresAfter(self::VERSION_EXPIRE_TIME);
+        $this->patAuthCache->save($cacheItem);
+    }
+
+    private function readVersion(CacheItemInterface $cacheItem): int
+    {
+        if (false === $cacheItem->isHit()) {
+            return self::VERSION_INITIAL;
+        }
+        $version = $cacheItem->get();
+        if (is_int($version)) {
+            return $version;
+        }
+
+        return self::VERSION_INITIAL;
+    }
+
+    private function getCacheKey(string $tokenHash, int $version): string
+    {
+        return sprintf('%s_%d_%s', self::CACHE_KEY_PREFIX, $version, $tokenHash);
+    }
+
+    private function getVersionKey(string $tokenHash): string
+    {
+        return self::VERSION_KEY_PREFIX . '_' . $tokenHash;
+    }
+}
diff --git a/src/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacade.php b/src/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacade.php
new file mode 100644
index 0000000..3f90e2a
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacade.php
@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Model\PersonalAccessTokenCreateResult;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\CommonBundle\Exception\ValidationException;
+use AnzuSystems\CommonBundle\Validator\Validator;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use DateTimeImmutable;
+use Random\RandomException;
+
+final readonly class PersonalAccessTokenFacade
+{
+    public const int TOKEN_BYTES_LENGTH = 32;
+
+    /**
+     * @param class-string<AbstractPersonalAccessToken> $entityClass
+     */
+    public function __construct(
+        private Validator $validator,
+        private PersonalAccessTokenManager $manager,
+        private PersonalAccessTokenAuthCache $authCache,
+        private string $entityClass,
+    ) {
+    }
+
+    /**
+     * @throws ValidationException
+     * @throws RandomException
+     */
+    public function create(
+        AnzuUser $user,
+        string $name,
+        ?DateTimeImmutable $expiresAt = null,
+    ): PersonalAccessTokenCreateResult {
+        $plainToken = AbstractPersonalAccessToken::TOKEN_PREFIX . bin2hex(random_bytes(self::TOKEN_BYTES_LENGTH));
+        $personalAccessToken = new $this->entityClass();
+        $personalAccessToken
+            ->setUser($user)
+            ->setName($name)
+            ->setTokenHash(AbstractPersonalAccessToken::hashToken($plainToken))
+        ;
+        if ($expiresAt instanceof DateTimeImmutable) {
+            $personalAccessToken->setExpiresAt($expiresAt);
+        }
+        $this->validator->validate($personalAccessToken);
+        $this->manager->create($personalAccessToken);
+
+        return new PersonalAccessTokenCreateResult($plainToken, $personalAccessToken);
+    }
+
+    public function revoke(AbstractPersonalAccessToken $personalAccessToken): AbstractPersonalAccessToken
+    {
+        if ($personalAccessToken->isRevoked()) {
+            return $personalAccessToken;
+        }
+
+        $revoked = $this->manager->revoke($personalAccessToken);
+        $this->authCache->invalidate($revoked->getTokenHash());
+
+        return $revoked;
+    }
+}
diff --git a/src/Domain/PersonalAccessToken/Manager/PersonalAccessTokenManager.php b/src/Domain/PersonalAccessToken/Manager/PersonalAccessTokenManager.php
new file mode 100644
index 0000000..32719c5
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Manager/PersonalAccessTokenManager.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\CommonBundle\Domain\AbstractManager;
+use AnzuSystems\Contracts\AnzuApp;
+
+final class PersonalAccessTokenManager extends AbstractManager
+{
+    public function create(AbstractPersonalAccessToken $personalAccessToken, bool $flush = true): AbstractPersonalAccessToken
+    {
+        $this->trackCreation($personalAccessToken);
+        $this->entityManager->persist($personalAccessToken);
+        $this->flush($flush);
+
+        return $personalAccessToken;
+    }
+
+    public function revoke(AbstractPersonalAccessToken $personalAccessToken, bool $flush = true): AbstractPersonalAccessToken
+    {
+        $this->trackModification($personalAccessToken);
+        $personalAccessToken->setRevokedAt(AnzuApp::date());
+        $this->flush($flush);
+
+        return $personalAccessToken;
+    }
+
+    public function updateLastUsedAt(AbstractPersonalAccessToken $personalAccessToken, bool $flush = true): AbstractPersonalAccessToken
+    {
+        $personalAccessToken->setLastUsedAt(AnzuApp::date());
+        $this->flush($flush);
+
+        return $personalAccessToken;
+    }
+}
diff --git a/src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateDto.php b/src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateDto.php
new file mode 100644
index 0000000..eff2beb
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateDto.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Model;
+
+use AnzuSystems\SerializerBundle\Attributes\Serialize;
+use DateTimeImmutable;
+
+final class PersonalAccessTokenCreateDto
+{
+    #[Serialize]
+    private string $name = '';
+
+    #[Serialize]
+    private ?DateTimeImmutable $expiresAt = null;
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function setName(string $name): self
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    public function getExpiresAt(): ?DateTimeImmutable
+    {
+        return $this->expiresAt;
+    }
+
+    public function setExpiresAt(?DateTimeImmutable $expiresAt): self
+    {
+        $this->expiresAt = $expiresAt;
+
+        return $this;
+    }
+}
diff --git a/src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateResult.php b/src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateResult.php
new file mode 100644
index 0000000..db1d8b0
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Model/PersonalAccessTokenCreateResult.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Model;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\SerializerBundle\Attributes\Serialize;
+
+final readonly class PersonalAccessTokenCreateResult
+{
+    public function __construct(
+        #[Serialize]
+        public string $token,
+        #[Serialize]
+        public AbstractPersonalAccessToken $personalAccessToken,
+    ) {
+    }
+}
diff --git a/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php b/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php
new file mode 100644
index 0000000..d16654e
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+
+final readonly class NoopPersonalAccessTokenExpiryNotifier implements PersonalAccessTokenExpiryNotifierInterface
+{
+    public function notifyExpiring(AbstractPersonalAccessToken $personalAccessToken, int $daysRemaining): bool
+    {
+        return false;
+    }
+}
diff --git a/src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php b/src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php
new file mode 100644
index 0000000..72086f8
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+
+interface PersonalAccessTokenExpiryNotifierInterface
+{
+    /**
+     * Notification windows of consecutive daily runs may overlap, the implementation
+     * must be idempotent per ($personalAccessToken, $daysRemaining) pair.
+     */
+    public function notifyExpiring(AbstractPersonalAccessToken $personalAccessToken, int $daysRemaining): bool;
+}
diff --git a/src/Domain/PersonalAccessToken/Repository/PersonalAccessTokenRepository.php b/src/Domain/PersonalAccessToken/Repository/PersonalAccessTokenRepository.php
new file mode 100644
index 0000000..6998353
--- /dev/null
+++ b/src/Domain/PersonalAccessToken/Repository/PersonalAccessTokenRepository.php
@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\CommonBundle\Repository\AbstractAnzuRepository;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use DateTimeImmutable;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\Common\Collections\Order;
+use Doctrine\ORM\NonUniqueResultException;
+use Doctrine\Persistence\ManagerRegistry;
+
+/**
+ * @extends AbstractAnzuRepository<AbstractPersonalAccessToken>
+ */
+final class PersonalAccessTokenRepository extends AbstractAnzuRepository
+{
+    /**
+     * @param class-string<AbstractPersonalAccessToken> $entityClass
+     */
+    public function __construct(
+        ManagerRegistry $registry,
+        private readonly string $entityClass,
+    ) {
+        parent::__construct($registry);
+    }
+
+    /**
+     * @throws NonUniqueResultException
+     */
+    public function findOneActiveByTokenHash(string $tokenHash): ?AbstractPersonalAccessToken
+    {
+        return $this->createQueryBuilder('personalAccessToken')
+            ->where('personalAccessToken.tokenHash = :tokenHash')
+            ->andWhere('personalAccessToken.revokedAt IS NULL')
+            ->andWhere('personalAccessToken.expiresAt > :now')
+            ->setParameter('tokenHash', $tokenHash)
+            ->setParameter('now', AnzuApp::date())
+            ->getQuery()
+            ->getOneOrNullResult();
+    }
+
+    /**
+     * @return Collection<int, AbstractPersonalAccessToken>
+     */
+    public function findByUser(AnzuUser $user): Collection
+    {
+        return new ArrayCollection(
+            $this->createQueryBuilder('personalAccessToken')
+                ->where('personalAccessToken.user = :user')
+                ->setParameter('user', $user)
+                ->orderBy('personalAccessToken.id', Order::Descending->value)
+                ->getQuery()
+                ->getResult()
+        );
+    }
+
+    /**
+     * @return Collection<int, AbstractPersonalAccessToken>
+     */
+    public function findAllActiveExpiringBetween(DateTimeImmutable $from, DateTimeImmutable $until): Collection
+    {
+        return new ArrayCollection(
+            $this->createQueryBuilder('personalAccessToken')
+                ->where('personalAccessToken.revokedAt IS NULL')
+                ->andWhere('personalAccessToken.expiresAt > :from')
+                ->andWhere('personalAccessToken.expiresAt <= :until')
+                ->setParameter('from', $from)
+                ->setParameter('until', $until)
+                ->getQuery()
+                ->getResult()
+        );
+    }
+
+    protected function getEntityClass(): string
+    {
+        return $this->entityClass;
+    }
+}
diff --git a/src/Entity/AbstractPersonalAccessToken.php b/src/Entity/AbstractPersonalAccessToken.php
new file mode 100644
index 0000000..8df08c3
--- /dev/null
+++ b/src/Entity/AbstractPersonalAccessToken.php
@@ -0,0 +1,150 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Entity;
+
+use AnzuSystems\CommonBundle\Exception\ValidationException;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use AnzuSystems\Contracts\Entity\Interfaces\IdentifiableInterface;
+use AnzuSystems\Contracts\Entity\Interfaces\TimeTrackingInterface;
+use AnzuSystems\Contracts\Entity\Interfaces\UserTrackingInterface;
+use AnzuSystems\Contracts\Entity\Traits\IdentityIntTrait;
+use AnzuSystems\Contracts\Entity\Traits\TimeTrackingTrait;
+use AnzuSystems\Contracts\Entity\Traits\UserTrackingTrait;
+use AnzuSystems\SerializerBundle\Attributes\Serialize;
+use AnzuSystems\SerializerBundle\Handler\Handlers\EntityIdHandler;
+use DateTimeImmutable;
+use Doctrine\DBAL\Types\Types;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+
+#[ORM\MappedSuperclass]
+abstract class AbstractPersonalAccessToken implements IdentifiableInterface, TimeTrackingInterface, UserTrackingInterface
+{
+    use IdentityIntTrait;
+    use TimeTrackingTrait;
+    use UserTrackingTrait;
+
+    public const string TOKEN_PREFIX = 'anzu_pat_';
+    public const int TOKEN_HASH_LENGTH = 64;
+    public const string DEFAULT_EXPIRES_AT_DATE = '+2 months';
+    public const string MAX_EXPIRES_AT_DATE = '+1 year';
+
+    #[ORM\ManyToOne(targetEntity: AnzuUser::class)]
+    #[ORM\JoinColumn(nullable: false)]
+    #[Serialize(handler: EntityIdHandler::class)]
+    #[Assert\NotNull(message: ValidationException::ERROR_FIELD_EMPTY)]
+    protected ?AnzuUser $user = null;
+
+    #[ORM\Column(type: Types::STRING, length: 255, options: ['default' => ''])]
+    #[Serialize]
+    #[Assert\NotBlank(message: ValidationException::ERROR_FIELD_EMPTY)]
+    #[Assert\Length(max: 255, maxMessage: ValidationException::ERROR_FIELD_LENGTH_MAX)]
+    protected string $name = '';
+
+    #[ORM\Column(type: Types::STRING, length: self::TOKEN_HASH_LENGTH)]
+    protected string $tokenHash = '';
+
+    #[ORM\Column(type: Types::DATETIME_IMMUTABLE)]
+    #[Serialize]
+    #[Assert\GreaterThan(value: 'now', message: ValidationException::ERROR_FIELD_RANGE_MIN)]
+    #[Assert\LessThanOrEqual(value: self::MAX_EXPIRES_AT_DATE, message: ValidationException::ERROR_FIELD_RANGE_MAX)]
+    protected DateTimeImmutable $expiresAt;
+
+    #[ORM\Column(type: Types::DATETIME_IMMUTABLE, nullable: true)]
+    #[Serialize]
+    protected ?DateTimeImmutable $revokedAt = null;
+
+    #[ORM\Column(type: Types::DATETIME_IMMUTABLE, nullable: true)]
+    #[Serialize]
+    protected ?DateTimeImmutable $lastUsedAt = null;
+
+    public function __construct()
+    {
+        $this->expiresAt = AnzuApp::date(self::DEFAULT_EXPIRES_AT_DATE);
+    }
+
+    public static function hashToken(string $plainToken): string
+    {
+        return hash('sha256', $plainToken);
+    }
+
+    public function isRevoked(): bool
+    {
+        return $this->revokedAt instanceof DateTimeImmutable;
+    }
+
+    public function getUser(): AnzuUser
+    {
+        return $this->user;
+    }
+
+    public function setUser(AnzuUser $user): static
+    {
+        $this->user = $user;
+
+        return $this;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function setName(string $name): static
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    public function getTokenHash(): string
+    {
+        return $this->tokenHash;
+    }
+
+    public function setTokenHash(string $tokenHash): static
+    {
+        $this->tokenHash = $tokenHash;
+
+        return $this;
+    }
+
+    public function getExpiresAt(): DateTimeImmutable
+    {
+        return $this->expiresAt;
+    }
+
+    public function setExpiresAt(DateTimeImmutable $expiresAt): static
+    {
+        $this->expiresAt = $expiresAt;
+
+        return $this;
+    }
+
+    public function getRevokedAt(): ?DateTimeImmutable
+    {
+        return $this->revokedAt;
+    }
+
+    public function setRevokedAt(?DateTimeImmutable $revokedAt): static
+    {
+        $this->revokedAt = $revokedAt;
+
+        return $this;
+    }
+
+    public function getLastUsedAt(): ?DateTimeImmutable
+    {
+        return $this->lastUsedAt;
+    }
+
+    public function setLastUsedAt(?DateTimeImmutable $lastUsedAt): static
+    {
+        $this->lastUsedAt = $lastUsedAt;
+
+        return $this;
+    }
+}
diff --git a/src/Security/Authentication/PersonalAccessTokenAuthenticator.php b/src/Security/Authentication/PersonalAccessTokenAuthenticator.php
new file mode 100644
index 0000000..414484d
--- /dev/null
+++ b/src/Security/Authentication/PersonalAccessTokenAuthenticator.php
@@ -0,0 +1,154 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Security\Authentication;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use DateTimeImmutable;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\NonUniqueResultException;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
+use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
+use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
+use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;
+
+final class PersonalAccessTokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
+{
+    private const string AUTHORIZATION_HEADER = 'Authorization';
+    private const string BEARER_PREFIX = 'Bearer ';
+    private const string WWW_AUTHENTICATE_HEADER = 'WWW-Authenticate';
+    private const string WWW_AUTHENTICATE_SCHEME = 'Bearer';
+
+    /**
+     * @param class-string<AnzuUser> $userEntityClass
+     */
+    public function __construct(
+        private readonly PersonalAccessTokenRepository $personalAccessTokenRepo,
+        private readonly PersonalAccessTokenManager $personalAccessTokenManager,
+        private readonly PersonalAccessTokenAuthCache $authCache,
+        private readonly EntityManagerInterface $entityManager,
+        private readonly string $userEntityClass,
+    ) {
+    }
+
+    public function supports(Request $request): bool
+    {
+        $header = (string) $request->headers->get(self::AUTHORIZATION_HEADER);
+        if (false === $this->hasBearerScheme($header)) {
+            return false;
+        }
+
+        return str_starts_with($this->extractPlainToken($header), AbstractPersonalAccessToken::TOKEN_PREFIX);
+    }
+
+    public function authenticate(Request $request): Passport
+    {
+        $plainToken = $this->extractPlainToken(
+            (string) $request->headers->get(self::AUTHORIZATION_HEADER)
+        );
+        $tokenHash = AbstractPersonalAccessToken::hashToken($plainToken);
+        $cacheVersion = $this->authCache->getInvalidationVersion($tokenHash);
+        $user = $this->findCachedUser($tokenHash, $cacheVersion) ?? $this->authenticateAgainstDatabase($tokenHash, $cacheVersion);
+        if (false === $user->isEnabled()) {
+            throw new AuthenticationException(sprintf('User (%d) is not active or is disabled!', (int) $user->getId()));
+        }
+
+        return new SelfValidatingPassport(
+            new UserBadge((string) $user->getId(), static fn (): AnzuUser => $user)
+        );
+    }
+
+    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
+    {
+        return null;
+    }
+
+    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): Response
+    {
+        return $this->createUnauthorizedResponse();
+    }
+
+    public function start(Request $request, ?AuthenticationException $authException = null): Response
+    {
+        return $this->createUnauthorizedResponse();
+    }
+
+    private function findCachedUser(string $tokenHash, int $cacheVersion): ?AnzuUser
+    {
+        $userId = $this->authCache->getUserId($tokenHash, $cacheVersion);
+        if (null === $userId) {
+            return null;
+        }
+        $user = $this->entityManager->find($this->userEntityClass, $userId);
+        if ($user instanceof AnzuUser) {
+            return $user;
+        }
+
+        return null;
+    }
+
+    private function authenticateAgainstDatabase(string $tokenHash, int $cacheVersion): AnzuUser
+    {
+        try {
+            $personalAccessToken = $this->personalAccessTokenRepo->findOneActiveByTokenHash($tokenHash);
+        } catch (NonUniqueResultException $exception) {
+            throw new AuthenticationException('Ambiguous personal access token!', 0, $exception);
+        }
+        if (null === $personalAccessToken) {
+            throw new AuthenticationException('Invalid personal access token!');
+        }
+        $user = $personalAccessToken->getUser();
+        $this->updateLastUsedAtThrottled($personalAccessToken);
+        $this->authCache->storeUserId($tokenHash, $cacheVersion, (int) $user->getId(), $personalAccessToken->getExpiresAt());
+
+        return $user;
+    }
+
+    private function createUnauthorizedResponse(): JsonResponse
+    {
+        return new JsonResponse(
+            [
+                'message' => 'The resource owner or authorization server denied the request.',
+            ],
+            Response::HTTP_UNAUTHORIZED,
+            [
+                self::WWW_AUTHENTICATE_HEADER => self::WWW_AUTHENTICATE_SCHEME,
+            ]
+        );
+    }
+
+    private function hasBearerScheme(string $header): bool
+    {
+        return str_starts_with(strtolower($header), strtolower(self::BEARER_PREFIX));
+    }
+
+    private function extractPlainToken(string $header): string
+    {
+        return trim(substr($header, strlen(self::BEARER_PREFIX)));
+    }
+
+    private function updateLastUsedAtThrottled(AbstractPersonalAccessToken $personalAccessToken): void
+    {
+        if (AnzuApp::isReadOnlyMode()) {
+            return;
+        }
+        $lastUsedAt = $personalAccessToken->getLastUsedAt();
+        $throttleThreshold = AnzuApp::date(sprintf('-%d seconds', PersonalAccessTokenAuthCache::USER_ID_EXPIRE_TIME));
+        if ($lastUsedAt instanceof DateTimeImmutable && $lastUsedAt > $throttleThreshold) {
+            return;
+        }
+        $this->personalAccessTokenManager->updateLastUsedAt($personalAccessToken);
+    }
+}
diff --git a/src/Security/PersonalAccessTokenPermission.php b/src/Security/PersonalAccessTokenPermission.php
new file mode 100644
index 0000000..d2b3800
--- /dev/null
+++ b/src/Security/PersonalAccessTokenPermission.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Security;
+
+final class PersonalAccessTokenPermission
+{
+    public const string ROLE_MCP = 'ROLE_MCP';
+
+    public const string PERSONAL_ACCESS_TOKEN_CREATE = 'auth_personalAccessToken_create';
+    public const string PERSONAL_ACCESS_TOKEN_READ = 'auth_personalAccessToken_read';
+    public const string PERSONAL_ACCESS_TOKEN_REVOKE = 'auth_personalAccessToken_revoke';
+}
diff --git a/src/Security/Voter/PersonalAccessTokenVoter.php b/src/Security/Voter/PersonalAccessTokenVoter.php
new file mode 100644
index 0000000..1338780
--- /dev/null
+++ b/src/Security/Voter/PersonalAccessTokenVoter.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Security\Voter;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission;
+use AnzuSystems\CommonBundle\Security\Voter\AbstractVoter;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use InvalidArgumentException;
+
+/**
+ * @template-extends AbstractVoter<string, AbstractPersonalAccessToken|null>
+ */
+final class PersonalAccessTokenVoter extends AbstractVoter
+{
+    protected function businessLogicVote(string $attribute, mixed $subject, AnzuUser $user): ?bool
+    {
+        if (PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE === $attribute
+            && false === $this->security->isGranted(PersonalAccessTokenPermission::ROLE_MCP)
+        ) {
+            return false;
+        }
+
+        if ($subject instanceof AbstractPersonalAccessToken && false === $subject->getUser()->is($user)) {
+            return false;
+        }
+
+        return null;
+    }
+
+    protected function resolveAllowOwner(mixed $subject, AnzuUser $user): bool
+    {
+        if (null === $subject) {
+            return true;
+        }
+        if ($subject instanceof AbstractPersonalAccessToken) {
+            return $subject->getUser()
+                ->is($user);
+        }
+
+        throw new InvalidArgumentException('Unsupported value for ' . self::class . '::' . __FUNCTION__);
+    }
+
+    protected function getSupportedPermissions(): array
+    {
+        return [
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE,
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_READ,
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_REVOKE,
+        ];
+    }
+}
diff --git a/tests/Data/Entity/PersonalAccessToken.php b/tests/Data/Entity/PersonalAccessToken.php
new file mode 100644
index 0000000..6ad5fd5
--- /dev/null
+++ b/tests/Data/Entity/PersonalAccessToken.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Data\Entity;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+
+final class PersonalAccessToken extends AbstractPersonalAccessToken
+{
+}
diff --git a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
index 77c74fb..d1a833e 100644
--- a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
+++ b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
@@ -4,14 +4,25 @@
 
 namespace AnzuSystems\AuthBundle\Tests\DependencyInjection;
 
+use AnzuSystems\AuthBundle\Command\CreatePersonalAccessTokenCommand;
+use AnzuSystems\AuthBundle\Command\NotifyExpiringPersonalAccessTokensCommand;
 use AnzuSystems\AuthBundle\Configuration\OAuth2Configuration;
+use AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController;
 use AnzuSystems\AuthBundle\DependencyInjection\AnzuSystemsAuthExtension;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\PersonalAccessTokenExpiryNotifierInterface;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
 use AnzuSystems\AuthBundle\Domain\Process\GrantAccessOnResponseProcess;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\GrantAccessByOAuth2TokenProcess;
 use AnzuSystems\AuthBundle\Domain\Process\RefreshTokenProcess;
 use AnzuSystems\AuthBundle\Event\Listener\LogoutListener;
+use AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator;
 use AnzuSystems\AuthBundle\Security\AuthenticationFailureHandler;
 use AnzuSystems\AuthBundle\Security\AuthenticationSuccessHandler;
+use AnzuSystems\AuthBundle\Security\Voter\PersonalAccessTokenVoter;
+use AnzuSystems\AuthBundle\Tests\Data\Entity\PersonalAccessToken;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\Yaml\Parser;
@@ -56,6 +67,45 @@ public function testEmptyConfiguration(): void
         $this->assertNotHasDefinition(LogoutListener::class);
         $this->assertNotHasDefinition(OAuth2Configuration::class);
         $this->assertNotHasDefinition(GrantAccessByOAuth2TokenProcess::class);
+        $this->assertNotHasDefinition(PersonalAccessTokenRepository::class);
+        $this->assertNotHasDefinition(PersonalAccessTokenFacade::class);
+        $this->assertNotHasDefinition(PersonalAccessTokenAuthenticator::class);
+        $this->assertNotHasDefinition(PersonalAccessTokenExpiryNotifierInterface::class);
+        $this->assertNotHasDefinition(PersonalAccessTokenController::class);
+    }
+
+    public function testPersonalAccessTokenConfiguration(): void
+    {
+        $this->configuration = new ContainerBuilder();
+        $loader = new AnzuSystemsAuthExtension();
+        $config = $this->getEmptyConfig();
+        $config['personal_access_token'] = [
+            'enabled' => true,
+            'entity_class' => PersonalAccessToken::class,
+            'user_entity_class' => 'App\Entity\User',
+            'auth_cache_pool' => 'cache.app',
+        ];
+        $loader->load([$config], $this->configuration);
+
+        $this->assertHasDefinition(PersonalAccessTokenRepository::class);
+        $this->assertHasDefinition(PersonalAccessTokenManager::class);
+        $this->assertHasDefinition(PersonalAccessTokenAuthCache::class);
+        $this->assertHasDefinition(PersonalAccessTokenFacade::class);
+        $this->assertHasDefinition(PersonalAccessTokenExpiryNotifierInterface::class);
+        $this->assertHasDefinition(PersonalAccessTokenAuthenticator::class);
+        $this->assertHasDefinition(PersonalAccessTokenVoter::class);
+        $this->assertHasDefinition(CreatePersonalAccessTokenCommand::class);
+        $this->assertHasDefinition(NotifyExpiringPersonalAccessTokensCommand::class);
+        $this->assertHasDefinition(PersonalAccessTokenController::class);
+
+        $repositoryArguments = $this->configuration->getDefinition(PersonalAccessTokenRepository::class)->getArguments();
+        self::assertSame(PersonalAccessToken::class, $repositoryArguments['$entityClass']);
+
+        $facadeArguments = $this->configuration->getDefinition(PersonalAccessTokenFacade::class)->getArguments();
+        self::assertSame(PersonalAccessToken::class, $facadeArguments['$entityClass']);
+
+        $authenticatorArguments = $this->configuration->getDefinition(PersonalAccessTokenAuthenticator::class)->getArguments();
+        self::assertSame('App\Entity\User', $authenticatorArguments['$userEntityClass']);
     }
 
     public function testFullConfiguration(): void
diff --git a/tests/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCacheTest.php b/tests/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCacheTest.php
new file mode 100644
index 0000000..1c1e55d
--- /dev/null
+++ b/tests/Domain/PersonalAccessToken/Cache/PersonalAccessTokenAuthCacheTest.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Domain\PersonalAccessToken\Cache;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\Contracts\AnzuApp;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
+
+final class PersonalAccessTokenAuthCacheTest extends TestCase
+{
+    private const string TOKEN_HASH = 'pat_auth_cache_test_token_hash';
+    private const int USER_ID = 42;
+    private const string FUTURE_EXPIRY = '+1 hour';
+
+    private PersonalAccessTokenAuthCache $cache;
+
+    public static function setUpBeforeClass(): void
+    {
+        AnzuApp::init(
+            appNamespace: 'anzusystems',
+            appSystem: 'authbundle',
+            appVersion: 'test',
+            appReadOnlyMode: false,
+            projectDir: sys_get_temp_dir(),
+            appEnv: 'test',
+        );
+    }
+
+    protected function setUp(): void
+    {
+        $this->cache = new PersonalAccessTokenAuthCache(new ArrayAdapter());
+    }
+
+    public function testGetUserIdReturnsNullOnMiss(): void
+    {
+        self::assertNull($this->cache->getUserId(self::TOKEN_HASH, $this->cache->getInvalidationVersion(self::TOKEN_HASH)));
+    }
+
+    public function testStoredUserIdWithFutureExpiryIsReturned(): void
+    {
+        $version = $this->cache->getInvalidationVersion(self::TOKEN_HASH);
+        $this->cache->storeUserId(self::TOKEN_HASH, $version, self::USER_ID, AnzuApp::date(self::FUTURE_EXPIRY));
+
+        self::assertSame(self::USER_ID, $this->cache->getUserId(self::TOKEN_HASH, $version));
+    }
+
+    public function testExpiredTokenIsNeverStored(): void
+    {
+        $version = $this->cache->getInvalidationVersion(self::TOKEN_HASH);
+        $this->cache->storeUserId(self::TOKEN_HASH, $version, self::USER_ID, AnzuApp::date('-1 second'));
+
+        self::assertNull($this->cache->getUserId(self::TOKEN_HASH, $version));
+    }
+
+    public function testInvalidateRejectsCachedUser(): void
+    {
+        $version = $this->cache->getInvalidationVersion(self::TOKEN_HASH);
+        $this->cache->storeUserId(self::TOKEN_HASH, $version, self::USER_ID, AnzuApp::date(self::FUTURE_EXPIRY));
+        $this->cache->invalidate(self::TOKEN_HASH);
+
+        self::assertNull($this->cache->getUserId(self::TOKEN_HASH, $this->cache->getInvalidationVersion(self::TOKEN_HASH)));
+    }
+
+    public function testStaleWriteWithPreInvalidationVersionIsUnreadable(): void
+    {
+        $staleVersion = $this->cache->getInvalidationVersion(self::TOKEN_HASH);
+        $this->cache->invalidate(self::TOKEN_HASH);
+        $this->cache->storeUserId(self::TOKEN_HASH, $staleVersion, self::USER_ID, AnzuApp::date(self::FUTURE_EXPIRY));
+
+        self::assertNull($this->cache->getUserId(self::TOKEN_HASH, $this->cache->getInvalidationVersion(self::TOKEN_HASH)));
+    }
+}
diff --git a/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php b/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php
new file mode 100644
index 0000000..43e6b4f
--- /dev/null
+++ b/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php
@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Domain\PersonalAccessToken\Facade;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\AuthBundle\Tests\Data\Entity\PersonalAccessToken;
+use AnzuSystems\CommonBundle\Domain\User\CurrentAnzuUserProvider;
+use AnzuSystems\CommonBundle\Validator\Validator;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use DateTimeImmutable;
+use Doctrine\ORM\EntityManagerInterface;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
+use Symfony\Component\Validator\ConstraintViolationList;
+use Symfony\Component\Validator\Validator\ValidatorInterface;
+
+final class PersonalAccessTokenFacadeTest extends TestCase
+{
+    private const int USER_ID = 42;
+
+    private PersonalAccessTokenAuthCache $authCache;
+    private PersonalAccessTokenFacade $facade;
+    private ?object $persistedEntity = null;
+
+    public static function setUpBeforeClass(): void
+    {
+        AnzuApp::init(
+            appNamespace: 'anzusystems',
+            appSystem: 'authbundle',
+            appVersion: 'test',
+            appReadOnlyMode: false,
+            projectDir: sys_get_temp_dir(),
+            appEnv: 'test',
+        );
+    }
+
+    protected function setUp(): void
+    {
+        $innerValidator = $this->createMock(ValidatorInterface::class);
+        $innerValidator->method('validate')
+            ->willReturn(new ConstraintViolationList());
+
+        $entityManager = $this->createMock(EntityManagerInterface::class);
+        $entityManager->method('persist')
+            ->willReturnCallback(function (object $entity): void {
+                $this->persistedEntity = $entity;
+            });
+
+        $currentUserProvider = $this->createMock(CurrentAnzuUserProvider::class);
+        $currentUserProvider->method('getCurrentUser')
+            ->willReturn($this->createConfiguredMock(AnzuUser::class, ['getId' => self::USER_ID]));
+
+        $manager = new PersonalAccessTokenManager();
+        $manager->setEntityManager($entityManager);
+        $manager->setCurrentAnzuUserProvider($currentUserProvider);
+
+        $this->authCache = new PersonalAccessTokenAuthCache(new ArrayAdapter());
+        $this->facade = new PersonalAccessTokenFacade(
+            new Validator($innerValidator),
+            $manager,
+            $this->authCache,
+            PersonalAccessToken::class,
+        );
+        $this->persistedEntity = null;
+    }
+
+    public function testCreateProducesPrefixedTokenMatchingStoredHash(): void
+    {
+        $user = $this->createConfiguredMock(AnzuUser::class, ['getId' => self::USER_ID]);
+
+        $result = $this->facade->create($user, 'test-token');
+
+        self::assertStringStartsWith(AbstractPersonalAccessToken::TOKEN_PREFIX, $result->token);
+        self::assertSame(
+            AbstractPersonalAccessToken::TOKEN_PREFIX . str_repeat('0', PersonalAccessTokenFacade::TOKEN_BYTES_LENGTH * 2),
+            preg_replace('~[0-9a-f]~', '0', $result->token),
+        );
+        self::assertSame(AbstractPersonalAccessToken::hashToken($result->token), $result->personalAccessToken->getTokenHash());
+        self::assertSame('test-token', $result->personalAccessToken->getName());
+        self::assertSame($user, $result->personalAccessToken->getUser());
+        self::assertSame($result->personalAccessToken, $this->persistedEntity);
+    }
+
+    public function testCreateRespectsExplicitExpiresAt(): void
+    {
+        $expiresAt = new DateTimeImmutable('+3 days');
+
+        $result = $this->facade->create($this->createConfiguredMock(AnzuUser::class, []), 'test-token', $expiresAt);
+
+        self::assertSame($expiresAt, $result->personalAccessToken->getExpiresAt());
+    }
+
+    public function testRevokeSetsRevokedAtAndInvalidatesCache(): void
+    {
+        $result = $this->facade->create($this->createConfiguredMock(AnzuUser::class, []), 'test-token');
+        $tokenHash = $result->personalAccessToken->getTokenHash();
+        $version = $this->authCache->getInvalidationVersion($tokenHash);
+        $this->authCache->storeUserId($tokenHash, $version, self::USER_ID, AnzuApp::date('+1 hour'));
+
+        $revoked = $this->facade->revoke($result->personalAccessToken);
+
+        self::assertTrue($revoked->isRevoked());
+        self::assertNull($this->authCache->getUserId($tokenHash, $this->authCache->getInvalidationVersion($tokenHash)));
+    }
+
+    public function testRevokeIsIdempotent(): void
+    {
+        $result = $this->facade->create($this->createConfiguredMock(AnzuUser::class, []), 'test-token');
+        $revoked = $this->facade->revoke($result->personalAccessToken);
+        $revokedAt = $revoked->getRevokedAt();
+
+        self::assertSame($revokedAt, $this->facade->revoke($revoked)->getRevokedAt());
+    }
+}
diff --git a/tests/Entity/AbstractPersonalAccessTokenTest.php b/tests/Entity/AbstractPersonalAccessTokenTest.php
new file mode 100644
index 0000000..2d4feb6
--- /dev/null
+++ b/tests/Entity/AbstractPersonalAccessTokenTest.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Entity;
+
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\AuthBundle\Tests\Data\Entity\PersonalAccessToken;
+use DateTimeImmutable;
+use PHPUnit\Framework\TestCase;
+
+final class AbstractPersonalAccessTokenTest extends TestCase
+{
+    public function testHashTokenProducesDeterministicSha256(): void
+    {
+        $plainToken = AbstractPersonalAccessToken::TOKEN_PREFIX . str_repeat('a', 64);
+        $hash = AbstractPersonalAccessToken::hashToken($plainToken);
+
+        self::assertSame(AbstractPersonalAccessToken::TOKEN_HASH_LENGTH, strlen($hash));
+        self::assertSame(hash('sha256', $plainToken), $hash);
+        self::assertSame($hash, AbstractPersonalAccessToken::hashToken($plainToken));
+    }
+
+    public function testNewTokenIsNotRevokedAndHasDefaultExpiry(): void
+    {
+        $personalAccessToken = new PersonalAccessToken();
+
+        self::assertFalse($personalAccessToken->isRevoked());
+        self::assertGreaterThan(new DateTimeImmutable('+1 month'), $personalAccessToken->getExpiresAt());
+        self::assertLessThanOrEqual(new DateTimeImmutable(AbstractPersonalAccessToken::MAX_EXPIRES_AT_DATE), $personalAccessToken->getExpiresAt());
+    }
+
+    public function testRevokedAtMarksTokenAsRevoked(): void
+    {
+        $personalAccessToken = new PersonalAccessToken();
+        $personalAccessToken->setRevokedAt(new DateTimeImmutable());
+
+        self::assertTrue($personalAccessToken->isRevoked());
+    }
+}
diff --git a/tests/Security/Authentication/PersonalAccessTokenAuthenticatorTest.php b/tests/Security/Authentication/PersonalAccessTokenAuthenticatorTest.php
new file mode 100644
index 0000000..bd6413c
--- /dev/null
+++ b/tests/Security/Authentication/PersonalAccessTokenAuthenticatorTest.php
@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Security\Authentication;
+
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
+use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
+use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
+use AnzuSystems\AuthBundle\Security\Authentication\PersonalAccessTokenAuthenticator;
+use AnzuSystems\AuthBundle\Tests\Data\Entity\PersonalAccessToken;
+use AnzuSystems\CommonBundle\Domain\User\CurrentAnzuUserProvider;
+use AnzuSystems\Contracts\AnzuApp;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\Persistence\ManagerRegistry;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+
+final class PersonalAccessTokenAuthenticatorTest extends TestCase
+{
+    private const int USER_ID = 42;
+    private const string USER_ENTITY_CLASS = 'App\Entity\User';
+    private const string PLAIN_TOKEN = AbstractPersonalAccessToken::TOKEN_PREFIX . 'a1b2c3d4';
+
+    private PersonalAccessTokenAuthCache $authCache;
+    private EntityManagerInterface $entityManager;
+    private PersonalAccessTokenAuthenticator $authenticator;
+
+    public static function setUpBeforeClass(): void
+    {
+        AnzuApp::init(
+            appNamespace: 'anzusystems',
+            appSystem: 'authbundle',
+            appVersion: 'test',
+            appReadOnlyMode: false,
+            projectDir: sys_get_temp_dir(),
+            appEnv: 'test',
+        );
+    }
+
+    protected function setUp(): void
+    {
+        $repositoryEntityManager = $this->createMock(EntityManagerInterface::class);
+        $repositoryEntityManager->method('getClassMetadata')
+            ->willReturn(new ClassMetadata(PersonalAccessToken::class));
+        $registry = $this->createMock(ManagerRegistry::class);
+        $registry->method('getManagerForClass')
+            ->willReturn($repositoryEntityManager);
+
+        $manager = new PersonalAccessTokenManager();
+        $manager->setEntityManager($this->createMock(EntityManagerInterface::class));
+        $manager->setCurrentAnzuUserProvider($this->createMock(CurrentAnzuUserProvider::class));
+
+        $this->authCache = new PersonalAccessTokenAuthCache(new ArrayAdapter());
+        $this->entityManager = $this->createMock(EntityManagerInterface::class);
+        $this->authenticator = new PersonalAccessTokenAuthenticator(
+            new PersonalAccessTokenRepository($registry, PersonalAccessToken::class),
+            $manager,
+            $this->authCache,
+            $this->entityManager,
+            self::USER_ENTITY_CLASS,
+        );
+    }
+
+    public function testSupportsOnlyBearerTokensWithPatPrefix(): void
+    {
+        self::assertFalse($this->authenticator->supports(Request::create('/api/mcp')));
+        self::assertFalse($this->authenticator->supports($this->createRequest('Basic dXNlcjpwYXNz')));
+        self::assertFalse($this->authenticator->supports($this->createRequest('Bearer some-jwt-token')));
+        self::assertTrue($this->authenticator->supports($this->createRequest('Bearer ' . self::PLAIN_TOKEN)));
+        self::assertTrue($this->authenticator->supports($this->createRequest('bearer ' . self::PLAIN_TOKEN)));
+    }
+
+    public function testAuthenticateReturnsCachedUser(): void
+    {
+        $this->storeUserIdForPlainToken();
+        $user = $this->createConfiguredMock(AnzuUser::class, [
+            'getId' => self::USER_ID,
+            'isEnabled' => true,
+        ]);
+        $this->entityManager->method('find')
+            ->with(self::USER_ENTITY_CLASS, self::USER_ID)
+            ->willReturn($user);
+
+        $passport = $this->authenticator->authenticate($this->createRequest('Bearer ' . self::PLAIN_TOKEN));
+
+        self::assertSame($user, $passport->getUser());
+    }
+
+    public function testAuthenticateRejectsDisabledUser(): void
+    {
+        $this->storeUserIdForPlainToken();
+        $user = $this->createConfiguredMock(AnzuUser::class, [
+            'getId' => self::USER_ID,
+            'isEnabled' => false,
+        ]);
+        $this->entityManager->method('find')
+            ->willReturn($user);
+
+        $this->expectException(AuthenticationException::class);
+
+        $this->authenticator->authenticate($this->createRequest('Bearer ' . self::PLAIN_TOKEN));
+    }
+
+    public function testUnauthorizedResponseContainsWwwAuthenticateHeader(): void
+    {
+        $response = $this->authenticator->start(Request::create('/api/mcp'));
+
+        self::assertSame(Response::HTTP_UNAUTHORIZED, $response->getStatusCode());
+        self::assertSame('Bearer', $response->headers->get('WWW-Authenticate'));
+    }
+
+    private function storeUserIdForPlainToken(): void
+    {
+        $tokenHash = AbstractPersonalAccessToken::hashToken(self::PLAIN_TOKEN);
+        $this->authCache->storeUserId(
+            $tokenHash,
+            $this->authCache->getInvalidationVersion($tokenHash),
+            self::USER_ID,
+            AnzuApp::date('+1 hour'),
+        );
+    }
+
+    private function createRequest(string $authorizationHeader): Request
+    {
+        $request = Request::create('/api/mcp');
+        $request->headers->set('Authorization', $authorizationHeader);
+
+        return $request;
+    }
+}
diff --git a/tests/Security/Voter/PersonalAccessTokenVoterTest.php b/tests/Security/Voter/PersonalAccessTokenVoterTest.php
new file mode 100644
index 0000000..07d91d4
--- /dev/null
+++ b/tests/Security/Voter/PersonalAccessTokenVoterTest.php
@@ -0,0 +1,134 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Security\Voter;
+
+use AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission;
+use AnzuSystems\AuthBundle\Security\Voter\PersonalAccessTokenVoter;
+use AnzuSystems\AuthBundle\Tests\Data\Entity\PersonalAccessToken;
+use AnzuSystems\Contracts\Entity\AnzuUser;
+use AnzuSystems\Contracts\Security\Grant;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
+
+final class PersonalAccessTokenVoterTest extends TestCase
+{
+    public function testCreateIsDeniedWithoutMcpRole(): void
+    {
+        $voter = $this->createVoter(isGrantedMap: [
+            [AnzuUser::ROLE_SUPER_ADMIN, null, false],
+            [PersonalAccessTokenPermission::ROLE_MCP, null, false],
+        ]);
+        $user = $this->createUser(permissions: [
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE => Grant::ALLOW,
+        ]);
+
+        $result = $voter->vote($this->createToken($user), null, [PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE]);
+
+        self::assertSame(VoterInterface::ACCESS_DENIED, $result);
+    }
+
+    public function testCreateIsGrantedWithMcpRoleAndAllowGrant(): void
+    {
+        $voter = $this->createVoter(isGrantedMap: [
+            [AnzuUser::ROLE_SUPER_ADMIN, null, false],
+            [PersonalAccessTokenPermission::ROLE_MCP, null, true],
+        ]);
+        $user = $this->createUser(permissions: [
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE => Grant::ALLOW,
+        ]);
+
+        $result = $voter->vote($this->createToken($user), null, [PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE]);
+
+        self::assertSame(VoterInterface::ACCESS_GRANTED, $result);
+    }
+
+    public function testForeignTokenIsDeniedEvenWithAllowGrant(): void
+    {
+        $voter = $this->createVoter(isGrantedMap: [
+            [AnzuUser::ROLE_SUPER_ADMIN, null, false],
+        ]);
+        $user = $this->createUser(permissions: [
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_REVOKE => Grant::ALLOW,
+        ]);
+        $foreignOwner = $this->createConfiguredMock(AnzuUser::class, ['is' => false]);
+        $subject = new PersonalAccessToken()
+            ->setUser($foreignOwner);
+
+        $result = $voter->vote($this->createToken($user), $subject, [PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_REVOKE]);
+
+        self::assertSame(VoterInterface::ACCESS_DENIED, $result);
+    }
+
+    public function testOwnTokenIsGrantedWithAllowOwnerGrant(): void
+    {
+        $voter = $this->createVoter(isGrantedMap: [
+            [AnzuUser::ROLE_SUPER_ADMIN, null, false],
+        ]);
+        $user = $this->createUser(permissions: [
+            PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_REVOKE => Grant::ALLOW_OWNER,
+        ]);
+        $owner = $this->createConfiguredMock(AnzuUser::class, ['is' => true]);
+        $subject = new PersonalAccessToken()
+            ->setUser($owner);
+
+        $result = $voter->vote($this->createToken($user), $subject, [PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_REVOKE]);
+
+        self::assertSame(VoterInterface::ACCESS_GRANTED, $result);
+    }
+
+    public function testSuperAdminBypassesPermissionCheck(): void
+    {
+        $voter = $this->createVoter(isGrantedMap: [
+            [AnzuUser::ROLE_SUPER_ADMIN, null, true],
+        ]);
+        $user = $this->createUser(permissions: []);
+
+        $result = $voter->vote($this->createToken($user), null, [PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_READ]);
+
+        self::assertSame(VoterInterface::ACCESS_GRANTED, $result);
+    }
+
+    public function testUnsupportedAttributeAbstains(): void
+    {
+        $voter = $this->createVoter(isGrantedMap: []);
+
+        $result = $voter->vote($this->createToken($this->createUser([])), null, ['some_other_permission']);
+
+        self::assertSame(VoterInterface::ACCESS_ABSTAIN, $result);
+    }
+
+    /**
+     * @param list<array{0: string, 1: mixed, 2: bool}> $isGrantedMap
+     */
+    private function createVoter(array $isGrantedMap): PersonalAccessTokenVoter
+    {
+        $security = $this->createMock(Security::class);
+        $security->method('isGranted')
+            ->willReturnMap($isGrantedMap);
+        $voter = new PersonalAccessTokenVoter();
+        $voter->setSecurity($security);
+
+        return $voter;
+    }
+
+    /**
+     * @param array<string, int> $permissions
+     */
+    private function createUser(array $permissions): AnzuUser
+    {
+        return $this->createConfiguredMock(AnzuUser::class, ['getResolvedPermissions' => $permissions]);
+    }
+
+    private function createToken(AnzuUser $user): TokenInterface
+    {
+        $token = $this->createMock(TokenInterface::class);
+        $token->method('getUser')
+            ->willReturn($user);
+
+        return $token;
+    }
+}

From 6597224634b8cd58b1307002ccbd524a67797e23 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 11:51:53 +0200
Subject: [PATCH 2/9] Add 6.0.0 changelog

---
 CHANGELOG.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..aeff0c1
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,13 @@
+## [6.0.0](https://github.com/anzusystems/auth-bundle/compare/5.0.0...6.0.0) (2026-07-22)
+
+### Features
+* New opt-in `personal_access_token` config section (disabled by default — upgrading without enabling it requires no schema or configuration changes): sha256-hashed bearer tokens bound to a user with expiration (default 2 months, max 1 year), revocation, a versioned auth cache with the entry lifetime capped at the token expiry, throttled `lastUsedAt` tracking and a read-only-mode guard.
+* `AbstractPersonalAccessToken` mapped superclass — the host subclasses it, owns the table, indexes (`UNIQ_tokenHash`, `IDX_revokedAt_expiresAt`) and migration; the `user` relation targets the contracts `AnzuUser` via doctrine `resolve_target_entities`. Configured via `entity_class`, `user_entity_class` and `auth_cache_pool`.
+* `PersonalAccessTokenAuthenticator` (`Security/Authentication`) — stateless bearer authenticator claiming only tokens with the `anzu_pat_` prefix, cache-first user lookup, uniform information-free 401 responses with a `WWW-Authenticate: Bearer` header.
+* `PersonalAccessTokenVoter` + `PersonalAccessTokenPermission` — `auth_personalAccessToken_(create|read|revoke)` permissions with owner-only access and creation gated by `ROLE_MCP`.
+* `PersonalAccessTokenController` (`Controller/Api`) — list own tokens, create (plaintext returned exactly once, request excluded from audit logs) and revoke; the host defines the routes.
+* Console commands `anzu:personal-access-token:create` (prints the plaintext token once) and `anzu:personal-access-token:notify-expiring` (daily cron notifying owners 7 days and 1 day before expiry through `PersonalAccessTokenExpiryNotifierInterface`; no-op by default — alias your own implementation, which must be idempotent per (token, daysRemaining) pair because consecutive final-notice windows overlap).
+
+### Changes
+* BC change: `anzusystems/common-bundle` requirement floor raised to `^9.4` (uses `AuditLogResourceHelper::excludeFromAuditLogs()`), with `^12.0` allowed.
+* BC change: new explicit `symfony/console` requirement `^7.3|^8.0` (invokable command support).

From eef5b8d81610107d819aabd26aebddc830a0b164 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 11:54:22 +0200
Subject: [PATCH 3/9] Use interface_exists for the doctrine/orm guard

---
 src/DependencyInjection/AnzuSystemsAuthExtension.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/DependencyInjection/AnzuSystemsAuthExtension.php b/src/DependencyInjection/AnzuSystemsAuthExtension.php
index 7356cce..ba1de33 100644
--- a/src/DependencyInjection/AnzuSystemsAuthExtension.php
+++ b/src/DependencyInjection/AnzuSystemsAuthExtension.php
@@ -182,7 +182,7 @@ private function loadPersonalAccessToken(ContainerBuilder $container, array $con
         if (false === $config['enabled']) {
             return;
         }
-        if (false === class_exists(EntityManagerInterface::class)) {
+        if (false === interface_exists(EntityManagerInterface::class)) {
             throw new InvalidArgumentException('The "personal_access_token" config section requires the "doctrine/orm" package.');
         }
         $entityClass = $config['entity_class'];

From c17432f2e7acd6dd6ff8d685b3affc81ed0fe016 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 12:04:25 +0200
Subject: [PATCH 4/9] Fix coding standard violations reported by the current
 ECS ruleset

---
 src/DependencyInjection/Configuration.php     | 122 +++++++++++++-----
 .../GrantAccessByOAuth2TokenProcess.php       |   6 +-
 .../ValidateOAuth2AccessTokenProcess.php      |   5 +-
 src/HttpClient/OAuth2HttpClient.php           |  13 +-
 src/Model/AccessTokenDto.php                  |   3 +-
 src/Model/Enum/JwtAlgorithm.php               |   2 +-
 .../RedisRefreshTokenStorage.php              |   3 +-
 .../Authentication/JwtAuthentication.php      |   3 +-
 src/Util/JwtUtil.php                          |   9 +-
 tests/Util/JwtUtilTest.php                    |   6 +-
 10 files changed, 124 insertions(+), 48 deletions(-)

diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index 6272018..450084f 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -8,9 +8,9 @@
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\GrantAccessByOAuth2TokenProcess;
 use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
 use AnzuSystems\AuthBundle\Model\Enum\AuthType;
-use AnzuSystems\Contracts\Entity\AnzuUser;
 use AnzuSystems\AuthBundle\Model\Enum\JwtAlgorithm;
 use AnzuSystems\AuthBundle\Model\SsoUserDto;
+use AnzuSystems\Contracts\Entity\AnzuUser;
 use Exception;
 use Symfony\Component\Config\Definition\Builder\NodeDefinition;
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
@@ -58,7 +58,9 @@ private function addPersonalAccessTokenSection(): NodeDefinition
                         ->thenInvalid('Invalid personal_access_token user_entity_class "%s".')
                     ->end()
                 ->end()
-                ->scalarNode('auth_cache_pool')->defaultValue('cache.app')->end()
+                ->scalarNode('auth_cache_pool')
+                    ->defaultValue('cache.app')
+                    ->end()
             ->end()
         ;
     }
@@ -69,26 +71,43 @@ private function addCookieSection(): NodeDefinition
             ->isRequired()
             ->addDefaultsIfNotSet()
             ->children()
-                ->scalarNode('domain')->defaultValue(null)->end()
+                ->scalarNode('domain')
+                    ->defaultValue(null)
+                    ->end()
                 ->scalarNode('same_site')
                     ->defaultValue(Cookie::SAMESITE_STRICT)
                     ->info('SameSite attribute for cookies (lax, strict, none or null)')
                 ->end()
-                ->booleanNode('secure')->isRequired()->end()
-                ->scalarNode('device_id_name')->defaultValue('anz_di')->end()
+                ->booleanNode('secure')
+                    ->isRequired()
+                    ->end()
+                ->scalarNode('device_id_name')
+                    ->defaultValue('anz_di')
+                    ->end()
                 ->arrayNode('jwt')
                     ->addDefaultsIfNotSet()
                     ->children()
-                        ->scalarNode('payload_part_name')->defaultValue('anz_jp')->end()
-                        ->scalarNode('signature_part_name')->defaultValue('anz_js')->end()
+                        ->scalarNode('payload_part_name')
+                            ->defaultValue('anz_jp')
+                            ->end()
+                        ->scalarNode('signature_part_name')
+                            ->defaultValue('anz_js')
+                            ->end()
                     ->end()
                 ->end()
                 ->arrayNode('refresh_token')
                     ->addDefaultsIfNotSet()
                     ->children()
-                        ->integerNode('lifetime')->defaultValue(31_536_000)->min(7_200)->end() // 1 year default
-                        ->scalarNode('name')->defaultValue('anz_rt')->end()
-                        ->scalarNode('existence_name')->defaultValue('anz_rte')->end()
+                        ->integerNode('lifetime')
+                            ->defaultValue(31_536_000)
+                            ->min(7_200)
+                            ->end() // 1 year default
+                        ->scalarNode('name')
+                            ->defaultValue('anz_rt')
+                            ->end()
+                        ->scalarNode('existence_name')
+                            ->defaultValue('anz_rte')
+                            ->end()
                     ->end()
                 ->end()
             ->end()
@@ -100,14 +119,25 @@ private function addJwtSection(): NodeDefinition
         return (new TreeBuilder('jwt'))->getRootNode()
             ->isRequired()
             ->children()
-                ->scalarNode('audience')->defaultValue('anz')->cannotBeEmpty()->end()
+                ->scalarNode('audience')
+                    ->defaultValue('anz')
+                    ->cannotBeEmpty()
+                    ->end()
                 ->enumNode('algorithm')
                     ->values(JwtAlgorithm::values())
                     ->defaultValue(JwtAlgorithm::Default->toString())
                 ->end()
-                ->scalarNode('public_cert')->isRequired()->cannotBeEmpty()->end()
-                ->scalarNode('private_cert')->isRequired()->end()
-                ->integerNode('lifetime')->defaultValue(3_600)->min(3_600)->end() // 1 hour
+                ->scalarNode('public_cert')
+                    ->isRequired()
+                    ->cannotBeEmpty()
+                    ->end()
+                ->scalarNode('private_cert')
+                    ->isRequired()
+                    ->end()
+                ->integerNode('lifetime')
+                    ->defaultValue(3_600)
+                    ->min(3_600)
+                    ->end() // 1 hour
             ->end()
         ;
     }
@@ -131,20 +161,28 @@ private function addAuthorizationSection(): NodeDefinition
                             ->children()
                                 ->arrayNode('redis')
                                     ->children()
-                                        ->scalarNode('service_id')->end()
+                                        ->scalarNode('service_id')
+                                            ->end()
                                     ->end()
                                 ->end()
                                 ->arrayNode('custom')
                                     ->children()
-                                        ->scalarNode('service_id')->end()
+                                        ->scalarNode('service_id')
+                                            ->end()
                                     ->end()
                                 ->end()
                             ->end()
                         ->end()
                     ->end()
                 ->end()
-                ->scalarNode('auth_redirect_default_url')->isRequired()->cannotBeEmpty()->end()
-                ->scalarNode('auth_redirect_query_url_allowed_pattern')->isRequired()->cannotBeEmpty()->end()
+                ->scalarNode('auth_redirect_default_url')
+                    ->isRequired()
+                    ->cannotBeEmpty()
+                    ->end()
+                ->scalarNode('auth_redirect_query_url_allowed_pattern')
+                    ->isRequired()
+                    ->cannotBeEmpty()
+                    ->end()
                 ->append($this->addOAuth2AuthorizationSection())
             ->end()
         ;
@@ -158,11 +196,21 @@ private function addOAuth2AuthorizationSection(): NodeDefinition
         return (new TreeBuilder('oauth2'))->getRootNode()
             ->addDefaultsIfNotSet()
             ->children()
-                ->scalarNode('user_repository_service_id')->defaultValue('')->end()
-                ->scalarNode('state_token_salt')->defaultValue(bin2hex(random_bytes(32)))->end()
-                ->booleanNode('state_token_enabled')->defaultTrue()->end()
-                ->scalarNode('authorize_url')->defaultValue('')->end()
-                ->scalarNode('access_token_url')->defaultValue('')->end()
+                ->scalarNode('user_repository_service_id')
+                    ->defaultValue('')
+                    ->end()
+                ->scalarNode('state_token_salt')
+                    ->defaultValue(bin2hex(random_bytes(32)))
+                    ->end()
+                ->booleanNode('state_token_enabled')
+                    ->defaultTrue()
+                    ->end()
+                ->scalarNode('authorize_url')
+                    ->defaultValue('')
+                    ->end()
+                ->scalarNode('access_token_url')
+                    ->defaultValue('')
+                    ->end()
                 ->scalarNode('user_info_url')
                     ->defaultValue('')
                     ->info(sprintf(
@@ -186,13 +234,27 @@ private function addOAuth2AuthorizationSection(): NodeDefinition
                     ->defaultValue(SsoUserDto::class)
                     ->info('Any replacement of the default value class, must extend it.')
                 ->end()
-                ->scalarNode('redirect_url')->defaultValue('')->end()
-                ->scalarNode('client_id')->defaultValue('')->end()
-                ->scalarNode('client_secret')->defaultValue('')->end()
-                ->scalarNode('public_cert')->defaultValue('')->end()
-                ->enumNode('scope_delimiter')->values([' ', ','])->defaultValue(',')->end()
-                ->arrayNode('scopes')->scalarPrototype()->end()->end()
-                ->booleanNode('consider_access_token_as_jwt')->defaultTrue()->end()
+                ->scalarNode('redirect_url')
+                    ->defaultValue('')
+                    ->end()
+                ->scalarNode('client_id')
+                    ->defaultValue('')
+                    ->end()
+                ->scalarNode('client_secret')
+                    ->defaultValue('')
+                    ->end()
+                ->scalarNode('public_cert')
+                    ->defaultValue('')
+                    ->end()
+                ->enumNode('scope_delimiter')
+                    ->values([' ', ','])->defaultValue(',')->end()
+                ->arrayNode('scopes')
+                    ->scalarPrototype()
+                    ->end()
+                    ->end()
+                ->booleanNode('consider_access_token_as_jwt')
+                    ->defaultTrue()
+                    ->end()
                 ->enumNode('auth_method')
                     ->values([GrantAccessByOAuth2TokenProcess::AUTH_METHOD_SSO_ID, GrantAccessByOAuth2TokenProcess::AUTH_METHOD_SSO_EMAIL])
                     ->defaultValue(GrantAccessByOAuth2TokenProcess::AUTH_METHOD_SSO_ID)
diff --git a/src/Domain/Process/OAuth2/GrantAccessByOAuth2TokenProcess.php b/src/Domain/Process/OAuth2/GrantAccessByOAuth2TokenProcess.php
index c62a7f5..8448812 100644
--- a/src/Domain/Process/OAuth2/GrantAccessByOAuth2TokenProcess.php
+++ b/src/Domain/Process/OAuth2/GrantAccessByOAuth2TokenProcess.php
@@ -82,7 +82,7 @@ public function execute(Request $request): Response
 
         try {
             $authUser = $this->getAuthUser($accessTokenDto);
-        } catch (UnsuccessfulUserInfoRequestException | UnsuccessfulAccessTokenRequestException $exception) {
+        } catch (UnsuccessfulUserInfoRequestException|UnsuccessfulAccessTokenRequestException $exception) {
             $this->logException($request, $exception);
 
             return $this->createRedirectResponseForRequest(
@@ -172,7 +172,9 @@ private function getAuthUser(AccessTokenDto $accessTokenDto): ?AnzuAuthUserInter
         if (self::AUTH_METHOD_SSO_ID === $this->authMethod) {
             // prefer to use the jwt
             if ($accessTokenDto->getJwt()) {
-                $ssoUserId = (string) $accessTokenDto->getJwt()->claims()->get(RegisteredClaims::SUBJECT);
+                $ssoUserId = (string) $accessTokenDto->getJwt()
+                    ->claims()
+                    ->get(RegisteredClaims::SUBJECT);
 
                 return $this->oAuth2AuthUserRepository->findOneBySsoUserId($ssoUserId);
             }
diff --git a/src/Domain/Process/OAuth2/ValidateOAuth2AccessTokenProcess.php b/src/Domain/Process/OAuth2/ValidateOAuth2AccessTokenProcess.php
index f14a93a..75cf3aa 100644
--- a/src/Domain/Process/OAuth2/ValidateOAuth2AccessTokenProcess.php
+++ b/src/Domain/Process/OAuth2/ValidateOAuth2AccessTokenProcess.php
@@ -36,7 +36,8 @@ public function execute(Plain $token): void
         }
 
         /** @psalm-var non-empty-string $subject */
-        $subject = (string) $token->claims()->get(RegisteredClaims::SUBJECT);
+        $subject = (string) $token->claims()
+            ->get(RegisteredClaims::SUBJECT);
 
         $constraints = [
             new PermittedFor($this->OAuth2Configuration->getSsoClientId()),
@@ -50,7 +51,7 @@ public function execute(Plain $token): void
 
         try {
             (new Validator())->assert($token, ...$constraints);
-        } catch (RequiredConstraintsViolated | NoConstraintsGiven $exception) {
+        } catch (RequiredConstraintsViolated|NoConstraintsGiven $exception) {
             throw InvalidJwtException::create($token->toString(), $exception);
         }
     }
diff --git a/src/HttpClient/OAuth2HttpClient.php b/src/HttpClient/OAuth2HttpClient.php
index a1265f8..4a805b9 100644
--- a/src/HttpClient/OAuth2HttpClient.php
+++ b/src/HttpClient/OAuth2HttpClient.php
@@ -54,7 +54,8 @@ public function getSsoUserInfo(string $id): SsoUserDto
                 method: Request::METHOD_GET,
                 url: $this->configuration->getSsoUserInfoUrl($id),
                 options: [
-                    'auth_bearer' => $this->requestAccessTokenForClientService()->getAccessToken(),
+                    'auth_bearer' => $this->requestAccessTokenForClientService()
+                        ->getAccessToken(),
                 ]
             );
 
@@ -95,7 +96,8 @@ public function getSsoUserInfoByEmail(string $email): SsoUserDto
                 method: Request::METHOD_GET,
                 url: $this->configuration->getSsoUserInfoByEmailUrl($email),
                 options: [
-                    'auth_bearer' => $this->requestAccessTokenForClientService()->getAccessToken(),
+                    'auth_bearer' => $this->requestAccessTokenForClientService()
+                        ->getAccessToken(),
                 ]
             );
 
@@ -157,9 +159,10 @@ private function sendTokenRequest(string $url, array $bodyParameters): AccessTok
     private function getAccessTokenCacheItem(): CacheItemInterface
     {
         /** @noinspection PhpUnhandledExceptionInspection */
-        return $this->configuration->getAccessTokenCachePool()->getItem(
-            self::CLIENT_SERVICE_ACCESS_TOKEN_CACHE_KEY
-        );
+        return $this->configuration->getAccessTokenCachePool()
+            ->getItem(
+                self::CLIENT_SERVICE_ACCESS_TOKEN_CACHE_KEY
+            );
     }
 
     private function storeAccessTokenToCache(
diff --git a/src/Model/AccessTokenDto.php b/src/Model/AccessTokenDto.php
index 8dfc0f2..2e53f1f 100644
--- a/src/Model/AccessTokenDto.php
+++ b/src/Model/AccessTokenDto.php
@@ -41,7 +41,8 @@ public static function createFromJwtAccessTokenResponse(AccessTokenResponseDto $
     {
         $jwt = $accessTokenResponseDto->getAccessToken();
         /** @var DateTimeInterface $expiresAt */
-        $expiresAt = $jwt->claims()->get('exp');
+        $expiresAt = $jwt->claims()
+            ->get('exp');
 
         return new self($jwt->toString(), $expiresAt, $jwt);
     }
diff --git a/src/Model/Enum/JwtAlgorithm.php b/src/Model/Enum/JwtAlgorithm.php
index b52c173..3f57367 100644
--- a/src/Model/Enum/JwtAlgorithm.php
+++ b/src/Model/Enum/JwtAlgorithm.php
@@ -17,7 +17,7 @@ enum JwtAlgorithm: string implements EnumInterface
 
     public const Default = self::ES256;
 
-    public function signer(): Signer\Ecdsa | Signer\Rsa\Sha256
+    public function signer(): Signer\Ecdsa|Signer\Rsa\Sha256
     {
         return match ($this) {
             self::ES256 => new Signer\Ecdsa\Sha256(),
diff --git a/src/RefreshTokenStorage/RedisRefreshTokenStorage.php b/src/RefreshTokenStorage/RedisRefreshTokenStorage.php
index 4457a65..b2ad0b1 100644
--- a/src/RefreshTokenStorage/RedisRefreshTokenStorage.php
+++ b/src/RefreshTokenStorage/RedisRefreshTokenStorage.php
@@ -45,7 +45,8 @@ public function store(RefreshTokenDto $refreshTokenDto): void
     {
         $this->storageRedis->setex(
             $this->getUserDeviceKey($refreshTokenDto->getUserId(), $refreshTokenDto->getDevice()->getDeviceId()),
-            $refreshTokenDto->getExpiresAt()->getTimestamp() - time(),
+            $refreshTokenDto->getExpiresAt()
+                ->getTimestamp() - time(),
             $this->serializer->serialize($refreshTokenDto),
         );
     }
diff --git a/src/Security/Authentication/JwtAuthentication.php b/src/Security/Authentication/JwtAuthentication.php
index 57ff58e..8c80d2d 100644
--- a/src/Security/Authentication/JwtAuthentication.php
+++ b/src/Security/Authentication/JwtAuthentication.php
@@ -52,7 +52,8 @@ public function authenticate(Request $request): Passport
             new CustomCredentials($this->checkCredentials(...), $jwtToken),
         );
 
-        $impersonatedBy = (string) $jwtToken->claims()->get(self::CLAIM_IMPERSONATED_BY, 0);
+        $impersonatedBy = (string) $jwtToken->claims()
+            ->get(self::CLAIM_IMPERSONATED_BY, 0);
         if (false === empty($impersonatedBy)) {
             $passport->addBadge(new ImpersonationBadge($impersonatedBy));
         }
diff --git a/src/Util/JwtUtil.php b/src/Util/JwtUtil.php
index d4da54e..173cfdc 100644
--- a/src/Util/JwtUtil.php
+++ b/src/Util/JwtUtil.php
@@ -58,7 +58,8 @@ public function create(string $authId, ?DateTimeImmutable $expiresAt = null, arr
 
         /** @var Plain */
         return $builder->getToken(
-            $this->jwtConfiguration->getAlgorithm()->signer(),
+            $this->jwtConfiguration->getAlgorithm()
+                ->signer(),
             InMemory::plainText($privateCert)
         );
     }
@@ -66,13 +67,15 @@ public function create(string $authId, ?DateTimeImmutable $expiresAt = null, arr
     public function validate(Token\Plain $token): bool
     {
         /** @psalm-var non-empty-string $subject */
-        $subject = (string) $token->claims()->get(RegisteredClaims::SUBJECT);
+        $subject = (string) $token->claims()
+            ->get(RegisteredClaims::SUBJECT);
 
         $constraints = [
             new PermittedFor($this->jwtConfiguration->getAudience()),
             new RelatedTo($subject),
             new SignedWith(
-                $this->jwtConfiguration->getAlgorithm()->signer(),
+                $this->jwtConfiguration->getAlgorithm()
+                    ->signer(),
                 InMemory::plainText($this->jwtConfiguration->getPublicCert())
             ),
             new LooseValidAt(SystemClock::fromUTC()),
diff --git a/tests/Util/JwtUtilTest.php b/tests/Util/JwtUtilTest.php
index d75485f..3aa8c47 100644
--- a/tests/Util/JwtUtilTest.php
+++ b/tests/Util/JwtUtilTest.php
@@ -40,7 +40,8 @@ public function testCreate(): void
         $this->assertSame('123', $jwt->claims()->get(RegisteredClaims::SUBJECT));
         $this->assertSame(
             $expireAt->getTimestamp(),
-            $jwt->claims()->get(RegisteredClaims::EXPIRATION_TIME)->getTimestamp()
+            $jwt->claims()
+                ->get(RegisteredClaims::EXPIRATION_TIME)->getTimestamp()
         );
         $this->assertSame(['anz'], $jwt->claims()->get(RegisteredClaims::AUDIENCE));
     }
@@ -58,7 +59,8 @@ public function testCreateWithClaims(): void
         $this->assertSame('quux', $jwt->claims()->get('qux'));
         $this->assertSame(
             $expireAt->getTimestamp(),
-            $jwt->claims()->get(RegisteredClaims::EXPIRATION_TIME)->getTimestamp()
+            $jwt->claims()
+                ->get(RegisteredClaims::EXPIRATION_TIME)->getTimestamp()
         );
         $this->assertSame(['anz'], $jwt->claims()->get(RegisteredClaims::AUDIENCE));
     }

From 359767c3f2bf19b612c389fa15ce1ac73f2430c7 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 12:15:29 +0200
Subject: [PATCH 5/9] Fix psalm errors on the personal access token entity

Final constructor makes the class-string instantiation in the facade safe
and getUser() guards the nullable property explicitly.
---
 src/Entity/AbstractPersonalAccessToken.php | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/Entity/AbstractPersonalAccessToken.php b/src/Entity/AbstractPersonalAccessToken.php
index 8df08c3..3f251c3 100644
--- a/src/Entity/AbstractPersonalAccessToken.php
+++ b/src/Entity/AbstractPersonalAccessToken.php
@@ -18,6 +18,7 @@
 use DateTimeImmutable;
 use Doctrine\DBAL\Types\Types;
 use Doctrine\ORM\Mapping as ORM;
+use LogicException;
 use Symfony\Component\Validator\Constraints as Assert;
 
 #[ORM\MappedSuperclass]
@@ -61,7 +62,7 @@ abstract class AbstractPersonalAccessToken implements IdentifiableInterface, Tim
     #[Serialize]
     protected ?DateTimeImmutable $lastUsedAt = null;
 
-    public function __construct()
+    final public function __construct()
     {
         $this->expiresAt = AnzuApp::date(self::DEFAULT_EXPIRES_AT_DATE);
     }
@@ -78,6 +79,10 @@ public function isRevoked(): bool
 
     public function getUser(): AnzuUser
     {
+        if (null === $this->user) {
+            throw new LogicException('Personal access token user is not set.');
+        }
+
         return $this->user;
     }
 

From 478b57de9f4c91f4c34abf0a4921df6e73e68023 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 12:18:40 +0200
Subject: [PATCH 6/9] Fix extension and facade tests

The user_entity_class validation requires an existing AnzuUser subclass, so
the extension test uses a test entity instead of a nonexistent class name;
the facade test asserts the random token part without mangling the prefix.
---
 tests/Data/Entity/User.php                            | 11 +++++++++++
 .../AnzuSystemsAuthExtensionTest.php                  |  5 +++--
 .../Facade/PersonalAccessTokenFacadeTest.php          |  6 +++---
 3 files changed, 17 insertions(+), 5 deletions(-)
 create mode 100644 tests/Data/Entity/User.php

diff --git a/tests/Data/Entity/User.php b/tests/Data/Entity/User.php
new file mode 100644
index 0000000..8306a2c
--- /dev/null
+++ b/tests/Data/Entity/User.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AnzuSystems\AuthBundle\Tests\Data\Entity;
+
+use AnzuSystems\Contracts\Entity\AnzuUser;
+
+final class User extends AnzuUser
+{
+}
diff --git a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
index d1a833e..7f8ca2c 100644
--- a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
+++ b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
@@ -23,6 +23,7 @@
 use AnzuSystems\AuthBundle\Security\AuthenticationSuccessHandler;
 use AnzuSystems\AuthBundle\Security\Voter\PersonalAccessTokenVoter;
 use AnzuSystems\AuthBundle\Tests\Data\Entity\PersonalAccessToken;
+use AnzuSystems\AuthBundle\Tests\Data\Entity\User;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\Yaml\Parser;
@@ -82,7 +83,7 @@ public function testPersonalAccessTokenConfiguration(): void
         $config['personal_access_token'] = [
             'enabled' => true,
             'entity_class' => PersonalAccessToken::class,
-            'user_entity_class' => 'App\Entity\User',
+            'user_entity_class' => User::class,
             'auth_cache_pool' => 'cache.app',
         ];
         $loader->load([$config], $this->configuration);
@@ -105,7 +106,7 @@ public function testPersonalAccessTokenConfiguration(): void
         self::assertSame(PersonalAccessToken::class, $facadeArguments['$entityClass']);
 
         $authenticatorArguments = $this->configuration->getDefinition(PersonalAccessTokenAuthenticator::class)->getArguments();
-        self::assertSame('App\Entity\User', $authenticatorArguments['$userEntityClass']);
+        self::assertSame(User::class, $authenticatorArguments['$userEntityClass']);
     }
 
     public function testFullConfiguration(): void
diff --git a/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php b/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php
index 43e6b4f..10986d8 100644
--- a/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php
+++ b/tests/Domain/PersonalAccessToken/Facade/PersonalAccessTokenFacadeTest.php
@@ -77,9 +77,9 @@ public function testCreateProducesPrefixedTokenMatchingStoredHash(): void
         $result = $this->facade->create($user, 'test-token');
 
         self::assertStringStartsWith(AbstractPersonalAccessToken::TOKEN_PREFIX, $result->token);
-        self::assertSame(
-            AbstractPersonalAccessToken::TOKEN_PREFIX . str_repeat('0', PersonalAccessTokenFacade::TOKEN_BYTES_LENGTH * 2),
-            preg_replace('~[0-9a-f]~', '0', $result->token),
+        self::assertMatchesRegularExpression(
+            sprintf('~^[0-9a-f]{%d}$~', PersonalAccessTokenFacade::TOKEN_BYTES_LENGTH * 2),
+            substr($result->token, strlen(AbstractPersonalAccessToken::TOKEN_PREFIX)),
         );
         self::assertSame(AbstractPersonalAccessToken::hashToken($result->token), $result->personalAccessToken->getTokenHash());
         self::assertSame('test-token', $result->personalAccessToken->getName());

From 3805fdc6a1ba42d14cb21a1a3753ba7bd39bc15b Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 12:39:01 +0200
Subject: [PATCH 7/9] Make the create role configurable and fix the doctrine
 guard for ChangeApiTokenCommand

The personal access token create gate no longer hardcodes ROLE_MCP - hosts
using tokens for non-MCP integrations configure create_role instead. The
pre-existing class_exists guard on EntityManagerInterface never matched an
interface, so ChangeApiTokenCommand was silently unregistered.
---
 README.md                                                  | 7 +++++--
 src/DependencyInjection/AnzuSystemsAuthExtension.php       | 3 ++-
 src/DependencyInjection/Configuration.php                  | 5 +++++
 src/Security/Voter/PersonalAccessTokenVoter.php            | 7 ++++++-
 tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php | 4 ++++
 5 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index c82423a..fdd3a6d 100644
--- a/README.md
+++ b/README.md
@@ -102,7 +102,10 @@ anzu_systems_auth:
 
 The `user` relation targets `AnzuSystems\Contracts\Entity\AnzuUser` — make sure doctrine
 `resolve_target_entities` maps it to the project user class. Add the doctrine mapping for the bundle's `Entity`
-namespace and generate the migration with `doctrine:migrations:diff`.
+namespace and generate the migration with `doctrine:migrations:diff`. `user_entity_class` must name the same class
+as the common-bundle `settings.user_entity_class` — the authenticator and `CurrentAnzuUserProvider` would otherwise
+load different user classes. The entity relies on constructor-less proxies, so use doctrine/orm 3 (lazy ghosts);
+the ORM 2 legacy proxy strategy conflicts with the final entity constructor.
 
 Wire the authenticator into a firewall protecting the API that accepts the tokens:
 
@@ -122,7 +125,7 @@ Management API routes (list/create/revoke) are provided by
 `AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController` — add routes pointing at its
 `getList`/`create`/`revoke` methods. Authorization uses the `auth_personalAccessToken_(create|read|revoke)`
 permissions (see `AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission`); creation additionally requires
-the `ROLE_MCP` role.
+the role configured via `create_role` (default `ROLE_MCP`).
 
 Console commands:
 
diff --git a/src/DependencyInjection/AnzuSystemsAuthExtension.php b/src/DependencyInjection/AnzuSystemsAuthExtension.php
index ba1de33..cd6039c 100644
--- a/src/DependencyInjection/AnzuSystemsAuthExtension.php
+++ b/src/DependencyInjection/AnzuSystemsAuthExtension.php
@@ -166,7 +166,7 @@ public function load(array $configs, ContainerBuilder $container): void
             }
         }
 
-        if (class_exists(EntityManagerInterface::class)) {
+        if (interface_exists(EntityManagerInterface::class)) {
             $container
                 ->register(ChangeApiTokenCommand::class)
                 ->setAutowired(true)
@@ -230,6 +230,7 @@ private function loadPersonalAccessToken(ContainerBuilder $container, array $con
             ->register(PersonalAccessTokenVoter::class)
             ->setAutowired(true)
             ->setAutoconfigured(true)
+            ->setArgument('$createRole', $config['create_role'])
         ;
 
         $container
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index 450084f..d74d2fd 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -10,6 +10,7 @@
 use AnzuSystems\AuthBundle\Model\Enum\AuthType;
 use AnzuSystems\AuthBundle\Model\Enum\JwtAlgorithm;
 use AnzuSystems\AuthBundle\Model\SsoUserDto;
+use AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission;
 use AnzuSystems\Contracts\Entity\AnzuUser;
 use Exception;
 use Symfony\Component\Config\Definition\Builder\NodeDefinition;
@@ -61,6 +62,10 @@ private function addPersonalAccessTokenSection(): NodeDefinition
                 ->scalarNode('auth_cache_pool')
                     ->defaultValue('cache.app')
                     ->end()
+                ->scalarNode('create_role')
+                    ->defaultValue(PersonalAccessTokenPermission::ROLE_MCP)
+                    ->cannotBeEmpty()
+                    ->end()
             ->end()
         ;
     }
diff --git a/src/Security/Voter/PersonalAccessTokenVoter.php b/src/Security/Voter/PersonalAccessTokenVoter.php
index 1338780..a94db5b 100644
--- a/src/Security/Voter/PersonalAccessTokenVoter.php
+++ b/src/Security/Voter/PersonalAccessTokenVoter.php
@@ -15,10 +15,15 @@
  */
 final class PersonalAccessTokenVoter extends AbstractVoter
 {
+    public function __construct(
+        private readonly string $createRole = PersonalAccessTokenPermission::ROLE_MCP,
+    ) {
+    }
+
     protected function businessLogicVote(string $attribute, mixed $subject, AnzuUser $user): ?bool
     {
         if (PersonalAccessTokenPermission::PERSONAL_ACCESS_TOKEN_CREATE === $attribute
-            && false === $this->security->isGranted(PersonalAccessTokenPermission::ROLE_MCP)
+            && false === $this->security->isGranted($this->createRole)
         ) {
             return false;
         }
diff --git a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
index 7f8ca2c..f4736d9 100644
--- a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
+++ b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
@@ -85,6 +85,7 @@ public function testPersonalAccessTokenConfiguration(): void
             'entity_class' => PersonalAccessToken::class,
             'user_entity_class' => User::class,
             'auth_cache_pool' => 'cache.app',
+            'create_role' => 'ROLE_INTEGRATION',
         ];
         $loader->load([$config], $this->configuration);
 
@@ -107,6 +108,9 @@ public function testPersonalAccessTokenConfiguration(): void
 
         $authenticatorArguments = $this->configuration->getDefinition(PersonalAccessTokenAuthenticator::class)->getArguments();
         self::assertSame(User::class, $authenticatorArguments['$userEntityClass']);
+
+        $voterArguments = $this->configuration->getDefinition(PersonalAccessTokenVoter::class)->getArguments();
+        self::assertSame('ROLE_INTEGRATION', $voterArguments['$createRole']);
     }
 
     public function testFullConfiguration(): void

From 9d632773e09db43fdb725503d80c469fc3678985 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 13:26:21 +0200
Subject: [PATCH 8/9] Align patterns with the bundle conventions

Personal access token controller carries attribute routes like the other
auth controllers (host imports them with a prefix) and the expiry notifier
interface lives in Contracts next to the other extension interfaces.
---
 README.md                                         | 15 +++++++++++----
 .../NotifyExpiringPersonalAccessTokensCommand.php |  2 +-
 ...PersonalAccessTokenExpiryNotifierInterface.php |  2 +-
 .../Api/PersonalAccessTokenController.php         |  6 ++++++
 .../AnzuSystemsAuthExtension.php                  |  2 +-
 .../AnzuSystemsAuthExtensionTest.php              |  2 +-
 6 files changed, 21 insertions(+), 8 deletions(-)
 rename src/{Domain/PersonalAccessToken/Notification => Contracts}/PersonalAccessTokenExpiryNotifierInterface.php (85%)

diff --git a/README.md b/README.md
index fdd3a6d..33516be 100644
--- a/README.md
+++ b/README.md
@@ -122,10 +122,17 @@ security:
 ```
 
 Management API routes (list/create/revoke) are provided by
-`AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController` — add routes pointing at its
-`getList`/`create`/`revoke` methods. Authorization uses the `auth_personalAccessToken_(create|read|revoke)`
-permissions (see `AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission`); creation additionally requires
-the role configured via `create_role` (default `ROLE_MCP`).
+`AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController` attribute routes — import them with a prefix:
+
+```php
+$routes
+    ->import('@AnzuSystemsAuthBundle/Controller/Api/PersonalAccessTokenController.php', type: 'attribute')
+    ->prefix('/api/adm/v1');
+```
+
+Authorization uses the `auth_personalAccessToken_(create|read|revoke)` permissions (see
+`AnzuSystems\AuthBundle\Security\PersonalAccessTokenPermission`); creation additionally requires the role
+configured via `create_role` (default `ROLE_MCP`).
 
 Console commands:
 
diff --git a/src/Command/NotifyExpiringPersonalAccessTokensCommand.php b/src/Command/NotifyExpiringPersonalAccessTokensCommand.php
index cdfdc2d..b60d2ba 100644
--- a/src/Command/NotifyExpiringPersonalAccessTokensCommand.php
+++ b/src/Command/NotifyExpiringPersonalAccessTokensCommand.php
@@ -4,7 +4,7 @@
 
 namespace AnzuSystems\AuthBundle\Command;
 
-use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\PersonalAccessTokenExpiryNotifierInterface;
+use AnzuSystems\AuthBundle\Contracts\PersonalAccessTokenExpiryNotifierInterface;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
 use AnzuSystems\Contracts\AnzuApp;
 use AnzuSystems\Contracts\Exception\AppReadOnlyModeException;
diff --git a/src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php b/src/Contracts/PersonalAccessTokenExpiryNotifierInterface.php
similarity index 85%
rename from src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php
rename to src/Contracts/PersonalAccessTokenExpiryNotifierInterface.php
index 72086f8..43c9d21 100644
--- a/src/Domain/PersonalAccessToken/Notification/PersonalAccessTokenExpiryNotifierInterface.php
+++ b/src/Contracts/PersonalAccessTokenExpiryNotifierInterface.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification;
+namespace AnzuSystems\AuthBundle\Contracts;
 
 use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
 
diff --git a/src/Controller/Api/PersonalAccessTokenController.php b/src/Controller/Api/PersonalAccessTokenController.php
index 3cbdd85..60b1dd8 100644
--- a/src/Controller/Api/PersonalAccessTokenController.php
+++ b/src/Controller/Api/PersonalAccessTokenController.php
@@ -29,7 +29,10 @@
 use Random\RandomException;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Routing\Requirement\Requirement;
 
+#[Route('/personal-access-token', name: 'auth_personal_access_token_')]
 #[OA\Tag('PersonalAccessToken')]
 final class PersonalAccessTokenController extends AbstractAnzuApiController
 {
@@ -40,6 +43,7 @@ public function __construct(
     ) {
     }
 
+    #[Route('', name: 'get_list', methods: [Request::METHOD_GET])]
     #[OAResponse([AbstractPersonalAccessToken::class]), OAResponseUnauthorized, OAResponseForbidden]
     public function getList(): JsonResponse
     {
@@ -53,6 +57,7 @@ public function getList(): JsonResponse
     /**
      * @throws ValidationException|AppReadOnlyModeException|RandomException
      */
+    #[Route('', name: 'create', methods: [Request::METHOD_POST])]
     #[OARequest(PersonalAccessTokenCreateDto::class), OAResponseCreated(PersonalAccessTokenCreateResult::class), OAResponseValidation, OAResponseUnauthorized, OAResponseForbidden]
     public function create(Request $request, #[SerializeParam] PersonalAccessTokenCreateDto $dto): JsonResponse
     {
@@ -77,6 +82,7 @@ public function create(Request $request, #[SerializeParam] PersonalAccessTokenCr
     /**
      * @throws AppReadOnlyModeException
      */
+    #[Route('/{id}/revoke', name: 'revoke', requirements: ['id' => Requirement::POSITIVE_INT], methods: [Request::METHOD_PATCH])]
     #[OAParameterPath('id'), OAResponse(AbstractPersonalAccessToken::class), OAResponseNotFound, OAResponseUnauthorized, OAResponseForbidden]
     public function revoke(Request $request, int $id): JsonResponse
     {
diff --git a/src/DependencyInjection/AnzuSystemsAuthExtension.php b/src/DependencyInjection/AnzuSystemsAuthExtension.php
index cd6039c..074e0ca 100644
--- a/src/DependencyInjection/AnzuSystemsAuthExtension.php
+++ b/src/DependencyInjection/AnzuSystemsAuthExtension.php
@@ -9,6 +9,7 @@
 use AnzuSystems\AuthBundle\Command\NotifyExpiringPersonalAccessTokensCommand;
 use AnzuSystems\AuthBundle\Configuration\OAuth2Configuration;
 use AnzuSystems\AuthBundle\Contracts\OAuth2AuthUserRepositoryInterface;
+use AnzuSystems\AuthBundle\Contracts\PersonalAccessTokenExpiryNotifierInterface;
 use AnzuSystems\AuthBundle\Contracts\RefreshTokenStorageInterface;
 use AnzuSystems\AuthBundle\Controller\Api\JsonCredentialsAuthController;
 use AnzuSystems\AuthBundle\Controller\Api\OAuth2AuthController;
@@ -17,7 +18,6 @@
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\NoopPersonalAccessTokenExpiryNotifier;
-use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\PersonalAccessTokenExpiryNotifierInterface;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\GrantAccessByOAuth2TokenProcess;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\ValidateOAuth2AccessTokenProcess;
diff --git a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
index f4736d9..71a9d38 100644
--- a/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
+++ b/tests/DependencyInjection/AnzuSystemsAuthExtensionTest.php
@@ -7,12 +7,12 @@
 use AnzuSystems\AuthBundle\Command\CreatePersonalAccessTokenCommand;
 use AnzuSystems\AuthBundle\Command\NotifyExpiringPersonalAccessTokensCommand;
 use AnzuSystems\AuthBundle\Configuration\OAuth2Configuration;
+use AnzuSystems\AuthBundle\Contracts\PersonalAccessTokenExpiryNotifierInterface;
 use AnzuSystems\AuthBundle\Controller\Api\PersonalAccessTokenController;
 use AnzuSystems\AuthBundle\DependencyInjection\AnzuSystemsAuthExtension;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Cache\PersonalAccessTokenAuthCache;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Facade\PersonalAccessTokenFacade;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Manager\PersonalAccessTokenManager;
-use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification\PersonalAccessTokenExpiryNotifierInterface;
 use AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Repository\PersonalAccessTokenRepository;
 use AnzuSystems\AuthBundle\Domain\Process\GrantAccessOnResponseProcess;
 use AnzuSystems\AuthBundle\Domain\Process\OAuth2\GrantAccessByOAuth2TokenProcess;

From df29e87d5649cc8e65f0333e451b1b7c3378fd21 Mon Sep 17 00:00:00 2001
From: gabrielzigo <gabriel.zigo@petitpress.sk>
Date: Wed, 22 Jul 2026 13:27:58 +0200
Subject: [PATCH 9/9] Import the notifier interface from Contracts in the noop
 implementation

---
 .../Notification/NoopPersonalAccessTokenExpiryNotifier.php       | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php b/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php
index d16654e..19e336b 100644
--- a/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php
+++ b/src/Domain/PersonalAccessToken/Notification/NoopPersonalAccessTokenExpiryNotifier.php
@@ -4,6 +4,7 @@
 
 namespace AnzuSystems\AuthBundle\Domain\PersonalAccessToken\Notification;
 
+use AnzuSystems\AuthBundle\Contracts\PersonalAccessTokenExpiryNotifierInterface;
 use AnzuSystems\AuthBundle\Entity\AbstractPersonalAccessToken;
 
 final readonly class NoopPersonalAccessTokenExpiryNotifier implements PersonalAccessTokenExpiryNotifierInterface