VCSSL/VNANO PLUGIN INTERFACE SPECIFICATION

# Permission Authorizer Connector Interface 1 (PACI1)
Specification Document
(org.vcssl.connect.PermissionAuthorizerConnectorInterface1)

## Abstract

Permission Authorizer Connector Interface 1 (PACI1) is an interface for implementing permission-based security plug-ins.

PACI 1 plug-ins receive requests of permissions from other plug-ins (through script engines), and determine whether allow or deny it (or ask to the user to determine it, if necessary).

What form of UI is suitable for the above determination highly depends on the application's UI, purpose, and so on. Hence, the application-side can design UI for the above determination, and can connect (and use) it to script engines, by implementing this interface.

On PACI 1, following two types of permission settings are assumed to exist:

Base permission settings:
  Settings which is set to applications/script engines explicitly, and applied automatically to each script at the beginning time of its execution.
Temporary permission settings:
  Temporary settings kept only during each script is running, of which values may change by user's responses for requests of permissions.

When the script is executed, at the beginning, values of the base permission settings are copied to the temporary permission settings. During the script is running, values of temporary permission settings are referred (and modified if necessary), when any permission is requested. When the next script is executed, values of the temporary permission settings are re-initialized by copying values of the base permission settings.

The reason of why the temporary permission settings exists is: to avoid repeating the same request to an user. For example, when the base permission for writing files is set to ASK, if the temporary permission does not exist, we should ask the user to determine whether allows it or not, for every time when write a line to a file (we should ask 100 times for writing 100 lines). It must be troublesome, so it is necessary to provide an option such as: "Allow the same request automatically, during the current script is running". In order to implement the above feature, the temporary permission settings exists.

## Status

The status of this interface is "FINALIZED".

The specification of this interface had been finalized at 2022/09/30. No modifications will be applied for this interface, excluding documents/comments.

This interface is currently supported by the scripting engine of Vnano. You can use this interface for development of plug-ins of applications equipped with the Vnano engine.

## License

This interface is published under CC0, which is almost the same as the so-called "copyright-free" (domain).

## List of Fields/Methods

INTERFACE_TYPE_ID
  The type ID of this interface (value: "PACI") referred when the plug-in will be loaded.
INTERFACE_GENERATION
  The generation of this interface (value: "1").
void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase)
  Sets values of permission items, by a Map (permission map) storing names and values of permission items.
Map<String, String> getPermissionMap(boolean getsFromBase)
  Gets the Map (permission map) storing names and current values of permission items.
void requestPermission(String permissionName, Object requester, Object metaInformation)
  Receives the request of the specified permission.
Class<?> getEngineConnectorClass()
  Returns the instance of "Class" class, representing the interface or the class of the engine connector, which is an object for communicating with the scripting engine.
void initializeForConnection(Object engineConnector)
  Performs the initialization process necessary when this plug-in is connected to the scripting engine.
void finalizeForDisconnection(Object engineConnector)
  Performs the finalization process necessary when this plug-in is disconnected from the scripting engine.
void initializeForExecution(Object engineConnector)
  Performs the initialization process necessary for each execution of a script.
void finalizeForTermination(Object engineConnector)
  Performs the finalization process necessary for each execution of a script.

## Fields

Name | INTERFACE_TYPE_ID
--- | ---
Value | The type ID of this interface (value: "PACI") referred when the plug-in will be loaded.
Type | static final String

Name | INTERFACE_GENERATION
--- | ---
Value | The generation of this interface (value: "1").
Type | static final String

## Methods

Name | setPermissionMap
--- | ---
Signature | void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase) throws ConnectorException
Description | Sets values of permission items, by a Map (permission map) storing names and values of permission items. This method will be called from script engines or applications.
Parameters | permissionMap: The Map (permission map) storing names and values of permission items. setsToBase: Specify "true" to set base permission settings, "false" to set temporary permission settings.
Return | None
Exception | ConnectorException: Thrown when invalid permission settings are detected. Also, thrown when "false" is specified to "setsToBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | getPermissionMap
--- | ---
Signature | Map<String, String> getPermissionMap(boolean getsFromBase) throws ConnectorException
Description | Gets the Map (permission map) storing names and current values of permission items. This method will be called from script engines or applications.
Parameters | getsFromBase: Specify "true" to get base permission settings, "false" to get temporary permission settings.
Return | The Map (permission map) storing names and values of permission items.
Exception | ConnectorException: Thrown when failed to get the specified permission settings. For example, thrown when "false" is specified to "setsToBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | requestPermission
--- | ---
Signature | void requestPermission(String permissionName, Object requester, Object metaInformation) throws ConnectorException
Description | Receives the request of the specified permission. If the specified permission should be allowed, this method is required to do nothing (explicitly). If the specified permission should be denied, this method throws an ConnectorException. This method will be called from other plug-ins through engine-connector interfaces.
Parameters | permissionName: The name of the requested permission item. requester: The plug-in requesting the permission. metaInformation: The information to be notified to the user (especially when the current value of the permission is set to ASK).
Return | None
Exception | ConnectorException: Thrown when the requested permission has been denied.

Name | getEngineConnectorClass
--- | ---
Signature | Class<?> getEngineConnectorClass()
Description | Returns the instance of "Class" class, representing the interface or the class of the engine connector, which is an object for communicating with the scripting engine. The instance of the specified interface/class by this method will be passed to the argument of initialization/finalization methods, e.g.: initializeForConnection(Object engineConnector). What type of interfaces are available depend on the implementation of the scripting engine, but at least, ECI1 is guaranteed to be available by the specification of PACI1.
Parameters | None
Return | The Class representing the interface/class for communicating with the scripting engine.
Exception | None

Name | initializeForConnection
--- | ---
Signature | void initializeForConnection(Object engineConnector) throws ConnectorException
Description | Performs the initialization process necessary when this plug-in is connected to the scripting engine.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the initialization has failed.

Name | finalizeForDisconnection
--- | ---
Signature | void finalizeForDisconnection(Object engineConnector) throws ConnectorException
Description | Performs the finalization process necessary when this plug-in is disconnected from the scripting engine.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the finalization has failed.

Name | initializeForExecution
--- | ---
Signature | void initializeForExecution(Object engineConnector) throws ConnectorException
Description | Performs the initialization process necessary for each execution of a script.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the initialization has failed.

Name | finalizeForTermination
--- | ---
Signature | void finalizeForTermination(Object engineConnector) throws ConnectorException
Description | Performs the finalization process necessary for each execution of a script.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the finalization has failed.