@alchemy.run/e2b 0.0.0-stage → 2.0.0-beta.86

package/lib/SandboxEvents.d.ts

@@ -0,0 +1,87 @@
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { SandboxEventType } from "./Webhook.ts";
+/** A sandbox lifecycle event, as E2B delivers it to a webhook. */
+export interface SandboxEvent {
+    /** The event's id. A redelivered event keeps it: deduplicate on it. */
+    readonly id: string;
+    readonly version: string;
+    readonly type: SandboxEventType;
+    readonly timestamp: string;
+    readonly sandbox_id: string;
+    readonly sandbox_execution_id: string;
+    readonly sandbox_template_id: string;
+    readonly sandbox_build_id: string;
+    readonly sandbox_team_id: string;
+    readonly event_data?: {
+        /** The sandbox's metadata, including the ownership stamp of the host that created it. */
+        readonly sandbox_metadata?: Readonly<Record<string, string>>;
+        /** On `killed` and `paused`: what the run used. */
+        readonly execution?: Readonly<Record<string, unknown>>;
+        /** On `killed`. */
+        readonly kill_reason?: string;
+        /** On `paused`: `full` (memory and disk) or `filesystem`. */
+        readonly pause_mode?: "full" | "filesystem";
+        /** On `resumed`: `restore` (memory) or `reboot`. */
+        readonly resume_mode?: "restore" | "reboot";
+    };
+}
+export interface SandboxEventsProps {
+    /**
+     * The events to receive.
+     * @default every sandbox lifecycle event
+     */
+    readonly events?: ReadonlyArray<SandboxEventType>;
+    /**
+     * The secret E2B signs deliveries with. A random one is generated and
+     * bound onto the host when omitted.
+     */
+    readonly secret?: Redacted.Redacted<string>;
+    /**
+     * The path on the host E2B delivers to.
+     * @default "/__alchemy/e2b/events"
+     */
+    readonly path?: string;
+}
+/** Receives sandbox lifecycle events on a host. */
+export type SandboxEventsService = <Req = never>(props: SandboxEventsProps, process: (event: SandboxEvent) => Effect.Effect<void, never, Req>) => Effect.Effect<void, never, never>;
+declare const SandboxEvents_base: Context.ServiceClass<SandboxEvents, "E2B.SandboxEvents", SandboxEventsService>;
+/**
+ * Receive E2B sandbox lifecycle events (created, paused, resumed,
+ * checkpointed, updated, killed) in a Worker or any other webhook host.
+ *
+ * At deploy, an {@link Webhook} is created pointing at the host. At runtime,
+ * each delivery's `e2b-signature` is verified before the handler runs; an
+ * unsigned or wrongly signed request is rejected with 401. E2B retries a
+ * failed delivery up to three times, so handlers should be idempotent on
+ * `event.id`.
+ *
+ * ### Handling lifecycle events
+ * **Example:** Record every killed sandbox
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     yield* E2B.consumeSandboxEvents({ events: ["sandbox.lifecycle.killed"] }, (event) =>
+ *       Effect.log(`sandbox ${event.sandbox_id} killed: ${event.event_data?.kill_reason}`),
+ *     );
+ *     return { fetch: Effect.succeed(HttpServerResponse.text("ok")) };
+ *   }).pipe(Effect.provide(E2B.SandboxEventsLive)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Webhook
+ */
+export declare class SandboxEvents extends SandboxEvents_base {
+}
+/** Subscribes the current host to sandbox lifecycle events. */
+export declare const consumeSandboxEvents: <Req = never>(props: SandboxEventsProps, process: (event: SandboxEvent) => Effect.Effect<void, never, Req>) => Effect.Effect<void, never, SandboxEvents>;
+/** Where E2B delivers on the host. */
+export declare const sandboxEventsPath: (props: SandboxEventsProps) => string;
+/** The env var the signing secret is bound under. */
+export declare const sandboxEventsSecretEnvName: (path: string) => string;
+export {};
+//# sourceMappingURL=SandboxEvents.d.ts.map

package/lib/SandboxEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEvents.d.ts","sources":["../src/SandboxEvents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,yFAAyF;QACzF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7D,mDAAmD;QACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACvD,mBAAmB;QACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,6DAA6D;QAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;QAC5C,oDAAoD;QACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;KAC7C,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,GAAG,KAAK,EAC7C,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAC9D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAc,SAAQ,kBAElC;CAAG;AAEJ,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,GAAI,GAAG,GAAG,KAAK,SACvC,kBAAkB,WAChB,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,8CACT,CAAC;AAE3D,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,UAAW,kBAAkB,KAAG,MACvB,CAAC;AAExC,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,SAAU,MAAM,KAAG,MACP,CAAC"}

package/lib/SandboxEvents.js

@@ -0,0 +1,39 @@
+import { sanitizeKey } from "alchemy/RuntimeContext";
+import * as Context from "effect/Context";
+/**
+ * Receive E2B sandbox lifecycle events (created, paused, resumed,
+ * checkpointed, updated, killed) in a Worker or any other webhook host.
+ *
+ * At deploy, an {@link Webhook} is created pointing at the host. At runtime,
+ * each delivery's `e2b-signature` is verified before the handler runs; an
+ * unsigned or wrongly signed request is rejected with 401. E2B retries a
+ * failed delivery up to three times, so handlers should be idempotent on
+ * `event.id`.
+ *
+ * ### Handling lifecycle events
+ * **Example:** Record every killed sandbox
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     yield* E2B.consumeSandboxEvents({ events: ["sandbox.lifecycle.killed"] }, (event) =>
+ *       Effect.log(`sandbox ${event.sandbox_id} killed: ${event.event_data?.kill_reason}`),
+ *     );
+ *     return { fetch: Effect.succeed(HttpServerResponse.text("ok")) };
+ *   }).pipe(Effect.provide(E2B.SandboxEventsLive)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Webhook
+ */
+export class SandboxEvents extends Context.Service()("E2B.SandboxEvents") {
+}
+/** Subscribes the current host to sandbox lifecycle events. */
+export const consumeSandboxEvents = (props, process) => SandboxEvents.use((source) => source(props, process));
+/** Where E2B delivers on the host. */
+export const sandboxEventsPath = (props) => props.path ?? "/__alchemy/e2b/events";
+/** The env var the signing secret is bound under. */
+export const sandboxEventsSecretEnvName = (path) => `ALCHEMY_E2B_WEBHOOK_SECRET_${sanitizeKey(path)}`;
+//# sourceMappingURL=SandboxEvents.js.map

package/lib/SandboxEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEvents.js","sources":["../src/SandboxEvents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAuD1C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,aAAc,SAAQ,OAAO,CAAC,OAAO,EAAuC,CACvF,mBAAmB,CACpB;CAAG;AAEJ,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAAyB,EACzB,OAAiE,EACjE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3D,sCAAsC;AACtC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAyB,EAAU,EAAE,CACrE,KAAK,CAAC,IAAI,IAAI,uBAAuB,CAAC;AAExC,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,IAAY,EAAU,EAAE,CACjE,8BAA8B,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC"}

package/lib/SandboxEventsLive.d.ts

@@ -0,0 +1,13 @@
+import { WebhookHost } from "alchemy/WebhookHost";
+import * as Layer from "effect/Layer";
+import { SandboxEvents } from "./SandboxEvents.ts";
+/**
+ * {@link SandboxEvents} on any {@link WebhookHost}: every Cloudflare Worker
+ * is one.
+ *
+ * @layer
+ * @product Webhook
+ * @provides E2B.SandboxEvents
+ */
+export declare const SandboxEventsLive: Layer.Layer<SandboxEvents, never, WebhookHost>;
+//# sourceMappingURL=SandboxEventsLive.d.ts.map

package/lib/SandboxEventsLive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEventsLive.d.ts","sources":["../src/SandboxEventsLive.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,EAEL,aAAa,EAKd,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,gDAuC7B,CAAC"}

package/lib/SandboxEventsLive.js

@@ -0,0 +1,80 @@
+import * as Namespace from "alchemy/Namespace";
+import * as Output from "alchemy/Output";
+import { Random } from "alchemy/Random";
+import { WebhookHost } from "alchemy/WebhookHost";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { SandboxEvents, sandboxEventsPath, sandboxEventsSecretEnvName, } from "./SandboxEvents.js";
+import { ALL_SANDBOX_EVENTS, Webhook } from "./Webhook.js";
+/**
+ * {@link SandboxEvents} on any {@link WebhookHost}: every Cloudflare Worker
+ * is one.
+ *
+ * @layer
+ * @product Webhook
+ * @provides E2B.SandboxEvents
+ */
+export const SandboxEventsLive = Layer.effect(SandboxEvents, Effect.gen(function* () {
+    const host = yield* WebhookHost;
+    // Yielding the resource class erases its `Providers` requirement; the
+    // stack satisfies it at plan time.
+    const createWebhook = yield* Webhook;
+    return Effect.fn(function* (props, process) {
+        const path = sandboxEventsPath(props);
+        const secret = props.secret ??
+            (yield* Namespace.push(host.LogicalId, Random(`E2BEventsSecret${path}`))).text;
+        if (!globalThis.__ALCHEMY_RUNTIME__) {
+            yield* Namespace.push(host.LogicalId, Effect.asVoid(createWebhook(`E2BEvents${path}`, {
+                url: Output.interpolate `${host.url}${path}`,
+                events: [...(props.events ?? ALL_SANDBOX_EVENTS)],
+                signatureSecret: secret,
+            })));
+        }
+        // Registers the secret on the host at deploy, reads it back at runtime.
+        const boundSecret = yield* Output.named(Output.asOutput(secret), sandboxEventsSecretEnvName(path)).asEffect();
+        yield* host.route(path, (request) => handleDelivery(request, boundSecret, process));
+    });
+}));
+const handleDelivery = (request, secret, process) => Effect.gen(function* () {
+    if (request.method !== "POST")
+        return new Response("method not allowed", { status: 405 });
+    const body = yield* Effect.tryPromise(() => request.text()).pipe(Effect.option);
+    if (body._tag === "None")
+        return new Response("unreadable body", { status: 400 });
+    const resolved = yield* secret;
+    const valid = yield* verifySignature(resolved === undefined ? undefined : Redacted.value(resolved), body.value, request.headers.get("e2b-signature") ?? undefined);
+    if (!valid)
+        return new Response("invalid signature", { status: 401 });
+    const event = yield* Effect.try(() => JSON.parse(body.value)).pipe(Effect.orElseSucceed(() => undefined));
+    if (event === undefined)
+        return new Response("invalid payload", { status: 400 });
+    yield* process(event);
+    return new Response(null, { status: 202 });
+});
+/**
+ * E2B's signature: the unpadded base64 SHA-256 of the secret followed by the
+ * raw body (a plain hash, not an HMAC).
+ */
+const verifySignature = (secret, body, signature) => Effect.gen(function* () {
+    if (!secret || !signature)
+        return false;
+    const digest = yield* Effect.tryPromise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret + body))).pipe(Effect.option);
+    if (digest._tag === "None")
+        return false;
+    let binary = "";
+    for (const byte of new Uint8Array(digest.value))
+        binary += String.fromCharCode(byte);
+    const expected = btoa(binary).replace(/=+$/, "");
+    return timingSafeEqual(expected, signature);
+});
+/** Constant-time comparison; `crypto.timingSafeEqual` needs `nodejs_compat` on Workers. */
+const timingSafeEqual = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i++)
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return mismatch === 0;
+};
+//# sourceMappingURL=SandboxEventsLive.js.map

package/lib/SandboxEventsLive.js.map

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

package/lib/Secret.d.ts

@@ -0,0 +1,105 @@
+import * as secrets from "@distilled.cloud/e2b/secrets";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Providers } from "./Providers.ts";
+export interface SecretProps {
+    /**
+     * Secret name, unique within the team. E2B lowercases it. If omitted, a
+     * unique name is generated from the stack, stage and logical ID. Changing
+     * it replaces the secret.
+     */
+    name?: string;
+    /**
+     * The secret value. Write-only: E2B never returns it. Changing it stores a
+     * new version, which every sandbox resolves on its next request.
+     */
+    value: Redacted.Redacted<string>;
+    /** Your own metadata (at most 32 entries). */
+    metadata?: Record<string, string>;
+}
+export interface SecretAttributes {
+    /** E2B's secret id (`sec_…`). */
+    secretId: string;
+    /** The secret's canonical (lowercased) name. */
+    name: string;
+    /** The version sandboxes resolve. */
+    version: number;
+    /** Your metadata, without Alchemy's ownership stamp. */
+    metadata: Record<string, string>;
+    /**
+     * The placeholder E2B resolves to the secret's value at sandbox egress:
+     * `${e2b.secrets.<name>}`. Put it in a sandbox's network header rules; the
+     * value itself never enters the sandbox.
+     */
+    ref: string;
+}
+export interface Secret extends Resource<"E2B.Secret", SecretProps, SecretAttributes, never, Providers, {
+    name: string;
+}> {
+}
+/**
+ * An E2B secret: a write-only value that E2B injects into a sandbox's
+ * outbound requests, so code inside the sandbox never sees it.
+ *
+ * Reference a secret in a sandbox's network rules with its `ref`
+ * placeholder (`${e2b.secrets.<name>}`). E2B resolves the placeholder at
+ * egress, on the host, for requests to the domains you list.
+ *
+ * Alchemy stamps its stack, stage and logical ID into the secret's
+ * metadata to recognise the secrets it owns.
+ *
+ * ### Creating a Secret
+ * **Example:** A GitHub token from the stage's config
+ * ```typescript
+ * export const GitHubToken = E2B.Secret("GitHubToken", {
+ *   value: Config.Redacted("GITHUB_TOKEN"),
+ * });
+ * ```
+ *
+ * ### Injecting a Secret at egress
+ * **Example:** Authenticate GitHub API calls from inside a sandbox
+ * ```typescript
+ * const github = yield* GitHubToken;
+ * const sandbox = yield* sandboxes.create({
+ *   network: {
+ *     allowOut: ["api.github.com"],
+ *     rules: {
+ *       "api.github.com": [{ transform: { headers: { Authorization: `Bearer ${github.ref}` } } }],
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * ### Rotating a Secret
+ * Changing `value` stores a new version in place. Sandboxes resolve the new
+ * version on their next request.
+ *
+ * **Example:** Rotate at runtime with `WriteSecret`
+ * ```typescript
+ * const token = yield* E2B.WriteSecret(GitHubToken);
+ * yield* token.put(Redacted.make(freshToken));
+ * ```
+ *
+ * ### Referencing a secret the stack doesn't manage
+ * `E2B.Secret.lookup` finds an existing secret by name. Nothing is created,
+ * adopted or deleted.
+ *
+ * **Example:** Look one up by name
+ * ```typescript
+ * const github = E2B.Secret.lookup({ name: "github-token" });
+ * const token = yield* E2B.WriteSecret(github);
+ * ```
+ *
+ * @resource
+ * @product Secret
+ */
+export declare const Secret: import("alchemy/Resource").ResourceClass<Secret>;
+/** E2B's egress placeholder for a secret name. */
+export declare const secretRef: (name: string) => string;
+export declare const toSecretAttributes: (secret: secrets.Secret) => SecretAttributes;
+/** A secret by id or canonical name (E2B accepts either). */
+export declare const observeSecret: (idOrName: string) => Effect.Effect<secrets.Secret | undefined, import("@distilled.cloud/e2b").BadRequest | import("@distilled.cloud/e2b").ConfigError | import("@distilled.cloud/e2b").Conflict | import("@distilled.cloud/e2b").Forbidden | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/core/protocol-http").InvalidInput | import("@distilled.cloud/e2b").Locked | import("@distilled.cloud/core/sdk-error").SdkError | import("@distilled.cloud/e2b").UnprocessableEntity | import("@distilled.cloud/e2b").ClientErrors | import("@distilled.cloud/core/errors").DefaultErrors, secrets.E2BOpContext>;
+export declare const SecretProvider: () => import("effect/Layer").Layer<Provider.Provider<Secret>, never, import("alchemy/Stack").Stack | import("alchemy/Stage").Stage | secrets.E2BOpContext>;
+//# sourceMappingURL=Secret.d.ts.map

package/lib/Secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Secret.d.ts","sources":["../src/Secret.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,8BAA8B,CAAC;AAGxD,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAU5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,MAAO,SAAQ,QAAQ,CACtC,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,KAAK,EACL,SAAS,EACT;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CACjB;CAAG;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,MAAM,kDAAiC,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,SAAS,SAAU,MAAM,KAAG,MAAmC,CAAC;AAE7E,eAAO,MAAM,kBAAkB,WAAY,OAAO,CAAC,MAAM,KAAG,gBAM1D,CAAC;AAEH,6DAA6D;AAC7D,eAAO,MAAM,aAAa,aAAc,MAAM,6lBAI3C,CAAC;AAQJ,eAAO,MAAM,cAAc,4JAsFxB,CAAC"}

package/lib/Secret.js

@@ -0,0 +1,161 @@
+import * as secrets from "@distilled.cloud/e2b/secrets";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
+import { E2BUnexpectedResponse } from "./Errors.js";
+import { e2bName, hasAnyAlchemyMetadata, hasOwnershipMetadata, ownershipMetadata, userMetadata, } from "./internal/Ownership.js";
+/**
+ * An E2B secret: a write-only value that E2B injects into a sandbox's
+ * outbound requests, so code inside the sandbox never sees it.
+ *
+ * Reference a secret in a sandbox's network rules with its `ref`
+ * placeholder (`${e2b.secrets.<name>}`). E2B resolves the placeholder at
+ * egress, on the host, for requests to the domains you list.
+ *
+ * Alchemy stamps its stack, stage and logical ID into the secret's
+ * metadata to recognise the secrets it owns.
+ *
+ * ### Creating a Secret
+ * **Example:** A GitHub token from the stage's config
+ * ```typescript
+ * export const GitHubToken = E2B.Secret("GitHubToken", {
+ *   value: Config.Redacted("GITHUB_TOKEN"),
+ * });
+ * ```
+ *
+ * ### Injecting a Secret at egress
+ * **Example:** Authenticate GitHub API calls from inside a sandbox
+ * ```typescript
+ * const github = yield* GitHubToken;
+ * const sandbox = yield* sandboxes.create({
+ *   network: {
+ *     allowOut: ["api.github.com"],
+ *     rules: {
+ *       "api.github.com": [{ transform: { headers: { Authorization: `Bearer ${github.ref}` } } }],
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * ### Rotating a Secret
+ * Changing `value` stores a new version in place. Sandboxes resolve the new
+ * version on their next request.
+ *
+ * **Example:** Rotate at runtime with `WriteSecret`
+ * ```typescript
+ * const token = yield* E2B.WriteSecret(GitHubToken);
+ * yield* token.put(Redacted.make(freshToken));
+ * ```
+ *
+ * ### Referencing a secret the stack doesn't manage
+ * `E2B.Secret.lookup` finds an existing secret by name. Nothing is created,
+ * adopted or deleted.
+ *
+ * **Example:** Look one up by name
+ * ```typescript
+ * const github = E2B.Secret.lookup({ name: "github-token" });
+ * const token = yield* E2B.WriteSecret(github);
+ * ```
+ *
+ * @resource
+ * @product Secret
+ */
+export const Secret = Resource("E2B.Secret");
+/** E2B's egress placeholder for a secret name. */
+export const secretRef = (name) => `\${e2b.secrets.${name}}`;
+export const toSecretAttributes = (secret) => ({
+    secretId: secret.secretID,
+    name: secret.name,
+    version: secret.currentVersion,
+    metadata: userMetadata(secret.metadata),
+    ref: secretRef(secret.name),
+});
+/** A secret by id or canonical name (E2B accepts either). */
+export const observeSecret = (idOrName) => secrets.getSecret({ secretID: idOrName }).pipe(Effect.map((secret) => secret), Effect.catchTag("NotFound", () => Effect.undefined));
+const sameMetadata = (a, b) => {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys)
+        if (a[key] !== b[key])
+            return false;
+    return true;
+};
+export const SecretProvider = () => Provider.effect(Secret, Effect.gen(function* () {
+    return {
+        stables: ["secretId", "name", "ref"],
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+            if (!isResolved(news))
+                return undefined;
+            if (news.name === undefined && olds?.name === undefined)
+                return undefined;
+            const name = output?.name ?? (yield* e2bName(id, olds?.name));
+            if (news.name?.toLowerCase() !== name)
+                return { action: "replace" };
+            return undefined;
+        }),
+        lookup: Effect.fn(function* ({ name }) {
+            const secret = yield* observeSecret(name.toLowerCase());
+            return secret === undefined ? undefined : toSecretAttributes(secret);
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+            const name = output?.name ?? (yield* e2bName(id, olds?.name));
+            const secret = yield* observeSecret(output?.secretId ?? name);
+            if (secret === undefined)
+                return undefined;
+            const attrs = toSecretAttributes(secret);
+            const ours = output !== undefined ||
+                (yield* hasOwnershipMetadata(id, secret.metadata));
+            return ours ? attrs : Unowned(attrs);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, olds, output, session }) {
+            const name = output?.name ?? (yield* e2bName(id, news.name)).toLowerCase();
+            const metadata = { ...news.metadata, ...(yield* ownershipMetadata(id)) };
+            // Observe
+            let secret = yield* observeSecret(output?.secretId ?? name);
+            // Ensure — a Conflict is a peer creating the same name: read it back
+            // and fall through to the sync, which writes our value.
+            if (secret === undefined) {
+                yield* session.note(`Creating secret ${name}...`);
+                const created = yield* secrets.createSecret({ name, value: news.value, metadata }).pipe(Effect.map((s) => s), Effect.catchTag("Conflict", () => Effect.undefined));
+                if (created !== undefined)
+                    return toSecretAttributes(created);
+                secret = yield* observeSecret(name);
+                if (secret === undefined) {
+                    return yield* new E2BUnexpectedResponse({
+                        message: `E2B secret ${name} vanished after create`,
+                    });
+                }
+                // A secret someone else created under this name: write our value.
+                olds = undefined;
+            }
+            // Sync — values are write-only, so `olds` is the only signal that the
+            // stored value already matches. Without it (adoption, a lost write),
+            // store ours. Metadata is observed.
+            const valueChanged = olds === undefined || Redacted.value(olds.value) !== Redacted.value(news.value);
+            const metadataChanged = !sameMetadata(metadata, secret.metadata);
+            if (valueChanged || metadataChanged) {
+                secret = yield* secrets.updateSecret({
+                    secretID: secret.secretID,
+                    value: news.value,
+                    metadata,
+                });
+            }
+            return toSecretAttributes(secret);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+            yield* secrets
+                .deleteSecret({ secretID: output.secretId })
+                .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+            const all = Array.from(yield* Stream.runCollect(secrets.listSecrets.items({ limit: 100 })));
+            return all
+                .filter((secret) => hasAnyAlchemyMetadata(secret.metadata))
+                .map(toSecretAttributes);
+        }),
+    };
+}));
+//# sourceMappingURL=Secret.js.map

package/lib/Secret.js.map

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

package/lib/Snapshot.d.ts

@@ -0,0 +1,118 @@
+import * as templates from "@distilled.cloud/e2b/templates";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import type { Providers } from "./Providers.ts";
+import type { SandboxTemplate } from "./Sandbox.ts";
+export interface SnapshotProps {
+    /**
+     * The `E2B.Template` (or `E2B.Snapshot`) the snapshot starts from.
+     * Rebuilding it takes the snapshot again.
+     */
+    template: SandboxTemplate;
+    /**
+     * Shell commands run in order (`bash -l -c`) before the snapshot is taken:
+     * clone a repository, install dependencies, warm a cache. A non-zero exit
+     * fails the deploy with `SnapshotSetupFailed`.
+     */
+    run: string[];
+    /** Environment variables for the setup commands. */
+    envs?: Record<string, string>;
+    /** Working directory for the setup commands. @default the sandbox user's home */
+    cwd?: string;
+    /**
+     * Capture memory as well as the filesystem, so sandboxes resume with the
+     * setup's processes still running. `false` captures the filesystem only
+     * and sandboxes cold-boot from it.
+     * @default true
+     */
+    memory?: boolean;
+    /**
+     * Snapshot name. If omitted, a unique name is generated from the stack,
+     * stage and logical ID. Changing it replaces the snapshot.
+     */
+    name?: string;
+    /**
+     * How long the setup sandbox may run, in seconds.
+     * @default 900
+     */
+    timeout?: number;
+}
+export interface SnapshotAttributes {
+    /** The id sandboxes are created from, e.g. `my-team/my-snapshot:default`. */
+    snapshotId: string;
+    /** The snapshot's name. */
+    name: string;
+    /** E2B's template id for the snapshot (a snapshot is stored as a template). */
+    templateId: string;
+    /** Every name the snapshot answers to. */
+    names: string[];
+    /** Content hash of the base and setup. A deploy re-snapshots only when it changes. */
+    setupHash: string;
+}
+export interface Snapshot extends Resource<"E2B.Snapshot", SnapshotProps, SnapshotAttributes, never, Providers, {
+    name: string;
+}> {
+}
+/**
+ * A warm base to fork sandboxes from: a template booted, set up with your
+ * commands, and snapshotted — memory included, so sandboxes created from it
+ * start exactly where the setup left off.
+ *
+ * Use a snapshot for work that is too slow to repeat per sandbox and does
+ * not belong in an image: cloning a repository, installing its
+ * dependencies, starting a language server. A deploy re-runs the setup only
+ * when the template or the commands change. E2B stores a snapshot as a
+ * template, so it is created from with `E2B.CreateSandbox(snapshot)` and
+ * deleted with its template.
+ *
+ * ### Creating a Snapshot
+ * **Example:** A repository with its dependencies installed
+ * ```typescript
+ * export const Agent = E2B.Template("Agent", { image: "node:22-bookworm" });
+ *
+ * export const Warm = E2B.Snapshot("Warm", {
+ *   template: Agent,
+ *   run: [
+ *     "git clone https://github.com/alchemy-run/alchemy /home/user/alchemy",
+ *     "cd /home/user/alchemy && pnpm install",
+ *   ],
+ * });
+ * ```
+ *
+ * ### Forking sandboxes from a Snapshot
+ * **Example:** Every sandbox starts from the warm base
+ * ```typescript
+ * const sandboxes = yield* E2B.CreateSandbox(Warm);
+ * const sandbox = yield* sandboxes.create({ timeout: 600 });
+ * yield* sandbox.exec("cd alchemy && pnpm test");
+ * ```
+ *
+ * ### Referencing a snapshot the stack doesn't manage
+ * `E2B.Snapshot.lookup` finds an existing snapshot by name. Nothing is created,
+ * adopted or deleted.
+ *
+ * **Example:** Look one up by name
+ * ```typescript
+ * const warm = E2B.Snapshot.lookup({ name: "warm-repo" });
+ * const sandboxes = yield* E2B.CreateSandbox(warm);
+ * ```
+ *
+ * @resource
+ * @product Snapshot
+ */
+export declare const Snapshot: import("alchemy/Resource").ResourceConstructor<Snapshot, Providers> & Effect.Effect<import("alchemy/Resource").ResourceConstructor<Snapshot, never>, never, never> & {
+    Self: import("alchemy/Self").Self<Snapshot>;
+    Provider: Provider.Provider<Snapshot>;
+    Aliases: readonly string[] | undefined;
+    ref(id: string, options?: {
+        stage?: string;
+        stack?: string;
+    }): Effect.Effect<Snapshot, never, never>;
+} & {
+    lookup(props: {
+        name: import("alchemy/Input").Input<string>;
+    }): Snapshot;
+} & ((id: string, props: import("./internal/Declared.ts").DeclaredProps<SnapshotProps>) => Effect.Effect<Snapshot, never, Providers>);
+export declare const SnapshotProvider: () => import("effect/Layer").Layer<Provider.Provider<Snapshot>, never, import("alchemy/Stack").Stack | import("alchemy/Stage").Stage | templates.E2BOpContext>;
+//# sourceMappingURL=Snapshot.d.ts.map

package/lib/Snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Snapshot.d.ts","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,SAAS,MAAM,gCAAgC,CAAC;AAG5D,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAKxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAS,SAAQ,QAAQ,CACxC,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CACjB;CAAG;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;qIAA6D,CAAC;AAyBnF,eAAO,MAAM,gBAAgB,gKA0F1B,CAAC"}