@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.
- package/CHANGELOG.md +84 -0
- package/README.md +79 -33
- package/package.json +6 -3
- package/src/agent/server.mjs +4 -2
- package/src/argon2.mjs +69 -0
- package/src/auth.mjs +46 -6
- package/src/authPin.mjs +95 -0
- package/src/cli.mjs +79 -24
- package/src/loginSecret.mjs +72 -0
- package/src/migrationInventory.mjs +45 -0
- package/src/sync.mjs +78 -12
- package/src/unlock.mjs +32 -16
- package/src/upload.mjs +216 -68
- package/src/uploadCrypto.mjs +178 -114
package/src/uploadCrypto.mjs
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
// ShieldFive CLI — upload field crypto,
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
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
|
-
// ──
|
|
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
|
+
}
|