@k2b/cloud 0.37.0 → 0.39.0

package/src/contracts/app.ts

@@ -58,6 +58,7 @@ export type AppAdminNavigationGroup = {
 
 export type AppPresentationTranslation = {
   name?: string;
+  panelLabel?: string;
   description?: string;
   /** Group labels keyed by `adminNav[].id`. */
   adminGroups?: Readonly<Record<string, string>>;
@@ -107,6 +108,18 @@ export type AppPwaPart = {
   requiresRoles?: Role[];
 };
 
+/** One same-origin panel page contributed by an application. Routes and services still authorize. */
+export type AppPanel = {
+  /** GET page below the app's routes, rendered with PanelLayout. */
+  href: string;
+  /** Panel name in the app's base locale; translated with presentation.translations[locale].panelLabel. */
+  label: string;
+  /** Icon class, for example "ti ti-sparkles". */
+  icon: string;
+  /** Coarse visibility like nav.requiresRoles; the slot grants no access. */
+  requiresRoles?: Role[];
+};
+
 export type AppMeta = {
   platformPermissions?: readonly PlatformPermission[];
   id: string;
@@ -142,6 +155,7 @@ export type AppMeta = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's pages in the installable mobile app (preview), at `href` = `/pwa/<id>`. */
   pwa?: AppPwaPart;
+  panel?: AppPanel;
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).

package/src/contracts/file-provider.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { CapabilityManifest } from "./capabilities";
+import { type CapabilityManifest, CloudResourceRefSchema } from "./capabilities";
 import { type CapabilityContract, type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
 
 /**
@@ -34,6 +34,26 @@ export const FileProviderListInputSchema = z
   })
   .strict();
 
+/** Caller hints are bounded independently of provider pagination. */
+export const FILE_PROVIDER_CONTEXT_MAX_REFS = 20;
+export const FileProviderContextSchema = z
+  .object({
+    refs: z
+      .array(CloudResourceRefSchema)
+      .max(FILE_PROVIDER_CONTEXT_MAX_REFS)
+      .describe(
+        "Hints about what the caller works on, for example the contacts a mail goes to; never a permission. Empty means nothing resolved.",
+      ),
+  })
+  .strict()
+  .describe("Caller resource hints, never a permission or proof of access.");
+export const FileProviderContextListInputSchema = FileProviderListInputSchema.extend({
+  context: FileProviderContextSchema.optional().describe(
+    "Optional caller context; keep it unchanged with cursor like parent, query and limit.",
+  ),
+}).strict();
+export type FileProviderContext = z.output<typeof FileProviderContextSchema>;
+
 const entryFacts = {
   id: ProviderIdSchema,
   name: z.string().min(1).max(255),
@@ -123,6 +143,33 @@ export const fileProvider = {
   },
 } as const satisfies Record<string, CapabilityContract>;
 
+/** Optional context-aware list contract; the base provider contract stays unchanged. */
+export const fileProviderContextList = { ...fileProvider.list, input: FileProviderContextListInputSchema } satisfies CapabilityContract;
+
+/** Only explicitly named, compatible context inputs opt in; open input objects do not. */
+export const fileProviderAcceptsContext = (manifest: CapabilityManifest): boolean => {
+  if (!manifest.fileProvider) return false;
+  const operation = manifest.queries.find((query) => query.localId === manifest.fileProvider?.list);
+  if (!operation) return false;
+  const root = operation.inputSchema;
+  let schema: unknown = root;
+  const visited = new Set<unknown>();
+  const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+  while (object(schema) && typeof schema.$ref === "string") {
+    if (visited.has(schema)) return false;
+    visited.add(schema);
+    if (!schema.$ref.startsWith("#/$defs/")) return false;
+    const defs = root.$defs;
+    schema = object(defs) ? defs[schema.$ref.slice(8)] : undefined;
+  }
+  return (
+    object(schema) &&
+    object(schema.properties) &&
+    Object.hasOwn(schema.properties, "context") &&
+    capabilityContractIssues(fileProviderContextList, { kind: "query", operation }).length === 0
+  );
+};
+
 export type FileProviderFunction = keyof typeof fileProvider;
 export const FILE_PROVIDER_FUNCTIONS = ["list", "read", "save"] as const satisfies readonly FileProviderFunction[];
 

package/src/contracts/outgoing-mail.ts

@@ -96,7 +96,14 @@ export const MailErrorCodeSchema = z.enum([
   "smtp_failed",
 ]);
 export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
-export const MailBounceErrorCodeSchema = z.enum(["open_failed", "search_failed", "apply_failed", "save_failed", "interrupted"]);
+export const MailBounceErrorCodeSchema = z.enum([
+  "open_failed",
+  "target_blocked",
+  "search_failed",
+  "apply_failed",
+  "save_failed",
+  "interrupted",
+]);
 export type MailBounceErrorCode = z.infer<typeof MailBounceErrorCodeSchema>;
 export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true, imap: true }).extend({
   key: MailProfileKeySchema,

package/src/contracts/registry.ts

@@ -1,4 +1,4 @@
-import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
+import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPanel, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
@@ -103,6 +103,8 @@ export type AppRegistryEntry = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */
   pwa?: AppRegistryPwaPart;
+  /** Optional panel declaration; older readers ignore it. */
+  panel?: AppPanel;
   widgets?: AppRegistryWidget[];
   /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
   settingKeys?: readonly string[];

package/src/contracts/shared.ts

@@ -401,6 +401,8 @@ export type SettingEntry = {
   valueSource: SettingValueSource;
   resetValueSource: Exclude<SettingValueSource, "custom">;
   isCustom: boolean;
+  /** A stored row exists but this application cannot decrypt or validate it; `value` is the fallback in use. */
+  unreadable: boolean;
   templateVars?: string[];
   options?: SettingOption[];
   min?: number;

package/src/server/help.ts

@@ -1,20 +1,48 @@
+import { formatShortcut } from "@k2b/ui";
 import { Hono } from "hono";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
-import { type HelpDocumentManifest, type HelpDocumentPayload, type HelpSearchPayload, helpLocaleChain } from "../shared/help";
-import { markdownToPlainText, renderHelpMarkdown } from "../shared/markdown";
+import { helpLinkTargets } from "../_internal/help";
+import { helpAgentMarkdown } from "../_internal/help-catalog";
+import {
+  HELP_ACCESS_LEVELS,
+  HELP_KINDS,
+  HELP_REFERENCE_PATTERN,
+  type HelpDocumentManifest,
+  type HelpDocumentPayload,
+  type HelpKind,
+  type HelpSearchPayload,
+  helpLocaleChain,
+  parseHelpReference,
+} from "../shared/help";
+import { helpHtmlToPlainText, lexHelpMarkdown, renderHelpMarkdown, walkHelpTokens } from "../shared/markdown";
 import { auth } from "./middleware/auth";
 
+// A help: target in a Markdown link or definition, an autolink, or an attribute value inside an HTML tag.
+const RAW_HELP_TARGET = /(?:(?:\]\(|\]:)\s*<?|<|<[^>]*\s[\w:-]+\s*=\s*["']?)\s*help:/i;
+
 const metadataSchema = z.object({
   id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
   title: z.string().trim().min(1),
   icon: z.string().trim().min(1).optional(),
   description: z.string().trim().min(1).optional(),
   order: z.number().int().optional(),
+  kind: z.enum(HELP_KINDS).optional(),
+  needs: z.enum(HELP_ACCESS_LEVELS).optional(),
+  next: z
+    .string()
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+    .optional(),
+  related: z
+    .array(z.string().regex(HELP_REFERENCE_PATTERN))
+    .refine((refs) => new Set(refs).size === refs.length, "Duplicate related Help reference")
+    .optional(),
 });
 
-export type HelpDefinitionDocument = Omit<z.infer<typeof metadataSchema>, "order"> & {
+export type HelpDefinitionDocument = Omit<z.infer<typeof metadataSchema>, "order" | "kind" | "related"> & {
   order: number;
+  kind: HelpKind;
+  related: readonly string[];
   markdown: string;
   html: string;
   searchText: string;
@@ -34,7 +62,7 @@ export type HelpCollection = {
   getMarkdown: (id: string) => string | undefined;
 };
 
-type ParsedHelpDocument = Omit<HelpDefinitionDocument, "order"> & { order?: number };
+type ParsedHelpDocument = z.infer<typeof metadataSchema> & Pick<HelpDefinitionDocument, "markdown" | "html" | "searchText">;
 
 const parseSource = (source: string, locale: string): ParsedHelpDocument => {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
@@ -43,12 +71,13 @@ const parseSource = (source: string, locale: string): ParsedHelpDocument => {
   const metadata = metadataSchema.parse(parseYaml(match[1]!));
   const markdown = match[2]!.trim();
   if (!markdown) throw new Error(`Help document "${metadata.id}" has no body`);
+  const html = renderHelpMarkdown(markdown, { locale });
 
   return {
     ...metadata,
     markdown,
-    html: renderHelpMarkdown(markdown, locale),
-    searchText: markdownToPlainText(markdown),
+    html,
+    searchText: helpHtmlToPlainText(html),
   };
 };
 
@@ -69,12 +98,27 @@ const parseDocuments = (
     .map((source) => parseSource(source, locale))
     .map((document): HelpDefinitionDocument => {
       const base = baseById?.get(document.id);
-      if (!baseById) return { ...document, order: document.order ?? 100 };
+      if (!baseById)
+        return { ...document, order: document.order ?? 100, kind: document.kind ?? "task", related: Object.freeze(document.related ?? []) };
       if (!base) throw new Error(`Help locale "${locale}" contains unknown document id "${document.id}"`);
       if ((document.icon !== undefined && document.icon !== base.icon) || (document.order !== undefined && document.order !== base.order)) {
         throw new Error(`Help locale "${locale}" must preserve icon and order for document "${document.id}"`);
       }
-      return { ...document, icon: base.icon, description: document.description ?? base.description, order: base.order };
+      for (const field of ["kind", "needs", "next", "related"] as const) {
+        if (document[field] !== undefined && JSON.stringify(document[field]) !== JSON.stringify(base[field])) {
+          throw new Error(`Help locale "${locale}" must preserve ${field} for document "${document.id}"`);
+        }
+      }
+      return {
+        ...document,
+        icon: base.icon,
+        description: document.description ?? base.description,
+        order: base.order,
+        kind: base.kind,
+        needs: base.needs,
+        next: base.next,
+        related: base.related,
+      };
     })
     .sort((a, b) => a.order - b.order || a.title.localeCompare(b.title))
     .map((document) => Object.freeze(document));
@@ -116,6 +160,82 @@ export const defineHelp = (
     documentsByLocale[locale] = parseDocuments(sources, locale, baseById);
   }
 
+  for (const [locale, localizedDocuments] of Object.entries(documentsByLocale)) {
+    for (const document of localizedDocuments) {
+      const validate = (reference: string, field: string) => {
+        const ref = parseHelpReference(reference);
+        if (!ref || (!ref.appId && !baseById.has(ref.documentId))) {
+          throw new Error(`Help locale "${locale}" document "${document.id}" has unknown ${field} reference "${reference}"`);
+        }
+      };
+      if (document.next === document.id)
+        throw new Error(`Help locale "${locale}" document "${document.id}" must not reference itself in next`);
+      if (document.next) validate(document.next, "next");
+      for (const reference of document.related) validate(reference, "related");
+      const unreadableLink = () =>
+        new Error(
+          `Help document "${document.id}" has a help: link that agents cannot read in locale "${locale}"; write it inline as [text](help:id)`,
+        );
+      const tokens = lexHelpMarkdown(document.markdown, locale);
+      const targets: string[] = [];
+      if (Object.values(tokens.links).some((link) => /^help:/i.test(link.href) && !link.href.startsWith("help:"))) throw unreadableLink();
+      walkHelpTokens(tokens, (token) => {
+        if (
+          (token.type === "link" && /^help:/i.test(token.href) && (!token.href.startsWith("help:") || !token.raw.startsWith("["))) ||
+          (token.type === "image" && /^help:/i.test(token.href)) ||
+          (token.type === "html" && RAW_HELP_TARGET.test(token.raw))
+        )
+          throw unreadableLink();
+        if ((token.type === "paragraph" || token.type === "text") && token.tokens?.length) {
+          let prose = token.raw;
+          // Keep line positions while excluding multiline code spans from the author contract.
+          walkHelpTokens(token.tokens, (child) => {
+            if (child.type === "codespan") prose = prose.replaceAll(child.raw, child.raw.replace(/[^\r\n]/g, "x"));
+          });
+          const block = /^ {0,3}:::(details|steps|reference|compare)(?=[ \t\r]|$)/m.exec(prose);
+          if (block) {
+            const missing =
+              block[1] === "details" ? "a blank line before it, a title, or a closing :::" : "a blank line before it or a closing :::";
+            throw new Error(`Help document "${document.id}" has a :::${block[1]} block without ${missing} in locale "${locale}"`);
+          }
+        }
+        if (token.type === "link" && token.href.startsWith("help:")) {
+          const target = token.href.slice(5);
+          validate(target, "help:");
+          targets.push(target);
+        }
+        // Callouts do not render inside details, and a warning must stay where the reader sees it.
+        if (token.type === "helpDetails" && token.callout === true) {
+          throw new Error(
+            `Help document "${document.id}" has a callout inside details in locale "${locale}"; place it outside the details`,
+          );
+        }
+        if (token.type === "helpKbd" && formatShortcut(String(token.keys), { platform: "other", locale }).keys.length === 0) {
+          throw new Error(`Help document "${document.id}" has an invalid key shortcut "${token.keys}" in locale "${locale}"`);
+        }
+      });
+      // Unconverted Help syntax and targets fail here instead of reaching agents.
+      const agentTokens = lexHelpMarkdown(helpAgentMarkdown({ markdown: document.markdown, locale, appId: "", links: {} }, tokens), locale);
+      let unconvertedLink = Object.values(agentTokens.links).some((link) => link.href.startsWith("help:"));
+      let unconvertedSyntax = false;
+      walkHelpTokens(agentTokens, (token) => {
+        if (
+          (token.type === "link" && token.href.startsWith("help:")) ||
+          // Markdown inside raw HTML and callout titles stays text in agent text, so its target would reach readers.
+          (token.type === "html" && RAW_HELP_TARGET.test(token.raw)) ||
+          (token.type === "markdownInfoBlock" && typeof token.title === "string" && RAW_HELP_TARGET.test(token.title))
+        )
+          unconvertedLink = true;
+        if (token.type === "helpKbd" || token.type === "helpLabel" || token.type === "helpDetails") unconvertedSyntax = true;
+      });
+      if (unconvertedLink) throw unreadableLink();
+      if (unconvertedSyntax) {
+        throw new Error(`Help document "${document.id}" has Help syntax that agents cannot read in locale "${locale}"`);
+      }
+      helpLinkTargets.set(document, targets);
+    }
+  }
+
   return {
     baseLocale,
     documentsByLocale: Object.freeze(documentsByLocale),
@@ -135,6 +255,8 @@ export const defineHelp = (
  * IDs, ordering and ownership stay visible in code; no filesystem scanning or
  * build-time convention is required.
  *
+ * Its payload includes kind and needs, but no next and an empty related list: it has no page route to link to.
+ *
  * @deprecated Declare Help with `defineHelp()` and pass it to `app.start({ help })`. This router only
  * requires sign-in; it does not apply the app's Help visibility, so the mounting app's routes must guard it.
  */
@@ -145,12 +267,13 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
   const byId = new Map(documents.map((document) => [document.id, document]));
 
   const searchUrl = `${basePath}/search`;
-  const manifest = documents.map<HelpDocumentManifest>(({ id, title, icon, description, order }) => ({
+  const manifest = documents.map<HelpDocumentManifest>(({ id, title, icon, description, order, kind }) => ({
     id,
     title,
     icon,
     description,
     order,
+    kind,
     searchUrl,
     url: `${basePath}/${encodeURIComponent(id)}`,
   }));
@@ -180,8 +303,11 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
         locale: "en",
         id: document.id,
         title: document.title,
-        markdown: document.markdown,
+        markdown: helpAgentMarkdown({ markdown: document.markdown, locale: "en", appId: "", links: {} }),
         html: document.html,
+        kind: document.kind,
+        needs: document.needs,
+        related: [],
       };
       return context.json(payload);
     });

package/src/server/services/access.ts

@@ -629,7 +629,11 @@ export const listUsersWithAccess = async (params: {
         OR LOWER(uid) LIKE ${pattern} ESCAPE '\\'
         OR LOWER(group_names) LIKE ${pattern} ESCAPE '\\'
       )
-    ORDER BY LOWER(display_name), id
+    -- A limit must never hide an exact login-name match.
+    ORDER BY
+      CASE WHEN LOWER(uid) = ${query || null}::text THEN 0 ELSE 1 END,
+      CASE WHEN LOWER(display_name) = ${query || null}::text THEN 0 ELSE 1 END,
+      LOWER(display_name), id
     LIMIT ${limit}
   `;
 

package/src/server/services/geo.ts

@@ -1,6 +1,13 @@
 import { err, fail, ok, type PageParams, type Paginated, paginate, type Result } from "@k2b/stdlib";
 import { z } from "zod";
 import { readBoundedJson } from "../../_internal/bounded-json";
+import { env } from "../../config/env";
+import { createAllowedNetworkFetch } from "../../services/allowed-network-fetch";
+import { logger } from "../../services/logging";
+import { NetworkTargetBlockedError } from "../../services/network-security";
+import { parseNetworkAllowlistEnv } from "../../shared/network-address";
+
+export const geoAllowlist = () => parseNetworkAllowlistEnv("GEO_ALLOWED_TARGETS", env.GEO_ALLOWED_TARGETS);
 
 const GEO_TIMEOUT_MS = 2_000;
 const GEO_MAX_RESPONSE_BYTES = 256 * 1024;
@@ -118,8 +125,11 @@ const list = async (config: {
   }
 
   try {
-    const res = await fetch(`${baseUrlResult.data}/geo/search?${params}`, { signal: geoSignal(config.signal) });
+    const res = await createAllowedNetworkFetch(geoAllowlist())(`${baseUrlResult.data}/geo/search?${params}`, {
+      signal: geoSignal(config.signal),
+    });
     if (!res.ok) {
+      await res.body?.cancel();
       return unavailable();
     }
 
@@ -152,7 +162,9 @@ const list = async (config: {
       total: filtered.length,
       hasNext: page * perPage < filtered.length,
     });
-  } catch {
+  } catch (error) {
+    if (error instanceof NetworkTargetBlockedError)
+      logger("geo").warn("Geo target is on an internal network. An operator can allow it with GEO_ALLOWED_TARGETS.");
     return unavailable();
   }
 };
@@ -165,8 +177,11 @@ const get = async (config: { baseUrl: string; lat: number; lon: number }): Promi
   if (!baseUrlResult.ok) return baseUrlResult;
 
   try {
-    const res = await fetch(`${baseUrlResult.data}/geo/reverse?lat=${config.lat}&lng=${config.lon}`, { signal: geoSignal() });
+    const res = await createAllowedNetworkFetch(geoAllowlist())(`${baseUrlResult.data}/geo/reverse?lat=${config.lat}&lng=${config.lon}`, {
+      signal: geoSignal(),
+    });
     if (!res.ok) {
+      await res.body?.cancel();
       return unavailable();
     }
 
@@ -181,7 +196,9 @@ const get = async (config: { baseUrl: string; lat: number; lon: number }): Promi
       .find((place): place is GeoPlace => place !== null);
 
     return ok(first ?? null);
-  } catch {
+  } catch (error) {
+    if (error instanceof NetworkTargetBlockedError)
+      logger("geo").warn("Geo target is on an internal network. An operator can allow it with GEO_ALLOWED_TARGETS.");
     return unavailable();
   }
 };

package/src/services/accounts/posix.ts

@@ -329,7 +329,8 @@ export const createPosixRuntime = (db: typeof sql = sql, readRanges = readIpaIdR
         // Same order as provisioning; settings write upgrades this lock in the same transaction.
         await lock(tx);
         if (parsed.data.enabled) await checkRange(tx, parsed.data, ranges);
-        await settings.set(CONFIG_KEY, JSON.stringify(parsed.data), tx);
+        // complete value from explicit admin input; nothing is merged over a read (#1303)
+        await settings.set(CONFIG_KEY, JSON.stringify(parsed.data), tx, { replaceUnreadable: true });
         await audit.record(
           {
             action: "accounts.linux.configure",

package/src/services/allowed-network-fetch.ts

@@ -0,0 +1,189 @@
+import { type ClientRequest, request as httpRequest, type IncomingMessage, type RequestOptions } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { type NetworkAllowlist, networkAddressFamily, normalizeNetworkHostname } from "../shared/network-address";
+import { type NetworkLookup, pinnedNetworkLookup, resolveAllowedNetworkAddresses } from "./network-security";
+
+type RequestFactory = (options: RequestOptions, callback: (response: IncomingMessage) => void) => ClientRequest;
+type AllowedNetworkFetchDeps = {
+  lookup?: NetworkLookup;
+  resolve?: typeof resolveAllowedNetworkAddresses;
+  request?: RequestFactory;
+};
+
+/**
+ * Fetch-compatible HTTP transport for operator-allowlisted targets. Resolves and
+ * pins every request, without proxies, retries, decompression or its own timeout.
+ * Never follows redirects: `redirect: "error"` rejects any 3xx; otherwise returns
+ * that response unchanged. The caller owns deadlines and response consumption.
+ */
+export const createAllowedNetworkFetch =
+  (allowlist: NetworkAllowlist, deps: AllowedNetworkFetchDeps = {}) =>
+  async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Network target must use HTTP or HTTPS");
+    if (url.username || url.password) throw new TypeError("Network target must not include user information");
+    const signal = request.signal;
+    signal.throwIfAborted();
+    const addresses = await new Promise<Awaited<ReturnType<typeof resolveAllowedNetworkAddresses>>>((resolve, reject) => {
+      const abort = () => reject(signal.reason);
+      signal.addEventListener("abort", abort, { once: true });
+      (deps.resolve ?? resolveAllowedNetworkAddresses)(url.hostname, allowlist, deps.lookup)
+        .then(resolve, reject)
+        .finally(() => signal.removeEventListener("abort", abort));
+      if (signal.aborted) abort();
+    });
+    signal.throwIfAborted();
+    // A body of known size goes out with Content-Length; only a caller's stream (in init or an input Request) is chunked.
+    const streamed = init?.body != null ? init.body instanceof ReadableStream : input instanceof Request && input.body !== null;
+    const payload = request.body && !streamed ? new Uint8Array(await request.arrayBuffer()) : undefined;
+    signal.throwIfAborted();
+    return new Promise<Response>((resolve, reject) => {
+      const headers = new Headers(request.headers);
+      headers.set("host", url.host);
+      headers.set("accept-encoding", "identity");
+      if (payload) headers.set("content-length", String(payload.byteLength));
+      let response: IncomingMessage | undefined;
+      let upload: ReadableStreamDefaultReader<Uint8Array> | undefined;
+      let bodyController: ReadableStreamDefaultController<Uint8Array> | undefined;
+      const cleanup = () => signal.removeEventListener("abort", abort);
+      const fail = (error: Error) => {
+        reject(error);
+        bodyController?.error(error);
+        bodyController = undefined;
+        response?.destroy();
+        void upload?.cancel(error).catch(() => {});
+        outgoing.destroy(error);
+        cleanup();
+      };
+      const abort = () => fail(signal.reason);
+      const outgoing = (deps.request ?? (url.protocol === "https:" ? httpsRequest : httpRequest))(
+        {
+          protocol: url.protocol,
+          hostname: normalizeNetworkHostname(url.hostname),
+          port: url.port || undefined,
+          path: `${url.pathname}${url.search}`,
+          method: request.method,
+          headers: Object.fromEntries(headers),
+          servername: url.protocol === "https:" && !networkAddressFamily(url.hostname) ? normalizeNetworkHostname(url.hostname) : undefined,
+          lookup: pinnedNetworkLookup(addresses),
+          agent: false,
+        } satisfies RequestOptions & { servername?: string },
+        (incoming) => {
+          response = incoming;
+          incoming.once("close", cleanup);
+          incoming.once("error", (error) => {
+            reject(error);
+            bodyController?.error(error);
+            bodyController = undefined;
+          });
+          const status = incoming.statusCode ?? 0;
+          if (request.redirect === "error" && status >= 300 && status < 400) {
+            fail(new TypeError(`Network target returned HTTP ${status} redirect`));
+            return;
+          }
+          const encoding = incoming.headers["content-encoding"];
+          if (encoding && encoding.trim().toLowerCase() !== "identity") {
+            fail(new TypeError("Network target returned an unsupported content encoding"));
+            return;
+          }
+          const responseHeaders = new Headers();
+          for (let i = 0; i < incoming.rawHeaders.length; i += 2)
+            responseHeaders.append(incoming.rawHeaders[i]!, incoming.rawHeaders[i + 1]!);
+          const empty = request.method === "HEAD" || [204, 205, 304].includes(status);
+          const iterator = incoming[Symbol.asyncIterator]();
+          const body = empty
+            ? null
+            : new ReadableStream<Uint8Array>({
+                start(controller) {
+                  bodyController = controller;
+                },
+                async pull(controller) {
+                  try {
+                    const chunk = await iterator.next();
+                    if (!bodyController) return;
+                    if (chunk.done) {
+                      bodyController = undefined;
+                      controller.close();
+                      cleanup();
+                    } else controller.enqueue(new Uint8Array(chunk.value));
+                  } catch (error) {
+                    if (bodyController) {
+                      bodyController = undefined;
+                      controller.error(error);
+                    }
+                    outgoing.destroy();
+                    cleanup();
+                  }
+                },
+                cancel() {
+                  bodyController = undefined;
+                  incoming.destroy();
+                  outgoing.destroy();
+                  cleanup();
+                },
+              });
+          try {
+            resolve(new Response(body, { status, statusText: incoming.statusMessage, headers: responseHeaders }));
+            if (empty) incoming.resume();
+          } catch (error) {
+            fail(error instanceof Error ? error : new Error(String(error)));
+          }
+        },
+      );
+      outgoing.once("close", () => {
+        void upload?.cancel().catch(() => {});
+      });
+      outgoing.once("error", (error) => {
+        reject(error);
+        bodyController?.error(error);
+        bodyController = undefined;
+        response?.destroy();
+        cleanup();
+      });
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      if (payload) {
+        outgoing.end(payload);
+        return;
+      }
+      void (async () => {
+        const reader = request.body?.getReader();
+        upload = reader;
+        try {
+          if (reader) {
+            while (true) {
+              const chunk = await reader.read();
+              if (chunk.done) break;
+              if (outgoing.destroyed) break;
+              if (!outgoing.write(chunk.value))
+                await new Promise<void>((resolve, reject) => {
+                  const closed = () => {
+                    clear();
+                    reject(new Error("Request closed"));
+                  };
+                  const drained = () => {
+                    clear();
+                    resolve();
+                  };
+                  const clear = () => {
+                    outgoing.off("close", closed);
+                    outgoing.off("drain", drained);
+                  };
+                  outgoing.once("drain", drained);
+                  outgoing.once("close", closed);
+                });
+            }
+          }
+          outgoing.end();
+        } catch (error) {
+          fail(error instanceof Error ? error : new Error(String(error)));
+        } finally {
+          await reader?.cancel().catch(() => {});
+        }
+      })();
+    });
+  };