@molecule/api-code-sandbox-flyio 1.0.1

package/dist/api.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Minimal HTTP client for the Fly Machines API.
+ *
+ * Speaks the documented REST surface at `https://api.machines.dev/v1` with a
+ * `Authorization: Bearer <token>` header
+ * (https://fly.io/docs/machines/api/working-with-machines-api/).
+ *
+ * The one non-obvious responsibility here is RATE LIMITING. Fly documents the
+ * Machines API at "1 request, per second, per action (i.e. Create Machine, Start
+ * Machine etc.) — with a short-term burst limit up to 3 req/s, per action", and
+ * 5 req/s (burst 10) for Get Machine. A sandbox boot issues a burst of calls
+ * (ensure app → create volume → create machine → wait → several execs), so a
+ * client with no 429 handling WILL trip that limit under concurrent boots and
+ * fail the whole boot. Retries are therefore part of the transport, not the
+ * caller's problem.
+ *
+ * @module
+ */
+/**
+ * An error from the Fly Machines API. Carries the HTTP status and the raw
+ * response body so callers can branch on `404` (absent) or `409` (conflict)
+ * without string-matching a message.
+ */
+export declare class FlyApiError extends Error {
+    /** HTTP status code, or 0 for a transport-level failure (timeout, DNS, reset). */
+    readonly status: number;
+    /** Raw response body text, truncated to a sane length for logging. */
+    readonly body: string;
+    /** HTTP method of the failed request. */
+    readonly method: string;
+    /** API path of the failed request (no base URL). */
+    readonly path: string;
+    /**
+     * Creates a Fly API error.
+     * @param method - HTTP method of the failed request.
+     * @param path - API path of the failed request.
+     * @param status - HTTP status code, or 0 for a transport failure.
+     * @param body - Raw response body text.
+     * @param options - Standard error options (used to carry a `cause`).
+     */
+    constructor(method: string, path: string, status: number, body: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Options for a single Fly API request. */
+export interface FlyRequestOptions {
+    /** HTTP method. Defaults to `GET`. */
+    method?: string;
+    /** JSON request body. Omitted entirely when undefined. */
+    body?: unknown;
+    /** Per-request timeout in ms. Defaults to the client's configured timeout. */
+    timeoutMs?: number;
+    /** Max attempts for a retryable failure. Defaults to 4. Pass 1 to disable retries. */
+    attempts?: number;
+    /**
+     * Treat these HTTP statuses as a successful `null` result instead of throwing.
+     * Used for idempotent deletes and existence checks (`[404]`).
+     */
+    nullOn?: number[];
+}
+/**
+ * Decides whether a failed attempt is worth repeating.
+ *
+ * `429` (the documented per-action rate limit) and `5xx` are transient — the
+ * request was well-formed and the same call can succeed moments later. Every
+ * other `4xx` is a real answer (no such app, name taken, bad token) and
+ * retrying it only wastes the rate-limit budget that the retry exists to
+ * protect. Status `0` means the transport failed before any answer arrived.
+ * @param status - HTTP status, or 0 for a transport-level failure.
+ * @returns `true` when the request should be retried.
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * Resolves how long to wait before the next attempt.
+ *
+ * Honors a `Retry-After` header when the server sent one (Fly returns it on
+ * 429), clamped to {@link MAX_RETRY_DELAY_MS}; otherwise uses exponential
+ * backoff from a 500 ms base. Fly's documented budget is one request per second
+ * per action, so the first backoff step deliberately exceeds a second.
+ * @param attempt - The 1-based attempt number that just failed.
+ * @param retryAfter - Raw `Retry-After` header value, if present.
+ * @returns The delay in milliseconds before the next attempt.
+ */
+export declare function retryDelayMs(attempt: number, retryAfter?: string | null): number;
+/**
+ * Normalizes a configured API base into a URL prefix ending in `/v1`.
+ *
+ * `FLY_API_HOSTNAME` is documented as a bare host (`https://api.machines.dev`,
+ * or `http://_api.internal:4280` from inside a Fly private network), so a value
+ * with no path gets `/v1` appended. A value that already carries a path is used
+ * verbatim, which is how an operator points at a proxy or a pinned version.
+ * @param value - Configured base URL, or undefined.
+ * @returns The base URL with no trailing slash.
+ */
+export declare function normalizeApiUrl(value: string | undefined): string;
+/** Constructor options for {@link FlyApiClient}. */
+export interface FlyApiClientOptions {
+    /** Bearer token. Resolved lazily so env/secrets can land after construction. */
+    token: () => string | undefined;
+    /** Base URL including `/v1`. */
+    baseUrl: string;
+    /** Default per-request timeout (ms). */
+    timeoutMs?: number;
+    /** Injectable fetch, for tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injectable sleep, for tests. Defaults to `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Thin, retrying JSON client for the Fly Machines API.
+ *
+ * Deliberately not a generated SDK: this provider touches ~12 endpoints, and a
+ * generated client would drag in the whole Machines + Postgres + tokens surface
+ * for no benefit.
+ */
+export declare class FlyApiClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly sleep;
+    /**
+     * Creates a Fly Machines API client.
+     * @param options - Token resolver, base URL, and injectable fetch/sleep.
+     */
+    constructor(options: FlyApiClientOptions);
+    /**
+     * Issues a request against the Machines API and parses the JSON response.
+     *
+     * @template T - Expected shape of the parsed response body.
+     * @param path - API path relative to the base URL, e.g. `/apps/foo/machines`.
+     * @param options - Method, body, timeout, attempts, and statuses to null on.
+     * @returns The parsed body, or `null` for an empty body or a status listed in
+     *   `options.nullOn`.
+     * @throws {FlyApiError} On a non-2xx status that is not listed in `nullOn`,
+     *   or when every retryable attempt is exhausted.
+     */
+    request<T>(path: string, options?: FlyRequestOptions): Promise<T | null>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBhC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBjE;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IAErD;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IASxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CA4EnF"}

package/dist/api.js

@@ -0,0 +1,226 @@
+/**
+ * Minimal HTTP client for the Fly Machines API.
+ *
+ * Speaks the documented REST surface at `https://api.machines.dev/v1` with a
+ * `Authorization: Bearer <token>` header
+ * (https://fly.io/docs/machines/api/working-with-machines-api/).
+ *
+ * The one non-obvious responsibility here is RATE LIMITING. Fly documents the
+ * Machines API at "1 request, per second, per action (i.e. Create Machine, Start
+ * Machine etc.) — with a short-term burst limit up to 3 req/s, per action", and
+ * 5 req/s (burst 10) for Get Machine. A sandbox boot issues a burst of calls
+ * (ensure app → create volume → create machine → wait → several execs), so a
+ * client with no 429 handling WILL trip that limit under concurrent boots and
+ * fail the whole boot. Retries are therefore part of the transport, not the
+ * caller's problem.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const logger = getLogger();
+/** Default per-request timeout (ms). */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Default number of attempts for a retryable failure. */
+const DEFAULT_ATTEMPTS = 4;
+/** Upper bound on a `Retry-After`-derived delay, so a hostile header cannot stall a boot. */
+const MAX_RETRY_DELAY_MS = 10_000;
+/**
+ * An error from the Fly Machines API. Carries the HTTP status and the raw
+ * response body so callers can branch on `404` (absent) or `409` (conflict)
+ * without string-matching a message.
+ */
+export class FlyApiError extends Error {
+    /** HTTP status code, or 0 for a transport-level failure (timeout, DNS, reset). */
+    status;
+    /** Raw response body text, truncated to a sane length for logging. */
+    body;
+    /** HTTP method of the failed request. */
+    method;
+    /** API path of the failed request (no base URL). */
+    path;
+    /**
+     * Creates a Fly API error.
+     * @param method - HTTP method of the failed request.
+     * @param path - API path of the failed request.
+     * @param status - HTTP status code, or 0 for a transport failure.
+     * @param body - Raw response body text.
+     * @param options - Standard error options (used to carry a `cause`).
+     */
+    constructor(method, path, status, body, options) {
+        super(t('codeSandbox.flyio.error.apiError', { method, path, status: String(status), error: body }, { defaultValue: `Fly API ${method} ${path}: ${status} ${body}` }), options);
+        this.name = 'FlyApiError';
+        this.status = status;
+        this.body = body;
+        this.method = method;
+        this.path = path;
+    }
+}
+/**
+ * Decides whether a failed attempt is worth repeating.
+ *
+ * `429` (the documented per-action rate limit) and `5xx` are transient — the
+ * request was well-formed and the same call can succeed moments later. Every
+ * other `4xx` is a real answer (no such app, name taken, bad token) and
+ * retrying it only wastes the rate-limit budget that the retry exists to
+ * protect. Status `0` means the transport failed before any answer arrived.
+ * @param status - HTTP status, or 0 for a transport-level failure.
+ * @returns `true` when the request should be retried.
+ */
+export function isRetryableStatus(status) {
+    return status === 0 || status === 429 || status >= 500;
+}
+/**
+ * Resolves how long to wait before the next attempt.
+ *
+ * Honors a `Retry-After` header when the server sent one (Fly returns it on
+ * 429), clamped to {@link MAX_RETRY_DELAY_MS}; otherwise uses exponential
+ * backoff from a 500 ms base. Fly's documented budget is one request per second
+ * per action, so the first backoff step deliberately exceeds a second.
+ * @param attempt - The 1-based attempt number that just failed.
+ * @param retryAfter - Raw `Retry-After` header value, if present.
+ * @returns The delay in milliseconds before the next attempt.
+ */
+export function retryDelayMs(attempt, retryAfter) {
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return Math.min(seconds * 1000, MAX_RETRY_DELAY_MS);
+        }
+    }
+    return Math.min(1000 * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS);
+}
+/**
+ * Normalizes a configured API base into a URL prefix ending in `/v1`.
+ *
+ * `FLY_API_HOSTNAME` is documented as a bare host (`https://api.machines.dev`,
+ * or `http://_api.internal:4280` from inside a Fly private network), so a value
+ * with no path gets `/v1` appended. A value that already carries a path is used
+ * verbatim, which is how an operator points at a proxy or a pinned version.
+ * @param value - Configured base URL, or undefined.
+ * @returns The base URL with no trailing slash.
+ */
+export function normalizeApiUrl(value) {
+    const raw = value?.trim();
+    if (!raw)
+        return 'https://api.machines.dev/v1';
+    const withoutSlash = raw.replace(/\/+$/, '');
+    try {
+        const url = new URL(withoutSlash);
+        if (url.pathname === '' || url.pathname === '/')
+            return `${withoutSlash}/v1`;
+        return withoutSlash;
+    }
+    catch (error) {
+        // Not an absolute URL — the operator gave something we cannot safely extend.
+        // Surface it instead of silently guessing a base for every subsequent call.
+        throw new Error(t('codeSandbox.flyio.error.badApiUrl', { value: raw }, { defaultValue: `Invalid Fly API URL "${raw}" — expected an absolute URL.` }), { cause: error });
+    }
+}
+/**
+ * Thin, retrying JSON client for the Fly Machines API.
+ *
+ * Deliberately not a generated SDK: this provider touches ~12 endpoints, and a
+ * generated client would drag in the whole Machines + Postgres + tokens surface
+ * for no benefit.
+ */
+export class FlyApiClient {
+    token;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    sleep;
+    /**
+     * Creates a Fly Machines API client.
+     * @param options - Token resolver, base URL, and injectable fetch/sleep.
+     */
+    constructor(options) {
+        this.token = options.token;
+        this.baseUrl = options.baseUrl;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.sleep =
+            options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /**
+     * Issues a request against the Machines API and parses the JSON response.
+     *
+     * @template T - Expected shape of the parsed response body.
+     * @param path - API path relative to the base URL, e.g. `/apps/foo/machines`.
+     * @param options - Method, body, timeout, attempts, and statuses to null on.
+     * @returns The parsed body, or `null` for an empty body or a status listed in
+     *   `options.nullOn`.
+     * @throws {FlyApiError} On a non-2xx status that is not listed in `nullOn`,
+     *   or when every retryable attempt is exhausted.
+     */
+    async request(path, options = {}) {
+        const method = options.method ?? 'GET';
+        const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+        const token = this.token();
+        if (!token) {
+            throw new Error(t('codeSandbox.flyio.error.noToken', undefined, {
+                defaultValue: 'No Fly API token — set FLY_API_TOKEN (or FLY_ACCESS_TOKEN), or pass config.apiToken.',
+            }));
+        }
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? this.timeoutMs);
+            // Initialized to 0 ("no answer received"), which is the value that
+            // stands when the request throws before a response arrives.
+            let status = 0;
+            let retryAfter = null;
+            try {
+                const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                    },
+                    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+                    signal: controller.signal,
+                });
+                status = response.status;
+                retryAfter = response.headers?.get?.('retry-after') ?? null;
+                const text = await response.text();
+                if (status >= 200 && status < 300) {
+                    if (!text.trim())
+                        return null;
+                    try {
+                        return JSON.parse(text);
+                    }
+                    catch (error) {
+                        // A 2xx with a non-JSON body is a real protocol surprise (an
+                        // intercepting proxy, an HTML error page behind a 200). Refusing it
+                        // loudly beats handing the caller a silently-empty result.
+                        throw new FlyApiError(method, path, status, text.slice(0, 500), { cause: error });
+                    }
+                }
+                if (options.nullOn?.includes(status))
+                    return null;
+                lastError = new FlyApiError(method, path, status, text.slice(0, 500));
+            }
+            catch (error) {
+                if (error instanceof FlyApiError)
+                    throw error;
+                // Transport-level failure (abort/timeout, DNS, connection reset) — no
+                // status was ever received, so it is modelled as status 0 and retried.
+                lastError = new FlyApiError(method, path, 0, error instanceof Error ? error.message : String(error), { cause: error });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!isRetryableStatus(status) || attempt === attempts)
+                break;
+            const delay = retryDelayMs(attempt, retryAfter);
+            logger.warn(`Fly API transient failure on ${method} ${path} — retrying`, {
+                attempt,
+                attempts,
+                status,
+                delay,
+            });
+            await this.sleep(delay);
+        }
+        throw lastError ?? new FlyApiError(method, path, 0, 'unknown failure');
+    }
+}

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-code-sandbox-flyio` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-code-sandbox-flyio is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/egress.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Fly network policies — the only egress restriction Fly.io exposes — and the
+ * pure logic behind the observation that proves one is actually in force.
+ *
+ * **What Fly actually offers.** 6PN custom private networks isolate apps from
+ * EACH OTHER ("Apps on separate 6PNs can never communicate unless explicitly
+ * configured to do so",
+ * https://fly.io/docs/networking/custom-private-networks/); they say nothing
+ * about reaching the public internet, which is a different question and the one
+ * `verifyEgress()` answers. The mechanism Fly documents for that is **network
+ * policies** (https://fly.io/docs/machines/guides-examples/network-policies/,
+ * announced at https://community.fly.io/t/new-feature-network-policies/19173):
+ * an app-scoped object with a `selector` and `allow` rules, where "Once you
+ * create a rule for a given direction, the default for that direction becomes
+ * drop."
+ *
+ * Three properties of that mechanism drive everything below, and every one of
+ * them is a limitation you cannot design around:
+ *
+ * 1. **Rules match protocol + port ONLY.** There is no host, IP or CIDR
+ *    matching, and (as of the announcement) no port ranges. A network policy
+ *    therefore CANNOT express a host allowlist. `allow tcp/443` permits a
+ *    sandbox to reach every host on the internet that listens on 443.
+ * 2. **They do not apply to Fly Proxy traffic** — stated in the docs and, in
+ *    the announcement, in capitals. Inbound preview traffic through the proxy
+ *    is unaffected by an ingress rule.
+ * 3. **They take effect at Machine boot.** Fly's own troubleshooting note:
+ *    "After creating or updating a policy, restart or redeploy the Machines for
+ *    changes to take effect." A policy applied to an app with an already-running
+ *    Machine does not retroactively cover it.
+ *
+ * The endpoints are documented in the guide and the announcement but are NOT in
+ * Fly's OpenAPI specification (https://docs.machines.dev/openapi.json — 68
+ * paths, none of them `network_policies`), so the request shape below is taken
+ * from those two documents verbatim and the LIST response shape, which neither
+ * document specifies, is parsed defensively by {@link extractPolicyId}.
+ *
+ * VERIFIED AGAINST A REAL FLY ORG, 2026-08-05 — the endpoints DO exist despite
+ * their absence from the spec:
+ *
+ *   GET  /apps/{app}/network_policies   -> 200 []
+ *   GET  /apps/{app}/network_policies/  -> 404 (trailing slash is NOT accepted)
+ *   POST /apps/{app}/network_policies   -> 400 {"error":"name is required"}
+ *
+ * The POST error is the useful one: it proves the route is real and validating,
+ * and that `name` is mandatory — which is why {@link DEFAULT_EGRESS_POLICY_NAME}
+ * is always sent.
+ *
+ * @module
+ */
+import type { EgressVerdict } from '@molecule/api-code-sandbox';
+import type { FlyNetworkPolicyPort } from './types.js';
+/** Default name of the egress policy this provider owns on each sandbox app. */
+export declare const DEFAULT_EGRESS_POLICY_NAME = "molecule-sandbox-egress";
+/**
+ * Probe exit status meaning at least one raw connection to a public IP
+ * SUCCEEDED. Deliberately not 1, so an interpreter error (which exits 1) can
+ * never be mistaken for a completed observation.
+ */
+export declare const EGRESS_PROBE_EXIT_REACHED = 9;
+/** Probe exit status meaning every raw connection attempt was refused or timed out. */
+export declare const EGRESS_PROBE_EXIT_BLOCKED = 0;
+/**
+ * Default probe targets: one IPv4 and one IPv6 literal, both anycast resolvers
+ * that answer on 443 from anywhere. IPv6 is included because Fly Machines have
+ * native public IPv6 egress and "often egress over IPv6 when the destination
+ * has an AAAA record" (https://fly.io/docs/networking/egress-ips/) — probing
+ * only IPv4 could miss an open v6 path entirely.
+ */
+export declare const DEFAULT_EGRESS_PROBE_TARGETS = "1.1.1.1:443,[2606:4700:4700::1111]:443";
+/** One literal host:port the probe attempts a raw TCP connection to. */
+export interface EgressProbeTarget {
+    /** A literal IPv4 or IPv6 address. Never a hostname — see {@link parseEgressProbeTargets}. */
+    host: string;
+    /** TCP port. */
+    port: number;
+}
+/** Context {@link verdictForProbeExit} renders its operator-facing messages from. */
+export interface EgressProbeContext {
+    /** Fly app the probe Machine ran in. */
+    app: string;
+    /** Targets the probe attempted. */
+    targets: EgressProbeTarget[];
+    /**
+     * Ports this provider's own egress policy allows, or `undefined` when it
+     * applies no policy at all. Used ONLY for the message and the remediation —
+     * never to decide the verdict, which comes from the observation alone.
+     */
+    policyPorts?: FlyNetworkPolicyPort[];
+}
+/**
+ * Renders a target the way it is written in configuration, so an operator can
+ * paste it straight back.
+ * @param target - The parsed target.
+ * @returns `host:port`, with IPv6 hosts bracketed.
+ */
+export declare function formatEgressProbeTarget(target: EgressProbeTarget): string;
+/**
+ * Parses probe targets from configuration.
+ *
+ * Only LITERAL addresses are accepted, never hostnames — Fly's own
+ * troubleshooting guidance for testing a policy is to "use direct IP addresses
+ * (not hostnames) to test blocked traffic to avoid DNS masking", and a probe
+ * that failed at name resolution would report a blocked connection it never
+ * actually attempted.
+ * @param raw - Comma-separated `ip:port` string, or an array of them. IPv6
+ *   literals must be bracketed (`[2606:4700:4700::1111]:443`).
+ * @returns The valid targets, in order. Invalid entries are dropped rather than
+ *   throwing: the caller turns an empty result into an `inconclusive` verdict,
+ *   which is the honest outcome for "nothing to probe".
+ */
+export declare function parseEgressProbeTargets(raw: string | string[] | undefined): EgressProbeTarget[];
+/**
+ * Parses an allowed-port list for the egress network policy.
+ *
+ * An EMPTY list is deliberately not expressible. Fly documents the deny default
+ * as a consequence of at least one `allow` rule existing for a direction; what
+ * an allow rule with zero ports does is not documented anywhere, so a provider
+ * that sent one would be guessing at a security control. An operator who wants
+ * near-total denial allows a single port nothing in the sandbox uses.
+ * @param raw - Comma-separated `protocol:port` pairs, e.g. `tcp:3128,udp:53`.
+ *   A bare port is treated as TCP.
+ * @returns The parsed ports, or `undefined` when the input is absent or empty
+ *   (meaning "apply no policy"), which is NOT the same as "deny everything".
+ * @throws {Error} When an entry is present but unparseable — silently dropping a
+ *   port from a security control would produce a policy the operator never wrote.
+ */
+export declare function parseEgressAllowedPorts(raw: string | undefined): FlyNetworkPolicyPort[] | undefined;
+/**
+ * Builds the shell command that observes egress from inside a Machine.
+ *
+ * Raw `net.connect` on purpose: an HTTP client would honour proxy environment
+ * variables and report the PROXY's policy instead of the network's. Every target
+ * is attempted in parallel and the process exits
+ * {@link EGRESS_PROBE_EXIT_REACHED} if any connected,
+ * {@link EGRESS_PROBE_EXIT_BLOCKED} if all were refused or timed out.
+ * @param targets - Literal targets to attempt.
+ * @param timeoutMs - Per-connection timeout.
+ * @returns A `sh`-safe command string.
+ */
+export declare function buildEgressProbeCommand(targets: EgressProbeTarget[], timeoutMs: number): string;
+/**
+ * Maps a probe's exit status onto an {@link EgressVerdict}.
+ *
+ * The mapping is the whole security contract of this file, so it is total and
+ * has exactly one path to each state:
+ *
+ * | Exit | Verdict | Meaning |
+ * |---|---|---|
+ * | {@link EGRESS_PROBE_EXIT_REACHED} | `open` | A raw socket reached a public IP. |
+ * | {@link EGRESS_PROBE_EXIT_BLOCKED} | `filtered` | Every attempt was refused or timed out. |
+ * | anything else | `inconclusive` | The probe did not complete its attempts. |
+ *
+ * Every other outcome — a missing interpreter (127), a killed process, Fly
+ * returning no status at all (-1), an API failure before the probe ever ran — is
+ * `inconclusive`. Collapsing any of those into `filtered` is precisely the "I
+ * could not look" ⇒ "I looked and it is safe" conflation the capability exists
+ * to prevent, and the caller refuses to boot production on anything but
+ * `filtered`.
+ * @param exitCode - The probe process's exit status.
+ * @param context - App, targets and the policy this provider applied.
+ * @returns The verdict.
+ */
+export declare function verdictForProbeExit(exitCode: number, context: EgressProbeContext): EgressVerdict;
+/**
+ * Finds an existing policy's id in a LIST response, so the next write updates it
+ * instead of stacking duplicates.
+ *
+ * Neither the guide nor the announcement specifies what
+ * `GET /v1/apps/{app}/network_policies/` returns, and the endpoint is absent
+ * from Fly's OpenAPI specification — so this accepts a bare array or an object
+ * wrapping one under any of the plausible keys, and returns `undefined` for
+ * anything it does not recognize. `undefined` is safe: the caller then POSTs
+ * without an `id`, which still applies the policy.
+ * @param response - The raw parsed LIST response.
+ * @param name - The policy name to match.
+ * @returns The matching policy's id, or `undefined`.
+ */
+export declare function extractPolicyId(response: unknown, name: string): string | undefined;
+//# sourceMappingURL=egress.d.ts.map

package/dist/egress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../src/egress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAGtD,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,4BAA4B,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,2CAA2C,CAAA;AAEpF,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,mCAAmC;IACnC,OAAO,EAAE,iBAAiB,EAAE,CAAA;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAA;CACrC;AAQD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAGzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,iBAAiB,EAAE,CAc/F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,oBAAoB,EAAE,GAAG,SAAS,CAyBpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAY/F;AAaD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CA0ChG;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAanF"}