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 run
scripts/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
});