telstore 0.1.1 → 0.1.3

package/README.md

@@ -14,6 +14,7 @@ npx telstore status                       # account, destination, unfinished bac
 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
@@ -40,7 +41,8 @@ npx telstore config chunkSize --unset     # back to the default
 |---|---|---|---|
 | `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 |
 
@@ -127,10 +129,71 @@ 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 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 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.
 
@@ -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 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/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) => {

package/package.json

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

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,18 +8,21 @@ 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' },
 }
 
@@ -35,28 +38,38 @@ Usage:
   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 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

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
@@ -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 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),

package/src/commands/login.js

@@ -1,21 +1,12 @@
-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 '../chat.js'
-import { createLogger } from '../client.js'
-import { resolveSettings } from '../settings.js'
-
-function createPrompts() {
-  const rl = readline.createInterface({ input: stdin, output: stdout })
-  return {
-    ask: (question) => rl.question(question),
-    close: () => rl.close(),
-  }
-}
+import { closeQuietly, connect as realConnect, createLogger } from '../client.js'
+import { createPrompts } from '../prompt.js'
+import { knownSettings, resolveSettings } from '../settings.js'
+import { decodeToken, isSealedToken } from '../token.js'
 
 const LOGIN_ERROR_MESSAGES = {
   PHONE_NUMBER_INVALID: 'invalid phone number',
@@ -43,14 +34,96 @@ export function describeLoginError(err) {
 const createTelegramClient = (apiId, apiHash, options) =>
   new TelegramClient(new StringSession(''), apiId, apiHash, options)
 
+// The token never reaches here as an argument, and telstore refuses to pretend otherwise: a
+// token on the command line sits in the shell history of a machine the user does not trust,
+// and ignoring it silently would leave it there for nothing.
+function refuseArguments(args) {
+  if (args.length === 0) return
+
+  throw new Error(
+    'login takes no arguments. A session token is pasted at a prompt, never written on the ' +
+      'command line — there it stays in this machine\'s shell history and is visible in "ps" ' +
+      'for as long as the command runs. Run "npx telstore login --token" and paste it when asked.',
+  )
+}
+
+// Logging in with a token telstore printed elsewhere. The blob is stored exactly as it
+// arrived rather than opened and written back out: what makes this worth doing is that the
+// session never exists on this machine's disk in a form anyone can read.
+async function loginWithToken({ configDir, prompts, connectWith, shutdown, verbose, log }) {
+  const token = (await prompts.askSecret('Session token: ')).trim()
+  const passphrase = isSealedToken(token) ? await prompts.askSecret('Passphrase for the token: ') : ''
+
+  // Opened here, before anything is written, so a wrong passphrase is a sentence now rather
+  // than a failure at the start of a restore that was going to take twenty minutes.
+  const bundle = await decodeToken(token, passphrase)
+  const account = { apiId: bundle.apiId, apiHash: bundle.apiHash, session: bundle.session }
+
+  // A token says what the session was when it was made. Only Telegram can say whether that
+  // session is still alive, and finding out now is the difference between a login that failed
+  // and a login that appeared to work.
+  const client = await connectWith(account, { verbose })
+
+  let me
+  try {
+    me = await client.getMe()
+  } finally {
+    await closeQuietly(client, shutdown)
+  }
+
+  const config = await loadConfig(configDir)
+  // Built fresh rather than merged over what was there: a config holding both a sealed
+  // session and a plain one is refused on the next run, and merging is how it would come to
+  // hold both. Settings are the exception, because they are nobody's secret.
+  const next = passphrase === '' ? { ...account } : { sealed: token }
+  const settings = { ...config.settings, ...knownSettings(bundle.settings) }
+
+  if (Object.keys(settings).length > 0) next.settings = settings
+
+  await saveConfig(next, configDir)
+
+  log(`\nLogged in as ${me.username ? `@${me.username}` : me.firstName}.`)
+
+  if (passphrase === '') {
+    log(
+      `Config saved to ${configDir}/config.json. This token had no passphrase, so the session ` +
+        'is stored here in plain text, exactly as an ordinary login would store it.',
+    )
+    return
+  }
+
+  log(
+    `Config saved to ${configDir}/config.json, with the session sealed behind your ` +
+      'passphrase. Every command that talks to Telegram will ask for it.',
+  )
+}
+
 export async function runLogin({
   configDir = defaultConfigDir(),
-  prompts = createPrompts(),
+  args = [],
+  token = false,
+  prompts = null,
+  connectWith = realConnect,
   verbose = false,
   createClient = createTelegramClient,
   shutdown = (client) => client.destroy(),
   log = (line) => console.log(line),
 } = {}) {
+  refuseArguments(args)
+
+  // Opened here and not in the parameter list: a default argument runs on every call, so the
+  // refusal above would open a readline on stdin it never reads from and the process would
+  // hang with nothing left to do.
+  prompts = prompts ?? createPrompts()
+
+  if (token) {
+    try {
+      return await loginWithToken({ configDir, prompts, connectWith, shutdown, verbose, log })
+    } finally {
+      prompts.close()
+    }
+  }
+
   const config = await loadConfig(configDir)
   const storedChat = config.settings?.chat
   const loud = verbose || resolveSettings({}, config).values.verbose
@@ -80,7 +153,7 @@ export async function runLogin({
   await client.start({
     phoneNumber: () => prompts.ask('Phone number (e.g. +1...): '),
     phoneCode: () => prompts.ask('Verification code Telegram just sent: '),
-    password: () => prompts.ask('Two-step password (leave blank if not enabled): '),
+    password: () => prompts.askSecret('Two-step password (leave blank if not enabled): '),
     onError: (err) => console.error(`Login failed: ${describeLoginError(err)}`),
   })
 

package/src/commands/logout.js

@@ -1,11 +1,21 @@
-import { clearSession, defaultConfigDir } from '../config.js'
+import { clearSession, defaultConfigDir, loadConfig } from '../config.js'
+
+// The same true fact in both cases — the session outlives this machine — but not the same
+// sentence about what is left behind. An ordinary login keeps the api_id and api_hash beside
+// the session, and a sealed one keeps them inside it, so there the api_hash goes too. Saying
+// otherwise would describe a machine other than the one in front of the reader.
+export async function runLogout({ configDir = defaultConfigDir(), log = (line) => console.log(line) } = {}) {
+  const { sealed } = await loadConfig(configDir)
 
-export async function runLogout({ configDir = defaultConfigDir() } = {}) {
   await clearSession(configDir)
-  console.log(
-    'Removed the session stored on this machine. api_id, api_hash and the destination are kept.',
+
+  log(
+    sealed
+      ? 'Removed the sealed session stored on this machine. The api_id and api_hash were ' +
+          'inside it, so they are gone with it; the destination is kept.'
+      : 'Removed the session stored on this machine. api_id, api_hash and the destination are kept.',
   )
-  console.log(
+  log(
     'Note: this only deletes the local copy — 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/src/commands/restore.js

@@ -28,8 +28,8 @@ async function realGetMessage(client, peer, msgId) {
   return message ?? null
 }
 
-export async function realDownloadChunk(client, message, handle, offset, onProgress, retryOptions) {
-  return await downloadToFile(client, message, handle.fd, { offset, onProgress, retryOptions })
+export async function realDownloadChunk(client, message, handle, offset, onProgress, options) {
+  return await downloadToFile(client, message, handle.fd, { offset, onProgress, ...options })
 }
 
 // manifest.name comes from data downloaded off Telegram — don't trust it when picking
@@ -165,7 +165,10 @@ export async function runRestore(backupId, options = {}, deps = {}) {
             handle,
             chunk.i * manifest.chunkSize,
             progress.advance,
-            { ...retryOptions, onRetry },
+            {
+              retryOptions: { ...retryOptions, onRetry },
+              concurrency: settings.downloadConcurrency,
+            },
           )
 
           if (size !== chunk.size) {

package/src/commands/status.js

@@ -1,12 +1,10 @@
-import path from 'node:path'
-
 import { countChunks } from '../chunking.js'
 import { describeChat } from '../chat.js'
 import { assertLoggedIn, closeQuietly, connect as realConnect } from '../client.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
 import { formatBytes } from '../progress.js'
 import { resolveSettings } from '../settings.js'
-import { listStates } from '../state.js'
+import { canResume, listStates } from '../state.js'
 
 const LABEL_WIDTH = 'Destination'.length + 2
 
@@ -14,6 +12,66 @@ function row(label, value) {
   return `${label.padEnd(LABEL_WIDTH)}${value}`
 }
 
+// Each unfinished backup gets its own indented block, so the fields line up under a heading
+// that is the id — the one string `restore` and `delete` both take.
+const FIELD_WIDTH = 'Resume'.length + 3
+const CONTINUATION = ' '.repeat(FIELD_WIDTH + 2)
+
+function field(label, value) {
+  return `  ${label.padEnd(FIELD_WIDTH)}${value}`
+}
+
+// The Resume line is a command meant to be pasted, so anything a shell would take apart has
+// to come back quoted — a path with a space in it is the ordinary case, not an exotic one.
+const BARE_ARG = /^[A-Za-z0-9_@%+:,./-]+$/
+
+function shellArg(text) {
+  const value = String(text)
+
+  return BARE_ARG.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`
+}
+
+// runUpload refuses to send the rest of a backup to a different chat, so the command has to
+// name the one the chunks are already in — unless the destination in force is that chat
+// anyway, where --to would just be noise. Not knowing the destination counts as not matching:
+// leaving --to out would be a guess about where a backup already in progress went.
+function resumeCommand(state, destination) {
+  const matches = destination !== null && state.chat === String(destination)
+
+  return `npx telstore ${shellArg(state.path)}${matches ? '' : ` --to ${shellArg(state.chat)}`}`
+}
+
+// Why a resume is off the table, in the words of the thing the user would have to fix. The
+// record is keyed on the file's path, size and mtime, so any of these means runUpload would
+// hash the file to a different key, find nothing, and start a second backup instead.
+const NO_RESUME = {
+  missing: 'the file is no longer there',
+  changed: 'the file has changed since the backup started',
+  'not-a-file': 'that path is no longer a file',
+  unreadable: 'the record does not name a file that can be read',
+}
+
+// A command is printed only when it will really resume. Printing one regardless would be
+// telling the user to run something that quietly starts a second backup and abandons every
+// chunk this one already sent — and those chunks are then findable only by this id, which
+// is worth saying while there are any.
+async function resumeLines(key, state, destination, done) {
+  const check = await canResume(key, state)
+
+  if (check.ok) return [field('Resume', resumeCommand(state, destination))]
+
+  const lines = [field('Resume', `not possible: ${NO_RESUME[check.reason]}.`)]
+
+  if (done > 0) {
+    lines.push(
+      `${CONTINUATION}${done} chunk${done === 1 ? ' is' : 's are'} already in the chat, ` +
+        'searchable by this id.',
+    )
+  }
+
+  return lines
+}
+
 function describeAccount(me) {
   const name = [me.firstName, me.lastName].filter(Boolean).join(' ')
   const handle = me.username ? ` (@${me.username})` : ''
@@ -72,6 +130,17 @@ export async function runStatus(options = {}, deps = {}) {
     settingsError = err.message
   }
 
+  // Which config this report is about, and whether the session in it can be read. Printed
+  // unconditionally: status never said where it looked before, and a row that shows up only
+  // when something is unusual reads as a warning rather than as a fact.
+  log(
+    row(
+      'Session',
+      config.sealed
+        ? `${configFile(configDir)} (sealed — opened with a passphrase)`
+        : configFile(configDir),
+    ),
+  )
   log(row('Account', await accountLine(config, settings?.verbose ?? false, { connect, disconnect })))
   log(
     row(
@@ -92,11 +161,20 @@ export async function runStatus(options = {}, deps = {}) {
 
   log(row('Unfinished', `${states.length} backup${states.length === 1 ? '' : 's'}`))
 
-  for (const state of states) {
+  // The destination is what decides whether the resume command needs a --to. A row that
+  // failed to parse leaves nothing to compare against, which is not the same as a match.
+  const destination = settings?.chat ?? null
+
+  for (const { key, state } of states) {
     const total = countChunks(state.size, state.chunkSize)
     const done = Object.keys(state.done ?? {}).length
 
-    log(`  ${state.id}  ${path.basename(state.path)}  ${done}/${total} chunks  ${formatBytes(state.size)}`)
-    log(`  → ${describeChat(state.chat)}`)
+    log('')
+    log(`  ${state.id}`)
+    log(field('File', `${state.path}  (${formatBytes(state.size)})`))
+    log(field('Chunks', `${done} of ${total} uploaded`))
+    log(field('Chat', describeChat(state.chat)))
+
+    for (const line of await resumeLines(key, state, destination, done)) log(line)
   }
 }

package/src/commands/token.js

@@ -0,0 +1,80 @@
+import { assertLoggedIn } from '../client.js'
+import { defaultConfigDir, loadConfig } from '../config.js'
+import { createPrompts } from '../prompt.js'
+import { unlockConfig } from '../session.js'
+import { knownSettings } from '../settings.js'
+import { encodeToken } from '../token.js'
+
+// Short enough that whoever holds the token can work through the possibilities faster than
+// scrypt can slow them down. Not a rule — a length minimum is a preference wearing a check's
+// clothes, and the main thing one teaches is to append digits — so this warns and goes on.
+const SHORT_PASSPHRASE = 12
+
+export async function runToken(args = [], options = {}, deps = {}) {
+  const {
+    configDir = defaultConfigDir(),
+    prompts = null,
+    log = (line) => console.log(line),
+    writeErr = (line) => process.stderr.write(line),
+  } = deps
+
+  const config = await loadConfig(configDir)
+
+  // Before anything is asked for. Someone who has never logged in should be told that, not
+  // asked to invent a passphrase for an account that is not there.
+  assertLoggedIn(config)
+
+  // Opened here rather than in the parameter list, so the command that refuses above never
+  // touches stdin. Every question in this run goes through this one interface: asking each
+  // through its own would leave the second one at end-of-input having read nothing.
+  const ask = prompts ?? createPrompts({ output: process.stderr })
+
+  try {
+    return await mint(config, ask, { log, writeErr })
+  } finally {
+    ask.close()
+  }
+}
+
+async function mint(config, ask, { log, writeErr }) {
+  const readSecret = (question) => ask.askSecret(question)
+  const account = await unlockConfig(config, { readSecret })
+
+  const passphrase = await readSecret('Passphrase to protect the token: ')
+  const again = await readSecret('Repeat it: ')
+
+  if (passphrase !== again) {
+    throw new Error('The two passphrases are different. Nothing was printed — run the command again.')
+  }
+
+  if (passphrase === '') {
+    writeErr(
+      'This token has no passphrase, so anyone who reads it can use your Telegram account. ' +
+        'Do not send it through anything that keeps a copy.\n',
+    )
+  } else if (passphrase.length < SHORT_PASSPHRASE) {
+    writeErr(
+      `That passphrase is ${passphrase.length} characters. Whoever holds the token can try ` +
+        'passphrases offline as fast as their hardware allows, and telstore can only make ' +
+        'each attempt cost about half a second.\n',
+    )
+  }
+
+  // The same true fact logout already states, said the same way: telstore cannot take a token
+  // back, and the session it carries outlives every copy of the token.
+  writeErr(
+    'This token carries your Telegram session. telstore cannot take it back — as with ' +
+      'logout, the session stays alive on Telegram\'s side until you open Telegram → ' +
+      'Settings → Devices (Active sessions) and terminate it. It is about to be printed ' +
+      'here, so it will sit in this terminal\'s scrollback until you clear it.\n\n',
+  )
+
+  // stdout carries the token and nothing else, the rule `config <name>` already follows, so
+  // this can be piped into a QR encoder with every warning above still on the screen.
+  log(
+    await encodeToken(
+      { ...account, settings: knownSettings(config.settings) },
+      passphrase,
+    ),
+  )
+}

package/src/commands/upload.js

@@ -95,7 +95,7 @@ export async function runUpload(filePath, options = {}, deps = {}) {
     file: configFile(configDir),
   })
   const chat = requireChat(settings)
-  const concurrency = settings.concurrency
+  const concurrency = settings.uploadConcurrency
 
   const key = stateKey(absPath, stat.size, stat.mtimeMs)
 

package/src/config.js

@@ -37,6 +37,26 @@ export function checkConfigShape(raw, file) {
     )
   }
 
+  // What `login --token` leaves behind: the session and the api_hash sealed inside one blob
+  // that only a passphrase opens. It is read by `connect`, never by anything that writes.
+  if (raw.sealed !== undefined && typeof raw.sealed !== 'string') {
+    throw new Error(
+      `"sealed" in ${file} holds ${Array.isArray(raw.sealed) ? 'a list' : typeof raw.sealed}, ` +
+        'not a sealed session. Log in again with "npx telstore login --token", or remove that ' +
+        'entry and log in with a phone number.',
+    )
+  }
+
+  // Two sources of truth for one account, and nothing to say which one was meant. Guessing
+  // would mean connecting as an account the user did not choose — either the stale one they
+  // thought they had replaced, or the one they thought they had left behind.
+  if (raw.sealed !== undefined && (raw.session !== undefined || raw.apiHash !== undefined)) {
+    throw new Error(
+      `${file} holds both a sealed session and a plain one. telstore will not guess which ` +
+        'account was meant — delete the file and log in again.',
+    )
+  }
+
   return raw
 }
 
@@ -79,8 +99,12 @@ export async function saveConfig(config, dir = defaultConfigDir()) {
   await writeJsonAtomic(configFile(dir), config)
 }
 
+// Both shapes go, because they are the same thing written two ways. On a machine that logged
+// in with a token the api_hash lives inside the sealed blob, so keeping it "like an ordinary
+// logout does" would keep the entire account.
 export async function clearSession(dir = defaultConfigDir()) {
   const config = await loadConfig(dir)
   delete config.session
+  delete config.sealed
   await saveConfig(config, dir)
 }

package/src/downloader.js

@@ -4,7 +4,7 @@ import { promisify } from 'node:util'
 
 import { returnBigInt } from 'telegram/Helpers.js'
 
-import { DEFAULT_CONCURRENCY, PART_SIZE, SLICE_SIZE } from './chunking.js'
+import { DEFAULT_DOWNLOAD_CONCURRENCY, PART_SIZE, SLICE_SIZE } from './chunking.js'
 import { withRetry } from './retry.js'
 import { DEFAULT_STALL_MS, withStallTimeout } from './stall.js'
 
@@ -57,7 +57,7 @@ export async function downloadToFile(
   client,
   message,
   fd,
-  { offset, onProgress, retryOptions, concurrency = DEFAULT_CONCURRENCY, stallMs = DEFAULT_STALL_MS } = {},
+  { offset, onProgress, retryOptions, concurrency = DEFAULT_DOWNLOAD_CONCURRENCY, stallMs = DEFAULT_STALL_MS } = {},
 ) {
   const document = message?.media?.document
 

package/src/prompt.js

@@ -0,0 +1,119 @@
+import readline from 'node:readline/promises'
+import { stdin, stdout, stderr } from 'node:process'
+import { Writable } from 'node:stream'
+
+// readline echoes what it reads through its own output, so putting a curtain in front of that
+// output is what makes typing invisible. The curtain is also where the mask is drawn from:
+// every echo readline makes is a write arriving here, and a write arriving here is the one
+// signal that something was typed which does not involve reading readline's internals.
+function veiledOutput(output) {
+  let onEcho = null
+
+  return {
+    hide: (draw) => {
+      onEcho = draw
+    },
+    show: () => {
+      onEcho = null
+    },
+    // The question goes straight to the real output, past the curtain, so it stays on screen
+    // while the answer to it does not.
+    say: (text) => output.write(text),
+    stream: new Writable({
+      write(chunk, encoding, callback) {
+        if (onEcho) onEcho(String(chunk))
+        else output.write(chunk, encoding)
+        callback()
+      },
+    }),
+  }
+}
+
+// What the line reads while a secret is being typed. The mask is capped to the line the question
+// sits on: askSecret redraws the whole line on every keystroke, and that redraw clears one line
+// only, so a mask allowed to wrap would leave stale asterisks on the rows above it. The trailing
+// ellipsis says the counting stopped, not the typing.
+export function maskLine(question, length, columns) {
+  // One column is kept back for the ellipsis, and one for the mask itself however narrow the
+  // terminal is: a question that fills the line would otherwise mask to nothing, which is the
+  // silence this whole thing exists to end.
+  const budget = Math.max(1, (columns || 80) - question.length - 1)
+
+  if (length <= budget) return question + '*'.repeat(length)
+
+  return `${question}${'*'.repeat(budget)}\u2026`
+}
+
+const NO_TERMINAL =
+  'There is no terminal here to type a secret into. Run this where you can type it.'
+
+// One readline for a whole conversation, some of whose answers must not stay on the screen.
+// It has to be one: two readlines over a single stdin do not take turns — the first keeps the
+// listener and everything typed after it lands nowhere, so the second reaches end-of-input
+// having read nothing and reports it as Ctrl-D. Verified against a real terminal, because a
+// fake stream takes turns perfectly well and would have called this fine.
+export function createPrompts({ input = stdin, output = stdout } = {}) {
+  const veil = veiledOutput(output)
+  // terminal follows stdin: true is what stops the tty driver from echoing on its own, which
+  // is what leaves the curtain as the only thing between the keyboard and the screen. Forcing
+  // it on a pipe would put readline into line editing over input with no terminal behind it.
+  const rl = readline.createInterface({ input, output: veil.stream, terminal: Boolean(input.isTTY) })
+
+  return {
+    ask: (question) => rl.question(question),
+    async askSecret(question) {
+      // A prompt written where nobody can see it, waiting on a stream that will never carry a
+      // typed answer, is a hang — the one failure this project refuses to produce anywhere.
+      // Reading it from the pipe instead would be worse: the secret would then have come from
+      // somewhere that kept a copy of it.
+      if (!input.isTTY) throw new Error(NO_TERMINAL)
+
+      veil.say(question)
+      // The question is already on screen and carries no asterisks yet, so the first echo has
+      // nothing to add. rl.line is what the mask counts — readline's own idea of the line,
+      // after it has applied the keystroke, whether that was a character, a paste, a backspace
+      // or a Ctrl-U.
+      let drawn = question
+
+      veil.hide((echo) => {
+        // Readline announces the finished line by writing a newline, and by then it has already
+        // emptied rl.line: redrawing on that would wipe the mask off the screen at the very
+        // moment the answer was accepted.
+        if (echo.includes('\n')) return
+
+        const line = maskLine(question, rl.line.length, output.columns)
+
+        // One keystroke can cost readline four writes — a redraw per write would be the same
+        // line four times and a cursor that flickers for nothing.
+        if (line === drawn) return
+
+        drawn = line
+        veil.say(`\x1b[2K\r${line}`)
+      })
+
+      try {
+        return await rl.question('')
+      } finally {
+        veil.show()
+        veil.say('\n')
+      }
+    },
+    // Not optional: terminal mode put stdin in raw mode, and leaving it there hands the user
+    // back a shell that no longer echoes what they type.
+    close: () => rl.close(),
+  }
+}
+
+// The single-question case. Its question goes to stderr rather than stdout, because
+// "npx telstore token > token.txt" has to still show it, and stdout there carries one thing.
+export async function readSecret(question, { input = stdin, output = stderr } = {}) {
+  if (!input.isTTY) throw new Error(NO_TERMINAL)
+
+  const prompts = createPrompts({ input, output })
+
+  try {
+    return await prompts.askSecret(question)
+  } finally {
+    prompts.close()
+  }
+}

package/src/session.js

@@ -0,0 +1,24 @@
+import { readSecret as realReadSecret } from './prompt.js'
+import { decodeToken } from './token.js'
+
+// How a stored config becomes the three things GramJS needs. There are two shapes on disk —
+// the ordinary login, and the sealed blob `login --token` writes — and this is the one place
+// that knows the difference, so `connect` stays about Telegram and the commands stay about
+// their own narrative.
+export async function unlockConfig(config, { readSecret = realReadSecret } = {}) {
+  const { sealed } = config
+
+  if (!sealed) {
+    const { apiId, apiHash, session } = config
+
+    return { apiId, apiHash, session }
+  }
+
+  const passphrase = await readSecret('Passphrase for the stored session: ')
+  // Everything comes out of the blob and nothing from around it. The fields beside it on disk
+  // are editable by anyone who can reach the file, and an apiId taken from there would let an
+  // edit decide which account a passphrase unlocks.
+  const { apiId, apiHash, session } = await decodeToken(sealed, passphrase)
+
+  return { apiId, apiHash, session }
+}

package/src/settings.js

@@ -1,7 +1,8 @@
 import { normalizeChatTarget } from './chat.js'
 import {
   DEFAULT_CHUNK_SIZE,
-  DEFAULT_CONCURRENCY,
+  DEFAULT_DOWNLOAD_CONCURRENCY,
+  DEFAULT_UPLOAD_CONCURRENCY,
   MAX_CONCURRENCY,
   parseSize,
 } from './chunking.js'
@@ -74,9 +75,9 @@ export const SETTINGS = {
     format: (value) => String(value),
     describe: (value) => formatBytes(value),
   },
-  concurrency: {
-    flag: 'concurrency',
-    default: DEFAULT_CONCURRENCY,
+  uploadConcurrency: {
+    flag: 'upload-concurrency',
+    default: DEFAULT_UPLOAD_CONCURRENCY,
     parse: (raw, where) =>
       wholeNumber(
         raw,
@@ -88,6 +89,20 @@ export const SETTINGS = {
       ),
     format: (value) => String(value),
   },
+  downloadConcurrency: {
+    flag: 'download-concurrency',
+    default: DEFAULT_DOWNLOAD_CONCURRENCY,
+    parse: (raw, where) =>
+      wholeNumber(
+        raw,
+        where,
+        1,
+        MAX_CONCURRENCY,
+        `Must be an integer from 1 to ${MAX_CONCURRENCY} — each slot runs its own download ` +
+          'stream, and Telegram answers with FLOOD_WAIT if too many requests go out at once.',
+      ),
+    format: (value) => String(value),
+  },
   limit: {
     flag: 'limit',
     default: DEFAULT_LIMIT,
@@ -188,3 +203,14 @@ export function requireChat(values) {
 
   return values.chat
 }
+
+// The snapshot of somebody's settings that a session token carries to a machine which has no
+// config file of its own. A stray key would arrive there as a line in `config` telling the
+// reader to remove a setting they never wrote, so keys telstore does not know are left behind
+// rather than carried along. This lives here because this is the one place that knows which
+// settings exist.
+export function knownSettings(stored = {}) {
+  return Object.fromEntries(
+    SETTING_KEYS.filter((key) => stored[key] !== undefined).map((key) => [key, stored[key]]),
+  )
+}

package/src/state.js

@@ -96,6 +96,10 @@ export async function pruneStates(configDir = defaultConfigDir(), keep = MAX_STA
 // status needs every unfinished backup at once. A state file that cannot be read is skipped
 // rather than fatal, for the same reason loadState returns null: one corrupt file must not
 // hide the other backups still waiting to be finished.
+//
+// The key comes back alongside each record because canResume needs it, and the file name is
+// the only place it survives: the record's own path, size and mtime are exactly what a
+// rewritten file makes stale, so recomputing the key from them would always say yes.
 export async function listStates(configDir = defaultConfigDir()) {
   let names
   try {
@@ -110,8 +114,10 @@ export async function listStates(configDir = defaultConfigDir()) {
   for (const name of names) {
     if (!name.endsWith('.json')) continue
 
-    const state = await loadState(name.slice(0, -'.json'.length), configDir)
-    if (state) states.push(state)
+    const key = name.slice(0, -'.json'.length)
+    const state = await loadState(key, configDir)
+
+    if (state) states.push({ key, state })
   }
 
   return states
@@ -149,3 +155,28 @@ export async function findStates(backupId, configDir = defaultConfigDir()) {
 
   return found
 }
+
+// Whether a record can still be resumed, which is not a question about the record alone:
+// runUpload hashes the file it finds on disk and looks the result up, so a backup is
+// resumable exactly when that hash is still the key this record is filed under. Recomputing
+// through stateKey rather than comparing size and mtime by hand is the point — a second way
+// of asking is a second way to drift, and status would end up promising a resume that upload
+// turns into a brand new backup, stranding every chunk already sent.
+//
+// Never throws. status calls this for every record it prints, and one damaged path must not
+// take the rest of the report down with it.
+export async function canResume(key, state) {
+  let stat
+
+  try {
+    stat = await fs.stat(state.path)
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: false, reason: 'missing' }
+    return { ok: false, reason: 'unreadable' }
+  }
+
+  if (!stat.isFile()) return { ok: false, reason: 'not-a-file' }
+  if (stateKey(state.path, stat.size, stat.mtimeMs) !== key) return { ok: false, reason: 'changed' }
+
+  return { ok: true }
+}

package/src/token.js

@@ -0,0 +1,221 @@
+import { createCipheriv, createDecipheriv, randomBytes, scrypt } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const derive = promisify(scrypt)
+
+// A session token is this machine's Telegram login, written down so another machine can use
+// it. Two formats, not one format with a flag inside: a blob that looked encrypted and was
+// not would be telstore lying about what it handed over, and the prefix is the one part a
+// reader can check before knowing anything else about the bytes.
+export const TOKEN_PREFIX_SEALED = 'tls1.'
+export const TOKEN_PREFIX_PLAIN = 'tls0.'
+
+const SALT_BYTES = 16
+const IV_BYTES = 12
+const TAG_BYTES = 16
+const KEY_BYTES = 32
+const OVERHEAD = SALT_BYTES + IV_BYTES + TAG_BYTES
+
+// Pinned to the prefix above, never carried inside the token. Whoever holds a token can try
+// passphrases offline as fast as their hardware allows, and 64MB per attempt is what makes
+// that expensive; letting a token name its own parameters would let a stranger's N decide how
+// much memory this machine allocates, which is a denial of service that needs no passphrase
+// at all. maxmem is spelled out because Node's own default is 32MB and would refuse these
+// outright, as an error that reads like a bug in telstore.
+const SCRYPT = { N: 65536, r: 8, p: 1, maxmem: 128 * 1024 * 1024 }
+
+const MAKE_ONE = 'Make a new one with "npx telstore token" on the machine you are logged in on.'
+
+// Whitespace is the one damage repaired rather than refused: a chat client or a mail reader
+// wrapping the line is the likeliest thing to happen to a token, whitespace is never part of
+// one, and joining it back up cannot produce a *different* valid token, because the
+// authentication tag still has to match. Anything else is refused — repairing it would be
+// guessing at what somebody meant.
+function tidy(token) {
+  return String(token).replace(/\s+/g, '')
+}
+
+export function isSealedToken(text) {
+  return tidy(text).startsWith(TOKEN_PREFIX_SEALED)
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// A token is untrusted input in the same category as a manifest or a state file. Opening one
+// proves whoever made it knew the passphrase, not that they made it correctly — and the
+// unprotected format proves nothing at all. An apiId of undefined does not throw here; it
+// reaches GramJS and fails much later as something that reads like a network problem.
+export function checkTokenBundle(bundle) {
+  if (!isPlainObject(bundle)) {
+    throw new Error(
+      `The session token holds ${Array.isArray(bundle) ? 'a list' : typeof bundle}, ` +
+        `not an account. ${MAKE_ONE}`,
+    )
+  }
+
+  if (!Number.isSafeInteger(bundle.apiId) || bundle.apiId < 1) {
+    throw new Error(
+      `The session token gives ${JSON.stringify(bundle.apiId)} as the api_id, which is not ` +
+        `one. ${MAKE_ONE}`,
+    )
+  }
+
+  for (const field of ['apiHash', 'session']) {
+    if (typeof bundle[field] !== 'string' || bundle[field] === '') {
+      throw new Error(`The session token is missing its ${field}. ${MAKE_ONE}`)
+    }
+  }
+
+  // The twin of checkConfigShape, refused for the twin's reason: every lookup below a
+  // settings that is not an object returns undefined, and telstore would then run on its
+  // built-in defaults while the choices carried in the token sat there ignored.
+  if (bundle.settings !== undefined && !isPlainObject(bundle.settings)) {
+    throw new Error(
+      `"settings" in the session token holds ` +
+        `${Array.isArray(bundle.settings) ? 'a list' : typeof bundle.settings}, not a group ` +
+        `of settings. ${MAKE_ONE}`,
+    )
+  }
+
+  return bundle
+}
+
+// Both spellings of the same accented passphrase have to derive the same key: macOS hands
+// back one and Linux the other, and the difference would surface as "wrong passphrase" for a
+// passphrase that is right.
+function keyFrom(passphrase, salt) {
+  return derive(String(passphrase).normalize('NFC'), salt, KEY_BYTES, SCRYPT)
+}
+
+export async function encodeToken(bundle, passphrase) {
+  checkTokenBundle(bundle)
+
+  const json = JSON.stringify(bundle)
+
+  // An empty passphrase is not a weak secret, it is the absence of one. Saying so in the
+  // prefix is what keeps the format honest: the alternative is a token that opens for anyone
+  // who reads the channel it travelled through while looking exactly like a protected one.
+  if (String(passphrase) === '') {
+    return TOKEN_PREFIX_PLAIN + Buffer.from(json, 'utf8').toString('base64url')
+  }
+
+  const salt = randomBytes(SALT_BYTES)
+  const iv = randomBytes(IV_BYTES)
+  const cipher = createCipheriv('aes-256-gcm', await keyFrom(passphrase, salt), iv)
+  const body = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()])
+
+  return (
+    TOKEN_PREFIX_SEALED +
+    Buffer.concat([salt, iv, cipher.getAuthTag(), body]).toString('base64url')
+  )
+}
+
+function splitToken(token) {
+  const text = tidy(token)
+
+  for (const prefix of [TOKEN_PREFIX_SEALED, TOKEN_PREFIX_PLAIN]) {
+    if (text.startsWith(prefix)) return { sealed: prefix === TOKEN_PREFIX_SEALED, encoded: text.slice(prefix.length) }
+  }
+
+  const version = /^([a-z]+\d+)\./.exec(text)
+
+  if (version) {
+    throw new Error(
+      `This session token is in format "${version[1]}", which this telstore does not know ` +
+        `(it reads "${TOKEN_PREFIX_SEALED.slice(0, -1)}" and ` +
+        `"${TOKEN_PREFIX_PLAIN.slice(0, -1)}"). Upgrade telstore, or make a new token with ` +
+        'the version you have.',
+    )
+  }
+
+  throw new Error(
+    `That does not look like a session token: one starts with "${TOKEN_PREFIX_SEALED}" or ` +
+      `"${TOKEN_PREFIX_PLAIN}". ${MAKE_ONE}`,
+  )
+}
+
+function bodyBytes(encoded) {
+  const trimmed = encoded.replace(/=+$/, '')
+  const bytes = Buffer.from(trimmed, 'base64url')
+
+  // Buffer.from silently drops every character outside the alphabet, so a token with a stray
+  // quote in it decodes to *something* — which would then fail authentication and be
+  // reported as a wrong passphrase. Re-encoding and comparing is what turns that into the
+  // sentence that actually helps.
+  if (bytes.toString('base64url') !== trimmed) {
+    throw new Error(
+      'The session token has characters that do not belong to one — it was probably ' +
+        'truncated or altered on the way here. Copy it again, whole.',
+    )
+  }
+
+  return bytes
+}
+
+export async function decodeToken(token, passphrase) {
+  const { sealed, encoded } = splitToken(token)
+  const bytes = bodyBytes(encoded)
+
+  if (!sealed) {
+    return checkTokenBundle(readJson(bytes.toString('utf8')))
+  }
+
+  // Asked here rather than at the top: a token nobody can read is a different problem from a
+  // passphrase nobody supplied, and telling someone to type a passphrase for a token that was
+  // damaged in transit sends them after the wrong thing.
+  if (String(passphrase) === '') {
+    throw new Error(
+      'This session token is protected by a passphrase, and none was given. Run the command ' +
+        'again where you can type it.',
+    )
+  }
+
+  if (bytes.length <= OVERHEAD) {
+    throw new Error(
+      `The session token is too short to be one: it carries ${bytes.length} bytes and the ` +
+        `salt, nonce and tag alone need ${OVERHEAD}. Copy it again, whole.`,
+    )
+  }
+
+  const decipher = createDecipheriv(
+    'aes-256-gcm',
+    await keyFrom(passphrase, bytes.subarray(0, SALT_BYTES)),
+    bytes.subarray(SALT_BYTES, SALT_BYTES + IV_BYTES),
+  )
+
+  decipher.setAuthTag(bytes.subarray(SALT_BYTES + IV_BYTES, OVERHEAD))
+
+  let json
+  try {
+    json = Buffer.concat([
+      decipher.update(bytes.subarray(OVERHEAD)),
+      decipher.final(),
+    ]).toString('utf8')
+  } catch {
+    // AES-GCM cannot tell a wrong key from altered bytes: both are one failed tag check, and
+    // guessing which it was would send half the readers after the wrong thing. Name both, put
+    // the likelier one first, and say out loud that telstore is not guessing.
+    throw new Error(
+      'Could not open the session token: either the passphrase is wrong or the token was ' +
+        'altered on the way here. Encryption cannot tell those two apart, so telstore will ' +
+        'not guess — check the passphrase first, then copy the token again, whole.',
+    )
+  }
+
+  return checkTokenBundle(readJson(json))
+}
+
+// Past the tag check the plaintext is ours, so bad JSON here is not somebody else's mistake:
+// it means the token was written by a telstore that disagreed with this one about the format.
+function readJson(json) {
+  try {
+    return JSON.parse(json)
+  } catch (err) {
+    throw new Error(
+      `The session token opened, but what is inside it is not what telstore writes ` +
+        `(${err.message}). ${MAKE_ONE}`,
+    )
+  }
+}

package/src/uploader.js

@@ -5,7 +5,7 @@ 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 { DEFAULT_UPLOAD_CONCURRENCY, PART_SIZE, MAX_PARTS } from './chunking.js'
 import { withRetry } from './retry.js'
 import { DEFAULT_STALL_MS, withStallTimeout } from './stall.js'
 
@@ -39,7 +39,7 @@ export async function uploadRange(client, fd, options) {
     offset,
     length,
     fileName,
-    concurrency = DEFAULT_CONCURRENCY,
+    concurrency = DEFAULT_UPLOAD_CONCURRENCY,
     partSize = PART_SIZE,
     onProgress,
     retryOptions,