[salmart-dev]

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

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

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

[provokateurin]

Despite the amount of comments, this looks really good!