@shieldfive/cli 0.3.0 → 0.3.1

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.
package/src/unlock.mjs CHANGED
@@ -10,7 +10,7 @@
10
10
 
11
11
  import { webcrypto } from 'node:crypto'
12
12
 
13
- import { deriveMasterSecret } from '@shieldfive/crypto/kdf/argon2id'
13
+ import { deriveMasterSecret } from './argon2.mjs'
14
14
 
15
15
  const subtle = webcrypto.subtle
16
16
 
@@ -62,9 +62,9 @@ export async function deriveUserKey({
62
62
  salt,
63
63
  preset: argon2Preset,
64
64
  })
65
- return subtle.importKey('raw', masterSecret, { name: 'AES-GCM' }, false, [
66
- 'decrypt',
67
- ])
65
+ try {
66
+ return await subtle.importKey('raw', masterSecret, { name: 'AES-GCM' }, false, ['decrypt'])
67
+ } finally { masterSecret.fill(0) }
68
68
  }
69
69
  throw new Error(`Unsupported vault KDF: ${kdf}`)
70
70
  }
@@ -73,21 +73,37 @@ export async function deriveUserKey({
73
73
  * Unwrap the vault root key from the password. `vaultKey` carries the base64
74
74
  * fields of the server's vault_keys row (same shape as the export bundle's
75
75
  * vault.json): ukSalt, ukIv, ukKdf, ukIterations?, ukArgon2Preset?, rkWrappedByUk.
76
+ *
77
+ * The web keyring (utils/keyring.ts) TRIMS the vault password before every
78
+ * wrap and unwrap, so a vault created or re-keyed on the web was wrapped under
79
+ * the trimmed password. That is tried first. Only if it fails AES-GCM
80
+ * authentication, and the password actually has surrounding whitespace, is the
81
+ * password tried exactly as typed (a vault wrapped by a client that does not
82
+ * trim). Nothing here is sent anywhere.
76
83
  * @returns {Promise<Uint8Array>} the 32-byte root key
77
84
  */
78
85
  export async function unlockRootKey({ password, vaultKey }) {
79
- const uk = await deriveUserKey({
80
- password,
81
- salt: base64ToBytes(vaultKey.ukSalt),
82
- kdf: vaultKey.ukKdf,
83
- iterations: vaultKey.ukIterations,
84
- argon2Preset: vaultKey.ukArgon2Preset,
85
- })
86
- return aesGcmDecrypt(
87
- uk,
88
- base64ToBytes(vaultKey.ukIv),
89
- base64ToBytes(vaultKey.rkWrappedByUk),
90
- )
86
+ if (typeof password !== 'string' || !password) throw new Error('Vault password is required')
87
+ const trimmed = password.trim()
88
+ const candidates = trimmed && trimmed !== password ? [trimmed, password] : [password]
89
+ for (let i = 0; i < candidates.length; i++) {
90
+ const uk = await deriveUserKey({
91
+ password: candidates[i],
92
+ salt: base64ToBytes(vaultKey.ukSalt),
93
+ kdf: vaultKey.ukKdf,
94
+ iterations: vaultKey.ukIterations,
95
+ argon2Preset: vaultKey.ukArgon2Preset,
96
+ })
97
+ try {
98
+ return await aesGcmDecrypt(
99
+ uk,
100
+ base64ToBytes(vaultKey.ukIv),
101
+ base64ToBytes(vaultKey.rkWrappedByUk),
102
+ )
103
+ } catch (err) {
104
+ if (i === candidates.length - 1 || err?.name !== 'OperationError') throw err
105
+ }
106
+ }
91
107
  }
92
108
 
93
109
  /** Recovery-key path: unwrap the root key with the base64 recovery key. */
package/src/upload.mjs CHANGED
@@ -10,25 +10,37 @@
10
10
  // (server-side) at finalize. Unchanged.
11
11
  //
12
12
  // Chunks are read from disk one at a time (never the whole file into memory),
13
- // so a multi-gigabyte upload holds at most one chunk (~5 MiB) resident.
13
+ // so a multi-gigabyte upload holds at most a few chunks (~5 MiB each) resident.
14
+ //
15
+ // Format: cipher_version 3, the web's default (suite 0x03, v1 wire format; see
16
+ // uploadCrypto.mjs). Every storage part is one encrypted chunk frame; part 1
17
+ // also carries the header. The header's file_id is the row id the server
18
+ // assigned at create-upload-session, so the stored object is bound to its row.
14
19
 
15
20
  import { open } from 'node:fs/promises'
16
21
 
22
+ import { encryptNameV6 } from '@shieldfive/crypto/vault'
23
+
17
24
  import {
25
+ base64ToBytes,
18
26
  bytesToBase64,
19
- encryptChunkWithDigest,
27
+ CIPHER_VERSION_PQ,
28
+ computeV3UploadProof,
20
29
  encryptMetadataV4,
21
- generateNoncePrefixB64,
30
+ encryptPartsV3,
22
31
  generateRandomKeyB64,
23
32
  getCiphertextHashFromParts,
24
33
  hashMetadataV4,
34
+ sha1Hex,
35
+ uuidToBytes,
36
+ V1_CHUNK_SIZE,
37
+ vaultMlKemPublicKey,
25
38
  wrapKeyB64,
26
39
  } from './uploadCrypto.mjs'
27
40
 
28
41
  const CREATE_SESSION_PATH = '/api/files/create-upload-session'
29
42
  const COMPLETE_PATH = '/api/files/complete-upload'
30
43
  const PART_URL_PATH = '/api/files/upload-part-url'
31
- const CHUNK_SIZE = 5 * 1024 * 1024
32
44
 
33
45
  // Backblaze documents retrying b2_upload_part on 5xx / network failures, and a
34
46
  // part upload is idempotent by (part number, SHA-1) — retrying overwrites the
@@ -81,10 +93,14 @@ export async function createUploadSession({
81
93
  size,
82
94
  }) {
83
95
  const rootKeyB64 = bytesToBase64(rootKey)
96
+ // The row id does not exist yet, so the first name is the row-unbound v4
97
+ // envelope (as on the web). finalizeUpload replaces it with a v6 envelope
98
+ // bound to the row id.
84
99
  const nameEnvelope = await encryptMetadataV4(name, rootKeyB64)
100
+ // For suite 0x03 this is the classical envelope key; csk_wrapped holds it
101
+ // under the parent key (the root key: sf uploads to the vault root).
85
102
  const csk = generateRandomKeyB64()
86
103
  const cskEnvelope = wrapKeyB64({ wrappingKeyB64: rootKeyB64, keyToWrapB64: csk })
87
- const noncePrefix = generateNoncePrefixB64()
88
104
 
89
105
  const res = await fetch(new URL(CREATE_SESSION_PATH, apiBaseUrl), {
90
106
  method: 'POST',
@@ -92,14 +108,15 @@ export async function createUploadSession({
92
108
  Authorization: `Bearer ${accessToken}`,
93
109
  'Content-Type': 'application/json',
94
110
  },
111
+ // v1 wire format: no cipher_nonce_prefix and no chunkSize (the server
112
+ // rejects both; they live in the header).
95
113
  body: JSON.stringify({
96
114
  name_encrypted: JSON.stringify(nameEnvelope),
97
115
  nameHash: hashMetadataV4(name.toLowerCase(), rootKeyB64),
98
116
  csk_wrapped: cskEnvelope.wrapped,
99
117
  csk_iv: cskEnvelope.iv,
100
- cipher_nonce_prefix: noncePrefix,
118
+ cipherVersion: CIPHER_VERSION_PQ,
101
119
  sizeBytes: size,
102
- chunkSize: CHUNK_SIZE,
103
120
  folderId: null,
104
121
  contentType: 'application/octet-stream',
105
122
  thumbnail_ciphertext_b64: null,
@@ -112,7 +129,7 @@ export async function createUploadSession({
112
129
  `create-upload-session failed (HTTP ${res.status}): ${JSON.stringify(body)}`,
113
130
  )
114
131
  }
115
- return { session: body, csk, noncePrefix }
132
+ return { session: body, csk }
116
133
  }
117
134
 
118
135
  // Direct upload: a presigned S3 PUT (web b52b4c8 / PR #726), not b2_upload_file.
@@ -255,6 +272,7 @@ async function finalizeUpload({
255
272
  partSha1Array,
256
273
  proof,
257
274
  ciphertextHash,
275
+ nameEncryptedV6,
258
276
  }) {
259
277
  const res = await fetch(new URL(COMPLETE_PATH, apiBaseUrl), {
260
278
  method: 'POST',
@@ -262,7 +280,7 @@ async function finalizeUpload({
262
280
  Authorization: `Bearer ${accessToken}`,
263
281
  'Content-Type': 'application/json',
264
282
  },
265
- body: JSON.stringify({ fileId, b2FileId, partSha1Array, proof, ciphertextHash }),
283
+ body: JSON.stringify({ fileId, b2FileId, partSha1Array, proof, ciphertextHash, nameEncryptedV6 }),
266
284
  })
267
285
  const body = await res.json().catch(() => ({}))
268
286
  if (!res.ok) {
@@ -273,29 +291,20 @@ async function finalizeUpload({
273
291
  return body
274
292
  }
275
293
 
276
- // Single-chunk file: encrypt the one chunk (AES-GCM, suite 0x01) + SHA-1 +
277
- // proof, PUT it at the presigned URL, finalize. No b2FileId is sent -- the
278
- // server HEADs the stored object and derives the storage id itself.
279
- async function uploadDirect({ apiBaseUrl, accessToken, session, csk, noncePrefix, path, onPlaintextChunk }) {
280
- const chunkSize = session.chunkSize ?? CHUNK_SIZE
281
- let plaintext = null
282
- for await (const chunk of readFileChunks(path, chunkSize)) {
283
- if (plaintext !== null) {
294
+ // Single-chunk file: one part (header || frame_0), SHA-1 + proof, PUT it at
295
+ // the presigned URL, finalize. No b2FileId is sent -- the server HEADs the
296
+ // stored object and derives the storage id itself.
297
+ async function uploadDirect({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6 }) {
298
+ let ciphertext = null
299
+ for await (const part of parts) {
300
+ if (ciphertext !== null) {
284
301
  throw new Error('Direct upload session is larger than a single chunk.')
285
302
  }
286
- plaintext = chunk
287
- onPlaintextChunk?.(chunk)
303
+ ciphertext = part
288
304
  }
289
- if (plaintext === null) plaintext = new Uint8Array(0)
290
-
291
- const { ciphertext, sha1Hex, proofHex } = await encryptChunkWithDigest({
292
- cskB64: csk,
293
- noncePrefixB64: noncePrefix,
294
- chunkIndex: 0,
295
- plaintext,
296
- proofKeyHex: session.proofKey,
297
- chunkSize,
298
- })
305
+ if (ciphertext === null) throw new Error('Direct upload produced no ciphertext.')
306
+ const sha1 = await sha1Hex(ciphertext)
307
+ const proof = await computeV3UploadProof({ proofKeyHex: session.proofKey, part0: ciphertext })
299
308
 
300
309
  await putDirectPresigned({ session, ciphertext })
301
310
 
@@ -308,16 +317,17 @@ async function uploadDirect({ apiBaseUrl, accessToken, session, csk, noncePrefix
308
317
  apiBaseUrl,
309
318
  accessToken,
310
319
  fileId: session.fileId,
311
- partSha1Array: [sha1Hex],
312
- proof: proofHex,
313
- ciphertextHash: sha1Hex,
320
+ partSha1Array: [sha1],
321
+ proof,
322
+ ciphertextHash: sha1,
323
+ nameEncryptedV6,
314
324
  })
315
325
  }
316
326
 
317
- // Multipart file: stream each chunk, encrypt (per-chunk nonce via chunkIndex),
318
- // b2_upload_part, collect part SHA-1s. The upload proof is computed from the
319
- // FIRST chunk only — the server re-derives it from the first chunkSize+tag
320
- // bytes of the stored object, which is exactly part 1. b2FileId is the
327
+ // Multipart file: stream each encrypted part (one chunk frame each; part 1
328
+ // also carries the header), b2_upload_part, collect part SHA-1s. The upload
329
+ // proof covers the header and the first frame only — the server re-derives it
330
+ // from the start of the stored object, which is exactly part 1. b2FileId is the
321
331
  // large-file id from the session; the server calls b2_finish_large_file with
322
332
  // the ordered part hashes at finalize.
323
333
  // Bounded concurrency for multipart part uploads. The serial version left the
@@ -337,11 +347,10 @@ function resolveUploadConcurrency() {
337
347
  return DEFAULT_UPLOAD_CONCURRENCY
338
348
  }
339
349
 
340
- async function uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePrefix, path, onPlaintextChunk }) {
350
+ async function uploadMultipart({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6 }) {
341
351
  if (!session.b2FileId) {
342
352
  throw new Error('Multipart upload session is missing storage id (b2FileId).')
343
353
  }
344
- const chunkSize = session.chunkSize ?? CHUNK_SIZE
345
354
  const concurrency = resolveUploadConcurrency()
346
355
 
347
356
  // Part SHA-1s keyed by chunkIndex, NOT push order, so parts finishing out of
@@ -360,18 +369,13 @@ async function uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePre
360
369
  (await refreshUploadPartUrl({ apiBaseUrl, accessToken, fileId: session.fileId }))
361
370
 
362
371
  const inFlight = new Set()
363
- const dispatch = (chunkIndex, plaintext) => {
372
+ const dispatch = (chunkIndex, ciphertext) => {
364
373
  const run = (async () => {
365
374
  try {
366
- const encrypted = await encryptChunkWithDigest({
367
- cskB64: csk,
368
- noncePrefixB64: noncePrefix,
369
- chunkIndex,
370
- plaintext,
371
- proofKeyHex: chunkIndex === 0 ? session.proofKey : undefined,
372
- chunkSize: chunkIndex === 0 ? chunkSize : undefined,
373
- })
374
- if (chunkIndex === 0) proof = encrypted.proofHex
375
+ const encrypted = { ciphertext, sha1Hex: await sha1Hex(ciphertext) }
376
+ if (chunkIndex === 0) {
377
+ proof = await computeV3UploadProof({ proofKeyHex: session.proofKey, part0: ciphertext })
378
+ }
375
379
 
376
380
  const slot = await acquireUrl()
377
381
  const updated = await putPartToBackblaze({
@@ -397,8 +401,7 @@ async function uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePre
397
401
  }
398
402
 
399
403
  let chunkIndex = 0
400
- for await (const plaintext of readFileChunks(path, chunkSize)) {
401
- onPlaintextChunk?.(plaintext)
404
+ for await (const ciphertext of parts) {
402
405
  if (firstError) break
403
406
  // Backpressure: hold at most `concurrency` parts in flight. inFlight is
404
407
  // non-empty when this runs (size >= concurrency >= 1), so race never hangs.
@@ -407,7 +410,7 @@ async function uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePre
407
410
  if (firstError) break
408
411
  }
409
412
  if (firstError) break
410
- dispatch(chunkIndex, plaintext)
413
+ dispatch(chunkIndex, ciphertext)
411
414
  chunkIndex += 1
412
415
  }
413
416
 
@@ -437,6 +440,7 @@ async function uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePre
437
440
  partSha1Array,
438
441
  proof,
439
442
  ciphertextHash,
443
+ nameEncryptedV6,
440
444
  })
441
445
  }
442
446
 
@@ -445,31 +449,62 @@ async function uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePre
445
449
  // chunks to record what was actually uploaded; hashing the file separately,
446
450
  // before or after, cannot see a change made and undone while it was being read.
447
451
  export async function uploadFile({ apiBaseUrl, accessToken, rootKey, name, path, size, onPlaintextChunk }) {
448
- const { session, csk, noncePrefix } = await createUploadSession({
452
+ // Derived before anything is sent, so a vault whose identity cannot be
453
+ // derived fails before a session (and a pending row) exists.
454
+ const recipientPublicKey = await vaultMlKemPublicKey(rootKey)
455
+ const { session, csk } = await createUploadSession({
449
456
  apiBaseUrl,
450
457
  accessToken,
451
458
  rootKey,
452
459
  name,
453
460
  size,
454
461
  })
455
-
456
- if (session.uploadKind === 'direct') {
457
- // No authToken and no storagePath check: since web b52b4c8 (PR #726) the
458
- // direct path is a presigned S3 PUT, so the signature inside uploadUrl is
459
- // the only credential and it already binds the object key. Requiring the
460
- // token the server stopped issuing is what made every <= 5 MiB upload fail
461
- // from 2026-09-03. The 'large' branch below still needs both.
462
- if (!session.uploadUrl) {
463
- throw new Error('Direct upload session is missing an upload URL.')
462
+ if (!session.proofKey) throw new Error('Upload session is missing its proof key.')
463
+
464
+ // The server's v1 chunk size (5 MiB): each encrypted chunk is one storage part.
465
+ const chunkSize = session.chunkSize ?? V1_CHUNK_SIZE
466
+ async function* plaintextChunks() {
467
+ for await (const chunk of readFileChunks(path, chunkSize)) {
468
+ onPlaintextChunk?.(chunk)
469
+ yield chunk
464
470
  }
465
- await uploadDirect({ apiBaseUrl, accessToken, session, csk, noncePrefix, path, onPlaintextChunk })
466
- } else if (session.uploadKind === 'large') {
467
- if (!session.uploadUrl || !session.authToken) {
468
- throw new Error('Multipart upload session is missing credentials.')
471
+ }
472
+ const envelopeKey = base64ToBytes(csk)
473
+ const parts = encryptPartsV3({
474
+ plaintextChunks: plaintextChunks(),
475
+ plaintextSize: size,
476
+ chunkSize,
477
+ envelopeKey,
478
+ fileId: uuidToBytes(session.fileId),
479
+ recipientPublicKey,
480
+ })
481
+ // The name, re-sealed with the row id as AAD (v6), replaces the v4 one at
482
+ // finalize, so the backend cannot relabel this row with another file's name.
483
+ const nameEncryptedV6 = JSON.stringify(
484
+ await encryptNameV6({ name, folderKey: rootKey, rowId: session.fileId }),
485
+ )
486
+
487
+ try {
488
+ if (session.uploadKind === 'direct') {
489
+ // No authToken and no storagePath check: since web b52b4c8 (PR #726) the
490
+ // direct path is a presigned S3 PUT, so the signature inside uploadUrl is
491
+ // the only credential and it already binds the object key. Requiring the
492
+ // token the server stopped issuing is what made every <= 5 MiB upload fail
493
+ // from 2026-09-03. The 'large' branch below still needs both.
494
+ if (!session.uploadUrl) {
495
+ throw new Error('Direct upload session is missing an upload URL.')
496
+ }
497
+ await uploadDirect({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6 })
498
+ } else if (session.uploadKind === 'large') {
499
+ if (!session.uploadUrl || !session.authToken) {
500
+ throw new Error('Multipart upload session is missing credentials.')
501
+ }
502
+ await uploadMultipart({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6 })
503
+ } else {
504
+ throw new Error(`Unknown uploadKind "${session.uploadKind}" for "${name}".`)
469
505
  }
470
- await uploadMultipart({ apiBaseUrl, accessToken, session, csk, noncePrefix, path, onPlaintextChunk })
471
- } else {
472
- throw new Error(`Unknown uploadKind "${session.uploadKind}" for "${name}".`)
506
+ } finally {
507
+ envelopeKey.fill(0)
473
508
  }
474
509
 
475
510
  return { fileId: session.fileId }