telstore 0.1.9 → 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,
@@ -34,12 +45,40 @@ import {
 import { uploadRange } from '../uploader.js'
 
 // Above this threshold the wait must be spelled out, per spec §8.
-const LONG_WAIT_MS = 60_000
+export const LONG_WAIT_MS = 60_000
 
 // A transient error that resolves itself on the next try is not news, and one line per
 // occurrence buries the progress bar in a wall of text. Stay quiet until the third retry:
 // by then the trouble has outlived two backoffs and is worth saying out loud.
-const ANNOUNCE_AFTER_ATTEMPT = 3
+export const ANNOUNCE_AFTER_ATTEMPT = 3
+
+// Retries and FLOOD_WAIT must be announced: a silent FLOOD_WAIT_3600 leaves the user
+// staring at a frozen progress bar for an hour, assuming the process has hung.
+//
+// Exported because a stream upload waits on the same Telegram and has to say the same
+// things about it. Two copies of this wording would drift, and the one that drifted would
+// be the one nobody was reading at the time.
+export function createOnRetry(warn) {
+  return function onRetry(err, attempt, delayMs, elapsedMs = 0) {
+    if (delayMs > LONG_WAIT_MS) {
+      warn(
+        `\nTelegram wants ${formatDuration(delayMs / 1000)} of waiting before the next send ` +
+          `(${err.message}). telstore is waiting and will carry on by itself, leave it running.\n`,
+      )
+      return
+    }
+
+    // The exception to staying quiet: an attempt that took a minute to fail spent that
+    // minute with the bar frozen, which is exactly what a hang looks like. Those are worth
+    // a line the first time, whatever the attempt number.
+    if (attempt < ANNOUNCE_AFTER_ATTEMPT && elapsedMs < LONG_WAIT_MS) return
+
+    warn(
+      `\nTemporary error (${err.message}), retry ${attempt} in ` +
+        `${formatDuration(delayMs / 1000)}.\n`,
+    )
+  }
+}
 
 // Chunks and manifests differ only in where the bytes come from. Everything Telegram is
 // told about them — document, not preview; this exact file name — is decided once.
@@ -52,11 +91,15 @@ async function sendDocument(client, peer, { file, fileName, caption }) {
   })
 }
 
-async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
+// The defaults behind runUpload's `sendChunk` and `sendManifest` deps. Exported because a
+// stream upload sends the same two kinds of document to the same Telegram, and a second copy
+// of "document, not preview; this exact file name" is how the two start disagreeing about
+// what telstore actually put in the chat.
+export async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
   return await sendDocument(client, peer, { file: inputFile, fileName, caption })
 }
 
-async function realSendManifest(client, peer, { bytes, fileName, caption }) {
+export async function realSendManifest(client, peer, { bytes, fileName, caption }) {
   return await sendDocument(client, peer, {
     file: new CustomFile(fileName, bytes.length, '', bytes),
     fileName,
@@ -107,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,
@@ -123,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)
@@ -142,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
@@ -195,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(),
@@ -203,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)
@@ -224,30 +398,11 @@ export async function runUpload(filePath, options = {}, deps = {}) {
   const log = silent ? () => {} : writeLog
   const warn = silent ? () => {} : writeErr
 
-  // Retries and FLOOD_WAIT must be announced: a silent FLOOD_WAIT_3600 leaves the user
-  // staring at a frozen progress bar for an hour, assuming the process has hung.
-  function onRetry(err, attempt, delayMs, elapsedMs = 0) {
-    if (delayMs > LONG_WAIT_MS) {
-      warn(
-        `\nTelegram wants ${formatDuration(delayMs / 1000)} of waiting before the next send ` +
-          `(${err.message}). telstore is waiting and will carry on by itself, leave it running.\n`,
-      )
-      return
-    }
-
-    // The exception to staying quiet: an attempt that took a minute to fail spent that
-    // minute with the bar frozen, which is exactly what a hang looks like. Those are worth
-    // a line the first time, whatever the attempt number.
-    if (attempt < ANNOUNCE_AFTER_ATTEMPT && elapsedMs < LONG_WAIT_MS) return
-
-    warn(
-      `\nTemporary error (${err.message}), retry ${attempt} in ` +
-        `${formatDuration(delayMs / 1000)}.\n`,
-    )
-  }
+  const onRetry = createOnRetry(warn)
 
   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 })
@@ -291,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,
@@ -299,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, {
@@ -311,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 {
@@ -339,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),
@@ -358,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,
       }),
     })
 
@@ -390,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
@@ -476,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,8 +11,8 @@ import {
   readMessageBytes as realReadMessageBytes,
 } from '../client.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
-import { chunkFileName, manifestFileName, parseManifest } from '../manifest.js'
-import { formatBytes, formatDuration } from '../progress.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'
 
@@ -21,10 +22,6 @@ function describeName(name) {
   return typeof name === 'string' && name.trim() !== '' ? name : '—'
 }
 
-function plural(n, word) {
-  return `${n} ${word}${n === 1 ? '' : 's'}`
-}
-
 // What is wrong with one chunk, or null when nothing is. The first failing check wins: a
 // chunk is damaged or it is not, and listing three complaints about one message would make
 // "2 damaged" mean something other than two chunks.
@@ -135,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')
@@ -11,8 +26,60 @@ export function newBackupId(now = new Date(), randomHex = () => randomBytes(3).t
   return `telstore-${yyyy}${mm}${dd}-${randomHex()}`
 }
 
+// The day a backup id carries, as the UTC second that day began. newBackupId stamps it above
+// from the clock of the machine making the backup, so it is that machine's idea of the day
+// rather than Telegram's — which is why the one reader of this (delete's walk of the chat)
+// gives it a day of slack and only ever uses it as a floor.
+//
+// A date that does not exist is not a day: `telstore-20269999-abc` would otherwise roll over
+// into a year's time and read as a floor above everything in the chat, which is an early stop
+// nobody would see. Null instead, and the caller falls back to a bound it can prove.
+const BACKUP_ID_DAY = /^telstore-(\d{4})(\d{2})(\d{2})-[0-9a-f]+$/
+
+export function backupIdDay(id) {
+  const match = BACKUP_ID_DAY.exec(String(id))
+
+  if (!match) return null
+
+  const [year, month, day] = match.slice(1).map(Number)
+  const at = new Date(Date.UTC(year, month - 1, day))
+
+  if (at.getUTCFullYear() !== year || at.getUTCMonth() !== month - 1 || at.getUTCDate() !== day) {
+    return null
+  }
+
+  return Math.floor(at.getTime() / 1000)
+}
+
+// The infix in every chunk's file name. A constant rather than a literal for the same reason
+// MANIFEST_SUFFIX is one: there are two readers of that name now — the writer below and
+// isChunkFileName — and a reader that disagrees with the writer by one character finds
+// nothing at all.
+const CHUNK_INFIX = '.part'
+
 export function chunkFileName(id, i) {
-  return `${id}.part${String(i + 1).padStart(4, '0')}`
+  return `${id}${CHUNK_INFIX}${String(i + 1).padStart(4, '0')}`
+}
+
+// Whether a document in a chat is a chunk of this backup, decided by the file name telstore
+// itself wrote and not by the caption beside it — the rule findManifestMessage already keeps,
+// for the same reason: a caption is text a person can edit and a file name is not.
+//
+// The number is checked but never read back. What the caller needs is which backup a document
+// belongs to, and a chunk whose index says something impossible is still that backup's chunk.
+// What the check is for is the other direction: without it `<id>.partial` or `<id>.part.bak`
+// — names telstore never writes, but names a person can give a file they upload themselves —
+// would be read as chunks of a backup and destroyed along with it.
+export function isChunkFileName(id, fileName) {
+  if (typeof fileName !== 'string') return false
+
+  const prefix = `${id}${CHUNK_INFIX}`
+
+  if (!fileName.startsWith(prefix)) return false
+
+  const number = fileName.slice(prefix.length)
+
+  return number.length > 0 && /^[0-9]+$/.test(number)
 }
 
 // The suffix telstore has written on every manifest since version 1, and what `list` picks
@@ -24,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,
@@ -32,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,
@@ -43,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 } : {}),
+      })),
   }
 }
 
@@ -96,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.',
     )
   }
 
@@ -156,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).`)