alchemy 0.76.1 → 0.77.1

package/src/docker/image.ts

@@ -5,6 +5,7 @@ import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import type { Secret } from "../secret.ts";
 import { DockerApi } from "./api.ts";
+import type { RemoteImage } from "./remote-image.ts";
 
 /**
  * Options for building a Docker image
@@ -40,9 +41,28 @@ export interface DockerBuildOptions {
   target?: string;
 
   /**
-   * List of images to use for cache
+   * Use an external cache source for a build
+   *
+   * @see https://docs.docker.com/reference/cli/docker/buildx/build/#cache-from
+   *
    */
   cacheFrom?: string[];
+
+  /**
+   * Export build cache to an external cache destination
+   *
+   * @see https://docs.docker.com/reference/cli/docker/buildx/build/#cache-to
+   *
+   */
+  cacheTo?: string[];
+
+  /**
+   * Additional options to pass to the Docker build command. This serves as an escape hatch for any additional options that are not supported by the other properties.
+   *
+   * @see https://docs.docker.com/reference/cli/docker/buildx/build/#options
+   *
+   */
+  options?: string[];
 }
 
 export interface ImageRegistry {
@@ -54,22 +74,12 @@ export interface ImageRegistry {
 /**
  * Properties for creating a Docker image
  */
-export interface ImageProps {
-  /**
-   * Repository name for the image (e.g., "username/image")
-   */
-  name?: string;
-
+export type ImageProps = {
   /**
    * Tag for the image (e.g., "latest")
    */
   tag?: string;
 
-  /**
-   * Build configuration
-   */
-  build?: DockerBuildOptions;
-
   /**
    * Registry credentials
    */
@@ -79,12 +89,36 @@ export interface ImageProps {
    * Whether to skip pushing the image to registry
    */
   skipPush?: boolean;
-}
+} & (
+  | {
+      /**
+       * Image name or reference (e.g., "nginx:alpine")
+       */
+      image: string | Image | RemoteImage;
+      build?: never;
+      name?: never;
+    }
+  | {
+      /**
+       * Repository name for the image (e.g., "username/image")
+       *
+       * @default - the id
+       */
+      name?: string;
+      /**
+       * Build configuration
+       */
+      build: DockerBuildOptions;
+
+      image?: never;
+    }
+);
 
 /**
  * Docker Image resource
  */
-export interface Image extends ImageProps {
+export interface Image {
+  kind: "Image";
   /**
    * Image name
    */
@@ -109,6 +143,15 @@ export interface Image extends ImageProps {
    * Time when the image was built
    */
   builtAt: number;
+  /**
+   * Tag for the image
+   */
+  tag: string;
+
+  /**
+   * Build configuration
+   */
+  build: DockerBuildOptions | undefined;
 }
 
 /**
@@ -142,12 +185,32 @@ export const Image = Resource(
       // No action needed for delete as Docker images aren't automatically removed
       // This is intentional as other resources might depend on the same image
       return this.destroy();
-    } else {
-      // Normalize properties
-      const tag = props.tag || "latest";
-      const name = props.name || id;
-      const imageRef = `${name}:${tag}`;
+    }
 
+    const tag = props.tag || "latest";
+    const name =
+      props.name ||
+      (typeof props.image === "string"
+        ? props.image
+        : props.image?.name
+      )?.split(":")[0] ||
+      id;
+    const imageRef = `${name}:${tag}`;
+    let imageId: string | undefined;
+    if (props.image) {
+      const image =
+        typeof props.image === "string" ? props.image : props.image.imageRef;
+
+      const kind =
+        typeof props.image === "object" && props.image.kind === "Image"
+          ? "local"
+          : "remote";
+      if (kind === "remote") {
+        await api.pullImage(image);
+      }
+      await api.tagImage(image, imageRef);
+      // TODO: Extract image ID from pull output if available
+    } else {
       let context: string;
       let dockerfile: string;
       if (props.build?.dockerfile && props.build?.context) {
@@ -170,7 +233,7 @@ export const Image = Resource(
       const buildOptions: Record<string, string> = props.build?.args || {};
 
       // Add platform if specified
-      let buildArgs = ["build", "-t", imageRef];
+      const buildArgs = ["build", "-t", imageRef];
 
       if (props.build?.platform) {
         buildArgs.push("--platform", props.build.platform);
@@ -188,11 +251,23 @@ export const Image = Resource(
         }
       }
 
+      // Add cache destinations if specified
+      if (props.build?.cacheTo && props.build.cacheTo.length > 0) {
+        for (const cacheTarget of props.build.cacheTo) {
+          buildArgs.push("--cache-to", cacheTarget);
+        }
+      }
+
       // Add build arguments
       for (const [key, value] of Object.entries(buildOptions)) {
         buildArgs.push("--build-arg", `${key}=${value}`);
       }
 
+      // Add build options if specified
+      if (props.build?.options && props.build.options.length > 0) {
+        buildArgs.push(...props.build.options);
+      }
+
       buildArgs.push("-f", dockerfile);
 
       // Add context path
@@ -203,77 +278,77 @@ export const Image = Resource(
 
       // Extract image ID from build output if available
       const imageIdMatch = /Successfully built ([a-f0-9]+)/.exec(stdout);
-      const imageId = imageIdMatch ? imageIdMatch[1] : undefined;
-
-      // Handle push if required
-      let repoDigest: string | undefined;
-      let finalImageRef = imageRef;
-      if (props.registry && !props.skipPush) {
-        const { server, username, password } = props.registry;
-
-        // Ensure the registry server does not have trailing slash
-        const registryHost = server.replace(/\/$/, "");
-
-        // Determine if the built image already includes a registry host (e.g. ghcr.io/user/repo)
-        const firstSegment = imageRef.split("/")[0];
-        const hasRegistryPrefix = firstSegment.includes(".");
-
-        // Compose the target image reference that will be pushed
-        const targetImage = hasRegistryPrefix
-          ? imageRef // already fully-qualified
-          : `${registryHost}/${imageRef}`;
-
-        try {
-          // Create a temporary directory that will act as an isolated Docker config
-          // (credentials) directory. This prevents race-conditions when multiple
-          // concurrent tests perform `docker login` / `logout` by ensuring each
-          // Image operation has its own credential store.
-          const tempConfigDir = await fs.mkdtemp(
-            path.join(os.tmpdir(), "docker-config-"),
-          );
-          const api = new DockerApi({ configDir: tempConfigDir });
-
-          // Authenticate to registry using the isolated config directory
-          await api.login(registryHost, username, password.unencrypted);
-
-          // Tag local image with fully qualified name if necessary
-          if (targetImage !== imageRef) {
-            await api.exec(["tag", imageRef, targetImage]);
-          }
-
-          // Push the image
-          const { stdout: pushOut } = await api.exec(["push", targetImage]);
-
-          // Attempt to extract the repo digest from push output
-          const digestMatch = /digest:\s+([a-z0-9]+:[a-f0-9]{64})/.exec(
-            pushOut,
-          );
-          if (digestMatch) {
-            const digestHash = digestMatch[1];
-            // Strip tag (anything after last :) to build image@digest reference
-            const [repoWithoutTag] =
-              targetImage.split(":").length > 2
-                ? [targetImage] // unlikely but safety
-                : [targetImage.substring(0, targetImage.lastIndexOf(":"))];
-            repoDigest = `${repoWithoutTag}@${digestHash}`;
-          }
-
-          // Update the final image reference to point at the pushed image
-          finalImageRef = targetImage;
-        } finally {
-          // Clean up credentials from the isolated config
-          await api.logout(registryHost);
+      imageId = imageIdMatch ? imageIdMatch[1] : undefined;
+    }
+
+    // Handle push if required
+    let repoDigest: string | undefined;
+    let finalImageRef = imageRef;
+    if (props.registry && !props.skipPush) {
+      const { server, username, password } = props.registry;
+
+      // Ensure the registry server does not have trailing slash
+      const registryHost = server.replace(/\/$/, "");
+
+      // Determine if the built image already includes a registry host (e.g. ghcr.io/user/repo)
+      const firstSegment = imageRef.split("/")[0];
+      const hasRegistryPrefix = firstSegment.includes(".");
+
+      // Compose the target image reference that will be pushed
+      const targetImage = hasRegistryPrefix
+        ? imageRef // already fully-qualified
+        : `${registryHost}/${imageRef}`;
+
+      try {
+        // Create a temporary directory that will act as an isolated Docker config
+        // (credentials) directory. This prevents race-conditions when multiple
+        // concurrent tests perform `docker login` / `logout` by ensuring each
+        // Image operation has its own credential store.
+        const tempConfigDir = await fs.mkdtemp(
+          path.join(os.tmpdir(), "docker-config-"),
+        );
+        const api = new DockerApi({ configDir: tempConfigDir });
+
+        // Authenticate to registry using the isolated config directory
+        await api.login(registryHost, username, password.unencrypted);
+
+        // Tag local image with fully qualified name if necessary
+        if (targetImage !== imageRef) {
+          await api.exec(["tag", imageRef, targetImage]);
         }
-      }
 
-      return {
-        ...props,
-        name,
-        imageRef: finalImageRef,
-        imageId,
-        repoDigest,
-        builtAt: Date.now(),
-      };
+        // Push the image
+        const { stdout: pushOut } = await api.exec(["push", targetImage]);
+
+        // Attempt to extract the repo digest from push output
+        const digestMatch = /digest:\s+([a-z0-9]+:[a-f0-9]{64})/.exec(pushOut);
+        if (digestMatch) {
+          const digestHash = digestMatch[1];
+          // Strip tag (anything after last :) to build image@digest reference
+          const [repoWithoutTag] =
+            targetImage.split(":").length > 2
+              ? [targetImage] // unlikely but safety
+              : [targetImage.substring(0, targetImage.lastIndexOf(":"))];
+          repoDigest = `${repoWithoutTag}@${digestHash}`;
+        }
+
+        // Update the final image reference to point at the pushed image
+        finalImageRef = targetImage;
+      } finally {
+        // Clean up credentials from the isolated config
+        await api.logout(registryHost);
+      }
     }
+    return {
+      kind: "Image",
+      ...props,
+      tag,
+      name,
+      imageRef: finalImageRef,
+      imageId,
+      repoDigest,
+      builtAt: Date.now(),
+      build: props.build,
+    };
   },
 );

package/src/docker/remote-image.ts

@@ -26,6 +26,7 @@ export interface RemoteImageProps {
  * Docker Remote Image resource
  */
 export interface RemoteImage extends RemoteImageProps {
+  kind: "RemoteImage";
   /**
    * Full image reference (name:tag)
    */
@@ -71,8 +72,10 @@ export const RemoteImage = Resource(
       await api.pullImage(imageRef);
 
       return {
+        kind: "RemoteImage",
         ...props,
         imageRef,
+        tag,
         createdAt: Date.now(),
       };
     }

package/src/encrypt.ts

@@ -1,11 +1,122 @@
+import crypto from "node:crypto";
+
+const KEY_LEN = 32;
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SALT_LEN = 16;
+const IV_LEN = 12;
+const ALGO = "aes-256-gcm";
+
+interface Encrypted {
+  version: "v1";
+  ciphertext: string; // base64
+  iv: string; // base64
+  salt: string; // base64
+  tag: string; // base64
+}
+
+/**
+ * Decrypts a value encrypted with a symmetric key.
+ * For backwards compatibility, uses the legacy libsodium implementation if the value is a string.
+ * Otherwise, uses the AES-256-GCM implementation with scrypt key derivation.
+ */
+export function decryptWithKey(
+  value: string | Encrypted,
+  key: string,
+): Promise<string> {
+  if (typeof value === "string") {
+    return libsodiumDecrypt(value, key);
+  }
+  return aes256Decrypt(value, key);
+}
+
+/**
+ * Encrypt a value with a symmetric key using AES-256-GCM with scrypt key derivation.
+ */
+export async function encrypt(
+  value: string,
+  passphrase: string,
+): Promise<Encrypted> {
+  const salt = crypto.randomBytes(SALT_LEN);
+  const key = await deriveScryptKey(passphrase, salt);
+  const iv = crypto.randomBytes(IV_LEN);
+
+  const cipher = crypto.createCipheriv(ALGO, key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(value, "utf8"),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    version: "v1",
+    ciphertext: ciphertext.toString("base64"),
+    iv: iv.toString("base64"),
+    salt: salt.toString("base64"),
+    tag: tag.toString("base64"),
+  };
+}
+
+/**
+ * Decrypt a value encrypted with a symmetric key using AES-256-GCM with scrypt key derivation.
+ * @internal - Exposed for testing. Use `decryptWithKey` instead.
+ */
+export async function aes256Decrypt(
+  parts: Encrypted,
+  passphrase: string,
+): Promise<string> {
+  const salt = Buffer.from(parts.salt, "base64");
+  const iv = Buffer.from(parts.iv, "base64");
+  const ciphertext = Buffer.from(parts.ciphertext, "base64");
+  const tag = Buffer.from(parts.tag, "base64");
+
+  const key = await deriveScryptKey(passphrase, salt);
+
+  const decipher = crypto.createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+
+  const plaintext = Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final(),
+  ]);
+  return plaintext.toString("utf8");
+}
+
+async function deriveScryptKey(
+  passphrase: string,
+  salt: Buffer,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(
+      passphrase,
+      salt,
+      KEY_LEN,
+      {
+        N: SCRYPT_N,
+        r: SCRYPT_R,
+        p: SCRYPT_P,
+      },
+      (err, derivedKey) => {
+        if (err) reject(err);
+        else resolve(derivedKey);
+      },
+    );
+  });
+}
+
 /**
  * Encrypt a value with a symmetric key using libsodium
+ * @internal - Exposed to test backwards compatibility. Use `encrypt` instead.
  *
  * @param value - The value to encrypt
  * @param key - The encryption key
  * @returns The base64-encoded encrypted value with nonce
  */
-export async function encrypt(value: string, key: string): Promise<string> {
+export async function libsodiumEncrypt(
+  value: string,
+  key: string,
+): Promise<string> {
   const sodium = (await import("libsodium-wrappers")).default;
   // Initialize libsodium
   await sodium.ready;
@@ -35,13 +146,14 @@ export async function encrypt(value: string, key: string): Promise<string> {
 }
 
 /**
- * Decrypt a value encrypted with a symmetric key
+ * Decrypt a value encrypted with a symmetric key using libsodium.
+ * @internal - Exposed to test backwards compatibility. Use `decryptWithKey` instead.
  *
  * @param encryptedValue - The base64-encoded encrypted value with nonce
  * @param key - The decryption key
  * @returns The decrypted string
  */
-export async function decryptWithKey(
+export async function libsodiumDecrypt(
   encryptedValue: string,
   key: string,
 ): Promise<string> {

package/src/planetscale/role.ts

@@ -51,6 +51,12 @@ export interface RoleProps extends PlanetScaleProps {
    * @default true
    */
   delete?: boolean;
+
+  /**
+   * successor role
+   * @default postgres
+   */
+  successor?: string | Role;
 }
 
 /**
@@ -123,6 +129,11 @@ export interface Role extends Omit<RoleProps, "inheritedRoles"> {
    * The roles that this role inherits from.
    */
   inheritedRoles: InheritedRole[];
+
+  /**
+   * The successor role
+   */
+  successor: string;
 }
 
 /**
@@ -198,10 +209,18 @@ export const Role = Resource(
       : props.inheritedRoles.inheritedRoles;
     const shouldDelete = props.delete ?? false;
 
+    const successorRole =
+      typeof props.successor === "string"
+        ? props.successor
+        : (props.successor?.name ?? "postgres");
+
     switch (this.phase) {
       case "delete": {
         if (shouldDelete && this.output?.id) {
           const res = await api.deleteRole({
+            body: {
+              successor: successorRole,
+            },
             path: {
               organization,
               database,
@@ -275,6 +294,7 @@ export const Role = Resource(
           expiresAt: data.expires_at,
           databaseName: data.database_name,
           inheritedRoles,
+          successor: successorRole,
           connectionUrl: alchemy.secret(
             `postgresql://${data.username}:${data.password}@${data.access_host_url}:5432/${data.database_name}?sslmode=verify-full`,
           ),
@@ -284,9 +304,16 @@ export const Role = Resource(
         };
       }
       case "update": {
-        // According to the types, the only property that can be updated is the name.
-        // However, I was getting 500 errors when trying to update the name, so we'll just replace.
-        return this.replace();
+        if (successorRole !== this.output.successor) {
+          // According to the types, the only property that can be updated is the name.
+          // However, I was getting 500 errors when trying to update the name, so we'll just replace.
+          return this.replace();
+        } else {
+          return {
+            ...this.output,
+            successor: successorRole,
+          };
+        }
       }
     }
   },

package/src/prisma-postgres/api.ts

@@ -56,6 +56,7 @@ export function createPrismaApi(
       throwOnError: true,
       headers: {
         Authorization: `Bearer ${serviceToken}`,
+        "User-Agent": "alchemy/1.0",
       },
     }),
   );

package/src/scope.ts

@@ -1,4 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import fs from "node:fs/promises";
 import util from "node:util";
 import path from "pathe";
 import pc from "picocolors";
@@ -357,6 +360,30 @@ export class Scope {
     return result.extracted as any;
   }
 
+  public async exec(
+    id: string,
+    command: string,
+  ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+    const logFilePath = path.join(this.dotAlchemy, "logs", `${id}.log`);
+    const [cmd, ...args] = command.split(/\s+/);
+    const child = spawn(cmd, args, { stdio: "pipe" });
+    await once(child, "spawn"); // throws if command not found
+    await fs.mkdir(path.dirname(logFilePath), { recursive: true });
+    const logFile = await fs.open(logFilePath, "w");
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+      logFile.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+      logFile.write(chunk);
+    });
+    const [exitCode] = (await once(child, "exit")) as [number];
+    return { exitCode, stdout, stderr };
+  }
+
   /**
    * @internal
    */

package/src/serde.ts

@@ -183,7 +183,7 @@ export async function deserialize(
             "See: https://alchemy.run/concepts/secret/#encryption-password",
         );
       }
-      if (typeof value["@secret"] === "object") {
+      if (typeof value["@secret"] === "object" && "data" in value["@secret"]) {
         return new Secret(
           JSON.parse(
             await decryptWithKey(value["@secret"].data, scope.password),

package/src/util/telemetry.ts

@@ -354,6 +354,7 @@ async function fetchNoResponse(
     body?: string;
     headers?: Record<string, string>;
     method?: string;
+    timeout?: number;
   } = {},
 ) {
   const parsedUrl = new URL(url);
@@ -372,12 +373,16 @@ async function fetchNoResponse(
     path: parsedUrl.pathname + parsedUrl.search,
     method: options.method || "GET",
     headers,
+    signal: AbortSignal.timeout(options?.timeout ?? 3000),
   };
 
   await new Promise<void>((resolve, reject) => {
     const req = client.request(requestOptions);
 
     req.on("error", (error) => {
+      if (error.name === "AbortError" && !SUPPRESS_TELEMETRY_ERRORS) {
+        logger.warn("Telemetry request timed out");
+      }
       reject(error);
     });