Upon startup, Firefox creates and listens on a new UNIX socket (shared
between all tabs and windows) on which commands can be thrown in to fill
HTML forms.  The socket path and permissions can respectively be
configured with the "extensions.icevault.socketPath" and
"extensions.icevault.socketPerms" preferences in "about:config".

The greeting message indicates that the server is ready to
accept commands.  Each command and response are single UTF8 string lines
ending with a newline character `\n'.  (JSON-encoding ensures that
control characters are escaped properly;  decoding to a string rather
than an object is allowed here, although it extends RFC4627.)  Each
response consists of a code (OK, ERROR, or BYE), together with a
JSON-encoded optional message.  Each command line yields to a single a
response line, and commands may not be sent in parallel: clients must
wait for the response of a first command before sending a second one.

An OK response code indicates a successful greeting or client command,
and may be accompanied with a JSON-encoded message data.  An ERROR
response code indicates a server or client protocol error, the reason of
which may be given as an accompanying JSON-encoded UTF8 string.  A BYE
response code indicates an imminent end to client connection.

    S: OK [' ' JSON-encoded-data]
    S: ERROR ' ' JSON-encoded-string
    S: BYE


The greeting message consists of the the URI (scheme://hostname:port) of
the active tab of the active window.  (":port" is omitted for default
ports, e.g., 443 for https.)  Said URI is then cached for the whole
session, until the client disconnects or an REFRESH command is issued.
Hence subsequent GETFORMS and FILL commands are always relative to the
greeting or the most recent REFRESH response URI, rather than the
possibly new active tab.  The URI is a JSON-encoded string.

    S: OK ' ' JSON-encoded-URI


The REFRESH command clears the internal URI and HTML form caches, and
the server replies with the URI of the currently (active) tab of the
(currently) active window.  See the greeting message above for details.

    C: REFRESH
    S: OK ' ' JSON-encoded-URI


The GETFORMS command yields a response message data consisting of the
list of all visible forms, with their method, action URI, and for each
field of type password, text or email, their name, type, value and
maxLength (unless -1) values:

    [
      {
        "method": "POST",
        "action": "https://mail.fripost.org/",
        "fields": [
          {
            "name": "_user",
            "type": "text",
            "value": "guilhem"
          },
          {
            "name": "_pass",
            "type": "password",
            "value": "top secret"
            "maxLength": 32
          }
        ]
      }
    ]

The form list is kept in cache until the client closes the connection or
another GETFORMS command is issued.  This ensure that subsequent FILL
commands are relative to these forms even if the document has been
modified.

    C: GETFORMS
    S: OK JSON-encoded-array


The FILL command must be preceded by a GETFORM command, and takes an
index and a JSON-encoded array of string as arguments.  The index is
that of the form one wants to fill, and the array must be at most as
long as there are of fields in that form (as found in the most recent
GETFORMS response).  The value of each such field is then updated with
that found in the array (unless null).

    C: FILL index JSON-encoded-array
    S: OK


The QUIT command yields a BYE response, and terminates the connection.

    C: QUIT
    S: BYE



Example:

    # client initiates the connection
    S: OK "https://mail.fripost.org"
    C: GETFORMS
    S: OK [{"method":"POST","action":"https://mail.fripost.org/","fields":[{"name":"_user","type":"text","value":""},{"name":"_pass","type":"password","value":""}]}]
    C: FILL 0 ["guilhem","topsecret"]
    S: OK
    C: GETFORM
    S: ERROR "Invalid command: GETFORM"
    C: GETFORMS
    S: OK [{"method":"POST","action":"https://mail.fripost.org/","fields":[{"name":"_user","type":"text","value":"guilhem"},{"name":"_pass","type":"password","value":"topsecret"}]}]
    C: QUIT
    S: BYE
    # client is disconnected