@open-e2ee/signal-protocol-sdk 8.1.0 → 8.2.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.
Files changed (147) hide show
  1. package/CHANGELOG.md +153 -0
  2. package/README.md +2 -2
  3. package/SECURITY.md +2 -2
  4. package/device/README.md +16 -7
  5. package/dist/client/client.d.ts +4 -2
  6. package/dist/client/client.d.ts.map +1 -1
  7. package/dist/client/client.js +23 -18
  8. package/dist/client/client.js.map +1 -1
  9. package/dist/client/group-outbox.d.ts +31 -1
  10. package/dist/client/group-outbox.d.ts.map +1 -1
  11. package/dist/client/group-outbox.js +67 -58
  12. package/dist/client/group-outbox.js.map +1 -1
  13. package/dist/client/hosted-anonymous-delivery.d.ts +9 -1
  14. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  15. package/dist/client/hosted-anonymous-delivery.js +61 -22
  16. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  17. package/dist/client/hosted-transport.d.ts +7 -0
  18. package/dist/client/hosted-transport.d.ts.map +1 -1
  19. package/dist/client/hosted-transport.js +44 -6
  20. package/dist/client/hosted-transport.js.map +1 -1
  21. package/dist/client/key-rotation.d.ts.map +1 -1
  22. package/dist/client/key-rotation.js +2 -4
  23. package/dist/client/key-rotation.js.map +1 -1
  24. package/dist/client/prekeys.d.ts.map +1 -1
  25. package/dist/client/prekeys.js +1 -1
  26. package/dist/client/prekeys.js.map +1 -1
  27. package/dist/client/relay-device-refusal.d.ts +32 -0
  28. package/dist/client/relay-device-refusal.d.ts.map +1 -0
  29. package/dist/client/relay-device-refusal.js +36 -0
  30. package/dist/client/relay-device-refusal.js.map +1 -0
  31. package/dist/client/relay-work.d.ts +26 -0
  32. package/dist/client/relay-work.d.ts.map +1 -1
  33. package/dist/client/relay-work.js +37 -0
  34. package/dist/client/relay-work.js.map +1 -1
  35. package/dist/client/sealed-sender.d.ts.map +1 -1
  36. package/dist/client/sealed-sender.js +12 -17
  37. package/dist/client/sealed-sender.js.map +1 -1
  38. package/dist/client/sessions.d.ts.map +1 -1
  39. package/dist/client/sessions.js +2 -4
  40. package/dist/client/sessions.js.map +1 -1
  41. package/dist/client/signal-service-cipher.d.ts +90 -4
  42. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  43. package/dist/client/signal-service-cipher.js +425 -136
  44. package/dist/client/signal-service-cipher.js.map +1 -1
  45. package/dist/client/types.d.ts +7 -0
  46. package/dist/client/types.d.ts.map +1 -1
  47. package/dist/client/types.js.map +1 -1
  48. package/dist/internal/manager/manager.d.ts +8 -7
  49. package/dist/internal/manager/manager.d.ts.map +1 -1
  50. package/dist/internal/manager/manager.js +34 -36
  51. package/dist/internal/manager/manager.js.map +1 -1
  52. package/dist/internal/protocol/spqr/index.d.ts +1 -1
  53. package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
  54. package/dist/internal/protocol/spqr/index.js +2 -2
  55. package/dist/internal/protocol/spqr/index.js.map +1 -1
  56. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  57. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +1 -3
  58. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  59. package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
  60. package/dist/internal/protocol/spqr/serialize.js +1 -4
  61. package/dist/internal/protocol/spqr/serialize.js.map +1 -1
  62. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  63. package/dist/internal/protocol/spqr/spqr.js +1 -2
  64. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  65. package/dist/internal/sesame/device-registry.d.ts +24 -4
  66. package/dist/internal/sesame/device-registry.d.ts.map +1 -1
  67. package/dist/internal/sesame/device-registry.js +55 -28
  68. package/dist/internal/sesame/device-registry.js.map +1 -1
  69. package/dist/internal/sesame/manager.d.ts +79 -11
  70. package/dist/internal/sesame/manager.d.ts.map +1 -1
  71. package/dist/internal/sesame/manager.js +381 -280
  72. package/dist/internal/sesame/manager.js.map +1 -1
  73. package/dist/internal/session/cipher.d.ts +0 -5
  74. package/dist/internal/session/cipher.d.ts.map +1 -1
  75. package/dist/internal/session/cipher.js +3 -9
  76. package/dist/internal/session/cipher.js.map +1 -1
  77. package/dist/internal/session/record-locks.d.ts +46 -0
  78. package/dist/internal/session/record-locks.d.ts.map +1 -0
  79. package/dist/internal/session/record-locks.js +72 -0
  80. package/dist/internal/session/record-locks.js.map +1 -0
  81. package/dist/local/store/expo/adapter.d.ts +8 -2
  82. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  83. package/dist/local/store/expo/adapter.js +24 -3
  84. package/dist/local/store/expo/adapter.js.map +1 -1
  85. package/dist/local/store/expo/driver.d.ts +7 -0
  86. package/dist/local/store/expo/driver.d.ts.map +1 -1
  87. package/dist/local/store/expo/driver.js +16 -0
  88. package/dist/local/store/expo/driver.js.map +1 -1
  89. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  90. package/dist/local/store/key-value/adapter.js +61 -38
  91. package/dist/local/store/key-value/adapter.js.map +1 -1
  92. package/dist/local/store/memory/adapter.d.ts +10 -0
  93. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  94. package/dist/local/store/memory/adapter.js +79 -55
  95. package/dist/local/store/memory/adapter.js.map +1 -1
  96. package/dist/local/store/reliability.d.ts +16 -0
  97. package/dist/local/store/reliability.d.ts.map +1 -1
  98. package/dist/local/store/reliability.js +58 -28
  99. package/dist/local/store/reliability.js.map +1 -1
  100. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  101. package/dist/local/store/sqlite/store.js +36 -14
  102. package/dist/local/store/sqlite/store.js.map +1 -1
  103. package/dist/local/store/web/adapter.d.ts.map +1 -1
  104. package/dist/local/store/web/adapter.js +63 -53
  105. package/dist/local/store/web/adapter.js.map +1 -1
  106. package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
  107. package/dist/local/vault/electron-safe-storage.js +15 -2
  108. package/dist/local/vault/electron-safe-storage.js.map +1 -1
  109. package/dist/profile/index.d.ts +2 -1
  110. package/dist/profile/index.d.ts.map +1 -1
  111. package/dist/profile/index.js +2 -1
  112. package/dist/profile/index.js.map +1 -1
  113. package/dist/profile/own-profile-key.d.ts +42 -0
  114. package/dist/profile/own-profile-key.d.ts.map +1 -0
  115. package/dist/profile/own-profile-key.js +64 -0
  116. package/dist/profile/own-profile-key.js.map +1 -0
  117. package/dist/profile/profile-key.d.ts +1 -34
  118. package/dist/profile/profile-key.d.ts.map +1 -1
  119. package/dist/profile/profile-key.js +3 -63
  120. package/dist/profile/profile-key.js.map +1 -1
  121. package/dist/profile/update-service.js +1 -1
  122. package/dist/profile/update-service.js.map +1 -1
  123. package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
  124. package/dist/remote/relay/memory/adapter.js +3 -4
  125. package/dist/remote/relay/memory/adapter.js.map +1 -1
  126. package/dist/username/link.d.ts.map +1 -1
  127. package/dist/username/link.js +1 -5
  128. package/dist/username/link.js.map +1 -1
  129. package/dist/utils/bounded-fan-out.d.ts +99 -0
  130. package/dist/utils/bounded-fan-out.d.ts.map +1 -0
  131. package/dist/utils/bounded-fan-out.js +180 -0
  132. package/dist/utils/bounded-fan-out.js.map +1 -0
  133. package/dist/utils/keyed-lock.d.ts +16 -0
  134. package/dist/utils/keyed-lock.d.ts.map +1 -0
  135. package/dist/utils/keyed-lock.js +39 -0
  136. package/dist/utils/keyed-lock.js.map +1 -0
  137. package/docs/ASSURANCE.md +62 -19
  138. package/docs/DEVIATIONS.md +21 -2
  139. package/examples/browser/index.html +1 -1
  140. package/hooks/README.md +11 -2
  141. package/local/store/expo/README.md +18 -5
  142. package/local/store/key-value/README.md +5 -3
  143. package/local/store/node/README.md +2 -1
  144. package/local/store/web-sqlite/README.md +28 -8
  145. package/local/vault/README.md +21 -2
  146. package/package.json +1 -1
  147. package/remote/object-store/convex-r2/README.md +10 -0
@@ -0,0 +1,180 @@
1
+ /**
2
+ * Bounded fan-out: parallel protocol work whose relay requests share one
3
+ * bound.
4
+ *
5
+ * A client owns one BoundedFanOut. Every fan-out of the client sends its relay
6
+ * requests through request(), so the client has at most `limit` relay requests
7
+ * in flight in total, also when one fan-out runs inside another.
8
+ *
9
+ * A slot is held only while one relay request runs. The request function must
10
+ * not await a lock or another request(): four callers that hold every slot and
11
+ * wait for a fifth slot never continue. The lock order is: session lock, then
12
+ * user lock, then a slot.
13
+ *
14
+ * all() runs one phase: a task for each item, all at the same time. It settles
15
+ * only after every item settles, so it is a barrier. phases() runs protocol
16
+ * phases in order, and a phase starts only after the phase before it
17
+ * succeeded.
18
+ *
19
+ * A stop signal ends the work: after it aborts, no request starts and no phase
20
+ * starts. A request in flight runs on. The work rejects with the error of the
21
+ * `stopped` option.
22
+ */
23
+ /** Relay requests that one client has in flight at most. */
24
+ export const RELAY_REQUESTS_IN_FLIGHT = 4;
25
+ /**
26
+ * One or more items of a fan-out failed. Every item settled before this error.
27
+ */
28
+ export class FanOutError extends Error {
29
+ /** The error of each failed item, in input order. */
30
+ errors;
31
+ /** The outcome of each item, in input order. */
32
+ outcomes;
33
+ constructor(outcomes) {
34
+ const errors = outcomes.flatMap((outcome) => (outcome.ok ? [] : [outcome.error]));
35
+ const first = errors[0];
36
+ const detail = first instanceof Error ? first.message : String(first);
37
+ super(`${errors.length} of ${outcomes.length} fan-out items failed: ${detail}`);
38
+ this.name = 'FanOutError';
39
+ this.errors = errors;
40
+ this.outcomes = outcomes;
41
+ }
42
+ }
43
+ /**
44
+ * The error of the first failed item of a fan-out, in input order, so a
45
+ * caller sees the error that the same work in input order threw. Any other
46
+ * error is returned as it is.
47
+ */
48
+ export function firstItemError(error) {
49
+ return error instanceof FanOutError ? error.errors[0] : error;
50
+ }
51
+ /**
52
+ * The relay request bound of one client, and the fan-outs that share it.
53
+ */
54
+ export class BoundedFanOut {
55
+ limit;
56
+ stopped;
57
+ inFlight = 0;
58
+ waiting = [];
59
+ constructor(options) {
60
+ const limit = options.limit ?? RELAY_REQUESTS_IN_FLIGHT;
61
+ if (!Number.isInteger(limit) || limit < 1) {
62
+ throw new RangeError(`The fan-out limit must be a positive integer, not ${limit}`);
63
+ }
64
+ this.limit = limit;
65
+ this.stopped = options.stopped;
66
+ }
67
+ /**
68
+ * Send one relay request under a slot. The slot is released when the request
69
+ * settles. When the stop signal aborts before the request gets a slot, the
70
+ * request never starts.
71
+ */
72
+ async request(send, stopSignal) {
73
+ await this.acquire(stopSignal);
74
+ try {
75
+ return await send();
76
+ }
77
+ finally {
78
+ this.release();
79
+ }
80
+ }
81
+ /**
82
+ * Run task for each item at the same time. Results keep input order. A failed
83
+ * item does not stop the other items. After every item settles, a failure
84
+ * rejects with a FanOutError, and a stop rejects with the `stopped` error.
85
+ * The fan-out holds no slot: each task takes a slot for each request.
86
+ */
87
+ async all(items, task, stopSignal) {
88
+ if (stopSignal?.aborted)
89
+ throw this.stopped();
90
+ const outcomes = await Promise.all(items.map((item, index) => new Promise((resolve) => resolve(task(item, index))).then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }))));
91
+ const values = [];
92
+ for (const outcome of outcomes) {
93
+ if (!outcome.ok) {
94
+ if (stopSignal?.aborted)
95
+ throw this.stopped();
96
+ throw new FanOutError(outcomes);
97
+ }
98
+ values.push(outcome.value);
99
+ }
100
+ return values;
101
+ }
102
+ /** Protocol phases that share one stop signal. */
103
+ phases(stopSignal) {
104
+ return new FanOutPhases(this, this.stopped, stopSignal);
105
+ }
106
+ acquire(stopSignal) {
107
+ if (stopSignal?.aborted)
108
+ return Promise.reject(this.stopped());
109
+ if (this.inFlight < this.limit) {
110
+ this.inFlight++;
111
+ return Promise.resolve();
112
+ }
113
+ return new Promise((resolve, reject) => {
114
+ const grant = () => {
115
+ stopSignal?.removeEventListener('abort', abandon);
116
+ resolve();
117
+ };
118
+ const abandon = () => {
119
+ const index = this.waiting.indexOf(grant);
120
+ if (index < 0)
121
+ return;
122
+ this.waiting.splice(index, 1);
123
+ reject(this.stopped());
124
+ };
125
+ this.waiting.push(grant);
126
+ stopSignal?.addEventListener('abort', abandon);
127
+ });
128
+ }
129
+ release() {
130
+ // The slot passes to the first waiter, so a new request cannot take it
131
+ // first.
132
+ const next = this.waiting.shift();
133
+ if (next)
134
+ next();
135
+ else
136
+ this.inFlight--;
137
+ }
138
+ }
139
+ /**
140
+ * Protocol phases in order, with a barrier between phases. A phase starts only
141
+ * after the phase before it settled and succeeded, and not after the stop
142
+ * signal aborts. A phase that starts too early throws and runs nothing.
143
+ */
144
+ export class FanOutPhases {
145
+ fanOut;
146
+ stopped;
147
+ stopSignal;
148
+ state = 'ready';
149
+ constructor(fanOut, stopped, stopSignal) {
150
+ this.fanOut = fanOut;
151
+ this.stopped = stopped;
152
+ this.stopSignal = stopSignal;
153
+ }
154
+ /** Run one fan-out phase: all() with the stop signal of these phases. */
155
+ all(items, task) {
156
+ return this.run(() => this.fanOut.all(items, task, this.stopSignal));
157
+ }
158
+ /** Run one phase that is not a fan-out, for example one request. */
159
+ async run(phase) {
160
+ if (this.state === 'running') {
161
+ throw new Error('A phase started before the phase before it settled');
162
+ }
163
+ if (this.state === 'failed') {
164
+ throw new Error('A phase started after the phase before it failed');
165
+ }
166
+ if (this.stopSignal?.aborted)
167
+ throw this.stopped();
168
+ this.state = 'running';
169
+ try {
170
+ const result = await phase();
171
+ this.state = 'ready';
172
+ return result;
173
+ }
174
+ catch (error) {
175
+ this.state = 'failed';
176
+ throw error;
177
+ }
178
+ }
179
+ }
180
+ //# sourceMappingURL=bounded-fan-out.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bounded-fan-out.js","sourceRoot":"","sources":["../../utils/bounded-fan-out.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * An in-process lock keyed by an owner object and a string key.
3
+ *
4
+ * Operations with the same owner and key run one at a time in call order.
5
+ * Operations with a different owner or key do not wait for each other. The
6
+ * lock is not reentrant: an operation that takes the same lock again waits
7
+ * for itself and never completes.
8
+ *
9
+ * The lock orders one JavaScript process only. It does not order two browser
10
+ * tabs, two workers, or two processes that share one store.
11
+ */
12
+ export {};
13
+ export type KeyedLocks = WeakMap<object, Map<string, Promise<void>>>;
14
+ export declare function createKeyedLocks(): KeyedLocks;
15
+ export declare function withKeyedLock<T>(collections: KeyedLocks, owner: object, key: string, operation: () => Promise<T>): Promise<T>;
16
+ //# sourceMappingURL=keyed-lock.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"keyed-lock.d.ts","sourceRoot":"","sources":["../../utils/keyed-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC;AAEV,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAErE,wBAAgB,gBAAgB,IAAI,UAAU,CAE7C;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,WAAW,EAAE,UAAU,EACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAoBZ"}
@@ -0,0 +1,39 @@
1
+ /**
2
+ * An in-process lock keyed by an owner object and a string key.
3
+ *
4
+ * Operations with the same owner and key run one at a time in call order.
5
+ * Operations with a different owner or key do not wait for each other. The
6
+ * lock is not reentrant: an operation that takes the same lock again waits
7
+ * for itself and never completes.
8
+ *
9
+ * The lock orders one JavaScript process only. It does not order two browser
10
+ * tabs, two workers, or two processes that share one store.
11
+ */
12
+ export function createKeyedLocks() {
13
+ return new WeakMap();
14
+ }
15
+ export async function withKeyedLock(collections, owner, key, operation) {
16
+ let locks = collections.get(owner);
17
+ if (!locks) {
18
+ locks = new Map();
19
+ collections.set(owner, locks);
20
+ }
21
+ const previous = locks.get(key) ?? Promise.resolve();
22
+ let release;
23
+ const current = new Promise((resolve) => {
24
+ release = resolve;
25
+ });
26
+ locks.set(key, current);
27
+ await previous.catch(() => undefined);
28
+ try {
29
+ return await operation();
30
+ }
31
+ finally {
32
+ release();
33
+ if (locks.get(key) === current)
34
+ locks.delete(key);
35
+ if (locks.size === 0)
36
+ collections.delete(owner);
37
+ }
38
+ }
39
+ //# sourceMappingURL=keyed-lock.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"keyed-lock.js","sourceRoot":"","sources":["../../utils/keyed-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,OAAO,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,WAAuB,EACvB,KAAa,EACb,GAAW,EACX,SAA2B;IAE3B,IAAI,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QAClB,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IACrD,IAAI,OAAoB,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxB,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;QACV,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;AACH,CAAC"}
package/docs/ASSURANCE.md CHANGED
@@ -16,16 +16,16 @@ Private testing also exists in other open-source projects. [SQLite publishes som
16
16
 
17
17
  Engineering CI runs the default automated checks on pull requests that are ready for review and on changes to the main branch. Release preparation requires a passing run.
18
18
 
19
- Most recent full run on 2026-09-29:
19
+ Most recent full run on 2026-09-30:
20
20
 
21
21
  | | |
22
22
  |---|---|
23
- | Test modules | 470 |
24
- | Test cases | 8,602 |
25
- | Passed | 8,598 |
23
+ | Test modules | 480 |
24
+ | Test cases | 8,820 |
25
+ | Passed | 8,816 |
26
26
  | Skipped | 4 |
27
27
  | Failed | 0 |
28
- | Wall time | 149 s |
28
+ | Wall time | 185 s |
29
29
 
30
30
  The total counts test cases. One test case can contain several assertions. Separate commands run the longer performance and endurance checks.
31
31
 
@@ -45,6 +45,8 @@ Release tooling generates this table from a completed run. It refuses results fr
45
45
 
46
46
  The browser storage job also runs 2,000 open, write, read, and close cycles of the IndexedDB store, and a soak of the web SQLite store. Each checks for upward memory and latency drift.
47
47
 
48
+ In Chromium, the browser storage job also builds an app with the Vite version of the browser example and the packed package. The entry module of the app completes an exchange in each direction with a top-level await. The job fails when the exchange does not finish in 30 seconds, or when a chunk of the build imports the entry chunk. A default automated check also fails when the SDK loads a module with a dynamic import and that module imports another module. Other bundlers are not checked.
49
+
48
50
  A storage contract check does not prove a full encrypted exchange. The [browser example](../examples/browser/README.md) and [Expo example](../examples/expo/README.md) exercise message encryption, delivery, and decryption.
49
51
 
50
52
  ## SQLite store checks
@@ -61,9 +63,15 @@ Four package entries keep device-local state in a SQLite database: `./local/stor
61
63
  | The store writes its key to the vault before it creates the file. A file without a key fails as a lost key and does not change. | Node store job: the same six runners | Real files and a vault. |
62
64
  | One process at a time owns a store. After the owner process is killed, the next open succeeds and reads the committed data. | Node store job: the same six runners | A child process holds the store. The parent process tries to open it, then kills the child and opens it. |
63
65
  | Every part of the store interface survives a close and a new open of the directory. | Node store job: the same six runners | Real files on the prebuilt binding. |
64
- | In the Electron main process, the store passes the shared storage contract with its key in the real `safeStorage`. The file has no SQLite header, and the vault file keeps only a ciphertext of the key. | Electron store job: Linux, macOS, and Windows | Electron from its npm package, with the GNOME keyring through libsecret on Linux, the Keychain on macOS, and DPAPI on Windows. A push to the main branch or a pull request runs this job only when it changes the store, the vault, the storage contract, the job, or a dependency. |
65
- | On Linux, the vault refuses the `basic_text` backend of `safeStorage`. The store does not open, and no key reaches the disk. | Electron store job: Linux | Electron with `--password-store=basic`. |
66
- | On Linux, the vault refuses the fixed fallback key that `safeStorage` uses when no secret service answers. The store does not open, and no key reaches the disk. | Electron store job: Linux | Electron with `--password-store=gnome-libsecret` and no unlocked keyring on the D-Bus session. |
66
+ | In the Electron main process, the store passes the shared storage contract with its key in the real `safeStorage`. The file has no SQLite header, and the vault file keeps only a ciphertext of the key. | Electron store job: Electron 44 on Linux, macOS, and Windows, and Electron 42 on Linux | Electron from its npm package, with the GNOME keyring through libsecret on Linux, the Keychain on macOS, and DPAPI on Windows. A push to the main branch or a pull request runs this job only when it changes the store, the vault, the storage contract, the job, or a dependency. |
67
+ | In an app that Electron Forge packages with ASAR, the store opens in the main process and in a utility process with its key in the real `safeStorage`, and a value that one launch writes reads back after a relaunch. The binding loads from `app.asar.unpacked`, and the file has no SQLite header. | Electron package job: Linux x64, macOS arm64, and Windows x64 | `electron-forge package` with Electron Forge 7.11.2 of an app that installs the packed package, with the auto-unpack-natives plugin and the fuses that the [Node store guide](../local/store/node/README.md#packaging) gives. On macOS, the job signs the app ad hoc and requires `codesign --verify --deep --strict` to pass before the first launch. A push to the main branch or a pull request runs this job only when it changes the store, the vault, the packaged app, the job, or a dependency. |
68
+ | On Linux, the vault refuses the `basic_text` backend of `safeStorage`. The store does not open, and no key reaches the disk. | Electron store job: Linux, Electron 44 and 42 | Electron with `--password-store=basic`. |
69
+ | On Linux, the vault refuses the fixed fallback key that `safeStorage` uses when no secret service answers. The store does not open, and no key reaches the disk. | Electron store job: Linux, Electron 44 and 42 | Electron with `--password-store=gnome-libsecret` and no unlocked keyring on the D-Bus session. |
70
+ | On Linux, the store passes the shared storage contract with its key in KWallet, on the `kwallet5` and `kwallet6` backends of `safeStorage`. | Electron store job: Linux, Electron 44. KWallet 6 job: Ubuntu 26.04, Electron 44 | Electron with `--password-store=kwallet5` on KWallet 5, and with `--password-store=kwallet6` on KWallet 6.24. A new wallet opens with no prompt, through the `pamOpen` call that `pam_kwallet` makes at login. The test checks the backend that `safeStorage` selected, and the harness removes the key from the wallet. Run 36528132421 also passed `--password-store=kwallet5` on KWallet 6.24. No job runs that case again. |
71
+ | On Linux, with a running Secret portal and the default Chromium features, the store passes the shared storage contract. `safeStorage` does not use the key of the portal. | Electron store job: Linux, Electron 44 | Electron with `--password-store=gnome-libsecret`, and xdg-desktop-portal with the GNOME keyring as the back end of its Secret portal. |
72
+ | On Linux, the vault refuses the key of the Secret portal, which `safeStorage` uses with the Chromium feature `SecretPortalKeyProviderUseForEncryption`. The store does not open, and no key reaches the disk. | Electron store job: Linux, Electron 44 | Electron with that feature and a Secret portal, with the GNOME keyring as the back end of the portal. The test checks that the ciphertext starts with `v12`. Run 36528132421 also refused the key with KWallet 6 (`kwallet6`, Ubuntu 26.04) as the back end of the portal. No job runs that case again. |
73
+
74
+ No CI job signs the app with a Developer ID. On 2026-09-29, a manual check on macOS 15.7.2 arm64 with Xcode 26.3 built the packaged app twice from the main branch, as version 1.0.0 and version 1.0.1. The build used the SDK 8.1.0 package and Electron 44.4.5. Electron Forge signed each build with a Developer ID identity and the hardened runtime, and notarized and stapled it. For each build, `spctl -a -vv` reported `accepted` and `source=Notarized Developer ID`. A check script wrote a value with version 1.0.0 in the main process and in a utility process. Then it copied version 1.0.1 over the app, and the relaunches read each value back. The securityd log had no Keychain prompt for a launch. When the check copied an ad-hoc signed copy of version 1.0.1 over version 1.0.0, securityd logged a Keychain prompt for each read, and the check stopped the app. The access list of the Keychain item of the key holds the designated requirement of the app, which names the bundle identifier and the Developer ID team, not a code hash.
67
75
 
68
76
  ### Expo: `./local/store/expo`
69
77
 
@@ -72,6 +80,7 @@ Four package entries keep device-local state in a SQLite database: `./local/stor
72
80
  | The store passes the shared storage contract. | Default automated checks: Linux, Node 26 | The storage contract on the `expo-sqlite` JavaScript layer over `node:sqlite`. This check runs no native module and no SQLCipher. |
73
81
  | A release build of the Expo example stores its state with SQLCipher on Android and keeps it across a process restart. | Android emulator job | A release APK on Hermes V1, run twice on an Android API 36 x86_64 emulator. Each run must log a SQLCipher version and a database header that is not the SQLite header. The second run must resume the stored identity and complete an exchange. This job runs on a change to the main branch that can reach the React Native runtime, and on demand. It does not run on a pull request. |
74
82
  | The Expo example, which imports this entry, bundles with the Hermes compiler that React Native pins. | Public CI (`Checks`) | The Android bundle of the Expo example with the packed package, on Expo SDK 55 and Expo SDK 57. |
83
+ | In an Expo web build, an encrypted open and a reset fail with `SqliteEncryptionUnavailableError` (`KEY_STORAGE_ERROR`) before they use the vault. With `encryptionAtRest: false`, the store opens and keeps its data across a page load. | Browser storage job: Chromium on Linux | An `expo export --platform web` of an Expo SDK 57 app that installs the packed package, loaded in Chromium. The page reads no `PRAGMA cipher_version` row, and Expo SecureStore reports that it is not available. The check does not open a store with `./local/store/web-sqlite` in the Expo web build. |
75
84
 
76
85
  The Hermes flow job does not load a SQLite store. Its flows use the memory and key-value stores. The Android emulator job is the only CI job that runs the Expo store on Hermes.
77
86
 
@@ -89,36 +98,70 @@ The Hermes flow job does not load a SQLite store. Its flows use the memory and k
89
98
 
90
99
  The Android emulator job is the only CI job that runs this store on Hermes with the native op-sqlite module. No CI job runs it on iOS. On 2026-09-28, a manual check of a development build of the SDK before 8.0.0 ran the bare React Native example in the iOS 26.2 simulator with Xcode 26.3. Each of four launches logged a SQLCipher version, a database header that is not the SQLite header, and the wrong-key failure. Each launch after the first resumed the stored identity.
91
100
 
101
+ On 2026-09-29, a manual check with Xcode 26.3 ran the release build of the example four times in the iOS 26.2 simulator. The check used the SDK 8.1.0 package built from the main branch. Each launch passed the same checks. A temporary native log in the app read the storage attributes. The example does not include this log:
102
+
103
+ - The keychain item of the database key has the accessibility class `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` (`cku`). The item does not synchronize. Its access control holds only that class. It has no user-presence flag, no biometric flag, and no token ID.
104
+ - The simulator reported no `NSFileProtectionKey` for the database file and its `-wal` and `-shm` files. The app also created a control file with `NSFileProtectionComplete`. The simulator reported no class for that file, so it does not keep the file class that an app requests. The store does not request a file class.
105
+
106
+ The simulator does not enforce Data Protection. These results do not show the protection on a device.
107
+
92
108
  ### Web: `./local/store/web-sqlite`
93
109
 
94
110
  | Claim | Check | What the check runs |
95
111
  |---|---|---|
96
- | The store passes the shared storage contract in a real browser, with the Wasm engine in its worker and the file in the origin private file system (OPFS). | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit on macOS | The page has a Content Security Policy that adds only `'wasm-unsafe-eval'`. |
97
- | An encrypted file keeps no plaintext in OPFS. A wrong key and no key cannot read it. The web driver reads a SQLCipher 4 file that the Node driver wrote. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit on macOS | Real files in OPFS. |
98
- | Two tabs share one file, and a tab hands it over only between transactions. A tab that dies in a transaction leaves the file readable without the writes of that transaction. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit on macOS | Two real tabs of one origin. |
99
- | Two tabs that open a new store at the same time write one key. A reset fails with `INVALID_STATE` while another tab has the store open. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit on macOS | Two real tabs of one origin. |
100
- | Without `'wasm-unsafe-eval'`, the open fails with `SQLITE_ENGINE_UNAVAILABLE` and writes no key. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit on macOS | A page under a policy without `'wasm-unsafe-eval'`. |
112
+ | The store passes the shared storage contract in a real browser, with the Wasm engine in its worker and the file in the origin private file system (OPFS). | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit and Safari on macOS | The page has a Content Security Policy that adds only `'wasm-unsafe-eval'`. |
113
+ | An encrypted file keeps no plaintext in OPFS. A wrong key and no key cannot read it. The web driver reads a SQLCipher 4 file that the Node driver wrote. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit and Safari on macOS | Real files in OPFS. |
114
+ | Two tabs share one file, and a tab hands it over only between transactions. A tab that dies in a transaction leaves the file readable without the writes of that transaction. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit and Safari on macOS | Two real tabs of one origin. |
115
+ | Two tabs that open a new store at the same time write one key. A reset fails with `INVALID_STATE` while another tab has the store open. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit and Safari on macOS | Two real tabs of one origin. |
116
+ | Without `'wasm-unsafe-eval'`, the open fails with `SQLITE_ENGINE_UNAVAILABLE` and writes no key. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit and Safari on macOS | A page under a policy without `'wasm-unsafe-eval'`. |
101
117
  | When the origin quota is full, a write and an atomic commit reject with `STORAGE_QUOTA_EXCEEDED` and leave no partial state. The store stays open, and after the clamp is removed, the same commit succeeds. A first open under a full quota rejects with `STORAGE_QUOTA_EXCEEDED`, writes no key and no database file, and succeeds after the clamp is removed. A store with two pool files opens, reads, and writes under a quota that has no room for a new pool. | Browser storage job: Chromium on Linux | A DevTools protocol call clamps the origin quota, and the store fills its real file in OPFS. Firefox and WebKit have no such call, so they do not run this check. |
118
+ | When a write of the engine fails with `QuotaExceededError`, the call fails with the SQLite full-disk error, which the store reports as `STORAGE_QUOTA_EXCEEDED`. The earlier rows stay, and after space frees, the same connection writes again and the file passes an integrity check. | Browser storage job: Chromium and Firefox on Linux. WebKit store job: WebKit and Safari on macOS | A fault in the worker makes each OPFS write that grows a file throw `QuotaExceededError`. It does not fill a real origin quota. |
102
119
  | Over a long run, the store holds latency, memory, and file size flat. A closed store leaves no worker and no lock of the store. Two tabs that write in turn each read the last write of the other. | Browser storage job: Chromium on Linux | 150 open, write, read, and close cycles, one session of 2,000 churn operations over 250 sessions, and 100 writes that two tabs make in turn. The check compares the medians of the early and late thirds of the run. It reads the page heap, and the heap and Wasm memory of the store's worker, through the DevTools protocol. Firefox and WebKit have no such protocol in the test runner, and no CI job runs this check in them. |
103
120
  | A worker without OPFS synchronous access handles fails with `OPFS_UNAVAILABLE` before it loads the engine. | Browser storage job: Chromium, Firefox, and WebKit on Linux | WebKit on Linux (WebKitGTK) has no OPFS synchronous access handles, so there WebKit runs only these checks and the checks that need no OPFS. |
104
121
 
105
- The WebKit store job runs Playwright's WebKit on macOS, where WebKit has OPFS synchronous access handles. It runs only on a change to the web SQLite store, the SQLite core, the storage contract, the key vault, the job, or a dependency. On a pull request, it runs only when a maintainer requests it. In the browser storage job for Chromium and Firefox and in the WebKit store job, a check that skips for want of OPFS fails.
122
+ The WebKit store job runs Playwright's WebKit on macOS, where WebKit has OPFS synchronous access handles. Playwright's WebKit is not Safari, so the same job then runs the same checks in the Safari of the macOS runner through `safaridriver`, and records the Safari version. A WebDriver runner runs the Playwright checks unchanged. It counts the workers of a page from inside the page, and it reports the uncaught errors of a page only after the page loads. Each browser context is a Safari WebDriver session, so the check for an ephemeral context that refuses OPFS access handles skips when that session has them. It runs only on a change to the web SQLite store, the SQLite core, the storage contract, the key vault, the job, or a dependency. On a pull request, it runs only when a maintainer requests it. In the browser storage job for Chromium and Firefox and in the WebKit store job, a check that skips for want of OPFS fails.
106
123
 
107
124
  The code-generation check in public CI runs the README example with the memory store. It does not load a SQLite store.
108
125
 
109
126
  ### Tauri
110
127
 
111
- No CI job runs a Tauri app. A Tauri 2 app uses `./local/store/web-sqlite` in its webview, with no Tauri-specific SDK code, so the web rows above check the same code in browsers. The [web SQLite store guide](../local/store/web-sqlite/README.md#tauri) gives the Tauri setup. On 2026-09-28, a manual check of a development build of the SDK before 8.0.0, in a Tauri 2.12.0 app, passed in WKWebView on macOS 15.7.2 and in the iOS 18.0 simulator. The check covered a two-device exchange, a close and reopen, an app relaunch, a relaunch after the app was killed with both stores open, and the store locks.
128
+ | Claim | Check | What the check runs |
129
+ |---|---|---|
130
+ | In a Tauri 2.12.0 app on Windows, the store opens in WebView2 with the default IndexedDB vault. Two new stores exchange one message each way. A second open of an open store fails with `INVALID_STATE`. After a close and a reopen, each store keeps its state and exchanges again. A relaunch in a new process reads the final state of the first launch and exchanges again. | Tauri example job: Windows x64, WebView2 153.0.4234.48 | A debug build of a Tauri example app that installs the packed package, launched twice. The app has no bundle and no installer. The app reports each step to its shell, and the job fails unless every step passes. A push to the main branch or a pull request runs this job only when it changes the example, the web SQLite entry, the web SQLite driver, or the job. On a pull request, the Windows leg runs only when a maintainer requests it. |
131
+ | In a Tauri 2.12.0 app on Linux, the first open fails with `OPFS_UNAVAILABLE`, because WebKitGTK has no OPFS synchronous access handles. No other step of the check runs. | Tauri example job: Linux x64, WebKitGTK 2.52.6 | The same app under Xvfb. The job fails when the first open succeeds or fails with a different code. |
132
+ | In a Tauri 2.12.0 app on Android, the store opens in the Android WebView with the default IndexedDB vault. Every step of the Windows check passes, including the relaunch in a new process. | Tauri example job: Android API 36 x86_64 emulator, Android WebView 133.0.6943.137 | A debug APK of the same app, installed on the emulator and launched twice. The app writes its report to its data directory, and the job reads the report with `adb`. The job fails unless every step passes. On a pull request, the Android leg runs only when a maintainer requests it. |
133
+
134
+ A Tauri 2 app uses `./local/store/web-sqlite` in its webview, with no Tauri-specific SDK code. The [web SQLite store guide](../local/store/web-sqlite/README.md#tauri) gives the Tauri setup. On 2026-09-28, a manual check of a development build of the SDK before 8.0.0, in a Tauri 2.12.0 app, passed in WKWebView on macOS 15.7.2 and in the iOS 18.0 simulator. The check covered a two-device exchange, a close and reopen, an app relaunch, a relaunch after the app was killed with both stores open, and the store locks.
135
+
136
+ On 2026-09-29, a manual check ran a debug build of the Tauri example with Tauri 2.12.0 in its shell. The app installed SDK 8.1.0, packed from the same commit as the example. On macOS 15.7.2 and in the iOS 17.5 simulator, every step of the first launch and of the relaunch passed. On macOS, two windows of the app shared one store. The second window opened the store that the first window held, and each window read the writes of the other. A reset in the second window failed with `INVALID_STATE`.
137
+
138
+ In the same check, `navigator.storage.persist()` returned `false` on macOS and in the iOS simulator. The app then cleared all website data of its webview, which removed the database file and the vault key. The next launch opened a new, empty store with no error.
112
139
 
113
140
  ### UNVERIFIED
114
141
 
115
142
  No CI job checks these items:
116
143
 
117
- - **Safari.** The WebKit store job runs Playwright's WebKit, not Safari. No check ran the web store in Safari.
118
- - **Tauri on WebView2 (Windows), the Android WebView, and WebKitGTK (Linux).** WebKitGTK 2.54 has no OPFS synchronous access handles, so the expected result of the open is `OPFS_UNAVAILABLE`. No run observed it.
119
- - **The React Native store on iOS and on physical devices.** No CI job opens `./local/store/react-native` on iOS. The manual check used only the iOS simulator. No check ran the store on a physical Android or iOS device.
144
+ - **A full origin quota in Firefox, WebKit, and Safari.** In these browsers, the quota check injects `QuotaExceededError` in the worker. No check fills a real origin quota there.
145
+ - **Tauri on macOS and iOS.** No CI job runs the Tauri example on macOS or iOS. The manual checks ran a debug build on macOS 15.7.2 and in the iOS 17.5 and 18.0 simulators. No check ran the store in a Tauri app on a physical iOS device.
146
+ - **A Tauri store that WebKit removes.** A check cleared all website data of the webview with a Tauri call. No check saw WebKit remove the data under storage pressure or after a period without use. No check removed the IndexedDB vault of a Tauri app while its database file stayed.
147
+ - **A Tauri release build, and Tauri on physical Android devices.** The Tauri example job runs a debug build with no bundle on Windows and Linux, and a debug APK on an Android API 36 emulator. No check ran the store in a release build, in an installed desktop app, on another Android API level, or on a physical Android device.
148
+ - **The React Native store on iOS and on physical devices.** No CI job opens `./local/store/react-native` on iOS. The manual checks used only the iOS simulator. No check ran the store on a physical Android or iOS device.
120
149
  - **iOS devices.** No CI job runs on iOS. The manual checks used only the iOS simulator.
121
- - **A packaged Electron app.** The Electron store job runs Electron from its npm package, not from an app build.
150
+ - **iOS Data Protection.** The simulator does not keep a file protection class. So no check recorded the class of the React Native store files. No check observed a file class or the keychain class enforced on a locked device.
151
+ - **An update of a notarized macOS Electron build through an updater.** The manual check copies the new build over the app. No check installed an update through Squirrel.Mac or another updater, or ran a notarized build on an Intel Mac.
152
+ - **Electron in a Flatpak or Snap sandbox.** There, the Secret portal gives each app its own key. No check ran it, and the vault refuses the portal key there too.
153
+ - **The `kwallet` backend (KWallet 4).** Ubuntu 24.04 and 26.04 do not have KWallet 4.
154
+ - **A KWallet wallet that the user opens.** The check opens a new wallet with `pamOpen`. No check opened a wallet at a password prompt or with `pam_kwallet` at login.
155
+
156
+ ## Realm backend: `./local/store/key-value/realm`
157
+
158
+ | Claim | Check | What the check runs |
159
+ |---|---|---|
160
+ | The Realm backend passes the key-value backend-conformance kit, including a close and a new open of the same Realm file. | Default automated checks: Linux, Node 26 | The kit on realm 20.2.0 in Node, over real Realm files. |
161
+
162
+ No CI job runs the Realm backend in a React Native app. On 2026-09-29, a manual check with Xcode 26.3 ran the kit on realm 20.2.0 in the iOS 26.2 simulator. The kit ran in a release build of the bare React Native example, with the SDK 8.1.0 package built from the main branch. All 13 cases passed on each of two launches. The SQLite store of the example passed in the same process. A build in which the backend skipped one write failed 7 of the 13 cases.
163
+
164
+ On 2026-09-28, a manual check ran the same kit in an Android emulator, and all 13 cases passed. No check ran the Realm backend on a physical device.
122
165
 
123
166
  ## Runtime checks for 2.0.1
124
167
 
@@ -771,8 +771,27 @@ that has none, and removes each local device record that the relay does not
771
771
  list. The time of the last read is kept in memory only, so a restarted client
772
772
  reads the list on its first send to each recipient.
773
773
 
774
- **Consequence.** A device linked less than 60 s before a send can miss that
775
- send, and a device removed less than 60 s before a send can still receive it.
774
+ On the hosted Relay, a direct send posts first and reads second when the
775
+ last successful read for that recipient in this process is at least 60 s and
776
+ less than 300 s old (`RECIPIENT_DEVICE_LIST_MAXIMUM_AGE_MILLISECONDS`). The
777
+ send posts to the known devices, and then reads the list. It encrypts the same
778
+ message for each newly listed device and posts it in the same send. It drops
779
+ a device that the Relay refused and the list no longer shows. The stored intent
780
+ records that its read is pending, so a replay after a crash reads the list
781
+ before it completes. A sender key distribution, and a send through the Convex
782
+ or memory relay, reads first as above.
783
+
784
+ **Consequence on the hosted Relay.** A device linked less than 60 s before a
785
+ send can miss that send. A device linked 60 s to 300 s before a send receives
786
+ it when the read in that send succeeds. A removed device receives no message,
787
+ because the Relay refuses the device's mailbox before the list shows the
788
+ removal. The 300 s maximum limits only how long a client posts first on a list
789
+ that no read confirmed.
790
+
791
+ **Consequence on the Convex and memory relays.** A device linked less than
792
+ 60 s before a send can miss that send, and a device removed less than 60 s
793
+ before a send can still receive it.
794
+
776
795
  The SESAME stale-device-list retry loop (`StaleDeviceListError`) stays in
777
796
  `internal/sesame/manager.ts`, but no caller supplies a device-list version, so
778
797
  it never runs.
@@ -19,7 +19,7 @@
19
19
  <p id="status" role="status">Ready</p>
20
20
  <pre id="output" aria-label="Execution output" tabindex="0"></pre>
21
21
  <p>The browser console shows the same results. Ciphertext changes on each run.</p>
22
- <p><a href="https://github.com/open-e2ee/signal-protocol-js/tree/v8.1.0/examples/browser/src/exchange.ts">Read the exchange code</a> · <a href="https://stackblitz.com/fork/github/open-e2ee/signal-protocol-js/tree/v8.1.0/examples/browser">Edit on StackBlitz</a></p>
22
+ <p><a href="https://github.com/open-e2ee/signal-protocol-js/tree/v8.2.0/examples/browser/src/exchange.ts">Read the exchange code</a> · <a href="https://stackblitz.com/fork/github/open-e2ee/signal-protocol-js/tree/v8.2.0/examples/browser">Edit on StackBlitz</a></p>
23
23
  <p>Continue with <a href="https://docs.open-e2ee.dev/start/browser">browser storage</a>, <a href="https://docs.open-e2ee.dev/start/expo">Expo / Hermes setup</a>, or <a href="https://open-e2ee.dev/relay">the OpenE2EE Signal Protocol Relay for separate devices</a>.</p>
24
24
  </main>
25
25
  <script type="module" src="/src/main.ts"></script>
package/hooks/README.md CHANGED
@@ -10,6 +10,16 @@ The core SDK is framework-neutral. React hooks live on a separate package
10
10
  subpath. Non-React consumers therefore do not load React, and UI code can
11
11
  subscribe to SDK state without duplicating effect cleanup.
12
12
 
13
+ ## Setup
14
+
15
+ Install the peers `react` 19.0.0 or later and `react-native` 0.83.6 or later.
16
+ The entry loads both, also in a web app: the relay lifecycle and key rotation
17
+ hooks read `AppState` from `react-native`.
18
+
19
+ ```sh
20
+ npm install react react-native
21
+ ```
22
+
13
23
  ## Usage
14
24
 
15
25
  ```tsx
@@ -59,8 +69,7 @@ for example while an Android foreground service runs. Outside React, call
59
69
  `bindRelayLifecycle(signal, AppState)` from
60
70
  `@open-e2ee/signal-protocol-sdk/client`.
61
71
 
62
- Install a compatible React version when importing this subpath. Do not call
63
- these hooks outside React components or custom hooks. Event callbacks from
72
+ Do not call these hooks outside React components or custom hooks. Event callbacks from
64
73
  `SignalProtocolClient.registerHook()` are a separate, framework-neutral API.
65
74
 
66
75
  See the [client guide](../client/README.md) and
@@ -47,11 +47,11 @@ Options:
47
47
  `open-e2ee-signal-protocol.db`.
48
48
  - `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
49
49
  Default: `ExpoSecureStoreSignalProtocolSecretVault`.
50
- - `encryptionAtRest`: pass `false` to store the database without encryption,
51
- for example on the web, where `expo-sqlite` has no SQLCipher. The store then
52
- does not use the vault, and it logs a warning at each open. A database
53
- created with one setting does not open with the other. Default: `true`, and
54
- the open fails when the build has no SQLCipher.
50
+ - `encryptionAtRest`: pass `false` to store the database without encryption.
51
+ The store then does not use the vault, and it logs a warning at each open. A
52
+ database created with one setting does not open with the other. Default:
53
+ `true`, and the open fails when the build has no SQLCipher (see
54
+ [Web](#web)).
55
55
  - `logger`: receives the warning of each open without encryption.
56
56
 
57
57
  A store holds its name until `close()`. In one process, the opens and resets
@@ -62,6 +62,19 @@ and the second open fails.
62
62
  Keep application tables in a separate database file. The SDK database holds
63
63
  only SDK tables.
64
64
 
65
+ ## Web
66
+
67
+ The web build of `expo-sqlite` has no SQLCipher, and Expo SecureStore has no
68
+ web implementation. On the web, `expoStore()` and `resetExpoStore()` therefore
69
+ fail with `SqliteEncryptionUnavailableError` (`KEY_STORAGE_ERROR`). They fail
70
+ before they use the vault or a database file, also when the app passes its own
71
+ vault. A native build without the `useSQLCipher` option fails in the same way.
72
+
73
+ For an encrypted store in a browser, use
74
+ [`./local/store/web-sqlite`](../web-sqlite/README.md). `encryptionAtRest: false`
75
+ opens this store on the web without encryption. Use it only when the app
76
+ accepts protocol state in plaintext in the browser storage of the origin.
77
+
65
78
  ## Lost key and reset
66
79
 
67
80
  When the database file exists and the vault holds no key for it, `expoStore`
@@ -132,9 +132,11 @@ Realm file. If you already use a Realm, add `realmKeyValueSchema` to its schema
132
132
  list, or open a separate Realm file for the store.
133
133
 
134
134
  The adapter is tested with the conformance kit on realm 20.2.0 in Node,
135
- including a reopen of the same Realm file. The SDK does not test it on a
136
- device. Run the conformance kit on your target devices with your Realm build
137
- before you ship.
135
+ including a reopen of the same Realm file. Manual checks ran the kit in
136
+ React Native apps in the iOS 26.2 simulator and in an Android emulator. All
137
+ 13 cases passed in each. The SDK does not test the adapter
138
+ on a physical device. Run the conformance kit on your target devices with
139
+ your Realm build before you ship.
138
140
 
139
141
  ### Realm maintenance status
140
142
 
@@ -61,7 +61,8 @@ only SDK tables.
61
61
 
62
62
  Use a supported Electron major: the Electron team supports the latest three
63
63
  stable majors ([release timelines](https://www.electronjs.org/docs/latest/tutorial/electron-timelines)).
64
- CI tests Electron 44 on Linux, macOS, and Windows. The binding uses Node-API,
64
+ CI tests the latest major, Electron 44, on Linux, macOS, and Windows, and the
65
+ oldest supported major, Electron 42, on Linux. The binding uses Node-API,
65
66
  so its prebuild loads in each supported major without a rebuild.
66
67
 
67
68
  Open the store in the main process, with the vault over Electron's
@@ -148,10 +148,12 @@ move to the other after an error that is not `OPFS_UNAVAILABLE`.
148
148
  ## Tauri
149
149
 
150
150
  A Tauri 2 app uses this entry in its webview. The entry runs unchanged in
151
- WKWebView on macOS and iOS. A manual check ran it with Tauri 2.12 on macOS
152
- 15.7 and in the iOS 18.0 simulator. No CI job runs it in Tauri. It needs no
153
- Tauri headers (`app.security.headers`) and no capability, because the store
154
- makes no IPC call.
151
+ WebView2 on Windows, in the Android WebView, and in WKWebView on macOS and iOS.
152
+ A CI job runs it in a Tauri 2.12 app in WebView2 on Windows and in the Android
153
+ WebView on an Android emulator. Manual checks ran it with Tauri 2.12 on
154
+ macOS 15.7 and in the iOS 17.5 and 18.0 simulators. It needs no Tauri headers
155
+ (`app.security.headers`) and no capability, because the store makes no IPC
156
+ call.
155
157
 
156
158
  Put the policy from [Content Security Policy](#content-security-policy) in
157
159
  `app.security.csp` of `tauri.conf.json`. When the app uses Tauri IPC, add the
@@ -183,11 +185,29 @@ IPC sources to `connect-src`:
183
185
  where the webview keeps its data. Set these values before the first release,
184
186
  and never change them. A change moves the data, and the app then cannot find
185
187
  its database or its vault.
186
- - **Linux.** WebKitGTK 2.54 has no OPFS synchronous access handles. On it,
187
- the expected result of the open is a rejection with `OPFS_UNAVAILABLE`. See
188
+ - **Windows of one app.** Each window of the app is its own JavaScript
189
+ context. The windows of one origin share the database. A reset fails
190
+ with `INVALID_STATE` while any window holds the store. See [Tabs](#tabs).
191
+ - **Website data.** The database and the vault key are website data of the
192
+ webview. In WKWebView, `navigator.storage.persist()` returns `false`, so
193
+ the webview does not promise to keep them. A clear of all website data,
194
+ for example with `clear_all_browsing_data`, removes the database and the
195
+ key together. The next open then creates a new, empty store and reports
196
+ no error. The open fails with `LOCAL_STORE_KEY_LOST` only when the file
197
+ stays and the key goes. See [Lost key and reset](#lost-key-and-reset).
198
+ - **Loss of all data.** The app must find a loss of all website data itself.
199
+ For example, write a marker to the store with `setMetadata`. Keep a record
200
+ in the app data directory, outside the webview data, that the device has a
201
+ store. When the record exists and the marker does not, treat the device as
202
+ a new device. Do not clear the website data of the webview that holds the
203
+ store.
204
+ - **Linux.** WebKitGTK has no OPFS synchronous access handles, so the open
205
+ rejects with `OPFS_UNAVAILABLE`. A CI job checks this refusal in a Tauri
206
+ app with WebKitGTK 2.52. See
188
207
  [When OPFS is not available](#when-opfs-is-not-available).
189
- - **Windows and Android.** WebView2 and the Android WebView are not yet
190
- tested.
208
+ - **Android.** A CI job runs every check in a debug APK in the Android
209
+ WebView 133 on an Android API 36 emulator, and every check passes. The
210
+ origin of the webview is `http://tauri.localhost`.
191
211
  - **Key custody.** The default vault keeps the key in IndexedDB in the same
192
212
  origin as the database. An app that needs OS keychain custody passes its own
193
213
  vault. See [Security boundary](#security-boundary).