telstore 0.1.9 → 0.1.11

package/src/cipher.js

@@ -0,0 +1,211 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, hkdfSync, randomBytes, scrypt } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const derive = promisify(scrypt)
+
+// Pinned to manifest version 2 and never read from a manifest, for the reason src/token.js
+// pins its own: a manifest naming its own N would let a stranger decide how much memory this
+// machine allocates, and whoever holds a manifest can try passwords offline as fast as their
+// hardware allows — 64MB per attempt is what makes that expensive.
+const SCRYPT = { N: 65536, r: 8, p: 1, maxmem: 128 * 1024 * 1024 }
+const KEY_BYTES = 32
+const SALT_BYTES = 16
+const IV_BYTES = 8
+const NONCE_BYTES = 12
+const TAG_BYTES = 16
+const BLOCK = 16
+const SHA256 = /^[0-9a-f]{64}$/
+
+// Large enough that a 1800MB chunk is a couple of hundred reads, and a multiple of the AES
+// block so a full pass never needs the partial-block path.
+const IN_PLACE_BLOCK = 8 * 1024 * 1024
+
+export function newSalt() {
+  return randomBytes(SALT_BYTES).toString('hex')
+}
+
+// Fresh for every attempt at a chunk, never derived from its index: a run that dies halfway
+// through chunk 3 leaves parts of it on Telegram's servers, and a derived nonce would put the
+// next run's chunk 3 — possibly different bytes, if the file changed — under the same keystream.
+export function newIv() {
+  return randomBytes(IV_BYTES).toString('hex')
+}
+
+// Two keys, because GCM is CTR inside: one key used for both would let a counter block of the
+// manifest seal coincide with a counter block of some chunk.
+export async function deriveKeys(password, salt) {
+  const saltBytes = Buffer.from(salt, 'hex')
+  const master = await derive(String(password).normalize('NFC'), saltBytes, KEY_BYTES, SCRYPT)
+
+  return {
+    chunkKey: Buffer.from(hkdfSync('sha256', master, saltBytes, 'telstore v2 chunk key', KEY_BYTES)),
+    manifestKey: Buffer.from(hkdfSync('sha256', master, saltBytes, 'telstore v2 manifest key', KEY_BYTES)),
+  }
+}
+
+// What an unfinished upload keeps on disk instead of the password: enough to refuse a resume
+// under a different one, which would put two keys into one backup.
+export function passwordCheck(keys) {
+  return createHmac('sha256', keys.manifestKey).update('telstore v2 password check').digest('hex')
+}
+
+// CTR at any offset inside a chunk: the counter block for byte `offset` is the chunk's iv
+// followed by the 64-bit block number, and the bytes before `offset` inside that block are
+// discarded. A chunk is at most 1950MB, about 1.3e8 blocks, so the counter never carries into
+// the iv.
+export function chunkCipher(chunkKey, iv) {
+  const prefix = Buffer.from(iv, 'hex')
+
+  return {
+    apply(bytes, offset) {
+      const counter = Buffer.alloc(BLOCK)
+      prefix.copy(counter, 0)
+      counter.writeBigUInt64BE(BigInt(Math.floor(offset / BLOCK)), IV_BYTES)
+
+      const cipher = createCipheriv('aes-256-ctr', chunkKey, counter)
+      const skip = offset % BLOCK
+
+      if (skip > 0) cipher.update(Buffer.alloc(skip))
+
+      return Buffer.concat([cipher.update(bytes), cipher.final()])
+    },
+  }
+}
+
+// Built from the fields, in one fixed order, and never by serializing the parsed object again:
+// an array has one serialization, while an object's depends on the key order of a file a person
+// can edit. Every field is covered, the readable ones included. That proves the hint genuine only
+// once a password opens the seal, and it is printed before then, so it is also made safe to print
+// (terminalSafe in src/caption.js) rather than trusted because of this.
+export function additionalData(manifest) {
+  return Buffer.from(
+    JSON.stringify([
+      'telstore-enc-v2',
+      manifest.id,
+      manifest.name,
+      manifest.size,
+      manifest.chunkSize,
+      manifest.createdAt,
+      manifest.note ?? null,
+      manifest.enc.salt,
+      manifest.enc.hint ?? null,
+      manifest.chunks.map((chunk) => [chunk.i, chunk.msgId, chunk.size, chunk.sha256, chunk.iv]),
+    ]),
+    'utf8',
+  )
+}
+
+export function sealManifest(manifest, keys, plainSha256) {
+  const nonce = randomBytes(NONCE_BYTES)
+  const cipher = createCipheriv('aes-256-gcm', keys.manifestKey, nonce)
+
+  cipher.setAAD(additionalData(manifest))
+
+  const body = Buffer.concat([cipher.update(JSON.stringify({ plainSha256 }), 'utf8'), cipher.final()])
+
+  return {
+    ...manifest,
+    enc: {
+      ...manifest.enc,
+      sealed: Buffer.concat([nonce, cipher.getAuthTag(), body]).toString('base64'),
+    },
+  }
+}
+
+// Null when the tag fails, which is one failure with two causes — a wrong password or an
+// altered manifest — and the caller is the one that decides whether to ask again. Past the tag
+// the contents are ours, so anything malformed there is a telstore that disagreed with this one
+// about the format, and that throws rather than reading as a wrong password.
+export async function openManifest(manifest, password) {
+  const keys = await deriveKeys(password, manifest.enc.salt)
+  const sealed = Buffer.from(manifest.enc.sealed, 'base64')
+
+  if (sealed.length <= NONCE_BYTES + TAG_BYTES) return null
+
+  const decipher = createDecipheriv('aes-256-gcm', keys.manifestKey, sealed.subarray(0, NONCE_BYTES))
+  decipher.setAAD(additionalData(manifest))
+  decipher.setAuthTag(sealed.subarray(NONCE_BYTES, NONCE_BYTES + TAG_BYTES))
+
+  let text
+  try {
+    text = Buffer.concat([
+      decipher.update(sealed.subarray(NONCE_BYTES + TAG_BYTES)),
+      decipher.final(),
+    ]).toString('utf8')
+  } catch {
+    return null
+  }
+
+  let inside = null
+  try {
+    inside = JSON.parse(text)
+  } catch {
+    // Falls through to the refusal below.
+  }
+
+  const hashes = inside?.plainSha256
+
+  if (
+    !Array.isArray(hashes) ||
+    hashes.length !== manifest.chunks.length ||
+    !hashes.every((hash) => typeof hash === 'string' && SHA256.test(hash))
+  ) {
+    throw new Error(
+      `The manifest of ${manifest.id} opened, but what is sealed inside it is not what telstore ` +
+        'writes. Refusing to restore from it.',
+    )
+  }
+
+  return { keys, plainSha256: hashes }
+}
+
+async function readFully(handle, buffer, length, position) {
+  let filled = 0
+
+  while (filled < length) {
+    const { bytesRead } = await handle.read(buffer, filled, length - filled, position + filled)
+
+    if (bytesRead === 0) {
+      throw new Error(`Short read: needed ${length} bytes at offset ${position} but the file ended.`)
+    }
+
+    filled += bytesRead
+  }
+}
+
+async function writeFully(handle, buffer, position) {
+  let written = 0
+
+  while (written < buffer.length) {
+    const { bytesWritten } = await handle.write(buffer, written, buffer.length - written, position + written)
+
+    // readFully's guard, for the same reason: a write that makes no progress would spin here
+    // forever rather than fail, and a .partial half-decrypted with nobody told is the worst end.
+    if (bytesWritten === 0) {
+      throw new Error(`Short write: ${buffer.length - written} bytes at offset ${position + written} would not go to disk.`)
+    }
+
+    written += bytesWritten
+  }
+}
+
+// Reads a range that holds a verified chunk's ciphertext, writes its plaintext back over it,
+// and hashes the plaintext on the way. Called only after the ciphertext sha256 has matched, so
+// the hash it returns is the second check, not the first.
+export async function decryptInPlace(handle, offset, length, cipher, { blockSize = IN_PLACE_BLOCK } = {}) {
+  const hash = createHash('sha256')
+  const buffer = Buffer.allocUnsafe(Math.min(blockSize, Math.max(length, 1)))
+
+  for (let at = 0; at < length; at += blockSize) {
+    const size = Math.min(blockSize, length - at)
+
+    await readFully(handle, buffer, size, offset + at)
+
+    const clear = cipher.apply(buffer.subarray(0, size), at)
+
+    hash.update(clear)
+    await writeFully(handle, clear, offset + at)
+  }
+
+  return hash.digest('hex')
+}

package/src/cli.js

@@ -1,26 +1,44 @@
 import { basename } from 'node:path'
 import { parseArgs } from 'node:util'
 
+import { deleteCommand } from './shell.js'
+import { archiveName } from './tar.js'
+
+// The shortcuts dispatch by name, not through SUBCOMMANDS: what they return is not a command
+// called `tarc`, it is an upload (or, for `tarx`, a restore) with the line already
+// rewritten into the form that command understands — there is no `runTarc` for SUBCOMMANDS to
+// route to. They still belong in the set below all the same, because SUBCOMMANDS is the list of
+// words telstore will not read as a file name, and a shortcut claims one exactly as a
+// subcommand does.
+const SHORTCUTS = new Map([
+  ['tarc', tarcLine],
+  ['tarx', tarxLine],
+])
+
 const SUBCOMMANDS = new Set([
   'login',
   'logout',
+  'down',
   'list',
   'restore',
   'verify',
   'delete',
+  'join',
   'status',
   'config',
   'token',
   'help',
+  ...SHORTCUTS.keys(),
 ])
 
-const OPTIONS = {
+export const OPTIONS = {
   chat: { type: 'string' },
   'chunk-size': { type: 'string' },
   'upload-concurrency': { type: 'string' },
   'download-concurrency': { type: 'string' },
   out: { type: 'string' },
   note: { type: 'string' },
+  encrypt: { type: 'boolean' },
   limit: { type: 'string' },
   search: { type: 'string' },
   verbose: { type: 'boolean' },
@@ -35,14 +53,20 @@ export const HELP = `telstore — split large files into chunks and store them o
 Usage:
   npx telstore login                      Log in to Telegram, only needed once
   npx telstore <file|folder|pattern>...   Split files and upload them to Telegram
+  npx telstore <name> -- <command>...     Store what a command writes, under <name>
+  npx telstore tarc <name> <path>...      Archive paths with tar and store the archive
+  npx telstore tarx <backup-id>           Restore a backup and extract it with tar
+  npx telstore restore <id> -- <cmd>...   Restore onto a command instead of a file
   npx telstore list                       List the backups stored in the destination
   npx telstore list --search <text>       List only the backups that text appears in
   npx telstore restore <backup-id>...     Download the chunks and reassemble the files
   npx telstore verify <backup-id>...      Check that a backup's chunks are all still in the chat
   npx telstore delete <backup-id>...      Remove backups' chunks and manifests from the chat
+  npx telstore join <manifest.json>       Reassemble chunks you downloaded by hand, offline
   npx telstore status                     Show the account, the destination and unfinished uploads and restores
   npx telstore config                     Show every setting and where its value comes from
   npx telstore logout                     Remove the saved session
+  npx telstore down                       Remove everything telstore keeps on this machine
 
 Running on a machine you do not trust:
   npx telstore token                      Print a session token for another machine
@@ -54,11 +78,42 @@ backup. A folder means the files one level inside it, and a pattern means the na
 one file is listed and confirmed before the first byte goes out. Run telstore again with only
 the files that are left to carry on after an interruption.
 
+A name followed by -- makes the backup out of what a command writes, so nothing has to be on
+disk first: npx telstore a.tar -- tar cf - ./a. The manifest goes out only if that command's
+output ended and the command exited 0 — an end after a crash looks exactly like an end after
+success, and running the command is how telstore tells them apart. A backup made this way
+cannot be resumed, so a run that fails, and a Ctrl-C, remove the chunks already sent rather
+than keeping them for a second run there will never be. No shell stands in between: a pipeline
+goes in as -- bash -c 'set -o pipefail; ...', which is also where compression or encryption
+belongs. The pipefail is not decoration — a shell reports the last command's exit status, so
+without it a producer that dies halfway through a pipeline still exits 0 and the manifest goes
+out for a truncated backup.
+
+tarc and tarx are the common case written out once: "npx telstore tarc a.tar.gz ./dir"
+is "npx telstore a.tar.gz -- tar czf - ./dir", and tarx is the same for "restore <id> --
+tar xzf -". telstore prints the long form as it runs, so the shortcut teaches what it is
+short for. tarc always compresses, so it makes the name say so: a.tar becomes a.tar.gz,
+and a name with no tar in it at all gets .tar.gz. --verbose adds tar's own file listing
+to both. For tarx, --out is the directory it extracts into, and tar's own semantics apply
+there: it overwrites files already in it without asking, unlike restore's one-file [y/N]
+prompt — --out is how you aim it somewhere empty instead. Anything beyond archiving
+the paths — -C, --exclude, a pipeline, another compressor — is what -- is still for.
+
+down is logout taken all the way: it removes ~/.telstore entirely — the session, the api_id
+and api_hash, every setting and every resume record — and asks once before it does. It opens
+no connection and deletes nothing from Telegram: the backups stay in the chat, and the session
+stays alive on Telegram's side until you terminate it under Settings → Devices.
+
 restore, verify and delete take several ids the same way: one connection, one line each, and
 an exit code that reports any that failed. delete shows everything it is about to destroy and
 asks once. verify downloads nothing: it asks the chat whether every chunk message is still
 there at the length the manifest records, which is what restore would need.
 
+join is restore without Telegram, for chunks you downloaded yourself — from Telegram web, say.
+Put the manifest and every <id>.partNNNN file in one folder under the names they have in the
+chat, and point join at the manifest. It needs no login and opens no connection, and it checks
+each chunk's size and sha256 against the manifest before the file takes its real name.
+
 Settings:
   npx telstore config <name>              Print one setting's value
   npx telstore config <name> <value>      Change it for good
@@ -77,14 +132,20 @@ Options apply to one run and are never saved. Use config to change a setting for
                               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, and works with one backup id only.
+  --out <path>                Where to write the restored or joined file. Defaults to the
+                              basename in the manifest, and works with one backup id only.
   --note <text>               A note to store with the upload. It goes into the manifest and
                               onto the manifest message, where Telegram's own search can find
                               it, and every file of a batch gets the same one. A note with
                               spaces in it has to be quoted — --note "march archive" — or the
                               shell hands the words after the first to telstore as more files
                               to upload.
+  --encrypt                   Encrypt the contents with a password before they leave this
+                              machine. Asks for the password twice and for an optional hint,
+                              which is shown in the chat as plain text. restore, tarx and join
+                              see from the manifest that a backup is encrypted and ask for the
+                              password themselves. The file name, note and size stay readable,
+                              and a forgotten password is a lost backup.
   --limit <n>                 How many backups list shows this run.
   --search <text>             List only the backups whose file name, note, backup id or
                               creation day contains this text. Telegram's own index does
@@ -96,7 +157,8 @@ Options apply to one run and are never saved. Use config to change a setting for
                               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                       Upload a batch, or delete, without being asked to confirm.
+  --yes                       Upload a batch, delete, or wipe this machine with down,
+                              without being asked to confirm.
   --verbose                   Show Telegram connection logs for this run.
   -h, --help                  Show this help.
 `
@@ -105,7 +167,54 @@ Options apply to one run and are never saved. Use config to change a setting for
 // finished chunk to a state file, restore has not. Naming the backup matters because the
 // id is what `status` lists and what a later `restore` needs — the chunks are already in
 // the chat under that id, whether or not this run ever finishes.
-export function interruptMessage(command, { backupId, done = [] } = {}) {
+export function interruptMessage(
+  command,
+  { backupId, done = [], stream = false, again = false, chat = null } = {},
+) {
+  // A backup made from a command is the one upload Ctrl-C cannot leave where it is. The bytes
+  // have gone past and the next run cuts them differently, so a chunk already in the chat is
+  // a chunk no manifest will ever name — which is why this run is asked to remove them and
+  // the process waits, rather than promising the resume the file wording promises.
+  if (command === 'upload' && stream) {
+    // Nothing is in the chat until there is an id to put it under, and a run stopped before
+    // that has nothing for anyone to clean up.
+    if (!backupId) {
+      return '\nStopped before anything was sent.\n'
+    }
+
+    if (again) {
+      // "may still" because this is said while the removal is halfway through and nobody
+      // knows how far it got. `deleteCommand` is what names the chat, and why: a later
+      // `delete` resolves its destination from config, and these ids fired at the wrong peer
+      // destroy whatever happens to carry them there. A null chat here is a Ctrl-C that
+      // landed before the run said where it was sending — the chatless branch documented
+      // beside that function is for exactly this caller.
+      const removal = deleteCommand(backupId, chat)
+
+      return (
+        `\nLeaving now. Backup ${backupId} may still have chunks in the chat with no manifest ` +
+        `pointing at them — run "${removal}" to remove them.\n`
+      )
+    }
+
+    return (
+      `\nStopping. Backup ${backupId} was made from a command and cannot be resumed, so ` +
+      'telstore is removing the chunks it already sent. This takes a moment — press Ctrl-C ' +
+      'again to leave now and clean up by hand.\n'
+    )
+  }
+
+  // The restore direction of the same idea, and the difference is the whole message: a stream
+  // upload has to unwind what it put in the chat, while this one put nothing there. What it
+  // cannot put back is what the command already did with the bytes it was given.
+  if (command === 'restore' && stream) {
+    return (
+      '\nStopped. Nothing in the chat changed and nothing was kept on this machine, but the ' +
+      'command had already been given part of the backup, so whatever it wrote from that is ' +
+      'incomplete. A restore into a command cannot be resumed — run it again from the start.\n'
+    )
+  }
+
   if (command === 'upload') {
     const backup = backupId ? `Backup ${backupId} is saved` : 'Progress is saved'
 
@@ -176,9 +285,28 @@ export function interruptMessage(command, { backupId, done = [] } = {}) {
     )
   }
 
+  // A join writes nothing under the real name until the end, and the half-joined file is
+  // removed on the way out, so there is nothing to carry on from — and nothing in the chat
+  // it could have touched.
+  if (command === 'join') {
+    return '\nStopped. Nothing was joined — run the same command again to start over.\n'
+  }
+
   return '\nStopped.\n'
 }
 
+// The one `--` this file did not write. protectNegativeChatIds, below, inserts one of its
+// own to rescue a negative chat id from parseArgs, so the position has to be taken off the
+// argv as typed — afterwards the two are indistinguishable, and `config chat -100123` would
+// become a command telstore tries to run.
+function splitAtTerminator(argv) {
+  const at = argv.indexOf('--')
+
+  if (at === -1) return { head: argv, childArgv: null }
+
+  return { head: argv.slice(0, at), childArgv: argv.slice(at + 1) }
+}
+
 // A channel id is negative, and typing it separated by a space is the natural reflex — but
 // parseArgs rejects anything starting with a dash as an option, and reports it as one:
 // `config chat -100123` fails with "Unknown option '-1'", naming a flag nobody typed.
@@ -233,9 +361,80 @@ function filesNamedAfterNote(tokens) {
   return tokens.some((token) => token.kind === 'positional' && token.index > note.index)
 }
 
-export function route(argv) {
+// tarc is the long form with the three decisions that never change already made: `c` for
+// create, `z` for gzip, `f -` for "write it to stdout, which is where telstore is listening".
+// The missing `-` is not a hypothetical mistake — this project's own help text and README
+// shipped exactly that omission once, and paid for it with an example that exited 2 instead
+// of writing a backup.
+//
+// An expansion rather than a command of its own: `runStreamUpload` is reached with exactly the
+// argv the `--` form reaches it with, so there is no second upload path, no second rollback
+// and no second guarantee. It also prints that argv, so the shortcut teaches the long form
+// instead of hiding it.
+function tarcLine(rest, values, filesAfterNote) {
+  const [name, ...paths] = rest
+
+  if (name === undefined) {
+    throw new Error(
+      'Missing a name for the backup. tarc stores the archive under a name you choose. ' +
+        'Example: npx telstore tarc a.tar.gz ./a',
+    )
+  }
+
+  // Refused rather than answered with a guess: a rule that read one positional as a name and
+  // two as a name plus a path would make `telstore tarc ./x ./y` archive ./y under the name
+  // ./x, which is the silent wrong answer this project exists to refuse.
+  if (paths.length === 0) {
+    throw new Error(
+      `Nothing to archive: tarc needs the paths to put in ${name}. ` +
+        'Example: npx telstore tarc a.tar.gz ./a',
+    )
+  }
+
+  return {
+    command: 'upload',
+    args: [archiveName(name)],
+    options: values,
+    filesAfterNote,
+    childArgv: ['tar', values.verbose ? 'czvf' : 'czf', '-', ...paths],
+    shortcut: 'tarc',
+  }
+}
+
+// The mirror of tarcLine. `x` for extract, `z` because tarc always compressed, `f -` because
+// the bytes arrive on stdin.
+function tarxLine(rest, values, filesAfterNote) {
+  requireOneBackupId(rest, 'tarx')
+
+  const childArgv = ['tar', values.verbose ? 'xzvf' : 'xzf', '-']
+
+  // Pushed after `-` on purpose, which is the order measured to work on GNU tar 1.35:
+  // `tar xzf - -C ./here`. See the probe table in the spec.
+  if (values.out !== undefined) childArgv.push('-C', values.out)
+
+  return { command: 'restore', args: rest, options: values, filesAfterNote, childArgv, shortcut: 'tarx' }
+}
+
+// One command reads one stream, so a line that names two backups is a line with no answer:
+// extracting two archives into one working directory in sequence is a question nobody asked.
+function requireOneBackupId(ids, what) {
+  if (ids.length === 0) {
+    throw new Error(`Missing backup id. Example: npx telstore ${what} telstore-20260905-7f3a91`)
+  }
+
+  if (ids.length > 1) {
+    throw new Error(
+      `One command reads one stream, so ${what} takes one backup id and got ${ids.length}: ` +
+        `${ids.join(', ')}. Run telstore once per backup.`,
+    )
+  }
+}
+
+function routeLine(argv) {
+  const { head, childArgv } = splitAtTerminator(argv)
+
   const { values, positionals, tokens } = parseArgs({
-    args: protectNegativeChatIds(argv),
+    args: protectNegativeChatIds(head),
     options: OPTIONS,
     allowPositionals: true,
     tokens: true,
@@ -244,26 +443,135 @@ export function route(argv) {
   const [first, ...rest] = positionals
   const filesAfterNote = filesNamedAfterNote(tokens)
 
+  // --help (or -h, or the `help` subcommand) always wins, terminator or not: someone typing
+  // `telstore --help -- tar cf - ./a` is asking what telstore does, not making a mistake for
+  // one of the checks below to catch.
+  if (values.help || first === 'help') {
+    return { command: 'help', args: [], options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
+  if (childArgv !== null && childArgv.length === 0) {
+    throw new Error(
+      'Missing the command after --: telstore has nothing to run and store. ' +
+        'Example: npx telstore a.tar -- tar cf - ./a',
+    )
+  }
+
+  // A terminator changes what "no name" and "which command" mean, so it is read before the
+  // ordinary help/chat fallbacks get a chance to answer for it — those apply to a line that
+  // never named a command to run at all.
+  if (childArgv !== null) {
+    // Reached before the generic "takes no command after --" below, because for these two the
+    // reason is different and so is the way out: they are not a subcommand that happens not to
+    // run commands, they are a command already.
+    if (SHORTCUTS.has(first)) {
+      throw new Error(
+        `${first} already is the command it runs, so it cannot be followed by another one. ` +
+          `Drop the -- to use ${first}, or drop ${first} to write the command out yourself.`,
+      )
+    }
+
+    if (first !== undefined && SUBCOMMANDS.has(first)) {
+      // restore is let through rather than refused here, and the binary is what turns it away.
+      // The shape is the spec's stage 2, so the parser keeps it whole — but a refusal that
+      // says "not built yet, restore to a file and pipe that" belongs where the command runs,
+      // beside the alternative it is offering, not in an argument parser.
+      if (first !== 'restore') {
+        throw new Error(
+          `${first} takes no command after --. An upload (npx telstore a.tar -- tar cf - ./a) ` +
+            'and a restore (npx telstore restore <id> -- tar xf -) are the two that run one.',
+        )
+      }
+
+      requireOneBackupId(rest, 'restore')
+
+      // --out places a file, and this path writes none: the bytes go to the command on its
+      // stdin. Left to pass silently it would read as "restore into the command AND write
+      // the file over there", which is not what happens.
+      if (values.out !== undefined) {
+        throw new Error(
+          'A restore into a command writes no file, so --out has nothing to place: the bytes ' +
+            'go to the command on its stdin. Tell the command where to put them instead ' +
+            '(npx telstore restore <id> -- tar xf - -C ./here).',
+        )
+      }
+
+      return { command: first, args: rest, options: values, filesAfterNote, childArgv, shortcut: null }
+    }
+
+    if (positionals.length === 0) {
+      throw new Error(
+        'Missing a name before --. telstore stores what the command writes under a name you ' +
+          'choose, and there is nothing to take one from. Example: npx telstore a.tar -- tar cf - ./a',
+      )
+    }
+
+    if (positionals.length > 1) {
+      throw new Error(
+        `One command produces one stream, so telstore takes one name before -- and got ` +
+          `${positionals.length}: ${positionals.join(', ')}. Run telstore once per backup.`,
+      )
+    }
+
+    return { command: 'upload', args: positionals, options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
   // `telstore --chat @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.chat && !values.help) {
+  // perfectly clear about what they wanted. (values.help already returned above, so reaching
+  // here means it was never set.)
+  if (first === undefined && values.chat) {
     throw new Error(
       `Nothing to upload. To change the destination for good, run "npx telstore config chat ${values.chat}". ` +
         'To use it for one run, pass --chat alongside a file or a command.',
     )
   }
 
-  if (values.help || first === undefined || first === 'help') {
-    return { command: 'help', args: [], options: values, filesAfterNote }
+  if (first === undefined) {
+    return { command: 'help', args: [], options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
+  const shortcut = SHORTCUTS.get(first)
+  if (shortcut) return shortcut(rest, values, filesAfterNote)
+
+  // --out names one file, and each manifest is one file: a second manifest on the line would
+  // have to be written somewhere nobody said.
+  if (first === 'join') {
+    if (rest.length === 0) {
+      throw new Error(
+        'Missing the manifest to join. Example: npx telstore join ./telstore-20260905-7f3a91.manifest.json',
+      )
+    }
+
+    if (rest.length > 1) {
+      throw new Error(
+        `join takes one manifest and got ${rest.length}: ${rest.join(', ')}. Run it once per backup.`,
+      )
+    }
   }
 
   if (SUBCOMMANDS.has(first)) {
-    return { command: first, args: rest, options: values, filesAfterNote }
+    return { command: first, args: rest, options: values, filesAfterNote, childArgv, shortcut: null }
   }
 
   // Every positional, not just the first: `telstore a b c` used to upload `a` and drop the
   // rest without a word, which is the one thing this project never does.
-  return { command: 'upload', args: positionals, options: values, filesAfterNote }
+  return { command: 'upload', args: positionals, options: values, filesAfterNote, childArgv, shortcut: null }
+}
+
+// Encryption is decided when a backup is made; every command that reads one learns it from the
+// manifest. A flag beside a restore would read as "decrypt with this", which it would not be,
+// and a flag that silently does nothing is one nobody can predict without the source.
+export function route(argv) {
+  const parsed = routeLine(argv)
+
+  if (parsed.options.encrypt && parsed.command !== 'upload' && parsed.command !== 'help') {
+    throw new Error(
+      '--encrypt applies to uploads only. restore, tarx and join see from the manifest that a ' +
+        'backup is encrypted and ask for its password by themselves.',
+    )
+  }
+
+  return parsed
 }

package/src/client.js

@@ -76,9 +76,15 @@ async function* iterMessagePages(client, peer, { search, what, options }) {
     max = Infinity,
     retryOptions = {},
     stallMs = DEFAULT_STALL_MS,
+    // Where the walk begins, as the id of the message just above the first one wanted. 0 is
+    // "the newest in the chat", which is what list asks for. delete starts at a backup's own
+    // manifest instead when the chat has shown it one: the manifest is the last message a
+    // backup's run sends, so nothing of that backup is newer, and everything posted since is
+    // a page of documents read for nothing.
+    offsetId: startId = 0,
   } = options
 
-  let offsetId = 0
+  let offsetId = startId
   let read = 0
 
   while (read < max) {