@terreno/syncdb 56.0.0-beta.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/README.md +419 -0
- package/dist/auth/betterAuthAdapter.d.ts +22 -0
- package/dist/auth/betterAuthAdapter.d.ts.map +1 -0
- package/dist/auth/betterAuthAdapter.js +181 -0
- package/dist/auth/betterAuthAdapter.js.map +1 -0
- package/dist/auth/betterAuthAdapter.test.d.ts +2 -0
- package/dist/auth/betterAuthAdapter.test.d.ts.map +1 -0
- package/dist/auth/betterAuthAdapter.test.js +350 -0
- package/dist/auth/betterAuthAdapter.test.js.map +1 -0
- package/dist/auth/types.d.ts +42 -0
- package/dist/auth/types.d.ts.map +1 -0
- package/dist/auth/types.js +9 -0
- package/dist/auth/types.js.map +1 -0
- package/dist/client.d.ts +246 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +1415 -0
- package/dist/client.js.map +1 -0
- package/dist/client.test.d.ts +2 -0
- package/dist/client.test.d.ts.map +1 -0
- package/dist/client.test.js +2310 -0
- package/dist/client.test.js.map +1 -0
- package/dist/crypto/aesGcmCodec.d.ts +33 -0
- package/dist/crypto/aesGcmCodec.d.ts.map +1 -0
- package/dist/crypto/aesGcmCodec.js +80 -0
- package/dist/crypto/aesGcmCodec.js.map +1 -0
- package/dist/crypto/aesGcmCodec.test.d.ts +2 -0
- package/dist/crypto/aesGcmCodec.test.d.ts.map +1 -0
- package/dist/crypto/aesGcmCodec.test.js +83 -0
- package/dist/crypto/aesGcmCodec.test.js.map +1 -0
- package/dist/crypto/identityCodec.d.ts +7 -0
- package/dist/crypto/identityCodec.d.ts.map +1 -0
- package/dist/crypto/identityCodec.js +9 -0
- package/dist/crypto/identityCodec.js.map +1 -0
- package/dist/crypto/keyProviders.d.ts +34 -0
- package/dist/crypto/keyProviders.d.ts.map +1 -0
- package/dist/crypto/keyProviders.js +102 -0
- package/dist/crypto/keyProviders.js.map +1 -0
- package/dist/crypto/keyProviders.test.d.ts +2 -0
- package/dist/crypto/keyProviders.test.d.ts.map +1 -0
- package/dist/crypto/keyProviders.test.js +189 -0
- package/dist/crypto/keyProviders.test.js.map +1 -0
- package/dist/crypto/types.d.ts +24 -0
- package/dist/crypto/types.d.ts.map +1 -0
- package/dist/crypto/types.js +8 -0
- package/dist/crypto/types.js.map +1 -0
- package/dist/debug/debugChannel.d.ts +52 -0
- package/dist/debug/debugChannel.d.ts.map +1 -0
- package/dist/debug/debugChannel.js +73 -0
- package/dist/debug/debugChannel.js.map +1 -0
- package/dist/debug/debugChannel.test.d.ts +2 -0
- package/dist/debug/debugChannel.test.d.ts.map +1 -0
- package/dist/debug/debugChannel.test.js +105 -0
- package/dist/debug/debugChannel.test.js.map +1 -0
- package/dist/debug/debugLog.d.ts +111 -0
- package/dist/debug/debugLog.d.ts.map +1 -0
- package/dist/debug/debugLog.js +150 -0
- package/dist/debug/debugLog.js.map +1 -0
- package/dist/debug/debugLog.test.d.ts +2 -0
- package/dist/debug/debugLog.test.d.ts.map +1 -0
- package/dist/debug/debugLog.test.js +121 -0
- package/dist/debug/debugLog.test.js.map +1 -0
- package/dist/index.d.ts +46 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +51 -0
- package/dist/index.js.map +1 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts +2 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts.map +1 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.js +38 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.js.map +1 -0
- package/dist/mutations/conflicts.d.ts +31 -0
- package/dist/mutations/conflicts.d.ts.map +1 -0
- package/dist/mutations/conflicts.js +73 -0
- package/dist/mutations/conflicts.js.map +1 -0
- package/dist/mutations/outbox.d.ts +174 -0
- package/dist/mutations/outbox.d.ts.map +1 -0
- package/dist/mutations/outbox.js +385 -0
- package/dist/mutations/outbox.js.map +1 -0
- package/dist/mutations/outbox.test.d.ts +2 -0
- package/dist/mutations/outbox.test.d.ts.map +1 -0
- package/dist/mutations/outbox.test.js +643 -0
- package/dist/mutations/outbox.test.js.map +1 -0
- package/dist/mutations/resolveConflict.d.ts +32 -0
- package/dist/mutations/resolveConflict.d.ts.map +1 -0
- package/dist/mutations/resolveConflict.js +101 -0
- package/dist/mutations/resolveConflict.js.map +1 -0
- package/dist/mutations/resolveConflict.test.d.ts +2 -0
- package/dist/mutations/resolveConflict.test.d.ts.map +1 -0
- package/dist/mutations/resolveConflict.test.js +282 -0
- package/dist/mutations/resolveConflict.test.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.d.ts +9 -0
- package/dist/persisters/defaultPersisterFactory.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.js +9 -0
- package/dist/persisters/defaultPersisterFactory.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.native.d.ts +10 -0
- package/dist/persisters/defaultPersisterFactory.native.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.native.js +44 -0
- package/dist/persisters/defaultPersisterFactory.native.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.test.d.ts +2 -0
- package/dist/persisters/defaultPersisterFactory.test.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.test.js +177 -0
- package/dist/persisters/defaultPersisterFactory.test.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.web.d.ts +17 -0
- package/dist/persisters/defaultPersisterFactory.web.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.web.js +65 -0
- package/dist/persisters/defaultPersisterFactory.web.js.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.d.ts +46 -0
- package/dist/persisters/encryptedIndexedDbPersister.d.ts.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.js +171 -0
- package/dist/persisters/encryptedIndexedDbPersister.js.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.d.ts +2 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.d.ts.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.js +352 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.js.map +1 -0
- package/dist/persisters/memoryPersister.d.ts +19 -0
- package/dist/persisters/memoryPersister.d.ts.map +1 -0
- package/dist/persisters/memoryPersister.js +31 -0
- package/dist/persisters/memoryPersister.js.map +1 -0
- package/dist/persisters/memoryPersister.test.d.ts +2 -0
- package/dist/persisters/memoryPersister.test.d.ts.map +1 -0
- package/dist/persisters/memoryPersister.test.js +113 -0
- package/dist/persisters/memoryPersister.test.js.map +1 -0
- package/dist/persisters/types.d.ts +65 -0
- package/dist/persisters/types.d.ts.map +1 -0
- package/dist/persisters/types.js +2 -0
- package/dist/persisters/types.js.map +1 -0
- package/dist/react/hooks.d.ts +132 -0
- package/dist/react/hooks.d.ts.map +1 -0
- package/dist/react/hooks.js +269 -0
- package/dist/react/hooks.js.map +1 -0
- package/dist/react/hooks.test.d.ts +2 -0
- package/dist/react/hooks.test.d.ts.map +1 -0
- package/dist/react/hooks.test.js +645 -0
- package/dist/react/hooks.test.js.map +1 -0
- package/dist/react/index.d.ts +11 -0
- package/dist/react/index.d.ts.map +1 -0
- package/dist/react/index.js +11 -0
- package/dist/react/index.js.map +1 -0
- package/dist/react/provider.d.ts +11 -0
- package/dist/react/provider.d.ts.map +1 -0
- package/dist/react/provider.js +17 -0
- package/dist/react/provider.js.map +1 -0
- package/dist/storage/idb.d.ts +27 -0
- package/dist/storage/idb.d.ts.map +1 -0
- package/dist/storage/idb.js +72 -0
- package/dist/storage/idb.js.map +1 -0
- package/dist/storage/idb.test.d.ts +2 -0
- package/dist/storage/idb.test.d.ts.map +1 -0
- package/dist/storage/idb.test.js +100 -0
- package/dist/storage/idb.test.js.map +1 -0
- package/dist/storage/purgeUnknownStream.test.d.ts +2 -0
- package/dist/storage/purgeUnknownStream.test.d.ts.map +1 -0
- package/dist/storage/purgeUnknownStream.test.js +64 -0
- package/dist/storage/purgeUnknownStream.test.js.map +1 -0
- package/dist/storage/schema.d.ts +33 -0
- package/dist/storage/schema.d.ts.map +1 -0
- package/dist/storage/schema.js +92 -0
- package/dist/storage/schema.js.map +1 -0
- package/dist/storage/store.d.ts +136 -0
- package/dist/storage/store.d.ts.map +1 -0
- package/dist/storage/store.js +275 -0
- package/dist/storage/store.js.map +1 -0
- package/dist/storage/store.test.d.ts +2 -0
- package/dist/storage/store.test.d.ts.map +1 -0
- package/dist/storage/store.test.js +357 -0
- package/dist/storage/store.test.js.map +1 -0
- package/dist/storage/types.d.ts +146 -0
- package/dist/storage/types.d.ts.map +1 -0
- package/dist/storage/types.js +32 -0
- package/dist/storage/types.js.map +1 -0
- package/dist/storage/wipe.d.ts +22 -0
- package/dist/storage/wipe.d.ts.map +1 -0
- package/dist/storage/wipe.js +43 -0
- package/dist/storage/wipe.js.map +1 -0
- package/dist/storage/wipe.test.d.ts +2 -0
- package/dist/storage/wipe.test.d.ts.map +1 -0
- package/dist/storage/wipe.test.js +95 -0
- package/dist/storage/wipe.test.js.map +1 -0
- package/dist/sync/bootstrap.d.ts +64 -0
- package/dist/sync/bootstrap.d.ts.map +1 -0
- package/dist/sync/bootstrap.js +160 -0
- package/dist/sync/bootstrap.js.map +1 -0
- package/dist/sync/bootstrap.test.d.ts +2 -0
- package/dist/sync/bootstrap.test.d.ts.map +1 -0
- package/dist/sync/bootstrap.test.js +447 -0
- package/dist/sync/bootstrap.test.js.map +1 -0
- package/dist/sync/cursor.d.ts +67 -0
- package/dist/sync/cursor.d.ts.map +1 -0
- package/dist/sync/cursor.js +74 -0
- package/dist/sync/cursor.js.map +1 -0
- package/dist/sync/cursor.test.d.ts +2 -0
- package/dist/sync/cursor.test.d.ts.map +1 -0
- package/dist/sync/cursor.test.js +73 -0
- package/dist/sync/cursor.test.js.map +1 -0
- package/dist/sync/deltaApplier.d.ts +30 -0
- package/dist/sync/deltaApplier.d.ts.map +1 -0
- package/dist/sync/deltaApplier.js +61 -0
- package/dist/sync/deltaApplier.js.map +1 -0
- package/dist/sync/deltaApplier.test.d.ts +2 -0
- package/dist/sync/deltaApplier.test.d.ts.map +1 -0
- package/dist/sync/deltaApplier.test.js +212 -0
- package/dist/sync/deltaApplier.test.js.map +1 -0
- package/dist/sync/entityRepair.d.ts +45 -0
- package/dist/sync/entityRepair.d.ts.map +1 -0
- package/dist/sync/entityRepair.js +91 -0
- package/dist/sync/entityRepair.js.map +1 -0
- package/dist/sync/entityRepair.test.d.ts +2 -0
- package/dist/sync/entityRepair.test.d.ts.map +1 -0
- package/dist/sync/entityRepair.test.js +146 -0
- package/dist/sync/entityRepair.test.js.map +1 -0
- package/dist/sync/httpChannel.d.ts +74 -0
- package/dist/sync/httpChannel.d.ts.map +1 -0
- package/dist/sync/httpChannel.js +123 -0
- package/dist/sync/httpChannel.js.map +1 -0
- package/dist/sync/httpChannel.test.d.ts +2 -0
- package/dist/sync/httpChannel.test.d.ts.map +1 -0
- package/dist/sync/httpChannel.test.js +215 -0
- package/dist/sync/httpChannel.test.js.map +1 -0
- package/dist/sync/replayCoordinator.d.ts +212 -0
- package/dist/sync/replayCoordinator.d.ts.map +1 -0
- package/dist/sync/replayCoordinator.js +1110 -0
- package/dist/sync/replayCoordinator.js.map +1 -0
- package/dist/sync/replayCoordinator.test.d.ts +2 -0
- package/dist/sync/replayCoordinator.test.d.ts.map +1 -0
- package/dist/sync/replayCoordinator.test.js +1496 -0
- package/dist/sync/replayCoordinator.test.js.map +1 -0
- package/dist/sync/socketTransport.d.ts +56 -0
- package/dist/sync/socketTransport.d.ts.map +1 -0
- package/dist/sync/socketTransport.js +292 -0
- package/dist/sync/socketTransport.js.map +1 -0
- package/dist/sync/socketTransport.test.d.ts +2 -0
- package/dist/sync/socketTransport.test.d.ts.map +1 -0
- package/dist/sync/socketTransport.test.js +346 -0
- package/dist/sync/socketTransport.test.js.map +1 -0
- package/dist/sync/transport.d.ts +80 -0
- package/dist/sync/transport.d.ts.map +1 -0
- package/dist/sync/transport.js +5 -0
- package/dist/sync/transport.js.map +1 -0
- package/dist/testing/fakeTransport.d.ts +55 -0
- package/dist/testing/fakeTransport.d.ts.map +1 -0
- package/dist/testing/fakeTransport.js +139 -0
- package/dist/testing/fakeTransport.js.map +1 -0
- package/dist/testing/fakeTransport.test.d.ts +2 -0
- package/dist/testing/fakeTransport.test.d.ts.map +1 -0
- package/dist/testing/fakeTransport.test.js +112 -0
- package/dist/testing/fakeTransport.test.js.map +1 -0
- package/dist/testing/index.d.ts +13 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +13 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/types.d.ts +271 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +9 -0
- package/dist/types.js.map +1 -0
- package/package.json +71 -0
- package/src/auth/betterAuthAdapter.test.ts +455 -0
- package/src/auth/betterAuthAdapter.ts +214 -0
- package/src/auth/types.ts +49 -0
- package/src/client.test.ts +2670 -0
- package/src/client.ts +1748 -0
- package/src/crypto/aesGcmCodec.test.ts +103 -0
- package/src/crypto/aesGcmCodec.ts +98 -0
- package/src/crypto/identityCodec.ts +10 -0
- package/src/crypto/keyProviders.test.ts +228 -0
- package/src/crypto/keyProviders.ts +153 -0
- package/src/crypto/types.ts +23 -0
- package/src/debug/debugChannel.test.ts +121 -0
- package/src/debug/debugChannel.ts +112 -0
- package/src/debug/debugLog.test.ts +139 -0
- package/src/debug/debugLog.ts +272 -0
- package/src/index.ts +157 -0
- package/src/isolated/defaultPersisterFactoryNative.isolated.ts +45 -0
- package/src/mutations/conflicts.ts +108 -0
- package/src/mutations/outbox.test.ts +754 -0
- package/src/mutations/outbox.ts +585 -0
- package/src/mutations/resolveConflict.test.ts +338 -0
- package/src/mutations/resolveConflict.ts +115 -0
- package/src/persisters/defaultPersisterFactory.native.ts +53 -0
- package/src/persisters/defaultPersisterFactory.test.ts +207 -0
- package/src/persisters/defaultPersisterFactory.ts +12 -0
- package/src/persisters/defaultPersisterFactory.web.ts +78 -0
- package/src/persisters/encryptedIndexedDbPersister.test.ts +381 -0
- package/src/persisters/encryptedIndexedDbPersister.ts +218 -0
- package/src/persisters/memoryPersister.test.ts +136 -0
- package/src/persisters/memoryPersister.ts +52 -0
- package/src/persisters/types.ts +71 -0
- package/src/react/hooks.test.tsx +761 -0
- package/src/react/hooks.ts +409 -0
- package/src/react/index.ts +11 -0
- package/src/react/provider.tsx +27 -0
- package/src/storage/idb.test.ts +116 -0
- package/src/storage/idb.ts +112 -0
- package/src/storage/purgeUnknownStream.test.ts +74 -0
- package/src/storage/schema.ts +103 -0
- package/src/storage/store.test.ts +424 -0
- package/src/storage/store.ts +461 -0
- package/src/storage/types.ts +159 -0
- package/src/storage/wipe.test.ts +111 -0
- package/src/storage/wipe.ts +58 -0
- package/src/sync/bootstrap.test.ts +486 -0
- package/src/sync/bootstrap.ts +217 -0
- package/src/sync/cursor.test.ts +84 -0
- package/src/sync/cursor.ts +113 -0
- package/src/sync/deltaApplier.test.ts +237 -0
- package/src/sync/deltaApplier.ts +84 -0
- package/src/sync/entityRepair.test.ts +161 -0
- package/src/sync/entityRepair.ts +124 -0
- package/src/sync/httpChannel.test.ts +265 -0
- package/src/sync/httpChannel.ts +220 -0
- package/src/sync/replayCoordinator.test.ts +1709 -0
- package/src/sync/replayCoordinator.ts +1370 -0
- package/src/sync/socketTransport.test.ts +413 -0
- package/src/sync/socketTransport.ts +379 -0
- package/src/sync/transport.ts +76 -0
- package/src/testing/fakeTransport.test.ts +125 -0
- package/src/testing/fakeTransport.ts +206 -0
- package/src/testing/index.ts +18 -0
- package/src/types.ts +284 -0
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import {describe, expect, it} from "bun:test";
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
AES_GCM_ENVELOPE_VERSION,
|
|
5
|
+
createAesGcmCodec,
|
|
6
|
+
getSubtleCrypto,
|
|
7
|
+
PayloadIntegrityError,
|
|
8
|
+
UnknownEnvelopeVersionError,
|
|
9
|
+
} from "./aesGcmCodec";
|
|
10
|
+
import {identityCodec} from "./identityCodec";
|
|
11
|
+
|
|
12
|
+
const generateKey = (): Promise<CryptoKey> =>
|
|
13
|
+
crypto.subtle.generateKey({length: 256, name: "AES-GCM"}, false, ["encrypt", "decrypt"]);
|
|
14
|
+
|
|
15
|
+
describe("createAesGcmCodec", () => {
|
|
16
|
+
it("round-trips plaintext including unicode", async () => {
|
|
17
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
18
|
+
const plaintext = JSON.stringify({emoji: "🔐", note: "héllo wörld", value: 42});
|
|
19
|
+
const payload = await codec.encode(plaintext);
|
|
20
|
+
expect(payload).toBeInstanceOf(Uint8Array);
|
|
21
|
+
expect(await codec.decode(payload)).toBe(plaintext);
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
it("writes the versioned envelope: version byte + 12-byte IV + ciphertext", async () => {
|
|
25
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
26
|
+
const payload = await codec.encode("x");
|
|
27
|
+
expect(payload[0]).toBe(AES_GCM_ENVELOPE_VERSION);
|
|
28
|
+
// 1 version + 12 IV + 1 plaintext byte + 16 GCM tag
|
|
29
|
+
expect(payload.length).toBe(1 + 12 + 1 + 16);
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
it("never exposes plaintext in the payload bytes", async () => {
|
|
33
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
34
|
+
const payload = await codec.encode("SECRET_MARKER_XYZ");
|
|
35
|
+
const asLatin1 = String.fromCharCode(...payload);
|
|
36
|
+
expect(asLatin1).not.toContain("SECRET_MARKER_XYZ");
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
it("uses a fresh IV per encryption (distinct payloads for identical plaintext)", async () => {
|
|
40
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
41
|
+
const a = await codec.encode("same plaintext");
|
|
42
|
+
const b = await codec.encode("same plaintext");
|
|
43
|
+
expect(Buffer.from(a).equals(Buffer.from(b))).toBe(false);
|
|
44
|
+
expect(Buffer.from(a.subarray(1, 13)).equals(Buffer.from(b.subarray(1, 13)))).toBe(false);
|
|
45
|
+
expect(await codec.decode(a)).toBe("same plaintext");
|
|
46
|
+
expect(await codec.decode(b)).toBe("same plaintext");
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
it("throws PayloadIntegrityError on a tampered ciphertext byte", async () => {
|
|
50
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
51
|
+
const payload = await codec.encode("important data");
|
|
52
|
+
payload[payload.length - 1] = (payload[payload.length - 1] as number) ^ 0xff;
|
|
53
|
+
expect(codec.decode(payload)).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
it("throws PayloadIntegrityError when decrypting with the wrong key", async () => {
|
|
57
|
+
const codecA = createAesGcmCodec({key: await generateKey()});
|
|
58
|
+
const codecB = createAesGcmCodec({key: await generateKey()});
|
|
59
|
+
const payload = await codecA.encode("important data");
|
|
60
|
+
expect(codecB.decode(payload)).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
it("throws UnknownEnvelopeVersionError for an unknown version byte", async () => {
|
|
64
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
65
|
+
const payload = await codec.encode("important data");
|
|
66
|
+
payload[0] = 9;
|
|
67
|
+
const error = await codec.decode(payload).catch((e: unknown) => e);
|
|
68
|
+
expect(error).toBeInstanceOf(UnknownEnvelopeVersionError);
|
|
69
|
+
// Distinguishable from tampering so callers can branch on the failure mode.
|
|
70
|
+
expect(error).not.toBeInstanceOf(PayloadIntegrityError);
|
|
71
|
+
expect((error as Error).message).toContain("9");
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
it("throws PayloadIntegrityError for an empty payload", async () => {
|
|
75
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
76
|
+
expect(codec.decode(new Uint8Array(0))).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
it("throws PayloadIntegrityError for a truncated payload", async () => {
|
|
80
|
+
const codec = createAesGcmCodec({key: await generateKey()});
|
|
81
|
+
const payload = await codec.encode("important data");
|
|
82
|
+
expect(codec.decode(payload.subarray(0, 10))).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
83
|
+
});
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
describe("identityCodec", () => {
|
|
87
|
+
it("round-trips without encryption", async () => {
|
|
88
|
+
const payload = await identityCodec.encode("plain ✨ text");
|
|
89
|
+
expect(payload).toBeInstanceOf(Uint8Array);
|
|
90
|
+
expect(await identityCodec.decode(payload)).toBe("plain ✨ text");
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
it("stores the plaintext bytes verbatim (opt-out of encryption)", async () => {
|
|
94
|
+
const payload = await identityCodec.encode("visible");
|
|
95
|
+
expect(new TextDecoder().decode(payload)).toBe("visible");
|
|
96
|
+
});
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
describe("getSubtleCrypto", () => {
|
|
100
|
+
it("returns the platform SubtleCrypto when available", () => {
|
|
101
|
+
expect(getSubtleCrypto()).toBe(crypto.subtle);
|
|
102
|
+
});
|
|
103
|
+
});
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type {PayloadCodec} from "./types";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Envelope layout (binary): `[1 version byte][12-byte IV][ciphertext + GCM tag]`.
|
|
5
|
+
* The version byte lets future envelope changes (new cipher, KDF, chunking)
|
|
6
|
+
* coexist with already-persisted blobs.
|
|
7
|
+
*/
|
|
8
|
+
export const AES_GCM_ENVELOPE_VERSION = 1;
|
|
9
|
+
|
|
10
|
+
const IV_BYTES = 12;
|
|
11
|
+
/** AES-GCM appends a 16-byte authentication tag to every ciphertext. */
|
|
12
|
+
const GCM_TAG_BYTES = 16;
|
|
13
|
+
|
|
14
|
+
/** Thrown when a persisted payload declares an envelope version this build cannot read. */
|
|
15
|
+
export class UnknownEnvelopeVersionError extends Error {
|
|
16
|
+
constructor(version: number) {
|
|
17
|
+
super(`Unknown syncdb payload envelope version: ${version}`);
|
|
18
|
+
this.name = "UnknownEnvelopeVersionError";
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Thrown when a payload is truncated or fails AES-GCM authentication (tampered
|
|
24
|
+
* ciphertext, wrong key, or corrupt storage).
|
|
25
|
+
*/
|
|
26
|
+
export class PayloadIntegrityError extends Error {
|
|
27
|
+
constructor(message: string, options?: {cause?: unknown}) {
|
|
28
|
+
super(message, options);
|
|
29
|
+
this.name = "PayloadIntegrityError";
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// Newer TS DOM libs type `BufferSource` as ArrayBuffer-backed while `Uint8Array`
|
|
34
|
+
// is `ArrayBufferLike`-backed; this bridges the mismatch for WebCrypto calls.
|
|
35
|
+
const asBufferSource = (bytes: Uint8Array): BufferSource => bytes as unknown as BufferSource;
|
|
36
|
+
|
|
37
|
+
/** WebCrypto SubtleCrypto, or a loud failure on platforms without it. */
|
|
38
|
+
export const getSubtleCrypto = (): SubtleCrypto => {
|
|
39
|
+
const subtle = globalThis.crypto?.subtle;
|
|
40
|
+
if (!subtle) {
|
|
41
|
+
throw new Error("WebCrypto SubtleCrypto is unavailable in this environment");
|
|
42
|
+
}
|
|
43
|
+
return subtle;
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* AES-256-GCM payload codec over WebCrypto. Every encode uses a fresh random
|
|
48
|
+
* 12-byte IV; the result is a versioned binary envelope. Decode distinguishes
|
|
49
|
+
* unknown envelope versions ({@link UnknownEnvelopeVersionError}) from
|
|
50
|
+
* tampered/undecryptable payloads ({@link PayloadIntegrityError}) so callers
|
|
51
|
+
* can react differently (migration vs. wipe-and-rebootstrap).
|
|
52
|
+
*/
|
|
53
|
+
export const createAesGcmCodec = ({key}: {key: CryptoKey}): PayloadCodec => {
|
|
54
|
+
const encode = async (plaintext: string): Promise<Uint8Array> => {
|
|
55
|
+
const subtle = getSubtleCrypto();
|
|
56
|
+
const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
|
|
57
|
+
const ciphertext = new Uint8Array(
|
|
58
|
+
await subtle.encrypt(
|
|
59
|
+
{iv: asBufferSource(iv), name: "AES-GCM"},
|
|
60
|
+
key,
|
|
61
|
+
asBufferSource(new TextEncoder().encode(plaintext))
|
|
62
|
+
)
|
|
63
|
+
);
|
|
64
|
+
const envelope = new Uint8Array(1 + IV_BYTES + ciphertext.length);
|
|
65
|
+
envelope[0] = AES_GCM_ENVELOPE_VERSION;
|
|
66
|
+
envelope.set(iv, 1);
|
|
67
|
+
envelope.set(ciphertext, 1 + IV_BYTES);
|
|
68
|
+
return envelope;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
const decode = async (payload: Uint8Array): Promise<string> => {
|
|
72
|
+
if (payload.length === 0) {
|
|
73
|
+
throw new PayloadIntegrityError("Empty payload");
|
|
74
|
+
}
|
|
75
|
+
if (payload[0] !== AES_GCM_ENVELOPE_VERSION) {
|
|
76
|
+
throw new UnknownEnvelopeVersionError(payload[0] as number);
|
|
77
|
+
}
|
|
78
|
+
if (payload.length < 1 + IV_BYTES + GCM_TAG_BYTES) {
|
|
79
|
+
throw new PayloadIntegrityError("Truncated payload");
|
|
80
|
+
}
|
|
81
|
+
const subtle = getSubtleCrypto();
|
|
82
|
+
const iv = payload.subarray(1, 1 + IV_BYTES);
|
|
83
|
+
const ciphertext = payload.subarray(1 + IV_BYTES);
|
|
84
|
+
let plaintext: ArrayBuffer;
|
|
85
|
+
try {
|
|
86
|
+
plaintext = await subtle.decrypt(
|
|
87
|
+
{iv: asBufferSource(iv), name: "AES-GCM"},
|
|
88
|
+
key,
|
|
89
|
+
asBufferSource(ciphertext)
|
|
90
|
+
);
|
|
91
|
+
} catch (error) {
|
|
92
|
+
throw new PayloadIntegrityError("Payload failed AES-GCM authentication", {cause: error});
|
|
93
|
+
}
|
|
94
|
+
return new TextDecoder().decode(plaintext);
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
return {decode, encode};
|
|
98
|
+
};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type {PayloadCodec} from "./types";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* No-op codec: UTF-8 bytes with no encryption. For tests and explicit opt-out
|
|
5
|
+
* of encryption at rest; never the default on web.
|
|
6
|
+
*/
|
|
7
|
+
export const identityCodec: PayloadCodec = {
|
|
8
|
+
decode: async (payload: Uint8Array): Promise<string> => new TextDecoder().decode(payload),
|
|
9
|
+
encode: async (plaintext: string): Promise<Uint8Array> => new TextEncoder().encode(plaintext),
|
|
10
|
+
};
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
import "fake-indexeddb/auto";
|
|
2
|
+
|
|
3
|
+
import {describe, expect, it, mock} from "bun:test";
|
|
4
|
+
|
|
5
|
+
import {idbGet} from "../storage/idb";
|
|
6
|
+
import {createAesGcmCodec, PayloadIntegrityError} from "./aesGcmCodec";
|
|
7
|
+
import {
|
|
8
|
+
createKeyProviderCodec,
|
|
9
|
+
createLocalKeyProvider,
|
|
10
|
+
createServerKeyProvider,
|
|
11
|
+
} from "./keyProviders";
|
|
12
|
+
import type {KeyProvider} from "./types";
|
|
13
|
+
|
|
14
|
+
let dbCounter = 0;
|
|
15
|
+
const uniqueDbName = (): string => `key-cache-test-${Date.now()}-${dbCounter++}`;
|
|
16
|
+
|
|
17
|
+
const randomMaterialBase64 = (): string =>
|
|
18
|
+
Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64");
|
|
19
|
+
|
|
20
|
+
const roundTripAcrossKeys = async ({
|
|
21
|
+
decryptKey,
|
|
22
|
+
encryptKey,
|
|
23
|
+
}: {
|
|
24
|
+
decryptKey: CryptoKey;
|
|
25
|
+
encryptKey: CryptoKey;
|
|
26
|
+
}): Promise<string> => {
|
|
27
|
+
const payload = await createAesGcmCodec({key: encryptKey}).encode("cross-key payload");
|
|
28
|
+
return createAesGcmCodec({key: decryptKey}).decode(payload);
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
describe("createServerKeyProvider", () => {
|
|
32
|
+
it("derives a non-extractable AES-GCM key", async () => {
|
|
33
|
+
const provider = createServerKeyProvider({
|
|
34
|
+
appName: "demo",
|
|
35
|
+
cacheDbName: uniqueDbName(),
|
|
36
|
+
fetchKeyMaterial: async () => randomMaterialBase64(),
|
|
37
|
+
});
|
|
38
|
+
const key = await provider.getKey({userId: "u1"});
|
|
39
|
+
expect(key.extractable).toBe(false);
|
|
40
|
+
expect(key.algorithm.name).toBe("AES-GCM");
|
|
41
|
+
expect((key.algorithm as AesKeyAlgorithm).length).toBe(256);
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
it("derives deterministically: same material + salt yields interoperable keys", async () => {
|
|
45
|
+
const material = randomMaterialBase64();
|
|
46
|
+
const providerA = createServerKeyProvider({
|
|
47
|
+
appName: "demo",
|
|
48
|
+
cacheDbName: uniqueDbName(),
|
|
49
|
+
fetchKeyMaterial: async () => material,
|
|
50
|
+
});
|
|
51
|
+
const providerB = createServerKeyProvider({
|
|
52
|
+
appName: "demo",
|
|
53
|
+
cacheDbName: uniqueDbName(),
|
|
54
|
+
fetchKeyMaterial: async () => material,
|
|
55
|
+
});
|
|
56
|
+
const decrypted = await roundTripAcrossKeys({
|
|
57
|
+
decryptKey: await providerB.getKey({userId: "u1"}),
|
|
58
|
+
encryptKey: await providerA.getKey({userId: "u1"}),
|
|
59
|
+
});
|
|
60
|
+
expect(decrypted).toBe("cross-key payload");
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
it("derives distinct keys per userId (salt isolation)", async () => {
|
|
64
|
+
const material = randomMaterialBase64();
|
|
65
|
+
const provider = createServerKeyProvider({
|
|
66
|
+
appName: "demo",
|
|
67
|
+
cacheDbName: uniqueDbName(),
|
|
68
|
+
fetchKeyMaterial: async () => material,
|
|
69
|
+
});
|
|
70
|
+
expect(
|
|
71
|
+
roundTripAcrossKeys({
|
|
72
|
+
decryptKey: await provider.getKey({userId: "u2"}),
|
|
73
|
+
encryptKey: await provider.getKey({userId: "u1"}),
|
|
74
|
+
})
|
|
75
|
+
).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
it("derives distinct keys per appName (salt isolation)", async () => {
|
|
79
|
+
const material = randomMaterialBase64();
|
|
80
|
+
const providerA = createServerKeyProvider({
|
|
81
|
+
appName: "app-a",
|
|
82
|
+
cacheDbName: uniqueDbName(),
|
|
83
|
+
fetchKeyMaterial: async () => material,
|
|
84
|
+
});
|
|
85
|
+
const providerB = createServerKeyProvider({
|
|
86
|
+
appName: "app-b",
|
|
87
|
+
cacheDbName: uniqueDbName(),
|
|
88
|
+
fetchKeyMaterial: async () => material,
|
|
89
|
+
});
|
|
90
|
+
expect(
|
|
91
|
+
roundTripAcrossKeys({
|
|
92
|
+
decryptKey: await providerB.getKey({userId: "u1"}),
|
|
93
|
+
encryptKey: await providerA.getKey({userId: "u1"}),
|
|
94
|
+
})
|
|
95
|
+
).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
it("skips the fetch on a cache hit (repeat and concurrent calls)", async () => {
|
|
99
|
+
const fetchKeyMaterial = mock(async () => randomMaterialBase64());
|
|
100
|
+
const provider = createServerKeyProvider({
|
|
101
|
+
appName: "demo",
|
|
102
|
+
cacheDbName: uniqueDbName(),
|
|
103
|
+
fetchKeyMaterial,
|
|
104
|
+
});
|
|
105
|
+
const [k1, k2] = await Promise.all([
|
|
106
|
+
provider.getKey({userId: "u1"}),
|
|
107
|
+
provider.getKey({userId: "u1"}),
|
|
108
|
+
]);
|
|
109
|
+
expect(k1).toBe(k2);
|
|
110
|
+
await provider.getKey({userId: "u1"});
|
|
111
|
+
expect(fetchKeyMaterial).toHaveBeenCalledTimes(1);
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
it("cold-starts offline from the IndexedDB cache without any network", async () => {
|
|
115
|
+
const cacheDbName = uniqueDbName();
|
|
116
|
+
const material = randomMaterialBase64();
|
|
117
|
+
const onlineProvider = createServerKeyProvider({
|
|
118
|
+
appName: "demo",
|
|
119
|
+
cacheDbName,
|
|
120
|
+
fetchKeyMaterial: async () => material,
|
|
121
|
+
});
|
|
122
|
+
const onlineKey = await onlineProvider.getKey({userId: "u1"});
|
|
123
|
+
|
|
124
|
+
const offlineProvider = createServerKeyProvider({
|
|
125
|
+
appName: "demo",
|
|
126
|
+
cacheDbName,
|
|
127
|
+
fetchKeyMaterial: async () => {
|
|
128
|
+
throw new Error("network unavailable");
|
|
129
|
+
},
|
|
130
|
+
});
|
|
131
|
+
const offlineKey = await offlineProvider.getKey({userId: "u1"});
|
|
132
|
+
const decrypted = await roundTripAcrossKeys({decryptKey: offlineKey, encryptKey: onlineKey});
|
|
133
|
+
expect(decrypted).toBe("cross-key payload");
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
it("rejects key material that is not exactly 32 bytes", async () => {
|
|
137
|
+
const provider = createServerKeyProvider({
|
|
138
|
+
appName: "demo",
|
|
139
|
+
cacheDbName: uniqueDbName(),
|
|
140
|
+
fetchKeyMaterial: async () =>
|
|
141
|
+
Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("base64"),
|
|
142
|
+
});
|
|
143
|
+
expect(provider.getKey({userId: "u1"})).rejects.toThrow("32 bytes");
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
it("does not poison future attempts after a failed fetch", async () => {
|
|
147
|
+
const material = randomMaterialBase64();
|
|
148
|
+
let shouldFail = true;
|
|
149
|
+
const provider = createServerKeyProvider({
|
|
150
|
+
appName: "demo",
|
|
151
|
+
cacheDbName: uniqueDbName(),
|
|
152
|
+
fetchKeyMaterial: async () => {
|
|
153
|
+
if (shouldFail) {
|
|
154
|
+
throw new Error("network unavailable");
|
|
155
|
+
}
|
|
156
|
+
return material;
|
|
157
|
+
},
|
|
158
|
+
});
|
|
159
|
+
expect(provider.getKey({userId: "u1"})).rejects.toThrow("network unavailable");
|
|
160
|
+
shouldFail = false;
|
|
161
|
+
const key = await provider.getKey({userId: "u1"});
|
|
162
|
+
expect(key.type).toBe("secret");
|
|
163
|
+
});
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
describe("createLocalKeyProvider", () => {
|
|
167
|
+
it("generates a non-extractable AES-GCM key on first use", async () => {
|
|
168
|
+
const provider = createLocalKeyProvider({cacheDbName: uniqueDbName()});
|
|
169
|
+
const key = await provider.getKey({userId: "u1"});
|
|
170
|
+
expect(key.extractable).toBe(false);
|
|
171
|
+
expect(key.algorithm.name).toBe("AES-GCM");
|
|
172
|
+
expect((key.algorithm as AesKeyAlgorithm).length).toBe(256);
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
it("persists the key across fresh provider instances (same IndexedDB)", async () => {
|
|
176
|
+
const cacheDbName = uniqueDbName();
|
|
177
|
+
const first = await createLocalKeyProvider({cacheDbName}).getKey({userId: "u1"});
|
|
178
|
+
const second = await createLocalKeyProvider({cacheDbName}).getKey({userId: "u1"});
|
|
179
|
+
const decrypted = await roundTripAcrossKeys({decryptKey: second, encryptKey: first});
|
|
180
|
+
expect(decrypted).toBe("cross-key payload");
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
it("shares one key across concurrent first calls (no split-brain keys)", async () => {
|
|
184
|
+
const provider = createLocalKeyProvider({cacheDbName: uniqueDbName()});
|
|
185
|
+
const [k1, k2] = await Promise.all([
|
|
186
|
+
provider.getKey({userId: "u1"}),
|
|
187
|
+
provider.getKey({userId: "u1"}),
|
|
188
|
+
]);
|
|
189
|
+
expect(k1).toBe(k2);
|
|
190
|
+
});
|
|
191
|
+
|
|
192
|
+
it("scopes keys per userId", async () => {
|
|
193
|
+
const provider = createLocalKeyProvider({cacheDbName: uniqueDbName()});
|
|
194
|
+
expect(
|
|
195
|
+
roundTripAcrossKeys({
|
|
196
|
+
decryptKey: await provider.getKey({userId: "u2"}),
|
|
197
|
+
encryptKey: await provider.getKey({userId: "u1"}),
|
|
198
|
+
})
|
|
199
|
+
).rejects.toBeInstanceOf(PayloadIntegrityError);
|
|
200
|
+
});
|
|
201
|
+
|
|
202
|
+
it("caches the CryptoKey itself in IndexedDB", async () => {
|
|
203
|
+
const cacheDbName = uniqueDbName();
|
|
204
|
+
await createLocalKeyProvider({cacheDbName}).getKey({userId: "u1"});
|
|
205
|
+
const stored = await idbGet<CryptoKey>({databaseName: cacheDbName, key: "local:u1"});
|
|
206
|
+
expect(stored).toBeInstanceOf(CryptoKey);
|
|
207
|
+
});
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
describe("createKeyProviderCodec", () => {
|
|
211
|
+
it("round-trips using a lazily resolved key", async () => {
|
|
212
|
+
const provider = createLocalKeyProvider({cacheDbName: uniqueDbName()});
|
|
213
|
+
const codec = createKeyProviderCodec({keyProvider: provider, userId: "u1"});
|
|
214
|
+
const payload = await codec.encode("lazy key payload");
|
|
215
|
+
expect(await codec.decode(payload)).toBe("lazy key payload");
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
it("resolves the key from the provider exactly once", async () => {
|
|
219
|
+
const inner = createLocalKeyProvider({cacheDbName: uniqueDbName()});
|
|
220
|
+
const getKey = mock(({userId}: {userId: string}) => inner.getKey({userId}));
|
|
221
|
+
const spyProvider: KeyProvider = {getKey};
|
|
222
|
+
const codec = createKeyProviderCodec({keyProvider: spyProvider, userId: "u1"});
|
|
223
|
+
await codec.decode(await codec.encode("a"));
|
|
224
|
+
await codec.encode("b");
|
|
225
|
+
expect(getKey).toHaveBeenCalledTimes(1);
|
|
226
|
+
expect(getKey).toHaveBeenCalledWith({userId: "u1"});
|
|
227
|
+
});
|
|
228
|
+
});
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import {idbGet, idbSet} from "../storage/idb";
|
|
2
|
+
import {createAesGcmCodec, getSubtleCrypto} from "./aesGcmCodec";
|
|
3
|
+
import type {KeyProvider, PayloadCodec} from "./types";
|
|
4
|
+
|
|
5
|
+
/** Default IndexedDB database used to cache derived/generated CryptoKeys. */
|
|
6
|
+
export const DEFAULT_KEY_CACHE_DB_NAME = "terreno-syncdb-keys";
|
|
7
|
+
|
|
8
|
+
const SERVER_KEY_MATERIAL_BYTES = 32;
|
|
9
|
+
|
|
10
|
+
const fromBase64 = (value: string): Uint8Array => {
|
|
11
|
+
if (typeof Buffer !== "undefined") {
|
|
12
|
+
return new Uint8Array(Buffer.from(value, "base64"));
|
|
13
|
+
}
|
|
14
|
+
const binary = atob(value);
|
|
15
|
+
const bytes = new Uint8Array(binary.length);
|
|
16
|
+
for (let i = 0; i < binary.length; i += 1) {
|
|
17
|
+
bytes[i] = binary.charCodeAt(i);
|
|
18
|
+
}
|
|
19
|
+
return bytes;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
// See aesGcmCodec.ts: bridges Uint8Array<ArrayBufferLike> to BufferSource.
|
|
23
|
+
const asBufferSource = (bytes: Uint8Array): BufferSource => bytes as unknown as BufferSource;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Wrap key resolution + caching so concurrent `getKey` calls for the same user
|
|
27
|
+
* share one in-flight promise (two racing calls must never persist two
|
|
28
|
+
* different keys — the loser's key would silently fail to decrypt later).
|
|
29
|
+
*/
|
|
30
|
+
const createCachedKeyResolver = ({
|
|
31
|
+
cacheDbName,
|
|
32
|
+
deriveKey,
|
|
33
|
+
scope,
|
|
34
|
+
}: {
|
|
35
|
+
cacheDbName: string;
|
|
36
|
+
deriveKey: ({userId}: {userId: string}) => Promise<CryptoKey>;
|
|
37
|
+
scope: string;
|
|
38
|
+
}): KeyProvider => {
|
|
39
|
+
const inFlight = new Map<string, Promise<CryptoKey>>();
|
|
40
|
+
|
|
41
|
+
const resolveKey = async ({userId}: {userId: string}): Promise<CryptoKey> => {
|
|
42
|
+
const cacheKey = `${scope}:${userId}`;
|
|
43
|
+
const cached = await idbGet<CryptoKey>({databaseName: cacheDbName, key: cacheKey});
|
|
44
|
+
if (cached) {
|
|
45
|
+
return cached;
|
|
46
|
+
}
|
|
47
|
+
const key = await deriveKey({userId});
|
|
48
|
+
await idbSet({databaseName: cacheDbName, key: cacheKey, value: key});
|
|
49
|
+
return key;
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
const getKey = ({userId}: {userId: string}): Promise<CryptoKey> => {
|
|
53
|
+
const existing = inFlight.get(userId);
|
|
54
|
+
if (existing) {
|
|
55
|
+
return existing;
|
|
56
|
+
}
|
|
57
|
+
const promise = resolveKey({userId}).catch((error) => {
|
|
58
|
+
// Failed resolutions must not poison future attempts (e.g. offline fetch).
|
|
59
|
+
inFlight.delete(userId);
|
|
60
|
+
throw error;
|
|
61
|
+
});
|
|
62
|
+
inFlight.set(userId, promise);
|
|
63
|
+
return promise;
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
return {getKey};
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Default web key provider: fetches per-user key material from the server
|
|
71
|
+
* (`GET /sync/key`, wired by the caller), HKDF-SHA256-derives a non-extractable
|
|
72
|
+
* AES-256-GCM key with salt `${appName}:${userId}`, and caches the derived
|
|
73
|
+
* CryptoKey in IndexedDB so an offline cold start needs no network. A cache hit
|
|
74
|
+
* skips `fetchKeyMaterial` entirely.
|
|
75
|
+
*/
|
|
76
|
+
export const createServerKeyProvider = ({
|
|
77
|
+
appName,
|
|
78
|
+
fetchKeyMaterial,
|
|
79
|
+
cacheDbName = DEFAULT_KEY_CACHE_DB_NAME,
|
|
80
|
+
}: {
|
|
81
|
+
appName: string;
|
|
82
|
+
/** Returns the server key material: base64 of exactly 32 random bytes. */
|
|
83
|
+
fetchKeyMaterial: () => Promise<string>;
|
|
84
|
+
cacheDbName?: string;
|
|
85
|
+
}): KeyProvider => {
|
|
86
|
+
const deriveKey = async ({userId}: {userId: string}): Promise<CryptoKey> => {
|
|
87
|
+
const subtle = getSubtleCrypto();
|
|
88
|
+
const material = fromBase64(await fetchKeyMaterial());
|
|
89
|
+
if (material.length !== SERVER_KEY_MATERIAL_BYTES) {
|
|
90
|
+
throw new Error(
|
|
91
|
+
`Server key material must be ${SERVER_KEY_MATERIAL_BYTES} bytes, got ${material.length}`
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
const baseKey = await subtle.importKey("raw", asBufferSource(material), "HKDF", false, [
|
|
95
|
+
"deriveKey",
|
|
96
|
+
]);
|
|
97
|
+
return subtle.deriveKey(
|
|
98
|
+
{
|
|
99
|
+
hash: "SHA-256",
|
|
100
|
+
info: new Uint8Array(0),
|
|
101
|
+
name: "HKDF",
|
|
102
|
+
salt: asBufferSource(new TextEncoder().encode(`${appName}:${userId}`)),
|
|
103
|
+
},
|
|
104
|
+
baseKey,
|
|
105
|
+
{length: 256, name: "AES-GCM"},
|
|
106
|
+
false,
|
|
107
|
+
["encrypt", "decrypt"]
|
|
108
|
+
);
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
return createCachedKeyResolver({cacheDbName, deriveKey, scope: `server:${appName}`});
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Device-local key provider: generates a random non-extractable AES-256-GCM key
|
|
116
|
+
* on first use and persists it in IndexedDB for reuse across sessions. Data
|
|
117
|
+
* encrypted with it is only readable on this device (no server escrow).
|
|
118
|
+
*/
|
|
119
|
+
export const createLocalKeyProvider = ({
|
|
120
|
+
cacheDbName = DEFAULT_KEY_CACHE_DB_NAME,
|
|
121
|
+
}: {
|
|
122
|
+
cacheDbName?: string;
|
|
123
|
+
} = {}): KeyProvider => {
|
|
124
|
+
const deriveKey = async (): Promise<CryptoKey> =>
|
|
125
|
+
getSubtleCrypto().generateKey({length: 256, name: "AES-GCM"}, false, ["encrypt", "decrypt"]);
|
|
126
|
+
|
|
127
|
+
return createCachedKeyResolver({cacheDbName, deriveKey, scope: "local"});
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* AES-GCM codec whose key is resolved lazily from a {@link KeyProvider} on
|
|
132
|
+
* first use. Lets persister factories stay synchronous while key
|
|
133
|
+
* fetch/derivation happens on the first load/save.
|
|
134
|
+
*/
|
|
135
|
+
export const createKeyProviderCodec = ({
|
|
136
|
+
keyProvider,
|
|
137
|
+
userId,
|
|
138
|
+
}: {
|
|
139
|
+
keyProvider: KeyProvider;
|
|
140
|
+
userId: string;
|
|
141
|
+
}): PayloadCodec => {
|
|
142
|
+
let codecPromise: Promise<PayloadCodec> | undefined;
|
|
143
|
+
const resolveCodec = (): Promise<PayloadCodec> => {
|
|
144
|
+
codecPromise ??= keyProvider.getKey({userId}).then((key) => createAesGcmCodec({key}));
|
|
145
|
+
return codecPromise;
|
|
146
|
+
};
|
|
147
|
+
|
|
148
|
+
return {
|
|
149
|
+
decode: async (payload: Uint8Array): Promise<string> => (await resolveCodec()).decode(payload),
|
|
150
|
+
encode: async (plaintext: string): Promise<Uint8Array> =>
|
|
151
|
+
(await resolveCodec()).encode(plaintext),
|
|
152
|
+
};
|
|
153
|
+
};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Encryption primitives for at-rest protection of persisted data. Encryption is
|
|
3
|
+
* applied at the persistence boundary (the serialized store blob), keeping the
|
|
4
|
+
* in-memory store plaintext for querying while only ciphertext lands in
|
|
5
|
+
* IndexedDB/SQLite.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** Symmetric codec applied to the serialized store blob before persistence. */
|
|
9
|
+
export interface PayloadCodec {
|
|
10
|
+
/** Encrypt/encode a plaintext string into a binary payload for storage. */
|
|
11
|
+
encode(plaintext: string): Promise<Uint8Array>;
|
|
12
|
+
/** Decrypt/decode a previously encoded binary payload. */
|
|
13
|
+
decode(payload: Uint8Array): Promise<string>;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Resolves the per-user symmetric encryption key. Implementations must return
|
|
18
|
+
* non-extractable AES-GCM keys so raw key bytes never sit in page-inspectable
|
|
19
|
+
* memory or storage.
|
|
20
|
+
*/
|
|
21
|
+
export interface KeyProvider {
|
|
22
|
+
getKey({userId}: {userId: string}): Promise<CryptoKey>;
|
|
23
|
+
}
|