Merge pull request #699 from nextcloud/feat/noid/add-openapi

feat: Add OpenAPI

.github/CODEOWNERS

@@ -1 +1 @@
-/appinfo/info.xml   @juliushaertl @Altahrim
+/appinfo/info.xml   @juliusknorr @Altahrim

.github/workflows/openapi.yml

@@ -0,0 +1,94 @@
+# This workflow is provided via the organization template repository
+#
+# https://github.com/nextcloud/.github
+# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization
+#
+# SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+# SPDX-FileCopyrightText: 2024 Arthur Schiwon <blizzz@arthur-schiwon.de>
+# SPDX-License-Identifier: MIT
+
+name: OpenAPI
+
+on: pull_request
+
+permissions:
+  contents: read
+
+concurrency:
+  group: openapi-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  openapi:
+    runs-on: ubuntu-latest
+
+    if: ${{ github.repository_owner != 'nextcloud-gmbh' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+
+      - name: Get php version
+        id: php_versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+
+      - name: Set up php
+        uses: shivammathur/setup-php@c541c155eee45413f5b09a52248675b1a2575231 # v2.31.1
+        with:
+          php-version: ${{ steps.php_versions.outputs.php-available }}
+          extensions: xml
+          coverage: none
+          ini-file: development
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check Typescript OpenApi types
+        id: check_typescript_openapi
+        uses: andstor/file-existence-action@076e0072799f4942c8bc574a82233e1e4d13e9d6 # v3.0.0
+        with:
+          files: "src/types/openapi/openapi*.ts"
+
+      - name: Read package.json node and npm engines version
+        if: steps.check_typescript_openapi.outputs.files_exists == 'true'
+        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
+        id: node_versions
+        # Continue if no package.json
+        continue-on-error: true
+        with:
+          fallbackNode: '^20'
+          fallbackNpm: '^10'
+
+      - name: Set up node ${{ steps.node_versions.outputs.nodeVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+        with:
+          node-version: ${{ steps.node_versions.outputs.nodeVersion }}
+
+      - name: Set up npm ${{ steps.node_versions.outputs.npmVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        run: npm i -g 'npm@${{ steps.node_versions.outputs.npmVersion }}'
+
+      - name: Install dependencies & build
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        env:
+          CYPRESS_INSTALL_BINARY: 0
+          PUPPETEER_SKIP_DOWNLOAD: true
+        run: |
+          npm ci
+
+      - name: Set up dependencies
+        run: composer i
+
+      - name: Regenerate OpenAPI
+        run: composer run openapi
+
+      - name: Check openapi*.json and typescript changes
+        run: |
+          bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please run \"composer run openapi\" and commit the openapi*.json files and (if applicable) src/types/openapi/openapi*.ts, see the section \"Show changes on failure\" for details' && exit 1)"
+
+      - name: Show changes on failure
+        if: failure()
+        run: |
+          git status
+          git --no-pager diff
+          exit 1 # make it red to grab attention

.gitignore

@@ -8,6 +8,7 @@ node_modules/
 
 # phpunit
 .phpunit.result.cache
+tests/.phpunit.cache
 clover.unit.xml
 
 # PhpStorm

REUSE.toml

@@ -11,6 +11,12 @@ precedence = "aggregate"
 SPDX-FileCopyrightText = "none"
 SPDX-License-Identifier = "CC0-1.0"
 
+[[annotations]]
+path = ["openapi.json"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2024 Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
 [[annotations]]
 path = ["screenshots/*.png"]
 precedence = "aggregate"

composer.json

@@ -19,12 +19,15 @@
 	},
 	"scripts": {
 		"post-install-cmd": [
-			"@composer bin psalm install --ansi",
-			"@composer bin phpunit install --ansi"
+			"@composer bin all install --ansi"
+		],
+		"post-update-cmd": [
+			"@composer bin all update --ansi"
 		],
 		"cs:fix": "php-cs-fixer fix",
 		"cs:check": "php-cs-fixer fix --dry-run --diff",
 		"lint": "find . -name \\*.php -not -path './vendor/*' -print0 | xargs -0 -n1 php -l",
+		"openapi": "generate-spec --verbose",
 		"test:unit": "phpunit -c tests/phpunit.xml --no-coverage",
 		"test:unit:coverage": "phpunit -c tests/phpunit.xml",
 		"psalm": "psalm --threads=1",

lib/Capabilities.php

@@ -13,21 +13,26 @@
 use OCP\IURLGenerator;
 
 class Capabilities implements ICapability {
-
-	/** @var PasswordPolicyConfig */
-	private $config;
-	/** @var IURLGenerator */
-	private $urlGenerator;
-
-	public function __construct(PasswordPolicyConfig $config, IURLGenerator $urlGenerator) {
-		$this->config = $config;
-		$this->urlGenerator = $urlGenerator;
+	public function __construct(
+		private PasswordPolicyConfig $config,
+		private IURLGenerator $urlGenerator,
+	) {
 	}
 
 	/**
-	 * Function an app uses to return the capabilities
-	 *
-	 * @return array<string, array<string, mixed>> Array containing the apps capabilities
+	 * @return array{
+	 *   password_policy: array{
+	 *     minLength: non-negative-int,
+	 *     enforceNonCommonPassword: bool,
+	 *     enforceNumericCharacters: bool,
+	 *     enforceSpecialCharacters: bool,
+	 *     enforceUpperLowerCase: bool,
+	 *     api: array{
+	 *       generate: string,
+	 *       validate: string,
+	 *     },
+	 *   }
+	 * } Array containing the app's capabilities
 	 * @since 12.0.0
 	 */
 	public function getCapabilities(): array {

lib/Controller/APIController.php

@@ -11,30 +11,31 @@
 use OCA\Password_Policy\Generator;
 use OCA\Password_Policy\PasswordValidator;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\HintException;
 use OCP\IRequest;
 
 class APIController extends OCSController {
-
-	/** @var PasswordValidator */
-	private $validator;
-	/** @var Generator */
-	private $generator;
-
-	public function __construct(string $appName, IRequest $request, PasswordValidator $validator, Generator $generator) {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private PasswordValidator $validator,
+		private Generator $generator,
+	) {
 		parent::__construct($appName, $request);
-		$this->validator = $validator;
-		$this->generator = $generator;
 	}
 
 	/**
-	 * @NoAdminRequired
+	 * Validate a password against the enabled password policy rules
+	 *
+	 * @param string $password The password to validate
+	 * @return DataResponse<Http::STATUS_OK, array{passed: bool, reason?: string}, array{}>
 	 *
-	 * @param string $password
-	 * @return DataResponse
+	 * 200: Always
 	 */
+	#[NoAdminRequired]
 	public function validate(string $password): DataResponse {
 		try {
 			$this->validator->validate($password);
@@ -51,14 +52,18 @@ public function validate(string $password): DataResponse {
 	}
 
 	/**
-	 * @NoAdminRequired
+	 * Generate a random password that validates against the enabled password policy rules
 	 *
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array{password: string}, array{}>|DataResponse<Http::STATUS_CONFLICT, list<empty>, array{}>
+	 *
+	 * 200: Password generated
+	 * 409: Generated password accidentally failed to validate against the rules, retry.
 	 */
+	#[NoAdminRequired]
 	public function generate(): DataResponse {
 		try {
 			$password = $this->generator->generate();
-		} catch (HintException $e) {
+		} catch (HintException) {
 			return new DataResponse([], Http::STATUS_CONFLICT);
 		}
 

lib/PasswordPolicyConfig.php

@@ -32,9 +32,10 @@ public function __construct(
 
 	/**
 	 * get the enforced minimum length of passwords
+	 * @return non-negative-int
 	 */
 	public function getMinLength(): int {
-		return $this->appConfig->getValueInt(Application::APP_ID, 'minLength', 10);
+		return max(0, $this->appConfig->getValueInt(Application::APP_ID, 'minLength', 10));
 	}
 
 	/**