/** * Restoring a full backup zip ("Download backup" in Settings → Data) into the running app. * * 1. The zip is unpacked into a staging folder inside the data folder, one file at a time * (only study.db, secret.key, manifest.json, uploads/* and media/* are accepted). * 2. The staged database is opened and upgraded to this version's schema (a backup from a * newer version is refused), saved AI keys are re-encrypted for this server's key, jobs that * were running when the backup was taken are marked interrupted, and the signed-in session * is carried over so the person restoring stays signed in. * 3. A snapshot of the current database is written to the backups folder, running generations * stop, and the database file is swapped under the open handle (`DB.replaceWith`). * 4. Uploaded files and images from the backup are copied into place (files already here that * the backup does not have are left alone), and background work restarts on the new data. */ import fs from 'node:fs'; import path from 'node:path'; import { Unzip, UnzipInflate, type UnzipFile } from 'fflate'; import { decryptSecret, encryptSecret } from '../crypto.ts'; import { DB, migrate } from '../db.ts'; import { badRequest, type AppContext } from '../http.ts'; import { cancelAllGenerations, tidyDrafts } from '../ai/generate.ts'; import { forgetMcpSessions, warmMcpServers } from '../ai/mcp.ts'; import { createSnapshot } from './backup.ts'; import { resumeQueue } from './documents.ts'; import { notifyChange } from './events.ts'; import { resetVectorCache, scheduleIndexing } from './semantic.ts'; export interface RestoreSummary { backupCreatedAt: string | null; classes: number; quizzes: number; decks: number; notes: number; documents: number; attempts: number; files: number; /** Saved keys (AI providers, MCP, web search) re-encrypted for this server. */ keysMoved: number; /** Saved keys that could not be read: the backup's secret.key or APP_SECRET is not available. */ keysUnreadable: number; /** The snapshot of the database as it was before the restore. */ safetySnapshot: string; /** Generations that were running and were stopped. */ stoppedJobs: number; } const ACCEPTED = /^(?:study\.db|secret\.key|manifest\.json|(?:uploads|media)\/[^/\\]+)$/; /** An encrypted value: `v1.<12-byte iv>.<16-byte tag>.` in base64url. */ const SEALED = /v1\.[A-Za-z0-9_-]{16}\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]+/g; /** Unpacks the accepted entries of a zip file into `dir` without holding the whole zip in memory. */ async function unpack(zipFile: string, dir: string, maxBytes: number): Promise { const written: string[] = []; let failure: Error | null = null; let total = 0; const unzip = new Unzip((file: UnzipFile) => { const name = file.name.replace(/\\/g, '/'); if (!ACCEPTED.test(name) || name.split('/').some((p) => p === '..' || p === '.' || p === '')) return; const target = path.join(dir, ...name.split('/')); fs.mkdirSync(path.dirname(target), { recursive: true }); const fd = fs.openSync(target, 'w'); file.ondata = (err, chunk, final) => { if (failure) return; if (err) failure = err; else { total += chunk.length; if (total > maxBytes) failure = badRequest('The backup is larger than this server accepts.'); else fs.writeSync(fd, chunk); } if (final || failure) { fs.closeSync(fd); if (final && !failure) written.push(name); } }; file.start(); }); unzip.register(UnzipInflate); for await (const chunk of fs.createReadStream(zipFile, { highWaterMark: 1 << 20 })) { unzip.push(chunk as Uint8Array); if (failure) break; } if (!failure) unzip.push(new Uint8Array(0), true); if (failure) throw failure; return written; } /** The 32-byte key in a backup's secret.key, or null when missing or damaged. */ function readKey(file: string): Buffer | null { try { const raw = Buffer.from(fs.readFileSync(file, 'utf8').trim(), 'base64'); return raw.length === 32 ? raw : null; } catch { return null; } } /** * Re-encrypts every sealed value in the staged database (wherever it is stored: provider * columns, settings JSON) from the backup's key to this server's key. Values this server can * already read are left as they are. */ function rekey(db: DB, from: Buffer | null, to: Buffer): { moved: number; unreadable: number } { let moved = 0; let unreadable = 0; const tables = db.all<{ name: string; sql: string | null }>("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'"); const virtual = tables.filter((t) => /^CREATE VIRTUAL TABLE/i.test(t.sql ?? '')).map((t) => t.name); for (const t of tables) { if (virtual.includes(t.name) || virtual.some((v) => t.name.startsWith(`${v}_`)) || /WITHOUT ROWID/i.test(t.sql ?? '')) continue; const quoted = `"${t.name.replace(/"/g, '""')}"`; const columns = db.all<{ name: string; type: string }>(`PRAGMA table_info(${quoted})`).filter((c) => /TEXT|^$/i.test(c.type)); for (const col of columns) { const c = `"${col.name.replace(/"/g, '""')}"`; const rows = db.all<{ rid: number; v: string }>(`SELECT rowid AS rid, ${c} AS v FROM ${quoted} WHERE typeof(${c}) = 'text' AND ${c} LIKE '%v1.%'`); for (const row of rows) { let changed = false; const next = row.v.replace(SEALED, (sealed) => { if (decryptSecret(sealed, to) !== null) return sealed; const plain = from ? decryptSecret(sealed, from) : null; if (plain === null) { unreadable += 1; return sealed; } moved += 1; changed = true; return encryptSecret(plain, to); }); if (changed) db.run(`UPDATE ${quoted} SET ${c} = ? WHERE rowid = ?`, next, row.rid); } } } return { moved, unreadable }; } /** Copies the signed-in session into the restored database so the person restoring stays signed in. */ function carrySession(from: DB, to: DB, tokenHash: string | null): void { if (!tokenHash) return; const row = from.get>('SELECT * FROM sessions WHERE token_hash = ?', tokenHash); if (!row) return; const known = new Set(to.all<{ name: string }>('PRAGMA table_info(sessions)').map((c) => c.name)); const cols = Object.keys(row).filter((k) => known.has(k)); to.run(`INSERT OR REPLACE INTO sessions (${cols.join(', ')}) VALUES (${cols.map(() => '?').join(', ')})`, ...cols.map((k) => row[k] as string | number | null)); } export async function restoreFullBackup(app: AppContext, zipFile: string, opts: { sessionHash?: string | null; maxBytes?: number } = {}): Promise { const { config } = app; const stage = path.join(config.dataDir, `.restore-${Date.now()}`); fs.mkdirSync(stage, { recursive: true }); try { const names = await unpack(zipFile, stage, opts.maxBytes ?? 20 * 1024 ** 3); if (!names.includes('study.db')) throw badRequest('This is not a Study Desk full backup: it has no study.db. Use "Download backup" to make one.'); const manifest = (() => { try { return JSON.parse(fs.readFileSync(path.join(stage, 'manifest.json'), 'utf8')) as { format?: string; createdAt?: string }; } catch { return null; } })(); if (manifest && manifest.format !== 'studydesk-backup') throw badRequest('This zip is not a Study Desk full backup.'); const stagedDb = path.join(stage, 'study.db'); const head = Buffer.alloc(16); const fd = fs.openSync(stagedDb, 'r'); fs.readSync(fd, head, 0, 16, 0); fs.closeSync(fd); if (head.toString('latin1', 0, 15) !== 'SQLite format 3') throw badRequest('The database in this backup is damaged.'); // Upgrade the backup to this version's schema, then prepare it while it is still offline. const staged = new DB(stagedDb); try { migrate(staged); } catch (e) { staged.close(); throw badRequest(e instanceof Error && /newer version/.test(e.message) ? 'This backup was made by a newer version of Study Desk. Update this server first.' : 'The database in this backup could not be opened.'); } let keys: { moved: number; unreadable: number }; const count = (table: string) => staged.get<{ n: number }>(`SELECT COUNT(*) AS n FROM ${table}`)?.n ?? 0; let counts: Pick; try { keys = staged.tx(() => rekey(staged, readKey(path.join(stage, 'secret.key')), config.secretKey)); tidyDrafts(staged); carrySession(app.db, staged, opts.sessionHash ?? null); counts = { classes: count('classes'), quizzes: count('quizzes'), decks: count('decks'), notes: count('notes'), documents: count('documents'), attempts: count('attempts') }; } finally { staged.close(); } // Point of no return: keep a copy of what is here now, stop work, and swap. const safety = createSnapshot(app, 'pre-restore'); const stoppedJobs = cancelAllGenerations(); forgetMcpSessions(); app.db.replaceWith(stagedDb); let files = 0; for (const [sub, target] of [ ['uploads', config.uploadsDir], ['media', config.mediaDir], ] as const) { const from = path.join(stage, sub); if (!fs.existsSync(from)) continue; fs.mkdirSync(target, { recursive: true }); for (const f of fs.readdirSync(from)) { const dest = path.join(target, f); fs.rmSync(dest, { force: true }); fs.renameSync(path.join(from, f), dest); files += 1; } } resetVectorCache(); resumeQueue(app); scheduleIndexing(app); warmMcpServers(app); for (const topic of ['library', 'drafts', 'documents'] as const) notifyChange(topic); app.log('info', `Full backup restored (${counts.classes} classes, ${files} files); previous database kept as ${safety.name}`); return { backupCreatedAt: manifest?.createdAt ?? null, ...counts, files, keysMoved: keys.moved, keysUnreadable: keys.unreadable, safetySnapshot: safety.name, stoppedJobs }; } finally { try { fs.rmSync(stage, { recursive: true, force: true }); } catch (e) { app.log('warn', `Could not remove the restore staging folder ${stage}`, e instanceof Error ? e.message : e); } } }