@open-e2ee/signal-protocol-sdk 13.4.0 → 13.5.1
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 +423 -0
- package/README.md +4 -8
- package/SECURITY.md +2 -2
- package/TROUBLESHOOTING.md +55 -27
- package/dist/client/binary-send.d.ts +28 -0
- package/dist/client/binary-send.d.ts.map +1 -0
- package/dist/client/binary-send.js +26 -0
- package/dist/client/binary-send.js.map +1 -0
- package/dist/client/client.d.ts +46 -6
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +181 -66
- package/dist/client/client.js.map +1 -1
- package/dist/client/content-adapter.d.ts +18 -0
- package/dist/client/content-adapter.d.ts.map +1 -1
- package/dist/client/content-adapter.js.map +1 -1
- package/dist/client/device-set-reconciliation.d.ts +23 -8
- package/dist/client/device-set-reconciliation.d.ts.map +1 -1
- package/dist/client/device-set-reconciliation.js +25 -11
- package/dist/client/device-set-reconciliation.js.map +1 -1
- package/dist/client/event-hooks.d.ts +88 -8
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +1 -0
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-outbox.d.ts +45 -10
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +246 -154
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/group-receive-authorization.d.ts +10 -1
- package/dist/client/group-receive-authorization.d.ts.map +1 -1
- package/dist/client/group-receive-authorization.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts +18 -1
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +84 -12
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-connection.js +1 -1
- package/dist/client/hosted-connection.js.map +1 -1
- package/dist/client/hosted-group-authority.d.ts +6 -2
- package/dist/client/hosted-group-authority.d.ts.map +1 -1
- package/dist/client/hosted-group-authority.js +11 -7
- package/dist/client/hosted-group-authority.js.map +1 -1
- package/dist/client/hosted-groups.d.ts +5 -1
- package/dist/client/hosted-groups.d.ts.map +1 -1
- package/dist/client/hosted-groups.js +8 -4
- package/dist/client/hosted-groups.js.map +1 -1
- package/dist/client/hosted-http-error.d.ts +5 -1
- package/dist/client/hosted-http-error.d.ts.map +1 -1
- package/dist/client/hosted-http-error.js +5 -1
- package/dist/client/hosted-http-error.js.map +1 -1
- package/dist/client/hosted-mailbox-subscription.d.ts +2 -0
- package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
- package/dist/client/hosted-mailbox-subscription.js +5 -5
- package/dist/client/hosted-mailbox-subscription.js.map +1 -1
- package/dist/client/hosted-transport.d.ts +11 -1
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +75 -30
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +1 -1
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/receive-queue.d.ts +5 -2
- package/dist/client/receive-queue.d.ts.map +1 -1
- package/dist/client/receive-queue.js +55 -18
- package/dist/client/receive-queue.js.map +1 -1
- package/dist/client/relay-acceptance.d.ts +49 -6
- package/dist/client/relay-acceptance.d.ts.map +1 -1
- package/dist/client/relay-acceptance.js +49 -3
- package/dist/client/relay-acceptance.js.map +1 -1
- package/dist/client/relay-protocol.d.ts +37 -7
- package/dist/client/relay-protocol.d.ts.map +1 -1
- package/dist/client/relay-protocol.js +53 -10
- package/dist/client/relay-protocol.js.map +1 -1
- package/dist/client/retry-family.d.ts +3 -3
- package/dist/client/retry-family.js +1 -1
- package/dist/client/retry-family.js.map +1 -1
- package/dist/client/retry-request-envelope.d.ts +18 -8
- package/dist/client/retry-request-envelope.d.ts.map +1 -1
- package/dist/client/retry-request-envelope.js +57 -29
- package/dist/client/retry-request-envelope.js.map +1 -1
- package/dist/client/retry-request-lifecycle.d.ts +24 -11
- package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
- package/dist/client/retry-request-lifecycle.js +46 -20
- package/dist/client/retry-request-lifecycle.js.map +1 -1
- package/dist/client/retry-terminal-recovery.d.ts +11 -8
- package/dist/client/retry-terminal-recovery.d.ts.map +1 -1
- package/dist/client/retry-terminal-recovery.js +18 -12
- package/dist/client/retry-terminal-recovery.js.map +1 -1
- package/dist/client/retry.d.ts +8 -7
- package/dist/client/retry.d.ts.map +1 -1
- package/dist/client/retry.js +30 -22
- package/dist/client/retry.js.map +1 -1
- package/dist/client/send-deadline.d.ts +308 -0
- package/dist/client/send-deadline.d.ts.map +1 -0
- package/dist/client/send-deadline.js +914 -0
- package/dist/client/send-deadline.js.map +1 -0
- package/dist/client/send-intent-driver.d.ts +116 -0
- package/dist/client/send-intent-driver.d.ts.map +1 -0
- package/dist/client/send-intent-driver.js +373 -0
- package/dist/client/send-intent-driver.js.map +1 -0
- package/dist/client/signal-service-cipher.d.ts +257 -27
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +1274 -283
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts +48 -5
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/local/store/conformance/cases/metadata.d.ts +3 -2
- package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -1
- package/dist/local/store/conformance/cases/metadata.js +153 -2
- package/dist/local/store/conformance/cases/metadata.js.map +1 -1
- package/dist/local/store/key-value/adapter.d.ts +2 -1
- package/dist/local/store/key-value/adapter.d.ts.map +1 -1
- package/dist/local/store/key-value/adapter.js +9 -0
- package/dist/local/store/key-value/adapter.js.map +1 -1
- package/dist/local/store/memory/adapter.d.ts +2 -1
- package/dist/local/store/memory/adapter.d.ts.map +1 -1
- package/dist/local/store/memory/adapter.js +4 -0
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/metadata-keys.d.ts +13 -0
- package/dist/local/store/metadata-keys.d.ts.map +1 -0
- package/dist/local/store/metadata-keys.js +20 -0
- package/dist/local/store/metadata-keys.js.map +1 -0
- package/dist/local/store/receive-work.d.ts.map +1 -1
- package/dist/local/store/receive-work.js +12 -1
- package/dist/local/store/receive-work.js.map +1 -1
- package/dist/local/store/reliability.d.ts +482 -33
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +690 -48
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.d.ts +2 -1
- package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.js +3 -0
- package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.d.ts +9 -0
- package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.js +12 -0
- package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts +2 -1
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +3 -0
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/local/store/web/adapter.d.ts +8 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +18 -0
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/remote/relay/request-admission.d.ts +49 -0
- package/dist/remote/relay/request-admission.d.ts.map +1 -0
- package/dist/remote/relay/request-admission.js +74 -0
- package/dist/remote/relay/request-admission.js.map +1 -0
- package/dist/types/api.d.ts +77 -0
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +144 -1
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +146 -1
- package/dist/types/errors.js.map +1 -1
- package/docs/ASSURANCE.md +31 -15
- package/docs/DEVIATIONS.md +34 -4
- package/docs/ERROR_HANDLING.md +134 -7
- package/docs/GETTING_STARTED.md +30 -23
- package/docs/PROTOCOL_POLICY.md +31 -20
- package/groups/README.md +1 -1
- package/hooks/README.md +6 -3
- package/local/store/react-native/README.md +9 -10
- package/local/store/web/README.md +1 -1
- package/package.json +1 -1
- package/safety/README.md +48 -11
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,428 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 13.5.1
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- Correct code examples and local links in ten SDK 13.5 guides.
|
|
8
|
+
|
|
9
|
+
## 13.5.0
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- `SendAcceptanceUnknownError`, code `SEND_ACCEPTANCE_UNKNOWN`, from
|
|
14
|
+
`@open-e2ee/signal-protocol-sdk/types`. A direct or group send throws it
|
|
15
|
+
when its posting deadline ends and the Relay acceptance of a device is not
|
|
16
|
+
known. The message might have arrived. It gives `deadlineAt`,
|
|
17
|
+
`acceptedDevices`, `unknownDevices` and `refusedDevices`, and its
|
|
18
|
+
`retryable` is false.
|
|
19
|
+
- `SendNeverAcceptedByRelayError`, code `SEND_NEVER_ACCEPTED`, from the same
|
|
20
|
+
subpath. A direct or group send throws it when the deadline ends and the
|
|
21
|
+
Relay accepted no request for an open device. The call and each replay throw
|
|
22
|
+
it only when the call raised no refusal (a thrown refusal or a refusal in the
|
|
23
|
+
receipt of a shared body) and no refused device has a stored refusal code.
|
|
24
|
+
- `deadlineAt`, `relayRetryable`, `acceptedDevices` and `refusedDevices` on
|
|
25
|
+
send errors.
|
|
26
|
+
- With a store that lists its metadata keys, the SDK now replays each open
|
|
27
|
+
send at start and when the Relay connection returns. It ends each send at
|
|
28
|
+
its posting deadline, or at the next start or connect after it. It posts
|
|
29
|
+
nothing for a send past its deadline.
|
|
30
|
+
- `onSendOutcome` on the client hooks, with `SendOutcomeEvent`. The SDK calls
|
|
31
|
+
it once for each end of a send, from its own replay or from your call. It
|
|
32
|
+
reports `content-required` when the plaintext of an open send is gone. An
|
|
33
|
+
internal send of the SDK, such as a sender key distribution, never reaches
|
|
34
|
+
it. The SDK keeps no content of a sender key distribution, so it does not
|
|
35
|
+
replay one. It ends an open distribution at its deadline, and a retry
|
|
36
|
+
request of the receiver recovers a lost distribution. One exception: an
|
|
37
|
+
open sender key distribution that an earlier SDK version stored carries no
|
|
38
|
+
marker, so the hook gets `content-required` for it once for each client
|
|
39
|
+
run before its deadline, and its end once at its deadline. Ignore an ID
|
|
40
|
+
that your application never sent.
|
|
41
|
+
- The optional method `listMetadataKeys` on `SignalProtocolLocalStore`, with
|
|
42
|
+
`MetadataKeyQuery`. Every built-in store implements it.
|
|
43
|
+
- `resendMessage(clientMessageId)` on the client. After a send ends with
|
|
44
|
+
`SendAcceptanceUnknownError` or `SendNeverAcceptedByRelayError`, it posts
|
|
45
|
+
the message again to each recipient device that the Relay did not accept.
|
|
46
|
+
The resend is a new operation with a fresh operation time and the message
|
|
47
|
+
ID `<clientMessageId>:manual:N`. Its content keeps the original timestamp.
|
|
48
|
+
A resend of a group send posts the content of its send log entry, so each
|
|
49
|
+
copy carries the group context of the original send, not the current one.
|
|
50
|
+
It has its own posting deadline 24 hours after the call, and the SDK replays
|
|
51
|
+
it until then. The Relay can charge the resend as a new message, and the
|
|
52
|
+
message might already have arrived. `onSendOutcome` reports the end of each
|
|
53
|
+
resend once, with `manualResend`. Only a send younger than 30 days takes a
|
|
54
|
+
new resend.
|
|
55
|
+
- `outcome` on `DeviceSetReconciliationError`: `failed` or
|
|
56
|
+
`acceptance-unknown`. With `acceptance-unknown`, the message might have
|
|
57
|
+
arrived. Treat it like `SendAcceptanceUnknownError`.
|
|
58
|
+
- Relay protocol version 2, and its Relay code `DELIVERY_ALREADY_ACCEPTED`.
|
|
59
|
+
The Relay gives the code to a version 2 request, with HTTP status 409,
|
|
60
|
+
`retryable` false and the `details` reason `message-id-held`, when it
|
|
61
|
+
already holds an accepted post under the message ID. It stored nothing
|
|
62
|
+
for the post. A version 1 request gets `RETRY_CONFLICT` for the same case.
|
|
63
|
+
The SDK reads the code as it reads `RETRY_CONFLICT`: on a direct post, a
|
|
64
|
+
sealed direct post, a pre-message and a group shared body, it is an earlier
|
|
65
|
+
acceptance with no receipt, under the same rules. The sealed path keeps the
|
|
66
|
+
code on its error. In the answer to a version 1 request, the code is an
|
|
67
|
+
unknown Relay code.
|
|
68
|
+
|
|
69
|
+
### Changed
|
|
70
|
+
|
|
71
|
+
- A direct send now has a posting deadline: the earlier of 24 hours after the
|
|
72
|
+
SDK first stores it and 24 hours after its timestamp. A replay or a restart
|
|
73
|
+
never moves it. SDK 13.4 had no posting deadline.
|
|
74
|
+
- At or after the deadline, the SDK starts no request for the send. This
|
|
75
|
+
includes a transport repeat and the identified fallback. A request that
|
|
76
|
+
started before the deadline still counts when its answer arrives later.
|
|
77
|
+
- SDK 13.4 posted a direct send whose timestamp was exactly 24 hours old. The
|
|
78
|
+
SDK now stores it, posts nothing and throws `SendNeverAcceptedByRelayError`.
|
|
79
|
+
- SDK 13.4 posted an attachment send whose upload finished after its
|
|
80
|
+
timestamp plus 24 hours. The SDK now posts nothing and throws.
|
|
81
|
+
- SDK 13.4 replayed a stored direct send after 24 hours and posted it again.
|
|
82
|
+
The SDK now posts nothing at or after the deadline, and the replay ends
|
|
83
|
+
with `SendAcceptanceUnknownError` or the failed-end error of the next entry.
|
|
84
|
+
- When a send ends failed and the call that ends it raised a refusal, the
|
|
85
|
+
first such refusal is the error. A thrown refusal keeps its SDK 13.4 class,
|
|
86
|
+
and a refusal in the receipt of a shared body is an `Error` with its `code`.
|
|
87
|
+
Otherwise, the end throws an `Error` with the `code` of the first refused
|
|
88
|
+
device that has a stored code, in the order of the destinations. With no
|
|
89
|
+
such device, it throws `SendNeverAcceptedByRelayError`. A replay of the
|
|
90
|
+
ended send raises no refusal. Each of these errors has `acceptedDevices`,
|
|
91
|
+
`refusedDevices` and `deadlineAt`.
|
|
92
|
+
- Before the deadline, a send error that leaves a device open now has
|
|
93
|
+
`retryable` set to true. In SDK 13.4 that field held only the Relay's hint.
|
|
94
|
+
`relayRetryable` now keeps that hint.
|
|
95
|
+
- SDK 13.4 threw `RETRY_CONFLICT` from a direct send or a sealed direct send
|
|
96
|
+
when the Relay already held bytes under its ID. The SDK now counts that
|
|
97
|
+
answer as an earlier acceptance, and the send goes on. This applies when the
|
|
98
|
+
SDK stored the send from its first post, and no repair replaced the session
|
|
99
|
+
of that device.
|
|
100
|
+
- In other cases, the acceptance of that device is unknown. Before the
|
|
101
|
+
deadline, the send still throws `RETRY_CONFLICT`, now with `retryable` true
|
|
102
|
+
and `deadlineAt`. At the deadline, it throws `SendAcceptanceUnknownError`.
|
|
103
|
+
- Such an answer has no Relay receipt. The send result takes its `messageId`
|
|
104
|
+
from a Relay receipt of another device when one exists. When every accepted
|
|
105
|
+
device gave that answer, `messageId` is the `clientMessageId`.
|
|
106
|
+
- Such an answer raises no `DEVICE_SET_UNCHECKED` report through
|
|
107
|
+
`onRelayProtocolError`, because it has no receipt to check.
|
|
108
|
+
- SDK 13.4 threw `RETRY_CONFLICT` from a group send when a pre-message got it.
|
|
109
|
+
The group send now goes on. A pre-message that counts it as an acceptance
|
|
110
|
+
records the sender-key handoff, as for any acceptance.
|
|
111
|
+
- A pre-message whose session the SDK replaced records no handoff when it
|
|
112
|
+
gets that answer, and the acceptance of its device is unknown. The next
|
|
113
|
+
group send gives the key again. This also holds on a replay.
|
|
114
|
+
- SDK 13.4 threw from an undeclared send when a sync copy failed. When the
|
|
115
|
+
deadline stops a sync copy, the send now returns `syncPending`. A replay of
|
|
116
|
+
that send returns the same result and posts nothing. Other sync failures
|
|
117
|
+
still throw.
|
|
118
|
+
- A replay of a send with `syncPending` posts the pending sync copies only
|
|
119
|
+
before `deadlineAt`. At or after it, the replay posts nothing and returns
|
|
120
|
+
the stored result with `syncPending`.
|
|
121
|
+
- One case differs. When the send has no sync copies yet, the replay reads
|
|
122
|
+
the own device list again. If it finds no other own device, the send
|
|
123
|
+
completes without `syncPending`.
|
|
124
|
+
- A replay of an ended send with the same content throws the stored result
|
|
125
|
+
again and posts nothing. A DataMessage replay takes the stored timestamp.
|
|
126
|
+
- A replay of a direct send now posts only the devices that the Relay did not
|
|
127
|
+
accept. SDK 13.4 posted every device again. A replay also skips the sync
|
|
128
|
+
copies that the Relay accepted.
|
|
129
|
+
- A replay of a DataMessage send now keeps its stored timestamp. SDK 13.4 read
|
|
130
|
+
a new timestamp and refused the replay as a different message.
|
|
131
|
+
- A `RETRY_CONFLICT` answer counts as an earlier acceptance unless the SDK
|
|
132
|
+
replaced the session of that device. A repair that adds a missing device
|
|
133
|
+
after `DEVICE_SET_MISMATCH` replaces nothing, so the added device counts as
|
|
134
|
+
accepted. A device whose session the SDK replaced after `STALE_DEVICE`
|
|
135
|
+
stays unknown, because the Relay can hold a message sealed to the old
|
|
136
|
+
session. This now also holds on a replay of a send that this SDK version
|
|
137
|
+
stored. On a replay of a send that SDK 13.4 stored, a `RETRY_CONFLICT`
|
|
138
|
+
answer stays uncertain.
|
|
139
|
+
- A send or its replay now ends at once, before the deadline, and posts
|
|
140
|
+
nothing, when every open device got `OPERATION_EXPIRED` as the last answer
|
|
141
|
+
in the call or has a refusal that the SDK cannot recover, and throws an `Error` with the stored
|
|
142
|
+
code of the first refused device that has one, in the order of the
|
|
143
|
+
destinations.
|
|
144
|
+
A `STALE_DEVICE` refusal counts only after the SDK repaired the session and
|
|
145
|
+
the Relay refused the repaired post too. A request with no answer, an
|
|
146
|
+
uncertain answer, or a send stored by SDK 13.4 still gives
|
|
147
|
+
`SendAcceptanceUnknownError`.
|
|
148
|
+
- A send that an earlier SDK stored gets its deadline from its stored times.
|
|
149
|
+
The SDK stores that deadline at its next change of the send.
|
|
150
|
+
- A group send now has the same posting deadline as a direct send. SDK 13.4
|
|
151
|
+
posted a group send whose timestamp was exactly 24 hours old, and it
|
|
152
|
+
replayed a stored group send after 24 hours. Both now post nothing at the
|
|
153
|
+
deadline, and the send ends with `SendAcceptanceUnknownError` or the
|
|
154
|
+
failed-end error of the direct send rule. The deadline also stops a pre-message, its
|
|
155
|
+
identified fallback, the shared body and a sync copy.
|
|
156
|
+
- A group send now records the Relay answer of each device: of each
|
|
157
|
+
pre-message, of each device post, and of the shared body for each of its
|
|
158
|
+
destinations. A replay posts only the devices that the Relay did not
|
|
159
|
+
accept. A device that the receipt of the shared body refuses counts as
|
|
160
|
+
refused, as a thrown refusal does, and the end error follows the rule of a
|
|
161
|
+
direct send. A replay of the ended send gives the stored code of the first
|
|
162
|
+
refused device that has one, in the order of the destinations. That code
|
|
163
|
+
can differ from the code of the call.
|
|
164
|
+
- A `RETRY_CONFLICT` answer to the shared body of a group send counts as an
|
|
165
|
+
earlier acceptance of each of its destinations. It raises no
|
|
166
|
+
`DEVICE_SET_UNCHECKED` report through `onRelayProtocolError`. The answer
|
|
167
|
+
has no receipt that can ask for a sync phase, so the send reads the own
|
|
168
|
+
device list once to find the devices that need a sync copy.
|
|
169
|
+
- A `RETRY_CONFLICT` answer to a group device post or pre-message whose
|
|
170
|
+
session the SDK replaced after `STALE_DEVICE` gives acceptance-unknown for
|
|
171
|
+
that device. On a device that a repair only added, or that no repair
|
|
172
|
+
changed, it counts as an earlier acceptance. The call and a replay after a
|
|
173
|
+
restart give the device the same class.
|
|
174
|
+
- SDK 13.4 started a send that ended with `DeviceSetReconciliationError`
|
|
175
|
+
again at 0 restarts when the application called `send()` with the same
|
|
176
|
+
`clientMessageId`. After an end in the recipient phase, the SDK now stores
|
|
177
|
+
the send outcome. That call throws `SendAcceptanceUnknownError` or
|
|
178
|
+
`SendNeverAcceptedByRelayError` and posts nothing. After an end in the sync
|
|
179
|
+
phase, the send keeps its result, and that call posts the sync phase again.
|
|
180
|
+
- An `UPGRADE_REQUIRED` or `DEVICE_REVOKED` answer now ends a send at once as
|
|
181
|
+
failed, or as acceptance-unknown when the acceptance of a device is not
|
|
182
|
+
known. SDK 13.4 threw the answer and left the send open.
|
|
183
|
+
- A recipient now drops a message that carries the same sender device, the
|
|
184
|
+
same content timestamp and the same content as a message it already
|
|
185
|
+
received. The drop also covers a copy under a new message ID, such as a
|
|
186
|
+
manual resend. Two different messages of one sender device in one
|
|
187
|
+
millisecond both deliver. The drop needs the timestamp that the content
|
|
188
|
+
adapter reads from the message. Content with no timestamp, such as raw
|
|
189
|
+
string or byte content, takes no drop key, and a recipient that holds it
|
|
190
|
+
receives the copy again. The recipient records the message with the
|
|
191
|
+
completion of its receive record. When a delivery receipt is due, it
|
|
192
|
+
records the message right after the receipt-due write and again with the
|
|
193
|
+
completion of the receipt. When no receipt is owed, a stop before the
|
|
194
|
+
completion of the receive record runs `onMessageDecrypted` again. When a
|
|
195
|
+
receipt is owed, only a stop before the receipt-due write runs it again.
|
|
196
|
+
The record expires after 60 days.
|
|
197
|
+
- A retry resend no longer encrypts again under the same ID after the Relay
|
|
198
|
+
answers `OPERATION_EXPIRED` to its stored bytes. SDK 13.4 encrypted the
|
|
199
|
+
content again with a fresh operation epoch and posted the new bytes. The SDK
|
|
200
|
+
now posts nothing more under that ID. It records that the acceptance of the
|
|
201
|
+
attempt is unknown.
|
|
202
|
+
- The same applies to a stored null-message answer and to the current
|
|
203
|
+
sender-key distribution that answers a group retry request. SDK 13.4
|
|
204
|
+
encrypted both again under the same ID. For the distribution, the SDK still
|
|
205
|
+
deletes the sender-key handoff of the requester, as SDK 13.4 does, so the
|
|
206
|
+
next group send gives the key again.
|
|
207
|
+
- When the plaintext of that message is gone, the SDK still posts the
|
|
208
|
+
null-message session reset under its own ID, as SDK 13.4 does.
|
|
209
|
+
- The SDK still counts such an answer toward the response limit, and it still
|
|
210
|
+
completes a group resend job as posted, as SDK 13.4 does after its post.
|
|
211
|
+
- A later retry request from the same device has a new attempt and a new ID,
|
|
212
|
+
so it gets a new encryption, as in SDK 13.4.
|
|
213
|
+
- A hosted group fan-out post now repeats once when the Relay answers 503
|
|
214
|
+
`DELIVERY_UNCERTAIN`. The repeat sends the identical request with the same
|
|
215
|
+
`logicalSendId`, as a direct post does. SDK 13.4 threw that error after the
|
|
216
|
+
first answer. A second uncertain answer reaches the caller. No other error
|
|
217
|
+
code starts a repeat.
|
|
218
|
+
- After such a repeat, the group send result has no `duplicate` field,
|
|
219
|
+
because the first request can have stored the fan-out.
|
|
220
|
+
- A send can be stored without its timestamp lookup when a write fails
|
|
221
|
+
between the two. Without the lookup, an E2EE delivery receipt for the
|
|
222
|
+
message gives no delivery event, and a retry request for a group message
|
|
223
|
+
does not find its group. When the SDK stores the same send again, it now
|
|
224
|
+
also stores a missing lookup and changes nothing else in the stored send.
|
|
225
|
+
SDK 13.4 did not. A replay of a stored send does not store it again in this
|
|
226
|
+
release, so a replay does not restore the lookup.
|
|
227
|
+
- Each hosted client now holds its Relay protocol version internally, and
|
|
228
|
+
every Relay request and the mailbox socket of that client send it. SDK 13.4
|
|
229
|
+
read one fixed version for the whole SDK. No option changes it.
|
|
230
|
+
- The default Relay protocol version is now version 2. Each Relay request
|
|
231
|
+
sends `x-open-e2ee-relay-protocol: 2`, and the mailbox socket offers
|
|
232
|
+
`open-e2ee-relay.v2`. SDK 13.4 sent version 1. A Relay that does not serve
|
|
233
|
+
version 2 answers `PROTOCOL_UNSUPPORTED`, and a send keeps the device open
|
|
234
|
+
and retryable until its posting deadline. The SDK does not fall back to
|
|
235
|
+
version 1. The Relay serves version 1 for at least 180 days after the
|
|
236
|
+
publish of this release, and the earliest end date is 2027-04-30.
|
|
237
|
+
See step 19.
|
|
238
|
+
- `HostedRelayUpgradeRequiredError` names the protocol version that the
|
|
239
|
+
client sent, and its constructor takes an optional `version`. Without it,
|
|
240
|
+
the message names version 1, as in SDK 13.4.
|
|
241
|
+
- A retry request now has a posting deadline 24 hours after the first
|
|
242
|
+
failure of its message, and no post of it starts at or after that time. A
|
|
243
|
+
request whose post is due then ends with the new terminal class
|
|
244
|
+
`posting-deadline`. SDK 13.4 posted a replacement request after
|
|
245
|
+
`OPERATION_EXPIRED`. The SDK now ends that request as `posting-deadline`
|
|
246
|
+
with acceptance unknown, because the request might have arrived, and posts
|
|
247
|
+
no replacement. Each `posting-deadline` end resets the session and reports
|
|
248
|
+
one `onRetryTerminal` event. After its posting deadline, a request whose
|
|
249
|
+
post the Relay accepted posts nothing more and waits for its content until
|
|
250
|
+
its 14-day deadline. A request that SDK 13.4 stored gets a posting deadline
|
|
251
|
+
from its first failure, and at most its deadline. SDK 13.4 reads a stored
|
|
252
|
+
`posting-deadline` record as corrupt, so do not downgrade after one exists.
|
|
253
|
+
- A retry request that gets `DELIVERY_ALREADY_ACCEPTED` from a version 2
|
|
254
|
+
Relay reads it as the acceptance of its stored attempt, as it reads
|
|
255
|
+
`RETRY_CONFLICT`. No replacement attempt posts.
|
|
256
|
+
- SDK 13.4 never replayed a send by itself. The application had to call
|
|
257
|
+
`send()` again with the same `clientMessageId`. That call is still safe, and
|
|
258
|
+
the SDK runs it after its own replay of the same send.
|
|
259
|
+
|
|
260
|
+
### Deprecated
|
|
261
|
+
|
|
262
|
+
Each entry names a change in the next major SDK version. Nothing in this
|
|
263
|
+
release changes for these items. The upgrade steps below say what to do now.
|
|
264
|
+
|
|
265
|
+
- Group content with no group context. The next major no longer decides it,
|
|
266
|
+
so content from an SDK 11 sender is not delivered. The denial reason
|
|
267
|
+
`legacy-no-context` then applies to all such content. See step 13.
|
|
268
|
+
- `ReceivedContent`. The next major removes the type and the first-open
|
|
269
|
+
conversion of SDK 11 received-content rows. See step 14.
|
|
270
|
+
- `SignalProtocolContentAdapter`. The next major adds the required method
|
|
271
|
+
`serializeGroupKeySync`, and `ParsedSyncContent.type` gets `groupKeySync`.
|
|
272
|
+
See step 15.
|
|
273
|
+
- The retry terminal class `expired-content`. The next major renames it to
|
|
274
|
+
`request-expired`. See step 16.
|
|
275
|
+
- A repeated send timestamp of one device. The next major makes each send
|
|
276
|
+
timestamp unique per sender device, and refuses a new send that repeats the
|
|
277
|
+
timestamp of a different send of the device with `InvalidSendTimestampError`.
|
|
278
|
+
A retry with the same `clientMessageId` keeps its timestamp. See step 17.
|
|
279
|
+
- `ReceiveWorkRecord.received.contentDigest` and
|
|
280
|
+
`ReceiveWorkRecord.received.senderDeviceId`, the fields of the received
|
|
281
|
+
message key, and the rule that two different messages of one sender device
|
|
282
|
+
with one timestamp both deliver. The next major keys a received message by its
|
|
283
|
+
sender and timestamp only, and drops a later message with the same key.
|
|
284
|
+
See step 18.
|
|
285
|
+
|
|
286
|
+
### Fixed
|
|
287
|
+
|
|
288
|
+
- The SDK reports a Signal Protocol Relay environment mismatch only for HTTP403
|
|
289
|
+
with the `SCOPE_MISMATCH` error code. Other403 responses use the generic
|
|
290
|
+
connection error.
|
|
291
|
+
- When a request envelope comes again, the SDK now gives `storeResendJob`
|
|
292
|
+
the first `createdAt` of the group resend job. SDK 13.4 gave it the time
|
|
293
|
+
of the new delivery. The built-in stores keep the first value, as the
|
|
294
|
+
store contract states, so their one-day end of the job did not move. A
|
|
295
|
+
custom store that stored the given value restarted that day on each
|
|
296
|
+
repeated request, so the job could stay alive past one day.
|
|
297
|
+
- A binary send now has one upload and one serialized attachment message for
|
|
298
|
+
each `clientMessageId`, across lost Relay replies and restarts. This
|
|
299
|
+
applies to direct and group sends. The stored intent keeps the message and
|
|
300
|
+
the digest of the file. A repeat sends the stored message under the stored
|
|
301
|
+
timestamp and uploads nothing. A repeat of a completed send returns the
|
|
302
|
+
stored result, with `storageId`, `aesKey`, `segmentSize`, `digest` and
|
|
303
|
+
`contentType`. SDK 13.4 uploaded the file again on each repeat, and the
|
|
304
|
+
repeat then failed with `A clientMessageId cannot identify two different
|
|
305
|
+
logical sends`.
|
|
306
|
+
- A binary repeat with another file, other pointer metadata, another
|
|
307
|
+
recipient or another explicit `timestamp` now throws that error before any
|
|
308
|
+
upload. The pointer metadata comes from the send options: `mimeType`,
|
|
309
|
+
`caption`, `fileName`, `isViewOnce`, `flags`, `blurHash`, `thumbnail`,
|
|
310
|
+
`width`, `height`, `durationMs`, `waveform`, `clientUuid` and `cdnNumber`.
|
|
311
|
+
A repeat that omits `clientUuid` keeps the stored one. A group recipient in
|
|
312
|
+
place of a direct recipient, or the reverse, is another recipient. A repeat
|
|
313
|
+
of an intent that has no stored attachment message also throws it before
|
|
314
|
+
any upload. This includes a text send and a binary send that SDK 13.4
|
|
315
|
+
stored.
|
|
316
|
+
- A binary send without a caller `timestamp` now reads the SDK clock once,
|
|
317
|
+
before the upload. The attachment message and the stored intent get the
|
|
318
|
+
same timestamp. SDK 13.4 read the clock after the upload, once for the
|
|
319
|
+
message and again for the intent, so the two timestamps could differ.
|
|
320
|
+
|
|
321
|
+
### Limits
|
|
322
|
+
|
|
323
|
+
- A replay or a resend after `SendAcceptanceUnknownError` can add one charged
|
|
324
|
+
unit within 24 hours, when the Relay no longer holds its record of the first
|
|
325
|
+
acceptance.
|
|
326
|
+
|
|
327
|
+
#### Upgrade steps
|
|
328
|
+
|
|
329
|
+
1. Catch `SendAcceptanceUnknownError`. Tell the user that the message might
|
|
330
|
+
already have arrived, and do not replay the send.
|
|
331
|
+
2. Catch `SendNeverAcceptedByRelayError`, and also any send error with
|
|
332
|
+
`refusedDevices`. Tell the user which devices did not get the message.
|
|
333
|
+
3. For another send error, read `deadlineAt`. With a store that implements
|
|
334
|
+
`listMetadataKeys`, the SDK replays the send until then and reports its end
|
|
335
|
+
once through `onSendOutcome`. Do not build your own replay loop. Without
|
|
336
|
+
that method, replay with the same `clientMessageId` before `deadlineAt`, as
|
|
337
|
+
step 11 says. A call of `send()` with the same `clientMessageId` is safe.
|
|
338
|
+
4. Code written for SDK 13.4 compiles unchanged. Check any code that reads
|
|
339
|
+
`retryable` on a send error, and any code that sends with a timestamp
|
|
340
|
+
close to 24 hours old.
|
|
341
|
+
5. A custom metadata store needs no change to keep working. The new record and
|
|
342
|
+
intent fields travel inside the stored JSON value. A store that also
|
|
343
|
+
implements the optional `listMetadataKeys` gets the automatic send driver.
|
|
344
|
+
See step 11.
|
|
345
|
+
6. A direct send that first stores a message now resolves on `RETRY_CONFLICT`
|
|
346
|
+
when no repair changed it. Other `RETRY_CONFLICT` errors now carry
|
|
347
|
+
`retryable` and `deadlineAt`, so follow step 3 for them.
|
|
348
|
+
7. Code that reads `messageId` from a send result must accept the
|
|
349
|
+
`clientMessageId` in that field. That occurs only when every accepted
|
|
350
|
+
device answered `RETRY_CONFLICT`.
|
|
351
|
+
8. A device that downgrades to SDK 13.4 ignores the new record fields. It
|
|
352
|
+
can then encrypt one expired retry-resend attempt again, as SDK 13.4 does.
|
|
353
|
+
9. Handle the new `posting-deadline` class in `onRetryTerminal`. The session
|
|
354
|
+
resets, and the request might have arrived. Do not downgrade below this
|
|
355
|
+
release after it ends a retry request as `posting-deadline`: an older SDK
|
|
356
|
+
reads that record as corrupt. A 13.4 record that is due, already past
|
|
357
|
+
its derived posting deadline, and not yet past its deadline ends right
|
|
358
|
+
after the upgrade as `posting-deadline`, with a session reset.
|
|
359
|
+
10. Handle `SendAcceptanceUnknownError` and `SendNeverAcceptedByRelayError` on
|
|
360
|
+
group sends too.
|
|
361
|
+
11. A custom metadata store can implement the optional `listMetadataKeys` to
|
|
362
|
+
get the automatic send driver. Run the store conformance suite to check it.
|
|
363
|
+
The suite skips its listing cases on a store without the method. Without
|
|
364
|
+
the method, the SDK does not replay open sends by itself, and it logs one
|
|
365
|
+
line at each client start. Replay with the same `clientMessageId` before
|
|
366
|
+
`deadlineAt`. `onSendOutcome` still reports each end of a send that your
|
|
367
|
+
application posts.
|
|
368
|
+
12. Read `outcome` on `DeviceSetReconciliationError`. When it is set, a call
|
|
369
|
+
of `send()` with the same `clientMessageId` posts nothing and throws the
|
|
370
|
+
error of the stored end. To post a message again after a send end, call
|
|
371
|
+
`resendMessage`. The Relay can charge the resend as a new message. Only a
|
|
372
|
+
send younger than 30 days takes a new resend. At or after 30 days,
|
|
373
|
+
`resendMessage` throws `Only a send younger than 30 days takes a manual
|
|
374
|
+
resend` and posts nothing. The receive queue drops the copy when the
|
|
375
|
+
content adapter reads a timestamp from the content. The
|
|
376
|
+
recipient records the message with the completion of its receive record,
|
|
377
|
+
or, when a receipt is due, right after the receipt-due write and again
|
|
378
|
+
with the completion of the receipt. The caller-origin receive path gives
|
|
379
|
+
every decrypted message to the caller, and a caller that keeps its own
|
|
380
|
+
records removes a copy itself. A recipient on an SDK version before this
|
|
381
|
+
release does not drop the resend copy, so it can show the message twice.
|
|
382
|
+
13. Move every client that sends to a managed group to SDK 12.0.0 or later
|
|
383
|
+
before the next major. SDK 12.0.0 and later put the group context in group
|
|
384
|
+
content. The next major no longer decides group content that has no group
|
|
385
|
+
context, so content from an SDK 11 sender is not delivered.
|
|
386
|
+
14. Open each durable store once on SDK 13.x before the next major. The open
|
|
387
|
+
converts the SDK 11 received-content rows to receive records. The next
|
|
388
|
+
major does not read or convert them. Stop using the `ReceivedContent` type,
|
|
389
|
+
and use `ReceiveWorkRecord`.
|
|
390
|
+
15. If you implement `SignalProtocolContentAdapter` yourself, plan to add the
|
|
391
|
+
method `serializeGroupKeySync` in the next major. If you switch on
|
|
392
|
+
`ParsedSyncContent.type`, plan to handle `'groupKeySync'`. An adapter that
|
|
393
|
+
spreads the result of `createDefaultSignalProtocolContentAdapter()` into
|
|
394
|
+
itself gets the default method. Upgrade every own device of one account in
|
|
395
|
+
one release. An own device on an older SDK version gives the raw group key
|
|
396
|
+
sync to `onMessageDecrypted`.
|
|
397
|
+
16. Prepare `onRetryTerminal` for the rename of `expired-content` to
|
|
398
|
+
`request-expired` in the next major. On 13.x, `RetryTerminalClass` does not
|
|
399
|
+
hold `request-expired`, so a `case 'request-expired':` does not compile.
|
|
400
|
+
Keep the `expired-content` branch, and give every exhaustive switch on the
|
|
401
|
+
class a default branch that does not throw. Add the `request-expired` case
|
|
402
|
+
when you upgrade to the major. Do not confuse it with the delivery error
|
|
403
|
+
cause `request-ended`.
|
|
404
|
+
17. Give each send of one device its own timestamp. The next major makes the
|
|
405
|
+
timestamp unique per sender device. A new send with a timestamp that a
|
|
406
|
+
different send of the device used throws `InvalidSendTimestampError`. A
|
|
407
|
+
retry with the same `clientMessageId` keeps its timestamp. For a
|
|
408
|
+
`DataMessage` send, match delivery receipts with the returned
|
|
409
|
+
`SendResult.clientTimestamp`. For other content, keep the
|
|
410
|
+
`SendOptions.timestamp` that you supply.
|
|
411
|
+
18. Do not rely on two messages of one sender with one timestamp both
|
|
412
|
+
delivering. Two different messages of one sender device with one timestamp
|
|
413
|
+
both deliver in 13.x. In the next major, a recipient keeps the first such
|
|
414
|
+
message and drops a later one with no notice, also when another device of
|
|
415
|
+
the sender sent it. A custom store that checks or stores
|
|
416
|
+
`ReceiveWorkRecord.received` must accept a key with no `contentDigest` and
|
|
417
|
+
no `senderDeviceId`.
|
|
418
|
+
19. This release sends Relay protocol version 2. The Relay serves version 1
|
|
419
|
+
for at least 180 days after the publish of this release, and the earliest
|
|
420
|
+
end date is 2027-04-30. After that date, the Relay can stop
|
|
421
|
+
serving version 1, and SDK 13.4 and earlier stop. From SDK 10.1.0, an
|
|
422
|
+
HTTP call then throws `HostedRelayUpgradeRequiredError`, and the mailbox
|
|
423
|
+
subscription stops with the connection reason `upgrade-required`. Move
|
|
424
|
+
every client to this release or later before that date.
|
|
425
|
+
|
|
3
426
|
## 13.4.0
|
|
4
427
|
|
|
5
428
|
### Added
|
package/README.md
CHANGED
|
@@ -16,14 +16,10 @@ The default policy requires post-quantum session establishment and ratcheting. T
|
|
|
16
16
|
[](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
|
|
17
17
|
[](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml)
|
|
18
18
|
|
|
19
|
-
[Documentation](https://docs.open-e2ee.dev) · [API reference](https://docs.open-e2ee.dev/reference/api) · [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) · [Security](./SECURITY.md)
|
|
19
|
+
[Documentation](https://docs.open-e2ee.dev) · [API reference](https://docs.open-e2ee.dev/reference/api) · [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay/) · [Security](./SECURITY.md)
|
|
20
20
|
|
|
21
21
|
## See an encrypted round trip
|
|
22
22
|
|
|
23
|
-
Press play for device setup, session establishment, encrypted delivery, and decryption on each device.
|
|
24
|
-
|
|
25
|
-
https://github.com/user-attachments/assets/d8002bc3-c037-41b6-8f48-4008f2d49e6c
|
|
26
|
-
|
|
27
23
|
The [visual demo](https://open-e2ee.dev/#demo) shows the envelope, ratchets, relay mailbox, and decrypted result. On desktop, type a message and inspect each step. On mobile, a recorded protocol run replays at reading pace. Displayed timings exclude network time.
|
|
28
24
|
|
|
29
25
|
The demonstrations use real protocol code and cryptography. Application integration requires device-local storage and authenticated delivery.
|
|
@@ -33,13 +29,13 @@ The demonstrations use real protocol code and cryptography. Application integrat
|
|
|
33
29
|
- **Session establishment and ratcheting.** PQXDH establishes sessions. The ML-KEM Braid ratchet adds post-quantum key updates. Required post-quantum operations fail closed.
|
|
34
30
|
- **Chat features.** Multi-device messaging, groups, sealed sender, encrypted attachments, and safety-number verification use the same package.
|
|
35
31
|
- **Device-local state.** Storage adapters keep identities, sessions, and message state on the device.
|
|
36
|
-
- **Hosted delivery.** Connect to [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) with the hosted client factory. Advanced integrations can supply a custom transport. A hosted client sends a sealed 1:1 message only with `hosted.profileKeys
|
|
32
|
+
- **Hosted delivery.** Connect to [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay/) with the hosted client factory. Advanced integrations can supply a custom transport. A hosted client sends a sealed 1:1 message only with `hosted.profileKeys`. It must also hold the contact's profile key.
|
|
37
33
|
|
|
38
34
|
The relay never needs message plaintext or device private keys.
|
|
39
35
|
|
|
40
36
|
The OpenE2EE Signal Protocol SDK implements a versioned profile of the published Signal Protocol specifications. It is not affiliated with Signal Messenger and is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate. See the [notice](./NOTICE) and [documented deviations](./docs/DEVIATIONS.md).
|
|
41
37
|
|
|
42
|
-
Version `13.
|
|
38
|
+
Version `13.5.x`. Public APIs and persisted formats follow semantic versioning.
|
|
43
39
|
|
|
44
40
|
## Install
|
|
45
41
|
|
|
@@ -105,7 +101,7 @@ See [client composition](./docs/CLIENT_COMPOSITION.md) for platform setup.
|
|
|
105
101
|
|
|
106
102
|
## Use your app’s storage and relay
|
|
107
103
|
|
|
108
|
-
Choose the device-local store for your runtime. Then supply a relay that authenticates each device and implements your product's access policy, or use [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) as the managed delivery path. The SDK does not require the managed service. [Review Relay plans and exact meter definitions.](https://open-e2ee.dev/relay
|
|
104
|
+
Choose the device-local store for your runtime. Then supply a relay that authenticates each device and implements your product's access policy, or use [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay/) as the managed delivery path. The SDK does not require the managed service. [Review Relay plans and exact meter definitions.](https://open-e2ee.dev/pricing/#relay-plans)
|
|
109
105
|
|
|
110
106
|
| Runtime | Storage path | Deployment boundary |
|
|
111
107
|
|---|---|---|
|
package/SECURITY.md
CHANGED
package/TROUBLESHOOTING.md
CHANGED
|
@@ -59,15 +59,22 @@ with `--force` or `--legacy-peer-deps`.
|
|
|
59
59
|
|
|
60
60
|
**"Identity key not found - client not initialized"**
|
|
61
61
|
|
|
62
|
-
<!-- doc-snippet:
|
|
62
|
+
<!-- doc-snippet:skip requires-application-storage -->
|
|
63
63
|
```typescript
|
|
64
|
-
|
|
65
|
-
const signal = new DefaultSignalProtocolClient(); // Don't use constructor directly!
|
|
66
|
-
await signal.encryptMessage(...); // Error!
|
|
64
|
+
import { DefaultSignalProtocolClient, type SignalProtocolClientConfig } from '@open-e2ee/signal-protocol-sdk';
|
|
67
65
|
|
|
68
|
-
//
|
|
69
|
-
|
|
70
|
-
|
|
66
|
+
// Compile-only negative example. This function is never called.
|
|
67
|
+
function compileOnlyRejectsDirectConstruction(): void {
|
|
68
|
+
// @ts-expect-error Initialize the client through its asynchronous factory.
|
|
69
|
+
new DefaultSignalProtocolClient();
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function initializeSignal(
|
|
73
|
+
userId: string,
|
|
74
|
+
storage: SignalProtocolClientConfig['storage'],
|
|
75
|
+
): Promise<DefaultSignalProtocolClient> {
|
|
76
|
+
return DefaultSignalProtocolClient.create(userId, { storage });
|
|
77
|
+
}
|
|
71
78
|
```
|
|
72
79
|
|
|
73
80
|
### Session Establishment
|
|
@@ -78,31 +85,44 @@ Make sure the prekey bundle is fresh and valid:
|
|
|
78
85
|
|
|
79
86
|
<!-- doc-snippet:skip requires-external-context -->
|
|
80
87
|
```typescript
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
88
|
+
import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
89
|
+
import type { SignalProtocolRelayServer } from '@open-e2ee/signal-protocol-sdk/remote/relay';
|
|
90
|
+
|
|
91
|
+
export async function establishBobSession(
|
|
92
|
+
signal: DefaultSignalProtocolClient,
|
|
93
|
+
relay: SignalProtocolRelayServer,
|
|
94
|
+
bobId: string,
|
|
95
|
+
): Promise<void> {
|
|
96
|
+
const address = ProtocolAddress.create(bobId, 1);
|
|
97
|
+
const bundle = await relay.fetchPreKeyBundle(bobId, 1, undefined, 'aci');
|
|
98
|
+
if (!bundle || !bundle.identity || !bundle.ecSignedPreKey) {
|
|
99
|
+
throw new Error('Invalid prekey bundle');
|
|
100
|
+
}
|
|
101
|
+
await signal.establishSession(address, bundle);
|
|
87
102
|
}
|
|
88
|
-
|
|
89
|
-
await signal.establishSession(sessionId, bobId, bundle);
|
|
90
103
|
```
|
|
91
104
|
|
|
92
|
-
###
|
|
105
|
+
### Device Address Format
|
|
93
106
|
|
|
94
107
|
**"No session with address"**
|
|
95
108
|
|
|
96
|
-
|
|
109
|
+
The serialized address form is `userId:deviceId`. Direct client methods take a
|
|
110
|
+
`ProtocolAddress` object. Create it with `ProtocolAddress.create(userId, deviceId)`.
|
|
97
111
|
|
|
98
112
|
<!-- doc-snippet:skip requires-external-context -->
|
|
99
113
|
```typescript
|
|
100
|
-
|
|
101
|
-
await signal.encryptMessage('bob', 'Hello');
|
|
114
|
+
import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
102
115
|
|
|
103
|
-
//
|
|
104
|
-
|
|
105
|
-
|
|
116
|
+
// Compile-only negative example. This function is never called.
|
|
117
|
+
async function compileOnlyRejectsSerializedAddress(signal: DefaultSignalProtocolClient): Promise<void> {
|
|
118
|
+
// @ts-expect-error encryptMessage requires a ProtocolAddress object.
|
|
119
|
+
await signal.encryptMessage('bob', 'Hello');
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export async function encryptToBobDevices(signal: DefaultSignalProtocolClient): Promise<void> {
|
|
123
|
+
await signal.encryptMessage(ProtocolAddress.create('bob', 1), 'Hello');
|
|
124
|
+
await signal.encryptMessage(ProtocolAddress.create('bob', 2), 'Hello');
|
|
125
|
+
}
|
|
106
126
|
```
|
|
107
127
|
|
|
108
128
|
### Out-of-Order Messages
|
|
@@ -144,19 +164,27 @@ console.log('OneTime prekeys remaining:', stats.oneTimePreKeysCount);
|
|
|
144
164
|
|
|
145
165
|
<!-- doc-snippet:skip requires-external-context -->
|
|
146
166
|
```typescript
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
167
|
+
import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
168
|
+
|
|
169
|
+
export async function checkBobSession(signal: DefaultSignalProtocolClient): Promise<void> {
|
|
170
|
+
const address = ProtocolAddress.create('bob', 1);
|
|
171
|
+
const hasSession = await signal.hasSession(address);
|
|
172
|
+
console.log('Has session with bob:1:', hasSession);
|
|
173
|
+
}
|
|
150
174
|
```
|
|
151
175
|
|
|
152
176
|
### Enable Debug Logging
|
|
153
177
|
|
|
154
178
|
<!-- doc-snippet:skip requires-external-context -->
|
|
155
179
|
```typescript
|
|
156
|
-
|
|
180
|
+
import { DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
181
|
+
import { inMemoryStore } from '@open-e2ee/signal-protocol-sdk/local/store/memory';
|
|
182
|
+
|
|
183
|
+
const signal = await DefaultSignalProtocolClient.create('alice', {
|
|
184
|
+
storage: inMemoryStore(),
|
|
157
185
|
enableDebugLogging: true,
|
|
158
186
|
});
|
|
159
|
-
//
|
|
187
|
+
// The in-memory adapter is for this local example. Select a protected platform store in an application.
|
|
160
188
|
```
|
|
161
189
|
|
|
162
190
|
### Verify Identity Keys
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The binary attachment of a send. The intent of a binary send stores it, so
|
|
3
|
+
* a repeat of the send reuses its one upload and its one serialized message.
|
|
4
|
+
*
|
|
5
|
+
* A binary send uploads the file and then sends a serialized attachment
|
|
6
|
+
* message that points to the upload. The intent keeps that message and the
|
|
7
|
+
* digest of the file. A send that repeats a stored `clientMessageId` with the
|
|
8
|
+
* same file sends the stored message again under the stored timestamp, and
|
|
9
|
+
* uploads nothing.
|
|
10
|
+
*
|
|
11
|
+
* The client marks the options of a new binary send with the attachment, and
|
|
12
|
+
* the direct and group intent builders copy the mark into the intent. The mark
|
|
13
|
+
* has a symbol key that no package subpath exports, and the client sets it
|
|
14
|
+
* after it spreads the application's options, so an application cannot set it.
|
|
15
|
+
*/
|
|
16
|
+
import type { StoredOutgoingMessageIntent } from '../local/store/reliability.js';
|
|
17
|
+
/** The key of the binary attachment mark. No package subpath exports it. */
|
|
18
|
+
export declare const SEND_BINARY_ATTACHMENT: unique symbol;
|
|
19
|
+
/** The options of a send, with the mark of its binary attachment. */
|
|
20
|
+
export interface SendBinaryAttachment {
|
|
21
|
+
readonly [SEND_BINARY_ATTACHMENT]?: NonNullable<StoredOutgoingMessageIntent['binaryAttachment']>;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* The `binaryAttachment` field of a new intent: the mark of the options, or
|
|
25
|
+
* no field when the options have no mark.
|
|
26
|
+
*/
|
|
27
|
+
export declare function intentBinaryAttachment(options: object): Pick<StoredOutgoingMessageIntent, 'binaryAttachment'>;
|
|
28
|
+
//# sourceMappingURL=binary-send.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"binary-send.d.ts","sourceRoot":"","sources":["../../client/binary-send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAE9E,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,EAAE,OAAO,MAAuC,CAAC;AAEpF,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,CAAC,sBAAsB,CAAC,CAAC,EAAE,WAAW,CAAC,2BAA2B,CAAC,kBAAkB,CAAC,CAAC,CAAC;CAClG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GACd,IAAI,CAAC,2BAA2B,EAAE,kBAAkB,CAAC,CAGvD"}
|