hullproof 0.0.0-stage → 0.5.0

package/dist/prove/executor.js

@@ -0,0 +1,149 @@
+import { canon, evalAssertion, fill, fillJson, pathGet, SECRET_NAME, sha256 } from './spec.js';
+export const LIMITS = { requestMs: 8000, bodyChars: 16384, textStore: 4096 };
+const HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+// The one place an address is accepted. Anything that is not the sandbox's own loopback is refused before a request is built.
+export function loopbackBase(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error(`refused: ${JSON.stringify(url).slice(0, 80)} is not an address`);
+    }
+    if (u.protocol !== 'http:' || !HOSTS.has(u.hostname) || u.username || u.password || !u.port || u.pathname !== '/' || u.search || u.hash) {
+        throw new Error(`refused: ${u.origin} is not a loopback address of the sandbox (http://127.0.0.1:PORT only)`);
+    }
+    return u;
+}
+const JWT = /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g;
+const LONG = /\b[A-Fa-f0-9]{40,}\b|\b[A-Za-z0-9_]{32,}\b/g;
+export const redactText = (s) => s.replace(JWT, '[redacted]').replace(LONG, '[redacted]');
+export function redactJson(v, key = '') {
+    if (SECRET_NAME.test(key) && v !== null && typeof v !== 'object')
+        return '[redacted]';
+    if (typeof v === 'string')
+        return redactText(v);
+    if (Array.isArray(v))
+        return v.map((x) => redactJson(x, key));
+    if (v && typeof v === 'object')
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, redactJson(x, k)]));
+    return v;
+}
+// What is kept of a response header: a short allow list. No cookie, no authorization, nothing that could hold a credential.
+const KEEP = new Set(['content-type', 'location', 'cache-control', 'www-authenticate', 'access-control-allow-origin', 'x-content-type-options']);
+function judgeStep(spec, s, rec, vars, secrets) {
+    rec.assertions = rec.response ? s.assert.map((a) => evalAssertion(rec.response, a, vars, secrets)) : [];
+}
+// One verdict function for the live run and for a replay. Reads only the stored records.
+export function judge(spec, recs) {
+    const vars = {};
+    const secrets = new Set();
+    const out = [];
+    for (let i = 0; i < recs.length; i++) {
+        const s = spec.steps[i];
+        const rec = recs[i];
+        if (!s || rec.id !== s.id)
+            return { done: true, outcome: 'error', detail: `the stored step ${i + 1} does not match the spec`, recs: out };
+        for (const c of s.captures ?? [])
+            if (SECRET_NAME.test(c.name) || SECRET_NAME.test(c.path ?? ''))
+                secrets.add(c.name);
+        const r = { ...rec, assertions: [...rec.assertions] };
+        judgeStep(spec, s, r, vars, secrets);
+        out.push(r);
+        Object.assign(vars, rec.captures);
+        const failed = r.assertions.find((a) => !a.ok);
+        if (rec.error && !(failed && s.phase !== 'attack'))
+            return { done: true, outcome: 'error', detail: `step ${s.id}: ${rec.error}`, recs: out };
+        if (s.phase === 'setup' && failed)
+            return { done: true, outcome: 'invalid', detail: `setup step ${s.id} did not hold (${failed.desc}), so the harness or the seed is not working`, recs: out };
+        if (s.phase === 'control' && failed)
+            return { done: true, outcome: 'invalid', detail: `positive control failed at step ${s.id} (${failed.desc}), so nothing can be said about the flaw`, recs: out };
+        if (s.phase === 'attack' && failed)
+            return { done: true, outcome: 'not_proven', detail: `the app refused as it should at step ${s.id} (${failed.desc} did not hold)`, recs: out };
+    }
+    if (recs.length === spec.steps.length)
+        return { done: true, outcome: 'proven', detail: 'the positive control passed and every attack assertion held', recs: out };
+    return { done: false, outcome: null, detail: '', recs: out };
+}
+const parseJson = (t) => { try {
+    return JSON.parse(t);
+}
+catch {
+    return undefined;
+} };
+// Runs the steps in order and stops as soon as the verdict is known. Returns the redacted records and the verdict.
+export async function executeSpec(spec, o) {
+    const base = loopbackBase(o.baseUrl);
+    const f = o.fetchFn ?? fetch;
+    const vars = {};
+    const secrets = new Set();
+    const recs = [];
+    for (const s of spec.steps) {
+        for (const c of s.captures ?? [])
+            if (SECRET_NAME.test(c.name) || SECRET_NAME.test(c.path ?? ''))
+                secrets.add(c.name);
+        const rec = { id: s.id, phase: s.phase, actor: s.actor, error: null, request: { method: s.method, path: s.path, headers: {}, body: null }, response: null, captures: {}, assertions: [] };
+        try {
+            const path = fill(s.path, vars, secrets, false);
+            if (!path.startsWith('/') || path.startsWith('//'))
+                throw new Error('the path became something other than a path on the app');
+            // The actor's headers apply once every variable in them has been captured (an actor that is not signed in yet sends none).
+            const headers = {};
+            for (const [k, v] of Object.entries(spec.actors[s.actor]?.headers ?? {})) {
+                try {
+                    headers[k] = fill(v, vars, secrets, false);
+                }
+                catch { /* not signed in yet */ }
+            }
+            for (const [k, v] of Object.entries(s.headers ?? {}))
+                headers[k] = fill(v, vars, secrets, false);
+            const body = s.body ? fillJson(s.body, vars, secrets, false) : null;
+            if (body && !headers['content-type'])
+                headers['content-type'] = 'application/json';
+            rec.request = {
+                method: s.method, path: fill(s.path, vars, secrets, true),
+                headers: Object.fromEntries(Object.entries({ ...(spec.actors[s.actor]?.headers ?? {}), ...(s.headers ?? {}) }).map(([k, v]) => [k, SECRET_NAME.test(k) ? '[redacted]' : v]).sort(([a], [b]) => (a < b ? -1 : 1))),
+                body: s.body ? redactJson(fillJson(s.body, vars, secrets, true)) : null,
+            };
+            const res = await f(new URL(path, base), { method: s.method, headers, body: body ? JSON.stringify(body) : undefined, redirect: 'manual', signal: AbortSignal.timeout(o.requestMs ?? LIMITS.requestMs) });
+            const full = (await res.text()).slice(0, LIMITS.bodyChars + 1);
+            const truncated = full.length > LIMITS.bodyChars;
+            const text = full.slice(0, LIMITS.bodyChars);
+            const rawJson = truncated ? undefined : parseJson(text);
+            const rh = {};
+            res.headers.forEach((v, k) => { if (KEEP.has(k.toLowerCase()))
+                rh[k.toLowerCase()] = redactText(v); });
+            rec.response = {
+                status: res.status, headers: rh, truncated,
+                json: rawJson === undefined ? undefined : redactJson(rawJson),
+                text: rawJson === undefined ? redactText(text).slice(0, LIMITS.textStore) : undefined,
+            };
+            // Captures read the raw response. What is stored is redacted. A capture that finds nothing is an error, but a failed assertion
+            // on the same step is reported first (a failed sign in is an invalid setup, not a broken run).
+            for (const c of s.captures ?? []) {
+                const v = c.from === 'status' ? res.status : c.from === 'header' ? (res.headers.get(c.path) ?? undefined) : pathGet(rawJson, c.path);
+                if (v === undefined || (typeof v === 'object' && v !== null)) {
+                    rec.error ??= `capture ${c.name} found nothing at ${c.from} ${c.path ?? ''}`.trim();
+                    continue;
+                }
+                vars[c.name] = v;
+                rec.captures[c.name] = secrets.has(c.name) ? '[redacted]' : redactJson(v);
+            }
+        }
+        catch (e) {
+            rec.error = e.name === 'TimeoutError' ? 'the request timed out' : e.message.slice(0, 200);
+        }
+        recs.push(rec);
+        const j = judge(spec, recs);
+        recs[recs.length - 1] = j.recs[j.recs.length - 1];
+        if (j.done)
+            return { outcome: j.outcome, detail: j.detail, steps: recs };
+    }
+    const j = judge(spec, recs);
+    return { outcome: j.outcome ?? 'error', detail: j.detail, steps: recs };
+}
+// The record stored for one run. The hash covers every other field.
+export function runRecord(spec, specSha, run, r) {
+    const body = { schema_version: '1.0.0', spec_id: spec.spec_id, spec_sha256: specSha, run, outcome: r.outcome, detail: r.detail, steps: r.steps };
+    return { ...body, transcript_sha256: sha256(canon(body)) };
+}

package/dist/prove/local.js

@@ -0,0 +1,131 @@
+// UNSAFE. A plain local process backend, for the engine's own fixture apps in CI and nothing else. There is no isolation here: the
+// app runs as the current user on the host. For that reason this runner refuses any repository that is not inside a fixture folder of
+// this engine, and the command line never offers it. It is labelled unsafe in its name, in the result file and in the report.
+import { spawn } from 'node:child_process';
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { executeSpec } from './executor.js';
+import { assertSandboxTarget } from './safety.js';
+import { validateSpec } from './spec.js';
+const ENGINE = fileURLToPath(new URL('../../', import.meta.url));
+export const FIXTURE_ROOTS = [join(ENGINE, 'test/fixtures/prove'), join(ENGINE, 'bench/fixtures')];
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const freePort = () => new Promise((res, rej) => { const s = createServer(); s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => res(p)); }); s.on('error', rej); });
+const inside = (p, root) => p === root || p.startsWith(root + sep);
+export class LocalProcessRunner {
+    name = 'local-process-unsafe';
+    roots;
+    constructor(o) {
+        if (o.acknowledgeUnsafe !== true)
+            throw new Error('the local process runner is unsafe and must be created with acknowledgeUnsafe: true');
+        this.roots = (o.fixtureRoots ?? FIXTURE_ROOTS).map((r) => { try {
+            return realpathSync(r);
+        }
+        catch {
+            return r;
+        } });
+    }
+    async available() { return { ok: true }; }
+    async prepare(req) {
+        let src;
+        try {
+            src = realpathSync(req.sourceDir);
+        }
+        catch {
+            return { ok: false, code: 'refused_unsafe_backend', reason: 'the source folder does not exist' };
+        }
+        if (!this.roots.some((r) => inside(src, r)))
+            return { ok: false, code: 'refused_unsafe_backend', reason: 'the local process backend has no isolation, so it only runs the fixture apps of this engine and refuses any other folder' };
+        if (req.recipe.install)
+            return { ok: false, code: 'refused_unsafe_backend', reason: 'the local process backend installs nothing' };
+        if (req.recipe.data_store.kind === 'postgres')
+            return { ok: false, code: 'refused_unsafe_backend', reason: 'the local process backend has no Postgres' };
+        return { ok: true, prepared: new LocalPrepared(req) };
+    }
+}
+class LocalPrepared {
+    req;
+    live = new Set();
+    constructor(req) { this.req = req; }
+    // A free port is chosen first and the app binds it a moment later, so another process can take it in between. Start again on a new
+    // port, twice at most, when the app exits before it answers.
+    async start() {
+        let last = await this.startOnce();
+        for (let i = 0; i < 2 && !last.ok && last.code === 'start_failed' && this.req.recipe.port_from_env; i++)
+            last = await this.startOnce();
+        return last;
+    }
+    async startOnce() {
+        const { recipe, copyDir, limits } = this.req;
+        const data = mkdtempSync(join(tmpdir(), 'hp-local-data-'));
+        const port = recipe.port_from_env ? await freePort() : recipe.port;
+        const env = { PATH: process.env.PATH ?? '', HOME: data, TMPDIR: data };
+        for (const [k, v] of Object.entries(recipe.env))
+            env[k] = v.replace(/\{DATA\}/g, data);
+        if (recipe.port_from_env)
+            env.PORT = String(port);
+        let log = '';
+        const child = spawn('sh', ['-c', `${recipe.seed ? recipe.seed + ' && ' : ''}exec ${recipe.start}`], { cwd: copyDir, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        child.stdout.on('data', (d) => { log = (log + d.toString()).slice(-2000); });
+        child.stderr.on('data', (d) => { log = (log + d.toString()).slice(-2000); });
+        let exited = false;
+        child.on('exit', () => { exited = true; });
+        const inst = new LocalInstance(child, data, port);
+        this.live.add(inst);
+        const deadline = Date.now() + limits.healthMs;
+        while (Date.now() < deadline && !exited) {
+            try {
+                const r = await fetch(`http://127.0.0.1:${port}${recipe.health_path}`, { signal: AbortSignal.timeout(1500) });
+                if (r.status < 500)
+                    return { ok: true, instance: inst };
+            }
+            catch { /* not up yet */ }
+            await sleep(100);
+        }
+        await inst.stop();
+        return { ok: false, code: exited ? 'start_failed' : 'health_failed', reason: `${exited ? 'the app exited before it answered' : 'the app did not answer in time'}: ${log.trim().replace(/\s+/g, ' ').slice(-300)}` };
+    }
+    async dispose() { for (const i of this.live)
+        await i.stop(); return { left_behind: [...this.live].flatMap((i) => i.alive() ? [`process ${i.pid}`] : []) }; }
+}
+class LocalInstance {
+    baseUrl;
+    pid;
+    child;
+    data;
+    port;
+    constructor(child, data, port) { this.child = child; this.data = data; this.port = port; this.pid = child.pid ?? 0; this.baseUrl = `http://127.0.0.1:${port}`; }
+    alive() { try {
+        process.kill(this.pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    } }
+    async exec() { return { code: null, stdout: '', stderr: 'the local process backend does not run commands', timedOut: false }; }
+    async runSpec(spec) {
+        const v = validateSpec(spec);
+        if (!v.ok)
+            return { ok: false, reason: `invalid spec: ${v.errors.join('; ')}` };
+        try {
+            assertSandboxTarget(this.baseUrl, this.port);
+            return { ok: true, ...(await executeSpec(v.spec, { baseUrl: this.baseUrl })) };
+        }
+        catch (e) {
+            return { ok: false, reason: e.message };
+        }
+    }
+    async stop() {
+        try {
+            process.kill(-this.pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        for (let i = 0; i < 20 && this.alive(); i++)
+            await sleep(25);
+        rmSync(this.data, { recursive: true, force: true });
+        return { left_behind: this.alive() ? [`process ${this.pid}`] : [] };
+    }
+}

package/dist/prove/probes.js

@@ -0,0 +1,65 @@
+// Escape attempts. Each probe is a short script run inside a started sandbox instance with the same limits as the app. The sandbox
+// has held when every probe reports ok. They are the exit test of step 4a and `hullproof prove --self-test` runs them on demand.
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const NET = `
+const net=require('net'),dns=require('dns');
+const conn=(h,p)=>new Promise(r=>{const s=net.connect({host:h,port:p,timeout:3000});s.on('connect',()=>{s.destroy();r(true)});s.on('error',()=>r(false));s.on('timeout',()=>{s.destroy();r(false)})});
+(async()=>{const o={};o.tcp_cloudflare=await conn('1.1.1.1',443);o.tcp_google=await conn('8.8.8.8',53);o.dns=await new Promise(r=>dns.lookup('example.com',e=>r(!e)));
+o.fetch=await fetch('http://example.com',{signal:AbortSignal.timeout(3000)}).then(()=>true,()=>false);console.log(JSON.stringify(o));})()`;
+const FILES = `
+const fs=require('fs');const out={};
+for(const p of [process.argv[1],'/Users','/host','/mnt/host','/var/run/docker.sock','/run/docker.sock','/root/.ssh']){try{fs.readFileSync(p);out[p]='READ';}catch(e){try{const l=fs.readdirSync(p);out[p]='LISTED:'+l.length;}catch(e2){out[p]=e2.code;}}}
+console.log(JSON.stringify(out))`;
+const WRITES = `
+const fs=require('fs');const out={};
+for(const p of ['/app/hp_probe','/etc/hp_probe','/usr/hp_probe','/hp_probe','/tmp/hp_probe']){try{fs.writeFileSync(p,'x');out[p]='WROTE';}catch(e){out[p]=e.code;}}
+out.uid=process.getuid();console.log(JSON.stringify(out))`;
+const FORK = `
+const {spawn}=require('child_process'),fs=require('fs');let refused=0,peak=0;const kids=[];
+const rd=(f)=>{try{return fs.readFileSync(f,'utf8').trim()}catch{return null}};
+const cur=()=>Number(rd('/sys/fs/cgroup/pids.current')||rd('/sys/fs/cgroup/pids/pids.current')||0);
+const max=rd('/sys/fs/cgroup/pids.max')||rd('/sys/fs/cgroup/pids/pids.max');
+const go=async()=>{for(let i=0;i<400;i++){const k=spawn(process.execPath,['-e','setTimeout(()=>{},60000)'],{stdio:'ignore'});k.on('error',()=>refused++);kids.push(k);peak=Math.max(peak,cur());await new Promise(r=>setTimeout(r,8));}
+await new Promise(r=>setTimeout(r,800));console.log(JSON.stringify({attempted:400,refused,peak_processes:peak,limit:max}));kids.forEach(k=>{try{k.kill('SIGKILL')}catch{}});process.exit(0);};go()`;
+const MEM = `const a=[];try{for(let i=0;i<64;i++)a.push(Buffer.alloc(64*1024*1024,1));console.log('ALLOCATED');}catch(e){console.log('REFUSED');}`;
+const j = (s) => { try {
+    return JSON.parse(s.trim().split('\n').pop() ?? '{}');
+}
+catch {
+    return {};
+} };
+export async function runEscapeProbes(inst, hostMarker) {
+    const out = [];
+    const net = j((await inst.exec(['node', '-e', NET], { timeoutMs: 30_000 })).stdout);
+    out.push({ name: 'network call to the internet', ok: Object.keys(net).length === 4 && Object.values(net).every((v) => v === false), detail: JSON.stringify(net) });
+    const files = j((await inst.exec(['node', '-e', FILES, hostMarker], { timeoutMs: 15_000 })).stdout);
+    out.push({ name: 'host file read', ok: Object.keys(files).length > 0 && Object.values(files).every((v) => v === 'ENOENT' || v === 'EACCES'), detail: JSON.stringify(files) });
+    const w = j((await inst.exec(['node', '-e', WRITES], { timeoutMs: 15_000 })).stdout);
+    const ro = ['/app/hp_probe', '/etc/hp_probe', '/usr/hp_probe', '/hp_probe'].every((p) => w[p] === 'EROFS' || w[p] === 'EACCES');
+    out.push({ name: 'write to the root filesystem, and run as root', ok: ro && typeof w.uid === 'number' && w.uid !== 0, detail: JSON.stringify(w) });
+    const fork = j((await inst.exec(['node', '-e', FORK], { timeoutMs: 40_000 })).stdout);
+    const alive = (await inst.exec(['node', '-e', 'console.log(1)'], { timeoutMs: 15_000 })).code === 0;
+    out.push({ name: 'fork bomb', ok: typeof fork.peak_processes === 'number' && fork.peak_processes > 0 && fork.peak_processes <= Number(fork.limit) && alive, detail: `${JSON.stringify(fork)}; sandbox still answers: ${alive}` });
+    const t0 = Date.now();
+    const loop = await inst.exec(['node', '-e', 'while(true){}'], { timeoutMs: 3000 });
+    const after = (await inst.exec(['node', '-e', 'console.log(1)'], { timeoutMs: 15_000 })).code === 0;
+    out.push({ name: 'long loop', ok: (loop.timedOut || loop.code === 137) && Date.now() - t0 < 30_000 && after, detail: `ended after ${Date.now() - t0} ms with code ${loop.code}; sandbox still answers: ${after}` });
+    const mem = await inst.exec(['node', '-e', MEM], { timeoutMs: 30_000 });
+    out.push({ name: 'memory limit', ok: !mem.stdout.includes('ALLOCATED') && (await inst.exec(['node', '-e', 'console.log(1)'], { timeoutMs: 15_000 })).code === 0, detail: `exit code ${mem.code}` });
+    return out;
+}
+// A small app and a recipe for `hullproof prove --self-test`: it needs nothing installed and reads nothing from the user's repository.
+export function selfTestApp() {
+    const dir = mkdtempSync(join(tmpdir(), 'hp-selftest-'));
+    const outside = mkdtempSync(join(tmpdir(), 'hp-marker-'));
+    const marker = join(outside, `secret-${randomBytes(4).toString('hex')}.txt`);
+    writeFileSync(marker, 'HOST-SECRET-MARKER');
+    mkdirSync(join(dir, 'app'), { recursive: true });
+    writeFileSync(join(dir, 'server.js'), "require('http').createServer((q,s)=>{s.setHeader('content-type','application/json');s.end(JSON.stringify({ok:true}))}).listen(3000);\n");
+    writeFileSync(join(dir, 'package.json'), '{"name":"hp-selftest","version":"0.0.0","main":"server.js"}\n');
+    const recipe = { schema_version: '1.0.0', stack: 'node-express', base_image: 'node:22-slim', install: null, vendored_modules: false, seed: null, start: 'node server.js', port: 3000, port_from_env: false, health_path: '/', data_store: { kind: 'none' }, env: {}, notes: [] };
+    return { dir, recipe, marker, cleanup: () => { rmSync(dir, { recursive: true, force: true }); rmSync(outside, { recursive: true, force: true }); } };
+}

package/dist/prove/recipe.js

@@ -0,0 +1,278 @@
+// Start recipes: how to build and start an app in the sandbox, read from stack.json and the code map and from the repository itself.
+// Two recipes: a Node app on Express with a local SQLite file or an ephemeral Postgres, and (Phase 6d) a Python app on Flask with a
+// local SQLite file. Anything else, or anything that needs a hosted service, comes back as "not provable here" with the reason. A
+// recipe is never guessed.
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmp } from '../util.js';
+import { dummyValue, envNames } from './safety.js';
+import { canon, sha256 } from './spec.js';
+export const BASE_IMAGE = 'node:22-slim';
+export const PYTHON_IMAGE = 'python:3.12-slim';
+const HOSTED_DATA = new Set(['supabase', 'firebase-realtime-database', 'firestore', 'dynamodb', 'azure-cosmos-db', 'neon', 'planetscale', 'turso', 'aws-rds', 'google-cloud-sql', 'azure-database-mysql', 'azure-database-postgres', 'azure-sql']);
+const HOSTED_AUTH = new Set(['auth0', 'clerk', 'firebase-auth', 'supabase-auth', 'aws-cognito', 'kinde', 'workos', 'stytch', 'okta', 'microsoft-entra']);
+const LOCAL_DATA = new Set(['sqlite', 'postgres']);
+const NATIVE = ['better-sqlite3', 'sqlite3', 'bcrypt', 'sharp', 'canvas', 'argon2', 'node-sass', 'grpc', 'libsql'];
+const DB_VARS = /^(?:DATABASE_URL|DB_PATH|DATABASE_PATH|SQLITE_PATH|SQLITE_FILE|DB_FILE|DATABASE_FILE)$/;
+const HEALTH = ['/health', '/healthz', '/api/health', '/ping', '/status', '/'];
+const nice = (id) => id.replace(/-/g, ' ');
+const no = (code, reason) => ({ ok: false, code, reason });
+const ids = (xs) => xs.map((x) => x.id);
+function sourceFiles(repo, depth = 0, out = []) {
+    if (depth > 6)
+        return out;
+    for (const n of readdirSync(repo).sort(cmp)) {
+        if (n === 'node_modules' || n === '.git' || n === '.hullproof')
+            continue;
+        const p = join(repo, n);
+        const st = lstatSync(p);
+        if (st.isSymbolicLink())
+            continue;
+        if (st.isDirectory())
+            sourceFiles(p, depth + 1, out);
+        else if (/\.(?:[cm]?js|ts)$/.test(n) && st.size < 1_000_000)
+            out.push(p);
+    }
+    return out;
+}
+// The port the app listens on: a number in listen(), or the number after process.env.PORT. Returns null when no listen() call is found.
+export function detectPort(text) {
+    const m = /\.listen\(\s*([^,)\n]+)/.exec(text);
+    if (!m)
+        return null;
+    let expr = m[1].trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(expr)) {
+        const d = new RegExp(`(?:const|let|var)\\s+${expr}\\s*=\\s*([^;\\n]+)`).exec(text);
+        if (d)
+            expr = d[1];
+    }
+    const fromEnv = /process\.env\.PORT|process\.env\[\s*['"]PORT['"]\s*\]/.test(expr);
+    const n = /\b(\d{2,5})\b/.exec(expr.replace(/process\.env\.PORT/g, ''));
+    if (n && Number(n[1]) <= 65535)
+        return { port: Number(n[1]), fromEnv };
+    return fromEnv ? { port: 3000, fromEnv } : null;
+}
+export function deriveRecipe(repo, stack, map, opts = {}) {
+    const hosted = [...stack.data_stores.filter((i) => HOSTED_DATA.has(i.id)), ...stack.auth.filter((i) => HOSTED_AUTH.has(i.id))];
+    if (hosted.length)
+        return no('hosted_service', `the app uses ${hosted.map((i) => nice(i.id)).join(' and ')}, a hosted service that cannot run locally and has no local stand in in this version. It is not faked.`);
+    const otherData = stack.data_stores.filter((i) => !LOCAL_DATA.has(i.id));
+    if (otherData.length)
+        return no('unsupported_datastore', `the app uses ${otherData.map((i) => nice(i.id)).join(' and ')}. Only a local SQLite file and an ephemeral Postgres are supported.`);
+    const fw = ids(stack.frameworks);
+    if (!fw.includes('express') && fw.includes('flask'))
+        return deriveFlask(repo, stack, map, opts);
+    if (!fw.includes('express'))
+        return no('unsupported_stack', `the proof sandbox has a recipe for Node on Express and for Python on Flask in this version${fw.length ? ` (found ${fw.slice(0, 4).join(', ')})` : ''}.`);
+    if (fw.includes('nextjs'))
+        return no('unsupported_stack', 'the app also uses Next.js, which needs a production build step that this version has no recipe for.');
+    const pjPath = join(repo, 'package.json');
+    if (!existsSync(pjPath))
+        return no('no_package_json', 'there is no package.json at the repository root.');
+    let pj;
+    try {
+        pj = JSON.parse(readFileSync(pjPath, 'utf8'));
+    }
+    catch {
+        return no('no_package_json', 'package.json cannot be read as JSON.');
+    }
+    const deps = { ...(pj.dependencies ?? {}), ...(pj.devDependencies ?? {}) };
+    const notes = [];
+    // Build phase: a lockfile install without install scripts, or nothing at all when the repository carries its own modules.
+    const hasDeps = Object.keys(deps).length > 0;
+    const native = NATIVE.filter((n) => n in deps);
+    let install = null;
+    let vendored = false;
+    if (hasDeps) {
+        if (native.length && !opts.allowInstallScripts)
+            return no('needs_install_scripts', `${native.join(', ')} needs an install script to build or download a native part, and the sandbox installs without install scripts so none can run. Pass --allow-install-scripts to let them run in the build container.`);
+        if (!existsSync(join(repo, 'package-lock.json')))
+            return no('no_lockfile', `there is no package-lock.json${existsSync(join(repo, 'yarn.lock')) || existsSync(join(repo, 'pnpm-lock.yaml')) ? ' (only npm lockfiles are installed in this version)' : ''}, and the sandbox installs from a lockfile only.`);
+        install = ['npm', 'ci', ...(opts.allowInstallScripts ? [] : ['--ignore-scripts']), '--no-audit', '--no-fund', '--registry=https://registry.npmjs.org/'];
+        if (opts.allowInstallScripts)
+            notes.push('install scripts run inside the build container, which has network access to the package registry');
+    }
+    else if (existsSync(join(repo, 'node_modules'))) {
+        vendored = true;
+        notes.push('the repository carries its own node_modules and has no dependencies to install, so the build phase needs no network');
+    }
+    const start = pj.scripts?.start ? 'npm start' : pj.main && existsSync(join(repo, pj.main)) ? `node ${pj.main}` : ['server.js', 'index.js', 'app.js', 'src/server.js', 'src/index.js'].find((f) => existsSync(join(repo, f))) ? `node ${['server.js', 'index.js', 'app.js', 'src/server.js', 'src/index.js'].find((f) => existsSync(join(repo, f)))}` : null;
+    if (!start)
+        return no('no_start_command', 'there is no start script, no main file and no server.js, index.js or app.js.');
+    let port = null;
+    for (const f of sourceFiles(repo)) {
+        port = detectPort(readFileSync(f, 'utf8'));
+        if (port)
+            break;
+    }
+    if (!port)
+        return no('port_unknown', 'no listen() call with a port was found in the source.');
+    const names = envNames(repo);
+    const env = {};
+    if (port.fromEnv)
+        env.PORT = String(port.port);
+    const sqliteUsed = stack.data_stores.some((i) => i.id === 'sqlite') || sourceFiles(repo).some((f) => /node:sqlite|better-sqlite3|require\(['"]sqlite3['"]\)/.test(readFileSync(f, 'utf8')));
+    const pgUsed = stack.data_stores.some((i) => i.id === 'postgres');
+    let data = { kind: 'none' };
+    if (pgUsed && !sqliteUsed) {
+        const url = names.find((n) => n === 'DATABASE_URL' || n === 'POSTGRES_URL');
+        if (!url)
+            return no('unsupported_datastore', 'the app uses Postgres but does not read DATABASE_URL or POSTGRES_URL, so the sandbox cannot point it at its own database.');
+        const sqlIn = (d) => (existsSync(join(repo, d)) ? readdirSync(join(repo, d)).filter((f) => f.endsWith('.sql')).sort(cmp).map((f) => `${d}/${f}`) : []);
+        const migrations = [...sqlIn('migrations'), ...sqlIn('db/migrations')];
+        const seedSql = ['seed.sql', 'db/seed.sql'].find((f) => existsSync(join(repo, f))) ?? null;
+        if (!migrations.length && !seedSql)
+            return no('no_seed', 'the app uses Postgres and the repository has no migrations folder or seed.sql to build the schema and data from.');
+        data = { kind: 'postgres', migrations, seed_sql: seedSql };
+        env[url] = '{PGURL}';
+        notes.push('Postgres runs as a second container on an internal network with no route out');
+    }
+    else if (sqliteUsed) {
+        const dbVars = names.filter((n) => DB_VARS.test(n));
+        if (!dbVars.length)
+            return no('db_path_hardcoded', 'the app uses SQLite but does not read its file path from an environment variable (DATABASE_URL, DB_PATH, SQLITE_PATH and similar). The sandbox root filesystem is read only, so a path written into the code cannot be redirected to a writable place.');
+        for (const v of dbVars)
+            env[v] = v.endsWith('_URL') ? 'file:{DATA}/app.db' : '{DATA}/app.db';
+        data = { kind: 'sqlite', env: dbVars };
+    }
+    for (const n of names)
+        if (!(n in env) && n !== 'PORT')
+            env[n] = dummyValue(n);
+    let seed = null;
+    if (pj.scripts?.seed)
+        seed = 'npm run seed';
+    else {
+        const f = ['seed.js', 'db/seed.js', 'scripts/seed.js', 'seed.mjs'].find((x) => existsSync(join(repo, x)));
+        if (f)
+            seed = `node ${f}`;
+        else
+            notes.push('no seed step found; the specs rely on data the app creates itself');
+    }
+    const gets = new Set(map.entry_points.filter((e) => e.kind === 'http_route' && e.method === 'GET' && e.path).map((e) => e.path));
+    const health = HEALTH.find((h) => gets.has(h)) ?? '/';
+    if (health === '/' && !gets.has('/'))
+        notes.push('no health route found; the app counts as up when it answers any request with a status below 500');
+    return { ok: true, recipe: { schema_version: '1.0.0', stack: 'node-express', base_image: BASE_IMAGE, ...(opts.allowInstallScripts && install ? { install_scripts: true } : {}), install, vendored_modules: vendored, seed, start, port: port.port, port_from_env: port.fromEnv, health_path: health, data_store: data, env: Object.fromEntries(Object.entries(env).sort(([a], [b]) => cmp(a, b))), notes } };
+}
+// ---- Python on Flask (Phase 6d) ---------------------------------------------------------------------------------------------------------
+function pyFiles(repo, depth = 0, out = []) {
+    if (depth > 6)
+        return out;
+    for (const n of readdirSync(repo).sort(cmp)) {
+        if (['node_modules', '.git', '.hullproof', '__pycache__', '.venv', 'venv'].includes(n))
+            continue;
+        const p = join(repo, n);
+        const st = lstatSync(p);
+        if (st.isSymbolicLink())
+            continue;
+        if (st.isDirectory())
+            pyFiles(p, depth + 1, out);
+        else if (n.endsWith('.py') && st.size < 1_000_000)
+            out.push(p);
+    }
+    return out;
+}
+// The port a Flask app listens on: app.run(port=...) with a number, or int(os.environ.get("PORT", "5000")). The flask command defaults to 5000.
+export function detectPyPort(text) {
+    const run = /\.run\s*\(/.exec(text);
+    if (!run)
+        return null;
+    // The text of the argument list, up to the bracket that closes it.
+    let depth = 1;
+    let i = run.index + run[0].length;
+    const from = i;
+    for (; i < text.length && depth > 0; i++) {
+        if (text[i] === '(')
+            depth++;
+        else if (text[i] === ')')
+            depth--;
+    }
+    const args = text.slice(from, i - 1);
+    const at = /\bport\s*=\s*/.exec(args);
+    if (!at)
+        return { port: 5000, fromEnv: false };
+    let d = 0;
+    let k = at.index + at[0].length;
+    const start = k;
+    for (; k < args.length; k++) {
+        if (args[k] === '(')
+            d++;
+        else if (args[k] === ')')
+            d--;
+        else if (args[k] === ',' && d === 0)
+            break;
+    }
+    const expr = args.slice(start, k);
+    const fromEnv = /os\.environ|getenv/.test(expr) && /PORT/.test(expr);
+    const n = /(\d{2,5})/.exec(expr.replace(/PORT/g, ''));
+    if (n && Number(n[1]) <= 65535)
+        return { port: Number(n[1]), fromEnv };
+    return fromEnv ? { port: 5000, fromEnv } : null;
+}
+function deriveFlask(repo, stack, map, opts) {
+    const files = pyFiles(repo);
+    const text = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
+    const notes = [];
+    const reqPath = join(repo, 'requirements.txt');
+    if (!existsSync(reqPath))
+        return no('no_lockfile', 'there is no requirements.txt, and the sandbox installs from pinned requirements only (Pipfile, Poetry and uv are not read in this version).');
+    const lines = readFileSync(reqPath, 'utf8').split(/\r?\n/).map((l) => l.replace(/\s+#.*$/, '').trim()).filter((l) => l && !l.startsWith('#'));
+    const loose = lines.filter((l) => !/^[A-Za-z0-9_.\[\]-]+\s*==\s*[\w.!+*-]+(?:\s*;.*)?(?:\s+--hash=.*)?$/.test(l) && !/^--hash=/.test(l));
+    if (loose.length)
+        return no('no_lockfile', `requirements.txt has lines that are not pinned with == (${loose.slice(0, 3).join(', ')}), and the sandbox installs from pinned requirements only.`);
+    if (lines.some((l) => /^(?:-e|git\+|https?:|\.\/|\/|--(?:index-url|extra-index-url|find-links))/.test(l)))
+        return no('no_lockfile', 'requirements.txt points at a source other than the package index, and the sandbox installs from the index only.');
+    const sqlite = stack.data_stores.some((i) => i.id === 'sqlite') || [...text.values()].some((t) => /\bimport\s+(?:[\w.]+\s*,\s*)*sqlite3\b|\bfrom\s+sqlite3\b/.test(t));
+    const otherDb = lines.some((l) => /^(?:psycopg2?|psycopg|pymysql|mysqlclient|pymongo|redis|sqlalchemy|django)\b/i.test(l));
+    if (otherDb && !sqlite)
+        return no('unsupported_datastore', 'the app uses a database package other than the built in sqlite3. Only a local SQLite file is supported for Python in this version.');
+    const names = envNames(repo);
+    const dbVars = names.filter((n) => DB_VARS.test(n));
+    if (sqlite && !dbVars.length)
+        return no('db_path_hardcoded', 'the app uses SQLite but does not read its file path from an environment variable (DATABASE_URL, DB_PATH, SQLITE_PATH and similar). The sandbox root filesystem is read only, so a path written into the code cannot be redirected to a writable place.');
+    if (!sqlite)
+        notes.push('no data store was found; the app starts with no database');
+    const appFile = files.find((f) => /\bFlask\s*\(\s*__name__/.test(text.get(f)));
+    if (!appFile)
+        return no('no_start_command', 'no file creates the app with Flask(__name__).');
+    const rel = (f) => f.slice(repo.length + 1);
+    const runner = files.find((f) => /if\s+__name__\s*==\s*['"]__main__['"]/.test(text.get(f)) && /\.run\s*\(/.test(text.get(f)) && (f === appFile || /from\s+\w+\s+import|import\s+\w+/.test(text.get(f))));
+    let start;
+    let port;
+    if (runner) {
+        const pt = detectPyPort(text.get(runner));
+        if (!pt)
+            return no('port_unknown', 'app.run() is called but its port could not be read.');
+        port = pt;
+        start = `python ${rel(runner)}`;
+    }
+    else {
+        const mod = rel(appFile).replace(/\.py$/, '').replace(/\//g, '.');
+        port = { port: 5000, fromEnv: false };
+        start = `python -m flask --app ${mod} run --host 127.0.0.1 --port 5000`;
+        notes.push('the app has no app.run() under __main__, so it starts with the flask command on port 5000');
+    }
+    const env = {};
+    if (port.fromEnv)
+        env.PORT = String(port.port);
+    for (const v of dbVars)
+        env[v] = v.endsWith('_URL') ? 'file:{DATA}/app.db' : '{DATA}/app.db';
+    for (const n of names)
+        if (!(n in env) && n !== 'PORT')
+            env[n] = dummyValue(n);
+    const seedFile = ['seed.py', 'db/seed.py', 'scripts/seed.py', 'init_db.py', 'db/init_db.py'].find((x) => existsSync(join(repo, x)));
+    if (!seedFile)
+        notes.push('no seed step found; the specs rely on data the app creates itself');
+    const gets = new Set(map.entry_points.filter((e) => e.kind === 'http_route' && e.method === 'GET' && e.path).map((e) => e.path));
+    const health = HEALTH.find((h) => gets.has(h)) ?? '/';
+    if (health === '/' && !gets.has('/'))
+        notes.push('no health route found; the app counts as up when it answers any request with a status below 500');
+    const install = ['pip', 'install', '--no-cache-dir', ...(opts.allowInstallScripts ? [] : ['--only-binary=:all:']), '--disable-pip-version-check', '-r', 'requirements.txt'];
+    if (opts.allowInstallScripts)
+        notes.push('a package with no wheel builds from source inside the build container, which has network access to the package index');
+    else
+        notes.push('packages install from wheels only, so no package build script runs; a package that has no wheel makes the app not provable here');
+    notes.push('requirements are pinned by version; the sandbox does not check package hashes');
+    return { ok: true, recipe: { schema_version: '1.0.0', stack: 'python-flask', base_image: PYTHON_IMAGE, ...(opts.allowInstallScripts ? { install_scripts: true } : {}), install, vendored_modules: false, seed: seedFile ? `python ${seedFile}` : null, start, port: port.port, port_from_env: port.fromEnv, health_path: health, data_store: sqlite ? { kind: 'sqlite', env: dbVars } : { kind: 'none' }, env: Object.fromEntries(Object.entries(env).sort(([a], [b]) => cmp(a, b))), notes } };
+}
+export const recipeSha256 = (r) => sha256(canon(r));