Public: anyone can read this; the crew can change it.
An app backup never follows a symlink swapped in after the walk #14929
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14899-an-app-backup-never-follows-a-symlink-sw → main 2 commits fork
2 files
changed +201
−29
src/apps/backup.ts +125 −28
| @@ -24,6 +24,7 @@ import { | ||
| 24 | 24 | } from "node:crypto"; |
| 25 | 25 | import { |
| 26 | 26 | closeSync, |
| 27 | constants, | |
| 27 | 28 | existsSync, |
| 28 | 29 | fstatSync, |
| 29 | 30 | fsyncSync, |
| @@ -32,6 +33,7 @@ import { | ||
| 32 | 33 | mkdtempSync, |
| 33 | 34 | openSync, |
| 34 | 35 | readdirSync, |
| 36 | readlinkSync, | |
| 35 | 37 | readSync, |
| 36 | 38 | realpathSync, |
| 37 | 39 | renameSync, |
| @@ -70,15 +72,23 @@ export interface Proof { | ||
| 70 | 72 | |
| 71 | 73 | const CHUNK = 1 << 18; |
| 72 | 74 | |
| 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 | ||
| 73 | 87 | /** Size and SHA-256 of a file, read a chunk at a time: the file is never whole in memory. */ |
| 74 | 88 | export function hashFile(path: string): { size: number; sha256: string } { |
| 75 | 89 | const fd = openSync(path, "r"); |
| 76 | 90 | 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); | |
| 82 | 92 | } finally { |
| 83 | 93 | closeSync(fd); |
| 84 | 94 | } |
| @@ -122,15 +132,66 @@ export function passphraseProblem(p: string | undefined): string | undefined { | ||
| 122 | 132 | return undefined; |
| 123 | 133 | } |
| 124 | 134 | |
| 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[] } { | |
| 126 | 143 | for (const e of readdirSync(join(root, rel), { withFileTypes: true })) { |
| 127 | 144 | const r = rel === "" ? e.name : `${rel}/${e.name}`; |
| 128 | 145 | if (e.isDirectory()) walk(root, r, out, skipped); |
| 129 | 146 | 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); | |
| 132 | 158 | } |
| 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 }; | |
| 134 | 195 | } |
| 135 | 196 | |
| 136 | 197 | const isSqlite = (bytes: Uint8Array): boolean => |
| @@ -160,16 +221,30 @@ export function tableCounts(path: string): Record<string, number> | undefined { | ||
| 160 | 221 | const headerFor = (salt: Buffer, iv: Buffer): Buffer => |
| 161 | 222 | Buffer.from(`${JSON.stringify({ v: 1, kdf: "scrypt", salt: salt.toString("base64url"), iv: iv.toString("base64url") })}\n`); |
| 162 | 223 | |
| 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 => { | |
| 165 | 234 | 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; | |
| 170 | 239 | } |
| 171 | 240 | }; |
| 172 | 241 | |
| 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 | ||
| 173 | 248 | /** |
| 174 | 249 | * Seal a data directory into `out`, written as it is built: each file is |
| 175 | 250 | * hashed for the manifest, then streamed a chunk at a time through the cipher |
| @@ -178,7 +253,7 @@ const startsSqlite = (path: string): boolean => { | ||
| 178 | 253 | * proof calls it out. `out` is written as given; `sealAndProve` names it |
| 179 | 254 | * `.part` and renames it only on PROVEN. Throws a message for unusable input. |
| 180 | 255 | */ |
| 181 | export function sealToFile(dir: string, out: string, passphrase: string): Manifest { | |
| 256 | export function sealToFile(dir: string, out: string, passphrase: string, hooks: SealHooks = {}): Manifest { | |
| 182 | 257 | const bad = passphraseProblem(passphrase); |
| 183 | 258 | if (bad !== undefined) throw new Error(bad); |
| 184 | 259 | 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 | ||
| 189 | 264 | const snapshot = join(dirname(resolve(out)), `.${basename(out)}.${randomBytes(6).toString("hex")}.snapshot`); |
| 190 | 265 | try { |
| 191 | 266 | cloneDir(dir, snapshot); |
| 192 | return sealSnapshot(snapshot, out, passphrase); | |
| 267 | return sealSnapshot(snapshot, out, passphrase, hooks); | |
| 193 | 268 | } finally { |
| 194 | 269 | rmSync(snapshot, { recursive: true, force: true }); |
| 195 | 270 | } |
| 196 | 271 | } |
| 197 | 272 | |
| 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)); | |
| 200 | 282 | 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); | |
| 207 | 300 | } |
| 208 | 301 | } |
| 302 | manifest.skipped!.sort(); | |
| 209 | 303 | const salt = randomBytes(16); |
| 210 | 304 | const iv = randomBytes(12); |
| 211 | 305 | const header = headerFor(salt, iv); |
| @@ -222,8 +316,11 @@ function sealSnapshot(dir: string, out: string, passphrase: string): Manifest { | ||
| 222 | 316 | len.writeUInt32BE(m.length); |
| 223 | 317 | put(cipher.update(Buffer.concat([len, m]))); |
| 224 | 318 | 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; | |
| 227 | 324 | try { |
| 228 | 325 | let left = f.size; |
| 229 | 326 | while (left > 0) { |
| @@ -415,7 +512,7 @@ export function sourceDrift(dir: string, manifest: Manifest): string[] { | ||
| 415 | 512 | const problems: string[] = []; |
| 416 | 513 | const now = walk(dir); |
| 417 | 514 | 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`); | |
| 419 | 516 | for (const f of manifest.files) { |
| 420 | 517 | // A database is sealed as a checkpointed, checked snapshot: its bytes |
| 421 | 518 | // differ from the live file and its log by design, not by drift. |
test/app-backup.test.ts +76 −1
| @@ -1,7 +1,7 @@ | ||
| 1 | 1 | import { Database } from "bun:sqlite"; |
| 2 | 2 | import { describe, expect, test } from "bun:test"; |
| 3 | 3 | 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"; | |
| 5 | 5 | import { tmpdir } from "node:os"; |
| 6 | 6 | import { join } from "node:path"; |
| 7 | 7 | 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", () => { | ||
| 144 | 144 | }); |
| 145 | 145 | }); |
| 146 | 146 | |
| 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 | ||
| 147 | 222 | describe("scripts/app-backup.ts", () => { |
| 148 | 223 | test("prove restores a sealed file and exits 0; a wrong passphrase exits 1", async () => { |
| 149 | 224 | const out = join(tmp(), "b.fab"); |
new above
offline