feat(Reference): Add public API endpoints to get references

Calling the public API endpoints will check for matching registered
reference providers that implement `IPublicReferenceProvider` and call
their respective functions. If no matching provider is found, the
default `LinkReferenceProvider` will be used to provide open graph data.

The frontend reference widget components will call these endpoints from
unauthorized sessions, e.g. in public shares.

If present, the sharing token of the origin URL is passed to
`resolveReferencePublic()` as additional information for the reference
provider to determine the access scope. This allows the respective
reference providers to determine whether the origin share has access to
the linked resource.

`getCacheKeyPublic` also gets the sharing token so it can scope the cached
entry to it.

Contributes to #45978

Signed-off-by: Jonas <jonas@freesources.org>

3 files changed, 54 insertions, 3 deletions

diff --git a/lib/public/Collaboration/Reference/IPublicReferenceProvider.php b/lib/public/Collaboration/Reference/IPublicReferenceProvider.php
new file mode 100644
index 00000000000..db6c3d3828b
--- /dev/null
+++ b/lib/public/Collaboration/Reference/IPublicReferenceProvider.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Collaboration\Reference;
+
+/**
+ * @since 30.0.0
+ */
+interface IPublicReferenceProvider extends IReferenceProvider {
+	/**
+	 * Return a reference with its metadata for a given reference identifier and sharingToken
+	 *
+	 * @since 30.0.0
+	 */
+	public function resolveReferencePublic(string $referenceText, string $sharingToken): ?IReference;
+
+	/**
+	 * Return a custom cache key to be used for caching the metadata
+	 * This could be for example the current sharingToken if the reference
+	 * access permissions are different for each share
+	 *
+	 * Should return null, if the cache is only related to the
+	 * reference id and has no further dependency
+	 *
+	 * @since 30.0.0
+	 */
+	public function getCacheKeyPublic(string $referenceId, string $sharingToken): ?string;
+}
diff --git a/lib/public/Collaboration/Reference/IReferenceManager.php b/lib/public/Collaboration/Reference/IReferenceManager.php
index 4a7de266435..c3cf7ca8e7b 100644
--- a/lib/public/Collaboration/Reference/IReferenceManager.php
+++ b/lib/public/Collaboration/Reference/IReferenceManager.php
@@ -27,8 +27,9 @@ interface IReferenceManager {
 	 * but may still return null in case this is disabled or the fetching fails
 	 *
 	 * @since 25.0.0
+	 * @since 30.0.0 optional arguments `$public` and `$sharingToken`
 	 */
-	public function resolveReference(string $referenceId): ?IReference;
+	public function resolveReference(string $referenceId, bool $public = false, string $sharingToken = ''): ?IReference;
 
 	/**
 	 * Get a reference by its cache key
@@ -42,8 +43,9 @@ interface IReferenceManager {
 	 * the cache can then be filled with a separate request from the frontend
 	 *
 	 * @since 25.0.0
+	 * @since 30.0.0 optional arguments `$public` and `$sharingToken`
 	 */
-	public function getReferenceFromCache(string $referenceId): ?IReference;
+	public function getReferenceFromCache(string $referenceId, bool $public = false, string $sharingToken = ''): ?IReference;
 
 	/**
 	 * Invalidate all cache entries with a prefix or just one if the cache key is provided
diff --git a/lib/public/Collaboration/Reference/LinkReferenceProvider.php b/lib/public/Collaboration/Reference/LinkReferenceProvider.php
index 79b5164950c..a7f54d02c04 100644
--- a/lib/public/Collaboration/Reference/LinkReferenceProvider.php
+++ b/lib/public/Collaboration/Reference/LinkReferenceProvider.php
@@ -26,7 +26,7 @@ use Psr\Log\LoggerInterface;
 /**
  * @since 29.0.0
  */
-class LinkReferenceProvider implements IReferenceProvider {
+class LinkReferenceProvider implements IReferenceProvider, IPublicReferenceProvider {
 
 	/**
 	 * for image size and webpage header
@@ -88,6 +88,14 @@ class LinkReferenceProvider implements IReferenceProvider {
 	}
 
 	/**
+	 * @inheritDoc
+	 * @since 30.0.0
+	 */
+	public function resolveReferencePublic(string $referenceText, string $sharingToken): ?IReference {
+		return $this->resolveReference($referenceText);
+	}
+
+	/**
 	 * Populates the reference with OpenGraph data
 	 *
 	 * @param Reference $reference
@@ -201,4 +209,12 @@ class LinkReferenceProvider implements IReferenceProvider {
 	public function getCacheKey(string $referenceId): ?string {
 		return null;
 	}
+
+	/**
+	 * @inheritDoc
+	 * @since 30.0.0
+	 */
+	public function getCacheKeyPublic(string $referenceId, string $sharingToken): ?string {
+		return null;
+	}
 }