fullstackgtm 0.48.0 → 0.50.0

package/src/planStore.ts

@@ -1,7 +1,9 @@
-import { chmodSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { chmodSync, closeSync, mkdirSync, openSync, readdirSync, unlinkSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
 import { computeApprovalDigests, loadOrCreateSigningKey } from "./integrity.ts";
+import { assertNoSymlinkComponents, readSecureRegularFile, UnsafeManagedPathError } from "./secureFile.ts";
 import type { ApprovalStatus, PatchPlan, PatchPlanRun } from "./types.ts";
 
 /**
@@ -23,11 +25,34 @@ export type StoredPlan = {
    * file is caught instead of written. Absent on plans approved before 0.26.0.
    */
   approvalDigests?: Record<string, string>;
+  /** Monotonic store revision used to make lifecycle changes explicit. */
+  revision: number;
+  /** Present only while one process owns the right to apply this plan. */
+  applyClaim?: {
+    id: string;
+    claimedAt: string;
+    revision: number;
+    hostedClaimId?: string;
+  };
+  /** Durable journal of apply ownership. An unresolved entry must never be replayed automatically. */
+  applyAttempts?: ApplyAttempt[];
   runs: PatchPlanRun[];
   createdAt: string;
   updatedAt: string;
 };
 
+export type ApplyAttempt = {
+  id: string;
+  claimedAt: string;
+  provider: string;
+  source: "cli" | "fix" | "mcp";
+  status: "in_progress" | "preflight_aborted" | "completed" | "uncertain";
+  resolvedAt?: string;
+  /** Deliberately generic: provider errors can contain CRM data or credentials. */
+  note?: string;
+  hostedClaimId?: string;
+};
+
 export interface PlanStore {
   save(plan: PatchPlan): Promise<StoredPlan>;
   get(planId: string): Promise<StoredPlan | null>;
@@ -38,9 +63,23 @@ export interface PlanStore {
     valueOverrides?: Record<string, unknown>,
   ): Promise<StoredPlan>;
   reject(planId: string): Promise<StoredPlan>;
-  recordRun(planId: string, run: PatchPlanRun): Promise<StoredPlan>;
+  claimApply(planId: string, metadata?: Pick<ApplyAttempt, "provider" | "source">): Promise<{ stored: StoredPlan; claimId: string }>;
+  recordHostedClaim(planId: string, claimId: string, hostedClaimId: string): Promise<StoredPlan>;
+  recordRun(planId: string, run: PatchPlanRun, claimId: string): Promise<StoredPlan>;
+  abortApplyPreflight(planId: string, claimId: string, note: string): Promise<StoredPlan>;
+  markApplyUncertain(planId: string, claimId: string): Promise<StoredPlan>;
+  recoverApply(planId: string): Promise<StoredPlan>;
+  reconcileReplica(planId: string, remote: ReplicaPlanState): Promise<{ stored: StoredPlan; changed: boolean }>;
 }
 
+/** A validated lifecycle snapshot received from another plan replica. */
+export type ReplicaPlanState = {
+  status: "approved" | "rejected" | "applied";
+  approvedOperationIds: string[];
+  valueOverrides?: Record<string, unknown>;
+  run?: PatchPlanRun;
+};
+
 /**
  * Plans as JSON files in a directory (default `$FSGTM_HOME/plans`), one file
  * per plan id. Filesystem-shaped on purpose: greppable, diffable, and any
@@ -49,6 +88,12 @@ export interface PlanStore {
 export function createFilePlanStore(directory?: string): PlanStore {
   const dir = directory ?? join(credentialsDir(), "plans");
 
+  function ensurePlanDirectory(): void {
+    assertNoSymlinkComponents(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    assertNoSymlinkComponents(dir);
+  }
+
   function pathFor(planId: string) {
     if (!/^[\w.-]+$/.test(planId)) throw new Error(`Invalid plan id: ${planId}`);
     return join(dir, `${planId}.json`);
@@ -56,8 +101,10 @@ export function createFilePlanStore(directory?: string): PlanStore {
 
   function read(planId: string): StoredPlan | null {
     try {
-      return JSON.parse(readFileSync(pathFor(planId), "utf8")) as StoredPlan;
-    } catch {
+      assertNoSymlinkComponents(dir);
+      return JSON.parse(readSecureRegularFile(pathFor(planId))) as StoredPlan;
+    } catch (error) {
+      if (error instanceof UnsafeManagedPathError) throw error;
       return null;
     }
   }
@@ -68,13 +115,17 @@ export function createFilePlanStore(directory?: string): PlanStore {
     // otherwise an `audit --save` before any `login` would create the home
     // directory world-readable.
     if (!directory) ensureSecureHomeDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    ensurePlanDirectory();
     try {
       chmodSync(dir, 0o700);
     } catch {
       // Non-POSIX filesystems ignore chmod.
     }
-    const next = { ...stored, updatedAt: new Date().toISOString() };
+    const next = {
+      ...stored,
+      revision: (stored.revision ?? 0) + 1,
+      updatedAt: new Date().toISOString(),
+    };
     writeSecureFile(pathFor(stored.plan.id), `${JSON.stringify(next, null, 2)}\n`);
     return next;
   }
@@ -85,17 +136,47 @@ export function createFilePlanStore(directory?: string): PlanStore {
     return stored;
   }
 
+  function withPlanLock<T>(planId: string, action: () => T): T {
+    ensurePlanDirectory();
+    const lockPath = `${pathFor(planId)}.lock`;
+    let fd: number;
+    try {
+      fd = openSync(lockPath, "wx", 0o600);
+    } catch (error) {
+      const code = error instanceof Error && "code" in error ? String(error.code) : "unknown";
+      if (code === "EEXIST") {
+        throw new Error(`Plan ${planId} is being updated by another process; retry after it finishes.`);
+      }
+      throw error;
+    }
+    try {
+      return action();
+    } finally {
+      closeSync(fd);
+      try { unlinkSync(lockPath); } catch { /* a missing lock is already released */ }
+    }
+  }
+
   return {
     async save(plan) {
-      const now = new Date().toISOString();
-      return write({
-        plan,
-        status: plan.status,
-        approvedOperationIds: [],
-        valueOverrides: {},
-        runs: [],
-        createdAt: now,
-        updatedAt: now,
+      return withPlanLock(plan.id, () => {
+        const existing = read(plan.id);
+        if (existing && ["approved", "applying", "applied"].includes(existing.status)) {
+          throw new Error(
+            `Plan ${plan.id} is already ${existing.status}; refusing to replace its approval or apply history.`,
+          );
+        }
+        const now = new Date().toISOString();
+        return write({
+          plan,
+          status: plan.status,
+          approvedOperationIds: [],
+          valueOverrides: {},
+          revision: 0,
+          runs: [],
+          createdAt: now,
+          updatedAt: now,
+        });
       });
     },
 
@@ -104,6 +185,7 @@ export function createFilePlanStore(directory?: string): PlanStore {
     },
 
     async list(status) {
+      assertNoSymlinkComponents(dir);
       let entries: string[] = [];
       try {
         entries = readdirSync(dir);
@@ -119,55 +201,238 @@ export function createFilePlanStore(directory?: string): PlanStore {
     },
 
     async approveOperations(planId, operationIds, valueOverrides = {}) {
-      const stored = mustRead(planId);
-      if (stored.status === "applied") {
-        throw new Error(`Plan ${planId} has already been applied.`);
-      }
-      if (stored.status === "rejected") {
-        throw new Error(`Plan ${planId} was rejected; re-run the audit for a fresh plan.`);
-      }
-      const known = new Set(stored.plan.operations.map((operation) => operation.id));
-      for (const operationId of operationIds) {
-        if (!known.has(operationId)) {
-          throw new Error(`Plan ${planId} has no operation ${operationId}.`);
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status === "applied") {
+          throw new Error(`Plan ${planId} has already been applied.`);
         }
-      }
-      const approvedOperationIds = Array.from(
-        new Set([...stored.approvedOperationIds, ...operationIds]),
-      );
-      const mergedOverrides = { ...stored.valueOverrides, ...valueOverrides };
-      // Bind the approval to the operation content so apply can detect a
-      // post-approval edit. Recompute over ALL approved ops (a later approve
-      // call may add overrides that change an earlier op's resolved value).
-      const approvalDigests = computeApprovalDigests(
-        stored.plan.operations,
-        approvedOperationIds,
-        mergedOverrides,
-        loadOrCreateSigningKey(),
-      );
-      return write({
-        ...stored,
-        status: "approved",
-        approvedOperationIds,
-        valueOverrides: mergedOverrides,
-        approvalDigests,
+        if (stored.status === "rejected") {
+          throw new Error(`Plan ${planId} was rejected; re-run the audit for a fresh plan.`);
+        }
+        if (stored.status === "applying" || stored.applyClaim) {
+          throw new Error(`Plan ${planId} is applying; approvals are frozen until the attempt is resolved.`);
+        }
+        const known = new Set(stored.plan.operations.map((operation) => operation.id));
+        for (const operationId of operationIds) {
+          if (!known.has(operationId)) {
+            throw new Error(`Plan ${planId} has no operation ${operationId}.`);
+          }
+        }
+        const approvedOperationIds = Array.from(
+          new Set([...stored.approvedOperationIds, ...operationIds]),
+        );
+        const mergedOverrides = { ...stored.valueOverrides, ...valueOverrides };
+        // Bind the approval to the operation content so apply can detect a
+        // post-approval edit. Recompute over ALL approved ops (a later approve
+        // call may add overrides that change an earlier op's resolved value).
+        const approvalDigests = computeApprovalDigests(
+          stored.plan.operations,
+          approvedOperationIds,
+          mergedOverrides,
+          loadOrCreateSigningKey(),
+        );
+        return write({
+          ...stored,
+          status: "approved",
+          approvedOperationIds,
+          valueOverrides: mergedOverrides,
+          approvalDigests,
+        });
       });
     },
 
     async reject(planId) {
-      const stored = mustRead(planId);
-      if (stored.status === "applied") {
-        throw new Error(`Plan ${planId} has already been applied.`);
-      }
-      return write({ ...stored, status: "rejected", approvedOperationIds: [] });
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status === "applied") {
+          throw new Error(`Plan ${planId} has already been applied.`);
+        }
+        if (stored.status === "applying" || stored.applyClaim) {
+          throw new Error(`Plan ${planId} is applying and cannot be rejected until the attempt is resolved.`);
+        }
+        return write({ ...stored, status: "rejected", approvedOperationIds: [], applyClaim: undefined });
+      });
     },
 
-    async recordRun(planId, run) {
-      const stored = mustRead(planId);
-      return write({
-        ...stored,
-        status: run.status === "applied" || run.status === "partial" ? "applied" : stored.status,
-        runs: [...stored.runs, run],
+    async claimApply(planId, metadata) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status === "applying" || stored.applyClaim) {
+          throw new Error(
+            `Plan ${planId} is already applying; inspect its recorded attempts before any retry.`,
+          );
+        }
+        if (stored.status !== "approved") {
+          throw new Error(`Plan ${planId} is ${stored.status}; only an approved plan can be claimed for apply.`);
+        }
+        const claimId = randomUUID();
+        const claimedAt = new Date().toISOString();
+        const claimed = write({
+          ...stored,
+          status: "applying",
+          applyClaim: {
+            id: claimId,
+            claimedAt,
+            revision: stored.revision ?? 0,
+          },
+          applyAttempts: [...(stored.applyAttempts ?? []), {
+            id: claimId,
+            claimedAt,
+            provider: metadata?.provider ?? "unknown",
+            source: metadata?.source ?? "cli",
+            status: "in_progress",
+          }],
+        });
+        return { stored: claimed, claimId };
+      });
+    },
+
+    async recordRun(planId, run, claimId) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status !== "applying" || stored.applyClaim?.id !== claimId) {
+          throw new Error(`Refusing to record run for plan ${planId}: apply claim is missing or does not match.`);
+        }
+        return write({
+          ...stored,
+          status: run.status === "applied" || run.status === "partial" ? "applied" : "approved",
+          applyClaim: undefined,
+          applyAttempts: (stored.applyAttempts ?? []).map((attempt) =>
+            attempt.id === claimId
+              ? { ...attempt, status: "completed" as const, resolvedAt: new Date().toISOString() }
+              : attempt),
+          runs: [...stored.runs, run],
+        });
+      });
+    },
+
+    async recordHostedClaim(planId, claimId, hostedClaimId) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status !== "applying" || stored.applyClaim?.id !== claimId) {
+          throw new Error(`Refusing to attach hosted claim for plan ${planId}: local apply claim does not match.`);
+        }
+        return write({
+          ...stored,
+          applyClaim: { ...stored.applyClaim, hostedClaimId },
+          applyAttempts: (stored.applyAttempts ?? []).map((attempt) =>
+            attempt.id === claimId ? { ...attempt, hostedClaimId } : attempt),
+        });
+      });
+    },
+
+    async abortApplyPreflight(planId, claimId, note) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status !== "applying" || stored.applyClaim?.id !== claimId) {
+          throw new Error(`Refusing to abort preflight for plan ${planId}: apply claim is missing or does not match.`);
+        }
+        return write({
+          ...stored,
+          status: "approved",
+          applyClaim: undefined,
+          applyAttempts: (stored.applyAttempts ?? []).map((attempt) =>
+            attempt.id === claimId
+              ? { ...attempt, status: "preflight_aborted" as const, resolvedAt: new Date().toISOString(), note }
+              : attempt),
+        });
+      });
+    },
+
+    async markApplyUncertain(planId, claimId) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status !== "applying" || stored.applyClaim?.id !== claimId) return stored;
+        return write({
+          ...stored,
+          applyAttempts: (stored.applyAttempts ?? []).map((attempt) =>
+            attempt.id === claimId
+              ? { ...attempt, status: "uncertain" as const, note: "Apply exited without a completed run; some provider writes may have landed." }
+              : attempt),
+        });
+      });
+    },
+
+    async recoverApply(planId) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status !== "applying" || !stored.applyClaim) {
+          throw new Error(`Plan ${planId} has no unresolved apply attempt.`);
+        }
+        // Recovery is deliberately privilege-decaying: discard the old approval.
+        // An operator must inspect the provider, then explicitly approve a fresh attempt.
+        return write({
+          ...stored,
+          status: "needs_approval",
+          applyClaim: undefined,
+          approvedOperationIds: [],
+          valueOverrides: {},
+          approvalDigests: undefined,
+          applyAttempts: (stored.applyAttempts ?? []).map((attempt) =>
+            attempt.id === stored.applyClaim!.id
+              ? { ...attempt, status: "uncertain" as const, resolvedAt: new Date().toISOString(), note: "Operator acknowledged uncertain provider state; approval cleared before any retry." }
+              : attempt),
+        });
+      });
+    },
+
+    async reconcileReplica(planId, remote) {
+      return withPlanLock(planId, () => {
+        const stored = mustRead(planId);
+        if (stored.status === "applying" || stored.applyClaim) {
+          throw new Error(`Plan ${planId} is applying locally; replica reconciliation will retry after it finishes.`);
+        }
+        const known = new Set(stored.plan.operations.map((operation) => operation.id));
+        const approvedOperationIds = Array.from(new Set(remote.approvedOperationIds));
+        if (approvedOperationIds.some((id) => !known.has(id))) {
+          throw new Error(`Replica state for ${planId} contains an unknown operation.`);
+        }
+        // Terminal receipts are monotonic. A delayed approval or rejection can
+        // never roll an already-applied local replica backwards.
+        if (stored.status === "applied" && remote.status !== "applied") {
+          return { stored, changed: false };
+        }
+        if (remote.status === "rejected") {
+          if (stored.status === "rejected") return { stored, changed: false };
+          return { stored: write({
+            ...stored, status: "rejected", approvedOperationIds: [], valueOverrides: {},
+            approvalDigests: undefined, applyClaim: undefined,
+          }), changed: true };
+        }
+        if (approvedOperationIds.length === 0) {
+          throw new Error(`Replica ${remote.status} state for ${planId} has no approved operations.`);
+        }
+        const valueOverrides = remote.valueOverrides ?? {};
+        const approvalDigests = computeApprovalDigests(
+          stored.plan.operations, approvedOperationIds, valueOverrides, loadOrCreateSigningKey(),
+        );
+        if (remote.status === "approved") {
+          const unchanged = stored.status === "approved"
+            && JSON.stringify(stored.approvedOperationIds) === JSON.stringify(approvedOperationIds)
+            && JSON.stringify(stored.valueOverrides) === JSON.stringify(valueOverrides);
+          if (unchanged) return { stored, changed: false };
+          return { stored: write({
+            ...stored, status: "approved", approvedOperationIds, valueOverrides, approvalDigests,
+          }), changed: true };
+        }
+        if (!remote.run || remote.run.planId !== planId) {
+          throw new Error(`Replica applied state for ${planId} is missing a matching execution receipt.`);
+        }
+        if (remote.run.results.some((result) => !known.has(result.operationId))) {
+          throw new Error(`Replica execution receipt for ${planId} contains an unknown operation.`);
+        }
+        const runKey = (run: PatchPlanRun) => `${run.startedAt}\0${run.finishedAt}\0${run.provider}`;
+        const alreadyRecorded = stored.runs.some((run) => runKey(run) === runKey(remote.run!));
+        if (stored.status === "applied" && alreadyRecorded) return { stored, changed: false };
+        return { stored: write({
+          ...stored,
+          status: "applied",
+          approvedOperationIds,
+          valueOverrides,
+          approvalDigests,
+          applyClaim: undefined,
+          runs: alreadyRecorded ? stored.runs : [...stored.runs, remote.run],
+        }), changed: true };
       });
     },
   };

package/src/progress.ts

@@ -186,8 +186,8 @@ export const RUNS_REPLAY_STAGES = ["runs", "health"] as const;
 
 export const APPLY_STAGES = ["preflight", "operations", "results"] as const;
 
-/** `enrich acquire` — routing sourced candidate rows into a create plan. */
-export const ACQUIRE_STAGES = ["candidates"] as const;
+/** `enrich acquire` — discovery through a governed create plan. */
+export const ACQUIRE_STAGES = ["discovery", "resolution", "plan"] as const;
 
 export const MARKET_CAPTURE_STAGES = ["sources", "capture", "classify", "persist"] as const;
 

package/src/providerError.ts

@@ -0,0 +1,37 @@
+/**
+ * A persistence-safe provider failure. Third-party response bodies are
+ * deliberately excluded: they can reflect credentials, filters, or PII and
+ * errors are rendered in terminals, MCP responses, and scheduled-run files.
+ */
+export class ProviderHttpError extends Error {
+  readonly code = "PROVIDER_HTTP_ERROR";
+  readonly provider: string;
+  readonly operation: string;
+  readonly status: number;
+  readonly retryable: boolean;
+
+  constructor(
+    provider: string,
+    operation: string,
+    status: number,
+    retryable = status === 429 || status >= 500,
+  ) {
+    super(`${provider} ${operation} failed: HTTP ${status}.`);
+    this.name = "ProviderHttpError";
+    this.provider = provider;
+    this.operation = operation;
+    this.status = status;
+    this.retryable = retryable;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      provider: this.provider,
+      operation: this.operation,
+      status: this.status,
+      retryable: this.retryable,
+      message: this.message,
+    };
+  }
+}

package/src/publicHttp.ts

@@ -0,0 +1,147 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpRequest, type RequestOptions } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+
+export const DEFAULT_PUBLIC_HTTP_MAX_BYTES = 5_000_000;
+
+export type PublicAddress = { address: string; family: number };
+export type PublicLookup = (hostname: string) => Promise<PublicAddress[]>;
+
+function ipv4IsPrivate(ip: string): boolean {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b, c] = parts;
+  return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 0 && (c === 0 || c === 2)) || (a === 192 && b === 168) ||
+    (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+    (a === 203 && b === 0 && c === 113) || a >= 224;
+}
+
+function embeddedIpv4IsPrivate(high: string, low: string): boolean {
+  const hi = Number.parseInt(high, 16);
+  const lo = Number.parseInt(low, 16);
+  if (!Number.isInteger(hi) || !Number.isInteger(lo) || hi > 0xffff || lo > 0xffff) return true;
+  return ipv4IsPrivate(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+}
+
+export function ipIsPrivate(ip: string): boolean {
+  const family = isIP(ip);
+  if (family === 4) return ipv4IsPrivate(ip);
+  if (family !== 6) return true;
+  const lower = ip.toLowerCase();
+  if (lower === "::" || lower === "::1") return true;
+  const embedded = lower.match(/^::(?:ffff:)?([0-9a-f]+):([0-9a-f]+)$/);
+  if (embedded) return embeddedIpv4IsPrivate(embedded[1], embedded[2]);
+  const embeddedDotted = lower.match(/^::(?:ffff:)?(.+\..+)$/);
+  if (embeddedDotted) return ipv4IsPrivate(embeddedDotted[1]);
+  const nat64 = lower.match(/^64:ff9b::([0-9a-f]+):([0-9a-f]+)$/);
+  if (nat64) return embeddedIpv4IsPrivate(nat64[1], nat64[2]);
+  const sixToFour = lower.match(/^2002:([0-9a-f]+):([0-9a-f]+):/);
+  if (sixToFour) return embeddedIpv4IsPrivate(sixToFour[1], sixToFour[2]);
+  return /^(?:fc|fd)/.test(lower) || /^(?:fe8|fe9|fea|feb)/.test(lower) ||
+    lower.startsWith("ff") || lower.startsWith("100:") ||
+    lower.startsWith("2001:db8:") || lower.startsWith("2001:0:") ||
+    lower.startsWith("2001:10:") || lower.startsWith("3fff:") ||
+    lower.startsWith("64:ff9b:1:");
+}
+
+const systemLookup: PublicLookup = async (hostname) =>
+  (await dnsLookup(hostname, { all: true, verbatim: true })).map(({ address, family }) => ({ address, family }));
+
+/** Resolve once and reject the entire hostname if any answer is non-public. */
+export async function resolvePublicAddresses(hostname: string, lookup: PublicLookup = systemLookup): Promise<PublicAddress[]> {
+  const literal = hostname.replace(/^\[|\]$/g, "");
+  const family = isIP(literal);
+  const addresses = family ? [{ address: literal, family }] : await lookup(literal);
+  if (addresses.length === 0) throw new Error(`public HTTP: ${literal} did not resolve to an address.`);
+  for (const { address } of addresses) {
+    if (ipIsPrivate(address)) throw new Error(`public HTTP refuses ${literal} — it resolves to private/internal address ${address} (SSRF guard).`);
+  }
+  return addresses;
+}
+
+export async function assertPublicUrl(rawUrl: string, lookup: PublicLookup = systemLookup): Promise<URL> {
+  let url: URL;
+  try { url = new URL(rawUrl); } catch { throw new Error(`market capture: "${rawUrl}" is not a valid URL.`); }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`market capture refuses ${url.protocol} URLs (only http/https): ${rawUrl}`);
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (isIP(host) && ipIsPrivate(host)) {
+    throw new Error(`market capture refuses private/loopback address ${host} (SSRF guard).`);
+  }
+  const addresses = await resolvePublicAddresses(host, lookup);
+  // Keep the resolved set available to the request path without changing the public API.
+  Object.defineProperty(url, "__publicAddresses", { value: addresses });
+  return url;
+}
+
+export type PublicHttpResult = { status: number; headers: Headers; body: Uint8Array; finalUrl: string };
+type HopResult = Omit<PublicHttpResult, "finalUrl">;
+export type PublicRequestHop = (url: URL, addresses: PublicAddress[], headers: Record<string, string>, timeoutMs: number, maxBytes: number) => Promise<HopResult>;
+
+const requestHop: PublicRequestHop = (url, addresses, headers, timeoutMs, maxBytes) => new Promise((resolve, reject) => {
+  let cursor = 0;
+  const options: RequestOptions = {
+    protocol: url.protocol, hostname: url.hostname, port: url.port || undefined,
+    path: `${url.pathname}${url.search}`, method: "GET", headers,
+    lookup: (_hostname, options, callback) => {
+      const requestedFamily = typeof options === "number" ? options : options?.family;
+      const eligible = requestedFamily ? addresses.filter((a) => a.family === requestedFamily) : addresses;
+      const selected = eligible[cursor++ % eligible.length];
+      if (!selected) return callback(new Error("public HTTP: no validated address matches the requested family"), "", 0);
+      callback(null, selected.address, selected.family);
+    },
+  };
+  const req = (url.protocol === "https:" ? httpsRequest : httpRequest)(options, (res) => {
+    if (maxBytes === 0) {
+      resolve({ status: res.statusCode ?? 0, headers: new Headers(res.headers as Record<string, string>), body: new Uint8Array() });
+      res.destroy();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let total = 0;
+    res.on("data", (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        req.destroy(new Error(`public HTTP response exceeds ${maxBytes} bytes`));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    res.on("end", () => resolve({ status: res.statusCode ?? 0, headers: new Headers(res.headers as Record<string, string>), body: Buffer.concat(chunks) }));
+  });
+  req.setTimeout(timeoutMs, () => req.destroy(new Error(`public HTTP request timed out after ${timeoutMs}ms`)));
+  req.on("error", reject);
+  req.end();
+});
+
+const SENSITIVE_HEADERS = new Set(["authorization", "cookie", "proxy-authorization"]);
+
+/** Public-only GET with DNS pinning, bounded bodies, and per-hop redirect validation. */
+export async function publicHttpGet(rawUrl: string, options: {
+  headers?: Record<string, string>; timeoutMs?: number; maxBytes?: number; maxRedirects?: number;
+  lookup?: PublicLookup; requestHop?: PublicRequestHop;
+} = {}): Promise<PublicHttpResult> {
+  let current = rawUrl;
+  let headers = { ...(options.headers ?? {}) };
+  const maxRedirects = options.maxRedirects ?? 5;
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    const url = await assertPublicUrl(current, options.lookup);
+    const addresses = (url as URL & { __publicAddresses: PublicAddress[] }).__publicAddresses;
+    const result = await (options.requestHop ?? requestHop)(url, addresses, headers, options.timeoutMs ?? 15_000, options.maxBytes ?? DEFAULT_PUBLIC_HTTP_MAX_BYTES);
+    const location = result.headers.get("location");
+    if (result.status >= 300 && result.status < 400 && location) {
+      const next = new URL(location, url);
+      if (next.origin !== url.origin) {
+        headers = Object.fromEntries(Object.entries(headers).filter(([key]) => !SENSITIVE_HEADERS.has(key.toLowerCase())));
+      }
+      current = next.toString();
+      continue;
+    }
+    return { ...result, finalUrl: current };
+  }
+  throw new Error(`public HTTP: too many redirects (>${maxRedirects}) for ${rawUrl}`);
+}