@shieldfive/cli 0.3.0 → 0.4.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.
@@ -1,10 +1,10 @@
1
- // ShieldFive CLI — upload field crypto, ported byte-for-byte from the apps
2
- // (mobile/src/features/crypto/encryptionCompat.ts). These produce the fields the
3
- // `create-upload-session` endpoint expects: the wrapped content key, the v4
4
- // filename envelope, and the keyed name hash. Same @noble versions as the apps
1
+ // ShieldFive CLI — upload field crypto. The key wrap, v4 filename envelope and
2
+ // keyed name hash are ported byte-for-byte from the apps
3
+ // (mobile/src/features/crypto/encryptionCompat.ts); the file body is the web's
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'
@@ -12,6 +12,11 @@ import { hmac } from '@noble/hashes/hmac.js'
12
12
  import { sha256 } from '@noble/hashes/sha2.js'
13
13
  import sodium from 'libsodium-wrappers-sumo'
14
14
 
15
+ import { parseHeader } from '@shieldfive/crypto/format'
16
+ import { createIdentity } from '@shieldfive/crypto/identity'
17
+ import { encryptStreamPqHybridV1 } from '@shieldfive/crypto/streams/pq-hybrid-v1'
18
+ import { buildUploadProofV3 } from '@shieldfive/crypto/vault'
19
+
15
20
  // libsodium's Argon2id (crypto_pwhash) is byte-identical to @noble's at the same
16
21
  // params but ~15x faster (native/WASM vs pure JS). It is used for the ENCRYPT
17
22
  // side of the v4 filename metadata — the once-per-file KDF that makes `sf sync`
@@ -43,38 +48,10 @@ export function aesGcmEncrypt(key, iv, plaintext) {
43
48
  return gcm(key, iv).encrypt(plaintext)
44
49
  }
45
50
 
46
- // WebCrypto AES-GCM. Its output is ciphertext||tag with a 16-byte (128-bit)
47
- // tag — byte-identical to @noble's gcm().encrypt for the same key, 12-byte
48
- // nonce and no additional data — so ciphertexts, the SHA-1 digests Backblaze
49
- // checks, and the HMAC upload proof are all unchanged. Native WebCrypto runs
50
- // at ~5 GiB/s versus @noble's ~70 MiB/s, so it is used for the per-chunk file
51
- // encryption (the throughput-bound path). @noble stays for the once-per-file
52
- // key wrap and filename metadata, and for all decryption. It is async because
53
- // subtle.encrypt is; the chunk path (encryptChunkWithDigest) is already async.
54
- async function aesGcmEncryptSubtle(key, iv, plaintext) {
55
- const cryptoKey = await webcrypto.subtle.importKey(
56
- 'raw',
57
- key,
58
- { name: 'AES-GCM' },
59
- false,
60
- ['encrypt'],
61
- )
62
- const ciphertext = await webcrypto.subtle.encrypt(
63
- { name: 'AES-GCM', iv },
64
- cryptoKey,
65
- plaintext,
66
- )
67
- return new Uint8Array(ciphertext)
68
- }
69
-
70
51
  export function generateRandomKeyB64(bytes = 32) {
71
52
  return bytesToBase64(randomBytes(bytes))
72
53
  }
73
54
 
74
- export function generateNoncePrefixB64() {
75
- return bytesToBase64(randomBytes(4))
76
- }
77
-
78
55
  export function wrapKeyB64({ wrappingKeyB64, keyToWrapB64 }) {
79
56
  const iv = randomBytes(12)
80
57
  const ciphertext = aesGcmEncrypt(
@@ -148,9 +125,7 @@ export function decryptMetadataV4(payload, rootKeySecret) {
148
125
  return new TextDecoder().decode(plaintext)
149
126
  }
150
127
 
151
- // ── File chunk encryption (suite 0x01 AES-GCM) + Backblaze upload proof ───────
152
-
153
- const UPLOAD_PROOF_VERSION = 1
128
+ // ── Storage-part digests ────────────────────────────────────────────────────
154
129
 
155
130
  function hexToBytes(hex) {
156
131
  const out = new Uint8Array(hex.length / 2)
@@ -160,89 +135,11 @@ function hexToBytes(hex) {
160
135
  return out
161
136
  }
162
137
 
163
- // nonce = 4-byte random prefix || 8-byte big-endian chunk counter.
164
- export async function encryptFileChunk({ cskB64, noncePrefixB64, chunkIndex, plaintext }) {
165
- const noncePrefix = base64ToBytes(noncePrefixB64)
166
- if (noncePrefix.length !== 4) throw new Error('Invalid nonce prefix')
167
- const nonce = new Uint8Array(12)
168
- nonce.set(noncePrefix, 0)
169
- let counter = BigInt(chunkIndex)
170
- for (let i = 0; i < 8; i += 1) {
171
- nonce[11 - i] = Number(counter & 0xffn)
172
- counter >>= 8n
173
- }
174
- return aesGcmEncryptSubtle(base64ToBytes(cskB64), nonce, plaintext)
175
- }
176
-
177
- function buildUploadProofPrefix({ cipherVersion, chunkSize, noncePrefixBytes }) {
178
- const size = Math.floor(chunkSize)
179
- if (!Number.isFinite(size) || size <= 0) {
180
- throw new Error('Invalid chunk size for upload proof')
181
- }
182
- if (noncePrefixBytes.length !== 4) {
183
- throw new Error('Invalid nonce prefix length for upload proof')
184
- }
185
- const prefix = new Uint8Array(1 + 1 + 4 + 4)
186
- prefix[0] = UPLOAD_PROOF_VERSION
187
- prefix[1] = cipherVersion
188
- new DataView(prefix.buffer).setUint32(2, size, false)
189
- prefix.set(noncePrefixBytes, 6)
190
- return prefix
191
- }
192
-
193
- export function computeAesGcmUploadProof({
194
- proofKeyHex,
195
- cipherVersion,
196
- chunkSize,
197
- noncePrefixB64,
198
- ciphertextChunk,
199
- }) {
200
- const proofKey = hexToBytes(proofKeyHex)
201
- const prefix = buildUploadProofPrefix({
202
- cipherVersion,
203
- chunkSize,
204
- noncePrefixBytes: base64ToBytes(noncePrefixB64),
205
- })
206
- const payload = new Uint8Array(prefix.length + ciphertextChunk.length)
207
- payload.set(prefix, 0)
208
- payload.set(ciphertextChunk, prefix.length)
209
- return bytesToHex(hmac(sha256, proofKey, payload))
210
- }
211
-
212
138
  export async function sha1Hex(bytes) {
213
139
  const digest = await webcrypto.subtle.digest('SHA-1', bytes)
214
140
  return bytesToHex(new Uint8Array(digest))
215
141
  }
216
142
 
217
- // Encrypt one chunk and produce its SHA-1 (for Backblaze) and the upload proof.
218
- export async function encryptChunkWithDigest({
219
- cskB64,
220
- noncePrefixB64,
221
- chunkIndex,
222
- plaintext,
223
- proofKeyHex,
224
- chunkSize,
225
- }) {
226
- const ciphertext = await encryptFileChunk({
227
- cskB64,
228
- noncePrefixB64,
229
- chunkIndex,
230
- plaintext,
231
- })
232
- const digest = await sha1Hex(ciphertext)
233
- const proofHex =
234
- proofKeyHex && chunkSize
235
- ? computeAesGcmUploadProof({
236
- proofKeyHex,
237
- cipherVersion: 1,
238
- chunkSize,
239
- noncePrefixB64,
240
- ciphertextChunk: ciphertext,
241
- })
242
- : undefined
243
- return { ciphertext, sha1Hex: digest, proofHex }
244
- }
245
-
246
143
  // Multipart ciphertextHash — the value `complete-upload` checks against the
247
144
  // server's own computeLargeFileSha1. One part: the part's SHA-1, lowercased.
248
145
  // Many parts: SHA-1 over the concatenated raw 20-byte part digests (NOT the
@@ -262,3 +159,170 @@ export async function getCiphertextHashFromParts(partSha1Array) {
262
159
  }
263
160
  return sha1Hex(bytes)
264
161
  }
162
+
163
+ // ── File encryption, v1 wire format, suite 0x03 (cipher_version 3) ───────────
164
+ //
165
+ // What the web app writes by default (encryptModal.tsx, `v1-pq-hybrid`), using
166
+ // the same @shieldfive/crypto stream encoder: a MAC'd header carrying
167
+ // plaintext_size and total_chunks, chunk AAD binding index/total/is_final (so a
168
+ // dropped or reordered chunk fails to decrypt), file_id = the server row id (so
169
+ // the blob cannot be moved onto another row), and ML-KEM-1024 + X25519 hybrid
170
+ // key encapsulation to the owner's vault identity.
171
+ //
172
+ // This replaces the legacy v0 writer (suite 0x01 chunks under a random 4-byte
173
+ // nonce prefix, no header): no truncation detection, no file binding, no PQ.
174
+ // The spec (crypto spec/format-v0.md) forbids new v0 writes.
175
+
176
+ export const V1_CHUNK_SIZE = 5 * 1024 * 1024
177
+ export const CIPHER_VERSION_PQ = 3
178
+ const FRAME_LENGTH_BYTES = 4
179
+
180
+ export function uuidToBytes(id) {
181
+ const hex = String(id).replace(/-/g, '')
182
+ if (!/^[0-9a-f]{32}$/i.test(hex)) throw new Error(`Not a UUID: ${id}`)
183
+ return hexToBytes(hex.toLowerCase())
184
+ }
185
+
186
+ // The owner's ML-KEM public key, derived from the root key exactly as the web
187
+ // keyring does (utils/pqIdentity.ts: createIdentity with the root key as the
188
+ // master secret; userId does not affect the key bytes). Derived locally, never
189
+ // taken from the server, so a server cannot substitute a recipient. Cached by a
190
+ // hash of the root key: the public key is not secret, the derivation is not free.
191
+ const identityCache = new Map()
192
+ export async function vaultMlKemPublicKey(rootKey) {
193
+ const id = bytesToHex(sha256(rootKey))
194
+ let pk = identityCache.get(id)
195
+ if (!pk) {
196
+ const identity = await createIdentity({ userId: 'shieldfive-cli', masterSecret: rootKey })
197
+ identity.mlKemSecretKey?.fill?.(0)
198
+ pk = identity.publicBundle.mlKemPublicKey
199
+ identityCache.set(id, pk)
200
+ }
201
+ return pk
202
+ }
203
+
204
+ function toReadableStream(iterable) {
205
+ const it = iterable[Symbol.asyncIterator]()
206
+ return new ReadableStream({
207
+ async pull(controller) {
208
+ const { value, done } = await it.next()
209
+ if (done) controller.close()
210
+ else controller.enqueue(value)
211
+ },
212
+ async cancel() {
213
+ await it.return?.()
214
+ },
215
+ })
216
+ }
217
+
218
+ /**
219
+ * Encrypt a plaintext chunk stream as one suite-0x03 object and yield it as
220
+ * storage parts: part 0 is `header || frame_0`, part i is `frame_i`. That is the
221
+ * layout the server's proof verifier and the web uploader use (one encrypted
222
+ * chunk per storage part). The split is made from the bytes themselves (header
223
+ * length, then each frame's length prefix), not from how the encoder happens
224
+ * to enqueue its output.
225
+ */
226
+ export async function* encryptPartsV3({
227
+ plaintextChunks,
228
+ plaintextSize,
229
+ chunkSize,
230
+ envelopeKey,
231
+ fileId,
232
+ recipientPublicKey,
233
+ }) {
234
+ const { ciphertext, combinedKey } = await encryptStreamPqHybridV1(toReadableStream(plaintextChunks), {
235
+ recipientPublicKey,
236
+ envelopeKey,
237
+ plaintextSize,
238
+ chunkSize,
239
+ fileId,
240
+ })
241
+ // combinedKey is used by the stream while it runs; wiped in the finally below.
242
+
243
+ const reader = ciphertext.getReader()
244
+ let buf = new Uint8Array(0)
245
+ let done = false
246
+ const pull = async () => {
247
+ const r = await reader.read()
248
+ if (r.done) {
249
+ done = true
250
+ return
251
+ }
252
+ const next = new Uint8Array(buf.length + r.value.length)
253
+ next.set(buf, 0)
254
+ next.set(r.value, buf.length)
255
+ buf = next
256
+ }
257
+ const take = (n) => {
258
+ const out = buf.slice(0, n)
259
+ buf = buf.slice(n)
260
+ return out
261
+ }
262
+ const readFrame = async () => {
263
+ while (buf.length < FRAME_LENGTH_BYTES && !done) await pull()
264
+ if (buf.length === 0 && done) return null
265
+ if (buf.length < FRAME_LENGTH_BYTES) throw new Error('Encrypted stream ended inside a chunk frame.')
266
+ const len = new DataView(buf.buffer, buf.byteOffset, buf.byteLength).getUint32(0, false)
267
+ while (buf.length < FRAME_LENGTH_BYTES + len && !done) await pull()
268
+ if (buf.length < FRAME_LENGTH_BYTES + len) throw new Error('Encrypted stream ended inside a chunk frame.')
269
+ return take(FRAME_LENGTH_BYTES + len)
270
+ }
271
+
272
+ try {
273
+ // Header: parse as soon as enough bytes are buffered.
274
+ let headerLength = null
275
+ while (headerLength === null) {
276
+ try {
277
+ headerLength = parseHeader(buf).headerLength
278
+ } catch (err) {
279
+ if (done) throw err
280
+ await pull()
281
+ }
282
+ }
283
+ const header = take(headerLength)
284
+ const first = await readFrame()
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
+ }
292
+ const part0 = new Uint8Array(header.length + first.length)
293
+ part0.set(header, 0)
294
+ part0.set(first, header.length)
295
+ yield part0
296
+ for (;;) {
297
+ const frame = await readFrame()
298
+ if (!frame) break
299
+ yield frame
300
+ }
301
+ } finally {
302
+ reader.releaseLock()
303
+ combinedKey.fill(0)
304
+ }
305
+ }
306
+
307
+ /** The suite-0x03 upload proof, from the library both other writers use. */
308
+ export function computeV3UploadProof({ proofKeyHex, part0 }) {
309
+ return buildUploadProofV3({ proofKeyHex, ciphertext: part0 })
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
+ }