@open-e2ee/signal-protocol-sdk 14.2.0 → 14.3.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 (93) hide show
  1. package/ADAPTERS.md +2 -2
  2. package/ARCHITECTURE.md +1 -1
  3. package/CHANGELOG.md +90 -0
  4. package/README.md +9 -9
  5. package/SECURITY.md +2 -2
  6. package/client/README.md +6 -5
  7. package/device/README.md +2 -1
  8. package/dist/client/client.d.ts +43 -42
  9. package/dist/client/client.d.ts.map +1 -1
  10. package/dist/client/client.js +54 -53
  11. package/dist/client/client.js.map +1 -1
  12. package/dist/client/compose.d.ts +5 -5
  13. package/dist/client/compose.d.ts.map +1 -1
  14. package/dist/client/compose.js +1 -1
  15. package/dist/client/config.d.ts +16 -16
  16. package/dist/client/config.d.ts.map +1 -1
  17. package/dist/client/content-adapter.d.ts +5 -5
  18. package/dist/client/content-adapter.d.ts.map +1 -1
  19. package/dist/client/content-adapter.js +6 -6
  20. package/dist/client/content-adapter.js.map +1 -1
  21. package/dist/client/device-set-reconciliation.d.ts +1 -1
  22. package/dist/client/device-set-reconciliation.js +1 -1
  23. package/dist/client/event-hooks.d.ts +4 -9
  24. package/dist/client/event-hooks.d.ts.map +1 -1
  25. package/dist/client/event-hooks.js +12 -7
  26. package/dist/client/event-hooks.js.map +1 -1
  27. package/dist/client/hosted-http-error.d.ts +1 -1
  28. package/dist/client/hosted-http-error.js +1 -1
  29. package/dist/client/hosted-sandbox-identity.d.ts +2 -2
  30. package/dist/client/hosted-sandbox-identity.js +2 -2
  31. package/dist/client/hosted-transport.d.ts +4 -4
  32. package/dist/client/hosted-transport.d.ts.map +1 -1
  33. package/dist/client/hosted-transport.js +2 -2
  34. package/dist/client/hosted-transport.js.map +1 -1
  35. package/dist/client/hosted.d.ts +17 -17
  36. package/dist/client/hosted.d.ts.map +1 -1
  37. package/dist/client/hosted.js +1 -1
  38. package/dist/client/send-deadline.d.ts +1 -1
  39. package/dist/client/send-deadline.d.ts.map +1 -1
  40. package/dist/client/send-deadline.js +4 -3
  41. package/dist/client/send-deadline.js.map +1 -1
  42. package/dist/client/signal-relay-lifecycle.d.ts +3 -4
  43. package/dist/client/signal-relay-lifecycle.d.ts.map +1 -1
  44. package/dist/client/signal-relay-lifecycle.js +3 -4
  45. package/dist/client/signal-relay-lifecycle.js.map +1 -1
  46. package/dist/client/signal-relay-subscription.d.ts +1 -1
  47. package/dist/client/signal-service-cipher.d.ts +3 -3
  48. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  49. package/dist/client/signal-service-cipher.js +5 -5
  50. package/dist/client/signal-service-cipher.js.map +1 -1
  51. package/dist/client/types.d.ts +4 -4
  52. package/dist/client/types.d.ts.map +1 -1
  53. package/dist/hooks/use-signal-relay-connection-state.d.ts +2 -3
  54. package/dist/hooks/use-signal-relay-connection-state.d.ts.map +1 -1
  55. package/dist/hooks/use-signal-relay-connection-state.js.map +1 -1
  56. package/dist/index.d.ts +5 -4
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +2 -1
  59. package/dist/index.js.map +1 -1
  60. package/dist/internal/groups/authority-certificate.d.ts +4 -3
  61. package/dist/internal/groups/authority-certificate.d.ts.map +1 -1
  62. package/dist/internal/groups/authority-certificate.js.map +1 -1
  63. package/dist/remote/signal-relay/types.d.ts +12 -11
  64. package/dist/remote/signal-relay/types.d.ts.map +1 -1
  65. package/dist/types/api.d.ts +15 -15
  66. package/dist/types/api.d.ts.map +1 -1
  67. package/dist/types/errors.d.ts +19 -12
  68. package/dist/types/errors.d.ts.map +1 -1
  69. package/dist/types/errors.js +20 -13
  70. package/dist/types/errors.js.map +1 -1
  71. package/dist/types/renamed-member.d.ts +13 -6
  72. package/dist/types/renamed-member.d.ts.map +1 -1
  73. package/dist/types/renamed-member.js +11 -6
  74. package/dist/types/renamed-member.js.map +1 -1
  75. package/docs/ASSURANCE.md +9 -9
  76. package/docs/CLIENT_COMPOSITION.md +4 -4
  77. package/docs/DEVIATIONS.md +2 -2
  78. package/docs/ERROR_HANDLING.md +3 -3
  79. package/docs/GETTING_STARTED.md +4 -3
  80. package/docs/INTERFACES.md +3 -3
  81. package/docs/PACKAGE_SURFACE.md +1 -1
  82. package/docs/PROTOCOL_POLICY.md +4 -4
  83. package/docs/RECIPES.md +7 -6
  84. package/local/store/expo/README.md +1 -1
  85. package/local/store/key-value/README.md +1 -1
  86. package/local/store/node/README.md +1 -1
  87. package/local/store/react-native/README.md +1 -1
  88. package/local/store/web/README.md +1 -1
  89. package/local/store/web-sqlite/README.md +1 -1
  90. package/package.json +1 -1
  91. package/remote/README.md +2 -2
  92. package/remote/object-store/convex-r2/README.md +1 -1
  93. package/remote/signal-relay/README.md +3 -2
@@ -13,9 +13,10 @@
13
13
  * import { createHostedSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
14
14
  *
15
15
  * // Supply a device-local store and the configured identity-provider callback.
16
+ * const signalRelayUrl = process.env.OPEN_E2EE_SIGNAL_RELAY_URL!;
16
17
  * const signal = await createHostedSignalProtocolClient({
17
18
  * adapters: { storage },
18
- * hosted: { signalProtocolRelayUrl, getIdentityAssertion },
19
+ * hosted: { relayUrl: signalRelayUrl, getIdentityAssertion },
19
20
  * });
20
21
  *
21
22
  * await signal.send(recipientUserId, 'Hello!');
@@ -25,7 +26,7 @@
25
26
  * ```typescript
26
27
  * const signal = await createSignalProtocolClient({
27
28
  * identity: { userId },
28
- * adapters: { storage, signalProtocolRelay },
29
+ * adapters: { storage, relay },
29
30
  * protocol: { postQuantum: 'required', braid: 'required' },
30
31
  * });
31
32
  * ```
@@ -36,7 +37,7 @@
36
37
  *
37
38
  * const signal = await DefaultSignalProtocolClient.create(userId, {
38
39
  * storage,
39
- * signalProtocolRelay,
40
+ * relay,
40
41
  * });
41
42
  * ```
42
43
  */
@@ -296,30 +297,30 @@ export class DefaultSignalProtocolClient {
296
297
  * The connection state of the relay subscription. Reads `stopped` when no
297
298
  * relay is configured.
298
299
  *
299
- * @see SignalProtocolClient.signalProtocolRelayConnectionState
300
+ * @see SignalProtocolClient.relayConnectionState
300
301
  */
302
+ get relayConnectionState() {
303
+ return this.signalProtocolRelayConnectionState;
304
+ }
305
+ /** @deprecated Use `relayConnectionState`. SDK 15.0.0 removes this name. */
301
306
  get signalProtocolRelayConnectionState() {
302
307
  return ((this.signalProtocolRelay && signalProtocolRelayConnectionStateOf(this.signalProtocolRelay)) ??
303
308
  this.stoppedSignalProtocolRelayConnection);
304
309
  }
305
- /** @deprecated Use `signalProtocolRelayConnectionState`. SDK 15.0.0 removes this name. */
306
- get relayConnectionState() {
307
- return this.signalProtocolRelayConnectionState;
308
- }
309
310
  /**
310
311
  * Subscribe to relay connection transitions. Without a relay, the listener
311
312
  * never runs.
312
313
  *
313
- * @see SignalProtocolClient.subscribeSignalProtocolRelayConnectionState
314
+ * @see SignalProtocolClient.subscribeRelayConnectionState
314
315
  */
316
+ subscribeRelayConnectionState(listener) {
317
+ return this.subscribeSignalProtocolRelayConnectionState(listener);
318
+ }
319
+ /** @deprecated Use `subscribeRelayConnectionState`. SDK 15.0.0 removes this name. */
315
320
  subscribeSignalProtocolRelayConnectionState(listener) {
316
321
  return ((this.signalProtocolRelay && subscribeSignalProtocolRelayConnectionStateOf(this.signalProtocolRelay, listener)) ??
317
322
  (() => undefined));
318
323
  }
319
- /** @deprecated Use `subscribeSignalProtocolRelayConnectionState`. SDK 15.0.0 removes this name. */
320
- subscribeRelayConnectionState(listener) {
321
- return this.subscribeSignalProtocolRelayConnectionState(listener);
322
- }
323
324
  signalProtocolRelayUnsubscribe;
324
325
  /**
325
326
  * Cached sender certificate for sealed sender.
@@ -334,7 +335,7 @@ export class DefaultSignalProtocolClient {
334
335
  state = new SignalProtocolClientState();
335
336
  /**
336
337
  * The delivery receipt sends in progress, from a batch timer, the batch
337
- * bound, stopSignalProtocolRelaySubscription(), or stop(): the relay work item of each
338
+ * bound, stopRelaySubscription(), or stop(): the relay work item of each
338
339
  * send, and the promise that settles when the send finishes. While stop()
339
340
  * holds the batches, only stop() starts a send. stop() waits until its
340
341
  * receipt deadline for the sends that are in progress when it starts,
@@ -345,7 +346,7 @@ export class DefaultSignalProtocolClient {
345
346
  /**
346
347
  * Posts the stored retry requests at their next attempt times, ends them
347
348
  * at their deadlines, and calls `onRetryTerminal`. create() and
348
- * startSignalProtocolRelaySubscription() start it when a relay is configured, and stop()
349
+ * startRelaySubscription() start it when a relay is configured, and stop()
349
350
  * stops it. Each pass is relay work, so its hooks run through that work.
350
351
  */
351
352
  retryRequests = new RetryRequestScheduler(this.state.signalRelayWork, (work) => {
@@ -1250,10 +1251,10 @@ export class DefaultSignalProtocolClient {
1250
1251
  * });
1251
1252
  *
1252
1253
  * // With an application-owned authenticated relay transport.
1253
- * const signalProtocolRelay = appSignalProtocolRelayTransport;
1254
+ * const relay = appSignalProtocolRelayTransport;
1254
1255
  * const signal = await DefaultSignalProtocolClient.create('user-123', {
1255
1256
  * storage,
1256
- * signalProtocolRelay,
1257
+ * relay,
1257
1258
  * onProgress: ({ stage, percent, message }) => {
1258
1259
  * console.log(`${stage}: ${percent}% - ${message}`);
1259
1260
  * }
@@ -1263,7 +1264,7 @@ export class DefaultSignalProtocolClient {
1263
1264
  * const signal = await DefaultSignalProtocolClient.create('user-123', {
1264
1265
  * deviceId: 1,
1265
1266
  * storage,
1266
- * signalProtocolRelay,
1267
+ * relay,
1267
1268
  * protocol: { postQuantum: 'required', braid: 'required' },
1268
1269
  * onProgress,
1269
1270
  * enableDebugLogging: true,
@@ -2449,7 +2450,7 @@ export class DefaultSignalProtocolClient {
2449
2450
  *
2450
2451
  * The content reaches onMessageDecrypted in a later pass of the receive
2451
2452
  * queue, after this call returns. After `stop()`, the content waits for
2452
- * the next start of the queue from `startSignalProtocolRelaySubscription`, or for
2453
+ * the next start of the queue from `startRelaySubscription`, or for
2453
2454
  * `processPendingReceives`.
2454
2455
  */
2455
2456
  async receiveIncomingEnvelopes(envelopes) {
@@ -2912,7 +2913,7 @@ export class DefaultSignalProtocolClient {
2912
2913
  * @example
2913
2914
  * ```typescript
2914
2915
  * // In ServicesProvider: wire up ContentManager after creation
2915
- * const signal = await DefaultSignalProtocolClient.create(userId, { storage, signalProtocolRelay });
2916
+ * const signal = await DefaultSignalProtocolClient.create(userId, { storage, relay });
2916
2917
  * const content = new ContentManager({ db, signal });
2917
2918
  *
2918
2919
  * signal.registerHook('onMessageDecrypted', content.getDecryptionHook());
@@ -2936,25 +2937,7 @@ export class DefaultSignalProtocolClient {
2936
2937
  // ============================================================================
2937
2938
  // SIGNAL PROTOCOL RELAY SUBSCRIPTION (Auto-decrypt and notify ContentManager via hook)
2938
2939
  // ============================================================================
2939
- /**
2940
- * Start relay subscription for automatic message decryption
2941
- *
2942
- * When configured with both `relay` and `onMessageDecrypted` hook, DefaultSignalProtocolClient will:
2943
- * 1. Subscribe to incoming envelopes from the relay
2944
- * 2. Decrypt messages appropriately (pairwise vs group/sender key)
2945
- * 3. Call onMessageDecrypted hook with DecryptedEnvelope (for ContentManager storage)
2946
- * 4. Mark messages as delivered on the relay
2947
- *
2948
- * This enables ContentManager to store decrypted content in an encrypted SQLite
2949
- * database without any knowledge of cryptography.
2950
- *
2951
- * Callers can run this manually after registering hooks via registerHook().
2952
- * Called automatically by create() when relay + hook configured.
2953
- * A call while stop() runs is refused and logged; start again after stop()
2954
- * resolves.
2955
- *
2956
- * @see SignalProtocolClient.startSignalProtocolRelaySubscription
2957
- */
2940
+ /** @deprecated Use `startRelaySubscription`. SDK 15.0.0 removes this name. */
2958
2941
  startSignalProtocolRelaySubscription() {
2959
2942
  if (!this.signalProtocolRelay) {
2960
2943
  this.logger.warn('Cannot start relay subscription: relay not configured', {
@@ -3073,21 +3056,29 @@ export class DefaultSignalProtocolClient {
3073
3056
  setSignalProtocolRelayBatching(active) {
3074
3057
  readRenamedImplementation(this.contentAdapter, 'setSignalProtocolRelayBatching', 'setRelayBatching')?.(active);
3075
3058
  }
3076
- /** @deprecated Use `startSignalProtocolRelaySubscription`. SDK 15.0.0 removes this name. */
3077
- startRelaySubscription() {
3078
- this.startSignalProtocolRelaySubscription();
3079
- }
3080
3059
  /**
3081
- * Stop the relay subscription
3060
+ * Start relay subscription for automatic message decryption
3082
3061
  *
3083
- * Pauses message processing via the relay subscription without destroying
3084
- * DefaultSignalProtocolClient state. startSignalProtocolRelaySubscription() restarts the subscription.
3062
+ * When configured with both `relay` and `onMessageDecrypted` hook, DefaultSignalProtocolClient will:
3063
+ * 1. Subscribe to incoming envelopes from the relay
3064
+ * 2. Decrypt messages appropriately (pairwise vs group/sender key)
3065
+ * 3. Call onMessageDecrypted hook with DecryptedEnvelope (for ContentManager storage)
3066
+ * 4. Mark messages as delivered on the relay
3085
3067
  *
3086
- * Use this when the app backgrounds to let the background task handle messages.
3087
- * Resume when the app foregrounds for real-time message delivery.
3068
+ * This enables ContentManager to store decrypted content in an encrypted SQLite
3069
+ * database without any knowledge of cryptography.
3088
3070
  *
3089
- * @see SignalProtocolClient.stopSignalProtocolRelaySubscription
3071
+ * Callers can run this manually after registering hooks via registerHook().
3072
+ * Called automatically by create() when relay + hook configured.
3073
+ * A call while stop() runs is refused and logged; start again after stop()
3074
+ * resolves.
3075
+ *
3076
+ * @see SignalProtocolClient.startRelaySubscription
3090
3077
  */
3078
+ startRelaySubscription() {
3079
+ this.startSignalProtocolRelaySubscription();
3080
+ }
3081
+ /** @deprecated Use `stopRelaySubscription`. SDK 15.0.0 removes this name. */
3091
3082
  stopSignalProtocolRelaySubscription() {
3092
3083
  // Send the batched delivery receipts before unsubscribing. During the
3093
3084
  // hold, stop() sends the batches that wait at each of its flushes and
@@ -3104,7 +3095,17 @@ export class DefaultSignalProtocolClient {
3104
3095
  });
3105
3096
  }
3106
3097
  }
3107
- /** @deprecated Use `stopSignalProtocolRelaySubscription`. SDK 15.0.0 removes this name. */
3098
+ /**
3099
+ * Stop the relay subscription
3100
+ *
3101
+ * Pauses message processing via the relay subscription without destroying
3102
+ * DefaultSignalProtocolClient state. startRelaySubscription() restarts the subscription.
3103
+ *
3104
+ * Use this when the app backgrounds to let the background task handle messages.
3105
+ * Resume when the app foregrounds for real-time message delivery.
3106
+ *
3107
+ * @see SignalProtocolClient.stopRelaySubscription
3108
+ */
3108
3109
  stopRelaySubscription() {
3109
3110
  this.stopSignalProtocolRelaySubscription();
3110
3111
  }
@@ -3301,7 +3302,7 @@ export class DefaultSignalProtocolClient {
3301
3302
  * waits for those sends until the same deadline. It does this again while
3302
3303
  * the deadline is not past. stop() holds the receipt batches from its
3303
3304
  * first flush until it clears its tracking state. During the hold,
3304
- * stopSignalProtocolRelaySubscription() does not send them, and stop() drops a receipt
3305
+ * stopRelaySubscription() does not send them, and stop() drops a receipt
3305
3306
  * batched after its last flush. At the deadline it stops each receipt
3306
3307
  * send that is left: a send that waits in an app hook stops, and that
3307
3308
  * receipt is not sent. A send that is in its relay call at the deadline
@@ -3316,7 +3317,7 @@ export class DefaultSignalProtocolClient {
3316
3317
  * the work after the hook and writes nothing more. The relay delivers the
3317
3318
  * envelope again after the next start.
3318
3319
  *
3319
- * A call to startSignalProtocolRelaySubscription() while stop() runs is refused and
3320
+ * A call to startRelaySubscription() while stop() runs is refused and
3320
3321
  * logged; start again after stop() resolves. A stop() call that overlaps a
3321
3322
  * running stop() waits for it and settles as it settles.
3322
3323
  *
@@ -3365,7 +3366,7 @@ export class DefaultSignalProtocolClient {
3365
3366
  // progress, except a send that an earlier stop() stopped, and start the
3366
3367
  // send of the batched delivery receipts, once each, as relay work. Until
3367
3368
  // the end of step 6, a delivery that finishes batches its receipt with no
3368
- // timer, and stopSignalProtocolRelaySubscription() does not send it. Step 5 sends the
3369
+ // timer, and stopRelaySubscription() does not send it. Step 5 sends the
3369
3370
  // batches that wait at the end of each wait, again while the deadline is
3370
3371
  // not past. A receipt batched after its last flush is dropped in step 6
3371
3372
  const receiptDeadline = Date.now() + SignalProtocolRelaySubscriptionOps.STOP_RECEIPT_FLUSH_MS;