Merge branch 'main' into docker-daemon-security-notes

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [1.2.2 - 2023-11-13]
+
+### Fixed
+
+- Fix "of the fix" of the bug in requestToExApp function introduced in previous release.
+
+## [1.2.1 - 2023-11-08]
+
+### Fixed
+
+- Fix bug in requestToExApp function introduced in previous release.
+
+## [1.2.0 - 2023-11-08]
+
+### Changed
+
+- Prototypes of functions for calling external applications and PHP have been redesigned. #112 @bigcat88, @kyteinsky
+- ExApp init (`/init`) endpoint now called with AppAPI auth too. #111
+
+### Fixed
+
+- UI error when default daemon missing. #109
+- FilesActions API: correct cast of file's permission to the number.
+- Docs: ExApp install flow described. #108
+
 ## [1.1.0 - 2023-10-23]
 
 ### Added

Makefile

@@ -35,14 +35,14 @@ dock-sock28:
 	@echo "creating daemon for nextcloud 'master' container"
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_api:daemon:unregister docker_dev || true
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_api:daemon:register \
-		docker_dev Docker docker-install unix-socket /var/run/docker.sock http://nextcloud/index.php --net=master_default
+		docker_dev Docker docker-install unix-socket /var/run/docker.sock http://nextcloud.local/index.php --net=master_default
 
 .PHONY: dock-sock27
 dock-sock27:
 	@echo "creating daemon for nextcloud 'stable27' container"
 	docker exec master-stable27-1 sudo -u www-data php occ app_api:daemon:unregister docker_dev || true
 	docker exec master-stable27-1 sudo -u www-data php occ app_api:daemon:register \
-		docker_dev Docker docker-install unix-socket /var/run/docker.sock http://stable27/index.php --net=master_default
+		docker_dev Docker docker-install unix-socket /var/run/docker.sock http://stable27.local/index.php --net=master_default
 
 .PHONY: dock2port
 dock2port:
@@ -71,13 +71,13 @@ dock-port28:
 	@echo "creating daemon for nextcloud 'master' container"
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_api:daemon:unregister docker_dev || true
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_api:daemon:register \
-    	docker_dev Docker docker-install https host.docker.internal:6443 http://nextcloud/index.php \
+    	docker_dev Docker docker-install https host.docker.internal:6443 http://nextcloud.local/index.php \
     	--net=master_default --ssl_cert /client/cert.pem --ssl_key /client/key.pem
 
 .PHONY: dock-port27
 dock-port27:
 	@echo "creating daemon for nextcloud '27' container"
 	docker exec master-stable27-1 sudo -u www-data php occ app_api:daemon:unregister docker_dev || true
 	docker exec master-stable27-1 sudo -u www-data php occ app_api:daemon:register \
-        docker_dev Docker docker-install https host.docker.internal:6443 http://stable27/index.php \
+        docker_dev Docker docker-install https host.docker.internal:6443 http://stable27.local/index.php \
         --net=master_default --ssl_cert /client/cert.pem --ssl_key /client/key.pem

appinfo/info.xml

@@ -40,7 +40,7 @@ to join us in shaping a more versatile, stable, and secure app landscape.
 *Your insights, suggestions, and contributions are invaluable to us.*
 
 	]]></description>
-	<version>1.1.0</version>
+	<version>1.2.2</version>
 	<licence>agpl</licence>
 	<author mail="[email protected]" homepage="https://github.com/andrey18106">Andrey Borysenko</author>
 	<author mail="[email protected]" homepage="https://github.com/bigcat88">Alexander Piskun</author>

docs/tech_details/Authentication.rst

@@ -26,6 +26,8 @@ Authentication flow
     	Nextcloud-->>-ExApp: Response (200/401)
 
 
+.. _auth-headers:
+
 Authentication headers
 ^^^^^^^^^^^^^^^^^^^^^^
 

docs/tech_details/InstallationFlow.rst

@@ -0,0 +1,75 @@
+.. _app_installation_flow:
+
+App Installation Flow
+=====================
+
+Heartbeat
+---------
+
+The first thing AppAPI does is deploy of the application.
+
+In the case of ``Docker``, this is:
+
+#. 1. performing an image pull
+#. 2. creating container from the docker image
+#. 3. waiting until the “/heartbeat” endpoint becomes available with a ``GET`` request.
+
+The application, in response to the request "/heartbeat", should return json: ``{"status": "ok"}``.
+
+.. note:: The request to ``/heartbeat`` endpoint is made without AppAPI authentication.
+
+Init
+----
+
+After application is ready, which is determined by previous step,
+AppAPI sends ``POST`` request to the ``/init`` application endpoint.
+
+*Application should response with empty JSON, if initialization takes long time it should be done in background and not in this request handler.*
+
+.. note:: Starting from this point, all requests made by AppAPI contains :ref:`auth-headers`.
+
+If the application does not need to carry out long initialization, it can immediately execute an ``OCS request`` to
+``/ocs/v1.php/apps/app_api/apps/status/$APP_ID`` with such a payload in json format::
+
+	{"progress": 100}
+
+If the application initialization takes a long time, the application should periodically send an ``OCS request`` to
+``/ocs/v1.php/apps/app_api/apps/status/$APP_ID`` with the progress value.
+
+Possible values for **progress** are integers from 1 to 100;
+after receiving the value 100, the **application is considered initialized and ready to work**.
+
+If at the initialization stage the application has a critical error due to which its further operation is impossible,
+
+``"error": "some error"``
+
+should be added to the ``OCS request`` for setting progress,
+with a short explanation at what stage this error occurred.
+
+Example of request payload with error will look like this::
+
+	{"progress": 67, "error": "connection error to huggingface."}
+
+Enabled
+-------
+
+After receiving **progress: 100**, AppAPI enables the application.
+
+It is done, by calling ``/enabled`` application endpoint with the ``PUT`` request.
+
+Payload of the request made by AppAPI to the application contains ``enabled`` value, which is ``True`` for enabling.
+
+.. note:: ``/enabled`` endpoint shares both **enabling** and **disabling**,
+	so app should determine what is going on using the ``enabled`` input parameter of the request.
+
+Inside ``/enabled`` handler application should register all actions related to the Nextcloud, like UI and all other stuff.
+
+Response for this request should contain::
+
+	{"error": ""}
+
+for success and if some error occur during **enabling**, it should be present and not be empty::
+
+	{"error": "i cant handle enabling"}
+
+This is all three steps involved in the applications installation flow.

docs/tech_details/api/index.rst

@@ -17,3 +17,4 @@ AppAPI Nextcloud APIs
 	fileactionsmenu
 	notifications
 	talkbots
+	other_ocs

docs/tech_details/api/other_ocs.rst

@@ -0,0 +1,20 @@
+Other OCS APIs
+==============
+
+With AppAPI authentication it is possible for ExApps to use any other OCS APIs, that doesn't require OCP implementation:
+
+.. note::
+
+	To access these APIs they have to be supported by AppAPI (see :ref:`api_scopes`),
+	and ExApp have to require granted access (in ``info.xml``) to them accordingly.
+
+1. Calendar
+2. Contacts
+3. File System & Tags
+4. Shares
+5. Notifications
+6. Users & Groups
+7. User & Weather status
+8. Activities
+9. Notes
+10. Etc.

docs/tech_details/index.rst

@@ -5,6 +5,7 @@ Technical details
    :maxdepth: 2
 
    Glossary
+   InstallationFlow
    ApiScopes
    Deployment
    Authentication

lib/Controller/ExAppsPageController.php

@@ -105,11 +105,13 @@ public function viewApps(): TemplateResponse {
 
 		if ($defaultDaemonConfigName !== '') {
 			$daemonConfig = $this->daemonConfigService->getDaemonConfigByName($defaultDaemonConfigName);
-			$this->dockerActions->initGuzzleClient($daemonConfig);
-			$daemonConfigAccessible = $this->dockerActions->ping($this->dockerActions->buildDockerUrl($daemonConfig));
-			$appInitialData['daemon_config_accessible'] = $daemonConfigAccessible;
-			if (!$daemonConfigAccessible) {
-				$this->logger->error(sprintf('Deploy daemon "%s" is not accessible by Nextcloud. Please verify its configuration', $daemonConfig->getName()));
+			if ($daemonConfig !== null) {
+				$this->dockerActions->initGuzzleClient($daemonConfig);
+				$daemonConfigAccessible = $this->dockerActions->ping($this->dockerActions->buildDockerUrl($daemonConfig));
+				$appInitialData['daemon_config_accessible'] = $daemonConfigAccessible;
+				if (!$daemonConfigAccessible) {
+					$this->logger->error(sprintf('Deploy daemon "%s" is not accessible by Nextcloud. Please verify its configuration', $daemonConfig->getName()));
+				}
 			}
 		}