@mt-tl/server 0.1.0

package/src/storage/mongo.ts

@@ -0,0 +1,215 @@
+import { MongoClient, Binary, type Db, type Collection, type AnyBulkWriteOperation } from 'mongodb'
+import type {
+    AuthKeyMeta,
+    AuthKeyRecord,
+    AuthKeyRepo,
+    SaltRepo,
+    SaltScheduleEntry,
+    SessionRecord,
+    SessionRepo,
+    Storage,
+} from './types.js'
+
+/**
+ * MongoDB-backed storage. Uses the gateway's own collections (auth keys are not
+ * shared byte-for-byte with the legacy server's encoding — that's a migration
+ * concern, out of Phase-1 scope). bigints are stored as decimal strings.
+ */
+
+interface AuthKeyDoc {
+    _id: string
+    key: Binary
+    expiresIn: boolean
+    createdAt: Date
+    subject: string | null
+    isBlocked?: boolean
+    meta?: AuthKeyRecord['meta']
+}
+interface SaltDoc {
+    /** `${authKeyId}:${validSince}` — one document per scheduled window. */
+    _id: string
+    authKeyId: string
+    salt: string
+    validSince: number
+    validUntil: number
+}
+interface SessionDoc {
+    _id: string
+    authKeyId: string
+    uniqueId: string
+    apiLayer: number
+    subject?: string
+    lastActivity: number
+}
+
+function toBuf(b: Binary): Buffer {
+    return Buffer.from(b.buffer)
+}
+
+class MongoAuthKeyRepo implements AuthKeyRepo {
+    constructor(private readonly col: Collection<AuthKeyDoc>) {}
+    async create(rec: AuthKeyRecord): Promise<void> {
+        await this.col.updateOne(
+            { _id: rec.id.toString() },
+            {
+                $set: {
+                    key: new Binary(rec.key),
+                    expiresIn: rec.expiresIn,
+                    createdAt: rec.createdAt,
+                    subject: rec.subject,
+                    isBlocked: rec.isBlocked ?? false,
+                    meta: rec.meta,
+                },
+            },
+            { upsert: true },
+        )
+    }
+    async getById(id: bigint): Promise<AuthKeyRecord | null> {
+        const doc = await this.col.findOne({ _id: id.toString() })
+        if (!doc) return null
+        return {
+            id,
+            key: toBuf(doc.key),
+            expiresIn: doc.expiresIn,
+            createdAt: doc.createdAt,
+            subject: doc.subject,
+            isBlocked: doc.isBlocked,
+            meta: doc.meta,
+        }
+    }
+    async setBlocked(id: bigint, blocked: boolean): Promise<void> {
+        await this.col.updateOne({ _id: id.toString() }, { $set: { isBlocked: blocked } })
+    }
+    async bindUser(id: bigint, subject: string | null): Promise<void> {
+        await this.col.updateOne({ _id: id.toString() }, { $set: { subject } })
+    }
+    async updateMeta(id: bigint, patch: AuthKeyMeta): Promise<void> {
+        // Set defined fields under dotted `meta.*` paths so we never clobber the
+        // sibling fields (e.g. `meta.apiLayer` set at handshake time).
+        const set: Record<string, unknown> = {}
+        for (const [k, v] of Object.entries(patch)) {
+            if (v !== undefined) set[`meta.${k}`] = v
+        }
+        if (Object.keys(set).length) await this.col.updateOne({ _id: id.toString() }, { $set: set })
+    }
+}
+
+class MongoSaltRepo implements SaltRepo {
+    constructor(private readonly col: Collection<SaltDoc>) {}
+    async append(authKeyId: bigint, entries: SaltScheduleEntry[]): Promise<void> {
+        if (!entries.length) return
+        const key = authKeyId.toString()
+        // $setOnInsert keeps the first writer's salt for a window, so all nodes
+        // that derive the same (deterministic) window converge on one salt.
+        const ops: AnyBulkWriteOperation<SaltDoc>[] = entries.map(e => ({
+            updateOne: {
+                filter: { _id: `${key}:${e.validSince}` },
+                update: {
+                    $setOnInsert: {
+                        authKeyId: key,
+                        salt: e.salt.toString(),
+                        validSince: e.validSince,
+                        validUntil: e.validUntil,
+                    },
+                },
+                upsert: true,
+            },
+        }))
+        await this.col.bulkWrite(ops, { ordered: false })
+    }
+    async list(authKeyId: bigint): Promise<SaltScheduleEntry[]> {
+        const docs = await this.col
+            .find({ authKeyId: authKeyId.toString() })
+            .sort({ validSince: 1 })
+            .toArray()
+        return docs.map(d => ({ salt: BigInt(d.salt), validSince: d.validSince, validUntil: d.validUntil }))
+    }
+    async prune(authKeyId: bigint, before: number): Promise<void> {
+        await this.col.deleteMany({ authKeyId: authKeyId.toString(), validUntil: { $lte: before } })
+    }
+}
+
+class MongoSessionRepo implements SessionRepo {
+    constructor(private readonly col: Collection<SessionDoc>) {}
+    async get(sessionId: bigint): Promise<SessionRecord | null> {
+        const doc = await this.col.findOne({ _id: sessionId.toString() })
+        if (!doc) return null
+        return {
+            sessionId,
+            authKeyId: BigInt(doc.authKeyId),
+            uniqueId: BigInt(doc.uniqueId),
+            apiLayer: doc.apiLayer,
+            subject: doc.subject,
+            lastActivity: doc.lastActivity,
+        }
+    }
+    async save(rec: SessionRecord): Promise<void> {
+        await this.col.updateOne(
+            { _id: rec.sessionId.toString() },
+            {
+                $set: {
+                    authKeyId: rec.authKeyId.toString(),
+                    uniqueId: rec.uniqueId.toString(),
+                    apiLayer: rec.apiLayer,
+                    subject: rec.subject,
+                    lastActivity: rec.lastActivity,
+                },
+            },
+            { upsert: true },
+        )
+    }
+    async update(sessionId: bigint, patch: Partial<SessionRecord>): Promise<void> {
+        const set: Record<string, unknown> = {}
+        if (patch.apiLayer !== undefined) set.apiLayer = patch.apiLayer
+        if (patch.subject !== undefined) set.subject = patch.subject
+        if (patch.lastActivity !== undefined) set.lastActivity = patch.lastActivity
+        if (Object.keys(set).length) await this.col.updateOne({ _id: sessionId.toString() }, { $set: set })
+    }
+    async delete(sessionId: bigint): Promise<void> {
+        await this.col.deleteOne({ _id: sessionId.toString() })
+    }
+    async touch(sessionId: bigint): Promise<boolean> {
+        const res = await this.col.updateOne(
+            { _id: sessionId.toString() },
+            { $set: { lastActivity: Date.now() } },
+        )
+        return res.matchedCount > 0
+    }
+}
+
+export async function createMongoStorage(url: string, dbName: string): Promise<Storage> {
+    const client = new MongoClient(url)
+    await client.connect()
+    const db: Db = client.db(dbName)
+    await ensureIndexes(db)
+    return {
+        authKeys: new MongoAuthKeyRepo(db.collection<AuthKeyDoc>('authKeys')),
+        salts: new MongoSaltRepo(db.collection<SaltDoc>('serverSalts')),
+        sessions: new MongoSessionRepo(db.collection<SessionDoc>('sessions')),
+        async close() {
+            await client.close()
+        },
+    }
+}
+
+/**
+ * Create the secondary indexes the protocol collections rely on. Idempotent
+ * (Mongo no-ops an index that already exists), so it's safe to run on every
+ * startup. `_id`-keyed lookups (get/save/touch by id) need no extra index.
+ */
+async function ensureIndexes(db: Db): Promise<void> {
+    await Promise.all([
+        // serverSalts: list() filters by authKeyId + sorts by validSince; prune()
+        // filters by authKeyId + validUntil.
+        db.collection('serverSalts').createIndex({ authKeyId: 1, validSince: 1 }),
+        db.collection('serverSalts').createIndex({ authKeyId: 1, validUntil: 1 }),
+        // sessions: looked up / aggregated by the key, the user, and recency.
+        db.collection('sessions').createIndex({ authKeyId: 1 }),
+        db.collection('sessions').createIndex({ subject: 1 }),
+        db.collection('sessions').createIndex({ lastActivity: 1 }),
+        // authKeys: "all devices for a user", moderation, and creation-over-time.
+        db.collection('authKeys').createIndex({ subject: 1 }),
+        db.collection('authKeys').createIndex({ isBlocked: 1 }),
+        db.collection('authKeys').createIndex({ createdAt: 1 }),
+    ])
+}

package/src/storage/types.ts

@@ -0,0 +1,92 @@
+/** Persistence contracts for auth keys, server salts and sessions. */
+
+/**
+ * Connection/device metadata for an auth key. An auth key is one device
+ * authorization (one app install), so this — captured from `initConnection` — is
+ * stable per key and lives here rather than being duplicated across the key's
+ * sessions. `apiLayer` is the last layer negotiated via `invokeWithLayer`,
+ * restored for a fresh session before it re-negotiates.
+ */
+export interface AuthKeyMeta {
+    apiLayer?: number
+    /** `initConnection.api_id` — the client app id. */
+    apiId?: number
+    /** `initConnection.device_model`. */
+    deviceModel?: string
+    /** `initConnection.system_version`. */
+    systemVersion?: string
+    /** `initConnection.app_version`. */
+    appVersion?: string
+    /** `initConnection.system_lang_code`. */
+    systemLangCode?: string
+    /** `initConnection.lang_code`. */
+    langCode?: string
+}
+
+export interface AuthKeyRecord {
+    id: bigint
+    key: Buffer
+    expiresIn: boolean
+    createdAt: Date
+    /** The bound subject (your internal user id), or null for an anonymous key. */
+    subject: string | null
+    isBlocked?: boolean
+    meta?: AuthKeyMeta
+}
+
+export interface SessionRecord {
+    sessionId: bigint
+    authKeyId: bigint
+    uniqueId: bigint
+    apiLayer: number
+    subject?: string
+    lastActivity: number
+}
+
+export interface AuthKeyRepo {
+    create(rec: AuthKeyRecord): Promise<void>
+    getById(id: bigint): Promise<AuthKeyRecord | null>
+    setBlocked(id: bigint, blocked: boolean): Promise<void>
+    /** Bind (or clear, with null) the subject authorized on this auth key. */
+    bindUser(id: bigint, subject: string | null): Promise<void>
+    /** Merge `initConnection`-derived device/app fields into the key's meta. */
+    updateMeta(id: bigint, patch: AuthKeyMeta): Promise<void>
+}
+
+/** One scheduled server salt and its validity window (unix seconds). */
+export interface SaltScheduleEntry {
+    salt: bigint
+    /** Inclusive lower bound (unix seconds). */
+    validSince: number
+    /** Exclusive upper bound (unix seconds). */
+    validUntil: number
+}
+
+export interface SaltRepo {
+    /**
+     * Persist salt-schedule entries for an auth key. Inserts only windows not
+     * already present (keyed by `validSince`) and never overwrites an existing
+     * window's salt, so concurrent gateway nodes converge on one salt per window.
+     */
+    append(authKeyId: bigint, entries: SaltScheduleEntry[]): Promise<void>
+    /** Full salt schedule for an auth key, ascending by `validSince`. */
+    list(authKeyId: bigint): Promise<SaltScheduleEntry[]>
+    /** Drop entries that fully expired before `before` (unix seconds). */
+    prune(authKeyId: bigint, before: number): Promise<void>
+}
+
+export interface SessionRepo {
+    get(sessionId: bigint): Promise<SessionRecord | null>
+    save(rec: SessionRecord): Promise<void>
+    update(sessionId: bigint, patch: Partial<SessionRecord>): Promise<void>
+    delete(sessionId: bigint): Promise<void>
+    /** Refresh last-activity; returns true if the session existed. */
+    touch(sessionId: bigint): Promise<boolean>
+}
+
+export interface Storage {
+    authKeys: AuthKeyRepo
+    salts: SaltRepo
+    sessions: SessionRepo
+    close(): Promise<void>
+}

package/src/testkit.ts

@@ -0,0 +1,19 @@
+// @mt-tl/server/testkit — protocol primitives a TEST CLIENT needs (TL codec +
+// the client side of the MTProto 2.0 crypto). NOT part of the consumer surface:
+// servers are built with `createServer` from the package root. This subpath
+// exists so `@mt-tl/testing` can drive a real handshake + encrypted RPC
+// against a gateway without deep-importing internal files. The crypto here is
+// the same code pinned byte-for-byte by `test/crypto.kat.test.ts`.
+
+export { TlReader } from './tl/reader.js'
+export { TlWriter } from './tl/writer.js'
+export { TlCodec } from './tl/codec.js'
+export { loadSchema, type LoadSchemaResult } from './tl/registry.js'
+
+export { igeEncrypt, igeDecrypt } from './crypto/aes-ige.js'
+export { sha1 } from './crypto/hashes.js'
+export { generateMessageKey, computeMsgKey } from './crypto/msg-key.js'
+export { modPow } from './crypto/dh.js'
+export { rsaEncryptNoPadding } from './crypto/rsa.js'
+
+export { toBigIntBE, toBigIntLE, toBufferBE, toBufferLE, xorBuffers } from './util/bytes.js'

package/src/tl/codec.ts

@@ -0,0 +1,292 @@
+import type { TlDef, TlType } from '@mt-tl/tl'
+import type { TlRegistry } from './registry.js'
+import type { LayeredRegistry } from './layered-registry.js'
+import { TlReader, BOOL_TRUE_ID, BOOL_FALSE_ID, VECTOR_ID } from './reader.js'
+import { TlWriter } from './writer.js'
+import type { TlObject, TlValue } from '@mt-tl/tl'
+
+/**
+ * IR-driven (de)serializer for arbitrary TL values. Constructed types are tagged
+ * objects `{ _: name, ...fields }`. Hand-written protocol codecs (registered on
+ * the registry) take precedence for their ids; everything else routes here.
+ *
+ * When a {@link LayeredRegistry} is supplied, `encode(value, layer)` writes each
+ * type with the constructor id/fields valid at the client's layer (decoding
+ * stays global by id). Without a layer, the merged registry is used.
+ */
+export class TlCodec {
+    /** Set transiently during a single `encode(value, layer)` call. */
+    private encodeLayer?: number
+
+    constructor(
+        private readonly registry: TlRegistry,
+        private readonly layered?: LayeredRegistry,
+    ) {}
+
+    encode(value: TlObject, layer?: number): Buffer {
+        this.encodeLayer = this.layered && layer !== undefined ? layer : undefined
+        try {
+            const w = new TlWriter()
+            this.writeObject(w, value)
+            return w.toBuffer()
+        } finally {
+            this.encodeLayer = undefined
+        }
+    }
+
+    decode(buf: Buffer): TlValue {
+        return this.readObject(new TlReader(buf))
+    }
+
+    /** Resolve the def to serialize a name with, honoring the active encode layer. */
+    private defForWrite(name: string): TlDef | undefined {
+        if (this.layered && this.encodeLayer !== undefined) {
+            const layerDef = this.layered.resolve(name, this.encodeLayer)
+            if (layerDef) return layerDef
+        }
+        return this.registry.getByName(name)
+    }
+
+    // --- boxed object (with constructor id) ---------------------------------
+
+    writeObject(w: TlWriter, value: TlValue): void {
+        if (typeof value === 'boolean') {
+            w.writeBool(value)
+            return
+        }
+        if (Array.isArray(value)) {
+            w.writeUInt32(VECTOR_ID)
+            w.writeUInt32(value.length)
+            for (const el of value) this.writeObject(w, el)
+            return
+        }
+        if (value && typeof value === 'object' && '_' in value) {
+            const obj = value as TlObject
+            const codec = this.protocolCodecByName(obj._)
+            if (codec) {
+                codec.write(w, obj)
+                return
+            }
+            const def = this.defForWrite(obj._)
+            if (!def) throw new Error(`Cannot serialize unknown TL type: ${obj._}`)
+            w.writeUInt32(def.idNum)
+            this.writeFields(w, def.params, obj)
+            return
+        }
+        throw new Error(`Cannot serialize value as boxed object: ${String(value)}`)
+    }
+
+    readObject(r: TlReader): TlValue {
+        const id = r.readUInt32()
+        if (id === BOOL_TRUE_ID) return true
+        if (id === BOOL_FALSE_ID) return false
+        if (id === VECTOR_ID) {
+            const count = r.readUInt32()
+            const out: TlValue[] = []
+            for (let i = 0; i < count; i++) out.push(this.readObject(r))
+            return out
+        }
+        const protocolCodec = this.registry.getProtocolCodec(id)
+        if (protocolCodec) return protocolCodec.read(r) as TlValue
+        const def = this.registry.getById(id)
+        if (!def) {
+            throw new Error(`Cannot read unknown TL id 0x${(id >>> 0).toString(16).padStart(8, '0')}`)
+        }
+        const obj: TlObject = { _: def.name }
+        this.readFields(r, def.params, obj)
+        return obj
+    }
+
+    // --- bare constructor (no id) -------------------------------------------
+
+    private writeBare(w: TlWriter, name: string, value: TlValue): void {
+        const def = this.defForWrite(name)
+        if (!def) throw new Error(`Cannot serialize unknown bare type: ${name}`)
+        this.writeFields(w, def.params, (value ?? { _: name }) as TlObject)
+    }
+
+    private readBare(r: TlReader, name: string): TlObject {
+        const def = this.registry.getByName(name)
+        if (!def) throw new Error(`Cannot read unknown bare type: ${name}`)
+        const obj: TlObject = { _: name }
+        this.readFields(r, def.params, obj)
+        return obj
+    }
+
+    // --- fields (with flags handling) ---------------------------------------
+
+    private writeFields(w: TlWriter, params: import('@mt-tl/tl').TlParam[], obj: TlObject): void {
+        const bitmaskFields = collectBitmaskFields(params)
+        const flags: Record<string, number> = {}
+        for (const p of params) {
+            if (p.type.kind !== 'flag') continue
+            const v = obj[p.name]
+            const present = p.type.inner.kind === 'true' ? v === true : v !== undefined && v !== null
+            if (present) flags[p.type.flagsField] = (flags[p.type.flagsField] ?? 0) | (1 << p.type.bit)
+        }
+
+        for (const p of params) {
+            const t = p.type
+            if (bitmaskFields.has(p.name)) {
+                // Bitmask field (`flags:#` or `flags:int`): write the value computed
+                // from which conditional fields are present.
+                w.writeUInt32((flags[p.name] ?? 0) >>> 0)
+            } else if (t.kind === 'flag') {
+                const set = ((flags[t.flagsField] ?? 0) >>> t.bit) & 1
+                if (set && t.inner.kind !== 'true') this.writeType(w, t.inner, obj[p.name])
+            } else {
+                this.writeType(w, t, obj[p.name])
+            }
+        }
+    }
+
+    private readFields(r: TlReader, params: import('@mt-tl/tl').TlParam[], obj: TlObject): void {
+        const bitmaskFields = collectBitmaskFields(params)
+        const flags: Record<string, number> = {}
+        for (const p of params) {
+            const t = p.type
+            if (bitmaskFields.has(p.name)) {
+                const v = r.readUInt32()
+                flags[p.name] = v
+                obj[p.name] = v
+            } else if (t.kind === 'flag') {
+                const set = ((flags[t.flagsField] ?? 0) >>> t.bit) & 1
+                if (set) obj[p.name] = t.inner.kind === 'true' ? true : this.readType(r, t.inner)
+            } else {
+                obj[p.name] = this.readType(r, t)
+            }
+        }
+    }
+
+    // --- single typed value --------------------------------------------------
+
+    private writeType(w: TlWriter, t: TlType, value: TlValue): void {
+        switch (t.kind) {
+            case 'int':
+                w.writeInt32(Number(value ?? 0))
+                return
+            case 'long':
+                w.writeLong(typeof value === 'bigint' ? value : BigInt((value as number | string) ?? 0))
+                return
+            case 'double':
+                w.writeDouble(Number(value ?? 0))
+                return
+            case 'string':
+                // Binary may be supplied for a `string` field (the protocol schema
+                // declares pq/g_a/g_b/encrypted_data as `string`). Preserve bytes
+                // exactly; `string` and `bytes` share the same wire encoding.
+                if (Buffer.isBuffer(value)) w.writeBytes(value)
+                else w.writeString(value == null ? '' : String(value))
+                return
+            case 'bytes':
+                w.writeBytes(asBuffer(value))
+                return
+            case 'int128':
+                w.writeFixed(asBuffer(value), 16)
+                return
+            case 'int256':
+                w.writeFixed(asBuffer(value), 32)
+                return
+            case 'bool':
+                w.writeBool(Boolean(value))
+                return
+            case 'true':
+                return
+            case 'flags':
+                w.writeUInt32(Number(value ?? 0) >>> 0)
+                return
+            case 'vector':
+                this.writeVector(w, t, Array.isArray(value) ? value : [])
+                return
+            case 'object':
+            case 'boxed':
+                this.writeObject(w, value)
+                return
+            case 'bare':
+                this.writeBare(w, t.name, value)
+                return
+            case 'flag':
+                throw new Error('flag must be handled by writeFields')
+        }
+    }
+
+    private readType(r: TlReader, t: TlType): TlValue {
+        switch (t.kind) {
+            case 'int':
+                return r.readInt32()
+            case 'long':
+                return r.readLong()
+            case 'double':
+                return r.readDouble()
+            case 'string':
+                return r.readString()
+            case 'bytes':
+                return r.readBytes()
+            case 'int128':
+                return r.readInt128()
+            case 'int256':
+                return r.readInt256()
+            case 'bool':
+                return r.readUInt32() === BOOL_TRUE_ID
+            case 'true':
+                return true
+            case 'flags':
+                return r.readUInt32()
+            case 'vector':
+                return this.readVector(r, t)
+            case 'object':
+            case 'boxed':
+                return this.readObject(r)
+            case 'bare':
+                return this.readBare(r, t.name)
+            case 'flag':
+                throw new Error('flag must be handled by readFields')
+        }
+    }
+
+    private writeVector(w: TlWriter, t: Extract<TlType, { kind: 'vector' }>, arr: TlValue[]): void {
+        if (t.boxed) w.writeUInt32(VECTOR_ID)
+        w.writeUInt32(arr.length)
+        for (const el of arr) this.writeType(w, t.inner, el)
+    }
+
+    private readVector(r: TlReader, t: Extract<TlType, { kind: 'vector' }>): TlValue[] {
+        if (t.boxed) {
+            const id = r.readUInt32()
+            if (id !== VECTOR_ID) {
+                throw new Error(`Expected Vector id, got 0x${(id >>> 0).toString(16).padStart(8, '0')}`)
+            }
+        }
+        const count = r.readUInt32()
+        const out: TlValue[] = []
+        for (let i = 0; i < count; i++) out.push(this.readType(r, t.inner))
+        return out
+    }
+
+    private protocolCodecByName(name: string) {
+        const def = this.registry.getByName(name)
+        if (!def) return undefined
+        return this.registry.getProtocolCodec(def.idNum)
+    }
+}
+
+/**
+ * Names of the bitmask fields in a param list: any `#` field plus any field
+ * referenced by a conditional (`name.bit?...`). Handles schemas that declare
+ * the bitmask as `flags:int` rather than the canonical `flags:#`.
+ */
+function collectBitmaskFields(params: import('@mt-tl/tl').TlParam[]): Set<string> {
+    const names = new Set<string>()
+    for (const p of params) {
+        if (p.type.kind === 'flags') names.add(p.name)
+        else if (p.type.kind === 'flag') names.add(p.type.flagsField)
+    }
+    return names
+}
+
+function asBuffer(value: TlValue): Buffer {
+    if (Buffer.isBuffer(value)) return value
+    if (value == null) return Buffer.alloc(0)
+    if (typeof value === 'string') return Buffer.from(value, 'hex')
+    throw new Error(`Expected Buffer, got ${typeof value}`)
+}