@mt-tl/server 0.1.0

package/src/auth/handshake.ts

@@ -0,0 +1,262 @@
+import { randomBytes } from 'node:crypto'
+import { noopLogger, type Logger } from '@mt-tl/tl'
+import type { TlCodec } from '../tl/codec.js'
+import type { TlObject } from '@mt-tl/tl'
+import { TlReader } from '../tl/reader.js'
+import type { Storage } from '../storage/index.js'
+import type { SaltService } from '../session/salts.js'
+import { NonceStore } from './nonce-store.js'
+import { igeEncrypt, igeDecrypt } from '../crypto/aes-ige.js'
+import { sha1, xorBuffers } from '../crypto/hashes.js'
+import { rsaDecryptNoPadding, type RsaKeyPair } from '../crypto/rsa.js'
+import { DH_G, DH_PRIME, DH_PRIME_BIGINT, makePQ, modPow, calculatePadding } from '../crypto/dh.js'
+import { toBigIntBE, toBigIntLE, toBufferBE } from '../util/bytes.js'
+
+// Immutable protocol constructor ids.
+const ID_REQ_PQ = 0x60469778
+const ID_REQ_PQ_MULTI = 0xbe7e8ef1
+const ID_REQ_DH_PARAMS = 0xd712e4be
+const ID_SET_CLIENT_DH_PARAMS = 0xf5045f1f
+
+const ID_P_Q_INNER_DATA = 0x83c95aec
+const ID_P_Q_INNER_DATA_DC = 0xa9f55f95
+const ID_P_Q_INNER_DATA_TEMP = 0x3c6a84d4
+const ID_P_Q_INNER_DATA_TEMP_DC = 0x56fddf88
+const ID_CLIENT_DH_INNER_DATA = 0x6643b654
+
+/** Raw -404 (regenerate key) sent when handshake state is missing/invalid. */
+const ERR_404 = Buffer.from('6cfeffff', 'hex')
+
+export interface HandshakeDeps {
+    codec: TlCodec
+    rsa: RsaKeyPair
+    storage: Storage
+    saltService: SaltService
+    nonceStore: NonceStore
+    defaultLayer: number
+    /** Observability sink; defaults to a no-op logger. */
+    logger?: Logger
+}
+
+export type HandshakeReply = { reply: TlObject } | { raw: Buffer } | null
+
+export class Handshake {
+    private readonly logger: Logger
+
+    constructor(private readonly deps: HandshakeDeps) {
+        this.logger = deps.logger ?? noopLogger
+    }
+
+    static isHandshakeId(id: number): boolean {
+        return (
+            id === ID_REQ_PQ ||
+            id === ID_REQ_PQ_MULTI ||
+            id === ID_REQ_DH_PARAMS ||
+            id === ID_SET_CLIENT_DH_PARAMS
+        )
+    }
+
+    /** `reader` is positioned just after the 4-byte constructor id. */
+    async handle(id: number, reader: TlReader): Promise<HandshakeReply> {
+        try {
+            switch (id) {
+                case ID_REQ_PQ:
+                case ID_REQ_PQ_MULTI:
+                    return this.handleReqPq(reader.readInt128())
+                case ID_REQ_DH_PARAMS:
+                    return this.handleReqDhParams(reader)
+                case ID_SET_CLIENT_DH_PARAMS:
+                    return this.handleSetClientDhParams(reader)
+                default:
+                    return null
+            }
+        } catch (e) {
+            // A malformed/forged handshake step; reply -404 (regenerate key). Client
+            // fault, not server fault → warn, with the step id for correlation.
+            this.logger.warn('handshake.error', { step: id.toString(16), err: e })
+            return { raw: ERR_404 }
+        }
+    }
+
+    private handleReqPq(clientNonce: Buffer): HandshakeReply {
+        const serverNonce = randomBytes(16)
+        const { p, q, pq } = makePQ()
+        this.deps.nonceStore.set(clientNonce.toString('hex'), { clientNonce, serverNonce, p, q, pq })
+
+        const reply: TlObject = {
+            _: 'resPQ',
+            nonce: clientNonce,
+            server_nonce: serverNonce,
+            pq,
+            server_public_key_fingerprints: [this.deps.rsa.fingerprint],
+        }
+        return { reply }
+    }
+
+    private handleReqDhParams(reader: TlReader): HandshakeReply {
+        const nonce = reader.readInt128()
+        const serverNonce = reader.readInt128()
+        reader.readBytes() // p
+        reader.readBytes() // q
+        reader.readLong() // public_key_fingerprint
+        const encryptedData = reader.readBytes()
+
+        const nd = this.deps.nonceStore.get(nonce.toString('hex'))
+        if (!nd) return { raw: ERR_404 }
+
+        // RSA decrypt -> [0x00][sha1(20)][ctor id (4)][p_q_inner_data fields][padding]
+        const data = rsaDecryptNoPadding(this.deps.rsa.privateKey, encryptedData)
+        const inner = readPqInnerData(data.subarray(21))
+        if (!inner) return { raw: ERR_404 }
+
+        nd.newClientNonce = inner.newNonce
+        nd.expiresIn = inner.expiresIn ?? false
+
+        // server_DH_inner_data
+        const a = randomBelow(DH_PRIME_BIGINT)
+        nd.a = a
+        const gA = toBufferBE(modPow(BigInt(DH_G), a, DH_PRIME_BIGINT), 256)
+
+        const innerData: TlObject = {
+            _: 'server_DH_inner_data',
+            nonce,
+            server_nonce: serverNonce,
+            g: DH_G,
+            dh_prime: DH_PRIME,
+            g_a: gA,
+            server_time: Math.floor(Date.now() / 1000),
+        }
+        const innerBytes = this.deps.codec.encode(innerData)
+        const innerHash = sha1(innerBytes)
+        const padLen = calculatePadding(innerHash.length + innerBytes.length, 16)
+        const plainAnswer = Buffer.concat([
+            innerHash,
+            innerBytes,
+            padLen > 0 ? randomBytes(padLen) : Buffer.alloc(0),
+        ])
+
+        const { tmpAesKey, tmpAesIv } = deriveTmpAes(nd.newClientNonce, serverNonce)
+        nd.tmpAesKey = tmpAesKey
+        nd.tmpAesIv = tmpAesIv
+        this.deps.nonceStore.set(nonce.toString('hex'), nd)
+
+        const reply: TlObject = {
+            _: 'server_DH_params_ok',
+            nonce,
+            server_nonce: serverNonce,
+            encrypted_answer: igeEncrypt(plainAnswer, tmpAesKey, tmpAesIv),
+        }
+        return { reply }
+    }
+
+    private async handleSetClientDhParams(reader: TlReader): Promise<HandshakeReply> {
+        const nonce = reader.readInt128()
+        reader.readInt128() // server_nonce
+        const encryptedData = reader.readBytes()
+
+        const nd = this.deps.nonceStore.get(nonce.toString('hex'))
+        if (!nd || !nd.tmpAesKey || !nd.tmpAesIv || !nd.a || !nd.newClientNonce) {
+            return { raw: ERR_404 }
+        }
+
+        const data = igeDecrypt(encryptedData, nd.tmpAesKey, nd.tmpAesIv)
+        // [sha1(20)][ctor id (4)][client_DH_inner_data fields]
+        if (data.readUInt32LE(20) !== ID_CLIENT_DH_INNER_DATA) return { raw: ERR_404 }
+        const gB = readClientDhInner(data.subarray(24))
+
+        const key = toBufferBE(modPow(toBigIntBE(gB), nd.a, DH_PRIME_BIGINT), 256)
+        const keyHash = sha1(key)
+        const keyId = toBigIntLE(keyHash.subarray(-8))
+        // Wire-compat: the FIRST salt keeps its legacy xor(newNonce, serverNonce)
+        // derivation; it just becomes window 0 of the rolling schedule.
+        const serverSalt = toBigIntLE(
+            xorBuffers(nd.newClientNonce.subarray(0, 8), nd.serverNonce.subarray(0, 8)),
+        )
+
+        await this.deps.storage.authKeys.create({
+            id: keyId,
+            key,
+            expiresIn: nd.expiresIn ? true : false,
+            createdAt: new Date(),
+            subject: null,
+            meta: { apiLayer: this.deps.defaultLayer },
+        })
+        await this.deps.saltService.seed(keyId, serverSalt)
+        // A new auth key was negotiated and persisted (an anonymous key until a
+        // handler binds a user to it).
+        this.logger.info('authkey.create', { authKeyId: keyId, temp: !!nd.expiresIn })
+
+        const newNonceHash1 = sha1(
+            Buffer.concat([nd.newClientNonce, Buffer.from([1]), keyHash.subarray(0, 8)]),
+        ).subarray(-16)
+
+        this.deps.nonceStore.delete(nonce.toString('hex'))
+
+        const reply: TlObject = {
+            _: 'dh_gen_ok',
+            nonce,
+            server_nonce: nd.serverNonce,
+            new_nonce_hash1: Buffer.from(newNonceHash1),
+        }
+        return { reply }
+    }
+}
+
+// --- hand-decoders for the binary-bearing inner structures -----------------
+
+interface PqInner {
+    newNonce: Buffer
+    expiresIn?: number
+}
+
+function readPqInnerData(buf: Buffer): PqInner | null {
+    const r = new TlReader(buf)
+    const id = r.readUInt32()
+    if (
+        id !== ID_P_Q_INNER_DATA &&
+        id !== ID_P_Q_INNER_DATA_DC &&
+        id !== ID_P_Q_INNER_DATA_TEMP &&
+        id !== ID_P_Q_INNER_DATA_TEMP_DC
+    ) {
+        return null
+    }
+    r.readBytes() // pq
+    r.readBytes() // p
+    r.readBytes() // q
+    r.readInt128() // nonce
+    r.readInt128() // server_nonce
+    const newNonce = r.readInt256()
+    if (id === ID_P_Q_INNER_DATA_DC || id === ID_P_Q_INNER_DATA_TEMP_DC) r.readInt32() // dc
+    let expiresIn: number | undefined
+    if (id === ID_P_Q_INNER_DATA_TEMP || id === ID_P_Q_INNER_DATA_TEMP_DC) expiresIn = r.readInt32()
+    return { newNonce, expiresIn }
+}
+
+/** Reads client_DH_inner_data fields (after its ctor id) and returns g_b bytes. */
+function readClientDhInner(buf: Buffer): Buffer {
+    const r = new TlReader(buf)
+    r.readInt128() // nonce
+    r.readInt128() // server_nonce
+    r.readLong() // retry_id
+    return r.readBytes() // g_b
+}
+
+// --- crypto helpers ---------------------------------------------------------
+
+function deriveTmpAes(newNonce: Buffer, serverNonce: Buffer): { tmpAesKey: Buffer; tmpAesIv: Buffer } {
+    const nsn = sha1(Buffer.concat([newNonce, serverNonce]))
+    const sns = sha1(Buffer.concat([serverNonce, newNonce]))
+    const nnn = sha1(Buffer.concat([newNonce, newNonce]))
+    return {
+        tmpAesKey: Buffer.concat([nsn, sns.subarray(0, 12)]),
+        tmpAesIv: Buffer.concat([sns.subarray(12, 20), nnn, newNonce.subarray(0, 4)]),
+    }
+}
+
+function randomBelow(limit: bigint): bigint {
+    let a: bigint
+    do {
+        a = toBigIntBE(randomBytes(256))
+    } while (a >= limit || a < 2n)
+    return a
+}

package/src/auth/nonce-store.ts

@@ -0,0 +1,39 @@
+/** In-flight auth-key-exchange state, keyed by the client nonce (hex). */
+export interface NonceData {
+    clientNonce: Buffer
+    serverNonce: Buffer
+    newClientNonce?: Buffer
+    p?: bigint
+    q?: bigint
+    pq?: Buffer
+    /** server DH secret exponent */
+    a?: bigint
+    tmpAesKey?: Buffer
+    tmpAesIv?: Buffer
+    expiresIn?: number | false
+    timer?: NodeJS.Timeout
+}
+
+const TTL_MS = 10 * 60 * 1000 // 10 minutes (Telegram drops stale handshakes)
+
+export class NonceStore {
+    private map = new Map<string, NonceData>()
+
+    set(nonceHex: string, data: NonceData): void {
+        const existing = this.map.get(nonceHex)
+        if (existing?.timer) clearTimeout(existing.timer)
+        data.timer = setTimeout(() => this.map.delete(nonceHex), TTL_MS)
+        if (typeof data.timer.unref === 'function') data.timer.unref()
+        this.map.set(nonceHex, data)
+    }
+
+    get(nonceHex: string): NonceData | undefined {
+        return this.map.get(nonceHex)
+    }
+
+    delete(nonceHex: string): void {
+        const existing = this.map.get(nonceHex)
+        if (existing?.timer) clearTimeout(existing.timer)
+        this.map.delete(nonceHex)
+    }
+}

package/src/bootstrap.ts

@@ -0,0 +1,114 @@
+import { buildGateway, type BuildOptions, type Gateway } from './gateway.js'
+import { InProcessForwarder } from './dispatch/forwarders/in-process.js'
+import { InMemoryUpdateBus, type UpdateBus } from './updates/update-bus.js'
+import { InMemoryPresence, type Presence } from './updates/presence.js'
+import { createRedisPresence } from './updates/redis-presence.js'
+import { createRedisUpdateBus } from './updates/redis-bus.js'
+import { createMongoUpdateLog } from './updates/mongo-update-log.js'
+import { UpdateRouter } from './updates/router.js'
+import { InMemoryUpdateLog, type UpdateLog } from './core/updates.js'
+import { createLogger, type Logger } from '@mt-tl/tl'
+import type { MTProtoConfig } from './config.js'
+import type { RpcRequest, RpcResponse } from './dispatch/rpc-forwarder.js'
+import type { UpdateMessage } from './updates/types.js'
+import type { MigrationRegistry } from '@mt-tl/tl'
+
+/** The app's forward handler — typically `req => dispatchRpc(app.rpc, req, app.deps)`. */
+export type ForwardHandler = (req: RpcRequest) => Promise<RpcResponse>
+
+/** Publishes a server update onto the gateway's push loop (no-op when push is off). */
+export type UpdatePublish = (msg: UpdateMessage) => Promise<void>
+
+export interface BootstrapOptions {
+    config: MTProtoConfig
+    /**
+     * Builds the app's forward handler. Receives a `publish` wired to the
+     * gateway's in-process push loop and the shared {@link UpdateLog} (durable
+     * when `config.updates.managed`) — feed both into the app's update emitter
+     * (`new LoggingUpdateEmitter(updateLog, publish)`) so handler-emitted updates
+     * reach connected clients and, when managed, persist with a pts.
+     */
+    createForward: (publish: UpdatePublish, updateLog: UpdateLog) => ForwardHandler
+    logger?: Logger
+    /** Per-predicate migration ladders (input `up` / output `down`). */
+    migrations?: MigrationRegistry
+}
+
+/**
+ * The in-process-first entrypoint: runs the gateway and an app in ONE process.
+ * The app is reached via an {@link InProcessForwarder} (no broker). When
+ * `config.updates.enabled`, server-push is wired in-process: the app's
+ * `publish` → update bus → {@link UpdateRouter} (presence lookup) → this node →
+ * client. Uses an in-memory bus/presence for a single process, or Redis (pub/sub
+ * bus + presence) when `config.updates.redisUrl` is set (then scale
+ * horizontally). Returns the gateway; call `listen()`.
+ */
+export async function bootstrap(opts: BootstrapOptions): Promise<Gateway> {
+    const logger = opts.logger ?? createLogger({ name: opts.config.nodeId })
+    const buildOpts: BuildOptions = { logger, migrations: opts.migrations }
+    const closers: Array<() => Promise<void>> = []
+    let publish: UpdatePublish = async () => {}
+
+    if (opts.config.updates.enabled) {
+        const presence = await makePresence(opts.config)
+        const bus = await makeBus(opts.config)
+        new UpdateRouter(bus.bus, presence.presence).start()
+        publish = msg => bus.bus.publishUpdate(msg)
+        buildOpts.presence = presence.presence
+        buildOpts.bus = bus.bus
+        closers.push(bus.close, presence.close)
+        logger.info('updates.inprocess', {
+            backend: opts.config.updates.redisUrl ? 'redis' : 'memory',
+        })
+    }
+
+    // Update state (pts log). Durable + engine-answered when `updates.managed`.
+    const updateLog = await makeUpdateLog(opts.config)
+    closers.push(updateLog.close)
+    buildOpts.updateLog = updateLog.log
+    buildOpts.managedUpdates = !!opts.config.updates.managed
+
+    buildOpts.forwarder = new InProcessForwarder(opts.createForward(publish, updateLog.log))
+    const gateway = await buildGateway(opts.config, buildOpts)
+
+    // Extend close() to also tear down the in-process update infra.
+    const closeGateway = gateway.close.bind(gateway)
+    gateway.close = async () => {
+        await closeGateway()
+        for (const close of closers) await close().catch(() => {})
+    }
+    return gateway
+}
+
+/** In-memory for a single process; Redis once `redisUrl` is set (multi-instance). */
+async function makePresence(
+    config: MTProtoConfig,
+): Promise<{ presence: Presence; close: () => Promise<void> }> {
+    const u = config.updates
+    if (!u.redisUrl) return { presence: new InMemoryPresence(), close: async () => {} }
+    return createRedisPresence(u.redisUrl, u.presenceTtlMs)
+}
+
+async function makeBus(config: MTProtoConfig): Promise<{ bus: UpdateBus; close: () => Promise<void> }> {
+    const u = config.updates
+    if (!u.redisUrl) {
+        const bus = new InMemoryUpdateBus()
+        return { bus, close: () => bus.close() }
+    }
+    return createRedisUpdateBus(u.redisUrl)
+}
+
+/**
+ * The pts log behind `ctx.push` and (when `updates.managed`) `updates.getState`/
+ * `getDifference`. Durable on Mongo when managed + `storage.backend: 'mongo'`;
+ * in-memory otherwise (the emitter still uses it to stamp a pts).
+ */
+async function makeUpdateLog(config: MTProtoConfig): Promise<{ log: UpdateLog; close: () => Promise<void> }> {
+    if (config.updates.managed && config.storage.backend === 'mongo') {
+        if (!config.storage.mongoUrl || !config.storage.mongoDb) {
+            throw new Error('updates.managed with mongo storage requires MONGO_URL and MONGO_DB')
+        }
+        return createMongoUpdateLog(config.storage.mongoUrl, config.storage.mongoDb)
+    }
+    return { log: new InMemoryUpdateLog(), close: async () => {} }
+}

package/src/config.ts

@@ -0,0 +1,103 @@
+import type { StorageBackend } from './storage/index.js'
+
+/**
+ * The configuration object you pass to {@link createServer}. The framework reads
+ * **no** environment of its own — your app builds this (its composition root) and
+ * hands it in. Only `nodeId`, `defaultLayer`, `schemaDir`, `schemaLayersDir`,
+ * `storage`, and `updates` are required.
+ *
+ * @example
+ * ```ts
+ * const config: MTProtoConfig = {
+ *   nodeId: 'node-1',
+ *   wsPort: 8081,
+ *   defaultLayer: 204,
+ *   schemaDir,                 // your business .tl
+ *   schemaLayersDir: layersDir,
+ *   rsaKeyPath: process.env.RSA_PRIVATE_KEY_PATH,
+ *   storage: { backend: 'mongo', mongoUrl: process.env.MONGO_URL },
+ *   updates: { enabled: true, redisUrl: process.env.REDIS_URL, presenceTtlMs: 60_000 },
+ * }
+ * ```
+ */
+export interface MTProtoConfig {
+    /** Stable id of this instance, unique per replica — the presence routing key. */
+    nodeId: string
+    /** WebSocket listen port. Omit to disable the WS carrier. */
+    wsPort?: number
+    /** Raw-TCP listen port. Omit to disable the TCP carrier. */
+    tcpPort?: number
+    /** TL layer assumed for a connection until it negotiates one via `invokeWithLayer`. */
+    defaultLayer: number
+    /**
+     * Whitelist of accepted `initConnection.api_id`s. Omit (default) to accept any
+     * id. When set, an `initConnection` carrying an id outside the list is rejected
+     * with `rpc_error` `API_ID_INVALID` (400) and its wrapped query is not run —
+     * so an unregistered app can't reach your handlers.
+     */
+    allowedApiIds?: number[]
+    /** Directory of your business `.tl` schema (the protocol schema is bundled). */
+    schemaDir: string
+    /** Directory of per-layer snapshots (`scheme_N.json`) that drive layered encoding. */
+    schemaLayersDir: string
+    /**
+     * Path to the server's RSA private key (PEM). Clients pin its fingerprint, so a
+     * real client needs the production key here. Omitted → an ephemeral key is
+     * generated (handshake works only for test clients).
+     */
+    rsaKeyPath?: string
+    /**
+     * Disable the inbound MTProto 2.0 `msg_key` integrity check. ⚠️ INSECURE — keep
+     * `false` (the default). Only enable as a temporary interop shim for a
+     * non-compliant client. See docs/internals/msgkey-v1-quirk.md.
+     */
+    disableMsgKeyCheck?: boolean
+    /**
+     * Disable inbound sequence-number validation (`bad_msg_notification` codes
+     * 32/34/35). Default `false` = enforced: content-related messages (RPC queries)
+     * must carry an odd, strictly increasing `seqno` and pure service messages an
+     * even one. Set `true` as an interop shim for a client that does not set `seqno`
+     * to spec — the same escape-hatch pattern as {@link disableMsgKeyCheck}.
+     */
+    disableSeqNoCheck?: boolean
+    /**
+     * Trust an upstream proxy/load balancer for the client address: parse the
+     * PROXY-protocol header (v1/v2) on the raw-TCP carrier, and trust
+     * `X-Forwarded-For` on WebSocket. Default `false` — leave off when clients
+     * connect directly, since both are spoofable by a direct client. When `true`,
+     * the announced IP surfaces as `ctx.request.ip`.
+     */
+    trustProxy?: boolean
+    /** Where auth keys, server salts, and sessions persist. */
+    storage: {
+        /** `'memory'` (single process, dev) or `'mongo'` (shared, multi-replica). */
+        backend: StorageBackend
+        /** Mongo connection string (required when `backend: 'mongo'`). */
+        mongoUrl?: string
+        /** Mongo database name (defaults to the driver's database in the URL). */
+        mongoDb?: string
+    }
+    /** Server-push (updates) delivery. */
+    updates: {
+        /** Master switch for server-push. When `false`, `ctx.push` is a no-op. */
+        enabled: boolean
+        /**
+         * Redis URL for cross-instance presence + the pub/sub update bus. Omit for a
+         * single process (in-memory presence/bus); required to deliver push across
+         * replicas.
+         */
+        redisUrl?: string
+        /** Presence entry TTL in ms; the node refreshes it on a heartbeat. */
+        presenceTtlMs: number
+        /**
+         * Who owns the update state (`pts` + `updates.getState`/`getDifference`).
+         * `false` (default) → your app owns it: handle those methods yourself and
+         * embed `pts` in the updates you push. `true` → the engine owns it: it keeps
+         * a durable per-user pts log (Mongo when `storage.backend: 'mongo'`, else
+         * in-memory) and answers `updates.getState`/`updates.getDifference` itself.
+         * Requires the `updates.*` types in your schema. Common-pts only — no qts,
+         * seq, or per-channel pts.
+         */
+        managed?: boolean
+    }
+}

package/src/core/context.ts

@@ -0,0 +1,94 @@
+import { noopLogger, type Logger, type RpcContext, type SessionEffect } from '@mt-tl/tl'
+import type { UpdateEmitter } from './updates.js'
+
+/**
+ * Handler-facing context: the request data plus session effects, server-push,
+ * and a per-request value bag. Business dependencies are NOT here — a handler
+ * (or a plugin) closes over its service (Style A DI), so `ctx` carries only
+ * request-scoped + cross-cutting concerns. Handlers stay thin: call the service,
+ * shape the result, optionally `login()`/`push()`.
+ */
+export interface HandlerCtx {
+    /** Raw request context forwarded by the gateway (sessionId, authKeyId, ip, …). */
+    readonly request: RpcContext
+    /** The bound **subject** — your app's internal user id (opaque string, e.g. a
+     * uuid), shareable across your services. `undefined` if the auth key is
+     * anonymous; on an `auth: true` method it is guaranteed present, so
+     * `ctx.subject!` is safe there. Distinct from any wire `user_id:int` your TL
+     * schema exposes — map between them in your app (see the demo `users` module). */
+    readonly subject: string | undefined
+    /** The TL layer this request came in on (the client's negotiated layer).
+     * Read-only — layer negotiation is the protocol's job. Branch on it when an
+     * old client needs a different response shape. */
+    readonly layer: number
+    /** Per-request logger (a child bound with method/subject) — log with the same
+     * style as the framework so app and engine lines interleave coherently. */
+    readonly log: Logger
+    /** Low-level update emitter behind {@link push}; prefer `ctx.push(subject, update)`. */
+    readonly updates: UpdateEmitter
+    /** Collected session effects (applied by the gateway). */
+    readonly effects: readonly SessionEffect[]
+
+    // ── session effects ──────────────────────────────────────────────────────
+    /** Bind the auth key to a `subject` — your internal user id (device login). */
+    login(subject: string): void
+    /** Unbind the auth key (logout). */
+    logout(): void
+    /** Revoke the auth key entirely. */
+    revoke(): void
+
+    // ── server push ──────────────────────────────────────────────────────────
+    /** Push a TL update to a `subject` (delivered via the update bus to whatever node holds them). */
+    push(subject: string, update: unknown): Promise<void>
+    /**
+     * Push to a specific auth key — including an anonymous (not-logged-in)
+     * connection, e.g. to deliver API to a client before it registers. Pass
+     * `ctx.request.authKeyId` for the current connection. No pts (anonymous
+     * connections have no durable update state).
+     */
+    pushToAuthKey(authKeyId: string, update: unknown): Promise<void>
+
+    // ── per-request value bag (pre-handler → handler) ─────────────────────────
+    /** Stash a value for the handler (e.g. data a pre-handler already fetched). */
+    set(key: string, value: unknown): void
+    /** Read a value stashed earlier in this request. */
+    get<T = unknown>(key: string): T | undefined
+
+    // ── deprecated aliases (use login/logout/revoke) ──────────────────────────
+    /** @deprecated use {@link login} */
+    bindUser(subject: string): void
+    /** @deprecated use {@link logout} */
+    unbindUser(): void
+    /** @deprecated use {@link revoke} */
+    revokeKey(): void
+}
+
+export function createHandlerCtx(
+    request: RpcContext,
+    updates: UpdateEmitter,
+    log: Logger = noopLogger,
+): HandlerCtx {
+    const effects: SessionEffect[] = []
+    const bag = new Map<string, unknown>()
+    const login = (subject: string) => void effects.push({ type: 'bindUser', subject })
+    const logout = () => void effects.push({ type: 'unbindUser' })
+    const revoke = () => void effects.push({ type: 'revokeKey' })
+    return {
+        request,
+        subject: request.subject,
+        layer: request.apiLayer,
+        log,
+        updates,
+        effects,
+        login,
+        logout,
+        revoke,
+        push: (subject, update) => updates.emit(subject, update as never),
+        pushToAuthKey: (authKeyId, update) => updates.emitToAuthKey(authKeyId, update as never),
+        set: (key, value) => void bag.set(key, value),
+        get: <T>(key: string) => bag.get(key) as T | undefined,
+        bindUser: login,
+        unbindUser: logout,
+        revokeKey: revoke,
+    }
+}

package/src/core/errors.ts

@@ -0,0 +1,52 @@
+/**
+ * Business errors. `code`/`message` map straight to the gateway's `rpc_error`
+ * (Telegram-style: 400/401/404/420/500…). Throw these from handlers; anything
+ * else becomes a 500 INTERNAL.
+ */
+export class AppError extends Error {
+    constructor(
+        readonly code: number,
+        message: string,
+    ) {
+        super(message)
+        this.name = new.target.name
+    }
+}
+
+/** Invalid input or a violated precondition → `rpc_error 400`. */
+export class BadRequestError extends AppError {
+    constructor(message = 'BAD_REQUEST') {
+        super(400, message)
+    }
+}
+
+/** Method requires an authorized user but the auth key is anonymous → `rpc_error 401`. */
+export class AuthRequiredError extends AppError {
+    constructor(message = 'AUTH_KEY_UNREGISTERED') {
+        super(401, message)
+    }
+}
+
+/** The requested entity does not exist → `rpc_error 404`. */
+export class NotFoundError extends AppError {
+    constructor(message = 'NOT_FOUND') {
+        super(404, message)
+    }
+}
+
+/**
+ * Rate-limited → `rpc_error 420 FLOOD_WAIT_<seconds>`. Clients read the number
+ * off the message and retry after that many seconds.
+ */
+export class FloodWaitError extends AppError {
+    constructor(seconds: number) {
+        super(420, `FLOOD_WAIT_${seconds}`)
+    }
+}
+
+/** An unexpected server-side failure → `rpc_error 500`. */
+export class InternalError extends AppError {
+    constructor(message = 'INTERNAL') {
+        super(500, message)
+    }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from './errors.js'
+export * from './updates.js'
+export * from './context.js'
+export * from './rpc.js'