diff --git a/packages/core/src/webui/backup.ts b/packages/core/src/webui/backup.ts new file mode 100644 index 00000000..132cf4e9 --- /dev/null +++ b/packages/core/src/webui/backup.ts @@ -0,0 +1,105 @@ +// WebUI config backup/restore (Wave A2). Format: a zero-dep JSON bundle +// { version, app, createdAt, files: { "": { encoding, data } } } +// over an explicit allowlist (never a whole-dir sweep) so a stray/unknown file +// can't leak and an import can't path-traverse. Credentials (webui.json password +// hash + key.pem private key) are gated by a toggle on both export and import. +// cert.pem is public so it always travels. +// +// Pure functions here (read/write/snapshot injected) — the fs glue lives in +// server.ts. Restore is restart-to-apply, like the rest of A1. + +export const BACKUP_VERSION = 1; +export const BACKUP_APP = 'snowluma'; + +export interface BackupFileSpec { + /** Path relative to the config dir; also the bundle key. */ + name: string; + binary: boolean; + /** Sensitive (private key / password hash) — gated by the credentials toggle. */ + credential: boolean; +} + +export const BACKUP_FILES: readonly BackupFileSpec[] = [ + { name: 'runtime.json', binary: false, credential: false }, + { name: 'ui.json', binary: false, credential: false }, + { name: 'onebot.json', binary: false, credential: false }, + { name: 'notifications.json', binary: false, credential: false }, + { name: 'cert.pem', binary: false, credential: false }, + { name: 'webui.json', binary: false, credential: true }, + { name: 'key.pem', binary: false, credential: true }, + { name: 'ui-assets/background', binary: true, credential: false }, +]; + +const SPEC_BY_NAME = new Map(BACKUP_FILES.map((f) => [f.name, f])); + +export interface BackupEntry { encoding: 'utf8' | 'base64'; data: string } +export interface Backup { + version: number; + app: string; + createdAt?: string; + files: Record; +} + +/** Assemble a bundle from the allowlist. `readFile` returns null for missing. */ +export function buildBackup( + readFile: (name: string) => Buffer | null, + opts: { includeCredentials: boolean }, + createdAt: string, +): Backup { + const files: Record = {}; + for (const spec of BACKUP_FILES) { + if (spec.credential && !opts.includeCredentials) continue; + const buf = readFile(spec.name); + if (!buf) continue; + files[spec.name] = spec.binary + ? { encoding: 'base64', data: buf.toString('base64') } + : { encoding: 'utf8', data: buf.toString('utf8') }; + } + return { version: BACKUP_VERSION, app: BACKUP_APP, createdAt, files }; +} + +/** Validate a parsed bundle wholesale — any defect rejects the whole import. */ +export function validateBackup(parsed: unknown): { ok: true; backup: Backup } | { ok: false; error: string } { + if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) { + return { ok: false, error: 'backup must be an object' }; + } + const b = parsed as Record; + if (b.app !== BACKUP_APP) return { ok: false, error: 'not a SnowLuma backup' }; + if (b.version !== BACKUP_VERSION) return { ok: false, error: `unsupported backup version ${String(b.version)}` }; + if (typeof b.files !== 'object' || b.files === null || Array.isArray(b.files)) { + return { ok: false, error: 'backup.files must be an object' }; + } + const files = b.files as Record; + for (const [name, entry] of Object.entries(files)) { + if (!SPEC_BY_NAME.has(name)) return { ok: false, error: `unknown file in backup: ${name}` }; + if (typeof entry !== 'object' || entry === null) return { ok: false, error: `malformed entry: ${name}` }; + const e = entry as Record; + if (e.encoding !== 'utf8' && e.encoding !== 'base64') return { ok: false, error: `bad encoding for ${name}` }; + if (typeof e.data !== 'string') return { ok: false, error: `bad data for ${name}` }; + } + return { ok: true, backup: { version: BACKUP_VERSION, app: BACKUP_APP, createdAt: typeof b.createdAt === 'string' ? b.createdAt : undefined, files: files as Record } }; +} + +/** + * Apply a (already-validated) bundle. For each file: snapshot the current one + * (so a bad restore is recoverable) then write the decoded bytes. Credential + * files are skipped unless `restoreCredentials`. + */ +export function applyBackup( + backup: Backup, + io: { snapshot: (name: string) => void; write: (name: string, data: Buffer) => void }, + opts: { restoreCredentials: boolean }, +): { restored: string[]; skipped: string[] } { + const restored: string[] = []; + const skipped: string[] = []; + for (const [name, entry] of Object.entries(backup.files)) { + const spec = SPEC_BY_NAME.get(name); + if (!spec) { skipped.push(name); continue; } // validated, but be defensive + if (spec.credential && !opts.restoreCredentials) { skipped.push(name); continue; } + const data = Buffer.from(entry.data, entry.encoding); + io.snapshot(name); + io.write(name, data); + restored.push(name); + } + return { restored, skipped }; +} diff --git a/packages/core/tests/webui-backup.test.ts b/packages/core/tests/webui-backup.test.ts new file mode 100644 index 00000000..3d2fbfba --- /dev/null +++ b/packages/core/tests/webui-backup.test.ts @@ -0,0 +1,118 @@ +import { describe, it, expect } from 'vitest'; +import { BACKUP_FILES, buildBackup, validateBackup, applyBackup } from '../src/webui/backup'; + +const TS = '2026-06-18T00:00:00.000Z'; + +function reader(map: Record) { + return (name: string): Buffer | null => map[name] ?? null; +} + +describe('buildBackup', () => { + it('includes present non-credential files and skips missing ones', () => { + const b = buildBackup(reader({ + 'runtime.json': Buffer.from('{"webuiPort":5099}'), + 'ui.json': Buffer.from('{}'), + }), { includeCredentials: false }, TS); + expect(b.version).toBe(1); + expect(b.app).toBe('snowluma'); + expect(b.createdAt).toBe(TS); + expect(Object.keys(b.files).sort()).toEqual(['runtime.json', 'ui.json']); + expect(b.files['runtime.json']).toEqual({ encoding: 'utf8', data: '{"webuiPort":5099}' }); + }); + + it('excludes credential files (webui.json, key.pem) unless includeCredentials', () => { + const map = { + 'runtime.json': Buffer.from('{}'), + 'webui.json': Buffer.from('{"hash":"x"}'), + 'key.pem': Buffer.from('KEY'), + 'cert.pem': Buffer.from('CERT'), + }; + const without = buildBackup(reader(map), { includeCredentials: false }, TS); + expect(Object.keys(without.files).sort()).toEqual(['cert.pem', 'runtime.json']); // cert is public + const withCreds = buildBackup(reader(map), { includeCredentials: true }, TS); + expect(Object.keys(withCreds.files).sort()).toEqual(['cert.pem', 'key.pem', 'runtime.json', 'webui.json']); + }); + + it('base64-encodes binary files (background image)', () => { + const png = Buffer.from([0x89, 0x50, 0x4e, 0x47]); + const b = buildBackup(reader({ 'ui-assets/background': png }), { includeCredentials: false }, TS); + expect(b.files['ui-assets/background']).toEqual({ encoding: 'base64', data: png.toString('base64') }); + }); +}); + +describe('validateBackup', () => { + const good = { version: 1, app: 'snowluma', files: { 'runtime.json': { encoding: 'utf8', data: '{}' } } }; + + it('accepts a well-formed bundle', () => { + const r = validateBackup(good); + expect(r.ok).toBe(true); + }); + + it('rejects a non-object / wrong app / wrong version', () => { + expect(validateBackup(null).ok).toBe(false); + expect(validateBackup({ ...good, app: 'other' }).ok).toBe(false); + expect(validateBackup({ ...good, version: 999 }).ok).toBe(false); + }); + + it('rejects an unknown / path-traversal filename', () => { + expect(validateBackup({ ...good, files: { '../evil': { encoding: 'utf8', data: 'x' } } }).ok).toBe(false); + expect(validateBackup({ ...good, files: { 'unknown.json': { encoding: 'utf8', data: 'x' } } }).ok).toBe(false); + }); + + it('rejects a malformed entry', () => { + expect(validateBackup({ ...good, files: { 'runtime.json': { encoding: 'rot13', data: 'x' } } }).ok).toBe(false); + expect(validateBackup({ ...good, files: { 'runtime.json': { encoding: 'utf8' } } }).ok).toBe(false); + }); +}); + +describe('applyBackup', () => { + function makeIo() { + const snapshots: string[] = []; + const writes: Record = {}; + return { + snapshots, writes, + io: { + snapshot: (name: string) => { snapshots.push(name); }, + write: (name: string, data: Buffer) => { writes[name] = data.toString(); }, + }, + }; + } + + it('snapshots then writes each restored file', () => { + const { io, snapshots, writes } = makeIo(); + const backup = { version: 1, app: 'snowluma', files: { 'runtime.json': { encoding: 'utf8' as const, data: '{"a":1}' } } }; + const res = applyBackup(backup, io, { restoreCredentials: false }); + expect(snapshots).toContain('runtime.json'); + expect(writes['runtime.json']).toBe('{"a":1}'); + expect(res.restored).toEqual(['runtime.json']); + }); + + it('skips credential files unless restoreCredentials', () => { + const { io, writes } = makeIo(); + const backup = { + version: 1, app: 'snowluma', + files: { + 'runtime.json': { encoding: 'utf8' as const, data: '{}' }, + 'webui.json': { encoding: 'utf8' as const, data: '{"hash":"x"}' }, + 'key.pem': { encoding: 'utf8' as const, data: 'KEY' }, + }, + }; + const res = applyBackup(backup, io, { restoreCredentials: false }); + expect(writes['webui.json']).toBeUndefined(); + expect(writes['key.pem']).toBeUndefined(); + expect(res.skipped.sort()).toEqual(['key.pem', 'webui.json']); + expect(res.restored).toEqual(['runtime.json']); + }); + + it('restores credentials when opted in', () => { + const { io, writes } = makeIo(); + const backup = { version: 1, app: 'snowluma', files: { 'webui.json': { encoding: 'utf8' as const, data: 'H' } } }; + applyBackup(backup, io, { restoreCredentials: true }); + expect(writes['webui.json']).toBe('H'); + }); +}); + +it('BACKUP_FILES marks webui.json and key.pem as credentials', () => { + const creds = BACKUP_FILES.filter((f) => f.credential).map((f) => f.name).sort(); + expect(creds).toEqual(['key.pem', 'webui.json']); +});