mobiletto 1.0.6 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +26 -21
  2. package/index.js +15 -30
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -7,8 +7,13 @@ It supports apps that are agnostic to where files are stored.
7
7
 
8
8
  All drivers are tested for identical behavior with 30 tests for each driver.
9
9
 
10
+ Today the supported drivers are:
11
+
12
+ * `s3`: read/write an Amazon S3 bucket
13
+ * `local`: read/write to local filesystem
14
+
10
15
  # Basic usage
11
- const { mobiletto, readFile } = require('mobiletto')
16
+ const { mobiletto } = require('mobiletto')
12
17
 
13
18
  // General usage
14
19
  const api = await mobiletto(driverName, key, secret, opts)
@@ -75,6 +80,13 @@ All drivers are tested for identical behavior with 30 tests for each driver.
75
80
  local.remove(path, {recursive, quiet})
76
81
  s3.remove(path, {recursive, quiet})
77
82
 
83
+ # Alternate usage
84
+ Import the fully-scoped module and use the `connect` function:
85
+
86
+ const storage = require('mobiletto')
87
+ const s3 = await storage.connect('s3', aws_key, aws_secret, {bucket: 'bk', region: 'us-east-1'})
88
+ const objectData = await s3.readFile('some/path')
89
+
78
90
  # Transparent Encryption
79
91
  Enable transparent client-side encryption:
80
92
 
@@ -82,36 +94,29 @@ Enable transparent client-side encryption:
82
94
  const encryption = {
83
95
  key: randomstring.generate(128), // required, must be >= 32 chars
84
96
  iv: randomstring.generate(128), // optional, default is to derive IV from key
85
- algo: 'aes-256-cbc', // optional, aes-256-cbc is the default
86
- encryptPaths: true // optional, default is true
97
+ algo: 'aes-256-cbc' // optional, aes-256-cbc is the default
87
98
  }
88
99
  const api = await mobiletto(driverName, key, secret, opts, encryption)
89
100
 
90
101
  // Subsequent write operations will encrypt data (client side) when writing
91
102
  // Subsequent read operations will decrypt data (client side) when reading
92
- // If `encryptPaths` is true, then path names will be hashed using the encrpytion key
93
103
 
94
- Note that when `encryptPaths` is enabled, `list` commands are considerably more inefficient,
95
- especially for directories with a large number of files.
96
-
97
- What's happening? A separate "directory entry" directory (encrypted) tracks what files are in that
104
+ What's happening? A separate "directory entry" (dirent) directory (encrypted) tracks what files are in that
98
105
  directory (aka the dirent directory).
99
106
  * The `list` command reads the directory entry files, decrypts each path listed; then returns metadata for each file
107
+ * `list` commands are more inefficient, especially for directories with a large number of files
100
108
  * The `write` command writes dirent files in each parent's dirent directory, recursively; then writes the file
109
+ * `write` commands will incur O(N) writes, with N = depth in the directory hierarchy
101
110
  * The `remove` command removes the corresponding dirent file, and its parent if empty, recursively; then removes the file
102
- * Note: Recursive removal on large and deep filesystems can be an expensive operation
103
-
104
- Note that even with `encryptPaths` enabled, an adversary with full visibility into your encrypted storage,
105
- even without the key, can still see the total number of directories and how many files are in each, and with some
106
- effort, discover some or all of the overall hierarchical structure. They would not know the names of the
107
- directories/files unless they also knew your encryption key or had otherwise successfully cracked the encryption.
108
- All bets are off then!
109
-
110
- # Alternate usage: import fully scoped module and use `connect`
111
-
112
- const storage = require('mobiletto')
113
- const s3 = await storage.connect('s3', aws_key, aws_secret, {bucket: 'bk', region: 'us-east-1'})
114
- const objectData = await s3.readFile('some/path')
111
+ * Non-recursive `remove` commands will incur O(N) reads and potentially as many deletes, with N = depth in the directory hierarchy
112
+ * Recursive `remove` commands on large and deep filesystems can be expensive
113
+
114
+ Note that even with client-side encryption enabled, an adversary with full visibility into your encrypted server-side
115
+ storage, even without the key, can still see the total number of directories and how many files are in each, and with
116
+ some effort, discover some or all of the overall structure of the directory hierarchy.
117
+ *Note: Use a relatively flat structure for better security.*
118
+ The adversary would not know the names of the directories/files unless they also knew your encryption
119
+ key or had otherwise successfully cracked the encryption. All bets are off then!
115
120
 
116
121
  # Driver Interface
117
122
  A driver is any JS file that exports a 'storageClient' function with this signature:
package/index.js CHANGED
@@ -74,12 +74,10 @@ async function mobiletto (driverPath, key, secret, opts, encryption = null) {
74
74
  if (!iv) {
75
75
  throw new MobilettoError(`mobiletto(${driverPath}): invalid encryption IV`)
76
76
  }
77
- const encryptPaths = encryption.encryptPaths || true;
78
77
  const enc = {
79
78
  key: encKey,
80
79
  iv,
81
80
  algo: encryption.algo || DEFAULT_CRYPT_ALGO,
82
- encryptPaths,
83
81
  dirLevels: encryption.dirLevels || 4,
84
82
  encPathPadding: () => ENC_PAD_SEP + randomstring.generate(1 + Math.floor(2*Math.random()))
85
83
  }
@@ -92,13 +90,10 @@ async function mobiletto (driverPath, key, secret, opts, encryption = null) {
92
90
  }
93
91
  return newPath + encrypted
94
92
  }
95
- const direntDir = dir => encryptPaths ? encryptPath(dir + DIR_ENT_DIR_SUFFIX) : null
93
+ const direntDir = dir => encryptPath(dir + DIR_ENT_DIR_SUFFIX)
96
94
  const direntFile = (dirent, path) => dirent + '/' + shasum(DIR_ENT_FILE_PREFIX + ' ' + path)
97
95
 
98
96
  const _metadata = (client) => async (path) => {
99
- if (!encryptPaths) {
100
- return client.metadata(path)
101
- }
102
97
  let meta
103
98
  try {
104
99
  meta = await client.metadata(encryptPath(path))
@@ -148,9 +143,6 @@ async function mobiletto (driverPath, key, secret, opts, encryption = null) {
148
143
 
149
144
  const encClient = {
150
145
  list: async (path) => {
151
- if (!encryptPaths) {
152
- return await client.list(path)
153
- }
154
146
  const dirent = direntDir(path)
155
147
  const entries = await client.list(dirent)
156
148
  if (!entries || entries.length === 0) {
@@ -160,7 +152,7 @@ async function mobiletto (driverPath, key, secret, opts, encryption = null) {
160
152
  },
161
153
  metadata: _metadata(client),
162
154
  read: async (path, callback) => {
163
- const realPath = encryptPaths ? encryptPath(path) : path
155
+ const realPath = encryptPath(path)
164
156
  const cipher = crypt.startDecryptStream(enc)
165
157
  return client.read(realPath,
166
158
  (chunk) => {
@@ -171,21 +163,19 @@ async function mobiletto (driverPath, key, secret, opts, encryption = null) {
171
163
  },
172
164
  write: async (path, readFunc) => {
173
165
  // if encrypting paths, write dirent file(s) for all parent directories
174
- if (encryptPaths) {
175
- let p = path
176
- while (true) {
177
- const direntGenerator = function* () {
178
- yield encrypt(p + enc.encPathPadding(), enc)
179
- }
180
- const dir = direntDir(dirname(p))
181
- const df = direntFile(dir, p);
182
- if (!(await client.write(df, direntGenerator()))) {
183
- throw new MobilettoError('write: error writing dirent file')
184
- }
185
- p = dirname(p)
186
- if (p === '.' || p === '') {
187
- break
188
- }
166
+ let p = path
167
+ while (true) {
168
+ const direntGenerator = function* () {
169
+ yield encrypt(p + enc.encPathPadding(), enc)
170
+ }
171
+ const dir = direntDir(dirname(p))
172
+ const df = direntFile(dir, p);
173
+ if (!(await client.write(df, direntGenerator()))) {
174
+ throw new MobilettoError('write: error writing dirent file')
175
+ }
176
+ p = dirname(p)
177
+ if (p === '.' || p === '') {
178
+ break
189
179
  }
190
180
  }
191
181
 
@@ -203,11 +193,6 @@ async function mobiletto (driverPath, key, secret, opts, encryption = null) {
203
193
  },
204
194
  remove: async (path, options) => {
205
195
  const recursive = (options && options.recursive) || false
206
- const quiet = (options && options.quiet) || false
207
- if (!encryptPaths) {
208
- return client.remove(path, {recursive, quiet})
209
- }
210
-
211
196
  if (recursive) {
212
197
  // ugh. we have to iterate over all dirent files, and remove each file/subdir one by one
213
198
  async function recRm (path) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mobiletto",
3
- "version": "1.0.6",
3
+ "version": "1.0.7",
4
4
  "description": "A storage abstraction layer",
5
5
  "main": "index.js",
6
6
  "author": "Jonathan Cobb",