@open-e2ee/signal-protocol-sdk 0.1.0-alpha.1 → 0.1.0-alpha.3

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 (43) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README.md +8 -15
  3. package/dist/client/client.d.ts +8 -5
  4. package/dist/client/client.d.ts.map +1 -1
  5. package/dist/client/client.js +8 -5
  6. package/dist/client/client.js.map +1 -1
  7. package/dist/client/prekeys.js +1 -1
  8. package/dist/client/prekeys.js.map +1 -1
  9. package/dist/internal/sesame/manager.d.ts.map +1 -1
  10. package/dist/internal/sesame/manager.js +50 -18
  11. package/dist/internal/sesame/manager.js.map +1 -1
  12. package/dist/internal/sesame/types.d.ts.map +1 -1
  13. package/dist/internal/sesame/types.js +7 -2
  14. package/dist/internal/sesame/types.js.map +1 -1
  15. package/dist/keys/identity.d.ts +32 -0
  16. package/dist/keys/identity.d.ts.map +1 -1
  17. package/dist/keys/identity.js +55 -0
  18. package/dist/keys/identity.js.map +1 -1
  19. package/dist/keys/index.d.ts +1 -1
  20. package/dist/keys/index.d.ts.map +1 -1
  21. package/dist/keys/index.js +1 -1
  22. package/dist/keys/index.js.map +1 -1
  23. package/dist/local/store/expo/adapter.d.ts +5 -1
  24. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  25. package/dist/local/store/expo/adapter.js +9 -4
  26. package/dist/local/store/expo/adapter.js.map +1 -1
  27. package/dist/local/store/mock/adapter.d.ts.map +1 -1
  28. package/dist/local/store/mock/adapter.js +17 -7
  29. package/dist/local/store/mock/adapter.js.map +1 -1
  30. package/dist/types/api.d.ts +11 -7
  31. package/dist/types/api.d.ts.map +1 -1
  32. package/docs/ERROR_HANDLING.md +8 -1
  33. package/docs/api/classes/SignalProtocolClient.md +8 -5
  34. package/docs/api/interfaces/IEcSignedPreKeyStore.md +3 -2
  35. package/docs/api/interfaces/IKyberLastResortPreKeyStore.md +2 -1
  36. package/docs/api/interfaces/ISignalProtocolClient.md +4 -2
  37. package/docs/api/interfaces/ISignalProtocolManager.md +2 -2
  38. package/docs/api/namespaces/keys/README.md +4 -0
  39. package/docs/api/namespaces/keys/functions/canonicalizeDeviceIdentityKey.md +30 -0
  40. package/docs/api/namespaces/keys/functions/compareDeviceIdentityKeys.md +28 -0
  41. package/docs/api/namespaces/keys/functions/isValidDeviceIdentityKey.md +22 -0
  42. package/docs/api/namespaces/keys/variables/UNPINNED_DEVICE_IDENTITY_KEY.md +18 -0
  43. package/package.json +1 -1
@@ -1752,8 +1752,10 @@ Normal sync and linked-device provisioning never call this operation.
1752
1752
 
1753
1753
  Rotate EC signed prekey
1754
1754
 
1755
- Should be called weekly to maintain forward secrecy.
1756
- Generates a new EC signed prekey and uploads it to the relay if configured.
1755
+ Rotates only once the current prekey is older than the configured refresh
1756
+ interval ([KEY\_REFRESH\_INTERVAL\_MS\_DEFAULT](../variables/KEY_REFRESH_INTERVAL_MS_DEFAULT.md), 2 days by default), so
1757
+ it is safe to call more often than that. Generates a new EC signed prekey
1758
+ and uploads it to the relay if configured.
1757
1759
 
1758
1760
  #### Returns
1759
1761
 
@@ -1852,9 +1854,10 @@ handleGroupMembershipChange - Helper method for common membership patterns
1852
1854
 
1853
1855
  Rotate the post-quantum KEM last-resort prekey.
1854
1856
 
1855
- Should be called weekly alongside signed prekey rotation.
1856
- Generates fresh ML-KEM/Kyber-compatible key material and uploads it to the
1857
- relay if configured.
1857
+ Shares the signed prekey's refresh interval
1858
+ ([KEY\_REFRESH\_INTERVAL\_MS\_DEFAULT](../variables/KEY_REFRESH_INTERVAL_MS_DEFAULT.md), 2 days by default) and rotates
1859
+ only once that interval has elapsed. Generates fresh ML-KEM/Kyber-compatible
1860
+ key material and uploads it to the relay if configured.
1858
1861
 
1859
1862
  #### Returns
1860
1863
 
@@ -9,8 +9,9 @@
9
9
  EC Signed PreKey store with an SDK-oriented API.
10
10
 
11
11
  Manages rotating EC signed prekeys for medium-term forward secrecy.
12
- EC signed prekeys should be rotated weekly, but OLD prekeys must be kept
13
- for a grace period (~30 days) to handle in-flight messages.
12
+ EC signed prekeys are rotated on the configured refresh interval (2 days by
13
+ default), but OLD prekeys must be kept for a grace period (~30 days) to
14
+ handle in-flight messages.
14
15
 
15
16
  Per X3DH Spec Section 4.4:
16
17
  "After uploading a new signed prekey, Bob may keep the private key
@@ -9,7 +9,8 @@
9
9
  Kyber Last-Resort PreKey store interface (post-quantum security).
10
10
 
11
11
  Manages the ML-KEM-1024 (Kyber) last-resort prekey for post-quantum forward secrecy.
12
- This is a reusable fallback key (like EC signed prekeys) that should rotate weekly.
12
+ This is a reusable fallback key (like EC signed prekeys) that rotates on the
13
+ configured refresh interval (2 days by default).
13
14
 
14
15
  Naming convention matches EC prekeys:
15
16
  - `IEcOneTimePreKeyStore` → one-time EC prekeys (`ecPreKeys`)
@@ -699,7 +699,8 @@ Explicit compare-and-swap rotation of the account-level relay identity.
699
699
 
700
700
  Rotate EC signed prekey
701
701
 
702
- Should be called weekly to maintain forward secrecy.
702
+ Rotates only once the current prekey is older than the configured refresh
703
+ interval ([KEY\_REFRESH\_INTERVAL\_MS\_DEFAULT](../variables/KEY_REFRESH_INTERVAL_MS_DEFAULT.md), 2 days by default).
703
704
  Returns false if rotation is not needed yet.
704
705
 
705
706
  #### Returns
@@ -736,7 +737,8 @@ New sender key ID and distribution message
736
737
 
737
738
  Rotate Kyber prekey (post-quantum)
738
739
 
739
- Should be called weekly alongside signed prekey rotation.
740
+ Shares the signed prekey's refresh interval
741
+ ([KEY\_REFRESH\_INTERVAL\_MS\_DEFAULT](../variables/KEY_REFRESH_INTERVAL_MS_DEFAULT.md), 2 days by default).
740
742
  Returns false if rotation is not needed yet.
741
743
 
742
744
  #### Returns
@@ -181,7 +181,7 @@ Identity types to generate keys for (defaults to ['aci', 'pni'])
181
181
 
182
182
  > **rotateEcSignedPreKey**(`userId`): `Promise`\<`void`\>
183
183
 
184
- Rotate EC signed prekey (weekly)
184
+ Rotate EC signed prekey (on the configured refresh interval, 2 days by default)
185
185
 
186
186
  #### Parameters
187
187
 
@@ -199,7 +199,7 @@ Rotate EC signed prekey (weekly)
199
199
 
200
200
  > **rotateKyberPreKey**(`userId`): `Promise`\<`void`\>
201
201
 
202
- Rotate Kyber prekey (post-quantum security, weekly)
202
+ Rotate Kyber prekey (post-quantum security, same interval as the signed prekey)
203
203
 
204
204
  #### Parameters
205
205
 
@@ -38,11 +38,14 @@ const signedPreKey = await keys.generateEcSignedPreKey(signingKey);
38
38
  - [PREKEY\_ALGORITHM\_ML\_KEM\_1024](variables/PREKEY_ALGORITHM_ML_KEM_1024.md)
39
39
  - [PREKEY\_ALGORITHM\_X25519](variables/PREKEY_ALGORITHM_X25519.md)
40
40
  - [PREKEY\_SIGNATURE\_V1\_DOMAIN](variables/PREKEY_SIGNATURE_V1_DOMAIN.md)
41
+ - [UNPINNED\_DEVICE\_IDENTITY\_KEY](variables/UNPINNED_DEVICE_IDENTITY_KEY.md)
41
42
 
42
43
  ## Functions
43
44
 
44
45
  - [acceptContactIdentityRotation](functions/acceptContactIdentityRotation.md)
45
46
  - [assertIdentityCommitment](functions/assertIdentityCommitment.md)
47
+ - [canonicalizeDeviceIdentityKey](functions/canonicalizeDeviceIdentityKey.md)
48
+ - [compareDeviceIdentityKeys](functions/compareDeviceIdentityKeys.md)
46
49
  - [compositeIdentitiesEqual](functions/compositeIdentitiesEqual.md)
47
50
  - [createCompositeIdentityV1](functions/createCompositeIdentityV1.md)
48
51
  - [createPreKeySignatureContext](functions/createPreKeySignatureContext.md)
@@ -58,6 +61,7 @@ const signedPreKey = await keys.generateEcSignedPreKey(signingKey);
58
61
  - [generateKemOneTimePreKeys](functions/generateKemOneTimePreKeys.md)
59
62
  - [generateKyberLastResortPreKey](functions/generateKyberLastResortPreKey.md)
60
63
  - [generateRegistrationId](functions/generateRegistrationId.md)
64
+ - [isValidDeviceIdentityKey](functions/isValidDeviceIdentityKey.md)
61
65
  - [signMlKem1024PreKey](functions/signMlKem1024PreKey.md)
62
66
  - [signPreKey](functions/signPreKey.md)
63
67
  - [validateContactIdentityRecord](functions/validateContactIdentityRecord.md)
@@ -0,0 +1,30 @@
1
+ [**@open-e2ee/signal-protocol-sdk**](../../../README.md)
2
+
3
+ ***
4
+
5
+ [@open-e2ee/signal-protocol-sdk](../../../README.md) / [keys](../README.md) / canonicalizeDeviceIdentityKey
6
+
7
+ # Function: canonicalizeDeviceIdentityKey()
8
+
9
+ > **canonicalizeDeviceIdentityKey**(`bytes`, `label`): `Uint8Array`
10
+
11
+ Reduce `DeviceRecord.identityKey` bytes to their canonical form, rejecting
12
+ any other encoding at the storage boundary.
13
+
14
+ Every producer of device identity bytes goes through here so that a single
15
+ encoding reaches storage and comparison. Without it, two producers using two
16
+ encodings of the same key compare unequal and forge an identity-change event.
17
+
18
+ ## Parameters
19
+
20
+ ### bytes
21
+
22
+ `Uint8Array`
23
+
24
+ ### label
25
+
26
+ `string`
27
+
28
+ ## Returns
29
+
30
+ `Uint8Array`
@@ -0,0 +1,28 @@
1
+ [**@open-e2ee/signal-protocol-sdk**](../../../README.md)
2
+
3
+ ***
4
+
5
+ [@open-e2ee/signal-protocol-sdk](../../../README.md) / [keys](../README.md) / compareDeviceIdentityKeys
6
+
7
+ # Function: compareDeviceIdentityKeys()
8
+
9
+ > **compareDeviceIdentityKeys**(`pinned`, `incoming`): `"unpinned"` \| `"same"` \| `"changed"`
10
+
11
+ Compare two `DeviceRecord.identityKey` values.
12
+
13
+ Returns `'unpinned'` when no identity has been observed for the device yet,
14
+ which is first contact (a TOFU pin) and not a change.
15
+
16
+ ## Parameters
17
+
18
+ ### pinned
19
+
20
+ `Uint8Array`
21
+
22
+ ### incoming
23
+
24
+ `Uint8Array`
25
+
26
+ ## Returns
27
+
28
+ `"unpinned"` \| `"same"` \| `"changed"`
@@ -0,0 +1,22 @@
1
+ [**@open-e2ee/signal-protocol-sdk**](../../../README.md)
2
+
3
+ ***
4
+
5
+ [@open-e2ee/signal-protocol-sdk](../../../README.md) / [keys](../README.md) / isValidDeviceIdentityKey
6
+
7
+ # Function: isValidDeviceIdentityKey()
8
+
9
+ > **isValidDeviceIdentityKey**(`bytes`): `boolean`
10
+
11
+ Whether `bytes` is a well-formed `DeviceRecord.identityKey`: either unpinned
12
+ or exactly one canonical composite tuple.
13
+
14
+ ## Parameters
15
+
16
+ ### bytes
17
+
18
+ `Uint8Array`
19
+
20
+ ## Returns
21
+
22
+ `boolean`
@@ -0,0 +1,18 @@
1
+ [**@open-e2ee/signal-protocol-sdk**](../../../README.md)
2
+
3
+ ***
4
+
5
+ [@open-e2ee/signal-protocol-sdk](../../../README.md) / [keys](../README.md) / UNPINNED\_DEVICE\_IDENTITY\_KEY
6
+
7
+ # Variable: UNPINNED\_DEVICE\_IDENTITY\_KEY
8
+
9
+ > `const` **UNPINNED\_DEVICE\_IDENTITY\_KEY**: `Uint8Array`
10
+
11
+ SESAME `DeviceRecord.identityKey` bytes for a device whose composite identity
12
+ has not been observed yet.
13
+
14
+ Zero length is the only representation of "not pinned". It must stay distinct
15
+ from a pinned tuple so that first contact performs a TOFU pin rather than
16
+ reporting an identity change, and it must never be a partial key: pinning
17
+ only the X25519 half would silently accept a peer that kept its DH key and
18
+ swapped its Ed25519 signing key.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.1.0-alpha.1",
3
+ "version": "0.1.0-alpha.3",
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",