cursedbelt-server 1.0.0

package/dist/server/sharing/store.js

@@ -0,0 +1,484 @@
+import { levelsMeeting, normalizeSubjectId, strongerAccess, } from "cursedbelt-core/sharing/model";
+import { runMigrations } from "../migration/runner";
+import { SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, SHARE_MIGRATIONS, } from "./migrations";
+import { sharedResourceSql } from "./sql";
+/** Shorthand for the common subject. `group(id)` is its sibling. */
+export const user = (id) => ({ type: "user", id });
+export const group = (id) => ({ type: "group", id });
+const toGrant = (row) => ({
+    resource: { app: row.app, kind: row.kind, id: row.resource_id },
+    subject: { type: row.subject_type, id: row.subject_id },
+    level: row.level,
+    grantedBy: row.granted_by,
+    grantedAt: row.granted_at,
+    note: row.note,
+});
+const toEvent = (row) => ({
+    id: row.event_id,
+    at: row.at,
+    action: row.action,
+    resource: row.app === null || row.kind === null || row.resource_id === null
+        ? null
+        : { app: row.app, kind: row.kind, id: row.resource_id },
+    subject: { type: row.subject_type, id: row.subject_id },
+    level: row.level,
+    previousLevel: row.previous_level,
+    actor: row.actor,
+    note: row.note,
+});
+/**
+ * Open (and migrate) the sharing tables in this database, returning the store.
+ *
+ * Idempotent: safe to call once per boot per `db`, and safe to call in a database
+ * that already has the tables (the migration runner records what it applied).
+ */
+export function createShareStore(options) {
+    const { db, app } = options;
+    const clock = options.now ?? (() => new Date().toISOString());
+    if (!app.trim())
+        throw new Error("[cursedbelt-core/sharing] a share store needs an `app`");
+    runMigrations(db, SHARE_MIGRATIONS);
+    /** Collected inside a transaction, delivered after it commits — see property 4
+     *  in the file header. */
+    const emit = (events) => {
+        const hook = options.onEvent;
+        if (!hook)
+            return;
+        for (const event of events) {
+            try {
+                hook(event);
+            }
+            catch (error) {
+                console.warn(`[cursedbelt-core/sharing] a share-event listener threw: ${String(error)}`);
+            }
+        }
+    };
+    const recordEvent = (input) => {
+        db.query(`INSERT INTO ${SHARE_EVENTS_TABLE}
+			   (at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.at, input.action, input.resource?.app ?? null, input.resource?.kind ?? null, input.resource?.id ?? null, input.subject.type, input.subject.id, input.level, input.previousLevel ?? null, input.actor, input.note ?? "");
+        const id = db.query("SELECT last_insert_rowid() AS id").get().id;
+        return {
+            id,
+            at: input.at,
+            action: input.action,
+            resource: input.resource,
+            subject: input.subject,
+            level: input.level,
+            previousLevel: input.previousLevel ?? null,
+            actor: input.actor,
+            note: input.note ?? "",
+        };
+    };
+    const normalized = (subject) => ({
+        type: subject.type,
+        id: normalizeSubjectId(subject.type, subject.id),
+    });
+    const readGrant = (target, subject) => {
+        const row = db
+            .query(`SELECT * FROM ${SHARE_GRANTS_TABLE}
+				 WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?`)
+            .get(app, target.kind, target.id, subject.type, subject.id);
+        return row ? toGrant(row) : null;
+    };
+    return {
+        /** The app this store speaks for — exposed so a consumer can build its own
+         *  `sharedResourceSql` call without re-declaring the name. */
+        app,
+        /**
+         * Give `subject` access to a resource, or change the access they have.
+         *
+         * An unchanged re-grant is still recorded as a `grant` event: "the owner
+         * confirmed this on Tuesday" is a fact somebody reading the trail wants, and
+         * suppressing it would make an idempotent API silently unauditable.
+         */
+        grant(input) {
+            const subject = normalized(input.subject);
+            if (!subject.id)
+                throw new Error("[cursedbelt-core/sharing] a grant needs a subject");
+            if (!input.id)
+                throw new Error("[cursedbelt-core/sharing] a grant needs a resource id");
+            const at = clock();
+            const events = [];
+            const grant = db.transaction(() => {
+                const existing = readGrant(input, subject);
+                db.query(`INSERT INTO ${SHARE_GRANTS_TABLE}
+					   (app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note)
+					 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+					 ON CONFLICT (app, kind, resource_id, subject_type, subject_id)
+					 DO UPDATE SET level = excluded.level, granted_by = excluded.granted_by,
+					               granted_at = excluded.granted_at, note = excluded.note`).run(app, input.kind, input.id, subject.type, subject.id, input.level, input.grantedBy, at, input.note ?? "");
+                const resource = { app, kind: input.kind, id: input.id };
+                events.push(recordEvent({
+                    action: existing && existing.level !== input.level ? "regrade" : "grant",
+                    resource,
+                    subject,
+                    level: input.level,
+                    previousLevel: existing && existing.level !== input.level ? existing.level : null,
+                    actor: input.grantedBy,
+                    note: input.note,
+                    at,
+                }));
+                return {
+                    resource,
+                    subject,
+                    level: input.level,
+                    grantedBy: input.grantedBy,
+                    grantedAt: at,
+                    note: input.note ?? "",
+                };
+            })();
+            emit(events);
+            return grant;
+        },
+        /** Take access away. Returns the level that was removed, or null when there
+         *  was nothing to remove — in which case nothing is logged, because an audit
+         *  trail full of "revoked nothing" is one nobody reads. */
+        revoke(input) {
+            const subject = normalized(input.subject);
+            const at = clock();
+            const events = [];
+            const removed = db.transaction(() => {
+                const existing = readGrant(input, subject);
+                if (!existing)
+                    return null;
+                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?`).run(app, input.kind, input.id, subject.type, subject.id);
+                events.push(recordEvent({
+                    action: "revoke",
+                    resource: { app, kind: input.kind, id: input.id },
+                    subject,
+                    level: existing.level,
+                    actor: input.revokedBy,
+                    note: input.note,
+                    at,
+                }));
+                return existing.level;
+            })();
+            emit(events);
+            return removed;
+        },
+        /**
+         * Revoke EVERY grant on one resource — what an app calls when it deletes the
+         * record. Returns how many were removed.
+         *
+         * 🔴 Not optional housekeeping. Resource ids are app-minted, and a grant left
+         * behind for a deleted id becomes access to whatever is created with that id
+         * later. `apps/family` calls this in the same transaction as deleting a
+         * person.
+         */
+        revokeResource(target, revokedBy) {
+            const at = clock();
+            const events = [];
+            const count = db.transaction(() => {
+                const rows = db
+                    .query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND kind = ? AND resource_id = ?`)
+                    .all(app, target.kind, target.id);
+                if (rows.length === 0)
+                    return 0;
+                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND kind = ? AND resource_id = ?`).run(app, target.kind, target.id);
+                for (const row of rows) {
+                    events.push(recordEvent({
+                        action: "revoke",
+                        resource: { app, kind: row.kind, id: row.resource_id },
+                        subject: { type: row.subject_type, id: row.subject_id },
+                        level: row.level,
+                        actor: revokedBy,
+                        note: "the record was deleted",
+                        at,
+                    }));
+                }
+                return rows.length;
+            })();
+            emit(events);
+            return count;
+        },
+        /** Revoke everything shared with one subject, across every kind — the
+         *  offboarding call. A person losing their fleet account keeps nothing. */
+        revokeSubject(subject, revokedBy) {
+            const normal = normalized(subject);
+            const at = clock();
+            const events = [];
+            const count = db.transaction(() => {
+                const rows = db
+                    .query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = ? AND subject_id = ?`)
+                    .all(app, normal.type, normal.id);
+                if (rows.length === 0)
+                    return 0;
+                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = ? AND subject_id = ?`).run(app, normal.type, normal.id);
+                for (const row of rows) {
+                    events.push(recordEvent({
+                        action: "revoke",
+                        resource: { app, kind: row.kind, id: row.resource_id },
+                        subject: normal,
+                        level: row.level,
+                        actor: revokedBy,
+                        note: "every share with this subject was revoked",
+                        at,
+                    }));
+                }
+                return rows.length;
+            })();
+            emit(events);
+            return count;
+        },
+        /** Who can see this record, strongest first then oldest — the panel's read. */
+        listForResource(target) {
+            const rows = db
+                .query(`SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND resource_id = ?
+					 -- Strongest first, then oldest. Spelled as a CASE rather than an
+					 -- ORDER BY on level, which happens to work only because 'write'
+					 -- sorts after 'read' and would silently mis-order a third level.
+					 ORDER BY CASE level WHEN 'write' THEN 0 ELSE 1 END, granted_at ASC`)
+                .all(app, target.kind, target.id);
+            return rows.map(toGrant);
+        },
+        /** Everything shared with one subject — "shared with you". Group grants are
+         *  NOT expanded here; use {@link resourceIdsFor} for the resolved answer. */
+        listForSubject(subject) {
+            const normal = normalized(subject);
+            const rows = db
+                .query(`SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND subject_type = ? AND subject_id = ?
+					 ORDER BY granted_at DESC`)
+                .all(app, normal.type, normal.id);
+            return rows.map(toGrant);
+        },
+        /**
+         * What may this viewer do with this resource — the resolver.
+         *
+         * The strongest of their own grant and every group they are in, computed in
+         * SQL. `resolveAccess` in `cursedbelt-core/sharing` is the same rule written as a
+         * pure function, and `store.spec.ts` checks the two agree.
+         */
+        accessFor(target, viewer) {
+            const subjectId = normalizeSubjectId("user", viewer.subjectId);
+            if (!subjectId)
+                return "none";
+            const rows = db
+                .query(`SELECT level FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND resource_id = ?
+					   AND ( (subject_type = 'user' AND subject_id = ?)
+					      OR (subject_type = 'group' AND subject_id IN
+					          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )`)
+                .all(app, target.kind, target.id, subjectId, subjectId);
+            let access = "none";
+            for (const row of rows)
+                access = strongerAccess(access, row.level);
+            return access;
+        },
+        /** Every resource of `kind` this viewer reaches at `atLeast` or above.
+         *  For filtering rows in the app's OWN query, prefer `sharedResourceSql`. */
+        resourceIdsFor(kind, viewer, atLeast = "read") {
+            const subjectId = normalizeSubjectId("user", viewer.subjectId);
+            if (!subjectId)
+                return [];
+            const levels = levelsMeeting(atLeast);
+            const rows = db
+                .query(`SELECT DISTINCT resource_id FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND level IN (${levels.map(() => "?").join(", ")})
+					   AND ( (subject_type = 'user' AND subject_id = ?)
+					      OR (subject_type = 'group' AND subject_id IN
+					          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )
+					 ORDER BY resource_id`)
+                .all(app, kind, ...levels, subjectId, subjectId);
+            return rows.map((row) => row.resource_id);
+        },
+        /** The WHERE-clause half, bound to this store's app. See `./sql.ts` for why
+         *  a fragment rather than a list of ids. */
+        sharedSql(input) {
+            return sharedResourceSql({ app, ...input });
+        },
+        // ── Groups ───────────────────────────────────────────────────────────────
+        createGroup(input) {
+            const id = normalizeSubjectId("group", input.id);
+            if (!id)
+                throw new Error("[cursedbelt-core/sharing] a group needs an id");
+            const at = clock();
+            const events = [];
+            const created = db.transaction(() => {
+                db.query(`INSERT INTO ${SHARE_GROUPS_TABLE} (group_id, name, created_by, created_at, note)
+					 VALUES (?, ?, ?, ?, ?)
+					 ON CONFLICT (group_id) DO UPDATE SET name = excluded.name, note = excluded.note`).run(id, input.name, input.createdBy, at, input.note ?? "");
+                events.push(recordEvent({
+                    action: "group.create",
+                    resource: null,
+                    subject: { type: "group", id },
+                    level: null,
+                    actor: input.createdBy,
+                    note: input.name,
+                    at,
+                }));
+                return {
+                    id,
+                    name: input.name,
+                    createdBy: input.createdBy,
+                    createdAt: at,
+                    note: input.note ?? "",
+                };
+            })();
+            emit(events);
+            return created;
+        },
+        renameGroup(id, name, actor) {
+            const groupId = normalizeSubjectId("group", id);
+            const at = clock();
+            const events = [];
+            db.transaction(() => {
+                db.query(`UPDATE ${SHARE_GROUPS_TABLE} SET name = ? WHERE group_id = ?`).run(name, groupId);
+                events.push(recordEvent({
+                    action: "group.rename",
+                    resource: null,
+                    subject: { type: "group", id: groupId },
+                    level: null,
+                    actor,
+                    note: name,
+                    at,
+                }));
+            })();
+            emit(events);
+        },
+        /**
+         * Delete a group — and every grant made TO it.
+         *
+         * 🔴 The grants go with it, explicitly, each with its own revoke event. The
+         * `ON DELETE CASCADE` on membership does not reach `share_grants` (a group
+         * subject is a string, not a foreign key, because the same column holds user
+         * addresses), so a group deleted without this leaves rows nobody can see in
+         * any UI and nothing can revoke.
+         */
+        deleteGroup(id, actor) {
+            const groupId = normalizeSubjectId("group", id);
+            const at = clock();
+            const events = [];
+            db.transaction(() => {
+                const grants = db
+                    .query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = 'group' AND subject_id = ?`)
+                    .all(app, groupId);
+                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = 'group' AND subject_id = ?`).run(app, groupId);
+                for (const row of grants) {
+                    events.push(recordEvent({
+                        action: "revoke",
+                        resource: { app, kind: row.kind, id: row.resource_id },
+                        subject: { type: "group", id: groupId },
+                        level: row.level,
+                        actor,
+                        note: "the group was deleted",
+                        at,
+                    }));
+                }
+                db.query(`DELETE FROM ${SHARE_GROUPS_TABLE} WHERE group_id = ?`).run(groupId);
+                events.push(recordEvent({
+                    action: "group.delete",
+                    resource: null,
+                    subject: { type: "group", id: groupId },
+                    level: null,
+                    actor,
+                    note: "",
+                    at,
+                }));
+            })();
+            emit(events);
+        },
+        listGroups() {
+            const rows = db
+                .query(`SELECT * FROM ${SHARE_GROUPS_TABLE} ORDER BY name`)
+                .all();
+            return rows.map((row) => ({
+                id: row.group_id,
+                name: row.name,
+                createdBy: row.created_by,
+                createdAt: row.created_at,
+                note: row.note,
+            }));
+        },
+        addGroupMember(groupId, subjectId, actor) {
+            const id = normalizeSubjectId("group", groupId);
+            const member = normalizeSubjectId("user", subjectId);
+            if (!member)
+                throw new Error("[cursedbelt-core/sharing] a group member needs an address");
+            const at = clock();
+            const events = [];
+            db.transaction(() => {
+                db.query(`INSERT INTO ${SHARE_GROUP_MEMBERS_TABLE} (group_id, subject_id, added_by, added_at)
+					 VALUES (?, ?, ?, ?) ON CONFLICT (group_id, subject_id) DO NOTHING`).run(id, member, actor, at);
+                events.push(recordEvent({
+                    action: "group.join",
+                    resource: null,
+                    subject: { type: "group", id },
+                    level: null,
+                    actor,
+                    note: member,
+                    at,
+                }));
+            })();
+            emit(events);
+        },
+        removeGroupMember(groupId, subjectId, actor) {
+            const id = normalizeSubjectId("group", groupId);
+            const member = normalizeSubjectId("user", subjectId);
+            const at = clock();
+            const events = [];
+            db.transaction(() => {
+                db.query(`DELETE FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? AND subject_id = ?`).run(id, member);
+                events.push(recordEvent({
+                    action: "group.leave",
+                    resource: null,
+                    subject: { type: "group", id },
+                    level: null,
+                    actor,
+                    note: member,
+                    at,
+                }));
+            })();
+            emit(events);
+        },
+        listGroupMembers(groupId) {
+            const rows = db
+                .query(`SELECT * FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? ORDER BY subject_id`)
+                .all(normalizeSubjectId("group", groupId));
+            return rows.map((row) => ({
+                groupId: row.group_id,
+                subjectId: row.subject_id,
+                addedBy: row.added_by,
+                addedAt: row.added_at,
+            }));
+        },
+        /** Which groups is this person in — the one place membership is resolved. */
+        groupIdsFor(subjectId) {
+            const member = normalizeSubjectId("user", subjectId);
+            if (!member)
+                return [];
+            const rows = db
+                .query(`SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ? ORDER BY group_id`)
+                .all(member);
+            return rows.map((row) => row.group_id);
+        },
+        // ── The audit trail ──────────────────────────────────────────────────────
+        /** The trail, newest first. Filter by resource, by subject, or neither. */
+        events(query = {}) {
+            const clauses = ["app IS NULL OR app = ?"];
+            const params = [app];
+            if (query.kind !== undefined) {
+                clauses.push("kind = ?");
+                params.push(query.kind);
+            }
+            if (query.id !== undefined) {
+                clauses.push("resource_id = ?");
+                params.push(query.id);
+            }
+            if (query.subject) {
+                const normal = normalized(query.subject);
+                clauses.push("subject_type = ? AND subject_id = ?");
+                params.push(normal.type, normal.id);
+            }
+            const where = clauses.map((clause) => `(${clause})`).join(" AND ");
+            const limit = Math.max(1, Math.min(query.limit ?? 200, 1000));
+            const rows = db
+                .query(`SELECT * FROM ${SHARE_EVENTS_TABLE} WHERE ${where} ORDER BY event_id DESC LIMIT ?`)
+                .all(...params, limit);
+            return rows.map(toEvent);
+        },
+    };
+}

package/dist/server/sqlite/backup.d.ts

@@ -0,0 +1,48 @@
+import { Database } from 'bun:sqlite';
+export interface SqliteBackupS3Opts {
+    bucket: string;
+    /** Key prefix within the bucket, e.g. `'ca/backups'`. */
+    prefix: string;
+    /** AWS region; falls back to Bun's env resolution when omitted. */
+    region?: string;
+    /** Custom endpoint (e.g. an S3-compatible store like R2/MinIO). */
+    endpoint?: string;
+}
+export interface SqliteBackupOpts {
+    /** Directory backups are written to (created if missing). */
+    backupDir: string;
+    /** How many local backups to retain after each run. Default: 7. */
+    maxBackups?: number;
+    /** Mirror each backup to S3 after writing it locally. */
+    s3?: SqliteBackupS3Opts;
+}
+export interface BackupInfo {
+    path: string;
+    createdAt: Date;
+    sizeMb: number;
+}
+export interface SqliteBackupService {
+    /** Write a fresh backup now, mirror to S3 (if configured), prune, and describe it. */
+    runNow(): Promise<{
+        path: string;
+        sizeMb: number;
+    }>;
+    /** Local backups, newest first. */
+    listBackups(): BackupInfo[];
+    /** Delete the oldest backups beyond `maxBackups`. */
+    pruneOld(): void;
+}
+/**
+ * `VACUUM INTO` a source db path to a fresh destination file — the path-level
+ * snapshot primitive behind `createSqliteBackupService` and the satellites' own
+ * backup scripts. It is transactionally consistent even while the db is being
+ * written under WAL (unlike `cp`), and it REFUSES an existing target, so a
+ * same-instant re-run errors rather than half-overwriting a previous snapshot.
+ * Opens the source read-only, closes it, and returns the snapshot's byte size.
+ *
+ * Use this when the caller chooses the exact destination path (a dated dir, a
+ * `latest.sqlite`, a remote-pull staging file); use {@link createSqliteBackupService}
+ * when you want a managed backup DIRECTORY with timestamped names + retention + S3.
+ */
+export declare function snapshotSqlite(sourcePath: string, destPath: string): number;
+export declare function createSqliteBackupService(db: Database, opts: SqliteBackupOpts): SqliteBackupService;

package/dist/server/sqlite/backup.js

@@ -0,0 +1,97 @@
+import { Database } from 'bun:sqlite';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * SQLite backup service for `bun:sqlite` — the from-scratch replacement for the apps'
+ * `backupService.ts`. It uses `VACUUM INTO`, the correct primitive for `bun:sqlite`:
+ * it writes a compact, defragmented copy with all WAL data merged in (the Node
+ * `better-sqlite3` online `.backup()` API does not exist here). Reads continue under
+ * WAL during the copy; only writes serialize behind it — negligible for normal DB
+ * sizes, so the `daily-backup` cron job (task 29) runs it off-peak on the main thread.
+ *
+ * Optional S3 mirroring uses Bun's native S3 client (credentials from the environment,
+ * never stored here). The job *definition* lives in the app; this is the reusable
+ * mechanism.
+ */
+const BACKUP_PREFIX = 'backup-';
+const BACKUP_EXT = '.sqlite';
+const BYTES_PER_MB = 1_048_576;
+/**
+ * `VACUUM INTO` a source db path to a fresh destination file — the path-level
+ * snapshot primitive behind `createSqliteBackupService` and the satellites' own
+ * backup scripts. It is transactionally consistent even while the db is being
+ * written under WAL (unlike `cp`), and it REFUSES an existing target, so a
+ * same-instant re-run errors rather than half-overwriting a previous snapshot.
+ * Opens the source read-only, closes it, and returns the snapshot's byte size.
+ *
+ * Use this when the caller chooses the exact destination path (a dated dir, a
+ * `latest.sqlite`, a remote-pull staging file); use {@link createSqliteBackupService}
+ * when you want a managed backup DIRECTORY with timestamped names + retention + S3.
+ */
+export function snapshotSqlite(sourcePath, destPath) {
+    const source = new Database(sourcePath, { readonly: true });
+    try {
+        source.run(`VACUUM INTO '${destPath.replaceAll("'", "''")}'`);
+    }
+    finally {
+        source.close();
+    }
+    return statSync(destPath).size;
+}
+const hasBunS3 = () => typeof Bun.S3Client === 'function';
+async function uploadToS3(localPath, s3) {
+    if (!hasBunS3()) {
+        console.warn('[sqlite-backup] S3 is configured but Bun.S3Client is unavailable; skipping upload. ' +
+            'Upgrade Bun (≥1.1) or remove the s3 option.');
+        return;
+    }
+    const client = new Bun.S3Client({
+        bucket: s3.bucket,
+        region: s3.region,
+        endpoint: s3.endpoint,
+    });
+    const key = `${s3.prefix.replace(/\/+$/, '')}/${localPath.split('/').pop()}`;
+    await client.file(key).write(Bun.file(localPath));
+}
+export function createSqliteBackupService(db, opts) {
+    const { backupDir, maxBackups = 7, s3 } = opts;
+    if (s3 && !hasBunS3()) {
+        console.warn('[sqlite-backup] S3 mirroring requested but Bun.S3Client is unavailable in this runtime; ' +
+            'backups will be written locally only.');
+    }
+    const service = {
+        async runNow() {
+            mkdirSync(backupDir, { recursive: true });
+            // ISO timestamp (filesystem-safe) + a short random suffix so rapid successive
+            // runs in the same millisecond never collide onto one path.
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const outPath = join(backupDir, `${BACKUP_PREFIX}${stamp}-${randomBytes(3).toString('hex')}${BACKUP_EXT}`);
+            // VACUUM INTO checkpoints the WAL and writes a clean, compact copy.
+            db.run('VACUUM INTO ?', [outPath]);
+            const sizeMb = statSync(outPath).size / BYTES_PER_MB;
+            if (s3)
+                await uploadToS3(outPath, s3);
+            service.pruneOld();
+            return { path: outPath, sizeMb };
+        },
+        listBackups() {
+            if (!existsSync(backupDir))
+                return [];
+            return readdirSync(backupDir)
+                .filter((f) => f.startsWith(BACKUP_PREFIX) && f.endsWith(BACKUP_EXT))
+                .map((f) => {
+                const path = join(backupDir, f);
+                const stat = statSync(path);
+                return { path, createdAt: stat.mtime, sizeMb: stat.size / BYTES_PER_MB };
+            })
+                .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || b.path.localeCompare(a.path));
+        },
+        pruneOld() {
+            for (const old of service.listBackups().slice(maxBackups)) {
+                rmSync(old.path, { force: true });
+            }
+        },
+    };
+    return service;
+}

package/dist/server/sqlite/browse.d.ts

@@ -0,0 +1,42 @@
+import type { Database } from 'bun:sqlite';
+/** Clamp a requested page size into `[1, MAX_PAGE]`, falling back when unparseable. */
+export declare function clampLimit(raw: number | string | undefined, fallback: number): number;
+/** Clamp an offset to a non-negative integer (0 when unparseable). */
+export declare function clampOffset(raw: number | string | undefined): number;
+/** Is `name` an actual table in this DB? (The injection guard for `SELECT * FROM`.) */
+export declare function isKnownTable(db: Database, name: string): boolean;
+/** Double-quote a name already proven to exist in `sqlite_master`. */
+export declare function quoteIdent(name: string): string;
+export interface SqliteTableInfo {
+    name: string;
+    count: number;
+}
+/** User tables (FTS shadow + `sqlite_*` internals excluded) with row counts. */
+export declare function listSqliteTables(db: Database): SqliteTableInfo[];
+export interface SqliteTablePage {
+    items: Record<string, unknown>[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export declare class UnknownTableError extends Error {
+    readonly table: string;
+    constructor(table: string);
+}
+/**
+ * A clamped, paginated window over one table. Throws {@link UnknownTableError} for a
+ * table that isn't in `sqlite_master` (callers map that to a 404).
+ */
+export declare function readSqliteTable(db: Database, table: string, opts?: {
+    limit?: number | string;
+    offset?: number | string;
+}): SqliteTablePage;
+export declare class NotReadOnlyError extends Error {
+    constructor();
+}
+/**
+ * Run an ad-hoc read-only query with bound params. Throws {@link NotReadOnlyError}
+ * for anything the {@link isReadOnlySql} guard rejects (non-SELECT, stacked
+ * statements, PRAGMA, …); SQLite errors (bad column/table) propagate as `Error`.
+ */
+export declare function runReadonlySqlite(db: Database, sql: string, params?: unknown[]): Record<string, unknown>[];