@open-e2ee/signal-protocol-sdk 4.0.0 → 5.0.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 (92) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/README.md +2 -2
  3. package/SECURITY.md +2 -2
  4. package/client/README.md +3 -3
  5. package/dist/client/client.d.ts +9 -20
  6. package/dist/client/client.d.ts.map +1 -1
  7. package/dist/client/client.js +9 -22
  8. package/dist/client/client.js.map +1 -1
  9. package/dist/client/config.d.ts +25 -25
  10. package/dist/client/headless.d.ts +9 -20
  11. package/dist/client/headless.d.ts.map +1 -1
  12. package/dist/client/headless.js +22 -67
  13. package/dist/client/headless.js.map +1 -1
  14. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  15. package/dist/client/hosted-anonymous-delivery.js +15 -2
  16. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  17. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  18. package/dist/client/hosted-mailbox-subscription.js +32 -0
  19. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  20. package/dist/client/hosted-transport.d.ts +14 -7
  21. package/dist/client/hosted-transport.d.ts.map +1 -1
  22. package/dist/client/hosted-transport.js +81 -60
  23. package/dist/client/hosted-transport.js.map +1 -1
  24. package/dist/client/key-rotation-core.d.ts +46 -69
  25. package/dist/client/key-rotation-core.d.ts.map +1 -1
  26. package/dist/client/key-rotation-core.js +161 -256
  27. package/dist/client/key-rotation-core.js.map +1 -1
  28. package/dist/client/key-rotation.d.ts +14 -29
  29. package/dist/client/key-rotation.d.ts.map +1 -1
  30. package/dist/client/key-rotation.js +37 -61
  31. package/dist/client/key-rotation.js.map +1 -1
  32. package/dist/client/one-time-prekey-refill.d.ts +52 -0
  33. package/dist/client/one-time-prekey-refill.d.ts.map +1 -0
  34. package/dist/client/one-time-prekey-refill.js +79 -0
  35. package/dist/client/one-time-prekey-refill.js.map +1 -0
  36. package/dist/client/prekeys.d.ts.map +1 -1
  37. package/dist/client/prekeys.js +38 -73
  38. package/dist/client/prekeys.js.map +1 -1
  39. package/dist/client/signal-service-cipher.d.ts +1 -1
  40. package/dist/client/signal-service-cipher.js +2 -2
  41. package/dist/client/signal-service-cipher.js.map +1 -1
  42. package/dist/client/types.d.ts +1 -1
  43. package/dist/device/lifecycle/manager.d.ts.map +1 -1
  44. package/dist/device/lifecycle/manager.js +0 -3
  45. package/dist/device/lifecycle/manager.js.map +1 -1
  46. package/dist/device/lifecycle/types.d.ts +1 -9
  47. package/dist/device/lifecycle/types.d.ts.map +1 -1
  48. package/dist/device/lifecycle/utils.d.ts +2 -4
  49. package/dist/device/lifecycle/utils.d.ts.map +1 -1
  50. package/dist/device/lifecycle/utils.js +2 -4
  51. package/dist/device/lifecycle/utils.js.map +1 -1
  52. package/dist/hooks/index.d.ts +1 -2
  53. package/dist/hooks/index.d.ts.map +1 -1
  54. package/dist/hooks/index.js +0 -1
  55. package/dist/hooks/index.js.map +1 -1
  56. package/dist/hooks/use-key-rotation.d.ts +2 -5
  57. package/dist/hooks/use-key-rotation.d.ts.map +1 -1
  58. package/dist/hooks/use-key-rotation.js +8 -5
  59. package/dist/hooks/use-key-rotation.js.map +1 -1
  60. package/dist/hooks/use-single-flight.d.ts +4 -4
  61. package/dist/hooks/use-single-flight.js +4 -4
  62. package/dist/index.d.ts +2 -2
  63. package/dist/index.d.ts.map +1 -1
  64. package/dist/index.js.map +1 -1
  65. package/dist/internal/manager/manager.d.ts +4 -4
  66. package/dist/internal/manager/manager.js +4 -4
  67. package/dist/local/store/expo/models/ec-one-time-prekey.d.ts.map +1 -1
  68. package/dist/local/store/expo/models/ec-one-time-prekey.js +4 -6
  69. package/dist/local/store/expo/models/ec-one-time-prekey.js.map +1 -1
  70. package/dist/local/store/expo/models/kyber-one-time-prekey.d.ts.map +1 -1
  71. package/dist/local/store/expo/models/kyber-one-time-prekey.js +4 -8
  72. package/dist/local/store/expo/models/kyber-one-time-prekey.js.map +1 -1
  73. package/dist/remote/relay/memory/adapter.d.ts +2 -14
  74. package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
  75. package/dist/remote/relay/memory/adapter.js +5 -58
  76. package/dist/remote/relay/memory/adapter.js.map +1 -1
  77. package/dist/remote/relay/types.d.ts +20 -64
  78. package/dist/remote/relay/types.d.ts.map +1 -1
  79. package/dist/safety/index.d.ts +2 -2
  80. package/dist/safety/index.js +2 -2
  81. package/dist/types/api.d.ts +25 -13
  82. package/dist/types/api.d.ts.map +1 -1
  83. package/docs/ASSURANCE.md +4 -4
  84. package/docs/ERROR_HANDLING.md +2 -2
  85. package/docs/PACKAGE_SURFACE.md +1 -2
  86. package/examples/browser/index.html +1 -1
  87. package/hooks/README.md +4 -14
  88. package/package.json +1 -5
  89. package/dist/hooks/use-connection-presence.d.ts +0 -66
  90. package/dist/hooks/use-connection-presence.d.ts.map +0 -1
  91. package/dist/hooks/use-connection-presence.js +0 -298
  92. package/dist/hooks/use-connection-presence.js.map +0 -1
@@ -1,56 +1,46 @@
1
1
  /**
2
2
  * Key Rotation Core
3
3
  *
4
- * Shared rotation logic that works with SignalProtocolRelayServer interface.
5
- * Used by both:
4
+ * Shared rotation logic that works with the SignalProtocolRelayServer
5
+ * interface. Used by both:
6
6
  * - SignalProtocolClient (foreground, via key-rotation.ts)
7
7
  * - Background tasks (headless, via headless.ts)
8
8
  *
9
- * This module handles the actual key generation and upload logic,
10
- * independent of React context or specific backend implementation.
9
+ * One rotation reads the inventory once, decides which of the EC signed
10
+ * prekey, the KEM last-resort prekey, and the one-time prekey batches are due,
11
+ * and publishes every due key in one publication. A rotation with nothing due
12
+ * costs one inventory read and no publication.
11
13
  *
12
14
  * ## Thread Safety
13
15
  *
14
- * Uses per-key-type AsyncLock to prevent race conditions when multiple
15
- * callers attempt key rotation concurrently. This protects against:
16
- * - Multiple React components calling rotation simultaneously
17
- * - Background tasks racing with foreground rotation
18
- * - Network requests completing out of order
19
- *
20
- * The lock wraps the entire check → generate → upload → store sequence
21
- * to make key rotation atomic.
16
+ * A per-identity AsyncLock serializes concurrent rotations for one device, so
17
+ * two callers cannot both generate and publish different keys. The lock wraps
18
+ * the whole read → decide → generate → publish → store sequence.
22
19
  *
23
20
  * ## Transactional Pattern
24
21
  *
25
- * Key rotation uses upload-first ordering for consistency:
26
- * 1. Check if rotation needed (metadata from server)
27
- * 2. Generate new key locally
28
- * 3. Upload to server (may fail - local state unchanged)
29
- * 4. Store locally only after successful upload
22
+ * Signed keys use publish-first ordering:
23
+ * 1. Read the inventory (through the relay adapter's publication fence)
24
+ * 2. Generate the due keys locally
25
+ * 3. Publish (may fail - the signed keys are not stored)
26
+ * 4. Store the signed keys locally only after the publication succeeds
30
27
  *
31
- * This keeps client and server in sync. If upload fails, local state does not
32
- * change, and the caller can safely retry rotation.
28
+ * One-time prekeys are stored before the publication, because their private
29
+ * halves must exist before a peer can consume the public halves.
33
30
  */
34
31
  import { type Logger } from '../logger.js';
35
- import type { SignalProtocolLocalStore } from '../types/index.js';
32
+ import type { PreKeyRotationResult, SignalProtocolLocalStore } from '../types/index.js';
36
33
  import type { IdentityType } from '../keys/types.js';
37
- import type { SignalProtocolRelayServer } from '../remote/relay/types.js';
34
+ import type { PreKeyInventory, SignalProtocolRelayServer } from '../remote/relay/types.js';
38
35
  import { type PreKeyMaintenanceStore } from './config.js';
39
36
  /**
40
37
  * Lock for key rotation operations.
41
38
  *
42
- * Prevents concurrent callers from both generating and uploading different keys,
43
- * which would result in one upload overwriting the other.
44
- *
45
- * Uses per-key-type locks so signed and Kyber rotations do not block each other.
39
+ * One lock per user, device, and identity type. A rotation holds it for the
40
+ * whole read, decide, publish, and store sequence.
46
41
  */
47
42
  export {};
48
- /**
49
- * Minimum one-time prekeys before replenishment starts.
50
- * When the count drops below this threshold, the client generates and uploads
51
- * new prekeys.
52
- */
53
- export declare const MIN_PREKEY_REPLENISHMENT_THRESHOLD = 10;
43
+ export { MIN_PREKEY_REPLENISHMENT_THRESHOLD } from './one-time-prekey-refill.js';
54
44
  /**
55
45
  * Check if a key needs rotation based on age
56
46
  *
@@ -81,20 +71,6 @@ export declare function shouldRotateKey(createdAt: number, expiresAt: number, re
81
71
  * @see https://signal.org/docs/specifications/pqxdh/#publishing-keys
82
72
  */
83
73
  export declare function isPreKeyExpired(createdAt: number, maxAgeMs?: number): boolean;
84
- /**
85
- * Core signed prekey rotation
86
- *
87
- * Generates a new signed prekey and uploads to server.
88
- * Works without React context.
89
- *
90
- * @param relay - Signal Protocol relay server interface
91
- * @param userId - User identifier
92
- * @param deviceId - Device identifier
93
- * @param providedStorage - Local store instance for the current runtime
94
- * @param refreshIntervalMs - Custom refresh interval (defaults to 2 days)
95
- * @returns true if the function rotated the key
96
- */
97
- export declare function rotateEcSignedPreKeyCore(relay: SignalProtocolRelayServer, userId: string, deviceId: number, providedStorage?: SignalProtocolLocalStore, refreshIntervalMs?: number, identityTypes?: readonly IdentityType[], logger?: Required<Logger>): Promise<boolean>;
98
74
  /**
99
75
  * The key id for the next Kyber last-resort prekey of one identity type.
100
76
  *
@@ -103,35 +79,36 @@ export declare function rotateEcSignedPreKeyCore(relay: SignalProtocolRelayServe
103
79
  * with no current key starts at 1.
104
80
  */
105
81
  export declare function nextKyberLastResortPreKeyId(storage: Pick<SignalProtocolLocalStore, 'getKyberPreKey'>, identityType: IdentityType): Promise<number>;
82
+ /** Options for one prekey rotation. */
83
+ export interface PreKeyRotationOptions {
84
+ /** Signed-key refresh interval (defaults to 2 days). */
85
+ refreshIntervalMs?: number;
86
+ /** One-time prekey count below which a refill starts (defaults to 10). */
87
+ threshold?: number;
88
+ /** Identity types to rotate (defaults to the active identity types). */
89
+ identityTypes?: readonly IdentityType[];
90
+ /** App-provided replaced-prekey maintenance store. */
91
+ preKeyMaintenance?: PreKeyMaintenanceStore;
92
+ logger?: Required<Logger>;
93
+ }
94
+ /** Whether one inventory calls for a refill of either one-time prekey set. */
95
+ export declare function oneTimePreKeysDue(inventory: PreKeyInventory, threshold: number): boolean;
106
96
  /**
107
- * Core post-quantum KEM prekey rotation.
108
- *
109
- * Generates fresh ML-KEM/Kyber-compatible key material and uploads it to the
110
- * relay.
111
- * Works without React context.
97
+ * Rotate the prekeys of one device: one inventory read and one publication
98
+ * per identity type.
112
99
  *
113
- * @param relay - Signal Protocol relay server interface
114
- * @param userId - User identifier
115
- * @param deviceId - Device identifier
116
- * @param providedStorage - Local store instance for the current runtime
117
- * @param refreshIntervalMs - Custom refresh interval (defaults to 2 days)
118
- * @returns true if the function rotated the key
119
- */
120
- export declare function rotateKyberPreKeyCore(relay: SignalProtocolRelayServer, userId: string, deviceId: number, providedStorage?: SignalProtocolLocalStore, refreshIntervalMs?: number, identityTypes?: readonly IdentityType[], logger?: Required<Logger>): Promise<boolean>;
121
- /**
122
- * Check and replenish one-time prekeys if running low
100
+ * Per PQXDH spec Section 3.2, the EC signed prekey and the KEM last-resort
101
+ * prekey rotate on the same schedule. The one-time prekey batches refill in
102
+ * the same publication when a server count is below the threshold. Nothing
103
+ * due costs one inventory read.
123
104
  *
124
- * Iterates both ACI and PNI identity types for consistency with
125
- * rotateEcSignedPreKeyCore and rotateKyberPreKeyCore.
105
+ * A failed identity type is reported in `errors` and does not stop the other
106
+ * identity types. The result booleans are true when any identity type rotated
107
+ * that key.
126
108
  *
127
- * @param relay - Signal Protocol relay server interface
128
- * @param userId - User identifier
129
- * @param deviceId - Device identifier
130
- * @param storage - Key storage for local persistence
131
- * @param threshold - Minimum number of prekeys before replenishment (default: 10)
132
- * @returns true if the function replenished both identity types
109
+ * @see https://signal.org/docs/specifications/pqxdh/#publishing-keys
133
110
  */
134
- export declare function replenishOneTimePreKeysCore(relay: SignalProtocolRelayServer, userId: string, deviceId: number, storage: SignalProtocolLocalStore, threshold?: number, identityTypes?: readonly IdentityType[], preKeyMaintenance?: PreKeyMaintenanceStore, logger?: Required<Logger>): Promise<boolean>;
111
+ export declare function rotatePreKeysCore(relay: SignalProtocolRelayServer, userId: string, deviceId: number, providedStorage?: SignalProtocolLocalStore, options?: PreKeyRotationOptions): Promise<PreKeyRotationResult>;
135
112
  /**
136
113
  * Result of pre-send prekey validation
137
114
  */
@@ -1 +1 @@
1
- {"version":3,"file":"key-rotation-core.d.ts","sourceRoot":"","sources":["../../client/key-rotation-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,UAAU,CAAC;AAElB;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC;AA+GV;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,iBAAiB,GAAE,MAAwC,GAC1D,OAAO,CAMT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAkC,GAC3C,OAAO,CAGT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,wBAAwB,EAC1C,iBAAiB,GAAE,MAAwC,EAC3D,aAAa,GAAE,SAAS,YAAY,EAAmB,EACvD,MAAM,GAAE,QAAQ,CAAC,MAAM,CAA+B,GACrD,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAgFD;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,IAAI,CAAC,wBAAwB,EAAE,gBAAgB,CAAC,EACzD,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,wBAAwB,EAC1C,iBAAiB,GAAE,MAAwC,EAC3D,aAAa,GAAE,SAAS,YAAY,EAAmB,EACvD,MAAM,GAAE,QAAQ,CAAC,MAAM,CAA+B,GACrD,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAwFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,wBAAwB,EACjC,SAAS,GAAE,MAA2C,EACtD,aAAa,GAAE,SAAS,YAAY,EAAmB,EACvD,iBAAiB,CAAC,EAAE,sBAAsB,EAC1C,MAAM,GAAE,QAAQ,CAAC,MAAM,CAA+B,GACrD,OAAO,CAAC,OAAO,CAAC,CAiBlB;AAkFD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,wBAAwB,EAClC,QAAQ,GAAE,MAAkC,EAC5C,YAAY,GAAE,YAAoB,EAClC,MAAM,GAAE,QAAQ,CAAC,MAAM,CAA+B,GACrD,OAAO,CAAC,qBAAqB,CAAC,CAkGhC"}
1
+ {"version":3,"file":"key-rotation-core.d.ts","sourceRoot":"","sources":["../../client/key-rotation-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAG/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAgB,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEtG,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,UAAU,CAAC;AAOlB;;;;;GAKG;AACH,OAAO,EAAE,CAAC;AA6GV,OAAO,EAAE,kCAAkC,EAAE,MAAM,0BAA0B,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,iBAAiB,GAAE,MAAwC,GAC1D,OAAO,CAMT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAkC,GAC3C,OAAO,CAGT;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,IAAI,CAAC,wBAAwB,EAAE,gBAAgB,CAAC,EACzD,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC3B;AASD,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAExF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,wBAAwB,EAC1C,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CAyC/B;AAkID;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,wBAAwB,EAClC,QAAQ,GAAE,MAAkC,EAC5C,YAAY,GAAE,YAAoB,EAClC,MAAM,GAAE,QAAQ,CAAC,MAAM,CAA+B,GACrD,OAAO,CAAC,qBAAqB,CAAC,CAgEhC"}