Introduce support for user-provided extensions

This change introduces support for discovering and executing
user-provided extensions to the program. Extensions are useful for
allowing users to provide additional functionality on top of the
nitrocli proper. Implementation wise we stick to an approach similar to
git or cargo subcommands in nature: we search the directories listed in
the PATH environment variable for a file that starts with "nitrocli-",
followed by the extension name. This file is then executed. It is
assumed that the extension recognizes (or at least not prohibits) the
following arguments: --nitrocli (providing the path to the nitrocli
binary), --model (with the model passed to the main program), and
--verbosity (the verbosity level).

1 files changed, 28 insertions, 2 deletions

diff --git a/doc/nitrocli.1 b/doc/nitrocli.1
index 0d33cd6..30a57a8 100644
--- a/doc/nitrocli.1
+++ b/doc/nitrocli.1
@@ -14,8 +14,8 @@ and the password safe.
 .TP
 \fB\-m\fR, \fB\-\-model pro\fR|\fBstorage\fR
 Restrict connections to the given device model.
-If this option is not set, nitrocli will connect to any connected Nitrokey Pro
-or Nitrokey Storage device.
+If this option is not set, \fBnitrocli\fR will connect to any connected Nitrokey
+Pro or Nitrokey Storage device.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 Enable additional logging and control its verbosity. Logging enabled through
@@ -271,6 +271,32 @@ The admin PIN cannot be unblocked.
 This operation is equivalent to the unblock PIN option provided by \fBgpg\fR(1)
 (using the \fB\-\-change\-pin\fR option).
 
+.SS Extensions
+In addition to the above built-in commands, \fBnitrocli\fR supports
+user-provided functionality in the form of extensions. An extension can be any
+executable file whose filename starts with "nitrocli-" and that is discoverable
+through lookup via the \fBPATH\fR environment variable.
+
+An extension should honor the following set of options, which are supplied to
+the extension by \fBnitrocli\fR itself:
+.TP
+\fB\-\-nitrocli\fR \fIpath\fR
+The path to the \fBnitrocli\fR binary. This path can be used to recursively
+invoke \fBnitrocli\fR to implement certain functionality. This option is
+guaranteed to be supplied.
+.TP
+\fB\-\-model pro\fR|\fBstorage\fR
+Restrict connections to the given device model (see the Options section for more
+details). This option is supplied only if it was provided by the user to the
+invocation of \fBnitrocli\fR itself.
+.TP
+\fB\-\-verbosity\fR \fIlevel\fR
+Control the logging verbosity by setting the log level to \fIlevel\fR. The
+default level is 0, which corresponds to an invocation of \fBnitrocli\fR
+without additional logging related options. Each additional occurrence of
+\fB\-v\fR/\fB\-\-verbose\fR increments the log level accordingly. This option is
+guaranteed to be supplied.
+
 .SH ENVIRONMENT
 The program honors a set of environment variables that can be used to
 suppress interactive PIN entry through \fBpinentry\fR(1). The following