@iislee/opencodex 2.11.0 → 2.31.0

package/src/lib/destination-policy.ts

@@ -130,6 +130,50 @@ function registryAllowsPrivateNetwork(name: string): boolean {
   return getProviderRegistryEntry(name)?.allowPrivateNetworkByDefault === true;
 }
 
+/**
+ * OAuth registry entries that opt into `allowBaseUrlOverride` send bearer credentials to a
+ * user-configured endpoint (review findings, PR #2109 / PR #2110): a cleartext `http:`
+ * override would expose the OAuth token on the wire. `https:` is therefore required for
+ * every non-local destination. Loopback/localhost/private relays keep working over
+ * `http:` because they already sit behind the explicit `allowPrivateNetwork` opt-in
+ * enforced by {@link providerDestinationConfigError}. Keyed/local providers (Ollama,
+ * vLLM, LM Studio, LiteLLM, Moonshot, Qwen, Alibaba) are untouched: they are not
+ * `authKind: "oauth"`, so this check never fires for them.
+ */
+function registrySendsOAuthToOverriddenBaseUrl(name: string): boolean {
+  const entry = getProviderRegistryEntry(name);
+  return entry?.authKind === "oauth" && entry.allowBaseUrlOverride === true;
+}
+
+export function providerSecureTransportConfigError(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">,
+): string | null {
+  if (!registrySendsOAuthToOverriddenBaseUrl(name)) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(provider.baseUrl.trim());
+  } catch {
+    return null; // invalid URLs are providerBaseUrlConfigError's concern
+  }
+  if (parsed.protocol !== "http:") return null;
+  const assessment = assessDestination(provider.baseUrl);
+  // Classify FIRST, then consult the opt-in. `allowPrivateNetwork` says "this destination is
+  // intentionally local", which is a statement about the address, not a waiver of transport
+  // security — reading it before classification let `http://attacker.example` with the opt-in
+  // set carry an OAuth bearer in cleartext to a public host.
+  if (!assessment) return null;
+  const local = assessment.kind === "localhost"
+    || assessment.kind === "loopback"
+    || assessment.kind === "private";
+  if (local && providerAllowsPrivateNetwork(name, provider)) {
+    // A genuinely local relay over http stays reachable through the explicit opt-in; the
+    // private-network gate still governs whether it may be reached at all.
+    return null;
+  }
+  return "baseUrl must use https: this provider sends OAuth credentials to its endpoint, and http is allowed only for loopback/private relays";
+}
+
 /**
  * Whether a provider may reach loopback/private addresses.
  *
@@ -150,6 +194,8 @@ export function providerAllowsPrivateNetwork(
 }
 
 export function providerDestinationConfigError(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): string | null {
+  const secureTransportError = providerSecureTransportConfigError(name, provider);
+  if (secureTransportError) return secureTransportError;
   const assessment = assessDestination(provider.baseUrl);
   if (!assessment) return null;
   if (assessment.kind === "public" || assessment.kind === "hostname") return null;
@@ -241,10 +287,18 @@ export function assessUrlDestination(url: string): UrlDestinationAssessment | nu
  * Returns the validated addresses so direct callers can pin the connect peer and
  * avoid a second, rebindable resolution. DNS failures remain fail-closed here;
  * the provider proxy wrapper alone may recognize that typed failure and degrade.
+ *
+ * `allowBenchmarkAddresses` is an explicit outbound-only opt-in for Clash/Surge/
+ * Mihomo fake-IP DNS (IANA benchmark space 198.18.0.0/15, credit #1748): a hostname
+ * answer in that range is accepted without marking the destination private, so the
+ * caller can keep the hostname on its configured HTTP(S) proxy path. It applies to
+ * resolved answers only — a literal 198.18.x URL still rejects — and mixed answers
+ * that include any other non-public address still fail. Callers that do not pass it
+ * (image and Lab fetch) keep rejecting benchmark space.
  */
 export async function resolvePublicAddresses(
   url: string,
-  options?: string | { context?: string; allowPrivateNetwork?: boolean },
+  options?: string | { context?: string; allowPrivateNetwork?: boolean; allowBenchmarkAddresses?: boolean },
 ): Promise<{
   hostname: string;
   addresses: { address: string; family: number }[];
@@ -254,6 +308,7 @@ export async function resolvePublicAddresses(
     ? `${options.trim() || "image"} URL`
     : options?.context?.trim() || "image URL";
   const privateNetworkAllowed = typeof options === "object" && options?.allowPrivateNetwork === true;
+  const benchmarkAllowed = typeof options === "object" && options?.allowBenchmarkAddresses === true;
   let hostname: string;
   try {
     hostname = normalizeHostname(new URL(url.trim()).hostname);
@@ -294,6 +349,14 @@ export async function resolvePublicAddresses(
     const ipKind = isIP(address) || (family === 4 || family === 6 ? family : 0);
     const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
     if (!assessment || assessment.kind !== "public") {
+      // Hostname → 198.18.0.0/15 under the explicit opt-in is Clash/Surge/Mihomo
+      // fake-IP DNS, not a LAN provider. Accept it without allowPrivateNetwork and
+      // do not mark the destination private, so the caller's HTTP(S)_PROXY path
+      // still applies (credit #1748).
+      if (benchmarkAllowed && assessment?.kind === "private" && assessment.detail === "benchmark address") {
+        validatedAddresses.push({ address, family: ipKind === 4 || ipKind === 6 ? ipKind : (family || 4) });
+        continue;
+      }
       const allowedPrivateAddress = privateNetworkAllowed
         && assessment
         && (assessment.kind === "loopback" || assessment.kind === "private");
@@ -314,3 +377,4 @@ export async function resolvePublicAddresses(
 export async function assertUrlResolvesPublic(url: string): Promise<void> {
   await resolvePublicAddresses(url);
 }
+

package/src/lib/errors.ts

@@ -43,6 +43,25 @@ function isSubscriptionGateMessage(text: string): boolean {
   );
 }
 
+function isLocalAclHardeningMessage(text: string): boolean {
+  const secretPathHardening = text.includes("secret path") && (
+    text.includes("acl") ||
+    text.includes("harden") ||
+    text.includes("permission") ||
+    text.includes("access denied") ||
+    text.includes("inheritance")
+  );
+  return (
+    text.includes("icacls") ||
+    text.includes("acl hardening") ||
+    text.includes("ntfs") ||
+    secretPathHardening ||
+    text.includes("inheritance:r") ||
+    /\bwindows\b.*\bacl\b/.test(text) ||
+    text.includes("/grant:r")
+  );
+}
+
 function isAuthenticationMessage(text: string): boolean {
   const accessDeniedWithCredentialCue = (
     text.includes("access denied") ||
@@ -124,6 +143,15 @@ export function classifyError(status: number, type: string, message: string): Oc
   if (type === CYBER_POLICY_ERROR_CODE || isCyberPolicyMessage(text)) {
     return { message, type: "invalid_request_error", code: CYBER_POLICY_ERROR_CODE };
   }
+  // A LOCAL preflight refusal keeps its own code (#1524). The message necessarily says
+  // "context window" -- that is what it is refusing on -- so the generic remap below would
+  // rewrite it to `context_length_exceeded` and make it indistinguishable from an UPSTREAM
+  // verdict. The two need opposite fallback handling: ours means "this candidate does not
+  // fit", theirs means "the request is impossible", so collapsing them ended the chain at
+  // the first candidate that was merely too small.
+  if (type === "input_admission_refused") {
+    return { message, type: "invalid_request_error", code: "input_admission_refused" };
+  }
   if (
     text.includes("context_length_exceeded") ||
     text.includes("context window") ||
@@ -134,11 +162,16 @@ export function classifyError(status: number, type: string, message: string): Oc
     return { message, type: "invalid_request_error", code: "context_length_exceeded" };
   }
   // "Cursor resource limit exceeded" is emitted only for explicit request-size overflow
-  // details (isCursorRequestTooLargeDetail in cursor-errors.ts); quota-style resource
-  // exhaustion arrives as "Cursor rate limit exceeded" and falls through to 429 below.
+  // details (isCursorRequestTooLargeDetail in cursor-errors.ts); "Cursor context limit
+  // exceeded" is the bare payload-overflow shape (isCursorZeroTokenResourceExhausted);
+  // quota-style resource exhaustion arrives as "Cursor rate limit exceeded" and falls
+  // through to 429 below.
   if (text.includes("cursor resource limit exceeded")) {
     return { message, type: "invalid_request_error", code: "tool_catalog_too_large" };
   }
+  if (text.includes("cursor context limit exceeded")) {
+    return { message, type: "invalid_request_error", code: "context_length_exceeded" };
+  }
   // The Cursor adapter's classified rate-limit prefix is authoritative: its DETAIL may echo
   // quota wording ("... quota exhausted") that would otherwise hit the insufficient_quota
   // branch below and break the planned retry-with-backoff contract (WP3 review blocker 1).
@@ -170,6 +203,11 @@ export function classifyError(status: number, type: string, message: string): Oc
   if (type === "origin_rejected") {
     return { message, type: "invalid_request_error", code: "origin_rejected" };
   }
+  // Local ACL setup failures can contain provider-like auth wording (for example
+  // "access denied" or "authentication") but represent unavailable infrastructure.
+  if (status === 503 && isLocalAclHardeningMessage(text)) {
+    return { message, type: "server_error", code: "upstream_server_error" };
+  }
   // HTTP 401 and explicit auth failures are authoritative even when provider text
   // also advertises an upgrade or subscription.
   if (
@@ -273,6 +311,7 @@ export function inferHttpStatusFromAdapterMessage(message: string): number {
   // See classifyError: this prefix now only means explicit request-size overflow (400);
   // quota-style Cursor resource exhaustion carries the rate-limit prefix and maps to 429.
   if (lower.includes("cursor resource limit exceeded")) return 400;
+  if (lower.includes("cursor context limit exceeded")) return 400;
   if (
     lower.includes("resource_exhausted") ||
     lower.includes("resource exhausted") ||
@@ -280,6 +319,9 @@ export function inferHttpStatusFromAdapterMessage(message: string): number {
     lower.includes("too many requests") ||
     lower.includes("throttling")
   ) return 429;
+  // Local Windows filesystem hardening is infrastructure, not provider authentication.
+  // Keep this ahead of auth/permission and timeout keyword inference.
+  if (isLocalAclHardeningMessage(lower)) return 503;
   // Strong authentication signals win when a message contains mixed auth and
   // subscription/permission wording.
   if (isAuthenticationMessage(lower)) return 401;

package/src/lib/fabric-task-execution-authority.ts

@@ -0,0 +1,7 @@
+import type { TrustedFabricPatchExecutor } from "../lab/fabric/types";
+import { isHostIssuedFabricPatchExecutor } from "./fabric-task-host";
+
+/** Trusted exact-route fabric patch executor recognition facade. */
+export function isTrustedFabricPatchExecutor(value: unknown): value is TrustedFabricPatchExecutor {
+  return isHostIssuedFabricPatchExecutor(value);
+}

package/src/lib/fabric-task-host.ts

@@ -0,0 +1,29 @@
+import type { FabricPatchExecutor, FabricPatchExecutorInput, TrustedFabricPatchExecutor } from "../lab/fabric/types";
+
+const HOST_ISSUED_EXECUTORS = new WeakSet<object>();
+
+/**
+ * Trusted host integration boundary for CL-07 exact-route fabric patch production.
+ *
+ * @internal host integration only
+ */
+export function createHostIssuedFabricPatchExecutor(
+  executorModulePath: string,
+  execute: FabricPatchExecutor,
+): TrustedFabricPatchExecutor {
+  const capability: TrustedFabricPatchExecutor = Object.freeze({
+    executorModulePath,
+    execute: (input: FabricPatchExecutorInput) => Promise.resolve(execute(input)),
+  });
+  HOST_ISSUED_EXECUTORS.add(capability);
+  return capability;
+}
+
+/** Internal recognition check consumed by the read-only authority facade. */
+export function isHostIssuedFabricPatchExecutor(value: unknown): value is TrustedFabricPatchExecutor {
+  if (typeof value !== "object" || value === null || !HOST_ISSUED_EXECUTORS.has(value as object)) return false;
+  const capability = value as TrustedFabricPatchExecutor;
+  return typeof capability.executorModulePath === "string"
+    && capability.executorModulePath.length > 0
+    && typeof capability.execute === "function";
+}

package/src/lib/lab-activation.ts

@@ -0,0 +1,223 @@
+/**
+ * Compatibility Lab activation.
+ *
+ * The proxy core does not import Lab. This module is the seam that does, and the startup
+ * composition root calls it only when the install actually uses Lab, so a user with no
+ * routing profile and no automation executes no Lab code and starts no Lab timer.
+ *
+ * Activation is SYNCHRONOUS by design. Three audit rounds established that a deferred
+ * activation window is unpatchable: `routeModelInternal` is sync, and so is the
+ * subagent-fallback chain that calls `routeModel`, so those callers have nowhere to await.
+ * During such a window a policy alias would be silently dropped from a fallback chain and
+ * the subagent would run on a different model than the operator configured. Registration
+ * therefore completes before `startServer` returns, inside the same synchronous turn as
+ * `Bun.serve`, so no request can observe an unregistered slot.
+ *
+ * See devlog/_fin/260814_lab_core_decoupling/080_activation_is_synchronous.md
+ *
+ * Startup degrades, explicit operator action reports. This asymmetry is deliberate: an
+ * invalid automation config disables automation with a warning here, but the management
+ * API and CLI paths that start a scheduler leave `LabAutomationError` to surface (the
+ * management route maps it to a 400). Someone who just toggled automation should see the
+ * validation error; someone merely starting the proxy should not lose unrelated traffic.
+ *
+ * @internal host integration only
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { labAutomationPolicyPath } from "../lab/paths";
+import type { OcxConfig } from "../types";
+import { LabAutomationError } from "../lab/automation/types";
+import { registerLabPassiveRouteLinker } from "./lab-passive-linker-registration";
+import { registerCurrentServerResourceCleanup } from "./server-resource-ownership";
+import { setCompatibilityEvidenceProvider } from "../routing/compatibility/provider-slot";
+import { labCompatibilityEvidenceProvider } from "../routing/compatibility/lab-evidence-provider";
+import {
+  setLabAutomationDispatchDeps,
+  startLabAutomationScheduler,
+} from "../lab/automation/orchestrator";
+import { createProductionLabRouteExecutor } from "./lab-live-route-production";
+
+interface LabRuntimeBinding {
+  release(): void;
+}
+
+interface LabActivationRecord {
+  staticDetach: Array<() => void>;
+  runtime: LabRuntimeBinding | null;
+  seenRuntimeConfigs: WeakSet<OcxConfig>;
+}
+
+/** Activation records keyed by configDir, so one process can own several configs. */
+const activated = new Map<string, LabActivationRecord>();
+
+const activationKey = (configDir?: string): string => configDir ?? "";
+
+function readJsonIfPresent(path: string): unknown {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    // A malformed or unreadable file means "not enabled": this detector must never throw
+    // during startup, and must never import Lab persistence to answer the question.
+    return null;
+  }
+}
+
+/**
+ * True when Lab automation is enabled on disk.
+ *
+ * Mirrors `loadLabAutomationConfig` precedence deliberately: the current authority is the
+ * combined `automation-config.json`, with `automation-policy.json` as the legacy fallback.
+ * Reading only the legacy file would miss every install that enabled automation through
+ * the current dashboard.
+ */
+export function labAutomationEnabledOnDisk(configDir?: string): boolean {
+  const legacyPath = labAutomationPolicyPath(configDir);
+  const combined = readJsonIfPresent(join(dirname(legacyPath), "automation-config.json"));
+  if (combined && typeof combined === "object") {
+    const policy = (combined as { policy?: unknown }).policy;
+    if (policy && typeof policy === "object") {
+      return (policy as { enabled?: unknown }).enabled === true;
+    }
+  }
+  const legacy = readJsonIfPresent(legacyPath);
+  if (legacy && typeof legacy === "object") {
+    return (legacy as { enabled?: unknown }).enabled === true;
+  }
+  return false;
+}
+
+/** True when this install actually uses Lab: any routing profile, or automation enabled. */
+export function labActivationRequired(config: OcxConfig, configDir?: string): boolean {
+  if (Object.keys(config.routingProfiles ?? {}).length > 0) return true;
+  return labAutomationEnabledOnDisk(configDir);
+}
+
+function startAutomationIfEnabled(configDir?: string): void {
+  if (!labAutomationEnabledOnDisk(configDir)) return;
+  try {
+    startLabAutomationScheduler(configDir);
+  } catch (err) {
+    // Neither a malformed automation file nor a busy state lock may take the proxy down
+    // at startup. Lab automation stays off for this run; routing, evidence, and every
+    // other subsystem keep working.
+    //
+    // The two causes get different messages because they need different actions, and a
+    // lock-contention failure reported as "invalid config" sends the operator to fix a
+    // file that is fine. Contention can also stall startup by up to the 5s lock wait.
+    const code = err instanceof LabAutomationError ? err.code : null;
+    if (code === "state_lock_busy" || code === "state_lock_failed") {
+      console.warn(
+        "[lab] Lab automation did not start: another process holds the automation state lock."
+        + " Automation stays off for this run and will be retried on the next start.",
+      );
+    } else {
+      console.warn(
+        "[lab] Lab automation is disabled for this run because its configuration could not be"
+        + " loaded:",
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+}
+
+function installLabAutomationRuntime(
+  record: LabActivationRecord,
+  config: OcxConfig,
+  configDir?: string,
+): void {
+  const previous = record.runtime;
+  const routeExecutor = createProductionLabRouteExecutor({ configDir, loadConfig: () => config });
+  const releaseDispatchDeps = setLabAutomationDispatchDeps({
+    configDir,
+    loadConfig: () => config,
+    routeExecutor,
+  });
+
+  let released = false;
+  let detachOwnerCleanup = () => {};
+  const binding: LabRuntimeBinding = {
+    release() {
+      if (released) return;
+      released = true;
+      detachOwnerCleanup();
+      releaseDispatchDeps();
+      if (record.runtime === binding) record.runtime = null;
+    },
+  };
+  // `setLabAutomationDispatchDeps` already registers its own owner cleanup. This second
+  // receipt only keeps the activation record in sync with that owner-scoped lifetime, so a
+  // later same-process server can see that the static Lab slots survived but CL-08 authority
+  // did not. The release is idempotent, so cleanup order does not matter.
+  detachOwnerCleanup = registerCurrentServerResourceCleanup(binding.release);
+
+  // Install the successor before releasing the predecessor. The dispatcher token check then
+  // makes the predecessor release a no-op for the successor scheduler/authority.
+  record.runtime = binding;
+  record.seenRuntimeConfigs.add(config);
+  previous?.release();
+}
+
+/**
+ * Register Lab into the core slots. Static activation is idempotent per configDir. The
+ * server-owned CL-08 runtime binding is refreshed when its prior owner ended or when a new
+ * server instance arrives with a config object that has not owned this activation before.
+ */
+export function activateLab(config: OcxConfig, configDir?: string): void {
+  const key = activationKey(configDir);
+  const existing = activated.get(key);
+  if (existing) {
+    // A released predecessor leaves the static Lab slots resident but removes dispatch
+    // authority and its scheduler. A live successor uses a fresh config object. Rebind in
+    // either case, but never let an older already-seen server steal authority back from a
+    // newer successor merely because it receives another management request.
+    if (existing.runtime === null || !existing.seenRuntimeConfigs.has(config)) {
+      installLabAutomationRuntime(existing, config, configDir);
+      startAutomationIfEnabled(configDir);
+    }
+    return;
+  }
+
+  // INVARIANT: static activation is all-or-nothing and reason-independent. Every static
+  // slot is registered here regardless of WHY activation was required, so automation-only
+  // activation still installs the compatibility provider a later profile needs.
+  const record: LabActivationRecord = {
+    staticDetach: [],
+    runtime: null,
+    seenRuntimeConfigs: new WeakSet<OcxConfig>(),
+  };
+  record.staticDetach.push(registerLabPassiveRouteLinker(configDir));
+  record.staticDetach.push(setCompatibilityEvidenceProvider(labCompatibilityEvidenceProvider));
+  installLabAutomationRuntime(record, config, configDir);
+
+  // Record the activation BEFORE the scheduler start. startLabAutomationScheduler runs the
+  // full automation normalizer, which throws on any field violation, and this call sits on
+  // the startup path of every install that has a routing profile. Storing the record first
+  // means a throw cannot orphan the detach receipts and leave slots registered with no
+  // activation record, which would let a later activateLab register them a second time.
+  activated.set(key, record);
+  startAutomationIfEnabled(configDir);
+}
+
+/** True when this configDir has been activated. */
+export function isLabActivated(configDir?: string): boolean {
+  return activated.has(activationKey(configDir));
+}
+
+/**
+ * Test-only teardown. Deactivation is deliberately NOT a production path: tearing an
+ * activation down mid-run would finalize in-flight automation as ineligible rather than
+ * cancelled, and the orchestrator's shutdown signal is process-global. An install that
+ * creates then deletes a profile keeps Lab resident until restart, which does not affect
+ * users who never opted in.
+ */
+export function resetLabActivationForTests(): void {
+  for (const [key, record] of [...activated]) {
+    activated.delete(key);
+    try { record.runtime?.release(); } catch { /* teardown is best-effort */ }
+    for (const release of [...record.staticDetach].reverse()) {
+      try { release(); } catch { /* teardown is best-effort */ }
+    }
+  }
+}

package/src/lib/lab-live-execution-authority.ts

@@ -0,0 +1,13 @@
+import type { TrustedLabRouteExecutor } from "../lab/live/types";
+import { isHostIssuedLabRouteExecutor } from "./lab-live-host";
+
+/**
+ * Read-only trust check used by the Lab executor.
+ *
+ * Capability issuance intentionally does not live in this authority module: callers cannot
+ * self-attest sandbox boundary names here. Only the dedicated trusted host integration may
+ * construct and register an evidence-eligible route executor.
+ */
+export function isTrustedLabRouteExecutor(value: unknown): value is TrustedLabRouteExecutor {
+  return isHostIssuedLabRouteExecutor(value);
+}

package/src/lib/lab-live-host.ts

@@ -0,0 +1,30 @@
+import type { LabRouteExecutor, TrustedLabRouteExecutor } from "../lab/live/types";
+import { REQUIRED_LAB_SANDBOX_BOUNDARIES } from "../lab/live/types";
+
+const HOST_ISSUED_EXECUTORS = new WeakSet<object>();
+
+/**
+ * Trusted host integration boundary for CL-03 exact-route execution.
+ *
+ * This module is intentionally not re-exported from the Lab public surface. The host owns
+ * enforcement of every mandatory sandbox boundary and therefore supplies no caller-controlled
+ * boundary list. Adapters/providers receive only the resulting opaque capability.
+ *
+ * @internal host integration only
+ */
+export function createHostIssuedLabRouteExecutor(execute: LabRouteExecutor): TrustedLabRouteExecutor {
+  const capability: TrustedLabRouteExecutor = Object.freeze({
+    execute,
+    enforcedBoundaries: Object.freeze([...REQUIRED_LAB_SANDBOX_BOUNDARIES]),
+  });
+  HOST_ISSUED_EXECUTORS.add(capability);
+  return capability;
+}
+
+/** Internal recognition check consumed by the read-only authority facade. */
+export function isHostIssuedLabRouteExecutor(value: unknown): value is TrustedLabRouteExecutor {
+  if (typeof value !== "object" || value === null || !HOST_ISSUED_EXECUTORS.has(value as object)) return false;
+  const capability = value as TrustedLabRouteExecutor;
+  return capability.enforcedBoundaries.length === REQUIRED_LAB_SANDBOX_BOUNDARIES.length
+    && REQUIRED_LAB_SANDBOX_BOUNDARIES.every((boundary, index) => capability.enforcedBoundaries[index] === boundary);
+}

package/src/lib/lab-live-pinned-sender.ts

@@ -0,0 +1,56 @@
+import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
+import { TransportError } from "../lab/live/transport";
+import type { LabCredentialLeaseV1, LabPinnedSender } from "../lab/live/types";
+
+/** Only response metadata required by current live assertions crosses into Lab. */
+const LAB_RESPONSE_HEADER_ALLOWLIST = ["content-type"] as const;
+
+/**
+ * Trusted credential/transport owner. Secret headers exist only in this non-Lab module and are
+ * consumed directly by the pinned HTTP primitive; they are never returned to Lab code.
+ */
+export function createLabAuthorizedPinnedSender(
+  authorize: (lease: LabCredentialLeaseV1) => Promise<HeadersInit> | HeadersInit,
+): LabPinnedSender {
+  return async (lease, destination, pinned, request, signal, limits) => {
+    const headers = await authorize(lease);
+    const url = `${destination.scheme}://${destination.host}:${destination.port}${destination.basePath}${request.path}`;
+    const options = {
+      headers,
+      maxBytes: limits.maxOutputBytes,
+      connectTimeoutMs: limits.connectTimeoutMs,
+      firstByteTimeoutMs: limits.firstByteTimeoutMs,
+      inactivityTimeoutMs: limits.inactivityTimeoutMs,
+      rejectUnauthorized: true,
+      context: "Lab provider response",
+    };
+    let response: Response;
+    let body: string;
+    try {
+      response = request.method === "POST"
+        ? await pinnedHttpPost(url, pinned, request.body ?? "", signal, options)
+        : await pinnedHttpGet(url, pinned, signal, options);
+      body = await response.text();
+    } catch (error) {
+      if (error instanceof PinnedHttpError) {
+        switch (error.code) {
+          case "connect_timeout":
+            throw new TransportError("connect_timeout", "pinned provider connection timed out");
+          case "first_byte_timeout":
+            throw new TransportError("first_byte_timeout", "pinned provider first byte timed out");
+          case "inactivity_timeout":
+            throw new TransportError("inactivity_timeout", "pinned provider response stalled");
+          case "output_byte_limit":
+            throw new TransportError("output_byte_limit", "pinned provider response exceeded byte budget");
+        }
+      }
+      throw error;
+    }
+    const responseHeaders: Record<string, string> = {};
+    for (const headerName of LAB_RESPONSE_HEADER_ALLOWLIST) {
+      const value = response.headers.get(headerName);
+      if (value !== null) responseHeaders[headerName] = value;
+    }
+    return { status: response.status, headers: responseHeaders, body };
+  };
+}