@stigmer/outbound 3.18.1-dev.20260919070736

package/LICENSE

@@ -0,0 +1,190 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Stigmer Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,22 @@
+# @stigmer/outbound
+
+The rules a Stigmer process follows when it dials a URL a user supplied, shared by the control plane (`@stigmer/server`), the runner (`@stigmer/runner`) and the catalogue audit (`plugins/scripts/audit`).
+
+Two entry points:
+
+- `@stigmer/outbound/egress`: which addresses a process refuses to dial (`blockedReason`, two postures, `strict` for managed cloud processes and `relaxed` for a machine that belongs to the user), the check that applies a policy to a URL after resolving every address it has (`checkEgress`), and the fetch that applies it to every redirect hop (`guardedFetch`). A process composes one guarded fetch at its root and hands it to every module that dials; the modules hold no `fetch` of their own.
+- `@stigmer/outbound/mcp-oauth`: how an MCP endpoint's authentication is read without a credential (`isOAuthChallenge`, the complete `initializeRequest`, `probeEndpointAuth`) and how its login server is found (`resolveAuthorizationServers` over RFC 9728, `readAuthorizationServerMetadata` over RFC 8414 with the issuer's path and OpenID's document).
+
+## Why one library
+
+Each rule here was first written where it was first needed: the address classification in the runner's `web_fetch` guard, the OAuth-challenge rule in the runner's failed-tool-call path, the complete handshake and the metadata walk in the catalogue audit. The control plane then needed all of them at once, to complete a URL-only server's `auth` at save time and to reach login servers on another origin, and a third copy would have let the storefront call OAuth what the runner called a bad token. So the rules moved here and every consumer imports them; the consumers keep only what is theirs (the runner its posture from its mode and its user-facing sentence, the control plane its edition driver point and its pinned validation copy, the audit its evidence and retry).
+
+## Shape
+
+Pure over injected `fetch` and `lookup`; the one Node-bound module is `egress/node-lookup.ts`. Every function that can fail on the network returns a value (`EgressCheck`, `EndpointAuthOutcome`, `MetadataRead`) rather than throwing, so a caller renders its own sentence; `EgressError` wraps a refusal for the guarded fetch. `OutboundFetch` is the fetch shape consumers take (`(url: string | URL, init?) => Promise<Response>`); the global `fetch` satisfies it.
+
+Published in lockstep with the other `backend/libs/ts` libraries by `scripts/publish-libs.mjs`; the server and runner link it with `file:` and pin the release version at stamp time.
+
+## Verify
+
+`npm run typecheck && npm test` here. The consumers' suites when a rule changes: `make test-server`, `make test-runner`, `make test-plugins-static`.

package/egress/address.d.ts

@@ -0,0 +1,23 @@
+/** The two egress postures; the caller derives one from where it runs. */
+export type EgressPosture = "strict" | "relaxed";
+/**
+ * An egress policy: the synchronous address judgement a process dials
+ * under. `blockedReason` answers for every string (an unparseable one is
+ * refused as "unrecognized"), never throws, and does no I/O. A policy that
+ * would need a network or a hostname to answer is a different seam.
+ */
+export interface EgressPolicy {
+    /** The posture's name, for logs and error copy. */
+    readonly name: string;
+    /** A human-readable range name when the address is refused, null when allowed. */
+    blockedReason(address: string): string | null;
+}
+/** The policy for a posture: the two shapes every consumer composes. */
+export declare function egressPolicyForPosture(posture: EgressPosture): EgressPolicy;
+/**
+ * Classify an IP address against the posture's refused ranges.
+ *
+ * @returns a human-readable range name when refused, or null when allowed.
+ */
+export declare function blockedReason(address: string, posture: EgressPosture): string | null;
+//# sourceMappingURL=address.d.ts.map

package/egress/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/egress/address.ts"],"names":[],"mappings":"AAkCA,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC/C;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAK3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAoBpF"}

package/egress/address.js

@@ -0,0 +1,148 @@
+/**
+ * Address classification for outbound egress: which IP addresses a Stigmer
+ * process refuses to dial, under which posture, and why.
+ *
+ * This is the one home of the rule. It began as the runner's `web_fetch`
+ * SSRF boundary (backend/services/runner/src/tools/url-guard.ts, which now
+ * delegates here) and is shared because the control plane dials
+ * user-supplied URLs too: an MCP endpoint at save time and its login server
+ * on Sign in. A rule with two copies drifts; a copy that drifted on the
+ * control plane would be the copy guarding the wider network.
+ *
+ * Two postures, because locality differs, not trust:
+ *
+ * - "strict" (managed cloud processes): loopback, RFC 1918 private,
+ *   link-local, unspecified, and their IPv6 equivalents are all refused.
+ * - "relaxed" (self-hosted and local processes): the machine belongs to
+ *   the user, and a server beside the process (http://localhost:3000/mcp,
+ *   the proto's own example) is the normal case. Only the link-local range,
+ *   which carries the cloud metadata endpoint 169.254.169.254, stays
+ *   refused, as costless defence in depth.
+ *
+ * Who chooses the posture is the caller's business: the runner keys it on
+ * its mode with an operator override; the control plane takes it from an
+ * edition driver point. This module knows addresses and nothing else.
+ *
+ * IPv4-mapped IPv6 (::ffff:a.b.c.d in dotted or hex form) is classified by
+ * the embedded IPv4, so the mapping cannot smuggle a refused address past
+ * the check. Anything that is not a well-formed address fails closed.
+ *
+ * Proven by __tests__/address.test.ts, the runner's classification cases
+ * moved here byte for byte.
+ */
+import { isIP } from "node:net";
+/** The policy for a posture: the two shapes every consumer composes. */
+export function egressPolicyForPosture(posture) {
+    return {
+        name: posture,
+        blockedReason: (address) => blockedReason(address, posture),
+    };
+}
+/**
+ * Classify an IP address against the posture's refused ranges.
+ *
+ * @returns a human-readable range name when refused, or null when allowed.
+ */
+export function blockedReason(address, posture) {
+    const family = isIP(address);
+    if (family === 4) {
+        return blockedReasonV4(address, posture);
+    }
+    if (family === 6) {
+        const groups = expandV6(address);
+        if (!groups)
+            return "unrecognized";
+        const embedded = extractMappedV4(groups);
+        if (embedded) {
+            return blockedReasonV4(embedded, posture);
+        }
+        return blockedReasonV6(groups, posture);
+    }
+    // Unparseable: fail closed; only real addresses get sockets.
+    return "unrecognized";
+}
+function blockedReasonV4(address, posture) {
+    const octets = address.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
+        return "unrecognized";
+    }
+    const a = octets[0];
+    const b = octets[1];
+    // Link-local (169.254.0.0/16) hosts the cloud metadata service at
+    // 169.254.169.254: refused under BOTH postures.
+    if (a === 169 && b === 254)
+        return "link-local (cloud metadata)";
+    if (posture === "relaxed")
+        return null;
+    if (a === 127)
+        return "loopback";
+    if (a === 0)
+        return "unspecified";
+    if (a === 10)
+        return "private (RFC 1918)";
+    if (a === 172 && b !== undefined && b >= 16 && b <= 31)
+        return "private (RFC 1918)";
+    if (a === 192 && b === 168)
+        return "private (RFC 1918)";
+    return null;
+}
+function blockedReasonV6(groups, posture) {
+    const first = groups[0] ?? 0;
+    // fe80::/10, the IPv6 link-local range, the v6 sibling of the metadata
+    // range: refused under BOTH postures for symmetry with v4.
+    if ((first & 0xffc0) === 0xfe80)
+        return "link-local (cloud metadata)";
+    if (posture === "relaxed")
+        return null;
+    const allZero = groups.every((g) => g === 0);
+    if (allZero)
+        return "unspecified";
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return "loopback";
+    // fc00::/7: unique local (private) addresses.
+    if ((first & 0xfe00) === 0xfc00)
+        return "private (unique local)";
+    return null;
+}
+/**
+ * Expand an IPv6 address (already validated by isIP) into its 8 groups.
+ * Handles `::` compression, a trailing dotted-IPv4 tail, and zone suffixes.
+ */
+function expandV6(address) {
+    let text = address.toLowerCase().split("%")[0] ?? "";
+    // Convert a dotted-IPv4 tail (for example ::ffff:127.0.0.1) into two hex groups.
+    const v4Tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    const tail4 = v4Tail?.[1];
+    if (tail4 !== undefined) {
+        const octets = tail4.split(".").map(Number);
+        if (octets.length !== 4 || octets.some((o) => o > 255))
+            return null;
+        const [o0 = 0, o1 = 0, o2 = 0, o3 = 0] = octets;
+        const hex = `${((o0 << 8) | o1).toString(16)}:${((o2 << 8) | o3).toString(16)}`;
+        text = text.slice(0, -tail4.length) + hex;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const parseHalf = (half) => (half === "" ? [] : half.split(":").map((g) => parseInt(g, 16)));
+    const head = parseHalf(halves[0] ?? "");
+    const tail = halves.length === 2 ? parseHalf(halves[1] ?? "") : [];
+    const fill = 8 - head.length - tail.length;
+    if (halves.length === 2 ? fill < 0 : head.length !== 8)
+        return null;
+    const groups = [...head, ...(halves.length === 2 ? Array(fill).fill(0) : []), ...tail];
+    if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff)) {
+        return null;
+    }
+    return groups;
+}
+/** Extract the IPv4 payload from IPv4-mapped groups (::ffff:0:0/96), if any. */
+function extractMappedV4(groups) {
+    const isMapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
+    if (!isMapped)
+        return null;
+    const hi = groups[6] ?? 0;
+    const lo = groups[7] ?? 0;
+    return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}
+//# sourceMappingURL=address.js.map

package/egress/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/egress/address.ts"],"names":[],"mappings":"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"}

package/egress/check.d.ts

@@ -0,0 +1,50 @@
+import type { EgressPolicy } from "./address.js";
+/** Resolve a hostname to every address it has; rejects when it has none. */
+export type LookupFn = (hostname: string) => Promise<readonly string[]>;
+/** Why a URL was refused; one shape per cause, each carrying what a sentence needs. */
+export type EgressRefusal = {
+    readonly kind: "invalid-url";
+    readonly url: string;
+} | {
+    readonly kind: "unsupported-scheme";
+    readonly url: URL;
+    readonly scheme: string;
+} | {
+    readonly kind: "unresolvable";
+    readonly url: URL;
+    readonly hostname: string;
+} | {
+    readonly kind: "blocked";
+    readonly url: URL;
+    readonly hostname: string;
+    readonly address: string;
+    readonly reason: string;
+    readonly policy: string;
+} | {
+    readonly kind: "too-many-redirects";
+    readonly url: URL;
+    readonly hops: number;
+};
+export type EgressCheck = {
+    readonly ok: true;
+    readonly url: URL;
+    readonly addresses: readonly string[];
+} | {
+    readonly ok: false;
+    readonly refusal: EgressRefusal;
+};
+export interface EgressCheckOptions {
+    readonly lookup: LookupFn;
+    /** Bounds the resolution; an abort propagates as the signal's reason. */
+    readonly signal?: AbortSignal | null | undefined;
+}
+/** One sentence per refusal, safe to show a user or a model. */
+export declare function describeRefusal(refusal: EgressRefusal): string;
+/** A refusal as a throwable, for callers that want one. */
+export declare class EgressError extends Error {
+    readonly refusal: EgressRefusal;
+    constructor(refusal: EgressRefusal);
+}
+/** Judge a URL under a policy: scheme, then every resolved address. */
+export declare function checkEgress(rawUrl: string | URL, policy: EgressPolicy, options: EgressCheckOptions): Promise<EgressCheck>;
+//# sourceMappingURL=check.d.ts.map

package/egress/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/egress/check.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;AAExE,uFAAuF;AACvF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/E;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;CAClD;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAiB9D;AAED,2DAA2D;AAC3D,qBAAa,WAAY,SAAQ,KAAK;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa;gBAAtB,OAAO,EAAE,aAAa;CAI5C;AAED,uEAAuE;AACvE,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyB/H"}

package/egress/check.js

@@ -0,0 +1,127 @@
+/**
+ * The egress check: may this process dial this URL under this policy?
+ *
+ * The answer is a value, not a throw, so a caller can render its own
+ * sentence (the runner tells a model "this runner does not fetch from", the
+ * control plane tells a user what the endpoint resolved to) while the
+ * judgement itself has one home. `EgressError` wraps a refusal for the
+ * callers that want a throw (the guarded fetch).
+ *
+ * The check resolves the hostname and judges EVERY address it resolves to:
+ * a name with one public and one private record must be refused, or the
+ * private record becomes the bypass. Literal IP hosts are judged as they
+ * are, without a lookup. Resolution is injected (`LookupFn`) so tests never
+ * touch DNS, and it races the caller's `signal`: `dns.lookup` has no
+ * timeout of its own, and a save that waits on a hanging resolver would be
+ * a save that hangs (the control plane's probe runs under one deadline
+ * that covers resolution, for exactly this reason). An aborted signal
+ * propagates as the signal's reason, the way `fetch` itself behaves.
+ *
+ * Accepted limitation, inherited from the runner's guard: a DNS-rebinding
+ * window remains between our lookup and the socket connect. Node's fetch
+ * (undici) offers no lookup pinning without replacing the dispatcher, and
+ * the strict posture's range refusals make the rebinding payoff (an
+ * internal address) unreachable anyway.
+ *
+ * Proven by __tests__/check.test.ts.
+ */
+import { isIP } from "node:net";
+/** One sentence per refusal, safe to show a user or a model. */
+export function describeRefusal(refusal) {
+    switch (refusal.kind) {
+        case "invalid-url":
+            return `Invalid URL: ${refusal.url}`;
+        case "unsupported-scheme":
+            return `Unsupported URL scheme "${refusal.scheme}": only http and https are allowed.`;
+        case "unresolvable":
+            return `Could not resolve hostname: ${refusal.hostname}`;
+        case "blocked":
+            return `Refusing to reach ${refusal.hostname}: it resolves to ${refusal.address}, a ${refusal.reason} address the ${refusal.policy} egress policy does not dial.`;
+        case "too-many-redirects":
+            return `Refusing to follow more than ${refusal.hops} redirects from ${refusal.url.href}.`;
+        default: {
+            const exhaustive = refusal;
+            return exhaustive;
+        }
+    }
+}
+/** A refusal as a throwable, for callers that want one. */
+export class EgressError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(describeRefusal(refusal));
+        this.refusal = refusal;
+        this.name = "EgressError";
+    }
+}
+/** Judge a URL under a policy: scheme, then every resolved address. */
+export async function checkEgress(rawUrl, policy, options) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return { ok: false, refusal: { kind: "invalid-url", url: String(rawUrl) } };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return { ok: false, refusal: { kind: "unsupported-scheme", url, scheme: url.protocol.replace(/:$/, "") } };
+    }
+    const addresses = await resolveAddresses(url.hostname, options);
+    if (addresses === undefined) {
+        return { ok: false, refusal: { kind: "unresolvable", url, hostname: url.hostname } };
+    }
+    for (const address of addresses) {
+        const reason = policy.blockedReason(address);
+        if (reason !== null) {
+            return { ok: false, refusal: { kind: "blocked", url, hostname: url.hostname, address, reason, policy: policy.name } };
+        }
+    }
+    return { ok: true, url, addresses };
+}
+/**
+ * Every address a hostname has. Literal IPs pass through (a bracketed IPv6
+ * host arrives from URL.hostname still bracketed). `undefined` when the name
+ * does not resolve; an aborted signal throws its reason.
+ */
+async function resolveAddresses(hostname, options) {
+    const literal = hostname.replace(/^\[|\]$/g, "");
+    if (isIP(literal) !== 0) {
+        return [literal];
+    }
+    try {
+        const records = await raceSignal(options.lookup(hostname), options.signal);
+        return records.length === 0 ? undefined : records;
+    }
+    catch (error) {
+        if (options.signal?.aborted === true)
+            throw error;
+        return undefined;
+    }
+}
+function raceSignal(promise, signal) {
+    if (signal === null || signal === undefined)
+        return promise;
+    if (signal.aborted) {
+        // The resolver was already asked; its eventual answer is nobody's now.
+        promise.catch(() => undefined);
+        return Promise.reject(abortReason(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            promise.catch(() => undefined);
+            reject(abortReason(signal));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+//# sourceMappingURL=check.js.map

package/egress/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/egress/check.ts"],"names":[],"mappings":"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"}

package/egress/fetch.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The guarded fetch: a `fetch`-shaped function that judges every URL it is
+ * about to dial, including every redirect hop, under one egress policy.
+ *
+ * A process composes exactly one of these at its root and hands it to
+ * every module that dials a user-supplied URL, so an unguarded call cannot
+ * be written by omission: the module holds no `fetch` of its own, only the
+ * `OutboundFetch` it was given. Tests hand a fake in the same shape.
+ *
+ * Redirects are the reason this is a wrapper and not a pre-check. The
+ * platform's own `fetch` would follow a redirect to an internal address
+ * after the first hop passed, so redirects are always requested `manual`
+ * from the underlying fetch and followed here, each hop judged like the
+ * first, up to `maxRedirects` (3, enough for a scheme upgrade and a
+ * trailing-slash canonicalisation with one to spare). A caller that asked
+ * for `redirect: "manual"` gets the 3xx back untouched (the OAuth preflight
+ * wants exactly that); `redirect: "error"` is honoured by throwing the same
+ * TypeError `fetch` throws. On a cross-origin hop the `Authorization`
+ * header is dropped, as the fetch standard does, so a credential meant for
+ * one host never travels to another. A 303, or a 301/302 answering a
+ * non-GET, becomes a GET without a body; 307 and 308 keep method and body.
+ *
+ * `OutboundFetch` takes a string or a URL, never a `Request`: a Request
+ * carries its own headers and body that a wrapper would have to merge, and
+ * no caller here builds one. The global `fetch` is assignable to it, so a
+ * test or a script can pass `fetch` where the guard is not the point.
+ *
+ * Proven by __tests__/fetch.test.ts.
+ */
+import type { EgressPolicy } from "./address.js";
+import { type LookupFn } from "./check.js";
+/** The fetch shape every outbound-dialling module takes; the global `fetch` satisfies it. */
+export type OutboundFetch = (url: string | URL, init?: RequestInit) => Promise<Response>;
+export interface GuardedFetchOptions {
+    readonly fetchImpl: OutboundFetch;
+    readonly lookup: LookupFn;
+    /** Hops followed before refusing; default 3. */
+    readonly maxRedirects?: number;
+}
+/** The default hop budget: a scheme upgrade and a canonicalisation, with one to spare. */
+export declare const DEFAULT_MAX_REDIRECTS = 3;
+/**
+ * An `OutboundFetch` in the global `fetch`'s shape, for a seam typed
+ * `typeof fetch`. A `Request` input is refused rather than flattened: this
+ * library's callers pass URLs, and a wrapper that silently dropped a
+ * Request's body or headers would be a bug that looked like a network
+ * failure.
+ */
+export declare function asFetch(outbound: OutboundFetch): typeof fetch;
+/** Compose a fetch that judges every URL and every hop under `policy`. */
+export declare function guardedFetch(policy: EgressPolicy, options: GuardedFetchOptions): OutboundFetch;
+//# sourceMappingURL=fetch.d.ts.map

package/egress/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/egress/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEzF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAIvC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,KAAK,CAK7D;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAyC9F"}