data-ark 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shovity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# data-ark
+
+Cắt file lớn thành từng chunk 1.8GB và lưu trữ trên Telegram, khôi phục lại được nguyên vẹn.
+
+## Dùng ngay
+
+```bash
+npx data-ark login                        # chỉ cần một lần
+npx data-ark data.tar --to @kho_backup    # đích được ghi nhớ cho lần sau
+npx data-ark data.tar                     # từ lần thứ hai trở đi
+npx data-ark restore ark-20260905-7f3a91
+```
+
+## Cần chuẩn bị
+
+- Node.js 18 trở lên.
+- `api_id` và `api_hash` lấy tại <https://my.telegram.org> → API development tools. Lệnh `login` sẽ hỏi hai giá trị này, kèm số điện thoại và mã xác nhận.
+
+data-ark đăng nhập bằng chính tài khoản Telegram của bạn (MTProto), không phải bot. Đây là điều kiện bắt buộc: Bot API chỉ cho upload 50MB mỗi file, còn tài khoản người dùng được 2GB.
+
+## Tuỳ chọn
+
+| Cờ | Mặc định | Ý nghĩa |
+|---|---|---|
+| `--to <chat>` | đích đã ghi nhớ | `@username`, `-100123…`, hoặc `me` |
+| `--chunk-size <n>` | `1800MB` | Ví dụ `1.8GB`, `500MB`. Trần cứng 1950MB. |
+| `--concurrency <n>` | `8` | Số phần 512KB gửi song song. Phải là số nguyên từ 1 đến 64. |
+| `--out <đường-dẫn>` | basename của tên trong manifest | Nơi ghi file khi restore, tính từ thư mục hiện tại nếu là đường dẫn tương đối |
+
+## Hoạt động thế nào
+
+Mỗi lần chạy sinh ra một `backupId`. File được đọc thẳng theo offset, không tạo file tạm, và đẩy lên thành các document tên `<backupId>.partNNNN`. Xong hết, data-ark gửi thêm một manifest JSON liệt kê message id và sha256 của từng chunk. Restore chỉ cần `backupId`: nó tìm manifest trong chat, tải từng chunk về đúng vị trí trong một file `.partial`, đối chiếu sha256 và kích thước từng chunk, và chỉ đổi tên thành file thật sau khi *toàn bộ* chunk đã khớp.
+
+Đứt mạng giữa chừng lúc **upload** thì cứ chạy lại đúng lệnh cũ — tiến độ nằm ở `~/.data-ark/state/`, những chunk đã xong sẽ được bỏ qua (`backupId` giữ nguyên). Vài lưu ý về việc chạy lại:
+
+- Nếu chạy lại với `--to` khác với đích đã lưu trong tiến độ dở dang, data-ark **từ chối chạy** thay vì tự chuyển hướng — một backup không thể tách làm hai đích. Thông báo lỗi chỉ đường: bỏ `--to` để tiếp tục gửi vào đích cũ, hoặc xoá file trạng thái để bắt đầu backup mới.
+- Nếu chạy lại với `--chunk-size` khác, data-ark coi đó là một backup mới hoàn toàn (backup id mới), không resume.
+
+**Restore không có trạng thái để resume.** Nhấn `Ctrl-C` giữa lúc restore thì không có gì được lưu — chạy lại sẽ tải lại từ đầu.
+
+## Giới hạn cần biết
+
+- Chunk không thể vượt 1950MB: Telegram nhận tối đa 4000 phần 512KB mỗi file, tức trần số học khoảng 1953MB, và data-ark chốt ở 1950MB để chừa biên an toàn.
+- Dữ liệu **không** được mã hoá. Đừng đẩy thứ gì bạn không muốn nằm trên hạ tầng của người khác.
+- Xoá message chunk trên Telegram là mất backup, không có cách cứu.
+- Giữ lấy `backupId`. Không có nó thì phải tự tìm manifest trong chat bằng tay.
+
+## Cấu hình lưu ở đâu
+
+`~/.data-ark/config.json` (quyền 600) chứa `apiId`, `apiHash`, session và đích lưu mặc định. `npx data-ark logout` **chỉ xoá bản session lưu dưới máy** và giữ lại phần còn lại — phiên đăng nhập vẫn còn sống phía Telegram. Muốn cắt hẳn quyền truy cập thì vào Telegram → Settings → Devices (Active sessions) và thu hồi phiên đó.

package/bin/data-ark.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { route, HELP } from '../src/cli.js'
+import { runLogin } from '../src/commands/login.js'
+import { runLogout } from '../src/commands/logout.js'
+import { runRestore } from '../src/commands/restore.js'
+import { runUpload } from '../src/commands/upload.js'
+
+const SIGINT_EXIT_CODE = 130
+
+// Lệnh đang chạy khi Ctrl-C xảy ra — mỗi lệnh có một sự thật khác nhau về việc
+// tiến độ có được lưu hay không, nên phải biết đang ở lệnh nào mới chọn đúng câu.
+let currentCommand = null
+
+function sigintMessage(command) {
+  if (command === 'upload') {
+    return '\nĐã dừng. Tiến độ đã lưu, chạy lại lệnh cũ để đi tiếp.\n'
+  }
+
+  if (command === 'restore') {
+    return '\nĐã dừng. Chưa lưu tiến độ tải, chạy lại sẽ tải lại từ đầu.\n'
+  }
+
+  return '\nĐã dừng.\n'
+}
+
+process.on('SIGINT', () => {
+  process.stderr.write(sigintMessage(currentCommand))
+  process.exit(SIGINT_EXIT_CODE)
+})
+
+async function main() {
+  let parsed
+
+  try {
+    parsed = route(process.argv.slice(2))
+  } catch (err) {
+    process.stderr.write(`Lỗi: ${err.message}\n\n${HELP}`)
+    process.exitCode = 2
+    return
+  }
+
+  currentCommand = parsed.command
+
+  switch (parsed.command) {
+    case 'help':
+      process.stdout.write(HELP)
+      return
+
+    case 'login':
+      await runLogin()
+      return
+
+    case 'logout':
+      await runLogout()
+      return
+
+    case 'upload':
+      await runUpload(parsed.args[0], parsed.options)
+      return
+
+    case 'restore':
+      if (!parsed.args[0]) {
+        throw new Error('Thiếu backup id. Ví dụ: npx data-ark restore ark-20260905-7f3a91')
+      }
+      await runRestore(parsed.args[0], parsed.options)
+      return
+
+    default:
+      throw new Error(`Lệnh không nhận ra: ${parsed.command}`)
+  }
+}
+
+// GramJS giữ lại các "exported sender" cùng một timer 30 giây để giải phóng
+// chúng, và client.disconnect()/destroy() không dọn nổi: cả hai map đó là Map
+// nhưng code duyệt bằng Object.values nên bỏ sót sạch. Hệ quả: lệnh in "Xong"
+// rồi vẫn treo thêm ~30 giây, và Ctrl-C trong khoảng đó lại báo sai rằng chưa
+// lưu được gì. Chạy xong việc là thoát hẳn, không nấn ná.
+function exitWhenFlushed(code) {
+  // Ghi rỗng chỉ để mượn callback: nó chạy sau khi mọi thứ xếp hàng trước đó đã
+  // xả xuống pipe, nên không mất chữ nào khi stdout/stderr không phải TTY.
+  let pending = 2
+
+  const done = () => {
+    pending -= 1
+    if (pending === 0) process.exit(code)
+  }
+
+  // Lưới an toàn: nếu callback không bao giờ tới (pipe đã đóng) thì vẫn thoát.
+  setTimeout(() => process.exit(code), 2000).unref()
+
+  process.stdout.write('', done)
+  process.stderr.write('', done)
+}
+
+main().then(
+  () => {
+    exitWhenFlushed(process.exitCode ?? 0)
+  },
+  (err) => {
+    process.stderr.write(`Lỗi: ${err.message}\n`)
+    process.exitCode = 1
+    exitWhenFlushed(1)
+  },
+)

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "data-ark",
+  "version": "0.1.0",
+  "description": "Cắt file lớn thành chunk và lưu trữ trên Telegram",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "data-ark": "bin/data-ark.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'"
+  },
+  "dependencies": {
+    "telegram": "^2.26.22"
+  }
+}

package/src/chunking.js

@@ -0,0 +1,51 @@
+export const PART_SIZE = 512 * 1024
+export const MAX_PARTS = 4000
+export const MAX_CHUNK_SIZE = 1950 * 1024 * 1024
+export const DEFAULT_CHUNK_SIZE = 1800 * 1024 * 1024
+export const DEFAULT_CONCURRENCY = 8
+export const MAX_CONCURRENCY = 64
+
+const UNITS = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 * 1024,
+  gb: 1024 * 1024 * 1024,
+}
+
+export function parseSize(input) {
+  const text = String(input).trim().toLowerCase()
+  const match = text.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/)
+
+  if (!match) {
+    throw new Error(`Kích thước không hợp lệ: "${input}". Ví dụ hợp lệ: 1800MB, 1.8GB, 524288.`)
+  }
+
+  const bytes = Math.floor(Number(match[1]) * UNITS[match[2] ?? 'b'])
+
+  if (bytes <= 0) {
+    throw new Error('Kích thước phải lớn hơn 0.')
+  }
+
+  if (bytes > MAX_CHUNK_SIZE) {
+    throw new Error(
+      'Chunk tối đa là 1950MB. Telegram chỉ nhận 4000 phần 512KB cho mỗi file, ' +
+        'tức trần số học khoảng 1953MB, nên cần chừa biên an toàn.',
+    )
+  }
+
+  return bytes
+}
+
+export function planChunks(fileSize, chunkSize) {
+  if (fileSize <= 0) {
+    throw new Error('File rỗng, không có gì để upload.')
+  }
+
+  const chunks = []
+
+  for (let offset = 0, i = 0; offset < fileSize; offset += chunkSize, i += 1) {
+    chunks.push({ i, offset, length: Math.min(chunkSize, fileSize - offset) })
+  }
+
+  return chunks
+}

package/src/cli.js

@@ -0,0 +1,47 @@
+import { parseArgs } from 'node:util'
+
+const SUBCOMMANDS = new Set(['login', 'logout', 'restore', 'help'])
+
+const OPTIONS = {
+  to: { type: 'string' },
+  'chunk-size': { type: 'string' },
+  concurrency: { type: 'string' },
+  out: { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+}
+
+export const HELP = `data-ark — cắt file lớn thành chunk và lưu trữ trên Telegram
+
+Cách dùng:
+  npx data-ark login                        Đăng nhập Telegram, chỉ cần chạy một lần
+  npx data-ark <file>                       Cắt file và đẩy lên Telegram
+  npx data-ark restore <backup-id>          Tải về và ghép lại file gốc
+  npx data-ark logout                       Xoá phiên đăng nhập đã lưu
+
+Tuỳ chọn:
+  --to <chat>            Đích lưu: @username, -100123..., hoặc me. Được ghi nhớ cho lần sau.
+  --chunk-size <n>       Kích thước mỗi chunk, mặc định 1800MB. Ví dụ: 1.8GB, 500MB.
+  --concurrency <n>      Số phần 512KB gửi song song, mặc định 8, tối đa 64.
+  --out <đường-dẫn>      Nơi ghi file khi restore. Mặc định lấy basename của tên trong manifest.
+  -h, --help             Hiện trợ giúp này.
+`
+
+export function route(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: OPTIONS,
+    allowPositionals: true,
+  })
+
+  const [first, ...rest] = positionals
+
+  if (values.help || first === undefined || first === 'help') {
+    return { command: 'help', args: [], options: values }
+  }
+
+  if (SUBCOMMANDS.has(first)) {
+    return { command: first, args: rest, options: values }
+  }
+
+  return { command: 'upload', args: [first], options: values }
+}

package/src/client.js

@@ -0,0 +1,52 @@
+import { TelegramClient } from 'telegram'
+import { StringSession } from 'telegram/sessions/index.js'
+
+export function normalizeChatTarget(input) {
+  const text = String(input).trim()
+
+  if (text === '') {
+    throw new Error('Đích lưu không được để rỗng.')
+  }
+
+  if (/^-?\d+$/.test(text)) {
+    return Number(text)
+  }
+
+  return text
+}
+
+export function requireChat(options, config) {
+  const raw = options.to ?? config.defaultChat
+
+  if (!raw) {
+    throw new Error(
+      'Chưa có đích lưu — chạy lại với --to @kho_backup (hoặc --to me để dùng Saved Messages). ' +
+        'Lần sau data-ark sẽ tự nhớ.',
+    )
+  }
+
+  return normalizeChatTarget(raw)
+}
+
+export function assertLoggedIn(config) {
+  if (!config.session || !config.apiId || !config.apiHash) {
+    throw new Error('Chưa đăng nhập — chạy "npx data-ark login" trước.')
+  }
+}
+
+export async function connect(config) {
+  assertLoggedIn(config)
+
+  const client = new TelegramClient(new StringSession(config.session), config.apiId, config.apiHash, {
+    connectionRetries: 5,
+    floodSleepThreshold: 60,
+  })
+
+  await client.connect()
+
+  if (!(await client.isUserAuthorized())) {
+    throw new Error('Phiên đăng nhập đã hết hạn — chạy "npx data-ark login".')
+  }
+
+  return client
+}

package/src/commands/login.js

@@ -0,0 +1,87 @@
+import readline from 'node:readline/promises'
+import { stdin, stdout } from 'node:process'
+
+import { TelegramClient } from 'telegram'
+import { StringSession } from 'telegram/sessions/index.js'
+
+import { loadConfig, saveConfig, defaultConfigDir } from '../config.js'
+import { normalizeChatTarget } from '../client.js'
+
+function createPrompts() {
+  const rl = readline.createInterface({ input: stdin, output: stdout })
+  return {
+    ask: (question) => rl.question(question),
+    close: () => rl.close(),
+  }
+}
+
+const LOGIN_ERROR_MESSAGES = {
+  PHONE_NUMBER_INVALID: 'số điện thoại không hợp lệ',
+  PHONE_CODE_INVALID: 'mã xác nhận sai',
+  PHONE_CODE_EXPIRED: 'mã xác nhận đã hết hạn',
+  PASSWORD_HASH_INVALID: 'mật khẩu hai lớp sai',
+  FLOOD_WAIT: 'bị Telegram giới hạn tần suất, cần chờ',
+}
+
+export function describeLoginError(err) {
+  const message = String(err?.message ?? err ?? '')
+  const known = Object.entries(LOGIN_ERROR_MESSAGES).find(([code]) => message.startsWith(code))
+
+  if (!known) return message
+
+  const [, description] = known
+  return `${description} (${message})`
+}
+
+export async function runLogin({ configDir = defaultConfigDir(), prompts = createPrompts() } = {}) {
+  const config = await loadConfig(configDir)
+
+  console.log('Cần api_id và api_hash của riêng bạn. Lấy tại https://my.telegram.org → API development tools.\n')
+
+  const apiIdAnswer = (await prompts.ask(`api_id${config.apiId ? ` [${config.apiId}]` : ''}: `)).trim()
+
+  if (apiIdAnswer !== '' && !/^\d+$/.test(apiIdAnswer)) {
+    prompts.close()
+    throw new Error('api_id phải là số nguyên.')
+  }
+
+  const apiId = apiIdAnswer === '' ? config.apiId : Number(apiIdAnswer)
+  const apiHash = (await prompts.ask(`api_hash${config.apiHash ? ' [giữ nguyên]' : ''}: `)) || config.apiHash
+
+  if (!apiId || !apiHash) {
+    prompts.close()
+    throw new Error('Thiếu api_id hoặc api_hash.')
+  }
+
+  const client = new TelegramClient(new StringSession(''), apiId, apiHash, { connectionRetries: 5 })
+
+  await client.start({
+    phoneNumber: () => prompts.ask('Số điện thoại (dạng +84...): '),
+    phoneCode: () => prompts.ask('Mã xác nhận Telegram vừa gửi: '),
+    password: () => prompts.ask('Mật khẩu hai lớp (bỏ trống nếu không bật): '),
+    onError: (err) => console.error(`Lỗi đăng nhập: ${describeLoginError(err)}`),
+  })
+
+  const me = await client.getMe()
+  const session = client.session.save()
+  await client.disconnect()
+
+  const chatAnswer = (
+    await prompts.ask(
+      `Đẩy backup vào chat nào? (@username, -100..., hoặc me)${config.defaultChat ? ` [${config.defaultChat}]` : ''}, Enter để bỏ qua: `,
+    )
+  ).trim()
+
+  prompts.close()
+
+  const next = { ...config, apiId, apiHash, session }
+
+  if (chatAnswer !== '') {
+    next.defaultChat = String(normalizeChatTarget(chatAnswer))
+  }
+
+  await saveConfig(next, configDir)
+
+  console.log(`\nĐã đăng nhập với tài khoản ${me.username ? `@${me.username}` : me.firstName}.`)
+  console.log(`Cấu hình đã lưu vào ${configDir}/config.json`)
+}

package/src/commands/logout.js

@@ -0,0 +1,13 @@
+import { clearSession, defaultConfigDir } from '../config.js'
+
+export async function runLogout({ configDir = defaultConfigDir() } = {}) {
+  await clearSession(configDir)
+  console.log(
+    'Đã xoá phiên đăng nhập lưu trên máy này. api_id, api_hash và đích lưu vẫn được giữ lại.',
+  )
+  console.log(
+    'Lưu ý: lệnh này chỉ xoá bản lưu dưới máy, phiên vẫn còn sống phía Telegram. ' +
+      'Muốn cắt hẳn quyền truy cập, mở Telegram → Settings → Devices (Active sessions) ' +
+      'và thu hồi phiên đó.',
+  )
+}

package/src/commands/restore.js

@@ -0,0 +1,197 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import readline from 'node:readline/promises'
+import { stdin, stdout } from 'node:process'
+
+import { Api } from 'telegram'
+
+import { connect as realConnect, requireChat } from '../client.js'
+import { defaultConfigDir, loadConfig } from '../config.js'
+import { downloadToFile } from '../downloader.js'
+import { manifestFileName, parseManifest } from '../manifest.js'
+import { createProgress, formatBytes } from '../progress.js'
+
+function documentFileName(message) {
+  const attributes = message?.media?.document?.attributes ?? []
+  const named = attributes.find((a) => a instanceof Api.DocumentAttributeFilename)
+  return named?.fileName ?? null
+}
+
+async function realSearchManifest(client, peer, backupId) {
+  const wanted = manifestFileName(backupId)
+
+  // Dùng client.getMessages thay vì raw Api.messages.Search: nó tự lo offset,
+  // hash và phân trang, nên không phải tự dựng các trường dễ sai kiểu.
+  const messages = await client.getMessages(peer, {
+    search: backupId,
+    filter: new Api.InputMessagesFilterDocument(),
+    limit: 100,
+  })
+
+  return messages.find((m) => documentFileName(m) === wanted) ?? null
+}
+
+async function realReadMessageBytes(client, message) {
+  return await client.downloadMedia(message)
+}
+
+async function realGetMessage(client, peer, msgId) {
+  const [message] = await client.getMessages(peer, { ids: [msgId] })
+  return message ?? null
+}
+
+export async function realDownloadChunk(client, message, handle, offset, onProgress) {
+  return await downloadToFile(client, message, handle.fd, { offset, onProgress })
+}
+
+// manifest.name đến từ dữ liệu tải về Telegram — không tin nó khi tự chọn đường
+// dẫn. path.basename chặn được "../../x" nhưng vẫn trả về "..", "." hay "" cho
+// vài tên bệnh: path.resolve('..') là thư mục cha, nên file .partial hàng GB sẽ
+// nằm ngoài thư mục hiện tại và chỉ vỡ ra ở bước rename.
+function safeOutName(name) {
+  const base = path.basename(String(name ?? ''))
+
+  if (base === '' || base === '.' || base === '..') {
+    throw new Error(
+      `Tên file trong manifest ("${name}") không dùng được làm tên file. ` +
+        'Chạy lại kèm --out <đường-dẫn> để tự chỉ định nơi ghi.',
+    )
+  }
+
+  return base
+}
+
+async function askConfirm(question) {
+  const rl = readline.createInterface({ input: stdin, output: stdout })
+  const answer = await rl.question(question)
+  rl.close()
+  return /^(c|y)/i.test(answer.trim())
+}
+
+export async function runRestore(backupId, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    searchManifest = realSearchManifest,
+    readMessageBytes = realReadMessageBytes,
+    getMessage = realGetMessage,
+    downloadChunk = realDownloadChunk,
+    confirm = askConfirm,
+    writeErr = (line) => process.stderr.write(line),
+    silent = false,
+  } = deps
+
+  const config = await loadConfig(configDir)
+  const chat = requireChat(options, config)
+  const log = silent ? () => {} : (line) => console.log(line)
+  const warn = silent ? () => {} : writeErr
+
+  const client = await connect(config)
+
+  try {
+    const manifestMessage = await searchManifest(client, chat, backupId)
+
+    if (!manifestMessage) {
+      throw new Error(
+        `Không tìm thấy manifest của ${backupId} trong ${chat}. ` +
+          'Kiểm tra lại backup id, hoặc dùng --to để trỏ đúng chat.',
+      )
+    }
+
+    const manifest = parseManifest(await readMessageBytes(client, manifestMessage))
+    // Khi người dùng tự chỉ định --out thì tôn trọng nguyên văn đường dẫn đó.
+    const target = path.resolve(options.out ?? safeOutName(manifest.name))
+    const partial = `${target}.partial`
+
+    // Chỉ ENOENT mới có nghĩa là "chưa có file". Lỗi quyền hay lỗi I/O mà bị coi
+    // là vắng mặt thì data-ark sẽ ghi đè file của người dùng mà không hỏi.
+    let exists = true
+    try {
+      await fs.stat(target)
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+      exists = false
+    }
+
+    if (exists && !(await confirm(`${target} đã tồn tại. Ghi đè? [c/K] `))) {
+      throw new Error('Đã huỷ theo yêu cầu.')
+    }
+
+    log(`Backup ${manifest.id}`)
+    log(`File   ${target} (${formatBytes(manifest.size)}, ${manifest.chunks.length} chunk)\n`)
+
+    const handle = await fs.open(partial, 'w+')
+
+    try {
+      await handle.truncate(manifest.size)
+
+      for (const chunk of manifest.chunks) {
+        const message = await getMessage(client, chat, chunk.msgId)
+
+        if (!message) {
+          throw new Error(
+            `Thiếu chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} không còn trong ${chat}. ` +
+              'Backup này không khôi phục được.',
+          )
+        }
+
+        const progress = silent
+          ? { advance: () => {}, finish: () => {} }
+          : createProgress({
+              total: chunk.size,
+              label: `Chunk ${chunk.i + 1}/${manifest.chunks.length}`,
+              write: writeErr,
+            })
+
+        const { sha256, size } = await downloadChunk(
+          client,
+          message,
+          handle,
+          chunk.i * manifest.chunkSize,
+          progress.advance,
+        )
+
+        progress.finish()
+
+        if (size !== chunk.size) {
+          throw new Error(
+            `Chunk ${chunk.i + 1} có ${size} byte, manifest ghi ${chunk.size} byte — không khớp.`,
+          )
+        }
+
+        if (sha256 !== chunk.sha256) {
+          throw new Error(
+            `Chunk ${chunk.i + 1} có sha256 không khớp manifest. File tải về giữ ở ${partial} để kiểm tra.`,
+          )
+        }
+      }
+    } finally {
+      await handle.close()
+    }
+
+    // Chốt chặn cuối: mọi chunk khớp sha256 mà file vẫn sai độ dài thì bố cục đã
+    // lệch ở đâu đó. Thà báo lỗi còn hơn đổi tên một file sai thành file thật.
+    const written = await fs.stat(partial)
+
+    if (written.size !== manifest.size) {
+      throw new Error(
+        `File ghép xong có ${written.size} byte, manifest ghi ${manifest.size} byte — không khớp. ` +
+          `File tải về giữ ở ${partial} để kiểm tra.`,
+      )
+    }
+
+    await fs.rename(partial, target)
+
+    log(`\nXong. Đã ghi ${formatBytes(manifest.size)} vào ${target}`)
+
+    return { path: target, size: manifest.size }
+  } finally {
+    // Ngắt kết nối hỏng thì cũng không được nuốt mất lỗi thật đang bay lên.
+    try {
+      await disconnect(client)
+    } catch (err) {
+      warn(`\nCảnh báo: không đóng được kết nối Telegram: ${err.message}\n`)
+    }
+  }
+}

package/src/commands/upload.js

@@ -0,0 +1,237 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+import { Api } from 'telegram'
+import { CustomFile } from 'telegram/client/uploads.js'
+
+import {
+  DEFAULT_CHUNK_SIZE,
+  DEFAULT_CONCURRENCY,
+  MAX_CONCURRENCY,
+  PART_SIZE,
+  parseSize,
+  planChunks,
+} from '../chunking.js'
+import { connect as realConnect, requireChat } from '../client.js'
+import { defaultConfigDir, loadConfig, saveConfig } from '../config.js'
+import {
+  buildManifest,
+  chunkFileName,
+  manifestFileName,
+  newBackupId,
+  serializeManifest,
+} from '../manifest.js'
+import { createProgress, formatBytes, formatDuration } from '../progress.js'
+import { clearState, loadState, markChunkDone, saveState, stateDir, stateKey } from '../state.js'
+import { uploadRange } from '../uploader.js'
+
+// Trên ngưỡng này thì phải nói rõ đang chờ bao lâu, theo spec §8.
+const LONG_WAIT_MS = 60_000
+
+async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
+  return await client.sendFile(peer, {
+    file: inputFile,
+    caption,
+    forceDocument: true,
+    attributes: [new Api.DocumentAttributeFilename({ fileName })],
+  })
+}
+
+async function realSendManifest(client, peer, { bytes, fileName, caption }) {
+  return await client.sendFile(peer, {
+    file: new CustomFile(fileName, bytes.length, '', bytes),
+    caption,
+    forceDocument: true,
+    attributes: [new Api.DocumentAttributeFilename({ fileName })],
+  })
+}
+
+export async function runUpload(filePath, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    sendChunk = realSendChunk,
+    sendManifest = realSendManifest,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    partSize = PART_SIZE,
+    retryOptions = {},
+    writeErr = (line) => process.stderr.write(line),
+    silent = false,
+  } = deps
+
+  const absPath = path.resolve(filePath)
+
+  let stat
+  try {
+    stat = await fs.stat(absPath)
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`File không tồn tại: ${absPath}`)
+    throw err
+  }
+
+  if (!stat.isFile()) {
+    throw new Error(`${absPath} không phải là file.`)
+  }
+
+  const config = await loadConfig(configDir)
+  const chat = requireChat(options, config)
+  const chunkSize = options['chunk-size'] ? parseSize(options['chunk-size']) : DEFAULT_CHUNK_SIZE
+  const concurrency = options.concurrency ? Number(options.concurrency) : DEFAULT_CONCURRENCY
+
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > MAX_CONCURRENCY) {
+    throw new Error(
+      `--concurrency không hợp lệ: "${options.concurrency}". ` +
+        `Phải là số nguyên từ 1 đến ${MAX_CONCURRENCY} — mỗi luồng giữ một phần 512KB trong RAM ` +
+        'và Telegram sẽ bắt chờ FLOOD_WAIT nếu bắn quá nhiều request cùng lúc.',
+    )
+  }
+
+  const chunks = planChunks(stat.size, chunkSize)
+  const key = stateKey(absPath, stat.size, stat.mtimeMs)
+
+  let state = await loadState(key, configDir)
+  const resuming = Boolean(state) && state.chunkSize === chunkSize
+
+  if (resuming && state.chat !== String(chat)) {
+    const stateFile = path.join(stateDir(configDir), `${key}.json`)
+    throw new Error(
+      `Backup dở dang này đang gửi vào ${state.chat}, nhưng lệnh hiện tại chỉ định đích ${chat} — ` +
+        `không thể tách một backup ra hai đích khác nhau. Chạy lại không kèm --to để tiếp tục gửi vào ` +
+        `${state.chat}, hoặc xoá ${stateFile} rồi chạy lại để bắt đầu backup mới vào ${chat}.`,
+    )
+  }
+
+  if (options.to) {
+    await saveConfig({ ...config, defaultChat: String(chat) }, configDir)
+  }
+
+  if (!resuming) {
+    state = {
+      id: newBackupId(),
+      chat: String(chat),
+      path: absPath,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      chunkSize,
+      done: {},
+    }
+    await saveState(key, state, configDir)
+  }
+
+  const log = silent ? () => {} : (line) => console.log(line)
+  const warn = silent ? () => {} : writeErr
+
+  // Thử lại và FLOOD_WAIT phải nói ra: một FLOOD_WAIT_3600 mà im lặng thì người
+  // dùng chỉ thấy thanh tiến độ đứng hình cả tiếng và tưởng máy treo.
+  function onRetry(err, attempt, delayMs) {
+    if (delayMs > LONG_WAIT_MS) {
+      warn(
+        `\nTelegram bắt chờ ${formatDuration(delayMs / 1000)} rồi mới cho gửi tiếp ` +
+          `(${err.message}). data-ark đang đợi và sẽ tự đi tiếp, đừng tắt.\n`,
+      )
+      return
+    }
+
+    warn(
+      `\nLỗi tạm thời (${err.message}), thử lại lần ${attempt} sau ` +
+        `${formatDuration(delayMs / 1000)}.\n`,
+    )
+  }
+
+  log(`Backup ${state.id}`)
+  log(`File   ${absPath} (${formatBytes(stat.size)}, ${chunks.length} chunk)`)
+  log(`Đích   ${chat}\n`)
+
+  const client = await connect(config)
+
+  try {
+    for (const chunk of chunks) {
+      if (state.done[String(chunk.i)]) {
+        log(`Chunk ${chunk.i + 1}/${chunks.length} đã có, bỏ qua.`)
+        continue
+      }
+
+      const fileName = chunkFileName(state.id, chunk.i)
+      const handle = await fs.open(absPath, 'r')
+
+      const progress = silent
+        ? { advance: () => {}, finish: () => {} }
+        : createProgress({
+            total: chunk.length,
+            label: `Chunk ${chunk.i + 1}/${chunks.length}`,
+            write: writeErr,
+          })
+
+      try {
+        const { inputFile, sha256 } = await uploadRange(client, handle.fd, {
+          offset: chunk.offset,
+          length: chunk.length,
+          fileName,
+          concurrency,
+          partSize,
+          onProgress: (bytes) => progress.advance(bytes),
+          retryOptions: { ...retryOptions, onRetry },
+        })
+
+        progress.finish()
+
+        const message = await sendChunk(client, chat, {
+          inputFile,
+          fileName,
+          caption: `#dataark ${state.id} ${chunk.i + 1}/${chunks.length}`,
+        })
+
+        state = await markChunkDone(
+          key,
+          state,
+          chunk.i,
+          { msgId: message.id, size: chunk.length, sha256 },
+          configDir,
+        )
+      } finally {
+        await handle.close()
+      }
+    }
+
+    // File có thể bị ghi đè trong lúc upload — với file 50GB thì cả tiếng đồng
+    // hồ trôi qua giữa chunk đầu và chunk cuối. Khi đó manifest mô tả một file
+    // lai chưa từng tồn tại: restore vẫn khớp sha256 nhưng dữ liệu là rác.
+    const after = await fs.stat(absPath)
+
+    if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) {
+      throw new Error(
+        `${absPath} đã thay đổi trong lúc upload ` +
+          `(kích thước ${stat.size} → ${after.size}, mtime ${stat.mtimeMs} → ${after.mtimeMs}). ` +
+          'Backup này trộn dữ liệu cũ với dữ liệu mới nên không đáng tin — data-ark không gửi manifest. ' +
+          'Chờ file ổn định rồi chạy lại để tạo một backup mới.',
+      )
+    }
+
+    const manifest = buildManifest({
+      id: state.id,
+      name: path.basename(absPath),
+      size: stat.size,
+      chunkSize,
+      chunks: chunks.map((chunk) => ({ i: chunk.i, ...state.done[String(chunk.i)] })),
+    })
+
+    await sendManifest(client, chat, {
+      bytes: serializeManifest(manifest),
+      fileName: manifestFileName(state.id),
+      caption: `#dataark ${state.id} manifest`,
+    })
+
+    await clearState(key, configDir)
+
+    log(`\nXong. Khôi phục bằng:\n  npx data-ark restore ${state.id}`)
+
+    return { id: state.id, chunks: chunks.length }
+  } finally {
+    // Ngắt kết nối hỏng thì cũng không được nuốt mất lỗi thật đang bay lên.
+    try {
+      await disconnect(client)
+    } catch (err) {
+      warn(`\nCảnh báo: không đóng được kết nối Telegram: ${err.message}\n`)
+    }
+  }
+}

package/src/config.js

@@ -0,0 +1,43 @@
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const FILE_NAME = 'config.json'
+
+export function defaultConfigDir() {
+  return path.join(os.homedir(), '.data-ark')
+}
+
+export async function loadConfig(dir = defaultConfigDir()) {
+  const file = path.join(dir, FILE_NAME)
+
+  let raw
+  try {
+    raw = await fs.readFile(file, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return {}
+    throw err
+  }
+
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw new Error(`File cấu hình hỏng: ${file}. Xoá nó rồi chạy lại "data-ark login".`)
+  }
+}
+
+export async function saveConfig(config, dir = defaultConfigDir()) {
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 })
+
+  const file = path.join(dir, FILE_NAME)
+  const tmp = `${file}.tmp`
+
+  await fs.writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  await fs.rename(tmp, file)
+}
+
+export async function clearSession(dir = defaultConfigDir()) {
+  const config = await loadConfig(dir)
+  delete config.session
+  await saveConfig(config, dir)
+}

package/src/downloader.js

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto'
+import { write as writeCallback } from 'node:fs'
+import { promisify } from 'node:util'
+
+import { PART_SIZE } from './chunking.js'
+
+const write = promisify(writeCallback)
+
+async function writeExactly(fd, buffer, position) {
+  let written = 0
+
+  while (written < buffer.length) {
+    const { bytesWritten } = await write(fd, buffer, written, buffer.length - written, position + written)
+    written += bytesWritten
+  }
+}
+
+export async function downloadToFile(client, message, fd, { offset, onProgress } = {}) {
+  const document = message?.media?.document
+
+  if (!document) {
+    throw new Error(`Message ${message?.id} không chứa file đính kèm.`)
+  }
+
+  if (!Number.isFinite(offset)) {
+    throw new Error(`offset phải là một số hữu hạn, nhận được: ${offset}`)
+  }
+
+  const hash = createHash('sha256')
+  let written = 0
+
+  for await (const buffer of client.iterDownload({ file: document, requestSize: PART_SIZE })) {
+    await writeExactly(fd, buffer, offset + written)
+    hash.update(buffer)
+    written += buffer.length
+    onProgress?.(buffer.length)
+  }
+
+  return { sha256: hash.digest('hex'), size: written }
+}

package/src/manifest.js

@@ -0,0 +1,92 @@
+import { randomBytes } from 'node:crypto'
+
+export const MANIFEST_VERSION = 1
+
+export function newBackupId(now = new Date(), randomHex = () => randomBytes(3).toString('hex')) {
+  const yyyy = now.getUTCFullYear()
+  const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
+  const dd = String(now.getUTCDate()).padStart(2, '0')
+  return `ark-${yyyy}${mm}${dd}-${randomHex()}`
+}
+
+export function chunkFileName(id, i) {
+  return `${id}.part${String(i + 1).padStart(4, '0')}`
+}
+
+export function manifestFileName(id) {
+  return `${id}.manifest.json`
+}
+
+export function buildManifest({ id, name, size, chunkSize, chunks, createdAt = new Date().toISOString() }) {
+  return {
+    v: MANIFEST_VERSION,
+    id,
+    name,
+    size,
+    chunkSize,
+    createdAt,
+    chunks: [...chunks]
+      .sort((a, b) => a.i - b.i)
+      .map(({ i, msgId, size: chunkBytes, sha256 }) => ({ i, msgId, size: chunkBytes, sha256 })),
+  }
+}
+
+export function serializeManifest(manifest) {
+  return Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+}
+
+export function parseManifest(input) {
+  const text = Buffer.isBuffer(input) ? input.toString('utf8') : String(input)
+
+  let manifest
+  try {
+    manifest = JSON.parse(text)
+  } catch {
+    throw new Error('Không đọc được manifest: nội dung không phải JSON hợp lệ.')
+  }
+
+  if (manifest.v !== MANIFEST_VERSION) {
+    throw new Error(
+      `Manifest dùng phiên bản ${manifest.v}, bản data-ark này chỉ hiểu phiên bản ${MANIFEST_VERSION}.`,
+    )
+  }
+
+  if (!Array.isArray(manifest.chunks) || manifest.chunks.length === 0) {
+    throw new Error('Manifest thiếu danh sách chunk.')
+  }
+
+  manifest.chunks.forEach((chunk, index) => {
+    if (chunk.i !== index) {
+      throw new Error(`Manifest thiếu chunk số ${index}: danh sách chunk không liên tục.`)
+    }
+  })
+
+  const expectedChunks = Math.ceil(manifest.size / manifest.chunkSize)
+  if (manifest.chunks.length !== expectedChunks) {
+    throw new Error(`Manifest thiếu ${expectedChunks - manifest.chunks.length} chunk(s).`)
+  }
+
+  const total = manifest.chunks.reduce((sum, chunk) => sum + chunk.size, 0)
+  if (total !== manifest.size) {
+    throw new Error(
+      `Tổng kích thước các chunk (${total}) không khớp kích thước file trong manifest (${manifest.size}).`,
+    )
+  }
+
+  // Restore ghi chunk i vào đúng offset i * chunkSize, nên bố cục phải đều:
+  // mọi chunk đúng bằng chunkSize, riêng chunk cuối là phần dư. Tổng đúng mà
+  // từng chunk lệch thì file ghép ra sẽ thủng lỗ hoặc dài thêm mà sha256 từng
+  // chunk vẫn khớp — sai âm thầm, đúng thứ data-ark không được phép để xảy ra.
+  manifest.chunks.forEach((chunk, index) => {
+    const expected = Math.min(manifest.chunkSize, manifest.size - index * manifest.chunkSize)
+    if (chunk.size !== expected) {
+      throw new Error(
+        `Chunk ${index + 1} trong manifest ghi ${chunk.size} byte, nhưng theo bố cục ` +
+          `${manifest.chunkSize} byte mỗi chunk thì phải là ${expected} byte. ` +
+          'Manifest này mô tả sai vị trí các chunk, khôi phục sẽ ra file hỏng.',
+      )
+    }
+  })
+
+  return manifest
+}

package/src/progress.js

@@ -0,0 +1,71 @@
+const UNITS = ['B', 'KB', 'MB', 'GB', 'TB']
+
+export function formatBytes(n) {
+  if (n < 1024) return `${n} B`
+
+  let value = n
+  let unit = 0
+
+  while (value >= 1024 && unit < UNITS.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+
+  return `${value.toFixed(1)} ${UNITS[unit]}`
+}
+
+export function formatDuration(seconds) {
+  if (!Number.isFinite(seconds)) return '--'
+
+  const total = Math.round(seconds)
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+
+  if (h > 0) return `${h}h${m}m`
+  if (m > 0) return `${m}m${s}s`
+  return `${s}s`
+}
+
+export function renderProgress({ done, total, elapsedMs, label, width = 24 }) {
+  const ratio = total === 0 ? 1 : Math.min(done / total, 1)
+  const filled = Math.round(ratio * width)
+  const bar = `${'█'.repeat(filled)}${'░'.repeat(width - filled)}`
+
+  const bytesPerSecond = elapsedMs > 0 ? done / (elapsedMs / 1000) : 0
+  // Kẹp về 0: done có thể vượt total (đếm dư một nhịp) và ETA âm thì vô nghĩa.
+  const remaining = bytesPerSecond > 0 ? Math.max(0, (total - done) / bytesPerSecond) : Infinity
+
+  const percent = String(Math.floor(ratio * 100)).padStart(3)
+  const speed = `${formatBytes(Math.round(bytesPerSecond))}/s`
+
+  return `${label} ${bar} ${percent}% ${formatBytes(done)}/${formatBytes(total)} ${speed} còn ${formatDuration(remaining)}`
+}
+
+export function createProgress({
+  total,
+  label,
+  write = (line) => process.stderr.write(line),
+  now = () => Date.now(),
+  minIntervalMs = 200,
+}) {
+  const startedAt = now()
+  let done = 0
+  let lastDrawnAt = startedAt
+
+  function draw(suffix) {
+    write(`\r${renderProgress({ done, total, elapsedMs: now() - startedAt, label })}${suffix}`)
+  }
+
+  return {
+    advance(bytes) {
+      done += bytes
+      if (now() - lastDrawnAt < minIntervalMs) return
+      lastDrawnAt = now()
+      draw('')
+    },
+    finish() {
+      draw('\n')
+    },
+  }
+}

package/src/retry.js

@@ -0,0 +1,42 @@
+const DEFAULT_ATTEMPTS = 5
+const DEFAULT_BASE_DELAY_MS = 1000
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function floodWaitSeconds(err) {
+  if (typeof err?.seconds === 'number' && String(err?.errorMessage ?? '').includes('FLOOD_WAIT')) {
+    return err.seconds
+  }
+  return null
+}
+
+export async function withRetry(fn, options = {}) {
+  const {
+    attempts = DEFAULT_ATTEMPTS,
+    baseDelayMs = DEFAULT_BASE_DELAY_MS,
+    sleep = defaultSleep,
+    onRetry,
+  } = options
+
+  let lastError
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastError = err
+
+      if (attempt === attempts) break
+
+      const flood = floodWaitSeconds(err)
+      const delayMs = flood === null ? baseDelayMs * 2 ** (attempt - 1) : flood * 1000
+
+      onRetry?.(err, attempt, delayMs)
+      await sleep(delayMs)
+    }
+  }
+
+  throw lastError
+}

package/src/state.js

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+import { defaultConfigDir } from './config.js'
+
+export function stateDir(configDir = defaultConfigDir()) {
+  return path.join(configDir, 'state')
+}
+
+export function stateKey(absPath, size, mtimeMs) {
+  return createHash('sha1').update(`${absPath}:${size}:${mtimeMs}`).digest('hex')
+}
+
+function stateFile(key, configDir) {
+  return path.join(stateDir(configDir), `${key}.json`)
+}
+
+export async function loadState(key, configDir = defaultConfigDir()) {
+  try {
+    return JSON.parse(await fs.readFile(stateFile(key, configDir), 'utf8'))
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    if (err instanceof SyntaxError) return null
+    throw err
+  }
+}
+
+export async function saveState(key, state, configDir = defaultConfigDir()) {
+  const dir = stateDir(configDir)
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 })
+
+  const file = stateFile(key, configDir)
+  const tmp = `${file}.tmp`
+
+  await fs.writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
+  await fs.rename(tmp, file)
+}
+
+export async function markChunkDone(key, state, i, entry, configDir = defaultConfigDir()) {
+  const updated = { ...state, done: { ...state.done, [String(i)]: entry } }
+  await saveState(key, updated, configDir)
+  return updated
+}
+
+export async function clearState(key, configDir = defaultConfigDir()) {
+  try {
+    await fs.unlink(stateFile(key, configDir))
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+}

package/src/uploader.js

@@ -0,0 +1,125 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { read as readCallback } from 'node:fs'
+import { promisify } from 'node:util'
+
+import { Api } from 'telegram'
+import { readBigIntFromBuffer } from 'telegram/Helpers.js'
+
+import { DEFAULT_CONCURRENCY, PART_SIZE, MAX_PARTS } from './chunking.js'
+import { withRetry } from './retry.js'
+
+const read = promisify(readCallback)
+
+// Telegram tách hai API upload theo kích thước file: trên 10MB mới được dùng
+// nhóm "big". GramJS chọn đúng ngưỡng này (LARGE_FILE_THRESHOLD trong
+// node_modules/telegram/client/uploads.js), data-ark bám theo.
+export const LARGE_FILE_THRESHOLD = 10 * 1024 * 1024
+
+async function readExactly(fd, length, position) {
+  const buffer = Buffer.alloc(length)
+  let filled = 0
+
+  while (filled < length) {
+    const { bytesRead } = await read(fd, buffer, filled, length - filled, position + filled)
+    if (bytesRead === 0) {
+      throw new Error(`Đọc hụt: cần ${length} byte từ vị trí ${position} nhưng file đã hết.`)
+    }
+    filled += bytesRead
+  }
+
+  return buffer
+}
+
+export async function uploadRange(client, fd, options) {
+  const {
+    offset,
+    length,
+    fileName,
+    concurrency = DEFAULT_CONCURRENCY,
+    partSize = PART_SIZE,
+    onProgress,
+    retryOptions,
+  } = options
+
+  const totalParts = Math.ceil(length / partSize)
+
+  if (totalParts > MAX_PARTS) {
+    throw new Error(
+      `Dải byte này cần ${totalParts} phần, trong khi Telegram chỉ nhận tối đa 4000 phần mỗi file.`,
+    )
+  }
+
+  const isLarge = length > LARGE_FILE_THRESHOLD
+  const fileId = readBigIntFromBuffer(randomBytes(8), true, true)
+  const hash = createHash('sha256')
+
+  function partRequest(part, bytes) {
+    if (isLarge) {
+      return new Api.upload.SaveBigFilePart({
+        fileId,
+        filePart: part,
+        fileTotalParts: totalParts,
+        bytes,
+      })
+    }
+
+    return new Api.upload.SaveFilePart({ fileId, filePart: part, bytes })
+  }
+
+  for (let start = 0; start < totalParts; start += concurrency) {
+    const end = Math.min(start + concurrency, totalParts)
+    const sending = []
+    let sendError = null
+    let sendFailed = false
+    let readError = null
+
+    // Đọc tuần tự để hash đúng thứ tự, gửi song song.
+    try {
+      for (let part = start; part < end; part += 1) {
+        const partOffset = part * partSize
+        const partLength = Math.min(partSize, length - partOffset)
+        const bytes = await readExactly(fd, partLength, offset + partOffset)
+
+        hash.update(bytes)
+
+        // Gắn handler ngay lúc tạo promise, không đợi Promise.all ở cuối lô:
+        // nếu readExactly ném ở part sau, một promise đã push mà chưa ai bắt sẽ
+        // nổ thành unhandledRejection và che mất lỗi thật.
+        sending.push(
+          withRetry(() => client.invoke(partRequest(part, bytes)), retryOptions).then(
+            () => onProgress?.(partLength),
+            (err) => {
+              // Không dùng `sendError ??= err`: nếu lý do reject là falsy
+              // (undefined/null), phép gán đó vẫn set sendError = err (falsy)
+              // rồi `if (sendError)` bên dưới coi như không có lỗi — nuốt mất
+              // một lần gửi thất bại và biến nó thành "thành công" giả.
+              if (!sendFailed) {
+                sendFailed = true
+                sendError = err
+              }
+            },
+          ),
+        )
+      }
+    } catch (err) {
+      readError = err
+    }
+
+    // Mọi promise trong sending đều đã tự nuốt lỗi ở trên nên luôn resolve;
+    // await ở đây chỉ để chắc chắn không còn request nào đang bay khi ném lỗi.
+    await Promise.all(sending)
+
+    if (readError) throw readError
+    if (sendFailed) throw sendError
+  }
+
+  const inputFile = isLarge
+    ? new Api.InputFileBig({ id: fileId, parts: totalParts, name: fileName })
+    : new Api.InputFile({ id: fileId, parts: totalParts, name: fileName, md5Checksum: '' })
+
+  return {
+    inputFile,
+    sha256: hash.digest('hex'),
+    parts: totalParts,
+  }
+}