@adminiumjs/adminium 0.1.0-rc.1

package/dist/backup/backup-service.js

@@ -0,0 +1,354 @@
+/**
+ * The §9 backup writer (11-electron.md §9) — the thing behind
+ * `POST /api/v1/desktop/backup`.
+ *
+ * It runs HERE, in the server, and not in the Electron main process, because §1
+ * principle 2 says so and because the reason it says so is load-bearing: this
+ * process is the one holding `ADMINIUM_SECRET`, the meta connection and the
+ * source-DB pools. A main process that produced the archive itself would have to
+ * open every database behind the back of the process writing to them.
+ *
+ * ─── Order is the guarantee ──────────────────────────────────────────────────
+ *
+ * discover → snapshot to a scratch dir → hash what was actually written →
+ * build the manifest FROM THOSE HASHES → zip → move into place.
+ *
+ * Every step reads the previous step's output rather than its intent. The
+ * manifest cannot overstate the archive (its checksums are of the bytes that
+ * went in, not of the files that were meant to), and the destination does not
+ * exist until the whole archive does — a crash mid-backup leaves a scratch
+ * directory, never a truncated `.zip` that a restore would cheerfully open.
+ *
+ * ─── Redaction ───────────────────────────────────────────────────────────────
+ *
+ * `config.json` travels with `secretEncrypted`/`secretPlain` stripped (§9). This
+ * module does not do the stripping and must not learn how: the desktop config is
+ * the main process's (§2.3), so the REDACTED body arrives as a parameter, and
+ * {@link assertNoSecrets} refuses to write it if it carries a secret-shaped key
+ * anyway. That is the `export/redaction.ts` rule — fail closed at the boundary,
+ * do not trust the caller's promise — applied to the one config this server does
+ * not own.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { strToU8, zipSync } from 'fflate';
+import { APP_VERSION } from '../version.js';
+import { BACKUP_CONFIG_PATH, BACKUP_FILE_PATTERN, BACKUP_FORMAT_VERSION, BACKUP_MANIFEST_PATH, BACKUP_META_PATH, backupDatabasePath, backupFileName, sha256Hex, } from './format.js';
+import { discoverSources, snapshotSqliteFile } from './snapshot.js';
+/** `<dataDir>/backups` — §9's auto-backup home and the staging root. */
+export const BACKUPS_DIR = 'backups';
+/**
+ * §9's rotation depth, default 7.
+ *
+ * Stated here AND in `apps/desktop/src/main/config.ts`, which is a duplication
+ * with a reason: that file is the schema for `config.json`, whose default this
+ * genuinely is, and this file is the server, which may not import the Electron
+ * app (`.dependency-cruiser.cjs` — the edge only runs the other way). The value
+ * is a number in a spec, not a decision either module gets to make, and the two
+ * are pinned to each other by `backup-defaults.test.ts`.
+ */
+export const DEFAULT_AUTO_BACKUP_KEEP = 7;
+/**
+ * Where a `staged` archive lands before the main process moves it to the path
+ * the user picked in the save dialog.
+ *
+ * Dot-prefixed and inside `backups/` on purpose. Inside, because the move to the
+ * user's chosen path is then a same-filesystem `rename` in the common case
+ * (both under the data dir's volume) instead of a cross-device copy. Dotted,
+ * because `<dataDir>/backups` is a folder §9 reveals to the user, and a
+ * half-written staging file appearing in it next to their real backups is
+ * confusing at best; the rotation sweep also skips it, since
+ * `BACKUP_FILE_PATTERN` cannot match a directory name.
+ */
+export const BACKUP_STAGING_DIR = '.staging';
+/**
+ * `secretEncrypted` and `secretPlain` are §9's named pair, but the assertion is
+ * SHAPE-based rather than a list of two, for the reason `export/redaction.ts`
+ * gives at length: a deny-list rots. A future `config.json` field called
+ * `apiToken` would be invisible to a two-name check and would ship in every
+ * backup from the day it was added.
+ */
+const SECRET_KEY_PATTERN = /secret|password|token|apikey|credential/i;
+/**
+ * The one key that is secret-SHAPED and is not a secret: `config.secretStorage`.
+ *
+ * It names WHERE the secret lives — `"safeStorage"` or `"plain"` — and §2.2
+ * step 3 / §13 require it to survive, because it is what makes the About screen
+ * warn that the master secret is sitting in cleartext. `redactConfig` keeps it
+ * on purpose (see its allow-list); a check that dropped it would silence a
+ * security warning in the name of security.
+ *
+ * Exempted by EXACT name AND by value: the two enum members are the only strings
+ * that can pass, so a future field called `secretStorage` holding anything else
+ * — a token, a path, a key — still fails. An exception to a fail-closed rule has
+ * to be narrower than the rule.
+ */
+const SECRET_STORAGE_KEY = 'secretStorage';
+const SECRET_STORAGE_VALUES = new Set(['safeStorage', 'plain']);
+/** Thrown when a redacted config is not, in fact, redacted. The backup aborts. */
+export class BackupRedactionError extends Error {
+    name = 'BackupRedactionError';
+    constructor(key) {
+        super(`refusing to write config.json into a backup: it still carries "${key}", which is ` +
+            'secret-shaped. 11-electron.md §9 requires the desktop config to travel with its ' +
+            'secrets stripped — the caller redacts (main/config.ts redactConfig), this asserts. ' +
+            'A backup zip is a file users email to support.');
+    }
+}
+/**
+ * Refuse a config body carrying anything secret-shaped, at any depth.
+ *
+ * Recursive because `config.json` is nested (`lanShare`, `updates`, `window`)
+ * and a top-level-only check would pass `{ updates: { token: "…" } }` — which is
+ * exactly the shape a future field would take.
+ */
+export function assertNoSecrets(value, path = 'config') {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries())
+            assertNoSecrets(item, `${path}[${String(index)}]`);
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (key === SECRET_STORAGE_KEY && SECRET_STORAGE_VALUES.has(item))
+            continue;
+        if (SECRET_KEY_PATTERN.test(key))
+            throw new BackupRedactionError(`${path}.${key}`);
+        assertNoSecrets(item, `${path}.${key}`);
+    }
+}
+/**
+ * The meta store's migration high-water mark — the ledger's last applied name.
+ *
+ * Read from `adminium_migrations`, not from `ALL_MIGRATIONS`, and the difference
+ * is the whole point of the field: what a restore has to reason about is the
+ * schema the ARCHIVE actually carries, not the one the build that wrote it
+ * happened to ship. They are normally equal (every boot fast-forwards), and when
+ * they are not it is because something went wrong — which is precisely when a
+ * manifest that reported the build's number would lie.
+ */
+async function readMetaMigrationVersion(meta) {
+    const rows = await meta.db
+        .selectFrom('adminium_migrations')
+        .select('name')
+        .orderBy('name', 'desc')
+        .limit(1)
+        .execute();
+    const latest = rows[0]?.name;
+    if (latest === undefined) {
+        throw new Error('refusing to back up a meta store with no applied migrations — there is nothing ' +
+            'here to restore, and an archive claiming otherwise would be worse than none.');
+    }
+    return latest;
+}
+/**
+ * Produce a §9 archive. Returns where it landed and what went in it.
+ *
+ * `zipSync` + in-memory buffers rather than a streaming writer: a desktop
+ * install's databases are the ones a person keeps on a laptop, the snapshots are
+ * already on disk before any of this runs, and a streaming zip would trade a
+ * bounded, obvious memory profile for a partially-written archive on the failure
+ * path. `mtime: createdAt` (not the zip epoch the M10 config bundle uses)
+ * because a backup is a MOMENT, not a diffable artifact — the reproducibility
+ * that matters there is exactly what would be wrong here.
+ */
+export async function createBackup(opts) {
+    const now = opts.now ?? Date.now;
+    const createdAt = now();
+    const dataDir = resolve(opts.dataDir);
+    if (opts.redactedConfig !== null && opts.redactedConfig !== undefined) {
+        assertNoSecrets(opts.redactedConfig);
+    }
+    // Staging is a HANDOFF, and every handoff drops things. A staged archive is
+    // claimed by the main process moving it to the user's chosen path — but that
+    // move can fail (the destination drive unplugged, permissions) or never happen
+    // at all (the app is killed between the reply and the move). Nothing else
+    // would ever remove it: rotation is documented to skip this directory, and
+    // these are FULL copies of every database. Left alone, a dot-directory nobody
+    // looks in grows by a whole install's worth of data every time a save goes
+    // wrong. So each backup sweeps the leftovers of the ones before it.
+    await sweepStaging(dataDir, createdAt);
+    const metaMigrationVersion = await readMetaMigrationVersion(opts.meta);
+    const sources = await discoverSources(opts.meta, opts.crypto);
+    // A scratch dir per run: `backup()` needs a real destination file, two backups
+    // must never collide over one, and a crash must leave its debris somewhere
+    // sweepable rather than in `backups/`.
+    const scratch = join(dataDir, BACKUPS_DIR, BACKUP_STAGING_DIR, `work-${randomBytes(8).toString('hex')}`);
+    await mkdir(scratch, { recursive: true });
+    try {
+        const files = {};
+        // meta.db first: it is the file whose loss is unrecoverable, so if the disk
+        // is going to be full, be full before the source snapshots waste minutes.
+        const metaSnapshot = join(scratch, 'meta.db');
+        await snapshotSqliteFile(opts.metaPath, metaSnapshot);
+        const metaBytes = await readFile(metaSnapshot);
+        files[BACKUP_META_PATH] = metaBytes;
+        const databases = [];
+        for (const source of sources.local) {
+            const dest = join(scratch, `${source.slug}.sqlite`);
+            await snapshotSqliteFile(source.path, dest);
+            const bytes = await readFile(dest);
+            const member = backupDatabasePath(source.slug);
+            files[member] = bytes;
+            databases.push({
+                kind: 'local',
+                slug: source.slug,
+                file: member,
+                bytes: bytes.byteLength,
+                sha256: sha256Hex(bytes),
+                connectionId: source.connectionId,
+                sourcePath: source.path,
+            });
+        }
+        for (const source of sources.external) {
+            databases.push({
+                kind: 'external',
+                slug: source.slug,
+                connectionId: source.connectionId,
+                engine: source.engine,
+            });
+        }
+        const manifest = {
+            formatVersion: BACKUP_FORMAT_VERSION,
+            appVersion: opts.appVersion ?? null,
+            serverVersion: APP_VERSION,
+            metaMigrationVersion,
+            createdAt,
+            meta: {
+                file: BACKUP_META_PATH,
+                bytes: metaBytes.byteLength,
+                sha256: sha256Hex(metaBytes),
+            },
+            databases,
+        };
+        if (opts.redactedConfig !== null && opts.redactedConfig !== undefined) {
+            files[BACKUP_CONFIG_PATH] = strToU8(`${JSON.stringify(opts.redactedConfig, null, 2)}\n`);
+        }
+        files[BACKUP_MANIFEST_PATH] = strToU8(`${JSON.stringify(manifest, null, 2)}\n`);
+        const zipped = zipSync(nest(files), { level: 6, mtime: new Date(createdAt) });
+        const path = opts.destination === 'auto'
+            ? join(dataDir, BACKUPS_DIR, backupFileName(createdAt))
+            : join(dataDir, BACKUPS_DIR, BACKUP_STAGING_DIR, `${randomBytes(8).toString('hex')}.zip`);
+        // Write beside the target and rename, for the same reason `saveConfig` does:
+        // a reader (the restore path, the CLI import) must never see a `.zip` that
+        // is still being written. Same directory ⇒ the rename is atomic.
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.part`;
+        await writeFile(tmp, zipped);
+        await rename(tmp, path);
+        return { path, bytes: zipped.byteLength, manifest };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * How long a staged archive is allowed to sit unclaimed before a later backup
+ * removes it.
+ *
+ * Generous on purpose: the only thing between the server writing a staged
+ * archive and the main process moving it is one `rename`, so anything still
+ * there an hour later was abandoned. The window exists at all because a sweep
+ * that deleted by mtime alone could race a move that is genuinely in flight —
+ * on a slow cross-device copy to a USB stick, of a multi-gigabyte archive.
+ */
+export const STAGING_TTL_MS = 60 * 60 * 1000;
+/**
+ * Remove abandoned staging entries older than {@link STAGING_TTL_MS}.
+ *
+ * Best-effort throughout: this is housekeeping, and a backup must never fail
+ * because a leftover from last week could not be deleted. Confined to
+ * `<dataDir>/backups/.staging`, which only this module ever writes to — unlike
+ * `backups/` itself, it is not a folder users are shown, so age is a safe
+ * criterion here in a way it explicitly is not one directory up.
+ */
+async function sweepStaging(dataDir, now) {
+    const dir = join(dataDir, BACKUPS_DIR, BACKUP_STAGING_DIR);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        const path = join(dir, name);
+        try {
+            const info = await stat(path);
+            if (now - info.mtimeMs < STAGING_TTL_MS)
+                continue;
+            await rm(path, { recursive: true, force: true });
+        }
+        catch {
+            // Locked, vanished under us, or a permission we do not have. The next
+            // backup tries again.
+        }
+    }
+}
+/** fflate takes a nested object; our member paths are flat `a/b` strings. */
+function nest(files) {
+    const root = {};
+    for (const [path, bytes] of Object.entries(files)) {
+        const parts = path.split('/');
+        let cursor = root;
+        for (const part of parts.slice(0, -1)) {
+            cursor[part] ??= {};
+            cursor = cursor[part];
+        }
+        cursor[parts[parts.length - 1]] = bytes;
+    }
+    return root;
+}
+/**
+ * §9: keep the newest `keep` archives in `<dataDir>/backups/`, delete the rest.
+ *
+ * ─── The two rules that keep this from being a data-loss bug ─────────────────
+ *
+ * 1. It only ever considers files matching {@link BACKUP_FILE_PATTERN}. That
+ *    directory is `showItemInFolder`-revealed (§9), so users WILL put things in
+ *    it — a copy of a backup they renamed, a note. "Delete the oldest files in
+ *    the folder" would eat them. This deletes archives this code wrote, and
+ *    nothing else.
+ * 2. It sorts by NAME, not mtime. The names are UTC-stamped and
+ *    lexicographically ordered by construction ({@link backupFileName}), whereas
+ *    mtime is metadata that a file copy, an rsync, or a restore-from-Time-Machine
+ *    rewrites — and a rotation that sorted on it after such an event would delete
+ *    a real backup and keep an old one.
+ *
+ * Best-effort per file: a locked archive (Windows, an open zip viewer) must not
+ * fail the BACKUP that just succeeded. The next sweep gets it.
+ */
+export async function rotateBackups(dataDir, keep, deps) {
+    const dir = join(resolve(dataDir), BACKUPS_DIR);
+    let names;
+    try {
+        names = await deps.readdir(dir);
+    }
+    catch {
+        return { kept: [], removed: [] };
+    }
+    const archives = names.filter((name) => BACKUP_FILE_PATTERN.test(name)).sort();
+    const cut = Math.max(0, archives.length - keep);
+    const doomed = archives.slice(0, cut);
+    const removed = [];
+    for (const name of doomed) {
+        try {
+            await deps.rm(join(dir, name));
+            removed.push(name);
+        }
+        catch {
+            // See above: a sweep that fails is a sweep, not a failed backup.
+        }
+    }
+    return { kept: archives.slice(cut), removed };
+}
+/** The real filesystem, for {@link rotateBackups}. */
+export function rotateBackupsOnDisk(dataDir, keep) {
+    return rotateBackups(dataDir, keep, {
+        readdir: (dir) => readdir(dir),
+        rm: (path) => rm(path, { force: true }),
+    });
+}
+//# sourceMappingURL=backup-service.js.map

package/dist/backup/backup-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-service.js","sourceRoot":"","sources":["../../src/backup/backup-service.ts"],"names":[],"mappings":"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"}

package/dist/backup/format.d.ts

@@ -0,0 +1,300 @@
+/**
+ * THE DESKTOP BACKUP FORMAT (11-electron.md §9), frozen at `formatVersion: 1`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THIS FILE IS A WIRE CONTRACT, NOT AN IMPLEMENTATION DETAIL. A zip written by
+ * any build must be readable by any other, so the layout, the manifest shape and
+ * the slug grammar live in ONE module, imported by the writer
+ * (`backup-service.ts`), the reader (`apps/desktop/src/main/backup-archive.ts`,
+ * via a mirrored schema pinned to these types) and the tests. Changing anything
+ * here is a `formatVersion` bump, not an edit.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * ─── THE M10 CLI DOES NOT READ THIS FORMAT. §9's INTEROP CLAIM IS UNBUILT ────
+ *
+ * §9 says the backup zip "doubles as the migration path to self-host/Cloud:
+ * `npx adminium` import accepts the same format". IT DOES NOT, and this header
+ * used to assert that it did. The truth, so nobody plans around the fiction:
+ *
+ * There are TWO unrelated archive formats that both independently call
+ * themselves `formatVersion: 1`.
+ *
+ *  - THIS one (§9 backup): `manifest.json` at the archive ROOT, carrying
+ *    `{ formatVersion, appVersion, serverVersion, metaMigrationVersion,
+ *    createdAt, meta, databases }`, plus `meta.db` and `databases/*.sqlite` —
+ *    a byte-level snapshot of a whole desktop install.
+ *  - The M10 CONFIG BUNDLE (`export/bundle.ts`): `adminium-export/manifest.json`
+ *    with a required, DISJOINT shape (`{ appVersion, configVersion, metaVersion,
+ *    exportedAt, connectionId, secrets, counts }`), describing rows to upsert.
+ *
+ * `cli/commands/import-zip.ts` → `export/import-service.ts` reads only the
+ * second: `parseBundle` demands `adminium-export/manifest.json` and throws
+ * "it is not an Adminium configuration bundle" for anything else. A desktop user
+ * who follows §9's stated migration path is told their backup is not an Adminium
+ * file. Nothing outside the desktop reader and a parity test has ever imported
+ * {@link BACKUP_FORMAT_VERSION}.
+ *
+ * WHY IT IS NOT MERELY A MISSING `if`. The two formats are not dialects, they
+ * are different operations. The bundle import replays CONFIG ROWS into whatever
+ * meta store the target runs; this archive's `meta.db` is a SQLite FILE, and a
+ * self-host target's meta store is routinely Postgres or MySQL. Making the CLI
+ * "accept the same archive" therefore means reading a SQLite meta store and
+ * translating every table into another dialect — a cross-dialect meta migration,
+ * not a branch. That is a real feature with a real design, and no task in
+ * 11-T12 or M10 covers it.
+ *
+ * WHOEVER PICKS THIS UP: sniffing a root `manifest.json` in `parseBundle` is the
+ * entry point, and the version gate below is ready for it. Until then, the
+ * desktop restore (`main/backup.ts`) is the only reader of this format, and
+ * anything telling a user otherwise — docs, dialog copy, this comment — is
+ * making a promise the code does not keep.
+ *
+ * The archive (§9, verbatim):
+ *
+ * ```
+ * adminium-backup-20260712-1430.zip
+ *   manifest.json              { formatVersion, appVersion, serverVersion,
+ *                                metaMigrationVersion, createdAt, databases: [...] }
+ *   meta.db                    meta-store snapshot
+ *   config.json                desktop config, secrets REDACTED
+ *   databases/<slug>.sqlite    every LOCAL source DB
+ * ```
+ *
+ * ─── Two places this completes §9 rather than quoting it ─────────────────────
+ *
+ * 1. **`databases[]` is a discriminated union.** §9's example row is
+ *    `{ slug, file, bytes, sha256 }`, and its prose says remote PG/MySQL "are
+ *    listed in manifest.json as 'external', never dumped". A row that is not
+ *    dumped has no `file`, no `bytes` and no `sha256` to carry, so the two cases
+ *    cannot be one shape. {@link BackupDatabaseEntry} is therefore
+ *    `kind: 'local' | 'external'`; the local arm is §9's four fields exactly,
+ *    plus the provenance (`connectionId`, `sourcePath`) a restore needs to
+ *    explain itself. Reading the union back as §9's example means: take the
+ *    local arm.
+ * 2. **`meta` carries its own checksum.** §9 lists `meta.db` as an archive
+ *    member and puts checksums only on `databases[]`. That asymmetry cannot be
+ *    right: a restore validates checksums *before* it moves the live data aside
+ *    (§9's flow), and meta.db is the file whose corruption is unrecoverable —
+ *    it holds every connection, page and user. A backup whose source DBs verify
+ *    and whose meta.db is truncated would pass validation and then destroy the
+ *    install. Since `formatVersion: 1` is being frozen by this task rather than
+ *    inherited, the hole is closed now instead of being shipped and versioned
+ *    around.
+ *
+ * NOTHING ELSE IS ADDED. In particular there is no `secrets` block: `config.json`
+ * travels redacted, unconditionally, and a manifest field describing a policy
+ * with one possible value would only invite a second value later.
+ */
+import { z } from 'zod';
+/**
+ * FROZEN (§9: "format frozen here as `formatVersion: 1`").
+ *
+ * READ BY: the desktop restore's `validateArchive`, which refuses a higher
+ * number rather than parsing leniently — the same rule `config.ts`'s version
+ * gate and the M10 bundle's already obey.
+ *
+ * NOT read by the M10 CLI, whatever §9 says — see the module header. This
+ * doc-comment used to claim it was; the claim was never true and the number is
+ * the same either way, which is exactly why nobody noticed.
+ */
+export declare const BACKUP_FORMAT_VERSION = 1;
+/** Archive member paths. The reader allow-lists against these — see below. */
+export declare const BACKUP_MANIFEST_PATH = "manifest.json";
+export declare const BACKUP_META_PATH = "meta.db";
+export declare const BACKUP_CONFIG_PATH = "config.json";
+export declare const BACKUP_DATABASES_DIR = "databases";
+/** `databases/<slug>.sqlite` — the ONLY shape a source-DB member may have. */
+export declare function backupDatabasePath(slug: string): string;
+/**
+ * The slug grammar, and the reason it is this narrow.
+ *
+ * A slug is interpolated into an archive member path and then, on restore, into
+ * a filesystem path under `<dataDir>/databases/`. That makes it the one value in
+ * this format that can escape its directory: `../../config.json` is a perfectly
+ * good zip entry name, and an unpacker that trusted it would overwrite the
+ * desktop config — with the master secret in it — from inside an archive a user
+ * double-clicked. Lowercase alnum + `-` + `_` cannot express a separator, a
+ * drive letter, a dot segment, or a NUL, so the traversal is not defended
+ * against, it is unrepresentable.
+ *
+ * The reader re-validates every slug it reads (it must: the archive is untrusted
+ * input, and the writer's guarantees are the writer's), which is why this regex
+ * is exported rather than inlined at the point of use.
+ */
+export declare const BACKUP_SLUG_PATTERN: RegExp;
+export declare const backupSlugSchema: z.ZodString;
+/** SHA-256, lowercase hex — the digest every checksum field carries. */
+export declare const sha256Schema: z.ZodString;
+export declare function sha256Hex(bytes: Uint8Array): string;
+/**
+ * A LOCAL source database: dumped, checksummed, restorable.
+ *
+ * `sourcePath` is provenance, not an instruction. It records where the file was
+ * when the backup ran; the restore does NOT write to it. See
+ * `apps/desktop/src/main/backup-archive.ts` for why an unpacker that honoured an
+ * absolute path out of an archive would be a remote-file-write primitive.
+ *
+ * It is READ, though — by `assertRestorablePaths`, which refuses any archive
+ * whose `sourcePath` is not already `<dataDir>/databases/<slug>.sqlite` on the
+ * target. That check is the whole reason this field is load-bearing rather than
+ * decorative: the unpack writes to the slug-derived path and `meta.db` is
+ * restored byte-for-byte, so a `sourcePath` that disagrees means the restored
+ * DSN would point somewhere the bytes are not — and the slug might belong to a
+ * different connection entirely. Provenance is exactly what is needed to notice
+ * that, and refusing is exactly what may be done with it.
+ */
+export declare const backupLocalDatabaseSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    slug: z.ZodString;
+    file: z.ZodString;
+    bytes: z.ZodNumber;
+    sha256: z.ZodString;
+    connectionId: z.ZodString;
+    sourcePath: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A REMOTE source database (§9: "remote PG/MySQL are listed in manifest.json as
+ * 'external', never dumped").
+ *
+ * Listed rather than omitted, because the difference between "this instance had
+ * no Postgres" and "this instance had a Postgres we did not dump" is the whole
+ * question a person asks when a restore comes up short. No DSN, not even
+ * encrypted: the DSN is in meta.db, and a manifest is the one file in the
+ * archive that is read before anything is trusted.
+ */
+export declare const backupExternalDatabaseSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    slug: z.ZodString;
+    connectionId: z.ZodString;
+    engine: z.ZodString;
+}, z.core.$strict>;
+export declare const backupDatabaseEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    slug: z.ZodString;
+    file: z.ZodString;
+    bytes: z.ZodNumber;
+    sha256: z.ZodString;
+    connectionId: z.ZodString;
+    sourcePath: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    slug: z.ZodString;
+    connectionId: z.ZodString;
+    engine: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type BackupLocalDatabase = z.infer<typeof backupLocalDatabaseSchema>;
+export type BackupExternalDatabase = z.infer<typeof backupExternalDatabaseSchema>;
+export type BackupDatabaseEntry = z.infer<typeof backupDatabaseEntrySchema>;
+/** `meta.db`'s own entry — see point 2 in the module header. */
+export declare const backupMetaEntrySchema: z.ZodObject<{
+    file: z.ZodLiteral<"meta.db">;
+    bytes: z.ZodNumber;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export type BackupMetaEntry = z.infer<typeof backupMetaEntrySchema>;
+/**
+ * `manifest.json` (§9).
+ *
+ * `strictObject`, like `config.json`'s schema and for the same reason: an
+ * unknown key is a hand-edit or a typo, and a genuinely newer archive is caught
+ * one field earlier by {@link BACKUP_FORMAT_VERSION}, with a message the user
+ * can act on.
+ */
+export declare const backupManifestSchema: z.ZodObject<{
+    formatVersion: z.ZodNumber;
+    appVersion: z.ZodNullable<z.ZodString>;
+    serverVersion: z.ZodString;
+    metaMigrationVersion: z.ZodString;
+    createdAt: z.ZodNumber;
+    meta: z.ZodObject<{
+        file: z.ZodLiteral<"meta.db">;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
+    databases: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"local">;
+        slug: z.ZodString;
+        file: z.ZodString;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+        connectionId: z.ZodString;
+        sourcePath: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"external">;
+        slug: z.ZodString;
+        connectionId: z.ZodString;
+        engine: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+export type BackupManifest = z.infer<typeof backupManifestSchema>;
+/**
+ * §9: "the migration runner fast-forwards an older backup; a backup whose
+ * `metaMigrationVersion` is **newer** than the app is refused".
+ *
+ * LEXICOGRAPHIC, and that is a property of the names rather than a hope about
+ * them: `@adminium/meta`'s ledger names every migration `NNNN_slug` with a
+ * zero-padded, append-only ordinal (`0001_core_auth` … `0009_views_kind`), so
+ * string order IS apply order for as long as the counter has four digits — about
+ * 9,990 migrations from now. That matters because the comparison has to work in
+ * the Electron MAIN process, which may not import `@adminium/meta` (§1
+ * principle 2 / `.dependency-cruiser.cjs` `desktop-shell-only`) and therefore
+ * cannot look a name up in `ALL_MIGRATIONS`. Two strings and `<` it can do.
+ *
+ * `same` and `older` are both restorable; only `newer` is refused. `older` is
+ * not merely tolerated but EXPECTED — it is what restoring last month's backup
+ * into this month's build is — and the meta migrator fast-forwards it at the
+ * next boot with no special casing anywhere.
+ */
+export type BackupVersionOrder = 'older' | 'same' | 'newer';
+export declare function compareMetaMigrationVersion(backupVersion: string, appVersion: string): BackupVersionOrder;
+/** §9's `adminium-backup-20260712-1430.zip`. */
+export declare const BACKUP_FILE_PREFIX = "adminium-backup-";
+export declare const BACKUP_FILE_EXTENSION = ".zip";
+/**
+ * Matches {@link backupFileName}'s output. The rotation sweep uses it as an
+ * allow-list rather than deleting whatever is in `<dataDir>/backups/`: that
+ * directory is `showItemInFolder`-revealed (§9) and users put things in folders
+ * they can see. Rotation deletes files THIS code wrote and nothing else.
+ */
+export declare const BACKUP_FILE_PATTERN: RegExp;
+/**
+ * `adminium-backup-YYYYMMDD-HHMMSS.zip`, in UTC.
+ *
+ * §9's example shows minutes (`…-1430.zip`); seconds are here because rotation
+ * sorts by NAME (the only ordering that survives a file copy, an rsync, or a
+ * restored-from-Time-Machine backups folder — mtime does not), and two backups
+ * in one minute would then be indistinguishable and unorderable. UTC for the
+ * same reason: a local-time name goes backwards for an hour every autumn, and a
+ * rotation that sorts names would delete the wrong one.
+ */
+export declare function backupFileName(createdAt: number): string;
+/** `<dataDir>/pre-restore-<ts>` (§9). The folder a restore never deletes. */
+export declare const PRE_RESTORE_PREFIX = "pre-restore-";
+export declare function preRestoreDirName(at: number): string;
+/**
+ * A slug for a local database file, derived from its BASENAME.
+ *
+ * The basename, not the connection name, because on desktop they are the same
+ * thing by construction: §6 step 2 creates `<dataDir>/databases/<slug>.sqlite`
+ * from the name the user typed, so the file already carries the slug the user
+ * chose and round-tripping through it keeps `databases/orders.sqlite` in the
+ * archive named `orders`. Deriving from `connection.name` instead would rename
+ * everything the moment somebody edited a label, and "Open an existing SQLite
+ * file" (§6 step 2, opened in place) has a real filename and a name the user
+ * never picked.
+ *
+ * Falls back to the connection id for a basename that survives none of the
+ * grammar — a file called `数据.sqlite` is legitimate and must not fail a backup.
+ */
+export declare function deriveDatabaseSlug(filePath: string, connectionId: string): string;
+/**
+ * Make `slug` unique against `taken`, appending `-2`, `-3`, …
+ *
+ * Needed because slugs come from basenames and basenames are only unique within
+ * a directory: "Open an existing SQLite file" can register
+ * `~/work/app.sqlite` and `~/archive/app.sqlite` as two connections, and two
+ * archive members called `databases/app.sqlite` means the second silently
+ * replaces the first — a backup that looks complete and has lost a database.
+ */
+export declare function uniqueSlug(slug: string, taken: ReadonlySet<string>): string;
+//# sourceMappingURL=format.d.ts.map