telstore 0.1.0 → 0.1.2

package/README.md

@@ -1,19 +1,20 @@
-# telark
+# telstore
 
 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
+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 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
@@ -21,26 +22,27 @@ npx telark delete telark-20260905-7f3a91   # take it back out of the chat, for g
 - 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.
+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.
 
 ## Settings and flags
 
-There are two ways to say what telark should do, and they never overlap. **`config` writes;
+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.
 
 ```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
+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
 ```
 
 | 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. |
+| `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 |
 
@@ -63,24 +65,24 @@ follows carries a summary card:
 🗄 data.tar
 ━━━━━━━━━━━━━━━
 💾 21.4 GB · 12 chunks
-🆔 telark-20260905-7f3a91
+🆔 telstore-20260905-7f3a91
 📅 2026-09-05 16:40 UTC
 
-↩ npx telark restore telark-20260905-7f3a91
-#telark
+↩ npx telstore restore telstore-20260905-7f3a91
+#telstore
 ```
 
-`npx telark list` reads those cards straight out of the chat — one search, no downloads —
+`npx telstore 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
+BACKUP ID                 FILE            SIZE  CHUNKS  CREATED
+telstore-20260905-7f3a91  data.tar     21.4 GB      12  2026-09-05
+telstore-20260901-9de447  photos.zip  940.3 MB       1  2026-09-01
 
-2 backups. Restore with: npx telark restore <backup-id>
+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
@@ -88,22 +90,22 @@ says nothing — `list` reports what the chat holds and never fills gaps with gu
 
 ## 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.
+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 `~/.telark/state/` and finished chunks are skipped, keeping the same `backupId`. Two things to know about rerunning:
+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:
 
-- 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 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 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.
+- 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.
 
-`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.
+`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
 
 ```bash
-npx telark delete telark-20260905-7f3a91
+npx telstore delete telstore-20260905-7f3a91
 ```
 
 It prints what it is about to destroy, asks once, and then removes every chunk message and
@@ -127,16 +129,77 @@ manifest or local record giving a message id that is not a whole positive number
 deletes anything at all. A manifest too damaged for `restore` to use *can* still be deleted —
 that is usually the one you want gone.
 
+## Running on a machine you do not trust
+
+`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:
+
+```bash
+# on the machine you are already logged in on
+npx telstore token                        # asks for a passphrase, twice
+                                          # prints one line: tls1.…
+
+# 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
+```
+
+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.
+
+`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:
+
+```json
+{ "sealed": "tls1.…", "settings": { "chat": "@my_backups" } }
+```
+
+`npx telstore status` shows which of the two you are running:
+
+```
+Session      /home/you/.telstore/config.json (sealed — opened with a passphrase)
+Account      Sho (@shovity)
+Destination  https://web.telegram.org/k/#@my_backups
+Unfinished   none
+```
+
+### 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.
+
 ## 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.
+- 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.
 
 ## 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`:
+`~/.telstore/config.json` (mode 600) holds `apiId`, `apiHash` and the session at the top level, with everything `config` manages under `settings`:
 
 ```json
 {
@@ -147,6 +210,16 @@ that is usually the one you want gone.
 }
 ```
 
+A machine logged in with `npx telstore login --token` holds `sealed` instead of those three
+fields, and nothing else about the account:
+
+```json
+{ "sealed": "tls1.…", "settings": { "chat": "@my_backups" } }
+```
+
+A file holding both shapes is refused rather than guessed at — there would be no way to know
+which account was meant.
+
 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.
+`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.

package/bin/{telark.js → telstore.js}

@@ -7,6 +7,7 @@ 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 { runToken } from '../src/commands/token.js'
 import { runUpload } from '../src/commands/upload.js'
 
 const SIGINT_EXIT_CODE = 130
@@ -18,6 +19,10 @@ let currentCommand = null
 let currentBackupId = null
 
 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.exit(SIGINT_EXIT_CODE)
 })
@@ -41,7 +46,11 @@ async function main() {
       return
 
     case 'login':
-      await runLogin({ verbose: Boolean(parsed.options.verbose) })
+      await runLogin({
+        args: parsed.args,
+        token: Boolean(parsed.options.token),
+        verbose: Boolean(parsed.options.verbose),
+      })
       return
 
     case 'logout':
@@ -60,6 +69,10 @@ async function main() {
       await runConfig(parsed.args, parsed.options)
       return
 
+    case 'token':
+      await runToken(parsed.args, parsed.options)
+      return
+
     case 'upload':
       await runUpload(parsed.args[0], parsed.options, {
         onBackupId: (id) => {
@@ -70,14 +83,14 @@ async function main() {
 
     case 'restore':
       if (!parsed.args[0]) {
-        throw new Error('Missing backup id. Example: npx telark restore telark-20260905-7f3a91')
+        throw new Error('Missing backup id. Example: npx telstore restore telstore-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')
+        throw new Error('Missing backup id. Example: npx telstore delete telstore-20260905-7f3a91')
       }
       await runDelete(parsed.args[0], parsed.options)
       return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telstore",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Split large files into chunks and store them on Telegram",
   "keywords": [
     "telegram",
@@ -11,19 +11,19 @@
     "cli",
     "mtproto"
   ],
-  "homepage": "https://github.com/shovity/telark#readme",
+  "homepage": "https://github.com/shovity/telstore#readme",
   "bugs": {
-    "url": "https://github.com/shovity/telark/issues"
+    "url": "https://github.com/shovity/telstore/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shovity/telark.git"
+    "url": "git+https://github.com/shovity/telstore.git"
   },
   "type": "module",
   "license": "MIT",
   "author": "shovity",
   "bin": {
-    "telark": "bin/telark.js"
+    "telstore": "bin/telstore.js"
   },
   "files": [
     "bin",
@@ -39,4 +39,4 @@
   "dependencies": {
     "telegram": "^2.26.22"
   }
-}
+}

package/src/caption.js

@@ -8,7 +8,7 @@ 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'
+export const MANIFEST_TAG = '#telstore'
 
 // 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.
@@ -32,7 +32,7 @@ export function manifestCaption({ id, name, size, chunks, createdAt }) {
     `🆔 ${id}`,
     `📅 ${utcMinutes(createdAt)}`,
     '',
-    `↩ npx telark restore ${id}`,
+    `↩ npx telstore restore ${id}`,
     MANIFEST_TAG,
   ].join('\n')
 }

package/src/chat.js

@@ -1,4 +1,4 @@
-// How telark talks about a destination. None of this touches Telegram — it is string
+// How telstore 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) {
@@ -17,7 +17,7 @@ export function normalizeChatTarget(input) {
 
 // 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
+// is reached by the account's own id, which telstore 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)

package/src/chunking.js

@@ -7,7 +7,20 @@ export const MAX_PARTS = 4000
 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
+// Upload counts 512KB parts and download counts 8MB slices, so one number cannot serve both.
+// Measured on a 1Gb/s line against a single 1800MB chunk, so every run transfers for three
+// to five minutes rather than the seconds a burst benchmark samples — the distinction the
+// parallel-download spec insists on, and it matters: measured in 20s bursts the download
+// order came out reversed, with 4 apparently the fastest value.
+//   upload     16 -> 7.7 MB/s (234s), 32 -> 9.4 (193s), 64 -> 9.5 (191s)
+//   download    4 -> 5.8 MB/s (311s),  8 -> 6.0 (300s), 16 -> 6.0 (302s)
+// Upload takes 32 because 64 measures the same speed (1% apart, inside the noise) at twice
+// the cost: 64 puts 32MB in flight, and a batch's last part then needs 4.4 Mbps to land
+// before the 60s stall deadline, against 2.1 Mbps at 32. A slow link would be told its
+// transfer stalled while it was merely slow, which is the one thing that deadline must not say.
+// Download takes 8 for the same reason from the other side: 16 buys nothing and 4 is slower.
+export const DEFAULT_UPLOAD_CONCURRENCY = 32
+export const DEFAULT_DOWNLOAD_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

package/src/cli.js

@@ -8,55 +8,68 @@ const SUBCOMMANDS = new Set([
   'delete',
   'status',
   'config',
+  'token',
   'help',
 ])
 
 const OPTIONS = {
   to: { type: 'string' },
   'chunk-size': { type: 'string' },
-  concurrency: { type: 'string' },
+  'upload-concurrency': { type: 'string' },
+  'download-concurrency': { type: 'string' },
   out: { type: 'string' },
   limit: { type: 'string' },
   verbose: { type: 'boolean' },
   unset: { type: 'boolean' },
   yes: { type: 'boolean' },
+  token: { type: 'boolean' },
   help: { type: 'boolean', short: 'h' },
 }
 
-export const HELP = `telark — split large files into chunks and store them on Telegram
+export const HELP = `telstore — split large files into chunks and store them on Telegram
 
 Usage:
-  npx telark login                        Log in to Telegram, only needed once
-  npx telark <file>                       Split a file and upload it to Telegram
-  npx telark list                         List the backups stored in the destination
-  npx telark restore <backup-id>          Download the chunks and reassemble the file
-  npx telark delete <backup-id>           Remove a backup's chunks and manifest from the chat
-  npx telark status                       Show the account, the destination and unfinished backups
-  npx telark config                       Show every setting and where its value comes from
-  npx telark logout                       Remove the saved session
+  npx telstore login                      Log in to Telegram, only needed once
+  npx telstore <file>                     Split a file and upload it to Telegram
+  npx telstore list                       List the backups stored in the destination
+  npx telstore restore <backup-id>        Download the chunks and reassemble the file
+  npx telstore delete <backup-id>         Remove a backup's chunks and manifest from the chat
+  npx telstore status                     Show the account, the destination and unfinished backups
+  npx telstore config                     Show every setting and where its value comes from
+  npx telstore logout                     Remove the saved session
+
+Running on a machine you do not trust:
+  npx telstore token                      Print a session token for another machine
+  npx telstore login --token              Log in there by pasting one, session stays sealed
 
 Settings:
-  npx telark config <name>                Print one setting's value
-  npx telark config <name> <value>        Change it for good
-  npx telark config <name> --unset        Drop it and fall back to the default
+  npx telstore config <name>              Print one setting's value
+  npx telstore config <name> <value>      Change it for good
+  npx telstore config <name> --unset      Drop it and fall back to the default
 
-  chat          Where backups go: @username, -100123..., or me. No default.
-  chunkSize     Size of each chunk, default 1800MB. Examples: 1.8GB, 500MB.
-  concurrency   512KB parts sent in parallel, default 8, max 64. Upload only.
-  limit         How many backups list shows, default 20.
-  verbose       Show Telegram connection logs, default false.
+  chat                 Where backups go: @username, -100123..., or me. No default.
+  chunkSize            Size of each chunk, default 1800MB. Examples: 1.8GB, 500MB.
+  uploadConcurrency    512KB parts sent in parallel, default 32, max 64.
+  downloadConcurrency  8MB slices fetched in parallel, default 8, max 64.
+  limit                How many backups list shows, default 20.
+  verbose              Show Telegram connection logs, default false.
 
 Options apply to one run and are never saved. Use config to change a setting for good.
-  --to <chat>            Destination for this run only.
-  --chunk-size <n>       Chunk size for this run only. An unfinished backup keeps the size
-                         it started with.
-  --concurrency <n>      Parts in parallel for this run only. Upload only — restore always
-                         downloads with its own fixed pool of workers.
-  --out <path>           Where to write the restored file. Defaults to the basename in the manifest.
-  --limit <n>            How many backups list shows this run.
-  --yes                  Delete without asking to confirm first.
-  --verbose              Show Telegram connection logs for this run.
-  -h, --help             Show this help.
+  --to <chat>                 Destination for this run only.
+  --chunk-size <n>            Chunk size for this run only. An unfinished backup keeps the
+                              size it started with.
+  --upload-concurrency <n>    512KB parts in parallel while uploading, this run only.
+  --download-concurrency <n>  8MB slices in parallel while restoring, this run only.
+  --out <path>                Where to write the restored file. Defaults to the basename in
+                              the manifest.
+  --limit <n>                 How many backups list shows this run.
+  --token                     Log in by pasting a session token. It 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.
+  --yes                       Delete without asking to confirm first.
+  --verbose                   Show Telegram connection logs for this run.
+  -h, --help                  Show this help.
 `
 
 // What Ctrl-C means depends on the command that was running: upload has written every
@@ -69,7 +82,7 @@ export function interruptMessage(command, { backupId } = {}) {
 
     return (
       `\n${backup} — run the same command again to continue, ` +
-      'or "npx telark status" to see what is left.\n'
+      'or "npx telstore status" to see what is left.\n'
     )
   }
 
@@ -138,13 +151,13 @@ export function route(argv) {
 
   const [first, ...rest] = positionals
 
-  // `telark --to @chan` with no file used to mean "remember this destination". Flags no
+  // `telstore --to @chan` with no file used to mean "remember this destination". Flags no
   // longer write anything, so that line now asks for a run that has nothing to upload —
   // say where the destination actually lives instead of printing help at someone who was
   // perfectly clear about what they wanted.
   if (first === undefined && values.to && !values.help) {
     throw new Error(
-      `Nothing to upload. To change the destination for good, run "npx telark config chat ${values.to}". ` +
+      `Nothing to upload. To change the destination for good, run "npx telstore config chat ${values.to}". ` +
         'To use it for one run, pass --to alongside a file or a command.',
     )
   }

package/src/client.js

@@ -5,6 +5,7 @@ import { StringSession } from 'telegram/sessions/index.js'
 
 import { manifestFileName } from './manifest.js'
 import { withRetry } from './retry.js'
+import { unlockConfig } from './session.js'
 import { DEFAULT_STALL_MS, withStallTimeout } from './stall.js'
 
 // GramJS narrates its version, every connection and every disconnect at info level, and
@@ -22,7 +23,7 @@ export function documentFileName(message) {
   return named?.fileName ?? null
 }
 
-// The one place telark searches a chat. Both callers want documents and nothing else,
+// The one place telstore searches a chat. Both callers want documents and nothing else,
 // and getMessages is preferred over a raw Api.messages.Search because it handles offsets,
 // hashes and pagination itself, so we don't hand-build easily mistyped fields. The raw
 // message is kept alongside the flat fields because downloading needs it whole.
@@ -42,9 +43,9 @@ export async function searchDocuments(client, peer, { search, limit }) {
   }))
 }
 
-// How telark finds a backup's manifest, in one place because restore and delete must not
+// How telstore finds a backup's manifest, in one place because restore and delete must not
 // disagree about it. The search is by backup id, but the answer is decided by the file name
-// telark itself wrote — a caption is text a person can edit, a file name is not.
+// telstore itself wrote — a caption is text a person can edit, a file name is not.
 export async function findManifestMessage(client, peer, backupId) {
   const wanted = manifestFileName(backupId)
   const found = await searchDocuments(client, peer, { search: backupId, limit: 100 })
@@ -56,7 +57,7 @@ export async function readMessageBytes(client, message) {
   return await client.downloadMedia(message)
 }
 
-// The one place telark removes messages from a chat, and the mirror of searchDocuments
+// The one place telstore removes messages from a chat, and the mirror of searchDocuments
 // above. GramJS has its own deleteMessages, and it is the right thing to call — it resolves
 // the peer and picks between channels.DeleteMessages and messages.DeleteMessages, which is
 // exactly the choice a fake client would never catch us getting wrong.
@@ -64,7 +65,7 @@ export async function readMessageBytes(client, message) {
 // What it does on top of that is the problem: it splits the ids into batches of a hundred
 // and fires every batch at once through Promise.all. A ten-thousand-chunk backup would put
 // a hundred requests in flight together, none of them under the retry policy or the stall
-// deadline that every other network wait in telark carries. Batching here instead keeps
+// deadline that every other network wait in telstore carries. Batching here instead keeps
 // one request outstanding at a time, under both.
 //
 // Telegram does not complain about an id that is no longer there, so sending a batch twice
@@ -121,16 +122,27 @@ export async function closeQuietly(client, disconnect, onWarn) {
   }
 }
 
+// Two shapes count as logged in: the ordinary one login writes, and the sealed blob that
+// "login --token" leaves, which holds the same three fields behind a passphrase. Checked
+// before anything asks for that passphrase, so somebody who never logged in is told so rather
+// than asked to type a secret for an account that is not there.
 export function assertLoggedIn(config) {
+  if (config.sealed) return
+
   if (!config.session || !config.apiId || !config.apiHash) {
-    throw new Error('Not logged in — run "npx telark login" first.')
+    throw new Error('Not logged in — run "npx telstore login" first.')
   }
 }
 
-export async function connect(config, { verbose = false } = {}) {
+// Every command that needs Telegram comes through here, which makes this the one place a
+// sealed session has to be opened. Doing it anywhere else would mean eight places to keep in
+// step, and a ninth command would simply forget.
+export async function connect(config, { verbose = false, unlock = unlockConfig } = {}) {
   assertLoggedIn(config)
 
-  const client = new TelegramClient(new StringSession(config.session), config.apiId, config.apiHash, {
+  const { apiId, apiHash, session } = await unlock(config)
+
+  const client = new TelegramClient(new StringSession(session), apiId, apiHash, {
     connectionRetries: 5,
     floodSleepThreshold: 60,
     baseLogger: createLogger(verbose),
@@ -139,7 +151,7 @@ export async function connect(config, { verbose = false } = {}) {
   await client.connect()
 
   if (!(await client.isUserAuthorized())) {
-    throw new Error('Session expired — run "npx telark login".')
+    throw new Error('Session expired — run "npx telstore login".')
   }
 
   return client