1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
# Browserpass Communication Protocol
This document describes the protocol used for communication between the browser extension,
and the native host application.
## Response Types
### OK
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>,
"data": <any type>
}
```
### Error
Consists solely of an `error` status, a nonzero integer error code, and an optional `params`
object that provides any parameters that should accompany the error.
```
{
"status": "error",
"code": <int>,
"version": <int>,
"params": {
"<paramN>": <valueN>
}
}
```
When the error message is relaying a message from a native system component, then that message
should be supplied as a `message` parameter.
## List of Error Codes
| Code | Description | Parameters |
| ---- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| 10 | Unable to parse browser request length | message, error |
| 11 | Unable to parse browser request | message, error |
| 12 | Invalid request action | message, action |
| 13 | Inaccessible user-configured password store | message, action, error, storeId, storePath, storeName |
| 14 | Inaccessible default password store | message, action, error, storePath |
| 15 | Unable to determine the location of the default password store | message, action, error |
| 16 | Unable to read the default settings of a user-configured password store | message, action, error, storeId, storePath, storeName |
| 17 | Unable to read the default settings of the default password store | message, action, error, storePath |
| 18 | Unable to list files in a password store | message, action, error, storeId, storePath, storeName |
| 19 | Unable to determine a relative path for a file in a password store | message, action, error, storeId, storePath, storeName, file |
| 20 | Invalid password store ID | message, action, storeId |
| 21 | Invalid gpg path | message, action, error, gpgPath |
| 22 | Unable to detect the location of the gpg binary | message, action, error |
| 23 | Invalid password file extension | message, action, file |
| 24 | Unable to decrypt the password file | message, action, error, storeId, storePath, storeName, file |
## Settings
The `settings` object is a key / value map of individual settings. It's provided by the
browser to the native app as part of every request.
Settings are saved in browser local storage. Each top-level setting is saved separately,
JSON-encoded and saved by its key.
Settings may also be supplied via a `.browserpass.json` file in the root of a password store,
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)
1. Configured by the user in `.browserpass.json` file in specific password stores
1. Configured by the user via the extension options
1. Defaults shipped with the browser extension
### Global 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 |
| ------- | --------------------------------------- | ------- |
| id | Unique store id (same as the store key) | `<key>` |
| name | Store name | `""` |
| path | Path to the password store directory | `""` |
## Actions
### Configure
Returns a response containing the per-store config. Used to check that the host app
is alive, determine the version at startup, and provide per-store defaults.
#### Request
```
{
"settings": <settings object>,
"defaultStoreSettings": <store-specific settings for default store>,
"action": "configure"
}
```
#### Response
```
{
"status": "ok",
"version": <int>,
"data": {
"defaultStore": {
"path": "/path/to/default/store",
"settings": "<raw contents of $defaultPath/.browserpass.json>",
},
“storeSettings”: {
“storeId”: "<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 ID of a password store, the key in `"settings.stores"` object.
#### Request
```
{
"settings": <settings object>,
"action": "list"
}
```
#### Response
```
{
"status": "ok",
"version": <int>,
"data": {
"files": {
"storeN": ["<storeNPath/file1.gpg>", "<...>"],
"storeN+1": ["<storeN+1Path/file1.gpg>", "<...>"]
}
}
}
```
### Fetch
Get the decrypted contents of a specific file.
#### Request
```
{
"settings": <settings object>,
"action": "fetch",
"storeId": "<storeId>",
"file": "relative/path/to/file.gpg"
}
```
#### Response
```
{
"status": "ok",
"version": <int>,
"data": {
"contents": "<decrypted file contents>"
}
}
```
### Echo
Send the `echoResponse` in the request as a response.
#### Request
```
{
"action": "echo",
"echoResponse": <anything>
}
```
#### Response
```
<echoResponse>
```
|
