meta-sovereign 0.49.15 → 0.49.16

package/js/src/server/background-jobs.js

@@ -78,14 +78,16 @@ export const backgroundJobs = ({ ctx, store, log, later, backups }) => {
   });
   const purge = cachePurgeFor({ store, log, later });
   return {
+    // Returns a promise settled once a backup in flight has finished.
     stopJobs: () => {
-      backup.stopBackups();
+      const backupDone = backup.stopBackups();
       audience.stopAudienceSync();
       purge.stopCachePurge();
       // The other timers and pollers the server started with the port.
       ctx.autoImport?.close();
       ctx.whatsappSignIn?.stop().catch(() => {});
       ctx.stopPulls?.();
+      return backupDone;
     },
   };
 };

package/js/src/server/backup-job.js

@@ -87,5 +87,6 @@ export const backupJobFor = ({ ctx, store, log, later, backups }) => {
       });
     });
   }
+  // Resolves once a backup in flight has finished (and pruned).
   return { stopBackups: () => scheduler?.stop() };
 };

package/js/src/server/index.js

@@ -916,13 +916,13 @@ export const startServer = async ({
         bus?.close();
         ctx.replies.close().catch(() => {});
         ctx.closeAutomations().catch(() => {});
-        ctx.stopJobs();
+        const jobsDone = ctx.stopJobs();
         ctx.chatIndex.close();
         stopAll(telegramAccount, ctx.telegramAccounts, ctx.telegramExtras);
         wsHandle?.close();
         signaling?.close();
         closeFront();
-        server.close(() => resolve());
+        server.close(() => Promise.resolve(jobsDone).then(resolve, resolve));
         for (const socket of sockets) {
           socket.destroy();
         }

package/js/src/server/routes-telegram-contact-extras.js

@@ -0,0 +1,102 @@
+// Contact notes, share-my-contact links, phone links, photos for contacts,
+// suggested birthdays, synced contacts and blocking from Replies (R-Y217):
+// the routes of the POSTS table in routes-telegram.js, each validated
+// strictly before the account is asked.
+//
+// Its routes:
+//   POST /api/telegram/contact-note {chat, note} -> { ok, note } the private
+//                       note on a contact (at most 128 characters, "" clears)
+//   POST /api/telegram/contact-token {} -> { ok, url, expires } the link
+//                       t.me/contact/<token> to share the user's contact
+//   POST /api/telegram/contact-token-open {token} -> { ok, chat, name } the
+//                       person that link names
+//   POST /api/telegram/phone-resolve {phone} -> { ok, found, chat?, name? }
+//                       the person with that number (t.me/+<digits>)
+//   POST /api/telegram/contact-photo {chat, mode, token?} -> { ok, mode }
+//                       mode save (only the user sees it), suggest, or reset
+//                       (the personal photo removed; no token)
+//   POST /api/telegram/birthday-suggest {chat, day, month, year?} -> { ok }
+//   POST /api/telegram/saved-contacts {} -> { ok, count } the imported
+//                       contacts Telegram keeps
+//   POST /api/telegram/saved-contacts-reset {} -> { ok } those deleted
+//   POST /api/telegram/block-from-replies {msgId, deleteMessage?,
+//                       deleteHistory?, reportSpam?} -> { ok } the sender
+//                       of a message of the Replies chat blocked
+
+import { route } from './routes-telegram-admin-extras.js';
+import {
+  MODES,
+  NOTE_MAX,
+  PHONE_DIGITS,
+  TOKEN,
+  USER,
+  validMsgId,
+} from '../sources/telegram-contact-extras.js';
+
+const UPLOAD = /^[a-f0-9]{32}$/;
+const user = (b) => USER.test(String(b.chat ?? ''));
+const flag = (v) => v === undefined || typeof v === 'boolean';
+const always = () => true;
+
+export const CONTACT_EXTRAS_POSTS = {
+  'contact-note': route(
+    'contactNote',
+    'chat and note required',
+    (b) => user(b) && typeof b.note === 'string' && b.note.length <= NOTE_MAX,
+    (b) => ({ chat: String(b.chat), note: b.note })
+  ),
+  'contact-token': route('contactToken', 'unsupported', always, () => ({})),
+  'contact-token-open': route(
+    'contactTokenOpen',
+    'token required',
+    (b) => typeof b.token === 'string' && TOKEN.test(b.token),
+    (b) => ({ token: b.token })
+  ),
+  'phone-resolve': route(
+    'phoneResolve',
+    'phone required',
+    (b) =>
+      typeof b.phone === 'string' &&
+      PHONE_DIGITS.test(b.phone.replace(/^\+/, '')),
+    (b) => ({ phone: b.phone })
+  ),
+  'contact-photo': route(
+    'contactPhoto',
+    'chat, mode and token required',
+    (b) =>
+      user(b) &&
+      MODES.includes(b.mode) &&
+      (b.mode === 'reset'
+        ? b.token === undefined
+        : typeof b.token === 'string' && UPLOAD.test(b.token)),
+    (b) => ({ chat: String(b.chat), mode: b.mode, token: b.token })
+  ),
+  'birthday-suggest': route(
+    'birthdaySuggest',
+    'chat, day and month required',
+    (b) => user(b) && Number.isInteger(b.day) && Number.isInteger(b.month),
+    ({ chat, day, month, year }) => ({ chat: String(chat), day, month, year })
+  ),
+  'saved-contacts': route('savedContacts', 'unsupported', always, () => ({})),
+  'saved-contacts-reset': route(
+    'savedContactsReset',
+    'unsupported',
+    always,
+    () => ({})
+  ),
+  'block-from-replies': route(
+    'blockFromReplies',
+    'msgId required',
+    (b) =>
+      validMsgId(b.msgId) &&
+      flag(b.deleteMessage) &&
+      flag(b.deleteHistory) &&
+      flag(b.reportSpam),
+    ({ msgId, deleteMessage, deleteHistory, reportSpam }) => ({
+      msgId,
+      deleteMessage,
+      deleteHistory,
+      reportSpam,
+    })
+  ),
+};

package/js/src/server/routes-telegram-security-extras.js

@@ -0,0 +1,64 @@
+// More of Privacy and Security (R-Y218): the routes of the POSTS table in
+// routes-telegram.js, each validated strictly before the account is asked.
+// A code in a body is passed on and never kept.
+//
+// Its routes:
+//   POST /api/telegram/login-email-send {email} -> { ok, pattern, length }
+//   POST /api/telegram/login-email-verify {code} -> { ok, email }
+//   POST /api/telegram/recovery-request -> { ok, pattern } a code mailed to
+//                       the recovery email
+//   POST /api/telegram/recovery-confirm {code} -> { ok } the password gone
+//   POST /api/telegram/password-reset -> { ok, result: 'ok' | 'wait' |
+//                       'failed-wait', until }
+//   POST /api/telegram/password-reset-cancel -> { ok }
+//   POST /api/telegram/passkeys -> { ok, passkeys: [{ id, name, created,
+//                       lastUsed }] }
+//   POST /api/telegram/passkey-options -> { ok, options } WebAuthn JSON
+//   POST /api/telegram/passkey-register {id, rawId, clientData,
+//                       attestation} -> { ok, passkey } (base64url strings)
+//   POST /api/telegram/passkey-delete {id} -> { ok }
+//   POST /api/telegram/sign-in-codes -> { ok, codes } fresh codes from 777000
+//   POST /api/telegram/invalidate-codes {codes: ['12345']} -> { ok }
+
+import { route } from './routes-telegram-admin-extras.js';
+
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,255}$/;
+const CODE = /^[0-9A-Za-z]{1,16}$/;
+const str = (v, max) =>
+  typeof v === 'string' && v.length > 0 && v.length <= max;
+const nothing = () => true;
+const code = (b) => CODE.test(String(b.code ?? ''));
+
+export const SECURITY_EXTRAS_POSTS = {
+  'login-email-send': route('loginEmailSend', 'a valid email required', (b) =>
+    EMAIL.test(String(b.email ?? ''))
+  ),
+  'login-email-verify': route('loginEmailVerify', 'the code required', code),
+  'recovery-request': route('recoveryRequest', 'no body', nothing),
+  'recovery-confirm': route('recoveryConfirm', 'the code required', code),
+  'password-reset': route('passwordReset', 'no body', nothing),
+  'password-reset-cancel': route('passwordResetCancel', 'no body', nothing),
+  passkeys: route('passkeys', 'no body', nothing),
+  'passkey-options': route('passkeyOptions', 'no body', nothing),
+  'passkey-register': route(
+    'passkeyRegister',
+    'id, rawId, clientData and attestation required',
+    (b) =>
+      ['id', 'rawId', 'clientData', 'attestation'].every((k) =>
+        str(b[k], 100_000)
+      )
+  ),
+  'passkey-delete': route('passkeyDelete', 'the passkey id required', (b) =>
+    str(b.id, 1024)
+  ),
+  'sign-in-codes': route('signInCodes', 'no body', nothing),
+  'invalidate-codes': route(
+    'invalidateCodes',
+    'one to ten codes required',
+    (b) =>
+      Array.isArray(b.codes) &&
+      b.codes.length > 0 &&
+      b.codes.length <= 10 &&
+      b.codes.every((v) => /^\d{5,6}$/.test(String(v)))
+  ),
+};

package/js/src/server/routes-telegram.js

@@ -243,6 +243,7 @@ import { FOLDER_EDIT_POSTS } from './routes-telegram-folder-edit.js';
 import { CHATLIST_POSTS } from './routes-telegram-chatlists.js';
 import { STICKER_SETTINGS_POSTS } from './routes-telegram-sticker-settings.js';
 import { CHAT_THEME_POSTS } from './routes-telegram-chat-themes.js';
+import { CONTACT_EXTRAS_POSTS } from './routes-telegram-contact-extras.js';
 import { CLOUD_THEME_POSTS } from './routes-telegram-cloud-themes.js';
 import { COMMON_CHATS_POSTS } from './routes-telegram-common-chats.js';
 import { STATS_POSTS } from './routes-telegram-stats.js';
@@ -267,6 +268,7 @@ import { EMOJI_STATUS_POSTS } from './routes-telegram-emoji-status.js';
 import { ROUND_POSTS } from './routes-telegram-round.js';
 import { PRIVACY_POSTS } from './routes-telegram-privacy.js';
 import { SECURITY_POSTS } from './routes-telegram-security.js';
+import { SECURITY_EXTRAS_POSTS } from './routes-telegram-security-extras.js';
 import { SHARE_POSTS } from './routes-telegram-share.js';
 import { INLINE_POSTS } from './routes-telegram-inline.js';
 import { MESSAGE_LINK_POSTS } from './routes-telegram-message-links.js';
@@ -1022,6 +1024,7 @@ const POSTS = {
   ...ADMIN_POSTS,
   ...EPHEMERAL_POSTS,
   ...YEXTRAS_POSTS,
+  ...CONTACT_EXTRAS_POSTS,
   ...GROUP_EXTRAS_POSTS,
   ...INSTANT_VIEW_POSTS,
   ...STICKER_EXTRAS_POSTS,
@@ -1071,6 +1074,7 @@ const POSTS = {
   ...ROUND_POSTS,
   ...PRIVACY_POSTS,
   ...SECURITY_POSTS,
+  ...SECURITY_EXTRAS_POSTS,
   ...SHARE_POSTS,
   ...INLINE_POSTS,
   ...TTL_POSTS,

package/js/src/sources/secret-chat-crypto.js

@@ -0,0 +1,275 @@
+/**
+ * The cryptography of secret chats (R-Y219; learned from Telegram's public
+ * description, https://core.telegram.org/api/end-to-end, and the layer-73
+ * schema credited in ./secret-chat-tl.js; never copied from a GPL client).
+ * Groundwork only: nothing imports this module but the secret-chat session
+ * and the tests, and no route or page uses it. Pure: the random bytes come
+ * in as an argument, so the tests fix them.
+ *
+ * Key exchange: the same Diffie-Hellman steps as a call's (./private-call-dh.js):
+ * the requester sends g_a, the accepter answers g_b, both get
+ * `key = g^(ab) mod p` (256 bytes) and its fingerprint (the low 64 bits of
+ * SHA1(key)). Telegram's checks are in `checkParameters` and `publicInRange`.
+ *
+ * Messages (MTProto 2.0): the payload is the serialised
+ * DecryptedMessageLayer with its length (int32, little endian) in front and
+ * 12..1024 random bytes behind, so that the whole is a multiple of 16:
+ *
+ *   msg_key_large = SHA256(key[88+x .. 88+x+32] + plaintext)
+ *   msg_key       = msg_key_large[8 .. 24]
+ *   sha256_a      = SHA256(msg_key + key[x .. x+36])
+ *   sha256_b      = SHA256(key[40+x .. 40+x+36] + msg_key)
+ *   aes_key       = a[0..8] + b[8..24] + a[24..32]
+ *   aes_iv        = b[0..8] + a[8..24] + b[24..32]
+ *
+ * with x = 0 for what the chat's originator sends and x = 8 for what the
+ * other side sends. The packet is `key_fingerprint (8) + msg_key (16) +
+ * AES-256-IGE(plaintext)`.
+ */
+
+import crypto from 'node:crypto';
+import {
+  bigOf,
+  bytesOf,
+  checkDhConfig,
+  exponentOf,
+  fingerprintOf,
+  publicInRange,
+  publicOf,
+  sharedKey,
+} from './private-call-dh.js';
+
+export const MIN_PADDING = 12;
+export const MAX_PADDING = 1024;
+export const KEY_BYTES = 256;
+
+/** The default random source; tests pass their own. */
+export const systemRandom = {
+  bytes: (n) => crypto.randomBytes(n),
+  int: (max) => crypto.randomInt(max),
+};
+
+const sha256 = (...parts) => {
+  const hash = crypto.createHash('sha256');
+  parts.forEach((p) => hash.update(p));
+  return hash.digest();
+};
+
+const xor16 = (a, b) => {
+  const out = Buffer.alloc(16);
+  for (let i = 0; i < 16; i += 1) {
+    out[i] = a[i] ^ b[i];
+  }
+  return out;
+};
+
+// One block through AES-256 without padding or chaining.
+const blocks = (mode, key) => {
+  const cipher = (
+    mode === 'encrypt' ? crypto.createCipheriv : crypto.createDecipheriv
+  )('aes-256-ecb', key, Buffer.alloc(0));
+  cipher.setAutoPadding(false);
+  return (block) => cipher.update(block);
+};
+
+/** AES-256-IGE (key 32 bytes, iv 32 bytes, data a multiple of 16). */
+export const igeEncrypt = (key, iv, data) => {
+  const run = blocks('encrypt', key);
+  let c = iv.subarray(0, 16);
+  let p = iv.subarray(16, 32);
+  const out = Buffer.alloc(data.length);
+  for (let i = 0; i < data.length; i += 16) {
+    const plain = data.subarray(i, i + 16);
+    const cipher = xor16(run(xor16(plain, c)), p);
+    cipher.copy(out, i);
+    c = cipher;
+    p = plain;
+  }
+  return out;
+};
+
+export const igeDecrypt = (key, iv, data) => {
+  const run = blocks('decrypt', key);
+  let c = iv.subarray(0, 16);
+  let p = iv.subarray(16, 32);
+  const out = Buffer.alloc(data.length);
+  for (let i = 0; i < data.length; i += 16) {
+    const cipher = data.subarray(i, i + 16);
+    const plain = xor16(run(xor16(cipher, p)), c);
+    plain.copy(out, i);
+    c = cipher;
+    p = plain;
+  }
+  return out;
+};
+
+/** msg_key for a plaintext (with its length and padding). */
+export const messageKey = (key, plaintext, x) =>
+  sha256(key.subarray(88 + x, 88 + x + 32), plaintext).subarray(8, 24);
+
+/** The AES key and iv of a packet, from the shared key and msg_key. */
+export const packetKeys = (key, msgKey, x) => {
+  const a = sha256(msgKey, key.subarray(x, x + 36));
+  const b = sha256(key.subarray(40 + x, 40 + x + 36), msgKey);
+  return {
+    aesKey: Buffer.concat([
+      a.subarray(0, 8),
+      b.subarray(8, 24),
+      a.subarray(24, 32),
+    ]),
+    aesIv: Buffer.concat([
+      b.subarray(0, 8),
+      a.subarray(8, 24),
+      b.subarray(24, 32),
+    ]),
+  };
+};
+
+// 12..1024 padding bytes making `4 + length + padding` a multiple of 16.
+const paddingLength = (length, random) => {
+  const least = MIN_PADDING + ((16 - ((4 + length + MIN_PADDING) % 16)) % 16);
+  const spare = Math.floor((MAX_PADDING - least) / 16);
+  return least + 16 * random.int(spare + 1);
+};
+
+/** The plaintext of a packet: length, payload, padding. */
+export const padPayload = (payload, random = systemRandom) => {
+  const head = Buffer.alloc(4);
+  head.writeInt32LE(payload.length);
+  return Buffer.concat([
+    head,
+    payload,
+    random.bytes(paddingLength(payload.length, random)),
+  ]);
+};
+
+const fingerprintBytes = (fingerprint) => {
+  const b = Buffer.alloc(8);
+  b.writeBigInt64LE(BigInt(fingerprint));
+  return b;
+};
+
+/**
+ * The `data` of messages.sendEncrypted for a serialised
+ * DecryptedMessageLayer. `originator`: whether we started the chat.
+ */
+export const encryptPayload = ({
+  key,
+  fingerprint,
+  payload,
+  originator,
+  random = systemRandom,
+}) => {
+  const x = originator ? 0 : 8;
+  const plaintext = padPayload(payload, random);
+  const msgKey = messageKey(key, plaintext, x);
+  const { aesKey, aesIv } = packetKeys(key, msgKey, x);
+  return Buffer.concat([
+    fingerprintBytes(fingerprint),
+    msgKey,
+    igeEncrypt(aesKey, aesIv, plaintext),
+  ]);
+};
+
+/**
+ * The payload of a received packet. `fromOriginator`: whether the chat's
+ * originator sent it. `{ ok: true, payload }`, or `{ ok: false, reason }`
+ * with reason `short`, `fingerprint`, `msg-key` or `length`.
+ */
+export const decryptPayload = ({ key, fingerprint, data, fromOriginator }) => {
+  const packet = Buffer.from(data ?? []);
+  if (packet.length < 8 + 16 + 16 || (packet.length - 24) % 16 !== 0) {
+    return { ok: false, reason: 'short' };
+  }
+  if (!packet.subarray(0, 8).equals(fingerprintBytes(fingerprint))) {
+    return { ok: false, reason: 'fingerprint' };
+  }
+  const x = fromOriginator ? 0 : 8;
+  const msgKey = packet.subarray(8, 24);
+  const { aesKey, aesIv } = packetKeys(key, msgKey, x);
+  const plaintext = igeDecrypt(aesKey, aesIv, packet.subarray(24));
+  const expected = messageKey(key, plaintext, x);
+  if (!crypto.timingSafeEqual(expected, msgKey)) {
+    return { ok: false, reason: 'msg-key' };
+  }
+  const length = plaintext.readInt32LE(0);
+  const padding = plaintext.length - 4 - length;
+  if (length < 0 || padding < MIN_PADDING || padding > MAX_PADDING) {
+    return { ok: false, reason: 'length' };
+  }
+  return { ok: true, payload: plaintext.subarray(4, 4 + length) };
+};
+
+/** Whether messages.getDhConfig's `g` and `p` are sound. */
+export const checkParameters = (config) => checkDhConfig(config);
+
+/** Our side of a new chat: the secret exponent and `g_a`. */
+export const startExchange = (config, serverRandom, local) => {
+  const a = exponentOf(serverRandom, local);
+  return { a, ga: publicOf(config, a) };
+};
+
+/**
+ * The accepting side: from the requester's `g_a`, our `g_b`, the key and
+ * its fingerprint; `{ ok: false, reason }` when `g_a` is out of range.
+ */
+export const acceptExchange = (config, ga, serverRandom, local) => {
+  if (!publicInRange(ga, config.p)) {
+    return { ok: false, reason: 'range' };
+  }
+  const b = exponentOf(serverRandom, local);
+  const key = sharedKey(config, ga, b);
+  return {
+    ok: true,
+    gb: publicOf(config, b),
+    key,
+    fingerprint: fingerprintOf(key),
+  };
+};
+
+/**
+ * The requester's last step, from the accepter's `g_b` (`g_a_or_b`) and the
+ * fingerprint Telegram reports: the key, or why it is refused.
+ */
+export const finishExchange = (config, a, gb, fingerprint) => {
+  if (!publicInRange(gb, config.p)) {
+    return { ok: false, reason: 'range' };
+  }
+  const key = sharedKey(config, gb, a);
+  if (fingerprintOf(key) !== String(fingerprint)) {
+    return { ok: false, reason: 'fingerprint' };
+  }
+  return { ok: true, key, fingerprint: fingerprintOf(key) };
+};
+
+// ---- the key as the two people compare it ---------------------------------
+
+/**
+ * The key as a picture to compare, derived from SHA256(key || g_a): an
+ * 8 x 8 identicon (mirrored, so 32 independent cells, each a colour index
+ * 0..5) and the hash as four lines of hex. A derived value only; the key
+ * itself never leaves the server. Both sides compute the same from the
+ * same key, so a man in the middle shows up as a different picture.
+ */
+export const keyVisual = (key, ga) => {
+  const hash = sha256(Buffer.from(key), Buffer.from(ga ?? []));
+  const cells = [];
+  for (let row = 0; row < 8; row += 1) {
+    const half = [];
+    for (let col = 0; col < 4; col += 1) {
+      const byte = hash[row * 4 + col];
+      half.push(byte % 6);
+    }
+    cells.push([...half, ...[...half].reverse()]);
+  }
+  const hex = hash.toString('hex');
+  const lines = [0, 16, 32, 48].map((at) =>
+    hex
+      .slice(at, at + 16)
+      .replace(/(.{4})/g, '$1 ')
+      .trim()
+  );
+  return { cells, lines };
+};
+
+export { bigOf, bytesOf, fingerprintOf };

package/js/src/sources/secret-chat-session.js

@@ -0,0 +1,178 @@
+/**
+ * One secret chat's cryptographic session: the key, the sequence numbers
+ * and the log of what was sent (R-Y219; learned from
+ * https://core.telegram.org/api/end-to-end/seq_no, never copied). Pure and
+ * immutable: every step returns the next state, a plain JSON object the
+ * server keeps in its secret store (the key is hex in it; it never leaves
+ * the server).
+ *
+ * Sequence numbers. The chat's originator numbers what it sends 1, 3, 5, ...
+ * (`out_seq_no = 2 * sent + 1`) and the other side 0, 2, 4, ...
+ * (`2 * sent`). Every layer carries `in_seq_no`, the `out_seq_no` the sender
+ * expects next from the other side (`2 * received + the other's parity`),
+ * which also tells the receiver what it may forget of its sent log. A
+ * received message whose `out_seq_no` is below the expected one is a
+ * duplicate (dropped); above it, a gap: it is dropped as well and a resend of
+ * the range `expected .. out_seq_no` is asked for (the other side then sends
+ * it again with the same numbers).
+ */
+
+import {
+  decryptPayload,
+  encryptPayload,
+  systemRandom,
+} from './secret-chat-crypto.js';
+import {
+  SECRET_LAYER,
+  decodeLayer,
+  decodeMessage,
+  encodeLayer,
+  encodeMessage,
+} from './secret-chat-tl.js';
+
+const OUTBOX_MAX = 100;
+
+const parityOf = (role) => (role === 'admin' ? 1 : 0);
+const otherParity = (role) => 1 - parityOf(role);
+
+/** A fresh session once the key is agreed. */
+export const createSession = ({ id, accessHash, role, key, fingerprint }) => ({
+  id: String(id),
+  accessHash: String(accessHash),
+  role,
+  keyHex: Buffer.from(key).toString('hex'),
+  fingerprint: String(fingerprint),
+  inCount: 0,
+  outCount: 0,
+  peerLayer: 0,
+  ttl: 0,
+  outbox: [],
+});
+
+/** The out_seq_no the next message gets. */
+export const nextOutSeq = (s) => 2 * s.outCount + parityOf(s.role);
+
+/** The out_seq_no expected from the other side next. */
+export const expectedInSeq = (s) => 2 * s.inCount + otherParity(s.role);
+
+const wrap = (s, { message, outSeqNo }, random) => {
+  const layer = encodeLayer({
+    randomBytes: random.bytes(15 + random.int(16)),
+    layer: SECRET_LAYER,
+    inSeqNo: expectedInSeq(s),
+    outSeqNo,
+    message,
+  });
+  return encryptPayload({
+    key: Buffer.from(s.keyHex, 'hex'),
+    fingerprint: s.fingerprint,
+    payload: layer,
+    originator: s.role === 'admin',
+    random,
+  });
+};
+
+/**
+ * Encrypts `message` (see ./secret-chat-tl.js) as the next one we send:
+ * `{ data, state, outSeqNo }`. The message is kept for a resend.
+ */
+export const seal = (state, message, random = systemRandom) => {
+  const outSeqNo = nextOutSeq(state);
+  const data = wrap(state, { message, outSeqNo }, random);
+  const kept = { seq: outSeqNo, hex: encodeMessage(message).toString('hex') };
+  return {
+    data,
+    outSeqNo,
+    state: {
+      ...state,
+      outCount: state.outCount + 1,
+      outbox: [...state.outbox, kept].slice(-OUTBOX_MAX),
+    },
+  };
+};
+
+/**
+ * The messages with out_seq_no from `start` to `end` (raw numbers, every
+ * second one is ours) sealed again as they were, for the other side's
+ * resend request; one we no longer have goes as a noop, so the numbers
+ * still follow on. Returns the packets.
+ */
+export const resendRange = (state, start, end, random = systemRandom) => {
+  const packets = [];
+  const first = Math.max(start, 0);
+  const last = Math.min(end, nextOutSeq(state) - 2);
+  for (let seq = first; seq <= last && packets.length < OUTBOX_MAX; seq += 1) {
+    if (seq % 2 !== parityOf(state.role)) {
+      continue;
+    }
+    const kept = state.outbox.find((m) => m.seq === seq);
+    const message = kept
+      ? decodeMessage(Buffer.from(kept.hex, 'hex'))
+      : {
+          type: 'service',
+          randomId: BigInt(seq) + (1n << 40n),
+          action: { type: 'noop' },
+        };
+    packets.push({
+      seq,
+      data: wrap(state, { message, outSeqNo: seq }, random),
+    });
+  }
+  return packets;
+};
+
+/**
+ * Decrypts a received packet. One of
+ *   { ok: false, reason }                    refused (see decryptPayload,
+ *                                            plus `malformed` and `seq`)
+ *   { ok: true, duplicate: true }            already seen
+ *   { ok: true, gap: { start, end }, state } a message is missing: ask for
+ *                                            the resend of start..end
+ *   { ok: true, layer, message, state }      a message, in order
+ */
+export const open = (state, data) => {
+  const plain = decryptPayload({
+    key: Buffer.from(state.keyHex, 'hex'),
+    fingerprint: state.fingerprint,
+    data,
+    fromOriginator: state.role !== 'admin',
+  });
+  if (!plain.ok) {
+    return plain;
+  }
+  let layer;
+  try {
+    layer = decodeLayer(plain.payload);
+  } catch {
+    return { ok: false, reason: 'malformed' };
+  }
+  if (layer.outSeqNo % 2 !== otherParity(state.role) || layer.outSeqNo < 0) {
+    return { ok: false, reason: 'seq' };
+  }
+  const expected = expectedInSeq(state);
+  if (layer.outSeqNo < expected) {
+    return { ok: true, duplicate: true };
+  }
+  // What the other side has received of ours need not be kept any more.
+  const settled = {
+    ...state,
+    peerLayer: Math.max(state.peerLayer, layer.layer),
+    outbox: state.outbox.filter((m) => m.seq >= layer.inSeqNo),
+  };
+  if (layer.outSeqNo > expected) {
+    return {
+      ok: true,
+      gap: { start: expected, end: layer.outSeqNo },
+      state: settled,
+    };
+  }
+  return {
+    ok: true,
+    layer,
+    message: layer.message,
+    state: { ...settled, inCount: state.inCount + 1 },
+  };
+};
+
+/** The same session with a new self-destruct timer (seconds, 0: off). */
+export const withTtl = (state, ttl) => ({ ...state, ttl });