Commita909c89dRecorded19 Oct 2026Repositorysigil-http3

Supervise the configured VPN phone window with verified echo inputs

Changed
 scripts/echo-lifecycle.mjs       |   6 +++++-
 scripts/phantom-vpn-phone-run.sh |   7 +++++++
 scripts/vpn-phone-run.mjs        | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 test/test-echo-lifecycle.mjs     |  17 ++++++++++++++++-
 4 files changed, 184 insertions(+), 2 deletions(-)
Diff
scripts/echo-lifecycle.mjsmodified
@@ -126,7 +126,7 @@ export function stopRun(directory) {
126
return { stopRequested: signalIdentity(state.supervisor, 'SIGTERM') };
127
}
128
−129
export async function runTest(configPath) {
+129
export async function runTest(configPath, { signal } = {}) {
130
const plan = inspectPlan(configPath);
131
check(plan.ready, plan.blockers.join('; '));
132
const { config } = plan;
@@ -147,8 +147,11 @@ export async function runTest(configPath) {
147
const streams = [];
148
const terminate = () => { reason ??= 'SIGTERM'; };
149
const interrupt = () => { reason ??= 'SIGINT'; };
+150
const cancel = () => { reason ??= 'parent-stop'; };
151
process.on('SIGTERM', terminate);
152
process.on('SIGINT', interrupt);
+153
signal?.addEventListener('abort', cancel, { once: true });
+154
if (signal?.aborted) cancel();
155
const timer = setTimeout(() => { reason ??= 'lifetime'; }, config.lifetimeSeconds * 1000);
156
try {
157
writeState(config.runDirectory, state);
@@ -216,6 +219,7 @@ export async function runTest(configPath) {
219
} catch (error) { failure ??= error; }
220
process.off('SIGTERM', terminate);
221
process.off('SIGINT', interrupt);
+222
signal?.removeEventListener('abort', cancel);
223
for (const stream of streams) { stream.removeAllListeners('data'); stream.destroy(); }
224
for (const file of files) closeSync(file);
225
Object.assign(state, { phase: 'finished', endedAt: new Date().toISOString(),
scripts/phantom-vpn-phone-run.shadded
@@ -0,0 +1,7 @@
+1
#!/usr/bin/env bash
+2
set -euo pipefail
+3
cd "$(dirname "$0")/.."
+4
# Validate the new parent-cancellation path before opening the VPN window.
+5
node --check scripts/vpn-phone-run.mjs
+6
bash scripts/phantom-lifecycle-check.sh
+7
exec node scripts/vpn-phone-run.mjs run
scripts/vpn-phone-run.mjsadded
@@ -0,0 +1,156 @@
+1
// operator-configured VPN window. No public binds, firewall changes or publishing.
+2
import { createHash } from 'node:crypto';
+3
import { createSocket } from 'node:dgram';
+4
import { copyFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+5
import { createServer } from 'node:net';
+6
import { hostname } from 'node:os';
+7
import { resolve, join } from 'node:path';
+8
import { identity, inspectPlan, runTest, stopRun } from './echo-lifecycle.mjs';
+9
import { startPhonePage } from './phone-page-host.mjs';
+10
+11
const pause = ms => new Promise(done => setTimeout(done, ms));
+12
const digest = path => createHash('sha256').update(readFileSync(path)).digest('hex');
+13
function check(value, message) { if (!value) throw new Error(message); }
+14
function json(path) { return JSON.parse(readFileSync(path, 'utf8')); }
+15
function privateJson(path, value) {
+16
writeFileSync(path + '.next', JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+17
renameSync(path + '.next', path);
+18
}
+19
async function unusedPort(kind, address) {
+20
const socket = kind === 'udp' ? createSocket('udp4') : createServer();
+21
try {
+22
await new Promise((ready, reject) => {
+23
socket.once('error', reject);
+24
if (kind === 'udp') socket.bind(0, address, ready);
+25
else socket.listen(0, address, ready);
+26
});
+27
return socket.address().port;
+28
} finally {
+29
await new Promise(done => {
+30
try { socket.close(done); } catch { done(); }
+31
});
+32
}
+33
}
+34
+35
async function runVpnPhone() {
+36
+37
const verifiedJob = process.env.HTTP3_VERIFIED_NATIVE_JOB;
+38
check(/^http3-spike-echo-[0-9]{3}$/.test(verifiedJob ?? ''), 'Expected the admitted native gate');
+39
const verified = `${process.env.HTTP3_WORKSPACE_ROOT ?? (process.cwd() + "/build/workspaces")}/${verifiedJob}`;
+40
check(readFileSync(verified + '/rc', 'utf8').trim() === '0', 'Native gate must have completed successfully');
+41
check(readFileSync(verified + '/src/build/spike-echo/result.txt', 'utf8')
+42
.includes('RESULT spike-echo-native-v4-v6-and-lifecycle=PASS'), 'Full family/lifecycle gate missing');
+43
const receipt = json(verified + '/src/build/browser/capabilities.json');
+44
check(receipt.quicRevision === readFileSync('quic.rev', 'utf8').trim() &&
+45
receipt.spikeSdkRevision === readFileSync('spike-sdk.rev', 'utf8').trim(), 'Verified QUIC/SDK pair mismatch');
+46
check(['ready', 'bidirectionalEcho', 'unidirectionalEcho', 'datagramEcho', 'chromeReaped', 'serverReaped']
+47
.every(key => receipt[key] === true), 'Real echo/reaping gate missing');
+48
check(['configurableBind', 'retry', 'antiAmplification', 'boundedAdmission', 'peerAddressLogging',
+49
'pathChangeLogging', 'cidChangeLogging', 'echoOnly'].every(key => receipt.server?.[key] === true),
+50
'Reviewed server capability gate missing');
+51
const originalBinary = verified + '/src/tools/interop/build/native/bin/http3-preflight';
+52
const originalCertificate = verified + '/src/build/browser';
+53
check(digest(originalBinary) === receipt.binarySha256 &&
+54
digest(originalCertificate + '/cert.der') === receipt.certificateSha256, 'Verified input hash mismatch');
+55
+56
mkdirSync('build', { recursive: true, mode: 0o700 });
+57
const directory = resolve('build/phone-vpn');
+58
mkdirSync(directory, { mode: 0o700 }); // Exclusive; never reuse another window.
+59
const certificateDirectory = join(directory, 'certificate');
+60
mkdirSync(certificateDirectory, { mode: 0o700 });
+61
for (const name of ['cert.pem', 'cert.der', 'key.pem', 'private.raw', 'certificate.json']) {
+62
copyFileSync(join(originalCertificate, name), join(certificateDirectory, name));
+63
chmodSync(join(certificateDirectory, name), 0o600);
+64
}
+65
const binary = join(directory, 'echo-server');
+66
copyFileSync(originalBinary, binary);
+67
chmodSync(binary, 0o700);
+68
privateJson(join(directory, 'interop.json'), receipt);
+69
const bindAddress = (process.env.HTTP3_IPV4_ADDRESS ?? '127.0.0.1');
+70
const lifetimeSeconds = 5400; // 90 minutes, including setup; below the two-hour cap.
+71
const cancellation = new AbortController();
+72
const deadline = Date.now() + lifetimeSeconds * 1000;
+73
const timer = setTimeout(() => cancellation.abort(), lifetimeSeconds * 1000);
+74
const terminate = () => cancellation.abort();
+75
process.on('SIGTERM', terminate);
+76
process.on('SIGINT', terminate);
+77
const statePath = join(directory, 'state.json');
+78
const state = { schema: 1, kind: 'phone-vpn-controller', phase: 'starting',
+79
supervisor: identity(process.pid), startedAt: new Date().toISOString(),
+80
expiresAt: new Date(deadline).toISOString(), verifiedJob,
+81
sourceRevision: receipt.sourceRevision, quicRevision: receipt.quicRevision,
+82
sdkRevision: receipt.spikeSdkRevision, binarySha256: receipt.binarySha256,
+83
certificateSha256: receipt.certificateSha256 };
+84
let page;
+85
let server;
+86
let serverEnded = false;
+87
let serverError;
+88
let failure;
+89
const serverDirectory = join(directory, 'server');
+90
try {
+91
privateJson(statePath, state);
+92
const port = await unusedPort('udp', bindAddress);
+93
const pagePort = await unusedPort('tcp', bindAddress);
+94
cancellation.signal.throwIfAborted();
+95
const origin = `https://${bindAddress}:${pagePort}`;
+96
const config = { schema: 1, testId: 'phone-vpn-001', expectedHost: hostname(), scope: 'vpn',
+97
binary, binarySha256: receipt.binarySha256, certificateDirectory,
+98
runDirectory: serverDirectory, interopReceipt: join(directory, 'interop.json'),
+99
bindAddress, port, lifetimeSeconds, authority: `${bindAddress}:${port}`, origins: [origin] };
+100
const configPath = join(directory, 'server-config.json');
+101
privateJson(configPath, config);
+102
check(inspectPlan(configPath).ready, 'Phone lifecycle prerequisites are incomplete');
+103
page = await startPhonePage({ schema: 1, scope: 'vpn', expectedHost: hostname(), bindAddress,
+104
port: pagePort, lifetimeSeconds, page: resolve('web/phone.html'), certificateDirectory });
+105
page.closed.then(() => cancellation.abort());
+106
server = runTest(configPath, { signal: cancellation.signal }).then(
+107
value => { serverEnded = true; return value; },
+108
error => { serverEnded = true; serverError = error; });
+109
const readyDeadline = Date.now() + 15000;
+110
let serverState;
+111
while (!serverEnded && !cancellation.signal.aborted) {
+112
if (existsSync(join(serverDirectory, 'state.json'))) {
+113
serverState = json(join(serverDirectory, 'state.json'));
+114
if (serverState.phase === 'ready') break;
+115
}
+116
check(Date.now() < readyDeadline, 'Phone server readiness deadline');
+117
await pause(50);
+118
}
+119
check(serverState?.phase === 'ready' && !serverEnded && !cancellation.signal.aborted,
+120
serverError?.message ?? 'Phone server ended before readiness');
+121
const query = new URLSearchParams({ host: bindAddress, port: String(port), hash: receipt.certificateSha256 });
+122
const parameters = { scope: 'vpn', host: bindAddress, port, hash: receipt.certificateSha256,
+123
pagePort, pageURL: page.url, phoneURL: `${page.url}?${query}`, expiresAt: state.expiresAt,
+124
sourceRevision: receipt.sourceRevision, binarySha256: receipt.binarySha256,
+125
quicRevision: receipt.quicRevision, sdkRevision: receipt.spikeSdkRevision,
+126
serverState: join(serverDirectory, 'state.json'), serverLog: join(serverDirectory, 'stdout.log') };
+127
privateJson(join(directory, 'parameters.json'), parameters);
+128
Object.assign(state, { phase: 'ready', readyAt: new Date().toISOString(), child: serverState.child });
+129
privateJson(statePath, state);
+130
console.log(`RESULT phone-vpn-ready parameters=build/phone-vpn/parameters.json expires=${state.expiresAt}`);
+131
await server;
+132
if (serverError) throw serverError;
+133
} catch (error) { failure = error; }
+134
finally {
+135
clearTimeout(timer);
+136
cancellation.abort();
+137
const cleanup = await Promise.allSettled([page?.close(), server]);
+138
if (cleanup[0].status === 'rejected') failure ??= cleanup[0].reason;
+139
process.off('SIGTERM', terminate);
+140
process.off('SIGINT', terminate);
+141
const terminal = existsSync(join(serverDirectory, 'state.json')) ? json(join(serverDirectory, 'state.json')) : null;
+142
Object.assign(state, { phase: 'finished', endedAt: new Date().toISOString(), pageClosed: cleanup[0].status === 'fulfilled',
+143
childReaped: terminal?.childReaped ?? !server, error: failure?.message ?? serverError?.message });
+144
privateJson(statePath, state);
+145
check(state.childReaped, 'Phone child cleanup was not confirmed');
+146
console.log(`RESULT phone-vpn-finished pageClosed=${state.pageClosed} childReaped=true`);
+147
}
+148
if (failure) throw failure;
+149
if (serverError) throw serverError;
+150
}
+151
+152
try {
+153
const [command, directory] = process.argv.slice(2);
+154
if (command === 'stop' && directory) console.log(JSON.stringify(stopRun(resolve(directory))));
+155
else { check(command === 'run' && !directory, 'Usage: vpn-phone-run.mjs run | stop RUN_DIRECTORY'); await runVpnPhone(); }
+156
} catch (error) { console.error(`RESULT phone-vpn-error ${error.message}`); process.exitCode = 1; }
test/test-echo-lifecycle.mjsmodified
@@ -8,7 +8,7 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync,
8
import { hostname } from 'node:os';
9
import { join, resolve } from 'node:path';
10
import { test } from 'node:test';
−11
import { identity, inspectPlan, sameIdentity, stopRun } from '../scripts/echo-lifecycle.mjs';
+11
import { identity, inspectPlan, runTest, sameIdentity, stopRun } from '../scripts/echo-lifecycle.mjs';
12
13
const root = resolve('build/lifecycle');
14
const runner = resolve('scripts/echo-lifecycle.mjs');
@@ -88,6 +88,21 @@ function reaped(config) {
88
return result;
89
}
90
+91
test('parent cancellation reaps its admitted child without signalling the parent', async t => {
+92
const f = fixture('parent-cancel', 5);
+93
const cancellation = new AbortController();
+94
const running = runTest(f.path, { signal: cancellation.signal });
+95
t.after(async () => { cancellation.abort(); await running.catch(() => {}); });
+96
const deadline = Date.now() + 5000;
+97
while (!existsSync(join(f.config.runDirectory, 'state.json')) || state(f.config).phase !== 'ready') {
+98
assert.ok(Date.now() < deadline, 'Owned fixture readiness deadline');
+99
await pause(25);
+100
}
+101
cancellation.abort();
+102
await running;
+103
assert.equal(reaped(f.config).reason, 'parent-stop');
+104
});
+105
106
test('plan is read-only and rejects capability-only or unproved admission', () => {
107
const f = fixture();
108
assert.equal(inspectPlan(f.path).ready, true);