Feat/admin audit logging

lib/AuditLog/Operation.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Circles\AuditLog;
+
+/**
+ * Operations Teams writes to the admin audit log, in the form `app.entity.action`
+ *
+ * The values are matched by log consumers (filters, alert rules, SIEM imports),
+ * so changing one is a breaking change for them. Case names may be renamed.
+ */
+enum Operation: string {
+	case TeamCreated = 'circles.team.created';
+	case TeamDeleted = 'circles.team.deleted';
+	case TeamRenamed = 'circles.team.renamed';
+	case TeamConfigUpdated = 'circles.team_config.updated';
+	case TeamSettingUpdated = 'circles.team_setting.updated';
+	case InvitationCreated = 'circles.invitation.created';
+	case InvitationRevoked = 'circles.invitation.revoked';
+	case MemberAdded = 'circles.member.added';
+	case MemberInvited = 'circles.member.invited';
+	case MemberRemoved = 'circles.member.removed';
+	case MemberLevelUpdated = 'circles.member_level.updated';
+	case MemberJoined = 'circles.member.joined';
+	case MemberRequested = 'circles.member.requested';
+	case MemberLeft = 'circles.member.left';
+	case RemoteInstanceAdded = 'circles.remote_instance.added';
+	case RemoteInstanceUpdated = 'circles.remote_instance.updated';
+	case RemoteInstanceRemoved = 'circles.remote_instance.removed';
+	case ScimInstanceAdded = 'circles.scim_instance.added';
+	case ScimInstanceRemoved = 'circles.scim_instance.removed';
+	case ConfigUpdated = 'circles.config.updated';
+
+	/**
+	 * Short description of when the operation is logged, used for the documentation
+	 */
+	public function description(): string {
+		return match ($this) {
+			self::TeamCreated => 'A team was created',
+			self::TeamDeleted => 'A team was deleted',
+			self::TeamRenamed => 'A team was renamed',
+			self::TeamConfigUpdated => 'The configuration flags of a team (open, invite only, visible, federated, ...) were changed',
+			self::TeamSettingUpdated => 'A setting of a team, for example the password of its shares, was set or removed',
+			self::InvitationCreated => 'An invitation link to join a team was created',
+			self::InvitationRevoked => 'The invitation link to join a team was revoked',
+			self::MemberAdded => 'A member was added to a team, or a request to join it was accepted',
+			self::MemberInvited => 'A user, group or team was invited to join an invite only team',
+			self::MemberRemoved => 'A member was removed from a team',
+			self::MemberLevelUpdated => 'The level of a member of a team (member, moderator, admin, owner) was changed, including ownership transfers',
+			self::MemberJoined => 'A user joined an open team, through an invitation link or by accepting an invitation',
+			self::MemberRequested => 'A user requested to join a team that requires confirmation',
+			self::MemberLeft => 'A member left a team',
+			self::RemoteInstanceAdded => 'A remote instance was added for federated teams, with the type defining how much it is trusted',
+			self::RemoteInstanceUpdated => 'The identity or the type of a known remote instance for federated teams was changed',
+			self::RemoteInstanceRemoved => 'A remote instance for federated teams was removed',
+			self::ScimInstanceAdded => 'A remote instance was allowed to add members to teams managed by SCIM',
+			self::ScimInstanceRemoved => 'A remote instance was no longer allowed to add members to teams managed by SCIM',
+			self::ConfigUpdated => 'An admin setting of Teams (federated teams, frontal address, team folder quotas) was changed',
+		};
+	}
+}

lib/Command/CirclesRemote.php

@@ -94,7 +94,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
 		if ($host) {
 			if ($input->getOption('delete')) {
-				$this->remoteRequest->deleteInstance($host);
+				$this->remoteStreamService->removeRemoteInstance($host);
 				return 0;
 			} else {
 				$this->requestInstance($host);
@@ -299,7 +299,7 @@ private function saveRemote(RemoteInstance $remoteSignatory) {
 			if (!$this->interfaceService->isInterfaceInternal($remoteSignatory->getInterface())) {
 				$remoteSignatory->setAliases([]);
 			}
-			$this->remoteRequest->save($remoteSignatory);
+			$this->remoteStreamService->saveRemoteInstance($remoteSignatory);
 			$this->output->writeln('<info>remote instance saved</info>');
 		}
 	}

lib/Command/CirclesScimAddRemoteInstance.php

@@ -10,8 +10,10 @@
 namespace OCA\Circles\Command;
 
 use OC\Core\Command\Base;
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\ConfigLexicon;
 use OCA\Circles\Db\RemoteRequest;
+use OCA\Circles\Service\AuditLogService;
 use OCP\AppFramework\Services\IAppConfig;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
@@ -21,6 +23,7 @@ class CirclesScimAddRemoteInstance extends Base {
 	public function __construct(
 		private readonly IAppConfig $appConfig,
 		private readonly RemoteRequest $remoteRequest,
+		private readonly AuditLogService $auditLogService,
 	) {
 		parent::__construct();
 	}
@@ -55,6 +58,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
 		$instances[] = $instance;
 		$this->appConfig->setAppValueArray(ConfigLexicon::SCIM_REMOTE_INSTANCES, $instances);
+		$this->auditLogService->log(Operation::ScimInstanceAdded, 'Remote instance "%s" was allowed to add members to SCIM teams', [
+			'instance' => $instance,
+		]);
 
 		$output->writeln('<info>done</info>');
 

lib/Command/CirclesScimRemoveRemoteInstance.php

@@ -10,7 +10,9 @@
 namespace OCA\Circles\Command;
 
 use OC\Core\Command\Base;
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\ConfigLexicon;
+use OCA\Circles\Service\AuditLogService;
 use OCA\Circles\Service\ScimService;
 use OCP\AppFramework\Services\IAppConfig;
 use Symfony\Component\Console\Input\InputArgument;
@@ -21,6 +23,7 @@ class CirclesScimRemoveRemoteInstance extends Base {
 	public function __construct(
 		private readonly IAppConfig $appConfig,
 		private readonly ScimService $scimService,
+		private readonly AuditLogService $auditLogService,
 	) {
 		parent::__construct();
 	}
@@ -46,6 +49,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
 		unset($instances[$key]);
 		$this->appConfig->setAppValueArray(ConfigLexicon::SCIM_REMOTE_INSTANCES, array_values($instances));
+		$this->auditLogService->log(Operation::ScimInstanceRemoved, 'Remote instance "%s" is no longer allowed to add members to SCIM teams', [
+			'instance' => $instance,
+		]);
 
 		$this->scimService->removeRemoteInstanceMembers($instance);
 

lib/Controller/SettingsController.php

@@ -9,7 +9,9 @@
 
 namespace OCA\Circles\Controller;
 
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\ConfigLexicon;
+use OCA\Circles\Service\AuditLogService;
 use OCA\Circles\Service\ConfigService;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
@@ -24,13 +26,15 @@ public function __construct(
 		IRequest $request,
 		private readonly IAppConfig $appConfig,
 		private readonly IGroupManager $groupManager,
+		private readonly AuditLogService $auditLogService,
 	) {
 		parent::__construct($appName, $request);
 	}
 
 	public function setValue(string $key, string $value): DataResponse {
 		if ($key === ConfigLexicon::FEDERATED_TEAMS_FRONTAL) {
 			if ($this->setFrontalValue($value)) {
+				$this->logSetting($key, $value);
 				return $this->getValues();
 			}
 
@@ -39,6 +43,7 @@ public function setValue(string $key, string $value): DataResponse {
 
 		if ($key === ConfigLexicon::FEDERATED_TEAMS_ENABLED) {
 			$this->appConfig->setAppValueBool(ConfigLexicon::FEDERATED_TEAMS_ENABLED, $value === 'yes');
+			$this->logSetting($key, $value === 'yes' ? 'yes' : 'no');
 			return $this->getValues();
 		}
 
@@ -48,6 +53,7 @@ public function setValue(string $key, string $value): DataResponse {
 			}
 
 			$this->appConfig->setAppValueInt(ConfigLexicon::TEAM_FOLDER_DEFAULT_QUOTA, (int)$value);
+			$this->logSetting($key, (string)(int)$value);
 			return $this->getValues();
 		}
 
@@ -58,6 +64,7 @@ public function setValue(string $key, string $value): DataResponse {
 			}
 
 			$this->appConfig->setAppValueArray(ConfigLexicon::TEAM_FOLDER_GROUP_QUOTAS, $quotas);
+			$this->logSetting($key, (string)json_encode($quotas));
 			return $this->getValues();
 		}
 
@@ -83,6 +90,13 @@ public function getGroups(string $search = ''): DataResponse {
 		));
 	}
 
+	private function logSetting(string $key, string $value): void {
+		$this->auditLogService->log(Operation::ConfigUpdated, 'Teams setting "%s" was set to "%s"', [
+			'key' => $key,
+			'value' => $value,
+		]);
+	}
+
 	/** @param array<mixed> $quotas */
 	private function areValidGroupQuotas(array $quotas): bool {
 		foreach ($quotas as $groupId => $quota) {

lib/Db/RemoteRequest.php

@@ -242,10 +242,11 @@ public function searchDuplicate(RemoteInstance $remoteInstance): RemoteInstance
 	/**
 	 * @param RemoteInstance $remoteInstance
 	 */
-	public function deleteInstance(string $host) {
+	public function deleteInstance(string $host): int {
 		$qb = $this->getRemoteDeleteSql();
 		$qb->limitToInstance($host);
-		$qb->executeStatement();
+
+		return $qb->executeStatement();
 	}
 
 	/**

lib/FederatedItems/CircleConfig.php

@@ -9,6 +9,7 @@
 
 namespace OCA\Circles\FederatedItems;
 
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\Db\CircleRequest;
 use OCA\Circles\Exceptions\FederatedItemBadRequestException;
 use OCA\Circles\Exceptions\FederatedItemException;
@@ -17,6 +18,7 @@
 use OCA\Circles\Model\Circle;
 use OCA\Circles\Model\Federated\FederatedEvent;
 use OCA\Circles\Model\Helpers\MemberHelper;
+use OCA\Circles\Service\AuditLogService;
 use OCA\Circles\Service\ConfigService;
 use OCA\Circles\Service\PermissionService;
 use OCA\Circles\Tools\Traits\TDeserialize;
@@ -36,11 +38,13 @@ class CircleConfig implements
 	 * @param CircleRequest $circleRequest
 	 * @param PermissionService $permissionService
 	 * @param ConfigService $configService
+	 * @param AuditLogService $auditLogService
 	 */
 	public function __construct(
 		private CircleRequest $circleRequest,
 		private PermissionService $permissionService,
 		private ConfigService $configService,
+		private AuditLogService $auditLogService,
 	) {
 	}
 
@@ -146,6 +150,17 @@ public function manage(FederatedEvent $event): void {
 		// TODO: sync if it is to broadcast to Trusted RemoteInstance
 
 		$this->circleRequest->updateConfig($circle);
+
+		$oldConfig = $event->getCircle()->getConfig();
+		if ($config !== $oldConfig) {
+			$this->auditLogService->logTeamChange($circle, Operation::TeamConfigUpdated, 'Configuration of team %s ("%s") was changed from %s to %s by "%s"', [
+				'circleId' => $circle->getSingleId(),
+				'name' => $this->auditLogService->getTeamName($circle),
+				'oldConfig' => $oldConfig,
+				'config' => $config,
+				'initiator' => $this->auditLogService->getInitiator($circle),
+			]);
+		}
 	}
 
 	/**

lib/FederatedItems/CircleCreate.php

@@ -10,6 +10,7 @@
 namespace OCA\Circles\FederatedItems;
 
 use OC\User\NoUserException;
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\Db\CircleRequest;
 use OCA\Circles\Db\MemberRequest;
 use OCA\Circles\Exceptions\CircleNotFoundException;
@@ -22,6 +23,7 @@
 use OCA\Circles\IFederatedItemHighSeverity;
 use OCA\Circles\IFederatedItemMustBeInitializedLocally;
 use OCA\Circles\Model\Federated\FederatedEvent;
+use OCA\Circles\Service\AuditLogService;
 use OCA\Circles\Service\CircleService;
 use OCA\Circles\Service\EventService;
 use OCA\Circles\Service\MaintenanceService;
@@ -47,6 +49,7 @@ public function __construct(
 		private MembershipService $membershipService,
 		private MaintenanceService $maintenanceService,
 		private EventService $eventService,
+		private AuditLogService $auditLogService,
 	) {
 	}
 
@@ -101,6 +104,13 @@ public function manage(FederatedEvent $event): void {
 		}
 
 		$this->eventService->circleCreating($event);
+
+		$this->auditLogService->logTeamChange($circle, Operation::TeamCreated, 'Team %s ("%s") was created with owner "%s" by "%s"', [
+			'circleId' => $circle->getSingleId(),
+			'name' => $this->auditLogService->getTeamName($circle),
+			'owner' => $this->auditLogService->getUserId($owner),
+			'initiator' => $this->auditLogService->getInitiator($circle),
+		]);
 	}
 
 	/**

lib/FederatedItems/CircleCreateInvitation.php

@@ -9,11 +9,13 @@
 
 namespace OCA\Circles\FederatedItems;
 
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\Entity\CircleInvitation;
 use OCA\Circles\IFederatedItem;
 use OCA\Circles\Model\Federated\FederatedEvent;
 use OCA\Circles\Model\Helpers\MemberHelper;
 use OCA\Circles\Repository\CircleInvitationRepository;
+use OCA\Circles\Service\AuditLogService;
 use OCA\Circles\Service\EventService;
 use OCA\Circles\Tools\Traits\TDeserialize;
 use OCP\Security\ISecureRandom;
@@ -25,6 +27,7 @@ class CircleCreateInvitation implements IFederatedItem {
 	public function __construct(
 		private CircleInvitationRepository $circleInvitationRepository,
 		private EventService $eventService,
+		private AuditLogService $auditLogService,
 	) {
 	}
 
@@ -56,6 +59,14 @@ public function manage(FederatedEvent $event): void {
 
 		// todo: do we need separate event here?
 		$this->eventService->circleEditing($event);
+
+		// never logs the invitation code, it lets anyone join the team
+		$circle = $event->getCircle();
+		$this->auditLogService->logTeamChange($circle, Operation::InvitationCreated, 'Invitation link of team %s ("%s") was created by "%s"', [
+			'circleId' => $circle->getSingleId(),
+			'name' => $this->auditLogService->getTeamName($circle),
+			'initiator' => $this->auditLogService->getInitiator($circle),
+		]);
 	}
 
 	public function result(FederatedEvent $event, array $results): void {

lib/FederatedItems/CircleDestroy.php

@@ -9,6 +9,7 @@
 
 namespace OCA\Circles\FederatedItems;
 
+use OCA\Circles\AuditLog\Operation;
 use OCA\Circles\Db\CircleRequest;
 use OCA\Circles\Db\MemberRequest;
 use OCA\Circles\Exceptions\FederatedItemBadRequestException;
@@ -20,6 +21,7 @@
 use OCA\Circles\Model\Circle;
 use OCA\Circles\Model\Federated\FederatedEvent;
 use OCA\Circles\Model\Helpers\MemberHelper;
+use OCA\Circles\Service\AuditLogService;
 use OCA\Circles\Service\EventService;
 use OCA\Circles\Service\MembershipService;
 use OCA\Circles\StatusCode;
@@ -46,12 +48,14 @@ class CircleDestroy implements
 	 * @param MemberRequest $memberRequest
 	 * @param EventService $eventService
 	 * @param MembershipService $membershipService
+	 * @param AuditLogService $auditLogService
 	 */
 	public function __construct(
 		private CircleRequest $circleRequest,
 		private MemberRequest $memberRequest,
 		private EventService $eventService,
 		private MembershipService $membershipService,
+		private AuditLogService $auditLogService,
 	) {
 	}
 
@@ -96,6 +100,12 @@ public function manage(FederatedEvent $event): void {
 		foreach ($parentCirlces as $parentCircle) {
 			$this->membershipService->updatePopulation($parentCircle);
 		}
+
+		$this->auditLogService->logTeamChange($circle, Operation::TeamDeleted, 'Team %s ("%s") was deleted by "%s"', [
+			'circleId' => $circle->getSingleId(),
+			'name' => $this->auditLogService->getTeamName($circle),
+			'initiator' => $this->auditLogService->getInitiator($circle),
+		]);
 	}
 
 	/**