@open-e2ee/signal-protocol-sdk 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/ADAPTERS.md +7 -0
  2. package/ARCHITECTURE.md +2 -0
  3. package/CHANGELOG.md +33 -0
  4. package/README.md +64 -102
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +7 -0
  7. package/blocking/README.md +1 -0
  8. package/client/README.md +10 -0
  9. package/device/README.md +5 -0
  10. package/dist/client/groups.d.ts.map +1 -1
  11. package/dist/client/groups.js +14 -4
  12. package/dist/client/groups.js.map +1 -1
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +3 -4
  15. package/dist/index.js.map +1 -1
  16. package/dist/internal/sesame/types.d.ts +0 -2
  17. package/dist/internal/sesame/types.d.ts.map +1 -1
  18. package/dist/internal/sesame/types.js +0 -2
  19. package/dist/internal/sesame/types.js.map +1 -1
  20. package/dist/media/index.d.ts +0 -1
  21. package/dist/media/index.d.ts.map +1 -1
  22. package/dist/media/index.js +0 -1
  23. package/dist/media/index.js.map +1 -1
  24. package/dist/remote/relay/convex/backend.d.ts +2 -2
  25. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  26. package/dist/remote/relay/convex/backend.js +1 -1
  27. package/dist/remote/relay/convex/backend.js.map +1 -1
  28. package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
  29. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  30. package/dist/remote/relay/convex/component/messages.d.ts +2 -2
  31. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  32. package/dist/remote/relay/convex/component/messages.js +1 -1
  33. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  34. package/dist/remote/relay/convex/component/schema.d.ts +2 -2
  35. package/dist/remote/relay/convex/component/schema.js +1 -1
  36. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  37. package/dist/utils/retry.d.ts +2 -1
  38. package/dist/utils/retry.d.ts.map +1 -1
  39. package/dist/utils/retry.js +2 -1
  40. package/dist/utils/retry.js.map +1 -1
  41. package/docs/ASSURANCE.md +11 -5
  42. package/docs/CLIENT_COMPOSITION.md +3 -0
  43. package/docs/DOCUMENTATION_STANDARDS.md +28 -0
  44. package/docs/ERROR_HANDLING.md +91 -60
  45. package/docs/GETTING_STARTED.md +20 -1
  46. package/docs/INTERFACES.md +5 -0
  47. package/docs/PACKAGE_SURFACE.md +1 -0
  48. package/docs/PROTOCOL_POLICY.md +6 -0
  49. package/docs/RECIPES.md +9 -0
  50. package/encoding/README.md +1 -0
  51. package/files/README.md +1 -0
  52. package/groups/README.md +1 -0
  53. package/keys/README.md +2 -0
  54. package/local/store/README.md +2 -0
  55. package/local/store/expo/README.md +2 -0
  56. package/local/store/memory/README.md +2 -0
  57. package/local/store/node/README.md +1 -0
  58. package/local/store/react-native/README.md +2 -0
  59. package/local/store/web/README.md +1 -0
  60. package/local/vault/README.md +1 -0
  61. package/media/README.md +2 -0
  62. package/package.json +4 -2
  63. package/profile/README.md +1 -0
  64. package/remote/README.md +6 -0
  65. package/remote/object-store/README.md +1 -0
  66. package/remote/object-store/convex-r2/README.md +2 -0
  67. package/remote/object-store/s3/README.md +1 -0
  68. package/remote/relay/README.md +2 -0
  69. package/remote/relay/convex/README.md +1 -0
  70. package/remote/relay/convex/component/README.md +9 -0
  71. package/remote/relay/memory/README.md +2 -0
  72. package/safety/README.md +1 -0
  73. package/sealed-sender/README.md +1 -0
  74. package/types/README.md +1 -0
  75. package/username/README.md +1 -0
  76. package/utils/README.md +1 -0
  77. package/zk/README.md +1 -0
@@ -14,6 +14,7 @@ security or persistence boundary.
14
14
 
15
15
  ## Usage
16
16
 
17
+ <!-- doc-snippet:run memory-store-client expect="" -->
17
18
  ```ts
18
19
  // Real protocol and cryptography; simulated in-memory infrastructure.
19
20
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -33,6 +34,7 @@ application discards the adapter. Never use this adapter for production accounts
33
34
  Failure mode is opt-in. A seed and cadence replay the same failing writes, or
34
35
  you can target the next named store operation:
35
36
 
37
+ <!-- doc-snippet:run memory-store-failure-injection expect="" -->
36
38
  ```ts
37
39
  // Real protocol and cryptography; simulated in-memory infrastructure.
38
40
  import {
@@ -20,6 +20,7 @@ boundary while allowing each deployment to choose an explicit data directory.
20
20
 
21
21
  ## Usage
22
22
 
23
+ <!-- doc-snippet:skip requires-external-context -->
23
24
  ```ts
24
25
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
25
26
  import { nodeStore } from "@open-e2ee/signal-protocol-sdk/local/store/node";
@@ -11,6 +11,7 @@ needed for trust, session, and one-time-prekey transitions.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
16
17
  import {
@@ -40,6 +41,7 @@ your application supplies. The package therefore exports a
40
41
  backend-conformance kit. Run it against your backend from your application's
41
42
  own tests:
42
43
 
44
+ <!-- doc-snippet:skip requires-external-context -->
43
45
  ```ts
44
46
  import {
45
47
  assertBackendConformance,
@@ -11,6 +11,7 @@ the browser-origin threat model explicit.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
16
17
  import { indexedDbStore } from "@open-e2ee/signal-protocol-sdk/local/store/web";
@@ -13,6 +13,7 @@ platform keychain.
13
13
 
14
14
  ## Expo usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import { ExpoSecureStoreSignalProtocolSecretVault } from "@open-e2ee/signal-protocol-sdk/local/vault/expo-secure-store";
18
19
 
package/media/README.md CHANGED
@@ -18,6 +18,7 @@ The remote object store never receives the media key or plaintext.
18
18
 
19
19
  ## Upload and send
20
20
 
21
+ <!-- doc-snippet:skip requires-external-context -->
21
22
  ```ts
22
23
  import {
23
24
  createMediaAttachmentMessage,
@@ -43,6 +44,7 @@ await signal.send(
43
44
 
44
45
  ## Receive and open
45
46
 
47
+ <!-- doc-snippet:skip requires-external-context -->
46
48
  ```ts
47
49
  import {
48
50
  parseMediaAttachmentMessage,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
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",
@@ -353,7 +353,8 @@
353
353
  "build:fix-esm": "node ./scripts/fix-esm-specifiers.mjs ./dist",
354
354
  "clean": "rm -rf dist",
355
355
  "typecheck": "tsc --noEmit -p tsconfig.build.json",
356
- "docs:api": "npx -y -p typedoc@0.28 -p typedoc-plugin-markdown@4 -p typescript@5.8 typedoc && node ./scripts/normalize-api-doc-paths.mjs",
356
+ "docs:api": "npx -y -p typedoc@0.28.20 -p typedoc-plugin-markdown@4.12.0 -p typescript@5.8.3 typedoc && node ./scripts/normalize-api-doc-paths.mjs",
357
+ "docs:api:check": "npm run docs:api && git diff --exit-code -- docs/api && test -z \"$(git ls-files --others --exclude-standard docs/api)\"",
357
358
  "prepare": "npm run build",
358
359
  "prepublishOnly": "npm run build"
359
360
  },
@@ -435,6 +436,7 @@
435
436
  "devDependencies": {
436
437
  "@convex-dev/r2": "^0.10.2",
437
438
  "@convex-dev/rate-limiter": "^0.3.2",
439
+ "@swc/core": "^1.15.43",
438
440
  "@types/async-lock": "^1.4.0",
439
441
  "@types/node": "^22.0.0",
440
442
  "@types/react": "^19.0.0",
package/profile/README.md CHANGED
@@ -12,6 +12,7 @@ encrypted fields and does not receive those keys.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  decryptProfileName,
package/remote/README.md CHANGED
@@ -29,6 +29,7 @@ replaceable and prevent them from owning private keys or plaintext.
29
29
 
30
30
  ## Composition
31
31
 
32
+ <!-- doc-snippet:skip requires-production-adapters -->
32
33
  ```ts
33
34
  import { SignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
34
35
  import {
@@ -95,6 +96,7 @@ application installs, mounts, and configures `@convex-dev/r2`, owns the R2
95
96
  bucket and credentials, and exposes authenticated app-owned functions for
96
97
  create, download, completion, and deletion.
97
98
 
99
+ <!-- doc-snippet:skip requires-external-context -->
98
100
  ```ts
99
101
  import { SignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
100
102
  import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
@@ -118,6 +120,7 @@ time-sensitive credentials or await provider metadata. The functions
118
120
  The optional server entry point removes repetitive broker plumbing without
119
121
  taking ownership away from the application:
120
122
 
123
+ <!-- doc-snippet:skip requires-external-context -->
121
124
  ```ts
122
125
  // convex/signalObjectStore.ts
123
126
  import { R2 } from "@convex-dev/r2";
@@ -174,6 +177,7 @@ on that backend. The broker follows the same identity contract: it receives a
174
177
  retry-stable `requestId`, reserves the private provider key, and returns the
175
178
  canonical `objectId`.
176
179
 
180
+ <!-- doc-snippet:skip requires-external-context -->
177
181
  ```ts
178
182
  import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
179
183
 
@@ -194,7 +198,9 @@ needed to authorize and construct short-lived operations.
194
198
 
195
199
  Use `InMemorySignalProtocolRelayServer` when multiple clients need a shared in-memory relay:
196
200
 
201
+ <!-- doc-snippet:run remote-shared-memory-relay expect="" -->
197
202
  ```ts
203
+ // Real protocol and cryptography; simulated in-memory infrastructure.
198
204
  import { SignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
199
205
  import { InMemorySignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
200
206
  import { InMemorySignalProtocolStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
@@ -18,6 +18,7 @@ retry-stable requestId -> canonical objectId -> private provider key
18
18
 
19
19
  ## Custom broker usage
20
20
 
21
+ <!-- doc-snippet:skip requires-external-context -->
21
22
  ```ts
22
23
  import type {
23
24
  SignalProtocolRemoteObjectStore,
@@ -13,6 +13,7 @@ component ownership into the SDK.
13
13
 
14
14
  ## Client usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
18
19
  import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
@@ -40,6 +41,7 @@ by `ConvexR2ObjectStoreApi`.
40
41
  The server-only subpath supplies validators and broker mechanics while keeping
41
42
  authorization and persistence in application callbacks:
42
43
 
44
+ <!-- doc-snippet:skip requires-external-context -->
43
45
  ```ts
44
46
  import { R2 } from "@convex-dev/r2";
45
47
  import {
@@ -11,6 +11,7 @@ returned by that backend.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
16
17
 
@@ -13,7 +13,9 @@ plaintext ownership to the backend.
13
13
 
14
14
  ## Local usage
15
15
 
16
+ <!-- doc-snippet:run relay-memory-client expect="" -->
16
17
  ```ts
18
+ // Real protocol and cryptography; simulated in-memory infrastructure.
17
19
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
18
20
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
19
21
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
@@ -21,6 +21,7 @@ functions, retention policy, and operational controls.
21
21
  Organize the application functions under one generated module namespace, then
22
22
  pass that namespace directly:
23
23
 
24
+ <!-- doc-snippet:skip requires-external-context -->
24
25
  ```ts
25
26
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
26
27
  import {
@@ -16,6 +16,7 @@ public wrappers.
16
16
 
17
17
  Mount the component in the app's Convex configuration:
18
18
 
19
+ <!-- doc-snippet:skip requires-external-context -->
19
20
  ```ts
20
21
  // convex/convex.config.ts
21
22
  import { defineApp } from 'convex/server';
@@ -89,6 +90,7 @@ O(versions × state size) per group.
89
90
  Create the wrapper once with the mounted component reference and the app's
90
91
  authentication hook:
91
92
 
93
+ <!-- doc-snippet:skip requires-external-context -->
92
94
  ```ts
93
95
  // convex/relayBackend.ts
94
96
  import { components } from './_generated/api';
@@ -113,6 +115,7 @@ export const signalRelay = defineConvexSignalProtocolBackend(
113
115
  The relay reads these functions through `api.signal`, so the modules must live
114
116
  inside that namespace rather than at the top of `convex/`:
115
117
 
118
+ <!-- doc-snippet:skip requires-external-context -->
116
119
  ```ts
117
120
  // convex/signal/groups.ts
118
121
  import { signalRelay } from '../relayBackend';
@@ -127,6 +130,7 @@ export const {
127
130
  } = signalRelay.groups;
128
131
  ```
129
132
 
133
+ <!-- doc-snippet:skip requires-external-context -->
130
134
  ```ts
131
135
  // convex/signal/zkAuth.ts
132
136
  import { signalRelay } from '../relayBackend';
@@ -139,6 +143,7 @@ export const {
139
143
 
140
144
  Mount the remaining relay namespaces alongside those group modules:
141
145
 
146
+ <!-- doc-snippet:skip requires-external-context -->
142
147
  ```ts
143
148
  // convex/signal/messages.ts
144
149
  import { signalRelay } from '../relayBackend';
@@ -155,6 +160,7 @@ export const {
155
160
  } = signalRelay.messages;
156
161
  ```
157
162
 
163
+ <!-- doc-snippet:skip requires-external-context -->
158
164
  ```ts
159
165
  // convex/signal/devices.ts
160
166
  import { signalRelay } from '../relayBackend';
@@ -168,6 +174,7 @@ export const {
168
174
  } = signalRelay.devices;
169
175
  ```
170
176
 
177
+ <!-- doc-snippet:skip requires-external-context -->
171
178
  ```ts
172
179
  // convex/signal/keys.ts
173
180
  import { signalRelay } from '../relayBackend';
@@ -185,12 +192,14 @@ export const {
185
192
  } = signalRelay.keys;
186
193
  ```
187
194
 
195
+ <!-- doc-snippet:skip requires-external-context -->
188
196
  ```ts
189
197
  // convex/signal/certificates.ts
190
198
  import { signalRelay } from '../relayBackend';
191
199
  export const { issueSenderCertificate } = signalRelay.certificates;
192
200
  ```
193
201
 
202
+ <!-- doc-snippet:skip requires-external-context -->
194
203
  ```ts
195
204
  // convex/signal/provisioning.ts
196
205
  import { signalRelay } from '../relayBackend';
@@ -14,6 +14,7 @@ authorization or durability boundary.
14
14
 
15
15
  ## Usage
16
16
 
17
+ <!-- doc-snippet:run memory-relay-client expect="" -->
17
18
  ```ts
18
19
  // Real protocol and cryptography; simulated in-memory infrastructure.
19
20
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -38,6 +39,7 @@ abuse, or deliver durably. Never use it in production.
38
39
  Failure mode is opt-in and seeded. The default `inMemoryRelay()` remains the
39
40
  deterministic happy path:
40
41
 
42
+ <!-- doc-snippet:run memory-relay-failure-injection expect="" -->
41
43
  ```ts
42
44
  // Real protocol and cryptography; simulated in-memory infrastructure.
43
45
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
package/safety/README.md CHANGED
@@ -12,6 +12,7 @@ decision.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import { generateCompositeSafetyNumber } from "@open-e2ee/signal-protocol-sdk/safety";
17
18
 
@@ -12,6 +12,7 @@ contract.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  ACCESS_KEY_BYTES,
package/types/README.md CHANGED
@@ -12,6 +12,7 @@ contracts they validate.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import type {
17
18
  ISignalProtocolLocalStore,
@@ -11,6 +11,7 @@ helps applications avoid treating display text as a stable account identifier.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  formatUsername,
package/utils/README.md CHANGED
@@ -11,6 +11,7 @@ internals.
11
11
 
12
12
  ## Retry usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  isRetryableError,
package/zk/README.md CHANGED
@@ -12,6 +12,7 @@ group secrets and profile keys on the service.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  computeProfileKeyVersion,