# Notation plugin management (PRD)

## Background

Notation plugins are add-on tools that can be integrated seamlessly with Notation. They provide a way to extend the core feature set of Notation, but without requiring every new feature to be written in Golang and added to the core code base. Notation also provides plugin interfaces and [standard plugin specification](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/plugin-extensibility.md) for users, and vendors to implement their own integrations with the solutions they use.

Currently, installing a Notation plugin is a prerequisite for signing especially in the production environment. In some cases, verification also relies on an external plugin. There are a few existing Notation plugins as listed in the [Notation plugin document](https://notaryproject.dev/docs/user-guides/how-to/plugin-management/). Users need to manually install the plugins from external sources and put the executable binaries into certain folder of the host file system. Notation CLI has only `notation list` command to view all the installed plugins, but as of Notation 1.0 release it lacks of plugin lifecycle management commands and capabilities.

To streamline the plugin installation process and provide an out-of-box plugin lifecycle management experience, we need to enhance the `notation plugin` command with a phased approach.

This document walks through the common user scenarios and desired user experience of Notation plugin lifecycle management, including plugin installation, uninstall, upgrade, etc.

## Goals/Non-goals

### Goals

- Provide convenient user experience to install, uninstall, and upgrade plugins
- Provide a secure approach to verify authenticity and integrity of plugins before installing them

### Non-goals

- Auto-update a plugin to the latest
- Downgrade a plugin (Can be achieved by uninstall and install an old version)

## User challenges and scenarios

### Scenario #1: Install a plugin from a local environment

Alice's company has strict confidential and security requirements so she can only use Notation with a plugin in an on-premises air-gapped environment. The plugin could be installed from an archive tar file (like `.tar.gz`,`.zip`) in the local file system and requires verification before installing it.

### Scenario #2: Install a plugin from a remote source

Alice wants to use Notation with a plugin developed by a vendor. In general, the plugin is packaged into an archive file like `tar.gz`, `.zip` file format. The plugin archive files can be downloaded from a public shared address (URL) or storage, such as GitHub Release page, OCI registry, object storage, or private address. User wants to easily install the plugin with Notation and upgrade it in case a new plugin version is available.

### Scenario #3: Use a plugin in a containerized Notation

Alice wants to containerize Notation into a Docker image and running Notation CLI in a container. However, it's complicated for her to handle the plugin installation and configure the plugin file location in the host's file system since the plugin needs to be installed in a specific folder but the file location varies per different operating system.

### Scenario #4: Use trusted built-in plugins out of the box

Alice wants to use Notation with multiple plugins from different vendors and automate the signing experience in a pipeline. It is a little cumbersome for her to manually install, configure, and verify a plugin in the pipeline runner machine. This process is also time-wasted when run the plugin installation. It would be much more convenient if there are trusted built-in plugins that can be used for signing process out of the box.

## Phased proposals and desired user experience

### Desired user journey of installing a plugin


### Desired UX for scenario #1: Install a plugin from a local file

To satisfy the user's requirement described in the scenario #1, the plugin installation command is proposed below. Notation is able to install the plugin from a local file path and verify the plugin's checksum.

notation plugin install --file <file_path> --checksum <digest>

> Note:
> - The plugin can be a archive tar file like `.tar.gz`, `.zip`. The `--checksum` flag is mandatory flag for verification purpose. Some plugins may have their recommended verification process like verifying GPG signature. There will be a requirement for plugin vendors that they must publish a checksum digest for plugin release assets.
> - Notation doesn't support installing and using multiple versions of a plugin in the system. If there there is an existing version, Notation will return an error message and will not start installation. Users can use `--force` to skip existence check and force the installation.

## Desired UX for scenario #2: Install a plugin from a remote source

To satisfy the user's requirement described in the scenario #2, there are two plugin installation approaches proposed below.

### Option 1: install plugin from an HTTPS address

notation plugin install https://wabbit-networks.com/intaller/linux/amd64/wabbit-plugin-v1.0.tar.gz --checksum <digest>

This option resolves the needs for downloading and installing the plugin from an HTTPS address.

> Note:
> - The plugin is recommended to be packaged into a compressed file like `.tar.gz`, `.zip`. This is the most secure approach to distribute the plugin installation package.
> - Binary archive files like `.msi`, `.exe`, `.pkg` are not recommended and supported so far.

### Option 2: install plugin as an OCI artifact from a registry

notation plugin install <registry>/<repository>@<digest>

This option borrows the idea from [Docker plugin installation approach](https://docs.docker.com/engine/reference/commandline/plugin_install/). There are three key benefits of this option:

- It provides a conformant standard of building, distributing, and verifying a plugin for plugin vendors. Users no longer need to care about the plugin location configuration.
- Users can also verify the plugin against the image digest and the image signature. Naturally, the plugin is recommended to be signed by Notation so users can use Notation to verify it.
- Plugin vendors will be convenient to package the plugin into different architectures with containerization standard.

If the plugin file is signed by Notation, one of the potential cumbersome steps is that verifying a Notary Project signature of a plugin requires users to configure trust store and trust policy in advance. It increases complexity for the plugin setup process.

## Desired UX for scenario #3: Use trusted built-in plugins

To satisfy the user's requirements described in the scenario #3 and #4, we can define two types of plugins in the Notary Project: "official plugins" and "third-party plugins", and make the "official plugins" as built-in plugins so that users no longer need to manually install them.

"Official plugins" are developed and maintained by Notary Project maintainers in a GitHub repository under the Notary Project organization. In general, "official plugins" are trusted and supported by a certain organization or vendor. Making the "official plugins" as the built-in plugins streamlines the plugin setup and verification that delivers an out-of-box experience for users. Users will be able to sign and verify an artifact with Notation using a built-in plugin.

"Third-party plugins" are developed by any users or vendors. These plugins are maintained outside the Notary Project organization. Users need to follow the suggested two proposals above to install the "third-party plugins" from target sources and verify them.

We need to discuss how to fairly define and decide which plugins can be accepted as "Official plugins" in the Notary Project community.

After installing Notation CLI, users will be able to see and use the built-in plugins out of the box.

$ notation list plugins
NAME                         DESCRIPTION           VERSION          CAPABILITIES
wabbit-networks (built-in)  Sign artifacts          v1.0              Sign
ABC-networks (3rd party)    Verify artifacts        v2.0              Verify

## Uninstall and upgrade a plugin

Users can install a Notation plugin via three different approaches above. Uninstall or upgrade an installed plugin is also a regular operation for Notation plugin users. Uninstall is necessary to be considered for the first iteration since this is a basic operation. Upgrade helps users easily upgrade the plugin to a specified higher version.

### Uninstall a plugin:

notation plugin uninstall <plugin-name>

### Upgrade a plugin to a specified version:

> Note:
> - Notation doesn't support using multiple versions of a plugin in the system.
> - If the upgrade version is equal to or lower than an existing plugin, Notation will return an error message and will not start upgrade.
> - If users upgrade a plugin before installing it, Notation will not start upgrade but will return an error message to guide users to install it.

Upgrade the plugin from a local file path and verify the checksum.

notation plugin upgrade --file <file_path> --checksum <digest>

Upgrade the plugin from an HTTPS shared address.

notation plugin upgrade https://wabbit-networks.com/intaller/linux/amd64/wabbit-plugin-v1.0.tar.gz --checksum <digest>

Upgrade the plugin from an OCI registry.

notation plugin upgrade <registry>/<repository>@<digest>

Upgrade a built-in plugin to a specified version.

notation plugin upgrade wabbit-networks --version 2.0

## Phased plan to implement the proposals

Proposal 1 and Proposal 2 (Option 1: install plugin from an HTTPS address) are suggested to be included in the first iteration and planned in v1.1.0. Proposal 2 (Option 2: install plugin as an OCI artifact from a registry) is suggested to be considered in the next iteration, i.e. v1.2.0, because there is not any Notation plugin already published the containerized version at this moment.

Uninstall and upgrade are suggested to be included in v1.1.0.

Proposal 3 still needs more discussion and alignment in the community.

## Open questions

- Why binary archive files like .msi, .exe, .pkg are not recommended and supported in our plugin installation/upgrade design? What is the drawback of supporting those file format?
- Why "notation plugin upgrade" only supports a higher version? Why can't we do a rollback in upgrade?
- > Notation doesn’t support installing and using multiple versions of a plugin in the system. If there there is an existing version, Notation will return an error message and will not start installation. Users can use --force to skip version check and install a specified version.

- Samir: This will likely break automation, as newer versions of the plugins become available, and people just want to use the latest version. Can we not just override the existing plugin with the new plugin in all cases?