Skip to content

feat: introduce the genric Actor entity - #65987

Merged
susnux merged 10 commits into
masterfrom
feat/ncu-actor
Nov 12, 2026
Merged

susnux merged 10 commits into
masterfrom
feat/ncu-actor

Conversation

@salmart-dev

@salmart-dev salmart-dev commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Introduces an Actor data object to pass around the information of who is performing an action / request, and include information about "privilege escalation" or delegation, so that audit or compliance apps can log a chain, and apps can take decisions losing less context and avoiding mix ups like $userId = null equalling to "all privileges" or "no privileges" depending on the call, which are completely different answers.

The DelegationKind and PrincipalType could be extended in the future as "stable" cases become more prominent.

Example: SystemTagManager

I took the example of the SystemTagManager, where I stumbled on the pattern first-hand.

Before

  public function getTagsByIds($tagIds, ?IUser $user = null): array {
          // ...
          while ($row = $result->fetchAssociative()) {
                  $tag = $this->createSystemTagFromRow($row);
                  if ($user && !$this->canUserSeeTag($tag, $user)) { // null: no filtering
                          continue;
                  }
                  $tags[$row['id']] = $tag;
          }
          // ...
  }

  public function createTag(string $tagName, bool $userVisible, bool $userAssignable, ?IUser $user = null): ISystemTag {
          $user ??= $this->userSession->getUser(); // null: whoever is in the session
          if (!$this->canUserCreateTag($user)) {
                  throw new TagCreationForbiddenException();
          }
          // ...
  }

  public function canUserCreateTag(?IUser $user): bool {
          if ($user === null) {
                  return \OC::$CLI; // null: allowed only if PHP runs from the command line
          }
          // ...
  }

  public function canUserAssignTag(ISystemTag $tag, ?IUser $user): bool {
          if ($user === null) {
                  return false; // null: nobody
          }
          // ...
  }

  public function canUserSeeTag(ISystemTag $tag, ?IUser $user): bool {
          if (!$user && $tag->getAccessLevel() === ISystemTag::ACCESS_LEVEL_PUBLIC) {
                  return true; // null: anonymous visitor
          }
          // ...
  }

After

  public function getTagsByIds($tagIds, Actor $actor): array {
          // ...
          while ($row = $result->fetchAssociative()) {
                  $tag = $this->createSystemTagFromRow($row);
                  if (!$this->canSeeTag($tag, $actor)) {
                          continue;
                  }
                  $tags[$row['id']] = $tag;
          }
          // ...
  }

  public function createTag(string $tagName, bool $userVisible, bool $userAssignable, Actor $actor): ISystemTag {
          if (!$this->canCreateTag($actor)) {
                  throw new TagCreationForbiddenException();
          }
          // ...
  }

  public function canCreateTag(Actor $actor): bool {
          $principal = $actor->principal;
          return match ($principal->type) {
                  PrincipalType::System => true,
                  PrincipalType::User => !$this->appConfig->getValueBool('systemtags', 'restrict_creation_to_admin', false)
                          || $this->groupManager->isAdmin($principal->id),
                  default => false,
          };
  }

  public function canAssignTag(ISystemTag $tag, Actor $actor): bool {
          $principal = $actor->principal;
          return match ($principal->type) {
                  PrincipalType::System => true,
                  PrincipalType::User => $this->canUserAssignTag($tag, $principal->id),
                  default => false,
          };
  }

  public function canSeeTag(ISystemTag $tag, Actor $actor): bool {
          $principal = $actor->principal;
          return match ($principal->type) {
                  PrincipalType::System => true,
                  PrincipalType::User => $tag->isUserVisible() || $this->groupManager->isAdmin($principal->id),
                  PrincipalType::Guest => $tag->getAccessLevel() === ISystemTag::ACCESS_LEVEL_PUBLIC,
                  default => false,
          };
  }

Checklist

AI (if applicable)

  • The content of this PR was partly or fully generated using AI

@salmart-dev salmart-dev added this to the Nextcloud 36 milestone Oct 28, 2026
@salmart-dev salmart-dev added the 3. to review Waiting for reviews label Oct 28, 2026
@salmart-dev salmart-dev self-assigned this Oct 28, 2026
@salmart-dev
salmart-dev marked this pull request as ready for review October 28, 2026 17:40
@salmart-dev
salmart-dev requested a review from a team as a code owner October 28, 2026 17:40
@salmart-dev
salmart-dev requested review from icewind1991, leftybournes, provokateurin and sorbaugh and removed request for a team October 28, 2026 17:40

@provokateurin provokateurin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Despite the amount of comments, this looks really good!

Comment thread lib/unstable/Actor/Actor.php Resolved
Comment thread lib/unstable/Actor/Actor.php Resolved
Comment thread lib/public/Actor/Actor.php Resolved
Comment thread lib/unstable/Actor/Actor.php Resolved
Comment thread lib/unstable/Actor/Actor.php Resolved
Comment thread lib/unstable/Actor/Principal.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
Comment thread lib/unstable/Actor/PrincipalType.php Resolved
Comment thread lib/unstable/Actor/PrincipalType.php Resolved
Comment thread lib/unstable/Actor/PrincipalType.php Resolved
Comment thread lib/unstable/Actor/Actor.php Resolved
@susnux susnux changed the title feat: introduce Actor data object in NCU feat: introduce the genric Actor entity Nov 2, 2026
@susnux
susnux force-pushed the feat/ncu-actor branch 2 times, most recently from 686c399 to d9c99aa Compare November 2, 2026 15:52
@susnux
susnux requested review from GhassenKefi and provokateurin and removed request for sorbaugh November 2, 2026 15:53
@susnux
susnux force-pushed the feat/ncu-actor branch 2 times, most recently from bc340c7 to 0186db6 Compare November 4, 2026 19:02
Comment thread lib/unstable/Actor/Actor.php Resolved
Comment thread lib/unstable/Actor/Actor.php Resolved
Comment thread lib/public/Actor/Actor.php Resolved
Comment thread lib/public/Actor/Principal.php Outdated
Comment on lines +68 to +109
public static function user(string $userId): self {
return new self(PrincipalType::User, $userId);
}

/**
* @param non-empty-string $userId - federated user id
* @param non-empty-string $remote - remote instance
* @experimental 36.0.0
*/
public static function federatedUser(string $userId, string $remote): self {
return new self(PrincipalType::User, $userId, $remote);
}

/**
* @param non-empty-string $externalId - anonymous user id
* @param non-empty-string $source app-namespaced kind of external user, e.g. "spreed.email"
* @param ?non-empty-string $token - share/room token, if any
* @experimental 36.0.0
*/
public static function anonymous(string $externalId, string $source, ?string $token = null): self {
return new self(PrincipalType::Anonymous, $externalId, $token, $source);
}

/**
* @param non-empty-string $botId - bot id
* @param ?non-empty-string $source - app owning the bot, e.g. "spreed"
* @experimental 36.0.0
*/
public static function bot(string $botId, ?string $source = null): self {
return new self(PrincipalType::Bot, $botId, null, $source);
}

/**
* Identifies a component, e.g. "governance.retention".
*
* @param non-empty-string $component - component name
* @param ?non-empty-string $source - app owning the component, e.g. "app_api"
* @experimental 36.0.0
*/
public static function system(string $component, ?string $source = null): self {
return new self(PrincipalType::System, $component, null, $source);
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feels a bit out of touch with the rest of Nextcloud code, where we usually rather do class extention, like:

class PrincipalActor {
	private function __construct(
		public PrincipalType $type,
		public string $id,
		public ?string $origin = null,
		public ?string $source = null,
	) {
		...
	}

	public function is(PrincipalType $type): bool {
		...
	}

	public function equals(self $other): bool {
		...
	}
}

class UserActor extends PrincipalActor {
	private function __construct(
		public string $id,
	) {
		...
	}
}

class FederatedUser extends PrincipalActor {
	private function __construct(
		public string $id,
		public ?string $origin = null,
	) {
		...
	}
}

class BotActor extends PrincipalActor {
	private function __construct(
		public string $appId,
		public string $botId,
	) {
		...
	}
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I won't hardly oppose this new pattern though, so fine to merge as is if you think otherwise :).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case a new class does not communicate something new, this by design should not be enhanced with new attributes like "user groups" etc. The idea of this API is simply communicating the identity, data attributes can be fetched from the proper APIs if needed, out of scope of this API.

So this only needs to communicate the type and the identifier(s), so new classes seem a bit over the top for this

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this only needs to communicate the type and the identifier(s), so new classes seem a bit over the top for this

Probably, it is just more aligned with the other APIs. I don't think we have other APIs where we use static methods to instanciate object.

@susnux
susnux requested a review from artonge November 5, 2026 18:09
Comment thread lib/public/Actor/Actor.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
Comment thread lib/public/Actor/Principal.php Resolved
@susnux
susnux requested a review from provokateurin November 9, 2026 19:16
salmart-dev and others added 10 commits November 10, 2026 16:40
Signed-off-by: Salvatore Martire <4652631+salmart-dev@users.noreply.github.com>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
@susnux
susnux merged commit d04a299 into master Nov 12, 2026
153 of 155 checks passed
@susnux
susnux deleted the feat/ncu-actor branch November 12, 2026 17:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants