Public: anyone can read this; the crew can change it.

An app backup never follows a symlink swapped in after the walk #14929

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/14899-an-app-backup-never-follows-a-symlink-sw → main 2 commits fork

  • Merged. torque/14899-an-app-backup-never-follows-a-symlink-sw was merged into main as bf7fb2c.

Review

Sign in to review this change.
2 files changed +201 −29
src/apps/backup.ts +125 −28
@@ -24,6 +24,7 @@ import {
2424 } from "node:crypto";
2525 import {
2626 closeSync,
27 constants,
2728 existsSync,
2829 fstatSync,
2930 fsyncSync,
@@ -32,6 +33,7 @@ import {
3233 mkdtempSync,
3334 openSync,
3435 readdirSync,
36 readlinkSync,
3537 readSync,
3638 realpathSync,
3739 renameSync,
@@ -70,15 +72,23 @@ export interface Proof {
7072
7173 const CHUNK = 1 << 18;
7274
75 /**
76 * Size and SHA-256 of what is open on `fd`, read a chunk at a time from the start: never whole in
77 * memory.
78 */
79 function hashFd(fd: number): { size: number; sha256: string } {
80 const h = createHash("sha256");
81 const buf = Buffer.allocUnsafe(CHUNK);
82 let size = 0;
83 for (let n; (n = readSync(fd, buf, 0, CHUNK, size)) > 0; size += n) h.update(buf.subarray(0, n));
84 return { size, sha256: h.digest("hex") };
85 }
86
7387 /** Size and SHA-256 of a file, read a chunk at a time: the file is never whole in memory. */
7488 export function hashFile(path: string): { size: number; sha256: string } {
7589 const fd = openSync(path, "r");
7690 try {
77 const h = createHash("sha256");
78 const buf = Buffer.allocUnsafe(CHUNK);
79 let size = 0;
80 for (let n; (n = readSync(fd, buf, 0, CHUNK, null)) > 0; size += n) h.update(buf.subarray(0, n));
81 return { size, sha256: h.digest("hex") };
91 return hashFd(fd);
8292 } finally {
8393 closeSync(fd);
8494 }
@@ -122,15 +132,66 @@ export function passphraseProblem(p: string | undefined): string | undefined {
122132 return undefined;
123133 }
124134
125 function walk(root: string, rel = "", out: string[] = [], skipped: string[] = []): { files: string[]; skipped: string[] } {
135 /** A file the walk saw: its path under the root and the inode `lstat` found there. */
136 interface Walked {
137 path: string;
138 dev: number;
139 ino: number;
140 }
141
142 function walk(root: string, rel = "", out: Walked[] = [], skipped: string[] = []): { files: Walked[]; skipped: string[] } {
126143 for (const e of readdirSync(join(root, rel), { withFileTypes: true })) {
127144 const r = rel === "" ? e.name : `${rel}/${e.name}`;
128145 if (e.isDirectory()) walk(root, r, out, skipped);
129146 else if (/-(wal|shm)$/.test(e.name)) continue; // emptied by the checkpoint
130 else if (e.isFile()) out.push(r);
131 else skipped.push(r);
147 else if (e.isFile()) {
148 let st: ReturnType<typeof lstatSync> | undefined;
149 try {
150 st = lstatSync(join(root, r));
151 } catch {
152 skipped.push(r); // gone between readdir and lstat
153 continue;
154 }
155 if (st?.isFile()) out.push({ path: r, dev: st.dev, ino: st.ino });
156 else skipped.push(r);
157 } else skipped.push(r);
132158 }
133 return { files: out.sort(), skipped: skipped.sort() };
159 return { files: out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)), skipped: skipped.sort() };
160 }
161
162 /**
163 * Open a file the walk saw, or say why not. The last name is never followed
164 * (`O_NOFOLLOW`; `O_NONBLOCK` so a FIFO swapped in never hangs the open), and
165 * the decision is made on the descriptor, never the path (Bun has no
166 * `openat`): `fstat` must find a regular file with the walk's own dev/ino, and
167 * where `/proc` names what a descriptor holds, it must be `root/path`, so a
168 * directory above swapped for a link to forge-side files (`secret.key`,
169 * another app's data) is refused too. A refusal names the path and why; nothing stays open.
170 */
171 function openWalked(root: string, f: Walked): { fd: number } | { refused: string } {
172 let fd: number;
173 try {
174 fd = openSync(join(root, f.path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
175 } catch (error) {
176 const code = (error as NodeJS.ErrnoException).code;
177 if (code === "ELOOP" || code === "EMLINK") return { refused: `${f.path}: became a symlink after the walk; not followed` };
178 return { refused: `${f.path}: could not be opened after the walk (${code ?? "error"})` };
179 }
180 const refuse = (why: string): { refused: string } => {
181 closeSync(fd);
182 return { refused: `${f.path}: ${why}` };
183 };
184 const st = fstatSync(fd);
185 if (!st.isFile()) return refuse("is no longer a regular file; not archived");
186 if (st.dev !== f.dev || st.ino !== f.ino) return refuse("is not the file the walk saw (replaced); not archived");
187 let held: string | undefined;
188 try {
189 held = readlinkSync(`/proc/self/fd/${fd}`);
190 } catch {
191 held = undefined; // no /proc (not Linux): dev/ino is the check
192 }
193 if (held !== undefined && held !== join(root, f.path)) return refuse("is reached through a link above it; not followed");
194 return { fd };
134195 }
135196
136197 const isSqlite = (bytes: Uint8Array): boolean =>
@@ -160,16 +221,30 @@ export function tableCounts(path: string): Record<string, number> | undefined {
160221 const headerFor = (salt: Buffer, iv: Buffer): Buffer =>
161222 Buffer.from(`${JSON.stringify({ v: 1, kdf: "scrypt", salt: salt.toString("base64url"), iv: iv.toString("base64url") })}\n`);
162223
163 const startsSqlite = (path: string): boolean => {
164 const fd = openSync(path, "r");
224 const startsSqlite = (fd: number): boolean => {
225 const b = Buffer.alloc(16);
226 return readSync(fd, b, 0, 16, 0) === 16 && isSqlite(b);
227 };
228
229 /**
230 * Is `path` under `root` still the inode `f` names? Checked around a read that cannot take a
231 * descriptor.
232 */
233 const sameInode = (root: string, f: Walked): boolean => {
165234 try {
166 const b = Buffer.alloc(16);
167 return readSync(fd, b, 0, 16, 0) === 16 && isSqlite(b);
168 } finally {
169 closeSync(fd);
235 const st = lstatSync(join(root, f.path));
236 return st.isFile() && st.dev === f.dev && st.ino === f.ino;
237 } catch {
238 return false;
170239 }
171240 };
172241
242 /** Test seam: runs between the walk and the first open, where a swap would land. */
243 export interface SealHooks {
244 /** `root` is the directory the seal reads (the snapshot), `paths` what the walk found in it. */
245 afterWalk?(root: string, paths: string[]): void;
246 }
247
173248 /**
174249 * Seal a data directory into `out`, written as it is built: each file is
175250 * hashed for the manifest, then streamed a chunk at a time through the cipher
@@ -178,7 +253,7 @@ const startsSqlite = (path: string): boolean => {
178253 * proof calls it out. `out` is written as given; `sealAndProve` names it
179254 * `.part` and renames it only on PROVEN. Throws a message for unusable input.
180255 */
181 export function sealToFile(dir: string, out: string, passphrase: string): Manifest {
256 export function sealToFile(dir: string, out: string, passphrase: string, hooks: SealHooks = {}): Manifest {
182257 const bad = passphraseProblem(passphrase);
183258 if (bad !== undefined) throw new Error(bad);
184259 if (!existsSync(dir) || !lstatSync(dir).isDirectory()) throw new Error("the data directory does not exist");
@@ -189,23 +264,42 @@ export function sealToFile(dir: string, out: string, passphrase: string): Manife
189264 const snapshot = join(dirname(resolve(out)), `.${basename(out)}.${randomBytes(6).toString("hex")}.snapshot`);
190265 try {
191266 cloneDir(dir, snapshot);
192 return sealSnapshot(snapshot, out, passphrase);
267 return sealSnapshot(snapshot, out, passphrase, hooks);
193268 } finally {
194269 rmSync(snapshot, { recursive: true, force: true });
195270 }
196271 }
197272
198 function sealSnapshot(dir: string, out: string, passphrase: string): Manifest {
199 const found = walk(dir);
273 /**
274 * Seal the snapshot. It is the forge's own copy, yet every open is still
275 * judged on its descriptor against what the walk saw (`openWalked`): the
276 * snapshot is a second line, never the only one.
277 */
278 function sealSnapshot(dir: string, out: string, passphrase: string, hooks: SealHooks): Manifest {
279 const root = realpathSync(dir);
280 const found = walk(root);
281 hooks.afterWalk?.(root, found.files.map((f) => f.path));
200282 const manifest: Manifest = { files: [], tables: {}, skipped: found.skipped };
201 for (const path of found.files) {
202 const full = join(dir, path);
203 manifest.files.push({ path, ...hashFile(full) });
204 if (startsSqlite(full)) {
205 const counts = tableCounts(full);
206 if (counts !== undefined) manifest.tables[path] = counts;
283 const kept: Walked[] = [];
284 for (const f of found.files) {
285 const opened = openWalked(root, f);
286 if ("refused" in opened) {
287 manifest.skipped!.push(f.path); // the proof names it: not archived
288 continue;
289 }
290 try {
291 manifest.files.push({ path: f.path, ...hashFd(opened.fd) });
292 kept.push(f);
293 // SQLite opens by name: count only while the name is still the inode just hashed.
294 if (startsSqlite(opened.fd) && sameInode(root, f)) {
295 const counts = tableCounts(join(root, f.path));
296 if (counts !== undefined && sameInode(root, f)) manifest.tables[f.path] = counts;
297 }
298 } finally {
299 closeSync(opened.fd);
207300 }
208301 }
302 manifest.skipped!.sort();
209303 const salt = randomBytes(16);
210304 const iv = randomBytes(12);
211305 const header = headerFor(salt, iv);
@@ -222,8 +316,11 @@ function sealSnapshot(dir: string, out: string, passphrase: string): Manifest {
222316 len.writeUInt32BE(m.length);
223317 put(cipher.update(Buffer.concat([len, m])));
224318 const buf = Buffer.allocUnsafe(CHUNK);
225 for (const f of manifest.files) {
226 const src = openSync(join(dir, f.path), "r");
319 for (const [i, f] of manifest.files.entries()) {
320 // The same inode the walk saw and the hash read, or the seal is refused naming the path.
321 const opened = openWalked(root, kept[i]!);
322 if ("refused" in opened) throw new Error(`the data directory changed under the backup: ${opened.refused}`);
323 const src = opened.fd;
227324 try {
228325 let left = f.size;
229326 while (left > 0) {
@@ -415,7 +512,7 @@ export function sourceDrift(dir: string, manifest: Manifest): string[] {
415512 const problems: string[] = [];
416513 const now = walk(dir);
417514 const had = new Set(manifest.files.map((f) => f.path));
418 for (const p of now.files) if (!had.has(p)) problems.push(`${p}: appeared in the data directory after the backup was read`);
515 for (const { path: p } of now.files) if (!had.has(p)) problems.push(`${p}: appeared in the data directory after the backup was read`);
419516 for (const f of manifest.files) {
420517 // A database is sealed as a checkpointed, checked snapshot: its bytes
421518 // differ from the live file and its log by design, not by drift.
test/app-backup.test.ts +76 −1
@@ -1,7 +1,7 @@
11 import { Database } from "bun:sqlite";
22 import { describe, expect, test } from "bun:test";
33 import { createCipheriv, randomBytes, scryptSync } from "node:crypto";
4 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, truncateSync, writeFileSync } from "node:fs";
4 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, truncateSync, writeFileSync } from "node:fs";
55 import { tmpdir } from "node:os";
66 import { join } from "node:path";
77 import { type Manifest, restoreProof, sealAndProve, sealToFile, sourceDrift as sourceDriftOf, tableCounts } from "../src/apps/backup.ts";
@@ -144,6 +144,81 @@ describe("the proof is against the manifest and the source", () => {
144144 });
145145 });
146146
147 describe("a name swapped after the walk is never followed (#14899)", () => {
148 /** A forge-side file outside the app's data: what a swapped link would reach. */
149 const forgeSide = (): { dir: string; key: string } => {
150 const dir = tmp();
151 writeFileSync(join(dir, "secret.key"), "FORGE-SIDE-SECRET");
152 return { dir, key: join(dir, "secret.key") };
153 };
154 const restored = (sealed: Buffer): { proof: Exclude<ReturnType<typeof restoreProof>, string>; bytes: string } => {
155 const scratch = join(tmp(), "out");
156 const proof = restoreProof(sealed, PASS, scratch);
157 if (typeof proof === "string") throw new Error(proof);
158 const all: string[] = [];
159 const read = (d: string): void => {
160 for (const e of readdirSync(d, { withFileTypes: true }))
161 e.isDirectory() ? read(join(d, e.name)) : all.push(readFileSync(join(d, e.name), "latin1"));
162 };
163 if (existsSync(scratch)) read(scratch);
164 return { proof, bytes: all.join("\n") };
165 };
166
167 test("a file swapped for a symlink between walk and open is skipped, named, and its target never sealed", () => {
168 const d = app();
169 const { key } = forgeSide();
170 const out = join(tmp(), "b.fab");
171 const manifest = sealToFile(d, out, PASS, {
172 afterWalk(root, paths) {
173 expect(paths).toContain("uploads/a/x.txt");
174 rmSync(join(root, "uploads/a/x.txt"));
175 symlinkSync(key, join(root, "uploads/a/x.txt"));
176 },
177 });
178 expect(manifest.files.map((f) => f.path)).toEqual(["app.db"]);
179 expect(manifest.skipped).toEqual(["uploads/a/x.txt"]);
180 const { proof, bytes } = restored(readFileSync(out));
181 expect(bytes.includes("FORGE-SIDE-SECRET")).toBe(false);
182 expect(proof.ok).toBe(false);
183 expect(proof.problems).toContain("uploads/a/x.txt: not archived (a symlink or special file); the backup does not cover it");
184 });
185
186 test("a directory above swapped for a symlink is skipped: the descriptor's own path is checked", () => {
187 const d = app();
188 const outside = forgeSide();
189 const out = join(tmp(), "b.fab");
190 const manifest = sealToFile(d, out, PASS, {
191 afterWalk(root) {
192 // Same leaf name, reached through a link: O_NOFOLLOW alone does not see it.
193 renameSync(join(outside.dir, "secret.key"), join(outside.dir, "x.txt"));
194 rmSync(join(root, "uploads/a"), { recursive: true });
195 symlinkSync(outside.dir, join(root, "uploads/a"));
196 },
197 });
198 expect(manifest.skipped).toEqual(["uploads/a/x.txt"]);
199 expect(restored(readFileSync(out)).bytes.includes("FORGE-SIDE-SECRET")).toBe(false);
200 });
201
202 test("a file replaced by another regular file after the walk is skipped (dev/ino differ)", () => {
203 const d = app();
204 const out = join(tmp(), "b.fab");
205 const manifest = sealToFile(d, out, PASS, {
206 afterWalk(root) {
207 writeFileSync(join(root, "uploads/a/other"), "SWAPPED-IN");
208 renameSync(join(root, "uploads/a/other"), join(root, "uploads/a/x.txt"));
209 },
210 });
211 expect(manifest.skipped).toEqual(["uploads/a/x.txt"]);
212 expect(restored(readFileSync(out)).bytes.includes("SWAPPED-IN")).toBe(false);
213 });
214
215 test("an unchanged tree seals every file it walked", () => {
216 const manifest = sealToFile(app(), join(tmp(), "b.fab"), PASS, { afterWalk() {} });
217 expect(manifest.files.map((f) => f.path)).toEqual(["app.db", "uploads/a/x.txt"]);
218 expect(manifest.skipped).toEqual([]);
219 });
220 });
221
147222 describe("scripts/app-backup.ts", () => {
148223 test("prove restores a sealed file and exits 0; a wrong passphrase exits 1", async () => {
149224 const out = join(tmp(), "b.fab");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs