@hienlh/ppm 0.18.12 → 0.18.14

package/src/services/file-watcher.service.ts

@@ -2,17 +2,32 @@ import { WatchTree } from "./file-watcher/watch-tree.ts";
 
 const DEBOUNCE_MS = 500;
 /**
- * Directory budgets. One covered directory costs one inotify watch on Linux, and
- * the machine-wide default ceiling is 524288 shared with every other process, so
- * PPM stays well inside it even with several projects watched at once.
+ * Directory budgets. These bound the directories PPM *covers*, which is not the same as
+ * the inotify watches it holds: measured on Linux, watching a directory costs one
+ * descriptor for it plus one for every file inside — 4 directories holding 600 files
+ * come to 604, recursive and non-recursive alike. So a directory cap bounds handles and
+ * walk cost, not descriptors; what keeps PPM inside the machine-wide 524288 ceiling is
+ * never registering `node_modules` in the first place.
  *
- * The per-project cap is hard. The total is best-effort: a native recursive watch
- * picks up directories created later without telling us, so exact accounting is not
- * possible — the worst case is a few projects at their own cap, still ~4% of the
- * kernel ceiling.
+ * The per-project cap is hard. The total is best-effort: a tree keeps growing after
+ * it starts, through `syncChildDir` -> `cover`, up to its own `maxDirs` — and on
+ * Windows/macOS a recursive handle covers directories created later without telling
+ * us either. So projects can add up past the total.
+ *
+ * A pnpm monorepo runs past 8000 directories on its own — the cap then silently stops
+ * watching the rest of the tree, which reads as a file change that never arrives.
+ * 12000 covers those with room to spare.
+ */
+const MAX_DIRS_PER_PROJECT = 12_000;
+const MAX_DIRS_TOTAL = 30_000;
+/**
+ * Floor on what a project is handed. Dividing the total down to nothing is worse than
+ * overshooting it: at 12000 per project the budgets ran 12000 -> 8000 -> **0**, and a
+ * project watching zero directories reports no changes at all — the same "file change
+ * that never arrives", total instead of partial, and indistinguishable from a broken
+ * watcher. A late project now gets a small budget and the truncation warning instead.
  */
-const MAX_DIRS_PER_PROJECT = 8_000;
-const MAX_DIRS_TOTAL = 20_000;
+const MIN_DIRS_PER_PROJECT = 1_000;
 
 type ChangeCallback = (projectName: string, path: string) => void;
 
@@ -64,7 +79,10 @@ export function startWatching(projectName: string, projectPath: string): void {
     return;
   }
 
-  const maxDirs = Math.max(0, Math.min(MAX_DIRS_PER_PROJECT, MAX_DIRS_TOTAL - totalCoveredDirs()));
+  const maxDirs = Math.max(
+    MIN_DIRS_PER_PROJECT,
+    Math.min(MAX_DIRS_PER_PROJECT, MAX_DIRS_TOTAL - totalCoveredDirs()),
+  );
   const entry: WatchEntry = {
     tree: new WatchTree({
       root: projectPath,

package/src/services/fs-credential-path-guard.ts

@@ -0,0 +1,103 @@
+import { resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { getPpmDir } from "./ppm-dir.ts";
+import { getUploadsDir } from "./chat-upload-storage.service.ts";
+import { realPathOrSelf } from "./fs-ops/fs-real-path.ts";
+
+/**
+ * Every path a generic filesystem route (read, write, copy, move, upload,
+ * trash…) must refuse because it holds credential material: the PPM config
+ * DB (provider keys, auth token) and `~/.cloudflared` (the Cloudflare login
+ * cert). Split out of `fs-path-guard.service.ts` so this one seam — "is this
+ * a credential path" — stays a single file instead of growing alongside the
+ * platform-allowlist and protected-root logic that lives there.
+ */
+
+/** Case-insensitive prefix test on Windows/macOS-style paths. */
+function isInside(child: string, parent: string): boolean {
+  const norm = (p: string) => (process.platform === "win32" ? p.toLowerCase() : p);
+  const c = norm(child);
+  const p = norm(parent);
+  return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+
+/** True when the path is the PPM directory or anything inside it. */
+export function isPpmDirPath(resolved: string): boolean {
+  return isInside(resolved, getPpmDir());
+}
+
+/**
+ * Chat attachments the user uploaded through the UI. They sit under the PPM
+ * dir so chat history keeps resolving them across reboots, but they are
+ * ordinary user content, not credential material: the transcript has to render
+ * the very image the assistant just read back from that directory.
+ */
+export function isChatUploadPath(resolved: string): boolean {
+  return isInside(resolved, getUploadsDir());
+}
+
+/**
+ * True when the path is `~/.cloudflared` or anything inside it. Real
+ * `homedir()` is a deliberate exception to the getPpmDir()-only rule (see
+ * CLAUDE.md "PPM Directory"): `cloudflared`, not PPM, decides this location,
+ * and it holds `cert.pem` — an account-level Cloudflare login credential that
+ * must never be servable through a generic file route. `isInside` is a
+ * prefix match against this exact resolved path, not a substring test, so an
+ * unrelated folder that merely contains ".cloudflared" as a path segment
+ * elsewhere does not match.
+ */
+export function isCloudflaredDirPath(resolved: string): boolean {
+  return isInside(resolved, resolve(homedir(), ".cloudflared"));
+}
+
+/** True when the path holds credential material a generic file route must never serve or relocate. */
+export function isCredentialPath(resolved: string): boolean {
+  return isPpmDirPath(resolved) || isCloudflaredDirPath(resolved);
+}
+
+/**
+ * Refuse the PPM directory subtree and `~/.cloudflared` on read-style doors.
+ * The former stores the config database with provider credentials and auth
+ * tokens; the latter stores the Cloudflare login cert. Neither may be
+ * downloadable through a generic file route.
+ *
+ * Chat uploads are the one exception, and only for the PPM-dir branch — chat
+ * uploads always live under `getPpmDir()`, never under `~/.cloudflared`, so
+ * the exception is a no-op for the cloudflared branch. Every caller applies
+ * this to the requested path *and* to its real path, so a symlink parked in
+ * the uploads directory still fails on the second call and cannot reach the
+ * rest of the PPM dir through the exception, and a symlink pointing at
+ * `~/.cloudflared/cert.pem` fails the same way.
+ */
+export function assertNotPpmDir(resolved: string): void {
+  if (isCredentialPath(resolved) && !isChatUploadPath(resolved)) {
+    throw Object.assign(new Error("Access denied"), { status: 403, code: "EDENIED" });
+  }
+}
+
+/**
+ * Refuse operations that would relocate a credential directory's contents
+ * anywhere else — copy, move, rename, upload-over, trash. Reading a
+ * credential path is already blocked by `assertNotPpmDir`, so without this a
+ * copy to a public path followed by an ordinary read would still hand out
+ * the PPM config DB or the Cloudflare login cert; every write/transfer door
+ * in `fs-ops/` calls this on both the source and the destination.
+ */
+export function assertNotPpmSubtree(candidate: string): void {
+  if (isCredentialPath(candidate)) {
+    throw Object.assign(new Error(`Refusing to operate on a credential directory: ${candidate}`), {
+      status: 403,
+      code: "EPROTECTED",
+    });
+  }
+}
+
+/**
+ * Same refusal, applied to the real path as well. A path that does not exist
+ * yet is still resolved through its parents, so a symlinked directory cannot
+ * be used to reach — or create something inside — a credential directory.
+ */
+export async function assertNotPpmSubtreeDeep(candidate: string): Promise<void> {
+  assertNotPpmSubtree(candidate);
+  assertNotPpmSubtree(await realPathOrSelf(candidate));
+}

package/src/services/fs-path-guard.service.ts

@@ -1,14 +1,26 @@
-import { resolve, sep } from "node:path";
+import { resolve } from "node:path";
 import { lstat, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { getPpmDir } from "./ppm-dir.ts";
-import { getUploadsDir } from "./chat-upload-storage.service.ts";
 import { realPathOrSelf, realPathOrSelfSync } from "./fs-ops/fs-real-path.ts";
 
 // Re-exported so callers reach both the guards and the resolver they build on
 // through one import.
 export { realPathOrSelf, realPathOrSelfSync };
 
+// The credential-path predicates (PPM dir + ~/.cloudflared) live in their own
+// module so this file stays focused on the platform allowlist and protected
+// roots; re-exported here so every existing caller keeps a single import.
+export {
+  isPpmDirPath,
+  isChatUploadPath,
+  isCloudflaredDirPath,
+  isCredentialPath,
+  assertNotPpmDir,
+  assertNotPpmSubtree,
+  assertNotPpmSubtreeDeep,
+} from "./fs-credential-path-guard.ts";
+
 /**
  * Central guard for every filesystem route that works outside project scope.
  * The whole disk is browsable behind PPM auth, so the remaining defences are:
@@ -38,14 +50,6 @@ export function resolvePath(input: string): string {
   return resolve(input);
 }
 
-/** Case-insensitive prefix test on Windows/macOS-style paths. */
-function isInside(child: string, parent: string): boolean {
-  const norm = (p: string) => (process.platform === "win32" ? p.toLowerCase() : p);
-  const c = norm(child);
-  const p = norm(parent);
-  return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
-}
-
 /**
  * Whitelist for system-level access. POSIX exposes the whole tree; Windows
  * requires a drive letter, which keeps UNC shares (`\\server\share`) out —
@@ -80,62 +84,6 @@ export function assertAllowed(resolved: string): void {
   }
 }
 
-/** True when the path is the PPM directory or anything inside it. */
-export function isPpmDirPath(resolved: string): boolean {
-  return isInside(resolved, getPpmDir());
-}
-
-/**
- * Chat attachments the user uploaded through the UI. They sit under the PPM
- * dir so chat history keeps resolving them across reboots, but they are
- * ordinary user content, not credential material: the transcript has to render
- * the very image the assistant just read back from that directory.
- */
-export function isChatUploadPath(resolved: string): boolean {
-  return isInside(resolved, getUploadsDir());
-}
-
-/**
- * Refuse the PPM directory subtree on read-style doors. It stores the config
- * database with provider credentials and auth tokens, which must never be
- * downloadable through a generic file route.
- *
- * Chat uploads are the one exception. Every caller applies this to the
- * requested path *and* to its real path, so a symlink parked in the uploads
- * directory still fails on the second call and cannot reach the rest of the
- * PPM dir through the exception.
- */
-export function assertNotPpmDir(resolved: string): void {
-  if (isPpmDirPath(resolved) && !isChatUploadPath(resolved)) {
-    throw Object.assign(new Error("Access denied"), { status: 403, code: "EDENIED" });
-  }
-}
-
-/**
- * Refuse operations that would take the PPM directory's contents anywhere
- * else. Reading that subtree is already blocked, so without this a copy to a
- * public path followed by an ordinary read would still hand out the
- * credentials database.
- */
-export function assertNotPpmSubtree(candidate: string): void {
-  if (isPpmDirPath(candidate)) {
-    throw Object.assign(new Error(`Refusing to operate on the PPM directory: ${candidate}`), {
-      status: 403,
-      code: "EPROTECTED",
-    });
-  }
-}
-
-/**
- * Same refusal, applied to the real path as well. A path that does not exist
- * yet is still resolved through its parents, so a symlinked directory cannot
- * be used to reach — or create something inside — the PPM directory.
- */
-export async function assertNotPpmSubtreeDeep(candidate: string): Promise<void> {
-  assertNotPpmSubtree(candidate);
-  assertNotPpmSubtree(await realPathOrSelf(candidate));
-}
-
 /** Paths whose removal or rename would break the host or PPM itself. */
 export function isProtectedRoot(candidate: string): boolean {
   const p = resolve(candidate);

package/src/services/named-tunnel/cloudflare-dns-api.ts

@@ -0,0 +1,40 @@
+/**
+ * Cloudflare REST calls the setup flow needs beyond what cloudflared's own
+ * CLI exposes: looking up an existing tunnel's UUID by name (so the DNS
+ * collision check can tell "already ours" from "someone else's" before
+ * `tunnel create` has even run) and reading a zone's DNS records for a
+ * candidate hostname.
+ */
+
+const TIMEOUT_MS = 10_000;
+
+export interface DnsRecord {
+  content: string;
+}
+
+async function cfGet<T extends { success?: boolean }>(url: string, apiToken: string): Promise<T> {
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiToken}` },
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  const json = (await res.json().catch(() => null)) as T | null;
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(`Cloudflare API call failed (HTTP ${res.status})`);
+  }
+  return json;
+}
+
+/** DNS records at `zoneID` matching `name` exactly (empty when none exist). */
+export async function fetchDnsRecords(zoneID: string, apiToken: string, name: string): Promise<DnsRecord[]> {
+  const url = `https://api.cloudflare.com/client/v4/zones/${encodeURIComponent(zoneID)}/dns_records?name=${encodeURIComponent(name)}`;
+  const json = await cfGet<{ success: true; result?: DnsRecord[] }>(url, apiToken);
+  return Array.isArray(json.result) ? json.result : [];
+}
+
+/** UUID of an existing, non-deleted tunnel named `name` — null if none exists yet. */
+export async function fetchTunnelIdByName(accountID: string, apiToken: string, name: string): Promise<string | null> {
+  const url = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountID)}/cfd_tunnel?name=${encodeURIComponent(name)}&is_deleted=false`;
+  const json = await cfGet<{ success: true; result?: Array<{ id?: string }> }>(url, apiToken);
+  const found = (json.result ?? []).find((t) => typeof t.id === "string" && t.id);
+  return found?.id ?? null;
+}

package/src/services/named-tunnel/cloudflare-zone-api.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve the zone name behind a `zoneID`, using the `apiToken` embedded in the
+ * user's origin cert — this avoids asking the user to type a hostname; PPM
+ * proposes `ppm.<zone>` from data it already has.
+ */
+
+/** 10s bound so a hung Cloudflare API call never wedges setup indefinitely. */
+const TIMEOUT_MS = 10_000;
+
+export async function fetchZoneName(zoneID: string, apiToken: string): Promise<string> {
+  const url = `https://api.cloudflare.com/client/v4/zones/${encodeURIComponent(zoneID)}`;
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiToken}` },
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+
+  let json: { success?: boolean; result?: { name?: string } } | null = null;
+  try {
+    json = await res.json();
+  } catch {
+    json = null;
+  }
+
+  if (!res.ok || !json || json.success !== true || typeof json.result?.name !== "string" || !json.result.name) {
+    throw new Error(`Cloudflare rejected the certificate token (HTTP ${res.status}) — log in again`);
+  }
+  return json.result.name;
+}

package/src/services/named-tunnel/cloudflared-cert.ts

@@ -0,0 +1,95 @@
+/**
+ * Parse `~/.cloudflared/cert.pem` — the credential `cloudflared tunnel login` writes.
+ * State is always derived by parsing the file, never `existsSync`: a truncated,
+ * foreign, or revoked cert must never look "authenticated" just because a file
+ * happens to sit at the expected path.
+ */
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+
+export interface ArgoCert {
+  zoneID: string;
+  accountID: string;
+  apiToken: string;
+}
+
+export type CertState =
+  | { kind: "absent" }
+  | { kind: "unparseable"; reason: string }
+  | { kind: "parsed"; cert: ArgoCert };
+
+const HEX32 = /^[0-9a-f]{32}$/;
+// The real-world label cloudflared ships today.
+const STRICT_BLOCK = /-----BEGIN ARGO TUNNEL TOKEN-----([\s\S]*?)-----END ARGO TUNNEL TOKEN-----/;
+// Fallback for a future cloudflared build that renames the label — accept any
+// "...TOKEN..." PEM block rather than hard-failing every login on a cosmetic
+// rename, while still preferring the known-good label as the first match.
+const GENERIC_TOKEN_BLOCK = /-----BEGIN ([A-Z0-9 ]*TOKEN[A-Z0-9 ]*)-----([\s\S]*?)-----END \1-----/;
+
+/**
+ * `cloudflared` decides this location, not PPM — it is a deliberate real-`homedir()`
+ * exception (see CLAUDE.md's "PPM Directory" section): `getPpmDir()` would point
+ * PPM's own data elsewhere and never find the user's actual login credential.
+ */
+export function getOriginCertPath(): string {
+  return process.env.TUNNEL_ORIGIN_CERT || resolve(homedir(), ".cloudflared", "cert.pem");
+}
+
+/** Extract the token PEM block's base64 payload, trying the strict label first. */
+function extractPayload(pem: string): string | null {
+  const strict = pem.match(STRICT_BLOCK);
+  if (strict) return strict[1]!;
+  const generic = pem.match(GENERIC_TOKEN_BLOCK);
+  if (generic) return generic[2]!;
+  return null;
+}
+
+/**
+ * Read and parse the origin cert. Never throws — every failure mode collapses
+ * to `unparseable` with a reason string that is safe to log (it never contains
+ * the base64 payload or any field value, so a leaked apiToken can't hide in it).
+ */
+export function readOriginCertState(path?: string): CertState {
+  const certPath = path ?? getOriginCertPath();
+  if (!existsSync(certPath)) return { kind: "absent" };
+
+  let raw: string;
+  try {
+    raw = readFileSync(certPath, "utf-8");
+  } catch {
+    return { kind: "unparseable", reason: "cert.pem could not be read" };
+  }
+
+  const payload = extractPayload(raw);
+  if (payload == null) return { kind: "unparseable", reason: "no TOKEN PEM block found" };
+
+  let decoded: string;
+  try {
+    decoded = Buffer.from(payload.replace(/\s+/g, ""), "base64").toString("utf-8");
+  } catch {
+    return { kind: "unparseable", reason: "PEM block is not valid base64" };
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(decoded);
+  } catch {
+    return { kind: "unparseable", reason: "PEM payload is not valid JSON" };
+  }
+
+  if (typeof json !== "object" || json === null) {
+    return { kind: "unparseable", reason: "PEM payload is not a JSON object" };
+  }
+  const obj = json as Record<string, unknown>;
+  const { zoneID, accountID, apiToken } = obj;
+  if (typeof zoneID !== "string" || !zoneID || typeof accountID !== "string" || !accountID ||
+      typeof apiToken !== "string" || !apiToken) {
+    return { kind: "unparseable", reason: "cert is missing zoneID/accountID/apiToken" };
+  }
+  if (!HEX32.test(zoneID) || !HEX32.test(accountID)) {
+    return { kind: "unparseable", reason: "zoneID/accountID are not 32-char hex ids" };
+  }
+
+  return { kind: "parsed", cert: { zoneID, accountID, apiToken } };
+}

package/src/services/named-tunnel/cloudflared-exec.ts

@@ -0,0 +1,50 @@
+/**
+ * One-shot cloudflared invocations (`tunnel create`, `route dns`, `tunnel
+ * token`) — distinct from the long-running login process in
+ * `cloudflared-login.service.ts`, which needs incremental stdout/stderr reads
+ * instead of a single awaited result.
+ */
+import { ensureCloudflared } from "../cloudflared.service.ts";
+import { killProcessTree } from "../windows-process-tree.ts";
+
+export interface RunCloudflaredResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Short one-shot calls must never hang setup indefinitely on a network stall. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Spawn cloudflared with `args`, capture both streams, and enforce a timeout.
+ * Never logs `args` — phase 1b's argv builders already keep them secret-free
+ * (the run token travels via `--token-file`, never argv), so this stays that
+ * way rather than re-introducing a leak at the logging layer.
+ */
+export async function runCloudflared(
+  args: string[],
+  opts: { timeoutMs?: number } = {},
+): Promise<RunCloudflaredResult> {
+  const bin = await ensureCloudflared();
+  const proc = Bun.spawn([bin, ...args], { stdout: "pipe", stderr: "pipe" });
+
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killProcessTree(proc.pid);
+  }, timeoutMs);
+
+  try {
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (timedOut) throw new Error(`cloudflared timed out after ${timeoutMs}ms`);
+    return { code, stdout, stderr };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/services/named-tunnel/cloudflared-login-helpers.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure/self-contained helpers for the login session state machine, split out
+ * of `cloudflared-login.service.ts` purely to keep that file under the
+ * project's line-count guideline — none of these hold their own module state.
+ */
+import { existsSync, renameSync } from "node:fs";
+import { getOriginCertPath } from "./cloudflared-cert.ts";
+import { resolveTunnelConfig } from "./named-tunnel-config.ts";
+import { configService } from "../config.service.ts";
+import { extractLoginUrl, isLoginSuccess } from "./login-output-parser.ts";
+
+const VERIFY_TIMEOUT_MS = 8_000;
+
+export type CertLiveCheck = "valid" | "invalid" | "unreachable";
+
+/**
+ * Live-checks an apiToken against Cloudflare, distinguishing an authoritative
+ * rejection from simply failing to ask. This distinction is the whole point:
+ * the caller renames a stale cert.pem aside on "invalid" (Cloudflare itself
+ * said the token is dead) but must NOT do that on "unreachable" (a network
+ * blip, timeout, rate limit, or Cloudflare-side outage) — a user on a flaky
+ * connection who presses "Set up" must never have a perfectly working
+ * credential discarded just because the verify call itself didn't land.
+ */
+export async function verifyCertLive(apiToken: string): Promise<CertLiveCheck> {
+  let res: Response;
+  try {
+    res = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", {
+      headers: { Authorization: `Bearer ${apiToken}` },
+      signal: AbortSignal.timeout(VERIFY_TIMEOUT_MS),
+    });
+  } catch {
+    return "unreachable"; // network error, DNS failure, or the bounded timeout firing
+  }
+
+  // 401/403: Cloudflare rejected the token outright. 429/5xx: rate-limited or
+  // Cloudflare's own outage — neither says anything about the token itself.
+  if (res.status === 401 || res.status === 403) return "invalid";
+  if (res.status === 429 || res.status >= 500) return "unreachable";
+
+  const json = (await res.json().catch(() => null)) as { success?: boolean } | null;
+  if (json?.success === true) return "valid";
+  if (json?.success === false) return "invalid";
+  return "unreachable"; // an unexpected response shape is not an authoritative rejection
+}
+
+/** True when no `tunnel` identity is pinned yet, or the cert matches the pinned one. */
+export function pinsMatch(cert: { zoneID: string; accountID: string }): boolean {
+  const resolved = resolveTunnelConfig(configService.get("tunnel"));
+  if (resolved.mode !== "named") return true;
+  return resolved.zoneID === cert.zoneID && resolved.accountID === cert.accountID;
+}
+
+/** Rename an existing cert.pem aside so a stale/foreign cert can never block a fresh login. */
+export function renameCertAside(): void {
+  const path = getOriginCertPath();
+  if (!existsSync(path)) return;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  renameSync(path, `${path}.bak-${stamp}`);
+}
+
+/**
+ * Read a login process's stdout/stderr stream incrementally: report the URL
+ * as soon as it appears, and signal success the moment the success line
+ * shows up (without waiting for the process to exit). `isSuperseded` lets the
+ * caller bail out the instant this stream stops being the "current" one
+ * (cancel/retry/timeout raced ahead of us).
+ */
+export async function pumpLoginStream(
+  stream: ReadableStream<Uint8Array>,
+  hooks: { isSuperseded: () => boolean; hasUrl: () => boolean; onUrl: (url: string) => void; onSuccess: () => void },
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (hooks.isSuperseded()) return;
+
+      const chunk = decoder.decode(value, { stream: true });
+      buffered += chunk;
+
+      if (!hooks.hasUrl()) {
+        const url = extractLoginUrl(chunk) ?? extractLoginUrl(buffered);
+        if (url) hooks.onUrl(url);
+      }
+      if (isLoginSuccess(chunk) || isLoginSuccess(buffered)) {
+        hooks.onSuccess();
+        return;
+      }
+    }
+  } catch {
+    // Stream closed underneath us (process killed) — a terminal state has
+    // already been (or is about to be) set by whichever timer/cancel did it.
+  }
+}