Merge branch 'release/1.4.0'

Author: infeo

.github/workflows/build.yml

@@ -1,6 +1,8 @@
 name: Build
 on:
-  [push]
+  push:
+  pull_request_target:
+    types: [labeled]
 jobs:
   build:
     name: Build and Test
@@ -24,9 +26,9 @@ jobs:
           name: artifacts
           path: target/*.jar
       - name: Create Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         if: startsWith(github.ref, 'refs/tags/')
         with:
           prerelease: true
           token: ${{ secrets.CRYPTOBOT_RELEASE_TOKEN }}
-          generate_release_notes: true
+          generate_release_notes: true

.github/workflows/codeql-analysis.yml

@@ -13,7 +13,8 @@ jobs:
   analyse:
     name: Analyse
     runs-on: ubuntu-latest
-    if: "!contains(github.event.head_commit.message, '[ci skip]') && !contains(github.event.head_commit.message, '[skip ci]')"
+    # dependeabot has on push events only read-only access, but codeql requires write access
+    if: ${{ !(github.actor == 'dependabot[bot]' && contains(fromJSON('["push"]'), github.event_name)) }}
     steps:
     - uses: actions/checkout@v4
       with:
@@ -30,4 +31,4 @@ jobs:
     - name: Build
       run: mvn -B compile
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v3

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.cryptomator</groupId>
     <artifactId>integrations-api</artifactId>
-    <version>1.3.1</version>
+    <version>1.4.0</version>
 
     <name>Cryptomator Integrations API</name>
     <description>Defines optional service interfaces that may be used by Cryptomator</description>
@@ -41,7 +41,7 @@
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-api</artifactId>
-			<version>2.0.12</version>
+			<version>2.0.13</version>
 		</dependency>
 
 		<dependency>
@@ -53,19 +53,19 @@
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-simple</artifactId>
-			<version>2.0.12</version>
+			<version>2.0.13</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>org.junit.jupiter</groupId>
 			<artifactId>junit-jupiter</artifactId>
-			<version>5.10.2</version>
+			<version>5.10.3</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>org.mockito</groupId>
 			<artifactId>mockito-core</artifactId>
-			<version>5.10.0</version>
+			<version>5.12.0</version>
 			<scope>test</scope>
 		</dependency>
 	</dependencies>
@@ -75,14 +75,14 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.12.1</version>
+                <version>3.13.0</version>
                 <configuration>
                     <release>17</release>
                 </configuration>
             </plugin>
             <plugin>
                 <artifactId>maven-source-plugin</artifactId>
-                <version>3.3.0</version>
+                <version>3.3.1</version>
                 <executions>
                     <execution>
                         <id>attach-sources</id>
@@ -95,11 +95,11 @@
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-surefire-plugin</artifactId>
-				<version>3.2.5</version>
+				<version>3.3.1</version>
 			</plugin>
             <plugin>
                 <artifactId>maven-javadoc-plugin</artifactId>
-                <version>3.6.3</version>
+                <version>3.8.0</version>
                 <executions>
                     <execution>
                         <id>attach-javadocs</id>
@@ -148,7 +148,7 @@
 				<plugins>
 					<plugin>
 						<artifactId>maven-gpg-plugin</artifactId>
-						<version>3.1.0</version>
+						<version>3.2.4</version>
 						<executions>
 							<execution>
 								<id>sign-artifacts</id>
@@ -183,7 +183,7 @@
 					<plugin>
 						<groupId>org.sonatype.plugins</groupId>
 						<artifactId>nexus-staging-maven-plugin</artifactId>
-						<version>1.6.13</version>
+						<version>1.7.0</version>
 						<extensions>true</extensions>
 						<configuration>
 							<serverId>ossrh</serverId>

src/main/java/module-info.java

@@ -1,3 +1,4 @@
+import org.cryptomator.integrations.quickaccess.QuickAccessService;
 import org.cryptomator.integrations.mount.MountService;
 import org.cryptomator.integrations.revealpath.RevealPathService;
 import org.cryptomator.integrations.tray.TrayMenuController;
@@ -18,6 +19,7 @@
 	exports org.cryptomator.integrations.revealpath;
 	exports org.cryptomator.integrations.tray;
 	exports org.cryptomator.integrations.uiappearance;
+	exports org.cryptomator.integrations.quickaccess;
 
 	uses AutoStartProvider;
 	uses KeychainAccessProvider;
@@ -26,4 +28,5 @@
 	uses TrayIntegrationProvider;
 	uses TrayMenuController;
 	uses UiAppearanceProvider;
+	uses QuickAccessService;
 }

src/main/java/org/cryptomator/integrations/common/DisplayName.java

@@ -0,0 +1,25 @@
+package org.cryptomator.integrations.common;
+
+import org.jetbrains.annotations.ApiStatus;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A humanreadable name of the annotated class.
+ * <p>
+ * Checked in the default implementation of the {@link NamedServiceProvider#getName()} with lower priority.
+ *
+ * @see NamedServiceProvider
+ * @see LocalizedDisplayName
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@ApiStatus.Experimental
+public @interface DisplayName {
+	String value();
+}

src/main/java/org/cryptomator/integrations/common/LocalizedDisplayName.java

@@ -0,0 +1,39 @@
+package org.cryptomator.integrations.common;
+
+import org.jetbrains.annotations.ApiStatus;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A humanreadable, localized name of the annotated class.
+ * <p>
+ * Checked in the default implementation of the {@link NamedServiceProvider#getName()} with highest priority.
+ *
+ * @see NamedServiceProvider
+ * @see DisplayName
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@ApiStatus.Experimental
+public @interface LocalizedDisplayName {
+
+	/**
+	 * Name of the localization bundle, where the display name is loaded from.
+	 *
+	 * @return Name of the localization bundle
+	 */
+	String bundle();
+
+	/**
+	 * The localization key containing the display name.
+	 *
+	 * @return Localization key to use
+	 */
+	String key();
+
+}

src/main/java/org/cryptomator/integrations/common/NamedServiceProvider.java

@@ -0,0 +1,41 @@
+package org.cryptomator.integrations.common;
+
+import org.slf4j.LoggerFactory;
+
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+/**
+ * A service provider with a human-readable, possibly localized name.
+ */
+public interface NamedServiceProvider {
+
+	/**
+	 * Get the name of this service provider.
+	 *
+	 * @return The name of the service provider
+	 * @implNote The default implementation looks first for a {@link LocalizedDisplayName} and loads the name from the specified resource bundle/key. If the annotation is not present or loading the resource throws an exception, the code looks for {@link DisplayName} and uses its value. If none of the former annotations are present, it falls back to the qualified class name.
+	 * @see DisplayName
+	 * @see LocalizedDisplayName
+	 */
+	default String getName() {
+		var localizedDisplayName = this.getClass().getAnnotation(LocalizedDisplayName.class);
+		if (localizedDisplayName != null) {
+			try {
+				return ResourceBundle.getBundle(localizedDisplayName.bundle()) //
+						.getString(localizedDisplayName.key());
+			} catch (MissingResourceException e) {
+				var clazz = this.getClass();
+				var logger = LoggerFactory.getLogger(clazz);
+				logger.warn("Failed to load localized display name for {}. Falling back to not-localized display name/class name.", clazz.getName(), e);
+			}
+		}
+
+		var displayName = this.getClass().getAnnotation(DisplayName.class);
+		if (displayName != null) {
+			return displayName.value();
+		} else {
+			return this.getClass().getName();
+		}
+	}
+}

src/main/java/org/cryptomator/integrations/keychain/KeychainAccessProvider.java

@@ -56,7 +56,24 @@ default void storePassphrase(String key, CharSequence passphrase) throws Keychai
 	 * @throws KeychainAccessException If storing the password failed
 	 */
 	@Blocking
-	void storePassphrase(String key, @Nullable String displayName, CharSequence passphrase) throws KeychainAccessException;
+	default void storePassphrase(String key, @Nullable String displayName, CharSequence passphrase) throws KeychainAccessException {
+		storePassphrase(key, displayName, passphrase, false);
+	}
+
+	/**
+	 * Associates a passphrase with a given key and a name for that key.
+	 *
+	 * @param key         Key used to retrieve the passphrase via {@link #loadPassphrase(String)}.
+	 * @param displayName The according name to the key. That's the name of the vault displayed in the UI.
+	 *                    It's passed to the keychain as an additional information about the vault besides the key.
+	 *                    The parameter does not need to be unique or be checked by the keychain.
+	 * @param passphrase  The secret to store in this keychain.
+	 * @param requireOsAuthentication Defines, whether the user needs to authenticate to store a passphrase.
+	 *                                The authentication mechanism is provided by the operating system dependent
+	 *                                implementations of this API.
+	 * @throws KeychainAccessException If storing the password failed
+	 */
+	void storePassphrase(String key, @Nullable String displayName, CharSequence passphrase, boolean requireOsAuthentication) throws KeychainAccessException;
 
 	/**
 	 * @param key Unique key previously used while {@link #storePassphrase(String, String, CharSequence)}  storing a passphrase}.

src/main/java/org/cryptomator/integrations/quickaccess/QuickAccessService.java

@@ -0,0 +1,56 @@
+package org.cryptomator.integrations.quickaccess;
+
+import org.cryptomator.integrations.common.IntegrationsLoader;
+import org.cryptomator.integrations.common.NamedServiceProvider;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NotNull;
+
+import java.nio.file.Path;
+import java.util.stream.Stream;
+
+/**
+ * Service adding a system path link to a quick access area of the OS or an application (e.g. file manager).
+ *
+ * @apiNote On purpose this service does not define, what an "link to a quick access area" is. The defintion depends on the OS. For example, the quick access area can be the home screen/desktop and the link would be an icon leading to the linked path.
+ */
+@FunctionalInterface
+public interface QuickAccessService extends NamedServiceProvider {
+
+	/**
+	 * Creates an entry in the quick access area.
+	 *
+	 * @param target      The filesystem path the quick access entry points to
+	 * @param displayName The display name of the quick access entry
+	 * @return a {@link QuickAccessEntry }, used to remove the entry again
+	 * @throws QuickAccessServiceException if adding an entry to the quick access area fails
+	 * @apiNote It depends on the service implementation wether the display name is used or not.
+	 */
+	@Blocking
+	QuickAccessEntry add(@NotNull Path target, @NotNull String displayName) throws QuickAccessServiceException;
+
+	/**
+	 * An entry of the quick access area, created by a service implementation.
+	 */
+	@FunctionalInterface
+	interface QuickAccessEntry {
+
+		/**
+		 * Removes this entry from the quick access area.
+		 *
+		 * @throws QuickAccessServiceException if removal fails.
+		 * @implSpec Service implementations should make this function <em>idempotent</em>, i.e. after the method is called once and succeeded, consecutive calls should not change anything or throw an error.
+		 */
+		@Blocking
+		void remove() throws QuickAccessServiceException;
+
+	}
+
+	/**
+	 * Loads all supported service providers.
+	 *
+	 * @return Stream of supported {@link QuickAccessService} implementations (may be empty)
+	 */
+	static Stream<QuickAccessService> get() {
+		return IntegrationsLoader.loadAll(QuickAccessService.class);
+	}
+}

src/main/java/org/cryptomator/integrations/quickaccess/QuickAccessServiceException.java

@@ -0,0 +1,12 @@
+package org.cryptomator.integrations.quickaccess;
+
+public class QuickAccessServiceException extends Exception {
+
+	public QuickAccessServiceException(String message) {
+		super(message);
+	}
+
+	public QuickAccessServiceException(String message, Throwable t) {
+		super(message, t);
+	}
+}