Updates doc for spi and re-organizes a class

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Author: DarshitChanpura

build.gradle

@@ -645,6 +645,7 @@ tasks.integrationTest.finalizedBy(jacocoTestReport) // report is always generate
 check.dependsOn integrationTest
 
 dependencies {
+    compileOnly project(path: ":opensearch-resource-sharing-spi", configuration: 'shadow')
     implementation project(path: ":${rootProject.name}-common", configuration: 'shadow')
     implementation "org.opensearch.plugin:transport-netty4-client:${opensearch_version}"
     implementation "org.opensearch.client:opensearch-rest-high-level-client:${opensearch_version}"

common/src/main/java/org/opensearch/security/common/resources/ResourceAccessHandler.java

@@ -173,7 +173,7 @@ public <T extends Resource> void getAccessibleResourcesForCurrentUser(String res
         try {
             validateArguments(resourceIndex);
 
-            ResourceParser<T> parser = ResourcePluginInfo.getInstance().getResourceProviders().get(resourceIndex).getResourceParser();
+            ResourceParser<T> parser = ResourcePluginInfo.getInstance().getResourceProviders().get(resourceIndex).resourceParser();
 
             StepListener<Set<String>> resourceIdsListener = new StepListener<>();
             StepListener<Set<T>> resourcesListener = new StepListener<>();
@@ -366,55 +366,6 @@ public void revokeAccess(
         );
     }
 
-    /**
-     * Checks if the current user has permission to modify a resource.
-     * NOTE: Only admins and owners of the resource can modify the resource.
-     * TODO: update this method to allow for other users to modify the resource.
-     * @param resourceId    The resource ID to check.
-     * @param resourceIndex The resource index containing the resource.
-     * @param listener      The listener to be notified with the permission check result.
-     */
-    public void canModifyResource(String resourceId, String resourceIndex, ActionListener<Boolean> listener) {
-        try {
-            validateArguments(resourceId, resourceIndex);
-
-            final UserSubjectImpl userSubject = (UserSubjectImpl) threadContext.getPersistent(
-                ConfigConstants.OPENDISTRO_SECURITY_AUTHENTICATED_USER
-            );
-            final User user = (userSubject == null) ? null : userSubject.getUser();
-
-            if (user == null) {
-                listener.onFailure(new ResourceSharingException("No authenticated user available."));
-                return;
-            }
-
-            StepListener<ResourceSharing> fetchDocListener = new StepListener<>();
-            resourceSharingIndexHandler.fetchDocumentById(resourceIndex, resourceId, fetchDocListener);
-
-            fetchDocListener.whenComplete(document -> {
-                if (document == null) {
-                    LOGGER.info("Document {} does not exist in index {}", resourceId, resourceIndex);
-                    // Either the document was deleted or has not been created yet. No permission check is needed for this.
-                    listener.onResponse(true);
-                    return;
-                }
-
-                boolean isAdmin = adminDNs.isAdmin(user);
-                boolean isOwner = isOwnerOfResource(document, user.getName());
-
-                if (!isAdmin && !isOwner) {
-                    LOGGER.info("User {} does not have access to delete the record {}", user.getName(), resourceId);
-                    listener.onResponse(false);
-                } else {
-                    listener.onResponse(true);
-                }
-            }, listener::onFailure);
-        } catch (Exception e) {
-            LOGGER.error("Failed to check delete permission for resource {}", resourceId, e);
-            listener.onFailure(e);
-        }
-    }
-
     /**
      * Deletes a resource sharing record by its ID and the resource index it belongs to.
      *

common/src/main/java/org/opensearch/security/common/resources/ResourcePluginInfo.java

@@ -8,8 +8,6 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 
-import org.opensearch.security.spi.resources.ResourceProvider;
-
 /**
  * This class provides information about resource plugins and their associated resource providers and indices.
  * It follows the Singleton pattern to ensure that only one instance of the class exists.

common/src/main/java/org/opensearch/security/common/resources/ResourceProvider.java

@@ -0,0 +1,19 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.security.common.resources;
+
+import org.opensearch.security.spi.resources.ResourceParser;
+
+/**
+ * This record class represents a resource provider.
+ * It holds information about the resource type, resource index name, and a resource parser.
+ */
+public record ResourceProvider(String resourceType, String resourceIndexName, ResourceParser resourceParser) {
+
+}

sample-resource-plugin/src/integrationTest/java/org/opensearch/sample/AbstractSampleResourcePluginFeatureEnabledTests.java

@@ -14,8 +14,8 @@
 import org.junit.Test;
 
 import org.opensearch.security.common.resources.ResourcePluginInfo;
+import org.opensearch.security.common.resources.ResourceProvider;
 import org.opensearch.security.spi.resources.ResourceAccessScope;
-import org.opensearch.security.spi.resources.ResourceProvider;
 import org.opensearch.test.framework.cluster.LocalCluster;
 import org.opensearch.test.framework.cluster.TestRestClient;
 

sample-resource-plugin/src/integrationTest/java/org/opensearch/sample/SampleResourcePluginSystemIndexDisabledTests.java

@@ -14,7 +14,7 @@
 
 import org.opensearch.painless.PainlessModulePlugin;
 import org.opensearch.security.common.resources.ResourcePluginInfo;
-import org.opensearch.security.spi.resources.ResourceProvider;
+import org.opensearch.security.common.resources.ResourceProvider;
 import org.opensearch.test.framework.cluster.ClusterManager;
 import org.opensearch.test.framework.cluster.LocalCluster;
 import org.opensearch.test.framework.cluster.TestRestClient;

sample-resource-plugin/src/integrationTest/java/org/opensearch/sample/SampleResourcePluginTests.java

@@ -16,7 +16,7 @@
 
 import org.opensearch.painless.PainlessModulePlugin;
 import org.opensearch.security.common.resources.ResourcePluginInfo;
-import org.opensearch.security.spi.resources.ResourceProvider;
+import org.opensearch.security.common.resources.ResourceProvider;
 import org.opensearch.test.framework.cluster.ClusterManager;
 import org.opensearch.test.framework.cluster.LocalCluster;
 import org.opensearch.test.framework.cluster.TestRestClient;

spi/README.md

@@ -2,6 +2,12 @@
 
 This SPI provides interfaces to implement Resource Sharing and Access Control.
 
+
+## Usage
+
+A plugin defining a resource and aiming to implement access control over that resource must extend ResourceSharingExtension class to register itself
+
+
 ## License
 
 This code is licensed under the Apache 2.0 License.

spi/src/main/java/org/opensearch/security/spi/resources/Resource.java

@@ -17,7 +17,7 @@
 public interface Resource extends NamedWriteable, ToXContentFragment {
     /**
      * Abstract method to get the resource name.
-     * Must be implemented by subclasses.
+     * Must be implemented by plugins defining resources.
      *
      * @return resource name
      */

spi/src/main/java/org/opensearch/security/spi/resources/ResourceAccessScope.java

@@ -11,7 +11,7 @@
 import java.util.Arrays;
 
 /**
- * This interface defines the two basic access scopes for resource-access.
+ * This interface defines the two basic access scopes for resource-access. Plugins can decide whether to use these.
  * Each plugin must implement their own scopes and manage them.
  * These access scopes will then be used to verify the type of access being requested.
  *

spi/src/main/java/org/opensearch/security/spi/resources/ResourceProvider.java

@@ -9,23 +9,27 @@
 package org.opensearch.security.spi.resources;
 
 /**
- * This interface should be implemented by all the plugins that define one or more resources.
+ * This interface should be implemented by all the plugins that define one or more resources and need access control over those resources.
  *
  * @opensearch.experimental
  */
 public interface ResourceSharingExtension {
 
     /**
      * Type of the resource
-     * @return a string containing the type of the resource
+     * @return a string containing the type of the resource. A qualified class name can be supplied here.
      */
     String getResourceType();
 
     /**
-     * The index where resource meta-data is stored
-     * @return the name of the parent index where resource meta-data is stored
+     * The index where resource is stored
+     * @return the name of the parent index where resource is stored
      */
     String getResourceIndex();
 
+    /**
+     * The parser for the resource, which will be used by security plugin to parse the resource
+     * @return the parser for the resource
+     */
     ResourceParser<? extends Resource> getResourceParser();
 }

spi/src/main/java/org/opensearch/security/spi/resources/ResourceSharingExtension.java

@@ -7,8 +7,9 @@
  */
 
 /**
- * This package defines class required to implement resource access control in OpenSearch.
+ * This package defines classes required to implement resource access control in OpenSearch.
+ * This package will be added as a dependency by all OpenSearch plugins that require resource access control.
  *
  * @opensearch.experimental
  */
-package main.java.org.opensearch.security.spi.resources;
+package org.opensearch.security.spi.resources;

spi/src/main/java/org/opensearch/security/spi/resources/package-info.java

@@ -19,7 +19,6 @@
 
 /**
  * This class is used to store information about the creator of a resource.
- * Concrete implementation will be provided by security plugin
  *
  * @opensearch.experimental
  */

spi/src/main/java/org/opensearch/security/spi/resources/sharing/CreatedBy.java

@@ -8,6 +8,11 @@
 
 package org.opensearch.security.spi.resources.sharing;
 
+/**
+ * This enum is used to store information about the creator of a resource.
+ *
+ * @opensearch.experimental
+ */
 public enum Creator {
     USER("user");
 

spi/src/main/java/org/opensearch/security/spi/resources/sharing/Creator.java

@@ -8,6 +8,10 @@
 
 package org.opensearch.security.spi.resources.sharing;
 
+/**
+ * Enum representing the recipients of a shared resource.
+ * It includes USERS, ROLES, and BACKEND_ROLES.
+ */
 public enum Recipient {
     USERS("users"),
     ROLES("roles"),

spi/src/main/java/org/opensearch/security/spi/resources/sharing/Recipient.java

@@ -13,8 +13,9 @@
 
 /**
  * This class determines a collection of recipient types a resource can be shared with.
+ * Allows addition of other recipient types in the future.
  *
- * @opensearch.experimental
+ *  @opensearch.experimental
  */
 public final class RecipientTypeRegistry {
     // TODO: Check what size should this be. A cap should be added to avoid infinite addition of objects

spi/src/main/java/org/opensearch/security/spi/resources/sharing/RecipientTypeRegistry.java

@@ -20,10 +20,6 @@
 /**
  * Represents a resource sharing configuration that manages access control for OpenSearch resources.
  * This class holds information about shared resources including their source, creator, and sharing permissions.
- *
- * <p>This class implements {@link ToXContentFragment} for JSON serialization and {@link NamedWriteable}
- * for stream-based serialization.</p>
- * <p>
  * The class maintains information about:
  * <ul>
  *   <li>The source index where the resource is defined</li>

spi/src/main/java/org/opensearch/security/spi/resources/sharing/ResourceSharing.java

@@ -22,7 +22,7 @@
 import org.opensearch.core.xcontent.XContentParser;
 
 /**
- * This class represents the scope at which a resource is shared with.
+ * This class represents the scope at which a resource is shared with for a particular scope.
  * Example:
  * "read_only": {
  * "users": [],

spi/src/main/java/org/opensearch/security/spi/resources/sharing/SharedWithScope.java

@@ -147,6 +147,7 @@
 import org.opensearch.security.common.resources.ResourceAccessHandler;
 import org.opensearch.security.common.resources.ResourceIndexListener;
 import org.opensearch.security.common.resources.ResourcePluginInfo;
+import org.opensearch.security.common.resources.ResourceProvider;
 import org.opensearch.security.common.resources.ResourceSharingConstants;
 import org.opensearch.security.common.resources.ResourceSharingIndexHandler;
 import org.opensearch.security.common.resources.ResourceSharingIndexManagementRepository;
@@ -195,7 +196,6 @@
 import org.opensearch.security.setting.TransportPassiveAuthSetting;
 import org.opensearch.security.spi.resources.Resource;
 import org.opensearch.security.spi.resources.ResourceParser;
-import org.opensearch.security.spi.resources.ResourceProvider;
 import org.opensearch.security.spi.resources.ResourceSharingExtension;
 import org.opensearch.security.ssl.ExternalSecurityKeyStore;
 import org.opensearch.security.ssl.OpenSearchSecureSettingsFactory;