@reclaimprotocol/agent 0.1.23 → 0.1.24

package/skill/user-script.md

@@ -0,0 +1,61 @@
+# User scripts (`jsUserScripts` / `customInjection`)
+
+A provider can inject **plain JavaScript** that runs in the page before every
+page load. Builder stores it as `webSettings.jsUserScripts`; old-devtools stores
+it as `customInjection`. Identical semantics, different field name.
+
+## What the script is for
+
+The verification client **already intercepts the page's network requests
+automatically** — the script does not need to capture, forward, or "claim" them.
+Its job is to get the page into the state where the target request happens,
+using standard browser APIs:
+
+- **Navigate** — `window.location.href = '…'`, `location.assign(…)`, the
+  history API.
+- **Interact** — select an element and `.click()` it, submit a form, dispatch
+  events.
+- **Wait** — poll the DOM until login/MFA completes or content loads, then
+  trigger the next step.
+
+Write it like any page script. It runs before EVERY page load, so keep it
+idempotent, cheap, and guarded against firing at the wrong time.
+
+Both backends run it the same way: before every page load, including before the
+first navigation to `initialUrl`/`loginUrl`.
+
+## `window.Reclaim` — rarely needed
+
+`window.Reclaim` is an OPTIONAL bridge for a handful of edge cases. Most
+providers never touch it, and **it does not do navigation** — use the standard
+browser APIs above for that.
+
+**On the Builder verification client it is installed but INERT.** Both
+`window.Reclaim` and `window.reclaimInterceptor` are injected before every
+document load, so a call won't throw — but the run never drains the
+`Reclaim` outbox and never delivers traffic to
+`reclaimInterceptor.addResponseMiddleware`, so nothing you send is acted on
+and no middleware ever fires. Write Builder-targeted scripts in plain browser
+JS unconditionally, and let the capture loop find the request itself.
+
+Don't reach for it by default. When an edge case genuinely requires it, consult
+the authoritative API surface rather than guessing:
+<https://github.com/reclaimprotocol/provider-web-script-dev/blob/main/src/support/env.d.ts>
+
+## Declaring the requests the script fires
+
+Requests the script triggers beyond the proven one (for example, pagination) are
+declared as `allowedJsRequests` (Builder) / `allowedInjectedRequestData`
+(old-devtools). Same concept, different field name.
+
+⚠️ **Before populating them to gate `verifyProof(proof, { providerId })`**, read
+topic `hash-validation` — the declared `url` is hashed VERBATIM, so a
+session-unique URL there makes `verifyProof` reject every real proof. Leaving
+the field empty is better than populating it wrong.
+
+## Related topics
+
+- `interception` — `injectionType`/`interceptorType`, live interception, and the
+  document-replay flag.
+- `hash-validation` — `bodySniff`, and how `verifyProof({ providerId })` gates
+  on the provider's declared spec.

package/src/authoring/backend.ts

@@ -85,9 +85,10 @@ export interface AuthoringBackend {
 	/** This session's drafts (propose → replay/run_proof). */
 	readonly drafts: DraftStore
 	/** Prove a drafted recipe. Local: attestor SDK (rich claim view). Remote: TEE
-	 *  `/reclaim/prove` (lean, secret-free summary). Returns the environment's
-	 *  display shape. A backend may record the proven recipe internally (e.g.
-	 *  the cloud publish step) — that side effect is the backend's, not ours. */
+	 * `/reclaim/prove` (lean, secret-free summary). Returns the environment's
+	 * display shape. A backend may record the proven recipe internally (for
+	 * example, the cloud publish step) — that side effect is the backend's, not
+	 * ours. */
 	prove(draft: Draft, opts?: ProveOptions): Promise<unknown>
 	/**
 	 * Validate/replay a drafted recipe before proving. Both local and remote
@@ -96,7 +97,7 @@ export interface AuthoringBackend {
 	 * always reflects the real browser session. With `withoutSecrets` it is
 	 * the AUTH-BOUND check: re-issue anonymously (`credentials: 'omit'`, no
 	 * secret headers) and report whether the values are STILL extractable —
-	 * i.e. the endpoint is public. Without it, validate extraction for the
+	 * that is, the endpoint is public. Without it, validate extraction for the
 	 * authenticated request. The shape is environment-specific and passed
 	 * straight through as the tool's result.
 	 */

package/src/authoring/tools.ts

@@ -116,7 +116,10 @@ export function authoringTools(
 		defineTool<Record<string, unknown>>(
 			{
 				name: 'navigate',
-				description: 'Navigate the browser tab to a URL, waiting for load.',
+				description:
+					'Navigate the captured tab to a URL and wait for its load event. '
+					+ 'Returns the URL the tab actually landed on, so you can detect a '
+					+ 'redirect to a login page.',
 				inputSchema: objectSchema(
 					{ url: { type: 'string' }, timeoutMs: { type: 'number' } },
 					['url'],
@@ -144,8 +147,10 @@ export function authoringTools(
 			{
 				name: 'eval_in_page',
 				description:
-					'Evaluate a JavaScript expression in the page and return its value '
-					+ '(use to read the displayed value, check login state, etc.).',
+					'Evaluate a JavaScript expression in the page and return its value. '
+					+ 'Use it to read the value being proven out of the DOM, to check '
+					+ 'login state, or to trigger the target request (for example, '
+					+ '`location.reload()`).',
 				inputSchema: objectSchema(
 					{ expression: { type: 'string' } }, ['expression'],
 				),
@@ -156,8 +161,10 @@ export function authoringTools(
 			{
 				name: 'wait_for_page',
 				description:
-					'Poll a JavaScript expression until it is truthy or the timeout '
-					+ 'elapses (e.g. wait for the user to finish logging in).',
+					'Poll a JavaScript expression once a second until it is truthy or '
+					+ 'the timeout elapses. Use it to wait for content to appear. To '
+					+ 'wait for a login, use wait_for_login instead — page JavaScript '
+					+ 'cannot see the httpOnly session cookie.',
 				inputSchema: objectSchema(
 					{ expression: { type: 'string' }, timeoutMs: { type: 'number' } },
 					['expression'],
@@ -183,26 +190,18 @@ export function authoringTools(
 			{
 				name: 'test_user_script',
 				description:
-					'Dry-run a USER SCRIPT — the same thing as the `jsUserScripts` / '
-					+ '`customInjection` field on a published provider: plain browser '
-					+ 'JS that runs before every page load, used to drive navigation '
-					+ 'for data gated behind login/routing — in the LIVE attached tab, '
-					+ 'BEFORE publishing. Installs `script` via CDP so it runs on the '
-					+ 'next navigation exactly like the real field would, then reports '
-					+ 'whether it ran and any errors it threw. Catches bugs (e.g. a '
-					+ 'listener registered with setTimeout that never fires because the '
-					+ "page was already past 'load' by the time it ran) before they "
-					+ 'surface in a real end-user session instead of after. If '
-					+ '`navigateUrl` is given, navigates there after installing, then '
-					+ 'removes the script again once the result is read (self-cleaning '
-					+ '— safe to call repeatedly). Without `navigateUrl` the script is '
-					+ 'left installed for you to navigate yourself (any way you like) '
-					+ 'then re-call this tool, or read '
-					+ '`window.__reclaimUserScriptResult` via eval_in_page — in that '
-					+ 'manual mode it is NOT auto-removed and keeps running on every '
-					+ 'later navigation until a follow-up call with `navigateUrl` '
-					+ 'removes it, so avoid stacking several manual-mode calls in a '
-					+ 'row.',
+					'Dry-run a USER SCRIPT (the `jsUserScripts` / `customInjection` '
+					+ 'field) in the LIVE attached tab, BEFORE publishing. Installs '
+					+ '`script` via CDP so it runs on the next navigation exactly as '
+					+ 'the real field would, then reports whether it ran and what it '
+					+ 'threw. With `navigateUrl`, it navigates there and removes the '
+					+ 'script once the result is read — self-cleaning, safe to repeat. '
+					+ 'WITHOUT `navigateUrl` the script stays installed (navigate '
+					+ 'yourself, then re-call this tool or read '
+					+ '`window.__reclaimUserScriptResult` via eval_in_page) and keeps '
+					+ 'running on every later navigation until a call WITH '
+					+ '`navigateUrl` removes it — so don\'t stack manual-mode calls. '
+					+ 'Guide: how_it_works({ topic: "user-script" }).',
 				inputSchema: objectSchema(
 					{
 						script: { type: 'string' },
@@ -246,8 +245,9 @@ export function authoringTools(
 							'Installed for the NEXT navigation only — it did not run on '
 							+ 'the current page, and stays installed (runs on every later '
 							+ 'navigation too) until a follow-up call with navigateUrl '
-							+ 'removes it. Navigate now (e.g. the navigate tool), then read '
-							+ 'window.__reclaimUserScriptResult via eval_in_page, or call '
+							+ 'removes it. Navigate now (for example, with the navigate '
+							+ 'tool), then read window.__reclaimUserScriptResult via '
+							+ 'eval_in_page, or call '
 							+ 'test_user_script again with navigateUrl.',
 					}
 				}
@@ -298,7 +298,8 @@ export function authoringTools(
 					'List the NAMES of cookies currently set for the page (values are '
 					+ 'NEVER returned). The most reliable, language- and DOM-independent '
 					+ 'login signal: after the user logs in, an auth/session cookie '
-					+ 'appears (e.g. session/sid/token/auth/jwt/_user/logged_in). '
+					+ 'appears (for example, session, sid, token, auth, jwt, _user, '
+					+ 'logged_in). '
 					+ 'Includes httpOnly cookies the page JS cannot see.',
 				inputSchema: objectSchema({}),
 			},
@@ -354,8 +355,8 @@ export function authoringTools(
 					'userFirstVisit', 'cf_', '_dd_', 'bcookie', 'bscookie', 'lidc',
 				].join('|') + ')', 'i')
 				// A real session/auth cookie name. Deliberately NOT bare `token` — a
-				// challenge/CSRF token (e.g. LinkedIn `chp_token`) contains it and is
-				// set BEFORE auth completes. Any new httpOnly cookie is also a
+				// challenge/CSRF token (for example, LinkedIn `chp_token`) contains it
+				// and is set BEFORE auth completes. Any new httpOnly cookie is also a
 				// candidate (server-set session cookies are usually httpOnly).
 				const SESSION = /sess|sid|jwt|_session|auth|logged.?in|remember|li_at/i
 				// Auth/challenge URL paths — while the page is still on one, login is

package/src/cdp/capture-engine.ts

@@ -89,9 +89,10 @@ export function isStaticAsset(url: string): boolean {
 }
 
 /** Response Content-Types for static assets. The URL-extension filter misses
- *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
- *  MIME at response time. `text/html`, `application/json`, and `text/plain`
- *  are NOT here — those are the document/API shapes recipes match. */
+ *  extension-less bundler/CDN URLs (for example, `/assets/3b8f1c`), so we also
+ *  drop by MIME at response time. `text/html`, `application/json`, and
+ *  `text/plain` are NOT here — those are the document/API shapes recipes
+ *  match. */
 const STATIC_ASSET_MIME_EXACT = new Set([
 	'text/css',
 	'application/javascript', 'text/javascript', 'application/x-javascript',
@@ -272,9 +273,9 @@ export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
 	function onResponseReceived(p: ResponseReceivedLike) {
 		const f = inFlight.get(p.requestId)
 		if(!f) {
-			// No in-flight entry → the request was skipped (e.g. a static asset)
-			// or never seen. Discard any buffered response extra-info so a skipped
-			// asset can't leave a dangling entry.
+			// No in-flight entry → the request was skipped (for example, a static
+			// asset) or never seen. Discard any buffered response extra-info so a
+			// skipped asset can't leave a dangling entry.
 			pendingResponseExtra.delete(p.requestId)
 			return
 		}
@@ -339,7 +340,7 @@ export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
 			r.finishedAt = Date.now()
 		} catch{
 			// Body might be unavailable for
-			// some content-types (e.g. websocket). Skip.
+			// some content-types (for example, websocket). Skip.
 		}
 	}
 }

package/src/cdp/client.ts

@@ -30,6 +30,14 @@ interface CdpTabEventMap {
 		headers: Record<string, string>
 	}
 	'Network.loadingFinished': { requestId: string }
+	/** Screencast frames, for the live view (`live/viewer.ts`). Each carries a
+	 *  `sessionId` that MUST be acked with `Page.screencastFrameAck`, or CDP
+	 *  stops sending. */
+	'Page.screencastFrame': {
+		data: string
+		sessionId: number
+		metadata?: { timestamp?: number }
+	}
 }
 
 export interface CdpTabClient {

package/src/cdp/geo.ts

@@ -0,0 +1,52 @@
+/**
+ * Country-code suggestion for a country-routed Popcorn browser session, when
+ * the caller doesn't name one explicitly. `attach_browser` returns this as the
+ * suggestion to confirm with the developer — the calling machine's own
+ * public-IP country, resolved the same way reclaim-portal's `ip-geolocation`
+ * util does.
+ */
+import { LOGGER } from '../logger.ts'
+
+export interface IpGeolocation {
+	countryCode: string
+	country?: string
+	region?: string
+	city?: string
+}
+
+const IPINFO_URL = 'https://ipinfo.io/json'
+const FALLBACK_COUNTRY_CODE = 'US'
+
+/** Resolve the calling machine's own public-IP country. Never throws — a
+ *  lookup failure just loses the "best guess" convenience, falling back to
+ *  {@link FALLBACK_COUNTRY_CODE} rather than blocking applying a proxy. */
+export async function suggestCountryFromIp(
+	fetchImpl: typeof fetch = fetch,
+): Promise<IpGeolocation> {
+	try {
+		const res = await fetchImpl(IPINFO_URL)
+		if(!res.ok) {
+			throw new Error(`ipinfo.io ${res.status}`)
+		}
+
+		const data = await res.json() as {
+			country?: string
+			region?: string
+			city?: string
+		}
+		const countryCode = data.country?.toUpperCase()
+		if(!countryCode) {
+			throw new Error('ipinfo.io response had no country')
+		}
+
+		return {
+			countryCode,
+			country: data.country,
+			region: data.region,
+			city: data.city,
+		}
+	} catch(err) {
+		LOGGER.warn({ err }, 'suggestCountryFromIp failed; using fallback')
+		return { countryCode: FALLBACK_COUNTRY_CODE }
+	}
+}

package/src/cdp/index.ts

@@ -4,3 +4,4 @@
 export * from './capture-engine.ts'
 export { startCapture } from './capture.ts'
 export { BodyStore } from './eviction.ts'
+export * from './geo.ts'

package/src/consts.ts

@@ -224,3 +224,4 @@ export function oldEthUid(): string | undefined {
 export function oldLoginUrl(): string | undefined {
 	return process.env.RECLAIM_OLD_LOGIN_URL
 }
+

package/src/live/cloudflared.ts

@@ -0,0 +1,348 @@
+/**
+ * Finding — and if necessary fetching — the `cloudflared` binary the live view
+ * tunnels through.
+ *
+ * Resolution order, first hit wins:
+ *  1. `RECLAIM_CLOUDFLARED_PATH`, for an air-gapped box or a corporate mirror.
+ *  2. `cloudflared` on PATH — someone who installed it with a package manager
+ *     keeps their own copy, updated their way.
+ *  3. `~/.reclaim/bin/cloudflared`, ours from a previous run.
+ *  4. Download it from Cloudflare's GitHub releases into `~/.reclaim/bin`.
+ *
+ * Step 4 happens on FIRST USE, never at install time. The npm `cloudflared`
+ * package would have done this for us, but its postinstall pulls a ~38 MB
+ * binary on every `npm install` of this package — a cost paid by everyone who
+ * never shares a live view. `run_proof`'s ZK circuits are deferred for exactly
+ * the same reason.
+ *
+ * Every download is SHA-256 verified. Cloudflare publishes a checksum table in
+ * the release notes (not as a release asset), so we read the release metadata
+ * first, take the digest for our asset, and refuse to install anything that
+ * doesn't match. The release TAG from that same response is used to build the
+ * download URL, so the checksum and the bytes always come from one release —
+ * `/latest/download/` could otherwise hand us a newer build than the table we
+ * just read.
+ *
+ * Verification is not optional: this writes an executable to the developer's
+ * machine. If the checksum can't be established, we fail rather than install.
+ * The escape hatch is to install cloudflared yourself — step 2 then wins and
+ * nothing is downloaded.
+ */
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+	chmod,
+	mkdir,
+	rename,
+	rm,
+	stat,
+	writeFile
+} from 'node:fs/promises'
+import { arch, platform } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { gunzipSync } from 'node:zlib'
+import { LOGGER } from '../logger.ts'
+import { reclaimHomeDirPath } from '../paths.ts'
+
+const execFileAsync = promisify(execFile)
+
+/** Release metadata: the tag to pin to, and the checksum table in its notes. */
+const LATEST_RELEASE_API =
+	'https://api.github.com/repos/cloudflare/cloudflared/releases/latest'
+/** Asset downloads, keyed by the tag we read the checksums from. */
+function releaseDownloadUrl(tag: string, asset: string): string {
+	return 'https://github.com/cloudflare/cloudflared/releases/download'
+		+ `/${tag}/${asset}`
+}
+
+/** Give up on a slow or stalled download rather than hanging the tool. */
+const DOWNLOAD_TIMEOUT_MS = 180_000
+
+export interface CloudflaredBinary {
+	/** Path to run. */
+	path: string
+	/** How it was found — surfaced so the caller can tell the developer when a
+	 *  download just happened on their machine. */
+	source: 'env' | 'path' | 'cached' | 'downloaded'
+}
+
+/**
+ * The release asset for this machine, or `undefined` when Cloudflare ships no
+ * build for it. macOS assets are gzipped tarballs; everything else is the bare
+ * executable.
+ */
+function assetFor(
+	os: string,
+	cpu: string,
+): { name: string, tarball: boolean } | undefined {
+	if(os === 'darwin') {
+		const suffix = cpu === 'arm64' ? 'arm64' : 'amd64'
+		return { name: `cloudflared-darwin-${suffix}.tgz`, tarball: true }
+	}
+
+	if(os === 'linux') {
+		const map: Record<string, string> = {
+			x64: 'amd64',
+			arm64: 'arm64',
+			arm: 'arm',
+			ia32: '386',
+		}
+		const suffix = map[cpu]
+		return suffix
+			? { name: `cloudflared-linux-${suffix}`, tarball: false }
+			: undefined
+	}
+
+	if(os === 'win32') {
+		const suffix = cpu === 'ia32' ? '386' : 'amd64'
+		return { name: `cloudflared-windows-${suffix}.exe`, tarball: false }
+	}
+
+	return undefined
+}
+
+/** Our install location. Kept beside the other `~/.reclaim` caches. */
+function cachedBinaryPath(): string {
+	const name = platform() === 'win32' ? 'cloudflared.exe' : 'cloudflared'
+	return join(reclaimHomeDirPath(), 'bin', name)
+}
+
+/** Whether `command` runs. Used both for a PATH probe and to smoke-test a
+ *  freshly downloaded binary before we hand it back. */
+async function runsOk(command: string): Promise<boolean> {
+	try {
+		await execFileAsync(command, ['--version'], { timeout: 15_000 })
+		return true
+	} catch{
+		return false
+	}
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await stat(path)
+		return true
+	} catch{
+		return false
+	}
+}
+
+/**
+ * Resolve a runnable cloudflared, downloading one only if `autoInstall` allows
+ * it and nothing else turned up. Throws with an actionable message when this
+ * platform has no build, or the download fails.
+ */
+export async function resolveCloudflared(
+	{ autoInstall = true }: { autoInstall?: boolean } = {},
+): Promise<CloudflaredBinary> {
+	const override = process.env.RECLAIM_CLOUDFLARED_PATH?.trim()
+	if(override) {
+		if(!await runsOk(override)) {
+			throw new Error(
+				`RECLAIM_CLOUDFLARED_PATH is set to "${override}", but that did not `
+				+ 'run. Point it at a working cloudflared binary, or unset it to let '
+				+ 'the agent find one.',
+			)
+		}
+
+		return { path: override, source: 'env' }
+	}
+
+	if(await runsOk('cloudflared')) {
+		return { path: 'cloudflared', source: 'path' }
+	}
+
+	const cached = cachedBinaryPath()
+	if(await exists(cached) && await runsOk(cached)) {
+		return { path: cached, source: 'cached' }
+	}
+
+	if(!autoInstall) {
+		throw new Error(
+			'cloudflared is not installed. Install it (macOS: `brew install '
+			+ 'cloudflared`; other platforms: https://developers.cloudflare.com/'
+			+ 'cloudflare-one/connections/connect-networks/downloads/), or allow '
+			+ 'the agent to fetch it.',
+		)
+	}
+
+	await install(cached)
+	return { path: cached, source: 'downloaded' }
+}
+
+/** `cloudflared-linux-amd64: <64 hex>` lines inside the notes' fenced block. */
+const CHECKSUM_LINE = /^\s*(\S+):\s*([a-f0-9]{64})\s*$/gim
+
+/**
+ * The current release's tag and its published SHA-256 table.
+ *
+ * Both come from one response on purpose: pinning the download to this tag is
+ * what makes the digest meaningful.
+ */
+async function fetchRelease(): Promise<{
+	tag: string
+	checksums: Map<string, string>
+}> {
+	const res = await fetch(LATEST_RELEASE_API, {
+		headers: {
+			accept: 'application/vnd.github+json',
+			'user-agent': '@reclaimprotocol/agent',
+		},
+		signal: AbortSignal.timeout(30_000),
+	})
+	if(!res.ok) {
+		throw new Error(
+			`Could not read cloudflared release metadata: ${res.status} `
+			+ `${res.statusText}. Needed to verify the download's checksum. `
+			+ 'Install cloudflared yourself, or set RECLAIM_CLOUDFLARED_PATH.',
+		)
+	}
+
+	const release = await res.json() as { tag_name?: string, body?: string }
+	const tag = release.tag_name
+	if(!tag) {
+		throw new Error('cloudflared release metadata carried no tag.')
+	}
+
+	const checksums = new Map<string, string>()
+	for(const match of (release.body ?? '').matchAll(CHECKSUM_LINE)) {
+		checksums.set(match[1], match[2].toLowerCase())
+	}
+
+	return { tag, checksums }
+}
+
+/** Download the release asset for this machine to `target`, verified. */
+async function install(target: string): Promise<void> {
+	const asset = assetFor(platform(), arch())
+	if(!asset) {
+		throw new Error(
+			`Cloudflare publishes no cloudflared build for ${platform()}/${arch()}. `
+			+ 'Install it another way and set RECLAIM_CLOUDFLARED_PATH, or use '
+			+ '`attach_browser` in builder mode, whose Popcorn browser returns a '
+			+ 'hosted liveViewUrl and needs no tunnel.',
+		)
+	}
+
+	// Read the checksum table BEFORE downloading, and pin the download to the
+	// tag it came from.
+	const { tag, checksums } = await fetchRelease()
+	const expected = checksums.get(asset.name)
+	if(!expected) {
+		throw new Error(
+			`cloudflared release ${tag} publishes no SHA-256 for ${asset.name}, so `
+			+ 'the download cannot be verified. Refusing to install an unverified '
+			+ 'binary. Install cloudflared yourself, or set '
+			+ 'RECLAIM_CLOUDFLARED_PATH.',
+		)
+	}
+
+	const url = releaseDownloadUrl(tag, asset.name)
+	LOGGER.info({ url, target, tag }, 'cloudflared: downloading (first use)')
+	const res = await fetch(url, {
+		redirect: 'follow',
+		signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+	})
+	if(!res.ok) {
+		throw new Error(
+			`Downloading cloudflared failed: ${res.status} ${res.statusText} `
+			+ `from ${url}. Install it manually and retry, or set `
+			+ 'RECLAIM_CLOUDFLARED_PATH.',
+		)
+	}
+
+	const downloaded = Buffer.from(await res.arrayBuffer())
+
+	// The macOS assets are tarballs, so unpack before hashing. Unpacked
+	// in-process rather than by shelling out to `tar`: that would add a
+	// dependency on something being on PATH, which is exactly the assumption
+	// this module exists to stop making.
+	//
+	// This ordering is not incidental. Cloudflare's table lists a digest for
+	// `cloudflared-darwin-arm64.tgz`, but that digest is of the BINARY INSIDE,
+	// not of the tarball (verified against a real release: the tarball hashes
+	// to something else entirely, and the binary self-reports the published
+	// value as its own checksum). The linux and windows entries, which ship a
+	// bare executable, do match the downloaded file. Hashing the payload we are
+	// about to write covers both, and is the stronger invariant anyway: what
+	// gets verified is what gets executed.
+	const payload = asset.tarball
+		? readTarEntry(gunzipSync(downloaded), 'cloudflared')
+		: downloaded
+
+	const actual = createHash('sha256').update(payload).digest('hex')
+	if(actual !== expected) {
+		// Nothing is written to disk on a mismatch — not even a partial file.
+		throw new Error(
+			`cloudflared checksum mismatch for ${asset.name} (release ${tag}). `
+			+ `Expected ${expected}, got ${actual}. The download was discarded. `
+			+ 'Retry; if it persists, install cloudflared yourself and set '
+			+ 'RECLAIM_CLOUDFLARED_PATH.',
+		)
+	}
+
+	LOGGER.info({ asset: asset.name, tag }, 'cloudflared: checksum verified')
+
+	// Write beside the target, then rename: a half-written or unverified
+	// binary is never left at a path a later run would trust.
+	await mkdir(join(target, '..'), { recursive: true })
+	const partial = `${target}.download`
+	await writeFile(partial, payload)
+	await rename(partial, target)
+
+	if(platform() !== 'win32') {
+		await chmod(target, 0o755)
+	}
+
+	if(!await runsOk(target)) {
+		await rm(target, { force: true })
+		throw new Error(
+			'Downloaded cloudflared, but it did not run. Removed it. Install '
+			+ 'cloudflared manually and retry.',
+		)
+	}
+
+	LOGGER.info({ target }, 'cloudflared: installed')
+}
+
+/** A tar header block is 512 bytes, and so is every data block. */
+const TAR_BLOCK = 512
+
+/**
+ * Pull one file out of an uncompressed tar archive.
+ *
+ * Only as much of the format as this needs: walk the 512-byte headers, read
+ * each entry's name and octal size, and return the payload of the first
+ * regular file whose basename matches. Cloudflare's macOS tarball holds a
+ * single binary, so there is nothing more to handle.
+ */
+function readTarEntry(tar: Buffer, wanted: string): Buffer {
+	let offset = 0
+	while(offset + TAR_BLOCK <= tar.length) {
+		const header = tar.subarray(offset, offset + TAR_BLOCK)
+		const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '')
+		if(!name) {
+			break // two zero blocks mark the end of the archive
+		}
+
+		const size = parseInt(
+			header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim(),
+			8,
+		) || 0
+		const type = header.subarray(156, 157).toString('utf8')
+		const dataStart = offset + TAR_BLOCK
+		if((type === '0' || type === '\0') && name.split('/').pop() === wanted) {
+			return tar.subarray(dataStart, dataStart + size)
+		}
+
+		// Data is padded up to the next block boundary.
+		offset = dataStart + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK
+	}
+
+	throw new Error(
+		`The cloudflared archive did not contain "${wanted}". Cloudflare may `
+		+ 'have changed its release layout — install cloudflared manually and '
+		+ 'set RECLAIM_CLOUDFLARED_PATH.',
+	)
+}