@shieldfive/cli 0.3.1 → 0.5.0

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/upload.mjs CHANGED
@@ -17,7 +17,9 @@
17
17
  // also carries the header. The header's file_id is the row id the server
18
18
  // assigned at create-upload-session, so the stored object is bound to its row.
19
19
 
20
+ import { constants as fsConstants } from 'node:fs'
20
21
  import { open } from 'node:fs/promises'
22
+ import { webcrypto } from 'node:crypto'
21
23
 
22
24
  import { encryptNameV6 } from '@shieldfive/crypto/vault'
23
25
 
@@ -25,8 +27,8 @@ import {
25
27
  base64ToBytes,
26
28
  bytesToBase64,
27
29
  CIPHER_VERSION_PQ,
30
+ computeV3EmptyUploadProof,
28
31
  computeV3UploadProof,
29
- encryptMetadataV4,
30
32
  encryptPartsV3,
31
33
  generateRandomKeyB64,
32
34
  getCiphertextHashFromParts,
@@ -41,23 +43,50 @@ import {
41
43
  const CREATE_SESSION_PATH = '/api/files/create-upload-session'
42
44
  const COMPLETE_PATH = '/api/files/complete-upload'
43
45
  const PART_URL_PATH = '/api/files/upload-part-url'
46
+ const DELETE_PATH = '/api/files/delete'
47
+ const CAPABILITIES_PATH = '/api/files/upload-capabilities'
44
48
 
45
49
  // Backblaze documents retrying b2_upload_part on 5xx / network failures, and a
46
50
  // part upload is idempotent by (part number, SHA-1) — retrying overwrites the
47
51
  // same part. Bound the retries and back off so one transient blip does not
48
52
  // abort a whole multi-gigabyte upload.
49
- const MAX_PART_ATTEMPTS = 3
50
- const PART_RETRY_BASE_DELAY_MS = 250
53
+ const MAX_PART_ATTEMPTS = 5
54
+ const PART_RETRY_BASE_DELAY_MS = 1000
51
55
 
52
56
  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
53
57
  const partRetryDelayMs = (attempt) =>
54
- PART_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) // 250ms, 500ms, ...
58
+ PART_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) // 1s, 2s, 4s, 8s
59
+
60
+ // `accessToken` is a string, or a function returning the current one. A
61
+ // function is resolved at every request, so an upload that outlives the access
62
+ // token (about an hour; a multi-gigabyte file can) picks up a refreshed session
63
+ // for its later part URLs and its finalize.
64
+ export async function resolveToken(accessToken) {
65
+ return typeof accessToken === 'function' ? accessToken() : accessToken
66
+ }
67
+
68
+ // An Error that keeps the HTTP status and the server's error code, so callers
69
+ // can tell a transient failure (5xx, 429) from a terminal one (quota, 4xx).
70
+ export function httpError(message, status, body) {
71
+ const err = new Error(message)
72
+ err.status = status
73
+ if (body && typeof body === 'object' && typeof body.code === 'string') err.serverCode = body.code
74
+ return err
75
+ }
55
76
 
56
77
  // Read a file in fixed-size chunks without holding it all in memory. Each yield
57
78
  // is an independent copy (the read buffer is reused), so the caller may retain
58
79
  // or transform a chunk across the next read safely.
80
+ //
81
+ // O_NOFOLLOW: callers list files with lstat and skip symlinks, but a regular
82
+ // file could be swapped for a symlink between that check and this open. With
83
+ // O_NOFOLLOW the open fails (ELOOP) instead of uploading whatever the link
84
+ // points at, possibly outside the folder being pushed. (Undefined on Windows,
85
+ // where it is simply not applied.)
86
+ const OPEN_READ_NOFOLLOW = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0)
87
+
59
88
  export async function* readFileChunks(path, chunkSize) {
60
- const handle = await open(path, 'r')
89
+ const handle = await open(path, OPEN_READ_NOFOLLOW)
61
90
  try {
62
91
  const buffer = Buffer.allocUnsafe(chunkSize)
63
92
  for (;;) {
@@ -85,39 +114,66 @@ export async function* readFileChunks(path, chunkSize) {
85
114
  }
86
115
  }
87
116
 
117
+ // A fresh UUIDv7 (RFC 9562): 48-bit ms timestamp, version 7, variant 10.
118
+ // The web app's newRowBoundId (utils/fileRowBinding.ts) builds the same shape;
119
+ // the server's create-upload-session takes it as clientUploadId.
120
+ export function newRowBoundId(now = Date.now()) {
121
+ const bytes = webcrypto.getRandomValues(new Uint8Array(16))
122
+ let ts = BigInt(now)
123
+ for (let i = 5; i >= 0; i -= 1) {
124
+ bytes[i] = Number(ts & 0xffn)
125
+ ts >>= 8n
126
+ }
127
+ bytes[6] = (bytes[6] & 0x0f) | 0x70
128
+ bytes[8] = (bytes[8] & 0x3f) | 0x80
129
+ const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
130
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
131
+ }
132
+
88
133
  export async function createUploadSession({
89
134
  apiBaseUrl,
90
135
  accessToken,
91
136
  rootKey,
92
137
  name,
93
138
  size,
139
+ rowId,
140
+ folderId = null,
141
+ folderKey = null,
94
142
  }) {
95
143
  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.
99
- const nameEnvelope = await encryptMetadataV4(name, rootKeyB64)
144
+ // The parent's key: the root key at the vault root, else the folder's own
145
+ // key. The name is sealed under it and the envelope key wrapped by it,
146
+ // exactly as the web uploader does for a file inside a folder. The name hash
147
+ // is always keyed by the root key (web hashMetadataClient(name, rootKey)).
148
+ const parentKey = folderKey ?? rootKey
149
+ const parentKeyB64 = bytesToBase64(parentKey)
150
+ // The client picks the row id (UUIDv7, sent as clientUploadId), so the very
151
+ // first stored name is already the v6 envelope bound to that row. No v4
152
+ // (row-unbound) name is ever written, even for an upload that fails before
153
+ // finalize.
154
+ const nameEnvelopeV6 = await encryptNameV6({ name, folderKey: parentKey, rowId })
100
155
  // 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).
156
+ // under the parent key.
102
157
  const csk = generateRandomKeyB64()
103
- const cskEnvelope = wrapKeyB64({ wrappingKeyB64: rootKeyB64, keyToWrapB64: csk })
158
+ const cskEnvelope = wrapKeyB64({ wrappingKeyB64: parentKeyB64, keyToWrapB64: csk })
104
159
 
105
160
  const res = await fetch(new URL(CREATE_SESSION_PATH, apiBaseUrl), {
106
161
  method: 'POST',
107
162
  headers: {
108
- Authorization: `Bearer ${accessToken}`,
163
+ Authorization: `Bearer ${await resolveToken(accessToken)}`,
109
164
  'Content-Type': 'application/json',
110
165
  },
111
166
  // v1 wire format: no cipher_nonce_prefix and no chunkSize (the server
112
167
  // rejects both; they live in the header).
113
168
  body: JSON.stringify({
114
- name_encrypted: JSON.stringify(nameEnvelope),
169
+ clientUploadId: rowId,
170
+ name_encrypted: JSON.stringify(nameEnvelopeV6),
115
171
  nameHash: hashMetadataV4(name.toLowerCase(), rootKeyB64),
116
172
  csk_wrapped: cskEnvelope.wrapped,
117
173
  csk_iv: cskEnvelope.iv,
118
174
  cipherVersion: CIPHER_VERSION_PQ,
119
175
  sizeBytes: size,
120
- folderId: null,
176
+ folderId,
121
177
  contentType: 'application/octet-stream',
122
178
  thumbnail_ciphertext_b64: null,
123
179
  thumbnail_nonce_prefix: null,
@@ -125,11 +181,13 @@ export async function createUploadSession({
125
181
  })
126
182
  const body = await res.json().catch(() => ({}))
127
183
  if (!res.ok) {
128
- throw new Error(
184
+ throw httpError(
129
185
  `create-upload-session failed (HTTP ${res.status}): ${JSON.stringify(body)}`,
186
+ res.status,
187
+ body,
130
188
  )
131
189
  }
132
- return { session: body, csk }
190
+ return { session: body, csk, nameEncryptedV6: JSON.stringify(nameEnvelopeV6) }
133
191
  }
134
192
 
135
193
  // Direct upload: a presigned S3 PUT (web b52b4c8 / PR #726), not b2_upload_file.
@@ -147,18 +205,34 @@ export async function createUploadSession({
147
205
  // Returns nothing. A presigned PUT answers with an ETag, not a Backblaze file
148
206
  // id, so there is no storage id to hand to finalize.
149
207
  async function putDirectPresigned({ session, ciphertext }) {
150
- const res = await fetch(session.uploadUrl, {
151
- method: 'PUT',
152
- headers: {
153
- 'Content-Type': session.contentType || 'application/octet-stream',
154
- },
155
- body: ciphertext,
156
- })
157
- if (!res.ok) {
158
- throw new Error(
208
+ // Retried on network errors and 5xx / 408 / 429: the presigned URL names one
209
+ // object key, so a repeated PUT overwrites the same object with the same bytes.
210
+ let lastError
211
+ for (let tries = 1; tries <= MAX_PART_ATTEMPTS; tries += 1) {
212
+ let res
213
+ try {
214
+ res = await fetch(session.uploadUrl, {
215
+ method: 'PUT',
216
+ headers: {
217
+ 'Content-Type': session.contentType || 'application/octet-stream',
218
+ },
219
+ body: ciphertext,
220
+ })
221
+ } catch (err) {
222
+ lastError = err
223
+ if (tries < MAX_PART_ATTEMPTS) await sleep(partRetryDelayMs(tries))
224
+ continue
225
+ }
226
+ if (res.ok) return
227
+ lastError = httpError(
159
228
  `Direct upload failed (HTTP ${res.status}): ${await res.text().catch(() => '')}`,
229
+ res.status,
160
230
  )
231
+ const retryable = res.status >= 500 || res.status === 429 || res.status === 408
232
+ if (!retryable) throw lastError
233
+ if (tries < MAX_PART_ATTEMPTS) await sleep(partRetryDelayMs(tries))
161
234
  }
235
+ throw lastError
162
236
  }
163
237
 
164
238
  // Ask the server for a fresh b2_upload_part URL + token when the current one
@@ -167,15 +241,17 @@ async function refreshUploadPartUrl({ apiBaseUrl, accessToken, fileId }) {
167
241
  const res = await fetch(new URL(PART_URL_PATH, apiBaseUrl), {
168
242
  method: 'POST',
169
243
  headers: {
170
- Authorization: `Bearer ${accessToken}`,
244
+ Authorization: `Bearer ${await resolveToken(accessToken)}`,
171
245
  'Content-Type': 'application/json',
172
246
  },
173
247
  body: JSON.stringify({ fileId }),
174
248
  })
175
249
  const body = await res.json().catch(() => ({}))
176
250
  if (!res.ok || !body.uploadUrl || !body.authToken) {
177
- throw new Error(
251
+ throw httpError(
178
252
  `upload-part-url failed (HTTP ${res.status}): ${JSON.stringify(body)}`,
253
+ res.status,
254
+ body,
179
255
  )
180
256
  }
181
257
  return { uploadUrl: body.uploadUrl, authToken: body.authToken }
@@ -242,9 +318,10 @@ async function putPartToBackblaze({
242
318
 
243
319
  if (res.ok) return { uploadUrl: url, authToken: token }
244
320
 
245
- lastError = new Error(
321
+ lastError = httpError(
246
322
  `Backblaze part ${partNumber} upload failed (HTTP ${res.status}): ` +
247
323
  `${await res.text().catch(() => '')}`,
324
+ res.status,
248
325
  )
249
326
 
250
327
  // 5xx / 408 / 429 are worth retrying; other 4xx (after the auth refresh
@@ -274,18 +351,28 @@ async function finalizeUpload({
274
351
  ciphertextHash,
275
352
  nameEncryptedV6,
276
353
  }) {
277
- const res = await fetch(new URL(COMPLETE_PATH, apiBaseUrl), {
278
- method: 'POST',
279
- headers: {
280
- Authorization: `Bearer ${accessToken}`,
281
- 'Content-Type': 'application/json',
282
- },
283
- body: JSON.stringify({ fileId, b2FileId, partSha1Array, proof, ciphertextHash, nameEncryptedV6 }),
284
- })
354
+ let res
355
+ try {
356
+ res = await fetch(new URL(COMPLETE_PATH, apiBaseUrl), {
357
+ method: 'POST',
358
+ headers: {
359
+ Authorization: `Bearer ${await resolveToken(accessToken)}`,
360
+ 'Content-Type': 'application/json',
361
+ },
362
+ body: JSON.stringify({ fileId, b2FileId, partSha1Array, proof, ciphertextHash, nameEncryptedV6 }),
363
+ })
364
+ } catch (err) {
365
+ // The request may have reached the server and finalized the file; only the
366
+ // answer was lost. Cancelling now could bin a file that is in the vault.
367
+ err.finalizeOutcomeUnknown = true
368
+ throw err
369
+ }
285
370
  const body = await res.json().catch(() => ({}))
286
371
  if (!res.ok) {
287
- throw new Error(
372
+ throw httpError(
288
373
  `complete-upload failed (HTTP ${res.status}): ${JSON.stringify(body)}`,
374
+ res.status,
375
+ body,
289
376
  )
290
377
  }
291
378
  return body
@@ -294,7 +381,7 @@ async function finalizeUpload({
294
381
  // Single-chunk file: one part (header || frame_0), SHA-1 + proof, PUT it at
295
382
  // the presigned URL, finalize. No b2FileId is sent -- the server HEADs the
296
383
  // stored object and derives the storage id itself.
297
- async function uploadDirect({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6 }) {
384
+ async function uploadDirect({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6, empty = false }) {
298
385
  let ciphertext = null
299
386
  for await (const part of parts) {
300
387
  if (ciphertext !== null) {
@@ -303,8 +390,12 @@ async function uploadDirect({ apiBaseUrl, accessToken, session, parts, nameEncry
303
390
  ciphertext = part
304
391
  }
305
392
  if (ciphertext === null) throw new Error('Direct upload produced no ciphertext.')
393
+ // For a 0-byte file part 1 is the header alone, and the proof covers it:
394
+ // the server's empty-file contract is HMAC(proofKey, [3][3] || header).
306
395
  const sha1 = await sha1Hex(ciphertext)
307
- const proof = await computeV3UploadProof({ proofKeyHex: session.proofKey, part0: ciphertext })
396
+ const proof = empty
397
+ ? computeV3EmptyUploadProof({ proofKeyHex: session.proofKey, header: ciphertext })
398
+ : await computeV3UploadProof({ proofKeyHex: session.proofKey, part0: ciphertext })
308
399
 
309
400
  await putDirectPresigned({ session, ciphertext })
310
401
 
@@ -444,21 +535,104 @@ async function uploadMultipart({ apiBaseUrl, accessToken, session, parts, nameEn
444
535
  })
445
536
  }
446
537
 
538
+ // Best-effort cancel of a session that will never finalize. The pending row
539
+ // otherwise holds quota (and, for multipart, an unfinished Backblaze large
540
+ // file) until the server's stale-upload reaper gets to it. POST
541
+ // /api/files/delete with the row id is what the web app's cancel path uses:
542
+ // for a non-ready row it cancels the large file and drops the metadata. Never
543
+ // throws; a failure here must not hide the error that caused it.
544
+ export async function cancelUploadSession({ apiBaseUrl, accessToken, fileId }) {
545
+ try {
546
+ const res = await fetch(new URL(DELETE_PATH, apiBaseUrl), {
547
+ method: 'POST',
548
+ headers: {
549
+ Authorization: `Bearer ${await resolveToken(accessToken)}`,
550
+ 'Content-Type': 'application/json',
551
+ },
552
+ body: JSON.stringify({ ids: [fileId] }),
553
+ })
554
+ return res.ok
555
+ } catch {
556
+ return false
557
+ }
558
+ }
559
+
560
+ export class EmptyFileUnsupportedError extends Error {
561
+ constructor(name) {
562
+ super(
563
+ `"${name}" is empty (0 bytes) and this ShieldFive server does not accept ` +
564
+ 'empty files yet. Nothing was uploaded for it.',
565
+ )
566
+ this.name = 'EmptyFileUnsupportedError'
567
+ this.code = 'empty_file_unsupported'
568
+ }
569
+ }
570
+
571
+ // Zero-byte cipher-v3 uploads are behind a server capability (web
572
+ // docs/desktop-empty-file-contract.md). Ask before creating a session, so an
573
+ // older or flag-off server gets no pending row at all.
574
+ async function serverAcceptsEmptyFiles({ apiBaseUrl, accessToken }) {
575
+ try {
576
+ const res = await fetch(new URL(CAPABILITIES_PATH, apiBaseUrl), {
577
+ headers: { Authorization: `Bearer ${await resolveToken(accessToken)}` },
578
+ })
579
+ if (!res.ok) return false
580
+ const body = await res.json().catch(() => ({}))
581
+ return body?.emptyCipherV3 === true
582
+ } catch {
583
+ return false
584
+ }
585
+ }
586
+
447
587
  // `onPlaintextChunk`, when given, is called with every plaintext chunk in file
448
588
  // order, from the same read that feeds encryption. The agent hashes those
449
589
  // chunks to record what was actually uploaded; hashing the file separately,
450
590
  // before or after, cannot see a change made and undone while it was being read.
451
- export async function uploadFile({ apiBaseUrl, accessToken, rootKey, name, path, size, onPlaintextChunk }) {
591
+ // `rowId` is for tests only; callers let it default to a fresh UUIDv7.
592
+ export async function uploadFile({ apiBaseUrl, accessToken, rootKey, name, path, size, onPlaintextChunk, rowId = newRowBoundId(), folderId = null, folderKey = null }) {
452
593
  // Derived before anything is sent, so a vault whose identity cannot be
453
594
  // derived fails before a session (and a pending row) exists.
454
595
  const recipientPublicKey = await vaultMlKemPublicKey(rootKey)
455
- const { session, csk } = await createUploadSession({
596
+ if (size === 0 && !(await serverAcceptsEmptyFiles({ apiBaseUrl, accessToken }))) {
597
+ throw new EmptyFileUnsupportedError(name)
598
+ }
599
+ const { session, csk, nameEncryptedV6 } = await createUploadSession({
456
600
  apiBaseUrl,
457
601
  accessToken,
458
602
  rootKey,
459
603
  name,
460
604
  size,
605
+ rowId,
606
+ folderId,
607
+ folderKey,
461
608
  })
609
+ // From here on a pending row exists. Any failure before finalize answers
610
+ // cancels it (see cancelUploadSession).
611
+ const envelopeKey = base64ToBytes(csk)
612
+ try {
613
+ // The name and the file header are bound to rowId. A server that ignored
614
+ // clientUploadId would hand back another id; refuse it (and cancel the
615
+ // row it made) rather than upload under a mismatched binding.
616
+ if (session?.fileId !== rowId) {
617
+ throw new Error(
618
+ `create-upload-session returned file id ${session?.fileId} for requested ${rowId}; ` +
619
+ 'this ShieldFive server is too old for this client.',
620
+ )
621
+ }
622
+ await sendUpload({ apiBaseUrl, accessToken, name, path, size, onPlaintextChunk, session, envelopeKey, recipientPublicKey, nameEncryptedV6 })
623
+ } catch (err) {
624
+ if (!err?.finalizeOutcomeUnknown && session?.fileId) {
625
+ await cancelUploadSession({ apiBaseUrl, accessToken, fileId: session.fileId })
626
+ }
627
+ throw err
628
+ } finally {
629
+ envelopeKey.fill(0)
630
+ }
631
+
632
+ return { fileId: session.fileId }
633
+ }
634
+
635
+ async function sendUpload({ apiBaseUrl, accessToken, name, path, size, onPlaintextChunk, session, envelopeKey, recipientPublicKey, nameEncryptedV6 }) {
462
636
  if (!session.proofKey) throw new Error('Upload session is missing its proof key.')
463
637
 
464
638
  // The server's v1 chunk size (5 MiB): each encrypted chunk is one storage part.
@@ -469,7 +643,6 @@ export async function uploadFile({ apiBaseUrl, accessToken, rootKey, name, path,
469
643
  yield chunk
470
644
  }
471
645
  }
472
- const envelopeKey = base64ToBytes(csk)
473
646
  const parts = encryptPartsV3({
474
647
  plaintextChunks: plaintextChunks(),
475
648
  plaintextSize: size,
@@ -478,34 +651,24 @@ export async function uploadFile({ apiBaseUrl, accessToken, rootKey, name, path,
478
651
  fileId: uuidToBytes(session.fileId),
479
652
  recipientPublicKey,
480
653
  })
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}".`)
654
+ // The same v6 name sent at create (bound to the row id) is sent again at
655
+ // finalize, which still expects it.
656
+ if (session.uploadKind === 'direct') {
657
+ // No authToken and no storagePath check: since web b52b4c8 (PR #726) the
658
+ // direct path is a presigned S3 PUT, so the signature inside uploadUrl is
659
+ // the only credential and it already binds the object key. Requiring the
660
+ // token the server stopped issuing is what made every <= 5 MiB upload fail
661
+ // from 2026-09-03. The 'large' branch below still needs both.
662
+ if (!session.uploadUrl) {
663
+ throw new Error('Direct upload session is missing an upload URL.')
505
664
  }
506
- } finally {
507
- envelopeKey.fill(0)
665
+ await uploadDirect({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6, empty: size === 0 })
666
+ } else if (session.uploadKind === 'large') {
667
+ if (!session.uploadUrl || !session.authToken) {
668
+ throw new Error('Multipart upload session is missing credentials.')
669
+ }
670
+ await uploadMultipart({ apiBaseUrl, accessToken, session, parts, nameEncryptedV6 })
671
+ } else {
672
+ throw new Error(`Unknown uploadKind "${session.uploadKind}" for "${name}".`)
508
673
  }
509
-
510
- return { fileId: session.fileId }
511
674
  }
@@ -4,7 +4,7 @@
4
4
  // default format, written by @shieldfive/crypto (see the end of this file). Same @noble versions as the apps
5
5
  // (@noble/ciphers@2, @noble/hashes@2) so the bytes match.
6
6
 
7
- import { webcrypto } from 'node:crypto'
7
+ import { createHmac, webcrypto } from 'node:crypto'
8
8
 
9
9
  import { gcm } from '@noble/ciphers/aes.js'
10
10
  import { argon2id } from '@noble/hashes/argon2.js'
@@ -282,7 +282,13 @@ export async function* encryptPartsV3({
282
282
  }
283
283
  const header = take(headerLength)
284
284
  const first = await readFrame()
285
- if (!first) throw new Error('Encrypted stream has no chunks.')
285
+ if (!first) {
286
+ // A 0-byte file is a header with no chunk frames (total_chunks 0); it is
287
+ // uploaded as a single header-only part. Anything else is a bug.
288
+ if (plaintextSize !== 0) throw new Error('Encrypted stream has no chunks.')
289
+ yield header
290
+ return
291
+ }
286
292
  const part0 = new Uint8Array(header.length + first.length)
287
293
  part0.set(header, 0)
288
294
  part0.set(first, header.length)
@@ -302,3 +308,21 @@ export async function* encryptPartsV3({
302
308
  export function computeV3UploadProof({ proofKeyHex, part0 }) {
303
309
  return buildUploadProofV3({ proofKeyHex, ciphertext: part0 })
304
310
  }
311
+
312
+ /**
313
+ * Upload proof for a 0-byte file, whose only part is the header. The library's
314
+ * buildUploadProofV3 requires a first chunk frame, which an empty file does not
315
+ * have; the server's empty-file contract (web docs/desktop-empty-file-contract.md,
316
+ * emptyFileUploadProof) is base64([3][3] || HMAC-SHA256(proofKey, [3][3] || header)).
317
+ */
318
+ export function computeV3EmptyUploadProof({ proofKeyHex, header }) {
319
+ if (typeof proofKeyHex !== 'string' || !/^[0-9a-f]{64}$/i.test(proofKeyHex)) {
320
+ throw new Error('Upload session proof key is not 32 bytes of hex.')
321
+ }
322
+ const prefix = Buffer.from([3, 3])
323
+ const mac = createHmac('sha256', Buffer.from(proofKeyHex, 'hex'))
324
+ .update(prefix)
325
+ .update(header)
326
+ .digest()
327
+ return Buffer.concat([prefix, mac]).toString('base64')
328
+ }