diff --git a/app/notes/F5.md b/app/notes/F5.md new file mode 100644 index 00000000..f4383c02 --- /dev/null +++ b/app/notes/F5.md @@ -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. diff --git a/app/test/tool/preview.test.mjs b/app/test/tool/preview.test.mjs new file mode 100644 index 00000000..3c6d6630 --- /dev/null +++ b/app/test/tool/preview.test.mjs @@ -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); +}); diff --git a/app/tool/preview/README.md b/app/tool/preview/README.md new file mode 100644 index 00000000..8dcfa751 --- /dev/null +++ b/app/tool/preview/README.md @@ -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. diff --git a/app/tool/preview/server.mjs b/app/tool/preview/server.mjs new file mode 100644 index 00000000..abc8e55e --- /dev/null +++ b/app/tool/preview/server.mjs @@ -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; }); +}