added guest identity

Author: dg

phpstan.neon

@@ -32,3 +32,8 @@ parameters:
 			identifier: argument.type
 			count: 1
 			path: src/Security/User.php
+
+		-   # getGuestIdentity() is declared via @method as optional; method_exists() guards it at runtime
+			identifier: function.alreadyNarrowedType
+			count: 1
+			path: src/Security/User.php

readme.md

@@ -183,6 +183,21 @@ If you prefer the identity to be discarded on every logout and expiration, set `
 Identity is an object that implements the [Nette\Security\IIdentity](https://api.nette.org/master/Nette/Security/IIdentity.html) interface, the default implementation is [Nette\Security\SimpleIdentity](https://api.nette.org/3.0/Nette/Security/SimpleIdentity.html). And as mentioned, identity is stored in the session, so if, for example, we change the role of some of the logged-in users, old data will be kept in the identity until he logs in again.
 
 
+Guest Identity
+--------------
+
+You can provide an identity even for users who are not logged in. If the authenticator implements `IdentityHandler` and its optional method `getGuestIdentity()`, the returned identity is used as a fallback for `getIdentity()`, `getId()` and `getRoles()`. So anonymous visitors can carry their own roles and data instead of the plain `guest` role:
+
+```php
+public function getGuestIdentity(): ?Nette\Security\IIdentity
+{
+	return new Nette\Security\SimpleIdentity('guest', ['guest'], ['name' => 'Guest']);
+}
+```
+
+The guest identity is resolved only when reading and is never stored.
+
+
 
 Authorization
 =============

src/Security/IdentityHandler.php

@@ -10,6 +10,7 @@
 
 /**
  * Serializes and restores identity to/from persistent storage.
+ * @method ?IIdentity getGuestIdentity()
  */
 interface IdentityHandler
 {

src/Security/User.php

@@ -44,7 +44,7 @@ class User
 	/** @deprecated use User::LogoutInactivity */
 	public const INACTIVITY = self::LogoutInactivity;
 
-	/** default role for unauthenticated user */
+	/** role for an unauthenticated user, unless a guest identity provides its own roles */
 	public string $guestRole = 'guest';
 
 	/** default role for authenticated user without own identity */
@@ -62,6 +62,8 @@ class User
 	private ?IIdentity $identity = null;
 	private ?bool $authenticated = null;
 	private ?int $logoutReason = null;
+	private ?IIdentity $guestIdentity = null;
+	private bool $guestIdentityResolved = false;
 
 
 	public function __construct(
@@ -143,13 +145,13 @@ final public function isLoggedIn(): bool
 
 
 	/**
-	 * Returns the user identity. It may be available even when not logged in (e.g. after logout or expiration)
-	 * unless $persistIdentity is disabled, so its presence does not imply the user is logged in; null if none.
+	 * Returns the user identity. When not logged in, this is the retained identity (unless $persistIdentity
+	 * is disabled) or a guest identity if the authenticator provides one; null otherwise.
 	 */
 	final public function getIdentity(): ?IIdentity
 	{
 		$this->loadStoredData();
-		return $this->identity;
+		return $this->identity ?? $this->resolveGuestIdentity();
 	}
 
 
@@ -173,9 +175,23 @@ private function loadStoredData(): void
 	}
 
 
+	/** Returns the guest identity provided by the IdentityHandler authenticator, or null. */
+	private function resolveGuestIdentity(): ?IIdentity
+	{
+		if (!$this->guestIdentityResolved) {
+			$this->guestIdentityResolved = true;
+			$this->guestIdentity = $this->authenticator instanceof IdentityHandler && method_exists($this->authenticator, 'getGuestIdentity')
+				? $this->authenticator->getGuestIdentity()
+				: null;
+		}
+
+		return $this->guestIdentity;
+	}
+
+
 	/**
-	 * Returns the ID of the identity returned by getIdentity(), so it may be available even when not
-	 * logged in; null if there is no identity.
+	 * Returns the ID of the identity returned by getIdentity(), so it may be the retained or guest
+	 * identity's ID even when not logged in; null if there is no identity.
 	 */
 	public function getId(): string|int|null
 	{
@@ -190,6 +206,8 @@ public function getId(): string|int|null
 	final public function refreshStorage(): void
 	{
 		$this->identity = $this->authenticated = $this->logoutReason = null;
+		$this->guestIdentity = null;
+		$this->guestIdentityResolved = false;
 	}
 
 
@@ -199,6 +217,7 @@ final public function refreshStorage(): void
 	public function setAuthenticator(IAuthenticator $handler): static
 	{
 		$this->authenticator = $handler;
+		$this->guestIdentityResolved = false;
 		return $this;
 	}
 
@@ -257,13 +276,13 @@ final public function getLogoutReason(): ?int
 
 	/**
 	 * Returns effective roles derived from the login state, not from the (possibly retained) identity.
-	 * Logged in: the identity's roles, or authenticatedRole. Otherwise: the guestRole.
+	 * Logged in: the identity's roles, or authenticatedRole. Otherwise: the guest identity's roles, or guestRole.
 	 * @return list<string>
 	 */
 	public function getRoles(): array
 	{
 		if (!$this->isLoggedIn()) {
-			return [$this->guestRole];
+			return $this->resolveGuestIdentity()?->getRoles() ?? [$this->guestRole];
 		}
 
 		$identity = $this->getIdentity();

tests/Security/User.emptyRoles.phpt

@@ -0,0 +1,62 @@
+<?php declare(strict_types=1);
+
+/**
+ * Test: Nette\Security\User getRoles() returns an identity's empty roles verbatim,
+ * without falling back to $authenticatedRole or $guestRole.
+ */
+
+use Nette\Security\IIdentity;
+use Nette\Security\SimpleIdentity;
+use Nette\Security\User;
+use Tester\Assert;
+
+
+require __DIR__ . '/../bootstrap.php';
+require __DIR__ . '/MockUserStorage.php';
+
+
+test('logged-in identity with empty roles is returned as-is (no authenticatedRole)', function () {
+	$authenticator = new class implements Nette\Security\Authenticator {
+		public function authenticate(string $username, string $password): IIdentity
+		{
+			return new SimpleIdentity('john', []);
+		}
+	};
+	$user = new User(new MockUserStorage, $authenticator);
+	$user->login('john', 'pass');
+
+	Assert::true($user->isLoggedIn());
+	Assert::same([], $user->getRoles());
+});
+
+
+test('guest identity with empty roles is returned as-is (no guestRole)', function () {
+	$authenticator = new class implements Nette\Security\Authenticator, Nette\Security\IdentityHandler {
+		public function authenticate(string $username, string $password): IIdentity
+		{
+			return new SimpleIdentity('john', ['admin']);
+		}
+
+
+		public function sleepIdentity(IIdentity $identity): IIdentity
+		{
+			return $identity;
+		}
+
+
+		public function wakeupIdentity(IIdentity $identity): ?IIdentity
+		{
+			return $identity;
+		}
+
+
+		public function getGuestIdentity(): ?IIdentity
+		{
+			return new SimpleIdentity('guest', []);
+		}
+	};
+	$user = new User(new MockUserStorage, $authenticator);
+
+	Assert::false($user->isLoggedIn());
+	Assert::same([], $user->getRoles());
+});

tests/Security/User.guestIdentity.phpt

@@ -0,0 +1,157 @@
+<?php declare(strict_types=1);
+
+/**
+ * Test: Nette\Security\User guest identity.
+ */
+
+use Nette\Security\IIdentity;
+use Nette\Security\SimpleIdentity;
+use Nette\Security\User;
+use Tester\Assert;
+
+
+require __DIR__ . '/../bootstrap.php';
+require __DIR__ . '/MockUserStorage.php';
+
+
+class GuestAuthenticator implements Nette\Security\Authenticator, Nette\Security\IdentityHandler
+{
+	public function authenticate(string $username, string $password): IIdentity
+	{
+		return new SimpleIdentity('john', ['admin']);
+	}
+
+
+	public function sleepIdentity(IIdentity $identity): IIdentity
+	{
+		return $identity;
+	}
+
+
+	public function wakeupIdentity(IIdentity $identity): ?IIdentity
+	{
+		return $identity;
+	}
+
+
+	public function getGuestIdentity(): ?IIdentity
+	{
+		return new SimpleIdentity('guest', ['guest-role'], ['name' => 'Guest']);
+	}
+}
+
+
+class RecordingStorage implements Nette\Security\UserStorage
+{
+	/** @var list<IIdentity> */
+	public array $saved = [];
+	private bool $auth = false;
+	private ?IIdentity $identity = null;
+
+
+	public function saveAuthentication(IIdentity $identity): void
+	{
+		$this->saved[] = $identity;
+		$this->auth = true;
+		$this->identity = $identity;
+	}
+
+
+	public function clearAuthentication(bool $clearIdentity): void
+	{
+		$this->auth = false;
+		$this->identity = $clearIdentity ? null : $this->identity;
+	}
+
+
+	public function getState(): array
+	{
+		return [$this->auth, $this->identity, null];
+	}
+
+
+	public function setExpiration(?string $expire, bool $clearIdentity): void
+	{
+	}
+}
+
+
+test('guest identity is exposed when not logged in', function () {
+	$user = new User(new MockUserStorage, new GuestAuthenticator);
+
+	Assert::false($user->isLoggedIn());
+	Assert::equal(new SimpleIdentity('guest', ['guest-role'], ['name' => 'Guest']), $user->getIdentity());
+	Assert::same('guest', $user->getId());
+	Assert::same(['guest-role'], $user->getRoles());
+	Assert::true($user->isInRole('guest-role'));
+	Assert::false($user->isInRole('admin'));
+});
+
+
+test('login overrides the guest identity', function () {
+	$user = new User(new MockUserStorage, new GuestAuthenticator);
+	$user->login('john', 'pass');
+
+	Assert::true($user->isLoggedIn());
+	Assert::same('john', $user->getId());
+	Assert::same(['admin'], $user->getRoles());
+});
+
+
+test('guest identity returns after logout that clears identity', function () {
+	$user = new User(new MockUserStorage, new GuestAuthenticator);
+	$user->login('john', 'pass');
+
+	$user->logout(clearIdentity: true);
+
+	Assert::false($user->isLoggedIn());
+	Assert::same('guest', $user->getId());
+	Assert::same(['guest-role'], $user->getRoles());
+});
+
+
+test('retained identity stays for personalization but roles fall back to the guest identity', function () {
+	$user = new User(new MockUserStorage, new GuestAuthenticator);
+	$user->login('john', 'pass');
+
+	$user->logout(); // persistIdentity is on by default -> identity is retained
+
+	Assert::false($user->isLoggedIn());
+	Assert::same('john', $user->getId()); // retained real identity for personalization
+	Assert::same(['guest-role'], $user->getRoles()); // but NOT the real ['admin'] roles
+});
+
+
+test('without a guest identity provider the behaviour is unchanged', function () {
+	$authenticator = new class implements Nette\Security\Authenticator {
+		public function authenticate(string $username, string $password): IIdentity
+		{
+			return new SimpleIdentity('john', ['admin']);
+		}
+	};
+	$user = new User(new MockUserStorage, $authenticator);
+
+	Assert::false($user->isLoggedIn());
+	Assert::null($user->getIdentity());
+	Assert::same(['guest'], $user->getRoles());
+});
+
+
+test('guest identity is never written to storage', function () {
+	$storage = new RecordingStorage;
+	$user = new User($storage, new GuestAuthenticator);
+
+	// acting as a guest must not persist anything
+	Assert::same('guest', $user->getId());
+	Assert::same(['guest-role'], $user->getRoles());
+	Assert::equal(new SimpleIdentity('guest', ['guest-role'], ['name' => 'Guest']), $user->getIdentity());
+	Assert::same([], $storage->saved);
+
+	// login/logout cycle, then guest again
+	$user->login('john', 'pass');
+	$user->logout(clearIdentity: true);
+	Assert::same('guest', $user->getId());
+
+	// only the real identity may ever reach the storage
+	Assert::same(['john'], array_map(fn(IIdentity $i) => $i->getId(), $storage->saved));
+});

tests/Security/User.identityHandler.phpt

@@ -52,6 +52,12 @@ class AuthenticatorWithHandler implements Nette\Security\Authenticator, Nette\Se
 		// Real implementation would fetch fresh data from DB
 		return new SimpleIdentity($identity->getId(), ['admin', 'user'], ['name' => 'John Doe Updated']);
 	}
+
+
+	public function getGuestIdentity(): ?IIdentity
+	{
+		return null;
+	}
 }
 
 
@@ -124,6 +130,12 @@ test('IdentityHandler.wakeupIdentity() returning null logs user out', function (
 			// Simulate invalid token/expired session
 			return null;
 		}
+
+
+		public function getGuestIdentity(): ?IIdentity
+		{
+			return null;
+		}
 	};
 
 	$storage = new MockUserStorage;

tests/Security/User.refreshStorage.phpt

@@ -195,6 +195,12 @@ test('refreshStorage() with IdentityHandler triggers wakeup again', function ()
 				array_merge($identity->getRoles(), ['role' . $this->wakeupCount]),
 			);
 		}
+
+
+		public function getGuestIdentity(): ?IIdentity
+		{
+			return null;
+		}
 	};
 
 	$storage = new MutableStorage;