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 runscripts/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);