@mt-tl/server 0.1.0

package/src/dispatch/forwarders/print.ts

@@ -0,0 +1,22 @@
+import { noopLogger, type Logger } from '@mt-tl/tl'
+import type { RpcForwarder, RpcRequest, RpcResponse } from '../rpc-forwarder.js'
+
+/**
+ * Dev fallback forwarder, used when no app is registered: logs the JSON-RPC 2.0
+ * envelope the handler *would* receive (info level), then returns NOT_IMPLEMENTED.
+ * Wire a real app via `createServer(...).register(app)` to get an
+ * {@link InProcessForwarder}.
+ */
+export class PrintForwarder implements RpcForwarder {
+    constructor(private readonly logger: Logger = noopLogger) {}
+
+    async forward(req: RpcRequest): Promise<RpcResponse> {
+        this.logger.info('rpc.print', {
+            id: req.id,
+            method: req.method,
+            params: req.params,
+            context: req.context,
+        })
+        return { error: { code: 501, message: 'NOT_IMPLEMENTED' } }
+    }
+}

package/src/dispatch/rpc-forwarder.ts

@@ -0,0 +1,15 @@
+// The envelope types describe what the engine hands the handler layer.
+export type { RpcContext, RpcRequest, RpcResponse, SessionEffect } from '@mt-tl/tl'
+import type { RpcRequest, RpcResponse } from '@mt-tl/tl'
+
+/**
+ * Bridge from a decoded business TL method to its handler. The framework is
+ * in-process, so there are two implementations:
+ *   - {@link InProcessForwarder} — calls the app's `dispatchRpc` directly (prod
+ *     and tests); what `createServer(...).listen()` wires.
+ *   - `PrintForwarder` — the dev fallback when no app is registered; logs the
+ *     decoded request envelope and returns NOT_IMPLEMENTED.
+ */
+export interface RpcForwarder {
+    forward(req: RpcRequest): Promise<RpcResponse>
+}

package/src/dispatch/types.ts

@@ -0,0 +1,60 @@
+import type { Connection } from '../transport/connection.js'
+import type { TlObject } from '@mt-tl/tl'
+import type { AcceptResult } from '../session/inbound-tracker.js'
+
+/** Per-message context extracted from the encrypted envelope. */
+export interface MessageContext {
+    msgId: bigint
+    seqNo: number
+    sessionId: bigint
+    authKeyId: bigint
+    salt: bigint
+}
+
+export interface SendOptions {
+    /** Notification (msg_id ends in 3), not a direct response. */
+    isNotification?: boolean
+    /** Consumes a seqno slot and gets an odd seqno (default true). */
+    contentRelated?: boolean
+}
+
+/** Sends an encrypted message back to a connected client. */
+export interface Responder {
+    sendEncrypted(conn: Connection, body: TlObject, opts?: SendOptions): void
+}
+
+/**
+ * Reply to a rejected inbound message (the non-`ok` result of
+ * `InboundTracker.accept`): `bad_msg_notification` for a coded violation,
+ * `msg_detailed_info` for a duplicate whose answer is cached, or nothing for a
+ * benign silent drop. Shared by the pipeline (outer envelope) and the dispatcher
+ * (container-inner messages).
+ */
+export function replyToBadAccept(
+    responder: Responder,
+    conn: Connection,
+    result: Exclude<AcceptResult, { ok: true }>,
+    msgId: bigint,
+    seqNo: number,
+): void {
+    if ('code' in result) {
+        responder.sendEncrypted(
+            conn,
+            { _: 'bad_msg_notification', bad_msg_id: msgId, bad_msg_seqno: seqNo, error_code: result.code },
+            { contentRelated: false },
+        )
+    } else if ('detailed' in result) {
+        responder.sendEncrypted(
+            conn,
+            {
+                _: 'msg_detailed_info',
+                msg_id: msgId,
+                answer_msg_id: result.detailed.answerMsgId,
+                bytes: result.detailed.bytes,
+                status: 0,
+            },
+            { contentRelated: false },
+        )
+    }
+    // { drop: true } → no reply.
+}

package/src/gateway.ts

@@ -0,0 +1,214 @@
+import { protocolSchemaDir } from '@mt-tl/tl'
+import { loadSchema } from './tl/registry.js'
+import { TlCodec } from './tl/codec.js'
+import { loadLayeredRegistry } from './tl/layered-registry.js'
+import { loadRsaKeyPair } from './crypto/rsa.js'
+import { createStorage, type Storage } from './storage/index.js'
+import { NonceStore } from './auth/nonce-store.js'
+import { Handshake } from './auth/handshake.js'
+import { SaltService } from './session/salts.js'
+import { Dispatcher } from './dispatch/dispatcher.js'
+import { PrintForwarder } from './dispatch/forwarders/print.js'
+import type { RpcForwarder } from './dispatch/rpc-forwarder.js'
+import { MessagePipeline } from './server/message-pipeline.js'
+import { MtprotoWsServer } from './transport/ws-server.js'
+import { MtprotoTcpServer } from './transport/tcp-server.js'
+import { Connection } from './transport/connection.js'
+import { ConnectionRegistry } from './transport/connection-registry.js'
+import { NodePresenceBinder, NoopPresenceBinder, type PresenceBinder } from './updates/presence-binder.js'
+import { PushService } from './updates/push.js'
+import type { Presence } from './updates/presence.js'
+import type { UpdateBus } from './updates/update-bus.js'
+import type { UpdateLog } from './core/updates.js'
+import type { MTProtoConfig } from './config.js'
+import { createLogger, type Logger } from '@mt-tl/tl'
+import type { MigrationRegistry } from '@mt-tl/tl'
+import type { KeyObject } from 'node:crypto'
+
+export interface Gateway {
+    /** Present when `config.wsPort` is set. */
+    wsServer?: MtprotoWsServer
+    /** Present when `config.tcpPort` is set. */
+    tcpServer?: MtprotoTcpServer
+    pipeline: MessagePipeline
+    storage: Storage
+    registry: ConnectionRegistry
+    nodeId: string
+    fingerprint: bigint
+    /** Gateway's RSA public key (clients encrypt pq_inner_data with it). */
+    publicKey: KeyObject
+    stats: { constructors: number; methods: number; crcMismatches: number; layers: number[] }
+    /** Start every configured carrier. */
+    listen(): Promise<void>
+    close(): Promise<void>
+}
+
+export interface BuildOptions {
+    forwarder?: RpcForwarder
+    /** Structured logger for observability; defaults to env-configured. */
+    logger?: Logger
+    /** Enables server-push: presence map (Redis in prod, in-memory for tests). */
+    presence?: Presence
+    /** Update bus this node consumes routed deliveries from (Redis pub/sub in prod). */
+    bus?: UpdateBus
+    /** Per-predicate migration ladders (input up / output down). */
+    migrations?: MigrationRegistry
+    /** Durable pts log read by the engine to answer getState/getDifference when managed. */
+    updateLog?: UpdateLog
+    /** When true, the engine answers `updates.getState`/`getDifference` from `updateLog`. */
+    managedUpdates?: boolean
+}
+
+/**
+ * Wires the gateway from config: load schema -> codec, RSA key, storage,
+ * handshake, dispatcher, pipeline, and the WS carrier. Returns the assembled
+ * gateway; call `wsServer.listen()` to start accepting clients.
+ */
+export async function buildGateway(config: MTProtoConfig, opts: BuildOptions = {}): Promise<Gateway> {
+    const logger = opts.logger ?? createLogger({ name: config.nodeId })
+
+    // Merge the framework's protocol schema with the app's business schema — the
+    // consumer ships only business `.tl`; the protocol layer lives in @mt-tl/tl.
+    const { registry, constructors, methods, crcMismatches } = loadSchema([
+        protocolSchemaDir,
+        config.schemaDir,
+    ])
+    const layeredAll = loadLayeredRegistry(config.schemaLayersDir)
+    const layered = layeredAll.hasLayers() ? layeredAll : undefined
+    // Decode-union: register every layer's constructor ids so older-layer clients
+    // decode by id (the name index keeps the newest, so encode is unaffected).
+    for (const def of layeredAll.allDefs()) registry.register(def)
+    const codec = new TlCodec(registry, layered)
+    const rsa = loadRsaKeyPair(config.rsaKeyPath)
+    const storage = await createStorage(config.storage)
+    const saltService = new SaltService(storage.salts)
+
+    const nonceStore = new NonceStore()
+    const handshake = new Handshake({
+        codec,
+        rsa,
+        storage,
+        saltService,
+        nonceStore,
+        defaultLayer: config.defaultLayer,
+        logger: logger.child({ scope: 'handshake' }),
+    })
+
+    const forwarder = opts.forwarder ?? new PrintForwarder(logger.child({ scope: 'rpc' }))
+
+    // Presence / server-push wiring (no-op unless a presence map is supplied).
+    const connRegistry = new ConnectionRegistry()
+    const binder: PresenceBinder = opts.presence
+        ? new NodePresenceBinder(config.nodeId, connRegistry, opts.presence)
+        : new NoopPresenceBinder()
+
+    const migrations = opts.migrations
+    const pipeline = new MessagePipeline({
+        codec,
+        storage,
+        handshake,
+        saltService,
+        defaultLayer: config.defaultLayer,
+        binder,
+        disableMsgKeyCheck: config.disableMsgKeyCheck,
+        disableSeqNoCheck: config.disableSeqNoCheck,
+        logger: logger.child({ scope: 'mtproto' }),
+    })
+    pipeline.dispatcher = new Dispatcher({
+        codec,
+        registry,
+        storage,
+        saltService,
+        responder: pipeline,
+        forwarder,
+        binder,
+        migrations,
+        logger: logger.child({ scope: 'rpc' }),
+        disableSeqNoCheck: config.disableSeqNoCheck,
+        updateLog: opts.updateLog,
+        managedUpdates: opts.managedUpdates,
+        allowedApiIds: config.allowedApiIds,
+    })
+
+    // Consume routed updates addressed to this node and push to local sockets.
+    if (opts.bus && opts.presence) {
+        const push = new PushService(
+            connRegistry,
+            pipeline,
+            layered,
+            migrations,
+            logger.child({ scope: 'push' }),
+        )
+        opts.bus.subscribeNode(config.nodeId, msg => {
+            if (msg.authKeyId !== undefined) push.deliverToAuthKey(msg.authKeyId, msg.update)
+            else if (msg.subject !== undefined) push.deliver(msg.subject, msg.update)
+        })
+    }
+
+    // Refresh presence TTL for locally-connected users + auth keys (heartbeat).
+    let heartbeat: ReturnType<typeof setInterval> | undefined
+    if (opts.presence) {
+        const presence = opts.presence
+        heartbeat = setInterval(
+            () => {
+                for (const subject of connRegistry.subjects())
+                    void presence.add(subject, config.nodeId).catch(() => {})
+                for (const authKeyId of connRegistry.authKeys())
+                    void presence.addAuthKey(authKeyId, config.nodeId).catch(() => {})
+            },
+            Math.max(5_000, Math.floor(config.updates.presenceTtlMs / 3)),
+        )
+        if (typeof heartbeat.unref === 'function') heartbeat.unref()
+    }
+
+    const handlers = {
+        onPacket: (packet: Buffer, conn: Connection) => pipeline.handlePacket(packet, conn),
+        onClose: (conn: Connection) => binder.unbind(conn),
+    }
+
+    const wsServer =
+        config.wsPort !== undefined
+            ? new MtprotoWsServer(
+                  {
+                      port: config.wsPort,
+                      defaultLayer: config.defaultLayer,
+                      trustProxy: config.trustProxy,
+                      logger,
+                  },
+                  handlers,
+              )
+            : undefined
+    const tcpServer =
+        config.tcpPort !== undefined
+            ? new MtprotoTcpServer(
+                  {
+                      port: config.tcpPort,
+                      defaultLayer: config.defaultLayer,
+                      trustProxy: config.trustProxy,
+                      logger,
+                  },
+                  handlers,
+              )
+            : undefined
+
+    return {
+        wsServer,
+        tcpServer,
+        pipeline,
+        storage,
+        registry: connRegistry,
+        nodeId: config.nodeId,
+        fingerprint: rsa.fingerprint,
+        publicKey: rsa.publicKey,
+        stats: { constructors, methods, crcMismatches, layers: layeredAll.layerNumbers() },
+        async listen() {
+            await Promise.all([wsServer?.listen(), tcpServer?.listen()])
+        },
+        async close() {
+            if (heartbeat) clearInterval(heartbeat)
+            wsServer?.close()
+            tcpServer?.close()
+            await storage.close()
+        },
+    }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// @mt-tl/server — the consumer-facing framework facade. Install this (plus
+// @mt-tl/tl for codegen) to build an MTProto server: define routes, listen.
+// The protocol engine (transport/crypto/session/dispatch) and the handler layer
+// (registry/dispatch/hooks/context/errors, under ./core) live in this same
+// package; this file re-exports just the consumer surface — not the internal
+// event/job/runner machinery.
+
+export * from './create-server.js' // createServer, definePlugin, MtprotoServer, Plugin, MethodOpts/Handler
+export * from './update-publisher.js' // createUpdatePublisher
+
+// Handler surface (curated from ./core).
+export {
+    // errors → rpc_error
+    AppError,
+    BadRequestError,
+    AuthRequiredError,
+    NotFoundError,
+    FloodWaitError,
+    InternalError,
+    // hooks
+    defineHook,
+    type Hook,
+    // dispatch + registry (for tests / advanced wiring)
+    RpcRegistry,
+    dispatchRpc,
+    type DispatchDeps,
+    // context + typing
+    type HandlerCtx,
+    type RpcMethodSpec,
+    type RpcMethodMap,
+    type RpcModule,
+    type UpdateEmitter,
+} from './core/index.js'
+
+// The system config object the server takes.
+export type { MTProtoConfig } from './lib.js'
+
+// Structured logger (re-exported from @mt-tl/tl) — build one with createLogger
+// and pass it to createServer, or use the same factory in your app code for a
+// unified log style. Handlers get a per-request child via `ctx.log`; the server
+// exposes its root logger as `app.log`. See docs/guide/observability.md.
+export {
+    createLogger,
+    noopLogger,
+    type Logger,
+    type LogLevel,
+    type LoggerOptions,
+    type Fields,
+} from './lib.js'
+
+// Schema-version migration ladders (input `up` / output `down`) — pass via
+// createServer(config, { migrations }). See docs/guide/releasing-a-version.md.
+export { MigrationRegistry, type MigrationRung } from '@mt-tl/tl'

package/src/lib.ts

@@ -0,0 +1,24 @@
+// The protocol ENGINE's internal API (transport/crypto/session/dispatch wiring).
+// Consumers don't import this directly; they use `createServer()` (./create-server),
+// which wraps it. Env-free and side-effect-free: the caller builds an MTProtoConfig.
+export { bootstrap, type BootstrapOptions, type ForwardHandler, type UpdatePublish } from './bootstrap.js'
+export { buildGateway, type Gateway, type BuildOptions } from './gateway.js'
+export { type MTProtoConfig } from './config.js'
+export { InProcessForwarder } from './dispatch/forwarders/in-process.js'
+export {
+    createLogger,
+    noopLogger,
+    type Logger,
+    type LogLevel,
+    type LoggerOptions,
+    type Fields,
+} from '@mt-tl/tl'
+export type { RpcForwarder } from './dispatch/rpc-forwarder.js'
+export type { RpcContext, RpcRequest, RpcResponse, SessionEffect } from '@mt-tl/tl'
+export type { UpdateMessage, NodeDelivery } from './updates/types.js'
+
+// Update-delivery adapters — the Redis pub/sub bus + presence behind the
+// in-process push loop (multi-instance), and the router that fans updates to nodes.
+export { createRedisPresence, type RedisPresenceHandle } from './updates/redis-presence.js'
+export { createRedisUpdateBus, type RedisBusHandle } from './updates/redis-bus.js'
+export { UpdateRouter, type RouterOptions } from './updates/router.js'

package/src/server/message-pipeline.ts

@@ -0,0 +1,256 @@
+import { randomBytes } from 'node:crypto'
+import { noopLogger, type Logger } from '@mt-tl/tl'
+import { TlReader } from '../tl/reader.js'
+import { TlWriter } from '../tl/writer.js'
+import type { TlCodec } from '../tl/codec.js'
+import type { TlObject } from '@mt-tl/tl'
+import type { Connection } from '../transport/connection.js'
+import type { Storage } from '../storage/index.js'
+import type { SaltService } from '../session/salts.js'
+import { Handshake } from '../auth/handshake.js'
+import { Dispatcher } from '../dispatch/dispatcher.js'
+import { replyToBadAccept, type MessageContext, type Responder, type SendOptions } from '../dispatch/types.js'
+import { ensureSession } from '../session/session-manager.js'
+import { messageClass } from '../session/inbound-tracker.js'
+import { igeDecrypt, igeEncrypt } from '../crypto/aes-ige.js'
+import { generateMessageKey, computeMsgKey } from '../crypto/msg-key.js'
+import { toBigIntLE, toBufferLE } from '../util/bytes.js'
+import type { PresenceBinder } from '../updates/presence-binder.js'
+import { NoopPresenceBinder } from '../updates/presence-binder.js'
+
+export interface PipelineDeps {
+    codec: TlCodec
+    storage: Storage
+    handshake: Handshake
+    saltService: SaltService
+    defaultLayer: number
+    /** Presence/registry binder; defaults to a no-op (push disabled). */
+    binder?: PresenceBinder
+    /**
+     * Disable the inbound MTProto 2.0 `msg_key` integrity check.
+     *
+     * ⚠️ INSECURE — leave this `false` (the default). When `false`, every inbound
+     * encrypted message must carry a `msg_key` equal to the 2.0 recompute
+     * `SHA256(authKey[88:120] ‖ plaintext)[8:24]`, which authenticates the
+     * ciphertext (integrity + binding to the auth key). Setting it `true` makes the
+     * gateway accept any ciphertext that merely decrypts to a well-formed message,
+     * dropping that authentication — only enable it as a temporary interop shim for
+     * non-compliant clients (e.g. ones still on the MTProto 1.0 msg_key scheme; see
+     * docs/internals/msgkey-v1-quirk.md).
+     */
+    disableMsgKeyCheck?: boolean
+    /** Disable inbound seqno validation (bad_msg codes 32/34/35); default enforced.
+     *  Interop shim for clients that don't set seqno to spec. */
+    disableSeqNoCheck?: boolean
+    /** Observability sink; defaults to a no-op logger. */
+    logger?: Logger
+}
+
+/**
+ * Central message pipeline. Routes plaintext (handshake) vs encrypted packets,
+ * performs MTProto 2.0 decrypt/encrypt, ensures the session, and hands decoded
+ * payloads to the dispatcher. Implements {@link Responder} so the dispatcher and
+ * session manager can send encrypted replies.
+ */
+export class MessagePipeline implements Responder {
+    /** Set once after construction (the dispatcher needs this pipeline as its Responder). */
+    dispatcher!: Dispatcher
+    private readonly binder: PresenceBinder
+    private readonly log: Logger
+
+    constructor(private readonly deps: PipelineDeps) {
+        this.binder = deps.binder ?? new NoopPresenceBinder()
+        this.log = deps.logger ?? noopLogger
+        // Surface the insecure interop shim ONCE at startup, not per message.
+        if (deps.disableMsgKeyCheck) {
+            this.log.warn('enc.msgkey.disabled', {
+                insecure: true,
+                hint: 'inbound ciphertext integrity not verified; see docs/internals/msgkey-v1-quirk.md',
+            })
+        }
+    }
+
+    async handlePacket(packet: Buffer, conn: Connection): Promise<void> {
+        if (packet.length < 8) {
+            conn.close()
+            return
+        }
+        // Any inbound traffic resets a pending ping_delay_disconnect idle timer.
+        conn.resetDisconnect()
+        const isPlaintext = packet.readUInt32LE(0) === 0 && packet.readUInt32LE(4) === 0
+        if (isPlaintext) return this.handlePlaintext(packet, conn)
+        return this.handleEncrypted(packet, conn)
+    }
+
+    // --- plaintext (handshake) ---------------------------------------------
+
+    private async handlePlaintext(packet: Buffer, conn: Connection): Promise<void> {
+        // [auth_key_id=0 (8)][msg_id (8)][len (4)][body]
+        if (packet.length < 20) return conn.close()
+        const len = packet.readUInt32LE(16)
+        if (len < 4 || packet.length < 20 + len) return conn.close()
+
+        const reader = new TlReader(packet.subarray(20, 20 + len))
+        const id = reader.readUInt32()
+        if (!Handshake.isHandshakeId(id)) return
+
+        const res = await this.deps.handshake.handle(id, reader)
+        if (!res) return
+        if ('raw' in res) {
+            conn.send(res.raw)
+            return
+        }
+        this.sendPlain(conn, res.reply)
+    }
+
+    private sendPlain(conn: Connection, body: TlObject): void {
+        const bodyBuf = this.deps.codec.encode(body)
+        const w = new TlWriter(bodyBuf.length + 24)
+        w.writeLong(0n) // auth_key_id
+        w.writeLong(conn.nextMessageId())
+        w.writeUInt32(bodyBuf.length)
+        w.writeRaw(bodyBuf)
+        conn.send(w.toBuffer())
+    }
+
+    // --- encrypted ----------------------------------------------------------
+
+    private async handleEncrypted(packet: Buffer, conn: Connection): Promise<void> {
+        if (packet.length < 24) return conn.close()
+        const authKeyId = toBigIntLE(packet.subarray(0, 8))
+        const msgKey = packet.subarray(8, 24)
+        const ciphertext = packet.subarray(24)
+        if (ciphertext.length % 16 !== 0 || ciphertext.length === 0) {
+            this.log.debug('enc.badlen', { authKeyId, len: ciphertext.length })
+            return conn.close()
+        }
+
+        const rec = await this.deps.storage.authKeys.getById(authKeyId)
+        this.log.debug('enc.key', { authKeyId, found: !!rec, blocked: rec?.isBlocked })
+        if (!rec || rec.isBlocked) return conn.close()
+
+        const { aesKey, aesIv } = generateMessageKey(rec.key, msgKey, false)
+        const plain = igeDecrypt(ciphertext, aesKey, aesIv)
+
+        // Inbound msg_key integrity (MTProto 2.0): the packet's msg_key must equal
+        // SHA256(authKey[88:120] ‖ plaintext)[8:24]. This authenticates the ciphertext
+        // and binds it to the auth key. Disabling the check (deps.disableMsgKeyCheck)
+        // is insecure and only intended as a temporary interop shim for non-compliant
+        // clients — see docs/internals/msgkey-v1-quirk.md.
+        if (!this.deps.disableMsgKeyCheck) {
+            if (!computeMsgKey(rec.key, plain, false).equals(msgKey)) {
+                // Ciphertext failed integrity/binding — a forged or non-2.0 client.
+                this.log.warn('enc.msgkey.reject', { authKeyId })
+                return conn.close()
+            }
+        }
+
+        const r = new TlReader(plain)
+        const salt = r.readLong()
+        const sessionId = r.readLong()
+        const msgId = r.readLong()
+        const seqNo = r.readUInt32()
+        const len = r.readUInt32()
+        this.log.trace('enc.ok', { authKeyId, len })
+        if (len < 4 || len > plain.length) return conn.close()
+        const payload = r.read(len)
+
+        // Bind auth/session state to the connection.
+        conn.ctx.authKeyId = authKeyId
+        conn.ctx.authKey = rec.key
+        conn.ctx.sessionId = sessionId
+        if (rec.meta?.apiLayer && conn.ctx.apiLayer === this.deps.defaultLayer) {
+            conn.ctx.apiLayer = rec.meta.apiLayer
+        }
+
+        // Server-salt schedule: advertise the current salt and validate the one the
+        // client encrypted with. A wrong/expired salt earns a `bad_server_salt`
+        // carrying the current salt — the client re-sends with it — and we drop this
+        // message. See docs/internals/protocol-compliance.md.
+        const { current, valid } = await this.deps.saltService.resolve(authKeyId, salt)
+        conn.ctx.serverSalt = current
+        if (!valid) {
+            this.log.debug('salt.bad', { authKeyId })
+            this.sendEncrypted(
+                conn,
+                {
+                    _: 'bad_server_salt',
+                    bad_msg_id: msgId,
+                    bad_msg_seqno: seqNo,
+                    error_code: 48,
+                    new_server_salt: current,
+                },
+                { contentRelated: false },
+            )
+            return
+        }
+
+        // Inbound msg_id / seqno validation (https://core.telegram.org/mtproto/description):
+        // a wrong/duplicate/out-of-window msg_id (or bad seqno) earns a
+        // `bad_msg_notification` and the message is dropped (not dispatched, no session
+        // touched). Runs after the salt gate so a salt re-send keeps its original
+        // msg_id. Content-relatedness is read from the payload's constructor id. See
+        // docs/internals/protocol-compliance.md.
+        const seqCheck = !this.deps.disableSeqNoCheck
+        const check = conn.tracker.accept(msgId, seqNo, {
+            ...messageClass(payload),
+            checkSeqNo: seqCheck,
+            checkOrder: seqCheck,
+        })
+        if (!check.ok) {
+            this.log.debug('msg.rejected', { authKeyId, result: check })
+            replyToBadAccept(this, conn, check, msgId, seqNo)
+            return
+        }
+
+        await ensureSession(
+            this.deps.storage,
+            this,
+            conn,
+            { sessionId, authKeyId, firstMsgId: msgId, subject: rec.subject ?? undefined },
+            this.log,
+        )
+
+        // Register presence: by auth key (any connection — enables anonymous push)
+        // and, for already-authorized keys, by subject.
+        this.binder.bindAuthKey(conn, authKeyId.toString())
+        if (conn.ctx.subject !== undefined) this.binder.bind(conn, conn.ctx.subject)
+
+        const ctx: MessageContext = { msgId, seqNo, sessionId, authKeyId, salt }
+        await this.dispatcher.dispatchPayload(payload, ctx, conn)
+    }
+
+    // --- Responder ----------------------------------------------------------
+
+    sendEncrypted(conn: Connection, body: TlObject, opts: SendOptions = {}): void {
+        const authKey = conn.ctx.authKey
+        const authKeyId = conn.ctx.authKeyId
+        if (!authKey || authKeyId === undefined) return
+
+        const bodyBuf = this.deps.codec.encode(body, conn.ctx.apiLayer)
+        const outMsgId = conn.nextMessageId(opts.isNotification)
+        // Cache the answer to a request so a later duplicate of it gets a
+        // `msg_detailed_info` (the request id is the `rpc_result.req_msg_id`).
+        if (body._ === 'rpc_result' && typeof body.req_msg_id === 'bigint') {
+            conn.tracker.recordAnswer(body.req_msg_id, outMsgId, bodyBuf.length)
+        }
+        const w = new TlWriter(bodyBuf.length + 32)
+        w.writeLong(conn.ctx.serverSalt ?? 0n)
+        w.writeLong(conn.ctx.sessionId ?? 0n)
+        w.writeLong(outMsgId)
+        w.writeUInt32(conn.nextSeqNo(opts.contentRelated ?? true))
+        w.writeUInt32(bodyBuf.length)
+        w.writeRaw(bodyBuf)
+        let plain = w.toBuffer()
+
+        // MTProto 2.0 padding: 12..1024 random bytes, total length divisible by 16.
+        const minPad = 12
+        const pad = minPad + ((16 - ((plain.length + minPad) % 16)) % 16)
+        plain = Buffer.concat([plain, randomBytes(pad)])
+
+        const msgKey = computeMsgKey(authKey, plain, true)
+        const { aesKey, aesIv } = generateMessageKey(authKey, msgKey, true)
+        const ciphertext = igeEncrypt(plain, aesKey, aesIv)
+        conn.send(Buffer.concat([toBufferLE(authKeyId, 8), msgKey, ciphertext]))
+    }
+}