telstore 0.1.5 → 0.1.7

package/README.md

@@ -1,78 +1,71 @@
 # telstore
 
-Split large files into 1.8GB chunks, store them on Telegram, and restore them intact.
+Split large files into chunks, store them on Telegram, and restore them byte-for-byte.
+
+telstore signs in with your own Telegram account over MTProto, not a bot: the Bot API caps
+uploads at 50MB per file, a user account gets 2GB.
+
+Needs Node.js 18+ and an `api_id`/`api_hash` from <https://my.telegram.org> → API
+development tools; `login` asks for those, your phone number and the verification code.
 
 ## Quick start
 
 ```bash
-npx telstore login                        # once only
-npx telstore config chat @my_backups      # where backups go, from now on
-npx telstore data.tar                     # split it and send it there
-npx telstore data.tar --to @somewhere     # somewhere else, this run only
-npx telstore config                       # every setting and where its value comes from
-npx telstore status                       # account, destination, unfinished backups
-npx telstore list                         # what is already stored in the destination
+npx telstore login                             # once only
+npx telstore config chat @my_backups           # where backups go, from now on
+npx telstore data.tar                          # split it and send it there
+npx telstore a.tar b.tar c.tar                 # or several: one backup each, one after another
+npx telstore ./backups                         # or a folder: every file one level inside it
+npx telstore list                              # what is already in the destination
 npx telstore restore telstore-20260905-7f3a91
-npx telstore delete telstore-20260905-7f3a91   # take it back out of the chat, for good
-npx telstore token                        # a session token for a machine you do not trust
 ```
 
-## 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.
+## Commands
 
-telstore 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.
+| Command | What it does |
+|---|---|
+| `telstore login` | Log in to Telegram. Add `--token` to log in with a session token instead. |
+| `telstore <file\|folder\|pattern>...` | Split each file and upload it. Prints the `backupId` you restore with. |
+| `telstore list` | The backups stored in the destination, newest first. |
+| `telstore restore <backup-id>...` | Download every chunk and reassemble the file. Several ids run one after another. |
+| `telstore delete <backup-id>...` | Remove a backup's chunks and manifest from the chat, for good. Several ids are listed and confirmed once. |
+| `telstore status` | Account, destination, and unfinished backups. |
+| `telstore config` | Show or change settings. |
+| `telstore token` | Print a session token for a machine you do not trust. |
+| `telstore logout` | Remove the locally stored session. |
 
-## Settings and flags
+## Settings
 
-There are two ways to say what telstore 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.
+`config` writes; flags do not. A flag applies to the run you typed it on and changes nothing
+on disk, so `--chat @elsewhere` sends one backup elsewhere without moving the destination for
+the next one.
 
 ```bash
-npx telstore config                       # everything, and whether it is yours or a default
-npx telstore config chat                  # one value, bare, ready to pipe
-npx telstore config chunkSize 500MB       # change it for good
-npx telstore config chunkSize --unset     # back to the default
+npx telstore config                    # every setting, and whether it is yours or a default
+npx telstore config chunkSize 500MB    # change it for good
+npx telstore 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. |
-| `uploadConcurrency` | `--upload-concurrency` | `32` | 512KB parts sent in parallel while uploading. An integer from 1 to 64. |
-| `downloadConcurrency` | `--download-concurrency` | `8` | 8MB slices fetched in parallel while restoring. An integer from 1 to 64. |
-| `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.
+| `chat` | `--chat` | none | `@username`, `-100123…`, or `me` |
+| `chunkSize` | `--chunk-size` | `1800MB` | e.g. `1.8GB`, `500MB`. Ceiling 1950MB. |
+| `uploadConcurrency` | `--upload-concurrency` | `32` | 512KB parts in parallel while uploading, 1–64 |
+| `downloadConcurrency` | `--download-concurrency` | `8` | 8MB slices in parallel while restoring, 1–64 |
+| `limit` | `--limit` | `20` | How many backups `list` shows |
+| `verbose` | `--verbose` | off | Show the Telegram client's own connection logs |
+
+Three flags have no setting behind them: `--out <path>` names where one restore writes,
+`--yes` skips the confirmation an upload batch and `delete` ask for, and `--token` takes no
+value — a token written
+on the command line would sit in `ps` and in that machine's shell history, so it is pasted at
+a prompt that does not echo.
 
 ## 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
-🆔 telstore-20260905-7f3a91
-📅 2026-09-05 16:40 UTC
-
-↩ npx telstore restore telstore-20260905-7f3a91
-#telstore
-```
-
-`npx telstore list` reads those cards straight out of the chat — one search, no downloads —
-and lays them out as a table:
+Every chunk goes up as a document captioned `📦 <backupId> · 3/12`, followed by a manifest
+carrying a summary card — file name, size, id, date and the restore command. `list` reads
+those cards straight out of the chat, one search and no downloads:
 
 ```
 Destination  https://web.telegram.org/k/#@my_backups
@@ -84,141 +77,109 @@ telstore-20260901-9de447  photos.zip  940.3 MB       1  2026-09-01
 2 backups. Restore with: npx telstore 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, telstore 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 `~/.telstore/state/` and finished chunks are skipped, keeping the same `backupId`. Two things to know about rerunning:
+## Several files at once
 
-- Running again against a destination that differs from the one in the unfinished progress makes telstore **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 telstore **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.
+`telstore a.tar b.tar c.tar` uploads them one after another over a single connection. Each
+file becomes its own backup with its own `backupId`, exactly as three separate runs would
+have produced.
 
-`Ctrl-C` during an upload names the backup it was working on, so `telstore status` and a later `restore` have something to go on. telstore keeps the **20 most recent** unfinished backups in `~/.telstore/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
+A **folder** stands for the files one level inside it — subfolders are named on screen and
+left alone, hidden files are skipped. A **pattern** stands for the names it matches:
 
 ```bash
-npx telstore delete telstore-20260905-7f3a91
+npx telstore ./backups            # every file directly inside ./backups
+npx telstore 'logs/*.tar'         # quoted, so telstore matches it rather than the shell
+npx telstore logs/abc*            # unquoted: your shell expands it first, same result
 ```
 
-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.
+More than one file is listed, added up and confirmed before the first byte goes out:
 
-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.
+```
+3 files, 4.20 GB, to https://web.telegram.org/k/#@my_backups
 
-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.
+  a.tar  1.20 GB
+  b.tar  2.00 GB
+  c.tar  1.00 GB
 
-## Running on a machine you do not trust
+Upload these 3 files? [y/N]
+```
 
-`login` leaves your Telegram session on the machine you run it on, in plain text. When that
-machine is not yours, print a **session token** on one that is and log in with that instead:
+`--yes` skips the question; without a terminal to ask in, the run stops and says so rather
+than reading an empty line as "no". Names that do not exist, and a file named twice, are
+refused before anything is sent; a file that fails mid-transfer does not stop the ones after
+it, and the run ends with a line per file and a non-zero exit code:
 
-```bash
-# on the machine you are already logged in on
-npx telstore token                        # asks for a passphrase, twice
-                                          # prints one line: tls1.…
+```
+3 files: 2 uploaded, 1 failed.
 
-# on the other machine
-npx telstore login --token                # paste the token, then type the passphrase
-npx telstore restore telstore-20260905-7f3a91
-npx telstore logout                       # when you are done
+  a.tar  telstore-20260905-7f3a91  (12 chunks)
+  b.tar  failed: connection dropped mid-transfer
+  c.tar  telstore-20260905-9de447  (1 chunk)
 ```
 
-The token holds your `api_id`, `api_hash`, session and settings, encrypted with the
-passphrase (AES-256-GCM, key derived with scrypt). It is one line of base64url, so it
-survives a chat message, an email or a QR code — and a copy that leaks without the
-passphrase is not enough to use your account.
+## Several backups at once
 
-`login --token` stores the token exactly as it arrived, so **the session never exists on that
-machine in a form anyone can read**. Every command that talks to Telegram asks for the
-passphrase and opens it in memory:
+`restore` and `delete` take a list of ids the same way, over one connection, with a summary
+and a non-zero exit code if any of them failed:
 
-```json
-{ "sealed": "tls1.…", "settings": { "chat": "@my_backups" } }
+```bash
+npx telstore restore telstore-20260905-7f3a91 telstore-20260901-9de447
+npx telstore delete telstore-20260905-7f3a91 telstore-20260901-9de447
 ```
 
-`npx telstore status` shows which of the two you are running:
+With several ids, `restore` writes each file under the name in its own manifest, so `--out`
+— which names exactly one file — is refused rather than quietly used three times. `delete`
+looks every id up first and shows the whole list before asking once; an id that is nowhere to
+be found stops the run before anything is destroyed.
 
-```
-Session      /home/you/.telstore/config.json (sealed — opened with a passphrase)
-Account      Sho (@shovity)
-Destination  https://web.telegram.org/k/#@my_backups
-Unfinished   none
-```
+## Resuming an upload
 
-### What is left behind
-
-- **No readable session.** `logout` removes the sealed blob, and with it the `api_hash`,
-  which lives inside it.
-- **State files, yes.** An upload writes `~/.telstore/state/<key>.json` so it can be resumed
-  after an interruption. It holds the file path, the chunk sizes and the message ids — no
-  secret — and losing it would strand chunks in the chat with nothing able to name them.
-
-### Things worth knowing before you use one
-
-- **`--token` takes no value, on purpose.** A token written on the command line would sit in
-  `ps` for the whole life of the command and stay in that machine's shell history afterwards.
-  It is pasted at a prompt that does not echo it.
-- **The passphrase may be left empty**, and then the token says so on its face: it starts
-  `tls0.` instead of `tls1.`, `token` warns, and `login` stores the session in plain text
-  exactly as an ordinary login would. telstore will not write a file that looks encrypted and
-  is not.
-- **telstore cannot take a token back.** There is no expiry and no revocation. Like `logout`,
-  it says nothing to Telegram — to end the session for good, open Telegram → Settings →
-  Devices (Active sessions) and terminate it. Every copy of the token dies with it.
-- **A wrong passphrase and a damaged token are the same event** to AES-GCM: one failed
-  authentication check. telstore names both possibilities rather than guessing which it was.
+Progress lives in `~/.telstore/state/` (the 20 most recent), so running the same command
+again skips the finished chunks and keeps the same `backupId`. A resumed backup keeps the
+chunk size it started with; passing a `--chunk-size` or a destination that differs from its
+own makes telstore refuse to run rather than re-cut or redirect it silently.
 
-## Limits worth knowing
+After a batch, run telstore again with **only the files that are left**: the finished ones
+have had their records cleared, so repeating the whole command would upload them a second
+time as new backups. `npx telstore status` lists what is unfinished.
 
-- A chunk cannot exceed 1950MB: Telegram accepts at most 4000 parts of 512KB per file, an arithmetic ceiling of about 1953MB, and telstore 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. The one thing telstore does encrypt is a session token, and that protects your login rather than your files.
-- Deleting a chunk message on Telegram destroys the backup, with no way to recover it. Use `npx telstore 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.
+**Restore keeps no state** — `Ctrl-C` mid-restore saves nothing, running again starts over.
+And `delete` has **no undo**: Telegram is the only copy.
 
-## Where the config lives
+## Running on a machine you do not trust
 
-`~/.telstore/config.json` (mode 600) holds `apiId`, `apiHash` and the session at the top level, with everything `config` manages under `settings`:
+`login` leaves your session on disk in plain text. When the machine is not yours, print a
+**session token** on one that is and log in with that instead:
 
-```json
-{
-  "apiId": 123456,
-  "apiHash": "…",
-  "session": "…",
-  "settings": { "chat": "@my_backups", "chunkSize": 524288000 }
-}
+```bash
+npx telstore token          # on your own machine: asks for a passphrase, prints one line
+npx telstore login --token  # on the other one: paste the token, then the passphrase
+npx telstore logout         # when you are done
 ```
 
-A machine logged in with `npx telstore login --token` holds `sealed` instead of those three
-fields, and nothing else about the account:
+The token holds your `api_id`, `api_hash`, session and settings, encrypted with the
+passphrase (AES-256-GCM, scrypt), as one line of base64url that survives a chat message or a
+QR code. `login --token` stores it exactly as it arrived and every command asks for the
+passphrase, so the session never exists on that machine in readable form.
 
-```json
-{ "sealed": "tls1.…", "settings": { "chat": "@my_backups" } }
-```
+There is no expiry and no revocation: to end a session for good, terminate it under Telegram
+→ Settings → Devices. An empty passphrase is allowed, and then the token says so on its face
+— it starts `tls0.` and `login` stores the session in plain text.
+
+## Limits worth knowing
+
+- **Your data is not encrypted.** Don't upload anything you would mind sitting on someone
+  else's infrastructure — the one thing telstore encrypts is a session token, and that
+  protects your login rather than your files.
+- A chunk cannot exceed 1950MB: Telegram accepts at most 4000 parts of 512KB per file.
+- Deleting a chunk message in the Telegram app destroys the backup, and keeping the
+  `backupId` is what saves you hunting for its manifest in the chat by hand.
 
-A file holding both shapes is refused rather than guessed at — there would be no way to know
-which account was meant.
+Settings and credentials live in `~/.telstore/config.json`, mode 600 — `apiId`, `apiHash` and
+the session at the top level (or a single `sealed` blob after `login --token`), everything
+`config` manages under `settings`. Editing it by hand is fine: a value that cannot be used is
+named on the next run, with the file and the key.
 
-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.
+## License
 
-`npx telstore 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.
+MIT

package/bin/telstore.js

@@ -14,12 +14,18 @@ const SIGINT_EXIT_CODE = 130
 let currentCommand = null
 let currentBackupId = null
 
+// A batch clears each finished file's record as it goes, so by the time Ctrl-C lands these
+// are backups no second run should touch. Ctrl-C needs their names to say so.
+const finishedUploads = []
+
 process.on('SIGINT', () => {
   // A passphrase prompt has stdin in raw mode, and process.exit skips readline's own cleanup.
   // Without this, Ctrl-C hands back a shell that no longer echoes what is typed into it.
   if (process.stdin.isTTY) process.stdin.setRawMode(false)
 
-  process.stderr.write(interruptMessage(currentCommand, { backupId: currentBackupId }))
+  process.stderr.write(
+    interruptMessage(currentCommand, { backupId: currentBackupId, done: finishedUploads }),
+  )
   process.exit(SIGINT_EXIT_CODE)
 })
 
@@ -88,13 +94,23 @@ async function main() {
     }
 
     case 'upload': {
-      const { runUpload } = await import('../src/commands/upload.js')
+      const { runUploads } = await import('../src/commands/upload.js')
 
-      await runUpload(parsed.args[0], parsed.options, {
+      const { failed } = await runUploads(parsed.args, parsed.options, {
+        // Only route saw the command line, and an unquoted note is told apart from a plain
+        // missing file by where the words sat on it.
+        filesAfterNote: parsed.filesAfterNote,
         onBackupId: (id) => {
           currentBackupId = id
         },
+        onFileDone: (file) => {
+          if (file.id) finishedUploads.push(file)
+        },
       })
+
+      // A batch reports its own failures by name and has already said so on stdout; the exit
+      // code is what carries that out to whatever ran telstore.
+      if (failed > 0) process.exitCode = 1
       return
     }
 
@@ -103,9 +119,11 @@ async function main() {
         throw new Error('Missing backup id. Example: npx telstore restore telstore-20260905-7f3a91')
       }
 
-      const { runRestore } = await import('../src/commands/restore.js')
+      const { runRestores } = await import('../src/commands/restore.js')
 
-      await runRestore(parsed.args[0], parsed.options)
+      const { failed } = await runRestores(parsed.args, parsed.options)
+
+      if (failed > 0) process.exitCode = 1
       return
     }
 
@@ -114,9 +132,11 @@ async function main() {
         throw new Error('Missing backup id. Example: npx telstore delete telstore-20260905-7f3a91')
       }
 
-      const { runDelete } = await import('../src/commands/delete.js')
+      const { runDeletes } = await import('../src/commands/delete.js')
+
+      const { failed } = await runDeletes(parsed.args, parsed.options)
 
-      await runDelete(parsed.args[0], parsed.options)
+      if (failed > 0) process.exitCode = 1
       return
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telstore",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Split large files into chunks and store them on Telegram",
   "keywords": [
     "telegram",

package/src/caption.js

@@ -14,6 +14,37 @@ function oneLine(name) {
   return String(name).replace(/\s+/g, ' ').trim()
 }
 
+// Telegram takes 1024 characters in a caption, and the card around the note already spends
+// some of them — a file name alone may be 255. 500 leaves both room to spare.
+export const MAX_NOTE_LENGTH = 500
+
+// A note is written at a shell prompt and read in two places: the manifest body and the card
+// in the chat. Folding it here, once, is what keeps those two from holding slightly different
+// notes and leaving nobody able to say which one was typed.
+export function parseNote(raw) {
+  if (raw === undefined || raw === null) return null
+
+  const note = oneLine(raw)
+
+  if (note === '') {
+    throw new Error(
+      '--note is empty. Write the note itself, or leave the flag off — a backup with a blank ' +
+        'note is one telstore had something to say about and did not.',
+    )
+  }
+
+  if (note.length > MAX_NOTE_LENGTH) {
+    throw new Error(
+      `--note is ${note.length} characters, and a caption has only room for ${MAX_NOTE_LENGTH} ` +
+        'once the rest of the card has had its share. Shorten it: telstore will not cut it ' +
+        'short by itself, because half a note read as a whole one is exactly the kind of ' +
+        'plausible wrong answer this tool exists to refuse.',
+    )
+  }
+
+  return note
+}
+
 function utcMinutes(createdAt) {
   return `${new Date(createdAt).toISOString().slice(0, 16).replace('T', ' ')} UTC`
 }
@@ -22,12 +53,15 @@ export function chunkCaption({ id, number, total }) {
   return `📦 ${id} · ${number}/${total}`
 }
 
-export function manifestCaption({ id, name, size, chunks, createdAt }) {
+export function manifestCaption({ id, name, size, chunks, createdAt, note = null }) {
   return [
-    `🗄 ${oneLine(name)}`,
+    `📄 ${oneLine(name)}`,
     `💾 ${formatBytes(size)} · ${chunks} chunk${chunks === 1 ? '' : 's'}`,
     `🆔 ${id}`,
     `📅 ${utcMinutes(createdAt)}`,
+    // Below the facts telstore knows, above the line that says how to get the file back:
+    // the note is the one part of the card a person wrote, so it reads last of the four.
+    ...(note ? [`📝 ${oneLine(note)}`] : []),
     '',
     `↩ npx telstore restore ${id}`,
     MANIFEST_TAG,
@@ -45,16 +79,20 @@ function marker(lines, emoji) {
 export function parseManifestCaption(text) {
   const lines = String(text ?? '').split('\n')
 
-  const name = marker(lines, '🗄')
+  const name = marker(lines, '📄')
   const totals = marker(lines, '💾')
   const id = marker(lines, '🆔')
   const createdAt = marker(lines, '📅')
 
+  // Every card telstore wrote before --note existed is a complete card, so the note is the
+  // one marker whose absence means "there is no note" rather than "this is not a card".
+  const note = 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 }
+  return { id, name, size: match[1], chunks: Number(match[2]), createdAt, note }
 }