@molecule/api-code-sandbox-flyio 1.0.18 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-08T23:10:20.743Z
+Generated: 2026-08-16T14:04:35.624Z
 -->
 
 # @molecule/api-code-sandbox-flyio
@@ -75,7 +75,7 @@ const warm = await provider.create({
 ## Installation
 
 ```bash
-npm install @molecule/api-code-sandbox-flyio @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @molecule/api-bond @molecule/api-code-sandbox @molecule/api-i18n
+npm install @molecule/api-code-sandbox-flyio @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @molecule/api-bond @molecule/api-code-sandbox @molecule/api-i18n @molecule/api-proxy-agent
 ```
 
 ## API
@@ -94,10 +94,24 @@ interface EgressProbeContext {
   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.
+   * applies no policy at all. Used for the message, the remediation, and as the
+   * INTENT half of the drift check against {@link appliedPolicyPorts} — never to
+   * decide `open` vs `filtered` from a probe that reached a target, which comes
+   * from the observation alone.
    */
   policyPorts?: FlyNetworkPolicyPort[]
+  /**
+   * Ports the policy Fly ACTUALLY holds for this app allows, read back from the
+   * API after the probe ran, or `undefined` when the readback failed or found no
+   * policy of this provider's name.
+   *
+   * This is the observation half of the only drift this module can catch: a
+   * policy widened outside the provider (by hand, by another tool, by an older
+   * build) allows ports nothing here configured, and the raw-connect probe
+   * cannot see it because it only attempts the targets it was given. See
+   * {@link unexpectedPolicyPorts}.
+   */
+  appliedPolicyPorts?: FlyNetworkPolicyPort[]
 }
 ```
 
@@ -133,6 +147,30 @@ interface FlyApiClientOptions {
 }
 ```
 
+#### `FlyApp`
+
+An app as returned by `GET /v1/apps?org_slug=…` (the fields this provider reads).
+
+```typescript
+interface FlyApp {
+  id?: string
+  name: string
+  machine_count?: number
+}
+```
+
+#### `FlyAppList`
+
+Response body of `GET /v1/apps?org_slug=…`.
+
+```typescript
+interface FlyAppList {
+  /** Total apps in the org, which the returned page may not cover. */
+  total_apps?: number
+  apps?: FlyApp[]
+}
+```
+
 #### `FlyExecResponse`
 
 Response body of `POST /v1/apps/{app}/machines/{id}/exec` (`flydv1.ExecResponse`).
@@ -244,10 +282,13 @@ interface FlyioConfig {
    */
   publicService?: boolean
   /**
-   * Fly Proxy idle behaviour for the preview service. `suspend` (the default)
-   * is the scale-to-zero mapping this bond exists for: the proxy suspends an
-   * idle Machine and resumes it from its memory snapshot on the next request.
-   * `stop` is a full stop (cold boot on wake); `off` never idles the Machine.
+   * Fly Proxy idle behaviour for the preview service. Defaults to `'off'` —
+   * never idle the Machine — because the autostop timer counts the PROXY
+   * service's idle time, not the workload's, so a sandbox with nobody looking at
+   * its preview is suspended out from under a build that is still running.
+   * `suspend` is the scale-to-zero mapping (resume from a memory snapshot on the
+   * next request) and `stop` is a full stop with a cold boot on wake; opt into
+   * either deliberately.
    */
   autostop?: 'off' | 'stop' | 'suspend'
   /**
@@ -264,9 +305,12 @@ interface FlyioConfig {
   /** Timeout for a single Machines API request, in ms. Defaults to 30000. */
   requestTimeoutMs?: number
   /**
-   * How long `start()`/`wake()` block waiting for the Machine to actually reach
-   * `started`, in seconds. Clamped to Fly's own ceiling — `GET .../wait` "will
-   * block for up to 60 seconds". Defaults to 60.
+   * TOTAL budget, in seconds, that `create()`/`start()`/`wake()` block waiting
+   * for the Machine to actually reach `started`. Fly's `GET .../wait` blocks
+   * for at most 60 seconds per call, so a larger budget is spent as consecutive
+   * wait rounds. Defaults to 180 — a Machine whose image is not yet cached on
+   * its host (every first boot after an image push) pulls it before starting,
+   * and that alone can exceed a single 60 s round.
    *
    * Without this wait, `start()` resolves the moment Fly ACCEPTS the request,
    * and the caller's very next `exec` hits a Machine that is not running yet.
@@ -449,6 +493,14 @@ interface FlyMachine {
   region?: string
   private_ip?: string
   config?: FlyMachineConfig
+  /** RFC 3339 creation time, as Fly reports it. */
+  created_at?: string
+  /**
+   * Lifecycle events, newest first. The ONLY place Fly records when a Machine
+   * was first started — there is no `started_at` field — which is what
+   * distinguishes a stopped Machine from one that was created and never ran.
+   */
+  events?: FlyMachineEvent[]
 }
 ```
 
@@ -470,6 +522,20 @@ interface FlyMachineConfig {
 }
 ```
 
+#### `FlyMachineEvent`
+
+One entry of {@link FlyMachine.events}.
+
+```typescript
+interface FlyMachineEvent {
+  /** `start`, `launch`, `exit`, … */
+  type?: string
+  status?: string
+  /** Epoch milliseconds. */
+  timestamp?: number
+}
+```
+
 #### `FlyMachineService`
 
 A Fly Proxy service attached to a Machine (`fly.MachineService`).
@@ -528,6 +594,13 @@ One rule in a Fly network policy. `allow` is the only documented action:
 "Once you create a rule for a given direction, the default for that direction
 becomes drop."
 
+There is no destination field, and that is measured rather than assumed
+(2026-08-16, live API): `ipv6_cidrs`, `ipv4_cidrs`, `cidrs`, `destinations`,
+`apps`, `app`, `to` and `dst` were each POSTed on a rule and each came back
+absent — the stored rule is `{action, direction, ports}` and nothing more. An
+`allow tcp/5432` rule therefore permits the Machine to reach port 5432 on
+every host on the internet.
+
 ```typescript
 interface FlyNetworkPolicyRule {
   /** Only `allow` is supported by Fly. */
@@ -541,8 +614,16 @@ interface FlyNetworkPolicyRule {
 
 #### `FlyNetworkPolicySelector`
 
-Which Machines in the app a policy applies to. Documented criteria combine
-with AND, so this provider uses `{ all: true }` alone.
+Which Machines in the app a policy applies to — the SOURCE side only. There is
+no destination selector: an `apps` array is the one candidate the API answers
+about, and it answers `400 {"error":"apps array not currently supported in
+selectors"}` (measured 2026-08-16); every other candidate field is silently
+dropped. Documented criteria combine with AND, so this provider uses
+`{ all: true }` alone.
+
+The API's LIST response returns this object under the key `netpolSelector`
+while accepting it as `selector` on write — which is why nothing here reads it
+back by name.
 
 ```typescript
 interface FlyNetworkPolicySelector {
@@ -855,11 +936,9 @@ type RawExec = (command: string[], timeoutSeconds: number) => Promise<FlyExecRes
 
 #### `FlyApiClient`
 
-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.
+Minimal Fly Machines API client: bearer auth, JSON bodies, per-request
+timeout, bounded retries with backoff, and account-wide request pacing via
+{@link paceFlyRequest}.
 
 #### `FlyApiError`
 
@@ -1115,6 +1194,28 @@ function decodePrivateRoutes(raw: string | undefined): Record<string, string>
 
 **Returns:** Target app name → allocated private address. Unparseable entries are skipped: this value only drives cleanup and self-healing, and a malformed entry must not stop either.
 
+#### `describePublicReach(policyPorts)`
+
+States, in the verdict itself, what an allowed port actually permits.
+
+A Fly network policy has no destination (see the module description — measured
+against the live API, not inferred), so every allowed port is open to every
+host on the internet, not only to the private service it was derived for. That
+is the single most consequential thing about this mechanism and it was invisible
+everywhere it mattered: the probe attempts one port the policy denies, reports
+`filtered`, and an operator reasonably reads that as "nothing gets out".
+
+Naming it here means the residual is restated on every re-probe (the consumer
+re-verifies every 15 minutes) instead of living only in a document.
+
+```typescript
+function describePublicReach(policyPorts: FlyNetworkPolicyPort[] | undefined): string
+```
+
+- `policyPorts` — Allowed ports, or `undefined` when no policy is applied.
+
+**Returns:** A sentence naming the public reach, or `''` when there is nothing to say (no policy, or nothing but UDP/53 — DNS is a documented residual of its own and not a TCP channel).
+
 #### `encodePrivateRoutes(routes)`
 
 Encodes allocated addresses for storage in Machine metadata.
@@ -1173,6 +1274,32 @@ function extractPolicyId(response: unknown, name: string): string | undefined
 
 **Returns:** The matching policy's id, or `undefined`.
 
+#### `extractPolicyPorts(response, name)`
+
+Reads back the egress ports the policy Fly ACTUALLY holds allows.
+
+The write is not the observation: this provider POSTs a policy, but what
+governs a Machine is whatever Fly has when that Machine boots — which may
+differ because a person, another tool or an older build changed it. Reading it
+back is what lets {@link unexpectedPolicyPorts} catch a policy wider than the
+one this provider configured, so `verifyEgress()` can fail on drift its raw
+connects were never going to attempt.
+
+Parsed as defensively as {@link extractPolicyId}, and for the same reason:
+neither Fly document specifies the LIST response shape. The live API answers
+with a bare array whose selector key is `netpolSelector` rather than the
+`selector` it accepts (verified 2026-08-16), which is exactly why nothing here
+depends on any key but `name` and `rules`.
+
+```typescript
+function extractPolicyPorts(response: unknown, name: string): FlyNetworkPolicyPort[] | undefined
+```
+
+- `response` — The raw parsed LIST response.
+- `name` — The policy name to match.
+
+**Returns:** The allowed egress ports, or `undefined` when no policy of that name is present or the shape is unrecognized. `undefined` means "nothing to compare", never "nothing is allowed".
+
 #### `flycastHost(app)`
 
 Renders the DNS name a sandbox dials to reach an app over its Flycast address.
@@ -1338,14 +1465,25 @@ It is deliberately a UNION and never a replacement, so an operator's list is
 still exactly what they wrote plus the ports their own declarations require,
 and the applied policy is logged.
 
-Whether the addition is even load-bearing is UNVERIFIED: Fly states "Network
-policies only apply to traffic directly to and from Machines. They do not
-affect traffic routed through the Fly Proxy"
+The addition is load-bearing — VERIFIED 2026-08-16, not inferred. Fly states
+"Network policies only apply to traffic directly to and from Machines. They do
+not affect traffic routed through the Fly Proxy"
 (https://fly.io/docs/machines/guides-examples/network-policies/), and Flycast
-traffic IS routed through Fly Proxy — but Fly says that about ingress and
-never addresses a Machine's egress toward a Flycast address. An inert entry
-costs a port on the allow list; a missing one costs every database in the
-fleet, so the port is added.
+traffic IS routed through Fly Proxy, so it was an open question whether these
+ports did anything. Measured on a throwaway app with a Flycast address into
+its own 6PN: under a policy allowing only `udp:53`, `molecule-pg-tenant.flycast`
+and `molecule-api.flycast` both RESOLVED and every TCP connect to them was
+dropped; re-applying the policy with `tcp:443` opened 443 and nothing else.
+Fly's sentence is about INGRESS — a Machine's egress TOWARD a Flycast address
+is filtered like any other. Drop a declared service's port and every database
+connection in the fleet goes with it.
+
+The cost of each derived port, stated plainly because a Fly policy has no
+destination field of any kind (also measured — see the `egress.ts` module
+description): the port is opened to EVERY host on the internet, not only to
+the private service it was derived for. That residual cannot be closed at this
+layer; it is named in `verifyEgress()`'s verdict and in
+`docs/sandbox-egress-enforcement.md`.
 
 ```typescript
 function mergeEgressPorts(
@@ -1520,6 +1658,14 @@ function requireStore(ctx: TemplateContext): ObjectStore
 
 **Returns:** The configured store.
 
+#### `resetFlyPacerForTests()`
+
+Test-only: reset the shared pacer so timing tests start from a clean slate.
+
+```typescript
+function resetFlyPacerForTests(): void
+```
+
 #### `resolveTemplateStorage(config)`
 
 Resolves template-storage settings from config and the environment.
@@ -1614,6 +1760,30 @@ function toSandboxId(app: string, machineId: string): string
 
 **Returns:** The composite sandbox id.
 
+#### `unexpectedPolicyPorts(applied, intended)`
+
+Finds ports the policy Fly holds allows that this provider never configured.
+
+The raw-connect probe can only speak for the targets it was handed, so a
+policy widened outside this provider — edited by hand to unblock something, or
+left behind by an older build — is invisible to it: the probe's own port stays
+denied and the verdict stays `filtered` while a port nothing here asked for is
+open to the whole internet. Comparing what Fly holds against what this
+provider intended is the one check that can catch that, and it is why the
+verdict reads the policy back rather than trusting the write.
+
+```typescript
+function unexpectedPolicyPorts(
+  applied: FlyNetworkPolicyPort[] | undefined,
+  intended: FlyNetworkPolicyPort[] | undefined,
+): FlyNetworkPolicyPort[]
+```
+
+- `applied` — Ports in the policy Fly actually holds, or `undefined` when the readback found nothing (in which case there is nothing to compare).
+- `intended` — Ports this provider configured, or `undefined` when it applies no policy.
+
+**Returns:** The applied ports with no counterpart in `intended`, in order.
+
 #### `verdictForProbeExit(exitCode, context)`
 
 Maps a probe's exit status onto an {@link EgressVerdict}.
@@ -1903,7 +2073,7 @@ export function setupCodeSandboxFlyio(): void {
 Peer dependencies:
 
 - `@molecule/api-bond` ^1.0.1
-- `@molecule/api-code-sandbox` ^1.0.1
+- `@molecule/api-code-sandbox` ^1.2.0
 - `@molecule/api-i18n` ^1.0.1
 
 ### Environment Variables
@@ -1942,6 +2112,7 @@ Peer dependencies:
 - `@molecule/api-bond`
 - `@molecule/api-code-sandbox`
 - `@molecule/api-i18n`
+- `@molecule/api-proxy-agent`
 
 **Sources.** Every endpoint, payload field and documented behaviour used here
 was checked against Fly's own material, not recalled:
@@ -2169,12 +2340,14 @@ live, and any failure to LIST or read the store throws rather than reporting
 exist for providers whose templates are host-local; object storage is already
 the shared store, so there is nothing to publish or fetch.
 
-**`exportFiles`/`importFiles` are NOT implemented.** The core says a provider
-with no bulk transfer should leave them unimplemented rather than emulate one,
-and Fly's only channel is the `exec` endpoint's JSON response — a file-by-file
-or base64 emulation would look supported and take hours. The template path
-moves bulk data without them precisely because it never routes the bytes
-through the control plane.
+**`importFiles` IS implemented; `exportFiles` is not.** Import takes the same
+route the template restore does — a presigned object-store URL the Machine
+pulls itself, falling back to chunked base64 over `exec` when no store is
+configured — so an app tree can be delivered into a fresh Machine. There is no
+inverse: Fly's only read channel is the `exec` endpoint's JSON response, and a
+base64 emulation of a whole-tree export would look supported and route every
+byte through the control plane. Pair a Fly destination with a source that CAN
+export (the core's rooting contract makes them interchangeable).
 
 **Sandbox ids are composite: `"<app>:<machineId>"`.** A Fly Machine id is only
 unique within its app and every endpoint is `/v1/apps/{app}/machines/{id}`, so

package/dist/api.d.ts

@@ -115,6 +115,11 @@ export interface FlyApiClientOptions {
 }
 /** Test-only: reset the shared pacer so timing tests start from a clean slate. */
 export declare function resetFlyPacerForTests(): void;
+/**
+ * Minimal Fly Machines API client: bearer auth, JSON bodies, per-request
+ * timeout, bounded retries with backoff, and account-wide request pacing via
+ * {@link paceFlyRequest}.
+ */
 export declare class FlyApiClient {
     private readonly token;
     private readonly baseUrl;

package/dist/api.d.ts.map

@@ -1 +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;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;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;AAyCD,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED,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;CAiFnF"}
+{"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;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;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;AAgDD,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;GAIG;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;CAiFnF"}

package/dist/api.js

@@ -145,6 +145,12 @@ function minRequestGapMs() {
  */
 let flyPacerTail = Promise.resolve();
 let flyLastRequestAt = 0;
+/**
+ * Queues the caller behind the shared pacer chain and resolves once its slot
+ * arrives (at least {@link MIN_REQUEST_GAP_MS} after the previous request).
+ * @param sleep - Injected sleep, so tests can collapse the waits.
+ * @returns Resolves when the caller may fire its request.
+ */
 function paceFlyRequest(sleep) {
     const mine = flyPacerTail.then(async () => {
         const wait = Math.max(0, flyLastRequestAt + minRequestGapMs() - Date.now());
@@ -160,6 +166,11 @@ export function resetFlyPacerForTests() {
     flyPacerTail = Promise.resolve();
     flyLastRequestAt = 0;
 }
+/**
+ * Minimal Fly Machines API client: bearer auth, JSON bodies, per-request
+ * timeout, bounded retries with backoff, and account-wide request pacing via
+ * {@link paceFlyRequest}.
+ */
 export class FlyApiClient {
     token;
     baseUrl;

package/dist/egress.d.ts

@@ -46,6 +46,30 @@
  * and that `name` is mandatory — which is why {@link DEFAULT_EGRESS_POLICY_NAME}
  * is always sent.
  *
+ * **THE PORT LIST IS THE WHOLE POLICY — there is no destination, and this was
+ * measured rather than inferred (2026-08-16, live API, throwaway app).** Every
+ * plausible destination field was POSTed and read back: on a RULE,
+ * `ipv6_cidrs` / `ipv4_cidrs` / `cidrs` / `destinations` / `apps` / `app` / `to`
+ * / `dst` are all accepted by the decoder and DROPPED — the stored rule comes
+ * back as `{action, direction, ports}` and nothing else. On the SELECTOR (which
+ * chooses which Machines a policy covers, i.e. the SOURCE, never a destination)
+ * only `all`, `machines` and `metadata` persist; `apps` is the one field the API
+ * answers about, with `400 {"error":"apps array not currently supported in
+ * selectors"}`. So an `allow tcp/5432` rule permits that Machine to reach port
+ * 5432 on EVERY host on the internet, and no arrangement of this object can say
+ * otherwise. {@link describePublicReach} states that in the verdict rather than
+ * leaving an operator to deduce it.
+ *
+ * **The derived private-service ports ARE load-bearing** (the open question this
+ * module and FLY-OPERATOR-SETUP §9 both carried since 2026-08-05). Measured the
+ * same day: with a policy allowing only `udp:53`, a Machine on a custom 6PN
+ * could resolve `molecule-pg-tenant.flycast` and `molecule-api.flycast` but
+ * every TCP connect to them was dropped, and re-applying `tcp:443` re-opened
+ * only 443. Fly's "policies do not affect traffic routed through the Fly Proxy"
+ * is about INGRESS; a Machine's egress TOWARD a Flycast address is filtered like
+ * any other. Dropping a declared service's port would therefore take out every
+ * database connection in the fleet.
+ *
  * @module
  */
 import type { EgressVerdict } from '@molecule/api-code-sandbox';
@@ -83,10 +107,24 @@ export interface EgressProbeContext {
     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.
+     * applies no policy at all. Used for the message, the remediation, and as the
+     * INTENT half of the drift check against {@link appliedPolicyPorts} — never to
+     * decide `open` vs `filtered` from a probe that reached a target, which comes
+     * from the observation alone.
      */
     policyPorts?: FlyNetworkPolicyPort[];
+    /**
+     * Ports the policy Fly ACTUALLY holds for this app allows, read back from the
+     * API after the probe ran, or `undefined` when the readback failed or found no
+     * policy of this provider's name.
+     *
+     * This is the observation half of the only drift this module can catch: a
+     * policy widened outside the provider (by hand, by another tool, by an older
+     * build) allows ports nothing here configured, and the raw-connect probe
+     * cannot see it because it only attempts the targets it was given. See
+     * {@link unexpectedPolicyPorts}.
+     */
+    appliedPolicyPorts?: FlyNetworkPolicyPort[];
 }
 /**
  * Renders a target the way it is written in configuration, so an operator can
@@ -139,6 +177,41 @@ export declare function parseEgressAllowedPorts(raw: string | undefined): FlyNet
  * @returns A `sh`-safe command string.
  */
 export declare function buildEgressProbeCommand(targets: EgressProbeTarget[], timeoutMs: number): string;
+/**
+ * States, in the verdict itself, what an allowed port actually permits.
+ *
+ * A Fly network policy has no destination (see the module description — measured
+ * against the live API, not inferred), so every allowed port is open to every
+ * host on the internet, not only to the private service it was derived for. That
+ * is the single most consequential thing about this mechanism and it was invisible
+ * everywhere it mattered: the probe attempts one port the policy denies, reports
+ * `filtered`, and an operator reasonably reads that as "nothing gets out".
+ *
+ * Naming it here means the residual is restated on every re-probe (the consumer
+ * re-verifies every 15 minutes) instead of living only in a document.
+ * @param policyPorts - Allowed ports, or `undefined` when no policy is applied.
+ * @returns A sentence naming the public reach, or `''` when there is nothing to
+ *   say (no policy, or nothing but UDP/53 — DNS is a documented residual of its
+ *   own and not a TCP channel).
+ */
+export declare function describePublicReach(policyPorts: FlyNetworkPolicyPort[] | undefined): string;
+/**
+ * Finds ports the policy Fly holds allows that this provider never configured.
+ *
+ * The raw-connect probe can only speak for the targets it was handed, so a
+ * policy widened outside this provider — edited by hand to unblock something, or
+ * left behind by an older build — is invisible to it: the probe's own port stays
+ * denied and the verdict stays `filtered` while a port nothing here asked for is
+ * open to the whole internet. Comparing what Fly holds against what this
+ * provider intended is the one check that can catch that, and it is why the
+ * verdict reads the policy back rather than trusting the write.
+ * @param applied - Ports in the policy Fly actually holds, or `undefined` when
+ *   the readback found nothing (in which case there is nothing to compare).
+ * @param intended - Ports this provider configured, or `undefined` when it
+ *   applies no policy.
+ * @returns The applied ports with no counterpart in `intended`, in order.
+ */
+export declare function unexpectedPolicyPorts(applied: FlyNetworkPolicyPort[] | undefined, intended: FlyNetworkPolicyPort[] | undefined): FlyNetworkPolicyPort[];
 /**
  * Maps a probe's exit status onto an {@link EgressVerdict}.
  *
@@ -177,4 +250,26 @@ export declare function verdictForProbeExit(exitCode: number, context: EgressPro
  * @returns The matching policy's id, or `undefined`.
  */
 export declare function extractPolicyId(response: unknown, name: string): string | undefined;
+/**
+ * Reads back the egress ports the policy Fly ACTUALLY holds allows.
+ *
+ * The write is not the observation: this provider POSTs a policy, but what
+ * governs a Machine is whatever Fly has when that Machine boots — which may
+ * differ because a person, another tool or an older build changed it. Reading it
+ * back is what lets {@link unexpectedPolicyPorts} catch a policy wider than the
+ * one this provider configured, so `verifyEgress()` can fail on drift its raw
+ * connects were never going to attempt.
+ *
+ * Parsed as defensively as {@link extractPolicyId}, and for the same reason:
+ * neither Fly document specifies the LIST response shape. The live API answers
+ * with a bare array whose selector key is `netpolSelector` rather than the
+ * `selector` it accepts (verified 2026-08-16), which is exactly why nothing here
+ * depends on any key but `name` and `rules`.
+ * @param response - The raw parsed LIST response.
+ * @param name - The policy name to match.
+ * @returns The allowed egress ports, or `undefined` when no policy of that name
+ *   is present or the shape is unrecognized. `undefined` means "nothing to
+ *   compare", never "nothing is allowed".
+ */
+export declare function extractPolicyPorts(response: unknown, name: string): FlyNetworkPolicyPort[] | undefined;
 //# sourceMappingURL=egress.d.ts.map

package/dist/egress.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../src/egress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;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;AAcnE;;;;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;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAA;IACpC;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,EAAE,CAAA;CAC5C;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;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,SAAS,GAAG,MAAM,CAW3F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,EAAE,GAAG,SAAS,EAC3C,QAAQ,EAAE,oBAAoB,EAAE,GAAG,SAAS,GAC3C,oBAAoB,EAAE,CAMxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAgEhG;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,MAAM,GACX,oBAAoB,EAAE,GAAG,SAAS,CAiBpC"}