Skip to content

Commit 8be76fc

Browse files
fix(cli): pin website capture connections to public peers (#5668)
* fix(cli): pin website capture connections to public peers * style(cli): keep capture policy explanations within comment limits * test(cli): separate case-sensitive dotenv assertions * fix(cli): honor capture deadlines and bootstrap isolation * chore: trim redundant capture dotenv comments * fix(capture): join signal cleanup and guard leading options * docs(capture): trim redundant cleanup comment
1 parent 490ecaf commit 8be76fc

29 files changed

Lines changed: 1869 additions & 135 deletions

‎docs/packages/cli.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,25 @@ npx hyperframes capture https://example.com --json
207207
Fonts: sohne-var
208208
```
209209

210+
Website capture accepts public HTTP(S) destinations without URL credentials.
211+
Browser traffic goes through a per-capture proxy, and asset downloads use the
212+
same checked-address policy. Each connection uses a validated numeric IPv4
213+
address; redirects and later requests are checked again. Private, loopback,
214+
link-local and special-use addresses are refused. IPv6-only sites are currently
215+
unsupported. Plain WebSocket upgrades are refused; slow or refused resources
216+
may be absent from the capture.
217+
218+
Capture uses a temporary browser profile with non-proxied WebRTC UDP disabled.
219+
The profile and proxy are removed when the browser closes. The Chromium sandbox
220+
is retained on macOS and Windows; Linux retains the container compatibility
221+
exception.
222+
223+
Ancestor `.env` files can supply the supported vision API keys, models, Vertex
224+
credentials/location and vision timeout. They cannot change the browser path,
225+
executable discovery, TLS, proxy or process runtime settings. Set
226+
`HYPERFRAMES_NO_CAPTURE_DOTENV=1` in the calling environment to skip these files.
227+
An inherited `HYPERFRAMES_BROWSER_PATH` still selects a browser.
228+
210229
`Dropped` is how many assets the page referenced that are **not** in the
211230
folder, and why. It is printed only when it is non-zero, and `--json` always
212231
carries it as a `dropped` object. Without it, a capture of a spare page and a

‎packages/cli/src/browser/launch.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ export class BrowserCleanupError extends AggregateError {}
1313
const browsers = new Set<Browser>();
1414
const closing = new WeakMap<Browser, Promise<void>>();
1515
const pending = new Map<Promise<Browser>, AbortController>();
16+
const sessionCleanups = new Set<() => Promise<void>>();
1617
const CLOSE_GRACE_MS = 1_000;
1718
const EXIT_POLL_MS = 50;
1819
let listening = false;
@@ -102,7 +103,17 @@ export async function launchManagedBrowser(
102103
async function closeManagedBrowsers(): Promise<void> {
103104
for (const abort of pending.values()) abort.abort();
104105
await Promise.allSettled(pending.keys());
105-
await Promise.all([...browsers].map(closeManagedBrowser));
106+
const results = await Promise.allSettled([...browsers].map(closeManagedBrowser));
107+
results.push(...(await Promise.allSettled([...sessionCleanups].map((cleanup) => cleanup()))));
108+
const errors = results.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
109+
if (errors.length) throw new AggregateError(errors, "Browser session shutdown failed.");
110+
}
111+
112+
export function registerBrowserSessionCleanup(cleanup: () => Promise<void>): () => void {
113+
if (shutdown) throw new Error("The CLI is stopping; no browser session can start.");
114+
ownSignals();
115+
sessionCleanups.add(cleanup);
116+
return () => sessionCleanups.delete(cleanup);
106117
}
107118

108119
/** Manual teardown and signal teardown share the same bounded close, exactly once. */

‎packages/cli/src/capture/assetCataloger.test.ts‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
import { describe, expect, it } from "vitest";
1+
import { afterEach, describe, expect, it, vi } from "vitest";
2+
import { publicRequest } from "./publicNetwork.js";
3+
4+
vi.mock("./publicNetwork.js", () => ({ publicRequest: vi.fn() }));
5+
afterEach(() => vi.mocked(publicRequest).mockReset());
26
import { annotateGifAssetMetadata, type CatalogedAsset } from "./assetCataloger.js";
37

48
function u16(value: number): number[] {
@@ -102,3 +106,40 @@ describe("annotateGifAssetMetadata", () => {
102106
expect(annotated[1]?.notes).toBe("hero");
103107
});
104108
});
109+
110+
it("uses safe redirects for GIF metadata and never follows a private redirect", async () => {
111+
const assets: CatalogedAsset[] = [
112+
{ url: "https://cdn.example/animated.gif", type: "Image", contexts: ["img[src]"] },
113+
{ url: "https://cdn.example/private.gif", type: "Image", contexts: ["img[src]"] },
114+
];
115+
const canceled = vi.fn();
116+
vi.mocked(publicRequest).mockImplementation(async (url) => {
117+
if (String(url).endsWith("animated.gif"))
118+
return new Response(null, {
119+
status: 302,
120+
headers: { location: "https://images.example/final.gif" },
121+
});
122+
if (String(url).endsWith("private.gif"))
123+
return new Response(new ReadableStream({ cancel: canceled }), {
124+
status: 302,
125+
headers: { location: "http://127.0.0.1/private.gif" },
126+
});
127+
if (String(url) === "https://images.example/final.gif")
128+
return new Response(new Uint8Array(gif([...frame(5), ...frame(15)], 0)));
129+
throw new Error(`Unexpected request: ${url}`);
130+
});
131+
const annotated = await annotateGifAssetMetadata(assets);
132+
expect(annotated[0]?.notes).toBe("animated GIF: 2 frames, 0.200s, loops forever");
133+
expect(annotated[1]?.notes).toBeUndefined();
134+
expect(
135+
vi
136+
.mocked(publicRequest)
137+
.mock.calls.map(([url]) => String(url))
138+
.sort(),
139+
).toEqual([
140+
"https://cdn.example/animated.gif",
141+
"https://cdn.example/private.gif",
142+
"https://images.example/final.gif",
143+
]);
144+
expect(canceled).toHaveBeenCalledOnce();
145+
});

‎packages/cli/src/capture/assetCataloger.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111

1212
import type { Page } from "puppeteer-core";
1313
import { parseAnimatedGifMetadata } from "@hyperframes/core";
14+
import { safeFetch } from "./assetDownloader.js";
15+
import { readBoundedResponse } from "./readBoundedResponse.js";
1416

1517
export interface CatalogedAsset {
1618
url: string;
@@ -276,11 +278,12 @@ function appendNote(existing: string | undefined, note: string): string {
276278

277279
async function readAssetBytes(url: string): Promise<Uint8Array | null> {
278280
try {
279-
const response = await fetch(url, { signal: AbortSignal.timeout(15_000) });
280-
if (!response.ok) return null;
281-
const contentLength = response.headers.get("content-length");
282-
if (contentLength && Number.parseInt(contentLength, 10) > 25 * 1024 * 1024) return null;
283-
return new Uint8Array(await response.arrayBuffer());
281+
const response = await safeFetch(url, { signal: AbortSignal.timeout(15_000) });
282+
if (!response?.ok) {
283+
await response?.body?.cancel().catch(() => {});
284+
return null;
285+
}
286+
return await readBoundedResponse(response, 25 * 1024 * 1024);
284287
} catch {
285288
return null;
286289
}

0 commit comments

Comments
 (0)