@molecule/api-code-sandbox-flyio 1.0.1

package/dist/flycast.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Flycast private routes — the one mechanism Fly documents for reaching an app
+ * ACROSS custom 6PN private networks, and the pure logic behind wiring it per
+ * project.
+ *
+ * **The problem this solves.** This provider puts every project's sandbox app on
+ * its own custom 6PN, which is what makes tenants unable to reach each other:
+ * "Apps on separate 6PNs can never communicate unless explicitly configured to
+ * do so" (https://fly.io/docs/networking/custom-private-networks/). The same
+ * sentence severs two paths the product REQUIRES — a sandbox reaching its own
+ * `mol_<uuid>` database on the tenant Postgres cluster, and a sandbox reaching
+ * the control plane's egress proxy. Neither is optional: a scaffolded app
+ * connects to `DATABASE_URL` at startup, and the proxy is where the per-project
+ * host allowlist is enforced.
+ *
+ * **The mechanism.** Fly names exactly three ways to cross a 6PN boundary
+ * (https://fly.io/docs/networking/custom-private-networks/): a public service
+ * IP, `fly-replay`, and a Flycast private address allocated INTO the calling
+ * network. Only the third one grants a single directed edge without exposing
+ * anything publicly, so it is what this module implements:
+ *
+ * > "You can use Flycast to expose an app on one private network to another
+ * > private network in your organization; the app won't be accessible via
+ * > Flycast from its own network. Use the `--network` option to specify the
+ * > network from which requests will originate:
+ * > `fly ips allocate-v6 --private --network custom-network-name`"
+ * > — https://fly.io/docs/networking/flycast/
+ *
+ * The REST equivalent is `POST /v1/apps/{app}/ip_assignments`, whose
+ * `assignIPRequest` schema carries `network`, `org_slug`, `region`,
+ * `service_name` and `type` — read directly from
+ * https://docs.machines.dev/openapi.json rather than inferred. `type` is a bare
+ * `string` there with no enum and no description, so `private_v6` — the value
+ * flyctl passes for `allocate-v6 --private`
+ * (https://github.com/superfly/flyctl `internal/command/ips/allocate.go`) — is
+ * this provider's default and is configurable via
+ * {@link FlyioConfig.privateIpAssignmentType}. Treat the literal as UNVERIFIED
+ * against an official Fly *doc page*; the flyctl source is a secondary source.
+ *
+ * **Three consequences that shape the code, none of which can be designed
+ * around:**
+ *
+ * 1. **The allocation lives on the TARGET app, keyed by the CALLER's network.**
+ *    So the tenant Postgres app accumulates one private address per project
+ *    network, and destroying a project must release its own. Fly documents no
+ *    limit on how many private addresses one app may hold, in either direction —
+ *    see the module `@remarks` in `index.ts`.
+ * 2. **`GET /apps/{app}/ip_assignments` does not report which network an address
+ *    belongs to** (`IPAssignment` is `{created_at, ip, region, service_name,
+ *    shared}`). A listing therefore cannot tell you whether THIS project's route
+ *    already exists, so the addresses are recorded in the sandbox Machine's own
+ *    metadata and read back from there.
+ * 3. **The target app needs a services block.** "Services configured in your
+ *    app's `fly.toml` with an `[http_service]` or `[services]` section"
+ *    (https://fly.io/docs/networking/flycast/). That is an operator action on
+ *    the target app, not something this provider can perform.
+ *
+ * @module
+ */
+import type { FlyNetworkPolicyPort, FlyPrivateService } from './types.js';
+/**
+ * DNS suffix Fly serves a Flycast address at: "If an app has a Flycast address
+ * allocated to it, there will be an AAAA record at `my-app-name.flycast`"
+ * (https://fly.io/docs/networking/flycast/).
+ */
+export declare const FLYCAST_SUFFIX = ".flycast";
+/**
+ * Machine-metadata key suffix (after the configured prefix) recording the
+ * private addresses allocated for a project, so `destroy()` can release exactly
+ * the ones it created. See consequence 2 in the module description: a listing on
+ * the target app cannot tell you which network an address serves.
+ */
+export declare const PRIVATE_ROUTES_METADATA_SUFFIX = "privateRoutes";
+/**
+ * `type` sent to `POST /apps/{app}/ip_assignments` for a Flycast address. This
+ * is the value flyctl passes for `fly ips allocate-v6 --private`; the field has
+ * no enum in Fly's OpenAPI specification, so it is configurable rather than
+ * hardcoded.
+ */
+export declare const DEFAULT_PRIVATE_IP_TYPE = "private_v6";
+/**
+ * Renders the DNS name a sandbox dials to reach an app over its Flycast address.
+ * @param app - The target Fly app name.
+ * @returns `<app>.flycast`.
+ */
+export declare function flycastHost(app: string): string;
+/**
+ * Parses the declared cross-network services.
+ *
+ * Each entry is `<app>:<port>` — the Fly app to allocate a Flycast address on,
+ * and the TCP port a sandbox dials it at. The port is not cosmetic: it is what
+ * {@link mergeEgressPorts} adds to the Fly network policy, and what
+ * {@link assertPrivateRoutesForEnv} checks the injected connection URLs against.
+ * @param raw - Comma-separated `app:port` pairs, e.g.
+ *   `molecule-pg-tenant:5432,molecule-api:3129`.
+ * @returns The declared services, deduplicated, in order — or `undefined` when
+ *   the input is absent or empty, meaning "allocate nothing", which is correct
+ *   for a control plane that shares one 6PN with its sandboxes.
+ * @throws {Error} When an entry is present but unparseable. Dropping one
+ *   silently would leave a sandbox with a `DATABASE_URL` that nothing routes.
+ */
+export declare function parsePrivateServices(raw: string | undefined): FlyPrivateService[] | undefined;
+/**
+ * Adds every declared private-service port to the egress network policy.
+ *
+ * A Fly network policy is deny-by-default once any rule exists for a direction,
+ * so a sandbox told to dial `molecule-pg-tenant.flycast:5432` under a policy
+ * allowing only `tcp:3128` would fail to connect with no diagnostic beyond a
+ * timeout. Deriving the port from the declaration — rather than asking the
+ * operator to keep two lists in step — is what makes that class of outage
+ * impossible: FLY-OPERATOR-SETUP.md § 9 can keep saying "never widen this list",
+ * because the operator never has to.
+ *
+ * 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"
+ * (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.
+ * @param ports - The operator's configured ports, or `undefined` when no policy
+ *   is being applied at all.
+ * @param services - The declared private services, or `undefined`.
+ * @returns The union, deduplicated — or `undefined` when `ports` is `undefined`.
+ *   "No policy" is never turned INTO a policy here: applying one that Fly then
+ *   uses to drop everything else is not something to infer from an unrelated
+ *   setting.
+ */
+export declare function mergeEgressPorts(ports: FlyNetworkPolicyPort[] | undefined, services: FlyPrivateService[] | undefined): FlyNetworkPolicyPort[] | undefined;
+/**
+ * Encodes allocated addresses for storage in Machine metadata.
+ * @param routes - Target app name → allocated private address.
+ * @returns `app=address` pairs joined by commas. An IPv6 literal contains
+ *   neither `,` nor `=`, so the encoding is unambiguous.
+ */
+export declare function encodePrivateRoutes(routes: Record<string, string>): string;
+/**
+ * Decodes the addresses recorded by {@link encodePrivateRoutes}.
+ * @param raw - The metadata value, or `undefined` when the Machine carries none.
+ * @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.
+ */
+export declare function decodePrivateRoutes(raw: string | undefined): Record<string, string>;
+/**
+ * Refuses to boot a sandbox that is told to dial a Flycast host this provider
+ * did not allocate a route for.
+ *
+ * This is the check that turns the product-breaking failure into a startup
+ * error. The control plane bakes `DATABASE_URL` (and the proxy environment) into
+ * every sandbox; on Fly those must name `<app>.flycast`, and that name resolves
+ * ONLY because this provider allocated a private address into the project's
+ * network for that app. Get the two out of step — a `SANDBOX_DB_HOST` pointing
+ * at an app nobody declared, a port that does not match the one the policy
+ * allows — and the sandbox boots healthy, the scaffolded app cannot connect, and
+ * the only symptom is a connection timeout inside someone else's project.
+ *
+ * It is also the guard on the control-plane cluster: reaching
+ * `molecule-pg-control.flycast` from a sandbox would require an operator to have
+ * declared it as a private service, which is an explicit act with its own name
+ * in the configuration — never something this provider arranges on its own.
+ * @param env - The environment the caller is baking into the sandbox.
+ * @param services - The declared private services, or `undefined`.
+ * @throws {Error} When an environment value names a `.flycast` host with no
+ *   matching declaration, naming the variable and the fix.
+ */
+export declare function assertPrivateRoutesForEnv(env: Record<string, string> | undefined, services: FlyPrivateService[] | undefined): void;
+//# sourceMappingURL=flycast.d.ts.map

package/dist/flycast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flycast.d.ts","sourceRoot":"","sources":["../src/flycast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEzE;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,kBAAkB,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,eAAe,CAAA;AAKnD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,EAAE,GAAG,SAAS,CAqC7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,oBAAoB,EAAE,GAAG,SAAS,EACzC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,SAAS,GACxC,oBAAoB,EAAE,GAAG,SAAS,CAUpC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI1E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnF;AA2BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACvC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,SAAS,GACxC,IAAI,CAwCN"}

package/dist/flycast.js

@@ -0,0 +1,287 @@
+/**
+ * Flycast private routes — the one mechanism Fly documents for reaching an app
+ * ACROSS custom 6PN private networks, and the pure logic behind wiring it per
+ * project.
+ *
+ * **The problem this solves.** This provider puts every project's sandbox app on
+ * its own custom 6PN, which is what makes tenants unable to reach each other:
+ * "Apps on separate 6PNs can never communicate unless explicitly configured to
+ * do so" (https://fly.io/docs/networking/custom-private-networks/). The same
+ * sentence severs two paths the product REQUIRES — a sandbox reaching its own
+ * `mol_<uuid>` database on the tenant Postgres cluster, and a sandbox reaching
+ * the control plane's egress proxy. Neither is optional: a scaffolded app
+ * connects to `DATABASE_URL` at startup, and the proxy is where the per-project
+ * host allowlist is enforced.
+ *
+ * **The mechanism.** Fly names exactly three ways to cross a 6PN boundary
+ * (https://fly.io/docs/networking/custom-private-networks/): a public service
+ * IP, `fly-replay`, and a Flycast private address allocated INTO the calling
+ * network. Only the third one grants a single directed edge without exposing
+ * anything publicly, so it is what this module implements:
+ *
+ * > "You can use Flycast to expose an app on one private network to another
+ * > private network in your organization; the app won't be accessible via
+ * > Flycast from its own network. Use the `--network` option to specify the
+ * > network from which requests will originate:
+ * > `fly ips allocate-v6 --private --network custom-network-name`"
+ * > — https://fly.io/docs/networking/flycast/
+ *
+ * The REST equivalent is `POST /v1/apps/{app}/ip_assignments`, whose
+ * `assignIPRequest` schema carries `network`, `org_slug`, `region`,
+ * `service_name` and `type` — read directly from
+ * https://docs.machines.dev/openapi.json rather than inferred. `type` is a bare
+ * `string` there with no enum and no description, so `private_v6` — the value
+ * flyctl passes for `allocate-v6 --private`
+ * (https://github.com/superfly/flyctl `internal/command/ips/allocate.go`) — is
+ * this provider's default and is configurable via
+ * {@link FlyioConfig.privateIpAssignmentType}. Treat the literal as UNVERIFIED
+ * against an official Fly *doc page*; the flyctl source is a secondary source.
+ *
+ * **Three consequences that shape the code, none of which can be designed
+ * around:**
+ *
+ * 1. **The allocation lives on the TARGET app, keyed by the CALLER's network.**
+ *    So the tenant Postgres app accumulates one private address per project
+ *    network, and destroying a project must release its own. Fly documents no
+ *    limit on how many private addresses one app may hold, in either direction —
+ *    see the module `@remarks` in `index.ts`.
+ * 2. **`GET /apps/{app}/ip_assignments` does not report which network an address
+ *    belongs to** (`IPAssignment` is `{created_at, ip, region, service_name,
+ *    shared}`). A listing therefore cannot tell you whether THIS project's route
+ *    already exists, so the addresses are recorded in the sandbox Machine's own
+ *    metadata and read back from there.
+ * 3. **The target app needs a services block.** "Services configured in your
+ *    app's `fly.toml` with an `[http_service]` or `[services]` section"
+ *    (https://fly.io/docs/networking/flycast/). That is an operator action on
+ *    the target app, not something this provider can perform.
+ *
+ * @module
+ */
+import { t } from '@molecule/api-i18n';
+/**
+ * DNS suffix Fly serves a Flycast address at: "If an app has a Flycast address
+ * allocated to it, there will be an AAAA record at `my-app-name.flycast`"
+ * (https://fly.io/docs/networking/flycast/).
+ */
+export const FLYCAST_SUFFIX = '.flycast';
+/**
+ * Machine-metadata key suffix (after the configured prefix) recording the
+ * private addresses allocated for a project, so `destroy()` can release exactly
+ * the ones it created. See consequence 2 in the module description: a listing on
+ * the target app cannot tell you which network an address serves.
+ */
+export const PRIVATE_ROUTES_METADATA_SUFFIX = 'privateRoutes';
+/**
+ * `type` sent to `POST /apps/{app}/ip_assignments` for a Flycast address. This
+ * is the value flyctl passes for `fly ips allocate-v6 --private`; the field has
+ * no enum in Fly's OpenAPI specification, so it is configurable rather than
+ * hardcoded.
+ */
+export const DEFAULT_PRIVATE_IP_TYPE = 'private_v6';
+/** Fly app names are DNS labels: lowercase alphanumerics and hyphens. */
+const APP_NAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Renders the DNS name a sandbox dials to reach an app over its Flycast address.
+ * @param app - The target Fly app name.
+ * @returns `<app>.flycast`.
+ */
+export function flycastHost(app) {
+    return `${app}${FLYCAST_SUFFIX}`;
+}
+/**
+ * Parses the declared cross-network services.
+ *
+ * Each entry is `<app>:<port>` — the Fly app to allocate a Flycast address on,
+ * and the TCP port a sandbox dials it at. The port is not cosmetic: it is what
+ * {@link mergeEgressPorts} adds to the Fly network policy, and what
+ * {@link assertPrivateRoutesForEnv} checks the injected connection URLs against.
+ * @param raw - Comma-separated `app:port` pairs, e.g.
+ *   `molecule-pg-tenant:5432,molecule-api:3129`.
+ * @returns The declared services, deduplicated, in order — or `undefined` when
+ *   the input is absent or empty, meaning "allocate nothing", which is correct
+ *   for a control plane that shares one 6PN with its sandboxes.
+ * @throws {Error} When an entry is present but unparseable. Dropping one
+ *   silently would leave a sandbox with a `DATABASE_URL` that nothing routes.
+ */
+export function parsePrivateServices(raw) {
+    const entries = (raw ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    if (entries.length === 0)
+        return undefined;
+    const services = [];
+    for (const entry of entries) {
+        const index = entry.lastIndexOf(':');
+        const app = index > 0 ? entry.slice(0, index) : '';
+        const port = Number(entry.slice(index + 1));
+        if (!APP_NAME.test(app) ||
+            app.length > 63 ||
+            !Number.isInteger(port) ||
+            port < 1 ||
+            port > 65535) {
+            throw new Error(t('codeSandbox.flyio.error.badPrivateService', { entry }, {
+                defaultValue: `Invalid Fly private service "${entry}" — expected "<fly-app>:<port>", e.g. ` +
+                    '"molecule-pg-tenant:5432". The app is the Fly app a Flycast address is allocated ' +
+                    'on; the port is the one a sandbox dials it at.',
+            }));
+        }
+        if (!services.some((service) => service.app === app && service.port === port)) {
+            services.push({ app, port });
+        }
+    }
+    return services;
+}
+/**
+ * Adds every declared private-service port to the egress network policy.
+ *
+ * A Fly network policy is deny-by-default once any rule exists for a direction,
+ * so a sandbox told to dial `molecule-pg-tenant.flycast:5432` under a policy
+ * allowing only `tcp:3128` would fail to connect with no diagnostic beyond a
+ * timeout. Deriving the port from the declaration — rather than asking the
+ * operator to keep two lists in step — is what makes that class of outage
+ * impossible: FLY-OPERATOR-SETUP.md § 9 can keep saying "never widen this list",
+ * because the operator never has to.
+ *
+ * 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"
+ * (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.
+ * @param ports - The operator's configured ports, or `undefined` when no policy
+ *   is being applied at all.
+ * @param services - The declared private services, or `undefined`.
+ * @returns The union, deduplicated — or `undefined` when `ports` is `undefined`.
+ *   "No policy" is never turned INTO a policy here: applying one that Fly then
+ *   uses to drop everything else is not something to infer from an unrelated
+ *   setting.
+ */
+export function mergeEgressPorts(ports, services) {
+    if (!ports)
+        return undefined;
+    if (!services?.length)
+        return ports;
+    const merged = [...ports];
+    for (const service of services) {
+        if (!merged.some((port) => port.protocol === 'tcp' && port.port === service.port)) {
+            merged.push({ protocol: 'tcp', port: service.port });
+        }
+    }
+    return merged;
+}
+/**
+ * Encodes allocated addresses for storage in Machine metadata.
+ * @param routes - Target app name → allocated private address.
+ * @returns `app=address` pairs joined by commas. An IPv6 literal contains
+ *   neither `,` nor `=`, so the encoding is unambiguous.
+ */
+export function encodePrivateRoutes(routes) {
+    return Object.entries(routes)
+        .map(([app, ip]) => `${app}=${ip}`)
+        .join(',');
+}
+/**
+ * Decodes the addresses recorded by {@link encodePrivateRoutes}.
+ * @param raw - The metadata value, or `undefined` when the Machine carries none.
+ * @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.
+ */
+export function decodePrivateRoutes(raw) {
+    const routes = {};
+    for (const entry of (raw ?? '').split(',')) {
+        const index = entry.indexOf('=');
+        if (index <= 0)
+            continue;
+        const app = entry.slice(0, index).trim();
+        const ip = entry.slice(index + 1).trim();
+        if (app && ip)
+            routes[app] = ip;
+    }
+    return routes;
+}
+/**
+ * Extracts the `<app>` and port from a URL that names a Flycast host.
+ * @param value - A candidate environment-variable value.
+ * @returns The target app and the port the URL dials it at (`undefined` when the
+ *   URL carries no explicit port), or `null` when the value is not a URL naming
+ *   a `.flycast` host.
+ */
+function flycastTarget(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (_error) {
+        // Intentionally ignored: "not a URL" is the normal case for an environment
+        // value, and a non-URL cannot be the connection string this check is
+        // responsible for. There is nothing to report.
+        return null;
+    }
+    const host = url.hostname.toLowerCase();
+    if (!host.endsWith(FLYCAST_SUFFIX))
+        return null;
+    const app = host.slice(0, -FLYCAST_SUFFIX.length);
+    if (!app)
+        return null;
+    const port = url.port ? Number(url.port) : undefined;
+    return Number.isInteger(port) ? { app, port } : { app };
+}
+/**
+ * Refuses to boot a sandbox that is told to dial a Flycast host this provider
+ * did not allocate a route for.
+ *
+ * This is the check that turns the product-breaking failure into a startup
+ * error. The control plane bakes `DATABASE_URL` (and the proxy environment) into
+ * every sandbox; on Fly those must name `<app>.flycast`, and that name resolves
+ * ONLY because this provider allocated a private address into the project's
+ * network for that app. Get the two out of step — a `SANDBOX_DB_HOST` pointing
+ * at an app nobody declared, a port that does not match the one the policy
+ * allows — and the sandbox boots healthy, the scaffolded app cannot connect, and
+ * the only symptom is a connection timeout inside someone else's project.
+ *
+ * It is also the guard on the control-plane cluster: reaching
+ * `molecule-pg-control.flycast` from a sandbox would require an operator to have
+ * declared it as a private service, which is an explicit act with its own name
+ * in the configuration — never something this provider arranges on its own.
+ * @param env - The environment the caller is baking into the sandbox.
+ * @param services - The declared private services, or `undefined`.
+ * @throws {Error} When an environment value names a `.flycast` host with no
+ *   matching declaration, naming the variable and the fix.
+ */
+export function assertPrivateRoutesForEnv(env, services) {
+    if (!env)
+        return;
+    const declared = services ?? [];
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value !== 'string' || !value.toLowerCase().includes(FLYCAST_SUFFIX))
+            continue;
+        const target = flycastTarget(value);
+        if (!target)
+            continue;
+        const forApp = declared.filter((service) => service.app === target.app);
+        if (forApp.length === 0) {
+            throw new Error(t('codeSandbox.flyio.error.undeclaredPrivateRoute', { key, app: target.app }, {
+                defaultValue: `${key} points at "${flycastHost(target.app)}", but "${target.app}" is not a ` +
+                    'declared Fly private service, so no Flycast address is allocated into this ' +
+                    "project's 6PN and the name will not resolve inside the sandbox. Add " +
+                    `"${target.app}:<port>" to FLY_SANDBOX_PRIVATE_SERVICES (or config.privateServices).`,
+            }));
+        }
+        if (target.port !== undefined && !forApp.some((service) => service.port === target.port)) {
+            throw new Error(t('codeSandbox.flyio.error.privateRoutePortMismatch', { key, app: target.app, port: String(target.port) }, {
+                defaultValue: `${key} dials "${flycastHost(target.app)}" on port ${target.port}, but the declared ` +
+                    `Fly private service for "${target.app}" is on port ` +
+                    `${forApp.map((service) => service.port).join(', ')}. The sandbox egress policy ` +
+                    'allows the declared port, so the connection would be dropped. Make the two match.',
+            }));
+        }
+    }
+}

package/dist/ids.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Sandbox identifiers, Fly app naming, and Machine-state mapping.
+ *
+ * A Fly Machine id is only unique WITHIN its app, and every Machines API call is
+ * `/v1/apps/{app_name}/machines/{machine_id}` — so a bare Machine id is not
+ * enough to address a Machine. The core interface hands `get(id)` and
+ * `destroy(id)` a single opaque string, so this provider's sandbox id is the
+ * composite `"<app>:<machineId>"`. Fly app names cannot contain `:` and Machine
+ * ids are hex, so the split is unambiguous. Callers must keep treating the id as
+ * opaque; nothing outside this module should parse it.
+ *
+ * @module
+ */
+import type { FlyMachineState } from './types.js';
+/**
+ * Builds the opaque sandbox id addressing one Machine inside one app.
+ * @param app - Fly app name.
+ * @param machineId - Fly Machine id.
+ * @returns The composite sandbox id.
+ */
+export declare function toSandboxId(app: string, machineId: string): string;
+/**
+ * Splits a composite sandbox id back into its app and Machine id.
+ * @param id - A sandbox id previously produced by {@link toSandboxId}.
+ * @returns The app name and Machine id.
+ * @throws {Error} When the id is not in `<app>:<machineId>` form — a bare Machine id
+ *   cannot be addressed, and guessing an app would delete or inspect the wrong
+ *   tenant's Machine.
+ */
+export declare function parseSandboxId(id: string): {
+    app: string;
+    machineId: string;
+};
+/**
+ * Derives a Fly app name for a project.
+ *
+ * Fly app names are globally unique DNS labels: lowercase alphanumerics and
+ * hyphens, no leading/trailing hyphen, at most 63 characters (they become
+ * `<app>.fly.dev`). Project ids are uuids, so `<prefix>-<uuid>` fits with room
+ * to spare; longer ids are truncated rather than rejected, and the trailing
+ * hyphen that truncation can leave is stripped.
+ * @param prefix - Configured app-name prefix.
+ * @param projectId - The project id from `SandboxConfig`.
+ * @returns A syntactically valid Fly app name.
+ * @throws {Error} When `projectId` has no characters usable in a DNS label.
+ */
+export declare function appNameForProject(prefix: string, projectId: string): string;
+/**
+ * Maps a Fly Machine state onto the core `Sandbox['status']` union.
+ *
+ * The core has four statuses and Fly documents seventeen states
+ * (https://fly.io/docs/machines/machine-states/), so the mapping is lossy by
+ * construction:
+ *
+ * - `started` → `running`.
+ * - `suspended`/`suspending` → `sleeping`. This is the mapping this bond exists
+ *   for: `sleep()` suspends and `wake()` resumes from the memory snapshot.
+ * - In-flight transitions (`creating`, `starting`, `restarting`, `updating`,
+ *   `replacing`, `migrated`) → `creating`, i.e. "not usable yet, will be".
+ * - Everything else — including `failed` and `launch_failed` — → `stopped`.
+ *   The core union has no error status, so a failed Machine is reported as
+ *   stopped; `failed` is distinguishable only via {@link isFailedState}.
+ *
+ * An unrecognized future state falls through to `stopped`, which is the safe
+ * default: a caller retries a start rather than assuming a usable sandbox.
+ * @param state - Raw Fly Machine state string.
+ * @returns The core sandbox status.
+ */
+export declare function mapMachineState(state: FlyMachineState): 'creating' | 'running' | 'sleeping' | 'stopped';
+/**
+ * Reports whether a Fly Machine state means the Machine errored, rather than
+ * having been stopped on purpose. {@link mapMachineState} flattens both to
+ * `stopped` because the core union has no failure status, so this is the only
+ * way to tell them apart.
+ * @param state - Raw Fly Machine state string.
+ * @returns `true` for `failed` and `launch_failed`.
+ */
+export declare function isFailedState(state: FlyMachineState): boolean;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAKjD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAgB7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAqB3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,GACrB,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAiBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAE7D"}

package/dist/ids.js

@@ -0,0 +1,121 @@
+/**
+ * Sandbox identifiers, Fly app naming, and Machine-state mapping.
+ *
+ * A Fly Machine id is only unique WITHIN its app, and every Machines API call is
+ * `/v1/apps/{app_name}/machines/{machine_id}` — so a bare Machine id is not
+ * enough to address a Machine. The core interface hands `get(id)` and
+ * `destroy(id)` a single opaque string, so this provider's sandbox id is the
+ * composite `"<app>:<machineId>"`. Fly app names cannot contain `:` and Machine
+ * ids are hex, so the split is unambiguous. Callers must keep treating the id as
+ * opaque; nothing outside this module should parse it.
+ *
+ * @module
+ */
+import { t } from '@molecule/api-i18n';
+/** Separator between the app name and the Machine id in a composite sandbox id. */
+const ID_SEPARATOR = ':';
+/**
+ * Builds the opaque sandbox id addressing one Machine inside one app.
+ * @param app - Fly app name.
+ * @param machineId - Fly Machine id.
+ * @returns The composite sandbox id.
+ */
+export function toSandboxId(app, machineId) {
+    return `${app}${ID_SEPARATOR}${machineId}`;
+}
+/**
+ * Splits a composite sandbox id back into its app and Machine id.
+ * @param id - A sandbox id previously produced by {@link toSandboxId}.
+ * @returns The app name and Machine id.
+ * @throws {Error} When the id is not in `<app>:<machineId>` form — a bare Machine id
+ *   cannot be addressed, and guessing an app would delete or inspect the wrong
+ *   tenant's Machine.
+ */
+export function parseSandboxId(id) {
+    const index = id.indexOf(ID_SEPARATOR);
+    if (index <= 0 || index === id.length - 1) {
+        throw new Error(t('codeSandbox.flyio.error.badSandboxId', { id }, {
+            defaultValue: `Invalid Fly sandbox id "${id}" — expected "<app>:<machineId>". ` +
+                'Fly Machine ids are only unique within an app, so a bare Machine id cannot be addressed.',
+        }));
+    }
+    return { app: id.slice(0, index), machineId: id.slice(index + 1) };
+}
+/**
+ * Derives a Fly app name for a project.
+ *
+ * Fly app names are globally unique DNS labels: lowercase alphanumerics and
+ * hyphens, no leading/trailing hyphen, at most 63 characters (they become
+ * `<app>.fly.dev`). Project ids are uuids, so `<prefix>-<uuid>` fits with room
+ * to spare; longer ids are truncated rather than rejected, and the trailing
+ * hyphen that truncation can leave is stripped.
+ * @param prefix - Configured app-name prefix.
+ * @param projectId - The project id from `SandboxConfig`.
+ * @returns A syntactically valid Fly app name.
+ * @throws {Error} When `projectId` has no characters usable in a DNS label.
+ */
+export function appNameForProject(prefix, projectId) {
+    const sanitize = (value) => value
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    const safePrefix = sanitize(prefix) || 'mol-sandbox';
+    const safeProject = sanitize(projectId);
+    if (!safeProject) {
+        throw new Error(t('codeSandbox.flyio.error.badProjectId', { projectId }, {
+            defaultValue: `Cannot derive a Fly app name from projectId "${projectId}" — no DNS-safe characters.`,
+        }));
+    }
+    return `${safePrefix}-${safeProject}`.slice(0, 63).replace(/-+$/, '');
+}
+/**
+ * Maps a Fly Machine state onto the core `Sandbox['status']` union.
+ *
+ * The core has four statuses and Fly documents seventeen states
+ * (https://fly.io/docs/machines/machine-states/), so the mapping is lossy by
+ * construction:
+ *
+ * - `started` → `running`.
+ * - `suspended`/`suspending` → `sleeping`. This is the mapping this bond exists
+ *   for: `sleep()` suspends and `wake()` resumes from the memory snapshot.
+ * - In-flight transitions (`creating`, `starting`, `restarting`, `updating`,
+ *   `replacing`, `migrated`) → `creating`, i.e. "not usable yet, will be".
+ * - Everything else — including `failed` and `launch_failed` — → `stopped`.
+ *   The core union has no error status, so a failed Machine is reported as
+ *   stopped; `failed` is distinguishable only via {@link isFailedState}.
+ *
+ * An unrecognized future state falls through to `stopped`, which is the safe
+ * default: a caller retries a start rather than assuming a usable sandbox.
+ * @param state - Raw Fly Machine state string.
+ * @returns The core sandbox status.
+ */
+export function mapMachineState(state) {
+    switch (state) {
+        case 'started':
+            return 'running';
+        case 'suspended':
+        case 'suspending':
+            return 'sleeping';
+        case 'creating':
+        case 'starting':
+        case 'restarting':
+        case 'updating':
+        case 'replacing':
+        case 'migrated':
+            return 'creating';
+        default:
+            return 'stopped';
+    }
+}
+/**
+ * Reports whether a Fly Machine state means the Machine errored, rather than
+ * having been stopped on purpose. {@link mapMachineState} flattens both to
+ * `stopped` because the core union has no failure status, so this is the only
+ * way to tell them apart.
+ * @param state - Raw Fly Machine state string.
+ * @returns `true` for `failed` and `launch_failed`.
+ */
+export function isFailedState(state) {
+    return state === 'failed' || state === 'launch_failed';
+}