@nimbus-dev/connectors 0.5.0 → 0.7.0

package/connectors/slack/src/tools.ts

@@ -102,9 +102,17 @@ export const SLACK_TOOL_NAMES = [
   "slack_message_post_dm",
   "slack_user_info",
   "slack_chat_post",
+  "slack_views_open",
   "slack_socket_open",
 ] as const;
 
+/** Largest serialised `blocks` array / `view` object Slack accepts from this connector (16 KiB). */
+export const SLACK_PAYLOAD_MAX_BYTES = 16 * 1024;
+
+function serialisedBytes(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+
 export function registerSlackTools(
   server: ConsentServer & { tool: (...args: never) => unknown },
 ): void {
@@ -122,7 +130,7 @@ export function registerSlackTools(
     scopeEnv: "NIMBUS_MCP_SLACK_WRITE_SCOPE",
     // `user` scopes a direct message by the recipient's user id, which is all a DM has before
     // `conversations.open` creates its channel.
-    scopeKinds: ["channel", "user"],
+    scopeKinds: ["channel", "user", "view"],
   });
 
   const slackChannelListSchema = z.object({
@@ -341,7 +349,19 @@ export function registerSlackTools(
       ),
   );
 
-  const slackChatPostSchema = z.object({ channel: z.string().min(1), text: z.string().min(1) });
+  const slackChatPostSchema = z.object({
+    channel: z.string().min(1),
+    text: z.string().min(1),
+    // Block Kit blocks, sent to Slack verbatim beside `text` (which stays the notification fallback).
+    blocks: z
+      .array(z.looseObject({ type: z.string() }))
+      .min(1)
+      .max(50)
+      .refine((b) => serialisedBytes(b) <= SLACK_PAYLOAD_MAX_BYTES, {
+        message: `blocks must serialise to at most ${SLACK_PAYLOAD_MAX_BYTES} bytes`,
+      })
+      .optional(),
+  });
   registerWriteTool(
     "slack_chat_post",
     {
@@ -351,12 +371,43 @@ export function registerSlackTools(
     },
     "Post an operational bot message to a channel (ChatOps reply surface; bot token).",
     slackChatPostSchema,
-    async (parsed) =>
-      slackInvokeJsonWithToken(
+    async (parsed) => {
+      const body: Record<string, unknown> = { channel: parsed.channel, text: parsed.text };
+      if (parsed.blocks !== undefined) {
+        body["blocks"] = parsed.blocks;
+      }
+      return slackInvokeJsonWithToken(
         requireProcessEnv("SLACK_BOT_TOKEN"),
         "chat.postMessage",
-        { channel: parsed.channel, text: parsed.text },
+        body,
         "Slack chat.postMessage",
+      );
+    },
+  );
+
+  const slackViewsOpenSchema = z.object({
+    trigger_id: z.string().min(1),
+    view: z
+      .looseObject({ type: z.literal("modal") })
+      .refine((v) => serialisedBytes(v) <= SLACK_PAYLOAD_MAX_BYTES, {
+        message: `view must serialise to at most ${SLACK_PAYLOAD_MAX_BYTES} bytes`,
+      }),
+  });
+  registerWriteTool(
+    "slack_views_open",
+    {
+      mutates: "slack.views.open",
+      recoverable: true,
+      scopeTargetOf: () => ({ kind: "view", value: "modal" }),
+    },
+    "Open a confirmation modal for a user who clicked a ChatOps card button (ChatOps operational surface; bot token).",
+    slackViewsOpenSchema,
+    async (parsed) =>
+      slackInvokeJsonWithToken(
+        requireProcessEnv("SLACK_BOT_TOKEN"),
+        "views.open",
+        { trigger_id: parsed.trigger_id, view: parsed.view },
+        "Slack views.open",
       ),
   );
 

package/connectors/teams/src/bot-send.ts

@@ -55,10 +55,14 @@ function serviceUrlBase(): string {
   return base.endsWith("/") ? base : `${base}/`;
 }
 
-/** Send a plain-text message activity to a Teams conversation via the Bot Framework. */
+/**
+ * Send a message activity to a Teams conversation via the Bot Framework. `attachments` (an Adaptive
+ * Card) goes into the activity body only when given.
+ */
 export async function teamsBotSendActivity(
   conversationId: string,
   text: string,
+  attachments?: readonly unknown[],
 ): Promise<GraphLikeResult> {
   const appId = requireProcessEnv("TEAMS_BOT_APP_ID");
   const appPassword = requireProcessEnv("TEAMS_BOT_APP_PASSWORD");
@@ -67,6 +71,10 @@ export async function teamsBotSendActivity(
   return fetchBearerAuthorizedJson(url, token, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ type: "message", text }),
+    body: JSON.stringify(
+      attachments === undefined
+        ? { type: "message", text }
+        : { type: "message", text, attachments },
+    ),
   });
 }

package/connectors/teams/src/tools.ts

@@ -14,6 +14,9 @@ import {
 } from "../../../shared/mcp-tool-kit.ts";
 import { teamsBotSendActivity } from "./bot-send.ts";
 
+/** Largest serialised `attachments` array `teams_chat_post` accepts (28 KiB). */
+export const TEAMS_ATTACHMENTS_MAX_BYTES = 28 * 1024;
+
 const GRAPH = "https://graph.microsoft.com/v1.0";
 
 async function graphRequest(
@@ -265,6 +268,20 @@ export function registerTeamsTools(
   const teamsChatPostSchema = z.object({
     conversationId: z.string().min(1),
     text: z.string().min(1),
+    // Exactly one Adaptive Card, sent in the activity verbatim; at most 28 KiB serialised.
+    attachments: z
+      .array(
+        z.object({
+          contentType: z.literal("application/vnd.microsoft.card.adaptive"),
+          content: z.record(z.string(), z.unknown()),
+        }),
+      )
+      .length(1)
+      .refine(
+        (a) => new TextEncoder().encode(JSON.stringify(a)).length <= TEAMS_ATTACHMENTS_MAX_BYTES,
+        { message: `attachments must serialise to at most ${TEAMS_ATTACHMENTS_MAX_BYTES} bytes` },
+      )
+      .optional(),
   });
   registerWriteTool(
     "teams_chat_post",
@@ -276,7 +293,7 @@ export function registerTeamsTools(
     "Post an operational bot message to a Teams conversation (ChatOps reply surface; bot app creds).",
     teamsChatPostSchema,
     async (parsed) => {
-      const r = await teamsBotSendActivity(parsed.conversationId, parsed.text);
+      const r = await teamsBotSendActivity(parsed.conversationId, parsed.text, parsed.attachments);
       return graphListResult(r);
     },
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },

package/shared/env-json-api.ts

@@ -38,6 +38,7 @@
  * fail with "X_TOKEN is not set" on the tool call rather than at startup.
  */
 
+import { guardedFetch } from "./guarded-fetch.ts";
 import { stripTrailingSlashes } from "./strip-trailing-slashes.ts";
 
 /** Body-snippet length in the thrown error. The value every connector used. */
@@ -156,7 +157,25 @@ function sendFor(
   const doFetch = config.fetch ?? ((url, init) => fetch(url, init));
   return async (path, init, errorPrefix) => {
     const root = typeof base === "string" ? base : base();
-    const res = await doFetch(`${root}${path}`, init(headers()));
+    // A credential must go only where the base names, and a runtime follows a 3xx by default
+    // (re-sending a custom header such as LaunchDarkly's bare Authorization or Flagsmith's Token
+    // to whatever Location says). So a mutation's 3xx is refused outright, and a GET follows only
+    // a same-origin Location or the same host's http -> https upgrade, at most 3 hops, each hop asked for manually.
+    const reqInit = init(headers());
+    const url = `${root}${path}`;
+    const method = (reqInit.method ?? "GET").toUpperCase();
+    const res =
+      method === "GET" || method === "HEAD"
+        ? await guardedFetch(errorPrefix, url, reqInit, {
+            fetch: doFetch,
+            requireSecureBase: false,
+          })
+        : await doFetch(url, { ...reqInit, redirect: "manual" });
+    if (res.status >= 300 && res.status < 400) {
+      throw new Error(
+        `${errorPrefix}: the server answered with a redirect (${String(res.status)}); the write may or may not have been applied`,
+      );
+    }
     const text = await res.text();
     if (!res.ok) {
       throw new Error(`${errorPrefix} ${String(res.status)}: ${text.slice(0, snippetMax)}`);
@@ -180,30 +199,53 @@ export function createJsonGetter(config: JsonApiConfig): (path: string) => Promi
 }
 
 /**
- * The mutating twin of {@link createJsonGetter}: a `(path, body) => Promise<unknown>`
- * POST client that sends `body` as JSON (adding `Content-Type: application/json` to
- * the request headers) and resolves to the parsed response — `{}` when the response
- * body is empty, as a mutation's often is.
+ * A `(method, path, body, extraHeaders?) => Promise<unknown>` JSON client for any mutating verb
+ * (PATCH, PUT, DELETE, POST). `Content-Type: application/json` is the default and `extraHeaders`
+ * override it key for key (LaunchDarkly's semantic patch needs `application/json;
+ * domain-model=launchdarkly.semanticpatch`). Resolves to the parsed response, `{}` when empty.
  *
- * Throws `"<label> <path> <status>: <body snippet>"` on any non-2xx: unlike the
- * getter's, the message names the path, so a failed mutation says which endpoint
- * refused it. The argocd and mlflow write tools each carried a copy of this.
+ * Throws `"<errorPrefix> <status>: <body snippet>"`; the prefix defaults to
+ * `"<label> <method> <path>"` and is taken explicitly so {@link createJsonPoster} keeps its own
+ * `"<label> <path>"` format. A 3xx is refused, never followed (see `sendFor`).
  */
-export function createJsonPoster(
+export function createJsonSender(
   config: JsonApiConfig,
-): (path: string, body: unknown) => Promise<unknown> {
-  const { label } = config;
+  errorPrefix: (method: string, path: string) => string = (method, path) =>
+    `${config.label} ${method} ${path}`,
+): (
+  method: string,
+  path: string,
+  body: unknown,
+  extraHeaders?: Record<string, string>,
+) => Promise<unknown> {
   const send = sendFor(config);
-  return async (path: string, body: unknown): Promise<unknown> => {
+  return async (method, path, body, extraHeaders) => {
     const text = await send(
       path,
       (headers) => ({
-        method: "POST",
-        headers: { ...headers, "Content-Type": "application/json" },
+        method,
+        headers: { ...headers, "Content-Type": "application/json", ...extraHeaders },
         body: JSON.stringify(body),
       }),
-      `${label} ${path}`,
+      errorPrefix(method, path),
     );
     return text === "" ? {} : (JSON.parse(text) as unknown);
   };
 }
+
+/**
+ * The mutating twin of {@link createJsonGetter}: a `(path, body) => Promise<unknown>`
+ * POST client that sends `body` as JSON (adding `Content-Type: application/json` to
+ * the request headers) and resolves to the parsed response — `{}` when the response
+ * body is empty, as a mutation's often is.
+ *
+ * Throws `"<label> <path> <status>: <body snippet>"` on any non-2xx: unlike the
+ * getter's, the message names the path, so a failed mutation says which endpoint
+ * refused it. The argocd and mlflow write tools each carried a copy of this.
+ */
+export function createJsonPoster(
+  config: JsonApiConfig,
+): (path: string, body: unknown) => Promise<unknown> {
+  const send = createJsonSender(config, (_method, path) => `${config.label} ${path}`);
+  return (path: string, body: unknown): Promise<unknown> => send("POST", path, body);
+}

package/shared/github-rest.ts

@@ -8,8 +8,10 @@
  * places, so a bump had to find all three.
  */
 
+import { resolveUrlWithBase } from "@nimbus-dev/sdk/connector-kit";
 import { optionalBaseUrl } from "./env-json-api.ts";
-import { makeRestFetcher, type RestFetchResult } from "./rest-tool-kit.ts";
+import { guardedFetch } from "./guarded-fetch.ts";
+import { type RestFetchResult, toRestFetchResult } from "./rest-tool-kit.ts";
 
 export const GH_API = "https://api.github.com";
 
@@ -33,13 +35,42 @@ export const GH_HEADERS: Record<string, string> = {
   "X-GitHub-Api-Version": GH_API_VERSION,
 };
 
-/** A Bearer-authenticated JSON request against {@link ghApiBase} (a relative path or a same-origin URL). */
-export function ghFetch(token: string, path: string, init?: RequestInit): Promise<RestFetchResult> {
-  return makeRestFetcher({ apiBase: ghApiBase(), token, defaultHeaders: GH_HEADERS })(path, init);
+/**
+ * A Bearer-authenticated JSON request against {@link ghApiBase} (a relative path or a same-origin
+ * URL). It goes through {@link guardedFetch}: a write that GitHub answers with a redirect (a renamed
+ * or transferred repository) is refused, not replayed as a GET that would report a false success,
+ * and a GET follows only a same-origin https redirect, at most 3 hops.
+ */
+export async function ghFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<RestFetchResult> {
+  const url = resolveUrlWithBase(ghApiBase(), path);
+  const headers = new Headers({ Authorization: `Bearer ${token}`, ...GH_HEADERS });
+  if (init?.headers !== undefined) {
+    for (const [k, v] of new Headers(init.headers)) headers.set(k, v);
+  }
+  const res = await guardedFetch("GitHub", url, { ...init, headers }, { requireSecureBase: false });
+  return toRestFetchResult(res);
 }
 
-/** `/repos/<owner>/<repo>`, both segments URI-encoded. */
+/**
+ * Whether `seg` is a safe GitHub `owner` or `repo`: 1..100 of `[A-Za-z0-9._-]`, and not `.` or `..`
+ * (a URL parser collapses those out of the path, turning `/repos/../../pulls/9` into another endpoint).
+ */
+export function isSafeGhSlug(seg: string): boolean {
+  return /^[A-Za-z0-9._-]{1,100}$/.test(seg) && seg !== "." && seg !== "..";
+}
+
+/**
+ * `/repos/<owner>/<repo>`, both segments URI-encoded. `.` and `..` are refused: `encodeURIComponent`
+ * leaves them alone and a URL parser collapses them (`/repos/../../pulls/9`).
+ */
 export function ghRepoPath(owner: string, repo: string): string {
+  for (const seg of [owner, repo]) {
+    if (seg === "." || seg === "..") throw new Error("owner and repo cannot be a dot segment");
+  }
   return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
 }
 
@@ -71,3 +102,95 @@ export function ghQueryPath(path: string, setQuery: (params: URLSearchParams) =>
   setQuery(u.searchParams);
   return `${u.pathname}${u.search}`;
 }
+
+/**
+ * Whether `ref` is safe to place in a GitHub API path and to hand to GitHub as a ref name.
+ *
+ * A ref reaches a URL path, so a hostile one is a path-traversal vector (`../x` would climb out of
+ * `/commits/`). One rule for every ref the model supplies: 1..255 characters of
+ * `[A-Za-z0-9._/-]`, no `..`, no leading or trailing `/`, no `//`, no leading `-`, no segment that
+ * starts with `.` or ends with `.lock`, and no trailing `.`.
+ */
+export function isSafeGitRef(ref: string): boolean {
+  if (ref.length < 1 || ref.length > 255) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(ref)) return false;
+  if (ref.startsWith("/") || ref.endsWith("/") || ref.startsWith("-") || ref.endsWith(".")) {
+    return false;
+  }
+  if (ref.includes("//") || ref.includes("..")) return false;
+  return ref.split("/").every((seg) => !seg.startsWith(".") && !seg.endsWith(".lock"));
+}
+
+/** What a ref resolved to: the commit SHA, and whether the name was a branch, a tag or a SHA. */
+export interface ResolvedCommit {
+  readonly sha: string;
+  readonly kind: "branch" | "tag" | "sha";
+}
+
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+
+/**
+ * One `GET /commits/<ref>` with the SHA media type; `undefined` when the ref does not exist, a throw
+ * on anything else. GitHub answers a missing ref with a 422 ("No commit found for SHA: ..."), not a
+ * 404, so both count as not found; a 422 with any other message is a real error.
+ */
+async function commitShaFor(
+  token: string,
+  owner: string,
+  repo: string,
+  ref: string,
+): Promise<string | undefined> {
+  const segments = ref.split("/").map(encodeURIComponent).join("/");
+  const res = await ghFetch(token, `${ghRepoPath(owner, repo)}/commits/${segments}`, {
+    headers: { Accept: "application/vnd.github.sha" },
+  });
+  if (res.status === 404) return undefined;
+  if (res.status === 422 && /no commit found/i.test(res.text)) return undefined;
+  if (!res.ok) {
+    throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+  }
+  const sha = res.text.trim();
+  if (!FULL_SHA.test(sha)) {
+    throw new Error(`GitHub returned no commit sha for ref "${ref}"`);
+  }
+  return sha.toLowerCase();
+}
+
+/**
+ * The names to try for `ref`, in order. A `heads/` or `tags/` prefix (or the full `refs/heads/` /
+ * `refs/tags/`) is one candidate; a bare name is both. Always the full `refs/...` form: GitHub's
+ * `/commits/tags/<x>` answers 422 for an existing tag, while `/commits/refs/tags/<x>` resolves.
+ */
+function refCandidates(ref: string): { readonly name: string; readonly kind: "branch" | "tag" }[] {
+  if (ref.startsWith("refs/heads/")) return [{ name: ref, kind: "branch" }];
+  if (ref.startsWith("refs/tags/")) return [{ name: ref, kind: "tag" }];
+  if (ref.startsWith("heads/")) return [{ name: `refs/${ref}`, kind: "branch" }];
+  if (ref.startsWith("tags/")) return [{ name: `refs/${ref}`, kind: "tag" }];
+  return [
+    { name: `refs/heads/${ref}`, kind: "branch" },
+    { name: `refs/tags/${ref}`, kind: "tag" },
+  ];
+}
+
+/**
+ * Resolve a branch, tag or commit to a COMMIT sha. `ref` must already satisfy {@link isSafeGitRef}.
+ *
+ * A 40-hex string is returned as is. `heads/*` or `tags/*` is one GET. A bare name tries
+ * `refs/heads/<ref>` then `refs/tags/<ref>`, falling through only on a not-found (404, or 422 "No commit found"). It reads `/commits/<ref>` and not
+ * `/git/ref/<ref>` so an annotated tag is peeled to a commit (a branch cannot point at a tag object).
+ * The read tool and the write tool share this, so what a name means cannot differ between the
+ * before-state the owner saw and the write that runs.
+ */
+export async function resolveCommitSha(
+  token: string,
+  owner: string,
+  repo: string,
+  ref: string,
+): Promise<ResolvedCommit> {
+  if (FULL_SHA.test(ref)) return { sha: ref.toLowerCase(), kind: "sha" };
+  for (const c of refCandidates(ref)) {
+    const sha = await commitShaFor(token, owner, repo, c.name);
+    if (sha !== undefined) return { sha, kind: c.kind };
+  }
+  throw new Error(`GitHub 404: ref "${ref}" not found`);
+}

package/shared/guarded-fetch.ts

@@ -0,0 +1,135 @@
+/**
+ * guarded-fetch — a `fetch` that never lets a redirect carry a credential to another origin.
+ *
+ * A runtime follows a 3xx by default, and the Fetch spec strips only the `Authorization` header on
+ * a cross-origin hop: a custom credential header (GitLab's `PRIVATE-TOKEN`) goes along to whatever
+ * `Location` names. So every credentialed request here asks for `redirect: "manual"` and decides
+ * itself:
+ *
+ * - a redirect on a mutation (anything but GET/HEAD) is refused: replaying a write is not ours to
+ *   decide, and the credential must not follow it;
+ * - a redirect on a GET/HEAD is followed (at most {@link MAX_REDIRECT_HOPS} times) only when the
+ *   `Location` resolves to the SAME origin as the request, or is the same host's http -> https
+ *   upgrade (same hostname, same explicit port or both default); https -> http and any other
+ *   target is refused and nothing is sent there. The request headers (credentials included) are
+ *   re-sent unchanged, and only ever to that host;
+ * - a request to a plain-http origin that is not loopback is refused before it is sent, since it
+ *   would put the credential on the wire in clear.
+ */
+
+import { fetchWithTimeout } from "@nimbus-dev/sdk/connector-kit";
+
+/** Followed redirects allowed on one GET/HEAD; the next one is refused. */
+export const MAX_REDIRECT_HOPS = 3;
+
+/** Per-request timeout when the caller supplies no transport; the SDK's default for every connector. */
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+const REDIRECT_STATUSES: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+
+/** Throws unless `url` is https, or http to a loopback host. */
+function assertSecureTransport(label: string, url: URL): void {
+  if (url.protocol === "https:") return;
+  if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return;
+  throw new Error(`${label} base URL must be https (or loopback http); refused`);
+}
+
+export interface GuardedFetchOptions {
+  /** The transport to use. Defaults to the SDK's `fetchWithTimeout` (15 s per request, per hop). */
+  readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+  /**
+   * Refuse a first request to a plain-http, non-loopback origin. Defaults to true. The JSON GET
+   * client turns it off: its callers have always been allowed a self-hosted http base, so only
+   * what a redirect points at is the new decision.
+   */
+  readonly requireSecureBase?: boolean;
+}
+
+type Transport = (url: string, init: RequestInit) => Promise<Response>;
+
+/** Phase 2: send one hop with `redirect: "manual"`, so no runtime follows anything on its own. */
+function sendHop(doFetch: Transport, url: URL, init: RequestInit): Promise<Response> {
+  return doFetch(url.toString(), { ...init, redirect: "manual" });
+}
+
+/** Phase 3a: a redirect on a mutation is never followed, and the credential never goes along. */
+function assertReadRedirect(label: string, method: string, status: number): void {
+  if (method === "GET" || method === "HEAD") return;
+  throw new Error(
+    `${label} answered a ${method} with a redirect (${String(status)}); the write may or may not have been applied`,
+  );
+}
+
+/** Phase 3b: the `Location` the redirect names. */
+function requireLocation(label: string, res: Response): string {
+  const location = res.headers.get("location");
+  if (location === null || location === "") {
+    throw new Error(`${label} sent a redirect without a Location; refused`);
+  }
+  return location;
+}
+
+/** Phase 3c: at most {@link MAX_REDIRECT_HOPS} followed redirects; `hop` counts those already followed. */
+function assertHopBudget(label: string, hop: number): void {
+  if (hop >= MAX_REDIRECT_HOPS) throw new Error(`${label} sent too many redirects; refused`);
+}
+
+/** Phase 3d: resolve `location` against the URL that answered. */
+function resolveNext(label: string, location: string, current: URL): URL {
+  try {
+    return new URL(location, current);
+  } catch {
+    throw new Error(`${label} redirected to an invalid URL; refused`);
+  }
+}
+
+/**
+ * Phase 3e: the target must be the same origin (a plain-http base was only reachable with
+ * requireSecureBase off, or is loopback), plus ONE widening: the same host's http -> https upgrade.
+ * Never https -> http; anything else is refused and nothing is sent there.
+ */
+function assertSameOriginOrUpgrade(label: string, current: URL, next: URL): void {
+  const sameOrigin = next.origin === current.origin;
+  const httpsUpgrade =
+    current.protocol === "http:" &&
+    next.protocol === "https:" &&
+    next.hostname === current.hostname &&
+    next.port === current.port;
+  if (!sameOrigin && !httpsUpgrade) {
+    throw new Error(`${label} redirected to another origin; refused`);
+  }
+}
+
+/**
+ * `fetch(url, init)` with the redirect policy above. `label` names the service in a refusal
+ * ("GitLab redirected a POST; refused"). Resolves to the final non-redirect response.
+ *
+ * The order of the checks is the policy; read it top to bottom in the loop.
+ */
+export async function guardedFetch(
+  label: string,
+  url: string,
+  init: RequestInit = {},
+  options: GuardedFetchOptions = {},
+): Promise<Response> {
+  const method = (init.method ?? "GET").toUpperCase();
+  const doFetch: Transport =
+    options.fetch ?? ((u: string, i: RequestInit) => fetchWithTimeout(u, i, DEFAULT_TIMEOUT_MS));
+  let current = new URL(url);
+  // Phase 1: the base itself.
+  if (options.requireSecureBase !== false) assertSecureTransport(label, current);
+  for (let hop = 0; ; hop += 1) {
+    const res = await sendHop(doFetch, current, init);
+    if (!REDIRECT_STATUSES.has(res.status)) return res;
+    assertReadRedirect(label, method, res.status);
+    const location = requireLocation(label, res);
+    assertHopBudget(label, hop);
+    const next = resolveNext(label, location, current);
+    assertSameOriginOrUpgrade(label, current, next);
+    current = next;
+  }
+}