telstore 0.1.10 → 0.1.11

package/src/commands/upload.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 
@@ -5,11 +6,20 @@ import { Api } from 'teleproto'
 import { CustomFile } from 'teleproto/client/uploads.js'
 
 import { PART_SIZE, planChunks } from '../chunking.js'
-import { chunkCaption, manifestCaption, parseNote } from '../caption.js'
+import {
+  MAX_HINT_LENGTH,
+  chunkCaption,
+  hasControlCharacter,
+  manifestCaption,
+  parseNote,
+  terminalSafe,
+} from '../caption.js'
+import { chunkCipher, deriveKeys, newIv, newSalt, passwordCheck, sealManifest } from '../cipher.js'
 import { describeChat } from '../chat.js'
 import { closeQuietly, connect as realConnect } from '../client.js'
 import { askConfirm } from '../confirm.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import { askNewPassword as realAskNewPassword, askPassword as realAskPassword } from '../password.js'
 import { expandSources } from '../sources.js'
 import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
@@ -24,6 +34,7 @@ import { createProgress, formatBytes, formatDuration } from '../progress.js'
 import {
   MAX_STATES,
   clearState,
+  encryptedStateKey,
   loadState,
   markChunkDone,
   pruneStates,
@@ -139,6 +150,31 @@ async function statSource(absPath, { note = null, filesAfterNote = false } = {})
   return stat
 }
 
+// The plaintext hashes the seal carries, read from the record that collected them one chunk at
+// a time — possibly across several runs. A record that lost one cannot produce a manifest that
+// decrypts, and sending one anyway would be a backup that restores to nothing.
+function plainHashesOf(state, chunks, file) {
+  return chunks.map((chunk) => {
+    const entry = state.done[String(chunk.i)]
+
+    if (
+      typeof entry?.iv !== 'string' ||
+      !/^[0-9a-f]{16}$/.test(entry.iv) ||
+      typeof entry.plainSha256 !== 'string' ||
+      !/^[0-9a-f]{64}$/.test(entry.plainSha256)
+    ) {
+      throw new Error(
+        `The record of this unfinished backup has no encryption details for chunk ${chunk.i + 1}, ` +
+          `so telstore cannot write a manifest that decrypts it. ${file} is damaged — delete it ` +
+          'and run again to start a new backup, which leaves the chunks already sent sitting in ' +
+          'the chat with nothing to point at them.',
+      )
+    }
+
+    return entry.plainSha256
+  })
+}
+
 export async function runUpload(filePath, options = {}, deps = {}) {
   const {
     connect = realConnect,
@@ -155,6 +191,10 @@ export async function runUpload(filePath, options = {}, deps = {}) {
     // Where on the command line the note sat, as `route` saw it. Nothing else can know, and
     // a run that never says leaves the advice unsaid rather than guessed at.
     filesAfterNote = false,
+    askNewPassword = realAskNewPassword,
+    askPassword = realAskPassword,
+    // A batch asks once and hands the answer to every file, rather than once per file.
+    secret = null,
   } = deps
 
   const absPath = path.resolve(filePath)
@@ -174,9 +214,57 @@ export async function runUpload(filePath, options = {}, deps = {}) {
   const chat = requireChat(settings)
   const concurrency = settings.uploadConcurrency
 
-  const key = stateKey(absPath, stat.size, stat.mtimeMs)
+  const encrypt = Boolean(options.encrypt)
+
+  // An encrypted record lives under a key of its own so an older telstore cannot find it (see
+  // encryptedStateKey). This run reads and writes its own key only, and looks under the other one
+  // just to refuse: a record there is this same file, unfinished the other way round.
+  const plainKey = stateKey(absPath, stat.size, stat.mtimeMs)
+  const encryptedKey = encryptedStateKey(absPath, stat.size, stat.mtimeMs)
+  const key = encrypt ? encryptedKey : plainKey
+  const otherKey = encrypt ? plainKey : encryptedKey
 
   let state = await loadState(key, configDir)
+  const other = await loadState(otherKey, configDir)
+
+  // A record whose kind disagrees with the key it is filed under was not written by this build —
+  // a hand edit, or this branch before encrypted records moved. One carrying `enc` under the plain
+  // key is exactly what an older telstore would resume in plain, so neither kind is trusted to say
+  // which way it goes: both are refused as damaged, whichever way this run was asked to go.
+  const filed = [
+    { filedUnder: plainKey, record: encrypt ? other : state, encrypted: false },
+    { filedUnder: encryptedKey, record: encrypt ? state : other, encrypted: true },
+  ]
+
+  for (const { filedUnder, record, encrypted } of filed) {
+    if (record && Boolean(record.enc) !== encrypted) {
+      throw new Error(
+        `The record of this unfinished backup says it is ${record.enc ? '' : 'not '}encrypted but is ` +
+          `filed where ${record.enc ? 'a plain' : 'an encrypted'} one belongs, so telstore cannot ` +
+          `tell how the chunks already sent went up. ${stateFile(filedUnder, configDir)} is damaged — ` +
+          'delete it and run again to start a new backup, which leaves the chunks already sent ' +
+          'sitting in the chat with nothing to point at them.',
+      )
+    }
+  }
+
+  // An unfinished backup is encrypted or it is not, and the chunks already in the chat decide
+  // which. Carrying on the other way would mix plaintext and ciphertext in one backup no manifest
+  // could describe, so a run that disagrees is refused the way a disagreeing --chunk-size is.
+  if (other) {
+    const file = stateFile(otherKey, configDir)
+
+    throw new Error(
+      other.enc
+        ? `This unfinished backup is encrypted, and this run has no --encrypt. Run again with ` +
+            `--encrypt to carry on, or delete ${file} and run again to start a new backup, which ` +
+            'leaves the chunks already sent sitting in the chat with nothing to point at them.'
+        : `This unfinished backup is not encrypted, and this run asks for --encrypt — the chunks ` +
+            `already in ${other.chat} went up as they are. Run again without --encrypt to carry ` +
+            `on, or delete ${file} and run again to start a new, encrypted backup, which leaves ` +
+            'the chunks already sent sitting in the chat with nothing to point at them.',
+    )
+  }
 
   // The chunks already in the chat were cut at the size this backup started with, and
   // nothing can re-cut them. Carrying on at a different size would abandon every one of
@@ -227,6 +315,59 @@ export async function runUpload(filePath, options = {}, deps = {}) {
     )
   }
 
+  let keys = null
+  let enc = null
+
+  if (encrypt && resuming) {
+    if (
+      typeof state.enc?.salt !== 'string' ||
+      !/^[0-9a-f]{32}$/.test(state.enc.salt) ||
+      typeof state.enc.check !== 'string' ||
+      // The record's hint goes into the manifest, and parseManifest refuses one that is not text,
+      // too long, or carrying a control character. Caught here it is a damaged record; caught at
+      // restore it would be a backup that uploaded cleanly and can never be restored.
+      (state.enc.hint !== undefined &&
+        (typeof state.enc.hint !== 'string' ||
+          state.enc.hint.length > MAX_HINT_LENGTH ||
+          hasControlCharacter(state.enc.hint)))
+    ) {
+      throw new Error(
+        'The record of this unfinished backup says it is encrypted but does not carry what is ' +
+          `needed to carry on encrypting it. ${stateFile(key, configDir)} is damaged — delete it ` +
+          'and run again to start a new backup, which leaves the chunks already sent sitting in ' +
+          'the chat with nothing to point at them.',
+      )
+    }
+
+    // The password is asked for again rather than kept: nothing on this disk can decrypt the
+    // chunks already in the chat. The check refuses a different one, which would put two keys
+    // into a single backup.
+    const password =
+      secret?.password ??
+      (await askPassword(`Password for ${state.id}${state.enc.hint ? ` (hint: ${terminalSafe(state.enc.hint)})` : ''}: `))
+
+    keys = await deriveKeys(password, state.enc.salt)
+
+    if (passwordCheck(keys) !== state.enc.check) {
+      throw new Error(
+        `That is not the password backup ${state.id} was started with, and the chunks already in ` +
+          `${state.chat} are encrypted with that one. Run again and type the first password, or ` +
+          `delete ${stateFile(key, configDir)} and run again to start a new backup, which leaves ` +
+          'the chunks already sent sitting in the chat with nothing to point at them.',
+      )
+    }
+
+    enc = state.enc
+  } else if (encrypt) {
+    // Before the record and before the connection: a run that cannot get a password has written
+    // nothing and opened nothing.
+    const chosen = secret ?? (await askNewPassword())
+    const salt = newSalt()
+
+    keys = await deriveKeys(chosen.password, salt)
+    enc = { salt, check: passwordCheck(keys), ...(chosen.hint ? { hint: chosen.hint } : {}) }
+  }
+
   if (!resuming) {
     state = {
       id: newBackupId(),
@@ -235,6 +376,7 @@ export async function runUpload(filePath, options = {}, deps = {}) {
       size: stat.size,
       mtimeMs: stat.mtimeMs,
       chunkSize,
+      ...(enc ? { enc } : {}),
       done: {},
     }
     await saveState(key, state, configDir)
@@ -260,6 +402,7 @@ export async function runUpload(filePath, options = {}, deps = {}) {
 
   log(`Backup ${state.id}`)
   log(`File   ${absPath} (${formatBytes(stat.size)}, ${chunks.length} chunks)`)
+  if (enc) log(`Lock   encrypted${enc.hint ? ` (hint: ${terminalSafe(enc.hint)})` : ''}`)
   log(`To     ${describeChat(chat)}\n`)
 
   const client = await connect(config, { verbose: settings.verbose })
@@ -303,6 +446,12 @@ export async function runUpload(filePath, options = {}, deps = {}) {
           const handle = await fs.open(absPath, 'r')
 
           try {
+            // A fresh iv per attempt at this chunk; see newIv in src/cipher.js for why it is never
+            // derived from the index.
+            const iv = keys ? newIv() : null
+            const cipher = keys ? chunkCipher(keys.chunkKey, iv) : null
+            const plain = keys ? createHash('sha256') : null
+
             const { inputFile, sha256 } = await uploadRange(client, handle.fd, {
               offset: chunk.offset,
               length: chunk.length,
@@ -311,6 +460,12 @@ export async function runUpload(filePath, options = {}, deps = {}) {
               partSize,
               onProgress: (bytes) => progress.advance(bytes),
               retryOptions: { ...retryOptions, onRetry },
+              transform: cipher
+                ? (bytes, at) => {
+                    plain.update(bytes)
+                    return cipher.apply(bytes, at)
+                  }
+                : undefined,
             })
 
             const message = await sendChunk(client, chat, {
@@ -323,7 +478,12 @@ export async function runUpload(filePath, options = {}, deps = {}) {
               key,
               state,
               chunk.i,
-              { msgId: message.id, size: chunk.length, sha256 },
+              {
+                msgId: message.id,
+                size: chunk.length,
+                sha256,
+                ...(cipher ? { iv, plainSha256: plain.digest('hex') } : {}),
+              },
               configDir,
             )
           } finally {
@@ -351,15 +511,18 @@ export async function runUpload(filePath, options = {}, deps = {}) {
       )
     }
 
-    const manifest = buildManifest({
+    let manifest = buildManifest({
       id: state.id,
       name: path.basename(absPath),
       size: stat.size,
       chunkSize,
       note,
+      enc: enc ? { salt: enc.salt, ...(enc.hint ? { hint: enc.hint } : {}) } : null,
       chunks: chunks.map((chunk) => ({ i: chunk.i, ...state.done[String(chunk.i)] })),
     })
 
+    if (keys) manifest = sealManifest(manifest, keys, plainHashesOf(state, chunks, stateFile(key, configDir)))
+
     await sendManifest(client, chat, {
       bytes: serializeManifest(manifest),
       fileName: manifestFileName(state.id),
@@ -370,6 +533,8 @@ export async function runUpload(filePath, options = {}, deps = {}) {
         chunks: manifest.chunks.length,
         createdAt: manifest.createdAt,
         note: manifest.note ?? null,
+        encrypted: Boolean(keys),
+        hint: manifest.enc?.hint ?? null,
       }),
     })
 
@@ -402,6 +567,7 @@ export async function runUploads(filePaths, options = {}, deps = {}) {
     confirm = askConfirm,
     interactive = () => Boolean(process.stdin.isTTY),
     filesAfterNote = false,
+    askNewPassword = realAskNewPassword,
   } = deps
 
   const log = silent ? () => {} : writeLog
@@ -488,12 +654,17 @@ export async function runUploads(filePaths, options = {}, deps = {}) {
     }
   }
 
+  // Once, after the list has been confirmed: nobody should type a password for a batch they are
+  // about to cancel. Every file still gets a salt of its own inside runUpload.
+  const secret = options.encrypt ? await askNewPassword() : null
+
   let shared = null
   const perFile = {
     ...deps,
     connect: async (theirConfig, connectOptions) =>
       (shared ??= await connect(theirConfig, connectOptions)),
     disconnect: async () => {},
+    secret,
   }
 
   const results = []

package/src/commands/verify.js

@@ -1,3 +1,4 @@
+import { terminalSafe } from '../caption.js'
 import { chatName, describeChat } from '../chat.js'
 import {
   MESSAGE_BATCH_SIZE,
@@ -10,7 +11,7 @@ import {
   readMessageBytes as realReadMessageBytes,
 } from '../client.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
-import { chunkFileName, manifestFileName, parseManifest } from '../manifest.js'
+import { chunkFileName, isEncrypted, manifestFileName, parseManifest } from '../manifest.js'
 import { formatBytes, formatDuration, plural } from '../progress.js'
 import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
@@ -131,6 +132,12 @@ export async function runVerify(backupId, options = {}, deps = {}) {
         `(${formatBytes(manifest.size)}, ${plural(total, 'chunk')})`,
     )
     log(`In     ${describeChat(chat)}`)
+
+    // Said, not checked: verify never has the password and never needs it. What it asks the chat
+    // about — presence, file name, length — is the same for ciphertext.
+    if (isEncrypted(manifest)) {
+      log(`Lock   encrypted${manifest.enc.hint ? ` (hint: ${terminalSafe(manifest.enc.hint)})` : ''}`)
+    }
     log('')
 
     // A backup at the 10000-chunk ceiling is a hundred requests, sent one at a time. Silence

package/src/manifest.js

@@ -1,9 +1,24 @@
 import { randomBytes } from 'node:crypto'
+import path from 'node:path'
 
+import { MAX_HINT_LENGTH, hasControlCharacter } from './caption.js'
 import { countChunks } from './chunking.js'
 
 export const MANIFEST_VERSION = 1
 
+// An encrypted backup's manifest, and only that. The bump is what stops an older telstore, which
+// checks `v` and nothing else it does not know: handed a version 1 manifest with an extra `enc`
+// in it, it would download the ciphertext, match every sha256 (they are the ciphertext's), match
+// the length (CTR keeps it), rename, and print Done over a file of random bytes.
+export const ENCRYPTED_MANIFEST_VERSION = 2
+
+const SALT_HEX = /^[0-9a-f]{32}$/
+const IV_HEX = /^[0-9a-f]{16}$/
+
+export function isEncrypted(manifest) {
+  return manifest?.v === ENCRYPTED_MANIFEST_VERSION
+}
+
 export function newBackupId(now = new Date(), randomHex = () => randomBytes(3).toString('hex')) {
   const yyyy = now.getUTCFullYear()
   const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
@@ -76,6 +91,24 @@ export function manifestFileName(id) {
   return `${id}${MANIFEST_SUFFIX}`
 }
 
+// manifest.name comes from data downloaded off Telegram — don't trust it when picking
+// a path ourselves. path.basename stops "../../x" but still returns "..", "." or "" for
+// a few pathological names: path.resolve('..') is the parent directory, so a multi-GB
+// file would land outside the current directory and only blow up at rename. Here rather
+// than in restore because join needs it too, and join must not import the network side.
+export function safeOutName(name) {
+  const base = path.basename(String(name ?? ''))
+
+  if (base === '' || base === '.' || base === '..') {
+    throw new Error(
+      `The name in the manifest ("${name}") cannot be used as a file name. ` +
+        'Run again with --out <path> to choose where to write.',
+    )
+  }
+
+  return base
+}
+
 export function buildManifest({
   id,
   name,
@@ -84,9 +117,10 @@ export function buildManifest({
   chunks,
   createdAt = new Date().toISOString(),
   note = null,
+  enc = null,
 }) {
   return {
-    v: MANIFEST_VERSION,
+    v: enc ? ENCRYPTED_MANIFEST_VERSION : MANIFEST_VERSION,
     id,
     name,
     size,
@@ -95,9 +129,19 @@ export function buildManifest({
     // Absent rather than null when there is none: a manifest without a note has to be the
     // same file telstore wrote before the flag existed, down to the bytes.
     ...(note ? { note } : {}),
+    // The same rule for encryption: a plain backup's manifest is today's manifest exactly.
+    ...(enc ? { enc } : {}),
+    // Picked field by field, which is also what keeps a chunk's plaintext hash out: it travels
+    // in the state record and in the seal, never in the open.
     chunks: [...chunks]
       .sort((a, b) => a.i - b.i)
-      .map(({ i, msgId, size: chunkBytes, sha256 }) => ({ i, msgId, size: chunkBytes, sha256 })),
+      .map(({ i, msgId, size: chunkBytes, sha256, iv }) => ({
+        i,
+        msgId,
+        size: chunkBytes,
+        sha256,
+        ...(enc ? { iv } : {}),
+      })),
   }
 }
 
@@ -148,12 +192,70 @@ export function manifestMessageIds(manifest) {
   })
 }
 
+// Structure only. Whether the seal opens is a question for the password, which verify never
+// has and never needs — so everything here is answerable from the file alone.
+function checkEncryption(manifest) {
+  const { enc } = manifest
+
+  if (typeof enc !== 'object' || enc === null || Array.isArray(enc)) {
+    throw new Error('Manifest is version 2, which is encrypted, but carries no encryption details.')
+  }
+
+  if (typeof enc.salt !== 'string' || !SALT_HEX.test(enc.salt)) {
+    throw new Error(`Manifest records ${JSON.stringify(enc.salt)} as its salt, which is not 32 hex characters.`)
+  }
+
+  if (enc.hint !== undefined && typeof enc.hint !== 'string') {
+    throw new Error(`Manifest records a hint of ${JSON.stringify(enc.hint)}, which is not text.`)
+  }
+
+  // The hint is printed above the password prompt before the seal can be checked, so it is the one
+  // field here a stranger's edit reaches a terminal through. telstore never writes one longer than
+  // the card allows or one carrying a control character, so either is an edit, and refused.
+  if (typeof enc.hint === 'string' && enc.hint.length > MAX_HINT_LENGTH) {
+    throw new Error(
+      `Manifest records a hint of ${enc.hint.length} characters, and telstore never writes one ` +
+        `longer than ${MAX_HINT_LENGTH}.`,
+    )
+  }
+
+  if (typeof enc.hint === 'string' && hasControlCharacter(enc.hint)) {
+    throw new Error(
+      'Manifest records a hint carrying a control character, which telstore never writes and ' +
+        'which would reach the terminal as an instruction rather than as text.',
+    )
+  }
+
+  if (typeof enc.sealed !== 'string' || enc.sealed === '') {
+    throw new Error('Manifest is encrypted but carries no sealed part, so nothing can check what it decrypts to.')
+  }
+
+  manifest.chunks.forEach((chunk, index) => {
+    if (typeof chunk.iv !== 'string' || !IV_HEX.test(chunk.iv)) {
+      throw new Error(
+        `Manifest records ${JSON.stringify(chunk.iv)} as the iv of chunk ${index + 1}, which is not 16 hex characters.`,
+      )
+    }
+  })
+}
+
 export function parseManifest(input) {
   const manifest = parseManifestJson(input)
 
-  if (manifest.v !== MANIFEST_VERSION) {
+  if (manifest.v !== MANIFEST_VERSION && manifest.v !== ENCRYPTED_MANIFEST_VERSION) {
     throw new Error(
-      `Manifest uses version ${manifest.v}, this build of telstore only understands version ${MANIFEST_VERSION}.`,
+      `Manifest uses version ${manifest.v}, this build of telstore only understands versions ` +
+        `${MANIFEST_VERSION} and ${ENCRYPTED_MANIFEST_VERSION}.`,
+    )
+  }
+
+  // Version 1 is never encrypted. A manifest claiming both would be restored as plain bytes by
+  // every telstore that reads version 1, which is the silent wrong file the bump exists to stop.
+  if (manifest.v === MANIFEST_VERSION && manifest.enc !== undefined) {
+    throw new Error(
+      'Manifest says version 1, which is never encrypted, and carries encryption fields anyway. ' +
+        'Restoring it as version 1 would hand over encrypted bytes as the file, so telstore is ' +
+        'not reading it.',
     )
   }
 
@@ -208,6 +310,8 @@ export function parseManifest(input) {
     }
   })
 
+  if (manifest.v === ENCRYPTED_MANIFEST_VERSION) checkEncryption(manifest)
+
   const expectedChunks = countChunks(manifest.size, manifest.chunkSize)
   if (manifest.chunks.length !== expectedChunks) {
     throw new Error(`Manifest is missing ${expectedChunks - manifest.chunks.length} chunk(s).`)

package/src/password.js

@@ -0,0 +1,101 @@
+import { stderr, stdin } from 'node:process'
+
+import { parseHint, terminalSafe } from './caption.js'
+import { openManifest } from './cipher.js'
+import { createPrompts, readSecret } from './prompt.js'
+
+export const PASSWORD_ATTEMPTS = 3
+
+// A password that came from an environment variable, a flag or a file came from somewhere that
+// kept a copy of it, which is the rule src/token.js keeps for a passphrase. Unattended encrypted
+// backups stay on the `--` pipeline with a key-based tool.
+const NO_TERMINAL_UPLOAD =
+  '--encrypt needs a terminal to type the password in, and there is none here. Run the upload ' +
+  'where you can type it; telstore does not read a password from anywhere else.'
+
+// One readline for the whole exchange, as docs/design/terminal-prompts.md requires: two over one
+// stdin do not take turns, and the second question would read nothing. On stderr, so a stdout
+// someone redirected still carries only what telstore reports.
+export async function askNewPassword({ input = stdin, output = stderr } = {}) {
+  if (!input.isTTY) throw new Error(NO_TERMINAL_UPLOAD)
+
+  const prompts = createPrompts({ input, output })
+
+  try {
+    const password = await prompts.askSecret('Password: ')
+
+    if (password === '') {
+      throw new Error('The password is empty. An encrypted backup needs one — run again and type it.')
+    }
+
+    const again = await prompts.askSecret('Password again: ')
+
+    if (again !== password) {
+      throw new Error(
+        'The two passwords are different, so telstore does not know which one you meant. ' +
+          'Nothing was sent — run again.',
+      )
+    }
+
+    const hint = parseHint(await prompts.ask('Hint (optional, shown in the chat as plain text): '), password)
+
+    return { password, hint }
+  } finally {
+    prompts.close()
+  }
+}
+
+export function askPassword(question) {
+  return readSecret(question)
+}
+
+// Opens an encrypted manifest or says why it cannot. Passwords this run has already seen work
+// are tried first and silently, so a batch of backups under one password asks once. A failed
+// tag cannot tell a wrong password from an altered manifest, so the last refusal names both,
+// likelier first, as src/token.js does for a token.
+export async function unlockManifest(
+  manifest,
+  { askPassword: ask, interactive = () => Boolean(stdin.isTTY), known = [], say = () => {} },
+) {
+  for (const password of known) {
+    const opened = await openManifest(manifest, password)
+    if (opened) return { ...opened, password }
+  }
+
+  if (!interactive()) {
+    throw new Error(
+      `${manifest.id} is encrypted, and there is no terminal here to type its password in. ` +
+        'Run this where you can type it; telstore does not read a password from anywhere else.',
+    )
+  }
+
+  say(`Backup ${manifest.id} is encrypted.`)
+
+  // Printed before any key exists, so the seal that covers it cannot have been checked yet: at
+  // this moment it is as trustworthy as the chat it came from, and is made safe to print as such.
+  const hint = manifest.enc.hint ? terminalSafe(manifest.enc.hint) : ''
+
+  if (hint) say(`Hint   ${hint}`)
+
+  for (let attempt = 1; attempt <= PASSWORD_ATTEMPTS; attempt += 1) {
+    const password = await ask('Password: ')
+    const opened = password === '' ? null : await openManifest(manifest, password)
+
+    if (opened) {
+      known.push(password)
+      return { ...opened, password }
+    }
+
+    if (attempt < PASSWORD_ATTEMPTS) say('That password does not open it. Try again.')
+  }
+
+  throw new Error(
+    `Could not open ${manifest.id} after ${PASSWORD_ATTEMPTS} attempts: either the password is ` +
+      'wrong or the manifest was altered. Encryption cannot tell those two apart, so telstore ' +
+      'will not guess — check the password first.' +
+      (hint
+        ? ' The hint shown comes from the chat and is only checked once the password opens the ' +
+          'backup, so a hint that does not help may itself have been altered.'
+        : ''),
+  )
+}

package/src/state.js

@@ -75,6 +75,18 @@ export function stateKey(absPath, size, mtimeMs) {
   return createHash('sha1').update(`${absPath}:${size}:${mtimeMs}`).digest('hex')
 }
 
+// Where an encrypted upload's record is filed, and the reason it is not filed under stateKey is
+// the reason the manifest went to version 2: an older telstore. That build computes stateKey
+// exactly as this one does and never reads `enc`, so given an unfinished encrypted record under
+// that key it would resume it without --encrypt, send the remaining chunks in plain, write a
+// version 1 manifest with no ivs in it — and a later restore would match every sha256 and print
+// Done over a file that is half ciphertext. A lookup that misses is the only refusal an older
+// build can be made to give. Same 40-hex shape, so every listing, prune and status report that
+// already handles upload records handles this one without learning a new name.
+export function encryptedStateKey(absPath, size, mtimeMs) {
+  return createHash('sha1').update(`enc:${absPath}:${size}:${mtimeMs}`).digest('hex')
+}
+
 export function stateFile(key, configDir = defaultConfigDir()) {
   return path.join(stateDir(configDir), `${key}.json`)
 }
@@ -282,7 +294,8 @@ export async function findStates(backupId, configDir = defaultConfigDir()) {
 // 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
+// through stateKey (encryptedStateKey for an encrypted record) 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.
 //
@@ -306,7 +319,16 @@ export async function canResume(key, state) {
   }
 
   if (!stat.isFile()) return { ok: false, reason: 'not-a-file' }
-  if (stateKey(state.path, stat.size, stat.mtimeMs) !== key) return { ok: false, reason: 'changed' }
+
+  // Two keys now, and the record says which one it belongs under: runUpload files an encrypted
+  // record under encryptedStateKey and a plain one under stateKey. A record sitting under the
+  // other kind's key for a file that has not changed is not a changed file — runUpload refuses
+  // it as damaged rather than resume it, and the report has to say the same thing.
+  const own = (state.enc ? encryptedStateKey : stateKey)(state.path, stat.size, stat.mtimeMs)
+  const other = (state.enc ? stateKey : encryptedStateKey)(state.path, stat.size, stat.mtimeMs)
+
+  if (key === other) return { ok: false, reason: 'damaged' }
+  if (key !== own) return { ok: false, reason: 'changed' }
 
   return { ok: true }
 }

package/src/uploader.js

@@ -44,6 +44,11 @@ export async function uploadRange(client, fd, options) {
     onProgress,
     retryOptions,
     stallMs = DEFAULT_STALL_MS,
+    // Applied to each part as it is read, in order, before it is hashed or sent — so the sha256
+    // this returns is of the bytes Telegram holds, and a retry resends the same transformed
+    // buffer rather than transforming again. It is what encryption rides on, and this file knows
+    // nothing else about it.
+    transform = (bytes) => bytes,
   } = options
 
   // A pool of fewer than one worker does no work. In the download path that means
@@ -94,7 +99,7 @@ export async function uploadRange(client, fd, options) {
       for (let part = start; part < end; part += 1) {
         const partOffset = part * partSize
         const partLength = Math.min(partSize, length - partOffset)
-        const bytes = await readExactly(fd, partLength, offset + partOffset)
+        const bytes = transform(await readExactly(fd, partLength, offset + partOffset), partOffset)
 
         hash.update(bytes)