PROTOCOL.md: Send default settings only for "configure" request, rename field "response" to "data" (#8)

2018-04-14 11:12:33 +02:00
parent ca706e7699
commit 72a0f239ad
1 changed files with 57 additions and 53 deletions
--- a/PROTOCOL.md
+++ b/PROTOCOL.md
@@ -1,4 +1,5 @@
 # Browserpass Communication Protocol
+
 This document describes the protocol used for communication between the browser extension,
 and the native host application.

@@ -6,16 +7,16 @@ and the native host application.

 ### OK

-Consists solely of an `ok` status, an integer app version, and a `response` field. The response
+Consists solely of an `ok` status, an integer app version, and a `data` field which
 may be of any type.

 The app version is an integer, calculated by `(MAJOR * 1000000) + (MINOR * 1000) + PATCH`.

 ```
 {
-    “status”: “ok”,
-    “version”: <int>
-    “response”: <any type>
+    "status": "ok",
+    "version": <int>,
+    "data": <any type>
 }
 ```

@@ -26,11 +27,12 @@ object that provides any parameters that should accompany the error.

 ```
 {
-    “status”: “error”,
-    “code”: <int>
-    “params”: {
-       “<paramN>”: <valueN>
-    }
+    "status": "error",
+    "code": <int>,
+    "version": <int>,
+    "params": {
+       "<paramN>": <valueN>
+    }
 }
 ```

@@ -56,25 +58,24 @@ and via parameters in individual `*.gpg` files.

 Settings are applied using the following priority, highest first:

-  1. Configured by the user in specific `*.gpg` files (e.g. autosubmit: true)
-  2. Configured by the user via the extension options
-  3. Configured by the user in each store’s `.browserpass.json` file
-  4. Defaults shipped with the browser extension
+1.  Configured by the user in specific `*.gpg` files (e.g. autosubmit: true)
+2.  Configured by the user via the extension options
+3.  Configured by the user in each store’s `.browserpass.json` file
+4.  Defaults shipped with the browser extension

 ### Global Settings

-| Setting      | Description                                          | Default |
-| ------------ | ---------------------------------------------------- | ------- |
-| gpgPath      | Optional path to gpg binary                          | `null`  |
-| defaultStore | Store-specific settings for default store            | `{}`    |
-| stores       | List of password stores with store-specific settings | `{}`    |
+| Setting | Description                                          | Default |
+| ------- | ---------------------------------------------------- | ------- |
+| gpgPath | Optional path to gpg binary                          | `null`  |
+| stores  | List of password stores with store-specific settings | `{}`    |

 ### Store-specific Settings

-| Setting      | Description                                          | Default |
-| ------------ | ---------------------------------------------------- | ------- |
-| name         | Store name (same as the store key)                   | <key>   |
-| path         | Path to the password store directory                 | `""`    |
+| Setting | Description                          | Default |
+| ------- | ------------------------------------ | ------- |
+| name    | Store name (same as the store key)   | <key>   |
+| path    | Path to the password store directory | `""`    |

 ## Actions

@@ -87,8 +88,9 @@ is alive, determine the version at startup, and provide per-store defaults.

 ```
 {
-    “settings”: <settings object>,
-    “action”: “configure”
+    "settings": <settings object>,
+    "defaultStoreSettings": <store-specific settings for default store>,
+    "action": "configure"
 }
 ```

@@ -97,29 +99,31 @@ is alive, determine the version at startup, and provide per-store defaults.
 ```
 {

-    “status”: “ok”,
-    “version”: <int>
-    “response”: {
-        "defaultPath": "/path/to/default/store",
-        "defaultSettings": <raw contents of $defaultPath/.browserpass.json>,
-        “storeSettings”: {
-            “storeName”: <raw contents of storePath/.browserpass.json>
-        }
-    }
+    "status": "ok",
+    "version": <int>,
+    "data": {
+        "defaultStore": {
+            "path": "/path/to/default/store",
+            "defaultSettings": "<raw contents of $defaultPath/.browserpass.json>",
+        },
+        “storeSettings”: {
+            “storeName”: "<raw contents of storePath/.browserpass.json>"
+        }
+    }
 }
 ```

 ### List

 Get a list of all `*.gpg` files for each of a provided array of directory paths. The `storeN`
-is the name of a password store, the key in `“settings.stores”` object.
+is the name of a password store, the key in `"settings.stores"` object.

 #### Request

 ```
 {
-    “settings”: <settings object>,
-    “action”: “list”
+    "settings": <settings object>,
+    "action": "list"
 }
 ```

@@ -127,14 +131,14 @@ is the name of a password store, the key in `“settings.stores”` object.

 ```
 {
-    “status”: “ok”,
-    “version”: <int>,
-    “response”: {
-        “files”: {
-            “storeN”: [<storeNPath/file1.gpg>, <...>],
-            “storeN+1”: [<storeN+1Path/file1.gpg>, <...>]
-        }
-    }
+    "status": "ok",
+    "version": <int>,
+    "data": {
+        "files": {
+            "storeN": ["<storeNPath/file1.gpg>", "<...>"],
+            "storeN+1": ["<storeN+1Path/file1.gpg>", "<...>"]
+        }
+    }
 }
 ```

@@ -146,10 +150,10 @@ Get the decrypted contents of a specific file.

 ```
 {
-    “settings”: <settings object>,
-    “action”: “fetch”,
-    “store”: <storeName>
-    “file”: “relative/path/to/file.gpg”
+    "settings": <settings object>,
+    "action": "fetch",
+    "store": "<storeName>",
+    "file": "relative/path/to/file.gpg"
 }
 ```

@@ -157,10 +161,10 @@ Get the decrypted contents of a specific file.

 ```
 {
-    “status”: “ok”,
-    “version”: <int>,
-    “response”: {
-        “data”: <decrypted file contents>
-    }
+    "status": "ok",
+    "version": <int>,
+    "data": {
+        "data": "<decrypted file contents>"
+    }
 }
 ```