telstore 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,152 @@
+# telark
+
+Split large files into 1.8GB chunks, store them on Telegram, and restore them intact.
+
+## Quick start
+
+```bash
+npx telark login                        # once only
+npx telark config chat @my_backups      # where backups go, from now on
+npx telark data.tar                     # split it and send it there
+npx telark data.tar --to @somewhere     # somewhere else, this run only
+npx telark config                       # every setting and where its value comes from
+npx telark status                       # account, destination, unfinished backups
+npx telark list                         # what is already stored in the destination
+npx telark restore telark-20260905-7f3a91
+npx telark delete telark-20260905-7f3a91   # take it back out of the chat, for good
+```
+
+## What you need
+
+- Node.js 18 or newer.
+- An `api_id` and `api_hash` from <https://my.telegram.org> → API development tools. The `login` command asks for both, plus your phone number and the verification code.
+
+telark signs in with your own Telegram account (MTProto), not a bot. That is a hard requirement: the Bot API caps uploads at 50MB per file, while a user account gets 2GB.
+
+## Settings and flags
+
+There are two ways to say what telark should do, and they never overlap. **`config` writes;
+flags do not.** A flag applies to the run you typed it on and changes nothing on disk, so
+`--to @elsewhere` sends one backup elsewhere without moving the destination for the next one.
+
+```bash
+npx telark config                       # everything, and whether it is yours or a default
+npx telark config chat                  # one value, bare, ready to pipe
+npx telark config chunkSize 500MB       # change it for good
+npx telark config chunkSize --unset     # back to the default
+```
+
+| Setting | Flag | Default | Meaning |
+|---|---|---|---|
+| `chat` | `--to` | none | `@username`, `-100123…`, or `me`. A negative channel id works with a space or an `=`, as a flag or as a config value. |
+| `chunkSize` | `--chunk-size` | `1800MB` | e.g. `1.8GB`, `500MB`. Hard ceiling 1950MB. An unfinished backup keeps the size it started with. |
+| `concurrency` | `--concurrency` | `8` | 512KB parts sent in parallel. An integer from 1 to 64. Upload only — `restore` downloads through its own fixed pool of workers. |
+| `limit` | `--limit` | `20` | How many backups `list` shows, newest first |
+| `verbose` | `--verbose` | off | Show the Telegram client's own connection logs, hidden by default so they do not break up the progress bar |
+
+`--yes` has no setting either — it answers the confirmation `delete` asks before destroying
+a backup, and an answer stored in a file would be an answer to a question nobody heard.
+
+`--out <path>` has no setting: it names where one particular restore should write, and
+defaults to the basename in the manifest. Relative paths resolve against the current directory.
+
+`config` reads and writes only settings — the `api_id`, `api_hash` and session that `login`
+stores in the same file are not reachable from it. A value is checked before it is written,
+so `config chunkSize 9GB` is refused there and then rather than at the start of a long upload.
+
+## What the chat looks like
+
+Every chunk goes up as a document captioned `📦 <backupId> · 3/12`, and the manifest that
+follows carries a summary card:
+
+```
+🗄 data.tar
+━━━━━━━━━━━━━━━
+💾 21.4 GB · 12 chunks
+🆔 telark-20260905-7f3a91
+📅 2026-09-05 16:40 UTC
+
+↩ npx telark restore telark-20260905-7f3a91
+#telark
+```
+
+`npx telark list` reads those cards straight out of the chat — one search, no downloads —
+and lays them out as a table:
+
+```
+Destination  https://web.telegram.org/k/#@my_backups
+
+BACKUP ID               FILE            SIZE  CHUNKS  CREATED
+telark-20260905-7f3a91  data.tar     21.4 GB      12  2026-09-05
+telark-20260901-9de447  photos.zip  940.3 MB       1  2026-09-01
+
+2 backups. Restore with: npx telark restore <backup-id>
+```
+
+A backup uploaded before the card existed still gets a row, with dashes where the caption
+says nothing — `list` reports what the chat holds and never fills gaps with guesses.
+
+## How it works
+
+Every run mints a `backupId`. The file is read directly by offset — no temporary copies — and uploaded as documents named `<backupId>.partNNNN`. Once every chunk is up, telark sends a JSON manifest listing the message id and sha256 of each one. Restore needs only the `backupId`: it finds the manifest in the chat, downloads each chunk to its exact position in a `.partial` file, checks every chunk's sha256 and size, and renames it to the real file only after *all* chunks match.
+
+If the connection drops during an **upload**, just run the same command again — progress lives in `~/.telark/state/` and finished chunks are skipped, keeping the same `backupId`. Two things to know about rerunning:
+
+- Running again against a destination that differs from the one in the unfinished progress makes telark **refuse to run** rather than silently redirect — one backup cannot be split across two destinations. The error names the chat to pass as `--to` to carry on, or the state file to delete to start a new backup. It reads the same whether the mismatch came from a flag or from your configured `chat`.
+- Running again **without** `--chunk-size` resumes at the size the backup started with, whatever your configured `chunkSize` says today. A setting is what to use when nobody asks for anything; it is not somebody asking.
+- Running again **with** a `--chunk-size` that differs from that size makes telark **refuse to run**: the chunks already in the chat were cut that way and cannot be re-cut. Drop the flag to carry on, or delete the state file to start a new backup — which leaves the chunks already sent in the chat with nothing pointing at them.
+
+`Ctrl-C` during an upload names the backup it was working on, so `telark status` and a later `restore` have something to go on. telark keeps the **20 most recent** unfinished backups in `~/.telark/state/`; starting a new one past that drops the oldest record and says which id it dropped. Only the local record goes — the chunks that backup sent stay in the chat, searchable by that id, but it can no longer be resumed.
+
+**Restore keeps no state to resume from.** Pressing `Ctrl-C` mid-restore saves nothing — running again starts over.
+
+## Deleting a backup
+
+```bash
+npx telark delete telark-20260905-7f3a91
+```
+
+It prints what it is about to destroy, asks once, and then removes every chunk message and
+the manifest from the chat and drops the local record if there is one. `--yes` skips the
+question. **There is no undo** — Telegram is the only copy.
+
+It also works on a backup that never finished: those have chunks in the chat but no manifest,
+so `list` cannot see them and only `status` knows they exist. `delete` reads the local record
+instead and clears both.
+
+The chunks go first and the manifest goes last, deliberately. The manifest is the only list
+of the message ids, so if a delete is interrupted — Ctrl-C, a dropped connection — running
+the same command again finds that list still there and finishes the job. Telegram says
+nothing about an id that is already gone, so a second run costs nothing. In between the two
+runs the backup still shows up in `list`, and a `restore` of it fails loudly rather than
+handing over a partial file.
+
+Two things it refuses rather than guesses at: a manifest whose body names a *different*
+backup (a file renamed in the chat — its message ids point at somebody else's chunks), and a
+manifest or local record giving a message id that is not a whole positive number. Neither
+deletes anything at all. A manifest too damaged for `restore` to use *can* still be deleted —
+that is usually the one you want gone.
+
+## Limits worth knowing
+
+- A chunk cannot exceed 1950MB: Telegram accepts at most 4000 parts of 512KB per file, an arithmetic ceiling of about 1953MB, and telark stops at 1950MB to leave a safety margin.
+- The data is **not** encrypted. Don't upload anything you would mind sitting on someone else's infrastructure.
+- Deleting a chunk message on Telegram destroys the backup, with no way to recover it. Use `npx telark delete <backup-id>` when that is what you actually want.
+- Keep the `backupId`. Without it you have to hunt for the manifest in the chat by hand.
+
+## Where the config lives
+
+`~/.telark/config.json` (mode 600) holds `apiId`, `apiHash` and the session at the top level, with everything `config` manages under `settings`:
+
+```json
+{
+  "apiId": 123456,
+  "apiHash": "…",
+  "session": "…",
+  "settings": { "chat": "@my_backups", "chunkSize": 524288000 }
+}
+```
+
+Editing it by hand is fine, and a value that cannot be used is named on the next run — with the file and the key, never with a flag you did not type.
+
+`npx telark logout` **only deletes the locally stored session** and keeps the rest — the session is still alive on Telegram's side. To revoke access for good, open Telegram → Settings → Devices (Active sessions) and terminate that session.

package/bin/telark.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { route, HELP, interruptMessage } from '../src/cli.js'
+import { runLogin } from '../src/commands/login.js'
+import { runConfig } from '../src/commands/config.js'
+import { runDelete } from '../src/commands/delete.js'
+import { runList } from '../src/commands/list.js'
+import { runLogout } from '../src/commands/logout.js'
+import { runRestore } from '../src/commands/restore.js'
+import { runStatus } from '../src/commands/status.js'
+import { runUpload } from '../src/commands/upload.js'
+
+const SIGINT_EXIT_CODE = 130
+
+// Which command is running when Ctrl-C arrives — each one tells a different truth
+// about whether progress was saved, so we need to know which to pick the right line.
+// The backup id arrives a moment later, once upload knows which backup this run is.
+let currentCommand = null
+let currentBackupId = null
+
+process.on('SIGINT', () => {
+  process.stderr.write(interruptMessage(currentCommand, { backupId: currentBackupId }))
+  process.exit(SIGINT_EXIT_CODE)
+})
+
+async function main() {
+  let parsed
+
+  try {
+    parsed = route(process.argv.slice(2))
+  } catch (err) {
+    process.stderr.write(`Error: ${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({ verbose: Boolean(parsed.options.verbose) })
+      return
+
+    case 'logout':
+      await runLogout()
+      return
+
+    case 'list':
+      await runList(parsed.options)
+      return
+
+    case 'status':
+      await runStatus(parsed.options)
+      return
+
+    case 'config':
+      await runConfig(parsed.args, parsed.options)
+      return
+
+    case 'upload':
+      await runUpload(parsed.args[0], parsed.options, {
+        onBackupId: (id) => {
+          currentBackupId = id
+        },
+      })
+      return
+
+    case 'restore':
+      if (!parsed.args[0]) {
+        throw new Error('Missing backup id. Example: npx telark restore telark-20260905-7f3a91')
+      }
+      await runRestore(parsed.args[0], parsed.options)
+      return
+
+    case 'delete':
+      if (!parsed.args[0]) {
+        throw new Error('Missing backup id. Example: npx telark delete telark-20260905-7f3a91')
+      }
+      await runDelete(parsed.args[0], parsed.options)
+      return
+
+    default:
+      throw new Error(`Unknown command: ${parsed.command}`)
+  }
+}
+
+// GramJS keeps "exported senders" around together with a 30-second timer to release
+// them, and neither client.disconnect() nor destroy() cleans them up: both of those
+// maps are Maps, but the code walks them with Object.values and so misses everything.
+// The result is a command that prints "Done" and then hangs for another ~30 seconds,
+// during which Ctrl-C falsely reports that nothing was saved. Finish the work, exit.
+function exitWhenFlushed(code) {
+  // The empty writes exist only to borrow their callbacks: they fire after everything
+  // queued earlier has flushed, so nothing is lost when stdout/stderr is not a TTY.
+  let pending = 2
+
+  const done = () => {
+    pending -= 1
+    if (pending === 0) process.exit(code)
+  }
+
+  // Safety net: exit anyway if a callback never arrives (the pipe is already closed).
+  setTimeout(() => process.exit(code), 2000).unref()
+
+  process.stdout.write('', done)
+  process.stderr.write('', done)
+}
+
+main().then(
+  () => {
+    exitWhenFlushed(process.exitCode ?? 0)
+  },
+  (err) => {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exitCode = 1
+    exitWhenFlushed(1)
+  },
+)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "telstore",
+  "version": "0.1.0",
+  "description": "Split large files into chunks and store them on Telegram",
+  "keywords": [
+    "telegram",
+    "backup",
+    "chunk",
+    "split",
+    "restore",
+    "cli",
+    "mtproto"
+  ],
+  "homepage": "https://github.com/shovity/telark#readme",
+  "bugs": {
+    "url": "https://github.com/shovity/telark/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shovity/telark.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "author": "shovity",
+  "bin": {
+    "telark": "bin/telark.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'"
+  },
+  "dependencies": {
+    "telegram": "^2.26.22"
+  }
+}

package/src/caption.js

@@ -0,0 +1,63 @@
+import { formatBytes } from './progress.js'
+
+// Captions are plain text on purpose. Telegram would render bold through a parse mode,
+// but that turns every file name into something that has to be escaped correctly, and
+// the fake client the tests talk to would never notice a mistake there.
+
+const DIVIDER = '━'.repeat(15)
+
+// The hashtag is what `list` searches for, and it lives on the manifest alone: chunk
+// captions stay out of that search so a twelve-chunk backup is one hit, not thirteen.
+export const MANIFEST_TAG = '#telark'
+
+// A file name may legally contain a newline or a tab, and either one would push the
+// rest of the card down a row and take its shape apart.
+function oneLine(name) {
+  return String(name).replace(/\s+/g, ' ').trim()
+}
+
+function utcMinutes(createdAt) {
+  return `${new Date(createdAt).toISOString().slice(0, 16).replace('T', ' ')} UTC`
+}
+
+export function chunkCaption({ id, number, total }) {
+  return `📦 ${id} · ${number}/${total}`
+}
+
+export function manifestCaption({ id, name, size, chunks, createdAt }) {
+  return [
+    `🗄 ${oneLine(name)}`,
+    DIVIDER,
+    `💾 ${formatBytes(size)} · ${chunks} chunk${chunks === 1 ? '' : 's'}`,
+    `🆔 ${id}`,
+    `📅 ${utcMinutes(createdAt)}`,
+    '',
+    `↩ npx telark restore ${id}`,
+    MANIFEST_TAG,
+  ].join('\n')
+}
+
+function marker(lines, emoji) {
+  const found = lines.find((line) => line.startsWith(`${emoji} `))
+  return found ? found.slice(emoji.length + 1).trim() : null
+}
+
+// list reads what the chat shows, and a caption is text a person can edit. Anything that
+// does not carry the whole card is reported as unknown rather than half-guessed: a backup
+// listed with invented numbers is worse than one listed with dashes.
+export function parseManifestCaption(text) {
+  const lines = String(text ?? '').split('\n')
+
+  const name = marker(lines, '🗄')
+  const totals = marker(lines, '💾')
+  const id = marker(lines, '🆔')
+  const createdAt = marker(lines, '📅')
+
+  if (!name || !totals || !id || !createdAt) return null
+
+  const match = /^(.+) · (\d+) chunks?$/.exec(totals)
+
+  if (!match) return null
+
+  return { id, name, size: match[1], chunks: Number(match[2]), createdAt }
+}

package/src/chat.js

@@ -0,0 +1,42 @@
+// How telark talks about a destination. None of this touches Telegram — it is string
+// handling around a target the user typed — so it lives apart from the client that does.
+
+export function normalizeChatTarget(input) {
+  const text = String(input).trim()
+
+  if (text === '') {
+    throw new Error('Destination must not be empty.')
+  }
+
+  if (/^-?\d+$/.test(text)) {
+    return Number(text)
+  }
+
+  return text
+}
+
+// Telegram's web client addresses a chat by putting the raw target in the fragment, which
+// covers both a negative channel id and an @username. Saved Messages is the exception: it
+// is reached by the account's own id, which telark does not know, so it gets no link
+// rather than a guessed one that lands somewhere else.
+export function chatUrl(chat) {
+  const text = String(chat)
+
+  if (text === 'me') return null
+
+  return `https://web.telegram.org/k/#${text}`
+}
+
+// How a destination is spoken about. "me" is a target, not a name someone would recognise
+// in a sentence, so every command that mentions a chat in prose goes through here.
+export function chatName(chat) {
+  return String(chat) === 'me' ? 'Saved Messages' : String(chat)
+}
+
+// A destination is worth more as something clickable than as a raw id, but Saved Messages
+// has no link to give, so it is named instead of being dressed up as one.
+export function describeChat(chat) {
+  const url = chatUrl(chat)
+
+  return url ?? `${chat} (${chatName(chat)})`
+}

package/src/chunking.js

@@ -0,0 +1,92 @@
+export const PART_SIZE = 512 * 1024
+export const MAX_PARTS = 4000
+
+// One slice is one short iterDownload stream. Small enough that a failed slice costs little
+// and that there are far more slices than workers for the pool to balance across; big enough
+// that the per-stream setup disappears against 16 parts of payload.
+export const SLICE_SIZE = 8 * 1024 * 1024
+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
+
+// Every chunk is one message in the chat and one entry in the manifest, so a plan this long
+// describes a backup nobody could use. At the 1950MB ceiling it allows a 19TB file; the only
+// way to reach it is a chunk size picked by mistake, and reaching it by mistake means asking
+// the loop below for billions of objects — an out-of-memory crash rather than an answer.
+export const MAX_CHUNKS = 10_000
+
+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(`Invalid size: "${input}". Valid examples: 1800MB, 1.8GB, 524288.`)
+  }
+
+  const bytes = Math.floor(Number(match[1]) * UNITS[match[2] ?? 'b'])
+
+  if (bytes <= 0) {
+    throw new Error('Size must be greater than 0.')
+  }
+
+  if (bytes > MAX_CHUNK_SIZE) {
+    throw new Error(
+      'Maximum chunk size is 1950MB. Telegram accepts only 4000 parts of 512KB per file, ' +
+        'an arithmetic ceiling of about 1953MB, so a safety margin is needed.',
+    )
+  }
+
+  return bytes
+}
+
+// How many chunks a file of this size splits into. planChunks builds them and parseManifest
+// checks them against this same rule, so the layout has one definition, not three.
+export function countChunks(fileSize, chunkSize) {
+  return Math.ceil(fileSize / chunkSize)
+}
+
+export function planChunks(fileSize, chunkSize) {
+  if (fileSize <= 0) {
+    throw new Error('File is empty, nothing to upload.')
+  }
+
+  // `offset += chunkSize` has to advance or the loop below never reaches fileSize. Anything
+  // that is not a whole number above zero either stands still or walks backwards, and the
+  // caller gets a process that spins until it runs out of memory instead of an error. This
+  // is reachable: an upload resuming from a state file takes chunkSize straight off disk.
+  if (!Number.isSafeInteger(chunkSize) || chunkSize < 1) {
+    throw new Error(
+      `Chunk size must be a whole number of bytes above zero, got: ${JSON.stringify(chunkSize)}.`,
+    )
+  }
+
+  if (!Number.isSafeInteger(fileSize)) {
+    throw new Error(`File size must be a whole number of bytes, got: ${JSON.stringify(fileSize)}.`)
+  }
+
+  // Counted before anything is built, so an impossible plan costs no memory.
+  const count = countChunks(fileSize, chunkSize)
+
+  if (count > MAX_CHUNKS) {
+    throw new Error(
+      `Splitting ${fileSize} bytes into ${chunkSize}-byte chunks needs ${count} chunks, ` +
+        `and a backup holds at most ${MAX_CHUNKS} chunks.`,
+    )
+  }
+
+  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
+}