@k2b/cloud 0.37.0 → 0.39.0

package/src/services/outgoing-mail/dispatcher.ts

@@ -12,7 +12,7 @@ import { allowedMailProfile, type MessageRow, messageAttachmentRefs, messageReco
 import { OutgoingMailError, resolveMailCredentials } from "./store";
 import { mailAttachments, mailSettled } from "./sync";
 import { smtpFailureMessage } from "./test-send";
-import { buildMailTransport } from "./transport";
+import { resolveMailTransport } from "./transport";
 
 export const cleanupMailAttachments = async (id: string): Promise<void> => {
   const row = await outgoingMailMessages.read(id);
@@ -136,7 +136,12 @@ export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal)
       socket.once("connect", () => {
         if (attempt.signal.aborted) socket.destroy();
       });
-      const transport = buildMailTransport(credentials, socket);
+      const resolved = await resolveMailTransport(credentials, attempt.signal).catch((error: unknown) => {
+        socket.destroy();
+        throw error;
+      });
+      // Nodemailer cannot fall back across IP literals; each queued retry rotates to the next checked address.
+      const transport = resolved.build(Math.max(0, row.attempt_count - 1), socket);
       const stop = () => {
         socket.destroy();
         transport.close();

package/src/services/outgoing-mail/resolve-host.ts

@@ -0,0 +1,39 @@
+import { env } from "../../config/env";
+import { networkAddressFamily, normalizeNetworkHostname, parseNetworkAllowlistEnv } from "../../shared/network-address";
+import { NetworkTargetBlockedError, resolveAllowedNetworkAddresses } from "../network-security";
+
+export const outgoingMailAllowlist = () => parseNetworkAllowlistEnv("OUTGOING_MAIL_ALLOWED_TARGETS", env.OUTGOING_MAIL_ALLOWED_TARGETS);
+
+/** One bounded lookup shared by SMTP and bounce IMAP; clients use only the checked addresses. */
+export const resolveMailHost = async (host: string, signal?: AbortSignal, resolve = resolveAllowedNetworkAddresses) => {
+  const hostname = normalizeNetworkHostname(host);
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new Error("Outgoing mail DNS lookup timed out.")), 5000);
+  const cancellation = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+  let abort: (() => void) | undefined;
+  try {
+    cancellation.throwIfAborted();
+    const addresses = await Promise.race([
+      resolve(hostname, outgoingMailAllowlist()),
+      new Promise<never>((_, reject) => {
+        abort = () => reject(cancellation.reason);
+        cancellation.addEventListener("abort", abort, { once: true });
+        if (cancellation.aborted) abort();
+      }),
+    ]);
+    return {
+      host: hostname,
+      addresses: [...addresses.filter((entry) => entry.family === 4), ...addresses.filter((entry) => entry.family === 6)],
+      servername: networkAddressFamily(hostname) ? undefined : hostname,
+    };
+  } catch (error) {
+    if (error instanceof NetworkTargetBlockedError)
+      throw new NetworkTargetBlockedError(
+        "Outgoing mail target is on an internal network. An operator can allow it with OUTGOING_MAIL_ALLOWED_TARGETS.",
+      );
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    if (abort) cancellation.removeEventListener("abort", abort);
+  }
+};

package/src/services/outgoing-mail/test-send.ts

@@ -1,7 +1,7 @@
 import { audit } from "../audit";
 import { get } from "../settings";
 import { type MailAuditContext, OutgoingMailError, resolveMailCredentials } from "./store";
-import { buildMailTransport } from "./transport";
+import { resolveMailTransport } from "./transport";
 
 export const smtpFailureMessage = (error: unknown, secrets: readonly (string | null)[]): string => {
   let message = error instanceof Error ? error.message : "SMTP delivery failed.";
@@ -17,8 +17,23 @@ export const outgoingMailTest = {
     const event = { ...context, action: "outgoing_mail.profile.test", target: { type: "outgoing_mail_profile", id: key } };
     // Fail before the external effect if audit storage is unavailable.
     await audit.record({ ...event, outcome: "allowed" });
-    const transport = buildMailTransport(profile);
+    let transport: ReturnType<Awaited<ReturnType<typeof resolveMailTransport>>["build"]> | undefined;
     try {
+      const resolved = await resolveMailTransport(profile);
+      for (let index = 0; index < resolved.count; index++) {
+        transport = resolved.build(index);
+        try {
+          // CONN also labels socket errors after DATA. Only fall back during a
+          // preflight that cannot send a message, then send once to that address.
+          await transport.verify();
+          break;
+        } catch (error) {
+          transport.close();
+          transport = undefined;
+          if (!(error instanceof Error) || !("command" in error) || error.command !== "CONN" || index === resolved.count - 1) throw error;
+        }
+      }
+      if (!transport) throw new Error("No validated SMTP address.");
       await transport.sendMail({
         from: { address: profile.fromAddress, name: profile.fromName ?? (await get<string>("app.name")) },
         to: recipient,
@@ -34,7 +49,7 @@ export const outgoingMailTest = {
       await audit.recordResultAfterSideEffect({ ...event, result: { ok: false, error: { code: "smtp_failed", message, status: 500 } } });
       throw new OutgoingMailError("smtp_failed", message, 502);
     } finally {
-      transport.close();
+      transport?.close();
     }
   },
 };

package/src/services/outgoing-mail/transport.ts

@@ -1,17 +1,28 @@
 import type { Socket } from "node:net";
 import { createTransport } from "nodemailer";
+import { resolveMailHost } from "./resolve-host";
 import type { resolveMailCredentials } from "./store";
 
-export const buildMailTransport = (profile: Awaited<ReturnType<typeof resolveMailCredentials>>, socket?: Socket) =>
-  createTransport({
-    // Workers own the raw socket so timeout/shutdown can destroy it. Nodemailer
-    // still owns SMTP and upgrades this socket for implicit TLS or STARTTLS.
-    ...(socket ? { socket } : {}),
-    host: profile.smtpHost,
-    port: profile.smtpPort,
-    secure: profile.smtpSecure,
-    ...(profile.smtpUser ? { auth: { user: profile.smtpUser, pass: profile.smtpPassword ?? "" } } : {}),
-    connectionTimeout: 10000,
-    greetingTimeout: 10000,
-    socketTimeout: 60000,
-  });
+export const resolveMailTransport = async (profile: Awaited<ReturnType<typeof resolveMailCredentials>>, signal?: AbortSignal) => {
+  const target = await resolveMailHost(profile.smtpHost, signal);
+  signal?.throwIfAborted();
+  const count = target.addresses.length;
+  return {
+    count,
+    build: (index: number, socket?: Socket) =>
+      createTransport({
+        // Workers own the raw socket so timeout/shutdown can destroy it. Nodemailer
+        // still owns SMTP and upgrades this socket for implicit TLS or STARTTLS.
+        ...(socket ? { socket } : {}),
+        host: target.addresses[Math.max(0, index) % count]!.address,
+        servername: target.servername,
+        tls: { servername: target.servername },
+        port: profile.smtpPort,
+        secure: profile.smtpSecure,
+        ...(profile.smtpUser ? { auth: { user: profile.smtpUser, pass: profile.smtpPassword ?? "" } } : {}),
+        connectionTimeout: 10000,
+        greetingTimeout: 10000,
+        socketTimeout: 60000,
+      }),
+  };
+};

package/src/services/pdf/image-protocol.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+
+/**
+ * Bun already reserves about 270..296 MiB of the 512 MiB data limit. A single 32 MiB input plus 64 MiB RGBA
+ * leaves about 120..146 MiB for codecs and temporary buffers. Notebooks defaults to 10 MB attachments.
+ */
+export const PDF_IMAGE_MAX_INPUT_BYTES = 32 * 1024 * 1024;
+/** Bound the number of encoders and the output envelope per call. */
+export const PDF_IMAGE_MAX_BOXES = 8;
+export const ImageBox = z.object({ width: z.number().int().min(1).max(16383), height: z.number().int().min(1).max(16383) });
+export const ImageRequest = z.object({
+  boxes: z.array(ImageBox).min(1).max(PDF_IMAGE_MAX_BOXES),
+  maxBytes: z.number().int().min(1).max(PDF_IMAGE_MAX_INPUT_BYTES),
+  // 240 s is the request idle-timeout ceiling; 30 s matches the PDF page decoder.
+  timeoutMs: z.number().int().min(1).max(240_000).default(30_000),
+});
+export const ImageErrorCode = z.enum(["unsupported_format", "unreadable", "too_large", "timed_out"]);
+export const ImageVariantHeader = z.object({
+  type: z.enum(["image/jpeg", "image/png"]),
+  width: z.number().int().min(1).max(16383),
+  height: z.number().int().min(1).max(16383),
+  bytes: z.number().int().min(1).max(PDF_IMAGE_MAX_INPUT_BYTES),
+});
+export const ImageResponse = z.discriminatedUnion("ok", [
+  z.strictObject({ ok: z.literal(true) }),
+  z.strictObject({ ok: z.literal(false), code: ImageErrorCode }),
+]);
+
+const ImageFrameHeader = ImageRequest.extend({ bytes: z.number().int().min(0).max(PDF_IMAGE_MAX_INPUT_BYTES) });
+
+const ImageRecord = z.union([ImageVariantHeader.extend({ index: z.number().int().min(0) }).strict(), ImageResponse]);
+type ImageVariant = { data: Blob; type: "image/jpeg" | "image/png"; width: number; height: number };
+
+/** Read bounded variant records and their exact bodies, followed by one final status and EOF. */
+export async function readImageRecords(
+  stream: ReadableStream<Uint8Array>,
+  request: Pick<z.infer<typeof ImageRequest>, "boxes" | "maxBytes">,
+) {
+  const reader = stream.getReader();
+  let chunk: Uint8Array = new Uint8Array();
+  let offset = 0;
+  const more = async () => {
+    while (offset === chunk.byteLength) {
+      const { done, value } = await reader.read();
+      if (done) return false;
+      chunk = value;
+      offset = 0;
+    }
+    return true;
+  };
+  const variants: (ImageVariant | null)[] = request.boxes.map(() => null);
+  let count = 0;
+  let total = 0;
+  try {
+    for (;;) {
+      const line: Uint8Array[] = [];
+      let length = 0;
+      for (;;) {
+        if (!(await more())) throw new Error("Missing image record.");
+        const newline = chunk.indexOf(10, offset);
+        const end = newline < 0 ? chunk.byteLength : newline;
+        length += end - offset;
+        if (length > 4096) throw new Error("Image record exceeds 4 KiB.");
+        line.push(chunk.subarray(offset, end));
+        offset = end + (newline < 0 ? 0 : 1);
+        if (newline >= 0) break;
+      }
+      const record = ImageRecord.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(line, length))));
+      if ("ok" in record) {
+        if (await more()) throw new Error("Unexpected data after final image record.");
+        return record.ok ? { ok: true as const, variants } : record;
+      }
+      const box = request.boxes[record.index];
+      total += record.bytes;
+      if (
+        ++count > request.boxes.length ||
+        !box ||
+        variants[record.index] !== null ||
+        record.bytes > request.maxBytes ||
+        record.width > box.width ||
+        record.height > box.height ||
+        total > request.boxes.length * request.maxBytes
+      ) {
+        throw new Error("Image variant exceeds its bounds or repeats an index.");
+      }
+      const body = new Uint8Array(record.bytes);
+      let written = 0;
+      while (written < body.byteLength) {
+        if (!(await more())) throw new Error("Truncated image variant.");
+        const size = Math.min(body.byteLength - written, chunk.byteLength - offset);
+        body.set(chunk.subarray(offset, offset + size), written);
+        written += size;
+        offset += size;
+      }
+      variants[record.index] = {
+        data: new Blob([body], { type: record.type }),
+        type: record.type,
+        width: record.width,
+        height: record.height,
+      };
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => {});
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Read a 4 KiB JSON header, then fill one allocation of exactly the declared input length. */
+export function readImageFrame(read: (buffer: Uint8Array, offset: number, length: number) => number) {
+  // Async stdin chunks made worker memory nondeterministic under its data limit, so read synchronously.
+  const headerBuffer = new Uint8Array(4097);
+  let headerBytes = 0;
+  let newline = -1;
+  while (newline < 0) {
+    const size = read(headerBuffer, headerBytes, headerBuffer.byteLength - headerBytes);
+    if (size === 0) throw new Error("Missing image frame header.");
+    newline = headerBuffer.subarray(0, headerBytes + size).indexOf(10, headerBytes);
+    headerBytes += size;
+    if (newline < 0 && headerBytes === headerBuffer.byteLength) throw new Error("Image frame header exceeds its limit.");
+  }
+  const header = ImageFrameHeader.parse(JSON.parse(Buffer.from(headerBuffer.buffer, 0, newline).toString("utf8")));
+  const body = new Uint8Array(header.bytes);
+  let bodyBytes = headerBytes - newline - 1;
+  if (bodyBytes > body.byteLength) throw new Error("Image frame body exceeds its declared length.");
+  body.set(headerBuffer.subarray(newline + 1, headerBytes));
+  while (bodyBytes < body.byteLength) {
+    const size = read(body, bodyBytes, body.byteLength - bodyBytes);
+    if (size === 0) throw new Error("Truncated image frame body.");
+    bodyBytes += size;
+  }
+  if (read(headerBuffer, 0, 1) !== 0) throw new Error("Image frame body exceeds its declared length.");
+  return { header, body };
+}

package/src/services/pdf/image-variants.ts

@@ -0,0 +1,124 @@
+import sharp from "sharp";
+import type { z } from "zod";
+import type { ImageRequest, ImageResponse, ImageVariantHeader } from "./image-protocol";
+
+sharp.concurrency(1);
+sharp.cache(false);
+
+/**
+ * 16 MiP is 64 MiB RGBA; A4 at 300 dpi needs about 5.8 MP. With 270..296 MiB for Bun and 32 MiB for input,
+ * about 120..146 MiB of the 512 MiB limit remains for codecs and temporary buffers. Some source decodes need more.
+ */
+const MAX_DECODED_PIXELS = 16 * 1024 * 1024;
+const MAX_SOURCE_PIXELS = 268402689; // sharp's unchanged default limitInputPixels.
+// Measured RGBA WebP peaks are non-monotonic: 440..473 MiB at 16 MiP, 476..495 at 24 MiP, 429..457 at 32 MiP.
+// Cap full-image decoders at 16 MiP to leave about 40 MiB below the worker's 512 MiB data limit.
+const MAX_FULL_DECODE_SOURCE_PIXELS = 16 * 1024 * 1024;
+
+const fit = (width: number, height: number, box: { width: number; height: number }) => {
+  const scale = Math.min(1, box.width / width, box.height / height);
+  return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+};
+
+/** Worker-only: validate pass-throughs, decode once for resized variants, then emit encodings sequentially. */
+export async function prepareImageVariants(
+  source: Uint8Array | undefined,
+  request: z.infer<typeof ImageRequest>,
+  write: (index: number, header: z.infer<typeof ImageVariantHeader>, bytes: Uint8Array) => Promise<void>,
+): Promise<z.infer<typeof ImageResponse>> {
+  let identified = false;
+  try {
+    const metadata = await sharp(source).metadata();
+    identified = true;
+    if (
+      !["jpeg", "png", "webp", "gif", "tiff"].includes(metadata.format) &&
+      !(metadata.format === "heif" && metadata.compression === "av1")
+    ) {
+      return { ok: false, code: "unsupported_format" };
+    }
+    const width = metadata.width;
+    const height = metadata.pageHeight ?? metadata.height;
+    if (width * height > MAX_SOURCE_PIXELS) return { ok: false, code: "too_large" };
+    if (["webp", "gif", "tiff", "heif"].includes(metadata.format) && width * height > MAX_FULL_DECODE_SOURCE_PIXELS) {
+      return { ok: false, code: "too_large" };
+    }
+    const rotated = (metadata.orientation ?? 1) >= 5;
+    const upright = { width: rotated ? height : width, height: rotated ? width : height };
+    const sizes = request.boxes.map((box) => fit(upright.width, upright.height, box));
+    const passthrough = request.boxes.map(
+      (box) =>
+        metadata.format === "jpeg" &&
+        (metadata.orientation === undefined || metadata.orientation === 1) &&
+        (metadata.space === "srgb" || metadata.space === "b-w") &&
+        // `space` describes the pixels, not the profile: a Display P3 or Adobe RGB JPEG also reports srgb.
+        !metadata.hasProfile &&
+        width <= box.width &&
+        height <= box.height &&
+        source!.byteLength <= request.maxBytes,
+    );
+    // Metadata alone accepts truncated JPEGs. Validate once with default failOn before emitting any unchanged bytes.
+    if (passthrough.some(Boolean)) await sharp(source).resize(8, 8, { fit: "inside" }).toBuffer();
+    for (let index = 0; index < sizes.length; index++) {
+      if (!passthrough[index]) continue;
+      await write(index, { type: "image/jpeg", width, height, bytes: source!.byteLength }, source!);
+    }
+    const needed = sizes.flatMap((_, index) => (passthrough[index] ? [] : [index]));
+    if (!needed.length) return { ok: true };
+    const largestIndex = needed.reduce((a, b) => (sizes[a]!.width * sizes[a]!.height >= sizes[b]!.width * sizes[b]!.height ? a : b));
+    const largest = sizes[largestIndex]!;
+    if (largest.width * largest.height > MAX_DECODED_PIXELS) return { ok: false, code: "too_large" };
+    const decoded = await sharp(source)
+      // Fit the original box once: fitting already rounded dimensions can shrink an extra pixel.
+      .resize({ ...request.boxes[largestIndex]!, fit: "inside", withoutEnlargement: true })
+      // autoOrient before resize disables shrink-on-load.
+      .autoOrient()
+      .toColourspace("srgb")
+      .raw({ depth: "uchar" })
+      .toBuffer({ resolveWithObject: true });
+    source = undefined;
+    const { data, info } = decoded;
+    let transparent = false;
+    if (info.channels === 2 || info.channels === 4) {
+      for (let offset = info.channels - 1; offset < data.length; offset += info.channels) {
+        if (data[offset] !== 255) {
+          transparent = true;
+          break;
+        }
+      }
+    }
+    for (let index = 0; index < sizes.length; index++) {
+      if (passthrough[index]) continue;
+      const size = sizes[index]!;
+      let image = sharp(data, { raw: { width: info.width, height: info.height, channels: info.channels } });
+      if (size.width !== info.width || size.height !== info.height) image = image.resize(size.width, size.height, { fit: "fill" });
+      const type = transparent ? "image/png" : "image/jpeg";
+      let encoded: Buffer | undefined = await (transparent
+        ? image.png()
+        : image.removeAlpha().jpeg({ quality: 85, mozjpeg: true })
+      ).toBuffer();
+      if (encoded.byteLength <= request.maxBytes) {
+        await write(index, { ...size, type, bytes: encoded.byteLength }, encoded);
+      }
+      encoded = undefined;
+    }
+    return { ok: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    // Codec allocation errors can also mention a corrupt header or unsupported format. Memory takes precedence.
+    // Thread stacks count against the data limit.
+    // Unidentified byte streams are unreadable; a recognized but missing codec is unsupported.
+    const code = [
+      "out of memory",
+      "insufficient memory",
+      "memory allocation",
+      "cannot allocate",
+      "pixel limit",
+      "error creating thread",
+    ].some((part) => message.includes(part))
+      ? "too_large"
+      : (identified && message.includes("unsupported image format")) || message.includes("compression format has not been built in")
+        ? "unsupported_format"
+        : "unreadable";
+    return { ok: false, code };
+  }
+}

package/src/services/pdf/image-worker.ts

@@ -0,0 +1,31 @@
+// Standalone subprocess. No server imports or application credentials.
+import { readSync } from "node:fs";
+import { readImageFrame } from "./image-protocol";
+import { prepareImageVariants } from "./image-variants";
+
+const write = (chunk: string | Uint8Array) =>
+  new Promise<void>((resolve, reject) => {
+    process.stdout.write(chunk, (error) => (error ? reject(error) : resolve()));
+  });
+// Timers bound processing. During blocking stdin reads, a crashed parent closes the pipe;
+// a live parent enforces its deadline with SIGKILL.
+const expire = () => process.exit(1);
+let timer = setTimeout(expire, 240_000);
+try {
+  let frame: ReturnType<typeof readImageFrame> | undefined = readImageFrame((buffer, offset, length) =>
+    readSync(0, buffer, offset, length, null),
+  );
+  const request = frame.header;
+  clearTimeout(timer);
+  timer = setTimeout(expire, request.timeoutMs);
+  const pending = prepareImageVariants(frame.body, request, async (index, header, bytes) => {
+    await write(`${JSON.stringify({ index, ...header })}\n`);
+    await write(bytes);
+  });
+  frame = undefined;
+  await write(`${JSON.stringify(await pending)}\n`);
+} catch {
+  await write(`${JSON.stringify({ ok: false, code: "unreadable" })}\n`).catch(() => {});
+} finally {
+  clearTimeout(timer);
+}

package/src/services/pdf/image.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { spawnCanvasWorker } from "../../_internal/canvas-worker";
+import { type ImageBox, type ImageErrorCode, ImageRequest, PDF_IMAGE_MAX_INPUT_BYTES, readImageRecords } from "./image-protocol";
+
+export { PDF_IMAGE_MAX_BOXES, PDF_IMAGE_MAX_INPUT_BYTES } from "./image-protocol";
+/** Integer pixels, 1..16383 per side: a square stays within sharp's default input pixel limit. */
+export type PdfImageBox = z.infer<typeof ImageBox>;
+export type PdfImageVariant = { data: Blob; type: "image/jpeg" | "image/png"; width: number; height: number };
+export type PdfImageErrorCode = z.infer<typeof ImageErrorCode>;
+export type PreparePdfImageInput = { data: Uint8Array | Blob; boxes: PdfImageBox[]; maxBytes: number };
+/** The deadline includes queue time. Default 30 s matches PDF page decoding; 240 s is the request idle-timeout ceiling. */
+export type PreparePdfImageOptions = { signal?: AbortSignal; timeoutMs?: number };
+export type PreparePdfImageResult = { ok: true; variants: (PdfImageVariant | null)[] } | { ok: false; code: PdfImageErrorCode };
+
+declare const __CLOUD_PDF_IMAGE_WORKER__: string | undefined;
+let activeWorkers = 0;
+const waiting: (() => void)[] = [];
+
+async function acquire(signal: AbortSignal) {
+  if (signal.aborted) return false;
+  if (activeWorkers < 2) {
+    activeWorkers++;
+    return true;
+  }
+  return new Promise<boolean>((resolve) => {
+    const abort = () => {
+      waiting.splice(waiting.indexOf(start), 1);
+      resolve(false);
+    };
+    const start = () => {
+      signal.removeEventListener("abort", abort);
+      resolve(true);
+    };
+    waiting.push(start);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function release() {
+  const next = waiting.shift();
+  if (next) next();
+  else activeWorkers--;
+}
+
+/**
+ * Fit raw image bytes into 1..8 pixel boxes, without enlargement, in one isolated Linux worker (at most two at once).
+ * Opaque images use sRGB JPEG q85; transparency uses PNG. Fitting upright sRGB JPEGs pass through unchanged after a validation decode.
+ * Results follow box order; null means that encoding exceeded maxBytes. Invalid arguments throw; image failures return codes.
+ * Input is capped at 32 MiB; the largest decoded variant at 16 MiP (64 MiB RGBA, versus about 5.8 MP for A4 at 300 dpi).
+ * WebP, GIF, TIFF and AVIF sources are capped at 16 MiP (about 16.8 MP).
+ * Bun itself uses about half the 512 MiB data limit; decodes that exhaust the remaining memory return too_large.
+ */
+export async function preparePdfImage(input: PreparePdfImageInput, options: PreparePdfImageOptions = {}): Promise<PreparePdfImageResult> {
+  const request = ImageRequest.parse({ boxes: input.boxes, maxBytes: input.maxBytes, timeoutMs: options.timeoutMs });
+  const inputData = z.union([z.instanceof(Uint8Array), z.instanceof(Blob)]).parse(input.data);
+  if (process.platform !== "linux") throw new Error("PDF image preparation requires the Linux Cloud runtime with memory isolation.");
+  if (options.signal?.aborted) return { ok: false, code: "timed_out" };
+  if ((input.data instanceof Blob ? input.data.size : input.data.byteLength) > PDF_IMAGE_MAX_INPUT_BYTES) {
+    return { ok: false, code: "too_large" };
+  }
+  const deadline = Date.now() + request.timeoutMs;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), request.timeoutMs);
+  const signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+  let acquired = false;
+  try {
+    acquired = await acquire(signal);
+    if (!acquired || signal.aborted || Date.now() >= deadline) return { ok: false, code: "timed_out" };
+    const worker =
+      typeof __CLOUD_PDF_IMAGE_WORKER__ === "string"
+        ? new URL(__CLOUD_PDF_IMAGE_WORKER__, import.meta.url)
+        : new URL("./image-worker.ts", import.meta.url);
+    // Bun's file-backed Blobs must be materialized before composing a multipart Blob. A slow read must not keep the
+    // slot past the deadline, so the abort settles the wait while the read finishes on its own.
+    const data =
+      inputData instanceof Blob
+        ? new Uint8Array(
+            await new Promise<ArrayBuffer>((resolve, reject) => {
+              signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+              inputData.arrayBuffer().then(resolve, reject);
+            }),
+          )
+        : inputData;
+    if (signal.aborted || Date.now() >= deadline) return { ok: false, code: "timed_out" };
+    if (data.byteLength > PDF_IMAGE_MAX_INPUT_BYTES) return { ok: false, code: "too_large" };
+    const header = `${JSON.stringify({ ...request, bytes: data.byteLength, timeoutMs: Math.max(1, deadline - Date.now()) })}\n`;
+    const child = spawnCanvasWorker(worker, "pdf-image", new Blob([header, data]));
+    const stop = () => child.kill("SIGKILL");
+    signal.addEventListener("abort", stop, { once: true });
+    if (signal.aborted) stop();
+    try {
+      const result = await readImageRecords(child.stdout, request);
+      if (signal.aborted || Date.now() >= deadline) return { ok: false, code: "timed_out" };
+      const exitCode = await child.exited;
+      if (signal.aborted || Date.now() >= deadline) return { ok: false, code: "timed_out" };
+      if (exitCode !== 0) return { ok: false, code: "unreadable" };
+      return result;
+    } finally {
+      signal.removeEventListener("abort", stop);
+      stop();
+      await child.exited;
+    }
+  } catch {
+    return { ok: false, code: signal.aborted || Date.now() >= deadline ? "timed_out" : "unreadable" };
+  } finally {
+    clearTimeout(timer);
+    if (acquired) release();
+  }
+}

package/src/services/pdf/index.ts

@@ -21,6 +21,15 @@ export {
   renderHtmlToPdfWithConfig,
   testGotenberg,
 } from "./gotenberg";
+export type {
+  PdfImageBox,
+  PdfImageErrorCode,
+  PdfImageVariant,
+  PreparePdfImageInput,
+  PreparePdfImageOptions,
+  PreparePdfImageResult,
+} from "./image";
+export { PDF_IMAGE_MAX_BOXES, PDF_IMAGE_MAX_INPUT_BYTES, preparePdfImage } from "./image";
 export type {
   BuildPresetPdfHtmlInput,
   MarkdownPdfErrorCode,

package/src/services/settings/api.ts

@@ -12,13 +12,14 @@
  *     `services/weather/forecast.ts`, OpenAPI middleware, cron callbacks).
  *     Loosely typed (caller provides the value type via the `T` generic).
  *
- * Backend: cache-aside via `store.ts` (Redis 5min TTL + DB fallback). All
- * functions are async — sync render-time access uses the per-request snapshot
+ * Backend: value reads use cache-aside via `store.ts` (Redis 5min TTL + DB
+ * fallback); stored-state reads use Postgres. All functions are async — sync
+ * render-time access uses the per-request snapshot
  * exposed via `c.get("settings")`.
  */
 
 import type { AppSettingsMap, KindToType } from "../../contracts/settings-types";
-import { deleteKey, readKey, writeKey } from "./store";
+import { deleteKey, readKey, readKeyState, type StoredSettingState, writeKey } from "./store";
 
 /**
  * Per-app typed settings API. Keys constrained to those declared in the
@@ -26,7 +27,8 @@ import { deleteKey, readKey, writeKey } from "./store";
  */
 export interface SettingsAPI<F extends Record<string, unknown>> {
   get<K extends keyof F & string>(key: K): Promise<F[K]>;
-  set<K extends keyof F & string>(key: K, value: F[K]): Promise<void>;
+  read<K extends keyof F & string>(key: K): Promise<{ value: F[K]; stored: StoredSettingState }>;
+  set<K extends keyof F & string>(key: K, value: F[K], options?: { replaceUnreadable?: boolean }): Promise<void>;
   remove<K extends keyof F & string>(key: K): Promise<void>;
 }
 
@@ -40,7 +42,8 @@ export const createSettingsAPI = <S extends AppSettingsMap>(): SettingsAPI<{
   [K in keyof S]: KindToType<S[K]["kind"]>;
 }> => ({
   get: async (key) => readKey(key) as never,
-  set: async (key, value) => writeKey(key, value),
+  read: async (key) => readKeyState(key) as never,
+  set: async (key, value, options) => writeKey(key, value, undefined, options),
   remove: async (key) => deleteKey(key),
 });
 
@@ -56,6 +59,8 @@ export const createSettingsAPI = <S extends AppSettingsMap>(): SettingsAPI<{
  */
 export const coreSettings = {
   get: <T = unknown>(key: string): Promise<T> => readKey(key) as Promise<T>,
-  set: (key: string, value: unknown): Promise<void> => writeKey(key, value),
+  read: <T = unknown>(key: string): Promise<{ value: T; stored: StoredSettingState }> =>
+    readKeyState(key) as Promise<{ value: T; stored: StoredSettingState }>,
+  set: (key: string, value: unknown, options?: { replaceUnreadable?: boolean }): Promise<void> => writeKey(key, value, undefined, options),
   remove: (key: string): Promise<void> => deleteKey(key),
 };

package/src/services/settings/app.ts

@@ -13,6 +13,7 @@ import { ImageMetadataError } from "../image-metadata";
 import type { SettingEntry } from ".";
 import * as settingsPrimitives from ".";
 import { SETTINGS_MAP, validateSettingValue } from "./defaults";
+import { SettingUnreadableError } from "./store";
 
 /**
  * Redact secret-kind setting values before they leave the server.
@@ -54,7 +55,7 @@ export const settingsService = {
 
       return paginateItems(filtered, config?.pagination);
     },
-    update: async (config: { key: string; value: unknown }) => {
+    update: async (config: { key: string; value: unknown; replaceUnreadable?: boolean }) => {
       if (!SETTINGS_MAP.has(config.key)) {
         return fail(err.badInput(`Unknown setting: ${config.key}`));
       }
@@ -64,11 +65,11 @@ export const settingsService = {
         return fail(err.badInput(validated.error));
       }
       try {
-        await settingsPrimitives.set(config.key, validated.value);
+        await settingsPrimitives.set(config.key, validated.value, undefined, { replaceUnreadable: config.replaceUnreadable });
         return ok(undefined);
       } catch (error) {
-        // A Result cannot carry 422; the typed HTTPException keeps its status through Hono.
-        if (error instanceof ImageMetadataError) throw error;
+        // Preserve the typed HTTP status and recovery code through Hono.
+        if (error instanceof ImageMetadataError || error instanceof SettingUnreadableError) throw error;
         const message = error instanceof Error ? error.message : String(error);
         if (message.startsWith("Unknown setting:")) {
           return fail(err.badInput(message));