@nimbus-dev/connectors 0.4.0 → 0.6.0

package/connectors/pagerduty/src/tools.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { guardedFetch } from "../../../shared/guarded-fetch.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
@@ -18,7 +19,8 @@ const API = "https://api.pagerduty.com";
 async function pdFetch(token: string, path: string, init?: RequestInit): Promise<RestFetchResult> {
   const rel = path.startsWith("/") ? path : `/${path}`;
   const url = path.startsWith("http") ? path : `${API}${rel}`;
-  const res = await fetch(url, {
+  // guardedFetch: a write answered with a redirect is refused, and a GET follows only same-origin.
+  const res = await guardedFetch("PagerDuty", url, {
     ...init,
     headers: {
       Accept: "application/vnd.pagerduty+json;version=2",
@@ -30,11 +32,59 @@ async function pdFetch(token: string, path: string, init?: RequestInit): Promise
   return toRestFetchResult(res);
 }
 
-async function pdIncidentPutMutation(actionLabel: string, pathSuffix: string, incidentId: string) {
+/**
+ * A linear-time email shape check (no regex, so no backtracking): at most 254 characters, no
+ * whitespace or control characters, exactly one `@`, a non-empty local part, and a domain that
+ * contains a `.` that is neither its first nor its last character.
+ */
+export function isEmailShape(email: string): boolean {
+  if (email.length === 0 || email.length > 254) return false;
+  for (let i = 0; i < email.length; i++) {
+    const c = email.charCodeAt(i);
+    if (c <= 0x20 || (c >= 0x7f && c <= 0xa0) || c === 0x2028 || c === 0x2029 || c === 0xfeff) {
+      return false;
+    }
+  }
+  const at = email.indexOf("@");
+  if (at < 1 || at !== email.lastIndexOf("@")) return false;
+  const domain = email.slice(at + 1);
+  // A "." strictly inside the domain: neither its first nor its last character.
+  return domain.length >= 3 && domain.slice(1, -1).includes(".");
+}
+
+/**
+ * The `From` header PagerDuty requires on an incident update: "The email address of a valid user
+ * associated with the account making the request". Writes only. Throws before any request.
+ * The gateway injects it from the Vault key `pagerduty.from_email`.
+ */
+function requirePdFromEmail(): string {
+  const email = requireProcessEnv("PAGERDUTY_FROM_EMAIL");
+  if (!isEmailShape(email)) {
+    throw new Error("PAGERDUTY_FROM_EMAIL is not an email address");
+  }
+  return email;
+}
+
+/** Incident ids are short alphanumerics; anything else never reaches a URL. */
+const incidentIdSchema = z.string().regex(/^[A-Za-z0-9]{1,64}$/);
+
+/**
+ * `PUT /incidents/{id}` with `{incident:{type:"incident_reference", status}}` and a required
+ * `From` header: the only update endpoint
+ * https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incident documents
+ * (retrieved 2026-11-06). There is no `/acknowledge` or `/resolve` sub-endpoint.
+ */
+async function pdIncidentPut(
+  actionLabel: string,
+  change: { readonly status: "acknowledged" | "resolved" } | { readonly escalation_level: number },
+  incidentId: string,
+) {
+  const from = requirePdFromEmail();
   const token = requireProcessEnv("PAGERDUTY_API_TOKEN");
-  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}/${pathSuffix}`, {
+  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}`, {
     method: "PUT",
-    body: JSON.stringify({ incident: { type: "incident_reference", id: incidentId } }),
+    headers: { From: from },
+    body: JSON.stringify({ incident: { type: "incident_reference", ...change } }),
   });
   if (!res.ok) {
     throw new Error(`PagerDuty ${actionLabel} ${String(res.status)}: ${res.text.slice(0, 400)}`);
@@ -42,6 +92,24 @@ async function pdIncidentPutMutation(actionLabel: string, pathSuffix: string, in
   return jsonResult(res.json ?? { ok: true });
 }
 
+/** The incident as it stands: status, assignments, escalation level. Audited before a write. */
+async function readIncidentPreState(incidentId: string): Promise<Record<string, unknown>> {
+  requirePdFromEmail();
+  const token = requireProcessEnv("PAGERDUTY_API_TOKEN");
+  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}`);
+  if (!res.ok) {
+    throw new Error(`PagerDuty pre-state ${String(res.status)}: ${res.text.slice(0, 400)}`);
+  }
+  const inc = (res.json as { incident?: Record<string, unknown> } | null)?.incident ?? {};
+  return {
+    id: incidentId,
+    status: inc["status"],
+    assignments: inc["assignments"],
+    escalation_level: inc["escalation_level"] ?? null,
+    escalation_policy: inc["escalation_policy"],
+  };
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const PAGERDUTY_TOOL_NAMES = [
   "pd_incident_list",
@@ -51,13 +119,6 @@ export const PAGERDUTY_TOOL_NAMES = [
   "pd_incident_escalate",
 ] as const;
 
-/** The incident status changes, which differ only in the word they PUT. */
-const INCIDENT_STATUS_ACTIONS = [
-  { action: "acknowledge", description: "Acknowledge an incident." },
-  { action: "resolve", description: "Resolve an incident." },
-  { action: "escalate", description: "Escalate an incident." },
-] as const;
-
 export function registerPagerdutyTools(
   server: ConsentServer & { tool: (...args: never) => unknown },
 ): void {
@@ -107,20 +168,54 @@ export function registerPagerdutyTools(
     (parsed) => `/incidents/${encodeURIComponent(parsed.incidentId)}`,
   );
 
-  // The three incident status changes are the same PUT with a different status
-  // word, so they are declared rather than written out three times. Each keeps
-  // its own description; the rest was identical.
-  for (const { action, description } of INCIDENT_STATUS_ACTIONS) {
-    registerWriteTool(
-      `pd_incident_${action}`,
-      {
-        mutates: `pagerduty.incident.${action}`,
-        recoverable: true,
-        scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
-      },
-      description,
-      z.object({ incidentId: z.string().min(1) }),
-      async (parsed) => pdIncidentPutMutation(action, action, parsed.incidentId),
-    );
-  }
+  // Literal tool ids and `mutates` strings, so a static scan reads them. None can be undone
+  // through these tools (there is no unacknowledge, reopen or de-escalate), so each records the
+  // incident's prior state in the audit.
+  const incidentArgs = z.object({ incidentId: incidentIdSchema });
+  const incidentScope = (p: { incidentId: string }) => ({
+    kind: "incident",
+    value: p.incidentId,
+  });
+
+  registerWriteTool(
+    "pd_incident_acknowledge",
+    {
+      mutates: "pagerduty.incident.acknowledge",
+      recoverable: false,
+      capturePreState: (p) => readIncidentPreState(p.incidentId),
+      scopeTargetOf: incidentScope,
+    },
+    "Acknowledge an incident (`PUT /incidents/{id}` with status acknowledged). Needs PAGERDUTY_FROM_EMAIL, the email of a valid PagerDuty user.",
+    incidentArgs,
+    async (p) => pdIncidentPut("acknowledge", { status: "acknowledged" }, p.incidentId),
+  );
+
+  registerWriteTool(
+    "pd_incident_resolve",
+    {
+      mutates: "pagerduty.incident.resolve",
+      recoverable: false,
+      capturePreState: (p) => readIncidentPreState(p.incidentId),
+      scopeTargetOf: incidentScope,
+    },
+    "Resolve an incident (`PUT /incidents/{id}` with status resolved); it cannot be reopened through these tools. Needs PAGERDUTY_FROM_EMAIL, the email of a valid PagerDuty user.",
+    incidentArgs,
+    async (p) => pdIncidentPut("resolve", { status: "resolved" }, p.incidentId),
+  );
+
+  registerWriteTool(
+    "pd_incident_escalate",
+    {
+      mutates: "pagerduty.incident.escalate",
+      recoverable: false,
+      capturePreState: (p) => readIncidentPreState(p.incidentId),
+      scopeTargetOf: incidentScope,
+    },
+    // `escalation_level` ("Escalate the incident to this level in the escalation policy.", an
+    // integer) is a property of the `incident` body of PUT /incidents/{id} in PagerDuty's OpenAPI
+    // schema (github.com/PagerDuty/api-schema, reference/REST/openapiv3.json, retrieved 2026-11-06).
+    "Escalate an incident to the given level of its escalation policy (`PUT /incidents/{id}` with `escalation_level`); it cannot be de-escalated through these tools. Needs PAGERDUTY_FROM_EMAIL, the email of a valid PagerDuty user.",
+    incidentArgs.extend({ escalationLevel: z.number().int().min(1).max(20) }),
+    async (p) => pdIncidentPut("escalate", { escalation_level: p.escalationLevel }, p.incidentId),
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.4.0",
+  "version": "0.6.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;
+  }
+}