Expand plugin spec with installation details

Signed-off-by: qmuntal <qmuntaldiaz@microsoft.com>

specs/plugin-extensibility.md

@@ -14,18 +14,47 @@ Keys and associated certificates used for signing artifacts using Notary could b
 
 * A plugin publisher MUST be able to distribute and patch a Notation plugin independently of Notation’s release cycle.
 * The plugin mechanism MUST work across commonly used OS platforms like Linux, Windows and macOS.
-* The plugin interface contract MUST be versioned. This version is different from Notation's release version. It will be used to accomodate for additional capabilities and contract changes post initial release of Notation.
+* The plugin interface contract MUST be versioned. This version is different from Notation's release version. It will be used to accommodate for additional capabilities and contract changes post initial release of Notation.
 * A plugin MAY implement a subset of capabilities (features) available in plugin contract. E.g A plugin may implement signing feature, but not verification.
 * Notation and plugins MAY be updated independently in an environment.
   * Notation MUST work with a plugin that implements a matching or lower minor version of the plugin contract. Notation SHALL NOT support using a plugin with higher version of plugin contract.
   * A plugin MUST support a single plugin contract version, per major version.
 
 Notation will invoke plugins as executable, pass parameters using command line arguments, and use standard IO streams to pass request/response payloads. This mechanism is used as Go language (used to develop [Notation library](https://github.com/notaryproject/notation-go-lib)) does not have a [in built support](https://github.com/golang/go/issues/19282) to load and execute plugins that works across OS platforms. Other mechanisms like gRPC require every plugin to be implemented as a service/daemon.
 
-### Plugin installation and config
+### Plugin lifecycle management
+
+#### Installation
+
+Plugin publisher will provide instructions to download and install the plugin. Plugins intended for public distribution should also include instructions for users to verify the authenticity of the plugin.
+
+To enumerate all available plugins the following paths are scanned:
+* Unix-like OSes:
+  * `$HOME/.notation/plugins`
+* On Windows:
+  * `%USERPROFILE%\.notation\plugins`
+
+Each plugin executable and dependencies are installed under directory `~/.notation/plugins/{plugin-name}` with an executable under that directory `~/.notation/plugins/{plugin-name}/notation-{plugin-name}`. 
+
+Any directory found inside `~/.notation/plugins` is considered potential plugin "candidates". Anything found which is not a directory or symbolic link is ignored and is not considered as a plugin candidate. On Windows files which do not have a `.exe` suffix are not considered candidates and are ignored.
+
+To be considered a valid plugin a candidate must pass each of these "plugin candidate tests":
+
+* The directory must contain an executable named `notation-{plugin-name}`.
+* On Windows, executables must have a `.exe` suffix.
+* Must, where relevant, have appropriate OS "execute" permissions (e.g. Unix x bit set) for the current user.
+* Must actually be executed successfully and when executed with the subcommand `discover` must produce a valid JSON metadata (and nothing else) on its standard output (schema to be discussed later).
+
+#### Commands
+
+* List
+
+`notation plugin list`
+
+List all valid plugins.
+
+### Plugin configuration
 
-* Plugin publisher will provide instructions to download and install the plugin. Plugins intended for public distribution should also include instructions for users to verify the authenticity of the plugin.
-* Each plugin executable and dependencies are installed under directory `~/.notation/plugins/{plugin-name}` with an executable under that directory `~/.notation/plugins/{plugin-name}/notation-{plugin-name}`. The executable can be a shim which calls plugin dependecies installed elsewhere on the file system.
 * To use a plugin for signing, the user associates the plugin as part of registering a signing key. E.g.
   * `notation key add --name "mysigningkey" --id "keyid" --plugin "com.example.nv2plugin"`
   * In the example, the command registers a signing key in `/notation/config.json`, where `mysigningkey` is a friendly key name to refer during signing operation from the CLI, `id` is an key identifier known to plugin that is used for signing, and the value of `plugin` specifies it's using a plugin located at `~/.notation/plugins/com.example.nv2plugin/notation-com.example.nv2plugin`.
@@ -107,7 +136,7 @@ All response attributes are required.
 
 *supported-contract-versions* - The list of contract versions supported by the plugin. Currently this list must include only one version, per major version. Post initial release, Notation may add new features through plugins, in the form of new commands (e.g. tsa-sign for timestamping), or additional request and response parameters. Notation will publish updates to plugin interface along with appropriate contract version update. Backwards compatible changes (changes for which older version of plugin continue to work with versions of Notation using newer contract version) like new optional parameters on existing contracts, and new commands will be supported through minor version contract updates, breaking changes through major version updates. Plugin `discover` command returns the contract version a plugin supports. Notation will evaluate the minimum plugin version required to satisfy a user's request, and reject the request if the plugin does not support the required version.
 
-*capabilities* - Non empty list of features supported by a plugin. Each capability such as `SIGNATURE_ENVELOPE_GENERATOR` requires one of more commands to be implemented by the plugin. When new features are available for plugins to implement, an implementation may choose to not implement it, and therefore will not include the feature in capabililies. Notation will evaluate the capability required to satisfy a user’s request, and reject the request if the plugin does not support the required capability.
+*capabilities* - Non empty list of features supported by a plugin. Each capability such as `SIGNATURE_ENVELOPE_GENERATOR` requires one of more commands to be implemented by the plugin. When new features are available for plugins to implement, an implementation may choose to not implement it, and therefore will not include the feature in capabilities. Notation will evaluate the capability required to satisfy a user’s request, and reject the request if the plugin does not support the required capability.
 
 ## Signing interfaces
 
@@ -283,4 +312,4 @@ TBD [#135](https://github.com/notaryproject/notaryproject/issues/135)
 * [Issue #151](https://github.com/notaryproject/notation/issues/151) - Add Notation command line options to pass raw signature generated by existing crypto tools.
 * What standard providers should be supported?
 * Do we need to support file based plugin configuration, or pass-through plugin configuration passed as is from Notation CLI to the plugin?
-* Suport for chaining plugins. It allows us to seperate out and compose things like signing, TSA integration, push to transparency log.
+* Support for chaining plugins. It allows us to separate out and compose things like signing, TSA integration, push to transparency log.