@open-e2ee/signal-protocol-sdk 0.1.0-alpha.4 → 0.1.0-alpha.5
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.
- package/CHANGELOG.md +54 -0
- package/README.md +4 -2
- package/dist/blocking/types.d.ts +1 -1
- package/dist/blocking/types.js +1 -1
- package/dist/client/client.d.ts +3 -3
- package/dist/client/client.js +4 -4
- package/dist/client/client.js.map +1 -1
- package/dist/client/compose.d.ts +1 -1
- package/dist/client/compose.d.ts.map +1 -1
- package/dist/client/config.d.ts +2 -2
- package/dist/client/event-hooks.d.ts +1 -1
- package/dist/client/headless.d.ts +2 -2
- package/dist/client/headless.js +2 -2
- package/dist/client/key-rotation-core.d.ts +4 -4
- package/dist/client/key-rotation-core.js +11 -11
- package/dist/client/key-rotation-core.js.map +1 -1
- package/dist/client/media.d.ts +2 -2
- package/dist/client/media.js +5 -5
- package/dist/client/media.js.map +1 -1
- package/dist/client/messages.js +2 -2
- package/dist/client/messages.js.map +1 -1
- package/dist/client/relay-subscription.js +17 -0
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/retry.js +1 -1
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender-ops.js +1 -1
- package/dist/client/sealed-sender-ops.js.map +1 -1
- package/dist/client/sessions.d.ts.map +1 -1
- package/dist/client/sessions.js +3 -0
- package/dist/client/sessions.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts +5 -1
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +19 -14
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/device/provisioning.d.ts +3 -3
- package/dist/device/provisioning.js +2 -2
- package/dist/device/provisioning.js.map +1 -1
- package/dist/hooks/use-connection-presence.d.ts +2 -2
- package/dist/hooks/use-connection-presence.d.ts.map +1 -1
- package/dist/hooks/use-connection-presence.js +1 -1
- package/dist/hooks/use-group-membership.d.ts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/internal/crypto/index.js +1 -1
- package/dist/internal/crypto/index.js.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.d.ts +1 -1
- package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.js +2 -2
- package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
- package/dist/internal/crypto/key-prefix.d.ts +1 -1
- package/dist/internal/crypto/key-prefix.js +1 -1
- package/dist/internal/crypto/pq/kyber.d.ts +1 -1
- package/dist/internal/crypto/pq/kyber.js +1 -1
- package/dist/internal/crypto/symmetric/aes-gcm-siv.d.ts +1 -1
- package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
- package/dist/internal/crypto/utils.d.ts +2 -2
- package/dist/internal/crypto/utils.js +2 -2
- package/dist/internal/encoding/proto/index.js +1 -1
- package/dist/internal/encoding/proto/index.js.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +2 -2
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js +2 -2
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
- package/dist/internal/groups/group-id.d.ts +1 -1
- package/dist/internal/groups/group-id.js +1 -1
- package/dist/internal/groups/group-id.js.map +1 -1
- package/dist/internal/groups-v2/access-control.d.ts +8 -1
- package/dist/internal/groups-v2/access-control.d.ts.map +1 -1
- package/dist/internal/groups-v2/access-control.js +8 -1
- package/dist/internal/groups-v2/access-control.js.map +1 -1
- package/dist/internal/groups-v2/change-actions.d.ts +8 -3
- package/dist/internal/groups-v2/change-actions.d.ts.map +1 -1
- package/dist/internal/groups-v2/change-actions.js +8 -3
- package/dist/internal/groups-v2/change-actions.js.map +1 -1
- package/dist/internal/groups-v2/index.d.ts +7 -2
- package/dist/internal/groups-v2/index.d.ts.map +1 -1
- package/dist/internal/groups-v2/index.js.map +1 -1
- package/dist/internal/groups-v2/manager.d.ts +4 -2
- package/dist/internal/groups-v2/manager.d.ts.map +1 -1
- package/dist/internal/groups-v2/manager.js +5 -3
- package/dist/internal/groups-v2/manager.js.map +1 -1
- package/dist/internal/groups-v2/types.d.ts +10 -3
- package/dist/internal/groups-v2/types.d.ts.map +1 -1
- package/dist/internal/groups-v2/types.js.map +1 -1
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +25 -14
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.d.ts +1 -1
- package/dist/internal/protocol/double-ratchet/chains.js +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.js +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.js +2 -2
- package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +1 -1
- package/dist/internal/protocol/sender-keys/index.d.ts +1 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts +2 -2
- package/dist/internal/protocol/sender-keys/manager.js +3 -3
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/index.d.ts +1 -1
- package/dist/internal/protocol/spqr/index.js +1 -1
- package/dist/internal/protocol/spqr/message.d.ts +1 -1
- package/dist/internal/protocol/spqr/message.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/index.js +2 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/index.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +5 -5
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.d.ts +9 -9
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +9 -9
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.js +1 -1
- package/dist/internal/protocol/username/generate.d.ts +1 -1
- package/dist/internal/protocol/username/generate.js +1 -1
- package/dist/internal/protocol/username/hash.d.ts +1 -1
- package/dist/internal/protocol/username/hash.js +1 -1
- package/dist/internal/protocol/username/link.d.ts +1 -1
- package/dist/internal/protocol/username/link.js +1 -1
- package/dist/internal/protocol/username/proof.d.ts +1 -1
- package/dist/internal/protocol/username/proof.js +1 -1
- package/dist/internal/protocol/x3dh/x3dh.js +3 -3
- package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +2 -2
- package/dist/internal/sesame/device-registry.d.ts +11 -6
- package/dist/internal/sesame/device-registry.d.ts.map +1 -1
- package/dist/internal/sesame/device-registry.js +11 -7
- package/dist/internal/sesame/device-registry.js.map +1 -1
- package/dist/internal/sesame/manager.js +1 -1
- package/dist/internal/sesame/manager.js.map +1 -1
- package/dist/internal/session/keys.d.ts +1 -1
- package/dist/keys/generation.d.ts +1 -1
- package/dist/keys/generation.js +1 -1
- package/dist/keys/types.d.ts +1 -1
- package/dist/keys/types.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.d.ts +3 -3
- package/dist/local/store/expo/adapter.js +2 -2
- package/dist/local/store/expo/db.js +1 -1
- package/dist/local/store/expo/db.js.map +1 -1
- package/dist/local/store/expo/index.d.ts +1 -1
- package/dist/local/store/expo/models/local-identity.d.ts +1 -1
- package/dist/local/store/expo/models/local-identity.js +1 -1
- package/dist/local/store/expo/models/sender-key.d.ts +3 -3
- package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
- package/dist/local/store/expo/models/sender-key.js +3 -3
- package/dist/local/store/expo/models/sender-key.js.map +1 -1
- package/dist/local/store/expo/schema.d.ts +1 -1
- package/dist/local/store/expo/schema.js +1 -1
- package/dist/local/store/expo/secure-store-options.d.ts +1 -1
- package/dist/local/store/mock/adapter.d.ts +6 -0
- package/dist/local/store/mock/adapter.d.ts.map +1 -1
- package/dist/local/store/mock/adapter.js +117 -47
- package/dist/local/store/mock/adapter.js.map +1 -1
- package/dist/local/store/mock/failures.d.ts +34 -0
- package/dist/local/store/mock/failures.d.ts.map +1 -0
- package/dist/local/store/mock/failures.js +75 -0
- package/dist/local/store/mock/failures.js.map +1 -0
- package/dist/local/store/mock/index.d.ts +4 -3
- package/dist/local/store/mock/index.d.ts.map +1 -1
- package/dist/local/store/mock/index.js +3 -2
- package/dist/local/store/mock/index.js.map +1 -1
- package/dist/local/store/node/database-key.js +1 -1
- package/dist/local/store/react-native/adapter.js +2 -2
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/react-native/storage.d.ts +1 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +14 -2
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/vault/index.d.ts +1 -1
- package/dist/logger.d.ts +1 -1
- package/dist/logger.js +1 -1
- package/dist/media/index.d.ts +2 -2
- package/dist/media/index.js +2 -2
- package/dist/profile/cipher.d.ts +1 -1
- package/dist/profile/cipher.js +1 -1
- package/dist/profile/contact-state.d.ts +1 -1
- package/dist/profile/contact-state.js +1 -1
- package/dist/profile/crypto.d.ts +1 -1
- package/dist/profile/crypto.js +1 -1
- package/dist/profile/profile-key.js +1 -1
- package/dist/profile/update-service.d.ts +2 -2
- package/dist/profile/update-service.d.ts.map +1 -1
- package/dist/remote/object-store/convex-r2/server.d.ts +1 -1
- package/dist/remote/relay/convex/index.d.ts +1 -1
- package/dist/remote/relay/convex/index.js +1 -1
- package/dist/remote/relay/convex/relay.d.ts +2 -2
- package/dist/remote/relay/convex/relay.js +2 -2
- package/dist/remote/relay/convex/types.d.ts +7 -7
- package/dist/remote/relay/convex/types.js +1 -1
- package/dist/remote/relay/mock/adapter.d.ts +13 -2
- package/dist/remote/relay/mock/adapter.d.ts.map +1 -1
- package/dist/remote/relay/mock/adapter.js +165 -51
- package/dist/remote/relay/mock/adapter.js.map +1 -1
- package/dist/remote/relay/mock/failures.d.ts +57 -0
- package/dist/remote/relay/mock/failures.d.ts.map +1 -0
- package/dist/remote/relay/mock/failures.js +118 -0
- package/dist/remote/relay/mock/failures.js.map +1 -0
- package/dist/remote/relay/mock/index.d.ts +4 -3
- package/dist/remote/relay/mock/index.d.ts.map +1 -1
- package/dist/remote/relay/mock/index.js +4 -3
- package/dist/remote/relay/mock/index.js.map +1 -1
- package/dist/remote/relay/types.d.ts +1 -1
- package/dist/remote/relay/types.js +1 -1
- package/dist/safety/protobuf.d.ts +1 -1
- package/dist/safety/protobuf.d.ts.map +1 -1
- package/dist/types/api.d.ts +6 -6
- package/dist/types/errors.d.ts +2 -2
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +2 -2
- package/dist/types/errors.js.map +1 -1
- package/dist/types/protocol-config.d.ts +3 -2
- package/dist/types/protocol-config.d.ts.map +1 -1
- package/dist/types/protocol-config.js.map +1 -1
- package/dist/types/protocol-constants.d.ts +1 -1
- package/dist/types/protocol-constants.js +1 -1
- package/dist/utils/binary-transfer.d.ts +1 -1
- package/dist/utils/errors.d.ts +2 -2
- package/dist/utils/errors.js +2 -2
- package/dist/utils/retry.d.ts +2 -1
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +3 -1
- package/dist/utils/retry.js.map +1 -1
- package/dist/zk/groups.d.ts +1 -1
- package/dist/zk/groups.js +1 -1
- package/docs/CLIENT_COMPOSITION.md +5 -3
- package/docs/DEVIATIONS.md +63 -62
- package/docs/GETTING_STARTED.md +10 -6
- package/docs/PACKAGE_SURFACE.md +2 -2
- package/docs/PROTOCOL_POLICY.md +2 -2
- package/docs/RECIPES.md +4 -0
- package/docs/api/classes/SignalProtocolClient.md +4 -4
- package/docs/api/functions/createDefaultSignalLogger.md +2 -2
- package/docs/api/functions/resolveSignalLogger.md +2 -2
- package/docs/api/interfaces/BlockedRecipientEntry.md +1 -1
- package/docs/api/interfaces/ILogger.md +1 -1
- package/docs/api/interfaces/ISignalLocalSecretVault.md +2 -2
- package/docs/api/interfaces/ISignalLocalStore.md +2 -2
- package/docs/api/interfaces/ISignalProtocolClient.md +2 -2
- package/docs/api/interfaces/MLKEMBraidAgentState.md +1 -1
- package/docs/api/interfaces/PreKeyMaintenanceStore.md +2 -1
- package/docs/api/interfaces/SealedSenderConfig.md +2 -2
- package/docs/api/interfaces/SignalProtocolClientCompositionOptions.md +2 -2
- package/docs/api/interfaces/SignalProtocolClientConfig.md +2 -2
- package/docs/api/interfaces/SignalProtocolClientHooks.md +1 -1
- package/docs/api/interfaces/SignalProtocolClientIdentityConfig.md +1 -1
- package/docs/api/interfaces/SignalProtocolClientMediaConfig.md +3 -3
- package/docs/api/interfaces/SignalProtocolConfig.md +1 -1
- package/docs/api/namespaces/encoding/functions/bytesToUrlSafeBase64.md +2 -2
- package/docs/api/namespaces/keys/functions/generateKemOneTimePreKeys.md +1 -1
- package/docs/api/namespaces/media/functions/prepareMediaAttachmentUpload.md +1 -1
- package/docs/api/namespaces/media/functions/resolveMediaAttachment.md +1 -1
- package/docs/api/namespaces/media/variables/downloadMediaAttachment.md +1 -1
- package/docs/api/type-aliases/GroupId.md +1 -1
- package/docs/api/variables/MAX_RECEIVER_CHAINS.md +1 -1
- package/docs/api/variables/ONE_TIME_PREKEY_BATCH_SIZE.md +1 -1
- package/docs/api/variables/defaultSignalLogger.md +2 -2
- package/local/store/mock/README.md +31 -0
- package/package.json +1 -1
- package/remote/relay/mock/README.md +37 -0
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -107,7 +107,9 @@ This is the target DX the package is moving toward. It is shown here so app
|
|
|
107
107
|
developers can understand the intended mental model while the current stable API
|
|
108
108
|
still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
|
|
109
109
|
|
|
110
|
+
<!-- mock-snippet:skip target-message-api-not-yet-shipped -->
|
|
110
111
|
```ts
|
|
112
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
111
113
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
112
114
|
import { createInMemoryDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/memory";
|
|
113
115
|
import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
|
|
@@ -180,8 +182,8 @@ const signal = await createSignalProtocolClient({
|
|
|
180
182
|
```
|
|
181
183
|
|
|
182
184
|
Attachments use the same message API. On Expo, pass the picker URI; the Signal
|
|
183
|
-
client copies or persists the bytes through `deviceStorage.files`
|
|
184
|
-
so retry can continue after restart:
|
|
185
|
+
Protocol client copies or persists the bytes through `deviceStorage.files`
|
|
186
|
+
before upload so retry can continue after restart:
|
|
185
187
|
|
|
186
188
|
```ts
|
|
187
189
|
await signal.messages.send({
|
|
@@ -226,7 +228,9 @@ Use mock adapters for local examples and development:
|
|
|
226
228
|
the demo sends while Bob is offline, inspects the relay-visible ciphertext, and
|
|
227
229
|
then starts Bob's subscription to show the decrypted plaintext entering the app.
|
|
228
230
|
|
|
231
|
+
<!-- mock-snippet:run getting-started-stable-local-clients -->
|
|
229
232
|
```ts
|
|
233
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
230
234
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
231
235
|
import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
|
|
232
236
|
import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
|
|
@@ -522,8 +526,8 @@ partial-byte store. Native background download code should implement the same
|
|
|
522
526
|
`MediaAttachmentTransfer` interface.
|
|
523
527
|
|
|
524
528
|
For background-safe uploads, use the durable client operation. The current API
|
|
525
|
-
persists bounded recovery metadata through the existing Signal storage
|
|
526
|
-
the target message-first API moves that responsibility behind
|
|
529
|
+
persists bounded recovery metadata through the existing Signal Protocol storage
|
|
530
|
+
adapter; the target message-first API moves that responsibility behind
|
|
527
531
|
`deviceStorage.messages`. The operation tries the upload when it is due and
|
|
528
532
|
returns either a completed pointer or a pending job id for later recovery:
|
|
529
533
|
|
|
@@ -560,8 +564,8 @@ await signal.media.processPending({
|
|
|
560
564
|
```
|
|
561
565
|
|
|
562
566
|
On receive, ask the media planner what work this device should do. Your app
|
|
563
|
-
supplies the IDs it has already processed or cached; the Signal package
|
|
564
|
-
the safe next step without taking ownership of your app database:
|
|
567
|
+
supplies the IDs it has already processed or cached; the Signal Protocol package
|
|
568
|
+
returns the safe next step without taking ownership of your app database:
|
|
565
569
|
|
|
566
570
|
```ts
|
|
567
571
|
const mediaWork = media.planMediaAttachmentProcessing({
|
package/docs/PACKAGE_SURFACE.md
CHANGED
|
@@ -183,8 +183,8 @@ Both concrete adapters keep provider credentials in the application backend.
|
|
|
183
183
|
Remote object storage is a normal first-class integration point for encrypted
|
|
184
184
|
attachments and files, not a niche or internal-only adapter. Use
|
|
185
185
|
`attachment.transfer` when your app has a foreground, background, resumable, or
|
|
186
|
-
platform-native byte transfer implementation. The Signal package still
|
|
187
|
-
encryption, digest verification, retry decisions, and pointer metadata.
|
|
186
|
+
platform-native byte transfer implementation. The Signal Protocol package still
|
|
187
|
+
owns encryption, digest verification, retry decisions, and pointer metadata.
|
|
188
188
|
|
|
189
189
|
Object stores can return signed upload headers, and stores that return
|
|
190
190
|
`protocol: 'tus'` automatically use the built-in resumable TUS transfer helper.
|
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -72,8 +72,8 @@ await createSignalProtocolClient({
|
|
|
72
72
|
`braid: 'required'` uses the specification-defined ML-KEM Braid SPQR profile
|
|
73
73
|
and is the default. HEK is `SHA3-256(ek_seed || ek_vector)`; that operand order
|
|
74
74
|
is part of the public compatibility boundary. It follows the ML-KEM Braid
|
|
75
|
-
specification text and is the reverse of
|
|
76
|
-
braid sessions do not interoperate with
|
|
75
|
+
specification text and is the reverse of `libsignal`'s implementation, which means
|
|
76
|
+
braid sessions do not interoperate with `libsignal`'s and the KEM in this mode is not
|
|
77
77
|
stock FIPS 203 — see [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
|
|
78
78
|
|
|
79
79
|
```ts
|
package/docs/RECIPES.md
CHANGED
|
@@ -13,7 +13,9 @@ uses public exports only.
|
|
|
13
13
|
This local demo sends while Bob is offline so you can see the relay's encrypted
|
|
14
14
|
envelope and Bob's decrypted plaintext in the same workflow.
|
|
15
15
|
|
|
16
|
+
<!-- mock-snippet:run recipes-two-local-clients -->
|
|
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 { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
|
|
19
21
|
import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
|
|
@@ -133,7 +135,9 @@ before creating the client.
|
|
|
133
135
|
|
|
134
136
|
## Local development
|
|
135
137
|
|
|
138
|
+
<!-- mock-snippet:run recipes-local-development -->
|
|
136
139
|
```ts
|
|
140
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
137
141
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
138
142
|
import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
|
|
139
143
|
import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
|
|
@@ -43,7 +43,7 @@ Device ID for this client instance (1 = primary, 2-5 = linked)
|
|
|
43
43
|
|
|
44
44
|
Resolved logger for this client instance.
|
|
45
45
|
|
|
46
|
-
This is the client-scoped logger used throughout the Signal runtime.
|
|
46
|
+
This is the client-scoped logger used throughout the Signal Protocol runtime.
|
|
47
47
|
|
|
48
48
|
#### Implementation of
|
|
49
49
|
|
|
@@ -55,7 +55,7 @@ This is the client-scoped logger used throughout the Signal runtime.
|
|
|
55
55
|
|
|
56
56
|
> `readonly` **media**: [`SignalProtocolClientMedia`](../interfaces/SignalProtocolClientMedia.md)
|
|
57
57
|
|
|
58
|
-
Durable media job facade backed by the configured Signal local store.
|
|
58
|
+
Durable media job facade backed by the configured Signal Protocol local store.
|
|
59
59
|
|
|
60
60
|
Use this for background-safe attachment uploads, downloads, and cleanup
|
|
61
61
|
when the app provides media lifecycle callbacks in `config.media`.
|
|
@@ -1785,7 +1785,7 @@ Per Signal Protocol specification, rotate sender keys on **membership changes**:
|
|
|
1785
1785
|
| Member ADDED | Distribute current key to new member (no rotation needed) |
|
|
1786
1786
|
| Group metadata changed | Rotate recommended |
|
|
1787
1787
|
|
|
1788
|
-
**Important**: Signal does NOT use periodic or message-count-based rotation.
|
|
1788
|
+
**Important**: The Signal Protocol does NOT use periodic or message-count-based rotation.
|
|
1789
1789
|
Only rotate when membership changes to maintain forward secrecy.
|
|
1790
1790
|
|
|
1791
1791
|
## Why Rotate on Member Removal?
|
|
@@ -1919,7 +1919,7 @@ All inputs are normalized to Uint8Array before reaching the cipher layer.
|
|
|
1919
1919
|
|
|
1920
1920
|
`string`
|
|
1921
1921
|
|
|
1922
|
-
User ID or group ID (groups use Signal V2 prefix)
|
|
1922
|
+
User ID or group ID (groups use the Signal Protocol V2 prefix)
|
|
1923
1923
|
|
|
1924
1924
|
##### content
|
|
1925
1925
|
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
|
|
11
11
|
Logging utilities for app composition
|
|
12
12
|
|
|
13
|
-
Pass a logger into `createSignalProtocolClient()` to route Signal logs
|
|
14
|
-
app logger or custom diagnostics pipeline.
|
|
13
|
+
Pass a logger into `createSignalProtocolClient()` to route Signal Protocol logs
|
|
14
|
+
through your app logger or custom diagnostics pipeline.
|
|
15
15
|
|
|
16
16
|
## Returns
|
|
17
17
|
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
|
|
11
11
|
Logging utilities for app composition
|
|
12
12
|
|
|
13
|
-
Pass a logger into `createSignalProtocolClient()` to route Signal logs
|
|
14
|
-
app logger or custom diagnostics pipeline.
|
|
13
|
+
Pass a logger into `createSignalProtocolClient()` to route Signal Protocol logs
|
|
14
|
+
through your app logger or custom diagnostics pipeline.
|
|
15
15
|
|
|
16
16
|
## Parameters
|
|
17
17
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
# Interface: BlockedRecipientEntry
|
|
8
8
|
|
|
9
|
-
Signal blocking contracts.
|
|
9
|
+
Signal Protocol blocking contracts.
|
|
10
10
|
|
|
11
11
|
Blocking is account/contact state, not message content. The core package owns
|
|
12
12
|
the local blocking workflow and lets each app choose whether blocked state is
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
# Interface: ILogger
|
|
8
8
|
|
|
9
|
-
Signal package logging primitives.
|
|
9
|
+
Signal Protocol package logging primitives.
|
|
10
10
|
|
|
11
11
|
The package resolves a logger once at composition time and passes it through
|
|
12
12
|
explicit dependencies. This keeps logging package-local without relying on
|
|
@@ -6,11 +6,11 @@
|
|
|
6
6
|
|
|
7
7
|
# Interface: ISignalLocalSecretVault
|
|
8
8
|
|
|
9
|
-
Small local secret vault used to bootstrap a local Signal store.
|
|
9
|
+
Small local secret vault used to bootstrap a local Signal Protocol store.
|
|
10
10
|
|
|
11
11
|
This interface is intentionally narrow: it exists for secrets that must
|
|
12
12
|
remain outside the main local store, such as a database encryption key.
|
|
13
|
-
It is not a second general-purpose Signal data store.
|
|
13
|
+
It is not a second general-purpose Signal Protocol data store.
|
|
14
14
|
|
|
15
15
|
## Methods
|
|
16
16
|
|
|
@@ -6,9 +6,9 @@
|
|
|
6
6
|
|
|
7
7
|
# Interface: ISignalLocalStore
|
|
8
8
|
|
|
9
|
-
Signal local store interface.
|
|
9
|
+
Signal Protocol local store interface.
|
|
10
10
|
|
|
11
|
-
Canonical device/browser-local persistence for Signal
|
|
11
|
+
Canonical device/browser-local persistence for Signal Protocol state:
|
|
12
12
|
- identity keys and registrations
|
|
13
13
|
- sessions and sender keys
|
|
14
14
|
- SESAME multi-device state
|
|
@@ -36,7 +36,7 @@ Device ID for this client instance (1 = primary, 2-5 = linked)
|
|
|
36
36
|
|
|
37
37
|
Resolved logger for this client instance.
|
|
38
38
|
|
|
39
|
-
This is the client-scoped logger used throughout the Signal runtime.
|
|
39
|
+
This is the client-scoped logger used throughout the Signal Protocol runtime.
|
|
40
40
|
|
|
41
41
|
***
|
|
42
42
|
|
|
@@ -778,7 +778,7 @@ Send content to a recipient
|
|
|
778
778
|
|
|
779
779
|
This is the primary API for sending encrypted content.
|
|
780
780
|
Automatically handles:
|
|
781
|
-
- Group vs user detection (Signal V2 prefix)
|
|
781
|
+
- Group vs user detection (Signal Protocol V2 prefix)
|
|
782
782
|
- Content type routing (DataMessageInput, string, Uint8Array)
|
|
783
783
|
- Multi-device fan-out
|
|
784
784
|
- Sender key distribution for groups
|
|
@@ -52,7 +52,7 @@ Decoded CT1 stored for combined MAC verification with CT2
|
|
|
52
52
|
|
|
53
53
|
> `optional` **ct1\_for\_mac?**: `Uint8Array`\<`ArrayBufferLike`\>
|
|
54
54
|
|
|
55
|
-
CT1 copy stored for combined MAC computation with CT2 (
|
|
55
|
+
CT1 copy stored for combined MAC computation with CT2 (libsignal authenticates ct1||ct2)
|
|
56
56
|
|
|
57
57
|
***
|
|
58
58
|
|
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
App-provided persistence helpers for prekey replacement bookkeeping.
|
|
10
10
|
|
|
11
|
-
Signal owns rotation semantics; concrete storage adapters
|
|
11
|
+
The Signal Protocol client owns rotation semantics; concrete storage adapters
|
|
12
|
+
own persistence.
|
|
12
13
|
|
|
13
14
|
## Methods
|
|
14
15
|
|
|
@@ -52,8 +52,8 @@ Base64-encoded serialized SenderCertificate
|
|
|
52
52
|
|
|
53
53
|
Optional host-provided contact profile state store.
|
|
54
54
|
|
|
55
|
-
When present, Signal can use per-contact profile keys
|
|
56
|
-
unidentified-access mode for direct-message sealed sender sends
|
|
55
|
+
When present, the Signal Protocol client can use per-contact profile keys
|
|
56
|
+
and unidentified-access mode for direct-message sealed sender sends
|
|
57
57
|
without importing the host app's persistence layer.
|
|
58
58
|
|
|
59
59
|
***
|
|
@@ -389,8 +389,8 @@ https://signal.org/docs/specifications/pqxdh/#publishing-keys
|
|
|
389
389
|
|
|
390
390
|
App-owned media lifecycle callbacks for the SignalProtocolClient media queue.
|
|
391
391
|
|
|
392
|
-
The queue itself is persisted through the existing Signal local
|
|
393
|
-
adapter. These callbacks keep local bytes, plaintext caches, and product
|
|
392
|
+
The queue itself is persisted through the existing Signal Protocol local
|
|
393
|
+
storage adapter. These callbacks keep local bytes, plaintext caches, and product
|
|
394
394
|
state in the app layer where they can share file permissions, UI state, and
|
|
395
395
|
app database ownership.
|
|
396
396
|
|
|
@@ -407,8 +407,8 @@ https://signal.org/docs/specifications/pqxdh/#publishing-keys
|
|
|
407
407
|
|
|
408
408
|
App-owned media lifecycle callbacks for the SignalProtocolClient media queue.
|
|
409
409
|
|
|
410
|
-
The queue itself is persisted through the existing Signal local
|
|
411
|
-
adapter. These callbacks keep local bytes, plaintext caches, and product
|
|
410
|
+
The queue itself is persisted through the existing Signal Protocol local
|
|
411
|
+
storage adapter. These callbacks keep local bytes, plaintext caches, and product
|
|
412
412
|
state in the app layer where they can share file permissions, UI state, and
|
|
413
413
|
app database ownership.
|
|
414
414
|
|
|
@@ -46,8 +46,8 @@ Delete app-owned local cache state for a cleanup job.
|
|
|
46
46
|
|
|
47
47
|
Load app-owned local bytes for a queued upload.
|
|
48
48
|
|
|
49
|
-
The Signal package owns encryption and upload execution. The app owns
|
|
50
|
-
files, cache paths, and file permissions, so bytes enter the queue through
|
|
49
|
+
The Signal Protocol package owns encryption and upload execution. The app owns
|
|
50
|
+
draft files, cache paths, and file permissions, so bytes enter the queue through
|
|
51
51
|
this callback instead of hidden package storage.
|
|
52
52
|
|
|
53
53
|
#### Parameters
|
|
@@ -80,7 +80,7 @@ Maximum attempts before a failing job is removed.
|
|
|
80
80
|
|
|
81
81
|
> `optional` **maxJobs?**: `number`
|
|
82
82
|
|
|
83
|
-
Bound the queue kept in the Signal local store metadata.
|
|
83
|
+
Bound the queue kept in the Signal Protocol local store metadata.
|
|
84
84
|
|
|
85
85
|
#### Default
|
|
86
86
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
# Interface: SignalProtocolConfig
|
|
8
8
|
|
|
9
|
-
Public Signal
|
|
9
|
+
Public Signal Protocol configuration.
|
|
10
10
|
|
|
11
11
|
This keeps application code in product/security terms. Internal protocol
|
|
12
12
|
strategy details such as X3DH fallback remain below the SignalProtocolClient seam.
|
|
@@ -15,8 +15,8 @@ URL-safe Base64 uses:
|
|
|
15
15
|
- `_` instead of `/`
|
|
16
16
|
- No padding (`=`)
|
|
17
17
|
|
|
18
|
-
Used for R2 storage keys (attachments, profiles)
|
|
19
|
-
|
|
18
|
+
Used for R2 storage keys (attachments, profiles), which must survive being
|
|
19
|
+
placed in a URL path without escaping.
|
|
20
20
|
|
|
21
21
|
## Parameters
|
|
22
22
|
|
|
@@ -16,7 +16,7 @@ Each key can only be used once for per-session post-quantum forward secrecy.
|
|
|
16
16
|
Per PQXDH spec Section 3.2, these are signed one-time pqkem prekeys
|
|
17
17
|
that the server prefers over the last-resort KEM prekey.
|
|
18
18
|
|
|
19
|
-
Uses the same batch size as EC one-time prekeys (
|
|
19
|
+
Uses the same batch size as EC one-time prekeys (libsignal uses 100 for both).
|
|
20
20
|
|
|
21
21
|
## Parameters
|
|
22
22
|
|
|
@@ -13,7 +13,7 @@ Encrypt and upload media bytes, returning a SDK attachment pointer.
|
|
|
13
13
|
The encrypted object digest and object ID are computed once. Upload
|
|
14
14
|
retries request fresh presigned URLs for that same key, which handles expired
|
|
15
15
|
upload URLs without changing the pointer metadata that will be encrypted into
|
|
16
|
-
the Signal message.
|
|
16
|
+
the Signal Protocol message.
|
|
17
17
|
|
|
18
18
|
## Parameters
|
|
19
19
|
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
> **resolveMediaAttachment**(`attachment`, `options`): `Promise`\<[`ResolvedMediaAttachment`](../interfaces/ResolvedMediaAttachment.md)\>
|
|
10
10
|
|
|
11
|
-
Download, verify, and decrypt a Signal media attachment pointer.
|
|
11
|
+
Download, verify, and decrypt a Signal Protocol media attachment pointer.
|
|
12
12
|
|
|
13
13
|
This is the safe receive-side counterpart to attachment upload. It validates
|
|
14
14
|
pointer metadata, downloads opaque ciphertext from the object store, verifies
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
> `const` **downloadMediaAttachment**: (`attachment`, `options`) => `Promise`\<[`ResolvedMediaAttachment`](../interfaces/ResolvedMediaAttachment.md)\> = `resolveMediaAttachment`
|
|
10
10
|
|
|
11
|
-
Download, verify, and decrypt a Signal media attachment pointer.
|
|
11
|
+
Download, verify, and decrypt a Signal Protocol media attachment pointer.
|
|
12
12
|
|
|
13
13
|
This is the safe receive-side counterpart to attachment upload. It validates
|
|
14
14
|
pointer metadata, downloads opaque ciphertext from the object store, verifies
|
|
@@ -10,5 +10,5 @@
|
|
|
10
10
|
|
|
11
11
|
Maximum number of receiver chains to store.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
libsignal maintains up to 5 receiver chains for handling out-of-order
|
|
14
14
|
DH ratchets. When a 6th chain would be added, the oldest is evicted.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
Batch size for one-time prekeys (both EC and KEM)
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
libsignal uses 100 for both EC and KEM one-time prekeys to maintain
|
|
14
14
|
protocol symmetry. This balances key availability with storage/upload costs.
|
|
15
15
|
|
|
16
16
|
Per PQXDH specification, KEM one-time prekeys follow the same
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
|
|
11
11
|
Logging utilities for app composition
|
|
12
12
|
|
|
13
|
-
Pass a logger into `createSignalProtocolClient()` to route Signal logs
|
|
14
|
-
app logger or custom diagnostics pipeline.
|
|
13
|
+
Pass a logger into `createSignalProtocolClient()` to route Signal Protocol logs
|
|
14
|
+
through your app logger or custom diagnostics pipeline.
|
|
15
15
|
|
|
16
16
|
## Example
|
|
17
17
|
|
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
`MockSignalStore` implements `ISignalLocalStore` in memory for examples, local
|
|
4
4
|
development, and deterministic application prototypes.
|
|
5
5
|
|
|
6
|
+
Real protocol and cryptography; simulated in-memory infrastructure.
|
|
7
|
+
|
|
6
8
|
## Why it exists
|
|
7
9
|
|
|
8
10
|
It lets developers exercise client composition without choosing a durable
|
|
@@ -12,6 +14,7 @@ security or persistence boundary.
|
|
|
12
14
|
## Usage
|
|
13
15
|
|
|
14
16
|
```ts
|
|
17
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
15
18
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
16
19
|
import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
|
|
17
20
|
|
|
@@ -24,4 +27,32 @@ const client = await createSignalProtocolClient({
|
|
|
24
27
|
All keys, sessions, and trust decisions disappear when the process or adapter
|
|
25
28
|
is discarded. Never use this adapter for production accounts.
|
|
26
29
|
|
|
30
|
+
## Deterministic storage failures
|
|
31
|
+
|
|
32
|
+
Failure mode is opt-in. A seed and cadence replay the same failing writes, or
|
|
33
|
+
you can target the next named store operation:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
37
|
+
import {
|
|
38
|
+
mockStore,
|
|
39
|
+
MockStorageWriteError,
|
|
40
|
+
} from "@open-e2ee/signal-protocol-sdk/local/store/mock";
|
|
41
|
+
|
|
42
|
+
const storage = mockStore({ failures: { seed: 7 } });
|
|
43
|
+
storage.failures.failNextWrite("setMetadata");
|
|
44
|
+
|
|
45
|
+
try {
|
|
46
|
+
await storage.setMetadata("draft", "encrypted-pointer");
|
|
47
|
+
} catch (error) {
|
|
48
|
+
if (error instanceof MockStorageWriteError) {
|
|
49
|
+
// The explicitly injected failure is consumed, so this retry succeeds.
|
|
50
|
+
await storage.setMetadata("draft", "encrypted-pointer");
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Use `writeFailureEvery` for a repeatable cadence. Failure selection uses the
|
|
56
|
+
configured seed and operation count, never `Math.random()` or wall-clock time.
|
|
57
|
+
|
|
27
58
|
See the parent [storage guide](../README.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.
|
|
3
|
+
"version": "0.1.0-alpha.5",
|
|
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",
|
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
`MockSignalRelayServer` implements `ISignalRelayServer` in memory for examples
|
|
4
4
|
and local application development.
|
|
5
5
|
|
|
6
|
+
Real protocol and cryptography; simulated in-memory infrastructure.
|
|
7
|
+
|
|
6
8
|
## Why it exists
|
|
7
9
|
|
|
8
10
|
It provides device registration, public-prekey exchange, and encrypted-envelope
|
|
@@ -12,6 +14,7 @@ authorization or durability boundary.
|
|
|
12
14
|
## Usage
|
|
13
15
|
|
|
14
16
|
```ts
|
|
17
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
15
18
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
16
19
|
import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
|
|
17
20
|
import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
|
|
@@ -29,4 +32,38 @@ All registered devices, public keys, mailboxes, and provisioning state disappear
|
|
|
29
32
|
with the adapter. It performs no real account authentication, rate limiting,
|
|
30
33
|
abuse prevention, or durable delivery and must not be used in production.
|
|
31
34
|
|
|
35
|
+
## Deterministic failure and recovery exercises
|
|
36
|
+
|
|
37
|
+
Failure mode is opt-in and seeded. The default `mockRelay()` remains the
|
|
38
|
+
deterministic happy path:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
42
|
+
import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
|
|
43
|
+
|
|
44
|
+
const relay = mockRelay({
|
|
45
|
+
failures: {
|
|
46
|
+
seed: 7,
|
|
47
|
+
latencyMs: 20,
|
|
48
|
+
duplicateDeliveryEvery: 3,
|
|
49
|
+
reorderDeliveryPairs: true,
|
|
50
|
+
rejectAuthorization: true,
|
|
51
|
+
exhaustOneTimePreKeys: true,
|
|
52
|
+
},
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
relay.failures.disconnect("bob", 1);
|
|
56
|
+
// Sends remain in Bob's encrypted mailbox.
|
|
57
|
+
relay.failures.reconnect("bob", 1);
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`flushReordered()` releases an unmatched final envelope. `configure()` changes
|
|
61
|
+
a scenario without rebuilding clients. Authorization rejection raises
|
|
62
|
+
`SealedSenderAuthError`, allowing the client's documented identified-delivery
|
|
63
|
+
fallback. One-time-prekey exhaustion withholds both EC and KEM one-time keys but
|
|
64
|
+
keeps the KEM last-resort key, so strict-PQ examples exercise the intended
|
|
65
|
+
post-quantum recovery path rather than a silent classical downgrade. Failure
|
|
66
|
+
selection uses the configured seed and delivery count, never `Math.random()` or
|
|
67
|
+
wall-clock time.
|
|
68
|
+
|
|
32
69
|
See the parent [relay guide](../README.md).
|