feat(admin_audit): add stable operation identifier to audit log entries

Every audit log entry now carries a machine-readable "operation" field
(e.g. "files.file.read") in its data, next to the human-readable message.
Log consumers can filter on it instead of matching message text, which
may change between releases.

The names are defined once in the new OCA\AdminAudit\Operation enum.
Operations passed by other apps through CriticalActionPerformedEvent are
written as given.

Refs nextcloud-gmbh/governance#199

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Ghassen kefi <ghassen.kefi.dev@gmail.com>

Author: GhassenKefi

apps/admin_audit/composer/composer/autoload_classmap.php

@@ -27,4 +27,5 @@
     'OCA\\AdminAudit\\Listener\\SharingEventListener' => $baseDir . '/../lib/Listener/SharingEventListener.php',
     'OCA\\AdminAudit\\Listener\\TagEventListener' => $baseDir . '/../lib/Listener/TagEventListener.php',
     'OCA\\AdminAudit\\Listener\\UserManagementEventListener' => $baseDir . '/../lib/Listener/UserManagementEventListener.php',
+    'OCA\\AdminAudit\\Operation' => $baseDir . '/../lib/Operation.php',
 );

apps/admin_audit/composer/composer/autoload_static.php

@@ -42,6 +42,7 @@ class ComposerStaticInitAdminAudit
         'OCA\\AdminAudit\\Listener\\SharingEventListener' => __DIR__ . '/..' . '/../lib/Listener/SharingEventListener.php',
         'OCA\\AdminAudit\\Listener\\TagEventListener' => __DIR__ . '/..' . '/../lib/Listener/TagEventListener.php',
         'OCA\\AdminAudit\\Listener\\UserManagementEventListener' => __DIR__ . '/..' . '/../lib/Listener/UserManagementEventListener.php',
+        'OCA\\AdminAudit\\Operation' => __DIR__ . '/..' . '/../lib/Operation.php',
     );
 
     public static function getInitializer(ClassLoader $loader)

apps/admin_audit/lib/Actions/Action.php

@@ -9,6 +9,7 @@
 namespace OCA\AdminAudit\Actions;
 
 use OCA\AdminAudit\IAuditLogger;
+use OCA\AdminAudit\Operation;
 
 class Action {
 
@@ -20,21 +21,28 @@ public function __construct(
 	/**
 	 * Log a single action with a log level of info
 	 *
+	 * @param Operation|string|null $operation Stable identifier of the action. A string in the form `app.entity.action` is only expected from other apps via CriticalActionPerformedEvent
 	 * @param string $text
 	 * @param array<string, scalar|null|\DateTimeInterface> $params
 	 * @param list<string> $elements
 	 * @param bool $obfuscateParameters
 	 */
 	public function log(
+		Operation|string|null $operation,
 		string $text,
 		array $params,
 		array $elements,
 		bool $obfuscateParameters = false,
 	): void {
+		$baseContext = ['app' => 'admin_audit'];
+		if ($operation !== null) {
+			$baseContext['operation'] = $operation instanceof Operation ? $operation->value : $operation;
+		}
+
 		foreach ($elements as $element) {
 			if (!array_key_exists($element, $params)) {
 				$message = '$params["' . $element . '"] was missing.';
-				$context = ['app' => 'admin_audit'];
+				$context = $baseContext;
 
 				if (!$obfuscateParameters) {
 					$message .= ' Transferred value: {params}';
@@ -47,7 +55,7 @@ public function log(
 		}
 
 		$replaceArray = [];
-		$context = ['app' => 'admin_audit'];
+		$context = $baseContext;
 		foreach ($elements as $element) {
 			$value = $params[$element];
 			if ($value instanceof \DateTimeInterface) {

apps/admin_audit/lib/Actions/Files.php

@@ -9,6 +9,7 @@
 namespace OCA\AdminAudit\Actions;
 
 use OC\Files\Node\NonExistingFile;
+use OCA\AdminAudit\Operation;
 use OCP\Files\Events\Node\BeforeNodeDeletedEvent;
 use OCP\Files\Events\Node\BeforeNodeReadEvent;
 use OCP\Files\Events\Node\NodeCopiedEvent;
@@ -43,6 +44,7 @@ public function read(BeforeNodeReadEvent $event): void {
 			return;
 		}
 		$this->log(
+			Operation::FileRead,
 			'File with id "%s" accessed: "%s"',
 			$params,
 			array_keys($params)
@@ -69,6 +71,7 @@ public function afterRename(NodeRenamedEvent $event): void {
 		}
 
 		$this->log(
+			Operation::FileRenamed,
 			'File renamed with id "%s" from "%s" to "%s"',
 			$params,
 			array_keys($params)
@@ -95,6 +98,7 @@ public function create(NodeCreatedEvent $event): void {
 			return;
 		}
 		$this->log(
+			Operation::FileCreated,
 			'File with id "%s" created: "%s"',
 			$params,
 			array_keys($params)
@@ -121,6 +125,7 @@ public function copy(NodeCopiedEvent $event): void {
 			return;
 		}
 		$this->log(
+			Operation::FileCopied,
 			'File id copied from: "%s" to "%s", path from "%s" to "%s"',
 			$params,
 			array_keys($params)
@@ -148,6 +153,7 @@ public function write(NodeWrittenEvent $event): void {
 		}
 
 		$this->log(
+			Operation::FileWritten,
 			'File with id "%s" written to: "%s"',
 			$params,
 			array_keys($params)
@@ -171,6 +177,7 @@ public function delete(BeforeNodeDeletedEvent $event): void {
 			return;
 		}
 		$this->log(
+			Operation::FileDeleted,
 			'File with id "%s" deleted: "%s"',
 			$params,
 			array_keys($params)

apps/admin_audit/lib/Actions/Sharing.php

@@ -8,6 +8,8 @@
 
 namespace OCA\AdminAudit\Actions;
 
+use OCA\AdminAudit\Operation;
+
 /**
  * Class Sharing logs the sharing actions
  *
@@ -22,6 +24,7 @@ class Sharing extends Action {
 	 */
 	public function updatePermissions(array $params): void {
 		$this->log(
+			Operation::SharePermissionsUpdated,
 			'The permissions of the shared %s "%s" with ID "%s" have been changed to "%s"',
 			$params,
 			[
@@ -40,6 +43,7 @@ public function updatePermissions(array $params): void {
 	 */
 	public function updatePassword(array $params): void {
 		$this->log(
+			Operation::SharePasswordUpdated,
 			'The password of the publicly shared %s "%s" with ID "%s" has been changed',
 			$params,
 			[
@@ -58,6 +62,7 @@ public function updatePassword(array $params): void {
 	public function updateExpirationDate(array $params): void {
 		if ($params['date'] === null) {
 			$this->log(
+				Operation::ShareExpirationRemoved,
 				'The expiration date of the publicly shared %s with ID "%s" has been removed',
 				$params,
 				[
@@ -67,6 +72,7 @@ public function updateExpirationDate(array $params): void {
 			);
 		} else {
 			$this->log(
+				Operation::ShareExpirationUpdated,
 				'The expiration date of the publicly shared %s with ID "%s" has been changed to "%s"',
 				$params,
 				[
@@ -85,6 +91,7 @@ public function updateExpirationDate(array $params): void {
 	 */
 	public function shareAccessed(array $params): void {
 		$this->log(
+			Operation::ShareLinkAccessed,
 			'The shared %s with the token "%s" by "%s" has been accessed.',
 			$params,
 			[

apps/admin_audit/lib/Actions/Trashbin.php

@@ -8,15 +8,17 @@
 
 namespace OCA\AdminAudit\Actions;
 
+use OCA\AdminAudit\Operation;
+
 class Trashbin extends Action {
 	public function delete(array $params): void {
-		$this->log('File "%s" deleted from trash bin.',
+		$this->log(Operation::TrashbinFileDeleted, 'File "%s" deleted from trash bin.',
 			['path' => $params['path']], ['path']
 		);
 	}
 
 	public function restore(array $params): void {
-		$this->log('File "%s" restored from trash bin.',
+		$this->log(Operation::TrashbinFileRestored, 'File "%s" restored from trash bin.',
 			['path' => $params['filePath']], ['path']
 		);
 	}

apps/admin_audit/lib/Actions/Versions.php

@@ -8,9 +8,11 @@
 
 namespace OCA\AdminAudit\Actions;
 
+use OCA\AdminAudit\Operation;
+
 class Versions extends Action {
 	public function delete(array $params): void {
-		$this->log('Version "%s" was deleted.',
+		$this->log(Operation::VersionDeleted, 'Version "%s" was deleted.',
 			['path' => $params['path']],
 			['path']
 		);

apps/admin_audit/lib/Listener/AppManagementEventListener.php

@@ -10,6 +10,7 @@
 namespace OCA\AdminAudit\Listener;
 
 use OCA\AdminAudit\Actions\Action;
+use OCA\AdminAudit\Operation;
 use OCP\App\Events\AppDisableEvent;
 use OCP\App\Events\AppEnableEvent;
 use OCP\App\Events\AppUpdateEvent;
@@ -33,27 +34,27 @@ public function handle(Event $event): void {
 
 	private function appEnable(AppEnableEvent $event): void {
 		if (empty($event->getGroupIds())) {
-			$this->log('App "%s" enabled',
+			$this->log(Operation::AppEnabled, 'App "%s" enabled',
 				['app' => $event->getAppId()],
 				['app']
 			);
 		} else {
-			$this->log('App "%1$s" enabled for groups: %2$s',
+			$this->log(Operation::AppEnabled, 'App "%1$s" enabled for groups: %2$s',
 				['app' => $event->getAppId(), 'groups' => implode(', ', $event->getGroupIds())],
 				['app', 'groups']
 			);
 		}
 	}
 
 	private function appDisable(AppDisableEvent $event): void {
-		$this->log('App "%s" disabled',
+		$this->log(Operation::AppDisabled, 'App "%s" disabled',
 			['app' => $event->getAppId()],
 			['app']
 		);
 	}
 
 	private function appUpdate(AppUpdateEvent $event): void {
-		$this->log('App "%s" updated',
+		$this->log(Operation::AppUpdated, 'App "%s" updated',
 			['app' => $event->getAppId()],
 			['app']
 		);

apps/admin_audit/lib/Listener/AuthEventListener.php

@@ -10,6 +10,7 @@
 namespace OCA\AdminAudit\Listener;
 
 use OCA\AdminAudit\Actions\Action;
+use OCA\AdminAudit\Operation;
 use OCP\Authentication\Events\AnyLoginFailedEvent;
 use OCP\EventDispatcher\Event;
 use OCP\EventDispatcher\IEventListener;
@@ -37,6 +38,7 @@ public function handle(Event $event): void {
 
 	private function beforeUserLoggedIn(BeforeUserLoggedInEvent $event): void {
 		$this->log(
+			Operation::LoginAttempted,
 			'Login attempt: "%s"',
 			[
 				'uid' => $event->getUsername()
@@ -50,6 +52,7 @@ private function beforeUserLoggedIn(BeforeUserLoggedInEvent $event): void {
 
 	private function userLoggedIn(UserLoggedInWithCookieEvent|UserLoggedInEvent $event): void {
 		$this->log(
+			Operation::LoginSucceeded,
 			'Login successful: "%s"',
 			[
 				'uid' => $event->getUser()->getUID()
@@ -63,6 +66,7 @@ private function userLoggedIn(UserLoggedInWithCookieEvent|UserLoggedInEvent $eve
 
 	private function beforeUserLogout(BeforeUserLoggedOutEvent $event): void {
 		$this->log(
+			Operation::LogoutPerformed,
 			'Logout occurred',
 			[],
 			[]
@@ -71,6 +75,7 @@ private function beforeUserLogout(BeforeUserLoggedOutEvent $event): void {
 
 	private function anyLoginFailed(AnyLoginFailedEvent $event): void {
 		$this->log(
+			Operation::LoginFailed,
 			'Login failed: "%s"',
 			[
 				'loginName' => $event->getLoginName()

apps/admin_audit/lib/Listener/CacheEventListener.php

@@ -10,6 +10,7 @@
 namespace OCA\AdminAudit\Listener;
 
 use OCA\AdminAudit\Actions\Action;
+use OCA\AdminAudit\Operation;
 use OCP\EventDispatcher\Event;
 use OCP\EventDispatcher\IEventListener;
 use OCP\Files\Cache\CacheEntryInsertedEvent;
@@ -29,7 +30,7 @@ public function handle(Event $event): void {
 	}
 
 	private function entryInserted(CacheEntryInsertedEvent $event): void {
-		$this->log('Cache entry inserted for fileid "%1$d", path "%2$s" on storageid "%3$d"',
+		$this->log(Operation::CacheEntryInserted, 'Cache entry inserted for fileid "%1$d", path "%2$s" on storageid "%3$d"',
 			[
 				'fileid' => $event->getFileId(),
 				'path' => $event->getPath(),
@@ -40,7 +41,7 @@ private function entryInserted(CacheEntryInsertedEvent $event): void {
 	}
 
 	private function entryRemoved(CacheEntryRemovedEvent $event): void {
-		$this->log('Cache entry removed for fileid "%1$d", path "%2$s" on storageid "%3$d"',
+		$this->log(Operation::CacheEntryRemoved, 'Cache entry removed for fileid "%1$d", path "%2$s" on storageid "%3$d"',
 			[
 				'fileid' => $event->getFileId(),
 				'path' => $event->getPath(),