Commita8738c73Recorded19 Oct 2026Repositorysigil-http3
Prepare bounded manual IPv6 priming with control and traced arms
Changed
scripts/phantom-ipv6-punch-run.sh | 20 ++++++++++++++++
scripts/prepare-punch-inputs.mjs | 34 +++++++++++++++++++++++++++
scripts/punch-firewall.mjs | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
scripts/punch-prime.mjs | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
scripts/punch-window.mjs | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
test/test-punch-prime.mjs | 58 +++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 470 insertions(+)Diff
scripts/phantom-ipv6-punch-run.shadded
@@ -0,0 +1,20 @@
+1
#!/usr/bin/env bash+2
set -euo pipefail+3
cd "$(dirname "$0")/.."+4
umask 077+5
mkdir -p build/punch-checks+6
node --check scripts/punch-prime.mjs+7
node --check scripts/punch-firewall.mjs+8
node --check scripts/punch-window.mjs+9
node scripts/prepare-punch-inputs.mjs+10
timeout --foreground 30 node --test test/test-punch-prime.mjs > build/punch-checks/socket-tests.log 2>&1+11
printf 'RESULT punch-socket-checks=PASS\n'+12
export HTTP3_PREFLIGHT_SAN="IP:127.0.0.1,IP:::1,IP:${HTTP3_IPV4_ADDRESS:-127.0.0.1},IP:$HTTP3_IPV6_ADDRESS,DNS:localhost"+13
export HTTP3_PREFLIGHT_PREBUILT=1 HTTP3_PREFLIGHT_HTTPS_PAGE=1 HTTP3_PREFLIGHT_QUERY=1+14
# This label selects the already reviewed driver contract. No SDK source is needed:+15
# the reused binary's exact old SDK hash/pin proof is retained above.+16
export HTTP3_SPIKE_SDK_JOB=http3-example HTTP3_SPIKE_TRACE=1 HTTP3_SPIKE_TRACE_PROBE=1+17
HTTP3_PREFLIGHT_HOST=::1 bash scripts/phantom-browser-preflight.sh+18
export HTTP3_SOURCE_REVISION+19
HTTP3_SOURCE_REVISION=$(git rev-parse HEAD)+20
exec node scripts/punch-window.mjs runscripts/prepare-punch-inputs.mjsadded
@@ -0,0 +1,34 @@
+1
// Reuse only a completed private trace gate; no shared checkout or SDK dependency.+2
import { createHash } from 'node:crypto';+3
import { copyFileSync, chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+4
import { resolve } from 'node:path';+5
import { hostname } from 'node:os';+6
+7
const job = 'http3-example';+8
const previous = process.env.HTTP3_INPUT_DIRECTORY ?? ((process.env.HTTP3_WORKSPACE_ROOT ?? (process.cwd() + '/build/workspaces')) + '/' + job);+9
const read = path => readFileSync(previous + path, 'utf8');+10
if (read('/rc').trim() !== '0' || !read('/src/build/spike-echo/trace-result.txt').includes('private-trace-native-browser-regressions=PASS') ||+11
!read('/src/build/spike-echo/tests.log').includes('SPIKE-CHECKS total=154 passed=154 failed=0'))+12
throw new Error('Completed traced regression gate missing');+13
const receipt = JSON.parse(read('/src/build/browser/capabilities.json'));+14
const manifest = JSON.parse(read('/src/build/spike-echo/trace-manifest.json'));+15
if (receipt.quicRevision !== readFileSync('quic.rev', 'utf8').trim() || manifest.base !== receipt.quicRevision ||+16
receipt.spikeSdkRevision !== readFileSync('spike-sdk.rev', 'utf8').trim() ||+17
!receipt.traceProbe?.newTuple || !receipt.traceProbe?.dropRecorded || !receipt.chromeReaped || !receipt.serverReaped)+18
throw new Error('Trace provenance/interop cleanup mismatch');+19
const original = previous + '/src/tools/interop/build/native/bin/http3-preflight';+20
const digest = path => createHash('sha256').update(readFileSync(path)).digest('hex');+21
if (digest(original) !== receipt.binarySha256) throw new Error('Traced native binary hash mismatch');+22
mkdirSync('tools/interop/build/native/bin', { recursive: true });+23
copyFileSync(original, 'tools/interop/build/native/bin/http3-preflight');+24
chmodSync('tools/interop/build/native/bin/http3-preflight', 0o700);+25
mkdirSync('build/punch-provenance', { recursive: true, mode: 0o700 });+26
for (const file of ['trace-result.txt', 'trace-manifest.json', 'trace.patch', 'test-sources.json'])+27
copyFileSync(previous + '/src/build/spike-echo/' + file, 'build/punch-provenance/' + file);+28
const proof = { scope: 'spike-only-reused-traced-artifact', job, sourceRevision: receipt.sourceRevision,+29
binarySha256: receipt.binarySha256, quicRevision: receipt.quicRevision, sdkRevision: receipt.spikeSdkRevision,+30
traceManifestSha256: digest(previous + '/src/build/spike-echo/trace-manifest.json'),+31
tracePatchSha256: digest(previous + '/src/build/spike-echo/trace.patch'), tests: '154/154',+32
preparedAt: new Date().toISOString() };+33
writeFileSync(resolve('build/punch-input-proof.json'), JSON.stringify(proof, null, 2) + '\n', { mode: 0o600 });+34
console.log('RESULT punch-inputs=VERIFIED reused-trace-job=' + job + ' no-native-build');scripts/punch-firewall.mjsadded
@@ -0,0 +1,77 @@
+1
// Generate one exact root command pair; this module never executes firewall tools.+2
import { writeFileSync, mkdirSync } from 'node:fs';+3
import { join } from 'node:path';+4
import { isIP } from 'node:net';+5
import { execFileSync } from 'node:child_process';+6
const quote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";+7
+8
export function preparePunchFirewall(directory, { bindAddress, interfaceName, supervisor }) {+9
if (isIP(bindAddress) !== 6 || !/^[23][0-9a-f:]+$/i.test(bindAddress) ||+10
!/^[-a-zA-Z0-9_.]+$/.test(interfaceName) || !Number.isInteger(supervisor?.pid) ||+11
!/^[0-9]+$/.test(supervisor.start) || !Number.isInteger(supervisor.uid))+12
throw new Error('Invalid exact firewall target/controller');+13
mkdirSync(directory, { mode: 0o700 });+14
const common = `#!/usr/bin/env bash+15
set -euo pipefail+16
(( EUID == 0 )) || { printf 'Run with sudo bash.\\n' >&2; exit 1; }+17
umask 022+18
firewall=/gnu/store/c3fa94c62chbj42q905zfi33x7z7kr9m-iptables-1.8.11/sbin/ip6tables+19
directory=${quote(directory)}+20
rule=(-i ${quote(interfaceName)} -d ${quote(bindAddress + '/128')} -p udp --dport 43443 -m comment --comment sigil-http3-example -j ACCEPT)+21
verify_close() {+22
local result+23
"$firewall" -w 5 -S INPUT >/dev/null+24
if "$firewall" -w 5 -C INPUT "\${rule[@]}" 2>/dev/null; then+25
"$firewall" -w 5 -D INPUT "\${rule[@]}"+26
else+27
result=$?+28
(( result == 1 )) || return "$result"+29
fi+30
if "$firewall" -w 5 -C INPUT "\${rule[@]}" 2>/dev/null; then+31
printf 'ERROR: matching punch allowance remains.\\n' >&2+32
return 1+33
else+34
result=$?+35
(( result == 1 )) || return "$result"+36
fi+37
if [[ ! -e "$directory/closed.json" ]]; then+38
(set -C; printf '{"schema":1,"verifiedAbsent":true,"closedEpoch":%s}\\n' "$(date +%s)" > "$directory/closed.json")+39
fi+40
printf 'Matching punch allowance absent.\\n'+41
}+42
`;+43
const open = common + `+44
controller_alive() {+45
local stat_line rest+46
local -a fields+47
[[ -r /proc/${supervisor.pid}/stat ]] || return 1+48
read -r stat_line < /proc/${supervisor.pid}/stat || return 1+49
rest=\${stat_line##*) }+50
read -r -a fields <<< "$rest"+51
[[ \${fields[19]:-} == ${quote(supervisor.start)} && \${fields[0]:-} != Z ]]+52
}+53
controller_alive || { printf 'Recorded punch controller is gone.\\n' >&2; exit 1; }+54
[[ ! -e "$directory/opened.json" && ! -e "$directory/closed.json" ]] || { printf 'Choose a fresh window.\\n' >&2; exit 1; }+55
if "$firewall" -w 5 -C INPUT "\${rule[@]}" 2>/dev/null; then+56
printf 'Matching punch allowance already exists; do not adopt it.\\n' >&2+57
exit 1+58
fi+59
installed=0+60
cleanup() { if (( installed )); then verify_close; fi; }+61
trap cleanup EXIT+62
trap 'exit 130' INT+63
trap 'exit 143' TERM HUP+64
installed=1+65
"$firewall" -w 5 -I INPUT 1 "\${rule[@]}"+66
"$firewall" -w 5 -C INPUT "\${rule[@]}"+67
opened=$(date +%s)+68
expires=$(( opened + 4500 ))+69
(set -C; printf '{"schema":1,"port":43443,"address":"${bindAddress}","supervisorPID":${supervisor.pid},"supervisorStart":"${supervisor.start}","openedEpoch":%s,"expiresEpoch":%s}\\n' "$opened" "$expires" > "$directory/opened.json")+70
printf 'Punch allowance opened; automatic close at 75 minutes or recorded controller exit. Keep this foreground guard running.\\n'+71
while (( $(date +%s) < expires )) && controller_alive && [[ ! -e "$directory/closed.json" ]]; do sleep 1; done+72
`;+73
writeFileSync(join(directory, 'open.sh'), open, { mode: 0o600 });+74
writeFileSync(join(directory, 'close.sh'), common + '\nverify_close\n', { mode: 0o600 });+75
execFileSync('bash', ['-n', join(directory, 'open.sh')]);+76
execFileSync('bash', ['-n', join(directory, 'close.sh')]);+77
}scripts/punch-prime.mjsadded
@@ -0,0 +1,78 @@
+1
// Bounded socket priming only. No router control or background sender.+2
import { createSocket } from 'node:dgram';+3
import { BlockList, isIP } from 'node:net';+4
import { setTimeout as pause } from 'node:timers/promises';+5
+6
export const punchPorts = Object.freeze([40000, 40001, 40002]);+7
function check(value, message) { if (!value) throw new Error(message); }+8
export function validateRendezvous(value, localAddress, now = Date.now()) {+9
check(value?.cellularOnly === true && isIP(value.phoneIPv6) === 6 &&+10
/^[23][0-9a-f:]+$/i.test(value.phoneIPv6) && !/^2001:db8:/i.test(value.phoneIPv6) &&+11
!value.phoneIPv6.includes('%'), 'Need the current numeric global cellular IPv6');+12
const home = new BlockList();+13
home.addSubnet(localAddress, 64, 'ipv6');+14
check(!home.check(value.phoneIPv6, 'ipv6'), 'Cellular target must be outside local /64');+15
const observed = Date.parse(value.observedAt);+16
check(Number.isFinite(observed) && observed <= now && now - observed <= 600000,+17
'Manual cellular address must have been confirmed within ten minutes');+18
return value.phoneIPv6;+19
}+20
+21
export async function primeSocket({ bindAddress, sourcePort, phoneIPv6, ports = punchPorts,+22
scope = 'ipv6-direct', signal, beforeSend = () => {}, onRecord = () => {} }) {+23
check(isIP(bindAddress) === 6 && isIP(phoneIPv6) === 6, 'Priming requires numeric IPv6');+24
check(Number.isInteger(sourcePort) && sourcePort >= 1024 && sourcePort <= 65535, 'Invalid priming source port');+25
check(ports.length === 3 && ports.every(port => Number.isInteger(port) && port >= 1024 && port <= 65535),+26
'Choose exactly three unprivileged destination ports');+27
check((scope === 'test-loopback' && bindAddress === '::1' && phoneIPv6 === '::1') ||+28
(scope === 'ipv6-direct' && sourcePort === 43443 && /^[23]/i.test(bindAddress) && /^[23]/i.test(phoneIPv6) &&+29
ports.every((port, index) => port === punchPorts[index])), 'Priming tuple exceeds the configured scope');+30
const socket = createSocket('udp6');+31
const receipt = { scope, bindAddress, sourcePort, phoneIPv6, destinationPorts: [...ports],+32
mode: 'address-only-unknown-browser-port', startedAt: new Date().toISOString(), packets: [], ingress: [] };+33
let bound = false;+34
let socketError;+35
socket.on('error', error => { socketError = error; });+36
socket.on('message', (bytes, peer) => {+37
if (receipt.ingress.length >= 32) return;+38
const long = bytes.length > 0 && bytes[0] >= 128;+39
const length = long && bytes.length >= 6 ? bytes[5] : null;+40
receipt.ingress.push({ utc: new Date().toISOString(), address: peer.address, port: peer.port,+41
bytes: bytes.length, header: long ? 'long' : 'short',+42
dcid: length !== null && length <= 20 && bytes.length >= 6 + length ? bytes.subarray(6, 6 + length).toString('hex') : null,+43
outcome: 'priming-socket-no-quic-processing' });+44
});+45
try {+46
signal?.throwIfAborted();+47
await new Promise((done, reject) => {+48
socket.once('error', reject);+49
socket.bind({ address: bindAddress, port: sourcePort, ipv6Only: true, exclusive: true }, done);+50
});+51
bound = true;+52
const local = socket.address();+53
check(local.address === bindAddress && local.port === sourcePort, 'Priming source tuple mismatch');+54
for (let round = 0; round < 2; round++) {+55
for (const port of ports) {+56
signal?.throwIfAborted();+57
if (socketError) throw socketError;+58
beforeSend();+59
const bytes = Buffer.alloc(8);+60
bytes.write('SGP1');+61
bytes.writeUInt32BE(receipt.packets.length, 4);+62
await new Promise((done, reject) => socket.send(bytes, port, phoneIPv6, error => error ? reject(error) : done()));+63
receipt.packets.push({ utc: new Date().toISOString(), destinationPort: port, bytes: bytes.length });+64
onRecord(receipt);+65
await pause(150, undefined, { signal });+66
}+67
}+68
if (socketError) throw socketError;+69
return receipt;+70
} finally {+71
await new Promise(done => { try { socket.close(done); } catch { done(); } });+72
receipt.socketClosed = true;+73
receipt.bound = bound;+74
receipt.endedAt = new Date().toISOString();+75
receipt.error = socketError?.message;+76
onRecord(receipt);+77
}+78
}scripts/punch-window.mjsadded
@@ -0,0 +1,203 @@
+1
// operator-configured, manual-rendezvous two-arm IPv6 experiment. No router writes.+2
import { createHash } from 'node:crypto';+3
import { createServer, isIP } from 'node:net';+4
import { copyFileSync, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';+5
import { hostname, networkInterfaces } from 'node:os';+6
import { join, resolve } from 'node:path';+7
import { fileURLToPath } from 'node:url';+8
import { identity, inspectPlan, runTest, stopRun } from './echo-lifecycle.mjs';+9
import { startPhonePage } from './phone-page-host.mjs';+10
import { preparePunchFirewall } from './punch-firewall.mjs';+11
import { primeSocket, punchPorts, validateRendezvous } from './punch-prime.mjs';+12
+13
const pause = ms => new Promise(done => setTimeout(done, ms));+14
const digest = path => createHash('sha256').update(readFileSync(path)).digest('hex');+15
function check(value, message) { if (!value) throw new Error(message); }+16
function json(path) { check(lstatSync(path).size <= 65536, 'JSON receipt exceeds limit'); return JSON.parse(readFileSync(path, 'utf8')); }+17
function privateJson(path, value) {+18
writeFileSync(path + '.next', JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });+19
renameSync(path + '.next', path);+20
}+21
function privateDirectory(path) {+22
const info = lstatSync(path);+23
check(info.isDirectory() && info.uid === process.getuid() && (info.mode & 0o077) === 0, 'Expected owned private run directory');+24
}+25
function rootJson(path) {+26
if (!existsSync(path)) return null;+27
const info = lstatSync(path);+28
check(info.isFile() && info.uid === 0 && (info.mode & 0o022) === 0 && info.size <= 4096, 'Expected root-owned bounded firewall receipt');+29
return json(path);+30
}+31
async function pagePort() {+32
const server = createServer();+33
await new Promise((done, reject) => { server.once('error', reject); server.listen(0, (process.env.HTTP3_IPV4_ADDRESS ?? '127.0.0.1'), done); });+34
const port = server.address().port;+35
await new Promise(done => server.close(done));+36
return port;+37
}+38
+39
export function requestPrime(directory, rendezvousPath, controlFailed) {+40
check(controlFailed, 'Explicit failed no-prime control confirmation is required');+41
privateDirectory(directory);+42
const state = json(join(directory, 'state.json'));+43
check(state.phase === 'control-ready' && Date.parse(state.expiresAt) > Date.now(), 'Control is not ready/active');+44
const rendezvous = json(rendezvousPath);+45
validateRendezvous(rendezvous, state.bindAddress);+46
writeFileSync(join(directory, 'prime-request.json'), JSON.stringify({ schema: 1, action: 'prime',+47
confirmedControlFailed: true, requestedAt: new Date().toISOString(), rendezvous }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });+48
return { requested: true, ports: punchPorts, packets: 6 };+49
}+50
+51
async function run() {+52
+53
const bindAddress = process.env.HTTP3_IPV6_ADDRESS;+54
check(isIP(bindAddress) === 6 && /^[23]/i.test(bindAddress), 'Choose configured global IPv6');+55
const device = Object.entries(networkInterfaces()).find(([, addresses]) => addresses?.some(address =>+56
address.family === 'IPv6' && address.address === bindAddress && !address.internal));+57
check(device && device[0] === process.env.HTTP3_INTERFACE, 'configured /128 is not assigned on the expected physical interface');+58
const input = json('build/punch-input-proof.json');+59
const receipt = json('build/browser/capabilities.json');+60
const originalBinary = resolve('tools/interop/build/native/bin/http3-preflight');+61
check(input.job === 'http3-example' && input.binarySha256 === digest(originalBinary) &&+62
receipt.binarySha256 === input.binarySha256 && receipt.quicRevision === readFileSync('quic.rev', 'utf8').trim() &&+63
receipt.spikeSdkRevision === readFileSync('spike-sdk.rev', 'utf8').trim(), 'Reused traced artifact proof mismatch');+64
check(['ready', 'bidirectionalEcho', 'unidirectionalEcho', 'datagramEcho', 'chromeReaped', 'serverReaped'].every(key => receipt[key] === true) &&+65
receipt.traceProbe?.newTuple && receipt.traceProbe?.dropRecorded && receipt.traceProbe?.connectionStillOpen,+66
'Fresh certificate/browser trace gate missing');+67
const directory = resolve('build/phone-punch');+68
mkdirSync(directory, { mode: 0o700 });+69
const certificateDirectory = join(directory, 'certificate');+70
mkdirSync(certificateDirectory, { mode: 0o700 });+71
for (const file of ['cert.pem', 'cert.der', 'key.pem', 'private.raw', 'certificate.json']) {+72
copyFileSync(resolve('build/browser', file), join(certificateDirectory, file));+73
chmodSync(join(certificateDirectory, file), 0o600);+74
}+75
const binary = join(directory, 'echo-server');+76
copyFileSync(originalBinary, binary); chmodSync(binary, 0o700);+77
privateJson(join(directory, 'interop.json'), receipt);+78
const supervisor = identity(process.pid);+79
check(supervisor && supervisor.uid === process.getuid(), 'Cannot admit punch controller');+80
const deadline = Date.now() + 3600000;+81
const state = { schema: 1, kind: 'phone-ipv6-punch', phase: 'preparing', supervisor, bindAddress, port: 43443,+82
startedAt: new Date().toISOString(), expiresAt: new Date(deadline).toISOString(), binarySha256: input.binarySha256,+83
sourceRevision: process.env.HTTP3_SOURCE_REVISION, tracedSourceRevision: input.sourceRevision };+84
const statePath = join(directory, 'state.json');+85
const firewall = join(directory, 'firewall');+86
preparePunchFirewall(firewall, { bindAddress, interfaceName: device[0], supervisor });+87
const cancellation = new AbortController();+88
const stop = () => cancellation.abort();+89
const timer = setTimeout(stop, 3600000);+90
process.on('SIGTERM', stop); process.on('SIGINT', stop);+91
let page, arm, failure;+92
const rootWindow = () => {+93
const closed = rootJson(join(firewall, 'closed.json'));+94
if (closed?.verifiedAbsent) return false;+95
const opened = rootJson(join(firewall, 'opened.json'));+96
return opened?.schema === 1 && opened.port === 43443 && opened.address === bindAddress &&+97
opened.supervisorPID === supervisor.pid && opened.supervisorStart === supervisor.start &&+98
opened.openedEpoch * 1000 >= Date.parse(state.startedAt) - 1000 && opened.expiresEpoch * 1000 > Date.now();+99
};+100
async function stopArm() {+101
if (!arm) return;+102
arm.cancel.abort();+103
await arm.done;+104
check(json(join(arm.directory, 'state.json')).childReaped, 'Native arm child was not reaped before handoff');+105
}+106
async function startArm(name, origin) {+107
cancellation.signal.throwIfAborted();+108
const runDirectory = join(directory, 'server-' + name);+109
const config = { schema: 1, testId: 'phone-punch-' + name, expectedHost: hostname(), scope: 'ipv6-direct',+110
bindAddress, port: 43443, binary, binarySha256: input.binarySha256, certificateDirectory,+111
authority: `[${bindAddress}]:43443`, origins: [origin],+112
interopReceipt: join(directory, 'interop.json'), runDirectory,+113
lifetimeSeconds: Math.max(1, Math.floor((deadline - Date.now()) / 1000)) };+114
const path = join(directory, name + '-config.json');+115
privateJson(path, config);+116
const plan = inspectPlan(path);+117
check(plan.ready, plan.blockers.join('; '));+118
arm = { name, directory: runDirectory, cancel: new AbortController(), ended: false };+119
const current = arm;+120
current.done = runTest(path, { signal: current.cancel.signal }).then(+121
result => { current.ended = true; return result; },+122
error => { current.ended = true; current.error = error; });+123
const readyUntil = Date.now() + 12000;+124
while (!current.ended && !cancellation.signal.aborted && Date.now() < readyUntil) {+125
const path = join(runDirectory, 'state.json');+126
if (existsSync(path)) {+127
const serverState = json(path);+128
if (serverState.phase === 'ready') { state.child = serverState.child; state.arm = name; return; }+129
}+130
await pause(50);+131
}+132
throw current.error ?? new Error('Native ' + name + ' readiness deadline');+133
}+134
try {+135
privateJson(statePath, state);+136
const port = await pagePort();+137
page = await startPhonePage({ schema: 1, scope: 'vpn', expectedHost: hostname(), bindAddress: (process.env.HTTP3_IPV4_ADDRESS ?? '127.0.0.1'),+138
port, lifetimeSeconds: 3600, page: resolve('web/phone.html'), certificateDirectory });+139
page.closed.then(stop);+140
await startArm('control', new URL(page.url).origin);+141
const query = new URLSearchParams({ host: bindAddress, port: '43443', hash: receipt.certificateSha256 });+142
const parameters = { scope: 'ipv6-punch', phoneURL: `${page.url}?${query}`, host: bindAddress, port: 43443,+143
hash: receipt.certificateSha256, pagePort: port, expiresAt: state.expiresAt,+144
primePorts: punchPorts, maximumPrimePackets: 6, openCommand: `sudo bash ${firewall}/open.sh`,+145
closeCommand: `sudo bash ${firewall}/close.sh`, rendezvous: 'manual-current-cellular-ipv6' };+146
privateJson(join(directory, 'parameters.json'), parameters);+147
state.phase = 'awaiting-firewall'; privateJson(statePath, state);+148
console.log('RESULT punch-page-and-control-listener-ready parameters=build/phone-punch/parameters.json awaiting-root-open');+149
while (!cancellation.signal.aborted && !arm.ended) {+150
if (rootJson(join(firewall, 'closed.json'))?.verifiedAbsent) { state.reason = 'firewall-closed'; break; }+151
if (state.phase === 'awaiting-firewall' && rootWindow()) {+152
state.phase = 'control-ready'; state.controlReadyAt = new Date().toISOString(); privateJson(statePath, state);+153
console.log('RESULT punch-control-ready no-prime=true');+154
}+155
if (state.phase !== 'awaiting-firewall' && !rootWindow()) { state.reason = 'firewall-window-ended'; break; }+156
const requestPath = join(directory, 'prime-request.json');+157
if (state.phase === 'control-ready' && existsSync(requestPath)) {+158
const request = json(requestPath);+159
check(request.schema === 1 && request.confirmedControlFailed === true, 'No failed-control confirmation');+160
const phoneIPv6 = validateRendezvous(request.rendezvous, bindAddress);+161
check(rootWindow(), 'Fresh root allowance is required');+162
await stopArm();+163
const controlLog = readFileSync(join(arm.directory, 'stdout.log'), 'utf8');+164
check(!controlLog.includes('event=udp-in') && !controlLog.includes('HTTP3-AUTHENTICATED ') &&+165
!controlLog.includes('event=trace-exhausted'), 'No-prime control received packets; inspect instead of priming');+166
privateJson(join(directory, 'control-result.json'), { failedOnPhoneConfirmed: true, ingress: 0,+167
capturedAt: new Date().toISOString(), logSha256: digest(join(arm.directory, 'stdout.log')) });+168
state.phase = 'priming'; privateJson(statePath, state);+169
const prime = await primeSocket({ bindAddress, sourcePort: 43443, phoneIPv6, signal: cancellation.signal,+170
beforeSend: () => check(rootWindow(), 'Firewall window closed during priming'),+171
onRecord: value => privateJson(join(directory, 'priming.json'), value) });+172
check(prime.socketClosed && prime.packets.length === 6, 'Priming did not finish/release its socket');+173
await startArm('primed', new URL(page.url).origin);+174
state.phase = 'primed-ready'; state.primedReadyAt = new Date().toISOString();+175
state.primeEndedAt = prime.endedAt; privateJson(statePath, state);+176
console.log('RESULT punch-primed-ready connect-immediately=true packets=6 ports=40000,40001,40002');+177
}+178
await pause(100);+179
}+180
if (arm.error) throw arm.error;+181
} catch (error) { failure = error; }+182
finally {+183
clearTimeout(timer); cancellation.abort();+184
const results = await Promise.allSettled([stopArm(), page?.close()]);+185
process.off('SIGTERM', stop); process.off('SIGINT', stop);+186
failure ??= results.find(result => result.status === 'rejected')?.reason;+187
Object.assign(state, { phase: 'finished', endedAt: new Date().toISOString(),+188
childReaped: results[0].status === 'fulfilled', pageClosed: results[1].status === 'fulfilled', error: failure?.message });+189
privateJson(statePath, state);+190
console.log(`RESULT punch-finished child-reaped=${state.childReaped} page-closed=${state.pageClosed}`);+191
}+192
if (failure) throw failure;+193
}+194
+195
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+196
try {+197
const [command, directory, rendezvous, confirmation] = process.argv.slice(2);+198
if (command === 'run') await run();+199
else if (command === 'stop') console.log(JSON.stringify(stopRun(resolve(directory))));+200
else if (command === 'prime') console.log(JSON.stringify(requestPrime(resolve(directory), resolve(rendezvous), confirmation === '--control-failed')));+201
else throw new Error('Usage: punch-window.mjs run | stop RUN_DIRECTORY | prime RUN_DIRECTORY RENDEZVOUS.json --control-failed');+202
} catch (error) { console.error('RESULT punch-error ' + error.message); process.exitCode = 1; }+203
}test/test-punch-prime.mjsadded
@@ -0,0 +1,58 @@
+1
import assert from 'node:assert/strict';+2
import { test } from 'node:test';+3
import { createSocket } from 'node:dgram';+4
import { primeSocket, validateRendezvous } from '../scripts/punch-prime.mjs';+5
+6
async function socket(port = 0) {+7
const value = createSocket('udp6');+8
await new Promise((done, reject) => { value.once('error', reject); value.bind(port, '::1', done); });+9
return value;+10
}+11
async function close(value) { await new Promise(done => value.close(done)); }+12
+13
test('six priming datagrams preserve one exact source tuple and release it', async () => {+14
const receivers = await Promise.all([socket(), socket(), socket()]);+15
const source = await socket();+16
const sourcePort = source.address().port;+17
await close(source);+18
const received = [];+19
for (const receiver of receivers) receiver.on('message', (bytes, peer) => received.push({ bytes, peer }));+20
try {+21
const result = await primeSocket({ scope: 'test-loopback', bindAddress: '::1', phoneIPv6: '::1',+22
sourcePort, ports: receivers.map(receiver => receiver.address().port) });+23
assert.equal(result.socketClosed, true);+24
assert.equal(result.packets.length, 6);+25
assert.equal(received.length, 6);+26
assert.ok(received.every(packet => packet.bytes.length === 8 && packet.peer.port === sourcePort && packet.peer.address === '::1'));+27
const replacement = createSocket('udp6');+28
await new Promise((done, reject) => { replacement.once('error', reject); replacement.bind(sourcePort, '::1', done); });+29
await close(replacement);+30
} finally { await Promise.all(receivers.map(close)); }+31
});+32
+33
test('parent cancellation closes priming socket before another owner binds', async () => {+34
const receiver = await socket(), source = await socket();+35
const port = source.address().port;+36
await close(source);+37
const cancellation = new AbortController();+38
let receipt;+39
try {+40
await assert.rejects(primeSocket({ scope: 'test-loopback', bindAddress: '::1', phoneIPv6: '::1', sourcePort: port,+41
ports: [receiver.address().port, receiver.address().port, receiver.address().port], signal: cancellation.signal,+42
onRecord(value) { receipt = value; if (value.packets.length === 1) cancellation.abort(); } }), /abort/i);+43
assert.equal(receipt.socketClosed, true);+44
assert.equal(receipt.packets.length, 1);+45
const replacement = await socket(port);+46
await close(replacement);+47
} finally { await close(receiver); }+48
});+49
+50
test('address rendezvous rejects home-prefix, stale, and noncellular targets', () => {+51
const now = Date.now(), local = '2001:db8:1:2::1';+52
const good = { cellularOnly: true, phoneIPv6: '2a00:1234:abcd:2345::1', observedAt: new Date(now).toISOString() };+53
assert.equal(validateRendezvous(good, local, now), good.phoneIPv6);+54
assert.throws(() => validateRendezvous({ ...good, phoneIPv6: '2001:db8:1:2::9' }, local, now));+55
assert.throws(() => validateRendezvous({ ...good, cellularOnly: false }, local, now));+56
assert.throws(() => validateRendezvous({ ...good, observedAt: new Date(now - 600001).toISOString() }, local, now));+57
assert.throws(() => validateRendezvous({ ...good, phoneIPv6: '::1' }, local, now));+58
});