@intactfile/engines 0.1.0

package/dist/sqlite/recover.js

@@ -0,0 +1,305 @@
+import { MemorySource } from '../byte-source.js';
+import { diagnoseSqlite } from './diagnose.js';
+import { parseHeader } from './format.js';
+import { PageReader, parseCreateTableColumns, parseSchema, rawScanLeafPages, walkTableBtree, } from './scan.js';
+import { buildFreshDatabase } from './sqlite-host.js';
+import { parseWal } from './wal.js';
+const LOST_AND_FOUND = 'lost_and_found';
+const MAX_LAF_COLUMNS = 32;
+/**
+ * Recover a SQLite database into a fresh one. Returns the new database bytes
+ * (omitted only when nothing could be produced) and an honest report.
+ */
+export async function recoverSqlite(src, opts = {}) {
+    const walBytes = opts.wal ? await toBytes(opts.wal) : undefined;
+    const diagnosis = await diagnoseSqlite(src, { walPresent: walBytes !== undefined });
+    const notes = [...diagnosis.notes];
+    const caveats = [];
+    const fail = (extra) => {
+        if (extra)
+            notes.push(extra);
+        return {
+            report: {
+                outcome: 'failed',
+                damageClass: diagnosis.damageClass,
+                strategy: null,
+                tablesRecovered: 0,
+                rowsRecovered: 0,
+                orphanCount: 0,
+                rowsFailedInsert: 0,
+                cellsDropped: 0,
+                tables: [],
+                caveats,
+                notes,
+                walApplied: false,
+                bytesIn: src.size,
+                bytesOut: 0,
+            },
+        };
+    };
+    if (diagnosis.damageClass === 'not-sqlite') {
+        return fail('input is not a SQLite database; recovery not attempted');
+    }
+    if (diagnosis.damageClass === 'encrypted') {
+        return fail('database appears encrypted (SQLCipher/SEE); recovery requires the key and is not attempted');
+    }
+    const bytes = await src.read(0, src.size);
+    const header = parseHeader(bytes);
+    if (!header) {
+        return fail('the database header is destroyed; the page size cannot be established, so pages cannot be located');
+    }
+    const textEncoding = header.textEncoding >= 1 && header.textEncoding <= 3 ? header.textEncoding : 1;
+    // Layer the -wal overlay if present.
+    let overlay;
+    let walApplied = false;
+    if (walBytes) {
+        const wal = parseWal(walBytes);
+        notes.push(...wal.notes);
+        if (wal.valid && wal.pages.size > 0 && wal.pageSize === header.pageSize) {
+            overlay = wal.pages;
+            walApplied = true;
+        }
+        else if (wal.valid && wal.pageSize !== header.pageSize) {
+            notes.push('-wal page size does not match the database; overlay skipped');
+        }
+    }
+    const reader = new PageReader(bytes, header.pageSize, header.reservedBytes, overlay);
+    if (reader.maxPage < 1) {
+        return fail('file is smaller than a single page; nothing to recover');
+    }
+    const schema = parseSchema(reader, textEncoding);
+    notes.push(...schema.notes);
+    const skip = new Set(schema.schemaPages);
+    skip.add(1);
+    const working = [];
+    let strategy = 'btree-walk';
+    if (schema.ok) {
+        for (const entry of schema.entries) {
+            if (entry.type !== 'table' || entry.name.startsWith('sqlite_'))
+                continue;
+            const cols = parseCreateTableColumns(entry.sql);
+            if (!cols) {
+                notes.push(`table "${entry.name}": CREATE statement could not be parsed; its rows will go to ${LOST_AND_FOUND}`);
+                continue;
+            }
+            const walk = walkTableBtree(reader, entry.rootpage, textEncoding);
+            for (const p of walk.visitedPages)
+                skip.add(p);
+            working.push({
+                entry: { name: entry.name, rootpage: entry.rootpage, sql: entry.sql },
+                columns: cols.columns,
+                ipkColumn: cols.ipkColumn,
+                rows: walk.rows,
+                viaRawScan: false,
+                complete: walk.complete,
+                droppedCells: walk.droppedCells,
+            });
+        }
+    }
+    else {
+        strategy = 'dump-fallback';
+        notes.push('schema unreadable: performing a .dump-style raw extraction into lost_and_found');
+    }
+    // Pointer-free sweep for everything the walks did not reach.
+    const orphansRaw = rawScanLeafPages(reader, textEncoding, skip);
+    // Attribute orphan rows to a table when the column count is unambiguous.
+    const byColCount = new Map();
+    for (const t of working) {
+        const list = byColCount.get(t.columns.length) ?? [];
+        list.push(t);
+        byColCount.set(t.columns.length, list);
+    }
+    const orphans = [];
+    for (const rec of orphansRaw) {
+        const candidates = byColCount.get(rec.values.length);
+        if (candidates && candidates.length === 1) {
+            const target = candidates[0];
+            target.rows.push({ rowid: rec.rowid, values: rec.values });
+            target.viaRawScan = true;
+            if (strategy === 'btree-walk')
+                strategy = 'raw-page-scan';
+        }
+        else {
+            orphans.push(rec);
+        }
+    }
+    const anyData = working.some((t) => t.rows.length > 0) || orphans.length > 0;
+    if (!anyData) {
+        return fail('no decodable rows were found anywhere in the file');
+    }
+    // Assemble the fresh-database build spec.
+    const statements = [];
+    const tableReports = [];
+    let rowsAttempted = 0;
+    for (const t of working) {
+        const rowsForTable = t.rows.length;
+        // Only skip empty non-recovered tables when nothing came out at all.
+        statements.push({ sql: buildCreateTable(t) });
+        if (rowsForTable > 0) {
+            const insert = buildInsert(t);
+            statements.push({ sql: insert.sql, rows: t.rows.map((r) => insert.bind(r)) });
+            rowsAttempted += rowsForTable;
+        }
+        tableReports.push({
+            name: t.entry.name,
+            columns: t.columns.length,
+            rowsRecovered: rowsForTable,
+            viaRawScan: t.viaRawScan,
+            complete: t.complete,
+            droppedCells: t.droppedCells,
+        });
+    }
+    if (orphans.length > 0) {
+        const maxFields = Math.min(MAX_LAF_COLUMNS, orphans.reduce((m, o) => Math.max(m, o.values.length), 0));
+        statements.push({ sql: buildLostAndFoundTable(maxFields) });
+        const lafSql = buildLostAndFoundInsert(maxFields);
+        statements.push({
+            sql: lafSql,
+            rows: orphans.map((o) => bindLostAndFound(o, maxFields)),
+        });
+        rowsAttempted += orphans.length;
+    }
+    const built = await buildFreshDatabase({ statements });
+    // Compose the report.
+    const rowsRecovered = built.rowsInserted;
+    const rowsFailedInsert = built.rowsFailed;
+    const tablesRecovered = tableReports.length;
+    const truncated = diagnosis.damageClass === 'truncated';
+    const anyIncomplete = working.some((t) => !t.complete || t.viaRawScan);
+    const droppedCells = working.reduce((sum, t) => sum + t.droppedCells, 0);
+    if (droppedCells > 0) {
+        notes.push(`${droppedCells} cell(s) present on intact pages could not be decoded (bit-rot) and were dropped`);
+        caveats.push(`${droppedCells} row(s) were present but too corrupted to decode; they are missing from the recovered database.`);
+    }
+    caveats.push("SQLite's own guidance: data recovered from a corrupt database is always suspect. Verify it against a known-good source before relying on it.");
+    caveats.push('Deleted rows may reappear: the scan reads freelist and unvacuumed pages, so previously-deleted records can resurface.');
+    caveats.push('Values reflect on-disk storage classes, not the original declared column affinities; a column’s type may shift.');
+    if (truncated) {
+        caveats.push('The file was truncated: any data beyond the cut is physically gone and cannot be recovered.');
+    }
+    if (orphans.length > 0) {
+        caveats.push(`${orphans.length} record(s) could not be attributed to a table and were placed in the ${LOST_AND_FOUND} table.`);
+    }
+    if (walApplied) {
+        caveats.push('A -wal sidecar was overlaid; recovered state reflects the last committed transaction in the WAL.');
+    }
+    if (rowsFailedInsert > 0) {
+        notes.push(`${rowsFailedInsert} row(s) were rejected by the fresh database (e.g. duplicate rowids) and dropped`);
+    }
+    let outcome;
+    if (diagnosis.damageClass === 'none' &&
+        !truncated &&
+        !anyIncomplete &&
+        orphans.length === 0 &&
+        rowsFailedInsert === 0 &&
+        droppedCells === 0 &&
+        strategy === 'btree-walk') {
+        outcome = 'success';
+    }
+    else {
+        outcome = 'partial';
+        if (truncated)
+            notes.push('truncated input: recovered what physically survived the cut');
+        if (anyIncomplete)
+            notes.push('some tables were reconstructed by the pointer-free scan after b-tree damage');
+    }
+    return {
+        db: built.bytes,
+        report: {
+            outcome,
+            damageClass: diagnosis.damageClass,
+            strategy,
+            tablesRecovered,
+            rowsRecovered,
+            orphanCount: orphans.length,
+            rowsFailedInsert,
+            cellsDropped: droppedCells,
+            tables: tableReports,
+            caveats,
+            notes,
+            walApplied,
+            bytesIn: src.size,
+            bytesOut: built.bytes.length,
+        },
+    };
+}
+async function toBytes(x) {
+    if (x instanceof Uint8Array)
+        return x;
+    return x.read(0, x.size);
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Synthesize a permissive CREATE TABLE: original column names, INTEGER PRIMARY
+ * KEY preserved so the rowid alias round-trips, but no NOT NULL/UNIQUE/CHECK/FK
+ * constraints that could reject resurrected rows (real .recover relaxes too).
+ */
+function buildCreateTable(t) {
+    const cols = t.columns.map((c, i) => i === t.ipkColumn ? `${quoteIdent(c)} INTEGER PRIMARY KEY` : quoteIdent(c));
+    return `CREATE TABLE ${quoteIdent(t.entry.name)} (${cols.join(', ')})`;
+}
+/**
+ * Build the INSERT plan for a table. When there is an INTEGER PRIMARY KEY the
+ * rowid is written into that column; otherwise the rowid is written into the
+ * `_rowid_` pseudo-column so it is preserved faithfully.
+ */
+function buildInsert(t) {
+    const n = t.columns.length;
+    if (t.ipkColumn !== null) {
+        const colList = t.columns.map(quoteIdent).join(', ');
+        const placeholders = t.columns.map(() => '?').join(', ');
+        const ipk = t.ipkColumn;
+        return {
+            sql: `INSERT OR IGNORE INTO ${quoteIdent(t.entry.name)} (${colList}) VALUES (${placeholders})`,
+            bind: (row) => {
+                const vals = normalizeRow(row.values, n);
+                vals[ipk] = coerceRowid(row.rowid);
+                return vals;
+            },
+        };
+    }
+    const colList = ['"_rowid_"', ...t.columns.map(quoteIdent)].join(', ');
+    const placeholders = new Array(n + 1).fill('?').join(', ');
+    return {
+        sql: `INSERT OR IGNORE INTO ${quoteIdent(t.entry.name)} (${colList}) VALUES (${placeholders})`,
+        bind: (row) => [coerceRowid(row.rowid), ...normalizeRow(row.values, n)],
+    };
+}
+/** Pad/truncate a decoded row to the table's column count. */
+function normalizeRow(values, n) {
+    if (values.length === n)
+        return values.slice();
+    const out = values.slice(0, n);
+    while (out.length < n)
+        out.push(null);
+    return out;
+}
+function coerceRowid(rowid) {
+    return rowid;
+}
+function buildLostAndFoundTable(maxFields) {
+    const cols = ['"pgno" INTEGER', '"cellidx" INTEGER', '"nfield" INTEGER', '"rowid" INTEGER'];
+    for (let i = 0; i < maxFields; i++)
+        cols.push(quoteIdent(`c${i}`));
+    return `CREATE TABLE ${quoteIdent(LOST_AND_FOUND)} (${cols.join(', ')})`;
+}
+function buildLostAndFoundInsert(maxFields) {
+    const cols = ['"pgno"', '"cellidx"', '"nfield"', '"rowid"'];
+    for (let i = 0; i < maxFields; i++)
+        cols.push(quoteIdent(`c${i}`));
+    const placeholders = new Array(cols.length).fill('?').join(', ');
+    return `INSERT INTO ${quoteIdent(LOST_AND_FOUND)} (${cols.join(', ')}) VALUES (${placeholders})`;
+}
+function bindLostAndFound(o, maxFields) {
+    const out = [o.pageNo, o.cellIndex, o.values.length, coerceRowid(o.rowid)];
+    for (let i = 0; i < maxFields; i++)
+        out.push(o.values[i] ?? null);
+    return out;
+}
+/** Convenience wrapper for callers holding raw bytes. */
+export function recoverSqliteBytes(bytes, opts) {
+    return recoverSqlite(new MemorySource(bytes), opts);
+}
+//# sourceMappingURL=recover.js.map

package/dist/sqlite/recover.js.map

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

package/dist/sqlite/scan.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Raw b-tree / page scanner: the recovery brain. It reads a (possibly corrupt)
+ * database at the byte level and extracts rows two ways:
+ *
+ *  1. `walkTableBtree` follows a table's b-tree from its root page, the way a
+ *     healthy reader would — fast and exact when the pointers are intact.
+ *  2. `rawScanLeafPages` ignores all pointers and treats every table-leaf page
+ *     in the file as a bag of records. This is what SQLite's own `.recover`
+ *     does via the dbdata/dbptr virtual tables: it survives zeroed interior
+ *     pages, freelisted pages and dropped tables, at the cost of not knowing
+ *     which table a stray page belonged to.
+ *
+ * Pure and dependency-free: works identically in Node and the browser.
+ */
+import { type SqlValue } from './format.js';
+/** Random access to database pages, with an optional `-wal` overlay layered on top. */
+export declare class PageReader {
+    private readonly bytes;
+    private readonly overlay?;
+    readonly pageSize: number;
+    readonly usableSize: number;
+    readonly filePageCount: number;
+    constructor(bytes: Uint8Array, pageSize: number, reservedBytes: number, overlay?: Map<number, Uint8Array> | undefined);
+    /** Highest page number reachable from the file or the WAL overlay. */
+    get maxPage(): number;
+    /** Bytes of a page (1-based). The last page may be short after a truncation. */
+    page(pageNo: number): Uint8Array | null;
+}
+export interface RecoveredRow {
+    rowid: number | bigint;
+    values: SqlValue[];
+}
+export interface TableWalkResult {
+    rows: RecoveredRow[];
+    /** Pages visited (so a later raw scan can skip them). */
+    visitedPages: Set<number>;
+    /** False when a page was missing/invalid mid-walk (partial subtree lost). */
+    complete: boolean;
+    /** Cells present on visited leaves that could not be decoded (bit-rot). */
+    droppedCells: number;
+}
+/**
+ * Walk a table b-tree from `rootpage`, collecting every decodable leaf row.
+ * Robust to loops (visited set), missing pages and bad subtrees: any failure
+ * degrades the walk to `complete: false` rather than throwing.
+ */
+export declare function walkTableBtree(reader: PageReader, rootpage: number, textEncoding: number): TableWalkResult;
+export interface OrphanRecord {
+    pageNo: number;
+    cellIndex: number;
+    rowid: number | bigint;
+    values: SqlValue[];
+    serialTypes: number[];
+}
+/**
+ * Pointer-free sweep: every table-leaf page in the file (except `skip`) is read
+ * as an independent bag of records. This is how rows survive a zeroed interior
+ * page or a dropped table. Records here are un-attributed — the caller decides
+ * whether a shape matches a known table or must land in lost_and_found.
+ */
+export declare function rawScanLeafPages(reader: PageReader, textEncoding: number, skip: Set<number>): OrphanRecord[];
+export interface MasterEntry {
+    type: string;
+    name: string;
+    tblName: string;
+    rootpage: number;
+    sql: string;
+}
+export interface SchemaParse {
+    entries: MasterEntry[];
+    ok: boolean;
+    /** Pages consumed by the schema b-tree (page 1 and any overflow/interior). */
+    schemaPages: Set<number>;
+    notes: string[];
+}
+/**
+ * Read the schema table (`sqlite_master`, rooted at page 1). Each row is
+ * (type, name, tbl_name, rootpage, sql). Failure to walk page 1 yields ok:false
+ * so the caller can fall back to a pure raw scan.
+ */
+export declare function parseSchema(reader: PageReader, textEncoding: number): SchemaParse;
+export interface TableColumns {
+    columns: string[];
+    /** Index of the INTEGER PRIMARY KEY column (the rowid alias), or null. */
+    ipkColumn: number | null;
+}
+/**
+ * Light CREATE TABLE column parser for the common case: pulls column names from
+ * the top-level column list and flags an INTEGER PRIMARY KEY rowid alias.
+ * Exotic DDL (generated columns, unusual quoting) may not parse — recovery
+ * degrades to lost_and_found rather than guessing, and says so.
+ */
+export declare function parseCreateTableColumns(sql: string): TableColumns | null;
+//# sourceMappingURL=scan.d.ts.map

package/dist/sqlite/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/sqlite/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAGL,KAAK,QAAQ,EAQd,MAAM,aAAa,CAAC;AAErB,uFAAuF;AACvF,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAGtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAR3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAGZ,KAAK,EAAE,UAAU,EAClC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACJ,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,YAAA;IAOpD,sEAAsE;IACtE,IAAI,OAAO,IAAI,MAAM,CAIpB;IAED,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;CAQxC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,yDAAyD;IACzD,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,eAAe,CA2CjB;AAwFD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAChB,YAAY,EAAE,CAgBhB;AAiCD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,8EAA8E;IAC9E,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,CAqBjF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAwCxE"}