merge(app): land authenticated isolated preview tooling

This commit is contained in:
2026-10-21 13:37:26 +01:00
4 changed files with 412 additions and 0 deletions
+26
View File
@@ -0,0 +1,26 @@
# F5 preview server candidate review
Manager reran all 6 fixture tests and added an idle-websocket regression past the
five-second establishment deadline. Healthy idle sockets now keep their session;
auth-check listeners are removed when finished. Default preview port is 8096,
separate from the raw API at 8080. HTTPS certificate paths remain untested.
Candidate `e3a82b0`'s static preview route was retained, with stricter decoded
path validation and canonical-path checks for files and SPA fallback. The proxy
now uses `http.request` / `https.request` streams so Range, HEAD, content-encoding,
and exact response bytes are preserved. Authentication checks fail closed after
five seconds and discard their response bodies. Unauthenticated document GETs
are redirected to the authenticated proxy's `/login?next=...`; assets remain
401. Login, logout, and artifact proxying still use the browser's upstream cookie.
WebSocket upgrades validate `/connect` and a same-origin browser Origin before
authentication or upstream connection. After authentication, both Host and
Origin map to the configured HTTP(S) upstream origin; cookies and upgrade headers
are retained. Upgraded sockets are tracked and destroyed during `close()`. HTTPS
uses Node TLS verification (no certificate bypass). Bind to loopback by default.
Verification: `node --test test/tool/preview.test.mjs`, `node --check` on server
and test, and `git diff --check`. Tests use only local fixtures and cover login
redirect, denied auth, exact compressed Range/HEAD bytes, origin rejection,
authenticated bidirectional WebSocket bytes, timeout, shutdown, and traversal / symlink
protection. No browser run, Flutter build, production access, or deployment was done.
+160
View File
@@ -0,0 +1,160 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { mkdtemp, writeFile, symlink, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { createServer } from 'node:http';
import { request as httpRequest } from 'node:http';
import { gzipSync } from 'node:zlib';
import net from 'node:net';
import { start } from '../../tool/preview/server.mjs';
async function fixture(t, { auth = true, hanging = false } = {}) {
const root = await mkdtemp(join(tmpdir(), 'preview-'));
await writeFile(join(root, 'index.html'), 'shell');
await writeFile(join(root, 'bundle.js'), 'bundle');
const seen = [];
const upstream = createServer((req, res) => {
seen.push({ url: req.url, headers: req.headers, method: req.method });
if (req.url === '/' && auth && req.headers.cookie !== 'sid=yes') {
res.writeHead(302, { location: '/login' }).end();
} else if (req.url === '/' && hanging) {
// Deliberately hold the auth check open to exercise its timeout.
} else if (req.url === '/login' || req.url === '/logout' || req.url.startsWith('/artifacts/')) {
res.writeHead(200, { 'content-type': 'application/octet-stream' }).end('proxied');
} else res.writeHead(200).end('authenticated');
});
upstream.on('upgrade', (req, socket, head) => {
seen.push({ url: req.url, headers: req.headers, upgraded: true });
socket.write('HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n');
if (head.length) socket.write(head);
socket.pipe(socket);
});
await new Promise((resolve) => upstream.listen(0, '127.0.0.1', resolve));
const preview = await start({ root, upstream: `http://127.0.0.1:${upstream.address().port}`, port: 0 });
t.after(async () => {
await preview.close();
await new Promise((resolve) => upstream.close(resolve));
await rm(root, { recursive: true, force: true });
});
return { root, upstream, preview, seen, base: `http://127.0.0.1:${preview.port}` };
}
function rawRequest(port, path, method, headers = {}) {
return new Promise((resolve, reject) => {
const request = httpRequest({ host: '127.0.0.1', port, path, method, headers }, (response) => {
const chunks = [];
response.on('data', (chunk) => chunks.push(chunk));
response.on('end', () => resolve({ status: response.statusCode, headers: response.headers, body: Buffer.concat(chunks) }));
});
request.on('error', reject);
request.end();
});
}
test('guards assets and redirects unauthenticated document requests to proxy login', async (t) => {
const { base, seen } = await fixture(t);
const redirect = await fetch(`${base}/runs/4?tab=active`, { redirect: 'manual', headers: { accept: 'text/html' } });
assert.equal(redirect.status, 302);
assert.equal(redirect.headers.get('location'), '/login?next=%2Fruns%2F4%3Ftab%3Dactive');
assert.equal((await fetch(`${base}/bundle.js`)).status, 401);
const auth = { cookie: 'sid=yes' };
assert.equal(await (await fetch(`${base}/bundle.js`, { headers: auth })).text(), 'bundle');
assert.equal((await fetch(`${base}/login`)).status, 200);
assert.equal(seen.filter((item) => item.url === '/login').length, 1);
assert.equal((await fetch(`${base}/%2f%2fevil`, { headers: auth })).status, 400);
});
test('streams exact compressed range bytes for GET and HEAD with mapped proxy requests', async (t) => {
const bytes = gzipSync(Buffer.from('preserve these exact compressed bytes'));
const { base, upstream, seen } = await fixture(t);
upstream.removeAllListeners('request');
upstream.on('request', (req, res) => {
if (req.url === '/') return res.end('authenticated');
seen.push({ url: req.url, headers: req.headers, method: req.method });
res.writeHead(206, { 'content-type': 'application/octet-stream', 'content-encoding': 'gzip', 'content-range': 'bytes 1-3/6', 'content-length': '3' });
res.end(bytes.subarray(1, 4));
});
const auth = { cookie: 'sid=yes', range: 'bytes=1-3' };
const response = await rawRequest(new URL(base).port, '/artifacts/x', 'GET', auth);
assert.equal(response.status, 206);
assert.equal(response.headers['content-encoding'], 'gzip');
assert.deepEqual(response.body, bytes.subarray(1, 4));
const head = await rawRequest(new URL(base).port, '/artifacts/x', 'HEAD', auth);
assert.equal(head.status, 206);
assert.equal(head.headers['content-length'], '3');
assert.equal(head.body.byteLength, 0);
assert.equal(seen.at(-1).headers.range, 'bytes=1-3');
});
test('rejects cross-origin and unauthenticated WebSocket upgrades before proxying', async (t) => {
const { preview, seen } = await fixture(t);
async function upgrade(headers) {
return new Promise((resolve) => {
const socket = net.connect(preview.port, '127.0.0.1', () => socket.write(`GET /connect HTTP/1.1\r\nHost: 127.0.0.1:${preview.port}\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n${headers}\r\n`));
let response = '';
socket.on('data', (chunk) => { response += chunk.toString(); if (response.includes('\r\n\r\n')) { socket.destroy(); resolve(response); } });
socket.on('error', () => resolve(response));
});
}
assert.match(await upgrade(`Origin: http://evil.test\r\nCookie: sid=yes\r\n`), /^HTTP\/1\.1 403/);
assert.match(await upgrade(`Origin: http://127.0.0.1:${preview.port}\r\n`), /^HTTP\/1\.1 401/);
assert.equal(seen.filter((item) => item.upgraded).length, 0);
});
test('authenticates and maps same-origin WebSocket Origin; bytes flow both directions and close completes', async (t) => {
const { preview, seen } = await fixture(t);
const socket = net.connect(preview.port, '127.0.0.1');
const chunks = [];
socket.on('data', (chunk) => chunks.push(chunk));
socket.write(`GET /connect HTTP/1.1\r\nHost: 127.0.0.1:${preview.port}\r\nOrigin: http://127.0.0.1:${preview.port}\r\nCookie: sid=yes\r\nConnection: Upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\nSec-WebSocket-Version: 13\r\n\r\n`);
await new Promise((resolve, reject) => {
const deadline = setTimeout(() => reject(new Error('upgrade timeout')), 1500);
const poll = setInterval(() => {
if (chunks.some((chunk) => chunk.toString().includes('101 Switching Protocols'))) { clearInterval(poll); clearTimeout(deadline); resolve(); }
}, 10);
});
const upgraded = seen.find((item) => item.upgraded);
assert.equal(upgraded.headers.origin, new URL(`http://${seen[0].headers.host}`).origin);
assert.equal(upgraded.headers.cookie, 'sid=yes');
await new Promise((resolve) => setTimeout(resolve, 5200));
assert.equal(socket.destroyed, false, 'healthy idle websocket must not time out');
const payload = Buffer.from([0x81, 0x02, 0x6f, 0x6b]);
socket.write(payload);
await new Promise((resolve, reject) => {
const deadline = setTimeout(() => reject(new Error('echo timeout')), 1500);
const poll = setInterval(() => {
if (Buffer.concat(chunks).includes(payload)) { clearInterval(poll); clearTimeout(deadline); resolve(); }
}, 10);
});
socket.destroy();
await preview.close();
});
test('fails closed on authentication timeout and closes idle upgraded sockets', async (t) => {
const { base } = await fixture(t, { auth: false, hanging: true });
const started = Date.now();
const response = await fetch(`${base}/bundle.js`);
assert.equal(response.status, 502);
assert.ok(Date.now() - started < 7000);
});
test('rejects encoded traversal and symlinked SPA fallback outside the root', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'preview-'));
const outside = await mkdtemp(join(tmpdir(), 'preview-out-'));
await writeFile(join(outside, 'index.html'), 'private');
await symlink(join(outside, 'index.html'), join(root, 'index.html'));
const upstream = createServer((req, res) => res.end('authenticated'));
await new Promise((resolve) => upstream.listen(0, '127.0.0.1', resolve));
const preview = await start({ root, upstream: `http://127.0.0.1:${upstream.address().port}`, port: 0 });
t.after(async () => {
await preview.close();
await new Promise((resolve) => upstream.close(resolve));
await rm(root, { recursive: true, force: true });
await rm(outside, { recursive: true, force: true });
});
const response = await fetch(`http://127.0.0.1:${preview.port}/missing/route`, { headers: { cookie: 'sid=yes' } });
assert.equal(response.status, 403);
assert.notEqual(await response.text(), 'private');
assert.equal((await fetch(`http://127.0.0.1:${preview.port}/%2e%2e%2fsecret`, { headers: { cookie: 'sid=yes' } })).status, 403);
});
+24
View File
@@ -0,0 +1,24 @@
# Flutter web preview
Build and run from `app/`:
```sh
/Users/alan/development/flutter/bin/flutter build web
UPSTREAM=http://127.0.0.1:8095 node tool/preview/server.mjs --port 8096
```
The preview binds to loopback by default and authenticates static requests by
checking the upstream authenticated web proxy with the browser cookie. Unauthenticated
HTML navigation goes to the proxy's `/login?next=...`; unauthenticated assets and
WebSocket upgrades are refused. Login, logout and artifacts are streamed to the
proxy without decoding compressed response bodies. `/connect` accepts only a
same-origin browser Origin, checks the cookie, then maps Origin and Host to the
configured upstream origin before upgrading. HTTP and HTTPS upstreams are
supported using Node's normal TLS certificate verification. Set `UPSTREAM` to
the authenticated proxy, never the raw control server. The root path and files
must exist locally, and only GET, HEAD, and POST are supported. Tests use
isolated loopback fixtures and port 0.
The persistent preview API is `start({ root, upstream, host, port })` from
`tool/preview/server.mjs`; it resolves to `{ server, port, close }`. Call
`close()` to stop accepting requests and close tracked upgraded sockets.
+202
View File
@@ -0,0 +1,202 @@
import { createServer, request as httpRequest } from 'node:http';
import { request as httpsRequest } from 'node:https';
import { realpath, stat, readFile } from 'node:fs/promises';
import { extname, resolve, sep } from 'node:path';
import net from 'node:net';
import tls from 'node:tls';
const mime = {
'.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
'.mjs': 'text/javascript; charset=utf-8', '.wasm': 'application/wasm',
'.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf',
'.json': 'application/json', '.css': 'text/css; charset=utf-8',
'.png': 'image/png', '.svg': 'image/svg+xml',
};
const noCache = { 'Cache-Control': 'no-store' };
const timeoutMs = 5000;
function reply(res, status, body = '') {
if (res.destroyed) return;
if (!res.headersSent) res.writeHead(status, { ...noCache, 'Content-Type': 'text/plain; charset=utf-8' });
res.end(body);
}
function inside(base, path) {
return path === base || path.startsWith(base + sep);
}
async function staticFile(base, pathname, req, res) {
let file = resolve(base, `.${pathname}`);
if (!inside(base, file)) return reply(res, 403);
try {
let real = await realpath(file);
if (!inside(base, real)) return reply(res, 403);
if ((await stat(real)).isDirectory()) {
real = await realpath(resolve(real, 'index.html'));
if (!inside(base, real)) return reply(res, 403);
}
file = real;
} catch (error) {
if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') return reply(res, 403);
if (extname(pathname)) return reply(res, 404, 'Not found');
try {
file = await realpath(resolve(base, 'index.html'));
if (!inside(base, file)) return reply(res, 403);
} catch { return reply(res, 404, 'Not found'); }
}
try {
const body = await readFile(file);
res.writeHead(200, { ...noCache, 'Content-Type': mime[extname(file)] ?? 'application/octet-stream' });
res.end(req.method === 'HEAD' ? undefined : body);
} catch { reply(res, 404, 'Not found'); }
}
function upstreamRequest(target, options, callback) {
return (target.protocol === 'https:' ? httpsRequest : httpRequest)(
{ protocol: target.protocol, hostname: target.hostname, port: target.port || undefined,
...options, timeout: timeoutMs }, callback,
);
}
function proxy(req, res, target) {
const url = new URL(req.url, target);
const headers = { ...req.headers, host: target.host };
delete headers.connection;
const upstream = upstreamRequest(target, { method: req.method, path: `${url.pathname}${url.search}`, headers }, (replyFromUpstream) => {
const forwarded = { ...replyFromUpstream.headers, ...noCache };
res.writeHead(replyFromUpstream.statusCode ?? 502, forwarded);
replyFromUpstream.on('error', () => res.destroy());
replyFromUpstream.pipe(res);
});
upstream.setTimeout(timeoutMs, () => upstream.destroy(new Error('upstream timeout')));
upstream.on('error', () => reply(res, 502, 'Upstream unavailable'));
req.on('aborted', () => upstream.destroy());
res.on('close', () => { if (!res.writableEnded) upstream.destroy(); });
if (req.method === 'GET' || req.method === 'HEAD') { req.resume(); upstream.end(); }
else req.pipe(upstream);
}
function authCheck(req, target, callback) {
let completed = false;
const finish = (result) => {
if (completed) return;
completed = true;
req.removeListener('aborted', abort);
req.socket.removeListener('close', abort);
callback(result);
};
const abort = () => check.destroy();
const check = upstreamRequest(target, { method: 'GET', path: '/', headers: {
cookie: req.headers.cookie ?? '', accept: 'text/html', 'accept-encoding': 'identity',
} }, (response) => {
response.resume();
finish(response.statusCode === 200);
});
check.setTimeout(timeoutMs, () => check.destroy(new Error('authentication check timeout')));
check.on('error', () => finish(null));
req.once('aborted', abort);
req.socket.once('close', abort);
check.end();
}
function reject(socket, status, phrase = 'Forbidden') {
if (!socket.destroyed) socket.end(`HTTP/1.1 ${status} ${phrase}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
}
export async function start({ root = resolve('build/web'), upstream = 'http://127.0.0.1:8095', host = '127.0.0.1', port = 8096 } = {}) {
const base = await realpath(root);
const target = new URL(upstream);
if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password) throw new Error('UPSTREAM must be credential-free HTTP(S)');
const sockets = new Set();
const upgrades = new Set();
let closing = false;
let closePromise;
const server = createServer((req, res) => {
let url;
try {
url = new URL(req.url, 'http://preview');
if (!req.url.startsWith('/') || req.url.startsWith('//')) throw new Error('invalid path');
decodeURIComponent(url.pathname);
} catch { return reply(res, 400, 'Bad request'); }
const pathname = decodeURIComponent(url.pathname);
if (pathname.startsWith('//')) return reply(res, 400, 'Bad request');
if (!['GET', 'HEAD', 'POST'].includes(req.method)) {
res.setHeader('Allow', 'GET, HEAD, POST'); return reply(res, 405);
}
if (pathname === '/login' || pathname === '/logout' || pathname.startsWith('/artifacts/')) return proxy(req, res, target);
if (req.method !== 'GET' && req.method !== 'HEAD') return reply(res, 405);
authCheck(req, target, (authenticated) => {
if (res.destroyed) return;
if (authenticated === null) return reply(res, 502, 'Authentication upstream unavailable');
if (!authenticated) {
if (req.method === 'GET' && String(req.headers.accept ?? '').includes('text/html') && !pathname.startsWith('/assets/')) {
res.writeHead(302, { ...noCache, Location: `/login?next=${encodeURIComponent(`${url.pathname}${url.search}`)}` });
return res.end();
}
return reply(res, 401, 'Authentication required');
}
staticFile(base, pathname, req, res);
});
});
server.on('connection', (socket) => {
sockets.add(socket);
socket.on('close', () => sockets.delete(socket));
});
server.on('upgrade', (req, socket, head) => {
upgrades.add(socket);
socket.on('close', () => upgrades.delete(socket));
let origin;
try {
if (req.url.split('?')[0] !== '/connect' || !req.headers.host || !req.headers.origin || !req.url.startsWith('/')) throw new Error();
origin = new URL(req.headers.origin);
if (!['http:', 'https:'].includes(origin.protocol) || origin.host.toLowerCase() !== req.headers.host.toLowerCase()) throw new Error();
} catch { return reject(socket, 403); }
authCheck(req, target, (authenticated) => {
if (closing || socket.destroyed) return;
if (authenticated === null) return reject(socket, 502, 'Bad Gateway');
if (!authenticated) return reject(socket, 401, 'Unauthorized');
const connect = target.protocol === 'https:' ? tls.connect : net.connect;
const upstreamSocket = connect({ host: target.hostname, port: Number(target.port || (target.protocol === 'https:' ? 443 : 80)), ...(target.protocol === 'https:' ? { servername: target.hostname } : {}) });
upgrades.add(upstreamSocket);
upstreamSocket.on('close', () => upgrades.delete(upstreamSocket));
upstreamSocket.setTimeout(timeoutMs, () => upstreamSocket.destroy(new Error('upgrade timeout')));
// Bound establishment only. A healthy, idle chat socket stays connected.
upstreamSocket.once('data', () => upstreamSocket.setTimeout(0));
upstreamSocket.once(target.protocol === 'https:' ? 'secureConnect' : 'connect', () => {
const headers = { ...req.headers, host: target.host, origin: target.origin };
const lines = Object.entries(headers).filter(([, value]) => value != null)
.map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(', ') : value}`).join('\r\n');
upstreamSocket.write(`GET ${req.url} HTTP/1.1\r\n${lines}\r\n\r\n`);
if (head.length) upstreamSocket.write(head);
upstreamSocket.pipe(socket);
socket.pipe(upstreamSocket);
});
upstreamSocket.on('error', () => socket.destroy());
socket.on('error', () => upstreamSocket.destroy());
socket.on('close', () => upstreamSocket.destroy());
});
});
await new Promise((resolveListen, rejectListen) => {
server.once('error', rejectListen);
server.listen(port, host, resolveListen);
});
return {
server, port: server.address().port,
close: () => closePromise ??= new Promise((resolveClose, rejectClose) => {
closing = true;
for (const socket of upgrades) socket.destroy();
server.close((error) => error ? rejectClose(error) : resolveClose());
for (const socket of sockets) socket.destroy();
}),
};
}
if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
const args = Object.fromEntries(process.argv.slice(2).reduce((result, value, index, all) => {
if (value.startsWith('--')) result.push([value.slice(2), all[index + 1]]);
return result;
}, []));
start({ root: args.root ?? 'build/web', upstream: process.env.UPSTREAM ?? args.upstream ?? 'http://127.0.0.1:8095', host: args.host ?? '127.0.0.1', port: Number(args.port ?? 8096) })
.then((preview) => console.log(`preview http://${args.host ?? '127.0.0.1'}:${preview.port}`))
.catch((error) => { console.error(error); process.exitCode = 1; });
}