@stratusagent/egress 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratus Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @stratusagent/egress
+
+Which addresses a tool may reach, enforced on the connection rather than on
+the name it was asked for.
+
+Used by [`@stratusagent/tool-web`](../tool-web) and
+[`@stratusagent/tool-browser`](../tool-browser). It is one module because two
+copies of this rule would not drift into a style difference — the stale one
+would be an SSRF hole — and both packs are tested against `HOSTILE_URLS`, the
+table exported from here, which is what fails if it is ever forked.
+
+## The rule
+
+**Every globally routable address, and nothing else**, in both families. A
+blacklist that stops at RFC 1918 still leaves:
+
+- `169.254.169.254` — cloud instance metadata, and the credentials it serves
+- `127.0.0.1` and `::1` — the daemon's own control API, among other things
+- `fc00::/7` and `fe80::/10` — the same internal services over IPv6
+- `::ffff:169.254.169.254`, `64:ff9b::a9fe:a9fe`, `2002:a9fe:a9fe::` — the
+  same IPv4 addresses again, written the ways an IPv4 check does not see.
+  The well-known NAT64 prefix is judged on the IPv4 it carries, so an
+  IPv6-only network still reaches the public internet through it; RFC 8215's
+  **local-use** prefix `64:ff9b:1::/48` is refused whole, because the
+  translator chooses the embedding length and there is no offset to read the
+  address from
+
+Schemes are `http:` and `https:`. `file:`, `data:`, and `javascript:` are
+refused before anything is fetched: the process doing the fetching runs as the
+daemon user, and address validation cannot protect a filesystem.
+
+## Validation binds to the connection
+
+Resolving a name to check it and then letting something else resolve it again
+to connect is DNS rebinding with extra steps — the attacker's server answers
+`93.184.216.34` for the check and `169.254.169.254` for the connection.
+
+```ts
+import { createPinnedLookup, requestThroughPolicy, createEgressProxy } from '@stratusagent/egress';
+```
+
+- `createPinnedLookup(policy)` is a `lookup` for Node's HTTP stack, so the
+  addresses the socket uses are the addresses this checked. There is no second
+  resolution to lose to.
+- `requestThroughPolicy(url, …)` is one exchange over that lookup, with a byte
+  cap. It deliberately does **not** follow redirects: each hop is a new request
+  to a new host, so the caller loops and each hop faces the policy again.
+Both of those pass `agent: false` alongside the lookup. Node's global agent
+pools sockets by host and port and knows nothing about `lookup`, so a
+connection opened under a permissive policy is one a stricter policy can be
+handed — and a reused socket resolves nothing, so the pinned lookup that
+would have refused it is never called.
+
+- `createEgressProxy(policy)` is a loopback proxy for a browser, which resolves
+  names for itself whatever an interception handler decides. It resolves,
+  checks, and dials the checked address. `chromiumProxyOptions` /
+  `chromiumProxyArgs` include `<-loopback>` in the bypass list, without which
+  Chromium bypasses the proxy for exactly the addresses it exists to refuse.
+
+## Widening it
+
+| Setting | What it does |
+| --- | --- |
+| `allowedHosts` | Exempts specific hosts, by name or literal address. The narrow override: one internal service an agent is meant to reach. |
+| `allowPrivateAddresses` | Reaches any non-global address. The trusted-workstation posture — it turns the protection off rather than adjusting it. |
+| `allowedSchemes` | Replaces the scheme allowlist. There is no good reason to add `file:`. |
+
+Neither is a substitute for network-level egress rules in a VM or hosted
+profile ([08](../../docs/roadmap/08-deployment-profiles.md)); this is the
+in-process half.

package/dist/addresses.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Which addresses a tool may reach.
+ *
+ * The rule is "every globally routable address, and nothing else" rather
+ * than a blacklist of the ranges people remember. A blacklist that stops at
+ * RFC 1918 leaves cloud metadata at `169.254.169.254`, the gateway on
+ * `127.0.0.1`, and — on any dual-stack network — the same services again
+ * over IPv6 unique-local addresses and IPv4-mapped forms. Enumerating what
+ * is *allowed* fails closed on the range nobody thought of.
+ */
+export interface AddressVerdict {
+    allowed: boolean;
+    /** One line naming what was refused, for the error the agent sees. */
+    reason?: string;
+}
+export interface EgressPolicy {
+    /**
+     * Schemes a tool may request. `http:`/`https:` by default — `file:`,
+     * `data:`, and the rest are rejected before anything is fetched, because
+     * a browser or fetcher runs as the daemon user and address validation
+     * cannot protect the filesystem.
+     */
+    allowedSchemes?: string[];
+    /**
+     * Reach addresses that are not globally routable. Off by default; on, it
+     * is the trusted-workstation posture — an agent that is meant to talk to
+     * a local development server. It turns off the SSRF protection, which is
+     * why it is one switch an operator flips rather than something a call can
+     * ask for.
+     */
+    allowPrivateAddresses?: boolean;
+    /**
+     * Hosts exempt from the address check, by hostname or literal address —
+     * `localhost`, `127.0.0.1`, `dev.internal`. Narrower than the switch
+     * above and the one to reach for: an agent that needs one internal
+     * service should not thereby be able to read the metadata endpoint.
+     */
+    allowedHosts?: string[];
+}
+/**
+ * Classify one literal address, in either family.
+ *
+ * Called on the address a connection is actually about to use, never on
+ * the one a name resolved to a moment earlier somewhere else — that gap is
+ * DNS rebinding, and it is the difference between a check and a ceremony.
+ */
+export declare const classifyAddress: (address: string) => AddressVerdict;
+/** Whether one resolved address may be connected to for this host. */
+export declare const checkAddress: (policy: EgressPolicy, host: string, address: string) => AddressVerdict;
+/** A URL this policy refuses, and why. */
+export declare class EgressPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * The check that can be made before anything is fetched: the scheme, and
+ * the address when the URL names one literally.
+ *
+ * A hostname cannot be judged here — that is what the connection-time
+ * check is for — so this returning without throwing is not permission to
+ * connect. It is permission to *try*, and it is where `file:///…` dies.
+ */
+export declare const assertRequestAllowed: (rawUrl: string, policy?: EgressPolicy) => URL;
+//# sourceMappingURL=addresses.d.ts.map

package/dist/addresses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../src/addresses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAiKD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,cAUjD,CAAC;AAOF,sEAAsE;AACtE,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,EAAE,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,cAKlF,CAAC;AAEF,0CAA0C;AAC1C,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,EAAE,SAAQ,YAAiB,KAAG,GAyBhF,CAAC"}

package/dist/addresses.js

@@ -0,0 +1,246 @@
+/**
+ * Which addresses a tool may reach.
+ *
+ * The rule is "every globally routable address, and nothing else" rather
+ * than a blacklist of the ranges people remember. A blacklist that stops at
+ * RFC 1918 leaves cloud metadata at `169.254.169.254`, the gateway on
+ * `127.0.0.1`, and — on any dual-stack network — the same services again
+ * over IPv6 unique-local addresses and IPv4-mapped forms. Enumerating what
+ * is *allowed* fails closed on the range nobody thought of.
+ */
+const DEFAULT_SCHEMES = ['http:', 'https:'];
+const parseIPv4 = (value) => {
+    const parts = value.split('.');
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part)) {
+            return undefined;
+        }
+        const octet = Number(part);
+        if (octet > 255) {
+            return undefined;
+        }
+        octets.push(octet);
+    }
+    return octets;
+};
+/** Every IPv4 range that is not globally routable, with the name of each. */
+const classifyIPv4 = (octets) => {
+    const [a = 0, b = 0, c = 0, d = 0] = octets;
+    const address = octets.join('.');
+    const refuse = (what) => ({
+        allowed: false,
+        reason: `${address} is ${what}, which is not a public address`,
+    });
+    if (a === 0)
+        return refuse('the unspecified range (0.0.0.0/8)');
+    if (a === 10)
+        return refuse('a private address (10.0.0.0/8)');
+    if (a === 100 && b >= 64 && b <= 127)
+        return refuse('a carrier-NAT address (100.64.0.0/10)');
+    if (a === 127)
+        return refuse('loopback (127.0.0.0/8)');
+    if (a === 169 && b === 254) {
+        // The one that matters most in a hosted deployment: this is where every
+        // major cloud serves instance credentials.
+        return refuse('link-local (169.254.0.0/16) — cloud instance metadata lives here');
+    }
+    if (a === 172 && b >= 16 && b <= 31)
+        return refuse('a private address (172.16.0.0/12)');
+    if (a === 192 && b === 0 && c === 0)
+        return refuse('IETF protocol assignment space (192.0.0.0/24)');
+    if (a === 192 && b === 0 && c === 2)
+        return refuse('documentation space (192.0.2.0/24)');
+    if (a === 192 && b === 88 && c === 99)
+        return refuse('6to4 relay anycast (192.88.99.0/24)');
+    if (a === 192 && b === 168)
+        return refuse('a private address (192.168.0.0/16)');
+    if (a === 198 && (b === 18 || b === 19))
+        return refuse('benchmarking space (198.18.0.0/15)');
+    if (a === 198 && b === 51 && c === 100)
+        return refuse('documentation space (198.51.100.0/24)');
+    if (a === 203 && b === 0 && c === 113)
+        return refuse('documentation space (203.0.113.0/24)');
+    if (a >= 224 && a <= 239)
+        return refuse('multicast (224.0.0.0/4)');
+    if (a >= 240)
+        return refuse(d === 255 && a === 255 ? 'broadcast' : 'reserved space (240.0.0.0/4)');
+    return { allowed: true };
+};
+const expandIPv6 = (value) => {
+    const zoneless = value.split('%')[0] ?? value;
+    const [head, tail, ...extra] = zoneless.split('::');
+    if (extra.length > 0) {
+        return undefined;
+    }
+    const parseGroups = (part) => {
+        if (!part) {
+            return [];
+        }
+        const groups = [];
+        for (const piece of part.split(':')) {
+            if (piece.length === 0) {
+                return undefined;
+            }
+            if (piece.includes('.')) {
+                // A trailing dotted quad: `::ffff:169.254.169.254` and friends.
+                const octets = parseIPv4(piece);
+                if (!octets) {
+                    return undefined;
+                }
+                groups.push(((octets[0] ?? 0) << 8) | (octets[1] ?? 0), ((octets[2] ?? 0) << 8) | (octets[3] ?? 0));
+                continue;
+            }
+            if (!/^[0-9a-fA-F]{1,4}$/.test(piece)) {
+                return undefined;
+            }
+            groups.push(Number.parseInt(piece, 16));
+        }
+        return groups;
+    };
+    const left = parseGroups(head);
+    const right = tail === undefined ? [] : parseGroups(tail);
+    if (!left || !right) {
+        return undefined;
+    }
+    if (tail === undefined) {
+        return left.length === 8 ? left : undefined;
+    }
+    const missing = 8 - left.length - right.length;
+    if (missing < 0) {
+        return undefined;
+    }
+    return [...left, ...Array.from({ length: missing }, () => 0), ...right];
+};
+const embeddedIPv4 = (groups) => {
+    const [g0 = 0, g1 = 0, g2 = 0, g3 = 0, g4 = 0, g5 = 0, g6 = 0, g7 = 0] = groups;
+    const asOctets = (high, low) => [high >> 8, high & 0xff, low >> 8, low & 0xff];
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d). Both are
+    // ways of writing an IPv4 address, so both are classified as one — a
+    // check that only knew dotted quads would pass `::ffff:127.0.0.1`.
+    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && (g5 === 0xffff || g5 === 0)) {
+        if (g6 === 0 && g7 <= 1) {
+            return undefined; // :: and ::1 are classified as IPv6 below.
+        }
+        return asOctets(g6, g7);
+    }
+    // NAT64 (64:ff9b::/96) and 6to4 (2002::/16) both carry an IPv4 address
+    // that the network will actually route to.
+    if (g0 === 0x0064 && g1 === 0xff9b && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) {
+        return asOctets(g6, g7);
+    }
+    if (g0 === 0x2002) {
+        return asOctets(g1, g2);
+    }
+    return undefined;
+};
+const classifyIPv6 = (groups, address) => {
+    const embedded = embeddedIPv4(groups);
+    if (embedded) {
+        const verdict = classifyIPv4(embedded);
+        return verdict.allowed
+            ? verdict
+            : { allowed: false, reason: `${address} embeds ${verdict.reason ?? 'a non-public address'}` };
+    }
+    const [g0 = 0] = groups;
+    const refuse = (what) => ({
+        allowed: false,
+        reason: `${address} is ${what}, which is not a public address`,
+    });
+    // RFC 8215's local-use NAT64 prefix. The well-known `64:ff9b::/96` above
+    // embeds its IPv4 at a fixed offset, so that one is extracted and judged
+    // on the address it carries — which is what lets an IPv6-only network
+    // reach the public IPv4 internet. This one may embed at any of RFC 6052's
+    // lengths, chosen by whoever runs the translator, so there is no offset
+    // to read it from. It is called local-use for a reason: refused whole,
+    // rather than guessed at and let through as public.
+    if (g0 === 0x0064 && groups[1] === 0xff9b && groups[2] === 0x0001) {
+        return refuse('the local-use NAT64 prefix (64:ff9b:1::/48), which can translate to any address');
+    }
+    if (groups.every((group) => group === 0))
+        return refuse('the unspecified address (::)');
+    if (groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1)
+        return refuse('loopback (::1)');
+    if ((g0 & 0xfe00) === 0xfc00)
+        return refuse('a unique-local address (fc00::/7)');
+    if ((g0 & 0xffc0) === 0xfe80)
+        return refuse('link-local (fe80::/10)');
+    if ((g0 & 0xff00) === 0xff00)
+        return refuse('multicast (ff00::/8)');
+    if (g0 === 0x2001 && groups[1] === 0x0db8)
+        return refuse('documentation space (2001:db8::/32)');
+    if (g0 === 0x0100 && groups[1] === 0 && groups[2] === 0 && groups[3] === 0)
+        return refuse('the discard prefix (100::/64)');
+    return { allowed: true };
+};
+/**
+ * Classify one literal address, in either family.
+ *
+ * Called on the address a connection is actually about to use, never on
+ * the one a name resolved to a moment earlier somewhere else — that gap is
+ * DNS rebinding, and it is the difference between a check and a ceremony.
+ */
+export const classifyAddress = (address) => {
+    const ipv4 = parseIPv4(address);
+    if (ipv4) {
+        return classifyIPv4(ipv4);
+    }
+    const ipv6 = expandIPv6(address);
+    if (ipv6) {
+        return classifyIPv6(ipv6, address);
+    }
+    return { allowed: false, reason: `${address} is not an IP address` };
+};
+const hostMatches = (policy, host) => {
+    const normalized = host.toLowerCase().replace(/^\[|\]$/g, '');
+    return (policy.allowedHosts ?? []).some((entry) => entry.toLowerCase() === normalized);
+};
+/** Whether one resolved address may be connected to for this host. */
+export const checkAddress = (policy, host, address) => {
+    if (policy.allowPrivateAddresses || hostMatches(policy, host)) {
+        return { allowed: true };
+    }
+    return classifyAddress(address);
+};
+/** A URL this policy refuses, and why. */
+export class EgressPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EgressPolicyError';
+    }
+}
+/**
+ * The check that can be made before anything is fetched: the scheme, and
+ * the address when the URL names one literally.
+ *
+ * A hostname cannot be judged here — that is what the connection-time
+ * check is for — so this returning without throwing is not permission to
+ * connect. It is permission to *try*, and it is where `file:///…` dies.
+ */
+export const assertRequestAllowed = (rawUrl, policy = {}) => {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new EgressPolicyError(`Not a URL: ${rawUrl}`);
+    }
+    const schemes = policy.allowedSchemes ?? DEFAULT_SCHEMES;
+    if (!schemes.includes(url.protocol)) {
+        throw new EgressPolicyError(`Refusing ${url.protocol}//: only ${schemes.join(', ')} may be requested. `
+            + 'Local schemes are rejected before navigation — this process can read the files they name.');
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    const literal = parseIPv4(host) ? host : (expandIPv6(host) ? host : undefined);
+    if (literal) {
+        const verdict = checkAddress(policy, host, literal);
+        if (!verdict.allowed) {
+            throw new EgressPolicyError(`Refusing ${url.href}: ${verdict.reason}`);
+        }
+    }
+    return url;
+};
+//# sourceMappingURL=addresses.js.map

package/dist/addresses.js.map

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

package/dist/connect.d.ts

@@ -0,0 +1,71 @@
+import http from 'node:http';
+import net from 'node:net';
+import { type EgressPolicy } from './addresses.ts';
+/**
+ * One policy, as a key — sorted, because `{a,b}` and `{b,a}` are the same
+ * policy. Exported because anything that keeps a per-policy resource needs
+ * the same answer to "is this the same policy", and two spellings of that
+ * question would be two answers.
+ */
+export declare const policyKeyFor: (policy: EgressPolicy) => string;
+/**
+ * A DNS lookup that hands the socket only addresses the policy allows.
+ *
+ * This is the whole point of the module. Resolving a name in one place and
+ * connecting in another is a DNS rebinding race: the attacker's server
+ * answers `93.184.216.34` for the check and `169.254.169.254` a moment
+ * later for the connection, and a checker that looked the name up itself
+ * would have validated an address nothing ever connected to. Node lets the
+ * connection's *own* resolution be replaced, so the addresses this returns
+ * are the addresses the socket uses — there is no second lookup to lose to.
+ */
+export declare const createPinnedLookup: (policy: EgressPolicy) => net.LookupFunction;
+export interface PolicyRequestOptions {
+    policy?: EgressPolicy;
+    headers?: Record<string, string>;
+    /** Give up on the whole exchange after this long. */
+    timeoutMs?: number;
+    /** Stop reading here. A tool's output is bounded; so is what it downloads. */
+    maxBytes?: number;
+    signal?: AbortSignal;
+}
+export interface PolicyResponse {
+    status: number;
+    headers: http.IncomingHttpHeaders;
+    body: string;
+    /** True when `maxBytes` cut the body short. */
+    truncated: boolean;
+}
+/**
+ * One HTTP exchange, pinned to a validated address.
+ *
+ * Redirects are deliberately **not** followed here: each hop is a new
+ * request to a new host, so each one has to face the policy again. A
+ * caller loops and re-enters this, which is what makes "an approved public
+ * URL that redirects into the metadata endpoint" a refusal rather than a
+ * fetch.
+ */
+export declare const requestThroughPolicy: (rawUrl: string, options?: PolicyRequestOptions) => Promise<PolicyResponse>;
+export interface EgressProxy {
+    /** `http://127.0.0.1:<port>` — what a browser is launched pointing at. */
+    url: string;
+    port: number;
+    /** Requests this proxy refused, newest last. Surfaced to the agent as the reason a page is blank. */
+    refusals: string[];
+    close(): Promise<void>;
+}
+export declare const createEgressProxy: (policy?: EgressPolicy) => Promise<EgressProxy>;
+/**
+ * What a Chromium launch needs to be actually pinned to a proxy.
+ *
+ * `--proxy-bypass-list=<-loopback>` is not optional: Chromium bypasses the
+ * proxy for loopback and `localhost` by default, so a browser pointed at
+ * this proxy would still reach `http://127.0.0.1:8080` directly — which is
+ * one of the exact destinations the proxy exists to refuse.
+ */
+export declare const chromiumProxyOptions: (proxy: Pick<EgressProxy, "url">) => {
+    server: string;
+    bypass: string;
+};
+export declare const chromiumProxyArgs: (proxy: Pick<EgressProxy, "url">) => string[];
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,GAAG,MAAM,UAAU,CAAC;AAG3B,OAAO,EAAyD,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE1G;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,KAAG,MAIlD,CAAC;AAqBH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,GAAG,CAAC,cAqC7D,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,MAAM,EACd,UAAS,oBAAyB,KACjC,OAAO,CAAC,cAAc,CAuFxB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,qGAAqG;IACrG,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAqCD,eAAO,MAAM,iBAAiB,GAAU,SAAQ,YAAiB,KAAG,OAAO,CAAC,WAAW,CA+GtF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,KAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAIrG,CAAC;AAEH,eAAO,MAAM,iBAAiB,GAAI,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,KAAG,MAAM,EAGzE,CAAC"}

package/dist/connect.js

@@ -0,0 +1,309 @@
+import dns from 'node:dns';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import { assertRequestAllowed, checkAddress, EgressPolicyError } from "./addresses.js";
+/**
+ * One policy, as a key — sorted, because `{a,b}` and `{b,a}` are the same
+ * policy. Exported because anything that keeps a per-policy resource needs
+ * the same answer to "is this the same policy", and two spellings of that
+ * question would be two answers.
+ */
+export const policyKeyFor = (policy) => JSON.stringify({
+    allowPrivateAddresses: policy.allowPrivateAddresses ?? false,
+    allowedHosts: [...(policy.allowedHosts ?? [])].sort(),
+    allowedSchemes: [...(policy.allowedSchemes ?? [])].sort(),
+});
+/**
+ * Connection options that keep a policy's sockets to itself.
+ *
+ * `agent: false` is the load-bearing half. Node's global agent pools
+ * sockets by host and port and knows nothing about `lookup`, so a
+ * connection opened under a permissive policy is a connection a stricter
+ * one can be handed — no DNS resolution happens on a reused socket, and the
+ * pinned lookup that would have refused it is never called. That is a
+ * policy bypass that gets *more* likely the busier the daemon is, and it
+ * cost us a browser test that passed alone and failed in company.
+ *
+ * The price is no keep-alive for tool traffic, which for a fetch an agent
+ * makes a few times a turn is not a price worth a shared pool.
+ */
+const pinnedConnection = (policy) => ({
+    agent: false,
+    lookup: createPinnedLookup(policy),
+});
+/**
+ * A DNS lookup that hands the socket only addresses the policy allows.
+ *
+ * This is the whole point of the module. Resolving a name in one place and
+ * connecting in another is a DNS rebinding race: the attacker's server
+ * answers `93.184.216.34` for the check and `169.254.169.254` a moment
+ * later for the connection, and a checker that looked the name up itself
+ * would have validated an address nothing ever connected to. Node lets the
+ * connection's *own* resolution be replaced, so the addresses this returns
+ * are the addresses the socket uses — there is no second lookup to lose to.
+ */
+export const createPinnedLookup = (policy) => {
+    const lookup = (hostname, options, callback) => {
+        dns.lookup(hostname, { all: true, verbatim: true }, (error, addresses) => {
+            if (error) {
+                callback(error, '', 0);
+                return;
+            }
+            const permitted = addresses.filter((entry) => checkAddress(policy, hostname, entry.address).allowed);
+            if (permitted.length === 0) {
+                const first = addresses[0];
+                const verdict = first ? checkAddress(policy, hostname, first.address) : undefined;
+                callback(new EgressPolicyError(`Refusing to connect to ${hostname}: ${verdict?.reason ?? 'it resolves to no public address'}`), '', 0);
+                return;
+            }
+            if (options.all) {
+                callback(null, permitted);
+                return;
+            }
+            const [chosen] = permitted;
+            callback(null, chosen?.address ?? '', chosen?.family ?? 4);
+        });
+    };
+    return lookup;
+};
+/**
+ * One HTTP exchange, pinned to a validated address.
+ *
+ * Redirects are deliberately **not** followed here: each hop is a new
+ * request to a new host, so each one has to face the policy again. A
+ * caller loops and re-enters this, which is what makes "an approved public
+ * URL that redirects into the metadata endpoint" a refusal rather than a
+ * fetch.
+ */
+export const requestThroughPolicy = async (rawUrl, options = {}) => {
+    const policy = options.policy ?? {};
+    const url = assertRequestAllowed(rawUrl, policy);
+    const transport = url.protocol === 'https:' ? https : http;
+    const maxBytes = options.maxBytes ?? 2_000_000;
+    return new Promise((resolve, reject) => {
+        let deadline;
+        const settle = (finish) => (value) => {
+            if (deadline) {
+                clearTimeout(deadline);
+                deadline = undefined;
+            }
+            finish(value);
+        };
+        const succeed = settle(resolve);
+        const fail = settle(reject);
+        const request = transport.request(url, {
+            method: 'GET',
+            headers: options.headers ?? {},
+            ...pinnedConnection(policy),
+            ...(options.signal ? { signal: options.signal } : {}),
+        }, (response) => {
+            let body = '';
+            let bytes = 0;
+            let truncated = false;
+            response.setEncoding('utf8');
+            response.on('data', (chunk) => {
+                if (truncated) {
+                    return;
+                }
+                const size = Buffer.byteLength(chunk, 'utf8');
+                if (bytes + size > maxBytes) {
+                    truncated = true;
+                    // Kept to the cap, not to the end of whichever chunk crossed
+                    // it: a single response can arrive in one piece, and "stop
+                    // after the chunk that went over" is no cap at all.
+                    body += chunk.slice(0, Math.max(0, maxBytes - bytes));
+                    bytes = maxBytes;
+                    // Stop the transfer rather than reading a gigabyte into a
+                    // string we have already decided not to keep.
+                    response.destroy();
+                    return;
+                }
+                bytes += size;
+                body += chunk;
+            });
+            response.on('error', (error) => {
+                if (truncated) {
+                    succeed({ status: response.statusCode ?? 0, headers: response.headers, body, truncated });
+                    return;
+                }
+                fail(error);
+            });
+            response.on('end', () => {
+                succeed({ status: response.statusCode ?? 0, headers: response.headers, body, truncated });
+            });
+            response.on('close', () => {
+                if (truncated) {
+                    succeed({ status: response.statusCode ?? 0, headers: response.headers, body, truncated });
+                }
+            });
+        });
+        if (options.timeoutMs) {
+            // A deadline for the whole exchange, not for a quiet socket.
+            // `setTimeout` on a request fires on *inactivity*, so a server that
+            // sends one byte before each interval keeps a fetch alive forever —
+            // which for a one-shot `stratus run` is a command that never returns.
+            // Both are armed: the wall clock bounds the exchange, and the
+            // inactivity timer still ends a connection that has simply stalled.
+            deadline = setTimeout(() => {
+                request.destroy(new Error(`Timed out after ${options.timeoutMs}ms: ${url.href}`));
+            }, options.timeoutMs);
+            deadline.unref?.();
+            request.setTimeout(options.timeoutMs, () => {
+                request.destroy(new Error(`Timed out after ${options.timeoutMs}ms of silence: ${url.href}`));
+            });
+        }
+        request.on('error', fail);
+        request.end();
+    });
+};
+/**
+ * A proxy that owns every connection a browser makes, so the browser's own
+ * resolver never decides where a request goes.
+ *
+ * Playwright can intercept requests, but interception happens in the
+ * browser and the browser resolves the name itself afterwards — validating
+ * there is the rebinding race again, one process further away. Routing
+ * Chromium through a proxy that resolves, validates, and connects means the
+ * socket the page gets is the socket this policy opened, for the address it
+ * checked. Redirects and subresources come back through here too, because
+ * every request does.
+ */
+/**
+ * The `host:port` a CONNECT carries, which is not a plain split on colons.
+ *
+ * A literal IPv6 host arrives bracketed — `[2606:4700::1111]:443` — and
+ * splitting that on every colon yields a host of `[`, which is then looked
+ * up in DNS and fails. Every IPv6-literal HTTPS page a browser is pointed
+ * at would be unreachable, and the failure would read as a policy refusal
+ * rather than a parse bug.
+ */
+const parseAuthority = (authority) => {
+    const bracketed = /^\[(?<host>[^\]]+)\](?::(?<port>\d+))?$/.exec(authority);
+    const plain = /^(?<host>[^:]+)(?::(?<port>\d+))?$/.exec(authority);
+    const groups = (bracketed ?? plain)?.groups;
+    if (!groups?.host) {
+        return undefined;
+    }
+    const port = groups.port === undefined ? 443 : Number(groups.port);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        return undefined;
+    }
+    return { host: groups.host, port };
+};
+export const createEgressProxy = async (policy = {}) => {
+    const refusals = [];
+    const sockets = new Set();
+    const dial = async (host, port) => {
+        const addresses = await dns.promises.lookup(host, { all: true, verbatim: true });
+        const permitted = addresses.find((entry) => checkAddress(policy, host, entry.address).allowed);
+        if (!permitted) {
+            const first = addresses[0];
+            const verdict = first ? checkAddress(policy, host, first.address) : undefined;
+            throw new EgressPolicyError(`Refusing to connect to ${host}: ${verdict?.reason ?? 'it resolves to no public address'}`);
+        }
+        // Connected to the checked address itself, not to the name: a second
+        // resolution is a second answer, and the attacker chooses when it
+        // changes.
+        return net.connect({ host: permitted.address, port });
+    };
+    const server = http.createServer();
+    server.on('connect', (request, clientSocket, head) => {
+        sockets.add(clientSocket);
+        clientSocket.on('close', () => sockets.delete(clientSocket));
+        const target = parseAuthority(request.url ?? '');
+        if (!target) {
+            clientSocket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+            return;
+        }
+        const { host, port } = target;
+        dial(host, port).then((upstream) => {
+            sockets.add(upstream);
+            upstream.on('close', () => sockets.delete(upstream));
+            clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+            if (head.length > 0) {
+                upstream.write(head);
+            }
+            upstream.pipe(clientSocket);
+            clientSocket.pipe(upstream);
+            upstream.on('error', () => clientSocket.destroy());
+            clientSocket.on('error', () => upstream.destroy());
+        }, (error) => {
+            const reason = error instanceof Error ? error.message : String(error);
+            refusals.push(reason);
+            // 403 rather than a dropped socket: the page sees a refusal it can
+            // render, and the reason reaches the agent through `refusals`.
+            clientSocket.end(`HTTP/1.1 403 Forbidden\r\n\r\n${reason}`);
+        });
+    });
+    server.on('request', (request, response) => {
+        // Plain HTTP arrives as an absolute-URI request rather than a CONNECT.
+        let target;
+        try {
+            target = assertRequestAllowed(request.url ?? '', policy);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            refusals.push(reason);
+            response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+            response.end(reason);
+            return;
+        }
+        const upstream = http.request({
+            host: target.hostname,
+            port: target.port ? Number(target.port) : 80,
+            path: `${target.pathname}${target.search}`,
+            method: request.method ?? 'GET',
+            headers: request.headers,
+            ...pinnedConnection(policy),
+        }, (upstreamResponse) => {
+            response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+            upstreamResponse.pipe(response);
+        });
+        upstream.on('error', (error) => {
+            refusals.push(error.message);
+            if (!response.headersSent) {
+                response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+            }
+            response.end(error.message);
+        });
+        request.pipe(upstream);
+    });
+    await new Promise((resolve) => {
+        // Loopback only: this proxy exists to narrow what one process may
+        // reach, and a proxy on a shared interface is an open relay.
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const port = server.address().port;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        port,
+        refusals,
+        async close() {
+            for (const socket of sockets) {
+                socket.destroy();
+            }
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+            });
+        },
+    };
+};
+/**
+ * What a Chromium launch needs to be actually pinned to a proxy.
+ *
+ * `--proxy-bypass-list=<-loopback>` is not optional: Chromium bypasses the
+ * proxy for loopback and `localhost` by default, so a browser pointed at
+ * this proxy would still reach `http://127.0.0.1:8080` directly — which is
+ * one of the exact destinations the proxy exists to refuse.
+ */
+export const chromiumProxyOptions = (proxy) => ({
+    server: proxy.url,
+    // Same reason as the flag below, in the form Playwright takes.
+    bypass: '<-loopback>',
+});
+export const chromiumProxyArgs = (proxy) => [
+    `--proxy-server=${proxy.url}`,
+    '--proxy-bypass-list=<-loopback>',
+];
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

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

package/dist/fixtures.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The table every tool that reaches the network is tested against.
+ *
+ * Shipped in `src` rather than kept in one package's tests because two
+ * packages must be held to it, and the acceptance criterion for that is
+ * exact: `web.fetch` refuses the same addresses and schemes as `browser.*`,
+ * *proven by a test that runs the same table through both*. If the shared
+ * module is ever forked, this is what fails — in whichever package forked
+ * it, because both suites read this list rather than their own.
+ */
+export interface HostileUrl {
+    url: string;
+    /** What it is, for a failing assertion that names the hole rather than an index. */
+    what: string;
+}
+export declare const HOSTILE_URLS: HostileUrl[];
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,EAAE,UAAU,EAwBpC,CAAC"}

package/dist/fixtures.js

@@ -0,0 +1,26 @@
+export const HOSTILE_URLS = [
+    { url: 'file:///home/ada/.stratus/credentials.json', what: 'the credential store, by file: URL' },
+    { url: 'file:///etc/passwd', what: 'a local file' },
+    { url: 'data:text/html,<script>fetch("http://169.254.169.254")</script>', what: 'an inline document' },
+    { url: 'javascript:fetch("http://127.0.0.1")', what: 'a javascript: URL' },
+    { url: 'ftp://example.com/secrets', what: 'a scheme nobody asked for' },
+    { url: 'http://169.254.169.254/latest/meta-data/', what: 'cloud instance metadata' },
+    { url: 'http://[fd00::1]/', what: 'an IPv6 unique-local address' },
+    { url: 'http://[::ffff:169.254.169.254]/', what: 'metadata again, as an IPv4-mapped IPv6 address' },
+    { url: 'http://[::ffff:127.0.0.1]/', what: 'loopback, as an IPv4-mapped IPv6 address' },
+    { url: 'http://[64:ff9b::a9fe:a9fe]/', what: 'metadata again, through NAT64' },
+    { url: 'http://[64:ff9b:1::a9fe:a9fe]/', what: 'metadata again, through the local-use NAT64 prefix' },
+    { url: 'http://[2002:a9fe:a9fe::]/', what: 'metadata again, through 6to4' },
+    { url: 'http://127.0.0.1:4123/api/v1/credentials', what: 'the daemon’s own control API' },
+    { url: 'http://[::1]:4123/api/v1/credentials', what: 'the control API over IPv6 loopback' },
+    { url: 'http://localhost:4123/api/v1/credentials', what: 'the control API by name' },
+    { url: 'http://10.0.0.5/', what: 'an RFC 1918 address' },
+    { url: 'http://172.16.4.4/', what: 'an RFC 1918 address in the /12' },
+    { url: 'http://192.168.1.1/', what: 'the home router' },
+    { url: 'http://100.100.100.200/', what: 'a carrier-NAT address' },
+    { url: 'http://[fe80::1]/', what: 'an IPv6 link-local address' },
+    { url: 'http://0.0.0.0/', what: 'the unspecified address' },
+    { url: 'http://192.0.0.1/', what: 'IETF protocol assignment space' },
+    { url: 'http://224.0.0.1/', what: 'multicast' },
+];
+//# sourceMappingURL=fixtures.js.map

package/dist/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,EAAE,GAAG,EAAE,4CAA4C,EAAE,IAAI,EAAE,oCAAoC,EAAE;IACjG,EAAE,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,cAAc,EAAE;IACnD,EAAE,GAAG,EAAE,iEAAiE,EAAE,IAAI,EAAE,oBAAoB,EAAE;IACtG,EAAE,GAAG,EAAE,sCAAsC,EAAE,IAAI,EAAE,mBAAmB,EAAE;IAC1E,EAAE,GAAG,EAAE,2BAA2B,EAAE,IAAI,EAAE,2BAA2B,EAAE;IACvE,EAAE,GAAG,EAAE,0CAA0C,EAAE,IAAI,EAAE,yBAAyB,EAAE;IACpF,EAAE,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,8BAA8B,EAAE;IAClE,EAAE,GAAG,EAAE,kCAAkC,EAAE,IAAI,EAAE,gDAAgD,EAAE;IACnG,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,0CAA0C,EAAE;IACvF,EAAE,GAAG,EAAE,8BAA8B,EAAE,IAAI,EAAE,+BAA+B,EAAE;IAC9E,EAAE,GAAG,EAAE,gCAAgC,EAAE,IAAI,EAAE,oDAAoD,EAAE;IACrG,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,8BAA8B,EAAE;IAC3E,EAAE,GAAG,EAAE,0CAA0C,EAAE,IAAI,EAAE,8BAA8B,EAAE;IACzF,EAAE,GAAG,EAAE,sCAAsC,EAAE,IAAI,EAAE,oCAAoC,EAAE;IAC3F,EAAE,GAAG,EAAE,0CAA0C,EAAE,IAAI,EAAE,yBAAyB,EAAE;IACpF,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,qBAAqB,EAAE;IACxD,EAAE,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,gCAAgC,EAAE;IACrE,EAAE,GAAG,EAAE,qBAAqB,EAAE,IAAI,EAAE,iBAAiB,EAAE;IACvD,EAAE,GAAG,EAAE,yBAAyB,EAAE,IAAI,EAAE,uBAAuB,EAAE;IACjE,EAAE,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,4BAA4B,EAAE;IAChE,EAAE,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,yBAAyB,EAAE;IAC3D,EAAE,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,gCAAgC,EAAE;IACpE,EAAE,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,WAAW,EAAE;CAChD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One implementation of the address policy, shared.
+ *
+ * `tool-web` and `tool-browser` both reach the network on an agent's
+ * instruction, and a second hand-rolled copy of "which addresses may a tool
+ * reach" would not be a drift — it would be an SSRF hole in whichever copy
+ * was not updated. So the rule lives here, once, and the packages that
+ * enforce it import it.
+ */
+export { assertRequestAllowed, checkAddress, classifyAddress, EgressPolicyError, type AddressVerdict, type EgressPolicy, } from './addresses.ts';
+export { chromiumProxyArgs, chromiumProxyOptions, createEgressProxy, createPinnedLookup, policyKeyFor, requestThroughPolicy, type EgressProxy, type PolicyRequestOptions, type PolicyResponse, } from './connect.ts';
+export { HOSTILE_URLS, type HostileUrl } from './fixtures.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * One implementation of the address policy, shared.
+ *
+ * `tool-web` and `tool-browser` both reach the network on an agent's
+ * instruction, and a second hand-rolled copy of "which addresses may a tool
+ * reach" would not be a drift — it would be an SSRF hole in whichever copy
+ * was not updated. So the rule lives here, once, and the packages that
+ * enforce it import it.
+ */
+export { assertRequestAllowed, checkAddress, classifyAddress, EgressPolicyError, } from "./addresses.js";
+export { chromiumProxyArgs, chromiumProxyOptions, createEgressProxy, createPinnedLookup, policyKeyFor, requestThroughPolicy, } from "./connect.js";
+export { HOSTILE_URLS } from "./fixtures.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,iBAAiB,GAGlB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,GAIrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAmB,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@stratusagent/egress",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.13 <23 || >=23.4"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stratuslabs/agent.git",
+    "directory": "packages/egress"
+  },
+  "description": "The Stratus Agent egress policy: which addresses a tool may reach, enforced on the connection rather than on the name it was asked for",
+  "keywords": [
+    "stratus",
+    "agent",
+    "ai",
+    "llm",
+    "ssrf",
+    "security"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
+    "test": "node --test --experimental-strip-types"
+  }
+}