[643] Add interface and models for synchronizing ACL policies

xtable-api/src/main/java/org/apache/xtable/conversion/ExternalCatalogConfig.java

@@ -58,6 +58,13 @@ public class ExternalCatalogConfig {
    */
   String catalogConversionSourceImpl;
 
+  /**
+   * (Optional) A fully qualified class name that implements the interface for {@link
+   * org.apache.xtable.spi.sync.CatalogAccessControlPolicySyncClient} it can be used if the
+   * implementation for catalogType doesn't exist in XTable.
+   */
+  String catalogPolicySyncClientImpl;
+
   /**
    * The properties for this catalog, used for providing any custom behaviour during catalog sync
    */

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalAccessControlPolicySnapshot.java

@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+import java.time.Instant;
+import java.util.Collections;
+import java.util.Map;
+
+import lombok.Builder;
+import lombok.Value;
+
+/** A snapshot of all access control data at a given point in time. */
+@Value
+@Builder
+public class InternalAccessControlPolicySnapshot {
+  /**
+   * A unique identifier representing this snapshot's version.
+   *
+   * <p>This could be a UUID, timestamp string, or any value that guarantees uniqueness across
+   * snapshots.
+   */
+  String versionId;
+
+  /**
+   * The moment in time when this snapshot was created.
+   *
+   * <p>Useful for maintaining an audit trail or comparing how policies have changed over time.
+   */
+  Instant timestamp;
+
+  /**
+   * A map of user names to {@link InternalUser} objects, capturing individual users' details such
+   * as assigned roles, auditing metadata, etc.
+   */
+  @Builder.Default Map<String, InternalUser> usersByName = Collections.emptyMap();
+
+  /**
+   * A map of group names to {@link InternalUserGroup} objects, representing logical groupings of
+   * users for easier role management.
+   */
+  @Builder.Default Map<String, InternalUserGroup> groupsByName = Collections.emptyMap();
+
+  /**
+   * A map of role names to {@link InternalRole} objects, defining the privileges and security rules
+   * each role entails.
+   */
+  @Builder.Default Map<String, InternalRole> rolesByName = Collections.emptyMap();
+
+  /**
+   * A map of additional properties or metadata related to this snapshot. This map provides
+   * flexibility for storing information without modifying the main schema of the snapshot.
+   */
+  @Builder.Default Map<String, String> properties = Collections.emptyMap();
+}

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalChangeLogInfo.java

@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+import java.time.Instant;
+
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Contains change-log information for roles, users, or user groups, enabling traceability of who
+ * created or last modified them.
+ *
+ * <p>This class is useful for governance and compliance scenarios, where an audit trail is
+ * necessary. It can be extended to include additional fields such as reasonForChange or
+ * changeDescription.
+ */
+@Value
+@Builder
+public class InternalChangeLogInfo {
+  /** The username or identifier of the entity that created this record. */
+  String createdBy;
+
+  /** The username or identifier of the entity that last modified this record. */
+  String lastModifiedBy;
+
+  /** The timestamp when this record was created. */
+  Instant createdAt;
+
+  /** The timestamp when this record was last modified. */
+  Instant lastModifiedAt;
+}

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalPrivilege.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Represents a single privilege assignment for a securable object.
+ *
+ * <p>This defines the kind of operation (e.g., SELECT, CREATE, MODIFY) and whether it is allowed or
+ * denied. Some catalogs may only accept ALLOW rules and treat all other operations as denied by
+ * default.
+ */
+@Value
+@Builder
+public class InternalPrivilege {
+  /**
+   * The type of privilege, such as SELECT, CREATE, or MODIFY. Each implementation can define its
+   * own set of enums.
+   */
+  InternalPrivilegeType privilegeType;
+
+  /**
+   * The decision, typically ALLOW or DENY. Some catalogs may not support DENY explicitly,
+   * defaulting to ALLOW.
+   */
+  String privilegeDecision;
+}

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalPrivilegeType.java

@@ -0,0 +1,71 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+/**
+ * Specifies a set of privileges that can be granted or revoked for securable objects.
+ *
+ * <p>This enum is used to indicate the type of actions that a subject (user, role, group) is
+ * allowed to perform on a given resource, such as a catalog, database, table, or other securable
+ * entity.
+ */
+public enum InternalPrivilegeType {
+
+  /** Grants all available privileges on the resource. */
+  ALL,
+
+  /**
+   * Allows modification of the structure or metadata of the resource. For example, modifying
+   * schemas or properties.
+   */
+  ALTER,
+
+  /**
+   * Allows describing or viewing the metadata of the resource. Typically applies to viewing schemas
+   * or properties of the resource.
+   */
+  DESCRIBE,
+
+  /**
+   * Allows reading or selecting data from the resource. Commonly associated with performing SQL
+   * SELECT statements.
+   */
+  SELECT,
+
+  /**
+   * Allows inserting new data into the resource. Typically granted for operations like SQL INSERT
+   * statements.
+   */
+  INSERT,
+
+  /**
+   * Allows updating existing data within the resource. Typically granted for operations like SQL
+   * UPDATE statements.
+   */
+  UPDATE,
+
+  /** Allows creating new resources within the catalog. */
+  CREATE,
+
+  /** Allows deleting or dropping a resource, such as a database or a table. */
+  DROP,
+
+  /** Allows removing data from the resource, for example using SQL DELETE statements. */
+  DELETE
+}

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalRole.java

@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+import java.util.List;
+import java.util.Map;
+
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Represents a role within the catalog.
+ *
+ * <p>A role can be granted access to multiple securable objects, each with its own set of
+ * privileges. Audit info is stored to track the role's creation and modifications, and a properties
+ * map can hold additional metadata.
+ */
+@Value
+@Builder
+public class InternalRole {
+  /** The unique name or identifier for the role. */
+  String name;
+
+  /** The list of securable objects this role can access. */
+  List<InternalSecurableObject> securableObjects;
+
+  /** Contains information about how and when this role was created and last modified. */
+  InternalChangeLogInfo changeLogInfo;
+
+  /**
+   * A map to store additional metadata or properties related to this role. For example, this might
+   * include a description, usage instructions, or any catalog-specific fields.
+   */
+  Map<String, String> properties;
+}

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalSecurableObject.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+import java.util.List;
+
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Represents a securable object in the catalog, which can be managed by access control.
+ *
+ * <p>Examples of securable objects include catalogs, schemas, tables, views, or any other data
+ * objects that require fine-grained privilege management. Each securable object can have one or
+ * more privileges assigned to it.
+ */
+@Value
+@Builder
+public class InternalSecurableObject {
+  /** The identifier of the securable object. */
+  InternalSecurableObjectIdentifier securableObjectIdentifier;
+  /**
+   * The type of securable object, such as TABLE, VIEW, FUNCTION, etc. Each implementation can
+   * define its own set of enums.
+   */
+  InternalSecurableObjectType securableObjectType;
+  /** The set of privileges assigned to this object. */
+  List<InternalPrivilege> privileges;
+}

xtable-api/src/main/java/org/apache/xtable/model/catalog/policy/InternalSecurableObjectIdentifier.java

@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.xtable.model.catalog.policy;
+
+/**
+ * Defines a structure for obtaining a unique, canonical identifier for a securable object within
+ * the catalog.
+ *
+ * <p>Implementations of this interface may represent entities such as catalogs, databases, tables,
+ * or any other resource that can be protected or controlled via security policies.
+ */
+public interface InternalSecurableObjectIdentifier {
+
+  /**
+   * Returns the unique identifier of the securable object in a canonical form.
+   *
+   * @return a non-null {@link String} representing the unique identifier of this securable object
+   */
+  String getId();
+}