@soffits/dsh-matrix-bot 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/inbound.js ADDED
@@ -0,0 +1,150 @@
1
+ /**
2
+ * Turn one incoming Matrix message into a DSH prompt: its text, its media as
3
+ * an attachment (pictures as images, voice messages transcribed), and what it
4
+ * replies to as metadata for the message's `source.envelope`.
5
+ */
6
+ import { mkdir, writeFile } from 'node:fs/promises'
7
+ import { extname, join } from 'node:path'
8
+ import { MAX_FILE_BYTES } from './constants.js'
9
+ import { clip } from './text.js'
10
+ import { transcribe, transcriptNote } from './voice.js'
11
+
12
+ /** Image types the DSH attachment store takes as pictures. */
13
+ const IMAGE_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif'])
14
+ /** Message types that carry media. */
15
+ const MEDIA_TYPES = new Set(['m.image', 'm.file', 'm.audio', 'm.video'])
16
+
17
+ /** @returns the event a message replies to, or undefined. */
18
+ export function replyTargetOf(content) {
19
+ const id = content?.['m.relates_to']?.['m.in_reply_to']?.event_id
20
+ return typeof id === 'string' ? id : undefined
21
+ }
22
+
23
+ /**
24
+ * A message's own text: the body without the quoted fallback older clients
25
+ * put before a reply.
26
+ * @param content - message content.
27
+ */
28
+ export function ownText(content) {
29
+ let body = String(content?.body ?? '')
30
+ if (replyTargetOf(content) !== undefined && body.startsWith('> ')) {
31
+ const lines = body.split('\n')
32
+ let index = 0
33
+ while (index < lines.length && lines[index].startsWith('>')) index += 1
34
+ body = lines.slice(index).join('\n')
35
+ }
36
+ return body.trim()
37
+ }
38
+
39
+ /** @returns whether a message carries media. */
40
+ export function hasMedia(content) {
41
+ return MEDIA_TYPES.has(content?.msgtype)
42
+ }
43
+
44
+ /**
45
+ * What a message replies to, as `envelope.replyTo` (the shape dsh-message-context reads).
46
+ * @param target - the replied-to event, or undefined when it could not be read.
47
+ * @param options - `{ botId, senderId, sentRecord, names }`: the bot's user id,
48
+ * the replying user's id, the send record the target belongs to, and names by user id.
49
+ * @returns `{ from, sentAt, text, details }` (fields only when known), or undefined.
50
+ */
51
+ export function replyInfo(target, { botId, senderId, sentRecord, names = {} } = {}) {
52
+ if (target === undefined) return undefined
53
+ const content = target.content ?? {}
54
+ const details = []
55
+ let text = hasMedia(content) ? undefined : ownText(content)
56
+ if (hasMedia(content)) details.push(`contains ${content.msgtype.slice(2)} "${content.body ?? ''}"`)
57
+ let from
58
+ if (target.sender === botId) {
59
+ from = { role: 'assistant' }
60
+ if (sentRecord !== undefined) {
61
+ details.unshift('posted by the bot on behalf of another sender')
62
+ if (sentRecord.job) from = { kind: 'cron-job', channel: 'cron', id: sentRecord.job, name: sentRecord.job }
63
+ else if (sentRecord.fromSession) from = { kind: 'dsh-session', channel: 'dsh', id: sentRecord.fromSession }
64
+ else if (sentRecord.label) from = { kind: 'external', channel: 'external', id: sentRecord.label, name: sentRecord.label }
65
+ if (typeof sentRecord.text === 'string' && sentRecord.text.length > 0) text = sentRecord.text
66
+ }
67
+ } else if (target.sender === senderId) {
68
+ from = { role: 'sender' }
69
+ } else {
70
+ from = { kind: 'matrix-user', channel: 'matrix', id: target.sender, ...(names[target.sender] ? { name: names[target.sender] } : {}) }
71
+ }
72
+ return {
73
+ from,
74
+ ...(typeof target.origin_server_ts === 'number' ? { sentAt: target.origin_server_ts } : {}),
75
+ ...(text ? { text } : {}),
76
+ ...(details.length > 0 ? { details } : {}),
77
+ }
78
+ }
79
+
80
+ /** @returns a safe file name for a download. */
81
+ function fileNameOf(content, eventId) {
82
+ const given = String(content.filename ?? content.body ?? '').split('/').pop().replace(/[^\p{L}\p{N}._ -]/gu, '_').trim()
83
+ if (given.length > 0 && given.length <= 120) return given
84
+ const extension = extname(given) || ''
85
+ return `${eventId.replace(/[^A-Za-z0-9]/gu, '').slice(0, 24)}${extension}`
86
+ }
87
+
88
+ /**
89
+ * Build the prompt for one message.
90
+ * @param event - the decrypted Matrix event.
91
+ * @param options - `{ download, mediaDir, attachments, voice, signal, warn }`:
92
+ * `download(content)` gives the media bytes; `mediaDir` where they are kept;
93
+ * `attachments` the DSH attachment store; `voice` `{ mode, language, command, ffmpeg, speech }`.
94
+ * @returns `{ text, attachments }`.
95
+ */
96
+ export async function composePrompt(event, options) {
97
+ const { download, mediaDir, attachments: store, voice, signal, warn } = options
98
+ const content = event.content ?? {}
99
+ const lines = []
100
+ const blocks = []
101
+ if (hasMedia(content)) {
102
+ const name = fileNameOf(content, event.event_id)
103
+ const size = Number(content.info?.size ?? 0)
104
+ if (size > MAX_FILE_BYTES) {
105
+ lines.push(`[File "${name}" (${size} bytes) is too large to fetch]`)
106
+ } else {
107
+ const data = await download(content)
108
+ const dir = join(mediaDir, event.event_id.replace(/[^A-Za-z0-9]/gu, '').slice(0, 40))
109
+ await mkdir(dir, { recursive: true, mode: 0o700 })
110
+ const path = join(dir, name)
111
+ await writeFile(path, data, { mode: 0o600 })
112
+ const voiceMessage = content['org.matrix.msc3245.voice'] !== undefined
113
+ if (content.msgtype === 'm.audio' && voice.mode !== 'off') {
114
+ const media = { kind: voiceMessage ? 'voice message' : 'audio file', name, seconds: content.info?.duration > 0 ? Math.round(content.info.duration / 1000) : undefined }
115
+ try {
116
+ const result = await transcribe({ ...voice, path, signal })
117
+ lines.push(transcriptNote(media, { ...result, path }))
118
+ } catch (error) {
119
+ lines.push(transcriptNote(media, { path, error: error?.message ?? String(error) }))
120
+ }
121
+ } else {
122
+ lines.push(`[${content.msgtype === 'm.image' ? 'Picture' : 'File'} "${name}", saved at ${path}]`)
123
+ }
124
+ if (store !== undefined) {
125
+ try {
126
+ const mediaType = String(content.info?.mimetype ?? '').toLowerCase()
127
+ let block
128
+ if (IMAGE_TYPES.has(mediaType)) {
129
+ try {
130
+ block = { type: 'image', attachment: await store.saveImage({ data, mediaType, name }) }
131
+ } catch (error) {
132
+ warn?.(`${name} kept as a file, not an image: ${error?.message ?? error}`)
133
+ }
134
+ }
135
+ block ??= { type: 'file', attachment: await store.saveFile({ data, name }) }
136
+ blocks.push(block)
137
+ } catch (error) {
138
+ warn?.(`${name} not attached: ${error?.message ?? error}`)
139
+ }
140
+ }
141
+ }
142
+ // A caption is sent as the body only when it differs from the file name.
143
+ const caption = typeof content.filename === 'string' && content.body !== content.filename ? String(content.body ?? '').trim() : ''
144
+ if (caption.length > 0) lines.push(caption)
145
+ } else {
146
+ const body = ownText(content)
147
+ if (body.length > 0) lines.push(content.msgtype === 'm.emote' ? `* ${body}` : body)
148
+ }
149
+ return { text: lines.join('\n'), attachments: blocks }
150
+ }
package/src/matrix.js ADDED
@@ -0,0 +1,507 @@
1
+ /**
2
+ * Everything that talks to the homeserver: login, the client with its
3
+ * on-disk sync and crypto stores, encryption setup (cross-signing, secret
4
+ * storage, key backup) and the few calls the bot makes. The rest of the bot
5
+ * sees only the object `connect` returns, so tests can pass a fake.
6
+ */
7
+ import { createRequire } from 'node:module'
8
+ import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
9
+ import { dirname, join } from 'node:path'
10
+ import { LogLevel, LogService, MatrixClient, RustSdkCryptoStorageProvider, SimpleFsStorageProvider } from '@vector-im/matrix-bot-sdk'
11
+
12
+ const require = createRequire(import.meta.url)
13
+ const { BackupDecryptionKey, SecretStorageItems, SecretStorageKey, StoreType } = require('@matrix-org/matrix-sdk-crypto-nodejs')
14
+
15
+ /**
16
+ * Stops in progress by account directory. Process-wide (and kept across
17
+ * reloads of this module), because a reloaded plugin connects again while
18
+ * the old instance is still stopping, and both would open one crypto store.
19
+ */
20
+ const STOPPING = Symbol.for('dsh-matrix-bot.stopping')
21
+ globalThis[STOPPING] ??= new Map()
22
+
23
+ /** Account data name of the key backup's secret. */
24
+ const BACKUP_SECRET = 'm.megolm_backup.v1'
25
+ const BACKUP_ALGORITHM = 'm.megolm_backup.v1.curve25519-aes-sha2'
26
+
27
+ /** @returns the Matrix error code of a failed request, or undefined. */
28
+ export function errcodeOf(error) {
29
+ return error?.errcode ?? error?.body?.errcode
30
+ }
31
+
32
+ /** Longest single wait for a rate limit, and the waits a send tries before it fails. */
33
+ const RATE_LIMIT_MAX_WAIT_MS = 60_000
34
+ const RATE_LIMIT_ATTEMPTS = 8
35
+ /** Wait when a rate limit names no time. */
36
+ const RATE_LIMIT_DEFAULT_MS = 2_000
37
+
38
+ /**
39
+ * Run a request again while the server says it is rate limited (429). The
40
+ * server took nothing then, so the request is not sent twice. Synapse limits
41
+ * messages, edits, reactions and redactions alike, which a streamed answer
42
+ * reaches.
43
+ * @param call - the request.
44
+ * @param options - `{ stopped, sleep }`: `stopped()` ends the retries; `sleep(ms)` waits.
45
+ * @returns the request's result.
46
+ */
47
+ export async function whileRateLimited(call, { stopped = () => false, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
48
+ for (let attempt = 1; ; attempt += 1) {
49
+ try {
50
+ return await call()
51
+ } catch (error) {
52
+ const limited = error?.statusCode === 429 || errcodeOf(error) === 'M_LIMIT_EXCEEDED'
53
+ if (!limited || attempt >= RATE_LIMIT_ATTEMPTS || stopped()) throw error
54
+ const asked = Number(error?.retryAfterMs ?? error?.body?.retry_after_ms)
55
+ await sleep(Math.min(RATE_LIMIT_MAX_WAIT_MS, asked > 0 ? asked : RATE_LIMIT_DEFAULT_MS))
56
+ if (stopped()) throw error
57
+ }
58
+ }
59
+ }
60
+
61
+ /**
62
+ * Read a secret file, trimmed, or undefined when it is missing or empty.
63
+ * @param path - file path.
64
+ */
65
+ export async function readSecret(path) {
66
+ if (!path) return undefined
67
+ try {
68
+ const value = (await readFile(path, 'utf8')).trim()
69
+ return value.length > 0 ? value : undefined
70
+ } catch (error) {
71
+ if (error?.code === 'ENOENT') return undefined
72
+ throw error
73
+ }
74
+ }
75
+
76
+ /** Write a secret file with mode 0600, its directory 0700, atomically. */
77
+ export async function writeSecret(path, value) {
78
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 })
79
+ const temporary = `${path}.${process.pid}.tmp`
80
+ await writeFile(temporary, `${value}\n`, { mode: 0o600 })
81
+ await chmod(temporary, 0o600)
82
+ await rename(temporary, path)
83
+ }
84
+
85
+ /**
86
+ * Log in with a password.
87
+ * @param options - `{ homeserver, userId, password, deviceName, deviceId }`;
88
+ * `deviceId` asks the server to keep using an existing device.
89
+ * @returns `{ userId, deviceId, accessToken }`.
90
+ */
91
+ export async function passwordLogin({ homeserver, userId, password, deviceName, deviceId }) {
92
+ // A redirect would send the password on to wherever it points.
93
+ const response = await fetch(new URL('/_matrix/client/v3/login', homeserver), {
94
+ method: 'POST',
95
+ redirect: 'error',
96
+ headers: { 'content-type': 'application/json' },
97
+ body: JSON.stringify({
98
+ type: 'm.login.password',
99
+ identifier: { type: 'm.id.user', user: userId },
100
+ password,
101
+ initial_device_display_name: deviceName,
102
+ ...(deviceId ? { device_id: deviceId } : {}),
103
+ }),
104
+ })
105
+ const body = await response.json().catch(() => ({}))
106
+ if (!response.ok) throw Object.assign(new Error(`login failed: ${body.errcode ?? response.status} ${body.error ?? ''}`.trim()), { errcode: body.errcode })
107
+ return { userId: body.user_id, deviceId: body.device_id, accessToken: body.access_token }
108
+ }
109
+
110
+ /**
111
+ * The stored login, reused while it belongs to the configured account and
112
+ * server; otherwise a new password login. The account is matched as
113
+ * configured, not as the server spells the user id, since a mismatch would
114
+ * make a new device on every start.
115
+ * @param options - `{ dir, homeserver, userId, passwordFile, deviceName, renew, info }`;
116
+ * `renew` logs in again on the stored device.
117
+ * @returns `{ account, userId, deviceId, accessToken, homeserver }`.
118
+ */
119
+ export async function loadLogin({ dir, homeserver, userId, passwordFile, deviceName, renew, info }) {
120
+ const path = join(dir, 'session.json')
121
+ let stored
122
+ try {
123
+ stored = JSON.parse(await readFile(path, 'utf8'))
124
+ } catch {
125
+ stored = undefined
126
+ }
127
+ const same = stored?.homeserver === homeserver && stored?.account === userId && typeof stored?.accessToken === 'string'
128
+ if (same && !renew) return stored
129
+ const password = await readSecret(passwordFile)
130
+ if (password === undefined) throw new Error(`no password in passwordFile (${passwordFile || 'not set'})`)
131
+ const login = await passwordLogin({ homeserver, userId, password, deviceName, deviceId: same ? stored.deviceId : undefined })
132
+ const record = { homeserver, account: userId, ...login }
133
+ await writeSecret(path, JSON.stringify(record, null, 2))
134
+ info(`logged in as ${record.userId} on device ${record.deviceId}`)
135
+ return record
136
+ }
137
+
138
+ /**
139
+ * Route the SDK's log through ours, warnings and errors only. The SDK logs
140
+ * every failed request; a missing state event or account data entry is an
141
+ * answer the caller expects (it reads them to find out), so those stay out.
142
+ */
143
+ function quietSdk(warn) {
144
+ const line = (module, parts) => {
145
+ if (parts.some((part) => errcodeOf(part) === 'M_NOT_FOUND')) return
146
+ warn(`sdk ${module}: ${parts.map(describe).join(' ')}`)
147
+ }
148
+ LogService.setLevel(LogLevel.WARN)
149
+ LogService.setLogger({
150
+ trace() {},
151
+ debug() {},
152
+ info() {},
153
+ warn: (module, ...parts) => line(module, parts),
154
+ error: (module, ...parts) => line(module, parts),
155
+ })
156
+ }
157
+
158
+ function describe(part) {
159
+ if (part instanceof Error) return part.message
160
+ if (typeof part === 'string') return part
161
+ return part?.message ?? part?.errcode ?? String(part)
162
+ }
163
+
164
+ /**
165
+ * Set up the account's cross-signing, secret storage and key backup, or join
166
+ * this device to the ones the account has.
167
+ * @param client - started client with crypto.
168
+ * @param options - `{ recoveryKeyFile, info, warn }`.
169
+ * @returns `{ verified, backup }`.
170
+ */
171
+ export async function bootstrapEncryption(client, { recoveryKeyFile, info, warn }) {
172
+ const crypto = client.crypto
173
+ const machine = crypto.engine.machine
174
+ const userId = await client.getUserId()
175
+ const local = await machine.crossSigningStatus()
176
+ let recoveryKey = await readSecret(recoveryKeyFile)
177
+ if (!(local.hasMaster && local.hasSelfSigning && local.hasUserSigning)) {
178
+ const query = await client.doRequest('POST', '/_matrix/client/v3/keys/query', null, { device_keys: { [userId]: [] } })
179
+ if (query?.master_keys?.[userId] === undefined) {
180
+ if (recoveryKey !== undefined && await openSecretStorage(client, recoveryKey).catch(() => undefined) === undefined) {
181
+ // Overwriting it would lose the key for good; it may be another account's.
182
+ warn(`encryption not set up: ${recoveryKeyFile} holds a recovery key that does not open this account's secret storage; move that file away or point recoveryKeyFile elsewhere`)
183
+ return { verified: false, backup: false }
184
+ }
185
+ if (recoveryKey === undefined) {
186
+ // A new identity: the recovery key is on disk before anything uses it.
187
+ const key = SecretStorageKey.createRandomKey()
188
+ recoveryKey = key.toBase58()
189
+ await writeSecret(recoveryKeyFile, recoveryKey)
190
+ await client.setAccountData(key.eventType(), JSON.parse(key.accountDataContent()))
191
+ await client.setAccountData('m.secret_storage.default_key', { key: key.keyId() })
192
+ }
193
+ await crypto.createIdentity(recoveryKey)
194
+ info(`created the account's cross-signing keys; recovery key written to ${recoveryKeyFile}`)
195
+ } else if (recoveryKey === undefined) {
196
+ warn(`this device is not verified: the account has cross-signing keys and ${recoveryKeyFile} holds no recovery key`)
197
+ return { verified: false, backup: false }
198
+ } else {
199
+ await importIdentity(client, recoveryKey)
200
+ info('verified this device with the recovery key')
201
+ }
202
+ }
203
+ return { verified: true, backup: await ensureBackup(client, recoveryKey, warn) }
204
+ }
205
+
206
+ /**
207
+ * Take the account's cross-signing keys from secret storage and sign this
208
+ * device with them. The SDK's own version holds a native device object that,
209
+ * still alive at exit, makes the crypto library abort the process.
210
+ */
211
+ async function importIdentity(client, recoveryKey) {
212
+ const engine = client.crypto.engine
213
+ const machine = engine.machine
214
+ await engine.processOutgoingRequests([machine.queryKeysForUsers([machine.userId])])
215
+ const storage = await openSecretStorage(client, recoveryKey)
216
+ if (storage === undefined) throw new Error('the account has no default secret storage key')
217
+ const secret = async (name) => JSON.stringify(await client.getAccountData(name))
218
+ const items = new SecretStorageItems({
219
+ masterKey: await secret('m.cross_signing.master'),
220
+ userSigningKey: await secret('m.cross_signing.user_signing'),
221
+ selfSigningKey: await secret('m.cross_signing.self_signing'),
222
+ })
223
+ await engine.processOutgoingRequests([await machine.importSecretsFromSecretStorage(storage, items)])
224
+ }
225
+
226
+ /** @returns the default secret storage key opened with the recovery key, or undefined. */
227
+ async function openSecretStorage(client, recoveryKey) {
228
+ if (recoveryKey === undefined) return undefined
229
+ const { key: keyId } = await client.getSafeAccountData('m.secret_storage.default_key', {})
230
+ if (typeof keyId !== 'string') return undefined
231
+ const name = `m.secret_storage.key.${keyId}`
232
+ const content = await client.getSafeAccountData(name, undefined)
233
+ if (content === undefined) return undefined
234
+ return SecretStorageKey.fromAccountData(recoveryKey, name, JSON.stringify(content))
235
+ }
236
+
237
+ /**
238
+ * Back up room keys to the server: use the account's backup, or create one
239
+ * whose key goes into secret storage.
240
+ * @returns true when backups run.
241
+ */
242
+ async function ensureBackup(client, recoveryKey, warn) {
243
+ const storage = await openSecretStorage(client, recoveryKey)
244
+ let backup = await client.getKeyBackupVersion()
245
+ if (backup === null || backup === undefined) {
246
+ if (storage === undefined) {
247
+ warn('no key backup: secret storage cannot be opened')
248
+ return false
249
+ }
250
+ const key = BackupDecryptionKey.createRandomKey()
251
+ const authData = { public_key: key.megolmV1PublicKey.publicKeyBase64 }
252
+ authData.signatures = await client.crypto.sign(authData)
253
+ const { version } = await client.doRequest('POST', '/_matrix/client/v3/room_keys/version', null, { algorithm: BACKUP_ALGORITHM, auth_data: authData })
254
+ await client.setAccountData(BACKUP_SECRET, JSON.parse(storage.encrypt(key.toBase64(), BACKUP_SECRET)))
255
+ await client.crypto.engine.machine.saveBackupDecryptionKey(key, version)
256
+ backup = await client.getKeyBackupVersion()
257
+ }
258
+ if (backup?.algorithm !== BACKUP_ALGORITHM) {
259
+ warn(`key backup ${backup?.version} uses ${backup?.algorithm}, which this bot cannot write`)
260
+ return false
261
+ }
262
+ await client.enableKeyBackup(backup)
263
+ return true
264
+ }
265
+
266
+ /**
267
+ * Count the calls running in a crypto machine, so it can be closed when none
268
+ * does. After `drain` starts, new calls fail at once.
269
+ * @param machine - the SDK's `OlmMachine`.
270
+ * @returns `{ drain }`: resolves when no call runs any more.
271
+ */
272
+ export function trackCalls(machine) {
273
+ let running = 0
274
+ let draining = false
275
+ const idle = []
276
+ const proto = Object.getPrototypeOf(machine)
277
+ for (const name of Object.getOwnPropertyNames(proto)) {
278
+ const original = Object.getOwnPropertyDescriptor(proto, name)?.value
279
+ if (name === 'constructor' || name === 'close' || typeof original !== 'function') continue
280
+ Object.defineProperty(machine, name, {
281
+ configurable: true,
282
+ writable: true,
283
+ value(...args) {
284
+ if (draining) throw new Error('the crypto store is closing')
285
+ const result = original.apply(machine, args)
286
+ if (typeof result?.then !== 'function') return result
287
+ running += 1
288
+ return Promise.resolve(result).finally(() => {
289
+ running -= 1
290
+ if (running === 0) for (const resolve of idle.splice(0)) resolve()
291
+ })
292
+ },
293
+ })
294
+ }
295
+ return {
296
+ async drain() {
297
+ draining = true
298
+ while (running > 0) await new Promise((resolve) => idle.push(resolve))
299
+ },
300
+ }
301
+ }
302
+
303
+ /**
304
+ * Connect to the homeserver.
305
+ * @param options - `{ dir, homeserver, userId, passwordFile, deviceName, recoveryKeyFile, info, warn }`.
306
+ * @returns the connection; call `start(handlers)` to begin syncing.
307
+ */
308
+ export async function connect(options) {
309
+ const { dir, homeserver, info, warn } = options
310
+ await globalThis[STOPPING].get(dir)
311
+ quietSdk(warn)
312
+ await mkdir(dir, { recursive: true, mode: 0o700 })
313
+ await chmod(dir, 0o700)
314
+ let login = await loadLogin({ ...options, renew: false })
315
+ const build = () => new MatrixClient(
316
+ homeserver,
317
+ login.accessToken,
318
+ new SimpleFsStorageProvider(join(dir, 'sync.json')),
319
+ new RustSdkCryptoStorageProvider(join(dir, 'crypto'), StoreType.Sqlite),
320
+ )
321
+ let client = build()
322
+ try {
323
+ await client.getWhoAmI()
324
+ } catch (error) {
325
+ if (errcodeOf(error) !== 'M_UNKNOWN_TOKEN') throw error
326
+ warn('the stored login stopped working; logging in again on the same device')
327
+ login = await loadLogin({ ...options, renew: true })
328
+ client = build()
329
+ }
330
+ return wrapClient(client, login, options)
331
+ }
332
+
333
+ /**
334
+ * The bot's view of a started client.
335
+ * @param client - bot-sdk client.
336
+ * @param login - `{ userId, deviceId, accessToken, homeserver }`.
337
+ * @param options - connect options.
338
+ */
339
+ function wrapClient(client, login, { dir, recoveryKeyFile, info, warn }) {
340
+ let encryption = { verified: false, backup: false }
341
+ const encrypted = new Map()
342
+ // The SDK's stop only ends the sync loop after the request in flight, and
343
+ // would still process its answer. A stopping client processes nothing and
344
+ // saves no sync token, so the next run gets those events again. The crypto
345
+ // store is closed only when no call into it runs: closing it under a
346
+ // running call corrupts memory, and one dropped by the garbage collector or
347
+ // at exit, outside the library's runtime, aborts the process.
348
+ let stopping
349
+ let processing = Promise.resolve()
350
+ let calls
351
+ client.persistTokenAfterSync = true
352
+ client.once('crypto.ready', () => { calls = trackCalls(client.crypto.engine.machine) })
353
+ let closed = false
354
+ const close = () => {
355
+ if (closed) return
356
+ closed = true
357
+ process.off('exit', close)
358
+ client.crypto?.engine?.machine?.close?.()
359
+ }
360
+ process.on('exit', close)
361
+ const processSync = client.processSync.bind(client)
362
+ client.processSync = (raw, emitFn) => {
363
+ if (stopping !== undefined) return Promise.reject(new Error('stopping'))
364
+ processing = processSync(raw, emitFn)
365
+ return processing
366
+ }
367
+
368
+ const limits = { stopped: () => stopping !== undefined }
369
+
370
+ async function isEncrypted(roomId) {
371
+ if (!encrypted.has(roomId)) encrypted.set(roomId, await client.crypto.isRoomEncrypted(roomId))
372
+ return encrypted.get(roomId)
373
+ }
374
+
375
+ return {
376
+ userId: login.userId,
377
+ deviceId: login.deviceId,
378
+ /** @returns `{ verified, backup }` of this device. */
379
+ encryption: () => ({ ...encryption }),
380
+
381
+ /**
382
+ * Start syncing and set up encryption.
383
+ * @param handlers - `{ onEvent(roomId, event), onInvite(roomId, event), onLeave(roomId, event) }`;
384
+ * `onEvent` gets every timeline event, decrypted when it can be.
385
+ */
386
+ async start({ onEvent, onInvite, onLeave }) {
387
+ client.on('room.event', (roomId, event) => onEvent(roomId, event))
388
+ client.on('room.invite', (roomId, event) => onInvite(roomId, event))
389
+ client.on('room.leave', (roomId, event) => onLeave(roomId, event))
390
+ client.on('room.failed_decryption', (roomId, event, error) => warn(`could not decrypt ${event?.event_id} in ${roomId}: ${describe(error)}`))
391
+ await client.start()
392
+ try {
393
+ encryption = await bootstrapEncryption(client, { recoveryKeyFile, info, warn })
394
+ } catch (error) {
395
+ warn(`encryption setup failed: ${describe(error)}`)
396
+ }
397
+ },
398
+ /** Stop syncing; resolves once the client is idle and its crypto store closed. */
399
+ stop() {
400
+ if (stopping !== undefined) return stopping
401
+ stopping = (async () => {
402
+ client.stop()
403
+ await Promise.allSettled([processing, client.crypto?.engine?.keyBackupWaiter])
404
+ await calls?.drain()
405
+ close()
406
+ })()
407
+ const registry = globalThis[STOPPING]
408
+ const done = stopping.finally(() => { if (registry.get(dir) === done) registry.delete(dir) })
409
+ registry.set(dir, done)
410
+ return stopping
411
+ },
412
+
413
+ async sendEvent(roomId, type, content) {
414
+ return whileRateLimited(() => client.sendEvent(roomId, type, content), limits)
415
+ },
416
+ async sendState(roomId, type, stateKey, content) {
417
+ return whileRateLimited(() => client.sendStateEvent(roomId, type, stateKey, content), limits)
418
+ },
419
+ /** @returns a state event's content, or undefined when the room has none. */
420
+ async getState(roomId, type, stateKey = '') {
421
+ try {
422
+ return await client.getRoomStateEvent(roomId, type, stateKey)
423
+ } catch (error) {
424
+ if (errcodeOf(error) === 'M_NOT_FOUND') return undefined
425
+ throw error
426
+ }
427
+ },
428
+ /** @returns every state event of a room. */
429
+ async roomState(roomId) {
430
+ return client.getRoomState(roomId)
431
+ },
432
+ /** @returns one event, decrypted when it can be. */
433
+ async getEvent(roomId, eventId) {
434
+ const event = await client.getEvent(roomId, eventId)
435
+ return event?.raw ?? event
436
+ },
437
+ async redact(roomId, eventId) {
438
+ return whileRateLimited(() => client.redactEvent(roomId, eventId), limits)
439
+ },
440
+ async setTyping(roomId, typing, timeoutMs) {
441
+ return client.setTyping(roomId, typing, timeoutMs)
442
+ },
443
+ async readReceipt(roomId, eventId) {
444
+ return client.sendReadReceipt(roomId, eventId)
445
+ },
446
+ async createRoom(options) {
447
+ return client.createRoom(options)
448
+ },
449
+ async join(roomId, via = []) {
450
+ return client.joinRoom(roomId, via)
451
+ },
452
+ async leave(roomId) {
453
+ encrypted.delete(roomId)
454
+ return client.leaveRoom(roomId)
455
+ },
456
+ async invite(roomId, userId) {
457
+ return client.inviteUser(userId, roomId)
458
+ },
459
+ /** @returns `{ userId, membership }` for everyone with a membership in the room. */
460
+ async members(roomId) {
461
+ const events = await client.getRoomMembers(roomId)
462
+ return events.map((event) => ({ userId: event.membershipFor, membership: event.effectiveMembership }))
463
+ },
464
+ async joinedRooms() {
465
+ return client.getJoinedRooms()
466
+ },
467
+ /**
468
+ * Upload a file for a room: encrypted when the room is.
469
+ * @returns `{ url }` for a plain upload or `{ file }` for an encrypted one.
470
+ */
471
+ async upload(roomId, buffer, { name, mimetype }) {
472
+ if (await isEncrypted(roomId)) {
473
+ const { buffer: data, file } = await client.crypto.encryptMedia(buffer)
474
+ const url = await client.uploadContent(data, 'application/octet-stream')
475
+ return { file: { ...file, url } }
476
+ }
477
+ return { url: await client.uploadContent(buffer, mimetype, name) }
478
+ },
479
+ /** @returns the bytes of a message's media (`content.file` or `content.url`). */
480
+ async download(content) {
481
+ if (content?.file?.url) return Buffer.from(await client.crypto.decryptMedia(content.file))
482
+ if (typeof content?.url !== 'string') throw new Error('the message has no media')
483
+ const { data } = await client.downloadContent(content.url)
484
+ return Buffer.from(data)
485
+ },
486
+ async setProfile({ displayName, avatar }) {
487
+ if (displayName) {
488
+ const current = await client.getUserProfile(login.userId).catch(() => ({}))
489
+ if (current?.displayname !== displayName) await client.setDisplayName(displayName)
490
+ }
491
+ if (avatar) {
492
+ const data = await readFile(avatar)
493
+ await client.setAvatarUrl(await client.uploadContent(data, mimeOf(avatar), avatar.split('/').pop()))
494
+ }
495
+ },
496
+ async displayName() {
497
+ const profile = await client.getUserProfile(login.userId).catch(() => ({}))
498
+ return profile?.displayname ?? login.userId
499
+ },
500
+ }
501
+ }
502
+
503
+ /** @returns a picture's MIME type from its name. */
504
+ function mimeOf(path) {
505
+ const extension = path.split('.').pop().toLowerCase()
506
+ return { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml' }[extension] ?? 'application/octet-stream'
507
+ }