@oneuptime/common 12.0.6 → 12.0.7

package/Server/Types/Workflow/Components/Slack/SendMessageToChannel.ts

@@ -65,6 +65,23 @@ export default class SendMessageToChannel extends ComponentCode {
       );
     }
 
+    /*
+     * Pin the target to Slack's own incoming-webhook endpoint. Without this the
+     * component POSTs from the API server to any URL a workflow author types -
+     * the SSRF reported as GHSA-v5xh-rw9h-77fv against the API components.
+     */
+    if (
+      !SlackUtil.isValidSlackIncomingWebhookUrl(
+        args["webhook-url"]?.toString() as string,
+      )
+    ) {
+      throw options.onError(
+        new BadDataException(
+          "Slack Webhook URL must start with https://hooks.slack.com/services/",
+        ),
+      );
+    }
+
     args["webhook-url"] = URL.fromString(
       args["webhook-url"]?.toString() as string,
     );

package/Server/Utils/AI/Chat/ObservabilityChatPrompt.ts

@@ -148,7 +148,7 @@ If the project has connected code repositories you can read their source, which
 
 ## Changing the code
 
-You can propose code changes. open_code_pull_request is the right tool almost always: it opens a DRAFT pull request off the default branch for a human to review. commit_code_to_branch is only for when the user names an existing branch to commit onto.
+You can propose code changes. open_code_pull_request is the right tool almost always: it opens a pull request off the default branch, ready for review, for a human to review and merge. commit_code_to_branch is only for when the user names an existing branch to commit onto.
 
 - ALWAYS read_code_file the exact file first. \`content\` replaces the file's ENTIRE contents, so writing from memory or from a guess destroys code you never read. If you have not read it in this conversation, read it now.
 - Never write to the default branch. The tools refuse it, and so should you — if the user asks you to commit straight to main/master, explain that changes go through a reviewable pull request.

package/Server/Utils/AI/CodeFix/CodeAgentWorkspaceGuard.ts

@@ -13,6 +13,88 @@ import path from "path";
 // Max characters a single tool result may feed back into the model.
 export const MAX_TOOL_OUTPUT_CHARS: number = 20_000;
 
+/*
+ * Max characters a single write_file may put on disk. A model that loops on
+ * a generation bug can otherwise fill the Runner's disk from inside a tool
+ * call, taking down every other capability on the host — and no legitimate
+ * source file a fix needs to write is anywhere near this size.
+ */
+export const MAX_WRITE_FILE_CHARS: number = 2_000_000;
+
+/*
+ * Git subcommands the code agent may not run.
+ *
+ * The pipeline owns the repository's git state: it cuts the branch, decides
+ * what to stage, writes the commit and pushes. It also computes "what did
+ * the agent change" from the working tree. A model that helpfully commits
+ * its own work, resets the tree, switches branches or pushes therefore does
+ * not just duplicate the pipeline — it destroys the pipeline's ability to
+ * see the change at all (a committed tree is a clean tree, so the run
+ * reports "no changes" and the fix is silently discarded), or it puts a
+ * branch on the customer's remote that no pull request points at.
+ *
+ * The system prompt already asks the model not to. This is the enforcement,
+ * because an instruction is not a control.
+ *
+ * Honest about what this is: a guard against a well-meaning model taking an
+ * obvious wrong turn, NOT a sandbox. Shell is too expressive to filter
+ * adversarially — the real containment boundary is that the workspace is
+ * ephemeral, the credential is never in it, and nothing merges without a
+ * human. Read-only git (log, diff, status, show, grep, blame) stays
+ * available because the agent genuinely needs it.
+ */
+const REFUSED_GIT_SUBCOMMANDS: Set<string> = new Set<string>([
+  "push",
+  "commit",
+  "reset",
+  "checkout",
+  "switch",
+  "restore",
+  "stash",
+  "clean",
+  "rebase",
+  "merge",
+  "cherry-pick",
+  "revert",
+  "am",
+  "apply",
+  "filter-branch",
+  "update-ref",
+  "remote",
+  "config",
+  "credential",
+  "gc",
+  "prune",
+]);
+
+/*
+ * Shell operators that start a new command. Splitting on these is what lets
+ * the guard see the `git push` in `npm test && git push`.
+ */
+const COMMAND_SEPARATORS: RegExp = /(?:&&|\|\||[;\n|&()`]|\$\()/;
+
+// A leading `VAR=value` assignment, which belongs to the command not to argv.
+const LEADING_ENV_ASSIGNMENT: RegExp = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/*
+ * Options that take a separate value argument, so the subcommand is the
+ * token after next rather than the next token (`git -C sub push`).
+ */
+const GIT_OPTIONS_WITH_VALUE: Set<string> = new Set<string>([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+]);
+
+export interface CommandGuardDecision {
+  allowed: boolean;
+  // Set when not allowed — the message handed back to the model.
+  reason: string | null;
+}
+
 export default class CodeAgentWorkspaceGuard {
   /*
    * Resolve a model-supplied path against the workspace root, refusing any
@@ -54,6 +136,95 @@ export default class CodeAgentWorkspaceGuard {
     return relative === "" ? "." : relative;
   }
 
+  /*
+   * Decide whether the agent may run a shell command.
+   *
+   * Only repository-state-mutating git is refused; everything else is
+   * allowed, because building and testing is the whole point of the tool.
+   * The refusal text names the reason so the model corrects course instead
+   * of retrying the same command.
+   */
+  public static evaluateCommand(command: string): CommandGuardDecision {
+    for (const segment of command.split(COMMAND_SEPARATORS)) {
+      const subcommand: string | null = this.gitSubcommandOf(segment);
+
+      if (subcommand && REFUSED_GIT_SUBCOMMANDS.has(subcommand)) {
+        return {
+          allowed: false,
+          reason:
+            `Refused: \`git ${subcommand}\` is not available to you. The surrounding ` +
+            `pipeline owns this repository's git state — it created the branch, and it ` +
+            `stages, commits and pushes your changes once you are done. Running git ` +
+            `yourself would hide your work from it. Edit files with write_file and ` +
+            `leave git alone; read-only git (status, diff, log, show, grep) is allowed.`,
+        };
+      }
+    }
+
+    return { allowed: true, reason: null };
+  }
+
+  /*
+   * The git subcommand a single shell segment invokes, or null when the
+   * segment does not invoke git. Skips leading environment assignments
+   * (`GIT_DIR=x git ...`) and git's own global options, including the ones
+   * that consume a following value.
+   */
+  private static gitSubcommandOf(segment: string): string | null {
+    const tokens: Array<string> = segment
+      .trim()
+      .split(/\s+/)
+      .filter((token: string) => {
+        return token.length > 0;
+      });
+
+    let index: number = 0;
+
+    // Leading VAR=value assignments belong to the command, not to argv.
+    while (
+      index < tokens.length &&
+      LEADING_ENV_ASSIGNMENT.test(tokens[index] as string)
+    ) {
+      index++;
+    }
+
+    const executable: string | undefined = tokens[index];
+
+    if (!executable) {
+      return null;
+    }
+
+    // Match `git`, `/usr/bin/git`, and `"git"` alike.
+    const executableName: string = executable
+      .replace(/^["']|["']$/g, "")
+      .split("/")
+      .pop() as string;
+
+    if (executableName !== "git") {
+      return null;
+    }
+
+    index++;
+
+    while (index < tokens.length) {
+      const token: string = tokens[index] as string;
+
+      if (!token.startsWith("-")) {
+        return token.toLowerCase();
+      }
+
+      // `--git-dir=x` carries its value; `--git-dir x` consumes the next token.
+      if (GIT_OPTIONS_WITH_VALUE.has(token)) {
+        index += 2;
+        continue;
+      }
+
+      index++;
+    }
+
+    return null;
+  }
+
   /*
    * Truncate a tool output to the model-context cap, appending an explicit
    * marker so the model knows the output is partial rather than complete.

package/Server/Utils/AI/SRE/FixFromIncidentTaskTrigger.ts

@@ -39,9 +39,9 @@ import CaptureSpan from "../../Telemetry/CaptureSpan";
  * same FixFromIncident task with no human click. Confidence alone is not
  * sufficient: operational and other non-code causes do not open PRs. Like its
  * InstrumentationTaskTrigger sibling it runs only after the Recommended
- * decision and snapshot are durable, and it never throws. The PR still opens as a
- * DRAFT and is always human-reviewed — the opt-in moves the human gate from
- * PR creation to PR review, never past it.
+ * decision and snapshot are durable, and it never throws. The PR opens ready
+ * for review and is always human-reviewed — the opt-in moves the human gate
+ * from PR creation to PR review, never past it.
  */
 
 export interface AutoFixTaskGateInput {

package/Server/Utils/AI/SRE/Insights/FixRouting.ts

@@ -21,8 +21,9 @@ import CaptureSpan from "../../../Telemetry/CaptureSpan";
  * Project.enableAi master switch AND on Project.enableInsightFixTasks
  * (default FALSE): insights whose evidence points at code (new/spiking
  * exceptions with a resolvable repository, latency regressions with
- * span-tree findings) queue a CodeFix AIRun that opens a draft pull
- * request. The decision is readiness/evidence-based, never LLM-decided.
+ * span-tree findings) queue a CodeFix AIRun that opens a pull request,
+ * ready for review. The decision is readiness/evidence-based, never
+ * LLM-decided.
  *
  * Everything downstream reuses the existing budgeted creation paths, so
  * every guardrail comes free: the daily fix-run budget (G11, pre-checked

package/Server/Utils/AI/SRE/TelemetryImprovementTaskTrigger.ts

@@ -11,7 +11,7 @@ import CaptureSpan from "../../Telemetry/CaptureSpan";
 /*
  * AI SRE — the service-scoped instrumentation-improvement triggers:
  * ImproveLogging and ImproveTracing. One click on a service's Logs or
- * Traces page opens a draft PR that improves that service's logging or
+ * Traces page opens a PR that improves that service's logging or
  * tracing hygiene — parameterized log messages, correct severities, spans
  * on uninstrumented paths, proper exception recording — WITHOUT changing
  * behavior.

package/Server/Utils/AI/Toolbox/CodeWriteTools.ts

@@ -327,7 +327,7 @@ export const CommitCodeToBranchTool: ObservabilityTool = {
 export const OpenCodePullRequestTool: ObservabilityTool = {
   name: "open_code_pull_request",
   description:
-    "Propose a code change: creates a new branch off the default branch, commits the changes, and opens a DRAFT pull request for a human to review. This is the safe, preferred way to change code from chat — it never writes to the default branch. Read each file with read_code_file first: content replaces the whole file.",
+    "Propose a code change: creates a new branch off the default branch, commits the changes, and opens a pull request, ready for review, for a human to review and merge. This is the safe, preferred way to change code from chat — it never writes to the default branch and never merges. Read each file with read_code_file first: content replaces the whole file.",
   isMutation: true,
   inputSchema: {
     type: "object",
@@ -358,7 +358,7 @@ export const OpenCodePullRequestTool: ObservabilityTool = {
     return resolveUpdatePermissions();
   },
   buildActionTitle: (args: JSONObject): string => {
-    return `Open draft pull request: ${ToolArgs.getString(args, "title") || "Untitled"}`;
+    return `Open pull request: ${ToolArgs.getString(args, "title") || "Untitled"}`;
   },
   execute: async (
     args: JSONObject,
@@ -454,7 +454,7 @@ export const OpenCodePullRequestTool: ObservabilityTool = {
         headBranchName: headBranchName,
         title: title,
         body: `${description}\n\n---\n_Proposed by OneUptime AI from a chat conversation. Review carefully before merging: this change was written by an agent that reads production telemetry._`,
-        isDraft: true,
+        isDraft: false,
       });
 
     /*
@@ -502,14 +502,14 @@ export const OpenCodePullRequestTool: ObservabilityTool = {
 
     return {
       dataForLlm: [
-        `Opened DRAFT pull request #${pullRequest.pullRequestNumber} on ${organizationName}/${repositoryName}.`,
+        `Opened pull request #${pullRequest.pullRequestNumber} on ${organizationName}/${repositoryName}, ready for review.`,
         `url: ${pullRequestUrl}`,
         `branch: ${headBranchName} → ${baseBranchName}`,
         `files:\n${describeChanges(changes)}`,
-        `It is a DRAFT and is NOT merged. Give the user the link and say it needs their review.`,
+        `It is NOT merged. Give the user the link and say it needs their review.`,
       ].join("\n"),
       rowCount: changes.length,
-      citationLabel: `Draft PR #${pullRequest.pullRequestNumber}: ${title}`,
+      citationLabel: `PR #${pullRequest.pullRequestNumber}: ${title}`,
       redactionCount: 0,
       isTruncated: false,
     };

package/Server/Utils/CodeRepository/GitHub/GitHub.ts

@@ -1426,8 +1426,14 @@ export default class GitHubUtil extends HostedCodeRepository {
    * sibling of the instance-method createPullRequest, which authenticates from
    * a clone's own token.
    *
-   * Opened as a DRAFT by default; GitHub answers 422 for repositories whose
-   * plan lacks drafts, and we retry as non-draft rather than losing the work.
+   * Opened READY FOR REVIEW by default: a draft never reaches reviewers,
+   * CODEOWNERS or review automation, which buried the work instead of
+   * surfacing it. Human review is still mandatory — the safety boundary is
+   * that we only ever write to a fresh branch and never merge anything.
+   *
+   * Pass isDraft: true to open a draft instead; GitHub answers 422 for
+   * repositories whose plan lacks drafts, and we then retry ready-for-review
+   * rather than losing the work.
    */
   @CaptureSpan()
   public static async createPullRequestWithToken(data: {
@@ -1450,7 +1456,7 @@ export default class GitHubUtil extends HostedCodeRepository {
       `https://api.github.com/repos/${data.organizationName}/${data.repositoryName}/pulls`,
     );
 
-    const wantsDraft: boolean = data.isDraft !== false;
+    const wantsDraft: boolean = data.isDraft === true;
 
     let result: HTTPErrorResponse | HTTPResponse<JSONObject> = await API.post({
       url: url,
@@ -1464,13 +1470,19 @@ export default class GitHubUtil extends HostedCodeRepository {
       headers: headers,
     });
 
+    /*
+     * Only retry when GitHub refused the DRAFT state specifically. A 422 is
+     * also how it reports "a pull request already exists for this branch" and
+     * an invalid head — retrying those just fails a second time and hides the
+     * real message behind a misleading one.
+     */
     if (
       result instanceof HTTPErrorResponse &&
       wantsDraft &&
-      result.statusCode === 422
+      GitHubUtil.isDraftNotSupportedError(result)
     ) {
       logger.debug(
-        `GitHub rejected the draft pull request for ${data.organizationName}/${data.repositoryName}; retrying as non-draft.`,
+        `GitHub rejected the draft pull request for ${data.organizationName}/${data.repositoryName}; retrying as ready-for-review.`,
       );
 
       result = await API.post({
@@ -1480,6 +1492,7 @@ export default class GitHubUtil extends HostedCodeRepository {
           head: data.headBranchName,
           title: data.title,
           body: data.body,
+          draft: false,
         },
         headers: headers,
       });
@@ -1499,6 +1512,31 @@ export default class GitHubUtil extends HostedCodeRepository {
     });
   }
 
+  /*
+   * True when a failed create-PR response is GitHub refusing the DRAFT state
+   * specifically — an HTTP 422 whose message or errors name drafts, e.g.
+   * "Draft pull requests are not supported in this repository."
+   *
+   * Every other 422 (a pull request already exists for this branch, an
+   * invalid head, a validation failure) must NOT trigger the ready-for-review
+   * retry: the retry would fail identically and the caller would be handed the
+   * second error, which no longer describes the real problem.
+   */
+  public static isDraftNotSupportedError(response: HTTPErrorResponse): boolean {
+    if (response.statusCode !== 422) {
+      return false;
+    }
+
+    const errorData: JSONObject = (response.data as JSONObject) || {};
+
+    const textParts: Array<string> = [
+      (errorData["message"] as string) || "",
+      JSON.stringify(errorData["errors"] || ""),
+    ];
+
+    return textParts.join(" ").toLowerCase().includes("draft");
+  }
+
   /*
    * Every blob path in a tree mapped to its git file mode, so a rewrite can
    * preserve the mode instead of flattening everything to 100644. Recursive

package/Server/Utils/DataSource/EgressGuard.ts

@@ -1,16 +1,26 @@
 import dns from "dns";
+import http from "http";
+import https from "https";
 import net from "net";
 import BadDataException from "../../../Types/Exception/BadDataException";
-import { IsBillingEnabled } from "../../EnvironmentConfig";
 
 /*
- * SSRF egress guard for external Data Source connections.
+ * SSRF egress guard for outbound connections whose target is chosen by a
+ * tenant.
  *
- * Data Sources let project members point OneUptime at arbitrary
- * hosts — which would otherwise turn the API server into an authenticated
- * request proxy into whatever network it runs in (cloud metadata endpoints,
- * internal services, sibling tenants' infrastructure). Every connector must
- * validate its target through this guard before opening a socket.
+ * It started life guarding external Data Source connections — hence the
+ * file's home — but the same policy now covers every sink where a project
+ * member picks the host and a self-hosted install may legitimately point at
+ * something internal: LLM providers (self-hosted Ollama/vLLM), SMTP OAuth
+ * token endpoints, status page / dashboard domain verification, OIDC
+ * discovery and Runbook HTTP steps. Sinks that can only ever be third-party
+ * SaaS (Slack, Teams, subscriber webhooks) use SSRFProtection instead, which
+ * blocks private ranges unconditionally.
+ *
+ * Without a guard these turn the API server into an authenticated request
+ * proxy into whatever network it runs in (cloud metadata endpoints, internal
+ * services, sibling tenants' infrastructure). Every caller must validate its
+ * target through this guard before opening a socket.
  *
  * Policy:
  *  - ALWAYS blocked, in every deployment: loopback, link-local (cloud
@@ -51,8 +61,38 @@ export interface EgressGuardOptions {
   blockPrivateAddresses?: boolean | undefined;
   // Test seam for DNS. Undefined ⇒ dns.promises.lookup with a timeout.
   resolveFunction?: EgressResolveFunction | undefined;
+  /*
+   * Noun used in error messages so a rejection names the thing the user was
+   * actually configuring ("LLM provider host ... is not allowed"). Defaults
+   * to "Data source".
+   */
+  targetLabel?: string | undefined;
+}
+
+export interface PinnedAgents {
+  httpAgent: http.Agent;
+  httpsAgent: https.Agent;
 }
 
+/*
+ * dns.lookup's shape, as http.Agent / net.Socket call it. Declared locally
+ * rather than pulled from @types/node because the real declaration is a heavy
+ * overload set and every consumer here uses exactly this one shape.
+ */
+export type EgressLookupCallback = (
+  error: NodeJS.ErrnoException | null,
+  address: string | Array<{ address: string; family: number }>,
+  family?: number,
+) => void;
+
+export type EgressLookupFunction = (
+  hostname: string,
+  options: { all?: boolean | undefined; family?: number | undefined },
+  callback: EgressLookupCallback,
+) => void;
+
+const DEFAULT_TARGET_LABEL: string = "Data source";
+
 export interface AddressVerdict {
   blocked: boolean;
   reason?: string | undefined;
@@ -93,7 +133,15 @@ export default class DataSourceEgressGuard {
     if (process.env["DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES"] === "true") {
       return true;
     }
-    return IsBillingEnabled;
+    /*
+     * Read BILLING_ENABLED at call time rather than the boot-time
+     * IsBillingEnabled const, so this policy is consistent with the env
+     * override checked above and can be exercised deterministically in tests
+     * (a self-hosted install with billing off must still be able to reach its
+     * own private ranges). In a running deployment the env is fixed at boot,
+     * so this is behaviourally identical to the const.
+     */
+    return process.env["BILLING_ENABLED"] === "true";
   }
 
   private static ipv4ToInt(ip: string): number {
@@ -352,8 +400,10 @@ export default class DataSourceEgressGuard {
     hostname: string,
     options?: EgressGuardOptions,
   ): Promise<Array<ResolvedAddress>> {
+    const label: string = options?.targetLabel || DEFAULT_TARGET_LABEL;
+
     if (!hostname) {
-      throw new BadDataException("Data source host is required.");
+      throw new BadDataException(`${label} host is required.`);
     }
 
     // Literal [::1] style hosts arrive with brackets from URL parsing.
@@ -363,7 +413,7 @@ export default class DataSourceEgressGuard {
       const verdict: AddressVerdict = this.checkAddress(bareHostname, options);
       if (verdict.blocked) {
         throw new BadDataException(
-          `Data source host ${bareHostname} is not allowed: ${verdict.reason}.`,
+          `${label} host ${bareHostname} is not allowed: ${verdict.reason}.`,
         );
       }
       return [{ address: bareHostname, family: net.isIP(bareHostname) }];
@@ -380,7 +430,7 @@ export default class DataSourceEgressGuard {
       addresses = await resolveFunction(bareHostname);
     } catch (error) {
       throw new BadDataException(
-        `Could not resolve data source host ${bareHostname}: ${
+        `Could not resolve ${label.toLowerCase()} host ${bareHostname}: ${
           error instanceof Error ? error.message : String(error)
         }`,
       );
@@ -388,7 +438,7 @@ export default class DataSourceEgressGuard {
 
     if (addresses.length === 0) {
       throw new BadDataException(
-        `Could not resolve data source host ${bareHostname}.`,
+        `Could not resolve ${label.toLowerCase()} host ${bareHostname}.`,
       );
     }
 
@@ -399,7 +449,7 @@ export default class DataSourceEgressGuard {
       );
       if (verdict.blocked) {
         throw new BadDataException(
-          `Data source host ${bareHostname} resolves to ${resolved.address}, which is not allowed: ${verdict.reason}.`,
+          `${label} host ${bareHostname} resolves to ${resolved.address}, which is not allowed: ${verdict.reason}.`,
         );
       }
     }
@@ -416,20 +466,24 @@ export default class DataSourceEgressGuard {
     urlString: string,
     options?: EgressGuardOptions,
   ): Promise<{ url: URL; addresses: Array<ResolvedAddress> }> {
+    const label: string = options?.targetLabel || DEFAULT_TARGET_LABEL;
+
     if (!urlString) {
-      throw new BadDataException("Data source URL is required.");
+      throw new BadDataException(`${label} URL is required.`);
     }
 
     let url: URL;
     try {
       url = new URL(urlString);
     } catch {
-      throw new BadDataException(`Invalid data source URL: ${urlString}`);
+      throw new BadDataException(
+        `Invalid ${label.toLowerCase()} URL: ${urlString}`,
+      );
     }
 
     if (url.protocol !== "http:" && url.protocol !== "https:") {
       throw new BadDataException(
-        `Data source URL must use http or https (got ${url.protocol.replace(
+        `${label} URL must use http or https (got ${url.protocol.replace(
           ":",
           "",
         )}).`,
@@ -443,4 +497,110 @@ export default class DataSourceEgressGuard {
 
     return { url, addresses };
   }
+
+  /*
+   * A dns.lookup-shaped function that always answers with the already
+   * validated addresses. Handing this to an http(s).Agent makes the address
+   * that was checked the address that gets dialed, closing the DNS-rebind
+   * window between validation and connect. TLS still verifies against the
+   * original hostname because SNI is taken from the URL, not from here.
+   */
+  public static createPinnedLookup(
+    addresses: Array<ResolvedAddress>,
+  ): EgressLookupFunction {
+    return (
+      _hostname: string,
+      lookupOptions: { all?: boolean | undefined },
+      callback: EgressLookupCallback,
+    ): void => {
+      if (lookupOptions && lookupOptions.all) {
+        callback(
+          null,
+          addresses.map((resolved: ResolvedAddress) => {
+            return { address: resolved.address, family: resolved.family };
+          }),
+        );
+        return;
+      }
+
+      const first: ResolvedAddress = addresses[0]!;
+      callback(null, first.address, first.family);
+    };
+  }
+
+  // http/https agent pair that dials only the given validated addresses.
+  public static createPinnedAgents(
+    addresses: Array<ResolvedAddress>,
+  ): PinnedAgents {
+    const lookup: EgressLookupFunction = this.createPinnedLookup(addresses);
+
+    return {
+      httpAgent: new http.Agent({ lookup: lookup as never }),
+      httpsAgent: new https.Agent({ lookup: lookup as never }),
+    };
+  }
+
+  /*
+   * Validate a URL and return agents pinned to what it resolved to — the
+   * one-call form for HTTP callers. Pair with maxRedirects 0 /
+   * doNotFollowRedirects: pinning only covers the host that was validated, so
+   * a 3xx to an unvalidated host would otherwise walk straight around it.
+   */
+  public static async assertUrlAllowedAndPin(
+    urlString: string,
+    options?: EgressGuardOptions,
+  ): Promise<{ url: URL; addresses: Array<ResolvedAddress> } & PinnedAgents> {
+    const { url, addresses } = await this.assertUrlAllowed(urlString, options);
+
+    return { url, addresses, ...this.createPinnedAgents(addresses) };
+  }
+
+  /*
+   * A dns.lookup-shaped function that validates every hostname it is asked
+   * about and then answers with the addresses it just checked.
+   *
+   * For libraries that build their own request URLs from documents they
+   * fetched (openid-client adopts token_endpoint/userinfo_endpoint/jwks_uri
+   * from the discovery document), pre-validating the one URL we know about
+   * fixes nothing. Installing this as the library's lookup puts the guard on
+   * every socket the library opens, whichever URL it decided to call.
+   */
+  public static createGuardedLookup(
+    options?: EgressGuardOptions,
+  ): EgressLookupFunction {
+    return (
+      hostname: string,
+      lookupOptions: { all?: boolean | undefined; family?: number | undefined },
+      callback: EgressLookupCallback,
+    ): void => {
+      this.assertHostnameAllowed(hostname, options)
+        .then((addresses: Array<ResolvedAddress>) => {
+          const wantedFamily: number | undefined =
+            lookupOptions && lookupOptions.family
+              ? lookupOptions.family
+              : undefined;
+
+          const usable: Array<ResolvedAddress> =
+            wantedFamily === 4 || wantedFamily === 6
+              ? addresses.filter((resolved: ResolvedAddress) => {
+                  return resolved.family === wantedFamily;
+                })
+              : addresses;
+
+          if (usable.length === 0) {
+            const error: NodeJS.ErrnoException = new Error(
+              `No IPv${wantedFamily} address for ${hostname}`,
+            );
+            error.code = "ENOTFOUND";
+            callback(error, "");
+            return;
+          }
+
+          this.createPinnedLookup(usable)(hostname, lookupOptions, callback);
+        })
+        .catch((error: Error) => {
+          callback(error as NodeJS.ErrnoException, "");
+        });
+    };
+  }
 }