Restore a full backup from Settings
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s

Settings → Data → Import gets "Restore a full backup" in place of the V1
import row. The zip from "Download backup" is uploaded and replaces the
database, every setting and the uploaded files on the running server:

- the staged database is upgraded to this schema (newer backups are refused),
  saved keys are re-encrypted for this server's key, interrupted jobs are
  marked, and the restoring session is carried over;
- a pre-restore snapshot is written, running generations stop, and the file
  is swapped under the open DB handle (DB.replaceWith); uploads and media are
  copied into place and background work restarts.

The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-16 12:33:42 -07:00
parent e0bc7b580e
commit 7125dec3e0
13 changed files with 521 additions and 72 deletions

View file

@ -204,6 +204,12 @@ sheet on phones. The drawer is resizable for both (drag the edge, 340-760 px, do
reset, remembered per browser). Checked in the browser at 1440, 1100 and 375 px wide, with a live
answer streamed on a share link.
Settings → Data → Import now restores a full backup zip in place of the V1 import row (the
`/api/import/v1` endpoint stays for the V1 cutover; see docs/MIGRATION.md). The restore replaces
the database, settings and files without a restart, re-encrypts saved keys for this server, keeps
a `pre-restore-*` snapshot and keeps the person signed in. Tests: `tests/restore.test.ts`;
round trip on the rev1 copy: 1 MB backup restored in 75 ms, same library, still signed in.
Tests: `tests/revision5.test.ts`. Live check on the rev1 copy with DeepSeek flash: a visitor's
10-card set was written, named ("Heparin, Furosemide, and Dosage Calculations"), saved and
listed once with the New tag; cards were single facts with no hints. The rev1 copy's 401 was its
@ -212,7 +218,7 @@ stored DeepSeek connection still holding the old key; it was updated from `.env`
## Verification status
Baseline: 162 tests passed, TypeScript passed and production web/server builds passed.
Added six regression tests. Full `npm run check` passes: **289 tests** (rationale layout, 2026-11-16; 285 after varied openers; 281 after generation steps; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript
Added six regression tests. Full `npm run check` passes: **291 tests** (full-backup restore, 2026-11-16; 289 after rationale layout; 285 after varied openers; 281 after generation steps; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript
and both production builds. The Docker `test` stage runs the same 181 tests on Node 24. Tests were run with loopback access for the mock provider.
The earlier agent manually exercised quiz completion/results, flashcards, streak effects,

View file

@ -94,6 +94,29 @@ cannot read an included file fails rather than silently substituting an empty fi
Avoid changing or deleting source files while making a full ZIP; filesystem content is not
transactional with SQLite.
## Restoring a full backup in the app
Settings → Data → **Restore a full backup** uploads a ZIP from "Download backup" and replaces
everything on the running server: content, progress, uploads, AI models and all settings. No
restart is needed. Steps (`server/services/restore.ts`):
- The ZIP is unpacked into a staging folder inside the data folder. Only `study.db`,
`secret.key`, `manifest.json`, `uploads/*` and `media/*` are accepted.
- The staged database is upgraded to this version's schema. A backup from a newer version is
refused.
- Saved API keys are re-encrypted from the backup's `secret.key` to this server's key, so a
backup from another install keeps its AI connections. Keys sealed with an `APP_SECRET` this
server does not have are reported as unreadable and must be entered again.
- A `pre-restore-*` snapshot of the current database is written, running generations stop, and
the database file is swapped under the open handle.
- Files from the backup are copied over the uploads and media folders. Files already there are
left in place.
- The person restoring stays signed in. Later sign-ins use the backup's password.
The upload is the raw ZIP body (up to 20 GB). A proxy may cap uploads well below that (Cloudflare's
free plan allows 100 MB per request). For a larger backup, restore through the server's own
address on the local network, or use the manual drill below.
## Restore drill
1. Download a full ZIP and verify it opens. Stop the V2 container before restoring.

View file

@ -6,7 +6,10 @@ a separate data folder. It never upgrades a production V1 database in place.
1. Use V1's backup facility to make a consistent SQLite copy. If copying files yourself,
stop V1 first; copying only a live WAL-mode `.db` can omit recent writes.
2. Keep the original and a verified backup untouched. Start V2 with an empty V2 volume.
3. In V2 Settings → Data → V1 import, select the **backup copy** and preview it.
3. Settings no longer shows the V1 import (its place went to restoring a full V2 backup), but
the endpoint remains. While signed in, preview the **backup copy** with
`POST /api/import/v1?preview=1` (multipart field `file`, header `X-Requested-With: studydesk`),
then import it without `?preview=1`.
4. Review the reported counts/skipped items, then explicitly import. V2 opens the submitted
SQLite file read-only and creates new IDs in one transaction. A failed import rolls back.
5. Compare class/folder/deck/quiz counts and representative questions, rationales, attempts and

View file

@ -615,6 +615,14 @@ export function cancelGeneration(draftId: string): void {
running.delete(draftId);
}
/** Stops every running generation (before a full backup replaces the database). */
export function cancelAllGenerations(): number {
const n = running.size;
for (const c of running.values()) c.abort();
running.clear();
return n;
}
/** Listeners for a running job's progress labels (the assistant shows them on its tool step). */
const progressListeners = new Map<string, (label: string) => void>();

View file

@ -366,6 +366,11 @@ function forget(serverId: string): void {
sessions.delete(serverId);
}
/** Drops every open MCP session (after a restore the servers and their credentials may differ). */
export function forgetMcpSessions(): void {
sessions.clear();
}
export class McpError extends Error {
expired: boolean;
/** The server answered 401: the credentials are missing, wrong or expired. */

View file

@ -97,6 +97,12 @@ function createSession(app: AppContext, c: Context): void {
setCookie(c, COOKIE, token, { httpOnly: true, sameSite: 'Lax', secure, path: '/', maxAge: Math.floor(SESSION_MS / 1000) });
}
/** The stored hash of this request's session token, or null when there is no session cookie. */
export function sessionHash(c: Context): string | null {
const token = getCookie(c, COOKIE);
return token ? sha256(token) : null;
}
export function isAuthenticated(app: AppContext, c: Context): boolean {
const token = getCookie(c, COOKIE);
if (!token) return false;

View file

@ -14,7 +14,7 @@ function bind(params: Param[]): (string | number | bigint | null | Uint8Array)[]
* exactly what a one-user app in one container needs, with no native add-on to build.
*/
export class DB {
readonly raw: DatabaseSync;
private handle: DatabaseSync;
readonly path: string;
private statements = new Map<string, StatementSync>();
private txDepth = 0;
@ -23,11 +23,53 @@ export class DB {
constructor(file: string) {
this.path = file;
this.raw = new DatabaseSync(file);
this.raw.exec('PRAGMA journal_mode = WAL');
this.raw.exec('PRAGMA synchronous = NORMAL');
this.raw.exec('PRAGMA foreign_keys = ON');
this.raw.exec('PRAGMA busy_timeout = 5000');
this.handle = DB.open(file);
}
private static open(file: string): DatabaseSync {
const raw = new DatabaseSync(file);
raw.exec('PRAGMA journal_mode = WAL');
raw.exec('PRAGMA synchronous = NORMAL');
raw.exec('PRAGMA foreign_keys = ON');
raw.exec('PRAGMA busy_timeout = 5000');
return raw;
}
/** The node:sqlite handle. Changes when a full backup is restored (`replaceWith`). */
get raw(): DatabaseSync {
return this.handle;
}
/**
* Swaps the database file for `file` (a complete, closed SQLite file in the same folder) under
* this same object, so every part of the app keeps working with the restored data. If the
* swap fails, the current database is reopened untouched.
*/
replaceWith(file: string): void {
if (this.txDepth > 0) throw new Error('A database transaction is still open.');
if (this.path === ':memory:') throw new Error('An in-memory database cannot be replaced.');
this.statements.clear();
try {
this.handle.exec('PRAGMA wal_checkpoint(TRUNCATE)');
} catch {
/* closing writes it anyway */
}
this.handle.close();
try {
const aside = `${this.path}.replaced`;
fs.rmSync(aside, { force: true });
fs.renameSync(this.path, aside);
try {
fs.renameSync(file, this.path);
} catch (e) {
fs.renameSync(aside, this.path);
throw e;
}
for (const ext of ['-wal', '-shm']) fs.rmSync(`${this.path}${ext}`, { force: true });
fs.rmSync(aside, { force: true });
} finally {
this.handle = DB.open(this.path);
}
}
private stmt(sql: string): StatementSync {

View file

@ -11,10 +11,14 @@ import { appSettingsSchema, deleteSetting, getAppSettings, getSetting, setSettin
import { createSnapshot, exportBundle, fullBackupStream, listBackups } from '../services/backup.ts';
import { createClass, createDeck, createFolder, createNote, createQuiz, draftCardToInput, draftQuestionToInput, getClass, getDeck, getQuiz, listCards, listQuestions } from '../services/content.ts';
import { createTemplate, deleteTemplate, listTemplates, resetTemplate, templateInputSchema, updateTemplate } from '../services/templates.ts';
import { restoreFullBackup } from '../services/restore.ts';
import { importV1 } from '../services/v1import.ts';
import { sessionHash } from '../auth.ts';
import { slugify } from '../util.ts';
export const APP_VERSION = '2.0.0';
/** The largest full backup that can be restored through the app. */
const RESTORE_MAX_BYTES = 20 * 1024 ** 3;
function dirSize(dir: string): number {
try {
@ -176,7 +180,45 @@ export function dataRoutes(app: AppContext): Hono {
return c.json({ summary }, 201);
});
/** Migration from a V1 database file. `?preview=1` only reports what would be imported. */
/**
* Restores a full backup zip (from "Download backup"): the database with every setting, and the
* uploaded files. The zip is the raw request body, streamed to disk. See services/restore.ts.
*/
r.post('/backup/restore', async (c) => {
const max = RESTORE_MAX_BYTES;
const declared = Number(c.req.header('content-length') ?? 0);
if (declared > max) throw new HttpError(413, 'too_large', 'The backup is larger than this server accepts.');
const body = c.req.raw.body;
if (!body) throw badRequest('Choose a backup zip');
const tmp = path.join(app.config.dataDir, `.restore-upload-${Date.now()}.zip`);
try {
let size = 0;
const out = fs.createWriteStream(tmp);
try {
for await (const chunk of body as unknown as AsyncIterable<Uint8Array>) {
size += chunk.length;
if (size > max) throw new HttpError(413, 'too_large', 'The backup is larger than this server accepts.');
if (!out.write(chunk)) await new Promise((r) => out.once('drain', r));
}
} finally {
await new Promise<void>((resolve, reject) => out.end((err?: Error | null) => (err ? reject(err) : resolve())));
}
if (size < 22) throw badRequest('Choose a backup zip');
const head = Buffer.alloc(4);
const fd = fs.openSync(tmp, 'r');
fs.readSync(fd, head, 0, 4, 0);
fs.closeSync(fd);
if (head.readUInt32LE(0) !== 0x04034b50) throw badRequest('That file is not a zip. Choose a file made with "Download backup".');
return c.json({ summary: await restoreFullBackup(app, tmp, { sessionHash: sessionHash(c) }) });
} finally {
fs.rmSync(tmp, { force: true });
}
});
/**
* Migration from a V1 database file. `?preview=1` only reports what would be imported. Not in
* Settings any more (full-backup restore took its place); see docs/MIGRATION.md.
*/
r.post('/import/v1', bodyLimit({ maxSize: 500 * 1024 * 1024 }), async (c) => {
const form = await c.req.parseBody().catch(() => {
throw badRequest('Upload could not be read');

222
server/services/restore.ts Normal file
View file

@ -0,0 +1,222 @@
/**
* 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>.<ciphertext>` 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<string[]> {
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<Record<string, unknown>>('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<RestoreSummary> {
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<RestoreSummary, 'classes' | 'quizzes' | 'decks' | 'notes' | 'documents' | 'attempts'>;
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);
}
}
}

View file

@ -251,6 +251,12 @@ interface VectorCache {
}
let cache: VectorCache | null = null;
/** Drops the in-memory vectors (after a restore replaced the database). */
export function resetVectorCache(): void {
cache = null;
queryCache.clear();
}
function loadVectors(db: DB, key: string): VectorCache | null {
const sig = db.get<{ n: number; m: number | null }>('SELECT COUNT(*) AS n, MAX(chunk_id) AS m FROM chunk_vectors WHERE model_key = ?', key)!;
if (sig.n === 0) return null;

101
tests/restore.test.ts Normal file
View file

@ -0,0 +1,101 @@
import fs from 'node:fs';
import path from 'node:path';
import { DatabaseSync } from 'node:sqlite';
import { strToU8, unzipSync, zipSync } from 'fflate';
import { afterEach, describe, expect, it } from 'vitest';
import { decryptSecret, encryptSecret } from '../server/crypto.ts';
import { getSetting, setSetting } from '../server/settings.ts';
import { createTestApp, type TestApp } from './helpers.ts';
const apps: TestApp[] = [];
async function newApp(): Promise<TestApp> {
const app = await createTestApp();
apps.push(app);
return app;
}
afterEach(() => {
for (const app of apps.splice(0)) {
try {
app.ctx.db.close();
} catch {
/* already closed */
}
fs.rmSync(app.dir, { recursive: true, force: true });
}
});
async function backupOf(app: TestApp): Promise<Uint8Array> {
const res = await app.raw('GET', '/api/backup/download');
expect(res.status).toBe(200);
return new Uint8Array(await res.arrayBuffer());
}
const restore = (app: TestApp, zip: Uint8Array) => app.raw('POST', '/api/backup/restore', { headers: { 'content-type': 'application/zip' }, body: zip });
describe('restoring a full backup', () => {
it('replaces the data, settings and files, moves saved keys to this server and keeps the session', async () => {
const source = await newApp();
await source.api('POST', '/api/classes', { name: 'Backed up class' });
setSetting(source.ctx.db, 'test.sealed', { apiKey: encryptSecret('test-only-key', source.ctx.config.secretKey) });
setSetting(source.ctx.db, 'test.plain', 'kept');
fs.writeFileSync(path.join(source.ctx.config.uploadsDir, 'lecture.txt'), 'Uploaded lecture');
const zip = await backupOf(source);
const target = await newApp();
await target.api('POST', '/api/classes', { name: 'Replaced class' });
fs.writeFileSync(path.join(target.ctx.config.uploadsDir, 'local-only.txt'), 'Left alone');
// Two installs have different keys, so the sealed key must be re-encrypted to be readable.
expect(target.ctx.config.secretKey.equals(source.ctx.config.secretKey)).toBe(false);
const res = await restore(target, zip);
const body = (await res.json()) as { summary: Record<string, unknown> };
expect(res.status).toBe(200);
expect(body.summary).toMatchObject({ classes: 1, files: 1, keysMoved: 1, keysUnreadable: 0 });
expect(String(body.summary.safetySnapshot)).toMatch(/^pre-restore-/);
// Still signed in, now looking at the restored library.
const classes = await target.api('GET', '/api/classes');
expect(classes.status).toBe(200);
expect(classes.body.classes.map((c: { name: string }) => c.name)).toEqual(['Backed up class']);
expect(getSetting(target.ctx.db, 'test.plain', '')).toBe('kept');
const sealed = getSetting<{ apiKey: string }>(target.ctx.db, 'test.sealed', { apiKey: '' }).apiKey;
expect(decryptSecret(sealed, target.ctx.config.secretKey)).toBe('test-only-key');
expect(fs.readFileSync(path.join(target.ctx.config.uploadsDir, 'lecture.txt'), 'utf8')).toBe('Uploaded lecture');
expect(fs.existsSync(path.join(target.ctx.config.uploadsDir, 'local-only.txt'))).toBe(true);
// The database as it was before is kept as a snapshot, and no staging files are left.
const before = new DatabaseSync(path.join(target.ctx.config.backupsDir, String(body.summary.safetySnapshot)), { readOnly: true });
expect((before.prepare('SELECT name FROM classes').all() as { name: string }[]).map((r) => r.name)).toEqual(['Replaced class']);
before.close();
expect(fs.readdirSync(target.ctx.config.dataDir).filter((f) => f.startsWith('.restore'))).toEqual([]);
// The swapped handle keeps working for writes.
expect((await target.api('POST', '/api/classes', { name: 'After restore' })).status).toBe(201);
});
it('refuses files that are not a usable backup and leaves the data untouched', async () => {
const app = await newApp();
await app.api('POST', '/api/classes', { name: 'Untouched' });
const notZip = await restore(app, strToU8('just some text, not a zip file at all'));
expect(notZip.status).toBe(400);
const noDb = await restore(app, zipSync({ 'notes.txt': strToU8('hello') }));
expect(noDb.status).toBe(400);
expect(((await noDb.json()) as { error: { message: string } }).error.message).toMatch(/no study\.db/);
// A backup from a newer version (a migration this server does not know) is refused.
const files = unzipSync(await backupOf(app));
const tmp = path.join(app.dir, 'newer.db');
fs.writeFileSync(tmp, files['study.db']!);
const newer = new DatabaseSync(tmp);
newer.prepare('INSERT INTO schema_migrations (id, name, applied_at) VALUES (999999, ?, ?)').run('from_the_future', Date.now());
newer.close();
files['study.db'] = new Uint8Array(fs.readFileSync(tmp));
const future = await restore(app, zipSync(files));
expect(future.status).toBe(400);
expect(((await future.json()) as { error: { message: string } }).error.message).toMatch(/newer version/);
const classes = await app.api('GET', '/api/classes');
expect(classes.body.classes.map((c: { name: string }) => c.name)).toEqual(['Untouched']);
});
});

View file

@ -79,12 +79,13 @@ export function errorMessage(e: unknown, fallback = 'Something went wrong.'): st
return fallback;
}
/** Uploads with progress (fetch cannot report upload progress). */
export function uploadWithProgress<T>(url: string, form: FormData, onProgress: (fraction: number) => void): Promise<T> {
/** Uploads with progress (fetch cannot report upload progress). A Blob or File is sent as the raw body. */
export function uploadWithProgress<T>(url: string, form: FormData | Blob, onProgress: (fraction: number) => void): Promise<T> {
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', url);
xhr.setRequestHeader('X-Requested-With', 'studydesk');
if (form instanceof Blob) xhr.setRequestHeader('Content-Type', form.type || 'application/octet-stream');
xhr.upload.onprogress = (e) => {
if (e.lengthComputable) onProgress(e.loaded / e.total);
};

View file

@ -6,11 +6,11 @@ import { toast } from 'sonner';
import { shareUrl } from '@/features/dialogs';
import { TemplateSettings } from '@/features/TemplateSettings';
import { WebSearchSettings } from '@/features/WebSearchSettings';
import { api, errorMessage } from '@/lib/api';
import { api, ApiError, errorMessage, uploadWithProgress } from '@/lib/api';
import { qk, useRefresh } from '@/lib/queries';
import type { AppSettings, ShareAiSettings, ShareListItem, Template } from '@/lib/types';
import { copyText, cx, downloadFile, formatBytes, formatDateTime, plural, timeAgo, useDocumentTitle, useTheme } from '@/lib/util';
import { Badge, Button, Callout, ClassDot, EmptyState, Field, IconButton, Input, PageHeader, PageLoading, Section, Segmented, Select, Skeleton, Switch, useConfirm } from '@/ui';
import { Badge, Button, Callout, ClassDot, EmptyState, Field, IconButton, Input, PageHeader, PageLoading, ProgressBar, Section, Segmented, Select, Skeleton, Switch, useConfirm } from '@/ui';
const AiSettings = lazy(() => import('@/features/AiSettings'));
@ -284,17 +284,19 @@ function ShareAiSafety() {
/* ------------------------------ data ------------------------------ */
interface V1Summary {
interface RestoreSummary {
backupCreatedAt: string | null;
classes: number;
folders: number;
decks: number;
cards: number;
quizzes: number;
questions: number;
decks: number;
notes: number;
documents: number;
attempts: number;
scheduledCards: number;
activityDays: number;
skipped: string[];
files: number;
keysMoved: number;
keysUnreadable: number;
safetySnapshot: string;
stoppedJobs: number;
}
function DataSettings() {
@ -303,10 +305,9 @@ function DataSettings() {
const settings = useQuery({ queryKey: qk.settings, queryFn: () => api.get<SettingsResponse>('/api/settings') });
const backups = useQuery({ queryKey: ['backups'], queryFn: () => api.get<{ backups: { name: string; size: number; createdAt: number }[]; directory: string }>('/api/backups') });
const bundleRef = useRef<HTMLInputElement>(null);
const v1Ref = useRef<HTMLInputElement>(null);
const restoreRef = useRef<HTMLInputElement>(null);
const [busy, setBusy] = useState('');
const [v1File, setV1File] = useState<File | null>(null);
const [v1Preview, setV1Preview] = useState<V1Summary | null>(null);
const [restoreProgress, setRestoreProgress] = useState<number | null>(null);
const importBundle = async (file: File) => {
setBusy('bundle');
@ -322,25 +323,31 @@ function DataSettings() {
setBusy('');
}
};
const v1 = async (file: File, preview: boolean) => {
setBusy(preview ? 'v1preview' : 'v1');
const restore = async (file: File) => {
const ok = await confirm({
title: 'Restore this backup?',
message: `Everything on this server is replaced with ${file.name}: classes, quizzes, flashcards, documents, progress, AI models and every setting. A snapshot of what is here now is saved first under Database snapshots. You stay signed in.`,
confirmLabel: 'Replace everything',
danger: true,
});
if (!ok) return;
setBusy('restore');
setRestoreProgress(0);
try {
const form = new FormData();
form.append('file', file);
const res = await api.upload<{ summary: V1Summary }>(`/api/import/v1${preview ? '?preview=1' : ''}`, form);
if (preview) {
setV1File(file);
setV1Preview(res.summary);
} else {
await refresh();
setV1File(null);
setV1Preview(null);
toast.success(`Migrated ${plural(res.summary.classes, 'class', 'classes')} from V1`);
}
const res = await uploadWithProgress<{ summary: RestoreSummary }>('/api/backup/restore', file, (f) => setRestoreProgress(f));
const s = res.summary;
const made = s.backupCreatedAt ? ` from ${new Date(s.backupCreatedAt).toLocaleString()}` : '';
toast.success(`Backup${made} restored: ${plural(s.classes, 'class', 'classes')}, ${plural(s.quizzes, 'quiz', 'quizzes')}, ${plural(s.decks, 'deck')}, ${plural(s.files, 'file')}.`, {
description: s.keysUnreadable ? `${plural(s.keysUnreadable, 'saved API key')} could not be read on this server; enter them again in Settings → AI.` : undefined,
duration: 10_000,
});
// Every screen's data changed: start fresh.
setTimeout(() => window.location.assign('/settings/data'), 1500);
} catch (e) {
toast.error(errorMessage(e));
toast.error(e instanceof ApiError && e.status === 413 ? 'The backup is too large to upload here. If a proxy such as Cloudflare limits uploads, restore it on the server instead (see the deployment guide).' : errorMessage(e));
} finally {
setBusy('');
setRestoreProgress(null);
}
};
const sys = settings.data?.system;
@ -385,42 +392,19 @@ function DataSettings() {
<div className="p-4">
<div className="flex flex-wrap items-center gap-3">
<div className="min-w-0 flex-1 basis-64">
<div className="text-sm font-medium">Migrate from Study Desk V1</div>
<div className="text-[13px] text-ink-3">
Upload the V1 database file (<code className="num text-[12px]">study.db</code> from the old container's data folder). Classes, groups, decks, quizzes, attempt history, flashcard schedules and your activity are copied in. The V1 file is only read, never changed.
</div>
<div className="text-sm font-medium">Restore a full backup</div>
<div className="text-[13px] text-ink-3">Replaces everything on this server with a backup zip from "Download backup": content, progress, uploaded files, AI models and all settings. A snapshot of the current database is saved first.</div>
</div>
<input ref={v1Ref} type="file" accept=".db,.sqlite,.sqlite3,application/octet-stream" hidden onChange={(e) => (e.target.files?.[0] && v1(e.target.files[0], true), (e.target.value = ''))} />
<Button icon={<Upload />} loading={busy === 'v1preview'} onClick={() => v1Ref.current?.click()}>
Choose study.db
<input ref={restoreRef} type="file" accept=".zip,application/zip" hidden onChange={(e) => (e.target.files?.[0] && restore(e.target.files[0]), (e.target.value = ''))} />
<Button icon={<Upload />} loading={busy === 'restore'} onClick={() => restoreRef.current?.click()}>
Choose backup
</Button>
</div>
{v1Preview && v1File && (
<Callout tone="accent" className="mt-3" title={`Found in ${v1File.name}`}>
<div className="mt-1 grid grid-cols-2 gap-x-6 gap-y-0.5 text-[13px] sm:grid-cols-3">
<span>{plural(v1Preview.classes, 'class', 'classes')}</span>
<span>{plural(v1Preview.folders, 'group')} → folders</span>
<span>{plural(v1Preview.quizzes, 'quiz', 'quizzes')} · {plural(v1Preview.questions, 'question')}</span>
<span>{plural(v1Preview.decks, 'deck')} · {plural(v1Preview.cards, 'card')}</span>
<span>{plural(v1Preview.attempts, 'quiz attempt')}</span>
<span>{plural(v1Preview.scheduledCards, 'card schedule')}</span>
</div>
<div className="mt-3 flex flex-wrap gap-2">
<Button
size="sm"
variant="primary"
loading={busy === 'v1'}
onClick={async () => {
if (await confirm({ title: 'Migrate this V1 data?', message: 'Everything listed is added as new classes. A snapshot of the current database is taken first. Running the migration twice creates duplicates.', confirmLabel: 'Migrate' })) void v1(v1File, false);
}}
>
Migrate now
</Button>
<Button size="sm" variant="ghost" onClick={() => (setV1Preview(null), setV1File(null))}>
Cancel
</Button>
</div>
</Callout>
{restoreProgress !== null && (
<div className="mt-3 space-y-1.5">
<ProgressBar value={restoreProgress} label="Uploading the backup" />
<div className="text-xs text-ink-3">{restoreProgress < 1 ? `Uploading… ${Math.round(restoreProgress * 100)}%` : 'Restoring… this can take a minute for large backups.'}</div>
</div>
)}
</div>
</div>