@open-e2ee/signal-protocol-sdk 0.1.0-alpha.13 → 0.1.0-alpha.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../local/store/react-native/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,mFAAmF;IACnF,WAAW,CAAC,UAAU,EAAE,SAAS,4BAA4B,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AACnD,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AACzF;;;GAGG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC"}
1
+ {"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../local/store/react-native/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,mFAAmF;IACnF,WAAW,CAAC,UAAU,EAAE,SAAS,4BAA4B,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AACnD,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AACzF;;;GAGG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC"}
package/docs/ASSURANCE.md CHANGED
@@ -33,12 +33,12 @@ Most recent full run — 2026-08-10:
33
33
 
34
34
  | | |
35
35
  |---|---|
36
- | Modules executed | 381 |
37
- | Assertions | 6,864 |
38
- | Passed | 6,862 |
36
+ | Modules executed | 384 |
37
+ | Assertions | 6,893 |
38
+ | Passed | 6,891 |
39
39
  | Skipped | 2 |
40
40
  | Failed | 0 |
41
- | Wall time | 253 s |
41
+ | Wall time | 330 s |
42
42
 
43
43
  Longer-running performance and endurance checks are excluded from that figure
44
44
  and run under separate commands.
@@ -66,8 +66,11 @@ Coverage spans, in the terms this documentation uses elsewhere:
66
66
  browser adapter's contract suites additionally run inside real Chromium,
67
67
  Firefox, and WebKit pages on every change, and a soak run drives thousands
68
68
  of full open/write/read/close cycles through the browser adapter in
69
- Chromium on every change, failing on upward memory or latency drift; the
70
- assertions target the adapter's contract, and the engines are the
69
+ Chromium on every change, failing on upward memory or latency drift. The
70
+ React Native adapter's exported backend-conformance kit runs against its
71
+ reference backend on the Hermes engine on every change, and interruption
72
+ and storage-pressure suites drive the adapter over that backend. In every
73
+ case the assertions target the adapter's contract, and the engines are the
71
74
  environment it must honor that contract in, not the subject of the tests.
72
75
  - **Public surface** — the exported API shape and the quickstart printed in the
73
76
  [README](../README.md), which is executed as written on every change.
@@ -163,7 +163,8 @@ Expo storage or Convex helpers.
163
163
  `clearDatabaseKeyCache`, and `createPreKeyMaintenanceStore`
164
164
  - `IndexedDbSignalProtocolStore` / `indexedDbStore()` for browsers
165
165
  - `ReactNativeSignalProtocolStore` / `reactNativeStore()` for bare React Native
166
- (experimental; provide your own key-value backend)
166
+ (provide your own key-value backend and verify it with the exported
167
+ backend-conformance kit)
167
168
  - `NodeSignalProtocolStore` / `nodeStore()` for Node environments
168
169
  - `InMemorySignalProtocolStore` / `inMemoryStore()` for local development
169
170
  - custom implementations via `ISignalProtocolLocalStore`
@@ -34,14 +34,17 @@ and recovery helpers, and it graduated from experimental by completing every
34
34
  gate on the checklist below. Deployment still requires the origin-security
35
35
  review described in the [web adapter guide](./web/README.md).
36
36
 
37
- ### Experimental
37
+ ### Bare React Native
38
38
 
39
39
  - `ReactNativeSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/react-native` (create it with `await ReactNativeSignalProtocolStore.create({ storage })` and provide your own key-value backend)
40
40
 
41
- This experimental adapter implements the full core store contract, including
42
- SESAME records, sender-key state, retry message records, and recovery helpers.
43
- It remains experimental because its platform hardening and long-run
44
- operational behavior require further deployment evidence.
41
+ Use this for bare React Native applications that supply their own key-value
42
+ backend. It implements the full core store contract, including SESAME records,
43
+ sender-key state, retry message records, and recovery helpers, and it
44
+ graduated from experimental by completing every gate on the checklist below.
45
+ The supplied backend is the application's responsibility: verify it with the
46
+ exported backend-conformance kit described in the
47
+ [React Native adapter guide](./react-native/README.md).
45
48
 
46
49
  #### Graduation checklist
47
50
 
@@ -85,13 +88,36 @@ honor its promises in, not the subject of a test.
85
88
  change to the source repository, and `npm run soak:web-store` runs
86
89
  longer sessions on demand.
87
90
 
88
- `ReactNativeSignalProtocolStore`:
91
+ `ReactNativeSignalProtocolStore` (graduated; the gates keep running):
89
92
 
90
- - [ ] Exported backend-conformance kit: the SDK cannot test an
93
+ - [x] Exported backend-conformance kit: the SDK cannot test an
91
94
  application-supplied `storage` backend, so it ships the contract suite
92
- the application runs against its own backend.
93
- - [ ] Reference backend passes that kit on Hermes in CI.
94
- - [ ] Interruption and storage-pressure tests against the reference backend.
95
+ the application runs against its own backend. `runBackendConformance`
96
+ and `assertBackendConformance` execute thirteen cases against any
97
+ `ReactNativeKeyValueStorage`: round-trips, key listing, batch removal,
98
+ in-order atomic application, checks evaluated against pre-batch state,
99
+ null-guarded creation, all-or-nothing failure, exact-userId session
100
+ removal with in-batch visibility, one winner between concurrent
101
+ guarded batches, and durability across reopen. A jest gate proves the
102
+ kit catches a non-atomic backend, a prefix-matching session removal,
103
+ and an unserialized backend, on every change to the source repository.
104
+ - [x] Reference backend passes that kit on Hermes in CI.
105
+ `createReferenceReactNativeBackend` is the executable specification of
106
+ the backend contract, and a named gate bundles the kit with esbuild
107
+ and runs it against the reference backend on the sha256-pinned Hermes
108
+ CLI — the engine React Native ships with — on every change to the
109
+ source repository. The runner requires an explicit pass sentinel
110
+ because Hermes exits 0 on an unhandled async rejection.
111
+ - [x] Interruption and storage-pressure tests against the reference
112
+ backend. A simulated process kill before commit leaves each atomic
113
+ security write — session/trust commit, identity rotation, trust
114
+ verification — fully absent after reopen, and an identical retry lands
115
+ it fully applied. Quota exhaustion surfaces as the typed
116
+ `StorageQuotaExceededError` (`STORAGE_QUOTA_EXCEEDED`), never a silent
117
+ partial write: a jest suite drives quota-shaped backend failures
118
+ through every write path, and a real-quota run over the reference
119
+ backend observes the typed rejection, no partial state, and a clean
120
+ retry once space frees. Runs on every change to the source repository.
95
121
 
96
122
  ### Node
97
123
 
@@ -166,7 +192,9 @@ can leave a concurrently-created session trusted under a rotated identity.
166
192
  still requires review of key custody, backups, and host security.
167
193
  - `@open-e2ee/signal-protocol-sdk/local/store/expo` is also the package home for Expo-specific
168
194
  integration helpers that a real app composes directly.
169
- - Experimental adapters may cover the same contract surface, but should still be positioned carefully until their platform security/performance characteristics are battle-tested.
195
+ - An adapter carries the experimental label until every item on its
196
+ graduation checklist is a named, continuously running CI gate. Both the web
197
+ and bare React Native adapters have completed theirs.
170
198
  - Storage adapters should expose the real package contract instead of app-specific wrappers.
171
199
 
172
200
  ## Related Docs
@@ -32,8 +32,40 @@ compare-and-swap checks and commit all writes, removals, and exact per-user
32
32
  session deletion atomically and durably, including across process termination.
33
33
  A batched sequence of independent writes is not sufficient.
34
34
 
35
- This adapter remains experimental because key custody, crash recovery, backup
36
- behavior, and transaction guarantees depend on the supplied native backend.
35
+ ## Verifying your backend
36
+
37
+ The adapter's guarantees hold only over a backend that honors the
38
+ `ReactNativeKeyValueStorage` contract, and the SDK cannot test the backend
39
+ your application supplies. The package therefore exports a
40
+ backend-conformance kit — run it against your backend from your
41
+ application's own tests:
42
+
43
+ ```ts
44
+ import {
45
+ assertBackendConformance,
46
+ createReferenceReactNativeBackend,
47
+ } from "@open-e2ee/signal-protocol-sdk/local/store/react-native";
48
+
49
+ await assertBackendConformance({
50
+ createBackend: () => createMyBackend(),
51
+ // Optional: return a new instance over the same persistence medium to
52
+ // verify committed writes survive reopen. Reported as skipped when absent.
53
+ reopen: (previous) => reopenMyBackend(previous),
54
+ });
55
+ ```
56
+
57
+ `assertBackendConformance` throws one error naming every failing case;
58
+ `runBackendConformance` returns the structured result instead.
59
+ `createReferenceReactNativeBackend` is the executable specification of the
60
+ contract: an in-memory backend that passes the kit, useful as a comparison
61
+ point and as a test double. Continuous integration runs the kit against the
62
+ reference backend on the Hermes engine, and drives the adapter over it
63
+ through interruption and storage-pressure suites; the checklist that
64
+ graduated this adapter is in the parent [storage guide](../README.md).
65
+
66
+ Key custody, crash durability, and backup behavior remain properties of your
67
+ chosen native storage engine — the kit verifies contract semantics, and your
68
+ deployment review must still cover the engine itself.
37
69
 
38
70
  See the parent [storage guide](../README.md), [adapter guide](../../../ADAPTERS.md),
39
71
  and [security model](../../../docs/SECURITY.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.1.0-alpha.13",
3
+ "version": "0.1.0-alpha.14",
4
4
  "description": "Signal Protocol E2EE SDK for TypeScript — Expo, React Native, browser, and Node. Post-quantum PQXDH and Double Ratchet.",
5
5
  "keywords": [
6
6
  "open-e2ee",