@molecule/api-code-sandbox-flyio 1.0.1

package/dist/storage.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The S3-compatible object store that holds Fly sandbox templates.
+ *
+ * Fly has no `docker commit`: it PULLS images from a registry and cannot produce
+ * one from a running Machine, and the Machines API has no file-transfer endpoint
+ * at all (its whole surface is enumerated in
+ * https://docs.machines.dev/openapi.json — `exec` is the only way in or out). So a
+ * template here is a tar archive in object storage, and the bytes move between the
+ * sandbox and that store DIRECTLY over presigned URLs; this module is only the
+ * control plane's half — presigning, metadata, enumeration and deletion.
+ *
+ * **Storage is bond configuration, never interface surface.** Nothing about
+ * buckets or endpoints appears in `@molecule/api-code-sandbox`. This mirrors the
+ * Docker bond's `templateRegistry`/`templateRegistryAuth` pattern: the capability
+ * belongs to the provider, the address belongs to the operator.
+ *
+ * On Fly the natural store is Tigris — "Tigris is S3-compatible, so any AWS SDK
+ * works — point it at `https://t3.storage.dev`"
+ * (https://fly.io/docs/tigris/) — and `fly storage create` exports
+ * `BUCKET_NAME`, `AWS_ENDPOINT_URL_S3`, `AWS_ACCESS_KEY_ID` and
+ * `AWS_SECRET_ACCESS_KEY`, which are read here as fallbacks so a Fly-provisioned
+ * bucket needs no extra configuration. Any S3-compatible endpoint works; the
+ * operations used are the six Tigris documents as supported
+ * (https://www.tigrisdata.com/docs/api/s3/): PutObject, GetObject, HeadObject,
+ * ListObjectsV2, DeleteObject and DeleteObjects.
+ *
+ * @module
+ */
+import type { FlyioConfig } from './types.js';
+/** Default key prefix for every object this bond writes. */
+export declare const DEFAULT_TEMPLATE_PREFIX = "molecule-sandbox-templates";
+/**
+ * Region sent when none is configured. Tigris (and most S3-compatible stores)
+ * accept `auto`; the AWS SDK requires *some* region to build a signature, so this
+ * is not optional even against a store that ignores it.
+ */
+export declare const DEFAULT_TEMPLATE_REGION = "auto";
+/**
+ * AWS's documented ceiling on a SigV4 presigned URL: "If you use the AWS CLI or
+ * AWS SDKs, the expiration time can be set as high as 7 days."
+ * (https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
+ * A larger value is not rejected at signing time — it simply produces a URL S3
+ * refuses — so it is clamped here.
+ */
+export declare const MAX_PRESIGN_EXPIRY_SECONDS: number;
+/** One object as this bond needs to see it. */
+export interface StoredObject {
+    /** Full key, including the configured prefix. */
+    key: string;
+    /** Size in bytes. */
+    size: number;
+    /** Last-modified timestamp, ISO 8601, or `null` when the store did not report one. */
+    lastModified: string | null;
+}
+/**
+ * The object-store operations the template capability needs.
+ *
+ * Declared as an interface so `templates.ts` stays transport-free and its tests
+ * can drive a fake store, the same way `exec.ts` takes an injected `RawExec`.
+ */
+export interface ObjectStore {
+    /** Human-readable identification of the store, for error messages. */
+    readonly describe: string;
+    /** Bucket holding the templates. Used to render the opaque `SandboxTemplate.ref`. */
+    readonly bucket: string;
+    /** Key prefix every template object lives under, with no trailing slash. */
+    readonly prefix: string;
+    /**
+     * Every object under a prefix, following pagination to the end.
+     * THROWS on failure — a caller that deletes must never read a failed query as
+     * "nothing is there".
+     */
+    list(prefix: string): Promise<StoredObject[]>;
+    /** One object's metadata, or `null` when it does not exist. Throws on any other failure. */
+    head(key: string): Promise<StoredObject | null>;
+    /** An object's body as text, or `null` when it does not exist. Throws on any other failure. */
+    getText(key: string): Promise<string | null>;
+    /** Write a small text object. */
+    putText(key: string, body: string, contentType: string): Promise<void>;
+    /** Delete objects. Deleting a key that is not there is a success. */
+    remove(keys: string[]): Promise<void>;
+    /** A presigned URL a sandbox can `PUT` an archive to. */
+    presignPut(key: string, expiresInSeconds: number): Promise<string>;
+    /** A presigned URL a sandbox can `GET` an archive from. */
+    presignGet(key: string, expiresInSeconds: number): Promise<string>;
+}
+/** Resolved connection settings for the template object store. */
+interface ResolvedStorage {
+    bucket: string;
+    endpoint: string | undefined;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string | undefined;
+    forcePathStyle: boolean;
+    prefix: string;
+}
+/**
+ * Resolves template-storage settings from config and the environment.
+ *
+ * Returns `null` when the store is not configured at all, which the template
+ * methods turn into an actionable error naming the settings. Partial
+ * configuration is treated as unconfigured for the same reason: half a
+ * connection cannot be used, and reporting it as a connection failure would
+ * point an operator at the network instead of at their settings.
+ * @param config - Fly provider configuration.
+ * @returns The resolved settings, or `null` when storage is not configured.
+ */
+export declare function resolveTemplateStorage(config: FlyioConfig): ResolvedStorage | null;
+/**
+ * Creates the object store used for templates, or `null` when it is not
+ * configured.
+ *
+ * @param config - Fly provider configuration; every field has an env fallback.
+ * @returns An {@link ObjectStore}, or `null` when no bucket/credentials are set.
+ */
+export declare function createTemplateStore(config: FlyioConfig): ObjectStore | null;
+export {};
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,+BAA+B,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,SAAS,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAmB,CAAA;AAE1D,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAA;IACX,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IAC7C,4FAA4F;IAC5F,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IAC/C,+FAA+F;IAC/F,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC5C,iCAAiC;IACjC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtE,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,yDAAyD;IACzD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAClE,2DAA2D;IAC3D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACnE;AAED,kEAAkE;AAClE,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,cAAc,EAAE,OAAO,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAmBD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,CAqClF;AAmBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CA6H3E"}

package/dist/storage.js

@@ -0,0 +1,241 @@
+/**
+ * The S3-compatible object store that holds Fly sandbox templates.
+ *
+ * Fly has no `docker commit`: it PULLS images from a registry and cannot produce
+ * one from a running Machine, and the Machines API has no file-transfer endpoint
+ * at all (its whole surface is enumerated in
+ * https://docs.machines.dev/openapi.json — `exec` is the only way in or out). So a
+ * template here is a tar archive in object storage, and the bytes move between the
+ * sandbox and that store DIRECTLY over presigned URLs; this module is only the
+ * control plane's half — presigning, metadata, enumeration and deletion.
+ *
+ * **Storage is bond configuration, never interface surface.** Nothing about
+ * buckets or endpoints appears in `@molecule/api-code-sandbox`. This mirrors the
+ * Docker bond's `templateRegistry`/`templateRegistryAuth` pattern: the capability
+ * belongs to the provider, the address belongs to the operator.
+ *
+ * On Fly the natural store is Tigris — "Tigris is S3-compatible, so any AWS SDK
+ * works — point it at `https://t3.storage.dev`"
+ * (https://fly.io/docs/tigris/) — and `fly storage create` exports
+ * `BUCKET_NAME`, `AWS_ENDPOINT_URL_S3`, `AWS_ACCESS_KEY_ID` and
+ * `AWS_SECRET_ACCESS_KEY`, which are read here as fallbacks so a Fly-provisioned
+ * bucket needs no extra configuration. Any S3-compatible endpoint works; the
+ * operations used are the six Tigris documents as supported
+ * (https://www.tigrisdata.com/docs/api/s3/): PutObject, GetObject, HeadObject,
+ * ListObjectsV2, DeleteObject and DeleteObjects.
+ *
+ * @module
+ */
+import { DeleteObjectsCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+/** Default key prefix for every object this bond writes. */
+export const DEFAULT_TEMPLATE_PREFIX = 'molecule-sandbox-templates';
+/**
+ * Region sent when none is configured. Tigris (and most S3-compatible stores)
+ * accept `auto`; the AWS SDK requires *some* region to build a signature, so this
+ * is not optional even against a store that ignores it.
+ */
+export const DEFAULT_TEMPLATE_REGION = 'auto';
+/**
+ * AWS's documented ceiling on a SigV4 presigned URL: "If you use the AWS CLI or
+ * AWS SDKs, the expiration time can be set as high as 7 days."
+ * (https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
+ * A larger value is not rejected at signing time — it simply produces a URL S3
+ * refuses — so it is clamped here.
+ */
+export const MAX_PRESIGN_EXPIRY_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * Reads one template-storage setting, preferring explicit config over the
+ * environment.
+ * @param configured - The value from {@link FlyioConfig}, if any.
+ * @param names - Environment variable names to try, in order.
+ * @returns The first non-empty value, or `undefined`.
+ */
+function resolve(configured, names) {
+    const explicit = configured?.trim();
+    if (explicit)
+        return explicit;
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Resolves template-storage settings from config and the environment.
+ *
+ * Returns `null` when the store is not configured at all, which the template
+ * methods turn into an actionable error naming the settings. Partial
+ * configuration is treated as unconfigured for the same reason: half a
+ * connection cannot be used, and reporting it as a connection failure would
+ * point an operator at the network instead of at their settings.
+ * @param config - Fly provider configuration.
+ * @returns The resolved settings, or `null` when storage is not configured.
+ */
+export function resolveTemplateStorage(config) {
+    const bucket = resolve(config.templateBucket, ['SANDBOX_TEMPLATE_BUCKET', 'BUCKET_NAME']);
+    const accessKeyId = resolve(config.templateAccessKeyId, [
+        'SANDBOX_TEMPLATE_ACCESS_KEY_ID',
+        'AWS_ACCESS_KEY_ID',
+    ]);
+    const secretAccessKey = resolve(config.templateSecretAccessKey, [
+        'SANDBOX_TEMPLATE_SECRET_ACCESS_KEY',
+        'AWS_SECRET_ACCESS_KEY',
+    ]);
+    if (!bucket || !accessKeyId || !secretAccessKey)
+        return null;
+    const forcePathStyleRaw = resolve(config.templateForcePathStyle === undefined ? undefined : String(config.templateForcePathStyle), ['SANDBOX_TEMPLATE_FORCE_PATH_STYLE']);
+    return {
+        bucket,
+        endpoint: resolve(config.templateEndpoint, [
+            'SANDBOX_TEMPLATE_ENDPOINT',
+            'AWS_ENDPOINT_URL_S3',
+        ]),
+        region: resolve(config.templateRegion, ['SANDBOX_TEMPLATE_REGION', 'AWS_REGION']) ??
+            DEFAULT_TEMPLATE_REGION,
+        accessKeyId,
+        secretAccessKey,
+        sessionToken: resolve(config.templateSessionToken, [
+            'SANDBOX_TEMPLATE_SESSION_TOKEN',
+            'AWS_SESSION_TOKEN',
+        ]),
+        forcePathStyle: forcePathStyleRaw === 'true',
+        prefix: (resolve(config.templatePrefix, ['SANDBOX_TEMPLATE_PREFIX']) ?? DEFAULT_TEMPLATE_PREFIX).replace(/\/+$/, ''),
+    };
+}
+/**
+ * Reports whether an S3 error means "no such object" rather than "the lookup
+ * failed".
+ *
+ * The distinction is the whole contract for `getTemplate`: absence is an answer
+ * the caller acts on by rebuilding, while a failed lookup reported as absence
+ * turns a transient store hiccup into a full cold rebuild on every boot.
+ * @param error - The thrown error.
+ * @returns `true` for a 404 / `NoSuchKey` / `NotFound`.
+ */
+function isNotFound(error) {
+    const candidate = error;
+    if (candidate?.$metadata?.httpStatusCode === 404)
+        return true;
+    return candidate?.name === 'NotFound' || candidate?.name === 'NoSuchKey';
+}
+/**
+ * Creates the object store used for templates, or `null` when it is not
+ * configured.
+ *
+ * @param config - Fly provider configuration; every field has an env fallback.
+ * @returns An {@link ObjectStore}, or `null` when no bucket/credentials are set.
+ */
+export function createTemplateStore(config) {
+    const settings = resolveTemplateStorage(config);
+    if (!settings)
+        return null;
+    const client = new S3Client({
+        region: settings.region,
+        ...(settings.endpoint ? { endpoint: settings.endpoint } : {}),
+        forcePathStyle: settings.forcePathStyle,
+        credentials: {
+            accessKeyId: settings.accessKeyId,
+            secretAccessKey: settings.secretAccessKey,
+            ...(settings.sessionToken ? { sessionToken: settings.sessionToken } : {}),
+        },
+        // The SDK's default is `WHEN_SUPPORTED`, which adds `x-amz-checksum-crc32`
+        // to every upload. On a PRESIGNED PUT that header becomes part of
+        // `X-Amz-SignedHeaders`, so the sandbox's `curl` would have to reproduce it
+        // exactly or the signature fails — and S3-compatible stores vary in whether
+        // they accept it at all. `WHEN_REQUIRED` is the documented opt-out:
+        // https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html
+        requestChecksumCalculation: 'WHEN_REQUIRED',
+    });
+    const expiry = (seconds) => Math.max(1, Math.min(Math.floor(seconds), MAX_PRESIGN_EXPIRY_SECONDS));
+    return {
+        describe: `s3://${settings.bucket}/${settings.prefix} at ${settings.endpoint ?? `region ${settings.region}`}`,
+        bucket: settings.bucket,
+        prefix: settings.prefix,
+        async list(prefix) {
+            const objects = [];
+            let token;
+            do {
+                const page = await client.send(new ListObjectsV2Command({
+                    Bucket: settings.bucket,
+                    Prefix: prefix,
+                    ...(token ? { ContinuationToken: token } : {}),
+                }));
+                for (const entry of page.Contents ?? []) {
+                    if (!entry.Key)
+                        continue;
+                    objects.push({
+                        key: entry.Key,
+                        size: typeof entry.Size === 'number' ? entry.Size : 0,
+                        lastModified: entry.LastModified ? entry.LastModified.toISOString() : null,
+                    });
+                }
+                // `IsTruncated` alone is not enough: a truncated page without a token
+                // would loop forever on the same page.
+                token = page.IsTruncated ? page.NextContinuationToken : undefined;
+            } while (token);
+            return objects;
+        },
+        async head(key) {
+            try {
+                const response = await client.send(new HeadObjectCommand({ Bucket: settings.bucket, Key: key }));
+                return {
+                    key,
+                    size: typeof response.ContentLength === 'number' ? response.ContentLength : 0,
+                    lastModified: response.LastModified ? response.LastModified.toISOString() : null,
+                };
+            }
+            catch (error) {
+                if (isNotFound(error))
+                    return null;
+                throw error;
+            }
+        },
+        async getText(key) {
+            try {
+                const response = await client.send(new GetObjectCommand({ Bucket: settings.bucket, Key: key }));
+                return (await response.Body?.transformToString()) ?? '';
+            }
+            catch (error) {
+                if (isNotFound(error))
+                    return null;
+                throw error;
+            }
+        },
+        async putText(key, body, contentType) {
+            await client.send(new PutObjectCommand({
+                Bucket: settings.bucket,
+                Key: key,
+                Body: body,
+                ContentType: contentType,
+            }));
+        },
+        async remove(keys) {
+            // DeleteObjects caps at 1000 keys per request
+            // (https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html).
+            for (let index = 0; index < keys.length; index += 1000) {
+                const batch = keys.slice(index, index + 1000);
+                if (batch.length === 0)
+                    continue;
+                await client.send(new DeleteObjectsCommand({
+                    Bucket: settings.bucket,
+                    Delete: { Objects: batch.map((key) => ({ Key: key })), Quiet: true },
+                }));
+            }
+        },
+        async presignPut(key, expiresInSeconds) {
+            // No ContentType and no metadata: anything set here joins
+            // `X-Amz-SignedHeaders` and must then be reproduced byte-for-byte by the
+            // sandbox's `curl`. Only `host` is signed, so the upload is a plain PUT.
+            return getSignedUrl(client, new PutObjectCommand({ Bucket: settings.bucket, Key: key }), {
+                expiresIn: expiry(expiresInSeconds),
+            });
+        },
+        async presignGet(key, expiresInSeconds) {
+            return getSignedUrl(client, new GetObjectCommand({ Bucket: settings.bucket, Key: key }), {
+                expiresIn: expiry(expiresInSeconds),
+            });
+        },
+    };
+}

package/dist/templates.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Warm-start templates on Fly — capture a prepared sandbox filesystem once, and
+ * restore it into every later sandbox that wants the same configuration.
+ *
+ * ## Why a tar in object storage, and not something Fly-native
+ *
+ * The Docker bond's template is `docker commit`. Fly has no equivalent, and the
+ * two Fly-native mechanisms that look like one do not survive contact with this
+ * bond's isolation model:
+ *
+ * - **An OCI image.** Fly PULLS images from a registry; nothing in the Machines
+ *   API produces an image from a running Machine. Building one would need the
+ *   Machine's bytes in hand, which is the very thing that is hard here.
+ * - **A volume snapshot.** Fly can snapshot a volume and create a new volume from
+ *   it (`POST /v1/apps/{app}/volumes` takes `snapshot_id` "restore from snapshot"
+ *   and `source_volume_id` "fork from remote volume" —
+ *   https://docs.machines.dev/openapi.json). But a warm-start template exists to
+ *   be shared by every project with the same dependency set, and Fly documents
+ *   that "Every Fly Volume belongs to a Fly App and you can't share a volume
+ *   between apps" (https://fly.io/docs/volumes/overview/). This bond puts each
+ *   project in its OWN app precisely for tenant isolation, so a snapshot taken in
+ *   one project's app can never become another project's volume. Volume snapshots
+ *   could serve a per-project restore point and nothing else, and the core
+ *   deliberately has ONE template primitive rather than two — a provider that
+ *   implemented only the per-project half would satisfy the type and silently
+ *   fail the case the capability exists for.
+ *
+ * What is left is the boring one: `tar` the prepared paths into an S3-compatible
+ * object store and untar them into the new sandbox. The Machines API has no file
+ * transfer endpoint (`exec` is the entire surface), and pushing hundreds of
+ * megabytes through `exec`'s JSON response is not a slower version of a transfer,
+ * it is a different order of magnitude — so the bytes move DIRECTLY between the
+ * sandbox and the store over presigned URLs. The control plane only ever handles
+ * the URL, the manifest and the metadata.
+ *
+ * ## What the base image already gives you, and what this adds
+ *
+ * The base image (`registry.fly.io/molecule-sandbox:latest`) already carries the
+ * toolchain and a warmed npm cache, so this is NOT about installing Node. It is
+ * about the per-configuration layer — the scaffold plus its `node_modules` — which
+ * otherwise gets rebuilt on every single boot.
+ *
+ * ## The tenant boundary is the RESTORE, not the capture
+ *
+ * A capture runs inside a sandbox the tenant controls, so nothing done there is a
+ * security control: a tenant can replace `tar` and emit any archive it likes. The
+ * boundary is the restore, which runs in a fresh Machine before anyone gets a
+ * handle to it. Four independent properties are enforced there, each verified
+ * against GNU tar 1.35 rather than assumed:
+ *
+ * 1. **Only the manifest's `capturePaths` are extracted.** They are passed to
+ *    `tar` as member selectors, and the manifest is written by the CONTROL PLANE,
+ *    never by the sandbox. An archive that also contains `usr/bin/node` does not
+ *    get it extracted.
+ * 2. **`..` and absolute members cannot escape.** GNU tar strips a leading `/`
+ *    and refuses a member containing `..` ("Member name contains '..'") with a
+ *    non-zero exit, which fails the restore.
+ * 3. **A symlink cannot be used to write outside the tree.** GNU tar refuses to
+ *    follow a symlink member when extracting through it, and exits non-zero.
+ * 4. **setuid/setgid never survives, and that is ASSERTED.** Extraction uses
+ *    `--no-same-owner --no-same-permissions`, a `find -perm /6000 -exec chmod a-s`
+ *    sweep follows, and then a second `find` re-checks: any remaining setuid or
+ *    setgid file FAILS the restore. A failed restore destroys the Machine rather
+ *    than handing back a sandbox that looks healthy.
+ *
+ * What that does NOT cover, stated plainly: the presigned `PUT` handed to a
+ * capturing sandbox stays valid until it expires, so a hostile tenant can
+ * re-upload different bytes after the control plane has verified the object, and
+ * the manifest's `sizeBytes` would then be stale. It gains that tenant nothing it
+ * did not already have — it authored the archive in the first place — which is
+ * exactly why the boundary is on the restore side rather than on the contents.
+ * Shorten `templateUrlExpirySeconds` if a stale size would matter to you.
+ *
+ * ## What the sandbox image must contain
+ *
+ * The capture and restore run as shell commands inside the Machine, so the image
+ * needs `tar` (GNU: the `..`/symlink refusals and `--no-same-permissions` above
+ * are GNU tar behaviours), `gzip`, GNU `find` (for `-perm /6000`), `mktemp` that
+ * accepts a suffix after the `X`s, and `curl` new enough for `--fail-with-body`
+ * (7.76+). The stock `molecule-sandbox` image is Debian-based and has all of
+ * them; a custom `baseImage` built on BusyBox does not, and the failure surfaces
+ * as a capture that exits non-zero rather than as a wrong template.
+ *
+ * @module
+ */
+import type { CommitTemplateOptions, ExecResult, ListTemplatesOptions, SandboxTemplate } from '@molecule/api-code-sandbox';
+import type { ObjectStore, StoredObject } from './storage.js';
+/**
+ * Single-`PUT` ceiling: "With a single `PUT` operation, you can upload a single
+ * object up to 5 GB in size"
+ * (https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html).
+ * The sandbox uploads with one presigned PUT, so an archive above this cannot be
+ * stored and the capture refuses before spending the bandwidth.
+ */
+export declare const MAX_ARCHIVE_BYTES: number;
+/** Default wall-clock budget for a capture or restore transfer, in ms. */
+export declare const DEFAULT_TRANSFER_TIMEOUT_MS = 900000;
+/** Default lifetime of a presigned capture/restore URL, in seconds. */
+export declare const DEFAULT_PRESIGN_EXPIRY_SECONDS = 3600;
+/**
+ * Extra time a restore lease counts as live beyond the transfer budget, covering
+ * the Machine boot and the API round trips that bracket the transfer itself.
+ * A lease older than `transferTimeoutMs + this` cannot belong to a live restore,
+ * because the restore's own exec is bounded by that budget.
+ */
+export declare const LEASE_GRACE_MS = 120000;
+/** Exit status the capture script uses when the archive is over the size ceiling. */
+export declare const EXIT_ARCHIVE_TOO_LARGE = 90;
+/** Exit status the restore script uses when a setuid/setgid file survived the sweep. */
+export declare const EXIT_SETUID_SURVIVED = 91;
+/** Exit status the capture script uses when `tar` failed outright (as opposed to warning). */
+export declare const EXIT_TAR_FAILED = 92;
+/** Marker the capture script prints on stderr when `tar` reported changed files. */
+export declare const TAR_CHANGED_MARKER = "MOL_TAR_FILES_CHANGED";
+/** The control-plane-written record of a template. Its existence defines the template's existence. */
+export interface TemplateManifest {
+    /** Schema version of this record. */
+    schema: number;
+    /** The caller's template id. */
+    id: string;
+    /**
+     * Absolute paths captured, exactly as the caller named them.
+     *
+     * This is the security-relevant field: on restore these become `tar`'s member
+     * selectors, so the extraction surface is control-plane policy rather than
+     * anything the captured sandbox could influence.
+     */
+    capturePaths: string[];
+    /** When the capture completed, ISO 8601. */
+    createdAt: string;
+    /** Archive size in bytes as observed in the store at capture time. */
+    sizeBytes: number;
+    /** Free-form label recorded at capture time. */
+    label?: string;
+}
+/** What the template capability needs from the provider. */
+export interface TemplateContext {
+    /** The configured object store, or `null` when the operator has not configured one. */
+    store: ObjectStore | null;
+    /** Runs a shell command inside a Machine and returns its result. */
+    exec(app: string, machineId: string, command: string, timeoutMs: number): Promise<ExecResult>;
+    /** Blocks until a Machine is running, so it can be exec'd into. */
+    ensureStarted(app: string, machineId: string): Promise<void>;
+    /** Splits a composite sandbox id into its app and Machine id. */
+    parseSandboxId(id: string): {
+        app: string;
+        machineId: string;
+    };
+    /** Lifetime of a presigned capture/restore URL, in seconds. */
+    presignExpirySeconds: number;
+    /** Wall-clock budget for a capture or restore transfer, in ms. */
+    transferTimeoutMs: number;
+    /** Largest archive this provider will store, in bytes. */
+    maxArchiveBytes: number;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Validate a caller-supplied template id.
+ * @param templateId - The caller's identifier.
+ * @throws {Error} When the id cannot be used verbatim as an object-key segment.
+ */
+export declare function assertTemplateId(templateId: string): void;
+/**
+ * Validate a path that will be interpolated into a `sh -c` command AND used as a
+ * `tar` member selector.
+ * @param path - Candidate absolute path inside the sandbox.
+ * @throws {Error} When the path is not a plain, absolute, traversal-free path.
+ */
+export declare function assertCapturePath(path: string): void;
+/**
+ * Converts an absolute capture path into the relative member name used in the
+ * archive, so an archive of `/workspace` holds `workspace/…` and extracts with
+ * `tar -C /`.
+ * @param path - Absolute capture path.
+ * @returns The path with its leading and trailing slashes removed.
+ */
+export declare function archiveMember(path: string): string;
+/** Key of a template's manifest object. */
+export declare function manifestKey(store: ObjectStore, templateId: string): string;
+/** Key of a template's archive object. */
+export declare function archiveKey(store: ObjectStore, templateId: string): string;
+/** Key of one in-flight restore lease. */
+export declare function leaseKey(store: ObjectStore, templateId: string, leaseId: string): string;
+/**
+ * The provider-native reference for a template. OPAQUE to callers.
+ * @param store - The configured object store.
+ * @param templateId - The caller's identifier.
+ * @returns An `s3://bucket/key` reference to the archive.
+ */
+export declare function templateRef(store: ObjectStore, templateId: string): string;
+/**
+ * Require a configured object store, naming the settings that turn it on.
+ *
+ * Thrown rather than reported as "no such template": the capability is present —
+ * Fly plus any S3-compatible endpoint — and only the address is missing, so an
+ * operator needs to see the configuration error rather than watch every boot
+ * quietly rebuild from scratch.
+ * @param ctx - Template context.
+ * @returns The configured store.
+ * @throws {Error} When no store is configured.
+ */
+export declare function requireStore(ctx: TemplateContext): ObjectStore;
+/**
+ * Builds the in-sandbox capture command: archive the named paths, refuse an
+ * oversized result, and upload it to a presigned URL.
+ *
+ * The archive is written to a file BEFORE the upload rather than piped into
+ * `curl`, for two reasons that both bite: a pipeline reports only the last
+ * command's status, so a failed `tar` would upload a truncated archive and
+ * report success; and an upload from a pipe has no `Content-Length`, so `curl`
+ * sends `Transfer-Encoding: chunked`, which S3 rejects on a presigned `PUT`.
+ * @param paths - Absolute capture paths, already validated.
+ * @param url - Presigned `PUT` URL for the archive object.
+ * @param maxBytes - Largest archive that may be uploaded.
+ * @returns A `sh` script.
+ */
+export declare function buildCaptureCommand(paths: string[], url: string, maxBytes: number): string;
+/**
+ * Builds the in-sandbox restore command: download the archive, extract ONLY the
+ * manifest's paths, and prove no setuid/setgid file survived.
+ *
+ * See the module docs for why each flag is here. The download is to a file
+ * rather than piped into `tar` so a failed download cannot be reported as a
+ * successful extraction of a truncated stream.
+ * @param paths - Absolute capture paths from the CONTROL-PLANE manifest.
+ * @param url - Presigned `GET` URL for the archive object.
+ * @returns A `sh` script.
+ */
+export declare function buildRestoreCommand(paths: string[], url: string): string;
+/**
+ * Decides whether any lease means a restore is still in flight.
+ *
+ * A lease with no readable timestamp counts as LIVE. That is the whole rule the
+ * core states for this field: an unreadable answer resolves to in-use, never to
+ * free.
+ * @param leases - Lease objects for one template.
+ * @param ttlMs - How long a lease can possibly correspond to a live restore.
+ * @param now - Current time in ms since the epoch.
+ * @returns `true` when at least one lease is live.
+ */
+export declare function hasLiveLease(leases: StoredObject[], ttlMs: number, now: number): boolean;
+/**
+ * Read one template, and the manifest behind it, by the caller's identifier.
+ *
+ * Separate from {@link getTemplate} because the restore path needs the
+ * manifest's `capturePaths` — the extraction surface — and the public shape does
+ * not carry them.
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @returns The template and its manifest, or `null` when no usable template exists.
+ */
+export declare function readTemplate(ctx: TemplateContext, templateId: string): Promise<{
+    template: SandboxTemplate;
+    manifest: TemplateManifest;
+} | null>;
+/**
+ * Read one template by the caller's identifier.
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @returns The template, or `null` when no template has that id.
+ */
+export declare function getTemplate(ctx: TemplateContext, templateId: string): Promise<SandboxTemplate | null>;
+/**
+ * Enumerate templates so the caller can apply its retention policy.
+ * @param ctx - Template context.
+ * @param options - Narrowing by id prefix.
+ * @returns Every matching template.
+ */
+export declare function listTemplates(ctx: TemplateContext, options?: ListTemplatesOptions): Promise<SandboxTemplate[]>;
+/**
+ * Capture a sandbox's filesystem into a reusable template.
+ * @param ctx - Template context.
+ * @param options - What to capture and what to call it.
+ * @returns The template as it now exists.
+ * @throws {Error} When no store is configured, no capture paths were given, the
+ *   in-sandbox capture failed, or the archive cannot be read back.
+ */
+export declare function commitTemplate(ctx: TemplateContext, options: CommitTemplateOptions): Promise<SandboxTemplate>;
+/**
+ * Delete a template, refusing while a restore is still reading it.
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @throws {Error} When a restore is in flight, or the store cannot be read.
+ */
+export declare function removeTemplate(ctx: TemplateContext, templateId: string): Promise<void>;
+/**
+ * Records that a restore of this template is in flight.
+ *
+ * The lease lives in the store rather than in this process, so a second control
+ * plane enforcing a retention budget can see it. A control plane that dies
+ * mid-restore leaves the lease behind; it stops counting once it is older than
+ * the transfer budget, because no live restore can outlast that budget.
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @param leaseId - Unique id for this restore.
+ * @returns The lease's key, for release.
+ */
+export declare function acquireRestoreLease(ctx: TemplateContext, templateId: string, leaseId: string): Promise<string>;
+/**
+ * Releases a restore lease.
+ *
+ * Best-effort: the restore has already finished, and a stale lease only delays
+ * an eviction until it ages out. Failing the boot over it would trade a
+ * completed sandbox for a bookkeeping error.
+ * @param ctx - Template context.
+ * @param key - The lease key returned by {@link acquireRestoreLease}.
+ */
+export declare function releaseRestoreLease(ctx: TemplateContext, key: string): Promise<void>;
+//# sourceMappingURL=templates.d.ts.map