@specific.dev/spectest 0.129.0 → 0.130.0

package/dist/components/s3-runtime/README.md

@@ -0,0 +1,33 @@
+# Native S3 component runtime
+
+GoFakeS3 is pinned by `go.mod`/`go.sum`. `s3.ts` embeds these assets into a constant
+multi-stage Dockerfile, builds for the worker's native architecture, and ships
+only the static binary and dependency licenses. The Go builder is pinned to a
+multi-architecture digest. No project files or options enter the image build.
+
+The entrypoint retains the component's port 9090, path-style addressing, no
+automatic buckets, no signature/date validation, and permissive browser CORS.
+The memory backend supports pagination and versioning. Full VM snapshots clone
+its buckets, versions and pending multipart uploads; restarting the process
+starts empty, matching S3Mock's default temporary store.
+
+`metadata.patch` preserves Cache-Control, Content-Language and Expires on object
+uploads, multipart initiation and copies. Upstream currently drops these headers
+in `metadataHeaders`. The patch applies to the vendored, checksum-verified module;
+a failed patch stops the build. Recheck it when changing the upstream pin.
+
+From `sdk`, run the real-image contract on a Linux Docker host:
+
+```
+SPECTEST_TEST_S3_DOCKER=1 bun test src/components/s3-docker.test.ts
+SPECTEST_TEST_S3_DOCKER=1 SPECTEST_TEST_S3_BASELINE=1 bun test src/components/s3-docker.test.ts
+bun test src/components/s3.test.ts src/components/internal-fetch.test.ts
+bun run build
+```
+
+The baseline uses S3Mock 5.1.0. The contract covers helpers and recording, setup,
+credentials, HTTPS with preserved Host, browser CORS, unsigned/stale signatures,
+metadata, copy/range requests, multipart, paginated listing, versioning, and
+fresh-process lifecycle. It does not prove every S3 API is interchangeable:
+GoFakeS3 lacks some S3Mock features, including tagging, lifecycle and retention.
+Java/Spring/S3Mock-specific environment settings are no longer interpreted.

package/dist/components/s3-runtime/go.mod

@@ -0,0 +1,11 @@
+module spectest-s3
+
+go 1.24
+
+require github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153
+
+require (
+	github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46 // indirect
+	go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d // indirect
+	golang.org/x/tools v0.8.0 // indirect
+)

package/dist/components/s3-runtime/go.sum

@@ -0,0 +1,54 @@
+github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
+github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.67 h1:9KxtdcIA/5xPNQyZRgUSpYOE6j9Bc4+D7nZua0KGYOM=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.67/go.mod h1:p3C44m+cfnbv763s52gCqrjaqyPikj9Sg47kUVaNZQQ=
+github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.75 h1:S61/E3N01oral6B3y9hZ2E1iFDqCZPPOBoBQretCnBI=
+github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.75/go.mod h1:bDMQbkI1vJbNjnvJYpPTSNYBkI/VIv18ngWb/K84tkk=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22 h1:rWyie/PxDRIdhNf4DzRk0lvjVOqFJuNnO8WwaIRVxzQ=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22/go.mod h1:zd/JsJ4P7oGfUhXn1VyLqaRZwPmZwg44Jf2dS84Dm3Y=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13 h1:JRaIgADQS/U6uXDqlPiefP32yXTda7Kqfx+LgspooZM=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13/go.mod h1:CEuVn5WqOMilYl+tbccq8+N2ieCy0gVn3OtRb0vBNNM=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21 h1:ZlvrNcHSFFWURB8avufQq9gFsheUgjVD9536obIknfM=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21/go.mod h1:cv3TNhVrssKR0O/xxLJVRfd2oazSnZnkUeTf6ctUwfQ=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3 h1:HwxWTbTrIHm5qY+CAEur0s/figc3qwvLWsNkF4RPToo=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3/go.mod h1:uoA43SdFwacedBfSgfFSjjCvYe8aYBS7EnU5GZ/YKMM=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/cevatbarisyilmaz/ara v0.0.4 h1:SGH10hXpBJhhTlObuZzTuFn1rrdmjQImITXnZVPSodc=
+github.com/cevatbarisyilmaz/ara v0.0.4/go.mod h1:BfFOxnUd6Mj6xmcvRxHN3Sr21Z1T3U2MYkYOmoQe4Ts=
+github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153 h1:ZaLBZJfUnKBlrPu0AX0T/i1N9BNU54j8sl9mCLzmpI0=
+github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153/go.mod h1:UHhRZRod9rENGFrUWTYnQHZqlNgSmjOq8DaD/ATQYRM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46 h1:GHRpF1pTW19a8tTFrMLUcfWwyC0pnifVo2ClaLq+hP8=
+github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46/go.mod h1:uAQ5PCi+MFsC7HjREoAz1BU+Mq60+05gifQSsHSDG/8=
+github.com/spf13/afero v1.2.1 h1:qgMbHoJbPbw579P+1zVY+6n4nIFuIchaIjzZ/I/Yq8M=
+github.com/spf13/afero v1.2.1/go.mod h1:9ZxEEn6pIJ8Rxe320qSDBk6AsU0r9pR7Q4OcevTdifk=
+github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+go.etcd.io/bbolt v1.3.5 h1:XAzx9gjCb0Rxj7EoqcClPD1d5ZBxZJk0jbuoPHenBt0=
+go.etcd.io/bbolt v1.3.5/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
+go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d h1:Ns9kd1Rwzw7t0BR8XMphenji4SmIoNZPn8zhYmaVKP8=
+go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d/go.mod h1:92Uoe3l++MlthCm+koNi0tcUCX3anayogF0Pa/sp24k=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.9.0 h1:2sjJmO8cDvYveuX97RDLsxlyUxLl+GHoLxBiRdHllBE=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
+golang.org/x/tools v0.8.0 h1:vSDcovVPld282ceKgDimkRSC8kpaH1dgyc9UMzlt84Y=
+golang.org/x/tools v0.8.0/go.mod h1:JxBZ99ISMI5ViVkT1tr6tdNmXeTrcpVSD3vZ1RsRdN4=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce h1:xcEWjVhvbDy+nHP67nPDDpbYrY+ILlfndk4bRioVHaU=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce/go.mod h1:yeKp02qBN3iKW1OzL3MGk2IdtZzaj7SFntXj72NppTA=
+gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

package/dist/components/s3-runtime/main.go

@@ -0,0 +1,77 @@
+// The component's native entrypoint. Keep its defaults compatible with S3Mock;
+// the upstream CLI enforces clock skew and has different browser CORS defaults.
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/johannesboyne/gofakes3"
+	"github.com/johannesboyne/gofakes3/backend/s3mem"
+)
+
+func main() {
+	// VM snapshots include RAM: buckets, versions and in-flight multipart state
+	// fork together. A fresh process starts empty, as S3Mock did by default.
+	// Unlike the Bolt backend, s3mem also supports bucket versioning.
+	backend := s3mem.New()
+	server := gofakes3.New(backend,
+		gofakes3.WithTimeSkewLimit(0), // S3Mock accepts arbitrary/expired signatures.
+		gofakes3.WithHostBucket(false),
+		gofakes3.WithAutoBucket(false),
+		gofakes3.WithLogger(gofakes3.GlobalLog()),
+	).Server()
+	log.Fatal(http.ListenAndServe(":9090", cors(server)))
+}
+
+// Preserve S3Mock's permissive browser uploads, including arbitrary metadata
+// headers. GoFakeS3's default allow-list rejects custom x-amz-meta-* headers and
+// only exposes ETag on preflights, hiding it from actual browser responses.
+func cors(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		origin := r.Header.Get("Origin")
+		w.Header().Add("Vary", "Origin")
+		w.Header().Add("Vary", "Access-Control-Request-Method")
+		w.Header().Add("Vary", "Access-Control-Request-Headers")
+		if origin != "" && r.Method == "OPTIONS" && r.Header.Get("Access-Control-Request-Method") != "" {
+			w.Header().Set("Access-Control-Allow-Origin", origin)
+			w.Header().Set("Access-Control-Allow-Credentials", "true")
+			w.Header().Set("Access-Control-Allow-Methods", r.Header.Get("Access-Control-Request-Method"))
+			w.Header().Set("Access-Control-Allow-Headers", r.Header.Get("Access-Control-Request-Headers"))
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		writer := &corsWriter{ResponseWriter: w, hasOrigin: origin != ""}
+		next.ServeHTTP(writer, r)
+		if !writer.written {
+			writer.WriteHeader(http.StatusOK)
+		}
+	})
+}
+
+type corsWriter struct {
+	http.ResponseWriter
+	hasOrigin bool
+	written   bool
+}
+
+func (w *corsWriter) WriteHeader(status int) {
+	if w.written {
+		return
+	}
+	w.written = true
+	if w.hasOrigin {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Expose-Headers", "*")
+	} else {
+		w.Header().Del("Access-Control-Allow-Origin")
+	}
+	w.ResponseWriter.WriteHeader(status)
+}
+
+func (w *corsWriter) Write(body []byte) (int, error) {
+	if !w.written {
+		w.WriteHeader(http.StatusOK)
+	}
+	return w.ResponseWriter.Write(body)
+}

package/dist/components/s3-runtime/metadata.patch

@@ -0,0 +1,12 @@
+--- a/vendor/github.com/johannesboyne/gofakes3/gofakes3.go
++++ b/vendor/github.com/johannesboyne/gofakes3/gofakes3.go
+@@ -1191,6 +1191,9 @@
+ 	for hk, hv := range headers {
+ 		if strings.HasPrefix(hk, "X-Amz-") ||
+ 			hk == "Content-Type" ||
++			hk == "Cache-Control" ||
++			hk == "Content-Language" ||
++			hk == "Expires" ||
+ 			hk == "Content-Disposition" ||
+ 			hk == "Content-Encoding" {
+ 			meta[hk] = hv[0]

package/dist/components/s3.d.ts

@@ -1,8 +1,7 @@
 import { type S3ClientLike } from "../s3.js";
 export interface S3Options {
     /**
-     * Buckets to create on first boot. The backing server's own `initialBuckets`
-     * env is unreliable across versions, so the component creates them in `setup`
+     * Buckets to create on first boot. The component creates them in `setup`
      * (a plain CreateBucket `PUT`) — captured into the warm snapshot, never
      * re-run on warm starts/forks.
      */
@@ -42,7 +41,7 @@ export interface S3Helpers {
 }
 /**
  * A ready-to-use, S3-compatible object store (backed by
- * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * [GoFakeS3](https://github.com/johannesboyne/gofakes3)), with an instrumented S3
  * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
  *
  * ```ts
@@ -90,8 +89,8 @@ export declare function s3(opts?: S3Options): {
     }[] | undefined;
     env?: Record<string, string> | undefined;
     image: {
-        type: "registry";
-        reference: string;
+        type: "dockerfile";
+        content: string;
     };
     ports: number[];
 };

package/dist/components/s3.js

@@ -1,21 +1,31 @@
+import { readFileSync } from "node:fs";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { S3Client } from "../s3.js";
-// Backing image, pinned internally (not user-configurable). adobe/s3mock 5.1.0
-// is the current release; avoid exactly 5.0.0, which crashed at startup on
-// Java 25 (`NoClassDefFoundError: KotlinBuiltIns$2`) — fixed in 5.1.0.
-const S3_IMAGE = "adobe/s3mock:5.1.0";
-// Port the store listens on, fixed like the image and deliberately NOT an
-// option. The backing server's HTTP port is baked into the image, and nothing
-// the component returns can move it — so a `port` option could only relabel
-// the ready check, the declared ports and the client endpoint while the
-// container kept listening here. That is exactly what it did until 0.78.0: a
-// project that passed one got 60 s of refused probes and an environment that
-// never booted, with a healthy container beside it. A service reaches the
-// store at `http://<key>:9090`.
+// Build once per architecture/cache from pinned source: upstream's Docker Hub
+// image is amd64-only. Only the static native server ships in the runtime image.
+// Keep the Dockerfile independent of options so stores share the build cache.
+const S3_DOCKERFILE = `
+FROM golang:1.27.2-alpine@sha256:f92b6ef800e499660581efdabdf25d9d817a9d124eaf900924f0504e7e27e12d AS build
+RUN apk add --no-cache patch
+WORKDIR /src
+${["go.mod", "go.sum", "main.go", "metadata.patch"].map((file) => {
+    const data = readFileSync(new URL(`./s3-runtime/${file}`, import.meta.url)).toString("base64");
+    return `RUN printf '%s' '${data}' | base64 -d > ${file}`;
+}).join("\n")}
+RUN go mod vendor && patch -p1 < metadata.patch
+RUN CGO_ENABLED=0 go build -mod=vendor -trimpath -ldflags='-s -w' -o /s3-server .
+FROM scratch
+COPY --from=build /s3-server /s3-server
+COPY --from=build /src/vendor/github.com/johannesboyne/gofakes3/LICENSE /licenses/gofakes3
+COPY --from=build /src/vendor/github.com/ryszard/goskiplist/LICENSE /licenses/goskiplist
+EXPOSE 9090
+ENTRYPOINT ["/s3-server"]
+`;
+// Public endpoint stays fixed across backing-server changes.
 const S3_PORT = 9090;
 /**
  * A ready-to-use, S3-compatible object store (backed by
- * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * [GoFakeS3](https://github.com/johannesboyne/gofakes3)), with an instrumented S3
  * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
  *
  * ```ts
@@ -51,7 +61,7 @@ export function s3(opts = {}) {
     const secretAccessKey = opts.secretAccessKey ?? "s3";
     const region = opts.region ?? "us-east-1";
     return {
-        image: { type: "registry", reference: S3_IMAGE },
+        image: { type: "dockerfile", content: S3_DOCKERFILE },
         ports: [S3_PORT],
         ...(opts.env ? { env: opts.env } : {}),
         ...(opts.hosts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.129.0",
+  "version": "0.130.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/s3-docker.test.ts

@@ -0,0 +1,159 @@
+// Linux opt-in: creates and removes its own containers/network/image.
+// SPECTEST_TEST_S3_DOCKER=1 bun test src/components/s3-docker.test.ts
+// Add SPECTEST_TEST_S3_BASELINE=1 to run the same contract against S3Mock 5.1.0.
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { s3 } from "./s3.js";
+import { runContainerArgs } from "../harness/container-run.js";
+import { startRecording, stopRecording } from "../recorder.js";
+
+async function run(args: string[]) {
+  const child = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
+  const [exit, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  return { exit, stdout, stderr };
+}
+async function checked(args: string[]) {
+  const result = await run(args);
+  if (result.exit) throw new Error(`${args.join(" ")}: ${result.stderr}\n${result.stdout}`);
+  return result.stdout.trim();
+}
+async function ready(endpoint: string) {
+  const start = performance.now();
+  while (performance.now() - start < 60_000) {
+    try { if ((await fetch(endpoint, { signal: AbortSignal.timeout(500) })).ok) return performance.now() - start; } catch {}
+    await Bun.sleep(20);
+  }
+  throw new Error(`S3 not ready: ${endpoint}`);
+}
+
+const enabled = process.env.SPECTEST_TEST_S3_DOCKER === "1";
+const baseline = process.env.SPECTEST_TEST_S3_BASELINE === "1";
+test.skipIf(!enabled)("S3 preserves the public component and object-storage contract", async () => {
+  const root = mkdtempSync(join(tmpdir(), "spectest-s3-"));
+  const name = `spectest-s3-${process.pid}-${Date.now()}`;
+  const tag = baseline ? "adobe/s3mock:5.1.0" : name;
+  const definition = s3({ buckets: ["uploads", "assets"], hosts: ["files.test"], env: { CUSTOM_S3_ENV: "forwarded" } });
+  let proxy: ReturnType<typeof Bun.serve> | undefined;
+  try {
+    await checked(["openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1", "-subj", "/CN=localhost", "-addext", "subjectAltName=DNS:localhost", "-keyout", `${root}/key.pem`, "-out", `${root}/ca.pem`]);
+    if (baseline) await checked(["docker", "pull", tag]);
+    else {
+      writeFileSync(`${root}/Dockerfile`, definition.image.content);
+      await checked(["docker", "build", "-t", tag, root]);
+    }
+    await checked(["docker", "network", "create", name]);
+    // Exercise the real harness command, including its CA mounts, on scratch.
+    await checked(["docker", ...runContainerArgs({ svc: { ...definition, name }, tag, network: name, hostCacheName: "spectest-host", caPath: `${root}/ca.pem`, caBundle: `${root}/ca.pem` })]);
+    const ip = await checked(["docker", "inspect", "--format", "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}", name]);
+    const endpoint = `http://${ip}:9090`;
+    console.log(`${baseline ? "S3Mock" : "GoFakeS3"} ready after ${Math.round(await ready(endpoint))} ms of probing`);
+    const info = JSON.parse(await checked(["docker", "inspect", name]))[0];
+    expect(info.Config.Env).toContain("CUSTOM_S3_ENV=forwarded");
+    // No implicit bucket, even when the helper has a default bucket configured.
+    expect(await (await fetch(endpoint)).text()).not.toContain("<Bucket>");
+    expect((await fetch(`${endpoint}/missing/key`, { method: "PUT", body: "x" })).status).toBe(404);
+    await definition.setup!({ name: ip });
+    await definition.setup!({ name: ip }); // idempotent CreateBucket
+
+    const client = definition.helpers({ name: ip }).client;
+    startRecording();
+    await client.write("hello.txt", "hello world", { type: "text/plain" });
+    expect((await client.file("hello.txt").text()).unwrap()).toBe("hello world");
+    const events = stopRecording();
+    expect(events.filter(event => event.kind === "s3").map(event => event.op)).toEqual(["write", "read"]);
+    expect(events.some(event => event.error)).toBe(false);
+    expect((await client.stat("hello.txt")).unwrap().size).toBe(11);
+    const other = s3({ bucket: "assets", accessKeyId: "custom", secretAccessKey: "secret", region: "eu-west-1" }).helpers({ name: ip }).client;
+    await other.write("custom.txt", "custom credentials");
+    expect((await other.file("custom.txt").text()).unwrap()).toBe("custom credentials");
+    await client.write("override.txt", "per-call bucket", { bucket: "assets" });
+    expect((await other.file("override.txt").text()).unwrap()).toBe("per-call bucket");
+
+    // Host-preserving TLS termination: the store must remain path-style.
+    proxy = Bun.serve({ hostname: "127.0.0.1", port: 0, tls: { key: Bun.file(`${root}/key.pem`), cert: Bun.file(`${root}/ca.pem`) }, async fetch(request) {
+      const url = new URL(request.url);
+      return fetch(endpoint + url.pathname + url.search, { method: request.method, headers: request.headers, body: request.body, redirect: "manual" });
+    } });
+    for (const tls of [false, true]) {
+      const transport = (url: string) => tls ? url.replace(endpoint, `https://localhost:${proxy!.port}`) : url;
+      const options = { headers: { Host: "files.test", Origin: "https://app.test" }, ...(tls ? { tls: { ca: await Bun.file(`${root}/ca.pem`).text() } } : {}) };
+      const put = await fetch(transport(client.presign("presigned.txt", { method: "PUT" })), { ...options, method: "PUT", body: "presigned content" });
+      expect(put.status).toBe(200);
+      expect(put.headers.get("access-control-expose-headers")).toBe("*");
+      expect(await (await fetch(transport(client.presign("presigned.txt")), options)).text()).toBe("presigned content");
+      const preflight = await fetch(transport(`${endpoint}/uploads/presigned.txt`), { ...options, method: "OPTIONS", headers: { ...options.headers, "Access-Control-Request-Method": "PUT", "Access-Control-Request-Headers": "content-type,x-amz-meta-custom" } });
+      expect(preflight.status).toBe(200);
+      expect(preflight.headers.get("access-control-allow-origin")).toBe("https://app.test");
+      expect(preflight.headers.get("access-control-allow-headers")).toContain("x-amz-meta-custom");
+      expect(preflight.headers.get("access-control-allow-credentials")).toBe("true");
+    }
+    // Arbitrary signatures/dates must not turn into auth failures after restore.
+    const stale = await fetch(`${endpoint}/uploads/hello.txt`, { headers: { "x-amz-date": "20000101T000000Z", Authorization: "AWS4-HMAC-SHA256 invalid" } });
+    expect(stale.status).toBe(200);
+    const range = await fetch(`${endpoint}/uploads/hello.txt`, { headers: { Range: "bytes=1-4" } });
+    expect(range.status).toBe(206);
+    expect(await range.text()).toBe("ello");
+    const metadata = { "Content-Type": "text/plain", "Content-Disposition": "attachment; filename=hello.txt", "Cache-Control": "max-age=600", "Content-Language": "en", "Expires": "Wed, 28 Oct 2026 00:00:00 GMT", "x-amz-meta-custom": "retained" };
+    expect((await fetch(`${endpoint}/uploads/metadata.txt`, { method: "PUT", headers: metadata, body: "metadata" })).status).toBe(200);
+    const head = await fetch(`${endpoint}/uploads/metadata.txt`, { method: "HEAD" });
+    for (const [key, value] of Object.entries(metadata)) expect(head.headers.get(key)).toBe(value);
+    expect((await fetch(`${endpoint}/uploads/copied.txt`, { method: "PUT", headers: { "x-amz-copy-source": "/uploads/metadata.txt" } })).status).toBe(200);
+    expect((await client.file("copied.txt").text()).unwrap()).toBe("metadata");
+
+    // Exercise both Bun's multipart writer and explicit multi-part S3 requests.
+    const bytes = new Uint8Array(12 * 1024 * 1024).fill(65);
+    await client.write("large.bin", bytes);
+    expect((await client.file("large.bin").arrayBuffer()).unwrap()).toEqual(bytes.buffer);
+    const start = await fetch(`${endpoint}/uploads/manual.bin?uploads`, { method: "POST" });
+    expect(start.status).toBe(200);
+    const id = (await start.text()).match(/<UploadId>([^<]+)/)![1]!;
+    const etags: string[] = [];
+    for (const [i, size] of [[1, 5 * 1024 * 1024], [2, 1234]]) {
+      const part = await fetch(`${endpoint}/uploads/manual.bin?partNumber=${i}&uploadId=${encodeURIComponent(id)}`, { method: "PUT", body: new Uint8Array(size).fill(i) });
+      expect(part.status).toBe(200);
+      etags.push(part.headers.get("etag")!);
+    }
+    const complete = await fetch(`${endpoint}/uploads/manual.bin?uploadId=${encodeURIComponent(id)}`, { method: "POST", body: `<CompleteMultipartUpload>${etags.map((etag, i) => `<Part><PartNumber>${i + 1}</PartNumber><ETag>${etag}</ETag></Part>`).join("")}</CompleteMultipartUpload>` });
+    expect(complete.status).toBe(200);
+    expect((await client.stat("manual.bin")).unwrap().size).toBe(5 * 1024 * 1024 + 1234);
+    await client.write("pages/one", "one");
+    await client.write("pages/two", "two");
+    const page = (await client.list({ prefix: "pages/", maxKeys: 1 })).unwrap();
+    expect(page.contents?.map(item => item.key)).toEqual(["pages/one"]);
+    expect(page.isTruncated).toBe(true);
+    const next = (await client.list({ prefix: "pages/", maxKeys: 1, continuationToken: page.nextContinuationToken })).unwrap();
+    expect(next.contents?.map(item => item.key)).toEqual(["pages/two"]);
+    await client.delete("pages/one");
+    expect((await client.exists("pages/one")).unwrap()).toBe(false);
+
+    // Versioning stays opt-in and old versions remain readable.
+    expect((await fetch(`${endpoint}/assets?versioning`, { method: "PUT", body: '<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Status>Enabled</Status></VersioningConfiguration>' })).status).toBe(200);
+    const first = await fetch(`${endpoint}/assets/versioned.txt`, { method: "PUT", body: "first" });
+    const version = first.headers.get("x-amz-version-id");
+    expect(version).toBeTruthy();
+    expect((await fetch(`${endpoint}/assets/versioned.txt`, { method: "PUT", body: "second" })).status).toBe(200);
+    expect(await (await fetch(`${endpoint}/assets/versioned.txt?versionId=${encodeURIComponent(version!)}`)).text()).toBe("first");
+    expect((await other.file("versioned.txt").text()).unwrap()).toBe("second");
+
+    await checked(["docker", "restart", name]);
+    await ready(endpoint);
+    // A process restart is different from a VM restore: the original S3Mock
+    // chose a fresh temporary store on every process start.
+    expect(await (await fetch(endpoint)).text()).not.toContain("<Bucket>");
+    await definition.setup!({ name: ip });
+    await client.write("after-restart.txt", "fresh store");
+    expect((await client.file("after-restart.txt").text()).unwrap()).toBe("fresh store");
+  } catch (error) {
+    console.error(await run(["docker", "logs", "--tail", "40", name]));
+    throw error;
+  } finally {
+    stopRecording();
+    proxy?.stop(true);
+    await run(["docker", "rm", "-f", "-v", name]);
+    await run(["docker", "network", "rm", name]);
+    if (!baseline) await run(["docker", "image", "rm", tag]);
+    rmSync(root, { recursive: true, force: true });
+  }
+}, 600_000);

package/src/components/s3-runtime/README.md

@@ -0,0 +1,33 @@
+# Native S3 component runtime
+
+GoFakeS3 is pinned by `go.mod`/`go.sum`. `s3.ts` embeds these assets into a constant
+multi-stage Dockerfile, builds for the worker's native architecture, and ships
+only the static binary and dependency licenses. The Go builder is pinned to a
+multi-architecture digest. No project files or options enter the image build.
+
+The entrypoint retains the component's port 9090, path-style addressing, no
+automatic buckets, no signature/date validation, and permissive browser CORS.
+The memory backend supports pagination and versioning. Full VM snapshots clone
+its buckets, versions and pending multipart uploads; restarting the process
+starts empty, matching S3Mock's default temporary store.
+
+`metadata.patch` preserves Cache-Control, Content-Language and Expires on object
+uploads, multipart initiation and copies. Upstream currently drops these headers
+in `metadataHeaders`. The patch applies to the vendored, checksum-verified module;
+a failed patch stops the build. Recheck it when changing the upstream pin.
+
+From `sdk`, run the real-image contract on a Linux Docker host:
+
+```
+SPECTEST_TEST_S3_DOCKER=1 bun test src/components/s3-docker.test.ts
+SPECTEST_TEST_S3_DOCKER=1 SPECTEST_TEST_S3_BASELINE=1 bun test src/components/s3-docker.test.ts
+bun test src/components/s3.test.ts src/components/internal-fetch.test.ts
+bun run build
+```
+
+The baseline uses S3Mock 5.1.0. The contract covers helpers and recording, setup,
+credentials, HTTPS with preserved Host, browser CORS, unsigned/stale signatures,
+metadata, copy/range requests, multipart, paginated listing, versioning, and
+fresh-process lifecycle. It does not prove every S3 API is interchangeable:
+GoFakeS3 lacks some S3Mock features, including tagging, lifecycle and retention.
+Java/Spring/S3Mock-specific environment settings are no longer interpreted.

package/src/components/s3-runtime/go.mod

@@ -0,0 +1,11 @@
+module spectest-s3
+
+go 1.24
+
+require github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153
+
+require (
+	github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46 // indirect
+	go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d // indirect
+	golang.org/x/tools v0.8.0 // indirect
+)

package/src/components/s3-runtime/go.sum

@@ -0,0 +1,54 @@
+github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
+github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.67 h1:9KxtdcIA/5xPNQyZRgUSpYOE6j9Bc4+D7nZua0KGYOM=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.67/go.mod h1:p3C44m+cfnbv763s52gCqrjaqyPikj9Sg47kUVaNZQQ=
+github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.75 h1:S61/E3N01oral6B3y9hZ2E1iFDqCZPPOBoBQretCnBI=
+github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.75/go.mod h1:bDMQbkI1vJbNjnvJYpPTSNYBkI/VIv18ngWb/K84tkk=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22 h1:rWyie/PxDRIdhNf4DzRk0lvjVOqFJuNnO8WwaIRVxzQ=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22/go.mod h1:zd/JsJ4P7oGfUhXn1VyLqaRZwPmZwg44Jf2dS84Dm3Y=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13 h1:JRaIgADQS/U6uXDqlPiefP32yXTda7Kqfx+LgspooZM=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13/go.mod h1:CEuVn5WqOMilYl+tbccq8+N2ieCy0gVn3OtRb0vBNNM=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21 h1:ZlvrNcHSFFWURB8avufQq9gFsheUgjVD9536obIknfM=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21/go.mod h1:cv3TNhVrssKR0O/xxLJVRfd2oazSnZnkUeTf6ctUwfQ=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3 h1:HwxWTbTrIHm5qY+CAEur0s/figc3qwvLWsNkF4RPToo=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3/go.mod h1:uoA43SdFwacedBfSgfFSjjCvYe8aYBS7EnU5GZ/YKMM=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/cevatbarisyilmaz/ara v0.0.4 h1:SGH10hXpBJhhTlObuZzTuFn1rrdmjQImITXnZVPSodc=
+github.com/cevatbarisyilmaz/ara v0.0.4/go.mod h1:BfFOxnUd6Mj6xmcvRxHN3Sr21Z1T3U2MYkYOmoQe4Ts=
+github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153 h1:ZaLBZJfUnKBlrPu0AX0T/i1N9BNU54j8sl9mCLzmpI0=
+github.com/johannesboyne/gofakes3 v1.2.1-0.20261011201219-0016ef2bf153/go.mod h1:UHhRZRod9rENGFrUWTYnQHZqlNgSmjOq8DaD/ATQYRM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46 h1:GHRpF1pTW19a8tTFrMLUcfWwyC0pnifVo2ClaLq+hP8=
+github.com/ryszard/goskiplist v0.0.0-20150312221310-2dfbae5fcf46/go.mod h1:uAQ5PCi+MFsC7HjREoAz1BU+Mq60+05gifQSsHSDG/8=
+github.com/spf13/afero v1.2.1 h1:qgMbHoJbPbw579P+1zVY+6n4nIFuIchaIjzZ/I/Yq8M=
+github.com/spf13/afero v1.2.1/go.mod h1:9ZxEEn6pIJ8Rxe320qSDBk6AsU0r9pR7Q4OcevTdifk=
+github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+go.etcd.io/bbolt v1.3.5 h1:XAzx9gjCb0Rxj7EoqcClPD1d5ZBxZJk0jbuoPHenBt0=
+go.etcd.io/bbolt v1.3.5/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
+go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d h1:Ns9kd1Rwzw7t0BR8XMphenji4SmIoNZPn8zhYmaVKP8=
+go.shabbyrobe.org/gocovmerge v0.0.0-20230507111327-fa4f82cfbf4d/go.mod h1:92Uoe3l++MlthCm+koNi0tcUCX3anayogF0Pa/sp24k=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.9.0 h1:2sjJmO8cDvYveuX97RDLsxlyUxLl+GHoLxBiRdHllBE=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
+golang.org/x/tools v0.8.0 h1:vSDcovVPld282ceKgDimkRSC8kpaH1dgyc9UMzlt84Y=
+golang.org/x/tools v0.8.0/go.mod h1:JxBZ99ISMI5ViVkT1tr6tdNmXeTrcpVSD3vZ1RsRdN4=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce h1:xcEWjVhvbDy+nHP67nPDDpbYrY+ILlfndk4bRioVHaU=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce/go.mod h1:yeKp02qBN3iKW1OzL3MGk2IdtZzaj7SFntXj72NppTA=
+gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

package/src/components/s3-runtime/main.go

@@ -0,0 +1,77 @@
+// The component's native entrypoint. Keep its defaults compatible with S3Mock;
+// the upstream CLI enforces clock skew and has different browser CORS defaults.
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/johannesboyne/gofakes3"
+	"github.com/johannesboyne/gofakes3/backend/s3mem"
+)
+
+func main() {
+	// VM snapshots include RAM: buckets, versions and in-flight multipart state
+	// fork together. A fresh process starts empty, as S3Mock did by default.
+	// Unlike the Bolt backend, s3mem also supports bucket versioning.
+	backend := s3mem.New()
+	server := gofakes3.New(backend,
+		gofakes3.WithTimeSkewLimit(0), // S3Mock accepts arbitrary/expired signatures.
+		gofakes3.WithHostBucket(false),
+		gofakes3.WithAutoBucket(false),
+		gofakes3.WithLogger(gofakes3.GlobalLog()),
+	).Server()
+	log.Fatal(http.ListenAndServe(":9090", cors(server)))
+}
+
+// Preserve S3Mock's permissive browser uploads, including arbitrary metadata
+// headers. GoFakeS3's default allow-list rejects custom x-amz-meta-* headers and
+// only exposes ETag on preflights, hiding it from actual browser responses.
+func cors(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		origin := r.Header.Get("Origin")
+		w.Header().Add("Vary", "Origin")
+		w.Header().Add("Vary", "Access-Control-Request-Method")
+		w.Header().Add("Vary", "Access-Control-Request-Headers")
+		if origin != "" && r.Method == "OPTIONS" && r.Header.Get("Access-Control-Request-Method") != "" {
+			w.Header().Set("Access-Control-Allow-Origin", origin)
+			w.Header().Set("Access-Control-Allow-Credentials", "true")
+			w.Header().Set("Access-Control-Allow-Methods", r.Header.Get("Access-Control-Request-Method"))
+			w.Header().Set("Access-Control-Allow-Headers", r.Header.Get("Access-Control-Request-Headers"))
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		writer := &corsWriter{ResponseWriter: w, hasOrigin: origin != ""}
+		next.ServeHTTP(writer, r)
+		if !writer.written {
+			writer.WriteHeader(http.StatusOK)
+		}
+	})
+}
+
+type corsWriter struct {
+	http.ResponseWriter
+	hasOrigin bool
+	written   bool
+}
+
+func (w *corsWriter) WriteHeader(status int) {
+	if w.written {
+		return
+	}
+	w.written = true
+	if w.hasOrigin {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Expose-Headers", "*")
+	} else {
+		w.Header().Del("Access-Control-Allow-Origin")
+	}
+	w.ResponseWriter.WriteHeader(status)
+}
+
+func (w *corsWriter) Write(body []byte) (int, error) {
+	if !w.written {
+		w.WriteHeader(http.StatusOK)
+	}
+	return w.ResponseWriter.Write(body)
+}

package/src/components/s3-runtime/metadata.patch

@@ -0,0 +1,12 @@
+--- a/vendor/github.com/johannesboyne/gofakes3/gofakes3.go
++++ b/vendor/github.com/johannesboyne/gofakes3/gofakes3.go
+@@ -1191,6 +1191,9 @@
+ 	for hk, hv := range headers {
+ 		if strings.HasPrefix(hk, "X-Amz-") ||
+ 			hk == "Content-Type" ||
++			hk == "Cache-Control" ||
++			hk == "Content-Language" ||
++			hk == "Expires" ||
+ 			hk == "Content-Disposition" ||
+ 			hk == "Content-Encoding" {
+ 			meta[hk] = hv[0]

package/src/components/s3.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from "bun:test";
+import { s3 } from "./s3.js";
+
+function presign(options: Parameters<typeof s3>[0], bucket?: string) {
+  return new URL(s3(options).helpers({ name: "storage" }).client.presign("hello.txt", bucket ? { bucket } : {}));
+}
+
+test("S3 keeps its endpoint, readiness, credential and region defaults", () => {
+  const service = s3();
+  expect(service.ports).toEqual([9090]);
+  expect(service.readyCheck).toEqual({ type: "http", port: 9090, path: "/", timeoutSecs: 60 });
+  expect(service.setup).toBeUndefined();
+  expect(service.env).toBeUndefined();
+  expect(service.tls).toBeUndefined();
+  const url = presign({}, "uploads");
+  expect(url.origin).toBe("http://storage:9090");
+  expect(url.pathname).toBe("/uploads/hello.txt");
+  expect(url.searchParams.get("X-Amz-Credential")).toMatch(/^s3\/\d+\/us-east-1\/s3\/aws4_request$/);
+});
+
+test("S3 keeps bucket precedence, caller credentials, region, env and TLS routes", () => {
+  const options = { buckets: ["uploads", "assets"], bucket: "assets", accessKeyId: "custom", secretAccessKey: "secret", region: "eu-west-1", hosts: ["files.test", "storage.test"], env: { CUSTOM: "value" } };
+  expect(presign({ buckets: options.buckets }).pathname).toBe("/uploads/hello.txt");
+  const url = presign(options);
+  expect(url.pathname).toBe("/assets/hello.txt");
+  expect(url.searchParams.get("X-Amz-Credential")).toMatch(/^custom\/\d+\/eu-west-1\/s3\/aws4_request$/);
+  expect(presign(options, "override").pathname).toBe("/override/hello.txt");
+  expect(presign({ ...options, secretAccessKey: "different" }).searchParams.get("X-Amz-Signature")).not.toBe(url.searchParams.get("X-Amz-Signature"));
+  expect(s3(options).env).toEqual(options.env);
+  expect(s3(options).tls).toEqual(options.hosts.map(hostname => ({ hostname, port: 9090 })));
+  // Selecting a helper default has never implicitly created that bucket.
+  expect(s3({ bucket: "not-created" }).setup).toBeUndefined();
+  expect(s3({ buckets: [] }).setup).toBeUndefined();
+  // Options must not create per-project copies of the same native image.
+  expect(s3(options).image).toEqual(s3().image);
+});

package/src/components/s3.ts

@@ -1,11 +1,11 @@
+import { readFileSync } from "node:fs";
 import { rawFetch } from "../harness/raw-fetch.js";
 import type { ServiceDefinition } from "../index.js";
 import { S3Client, type S3ClientLike } from "../s3.js";
 
 export interface S3Options {
   /**
-   * Buckets to create on first boot. The backing server's own `initialBuckets`
-   * env is unreliable across versions, so the component creates them in `setup`
+   * Buckets to create on first boot. The component creates them in `setup`
    * (a plain CreateBucket `PUT`) — captured into the warm snapshot, never
    * re-run on warm starts/forks.
    */
@@ -45,24 +45,33 @@ export interface S3Helpers {
   client: S3ClientLike;
 }
 
-// Backing image, pinned internally (not user-configurable). adobe/s3mock 5.1.0
-// is the current release; avoid exactly 5.0.0, which crashed at startup on
-// Java 25 (`NoClassDefFoundError: KotlinBuiltIns$2`) — fixed in 5.1.0.
-const S3_IMAGE = "adobe/s3mock:5.1.0";
+// Build once per architecture/cache from pinned source: upstream's Docker Hub
+// image is amd64-only. Only the static native server ships in the runtime image.
+// Keep the Dockerfile independent of options so stores share the build cache.
+const S3_DOCKERFILE = `
+FROM golang:1.27.2-alpine@sha256:f92b6ef800e499660581efdabdf25d9d817a9d124eaf900924f0504e7e27e12d AS build
+RUN apk add --no-cache patch
+WORKDIR /src
+${["go.mod", "go.sum", "main.go", "metadata.patch"].map((file) => {
+  const data = readFileSync(new URL(`./s3-runtime/${file}`, import.meta.url)).toString("base64");
+  return `RUN printf '%s' '${data}' | base64 -d > ${file}`;
+}).join("\n")}
+RUN go mod vendor && patch -p1 < metadata.patch
+RUN CGO_ENABLED=0 go build -mod=vendor -trimpath -ldflags='-s -w' -o /s3-server .
+FROM scratch
+COPY --from=build /s3-server /s3-server
+COPY --from=build /src/vendor/github.com/johannesboyne/gofakes3/LICENSE /licenses/gofakes3
+COPY --from=build /src/vendor/github.com/ryszard/goskiplist/LICENSE /licenses/goskiplist
+EXPOSE 9090
+ENTRYPOINT ["/s3-server"]
+`;
 
-// Port the store listens on, fixed like the image and deliberately NOT an
-// option. The backing server's HTTP port is baked into the image, and nothing
-// the component returns can move it — so a `port` option could only relabel
-// the ready check, the declared ports and the client endpoint while the
-// container kept listening here. That is exactly what it did until 0.78.0: a
-// project that passed one got 60 s of refused probes and an environment that
-// never booted, with a healthy container beside it. A service reaches the
-// store at `http://<key>:9090`.
+// Public endpoint stays fixed across backing-server changes.
 const S3_PORT = 9090;
 
 /**
  * A ready-to-use, S3-compatible object store (backed by
- * [`adobe/s3mock`](https://github.com/adobe/S3Mock)), with an instrumented S3
+ * [GoFakeS3](https://github.com/johannesboyne/gofakes3)), with an instrumented S3
  * client on `ctx.svc.<key>.client`. Drop into `environment.services`:
  *
  * ```ts
@@ -99,7 +108,7 @@ export function s3(opts: S3Options = {}) {
   const region = opts.region ?? "us-east-1";
 
   return {
-    image: { type: "registry", reference: S3_IMAGE },
+    image: { type: "dockerfile", content: S3_DOCKERFILE },
     ports: [S3_PORT],
     ...(opts.env ? { env: opts.env } : {}),
     ...(opts.hosts